neotoma 0.3.0 → 0.3.2

package/.cursor/plans/me_and_get_authenticated_user_response_updates.plan.md

@@ -1,125 +0,0 @@
----
-name: Me and get_authenticated_user response updates
-overview: Add optional local storage details to GET /me and POST /get_authenticated_user (and MCP get_authenticated_user), keep email as optional, and include Supabase-removal cleanup where relevant.
-todos:
-  - id: me-storage
-    content: Add optional storage object to GET /me when storageBackend is local (actions.ts)
-    status: pending
-  - id: get-auth-user-storage
-    content: Add optional storage to POST /get_authenticated_user and MCP get_authenticated_user when local
-    status: pending
-  - id: openapi-schemas
-    content: Extend OpenAPI and types for /me and get_authenticated_user with optional storage
-    status: pending
-  - id: remove-auth-ui
-    content: Remove all frontend auth UI flows (SigninForm, SignupForm, OAuthButtons, PasswordReset, AuthCallback, pages, AuthDialog)
-    status: pending
-  - id: supabase-cleanup
-    content: Trim auth shim stubs and doc fixes (see plan section)
-    status: pending
-isProject: false
----
-
-# Me and get_authenticated_user response updates
-
-## Current behavior
-
-- **GET /me** ([src/actions.ts](src/actions.ts) ~1181–1192): returns `{ user_id, email? }`. `email` is set only when the request is authenticated via **session token** (OAuth path in auth middleware); for local dev, key-derived token, or `NEOTOMA_BEARER_TOKEN`, `authenticatedUserEmail` is never set, so `email` is omitted.
-- **POST /get_authenticated_user** (same file ~4170–4186): returns `{ user_id }` only.
-- **MCP get_authenticated_user** ([src/server.ts](src/server.ts) ~457–469): returns JSON text `{ user_id, authenticated: true }`.
-
-Email is **only** set in [src/actions.ts](src/actions.ts) at line 1163 when `validateSessionToken(bearerToken)` succeeds (session/OAuth). The CLI uses `email` when present for display. The frontend does **not** call `/me`; it uses the **local auth shim** ([frontend/src/lib/auth.ts](frontend/src/lib/auth.ts)) with guest sign-in only (no Supabase).
-
-## Recommendations
-
-### 1. Keep `email` on GET /me (do not remove)
-
-In local mode we do not set it; that's expected. Removing it would break CLI display for OAuth/session users. No change to email handling.
-
-### 2. Add optional `storage` when backend is local
-
-When `config.storageBackend === "local"`, include an optional **storage** object. Source: [src/config.ts](src/config.ts) (`config.dataDir`, `config.sqlitePath`).
-
-- **GET /me**: add `storage?: { storage_backend: "local"; data_dir: string; sqlite_db: string }`.
-- **POST /get_authenticated_user** and **MCP get_authenticated_user**: same optional `storage` when local.
-
-### 3. No other new fields for now
-
-Identity (`user_id`, optional `email` on /me) plus optional `storage` is sufficient.
-
----
-
-## Supabase removal – further cleanup
-
-Supabase-based functionality has been removed: no `@supabase/` in package.json, and the frontend uses a **local auth shim** ([frontend/src/lib/auth.ts](frontend/src/lib/auth.ts)) that mimics a Supabase-like API (getSession, signInAnonymously, signOut, setSession, plus stubs for signInWithOtp, signInWithPassword, signUp, resetPasswordForEmail, signInWithOAuth) that return "disabled in local-only mode."
-
-### Remove all frontend auth UI flows
-
-Remove the components and pages that implement sign-in, sign-up, OAuth, and password-reset flows; they all call auth methods that in local-only mode return "disabled" errors and cannot succeed.
-
-**Files to delete (9):**
-
-- [frontend/src/components/auth/SigninForm.tsx](frontend/src/components/auth/SigninForm.tsx)
-- [frontend/src/components/auth/SignupForm.tsx](frontend/src/components/auth/SignupForm.tsx)
-- [frontend/src/components/auth/OAuthButtons.tsx](frontend/src/components/auth/OAuthButtons.tsx)
-- [frontend/src/components/auth/PasswordReset.tsx](frontend/src/components/auth/PasswordReset.tsx)
-- [frontend/src/components/auth/AuthCallback.tsx](frontend/src/components/auth/AuthCallback.tsx)
-- [frontend/src/components/auth/SignInPage.tsx](frontend/src/components/auth/SignInPage.tsx)
-- [frontend/src/components/auth/SignUpPage.tsx](frontend/src/components/auth/SignUpPage.tsx)
-- [frontend/src/components/auth/ResetPasswordPage.tsx](frontend/src/components/auth/ResetPasswordPage.tsx)
-- [frontend/src/components/auth/AuthDialog.tsx](frontend/src/components/auth/AuthDialog.tsx)
-
-**Routing:** The current app ([MainApp.tsx](frontend/src/components/MainApp.tsx)) does not mount routes for `/signin`, `/signup`, `/auth/callback`, or `/reset-password`; no route changes are required. If any other entry references these components or paths, remove those references.
-
-### Auth shim trim
-
-After removing the auth UI, [frontend/src/lib/auth.ts](frontend/src/lib/auth.ts) can be trimmed: remove or simplify the Supabase-shaped stubs that were only used by the removed components—`signInWithOtp`, `signInWithPassword`, `signUp`, `resetPasswordForEmail`, `signInWithOAuth`, and `oauth.getAuthorizationDetails`. Keep the minimal set used by AuthContext and any remaining callers: `getSession`, `signInAnonymously`, `signOut`, `onAuthStateChange`, `setSession`.
-
-### Docs and comments
-
-- Correct any in-repo docs that still claim the frontend uses Supabase to "local auth shim" / "guest sign-in only."
-- Confirm no Supabase packages or imports remain (already the case).
-
-### Optional (out of scope or follow-up)
-
-- **Frontend identity vs backend:** AuthContext currently provides `user.id` and `sessionToken` from the local shim. Optional improvement: have the frontend call GET /me to show consistent `user_id` and optional storage.
-- Historical/competitive docs in `docs/private/` that mention Supabase can stay as-is or be updated in a separate pass.
-
----
-
-## Implementation summary
-
-| Area                                                       | Change                                                                                                                                                             |
-| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| [src/actions.ts](src/actions.ts)                           | GET /me: build response with optional `storage` when `config.storageBackend === "local"`. Keep `user_id` and `email: email ?? undefined`.                          |
-| [src/actions.ts](src/actions.ts)                           | POST /get_authenticated_user: same optional `storage` when local.                                                                                                  |
-| [src/server.ts](src/server.ts)                             | MCP `getAuthenticatedUser`: when local, include same `storage` in object passed to `buildTextResponse`.                                                            |
-| [openapi.yaml](openapi.yaml)                               | Extend GET /me and POST /get_authenticated_user response schemas with optional `storage` object.                                                                   |
-| [src/shared/openapi_types.ts](src/shared/openapi_types.ts) | Add optional `storage` to response types for getMe and getAuthenticatedUser (if not generated).                                                                    |
-| Frontend auth                                              | See "Remove all frontend auth UI flows" and "Auth shim trim" above: delete 9 auth component files, trim auth shim stubs, doc fixes. Optional: GET /me integration. |
-
-## Response shape (after change)
-
-**GET /me (200):**
-
-```json
-{
-  "user_id": "...",
-  "email": "user@example.com",
-  "storage": {
-    "storage_backend": "local",
-    "data_dir": "/path/to/data",
-    "sqlite_db": "/path/to/data/neotoma.db"
-  }
-}
-```
-
-(`email` and `storage` optional. `storage` only when storageBackend is local.)
-
-**POST /get_authenticated_user (200):** same structure (no `email`; optional `storage` when local). **MCP get_authenticated_user:** same fields in JSON text (including `authenticated: true`; optional `storage` when local).
-
-## Testing
-
-- Call GET /me and POST /get_authenticated_user with local backend; assert `storage` is present with correct paths.
-- Contract tests: update expectations to allow optional `storage` and keep optional `email` for /me.
-- After auth UI removal: verify app loads and guest flow works; no references to removed auth components or routes.

package/.cursor/plans/multi-llm_provider_support_3fdeb361.plan.md

@@ -1,120 +0,0 @@
----
-name: Multi-LLM provider support
-overview: Add configuration and an LLM adapter layer so chat completions and (optionally) embeddings can use providers other than OpenAI (e.g., Anthropic, Azure OpenAI, or any OpenAI-compatible endpoint), while keeping OPENAI_API_KEY as the default for backward compatibility.
-todos: []
-isProject: false
----
-
-# Multi-LLM Provider Support Plan
-
-## Current state
-
-- **Chat completions**: Used in [src/services/llm_extraction.ts](src/services/llm_extraction.ts), [src/services/schema_icon_service.ts](src/services/schema_icon_service.ts), and [src/services/schema_recommendation.ts](src/services/schema_recommendation.ts). All instantiate `new OpenAI({ apiKey: config.openaiApiKey })` and call `openai.chat.completions.create()` with models like `gpt-4o` / `gpt-4o-mini`.
-- **Embeddings**: [src/embeddings.ts](src/embeddings.ts) uses OpenAI `text-embedding-3-small` (1536 dimensions). [src/services/local_entity_embedding.ts](src/services/local_entity_embedding.ts) hardcodes `EMBEDDING_DIM = 1536` for sqlite-vec; entity semantic search and schema registry depend on `generateEmbedding()`.
-- **Config**: [src/config.ts](src/config.ts) exposes only `openaiApiKey` from `OPENAI_API_KEY`.
-- **CLI**: [src/cli/index.ts](src/cli/index.ts) init flow prompts for `OPENAI_API_KEY` and writes it to `.env`; secret list includes `OPENAI_API_KEY`.
-- **API**: Interpretation config and errors reference `provider: "openai"` and `openai_not_configured` / "Set OPENAI_API_KEY" in [src/actions.ts](src/actions.ts), [src/server.ts](src/server.ts), and [src/cli/index.ts](src/cli/index.ts).
-
-## Architecture
-
-```mermaid
-flowchart LR
-  subgraph call_sites [Call sites]
-    LLMExtraction[llm_extraction.ts]
-    SchemaIcon[schema_icon_service.ts]
-    SchemaRec[schema_recommendation.ts]
-    Embeddings[embeddings.ts]
-  end
-  subgraph adapter [LLM adapter]
-    Chat[createChatCompletion]
-    Embed[createEmbedding]
-  end
-  subgraph providers [Providers]
-    OpenAI[OpenAI]
-    Anthropic[Anthropic]
-    OpenAICompat[OpenAI-compatible URL]
-  end
-  LLMExtraction --> Chat
-  SchemaIcon --> Chat
-  SchemaRec --> Chat
-  Embeddings --> Embed
-  Chat --> OpenAI
-  Chat --> Anthropic
-  Chat --> OpenAICompat
-  Embed --> OpenAI
-  Embed --> OpenAICompat
-```
-
-
-
-- **Single abstraction**: One module exposes `createChatCompletion(messages, options)` and `createEmbedding(text)` (or keep `generateEmbedding` in embeddings.ts but have it call the adapter). Provider selection is driven by config.
-- **Backward compatibility**: If only `OPENAI_API_KEY` is set (no new provider env), behavior stays as today (OpenAI).
-
-## 1. Config and environment
-
-- **New env vars** (suggested; names can follow existing [ENV_VAR_NAMING_STRATEGY](docs/developer/environment/ENV_VAR_NAMING_STRATEGY.md)):
-  - `NEOTOMA_LLM_PROVIDER`: `openai` (default) | `anthropic` | `azure` | `openai_compatible`
-  - Provider-specific: `OPENAI_API_KEY` (existing), `ANTHROPIC_API_KEY`, `AZURE_OPENAI_ENDPOINT` + `AZURE_OPENAI_API_KEY`, or `OPENAI_COMPATIBLE_BASE_URL` + `OPENAI_COMPATIBLE_API_KEY`
-- **Config shape** in [src/config.ts](src/config.ts): Add `llm: { provider, openaiApiKey?, anthropicApiKey?, azureEndpoint?, azureApiKey?, openaiCompatibleBaseUrl?, openaiCompatibleApiKey? }` and a derived `isLlmConfigured(): boolean` (true if the selected provider has its key/endpoint set). Keep `openaiApiKey` on the root for backward compat during migration, then optionally deprecate or alias from `config.llm.openaiApiKey`.
-- **.env.example**: Document `NEOTOMA_LLM_PROVIDER` and the optional provider-specific variables; keep `OPENAI_API_KEY` as the default example.
-
-## 2. LLM adapter module
-
-- **New module** e.g. `src/llm/client.ts` (or `src/services/llm_client.ts`):
-  - **Chat**: `createChatCompletion({ messages, model, temperature?, max_tokens?, response_format? })` returning `{ content: string, usage? }`. Internally:
-    - `openai`: use existing `openai` package (unchanged).
-    - `anthropic`: use `@anthropic-ai/sdk` with message conversion (Anthropic has different message shape and no `response_format.type: "json_object"`; use tool use / structured output if required).
-    - `azure`: use `openai` with `baseURL` and `apiKey` from config.
-    - `openai_compatible`: use `openai` with `baseURL: OPENAI_COMPATIBLE_BASE_URL` and `apiKey: OPENAI_COMPATIBLE_API_KEY` (covers Groq, Together, local servers, etc.).
-  - **Embeddings**: Either add `createEmbedding(text)` in the same module and have [src/embeddings.ts](src/embeddings.ts) call it, or keep embedding logic in embeddings.ts and add a small provider dispatch there. For non-OpenAI providers, only support options that yield **1536-dimensional** vectors (or document that changing embedding provider may require a migration/re-embed). Azure OpenAI and many OpenAI-compatible endpoints support the same embedding model/dims.
-- **Message format**: Normalize to a small internal type (e.g. `{ role, content }[]`). Reuse or align with [src/utils/chat.ts](src/utils/chat.ts) `ChatMessage` / `serializeChatMessagesForOpenAI`; adapter converts to provider-specific format (OpenAI vs Anthropic differ).
-- **Model IDs**: Keep current defaults (e.g. `gpt-4o`) for `provider === "openai"`. For other providers, accept model in options and document mapping (e.g. `claude-3-5-sonnet`, `azure-deployment-name`). Config could expose optional `NEOTOMA_LLM_CHAT_MODEL` / `NEOTOMA_LLM_EMBEDDING_MODEL` with provider-specific defaults.
-
-## 3. Migrate call sites
-
-- **llm_extraction.ts**: Remove direct `OpenAI` import and `openai` instance. Use adapter `createChatCompletion` for all three call paths (text, image/vision, retry). Replace `if (!openai)` with `if (!isLlmConfigured())` (or adapter returns a clear error). Vision: only OpenAI and Azure support image inputs today; document that vision extraction may require `openai` or `azure` or skip with a clear error for other providers.
-- **schema_icon_service.ts**: Same: use adapter for `matchLucideIcon` and `generateCustomSVGIcon`; replace `openai` checks with config/adapter availability.
-- **schema_recommendation.ts**: Replace dynamic `import("openai")` and `openai.chat.completions.create` with adapter `createChatCompletion`.
-- **embeddings.ts**: Replace direct OpenAI usage with adapter (or adapter’s `createEmbedding`). Ensure 1536-dim contract is preserved; log or error if provider returns wrong dims.
-- **Availability checks**: Replace `config.openaiApiKey` / `openai !== null` with a single `isLlmConfigured()` (or adapter method) everywhere: [src/services/llm_extraction.ts](src/services/llm_extraction.ts) (`isLLMExtractionAvailable`), [src/services/schema_icon_service.ts](src/services/schema_icon_service.ts), [src/embeddings.ts](src/embeddings.ts), [src/actions.ts](src/actions.ts), [src/server.ts](src/server.ts), [src/cli/index.ts](src/cli/index.ts).
-
-## 4. API and CLI behavior
-
-- **Interpretation config**: Keep returning `provider` and `model_id`; set `provider` from config (e.g. `config.llm.provider`) so clients see the actual backend. Keep `openai_not_configured` or generalize to `llm_not_configured` and message "Set NEOTOMA_LLM_PROVIDER and the corresponding API key in .env to enable AI interpretation."
-- **CLI init**: In [src/cli/index.ts](src/cli/index.ts), when prompting for LLM setup, ask for provider (openai / anthropic / etc.) then the relevant key(s). Write `NEOTOMA_LLM_PROVIDER` and the chosen key var(s) to `.env`. Optionally keep prompting for `OPENAI_API_KEY` if provider is openai for minimal change. Update the secret list used for masking to include the new provider keys (e.g. `ANTHROPIC_API_KEY`).
-
-## 5. Dependencies and tests
-
-- **Dependencies**: Add `@anthropic-ai/sdk` only if supporting Anthropic; Azure uses existing `openai` with different base URL. For OpenAI-compatible, no new dependency.
-- **Unit tests**: Mock the adapter in [tests/integration/llm_extraction.test.ts](tests/integration/llm_extraction.test.ts), [src/services/**tests**/schema_icon_service.test.ts](src/services/__tests__/schema_icon_service.test.ts), and any schema_recommendation tests so they no longer depend on `new OpenAI()`. Add unit tests for the adapter (e.g. message conversion, provider selection from config).
-- **Integration**: Optionally add one integration test that runs with an alternative provider (e.g. `openai_compatible` with a mock server or a real key in CI secret) to validate the path end-to-end.
-
-## 6. Documentation and foundation
-
-- **.env.example**: Add commented `NEOTOMA_LLM_PROVIDER` and provider-specific vars; note that `OPENAI_API_KEY` alone keeps current behavior.
-- **Developer docs**: Short section in [docs/developer/getting_started.md](docs/developer/getting_started.md) or a new `docs/developer/llm_providers.md` describing supported providers, env vars, and limitations (e.g. vision only for OpenAI/Azure; embeddings 1536).
-- **vector_ops.md**: Update [docs/subsystems/vector_ops.md](docs/subsystems/vector_ops.md) to say embeddings can use the configured LLM provider when it supports embeddings (and 1536 dims).
-- **1Password / foundation**: If [foundation scripts](foundation/scripts/README.md) or env mappings reference `OPENAI_API_KEY`, add optional mappings for the new provider keys so teams can sync them the same way.
-
-## 7. Embedding dimension constraint
-
-- **Fixed 1536**: Local entity embeddings and sqlite-vec use 1536. The adapter (or embeddings.ts) must only return 1536-dim vectors for entity/schema search. Document that:
-  - OpenAI and Azure (same model) are 1536.
-  - If another provider is used for embeddings, either use a model that outputs 1536 or keep embeddings on OpenAI-only and allow chat to use another provider (split config: chat provider vs embedding provider) for a first version.
-
-## Implementation order
-
-1. Config: add `NEOTOMA_LLM_PROVIDER` and provider-specific env, `config.llm`, `isLlmConfigured()`.
-2. Adapter: implement `createChatCompletion` for `openai` and `openai_compatible` (no new deps); then add `anthropic` and `azure` if desired.
-3. Embeddings: route through adapter or keep in embeddings.ts with provider dispatch; enforce 1536.
-4. Migrate llm_extraction, schema_icon_service, schema_recommendation to adapter; replace all `openai` / `config.openaiApiKey` checks with `isLlmConfigured()` and adapter.
-5. Update actions, server, CLI (errors, init prompts, interpretation config).
-6. Tests: switch to mocking adapter; add adapter unit tests.
-7. Docs and .env.example.
-
-## Out of scope (for this plan)
-
-- Changing embedding dimension or supporting multiple dimensions.
-- Per-request provider selection (only env-driven default).
-- Streaming chat responses (unless already used somewhere).
-

package/.cursor/plans/plan_migration_command_integrated.plan.md

@@ -1,393 +0,0 @@
----
-name: Plan Migration Command (Integrated with Commit)
-overview: "Create a plan migration system that automatically runs during /commit workflow. Reviews all plans in .cursor/plans, determines relevance, and migrates relevant ones to docs/proposals with modifications for future consideration. Integrated into commit workflow so proposals are automatically included in commits."
-todos:
-  - id: create-command-file
-    content: "Create .cursor/commands/migrate_plans.md with command specification (standalone version for manual use)"
-    status: pending
-  - id: integrate-commit-workflow
-    content: "Integrate plan migration into .cursor/commands/commit.md workflow - run after security audit, before staging"
-    status: pending
-  - id: create-proposals-dir
-    content: "Ensure docs/proposals/ directory exists (create if needed) and add README.md explaining proposal format"
-    status: pending
-  - id: implement-parsing
-    content: "Implement plan file parsing logic (frontmatter extraction, todo status counting, content analysis)"
-    status: pending
-  - id: implement-relevance
-    content: "Implement relevance checking (completion status, architecture alignment, duplicate detection)"
-    status: pending
-  - id: implement-conversion
-    content: "Implement plan-to-proposal conversion (format transformation, metadata addition, reference updates)"
-    status: pending
-  - id: implement-reporting
-    content: "Implement migration report generation showing what was migrated, archived, or removed"
-    status: pending
-  - id: add-proposal-template
-    content: "Create docs/proposals/PROPOSAL_TEMPLATE.md as reference for proposal format"
-    status: pending
-  - id: test-integration
-    content: "Test migration integration in commit workflow to ensure proposals are staged and committed correctly"
-    status: pending
----
-
-# Plan Migration Command (Integrated with Commit Workflow)
-
-## Context
-
-The `.cursor/plans/` directory contains many plan files from past work. Some are completed, some are obsolete, and some represent future work that should be preserved as proposals for later consideration. This command automates the review and migration process, and **runs automatically during the `/commit` workflow** so that migrated proposals are included in commits.
-
-## Integration with Commit Workflow
-
-**Location in Commit Workflow:**
-
-The plan migration runs **after security audit passes** and **before staging changes**:
-
-```mermaid
-flowchart TD
-    Start[Start Commit] --> Security[Security Audit]
-    Security -->|Pass| MigratePlans[Plan Migration]
-    Security -->|Fail| Abort[Abort Commit]
-    MigratePlans --> Stage[Stage Changes]
-    Stage --> Analyze[Change Analysis]
-    Analyze --> Commit[Commit & Push]
-    
-    MigratePlans -->|Creates proposals| Stage
-    MigratePlans -->|Updates .cursor/plans| Stage
-```
-
-**Why this placement:**
-- After security audit: Ensures clean state before creating new files
-- Before staging: Migrated proposals are automatically included in the commit
-- Non-blocking: If migration fails, commit can still proceed (with warning)
-
-## Command Structure
-
-**Standalone Command:** `.cursor/commands/migrate_plans.md` (for manual use)
-
-**Integrated Workflow:** Added to `.cursor/commands/commit.md` after security audit section
-
-## Purpose
-
-1. **Review all plans** in `.cursor/plans/` directory
-2. **Determine relevance** based on completion status and current architecture
-3. **Migrate relevant plans** to `docs/proposals/` with modifications
-4. **Archive or remove** obsolete plans
-5. **Auto-include in commit** - Migrated proposals are staged automatically
-
-## Relevance Criteria
-
-A plan is considered **relevant** if:
-
-1. **Has pending todos** - Not all work is completed
-2. **Architecture still applicable** - Plan aligns with current architecture (check against `docs/NEOTOMA_MANIFEST.md` and `docs/architecture/`)
-3. **Not superseded** - No newer plan or implementation covers the same work
-4. **Future work** - Represents enhancements, optimizations, or features for later consideration
-
-A plan is considered **obsolete** if:
-
-1. **Fully completed** - All todos marked `completed`
-2. **Architecture mismatch** - Conflicts with current architecture or has been superseded
-3. **Duplicate** - Multiple versions of same plan (keep most recent)
-
-## Implementation Steps
-
-### Step 1: Integration into Commit Workflow
-
-**File:** `.cursor/commands/commit.md`
-
-**Location:** After security audit section (around line 301), before nested repo handling:
-
-```markdown
-After security audit passes, proceed with:
-
-**PLAN MIGRATION** (Automatic, runs before staging):
-
-**Configuration:** Enable/disable in `foundation-config.yaml`:
-```yaml
-development:
-  commit:
-    migrate_plans: true  # Enable automatic plan migration
-```
-
-**If enabled**, automatically review and migrate plans:
-
-1. **Run plan migration:**
-   ```bash
-   # Execute plan migration logic
-   # (See migrate_plans.md for full implementation)
-   ```
-
-2. **Stage migrated proposals:**
-   ```bash
-   # Auto-stage any new proposal files created
-   if [ -d "docs/proposals" ]; then
-     git add docs/proposals/*.md 2>/dev/null || true
-   fi
-   ```
-
-3. **Log migration results:**
-   - Display summary of plans migrated/archived/removed
-   - Include in commit message if proposals were created
-
-4. **Continue with commit workflow** (nested repos, staging, etc.)
-```
-
-### Step 2: Plan Migration Logic
-
-**Core Implementation** (can be in script or inline):
-
-```bash
-PLANS_DIR=".cursor/plans"
-PROPOSALS_DIR="docs/proposals"
-
-# Create proposals directory if it doesn't exist
-mkdir -p "$PROPOSALS_DIR"
-
-# Get all plan files
-PLAN_FILES=$(find "$PLANS_DIR" -name "*.plan.md" -type f | sort)
-
-MIGRATED_COUNT=0
-ARCHIVED_COUNT=0
-REMOVED_COUNT=0
-
-for PLAN_FILE in $PLAN_FILES; do
-  # Parse plan and determine action
-  # (See detailed logic below)
-done
-
-# Generate summary
-echo "Plan migration complete: $MIGRATED_COUNT migrated, $ARCHIVED_COUNT archived, $REMOVED_COUNT removed"
-```
-
-### Step 3: Analyze Each Plan
-
-For each plan file:
-
-1. **Parse frontmatter** to extract:
-   - `name` - Plan name
-   - `overview` - Brief description
-   - `todos` - List of todos with status
-
-2. **Check completion status:**
-   ```bash
-   PENDING_COUNT=$(grep -c "status: pending" "$PLAN_FILE" || echo "0")
-   COMPLETED_COUNT=$(grep -c "status: completed" "$PLAN_FILE" || echo "0")
-   TOTAL_COUNT=$((PENDING_COUNT + COMPLETED_COUNT))
-   
-   if [ "$TOTAL_COUNT" -eq 0 ]; then
-     # No todos - treat as unknown status
-     STATUS="unknown"
-   elif [ "$PENDING_COUNT" -eq 0 ]; then
-     # All completed
-     STATUS="completed"
-   else
-     # Has pending work
-     STATUS="pending"
-   fi
-   ```
-
-3. **Check architecture alignment:**
-   - Read key sections of plan
-   - Compare against current architecture docs
-   - Flag if plan references obsolete patterns
-
-4. **Check for duplicates:**
-   - Compare plan names/overviews
-   - If multiple versions exist, keep most recent
-
-### Step 4: Determine Action
-
-For each plan, classify as:
-
-- **Migrate to proposals** - Relevant future work (has pending todos, architecture aligned)
-- **Archive** - Completed but worth preserving (all todos completed, still relevant)
-- **Remove** - Obsolete or duplicate (architecture mismatch, superseded, duplicate)
-
-### Step 5: Convert Plan to Proposal Format
-
-When migrating to proposals:
-
-1. **Remove todos section** from frontmatter - Proposals don't need task tracking
-2. **Add proposal metadata:**
-   ```yaml
-   ---
-   title: "[Original Plan Name]"
-   status: "proposal"
-   source_plan: "[original-plan-filename]"
-   migrated_date: "[ISO date]"
-   priority: "p0|p1|p2|p3" # Extract from plan if present
-   estimated_effort: "[if mentioned in plan]"
-   ---
-   ```
-
-3. **Add proposal context section:**
-   ```markdown
-   ## Proposal Context
-   
-   This proposal was migrated from a plan created on [date]. 
-   Original plan: `.cursor/plans/[filename]`
-   
-   **Status:** [Relevant/Partially Complete/Architectural Enhancement]
-   **Rationale for Migration:** [Why this is still relevant]
-   **Completion Status:** [X/Y todos completed]
-   ```
-
-4. **Preserve plan content** - Keep all technical details, architecture diagrams, implementation notes
-5. **Update references** - Fix any broken links or update paths
-6. **Add implementation notes** - If plan is partially complete, note what's already done
-
-### Step 6: File Naming Convention
-
-Proposal files should use descriptive names:
-
-```
-docs/proposals/[kebab-case-description].md
-```
-
-Examples:
-- `schema-evolution-scaling.md`
-- `gdpr-compliance-immutability.md`
-- `agent-trust-framework.md`
-
-### Step 7: Auto-Staging in Commit Workflow
-
-After migration completes:
-
-```bash
-# Stage any new proposal files
-if [ -d "docs/proposals" ]; then
-  NEW_PROPOSALS=$(git status --porcelain docs/proposals/*.md 2>/dev/null | grep "^??" | cut -c4-)
-  if [ -n "$NEW_PROPOSALS" ]; then
-    echo "📝 Staging migrated proposals..."
-    git add docs/proposals/*.md
-    echo "  Staged: $(echo "$NEW_PROPOSALS" | wc -l) proposal(s)"
-  fi
-fi
-
-# Stage any updates to .cursor/plans (if plans were archived/removed)
-if git status --porcelain .cursor/plans/ | grep -q .; then
-  echo "📝 Staging plan updates..."
-  git add .cursor/plans/
-fi
-```
-
-### Step 8: Include in Commit Message
-
-Add to commit message if proposals were created:
-
-```markdown
-## Plan Migration
-
-Migrated [N] plans to proposals:
-- [plan-name] → docs/proposals/[proposal-name]
-- ...
-
-Archived [N] completed plans:
-- [plan-name] → docs/proposals/archived/[plan-name]
-- ...
-```
-
-## Standalone Command
-
-**File:** `.cursor/commands/migrate_plans.md`
-
-For manual execution (outside of commit workflow):
-
-- Same logic as integrated version
-- Can be run independently: `/migrate_plans`
-- Useful for bulk migration or review without committing
-
-## Proposal Format Template
-
-```markdown
----
-title: "[Plan Name]"
-status: "proposal"
-source_plan: "[original-filename]"
-migrated_date: "2026-01-22"
-priority: "p1"
-estimated_effort: "[if available]"
----
-
-# [Plan Name]
-
-## Proposal Context
-
-This proposal was migrated from `.cursor/plans/[original-filename]` on [date].
-
-**Original Status:** [pending/completed/partial]
-**Relevance:** [Why this is still relevant for future consideration]
-**Architecture Alignment:** [Verified/Needs Review/Conflicts]
-**Completion Status:** [X/Y todos completed at time of migration]
-
-## Overview
-
-[Original overview from plan]
-
-## Technical Details
-
-[Original plan content - architecture, implementation notes, diagrams]
-
-## Implementation Considerations
-
-[Any notes about what's already done, what conflicts exist, what needs updating]
-
-## References
-
-- Original plan: `.cursor/plans/[filename]`
-- Related docs: [links to relevant architecture/spec docs]
-```
-
-## Edge Cases
-
-1. **Malformed frontmatter** - Skip or attempt to parse manually, log warning
-2. **Missing todos** - Treat as "unknown status", require manual review (don't auto-migrate)
-3. **Conflicting architecture** - Flag for manual review, don't auto-migrate
-4. **Very old plans** - Check modification date, may need special handling
-5. **Plans referencing deleted files** - Update or remove broken references
-6. **Migration fails during commit** - Log warning but don't block commit (non-critical)
-
-## User Interaction
-
-**During Commit Workflow:**
-- **Automatic** - No user interaction required
-- **Non-blocking** - If migration fails, commit proceeds with warning
-- **Summary in commit message** - Shows what was migrated
-
-**Standalone Command:**
-- **Show preview** of what will be migrated before proceeding
-- **Ask for confirmation** on ambiguous cases
-- **Generate report** showing all actions taken
-
-## Configuration
-
-Add to `foundation-config.yaml`:
-
-```yaml
-development:
-  commit:
-    migrate_plans: true  # Enable automatic plan migration during commit
-    migrate_plans_config:
-      proposals_dir: "docs/proposals"
-      archive_completed: true
-      auto_remove_obsolete: false  # Require manual confirmation for removal
-      relevance_check:
-        check_architecture: true
-        check_completion: true
-        check_duplicates: true
-```
-
-## Testing Strategy
-
-1. **Test integration** - Run `/commit` with plan migration enabled
-2. **Verify staging** - Ensure proposals are automatically staged
-3. **Verify commit message** - Check that migration summary is included
-4. **Test edge cases** - Malformed plans, missing todos, architecture conflicts
-5. **Test standalone** - Verify `/migrate_plans` works independently
-
-## Rollback Strategy
-
-- **Non-destructive** - Original plans remain in `.cursor/plans/` until explicitly removed
-- **Proposals are additive** - Can be deleted if migration was incorrect
-- **Git history** - All changes tracked in commit history