Agent-Deployment-Co · jcsalterego · Jul 28, 2026 · Jul 28, 2026 · Jul 28, 2026 · Jul 28, 2026
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -137,8 +137,17 @@ export default defineConfig({
         ]
       },
       {
-        text: 'Teams',
-        items: [{ text: 'Argus Hub', link: '/argus-hub' }]
+        text: 'Using Argus Hub',
+        items: [
+          { text: 'Overview', link: '/argus-hub' },
+          { text: 'Configuration', link: '/argus-hub/configuration' },
+          { text: 'Activity', link: '/argus-hub/activity' },
+          { text: 'Tasks', link: '/argus-hub/tasks' },
+          { text: 'Tools', link: '/argus-hub/tools' },
+          { text: 'Team', link: '/argus-hub/team' },
+          { text: 'MCP', link: '/argus-hub/mcp' },
+          { text: 'Export', link: '/argus-hub/export' }
+        ]
       },
       {
         text: 'Reference',

diff --git a/docs/argus-hub.md b/docs/argus-hub.md
@@ -2,48 +2,30 @@
 description: Run an Argus Hub so a team can pool its usage into one org-wide dashboard. Setup, connecting people and what each person sends.
 ---
 
-# Argus Hub
+# Argus Hub: Overview
 
-Argus Hub is a self-hosted server that collects usage data from multiple Argus clients and
-presents an org-wide [dashboard](/terminology#dashboard). It is the on-premises alternative to
-the hosted `argus-dash` backend.
+[Argus Hub](https://github.com/Agent-Deployment-Co/argus-hub) is a self-hosted server that pools session, task, and usage data
+from a team's [Argus](https://github.com/Agent-Deployment-Co/argus) clients into one org-wide dashboard. Argus Hub runs
+entirely on your own network.
 
-Each person points Argus at the Hub and uses the normal [sync](/terminology#sync) command. Hub
+Each person points their Argus client at an Argus Hub instance and uses the normal [sync](/terminology#sync) command. Argus Hub
 receives the usage snapshot at `POST /api/sync`, combines it in one database and tags it by user.
 Nothing is forwarded anywhere else. The raw prompt and response text stays on each person's
 machine, as do their BYO model API keys.
 
-## Set up a Hub
-
-Hub requires Node.js 20.17 or later, or Bun 1.0 or later. Start it with:
-
-```bash
-npx @agentdeploymentco/argus-hub serve --port 4343
-```
-
-The first startup creates `data/hub.db`, generates an API key and generates an admin password.
-Both values are printed once, so copy them to a secure location before closing the terminal.
-
-The **API key** authenticates uploads from Argus clients. The **admin password** protects the
-dashboard at `http://localhost:4343/login` and the Hub's read-only MCP endpoint. Set
-`ADMIN_PASSWORD` before starting Hub to keep the same dashboard password across restarts. If you
-do not set it, Hub generates a new password each time it starts.
-
-::: warning Keep the credentials private
-The API key allows clients to upload data. The admin password allows access to the organization's
-pooled usage data. Do not put either value in source control or share them in a public channel.
-:::
+Setting an Argus Hub up, including generating its secret key, API key and admin password, is covered in
+[Configuration](/argus-hub/configuration#quick-start).
 
 ## Connect Argus clients
 
-In the desktop app, open **Settings** and enter the Hub URL and API key. The app uploads on a
+In the desktop app, open **Settings** and enter the Argus Hub URL and API key. The app uploads on a
 schedule after the connection is configured.
 
 The app stores the key securely and shows a masked value after you save it.
 
 <div class="screenshot">
 
-![Argus Hub settings with a Hub URL and masked Hub key.](./images/screenshots/argus-hub-settings@1920x1080@2.webp)
+![Argus Hub settings with an Argus Hub URL and masked Argus Hub key.](../images/screenshots/argus-hub-settings@1920x1080@2.webp)
 
 </div>
 
@@ -62,8 +44,8 @@ export ARGUS_HUB_URL=https://hub.internal:4343
 export ARGUS_HUB_KEY=hub-example-key
 ```
 
-With a Hub configured, `argus sync` uploads to that Hub instead of the hosted service. No
-`argus login` or OAuth flow is needed. Hub identifies a person from the client's latest identity
+With an Argus Hub configured, `argus sync` uploads to that Argus Hub instead of the hosted service. No
+`argus login` or OAuth flow is needed. Argus Hub identifies a person from the client's latest identity
 signal, using the Claude or Codex OAuth email when available and falling back to the local Git
 name. Repeat clients from the same person are grouped together.
 
@@ -83,214 +65,68 @@ To upload one snapshot immediately:
 npx @agentdeploymentco/argus sync
 ```
 
-## Configure the Hub
-
-Hub reads `hub.json` from the current directory, then environment variables, then command-line
-flags. A later source takes precedence over an earlier one.
-
-| CLI flag | Environment variable | `hub.json` key | Default | What it controls |
-|---|---|---|---|---|
-| `--port` | `HUB_PORT` | `port` | `4343` | Port Hub listens on |
-| `--data-dir` | `HUB_DATA_DIR` | `dataDir` | `./data` | Folder containing `hub.db` |
-| None | `ADMIN_PASSWORD` | None | Random | Dashboard and MCP password |
-| None | `HUB_INSECURE_COOKIE_HOSTS` | None | None | Hostnames allowed to use a non-`Secure` cookie for private plain-HTTP deployments |
-
-For example:
-
-```json
-{
-  "port": 4343,
-  "dataDir": "/var/lib/argus-hub"
-}
-```
-
-There is no `HUB_KEY` setting. Hub stores API keys in `hub.db`. If the database has no API keys
-when Hub starts, it generates a key for the Default organization and prints it to the terminal.
-
-Only use `HUB_INSECURE_COOKIE_HOSTS` for hostnames reachable through a private network. Never list
-a hostname that is reachable from the public internet.
-
-To rotate a key, delete the old key's row from the Hub database, then restart Hub. Hub only
-generates a new key when the `api_keys` table is empty, so disabling a key with `is_enabled = 0`
-does not trigger this: rotation requires removing the row outright, not just disabling it. A
-disabled key is rejected before Hub reads the upload body.
-
-## Run Hub continuously
-
-Hub runs in the foreground, so a service manager can restart it and collect its logs. The Argus
-Hub repository contains the Dockerfile and the complete service examples. The common deployment
-shapes are below.
-
-### Linux with systemd
-
-Save this as `/etc/systemd/system/argus-hub.service`:
-
-```ini
-[Unit]
-Description=Argus Hub
-After=network.target
-
-[Service]
-Type=simple
-ExecStart=npx @agentdeploymentco/argus-hub serve --port 4343
-WorkingDirectory=/srv/argus-hub
-Environment=HUB_DATA_DIR=/srv/argus-hub/data
-Restart=on-failure
-RestartSec=5
-
-[Install]
-WantedBy=multi-user.target
-```
-
-Enable and follow it with:
-
-```bash
-sudo systemctl enable --now argus-hub
-sudo journalctl -fu argus-hub
-```
-
-Set `ADMIN_PASSWORD` in the service environment so a restart does not change the dashboard
-password.
-
-### Docker
-
-Build the image and persist `/data`, which contains `hub.db`:
-
-```bash
-docker build -t argus-hub .
-docker run -d \
-  --name argus-hub \
-  -p 4343:4343 \
-  -v argus-hub-data:/data \
-  argus-hub
-```
-
-Pass `ADMIN_PASSWORD` with `-e` or an env file. The image exposes `GET /healthz`, which returns
-`200 ok` without authentication for container health checks and Kubernetes liveness probes.
-
-For Docker Compose, persist the same data volume:
-
-```yaml
-services:
-  argus-hub:
-    build: .
-    restart: unless-stopped
-    ports:
-      - "4343:4343"
-    volumes:
-      - argus-hub-data:/data
-
-volumes:
-  argus-hub-data:
-```
-
-### macOS with launchd
-
-Create a LaunchAgent at `~/Library/LaunchAgents/co.agentdeployment.argus-hub.plist`, set its
-working directory and `HUB_DATA_DIR`, then load it:
-
-```bash
-launchctl load ~/Library/LaunchAgents/co.agentdeployment.argus-hub.plist
-```
-
-Use the service definition in the [Argus Hub repository](https://github.com/Agent-Deployment-Co/argus-hub)
-for the complete plist, including log paths and restart behavior.
+Argus Hub's port, data directory, secret key and admin password, plus how to keep it running and
+private, are covered in [Configuration](/argus-hub/configuration).
 
 ## Use the dashboard
 
-Open the Hub URL in a browser. The dashboard groups organization-wide usage into these views:
+Open the Argus Hub URL in a browser. The dashboard groups organization-wide usage into five views,
+each covered in depth under **Using Argus Hub** in the nav:
 
 <div class="screenshot">
 
-![Argus Hub activity dashboard showing organization-wide usage, tasks, token usage and cost.](./images/screenshots/argus-hub-dashboard@1920x1080@2.webp)
+![The Argus Hub Activity view: headline totals, the daily activity chart and cost by model.](../images/screenshots/argus-hub-activity@1920x1080@2.webp)
 
 </div>
 
 | View | What you can see |
 |---|---|
-| Activity | Usage and cost for the whole organization or one person |
-| Tasks | Extracted tasks, including outcomes, frustration and interrupted rates, and top failure signals |
-| Tools | Tool and MCP server usage across the organization or for one person |
-| Team | Per-user sessions, tokens, estimated cost and last-sync time |
-| Export | Download the full dataset as a Snowflake-ready zip |
-
-The user/group picker appears after at least one client syncs. Leave it on **All** for an
-organization-wide view, or choose one person or group to scope Activity, Tasks and Tools. The
-Team table can be sorted by any column, and clicking a row opens that person's own activity view.
-
-## Query Hub from an agent
-
-Hub provides a read-only [MCP](https://modelcontextprotocol.io) endpoint at `POST /mcp`. It uses
-the stateless Streamable HTTP transport, so an MCP client sends JSON-RPC requests directly over
-HTTPS without a subprocess or a session.
-
-| Tool | What it answers |
-|---|---|
-| `query_activity` | Usage and cost over a time window, including the previous window for comparison |
-| `query_tasks` | A paged, filterable list of extracted tasks |
-| `query_task_quality` | Success, frustration and interruption rates, outcomes over time and failure signals |
-| `query_tool_usage` | Which tools and MCP servers people use |
-| `query_users` | User IDs, display names, emails, last-sync time, sessions, tokens and cost |
-
-The first four query tools accept `since`, `until`, `project`, `source`, `user` and `group`
-filters. The `source` filter accepts `claude`, `codex`, `gemini` or `cowork`. The `group` filter
-takes a groupId, or `__none__` for users with no group assigned. `query_users` accepts an
-optional `group` filter (matching a groupId or groupName) and can help you find a `userId` before
-scoping another query.
-
-Authenticate with the Hub admin password:
-
-```text
-Authorization: Bearer <admin-password>
-```
-
-For Claude Code, add the endpoint with:
-
-```bash
-claude mcp add --transport http argus-hub https://hub.internal:4343/mcp \
-  --header "Authorization: Bearer <admin-password>"
-```
-
-Treat the admin password as a shared read credential after you give it to an agent. Anyone who
-holds it can query the organization's activity, tasks and tool usage. If Hub runs without
-`ADMIN_PASSWORD`, the MCP route is open, so set a password for any shared or network-accessible
-deployment.
+| [Activity](/argus-hub/activity) | Usage and cost for the whole organization, trended against the prior window |
+| [Tasks](/argus-hub/tasks) | Extracted tasks, outcomes, frustration and friction, top failure signals |
+| [Tools](/argus-hub/tools) | Tool, skill and MCP server usage across the organization |
+| [Team](/argus-hub/team) | Per-user sessions, tokens, estimated cost, last-sync time and groups |
+| Labels | Argus Hub-wide task labels: create, apply and remove them (see [Argus Hub labels](/argus-hub/tasks#argus-hub-labels)) |
+| [Export](/argus-hub/export) | Download the full dataset, or load it into Snowflake |
 
-## Export Hub data
+The group picker appears after at least one client syncs and someone has been put in a group.
+Leave it on **All** for an organization-wide view, or choose a group to scope Activity, Tasks and
+Tools. The Team table lists everyone by group, and clicking a row opens that person's own
+activity view.
 
-`argus-hub export snowflake` creates a consistent Snowflake-ready snapshot of the live Hub
-database. Add `--load` to upload it with the built-in connector, or use the generated JSONL files
-and `load.sql` for a manual or scheduled load.
+**Settings** holds the task LLM provider Argus Hub will use for organization-level task labeling.
+Nothing in Argus Hub calls this provider yet beyond a **Test connection** check on the Settings page
+itself; it's reserved for a future feature. Any API key you save there is encrypted in `hub.db`
+with `HUB_SECRET_KEY`.
 
-See [Export Argus Hub data to Snowflake](https://github.com/Agent-Deployment-Co/argus-hub/blob/main/docs/snowflake.md)
-for data coverage, setup, authentication, scheduling and limitations.
+## MCP
 
-## Keep a Hub private
+Argus Hub also provides a read-only-by-default [MCP](https://modelcontextprotocol.io) endpoint at
+`POST /mcp`, so an agent can query activity, tasks and tool usage directly. See
+[MCP](/argus-hub/mcp) for the full tool list, filters, authentication and a worked
+example.
 
-Place Hub behind a VPN or a reverse proxy with TLS. Do not expose it directly to the internet.
-The Hub database contains the session data of every syncing user, so restrict filesystem access
-and include it in backups. Hub sets new database files to mode `0600`.
+## Export Argus Hub data
 
-The client sends resolved usage rows, session summaries, tasks, interaction metadata, tool and MCP
-invocations and labels. It does not send retained prompt and response text or BYO API keys. The
-client's local `argus.db` file never leaves the machine as a file.
+`argus-hub export snowflake` creates a consistent Snowflake-ready snapshot of the live Argus Hub
+database, from the dashboard or the command line. See [Export](/argus-hub/export) for both paths and
+the Snowflake load flow.
 
 ## Data flow
 
 ```text
-Argus clients --POST /api/sync--> Hub ingest --> hub.db
+Argus clients --POST /api/sync--> Argus Hub ingest --> hub.db
                                       |
                                       +--> dashboard and MCP queries
 ```
 
-Hub supports multiple organizations. Each API key belongs to one organization. Run separate Hub
+Argus Hub supports multiple organizations. Each API key belongs to one organization. Run separate Argus Hub
 instances when unrelated tenants need strict isolation.
 
 ## License
 
 Argus Hub is licensed under the [Functional Source License 1.1](https://github.com/Agent-Deployment-Co/argus-hub/blob/main/LICENSE),
 which converts to MIT two years after each release. You can use, modify, distribute and build on
-Hub for personal, internal or commercial purposes. For the first two years, you cannot run a paid
+Argus Hub for personal, internal or commercial purposes. For the first two years, you cannot run a paid
 hosted service whose primary offering is Argus Hub as a service. The restriction does not cover a
 larger product where agent-usage reporting is a small feature.