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

apps/agent/doc/usage.md

@@ -0,0 +1,61 @@
+# Usage and Examples
+
+Running locally (development)
+
+1. Build the agent (from repository root):
+
+   ```sh
+   cargo build -p agent
+   ```
+
+2. Run the agent with defaults (socket in current directory):
+
+   ```sh
+   ./target/debug/yanpm-agent
+   ```
+
+3. Run with explicit socket and nginx config directory:
+
+   ```sh
+   ./target/debug/yanpm-agent --sock /run/yanpm/yanpm-agent.sock --nginx-config-dir /etc/nginx/conf.d
+   ```
+
+HTTP over unix-socket examples (using `socat` / `curl` helper)
+
+If you want to call the API from the shell, you can use `socat` to convert the unix socket to an HTTP stream, or use tools that support unix sockets directly (e.g. `curl --unix-socket`). Examples below use `curl --unix-socket`.
+
+Validate a fragment by name and timestamp:
+
+```sh
+curl --unix-socket ./yanpm-agent.sock -X POST http://localhost/validate \
+  -H 'Content-Type: application/json' \
+  -d '{"config_name":"example","timestamp":1234567890}'
+```
+
+Validate and reload (returns `rc` and `ro`):
+
+```sh
+curl --unix-socket ./yanpm-agent.sock -X POST http://localhost/validate_and_reload \
+  -H 'Content-Type: application/json' \
+  -d '{"config_name":"example","timestamp":1234567890}'
+```
+
+Write a fragment (create or update):
+
+```sh
+curl --unix-socket ./yanpm-agent.sock -X POST http://localhost/write_config \
+  -H 'Content-Type: application/json' \
+  -d '{"config_name":"example","timestamp":1234567890,"content":"server { listen 80; server_name example.local; }"}'
+```
+
+Status endpoint (health)
+
+```sh
+curl --unix-socket ./yanpm-agent.sock http://localhost/status
+```
+
+Notes
+
+- Use the `config_name` and `timestamp` fields consistently: `timestamp` is typically a monotonic update ID from the caller ensuring unique file names.
+- When running in containers, mount the host nginx config dir if you want the agent to write directly to host nginx configuration.
+- The repository includes a runtime Docker image built by `apps/agent/Dockerfile` which bundles `nginx` and the `yanpm-agent` binary (via s6-overlay). Use that image when you want nginx and the agent colocated (the agent is intended as a runtime companion to `apps/api`).