agent-skillboard 0.2.15 → 0.2.17

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 ## Unreleased
 
+## 0.2.17 — 2026-07-07
+
+### Changed
+
+- Reworked the README opening and quick start so developers using multiple
+  agents, skill packs, plugins, MCP tools, or marketplaces can understand
+  SkillBoard's purpose and try the CLI with read-only `npm exec` commands before
+  installing it globally.
+
+### Fixed
+
+- Kept packaged npm smoke tests compatible with Node 20 release checks that run
+  inside an outer `npx -p node@20 -c ...` invocation.
+
+## 0.2.16 — 2026-07-06
+
+### Changed
+
+- Reframed SkillBoard as a permissive overlap-routing layer so agents continue
+  working with already-allowed skills instead of interrupting users for
+  pre-task settings.
+- Split routing and agent-integration internals into smaller modules while
+  preserving the existing CLI surface.
+- Setup guidance now clarifies that postinstall performs agent-layer setup only;
+  project initialization remains an explicit `skillboard init` step.
+
+### Fixed
+
+- Hardened setup and uninstall lifecycle cleanup around symlinked managed
+  guidance paths and project state directories.
+- Preserved Node.js 14.21 runtime compatibility by avoiding newer
+  `replaceAll`/`.at()` APIs in shipped runtime paths.
+- Avoided macOS false positives when agent homes live below symlinked system
+  ancestors such as `/var`.
+
 ## 0.2.15 — 2026-07-03
 
 ### Fixed

package/README.md

@@ -1,34 +1,49 @@
 # SkillBoard
 
-Use the right AI-agent skills without managing another checklist.
-
-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 skill, a
-short disclosure of what was used, and fewer setup interruptions when skills
-overlap.
+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; use `npx --yes --package agent-skillboard`.
+- No global install is required for a trial; use
+  `npm exec --yes --package agent-skillboard@latest -- skillboard`.
 - Most use is read-only: `brief`, `route`, `doctor`, and `guard use` answer
-  what is safe now.
+  what can run now and which route fits the request.
 - Nothing changes until you approve a policy action.
-- Project cleanup is conservative and previewable with `skillboard uninstall --dry-run`;
-  `--purge` removes SkillBoard's policy footprint while preserving local skills.
+- Project cleanup is previewable with `skillboard uninstall --dry-run`; default
+  uninstall removes SkillBoard settings and generated project state while
+  preserving local skills. Add `--keep-settings` only when you want to keep
+  project policy and bridge guidance.
 
 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 routing for AI
-agents. Installed user skills are usable by default unless runtime, user, or
-local instructions disable them; SkillBoard helps agents resolve overlap,
-policy, and workflow priority instead of guessing from raw skill files.
+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?"
-- "Which skill should you use to write tests first?"
+- "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?"
 
@@ -41,7 +56,7 @@ not need to memorize the SkillBoard command loop.
 
 A normal allowed-skill turn can look like this:
 
-- You: "Which skill should you use to write tests first?"
+- You: "Write tests before implementation."
 - AI: "I will use matt.tdd for this request."
 - AI: "I used matt.tdd for this request."
 
@@ -51,12 +66,25 @@ Names you may see in setup and logs:
 - `agent-skillboard`: the npm package.
 - `skillboard`: the CLI binary.
 
-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.
+## 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.
 
 <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%">
@@ -64,8 +92,8 @@ after → remember policy` loop that development should preserve.
 
 ## Why Not Just List `/skills`?
 
-A raw skill list answers what is declared. SkillBoard answers what can safely
-run now.
+A raw skill list answers what is declared. SkillBoard answers what can run now
+and how overlapping matches should route.
 
 Same fixture, different answer:
 
@@ -73,19 +101,31 @@ Same fixture, different answer:
 | --- | --- |
 | `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 ...` |
 
-That gap is the product. SkillBoard separates `installed` from `allowed`,
-checks policy health, and gives agents a brief they can use without guessing
+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.
+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.
 
 See [Tested Value Proof](#tested-value-proof) for the executable proof.
 
 ## 5-Minute Quick Start
 
-Install the CLI. On a normal global install, SkillBoard auto-connects the
-agent layer for detected Codex, Claude, OpenCode, and Hermes user skill roots:
+Try it without a global install. These read-only commands download the latest
+package for one run and do not create project files:
+
+```bash
+npm exec --yes --package agent-skillboard@latest -- skillboard --version
+npm exec --yes --package agent-skillboard@latest -- skillboard help brief
+```
+
+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:
 
 AI/automation/operator details:
 
@@ -108,15 +148,18 @@ 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 rerun the agent-home scan, refresh managed SkillBoard
-guidance files, and add newly detected supported agent roots.
+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 does not run `skillboard init`; use `init`
+only inside a workspace where you want project-local policy files.
 
 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:
 
-- "Which skill should you use to write tests first?"
+- "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?"
@@ -129,7 +172,8 @@ before creating an adapted target-agent `SKILL.md` and installs that file with
 provenance.
 
 If you intentionally maintain local workspace policy files, use the explicit
-operator commands for that layer:
+operator commands for that layer. `skillboard init` is needed only for a
+workspace where you want project-local policy, bridge guidance, and reports:
 
 ```bash
 npx --yes --package agent-skillboard skillboard init
@@ -137,26 +181,39 @@ npx --yes --package agent-skillboard skillboard doctor --summary
 npx --yes --package agent-skillboard skillboard brief --workflow <workflow-from-init>
 ```
 
-Remove the project bridge when you are done:
+Remove SkillBoard from a project when you are done:
 
 ```bash
 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
 ```
 
-Uninstall preserves local skills and policy files by default, and reports what
-it removed or preserved.
+Default project uninstall removes SkillBoard config, bridge guidance, and
+`.skillboard/` project state while preserving local `skills/*/SKILL.md` files.
+It reports what it removed or preserved.
+
+```bash
+npx --yes --package agent-skillboard skillboard uninstall --dir /path/to/your/project --keep-settings --dry-run
+npx --yes --package agent-skillboard skillboard uninstall --dir /path/to/your/project --keep-settings
+```
+
+Use `--keep-settings` only when you want to keep project SkillBoard 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.
 
-Remove SkillBoard's policy influence entirely while keeping local skill files:
+Remove SkillBoard's managed agent-layer guidance before package removal when
+you want agent homes back to their pre-SkillBoard guidance state:
 
 ```bash
-npx --yes --package agent-skillboard skillboard uninstall --dir /path/to/your/project --purge --dry-run
-npx --yes --package agent-skillboard skillboard uninstall --dir /path/to/your/project --purge
+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
 ```
 
-`--purge` deletes SkillBoard config, bridge blocks, and the entire
-`.skillboard/` project state directory while leaving `skills/*/SKILL.md` in
-place.
+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.
@@ -164,10 +221,11 @@ builds, clone-based development, Hermes bridge setup, refresh, and uninstall.
 ## What SkillBoard Gives You
 
 - Inventory that separates installed skills from callable skills.
-- Workflow-scoped policy instead of global "everything is active" behavior.
+- 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 so overlapping skills cannot quietly degrade an answer.
+- 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.

package/bin/postinstall.mjs

@@ -8,7 +8,8 @@ if (isTruthy(process.env.SKILLBOARD_SKIP_POSTINSTALL)) {
 
 process.stderr.write(`${[
   "SkillBoard installed or updated.",
-  "It does not change agent configs or project files.",
+  "It can refresh user-agent guidance on global installs, but it does not initialize projects.",
+  "Run skillboard init only inside a workspace where you want project-local policy files.",
   ""
 ].join("\n")}\n`);
 
@@ -18,7 +19,8 @@ if (!shouldAutoSetup(process.env)) {
     "Run skillboard setup later after adding another supported agent:",
     "  skillboard setup",
     "",
-    "Setup only writes user agent skill files and does not initialize projects.",
+    "Setup only writes user agent skill files. It does not create skillboard.config.yaml or .skillboard/.",
+    "Run skillboard init later only for a project that needs local SkillBoard policy.",
     ""
   ].join("\n")}`);
   process.exit(0);
@@ -40,7 +42,7 @@ try {
     packageSpec: "agent-skillboard"
   });
   if (exitCode === 0) {
-    process.stderr.write("Agent setup complete. Package updates rerun this setup automatically; run skillboard setup later after adding another supported agent.\n");
+    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");
   } else {
     process.stderr.write("Agent setup did not find supported agent homes. Run skillboard setup after installing or enabling a supported agent.\n");
   }

package/docs/ai-skill-routing-goal.md

@@ -1,12 +1,13 @@
 # AI Skill Routing Goal
 
-SkillBoard's product goal is to be a **non-blocking AI skill routing control plane**. It should help an AI decide which skills and workflow policies apply to the current task without turning normal work into a settings session.
+SkillBoard's product goal is to be a **permissive AI skill routing layer**. It keeps installed skills broadly available by default, then gives the AI a deterministic route when multiple skills could steer the same task. It should help an AI decide which skills and workflow policies apply to the current task without turning normal work into a settings session.
 
 This document is the goal reference for product work, routing changes, AI-facing brief changes, bridge updates, policy UX, and workflow UX.
 
 ## Core principle
 
-SkillBoard should keep the user's work moving by default.
+SkillBoard should keep the user's work moving by default. Broadly available
+skills are normal; deterministic overlap resolution is the value.
 
 The preferred loop is:
 
@@ -17,7 +18,7 @@ observe → route → work → explain briefly → ask after → remember policy
 That means:
 
 1. **Observe** the user's request and current workflow context.
-2. **Route** to the most appropriate allowed skill or workflow policy without asking first when the risk is low.
+2. **Route** to the most appropriate allowed skill or workflow policy without asking first when the risk is low, especially when several similar skills match.
 3. **Work** normally so SkillBoard does not become a pre-task settings checklist.
 4. **Explain briefly** which skill was used or skipped, only at the level needed for trust.
 5. **Ask after** the task when the routing choice was ambiguous, recurring, or likely to become a useful preference.
@@ -33,9 +34,18 @@ SkillBoard should not:
 - require users to memorize the SkillBoard command loop;
 - infer permission from raw installed `SKILL.md` files;
 - silently let overlapping skills contaminate an answer;
+- make the default model feel deny-first when the user's skill set is already allowed;
 - mutate skill body content when a usage policy would solve the problem;
 - turn every allowed skill invocation into a permission prompt.
 
+## Simplification rule
+
+Do not simplify by deleting concepts blindly. Keep a concept only when it
+justifies itself against SkillBoard's routing identity: routing, overlap
+resolution, policy memory, or a less interruptive user flow. Concepts that do
+not pass that test should be removed, merged, or renamed into the smaller
+surface that does.
+
 ## What SkillBoard controls
 
 SkillBoard controls **when and how a skill may influence an AI workflow**.
@@ -47,6 +57,7 @@ The control object is a usage policy, not the skill body itself:
 - user, project, or team scope;
 - preferred and fallback skills;
 - exclusion rules;
+- overlap resolution summaries;
 - confidence or ambiguity thresholds;
 - disclosure and guard behavior;
 - pending policy suggestions to review later.
@@ -105,6 +116,7 @@ A change moves SkillBoard toward this goal when:
 
 - ordinary allowed-skill work proceeds without a pre-task skill-selection prompt;
 - ambiguous but low-risk choices can be handled with ask-after-use policy suggestions;
+- multiple allowed matching skills stay available while the routed skill is deterministic;
 - risky or policy-changing actions still require explicit confirmation before apply;
 - `brief --json` gives AI integrations a stable way to discover the goal document and routing guidance;
 - text output stays compact by default and reserves verbose detail for explicit requests;

package/docs/install.md

@@ -3,13 +3,15 @@
 SkillBoard sits one layer above skill installers, plugin marketplaces, harness
 bundles, and local skill repositories.
 
-After install, ask your AI questions like "what skills can you use here?" or
-"which skill should you use for this task?" The AI runs SkillBoard behind the
-scenes when skill choices overlap or workflow priority matters. Installed user
-skills are usable by default unless runtime, user, or local instructions disable
-them; SkillBoard should not turn every skill choice into a permission prompt.
-When it selects a skill, the AI should briefly say which skill it will use and
-which skill it used. You do not need to memorize the SkillBoard command loop.
+After install, ask your AI normal work requests such as "write tests before
+implementation", "review this plan and point out weak assumptions", or "help me
+refine this UX flow." The AI runs SkillBoard behind the scenes only when skill
+choices overlap, workflow priority matters, or you explicitly ask for a
+SkillBoard or skill decision. Installed user skills are usable by default unless
+runtime, user, or local instructions disable them; SkillBoard should not turn
+every skill choice into a permission prompt. When it selects a skill, the AI
+should briefly say which skill it will use and which skill it used. You do not
+need to memorize the SkillBoard command loop.
 
 ## Install From npm
 
@@ -17,7 +19,9 @@ Global install auto-runs agent integration. Installing the package makes the
 CLI available and the postinstall step runs agent-layer setup for detected
 Codex, Claude, OpenCode, and Hermes user skill roots. The setup is best-effort:
 it never fails the package install, does not edit agent config files, and does
-not create project policy files.
+not create project policy files. It does not run `skillboard init`; run `init`
+only inside a workspace where you want local SkillBoard policy, bridge guidance,
+and reports.
 
 The published CLI supports Node.js 14.21 or newer. Node 12 and older are not
 supported without a transpiled bundle because the source uses modern ESM and
@@ -219,16 +223,24 @@ passing guard is not a user prompt; the agent should disclose the selected skill
 at the start and completion, and ask only if the guard denies use or a
 policy-changing action is needed.
 
-When the user asks which skill fits a task, the bridge tells agents to use
-`skillboard brief --intent <request> --json`, read `assistant_guidance.route`,
-and use `recommended_skill`, `fallback_skills`, `route_candidates`,
+When a normal request leaves skill choice ambiguous, several skills overlap,
+workflow priority matters, or the user asks for a SkillBoard or skill decision,
+the bridge tells agents to use `skillboard brief --intent <request> --json`,
+read `assistant_guidance.route`, and use `recommended_skill`, `fallback_skills`,
+`route_candidates`, `overlap_resolution`, `policy_memory`,
 `post_use_policy_suggestion`, and `guard_command` instead of guessing from raw
 skill text. Inspect
-`route_candidates` when several skills match so denied candidates and selected
-fallbacks are clear. If `post_use_policy_suggestion` is present, the agent
-should use the allowed routed skill first, then ask after completion whether to
-remember the suggested policy. If no skill matches, the agent should ask a
-clarifying question before choosing a skill.
+`overlap_resolution` and `route_candidates` when several skills match so
+allowed overlap, denied candidates, and selected fallbacks are clear. If
+`policy_memory` is present, the agent should mention after completion that
+remembered or configured policy selected this skill even though other allowed
+skills were available. If
+`post_use_policy_suggestion` is present, the agent should use the allowed
+routed skill first, then ask after completion whether to remember the suggested
+policy. If no skill matches, the agent should ask a clarifying question before
+choosing a skill. If the user explicitly requests a specific already-allowed
+skill, the agent should honor that request after guard use instead of rerouting
+away solely because another skill also matches.
 
 Action cards are change suggestions. Before an agent applies one that changes
 policy, trust, hooks, reset state, or skill references, it should request user
@@ -260,14 +272,24 @@ workflow you explicitly created for that Hermes profile.
 Before answering what skills can be used in that workflow, run:
 skillboard brief --workflow <workflow-name> --json --include-actions --dir /path/to/your/project
 
-When the user asks which skill fits a task, run:
+When a normal request leaves skill choice ambiguous, several skills overlap,
+workflow priority matters, or the user asks for a SkillBoard or skill decision,
+run:
 skillboard brief --workflow <workflow-name> --intent <request> --json --dir /path/to/your/project
 Read assistant_guidance.route. Use recommended_skill, fallback_skills,
-route_candidates, post_use_policy_suggestion, and guard_command. Inspect
-route_candidates when several skills match so denied candidates and selected
-fallbacks are clear. If post_use_policy_suggestion is present, use the allowed
-routed skill first, then ask after completion whether to remember the suggested
-policy. If no skill matches, ask a clarifying question before choosing a skill.
+route_candidates, overlap_resolution, policy_memory,
+post_use_policy_suggestion, and guard_command. Inspect overlap_resolution and
+route_candidates when several skills match so allowed overlap, denied
+candidates, and selected fallbacks are clear. If policy_memory is present,
+mention after completion that remembered or configured policy selected this
+skill even though other allowed skills were available. If
+post_use_policy_suggestion is present, use the allowed routed skill first, then
+ask after completion whether to remember the suggested policy. If no skill
+matches, ask a clarifying question before choosing a skill.
+
+If the user explicitly requests a specific already-allowed skill, honor that
+request after guard use instead of rerouting away solely because another skill
+also matches.
 
 Do not infer availability from installed SKILL.md files. Immediately before
 invoking a skill, run:
@@ -345,66 +367,74 @@ GitHub `org/repo` shorthands, and `file://` Git remotes. It writes the refreshed
 checkout under `.skillboard/sources/<install-unit-id>`, updates `cache_path`,
 `source_digest`, and `verified_at`, and leaves the config untouched on dry-run.
 
-## Uninstall From A Project
+## Uninstall Agent Guidance Or Project State
+
+Package removal, agent guidance cleanup, and project cleanup are intentionally
+separate. `npm uninstall -g agent-skillboard` removes the CLI package, but npm
+uninstall should not be relied on to edit agent homes or projects. If you want
+the postinstall-created user-agent guidance removed, run the agent-layer cleanup
+while the `skillboard` binary is still available:
+
+```bash
+skillboard uninstall --agent-layer --dry-run
+skillboard uninstall --agent-layer
+npm uninstall -g agent-skillboard
+```
+
+Agent-layer uninstall removes only managed `skillboard/SKILL.md` guidance files
+that contain SkillBoard's agent integration marker. It preserves other agent
+skills and user-authored `skillboard` skills that do not contain that marker.
+Use `--agent codex,claude,opencode,hermes` to target specific supported agents.
 
-Package removal and project cleanup are intentionally separate. `npm uninstall
--g agent-skillboard` removes the CLI package, but it does not edit a project.
-Use the project cleanup command when you want to remove the bridge files created
-by init:
+Use the project cleanup command when you want to remove SkillBoard from a
+project:
 
 ```bash
 skillboard uninstall --dir /path/to/your/project --dry-run
 skillboard uninstall --dir /path/to/your/project
 ```
 
-Default uninstall behavior is conservative:
+Default project uninstall is a clean removal:
 
-- removes only the `BEGIN SKILLBOARD` / `END SKILLBOARD` bridge block from
-  `AGENTS.md` and `CLAUDE.md`;
+- removes SkillBoard config, bridge blocks, and the entire `.skillboard/`
+  project state directory;
 - deletes a bridge file only when it has no user content left;
-- deletes `.skillboard/profiles/README.md` and `.skillboard/hooks/README.md`
-  only when they still exactly match the generated text;
-- removes empty generated directories;
-- preserves `skillboard.config.yaml`, local skill files, reports, generated guard
-  hooks, and modified files by default. Empty generated directories can be
-  removed.
+- preserves user-authored non-SkillBoard content in `AGENTS.md` and
+  `CLAUDE.md`;
+- preserves local `skills/*/SKILL.md` files because skill creation and deletion
+  are outside the uninstall scope.
 
-Use `--purge` when you want SkillBoard's influence removed from the project
-instead of merely disconnecting the bridge:
+Use `--keep-settings` only when you want to keep project SkillBoard policy and
+bridge guidance in place:
 
 ```bash
-skillboard uninstall --dir /path/to/your/project --purge --dry-run
-skillboard uninstall --dir /path/to/your/project --purge
+skillboard uninstall --dir /path/to/your/project --keep-settings --dry-run
+skillboard uninstall --dir /path/to/your/project --keep-settings
 ```
 
-`--purge` removes SkillBoard config, bridge blocks, and the entire
-`.skillboard/` project state directory, including reports, hooks, source caches,
-rollout logs, variant snapshots, and profiles. It preserves local `skills/`
-files because skills that were created or deleted are outside the uninstall
-scope.
-
-Use `--remove-config` to delete `skillboard.config.yaml` only when it still
-matches the untouched default config. If the config contains scanned skills or
-user edits, uninstall preserves it and reports it under `Preserved`.
-
-Use `--reset-config` only when you intentionally want to discard the current
-SkillBoard policy state and run `skillboard init` again from a fresh lifecycle.
-This removes `skillboard.config.yaml` even when it contains imported skills or
-workflow edits, but it still preserves local `skills/` files, reports, and
-user-authored bridge content.
-
-Add `--remove-reports` when a test reset should also delete generated
-`.skillboard/reports/` output. This flag is explicit because reports may contain
-review notes or other user-authored context. Local `skills/` files are still
-preserved.
-
-Add `--remove-hooks` only when a reset should also delete the entire
-`.skillboard/hooks/` directory contents. This is explicit because hook scripts
-may be wired into local agent/runtime configuration. Combine `--reset-config`,
-`--remove-reports`, and `--remove-hooks` for a clean test reset that removes
-the most common SkillBoard-owned lifecycle scaffolding while preserving local
-`skills/`. Use `--purge` instead when no `.skillboard/` project state should
-remain at all.
+`--keep-settings` preserves `skillboard.config.yaml`, project bridge guidance,
+reports, generated guard hooks, and modified project state. It is the explicit
+opt-in when project policy and guidance should survive package cleanup.
+
+`--purge` is still accepted as an explicit spelling for the default clean
+project removal. Default removal and `--purge` both remove `.skillboard/`,
+including reports, hooks, source caches, rollout logs, variant snapshots, and
+profiles.
+
+The older granular flags are still supported for scripts that assembled cleanup
+piecemeal. Passing `--remove-config`, `--reset-config`, `--remove-reports`, or
+`--remove-hooks` without `--purge` runs a partial cleanup instead of the default
+clean project removal:
+
+- `--remove-config` deletes `skillboard.config.yaml` only when it still matches
+  the generated default;
+- `--reset-config` deletes `skillboard.config.yaml` even when it contains policy
+  choices;
+- `--remove-reports` deletes `.skillboard/reports/`;
+- `--remove-hooks` deletes `.skillboard/hooks/`.
+
+For ordinary users, the default project uninstall is already the clean reset that
+removes SkillBoard-owned lifecycle scaffolding while preserving local `skills/`.
 
 ## Upper-Layer Control
 

package/docs/positioning.md

@@ -2,7 +2,8 @@
 
 ## Problem
 
-AI agent skills are easy to install but hard to govern.
+AI agent skills are easy to install but hard to route consistently once several
+similar skills are broadly available.
 
 Users lose confidence when they cannot tell:
 
@@ -17,10 +18,11 @@ Users lose confidence when they cannot tell:
 
 ## Product Definition
 
-SkillBoard is a workflow-scoped skill control board with a reconciler.
+SkillBoard is a workflow-scoped skill routing board with a reconciler.
 
-It is not primarily a skill catalog. It is an operations layer that turns a
-skill repository into a visible, policy-checked system. Users define intent and
+It is not primarily a skill catalog or a deny-first permission wall. It is an
+operations layer that keeps skills broadly usable, turns overlap into a visible
+route, and still checks policy before invocation. Users define intent and
 policy; SkillBoard interprets drift between desired state and actual state.
 
 ## Adjacent Tools
@@ -90,5 +92,5 @@ obvious safe defaults and only ask for important decisions:
 - removed skills: show affected workflows and fallback capabilities;
 - changed harnesses: show missing commands and migration hints;
 - new harnesses: disable by default until explicitly assigned;
-- duplicate skills: group by capability and recommend a canonical
-  implementation.
+- duplicate or overlapping skills: group by capability, keep allowed skills
+  available, and recommend a canonical route for the current workflow.