neotoma 0.3.0 → 0.3.2

package/docs/developer/environment/SETUP_ENV_MAPPINGS.md

@@ -1,256 +0,0 @@
-# Setting Up Environment Variable Mappings for 1Password Sync
-
-This guide helps you add mappings for Neotoma-specific environment variables to the `env_var_mappings` parquet data type.
-
-## Current Status
-
-✅ **Setup Complete:**
-- Foundation script is configured
-- Wrapper script is ready (`npm run sync:env`)
-- 1Password CLI is installed
-- Python 3 is available
-
-📋 **Next Steps:**
-- Add mappings for Neotoma environment variables (see list below)
-- Test the sync process
-
-## Required Environment Variables (from .env.example)
-
-Based on `.env.example`, these variables should be mapped to 1Password:
-
-### Database Configuration (Required)
-- `DEV_REMOTE_DB_PROJECT_ID` - Development remote database project ID
-- `DEV_REMOTE_DB_SERVICE_KEY` - Development remote database service role key
-- `REMOTE_DB_ACCESS_TOKEN` - Remote database Management API access token (optional)
-- `PROD_REMOTE_DB_PROJECT_ID` - Production remote database project ID (if needed)
-- `PROD_REMOTE_DB_SERVICE_KEY` - Production remote database service role key (if needed)
-
-### Connector Configuration
-- `DEV_CONNECTOR_SECRET_KEY` - Development connector secret key (min 16 chars)
-- `PROD_CONNECTOR_SECRET_KEY` - Production connector secret key (if needed)
-
-### OpenAI Configuration
-- `DEV_OPENAI_API_KEY` - Development OpenAI API key
-- `PROD_OPENAI_API_KEY` - Production OpenAI API key (if needed)
-
-**Note:** `OPENAI_API_KEY` already has mappings, but you may want to use `DEV_OPENAI_API_KEY` and `PROD_OPENAI_API_KEY` instead for consistency.
-
-### Plaid Configuration (Optional)
-- `DEV_PLAID_CLIENT_ID` - Development Plaid client ID
-- `DEV_PLAID_SECRET` - Development Plaid secret
-- `PLAID_ENV` - Plaid environment (usually "sandbox" or "production")
-- `PROD_PLAID_CLIENT_ID` - Production Plaid client ID (if needed)
-- `PROD_PLAID_SECRET` - Production Plaid secret (if needed)
-
-### Server Configuration (Optional - usually local)
-These can be excluded from 1Password sync as they're typically local development values:
-- `PORT` / `NEOTOMA_PORT` - MCP Server port (default: 3000)
-- `HTTP_PORT` / `NEOTOMA_HTTP_PORT` - HTTP Actions Server port (default: 8080 for development, 8180 for production)
-- `WS_PORT` / `NEOTOMA_WS_PORT` - WebSocket MCP Bridge port (default: 8280)
-- `ACTIONS_BEARER_TOKEN` - Bearer token for HTTP Actions API
-- `NEOTOMA_HOST_URL` - Host URL for API and MCP
-- `NEOTOMA_FRONTEND_URL` / `FRONTEND_URL` - Frontend URL for CORS
-- `NEOTOMA_MCP_PROXY_URL` / `MCP_PROXY_URL` - MCP proxy URL override
-- `NEOTOMA_OAUTH_REDIRECT_BASE_URL` / `OAUTH_REDIRECT_BASE_URL` - OAuth redirect base
-- `NEOTOMA_MCP_TOKEN_ENCRYPTION_KEY` / `MCP_TOKEN_ENCRYPTION_KEY` - OAuth token encryption
-- `NEOTOMA_MCP_CMD` / `MCP_CMD`, `NEOTOMA_MCP_ARGS` / `MCP_ARGS` - MCP WebSocket bridge config
-
-### Frontend Configuration (Optional - usually local)
-These can be excluded from 1Password sync:
-- `VITE_WS_PORT` - WebSocket port for frontend
-- `VITE_LOCAL_MCP_URL` - Local MCP WebSocket URL
-- `VITE_MCP_URL` - MCP URL
-- `VITE_API_BASE_URL` - API Base URL (frontend)
-- `VITE_AUTO_SEED_RECORDS` - Auto-seed records flag
-
-## How to Add Mappings
-
-### Step 1: Find 1Password References
-
-For each environment variable, you need to find its 1Password reference. Use the 1Password CLI:
-
-```bash
-# List all items in a vault
-op item list --vault="VaultName"
-
-# Get details of a specific item
-op item get "Item Name" --vault="VaultName" --format=json
-
-# Get a specific field reference
-op item get "Item Name" --vault="VaultName" --fields="fieldLabel"
-```
-
-The reference format is: `op://vault/item/field`
-
-### Step 2: Add Mapping via MCP Parquet Server
-
-Use the MCP parquet server to add a new record. The required fields are:
-- `env_var` (string, required) - The environment variable name
-- `op_reference` (string, required) - The 1Password reference (op://...)
-
-Optional but recommended fields:
-- `vault` (string) - Vault name
-- `item_name` (string) - Item name in 1Password
-- `field_label` (string) - Field label
-- `service` (string) - Service name (e.g., "database", "OpenAI", "Plaid")
-- `is_optional` (boolean) - Whether this variable is optional
-- `notes` (string) - Any additional notes
-- `environment_based` (boolean) - Whether this is environment-specific
-- `environment_key` (string) - Environment name if environment_based is true
-
-### Step 3: Example Mapping
-
-Here's an example for adding `DEV_REMOTE_DB_SERVICE_KEY`:
-
-```json
-{
-  "env_var": "DEV_REMOTE_DB_SERVICE_KEY",
-  "op_reference": "op://Private/your-item-id/field-id",
-  "vault": "Private",
-  "item_name": "Neotoma Database",
-  "field_label": "Development Service Role Key",
-  "service": "database",
-  "is_optional": false,
-  "environment_based": false,
-  "notes": "Development environment remote database service role key"
-}
-```
-
-### Step 4: Environment-Based Variables
-
-For variables that have different values for dev/prod (like OpenAI API keys), you can create separate mappings:
-
-```json
-{
-  "env_var": "DEV_OPENAI_API_KEY",
-  "op_reference": "op://Private/openai-item/dev-key-field",
-  "environment_based": true,
-  "environment_key": "development",
-  "service": "OpenAI"
-}
-```
-
-```json
-{
-  "env_var": "PROD_OPENAI_API_KEY",
-  "op_reference": "op://Private/openai-item/prod-key-field",
-  "environment_based": true,
-  "environment_key": "production",
-  "service": "OpenAI"
-}
-```
-
-## Quick Reference: Using MCP Tools
-
-You can use the MCP parquet tools directly. Here's the pattern:
-
-**Add a new mapping:**
-```javascript
-// Use mcp_parquet_add_record with:
-{
-  "data_type": "env_var_mappings",
-  "record": {
-    "env_var": "DEV_REMOTE_DB_SERVICE_KEY",
-    "op_reference": "op://Private/item/field",
-    "vault": "Private",
-    "item_name": "Neotoma Database",
-    "service": "database",
-    "is_optional": false,
-    "environment_based": false
-  }
-}
-```
-
-**Update an existing mapping:**
-```javascript
-// Use mcp_parquet_update_records with:
-{
-  "data_type": "env_var_mappings",
-  "filters": {
-    "env_var": "DEV_REMOTE_DB_SERVICE_KEY"
-  },
-  "updates": {
-    "op_reference": "op://Private/new-item/new-field"
-  }
-}
-```
-
-## Testing the Sync
-
-Once you've added mappings:
-
-1. **Sign in to 1Password:**
-   ```bash
-   op signin
-   ```
-
-2. **Run the sync:**
-   ```bash
-   npm run sync:env
-   ```
-
-3. **Verify the results:**
-   - Check that `.env` was updated
-   - Check that a backup was created in `.env.backups/`
-   - Verify the variables have the correct values
-
-## Excluding Variables
-
-If you want to exclude certain variables from being managed by 1Password (e.g., local development ports), add them to `foundation-config.yaml`:
-
-```yaml
-tooling:
-  env_management:
-    onepassword_sync:
-      default_exclusions:
-        - PORT
-        - NEOTOMA_PORT
-        - HTTP_PORT
-        - NEOTOMA_HTTP_PORT
-        - WS_PORT
-        - NEOTOMA_WS_PORT
-        - ACTIONS_BEARER_TOKEN
-        - NEOTOMA_HOST_URL
-        - NEOTOMA_FRONTEND_URL
-        - FRONTEND_URL
-        - NEOTOMA_MCP_PROXY_URL
-        - MCP_PROXY_URL
-        - NEOTOMA_OAUTH_REDIRECT_BASE_URL
-        - OAUTH_REDIRECT_BASE_URL
-        - NEOTOMA_MCP_TOKEN_ENCRYPTION_KEY
-        - MCP_TOKEN_ENCRYPTION_KEY
-        - NEOTOMA_MCP_CMD
-        - MCP_CMD
-        - NEOTOMA_MCP_ARGS
-        - MCP_ARGS
-        - VITE_WS_PORT
-        - VITE_LOCAL_MCP_URL
-        - VITE_MCP_URL
-        - VITE_API_BASE_URL
-        - VITE_AUTO_SEED_RECORDS
-```
-
-Or create `foundation-config.local.yaml` (gitignored) for instance-specific exclusions.
-
-## Troubleshooting
-
-### "Failed to resolve [variable]"
-- Verify the 1Password reference is correct
-- Ensure you have access to the vault/item
-- Check that the field name matches
-
-### "No environment variable mappings found"
-- Verify mappings exist in the parquet file
-- Check that `op_reference` doesn't start with `PLACEHOLDER_`
-- Ensure the MCP server can access the parquet file
-
-### Variables not syncing
-- Check if they're in the exclusion list
-- Verify the mapping exists and `op_reference` is valid
-- Check that `environment_based` and `environment_key` match your `ENVIRONMENT` variable
-
-## See Also
-
-- Main documentation: [README_1PASSWORD_SYNC.md](README_1PASSWORD_SYNC.md)
-- Foundation script: `foundation/scripts/op_sync_env_from_1password.py`
-- Configuration: `foundation-config.yaml`

package/docs/developer/environment_distinction_audit.md

@@ -1,43 +0,0 @@
-# Environment distinction audit (dev vs prod)
-
-## Purpose
-
-This document records how the codebase distinguishes development from production (local SQLite, CLI, API) and what was audited or changed so dev and prod can run in parallel without overwriting each other.
-
-## Scope
-
-- Local backend: SQLite path, raw storage, event log, logs, API background log/PID.
-- Out of scope: MCP token storage (single config file).
-
-## Implemented (env-specific)
-
-| Area | Dev default | Prod default | Override env var |
-|------|-------------|--------------|------------------|
-| SQLite DB | `data/neotoma.db` | `data/neotoma.prod.db` | (derived from `NEOTOMA_DATA_DIR` + env) |
-| Raw sources | `data/sources` | `data/sources_prod` | `NEOTOMA_RAW_STORAGE_DIR` |
-| Event log (file) | `data/logs/events.log` | `data/logs_prod/events.log` | `NEOTOMA_EVENT_LOG_PATH` |
-| Logs (CLI/backup) | `data/logs` | `data/logs_prod` | `NEOTOMA_LOGS_DIR` |
-
-**Event log vs logs:** The event-sourcing append-only log is a single file `events.log` inside the logs directory. All other application logs (CLI, API, session) also live under `data/logs/` with descriptive names (e.g. `session.log` for dev, `session.prod.log` for prod, `cli.<pid>.log`).
-| API background log dir | `~/.config/neotoma/logs` | `~/.config/neotoma/logs_prod` | (derived from `NEOTOMA_ENV`) |
-| API background PID file | `~/.config/neotoma/api.pid` | `~/.config/neotoma/api_prod.pid` | (derived from env) |
-| HTTP port | 8080 | 8021 | `NEOTOMA_HTTP_PORT` or `HTTP_PORT` |
-
-Environment is determined by `NEOTOMA_ENV`; `production` means prod defaults. `NEOTOMA_ENV` and `NEOTOMA_HTTP_PORT` are not in `.env.example` or the init template; set them at runtime (e.g. `NEOTOMA_ENV=production neotoma api start`) or in your shell profile if you want a fixed env or port.
-
-## CLI base URL and port choice
-
-When resolving the API base URL, the CLI uses: `--base-url` if set; otherwise session ports (`NEOTOMA_SESSION_DEV_PORT` / `NEOTOMA_SESSION_PROD_PORT`) when in a session; otherwise probe of 8180 and 8080. When **no server is detected**, the CLI falls back to port **8180** (prod). When one or two servers are found, port choice follows `--env`, `NEOTOMA_SESSION_ENV`, or `NEOTOMA_ENV` (e.g. prod → 8180, dev → 8080). See `src/cli/config.ts` `resolveBaseUrl()`.
-
-## Optional / not implemented
-
-- **Local storage for non-`sources` buckets** (`src/repositories/sqlite/` (storage adapter)): Path is `data/storage/<bucket>`. Could be made env-specific (e.g. `data/storage_prod/<bucket>`) for consistency if multiple buckets are used.
-- **Backup output directory**: Default `./backups`; could default to `./backups_prod` when running in prod.
-- **Restore target**: Restore could be env-aware so restores go to the correct env-specific dirs (more involved).
-
-## References
-
-- Config: `src/config.ts` (data dirs, ports).
-- CLI paths: `src/cli/index.ts` (storage info, backup, logs tail) and `src/cli/config.ts` (API log/PID paths).
-- Wipe script: `scripts/wipe-local-database.js` (uses env-specific subdirs when targeting prod).
-- Docs: `docs/developer/getting_started.md`, `docs/operations/runbook.md`, `docs/developer/cli_reference.md`.

package/docs/developer/fix_doc_inconsistencies_plan.md

@@ -1,63 +0,0 @@
-name: Fix Doc Inconsistencies
-overview: Resolve documentation inconsistencies between v0.2.0 release plan and foundational docs by updating determinism doctrine, sources.md scope, observation_architecture provenance chain, and consolidating validation contract.
-todos:
-  - id: fix-determinism
-    content: Remove LLM prohibition from determinism.md checklist and forbidden patterns
-    status: completed
-  - id: scope-sources
-    content: Remove upload_queue, storage_usage, timeout handling from sources.md
-    status: completed
-  - id: update-provenance
-    content: Update observation_architecture.md provenance chain to include InterpretationRun
-    status: completed
-  - id: add-validation
-    content: Add consolidated ingestion validation contract section to sources.md
-    status: completed
-# Documentation Consistency Fixes
-Align foundational docs with the streamlined v0.2.0 "Minimal Ingestion + Correction Loop" scope.
-## 1. Fix Determinism Doctrine Contradictions
-**File:** [`docs/architecture/determinism.md`](docs/architecture/determinism.md)
-**Changes:**
-- Remove "FORBIDDEN (in MVP)" from Section 2.6 (LLM Outputs) — replace with guidance that AI interpretation is allowed but bounded
-- Update "Code Review Checklist" (Section 8) — remove "No LLM extraction in MVP (rule-based only)"
-- Update "Forbidden Patterns" in Agent Instructions — remove "LLM-based extraction (MVP)"
-- Add forward reference to Section 1.2-1.3 (the corrected determinism table and auditability section)
-The existing table at lines 46-59 is correct; the issue is stale text in later sections.
-## 2. Scope sources.md to v0.2.0 Minimal
-**File:** [`docs/subsystems/sources.md`](docs/subsystems/sources.md)
-**Changes:**
-- Remove Section 7 (Upload Queue) entirely — add note that async retry is deferred to v0.3.0
-- Simplify Section 6 (Quota Enforcement) — replace with "simple hard-coded limit" per v0.2.0 scope
-- Remove `storage_usage` table schema (Section 6.3) — note deferred to v0.3.0
-- Remove Section 3.4 (Timeout Handling) — note deferred to v0.3.0
-- Update `interpretations` schema (Section 3.1) — remove `timeout_at`, `heartbeat_at` columns
-**Add "Deferred Features" section** listing what moves to v0.3.0:
-- Upload queue + retry worker
-- storage_usage table
-- Timeout/heartbeat handling
-- Strict quota enforcement
-## 3. Update Observation Architecture Provenance
-**File:** [`docs/subsystems/observation_architecture.md`](docs/subsystems/observation_architecture.md)
-**Changes:**
-- Update Section 1.1 model to show:
-  ```
-  Source → InterpretationRun (with config) → Observation → EntitySnapshot
-  ```
-- Update mermaid diagram to include InterpretationRun node
-- Update Section 4.1 Provenance Chain to explicitly include interpretation_run
-- Add reference to `sources.md` for interpretation config requirements
-## 4. Add Ingestion Validation Contract Section
-**File:** [`docs/subsystems/sources.md`](docs/subsystems/sources.md) (new Section 10)
-**Add consolidated validation contract:**
-- All AI-produced records MUST pass schema validation before observations are written
-- Failure paths: reject with error code (not quarantine)
-- Schema registry is single source of truth
-- Unknown fields route to `raw_fragments` (not silently dropped)
-- Provenance mandatory: `source_id` and `interpretation_run` enforced via FK + NOT NULL
-This consolidates scattered validation requirements into one authoritative section.
-## Files Changed
-| File | Changes |
-|------|---------|
-| `docs/architecture/determinism.md` | Remove LLM prohibition from checklist/forbidden patterns |
-| `docs/subsystems/sources.md` | Remove deferred features, add validation contract |
-| `docs/subsystems/observation_architecture.md` | Update provenance chain to include InterpretationRun |

package/docs/developer/getting_started.md

@@ -1,100 +0,0 @@
-# Developer Getting Started Guide
-
-_(Local-only setup)_
-
-## Scope
-
-This guide covers local development setup for Neotoma using SQLite + local filesystem only.
-
-## Prerequisites
-
-- Node.js `v18.x` or `v20.x`
-- npm `v9+`
-- Git (for contributors)
-
-## Install
-
-### Option A: npm package
-
-```bash
-npm install -g neotoma
-neotoma init
-neotoma api start --env dev
-neotoma mcp config
-```
-
-### Option B: repository clone
-
-```bash
-git clone https://github.com/markmhendrickson/neotoma.git
-cd neotoma
-npm install
-npm run type-check
-```
-
-## Local storage model
-
-Neotoma now runs in local-only mode:
-
-- SQLite database under `./data` by default
-- Local raw file storage under `./data/sources`
-- Optional logs directory under `./data/logs` (includes `events.log` for event-sourcing)
-
-No remote backend configuration is required.
-
-## Environment setup
-
-Create a `.env` only if you want overrides. Defaults work without one.
-
-```bash
-# Optional local path overrides
-# NEOTOMA_DATA_DIR=./data
-# NEOTOMA_RAW_STORAGE_DIR=./data/sources
-# NEOTOMA_EVENT_LOG_PATH=./data/logs/events.log
-# NEOTOMA_LOGS_DIR=./data/logs
-
-# Optional event mirroring
-NEOTOMA_EVENT_LOG_MIRROR=false
-
-# Optional server ports
-PORT=3000
-HTTP_PORT=8080
-WS_PORT=8280
-
-# API auth token used by local HTTP actions
-ACTIONS_BEARER_TOKEN=dev-token-or-random-string
-
-# Optional AI features
-OPENAI_API_KEY=sk-your-api-key-here
-```
-
-## Run development servers
-
-```bash
-npm run dev
-npm run dev:server
-npm run dev:ui
-npm run dev:full
-```
-
-## Run tests
-
-```bash
-npm test
-npm run test:integration
-npm run test:e2e
-npm run type-check
-npm run lint
-```
-
-## First contribution checklist
-
-- Run `npm run type-check`
-- Run `npm run lint`
-- Run affected tests
-- Verify no local-only behavior regressed
-
-## Notes
-
-- Remote backend setup has been removed from active docs and runtime.
-- If remote support is needed in the future, restore from git history.

package/docs/developer/import_interpretation_debug.md

@@ -1,69 +0,0 @@
-# Import and Interpretation Debug Guide
-
-## Scope
-
-This document helps agents and developers debug Neotoma file import, AI interpretation, and entity/snapshot behavior. It summarizes common root causes and fixes.
-
-## 1. Empty contact (or other entity) snapshot
-
-**Symptom:** Observation has `fields: {}` or very few fields; entity snapshot is empty even though the source document has clear data.
-
-**Root cause:** The LLM returns field names that do not match the schema. Validation only accepts exact schema keys; unknown keys are routed to `raw_fragments`. Example: JSON with `fullName`, `firstName`, `lastName` produces no schema match if the contact schema expects `name`, `email`, `phone`, etc.
-
-**Fix (implemented):** The LLM prompt in `src/services/llm_extraction.ts` now includes exact contact schema field names and mapping hints (e.g. fullName/firstName+lastName → name, url → website, homeLocation → address). Re-import or re-interpret the source after updating the prompt.
-
-**Debug checklist:**
-- Inspect `raw_fragments` for the source: unknown but extracted fields appear there.
-- Compare `raw_fragments.fragment_key` values to the entity schema in `src/services/schema_definitions.ts` (e.g. `contact`).
-- Ensure the prompt lists the exact schema field names for that entity type.
-
-## 2. PDF (or other file) first run: 0 entities; retry: 1+ entities
-
-**Symptom:** First interpretation run creates 0 observations/entities; re-interpreting the same source later creates observations.
-
-**Root cause:** AI interpretation is not replay-deterministic. The same source can yield different LLM outputs across runs (e.g. empty vs. successful extraction). See `docs/architecture/determinism.md` (Section 1.2–1.4).
-
-**Fix:** Re-run interpretation for the same source (e.g. via MCP `reinterpret` or store with same file). No code change required; behavior is documented.
-
-**Debug checklist:**
-- Check `interpretations` for the source: multiple runs with different `observations_created` are expected.
-- If the first run failed due to a backend error (e.g. missing column), fix the schema/migrations and retry.
-
-## 3. Invoice (or other) raw_fragments contain wrong/hallucinated data
-
-**Symptom:** Snapshot or raw_fragments show vendor names, amounts, or line items that do not appear in the source document (e.g. template-like or invented values).
-
-**Root cause:** The LLM sometimes filled fields with assumed or template values instead of document-only content.
-
-**Fix (implemented):** The LLM prompt now states: "Extract ONLY information that appears explicitly in the document. Do not invent, assume, or use template/example values." Invoice items are described as "Line items only if listed in the document (do not invent items)." Re-interpret the source after the prompt update to get document-accurate extraction.
-
-**Debug checklist:**
-- Open the source file and confirm whether each extracted value (vendor_name, customer_name, amount_due, items) appears in the text.
-- If not, treat as hallucination; tighten prompt or re-interpret after prompt changes.
-
-## 4. Backend interpretation errors (e.g. missing columns)
-
-**Symptom:** Errors such as `table interpretations has no column named user_id` or `created_at`.
-
-**Root cause:** Database schema out of sync with code (e.g. migrations not applied).
-
-**Fix:** Run migrations and ensure the `interpretations` table has all required columns. See `migrations/` and `docs/private/migration/migrations_lifecycle.md`.
-
-## 5. Related docs and MCP tools
-
-- **Determinism and retries:** `docs/architecture/determinism.md` (AI interpretation, idempotence, retry behavior).
-- **Ingestion pipeline:** `docs/subsystems/ingestion/ingestion.md`.
-- **MCP:** `store_unstructured` (file_path, interpret=true), `reinterpret`, `retrieve_entity_snapshot`, `list_observations`.
-
-## Agent Instructions
-
-### When to load
-
-- Debugging empty snapshots after import.
-- Debugging first-run vs retry variance for interpretations.
-- Investigating mismatches between source documents and extracted/raw_fragment data.
-
-### Constraints
-
-- Do not treat LLM interpretation as deterministic; document retry as expected when needed.
-- Verify alleged hallucinations against the actual source content before changing code.

package/docs/developer/launchd_dev_servers.md

@@ -1,51 +0,0 @@
-# Run Neotoma dev servers at login (macOS)
-
-Use a LaunchAgent so the Neotoma dev API (and optional tunnel) starts when you log in and restarts after reboot. You can then run `neotoma` or `neotoma dev` anytime without starting servers manually.
-
-## One-time setup
-
-From the Neotoma repo root:
-
-```bash
-npm run setup:launchd-dev
-```
-
-This will:
-
-1. Install `~/Library/LaunchAgents/com.neotoma.dev-servers.plist` with your repo path.
-2. Create `data/logs` if needed (logs go to `data/logs/launchd-dev-servers.log`).
-3. Load the agent so dev servers start immediately.
-
-After reboot, the agent runs again automatically (RunAtLoad + KeepAlive).
-
-## What runs
-
-The agent runs `npm run dev:api` (tunnel + API on port 8080). It sources `.env` from the repo root if present, so `NEOTOMA_*` and tunnel vars are applied.
-
-## Commands
-
-| Action        | Command |
-|---------------|--------|
-| Load (start)  | `launchctl load ~/Library/LaunchAgents/com.neotoma.dev-servers.plist` |
-| Unload (stop) | `launchctl unload ~/Library/LaunchAgents/com.neotoma.dev-servers.plist` |
-| Status        | `launchctl list \| grep neotoma` |
-| Logs          | `tail -f data/logs/launchd-dev-servers.log` |
-
-## Disable
-
-To stop the dev servers from starting at login:
-
-```bash
-launchctl unload ~/Library/LaunchAgents/com.neotoma.dev-servers.plist
-```
-
-To remove the agent entirely, unload as above and delete the plist:
-
-```bash
-rm ~/Library/LaunchAgents/com.neotoma.dev-servers.plist
-```
-
-## Scope
-
-- **macOS only.** LaunchAgents are a macOS feature. On Linux, use a systemd user service or similar.
-- **Dev environment only.** This runs the dev API (port 8080). For production-like always-on, you would use a separate plist or process manager.

package/docs/developer/launchd_watch_build.md

@@ -1,37 +0,0 @@
-# Run tsc --watch at login (macOS)
-
-Use a LaunchAgent so `tsc --watch` runs when you log in and after reboot. That keeps `dist/` in sync with source changes, so the global `neotoma` CLI (from `npm link`) always runs the latest build without starting servers or a manual watch process.
-
-## One-time setup
-
-From the Neotoma repo root:
-
-```bash
-npm run setup:launchd-watch-build
-```
-
-This installs `~/Library/LaunchAgents/com.neotoma.watch-build.plist`, loads it so the watcher starts immediately, and creates `data/logs` for output. After reboot, the agent runs again automatically.
-
-## What runs
-
-At startup the agent runs `npm run build:server` once (full TypeScript compile plus PDF worker copy), then runs `npm run watch:build` (i.e. `tsc --watch`) so `dist/` stays in sync with source. It does not start the API or tunnel. If the watch process exits (e.g. after a fatal error), the script restarts it after a short delay so the watcher is always running.
-
-## Commands
-
-| Action        | Command |
-|---------------|--------|
-| Load (start)  | `launchctl load ~/Library/LaunchAgents/com.neotoma.watch-build.plist` |
-| Unload (stop) | `launchctl unload ~/Library/LaunchAgents/com.neotoma.watch-build.plist` |
-| Status        | `launchctl list \| grep neotoma` |
-| Logs          | `tail -f data/logs/launchd-watch-build.log` |
-
-## Disable
-
-```bash
-launchctl unload ~/Library/LaunchAgents/com.neotoma.watch-build.plist
-rm ~/Library/LaunchAgents/com.neotoma.watch-build.plist
-```
-
-## Scope
-
-macOS only. The plist runs the script at `scripts/run_watch_build_launchd.sh`, which runs `npm run build:server` once then `npm run watch:build` in the repo.