---
name: docforge-dashboard
description: Previews the written docs as a local, browsable site — rebuilds only what changed, never touches the repo's package files.
---

# Docforge Dashboard

Slash command: `/docforge-dashboard`. Thin entrypoint into the `docforge`
skill — this skill has no runtime of its own. It requires the `docforge`
skill to be installed and loads its shared cartridge:
[`../docforge/_shared/README.md`](../docforge/_shared/README.md).

Cartridge root: `../docforge/_shared` relative to this SKILL.md — the
`docforge` skill's `_shared`, whether installed as a plugin, via Agent Skills,
or in a global skill dir. Locate the copy of this skill that the host loaded —
never resolve against the session working directory. Check, in order:

1. **Repo-local self-host** — if the working repo contains
   `skills/docforge-dashboard/SKILL.md`, the cartridge is
   `<repo>/skills/docforge/_shared`.
2. **Plugin root** — a plugin install keeps the same layout:
   `<plugin-root>/skills/docforge/_shared`.
3. **Global skill dirs** — the running agent's own dir first, then the shared
   standard set: `~/.agents/skills/docforge/_shared`,
   `~/.claude/skills/docforge/_shared`,
   `~/.config/opencode/skills/docforge/_shared`, plus any other skill dir the
   running agent documents.

Use the repo-local copy when the working repo self-hosts it; otherwise the
global one. Resolve every path inside loaded cartridge files against this
root, never the working directory. If no copy can be located,
ask the user for the absolute cartridge root first.

## Load order

1. [`../docforge/_shared/rules.md`](../docforge/_shared/rules.md) — safety, graph precondition,
   provider sufficiency, completion.
2. [`../docforge/_shared/flags.md`](../docforge/_shared/flags.md) — `--plan-only`,
   `--auto-accept`.
3. [`../docforge/_shared/retrieval.md`](../docforge/_shared/retrieval.md) — catalog retrieval
   protocol.
4. Follow [`../docforge/_shared/workflows/dashboard.md`](../docforge/_shared/workflows/dashboard.md)
   for the full dashboard lifecycle.
5. For execution rules and CLI syntax, use
   [`../docforge/_shared/workflows/tools.md`](../docforge/_shared/workflows/tools.md).

Run tools from the cartridge root (`../docforge/_shared/`). Lock one session
engine first; see
[`../docforge/_shared/workflows/tools.md`](../docforge/_shared/workflows/tools.md).

```sh
# After locking python3 for this session:
python3 runtime/cli/python/dashboard.py scan --repo <repo> [--json]
python3 runtime/cli/python/dashboard.py start --repo <repo> [--force] [--plan-only] [--no-open]
python3 runtime/cli/python/dashboard.py export --repo <repo>

# After locking node instead:
node runtime/cli/js/dashboard.js scan --repo <repo> [--json]
node runtime/cli/js/dashboard.js start --repo <repo> [--force] [--plan-only] [--no-open]
node runtime/cli/js/dashboard.js export --repo <repo>
```

## `/docforge-dashboard`

| Flag | Effect |
|---|---|
| *(none)* | `dashboard.{py,js} start` (scripts and README: [`../docforge/_shared/runtime/dashboard/README.md`](../docforge/_shared/runtime/dashboard/README.md)): reconcile metadata → rebuild generated output when the working-tree signature changed → serve → open |
| `--force` | Ignore signatures: always regenerate generated output (`content/docs`, assets, navigation, app shell), keeping `node_modules` |
| `--plan-only` | Preflight, metadata dry-run, signatures, and route plan; no conversion, no writes, no server. On a legacy manifest, the metadata dry-run is the `migrate_metadata.{py,js} --dry-run` preview (see [`../docforge/_shared/runtime/manifest/README.md`](../docforge/_shared/runtime/manifest/README.md)) |
| `--auto-accept` | Skip the revise-vs-render prompt and routine pauses; never authorizes npm install of new packages without its own confirmation gate (see [`../docforge/_shared/flags.md`](../docforge/_shared/flags.md)) |
| `--help` | Print this command's purpose and full parameter reference — [`../docforge/_shared/help.md`](../docforge/_shared/help.md) — then stop; run no workflow |

Subcommands: `scan` (read-only diagnostics: missing metadata, incomplete or
missing documents, stale provenance sources, broken links, untracked `docs/`
files), `start` (build-if-changed → serve → open), `export` (build-if-changed
→ static HTML export: `next build` emits **`index.html` per page** under
`<dashboard>/out/` — `/docs` → `out/docs/index.html`, never flat `docs.html`
— for static hosting (GitHub Pages, S3, …) at a domain root; no server, no
browser; takes no flags), `status` (read-only state), `stop` (shut down the
background dev server). See
[`../docforge/_shared/workflows/dashboard.md`](../docforge/_shared/workflows/dashboard.md)
for the full lifecycle and isolation rules.

## Preflight gates

`start` runs three preflight checks before it opens the dashboard; the full
procedure and exact wording are owned by
[`../docforge/_shared/workflows/dashboard.md`](../docforge/_shared/workflows/dashboard.md),
which this entrypoint's load order already pulls in.

- **Legacy manifest** — a pre-3.0 `.docforge/manifest.json` (1.1
  `project_context` / `document_groups`, 2.0 flat `documents`, or any other
  legacy shape) is auto-migrated to 3.2 automatically, never a stop-and-ask
  gate: `migrate_metadata` (**any** legacy version, re-registered) is
  idempotent and only ever touches the manifest and document frontmatter,
  never bodies. The migration is always printed, never silent. `--plan-only`
  runs the `migrate_metadata.{py,js} --dry-run` preview instead of migrating;
  `scan`/`status` stay strictly read-only and never migrate.
- **Scan** — findings (missing metadata, incomplete documents, stale sources,
  broken links, route-plan problems, untracked `docs/` files) print in full
  and recommend `/docforge-revise`, each tagged blocking or advisory. A
  blocking finding (broken links, route-plan problems, or metadata errors on
  an included document) stops `start` before any build is attempted;
  advisory-only findings (or a clean scan) still let the dashboard render.
- **Build failure** — a failed `start` is **not** opened and no previous build
  is presented as current; revise first, then re-run once the whole-tree gate
  passes.

`--auto-accept` never suppresses the scan or build-failure findings above —
the recommendation to revise is never silent.

## Not this command

- Fresh-start documentation plan → `/docforge`
  ([`../docforge/SKILL.md`](../docforge/SKILL.md)).
- Structural revise of the documentation itself → `/docforge-revise`
  ([`../docforge-revise/SKILL.md`](../docforge-revise/SKILL.md)).
- Read-only progress → plain language or `manage_manifest.{py,js} status` (no
  `--status` skill flag; scripts and README:
  [`../docforge/_shared/runtime/manifest/README.md`](../docforge/_shared/runtime/manifest/README.md)).