docs: Add documentation for FlatRun Agent

docs.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://raw.githubusercontent.com/whilesmart/docs-kit/main/schema/docs.schema.json",
+  "name": "FlatRun Agent",
+  "description": "Lightweight Go backend for flat-file Docker Compose orchestration with a REST API, container lifecycle management, and plugin architecture",
+  "icon": "server",
+  "category": {
+    "language": "go",
+    "framework": "app"
+  },
+  "sidebar": [
+    {
+      "title": "Overview",
+      "path": "docs/overview.md"
+    },
+    {
+      "title": "Installation",
+      "path": "docs/installation.md"
+    },
+    {
+      "title": "Configuration",
+      "path": "docs/configuration.md"
+    },
+    {
+      "title": "API Reference",
+      "path": "docs/api-reference.md"
+    },
+    {
+      "title": "OpenAPI Spec",
+      "path": "docs/flatrun-agent-openapi.yaml"
+    },
+    {
+      "title": "Plugin Architecture",
+      "path": "docs/plugin-architecture.md"
+    },
+    {
+      "title": "Security",
+      "path": "docs/security.md"
+    }
+  ],
+  "openapi": "docs/flatrun-agent-openapi.yaml"
+}

docs/api-reference.md

@@ -0,0 +1,43 @@
+## API Reference
+
+### Authentication
+
+| Method | Endpoint | Description |
+|---|---|---|
+| POST | `/api/auth/login` | Login with API key |
+| GET | `/api/auth/validate` | Validate JWT token |
+| GET | `/api/auth/status` | Check auth status |
+
+### Deployments
+
+| Method | Endpoint | Description |
+|---|---|---|
+| GET | `/api/deployments` | List all deployments |
+| POST | `/api/deployments` | Create new deployment |
+| GET | `/api/deployments/:name` | Get deployment details |
+| DELETE | `/api/deployments/:name` | Delete deployment |
+| POST | `/api/deployments/:name/start` | Start deployment |
+| POST | `/api/deployments/:name/stop` | Stop deployment |
+| POST | `/api/deployments/:name/restart` | Restart deployment |
+| GET | `/api/deployments/:name/logs` | Get deployment logs |
+
+### Docker Resources
+
+| Method | Endpoint | Description |
+|---|---|---|
+| GET | `/api/containers` | List containers |
+| GET | `/api/images` | List images |
+| GET | `/api/volumes` | List volumes |
+| GET | `/api/networks` | List networks |
+| POST | `/api/networks` | Create network |
+| DELETE | `/api/networks/:name` | Delete network |
+
+### Other
+
+| Method | Endpoint | Description |
+|---|---|---|
+| GET | `/api/health` | Health check |
+| GET | `/api/stats` | System statistics |
+| GET | `/api/certificates` | List SSL certificates |
+| GET | `/api/templates` | List Quick App templates |
+| GET | `/api/plugins` | List installed plugins |

docs/configuration.md

@@ -0,0 +1,57 @@
+## Configuration
+
+Copy the example configuration and edit it:
+
+```bash
+cp config.example.yml config.yml
+```
+
+### Reference
+
+```yaml
+deployments_path: /home/user/deployments
+docker_socket: unix:///var/run/docker.sock
+
+api:
+  host: 0.0.0.0
+  port: 8090
+  enable_cors: true
+  allowed_origins:
+    - http://localhost:5173
+    - http://localhost:3000
+
+auth:
+  enabled: true
+  api_keys:
+    - "your-secure-api-key-here"
+  jwt_secret: "REPLACE_WITH_SECURE_RANDOM_STRING"  # generate via: openssl rand -base64 32
+
+nginx:
+  container_name: nginx
+  config_path: /deployments/nginx/conf.d
+  reload_command: nginx -s reload
+
+certbot:
+  container_name: certbot
+  email: your-email@example.com
+  staging: true
+
+logging:
+  level: info
+  format: json
+
+health:
+  check_interval: 30s
+  metrics_retention: 24h
+```
+
+### Key Options
+
+| Option | Description |
+|---|---|
+| `deployments_path` | Directory containing docker-compose deployments |
+| `api.port` | API server port (default: 8090) |
+| `auth.api_keys` | Valid API keys for authentication |
+| `auth.jwt_secret` | Secret for signing JWT tokens |
+| `logging.level` | Log level: debug, info, warn, error |
+| `health.check_interval` | Health check frequency |