@dtlabs/ai-toolkit 0.10.1 → 0.12.0

package/docs/installation.md

@@ -13,7 +13,8 @@ No authentication setup required — it is a public package.
 
 ### Local installation (default)
 
-Copies `.claude/`, `docs/`, and `CLAUDE.md` into the current directory:
+Copies all asset categories from the toolkit's `src/claude/` tree into the target project's `.claude/`
+directory, plus `docs/` and `CLAUDE.md`:
 
 ```bash
 npx @dtlabs/ai-toolkit
@@ -31,9 +32,15 @@ Overwrite existing files without confirmation:
 npx @dtlabs/ai-toolkit --local . --force
 ```
 
+Preview what would change without writing any files (dry run):
+
+```bash
+npx @dtlabs/ai-toolkit --local . --dry-run
+```
+
 ### Global installation
 
-Merges `.claude/agents`, `.claude/skills`, `.claude/commands`, `docs/`, and `CLAUDE.md` into `~/.claude/`:
+Merges all asset categories into `~/.claude/<category>/`, plus `docs/` and `CLAUDE.md`:
 
 ```bash
 npm install -g @dtlabs/ai-toolkit
@@ -46,20 +53,79 @@ Force overwrite:
 ai-toolkit --global --force
 ```
 
+Preview the global install without writing any files:
+
+```bash
+ai-toolkit --global --dry-run
+```
+
+### Asset catalog
+
+The installer derives the list of installable directories from the **asset catalog**
+(`lib/asset-catalog.js`). Each catalog entry defines:
+
+| Field | Description |
+|---|---|
+| `name` | Category name (e.g. `agents`, `skills`) |
+| `sourceDir` | Location inside the package (`src/claude/<name>`) |
+| `runtimeDir` | Destination inside the installed `.claude/` folder (`.claude/<name>`) |
+
+Adding a new category to the catalog automatically includes it in every install — no
+changes to `bin/cli.js` are required.
+
 ### What gets copied where
 
 | Mode | Source (in package) | Destination |
 |---|---|---|
-| Local | `.claude/` | `<target>/.claude/` |
+| Local | `src/claude/agents/` | `<target>/.claude/agents/` |
+| Local | `src/claude/skills/` | `<target>/.claude/skills/` |
+| Local | `src/claude/commands/` | `<target>/.claude/commands/` |
+| Local | `src/claude/workflows/` | `<target>/.claude/workflows/` |
+| Local | `src/claude/scripts/` | `<target>/.claude/scripts/` |
 | Local | `docs/` | `<target>/docs/` |
 | Local | `CLAUDE.md` | `<target>/CLAUDE.md` |
-| Global | `.claude/agents/` | `~/.claude/agents/` |
-| Global | `.claude/skills/` | `~/.claude/skills/` |
-| Global | `.claude/commands/` | `~/.claude/commands/` |
+| Global | `src/claude/agents/` | `~/.claude/agents/` |
+| Global | `src/claude/skills/` | `~/.claude/skills/` |
+| Global | `src/claude/commands/` | `~/.claude/commands/` |
+| Global | `src/claude/workflows/` | `~/.claude/workflows/` |
+| Global | `src/claude/scripts/` | `~/.claude/scripts/` |
 | Global | `docs/` | `~/.claude/docs/` |
-| Global | `CLAUDE.md` | `~/.claude/CLAUDE.md` |
+| Global | `CLAUDE.global.md` | `~/.claude/CLAUDE.md` |
+
+> The toolkit sources assets from `src/claude/` (versioned, purity-guarded), not from
+> `.claude/` at the project root. The `.claude/` folder in the toolkit repository is for
+> personal configuration only (gitignored).
 
-> The asymmetry is intentional: locally you mirror the package layout, globally you merge into Claude Code's standard folder structure.
+---
+
+## Upgrade path
+
+When a newer version of the toolkit is installed over an existing one, the installer
+automatically detects and removes **orphaned files** — files that were part of a previous
+installation but no longer exist in the current package.
+
+Orphaned files are moved to `.claude/.ai-toolkit-trash/<timestamp>/` rather than
+deleted outright, so they can be recovered if needed. Each upgrade session uses a
+unique ISO-timestamp subdirectory, ensuring that repeated upgrades never overwrite
+previously trashed files.
+
+The manifest (`.claude/.ai-toolkit-manifest.json`) is updated after each install to
+reflect the current file set. The trash directory is excluded from the manifest automatically.
+
+---
+
+## Developer workflow
+
+When developing the toolkit itself, use the convenience scripts in `package.json`:
+
+```bash
+# Preview global install without writing files
+npm run toolkit:dev-install-global
+# (this runs --global --dry-run first, then --global)
+
+# Validate that no test files have crept into src/claude/
+npm run toolkit:validate-purity
+```
 
 ---
 

package/docs/reference.md

@@ -41,7 +41,7 @@ Cheatsheet of every skill, command, agent, and procedure shipped with this toolk
 
 ---
 
-## Skills (in `.claude/skills/`)
+## Skills (in `src/claude/skills/`, installed to `.claude/skills/`)
 
 Invoked as `/<name>`. Comprehensive workflows that may chain multiple agents.
 
@@ -68,7 +68,7 @@ Invoked as `/<name>`. Comprehensive workflows that may chain multiple agents.
 
 ---
 
-## Commands (in `.claude/commands/`)
+## Commands (in `src/claude/commands/`, installed to `.claude/commands/`)
 
 Invoked as `/<name>`. Lightweight shortcuts focused on the current state of the repo. Do **not** spawn long-running workflows.
 
@@ -89,7 +89,7 @@ Invoked as `/<name>`. Lightweight shortcuts focused on the current state of the
 
 ---
 
-## Agents (in `.claude/agents/`)
+## Agents (in `src/claude/agents/`, installed to `.claude/agents/`)
 
 Invoked via the Agent tool with `subagent_type`. Specialised sub-conversations that produce a single deliverable.
 
@@ -160,6 +160,52 @@ Reusable text procedures referenced by agents. **Override locally** by placing a
 
 ---
 
+## CLI Commands (`ai-toolkit <command>`)
+
+The `ai-toolkit` binary (from `bin/cli.js`) provides commands for runtime asset resolution, script execution, and diagnostics.
+
+### Asset resolution
+
+| Command | Purpose | Exit |
+|---|---|---|
+| `ai-toolkit resolve-asset <relativePath> [--project <dir>] [--home <dir>]` | Resolve a runtime asset path using the six-phase algorithm; stdout=resolved path | 0 success / 1 error |
+| `ai-toolkit run-asset <relativePath> [--project <dir>] [--home <dir>] [-- ...args]` | Resolve and execute a `scripts/*.js` asset; propagates exit code | script exit code |
+| `ai-toolkit list-assets [--category <name>] [--format json\|plain] [--project <dir>] [--home <dir>]` | List installed runtime assets from `.claude/<category>/`; exit 0 even when empty | 0 always |
+| `ai-toolkit doctor-resolution [--project <dir>] [--home <dir>]` | Doctor resolution diagnostics: reports presence mode, install mode, version, completeness gaps | 0 / 1 |
+| `ai-toolkit validate-purity [<sourceDir>]` | Check that `src/claude/` contains no test or fixture files | 0 clean / 1 violations |
+
+### `resolveClaudeRuntimeAsset(relativePath, options)` — resolver API
+
+The core runtime resolution algorithm exposed from `bin/cli.js`:
+
+```javascript
+const { resolveClaudeRuntimeAsset } = require('@dtlabs/ai-toolkit/bin/cli');
+const resolvedPath = resolveClaudeRuntimeAsset('agents/developer-backend.md', {
+  projectDir: '/path/to/project',   // optional; defaults to process.cwd()
+  home: '/path/to/home',            // optional; defaults to os.homedir()
+});
+```
+
+Six-phase algorithm:
+- **Phase 0**: Input validation (relativePath must be a non-empty string)
+- **Phase A**: Presence detection — checks manifest (condA), version stamp (condB), payload files (condC)
+- **Phase B**: Mode decision — local (project `.claude/`) vs global (`~/.claude/`)
+- **Phase C**: Metadata warnings (version stamp missing, mode ambiguity)
+- **Phase D**: Completeness check — verifies requested file exists, validates catalog membership
+- **Phase E**: Return resolved absolute path with confinement check
+
+### Doctor resolution
+
+`ai-toolkit doctor-resolution` reports the full resolution diagnosis for a project:
+- Detected presence mode (manifest / stamp / payload / none)
+- Install mode (local / global)
+- Installed version
+- Catalog completeness gaps (files present in asset catalog but missing from runtime)
+
+Used by workflow agents to verify installation via doctor resolution before dispatching asset-dependent tasks.
+
+---
+
 ## Typical flows
 
 ### Flow 1 — Brand new feature, end-to-end
@@ -217,12 +263,14 @@ Then delegate manually to the suggested agent, or rerun `/implement-feature` to
 
 ## File locations
 
-| What | Local install | Global install |
-|---|---|---|
-| Agents | `<project>/.claude/agents/` | `~/.claude/agents/` |
-| Skills | `<project>/.claude/skills/` | `~/.claude/skills/` |
-| Commands | `<project>/.claude/commands/` | `~/.claude/commands/` |
-| Procedures | `<project>/docs/procedures/` | `~/.claude/docs/procedures/` |
-| Feature docs | `<project>/docs/features/FTR-NNN-slug/` | — |
-| Assessment docs | `<project>/docs/assessments/ASSESS-NNN/` | — |
-| This reference | `<project>/docs/reference.md` | `~/.claude/docs/reference.md` |
+| What | Source (toolkit repo) | Local install | Global install |
+|---|---|---|---|
+| Agents | `src/claude/agents/` | `<project>/.claude/agents/` | `~/.claude/agents/` |
+| Skills | `src/claude/skills/` | `<project>/.claude/skills/` | `~/.claude/skills/` |
+| Commands | `src/claude/commands/` | `<project>/.claude/commands/` | `~/.claude/commands/` |
+| Workflows | `src/claude/workflows/` | `<project>/.claude/workflows/` | `~/.claude/workflows/` |
+| Scripts | `src/claude/scripts/` | `<project>/.claude/scripts/` | `~/.claude/scripts/` |
+| Procedures | `docs/procedures/` | `<project>/docs/procedures/` | `~/.claude/docs/procedures/` |
+| Feature docs | — | `<project>/docs/features/FTR-NNN-slug/` | — |
+| Assessment docs | — | `<project>/docs/assessments/ASSESS-NNN/` | — |
+| This reference | `docs/reference.md` | `<project>/docs/reference.md` | `~/.claude/docs/reference.md` |

package/lib/asset-catalog.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const ASSET_CATEGORIES = [
+  {
+    name: 'agents',
+    sourceDir: 'src/claude/agents',
+    runtimeDir: '.claude/agents',
+    description: 'Agent definition files (.md with YAML frontmatter)',
+  },
+  {
+    name: 'commands',
+    sourceDir: 'src/claude/commands',
+    runtimeDir: '.claude/commands',
+    description: 'Slash command definition files',
+  },
+  {
+    name: 'skills',
+    sourceDir: 'src/claude/skills',
+    runtimeDir: '.claude/skills',
+    description: 'User-invocable skill directories with SKILL.md',
+  },
+  {
+    name: 'workflows',
+    sourceDir: 'src/claude/workflows',
+    runtimeDir: '.claude/workflows',
+    description: 'Claude Code Workflow orchestrator scripts (.js)',
+  },
+  {
+    name: 'scripts',
+    sourceDir: 'src/claude/scripts',
+    runtimeDir: '.claude/scripts',
+    description: 'Utility and helper scripts',
+  },
+];
+
+function getAssetCategories() {
+  return ASSET_CATEGORIES;
+}
+
+function getCategoryByName(name) {
+  return ASSET_CATEGORIES.find(cat => cat.name === name);
+}
+
+if (require.main === module) {
+  console.log(JSON.stringify(ASSET_CATEGORIES, null, 2));
+} else {
+  module.exports = {
+    ASSET_CATEGORIES,
+    getAssetCategories,
+    getCategoryByName,
+  };
+}