neotoma 0.3.0 → 0.3.2

package/docs/developer/developer_preview_storage.md

@@ -1,35 +0,0 @@
-# Developer preview storage
-
-## Scope
-
-This document states the storage stance for the Neotoma **developer preview**: what is supported and what is not. It does not define migration or deployment procedures.
-
-## Developer preview: local storage only
-
-For the developer preview, **only local storage is supported.**
-
-- **Database:** SQLite at `./data/neotoma.db` (development) or `./data/neotoma.prod.db` (production). Set `NEOTOMA_DATA_DIR` to change the data root.
-- **Raw file storage:** Local directory at `./data/sources/` (dev) or `./data/sources_prod/` (prod). Set `NEOTOMA_RAW_STORAGE_DIR` if needed.
-- **Backend:** Local backend only in developer preview.
-
-**Why local-only for the preview:** Local storage keeps the preview easy to run, avoids external dependencies, and makes truth validation and determinism easier to reason about. All operations stay on your machine with full control over data and audit trails.
-
-## What is not in the developer preview
-
-- **Remote backends** (e.g. PostgreSQL, S3, cloud storage) are out of scope for the preview.
-
-When remote storage is reintroduced (in a future release), it will be documented in [Getting started](getting_started.md) and the main [README](../../README.md).
-
-## Quick reference
-
-| Need                         | Developer preview | Later (when supported) |
-|-----------------------------|-------------------|-------------------------|
-| Run Neotoma locally         | Local (SQLite + local files) | Same or remote backend |
-| Truth validation / determinism | Local preferred   | Local or remote         |
-| Multi-user / hosted         | Not in preview    | Remote backend          |
-| No external service         | Local only        | Local only              |
-
-## Related
-
-- [Getting started](getting_started.md) – Full setup and env vars
-- [README – Developer preview](../../README.md#developer-preview) – Guarantees and who the preview is for

package/docs/developer/developer_release_manual_test_checklist.md

@@ -1,209 +0,0 @@
-# Developer Release Manual Test Checklist
-
-_(Manual validation before releasing a developer-facing release)_
-
-## Scope
-
-This document is a checklist of functionality across the repository that you should manually test before releasing a developer release. It complements the automated pre-release validation in `docs/developer/pre_release_validation_rules.mdc` and release-specific integration tests in `docs/releases/{version}/integration_tests.md`.
-
-## When to Use
-
-- Before marking a release as `ready_for_deployment`
-- After automated tests pass and before deployment
-- When cutting a developer-focused release (MCP, CLI, API, setup flows)
-
-## Prerequisites
-
-- [ ] Pre-release validation checklist completed (`docs/developer/pre_release_validation_rules.mdc`): type-check, lint, build, migrations, test suite, MCP startup
-- [ ] `.env` (or `.env.dev`) configured for the backend you are testing (local SQLite)
-
----
-
-## 1. Installation and Setup
-
-### 1.1 From repository (developer path)
-
-- [ ] `git clone` (or fresh pull), `npm install`, `npm run type-check` succeeds
-- [ ] `neotoma init` (from repo root) creates `data/`, SQLite DB, and `.env.example` (or prompts)
-- [ ] When init prompts for key-derived auth, choosing to create a key creates the encryption key
-- [ ] `neotoma init --data-dir /path/to/custom` uses custom data directory
-- [ ] `neotoma storage info` shows correct backend and paths
-
-### 1.2 From npm (user path)
-
-- [ ] `npm install -g neotoma` (or `npm link` from repo) installs `neotoma` binary
-- [ ] `neotoma init` creates `~/neotoma/data/` (or configured dir), DB, and env template
-- [ ] `neotoma storage info` shows expected paths and backend
-
-### 1.3 Environment and backend
-
-- [ ] Server uses SQLite and local `data/sources/`
-- [ ] `npm run copy:env` (in worktree) copies env from main repo when documented
-
----
-
-## 2. CLI
-
-### 2.1 Auth and config
-
-- [ ] `neotoma auth status` shows auth mode (none / dev-token / key-derived) and does not require login
-- [ ] `neotoma auth login` (local) completes; with `--dev-stub` skips redirect when applicable
-- [ ] `neotoma auth logout` clears stored OAuth credentials
-- [ ] CLI uses `--base-url` and config from `~/.config/neotoma/config.json` as documented
-
-### 2.2 Read-only commands (no MCP, against running API)
-
-Start API (e.g. `npm run dev:server` or `npm run start:api`) then:
-
-- [ ] `neotoma entities list`, `--type`, `--search`, `--limit`, `--offset`, `--include-merged`
-- [ ] `neotoma entities get <id>`
-- [ ] `neotoma sources list` with optional filters
-- [ ] `neotoma observations list` with `--entity-id` / `--entity-type`
-- [ ] `neotoma relationships list <entityId>` with `--direction`
-- [ ] `neotoma timeline list` with date/type filters
-- [ ] `neotoma schemas list`, `neotoma schemas get <entityType>`
-- [ ] `neotoma stats` returns expected structure
-
-### 2.3 Write and utility commands
-
-- [ ] `neotoma store --file <path>` and/or `neotoma store --json '[...]'` create sources/entities as expected
-- [ ] `neotoma upload <filePath>` uploads and processes file (if supported)
-- [ ] `neotoma analyze <filePath>` runs analysis (if supported)
-- [ ] `neotoma watch` (local backend) streams changes; `--tail`, `--json`, `--human` behave as documented
-- [ ] `neotoma backup create` / `neotoma backup restore --from <dir>` work against local data
-- [ ] `neotoma logs tail` (and `--decrypt` if encryption on) show log output
-- [ ] `neotoma request --operation <id>` with `--params` or `--body`/`--query`/`--path` matches OpenAPI
-
-### 2.4 Developer helpers
-
-- [ ] `neotoma dev list` lists npm scripts
-- [ ] `neotoma dev <script>` runs `npm run <script>` from repo root
-
----
-
-## 3. MCP Server (stdio)
-
-### 3.1 Startup and protocol
-
-- [ ] `npm run dev` (or `npm run watch:mcp:stdio`) starts MCP server without crashing
-- [ ] No stray console.log/console.error to stdout (would break JSON-RPC)
-- [ ] Cursor (or other MCP client) sees the server when configured in `.cursor/mcp.json` with correct `command` and `cwd`
-
-### 3.2 Core tools (smoke)
-
-With MCP client connected:
-
-- [ ] `store` with `entities` array (e.g. one `contact` or `task`) creates source and entities
-- [ ] `store` with `file_content` (base64) + `mime_type` (e.g. PDF) creates source and runs interpretation when `interpret=true`
-- [ ] `retrieve_entities` with `entity_type` returns stored entities
-- [ ] `retrieve_entities` with `search` returns semantically similar entities when OPENAI_API_KEY set (local embeddings)
-- [ ] `retrieve_entity_snapshot` for an entity ID returns snapshot and provenance
-- [ ] `list_observations` for an entity returns observations
-- [ ] `list_entity_types` returns schema list; optional keyword filter works
-- [ ] `retrieve_entity_by_identifier` finds entity by name/email when applicable
-- [ ] `retrieve_entity_by_identifier` semantic fallback when keyword returns 0 (local embeddings)
-- [ ] `retrieve_related_entities` and `retrieve_graph_neighborhood` return expected structure when data exists
-
-### 3.3 Mutations and lifecycle
-
-- [ ] `correct` updates field and snapshot reflects correction (priority over AI)
-- [ ] `create_relationship` creates typed relationship; `list_relationships` shows it
-- [ ] `merge_entities` merges two entities; merged entity excluded from default `retrieve_entities`
-- [ ] `reinterpret` on a source creates new interpretation run and new observations; existing observations unchanged
-- [ ] `delete_entity` soft-deletes; entity excluded from default queries
-- [ ] `restore_entity` restores soft-deleted entity
-
-### 3.4 Resources (if exposed)
-
-- [ ] Resource `neotoma://entity_types` (or equivalent) returns entity types
-- [ ] Resource for entity by ID returns expected payload
-
-### 3.5 Auth (OAuth)
-
-- [ ] When MCP OAuth is required, authorize flow completes and subsequent tool calls are scoped to user
-- [ ] Cross-user isolation: User B cannot see or modify User A’s entities/sources (see IT-006 in release report)
-
----
-
-## 4. HTTP API
-
-With API running (e.g. `npm run dev:server` on port 8080):
-
-- [ ] `GET /api/me` returns current user or guest when anonymous sign-in enabled
-- [ ] `POST /api/entities/query` with body returns entities; pagination and filters work
-- [ ] `GET /api/entities/{id}` returns entity snapshot
-- [ ] `GET /api/sources` returns sources list
-- [ ] `POST /api/observations/query` returns observations for entity/type
-- [ ] `GET /api/timeline` returns timeline events with optional filters
-- [ ] `GET /api/schemas`, `GET /api/schemas/{entity_type}` return schema info
-- [ ] `POST /api/observations/create` (or equivalent) creates observation when supported
-- [ ] OAuth: `GET /api/mcp/oauth/authorize` and callback/token flow work for MCP Connect
-
----
-
-## 5. Frontend (optional for developer release)
-
-If the release includes UI changes or you want to validate the full stack:
-
-- [ ] `npm run build:ui` succeeds
-- [ ] `npm run dev:ui` (or full stack) serves UI; login/signup (or guest) works
-- [ ] Dashboard loads; entities/sources/timeline/schemas views load without errors
-- [ ] Entity detail and source detail pages open and show data
-- [ ] Quick entry (contact, task, event, transaction) creates data when implemented
-- [ ] MCP setup/integration pages (Cursor, ChatGPT, etc.) load and instructions/copy are correct
-- [ ] File upload (if used) uploads and appears in sources
-- [ ] Settings (theme, keys, connections) save and persist
-
----
-
-## 6. Storage and Data
-
-### 6.1 Local backend
-
-- [ ] Data directory contains `neotoma.db`, `sources/`, and optionally `logs/` (includes `events.log`)
-- [ ] After `store` (file), file exists under `sources/` with expected naming (e.g. by hash)
-- [ ] `neotoma backup create` includes DB, sources, logs; checksums in manifest
-
----
-
-## 7. Release-Specific Manual Tests
-
-For each release, use the manual test cases defined in that release’s integration tests and release report:
-
-- [ ] Open `docs/releases/{version}/integration_tests.md` and run any listed manual tests
-- [ ] Open `docs/releases/{version}/release_report.md` Section 9 (Testing Guidance) and execute every manual test case (e.g. IT-001 through IT-010 for v0.2.0)
-- [ ] Document Pass/Fail per test case; fix failures before deployment
-
-Example flows often covered there: raw file ingestion (IT-001), deduplication (IT-002), reinterpretation immutability (IT-003), correction override (IT-004), entity merge (IT-005), cross-user isolation (IT-006), quota (IT-007), merged entity exclusion (IT-008), provenance chain (IT-009), and any additional cases for the release.
-
----
-
-## 8. Smoke Command Sequence (quick pass)
-
-After a full manual pass, a minimal smoke sequence:
-
-1. `npm run type-check && npm run lint && npm run build:server && npm run build:ui`
-2. `npm test`
-3. Start API: `npm run start:api` (or `npm run dev:server`)
-4. CLI: `neotoma auth status`, `neotoma entities list --limit 5`, `neotoma stats`
-5. MCP: Connect Cursor; call `store` with one entity; call `retrieve_entities`; verify result
-6. (Optional) Load frontend in browser; open Dashboard and one entity
-
----
-
-## 9. Sign-Off
-
-- [ ] All sections above relevant to this release are completed
-- [ ] All release-specific manual test cases from `integration_tests.md` and release report Section 9 are executed and passed
-- [ ] No critical or blocking issues open; known issues documented
-- [ ] Release status updated to `ready_for_deployment` only after this sign-off
-
-## Related Documents
-
-- **Pre-release validation (automated):** `docs/developer/pre_release_validation_rules.mdc`
-- **CLI reference:** `docs/developer/cli_reference.md`
-- **Getting started:** `docs/developer/getting_started.md`
-- **MCP spec:** `docs/specs/MCP_SPEC.md`
-- **Release integration tests:** `docs/releases/{version}/integration_tests.md`
-- **Release report (Testing Guidance):** `docs/releases/{version}/release_report.md` Section 9
-- **Deployment checklist (example):** `docs/releases/v0.2.15/deployment_checklist.md`

package/docs/developer/development_workflow.md

@@ -1,308 +0,0 @@
-# Development Workflow Guide
-## Scope
-This document covers:
-- Git branch naming and strategy
-- Pull request creation and review process
-- Code review criteria
-- Commit message conventions
-- Feature Unit integration workflow
-This document does NOT cover:
-- Local environment setup (see `docs/developer/getting_started.md`)
-- Feature Unit specification (see `docs/feature_units/standards/feature_unit_spec.md`)
-- Deployment procedures (see `docs/infrastructure/deployment.md`)
-## Branch Strategy
-### Main Branches
-- **`main`**: Production-ready code (protected, requires PR)
-- **`dev`**: Integration branch for MVP development (protected, requires PR)
-### Feature Branches
-**Naming Convention:**
-```
-feature/FU-XXX-short-description
-```
-Examples:
-- `feature/FU-101-entity-resolution`
-- `feature/FU-400-timeline-view`
-- `feature/FU-702-billing-integration`
-**Rules:**
-- Branch from `dev` (not `main`)
-- One Feature Unit per branch (atomic changes)
-- Descriptive names matching Feature Unit ID
-### Bugfix Branches
-**Naming Convention:**
-```
-bugfix/FU-XXX-issue-description
-```
-Examples:
-- `bugfix/FU-101-deterministic-entity-ids`
-- `bugfix/FU-400-timeline-sorting`
-### Hotfix Branches
-**Naming Convention:**
-```
-hotfix/critical-issue-description
-```
-**Rules:**
-- Branch from `main` (for production fixes)
-- Merge to both `main` and `dev`
-- Use sparingly (only for critical production issues)
-## Development Workflow
-### Step 1: Create Feature Branch (Worktree Recommended)
-**Recommended: Use Git Worktrees**
-Each Feature Unit should be developed in its own worktree for isolation and parallel development:
-```bash
-# From main repo root
-cd /path/to/neotoma
-# Ensure dev is up to date
-git fetch origin
-git checkout dev
-git pull origin dev
-# Create worktree for this Feature Unit (creates branch from current branch, which should be dev)
-git worktree add ../neotoma-FU-XXX -b feature/FU-XXX-short-description
-# Navigate to worktree
-cd ../neotoma-FU-XXX
-# Verify branch is based on dev
-git branch --show-current  # Should show feature/FU-XXX-short-description
-git log --oneline -1       # Should show latest dev commit
-# Setup worktree environment (copies .env files)
-npm run copy:env || node scripts/copy-env-to-worktree.js
-# Install dependencies in worktree
-npm install
-# Push branch to remote
-git push -u origin feature/FU-XXX-short-description
-```
-**Benefits of Worktrees:**
-- **Isolation:** Each Feature Unit has its own `node_modules`, `.env`, and build artifacts
-- **Parallel Development:** Work on multiple Feature Units simultaneously without conflicts
-- **Clean Context Switching:** Each worktree is independent
-- **Environment Management:** Automatic `.env` copying via `scripts/copy-env-to-worktree.js`
-**Alternative: Traditional Branching (if not using worktrees)**
-```bash
-# Ensure you're on dev and up to date
-git checkout dev
-git pull origin dev
-# Create feature branch
-git checkout -b feature/FU-XXX-short-description
-# Push to remote (sets upstream)
-git push -u origin feature/FU-XXX-short-description
-```
-**Note:** See `.cursor/rules/worktree_env.md` for worktree environment setup details.
-### Step 2: Implement Feature Unit
-1. **Load relevant documentation:**
-   - `docs/NEOTOMA_MANIFEST.md`: Foundational principles
-   - Foundation rules in `.cursor/rules/`: Agent instructions and documentation loading order
-   - Feature Unit spec (if exists in `docs/feature_units/completed/`)
-   - Relevant subsystem docs
-2. **Write code following:**
-   - Architecture layer boundaries (see `docs/architecture/architecture.md`)
-   - Determinism rules (see `docs/architecture/determinism.md`)
-   - Error handling (see `docs/subsystems/errors.md`)
-   - Testing standards (see `docs/testing/testing_standard.md`)
-3. **Write tests:**
-   - Unit tests for pure functions
-   - Integration tests for services
-   - E2E tests for UI flows (if applicable)
-4. **Verify locally:**
-   ```bash
-   npm run lint
-   npm run type-check
-   npm test
-   ```
-### Step 3: Commit Changes
-**Commit Message Format:**
-```
-FU-XXX: Brief description
-- Detailed change 1
-- Detailed change 2
-References: docs/specs/MVP_FEATURE_UNITS.md
-```
-**Examples:**
-```
-FU-101: Implement entity resolution
-- Add normalizeEntityValue function
-- Add generateEntityId with hash-based IDs
-- Add entity resolution service
-- Add unit tests for determinism
-References: docs/specs/MVP_FEATURE_UNITS.md
-```
-**Commit Rules:**
-- One logical change per commit
-- Reference Feature Unit ID in message
-- Include "References:" line pointing to relevant docs
-- Keep commits atomic (easy to review, revert)
-
-**Cursor IDE — disable "Made-with: Cursor" trailer:** Cursor adds a `--trailer "Made-with: Cursor"` to commits made through its UI or agent. To turn this off: **Cursor Settings → Agents → Attribution** and toggle Attribution off. (See [Cursor forum](https://forum.cursor.com/t/trailer-in-git-commit-messages-cant-be-stopped/150552).)
-
-### Step 4: Push and Create Pull Request
-```bash
-# Push commits
-git push
-# Create PR via GitHub UI or CLI
-gh pr create --base dev --title "FU-XXX: Feature Description" --body "PR body"
-```
-**PR Title Format:**
-```
-FU-XXX: Feature Description
-```
-**PR Body Template:**
-```markdown
-## Feature Unit
-- **ID**: FU-XXX
-- **Priority**: P0/P1/P2
-- **Spec**: [Link to spec if exists]
-## Changes
-- Change 1
-- Change 2
-## Testing
-- [ ] Unit tests added/updated
-- [ ] Integration tests added/updated
-- [ ] E2E tests added/updated (if UI)
-- [ ] All tests passing locally
-## Documentation
-- [ ] Code comments added
-- [ ] Subsystem docs updated (if patterns changed)
-- [ ] Feature Unit spec updated (if Class 1 error found)
-## Risk Assessment
-- **Risk Level**: Low/Medium/High (see `docs/private/governance/risk_classification.md`)
-- **Breaking Changes**: Yes/No
-- **Migration Required**: Yes/No
-## Checklist
-- [ ] Follows architectural layer boundaries
-- [ ] Maintains determinism (same input → same output)
-- [ ] Error handling uses ErrorEnvelope
-- [ ] No PII in logs
-- [ ] Respects Truth Layer boundaries (no strategy/execution logic)
-```
-## Code Review Process
-### Review Criteria
-**MUST Verify:**
-1. **Architectural Compliance:**
-   - Respects layer boundaries (no upward dependencies)
-   - Follows determinism rules
-   - Maintains Truth Layer purity (no strategy/execution logic)
-2. **Code Quality:**
-   - TypeScript types are correct
-   - Error handling is structured (ErrorEnvelope)
-   - No PII in logs or error messages
-   - Tests cover critical paths
-3. **Documentation:**
-   - Code is commented where complex
-   - Subsystem docs updated if patterns changed
-   - Feature Unit spec updated if Class 1 errors found
-4. **Testing:**
-   - Unit tests for pure functions
-   - Integration tests for services
-   - E2E tests for UI flows
-   - Regression tests for bug fixes
-### Review Labels
-- **`approved`**: Ready to merge (all criteria met)
-- **`changes-requested`**: Needs fixes before merge
-- **`needs-docs`**: Code is fine, but documentation needs updates
-- **`needs-tests`**: Code is fine, but test coverage insufficient
-- **`high-risk`**: Requires additional review (see `docs/private/governance/risk_classification.md`)
-### Review Response Time
-- **P0 Features**: Review within 4 hours
-- **P1 Features**: Review within 24 hours
-- **P2 Features**: Review within 48 hours
-## Merge Process
-### Before Merging
-1. **All CI checks pass:**
-   - Lint passes
-   - Type check passes
-   - Tests pass
-   - Coverage meets thresholds
-2. **Review approved:**
-   - At least one approval
-   - No "changes-requested" label
-   - High-risk PRs require 2 approvals
-3. **Branch is up to date:**
-   ```bash
-   git checkout dev
-   git pull origin dev
-   git checkout feature/FU-XXX-short-description
-   git rebase dev  # or merge dev into feature branch
-   ```
-### Merge Strategy
-**For MVP Development:**
-- Use **"Squash and merge"** to keep `dev` history clean
-- PR title becomes commit message
-- Feature Unit ID preserved in commit message
-**After Merge:**
-**If using worktree:**
-```bash
-# From main repo root
-git worktree remove ../neotoma-FU-XXX
-# Or if worktree still has uncommitted changes:
-git worktree remove --force ../neotoma-FU-XXX
-# The branch will be automatically deleted from remote after merge
-# If you need to delete local branch tracking:
-git branch -d feature/FU-XXX-short-description
-```
-**If using traditional branching:**
-```bash
-# Delete local branch
-git checkout dev
-git pull origin dev
-git branch -d feature/FU-XXX-short-description
-```
-## Feature Unit Integration
-### When Feature Unit is Complete
-1. **Update Feature Unit Status:**
-   - Mark as complete in `docs/specs/MVP_FEATURE_UNITS.md`
-   - Move spec to `docs/feature_units/completed/FU-XXX/` (if detailed spec exists)
-2. **Update Documentation:**
-   - Update subsystem docs if patterns changed
-   - Add error codes to `docs/reference/error_codes.md` (if new codes added)
-   - Update architecture docs if structural changes
-3. **Verify Integration:**
-   - Run full test suite: `npm test`
-   - Verify E2E tests: `npm run test:e2e` (if applicable)
-   - Check metrics/observability (if applicable)
-## Conflict Resolution
-### When Conflicts Occur
-1. **Rebase on latest dev:**
-   ```bash
-   git checkout feature/FU-XXX-short-description
-   git fetch origin
-   git rebase origin/dev
-   ```
-2. **Resolve conflicts:**
-   - Edit conflicted files
-   - Keep changes that align with Feature Unit spec
-   - Verify tests still pass after resolution
-3. **Continue rebase:**
-   ```bash
-   git add <resolved-files>
-   git rebase --continue
-   ```
-4. **Force push (if already pushed):**
-   ```bash
-   git push --force-with-lease
-   ```
-**Note:** Only force push to feature branches, never to `dev` or `main`.
-## Agent Instructions
-### When to Load This Document
-Load when:
-- Creating a new feature branch
-- Preparing a pull request
-- Reviewing code changes
-- Resolving merge conflicts
-- Understanding git workflow
-### Required Co-Loaded Documents
-- `docs/NEOTOMA_MANIFEST.md`: Foundational principles
-- `docs/feature_units/standards/feature_unit_spec.md`: Feature Unit structure
-- `docs/private/governance/risk_classification.md`: Risk assessment
-### Constraints Agents Must Enforce
-1. **Always branch from `dev`**: Never from `main` (except hotfixes)
-2. **One Feature Unit per branch**: Keep changes atomic
-3. **Use worktrees for isolation**: Each Feature Unit should have its own worktree when possible
-4. **Setup worktree environment**: Run `npm run copy:env` or `node scripts/copy-env-to-worktree.js` after creating worktree
-5. **Reference Feature Unit ID**: In commit messages and PR titles
-6. **Follow commit message format**: Include "References:" line
-7. **Verify tests pass**: Before creating PR
-8. **Update documentation**: If patterns or architecture change
-### Forbidden Patterns
-- Committing directly to `dev` or `main`
-- Mixing multiple Feature Units in one branch
-- Force pushing to `dev` or `main`
-- Skipping code review
-- Merging without tests passing
-- Committing secrets or API keys

package/docs/developer/environment/CONNECTOR_SECRET_KEY_SETUP.md

@@ -1,96 +0,0 @@
-# CONNECTOR_SECRET_KEY Setup
-
-## Overview
-
-`CONNECTOR_SECRET_KEY` is a cryptographic key used to encrypt OAuth tokens for external connectors. Unlike other credentials (e.g., OpenAI), this key is **generated locally** for each environment rather than synced from 1Password.
-
-## Why Generate Locally?
-
-1. **Repo-specific**: Each repository/environment should have its own unique key
-2. **No external source**: It's not a credential from an external service
-3. **One-time generation**: Generate once, keep forever (changing it breaks existing encrypted data)
-4. **Local storage**: Stored in `.env` (gitignored), not in 1Password
-
-## Quick Setup
-
-### Generate the Key
-
-```bash
-npm run generate:connector-key
-```
-
-This will:
-- Generate a secure random 32-character key
-- Add it to your `.env` file
-- Skip if the key already exists
-
-### Manual Generation
-
-If you prefer to generate manually:
-
-```bash
-# Generate a random key
-openssl rand -base64 24
-
-# Or using Python
-python3 -c "import secrets; print(secrets.token_urlsafe(24))"
-```
-
-Then add to your `.env`:
-```bash
-CONNECTOR_SECRET_KEY="<generated-key-here>"
-```
-
-## Requirements
-
-- **Minimum length**: 16 characters (32+ recommended)
-- **Must remain static**: Never change this key once set
-- **Why?**: Changing it makes all existing encrypted OAuth tokens inaccessible
-
-## Environment Separation
-
-For different environments (dev/prod), you can:
-
-1. **Same key for both** (simpler, less secure):
-   - Use the same `CONNECTOR_SECRET_KEY` in both environments
-   - Works if you don't need strict separation
-
-2. **Different keys** (recommended):
-   - Development: Generate locally, store in `.env`
-   - Production: Generate separately, store in production `.env` or deployment config
-   - The code uses `CONNECTOR_SECRET_KEY` for both, but you set different values per environment
-
-## Exclusion from 1Password Sync
-
-`CONNECTOR_SECRET_KEY` is excluded from 1Password sync in `foundation-config.yaml` because:
-- It's generated locally, not stored in 1Password
-- Each repo/environment should have its own key
-- It's not a shared credential
-
-## Security Notes
-
-- ✅ Key is stored in `.env` (gitignored)
-- ✅ Key is hashed (SHA-256) before use
-- ✅ Uses AES-256-GCM encryption
-- ⚠️ Never commit `.env` to git
-- ⚠️ Never change the key once OAuth tokens are encrypted with it
-
-## Troubleshooting
-
-### "CONNECTOR_SECRET_KEY must be defined"
-- Run `npm run generate:connector-key` to generate it
-- Or manually add it to `.env`
-
-### "Key must be at least 16 characters"
-- Ensure the generated key is at least 16 characters
-- The script generates 32-character keys by default
-
-### "Can't decrypt existing tokens"
-- You may have changed the key
-- You need the original key to decrypt existing tokens
-- If lost, you'll need to re-authenticate all connectors
-
-## See Also
-
-- [DEV_CONNECTOR_SECRET_KEY Explanation](DEV_CONNECTOR_SECRET_KEY_EXPLANATION.md) - What the key does
-- [Environment Variable Management](../environment/README.md) - General env var docs