neotoma 0.3.0 → 0.3.2

package/.cursor/rules/cursor_rules_sync_requirement.mdc

@@ -1,156 +0,0 @@
----
-description: "Load after editing any rule or command source: run setup_cursor_copies immediately in same conversation; do not defer; verify sync succeeded before marking rule update complete."
-alwaysApply: false
----
-
-# ⚠️  DO NOT EDIT THIS FILE DIRECTLY
-#
-# This is a copy of: foundation/agent_instructions/cursor_rules/cursor_rules_sync_requirement.mdc
-# Source of truth: foundation/agent_instructions/cursor_rules/cursor_rules_sync_requirement.mdc
-#
-# To edit this rule:
-# 1. Edit the source file: foundation/agent_instructions/cursor_rules/cursor_rules_sync_requirement.mdc
-# 2. Run '/setup_cursor_copies' to sync changes
-#
-# This file will be overwritten when running setup_cursor_copies.
-
-# Cursor Rules Sync Requirement Rule
-
-## Purpose
-
-Ensures agents ALWAYS run `/setup_cursor_copies` immediately after updating any rule or command file, ensuring changes are synced to `.cursor/` directory in the same conversation/workflow.
-
-## Scope
-
-This document covers:
-- Mandatory requirement to run `/setup_cursor_copies` after rule/command updates
-- When this requirement applies
-- Validation requirements
-
-This document does NOT cover:
-- How to edit rules (see `cursor_rules_editing.mdc`)
-- Foundation vs repository rule locations (see `cursor_rules_editing.mdc`)
-
-## Trigger Patterns
-
-Agents MUST run `/setup_cursor_copies` immediately after:
-
-- Editing any file in `docs/` that is a rule source (files matching `*_rules.mdc` or `*_rules.md`)
-- Editing any file in `docs/` that is a command source (files matching `*_command.md`)
-- Editing any file in `foundation/agent_instructions/cursor_rules/`
-- Editing any file in `foundation/agent_instructions/cursor_commands/`
-- Updating rule documentation
-- Creating new rule files
-- Modifying existing rule files
-
-## Mandatory Requirement
-
-**MANDATORY:** After editing ANY rule or command source file, agents MUST:
-
-1. **Immediately run `/setup_cursor_copies`** in the same conversation/workflow
-2. **Do NOT defer this step** to a later conversation
-3. **Do NOT mark rule updates complete** without running `/setup_cursor_copies`
-4. **Verify the sync succeeded** by checking script output
-
-## Agent Actions
-
-### Step 1: Edit Source File
-
-1. Identify the source file location:
-   - Repository rules: `docs/{subdirectory}/{name}_rules.mdc` or `docs/{subdirectory}/{name}_rules.md`
-   - Foundation rules: `foundation/agent_instructions/cursor_rules/{name}.mdc`
-   - Commands: `docs/{subdirectory}/{name}_command.md` or `foundation/agent_instructions/cursor_commands/{name}.md`
-
-2. Edit the source file directly (never edit `.cursor/` copies)
-
-### Step 2: Run Setup Script (MANDATORY)
-
-**MUST run immediately after editing:**
-
-```bash
-./foundation/scripts/setup_cursor_copies.sh
-```
-
-Or if foundation is in parent directory:
-
-```bash
-../foundation/scripts/setup_cursor_copies.sh
-```
-
-**Verify success:**
-- Check script output for "✅ Cursor rules setup complete!"
-- Verify no errors in script output
-- Confirm files were copied/updated
-
-### Step 3: Verify Sync
-
-1. Check that `.cursor/rules/` or `.cursor/commands/` contains updated files
-2. Verify header comments in copied files reference correct source
-3. Confirm changes are reflected in copied files
-
-## Constraints
-
-- **MUST ALWAYS run `/setup_cursor_copies`** after editing any rule or command source file
-- **MUST run in the same conversation/workflow** as the rule update
-- **MUST NOT defer** this step to a later conversation
-- **MUST NOT mark rule updates complete** without running `/setup_cursor_copies`
-- **MUST verify sync succeeded** before completing the workflow
-
-## Forbidden Patterns
-
-- Editing rule/command source files without running `/setup_cursor_copies`
-- Deferring `/setup_cursor_copies` to a later conversation
-- Marking rule updates complete without running `/setup_cursor_copies`
-- Assuming changes will sync automatically (they won't)
-- Skipping sync verification
-
-## Validation Checklist
-
-Before marking rule/command updates complete:
-- [ ] Source file edited (in `docs/` or `foundation/agent_instructions/`)
-- [ ] **`/setup_cursor_copies` run immediately after editing** (MANDATORY)
-- [ ] Script output shows "✅ Cursor rules setup complete!"
-- [ ] No errors in script output
-- [ ] Changes verified in `.cursor/rules/` or `.cursor/commands/` copies
-- [ ] Rule update workflow complete (edit → sync → verify)
-
-## Related Documents
-
-- `cursor_rules_editing.mdc` - How to edit rules and commands
-- Repository setup_cursor_copies command documentation
-
-## Agent Instructions
-
-### When to Load This Document
-
-Load this document when:
-- Editing any rule or command file
-- Creating new rule or command files
-- Updating rule documentation
-
-### Required Co-Loaded Documents
-
-- `cursor_rules_editing.mdc` - Rule editing guidelines
-
-### Constraints Agents Must Enforce
-
-1. **MANDATORY:** Always run `/setup_cursor_copies` immediately after editing any rule or command
-2. **MANDATORY:** Run sync in the same conversation/workflow as the edit
-3. **MANDATORY:** Verify sync succeeded before marking updates complete
-4. **FORBIDDEN:** Deferring sync to a later conversation
-5. **FORBIDDEN:** Marking rule updates complete without running sync
-
-### Forbidden Patterns
-
-- Editing rules without running `/setup_cursor_copies`
-- Deferring sync to later conversations
-- Marking updates complete without sync
-- Assuming automatic sync (doesn't exist)
-
-### Validation Checklist
-
-- [ ] Source file edited
-- [ ] `/setup_cursor_copies` run immediately (same conversation)
-- [ ] Sync verified successful
-- [ ] Changes confirmed in `.cursor/` copies
-- [ ] Workflow complete

package/.cursor/rules/developer_agent_instructions_sync_rules.mdc

@@ -1,109 +0,0 @@
----
-description: "MCP/CLI instruction parity: when either mcp/instructions.md or cli_agent_instructions.md changes, apply equivalent change to the other."
-globs: ["docs/developer/mcp/instructions.md", "docs/developer/cli_agent_instructions.md"]
----
-
-# ⚠️  DO NOT EDIT THIS FILE DIRECTLY
-#
-# This is a copy of: docs/developer/agent_instructions_sync_rules.mdc
-# Source of truth: docs/developer/agent_instructions_sync_rules.mdc
-#
-# To edit this rule:
-# 1. Edit the source file: docs/developer/agent_instructions_sync_rules.mdc
-# 2. Run '/setup_cursor_copies' to sync changes
-#
-# This file will be overwritten when running setup_cursor_copies.
-
-
-# Agent Instructions Sync Rule
-
-## Purpose
-
-Ensures behavioral instructions stay in sync across the two agent instruction files. When either file is updated, the equivalent change must be applied to the other.
-
-## Scope
-
-The two files governed by this rule:
-
-- `docs/developer/mcp/instructions.md` — loaded at runtime by `getMcpInteractionInstructions()` in `src/server.ts`; sent verbatim to MCP clients
-- `docs/developer/cli_agent_instructions.md` — source of truth for CLI agent rules; applied to `.cursor/rules/neotoma_cli.mdc`, `.claude/rules/`, and `.codex/` by `neotoma cli-instructions check`
-
-This rule does NOT cover:
-- The auto-injected active-env section in `.cursor/rules/neotoma_cli.mdc` (managed by CLI session startup)
-- Per-tool descriptions in `docs/developer/mcp/tool_descriptions.yaml`
-- Format differences between the two files (the MCP file uses a plain-text code block; the CLI file uses markdown sections)
-
-## Trigger Patterns
-
-Apply this rule whenever:
-- Any behavioral instruction is added, changed, or removed in either file
-- A new category of behavior is introduced (e.g. new store pattern, new retrieval pattern, new relationship type)
-- Wording of an existing rule is corrected or clarified in one file
-
-## Behavioral Sections That Must Stay in Parity
-
-Each behavioral rule exists in both files with transport-appropriate wording. The following behaviors must be equivalent in both:
-
-| Behavior | MCP anchor | CLI anchor |
-|---|---|---|
-| Chat persistence (MANDATORY) | `Chat (one call):` line | `MANDATORY in chat` bullet |
-| Entity shapes (conversation, agent_message) | `Chat (one call):` line | `MANDATORY in chat` bullet |
-| Stable turn identity (`turn_key`) | `Chat (one call):` line | `MANDATORY in chat` bullet |
-| Observation history / branch overwriting | `Chat details:` line | `Chat details` bullet |
-| Reverted turns (SUPERSEDES) | `Chat details:` line | `Chat details` bullet |
-| Attachments | `Chat details:` line | `Chat details` bullet |
-| Screenshot/image (extract and store) | `Screenshot/image:` line | `Screenshot/image:` bullet |
-| Do not mention storage in thoughts | `Do not mention...` line | `Do not mention` bullet |
-| Store-first rule (external tools) | `Other MCPs:` line | `External tool data` bullet |
-| Proactive retrieval (before final response) | `Proactive retrieval:` line | `Proactive retrieval` bullet |
-| Retrieval guardrails and answer grounding | `Retrieval guardrails:` / `Answer grounding:` lines | `Retrieval guardrails and answer grounding` bullet |
-| User identity | `User identity:` line | `User identity` bullet |
-| Entity extraction | `Extract and store...` line | `Extract and store` bullet |
-| Tasks | `Tasks:` line | `Tasks` bullet |
-| Entity type discovery | `Entity types:` line | `Entity types` bullet |
-| Conventions (pre-check, structured/unstructured path, summary) | `Conventions:` line | `Conventions` bullet |
-| Relationship fallback | `Fallback if relationships...` line | `Relationship creation` section |
-
-## Agent Actions
-
-### When modifying either file
-
-1. **Identify the changed behavior** — which category in the table above does it belong to?
-2. **Locate the equivalent section in the other file** — use the anchor column in the table
-3. **Apply the equivalent change** — reword for the transport (MCP tool calls vs CLI commands) but preserve the behavioral intent exactly
-4. **Verify both files are updated before completing the task**
-
-### Wording conventions
-
-The MCP file is a dense plain-text code block (one instruction per line). The CLI file uses structured markdown with transport-branched wording (`**MCP:** ... **CLI:** ...`). Translate between them:
-
-- MCP action names (`store_structured`, `create_relationship`) → CLI equivalents (`neotoma --servers=start store --json='...'`, `neotoma --servers=start relationships create ...`)
-- MCP retrieval actions (`retrieve_entity_by_identifier`, `retrieve_entities`, `list_timeline_events`, `retrieve_related_entities`, `retrieve_graph_neighborhood`, `list_observations`) → CLI retrieval equivalents (`neotoma --servers=start entities search/list`, timeline/event query commands, `relationships list`, `observations list`)
-- MCP `list_entity_types` → CLI `neotoma --servers=start schemas list --search <keyword>`
-- MCP `npm_check_update` → CLI `neotoma --servers=start --help` / update notifier
-- Inline `relationships: [...]` in MCP store → separate `relationships create` call in CLI
-
-### Files to update
-
-When `docs/developer/mcp/instructions.md` changes:
-- Update `docs/developer/cli_agent_instructions.md` (source of truth for CLI)
-- The `.cursor/rules/neotoma_cli.mdc` Rule section is regenerated from the source doc on next CLI session start; if an immediate update is needed, edit `.cursor/rules/neotoma_cli.mdc` directly as well
-
-When `docs/developer/cli_agent_instructions.md` changes:
-- Update `docs/developer/mcp/instructions.md`
-- Update `.cursor/rules/neotoma_cli.mdc` Rule section directly (same content as source doc)
-
-## Constraints
-
-- MUST update both files when behavioral instructions change in either one
-- MUST NOT change the behavioral intent when translating between transports — only the commands differ
-- MUST NOT add CLI-specific operational sections (e.g. `--servers=start` protocol, `--json=` syntax warning, active-env block) to `mcp/instructions.md`
-- MUST NOT add MCP-specific internals (e.g. `source_index`/`target_index` for inline relationships, `file_content+mime_type` parameters) to the CLI file beyond what is needed for behavioral equivalence
-- MUST verify both files are updated before marking the task complete
-
-## Related Documents
-
-- `docs/developer/mcp/instructions.md` — MCP instruction source
-- `docs/developer/cli_agent_instructions.md` — CLI instruction source
-- `.cursor/rules/neotoma_cli.mdc` — applied CLI rule file (auto-updated by CLI session startup)
-- `docs/developer/agent_cli_configuration.md` — CLI/MCP strategy overview

package/.cursor/rules/document_loading_order.mdc

@@ -1,206 +0,0 @@
----
-description: "Load at session start or when uncertain about doc order: load foundation docs first, then foundation submodule when needed, then task-specific docs; follow dependency graph."
-alwaysApply: false
----
-
-# ⚠️  DO NOT EDIT THIS FILE DIRECTLY
-#
-# This is a copy of: foundation/agent_instructions/cursor_rules/document_loading_order.mdc
-# Source of truth: foundation/agent_instructions/cursor_rules/document_loading_order.mdc
-#
-# To edit this rule:
-# 1. Edit the source file: foundation/agent_instructions/cursor_rules/document_loading_order.mdc
-# 2. Run '/setup_cursor_copies' to sync changes
-#
-# This file will be overwritten when running setup_cursor_copies.
-
-# Document Loading Order Rule
-
-**Reference:** `foundation/conventions/documentation-standards.md` - Documentation standards
-
-## Purpose
-
-Ensures agents load documentation in the correct order to establish proper context before proceeding with work.
-
-## Scope
-
-This document defines:
-- Mandatory loading order for documentation
-- Foundation submodule usage
-- Workflows for AI assistants and human developers
-
-This document does NOT cover:
-- Specific constraints agents must enforce (see `agent_constraints.md`)
-- Risk management and hold points (see `risk_management.md`)
-- Repository-specific document paths (configured in `foundation-config.yaml`)
-
-## Configuration
-
-Configure document loading paths in `foundation-config.yaml`:
-
-```yaml
-agent_instructions:
-  enabled: true
-  location: "docs/foundation/agent_instructions.md"  # Repository-wide agent instructions
-  foundation_docs_path: "docs/foundation/"  # Path to foundation documents
-  cursor_rules:
-    enabled: true
-    location: ".cursor/rules/"
-```
-
-**Document paths are configurable per repository.** Default paths shown above can be customized in `foundation-config.yaml`.
-
-## Mandatory Loading Order
-
-Every AI assistant session MUST load documents in this order:
-
-### 1. Foundation Documents (First)
-
-Load foundation documents from configured foundation docs path FIRST (default: `docs/foundation/`):
-
-**Required foundation documents:**
-- Core philosophy/principles document (e.g., `philosophy.md`, `principles.md`)
-- Core identity document (e.g., `core_identity.md`, `identity.md`)
-- Data models document (if applicable, e.g., `data_models.md`)
-- Architecture document (if applicable, e.g., `architecture.md`, `layered_architecture.md`)
-
-**Why:** These establish the fundamental constraints and boundaries that all other work must respect.
-
-**Configuration:** Set `agent_instructions.foundation_docs_path` in `foundation-config.yaml` to customize the path.
-
-### 2. Foundation Submodule Documents (When Needed)
-
-Load shared foundation processes from `foundation/` submodule when needed:
-
-- `foundation/development/workflow.md` - For git workflow, branching, PRs
-- `foundation/conventions/code-conventions.md` - For code style and naming
-- `foundation/conventions/documentation-standards.md` - For documentation structure
-- `foundation/security/security-rules.md` - For security practices
-- `foundation-config.yaml` - For repository-specific configuration
-
-**When:** Load when working on development workflow, code style, documentation, or security-related tasks.
-
-### 3. Task-Specific Documents
-
-Load task-specific docs based on change type:
-
-- **Architecture changes:** Architecture docs from configured architecture path (default: `docs/architecture/`)
-- **Subsystem work:** Relevant subsystem docs from configured subsystems path (default: `docs/subsystems/`)
-- **Feature work:** Feature specs from configured specs path (default: `docs/specs/` or `docs/feature_units/`)
-- **Release work:** Release plans and status from configured releases path (default: `docs/releases/`)
-- **Documentation work:** Documentation standards from configured conventions path (default: `docs/conventions/`)
-- **Code work:** Code conventions from configured conventions path (default: `docs/conventions/`)
-
-**Configuration:** Document paths can be customized per repository structure.
-
-### 4. Related Context Documents
-
-Load additional context as needed:
-
-- Related subsystem docs
-- Integration guides
-- Testing standards
-- API specifications
-
-## For AI Assistants
-
-**Every session:**
-
-1. Load foundation documents from configured foundation docs path first (see Section 1)
-2. Load foundation submodule docs when relevant (see Section 2)
-3. Reference foundation documents to resolve ambiguities
-4. Validate all outputs against invariants
-5. Stop at hold points for human approval (see `.cursor/rules/foundation-risk_management.md` if exists)
-
-**When uncertain:**
-
-- Default to conservative interpretation
-- Prioritize correctness over convenience
-- Ask for clarification rather than guess
-
-## For Human Developers
-
-**Before starting work:**
-
-1. Read foundation documents from configured foundation docs path (see Section 1)
-2. Read relevant subsystem/docs as indicated by context
-3. Understand project constraints and boundaries
-4. Verify feature fits within project scope
-
-**During implementation:**
-
-- Follow project conventions
-- Write maintainable code
-- Test thoroughly
-- Document all assumptions
-
-**Before committing:**
-
-- **Run security audit** from `foundation/security/pre-commit-audit.sh` (if configured)
-- Verify alignment with project standards
-- Check validation checklists
-- Run full test suite
-- Update docs if patterns changed
-- **Follow commit format** from `foundation/development/workflow.md` (configured in `foundation-config.yaml`)
-
-## Using Foundation Submodule
-
-Repositories using the foundation framework have access to the shared **foundation** submodule (`foundation/`) for development processes and conventions:
-
-### When to Reference Foundation
-
-**Development Workflow:**
-- Creating branches: See `foundation/development/workflow.md` and `foundation/development/branch-strategy.md`
-- Creating worktrees: Use `foundation/development/worktree-setup.sh` (if configured)
-- PR process: Follow `foundation/development/pr-process.md`
-- Commit format: Configured in `foundation-config.yaml` (see `development.commit_format.pattern`)
-
-**Code Conventions:**
-- Code style: See `foundation/conventions/code-conventions.md`
-- Naming patterns: See `foundation/conventions/naming-patterns.yaml`
-- Repository overrides: Check `foundation-config.yaml` for repo-specific settings
-
-**Documentation:**
-- Doc structure: Follow `foundation/conventions/documentation-standards.md`
-- Writing style: Avoid AI-generated patterns, use RFC 2119 language
-- Agent Instructions: Use template from `foundation/agent_instructions/README.md`
-
-**Security:**
-- Pre-commit audit: Run `foundation/security/pre-commit-audit.sh` before commits (if configured)
-- Credential management: See `foundation/security/credential-management.md`
-- Security rules: See `foundation/security/security-rules.md`
-
-**Configuration:**
-- Repository config: `foundation-config.yaml` (repo root)
-- Foundation defaults: `foundation/config/foundation-config.yaml`
-
-### Foundation Submodule vs Repository Foundation Docs
-
-- **`foundation/` submodule**: Shared development processes (workflow, conventions, security) - can be used by multiple repos
-- **Repository foundation docs** (e.g., `docs/foundation/`): Repository-specific foundation (philosophy, architecture, product positioning) - repository only
-
-Both are important:
-- Use `foundation/` for development practices (how to code, commit, review)
-- Use repository foundation docs for repository architecture (what to build, why, constraints)
-
-### Syncing Foundation Updates
-
-When foundation submodule is updated:
-
-```bash
-# Update to latest foundation
-git submodule update --remote foundation
-
-# Or use sync script (if available)
-./foundation/scripts/sync-foundation.sh
-```
-
-See `foundation/README.md` for complete foundation documentation.
-
-## Related Documents
-
-- `foundation/conventions/documentation-standards.md` - Documentation standards
-- `foundation/README.md` - Foundation submodule documentation
-- `foundation-config.yaml` - Repository-specific foundation configuration
-- `.cursor/rules/foundation-risk_management.md` - Risk management and hold points (if exists)
-