feat: add comprehensive documentation for yanpm-agent, including API reference, configuration, deployment, usage examples, and troubleshooting

apps/agent/doc/api.md

@@ -0,0 +1,68 @@
+# HTTP API Reference
+
+Base: HTTP over a unix-domain socket. Example using curl: `curl --unix-socket /path/to/socket -X POST http://localhost/<path>`
+
+1) GET /status
+
+   - Response: 200 OK
+   - Body: JSON `{ "ok": true }`
+
+2) POST /validate
+
+   - Request JSON:
+
+   ```json
+   {
+     "config_name": "example",
+     "timestamp": 1234567890
+   }
+   ```
+
+   - Behavior: validates the fragment file named by `config_name` and `timestamp` under the agent's internal subdirectory inside the configured nginx config directory. Delegates to `ValidateCommand::validate`.
+   - Success: 200 OK, body is `[rc, output]` tuple serialized as JSON (actual shape is `(i32, String)` returned from the command; examine responses for exact formatting).
+   - Error cases:
+     - 400 Bad Request: invalid or malformed JSON
+     - 500 Internal Server Error: validation error or missing fragment file
+
+   - Request JSON:
+
+   ```json
+   {
+      "config_name": "example",
+      "timestamp": 1234567890
+   }
+   ```
+
+   - Behavior: validates the fragment file named by `config_name` and `timestamp` under the agent's internal subdirectory inside the configured nginx config directory. Delegates to `ValidateCommand::validate`.
+   - Success: 200 OK, body is a JSON array `[rc, output]` where `rc` is the integer return code and `output` is the combined stdout/stderr string from the validation command (the command returns an `(i32, String)` tuple).
+   - Error cases:
+      - 400 Bad Request: invalid or malformed JSON
+      - 500 Internal Server Error: validation error or missing fragment file
+
+3) POST /validate_and_reload
+
+   - Request JSON same as `/validate`.
+   - Behavior: runs validation and, on success, attempts to reload nginx. Returns an object with `rc` and `ro` (return code and combined stdout/stderr output).
+   - Success: 200 OK with body: `{ "rc": <int>, "ro": "<output>" }`
+   - Errors: 400 for malformed JSON, 500 if the validate-and-reload command fails (body presents error text).
+
+4) POST /write_config
+
+   - Request JSON:
+
+   ```json
+   {
+     "config_name": "example",
+     "timestamp": 1234567890,
+     "content": "server { ... }"
+   }
+   ```
+
+   - Behavior: writes the provided `content` into an agent-managed fragment file named from `config_name` and `timestamp` in the internal subdirectory under `nginx_config_dir`.
+   - Success: 200 OK with empty body
+   - Error: 400 for malformed JSON, 500 if writing the file fails
+
+Notes
+
+- The agent expects callers to choose a `config_name` and `timestamp` that together form a unique filename. The concrete filename encoding is performed by `commands::run::to_file_name` in source.
+- On validation failures the returned output often contains the full `nginx -t` output; inspect `ro` or the returned JSON error messages.