@eltonssouza/development-utility-kit 0.10.0

package/dashboard/public/content/docs/cli-reference.en.md

@@ -0,0 +1,538 @@
+# CLI reference — `duk` commands
+
+The `duk` CLI is the **mechanical surface** of the harness — everything deterministic, idempotent, and scriptable lives here (per ADR-034). For decisions that require contextual judgment (designing a feature, picking a stack, refactoring), use the chat layer (skills + agents). For everything that should run in CI without an LLM (validate environment, lint structure, install harness, scaffold project), use `duk`.
+
+This page is the operational index. Each command has its own subsection with signature, options, examples, exit codes, and what breaks if it fails. Help inside the terminal is always one step away: `duk help` for the menu, `duk help <command>` for command-specific details.
+
+Audience: developers integrating the harness into a project, ops/SRE running it in CI, and anyone debugging why `duk install` did not pick up a stack.
+
+Reference: ADR-018 (CLI redesign), ADR-028 (workflow), ADR-034 (CLI vs Skill design principle).
+
+---
+
+## Quick reference — all commands
+
+| Command | Mode | Idempotent | Needs LLM | Typical use |
+|---|---|---|---|---|
+| `duk new <name>` | scaffold | yes (refuses if dir exists with content) | no | Brand-new project, opens Cowork pointing at the new folder |
+| `duk install` | adopt | yes (drift detection refuses unsafe overwrites) | no | Inject `.claude/` + `CLAUDE.md` into an existing project |
+| `duk update` | adopt (alias) | yes (same as `install`) | no | Pull harness updates into an already-adopted project |
+| `duk sync-all <dir>` | batch | yes (dry-run by default) | no | Update harness across many projects at once |
+| `duk dashboard` | server | yes (port auto-increment) | no | Boot local telemetry + docs UI |
+| `duk doctor` | diagnose | yes | no | Validate environment (Node, git, hooks, packs, credentials) |
+| `duk lint` | validate | yes | no | Validate harness `.claude/` structure (frontmatter, refs, ADRs, packs) |
+| `duk help [command]` | meta | yes | no | Show usage or command-specific docs |
+| `duk --version` | meta | yes | no | Print installed `duk` version |
+
+All commands run on Node ≥18 and require `git` on `PATH`. Mechanical: no API call, no LLM, no network for `doctor`/`lint`/`help`/`--version`. Safe for CI.
+
+---
+
+## duk new — scaffold a new project
+
+```
+duk new <name>
+```
+
+Creates a brand-new folder `<name>` in the current directory, initialises a git repo, writes a `CLAUDE.md` template with an empty `## Project Identity` block, and injects the full `.claude/` harness (skills + agents + stacks + settings). Refuses if `<name>` already exists.
+
+### Arguments
+
+- `<name>` — required. Project folder name. Kebab-case recommended (`payment-gateway`, not `PaymentGateway` or `payment_gateway`).
+
+### Options
+
+(none beyond `--help` and `--version`)
+
+### What happens
+
+1. `mkdir <name>` in the current directory.
+2. `git init -q` in the new folder (non-fatal if git is not in PATH; warns and continues).
+3. Calls the same code path as `duk install --force` to inject `.claude/` + `CLAUDE.md` (drift detection skipped — fresh folder).
+4. Writes a placeholder `## Project Identity` block in `CLAUDE.md` for the user to fill via the `stack-discovery` skill.
+5. Prints a next-steps banner.
+
+### Examples
+
+```bash
+duk new my-app
+cd my-app
+# Open Cowork or Claude Code in this folder
+# First chat message: "sabatina pra projeto novo"
+# → stack-discovery skill walks through 8 questions, fills Project Identity
+```
+
+### Exit codes
+
+- `0` — project created successfully.
+- `1` — name missing, target dir already exists, or any fatal step (cannot create dir, etc.).
+
+### What breaks if it fails
+
+Nothing leaves residue: if the script fails mid-way, the partially created folder is left for the user to inspect or `rm -rf`. No global state is changed.
+
+### See also
+
+- [getting-started](existing-project) — once `duk new` is done, what to type next in the chat.
+- `stack-discovery` skill in [skills-reference](skills-reference) — fills `## Project Identity`.
+
+---
+
+## duk install — inject harness into a project
+
+```
+duk install [--sub <dir>] [--dry-run] [--check-only] [--force]
+```
+
+Injects the harness into the current working directory (or `--sub <dir>` subdirectory). Detects the existing stack from `pom.xml`, `package.json`, `pyproject.toml`, `go.mod`, etc. Preserves any existing `## Project Identity` block in `CLAUDE.md`. Refuses to overwrite local modifications without `--force`.
+
+### Arguments
+
+(none — operates on the current directory or `--sub <dir>`)
+
+### Options
+
+| Flag | Effect |
+|---|---|
+| `--sub <dir>` | Install into `<dir>` instead of CWD. The dir must already exist. |
+| `--dry-run` | Print what would be done; write nothing. |
+| `--check-only` | Detect stack + report local-vs-latest harness version + show drift; do not write. |
+| `--force` | Skip drift detection (overwrite local modifications). Backup is still created. |
+| `--help`, `-h` | Show this command-specific help. |
+
+### What happens
+
+1. Stack detection (`bin/lib/detect-stack.js`) — parses build files, infers language + framework + database hints.
+2. Drift detection — reads `.claude/.MANIFEST` (sha256 per file from the prior install). If any file was modified locally, install aborts and asks the user to either move customisations to `.claude/local/` (never overwritten), run with `--force`, or open a PR upstream.
+3. Backup — moves existing `.claude/` to `.claude.bak-<timestamp>/`.
+4. Copy — writes the new `.claude/` + `CLAUDE.md` (preserving `## Project Identity`).
+5. Manifest — writes `.claude/.MANIFEST` for the next drift check + `.claude/HARNESS_VERSION` for compatibility tracking.
+6. `local/` placeholder — writes `.claude/local/README.md` if not present.
+
+### Examples
+
+```bash
+# Inject into current directory
+duk install
+
+# Preview without writing
+duk install --dry-run
+
+# Detect stack + show drift without writing
+duk install --check-only
+
+# Force overwrite of local changes (backup preserved)
+duk install --force
+
+# Install into a subfolder
+duk install --sub backend
+```
+
+### Exit codes
+
+- `0` — install succeeded.
+- `1` — drift detected (user must resolve via `.claude/local/` or `--force`); also for any fatal step.
+
+### Drift detection — what to do when it triggers
+
+When `duk install` aborts due to drift, you have three options:
+
+1. **Move your customisations to `.claude/local/`** — that folder is never touched by `install`; the loader merges it on top of the canonical `.claude/`. Per ADR-032.
+2. **Re-run with `--force`** — overwrites with backup. Your changes survive in `.claude.bak-<timestamp>/` for review.
+3. **Open a PR upstream** — if your change is canonical (good for everyone), the harness adopts it.
+
+### What breaks if it fails
+
+If drift detection triggers, **nothing is written**. The existing `.claude/` is left intact. The error message tells you exactly which files drifted.
+
+If the copy step fails mid-way (rare, usually permission issues), the backup at `.claude.bak-<timestamp>/` is your rollback path:
+
+```bash
+rm -rf .claude
+mv .claude.bak-<timestamp> .claude
+```
+
+### See also
+
+- ADR-018 (CLI redesign, `install → adoptProject`)
+- ADR-028 (workflow), ADR-032 (drift + local/ + opt-in propagation)
+- `update-template` skill — same flow with a preview checkpoint inside chat.
+- `active-project` skill — same flow path-driven, non-interactive (for batch adoption).
+
+---
+
+## duk update — alias for install
+
+```
+duk update [same options as install]
+```
+
+Identical to `duk install`. Provided for ergonomics when you are updating an already-adopted project — the verb `update` reads more naturally than `install` in that context. Internally the code path is the same.
+
+See `duk install` above for full options and behaviour.
+
+---
+
+## duk sync-all — batch update across many projects
+
+```
+duk sync-all <dir> [--filter <expr>] [--exclude <name>] [--apply]
+```
+
+Iterates over every folder under `<dir>` that contains a `.claude/` directory and runs `duk install` on each. Default is dry-run — pass `--apply` to execute.
+
+### Arguments
+
+- `<dir>` — required. Parent directory containing adopted projects. Typically `C:\development\source\projects` on Windows, `~/development/source/projects` elsewhere.
+
+### Options
+
+| Flag | Effect |
+|---|---|
+| `--apply` | Execute the updates. Default behaviour is dry-run (prints what would be done). |
+| `--filter <expr>` | Filter projects by criteria. Repeatable (multiple filters AND together). |
+| `--exclude <name>` | Skip a project by folder name. Repeatable. |
+| `--help`, `-h` | Show command-specific help. |
+
+### Filter expressions
+
+| Expression | Matches |
+|---|---|
+| `stack:<lang\|framework>` | Projects with the given primary stack — e.g., `stack:java`, `stack:angular` |
+| `type:<value>` | Projects with the given `type:` in `## Project Identity` — e.g., `type:fullstack`, `type:backend` |
+| `age:<duration>` | Projects whose harness was last installed more than `<duration>` ago — e.g., `age:30d`, `age:6m` |
+| `harness-version:<semver>` | Projects with the specified harness version range — e.g., `harness-version:<0.2`, `harness-version:>=1.0` |
+
+### Examples
+
+```bash
+# Preview what would be updated
+duk sync-all C:/development/source/projects
+
+# Update only Java projects
+duk sync-all C:/development/source/projects --filter stack:java --apply
+
+# Update projects whose harness is older than 60 days
+duk sync-all C:/development/source/projects --filter age:60d --apply
+
+# Update everything except a critical production project
+duk sync-all C:/development/source/projects --exclude prod-critical --apply
+
+# Combine filters (AND logic)
+duk sync-all . --filter stack:java --filter age:30d --apply
+```
+
+### Exit codes
+
+- `0` — all targeted projects updated successfully (or dry-run completed).
+- non-zero — one or more updates failed (sync-all does not abort on per-project failure; it reports at the end).
+
+### What breaks if it fails
+
+Same drift semantics as `duk install` apply per project. A drift failure on one project does not stop the batch — `sync-all` collects results and reports at the end.
+
+### See also
+
+- Module: `bin/lib/sync-all.js`
+- `duk install` for per-project semantics
+
+---
+
+## duk dashboard — local telemetry + docs UI
+
+```
+duk dashboard [--port <n>] [--no-open]
+```
+
+Boots an Express server that serves the local telemetry dashboard (Vanilla JS + Chart.js CDN, no build) at `http://localhost:<port>`. Default port `4242`; auto-increments on `EADDRINUSE`. The dashboard reads:
+
+- `~/.claude/telemetry.db` (SQLite) — subagent telemetry from the `SubagentStop` hook
+- `rtk gain --format json` — RTK token savings (if `rtk` is on PATH; otherwise widget gracefully degrades)
+- `dashboard/public/content/manual/*.en.md` — user manuals
+- `dashboard/public/content/docs/*.en.md` — tech docs (this page is one of them)
+- `.claude/skills/*/SKILL.md` and `.claude/agents/*.md` — live skill/agent index
+- `docs/brain/decisions/ADR-*.md` — ADR catalog
+
+### Options
+
+| Flag | Effect |
+|---|---|
+| `--port <n>` | Bind to a specific port instead of `4242`. |
+| `--no-open` | Do not launch the browser automatically. |
+| `--help`, `-h` | Show command-specific help. |
+
+### Examples
+
+```bash
+duk dashboard                  # auto-detect free port from 4242
+duk dashboard --port 5000      # specific port
+duk dashboard --no-open        # do not open browser (useful for SSH/remote)
+```
+
+### Exit codes
+
+- `0` — dashboard started successfully (in foreground; Ctrl+C to stop).
+- non-zero — failed to start (port permission, dashboard dir missing, npm install failure on first run, etc.).
+
+### First-run behaviour
+
+If `dashboard/node_modules` does not exist, `duk dashboard` runs `npm install --prefix dashboard/` first (Express + better-sqlite3/sql.js). This happens once per machine.
+
+`bin/cli.js` also calls `rtk gain` once at startup and prints the output as a status banner. If `rtk` is not on PATH, prints "Note: rtk not found or returned no output — skipping gain report." and continues. The dashboard widget gracefully shows null.
+
+### What breaks if it fails
+
+If the server fails to start, the error is printed to stderr (usually permission or port conflict). Nothing is written to disk by the dashboard itself; safe to retry with a different port.
+
+### See also
+
+- [architecture-overview](architecture-overview) §"Telemetry + Dashboard"
+- [plugins](plugins) §"rtk — Rust Token Killer"
+- ADR-014 (Vanilla JS + Chart.js CDN), ADR-015 (triple-fallback telemetry writer), ADR-016 (`findFreePort` auto-increment)
+
+---
+
+## duk doctor — validate the environment
+
+```
+duk doctor [--strict] [--json]
+```
+
+Mechanical health check of everything needed for the harness to work day-to-day. No LLM, no API calls — safe to run in CI. Per ADR-034.
+
+### Options
+
+| Flag | Effect |
+|---|---|
+| `--json` | Machine-readable JSON output (`{ summary, checks }`). Good for CI integration. |
+| `--strict` | Exit non-zero on any WARN too (default: only FAIL fails). |
+| `--help`, `-h` | Show command-specific help. |
+
+### Checks (categories)
+
+| Category | What it validates |
+|---|---|
+| `environment` | Node ≥18, git, npx, python (warn for python — used by some plugin hooks) |
+| `harness` | `.claude/{agents,skills,stacks}` exist, `CLAUDE.md`, `package.json`, `bin/cli.js` |
+| `settings` | `~/.claude/settings.json` is valid JSON; hook command paths point to existing files |
+| `stacks` | `.claude/stacks/` has packs + `README.md` index |
+| `credentials` | `C:\development\tools\credentials\vps.txt` present (WARN if missing — not fatal) |
+| `project` | If CWD is an adopted project: `.MANIFEST` present + `Project Identity` is filled (not `<project-name>` placeholder) |
+
+### Examples
+
+```bash
+# Standard health check
+duk doctor
+
+# Treat warnings as failures (useful in CI)
+duk doctor --strict
+
+# Machine-readable output for CI parsing
+duk doctor --json | jq .summary
+```
+
+### Exit codes
+
+- `0` — all PASS, or only WARN (unless `--strict`).
+- `1` — any FAIL, or any WARN with `--strict`.
+
+### Output format
+
+Human-readable: aligned table with `CATEGORY | CHECK | STATUS | DETAIL` columns and a summary line. JSON: `{ "summary": {PASS, WARN, FAIL}, "checks": [{category, name, status, detail}, ...] }`.
+
+### What breaks if it fails
+
+`doctor` itself never modifies state. A failure means an environment issue (Node too old, git not in PATH, broken hook path in `~/.claude/settings.json`, missing pack, etc.). Read the DETAIL column and fix the specific issue, then re-run.
+
+### See also
+
+- ADR-034 (mechanical → CLI principle)
+- Module: `bin/lib/doctor.js`
+
+---
+
+## duk lint — validate harness structure
+
+```
+duk lint [--category <name>] [--json]
+```
+
+Mechanical structural validation of the harness `.claude/` directory. No LLM. Replaces `scripts/lint-harness.mjs` (deprecated).
+
+### Options
+
+| Flag | Effect |
+|---|---|
+| `--json` | Machine-readable JSON output. |
+| `--category <name>` | Run only specified category (comma-separated for multiple). |
+| `--help`, `-h` | Show command-specific help. |
+
+### Categories
+
+| Category | What it validates |
+|---|---|
+| `skills` | `SKILL.md` frontmatter: required fields (`name`, `description`, `tools`, `model`) + `name` matches directory |
+| `agents` | Agent `.md` frontmatter: required fields (`name`, `description`, `model`) + `name` matches filename |
+| `refs` | Agents mentioned in skill routing tables exist in `.claude/agents/` |
+| `adrs` | ADRs cross-referenced across decisions exist + numbering gaps reported |
+| `stacks` | Each stack pack has the recommended sections (Build & run, Code patterns, Anti-patterns, Security, Testing) |
+| `d1-contract` | Pattern 1 pairs (skill↔agent share name): skill body forbids `checklist`/`golden rule`/`inviolable rules` sections; agent body forbids `PT triggers:` sections |
+
+### Examples
+
+```bash
+# Full lint suite
+duk lint
+
+# Single category
+duk lint --category skills
+
+# Multiple categories
+duk lint --category skills,agents
+
+# Machine-readable for CI
+duk lint --json > lint-report.json
+```
+
+### Exit codes
+
+- `0` — no ERROR found.
+- `1` — at least one ERROR (WARN never fails the exit code; use the JSON output to act on WARN if you want).
+
+### Output format
+
+Human-readable: violations grouped by category, each line shows `[ERROR|WARN] <relative-path>:<line> — <message>`, followed by a summary line. JSON: `{ "summary": {ERROR, WARN}, "categories": [...], "violations": [{category, severity, file, line, msg}, ...] }`.
+
+### Severity policy
+
+- **ERROR** — structural break (missing required field, broken reference). Blocks. Triggers exit code 1.
+- **WARN** — cosmetic or non-blocking issue (numbering gap, missing recommended section, optional contract drift). Reports but does not block.
+
+### What breaks if it fails
+
+`lint` itself never modifies state. A failure tells you the harness's `.claude/` structure has a real or perceived issue. Read the violation list and either fix the file or — if the lint is wrong — update the rules in `bin/lib/lint.js` (with an ADR if the change is structural).
+
+### See also
+
+- ADR-034 (mechanical → CLI principle)
+- Module: `bin/lib/lint.js`
+- Deprecated predecessor: `scripts/lint-harness.mjs` (still works but emits a deprecation warning; `duk lint --category d1-contract` gives the same coverage)
+
+---
+
+## duk help — show usage
+
+```
+duk help [command]
+duk <command> --help
+```
+
+Two forms, identical behaviour:
+
+- `duk help` — general usage page (all commands, common flags, examples).
+- `duk help <command>` or `duk <command> --help` — command-specific help with all flags and examples for that one command.
+
+Commands with detailed help: `new`, `install`, `update`, `sync-all`, `dashboard`, `doctor`, `lint`, `help`.
+
+### Examples
+
+```bash
+duk help
+duk help install
+duk install --help        # equivalent
+duk help doctor
+```
+
+### Exit codes
+
+- `0` — help shown.
+- `1` — unknown command name passed to `duk help <unknown>` (still prints general help, but signals error).
+
+---
+
+## duk --version
+
+```
+duk --version
+duk -v
+```
+
+Prints the installed `duk` version (from `package.json`). Useful for sync-all filtering (`--filter harness-version:<X>`) and for CI smoke tests.
+
+### Examples
+
+```bash
+duk --version    # → 1.0.0
+duk -v           # → 1.0.0
+```
+
+### Exit codes
+
+- `0` — always (version is read from a bundled file, cannot fail).
+
+---
+
+## Roadmap — future commands
+
+Per ADR-034 (mechanical → CLI), the following commands are likely additions in future waves. Each is listed with the skill it extracts the mechanical part from, so the migration path is auditable.
+
+| Future command | Extracts mechanical part from | Status |
+|---|---|---|
+| `duk gate` | `prd-ready-check`, `auto-test-guard` (the runner part) | Planned — turns the senior+ gate into a CI-runnable check without LLM |
+| `duk template diff` | `update-template` | Planned — extracts the hash-compare drift detection logic |
+| `duk scaffold <type> --stack <pack>` | `scaffold` skill (the dispatch part) | Planned — runs the stack-specific setup without going through chat |
+| `duk brain new <type>` | `brain-keeper` | Planned — generates `docs/brain/` templates for daily, feature, ADR, bug, tech-debt, migration |
+| `duk audit-coverage` | `test-coverage-auditor` | Planned — extracts the metrics part; flagging stays in the skill |
+| `duk freeze <plugin>` | new — version pinning for external plugins | Planned |
+| `duk uninstall` | new — reverse of `install` | Planned |
+
+Migration is **by demand**, not speculative. When a current skill is slow because of inline bash, or needs to run in CI, that's when the mechanical part gets extracted to `duk`. See ADR-034 §"Migration plan".
+
+---
+
+## Common debug recipes
+
+### "Why is my drift detection triggering?"
+
+```bash
+duk install --check-only          # shows which files drifted
+cat .claude/.MANIFEST | head -10  # see the recorded sha256s
+```
+
+### "I want to know which projects are out of date"
+
+```bash
+duk sync-all C:/development/source/projects --filter age:30d
+# Dry-run — lists projects whose harness is older than 30 days
+```
+
+### "Lint is angry about a skill — what's wrong exactly?"
+
+```bash
+duk lint --category skills --json | jq '.violations[] | select(.file | contains("<skill-name>"))'
+```
+
+### "Is my environment actually OK?"
+
+```bash
+duk doctor --strict        # exits non-zero on warnings too
+```
+
+### "Dashboard won't start"
+
+```bash
+duk dashboard --port 5000  # try a non-default port
+node --version             # check Node ≥18
+ls dashboard/node_modules  # should exist after first run
+```
+
+---
+
+## See also
+
+- [architecture-overview](architecture-overview) — where the CLI fits in the 3-layer model.
+- [skills-reference](skills-reference) — for the chat layer (what NOT to put in `duk`).
+- [plugins](plugins) — external dependencies that `duk` shells out to (`rtk`, `impeccable`).
+- [hooks-reference](hooks-reference) — runtime hooks the harness installs in `~/.claude/settings.json`.
+- ADR-018 (CLI redesign), ADR-028 (workflow), ADR-034 (CLI vs Skill design principle).