neotoma 0.3.0 → 0.3.2

package/.cursor/plans/automated_error_debugging_localhost_clarified.plan.md

@@ -1,510 +0,0 @@
-# Automated Error Debugging for Localhost
-
-Set up automated error debugging that automatically debugs and fixes errors when they're reported, running fully automatically unless human intervention is required due to unclear design needs.
-
-## Clarification: Technology Stack
-
-**This implementation uses:**
-- ✅ **Local Node.js file system watcher** - Pure Node.js script that monitors files
-- ✅ **Existing Cursor commands** - Uses `/debug_pending_errors` and `/fix_feature_bug` commands
-- ✅ **No Cloud Agents** - Runs entirely locally on your machine
-- ✅ **No Claude Code** - Uses Cursor's built-in command system
-
-**If you want Cloud Agents or Claude Code instead, those require different implementations (see alternatives below).**
-
-## Three Approaches Comparison
-
-### Option 1: Local File System Watcher (RECOMMENDED - This Plan)
-**What it is:** A Node.js script that watches `.cursor/error_reports/pending.json` and automatically runs the debug workflow when errors are added.
-
-**Technology:** Pure Node.js (fs.watch), uses existing Cursor commands
-**Cloud Agents:** ❌ No
-**Claude Code:** ❌ No
-
-**Pros:**
-- ✅ Fast response (triggers immediately when errors added)
-- ✅ Low overhead (only active when files change)
-- ✅ No subscription required
-- ✅ Works completely locally on your machine
-- ✅ Uses existing debug_pending_errors command
-- ✅ No external dependencies beyond Node.js
-
-**Cons:**
-- ❌ Runs only when script is active (needs to be started)
-- ❌ Uses your local resources
-
-### Option 2: Cursor Cloud Agents (Alternative - Not This Plan)
-**What it is:** Use Cursor's Cloud Agents API to spawn background agents that process error queue remotely.
-
-**Technology:** Cursor Cloud Agents API (remote background agents)
-**Cloud Agents:** ✅ Yes (required)
-**Claude Code:** ❌ No
-
-**Pros:**
-- ✅ Runs in background automatically
-- ✅ Doesn't consume local resources
-- ✅ Can run even when your machine is off (if repo is accessible)
-
-**Cons:**
-- ❌ Requires Cursor Cloud subscription with Background Agents enabled
-- ❌ Requires API credentials (CURSOR_CLOUD_API_URL, CURSOR_CLOUD_API_KEY)
-- ❌ More complex setup (API integration)
-- ❌ Runs remotely, not truly "localhost"
-- ❌ Need to configure repo access
-
-### Option 3: Claude Code Integration (Alternative - Not This Plan)
-**What it is:** Use Anthropic's Claude Code CLI to process errors via Claude Code commands.
-
-**Technology:** Claude Code CLI (Anthropic's tool)
-**Cloud Agents:** ❌ No
-**Claude Code:** ✅ Yes (required)
-
-**Pros:**
-- ✅ Uses Claude's code understanding capabilities
-- ✅ Separate tool from Cursor (independent)
-
-**Cons:**
-- ❌ Requires Claude Code installation and setup
-- ❌ Need to build integration with error reporting system
-- ❌ Additional tool to maintain
-- ❌ Not as tightly integrated with Cursor
-
-## Recommendation: Option 1 - Local File System Watcher
-
-**This plan implements Option 1 because:**
-- It's the simplest and most direct solution
-- Works entirely on localhost as requested
-- No subscription or external dependencies
-- Integrates cleanly with existing commands
-- Uses your existing Cursor setup (no new tools)
-
-**To use Cloud Agents or Claude Code instead**, you would need a different implementation (see alternatives section below).
-
-## Implementation Plan (Hybrid Automation - Option A)
-
-**This plan implements Option A (Hybrid):** Automates infrastructure fixes, logs code bugs for review.
-
-### 1. Create Watcher Script
-
-**File:** `scripts/watch_error_reports.js`
-
-- Monitor `.cursor/error_reports/pending.json` for changes using Node.js `fs.watch`
-- When changes detected, execute debug workflow automatically
-- Use existing `debug_pending_errors` command logic (via --auto flag)
-- Log all actions for audit trail
-
-### 2. Implement Hybrid Debug Logic
-
-- Create `scripts/debug_error_reports.js` with automated fix logic
-- **Automatic fixes (no AI needed):**
-  - Database migrations: Run `npm run migrate` if table missing
-  - Missing directories: Create `.cursor/error_reports/` if needed
-  - Configuration: Check env vars, suggest fixes
-  - Simple file operations: Create missing files, update configs
-- **Code bugs (requires AI):**
-  - Log to `.cursor/error_reports/needs_ai_review.json`
-  - Include error details and affected files
-  - You review these in Cursor and run `/debug_pending_errors` manually
-- No AI API calls - pure automation for infrastructure, logging for code bugs
-
-### 3. Startup Script
-
-**File:** `scripts/start_error_watcher.js` (or npm script)
-
-- Start file watcher in background
-- Handle graceful shutdown (Ctrl+C)
-- Restart on crashes (optional)
-- Log watcher status
-
-### 4. Configuration
-
-**Add to `foundation-config.yaml`:**
-
-```yaml
-development:
-  error_debugging:
-    enabled: true
-    auto_select_highest_priority: true
-    require_confirmation: false  # Auto-mode
-    integrate_fix_feature_bug: true
-    auto_archive_resolved: true
-    watcher:
-      enabled: true
-      watch_file: ".cursor/error_reports/pending.json"
-      debounce_ms: 1000  # Wait 1s after file change before processing
-      auto_mode: true
-```
-
-### 5. npm Scripts
-
-**Add to `package.json`:**
-
-```json
-{
-  "scripts": {
-    "watch:errors": "node scripts/watch_error_reports.js",
-    "watch:errors:background": "node scripts/watch_error_reports.js > .cursor/error_watcher.log 2>&1 &"
-  }
-}
-```
-
-## Important: The AI Question
-
-**Which AI is actually debugging?**
-
-This is a critical question. The file watcher is just a Node.js script - it can't reason about code or write fixes. Here are the realistic options:
-
-### Option A: Hybrid Automation (RECOMMENDED)
-**What:** Watcher automates infrastructure fixes only, flags code bugs for manual AI review
-
-**Handles automatically:**
-- ✅ Database migrations (`npm run migrate`)
-- ✅ Missing configuration files
-- ✅ Simple file/directory creation
-- ✅ Running tests to verify fixes
-
-**Requires AI (logged for review):**
-- ❌ Code bugs requiring reasoning
-- ❌ Schema/architecture decisions
-- ❌ Complex logic fixes
-
-**AI Used:** None (just automation) + You review flagged items in Cursor
-
-### Option B: Direct AI API Integration
-**What:** Watcher calls OpenAI/Anthropic API directly to analyze and fix bugs
-
-**Handles automatically:**
-- ✅ Code analysis via AI API
-- ✅ Bug fixes generated by AI
-- ✅ Code changes written programmatically
-
-**AI Used:** OpenAI API or Anthropic API (direct API calls, bypassing Cursor)
-
-**Requirements:**
-- API keys for OpenAI/Anthropic
-- Implement code analysis and fix generation
-- Git operations to apply fixes
-
-### Option C: Cursor Agent Triggering (Doesn't Work)
-**What:** Watcher somehow triggers Cursor agents/commands
-
-**Problem:** Cursor commands require active chat sessions - a Node.js script can't create these.
-
-### Recommendation: Option A (Hybrid)
-
-For localhost automation, **Option A is most practical:**
-- Handles the 80% of errors that are infrastructure/configuration issues
-- Logs code bugs that need AI reasoning
-- You review flagged items in Cursor when needed
-- Simple, reliable, no API dependencies
-
-If you want full AI automation, **Option B** requires implementing AI API integration (more complex).
-
-## File System Watcher Implementation
-
-```javascript
-// scripts/watch_error_reports.js
-const fs = require('fs');
-const path = require('path');
-
-const WATCH_FILE = '.cursor/error_reports/pending.json';
-const DEBOUNCE_MS = 1000;
-const REPO_ROOT = process.cwd();
-
-let debounceTimer = null;
-let isProcessing = false;
-
-async function processPendingErrors() {
-  if (isProcessing) {
-    console.log('[WATCHER] Already processing errors, skipping...');
-    return;
-  }
-
-  isProcessing = true;
-  console.log('[WATCHER] Detected change in pending.json, processing errors...');
-
-  try {
-    // Read pending.json
-    const pendingPath = path.join(REPO_ROOT, WATCH_FILE);
-    const pending = JSON.parse(fs.readFileSync(pendingPath, 'utf8'));
-    
-    if (pending.length === 0) {
-      console.log('[WATCHER] No pending errors');
-      isProcessing = false;
-      return;
-    }
-
-    // Extract and run debug logic directly (not via Cursor command)
-    // This requires implementing the debug workflow as a Node.js function
-    // See "Extracted Debug Logic" section below
-    
-    await debugPendingErrors(pending, { auto: true });
-    
-  } catch (error) {
-    console.error('[WATCHER] Error processing:', error);
-  } finally {
-    isProcessing = false;
-  }
-}
-
-// Watch for file changes
-if (!fs.existsSync(WATCH_FILE)) {
-  console.log(`[WATCHER] Warning: ${WATCH_FILE} does not exist. Creating it...`);
-  fs.writeFileSync(WATCH_FILE, '[]', 'utf8');
-}
-
-fs.watch(WATCH_FILE, (eventType) => {
-  if (eventType === 'change') {
-    // Debounce: wait for file write to complete
-    clearTimeout(debounceTimer);
-    debounceTimer = setTimeout(processPendingErrors, DEBOUNCE_MS);
-  }
-});
-
-console.log(`[WATCHER] Monitoring ${path.resolve(WATCH_FILE)} for changes...`);
-console.log('[WATCHER] Press Ctrl+C to stop');
-```
-
-## Automated Fix Logic (Hybrid Approach)
-
-**File:** `scripts/debug_error_reports.js` (NEW - automated fixes only)
-
-This file implements automated fixes for infrastructure errors, logs code bugs for AI review:
-
-```javascript
-// scripts/debug_error_reports.js
-async function processErrorAuto(errorReport) {
-  const category = errorReport.category;
-  const message = errorReport.error_message;
-
-  // Infrastructure fixes (automatic, no AI)
-  if (category === 'runtime' && message.includes('table') && message.includes('not found')) {
-    // Database migration needed
-    console.log('[AUTO] Running database migrations...');
-    await exec('npm run migrate');
-    return { fixed: true, method: 'migration' };
-  }
-
-  if (category === 'configuration' && message.includes('missing env')) {
-    // Check .env file, suggest fix
-    console.log('[AUTO] Configuration issue detected - logged for review');
-    return { fixed: false, needs_review: true };
-  }
-
-  // Code bugs require AI - log for manual review
-  if (category === 'build' || (category === 'runtime' && !canFixAutomatically(message))) {
-    await logForAIReview(errorReport);
-    return { fixed: false, needs_ai_review: true };
-  }
-
-  return { fixed: false, reason: 'requires_ai' };
-}
-
-async function logForAIReview(errorReport) {
-  // Append to review queue
-  const reviewFile = '.cursor/error_reports/needs_ai_review.json';
-  // ... log error for manual review in Cursor
-}
-
-module.exports = { processErrorAuto };
-```
-
-**Key Point:** This handles infrastructure only. Code bugs are logged for you to fix in Cursor with `/debug_pending_errors`.
-
-## Alternative Approaches (Not Implemented in This Plan)
-
-### If You Want Cloud Agents Instead
-
-This would require a different implementation:
-
-1. **Setup:**
-   ```bash
-   export CURSOR_CLOUD_API_URL="https://api.cursor.com/v1"
-   export CURSOR_CLOUD_API_KEY="your_api_key_here"
-   ```
-
-2. **Create script to spawn agents:**
-   ```javascript
-   // scripts/spawn_error_debug_agent.js
-   const response = await fetch(`${process.env.CURSOR_CLOUD_API_URL}/v0/agents`, {
-     method: 'POST',
-     headers: { 
-       'Authorization': `Bearer ${process.env.CURSOR_CLOUD_API_KEY}`,
-       'Content-Type': 'application/json'
-     },
-     body: JSON.stringify({
-       instruction: 'Run /debug_pending_errors --auto for repository',
-       repo_url: process.env.REPO_URL || 'https://github.com/your-org/neotoma'
-     })
-   });
-   ```
-
-3. **Differences:**
-   - Requires Cursor Cloud subscription
-   - Agents run remotely, not on localhost
-   - More complex setup
-   - Different architecture (API-based vs file watcher)
-
-**This plan does NOT implement Cloud Agents - it uses local file watcher.**
-
-### If You Want Claude Code Instead
-
-This would require a different implementation:
-
-1. **Install Claude Code:**
-   ```bash
-   npm install -g @anthropic-ai/claude-code
-   ```
-
-2. **Create integration script:**
-   ```javascript
-   // scripts/claude_debug_errors.js
-   const { exec } = require('child_process');
-   // Use Claude Code CLI to process errors
-   // Would need to format error reports for Claude Code
-   ```
-
-3. **Differences:**
-   - Requires Claude Code installation
-   - Uses Claude's AI instead of Cursor's commands
-   - Less integrated with Cursor ecosystem
-   - Different tooling stack
-
-**This plan does NOT implement Claude Code - it uses Cursor commands directly.**
-
-## Human Intervention Points
-
-Auto-mode should only stop for human input when:
-
-1. **Unclear design needs:**
-   - Schema conflicts require architectural decision
-   - Multiple valid fix approaches need selection
-   - Missing context/documentation for proper fix
-
-2. **Security-sensitive changes:**
-   - Credential handling
-   - Permission changes
-   - Security policy updates
-
-3. **Breaking changes:**
-   - API contract changes
-   - Database schema migrations (for production)
-   - Behavioral changes affecting other systems
-
-4. **Configuration required:**
-   - Missing environment variables
-   - External service configuration
-   - User-specific settings
-
-## Integration Points
-
-### With debug_pending_errors Command (Documentation)
-
-- The Cursor command (`/debug_pending_errors`) uses the same logic as the extracted function
-- Both share the same workflow (sort, select, fix, archive)
-- Command is for manual/interactive use, extracted function is for automation
-
-### With fix_feature_bug Logic (Extracted)
-
-- Extract `fix_feature_bug` workflow into callable Node.js functions
-- Automatically classifies and fixes bugs
-- Logs when human intervention needed (doesn't stop execution)
-- All actions logged for review
-
-### With git hooks (Optional Enhancement)
-
-- Pre-commit hook: Check for pending errors before commit
-- Post-merge hook: Process errors after pulling changes
-
-## Startup Options
-
-### Option 1: Manual Start
-```bash
-npm run watch:errors
-```
-
-### Option 2: Background Process
-```bash
-npm run watch:errors:background
-# Check logs: tail -f .cursor/error_watcher.log
-```
-
-### Option 3: Auto-start with Dev Server
-Integrate into `npm run dev` to start watcher automatically
-
-## Monitoring & Logging
-
-- Log all processed errors to `.cursor/error_watcher.log`
-- Include timestamps, error IDs, resolution status
-- Alert on repeated failures
-- Summary stats (errors processed, fixed, failed)
-
-## Error Handling
-
-- Handle file read errors gracefully
-- Skip invalid JSON in pending.json
-- Continue processing if one error fails
-- Retry failed fixes after delay
-
-## Testing
-
-1. Create test error report
-2. Verify watcher detects change
-3. Verify auto-debug runs
-4. Verify error archived after fix
-5. Verify logs created
-
-## Files to Create
-
-1. `scripts/watch_error_reports.js` - Main watcher script
-2. `scripts/debug_error_reports.js` - Extracted debug logic (if needed, to make it callable)
-3. Update `package.json` - Add npm scripts
-4. Update `foundation-config.yaml` - Add watcher config
-5. `.cursor/error_watcher.log` - Log file (gitignored)
-
-## Files to Modify
-
-1. `foundation/agent_instructions/cursor_commands/debug_pending_errors.md` - Document auto-mode integration
-2. `docs/developer/getting_started.md` - Document watcher setup
-3. `.gitignore` - Add error_watcher.log
-
-## Configuration Options
-
-```yaml
-development:
-  error_debugging:
-    watcher:
-      enabled: true  # Enable/disable watcher
-      watch_file: ".cursor/error_reports/pending.json"
-      debounce_ms: 1000  # Delay before processing (ms)
-      auto_mode: true  # Run with --auto flag
-      stop_on_human_intervention: true  # Pause when human input needed
-      max_concurrent: 1  # Process one error at a time
-      retry_failed: true  # Retry failed fixes
-      retry_delay_ms: 5000  # Delay before retry
-      log_file: ".cursor/error_watcher.log"
-```
-
-## Summary
-
-**This plan implements:** Local Node.js file system watcher with hybrid automation
-**AI Used:** None (just automation) - you review code bugs in Cursor
-**Automatically fixes:** Infrastructure issues (migrations, config, files)
-**Logs for review:** Code bugs requiring AI reasoning
-**Does NOT use:** Cursor Cloud Agents, Claude Code, or AI APIs
-**Does NOT trigger:** Cursor commands or chat sessions automatically
-**Runs on:** Your localhost machine as a background script
-
-**How it works:**
-1. Watcher monitors pending.json
-2. For infrastructure errors → fixes automatically (migrations, configs)
-3. For code bugs → logs to `needs_ai_review.json`
-4. You review logged items in Cursor and run `/debug_pending_errors` manually
-
-**If you want full AI automation** (Option B), that requires:
-- OpenAI/Anthropic API integration
-- Code analysis and fix generation
-- More complex implementation
-
-**This plan is simpler:** Handles the 80% of errors that are infrastructure issues, logs the rest for manual AI review.
-

package/.cursor/plans/bug_report_and_contribution_client_guidance.plan.md

@@ -1,143 +0,0 @@
----
-name: ""
-overview: ""
-todos: []
-isProject: false
----
-
-# Bug report and contribution instructions in client guidance
-
-## Recommendation
-
-**Yes.** Add structured steps for (A) reporting bugs and (B) contributing fixes. Prefer (B) when the agent has access to a full Neotoma repo or fork (current workspace or another path with permission); otherwise do (A).
-
-## Scope and placement
-
-- **Files to update (parity required):**
-  - [docs/developer/mcp/instructions.md](docs/developer/mcp/instructions.md) — plain-text instruction block sent to MCP clients
-  - [docs/developer/cli_agent_instructions.md](docs/developer/cli_agent_instructions.md) — CLI rule content and any new section
-- **Sync rule:** [docs/developer/agent_instructions_sync_rules.mdc](docs/developer/agent_instructions_sync_rules.mdc) — add a new row to the "Behavioral Sections That Must Stay in Parity" table for "Bug report / contribute fix".
-- **Reference only (no change):** [CONTRIBUTING.md](CONTRIBUTING.md), [docs/templates/issue_template.md](docs/templates/issue_template.md), [docs/developer/development_workflow.md](docs/developer/development_workflow.md).
-
-## Trigger conditions (when to apply automatically)
-
-Encode so the agent **proactively** applies the bug-report or contribute-fix flow based on recent context. Do not wait for the user to say "report this bug" or "fix this."
-
-**Apply when either:**
-
-1. **Errors or failures in recent context**
-
-- A Neotoma-related error was thrown or appears in output (stack trace, error message, failed MCP tool result, non-zero exit from a `neotoma` CLI command).
-- A command or tool call that uses Neotoma (store, entities, schemas, API, etc.) failed or returned an error envelope.
-- Tests failed in a Neotoma repo (e.g. `npm test` or integration tests) and the failure points to Neotoma code.
-
-1. **User is discussing or reporting a bug**
-
-- User describes something not working, an error they saw, or unexpected behavior with Neotoma.
-- User asks why something failed or mentions a possible bug in Neotoma.
-- User says they want to report a bug or contribute a fix.
-
-**Instruction wording:** Start the bug-report/contribute section with a line like: "When recent context shows a Neotoma error (thrown error, failed MCP/CLI call, stack trace, test failure) or the user describes or discusses a Neotoma bug, apply the flow below immediately—report (Option A) or contribute fix (Option B) as applicable; do not wait for the user to ask."
-
-## When Option B works vs Option A only
-
-- **Option B (contribute fix)** works when the agent has access to **a directory that is a full clone or fork of the Neotoma repo** — whether that is the current workspace or another path the user allows (e.g. "use `~/repos/neotoma`"). The agent can work outside the current workspace if given permission (read/write by path, run commands in that directory). Require that the directory has `.git`, tests, and dev scripts (full repo), not just installed package code.
-- **Option A only** when:
-  - The only Neotoma code visible is the **global npm install** path (e.g. `npm root -g` / packaged `neotoma`). That path is not a full repo (no `.git`, often no tests/scripts), so the agent cannot run tests or create a branch/PR from there. Do not attempt to patch there; report the bug (Option A) and tell the user: "To contribute a fix, clone or fork the repo, open that folder (or give me access to it), and we can do the fix and PR from there."
-  - The user only wants to report, or the agent cannot push (no fork, no auth).
-
-## Option A: Report bug to GitHub
-
-**Steps to encode:**
-
-1. **Collect:** Repro steps, environment (OS, Neotoma version, CLI vs MCP, global vs local install), exact error message or unexpected behavior.
-2. **Create issue:**
-
-- **Preferred:** If `gh` is available and authenticated, run `gh issue create --repo markmhendrickson/neotoma --title "Brief description" --body "…"` (body can follow [docs/templates/issue_template.md](docs/templates/issue_template.md)).
-- **Fallback:** Provide the user a link to `https://github.com/markmhendrickson/neotoma/issues/new` and a pre-filled body so they can paste and submit.
-
-## Option B: Patch, verify, fork, PR (preferred when applicable)
-
-**Steps to encode:**
-
-1. **Context:** Only when the agent has access to a **full clone or fork** of Neotoma (current workspace or another path with permission). If Neotoma is only installed globally, use Option A and guide the user to clone/fork first.
-2. **Fix:** Implement the fix following existing code conventions; add a regression test per bug_learning (test that would have caught the bug).
-3. **Verify:** From the repo directory, run `npm run type-check`, `npm run lint`, `npm test` (and `npm run test:integration` if relevant); fix any failures.
-4. **Branch:** Create branch `bugfix/short-description` (or `bugfix/FU-XXX-description` if a Feature Unit applies).
-5. **Commit:** Commit with a clear message; reference issue if one was created.
-6. **Remote:** If the user has a fork, push to the fork. If the agent cannot push (no fork, no auth), instruct the user to create a fork and push the branch, or fall back to Option A and include the suggested fix in the issue body.
-7. **PR:** Run `gh pr create --base dev --title "Brief description" --body "…"` (body per [docs/developer/development_workflow.md](docs/developer/development_workflow.md)); if base is `main` for hotfixes, say so in instructions.
-
-**Caveats:**
-
-- The agent cannot create a GitHub fork for the user. If the user has no fork, guide them using the steps below (fork and install from fork), then retry Option B.
-- Prefer not to push to `markmhendrickson/neotoma` from an agent; contributions from external contributors go via fork → PR.
-
-## Fork and install from fork (when user doesn't have one yet)
-
-Include these steps in client guidance so the agent can guide the user (or run when permitted) when Option B is desired but no fork exists:
-
-1. **Create fork**
-
-- **Preferred (if `gh` authenticated):** `gh repo fork markmhendrickson/neotoma` (creates fork under the user's GitHub account and adds it as a remote if run from an existing clone).
-- **Otherwise:** Direct user to [https://github.com/markmhendrickson/neotoma/fork](https://github.com/markmhendrickson/neotoma/fork) and have them click "Create fork".
-
-1. **Get a full clone of the fork**
-
-- If user had no clone: `git clone https://github.com/<USER>/neotoma.git` (replace `<USER>` with their GitHub username) or `gh repo clone <USER>/neotoma`.
-- If user already had a clone of upstream: add fork as remote and fetch — `git remote add fork https://github.com/<USER>/neotoma.git` (or `origin` if they renamed it), then `git fetch fork`.
-
-1. **Install from fork (so they can run Option B from that directory)**
-
-- **For contributing (fix + tests + PR):** From the clone, run `npm install` (install deps). No need to install the package globally; the agent works in the repo directory and runs `npm test` etc. from there. User (or agent) opens that folder as the workspace or grants access to that path.
-- **Optional — use forked CLI globally:** From the clone, `npm install -g .` or `npm link` (local symlink for development). Only if the user wants to run the fixed version as their global `neotoma` before the PR is merged.
-
-Encode in instructions: "If user has no fork but wants Option B, guide them: (1) create fork (gh repo fork or GitHub UI), (2) clone the fork (or add fork remote to existing clone), (3) open the clone (or give agent access to that path) and run npm install there; then proceed with fix, test, push to fork, and open PR."
-
-## Content shape per file
-
-### MCP ([docs/developer/mcp/instructions.md](docs/developer/mcp/instructions.md))
-
-Add a short block (3–4 lines) in the existing instruction style. **Lead with trigger:**
-
-- **Trigger:** When recent context shows a Neotoma error (thrown error, failed MCP/CLI call, stack trace, test failure) or the user describes or discusses a Neotoma bug, apply the flow below immediately; do not wait for the user to ask to report or fix.
-- **Bug report:** Collect repro, env, and error. Prefer Option B only when the agent has access to a **full clone or fork** of the repo (current workspace or another path with permission). If Neotoma is installed globally only, or no repo path is available, use Option A: `gh issue create --repo markmhendrickson/neotoma` or give user link + pre-filled body; tell user to clone/fork if they want to contribute a fix.
-- **Option B (when repo available):** Implement fix, add regression test, run type-check/lint/tests from repo dir, commit on bugfix/ branch, push to user fork, then `gh pr create --base dev`. If no fork or cannot push: guide user through fork and install from fork (create fork via gh repo fork or GitHub UI, clone fork or add fork remote, open clone and npm install), then retry Option B; or fall back to Option A with suggested fix in issue.
-
-### CLI ([docs/developer/cli_agent_instructions.md](docs/developer/cli_agent_instructions.md))
-
-Add a new section **"Neotoma bug report and contributing a fix"** with:
-
-- **Trigger (apply automatically):** When recent context shows a Neotoma error (thrown error, failed MCP/CLI call, stack trace, test failure) or the user describes or discusses a Neotoma bug, apply the flow below immediately; do not wait for the user to ask to report or fix.
-- **Option B when:** Agent has access to a directory that is a full clone or fork of Neotoma (current workspace or another path with permission). If Neotoma is only installed globally, use Option A and guide the user to clone/fork to contribute.
-- **Option B steps:** Fix → regression test → from repo dir run type-check, lint, test → branch `bugfix/…` → commit → push to fork → `gh pr create --base dev`. If no fork: guide user through fork and install from fork (see below), then retry Option B or fall back to Option A with suggested fix.
-- **Fork and install from fork (when user doesn't have one yet):** (1) Create fork: `gh repo fork markmhendrickson/neotoma` or [https://github.com/markmhendrickson/neotoma/fork](https://github.com/markmhendrickson/neotoma/fork). (2) Clone fork: `git clone https://github.com/<USER>/neotoma.git` or `gh repo clone <USER>/neotoma`; or add remote if they have upstream clone. (3) From clone: `npm install`; open that folder (or give agent access) and proceed with fix/test/push/PR. Optional: `npm install -g .` or `npm link` from clone to use forked CLI globally.
-- **Option A:** Collect repro/env/error → `gh issue create --repo markmhendrickson/neotoma` or give user link + body from issue template. Repo URL: `https://github.com/markmhendrickson/neotoma`.
-
-Optional: add one bullet to the "Rule (instruction content)" list that references this section.
-
-## Sync rule update
-
-In [docs/developer/agent_instructions_sync_rules.mdc](docs/developer/agent_instructions_sync_rules.mdc), add to the behavioral parity table:
-
-| Behavior                    | MCP anchor                                 | CLI anchor                                              |
-| --------------------------- | ------------------------------------------ | ------------------------------------------------------- |
-| Bug report / contribute fix | New "Neotoma bug:" / "Bug report:" line(s) | New "Neotoma bug report and contributing a fix" section |
-
-## Implementation order
-
-1. Add the new section and MCP block (content as above).
-2. Update the sync rule parity table.
-3. Run `neotoma cli-instructions check` (or equivalent) so applied CLI rule picks up the new section.
-4. Optionally add a short note in [docs/developer/agent_cli_configuration.md](docs/developer/agent_cli_configuration.md) or [docs/developer/mcp_overview.md](docs/developer/mcp_overview.md) that agents are instructed to report bugs and contribute fixes when applicable.
-
-## Summary
-
-| Item             | Action                                                                                                                                                                                            |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Trigger          | Encode so agent applies flow **automatically** when recent context has Neotoma errors (thrown/failed call/stack trace/test failure) or user discusses/reports a bug; do not wait for user to ask. |
-| MCP instructions | Lead with trigger line; then 2–3 lines for bug report + Option B (only when full repo available), global-install → Option A; if no fork, guide through fork + clone + npm install                 |
-| CLI instructions | Section opens with **Trigger (apply automatically)**; then A/B steps, repo URL, "full clone/fork (any path with permission)", global-install caveat, and **fork and install from fork** steps     |
-| Sync rule        | Add parity row for bug report / contribute fix                                                                                                                                                    |
-| Global install   | Explicit: Option B does not run from global install path; use Option A and guide user to clone/fork for contributing                                                                              |
-| Fork / install   | Include steps: create fork (gh repo fork or GitHub UI), clone fork or add remote, npm install in clone; optional install -g / npm link from clone                                                 |