agent-skillboard 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## Unreleased
+
+## 0.2.3 — 2026-07-03
+
+### Added
+
+- `skillboard uninstall --purge` removes SkillBoard config, reports, hooks,
+  bridge blocks, and empty generated directories while preserving local skill
+  files.
+
+### Changed
+
+- Cleanup action cards now present the shorter purge command instead of the
+  three-flag reset form.
+- Uninstall help and docs clarify the difference between conservative bridge
+  removal and full SkillBoard policy-footprint removal.
+
+## 0.2.2 — 2026-07-03
+
+### Changed
+
+- High-risk runtime/plugin source action cards now recommend a one-time source review instead of defaulting to a block action.
+- Reviewed quarantined runtime/plugin skills can be activated into a workflow as `manual-only` skills, keeping ask-after preference learning separate from source trust review.
+- Bootstrap and install docs explain source review followed by manual activation for runtime/plugin skills.
+- Generated guard hooks pin their install-time SkillBoard command, config, skills root, and workflow instead of accepting environment overrides for those trust-boundary values.
+- README now surfaces public alpha and config schema v1 status near the quick product summary.
+- npm package contents exclude historical planning documents under `docs/plans`.
+- CI check matrix includes Node 24 before publish-time verification.
+
+## 0.2.1 — 2026-07-02
+
+### Added
+
+- Ask-after skill routing guidance for ambiguous or fallback skill choices.
+- Packaged runtime smoke coverage for npm-installed SkillBoard usage.
+
+### Changed
+
+- Release automation now skips publishing only when the exact npm version already exists.
+- AI bridge guidance emphasizes route candidates, post-use policy suggestions, and guard disclosure.
+
+## 0.2.0 — 2026-06-30
+
+### Added
+
+- AI-mediated brief/action-card flow with current action IDs and post-apply brief refresh.
+- Source inventory refresh, doctor/status summaries, source pin refresh, and install-output detection.
+- Richer dry-run plans for lifecycle, import, hook, and cleanup workflows.
+
+### Changed
+
+- README and install docs now lead with low-burden npm usage instead of source-tree setup.
+- Workflow routing now separates installed skills from currently allowed skills more explicitly.
+
 ## 0.1.2 — 2026-06-29
 
 ### Added

package/README.md

@@ -13,7 +13,11 @@ The burden stays low:
 - 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`.
+- Project cleanup is conservative and previewable with `skillboard uninstall --dry-run`;
+  `--purge` removes SkillBoard's policy footprint while preserving local 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 policy and routing for AI
 agents. It separates `installed` from `allowed`, checks workflow policy and
@@ -97,9 +101,12 @@ npx --yes --package agent-skillboard skillboard brief --workflow <workflow-from-
 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 or
-blocked until reviewed. The explicit package/binary spelling avoids an extra npx
-install prompt and keeps the `skillboard` executable name clear.
+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.
 
 Remove the project bridge when you are done:
 
@@ -111,6 +118,16 @@ npx --yes --package agent-skillboard skillboard uninstall --dir /path/to/your/pr
 Uninstall preserves local skills and policy files by default, and reports what
 it removed or preserved.
 
+Remove SkillBoard's policy influence entirely while keeping local skill files:
+
+```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
+```
+
+`--purge` deletes SkillBoard config, reports, hooks, bridge blocks, and empty
+generated directories while leaving `skills/*/SKILL.md` in place.
+
 See [docs/install.md](docs/install.md) for global installs, `--dir`, GitHub
 builds, clone-based development, Hermes bridge setup, refresh, and uninstall.
 

package/docs/install.md

@@ -28,11 +28,12 @@ npx --yes --package agent-skillboard skillboard brief --workflow <workflow-from-
 
 SkillBoard does not make installed skills automatically callable. It imports
 trusted local skills as manual-only and keeps runtime/plugin skills quarantined
-until reviewed. When `init` creates or discovers workflows, use one of the
-workflow names it prints for the first brief. If `init` does not print a
-workflow, run the unscoped `brief` command it prints instead. The explicit
-package/binary spelling avoids an extra npx install prompt and keeps the
-executable name clear.
+until their source is reviewed. The brief presents unreviewed runtime sources as
+one-time review decisions rather than default block recommendations; after
+review, individual quarantined skills can be activated as manual-only workflow
+skills. When `init` creates or discovers workflows, use one of the workflow names
+it prints for the first brief. If `init` does not print a workflow, run the unscoped `brief` command it prints instead. The explicit package/binary spelling
+avoids an extra npx install prompt and keeps the executable name clear.
 
 The equivalent `npm exec` spelling is also no-prompt and works well in scripts:
 
@@ -119,12 +120,16 @@ manual-only` and attached to a generated local manual workflow when the project
 has no workflow metadata yet. That lets a first-time user keep their existing
 manual skills usable through `skillboard can-use` and guard checks without
 granting automatic model invocation or creating legacy-state warning noise.
-System, plugin, and other runtime-supplied skills are written with `status: quarantined` and
-`invocation: blocked`. Plugin hooks, MCP servers, commands, and modified config files are
-recorded on the owning install unit when manifest metadata exposes them, which
-lets policy checks flag high-risk runtime extensions without flattening them
-into loose skills. Use `--no-scan-installed` for a scaffold-only bootstrap, or
-`--scan-root <dir>[,<dir>]` to add server-specific skill roots during bootstrap.
+System, plugin, and other runtime-supplied skills are written with `status:
+quarantined` and `invocation: blocked`. Plugin hooks, MCP servers, commands, and
+modified config files are recorded on the owning install unit when manifest
+metadata exposes them, which lets policy checks flag high-risk runtime
+extensions without flattening them into loose skills. After the owning source is
+reviewed, action cards can activate a quarantined runtime skill into a workflow
+as `manual-only`; automatic preference should still be remembered later through
+the normal ask-after-use policy loop. Use `--no-scan-installed` for a
+scaffold-only bootstrap, or `--scan-root <dir>[,<dir>]` to add server-specific
+skill roots during bootstrap.
 
 After init, run:
 
@@ -178,7 +183,10 @@ so stale action ids and cached action-card shell text are not replayed.
 For hook action cards specifically, keep `apply-action` as the action-card
 primary flow. Raw `skillboard hook install ... --dry-run --json` previews and
 the matching non-dry-run command are underlying manual detail for operators who
-need to inspect or materialize an executable guard hook directly.
+need to inspect or materialize an executable guard hook directly. Generated hooks
+pin the install-time SkillBoard command, config, skills root, and workflow; set
+those values with hook install options such as `--skillboard-bin`, not with
+runtime environment overrides.
 
 ## Hermes System Prompt Bridge
 
@@ -303,6 +311,18 @@ Default uninstall behavior is conservative:
   hooks, and modified files by default. Empty generated directories can be
   removed.
 
+Use `--purge` when you want SkillBoard's influence removed from the project
+instead of merely disconnecting the bridge:
+
+```bash
+skillboard uninstall --dir /path/to/your/project --purge --dry-run
+skillboard uninstall --dir /path/to/your/project --purge
+```
+
+`--purge` removes SkillBoard config, reports, hooks, bridge blocks, and empty
+generated directories. 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`.
@@ -322,7 +342,8 @@ 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
-SkillBoard-owned lifecycle scaffolding while preserving local `skills/`.
+SkillBoard-owned lifecycle scaffolding while preserving local `skills/`. The
+equivalent short form is `--purge`.
 
 ## Upper-Layer Control
 
@@ -370,8 +391,8 @@ skillboard review install-unit github.mattpocock.skills \
 
 Automatic invocation remains blocked for unreviewed non-user sources. The user
 experience should still be a one-time decision queue: review, trust, or block
-the install unit once, then revisit only when the source, skill, or workflow
-changes.
+the install unit once, activate only the needed quarantined skills as
+manual-only, then revisit only when the source, skill, or workflow changes.
 
 ```yaml
 install_units:

package/docs/reference.md

@@ -52,7 +52,7 @@ node bin/skillboard.mjs brief --dir /path/to/your/project --workflow <workflow-f
 
 ```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 uninstall [--dir <path>] [--dry-run] [--purge] [--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]

package/docs/user-flow.md

@@ -191,7 +191,10 @@ skillboard hook install --workflow daily-workflow --config skillboard.config.yam
 ```
 
 For direct manual hook installation, inspect the JSON `planned.preview.shell`
-before an operator materializes the matching non-dry-run hook command.
+before an operator materializes the matching non-dry-run hook command. Generated
+hooks pin the install-time SkillBoard command, config, skills root, and workflow;
+set those values with hook install options such as `--skillboard-bin`, not with
+runtime environment overrides.
 
 ## 4. Enable, Disable, Or Prefer
 
@@ -258,8 +261,8 @@ skillboard remove skill user.helper \
   --force
 ```
 
-This removes SkillBoard policy references only. It does not delete
-`skills/user-helper/SKILL.md`.
+This removes SkillBoard policy references only and leaves
+`skills/user-helper/SKILL.md` in place.
 
 ## 6. Stop Using SkillBoard Safely
 
@@ -277,14 +280,16 @@ content in bridge files.
 For a fresh policy lifecycle during testing, use:
 
 ```bash
-skillboard uninstall --reset-config --remove-reports --remove-hooks --dry-run
-skillboard uninstall --reset-config --remove-reports --remove-hooks
+skillboard uninstall --purge --dry-run
+skillboard uninstall --purge
 skillboard init
 ```
 
-`--reset-config` discards the current SkillBoard config even if it contains
-imported skills or workflow edits. `--remove-reports` also discards generated
-dashboard and impact reports. `--remove-hooks` discards the entire
-`.skillboard/hooks/` directory contents when you explicitly want a full test or
-test reset, so `.skillboard/` can disappear when no other SkillBoard state
-remains. These reset flags do not delete local `skills/` files.
+Use `--purge` when you want SkillBoard's allow/block/preference influence gone
+from the project while keeping local skill files. It discards the current
+SkillBoard config even if it contains imported skills or workflow edits,
+discards generated dashboard and impact reports, and removes the entire
+`.skillboard/hooks/` directory contents. It is equivalent to
+`--reset-config --remove-reports --remove-hooks`, so `.skillboard/` can
+disappear when no other SkillBoard state remains. Local `skills/` files stay in
+place.

package/docs/value-proof.md

@@ -35,6 +35,10 @@ examples/skillboard.config.yaml
 examples/skills
 ```
 
+`examples/skillboard.config.yaml` is an intentional policy-failure fixture. It
+is not the passing starter example; it exists to prove that SkillBoard refuses a
+raw-list availability claim when policy health fails.
+
 Workflow:
 
 ```bash

package/docs/versioning.md

@@ -8,7 +8,7 @@ source profiles, and the generated lockfile.
 
 ## Status
 
-Current package version: `0.2.1`
+Current package version: `0.2.3`
 
 Current config schema version:
 
@@ -59,7 +59,8 @@ must call them out clearly.
 Suggested tags:
 
 - `v0.1.0-alpha`: first public GitHub alpha.
-- `v0.2.1`: ask-after skill routing, README benefit-first positioning,
+- `v0.2.3`: one-time runtime source review before manual activation, ask-after
+  skill routing, purge uninstall, README benefit-first positioning,
   source inventory refresh, doctor/status, source pin refresh,
   installer/config detection, resilient detector warnings, and richer dry-run
   plans.
@@ -193,8 +194,8 @@ Before tagging a public release:
   provenance with GitHub Actions OIDC, so keep `permissions.id-token: write`,
   the npm registry URL in `setup-node`, and
   `NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}` on the publish step.
-- Push a version tag that exactly matches `package.json`, for example `v0.2.1`
-  for package version `0.2.1`.
+- Push a version tag that exactly matches `package.json`, for example `v0.2.3`
+  for package version `0.2.3`.
 - Let `.github/workflows/publish.yml` publish from the tag. The workflow runs
   the full check suite, validates that the tag matches the package version, and
   skips `npm publish` only when that exact version already exists on npm.
@@ -228,8 +229,21 @@ completion notes:
 - update README quick-start to verify the installed version before running
   policy commands.
 
-## 0.2.1 Completion Notes
+## 0.2.3 Completion Notes
 
+- add `skillboard uninstall --purge` for users who want SkillBoard's policy
+  influence and generated footprint removed while preserving local skill files;
+- document the lifecycle split between conservative bridge cleanup and full
+  SkillBoard policy-footprint removal;
+- show purge in cleanup action cards so users do not need to remember the
+  equivalent `--reset-config --remove-reports --remove-hooks` sequence.
+
+## 0.2.2 Completion Notes
+
+- recommend one-time review, not default blocking, for high-risk runtime/plugin
+  install units;
+- after source review, allow quarantined runtime/plugin skills to be activated
+  as `manual-only` workflow skills before any ask-after preference is recorded;
 - add ask-after route policy suggestions for safe ambiguous workflow skill
   matches while preserving the public route JSON contract;
 - carry route candidate guard and capability roles into AI-facing brief

package/examples/skillboard.config.yaml

@@ -1,6 +1,11 @@
-version: 1
-
-defaults:
+# Intentional policy-failure fixture.
+# This file is used by the value-proof tests to show why a raw skill list can
+# look usable while SkillBoard correctly reports policy errors. Use
+# examples/multi-source.config.yaml for a passing multi-source example.
+
+version: 1
+
+defaults:
   invocation_policy: deny-by-default
   allow_model_invocation: false
   require_explicit_workflow: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-skillboard",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Let AI agents pick and use allowed skills in each workflow.",
   "keywords": [
     "ai-agent",
@@ -25,7 +25,6 @@
     "bin",
     "src",
     "docs/*.md",
-    "docs/plans",
     "examples",
     "profiles",
     "README.md",

package/src/advisor/actions.mjs

@@ -12,6 +12,7 @@ import { buildSetupGuidanceActions } from "./setup-actions.mjs";
 import { trustRecommendationAction } from "./trust-policy.mjs";
 
 const WRITABLE_MODES = new Set(["manual-only", "router-only", "workflow-auto"]);
+const NON_ACTIVATABLE_STATUSES = new Set(["deprecated", "archived", "removed"]);
 
 export function buildInitActions(paths) {
   return [makeAction({
@@ -82,7 +83,10 @@ function reviewInstallUnitActions({ paths, workflow, reviewQueue }) {
 }
 
 function activateSkillActions({ paths, workflow, skills, workspace }) {
-  const candidates = [...skills.not_in_workflow, ...skills.blocked.filter((skill) => missingProvenance(workspace, skill.id))];
+  const candidates = [
+    ...skills.not_in_workflow,
+    ...skills.blocked.filter((skill) => missingProvenance(workspace, skill.id) || canActivate(skill))
+  ];
   return candidates.flatMap((skill) => {
     if (missingProvenance(workspace, skill.id)) {
       return [blockedActivateAction(paths, workflow, skill)];
@@ -90,7 +94,7 @@ function activateSkillActions({ paths, workflow, skills, workspace }) {
     if (!canActivate(skill)) {
       return [];
     }
-    const mode = skill.advanced.invocation;
+    const mode = activationMode(skill);
     const risk = riskFromSkill(skill);
     const dryRun = command([
       "skillboard", "activate", skill.id, "--workflow", workflow.selected, "--mode", mode,
@@ -169,6 +173,7 @@ function hookInstallActions({ paths, workflow }) {
 function removeSkillForceActions({ paths, workflow, skills, workspace }) {
   return skills.blocked
     .filter((skill) => !missingProvenance(workspace, skill.id))
+    .filter((skill) => !canActivate(skill))
     .map((skill) => {
       const dryRun = command([
         "skillboard", "remove", "skill", skill.id, "--force",
@@ -194,19 +199,17 @@ function removeSkillForceActions({ paths, workflow, skills, workspace }) {
 
 function resetCleanupAction({ paths, workflow, cleanup }) {
   const dryRun = command([
-    "skillboard", "uninstall", "--dir", paths.root, "--dry-run",
-    "--reset-config", "--remove-reports", "--remove-hooks"
+    "skillboard", "uninstall", "--dir", paths.root, "--purge", "--dry-run"
   ]);
   return makeAction({
     kind: "reset-cleanup",
     targetId: paths.root,
-    label: "Reset SkillBoard generated project files",
-    reason: "Preview full SkillBoard cleanup before applying it.",
+    label: "Purge SkillBoard project footprint",
+    reason: "Preview full SkillBoard policy cleanup before applying it.",
     risk: "destructive",
     dryRun,
     apply: applyOrNull(workflow, dryRun, [
-      "skillboard", "uninstall", "--dir", paths.root,
-      "--reset-config", "--remove-reports", "--remove-hooks"
+      "skillboard", "uninstall", "--dir", paths.root, "--purge"
     ]),
     appliesTo: { kind: "project", id: paths.root },
     blockedReason: blockedByWorkflow(workflow),
@@ -230,7 +233,24 @@ function blockedActivateAction(paths, workflow, skill) {
 }
 
 function canActivate(skill) {
-  return WRITABLE_MODES.has(skill.advanced.invocation) && skill.advanced.trust.reviewed === true;
+  return activationMode(skill) !== null && skill.advanced.trust.reviewed === true;
+}
+
+function activationMode(skill) {
+  if (NON_ACTIVATABLE_STATUSES.has(skill.advanced.status)) {
+    return null;
+  }
+  if (WRITABLE_MODES.has(skill.advanced.invocation)) {
+    return skill.advanced.invocation;
+  }
+  if (
+    skill.advanced.owner_install_unit !== undefined
+    && skill.advanced.owner_install_unit !== null
+    && (skill.advanced.status === "quarantined" || skill.advanced.invocation === "blocked")
+  ) {
+    return "manual-only";
+  }
+  return null;
 }
 
 function missingProvenance(workspace, skillId) {

package/src/advisor/trust-policy.mjs

@@ -21,9 +21,11 @@ export function recommendTrustLevel(unit) {
     return "trusted";
   }
 
-  // High-risk sources should not be activated from advisor suggestions without explicit blocking/review.
+  // High-risk sources require explicit review, not a default block. Blocking is
+  // still available as a recorded trust policy, but the advisor keeps the work
+  // moving by asking for a one-time source review first.
   if (risk === "high") {
-    return "blocked";
+    return "reviewed";
   }
 
   // Unknown risk always requires at least a review before any automatic use.
@@ -54,7 +56,7 @@ export function trustRecommendationAction(recommended) {
     return {
       kind: "block-install-unit",
       label: "Decide whether to block source",
-      reason: "High-risk or runtime-extending source needs a one-time decision before its skills appear again."
+      reason: "Source is blocked by trust policy and needs an explicit decision before its skills appear again."
     };
   }
   return {

package/src/cli.mjs

@@ -61,7 +61,7 @@ const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.u
 
 const APPLY_ACTION_VALUE_OPTIONS = new Set(["workflow", "dir", "config", "skills", "out", "skillboard-bin"]);
 const COMMAND_USAGE = new Map([
-  ["uninstall", ["uninstall [--dir <path>] [--dry-run] [--remove-config|--reset-config] [--remove-reports] [--remove-hooks] [--keep-empty-dirs]"]],
+  ["uninstall", ["uninstall [--dir <path>] [--dry-run] [--purge] [--remove-config|--reset-config] [--remove-reports] [--remove-hooks] [--keep-empty-dirs]"]],
   [
     "inventory",
     [
@@ -1501,7 +1501,7 @@ function helpText() {
     "",
     "AI/automation operations:",
     "  init [--dir <path>] [--scan-root <dir>[,<dir>]] [--no-scan-installed]",
-    "  uninstall [--dir <path>] [--dry-run] [--remove-config|--reset-config] [--remove-reports] [--remove-hooks] [--keep-empty-dirs]",
+    "  uninstall [--dir <path>] [--dry-run] [--purge] [--remove-config|--reset-config] [--remove-reports] [--remove-hooks] [--keep-empty-dirs]",
     "  inventory refresh [--dir <path>] [--config <path>] [--scan-root <dir>[,<dir>]] [--dry-run] [--json]",
     "  inventory detect --unit <id> --config <path> [--install-output <path>] [--config-file a,b] [--source <value>] [--kind <kind>] [--scope <scope>] [--dry-run] [--json]",
     "  sources refresh [--dir <path>] [--config <path>] [--unit <id>[,<id>]] [--cache-dir <dir>] [--dry-run] [--json]",
@@ -1560,6 +1560,9 @@ function commandHelpText(command) {
   if (command === "init") {
     return initHelpText();
   }
+  if (command === "uninstall") {
+    return uninstallHelpText();
+  }
   if (command === "doctor" || command === "status") {
     return doctorHelpText();
   }
@@ -1601,7 +1604,7 @@ function initHelpText() {
     "What changes:",
     "  Writes skillboard.config.yaml, skills/, .skillboard/, AGENTS.md, and CLAUDE.md as needed.",
     "  Imports trusted user-local skills as on-request skills.",
-    "  Keeps runtime, plugin, system, and external skills quarantined until reviewed.",
+    "  Keeps runtime, plugin, system, and external skills behind source review before manual activation.",
     "",
     "Next:",
     "  Run skillboard doctor --summary.",
@@ -1610,6 +1613,33 @@ function initHelpText() {
   ].join("\n");
 }
 
+function uninstallHelpText() {
+  return [
+    "Usage: skillboard uninstall [--dir <path>] [--dry-run] [--purge] [--remove-config|--reset-config] [--remove-reports] [--remove-hooks] [--keep-empty-dirs]",
+    "",
+    "This help is read-only. It does not load config or change project files.",
+    "",
+    "Removes SkillBoard project bridge files and generated lifecycle scaffolding.",
+    "Default cleanup is conservative and preserves policy, reports, hooks, local skills, and user-authored content.",
+    "",
+    "Options:",
+    "  --dir <path>        Project root to clean up; defaults to the current directory.",
+    "  --dry-run           Preview the cleanup without writing changes.",
+    "  --purge             Remove SkillBoard policy influence and generated footprint while preserving local skills.",
+    "  --remove-config     Delete skillboard.config.yaml only if it still matches the generated default.",
+    "  --reset-config      Delete skillboard.config.yaml even when it contains policy choices.",
+    "  --remove-reports    Delete .skillboard/reports/.",
+    "  --remove-hooks      Delete .skillboard/hooks/.",
+    "  --keep-empty-dirs   Preserve empty generated directories.",
+    "",
+    "Purge:",
+    "  Equivalent to --reset-config --remove-reports --remove-hooks.",
+    "  It removes SkillBoard config, reports, hooks, bridge blocks, and empty generated dirs.",
+    "  It does not delete local skills under skills/.",
+    ""
+  ].join("\n");
+}
+
 function doctorHelpText() {
   return [
     "Usage: skillboard doctor [--dir <path>] [--config <path>] [--skills <dir>] [--verify] [--strict] [--summary] [--json]",

package/src/hook-plan.mjs

@@ -58,10 +58,10 @@ function renderGuardHookScript(options) {
   return `#!/usr/bin/env sh
 set -eu
 
-SKILLBOARD_BIN=\${SKILLBOARD_BIN:-${shellQuote(options.command)}}
-SKILLBOARD_CONFIG=\${SKILLBOARD_CONFIG:-${shellQuote(options.configPath)}}
-SKILLBOARD_SKILLS=\${SKILLBOARD_SKILLS:-${shellQuote(options.skillsRoot)}}
-SKILLBOARD_WORKFLOW=\${SKILLBOARD_WORKFLOW:-${shellQuote(options.workflow)}}
+SKILLBOARD_BIN=${shellQuote(options.command)}
+SKILLBOARD_CONFIG=${shellQuote(options.configPath)}
+SKILLBOARD_SKILLS=${shellQuote(options.skillsRoot)}
+SKILLBOARD_WORKFLOW=${shellQuote(options.workflow)}
 
 if [ "\${SKILLBOARD_SKILL_ID:-}" != "" ]; then
   skill_id="$SKILLBOARD_SKILL_ID"
@@ -72,8 +72,8 @@ else
   exit 64
 fi
 
-# Split SKILLBOARD_BIN so local hook configs can use commands like:
-#   SKILLBOARD_BIN="node bin/skillboard.mjs"
+# Split the install-time command so hooks can use commands like:
+#   --skillboard-bin "node bin/skillboard.mjs"
 # Paths containing spaces should be provided through an environment wrapper.
 set -- $SKILLBOARD_BIN
 exec "$@" guard use "$skill_id" --workflow "$SKILLBOARD_WORKFLOW" --config "$SKILLBOARD_CONFIG" --skills "$SKILLBOARD_SKILLS"

package/src/lifecycle-cli.mjs

@@ -37,17 +37,23 @@ export async function runInitCommand(options, stdout, runtime = defaultRuntime()
 }
 
 export async function runUninstallCommand(options, stdout) {
-  if (options.get("remove-config") === "true" && options.get("reset-config") === "true") {
+  const removeConfig = options.get("remove-config") === "true";
+  const resetConfig = options.get("reset-config") === "true";
+  const purge = options.get("purge") === "true";
+  if (removeConfig && resetConfig) {
     throw new Error("--remove-config and --reset-config are mutually exclusive");
   }
+  if (removeConfig && purge) {
+    throw new Error("--remove-config cannot be combined with --purge");
+  }
   const root = resolve(options.get("dir") ?? ".");
   const result = await uninstallProject({
     root,
     dryRun: options.get("dry-run") === "true",
-    removeConfig: options.get("remove-config") === "true",
-    resetConfig: options.get("reset-config") === "true",
-    removeReports: options.get("remove-reports") === "true",
-    removeHooks: options.get("remove-hooks") === "true",
+    removeConfig,
+    resetConfig: resetConfig || purge,
+    removeReports: options.get("remove-reports") === "true" || purge,
+    removeHooks: options.get("remove-hooks") === "true" || purge,
     removeEmptyDirs: options.get("keep-empty-dirs") !== "true"
   });
   stdout.write(`${result.dryRun ? "Dry run: " : ""}Uninstalled SkillBoard: ${root}\n`);
@@ -86,7 +92,7 @@ function writeSafetyDefault(stdout, safety) {
     stdout.write(`- ${safety.automatic} automatic skills enabled by existing policy.\n`);
   }
   stdout.write("- Imported local skills are manual-only.\n");
-  stdout.write("- Runtime/plugin/system skills are quarantined until reviewed.\n");
+  stdout.write("- Runtime/plugin/system skills require source review before manual activation.\n");
   stdout.write(`- ${safety.automatic} automatic skills enabled\n`);
   stdout.write(`- ${safety.manualOnly} manual-only skills available\n`);
   stdout.write(`- ${safety.routerOnly} router-only skills available\n`);

package/src/lifecycle-content.mjs

@@ -47,9 +47,9 @@ Your responsibility is to answer skill availability questions from SkillBoard, t
 
 ## Operations
 
-- Source trust: run \`skillboard audit sources --config skillboard.config.yaml --skills skills\` before trusting newly imported external skill sources; after review, use \`skillboard review install-unit <unit-id> --trust-level reviewed --config skillboard.config.yaml --skills skills\`.
+- Source trust: run \`skillboard audit sources --config skillboard.config.yaml --skills skills\` before trusting newly imported external skill sources; after review, use \`skillboard review install-unit <unit-id> --trust-level reviewed --config skillboard.config.yaml --skills skills\`. Unreviewed runtime sources are a one-time review decision, not a default block recommendation; after review, activate only the needed quarantined skills as manual-only workflow skills and use ask-after policy suggestions for future preferences.
 - Health: run \`skillboard doctor --config skillboard.config.yaml --skills skills\` or \`skillboard status --config skillboard.config.yaml --skills skills --json\`; add \`--strict\` when review-needed safe mode should fail automation.
-- Hook action cards: prefer \`skillboard apply-action <action-id> --yes --json\`. The underlying manual preview is \`skillboard hook install --workflow <name> --config skillboard.config.yaml --skills skills --out .skillboard/hooks/<name>-guard.sh --dry-run --json\`; inspect \`planned.preview.shell\` before materializing an executable guard hook outside the action-card control loop.
+- Hook action cards: prefer \`skillboard apply-action <action-id> --yes --json\`. The underlying manual preview is \`skillboard hook install --workflow <name> --config skillboard.config.yaml --skills skills --out .skillboard/hooks/<name>-guard.sh --dry-run --json\`; inspect \`planned.preview.shell\` before materializing an executable guard hook outside the action-card control loop. Generated hooks pin the install-time SkillBoard command, config, skills root, and workflow; set those values with hook install options such as \`--skillboard-bin\`, not runtime environment overrides.
 - Inventory/import growth: run \`skillboard inventory refresh --dry-run --config skillboard.config.yaml\` after installing local skill packs, plugins, workflow bundles, or harnesses; run \`skillboard import --profile <id-or-path> --source-root <repo> --out .skillboard/reports/import-fragment.yaml\` after installing a new skill repository, then review the fragment before merging it into \`skillboard.config.yaml\`.
 - Prefer workflow-scoped skills over global skill invocation. Only \`global-meta\` skills may be treated as globally available.
 
@@ -88,7 +88,10 @@ For hook action cards, prefer the bridge control loop with
 \`skillboard apply-action <action-id> --yes --json\`. These raw hook commands
 are the underlying manual detail: preview the JSON plan first and inspect
 \`planned.preview.shell\` before materializing an executable guard hook.
-The generated script delegates to \`skillboard guard use\` and can be wired into
-the hook mechanism of the active harness.
+Generated hooks pin the install-time SkillBoard command, config, skills root,
+and workflow; set those values with hook install options such as
+\`--skillboard-bin\`, not runtime environment overrides. The generated script
+delegates to \`skillboard guard use\` and can be wired into the hook mechanism of
+the active harness.
 `;
 }

package/docs/plans/20260625-080025-skillboard-mvp-review.md

@@ -1,189 +0,0 @@
-# skillboard-mvp-review
-
-- Skill: tdd-work-continuity
-- Agent: hermes
-- Created: 2026-06-25T08:00:25Z
-- Updated: 2026-06-25T10:05:00Z
-- Workdir: /home/nyxxir/skillboard
-- Status: completed
-
-## Goal
-
-SkillBoard(`skill-control-plane`)의 MVP 기능과 낶부 도메인 설계를 검토하고, **처음 사용자가 skill을 가져다 붙이고 이용 및 삭제하는 불편을 해소하는 방향인지**, **도메인 설계가 적합하고 확장 가능한지**를 평가한다. 이전 대화에서 제안한 4.1~4.3 UX 개선 항목도 포함된 실행 계획을 문서화한다.
-
-## Context
-
-- Repo: `/home/nyxxir/skillboard`
-- Relevant files:
-  - `src/cli.mjs` — CLI 라우터
-  - `src/control.mjs` — skill/workflow/harness/capability CRUD, `can-use`, `guard`, trust/source 분류
-  - `src/domain/rules/*.mjs` — 정책 규칙 엔진
-  - `src/workspace.mjs` — config 파싱, `SKILL.md` frontmatter 파싱
-  - `src/agent-inventory.mjs` — 설치된 agent skill 자동 스캔/병합
-  - `src/brief-cli.mjs`, `src/brief-renderer.mjs`, `src/advisor.mjs` — AI/사용자 브리핑
-  - `src/impact.mjs`, `src/reconcile.mjs` — 영향도/재조정 분석
-  - `src/init.mjs`, `src/uninstall.mjs` — 생명주기
-- Constraints:
-  - MVP 단계, npm publish 전 (`version: 0.1.0`)
-  - Node.js >= 20, ESM, yaml 의존성 하나
-  - cross-platform CI (ubuntu/macOS/windows × node 20/22)
-
-## Findings Summary
-
-### 1. 도메인 설계: 적합하고 확장 가능함 (Score: 8/10)
-
-**핵심 엔티티 5개**가 skill 생태계의 실제 관심사를 잘 반영한다.
-
-| Entity | 역할 | 적합성 |
-|--------|------|--------|
-| `skills` | 선언된 스킬의 상태/호출방식/노출범위 | ✅ 적절. status/invocation/exposure 3중 분리로 정책 표현력 높음 |
-| `capabilities` | 역할 기반 스킬 추상화 | ✅ 적절. canonical/alternatives/default_policy로 교체/대안 추천 가능 |
-| `workflows` | 스킬이 활성화되는 맥락 | ✅ 적절. active_skills/blocked_skills/required_capabilities로 명시적 제어 |
-| `harnesses` | runtime/command 제공자 추적 | ✅ 적절. harness 제거 시 workflow 영향도 파악 가능 |
-| `install_units` | plugin/marketplace/harness 등의 부모 단위 | ✅ 매우 적절. skill 평탄화 문제 해결 |
-
-**확장 가능성**
-- `INSTALL_UNIT_KIND_VALUES`에 `skill`, `plugin`, `marketplace`, `harness`, `mcp-server`, `hook`, `agent`, `lsp`, `custom`을 두어 새로운 runtime primitive 추가가 용이함.
-- `source_classes.mjs`의 우선순위/분류 함수가 데이터 기반으로 되어 있어 새 source class 추가가 쉬움.
-- `source profile` 어댑터 모델이 하드코딩을 피하고 데이터 주도 import를 지향함.
-
-**위험 요소**
-- `src/control.mjs`가 1000줄에 달해 단일 책임 위반. `can-use`, CRUD, trust/source, YAML 쓰기, hook 설치 등이 한 파일에 있어 장기 유지보수 부담.
-- `status` 값이 14개로 많고, `status`와 `invocation` 간의 유효 조합 규칙이 복잡(`SKILL-STATUS-001`). 새로운 상태 추가 시 규칙 행렬이 기하급수적으로 늘어날 수 있음.
-- `capability`가 workflow-scoped `required_capabilities`와 global `capabilities`로 이중 정의됨. 의도는 명확하지만 사용자 입장에서 학습 곡선이 있음.
-
-### 2. 사용자 불편 해소 vs 가중
-
-#### 해소하는 설계
-
-| 기능 | 불편 해소 메커니즘 |
-|------|------------------|
-| `init` 시 자동 스캔 + `active-manual` 연결 | 기존 수동 스킬을 따로 등록하지 않아도 `can-use`/`guard`로 계속 사용 가능 |
-| `deny-by-default` + quarantine | 설치만으로 AI가 스킬을 부르는 것을 원천 차단 |
-| `impact disable` | 스킬 제거 전 영향받는 workflow/capability를 사전에 노출 |
-| 대부분의 mutating 명령에 `--dry-run` | 실수로 config를 망치는 위험 감소 |
-| `brief --json` | 에이전트가 정책을 직접 해석하지 않고 control plane에 질의 |
-| `uninstall`이 사용자 파일 보존 | 도구를 빼도 skill 파일과 사용자 config는 남음 |
-
-#### 가중할 수 있는 설계
-
-| 지점 | 불편 가능성 | 심각도 |
-|------|------------|--------|
-| 매번 `--config skillboard.config.yaml --skills skills` 필요 | 일상 명령이 번거로움 | 중간 |
-| `SKILL.md` frontmatter 누락 시 메시지가 모호함 | 처음 사용자가 문서를 찾아야 함 | 높음 |
-| `doctor` 출력이 길고 `--summary` 부재 | 매일 보기에 피로함 | 중간 |
-| `add workflow` 시 `--harness`를 명시해야 함 | harness 개념을 모르는 사용자에게 진입 장벽 | 중간 |
-| `status`/`invocation`/`exposure`/`trust_level` 용어가 많음 | 정책 도구이므로 불가피하지만, 온볭딩 문서가 중요 | 중간 |
-| `init` 후 생성되는 config가 수십 개 스킬로 즉시 커짐 | 실제로 설치된 게 많으면 압도적 | 낮음~중간 |
-
-**종합 판단**: 보안/통제를 얻는 대가로 적정 수준의 복잡성을 요구한다. 다만 **처음 사용자의 첫 5분**을 더 부드럽게 만들면 Adoption이 크게 올라갈 것이다.
-
-### 3. MVP 기능 검증 결과
-
-| 기능 | 상태 | 비고 |
-|------|------|------|
-| `init` | ✅ 정상 | bridge 파일, config, 디렉토리 생성, 자동 스캔 |
-| `doctor`/`status` | ✅ 정상 | safe-mode, strict 모드, JSON 출력 |
-| `brief` | ✅ 정상 | text/JSON, action cards, unknown workflow 처리 |
-| `add skill/workflow/harness` | ✅ 정상 | dry-run, 자동 status 승격 |
-| `activate`/`block`/`quarantine` | ✅ 정상 | workflow-scoped |
-| `can-use`/`guard` | ✅ 정상 | 정책 위반 시 거부 |
-| `impact disable` | ✅ 정상 | affected workflows/alternatives/risk |
-| `remove skill` | ✅ 정상 | 참조 시 거부, `--force`로 정리 |
-| `uninstall` | ✅ 정상 | 보수적 제거, dry-run |
-| `inventory refresh`/`detect` | ✅ 정상 | runtime component 감지 |
-| `sources refresh`/`audit` | ✅ 정상 | Git source digest pin |
-| `import`/`merge` | ✅ 정상 | built-in profiles |
-| `check` | ✅ 정상 | policy reference/rules |
-| `dashboard` | ✅ 정상 | markdown 보고서 |
-| `hook install` | ✅ 정상 | dry-run preview |
-
-### 4. 핵심 코드 품질 관찰
-
-- **정책 엔진**: `src/domain/rules/*.mjs`가 rule-id 기반으로 깔끔하게 분리되어 있어 새 규칙 추가가 쉬움.
-- **workspace 로딩**: `workspace.mjs`가 config 파싱과 설치 skill discovery를 분리. `SKILL.md` frontmatter 강제는 정합성을 위해 필요하지만, 에러 메시지가 개선되어야 함.
-- **control.mjs**: 거대 파일. CRUD, policy runtime, source classification, hook 설치 등을 분리하면 가독성과 테스트 용이성이 향상.
-- **writeCheckedConfig**: 임시 파일에 쓰고 policy + usability 검증 후 rename하는 방식은 안전함. dry-run과 실제 적용의 경계도 명확.
-- **agent-inventory**: detector 기반 스캔이 확장 가능. 다만 detector matching이 경로 suffix에 의존해 Windows/Linux 경로를 모두 고려한 점은 긍정적.
-
-## Plan
-
-### Phase 1: 첫 5분 UX 다듬기 (4.1)
-
-- [x] `workspace.mjs`의 `parseSkillFrontmatter` 에러 메시지 개선
-  - "SKILL.md is missing YAML frontmatter" → 필요한 frontmatter 예시와 docs/user-flow.md 링크 포함
-  - 예상 영향: `src/workspace.mjs` 1함수, test 1~2개 추가
-- [x] `add workflow`에서 `--harness` 누락 시 usage dump 대신 사용 가능한 harness 목록 제시
-  - 예상 영향: `src/cli.mjs` 또는 `src/control.mjs`의 `addWorkflow`
-- [x] `doctor`에 `--summary` 플래그 추가 (또는 기본 출력에서 1줄 status + 핵심 warnings만)
-  - 예상 영향: `src/doctor.mjs`, `src/report.mjs` 수정
-- [x] CLI 글로벌 defaults 파일/디렉토리 탐지: `--config`, `--skills` 미지정 시 현재 디렉토리의 `skillboard.config.yaml`과 `skills/`를 기본으로 사용하도록 개선
-  - 예상 영향: `src/cli.mjs` option parser, test 보강
-
-### Phase 2: 생태계 연결 및 문서 (4.2)
-
-- [x] `CONTRIBUTING.md` 작성: 개발 환경, 테스트 실행, source profile 추가 방법
-- [x] built-in profile 추가 가이드 문서화 (`docs/adapters.md` 보강 또는 `docs/profiles.md` 신규)
-- [x] README의 install 전/후 명령어 섹션 정리 (`skillboard` vs `node bin/skillboard.mjs` 구분 강조)
-- [x] 본 프로젝트에 `AGENTS.md`/`CLAUDE.md` bridge 적용 검토 (dogfooding)
-
-### Phase 3: 성능 및 구조 (4.3)
-
-- [x] `npm test` 실행 시간 프로파일링
-  - 병목이 되는 CLI 통합 테스트 식별
-  - 가능하다면 독립적인 단위 테스트와 통합 테스트 분리 (`npm run test:unit`, `npm run test:integration`)
-- [x] `src/control.mjs` 분리
-  - `skill-crud.mjs`, `workflow-crud.mjs`, `trust-source.mjs`, `can-use-guard.mjs`, `config-write.mjs` 등으로 쪼개기
-  - 예상 영향: 낶부 구조 개선, 기존 테스트 그대로 통과해야 함
-- [x] `doctor`/`brief`의 중복 workspace 로딩 최소화 (cache 또는 단일 로드 경로)
-
-### Phase 4: 도메인 정제 (선택, 높은 가치)
-
-- [x] `status`/`invocation` 매트릭스 검토: 14×7 조합 중 실제로 사용되는 조합을 문서화하고, 불필요한 조합은 deprecate 또는 명시적 금지
-- [x] `capability`의 global 정의와 workflow-scope `required_capabilities` 관계를 docs에 명확히 시각화
-- [x] `install_unit`의 `trust_level`과 `permission_risk` 조합에 따른 자동 권고 정책을 advisor action cards로 노출
-
-## TDD Notes
-
-- Red: Add failing tests for newly invalid status/invocation combos, capability docs, trust/risk action cards.
-- Green: Implement matrix, docs, and action card logic.
-- Refactor: `control.mjs` split into `src/control/*.mjs` modules; public API preserved.
-
-## Verification
-
-- Commands to run:
-  - `npm run diagnostics`
-  - `npm run test:unit`
-  - `npm run test:integration`
-  - `npm run check`
-  - `node bin/skillboard.mjs brief --config skillboard.config.yaml --skills skills`
-  - `git diff --check`
-- Results:
-  - TypeScript diagnostics: ✅
-  - `npm run test:unit`: 47 passed
-  - `npm run test:integration`: 103 passed
-  - `npm run check`: 161 passed
-  - CLI smoke test: ✅
-  - `git diff --check`: ✅
-
-## Decisions
-
-- **즉시 개선 권장**: 4.1 frontmatter 에러 메시지, `--config/--skills` 기본값, `doctor --summary`
-- **중기 개선 권장**: `control.mjs` 분리, test suite 분리, `CONTRIBUTING.md`
-- **도메인 설계는 유지**: 5개 엔티티 구조와 deny-by-default 정책은 변경하지 않음. 세부 상태/호출 매트릭스만 정제
-- **변경사항은 unstaged로 보관**: 사용자가 직접 커밋 지시 전까지 git index에 추가하지 않음
-
-## Resume State
-
-- Done: Phase 1~4 모두 완료. 모든 테스트 통과. 문서/워크로그 정리 완료.
-- In progress: 없음.
-- Next command: 사용자가 커밋/푸시 지시 또는 추가 개선 항목 제시
-- Open risks:
-  - `.skillboard/`와 `.omo/` 등 untracked artifact는 별도 정리 필요
-  - npm pack 시 포함 여부는 `test/package.test.mjs`에서 검증 완료
-
-## Progress Log
-
-- 2026-06-25T08:00:25Z: Plan created.
-- 2026-06-25T08:45:00Z: Domain audit, friction analysis, and improvement plan written.
-- 2026-06-25T10:05:00Z: Phase 1~4 implementation completed. All 161 tests passing.

package/docs/plans/README.md

@@ -1,20 +0,0 @@
-# Agent Handoff Plans
-
-This directory contains durable plans that can be picked up by another agent
-(such as Hermes) when the original author is not available.
-
-## Conventions
-
-- Each plan file is named `<timestamp>-<slug>.md`.
-- The `Status:` field in the frontmatter controls the lifecycle:
-  - `pending` — waiting for an agent to pick it up
-  - `assigned` — an agent is currently working on it
-  - `consumed` — the agent has finished the planned work
-- Agents should only pick up files with `Status: pending`.
-- After picking up a plan, change the status to `assigned` and commit.
-- After completing the work, change the status to `consumed` and commit.
-
-## Current Plans
-
-- `20260625-080025-skillboard-mvp-review.md` — SkillBoard MVP feature/domain
-  review and UX improvement plan (Status: completed)

package/docs/plans/skillboard-variant-lifecycle-handoff.md

@@ -1,56 +0,0 @@
-# SkillBoard Variant Lifecycle Handoff Plan
-
-This document was the handoff point for continuing the SkillBoard variant lifecycle implementation in `/home/nyxxir/skillboard`.
-
-## Status
-
-Completed on 2026-06-29.
-
-The authoritative execution plan was `.omo/plans/skillboard-variant-lifecycle.md`; all Todos 1-8 and final verification wave F1-F4 were completed. Ignored orchestration artifacts under `.omo/` and `.agent-work/` contain the detailed evidence and continuity logs.
-
-## Implemented Scope
-
-The feature adds a manual, auditable lifecycle for cross-agent skill variants:
-
-- `skillboard variant fork`
-- `skillboard variant status`
-- `skillboard variant approve`
-- `skillboard variant reset`
-- nested `skills.<id>.variant` metadata
-- digest-backed raw `SKILL.md` snapshots
-- documentation and tests for manual cross-agent adaptation
-
-## Product Decisions Preserved
-
-- `variant add` remains the existing immediate policy-registration command.
-- New lifecycle commands are additive: `fork`, `status`, `approve`, `reset`.
-- A draft fork is policy-valid but not callable:
-  - top-level `status: candidate`
-  - top-level `invocation: manual-only`
-  - no workflow active/preferred/fallback role until approval
-- `variant.status` is nested lifecycle metadata only. Top-level skill statuses were not expanded with `draft` or `approved`.
-- Snapshot files are raw `SKILL.md` content only.
-- Snapshot paths are config-relative and stay under `.skillboard/variant-snapshots/`.
-- Drift is computed from file digests; `drifted` is not persisted in config.
-- The implementation does not add automatic prompt conversion, LLM calls, new dependencies, or prompt rewriting.
-
-## Verification Summary
-
-Final verification passed:
-
-- `npm run check` → 244/244 tests pass.
-- Focused lifecycle suite → 24/24 tests pass.
-- Manual CLI QA evidence was written under `.omo/evidence/manual-variant-lifecycle/`.
-- F1-F4 evidence files were written under `.omo/evidence/`.
-- Independent final no-edit review passed with no blockers.
-- `git diff --check` and untracked whitespace checks passed.
-
-## Final Commit
-
-Planned commit message:
-
-```text
-feat(control): add variant lifecycle management
-```
-
-Do not push unless the user explicitly asks.