agent-skillboard 0.1.2 → 0.2.2

package/README.md

@@ -1,669 +1,198 @@
 # SkillBoard
 
-Know which agent skills can run before they run.
+Use the right AI-agent skills without managing another checklist.
 
-SkillBoard is a policy and visibility layer for AI coding-agent skills. It is
-for developers who already have skill folders, plugins, MCP tools, hooks, or
-marketplaces, but still cannot answer the operational question that matters
-most:
+Ask your AI normal questions: "what skills can you use?", "which skill should
+write tests first?", or "can you make this reviewed skill available here?"
+SkillBoard runs behind the scenes so you get the benefit: the right allowed
+skill, a short disclosure of what was used, and fewer setup interruptions.
 
-> Which skills can run in this workflow, why, and what breaks if I remove one?
+The burden stays low:
 
-SkillBoard separates "installed" from "allowed". A skill can be present in a
-repository without being eligible for model invocation. Workflows choose the
-active pool, automatic invocation is denied by default, and the reconciler turns
-skill or harness drift into safe defaults plus a short list of decisions that
-actually need user approval.
+- No global install is required; use `npx --yes --package agent-skillboard`.
+- Most use is read-only: `brief`, `route`, `doctor`, and `guard use` answer
+  what is safe now.
+- Nothing changes until you approve a policy action.
+- Project cleanup is conservative and previewable with `skillboard uninstall --dry-run`.
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/NyXXiR/skillboard/main/skillboard.png" alt="SkillBoard architecture diagram: sources, inventory scanner, SkillBoard model, policy engine, and user and agent surfaces." width="100%">
-</p>
+Status: public alpha. The current config schema is config schema v1; breaking
+changes may still happen before `1.0.0` and are documented in release notes.
 
-## The Problem
+Under the hood, SkillBoard is workflow-scoped skill policy and routing for AI
+agents. It separates `installed` from `allowed`, checks workflow policy and
+guard state before use, and leaves a clear record of which skill influenced the
+answer.
 
-You installed a few agent skill packs.
+Start with normal requests:
 
-Now every repository has a growing pile of `SKILL.md` files, plugin-provided
-tools, hooks, MCP servers, and workflow rules. Before an agent starts working,
-you still need to know:
+- "What skills can you use in this project?"
+- "Which skill should you use to write tests first?"
+- "Can you make `anthropic.docx` available for this workflow?"
+- "Why is this skill blocked?"
 
-- Which skills are merely installed?
-- Which skills are allowed to run in this workflow?
-- Which skills can be invoked automatically?
-- What changes if I disable one?
-- Did a plugin or runtime update silently add new capabilities?
+Your AI runs SkillBoard behind the scenes, reads the current brief, checks the
+guard automatically before invoking an allowed skill, and asks only before
+policy-changing actions. For already-allowed skills, it should say which skill
+it is about to use and which skill it used, not interrupt you for another
+approval. That disclosure is an audit trace, not a permission prompt. You do
+not need to memorize the SkillBoard command loop.
 
-SkillBoard turns that mess into an explicit skill map.
+A normal allowed-skill turn can look like this:
 
-## What SkillBoard Gives You
+- You: "Which skill should you use to write tests first?"
+- AI: "I will use matt.tdd for this request."
+- AI: "I used matt.tdd for this request."
 
-- A skill inventory that separates installed from active.
-- Workflow-scoped allowlists for automatic invocation.
-- Quarantine for newly discovered skills.
-- Impact reports before disabling or migrating skills.
-- Agent bridge files so Codex and Claude Code follow the same policy.
-- An AI-facing brief so agents can explain availability without guessing from
-  raw `SKILL.md` files.
+Names you may see in setup and logs:
 
-## Demo
+- `SkillBoard`: the product and policy model.
+- `agent-skillboard`: the npm package.
+- `skillboard`: the CLI binary.
 
-```bash
-skillboard init
-skillboard doctor
-skillboard brief --json --workflow codex-night-workflow
-skillboard list skills --workflow codex-night-workflow
-skillboard can-use matt.tdd --workflow codex-night-workflow
-skillboard impact disable matt.tdd
-```
-
-Example dashboard output:
+Use SkillBoard when your agent setup has grown beyond one trusted skill folder
+and you want workflow-scoped control without turning skill governance into a
+manual checklist. If you are changing routing, brief, bridge, policy, or
+workflow UX, read [AI Skill Routing Goal](docs/ai-skill-routing-goal.md) first;
+it defines the non-blocking `observe → route → work → explain briefly → ask
+after → remember policy` loop that development should preserve.
 
-```markdown
-## Skills
+<p align="center">
+  <img src="https://raw.githubusercontent.com/NyXXiR/skillboard/main/skillboard.png" alt="SkillBoard architecture diagram: sources, inventory scanner, SkillBoard model, policy engine, and user and agent surfaces." width="100%">
+</p>
 
-- `private.tdd-work-continuity` — active, manual-only, local, owner: `user.local`
-- `matt.tdd` — active, workflow-auto, exported, owner: `github.mattpocock.skills`
-- `vendor.experimental-review` — quarantined, blocked, vendor, owner: `new.runtime.bundle`
+## Why Not Just List `/skills`?
 
-## Reconcile Plan
+A raw skill list answers what is declared. SkillBoard answers what can safely
+run now.
 
-- quarantine new skills until a workflow explicitly opts in
-- report workflows affected before a skill or harness is disabled
-```
+Same fixture, different answer:
 
-## Why This Exists
-
-Agent skill tooling is moving fast. `skillshare` is good at syncing skills across
-agent targets. Microsoft APM focuses on reproducible agent context from a
-manifest and lockfile. Security scanners such as SkillGate/SkillGuard focus on
-trust and risk.
-
-SkillBoard is deliberately narrower:
-
-- Deny automatic invocation by default.
-- Activate skills per workflow, not globally.
-- Separate installed, active, manual-only, router-only, workflow-auto, blocked,
-  and deprecated states.
-- Quarantine newly discovered skills instead of auto-enabling them.
-- Treat harness additions/removals as migration events, not silent breakage.
-- Track capabilities so workflows can depend on roles instead of only skill ids.
-- Track install units so plugin bundles, package-manager dependencies, harnesses,
-  MCP servers, hooks, agents, and LSPs are not flattened into skill names.
-- Keep user-added global skills limited to explicit `global-meta` skills such as
-  routers, impact analyzers, and verification gates.
-- Show a human-readable skill map before users add or remove skills.
-- Report impact before disabling a skill.
-
-## MVP Status
-
-This repository is an early CLI-first foundation. It currently supports:
-
-- YAML policy config parsing.
-- Recursive `SKILL.md` discovery.
-- Source-profile import for cloned or installed skill repositories.
-- Capability and harness config parsing.
-- Agent runtime install-unit inventory, including Codex plugin skills, hooks,
-  MCP servers, commands, and modified config files when manifest metadata is
-  available.
-- Strong reference checks for workflows, skills, capabilities, harnesses, and
-  install units.
-- Semantic policy checks for workflow-scoped auto invocation, canonical skill
-  claims, conflicts, status/invocation combinations, and install-unit component
-  declarations.
-- Markdown dashboard generation.
-- Disable-impact analysis.
-- Reconcile plan generation for new skills, new harnesses, and removed
-  harnesses.
-
-## 5-Minute Quick Start
+| Raw skill list | SkillBoard brief |
+| --- | --- |
+| `matt.tdd active workflow-auto` | `AI can use now: 0` |
+| no policy health | `Blocked for safety: 8`, `Policy errors: 2` |
 
-Run SkillBoard in the project you want to manage:
+That gap is the product. SkillBoard separates `installed` from `allowed`,
+checks policy health, and gives agents a brief they can use without guessing
+from raw `SKILL.md` files. The same proof also routes "write tests before
+implementation" to `matt.tdd`, returns `private.tdd-work-continuity` as the
+fallback, and gives the AI exact start and finish disclosure text.
 
-```bash
-npx agent-skillboard init
-npx agent-skillboard --version
-npx agent-skillboard brief
-npx agent-skillboard doctor --summary
-```
+See [Tested Value Proof](#tested-value-proof) for the executable proof.
 
-The first command creates the local control-plane files for the current
-directory. To manage another project from elsewhere, pass `--dir`:
+## 5-Minute Quick Start
 
-```bash
-npx agent-skillboard init --dir /path/to/your/project
-npx agent-skillboard brief --dir /path/to/your/project
-npx agent-skillboard doctor --dir /path/to/your/project --summary
-```
+Ask your AI to set up SkillBoard in the project you want to manage. The AI runs
+SkillBoard behind the scenes, then answers from the generated brief instead of
+from memory or raw skill files.
 
-SkillBoard does not make installed skills automatically callable. It imports
-trusted local skills as manual-only and keeps runtime/plugin skills quarantined
-until reviewed.
+Use without a global install:
 
-For CI or scripts, the explicit package form avoids ambiguity about the binary
-name:
+AI/automation/operator details:
 
 ```bash
 npx --yes --package agent-skillboard skillboard init
-npm exec --yes --package agent-skillboard -- skillboard init
-```
-
-Then check the project:
-
-```bash
-npx --yes --package agent-skillboard skillboard doctor
-```
-
-For repeated local use, install the CLI globally:
-
-```bash
-npm install -g agent-skillboard
-skillboard init
-skillboard doctor
-```
-
-Unreleased GitHub builds are available for testing changes before npm release:
-
-```bash
-npx --yes --package github:NyXXiR/skillboard skillboard init
-npx --yes --package github:NyXXiR/skillboard skillboard brief
-npx --yes --package github:NyXXiR/skillboard skillboard doctor --summary
-```
-
-For development from a clone, run the source-tree CLI:
-
-```bash
-git clone https://github.com/NyXXiR/skillboard.git
-cd skillboard
-npm install
-npm test
-node bin/skillboard.mjs init --dir /path/to/your/project
-node bin/skillboard.mjs brief --dir /path/to/your/project
-node bin/skillboard.mjs doctor --dir /path/to/your/project --summary
-```
-
-Most examples below use the global or npm-exec `skillboard` command. When
-running from a clone, replace `skillboard ` with `node bin/skillboard.mjs `.
-
-Useful first commands:
-
-```bash
-skillboard inventory refresh --dry-run
-skillboard import --profile github.mattpocock.skills --source-root /path/to/mattpocock-skills
-skillboard import --profile github.mattpocock.skills --source-root /path/to/mattpocock-skills --config skillboard.config.yaml --merge --dry-run
-skillboard check --config skillboard.config.yaml --skills skills
-skillboard rollout audit --config skillboard.config.yaml --skills skills --json
-skillboard rollout plan --config skillboard.config.yaml --skills skills --json
-```
-
-`skillboard init` creates `skillboard.config.yaml`, `skills/`,
-`.skillboard/reports/`, `.skillboard/profiles/`, `AGENTS.md`, and `CLAUDE.md`.
-It also scans known local agent skill roots, including Codex user/system skills,
-Codex plugin-cache manifests, Claude user skills, Hermes user skills, and Hermes
-profile skills under `.hermes/profiles/*/skills`. Trusted user-local skills are
-imported as `status: active` with `invocation: manual-only` and attached to a
-generated local manual workflow when the project has no workflow metadata yet,
-so a first-time user can immediately use their own manual skills through
-`can-use` and guard checks without receiving legacy-state warning noise. System,
-plugin, and other runtime-supplied skills stay `quarantined` / `blocked`; plugin
-hooks, MCP servers, commands, and modified config files are attached to the
-owning install unit for review. The agent bridge files tell Codex-style and
-Claude Code agents to use `skillboard.config.yaml` as the control-plane source
-of truth instead of treating every installed `SKILL.md` as active.
-
-When you ask an agent "what skills can you use?", the bridge tells it to run
-`skillboard brief --json` before answering. The brief is designed for
-AI-mediated use without becoming another policy engine: it summarizes "What
-your AI can use now", what needs your decision, what is blocked for safety, and
-which change suggestions are available as action cards. Reviewable items should
-feel like a short decision queue, not repeated blocked chores: once the source,
-skill, and workflow decision is recorded, the same prompt should not return
-unless that input changes. Before an agent applies a risk-bearing action card,
-it should pick one current action id from the brief, ask for user confirmation,
-then use
-`skillboard apply-action <action-id> --yes --json` with the same config, skills,
-and workflow options instead of running raw action-card shell text. After a
-mutating `apply-action`, the agent should read the returned post-apply brief
-before answering the next availability question or applying another action.
-`apply-action` re-resolves the current brief, so stale action ids, cached action
-cards, and multi-action batches are refused rather than replayed.
-Immediately before a skill is actually invoked,
-`skillboard guard use ...` remains the final gate.
-The default text brief is compact for large skill sets: it keeps the summary,
-top categories, next safe action, short section previews, and short action
-summaries. Use `skillboard brief --verbose` when you need the full list or
-full copyable command details.
-
-### Hermes System Prompt Bridge
-
-Hermes does not automatically read `AGENTS.md` or `CLAUDE.md`. To make Hermes
-follow the same SkillBoard policy, add a small bridge instruction to the Hermes
-profile or system prompt for the project:
-
-```text
-Use SkillBoard as the source of truth for agent skill availability.
-Before answering what skills can be used, run:
-skillboard brief --json --dir /path/to/your/project
-
-Do not infer availability from installed SKILL.md files. Immediately before
-invoking a skill, run:
-skillboard guard use <skill-id> --workflow <workflow-name> --dir /path/to/your/project
-
-For suggested policy changes, ask the user to approve one current action id,
-then run:
-skillboard apply-action <action-id> --dir /path/to/your/project --yes --json
-```
-
-Replace `/path/to/your/project` and `<workflow-name>` with the project and
-workflow Hermes should operate inside.
-
-Example: overloaded local agent profile
-
-```text
-Scanned installed agent skills: 128
-AI can use now: 123 (0 automatic, 123 manual)
-Needs your decision: 0
-Blocked for safety: 5
-Default brief: 54 lines
-Verbose inventory: 244 lines
+npx --yes --package agent-skillboard skillboard doctor --summary
+npx --yes --package agent-skillboard skillboard brief --workflow <workflow-from-init>
 ```
 
-The point is not to install more skills. The point is to see that installed
-does not mean automatically callable, local skills stay manual-only, and risky
-runtime/plugin skills stay blocked until reviewed.
-
-Run `skillboard doctor` after init to see config health, bridge status, managed
-skill/install-unit counts, policy/source audit summaries, and the default
-uninstall dry-run plan. The default doctor command passes when the workspace is
-usable but has review-needed safe-mode warnings; add `--strict` when those
-warnings should fail automation. Add `--json` when an agent or script needs the
-same information as structured output. `skillboard status` returns the same
-health report for users and agents that prefer a shorter command name.
-
-See [docs/user-flow.md](docs/user-flow.md) for the first-time flow that covers
-adding a local skill, inspecting its influence, activating/blocking it, and
-removing SkillBoard policy references without deleting the underlying
-`SKILL.md`.
-
-Run `skillboard inventory refresh --dry-run` after installing a new local agent
-skill pack, plugin, workflow bundle, or harness. It reuses the same scanner as
-init and reports the text and YAML semantic config change plan. If the project
-has no workflows yet, newly discovered trusted user-local skills are attached to
-a generated manual workflow; if workflows already exist, those skills are kept as
-manual-only candidates and the refresh prints a review note to attach them with
-`skillboard add workflow`. Runtime or external skills remain out of automatic
-use until the source and workflow decisions are recorded. Broken detector
-entries or malformed `SKILL.md` files are reported as scan warnings instead of
-aborting the whole refresh.
-
-Add new local growth paths without hand-editing YAML:
+`init` creates the local control-plane files, scans known local skill roots,
+and writes agent bridge instructions. It prints the workflows it found and a
+copyable workflow-scoped `brief` command. If `init` does not print a workflow,
+run the unscoped `brief` command it prints instead. Trusted user-local skills
+start as manual-only. Runtime, plugin, and external skills stay quarantined
+until their source is reviewed; the brief presents that as a one-time review
+decision, then individual quarantined skills can be activated as manual-only
+workflow skills before any later ask-after preference is recorded. The explicit
+package/binary spelling avoids an extra npx install prompt and keeps the
+`skillboard` executable name clear.
 
-```bash
-skillboard add harness codex --config skillboard.config.yaml --skills skills
-skillboard add workflow daily-workflow --harness codex --skill user.helper --config skillboard.config.yaml --skills skills
-```
-
-When an installer writes runtime settings without a manifest, capture that
-surface explicitly:
+Remove the project bridge when you are done:
 
 ```bash
-skillboard inventory detect --unit acme.runtime --config skillboard.config.yaml --install-output install.log --config-file ~/.codex/config.toml --dry-run
+npx --yes --package agent-skillboard skillboard uninstall --dir /path/to/your/project --dry-run
+npx --yes --package agent-skillboard skillboard uninstall --dir /path/to/your/project
 ```
 
-For fetchable Git sources, refresh the local cache and digest pin before writing
-a lockfile:
+Uninstall preserves local skills and policy files by default, and reports what
+it removed or preserved.
 
-```bash
-skillboard sources refresh --config skillboard.config.yaml --unit github.mattpocock.skills --dry-run
-skillboard sources refresh --config skillboard.config.yaml --unit github.mattpocock.skills
-```
-
-After reviewing an imported install unit, record that decision before activating
-model-selectable skills from it:
-
-```bash
-skillboard review install-unit github.mattpocock.skills --trust-level reviewed --config skillboard.config.yaml --skills skills
-```
+See [docs/install.md](docs/install.md) for global installs, `--dir`, GitHub
+builds, clone-based development, Hermes bridge setup, refresh, and uninstall.
 
-To remove the project bridge safely:
-
-```bash
-skillboard uninstall --dry-run
-skillboard uninstall
-```
-
-`skillboard uninstall` removes only SkillBoard bridge blocks and unchanged
-generated helper files by default. It preserves `skillboard.config.yaml`, local
-skills, reports, and any user content in `AGENTS.md` or `CLAUDE.md`. Add
-`--remove-config` only when you want to delete an untouched default config. Use
-`--reset-config` when you intentionally want to discard the current
-`skillboard.config.yaml` and re-run `skillboard init` from a fresh policy
-lifecycle; local skill files, reports, and generated guard hooks are still
-preserved. Add `--remove-reports` with `--reset-config` when a test reset should
-also discard generated dashboard and impact reports. Add
-`--remove-hooks` with the same reset when you also want to discard the entire
-`.skillboard/hooks/` directory contents and remove the `.skillboard/` directory
-if it has no other content.
-
-Run the bundled examples from the repository root:
-
-```bash
-npm install
-npm run check
-node bin/skillboard.mjs check \
-  --config examples/multi-source.config.yaml \
-  --skills examples/multi-source-skills
-node bin/skillboard.mjs list skills \
-  --config examples/multi-source.config.yaml \
-  --skills examples/multi-source-skills \
-  --workflow codex-night-workflow
-node bin/skillboard.mjs explain private.tdd-work-continuity \
-  --config examples/multi-source.config.yaml \
-  --skills examples/multi-source-skills
-node bin/skillboard.mjs can-use matt.tdd \
-  --workflow codex-night-workflow \
-  --config examples/multi-source.config.yaml \
-  --skills examples/multi-source-skills
-node bin/skillboard.mjs audit sources --verify \
-  --config examples/multi-source.config.yaml \
-  --skills examples/multi-source-skills
-mkdir -p .skillboard/reports
-node bin/skillboard.mjs lock write \
-  --config examples/multi-source.config.yaml \
-  --skills examples/multi-source-skills \
-  --out .skillboard/reports/multi-source.lock.yaml \
-  --replace
-node bin/skillboard.mjs apply-action <action-id> \
-  --workflow codex-night-workflow \
-  --config examples/multi-source.config.yaml \
-  --skills examples/multi-source-skills \
-  --yes --json
-```
-
-For hook action cards, keep `apply-action` as the primary flow:
-`node bin/skillboard.mjs apply-action <action-id> ... --yes --json`. The raw
-hook commands below are underlying manual operator detail for previewing and
-materializing an executable guard hook outside the action-card approval loop:
-
-```bash
-node bin/skillboard.mjs hook install \
-  --workflow codex-night-workflow \
-  --config examples/multi-source.config.yaml \
-  --skills examples/multi-source-skills \
-  --out .skillboard/reports/codex-night-guard.sh \
-  --skillboard-bin "node bin/skillboard.mjs" \
-  --dry-run --json
-node bin/skillboard.mjs hook install \
-  --workflow codex-night-workflow \
-  --config examples/multi-source.config.yaml \
-  --skills examples/multi-source-skills \
-  --out .skillboard/reports/codex-night-guard.sh \
-  --skillboard-bin "node bin/skillboard.mjs"
-```
-
-For manual hook installation, preview with `--dry-run --json` and inspect
-`planned.preview.shell` before an operator materializes the matching non-dry-run
-hook command directly.
-The multi-source example intentionally uses project-root-relative local paths,
-such as `./examples/multi-source-skills/private`, so a fresh clone can run these
-commands without editing machine-specific paths.
-
-## Config Shape
-
-```yaml
-version: 1
-
-defaults:
-  invocation_policy: deny-by-default
-  allow_model_invocation: false
-  require_explicit_workflow: true
-
-skills:
-  matt.tdd:
-    path: tdd
-    status: active
-    invocation: workflow-auto
-    exposure: exported
-    category: engineering
-
-  user.workflow-router:
-    path: user/workflow-router
-    status: active
-    invocation: global-auto
-    exposure: global-meta
-    category: meta
-
-capabilities:
-  test-first-implementation:
-    canonical: matt.tdd
-    alternatives:
-      - meerkat.test-first-implementation
-    default_policy: workflow-auto
-
-harnesses:
-  codex:
-    status: primary
-    workflows:
-      - codex-night-workflow
-
-install_units:
-  lazycodex.omo:
-    kind: harness
-    source: npx lazycodex-ai install
-    scope: user-global
-    manifest_path: ~/.codex/plugins/cache/sisyphuslabs/omo/plugin.json
-    cache_path: ~/.codex/plugins/cache/sisyphuslabs/omo
-    provided_components:
-      - skills
-      - commands
-      - mcp-server
-      - hook
-    components:
-      skills:
-        - lazycodex.ulw-plan
-      commands:
-        - $ulw-plan
-        - $start-work
-      hooks:
-        - post-tool-use
-      mcp_servers:
-        - omo-docs
-    modified_config_files:
-      - ~/.codex/config.toml
-      - ~/.local/bin
-    auto_update: false
-    enabled: true
-    workflow_dependencies:
-      - large-refactor-workflow
-    permission_risk: high
-    rollback: manual
-
-workflows:
-  codex-night-workflow:
-    harness: codex
-    active_skills:
-      - matt.tdd
-    blocked_skills: []
-    required_capabilities:
-      test-first-implementation:
-        preferred: matt.tdd
-        fallback:
-          - meerkat.test-first-implementation
-        policy: workflow-auto
-```
-
-## Source Profiles
-
-`skillboard import` reads a source profile and emits a YAML fragment containing
-governed `skills` plus their owning `install_units`.
-
-```bash
-skillboard import \
-  --profile github.mattpocock.skills \
-  --source-root /path/to/cloned-or-installed/repo \
-  --out .skillboard/reports/import-fragment.yaml
-```
-
-To preview a direct apply path, pass `--merge --config --dry-run`. Merge is
-non-destructive by default: if a skill or install-unit id already exists, the
-command fails and leaves the config unchanged. Use `--replace` only when you
-intend to overwrite existing entries, and drop `--dry-run` only after reviewing
-the reported change plan.
-
-```bash
-skillboard import \
-  --profile github.mattpocock.skills \
-  --source-root /path/to/cloned-or-installed/repo \
-  --config skillboard.config.yaml \
-  --merge \
-  --dry-run
-```
-
-Built-in profiles are shipped as YAML data under `profiles/`, including:
-
-- `github.mattpocock.skills`
-- `github.code-yeongyu.oh-my-openagent`
-- `github.anthropics.skills`
-- `github.wshobson.agents`
-- `github.voltagent.awesome-agent-skills`
-
-Project-specific profiles can live under `.skillboard/profiles/` and be passed
-by path:
-
-```bash
-skillboard import --profile .skillboard/profiles/my-source.yaml --source-root /path/to/repo
-```
-
-Invocation modes:
-
-- `manual-only`: user must explicitly ask for it.
-- `router-only`: a router/orchestrator may select it after policy checks.
-- `workflow-auto`: model invocation is allowed only inside listed workflows.
-- `global-auto`: allowed globally; use sparingly.
-- `blocked`: installed but not callable until policy or provenance changes.
-- `deprecated`: kept for history, not for new use.
-
-Skill exposure:
-
-- `exported`: centrally governed skill that may serve shared workflows or
-  canonical capabilities.
-- `global-meta`: intentionally global control skill, such as a router,
-  impact analyzer, or verification gate. This is the only exposure that may use
-  `global-auto`.
-- `unit-managed`: child component supplied by a parent install unit or harness
-  bundle.
-- `private`: workflow-internal implementation detail; central governance should
-  avoid managing it unless it becomes shared.
-
-`owner_install_unit` links a declared skill back to the package, plugin,
-marketplace, harness, or local source that supplied it. SkillBoard checks this
-both ways: install-unit `components.skills` must reference declared skills, and a
-skill that names an owner must be listed by that owner. `unit-managed` skills
-must always declare an owner.
-
-The multi-source example in `examples/multi-source.config.yaml` models one
-private skill source plus five external repositories:
-
-- `mattpocock/skills`
-- `code-yeongyu/oh-my-openagent`
-- `anthropics/skills`
-- `wshobson/agents`
-- `VoltAgent/awesome-agent-skills`
-
-Run the example commands from the repository root. Local example sources are
-written as project-root-relative paths; fetchable Git sources can be cached and
-pinned with `skillboard sources refresh`.
-
-## Commands
-
-All commands below use the global `skillboard` binary. When running from a
-clone without `npm install -g agent-skillboard`, replace `skillboard ` with
-`node bin/skillboard.mjs ` and run from the repository root.
-
-```bash
-skillboard init [--dir <path>] [--scan-root <dir>[,<dir>]] [--no-scan-installed]
-skillboard uninstall [--dir <path>] [--dry-run] [--remove-config|--reset-config] [--remove-reports] [--remove-hooks] [--keep-empty-dirs]
-skillboard inventory refresh [--dir <path>] [--config <path>] [--scan-root <dir>[,<dir>]] [--dry-run] [--json]
-skillboard inventory detect --unit <id> --config <path> [--install-output <path>] [--config-file a,b] [--source <value>] [--kind <kind>] [--scope <scope>] [--dry-run] [--json]
-skillboard sources refresh [--dir <path>] [--config <path>] [--unit <id>[,<id>]] [--cache-dir <dir>] [--dry-run] [--json]
-skillboard doctor [--dir <path>] [--config <path>] [--skills <dir>] [--verify] [--strict] [--json] [--summary]
-skillboard status [--dir <path>] [--config <path>] [--skills <dir>] [--verify] [--strict] [--json] [--summary]
-skillboard brief [--workflow <name>] [--dir <path>] [--config <path>] [--skills <dir>] [--include-actions] [--verbose] [--json]
-skillboard apply-action <action-id> [--workflow <name>] [--dir <path>] [--config <path>] [--skills <dir>] [--dry-run] [--yes] [--allow-destructive] [--json]
-skillboard import --profile <id-or-path> --source-root <dir> [--profile-dirs a,b] [--out <path>]
-skillboard import --profile <id-or-path> --source-root <dir> --config <path> --merge [--replace] [--dry-run]
-skillboard scan --config <path> --skills <dir>
-skillboard check --config <path> --skills <dir>
-skillboard list [skills|workflows|harnesses|install-units] --config <path> --skills <dir>
-skillboard explain <skill-id> --config <path> --skills <dir>
-skillboard can-use <skill-id> --workflow <name> --config <path> --skills <dir>
-skillboard guard use <skill-id> --workflow <name> --config <path> --skills <dir>
-skillboard audit sources --config <path> --skills <dir> [--verify]
-skillboard rollout [audit|plan|apply|rollback|report] [--dir <path>] [--config <path>] [--skills <dir>] [--transaction <id>] [--json]
-skillboard hook install --workflow <name> --config <path> --skills <dir> [--out <path>] [--skillboard-bin <path>] [--dry-run] [--json]
-skillboard lock write --config <path> --skills <dir> [--out <path>] [--replace] [--allow-unverified]
-skillboard review install-unit <unit-id> [--trust-level trusted|reviewed|unreviewed|blocked] --config <path> --skills <dir>
-skillboard add skill <skill-id> --path <relative-skill-path> --config <path> --skills <dir>
-skillboard add workflow <workflow-name> --harness <harness-name> --config <path> --skills <dir> [--skill <id>[,<id>]]
-skillboard add harness <harness-name> --config <path> --skills <dir> [--status <status>] [--command <cmd>[,<cmd>]]
-skillboard activate <skill-id> --workflow <name> --config <path> --skills <dir>
-skillboard block <skill-id> --workflow <name> --config <path> --skills <dir>
-skillboard quarantine <skill-id> --config <path> --skills <dir>
-skillboard prefer <skill-id> --workflow <name> --capability <name> --config <path> --skills <dir>
-skillboard remove skill <skill-id> --config <path> --skills <dir> [--force]
-skillboard dashboard --config <path> --skills <dir> [--out <path>]
-skillboard reconcile --config <path> --skills <dir> [--actual-harnesses a,b] [--out <path>]
-skillboard impact disable <skill-id> --config <path> --skills <dir> [--out <path>] [--json]
-```
+## What SkillBoard Gives You
 
-The bundled examples in this repository use `node bin/skillboard.mjs` explicitly
-because they are meant to run from a fresh clone without a global install.
-
-## Reconciliation Model
-
-SkillBoard compares desired state from config with actual state from discovered
-`SKILL.md` files and detected harnesses.
-
-- New skills become `quarantined` / `blocked` recommendations.
-- Known capability matches are surfaced, but not auto-enabled.
-- Removed harnesses report affected workflows, missing commands, and migration
-  recommendations.
-- Newly detected harnesses are disabled until workflows explicitly opt in.
-- If actual harness inventory is not provided, reconcile emits a warning instead
-  of silently assuming harness state.
-
-## Install Units
-
-SkillBoard should not assume that every runtime change is a standalone skill.
-Modern agent environments increasingly install packaged primitives:
-
-- `skill`
-- `plugin`
-- `marketplace`
-- `package-manager-dependency`
-- `harness`
-- `mcp-server`
-- `hook`
-- `agent`
-- `lsp`
-
-An install unit records source, scope, manifest/cache paths, provided
-components, modified config files, enablement, workflow dependencies, permission
-risk, trust level, digest/signature pins, and rollback shape. LazyCodex-style setups fit this model as
-user-global harness/plugin bundles that provide commands, skills, MCP
-integrations, hooks, and config.
-
-## Positioning
-
-SkillBoard is not a replacement for installers such as `skillshare` or package
-managers such as APM. It is the governance layer above them: it decides what is
-active, what is blocked, and what a user should inspect before changing the skill
-set.
-
-See [docs/install.md](docs/install.md) for install and bootstrap details.
-
-See [docs/user-flow.md](docs/user-flow.md),
-[docs/positioning.md](docs/positioning.md), and
-[docs/policy-model.md](docs/policy-model.md). See
-[docs/adapters.md](docs/adapters.md) for the source-profile adapter model, and
-[docs/versioning.md](docs/versioning.md) for release, schema, profile, workflow,
-and lockfile versioning rules.
+- Inventory that separates installed skills from callable skills.
+- Workflow-scoped policy instead of global "everything is active" behavior.
+- `brief`, `route`, `can-use`, and `guard use` surfaces for AI-mediated selection and availability.
+- Workflow conflict checks so overlapping skills cannot quietly degrade an answer.
+- Action cards that apply one approved policy change, then re-resolve state.
+- Source and install-unit review for plugins, hooks, MCP servers, harnesses,
+  commands, LSPs, and package-manager dependencies.
+- Impact, reconcile, rollout, and dashboard output before cleanup or migration.
+- Manual skill variant lifecycle for relationships such as `a -> claude.a`,
+  with draft, approval, drift, and reset checkpoints.
+
+SkillBoard is deny-by-default. Installing a skill does not make it automatically
+callable. A workflow, source, and invocation decision must make that explicit.
+For action cards, use `skillboard apply-action <action-id> --yes --json`; raw
+`skillboard hook install ... --dry-run --json` previews are underlying manual
+operator detail, not the primary action-card flow.
+
+## What Works Today
+
+SkillBoard currently supports:
+
+- YAML policy config parsing and semantic checks.
+- Recursive `SKILL.md` discovery.
+- Source-profile import for cloned or installed skill repositories.
+- Agent runtime install-unit inventory when manifest metadata is available.
+- Markdown dashboard and machine-readable brief generation.
+- Disable-impact analysis and reconcile plans.
+- Workflow-scoped activation, blocking, preference, and guard checks.
+- Action-card approval and post-apply brief refresh.
+- Manual variant registration, fork, status, approval, and reset.
+
+For the full command catalog and config shape, use
+[docs/reference.md](docs/reference.md).
+
+## Tested Value Proof
+
+A raw list says `matt.tdd` is active. SkillBoard says the same workflow has 0
+usable skills because policy health fails.
+
+| Question | Raw list | SkillBoard brief |
+| --- | --- | --- |
+| Does `matt.tdd` look enabled? | `active`, `workflow-auto` | blocked by policy health |
+| Can the agent safely use anything now? | not answered | 0 usable skills, 8 blocked skills |
+| Why? | not answered | `Policy errors: 2`, `Policy warnings: 1` |
+
+The action-card flow is tested too. Applying
+`activate-skill:anthropic.docx` in a temporary project changes the next brief
+from 2 usable skills to 3 and moves `anthropic.docx` into the manual-allowed
+set. SkillBoard applies one approved change, then re-resolves the next state.
+
+Run the proof with:
+
+```bash
+node --test test/readme-value-proof.test.mjs
+```
+
+See the [full reproducible proof](docs/value-proof.md) for exact commands,
+fixtures, and assertions.
+
+## Where To Go Next
+
+- [AI skill routing goal](docs/ai-skill-routing-goal.md)
+- [Install and bootstrap](docs/install.md)
+- [First-time control flow](docs/user-flow.md)
+- [Capability routing](docs/routing.md)
+- [Command and config reference](docs/reference.md)
+- [Policy model](docs/policy-model.md)
+- [Capabilities](docs/capabilities.md)
+- [Skill variant lifecycle](docs/variant-lifecycle.md)
+- [Value proof](docs/value-proof.md)
+- [Source-profile adapters](docs/adapters.md)
+- [Rollout runbook](docs/rollout-runbook.md)
+- [Versioning and release rules](docs/versioning.md)
+- [Contributing](CONTRIBUTING.md)