agent-skillboard 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## Unreleased
 
+## 0.2.4 — 2026-07-03
+
+### Changed
+
+- `skillboard uninstall --purge` now removes the entire `.skillboard/` project
+  state directory, including source caches, rollout logs, variant snapshots, and
+  profiles, while preserving local skill files.
+
+## 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

package/README.md

@@ -13,7 +13,8 @@ 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.
@@ -117,6 +118,17 @@ 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, bridge blocks, and the entire
+`.skillboard/` project state directory 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

@@ -311,6 +311,20 @@ 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, 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`.
@@ -330,7 +344,9 @@ 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/`.
+the most common SkillBoard-owned lifecycle scaffolding while preserving local
+`skills/`. Use `--purge` instead when no `.skillboard/` project state should
+remain at all.
 
 ## Upper-Layer Control
 

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

@@ -261,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
 
@@ -280,14 +280,14 @@ 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,
+removes generated dashboard and impact reports, and removes the entire
+`.skillboard/` project state directory, including hooks, source caches, rollout
+logs, variant snapshots, and profiles. Local `skills/` files stay in place.

package/docs/versioning.md

@@ -8,7 +8,7 @@ source profiles, and the generated lockfile.
 
 ## Status
 
-Current package version: `0.2.2`
+Current package version: `0.2.4`
 
 Current config schema version:
 
@@ -59,8 +59,8 @@ must call them out clearly.
 Suggested tags:
 
 - `v0.1.0-alpha`: first public GitHub alpha.
-- `v0.2.2`: one-time runtime source review before manual activation, ask-after
-  skill routing, README benefit-first positioning,
+- `v0.2.4`: 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.
@@ -194,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.2`
-  for package version `0.2.2`.
+- Push a version tag that exactly matches `package.json`, for example `v0.2.4`
+  for package version `0.2.4`.
 - 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.
@@ -229,6 +229,22 @@ completion notes:
 - update README quick-start to verify the installed version before running
   policy commands.
 
+## 0.2.4 Completion Notes
+
+- broaden `skillboard uninstall --purge` from reports/hooks cleanup to removal
+  of the full `.skillboard/` project state directory, covering source caches,
+  rollout logs, variant snapshots, profiles, hooks, and reports while preserving
+  local skill files.
+
+## 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-skillboard",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Let AI agents pick and use allowed skills in each workflow.",
   "keywords": [
     "ai-agent",

package/src/advisor/actions.mjs

@@ -199,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),

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();
   }
@@ -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:",
+    "  Removes SkillBoard config, bridge blocks, and the entire .skillboard/ project state directory.",
+    "  This includes reports, hooks, source caches, rollout logs, variant snapshots, and profiles.",
+    "  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/lifecycle-cli.mjs

@@ -37,17 +37,24 @@ 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,
+    removeProjectState: purge,
     removeEmptyDirs: options.get("keep-empty-dirs") !== "true"
   });
   stdout.write(`${result.dryRun ? "Dry run: " : ""}Uninstalled SkillBoard: ${root}\n`);

package/src/uninstall.mjs

@@ -19,14 +19,6 @@ export async function uninstallProject(options) {
     recordFileResult(filename, result, { removed, updated, preserved });
   }
 
-  for (const entry of generatedFiles(root)) {
-    const result = await removeGeneratedFile(entry.path, entry.expected, dryRun);
-    if (result === "removed") {
-      plannedRemovedPaths.add(entry.path);
-    }
-    recordFileResult(entry.label, result, { removed, updated, preserved });
-  }
-
   if (options.resetConfig === true) {
     const path = join(root, "skillboard.config.yaml");
     const result = await removeConfigFile(path, dryRun);
@@ -45,7 +37,24 @@ export async function uninstallProject(options) {
     preserved.push("skillboard.config.yaml");
   }
 
-  if (options.removeReports === true) {
+  if (options.removeProjectState === true) {
+    const path = join(root, ".skillboard");
+    const result = await removeProjectStateDir(path, dryRun);
+    if (result === "removed") {
+      plannedRemovedPaths.add(path);
+    }
+    recordFileResult(".skillboard", result, { removed, updated, preserved });
+  } else {
+    for (const entry of generatedFiles(root)) {
+      const result = await removeGeneratedFile(entry.path, entry.expected, dryRun);
+      if (result === "removed") {
+        plannedRemovedPaths.add(entry.path);
+      }
+      recordFileResult(entry.label, result, { removed, updated, preserved });
+    }
+  }
+
+  if (options.removeReports === true && options.removeProjectState !== true) {
     const path = join(root, ".skillboard", "reports");
     const result = await removeGeneratedDir(path, dryRun);
     if (result === "removed") {
@@ -54,7 +63,7 @@ export async function uninstallProject(options) {
     recordFileResult(".skillboard/reports", result, { removed, updated, preserved });
   }
 
-  if (options.removeHooks === true) {
+  if (options.removeHooks === true && options.removeProjectState !== true) {
     const path = join(root, ".skillboard", "hooks");
     const result = await removeGeneratedDir(path, dryRun);
     if (result === "removed") {
@@ -66,7 +75,8 @@ export async function uninstallProject(options) {
   if (options.removeEmptyDirs !== false) {
     for (const dir of emptyDirs(root, {
       skipReports: options.removeReports === true,
-      skipHooks: options.removeHooks === true
+      skipHooks: options.removeHooks === true,
+      skipSkillboard: options.removeProjectState === true
     })) {
       const result = await removeEmptyDir(dir.path, dryRun, plannedRemovedPaths);
       if (result === "removed") {
@@ -109,6 +119,9 @@ function emptyDirs(root, options = {}) {
     if (options.skipHooks === true && dir.label === ".skillboard/hooks") {
       return false;
     }
+    if (options.skipSkillboard === true && dir.label.startsWith(".skillboard")) {
+      return false;
+    }
     return true;
   });
 }
@@ -210,6 +223,26 @@ async function removeGeneratedDir(path, dryRun) {
   return "removed";
 }
 
+async function removeProjectStateDir(path, dryRun) {
+  const stats = await pathStats(path);
+  if (stats === null) {
+    return "absent";
+  }
+  if (stats.isSymbolicLink()) {
+    if (!dryRun) {
+      await rm(path);
+    }
+    return "removed";
+  }
+  if (!stats.isDirectory()) {
+    return "preserved";
+  }
+  if (!dryRun) {
+    await rm(path, { recursive: true });
+  }
+  return "removed";
+}
+
 async function removeEmptyDir(path, dryRun, plannedRemovedPaths) {
   const stats = await pathStats(path);
   if (stats === null) {