agent-skillboard 0.2.18 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,91 @@
 
 ## Unreleased
 
+## 0.3.1 — 2026-07-14
+
+### Added
+
+- Added read-only installation health to `doctor` and `status`, including the
+  running package, PATH-selected executable, shadowing, and duplicate npm
+  installs without executing candidate programs.
+- Added `skillboard setup --agent <agent> --skill-root <path>` for registering a
+  nonstandard user skill root and reusing it across later setup, package update,
+  share, unshare, and user-uninstall runs.
+
+### Changed
+
+- Made setup and global package updates preserve version 1 policy bytes and
+  print only the explicit v2 migration preview command.
+- Made `setup` the idempotent install/update/reconcile entrypoint for agents and
+  Hermes profiles added after SkillBoard installation.
+- Made setup backfill only already-selected `shared: true` skills into newly
+  active compatible roots while preserving agent-local defaults and unmanaged
+  collisions.
+- Kept registered roots in generated operational state rather than expanding
+  the v2 policy beyond `enabled`, `shared`, and optional preference.
+
+### Fixed
+
+- Added actionable single-prefix recovery guidance so system npm and Node
+  version-manager installations cannot silently drift without a doctor warning.
+- Prevented a stale default-root copy from producing false guard availability
+  after a custom root is registered.
+- Preserved conventional roots that still contain agent-owned skills alongside
+  registered roots, and included historical managed guidance in clean user
+  removal.
+- Restored invoking-user ownership recursively for shared skill copies created
+  or repaired by setup during sudo-driven global installs and updates.
+
+### Security
+
+- Restricted registered roots to non-symlinked directories inside the invoking
+  user's home and rejected assigning one root to different agents.
+- Treated malformed or symlinked share markers as unmanaged evidence so setup
+  and removal preserve user-owned or externally linked content.
+
+## 0.3.0 — 2026-07-13
+
+### Changed
+
+- Replaced the v1 policy matrix with schema v2's user-level decisions:
+  enable/disable and explicit per-skill cross-agent sharing.
+- Made valid installed skills enabled and agent-local by default; `shared: true`
+  preserves originals while creating managed compatible copies.
+- Added generated `installed_on` inventory so route and guard evaluate the
+  selected agent without a user-managed agent matrix.
+- Made normal setup, brief, route, guard, and policy mutations use home state
+  from any working directory; project init is no longer part of the v2 flow.
+- Limited optional preference to candidate ranking; preference never changes
+  availability or sharing.
+- Moved source, provenance, install-unit, digest, alias, and risk observations to
+  optional generated audit metadata that cannot block a skill.
+- Added explicit preview, apply, and byte-restoring rollback documentation for
+  `skillboard migrate v2`.
+- Scheduled removal of the one-release v1 read-only compatibility window for
+  v0.4.0.
+- Added `skill forget` for explicit policy-only cleanup after an owning
+  installer removes a local skill.
+- Added `uninstall --user` dry-run and confirmed apply flows that remove all
+  marker-owned shared copies, managed guidance, and home state while preserving
+  agent-owned and unmanaged skills.
+- Restored the declared Node.js 14.21 runtime floor and added release gates for
+  Node.js 14.21, 20, and 22 on Ubuntu, macOS, and Windows.
+
+### Fixed
+
+- Prevented removed skills from leaving unrecoverable stale policy that keeps
+  doctor unhealthy.
+- Prevented package removal from orphaning SkillBoard-managed shared copies in
+  supported agent skill roots.
+- Replaced Node 15/16-only clone, string replacement, recursive copy, and npm
+  smoke-test APIs with Node.js 14.21-compatible paths.
+
+### Security
+
+- Clarified that SkillBoard does not authorize hooks, MCP servers, commands,
+  external writes, destructive actions, or secrets; those remain runtime and
+  harness permission decisions.
+
 ## 0.2.18 — 2026-07-07
 
 ### Changed

package/README.md

@@ -1,298 +1,204 @@
 # SkillBoard
 
-Keep AI-agent skills broadly available, then route overlaps consistently.
-
-If you use more than one coding agent, skill pack, plugin, MCP tool, or
-marketplace, SkillBoard answers the practical questions before you install
-anything or change workflow policy: which skills are usable now, which one
-should win when skills overlap, which external skills need review, and how
-Codex, Claude, OpenCode, and Hermes can follow the same policy.
-
-Ask your AI normal work requests: "write tests before implementation",
-"review this plan and point out weak assumptions", "help me refine this UX
-flow", or explicit control requests like "use the Codex test-first skill in
-OpenCode too." SkillBoard runs behind the scenes only when skill choices
-overlap, workflow priority matters, or you explicitly ask for a skill/control
-decision, so you get the benefit: broadly available skills, one routed skill
-when similar skills overlap, and a short disclosure of what was used.
-
-The burden stays low:
-
-- No global install is required for a trial; use
-  `npm exec --yes --package agent-skillboard@latest -- skillboard`.
-- Most use is read-only: `brief`, `route`, and `guard use` answer what can run
-  now and which route fits the request; `doctor` checks local policy and source
-  health without writing changes.
-- Nothing changes until you approve a policy action.
-- Agent-layer cleanup is previewable with
-  `skillboard uninstall --agent-layer --dry-run`; it removes only managed
-  SkillBoard guidance while preserving other agent skills.
-
-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.
-
-Under the hood, SkillBoard is workflow-scoped skill priority and overlap routing
-for AI agents. Installed user skills are usable by default unless runtime, user,
-or local instructions disable them; SkillBoard helps Codex, OpenCode, Claude,
-and Hermes resolve overlapping skills and workflow priority instead of guessing
-from raw skill files.
-
-Start with normal requests:
-
-- "What skills can you use in this project?"
-- "Write tests before implementation."
-- "Review this plan and point out weak assumptions."
-- "Help me refine this UX flow."
-- "Use the Codex test-first skill in OpenCode too."
-- "Can you make `anthropic.docx` available for this workflow?"
-- "Why is this skill blocked?"
-
-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.
-
-A normal allowed-skill turn can look like this:
-
-- You: "Write tests before implementation."
-- AI: "I will use matt.tdd for this request."
-- AI: "I used matt.tdd for this request."
-
-Names you may see in setup and logs:
-
-- `SkillBoard`: the product and policy model.
-- `agent-skillboard`: the npm package.
-- `skillboard`: the CLI binary.
-
-## Who This Is For
-
-Use SkillBoard if you use more than one coding agent, skill pack, plugin, MCP
-tool, or marketplace and want one answer to:
-
-- Which skills can this agent use right now?
-- Which skill should win when several match the same task?
-- Which external or plugin skills are reviewed, blocked, or waiting for approval?
-- How can Codex, Claude, OpenCode, and Hermes follow the same skill policy?
-
-If you use one agent with a few hand-written local skills, you probably do not
-need SkillBoard yet. SkillBoard is for setups that have grown beyond one trusted
-skill folder and need 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.
+SkillBoard gives AI agents one small user-level policy for installed skills:
+
+1. Enable or disable a skill.
+2. Keep an enabled skill agent-local or shared across agents.
+
+Valid installed skills default to enabled and agent-local. Sharing is opt-in per
+skill. Optional preference ranks enabled skills installed for the current agent
+and never changes availability or copies files.
+
+Status: public alpha. Package 0.3.1 writes policy schema v2.
 
 <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%">
+  <img src="https://raw.githubusercontent.com/NyXXiR/skillboard/main/skillboard.png" alt="SkillBoard architecture diagram" width="100%">
 </p>
 
-## Why Not Just List `/skills`?
+## 5-Minute Quick Start
 
-A raw skill list answers what is declared. SkillBoard answers what can run now
-and how overlapping matches should route.
+Try the read-only CLI:
 
-Same fixture, different answer:
+```bash
+npm exec --yes --package agent-skillboard@latest -- skillboard --version
+npm exec --yes --package agent-skillboard@latest -- skillboard help
+```
 
-| 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` |
-| several review skills look relevant | `Overlap: Multiple allowed skills match... routes ...` |
+Install globally:
 
-That gap is the product. SkillBoard separates `installed` from `available`,
-checks policy health, and gives agents a route 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. Targeted
-tests also cover `grill-me`-style review overlap across Codex and OpenCode
-workflows.
+```bash
+npm install -g agent-skillboard
+skillboard doctor --summary
+```
 
-See [Tested Value Proof](#tested-value-proof) for the executable proof.
+The package postinstall sets up detected agent guidance and creates the
+user-level state at `~/skillboard.config.yaml` and
+`~/.skillboard/inventory.json`. No separate setup command is required after a
+normal install. If lifecycle scripts were skipped or another agent was added:
 
-## 5-Minute Quick Start
+```bash
+skillboard setup --agent codex,claude,opencode,hermes --yes
+```
 
-Try it without a global install. These read-only commands download the latest
-package for one run and do not create project files:
+Use the same Node/npm environment for later updates:
 
 ```bash
-npm exec --yes --package agent-skillboard@latest -- skillboard --version
-npm exec --yes --package agent-skillboard@latest -- skillboard help brief
+npm config get prefix
+npm install -g agent-skillboard@latest
+skillboard doctor --summary
 ```
 
-Install the CLI when you want SkillBoard connected to your agent layer. On a
-normal global install, SkillBoard auto-connects the agent layer for detected
-Codex, Claude, OpenCode, and Hermes user skill roots:
+Doctor compares the running package with the `skillboard` executable selected
+by `PATH` and reports duplicate global installs without executing those
+candidates. If multiple SkillBoard installations are reported, choose one npm
+prefix, activate the Node environment that owns each stale copy, and run
+`npm uninstall -g agent-skillboard` there. SkillBoard does not automatically
+uninstall another prefix. Restart or refresh agents after an update because
+some agents cache user skills.
+
+`setup` is safe to rerun. It refreshes managed guidance and inventory, discovers
+late standard agent homes and Hermes profiles, and fills already-selected
+`shared: true` skills into newly active roots. It does not make every skill
+global and never overwrites an unmanaged skill.
 
-AI/automation/operator details:
+For an agent that uses a nonstandard skill directory, register that root once:
 
 ```bash
-npm install -g agent-skillboard
+skillboard setup --agent hermes --skill-root ~/.hermes/profiles/work/skills --yes
 ```
 
-If your system npm requires elevated permissions, `sudo npm install -g
-agent-skillboard` is also supported. In that flow, install-time setup resolves
-`SUDO_USER` and writes the user-level guidance skill under the invoking user's
-agent homes. Managed guidance files written under the user's home are restored
-to the invoking user's ownership, while the `skillboard` binary still lands in
-the global prefix used by that npm command.
-
-The install-time setup writes a user-level `skillboard` guidance skill under
-detected agent homes. For Codex, detection includes `CODEX_HOME/skills`,
-`AGENTS_HOME/skills`, `~/.agents/skills`, and `~/.codex/skills`.
-If `~/.agents` already exists, setup creates `~/.agents/skills` because that is
-the shared Codex-visible skill tree in LazyCodex-style environments.
-It does not create `skillboard.config.yaml`,
-`.skillboard/`, `AGENTS.md`, or `CLAUDE.md` in projects.
-No separate setup command is required after a normal global install or update:
-npm lifecycle scripts run agent-layer setup automatically, rerun the agent-home
-scan, refresh managed SkillBoard guidance files, and add newly detected
-supported agent roots. This setup is agent-layer only.
-
-Run `skillboard setup --agent codex,claude,opencode,hermes --yes` later only
-after adding another supported agent, enabling a new agent home, or installing
-with lifecycle scripts disabled. Restart or refresh agents that cache user
-skills, then ask normal questions:
-
-- "Write tests before implementation."
-- "Review this plan and point out weak assumptions."
-- "What skills can you use here?"
-- "Use the Codex test-first skill in OpenCode too."
-- "When two skills overlap, which one should take priority?"
-
-When a target agent needs a skill from another agent, it can use
-`skillboard import-skill --from codex --to opencode --skill <skill> --json`
-behind the scenes. Compatible skills are copied into the target agent's user
-skill root. If the source contains agent-specific instructions, the agent asks
-before creating an adapted target-agent `SKILL.md` and installs that file with
-provenance.
-
-Remove SkillBoard's managed agent-layer guidance before package removal when
-you want agent homes back to their pre-SkillBoard guidance state:
+The root must be inside the invoking user's home. SkillBoard records it as
+operational discovery state in `~/.skillboard/agent-roots.json`, then reuses it
+on later setup and global package updates. This does not add another policy
+scope; per-skill `shared` remains the only cross-agent sharing decision.
+
+`sudo npm install -g agent-skillboard` is supported when system npm requires
+it. Setup resolves `SUDO_USER` and restores managed home files to that user.
+Setup and ordinary use write no project policy and require no project init.
+
+Ask the agent for the work you want. SkillBoard is consulted when skills overlap
+or when you ask which skill should be used.
+
+## The v2 policy
+
+```yaml
+version: 2
+skills:
+  test-first:
+    enabled: true
+    shared: false
+    preference:
+      intents: [testing]
+      priority: 100
+  docs-helper:
+    enabled: true
+    shared: true
+  unused:
+    enabled: false
+    shared: false
+```
+
+`enabled` controls use. `shared` controls whether SkillBoard maintains compatible
+copies for other supported agents. `shared: false` leaves the skill where its
+owner installed it; it does not quarantine, isolate, move, or delete anything.
+`shared: true` preserves the owner copy and adds only managed shared copies.
+
+New valid skills receive `enabled: true` and `shared: false`. See
+`examples/v2-multi-source.config.yaml` for a valid policy and
+`examples/v2-policy-error.config.yaml` for a validation fixture. Unprefixed
+examples are retained only as v1 migration fixtures.
+
+Generated inventory records where a skill is installed through `installed_on`.
+Source, provenance, path, digest, aliases, install-unit details, and risk are
+optional audit metadata and never determine availability. Runtime and action
+authorization are outside SkillBoard's scope; the active agent or harness still
+authorizes commands, hooks, MCP servers, network access, external writes,
+destructive actions, and secrets.
+
+## Agent flow
+
+From any working directory, an agent can:
+
+1. Read `skillboard brief --intent <request> --agent <agent> --json`.
+2. Select an enabled skill installed for that agent, using preference only to
+   rank matches.
+3. Run `skillboard guard use <skill-id> --agent <agent> --json` before use.
+4. Work without another approval when the guard allows use.
+5. Ask after completion only if remembering a preference would help.
+
+Direct policy changes are:
 
 ```bash
-npx --yes --package agent-skillboard skillboard uninstall --agent-layer --dry-run
-npx --yes --package agent-skillboard skillboard uninstall --agent-layer
-npm uninstall -g agent-skillboard
+skillboard skill enable <skill-id>
+skillboard skill disable <skill-id>
+skillboard skill share <skill-id>
+skillboard skill unshare <skill-id>
+skillboard skill preference <skill-id> --intent <term>[,<term>] --priority <integer>
+skillboard skill forget <skill-id>
 ```
 
-Agent-layer uninstall removes only managed `skillboard/SKILL.md` guidance files
-that contain SkillBoard's integration marker. It preserves other agent skills
-and user-authored `skillboard` skills.
-
-See [docs/install.md](docs/install.md) for global installs, `--dir`, GitHub
-builds, clone-based development, Hermes bridge setup, refresh, and uninstall.
-
-## What SkillBoard Gives You
-
-- Inventory that separates installed skills from callable skills.
-- Broad default availability with workflow-scoped overlap routing.
-- `brief`, `route`, `can-use`, and `guard use` surfaces for AI-mediated selection and availability.
-- `import-skill` for agent-layer skill reuse across Codex, Claude, OpenCode, and Hermes.
-- Workflow conflict checks and overlap summaries so similar skills stay
-  available without quietly degrading 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 priority-first at the agent layer: installed user skills are
-usable unless runtime, user, or local instructions disable them. Local workspace
-policy files can still model stricter workflow, source, and invocation
-decisions when a team needs that control.
-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.
-
-## Legacy Project Policy Mode
-
-Legacy project policy mode is for existing workspaces that still carry local
-SkillBoard policy files.
-
-`skillboard init` is deprecated project-local policy bootstrap and is not
-needed for normal use. Global install/postinstall and `skillboard setup`
-connect SkillBoard at the agent layer without creating `skillboard.config.yaml`,
-`.skillboard/`, `AGENTS.md`, or `CLAUDE.md` in projects. Agent-layer setup does
-not run `skillboard init`.
-
-The command remains for existing workspaces that intentionally maintain local
-policy files, bridge guidance, and reports. Use `skillboard help init` before
-using it in an existing workspace.
-
-Default legacy project uninstall removes SkillBoard config, bridge guidance,
-and `.skillboard/` project state while preserving local `skills/*/SKILL.md`
-files:
+Add `--dry-run` to preview or `--json` for machine-readable output. For mediated
+changes, the agent reads `brief --include-actions --json`, asks once about one
+current action, runs `skillboard apply-action <action-id> --agent <agent> --yes --json`, and
+rereads the returned post-apply brief.
+
+This is the distinction from a pure distribution tool: skills stay local by
+default, users promote only selected skills to shared use, and routing preference
+can be remembered without changing installation or availability.
+
+## Migrate version 1
+
+Version 1 has a one-release read-only window beginning in v0.3.0. Preview makes
+no writes; apply creates an adjacent byte-for-byte backup; rollback restores it.
 
 ```bash
-skillboard uninstall --dir /path/to/your/project --dry-run
-skillboard uninstall --dir /path/to/your/project
+skillboard migrate v2 --config <path> --json
+skillboard migrate v2 --config <path> --yes --json
+skillboard migrate v2 --config <path> --rollback <backup> --json
 ```
 
-Use `--keep-settings` only when you want to keep legacy project policy and
-bridge guidance in place, for example while cleaning generated helper files.
-`--purge` remains accepted as an explicit spelling for the default clean
-project removal.
+Setup and package updates keep v1 bytes unchanged and print the preview command.
+SkillBoard does not automatically migrate version 1. All v1 mutations refuse
+and point to migration. v0.4.0 removes the v1 reader.
 
-## What Works Today
+## Cleanup
 
-SkillBoard currently supports:
+After removing a local skill with its owning agent or package manager, refresh
+inventory and explicitly forget the stale policy entry:
 
-- 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.
-- Agent-layer skill import with compatible copy or user-approved AI-mediated adaptation.
-- Manual variant registration, fork, status, approval, and reset.
+```bash
+skillboard inventory refresh
+skillboard skill forget <skill-id> --dry-run
+skillboard skill forget <skill-id>
+```
 
-For the full command catalog and config shape, use
-[docs/reference.md](docs/reference.md).
+`forget` never deletes skill files. It refuses skills that are still observed or
+shared, so shared skills must be unshared first.
 
-## Tested Value Proof
+Before removing the SkillBoard package, preview and apply the complete
+user-level cleanup:
 
-A raw list says `matt.tdd` is active. SkillBoard says the same workflow has 0
-usable skills because policy health fails.
+```bash
+skillboard uninstall --user --dry-run
+skillboard uninstall --user --yes
+npm uninstall -g agent-skillboard
+```
 
-| 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` |
+User cleanup removes marker-owned shared copies, managed guidance, the home
+policy, and generated user state. It preserves agent-owned and unmanaged skills.
+Legacy project and guidance-only cleanup remain available through command help.
 
-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.
+## Development
 
-Run the proof with:
+From a clone, replace `skillboard ` with `node bin/skillboard.mjs `.
 
 ```bash
-node --test test/readme-value-proof.test.mjs
+npm install
+npm run check
+node bin/skillboard.mjs help
 ```
 
-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 agent-layer setup](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)
+Read [installation](docs/install.md), [user flow](docs/user-flow.md),
+[policy model](docs/policy-model.md), [routing](docs/routing.md),
+[reference](docs/reference.md), [versioning](docs/versioning.md), and the
+[Rollout runbook](docs/rollout-runbook.md).

package/bin/postinstall.mjs

@@ -19,7 +19,7 @@ if (!shouldAutoSetup(process.env)) {
     "Run skillboard setup later after adding another supported agent:",
     "  skillboard setup",
     "",
-    "Setup only writes user agent skill files. It does not create skillboard.config.yaml or .skillboard/.",
+    "Setup writes user-agent guidance, reconciles shared skills, and refreshes the user-level policy and inventory.",
     "skillboard init is deprecated project-local policy bootstrap and is not needed for normal use.",
     ""
   ].join("\n")}`);
@@ -43,6 +43,7 @@ try {
   });
   if (exitCode === 0) {
     process.stderr.write("Agent setup complete. Package updates rerun this setup automatically; run skillboard setup later after adding another supported agent. No project init was run.\n");
+    process.stderr.write("Run skillboard doctor --summary to check policy and executable paths after the update.\n");
   } else {
     process.stderr.write("Agent setup did not find supported agent homes. Run skillboard setup after installing or enabling a supported agent.\n");
   }