diff --git a/.claude/rules/change_guardrails_rules.md b/.claude/rules/change_guardrails_rules.md
index 78cdbf4c9..685c65c54 100644
--- a/.claude/rules/change_guardrails_rules.md
+++ b/.claude/rules/change_guardrails_rules.md
@@ -93,9 +93,6 @@ These rules sit between subsystems. Each canonical doc covers its own surface; o
 16. Authority over loopback / proxy / `X-Forwarded-For` trust lives in `src/actions.ts` (`isLocalRequest`, `forwardedForValues`, `isProductionEnvironment`) and the matching helpers in `src/services/root_landing/**`. Any new code that needs to know "is this request local?" MUST consume those exports — not a bare `req.socket.remoteAddress` check, not a `Host` header read, not an inlined fork (`docs/security/threat_model.md`). Treat the v0.11.1 advisory shape as a regression class, not a one-off.
 17. Every new Express route MUST land in `scripts/security/protected_routes_manifest.json` (auth-required) or in the runtime allow-list with a stated `reason`. Run `npm run security:manifest:write` in the same change; CI's `security_gates` job runs `--check` and rejects drift.
 18. Every release that the diff classifier (`scripts/security/classify_diff.js`) labels `sensitive=true` MUST land with a filled `docs/releases/in_progress/<TAG>/security_review.md` and a supplement `Security hardening` section linking it. `none` provider mode is acceptable, manual fill is mandatory.
-19. Every new **destructive or data-mutating operation** (DB migration, encryption migration, repair command, bulk-rewrite over user data) MUST ship with a real round-trip integration test that operates on a real file, not in-memory stubs. The test MUST cover: identity (forward→inverse leaves the data unchanged), dry-run non-mutation, idempotency on re-run, and NULL preservation. See `docs/testing/testing_standard.md` § Destructive operations.
-20. Every new **external-file-shape parser** (harness transcripts, SQLite imports, third-party config formats) MUST ship with a test that exercises the actual parsing path against a fixture file in the supported format. Detection-only tests (asserting `detectSource` returns the right tag) are not coverage of parsing.
-21. Every new **HTTP server runtime-config knob** (timeouts, connection behavior, header policy) MUST ship with a test that asserts the *runtime* behavior — a response header value, a socket lifetime, an observable connection property — not just the source string. A constant declared in code with no runtime assertion regresses silently.
 
 ### MUST NOT
 
@@ -152,11 +149,6 @@ Before opening a PR that touches any surface in the Touchpoint Matrix, confirm:
 - [ ] `npm run security:classify-diff` recorded; if `sensitive=true`, `npm run security:lint` is clean, `npm run security:manifest:check` passes, `npm run test:security:auth-matrix` passes, and `docs/releases/in_progress/<TAG>/security_review.md` exists with a sign-off verdict.
 - [ ] New Express routes registered in `protected_routes_manifest.json` (or runtime unauth allow-list with a `reason`); manifest regenerated via `npm run security:manifest:write` when needed.
 - [ ] No bare `req.socket.remoteAddress`, `X-Forwarded-For`, or `Host` reads outside `src/actions.ts` / `src/services/root_landing/**`; auth-local fallbacks (`!auth && isLocalRequest`) gated through `assertExplicitlyTrusted`.
-- [ ] **User-facing-surface coverage**: any new CLI command, new CLI flag, new destructive/data-mutating operation, new external-file-shape parser, or new HTTP runtime-config knob has a test that exercises the **user-observable behavior end-to-end**, not just a helper function. A test file with the right name that only covers an internal helper is not coverage. Required regression tests by surface class:
-  - Destructive operations (DB migrations, encryption migrations, repair commands): real round-trip test against a real file — encrypt→decrypt identity, dry-run non-mutation, idempotency on re-run, NULL preservation.
-  - External-file-shape parsers (harness transcripts, SQLite imports, third-party config): at least one fixture per supported format that exercises the actual parser path, not just `detectSource`.
-  - Discovery / detection / parser pairs: a roundtrip test asserting paths emitted by discovery are parseable by the parser.
-  - HTTP runtime config (timeouts, headers, keep-alive): a test that asserts the *runtime* behavior (response header, socket lifetime), not just the source string.
 
 ## Canonical doc index
 
diff --git a/.claude/rules/gmail_proactive.md b/.claude/rules/gmail_proactive.md
new file mode 100644
index 000000000..3f64b0300
--- /dev/null
+++ b/.claude/rules/gmail_proactive.md
@@ -0,0 +1,37 @@
+---
+description: Agents MUST use the Gmail MCP proactively to check email whenever task context makes it relevant, without waiting to be asked.
+globs:
+alwaysApply: true
+---
+
+<!-- Source: foundation/agent_instructions/cursor_rules/gmail_proactive.mdc -->
+
+
+# Gmail Proactive Check Rule
+
+## Purpose
+
+Ensures agents check Gmail proactively when task context implies email may contain relevant information, rather than waiting for an explicit instruction to check.
+
+## Trigger Patterns
+
+Agents MUST check Gmail proactively when:
+
+- Waiting on an external action that sends email confirmation (account signups, invitations, verifications, notifications)
+- A workflow step is blocked pending an email (e.g. invitation acceptance, token delivery, approval)
+- The user asks about status of something that would be communicated via email
+- Setting up third-party integrations that send credentials or confirmation links by email
+- Any context where "did the email arrive?" is a natural next question
+
+## Agent Actions
+
+1. Use `mcp__aa7dd3ca-ee1b-423d-8787-cf03044822ee__search_threads` with a targeted query (recipient, sender, subject keywords, time window)
+2. If relevant emails are found, surface the key details and next action
+3. If no relevant emails are found, report that and suggest next steps
+
+## Constraints
+
+- MUST check Gmail proactively when task context implies email is a dependency — do not wait for the user to say "check my email"
+- MUST use targeted queries (narrow by sender, recipient, subject, or time) rather than fetching all mail
+- MUST store any emails retrieved in Neotoma per the external-tool store-first rule
+- MUST NOT check Gmail in unrelated contexts where email is not a plausible dependency
diff --git a/.claude/rules/inspector_shadcn_rules.md b/.claude/rules/inspector_shadcn_rules.md
new file mode 100644
index 000000000..280394961
--- /dev/null
+++ b/.claude/rules/inspector_shadcn_rules.md
@@ -0,0 +1,81 @@
+---
+description: Enforce shadcn/ui primitives in Inspector UI work; prefer existing inspector components over native HTML controls.
+globs:
+  - inspector/**
+alwaysApply: false
+---
+
+<!-- Source: docs/ui/inspector_shadcn_rules.mdc -->
+
+
+# Inspector shadcn UI Rules
+
+## Purpose
+
+Keep the Inspector app visually and behaviorally consistent with the Neotoma design system by using shadcn/ui-style primitives from `inspector/src/components/ui/` instead of ad hoc native HTML controls and one-off Tailwind patterns.
+
+Inspector is an inspection surface, not a marketing or agentic UI. Prefer consistency, accessibility, and design tokens over decorative variation.
+
+## Canonical references
+
+- `docs/ui/shadcn_components.md` — component inventory and Select vs DropdownMenu guidance
+- `docs/ui/design_system/implementation_notes.md` — prefer shadcn over native HTML, tokens, dark mode, WCAG AA
+- `docs/ui/inspector_shadcn_audit.md` — route-level adoption backlog (if present)
+
+## Installed primitives (`inspector/src/components/ui/`)
+
+Prefer these when they fit the interaction. Do not add new primitives in feature work without a short justification.
+
+**Core (use first):** `Button`, `Input`, `Label`, `Textarea`, `Select`, `Card`, `Badge`, `Separator`, `Dialog`, `Sheet`, `Alert`, `Skeleton`, `Tooltip`, `ScrollArea`, `Tabs`, `Switch`, `DropdownMenu`
+
+**Composites (preserve mirror contract):** `DataTable`, `Pagination`, `ConfirmDialog` — keep in sync with `frontend/src/components/ui/` when editing; see comments in those files.
+
+**Available but often unused in pages:** `Checkbox`, `Popover`, `Toggle`, `ToggleGroup` — use them before inventing custom segmented controls or native checkboxes.
+
+**Not present in Inspector yet (add only with plan):** shadcn `Table` markup inside `DataTable`, `AlertDialog` (prefer `ConfirmDialog` until added), `Command` for search/command palettes.
+
+## MUST
+
+### Control selection
+
+- **MUST** use `Select` from `@/components/ui/select` for single-value dropdowns. **MUST NOT** use native `<select>` (including `agent_filter.tsx` and similar filters).
+- **MUST** use `DropdownMenu` for context menus, column visibility, and action menus — not `Select`.
+- **MUST** use `Button` with appropriate `variant` and `size` instead of raw `<button>` with hand-rolled border/background classes.
+- **MUST** use `Checkbox` + `Label` for boolean row selection and multi-select lists — not native `<input type="checkbox">`.
+- **MUST** use `Textarea` for multi-line text entry — not unstyled native `<textarea>` except where a documented exception applies.
+- **MUST** use `ToggleGroup` / `ToggleGroupItem` for segmented filters (e.g. open/closed/all, formatted/raw) — not custom `role="group"` button clusters unless accessibility requirements cannot be met with shadcn.
+- **MUST** use `Badge` for status, labels, and compact chips — not ad hoc `rounded-full` span pills with hard-coded palette classes.
+- **MUST** use `Alert` or shared `QueryErrorAlert` for errors — not bare `<p className="text-destructive">` alone.
+- **MUST** use `ConfirmDialog` (or `AlertDialog` once added) for destructive confirmations — **MUST NOT** use `window.confirm`.
+
+### Layout and tokens
+
+- **MUST** use design tokens from `inspector/src/index.css` (`--background`, `--foreground`, `--primary`, `--border`, `--muted`, `--destructive`, sidebar/popover tokens, etc.). **MUST NOT** hard-code one-off hex colors for product chrome (graph node styling may use theme-aware variables when touched).
+- **MUST** preserve semantic `<Link>` from `react-router-dom` for navigation; do not replace links with `Button` unless the control is an action, not navigation.
+
+### Data display
+
+- **MUST** use shared `DataTable` for tabular data — do not add parallel raw `<table>` layouts in pages.
+- **MUST** use `Card` / `CardHeader` / `CardContent` for grouped content blocks when replacing hand-built bordered `div` list cards (e.g. sources list, issue rows) unless a feed-specific layout is intentionally feed-only.
+
+## SHOULD
+
+- **SHOULD** use `Sheet` for slide-over detail (markdown preview, large JSON) where a side panel pattern already exists.
+- **SHOULD** use `Skeleton` / shared loading helpers from `components/shared/query_status.tsx` for loading states.
+- **SHOULD** migrate highest-traffic inconsistency surfaces first: `pages/issues.tsx`, `pages/issue_detail.tsx`, `components/shared/agent_filter.tsx`, then segmented controls in `entity_detail.tsx` and `components/shared/inspector_theme_toggle.tsx`.
+
+## MUST NOT
+
+- **MUST NOT** introduce new UI primitives under `inspector/src/components/ui/` without updating `docs/ui/shadcn_components.md` and noting why.
+- **MUST NOT** duplicate full shadcn component source into pages — import from `@/components/ui/*` and `@/lib/utils` (`cn`).
+- **MUST NOT** edit files under `.claude/rules/` or `.claude/skills/` — edit this file and run `npm run setup:cursor` (or `./scriptsscripts/setup_claude_instructions.sh.sh`).
+
+## Validation
+
+Before marking Inspector UI work complete:
+
+- [ ] No new native `<select>` for product controls in touched files
+- [ ] No new raw `<button>` for primary actions in touched files (except inside shadcn `Button` composition patterns)
+- [ ] Errors and confirmations use shared alert/confirm patterns
+- [ ] `npm run lint` and `npm run build` succeed in `inspector/`
+- [ ] Smoke-test changed routes (especially Issues, Settings, entity detail) in light and dark mode
diff --git a/.claude/rules/publish_plan_prompt.md b/.claude/rules/publish_plan_prompt.md
new file mode 100644
index 000000000..2c2aaf389
--- /dev/null
+++ b/.claude/rules/publish_plan_prompt.md
@@ -0,0 +1,86 @@
+---
+description: Prompt to publish plan to GitHub Discussions after any plan file is created or updated.
+globs:
+  - "docs/releases/in_progress/**/release_plan.md"
+  - "docs/feature_units/in_progress/**/*_spec.md"
+  - ".cursor/plans/**/*.md"
+  - ".cursor/plans/**/*.plan.md"
+alwaysApply: false
+---
+
+<!-- Source: foundation/agent_instructions/cursor_rules/publish_plan_prompt.mdc -->
+
+
+# Publish Plan Prompt Rule
+
+## Purpose
+
+Ensures users are offered the option to share a newly written plan as a
+GitHub Discussion post for pre-execution public input, without blocking
+the workflow if they decline.
+
+## Trigger Patterns
+
+Offer the publish-plan prompt after any of the following:
+
+- A release plan file is created or substantially updated
+  (`docs/releases/in_progress/**/release_plan.md`)
+- A feature unit spec is created or substantially updated
+  (`docs/feature_units/in_progress/**/*_spec.md`)
+- A plan file is created under `.cursor/plans/`
+- The user completes the `create-release` or `create-feature-unit` skill
+- The user writes or edits a file whose name includes `plan`, `spec`, or
+  `release_plan` and the file contains a goal, scope, or decisions section
+
+Do NOT trigger when:
+- The plan file already has a corresponding GitHub Discussion linked
+- The user explicitly declined in the same session
+- The file is a template, example, or stub (fewer than 30 lines)
+
+## Agent Actions
+
+### Step 1: Detect plan creation
+
+After writing a plan file that meets the trigger conditions, check
+whether a publish-plan prompt is appropriate:
+
+1. Confirm the file has substantive content (goal, approach, or scope
+   section present).
+2. Confirm the file is not a template or stub.
+3. Confirm the user has not already declined in this session.
+
+### Step 2: Offer the prompt
+
+Present a single, non-blocking offer immediately after reporting that
+the plan file was created:
+
+```
+Plan saved to {path}.
+
+Would you like to share this as a GitHub Discussion for pre-execution
+input? Run /publish-plan {path} to generate a public-facing post.
+```
+
+- One line, no pressure, no follow-up questions.
+- Do not re-offer if the user does not respond or says no.
+- Do not block any subsequent workflow steps on the user's answer.
+
+### Step 3: If user says yes
+
+Invoke the `publish-plan` skill:
+
+```
+/publish-plan {path}
+```
+
+Pass the plan file path as the argument. Let the skill handle all
+subsequent steps (stripping PII, drafting the post, posting to
+Discussions).
+
+## Constraints
+
+- MUST offer the prompt at most once per plan file per session.
+- MUST NOT block workflow continuation on the user's response.
+- MUST NOT re-offer after a decline.
+- MUST pass the exact file path to `/publish-plan` without modification.
+- MUST NOT offer for templates, stubs, or files under 30 lines.
diff --git a/.claude/settings.json b/.claude/settings.json
index 888036f2e..6f24c637a 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -1,17 +1,5 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-settings.json",
   "env": {},
-  "hooks": {
-    "Stop": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "cd /Users/markmhendrickson/repos/neotoma && npm run mirror:plans 2>&1 | tail -5"
-          }
-        ]
-      }
-    ]
-  }
+  "hooks": {}
 }
diff --git a/.claude/skills/analyze/SKILL.md b/.claude/skills/analyze/SKILL.md
index cdaa7f169..6b0dac5b4 100644
--- a/.claude/skills/analyze/SKILL.md
+++ b/.claude/skills/analyze/SKILL.md
@@ -1,3 +1,10 @@
+---
+name: analyze
+description: Analyze Project
+---
+
+<!-- Source: foundation/.cursor/skills/analyze/SKILL.md -->
+
 ---
 name: analyze
 description: Analyze codebase or context per foundation analyze command.
@@ -400,7 +407,6 @@ This command performs systematic analysis following the framework defined in `fo
 **If no foundational docs exist:**
 
 ```
-⚠️ Warning: No foundational documents found in `docs/foundation/`.
 Analysis will proceed without repo-specific context.
 
 Recommendation: Create foundational documents for better analysis:
@@ -431,7 +437,6 @@ Enter choice (1/2/3):
 **If `docs/private/` doesn't exist:**
 
 ```
-⚠️ Warning: Private docs directory not found at `docs/private/`.
 
 Output will be saved to:
 - docs/competitive/[target_name]_competitive_analysis.md
@@ -448,7 +453,6 @@ Proceed? (yes/no)
 **If web scraper URL is provided but MCP server is not configured:**
 
 ```
-⚠️ Notice: Web scraper MCP server not configured for URL "[url]".
 
 Falling back to browser tools for research.
 
@@ -462,7 +466,6 @@ Proceeding with browser tools...
 **If web scraper MCP tool fails:**
 
 ```
-⚠️ Warning: Web scraper failed for URL "[url]".
 
 Error: [error message]
 
diff --git a/.claude/skills/audit/SKILL.md b/.claude/skills/audit/SKILL.md
index 212ac77f3..a2ddbff63 100644
--- a/.claude/skills/audit/SKILL.md
+++ b/.claude/skills/audit/SKILL.md
@@ -1,15 +1,11 @@
 ---
 name: audit
-description: Audit a Neotoma database for graph-health issues (duplicate or redundant entity types, misused types, excessive raw_fragments, non-humanreadable canonical names, orphans, cycles, schema drift). Runs deterministic checks first; LLM-assisted checks are opt-in. Detection separate from repair — emits structured remediation hints pointing at existing tools (merge_entities, correct, register_schema, split_entity, delete_entity).
-triggers:
-  - audit
-  - /audit
-  - audit neotoma
-  - check database health
-  - find duplicates in neotoma
-  - clean up neotoma graph
+description: audit
 ---
 
+<!-- Source: .cursor/skills/audit/SKILL.md -->
+
+
 # audit
 
 ## Purpose
diff --git a/.claude/skills/commit/SKILL.md b/.claude/skills/commit/SKILL.md
index b35508589..cb7ba3ef1 100644
--- a/.claude/skills/commit/SKILL.md
+++ b/.claude/skills/commit/SKILL.md
@@ -1,3 +1,10 @@
+---
+name: commit
+description: commit
+---
+
+<!-- Source: foundation/.cursor/skills/commit/SKILL.md -->
+
 ---
 name: commit
 description: Commit submodules and/or main repo with structured messages; supports /commit repo, /commit <submodule>.
@@ -292,14 +299,14 @@ Run entire test suite and resolve any errors as necessary. Proceed to analyze al
 
 **CRITICAL: PRE-COMMIT SECURITY AUDIT** - MUST RUN BEFORE STAGING:
 
-Execute security audit from `foundation/agent_instructions/cursor_rules/security.md` (or `.cursor/rules/foundation_security.md` if installed) before staging ANY files:
+Execute security audit from `foundation/agent_instructions/cursor_rules/security.md` (or `.claude/rules/foundation_security.md` if installed) before staging ANY files:
 
 1. **Run security audit script:**
    ```bash
    # Use foundation security audit script if available
    if [ -f "foundation/security/pre-commit-audit.sh" ]; then
      ./foundation/security/pre-commit-audit.sh
-   elif [ -f ".cursor/rules/foundation_security.md" ]; then
+   elif [ -f ".claude/rules/foundation_security.md" ]; then
      # Follow security rule checks
      # (Implementation depends on how security rules are executed)
    fi
@@ -719,7 +726,7 @@ development:
 # Use foundation security audit script or rules
 if [ -f "foundation/security/pre-commit-audit.sh" ]; then
   ./foundation/security/pre-commit-audit.sh
-elif [ -f ".cursor/rules/foundation_security.md" ]; then
+elif [ -f ".claude/rules/foundation_security.md" ]; then
   # Follow security rule checks
 fi
 
@@ -729,7 +736,7 @@ fi
 
 If final security check passes, proceed to git commit with the comprehensive commit message and push to origin. **If push is rejected** (remote has new commits): run `git pull --rebase origin <current_branch>` (or `git pull origin <current_branch> --no-rebase --no-edit`), resolve any conflicts, then `git push origin HEAD` again. Always reconcile and retry before reporting push failure.
 
-**WORKTREE DETECTION:** Follow the Worktree Rule (`.cursor/rules/foundation_worktree_env.md` or `foundation/agent_instructions/cursor_rules/worktree_env.md`) to restrict all commit activity to the current worktree.
+**WORKTREE DETECTION:** Follow the Worktree Rule (`.claude/rules/foundation_worktree_env.md` or `foundation/agent_instructions/cursor_rules/worktree_env.md`) to restrict all commit activity to the current worktree.
 
 **COMMIT MESSAGE DISPLAY**: After successfully committing and pushing, always display the full commit message to the user by running `git log -1 --pretty=format:"%B"` and showing the output. This allows the user to review what was committed.
 
diff --git a/.claude/skills/create-plan/SKILL.md b/.claude/skills/create-plan/SKILL.md
new file mode 100644
index 000000000..cbfac02ac
--- /dev/null
+++ b/.claude/skills/create-plan/SKILL.md
@@ -0,0 +1,99 @@
+---
+name: create-plan
+description: Create New Plan
+---
+
+<!-- Source: foundation/.cursor/skills/create-plan/SKILL.md -->
+
+---
+name: create-plan
+description: Create a new plan as a Neotoma entity, optionally linked to objectives, releases, or other plans.
+triggers:
+  - create plan
+  - new plan
+  - create a plan
+  - /create-plan
+---
+
+# Create New Plan
+
+Create a new plan entity in Neotoma with title = {{input:title}}.
+
+Follow the complete workflow in `foundation/development/plan_workflow.md`. Configuration is read from `foundation-config.yaml`.
+
+This workflow can also be triggered automatically via `.claude/rules/plan_detection.mdc` when you mention planning-related patterns in natural language (e.g., "create plan", "new plan"). Both paths execute the same workflow.
+
+## Workflow Overview
+
+Implements Checkpoint 0 of the plan creation workflow:
+
+1. Collect required plan fields from the user
+2. Run alignment check (summary → user confirms)
+3. Store plan as a Neotoma `plan` entity
+4. Create relationships to related entities
+5. Optionally rebuild the `neotoma-plans` mirror
+
+## Tasks
+
+1. **Collect required fields:**
+
+   Ask the user for any missing required fields:
+   - `title` — Short, imperative name
+   - `description` — Problem being solved and why it matters
+   - `scope` — What is explicitly in scope
+   - `out_of_scope` — What is explicitly out of scope
+   - `success_criteria` — Measurable conditions for completion
+   - `status` — Default to `draft`
+
+   Optional fields to offer (collect if relevant):
+   - `priority` (P0/P1/P2/P3)
+   - `phase`
+   - `target_release`
+   - `deliverables`
+   - `dependencies` (canonical names of plans this plan requires)
+   - `testing_notes`
+   - `observability_notes`
+
+2. **Alignment check:**
+
+   After collecting fields, produce a concise summary:
+   - Problem it solves and why it exists
+   - What is explicitly in scope and out of scope
+   - Critical constraints or invariants
+
+   Ask: "Does this accurately capture what you want this plan to do?"
+
+   Incorporate corrections and re-summarize if changes are substantial. Do not proceed until the user confirms.
+
+3. **Store the plan:**
+
+   Use `store` or `submit_entity` with:
+   - `entity_type: plan`
+   - All collected fields as snapshot fields
+
+4. **Create relationships** (if relevant entities are mentioned or known):
+   - `REFERS_TO` for objectives, releases, or parent plans
+   - `DEPENDS_ON` for plans this plan requires
+   - `INFORMED_BY` for issues, feedback, or research
+
+5. **Confirm and offer mirror rebuild:**
+
+   ```
+   Plan stored: {canonical_name}
+
+   To refresh plans/ in the repo, run:
+     neotoma mirror rebuild --profile neotoma-plans
+   ```
+
+   Do not wait for a response before completing this skill.
+
+## Required Documents
+
+Load before starting:
+
+- `foundation/development/plan_workflow.md` (workflow)
+- `foundation-config.yaml` (configuration)
+
+## Inputs
+
+- `title` (string): Short plan name, e.g. "Add selective mirror profiles"
diff --git a/.claude/skills/create-prototype/SKILL.md b/.claude/skills/create-prototype/SKILL.md
new file mode 100644
index 000000000..3fb9bf76b
--- /dev/null
+++ b/.claude/skills/create-prototype/SKILL.md
@@ -0,0 +1,98 @@
+---
+name: create-prototype
+description: Create Prototype
+---
+
+<!-- Source: foundation/.cursor/skills/create-prototype/SKILL.md -->
+
+---
+name: create-prototype
+description: Create prototype per foundation command.
+triggers:
+  - create prototype
+  - /create_prototype
+  - create-prototype
+---
+
+# Create Prototype
+
+Create fully functional client-side prototype for Feature Unit {{input:feature_id}}.
+
+Follow `foundation/development/feature_unit_workflow.md` Step 1 (Prototype Creation). Configuration is read from `foundation-config.yaml`.
+
+This happens after Checkpoint 0 (spec creation) and before Checkpoint 1 (prototype review).
+
+Implements prototype creation after Checkpoint 0 (spec) is complete. Creates a fully interactive, client-side prototype with mocked APIs.
+
+## Trigger
+
+- Spec created with UI requirements (Checkpoint 0 complete, UI changes present) OR
+- No UI changes required (skip prototype)
+
+## Tasks
+
+1. **Load configuration:**
+   - Read `foundation-config.yaml` to get feature unit settings
+   - Determine directory structure and prototype paths
+
+2. **Load spec and manifest:**
+   - `{configured_directory}/in_progress/{{input:feature_id}}/{{input:feature_id}}_spec.md` (or `completed/` if completed)
+   - `{configured_directory}/in_progress/{{input:feature_id}}/manifest.yaml` (or `completed/` if completed)
+   
+3. **Check if UI changes present:**
+   - Review spec and manifest for UI components
+   - Verify UX Requirements section exists in spec (from Checkpoint 0)
+   - If no UI changes → skip to implementation
+   - If UI changes present → proceed
+
+4. **Create prototype:**
+   - Use configured prototype directory structure (or default: `frontend/src/prototype/`)
+   - Create prototype component(s): `{prototype_dir}/components/{{input:feature_id}}_*.tsx`
+   - Create mock API fixtures: `{prototype_dir}/fixtures/{{input:feature_id}}_*.ts`
+   - Integrate into prototype main file
+
+5. **Prototype requirements:**
+   - Fully interactive (click, type, navigate)
+   - All API calls mocked (no real backend)
+   - All UI states testable (empty, error, loading, success)
+   - Accessible (keyboard nav, ARIA if applicable)
+   - Uses existing design system components (if available)
+   - Documented mock API responses
+
+6. **Make prototype runnable:**
+   - Ensure prototype can be run (e.g., `npm run dev:prototype`)
+   - Document how to run prototype
+
+7. **Output:**
+   - Prototype location and run command
+   - Summary of what prototype demonstrates
+   - List of mocked APIs
+   - STOP and proceed to Checkpoint 1 (Prototype Review)
+
+## User Review Prompt
+
+Present:
+- Prototype location
+- How to run: [command]
+- Summary of prototype features
+
+Ask:
+- "Please review the prototype at [location]. Run with [command]."
+- "Does the prototype meet your requirements? (yes/no)"
+- "Any changes needed? (list changes or 'none')"
+
+## If User Requests Changes
+
+- Update prototype based on feedback
+- Re-run prototype creation
+- Repeat until approved
+
+## If Approved
+
+- Document approval in spec: `**Prototype Approved:** YYYY-MM-DD`
+- Proceed to implementation (use `Run Feature Workflow`)
+
+## Inputs
+
+- `feature_id` (string): The feature identifier
+
diff --git a/.claude/skills/create-release/SKILL.md b/.claude/skills/create-release/SKILL.md
new file mode 100644
index 000000000..2fc8956af
--- /dev/null
+++ b/.claude/skills/create-release/SKILL.md
@@ -0,0 +1,451 @@
+---
+name: create-release
+description: Create New Release
+---
+
+<!-- Source: foundation/.cursor/skills/create-release/SKILL.md -->
+
+---
+name: create-release
+description: Create a new software release with planning, manifest, and execution schedule.
+triggers:
+  - new release
+  - create release
+  - plan release
+  - create-release
+  - /create-release
+---
+
+# Create New Release
+
+Orchestrates multiple Feature Units into a cohesive release. Implements the Release workflow from `foundation/development/release_workflow.md`.
+
+## When to Use
+
+**Explicit Command:** Use when you know exactly what you want: start a new release, plan multi-FU work with dependency resolution, generate execution schedules with parallelization, orchestrate FU creation/execution in dependency order, run cross-FU integration tests.
+
+**Automatic Detection:** This workflow can also be triggered automatically via `.claude/rules/release_detection.md` when you mention release-related patterns in natural language (e.g., "new release", "release v1.1.0"). Both paths execute the same workflow.
+
+This is a foundation command. If installed, it will be available in `.claude/skills/` via symlink.
+
+## Prerequisites
+
+- Release ID chosen (format: `vX.Y.Z`, e.g., `v1.0.0`)
+- Release scope roughly defined (what's in, what's out)
+- FU IDs for included work identified (or to be created)
+
+## Command Execution
+
+### Step 1: Load Documentation
+
+Load required documents:
+- `foundation/development/release_workflow.md` (primary workflow)
+- `docs/feature_units/standards/creating_feature_units.md` (FU creation)
+- `docs/feature_units/standards/execution_instructions.md` (FU execution)
+- `docs/feature_units/completed/` and `docs/feature_units/in_progress/` (for Feature Unit specs)
+
+### Step 2: Checkpoint 0 — Release Planning
+
+Check if Release plan exists:
+
+- Look for `docs/releases/in_progress/{release_id}/release_plan.md`
+- Look for `docs/releases/in_progress/{release_id}/manifest.yaml`
+
+**If Release plan exists:** Load and validate. If complete → proceed to Step 3. If incomplete → prompt user to complete.
+
+**If Release plan does NOT exist:** Prompt user interactively for Release details:
+
+1. **Release name and version** (e.g., "MVP", "v1.0.0")
+2. **Release goal** (1-2 sentence summary of what this ships)
+3. **Target ship date** (date or "when ready")
+4. **Priority** (P0 critical / P1 high / P2 normal)
+5. **Included Feature Units** (list of FU IDs, e.g., "FU-100, FU-101, FU-102")
+6. **Excluded scope** (what's explicitly NOT in this release)
+7. **Release-level acceptance criteria:**
+   - Product acceptance (core workflows, empty/error states)
+   - Technical acceptance (test coverage, performance, integrity)
+   - Business acceptance (metrics, KPIs)
+8. **Cross-FU integration test requirements** (flows that span multiple FUs)
+9. **Deployment strategy** (staging_first / canary / full_rollout)
+10. **Rollback plan** (how to revert if issues found)
+11. **Post-release monitoring plan** (key metrics, alerts)
+
+**After user input:** Generate complete Release plan (`release_plan.md`), create manifest YAML (`manifest.yaml`), create integration test spec (`integration_tests.md`), create status tracker (`status.md`), save all to `docs/releases/in_progress/{release_id}/`.
+
+**After saving the release plan**, offer the publish-plan prompt once:
+
+```
+Release plan saved to docs/releases/in_progress/{release_id}/release_plan.md.
+
+Would you like to share this as a GitHub Discussion for pre-execution
+input? Run /publish-plan docs/releases/in_progress/{release_id}/release_plan.md
+to generate a public-facing post.
+```
+
+Do not wait for a response before proceeding to Step 3.
+
+### Step 3: Dependency Analysis and Schedule Generation
+
+Analyze dependencies:
+
+1. **Load all FU manifests** for FUs in Release
+2. **Extract dependencies** from each FU's `dependencies.requires` field
+3. **Build dependency graph**: FU → [list of required FUs]
+4. **Detect cycles:** If cycle found → REJECT with error message. List cycle: "FU-A → FU-B → FU-C → FU-A"
+5. **Validate dependencies:** If any required FU is ⏳ Not Started and not in this Release → REJECT. If any required FU is 🔨 Partial → WARN but allow with user confirmation. If any required FU is ✅ Complete → proceed.
+
+Generate execution schedule:
+
+1. **Perform topological sort** of FU dependency graph
+2. **Group into batches**:
+   - Batch 0: FUs with no dependencies
+   - Batch 1: FUs that depend only on Batch 0
+   - Batch 2: FUs that depend only on Batch 0 or 1
+   - ... continue until all FUs assigned to batches
+3. **Identify parallelization opportunities**:
+   - Within each batch, FUs can execute in parallel
+4. **Estimate timeline**:
+   - Sum FU effort estimates per batch
+   - Account for parallelization (divide by number of parallel agents if applicable)
+5. **Save execution schedule** to `execution_schedule.md`
+
+Pre-Mortem Analysis:
+
+1. Identify top 3-5 most likely failure modes for this Release
+2. For each failure mode, specify:
+   - Early warning signals (metrics, test failures, timeline slips)
+   - Mitigating FUs or actions
+   - Rollback plan
+3. Present pre-mortem to user and ask:
+   - "Do these failure modes match your concerns? (yes/no)"
+   - "What other failure modes should we plan for?"
+4. Incorporate feedback and add "Pre-Mortem" section to Release plan
+
+WIP and Parallelization Limits:
+
+1. Encode limits in `manifest.yaml`:
+   - `max_parallel_fus: <number>` (default: 3)
+   - `max_high_risk_in_parallel: <number>` (default: 1)
+2. Present limits to user: "Proposed limits: max_parallel_fus=3, max_high_risk_in_parallel=1. Approve? (yes/modify)"
+
+Machine-Checkable Exit Criteria:
+
+1. For each Release acceptance criterion, define:
+   - Concrete test suite or script that validates it
+   - Single metric or query that proves it
+2. Add these to `integration_tests.md` with explicit pass/fail conditions
+3. Present to user: "Each acceptance criterion now has a machine-checkable test. Review? (yes/modify)"
+
+Present schedule to user: Display batch breakdown, show which FUs run in parallel, show estimated timeline, show WIP limits and pre-mortem failure modes. STOP and prompt: "Approve execution schedule? (yes/no/modify)"
+
+**If user approves:**
+
+- Initialize `status.md` with "Decision Log" section (empty initially)
+- Update Release status to `in_progress`
+- Proceed to Step 4
+
+**If user requests modifications:**
+
+- Adjust schedule based on user input
+- Re-present for approval
+
+---
+
+### Step 4: Execute FU Batches (Autonomous)
+
+Before starting execution, prompt user for execution strategy:
+- Run `node scripts/release_orchestrator.js <release_id>`
+- Orchestrator will prompt: "How would you like to execute this release build? 1. Single-agent (sequential execution) 2. Multi-agent (parallel execution)"
+- If single-agent selected, orchestrator recommends model based on release complexity
+- Selected strategy saved to `manifest.yaml`
+
+For each batch in execution schedule (in order):
+
+**Batch Execution Loop:**
+
+1. **Start all FUs in batch:**
+
+   - For each FU in batch:
+     - Check if FU spec exists
+     - If not, run `Create New Feature Unit` command (Checkpoint 0)
+     - If UI FU and no prototype, run `Create Prototype` command
+     - If UI FU and prototype not approved, run Checkpoint 1 (Prototype Review)
+     - Run `Run Feature Workflow` command to implement FU
+     - Run `Final Review` command (Checkpoint 2) for FU approval
+   - If multiple FUs in batch, suggest running in parallel (separate agent sessions or worktrees)
+
+2. **Wait for all FUs in batch to complete**
+
+3. **Run cross-FU integration tests:**
+
+   - Execute integration test suite from `integration_tests.md`
+   - Test flows that span multiple FUs in this batch
+   - If tests fail: STOP and report failures to user. User decides: fix and retry, skip FU, or abort Release
+   - If tests pass, proceed
+
+4. **Update Release status:**
+   - Mark batch as `completed` in `status.md`
+   - Update progress percentage: `(completed_batches / total_batches) * 100`
+   - If any decisions were made during batch execution (scope changes, FU deferrals, etc.), append to Decision Log in `status.md` with timestamp
+
+**After all batches complete:**
+
+- Mark all FUs as `completed` in status tracker
+- Proceed to Step 5
+
+---
+
+### Step 5: Checkpoint 1 — Mid-Release Review (Optional)
+
+Check if mid-release checkpoint is configured: Look for `checkpoint_1_after_batch` in `manifest.yaml`. If not configured, skip to Step 6.
+
+If configured and batch threshold reached, present mid-release status:
+
+- "Mid-release checkpoint reached"
+- "FUs completed: X/Y"
+- "Integration tests: [pass/fail summary]"
+- "Current batch: N"
+- "Remaining batches: [list]"
+
+**STOP and prompt user:**
+
+- "Continue to remaining FUs? (yes/no/pause)"
+
+**If user responds:**
+
+- **yes** → continue to remaining batches
+- **no** → halt execution, mark Release as `paused`
+- **pause** → halt execution, user can resume later
+
+---
+
+### Step 6: Cross-Release Integration Testing
+
+Run full integration test suite:
+
+1. **Execute all tests** from `integration_tests.md`
+2. **Run end-to-end user flows** that span multiple FUs
+3. **Verify no regressions** in existing functionality
+4. **Run performance benchmarks** (if specified in acceptance criteria)
+5. **Verify graph integrity** (0 orphans, 0 cycles if applicable)
+
+Check Release-level acceptance criteria:
+
+- Product acceptance: Core workflows functional?
+- Technical acceptance: Test coverage met? Performance targets hit?
+- Business acceptance: Metrics instrumented? Analytics ready?
+
+Generate integration test report:
+
+- Save to `integration_test_report.md`
+- Include:
+  - Pass/fail summary
+  - Performance metrics
+  - Regression test results
+  - Issues found (if any)
+
+**If tests fail:** STOP and report failures to user. User decides: fix issues and re-test, or abort Release.
+
+**If all tests pass:** Proceed to Step 7.
+
+### Step 7: Checkpoint 2 — Pre-Release Sign-Off
+
+Present Release summary:
+
+- FUs completed: X/Y (with list)
+- Integration tests: [pass/fail summary with link to report]
+- Acceptance criteria: [checklist with ✅ / ❌ status]
+- Release plan: [link]
+- Integration test report: [link]
+
+**STOP and prompt user:**
+
+- "Release {release_id} ready for deployment."
+- "All FUs complete: [list with status]"
+- "Integration tests passed: [summary]"
+- "Acceptance criteria met: [checklist]"
+- "Approve for deployment? (yes/no)"
+- "Any final changes needed? (list or 'none')"
+
+**If user requests changes:**
+
+- Apply changes
+- Re-run affected tests
+- Update status
+- Repeat Checkpoint 2 until approved
+
+**If user approves:**
+
+- Update Release status to `ready_for_deployment`
+- Proceed to Step 8
+
+---
+
+### Step 8: Deployment
+
+Execute deployment plan:
+
+1. **Follow deployment strategy** from Release plan:
+   - **staging_first**: Deploy to staging, run smoke tests, then production
+   - **canary**: Deploy to small % of users, monitor, then full rollout
+   - **full_rollout**: Deploy to all users at once
+2. **Run deployment steps:**
+   - Build production bundle
+   - Run database migrations (if any)
+   - Deploy backend services
+   - Deploy frontend assets
+   - Run health checks
+   - Run smoke tests
+3. **Verify deployment success:**
+   - Health checks pass?
+   - Smoke tests pass?
+   - Key metrics normal?
+
+**If deployment fails:** STOP and report failure, execute rollback plan, user investigates and fixes.
+
+**If deployment succeeds:** Update Release status to `deployed`, record deployment timestamp, proceed to Step 9.
+
+### Step 9: Post-Release Monitoring Setup
+
+Setup monitoring:
+
+1. **Verify metrics instrumentation:**
+   - Check that key metrics from acceptance criteria are being collected
+   - Verify dashboards are accessible
+2. **Setup alerts:**
+   - Configure alerts for critical metrics (error rates, latency, etc.)
+3. **Document monitoring links:**
+   - Add links to dashboards, alerts to Release status doc
+
+Mark Release as completed:
+
+- Update status to `completed`
+- Move Release files from `in_progress/` to `completed/`:
+  ```bash
+  mv docs/releases/in_progress/{release_id} docs/releases/completed/{release_id}
+  ```
+
+Present completion summary:
+
+- "Release {release_id} deployed and complete!"
+- "Deployed at: {timestamp}"
+- "Monitoring: {dashboard_links}"
+- "FUs shipped: [list]"
+
+## Example Interaction
+
+```
+User: Create release v1.0.0 for MVP
+
+Agent: Loading Release workflow documentation...
+
+Agent: No existing Release plan found for v1.0.0. Starting interactive Release planning (Checkpoint 0).
+
+Agent: What is the Release name and version?
+User: MVP, v1.0.0
+
+Agent: What is the Release goal? (1-2 sentence summary)
+User: Ship deterministic Truth Layer with ingestion, extraction, entity resolution, timeline, and MCP access for AI tools. Support multi-user teams.
+
+Agent: What is the target ship date?
+User: 2025-03-01
+
+Agent: What is the priority?
+User: P0 critical
+
+Agent: Which Feature Units should be included? (list FU IDs)
+User: FU-100, FU-101, FU-102, FU-103, FU-105, FU-300, FU-700, FU-701
+
+Agent: [loads the matching Feature Unit specs from `docs/feature_units/`]
+
+Agent: What scope is explicitly excluded from this release?
+User: Semantic search, Plaid integration, X/Instagram integrations (all post-MVP)
+
+Agent: What are the Release-level acceptance criteria? (product, technical, business)
+User: [provides release-specific criteria]
+
+Agent: What cross-FU integration tests are required?
+User: Full user flow: upload → extraction → entity resolution → event generation → timeline display → AI query via MCP
+
+Agent: What is the deployment strategy?
+User: staging_first
+
+Agent: What is the rollback plan?
+User: Revert to previous release tag, restore DB snapshot if needed
+
+Agent: What monitoring plan should be setup post-release?
+User: Monitor upload success rate, P95 latency, DAU, orphan node count
+
+Agent: Generating Release plan, manifest, and integration test spec...
+Agent: Analyzing FU dependencies...
+Agent: Dependency graph:
+  FU-100 → []
+  FU-101 → [FU-100]
+  FU-102 → [FU-100]
+  FU-103 → [FU-101, FU-102]
+  FU-105 → [FU-103]
+  FU-300 → []
+  FU-700 → []
+  FU-701 → [FU-700]
+
+Agent: Generating execution schedule...
+Agent: Execution schedule:
+  Batch 0: FU-100, FU-300, FU-700 (can run in parallel)
+  Batch 1: FU-101, FU-102 (can run in parallel, depend on FU-100)
+  Batch 2: FU-103 (depends on FU-101, FU-102)
+  Batch 3: FU-105, FU-701 (can run in parallel, FU-105 depends on FU-103, FU-701 depends on FU-700)
+
+Agent: Estimated timeline: 11-14 days (with parallelization across 3 agents)
+
+Agent: Approve execution schedule? (yes/no/modify)
+User: yes
+
+Agent: Starting batch execution...
+Agent: Batch 0: Starting FU-100, FU-300, FU-700 in parallel...
+[FU execution proceeds autonomously]
+Agent: Batch 0 complete. Running cross-FU integration tests...
+Agent: Integration tests passed.
+Agent: Batch 1: Starting FU-101, FU-102 in parallel...
+[continues through all batches]
+
+Agent: All batches complete. Running full integration test suite...
+Agent: All integration tests passed.
+Agent: Release v1.0.0 ready for deployment.
+Agent: All FUs complete: FU-100 ✅, FU-101 ✅, FU-102 ✅, FU-103 ✅, FU-105 ✅, FU-300 ✅, FU-700 ✅, FU-701 ✅
+Agent: Integration tests passed: 12/12
+Agent: Acceptance criteria met: ✅ Product, ✅ Technical, ✅ Business
+Agent: Approve for deployment? (yes/no)
+User: yes
+
+Agent: Deploying to staging...
+Agent: Staging smoke tests passed.
+Agent: Deploying to production...
+Agent: Production health checks passed.
+Agent: Release v1.0.0 deployed and complete!
+Agent: Monitoring: [dashboard links]
+```
+
+## Agent Instructions
+
+### Load Order
+
+1. `foundation/development/release_workflow.md` (primary)
+2. `docs/feature_units/standards/creating_feature_units.md` (for FU creation)
+3. `docs/feature_units/standards/execution_instructions.md` (for FU execution)
+4. `docs/feature_units/completed/` and `docs/feature_units/in_progress/` (for Feature Unit specs)
+
+### Constraints
+
+- Do NOT proceed past Checkpoint 0 without complete Release plan
+- Always validate FU dependencies before generating schedule
+- REJECT if circular dependencies detected
+- Always run cross-FU integration tests after each batch
+- Always get user approval at Checkpoints 0, 1 (if configured), 2
+- Do NOT deploy without passing integration tests and acceptance criteria
+
+### Forbidden Patterns
+
+- Starting FUs out of dependency order
+- Skipping integration tests
+- Proceeding without user approval at checkpoints
+- Deploying with failing tests or unmet acceptance criteria
diff --git a/.claude/skills/create-rule/SKILL.md b/.claude/skills/create-rule/SKILL.md
new file mode 100644
index 000000000..b570d0037
--- /dev/null
+++ b/.claude/skills/create-rule/SKILL.md
@@ -0,0 +1,299 @@
+---
+name: create-rule
+description: Create Rule
+---
+
+<!-- Source: foundation/.cursor/skills/create-rule/SKILL.md -->
+
+---
+name: create-rule
+description: Create Cursor rule for persistent AI guidance.
+triggers:
+  - create rule
+  - /create_rule
+  - create-rule
+---
+
+# Create Rule
+
+Create a new rule file with `_rules` suffix and automatically create symlink in `.claude/rules/`.
+
+**SUBMODULE MODE**: If a submodule name is provided (e.g., `/create-rule foundation`), create the rule in that submodule. If no submodule name is provided, create in the main repository's `docs/` directory.
+
+## Command
+
+```
+create-rule [submodule_name]
+```
+
+## Inputs
+
+- `submodule_name` (optional string): Submodule name to create rule in (e.g., "foundation"). If omitted, creates rule in main repository's `docs/` directory.
+
+## Workflow Overview
+
+**If submodule name provided:**
+1. Verify submodule exists
+2. Determine submodule rule location
+3. Prompt user for rule details
+4. Create rule file in submodule
+5. Run setup script to create symlink (if applicable)
+6. Exit after submodule rule creation
+
+**If no submodule name provided (default - repo mode):**
+1. Prompt user for rule details
+2. Create rule file in `docs/{location}/{name}_rules.md`
+3. Include standard Agent Instructions template
+4. Run setup script to create symlink
+5. Verify symlink created
+
+## Tasks
+
+### Step 1: Determine Scope
+
+**If submodule name provided:**
+
+1. Verify submodule exists:
+   ```bash
+   if ! git submodule status <submodule_name> >/dev/null 2>&1; then
+     echo "❌ Submodule not found: <submodule_name>"
+     exit 1
+   fi
+   ```
+
+2. Determine submodule rule location:
+   - For `foundation` submodule: `foundation/agent_instructions/cursor_rules/`
+   - For other submodules: Check for standard rule directories or prompt user
+
+3. Set context for submodule rule creation
+
+**If no submodule name provided:**
+- Set context for main repository rule creation in `docs/` directory
+
+### Step 2: Prompt User for Rule Details
+
+**Repository mode prompts:**
+1. **Rule file name** (without `_rules.md` suffix)
+   - Example: "entity_resolution" will become "entity_resolution_rules.md"
+   - Validate: alphanumeric with underscores only
+
+2. **Location in `docs/` directory**
+   - Options: `conventions`, `foundation`, `subsystems`, `architecture`, `developer`, etc.
+   - Validate: directory must exist or ask to create
+
+3. **Rule purpose and scope**
+   - Brief description of what this rule ensures
+   - What triggers loading this rule
+
+4. **Key constraints/MUST/SHOULD rules**
+   - List of main rules this document will enforce
+   - Use RFC 2119 language (MUST, SHOULD, MUST NOT)
+
+**Submodule mode prompts:**
+1. **Rule file name** (without `_rules.mdc` suffix for foundation submodule, or without `.mdc` for foundation submodule - MUST use `.mdc` extension for foundation rules)
+
+2. **Rule purpose and scope**
+
+3. **Key constraints/MUST/SHOULD rules**
+
+### Step 3: Create Rule File
+
+**Repository mode:**
+
+Create file at `docs/{location}/{name}_rules.md` with content:
+
+```markdown
+# {Rule Title}
+
+**Reference:** `docs/{reference_doc}.md` — Related documentation (if applicable)
+
+{Brief description of what this rule ensures}
+
+## Purpose
+
+{Expanded purpose from user input}
+
+## Trigger Patterns
+
+When any of the following occur:
+
+- {Trigger pattern 1}
+- {Trigger pattern 2}
+- {Trigger pattern 3}
+
+## Agent Actions
+
+### Step 1: {Action Title}
+
+{Description of what agent should do}
+
+### Step 2: {Action Title}
+
+{Description of what agent should do}
+
+## Constraints
+
+### MUST
+
+1. {MUST constraint 1}
+2. {MUST constraint 2}
+
+### SHOULD
+
+1. {SHOULD constraint 1}
+2. {SHOULD constraint 2}
+
+### MUST NOT
+
+1. {MUST NOT constraint 1}
+2. {MUST NOT constraint 2}
+
+## Examples
+
+### Example 1: {Example Title}
+
+{Example description and code/steps}
+
+---
+
+## Agent Instructions
+
+### When to Load This Document
+
+Load this document when:
+
+- {Trigger condition 1}
+- {Trigger condition 2}
+
+### Required Co-Loaded Documents
+
+- {Required document 1}
+- {Required document 2}
+
+### Constraints Agents Must Enforce
+
+1. {Constraint to enforce 1}
+2. {Constraint to enforce 2}
+
+### Forbidden Patterns
+
+- {Anti-pattern 1}
+- {Anti-pattern 2}
+
+### Validation Checklist
+
+- [ ] {Validation item 1}
+- [ ] {Validation item 2}
+```
+
+**Submodule mode:**
+
+For foundation submodule, create file following foundation cursor-rules pattern (simpler structure without Agent Instructions section since these are loaded automatically).
+
+### Step 4: Run Setup Script
+
+**Repository mode:**
+
+1. Run foundation setup script:
+   ```bash
+   ./foundation/scripts/setup-cursor-rules.sh
+   ```
+
+2. Verify symlink created in `.claude/rules/`:
+   - Expected symlink name: `{location}_{name}_rules.md`
+   - Example: `docs/conventions/entity_resolution_rules.md` → `.claude/rules/conventions_entity_resolution_rules.md`
+
+3. Output success message:
+   ```
+   ✅ Rule created successfully!
+   
+   File: docs/{location}/{name}_rules.md
+   Symlink: .claude/rules/{location}_{name}_rules.md
+   
+   The rule is now available to all Cursor agents in this repository.
+   
+   Next steps:
+   1. Review the generated rule file and fill in any remaining details
+   2. Test the rule by triggering its conditions
+   3. Update related documentation to reference this rule if needed
+   ```
+
+**Submodule mode:**
+
+1. If submodule is `foundation`, run setup script from main repository:
+   ```bash
+   ./foundation/scripts/setup-cursor-rules.sh
+   ```
+
+2. Verify symlink created (for foundation rules, they're prefixed with `foundation-`)
+
+3. Output success message:
+   ```
+   ✅ Rule created in submodule successfully!
+   
+   File: {submodule}/{rule_path}/{name}{suffix}.mdc (for foundation submodule, use .mdc extension)
+   Symlink: .claude/rules/{prefix}{name}.mdc (if applicable)
+   
+   The rule is now available to all repositories using this submodule.
+   ```
+
+## Error Handling
+
+- If submodule not found: Exit with error message
+- If location directory doesn't exist in repo mode: Offer to create it or exit
+- If file already exists: Warn and ask to overwrite or exit
+- If setup script fails: Report error but keep the created file
+
+## Configuration
+
+Optional configuration in `foundation-config.yaml`:
+
+```yaml
+agent_instructions:
+  rules:
+    default_location: "docs/conventions"  # Default location for new rules
+    template_path: null  # Custom template path (optional)
+    auto_run_setup: true  # Automatically run setup script after creation
+```
+
+## Examples
+
+### Example 1: Create Repository Rule
+
+```
+/create-rule
+```
+
+Prompts:
+- Rule file name: `entity_resolution`
+- Location: `subsystems`
+- Purpose: "Ensure consistent entity resolution patterns across codebase"
+- Key constraints: "MUST use deterministic merging, MUST NOT introduce randomness"
+
+Creates:
+- `docs/subsystems/entity_resolution_rules.md`
+- `.claude/rules/subsystems_entity_resolution_rules.md` (symlink)
+
+### Example 2: Create Foundation Submodule Rule
+
+```
+/create-rule foundation
+```
+
+Prompts:
+- Rule file name: `testing_patterns`
+- Purpose: "Enforce consistent testing patterns"
+- Key constraints: "MUST include unit tests, SHOULD use fixtures"
+
+Creates:
+- `foundation/agent_instructions/cursor_rules/testing_patterns.mdc`
+- `.claude/rules/foundation_testing_patterns.mdc` (symlink)
+
+## Required Documents
+
+Load before starting:
+
+- `foundation/scripts/setup-cursor-rules.sh` (setup script)
+- `docs/conventions/documentation_standards_rules.md` (if creating repo rule)
+- `foundation-config.yaml` (configuration)
+
diff --git a/.claude/skills/create_plan/SKILL.md b/.claude/skills/create_plan/SKILL.md
index 014b9d077..e0e8c6a68 100644
--- a/.claude/skills/create_plan/SKILL.md
+++ b/.claude/skills/create_plan/SKILL.md
@@ -1,20 +1,18 @@
 ---
-name: create-plan
-description: Create a new plan as a Neotoma entity, optionally linked to objectives, releases, or other plans.
-triggers:
-  - create plan
-  - new plan
-  - create a plan
-  - /create-plan
+name: create_plan
+description: Create New Plan
 ---
 
+<!-- Source: .cursor/skills/create-plan/SKILL.md -->
+
+
 # Create New Plan
 
 Create a new plan entity in Neotoma with title = {{input:title}}.
 
 Follow the complete workflow in `foundation/development/plan_workflow.md`. Configuration is read from `foundation-config.yaml`.
 
-This workflow can also be triggered automatically via `.cursor/rules/plan_detection.mdc` when you mention planning-related patterns in natural language (e.g., "create plan", "new plan"). Both paths execute the same workflow.
+This workflow can also be triggered automatically via `.claude/rules/plan_detection.mdc` when you mention planning-related patterns in natural language (e.g., "create plan", "new plan"). Both paths execute the same workflow.
 
 ## Workflow Overview
 
diff --git a/.claude/skills/create_prototype/SKILL.md b/.claude/skills/create_prototype/SKILL.md
index 7f65a99d6..d87306020 100644
--- a/.claude/skills/create_prototype/SKILL.md
+++ b/.claude/skills/create_prototype/SKILL.md
@@ -1,12 +1,11 @@
 ---
-name: create-prototype
-description: Create prototype per foundation command.
-triggers:
-  - create prototype
-  - /create_prototype
-  - create-prototype
+name: create_prototype
+description: Create Prototype
 ---
 
+<!-- Source: .cursor/skills/create-prototype/SKILL.md -->
+
+
 # Create Prototype
 
 Create fully functional client-side prototype for Feature Unit {{input:feature_id}}.
diff --git a/.claude/skills/create_release/SKILL.md b/.claude/skills/create_release/SKILL.md
index 8c9e1d9da..bee4e7f30 100644
--- a/.claude/skills/create_release/SKILL.md
+++ b/.claude/skills/create_release/SKILL.md
@@ -1,14 +1,11 @@
 ---
-name: create-release
-description: Create a new software release with planning, manifest, and execution schedule.
-triggers:
-  - new release
-  - create release
-  - plan release
-  - create-release
-  - /create-release
+name: create_release
+description: Create New Release
 ---
 
+<!-- Source: .cursor/skills/create-release/SKILL.md -->
+
+
 # Create New Release
 
 Orchestrates multiple Feature Units into a cohesive release. Implements the Release workflow from `foundation/development/release_workflow.md`.
@@ -17,9 +14,9 @@ Orchestrates multiple Feature Units into a cohesive release. Implements the Rele
 
 **Explicit Command:** Use when you know exactly what you want: start a new release, plan multi-FU work with dependency resolution, generate execution schedules with parallelization, orchestrate FU creation/execution in dependency order, run cross-FU integration tests.
 
-**Automatic Detection:** This workflow can also be triggered automatically via `.cursor/rules/release_detection.md` when you mention release-related patterns in natural language (e.g., "new release", "release v1.1.0"). Both paths execute the same workflow.
+**Automatic Detection:** This workflow can also be triggered automatically via `.claude/rules/release_detection.md` when you mention release-related patterns in natural language (e.g., "new release", "release v1.1.0"). Both paths execute the same workflow.
 
-This is a foundation command. If installed, it will be available in `.cursor/commands/` via symlink.
+This is a foundation command. If installed, it will be available in `.claude/skills/` via symlink.
 
 ## Prerequisites
 
diff --git a/.claude/skills/create_rule/SKILL.md b/.claude/skills/create_rule/SKILL.md
index 5f2a9c18a..a7f4fad4f 100644
--- a/.claude/skills/create_rule/SKILL.md
+++ b/.claude/skills/create_rule/SKILL.md
@@ -1,15 +1,14 @@
 ---
-name: create-rule
-description: Create Cursor rule for persistent AI guidance.
-triggers:
-  - create rule
-  - /create_rule
-  - create-rule
+name: create_rule
+description: Create Rule
 ---
 
+<!-- Source: .cursor/skills/create-rule/SKILL.md -->
+
+
 # Create Rule
 
-Create a new rule file with `_rules` suffix and automatically create symlink in `.cursor/rules/`.
+Create a new rule file with `_rules` suffix and automatically create symlink in `.claude/rules/`.
 
 **SUBMODULE MODE**: If a submodule name is provided (e.g., `/create-rule foundation`), create the rule in that submodule. If no submodule name is provided, create in the main repository's `docs/` directory.
 
@@ -192,16 +191,16 @@ For foundation submodule, create file following foundation cursor-rules pattern
    ./foundation/scripts/setup-cursor-rules.sh
    ```
 
-2. Verify symlink created in `.cursor/rules/`:
+2. Verify symlink created in `.claude/rules/`:
    - Expected symlink name: `{location}_{name}_rules.md`
-   - Example: `docs/conventions/entity_resolution_rules.md` → `.cursor/rules/conventions_entity_resolution_rules.md`
+   - Example: `docs/conventions/entity_resolution_rules.md` → `.claude/rules/conventions_entity_resolution_rules.md`
 
 3. Output success message:
    ```
    ✅ Rule created successfully!
    
    File: docs/{location}/{name}_rules.md
-   Symlink: .cursor/rules/{location}_{name}_rules.md
+   Symlink: .claude/rules/{location}_{name}_rules.md
    
    The rule is now available to all Cursor agents in this repository.
    
@@ -225,7 +224,7 @@ For foundation submodule, create file following foundation cursor-rules pattern
    ✅ Rule created in submodule successfully!
    
    File: {submodule}/{rule_path}/{name}{suffix}.mdc (for foundation submodule, use .mdc extension)
-   Symlink: .cursor/rules/{prefix}{name}.mdc (if applicable)
+   Symlink: .claude/rules/{prefix}{name}.mdc (if applicable)
    
    The rule is now available to all repositories using this submodule.
    ```
@@ -265,7 +264,7 @@ Prompts:
 
 Creates:
 - `docs/subsystems/entity_resolution_rules.md`
-- `.cursor/rules/subsystems_entity_resolution_rules.md` (symlink)
+- `.claude/rules/subsystems_entity_resolution_rules.md` (symlink)
 
 ### Example 2: Create Foundation Submodule Rule
 
@@ -280,7 +279,7 @@ Prompts:
 
 Creates:
 - `foundation/agent_instructions/cursor_rules/testing_patterns.mdc`
-- `.cursor/rules/foundation_testing_patterns.mdc` (symlink)
+- `.claude/rules/foundation_testing_patterns.mdc` (symlink)
 
 ## Required Documents
 
diff --git a/.claude/skills/debug/SKILL.md b/.claude/skills/debug/SKILL.md
index 75f70eccd..f70531341 100644
--- a/.claude/skills/debug/SKILL.md
+++ b/.claude/skills/debug/SKILL.md
@@ -1,3 +1,10 @@
+---
+name: debug
+description: Debug Command
+---
+
+<!-- Source: foundation/.cursor/skills/debug/SKILL.md -->
+
 ---
 name: debug
 description: Debug workflow per foundation command.
diff --git a/.claude/skills/design_issues/SKILL.md b/.claude/skills/design_issues/SKILL.md
deleted file mode 100644
index 4bf9fd12d..000000000
--- a/.claude/skills/design_issues/SKILL.md
+++ /dev/null
@@ -1,114 +0,0 @@
----
-name: design_issues
-description: Work through needs-design issues depth-first until the design question is resolved and the issue is ready to execute
----
-
-# Design Issues
-
-Use this skill to resolve the design questions blocking `needs-design` issues, one issue at a time, until each is ready to hand off to `/process_issues` for execution.
-
-## Invocation
-
-```
-/design_issues          # list all needs-design issues, then work the oldest/most-referenced
-/design_issues <number> # jump directly to a specific issue by GitHub number
-```
-
-## Workflow
-
-### Step 1: Discover needs-design issues
-
-1. Run `gh issue list --label needs-design --state open --json number,title,body,createdAt,url` to fetch all deferred issues.
-2. For each issue, retrieve the linked Neotoma `plan` entity (matched by issue number or title) and load the stored design question(s) from the plan body.
-3. Also retrieve any existing Neotoma plans linked via `REFERS_TO` from the issue entity — these are candidate prior plans that may already answer or constrain the design question.
-4. Rank issues for default selection:
-   - Issues with the most `REFERS_TO` links to existing plans (most context available) rank first.
-   - Among ties, oldest `createdAt` ranks first.
-
-### Step 2: Present and select
-
-If no issue number was given:
-
-1. Print a numbered list of all needs-design issues with: GitHub number, title, open design question (from plan), and any linked existing plan titles.
-2. Default selection is the top-ranked issue. State: "Working issue #N — `<title>`. Press enter to confirm or type a different number."
-3. In `proactive` mode, proceed with the top-ranked issue without prompting.
-
-### Step 3: Load full context for selected issue
-
-1. Load the full issue body and comment thread via `gh issue view <number> --comments`.
-2. Load the linked `plan` entity snapshot from Neotoma, including the design question and any prior notes.
-3. Load all plans linked via `REFERS_TO` from the issue entity — read their full snapshots, including any mirrored `docs/plans/` files.
-4. Load relevant codebase context: files, modules, or subsystems named in the issue or plan. Read enough to give an informed recommendation.
-5. Load any related issues or PRs referenced in the issue body or plan.
-
-### Step 4: Analyze and attempt autonomous resolution
-
-Before engaging the user, attempt to resolve the design question from loaded context alone:
-
-- Has a prior plan already decided this question? If yes, the answer is to adopt that decision — state it explicitly.
-- Does the codebase already implement a pattern that makes one approach clearly correct? If yes, state the pattern and the answer.
-- Are all design options clearly inferior except one given current architecture and constraints? If yes, recommend that option with rationale.
-
-If autonomous resolution is confident (one clearly correct answer, no architectural ambiguity), proceed directly to Step 6 with that answer. State the answer and reasoning before acting.
-
-### Step 5: Interactive resolution (when autonomous resolution is not confident)
-
-Present the design question with full context:
-
-1. State the question precisely as recorded in the plan.
-2. Summarize relevant context: codebase patterns, related plans, constraints, prior decisions.
-3. Present 2–4 concrete options, each with:
-   - What it entails technically
-   - Trade-offs (complexity, coupling, consistency model, future flexibility)
-   - Compatibility with existing architecture and State Layer constraints
-4. Give a recommendation with rationale.
-5. Ask the user to confirm the recommendation or choose an alternative.
-
-Iterate until the user confirms a direction. Each turn should narrow the question further — do not re-open settled sub-questions.
-
-### Step 6: Record the resolution
-
-Once a design direction is confirmed:
-
-1. Update the linked `plan` entity in Neotoma:
-   - Add the resolved design decision to the plan body.
-   - Change `status` from `needs_design` to `ready` (or `awaiting_execution` if the plan uses that value).
-   - Record who decided (user confirmation vs autonomous) and the rationale.
-2. If a prior linked plan was the source of the answer, add a `REFERS_TO` relationship from the updated plan to that prior plan if not already present.
-3. Update the plan's linked `docs/plans/` file if one is mirrored, to reflect the resolved decision.
-4. Post `add_issue_message` on the GitHub issue summarizing the design decision reached and stating that the issue is now ready for implementation.
-5. Remove the `needs-design` label: `gh issue edit <number> --remove-label needs-design`.
-6. Optionally add an `implementation-ready` label: `gh issue edit <number> --add-label implementation-ready` (skip if the repo does not use this label — check with `gh label list` first).
-
-### Step 7: Offer to continue
-
-After resolving the current issue:
-
-1. Report: "Issue #N resolved. Design decision recorded. `needs-design` label removed."
-2. If other needs-design issues remain, list them and ask: "Work the next issue (#M — `<title>`)? (yes/no)"
-3. In `proactive` mode, proceed to the next issue automatically.
-
-## Storage Requirements
-
-- Update the `plan` entity status and body when a design decision is reached.
-- Record the design decision as a new observation on the plan entity (do not mutate the original design-question observation — add a new one per immutability rules).
-- Create `REFERS_TO` from the resolved plan to any prior plan whose decision was adopted.
-- Store `conversation_message` rows for each substantive design turn and link them to the plan with `REFERS_TO`.
-- Reference every materially cited or updated plan entity in the closing assistant store for this skill invocation.
-
-## Output Requirements
-
-- Always state the design question being worked before asking the user anything.
-- Always show trade-offs for each option — do not present options without trade-offs.
-- Always give a recommendation; do not present options without a preferred direction.
-- After resolution, always post the `add_issue_message` and remove the label before reporting completion.
-- End each invocation with the list of remaining needs-design issues (count and titles), even if zero.
-
-## Constraints
-
-- Never remove `needs-design` without a confirmed design decision recorded in the plan entity.
-- Never execute code changes within this skill — resolution only; hand off to `/process_issues` for implementation.
-- Never re-open a design question that was settled in a prior turn within the same session.
-- Never present more than 4 options for a single design question — consolidate or eliminate dominated options first.
-- Always respect the State Layer boundary: design decisions that would place strategy or execution logic inside Neotoma are not valid options.
-- Always check `gh label list` before adding `implementation-ready` — only add it if the label exists in the repo.
diff --git a/.claude/skills/draft-illustration/SKILL.md b/.claude/skills/draft-illustration/SKILL.md
new file mode 100644
index 000000000..b2ea732c3
--- /dev/null
+++ b/.claude/skills/draft-illustration/SKILL.md
@@ -0,0 +1,92 @@
+---
+name: draft-illustration
+description: Blog Post Visual Style (Cross-Repo)
+---
+
+<!-- Source: foundation/.cursor/skills/draft-illustration/SKILL.md -->
+
+---
+name: draft-illustration
+description: Apply consistent visual style for blog post hero and social images across repos. Use when creating or generating hero images, OG images, or post artwork so all assets share the same look.
+triggers:
+  - draft illustration
+  - blog post image
+  - hero image
+  - post visual style
+  - hero style
+  - OG image
+  - create post image
+  - same visual style
+  - draft-illustration
+  - /draft-illustration
+---
+
+# Blog Post Visual Style (Cross-Repo)
+
+Use this skill whenever you create or generate **hero images**, **OG/social preview images**, or any **post artwork** so that assets have the same visual style across repositories. The style is mandatory for blog/post imagery; repo-specific paths and scripts are documented per project.
+
+## Visual style (mandatory)
+
+All hero and post imagery MUST follow this style. Apply it when prompting image generation (e.g. GenerateImage, DALL·E, Midjourney) or when briefing a designer.
+
+**Visual rules:**
+
+| Rule | Requirement |
+|------|--------------|
+| **Background** | Solid black only. No gradients, no white sections, no mixed backgrounds. |
+| **Foreground** | White line-art. Subtle edge shading for dimensionality is encouraged; large filled areas and color gradients are not. |
+| **Line work** | Polished, refined white outlines with consistent stroke weight. Lines should feel engraved or blueprint-quality — smooth curves, clean joints, slight dimensional depth on edges. Not sketchy or rough. |
+| **Color** | Monochromatic black and white only. No gray tones or other colors outside of subtle edge shading for depth. |
+| **Composition** | Scene-based or centered. Objects may sit on surfaces with perspective (e.g. an angled desk, a platform). Generous negative (black) space around the subject. |
+| **Aesthetic** | Polished, dimensional, iconic. Technical engraving or refined blueprint feel. Not flat/clip-art, not photorealistic. Symbolic objects should feel like they have weight and presence. |
+| **Typography** | None. No text, labels, or captions within the image. |
+
+**Focal brand:** When the post is about a specific product or brand (e.g. Notion, Claude, OpenAI), focus the hero on that brand using recognizable shapes or motifs in the same white line-art style. No logos or wordmarks; the image should read as "this post is about X" at a glance.
+
+## Prompt template for image generation
+
+When generating a new hero or post image, use a prompt that enforces the style. Example structure:
+
+```
+[Subject or theme]. Pure black background. White line-art with polished, refined outlines and subtle edge shading for dimensionality. Engraving or blueprint quality — smooth curves, clean joints, slight depth on edges. Objects may sit on a surface with perspective. Iconic, symbolic, not photorealistic. No text or labels. Generous negative (black) space around the subject.
+```
+
+Replace `[Subject or theme]` with the post topic (e.g. "Agent memory and a source of truth", "Three robot faces in wax-seal stamps on a desk", "Calendar grid connected to a mesh network").
+
+**Style references:** `know-which-of-your-agents-wrote-what-hero.png` (wax seals with dimensional depth on angled desk), `the-argument-cagan-already-won-hero.png` (geometric Atlas figure with polished wireframe).
+
+## Asset variants (when a repo supports them)
+
+Some repos (e.g. markmhendrickson website) expect multiple composed assets from the same style. Create **separate compositions** for each aspect ratio; do not just crop one image.
+
+| Asset | Aspect | Typical use |
+|-------|--------|-------------|
+| Hero | Flexible (keep-proportions) | Full-width on post page |
+| Square thumbnail | 1:1 | Listings, cards, prev/next |
+| OG / social | 1200×630 landscape | Twitter, LinkedIn, etc. |
+
+All three must share the same visual style (black background, white line-art, no typography). Prefer a script or export step to generate OG from a composed 1200×630 source when the repo provides one.
+
+## Repo-specific paths and scripts
+
+Each repository may define where to store assets and which scripts to run. Check that repo's docs (e.g. `README.md`, `content/posts/README.md`, or foundation adapter config) for:
+
+- **Image directory** — e.g. `public/images/posts/`, `static/images/posts/`
+- **Naming** — e.g. `{slug}-hero.png`, `{slug}-hero-square.png`, `{slug}-hero-og.png`, `og/{slug}-1200x630.jpg`
+- **Layout hint** — e.g. `{slug}-hero-style.txt` with `keep-proportions` for uncropped display
+- **Scripts** — e.g. `generate-hero-square-from-hero.mjs`, `npm run generate:og:post -- <slug>`, `regenerate-hero-assets-centered.mjs`
+- **Cache** — e.g. `python3 execution/scripts/generate_posts_cache.py` after adding or changing assets
+
+If the repo has no docs, apply only the **Visual style (mandatory)** and use sensible paths (e.g. `images/posts/`, slug-based filenames).
+
+## Checklist when creating post images
+
+1. **Generate or obtain** the hero (and optional square/OG) using the mandatory visual style and prompt template above.
+2. **Save** assets in the repo's configured directory with the repo's naming convention.
+3. **Add layout hint** when the repo uses it (e.g. `keep-proportions` in `-hero-style.txt`).
+4. **Run repo scripts** for derived assets (square crop, OG export) and cache regeneration when documented.
+5. **Do not** add text, logos, or colors that break the black-background / white-line-art rule.
+
+## Reference
+
+Canonical style reference: **Hero Image Style Guide** in the markmhendrickson website posts README (`execution/website/markmhendrickson/react-app/src/content/posts/README.md`). This skill is the foundation-level summary so the same style can be applied in any repo without reading that file.
diff --git a/.claude/skills/draft_illustration/SKILL.md b/.claude/skills/draft_illustration/SKILL.md
index 3556da1f6..34c594315 100644
--- a/.claude/skills/draft_illustration/SKILL.md
+++ b/.claude/skills/draft_illustration/SKILL.md
@@ -1,19 +1,11 @@
 ---
-name: draft-illustration
-description: Apply consistent visual style for blog post hero and social images across repos. Use when creating or generating hero images, OG images, or post artwork so all assets share the same look.
-triggers:
-  - draft illustration
-  - blog post image
-  - hero image
-  - post visual style
-  - hero style
-  - OG image
-  - create post image
-  - same visual style
-  - draft-illustration
-  - /draft-illustration
+name: draft_illustration
+description: Blog Post Visual Style (Cross-Repo)
 ---
 
+<!-- Source: .cursor/skills/draft-illustration/SKILL.md -->
+
+
 # Blog Post Visual Style (Cross-Repo)
 
 Use this skill whenever you create or generate **hero images**, **OG/social preview images**, or any **post artwork** so that assets have the same visual style across repositories. The style is mandatory for blog/post imagery; repo-specific paths and scripts are documented per project.
diff --git a/.claude/skills/final-review/SKILL.md b/.claude/skills/final-review/SKILL.md
new file mode 100644
index 000000000..3b453f259
--- /dev/null
+++ b/.claude/skills/final-review/SKILL.md
@@ -0,0 +1,100 @@
+---
+name: final-review
+description: Final Review
+---
+
+<!-- Source: foundation/.cursor/skills/final-review/SKILL.md -->
+
+---
+name: final-review
+description: Final review workflow per foundation command.
+triggers:
+  - final review
+  - /final_review
+  - final-review
+---
+
+# Final Review
+
+Present final implementation for review and approval for Feature Unit {{input:feature_id}}.
+
+Follow `foundation/development/feature_unit_workflow.md` Step 4 (Checkpoint 2 — Final Review). Configuration is read from `foundation-config.yaml`.
+
+Implements Checkpoint 2 of the Feature Unit creation workflow. Presents the completed implementation for human review and approval.
+
+## Trigger
+
+- Implementation complete
+- Tests passing
+- PR created (if required by config)
+
+## Tasks
+
+1. **Load configuration:**
+   - Read `foundation-config.yaml` to get feature unit settings
+   - Determine directory structure, testing requirements, git workflow
+
+2. **Run spec compliance validation (if available):**
+   - Execute spec compliance validation script (if repository has one)
+   - If compliance check fails: STOP and present compliance report to user
+     - List all gaps found
+     - Require user to fix gaps, update spec, or explicitly defer requirements before proceeding
+     - Re-run compliance check after fixes
+   - If compliance check passes or not available, continue to next step
+
+3. **Gather implementation summary:**
+   - List all files changed
+   - List tests added (with pass status)
+   - List documentation updated
+   - PR link and status (if PR required)
+   - Compliance report link (if generated)
+
+4. **Verify completion:**
+   - All required tests passing (based on config)
+   - Coverage meets configured targets
+   - PR created with proper format (if required)
+   - Spec compliance validation passed (if available)
+
+5. **Present summary:**
+   - Files changed (count and key files)
+   - Tests added/passing
+   - Coverage achieved vs target
+   - Documentation updated
+   - PR link (if applicable)
+   - Spec compliance status (if available)
+
+6. STOP and prompt user:
+   - "Implementation complete. PR: [link]" (if applicable)
+   - "Please review the implementation"
+   - "Approve for merge? (yes/no)"
+   - "Any final changes needed? (list or 'none')"
+   - "Spec compliance validation: ✅ Pass / ❌ Fail (see report: [link])" (if available)
+
+7. **If user requests changes:**
+   - Apply changes
+   - Re-run tests
+   - Re-run spec compliance validation (if available)
+   - Update PR (if applicable)
+   - Repeat until approved
+
+8. **If approved:**
+   - Mark spec status as `Completed`
+   - Move files from `in_progress/` to `completed/`:
+     ```bash
+     mv {configured_directory}/in_progress/{{input:feature_id}} {configured_directory}/completed/{{input:feature_id}}
+     ```
+   - Update manifest `status: "completed"`
+   - Update repository-specific FU inventory (if configured)
+   - Mark PR as ready for merge (if applicable)
+   - **If using worktrees (from config), clean up worktree:**
+     ```bash
+     # From main repo root
+     git worktree remove {configured_worktree_path}
+     # Or if worktree still has uncommitted changes:
+     git worktree remove --force {configured_worktree_path}
+     ```
+
+## Inputs
+
+- `feature_id` (string): The feature identifier
+
diff --git a/.claude/skills/final_review/SKILL.md b/.claude/skills/final_review/SKILL.md
index d758d4133..9b931c278 100644
--- a/.claude/skills/final_review/SKILL.md
+++ b/.claude/skills/final_review/SKILL.md
@@ -1,12 +1,11 @@
 ---
-name: final-review
-description: Final review workflow per foundation command.
-triggers:
-  - final review
-  - /final_review
-  - final-review
+name: final_review
+description: Final Review
 ---
 
+<!-- Source: .cursor/skills/final-review/SKILL.md -->
+
+
 # Final Review
 
 Present final implementation for review and approval for Feature Unit {{input:feature_id}}.
diff --git a/.claude/skills/fix-feature-bug/SKILL.md b/.claude/skills/fix-feature-bug/SKILL.md
new file mode 100644
index 000000000..e850f0226
--- /dev/null
+++ b/.claude/skills/fix-feature-bug/SKILL.md
@@ -0,0 +1,107 @@
+---
+name: fix-feature-bug
+description: Fix Feature Bug
+---
+
+<!-- Source: foundation/.cursor/skills/fix-feature-bug/SKILL.md -->
+
+---
+name: fix-feature-bug
+description: Fix bugs using structured workflow with error classification and regression tests.
+triggers:
+  - bug
+  - error
+  - fix
+  - broken
+  - not working
+  - failing
+  - fix-feature-bug
+  - /fix-feature-bug
+---
+
+# Fix Feature Bug
+
+Fix a bug in a feature or module.
+
+Configuration is read from `foundation-config.yaml`.
+
+This workflow can also be triggered automatically via `.claude/rules/bug_fix_detection.md` (or `foundation/agent_instructions/cursor_rules/bug_fix_detection.md`) when you mention bug/error-related patterns in natural language (e.g., "bug", "error", "fix", "broken"). Both paths execute the same workflow.
+
+## Workflow
+
+1. **Load configuration:**
+   - Read `foundation-config.yaml` for bug fix settings
+   - Check if error classification is configured
+   - Determine feature/module directory structure
+
+2. **Identify feature/module** from error, path, or context.
+
+3. **Load relevant documents:**
+   - Repository navigation guide (if configured)
+   - Feature/module spec and manifest (if available)
+   - Error classification documentation (if configured)
+   - Relevant subsystem/module documentation (if configured)
+
+4. **Classify bug** (if error classification configured):
+   - Use configured error classification system
+   - Determine correction approach based on class
+
+5. **Apply correction rules:**
+   - **If Class 1 (Implementation bug):** Patch code only
+   - **If Class 2 (Spec bug):** Update spec/manifest first, then align code/tests
+   - **If Class 3 (Architectural bug):** Update subsystem/architecture docs first, then rebuild
+   - **If no classification:** Fix bug and update relevant documentation
+
+6. **Always add a regression test.**
+
+7. **Run tests:**
+   - Run configured test commands
+   - Verify fix doesn't break existing functionality
+
+8. **Output:**
+   - Error class (if classification configured)
+   - Reason for classification
+   - Corrected files
+   - Tests added/updated
+
+## Error Classification (Configurable)
+
+If `development.bug_fix.error_classification.enabled: true` in foundation-config:
+
+- **Class 1:** Implementation bug - spec is correct, code doesn't match spec
+  - **Action:** Patch code only
+- **Class 2:** Spec bug - spec is incomplete or wrong, code matches spec but spec is wrong
+  - **Action:** Update spec/manifest first, then align code/tests
+- **Class 3:** Architectural bug - subsystem/architecture docs are wrong or incomplete
+  - **Action:** Update architecture docs first, then rebuild
+
+## Configuration
+
+Bug fix workflow uses settings from `foundation-config.yaml`:
+
+```yaml
+development:
+  bug_fix:
+    enabled: true
+    error_classification:
+      enabled: false  # Enable if you have error classification system
+      classes:
+        - name: "Class 1"
+          description: "Implementation bug"
+          correction: "Patch code only"
+        - name: "Class 2"
+          description: "Spec bug"
+          correction: "Update spec first, then code"
+        - name: "Class 3"
+          description: "Architectural bug"
+          correction: "Update architecture docs first"
+    require_regression_test: true
+    test_commands:  # Optional, repo-specific test commands
+      - "npm test"
+      - "npm run test:integration"
+```
+
+## Inputs
+
+- `feature_id` or `module_name` (optional): The feature/module identifier to fix
+
diff --git a/.claude/skills/fix_feature_bug/SKILL.md b/.claude/skills/fix_feature_bug/SKILL.md
index c11975761..339f16c9d 100644
--- a/.claude/skills/fix_feature_bug/SKILL.md
+++ b/.claude/skills/fix_feature_bug/SKILL.md
@@ -1,24 +1,18 @@
 ---
-name: fix-feature-bug
-description: Fix bugs using structured workflow with error classification and regression tests.
-triggers:
-  - bug
-  - error
-  - fix
-  - broken
-  - not working
-  - failing
-  - fix-feature-bug
-  - /fix-feature-bug
+name: fix_feature_bug
+description: Fix Feature Bug
 ---
 
+<!-- Source: .cursor/skills/fix-feature-bug/SKILL.md -->
+
+
 # Fix Feature Bug
 
 Fix a bug in a feature or module.
 
 Configuration is read from `foundation-config.yaml`.
 
-This workflow can also be triggered automatically via `.cursor/rules/bug_fix_detection.md` (or `foundation/agent_instructions/cursor_rules/bug_fix_detection.md`) when you mention bug/error-related patterns in natural language (e.g., "bug", "error", "fix", "broken"). Both paths execute the same workflow.
+This workflow can also be triggered automatically via `.claude/rules/bug_fix_detection.md` (or `foundation/agent_instructions/cursor_rules/bug_fix_detection.md`) when you mention bug/error-related patterns in natural language (e.g., "bug", "error", "fix", "broken"). Both paths execute the same workflow.
 
 ## Workflow
 
diff --git a/.claude/skills/manage-error-debugging/SKILL.md b/.claude/skills/manage-error-debugging/SKILL.md
new file mode 100644
index 000000000..462a3bf89
--- /dev/null
+++ b/.claude/skills/manage-error-debugging/SKILL.md
@@ -0,0 +1,189 @@
+---
+name: manage-error-debugging
+description: Manage Error Debugging Automation
+---
+
+<!-- Source: foundation/.cursor/skills/manage-error-debugging/SKILL.md -->
+
+---
+name: manage-error-debugging
+description: Manage error debugging per foundation command.
+triggers:
+  - manage error debugging
+  - /manage_error_debugging
+  - manage-error-debugging
+---
+
+# Manage Error Debugging Automation
+
+Manage the error debugging automation monitoring script (start, stop, status, logs).
+
+## Command Usage
+
+```bash
+/manage_error_debugging [action]
+```
+
+**Actions:**
+- `start` - Start the error debugging watcher in background
+- `stop` - Stop the running watcher
+- `status` - Check if watcher is running and show status
+- `logs` - Show recent logs from the watcher
+- `restart` - Stop and start the watcher
+- (no action) - Show status (default)
+
+## Prerequisites
+
+- Error debugging automation enabled in `foundation-config.yaml`
+- `scripts/trigger_error_debug_cli.js` exists and is executable
+- Node.js installed
+
+## Workflow
+
+### Action: `start`
+
+1. **Check if already running:**
+   - Check for PID file: `.cursor/error_reports/watcher.pid`
+   - If PID file exists, verify process is still running
+   - If running, exit with message: "Error debugging watcher is already running (PID: {pid})"
+
+2. **Verify configuration:**
+   - Load `foundation-config.yaml`
+   - Check `development.error_debugging.enabled === true`
+   - If disabled, exit with error
+
+3. **Create necessary directories:**
+   - Ensure `.cursor/error_reports/` exists
+   - Ensure log directory exists (if configured)
+
+4. **Start watcher in background:**
+   - Run: `node scripts/trigger_error_debug_cli.js --watch > .cursor/error_reports/watcher.log 2>&1 &`
+   - Capture PID of background process
+   - Write PID to `.cursor/error_reports/watcher.pid`
+   - Output: "Started error debugging watcher (PID: {pid})"
+
+5. **Verify start:**
+   - Wait 1 second
+   - Check if process is still running
+   - If not running, read log file and show error
+
+### Action: `stop`
+
+1. **Check if running:**
+   - Read PID from `.cursor/error_reports/watcher.pid`
+   - If PID file doesn't exist, exit: "Error debugging watcher is not running"
+
+2. **Verify process exists:**
+   - Check if process with PID is running
+   - If not running, remove stale PID file and exit: "Watcher process not found (stale PID file removed)"
+
+3. **Stop process:**
+   - Send TERM signal to process
+   - Wait up to 5 seconds for graceful shutdown
+   - If still running, send KILL signal
+   - Remove PID file
+   - Output: "Stopped error debugging watcher (PID: {pid})"
+
+### Action: `status`
+
+1. **Check PID file:**
+   - Read `.cursor/error_reports/watcher.pid`
+   - If not found: "Status: Not running"
+
+2. **Check if process is running:**
+   - Verify process with PID exists
+   - If not: "Status: Not running (stale PID file)"
+   - Remove stale PID file
+
+3. **If running, show:**
+   - PID
+   - Uptime (how long it's been running)
+   - Configuration status (enabled/disabled)
+   - Last log entry (if log file exists)
+
+### Action: `logs`
+
+1. **Check log file:**
+   - Read `.cursor/error_reports/watcher.log`
+   - If not found: "No log file found. Watcher may not have started yet."
+
+2. **Display logs:**
+   - Show last 50 lines (configurable)
+   - Or tail logs if `--follow` flag provided
+
+### Action: `restart`
+
+1. **Run stop action** (if running)
+2. **Wait 1 second**
+3. **Run start action**
+
+## Implementation Notes
+
+**PID File Management:**
+- Store PID in: `.cursor/error_reports/watcher.pid`
+- Remove PID file on stop or if process not found
+
+**Log File:**
+- Logs written to: `.cursor/error_reports/watcher.log`
+- Rotate or truncate on restart (optional)
+
+**Process Verification:**
+```bash
+# Check if process exists (cross-platform)
+if ps -p $PID > /dev/null 2>&1; then
+  # Process is running
+fi
+```
+
+**Platform-Specific:**
+- Use `ps` command (available on macOS, Linux)
+- On Windows, may need `tasklist` or PowerShell `Get-Process`
+
+## Configuration
+
+Configure in `foundation-config.yaml`:
+
+```yaml
+development:
+  error_debugging:
+    enabled: true
+    automation:
+      watch_mode: true  # Enable continuous monitoring
+      cursor_cli:
+        # ... cursor_cli configuration ...
+```
+
+## Examples
+
+```bash
+# Check status
+/manage_error_debugging
+/manage_error_debugging status
+
+# Start watcher
+/manage_error_debugging start
+
+# Stop watcher
+/manage_error_debugging stop
+
+# View logs
+/manage_error_debugging logs
+
+# Restart watcher
+/manage_error_debugging restart
+```
+
+## Related Commands
+
+- `/report` - Report an error (triggers debugging if automation enabled)
+- `/debug` - Manually debug pending errors (deprecated: use `/debug` instead)
+
+## Error Handling
+
+- If watcher fails to start, show error from log file
+- If PID file exists but process not found, clean up stale PID file
+- If configuration disabled, prevent start and show message
+- On stop, handle graceful shutdown with timeout fallback to KILL
+
+
+
diff --git a/.claude/skills/manage_error_debugging/SKILL.md b/.claude/skills/manage_error_debugging/SKILL.md
index 66da25b66..1b27af593 100644
--- a/.claude/skills/manage_error_debugging/SKILL.md
+++ b/.claude/skills/manage_error_debugging/SKILL.md
@@ -1,12 +1,11 @@
 ---
-name: manage-error-debugging
-description: Manage error debugging per foundation command.
-triggers:
-  - manage error debugging
-  - /manage_error_debugging
-  - manage-error-debugging
+name: manage_error_debugging
+description: Manage Error Debugging Automation
 ---
 
+<!-- Source: .cursor/skills/manage-error-debugging/SKILL.md -->
+
+
 # Manage Error Debugging Automation
 
 Manage the error debugging automation monitoring script (start, stop, status, logs).
diff --git a/.claude/skills/process_prs/SKILL.md b/.claude/skills/process_prs/SKILL.md
index decd4d066..73c2b315b 100644
--- a/.claude/skills/process_prs/SKILL.md
+++ b/.claude/skills/process_prs/SKILL.md
@@ -1,16 +1,11 @@
 ---
 name: process_prs
-description: Process open pull requests — triage readiness, run security checks, request Opus review on substantial PRs, post per-issue closure-narrative comments, merge eligible PRs, and detect release PRs and hand off to /release.
-triggers:
-  - process prs
-  - /process_prs
-  - work the pr queue
-  - triage prs
-  - review open prs
+description: Process PRs
 ---
 
 <!-- Source: .cursor/skills/process-prs/SKILL.md -->
 
+
 # Process PRs
 
 Use this skill to work the open PR queue end-to-end: assess merge readiness, run security gates, selectively request Claude Opus review on substantial PRs, merge eligible PRs, and hand off release PRs to `/release`.
diff --git a/.claude/skills/publish-plan/SKILL.md b/.claude/skills/publish-plan/SKILL.md
new file mode 100644
index 000000000..f9b60af0f
--- /dev/null
+++ b/.claude/skills/publish-plan/SKILL.md
@@ -0,0 +1,218 @@
+---
+name: publish-plan
+description: publish-plan
+---
+
+<!-- Source: foundation/.cursor/skills/publish-plan/SKILL.md -->
+
+---
+name: publish-plan
+description: Convert a plan file into a GitHub Discussion post for public input.
+triggers:
+  - publish plan
+  - share plan
+  - publish-plan
+  - /publish-plan
+---
+
+# publish-plan
+
+Convert a plan file (release plan, feature spec, or `.cursor/plans/` file) into a
+GitHub Discussion post written for external readers. Strips internal references and
+PII, rewrites for a public audience, and optionally posts via the GitHub CLI.
+
+## When to Use
+
+Use when you have a plan in progress and want external input before execution.
+Pass the path to any plan document as the argument:
+
+```
+/publish-plan docs/releases/in_progress/v0.12.0/release_plan.md
+/publish-plan .cursor/plans/some_plan.md
+/publish-plan docs/feature_units/in_progress/FU-2026-01-001/FU-2026-01-001_spec.md
+```
+
+Optionally pass a specific question to ask readers as a second argument:
+
+```
+/publish-plan docs/releases/in_progress/v0.12.0/release_plan.md "Does this sync model work for your use case?"
+```
+
+---
+
+## Step 1: Read and Parse the Plan
+
+1. Read the plan file at the provided path.
+2. Extract the following from the document:
+   - **Goal / motivation**: Why does this exist? What problem does it solve?
+   - **Approach / key decisions**: What choices were made or are still open?
+   - **Scope boundaries**: What is explicitly excluded or deferred?
+   - **Open questions**: What is uncertain or unresolved?
+
+---
+
+## Step 2: Strip Internal References
+
+Remove or redact anything that should not be public:
+
+- Full names and email addresses of individuals
+- Internal Slack channels, ticket numbers, or system identifiers that leak org structure
+- Pricing, cost, or revenue figures
+- Internal hostnames, credentials, or environment-specific configuration values
+- Agent execution notes (batch status, orchestrator output, FU dependency trees)
+- Anything marked `<!-- internal -->` or `[INTERNAL]`
+
+Do not strip:
+- Feature IDs (FU-YYYY-MM-NNN) — these are useful public references
+- Architecture decisions and technical rationale
+- Version numbers and release IDs
+- Links to public repo files or issues
+
+---
+
+## Step 3: Draft the Discussion Post
+
+Rewrite the extracted content into the following structure. Write in plain prose
+for an external developer audience. No jargon specific to the foundation framework.
+
+```markdown
+## What we're building
+
+[2-3 sentences: the problem being solved and the general approach. No implementation detail.]
+
+## Key decisions
+
+[3-5 bullet points: choices made or still open. Frame as "We chose X because Y" or "We're deciding between X and Y".]
+
+## What's out of scope (for now)
+
+[2-4 bullet points: explicit exclusions that might surprise readers or that they might assume are included.]
+
+## Where we want input
+
+[The specific question. One sentence. Concrete. If the user provided a question, use it here. Otherwise, derive the most useful open question from the plan.]
+
+---
+
+*This is a pre-execution plan. We're sharing it before we build to get early input.
+Comments and questions welcome.*
+```
+
+Apply the content style rules:
+- Complete sentences throughout
+- No em dashes, no "leverage", no "seamless", no marketing language
+- Active voice
+- 15-20 words per sentence maximum
+- No filler transitions ("Furthermore", "Moreover", "In addition")
+
+---
+
+## Step 4: Preview and Confirm
+
+Show the drafted post to the user and ask:
+
+```
+Here is the Discussion post draft:
+
+---
+[post content]
+---
+
+Options:
+1. Post to GitHub Discussions now (requires gh CLI and Discussions enabled)
+2. Copy to clipboard / show as output only
+3. Edit — describe what to change
+```
+
+Wait for the user's choice before proceeding.
+
+---
+
+## Step 5: Post to GitHub Discussions (if requested)
+
+If the user chooses to post, use the GitHub CLI GraphQL API:
+
+```bash
+# Get the repository ID and Discussions category ID
+REPO_OWNER=$(gh repo view --json owner -q '.owner.login')
+REPO_NAME=$(gh repo view --json name -q '.name')
+
+# List available discussion categories
+gh api graphql -f query='
+  query($owner: String!, $name: String!) {
+    repository(owner: $owner, name: $name) {
+      discussionCategories(first: 10) {
+        nodes { id name }
+      }
+    }
+  }
+' -f owner="$REPO_OWNER" -f name="$REPO_NAME"
+```
+
+Use category "RFC / Plans" if it exists. If it does not exist, use the closest
+match ("Ideas", "General") and note to the user that a dedicated category would
+be better. Do not create the category automatically.
+
+Post the discussion:
+
+```bash
+REPO_ID=$(gh api graphql -f query='
+  query($owner: String!, $name: String!) {
+    repository(owner: $owner, name: $name) { id }
+  }
+' -f owner="$REPO_OWNER" -f name="$REPO_NAME" -q '.data.repository.id')
+
+CATEGORY_ID="<selected category id>"
+TITLE="<derived from plan title or release version>"
+BODY="<the drafted post content>"
+
+gh api graphql -f query='
+  mutation($repoId: ID!, $categoryId: ID!, $title: String!, $body: String!) {
+    createDiscussion(input: {
+      repositoryId: $repoId,
+      categoryId: $categoryId,
+      title: $title,
+      body: $body
+    }) {
+      discussion { url }
+    }
+  }
+' -f repoId="$REPO_ID" -f categoryId="$CATEGORY_ID" \
+  -f title="$TITLE" -f body="$BODY"
+```
+
+Report the Discussion URL on success.
+
+---
+
+## Step 6: Follow-up Reminder
+
+After posting (or outputting the draft), remind the user:
+
+```
+Remember to reply in the thread once a decision is made. A single note —
+"We went with X because Y" — closes the loop for anyone who finds the
+thread later.
+```
+
+---
+
+## Error Handling
+
+**gh CLI not installed or not authenticated:**
+Output the draft post only. Include a note: "Install and authenticate the GitHub
+CLI (`gh auth login`) to post directly from this skill."
+
+**Discussions not enabled on the repository:**
+Output the draft post only. Include a note: "Enable Discussions in the
+repository Settings to use the post step."
+
+**Plan file not found:**
+Exit with: "Plan file not found: {path}. Pass the path to an existing plan document."
+
+---
+
+## Configuration
+
+No configuration required. The skill reads `foundation-config.yaml` for the
+repository name and remote when deriving post metadata, but falls back to `gh repo view`.
diff --git a/.claude/skills/publish/SKILL.md b/.claude/skills/publish/SKILL.md
index b4de8a653..996193f82 100644
--- a/.claude/skills/publish/SKILL.md
+++ b/.claude/skills/publish/SKILL.md
@@ -1,3 +1,10 @@
+---
+name: publish
+description: publish
+---
+
+<!-- Source: foundation/.cursor/skills/publish/SKILL.md -->
+
 ---
 name: publish
 description: Publish workflow per foundation publish command.
diff --git a/.claude/skills/publish_plan/SKILL.md b/.claude/skills/publish_plan/SKILL.md
index 22797f5c1..42d07f234 100644
--- a/.claude/skills/publish_plan/SKILL.md
+++ b/.claude/skills/publish_plan/SKILL.md
@@ -1,13 +1,11 @@
 ---
-name: publish-plan
-description: Convert a plan file into a GitHub Discussion post for public input.
-triggers:
-  - publish plan
-  - share plan
-  - publish-plan
-  - /publish-plan
+name: publish_plan
+description: publish-plan
 ---
 
+<!-- Source: .cursor/skills/publish-plan/SKILL.md -->
+
+
 # publish-plan
 
 Convert a plan file (release plan, feature spec, or `.cursor/plans/` file) into a
diff --git a/.claude/skills/pull/SKILL.md b/.claude/skills/pull/SKILL.md
index 0ec77848d..2791b3317 100644
--- a/.claude/skills/pull/SKILL.md
+++ b/.claude/skills/pull/SKILL.md
@@ -1,3 +1,10 @@
+---
+name: pull
+description: pull
+---
+
+<!-- Source: foundation/.cursor/skills/pull/SKILL.md -->
+
 ---
 name: pull
 description: Pull from origin; supports /pull <submodule>.
diff --git a/.claude/skills/push/SKILL.md b/.claude/skills/push/SKILL.md
index 5fed58e47..04bd07df3 100644
--- a/.claude/skills/push/SKILL.md
+++ b/.claude/skills/push/SKILL.md
@@ -1,3 +1,10 @@
+---
+name: push
+description: push
+---
+
+<!-- Source: foundation/.cursor/skills/push/SKILL.md -->
+
 ---
 name: push
 description: Push current branch to origin; supports /push <submodule>.
diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md
index 533428f45..c54d56c92 100644
--- a/.claude/skills/release/SKILL.md
+++ b/.claude/skills/release/SKILL.md
@@ -1,18 +1,11 @@
 ---
 name: release
-description: Prepare a GitHub + npm + sandbox release with preview. Covers preflight, changelog preview, RC branch + PR for public review, version bump, tag, GitHub Release creation, npm publish, and sandbox.neotoma.io deployment.
-triggers:
-  - new release
-  - release
-  - /release
-  - create release
-  - prepare a release
-  - prepare release
-  - prep release
-  - /publish
-  - publish
+description: Release
 ---
 
+<!-- Source: .cursor/skills/release/SKILL.md -->
+
+
 # Release
 
 Prepare and ship a GitHub + npm + sandbox release with a mandatory preview step. A confirmed **execute** run is **not complete** until **`npm publish`** succeeds from the published package root and `sandbox.neotoma.io` is deployed and verified, unless the user explicitly scoped the request to GitHub-only / no registry / no sandbox.
diff --git a/.claude/skills/report-error/SKILL.md b/.claude/skills/report-error/SKILL.md
new file mode 100644
index 000000000..aed757c7d
--- /dev/null
+++ b/.claude/skills/report-error/SKILL.md
@@ -0,0 +1,1508 @@
+---
+name: report-error
+description: Report Error Command
+---
+
+<!-- Source: foundation/.cursor/skills/report-error/SKILL.md -->
+
+---
+name: report-error
+description: Report error per foundation command.
+triggers:
+  - report error
+  - /report_error
+  - report-error
+---
+
+# Report Error Command
+
+## Purpose
+
+Enable agents to report errors for automated resolution by Cursor Cloud Agent. This command detects, classifies, and documents errors in a structured format for systematic resolution.
+
+Supports **cross-repo reporting**: Report errors to sibling repositories (repos sharing the same parent directory) by passing the target repo name.
+
+## Command Usage
+
+```bash
+/report_error [target-repo-name] [--no-wait] [--timeout SECONDS] [--poll-interval SECONDS]
+```
+
+**Parameters:**
+- `target-repo-name` (optional): Name of sibling repository to report error to
+  - Must be a sibling repository (shares same parent directory)
+  - Example: If current repo is `/Users/user/Projects/personal`, target `neotoma` resolves to `/Users/user/Projects/neotoma`
+  - If omitted: Auto-detect target repository based on error origin (see Auto-Detection below)
+- `--no-wait` (optional): Disable wait-for-resolution mode (default: wait mode is enabled)
+- `--timeout SECONDS` (optional): Maximum time to wait for resolution (default: 300 seconds / 5 minutes)
+- `--poll-interval SECONDS` (optional): How often to check error status (default: 5 seconds)
+
+**Default Behavior:**
+- **Wait mode is enabled by default** - Agent will monitor error status until resolved or timeout
+- **Auto-detection is enabled** - If target-repo-name is not provided, automatically detect target repository based on error origin
+
+**Examples:**
+```bash
+# Auto-detect target repo and wait for resolution (default behavior)
+/report_error
+
+# Explicitly specify target repo (auto-detection disabled)
+/report_error neotoma
+
+# Disable wait mode (report and continue immediately)
+/report_error --no-wait
+
+# Custom timeout (10 minutes, default is 5 minutes)
+/report_error --timeout 600
+
+# Custom poll interval (check every 2 seconds, default is 5 seconds)
+/report_error --poll-interval 2
+
+# Explicit target repo with custom timeout
+/report_error neotoma --timeout 600
+```
+
+## When to Use
+
+Use this command when you encounter:
+- Build errors (TypeScript compilation, module resolution)
+- Runtime errors (MCP server errors, API failures, database errors)
+- Test failures
+- Dependency issues (missing modules, version conflicts)
+- Configuration errors (missing env vars, invalid config)
+
+**Auto-Detection:** The command automatically detects the target repository when errors originate from MCP servers or external modules. For example:
+- Errors from `mcp_neotoma_*` functions → automatically report to `neotoma` repo
+- Errors from `mcp_asana_*` functions → automatically report to `asana` repo (if exists)
+- Errors with file paths containing `/Projects/neotoma/` → automatically report to `neotoma` repo
+
+## Workflow
+
+### 1. Target Repository Resolution
+
+1. **Get Current Repository Path:**
+   ```bash
+   git rev-parse --show-toplevel
+   ```
+   Store as `current_repo_path`
+
+2. **Auto-Detect Target Repository (if target-repo-name not provided):**
+   
+   Analyze error context to determine target repository:
+   
+   **MCP Error Detection:**
+   - If error message contains `MCP error` or `mcp_` prefix:
+     - Extract MCP server name from error context
+     - Check `agent_context.command` for MCP function names (e.g., `mcp_neotoma_ingest_structured`)
+     - Map MCP server to target repository using configured mapping or default patterns:
+       - `mcp_neotoma` → `neotoma`
+       - `mcp_asana` → `asana` (if exists)
+       - `mcp_gmail` → `gmail` (if exists)
+       - `mcp_google-calendar` or `mcp_google_calendar` → `google-calendar` (if exists)
+       - Pattern: `mcp_<server-name>` → lookup in `mcp_server_mapping` config or use `<server-name>`
+     - Validate target repository exists before using
+   
+   **Module Path Detection:**
+   - If error contains file paths:
+     - Extract repository name from path patterns:
+       - `/Users/user/Projects/neotoma/` → `neotoma`
+       - `/Users/user/Projects/foundation/` → `foundation`
+     - Check if path matches sibling repository structure
+   
+   **Error Source Detection:**
+   - If error originates from MCP call:
+     - Check `agent_context.command` for MCP function names
+     - Extract server name from command (e.g., `mcp_neotoma_ingest_structured` → `neotoma`)
+   
+   **Fallback:**
+   - If auto-detection fails or no match found:
+     - Use `current_repo_path` (local reporting)
+     - Log warning: "Could not auto-detect target repository, using current repo"
+
+3. **Resolve Target Repository Path:**
+   - If `target-repo-name` parameter provided:
+     - Use explicit target (skip auto-detection)
+     - Get parent directory: `dirname(current_repo_path)`
+     - Construct target path: `parent_dir/target-repo-name`
+     - Example: Current repo at `/Users/user/Projects/personal`, target `neotoma` → `/Users/user/Projects/neotoma`
+   - If parameter omitted and auto-detection succeeded:
+     - Use auto-detected target repository
+   - If parameter omitted and auto-detection failed:
+     - Use `current_repo_path` (local reporting)
+
+4. **Sanitize Repository Name** (if provided or auto-detected):
+   - Ensure repo name doesn't contain path traversal characters (`..`, `/`, `\`)
+   - Validate repo name is a valid directory name (alphanumeric, hyphens, underscores, dots)
+   - Abort if repo name contains invalid characters
+
+5. **Validate Target Repository:**
+   - Verify target path exists and is a directory
+   - Verify target contains `.git` directory (is a git repository)
+   - Verify write permissions to target directory
+   - If validation fails: abort with clear error message
+
+### 2. Error Detection & Collection
+
+Extract the following from context:
+- Error message and stack trace
+- Affected files/modules from error paths
+- Agent context (agent_id, task being performed, command name)
+- Environment details (Node version, OS, etc.)
+- **MCP context**: Function names, server identifiers, module paths
+
+**For Auto-Detection:**
+- Extract MCP server name from error message (e.g., "MCP error" from `mcp_neotoma`)
+- Extract command name from agent context (e.g., `mcp_neotoma_ingest_structured`)
+- Extract repository paths from stack traces and affected files
+- Map detected sources to sibling repository names
+
+### 3. Error Classification
+
+Classify error into one of these categories:
+- **build**: TypeScript compilation, module resolution, missing dependencies
+- **runtime**: MCP server errors, API failures, database errors
+- **test**: Test failures, assertion errors
+- **dependency**: Missing modules, version conflicts
+- **configuration**: Missing env vars, invalid config
+
+### 4. Severity Assessment
+
+Assign severity based on impact:
+- **critical**: Server crashes, data loss, security issues
+- **high**: Feature breakage, blocking errors
+- **medium**: Non-blocking errors, warnings
+- **low**: Cosmetic issues, deprecation warnings
+
+### 5. Generate Error Report
+
+Create a structured error report with:
+- Error ID (UUIDv7 or timestamp-based)
+- Timestamp (ISO 8601)
+- Category and severity
+- Sanitized error message (no PII)
+- Truncated stack trace (max 5000 chars)
+- Affected files and modules
+- Agent context
+- Environment details
+- **Repository metadata** (source_repo, target_repo)
+- Resolution status (initially "pending")
+
+### 6. Store Error Report in Target Repository
+
+1. **Ensure Target Directory Structure:**
+   - Create `target_repo/.cursor/error_reports/` if missing
+   - Create `target_repo/.cursor/error_reports/pending/` if missing
+   - Create `target_repo/.cursor/error_reports/resolved/` if missing
+
+2. **Write Error Report Files:**
+   - Save JSON: `target_repo/.cursor/error_reports/pending/error_[timestamp]_[category].json`
+   - Save Markdown: `target_repo/.cursor/error_reports/pending/error_[timestamp]_[category].md`
+
+3. **Update Pending Queue:**
+   - Append to `target_repo/.cursor/error_reports/pending.json`
+   - Include priority/severity for processing order
+   - File paths in pending.json should reference the pending/ subdirectory
+
+### 7. Output Summary
+
+Present to user:
+- Error ID and category
+- Severity level
+- Target repository path (indicate if auto-detected)
+- Location of report files
+- Queue status
+
+### 8. Wait-for-Resolution (Default Behavior)
+
+**IMPORTANT**: Wait mode is enabled by default unless `--no-wait` is specified.
+
+After creating error report, monitor resolution status:
+
+1. **Check Wait Mode:**
+   - If `--no-wait` flag provided: Skip wait mode, exit immediately
+   - Otherwise: Proceed with wait mode
+
+2. **Monitor Resolution:**
+   - Poll error report file for status changes
+   - **Critical**: Check both `pending/` and `resolved/` directories on each poll
+     - Files are moved from `pending/` to `resolved/` by Cursor Cloud Agent upon resolution
+     - If file not found in `pending/`, check `resolved/` before assuming file is missing
+   - Check `resolution_status` field in JSON report
+   - Status values: `pending` → `in_progress` → `resolved` | `failed`
+   - Use configured timeout and poll interval
+
+3. **Resolution Detection:**
+   - **Resolved:** Status changes to `"resolved"`
+     - Output resolution notes
+     - Exit with success
+   - **Failed:** Status changes to `"failed"`
+     - Output failure reason
+     - Exit with error
+   - **Timeout:** Timeout reached while status is `pending` or `in_progress`
+     - Output current status
+     - Exit with warning (non-fatal)
+
+4. **Resume/Retry Logic:**
+   - After resolution, agent can:
+     - **Retry:** Re-execute the operation that failed
+     - **Skip:** If error indicates operation should be skipped
+     - **Continue:** Proceed with next operation
+
+## Error Report Schema
+
+```json
+{
+  "error_id": "uuid-v7",
+  "timestamp": "ISO-8601",
+  "category": "build|runtime|test|dependency|configuration",
+  "severity": "critical|high|medium|low",
+  "error_message": "sanitized error message",
+  "stack_trace": "truncated stack trace",
+  "affected_files": ["path/to/file1.ts", "path/to/file2.ts"],
+  "affected_modules": ["module_name"],
+  "agent_context": {
+    "agent_id": "cursor-agent",
+    "task": "description of task",
+    "command": "command_name if applicable"
+  },
+  "repositories": {
+    "source_repo": {
+      "path": "/absolute/path/to/source/repo",
+      "name": "repo-name",
+      "remote_url": "git@github.com:user/repo.git"
+    },
+    "target_repo": {
+      "path": "/absolute/path/to/target/repo",
+      "name": "target-repo-name",
+      "remote_url": "git@github.com:user/target.git"
+    }
+  },
+  "environment": {
+    "node_version": "v20.x.x",
+    "os": "darwin|linux|windows",
+    "neotoma_env": "development|production"
+  },
+  "resolution_status": "pending|in_progress|resolved|failed",
+  "resolution_notes": ""
+}
+```
+
+## Path Sanitization Rules
+
+**Repository Name Validation:**
+- Ensure repo name doesn't contain path traversal: `..`, `/`, `\`
+- Allow only valid directory name characters: alphanumeric, hyphens, underscores, dots
+- Reject repo names that don't match pattern: `^[a-zA-Z0-9._-]+$`
+- Example valid names: `neotoma`, `personal-project`, `my_repo`, `repo.2`
+- Example invalid names: `../other`, `repo/subdir`, `../../secret`
+
+**Path Construction:**
+```javascript
+// Get current repo root
+const currentRepoPath = execSync('git rev-parse --show-toplevel').toString().trim();
+
+// If target repo name provided
+if (targetRepoName) {
+  // Sanitize repo name first
+  if (!/^[a-zA-Z0-9._-]+$/.test(targetRepoName)) {
+    throw new Error(`Invalid repo name: ${targetRepoName}. Only alphanumeric, hyphens, underscores, and dots allowed.`);
+  }
+  
+  // Get parent directory
+  const parentDir = path.dirname(currentRepoPath);
+  
+  // Construct target repo path
+  const targetPath = path.join(parentDir, targetRepoName);
+  
+  return targetPath;
+} else {
+  // Use current repo
+  return currentRepoPath;
+}
+```
+
+## Target Repository Validation
+
+Before writing error report, validate target repository:
+
+1. **Path Exists:**
+   ```javascript
+   if (!fs.existsSync(targetPath)) {
+     throw new Error(`Target repository not found: ${targetPath}`);
+   }
+   ```
+
+2. **Is Directory:**
+   ```javascript
+   if (!fs.statSync(targetPath).isDirectory()) {
+     throw new Error(`Target path is not a directory: ${targetPath}`);
+   }
+   ```
+
+3. **Is Git Repository:**
+   ```javascript
+   const gitPath = path.join(targetPath, '.git');
+   if (!fs.existsSync(gitPath)) {
+     throw new Error(`Target path is not a git repository: ${targetPath}`);
+   }
+   ```
+
+4. **Is Writable:**
+   ```javascript
+   try {
+     fs.accessSync(targetPath, fs.constants.W_OK);
+   } catch {
+     throw new Error(`No write permission for target repository: ${targetPath}`);
+   }
+   ```
+
+If any validation fails, abort with clear error message and do not write error report.
+
+## Error Message Sanitization Rules
+
+Apply these rules when generating reports:
+1. Remove PII from error messages
+2. Truncate stack traces to max 5000 characters
+3. Replace sensitive paths with placeholders
+4. Redact API keys, tokens, credentials
+5. Remove user-specific data from file paths
+
+## Error Handling & User Feedback
+
+**Validation Failures:**
+
+1. **Invalid Repo Name:**
+   ```
+   Error: Invalid repo name: ../other. Only alphanumeric, hyphens, underscores, and dots allowed.
+   ```
+
+2. **Target Repo Not Found:**
+   ```
+   Error: Target repository not found: /Users/user/Projects/non-existent-repo
+   
+   Available sibling repositories:
+   - neotoma
+   - personal-project
+   - another-repo
+   ```
+
+3. **Not a Git Repository:**
+   ```
+   Error: Target path is not a git repository: /Users/user/Projects/some-dir
+   
+   Target must be a git repository (contains .git directory).
+   ```
+
+4. **No Write Permission:**
+   ```
+   Error: No write permission for target repository: /Users/user/Projects/neotoma
+   
+   Check file permissions and try again.
+   ```
+
+**Success Feedback:**
+```
+Error report created successfully.
+
+Error ID: 01JQZ8X9K2M3N4P5Q6R7S8T9U0
+Category: build
+Severity: high
+Target: /Users/user/Projects/neotoma
+
+Report saved to:
+- /Users/user/Projects/neotoma/.cursor/error_reports/pending/error_20250131_143022_build.json
+- /Users/user/Projects/neotoma/.cursor/error_reports/pending/error_20250131_143022_build.md
+
+Added to pending queue for resolution.
+```
+
+## Example Usage
+
+### Scenario 1: Auto-Detection from File Path
+
+```
+Agent: I encountered a TypeScript compilation error while building the project.
+
+Error: Cannot find module '../db'
+  at Object.<anonymous> (/Users/user/Projects/neotoma/src/services/raw_storage.ts:1:1)
+  ...
+
+Command: /report_error
+```
+
+Agent will:
+1. Auto-detect target repo: Extract `/Users/user/Projects/neotoma/` from stack trace → target: `neotoma`
+2. Validate target repo exists and is writable
+3. Classify as "build" error with "high" severity
+4. Extract affected files: `src/services/raw_storage.ts`, etc.
+5. Generate error report with sanitized paths
+6. Save to neotoma repo's `.cursor/error_reports/pending/error_20250131_143022_build.json`
+7. Add to neotoma's pending queue
+8. Wait for resolution (default behavior)
+9. Output summary with error ID and auto-detected target
+
+### Scenario 2: Auto-Detection from MCP Error
+
+```
+Agent: Working in personal-project repo, encountered MCP error.
+
+Error: MCP error -32603: Failed to upload to storage: Bucket not found
+Command: mcp_neotoma_ingest_structured
+
+Command: /report_error
+```
+
+Agent will:
+1. Auto-detect target repo: Extract `mcp_neotoma` from command context → target: `neotoma`
+2. Resolve target repo: `/Users/user/Projects/neotoma` (sibling of personal-project)
+3. Validate target repo exists and is writable
+4. Classify as "runtime" error with "high" severity
+5. Generate error report with repository metadata (source: personal-project, target: neotoma)
+6. Save to neotoma repo's `.cursor/error_reports/pending/`
+7. Add to neotoma's pending queue
+8. Wait for resolution (default behavior)
+9. Output summary showing auto-detected target repo path
+
+### Scenario 2b: Explicit Target (Overrides Auto-Detection)
+
+```
+Agent: Working in personal-project repo, want to explicitly report to neotoma.
+
+Error: MCP error -32603: Failed to upload to storage: Bucket not found
+
+Command: /report_error neotoma
+```
+
+Agent will:
+1. Skip auto-detection (explicit target provided)
+2. Resolve target repo: `/Users/user/Projects/neotoma` (sibling of personal-project)
+3. Validate target repo exists and is writable
+4. Classify as "runtime" error with "high" severity
+5. Generate error report with repository metadata (source: personal-project, target: neotoma)
+6. Save to neotoma repo's `.cursor/error_reports/pending/`
+7. Add to neotoma's pending queue
+8. Wait for resolution (default behavior)
+9. Output summary showing target repo path
+
+### Scenario 3: Auto-Detection Fallback to Local
+
+```
+Agent: Encountered error with no clear repository origin.
+
+Error: Generic runtime error
+Command: /report_error
+```
+
+Agent will:
+1. Attempt auto-detection: No MCP patterns, no clear repo paths found
+2. Fallback to current repository (local reporting)
+3. Log warning: "Could not auto-detect target repository, using current repo"
+4. Generate error report
+5. Save to current repo's `.cursor/error_reports/pending/`
+6. Wait for resolution (default behavior)
+
+### Scenario 4: Invalid Target Repo
+
+```
+Command: /report_error ../secret-repo
+```
+
+Agent will:
+1. Detect invalid repo name (contains `..`)
+2. Abort with error: "Invalid repo name: ../secret-repo. Only alphanumeric, hyphens, underscores, and dots allowed."
+3. Do not create error report
+
+## Cross-Repo File Writing Logic
+
+**Directory Creation:**
+```javascript
+const errorReportsDir = path.join(targetRepoPath, '.cursor', 'error_reports');
+const pendingDir = path.join(errorReportsDir, 'pending');
+const resolvedDir = path.join(errorReportsDir, 'resolved');
+
+// Create directories if they don't exist
+fs.mkdirSync(errorReportsDir, { recursive: true });
+fs.mkdirSync(pendingDir, { recursive: true });
+fs.mkdirSync(resolvedDir, { recursive: true });
+```
+
+**File Naming:**
+```javascript
+const timestamp = new Date().toISOString().replace(/[:.]/g, '').slice(0, 15);
+const jsonFilename = `error_${timestamp}_${category}.json`;
+const mdFilename = `error_${timestamp}_${category}.md`;
+
+const jsonPath = path.join(pendingDir, jsonFilename);
+const mdPath = path.join(pendingDir, mdFilename);
+```
+
+**Write Error Reports:**
+```javascript
+// Write JSON report
+fs.writeFileSync(jsonPath, JSON.stringify(errorReport, null, 2), 'utf8');
+
+// Write Markdown summary
+fs.writeFileSync(mdPath, markdownSummary, 'utf8');
+
+// Update pending queue
+const pendingPath = path.join(errorReportsDir, 'pending.json');
+let pending = [];
+if (fs.existsSync(pendingPath)) {
+  pending = JSON.parse(fs.readFileSync(pendingPath, 'utf8'));
+}
+pending.push({
+  error_id: errorReport.error_id,
+  timestamp: errorReport.timestamp,
+  category: errorReport.category,
+  severity: errorReport.severity,
+  file_path: jsonPath
+});
+fs.writeFileSync(pendingPath, JSON.stringify(pending, null, 2), 'utf8');
+```
+
+## File Structure
+
+Error reports are stored in the **target repository's** `.cursor/error_reports/` directory:
+
+```
+target_repo/.cursor/
+  error_reports/
+    pending.json                           # Queue of errors awaiting resolution
+    pending/                               # Pending error reports
+      error_20250131_143022_build.json    # Individual error reports (JSON)
+      error_20250131_143022_build.md      # Human-readable summaries (Markdown)
+    resolved/                              # Archived resolved errors
+      error_20250131_143022_build.json
+      error_20250131_143022_build.md
+```
+
+## Integration with Cursor Cloud Agent
+
+The Cursor Cloud Agent will:
+1. Monitor `.cursor/error_reports/pending.json`
+2. Process errors in priority order (critical → low)
+3. Update `resolution_status` when working on error
+4. **Move resolved errors from `.cursor/error_reports/pending/` to `.cursor/error_reports/resolved/`**
+5. Add resolution notes to error report
+
+**Important for Wait Mode**: When monitoring for resolution, the agent must check both `pending/` and `resolved/` directories, as the Cursor Cloud Agent moves files upon resolution. If a file is not found in `pending/`, check `resolved/` before assuming the file is missing.
+
+## Integration with Existing Commands
+
+### With `fix_feature_bug`
+
+- Errors classified as bugs can trigger the `fix-feature-bug` skill
+- Agent can auto-classify certain error types as bugs
+- Bug fix workflow will update error report resolution status
+
+### With `analyze`
+
+- Can analyze error patterns across multiple reports
+- Identify recurring issues
+- Generate error trend reports
+
+## Configuration
+
+Error reporting behavior can be configured in `foundation-config.yaml`:
+
+```yaml
+development:
+  error_reporting:
+    enabled: true
+    auto_detect: true  # Enable automatic target repository detection
+    auto_classify_bugs: true
+    severity_threshold: "medium"
+    max_stack_trace_length: 5000
+    retention_days: 30
+    output_directory: ".cursor/error_reports"
+    wait_by_default: true  # Enable wait mode by default (can disable with --no-wait)
+    mcp_server_mapping:  # Map MCP server names to repository names
+      neotoma: "neotoma"
+      asana: "asana"
+      gmail: "gmail"
+      google_calendar: "google-calendar"
+      google-calendar: "google-calendar"
+    wait_mode:
+      default_timeout: 300  # Default timeout in seconds (5 minutes)
+      default_poll_interval: 5  # Default poll interval in seconds
+      max_timeout: 3600  # Maximum allowed timeout (1 hour)
+      min_poll_interval: 1  # Minimum allowed poll interval
+```
+
+## Error Detection Patterns
+
+Auto-detect errors matching these patterns:
+- MCP error responses: `MCP error -32603`, `UNKNOWN_CAPABILITY`, etc.
+- Build errors: TypeScript compilation failures, `tsc` errors
+- Module resolution: `Cannot find module`, `Module not found`
+- Runtime exceptions: Stack traces with `Error:`, `Exception:`
+- Test failures: `Test failed`, `AssertionError`
+
+## Implementation Checklist
+
+When reporting an error:
+- [ ] Parse target-repo-name parameter (if provided)
+- [ ] If target-repo-name not provided: Auto-detect target repository from error origin
+  - [ ] Check for MCP error patterns (`MCP error`, `mcp_` prefix)
+  - [ ] Extract MCP server name from error message/stack trace
+  - [ ] Check agent context for MCP command names
+  - [ ] Check affected files for repository paths
+  - [ ] Map detected source to sibling repository
+  - [ ] Fallback to current repo if auto-detection fails
+- [ ] Sanitize repo name (validate pattern)
+- [ ] Resolve target repository path (parent_dir + repo_name or auto-detected)
+- [ ] Validate target repository (exists, is git repo, writable)
+- [ ] Extract error message and stack trace
+- [ ] Classify error category
+- [ ] Assign severity level
+- [ ] Sanitize sensitive data
+- [ ] Collect repository metadata (source and target)
+- [ ] Generate unique error ID
+- [ ] Create target repo directory structure if missing
+- [ ] Create JSON report file in target repo (pending/ subdirectory)
+- [ ] Create Markdown summary file in target repo (pending/ subdirectory)
+- [ ] Update pending queue in target repo
+- [ ] Output summary to user with target repo path (indicate if auto-detected)
+- [ ] If wait mode enabled (default): Monitor error status until resolved or timeout
+
+## Example Error Report Files
+
+### JSON Report (`error_20250131_143022_build.json`)
+
+**Example: Local Reporting**
+```json
+{
+  "error_id": "01JQZ8X9K2M3N4P5Q6R7S8T9U0",
+  "timestamp": "2025-01-31T14:30:22Z",
+  "category": "build",
+  "severity": "high",
+  "error_message": "Cannot find module '../db'",
+  "stack_trace": "Error: Cannot find module '../db'\n  at Object.<anonymous> (src/services/raw_storage.ts:1:1)\n  at Module._compile (node:internal/modules/cjs/loader:1376:14)\n  ...",
+  "affected_files": [
+    "src/services/raw_storage.ts",
+    "src/services/interpretation.ts",
+    "src/services/entity_queries.ts"
+  ],
+  "affected_modules": ["db"],
+  "agent_context": {
+    "agent_id": "cursor-agent",
+    "task": "Transfer contacts from Parquet to Neotoma",
+    "command": null
+  },
+  "repositories": {
+    "source_repo": {
+      "path": "/Users/user/Projects/neotoma",
+      "name": "neotoma",
+      "remote_url": "git@github.com:user/neotoma.git"
+    },
+    "target_repo": {
+      "path": "/Users/user/Projects/neotoma",
+      "name": "neotoma",
+      "remote_url": "git@github.com:user/neotoma.git"
+    }
+  },
+  "environment": {
+    "node_version": "v20.11.0",
+    "os": "darwin",
+    "neotoma_env": "development"
+  },
+  "resolution_status": "pending",
+  "resolution_notes": ""
+}
+```
+
+**Example: Cross-Repo Reporting**
+```json
+{
+  "error_id": "01JQZ8X9K2M3N4P5Q6R7S8T9U1",
+  "timestamp": "2025-01-31T14:35:10Z",
+  "category": "runtime",
+  "severity": "high",
+  "error_message": "MCP error -32603: Failed to upload to storage: Bucket not found",
+  "stack_trace": "...",
+  "affected_files": ["src/actions.ts"],
+  "affected_modules": ["mcp_neotoma"],
+  "agent_context": {
+    "agent_id": "cursor-agent",
+    "task": "Ingest structured contact data",
+    "command": "ingest_structured"
+  },
+  "repositories": {
+    "source_repo": {
+      "path": "/Users/user/Projects/personal-project",
+      "name": "personal-project",
+      "remote_url": "git@github.com:user/personal-project.git"
+    },
+    "target_repo": {
+      "path": "/Users/user/Projects/neotoma",
+      "name": "neotoma",
+      "remote_url": "git@github.com:user/neotoma.git"
+    }
+  },
+  "environment": {
+    "node_version": "v20.11.0",
+    "os": "darwin",
+    "neotoma_env": "development"
+  },
+  "resolution_status": "pending",
+  "resolution_notes": ""
+}
+```
+
+### Markdown Summary (`error_20250131_143022_build.md`)
+
+**Example: Cross-Repo Reporting**
+```markdown
+# Error Report: Runtime Error
+
+**Error ID:** `01JQZ8X9K2M3N4P5Q6R7S8T9U1`  
+**Timestamp:** 2025-01-31T14:35:10Z  
+**Category:** runtime  
+**Severity:** high  
+**Status:** pending
+
+## Error Message
+
+MCP error -32603: Failed to upload to storage: Bucket not found
+
+## Source Repository
+
+- **Name:** personal-project
+- **Path:** /Users/user/Projects/personal-project
+- **Remote:** git@github.com:user/personal-project.git
+
+## Target Repository
+
+- **Name:** neotoma
+- **Path:** /Users/user/Projects/neotoma
+- **Remote:** git@github.com:user/neotoma.git
+
+## Affected Files
+
+- `src/actions.ts`
+
+## Affected Modules
+
+- mcp_neotoma
+
+## Stack Trace
+
+```
+...
+```
+
+## Context
+
+Agent was ingesting structured contact data when this runtime error occurred.
+
+## Environment
+
+- Node: v20.11.0
+- OS: darwin
+- Environment: development
+
+## Resolution
+
+Awaiting resolution by Cursor Cloud Agent.
+```
+
+## Best Practices
+
+1. **Always sanitize**: Remove PII and sensitive data before storing
+2. **Be specific**: Include relevant context about the task being performed
+3. **Truncate wisely**: Keep stack traces informative but not excessive
+4. **Update status**: Mark errors as resolved when fixed
+5. **Archive old errors**: Move resolved errors to archive directory
+6. **Review patterns**: Periodically analyze error reports for trends
+7. **Use cross-repo reporting**: Report errors to appropriate repo (e.g., foundation errors to neotoma)
+8. **Validate target repo**: Always validate target exists and is writable before attempting to write
+
+## Testing Scenarios
+
+### Test 1: Auto-Detection with MCP Error
+```bash
+/report_error
+```
+Error: "MCP error -32603: Failed to create interpretation run"
+Expected: 
+- Auto-detects target as `neotoma` (from `mcp_neotoma` in error context)
+- Error report written to `../neotoma/.cursor/error_reports/pending/`
+- Wait mode enabled by default
+
+### Test 2: Explicit Target Repo (Overrides Auto-Detection)
+```bash
+/report_error neotoma
+```
+Expected: 
+- Auto-detection skipped (explicit target provided)
+- Error report written to `../neotoma/.cursor/error_reports/pending/`
+- Wait mode enabled by default
+
+### Test 3: Non-Existent Sibling Repo
+```bash
+/report_error non-existent-repo
+```
+Expected: Error message: "Target repository not found: /Users/user/Projects/non-existent-repo"
+
+### Test 4: Invalid Repo Name (Path Traversal)
+```bash
+/report_error ../other-dir
+```
+Expected: Error message: "Invalid repo name: ../other-dir. Only alphanumeric, hyphens, underscores, and dots allowed."
+
+### Test 5: Valid Name but Not Git Repo
+```bash
+/report_error some-directory
+```
+Expected: Error message: "Target path is not a git repository: /Users/user/Projects/some-directory"
+
+### Test 6: Cross-Repo with Directory Creation
+```bash
+/report_error neotoma
+```
+(Where neotoma repo exists but `.cursor/error_reports/pending/` doesn't exist yet)
+Expected: Directories created automatically, error report written successfully
+
+## Wait-for-Resolution Mode
+
+**Wait mode is enabled by default.** The agent will automatically monitor the error report status and wait for resolution before continuing, unless `--no-wait` is specified.
+
+### Workflow with Wait Mode (Default)
+
+1. **Report Error:**
+   - Agent executes `/report_error` (wait mode enabled by default)
+   - Error report created with `resolution_status: "pending"`
+   - Error ID returned to agent
+   - Auto-detection determines target repository if not specified
+
+2. **Monitor Resolution:**
+   - Agent polls error report file for status changes
+   - **Important**: Check both `pending/` and `resolved/` directories, as resolved errors are moved from `pending/` to `resolved/` by the Cursor Cloud Agent
+   - Checks `resolution_status` field in JSON report
+   - Status values: `pending` → `in_progress` → `resolved` | `failed`
+
+3. **Resolution Detection:**
+   - **Resolved:** Status changes to `"resolved"`
+     - Agent can resume/retry the operation that failed
+     - Check `resolution_notes` for details about the fix
+   - **Failed:** Status changes to `"failed"`
+     - Agent should handle failure case (log, skip, or escalate)
+     - Check `resolution_notes` for failure reason
+
+4. **Timeout Handling:**
+   - If timeout reached while status is still `pending` or `in_progress`:
+     - Agent logs warning and continues (assumes resolution in progress)
+     - Agent can check status later or proceed without waiting
+
+5. **Resume/Retry Logic:**
+   - After resolution, agent can:
+     - **Resume:** Continue from where error occurred
+     - **Retry:** Re-execute the operation that failed
+     - **Skip:** If error indicates operation should be skipped
+
+### Configuration
+
+Wait mode settings are read from `foundation-config.yaml`:
+- `error_reporting.wait_mode.default_timeout` - Default timeout (overridden by `--timeout`)
+- `error_reporting.wait_mode.default_poll_interval` - Default poll interval (overridden by `--poll-interval`)
+- `error_reporting.wait_mode.max_timeout` - Maximum allowed timeout
+- `error_reporting.wait_mode.min_poll_interval` - Minimum allowed poll interval
+
+### Auto-Detection Implementation
+
+```javascript
+function autoDetectTargetRepo(error, currentRepoPath) {
+  const parentDir = path.dirname(currentRepoPath);
+  
+  // 1. Check for MCP errors
+  if (error.message && error.message.includes('MCP error')) {
+    // Extract MCP server name from error context
+    const mcpMatch = error.message.match(/mcp_(\w+)/i) || 
+                     error.stack?.match(/mcp_(\w+)/i);
+    if (mcpMatch) {
+      const serverName = mcpMatch[1];
+      // Map common MCP servers to repos
+      const repoMap = {
+        'neotoma': 'neotoma',
+        'asana': 'asana',
+        'gmail': 'gmail',
+        'google-calendar': 'google-calendar',
+        'google_calendar': 'google-calendar'
+      };
+      const targetRepo = repoMap[serverName] || serverName;
+      const targetPath = path.join(parentDir, targetRepo);
+      if (fs.existsSync(targetPath) && fs.existsSync(path.join(targetPath, '.git'))) {
+        return targetPath;
+      }
+    }
+  }
+  
+  // 2. Check agent context for MCP commands
+  if (error.agent_context?.command) {
+    const cmd = error.agent_context.command;
+    if (cmd.startsWith('mcp_')) {
+      const serverName = cmd.split('_')[1];
+      const targetPath = path.join(parentDir, serverName);
+      if (fs.existsSync(targetPath) && fs.existsSync(path.join(targetPath, '.git'))) {
+        return targetPath;
+      }
+    }
+  }
+  
+  // 3. Check affected files/modules for repo paths
+  if (error.affected_files) {
+    for (const file of error.affected_files) {
+      const repoMatch = file.match(/\/Projects\/([^\/]+)\//);
+      if (repoMatch) {
+        const repoName = repoMatch[1];
+        const targetPath = path.join(parentDir, repoName);
+        if (fs.existsSync(targetPath) && fs.existsSync(path.join(targetPath, '.git'))) {
+          return targetPath;
+        }
+      }
+    }
+  }
+  
+  // 4. Fallback to current repo
+  return currentRepoPath;
+}
+```
+
+### Implementation Example
+
+```javascript
+// Agent workflow (wait mode enabled by default)
+try {
+  await performOperation();
+} catch (error) {
+  // Report error with auto-detection and wait for resolution (default)
+  const result = await reportError('--timeout', '600');
+  
+  if (result.resolved) {
+    // Retry operation after resolution
+    console.log(`Retrying operation after error resolution: ${result.errorId}`);
+    await performOperation(); // Retry
+  } else if (result.failed) {
+    // Handle failure case
+    console.log(`Error resolution failed: ${result.resolutionNotes}`);
+    throw new Error(`Operation failed and could not be resolved: ${result.errorId}`);
+  } else if (result.timeout) {
+    // Timeout - proceed or skip
+    console.log(`Timeout waiting for resolution, skipping operation`);
+    // Agent decides whether to skip or continue
+  }
+}
+```
+
+### Status Monitoring
+
+The agent polls the error report JSON file for status changes. **Important**: When errors are resolved, the Cursor Cloud Agent moves the report files from `pending/` to `resolved/`. The wait logic must check both directories.
+
+```javascript
+async function waitForErrorResolution(errorId, errorReportPath, options = {}) {
+  const {
+    timeout = 300, // 5 minutes default
+    pollInterval = 5, // 5 seconds default
+  } = options;
+
+  const startTime = Date.now();
+  const timeoutMs = timeout * 1000;
+
+  // Normalize error report path - extract base filename
+  let baseFilename = path.basename(errorReportPath);
+  if (!baseFilename.endsWith('.json')) {
+    baseFilename = `${baseFilename}.json`;
+  }
+
+  // Get directory structure
+  const errorReportsDir = path.dirname(path.dirname(errorReportPath)); // Go up from pending/ or resolved/
+  const pendingDir = path.join(errorReportsDir, 'pending');
+  const resolvedDir = path.join(errorReportsDir, 'resolved');
+
+  // Start with pending path
+  let currentPath = path.join(pendingDir, baseFilename);
+
+  while (true) {
+    // Check timeout
+    if (Date.now() - startTime > timeoutMs) {
+      throw new Error(`Timeout waiting for error resolution: ${errorId}`);
+    }
+
+    // Check if file exists in pending/ or resolved/
+    let reportPath = null;
+    if (fs.existsSync(path.join(pendingDir, baseFilename))) {
+      reportPath = path.join(pendingDir, baseFilename);
+    } else if (fs.existsSync(path.join(resolvedDir, baseFilename))) {
+      reportPath = path.join(resolvedDir, baseFilename);
+    } else {
+      // File not found in either location - might have been deleted or moved
+      throw new Error(`Error report file not found: ${baseFilename}`);
+    }
+
+    // Read error report
+    const report = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
+    const status = report.resolution_status;
+
+    // Check if resolved or failed
+    if (status === 'resolved') {
+      return {
+        status: 'resolved',
+        errorId,
+        resolutionNotes: report.resolution_notes || '',
+        report,
+        reportPath // Return actual path (may be in resolved/)
+      };
+    }
+
+    if (status === 'failed') {
+      return {
+        status: 'failed',
+        errorId,
+        resolutionNotes: report.resolution_notes || '',
+        report,
+        reportPath // Return actual path (may be in resolved/)
+      };
+    }
+
+    // Still pending or in_progress, wait and check again
+    console.log(`[WAIT] Error ${errorId} status: ${status}, waiting...`);
+    await new Promise(resolve => setTimeout(resolve, pollInterval * 1000));
+  }
+}
+```
+
+### Shell Script Example
+
+For shell-based implementations, check both directories:
+
+```bash
+ERROR_REPORT_PATH="/path/to/target/.cursor/error_reports/pending/error_TIMESTAMP_runtime.json"
+ERROR_REPORTS_DIR="/path/to/target/.cursor/error_reports"
+PENDING_DIR="$ERROR_REPORTS_DIR/pending"
+RESOLVED_DIR="$ERROR_REPORTS_DIR/resolved"
+BASE_FILENAME=$(basename "$ERROR_REPORT_PATH")
+
+TIMEOUT=300
+POLL_INTERVAL=5
+START_TIME=$(date +%s)
+
+while true; do
+  CURRENT_TIME=$(date +%s)
+  ELAPSED=$((CURRENT_TIME - START_TIME))
+  
+  # Check timeout
+  if [ $ELAPSED -ge $TIMEOUT ]; then
+    echo "⏱️  Timeout reached (${TIMEOUT}s) while waiting for resolution"
+    # Check final status in either directory
+    if [ -f "$RESOLVED_DIR/$BASE_FILENAME" ]; then
+      STATUS=$(cat "$RESOLVED_DIR/$BASE_FILENAME" | jq -r '.resolution_status' || echo "unknown")
+    elif [ -f "$PENDING_DIR/$BASE_FILENAME" ]; then
+      STATUS=$(cat "$PENDING_DIR/$BASE_FILENAME" | jq -r '.resolution_status' || echo "unknown")
+    else
+      STATUS="unknown"
+    fi
+    echo "Final status: $STATUS"
+    exit 0
+  fi
+  
+  # Check both pending/ and resolved/ directories
+  REPORT_PATH=""
+  if [ -f "$PENDING_DIR/$BASE_FILENAME" ]; then
+    REPORT_PATH="$PENDING_DIR/$BASE_FILENAME"
+  elif [ -f "$RESOLVED_DIR/$BASE_FILENAME" ]; then
+    REPORT_PATH="$RESOLVED_DIR/$BASE_FILENAME"
+  else
+    echo "⚠️  Error report file not found in pending/ or resolved/: $BASE_FILENAME"
+    exit 1
+  fi
+  
+  # Read status
+  STATUS=$(cat "$REPORT_PATH" | jq -r '.resolution_status' 2>/dev/null || echo "pending")
+  echo "[WAIT] Error status: $STATUS (elapsed: ${ELAPSED}s)"
+  
+  # Check if resolved or failed
+  if [ "$STATUS" = "resolved" ]; then
+    echo "✅ Error resolved!"
+    cat "$REPORT_PATH" | jq -r '.resolution_notes // "No resolution notes provided."'
+    exit 0
+  fi
+  
+  if [ "$STATUS" = "failed" ]; then
+    echo "❌ Error resolution failed"
+    cat "$REPORT_PATH" | jq -r '.resolution_notes // "No failure reason provided."'
+    exit 1
+  fi
+  
+  # Still pending or in_progress, wait and check again
+  sleep $POLL_INTERVAL
+done
+```
+
+## Helper Scripts
+
+The following scripts are provided in `foundation/scripts/` to simplify error reporting implementation. These can be used by agents when implementing the `/report_error` command.
+
+**Script Location:** `foundation/scripts/report_error_*.sh`
+
+**Usage:** Scripts can be called directly from the foundation submodule, or copied/referenced as needed.
+
+### Script: Validate Target Repository
+
+**File:** `foundation/scripts/report_error_validate_target.sh`
+
+```bash
+#!/bin/bash
+# validate_target_repo.sh
+# Usage: validate_target_repo.sh <target-repo-path>
+
+TARGET_REPO="$1"
+
+if [ -z "$TARGET_REPO" ]; then
+  echo "❌ Error: Target repository path required"
+  exit 1
+fi
+
+# Check if path exists
+if [ ! -d "$TARGET_REPO" ]; then
+  echo "❌ Error: Target repository not found: $TARGET_REPO"
+  exit 1
+fi
+
+# Check if it's a git repository
+if [ ! -d "$TARGET_REPO/.git" ]; then
+  echo "❌ Error: Target path is not a git repository: $TARGET_REPO"
+  exit 1
+fi
+
+# Check write permissions
+if [ ! -w "$TARGET_REPO" ]; then
+  echo "❌ Error: No write permission for target repository: $TARGET_REPO"
+  exit 1
+fi
+
+echo "✅ Target repository validated: $TARGET_REPO"
+exit 0
+```
+
+### Script: Generate Error ID and Timestamp
+
+**File:** `foundation/scripts/report_error_generate_id.sh`
+
+```bash
+#!/bin/bash
+# generate_error_id.sh
+# Outputs: ERROR_ID|TIMESTAMP
+
+TIMESTAMP=$(date -u +"%Y%m%dT%H%M%S")
+ERROR_ID="01JQ$(echo $TIMESTAMP | tr -d 'T' | cut -c1-20)"
+echo "${ERROR_ID}|${TIMESTAMP}"
+```
+
+### Script: Create Error Report Directories
+
+**File:** `foundation/scripts/report_error_create_dirs.sh`
+
+```bash
+#!/bin/bash
+# create_error_report_dirs.sh
+# Usage: create_error_report_dirs.sh <target-repo-path>
+
+TARGET_REPO="$1"
+ERROR_REPORTS_DIR="$TARGET_REPO/.cursor/error_reports"
+PENDING_DIR="$ERROR_REPORTS_DIR/pending"
+RESOLVED_DIR="$ERROR_REPORTS_DIR/resolved"
+
+mkdir -p "$PENDING_DIR" "$RESOLVED_DIR"
+echo "✅ Created error report directories in $TARGET_REPO"
+```
+
+### Script: Create Error Report Files
+
+```bash
+#!/bin/bash
+# create_error_report.sh
+# Usage: create_error_report.sh <target-repo-path> <error-id> <timestamp> <category> <severity> <error-message> <json-data>
+
+TARGET_REPO="$1"
+ERROR_ID="$2"
+TIMESTAMP="$3"
+CATEGORY="$4"
+SEVERITY="$5"
+ERROR_MSG="$6"
+JSON_DATA="$7"
+
+ERROR_REPORTS_DIR="$TARGET_REPO/.cursor/error_reports"
+PENDING_DIR="$ERROR_REPORTS_DIR/pending"
+
+# Generate filenames
+JSON_FILENAME="error_${TIMESTAMP}_${CATEGORY}.json"
+MD_FILENAME="error_${TIMESTAMP}_${CATEGORY}.md"
+JSON_PATH="$PENDING_DIR/$JSON_FILENAME"
+MD_PATH="$PENDING_DIR/$MD_FILENAME"
+
+# Write JSON report
+echo "$JSON_DATA" > "$JSON_PATH"
+
+# Generate Markdown summary
+cat > "$MD_PATH" << EOF
+# Error Report: $(echo $CATEGORY | tr '[:lower:]' '[:upper:]') Error
+
+**Error ID:** \`$ERROR_ID\`  
+**Timestamp:** $(echo $TIMESTAMP | sed 's/\(....\)\(..\)\(..\)T\(..\)\(..\)\(..\)/\1-\2-\3T\4:\5:\6Z/')  
+**Category:** $CATEGORY  
+**Severity:** $SEVERITY  
+**Status:** pending
+
+## Error Message
+
+$ERROR_MSG
+
+## Resolution
+
+Awaiting resolution by Cursor Cloud Agent.
+EOF
+
+echo "$JSON_PATH|$MD_PATH"
+```
+
+### Script: Update Pending Queue
+
+```bash
+#!/bin/bash
+# update_pending_queue.sh
+# Usage: update_pending_queue.sh <target-repo-path> <error-id> <timestamp> <category> <severity> <json-path>
+
+TARGET_REPO="$1"
+ERROR_ID="$2"
+TIMESTAMP="$3"
+CATEGORY="$4"
+SEVERITY="$5"
+JSON_PATH="$6"
+
+PENDING_FILE="$TARGET_REPO/.cursor/error_reports/pending.json"
+NEW_ENTRY="{\"error_id\": \"$ERROR_ID\", \"timestamp\": \"$(echo $TIMESTAMP | sed 's/\(....\)\(..\)\(..\)T\(..\)\(..\)\(..\)/\1-\2-\3T\4:\5:\6Z/')\", \"category\": \"$CATEGORY\", \"severity\": \"$SEVERITY\", \"file_path\": \"$JSON_PATH\"}"
+
+if [ -f "$PENDING_FILE" ]; then
+  cat "$PENDING_FILE" | jq ". + [$NEW_ENTRY]" > "$PENDING_FILE.tmp" && mv "$PENDING_FILE.tmp" "$PENDING_FILE"
+else
+  echo "[$NEW_ENTRY]" > "$PENDING_FILE"
+fi
+
+echo "✅ Pending queue updated"
+```
+
+### Script: Wait for Error Resolution
+
+**File:** `foundation/scripts/report_error_wait_resolution.sh`
+
+```bash
+#!/bin/bash
+# wait_for_resolution.sh
+# Usage: wait_for_resolution.sh <target-repo-path> <base-filename> [timeout] [poll-interval]
+
+TARGET_REPO="$1"
+BASE_FILENAME="$2"
+TIMEOUT="${3:-300}"
+POLL_INTERVAL="${4:-5}"
+
+ERROR_REPORTS_DIR="$TARGET_REPO/.cursor/error_reports"
+PENDING_DIR="$ERROR_REPORTS_DIR/pending"
+RESOLVED_DIR="$ERROR_REPORTS_DIR/resolved"
+
+START_TIME=$(date +%s)
+
+while true; do
+  CURRENT_TIME=$(date +%s)
+  ELAPSED=$((CURRENT_TIME - START_TIME))
+  
+  # Check timeout
+  if [ $ELAPSED -ge $TIMEOUT ]; then
+    echo "⏱️  Timeout reached (${TIMEOUT}s) while waiting for resolution"
+    # Check final status in either directory
+    if [ -f "$RESOLVED_DIR/$BASE_FILENAME" ]; then
+      STATUS=$(cat "$RESOLVED_DIR/$BASE_FILENAME" | jq -r '.resolution_status' || echo "unknown")
+    elif [ -f "$PENDING_DIR/$BASE_FILENAME" ]; then
+      STATUS=$(cat "$PENDING_DIR/$BASE_FILENAME" | jq -r '.resolution_status' || echo "unknown")
+    else
+      STATUS="unknown"
+    fi
+    echo "Final status: $STATUS"
+    exit 0
+  fi
+  
+  # Check both pending/ and resolved/ directories
+  REPORT_PATH=""
+  if [ -f "$PENDING_DIR/$BASE_FILENAME" ]; then
+    REPORT_PATH="$PENDING_DIR/$BASE_FILENAME"
+  elif [ -f "$RESOLVED_DIR/$BASE_FILENAME" ]; then
+    REPORT_PATH="$RESOLVED_DIR/$BASE_FILENAME"
+  else
+    echo "⚠️  Error report file not found in pending/ or resolved/: $BASE_FILENAME"
+    exit 1
+  fi
+  
+  # Read status
+  STATUS=$(cat "$REPORT_PATH" | jq -r '.resolution_status' 2>/dev/null || echo "pending")
+  echo "[WAIT] Error status: $STATUS (elapsed: ${ELAPSED}s)"
+  
+  # Check if resolved or failed
+  if [ "$STATUS" = "resolved" ]; then
+    echo "✅ Error resolved!"
+    cat "$REPORT_PATH" | jq -r '.resolution_notes // "No resolution notes provided."'
+    exit 0
+  fi
+  
+  if [ "$STATUS" = "failed" ]; then
+    echo "❌ Error resolution failed"
+    cat "$REPORT_PATH" | jq -r '.resolution_notes // "No failure reason provided."'
+    exit 1
+  fi
+  
+  # Still pending or in_progress, wait and check again
+  sleep $POLL_INTERVAL
+done
+```
+
+### Complete Workflow Script
+
+```bash
+#!/bin/bash
+# report_error_workflow.sh
+# Complete workflow for reporting an error
+# Usage: report_error_workflow.sh <target-repo-name> <error-message> <category> <severity> [--no-wait] [--timeout SECONDS]
+
+set -e
+
+# Parse arguments
+TARGET_REPO_NAME="$1"
+ERROR_MSG="$2"
+CATEGORY="$3"
+SEVERITY="$4"
+NO_WAIT=false
+TIMEOUT=300
+
+shift 4
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --no-wait)
+      NO_WAIT=true
+      shift
+      ;;
+    --timeout)
+      TIMEOUT="$2"
+      shift 2
+      ;;
+    *)
+      shift
+      ;;
+  esac
+done
+
+# Get current repo path
+CURRENT_REPO=$(git rev-parse --show-toplevel)
+PARENT_DIR=$(dirname "$CURRENT_REPO")
+
+# Resolve target repo
+if [ -n "$TARGET_REPO_NAME" ]; then
+  TARGET_REPO="$PARENT_DIR/$TARGET_REPO_NAME"
+else
+  # Auto-detect (simplified - would need full MCP detection logic)
+  TARGET_REPO="$CURRENT_REPO"
+fi
+
+# Validate target repo
+if [ ! -d "$TARGET_REPO" ] || [ ! -d "$TARGET_REPO/.git" ]; then
+  echo "❌ Error: Invalid target repository: $TARGET_REPO"
+  exit 1
+fi
+
+# Generate error ID and timestamp
+ID_TIMESTAMP=$(TIMESTAMP=$(date -u +"%Y%m%dT%H%M%S") && ERROR_ID="01JQ$(echo $TIMESTAMP | tr -d 'T' | cut -c1-20)" && echo "${ERROR_ID}|${TIMESTAMP}")
+ERROR_ID=$(echo "$ID_TIMESTAMP" | cut -d'|' -f1)
+TIMESTAMP=$(echo "$ID_TIMESTAMP" | cut -d'|' -f2)
+
+# Create directories
+mkdir -p "$TARGET_REPO/.cursor/error_reports/pending" "$TARGET_REPO/.cursor/error_reports/resolved"
+
+# Create error report (simplified - would need full JSON structure)
+JSON_FILENAME="error_${TIMESTAMP}_${CATEGORY}.json"
+JSON_PATH="$TARGET_REPO/.cursor/error_reports/pending/$JSON_FILENAME"
+
+# Generate JSON report (simplified structure)
+cat > "$JSON_PATH" << EOF
+{
+  "error_id": "$ERROR_ID",
+  "timestamp": "$(echo $TIMESTAMP | sed 's/\(....\)\(..\)\(..\)T\(..\)\(..\)\(..\)/\1-\2-\3T\4:\5:\6Z/')",
+  "category": "$CATEGORY",
+  "severity": "$SEVERITY",
+  "error_message": "$(echo "$ERROR_MSG" | jq -Rs .)",
+  "resolution_status": "pending",
+  "resolution_notes": ""
+}
+EOF
+
+# Update pending queue
+PENDING_FILE="$TARGET_REPO/.cursor/error_reports/pending.json"
+NEW_ENTRY="{\"error_id\": \"$ERROR_ID\", \"timestamp\": \"$(echo $TIMESTAMP | sed 's/\(....\)\(..\)\(..\)T\(..\)\(..\)\(..\)/\1-\2-\3T\4:\5:\6Z/')\", \"category\": \"$CATEGORY\", \"severity\": \"$SEVERITY\", \"file_path\": \"$JSON_PATH\"}"
+if [ -f "$PENDING_FILE" ]; then
+  cat "$PENDING_FILE" | jq ". + [$NEW_ENTRY]" > "$PENDING_FILE.tmp" && mv "$PENDING_FILE.tmp" "$PENDING_FILE"
+else
+  echo "[$NEW_ENTRY]" > "$PENDING_FILE"
+fi
+
+echo "Error report created successfully."
+echo "Error ID: $ERROR_ID"
+echo "Category: $CATEGORY"
+echo "Severity: $SEVERITY"
+echo "Target: $TARGET_REPO"
+echo "Report saved to: $JSON_PATH"
+
+# Wait for resolution if enabled
+if [ "$NO_WAIT" = false ]; then
+  echo ""
+  echo "⏳ Waiting for resolution (timeout: ${TIMEOUT}s)..."
+  BASE_FILENAME=$(basename "$JSON_PATH")
+  "$(dirname "$0")/wait_for_resolution.sh" "$TARGET_REPO" "$BASE_FILENAME" "$TIMEOUT"
+fi
+```
+
+### Usage in Agent Implementation
+
+Agents can use these scripts as building blocks. Scripts are located in `foundation/scripts/`:
+
+```bash
+# Example: Report error using helper scripts
+FOUNDATION_DIR="foundation"  # or path to foundation submodule
+TARGET_REPO_NAME="neotoma"
+CURRENT_REPO=$(git rev-parse --show-toplevel)
+PARENT_DIR=$(dirname "$CURRENT_REPO")
+TARGET_REPO="$PARENT_DIR/$TARGET_REPO_NAME"
+
+# Validate target repository
+"$FOUNDATION_DIR/scripts/report_error_validate_target.sh" "$TARGET_REPO"
+
+# Generate error ID and timestamp
+ID_TIMESTAMP=$("$FOUNDATION_DIR/scripts/report_error_generate_id.sh")
+ERROR_ID=$(echo "$ID_TIMESTAMP" | cut -d'|' -f1)
+TIMESTAMP=$(echo "$ID_TIMESTAMP" | cut -d'|' -f2)
+
+# Create directories
+"$FOUNDATION_DIR/scripts/report_error_create_dirs.sh" "$TARGET_REPO"
+
+# ... create error report files (JSON and Markdown) ...
+# ... update pending queue ...
+
+# Wait for resolution (if wait mode enabled)
+BASE_FILENAME="error_${TIMESTAMP}_runtime.json"
+"$FOUNDATION_DIR/scripts/report_error_wait_resolution.sh" "$TARGET_REPO" "$BASE_FILENAME" 300 5
+```
+
+**Note:** If `foundation` is a submodule, use the relative path from the repository root. If scripts are symlinked or copied, adjust paths accordingly.
+
+## Related Documentation
+
+- Skill `fix-feature-bug` (`.cursor/skills/fix-feature-bug/SKILL.md`) - Bug fix workflow
+- Skill `analyze` (`.cursor/skills/analyze/SKILL.md`) - Analysis workflow
+- Skill `debug` (`.cursor/skills/debug/SKILL.md`) - Debug workflow
+- `foundation-config.yaml` - Configuration file (in repository root)
+
diff --git a/.claude/skills/report/SKILL.md b/.claude/skills/report/SKILL.md
index a17a2d736..6732a21de 100644
--- a/.claude/skills/report/SKILL.md
+++ b/.claude/skills/report/SKILL.md
@@ -1,3 +1,10 @@
+---
+name: report
+description: Report Error Command
+---
+
+<!-- Source: foundation/.cursor/skills/report/SKILL.md -->
+
 ---
 name: report
 description: Generate report per foundation report command.
diff --git a/.claude/skills/report_error/SKILL.md b/.claude/skills/report_error/SKILL.md
index 72c69b5ff..3fc231c85 100644
--- a/.claude/skills/report_error/SKILL.md
+++ b/.claude/skills/report_error/SKILL.md
@@ -1,12 +1,11 @@
 ---
-name: report-error
-description: Report error per foundation command.
-triggers:
-  - report error
-  - /report_error
-  - report-error
+name: report_error
+description: Report Error Command
 ---
 
+<!-- Source: .cursor/skills/report-error/SKILL.md -->
+
+
 # Report Error Command
 
 ## Purpose
diff --git a/.claude/skills/run-feature-workflow/SKILL.md b/.claude/skills/run-feature-workflow/SKILL.md
new file mode 100644
index 000000000..80693ba80
--- /dev/null
+++ b/.claude/skills/run-feature-workflow/SKILL.md
@@ -0,0 +1,86 @@
+---
+name: run-feature-workflow
+description: Run Feature Workflow
+---
+
+<!-- Source: foundation/.cursor/skills/run-feature-workflow/SKILL.md -->
+
+---
+name: run-feature-workflow
+description: Run feature workflow per foundation command.
+triggers:
+  - run feature workflow
+  - /run_feature_workflow
+  - run-feature-workflow
+---
+
+# Run Feature Workflow
+
+feature_id = {{input:feature_id}}
+
+Configuration is read from `foundation-config.yaml`.
+
+1. **Load configuration:**
+   - Read `foundation-config.yaml` to get feature unit settings
+   - Determine directory structure, manifest complexity, testing requirements
+
+2. **Read authoritative documents:**
+   - `foundation/development/feature_unit_workflow.md` (workflow context)
+   - `{configured_directory}/in_progress/{{input:feature_id}}/{{input:feature_id}}_spec.md` (or `completed/` if completed)
+   - `{configured_directory}/in_progress/{{input:feature_id}}/manifest.yaml` (or `completed/` if completed)
+   - `foundation/development/templates/feature_unit_spec_template.md`
+   - Repository-specific execution instructions (if they exist)
+   - Repository-specific architecture/module documentation (based on spec)
+
+3. **Determine risk level:**
+   - low → skip plan
+   - medium → produce brief structured plan
+   - high/critical → produce detailed plan and wait for user approval
+
+4. **Apply Feature Unit execution principles:**
+   - Update spec/manifest if ambiguous
+   - Update code/tests/docs together
+   - Follow architectural invariants (from repo-specific docs)
+   - Preserve accessibility and i18n rules (if applicable)
+
+5. **Run tests (based on configuration):**
+   - Unit tests (if `testing.require_unit_tests: true`)
+   - Integration tests (if `testing.require_integration_tests: true`)
+   - E2E tests (if `testing.require_e2e_tests: true`)
+   - Verify coverage meets configured targets
+   
+   **If any tests fail:**
+   - Immediately invoke `Fix Feature Bug` with feature_id={{input:feature_id}}
+   - Do NOT attempt to fix bugs inline
+   - Let the error protocol classify and correct
+   - After bugfix completes, re-run the test suite
+   - Only proceed to step 6 once all tests pass
+
+6. **Apply error protocol** (if repository has one) only if bugs were encountered and fixed via step 5.
+
+7. **Spec-to-Implementation Diff Checkpoint (CRITICAL):**
+
+   Before producing the final summary:
+   
+   - Compare the implemented code against the spec
+   - List any ways implementation **intentionally diverged** from spec (even if small)
+   - For each divergence:
+     - Either update the spec to reflect the change (if divergence is intentional and correct)
+     - Or mark the divergence as a bug to be fixed (if divergence is unintentional)
+   - Present this diff to the user:
+     - "Implementation vs Spec Diff: [list of divergences]"
+     - "For each divergence, should I update the spec or fix the implementation? (spec/implementation/list)"
+   - Do NOT proceed to final summary until spec and implementation are aligned (either by updating spec or fixing implementation)
+
+8. **Produce a final change summary:**
+   - feature_id
+   - files changed
+   - risk
+   - error_class (if bugfix)
+   - tests run
+   - coverage achieved
+
+## Inputs
+
+- `feature_id` (string): The feature_id to work on.
+
diff --git a/.claude/skills/run_feature_workflow/SKILL.md b/.claude/skills/run_feature_workflow/SKILL.md
index e5e468871..720993c3d 100644
--- a/.claude/skills/run_feature_workflow/SKILL.md
+++ b/.claude/skills/run_feature_workflow/SKILL.md
@@ -1,12 +1,11 @@
 ---
-name: run-feature-workflow
-description: Run feature workflow per foundation command.
-triggers:
-  - run feature workflow
-  - /run_feature_workflow
-  - run-feature-workflow
+name: run_feature_workflow
+description: Run Feature Workflow
 ---
 
+<!-- Source: .cursor/skills/run-feature-workflow/SKILL.md -->
+
+
 # Run Feature Workflow
 
 feature_id = {{input:feature_id}}
diff --git a/.claude/skills/setup-commands/SKILL.md b/.claude/skills/setup-commands/SKILL.md
new file mode 100644
index 000000000..145f7e813
--- /dev/null
+++ b/.claude/skills/setup-commands/SKILL.md
@@ -0,0 +1,35 @@
+---
+name: setup-commands
+description: Setup Commands (Legacy)
+---
+
+<!-- Source: foundation/.cursor/skills/setup-commands/SKILL.md -->
+
+---
+name: setup-commands
+description: Legacy setup for .claude/skills; foundation uses skills instead. Prefer setup-cursor-copies.
+triggers:
+  - setup commands
+  - /setup_commands
+  - setup-commands
+---
+
+# Setup Commands (Legacy)
+
+Foundation workflows have been **replaced by skills**. There is no longer a `foundation/agent_instructions/cursor_commands/` directory; workflows live in `foundation/agent_instructions/cursor_skills/{slug}/SKILL.md`.
+
+## What to do instead
+
+1. **Use setup-cursor-copies** — Run `./foundation/scriptsscripts/setup_claude_instructions.sh.sh` (or the **setup-cursor-copies** skill). It copies foundation rules into `.claude/rules/` and foundation skills into `.cursor/skills/`.
+2. **Load skills by trigger** — When a trigger matches (e.g. commit, pull, push, fix-feature-bug), load the corresponding skill from `.cursor/skills/{slug}/SKILL.md` per the router rule.
+
+## When this skill is invoked
+
+- Tell the user that foundation no longer installs into `.claude/skills/`.
+- Run or direct them to run **setup-cursor-copies** to refresh `.claude/rules/` and `.cursor/skills/`.
+- Repository-specific command files in `docs/*_command.md` (if any) may still be installed by setup into `.claude/skills/` when configured in the manifest; foundation workflows are only in `.cursor/skills/`.
+
+## Related
+
+- **setup-cursor-copies** skill — Copies foundation rules and skills into `.cursor/`.
+- **Foundation skills source:** `foundation/agent_instructions/cursor_skills/`
diff --git a/.claude/skills/setup-cursor-copies/SKILL.md b/.claude/skills/setup-cursor-copies/SKILL.md
new file mode 100644
index 000000000..ff8f3b35c
--- /dev/null
+++ b/.claude/skills/setup-cursor-copies/SKILL.md
@@ -0,0 +1,240 @@
+---
+name: setup-cursor-copies
+description: Setup Foundation Cursor Copies
+---
+
+<!-- Source: foundation/.cursor/skills/setup-cursor-copies/SKILL.md -->
+
+---
+name: setup-cursor-copies
+description: Setup foundation cursor rules and commands in .cursor/ (run setup script).
+triggers:
+  - setup cursor copies
+  - sync cursor files
+  - scripts/setup_claude_instructions.sh
+  - setup-cursor-copies
+---
+
+# Setup Foundation Cursor Copies
+
+Sets up foundation cursor rules and commands in `.cursor/`. **When foundation is a git submodule**, creates **symlinks** (stays in sync with `git submodule update`). Otherwise creates **independent copies**.
+
+## Command
+
+```
+setup_cursor_copies
+```
+
+or
+
+```
+setup cursor copies
+```
+
+## Purpose
+
+This command runs the foundation setup script (`foundation/scriptsscripts/setup_claude_instructions.sh.sh`) which:
+
+1. **If foundation is a git submodule:** Delegates to `setup_cursor_rules.sh` and creates **symlinks** from foundation to `.cursor/` (single source of truth; updates apply with `git submodule update`).
+2. **Otherwise:** Creates **independent copies** of foundation rules/commands in `.cursor/`.
+3. Uses original filenames (no prefix).
+4. Removes existing foundation files before creating new ones.
+5. Preserves any non-foundation files (custom rules/commands).
+
+**When run from the foundation repository itself**, it also automatically runs the setup script in peer repositories (located at `../*`) that include this foundation repo via symlink.
+
+## When to Use
+
+- **Submodule:** Run after `git submodule update` (or any setup); symlinks keep `.cursor/` in sync automatically.
+- **Copy mode (foundation not a submodule):** When you want independent copies, need to customize rules, symlinks are not suitable, or you version-control your own copies. Re-run after foundation updates to refresh.
+
+## Submodule vs copy behavior
+
+**When foundation is a git submodule** (this command delegates to `setup_cursor_rules`):
+- Creates symlinks to foundation (single source of truth)
+- Updates automatically when foundation changes (`git submodule update`)
+- Cannot customize foundation rules without breaking the link
+
+**When foundation is a symlink or copy** (this command uses copy mode):
+- Creates independent file copies
+- Uses original filenames (no prefix)
+- Does NOT update automatically when foundation changes
+- Can be customized per repository
+- Must re-run script to get foundation updates
+
+## Execution Instructions
+
+### Step 1: Verify Foundation Directory
+
+**Check if foundation exists:**
+
+- Look for `foundation/` directory in repo root
+- If not found, check `../foundation/` (parent directory)
+- If still not found, error: "Foundation directory not found. Please ensure foundation is installed."
+
+### Step 2: Run Copy Script in Current Repository
+
+**Execute the script:**
+
+```bash
+./foundation/scriptsscripts/setup_claude_instructions.sh.sh
+```
+
+**Or if foundation is in parent directory:**
+
+```bash
+../foundation/scriptsscripts/setup_claude_instructions.sh.sh
+```
+
+### Step 3: Run Copy Script in Peer Repositories (If in Foundation Repo)
+
+**If running from the foundation repository itself** (detected by presence of `agent_instructions/cursor_skills/` directory):
+
+1. **Get current repository absolute path:**
+   ```bash
+   CURRENT_REPO=$(pwd -P)
+   ```
+
+2. **Find peer repositories in parent directory:**
+   ```bash
+   PARENT_DIR=$(dirname "$CURRENT_REPO")
+   for peer_repo in "$PARENT_DIR"/*; do
+     # Skip if not a directory or if it's the current repo
+     if [ ! -d "$peer_repo" ] || [ "$peer_repo" = "$CURRENT_REPO" ]; then
+       continue
+     fi
+     
+     # Check if peer repo has foundation/ symlink pointing to this repo
+     if [ -L "$peer_repo/foundation" ]; then
+       SYMLINK_TARGET=$(readlink -f "$peer_repo/foundation" 2>/dev/null || readlink "$peer_repo/foundation")
+       if [ "$SYMLINK_TARGET" = "$CURRENT_REPO" ]; then
+         echo "Found peer repo with foundation symlink: $(basename "$peer_repo")"
+         # Run copy script in peer repo using absolute path
+         (cd "$peer_repo" && "$CURRENT_REPO/scriptsscripts/setup_claude_instructions.sh.sh" || echo "Failed to run in $(basename "$peer_repo")")
+       fi
+     fi
+   done
+   ```
+
+**Behavior:**
+- Only runs in peer repos if executing from foundation repo itself
+- Detects peer repos by checking `../*` directories
+- Verifies each peer repo has `foundation/` symlink pointing to current repo
+- Runs copy script in each matching peer repo
+- Continues even if one peer repo fails
+
+**Expected output (when peer repos found):**
+```
+[INFO] ✅ Cursor rules setup complete!
+...
+[INFO] Detected foundation repository - checking for peer repos...
+[INFO] Found peer repo with foundation symlink: my-project
+[INFO] Running copy setup script in my-project...
+[INFO] Foundation is a git submodule; using symlinks (setup_cursor_rules)...  (or copy mode)
+...
+[INFO] ✅ Cursor rules setup complete!
+[INFO] ✓ Successfully updated my-project
+
+[INFO] Updated 1 peer repo(s)
+```
+
+### Step 4: Verify Results
+
+**Check output:**
+
+- **Submodule:** Script reports "Foundation is a git submodule; using symlinks", then rules **linked**. Check `.claude/rules/` for symlinks; `.cursor/skills/` is populated from foundation skills.
+- **Copy mode:** Script reports rules and skills **copied**. Check `.claude/rules/` and `.cursor/skills/` for regular files (not symlinks).
+
+**Expected output (submodule):**
+
+```
+[INFO] Foundation is a git submodule; using symlinks (setup_cursor_rules)...
+[INFO] Setting up cursor rules and commands...
+[INFO] Creating symlinks for generic cursor rules...
+  ✓ Linked security.mdc -> security.mdc
+  ...
+[INFO] ✅ Cursor rules setup complete!
+[INFO]   Foundation rules linked: X
+[INFO]   Foundation commands linked: Y
+```
+
+**Expected output (copy mode):**
+
+```
+[INFO] Setting up cursor rules and commands (copy mode)...
+[INFO] Copying generic cursor rules...
+  ✓ Copied security.mdc
+  ...
+[INFO] ✅ Cursor rules setup complete!
+[INFO]   Rules copied: X
+[INFO]   Commands copied: Y
+```
+
+## What Gets Created
+
+**When foundation is a submodule (symlinks):**
+- `.claude/rules/` contains **symlinks** to `foundation/agent_instructions/cursor_rules/`. `.cursor/skills/` is populated from `foundation/agent_instructions/cursor_skills/` (skills replace legacy commands). Updates to foundation apply when you re-run setup.
+
+**When foundation is not a submodule (copies):**
+- `.claude/rules/` and `.cursor/skills/` contain **independent copies** of foundation rules and skills (e.g. `security.mdc`, `worktree_env.mdc`, and full skill workflows). Re-run to refresh after foundation updates.
+
+**Note:** Repository rules from `docs/` are handled per `setup_cursor_rules` (symlinks when submodule) or copied in copy mode. Source files in `docs/` remain the source of truth.
+
+## Behavior
+
+**Filenames:**
+- Foundation rules/commands use original filenames (no prefix), e.g. `security.mdc` remains `security.mdc`.
+
+**Submodule (symlinks):** Removes existing foundation files (symlinks or copies), then creates symlinks. Repo rules from `docs/` are symlinked; any existing file at the target path (symlink or regular file) is removed and replaced with the symlink to the source.
+
+**Copy mode:** Removes existing foundation files, then creates copies. Repo rules from `docs/` are copied.
+
+**Existing Files:** If a target already exists (symlink or regular file), it is removed and replaced with the symlink (or copy in copy mode). Source in `docs/` or foundation is the single source of truth.
+
+**Existing Foundation Files:** Removed first (prefixed and unprefixed), then new symlinks or copies created. Ensures output matches current foundation.
+
+**Copy mode only:** Files are independent; foundation changes do not apply until you re-run. You can customize copies.
+
+## Error Handling
+
+### Foundation Directory Not Found
+
+**Error:**
+```
+[ERROR] Foundation directory not found. Please run from repository root or ensure foundation is installed.
+```
+
+**Solution:**
+- Ensure you're in repository root
+- Verify foundation is installed (as submodule or symlink)
+- Check if foundation is in parent directory
+
+### Cursor Rules Directory Not Found
+
+**Error:**
+```
+[ERROR] Cursor rules directory not found: foundation/agent_instructions/cursor_rules
+```
+
+**Solution:**
+- Verify foundation submodule is initialized: `git submodule update --init`
+- Check that foundation has cursor rules directory
+
+### Cursor Skills Directory (optional)
+
+Foundation workflows are in `foundation/agent_instructions/cursor_skills/`. If present, setup copies them to `.cursor/skills/`. If the directory is missing, setup still succeeds (rules only).
+
+## Related Documents
+
+- `foundation/scriptsscripts/setup_claude_instructions.sh.sh` - Entry script (delegates to symlink or copy logic)
+- `foundation/scripts/setup_cursor_rules.sh` - Symlink implementation (used when foundation is submodule)
+- `foundation/agent_instructions/README.md` - Cursor rules and commands documentation
+- `foundation/README.md` - Foundation overview and installation
+
+## Notes
+
+- **Submodule → symlinks**: Foundation as git submodule yields symlinks; updates apply with `git submodule update`.
+- **Otherwise → copies**: Symlink or copy foundation yields independent copies; re-run to refresh.
+- **Original filenames**: Foundation rules/commands use original filenames (no prefix).
+- **Repository rules**: From `docs/`; symlinked or copied per mode. Source in `docs/` remains source of truth.
+- **When run from foundation repo**: Propagates to peer repos in `../*` that have `foundation/` symlink to this repo.
diff --git a/.claude/skills/setup_commands/SKILL.md b/.claude/skills/setup_commands/SKILL.md
index dc8ea2ede..5d2f00eed 100644
--- a/.claude/skills/setup_commands/SKILL.md
+++ b/.claude/skills/setup_commands/SKILL.md
@@ -1,26 +1,25 @@
 ---
-name: setup-commands
-description: Legacy setup for .cursor/commands; foundation uses skills instead. Prefer setup-cursor-copies.
-triggers:
-  - setup commands
-  - /setup_commands
-  - setup-commands
+name: setup_commands
+description: Setup Commands (Legacy)
 ---
 
+<!-- Source: .cursor/skills/setup-commands/SKILL.md -->
+
+
 # Setup Commands (Legacy)
 
 Foundation workflows have been **replaced by skills**. There is no longer a `foundation/agent_instructions/cursor_commands/` directory; workflows live in `foundation/agent_instructions/cursor_skills/{slug}/SKILL.md`.
 
 ## What to do instead
 
-1. **Use setup-cursor-copies** — Run `./foundation/scripts/setup_cursor_copies.sh` (or the **setup-cursor-copies** skill). It copies foundation rules into `.cursor/rules/` and foundation skills into `.cursor/skills/`.
+1. **Use setup-cursor-copies** — Run `./foundation/scriptsscripts/setup_claude_instructions.sh.sh` (or the **setup-cursor-copies** skill). It copies foundation rules into `.claude/rules/` and foundation skills into `.cursor/skills/`.
 2. **Load skills by trigger** — When a trigger matches (e.g. commit, pull, push, fix-feature-bug), load the corresponding skill from `.cursor/skills/{slug}/SKILL.md` per the router rule.
 
 ## When this skill is invoked
 
-- Tell the user that foundation no longer installs into `.cursor/commands/`.
-- Run or direct them to run **setup-cursor-copies** to refresh `.cursor/rules/` and `.cursor/skills/`.
-- Repository-specific command files in `docs/*_command.md` (if any) may still be installed by setup into `.cursor/commands/` when configured in the manifest; foundation workflows are only in `.cursor/skills/`.
+- Tell the user that foundation no longer installs into `.claude/skills/`.
+- Run or direct them to run **setup-cursor-copies** to refresh `.claude/rules/` and `.cursor/skills/`.
+- Repository-specific command files in `docs/*_command.md` (if any) may still be installed by setup into `.claude/skills/` when configured in the manifest; foundation workflows are only in `.cursor/skills/`.
 
 ## Related
 
diff --git a/.claude/skills/setup_cursor_copies/SKILL.md b/.claude/skills/setup_cursor_copies/SKILL.md
index 5ebc80ec0..4ec5cfd10 100644
--- a/.claude/skills/setup_cursor_copies/SKILL.md
+++ b/.claude/skills/setup_cursor_copies/SKILL.md
@@ -1,13 +1,11 @@
 ---
-name: setup-cursor-copies
-description: Setup foundation cursor rules and commands in .cursor/ (run setup script).
-triggers:
-  - setup cursor copies
-  - sync cursor files
-  - /setup_cursor_copies
-  - setup-cursor-copies
+name: setup_cursor_copies
+description: Setup Foundation Cursor Copies
 ---
 
+<!-- Source: .cursor/skills/setup-cursor-copies/SKILL.md -->
+
+
 # Setup Foundation Cursor Copies
 
 Sets up foundation cursor rules and commands in `.cursor/`. **When foundation is a git submodule**, creates **symlinks** (stays in sync with `git submodule update`). Otherwise creates **independent copies**.
@@ -26,7 +24,7 @@ setup cursor copies
 
 ## Purpose
 
-This command runs the foundation setup script (`foundation/scripts/setup_cursor_copies.sh`) which:
+This command runs the foundation setup script (`foundation/scriptsscripts/setup_claude_instructions.sh.sh`) which:
 
 1. **If foundation is a git submodule:** Delegates to `setup_cursor_rules.sh` and creates **symlinks** from foundation to `.cursor/` (single source of truth; updates apply with `git submodule update`).
 2. **Otherwise:** Creates **independent copies** of foundation rules/commands in `.cursor/`.
@@ -70,13 +68,13 @@ This command runs the foundation setup script (`foundation/scripts/setup_cursor_
 **Execute the script:**
 
 ```bash
-./foundation/scripts/setup_cursor_copies.sh
+./foundation/scriptsscripts/setup_claude_instructions.sh.sh
 ```
 
 **Or if foundation is in parent directory:**
 
 ```bash
-../foundation/scripts/setup_cursor_copies.sh
+../foundation/scriptsscripts/setup_claude_instructions.sh.sh
 ```
 
 ### Step 3: Run Copy Script in Peer Repositories (If in Foundation Repo)
@@ -103,7 +101,7 @@ This command runs the foundation setup script (`foundation/scripts/setup_cursor_
        if [ "$SYMLINK_TARGET" = "$CURRENT_REPO" ]; then
          echo "Found peer repo with foundation symlink: $(basename "$peer_repo")"
          # Run copy script in peer repo using absolute path
-         (cd "$peer_repo" && "$CURRENT_REPO/scripts/setup_cursor_copies.sh" || echo "Failed to run in $(basename "$peer_repo")")
+         (cd "$peer_repo" && "$CURRENT_REPO/scriptsscripts/setup_claude_instructions.sh.sh" || echo "Failed to run in $(basename "$peer_repo")")
        fi
      fi
    done
@@ -135,8 +133,8 @@ This command runs the foundation setup script (`foundation/scripts/setup_cursor_
 
 **Check output:**
 
-- **Submodule:** Script reports "Foundation is a git submodule; using symlinks", then rules **linked**. Check `.cursor/rules/` for symlinks; `.cursor/skills/` is populated from foundation skills.
-- **Copy mode:** Script reports rules and skills **copied**. Check `.cursor/rules/` and `.cursor/skills/` for regular files (not symlinks).
+- **Submodule:** Script reports "Foundation is a git submodule; using symlinks", then rules **linked**. Check `.claude/rules/` for symlinks; `.cursor/skills/` is populated from foundation skills.
+- **Copy mode:** Script reports rules and skills **copied**. Check `.claude/rules/` and `.cursor/skills/` for regular files (not symlinks).
 
 **Expected output (submodule):**
 
@@ -166,10 +164,10 @@ This command runs the foundation setup script (`foundation/scripts/setup_cursor_
 ## What Gets Created
 
 **When foundation is a submodule (symlinks):**
-- `.cursor/rules/` contains **symlinks** to `foundation/agent_instructions/cursor_rules/`. `.cursor/skills/` is populated from `foundation/agent_instructions/cursor_skills/` (skills replace legacy commands). Updates to foundation apply when you re-run setup.
+- `.claude/rules/` contains **symlinks** to `foundation/agent_instructions/cursor_rules/`. `.cursor/skills/` is populated from `foundation/agent_instructions/cursor_skills/` (skills replace legacy commands). Updates to foundation apply when you re-run setup.
 
 **When foundation is not a submodule (copies):**
-- `.cursor/rules/` and `.cursor/skills/` contain **independent copies** of foundation rules and skills (e.g. `security.mdc`, `worktree_env.mdc`, and full skill workflows). Re-run to refresh after foundation updates.
+- `.claude/rules/` and `.cursor/skills/` contain **independent copies** of foundation rules and skills (e.g. `security.mdc`, `worktree_env.mdc`, and full skill workflows). Re-run to refresh after foundation updates.
 
 **Note:** Repository rules from `docs/` are handled per `setup_cursor_rules` (symlinks when submodule) or copied in copy mode. Source files in `docs/` remain the source of truth.
 
@@ -219,7 +217,7 @@ Foundation workflows are in `foundation/agent_instructions/cursor_skills/`. If p
 
 ## Related Documents
 
-- `foundation/scripts/setup_cursor_copies.sh` - Entry script (delegates to symlink or copy logic)
+- `foundation/scriptsscripts/setup_claude_instructions.sh.sh` - Entry script (delegates to symlink or copy logic)
 - `foundation/scripts/setup_cursor_rules.sh` - Symlink implementation (used when foundation is submodule)
 - `foundation/agent_instructions/README.md` - Cursor rules and commands documentation
 - `foundation/README.md` - Foundation overview and installation
diff --git a/.claude/skills/shadcn/SKILL.md b/.claude/skills/shadcn/SKILL.md
deleted file mode 100644
index 7ef6c31a0..000000000
--- a/.claude/skills/shadcn/SKILL.md
+++ /dev/null
@@ -1,255 +0,0 @@
----
-name: shadcn
-description: Add or update shadcn/ui components, tokens, and registry components in the Neotoma frontend.
-triggers:
-  - shadcn
-  - /shadcn
-  - add component
-  - install component
-  - shadcn registry
----
-
-# shadcn Skill
-
-Use this skill when adding UI components, theme tokens, or integrating community/registry components from the shadcn ecosystem.
-
-## Project Configuration
-
-- **components.json**: repo root (`/components.json`)
-- **Component output**: `frontend/src/components/ui/`
-- **Tailwind config**: `tailwind.config.mjs` (repo root)
-- **CSS tokens**: `frontend/src/index.css` (`@layer base` — CSS variables for light/dark)
-- **Install command** (run from repo root):
-  ```bash
-  npx shadcn@latest add <component-name>
-  ```
-
-## Decision Tree: Which Component to Use
-
-Work through these layers in order. Stop at the first match.
-
-### 1. Core shadcn/ui (already installed)
-
-Check `frontend/src/components/ui/` first. If the component is there, import and use it.
-
-**Currently installed:**
-`accordion`, `alert`, `avatar`, `badge`, `breadcrumb`, `button`, `card`, `checkbox`, `collapsible`, `command`, `dialog`, `dropdown-menu`, `form`, `input`, `input-group`, `label`, `navigation-menu`, `popover`, `progress`, `scroll-area`, `section-divider`, `select`, `separator`, `sheet`, `sidebar`, `skeleton`, `sonner`, `switch`, `table`, `tabs`, `textarea`, `toast`, `toaster`, `tooltip`
-
-### 2. Standard shadcn/ui (not yet installed)
-
-If the component appears on [https://ui.shadcn.com/docs/components](https://ui.shadcn.com/docs/components), install it:
-
-```bash
-npx shadcn@latest add <component-name>
-```
-
-Common candidates not yet installed:
-- `alert-dialog` — destructive confirmation dialogs
-- `calendar` — date pickers
-- `radio-group` — single-choice options
-- `slider` — numeric range inputs
-- `toggle`, `toggle-group` — toggle buttons
-- `context-menu` — right-click menus
-- `hover-card` — hover information cards
-- `menubar` — application menu bars
-- `pagination` — paginated data navigation
-- `resizable` — resizable panel layouts
-
-### 3. shadcn/ui Registry (community components)
-
-If the standard library doesn't cover the use case, check the registry:
-**URL**: [https://ui.shadcn.com/docs/registry](https://ui.shadcn.com/docs/registry)
-**Directory**: [https://ui.shadcn.com/docs/directory](https://ui.shadcn.com/docs/directory)
-
-Registry components are installable via URL:
-```bash
-npx shadcn@latest add <registry-url>
-```
-
-**When to use the registry:**
-- Complex data tables with sorting/filtering/pagination (look for `data-table` variants)
-- Date range pickers with calendar integration
-- Multi-select combobox / tag inputs
-- Rich text editors (Tiptap-based)
-- File upload dropzones
-- Color pickers
-- Phone number inputs with country code
-- Image cropping / upload components
-- Charts (Recharts-based — `chart` from shadcn is standard, but registry has extensions)
-- Timeline/feed components
-- Drag-and-drop list/board components
-- Code editors (Monaco/CodeMirror wrappers)
-
-**How to find registry components:**
-
-1. Browse [https://ui.shadcn.com/docs/directory](https://ui.shadcn.com/docs/directory) for the component category
-2. Each listing shows the install URL — copy it exactly
-3. Install: `npx shadcn@latest add <url>`
-4. Component lands in `frontend/src/components/ui/` automatically
-
-**Example — installing a registry component:**
-```bash
-# Find component URL from directory, then:
-npx shadcn@latest add https://ui.shadcn.com/r/<component-name>.json
-```
-
-### 4. Custom hand-rolled component
-
-Only build a custom component when:
-- No shadcn or registry equivalent exists
-- The registry equivalent has too many dependencies for the use case
-- The component requires behavior that conflicts with Radix UI primitives
-
-If building custom, still:
-- Use `cn()` from `@/lib/utils` for class merging
-- Use CVA for variants where applicable
-- Follow the token system (see Token System section)
-
----
-
-## Token System
-
-All Tailwind classes must use the registered tokens. Never use arbitrary values that have a named token.
-
-### Color tokens
-
-```
-bg-background / text-foreground
-bg-muted / text-muted-foreground
-bg-card / text-card-foreground
-bg-popover / text-popover-foreground
-bg-primary / text-primary-foreground
-bg-secondary / text-secondary-foreground
-bg-destructive / text-destructive-foreground
-bg-accent / text-accent-foreground
-border-border
-ring-ring
-bg-success / text-success
-bg-warning / text-warning
-bg-info / text-info
-border-divider
-bg-entity-person / bg-entity-company / bg-entity-location / bg-entity-event / bg-entity-document
-```
-
-### Font-size tokens
-
-| Token | Size | Use |
-|---|---|---|
-| `text-caption` | 11px | Smallest labels, timestamps |
-| `text-fine` | 12px | Secondary metadata, captions |
-| `text-ui` | 13px | Primary UI text, table cells |
-| `text-base` | 14px | Nav items, sidebar text |
-| `text-body` | 15px | Body copy |
-| `text-body-lg` | 16px | Larger body |
-| `text-small` | 13px | Small alias |
-| `text-mono` | 14px | Monospace |
-
-Do not use `text-[11px]`, `text-[12px]`, `text-[13px]`, or `text-[14px]` — use the named tokens above.
-
-### Shadow token
-
-Use `shadow-card` instead of `shadow-[0px_15px_30px_0px_rgba(0,0,0,0.05)]`.
-
-### Gradient classes
-
-For radial gradient backgrounds, use the named CSS classes from `index.css`:
-- `.gradient-hero-success` — green+blue hero radial
-- `.gradient-hero-destructive` — red/destructive hero radial
-- `.gradient-section-teal` — teal diagnostic overlay
-
----
-
-## Installing Components
-
-### Standard install (from repo root)
-
-```bash
-cd /path/to/neotoma
-npx shadcn@latest add <component-name>
-```
-
-Answer prompts:
-- If asked to overwrite `components.json`: **n** (preserve existing config)
-- If asked to overwrite an existing component: **n** unless intentionally upgrading
-
-### Registry install
-
-```bash
-npx shadcn@latest add <full-registry-url>
-# Example:
-npx shadcn@latest add https://ui.shadcn.com/r/data-table.json
-```
-
-### After installing
-
-1. Verify the new file appears in `frontend/src/components/ui/`
-2. Check for any new dependencies added to `package.json`
-3. Run `npm install` if new dependencies were added
-4. Verify the component uses the project's token system (update if it uses hardcoded colors/sizes)
-
----
-
-## Replacing Hand-Rolled Patterns
-
-### Expand/collapse → Accordion
-
-Replace:
-```tsx
-<button type="button" className="group flex items-center gap-2 w-full text-left focus:outline-none">
-  {/* trigger */}
-</button>
-{isOpen && <div>{/* content */}</div>}
-```
-
-With:
-```tsx
-import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from "@/components/ui/accordion";
-
-<Accordion type="single" collapsible>
-  <AccordionItem value="item-1">
-    <AccordionTrigger>Trigger text</AccordionTrigger>
-    <AccordionContent>Content</AccordionContent>
-  </AccordionItem>
-</Accordion>
-```
-
-### Raw checkbox → Checkbox
-
-Replace:
-```tsx
-<input type="checkbox" className="rounded border-input" />
-```
-
-With:
-```tsx
-import { Checkbox } from "@/components/ui/checkbox";
-<Checkbox id="my-checkbox" />
-```
-
-### Raw button → Button
-
-Replace:
-```tsx
-<button type="button" className="...custom styles...">
-```
-
-With:
-```tsx
-import { Button } from "@/components/ui/button";
-<Button variant="ghost" size="sm">Label</Button>
-```
-
-Available variants: `default`, `destructive`, `outline`, `secondary`, `ghost`, `link`
-Available sizes: `default`, `sm`, `lg`, `icon`
-
----
-
-## Key References
-
-- Installed components inventory: `docs/ui/shadcn_components.md`
-- Design system spec: `docs/ui/design_system.md`
-- Token definitions (CSS variables): `frontend/src/index.css`
-- Token registrations (Tailwind): `tailwind.config.mjs`
-- shadcn/ui docs: https://ui.shadcn.com/docs
-- Component registry/directory: https://ui.shadcn.com/docs/directory
-- Radix UI primitives: https://www.radix-ui.com/
diff --git a/.claude/skills/store-neotoma/SKILL.md b/.claude/skills/store-neotoma/SKILL.md
new file mode 100644
index 000000000..013c570e0
--- /dev/null
+++ b/.claude/skills/store-neotoma/SKILL.md
@@ -0,0 +1,154 @@
+---
+name: store-neotoma
+description: store-neotoma
+---
+
+<!-- Source: foundation/.cursor/skills/store-neotoma/SKILL.md -->
+
+---
+name: store-neotoma
+description: Review chat, preview exact Neotoma payloads, then store conversation, dual agent_message rows per turn (user + assistant, PART_OF conversation), and attachments after user confirmation.
+triggers:
+  - store_neotoma
+  - /store_neotoma
+  - store chat in neotoma
+  - persist chat to neotoma
+  - review and store conversation
+---
+
+# store-neotoma
+
+## Purpose
+
+Define the workflow for reviewing chat, building a Neotoma store preview, and executing storage after user confirmation. Neotoma is the only data store; there is no Parquet migration phase.
+
+**Canonical location:** `foundation/.cursor/skills/store-neotoma/SKILL.md` (foundation git submodule). Consumer repos may symlink or copy this into `.cursor/skills/store-neotoma/` via `setup_cursor_copies` / `setup_cursor_rules`.
+
+## Scope
+
+Applies when the user asks to store the current chat in Neotoma. Covers preview, user revisions, confirmation, storage, and relationships. Excludes one-off store operations without preview.
+
+Reviews the current chat conversation, builds a preview of records to store in Neotoma, waits for user confirmation (or revision input), then stores conversation, **two `agent_message` entities per logical turn** (`role: "user"` and `role: "assistant"`), each with `PART_OF` → conversation — the canonical shape from Neotoma MCP live chat instructions — plus attachments.
+
+Preview-before-execute: On first run, this workflow MUST preview what will be stored and MUST NOT execute storage until the user confirms. User input (corrections, scope changes, exclusions) MUST be applied to revise the preview.
+
+## Prerequisites
+
+- Chat transcript available in agent context (user and agent messages).
+- Neotoma MCP available.
+- Load `.claude/rules/conversation_tracking.mdc` and `.claude/rules/neotoma_access_policy.mdc` for entity schemas and access rules. `conversation_tracking` defines dual-message + `PART_OF`; do not use merged `role_user`/`role_agent` on a single `agent_message`.
+
+## Phase 0: Preview (MANDATORY — Execute First)
+
+### Step 0.1 — Extract and build preview
+
+Parse all user and agent messages in the conversation. For each **logical turn** (user message + following assistant reply):
+
+- **User row (preview + store):** `entity_type: agent_message`, `role: "user"`, `content` = exact user text, `turn_key` (stable per turn), optional `turn_number` (1-based), `timestamp`, `files_modified`, `tools_used`, `platform`, `model`, `neotoma_operations` (inferred from the turn).
+- **Assistant row (preview + store):** `entity_type: agent_message`, `role: "assistant"`, `content` = exact assistant text shown in chat, `turn_key` e.g. same base + `:assistant`, optional same `turn_number` / `timestamp` for sorting.
+- Topics: extract from user questions, entity types discussed, file paths, domain keywords (finance, admin, health, work).
+- Decisions: extract when agent states an approach, user confirms a choice, or implementation strategy is chosen.
+- Action items: tasks to create, follow-ups mentioned.
+- `files_modified`: file paths from tool calls, @-mentions, or explicit file references (typically attributed to the **user** message for that turn).
+- `neotoma_operations`: inferred from agent tool-call patterns (`store_structured`, `correct`, `create_relationship`).
+
+Identify attachments. All of the following must be included:
+- User-uploaded files (images, screenshots, files attached or pasted in any message, including turn 1). Use whatever path or content the platform provides.
+- @-mentioned file paths.
+- Attachment references and file URLs in message text.
+
+Build preview structure:
+
+- Conversation: full payload with every property and exact value to be stored (see Step 0.2).
+- Messages: **two** exact `agent_message` payloads per turn (user and assistant), each with every property and exact value to be stored, plus distinct `idempotency_key` / `turn_key` per row. Include `PART_OF` targets (conversation `entity_id` after conversation is created).
+- Attachments: list of files to store with path, type, and any store payload (`file_path` or `file_content`).
+- Derived entities (optional): tasks, contacts, events, transactions, notes, or other entity types the turn implies. Show exact raw payloads for user approval.
+
+### Step 0.2 — Display preview
+
+Show structured preview to the user with clear sections. Include tables with the exact properties and exact raw values of every structured object that will be sent to Neotoma, so the user can approve precise payloads before proceeding.
+
+Required sections:
+1. Conversation entity (exact payload).
+2. Agent_message entities (exact payloads — **pairs** per turn: user then assistant).
+3. Attachments (all user-uploaded files, @-mentioned paths, file URLs).
+4. Relationships to create.
+5. Derived entities (exact payloads for any non-chat entities implied by the conversation).
+
+End the preview with:
+- Confirm to proceed, or provide input to revise.
+- Revisions can include exclusions, title/topics changes, and "how to store" preferences (field names, exclusions, formats).
+
+### Step 0.3 — Wait for user response
+
+- If user confirms ("proceed", "confirm", "yes", "go ahead", or equivalent): proceed to Phase 1. If the user previously provided "how to store" input, retain it for post-store neotoma-learn.
+- If user provides input: apply it to preview and/or payloads:
+  - Exclude turns (e.g. "skip turn 3").
+  - Change title or topics.
+  - Add or remove derived entities.
+  - Correct any field.
+  - How to store (e.g. "use conversation_id without date prefix", "store topics as JSON string"). Do not request reverting to merged single-row `role_user`/`role_agent`; dual messages are canonical.
+- Re-display the revised preview (including updated exact payload tables), then wait again.
+- Repeat until user confirms.
+
+## Phase 1: Storage (After Confirmation)
+
+### Step 1.1 — Create conversation entity
+
+Generate `conversation_id` if not yet final. Store via Neotoma MCP:
+
+- `entity_type: conversation`
+- `conversation_id`, `title`, `turn_count`, `start_timestamp`, `last_updated`
+- `topics`, `decisions`, `action_items`
+- `platform: cursor`, `status: active`, `summary`
+
+Use `store_structured` (or equivalent MCP action).
+
+### Step 1.2 — Create agent_message entities per turn (dual rows)
+
+For each turn (respecting exclusions from preview), create **two** stored messages linked to the **same** conversation:
+
+1. **User message:** `entity_type: agent_message`, `role: "user"`, `content` (full text), `turn_key`, optional `turn_number`, `timestamp`, `files_modified`, `tools_used`, `platform`, `model`, `neotoma_operations` as previewed.
+2. **Assistant message:** `entity_type: agent_message`, `role: "assistant"`, `content` (full text), `turn_key` (distinct from user row), optional same `turn_number` / `timestamp`.
+
+Store via Neotoma MCP (`store_structured`), batching multiple entities and `relationships` in one request when supported. For each row, ensure **`PART_OF` from that `agent_message` → conversation** (conversation `entity_id` from Step 1.1 response). Use **distinct** `idempotency_key` values per message (e.g. suffix `-user` / `-assistant` per turn).
+
+### Step 1.3 — Handle attachments
+
+For each file in the attachments list with an accessible path:
+
+- Store file via Neotoma using `file_path` (or `file_content` if required).
+- Create image/media entity if file is an image.
+- Attempt `create_relationship(EMBEDS, user_agent_message_entity_id, file_entity_id)` for attachments on the user turn (or conversation-level link if turn-level linking is unavailable).
+- If EMBEDS fails (known issue), log and continue.
+
+### Step 1.4 — Create relationships
+
+- For **each** `agent_message` (user and assistant): `create_relationship(PART_OF, agent_message_entity_id, conversation_entity_id)` if not already created in the same batched `store_structured` call.
+- For tasks, contacts, projects, execution plans, and other discussed entities: `conversation --[REFERS_TO]--> entity`, or `agent_message --[REFERS_TO]--> entity` for turn-level links.
+
+### Step 1.5 — If user provided "how to store" input: invoke neotoma-learn skill
+
+- If during Phase 0 the user provided input on how to store objects (field renames, exclusions, format preferences), after Phase 1 invoke the `neotoma-learn` skill with that input as the scenario/description (for example "When storing conversation from /store_neotoma: use conversation_id without date prefix"). Do not use neotoma-learn to undo dual-message storage; that shape is canonical.
+- If the user gave no "how to store" input, skip this step.
+
+## Output and Reporting
+
+After execution, report:
+- Storage summary: `conversation_id`, **agent_message count** (expect ~2× turn count when both sides exist), attachments stored, relationship count, derived entity count.
+- Per `.claude/rules/persistence.mdc`, show stored entities via retrieve/list observation actions where relevant.
+- Render the mandatory `🧠 Neotoma` turn report per `.claude/rules/neotoma_turn_lifecycle.mdc`.
+
+## Error Handling
+
+- Neotoma MCP failures: retry once, then report and continue where possible.
+- EMBEDS relationship failure: log and continue.
+
+## References
+
+- `execution/scripts/migrate_neotoma_chat_dual_messages.py` — One-off migration for legacy merged `role_user`/`role_agent` rows and inverted `PART_OF` edges; use `--cli` with the `neotoma` binary when HTTP bearer is rejected (dry-run by default, `--execute` to apply). Path is relative to repos that include `execution/` (e.g. ateles); omit or locate equivalent in other layouts.
+- `.claude/rules/conversation_tracking.mdc` — Entity model and fields.
+- `.claude/rules/neotoma_access_policy.mdc` — Canonical Neotoma-only access rules.
+- `.claude/rules/neotoma_turn_lifecycle.mdc` — Turn lifecycle and turn report contract.
+- `.claude/rules/confirmation_requirements.mdc` — Preview/confirm pattern.
+- `.cursor/skills/neotoma-learn/SKILL.md` — Update Neotoma MCP instructions after user provides "how to store" input (repo-local skill where present; not bundled in foundation-only checkouts).
diff --git a/.claude/skills/store_neotoma/SKILL.md b/.claude/skills/store_neotoma/SKILL.md
index 232c03ca1..e781a5f65 100644
--- a/.claude/skills/store_neotoma/SKILL.md
+++ b/.claude/skills/store_neotoma/SKILL.md
@@ -1,14 +1,11 @@
 ---
-name: store-neotoma
-description: Review chat, preview exact Neotoma payloads, then store conversation, dual agent_message rows per turn (user + assistant, PART_OF conversation), and attachments after user confirmation.
-triggers:
-  - store_neotoma
-  - /store_neotoma
-  - store chat in neotoma
-  - persist chat to neotoma
-  - review and store conversation
+name: store_neotoma
+description: store-neotoma
 ---
 
+<!-- Source: .cursor/skills/store-neotoma/SKILL.md -->
+
+
 # store-neotoma
 
 ## Purpose
@@ -29,7 +26,7 @@ Preview-before-execute: On first run, this workflow MUST preview what will be st
 
 - Chat transcript available in agent context (user and agent messages).
 - Neotoma MCP available.
-- Load `.cursor/rules/conversation_tracking.mdc` and `.cursor/rules/neotoma_access_policy.mdc` for entity schemas and access rules. `conversation_tracking` defines dual-message + `PART_OF`; do not use merged `role_user`/`role_agent` on a single `agent_message`.
+- Load `.claude/rules/conversation_tracking.mdc` and `.claude/rules/neotoma_access_policy.mdc` for entity schemas and access rules. `conversation_tracking` defines dual-message + `PART_OF`; do not use merged `role_user`/`role_agent` on a single `agent_message`.
 
 ## Phase 0: Preview (MANDATORY — Execute First)
 
@@ -129,8 +126,8 @@ For each file in the attachments list with an accessible path:
 
 After execution, report:
 - Storage summary: `conversation_id`, **agent_message count** (expect ~2× turn count when both sides exist), attachments stored, relationship count, derived entity count.
-- Per `.cursor/rules/persistence.mdc`, show stored entities via retrieve/list observation actions where relevant.
-- Render the mandatory `🧠 Neotoma` turn report per `.cursor/rules/neotoma_turn_lifecycle.mdc`.
+- Per `.claude/rules/persistence.mdc`, show stored entities via retrieve/list observation actions where relevant.
+- Render the mandatory `🧠 Neotoma` turn report per `.claude/rules/neotoma_turn_lifecycle.mdc`.
 
 ## Error Handling
 
@@ -140,8 +137,8 @@ After execution, report:
 ## References
 
 - `execution/scripts/migrate_neotoma_chat_dual_messages.py` — One-off migration for legacy merged `role_user`/`role_agent` rows and inverted `PART_OF` edges; use `--cli` with the `neotoma` binary when HTTP bearer is rejected (dry-run by default, `--execute` to apply). Path is relative to repos that include `execution/` (e.g. ateles); omit or locate equivalent in other layouts.
-- `.cursor/rules/conversation_tracking.mdc` — Entity model and fields.
-- `.cursor/rules/neotoma_access_policy.mdc` — Canonical Neotoma-only access rules.
-- `.cursor/rules/neotoma_turn_lifecycle.mdc` — Turn lifecycle and turn report contract.
-- `.cursor/rules/confirmation_requirements.mdc` — Preview/confirm pattern.
+- `.claude/rules/conversation_tracking.mdc` — Entity model and fields.
+- `.claude/rules/neotoma_access_policy.mdc` — Canonical Neotoma-only access rules.
+- `.claude/rules/neotoma_turn_lifecycle.mdc` — Turn lifecycle and turn report contract.
+- `.claude/rules/confirmation_requirements.mdc` — Preview/confirm pattern.
 - `.cursor/skills/neotoma-learn/SKILL.md` — Update Neotoma MCP instructions after user provides "how to store" input (repo-local skill where present; not bundled in foundation-only checkouts).
diff --git a/.claude/skills/sync-env-from-1password/SKILL.md b/.claude/skills/sync-env-from-1password/SKILL.md
new file mode 100644
index 000000000..b09c51f1c
--- /dev/null
+++ b/.claude/skills/sync-env-from-1password/SKILL.md
@@ -0,0 +1,309 @@
+---
+name: sync-env-from-1password
+description: Sync Environment Variables from 1Password
+---
+
+<!-- Source: foundation/.cursor/skills/sync-env-from-1password/SKILL.md -->
+
+---
+name: sync-env-from-1password
+description: Sync .env from 1Password using env_var_mappings.
+triggers:
+  - sync env from 1password
+  - /sync_env_from_1password
+  - sync-env-from-1password
+---
+
+# Sync Environment Variables from 1Password
+
+Sync environment variables from 1Password to local `.env` file using environment variable mappings stored in the truth layer (per `neotoma_parquet_migration_rules.mdc`).
+
+## Command
+
+```
+sync_env_from_1password
+```
+
+or
+
+```
+sync env from 1password
+```
+
+## Purpose
+
+This command syncs environment variables from 1Password to your local `.env` file based on mappings stored in the truth layer (per `neotoma_parquet_migration_rules.mdc`). Parquet path when used: `$DATA_DIR/env_var_mappings/env_var_mappings.parquet`.
+
+**Key features:**
+- Automatic backup before modification
+- Preserves unmanaged environment variables
+- Never prints secret values
+- Supports environment-based keys (e.g., different API keys for dev/prod)
+- Uses 1Password MCP server (preferred) or CLI (fallback)
+
+## Prerequisites
+
+### Option 1: 1Password MCP Server (Recommended)
+
+**Benefits:**
+- Persistent connection (no session expiration)
+- Better error handling
+- No repeated authentication
+- Consistent with other MCP integrations
+
+**Setup:**
+
+1. **Ensure 1Password CLI is installed:**
+   ```bash
+   brew install 1password-cli
+   op signin
+   ```
+
+2. **Configure MCP server** in `~/.cursor/mcp.json`:
+   ```json
+   {
+     "mcpServers": {
+       "onepassword": {
+         "command": "bash",
+         "args": [
+           "/Users/markmhendrickson/repos/ateles/mcp/onepassword/run-onepassword-mcp.sh"
+         ],
+         "env": {}
+       }
+     }
+   }
+   ```
+
+3. **Verify MCP server is running:**
+   - Restart Cursor after updating mcp.json
+   - MCP server status visible in Cursor MCP panel
+
+**For detailed setup instructions, see:** `mcp/onepassword/README.md`
+
+### Option 2: 1Password CLI (Fallback)
+
+**When to use:**
+- MCP server not configured
+- Temporary/one-off sync
+- Troubleshooting MCP issues
+
+**Setup:**
+
+1. **Install 1Password CLI:**
+   ```bash
+   brew install 1password-cli
+   ```
+
+2. **Sign in:**
+   ```bash
+   op signin
+   ```
+
+**Note:** CLI sessions expire periodically and require re-authentication.
+
+## Configuration
+
+### Environment Variable Mappings
+
+Mappings are in the truth layer (per `neotoma_parquet_migration_rules.mdc`). Parquet path when used: `$DATA_DIR/env_var_mappings/env_var_mappings.parquet`.
+
+**Schema:**
+- `env_var` (string): Environment variable name (e.g., `OPENAI_API_KEY`)
+- `op_reference` (string): 1Password reference (e.g., `op://Personal/API-Keys/openai_token`)
+- `item_name` (string, optional): Friendly name of 1Password item
+- `field_label` (string, optional): Field label in 1Password
+- `notes` (string, optional): Additional notes
+- `environment_based` (boolean, optional): If true, key varies by environment
+- `environment_key` (string, optional): Environment identifier (e.g., "development", "production")
+
+### Adding/Updating Mappings
+
+**Via MCP parquet server:**
+```python
+# Add new mapping
+mcp_parquet_add_record(
+    data_type="env_var_mappings",
+    record={
+        "env_var": "MY_API_KEY",
+        "op_reference": "op://Personal/API-Keys/my_api_key",
+        "item_name": "API Keys",
+        "field_label": "my_api_key"
+    }
+)
+
+# Update existing mapping
+mcp_parquet_update_records(
+    data_type="env_var_mappings",
+    filters={"env_var": "MY_API_KEY"},
+    updates={"op_reference": "op://Personal/NewItem/field"}
+)
+```
+
+**Via direct parquet editing:**
+```python
+import pandas as pd
+from scripts.config import DATA_DIR
+
+# Read mappings
+mappings_file = DATA_DIR / "env_var_mappings" / "env_var_mappings.parquet"
+df = pd.read_parquet(mappings_file)
+
+# Add or modify rows
+# ...
+
+# Write back
+df.to_parquet(mappings_file)
+```
+
+### Environment-Based Keys
+
+For environment-specific keys (e.g., different API keys for dev/prod):
+
+```python
+# Development key
+{
+    "env_var": "OPENAI_API_KEY",
+    "op_reference": "op://Personal/API-Keys/openai_dev",
+    "environment_based": True,
+    "environment_key": "development"
+}
+
+# Production key
+{
+    "env_var": "OPENAI_API_KEY",
+    "op_reference": "op://Personal/API-Keys/openai_prod",
+    "environment_based": True,
+    "environment_key": "production"
+}
+```
+
+**Set environment:**
+```bash
+export ENVIRONMENT=production  # or "development"
+```
+
+## Execution Instructions
+
+### Step 1: Verify Prerequisites
+
+**If using MCP server:**
+```bash
+# Verify MCP server is configured (check ~/.cursor/mcp.json)
+# Restart Cursor if you just added the configuration
+```
+
+**If using CLI fallback:**
+```bash
+# Verify 1Password CLI is installed and signed in
+op whoami
+# If not signed in: op signin
+```
+
+### Step 2: Run Sync Command
+
+**From repository root:**
+```bash
+python execution/scripts/op_sync_env_from_1password.py
+```
+
+**Or with custom .env path:**
+```bash
+python execution/scripts/op_sync_env_from_1password.py /path/to/.env
+```
+
+### Step 3: Verify Results
+
+**Check output:**
+- ✓ Backup created (in `.env.backups/`)
+- ✓ Updated keys listed (values NOT shown for security)
+- ✓ Sync completed successfully
+
+**Check .env file:**
+```bash
+# Verify variables were updated (don't print full file - contains secrets)
+grep -c "=" .env  # Count of variables
+```
+
+## Behavior
+
+### Backup
+
+**Automatic backup before modification:**
+- Location: `.env.backups/.env-YYYY-MM-DD-HHMMSS`
+- Only created if `.env` file exists
+- Backup preserves exact file state
+
+### Variable Updates
+
+**For each mapped variable:**
+1. Resolve secret from 1Password (via MCP or CLI)
+2. Update existing variable or append new one
+3. Preserve other variables in `.env` (unmanaged variables untouched)
+
+**Variables with `PLACEHOLDER_` prefix are skipped** until configured with actual 1Password references.
+
+### Security
+
+**Security guarantees:**
+- Never prints secret values (only variable names)
+- Creates backup before modification
+- Error messages never expose secrets
+- Validates session before proceeding
+
+## Error Handling
+
+### "1Password CLI is not authenticated"
+
+**Problem:** Not signed in to 1Password CLI.
+
+**Solution:**
+```bash
+op signin
+```
+
+### "MCP failed, falling back to CLI"
+
+**Problem:** MCP server unavailable or misconfigured.
+
+**Solution:**
+1. Check MCP server configuration in `~/.cursor/mcp.json`
+2. Restart Cursor after updating configuration
+3. Verify 1Password CLI is installed and signed in
+4. Script will automatically fall back to CLI
+
+### "Environment variable mappings file not found"
+
+**Problem:** Mappings file doesn't exist.
+
+**Solution:**
+```bash
+# Create mappings file structure
+mkdir -p $DATA_DIR/env_var_mappings
+
+# Add mappings via MCP parquet server or create parquet file
+# See Configuration section above
+```
+
+### "Empty value returned for 1Password ref"
+
+**Problem:** Field exists but contains empty value.
+
+**Solution:**
+- Verify field has value in 1Password app
+- Check spelling of field name in reference
+- Try: `op item get "<item-name>" --format=json` to see available fields
+
+## Related Documentation
+
+- `mcp/onepassword/README.md` - 1Password MCP server documentation
+- `execution/scripts/onepassword_client.py` - MCP client implementation
+- `execution/scripts/op_sync_env_from_1password.py` - Sync script implementation
+- `$DATA_DIR/schemas/env_var_mappings_schema.json` - Mappings schema (if exists)
+
+## Notes
+
+- **MCP preferred over CLI:** Script tries MCP first, falls back to CLI automatically
+- **Persistent connection:** MCP eliminates session expiration issues
+- **Backward compatible:** Existing CLI-based workflows continue to work
+- **No breaking changes:** Same interface, enhanced implementation
+- **Security first:** All security guarantees preserved from original implementation
diff --git a/.claude/skills/sync_env_from_1password/SKILL.md b/.claude/skills/sync_env_from_1password/SKILL.md
index 09ed98d18..0b8bed93a 100644
--- a/.claude/skills/sync_env_from_1password/SKILL.md
+++ b/.claude/skills/sync_env_from_1password/SKILL.md
@@ -1,12 +1,11 @@
 ---
-name: sync-env-from-1password
-description: Sync .env from 1Password using env_var_mappings.
-triggers:
-  - sync env from 1password
-  - /sync_env_from_1password
-  - sync-env-from-1password
+name: sync_env_from_1password
+description: Sync Environment Variables from 1Password
 ---
 
+<!-- Source: .cursor/skills/sync-env-from-1password/SKILL.md -->
+
+
 # Sync Environment Variables from 1Password
 
 Sync environment variables from 1Password to local `.env` file using environment variable mappings stored in the truth layer (per `neotoma_parquet_migration_rules.mdc`).
diff --git a/.cursor/rules/inspector_shadcn_rules.mdc b/.cursor/rules/inspector_shadcn_rules.mdc
new file mode 120000
index 000000000..e3689f546
--- /dev/null
+++ b/.cursor/rules/inspector_shadcn_rules.mdc
@@ -0,0 +1 @@
+/Users/markmhendrickson/repos/neotoma/docs/ui/inspector_shadcn_rules.mdc
\ No newline at end of file
diff --git a/.github/workflows/claude_pr_review.yml b/.github/workflows/claude_pr_review.yml
index 26639c23e..3c022db52 100644
--- a/.github/workflows/claude_pr_review.yml
+++ b/.github/workflows/claude_pr_review.yml
@@ -80,6 +80,25 @@ jobs:
             echo "substantial=false" >> $GITHUB_OUTPUT
           fi
 
+      - name: Comment on skipped review
+        if: steps.diff_check.outputs.substantial == 'false' && github.event_name == 'pull_request'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          PR_NUMBER=${{ github.event.pull_request.number }}
+          REPO=${{ github.repository }}
+
+          FILES=$(gh pr view $PR_NUMBER --repo $REPO --json files --jq '.files | length')
+          ADDITIONS=$(gh pr view $PR_NUMBER --repo $REPO --json additions --jq '.additions')
+          DELETIONS=$(gh pr view $PR_NUMBER --repo $REPO --json deletions --jq '.deletions')
+          LINES=$((ADDITIONS + DELETIONS))
+
+          gh pr comment $PR_NUMBER --repo $REPO --body "**Claude review skipped** — diff is below the automatic-review threshold (${FILES} file(s), ${LINES} line(s) changed).
+
+Thresholds that trigger a review: >5 files, >150 lines, any \`packages/\` change, any auth-related path, or a simultaneous \`src/\` + \`openapi.yaml\` change.
+
+To request a review anyway, comment \`@claude review\` on this PR."
+
       - uses: anthropics/claude-code-action@beta
         if: steps.diff_check.outputs.substantial == 'true'
         with:
diff --git a/docs/developer/cli_agent_instructions.md b/docs/developer/cli_agent_instructions.md
index 8be4fe8bd..0cd375ced 100644
--- a/docs/developer/cli_agent_instructions.md
+++ b/docs/developer/cli_agent_instructions.md
@@ -71,6 +71,10 @@ neotoma relationships create --source-entity-id <container_id> --target-entity-i
 
 Entity IDs are returned in the `store` response (`entities[].entity_id`). If `relationships create` fails or is unavailable, check `neotoma relationships --help` for current syntax.
 
+## Relationship creation guidance (canonical)
+
+For when and how to link a newly stored entity to existing entities (pre-store candidate discovery, `retrieve_related_entities`, canonical relationship examples, direction convention), see `docs/developer/mcp/instructions.md` [RELATIONSHIP CREATION].
+
 ## Pre-check before storing (CLI backup)
 
 Before storing a new entity, check for an existing record to avoid duplicates:
diff --git a/docs/developer/getting_started.md b/docs/developer/getting_started.md
index 7ef3e40e4..0ebd3c7dd 100644
--- a/docs/developer/getting_started.md
+++ b/docs/developer/getting_started.md
@@ -118,6 +118,14 @@ npm run type-check
 npm run lint
 ```
 
+## Feature guides
+
+- [Plans](plans_guide.md) — store engineering plans as entities, with optional disk mirror.
+- [Issues](issues_guide.md) — built-in issue tracker with optional GitHub mirror.
+- [Markdown mirror](mirror_guide.md) — read-only filesystem view of Neotoma data.
+- [Subscriptions](subscriptions_guide.md) — real-time webhooks and SSE for data changes.
+- [Skills](skills_guide.md) — store reusable agent workflows as entities, mirrored to your harness skill directory.
+
 ## First contribution checklist
 
 - Run `npm run type-check`
diff --git a/docs/developer/mcp/instructions.md b/docs/developer/mcp/instructions.md
index 1a19b046f..1a132e181 100644
--- a/docs/developer/mcp/instructions.md
+++ b/docs/developer/mcp/instructions.md
@@ -132,6 +132,13 @@ Restore: restore_entity and restore_relationship create restoration observations
 Merge and duplicate repair: use list_potential_duplicates(entity_type, threshold?, limit?) as a read-only detector; never auto-merge. Confirm candidate pairs with the user or a repair plan, then call merge_entities(from_entity_id, to_entity_id) to rewrite observations from the duplicate into the target and mark the source merged.
 Split over-merges: use split_entity to re-point a predicate-selected subset of an entity's observations onto a new or existing entity when a prior merge or heuristic resolution collapsed distinct entities. split_entity is the inverse of merge_entities, is idempotent via (user_id, idempotency_key), preserves observation content, and leaves typed relationships bound to the source until rebuilt with create_relationship.
 
+[RELATIONSHIP CREATION]
+Pre-store candidate discovery: before completing any `store` operation that creates a new entity, check whether the new entity logically relates to entities already in context — same person, same project, same conversation thread, same source document, same organization. Use `retrieve_related_entities` or `retrieve_entity_by_identifier` to discover existing candidates when the session has not already confirmed their ids. When a candidate is found, create the relationship in the same `store` call using the `relationships` array (index-based or id-based entries), or immediately after with `create_relationships`. FORBIDDEN: completing a store turn that creates a new non-bookkeeping entity without first considering whether it has a logical relationship to entities already known this session or returned by bounded retrieval.
+Relationship-in-same-store: prefer defining relationships in the `store` `relationships` array over separate `create_relationship` calls. Use `{ relationship_type, source_index, target_index }` when both entities are in the same request, or `{ relationship_type, source_entity_id, target_entity_id }` when linking to an existing entity whose id was returned by retrieval. Only use `create_relationships` as a follow-up when the target entity id was not known at store time.
+Canonical relationship examples — use these as a guide when context implies a connection: (1) person or contact → organization/company: `REFERS_TO` (person works at or is affiliated with org); (2) task → conversation: `REFERS_TO` (task was created from or motivated by a conversation turn); (3) workout_session, run, or activity → source conversation: `REFERS_TO` (entity extracted from a chat message describing the session); (4) issue → plan or feature_spec: `REFERS_TO` (issue relates to a plan or spec); (5) note or report → analyzed entity: `REFERS_TO` (analysis references its subject); (6) event → location/place: `REFERS_TO` (event occurs at a place); (7) task → person/contact: `REFERS_TO` (task involves or is assigned to a person); (8) any extracted entity → source document or email: `REFERS_TO` (entity was extracted from that artifact, complementing the `interpretation` / `source_id` provenance chain). These examples are illustrative, not exhaustive — apply the same logic to any entity pair where one logically concerns, involves, or was produced from the other.
+retrieve_related_entities for traversal: when you need to check whether an entity is already linked to a candidate target, or when the user asks about connections, call `retrieve_related_entities` with the known `entity_id` before creating a new relationship — this avoids duplicate edges and surfaces existing context. Use `retrieve_graph_neighborhood` for a broader view of an entity's graph position when multi-hop context is needed.
+Relationship direction convention: for `REFERS_TO`, set `source_entity_id` to the more specific or derivative entity (the thing that refers) and `target_entity_id` to the more general or foundational entity (the thing being referred to). For `PART_OF`, set source to the part and target to the whole. Do not invert these; incorrect direction degrades graph traversal quality.
+
 [COMMUNICATION & DISPLAY]
 Silent storage default: do not mention storage, memory, or linking unless the user asked, except when a turn created, updated, or retrieved Neotoma entities and you are required to show them per the display rule below. Do not describe internal persistence in thought or reply (e.g. "Persisting this turn, then replying", "Storing the conversation first"). When confirming something was stored, use memory-related language ("remember", "recall", "stored in memory") and include one of those phrases.
 Proactive storage: use MCP actions proactively. Store when the user states relevant information; store first, then respond. Do not skip store because the user did not ask to save.
@@ -233,7 +240,7 @@ Optional `relationships` on **`store`** is an array of relationship entries. Use
 
 The instruction block is tuned so agents can complete a turn (retrieval → user-phase store → attachment EMBEDS → assistant reply → closing store) without opening tool schemas or exploring the MCP tool set:
 
-1. **Labelled sections.** Bracket-prefixed labels ([TURN LIFECYCLE], [DATA MODEL], [GUEST ENTITY SUBMISSION] (includes PII stripping checklist before issue filing), [CROSS-INSTANCE SYNC — PEERS], [SUBSTRATE SUBSCRIPTIONS], [STORE RECIPES], [RETRIEVAL], [PROVENANCE], [TASKS & COMMITMENTS], [ENTITY TYPES & SCHEMA], [ENTITY & RELATIONSHIP LIFECYCLE], [COMMUNICATION & DISPLAY], [ATTRIBUTION & AGENT IDENTITY], [CONVENTIONS], [ISSUE REPORTING], [QA REFLECTION], [ERRORS & RECOVERY], [ONBOARDING]) let agents locate rules by topic and cross-reference from one section to another without restating them.
+1. **Labelled sections.** Bracket-prefixed labels ([TURN LIFECYCLE], [DATA MODEL], [GUEST ENTITY SUBMISSION] (includes PII stripping checklist before issue filing), [CROSS-INSTANCE SYNC — PEERS], [SUBSTRATE SUBSCRIPTIONS], [STORE RECIPES], [RETRIEVAL], [PROVENANCE], [TASKS & COMMITMENTS], [ENTITY TYPES & SCHEMA], [ENTITY & RELATIONSHIP LIFECYCLE], [RELATIONSHIP CREATION], [COMMUNICATION & DISPLAY], [ATTRIBUTION & AGENT IDENTITY], [CONVENTIONS], [ISSUE REPORTING], [QA REFLECTION], [ERRORS & RECOVERY], [ONBOARDING]) let agents locate rules by topic and cross-reference from one section to another without restating them.
 2. **No exploration.** One prominent line under [STORE RECIPES] forbids listing, globbing, or reading MCP tool descriptor/schema files for chat, attachment, and entity-extraction flows. All parameter names and response paths used by the recipes (`structured.entities[].entity_id`, `unstructured.asset_entity_id`) are inline, so agents never need to open schemas.
 3. **Unified store shape.** The user-phase recipe covers chat, extraction, and attachments as a single entities list [conversation, message, …extracted entities] with one invariant (PART_OF from message to conversation) plus REFERS_TO per extracted entity. Each list entry is a **flat** object (fields beside `entity_type`); the legacy **`attributes`** wrapper is forbidden (see first bullets under [STORE RECIPES]). Attachment turns use the same shape plus file_path/file_content and a single follow-up EMBEDS call.
 4. **Turn-ordered rules.** [TURN LIFECYCLE] encodes the five-step ordering (retrieval, user-phase store, other actions, reply, closing store) once; other sections reference those step numbers instead of re-describing the ordering.
diff --git a/docs/developer/skills_guide.md b/docs/developer/skills_guide.md
new file mode 100644
index 000000000..74f22422d
--- /dev/null
+++ b/docs/developer/skills_guide.md
@@ -0,0 +1,125 @@
+# Skills
+
+Skills are reusable agent workflows stored as Neotoma entities and mirrored to your harness skill directory. This is optional. You can keep writing skill files by hand and Neotoma works the same as before.
+
+## Why store skills in Neotoma
+
+When skills are entities, you can:
+
+- Query and retrieve them across harnesses (`retrieve_entities { entity_type: "skill" }`).
+- Surface them in the harness slash-command palette automatically via the `user_invocable` field.
+- Mirror them to disk via the `neotoma-skills` mirror profile so your harness picks them up as `<name>/SKILL.md` files.
+- Link them to issues, plans, and other entities in the graph.
+
+If you do not need any of that, skip this guide. Hand-authored skill files work as they always have.
+
+## Storing skills
+
+### From an agent conversation
+
+Any agent with MCP access can store a skill during a conversation turn:
+
+```json
+{
+  "entity_type": "skill",
+  "name": "import-audio",
+  "description": "Import and transcribe audio files from desktop.",
+  "triggers": ["import audio", "transcribe audio from desktop"],
+  "content": "# Import Audio\n\n...",
+  "user_invocable": true
+}
+```
+
+`name` is the canonical identifier (kebab-case). Storing the same `name` again updates the existing skill entity rather than creating a duplicate.
+
+### From existing skill files
+
+You can capture an existing `SKILL.md` file by parsing its frontmatter and body and storing the result as a `skill` entity:
+
+```bash
+neotoma store --entity-type skill \
+  --file .cursor/skills/import-audio/SKILL.md
+```
+
+The CLI reads `name`, `description`, `triggers`, and `user_invocable` from the YAML frontmatter and `content` from the markdown body.
+
+## Reading skills
+
+Use standard entity retrieval:
+
+```bash
+# List all skill entities
+neotoma list --entity-type skill
+
+# Show a specific skill by name
+neotoma retrieve --entity-type skill --name import-audio
+```
+
+Via MCP:
+- `retrieve_entities { entity_type: "skill" }` for list queries.
+- `retrieve_entity_by_identifier { entity_type: "skill", identifier: "import-audio" }` for lookup by name.
+- `retrieve_entity_snapshot { entity_id: "<id>" }` for the full skill body and all fields.
+
+## Mirror to disk
+
+The `neotoma-skills` mirror profile writes skill entities back to your harness skill directory as `<name>/SKILL.md` files with YAML frontmatter. When the mirror is active, any change to a skill entity regenerates the corresponding file automatically.
+
+Mirror layout example:
+
+```
+.cursor/skills/
+  import-audio/
+    SKILL.md        ← generated from the skill entity
+  process-issues/
+    SKILL.md
+```
+
+Each `SKILL.md` file contains:
+
+```yaml
+---
+name: import-audio
+description: "Import and transcribe audio files from desktop."
+triggers:
+  - import audio
+  - transcribe audio from desktop
+user_invocable: true
+entity_id: ent_f971d8f20a9d26cc15acdf10
+---
+
+# Import Audio
+
+...workflow instructions...
+```
+
+The `entity_id` field in the frontmatter lets Neotoma match the file back to its entity on the next sync. Do not edit mirrored files directly — changes are overwritten on the next mirror write. To modify a skill, use the Inspector, `neotoma edit <entity-id>`, or the MCP `correct` action.
+
+## Slash-command palette
+
+Setting `user_invocable: true` on a skill entity causes the harness to surface it as an invocable slash command. In Claude Code, skills with this field set appear in the `/` palette and can be triggered by name (e.g. `/import-audio`).
+
+When the mirror is enabled, setting `user_invocable: true` on a skill entity and rebuilding the mirror is all that is needed — no manual frontmatter editing required.
+
+## Skill fields
+
+Key fields on a skill entity:
+
+| Field | Description |
+|-------|-------------|
+| `name` | Kebab-case canonical identifier (e.g. `import-audio`). Used as the subdirectory name. |
+| `description` | One-sentence description shown in the slash-command palette and used for intent matching. |
+| `triggers` | Natural-language phrases that activate the skill (e.g. `["import audio", "transcribe audio"]`). |
+| `content` | Full markdown workflow body, written as the content section of `SKILL.md`. |
+| `user_invocable` | When `true`, the skill appears in the harness slash-command palette. |
+| `enabled` | When `false`, the skill is excluded from mirror output. Defaults to active. |
+| `version` | Semver or free-form version string. Informational only. |
+| `supported_harnesses` | List of harnesses this skill is compatible with (e.g. `["cursor", "claude-code"]`). Empty means all. |
+| `harness_config` | Per-harness configuration overrides. |
+| `synced_at` | Timestamp of the last mirror write or external sync. |
+
+For the full schema, see [`src/services/skills/seed_schema.ts`](../../src/services/skills/seed_schema.ts).
+
+## Related
+
+- [`docs/developer/mirror_guide.md`](mirror_guide.md) for the mirror profile system.
+- [`docs/developer/cli_reference.md`](cli_reference.md) for the `neotoma` CLI reference.
diff --git a/docs/plans/fu-2026-05-003-inspector-conversation-turn-anchors-ext-apps-widget-host.md b/docs/plans/fu-2026-05-003-inspector-conversation-turn-anchors-ext-apps-widget-host.md
new file mode 100644
index 000000000..1972f856b
--- /dev/null
+++ b/docs/plans/fu-2026-05-003-inspector-conversation-turn-anchors-ext-apps-widget-host.md
@@ -0,0 +1,50 @@
+---
+title: Fu 2026 05 003 inspector conversation turn anchors ext apps widget host
+category: process
+subcategory: planning
+---
+
+# Fu 2026 05 003 inspector conversation turn anchors ext apps widget host
+
+<!-- Do not edit this file directly. Corrections go through `neotoma corrections create`, `neotoma edit <id>`, or the Neotoma Inspector. This file is regenerated on every relevant write. -->
+
+---
+entity_id: ent_d444e07b939442ee21de0c89
+entity_type: plan
+schema_version: 1.26.0
+last_observation_at: 2026-05-18T10:03:16.080Z
+observation_count: 1
+computed_at: 2026-05-18T10:03:16.080Z
+title: "FU-2026-05-003: Inspector Conversation Turn Anchors + ext-apps Widget Host"
+status: draft
+priority: P1
+tags:
+  - inspector
+  - ext-apps
+  - conversation
+  - turn-anchors
+---
+
+## overview
+
+Per-turn anchor sections (#msg-N, #stored-N, #retrieved-N, #issues-N) on Inspector conversation page, derived from REFERS_TO relationship graph. Turn timeline sidebar. Issue consent card and mode discovery prompt. New GET /api/conversations/:id/turn-index API endpoint. Depends on FU-2026-05-002.
+
+## scope
+
+Per-turn anchor sections on Inspector conversation page. REFERS_TO graph traversal for turn index. Turn timeline sidebar. Issue consent card. Mode discovery prompt. GET /api/conversations/:id/turn-index endpoint.
+
+## target_release
+
+v0.13.0
+
+## out_of_scope
+
+Changes to MCP tool definitions (FU-2026-05-002). Backend conversation_message_count (FU-2026-05-001).
+
+## dependencies
+
+- FU-2026-05-002: neotoma_turn_summary MCP Tool + Single-Line Display Rule
+
+## success_criteria
+
+Inspector conversation page shows per-turn anchors. Timeline sidebar navigates to turns. Issue consent card surfaces correctly. /api/conversations/:id/turn-index endpoint returns correct index.
diff --git a/docs/testing/automated_test_catalog.md b/docs/testing/automated_test_catalog.md
index 233528682..8fcdc3480 100644
--- a/docs/testing/automated_test_catalog.md
+++ b/docs/testing/automated_test_catalog.md
@@ -61,15 +61,15 @@ flowchart TD
 - Do not hand-edit suite inventory entries in this file. Update the generator or the repository tree, then regenerate.
 
 ## Repo-wide summary
-- Total automated test files: **392**
-- Backend and repo Vitest files: **359**
+- Total automated test files: **393**
+- Backend and repo Vitest files: **360**
 - Frontend Vitest files: **9**
 - Playwright spec files: **24**
 
 ### Suite counts
 | Suite | Files |
 |---|---:|
-| Vitest unit tests | 96 |
+| Vitest unit tests | 97 |
 | Vitest service tests | 33 |
 | Source-adjacent tests | 45 |
 | Vitest integration tests | 107 |
@@ -107,7 +107,7 @@ flowchart TD
 **Runner:** `vitest`
 **Command:** `npm test -- tests/unit`
 **Requirements:** Basic `.env` if required by the module under test.
-**Files (96):**
+**Files (97):**
 - `tests/unit/aauth_admission.test.ts`
 - `tests/unit/aauth_attestation_apple_se.test.ts`
 - `tests/unit/aauth_attestation_revocation.test.ts`
@@ -149,6 +149,7 @@ flowchart TD
 - `tests/unit/drift_comparison.test.ts`
 - `tests/unit/duplicate_detection.test.ts`
 - `tests/unit/encrypt_response_middleware.test.ts`
+- `tests/unit/entity_search_type_boost.test.ts`
 - `tests/unit/external_actor_badge.test.ts`
 - `tests/unit/external_actor_builder.test.ts`
 - `tests/unit/external_actor_promoter.test.ts`
diff --git a/docs/ui/inspector_shadcn_audit.md b/docs/ui/inspector_shadcn_audit.md
new file mode 100644
index 000000000..76d6c543a
--- /dev/null
+++ b/docs/ui/inspector_shadcn_audit.md
@@ -0,0 +1,116 @@
+---
+title: Inspector shadcn audit
+category: developer_reference
+subcategory: inspector
+---
+
+# Inspector shadcn audit
+
+## Route Groups
+
+- **Chrome:** `inspector/src/components/layout/app_layout.tsx`, `header.tsx`, `sidebar.tsx`, `sidebar_user_footer.tsx`, `sandbox_banner.tsx`, `page_shell.tsx`
+- **Primary browsing:** `dashboard.tsx`, `search.tsx`, `entities.tsx`, `sources.tsx`, `observations.tsx`, `relationships.tsx`, `timeline.tsx`, `interpretations.tsx`
+- **Detail inspection:** `entity_detail.tsx`, `source_detail.tsx`, `relationship_detail.tsx`, `schema_detail.tsx`, `timeline_event_detail.tsx`, `conversation_detail.tsx`, `turn_detail.tsx`
+- **Agent and access:** `agents.tsx`, `agent_detail.tsx`, `agent_grants.tsx`, `agent_grant_detail.tsx`, `access_policies.tsx`
+- **Operations:** `issues.tsx`, `issue_detail.tsx`, `subscriptions.tsx`, `peers.tsx`, `peer_detail.tsx`, `compliance.tsx`, `settings.tsx`, `sandbox.tsx`
+- **Shared inspection components:** `agent_filter.tsx`, `json_viewer.tsx`, `type_badge.tsx`, `field_value.tsx`, `snapshot_field_list.tsx`, `markdown_body_sheet.tsx`, recent feed components, relationship and timeline panels
+
+## Live reference
+
+- **`/design`** in the Inspector app (`inspector/src/pages/design.tsx`) — tabbed showcase of tokens, typography, primitives, forms, overlays, data composites, and inspection patterns (including observation vs world-time timelines). Use when validating UI work or onboarding to Inspector chrome.
+
+## Current shadcn Coverage
+
+Inspector already has a strong shadcn-style base under `inspector/src/components/ui`:
+
+- **Core primitives in use:** `Button`, `Input`, `Label`, `Card`, `Badge`, `Dialog`, `Select`, `Switch`, `Tooltip`, `Skeleton`, `Alert`, `ScrollArea`, `Sheet`, `Tabs`, `Textarea`, `DropdownMenu`
+- **Data composites in use:** `DataTable`, `Pagination`, `ConfirmDialog`
+- **Available but underused:** `Checkbox`, `Popover`, `Toggle`, `ToggleGroup`
+- **Missing for planned adoption:** `Table`, `AlertDialog`
+
+Keep the mirrored frontend contract on `data-table.tsx`, `pagination.tsx`, and `confirm-dialog.tsx` unless that coupling is intentionally removed.
+
+## Findings
+
+| Surface | Current pattern | shadcn target | Priority |
+| --- | --- | --- | --- |
+| `components/shared/agent_filter.tsx` | Native `<select>` and `<optgroup>` | `Select` or a grouped Select-equivalent | High |
+| `pages/issues.tsx` | Raw filter buttons | `ToggleGroup` with `ToggleGroupItem` | High |
+| `pages/issues.tsx` | Native checkboxes | `Checkbox` with `Label` | High |
+| `pages/issues.tsx` | Raw action buttons | `Button` variants and sizes | High |
+| `pages/issues.tsx` | Hand-built status and label pills | `Badge` | High |
+| `pages/issues.tsx` | Bare destructive error text | `QueryErrorAlert` or `Alert` | High |
+| `pages/issues.tsx` | `window.confirm` for remove flows | `ConfirmDialog` now; `AlertDialog` later | High |
+| `pages/issue_detail.tsx` | Raw copy/action/send buttons | `Button` | High |
+| `pages/issue_detail.tsx` | Raw reply `<textarea>` | `Textarea` | High |
+| `pages/issue_detail.tsx` | Hand-built status and label pills | `Badge` | High |
+| `pages/issue_detail.tsx` | Raw segmented formatted/raw toggle | `ToggleGroup` | High |
+| `pages/issue_detail.tsx` | `window.confirm` for removal | `ConfirmDialog` now; `AlertDialog` later | High |
+| `components/shared/inspector_theme_toggle.tsx` | Custom radiogroup buttons | `ToggleGroup` while preserving radiogroup semantics | Medium |
+| `pages/entity_detail.tsx` | Raw formatted/raw toggle | `ToggleGroup` | Medium |
+| `pages/entity_detail.tsx` | Native textareas for field edits | `Textarea` | Medium |
+| `components/shared/markdown_body_sheet.tsx` | Raw formatted/raw toggle | `ToggleGroup` | Medium |
+| `components/shared/json_viewer.tsx` | Tiny raw expander buttons | `Button` `variant="ghost"` `size="sm"` | Medium |
+| `components/shared/type_badge.tsx` | Custom span pill | `Badge` wrapper retaining entity-type colors | Medium |
+| `components/layout/sidebar.tsx` | Hand-built search suggestion popover | `Popover` or `Command` later | Medium |
+| `components/layout/sidebar.tsx` | More section label (static) | — | Done |
+| `pages/sources.tsx` | Hand-built source cards and chips | `Card`, `Badge`, reusable result-list item | Low |
+| `pages/graph_explorer.tsx` | Inline hardcoded node colors | CSS variable-backed node styles | Low |
+| `pages/peers.tsx`, `peer_detail.tsx`, `subscriptions.tsx` | `window.confirm` on destructive actions | `ConfirmDialog` now; `AlertDialog` later | Low |
+
+## Batches
+
+### Batch 1: Low-risk consistency pass
+
+Use only primitives already present in `inspector/src/components/ui`.
+
+- Replace `AgentFilterControl` native select with `Select`
+- Normalize `issues.tsx` with `ToggleGroup`, `Checkbox`, `Button`, `Badge`, `Alert`, and `ConfirmDialog`
+- Normalize `issue_detail.tsx` with `Button`, `Textarea`, `Badge`, `ToggleGroup`, `Alert`, and `ConfirmDialog`
+- Convert formatted/raw toggles in `entity_detail.tsx` and `markdown_body_sheet.tsx` to `ToggleGroup`
+
+### Batch 2: Shared inspection primitives
+
+Create small wrappers only where they remove repeated markup.
+
+- Add a reusable issue/status badge helper if Issue pages need status-specific variants
+- Convert `TypeBadge` to wrap `Badge` while preserving `getEntityTypeColor`
+- Convert `JsonViewer` expander buttons to `Button` ghost controls
+- Introduce a `FilterBar` or `ResultCard` only if two or more pages can immediately use it
+
+### Batch 3: New primitives and heavier surfaces
+
+Install or add missing shadcn primitives only after Batch 1 proves the pattern.
+
+- Add `Table` primitives and update `DataTable`; mirror to `frontend/src/components/ui/data-table.tsx` if the sync contract still applies
+- Add `AlertDialog` and replace remaining `window.confirm` calls across issues, peers, and subscriptions
+- Evaluate `Command` for sidebar/global search after preserving current routing, keyboard, and focus behavior
+- Move graph node styles to CSS variables; keep React Flow canvas custom
+
+## Verification
+
+For documentation-only audit updates:
+
+- Read the changed markdown for broken paths and duplicated guidance
+
+For Batch 1 UI changes:
+
+- Run `npm run lint` in `inspector`
+- Run `npm run build` in `inspector`
+- Smoke test `/issues`, `/issues/:number`, `/entities/:id`, and `/settings`
+- Verify keyboard focus and screen reader labels on issue filters, checkboxes, action buttons, and formatted/raw toggles
+
+For Batch 2 and Batch 3:
+
+- Run `npm run lint` and `npm run build` in `inspector`
+- If `DataTable` changes, also inspect `frontend/src/components/ui/data-table.tsx` for required mirror updates
+- Smoke test table-heavy pages: `/entities`, `/observations`, `/sources`, `/relationships`, `/schemas`, `/agents`
+- Smoke test destructive confirmations without completing destructive actions unless using fixture data
+
+## Adoption Rules
+
+- Preserve Inspector as an inspection surface, not an agentic experience
+- Prefer existing local primitives before adding new shadcn files
+- Keep dark mode and `inspector/src/index.css` design tokens intact
+- Avoid replacing semantic `Link` elements with buttons unless the interaction is truly an action
+- Preserve keyboard behavior and ARIA semantics when replacing custom controls
diff --git a/docs/ui/inspector_shadcn_rules.mdc b/docs/ui/inspector_shadcn_rules.mdc
new file mode 100644
index 000000000..9b44a1c11
--- /dev/null
+++ b/docs/ui/inspector_shadcn_rules.mdc
@@ -0,0 +1,78 @@
+---
+description: Enforce shadcn/ui primitives in Inspector UI work; prefer existing inspector components over native HTML controls.
+globs:
+  - inspector/**
+alwaysApply: false
+---
+
+# Inspector shadcn UI Rules
+
+## Purpose
+
+Keep the Inspector app visually and behaviorally consistent with the Neotoma design system by using shadcn/ui-style primitives from `inspector/src/components/ui/` instead of ad hoc native HTML controls and one-off Tailwind patterns.
+
+Inspector is an inspection surface, not a marketing or agentic UI. Prefer consistency, accessibility, and design tokens over decorative variation.
+
+## Canonical references
+
+- `docs/ui/shadcn_components.md` — component inventory and Select vs DropdownMenu guidance
+- `docs/ui/design_system/implementation_notes.md` — prefer shadcn over native HTML, tokens, dark mode, WCAG AA
+- `docs/ui/inspector_shadcn_audit.md` — route-level adoption backlog (if present)
+
+## Installed primitives (`inspector/src/components/ui/`)
+
+Prefer these when they fit the interaction. Do not add new primitives in feature work without a short justification.
+
+**Core (use first):** `Button`, `Input`, `Label`, `Textarea`, `Select`, `Card`, `Badge`, `Separator`, `Dialog`, `Sheet`, `Alert`, `Skeleton`, `Tooltip`, `ScrollArea`, `Tabs`, `Switch`, `DropdownMenu`
+
+**Composites (preserve mirror contract):** `DataTable`, `Pagination`, `ConfirmDialog` — keep in sync with `frontend/src/components/ui/` when editing; see comments in those files.
+
+**Available but often unused in pages:** `Checkbox`, `Popover`, `Toggle`, `ToggleGroup` — use them before inventing custom segmented controls or native checkboxes.
+
+**Not present in Inspector yet (add only with plan):** shadcn `Table` markup inside `DataTable`, `AlertDialog` (prefer `ConfirmDialog` until added), `Command` for search/command palettes.
+
+## MUST
+
+### Control selection
+
+- **MUST** use `Select` from `@/components/ui/select` for single-value dropdowns. **MUST NOT** use native `<select>` (including `agent_filter.tsx` and similar filters).
+- **MUST** use `DropdownMenu` for context menus, column visibility, and action menus — not `Select`.
+- **MUST** use `Button` with appropriate `variant` and `size` instead of raw `<button>` with hand-rolled border/background classes.
+- **MUST** use `Checkbox` + `Label` for boolean row selection and multi-select lists — not native `<input type="checkbox">`.
+- **MUST** use `Textarea` for multi-line text entry — not unstyled native `<textarea>` except where a documented exception applies.
+- **MUST** use `ToggleGroup` / `ToggleGroupItem` for segmented filters (e.g. open/closed/all, formatted/raw) — not custom `role="group"` button clusters unless accessibility requirements cannot be met with shadcn.
+- **MUST** use `Badge` for status, labels, and compact chips — not ad hoc `rounded-full` span pills with hard-coded palette classes.
+- **MUST** use `Alert` or shared `QueryErrorAlert` for errors — not bare `<p className="text-destructive">` alone.
+- **MUST** use `ConfirmDialog` (or `AlertDialog` once added) for destructive confirmations — **MUST NOT** use `window.confirm`.
+
+### Layout and tokens
+
+- **MUST** use design tokens from `inspector/src/index.css` (`--background`, `--foreground`, `--primary`, `--border`, `--muted`, `--destructive`, sidebar/popover tokens, etc.). **MUST NOT** hard-code one-off hex colors for product chrome (graph node styling may use theme-aware variables when touched).
+- **MUST** preserve semantic `<Link>` from `react-router-dom` for navigation; do not replace links with `Button` unless the control is an action, not navigation.
+
+### Data display
+
+- **MUST** use shared `DataTable` for tabular data — do not add parallel raw `<table>` layouts in pages.
+- **MUST** use `Card` / `CardHeader` / `CardContent` for grouped content blocks when replacing hand-built bordered `div` list cards (e.g. sources list, issue rows) unless a feed-specific layout is intentionally feed-only.
+
+## SHOULD
+
+- **SHOULD** use `Sheet` for slide-over detail (markdown preview, large JSON) where a side panel pattern already exists.
+- **SHOULD** use `Skeleton` / shared loading helpers from `components/shared/query_status.tsx` for loading states.
+- **SHOULD** migrate highest-traffic inconsistency surfaces first: `pages/issues.tsx`, `pages/issue_detail.tsx`, `components/shared/agent_filter.tsx`, then segmented controls in `entity_detail.tsx` and `components/shared/inspector_theme_toggle.tsx`.
+
+## MUST NOT
+
+- **MUST NOT** introduce new UI primitives under `inspector/src/components/ui/` without updating `docs/ui/shadcn_components.md` and noting why.
+- **MUST NOT** duplicate full shadcn component source into pages — import from `@/components/ui/*` and `@/lib/utils` (`cn`).
+- **MUST NOT** edit files under `.cursor/rules/` or `.cursor/commands/` — edit this file and run `npm run setup:cursor` (or `./scripts/setup_cursor_copies.sh`).
+
+## Validation
+
+Before marking Inspector UI work complete:
+
+- [ ] No new native `<select>` for product controls in touched files
+- [ ] No new raw `<button>` for primary actions in touched files (except inside shadcn `Button` composition patterns)
+- [ ] Errors and confirmations use shared alert/confirm patterns
+- [ ] `npm run lint` and `npm run build` succeed in `inspector/`
+- [ ] Smoke-test changed routes (especially Issues, Settings, entity detail) in light and dark mode
\ No newline at end of file
diff --git a/scripts/copy-env-to-worktree.js b/scripts/copy-env-to-worktree.js
index 81b174433..4399bc82c 100644
--- a/scripts/copy-env-to-worktree.js
+++ b/scripts/copy-env-to-worktree.js
@@ -38,13 +38,15 @@ function isCursorWorktree(worktreePath) {
 }
 
 function findEnvFile(repoPath) {
-  // Priority: .env.dev, .env, .env.development
+  // Priority: repo-local first, then ~/.config/neotoma fallback
+  const home = process.env.HOME || process.env.USERPROFILE || '';
   const candidates = [
     join(repoPath, '.env.dev'),
     join(repoPath, '.env'),
     join(repoPath, '.env.development'),
+    join(home, '.config', 'neotoma', '.env'),
   ];
-  
+
   for (const candidate of candidates) {
     if (existsSync(candidate)) {
       return candidate;
diff --git a/src/actions.ts b/src/actions.ts
index 04a2c9976..af528d4e9 100644
--- a/src/actions.ts
+++ b/src/actions.ts
@@ -9699,6 +9699,15 @@ export async function startHTTPServer() {
     logger.warn(`[Plans] failed to seed plan schema: ${(err as Error).message}`);
   }
 
+  // Seed `skill` schema (harness-mirrored skills, slash-command palette).
+  try {
+    const { seedSkillSchema } = await import("./services/skills/seed_schema.js");
+    await seedSkillSchema();
+    logger.info("[Skills] skill schema seeded");
+  } catch (err) {
+    logger.warn(`[Skills] failed to seed skill schema: ${(err as Error).message}`);
+  }
+
   try {
     const { seedSubscriptionSchema } = await import("./services/subscriptions/seed_schema.js");
     await seedSubscriptionSchema();
diff --git a/src/services/inspector_mount.ts b/src/services/inspector_mount.ts
index 07fb7b831..56f25fa4e 100644
--- a/src/services/inspector_mount.ts
+++ b/src/services/inspector_mount.ts
@@ -41,19 +41,51 @@ function resolvePackageRoot(): string {
   return dir;
 }
 
+/**
+ * True when index.html references Vite chunks at `/assets/...` (root base) rather
+ * than under the configured mount prefix (e.g. `/inspector/assets/...`).
+ */
+export function inspectorIndexHtmlHasRootAssetRefs(html: string): boolean {
+  return /(?:src|href)=["']\/assets\//.test(html);
+}
+
+/**
+ * Reject dist trees built with `base: /` when the API serves the SPA under a
+ * sub-path (default `/inspector`). Those shells request `/assets/*`, which hit
+ * the authenticated API surface and return 401 JSON — blank Inspector + MIME errors.
+ */
+export function inspectorIndexHtmlMatchesMountBase(html: string, basePath: string): boolean {
+  const normalized = (basePath.trim() || DEFAULT_BASE_PATH).replace(/\/$/, "") || "";
+  if (!normalized || normalized === "/") {
+    return true;
+  }
+  if (inspectorIndexHtmlHasRootAssetRefs(html)) {
+    return false;
+  }
+  const expectedPrefix = `${normalized}/assets/`;
+  return html.includes(expectedPrefix);
+}
+
+function resolveInspectorBasePathFromEnv(env: NodeJS.ProcessEnv): string {
+  const basePath =
+    (env.NEOTOMA_INSPECTOR_BASE_PATH || DEFAULT_BASE_PATH).trim() || DEFAULT_BASE_PATH;
+  return basePath.startsWith("/") ? basePath.replace(/\/$/, "") : `/${basePath}`.replace(/\/$/, "");
+}
+
 /**
  * Resolve the bundled Inspector dist directory. Returns null when the
  * bundled dist is not present (e.g. submodule not built, or SKIP_INSPECTOR_BUILD).
  */
-export function resolveBundledInspectorDir(): string | null {
+export function resolveBundledInspectorDir(env: NodeJS.ProcessEnv = process.env): string | null {
   const root = resolvePackageRoot();
-  const distDir = path.join(root, "dist", "inspector");
-  if (fs.existsSync(path.join(distDir, "index.html"))) return distDir;
-
-  // Source-checkout fallback: inspector/dist when the submodule is built.
-  const submoduleDistDir = path.join(root, "inspector", "dist");
-  if (fs.existsSync(path.join(submoduleDistDir, "index.html"))) return submoduleDistDir;
-
+  const basePath = resolveInspectorBasePathFromEnv(env);
+  const candidates = [path.join(root, "dist", "inspector"), path.join(root, "inspector", "dist")];
+  for (const dir of candidates) {
+    const html = readInspectorIndexHtml(dir);
+    if (!html) continue;
+    if (!inspectorIndexHtmlMatchesMountBase(html, basePath)) continue;
+    return dir;
+  }
   return null;
 }
 
@@ -94,15 +126,28 @@ export function resolveInspectorMount(env: NodeJS.ProcessEnv = process.env): Ins
   return { kind: "disabled", basePath: normalizedBase };
 }
 
+export type InjectInspectorApiBaseMetaOptions = {
+  /** When true, expose dev-only Inspector nav (e.g. /design) via client meta probe. */
+  source_build?: boolean;
+};
+
 /**
- * Inject `<meta name="neotoma-api-base" content="<origin>">` into the
- * Inspector's index.html so the SPA discovers the API origin at runtime.
+ * Inject runtime `<meta>` tags into the Inspector shell:
+ * - `neotoma-api-base` — API origin for same-origin bundled mounts
+ * - `neotoma-inspector-source-build` — optional; monorepo live/source builds only
  */
-export function injectInspectorApiBaseMeta(html: string, origin: string): string {
-  const metaTag = `<meta name="neotoma-api-base" content="${origin}">`;
+export function injectInspectorApiBaseMeta(
+  html: string,
+  origin: string,
+  options: InjectInspectorApiBaseMetaOptions = {}
+): string {
+  const tags = [`<meta name="neotoma-api-base" content="${origin}">`];
+  if (options.source_build) {
+    tags.push('<meta name="neotoma-inspector-source-build" content="1">');
+  }
   const headIdx = html.indexOf("</head>");
   if (headIdx === -1) return html;
-  return html.slice(0, headIdx) + metaTag + "\n" + html.slice(headIdx);
+  return html.slice(0, headIdx) + tags.join("\n") + "\n" + html.slice(headIdx);
 }
 
 /** `stampPath` must be the absolute path (e.g. `/inspector/__live/build_stamp`). */
@@ -237,12 +282,24 @@ export function installInspectorMount(
     staticDir = resolveLiveInspectorStaticDir(staticDir);
   }
 
+  /** Submodule `inspector/dist` fallback is source-checkout only; npm packs use `dist/inspector`. */
+  const injectSourceBuildMeta =
+    inspectorLiveBuild ||
+    staticDir.replace(/\\/g, "/").replace(/\/+$/, "").endsWith("/inspector/dist");
+
   try {
     const rawHtml = readInspectorIndexHtml(staticDir);
     if (!rawHtml) {
       logger.warn(`[Inspector] index.html not found in ${staticDir}; skipping mount.`);
       return;
     }
+    if (!inspectorIndexHtmlMatchesMountBase(rawHtml, basePath)) {
+      logger.warn(
+        `[Inspector] index.html in ${staticDir} was built with root asset paths (/assets/*) but mount base is ${basePath}. ` +
+          `Rebuild with VITE_PUBLIC_BASE_PATH=${basePath}/ (e.g. npm run build:inspector:prod-target). Skipping mount.`
+      );
+      return;
+    }
 
     // Align with Vite non-root base: `/inspector` → `/inspector/` so asset URLs resolve.
     app.use((req, res, next) => {
@@ -355,7 +412,7 @@ export function installInspectorMount(
           const latest = readInspectorIndexHtml(activeStaticDir);
           if (!latest) return next();
           const html = appendInspectorLiveReloadScript(
-            injectInspectorApiBaseMeta(latest, origin),
+            injectInspectorApiBaseMeta(latest, origin, { source_build: injectSourceBuildMeta }),
             buildStampPath
           );
           res.set("Content-Type", "text/html; charset=utf-8");
@@ -366,7 +423,9 @@ export function installInspectorMount(
 
         const latestShell = readInspectorIndexHtml(staticDir);
         if (!latestShell) return next();
-        const html = injectInspectorApiBaseMeta(latestShell, origin);
+        const html = injectInspectorApiBaseMeta(latestShell, origin, {
+          source_build: injectSourceBuildMeta,
+        });
 
         res.set("Content-Type", "text/html; charset=utf-8");
         res.set("Cache-Control", "no-store");
diff --git a/src/services/skills/seed_schema.ts b/src/services/skills/seed_schema.ts
new file mode 100644
index 000000000..ce16cb5e4
--- /dev/null
+++ b/src/services/skills/seed_schema.ts
@@ -0,0 +1,191 @@
+/**
+ * Seed / extend the `skill` entity schema.
+ *
+ * Skills are first-class Neotoma rows that capture reusable agent workflows
+ * invocable from any supported harness (Cursor, Claude Code, etc.). Each skill
+ * has a canonical name, a description that drives trigger matching, a list of
+ * natural-language trigger phrases, and a markdown `content` body containing
+ * the full workflow instructions.
+ *
+ * The mirror profile (`render_mode: "frontmatter_content"`) writes each skill
+ * as a `<name>/SKILL.md` file under the harness skill directory. The
+ * `user_invocable` flag surfaces the skill in the harness slash-command
+ * palette.
+ *
+ * Identity rule: `name` is the canonical identifier — one row per skill name
+ * per user instance.
+ *
+ * Registered as a GLOBAL schema (user_specific: false). Idempotent boot-time
+ * registration — safe to call on every server start.
+ */
+
+import type {
+  FieldDefinition,
+  ReducerConfig,
+  SchemaDefinition,
+  SchemaRegistryEntry,
+} from "../schema_registry.js";
+import { SchemaRegistryService } from "../schema_registry.js";
+
+export const SKILL_ENTITY_TYPE = "skill";
+
+type FieldSpec = Array<{
+  name: string;
+  type: FieldDefinition["type"];
+  required?: boolean;
+  reducer?: "last_write" | "highest_priority" | "most_specific" | "merge_array";
+  description?: string;
+}>;
+
+const SKILL_FIELDS: FieldSpec = [
+  {
+    name: "name",
+    type: "string",
+    required: true,
+    description:
+      "Kebab-case canonical identifier (e.g. import-audio). Used as the subdirectory name in the harness skill directory.",
+  },
+  {
+    name: "description",
+    type: "string",
+    description:
+      "One-sentence description used by the harness to match the skill to user intent and display in the slash-command palette.",
+  },
+  {
+    name: "triggers",
+    type: "array",
+    reducer: "merge_array",
+    description:
+      "Natural-language trigger phrases that activate this skill (e.g. ['import audio', 'transcribe audio from desktop']).",
+  },
+  {
+    name: "content",
+    type: "string",
+    description:
+      "Full markdown workflow body. Rendered as the content section of the SKILL.md file by the mirror profile.",
+  },
+  {
+    name: "slug",
+    type: "string",
+    description:
+      "URL-safe identifier; typically matches `name`. Included for forward-compatibility with index-based lookup.",
+  },
+  {
+    name: "user_invocable",
+    type: "boolean",
+    description:
+      "When true the skill appears in the harness slash-command palette (Claude Code `user_invocable: true` frontmatter field).",
+  },
+  {
+    name: "enabled",
+    type: "boolean",
+    description: "Whether the skill is active. Disabled skills are excluded from mirror output.",
+  },
+  {
+    name: "version",
+    type: "string",
+    description: "Skill content version (semver or free-form). Informational only.",
+  },
+  {
+    name: "supported_harnesses",
+    type: "array",
+    reducer: "merge_array",
+    description:
+      "Harnesses this skill is compatible with (e.g. ['cursor', 'claude-code']). Empty means all.",
+  },
+  {
+    name: "harness_config",
+    type: "object",
+    description:
+      "Per-harness configuration overrides (e.g. { cursor: { triggers: [...] }, claude-code: { description: '...' } }).",
+  },
+  {
+    name: "synced_at",
+    type: "date",
+    description: "Timestamp of the last mirror write or external sync for this skill.",
+  },
+];
+
+function buildSchemaDefinition(): SchemaDefinition {
+  const fields: Record<string, FieldDefinition> = {
+    schema_version: { type: "string", required: true },
+  };
+  for (const spec of SKILL_FIELDS) {
+    fields[spec.name] = {
+      type: spec.type,
+      required: spec.required === true,
+      ...(spec.description ? { description: spec.description } : {}),
+    };
+  }
+  return {
+    fields,
+    canonical_name_fields: ["name"],
+  };
+}
+
+function buildReducerConfig(): ReducerConfig {
+  const merge_policies: ReducerConfig["merge_policies"] = {
+    schema_version: { strategy: "last_write" },
+  };
+  for (const spec of SKILL_FIELDS) {
+    merge_policies[spec.name] = { strategy: spec.reducer ?? "last_write" };
+  }
+  return { merge_policies };
+}
+
+/**
+ * Ensure the global `skill` schema exists and has every field required by
+ * the skill mirror profile and harness integrations.
+ * Safe to call multiple times.
+ */
+export async function seedSkillSchema(options?: {
+  registry?: SchemaRegistryService;
+}): Promise<SchemaRegistryEntry> {
+  const registry = options?.registry ?? new SchemaRegistryService();
+  const existing = await registry.loadGlobalSchema(SKILL_ENTITY_TYPE);
+
+  const definition = buildSchemaDefinition();
+  const reducerConfig = buildReducerConfig();
+
+  if (!existing) {
+    return await registry.register({
+      entity_type: SKILL_ENTITY_TYPE,
+      schema_version: "1.0",
+      schema_definition: definition,
+      reducer_config: reducerConfig,
+      user_specific: false,
+      activate: true,
+      metadata: {
+        label: "Skill",
+        description:
+          "Reusable agent workflow invocable from any supported harness (Cursor, Claude Code, etc.). Each skill has a canonical name, trigger phrases for intent matching, and a markdown content body containing the full workflow instructions. Mirrored to the harness skill directory as <name>/SKILL.md.",
+        category: "productivity",
+      },
+    });
+  }
+
+  const existingFieldNames = new Set(Object.keys(existing.schema_definition.fields ?? {}));
+  const missing = SKILL_FIELDS.filter((spec) => !existingFieldNames.has(spec.name));
+  if (missing.length === 0) return existing;
+
+  return await registry.updateSchemaIncremental({
+    entity_type: SKILL_ENTITY_TYPE,
+    fields_to_add: missing.map((spec) => ({
+      field_name: spec.name,
+      field_type: spec.type,
+      required: spec.required === true,
+      reducer_strategy: spec.reducer ?? "last_write",
+    })),
+    user_specific: false,
+    activate: true,
+    migrate_existing: true,
+  });
+}
+
+export const SKILL_FIELD_SPECS: ReadonlyArray<{
+  name: string;
+  type: FieldDefinition["type"];
+  required?: boolean;
+  reducer?: "last_write" | "highest_priority" | "most_specific" | "merge_array";
+  description?: string;
+}> = SKILL_FIELDS;
diff --git a/src/shared/action_handlers/entity_handlers.ts b/src/shared/action_handlers/entity_handlers.ts
index 27b0a6f3c..d02488455 100644
--- a/src/shared/action_handlers/entity_handlers.ts
+++ b/src/shared/action_handlers/entity_handlers.ts
@@ -4,6 +4,7 @@ import { BOOKKEEPING_ENTITY_TYPES } from "../../services/memory_export.js";
 import { suggestSingular } from "../../services/entity_type_guard.js";
 import { logger } from "../../utils/logger.js";
 import { semanticSearchEntities } from "../../services/entity_semantic_search.js";
+import { isNeotomaEntityId } from "../neotoma_entity_id.js";
 import type { EntityWithProvenance } from "../../services/entity_queries.js";
 
 interface QueryEntitiesParams {
@@ -134,6 +135,27 @@ export function buildEntityTypeFilterTokens(
   return filters;
 }
 
+/**
+ * Multi-word queries often include registered entity type names in titles
+ * (e.g. "Schema Packs Strategy" should match a plan, not filter to strategy rows).
+ * Drop type-filter tokens when removing them still leaves two or more text tokens.
+ */
+export function refineTypeFilterTokens(
+  searchTokens: string[],
+  typeFilterTokens: Set<string>
+): Set<string> {
+  if (typeFilterTokens.size === 0 || searchTokens.length <= 1) {
+    return typeFilterTokens;
+  }
+  const textTokens = searchTokens.filter(
+    (token) => !tokenIsEntityTypeFilter(token, typeFilterTokens)
+  );
+  if (textTokens.length >= 2) {
+    return new Set();
+  }
+  return typeFilterTokens;
+}
+
 /** When the query names an entity type, that token filters by type instead of snapshot text. */
 export function textTokensForEntityMatch(
   searchTokens: string[],
@@ -301,7 +323,10 @@ async function lexicalSearchEntityIds(params: LexicalSearchEntityIdsParams): Pro
   }
 
   const registryTypes = await loadKnownEntityTypes(userId, []);
-  const typeFilterTokens = buildEntityTypeFilterTokens(searchTokens, registryTypes);
+  const typeFilterTokens = refineTypeFilterTokens(
+    searchTokens,
+    buildEntityTypeFilterTokens(searchTokens, registryTypes)
+  );
 
   let entityQuery = db
     .from("entities")
@@ -590,6 +615,80 @@ async function queryEntitiesFromLexicalSearch(params: {
   return { entities, total: lexicalTotal };
 }
 
+type ExactEntityIdQueryParams = Pick<
+  QueryEntitiesParams,
+  | "userId"
+  | "entityType"
+  | "includeMerged"
+  | "includeSnapshots"
+  | "sortBy"
+  | "sortOrder"
+  | "published"
+  | "publishedAfter"
+  | "publishedBefore"
+  | "updatedSince"
+  | "createdSince"
+  | "identityBasis"
+  | "limit"
+  | "offset"
+> & {
+  entityId: string;
+  excludeBookkeeping?: boolean;
+};
+
+/** Direct lookup when the search string is a full Neotoma entity id (`ent_` + 24 hex). */
+export async function queryEntitiesByExactEntityId(
+  params: ExactEntityIdQueryParams
+): Promise<{ entities: EntityWithProvenance[]; total: number }> {
+  const entityId = params.entityId.trim();
+  const limit = params.limit ?? 100;
+  const offset = params.offset ?? 0;
+
+  let rowQuery = db
+    .from("entities")
+    .select("id, entity_type")
+    .eq("user_id", params.userId)
+    .eq("id", entityId);
+
+  if (params.entityType) {
+    rowQuery = rowQuery.eq("entity_type", params.entityType);
+  }
+  if (!params.includeMerged) {
+    rowQuery = rowQuery.is("merged_to_entity_id", null);
+  }
+
+  const { data: row, error: rowError } = await rowQuery.maybeSingle();
+  if (rowError) {
+    throw new Error(`Failed exact entity id lookup: ${rowError.message}`);
+  }
+  if (!row) {
+    return { entities: [], total: 0 };
+  }
+  if (params.excludeBookkeeping && BOOKKEEPING_ENTITY_TYPES.has(row.entity_type)) {
+    return { entities: [], total: 0 };
+  }
+
+  const entities = await queryEntities({
+    userId: params.userId,
+    entityType: params.entityType,
+    includeMerged: params.includeMerged,
+    includeSnapshots: params.includeSnapshots,
+    sortBy: params.sortBy,
+    sortOrder: params.sortOrder,
+    published: params.published,
+    publishedAfter: params.publishedAfter,
+    publishedBefore: params.publishedBefore,
+    limit,
+    offset,
+    entityIds: [entityId],
+    updatedSince: params.updatedSince,
+    createdSince: params.createdSince,
+    identityBasis: params.identityBasis,
+  });
+
+  return { entities, total: entities.length > 0 ? 1 : 0 };
+}
+
 export async function queryEntitiesWithCount(params: QueryEntitiesParams): Promise<{
   entities: EntityWithProvenance[];
   total: number;
@@ -619,11 +718,40 @@ export async function queryEntitiesWithCount(params: QueryEntitiesParams): Promi
 
   if (search && search.trim()) {
     const trimmedSearch = search.trim();
-    const searchTokens = normalizeSearchText(trimmedSearch).split(" ").filter(Boolean);
-    const registryTypes = await loadKnownEntityTypes(userId, []);
-    const typeFilterTokens = buildEntityTypeFilterTokens(searchTokens, registryTypes);
     const excludeBookkeeping = shouldExcludeBookkeepingFromSearch(entityType);
 
+    if (isNeotomaEntityId(trimmedSearch)) {
+      const exactResult = await queryEntitiesByExactEntityId({
+        userId,
+        entityId: trimmedSearch,
+        entityType,
+        includeMerged,
+        includeSnapshots,
+        sortBy,
+        sortOrder,
+        published,
+        publishedAfter,
+        publishedBefore,
+        updatedSince,
+        createdSince,
+        identityBasis,
+        limit,
+        offset,
+        excludeBookkeeping,
+      });
+      return {
+        entities: exactResult.entities,
+        total: exactResult.total,
+        excluded_merged: !includeMerged,
+      };
+    }
+
+    const searchTokens = normalizeSearchText(trimmedSearch).split(" ").filter(Boolean);
+    const registryTypes = await loadKnownEntityTypes(userId, []);
+    const typeFilterTokens = refineTypeFilterTokens(
+      searchTokens,
+      buildEntityTypeFilterTokens(searchTokens, registryTypes)
+    );
     const lexicalParams = {
       userId,
       entityType,
diff --git a/tests/integration/inspector_bundled_mount.test.ts b/tests/integration/inspector_bundled_mount.test.ts
index df7f2339c..8ad37fe53 100644
--- a/tests/integration/inspector_bundled_mount.test.ts
+++ b/tests/integration/inspector_bundled_mount.test.ts
@@ -21,11 +21,18 @@ import {
   computeInspectorBuildOutputStamp,
   isInspectorViteAssetUrlPath,
   normalizeInspectorUrlPathname,
+  inspectorIndexHtmlHasRootAssetRefs,
+  inspectorIndexHtmlMatchesMountBase,
 } from "../../src/services/inspector_mount.js";
 
 type Server = ReturnType<express.Application["listen"]>;
 
-const FIXTURE_HTML = `<!DOCTYPE html><html><head><title>Inspector</title></head><body>OK</body></html>`;
+function fixtureInspectorHtml(basePath = "/inspector"): string {
+  const base = (basePath.trim() || "/inspector").replace(/\/$/, "");
+  return `<!DOCTYPE html><html><head><title>Inspector</title><script src="${base}/assets/index.js"></script><link href="${base}/assets/index.css" rel="stylesheet"></head><body>OK</body></html>`;
+}
+
+const FIXTURE_HTML = fixtureInspectorHtml("/inspector");
 
 function noopLogger() {
   return { info: () => {}, warn: () => {} };
@@ -75,6 +82,25 @@ describe("isInspectorViteAssetUrlPath", () => {
   });
 });
 
+describe("inspectorIndexHtmlMatchesMountBase", () => {
+  const rootBaseHtml = `<script src="/assets/index.js"></script><link href="/assets/index.css">`;
+  const inspectorBaseHtml = `<script src="/inspector/assets/index.js"></script>`;
+
+  it("detects root /assets/ references", () => {
+    expect(inspectorIndexHtmlHasRootAssetRefs(rootBaseHtml)).toBe(true);
+    expect(inspectorIndexHtmlHasRootAssetRefs(inspectorBaseHtml)).toBe(false);
+  });
+
+  it("rejects root-base HTML when mount is /inspector", () => {
+    expect(inspectorIndexHtmlMatchesMountBase(rootBaseHtml, "/inspector")).toBe(false);
+    expect(inspectorIndexHtmlMatchesMountBase(inspectorBaseHtml, "/inspector")).toBe(true);
+  });
+
+  it("accepts root-base HTML when mount is /", () => {
+    expect(inspectorIndexHtmlMatchesMountBase(rootBaseHtml, "/")).toBe(true);
+  });
+});
+
 describe("resolveInspectorMount", () => {
   it("returns disabled when NEOTOMA_INSPECTOR_DISABLE=1", () => {
     const cfg = resolveInspectorMount(
@@ -170,6 +196,13 @@ describe("injectInspectorApiBaseMeta", () => {
     expect(result.indexOf("neotoma-api-base")).toBeLessThan(result.indexOf("</head>"));
   });
 
+  it("injects source-build meta when requested", () => {
+    const result = injectInspectorApiBaseMeta(FIXTURE_HTML, "http://localhost:3080", {
+      source_build: true,
+    });
+    expect(result).toContain('<meta name="neotoma-inspector-source-build" content="1">');
+  });
+
   it("returns unchanged HTML when </head> is missing", () => {
     const noHead = "<html><body>hi</body></html>";
     expect(injectInspectorApiBaseMeta(noHead, "http://x")).toBe(noHead);
@@ -388,7 +421,7 @@ describe("installInspectorMount — integration", () => {
   it("respects custom base path", async () => {
     tmpDir = path.join(process.cwd(), "tmp", "inspector-test-path-" + Date.now());
     mkdirSync(tmpDir, { recursive: true });
-    writeFileSync(path.join(tmpDir, "index.html"), FIXTURE_HTML);
+    writeFileSync(path.join(tmpDir, "index.html"), fixtureInspectorHtml("/ui"));
 
     const app = express();
     installInspectorMount(
diff --git a/tests/integration/lexical_search.test.ts b/tests/integration/lexical_search.test.ts
index 9ee099830..af007e45c 100644
--- a/tests/integration/lexical_search.test.ts
+++ b/tests/integration/lexical_search.test.ts
@@ -168,6 +168,29 @@ describe("Lexical retrieval fallback", () => {
     expect(result.entities.some((entity) => entity.entity_id === targetEntityId)).toBe(true);
   });
 
+  it("matches plan titles that end with a registered entity type name", async () => {
+    const entityId = `ent_lex_plan_strategy_title_${Date.now()}`;
+    await createEntityWithSnapshot({
+      id: entityId,
+      entityType: "plan",
+      canonicalName: "plan:Schema Packs Strategy",
+      snapshot: {
+        title: "Schema Packs Strategy",
+        status: "pending",
+      },
+    });
+
+    const result = await queryEntitiesWithCount({
+      userId: testUserId,
+      search: "Schema Packs Strategy",
+      limit: 25,
+      offset: 0,
+    });
+
+    expect(result.total).toBeGreaterThanOrEqual(1);
+    expect(result.entities.some((entity) => entity.entity_id === entityId)).toBe(true);
+  });
+
   it("ranks cross-type lexical matches deterministically without entity_type filter", async () => {
     const runId = Date.now();
     const canonicalFirstId = `ent_lex_rank_canonical_${runId}`;
@@ -199,4 +222,39 @@ describe("Lexical retrieval fallback", () => {
     expect(ids).toContain(snapshotFirstId);
     expect(ids.indexOf(canonicalFirstId)).toBeLessThan(ids.indexOf(snapshotFirstId));
   });
+
+  it("resolves a full entity id search string to that entity", async () => {
+    const entityId = `ent_${Date.now().toString(16).padStart(24, "0").slice(-24)}`;
+    await createEntityWithSnapshot({
+      id: entityId,
+      entityType: "note",
+      canonicalName: "id lookup fixture",
+      snapshot: { title: "Unrelated title for lexical mismatch" },
+    });
+
+    const result = await queryEntitiesWithCount({
+      userId: testUserId,
+      search: entityId,
+      limit: 25,
+      offset: 0,
+    });
+
+    expect(result.total).toBe(1);
+    expect(result.entities).toHaveLength(1);
+    expect(result.entities[0]?.entity_id).toBe(entityId);
+  });
+
+  it("returns no rows when a full entity id does not exist for the user", async () => {
+    const missingId = "ent_000000000000000000000000";
+
+    const result = await queryEntitiesWithCount({
+      userId: testUserId,
+      search: missingId,
+      limit: 25,
+      offset: 0,
+    });
+
+    expect(result.total).toBe(0);
+    expect(result.entities).toHaveLength(0);
+  });
 });
diff --git a/tests/unit/entity_search_type_boost.test.ts b/tests/unit/entity_search_type_boost.test.ts
new file mode 100644
index 000000000..5980e39ab
--- /dev/null
+++ b/tests/unit/entity_search_type_boost.test.ts
@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+import {
+  ENTITY_TYPE_KEYWORD_BOOST,
+  buildEntityLexicalSearchText,
+  buildEntityTypeFilterTokens,
+  entityTypeKeywordBoost,
+  refineTypeFilterTokens,
+  searchTokenMatchesEntityType,
+  shouldExcludeBookkeepingFromSearch,
+  textTokensForEntityMatch,
+} from "../../src/shared/action_handlers/entity_handlers.js";
+
+describe("entity search entity_type keyword boost", () => {
+  it("matches entity_type token exactly", () => {
+    expect(searchTokenMatchesEntityType("plan", "plan")).toBe(true);
+    expect(entityTypeKeywordBoost("plan", ["aibtc", "plan"])).toBe(ENTITY_TYPE_KEYWORD_BOOST);
+  });
+
+  it("matches conventional plural tokens to singular entity types", () => {
+    expect(searchTokenMatchesEntityType("plans", "plan")).toBe(true);
+    expect(entityTypeKeywordBoost("plan", ["aibtc", "plans"])).toBe(ENTITY_TYPE_KEYWORD_BOOST);
+  });
+
+  it("does not boost unrelated types", () => {
+    expect(entityTypeKeywordBoost("note", ["aibtc", "plan"])).toBe(0);
+    expect(searchTokenMatchesEntityType("plan", "note")).toBe(false);
+  });
+
+  it("includes raw fragment text in lexical haystack", () => {
+    const haystack = buildEntityLexicalSearchText(
+      "plan:Agent Swarm Testing Plan",
+      { title: "Agent Swarm Testing Plan", status: "planning" },
+      "networks AIBTC primary network"
+    );
+    expect(haystack).toContain("aibtc");
+    expect(haystack).toContain("agent swarm testing plan");
+  });
+
+  it("excludes bookkeeping from unscoped search but not when type is explicit", () => {
+    expect(shouldExcludeBookkeepingFromSearch()).toBe(true);
+    expect(shouldExcludeBookkeepingFromSearch("plan")).toBe(true);
+    expect(shouldExcludeBookkeepingFromSearch("conversation_message")).toBe(false);
+  });
+
+  it("treats entity_type tokens as type filters for matching rows", () => {
+    const knownTypes = new Set(["plan", "note"]);
+    const typeFilters = buildEntityTypeFilterTokens(["aibtc", "plan"], knownTypes);
+    expect([...typeFilters]).toEqual(["plan"]);
+    expect(textTokensForEntityMatch(["aibtc", "plan"], "plan", typeFilters)).toEqual(["aibtc"]);
+    expect(textTokensForEntityMatch(["aibtc", "plan"], "note", typeFilters)).toEqual([
+      "aibtc",
+      "plan",
+    ]);
+  });
+
+  it("does not treat trailing entity type names in multi-word titles as type filters", () => {
+    const knownTypes = new Set(["plan", "strategy"]);
+    const rawFilters = buildEntityTypeFilterTokens(
+      ["schema", "packs", "strategy"],
+      knownTypes
+    );
+    expect([...rawFilters]).toEqual(["strategy"]);
+    expect([...refineTypeFilterTokens(["schema", "packs", "strategy"], rawFilters)]).toEqual([]);
+  });
+
+  it("keeps type filters for short qualifier queries like aibtc plan", () => {
+    const knownTypes = new Set(["plan", "strategy"]);
+    const rawFilters = buildEntityTypeFilterTokens(["aibtc", "plan"], knownTypes);
+    expect([...refineTypeFilterTokens(["aibtc", "plan"], rawFilters)]).toEqual(["plan"]);
+  });
+});