ndomo 0.1.0

package/docs/http-server.md

@@ -0,0 +1,244 @@
+# HTTP Server (Phase 1)
+
+## Overview
+
+The optional **ndomo HTTP server** exposes the plugin's SQLite state (plans, tasks, sessions) as a read-only REST API and bridges the OpenCode SDK event stream as Server-Sent Events. Built on [Elysia](https://elysiajs.com/) with `@opencode-ai/sdk` for upstream connectivity.
+
+**Phase 1 scope:** read-only REST endpoints + live SSE event relay. No HTTP writes to the DB, no WebSocket, no JWT. Phase 2 will introduce peer-spawning actions.
+
+**Feature flag:** `NDOMO_HTTP_ENABLED=false` by default. The server does not bind a port unless explicitly enabled. CLI `--force` flag can override.
+
+**Why it exists:** lets external clients (custom dashboards, scripts, browsers) observe ndomo's multi-agent activity without running inside OpenCode. Decouples consumer clients from OpenCode's session lifecycle.
+
+## Quickstart
+
+```bash
+# 1. Configure (only OPENCODE_SERVER_PASSWORD is mandatory when auth enabled)
+export NDOMO_HTTP_ENABLED=true
+export NDOMO_HTTP_PORT=4097
+export OPENCODE_SERVER_PASSWORD='pick-a-strong-passphrase'
+
+# 2. Start the server from your project root (where .ndomo/state.db lives)
+bun run src/cli/serve.ts
+
+# 3. Liveness probe (no auth)
+curl -fsS localhost:4097/health
+
+# 4. Authenticated read
+curl -fsS -u "user:$OPENCODE_SERVER_PASSWORD" localhost:4097/api/plans
+
+# 5. Live SSE stream (Ctrl-C to disconnect)
+curl -N -u "user:$OPENCODE_SERVER_PASSWORD" localhost:4097/api/events
+```
+
+## Configuration
+
+All settings have sensible defaults; only `OPENCODE_SERVER_PASSWORD` is required when auth is enabled.
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `NDOMO_HTTP_ENABLED` | `false` | Master feature flag. Server binds port only when `true`. |
+| `NDOMO_HTTP_PORT` | `4097` | TCP port. Avoids OpenCode default `4096`. |
+| `NDOMO_HTTP_CORS_ORIGINS` | `*` | Comma-separated allowlist. `*` permits all origins (no credentials). |
+| `NDOMO_HTTP_AUTH_REQUIRED` | `true` | HTTP Basic auth gate. Set `false` for local dev. |
+| `OPENCODE_SERVER_PASSWORD` | (unset) | The HTTP Basic password. Server returns `503 auth_not_configured` if required + unset. |
+| `OPENCODE_SERVER_URL` | `http://localhost:4096` | Upstream OpenCode server for SDK event relay. |
+
+See [`.env.example`](.env.example) for full annotations.
+
+## CLI usage
+
+```
+bun run src/cli/serve.ts [options]
+```
+
+Or via the unified CLI:
+
+```
+bun run src/cli/index.ts serve [options]
+```
+
+| Flag | Default | Effect |
+|---|---|---|
+| `--port <n>` | config (4097) | Override port (1-65535). |
+| `--no-auth` | auth required | Disable HTTP Basic auth check (still loads `HttpConfig`). |
+| `--cors <origins>` | config (`*`) | Comma-separated CORS origins, e.g. `https://app.example.com,https://admin.example.com`. |
+| `--force` | off | Start even when `NDOMO_HTTP_ENABLED` is not `true`. |
+| `--help`, `-h` | — | Print help and exit. |
+
+**Examples:**
+
+```bash
+# Default config (auth enabled, CORS *)
+bun run src/cli/serve.ts
+
+# Local dev with auth off
+bun run src/cli/serve.ts --no-auth --port 4098
+
+# Production: explicit CORS allowlist
+bun run src/cli/serve.ts --cors "https://app.example.com,https://admin.example.com"
+
+# Bypass feature flag (for ad-hoc runs)
+bun run src/cli/serve.ts --force --port 4099
+```
+
+**Graceful shutdown:** `SIGINT` and `SIGTERM` close the listener and DB cleanly. Exit code `0` on clean shutdown, `1` on startup failure.
+
+## API reference
+
+All `/api/*` endpoints require HTTP Basic auth (unless `--no-auth`). `/health` is always public.
+
+| Method | Path | Auth | Query params | Response |
+|---|---|---|---|---|
+| `GET` | `/health` | no | — | `{ status, version, uptime, timestamp, dbHealthy }` |
+| `GET` | `/api/plans` | yes | `status`, `sessionId`, `limit` (1-500) | `Plan[]` |
+| `GET` | `/api/plans/search` | yes | `q` (required), `limit` (1-100) | `Plan[]` (FTS5) |
+| `GET` | `/api/plans/:id` | yes | — | `Plan` or `404` |
+| `GET` | `/api/tasks` | yes | `planId` (**required**), `status` | `Task[]` (422 if `planId` missing) |
+| `GET` | `/api/tasks/search` | yes | `q` (required), `limit` (1-100) | `Task[]` (FTS5) |
+| `GET` | `/api/tasks/:id` | yes | — | `Task` or `404` |
+| `GET` | `/api/sessions` | yes | `planId`, `limit` (1-100) | `Session[]` |
+| `GET` | `/api/sessions/active` | yes | — | `Session[]` (`endedAt === null`) |
+| `GET` | `/api/sessions/:id` | yes | — | `Session` or `404` |
+| `GET` | `/api/events` | yes | `types` (csv filter) | `text/event-stream` (SSE) |
+
+### Health response shape
+
+```json
+{
+  "status": "ok",
+  "version": "0.1.0",
+  "uptime": 12345,
+  "timestamp": 1735689600000,
+  "dbHealthy": true
+}
+```
+
+`status` is `"ok"` when the DB responds to `SELECT 1`, otherwise `"degraded"`.
+
+### SSE response
+
+`GET /api/events` returns `Content-Type: text/event-stream` with:
+
+- A `hello` event on connect.
+- Forwarded SDK events as `event: <type>` + `data: <json>` lines (default: all types).
+- Optional filter: `?types=session.idle,session.error` (comma-separated type allowlist).
+- A `: keepalive` comment every **30 seconds** to keep proxies from closing idle connections.
+- The stream closes cleanly on client disconnect (abort signal) or SDK error.
+
+If the SDK client is unreachable, the endpoint returns `503 sdk_unavailable` (no stream).
+
+**Browser example:**
+
+```js
+const es = new EventSource("/api/events", { withCredentials: true });
+// NOTE: EventSource cannot set Authorization. Use a short-lived token via query string (Phase 3).
+es.addEventListener("session.idle", (e) => console.log("session idle:", e.data));
+es.addEventListener("error", (e) => console.error("SSE error:", e));
+```
+
+For auth in the browser, Phase 3 will introduce short-lived SSE tokens via query string. Today, use HTTP Basic + a reverse proxy that injects `Authorization`, or call from server-side scripts only.
+
+## Security notes
+
+**HTTP Basic is plaintext over the wire.** Always run behind TLS in production (reverse proxy with nginx/Caddy, or `--force` over a VPN/localhost). HTTP Basic sends `base64(user:password)` — not encrypted, only obfuscated.
+
+**CORS:**
+- `NDOMO_HTTP_CORS_ORIGINS=*` permits any origin to call `/api/*` but **does not** send `Access-Control-Allow-Credentials`. Browser credentialed requests (cookies, `withCredentials`) will be rejected.
+- For a real frontend, set explicit origins: `NDOMO_HTTP_CORS_ORIGINS=https://app.example.com`. Credentials are then allowed.
+
+**Security headers** applied to every response (from `SECURITY_HEADERS` in `src/config/schema.ts`):
+
+| Header | Value |
+|---|---|
+| `X-Content-Type-Options` | `nosniff` |
+| `X-Frame-Options` | `DENY` |
+| `X-XSS-Protection` | `1; mode=block` |
+| `Referrer-Policy` | `strict-origin-when-cross-origin` |
+| `Content-Security-Policy` | `default-src 'none'; frame-ancestors 'none'` |
+| `Permissions-Policy` | `interest-cohort=()` |
+| `X-Powered-By` | `ndomo` |
+| `Strict-Transport-Security` | `max-age=31536000; includeSubDomains` (when `NODE_ENV=production`) |
+
+**Localhost-only recommendation:** the server has no rate limiting and no per-user audit trail. For multi-tenant exposure, put it behind a reverse proxy that enforces auth, rate limits, and request logging.
+
+**Password strength:** `OPENCODE_SERVER_PASSWORD` is the only gate. Use a passphrase ≥ 24 chars, or wire in a secret manager. Rotate via env reload + process restart.
+
+**503 when password missing:** if `auth.required=true` and `OPENCODE_SERVER_PASSWORD` is unset, `/api/*` returns `503 auth_not_configured` with `WWW-Authenticate: Basic realm="ndomo"`. The `/health` endpoint stays public.
+
+**No CSRF:** HTTP Basic is CSRF-immune (browser auto-supplies credentials only for same-origin requests, and cross-origin requests need explicit `withCredentials: true` + matching `Allow-Credentials`). For a frontend served from a different origin, set explicit CORS origins (not `*`).
+
+## Troubleshooting
+
+**Port already in use (`EADDRINUSE`).**
+Another process bound the port. Check with `lsof -i :4097` or `ss -lntp | grep 4097`. Either kill the conflicting process or use `--port <free>`.
+
+**`error: HTTP server is disabled (NDOMO_HTTP_ENABLED is not 'true').`**
+Feature flag off. Either set `NDOMO_HTTP_ENABLED=true` or pass `--force` to the CLI.
+
+**`503 auth_not_configured` on every request.**
+`auth.required=true` but `OPENCODE_SERVER_PASSWORD` is empty. Export the env var and restart.
+
+**CORS error in browser console: "No 'Access-Control-Allow-Origin' header".**
+The request's `Origin` is not in `NDOMO_HTTP_CORS_ORIGINS` and `*` is not set. Either add the origin to the allowlist or set `*` for development (no credentials).
+
+**SSE appears to hang / no events arrive.**
+Two common causes:
+1. **nginx buffering.** SSE responses need `X-Accel-Buffering: no` (the server sets this header, but a proxy might strip it). Configure your proxy: `proxy_buffering off;` (nginx) or `flush_interval -1` (HAProxy).
+2. **OpenCode server unreachable.** The `/api/events` endpoint depends on `OPENCODE_SERVER_URL` (default `http://localhost:4096`). Verify with `curl -fsS localhost:4096/config`. If the OpenCode server is down, the endpoint returns `503 sdk_unavailable`.
+
+**Connection drops after ~60s behind a load balancer.**
+The server sends `: keepalive` every 30s. If you still see drops, the proxy is closing idle TCP connections faster than 30s. Either lower the keepalive in your proxy or configure TCP keepalive at the OS level.
+
+**`422 validation_error: planId is required` from `/api/tasks`.**
+`planId` is required (unlike `/api/sessions` which makes it optional). Pass `?planId=<uuid>`.
+
+## Architecture
+
+```
+┌──────────┐        ┌──────────────────────────┐        ┌─────────────────────┐
+│ Browser  │ HTTP+SSE│   ndomo Elysia server    │  SDK   │  OpenCode server    │
+│ / curl   │────────▶│  :4097 (Phase 1)         │───────▶│  :4096              │
+│ / script │  basic  │  ┌────────────────────┐  │  HTTP  │  ┌───────────────┐  │
+│          │◀────────│  │ securityHeaders    │  │◀───────│  │ event.subscribe│  │
+│          │         │  │ corsMiddleware     │  │  SSE   │  │ session.*     │  │
+│          │         │  │ httpBasicAuth      │  │        │  │ ...           │  │
+│          │         │  │ /health (public)   │  │        │  └───────────────┘  │
+│          │         │  │ /api/plans (auth)  │  │        └─────────────────────┘
+│          │         │  │ /api/tasks (auth)  │  │
+│          │         │  │ /api/sessions      │  │        ┌─────────────────────┐
+│          │         │  │ /api/events (SSE)  │──────────│ .ndomo/state.db     │
+│          │         │  └────────────────────┘  │  SQL   │ (plans, tasks, ... )│
+│          │         └──────────────────────────┘        └─────────────────────┘
+```
+
+- **Inbound:** `Elysia` handles auth (Basic), CORS, security headers, then dispatches to REST handlers or SSE stream.
+- **REST handlers** are thin adapters — they delegate to `src/db/*.ts` (SQLite) and return JSON. No business logic in routes.
+- **SSE** opens an async iterator on `sdkClient.event.subscribe()`, writes events through `SseWriter`, and cleans up on abort.
+- **Outbound to OpenCode:** `getSdkClient()` creates a singleton `createOpencodeClient` configured with `baseUrl: OPENCODE_SERVER_URL` and `directory: process.cwd()` (project scoping via `x-opencode-directory` header).
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `src/http/server.ts` | Elysia app builder + listen wrapper |
+| `src/http/auth.ts` | HTTP Basic auth middleware (timing-safe compare, 503 on missing password) |
+| `src/http/middleware/security-headers.ts` | OWASP baseline headers |
+| `src/http/middleware/cors.ts` | CORS preflight + `Allow-Origin` logic |
+| `src/http/routes/health.ts` | `GET /health` |
+| `src/http/routes/plans.ts` | `/api/plans/*` |
+| `src/http/routes/tasks.ts` | `/api/tasks/*` |
+| `src/http/routes/sessions.ts` | `/api/sessions/*` |
+| `src/http/routes/events.ts` | `/api/events` SSE relay |
+| `src/http/sse.ts` | SSE format + writer + keepalive |
+| `src/sdk/client.ts` | OpenCode SDK singleton (with health check) |
+| `src/cli/serve.ts` | CLI entry point with flags |
+| `src/config/schema.ts` | `loadHttpConfig()` + `SECURITY_HEADERS` |
+| `src/http/__tests__/` | Unit + integration tests (528 tests total in repo) |
+| `scripts/smoke-http.sh` | End-to-end smoke (5 curl assertions + headers) |
+
+## See also
+
+- [`.env.example`](.env.example) — annotated env reference
+- [`docs/database.md`](database.md) — schema for `Plan`, `Task`, `Session`
+- [`README.md`](../README.md) — quickstart + features

package/docs/installation.md

@@ -0,0 +1,259 @@
+# Installation Guide
+
+## Prerequisites
+
+- **bun** >= 1.1.0 — [install bun](https://bun.sh)
+- **OpenCode** installed and configured
+- At least one **provider authenticated** in OpenCode (the agents will use provider models)
+
+Verify prerequisites:
+
+```bash
+bun --version  # >= 1.1.0
+opencode --version
+opencode config list providers  # should show at least one authenticated provider
+```
+
+## Install via curl/wget
+
+The install script supports being piped directly from a URL, useful for quick setups, CI/CD pipelines, and ephemeral environments. When piped, the script detects it is running from stdin, clones the repository to `/tmp`, and re-executes itself.
+
+```bash
+# Quick install (interactive, will prompt for provider)
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash
+
+# Non-interactive with provider preset
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s -- --provider=opencode --no-provider-prompt
+
+# With budget preset + DCP
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s -- --preset=budget --with-dcp
+
+# Install from a fork or dev branch
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s -- \
+  --repo=https://github.com/myorg/ndomo-fork \
+  --branch=dev \
+  --provider=opencode
+```
+
+The `--repo` and `--branch` flags are only relevant in piped mode; they are ignored when running from a local clone.
+
+## Install from Git Clone
+
+```bash
+# 1. Clone the repository
+git clone <repo-url> ndomo
+cd ndomo
+
+# 2. Install dependencies
+bun install
+
+# 3. Run the install script
+./scripts/install.sh
+```
+
+The install script:
+1. Copies the configuration to `~/.config/opencode/ndomo.json`
+2. Registers the plugin with OpenCode
+3. Verifies all agent definitions in `agents/` are valid
+4. Links the bundled skills (bash-scripting, caveman, grill-me, and 20+ others from `skills/`) to the OpenCode skills directory
+5. Applies the active preset (`presets[PRESET]` from `ndomo.config.json`) to every agent's `model:` and `temperature:` frontmatter.
+6. Registers `ndomo` as a local `file:` dependency in `~/.config/opencode/package.json` and installs it to `~/.config/opencode/node_modules/ndomo/` via `bun install`. This is what allows OpenCode to resolve the plugin from `plugin: ["ndomo", ...]` and register its tools. See [OpenCode plugin docs](https://opencode.ai/docs/es/plugins/) and [custom tools docs](https://opencode.ai/docs/es/custom-tools/).
+7. Symlinks the bundled custom tools (14 DB access tools: `plan_*`, `task_*`, `session_*`) from `tools/` to `~/.config/opencode/tools/`. See [OpenCode custom tools docs](https://opencode.ai/docs/es/custom-tools/).
+
+**Note:** The `reasoning_effort` field (optional, `low`|`medium`|`high`|`xhigh`) is supported for reasoning-capable models (DeepSeek, MiMo, OpenAI). Omit it for non-reasoning models.
+
+## Development Workflow
+
+When developing ndomo (editing agents, skills, config, or source files), use these commands to apply changes:
+
+| Command | When to use | What it does |
+|---|---|---|
+| `./scripts/install.sh` | First install, after cloning, or after changing agents/skills/config | Copies agents, skills, and config to `~/.config/opencode/`. Installs ndomo package. Always preferred for structural changes. |
+| `bun run dev:bust` | After editing only `src/*.ts` source files (no agent/skill/config changes) | Quick cache bust: removes stale Bun transpiler cache entries referencing ndomo, bumps mtime on all `src/*.ts` files. Does not kill opencode. |
+| `bun run dev:reset` | Same as `dev:bust` but when opencode is running and you need a clean restart | `dev:bust` + kills running opencode processes. Run this after editing source to ensure the next `opencode` picks up fresh code. |
+
+### Daily dev loop
+
+1. Edit source files in `src/`.
+2. Run `bun run dev:reset` to kill opencode + bust Bun cache + bump mtimes.
+3. Start opencode: `opencode`.
+4. Repeat.
+
+### Why symlinks cause stale cache
+
+Bun caches transpiled TypeScript modules in `~/.bun/install/cache/` keyed by the **resolved path** of the module. When ndomo is installed via a symlink (e.g., `~/.config/opencode/node_modules/ndomo → /home/nico/ndomo`), the cache key uses the symlink path. Editing source files on the target filesystem does **not** change the symlink path, so Bun serves stale code from cache.
+
+The `file:` dep strategy in `install_ndomo_package()` avoids this by creating a real copy in `node_modules` (no symlink → no stale cache). If you ever end up with a symlink install (from an older `install.sh` version or a manual `ln -s`), re-run `./scripts/install.sh` — it detects the symlink, removes it, and reinstalls as a real copy (`scripts/install.sh` lines 247–254).
+
+### Manual cache busting (advanced)
+
+Run the cache bust script directly for more control:
+
+```bash
+# Dry-run — inspect what would be removed
+./scripts/dev-bust-cache.sh
+
+# Apply — remove stale cache entries + bump mtimes
+./scripts/dev-bust-cache.sh --apply
+
+# Kill opencode first, then bust cache
+./scripts/dev-bust-cache.sh --apply --kill
+```
+
+The script (`scripts/dev-bust-cache.sh`):
+1. Optionally kills running opencode processes (`--kill`)
+2. Removes Bun cache entries referencing "ndomo"
+3. Removes Bun cache entries referencing the ndomo source path (`$PROJECT_ROOT/src`)
+4. Touches all `src/*.ts` files to bump mtime (forces re-transpilation)
+
+It is **idempotent** — safe to run multiple times. No-op if the cache is already clean.
+
+## Install Flags
+
+| Flag | Description |
+|---|---|
+| `--provider=ID` | Override the provider prefix for all agents. The model ID is taken from the active preset; only the `provider/` segment of the `model:` field is swapped. Example: preset gives `opencode-go/minimax-m2.7`, `--provider=opencode` rewrites to `opencode/minimax-m2.7`. |
+| `--no-provider-prompt` | Skip the interactive provider prompt. The preset is still applied; no provider prefix override is performed. |
+| `--with-dcp` | Install and configure the DCP plugin (opencode-dynamic-context-pruning) as an optional peer dependency |
+| `--preset=NAME` | Select preset from `config/ndomo.config.json::presets[NAME]`. The preset is the source of truth for agent models at install time. (default: `default`, options: `default`, `budget`) |
+| `--repo=URL` | Override the repository URL (for piped installs from a fork or mirror). Ignored in local clones. |
+| `--branch=NAME` | Override the repository branch (for piped installs from `dev`/`feature/*` branches). Ignored in local clones. |
+
+**Environment variable:** `NDOMO_SKIP_PACKAGE_INSTALL=1` — skip the package installation step (`bun install` in `~/.config/opencode/`). Useful if you manage the OpenCode plugin directory manually or if the install step is causing conflicts.
+
+Example with all flags:
+
+```bash
+# Local clone with all flags
+./scripts/install.sh --with-dcp --preset=budget
+
+# Piped install with provider, fork, and custom branch
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s -- \
+  --repo=https://github.com/myorg/ndomo-fork \
+  --branch=dev \
+  --provider=opencode \
+  --no-provider-prompt
+```
+
+## Provider Override
+
+When `install.sh` runs without `--provider` and without `--no-provider-prompt`, it shows the active preset and asks for confirmation. The active preset is the single source of truth for agent models; `--provider=ID` only changes the provider prefix.
+
+TTY flow:
+
+1. The script prints a table of `(agent, preset model, current provider prefix)` derived from `config/ndomo.config.json`.
+2. It asks: `Apply preset '$PRESET' as configured? [Y/n/override]`
+3. `Y` (or Enter) applies the preset, no prefix override.
+4. `n` skips preset application (warn).
+5. `override` enters the interactive provider picker from models.dev and applies a prefix override to every agent's `model:` field. The model ID comes from the preset; only the `provider/` segment is swapped.
+
+To skip the prompt and apply the preset silently:
+
+```bash
+./scripts/install.sh --no-provider-prompt
+```
+
+To override the provider prefix non-interactively (e.g., use `opencode` instead of `opencode-go` for all agents):
+
+```bash
+./scripts/install.sh --provider=opencode
+```
+
+The provider override works in piped mode:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s -- --provider=opencode --no-provider-prompt
+```
+
+## Verify Installation
+
+1. Start OpenCode:
+
+```bash
+opencode
+```
+
+2. Inside the OpenCode session, test agent communication:
+
+```
+ping all agents
+```
+
+Expected output: each of the 22 agents responds with a status confirmation.
+
+3. Check that the Foreman is the primary agent:
+
+```
+/agent
+```
+
+Should show `foreman` as the active agent.
+
+4. Verify the ndomo DB was created:
+
+   ```bash
+   ls -la .ndomo/state.db
+   ```
+
+   The plugin creates this SQLite database automatically on first load. It
+   stores plans, tasks, and sessions. See [docs/database.md](docs/database.md)
+   for details.
+
+## Uninstall
+
+```bash
+./scripts/uninstall.sh
+```
+
+Removes:
+- The config file at `~/.config/opencode/ndomo.json`
+- Plugin registration from OpenCode
+- Skill symlinks
+
+**Flag:**
+
+| Flag | Description |
+|---|---|
+| `--keep-data` | Remove plugin config but preserve memory files in `~/.ndomo/mem/` |
+
+## Troubleshooting
+
+### bun not found
+
+```
+bun: command not found
+```
+
+Install bun: `curl -fsSL https://bun.sh/install | bash`. Restart your shell after installation.
+
+### Provider not authenticated
+
+```
+Error: No authenticated provider found
+```
+
+Configure a provider in OpenCode: `opencode config set provider <provider-name>` and follow the authentication flow. At least one provider must be authenticated before ndomo agents can make API calls.
+
+### Agent not responding
+
+If `ping all agents` shows no response from one or more agents:
+
+1. Verify the config file exists: `ls ~/.config/opencode/ndomo.json`
+2. Validate the config against the schema: `cat ~/.config/opencode/ndomo.json`
+3. Re-run the install script: `./scripts/install.sh`
+4. Check OpenCode logs for model routing errors — the agent's `model` field in the config must match a model available through your authenticated provider.
+
+### Permission denied on scripts
+
+```bash
+chmod +x scripts/install.sh scripts/uninstall.sh
+```
+
+### Plugin not loading
+
+If OpenCode doesn't detect ndomo as a plugin:
+
+1. Ensure `ndomo` is listed in `config/ndomo.config.json` under `plugins`
+2. Check that the package is installed: `ls ~/.config/opencode/node_modules/ndomo/` — if missing, re-run `./scripts/install.sh` or symlink manually: `ln -sfn $(pwd) ~/.config/opencode/node_modules/ndomo`
+3. Verify the plugin entry point (`src/index.ts`) compiles without errors: `bun run build`
+4. Check that the local node_modules were installed: `ls node_modules/ndomo` (or the symlink target)

package/docs/integrations.md

@@ -0,0 +1,129 @@
+# Integration Guide
+
+## opencode-mem (required)
+
+opencode-mem is a persistent memory system for OpenCode. It provides a local vector database (SQLite + USearch) with semantic search across sessions.
+
+**License:** MIT
+
+### What it is
+
+opencode-mem stores and retrieves developer knowledge across sessions. ndomo uses it as the primary persistence layer — every agent stores and searches memories before planning or executing tasks.
+
+### How ndomo uses it
+
+The foreman searches memory before every planning cycle:
+
+1. **Project search** — `memory({mode:"search", query, scope:"project"})` retrieves past decisions from the current project.
+2. **Cross-project search** — `memory({mode:"search", query, scope:"all-projects"})` retrieves knowledge from all projects.
+3. **Compressed storage** — before calling `memory({mode:"add"})`, ndomo compresses content using caveman regex patterns (0 LLM tokens).
+
+### Tool usage
+
+| Mode | Call | Purpose |
+|---|---|---|
+| search | `memory({mode:"search", query, scope:"project"})` | Search current project memories |
+| search | `memory({mode:"search", query, scope:"all-projects"})` | Search all project memories |
+| add | `memory({mode:"add", content, topic})` | Store a new memory entry |
+| add | `memory({mode:"add", content, topic, tags})` | Store with tags for filtering |
+
+### Web UI
+
+opencode-mem includes a web UI at `http://localhost:4747` for browsing and managing memory entries.
+
+### Config
+
+See [configuration.md](configuration.md#memory-config) for memory-specific settings (`storagePath`, `defaultScope`, `autoCaptureEnabled`, `cavemanCompress`).
+
+## DCP (optional)
+
+Dynamic Context Pruning (`@tarquinen/opencode-dcp`) is an optional plugin that compresses conversation context by removing low-value tool outputs while preserving critical information.
+
+**License:** AGPL-3.0
+
+### What it is
+
+DCP monitors context token usage and, on request or automatically, prunes low-value content from the conversation window. This extends session life in long-running tasks.
+
+### How to install
+
+```bash
+./scripts/install.sh --with-dcp
+```
+
+This installs `@tarquinen/opencode-dcp` as an optional peer dependency.
+
+### How ndomo uses it
+
+The foreman monitors context size:
+
+- **~50k tokens** (foreman `minContextLimit`) — suggests `/dcp-compress` to the user.
+- **~100k tokens** (foreman `maxContextLimit`) — invokes `compress` tool automatically at a natural pause point.
+- **If DCP not installed** — falls back to native OpenCode context compaction.
+
+### Context thresholds
+
+Per-agent thresholds in `dcp_overrides` (only when DCP installed):
+
+| Agent | minContextLimit | maxContextLimit |
+|---|---|---|
+| scout | 30,000 | 80,000 |
+| scribe | 30,000 | 80,000 |
+| foreman | 50,000 | 100,000 |
+| sage | 50,000 | 100,000 |
+| guild | 50,000 | 100,000 |
+| inspector | 40,000 | 90,000 |
+
+Agents without overrides use DCP defaults.
+
+### Protected tools
+
+The `compress` tool is listed in `protectedTools` — it cannot be pruned from context or disabled by subagents. This ensures DCP can always function when needed.
+
+## Caveman + Memory
+
+Memories are compressed before storage using regex-based caveman compression (`src/orchestrator/memory-hook.ts`).
+
+### Compression rules
+
+- **Protected:** Fenced code blocks (`` ``` ``), URLs (http, https, git, ssh).
+- **Removed:** Articles (a, an, the, el, la, los, las, un, una), filler words (just, really, basically, actually, simply, etc.), leading conjunctions (and, but, or, so, then, also), filler phrases ("in order to", "it is important to note that", etc.), excess whitespace.
+
+### Regex-only
+
+All compression is regex-based — zero LLM tokens consumed for compression. The `COMPRESSION_PATTERNS` array in `memory-hook.ts` defines all patterns, applied sequentially.
+
+### Limitations
+
+- **Non-English text:** Spanish articles (el, la, los, las, un, una, unos, unas) are included in the pattern set. Other languages are not explicitly handled — their articles and fillers may survive compression.
+- **Bilingual content:** Mixed-language content is compressed with English + Spanish rules only. Additional languages may require new patterns in `COMPRESSION_PATTERNS`.
+- **Preserved content:** Code blocks and URLs are always preserved verbatim, even if they contain patterns that would otherwise be stripped.
+
+## Troubleshooting
+
+### opencode-mem not found
+
+```
+Error: Cannot find module 'opencode-mem'
+```
+
+Ensure opencode-mem is installed. ndomo lists it as a dependency in `package.json` — `bun install` should install it automatically. If not: `bun add opencode-mem`.
+
+### Web UI not accessible
+
+```
+curl http://localhost:4747
+Connection refused
+```
+
+Verify opencode-mem is running. Start it manually: `npx opencode-mem serve`. Default port is 4747.
+
+### DCP commands not available
+
+If `/dcp-compress` doesn't work:
+
+1. Verify DCP is installed: check `~/.config/opencode/node_modules/@tarquinen/opencode-dcp` exists.
+2. Verify DCP is registered as an optional plugin in `config/ndomo.config.json`: `"optionalPlugins": ["@tarquinen/opencode-dcp"]`.
+3. Restart OpenCode after installing.
+
+DCP is optional — ndomo functions without it, but long sessions may exhaust context without pruning.

package/docs/operations/anti-pattern-sub-agent-verify-2026-06-21.md

@@ -0,0 +1,32 @@
+# Anti-pattern: Sub-agents marking plans done without DB verification
+
+**Date:** 2026-06-21  
+**Plan context:** a7e75f8b (foreman-verify-protocol-v1)  
+**Severity:** process — schema drift / audit gaps
+
+## Incidents
+
+### 1. ops-audit-v2
+A sub-agent closed the plan as `completed` after reporting audit findings, but never ran an objective verification pass against the DB state. The completion status became self-certified rather than evidence-based.
+
+- **Root cause:** no explicit verify step before `plan_update_status("completed")`.
+- **Impact:** plan marked done while DB consistency checks were unverified; audit trail gap.
+
+### 2. craftsman-db-optimize-v1
+Migration v12 was not auto-applied in the execution environment, yet the plan was marked `completed`. This is the second occurrence of a schema migration being skipped while the plan status advanced.
+
+- **Root cause:** craftsman trusted implementation-side success (tests green, code merged) without checking `PRAGMA user_version`.
+- **Impact:** schema drift between code expectations and runtime DB; runtime queries could hit missing views/indexes.
+
+## Pattern
+
+Both cases share the same failure mode: the executing sub-agent acted as both implementer and certifier. It assumed "I wrote it / tests passed" meant "system state matches intent," bypassing objective verification of the actual DB and runtime artifacts.
+
+This is a governance anti-pattern: the agent that performs the work cannot also be the sole authority that declares the work correct. Objective verification must come from an independent check of the produced state.
+
+## Mitigation
+
+- Enforce the **foreman verify protocol** (see `agents/foreman.md`): no plan moves to `completed` until verify checks are recorded.
+- Add a **gate agent** (inspector) as an independent post-plan verification step; see `verify-gate-architecture.md`.
+- Craftsman must not self-certify completion; gate verdict is binary and write-once.
+- For DB-touching plans, require `PRAGMA user_version` and a smoke query against the changed schema as gate checks.