feat: More documentation entries

content/docs/advanced/cli.mdx

@@ -0,0 +1,122 @@
+---
+title: CLI Reference
+description: Hub command-line interface for backup, restore, and key management
+---
+
+The Hub binary includes a CLI for administrative tasks that cannot be performed through the web UI. Run any command with `--help` to see all available options.
+
+When using Docker, prefix commands with `docker compose exec hub /app/hub`:
+
+```bash
+docker compose exec hub /app/hub <command>
+```
+
+<Callout>
+	Commands that ask for a yes/no confirmation (`import`, `key rotate`) don't require `-it`. Without
+	an attached terminal, the prompt is treated as "no" and the command safely aborts. For scripted or
+	non-interactive runs, pass `--yes`/`-y` explicitly instead of relying on this behavior.
+</Callout>
+
+## export
+
+Creates a consistent backup of the Hub database. The export uses SQLite's `VACUUM INTO` and is safe to run while the Hub is running.
+
+```bash
+hub export [--output <path>]
+```
+
+| Flag             | Default                         | Description                     |
+| ---------------- | ------------------------------- | ------------------------------- |
+| `-o`, `--output` | `hub-export-YYYYMMDD-HHMMSS.db` | Output path for the backup file |
+
+**With Docker:**
+
+```bash
+docker compose exec hub /app/hub export
+```
+
+The file is created inside the container under `/app/data/`. Copy it out of the container to include it in your backup strategy:
+
+```bash
+docker compose cp hub:/app/data/hub-export-*.db ./backups/
+```
+
+## import
+
+Restores a database from a backup file. The existing database is copied to a rollback file before the restore, so you can recover if something goes wrong.
+
+<Callout type="warn">
+	The Hub server must be **stopped** before running import. All existing data is overridden by the
+	backup.
+</Callout>
+
+```bash
+hub import <file> [--yes]
+```
+
+| Argument / Flag | Description                   |
+| --------------- | ----------------------------- |
+| `<file>`        | Path to the backup `.db` file |
+| `-y`, `--yes`   | Skip the confirmation prompt  |
+
+**With Docker:**
+
+```bash
+# Copy the backup into the container
+docker compose cp ./backups/hub-export-20240101-120000.db hub:/app/data/
+
+# Stop the hub
+docker compose stop hub
+
+# Run import
+docker compose run --rm hub /app/hub import data/hub-export-20240101-120000.db
+
+# Restart the hub
+docker compose up -d hub
+```
+
+## key rotate
+
+Re-encrypts all sensitive database fields with a new `APP_SECRET`. Use this when you need to rotate your encryption key.
+
+<Callout type="warn">
+	The Hub server must be **stopped** before rotating the key. Create a database backup first. If the
+	rotation fails, restore the backup, keep the old `APP_SECRET`, and retry.
+</Callout>
+
+```bash
+hub key rotate [--old-secret <secret>] [--yes]
+```
+
+| Flag           | Description                                                                   |
+| -------------- | ----------------------------------------------------------------------------- |
+| `--old-secret` | Previous `APP_SECRET` value. Can also be set via the `OLD_APP_SECRET` env var |
+| `-y`, `--yes`  | Skip the confirmation prompt                                                  |
+
+**With Docker:**
+
+```bash
+# 1. Create a backup
+docker compose exec hub /app/hub export
+
+# 2. Stop the hub
+docker compose stop hub
+
+# 3. Rotate the key (set the NEW APP_SECRET in .env first)
+docker compose run --rm \
+  -e OLD_APP_SECRET=<old-secret> \
+  hub /app/hub key rotate --yes
+
+# 4. Restart the hub with the new APP_SECRET
+docker compose up -d hub
+```
+
+After a successful rotation, all agent tokens and user sessions signed with the old secret are invalidated. Users need to log in again and agents need their tokens re-issued (or simply reconnect. The agent will re-authenticate automatically if the hub is reachable).
+
+## reset-password
+
+Resets a user's password and forces them to change it on the next login. See [Account Recovery](/docs/troubleshooting/account-recovery) for full details.
+
+```bash
+hub reset-password <user-id-or-email>
+```

content/docs/architecture/agents.mdx

@@ -0,0 +1,74 @@
+---
+title: Agents
+description: Managing agents and connecting them to the Hub
+---
+
+An **Agent** is a lightweight service that runs on the target host where your Docker containers are deployed. It connects to the Hub via WebSocket, receives deployment instructions, and reports status back. You can run multiple agents. One agent per environment, server, or cluster.
+
+## Creating an Agent
+
+Before deploying the Agent binary, you need to register it in the Hub to obtain an authentication token.
+
+1. Navigate to the **Agents** page in the OrcaCD UI.
+2. Click **Add Agent** and give it a name (e.g., `production`, `staging`).
+3. Copy the generated `AUTH_TOKEN` (only shown once).
+
+![Create Agent](/assets/docs/create-agent.png?url)
+
+## Deploying an Agent
+
+### Same Host as the Hub
+
+The default `docker-compose.yml` includes both Hub and Agent. If you are running both on the same machine, just set the `AUTH_TOKEN` in your `.env` and restart:
+
+```bash
+docker compose up -d
+```
+
+### Remote Host
+
+To deploy an Agent on a separate server, copy only the Agent service definition to that machine. See [installation](/docs/setup/installation) for instructions on how to set up the Agent service.
+
+The Agent will connect to the Hub. Once connected, its status in the Hub UI changes to **Online**.
+
+<Callout>
+	The Agent needs access to the Docker socket (`/var/run/docker.sock`) to manage containers on the
+	host.
+</Callout>
+
+## Multiple Agents
+
+You can register as many agents as you need. For example, one per environment:
+
+| Agent name   | Purpose                       |
+| ------------ | ----------------------------- |
+| `production` | Deploys to the production VPS |
+| `staging`    | Deploys to a staging server   |
+| `dev`        | Local development environment |
+
+Each Application in OrcaCD is assigned to exactly one Agent. You can split workloads across agents freely.
+
+## Rotating an Agent Token
+
+If a token is compromised or needs to be rotated, navigate to the Agent in the UI, open the options menu, and select **Rotate Token**. A new token is generated immediately and the old token becomes invalid.
+
+Update the `AUTH_TOKEN` in the Agent's `.env` and restart it:
+
+```bash
+docker compose up -d
+```
+
+You can also rotate tokens via the API:
+
+```bash
+POST /api/v1/agents/:id/rotate-token
+```
+
+## Agent Status
+
+| Status    | Meaning                                             |
+| --------- | --------------------------------------------------- |
+| `online`  | Agent is connected and ready to receive deployments |
+| `offline` | Agent has disconnected or has not yet connected     |
+
+If an Agent is offline, deployment dispatch fails immediately and the application is marked out-of-sync with an error. Deployments are not queued or retried automatically. Trigger the deployment again once the Agent is back online.

content/docs/architecture/applications.mdx

@@ -0,0 +1,89 @@
+---
+title: Applications
+description: Creating and managing applications in OrcaCD
+---
+
+An **Application** in OrcaCD represents a Docker Compose deployment. It links a repository (and a specific branch and file path) to an Agent, which runs the actual containers.
+
+## Creating an Application
+
+1. Navigate to the **Applications** page and click **Add Application**.
+2. Fill in the required fields:
+
+   | Field          | Description                                                                                    |
+   | -------------- | ---------------------------------------------------------------------------------------------- |
+   | **Name**       | Display name for the application                                                               |
+   | **Repository** | The repository containing the Compose file                                                     |
+   | **Branch**     | The branch to track (e.g., `main`, `production`)                                               |
+   | **Path**       | Path to the `docker-compose.yml` inside the repository (e.g., `apps/myapp/docker-compose.yml`) |
+   | **Agent**      | The agent that will execute the deployment                                                     |
+
+3. Click **Create**.
+
+OrcaCD will immediately sync the repository and deploy the Compose file to the selected Agent.
+
+## Application Status
+
+Each application shows two status indicators:
+
+### Sync Status
+
+| Status        | Meaning                                              |
+| ------------- | ---------------------------------------------------- |
+| `Synced`      | Deployed commit matches the latest repository commit |
+| `Out Of Sync` | A new commit exists that has not been deployed yet   |
+| `Syncing`     | A deployment is currently in progress                |
+| `Unknown`     | No deployment has been triggered yet                 |
+
+### Health Status
+
+| Status      | Meaning                                              |
+| ----------- | ---------------------------------------------------- |
+| `Healthy`   | All containers from the Compose file are running     |
+| `Unhealthy` | One or more containers are stopped or in a bad state |
+| `Unknown`   | Health has not been checked yet                      |
+
+## Triggering a Deployment
+
+OrcaCD automatically deploys when the tracked repository branch receives a new commit (depending on the repository sync strategy). You can also trigger a deployment manually:
+
+1. Open the application.
+2. Click **Deploy** in the top-right corner.
+
+This forces an immediate sync and deployment regardless of the current sync status.
+
+## Application Settings
+
+Open an application and navigate to the **Settings** tab to configure it.
+
+### General
+
+Change the application name, icon, linked repository, branch, path, or agent.
+
+### Image Polling
+
+Image polling lets OrcaCD automatically pull updated Docker images and restart containers, even when no Compose file has changed. This is useful for continuous delivery workflows where a CI pipeline pushes new image tags.
+
+| Setting                  | Description                                                                  |
+| ------------------------ | ---------------------------------------------------------------------------- |
+| **Enable image polling** | Turns image polling on or off                                                |
+| **Polling interval**     | How often to check for new images (minimum 30 seconds, default 120 seconds)  |
+| **Delete old images**    | When enabled, old images are removed from the host after a successful update |
+
+## Image Pull Webhooks
+
+Instead of polling, you can trigger an image pull from your container registry via a webhook. This is ideal for registry-side push notifications.
+
+1. Open the application settings.
+2. In the **Image Pull Webhook** section, click **Generate Webhook**.
+3. OrcaCD returns a webhook URL and secret.
+4. Register this webhook in your container registry (e.g., Docker Hub, GitHub Container Registry, Harbor).
+
+When the registry sends a push event to the webhook URL, OrcaCD instructs the Agent to pull the latest image and restart the affected container.
+
+<Callout>
+	The Agent must be online for the image pull webhook to succeed. If the Agent is offline, the event
+	is not queued.
+</Callout>
+
+To revoke a webhook and generate a new one, click **Revoke Webhook** and then **Generate Webhook** again.

content/docs/architecture.mdx → content/docs/architecture/index.mdx

@@ -1,5 +1,5 @@
 ---
-title: Architecture
+title: Overview
 description: An overview of the architecture of OrcaCD.
 ---