# Decantr Command Surface

This is the current command audit for the Decantr 3 governance line. The goal is consolidation without breaking users: workflow commands are the human-facing product surface, while existing primitives remain available for advanced users, scripts, and CI internals.

| Command | Class | Decision | Notes |
| --- | --- | --- | --- |
| `setup` | primary | keep | Detect project state and recommend the right Decantr workflow without writing files. |
| `scan` | primary | keep | Read-only Brownfield reconnaissance over local files; prints `ScanReportV2` plus typed Contract graph readiness as terminal output or JSON and writes no files. |
| `new` | primary | keep | Greenfield workspace creation. |
| `adopt` | primary | keep | Brownfield one-liner over analyze, proposal acceptance, online pack hydration, Project Health, evidence, baseline, and optional CI. |
| `task` | primary | keep | Route/task context activation for AI coding assistants, including typed graph capsule references, task-aware route graph ranking, optional graph-shaped changed-file impact, authority lane, local law, and runtime boundary. |
| `verify` | primary | keep | One reliability gate over Project Health, typed graph freshness, optional Brownfield guard checks, baselines, evidence, local law, and workspace health. |
| `ci` | primary | keep | Non-mutating CI gate plus CI integration generator for projects and workspaces. |
| `resolve` | primary | keep | Read-only authority resolver for source-vs-contract conflicts; explicit drift-log writes require flags and contract/source mutations remain in existing workflows. |
| `connect` | primary | keep | Configure editor-specific Decantr activation such as Cursor MCP and project rules without changing source. |
| `doctor` | primary | keep | Explain project/workspace state, adoption lane, generated artifacts, typed graph readiness, local law, CI wiring, design authority signals, and the ordered next-step queue. |
| `codify` | primary | keep | Propose and accept project-owned Brownfield/Hybrid UI law and style bridges. |
| `studio` | primary | keep | Local Project Health and workspace triage UI. |
| `content` | content-author | keep | Content-author namespace over check, create, corpus summary, and execution-pack hydration. Hosted publish is retired. |
| `magic` | advanced | keep | Intent-first greenfield path; not the primary enterprise story. |
| `init` | advanced | keep | Attach/setup primitive for Decantr contracts and context. |
| `analyze` | advanced | keep | Brownfield inventory and proposal primitive used by `adopt`. |
| `refresh` | advanced | keep | Regenerate derived context/style artifacts. |
| `graph` | advanced | keep | Generate typed Contract graph artifacts, graph diff, manifest, source-artifact index, contract capsule, optional task-ranked route subgraph, and optional node/source-file impact subgraph under `.decantr/graph`. |
| `check` | advanced | keep | Fast contract and guard validation. |
| `health` | advanced | keep | Canonical report, Evidence Bundle, prompt, browser/token checks, and lower-level Project Health primitive used by `verify` and `ci`. |
| `workspace` | advanced | keep | Monorepo app candidate discovery, attached Decantr project listing, and aggregate health; `verify --workspace` is the user-facing shortcut. |
| `heal` | deprecated-alias | soft-deprecate | Alias for `check`; retained for compatibility. |
| `audit` | advanced | keep advanced | Lower-level verifier audit/file critique. |
| `status`, `sync`, `upgrade`, `sync-drift`, `get`, `list`, `validate`, `rules`, `export` | advanced | keep | Useful when users need direct corpus, rules, export, or diagnostic control. |
| `registry` | deprecated-alias | soft-deprecate | Compatibility alias for content-corpus and execution-pack workflows; docs should prefer `decantr content ...`. |
| `showcase`, `telemetry` | operator | keep | Internal support workflows. |
| `login`, `logout` | deprecated-alias | soft-deprecate | Legacy registry-account commands retained for scripts; hosted account flows are retired. |
| `content-health`, `create`, `publish` | content-author | keep as aliases | Backward-compatible root commands; docs should prefer `decantr content ...`; hosted publish exits with a retirement message. |

The typed metadata lives in `packages/cli/src/command-surface.ts` and is covered by tests against the dispatched CLI commands. Any new top-level command should update that file, command help, package docs, root docs, release notes, and relevant skills before it ships.

Brownfield intelligence is now exposed through workflows first:

- `decantr scan` is the zero-commit preview. It detects selected app scope, workspace package manager, frontend framework, primary language, route signals, taskable routes, component inventory confidence, styling, static-hosting hints, Decantr presence, assistant-rule files, and typed Contract graph readiness, then prints a terminal report without creating `.decantr`, installing dependencies, building the app, executing scripts, uploading source, or saving a report. For attached Essence V4 apps, `graphPreview` is derived in memory and reports whether `.decantr/graph` artifacts are current, stale, or missing. Use `--project apps/web` from monorepos and `--json` for automation; JSON emits `scan-report.v2`.
- `decantr adopt --yes` runs the full adoption path and explains the underlying primitives before writing. In monorepos, use `decantr adopt --project apps/web --yes`; `--base-url` is optional visual evidence, not the default attach command. Online adoption hydrates content API execution packs automatically; use `--no-packs` to defer that step.
- First-time users should read the command choice this way: `scan` for read-only preview, `adopt` for existing app attachment, `new` for greenfield starters, and `init` only when they need the lower-level attach primitive. After adoption, `decantr studio` gives a local visual triage view and `decantr doctor` explains the next command.
- `decantr task <route>` surfaces the relevant context files, patterns, screenshot references, accepted local laws, accepted style bridge mappings, changed files, impacted routes, typed route graph context when available, v2 loop instructions, and authority lane for the next LLM edit. When task text is present, route graph ranking combines weighted traversal with deterministic local personalized PageRank and task boosts, then records matched terms. When changed files resolve to SourceArtifact nodes, task JSON includes a graph-shaped changed-file impact context with affected routes, pages, findings, evidence, and provenance. The authority block states source authority, style authority, active authorities, runtime boundary, and warnings for cross-runtime or Decantr CSS requests.
- `decantr codify --from-audit` proposes `.decantr/local-patterns.proposal.json` and `.decantr/rules.proposal.json` with source evidence, confidence tiers, and likely variants for project-owned component families; `decantr codify --style-bridge` proposes `.decantr/style-bridge.proposal.json`; `decantr codify --map-pattern <slug>` maps a hosted/bundled registry pattern into advisory local law without changing source; `decantr codify --accept` promotes reviewed proposals, activating Hybrid local law or Hybrid style bridge.
- `decantr verify --brownfield --local-patterns` runs the reliability gate, checks typed graph freshness for attached apps, requires accepted local patterns, scans accepted local rules when present, and emits v2 Project Health/Evidence loop payloads.
- `decantr resolve --project <path>` reads the v2 authority resolution block, groups conflicts by authority lane, and prints exact next commands. It does not mutate by default. `--defer <finding-id>` and `--mark-advisory <finding-id>` may write `.decantr/drift-log.json`; contract, source, local-law, and style-bridge changes stay in explicit workflows such as `codify`, `init --existing --merge-proposal`, `add/remove`, and MCP `decantr_contract_write`.
- `decantr connect cursor --project <path>` writes `.cursor/mcp.json` and `.cursor/rules/decantr.mdc` in the opened workspace, preserving existing MCP servers. The generated rule tells Cursor Agent to call Decantr task context before route edits, preserve source-vs-contract drift stop conditions, and keep monorepo app scope in the task and verify commands. Use `--preview` for a no-write inspection.
- `decantr doctor --project <path>` explains whether the app is attached, which adoption lane is active, whether generated context and typed graph artifacts are current, whether local law exists, whether CI is wired, and which commands to run next.
- `decantr ci --project <path>` is the blessed CI command. It is non-mutating, adoption-mode aware, emits a v2 `DecantrCiReport`, carries the same loop verdict as `verify`, and prints accepted `.decantr/rules.json` findings plus style bridge status alongside Project Health. Text and Markdown output distinguish enforceable accepted local rules from advisory style-bridge mappings. `--fail-on error` leaves warning-level local law visible; `--fail-on warn` blocks on it. `decantr ci init` writes root GitHub workflows or generic pipeline snippets using the pinned package-manager command instead of `@latest`, and prints the install command when `@decantr/cli` is not pinned yet.
- `decantr health init-ci` and `decantr verify init-ci` are legacy aliases for `decantr ci init`; they should generate the same pinned `decantr-ci.yml` surface, not the old `@latest` Project Health workflow.
- `decantr analyze` still writes Brownfield intelligence, theme inventory, and enrichment backlog artifacts.
- `decantr graph --project <path>` writes `.decantr/graph/graph.snapshot.json`, `.decantr/graph/snapshots/<snapshot-id>.json`, `graph.manifest.json`, `graph.diff.json`, and `contract-capsule.json` from Essence, accepted local rules, accepted style bridge, Brownfield analysis route-source provenance, reusable component declarations, visual manifest, health baseline diffs, and saved Evidence Bundle artifacts when present. Accepted style bridge token hints become first-class Token nodes so the Contract capsule can expose project-owned style authority without requiring Decantr CSS. Evidence Bundle repair/read targets and baseline changed files become source artifacts when the referenced files exist, giving findings and temporal evidence file-level anchors; the capsule includes bounded SourceArtifact paths as `file_path` handles for follow-up graph tools, reports when the list is truncated, and can be tuned with `--capsule-source-limit <count>`. CLI JSON and MCP graph metadata expose typed diff counts such as added findings, resolved findings, and added evidence. `decantr graph --route /feed --json` includes the route-scoped graph subgraph with hybrid weighted/PageRank ranking; `decantr graph --node cmp:button --impact --json` includes dependency impact context for a component, token, rule, finding, or source artifact; `decantr graph --file src/app/page.tsx --impact --json` resolves a project-relative source file to its SourceArtifact node and returns its route/page blast radius; `--snapshot-id <id>` replays a local history snapshot, and `--compare-to <id> --include-diff-ops --json` compares the selected/current graph against another local snapshot with bounded typed diff operations. `decantr graph --check` is the CI-safe freshness check.
- `decantr setup` is stateful orientation: before adoption it shows app candidates and the attach command; after adoption it shows attached projects plus `doctor`, `task`, `verify`, and `ci init` as the day-two loop.
- `decantr workspace list` ranks monorepo app candidates before any workflow command uses the first suggestion. Product UI apps rank ahead of docs, Storybook, API/server, MCP helper, workbench/demo, and package/library surfaces. JSON output includes `rank`, `score`, `category`, and `reason` in addition to the existing path, attachment state, and suggested adopt command.
- `decantr suggest` accepts `--route`, `--file`, `--from-code`, and `--project`; when accepted local law or a style bridge exists, project-owned patterns and mappings are shown before registry suggestions. From an app root, suggestions should discover local law from the current directory without requiring `--project`; from a monorepo root, use `--project <app>`. `--from-code` may derive the query from `--route` or `--file`, and monorepo-root file paths under the selected project are normalized to app-local paths.
- `decantr check --brownfield --project <path>` validates the selected app from a monorepo root; app-scoped primitives should not silently fall back to the workspace root.
- `decantr add page <section>/<page> --route <route> --project <path>` writes both the page and route mapping so the page is immediately usable by `decantr task <route>`.
- App-scoped primitives that support project state (`health`, `status`, `upgrade`, `add`, `remove`, `theme`, `export`, `suggest`, `magic`, `rules`, and `telemetry`) should honor `--project <path>`. Unsupported flags should fail before writing proposal/generated files.
- `decantr content get-pack page --route <route>` is the CLI task-context path through the existing pack surface. `decantr content compile-packs apps/web/decantr.essence.json --write-context` hydrates app packs beside the provided essence path. Legacy `decantr registry ...` aliases remain compatible for Decantr 3.x scripts.
- `decantr health --browser --base-url <url> --evidence` writes local screenshots and a visual manifest; `--save-baseline` / `--since-baseline` add continuity.
- `decantr health --diagnostics --json` prints the stable diagnostic code and repair ID catalog without running a project audit.
- `decantr refresh --check` is the CI-safe generated-context freshness check and fails when `pack-manifest.json` references missing files. In contract-only Brownfield it should not fail solely because content API packs were intentionally deferred. `decantr refresh --list-changes` prints created, updated, and removed generated files after regeneration, using paths that are openable from the command's current directory.

Command help must be side-effect free. `decantr <command> --help`, `decantr <command> -h`, and `decantr <command> help` should print help and never execute command bodies or write project files.

Package and trust audits are repo scripts, not user-facing CLI commands. `pnpm audit:package-surface` verifies support-matrix drift and the installed permission surface, while `pnpm audit:package-permissions` runs the permission-only audit with `npm pack --dry-run --json`. The generated reference is `docs/reference/security-permissions.md`.

`@decantr/vite-plugin` remains experimental after this audit. It may become a verifier-backed dev adapter later, but it is not part of the default Decantr 3 reliability layer.