@rhize/skill-forge 0.14.0 → 0.16.0

package/README.md

@@ -2,7 +2,8 @@
 
 **The supply-chain gate for agent skills.**
 
-Status: pre-release (built 2026-07-11)
+Status: published — `@rhize/skill-forge@0.14.0` on npm (`0.16.0` in this repo, pending release),
+0.x beta (Pro features free until 1.0)
 
 > This project is unrelated to the [`skillforge`](https://www.npmjs.com/package/skillforge)
 > package on npm, which is a Claude Skills *evaluation* framework. `skill-forge` (this package,
@@ -27,19 +28,15 @@ promote/hold/reject decision**, before it is allowed anywhere near your working
 npx @rhize/skill-forge init
 ```
 
-Optional, but recommended first: `init` detects which coding agents you have installed — the
-matrix covers 73 known agents (Claude Code, Codex CLI, Cursor, Windsurf, OpenCode, Gemini CLI,
-and 67 more; see `src/agents.ts`), and every entry's skill-directory paths are verified directly
-against the [vercel-labs/skills](https://github.com/vercel-labs/skills) CLI's own source, not
-just its README — none are unverified/community guesses today. (The schema carries a
-`verified: false` flag for any future entry that can't be confirmed that way; it's unused as of
-this release.) `init` lets you pick which of their skill directories should be gated, a default
-promotion target, and an optional agent to hand follow-up prompts off to (see
-[`--ingest`](#ingestion-handoff---ingest)). No configuration is
-required for a first run either way — skip `init` and skill-forge defaults to `<cwd>/.claude/skills`
-as its promotion target and `~/.skill-forge/quarantine` as its sandbox (and offers to run `init` for
-you the first time `add`/`scan`/`list`/`status` runs with no config present, in an interactive
-terminal). See [docs/configuration.md](docs/configuration.md) for the full field reference.
+Optional, but recommended first: `init` detects which coding agents you have installed (73 known
+agents) and lets you pick which of their skill directories to gate, a default promotion target,
+and an optional agent to hand follow-up prompts off to. It also checks whether each picked root is
+under Git version control yet and, if not, offers to give it a baseline commit (exact commands
+shown first, default No). No configuration is required either way — skip `init` and skill-forge
+defaults to `<cwd>/.claude/skills` as its promotion target (and offers to run `init` for you the
+first time `add`/`scan`/`list`/`status` runs with no config present, in an interactive terminal).
+See [docs/commands/init.md](docs/commands/init.md) for the full detection/menu/Git-preflight
+behavior and [docs/configuration.md](docs/configuration.md) for the config field reference.
 
 ```bash
 npx @rhize/skill-forge add <owner>/<skill-name>
@@ -64,866 +61,31 @@ anything ending in `.git`), or a local filesystem path.
 
 ## Commands
 
-```
-skill-forge init [options]                     Detect installed agents and set gate targets / handoff agent
-skill-forge add <source> [options]             Quarantine-install a skill and run it through the gate
-skill-forge scan <source> [options]            Gate a skill without installing it (always cleans up)
-skill-forge evolve <skill-dir> [options]       Self-evolve an installed skill via SkillOpt-Sleep, re-gate, decide (Pro)
-skill-forge audit [options]                    Doctor-style health check over the configured skill/MCP set (alias: doctor)
-skill-forge finding accept <fp-prefix>         Acknowledge a LOW/MEDIUM audit finding you've reviewed (human-only, no gate effect)
-skill-forge finding revoke <fp-prefix>         Remove a stored acceptance so the finding reports again
-skill-forge finding list [options]             List every accepted finding
-skill-forge organize [options]                 Set-level capability registry + dependency graph across configured skills roots (Pro)
-skill-forge find [query] [options]             Discover skills via skills.sh and check partner security audits (free)
-skill-forge watch [options]                    Drift check across every SOURCES.md provenance ledger (Pro)
-skill-forge ingest [options]                   Hand the pending-ingestion queue off to a coding agent for the decide/absorb pass (Pro)
-skill-forge queue close <id> --status <s>      Close a queue entry after the decide pass (Pro)
-skill-forge refine [options]                   Capture a project-scope override from real usage feedback (Pro)
-skill-forge refine list [options]              Show refinement history
-skill-forge refine patterns [options]          List tracked/ready/generalized/dismissed patterns
-skill-forge refine promote <PATTERN-ID>        Merge a ready pattern into the user-scope skill (Pro)
-skill-forge refine rollback <backup-id>        Restore a promotion backup (Pro)
-skill-forge refine which <skill>               Print override-resolution order for a skill
-skill-forge routine [options]                  One scheduled maintenance pass: audit + drift + registry, cron-friendly (Pro)
-skill-forge promote <id> [options]             Re-gate a held quarantine entry and promote it
-skill-forge reject <id> [options]              Discard a held quarantine entry
-skill-forge config <sub> [args]                Read/write open-ended preferences (list|get|set|unset|propose|review)
-skill-forge list                               List skills currently held in quarantine
-skill-forge status                             Show configuration and quarantine summary
-skill-forge guide [topic]                      Orientation: what this does, your current state, the next command
-```
-
-### `init`
-
-```bash
-skill-forge init              # interactive: pick targets, default target, handoff agent
-skill-forge init --defaults   # non-interactive: agents found on PATH, first as default (CI)
-skill-forge init --list       # print detected agent skill roots and exit — no writes
-skill-forge init --all-agents # don't narrow to agents whose CLI is on PATH — keep every root
-```
-
-Probes the known agent matrix (`src/agents.ts`) for both project-relative (`.claude/skills`, ...)
-and global (`~/.codex/skills`, ...) skill directories that already exist on disk, then writes
-`skillsRoots`, `agents`, `defaultTarget`, and (if you pick a handoff agent) `handoffCommand` to
-`config.json`. Safe to re-run any time — it always starts from your existing config and only
-overwrites the fields it's responsible for. If no `config.json` exists yet, `add`/`scan`/`list`/
-`status` offer to run this for you on first use (skipped entirely for `--json`/`--yes`/non-TTY
-invocations, so scripted runs never block on a prompt).
-
-**Menus are keyed on the PATH, not the agent (v0.11).** Many agents share one skills directory —
-18 entries in the agent matrix use `.agents/skills` as their project root — so the gate-target and
-default-target menus list each *distinct* root once, labelled with the agents that resolve to it
-(`19 agents (project): Amp, Replit, Universal, +16 more`), and `skillsRoots`/`mcpTargets` are
-written deduped. `config.agents` still records every agent, since it's an id→root map. Detection
-output says so explicitly when roots collapse (`→ 21 agents share 3 distinct skills root(s)`).
-Configs written by earlier versions are deduped on load, so no re-run is required to clean one up.
-
-**Narrowed to agents you actually have (v0.11).** Because a shared directory can't tell you which
-of its 18 agents you use, init also checks PATH: a root is pre-selected when at least one agent
-mapped to it has its CLI installed, and roots with none are still listed, just switched off with
-the reason shown.
-
-```
-[x] 1. /Users/you/.agents/skills
-       on PATH: Codex, Gemini CLI (project) (+17 other agents share this path)
-[ ] 3. /Users/you/.openclaw/skills
-       OpenClaw (global) — no verified CLI name to check
-```
-
-The PATH check is a **look-up only — nothing found is ever executed** (no `--version` probe), and
-binary names are held to the same evidence bar as the skill paths: an agent with no verified
-command name reports "unknown", never "not installed". `--all-agents` turns narrowing off, and it
-disables itself automatically if no agent CLI is found at all, so it can never reduce a working
-detection to an empty config. The handoff menu is only *reordered* by it — installed CLIs float to
-the top and everything detected stays pickable.
-
-**Selecting things (v0.11).** The multi-selects take a whole answer at once — `2`, `1 3`, `2, 4`,
-`2-5`, plus `all` and `none` — and Enter confirms. Anything unrecognized is named back to you and
-ignored, never silently swallowed. The single-choice prompts (default target, handoff agent)
-**re-ask** on an answer that isn't one listed number instead of falling back to option 1, so a
-multi-value or mistyped answer can no longer write a target you didn't choose. Ctrl+D at any
-prompt exits cleanly.
-
-**Init now ends by offering the audit (v0.8).** After an interactive run writes its config, it
-asks "Run the skills & MCP audit now? [Y/n]" (default yes) and, if accepted, runs
-`skill-forge audit` interactively — see [`audit`](#audit-v08) below. `init --defaults` runs it too,
-but non-interactively (`--yes`): a report is written, with no business-profile prompt, no
-foundation scaffold, and no agent handoff. `init --list` and an aborted/empty selection stay
-write-free, so neither writes a config nor runs the audit.
-
-### `add`
-
-```bash
-skill-forge add owner/name
-skill-forge add https://github.com/owner/repo.git --target ./.claude/skills
-skill-forge add ./local-skill-dir --yes
-skill-forge add owner/name --json
-skill-forge add owner/name --yes --ingest
-```
-
-Installs the source into a quarantine sandbox, then runs it through the gate: profile → safety
-scan → overlap analysis against the configured skills root (Pro) → report. Nothing touches the
-target skills root until you decide.
-
-| Option | Effect |
-|---|---|
-| *(none)* | Prompts you to **promote**, **hold**, or **reject** the candidate. |
-| `-y, --yes` | Skips the prompt and honors the gate verdict: a `block` safety verdict is rejected (process exits nonzero); anything else (`pass`/`warn`) is promoted. |
-| `-t, --target <dir>` | Skills root to promote into. Defaults to the config's `defaultTarget`, then `skillsRoots[0]`. |
-| `--json` | Prints the gate result (profile, safety findings, overlap) as JSON instead of the terminal report box. Implies non-interactive: the decision is made the same way `--yes` makes it (verdict decides promote/hold/reject), never an interactive prompt. |
-| `--ingest` | Pro (free during the 0.x beta). After a successful promote, hands off to a coding agent — see [Ingestion handoff](#ingestion-handoff---ingest). |
-| `--skill-map <path>` | Path to a generated `rhize-plugins` skill map (Phase 4 of that repo's skill-map-graph-substrate plan). When given, ranks the candidate's name/description against every `skill` node in the map — a near-duplicate of an already-shipped marketplace skill is folded into the safety findings as a `HIGH`-severity finding (escalates the verdict to `block`, so it's held rather than silently promoted); a moderate overlap is `MEDIUM` (`warn`). Free (not Pro-gated) — this enforces the marketplace's own curation rule ("close the gap, don't duplicate"), not a premium ranking feature. Missing/unreadable map: printed to stderr, never fatal. **Two map variants exist, with different coverage**: the **static** map (`rhize-plugins/generated/skill-map.static.json`) is first-party-only — it only knows about that marketplace's own skills, so it cannot catch a candidate that duplicates an *installed third-party plugin's* skill. The **resolved** map (`~/.claude/context-manager/skill-map.resolved.json`, produced by `rhize-context-manager`) additionally carries the full third-party ecosystem inventory. Point `--skill-map` at the resolved map when you want ecosystem-wide duplicate detection; the static map is enough only when you're curating a single first-party marketplace against itself. |
-
-**Observability (v0.14.0):** the `--skill-map` curation check now always reports that it ran. A below-threshold PASS previously left no trace at all — no line in the report, no field in `--json` — making "checked 45 skills, nothing crossed the threshold" indistinguishable from "the check never ran". That ambiguity caused a correct PASS to be written up as a broken gate. The report now carries a `Marketplace overlap` line (`checked N skills — closest "x" (score), none over threshold` / `skipped — <reason>`) and `--json` a `mapOverlap` object with `status`, `compared`, `topMatch`, and `matches`. `topMatch` is informational only: it is never graded and never produces a finding. **Scoring and both thresholds are unchanged.** Note the check is lexical, not semantic — two skills can claim the same invocation trigger in different words and score far below threshold (measured: 0.134), so competing `description:` triggers still need a human read. See `gate/mapOverlap.ts`'s module doc.
-
-**Bugfix (v0.13.0):** `--skill-map` previously matched nothing against either real map variant — the loader read a `type` field that the real generated artifact never sets (it uses `kind`), so every node was silently invisible to the overlap check. `loadSkillMap()` now normalizes `kind` → `type` at load time; regression coverage lives in `test/mapOverlap.realmap.test.ts` against vendored real-map snapshots. If you were relying on `--skill-map` before v0.13.0, it was a no-op — re-run `add`/`scan` on anything you're unsure about.
-
-**Extends-declared overlap exemption**: a candidate can declare `metadata.rhize.extends:
-["<skill-name>" | "<plugin>/<skill-name>"]` in its SKILL.md frontmatter to mark itself a
-deliberate specialization/layering of an existing map skill. When the top `--skill-map` match is
-a skill the candidate declares it extends, that finding is downgraded from a HOLD-level safety
-finding to an informational notice printed above the report — it never escalates the verdict.
-Overlap with any *other* skill (a different match, or a second candidate/skill pair) still holds
-at full severity: the exemption applies per declared pair, not globally, so declaring an
-extension of skill X never waives overlap with skill Y.
-
-A promoted skill gets a provenance entry appended to `<target>/SOURCES.md`, and every promote or
-hold decision is recorded to `~/.skill-forge/queue.json` (or `$SKILL_FORGE_HOME/queue.json`) — see
-[`docs/queue-schema.md`](docs/queue-schema.md) for the entry schema. A reject writes neither —
-nothing is left behind to record. These are Pro features that run free during the 0.x beta (see
-[docs/pro.md](docs/pro.md#beta-pricing-0x)): with no valid license, `add` still writes them, and
-prints a one-line notice above the report instead of skipping them.
-
-`add`/`scan` also accept `--artifact mcp` (plus `add`-only `--mcp-target <file>`/`--force`) to gate
-an MCP server instead of a skill — see [MCP gating](#mcp-gating-v05) below.
-
-### `scan`
-
-```bash
-skill-forge scan owner/name
-skill-forge scan owner/name --json
-```
-
-Runs the same gate pipeline as `add` (profile → safety → overlap → report) but never promotes
-anything — the quarantine sandbox is always cleaned up afterward, on success or failure. Exits
-nonzero when the safety verdict is `block`. `--json` prints the same gate-result payload shape as
-`add`'s. Also accepts `--skill-map <path>` — see `add`'s option table above.
-
-### `evolve` (v0.7)
-
-```bash
-skill-forge evolve .claude/skills/my-skill
-skill-forge evolve .claude/skills/my-skill --yes
-skill-forge evolve .claude/skills/my-skill --dry-run
-skill-forge evolve .claude/skills/my-skill --backend claude --yes
-```
-
-Pro (free during the 0.x beta). Orchestrates [microsoft/SkillOpt](https://github.com/microsoft/SkillOpt)'s
-`skillopt-sleep` CLI (`pip install skillopt`) to propose a self-evolution of an already-installed
-skill — harvest recent sessions, generate a candidate replacement `SKILL.md`/`CLAUDE.md`, and stage
-it — then runs the **staged proposal**, never the live skill, back through skill-forge's own static
-safety ruleset before you decide anything. SkillOpt-Sleep's own validation gate is score-only; it
-never content-vets the generated markdown. This closes that gap.
-
-| Option | Effect |
-|---|---|
-| `--project <dir>` | Project dir passed to SkillOpt-Sleep as `--project`. Defaults to cwd. |
-| `--dry-run` | Uses SkillOpt-Sleep's `dry-run` subcommand — report only, nothing staged. |
-| `--backend <name>` | SkillOpt-Sleep backend. Defaults to `mock` (offline, deterministic, no network). |
-| `--lookback-hours <n>` | Hours of session history for SkillOpt-Sleep to harvest. |
-| `-y, --yes` | Skips interactive prompts (the disclosure confirm below, and the promote/hold/reject prompt) and honors the re-gate verdict automatically. |
-| `--json` | Prints the re-gate result as JSON instead of the terminal report. Implies non-interactive, same as `add`'s `--json`. |
-| `--force` | Allows re-adopting a staging dir whose proposed content already matches the live skill (see the double-adopt guard below). |
-
-**Requires `skillopt-sleep` on PATH** — skill-forge never installs it for you. If it's missing,
-`evolve` prints `pip install skillopt` + a docs pointer and exits, rather than attempting an
-auto-install (the same "detect, don't install" discipline the rest of the gate follows).
-
-**Data boundary.** The default `mock` backend is fully offline — harvesting and proposal
-generation both run locally, no session data leaves the machine. Any other backend (`claude`,
-`codex`, `azure_openai`, ...) sends truncated excerpts from harvested sessions and derived tasks to
-the provider you selected; per SkillOpt-Sleep's own docs this is not currently guaranteed to be
-secret-free. `evolve` prints that disclosure and requires either `--yes` or an interactive `y/N`
-confirmation before a non-`mock` run proceeds — `--json` is non-interactive, so a non-`mock` run
-under `--json` without `--yes` is refused rather than silently sending data off-machine.
-
-**Re-gate.** SkillOpt-Sleep only ever *stages* a proposal (`<project>/.skillopt-sleep/staging/<timestamp>/`
-— full replacement files, never auto-adopted). `evolve` copies just `proposed_SKILL.md` (and
-`proposed_CLAUDE.md`, if present) into a fresh temporary directory and runs skill-forge's own
-static safety ruleset over that copy — the same one `add`/`scan` use, at your configured
-`strictness`. `report.json`/`diagnostics.json` (SkillOpt-Sleep's own redacted holdout evidence) are
-never scanned. The result renders through the same terminal report / `--json` shape as `add`/`scan`.
-
-**Decision.** Same promote/hold/reject semantics as `add`: `--yes`/`--json` honor the re-gate
-verdict (a `block` is rejected); otherwise you're prompted.
-
-- **promote** — runs SkillOpt-Sleep's own `adopt --staging <dir>` (which backs up the live file(s)
-  before copying the proposal over them), then records a provenance entry to the target skill's
-  `SOURCES.md` and a pending-ingestion queue entry (`origin: "evolve"`, see
-  [docs/queue-schema.md](docs/queue-schema.md)) so a later ingest pass reviews the evolution rather
-  than an external source.
-- **hold** — leaves the staging dir exactly as SkillOpt-Sleep produced it (its own `status` command
-  still lists it); `report.md` has the full evidence.
-- **reject** — deletes the staging dir.
-
-**Double-adopt guard.** SkillOpt-Sleep's `adopt` has no confirmation of its own, and adopting the
-same staging dir twice overwrites *its* backup — the pre-evolution original would be lost. Before
-adopting, `evolve` refuses (unless `--force`) when the staged proposal is already byte-identical to
-the live skill it would replace, since that's the signature of a staging dir that was already
-adopted once.
-
-### `audit` (v0.8)
-
-```bash
-skill-forge audit
-skill-forge doctor                          # alias
-skill-forge audit --json --report ./audit.md
-skill-forge audit --yes
-skill-forge audit --foundation
-skill-forge audit --handoff
-```
-
-A re-runnable, doctor-style health check over the skill/MCP set you've **already** configured —
-unlike `add`/`scan`, which gate a new candidate before it's installed, `audit` inventories what's
-already there and looks for hygiene issues and consolidation/refinement opportunities. Requires a
-real, saved config (`skill-forge init` first) — it never silently audits an invented default.
-`init` now ends by offering to run it (see [`init`](#init) above); it's equally safe to run any
-time on its own.
-
-| Option | Effect |
-|---|---|
-| *(none)* | Interactive: offers to capture/reuse a business profile, then runs the audit, then offers the foundation scaffold and agent handoff. |
-| `--json` | Prints the full audit report as JSON instead of the terminal summary. Non-interactive — skips the business-profile prompt. |
-| `-y, --yes` | Skips every interactive prompt (business profile, foundation, handoff). Never implies `--foundation` or `--handoff`. |
-| `--report <file>` | Write the report here instead of the default `~/.skill-forge/reports/audit-<ISO-timestamp>.md`. Refuses an existing path — never overwrites. |
-| `--foundation` | The one skills-root write this command can make: scaffold a `business-foundation` skill from the captured business profile (see below). |
-| `--handoff` | Hand the written report off to your configured coding agent with the bundled curation prompt, via the same handoff plumbing as `add --ingest`. |
-
-**What it inventories/checks.** Every configured `skillsRoots` entry — symlink-aware, deduped by
-realpath so a skill reachable via two roots or an aliased symlink is reported once, with alias
-locations kept rather than dropped. Per skill: strict frontmatter validation (a missing/unclosed
-fence or missing `name`/`description` is a finding, not silently backfilled), `SKILL.md` size and
-an estimated token count, and a full `scanSafety` pass — the same safety ruleset `add`/`scan` run.
-Every configured `mcpTargets` file: JSON targets get full server enumeration (name, command
-basename, package spec, arg/env **counts** — never values); TOML targets (e.g. Codex CLI's
-`config.toml`) get the same textual MCP safety scan `--artifact mcp` uses, since there's no
-structured TOML enumeration. A per-item failure (unreadable skill, broken symlink, malformed MCP
-config) becomes a finding — it never aborts the run.
-
-**Accepted findings (v0.12).** Every finding in the report carries a fingerprint
-(`(fp a1b2c3d4e5f6)`); `Findings` shows **active** findings only, and a separate
-**Accepted findings** section lists whatever you've reviewed and accepted via
-[`skill-forge finding accept`](#finding-v012) — permanently, with reason and date, even after it
-stops matching (see that section for the full contract). `summary.acceptedCount` and each
-finding's `fingerprint` are additive `--json` fields; nothing accepted is ever silently deleted.
-
-**Opportunity pass.** Beyond hygiene, the report surfaces:
-
-- **Overlap clusters** (Pro, free during the 0.x beta) — cross-root overlap scoring across every
-  inventoried skill, grouped into connected components, each with a top pairwise score and a
-  suggested verb code (`ABSORB`/`FORK`/`DEFER` — `opportunities.overlapLocked` in `--json` output
-  says whether this ran or was Pro-locked, without string-matching `notices`). The fuller
-  five-verb matrix (adding `REJECT`/`WATCH`) belongs to the agent-side curation prompt's deeper
-  decide pass (`--handoff`), not this report. Locked → that section shows the standard upgrade
-  notice and empty clusters; everything else in the report still runs.
-- **Evolve-eligible skills** — structurally valid, safety-passing skills, labeled as eligible for
-  `skill-forge evolve` — an eligibility list, not a judgment that they need refining.
-- **A business-foundation opportunity** — offered whenever `config.foundationSkillPath` isn't set
-  yet.
-
-**Business profile.** Interactive runs (never under `--yes`/`--json`/non-TTY) open with a
-business-name/industry/audiences/workflows/constraints Q&A, preceded by an explicit "don't enter
-credentials or confidential customer data" warning. An existing stored profile is offered for
-reuse rather than re-asked, and a fresh capture is shown back as a summary before it's saved to
-`config.businessProfile`. This profile grounds both the foundation scaffold and the curation
-handoff prompt.
-
-**Report location + privacy.** Written to `~/.skill-forge/reports/audit-<ISO-timestamp>.md` by
-default (`--report <file>` to override), created with `{ flag: 'wx', mode: 0o600 }` — exclusive
-create (refuses to overwrite an existing report) and owner-only permissions. MCP `env` values and
-arbitrary arg values are never written into the report or the `--json` payload — only server/
-command names, package specs, and counts.
-
-**Explicit opt-ins.** `--foundation` is the *only* way this command writes to a skills root: it
-scaffolds `<targetRoot>/business-foundation/SKILL.md` from the captured business profile
-(containment-checked against `config.skillsRoots`, refuses an existing or symlinked destination,
-writes atomically, and runs `scanSafety` on the generated content before it's placed), then
-records the path to `config.foundationSkillPath`. `--handoff` is the *only* way this command
-launches an agent — same argv-array, no-shell discipline as `--ingest` (see
-[Ingestion handoff](#ingestion-handoff---ingest)), using the bundled `assets/curation-prompt.md`
-in place of `ingest-prompt.md`. `--yes` (and `init --defaults`, which passes it through) never
-implies either — a non-interactive run writes only the report and, if a profile was already
-stored, the config; nothing else.
-
-### `finding` (v0.12)
-
-```bash
-skill-forge finding accept <fingerprint-prefix> --reason "Funnel genuinely needs root; verified"
-skill-forge finding revoke <fingerprint-prefix>
-skill-forge finding list [--stale] [--json]
-```
-
-Acknowledge an `audit` finding you've reviewed and accepted, so it stops counting against
-`routine --fail-on` and the `add`/`scan` advisory while staying **permanently visible** in its own
-report section — an audit you can't triage decays into noise, and noise is how the one real
-finding gets skimmed. Every finding in an `audit`/`routine` report now carries a 12-char
-fingerprint (`(fp a1b2c3d4e5f6)`) you copy into `accept`/`revoke`.
-
-| Command | Effect |
-|---|---|
-| `finding accept <fp-prefix> --reason <text>` | Records an acceptance. Re-runs the read-only audit engine to resolve the prefix against what's **currently active** — you can only accept a finding that exists right now, never from a stale report. `--reason` is mandatory (1-200 chars, no control characters). |
-| `finding revoke <fp-prefix>` | Removes a stored acceptance so the finding reports again. Resolves against the **store**, not a fresh audit run — the target may no longer be producible, which is exactly when you'd want to clean up. |
-| `finding list [--stale] [--json]` | Lists every accepted finding (severity, rule, target, reason, accepted date, fingerprint). `--stale` filters to records whose target no longer exists on disk. |
-
-**Identity is content-derived, not a name you pick.** A finding's fingerprint is
-`sha256(severity + rule + target + the offending line's text)` — deliberately excluding the LINE
-NUMBER (drifts on unrelated edits) and deliberately including SEVERITY (so a rule re-tuned to a
-higher severity for the same content can't inherit an ack minted against the lower one). Any change
-to the offending content **fails open to re-reporting** — this is the design, not a bug: the
-alternative (key on rule+path only) is the classic baseline trap, where accepting one benign line
-silently suppresses every future line the same rule matches in that file. Full contract, the
-per-rule `context` table, and fail-open read semantics: see
-[docs/accepted-findings-schema.md](docs/accepted-findings-schema.md).
-
-**Severity-capped, human-only, no override.** `finding accept` refuses `HIGH`/`CRITICAL` findings
-outright — there is no `--force`. The precision problem this command exists to solve lives at
-`LOW`/`MEDIUM`; a `HIGH` false positive is a rule bug to fix, not something to baseline. This is a
-human-door CLI (`config set` model), not the agent-facing propose/review queue — both
-`assets/ingest-prompt.md` and `assets/curation-prompt.md` instruct agents to never run
-`finding accept`/`finding revoke` themselves; an agent that judges a finding a false positive says
-so in its summary and lets the user run the command.
-
-**Never a gate input.** Acceptances only ever affect `audit`'s own report classification (and,
-downstream, `routine --fail-on` and the `add`/`scan` advisory) — `add`/`scan`/`promote <id>`/
-`evolve`'s re-gate never reads the accepted-findings store. See
-[docs/gate-policy.md](docs/gate-policy.md#accepted-findings-v012).
-
-### `organize` (v0.9, Pro)
-
-```bash
-skill-forge organize
-skill-forge organize --json
-skill-forge organize --out ./registry.json
-skill-forge organize --usage-snapshot ./skill-monitor-snapshot.json
-```
-
-Pro (free during the 0.x beta). Builds a set-level view across every configured `skillsRoots`
-entry: a **capability registry** (per-skill row — `tier`/`domain`/`consumes`/`provenance`/
-`maturity` frontmatter, plus untagged/rot flags) and a **dependency graph** (nodes, `consumes`
-edges, orphans, hot resources, dangling edges, cycles). This is the TS port of the plugin's
-`index_skills.py` + `build_dependency_graph.py`, merged into one command — graph nodes are keyed
-by realpath-qualified stable IDs (not bare frontmatter names), so duplicate names across roots
-don't collapse adjacency; duplicate-name ambiguity and unresolved `consumes` targets are reported
-rather than silently dropped.
-
-| Option | Effect |
-|---|---|
-| `--json` | Print the registry + graph as JSON instead of the terminal summary. |
-| `--out <file>` | Write the full report JSON to this path. Refuses an existing path (`wx`, `0o600` — same discipline as `audit --report`). |
-| `--usage-snapshot <file>` | Join per-skill usage counts from a skill-monitor snapshot JSON (`usage_joined` in the output); a zero-match snapshot is warned about, not silently ignored. |
-
-`organize` performs its own self-contained scan — it does not reuse `audit`'s inventory walker
-— and, like every other command, never executes anything found under a scanned skills root.
-
-### `find` (v0.9, free)
-
-```bash
-skill-forge find "pdf form filling"
-skill-forge find "pdf form filling" --limit 20 --json
-skill-forge find --audit owner/skill-name
-skill-forge find --get owner/skill-name
-skill-forge find --curated
-```
-
-Free. TS port of the plugin's `skills_sh.py` — discovery only, exactly one mode per invocation
-(search, `--audit`, `--get`, or `--curated`; mutually exclusive):
-
-| Mode | Effect |
-|---|---|
-| `<query>` (default) | Search skills.sh; each result shows id, install count, and the install hint `skill-forge add <id>` — **not** `npx skills add`, since `add` runs the full local quarantine/gate. |
-| `--audit <id>` | Partner security-audit verdicts (Socket, Snyk, Gen Agent Trust Hub, …) for a specific skills.sh id — pass/warn/fail + risk. No auto-audit of search results. |
-| `--get <id>` | Detail + file tree for a specific skills.sh id. |
-| `--curated` | List skills.sh's curated skills. |
-| `--limit <n>` | Max search results (default 10). |
-| `--json` | Print the raw API payload as JSON. |
-
-Search results are labeled **unvetted** — `find` never installs or gates anything itself. Think
-of `find --audit` as the partner-verdict layer and `add`/`scan` as the deep local gate; they're
-two independent checks, not a replacement for one another.
-
-**Auth: `VERCEL_OIDC_TOKEN`.** All requests are HTTPS GETs to `https://skills.sh/api/v1`, using a
-bearer token read from `process.env.VERCEL_OIDC_TOKEN` — never stored in config, never printed.
-Without it, `find` fails loud (exit code 3) with setup guidance:
-
-```
-1. skills.sh authenticates with a short-lived Vercel OIDC token
-2. npm i -g vercel && vercel link && vercel env pull   (writes VERCEL_OIDC_TOKEN to .env.local)
-3. export VERCEL_OIDC_TOKEN from .env.local into your shell before running this command
-   (or set it directly: export VERCEL_OIDC_TOKEN=...)   —   docs: https://skills.sh/docs/api
-```
-
-Note step 3: `vercel env pull` writes the token into `.env.local`, it does not export it into your
-shell — you (or your shell's dotenv loader) still need to export it before `find` can see it.
-
-### `watch` (v0.9, Pro)
-
-```bash
-skill-forge watch
-skill-forge watch --offline
-skill-forge watch --json
-skill-forge watch --skill-map generated/skill-map.static.json
-```
-
-Pro (free during the 0.x beta). TS port of the plugin's `record_provenance.py --check-drift`.
-Scans **every** configured `skillsRoots` entry's `SOURCES.md` provenance ledger (deduped by
-realpath, each reported row names its ledger) and reports, per tracked entry, whether the
-recorded upstream ref still matches what the source currently resolves to.
-
-For entries whose `Source` parses as a git URL and whose `Upstream ref` looks like a commit/tag,
-`watch` runs a fixed, first-party `git ls-remote <url> [ref]` (argv array, no shell) to compare —
-`--offline` skips all network checks and just lists entries for manual comparison. Every other
-entry is listed for manual checking regardless.
-
-**`watch` NEVER executes a ledger's stored drift-check command string.** That string is
-attacker-influenceable data — anyone who can write to a skills root's `SOURCES.md` controls it.
-It is only ever printed, sanitized, as a suggestion for you (or an agent) to run yourself.
-
-**`--skill-map <path>` (Phase 4 of `rhize-plugins`' skill-map-graph-substrate plan)** additionally
-drift-checks every `fork-of` edge in a generated skill map: for each edge it resolves the local
-`skill` node's `path`/`contentHash` and the upstream (`external`) node's `url`/`path`, fetches or
-reads the upstream content, and compares content hashes. Same never-execute posture as the ledger
-check above: nothing derived from the map — including a fork-of edge's own `driftCheck`
-metadata — is ever executed; only fetch/read/hash/compare. A missing/unreadable map is a warning,
-never fatal. A node's repo-relative `path` (e.g. `rhize-context-manager/skills/x/SKILL.md`) is
-resolved against cwd, the map's own directory, and that directory's parent (in that order) — not
-cwd alone — so `watch --skill-map <path>` gives correct verdicts regardless of the directory you
-run it from.
-
-**Verdict**, per fork-of edge — three-way comparison, four verdict states when both hashes below
-are present on the map, else the older two-way fallback (`in-sync`/`drifted`, `contentHash` vs
-freshly-fetched upstream):
-
-| local-normalized vs baseline | upstream-now vs baseline | status | actionable |
-|---|---|---|---|
-| == | == | `in-sync` | no |
-| != | == | `local-only` | no (deliberate fork divergence, e.g. Rhize's added frontmatter) |
-| == | != | `upstream-moved` | yes |
-| != | != | `diverged` | yes |
-
-The three-way matrix fires only when the local `skill` node carries `contentHashNormalized` (a
-hash of the file with Rhize-injected frontmatter stripped, computed once by the rhize-plugins
-compiler) **and** the upstream `external` node carries `baselineHash` (the upstream content hash
-as of the last human review, recorded in `rhize-plugins`' SOURCES.md and copied onto the node by
-that compiler — skill-forge never computes or fetches it itself). Either field missing on a given
-edge falls back to the two-way compare for that edge, so older maps keep working. All four
-three-way verdicts — `in-sync`, `local-only`, `upstream-moved`, and `diverged` — carry
-`baselineHash`/`upstreamHash` in the JSON output; the two-way-fallback rows and
-`upstream-unreachable`/`local-missing` never do (no verdict without a successful fetch/read, so
-there is nothing to compare against a baseline). Every row also carries an `actionable` boolean
-(from `isActionable`), so callers don't have to re-derive "needs attention" from `status`/`detail`
-prose — it's `true` for `drifted`, `upstream-moved`, `diverged`, `upstream-unreachable`, and
-`local-missing`; `false` for `in-sync` and `local-only`. **Re-baselining**: after reviewing and
-adopting an `upstream-moved`/`diverged` change, re-run `rhize-plugins`' `scripts/baseline_upstreams.py`
-and commit the updated SOURCES.md — that's the "I reviewed upstream, accept its state" action that
-clears the row back to `in-sync`/`local-only`.
-
-### `ingest` + `queue close` (v0.9, Pro)
-
-```bash
-skill-forge ingest
-skill-forge ingest --list
-skill-forge ingest --list --json
-skill-forge queue close <id> --status ingested
-skill-forge queue close <id> --status dismissed
-```
-
-Pro (free during the 0.x beta). The queue-drain UX for pending ingestions. `ingest` (no args)
-validates every pending `~/.skill-forge/queue.json` entry — each entry's `quarantinePath`/`installedPath` must
-canonicalize under the configured quarantine dir or a configured skills root/MCP target;
-mismatched or escaping entries are reported and excluded — then hands the surviving summary off to
-the configured coding agent (same handoff plumbing as `add --ingest`) with `assets/ingest-prompt.md`,
-which now carries the full queue-drain workflow. `--list` is read-only: it prints pending entries
-(`--json` for machine-readable output) without any handoff.
-
-For a single new source, use `skill-forge add <source> --ingest` instead — that runs the full
-quarantine/gate pipeline first; `ingest` only ever drains what's already queued.
-
-`skill-forge queue close <id> --status ingested|dismissed` lets an agent close out a queue entry
-after its decide pass without hand-editing `queue.json` — writes are atomic (temp file + rename).
-
-### `refine` (v0.10, Pro)
-
-```bash
-skill-forge refine --skill my-skill --category hook --override-type patch \
-  --action insert-after --marker "Only check paths" \
-  --content "..." --expected "..." --actual "..." --dry-run
-skill-forge refine list [--status <s>] [--skill <s>] [--project <p>]
-skill-forge refine patterns [--status tracking|ready|generalized|dismissed] [--skill <s>]
-skill-forge refine promote <PATTERN-ID> [--dry-run] [--force] [--user-root <dir>]
-skill-forge refine rollback <backup-id> [--force]
-skill-forge refine which <skill> [--user-root <dir>]
-```
-
-Pro (free during the 0.x beta). Captures, applies, and generalizes improvements to installed
-skills from real usage feedback (see [CLAUDE.md's "refine (v0.10)" section](CLAUDE.md) for the
-full architecture notes, or `docs/refinement-schema.md` for the store shape).
-
-**Capture never mutates a base `SKILL.md`.** `refine` capture/apply writes ONLY project-scope
-override artifacts — `SKILL.patch.md` / `SKILL.extend.md` / `skill-config.json`, or a whole-file
-override copy for `full`/`hook`/`script` override types. The only command that ever touches a
-user-scope base skill is `refine promote`, and only against a `ready` pattern (or with `--force`).
-
-**Override precedence** (configurable roots):
-
-```
-1. PROJECT LOCAL   <cwd>/.claude/skills/<skill>/   highest
-2. PROJECT SHARED  <cwd>/skills/<skill>/
-3. USER SCOPE      first configured skillsRoots entry outside cwd (fallback ~/.claude/skills)
-```
-
-`refine which <skill>` prints this resolution order and which override files exist at each scope —
-the "why didn't my patch take effect" debugging aid, made explicit and read-only. Both `refine
-which` and `refine promote` accept `--user-root <dir>` to override the detected user-scope skills
-root (default: the first configured `skillsRoots` entry outside the current working directory,
-falling back to `~/.claude/skills`) — useful when the config's default root doesn't match the
-skill you're targeting.
-
-**Non-interactive capture contract.** Capture flags: `--skill --category --target --override-type
-<patch|extend|config|full|hook|script|new> --action <append|prepend|replace-section|insert-after|
-insert-before|delete-section> --marker --content <text> --content-file <file> --expected --actual
---example --outcome --root-cause --pattern-id --scope <local|shared> --dry-run --json --yes
---handoff`. `--content` takes override content inline; `--content-file <file>` reads it from a
-file instead (mutually exclusive with `--content`) — use it for anything multi-line rather than
-fighting shell quoting. All seven override types
-are supported: `patch`/`extend`/`config` are rendered from the flags; `full`/`hook`/`script` are
-verbatim override-file writes at project scope (content required); `new` creates an extension file
-for a capability that doesn't exist in the base skill yet. Always run `--dry-run` first and confirm
-the preview before writing for real — `--yes` skips re-prompting for a confirmation already given,
-it does not replace the dry-run preview.
-
-**The judgment step is the agent's job**, same pattern as `--ingest`/`audit --handoff`: a
-bundled `assets/refine-prompt.md` carries the gap-analysis rubric (category/override-type decision
-tables, guided-mode triggers), the patch-action syntax, the pattern-fingerprint/generalization
-criteria, and the verification step. `refine --handoff`
-(opt-in) launches your configured agent with it, same handoff plumbing as `--ingest`; `--yes` never
-implies `--handoff`.
-
-**Pattern tracking and promotion.** A pattern becomes `ready` only when it recurs in a **second,
-genuinely different project** — repeat captures in the same project never flip it (occurrence
-`count` is derived from unique project identities, not raw refinement counts; see
-`docs/refinement-schema.md`). `refine patterns` lists tracked/ready/generalized/dismissed patterns,
-filterable by `--status --skill --project`. `refine promote <PATTERN-ID>` merges a `ready` pattern
-into the user-scope base skill: it backs up affected files first (manifest with per-file sha256 +
-original bytes + mode, tombstones for files that didn't exist), stages the write, validates, then
-renames into place — `--dry-run` previews the diff without writing, `refine rollback <backup-id>`
-restores from the manifest (refusing if current files have drifted since promote, unless
-`--force`). On promote, a `SOURCES.md` provenance entry is appended (verb `DEFER`, notes
-`"generalized from PAT-xxxx via skill-forge refine"`).
-
-**`evolve` vs. `refine`.** Both improve an already-installed skill, but at different scopes and
-triggers: `evolve` (v0.7) is *automated, whole-skill* optimization — it hands the entire skill off
-to SkillOpt-Sleep to propose a fresh replacement, re-gates the proposal, and lets you adopt or
-reject it wholesale. `refine` is *targeted, human/agent-driven* — it captures one specific observed
-gap ("expected X, got Y") and writes the smallest override that closes it, tracked and eventually
-generalized only once the same gap recurs elsewhere. A `refine` patch on top of an `evolve`d skill
-is fine; both record their own provenance entry, so the `SOURCES.md` ledger shows which change came
-from which mechanism.
-
-**Legacy store — deliberate skip, not a migration.** `~/.claude/skill-refinements/` is a legacy
-location some users may have from earlier tooling — three flat markdown notes, no structured
-ledgers, no schema — and there is no migration from it. Files there stay readable in place; if
-anything in them still matters, re-capture it via `skill-forge refine` against the greenfield JSON
-store described in [`docs/refinement-schema.md`](docs/refinement-schema.md). Markdown ledgers like
-`refinement-history/*.md`, `aggregated-patterns.md`, or `generalization-queue.md` are not
-recreated — JSON is the store; `refine list`/`refine patterns` are the human-readable view over it.
-
-**Auto-trigger hooks — templates, not automation.** A CLI cannot hook a running Claude Code
-session, so two auto-trigger hooks ship here as documented templates instead:
-`assets/hooks/refinement-detector.sh` (detects refinement-shaped language in a prompt) and
-`assets/hooks/session-end.sh` (prompts after a substantial session). Both are optional, inert if
-`skill-forge` isn't on `PATH`, and never call `skill-forge` themselves — they only print a
-suggestion. Wire either one in by adding it to your `.claude/settings.json` (or
-`~/.claude/settings.json`) hooks section — the exact snippet is in each script's own header
-comment:
-
-```json
-{
-  "hooks": {
-    "UserPromptSubmit": [
-      { "hooks": [{ "type": "command", "command": "bash /path/to/refinement-detector.sh" }] }
-    ],
-    "SessionEnd": [
-      { "hooks": [{ "type": "command", "command": "bash /path/to/session-end.sh" }] }
-    ]
-  }
-}
-```
-
-**Security invariants** (same regime as v0.8/v0.9): nothing from a skill being refined is ever
-executed. Patch application writes ONLY under the resolved target scope dir for the named skill
-(containment-checked realpath, refuses a symlinked destination file); promotion writes ONLY under
-user scope, backup first. All child processes are argv arrays (git only, for context gathering).
-Control-char sanitization on every untrusted string that lands in human-readable output. `--yes`
-never implies `--handoff`. Applying a patch whose target `SKILL.md` is missing is refused; promoting
-a non-`ready` pattern without `--force` is refused.
-
-### `routine` (v0.11, Pro)
-
-```bash
-skill-forge routine                       # audit + drift + registry, one report, writes nothing else
-skill-forge routine --json --offline      # for a scheduler: one JSON document, no network
-skill-forge routine --fail-on high        # exit 1 when a high/critical finding exists
-skill-forge routine --housekeeping        # opt in to bounded writes (see below)
-```
-
-The whole maintenance pipeline in one command, shaped for cron. Every other command answers one
-question; keeping a set healthy means running four and correlating them by hand, which is exactly
-what nobody does on a schedule. `routine` runs the audit, drift, and registry **engines**,
-correlates them into one report and one summary, and exits with a code a scheduler can alert on.
-
-**Non-interactive by construction** — it never prompts, so it cannot hang a scheduled job. It is
-also the only schedulable command that writes, so what it may write is fenced:
-
-| | writes |
-|---|---|
-| always | the combined report + `audit-state.json`, both under `~/.skill-forge` |
-| `--housekeeping` | prunes quarantine sandboxes older than `--prune-days` (default 30); closes queue entries whose skill is gone from disk |
-| `--handoff` | launches your configured agent with the curation prompt |
-
-Housekeeping and handoff are **opt-in**: a bare `skill-forge routine` in a crontab reports and
-nothing else. A step that was requested but could not run — a crashed drift check, a failed
-prune, an unreadable queue — is listed under **Incomplete steps** and **always exits nonzero**,
-independent of `--fail-on`: `--fail-on` grades what the audit *found*, whereas a degraded run
-means the routine did not do what was scheduled, and a cron job that exits 0 on that is blind. Pruning only ever deletes inside the quarantine dir — never a skills root — is
-age-bounded, `--dry-run`-able, and lists every path in the report. A queue entry is only closed
-when the skill it points at no longer exists; a pending entry whose skill is still installed is
-undone work, not an orphan. `routine` never installs, promotes, or rejects: no candidate enters a
-skills root without a human or agent decision, and a cron job is not that.
-
-**Accepted findings (v0.12)** are honored the same way `audit` honors them: `--fail-on` grades
-**active** findings only, so accepting every remaining finding via `skill-forge finding accept`
-turns a red `--fail-on any` green, and any new or changed finding turns it red again. A
-corrupt/missing accepted-findings store fails open (nothing gets suppressed) and surfaces as a
-report **notice**, never as an "Incomplete step" — see
-[docs/accepted-findings-schema.md](docs/accepted-findings-schema.md).
-
-```
-0 9 * * 1  skill-forge routine --offline --fail-on high --housekeeping
-```
-
-### `promote <id>` / `reject <id>` (v0.11)
-
-Answering **hold** at the gate used to be a dead end: the sandbox sat in quarantine and no command
-could ever finish the decision. These close that loop.
-
-```bash
-skill-forge promote <id>          # re-gate the held sandbox, then promote/hold/reject
-skill-forge reject <id>           # discard it
-```
-
-Works for both artifact types: a held MCP candidate is re-gated as an MCP server and written into
-your MCP config (`--mcp-target`), with env values emptied and unpinned `npx` specs pinned, exactly
-as `add --artifact mcp` would.
-
-Promotion also re-validates the candidate against the state it was gated in: each skill dir must
-still be a real directory rather than a symlink, no symlink inside it may resolve out of the
-sandbox, and its content digest must still match the one captured at gate time. Otherwise the gap
-between "scanned" and "installed" — days, for a hold — is a window in which vetted content can be
-swapped for something that never passed the gate.
-
-`promote` **re-gates** rather than promoting blind. The original run's gate result was never
-persisted, so the alternative would be a queue entry with a fabricated gate record — and a hold
-may be days old, with the ruleset and your installed set since changed. Re-scanning is static and
-cheap. Ids come from `skill-forge list`; anything that resolves outside your quarantine dir
-(traversal, absolute path, symlink) is refused.
-
-### `config` (v0.11)
-
-`businessProfile` is five fixed fields, so anything else learned about you has nowhere to live.
-Preferences are open-ended key/value facts that accumulate without a schema change:
-
-```bash
-skill-forge config set prefers-typescript "strict mode, no any"
-skill-forge config list
-skill-forge config review
-```
-
-**Agents get a different door.** `set` is for a human at a keyboard and takes effect immediately;
-`propose` only ever queues something for review:
-
-```bash
-skill-forge config propose deploys-on vercel --origin "ingest agent" --note "seen in 3 skills"
-```
-
-An agent draining the queue reads untrusted skill content, so anything it concludes about you is
-downstream of text an attacker may have written. If agents could write preferences directly, a
-malicious `SKILL.md` could talk one into persisting an instruction into your config, where every
-later run would read it back as *your stated preference* — a durable prompt-injection foothold
-with a laundering step in the middle. Routing agent writes through review means the worst case is
-a proposal you decline. `review` is interactive, or takes an explicit `--accept-all`/`--reject-all`;
-it refuses to fall through to a default in a non-interactive shell.
-
-Both doors run the same validation: kebab-case keys, a length cap, no control characters, and a
-refusal for anything credential-shaped — by key name (`api-key`, `*-token`) or by value shape
-(`sk-…`, `ghp_…`, `AKIA…`, PEM blocks, JWTs). `config.json` is plain text; secrets belong in your
-keychain. Hand-edited entries that fail those checks are dropped on load rather than rendered.
-
-### `list` / `status`
-
-`list` shows what's currently held in quarantine (installed via `add`, answered "hold", not yet
-promoted or rejected). `status` shows the resolved configuration (skills roots, quarantine dir,
-strictness) plus a count of held entries.
-
-### `guide` (v0.11)
-
-```bash
-skill-forge guide            # what this does, where you are, what to run next
-skill-forge guide verbs      # a single topic
-```
-
-Orientation for someone — or some agent — dropping into an existing session. `--help` lists flags
-but can't tell you what to do with them, and `status` prints configuration without saying what it
-means; `guide` answers "what is my current state, and what is the next command". It reads your
-config, quarantine, and queue and names one next step, unfinished work first: nothing configured →
-`init`; entries awaiting a decide-pass verb → `ingest`; candidates still held → `list`; no audit
-ever run → `audit`.
-
-```
-Where you are:
-  config:      /Users/you/.skill-forge/config.json
-  gate targets: 3 (default: /Users/you/.agents/skills)
-  quarantined: 2
-  queue:       12 pending
-
-Suggested next step:
-  skill-forge ingest
-  12 promoted items still awaiting a decide-pass verb
-```
-
-Topics: `pipeline`, `verbs`, `queue`, `mcp`, `refine`, `maintenance`, `pro`. **Read-only and
-non-interactive** — it writes nothing and never prompts, so it's safe to run inside an agent turn,
-and with no config it says so rather than reciting default placeholder paths as if they were
-settings.
-
-## MCP gating (v0.5)
-
-`add` and `scan` can also gate an **MCP server** instead of a skill — the same quarantine →
-profile → safety scan → overlap analysis → report → promote/hold/reject pipeline, applied to an
-MCP server candidate rather than a skill:
-
-```bash
-skill-forge scan ./my-mcp-server --artifact mcp
-skill-forge add @scope/some-mcp-server --artifact mcp --mcp-target ~/.claude.json
-skill-forge add https://github.com/owner/mcp-server.git --artifact mcp --yes
-```
-
-Pass `--artifact mcp` explicitly — skill-forge never guesses. In particular, an npm package name
-(`@scope/name`, or a bare `some-mcp-server` name) is only treated as an npm source with this flag;
-without it, the same string resolves as a skills.sh `owner/name` slug instead (no ambiguity
-guessing between the two).
-
-**Source forms**
-
-| Form | Example | How it's fetched |
+| Command | Description | Docs |
 |---|---|---|
-| Local directory | `./my-mcp-server` | Copied into quarantine, same as a local skill source. |
-| Git URL | `https://github.com/owner/mcp-server.git` | Shallow-cloned into quarantine, same as a git skill source. |
-| npm package | `@scope/name` or `some-mcp-server` | `npm pack <name> --ignore-scripts --pack-destination <quarantine>`, then tarball **extraction only** — never `npm install`, never lifecycle scripts. Every tarball member path is validated (absolute paths and `..` segments are rejected) before extraction. |
-
-**What's gated**
-
-Safety runs the same built-in deny-pattern ruleset used for skills (curl\|bash, credential-file
-access, etc.) plus MCP-specific rules: inline credential values in config/env (quoted or
-unquoted), unpinned `npx` launch commands — MEDIUM with `-y`/`--yes` (silent install), **LOW
-without it (v0.12)**, since npx still prompts before the first install but the tag floats once
-cached (a moving/dist tag like `@latest` counts as unpinned either way, and `npx` is recognized by
-basename so a full path or `npx.cmd` can't evade it) — `--dangerously-*`/`--no-sandbox` flags, and
-filesystem-root launch args — see the
-[MCP safety ruleset table](docs/gate-policy.md#mcp-safety-ruleset). Overlap analysis (Pro, free
-during the 0.x beta) ranks the candidate against the server entries already present in your
-configured `mcpTargets` files, instead of against a skills root.
-
-**Capability profile (v0.6).** The report also includes a **static** capability summary — tool,
-resource, and prompt counts, plus a `declaredConfidence` (`high`/`partial`/`none`) — parsed from
-the candidate's `package.json`, any shipped `.mcp.json`/manifest, and MCP SDK source-text patterns
-(`server.tool(...)`, `setRequestHandler(ListToolsRequestSchema, ...)`, etc.):
-
-```
-Artifact type       : mcp
-Capabilities        : 2 tools, 1 resource, 0 prompts (declaredConfidence: high)
-```
-
-This is free (it's profiling, not a Pro feature) and **never derived by running the candidate
-server** — anything that can't be determined from source text is reported as undetermined rather
-than discovered by executing it. `--json` includes the full `tools`/`resources`/`prompts` name
-lists under `profile.capabilities`.
-
-**Promote semantics**
-
-Promoting an MCP candidate writes ONE server entry into a target MCP config file's `mcpServers`
-map — it never touches a skills root:
-
-```json
-{ "mcpServers": { "<name>": { "command": "...", "args": ["..."], "env": { "SOME_KEY": "" } } } }
-```
-
-- **Env values are never copied** from the candidate — every declared env var is written as an
-  empty string, and skill-forge prints the var names you need to fill in yourself.
-- **Target resolution:** `--mcp-target <file>`, else `config.mcpTargets[0]`, else `<cwd>/.mcp.json`.
-- **Existing target file:** backed up first to `<file>.bak-<timestamp>`.
-- **Existing same-name server entry:** refused unless `--force` is passed.
-- **Missing target file/parent dirs:** created.
-- A candidate config listing more than one server gates/promotes the first (same "N found — using
-  the first" convention `add`/`scan` already use for a multi-skill source), noted on stderr.
-- **Version pinning is enforced, including on a candidate's own documented entry (v0.7).** A
-  candidate's `.mcp.json` server entry is used for `command`/`args` when present, but an unpinned
-  `npx` spec there (`"args": ["-y", "pkg@latest"]`) is no longer written through as-is: it's
-  **auto-pinned** to `<package>@<version>` when it matches the version skill-forge scanned from the
-  candidate's own (self-declared) `package.json`, or **promotion is refused** (with an explanation
-  and no override flag) when it can't be safely auto-pinned — a different package name, no version
-  found, or a more complex shape (e.g. a `-p`/`--package` dependency, or more than one spec).
-  See [docs/gate-policy.md](docs/gate-policy.md#mcp-promote-version-pin-enforcement-v07).
-
-There's no MCP equivalent of the skill provenance ledger (`SOURCES.md`) — the pending-ingestion
-queue (Pro) and `--ingest` handoff both apply the same way, keyed on the written config file path
-instead of an installed skill directory. The queued entry carries the candidate's static capability
-profile (`capabilities`, v0.6, above), so a `--ingest` handoff run on an MCP promote has real
-material to work with: `assets/ingest-prompt.md` branches on `artifactType: "mcp"` and walks the
-same five-verb decide (DEFER/ABSORB/FORK/REJECT/WATCH) applied to a server instead of a skill —
-compare declared capabilities against what's already configured, then keep/tighten/remove the
-promoted config entry accordingly. Same static-only rule as the CLI's own profiling: the deep pass
-never runs or installs the candidate server to inspect it.
-
-**TOML-format agents: detect-only.** `skill-forge init` detects MCP config files for every known
-agent, including TOML-format ones (Codex CLI's `config.toml`) — they show up in `init`'s MCP-target
-list and can be selected into `config.mcpTargets` for **overlap ranking**. But **promote only
-writes JSON-shaped targets** (`{ "mcpServers": { ... } }`); pointing `--mcp-target` at (or letting
-`config.mcpTargets[0]` resolve to) a TOML file fails when the promote step tries to parse it as
-JSON. Detection/overlap is agent-format-agnostic; writing is JSON-only.
+| `init [options]` | Detect installed agents and set gate targets / handoff agent | [docs/commands/init.md](docs/commands/init.md) |
+| `add <source> [options]` | Quarantine-install a skill and run it through the gate | [docs/commands/add.md](docs/commands/add.md) |
+| `scan <source> [options]` | Gate a skill without installing it (always cleans up) | [docs/commands/scan.md](docs/commands/scan.md) |
+| `evolve <skill-dir> [options]` (Pro) | Self-evolve an installed skill via SkillOpt-Sleep, re-gate, decide | [docs/commands/evolve.md](docs/commands/evolve.md) |
+| `audit [options]` (alias `doctor`) | Doctor-style health check over the configured skill/MCP set | [docs/commands/audit.md](docs/commands/audit.md) |
+| `finding accept\|revoke\|list` | Acknowledge, revoke, or list reviewed audit findings (human-only, no gate effect) | [docs/commands/finding.md](docs/commands/finding.md) |
+| `organize [options]` (Pro) | Set-level capability registry + dependency graph across configured skills roots | [docs/commands/organize.md](docs/commands/organize.md) |
+| `find [query] [options]` | Discover skills via skills.sh and check partner security audits (free) | [docs/commands/find.md](docs/commands/find.md) |
+| `watch [options]` (Pro) | Drift check across every `SOURCES.md` provenance ledger | [docs/commands/watch.md](docs/commands/watch.md) |
+| `ingest [options]` / `queue close <id>` (Pro) | Hand the pending-ingestion queue off to a coding agent for the decide/absorb pass | [docs/commands/ingest.md](docs/commands/ingest.md) |
+| `refine [options]` (Pro) | Capture, list, review, promote, and roll back project-scope skill overrides | [docs/commands/refine.md](docs/commands/refine.md) |
+| `insight <subcommand>` (Pro) | Turn sources into evidence-backed capability plans and Jira manifests | [docs/commands/insight.md](docs/commands/insight.md) |
+| `routine [options]` (Pro) | One scheduled maintenance pass: audit + drift + registry, cron-friendly | [docs/commands/routine.md](docs/commands/routine.md) |
+| `promote <id>` / `reject <id>` [options] | Re-gate and finish a held quarantine decision, or discard it | [docs/commands/promote-reject.md](docs/commands/promote-reject.md) |
+| `config <sub> [args]` | Read/write open-ended preferences (`list`\|`get`\|`set`\|`unset`\|`propose`\|`review`) | [docs/commands/config.md](docs/commands/config.md) |
+| `list` / `status` | List held quarantine entries, or show configuration and quarantine summary | [docs/commands/list-status.md](docs/commands/list-status.md) |
+| `guide [topic]` | Orientation: what this does, your current state, the next command | [docs/commands/guide.md](docs/commands/guide.md) |
+
+`add`/`scan` also gate an **MCP server** instead of a skill via `--artifact mcp` — see
+[docs/mcp-gating.md](docs/mcp-gating.md).
 
 ## Free vs. Pro
 
-| Capability | Free | Pro |
-|---|:---:|:---:|
-| Quarantine install (skills.sh slug / git / local path) | ✓ | ✓ |
-| Profile (name, version, license, structure, MCP/tool deps) | ✓ | ✓ |
-| Safety gate — built-in ruleset + SkillSpector shell-out | ✓ | ✓ |
-| Terminal report + `--json` | ✓ | ✓ |
-| Promote / hold / reject decision | ✓ | ✓ |
-| `init` setup wizard (agent detection, gate targets, handoff agent) | ✓ | ✓ |
-| Overlap analysis against your configured skill set | | ✓ |
-| Provenance ledger (`SOURCES.md` audit trail) | | ✓ |
-| Pending-ingestion queue + `--ingest` handoff | | ✓ |
-| `evolve` — SkillOpt-Sleep self-evolution, re-gating, provenance, queueing (v0.7) | | ✓ |
-| `audit` — inventory, hygiene findings, report, business profile, foundation scaffold (v0.8) | ✓ | ✓ |
-| `audit`'s cross-root overlap clusters (v0.8) | | ✓ |
-| `organize` — set-level capability registry + dependency graph (v0.9) | | ✓ |
-| `find` — skills.sh discovery + partner audit verdicts (v0.9) | ✓ | ✓ |
-| `watch` — provenance drift check across every `SOURCES.md` ledger (v0.9) | | ✓ |
-| `ingest` + `queue close` — pending-queue drain handoff (v0.9) | | ✓ |
-| `refine` — capture/apply/generalize project-scope skill overrides (v0.10) | | ✓ |
-| `finding accept`/`revoke`/`list` — acknowledge audit findings, never a gate input (v0.12) | ✓ | ✓ |
-
 Free is the complete safety gate on its own — quarantine, profile, safety scan, and an explicit
 promote/reject decision, with nothing held back. Pro is the curation layer on top: whether a new
 candidate duplicates something you already have, and an ongoing provenance record across your
@@ -931,73 +93,29 @@ whole skill set rather than a single install-time decision.
 
 **Everything free until 1.0.** This is a 0.x beta build, and the Pro tier's runtime license check
 is intentionally asleep for the whole 0.x line: overlap analysis, the provenance ledger, and the
-pending-ingestion queue / `--ingest` handoff all run for everyone, licensed or not. Without a valid
-license (`SKILL_FORGE_LICENSE` env var or `config.json`'s `licenseKey`, verified offline), `add`
-prints a one-line notice — `Pro feature (...) — free during the 0.x beta; will require a license at
-1.0.` — above the report (or in the `--json` payload's `notices` array) and otherwise runs exactly
-as a licensed run would. At 1.0 the lock re-arms and these features go back to requiring a valid
-key. The set-level organizer and the skills.sh partner-audit enrichment are not yet exposed by any
-CLI command, licensed or not, beta or not. See [docs/pro.md](docs/pro.md) for the per-feature
-implementation status.
+pending-ingestion queue / `--ingest` handoff all run for everyone, licensed or not — `add` prints a
+one-line "free during the beta" notice above the report when no valid license is set, and otherwise
+runs exactly as a licensed run would.
+
+See [docs/pro.md](docs/pro.md#free-vs-pro) for the full Free/Pro capability table and the
+per-feature implementation status.
 
 ## Security model
 
-- **Quarantine-first.** Every source — skills.sh slug, git URL, or local path — is installed into
-  an isolated sandbox (`~/.skill-forge/quarantine/<id>/`) before anything is inspected. Nothing
-  reaches your working skill set without an explicit promote decision.
+- **Quarantine-first.** Every source is installed into an isolated sandbox before anything is
+  inspected — nothing reaches your working skill set without an explicit promote decision.
 - **Built-in safety ruleset, always on, fully offline.** A deny-pattern scan (curl/wget-into-shell,
-  base64-obfuscated exec, reverse shells, recursive force-delete, credential-file access/exfil,
-  dynamic eval, `shell=True` subprocess, persistence via shell rc files or cron, `sudo` usage) runs
-  against every candidate with no external dependency and no network call. See
-  [docs/gate-policy.md](docs/gate-policy.md) for the full rule table.
+  base64-obfuscated exec, reverse shells, credential-file access/exfil, `shell=True` subprocess,
+  persistence via shell rc files or cron, `sudo` usage, and more) runs against every candidate with
+  no external dependency and no network call.
 - **Block on HIGH/CRITICAL.** Any finding at `HIGH` or `CRITICAL` severity blocks the candidate
-  outright (verdict `block`); a lower-severity finding produces `warn`; a clean scan is `pass`.
-  `--yes` honors this: `block` is rejected automatically.
-- **npm-sourced MCP candidates: `--ignore-scripts` + tarball member validation.** An npm-package
-  MCP source is fetched with `npm pack --ignore-scripts`, and the tarball's member list is checked
-  with `tar -tzf` before extraction — any absolute path or `..` path segment refuses the extract
-  with an error instead of running `tar -xzf` (a path-traversal guard against a malicious tarball
-  writing outside the quarantine sandbox).
-- **SkillSpector, when installed.** If [SkillSpector](https://github.com/NVIDIA/SkillSpector)
-  (Apache-2.0) is on `PATH`, skill-forge shells out to it (`--no-llm` by default, so scanned skill
-  content is never sent to an external LLM provider) and merges its findings into the same report.
-  Purely additive — its absence never blocks the gate.
-- **skills.sh partner audits — implemented, not yet wired into the CLI pipeline.** skill-forge
-  ships a client for skills.sh's documented `/api/v1/skills/audit` endpoint (partner verdicts from
-  Socket, Snyk, Gen Agent Trust Hub, Runlayer, ZeroLeaks), gated on a user-supplied
-  `VERCEL_OIDC_TOKEN`. The client exists (`src/gate/skillsSh.ts`) but `add`/`scan` do not call it
-  yet in this build — see [docs/gate-policy.md](docs/gate-policy.md) for current status.
-
-## Ingestion handoff (`--ingest`)
-
-`skill-forge` deliberately doesn't try to decide *what to extract* from a skill worth adopting —
-that deeper judgment (which patterns to keep, whether to absorb into an existing skill vs. fork a
-new one, verifying the result beats baseline) is a job for a coding agent, not the gate. `--ingest`
-hands a promoted skill off to one, running the bundled, agent-neutral prompt at
-`assets/ingest-prompt.md` — works with any agent. ABSORB extractions from an ingest pass route
-through `skill-forge refine` in this same package — see [`refine`](#refine-v010-pro) above and
-[docs/forge-workflow.md](docs/forge-workflow.md).
-The same flag works on an MCP server promote (`--artifact mcp --ingest`, v0.6): the bundled prompt branches on the
-queue entry's `artifactType` and runs the matching decide pass — see
-[MCP gating](#mcp-gating-v05) above.
-
-```bash
-skill-forge add owner/name --yes --ingest
-```
-
-The command that gets run, in order:
+  outright; a lower-severity finding produces `warn`; a clean scan is `pass`.
+- **npm-sourced MCP candidates:** fetched with `--ignore-scripts`, and every tarball member path is
+  validated before extraction (a path-traversal guard).
+- **SkillSpector, when installed,** is purely additive — its absence never blocks the gate.
 
-1. `config.handoffCommand` — an argv-style template (`["claude", "-p", "{prompt}"]`-shaped) set by
-   `skill-forge init`'s "handoff agent" prompt, with `{path}` (the installed skill) and `{prompt}`
-   (the bundled prompt file) substituted in. Never shell-parsed, so it's safe even if a substituted
-   path contains shell metacharacters.
-2. Otherwise, the first known agent binary found on `PATH` (`claude`, `codex`, `cursor-agent`,
-   `windsurf`, `opencode`, `gemini`), invoked generically with the prompt.
-3. Otherwise, skill-forge prints the prompt path and skill path for you to hand off yourself.
-
-Every promote or hold is recorded to the pending queue (`~/.skill-forge/queue.json`) regardless of
-`--ingest` — nothing is lost if you skip the handoff. See [`docs/queue-schema.md`](docs/queue-schema.md)
-for the entry schema.
+See [docs/security-model.md](docs/security-model.md) for the full rule table and current status of
+each check.
 
 ## Configuration
 
@@ -1049,6 +167,18 @@ the provenance ledger, and the pending-ingestion queue / `--ingest` handoff all
 with a one-line "free during the beta" notice if no valid key is set. See
 [docs/pro.md](docs/pro.md) for details.
 
+**How do I roll back a customization?**
+It depends what changed. If `skill-forge init` gave a skills root a Git baseline (or you'd already
+committed it yourself), rolling back a change under that root is ordinary Git —
+`git checkout -- <path>` or `git reset`, run by you; skill-forge doesn't ship its own rollback for
+that. `refine rollback <backup-id>` is different and narrower: it only undoes a `refine promote`
+(a base-skill update recorded by `skill-forge refine`), not a Git commit or anything else. See
+[Git preflight](docs/commands/init.md#git-preflight-v016) and
+[`refine`](docs/commands/refine.md) for both.
+
+**Where's the full documentation?**
+See the [docs index](docs/README.md) for every command reference and background doc.
+
 ## License
 
 skill-forge is open-core with a split license (as of v0.2.0):
@@ -1058,7 +188,8 @@ skill-forge is open-core with a split license (as of v0.2.0):
 - **Pro modules — Rhize Commercial License.** `src/license.ts`, `src/gate/overlap.ts`,
   `src/provenance.ts`, `src/queue.ts` (overlap analysis, provenance ledger, pending
   queue / `--ingest` handoff), and `src/refine/` (v0.10 — capture/apply/generalize skill
-  overrides). The source is available to read and audit, but production use of Pro
+  overrides), plus `src/insights/` (source studies, evidence validation, inventory mapping,
+  plans, and Jira manifests). The source is available to read and audit, but production use of Pro
   functionality requires a license key — see [LICENSE-COMMERCIAL](LICENSE-COMMERCIAL).
 
 [LICENSE](LICENSE) is the authoritative map of which files fall under which license.