codetrap 0.1.2 → 0.1.3

package/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "codetrap-local",
+  "interface": {
+    "displayName": "codetrap Local"
+  },
+  "plugins": [
+    {
+      "name": "codetrap-agent",
+      "source": {
+        "source": "local",
+        "path": "./plugins/codetrap-agent"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

package/README.md

@@ -2,7 +2,7 @@
 
 > A local-first coding pitfall memory bank — record mistakes once, never repeat them twice.
 
-**codetrap** records structured coding pitfalls ("traps") and provides search across them before you write code. It serves both human developers via CLI and AI coding agents via MCP (Model Context Protocol).
+**codetrap** records structured coding pitfalls ("traps") and provides search across them before you write code. It is CLI-first for humans and AI coding agents, with an optional MCP (Model Context Protocol) adapter for clients that prefer tool schemas.
 
 ## Why?
 
@@ -36,9 +36,12 @@ codetrap add --json '{
   "tags": ["fetch", "timeout", "http"]
 }'
 
-# Search for relevant traps
+# Search for relevant traps as a human
 codetrap search "HTTP request timeout" --mode hybrid
 
+# Search for relevant traps as an agent
+codetrap search "HTTP request timeout" --mode hybrid --json
+
 # List all traps
 codetrap list
 
@@ -50,11 +53,13 @@ codetrap show 1
 
 - **Structured trap recording** — title, category, context, mistake, fix, severity, tags, lifecycle, evidence, before/after code
 - **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)
 - **Chinese + mixed-language search** — CJK bigram tokenizer, synonym map for Chinese-English terms
-- **MCP server** — 10 tools + 4 resources for AI agent integration
+- **MCP server** — optional tools + resources for AI agent integration
 - **Embedding cache** with freshness tracking — embeddings are rebuildable, stale ones auto-invalidated
-- **Schema migrations** — in-code migration system from v0 through current v4
+- **Doctor diagnostics** — scope, database, and embedding health in text or JSON
+- **Schema migrations** — in-code migration system from v0 through current v5
 - **Single-binary builds** — `bun build --compile` produces standalone binaries in `dist/`
 
 ## Directory Structure
@@ -64,7 +69,9 @@ codetrap/
 ├── src/
 │   ├── index.ts              CLI entry point
 │   ├── mcp-server.ts         MCP server entry point
-│   ├── commands/router.ts    CLI command dispatch
+│   ├── commands/router.ts    Thin CLI adapter + renderer
+│   ├── commands/workflow.ts  CLI command behavior
+│   ├── commands/command-result.ts  CLI command results + rendering
 │   ├── mcp/
 │   │   ├── server.ts         MCP stdio transport + handlers
 │   │   ├── tools.ts          10 MCP tool definitions
@@ -73,13 +80,23 @@ codetrap/
 │   ├── lib/
 │   │   ├── store.ts          Project/global scope orchestration
 │   │   ├── trap-operations.ts Shared CLI/MCP operation semantics
-│   │   ├── search-service.ts FTS/semantic/hybrid search, RRF fusion
+│   │   ├── output-json.ts    Shared CLI/MCP JSON presenters
+│   │   ├── 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-health.ts  Fresh/stale/missing embedding summaries
+│   │   ├── 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
 │   │   ├── search-normalizer.ts  CJK bigram, synonyms, search_text
 │   │   ├── fts-query.ts      Safe FTS5 literal query compiler
 │   │   ├── trap-search-document.ts Derived search text + embedding passage
-│   │   ├── trap-json-fields.ts Tags/evidence JSON array codec
+│   │   ├── 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
+│   │   ├── 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
 │   │   ├── embedding-job.ts  Batch embedding generation
 │   │   ├── format.ts         CLI output formatting
@@ -96,9 +113,12 @@ codetrap/
 │       ├── trap-*.test.ts
 │       ├── mcp-tools.test.ts
 │       ├── scope.test.ts
+│       ├── 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
+├── scripts/                  Release asset and preflight scripts
 ├── docs/                     Architecture + reference docs
 ├── package.json
 ├── tsconfig.json
@@ -111,29 +131,32 @@ codetrap/
 |---|---|
 | `init` | Initialize `.codetrap/` in current project |
 | `add` | Record a new trap (`--json` structured input; interactive mode is not implemented) |
-| `search <query>` | Search traps (--mode fts\|semantic\|hybrid, --category, --scope, --status, --limit) |
-| `list` | List traps (--category, --scope, --status, --limit) |
-| `show <id>` | Show full trap details |
-| `edit <id>` | Edit a trap |
-| `delete <id>` | Delete a trap |
-| `add_trap_evidence <id>` | Attach source/evidence metadata |
-| `archive_trap <id>` | Archive a trap so default search skips it |
-| `supersede_trap <old_id> <new_id>` | Mark one trap as replaced by another |
+| `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) |
+| `edit <id>` | Edit a trap (`--json` input, `--output-json` output) |
+| `delete <id>` | Delete a trap (--json) |
+| `add_trap_evidence <id>` | Attach source/evidence metadata (--output-json) |
+| `archive_trap <id>` | Archive a trap so default search skips it (--json) |
+| `supersede_trap <old_id> <new_id>` | Mark one trap as replaced by another (--json) |
 | `export` | Export traps to JSON |
-| `import` | Import traps from JSON |
-| `stats` | Show database statistics |
+| `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) |
+| `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) |
 | `serve` | Start MCP server |
 
 ## Agent Integration
 
-For AI coding agents, use three layers:
+For AI coding agents, use the CLI as the default integration path:
 
-- **MCP** gives the agent structured tools like `search_traps` and `add_trap`.
+- **CLI JSON** is the primary agent API and works in any client that can run shell commands.
 - **AGENTS.md / CLAUDE.md** tells the agent when to use codetrap.
-- **CLI** is the fallback that works even when MCP is unavailable.
+- **MCP** is an optional adapter for clients that prefer tool schemas.
 
-MCP and project guidance are complementary. MCP tells the agent what it can call; `AGENTS.md` or `CLAUDE.md` tells it when to call it.
+CLI and project guidance are the main path. MCP should stay thin and share the same store/search behavior.
 
 ### MCP Setup
 
@@ -165,26 +188,37 @@ Add this to `AGENTS.md` for Codex, or to `CLAUDE.md` for Claude Code:
 
 Before non-trivial code edits, check codetrap for relevant pitfalls.
 
-Prefer MCP tools when available:
-- `search_traps`
-- `get_trap`
-- `add_trap`
+Default to CLI JSON from the current project cwd:
 
-Fallback to CLI:
+```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 search "<keywords>" --mode hybrid
+codetrap show <id> --scope <project|global> --json
 ```
 
+When `.codetrap/` exists, prefer project scope for project conventions. Use global for cross-project rules.
+
+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:
 
-- Use `search_traps` or `codetrap search` before risky edits in APIs, auth, database, security, migrations, or project conventions.
-- Call `get_trap` for highly relevant results before editing code.
+- 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`.
 - Apply the recorded `avoid` and `do_instead` guidance while making changes.
-- Ask before recording a new trap unless the user explicitly requested it.
+- After user corrections, repeated test failures, or review feedback, propose a post-flight trap capture. Ask before recording a new trap unless the user explicitly requested it.
 
 ### Codex Skills
 
@@ -196,6 +230,8 @@ Codex users can optionally install the bundled skills from `skills/`:
 
 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 repo also includes a sample Codex plugin bundle at `plugins/codetrap-agent` with skills, optional MCP config, hook templates, and an `AGENTS.md` snippet.
+
 ### MCP Tools
 
 | Tool | Description |
@@ -219,13 +255,50 @@ Skills are a convenience layer for Codex users. They do not replace MCP or `AGEN
 - `codetrap://global/top` — Most-hit global traps
 - `codetrap://{scope}/trap/{id}` — Individual trap by ID
 
+Resources can accept an optional encoded `cwd` query parameter when the client knows the target workspace:
+
+```text
+codetrap://project/recent?cwd=%2Fpath%2Fto%2Fproject
+```
+
 ## Configuration
 
 | 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_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` |
+| `CODETRAP_RERANK` | No | Enable query-aware reranking (`true`/`false`) |
+
+Behavior preferences can also live in `~/.codetrap/config.json`; CLI args override config, config overrides env vars, and env vars override built-in defaults.
+
+```json
+{
+  "search": {
+    "mode": "hybrid",
+    "limit": 20,
+    "scope": "project",
+    "rerank": true
+  }
+}
+```
+
+API keys still belong in environment variables, not config files.
+
+### Scoped Traps
+
+Trap JSON supports optional applicability fields:
+
+```json
+{
+  "path_globs": ["src/db/**"],
+  "module": "db",
+  "owner": "platform"
+}
+```
 
-All other behavior is configured via sensible defaults — see `src/lib/constants.ts`.
+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
 
@@ -289,6 +362,8 @@ If `JINA_API_KEY` is not set:
 bun run build          # Build CLI + MCP server binaries → dist/
 bun run build:cli      # dist/codetrap
 bun run build:serve    # dist/codetrap-serve
+bunx tsc --noEmit      # Type-check without emitting files
+bun run release:preflight  # tests, builds, release assets, smoke test, npm dry-runs
 ```
 
 ## Test
@@ -306,7 +381,7 @@ bun test src/tests/search-eval.test.ts # Recall@5 evaluation
 | Database | SQLite (bun:sqlite) + FTS5 |
 | Embeddings | Jina AI (`jina-embeddings-v5-text-small`) |
 | MCP | `@modelcontextprotocol/sdk` |
-| Search | FTS5 + cosine similarity + RRF fusion |
+| Search | FTS5 + cosine similarity + RRF fusion + generic rerank |
 
 ## License
 

package/docs/installation.md

@@ -1,6 +1,6 @@
 # Installation
 
-codetrap supports three installation paths. Use source installation while developing the tool, binary installation for users who do not want a Bun toolchain, and package-manager installation after publishing the package.
+codetrap supports three installation paths. Use source installation while developing the tool, binary installation for users who do not want a Bun toolchain, and package-manager installation for the published `codetrap` package.
 
 ## Method 1: Source Install
 
@@ -72,11 +72,11 @@ 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.1
-git push origin v0.1.1
+git tag v0.1.2
+git push origin v0.1.2
 ```
 
-The release tag must match `package.json` exactly. For example, package version `0.1.1` must use tag `v0.1.1`.
+The release tag must match `package.json` exactly. For example, package version `0.1.2` must use tag `v0.1.2`.
 
 The workflow runs:
 
@@ -158,7 +158,7 @@ Then add `%USERPROFILE%\bin` to your user `Path`.
 
 ## Method 3: Package-Manager Install
 
-Best for long-term use after codetrap is published as a package.
+Best for long-term use with the published `codetrap` package.
 
 ### For maintainers
 
@@ -202,7 +202,7 @@ npm pack --dry-run
 
 ### For users
 
-Bun users can install it globally after publishing:
+Bun users can install it globally:
 
 ```bash
 bun add -g codetrap
@@ -216,7 +216,7 @@ npm install -g codetrap
 codetrap --help
 ```
 
-Until the package is published, use the source install method:
+For local development or unpublished branch testing, use the source install method:
 
 ```bash
 git clone <repo-url>
@@ -296,11 +296,19 @@ codex mcp add codetrap -- "$(bun pm bin -g)/codetrap" serve
 Agents can also use the CLI directly from `AGENTS.md`:
 
 ```md
-Before non-trivial code edits, check codetrap:
+Before non-trivial code edits, check codetrap from the current project cwd:
 
-codetrap search "<keywords>" --mode hybrid
+codetrap search "<keywords>" --mode hybrid --json
+
+Review the top 3 action cards before deciding no trap applies. If a critical/error result is plausibly related, inspect it before editing:
+
+codetrap show <id> --scope <project|global> --json
+
+When editing a known area, pass applicability hints:
+
+codetrap search "<keywords>" --path src/db/repository.ts --module db --json
 
 To add a lesson:
 
-codetrap add --json '{...}'
+codetrap add --json '{...}' --output-json
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codetrap",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Capture and retrieve coding pitfalls so AI doesn't repeat mistakes",
   "type": "module",
   "license": "MIT",
@@ -33,6 +33,8 @@
     "src/index.ts",
     "src/mcp-server.ts",
     "skills",
+    "plugins",
+    ".agents/plugins/marketplace.json",
     "scripts",
     "docs/installation.md",
     ".env.example",
@@ -46,6 +48,7 @@
     "dev": "bun run src/index.ts",
     "install:cli": "ln -sf \"$PWD/bin/codetrap\" \"$(bun pm bin -g)/codetrap\"",
     "build:release": "bun run scripts/build-release.ts",
+    "release:preflight": "bun run scripts/release-preflight.ts",
     "check:release-version": "bun run scripts/check-release-version.ts",
     "build": "bun build ./src/index.ts --compile --outfile dist/codetrap && bun build ./src/mcp-server.ts --compile --outfile dist/codetrap-serve",
     "build:cli": "bun build ./src/index.ts --compile --outfile dist/codetrap",

package/plugins/codetrap-agent/.codex-plugin/plugin.json

@@ -0,0 +1,34 @@
+{
+  "name": "codetrap-agent",
+  "version": "0.1.2",
+  "description": "CLI-first codetrap integration bundle for coding agents.",
+  "author": {
+    "name": "codetrap maintainers",
+    "email": "maintainers@example.com",
+    "url": "https://github.com/woertedetiankong/codetrap"
+  },
+  "homepage": "https://github.com/woertedetiankong/codetrap#readme",
+  "repository": "https://github.com/woertedetiankong/codetrap",
+  "license": "MIT",
+  "keywords": ["agent", "memory", "cli", "mcp", "pitfalls"],
+  "skills": "./skills/",
+  "hooks": "./hooks.json",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "codetrap Agent",
+    "shortDescription": "Check local pitfall memory before code changes.",
+    "longDescription": "Installs CLI-first guidance, optional MCP config, and example hooks so coding agents can search codetrap before risky edits and propose new trap captures after failures.",
+    "developerName": "codetrap maintainers",
+    "category": "Productivity",
+    "capabilities": ["Tools", "Memory", "Code"],
+    "websiteURL": "https://github.com/woertedetiankong/codetrap",
+    "privacyPolicyURL": "https://github.com/woertedetiankong/codetrap#readme",
+    "termsOfServiceURL": "https://github.com/woertedetiankong/codetrap/blob/main/LICENSE",
+    "defaultPrompt": [
+      "Check codetrap before editing this code.",
+      "Search prior pitfalls for this task.",
+      "Propose a codetrap for this failure."
+    ],
+    "brandColor": "#2563EB"
+  }
+}

package/plugins/codetrap-agent/hooks/post-flight-capture.example.md

@@ -0,0 +1,25 @@
+# Post-flight Codetrap Capture
+
+Use this template after a task reveals a reusable pitfall. Do not write the trap automatically; ask the user to confirm first.
+
+```json
+{
+  "title": "Short pitfall title",
+  "category": "bug",
+  "scope": "project",
+  "context": "When this situation appears...",
+  "mistake": "The agent tends to...",
+  "fix": "Do this instead...",
+  "tags": ["area", "tool"],
+  "severity": "warning",
+  "path_globs": ["src/example/**"],
+  "module": "example",
+  "owner": "platform"
+}
+```
+
+After confirmation:
+
+```bash
+codetrap add --json '<json above>' --output-json
+```

package/plugins/codetrap-agent/hooks/pre-edit.example.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env sh
+set -eu
+
+query="${CODETRAP_QUERY:-${1:-}}"
+if [ -z "$query" ]; then
+  echo "CODETRAP_QUERY or first argument is required" >&2
+  exit 2
+fi
+
+codetrap search "$query" --mode hybrid --json

package/plugins/codetrap-agent/hooks.json

@@ -0,0 +1,11 @@
+{
+  "description": "Example codetrap hook bundle. Treat these commands as templates for clients with hook support.",
+  "pre_edit": {
+    "description": "Before non-trivial edits, search local pitfalls from the target project cwd.",
+    "command": "codetrap search \"$CODETRAP_QUERY\" --mode hybrid --json"
+  },
+  "post_task": {
+    "description": "After repeated failures or user corrections, propose a structured trap; write only after user confirmation.",
+    "command": "codetrap add --json '{...}' --output-json"
+  }
+}

package/plugins/codetrap-agent/skills/codetrap-capture/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: codetrap-capture
+description: Propose a new codetrap after repeated failures, user corrections, or review feedback.
+---
+
+Use this after a task exposes a recurring mistake pattern. Draft a candidate trap with:
+
+- triggering context
+- mistake to avoid
+- fix to apply next time
+- severity
+- tags
+- optional `path_globs`, `module`, and `owner`
+
+Ask the user to confirm before writing. After confirmation, run:
+
+```bash
+codetrap add --json '{...}' --output-json
+```

package/plugins/codetrap-agent/skills/codetrap-check/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: codetrap-check
+description: Check codetrap from the current project cwd before non-trivial code edits.
+---
+
+Before risky code changes, run:
+
+```bash
+codetrap search "<task keywords>" --mode hybrid --json
+```
+
+Review the top 3 action cards. If a card is highly relevant, or has `critical` or `error` severity and is plausibly related, run its `next_action.command` before editing.
+
+Use MCP only as an optional adapter. When calling MCP tools, pass `cwd` when the client supports it.

package/plugins/codetrap-agent/templates/AGENTS.codetrap.md

@@ -0,0 +1,25 @@
+## Codetrap
+
+Before non-trivial code edits, check local pitfall memory from the current project cwd:
+
+```bash
+codetrap search "<keywords>" --mode hybrid --json
+```
+
+Review the top 3 action cards before deciding no trap applies. If a card is highly relevant, or has `critical` or `error` severity and is plausibly related, inspect it before editing:
+
+```bash
+codetrap show <id> --scope <project|global> --json
+```
+
+When editing a specific area, pass applicability hints:
+
+```bash
+codetrap search "<keywords>" --path src/db/repository.ts --module db --json
+```
+
+After user corrections, repeated test failures, or review feedback, propose a new trap. Only write it after user confirmation:
+
+```bash
+codetrap add --json '{...}' --output-json
+```

package/scripts/release-preflight.ts

@@ -0,0 +1,55 @@
+#!/usr/bin/env bun
+
+const tag = process.argv[2] ?? process.env.RELEASE_TAG;
+const packageJson = await Bun.file("package.json").json() as { name?: string; version?: string };
+const published = await packageVersionExists(packageJson.name, packageJson.version);
+
+const commands: { name: string; cmd: string[]; optional?: boolean }[] = [
+  ...(tag ? [{ name: "check release version", cmd: ["bun", "run", "check:release-version", tag] }] : []),
+  { name: "test", cmd: ["bun", "test", "src/tests"] },
+  { name: "build", cmd: ["bun", "run", "build"] },
+  { name: "build release assets", cmd: ["bun", "run", "build:release"] },
+  { name: "smoke test release binary", cmd: [hostBinaryPath(), "--help"] },
+  { name: "npm pack dry-run", cmd: ["npm", "pack", "--dry-run"] },
+  ...(!published ? [{ name: "npm publish dry-run", cmd: ["npm", "publish", "--dry-run", "--access", "public"] }] : []),
+];
+
+for (const step of commands) {
+  console.log(`\n==> ${step.name}`);
+  const proc = Bun.spawnSync({
+    cmd: step.cmd,
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+  if (!proc.success) {
+    console.error(`Release preflight failed at: ${step.name}`);
+    process.exit(proc.exitCode ?? 1);
+  }
+}
+
+if (published) {
+  console.log(`\nSkipped npm publish dry-run because ${packageJson.name}@${packageJson.version} is already published.`);
+}
+console.log("\nRelease preflight passed. No package was published and no GitHub release was created.");
+
+function hostBinaryPath(): string {
+  const platform = process.platform;
+  const arch = process.arch;
+  if (platform === "darwin" && arch === "arm64") return "./dist/release/codetrap-darwin-arm64";
+  if (platform === "darwin" && arch === "x64") return "./dist/release/codetrap-darwin-x64";
+  if (platform === "linux" && arch === "arm64") return "./dist/release/codetrap-linux-arm64";
+  if (platform === "linux" && arch === "x64") return "./dist/release/codetrap-linux-x64";
+  if (platform === "win32" && arch === "x64") return "./dist/release/codetrap-windows-x64.exe";
+  throw new Error(`Unsupported release smoke-test platform: ${platform}/${arch}`);
+}
+
+async function packageVersionExists(name?: string, version?: string): Promise<boolean> {
+  if (!name || !version) return false;
+  const proc = Bun.spawnSync({
+    cmd: ["npm", "view", `${name}@${version}`, "version", "--json"],
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (!proc.success) return false;
+  return new TextDecoder().decode(proc.stdout).trim().replace(/^"|"$/g, "") === version;
+}

package/skills/codetrap-add/SKILL.md

@@ -50,9 +50,12 @@ codetrap add --json '{
   "fix": "<what should be done instead>",
   "tags": ["<tag1>", "<tag2>"],
   "severity": "<warning|error|critical>",
+  "path_globs": ["src/example/**"],
+  "module": "<optional subsystem>",
+  "owner": "<optional team>",
   "before_code": "<wrong code snippet (optional)>",
   "after_code": "<correct code snippet (optional)>"
-}'
+}' --output-json
 ```
 
 If the CLI is not available, use the MCP tool `add_trap` instead.

package/skills/codetrap-check/SKILL.md

@@ -23,13 +23,33 @@ From the user's request, extract search keywords. Focus on:
 
 ## Step 2: Search the database
 
-Call the MCP tool `search_traps` with the extracted keywords. Search both project and global scopes.
+Default to the CLI from the current project cwd:
+
+```bash
+codetrap search "<keywords>" --mode hybrid --json
+```
+
+When the task targets a known file or subsystem, include applicability hints:
+
+```bash
+codetrap search "<keywords>" --path src/db/repository.ts --module db --json
+```
+
+If the query comes from another tool, stdin is also supported:
+
+```bash
+echo "<keywords>" | codetrap search --mode hybrid --json
+```
+
+MCP `search_traps` is optional. Use it only when it is already available and project-scoped correctly; pass `cwd` when the client supports it.
+
+Review the top 3 returned action cards before deciding that no trap applies. Do not stop after only the first result; relevant traps may rank second or third. If fewer than 3 cards are returned, review all returned cards.
 
 ## Step 3: Apply the lessons
 
-For each relevant trap found:
+For each relevant trap found in the reviewed top cards:
 1. Read the action card's `avoid` and `do_instead`
-2. If the card is highly relevant and you are about to edit code, call `get_trap` with `next_action.details_args.id` and `next_action.details_args.scope`
+2. If the card is highly relevant, or has `critical`/`error` severity and is plausibly related, and you are about to edit code, run `next_action.command` from CLI JSON; with MCP, call `get_trap` with `next_action.details_args.id` and `next_action.details_args.scope`
 3. Adjust your code generation to follow the correct approach
 4. If a trap matches exactly what you were about to do, explicitly tell the user: "I was about to [avoid], but the codetrap database says [do_instead]. I'll do it the right way."
 
@@ -44,4 +64,4 @@ If no traps found, say nothing — don't waste tokens.
 
 ## Step 5: Record new pitfalls
 
-If while writing code you discover a NEW pitfall that isn't in the database, suggest: "This seems like a recurring pitfall. Want me to record it with `/codetrap-add`?"
+If while writing code you discover a NEW pitfall that isn't in the database, propose a post-flight trap candidate. Do not write it automatically; ask: "This seems like a recurring pitfall. Want me to record it with `/codetrap-add`?"