codetrap 0.1.7 → 0.1.9

package/README.md

@@ -53,18 +53,45 @@ codetrap list
 codetrap show 1
 ```
 
+## 5-Minute Agent Setup
+
+For a first AI-agent user, the fastest path is CLI-first project guidance:
+
+```bash
+# npm/source installs require Bun because the package entrypoint uses /usr/bin/env bun
+bun --version  # If this fails, install Bun first or use the binary install in docs/installation.md
+npm install -g codetrap
+
+# Initialize pitfall memory in the target project
+cd /path/to/project
+codetrap setup codex
+codetrap doctor
+```
+
+`codetrap setup codex` installs the bundled Codex skills into `~/.codex/skills`, initializes `.codetrap/` when needed, and writes `AGENTS.md`. It does not configure MCP by default.
+
+To also configure Codex MCP, opt in explicitly:
+
+```bash
+codetrap setup codex --mcp
+```
+
+The packaged template is the source of truth for exact agent behavior. It tells agents to run CLI JSON checks before non-trivial edits, inspect only relevant action cards, keep post-flight lessons in the session candidate inbox, and require explicit human approval before accepting a candidate into `traps.db`.
+
+For a quick manual check, agents can run `codetrap search "<task keywords>" --mode hybrid --json` from the project cwd.
+
 ## Features
 
 - **Structured trap recording** — title, category, context, mistake, fix, severity, tags, lifecycle, evidence, before/after code
 - **Session mode capture** — record implementation notes, promote explicit structured trap notes into candidates, and save only user-accepted lessons
 - **Dual scope** — project-scoped (`.codetrap/traps.db`) and global (`~/.codetrap/traps.db`)
 - **CLI-first agent API** — `search/show/list/stats/doctor --json` and stdin query support for shell-friendly automation
-- **Three search modes** — FTS (SQLite FTS5), semantic (Jina embeddings), hybrid (RRF fusion)
+- **Three search modes** — FTS (SQLite FTS5), semantic (local Ollama or Jina embeddings), hybrid (RRF fusion)
 - **Chinese + mixed-language search** — CJK bigram tokenizer, synonym map for Chinese-English terms
 - **MCP server** — optional tools + resources for AI agent integration
-- **Embedding cache** with freshness tracking — embeddings are rebuildable, stale ones auto-invalidated
+- **Embedding cache** with multi-profile freshness tracking — Jina/Ollama vectors can coexist and stale ones auto-invalidate
 - **Doctor diagnostics** — scope, database, and embedding health in text or JSON
-- **Schema migrations** — in-code migration system from v0 through current v5
+- **Schema migrations** — in-code migration system from v0 through current v6
 - **Single-binary builds** — `bun build --compile` produces standalone binaries in `dist/`
 
 ## Directory Structure
@@ -74,7 +101,7 @@ codetrap/
 ├── src/
 │   ├── index.ts              CLI entry point
 │   ├── mcp-server.ts         MCP server entry point
-│   ├── commands/router.ts    Thin CLI adapter + renderer
+│   ├── commands/router.ts    Optional thin CLI adapter + renderer
 │   ├── commands/workflow.ts  CLI command behavior
 │   ├── commands/command-result.ts  CLI command results + rendering
 │   ├── mcp/
@@ -87,9 +114,12 @@ codetrap/
 │   │   ├── store.ts          Project/global scope orchestration
 │   │   ├── trap-operations.ts Shared CLI/MCP operation semantics
 │   │   ├── session-operations.ts Session command semantics + accept/reject flow
+│   │   ├── session-review.ts Shared session review payloads + CLI conflict presenter
 │   │   ├── session-store.ts  Session files, active state, index, recaps
 │   │   ├── session-codec.ts  Session JSON/Markdown/candidate file conversion
-│   │   ├── session-capture.ts Candidate trap extraction from explicit structured notes
+│   │   ├── session-capture.ts Candidate draft normalization, extraction, and merge policy
+│   │   ├── session-candidate-document.ts Candidate document transition rules
+│   │   ├── session-candidate-scope.ts Candidate accepted-scope fallback
 │   │   ├── session-conflicts.ts Candidate vs active-trap conflict checks
 │   │   ├── trap-quality.ts   Deterministic candidate quality scoring
 │   │   ├── command-requests.ts CLI/MCP request normalization helpers
@@ -97,7 +127,9 @@ codetrap/
 │   │   ├── scope-context.ts  cwd/project/global DB context + repo selection
 │   │   ├── scope-migration.ts Safe project trap scope repair/migration
 │   │   ├── doctor.ts         Scope and embedding health diagnostics
+│   │   ├── embedding-runtime.ts Embedding provider runtime/config/status
 │   │   ├── embedding-health.ts  Fresh/stale/missing embedding summaries
+│   │   ├── embedding-management.ts Embedding profile command output
 │   │   ├── search-service.ts FTS/semantic/hybrid candidate retrieval
 │   │   ├── search-policy.ts  Applicability filtering, rerank, fusion signals
 │   │   ├── search-result-card.ts Compact agent-facing result cards
@@ -107,10 +139,13 @@ codetrap/
 │   │   ├── trap-json-fields.ts Tags/path/evidence JSON array codec
 │   │   ├── trap-codec.ts     Storage/JSON/archive/import shape conversion
 │   │   ├── trap-mutation-result.ts Mutation result + scope fallback semantics
+│   │   ├── string-list.ts    Shared string list de-duping
+│   │   ├── text-lines.ts     Shared line trimming helpers
+│   │   ├── value-types.ts    Shared runtime value guards
 │   │   ├── trap-scope-match.ts Path/module/owner applicability matching
 │   │   ├── trap-archive.ts   Import/export compatibility
 │   │   ├── trap-transfer.ts  DB-to-DB transfer for scope migration
-│   │   ├── embedder.ts       Jina Embeddings adapter
+│   │   ├── embedder.ts       Ollama and Jina Embeddings adapters
 │   │   ├── embedding-job.ts  Batch embedding generation
 │   │   ├── format.ts         CLI output formatting
 │   │   ├── scope.ts          Project root detection
@@ -121,6 +156,13 @@ codetrap/
 │   │   ├── queries.ts        CRUD, search, stats, import/export
 │   │   ├── embedding-queries.ts  Embedding storage SQL
 │   │   └── repository.ts     Single-DB facade
+│   ├── web/
+│   │   ├── server.ts         Thin Web API adapter over shared operations
+│   │   ├── static.ts         HTML/CSS shell
+│   │   ├── client-shell.ts   Pane sizing/collapse behavior
+│   │   ├── client-review.ts  Review queue + candidate draft/request model
+│   │   ├── client-script.ts  DOM composition and event wiring
+│   │   └── client-text.ts    Localized UI strings
 │   └── tests/
 │       ├── search-*.test.ts
 │       ├── trap-*.test.ts
@@ -130,8 +172,7 @@ codetrap/
 │       ├── scope-migration-cli.test.ts
 │       ├── import-export-cli.test.ts
 │       └── fixtures/search-eval.json
-├── skills/                   Agent skill definitions
-├── plugins/codetrap-agent/   Sample Codex plugin bundle
+├── plugins/codetrap-agent/   Codex plugin bundle with skills, MCP config, hooks, and templates
 ├── scripts/                  Release asset and preflight scripts
 ├── docs/                     Architecture + reference docs
 ├── package.json
@@ -144,7 +185,7 @@ codetrap/
 | Command | Description |
 |---|---|
 | `init` | Initialize `.codetrap/` in current project |
-| `add` | Record a new trap (`--json` structured input; interactive mode is not implemented) |
+| `add` | Record a confirmed trap (`--json` structured input; interactive mode is not implemented) |
 | `search <query>` | Search traps (--mode fts\|semantic\|hybrid, --category, --scope, --status, --limit, --path, --module, --owner, --no-rerank, --ranking-signals, --json; query can come from stdin) |
 | `list` | List traps (--category, --scope, --status, --path, --module, --owner, --limit, --json) |
 | `show <id>` | Show full trap details (--json) |
@@ -157,11 +198,13 @@ codetrap/
 | `import` | Import traps from JSON (--json) |
 | `stats` | Show database statistics (--json includes embedding health) |
 | `doctor` | Diagnose cwd, scope, database paths, trap counts, and embedding health (--json) |
+| `setup codex` | Install Codex skills and project guidance; MCP is opt-in with `--mcp` |
 | `repair-scope` | Move legacy mis-scoped project traps into the current project (dry-run by default, `--apply` to mutate, `--json`) |
 | `migrate-project` | Move project traps between initialized projects (`--from-project-path`, `--to-project-path`, dry-run by default, `--apply`, `--json`) |
-| `embed` | Generate embeddings (requires JINA_API_KEY) |
-| `session` | Start a development session, append notes, promote explicit structured trap notes into candidates, accept/reject candidates, and clean up session files |
-| `web` | Start the local review and trap library console |
+| `embed` | Generate embeddings (requires configured Ollama or Jina provider) |
+| `embeddings` | Manage embedding profiles (`status`, `list`, `use ollama|jina`, `reindex`) |
+| `session` | Start a development session, append notes, capture post-flight candidates, promote explicit structured trap notes into candidates, accept/reject candidates, and clean up session files |
+| `web` | Start the local review, trap library, insights, and Embeddings console |
 | `serve` | Start MCP server |
 
 ### Session Mode
@@ -171,13 +214,26 @@ Session mode stores temporary working memory in `.codetrap/sessions/`. It does n
 ```bash
 codetrap session start "implement agent harness" --spec docs/agent-harness-spec.md --module agent-runtime
 codetrap session note --kind decision --text "Defaulted tool calls to 30s because the spec does not define timeout behavior."
-codetrap session note --kind review --text $'Title: Do not parse nested tool calls with regex\nContext: When implementing parser logic for nested tool-call arguments.\nMistake: Using regex to split nested calls corrupts arguments.\nFix: Use a tokenizer/parser and add regression tests for nested calls.'
+cat <<'EOF' | codetrap session capture --trap-markdown - --kind review --json
+Title: Do not parse nested tool calls with regex
+Context: When implementing parser logic for nested tool-call arguments.
+Mistake: Using regex to split nested calls corrupts arguments.
+Fix: Use a tokenizer/parser and add regression tests for nested calls.
+Tags: parser, tool-calls
+Severity: error
+EOF
 codetrap session close --propose-traps
 codetrap session candidates
 codetrap session candidate cand-001
+
+# Only after explicit human approval:
 codetrap session accept cand-001
 ```
 
+`session capture` is the low-friction post-flight path: an agent drafts a structured Markdown or JSON candidate, codetrap scores it and puts it in the session inbox, and nothing is written to `traps.db` until the candidate is accepted. If no session is active, capture creates a post-flight session, writes the candidate and recap, then closes it.
+
+Pending candidates are surfaced through `codetrap session status`, `codetrap session list`, `codetrap doctor`, and the local `codetrap web` review console so candidate lessons do not disappear into session files.
+
 `session accept` writes the confirmed lesson through `TrapOperations`, attaches session evidence, and checks similar active traps before saving. `--edit-json` is applied before the conflict check, so edits to scope/module/title/tags/path globs affect both the saved trap and conflict detection. If a possible conflict is found, the candidate keeps its edited trap shape and conflict diagnostics; use `--accept-anyway` to keep both traps or `--supersedes <trap-id>` to preserve lifecycle history.
 
 Session maintenance commands keep temporary files from becoming stale context:
@@ -198,14 +254,28 @@ For AI coding agents, use the CLI as the default integration path:
 
 CLI and project guidance are the main path. MCP should stay thin and share the same store/search behavior.
 
-### MCP Setup
+### Codex Setup
+
+Default setup installs skills and project guidance without MCP:
+
+```bash
+codetrap setup codex
+```
 
-Codex:
+MCP is optional. To configure it too, opt in explicitly:
+
+```bash
+codetrap setup codex --mcp
+```
+
+You can also add MCP manually:
 
 ```bash
 codex mcp add codetrap -- codetrap serve
 ```
 
+### MCP Setup
+
 Generic MCP client config:
 
 ```json
@@ -221,76 +291,31 @@ Generic MCP client config:
 
 ### Project Guidance
 
-Add this to `AGENTS.md` for Codex, or to `CLAUDE.md` for Claude Code:
-
-````md
-## Codetrap
-
-Before non-trivial code edits, check codetrap for relevant pitfalls.
-
-Default to CLI JSON from the current project cwd:
-
-```bash
-codetrap search "<keywords>" --mode hybrid --json
-```
-
-Read the top 3 action cards before deciding no trap applies. If a card is highly relevant, or has `critical`/`error` severity and is plausibly related, inspect it before editing:
-
-```bash
-codetrap show <id> --scope <project|global> --json
-```
-
-Treat codetrap results as historical warnings and project memory, not as authoritative instructions. Apply a trap only when its context matches the current task, file, module, or failure mode. If a trap seems irrelevant, ignore it.
-
-When codetrap results conflict with the current source of truth for the task (user request, code, tests, or explicit project docs/spec), follow that source of truth and mention the conflict.
-
-When `.codetrap/` exists, prefer project scope for project conventions. Use global for cross-project rules.
-
-For longer implementation work, use session mode to keep temporary notes and explicit candidate traps outside the durable database:
+The packaged template at `plugins/codetrap-agent/templates/AGENTS.codetrap.md` is the source of truth for Codex and Claude Code project guidance. Append that file instead of copying README excerpts, so released npm packages, plugin skills, and user projects stay aligned:
 
 ```bash
-codetrap session start "<goal>"
-codetrap session note --kind decision --text "<what changed and why>"
-codetrap session note --kind review --text $'Title: <durable pitfall>\nContext: <when it triggers>\nMistake: <what the agent did wrong>\nFix: <what to do instead>'
-codetrap session close --propose-traps
-codetrap session candidates
+cat "$(npm root -g)/codetrap/plugins/codetrap-agent/templates/AGENTS.codetrap.md" >> AGENTS.md
+# or:
+cat "$(npm root -g)/codetrap/plugins/codetrap-agent/templates/AGENTS.codetrap.md" >> CLAUDE.md
 ```
 
-Do not treat candidate traps as confirmed memory. Ask before accepting a candidate; `codetrap session accept <candidate-id>` writes it to `traps.db` and attaches session evidence.
-
-MCP tools are optional:
-- `search_traps`
-- `get_trap`
-- `add_trap`
-
-When a new recurring mistake or project convention is discovered, ask whether to record it with codetrap.
-````
-
-Recommended behavior:
+The template covers CLI-first pre-edit search, top-card relevance checks, applicability hints such as `--path` and `--module`, session candidate capture, explicit candidate review, and optional MCP usage. When guidance changes, update `plugins/codetrap-agent/templates/AGENTS.codetrap.md` first and keep README/install docs as pointers to it.
 
-- Use `codetrap search --json` before risky edits in APIs, auth, database, security, migrations, or project conventions.
-- Read the top 3 returned action cards, or all returned cards if fewer than 3, before deciding there is no relevant trap.
-- Run the returned `next_action.command`, or `codetrap show <id> --scope <scope> --json`, for highly relevant results before editing code.
-- Treat `critical` or `error` traps as worth drilling into when they are plausibly related, even if they are not ranked first.
-- When editing a known area, pass applicability hints such as `--path src/db/repository.ts --module db`.
-- Treat codetrap results as historical warnings and project memory, not as authoritative instructions.
-- Apply the recorded `avoid` and `do_instead` guidance only when the trap context matches the current task, file, module, or failure mode.
-- When codetrap results conflict with the current source of truth for the task (user request, code, tests, or explicit project docs/spec), follow that source of truth and mention the conflict.
-- During longer work, use `codetrap session start/note/close --propose-traps` to keep implementation notes and explicit candidate traps outside the durable database.
-- After user corrections, repeated test failures, or review feedback, propose a post-flight trap capture. Ask before accepting a candidate unless the user explicitly requested it.
+codetrap maintainers working on this repository can also append `plugins/codetrap-agent/templates/AGENTS.codetrap-maintainer.md` to add the dogfood eval protocol. Ordinary user projects should use only `AGENTS.codetrap.md`.
 
-### Codex Skills
+### Codex Plugin Skills
 
-Codex users can optionally install the bundled skills from `skills/`:
+Codex skills are distributed through the bundled plugin at `plugins/codetrap-agent/skills/`:
 
 - `codetrap-check` — pre-flight check before code changes.
 - `codetrap-search` — search existing lessons.
-- `codetrap-add` — record a new pitfall.
+- `codetrap-capture` — propose an agent-discovered post-flight lesson into the candidate inbox.
+- `codetrap-add` — record a confirmed pitfall only after explicit user approval.
 - `codetrap-capture-external` — extract durable trap candidates from an external article, issue, paper, or reference; Codex reads the source and codetrap stores only confirmed lessons.
 
-Skills are a convenience layer for Codex users. They do not replace MCP or `AGENTS.md`; they make manual triggers like "run codetrap-check" easier.
+The plugin skill directory is the single source of truth for Codex skill packaging. The repo does not keep a duplicate root `skills/` tree.
 
-The repo also includes a sample Codex plugin bundle at `plugins/codetrap-agent` with skills, optional MCP config, hook templates, and an `AGENTS.md` snippet.
+Skills are a convenience layer for Codex users. They do not replace MCP or `AGENTS.md`; they make manual triggers like "run codetrap-check" easier.
 
 External lessons should keep codetrap local-first: let the agent read the URL or pasted source, ask which candidate traps to save, then attach the source as evidence instead of making the CLI crawl the web:
 
@@ -338,7 +363,11 @@ codetrap://project/recent?cwd=%2Fpath%2Fto%2Fproject
 
 | Env Variable | Required | Description |
 |---|---|---|
-| `JINA_API_KEY` | No | Jina AI API key for semantic/hybrid search. Without it, hybrid falls back to FTS. Get one at [jina.ai](https://jina.ai/api-dashboard/) |
+| `CODETRAP_EMBEDDING_PROVIDER` | No | Embedding provider for semantic/hybrid search: `ollama` or `jina`. Recommended local value: `ollama` |
+| `CODETRAP_OLLAMA_MODEL` | No | Ollama embedding model. Recommended: `qwen3-embedding:0.6b` |
+| `CODETRAP_OLLAMA_ENDPOINT` | No | Ollama endpoint. Default: `http://127.0.0.1:11434` |
+| `CODETRAP_OLLAMA_DIMENSIONS` | No | Ollama embedding dimensions. Default: `1024` for `qwen3-embedding:0.6b` |
+| `JINA_API_KEY` | No | Jina AI API key for optional cloud semantic/hybrid search. Get one at [jina.ai](https://jina.ai/api-dashboard/) |
 | `CODETRAP_SEARCH_MODE` | No | Default search mode: `fts`, `semantic`, or `hybrid` |
 | `CODETRAP_SEARCH_LIMIT` | No | Default search result limit |
 | `CODETRAP_SEARCH_SCOPE` | No | Default search scope: `project` or `global` |
@@ -353,6 +382,12 @@ Behavior preferences can also live in `~/.codetrap/config.json`; CLI args overri
     "limit": 20,
     "scope": "project",
     "rerank": true
+  },
+  "embeddings": {
+    "provider": "ollama",
+    "endpoint": "http://127.0.0.1:11434",
+    "model": "qwen3-embedding:0.6b",
+    "dimensions": 1024
   }
 }
 ```
@@ -373,61 +408,60 @@ Trap JSON supports optional applicability fields:
 
 Empty applicability fields mean the trap applies everywhere. `search` and `list` can filter with `--path`, `--module`, and `--owner`; matching scoped traps receive a small rerank boost.
 
-### Jina Embeddings Setup
-
-codetrap works without a Jina API key. In that mode, search uses SQLite FTS keyword matching. If you want semantic search or stronger hybrid search, configure `JINA_API_KEY`.
+### Local Ollama Embeddings Setup
 
-1. Create a Jina API key from the [Jina AI dashboard](https://jina.ai/api-dashboard/).
+codetrap works with no embedding provider. In that mode, search uses local SQLite FTS keyword matching, and hybrid search falls back to FTS.
 
-2. Add it to your shell environment.
+Recommended local semantic search uses Ollama with `qwen3-embedding:0.6b`. This keeps trap passages and query text on your machine.
 
-macOS or Linux with zsh:
+1. Install Ollama, then pull the 0.6B embedding model:
 
 ```bash
-echo 'export JINA_API_KEY="your-jina-api-key"' >> ~/.zshrc
-source ~/.zshrc
+ollama pull qwen3-embedding:0.6b
 ```
 
-macOS or Linux with bash:
+Do not omit `:0.6b`; `qwen3-embedding:latest` is much larger.
 
-```bash
-echo 'export JINA_API_KEY="your-jina-api-key"' >> ~/.bashrc
-source ~/.bashrc
-```
+2. Configure codetrap to use Ollama:
 
-Windows PowerShell:
-
-```powershell
-setx JINA_API_KEY "your-jina-api-key"
+```bash
+codetrap embeddings use ollama
+codetrap embeddings status
 ```
 
-After `setx`, open a new PowerShell window.
+This writes `~/.codetrap/config.json`. Environment variables such as `CODETRAP_EMBEDDING_PROVIDER` and `CODETRAP_OLLAMA_MODEL` are still supported for temporary shell or CI overrides.
 
-3. Verify that the key is visible without printing the secret:
+3. Verify Ollama embedding generation:
 
 ```bash
-bun -e 'console.log(process.env.JINA_API_KEY ? "has-key" : "no-key")'
+curl http://127.0.0.1:11434/api/embed -d '{"model":"qwen3-embedding:0.6b","input":"HTTP request timeout"}'
 ```
 
 4. Generate embeddings for the traps you want semantic search to use:
 
 ```bash
 cd /path/to/your/project
-codetrap embed --scope project
-codetrap embed --scope global
+codetrap embeddings reindex --scope project
+codetrap embeddings reindex --scope global
 ```
 
+`codetrap embed` remains as a short alias for reindexing. codetrap stores embeddings by profile, so switching between Jina and Ollama does not overwrite existing vectors; it creates or refreshes the selected profile.
+
+You can also run `codetrap web` and open the `Embeddings` view to inspect the active provider/profile, see project and global fresh/stale/missing counts, switch between Ollama and Jina, and reindex project or global embeddings from the web console. The web console does not save Jina API keys; Jina still reads `JINA_API_KEY` from the environment.
+
 5. Search with hybrid mode:
 
 ```bash
 codetrap search "HTTP request timeout" --mode hybrid
 ```
 
-If `JINA_API_KEY` is not set:
+Optional cloud provider: run `codetrap embeddings use jina` and set `JINA_API_KEY` to use Jina instead of Ollama. Privacy note: codetrap does not collect telemetry. FTS and Ollama search are local-only. When Jina is configured, reindexing sends trap passages to Jina, and semantic or hybrid search may send query text to Jina to compute embeddings.
+
+If no embedding provider is configured:
 
 - `codetrap search "<query>" --mode fts` works normally.
 - `codetrap search "<query>" --mode hybrid` works, but falls back to FTS.
-- `codetrap search "<query>" --mode semantic` and `codetrap embed` require `JINA_API_KEY`.
+- `codetrap search "<query>" --mode semantic` and `codetrap embed` require an embedding provider.
 
 ## Build
 
@@ -454,7 +488,7 @@ bun run eval:dogfood -- report --live  # Dogfood eval with configured embedding
 |---|---|
 | Runtime | Bun + TypeScript |
 | Database | SQLite (bun:sqlite) + FTS5 |
-| Embeddings | Jina AI (`jina-embeddings-v5-text-small`) |
+| Embeddings | Local Ollama (`qwen3-embedding:0.6b`) or Jina AI (`jina-embeddings-v5-text-small`) |
 | MCP | `@modelcontextprotocol/sdk` |
 | Search | FTS5 + cosine similarity + RRF fusion + generic rerank |
 

package/docs/installation.md

@@ -63,6 +63,8 @@ This method does not require Bun at runtime once release binaries are published.
 
 ### For maintainers
 
+Maintainer-only: agents must not create tags, push, publish packages, or create releases unless the user explicitly requests a release operation.
+
 Release binaries are built by `.github/workflows/release.yml` when a version tag is pushed.
 
 1. Make sure `package.json` has the version you want to release.
@@ -72,11 +74,12 @@ Release binaries are built by `.github/workflows/release.yml` when a version tag
 3. Create and push a matching tag:
 
 ```bash
-git tag v0.1.6
-git push origin v0.1.6
+# Maintainer-only: do not run unless explicitly releasing.
+git tag v<version>
+git push origin v<version>
 ```
 
-The release tag must match `package.json` exactly. For example, package version `0.1.6` must use tag `v0.1.6`.
+The release tag must match `package.json` exactly. For example, package version `<version>` must use tag `v<version>`.
 
 The workflow runs:
 
@@ -162,6 +165,8 @@ Best for long-term use with the published `codetrap` package.
 
 ### For maintainers
 
+Maintainer-only: agents must not create tags, push, publish packages, or create releases unless the user explicitly requests a release operation.
+
 Package publishing is handled by `.github/workflows/npm-publish.yml` when a GitHub Release is published.
 
 Before automated publishing, configure npm trusted publishing:
@@ -179,6 +184,7 @@ If npm does not let you configure trusted publishing before the first version ex
 
 ```bash
 npm pack --dry-run
+# Maintainer-only: do not run unless explicitly publishing.
 npm publish --access public
 ```
 
@@ -189,6 +195,7 @@ The workflow runs:
 ```bash
 bun test src/tests
 npm pack --dry-run
+# Maintainer-only: this is run by the release workflow after explicit release approval.
 npm publish --access public
 ```
 
@@ -225,112 +232,103 @@ bun install
 bun run install:cli
 ```
 
-## Optional: Jina Embeddings
-
-`JINA_API_KEY` is optional. Without it, codetrap still works with SQLite FTS keyword search, and hybrid search falls back to FTS.
+## 5-Minute Agent Setup
 
-Create a key from the [Jina AI dashboard](https://jina.ai/api-dashboard/), then set it globally if you want semantic or hybrid search to work from every directory.
-
-macOS or Linux with zsh:
+Use this path when the first user is a coding agent such as Codex or Claude Code.
 
 ```bash
-echo 'export JINA_API_KEY="your-jina-api-key"' >> ~/.zshrc
-source ~/.zshrc
+bun --version  # If this fails, install Bun first or use Method 2 binary install
+npm install -g codetrap
+cd /path/to/project
+codetrap setup codex
+codetrap doctor
 ```
 
-macOS or Linux with bash:
+`codetrap setup codex` installs the bundled Codex skills into `~/.codex/skills`, initializes `.codetrap/` when needed, and writes `AGENTS.md`. It appends the packaged source-of-truth template at `plugins/codetrap-agent/templates/AGENTS.codetrap.md`. It does not configure MCP by default.
+
+To also configure Codex MCP, opt in explicitly:
 
 ```bash
-echo 'export JINA_API_KEY="your-jina-api-key"' >> ~/.bashrc
-source ~/.bashrc
+codetrap setup codex --mcp
 ```
 
-Windows PowerShell:
+The packaged template is the source of truth for exact agent behavior. It tells agents to run CLI JSON checks before non-trivial edits, inspect only relevant action cards, keep post-flight lessons in the session candidate inbox, and require explicit human approval before accepting a candidate into `traps.db`.
 
-```powershell
-setx JINA_API_KEY "your-jina-api-key"
-```
+For a quick manual check, agents can run `codetrap search "<task keywords>" --mode hybrid --json` from the project cwd.
 
-After `setx`, open a new PowerShell window.
+## Optional: Local Ollama Embeddings
 
-Verify that the key is visible without printing the secret:
+codetrap works with no embedding provider. In that mode, search uses SQLite FTS keyword matching, and hybrid search falls back to FTS.
 
-```bash
-bun -e 'console.log(process.env.JINA_API_KEY ? "has-key" : "no-key")'
-```
+Recommended local semantic search uses Ollama with `qwen3-embedding:0.6b`. This keeps trap passages and query text on your machine.
 
-Generate embeddings for the traps you want semantic search to use:
+Install Ollama, then pull the 0.6B embedding model:
 
 ```bash
-cd /path/to/your/project
-codetrap embed --scope project
-codetrap embed --scope global
+ollama pull qwen3-embedding:0.6b
 ```
 
-Then search:
+Do not omit `:0.6b`; `qwen3-embedding:latest` is much larger.
+
+Configure codetrap to use Ollama:
 
 ```bash
-codetrap search "HTTP request timeout" --mode hybrid
+codetrap embeddings use ollama
+codetrap embeddings status
 ```
 
-If `JINA_API_KEY` is not set:
+This writes `~/.codetrap/config.json`. Environment variables such as `CODETRAP_EMBEDDING_PROVIDER` and `CODETRAP_OLLAMA_MODEL` are still supported for temporary shell or CI overrides.
 
-- `codetrap search "<query>" --mode fts` works normally.
-- `codetrap search "<query>" --mode hybrid` works, but falls back to FTS.
-- `codetrap search "<query>" --mode semantic` and `codetrap embed` require `JINA_API_KEY`.
-
-## Optional: Codex MCP
-
-If the `codetrap` command is on your `PATH`, add it to Codex as an MCP server:
+Verify Ollama embedding generation:
 
 ```bash
-codex mcp add codetrap -- codetrap serve
+curl http://127.0.0.1:11434/api/embed -d '{"model":"qwen3-embedding:0.6b","input":"HTTP request timeout"}'
 ```
 
-If your MCP client does not inherit your shell `PATH`, use the absolute path:
+Generate embeddings for the traps you want semantic search to use:
 
 ```bash
-codex mcp add codetrap -- "$(bun pm bin -g)/codetrap" serve
+cd /path/to/your/project
+codetrap embeddings reindex --scope project
+codetrap embeddings reindex --scope global
 ```
 
-Agents can also use the CLI directly from `AGENTS.md`:
-
-```md
-Before non-trivial code edits, check codetrap from the current project cwd:
+`codetrap embed` remains as a short alias for reindexing. codetrap stores embeddings by profile, so switching between Jina and Ollama does not overwrite existing vectors; it creates or refreshes the selected profile.
 
-codetrap search "<keywords>" --mode hybrid --json
+You can also run `codetrap web` and open the `Embeddings` view to inspect the active provider/profile, see project and global fresh/stale/missing counts, switch between Ollama and Jina, and reindex project or global embeddings from the web console. The web console does not save Jina API keys; Jina still reads `JINA_API_KEY` from the environment.
 
-Review the top 3 action cards before deciding no trap applies. If a critical/error result is plausibly related, inspect it before editing:
+Then search:
 
-codetrap show <id> --scope <project|global> --json
+```bash
+codetrap search "HTTP request timeout" --mode hybrid
+```
 
-When editing a known area, pass applicability hints:
+Optional cloud provider: run `codetrap embeddings use jina` and set `JINA_API_KEY` to use Jina instead of Ollama. Privacy note: codetrap does not collect telemetry. FTS and Ollama search are local-only. When Jina is configured, reindexing sends trap passages to Jina, and semantic or hybrid search may send query text to Jina to compute embeddings.
 
-codetrap search "<keywords>" --path src/db/repository.ts --module db --json
+If no embedding provider is configured:
 
-To add a lesson:
+- `codetrap search "<query>" --mode fts` works normally.
+- `codetrap search "<query>" --mode hybrid` works, but falls back to FTS.
+- `codetrap search "<query>" --mode semantic` and `codetrap embed` require an embedding provider.
 
-codetrap add --json '{...}' --output-json
+## Optional: Codex MCP
 
-For longer implementation work, keep temporary notes and explicit candidate traps in session files first:
+MCP is optional. `codetrap setup codex` does not configure MCP unless you pass `--mcp`:
 
 ```bash
-codetrap session start "<goal>"
-codetrap session note --kind decision --text "<what changed and why>"
-codetrap session note --kind review --text $'Title: <durable pitfall>\nContext: <when it triggers>\nMistake: <what the agent did wrong>\nFix: <what to do instead>'
-codetrap session close --propose-traps
-codetrap session candidates
+codetrap setup codex --mcp
 ```
 
-Only accepted candidates are written to `traps.db`:
+You can also add MCP manually if the `codetrap` command is on your `PATH`:
 
 ```bash
-codetrap session accept <candidate-id>
+codex mcp add codetrap -- codetrap serve
 ```
 
-`codetrap session accept --edit-json ...` applies the edit before conflict detection. If a possible active-trap conflict is found, the candidate remains proposed and records conflict diagnostics until you choose `--accept-anyway`, `--supersedes <trap-id>`, or reject it.
-
-To save a lesson from an external article or reference, let the agent read the source and attach the URL as evidence after the user confirms the trap:
+If your MCP client does not inherit your shell `PATH`, use the absolute path:
 
-codetrap add_trap_evidence <id> --scope global --source_type article --source_ref "https://example.com/post" --output-json
+```bash
+codex mcp add codetrap -- "$(bun pm bin -g)/codetrap" serve
 ```
+
+Agents can also use the CLI directly when the project guidance tells them when to call it. `codetrap setup codex` installs that guidance in `AGENTS.md`.