@soleri/forge 9.3.1 → 9.5.0

package/dist/skills/env-setup/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: env-setup
+description: >
+  Use when a developer needs to set up, fix, or restore a local development environment.
+  Triggers on post-clone setup, project onboarding, first-time running a repo, pulled changes
+  that broke the build, missing or misconfigured dependencies, MODULE_NOT_FOUND or Cannot find
+  module errors, gyp ERR or native module build failures, missing .env files or unknown required
+  environment variables, database setup, Docker compose issues, or connection refused during
+  local dev. Covers Node.js, Python, Rust, Go, Ruby, PHP, and Docker-based projects.
+---
+
+# Environment Setup
+
+Detect what a project needs, diagnose what's missing, and produce an actionable setup checklist.
+
+## Overview
+
+Scan the project root for configuration files, detect the tech stack and dependencies, identify gaps between what's required and what's present, then generate ordered setup steps. Offer to execute each step.
+
+## When to Use
+
+- Just cloned a repo and need to get it running
+- Getting errors after pulling changes (missing deps, env vars, DB migrations)
+- Onboarding to an unfamiliar project
+- Setting up a project on a new machine
+- Docker/container environment not starting
+- Missing `.env` file or environment variables
+
+## Detection Phase
+
+Scan the project root and identify:
+
+### Package Managers & Dependencies
+
+| File               | Stack   | Install Command                                              |
+| ------------------ | ------- | ------------------------------------------------------------ |
+| `package.json`     | Node.js | `npm install` / `yarn` / `pnpm install` (check for lockfile) |
+| `requirements.txt` | Python  | `pip install -r requirements.txt`                            |
+| `pyproject.toml`   | Python  | `pip install -e .` or `poetry install` or `uv sync`          |
+| `Pipfile`          | Python  | `pipenv install`                                             |
+| `Cargo.toml`       | Rust    | `cargo build`                                                |
+| `go.mod`           | Go      | `go mod download`                                            |
+| `Gemfile`          | Ruby    | `bundle install`                                             |
+| `composer.json`    | PHP     | `composer install`                                           |
+
+**Lockfile priority:** If a lockfile exists (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `Pipfile.lock`, `poetry.lock`), use the matching package manager. Don't mix.
+
+### Environment Variables
+
+1. Check for `.env.example`, `.env.sample`, `.env.template`
+2. Check for existing `.env` — if missing, copy from template
+3. Parse template for required variables (lines without defaults or with placeholder values)
+4. Flag variables that need real values (API keys, secrets, database URLs)
+5. **If no template exists:** grep source for `process.env.`, `os.environ`, `env::var`, `os.Getenv` to discover env vars the project actually uses.
+
+### Native Dependencies
+
+| Indicator                                | What It Means                          |
+| ---------------------------------------- | -------------------------------------- |
+| `better-sqlite3`, `sqlite3` in deps      | Needs C++ compiler                     |
+| `node-gyp` in deps or scripts            | Needs Python 3 + C++ toolchain         |
+| `sharp` in deps                          | Needs `libvips`                        |
+| `Cargo.toml` with `[build-dependencies]` | Needs Rust toolchain for build scripts |
+| `setup.py` with `ext_modules`            | Needs C compiler for Python extensions |
+
+### Databases
+
+| File/Config                              | Database         | Setup Needed                 |
+| ---------------------------------------- | ---------------- | ---------------------------- |
+| `docker-compose.yml` with postgres/mysql | PostgreSQL/MySQL | Container + migrations       |
+| `prisma/schema.prisma`                   | Prisma-managed   | `npx prisma migrate dev`     |
+| `drizzle.config.*`                       | Drizzle-managed  | `npx drizzle-kit push`       |
+| `alembic.ini`                            | SQLAlchemy       | `alembic upgrade head`       |
+| `config/database.yml`                    | Rails            | `rails db:create db:migrate` |
+
+### Infrastructure
+
+| File                                          | What It Means                               |
+| --------------------------------------------- | ------------------------------------------- |
+| `docker-compose.yml`                          | Services to start with `docker compose up`  |
+| `Dockerfile`                                  | Can build container locally                 |
+| `Makefile`                                    | Check for `setup`, `install`, `dev` targets |
+| `.tool-versions` / `.node-version` / `.nvmrc` | Required runtime version                    |
+| `turbo.json` / `nx.json` / `lerna.json`       | Monorepo setup                              |
+
+### IDE & Tool Integration
+
+| File                     | Integration                  |
+| ------------------------ | ---------------------------- |
+| `.vscode/`               | VS Code settings, extensions |
+| `.mcp.json` / `mcp.json` | MCP server config            |
+| `.editorconfig`          | Cross-editor formatting      |
+
+## Diagnosis Phase
+
+After detection, check what's present vs needed:
+
+1. **Runtime version** — does installed version match version files?
+2. **Dependencies installed?** — does `node_modules/`, `venv/`, `vendor/` exist?
+3. **Native build tools?** — are compilers available?
+4. **Env file present?** — does `.env` exist when a template does?
+5. **Database reachable?** — can the configured DB URL connect?
+6. **Docker running?** — is Docker daemon running if needed?
+7. **Build artifacts** — does the project need an initial build step?
+
+## Checklist Generation
+
+Produce steps in dependency order:
+
+```
+## Setup Checklist
+
+1. [ ] Install runtime (Node 20.x via nvm)
+2. [ ] Install dependencies (pnpm install)
+3. [ ] Copy environment file (cp .env.example .env)
+4. [ ] Fill in required env vars: DATABASE_URL, API_KEY
+5. [ ] Start Docker services (docker compose up -d)
+6. [ ] Run database migrations (npx prisma migrate dev)
+7. [ ] Build the project (pnpm build)
+8. [ ] Start dev server (pnpm dev)
+```
+
+**Order matters:** runtime -> deps -> env -> infrastructure -> migrations -> build -> run.
+
+After presenting the checklist, offer: "Want me to run these steps for you?"
+
+## Execution Phase
+
+If the user says yes, execute steps sequentially. Stop and ask if:
+
+- A step fails
+- A step requires manual input (API keys, passwords)
+- A step would modify system-level config (global installs, PATH changes)
+
+## Monorepo Handling
+
+If monorepo detected (turbo.json, nx.json, pnpm-workspace.yaml):
+
+1. Install root dependencies first
+2. Ask which package/app the user wants to work on
+3. Check for package-specific setup
+4. Run package-specific setup after root
+
+## Common Mistakes
+
+- **Wrong package manager** — using `npm install` when `yarn.lock` exists. Always check lockfiles first.
+- **Skipping env file** — project crashes on first API call. Always check for templates.
+- **Missing native build tools** — `npm install` fails with gyp errors. Check before installing.
+- **Missing runtime version** — subtle bugs from wrong Node/Python version.
+- **Docker not running** — cryptic "connection refused" errors.
+- **Stale dependencies** — after `git pull`, always re-install if lockfile changed.

package/dist/skills/executing-plans/SKILL.md

@@ -77,6 +77,18 @@ Capture mid-execution learnings with `op:capture_quick` as they happen — don't
 - Forgetting to reconcile the plan after execution (drift data improves future plans)
 - Starting implementation on main/master without explicit consent
 
+## Rationalization Prevention
+
+Do NOT rationalize away failures. If a verification step fails, the task is not complete.
+
+- **HARD-GATE: Each task's verification must pass before marking it `completed`.**
+- **HARD-GATE: Final verification (Step 6) must pass before `plan_reconcile`. Do not reconcile a failing plan.**
+- Do not say "this task is basically done" when its verification has not run.
+- Do not skip verification steps "to save time" -- they exist for a reason.
+- Do not mark a task `completed` while its tests fail, even if the code "looks right."
+- If a task is blocked or failing, leave it `in_progress` and report honestly.
+- Do not treat reconciliation drift as permission to ignore failures.
+
 ## Quick Reference
 
 | Op                                              | When to Use                 |

package/dist/skills/finishing-a-development-branch/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: finishing-a-development-branch
+description: >
+  Use when the user says "finish branch", "merge branch", "ready to merge", "PR ready",
+  "close branch", "submit PR", or wants to finalize a development branch for merge into
+  the base branch.
+---
+
+# Finishing a Development Branch
+
+Pre-merge checks, PR creation, merge strategy, and branch cleanup.
+
+**Announce at start:** "I'm using the finishing-a-development-branch skill to prepare this branch for merge."
+
+## Step 1: Pre-Merge Checklist
+
+Run all checks before creating a PR. Stop on any failure.
+
+```bash
+npm test              # all tests pass
+npx tsc --noEmit      # typecheck clean
+npm run lint          # no lint errors (if configured)
+```
+
+Verify no uncommitted changes: `git status` should be clean. Commit or stash before proceeding.
+
+## Step 2: Create the Pull Request
+
+1. Push the branch: `git push -u origin <branch>`
+2. Create PR with `gh pr create`:
+   - **Title**: under 70 chars, conventional format (`feat:`, `fix:`, `refactor:`)
+   - **Body**: summary (what + why), test plan, breaking changes if any
+   - **Reviewers**: add if the user specifies or the repo has CODEOWNERS
+   - **Labels/milestone**: add if relevant
+
+Keep the description focused on _why_ the change exists, not a file-by-file diff recap.
+
+## Step 3: Squash vs Merge Commit
+
+| Signal                           | Strategy         | Rationale                         |
+| -------------------------------- | ---------------- | --------------------------------- |
+| Many WIP/fixup commits           | **Squash**       | Clean history, one logical change |
+| Each commit is a meaningful unit | **Merge commit** | Preserves granular history        |
+| Single commit on branch          | Either           | No difference                     |
+| Team convention exists           | **Follow it**    | Consistency wins                  |
+
+Default to **squash** unless the user or repo convention says otherwise.
+
+## Step 4: Handle Merge Conflicts
+
+If the base branch has diverged:
+
+1. `git fetch origin && git rebase origin/<base>` — preferred, keeps history linear
+2. Resolve conflicts file by file, run the full checklist (Step 1) again after resolving
+3. `git rebase --continue` after each resolution
+4. If rebase is too complex, `git merge origin/<base>` is acceptable — ask the user
+
+Never force-push a rebased branch that others are working on.
+
+## Step 5: Branch Cleanup
+
+After merge is confirmed:
+
+1. `git checkout <base> && git pull`
+2. `git branch -d <branch>` — delete local branch
+3. If remote branch not auto-deleted: `git push origin --delete <branch>`
+
+## Anti-Patterns
+
+- **Force-pushing to shared branches** — destroys others' history; only force-push personal branches
+- **Merging without tests passing** — broken main is worse than a delayed merge
+- **Giant PRs** — split if touching 10+ files across unrelated concerns
+- **Empty PR descriptions** — reviewers need context; "fixes stuff" is not a description
+- **Leaving stale branches** — delete after merge; stale branches create confusion
+
+**Related skills:** executing-plans, verification-before-completion

package/dist/skills/fix-and-learn/SKILL.md

@@ -90,6 +90,18 @@ Bug resolved, tests pass, root cause captured in vault. A fix without a capture
 - Skipping the capture step after fixing
 - Not running the full test suite to check regressions
 
+## Rationalization Prevention
+
+Do NOT rationalize away failures. A fix is not done until it is proven done.
+
+- **HARD-GATE: The original symptom must be verified as resolved (test passes, error gone) before claiming the bug is fixed.**
+- **HARD-GATE: Full test suite must pass (no regressions) before completing the fix loop.**
+- Do not say "the fix should work" -- reproduce the original issue and confirm it is gone.
+- Do not say "this is unrelated" to dismiss a new test failure without investigation.
+- Do not skip the capture step -- a fix without a vault entry is incomplete.
+- If the fix introduces a new failure, the fix is not done. Do not rationalize it away.
+- If you cannot verify the fix, say so. Never claim success without evidence.
+
 ## Quick Reference
 
 | Op                                              | When to Use                |

package/dist/skills/mcp-doctor/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: mcp-doctor
+description: >
+  Use when MCP servers fail to connect, tools are missing, or the user says "check MCP",
+  "MCP not working", "server not connecting", "tools missing", "heal MCP", "fix MCP",
+  "mcp doctor", "mcp status". Diagnoses and repairs MCP server connectivity issues.
+---
+
+# MCP Doctor — Diagnose and Heal MCP Connections
+
+Systematically diagnose why MCP servers are not connecting and attempt to repair them.
+
+## Phase 1: Inventory
+
+Read the `.mcp.json` in the project root to get the list of configured servers.
+
+```bash
+cat .mcp.json
+```
+
+For each server entry, record:
+
+- Server name
+- Command (`command` field)
+- Arguments (`args` field)
+- Working directory (`cwd` field, defaults to `.`)
+- Environment variables (`env` field, if any)
+
+## Phase 2: Diagnose Each Server
+
+For each configured server, run these checks in order:
+
+### 2a. Binary exists?
+
+```bash
+which <command>
+# e.g. which node, which uvx, which npx
+```
+
+If the binary is missing, report it and suggest installation.
+
+### 2b. Entry point exists?
+
+For `node` commands, check the script file exists:
+
+```bash
+ls -la <args[0]>
+```
+
+For `npx`/`uvx` commands, check the package resolves:
+
+```bash
+npx --yes <package> --help 2>&1 | head -5
+# or
+uvx --from <source> <command> --help 2>&1 | head -5
+```
+
+### 2c. Server starts?
+
+Attempt to start the server with a timeout to verify it initializes:
+
+```bash
+timeout 10 <full command> 2>&1 &
+sleep 3
+kill %1 2>/dev/null
+```
+
+Look for:
+
+- Startup success messages (e.g. "Starting MCP server", "tools loaded")
+- Error messages (missing dependencies, port conflicts, config errors)
+- Crash/exit codes
+
+### 2d. Port conflicts?
+
+If the server binds to a port, check for conflicts:
+
+```bash
+lsof -i :<port>
+```
+
+If a stale process holds the port, report the PID and suggest killing it.
+
+### 2e. Dependencies met?
+
+For Node.js servers, check if `node_modules` exist:
+
+```bash
+ls <cwd>/node_modules/.package-lock.json 2>/dev/null
+```
+
+If missing, suggest `npm install`.
+
+For Python (uvx) servers, the virtual env is managed by uvx — check if the package installs cleanly.
+
+## Phase 3: Repair
+
+For each issue found, apply the appropriate fix:
+
+| Issue                         | Fix                                    |
+| ----------------------------- | -------------------------------------- |
+| Binary not found              | Suggest install command                |
+| Entry point missing           | `npm run build` or check path          |
+| Port conflict (stale process) | `kill <PID>` (ask user first)          |
+| Missing node_modules          | `npm install` in the right directory   |
+| Config error in .mcp.json     | Show the fix, apply with user approval |
+| Package resolution failure    | Clear cache, retry install             |
+| Server crashes on start       | Show error log, diagnose root cause    |
+
+**IMPORTANT:** Never kill processes without user confirmation. Always show the PID and process name first.
+
+## Phase 4: Verify
+
+After repairs, instruct the user:
+
+> Repairs complete. Please restart MCP connections:
+>
+> 1. Type `/mcp` in the prompt
+> 2. Toggle the repaired server(s) off and back on
+> 3. Verify tools appear with a ToolSearch
+
+Note: Claude Code does not support programmatic MCP restarts. The user must use `/mcp` to reconnect.
+
+## Phase 5: Report
+
+Present findings as a table:
+
+```
+## MCP Doctor Report
+
+| Server | Binary | Entry Point | Starts | Port | Status |
+|--------|--------|-------------|--------|------|--------|
+| soleri | node OK | dist/index.js OK | OK | — | Healthy |
+| serena | uvx OK | git+... OK | OK | 24285 OK | Healthy |
+
+### Issues Found
+| Server | Issue | Fix Applied |
+|--------|-------|-------------|
+| serena | Stale process on :24285 | Killed PID 1234 |
+
+### Action Required
+- [ ] Run `/mcp` and reconnect repaired servers
+```
+
+## Common Issues
+
+- **uvx servers**: Often fail due to network issues when pulling from git. Check connectivity.
+- **Node servers**: Often fail because `dist/` hasn't been built. Run the build command.
+- **Port conflicts**: Previous server instances that didn't shut down cleanly. Kill and restart.
+- **cwd issues**: Relative `cwd: "."` resolves from where Claude Code launched, not the .mcp.json location.
+
+## Quick Reference
+
+| Check          | Command            | What it tells you               |
+| -------------- | ------------------ | ------------------------------- |
+| Binary exists  | `which <cmd>`      | Is the runtime installed?       |
+| Script exists  | `ls <path>`        | Is the entry point built?       |
+| Port free      | `lsof -i :<port>`  | Is something blocking the port? |
+| Deps installed | `ls node_modules`  | Are npm packages present?       |
+| Server starts  | `timeout 10 <cmd>` | Does initialization succeed?    |

package/dist/skills/subagent-driven-development/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: subagent-driven-development
+description: >
+  Use when the user says "use subagents", "parallel agents", "fan out", "dispatch agents",
+  "subagent driven", or when a task decomposes into 2+ independent units that benefit from
+  isolated execution. Covers when to dispatch, worktree isolation, and merge strategy.
+---
+
+# Subagent-Driven Development
+
+Decompose work into isolated units, dispatch subagents via the Agent tool, merge results back. You are the controller — you never implement, you orchestrate.
+
+**Announce at start:** "I'm using the subagent-driven-development skill to dispatch isolated agents."
+
+## When to Dispatch
+
+| Signal                                        | Dispatch?                                |
+| --------------------------------------------- | ---------------------------------------- |
+| 2+ independent tasks touching different files | Yes — no conflict risk, parallel speedup |
+| Risky/experimental work (spike, prototype)    | Yes — isolate blast radius in a worktree |
+| Large refactor across unrelated modules       | Yes — each module is a clean unit        |
+| Single-file change or trivial fix             | **No** — overhead exceeds benefit        |
+| Tasks with sequential dependencies            | **No** — cannot parallelize              |
+| Tasks modifying the same file                 | **No** — guaranteed merge conflicts      |
+
+## The Process
+
+### Step 1: Decompose
+
+Break work into discrete units. For each, determine: files involved, dependencies on other units, conflict risk. Only units with no file overlap and no inter-dependency qualify for dispatch.
+
+### Step 2: Dispatch with Worktree Isolation
+
+```
+Agent(prompt: "<task prompt>", isolation: "worktree")
+```
+
+Each subagent prompt must include: (1) task scope, (2) file boundaries, (3) acceptance criteria, (4) rules — no commits, no out-of-scope changes, run tests before reporting.
+
+Launch all independent subagents in a **single message** so they run in parallel.
+
+### Step 3: Review and Merge
+
+For each returning subagent:
+
+1. **Review** — read actual file changes (do not trust self-reports alone), verify tests pass, check scope compliance
+2. **Merge** — `git merge` or `git cherry-pick` from the worktree branch, one at a time
+3. **Test** — run the full suite after each merge; only proceed if green
+4. **Conflicts** — resolve manually, re-run tests, capture as anti-pattern for future planning
+
+After all merges, capture learnings:
+
+```
+YOUR_AGENT_core op:capture_quick params:{
+  title: "subagent dispatch outcome",
+  description: "<which tasks parallelized well, which conflicted>"
+}
+```
+
+## Anti-Patterns
+
+| Anti-Pattern                                 | Why It Fails                                  |
+| -------------------------------------------- | --------------------------------------------- |
+| Dispatching for a 5-line fix                 | Startup overhead exceeds the work             |
+| Parallel dispatch of dependent tasks         | Second agent works on stale assumptions       |
+| Skipping worktree isolation for nearby files | Silent overwrites between agents              |
+| Trusting self-reports without reading code   | Agents miss edge cases or misunderstand scope |
+| Dispatching 10+ agents at once               | Review bottleneck shifts to the controller    |
+
+## Merge Strategy
+
+| Situation                           | Strategy                                                 |
+| ----------------------------------- | -------------------------------------------------------- |
+| Completely separate directories     | Fast-forward merge, no conflicts expected                |
+| Different files in the same package | Merge one by one, test after each                        |
+| Unexpected conflict                 | Resolve manually, re-run tests, capture as anti-pattern  |
+| Subagent result fails review        | Dispatch fix subagent into same worktree (max 2 retries) |
+
+**Related skills:** parallel-execute, executing-plans, verification-before-completion

package/dist/skills/using-git-worktrees/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: using-git-worktrees
+description: >
+  Use when the user says "worktree", "isolate", "parallel branch", "safe branch", or when a plan
+  has independent tasks that benefit from parallel execution in isolated branches. Provides the
+  protocol for creating, working in, and cleaning up git worktrees safely.
+---
+
+# Using Git Worktrees
+
+Isolate work into parallel branches without stashing or switching. Use for multi-task plans, risky changes, or parallel execution. Claude Code natively supports `isolation: "worktree"` on sub-agents.
+
+**Announce at start:** "I'm using the using-git-worktrees skill to isolate this work."
+
+## When to Use
+
+- Plan has 2+ independent tasks that can run in parallel
+- Risky or experimental change that should not touch the main working tree
+- Long-running task where you need the main branch clean for hotfixes
+
+## Creation Protocol
+
+```bash
+# 1. Pre-flight — working tree must be clean
+git status
+git log origin/main..main              # check for unpushed commits
+
+# 2. Create worktree
+git worktree add ../<repo>-<task> -b <branch-name>
+cd ../<repo>-<task>
+
+# 3. Bootstrap and baseline
+npm install                            # shared .git does NOT share node_modules
+npm test                               # must pass before any changes
+```
+
+If the working tree is dirty, commit or stash first. If baseline tests fail, stop and investigate.
+
+## Working in a Worktree
+
+- Full working copy — edit, test, commit normally
+- Commits are visible across worktrees (shared `.git`)
+- `git worktree list` to see all active worktrees
+
+## Cleanup Protocol
+
+```bash
+# 1. Safety check — never delete with unpushed/uncommitted work
+git log origin/<branch>..<branch>      # unpushed commits?
+git diff --stat                        # uncommitted changes?
+
+# 2. Merge or discard
+git merge <branch-name>                # from main worktree
+# OR: git branch -D <branch-name>     # only if work is abandoned
+
+# 3. Remove and verify
+git worktree remove ../<repo>-<task>
+git worktree prune
+git worktree list                      # confirm removal
+```
+
+## Anti-Patterns
+
+- Creating worktrees for single-file changes or one-liner fixes
+- Leaving orphan worktrees after tasks complete — always clean up
+- Deleting the worktree directory manually instead of `git worktree remove`
+- Forgetting `npm install` in new worktree
+- Skipping baseline tests before starting work
+
+## Quick Reference
+
+| Action         | Command                                          |
+| -------------- | ------------------------------------------------ |
+| Create         | `git worktree add ../<name> -b <branch>`         |
+| List           | `git worktree list`                              |
+| Remove         | `git worktree remove ../<name>`                  |
+| Prune          | `git worktree prune`                             |
+| Check unpushed | `git log origin/<branch>..<branch>`              |
+| Claude Code    | Sub-agent with `isolation: "worktree"` parameter |
+
+**Related skills:** executing-plans, parallel-execute

package/dist/skills/vault-curate/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: vault-curate
+description: >
+  Use when the user says "clean vault", "deduplicate", "groom knowledge",
+  "consolidate vault", "vault maintenance", "find duplicates", "merge patterns",
+  "check contradictions", "vault health", or wants to maintain, clean, reorganize,
+  or improve the quality of the agent's knowledge base.
+---
+
+# Vault Curate — Knowledge Maintenance
+
+Maintain vault quality through deduplication, grooming, contradiction detection, and consolidation. A well-curated vault produces better search results and brain recommendations.
+
+## When to Use
+
+Periodically (weekly or after heavy capture sessions), when search quality degrades, when vault health shows warnings, or when the user explicitly requests maintenance.
+
+## Orchestration Sequence
+
+### Step 1: Health Assessment
+
+```
+YOUR_AGENT_core op:knowledge_health
+```
+
+```
+YOUR_AGENT_core op:get_vault_analytics
+```
+
+Present the health summary to the user before proceeding: total entries, quality scores, staleness, coverage gaps.
+
+### Step 2: Detect Duplicates
+
+```
+YOUR_AGENT_core op:curator_detect_duplicates
+```
+
+This finds entries with overlapping titles, descriptions, or content. Review the duplicate pairs — some may be intentional (different contexts) while others are true duplicates.
+
+For true duplicates:
+
+```
+YOUR_AGENT_core op:merge_patterns
+  params: { patternIds: ["<id1>", "<id2>"] }
+```
+
+Preserve the best content from each.
+
+### Step 3: Find Contradictions
+
+```
+YOUR_AGENT_core op:curator_contradictions
+```
+
+Contradictions erode trust in vault search results. For each contradiction: decide which entry is correct (check dates, context, evidence), then archive or update the incorrect one.
+
+### Step 4: Groom Entries
+
+```
+YOUR_AGENT_core op:curator_groom_all
+```
+
+Runs tag enrichment and metadata cleanup across all entries. This improves searchability and categorization.
+
+For targeted grooming of specific entries:
+
+```
+YOUR_AGENT_core op:curator_groom
+  params: { entryIds: ["<id>"], tags: ["<tag>"] }
+```
+
+### Step 5: Full Consolidation
+
+```
+YOUR_AGENT_core op:curator_consolidate
+```
+
+Runs the complete pipeline: dedup + archive stale entries + resolve contradictions. This is the heavy-duty cleanup.
+
+### Step 6: Knowledge Reorganization
+
+```
+YOUR_AGENT_core op:knowledge_reorganize
+  params: { mode: "preview" }
+```
+
+Preview first, then run again with `mode: "apply"` if the preview looks good.
+
+### Step 7: Verify Results
+
+```
+YOUR_AGENT_core op:knowledge_health
+```
+
+Compare with Step 1 metrics. Vault health should improve: fewer duplicates, no contradictions, better coverage.
+
+## Exit Criteria
+
+Curation is complete when: duplicates merged, contradictions resolved, entries groomed, and health metrics improved compared to Step 1 baseline.