> ## Documentation Index
> Fetch the complete documentation index at: https://docs.equa.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Command Center

# Command Center

Command Center is the full-screen Equanaut operating mode inside equa-web. It is no longer a supported split-origin Next.js app on port 3001. The frozen `equanaut-command-center-main` / `command-center-so` codebase remains source material for migrated behavior, but current operator workflows must open from the authenticated equa-web shell.

## URL contract

| Environment                  | URL                                             | Source of truth                                         |
| ---------------------------- | ----------------------------------------------- | ------------------------------------------------------- |
| Production / same-origin app | `https://app.equa.cc/prime?openEquanaut=true`   | equa-web opens Equanaut on the current app origin       |
| Local development            | `http://localhost:8080/prime?openEquanaut=true` | equa-web webpack dev server and authenticated app shell |
| Fleet observer               | `http://localhost:8080/fleet`                   | equa-web fleet tracker route with the Equanaut rail     |
| Admin diagnostics            | `http://localhost:8080/admin`                   | equa-web site-admin Command Center dashboard            |
| Equabot admin                | `http://localhost:8080/ai`                      | equa-web Equabot admin shell                            |
| Equabotz gateway             | `http://localhost:8080/equabotz`                | equa-web gateway-control embed                          |
| Deprecated source app        | `http://localhost:3001/command-center`          | unsupported; frozen source material only                |
| Docs                         | `https://docs.equa.cc/web/command-center`       | This page                                               |

The supported local Command Center path is same-origin through equa-web. Do not start or navigate to `localhost:3001` for current Command Center work unless you are explicitly comparing frozen source-material behavior.

<Note>
  This page is the current Command Center routing authority. Older docs that still describe `command-center-so`, `localhost:3001`, or `/command-center` as the current local app surface are legacy until they are reconciled with Spec 060.
</Note>

**Source evidence:**

* `equa-web/specs/060-command-center-fleet-management-shell/spec.md` defines equa-web as the sole supported Command Center surface and deprecates `localhost:3001/command-center`.
* `equa-web/src/logic/paths.ts` defines the mounted `/prime`, `/equabotz`, `/admin`, and `/ai` route constants.
* `equa-web/src/app/routes/routes.ts` mounts `/prime`, `/admin`, `/ai/*`, and `/equabotz` inside the authenticated equa-web app.
* `equa-web/src/modules/equanaut/index.tsx` opens full-page Equanaut via the same-origin `/prime?openEquanaut=true` handoff.
* `equa-web/src/modules/fleet-tracker/services/fleet-tracker-config.ts` defines the Fleet Tracker `command-center` panel used by `/fleet`.

## equa-web integration

Command Center is not a separate user-facing product surface. It is the expanded, full-page mode of the same Equanaut assistant experience:

* equa-web owns the main app shell, organization context, and the Equanaut sidebar.
* The Equanaut rail maximize control opens the full Command Center in place: full-screen rail, Command Center mode, and the Threads/Fleet/Status tabs.
* The Equanaut rail page action opens the same-origin Prime surface with `openEquanaut=true`, preserving the session key, organization id, and return URL.
* Command Center mode defaults to `agent:main:main`; org-scoped Equanaut sidebar chat uses `agent:main:equa-{organizationId}`.
* Operational panels now live in equa-web surfaces: `/prime`, `/fleet`, `/admin`, `/ai`, and `/equabotz`.

## Architecture

```
Browser (PWA)
    |
    v
equa-web authenticated app shell (local port 8080)
    |
    +-- /prime?openEquanaut=true -------> Equanaut chat + full Command Center rail mode
    +-- /fleet -------------------------> Fleet tracker observer with Command Center handoff
    +-- /admin -------------------------> Site-admin Command Center dashboard
    +-- /ai/* --------------------------> Equabot admin shell
    +-- /equabotz ----------------------> Gateway-control embed
    +-- /api/equanaut/* ----------------> Threads, fleet, sessions, and priority data
    +-- /api/fleet/* -------------------> Migrated fleet command contracts
    \-- Equabot Gateway (port 18789) ---> Gateway chat and runtime control
```

Command Center reads orchestration state from local JSON files written by the orchestration system and routes chat messages based on routing mode and model selection.

## Key components

| Component              | Purpose                                                                              |
| ---------------------- | ------------------------------------------------------------------------------------ |
| EquanautSidebar        | Rail surface, chat composer, maximize control, page handoff, and Command Center mode |
| CommandCenterPanel     | Threads, Fleet, and Status tabs rendered inside the full rail                        |
| PrimePage              | Same-origin conversational landing surface for Equanaut and gateway bootstrap        |
| FleetTracker           | Read-only observer route that embeds fleet state and exposes Command Center handoff  |
| CommandCenterDashboard | Site-admin dashboard mounted under `/admin`                                          |
| Equabot Admin Shell    | `/ai/*` gateway administration, approvals, agents, sessions, logs, and models        |
| Equabotz Embed         | Gateway-control surface mounted under `/equabotz`                                    |

## Setup

### Prerequisites

* Node.js version supported by equa-web
* equa-server available on port 3000
* Equabot gateway running on port 18789

### Environment

Use the equa-web development environment. Gateway-specific values are still read by the gateway and API layer:

```env theme={null}
EQUABOT_GATEWAY_URL=http://localhost:18789
EQUABOT_GATEWAY_TOKEN=your-token-here

# Optional -- only needed for OpenAI direct routing
OPENAI_API_KEY=sk-...

# Optional -- override local Ollama endpoint (default: http://localhost:11434)
OLLAMA_URL=http://localhost:11434
```

### Run

```bash theme={null}
yarn install
yarn start
```

`yarn start` already sets the legacy OpenSSL provider in equa-web's `package.json`. Open the app at `http://localhost:8080/prime?openEquanaut=true` or use the Equanaut rail from any supported equa-web route.

## API routes

Core same-origin contracts used by the integrated Command Center surfaces:

| Route                                                        | Method   | Auth       | Description                                              |
| ------------------------------------------------------------ | -------- | ---------- | -------------------------------------------------------- |
| `/api/equanaut/threads`                                      | GET/POST | Yes        | Thread list and creation data for the Threads tab        |
| `/api/equanaut/fleet`                                        | GET      | Yes        | Browser-agent fleet data for the Fleet tab               |
| `/api/equanaut/sessions`                                     | GET      | Yes        | Active session metadata for Command Center status        |
| `/api/fleet/pr-review`                                       | GET/POST | Yes        | Migrated PR review queue and dispatch contract           |
| `/api/fleet/instruct`                                        | POST     | Yes        | Migrated fleet instruction dispatch contract             |
| `/api/v1/agent/gateway/tools/invoke`                         | POST     | Yes        | Gateway tool calls used for sessions and task stack data |
| `/api/v1/organization/{organizationId}/agent/gateway/status` | GET      | Yes        | Gateway status for the Command Center Status tab         |
| `/api/v1/admin/gateway/health`                               | GET      | Site admin | Gateway health for admin and Prime operator panels       |
| `/api/v1/admin/gateway/token`                                | GET      | Site admin | Gateway token bootstrap metadata                         |

Namespace note: `/api/equanaut/*` and `/api/fleet/*` are top-level same-origin contracts introduced by Specs 041 and 031. The `/api/v1/*` paths are the existing equa-web API client namespace. The retired `/command-center/api/*` paths are not the supported local API surface. Keep any remaining references categorized as frozen-source or compatibility-only.

## Task stack contract

The priority stack adapter ingests GitHub Project items (24-field inventory) and produces a unified `TaskStackItem` payload consumed by Command Center status and task surfaces.

The response includes a `schemaVersion` field for observability.

<Accordion title="GitHub Project field inventory (24 fields)">
  Last verified against source: 2026-02-28

  <Note>
    The `gh project field-list --format json` CLI does not distinguish text, number, and date fields -- all report as `ProjectV2Field`. Only `ProjectV2SingleSelectField` is identified by type. The `update-project-field.py` helper infers field type from the value format (numeric values use `--number`, `YYYY-MM-DD` patterns use `--date`, otherwise `--text`).
  </Note>

  **Visible fields (17 table columns)**

  | #  | Field Name           | Field Type                     | Options / Details                                       |
  | -- | -------------------- | ------------------------------ | ------------------------------------------------------- |
  | 1  | Title                | Title (built-in)               | Issue/item title with link to source repo               |
  | 2  | Assignees            | Assignees (built-in)           | GitHub users                                            |
  | 3  | Linked pull requests | Linked PRs (built-in)          | Auto-linked PRs (draft/open/merged)                     |
  | 4  | Sub-issues progress  | Sub-issues progress (built-in) | Segmented bar; numerical ratio (e.g. 2/5)               |
  | 5  | Priority             | Single select (custom)         | `P0 - Critical`, `P1 - High`, `P2 - Medium`, `P3 - Low` |
  | 6  | Stack Rank           | Number (custom)                | Primary sort key; ascending                             |
  | 7  | Urgency              | Single select (custom)         | `Urgent`, `High`, `Normal`, `Low`                       |
  | 8  | Blocked By           | Text (custom)                  | Free-text dependency/blocker references                 |
  | 9  | Equabot Session      | Text (custom)                  | Equabot session links or IDs                            |
  | 10 | Comet Browser Thread | Text (custom)                  | Comet browser thread references                         |
  | 11 | Comet Browser Space  | Text (custom)                  | Comet browser space references                          |
  | 12 | Gmail Email Thread   | Text (custom)                  | Gmail thread links                                      |
  | 13 | Shortwave App        | Text (custom)                  | Shortwave references                                    |
  | 14 | NotebookLM           | Text (custom)                  | NotebookLM links                                        |
  | 15 | Google Drive Folder  | Text (custom)                  | Google Drive folder URL                                 |
  | 16 | QBO Link             | Text (custom)                  | QuickBooks Online links                                 |
  | 17 | Google Doc           | Text (custom)                  | Google Doc links                                        |

  **Hidden fields (7 — configured but not displayed as columns)**

  | #  | Field Name   | Field Type               | Details                                                          |
  | -- | ------------ | ------------------------ | ---------------------------------------------------------------- |
  | 18 | Status       | Single select (built-in) | `Todo`, `In Progress`, `Done`; used by filter and board grouping |
  | 19 | Labels       | Labels (built-in)        | GitHub issue labels                                              |
  | 20 | Milestone    | Milestone (built-in)     | GitHub milestones                                                |
  | 21 | Repository   | Repository (built-in)    | Multi-repo source field                                          |
  | 22 | Type         | Type (built-in)          | Issue type classification                                        |
  | 23 | Reviewers    | Reviewers (built-in)     | PR reviewers                                                     |
  | 24 | Parent issue | Parent issue (built-in)  | Hierarchy parent reference                                       |

  **View configuration (Stack Ranked Priority List)**

  * Group by: `Priority`
  * Sort: `Stack Rank` ascending (primary), `Priority` ascending (secondary)
  * Filter: `-status:Done`
  * Field sum: `Count`
  * Default repository: `EQUAStart/equanaut-command-center-main`

  **Project owner mapping:** Two GitHub owners reference "Project #4" with different internal IDs. Orchestration scripts must specify `--project-owner` explicitly to target the correct project.

  | Owner            | Project # | Internal ID            | Default in Scripts                                 |
  | ---------------- | --------- | ---------------------- | -------------------------------------------------- |
  | `ShawnOwen`      | 4         | `PVT_kwHOAX66ks4BOENI` | `update-project-field.py`, `sync-project-ranks.py` |
  | `Balancing-Rock` | 4         | `PVT_kwDOD2hUnc4BPXw1` | `backfill-project4-fields.sh`, `project-sync.py`   |
</Accordion>

### Issue ingestion

Issues from 9 connected repositories are automatically added to Project #4 through two mechanisms. The GitHub Team plan limits built-in auto-add workflows to 5 per project; additional repos use a GitHub Actions workflow.

**Method A -- Built-in Project Workflows (5 repos)**

Configured directly on the project under **Settings > Workflows**. Each triggers when a new or updated item matches the `is:issue` filter.

| Repository                               | Workflow Name                          |
| ---------------------------------------- | -------------------------------------- |
| `stacks-ranking-priorities`              | Auto-add to project                    |
| `EQUAStart/equanaut-command-center-main` | Auto-add: equanaut-command-center-main |
| `stack-ranked-priorities`                | Auto-add: stack-ranked-priorities      |
| `Food-Tracking_App`                      | Auto-add: Food-Tracking\_App           |
| `sscs-qbo-sync`                          | Auto-add: sscs-qbo-sync                |

**Method B -- GitHub Actions (4 repos)**

Each repo contains `.github/workflows/auto-add-to-project.yml` using `actions/add-to-project@v1.0.2`, authenticated via the `ADD_TO_PROJECT_PAT` classic PAT (`repo` + `project` scopes).

| Repository          | Trigger                                   | Auth                        |
| ------------------- | ----------------------------------------- | --------------------------- |
| `task-threads`      | `issues: [opened]`                        | Org secret (Balancing-Rock) |
| `demo-repository`   | `issues: [opened]`                        | Org secret (Balancing-Rock) |
| `Speed-Reader-App`  | `issues: [opened]`                        | Org secret (Balancing-Rock) |
| `EQUAStart/equabot` | `issues: [opened, transferred, reopened]` | Repo secret (cross-org)     |

`EQUAStart/equabot` uses a repo-level secret because GitHub org secrets do not cross org boundaries. The PAT itself is scoped to the user account and covers both orgs.

Canonical architecture reference: [project-auto-add-flowchart.md](https://github.com/Balancing-Rock/stacks-ranking-priorities/blob/main/docs/project-auto-add-flowchart.md)

### Source priority

The stack adapter tries these sources in order:

1. **GitHub Projects** (live data via `gh` CLI)
2. **Local stack file** (for local dev with recent syncs)
3. **Remote compute API** (if configured)
4. **Bundled data** (static fallback)

### Task identity

Tasks use a composite identity with precedence:

1. `projectItemId` (GitHub Project item ID -- used for project mutations)
2. `githubIssueNumber` (cross-repo references)
3. `slug` (UI/session alias)

### Priority and status authority

GitHub Project fields (`Priority`, `Status`, `Stack Rank`, `Urgency`) are authoritative. The UI may compute display-only decorations but does not override the normalized values from the API payload.

### Blocker convention

The `Blocked By` text field supports parseable tokens:

| Pattern                            | Example                             |
| ---------------------------------- | ----------------------------------- |
| `#N` (same-repo issue)             | `#123`                              |
| `issue:N`                          | `issue:456`                         |
| `owner/repo#N` (cross-repo)        | `Balancing-Rock/equabot#789`        |
| `item:PVTI_xxx` (project item)     | `item:PVTI_abc123`                  |
| `session:...` (session dependency) | `session:agent:main:task-thread:42` |

Tokens are comma- or semicolon-separated. Optional annotation text after `--` is stripped before parsing.

### Session linkage

Sessions are linked to task threads using cascade matching:

1. **Equabot session key** (strongest match)
2. **GitHub issue number** (extracted from session label)
3. **Slug** (legacy fallback)

### Runtime mapping

Each project field anchors a specific runtime entity:

| System Entity            | Project Fields                                      | Purpose                                   |
| ------------------------ | --------------------------------------------------- | ----------------------------------------- |
| Task Thread              | `Title`, `Repository`, `Type`, `Parent issue`       | Canonical thread identity and hierarchy   |
| Priority Stack           | `Priority`, `Stack Rank`, `Urgency`, `Status`       | Ordering, triage, and lifecycle           |
| Dependency Graph         | `Blocked By`, `Sub-issues progress`                 | Blockers and aggregate completion         |
| Agent Runtime Session    | `Equabot Session`                                   | Primary orchestrator/agent context        |
| Browser Subagent Context | `Comet Browser Thread`, `Comet Browser Space`       | Browser automation and research context   |
| Conversation Context     | `Gmail Email Thread`, `Shortwave App`, `NotebookLM` | Communication and knowledge context       |
| Artifact Layer           | `Google Drive Folder`, `Google Doc`, `QBO Link`     | Persistent deliverables and finance links |

The unified runtime chain is:

`Task Thread` → `Agent Session` → `Subagent Context` → `Conversation Surfaces` → `Artifacts`

Where:

* **Agent Session** is anchored by the `Equabot Session` field.
* **Subagent Context** is anchored by the Comet Browser fields.
* **Conversation Surfaces** are anchored by email and research fields (Gmail, Shortwave, NotebookLM).
* **Artifacts** are anchored by Drive, Docs, and QBO fields.

This mapping allows different UI layouts (table, board, conversation panel, session monitor) to render the same underlying thread state from one project schema.

## Polling and real-time behavior

The integrated Command Center uses same-origin API polling for rail tabs and admin panels. Fleet dispatch remains request-driven.

| Endpoint(s)                                                  | Mechanism      | Interval                      | Component                            |
| ------------------------------------------------------------ | -------------- | ----------------------------- | ------------------------------------ |
| `/api/equanaut/threads`                                      | Poll           | 30s                           | Threads tab                          |
| `/api/equanaut/fleet`                                        | Poll           | 30s while Fleet tab is active | Fleet tab                            |
| `/api/equanaut/sessions`                                     | Poll fallback  | 30s                           | Status tab                           |
| `/api/v1/agent/gateway/tools/invoke`                         | Poll fallback  | 30s                           | Sessions and priority stack          |
| `/api/v1/organization/{organizationId}/agent/gateway/status` | Poll fallback  | 30s                           | Gateway status                       |
| `/api/v1/admin/gateway/health`                               | Poll           | Page controlled               | Prime operator and admin diagnostics |
| `/api/fleet/pr-review`                                       | Request-driven | On demand                     | PR review queue and dispatch         |

## Orchestration integration

Command Center reads these files from the orchestration directory:

| File                  | Contents                                        |
| --------------------- | ----------------------------------------------- |
| `global-stack.json`   | Priority-ranked task list                       |
| `blocked-agents.json` | Blocked agents and threads                      |
| `work-queue.json`     | Active sessions, completed tasks, stalled items |
| `learnings.jsonl`     | Daily learnings log                             |

### Orchestration scripts

These Python scripts in `equabot/orchestration/` interact with GitHub Project V2 fields:

| Script                        | Purpose                                                                                               | Invocation                                                                             |
| ----------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `update-project-field.py`     | Update any project field by human-readable name                                                       | `python3 update-project-field.py <issue_ref> <field_name> <value>`                     |
| `sync-project-ranks.py`       | Sync Stack Rank from `global-stack.json` to project                                                   | Cron-driven; reads `global-stack.json`                                                 |
| `backfill-project4-fields.sh` | Backfill Priority and Urgency from issue labels                                                       | Manual; one-time setup                                                                 |
| `project-sync.py`             | Sync project items to Priority Stack cache                                                            | Cron-driven                                                                            |
| `verify-sync-chain.py`        | Verify sync chain integrity across GDrive, local threads, global-stack, GitHub Project #4, and CC API | `python3 verify-sync-chain.py [--issues REF,...] [--json] [--skip-gdrive] [--skip-cc]` |

#### update-project-field.py

Unified helper for updating any GitHub Project V2 custom field by human-readable inputs. Resolves all identifiers at runtime via the `gh` CLI with zero raw GraphQL.

```bash theme={null}
python3 update-project-field.py <issue_ref> <field_name> <value> [--project-owner OWNER] [--project-number N] [--dry-run]
```

**Arguments:**

* `issue_ref` -- Issue URL (`https://github.com/owner/repo/issues/N`) or shortref (`owner/repo#N`)
* `field_name` -- Human-readable project field name (e.g., `"Google Drive Folder"`, `"Priority"`, `"Stack Rank"`)
* `value` -- Value to set. For single-select fields, use the option name (e.g., `"P1 - High"`)

**Flags:**

* `--project-owner` -- GitHub project owner (default: `ShawnOwen`)
* `--project-number` -- GitHub project number (default: `4`)
* `--dry-run` -- Resolve all IDs and print the `gh project item-edit` command without executing

**Field type auto-detection:** The `gh` CLI does not expose granular field types for text, number, and date fields (all report as `ProjectV2Field`). The script infers the correct `gh project item-edit` flag from the value format:

| Value Pattern                   | Detected Type | CLI Flag                    |
| ------------------------------- | ------------- | --------------------------- |
| Has `options` in field metadata | Single select | `--single-select-option-id` |
| Matches `YYYY-MM-DD`            | Date          | `--date`                    |
| Valid integer or float          | Number        | `--number`                  |
| Anything else                   | Text          | `--text`                    |

**Examples:**

```bash theme={null}
# Set a text field
python3 update-project-field.py EQUAStart/equabot#14 "Google Drive Folder" "https://drive.google.com/..."

# Set a number field
python3 update-project-field.py EQUAStart/equabot#14 "Stack Rank" 3

# Set a single-select field
python3 update-project-field.py EQUAStart/equabot#14 "Priority" "P1 - High"

# Dry run with a different project owner
python3 update-project-field.py --dry-run --project-owner EQUAStart EQUAStart/equanaut-command-center-main#34 "Priority" "P2 - Medium"
```

**Error handling:** Exits non-zero with actionable messages for invalid issue references, issues not in the project, unknown field names (lists available fields), unknown option names (lists valid options), and `gh` CLI failures.

## Tech stack

* **Host app:** equa-web React application
* **Language:** TypeScript
* **Styling:** equa-web component styles and module-local React styles
* **Auth:** equa-web authenticated routes and site-admin permission gates
* **State:** React hooks, Redux-backed app context, and same-origin API calls

## Troubleshooting

### Browser still opens port 3001

The docs or app entry point is stale if it sends you to `http://localhost:3001/command-center`. Use the same-origin equa-web route instead:

1. Start equa-web locally.
2. Open `http://localhost:8080/prime?openEquanaut=true`.
3. Use the Equanaut rail maximize button to enter the full Command Center.

### Command Center does not open from the rail

Confirm the page is running inside equa-web and that the URL parameter `openEquanaut=true` is present when using the full-page action. The rail maximize control should switch the existing rail into Command Center mode without leaving the current page.

## Related

* [System Overview](/architecture/system-overview) for how Command Center fits in the architecture
* [Repository Map](/architecture/repo-map) for project structure
* [Developer Setup](/onboarding/developer-setup) for local development
* [Control UI](/web/control-ui) for the Gateway built-in Control UI (separate from Command Center)