release: v0.4.0

.claude.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "codegraph": {
+      "type": "stdio",
+      "command": "codegraph",
+      "args": [
+        "serve",
+        "--mcp"
+      ]
+    }
+  }
+}

.claude/CLAUDE.md

@@ -0,0 +1,33 @@
+<!-- CODEGRAPH_START -->
+## CodeGraph
+
+This project has a CodeGraph MCP server (`codegraph_*` tools) configured. CodeGraph is a tree-sitter-parsed knowledge graph of every symbol, edge, and file. Reads are sub-millisecond and return structural information grep cannot.
+
+### When to prefer codegraph over native search
+
+Use codegraph for **structural** questions — what calls what, what would break, where is X defined, what is X's signature. Use native grep/read only for **literal text** queries (string contents, comments, log messages) or after you already have a specific file open.
+
+| Question | Tool |
+|---|---|
+| "Where is X defined?" / "Find symbol named X" | `codegraph_search` |
+| "What calls function Y?" | `codegraph_callers` |
+| "What does Y call?" | `codegraph_callees` |
+| "What would break if I changed Z?" | `codegraph_impact` |
+| "Show me Y's signature / source / docstring" | `codegraph_node` |
+| "Give me focused context for a task/area" | `codegraph_context` |
+| "Survey an unfamiliar module/topic" | `codegraph_explore` |
+| "What files exist under path/" | `codegraph_files` |
+| "Is the index healthy?" | `codegraph_status` |
+
+### Rules of thumb
+
+- **Trust codegraph results.** They come from a full AST parse. Do NOT re-verify them with grep — that's slower, less accurate, and wastes context.
+- **Don't grep first** when looking up a symbol by name. `codegraph_search` is faster and returns kind + location + signature in one call.
+- **Don't chain `codegraph_search` + `codegraph_node`** when you just want context — `codegraph_context` is one call.
+- **`codegraph_explore` is the heavy hitter** for unfamiliar areas — it returns full source from all relevant files in one call, but is token-heavy. If your harness supports parallel subagents (e.g., Claude Code's Task tool), spawn one for explore-class questions to keep main session context clean.
+- **Index lag**: the file watcher debounces ~500ms behind writes; don't re-query immediately after editing a file in the same turn.
+
+### If `.codegraph/` doesn't exist
+
+The MCP server returns "not initialized." Ask the user: *"I notice this project doesn't have CodeGraph initialized. Want me to run `codegraph init -i` to build the index?"*
+<!-- CODEGRAPH_END -->

.claude/settings.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__codegraph__codegraph_search",
+      "mcp__codegraph__codegraph_context",
+      "mcp__codegraph__codegraph_callers",
+      "mcp__codegraph__codegraph_callees",
+      "mcp__codegraph__codegraph_impact",
+      "mcp__codegraph__codegraph_node",
+      "mcp__codegraph__codegraph_status"
+    ]
+  }
+}

.claude/skills/check-licenses/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: check-licenses
-description: Audit direct third-party Go dependencies for license compatibility with Apache 2.0, present them for user verification, and maintain the Third-Party Notices section in LICENSE
+description: Audit direct third-party Go dependencies for license compatibility with Apache 2.0, present them for user verification, and maintain the Third-Party Notices section in LICENSE. Build tools (linters, code generators) are tracked separately in docs/development-tools.md, never in LICENSE.
 ---
 
 ## Instructions
@@ -27,9 +27,18 @@ Also run:
 git diff HEAD~1 -- Makefile
 ```
 Scan the diff for changes to `go install` lines (anywhere in the file):
-- Lines prefixed `+` matching `go install`: added build tools → add to LICENSE.
+- Lines prefixed `+` matching `go install`: added build tools → add to
+  `docs/development-tools.md` under `## Build tools`.
 - Lines prefixed `-` matching `go install`: removed build tools → remove from
-  LICENSE only if the base module does NOT also appear in any `go.mod`.
+  `docs/development-tools.md` only if the base module does NOT also appear
+  in any `go.mod`.
+
+Build tools are **never** added to `LICENSE`'s `## Third-Party Notices`
+section: that section is for libraries linked into the shipped `locksmith`
+binary, while build tools (linters, code generators) run only on the
+maintainer's machine. Tools fetched outside `Makefile` (npm packages,
+external MCP servers, agent skill packs) are out of scope for this skill -
+add them manually to the relevant section of `docs/development-tools.md`.
 
 If neither go.mod nor Makefile has relevant changes, report "No dependency
 changes found" and stop.
@@ -76,7 +85,8 @@ For each matching line:
 
 Label surviving tools as **(build tool)** in the verification table in Step 3.
 Build tools **skip the block-list check** in Step 4 - they are never distributed
-with the software so copyleft restrictions do not apply to users.
+with the software so copyleft restrictions do not apply to users. They are
+also written to `docs/development-tools.md` in Step 5, not to `LICENSE`.
 
 ### Step 3 - Look up licenses and build the verification table
 
@@ -152,7 +162,15 @@ If a license identifier does not appear in either the block-list above or
 the acceptable list, treat it as **unknown or ambiguous** and stop to ask
 the user to verify it manually.
 
-### Step 5 - Update `LICENSE`
+### Step 5 - Update `LICENSE` (go.mod deps) and `docs/development-tools.md` (build tools)
+
+Route each entry by kind:
+
+- **go.mod direct deps** → `LICENSE`'s `## Third-Party Notices` section.
+- **Makefile build tools** (collected in Step 2b) → `docs/development-tools.md`
+  under `## Build tools`. They are never written to `LICENSE`.
+
+#### LICENSE (go.mod deps only)
 
 If the `## Third-Party Notices` section does not yet exist, append the
 following block at the very end of `LICENSE` (including the leading `---`
@@ -169,9 +187,14 @@ The section header:
 This project uses the following third-party libraries. Each library
 retains its original copyright and is distributed under its respective
 license.
+
+Development-time tools (linters, code generators, AI agent helpers)
+are **not** listed here because they are not linked into or shipped
+with the `locksmith` binary. They are tracked separately in
+[`docs/development-tools.md`](docs/development-tools.md).
 ```
 
-For each dependency, add an entry sorted **alphabetically by module path**:
+For each go.mod dep, add an entry sorted **alphabetically by module path**:
 
 ```
 ### <module-path>
@@ -194,6 +217,28 @@ In incremental mode:
   it along with all its bullet lines, up to (but not including) the next `###`
   heading or end of file.
 
+#### docs/development-tools.md (Makefile build tools only)
+
+If `docs/development-tools.md` is missing entirely, stop and ask the user to
+restore it - this skill does not create the file from scratch (its `## AI
+agent tooling` section is curated manually).
+
+Otherwise, insert or remove entries under the `## Build tools` heading,
+sorted **alphabetically by module path**:
+
+```
+### <module-path>
+- Version: <version>
+- License: <SPDX identifier>
+- Role: <one-line description of which Make target uses it>
+- Source: https://<module-path>
+- License text: <URL to LICENSE file at tagged version>
+```
+
+For each **removed** build tool identified in Step 1, delete its
+`### <module-path>` entry and all its bullet lines, up to (but not
+including) the next `###` heading or the next `##` section.
+
 ### Step 6 - Update `CONTRIBUTING.md`
 
 Check whether `CONTRIBUTING.md` already contains a `## License Compliance`
@@ -230,17 +275,19 @@ adding it.
 
 ### Step 7 - Commit
 
-Stage and commit changed files:
+Stage and commit whichever of `LICENSE`, `docs/development-tools.md`, and
+`CONTRIBUTING.md` were actually modified in Steps 5-6. Skip files that were
+not touched.
 
 ```bash
-git add LICENSE CONTRIBUTING.md
+git add LICENSE docs/development-tools.md CONTRIBUTING.md
 git commit -S -m "chore: update third-party notices and license compliance docs"
 ```
 
-If `CONTRIBUTING.md` was not modified (section already existed), commit
-only `LICENSE`:
+If only one file changed, narrow the `git add` and the message accordingly,
+for example:
 
 ```bash
-git add LICENSE
-git commit -S -m "chore: update third-party notices"
+git add docs/development-tools.md
+git commit -S -m "chore: update development tools list"
 ```

.claude/skills/verification/SKILL.md

@@ -36,7 +36,7 @@ For every `FAIL` line in the output, apply the fix described below, then re-run
 | `make lint` | Run `make lint` to see current errors. Fix each one - do not add `//nolint:` without a comment explaining why. Re-run until clean. |
 | `test-race` | Find the failing test(s) in the output above the gate line. Fix the root cause. Do NOT suppress the race detector with `runtime.GOMAXPROCS(1)` or similar hacks. |
 | coverage below 90% | Open `.reports/coverage-<module>.html` for the listed package. Add tests for uncovered lines. Aim for lines that test real behaviour, not just coverage points. |
-| GPG signatures | Do NOT re-sign automatically. Report the unsigned commits to the user, show the exact commits, and ask for explicit confirmation before running the re-sign command from CLAUDE.md. |
+| GPG signatures | Do NOT re-sign automatically. Report the unsigned commits to the user, show the exact commits, and ask for explicit confirmation before running the re-sign command from CLAUDE.md. GitHub-generated "Merge pull request" commits are ignored by the gate (their `web-flow` key is often expired/untrusted locally and they can't be re-signed without diverging from the remote). |
 | CHANGES.md missing `## Development` | Add the section at the top of CHANGES.md with one bullet per user-visible change introduced on this branch. |
 | CHANGES.md has no bullet entries | Add bullets under `## Development` - one per logical change: what changed and why, in plain English. |
 | docs not updated | Identify which new or changed behaviour is undocumented. Add a section to `README.md` (user-facing changes) or the relevant file under `docs/` (architecture/config changes). |
@@ -73,3 +73,6 @@ git log --format="%G? %h %s" | head -20
 - Every line starts with `G` - report "All commits signed. Verification complete."
 - Any line starts with `N` or `B` - list those commits and ask the user for confirmation
   before re-signing. Use the re-sign command from CLAUDE.md.
+- Lines whose subject begins with `Merge pull request` may carry `E` (expired
+  GitHub `web-flow` key) - ignore them. Re-signing them would diverge from
+  the remote and serves no purpose.

.codegraph/.gitignore

@@ -0,0 +1,16 @@
+# CodeGraph data files
+# These are local to each machine and should not be committed
+
+# Database
+*.db
+*.db-wal
+*.db-shm
+
+# Cache
+cache/
+
+# Logs
+*.log
+
+# Hook markers
+.dirty

.codegraph/config.json

@@ -0,0 +1,143 @@
+{
+  "version": 1,
+  "include": [
+    "**/*.ts",
+    "**/*.tsx",
+    "**/*.js",
+    "**/*.jsx",
+    "**/*.py",
+    "**/*.go",
+    "**/*.rs",
+    "**/*.java",
+    "**/*.c",
+    "**/*.h",
+    "**/*.cpp",
+    "**/*.hpp",
+    "**/*.cc",
+    "**/*.cxx",
+    "**/*.cs",
+    "**/*.php",
+    "**/*.rb",
+    "**/*.swift",
+    "**/*.kt",
+    "**/*.kts",
+    "**/*.dart",
+    "**/*.svelte",
+    "**/*.vue",
+    "**/*.liquid",
+    "**/*.pas",
+    "**/*.dpr",
+    "**/*.dpk",
+    "**/*.lpr",
+    "**/*.dfm",
+    "**/*.fmx",
+    "**/*.scala",
+    "**/*.sc"
+  ],
+  "exclude": [
+    "**/.git/**",
+    "**/node_modules/**",
+    "**/vendor/**",
+    "**/Pods/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/out/**",
+    "**/bin/**",
+    "**/obj/**",
+    "**/target/**",
+    "**/*.min.js",
+    "**/*.bundle.js",
+    "**/.next/**",
+    "**/.nuxt/**",
+    "**/.svelte-kit/**",
+    "**/.output/**",
+    "**/.turbo/**",
+    "**/.cache/**",
+    "**/.parcel-cache/**",
+    "**/.vite/**",
+    "**/.astro/**",
+    "**/.docusaurus/**",
+    "**/.gatsby/**",
+    "**/.webpack/**",
+    "**/.nx/**",
+    "**/.yarn/cache/**",
+    "**/.pnpm-store/**",
+    "**/storybook-static/**",
+    "**/.expo/**",
+    "**/web-build/**",
+    "**/ios/Pods/**",
+    "**/ios/build/**",
+    "**/android/build/**",
+    "**/android/.gradle/**",
+    "**/__pycache__/**",
+    "**/.venv/**",
+    "**/venv/**",
+    "**/site-packages/**",
+    "**/dist-packages/**",
+    "**/.pytest_cache/**",
+    "**/.mypy_cache/**",
+    "**/.ruff_cache/**",
+    "**/.tox/**",
+    "**/.nox/**",
+    "**/*.egg-info/**",
+    "**/.eggs/**",
+    "**/go/pkg/mod/**",
+    "**/target/debug/**",
+    "**/target/release/**",
+    "**/.gradle/**",
+    "**/.m2/**",
+    "**/generated-sources/**",
+    "**/.kotlin/**",
+    "**/.dart_tool/**",
+    "**/.vs/**",
+    "**/.nuget/**",
+    "**/artifacts/**",
+    "**/publish/**",
+    "**/cmake-build-*/**",
+    "**/CMakeFiles/**",
+    "**/bazel-*/**",
+    "**/vcpkg_installed/**",
+    "**/.conan/**",
+    "**/Debug/**",
+    "**/Release/**",
+    "**/x64/**",
+    "**/.pio/**",
+    "**/release/**",
+    "**/*.app/**",
+    "**/*.asar",
+    "**/DerivedData/**",
+    "**/.build/**",
+    "**/.swiftpm/**",
+    "**/xcuserdata/**",
+    "**/Carthage/Build/**",
+    "**/SourcePackages/**",
+    "**/__history/**",
+    "**/__recovery/**",
+    "**/*.dcu",
+    "**/.composer/**",
+    "**/storage/framework/**",
+    "**/bootstrap/cache/**",
+    "**/.bundle/**",
+    "**/tmp/cache/**",
+    "**/public/assets/**",
+    "**/public/packs/**",
+    "**/.yardoc/**",
+    "**/coverage/**",
+    "**/htmlcov/**",
+    "**/.nyc_output/**",
+    "**/test-results/**",
+    "**/.coverage/**",
+    "**/.idea/**",
+    "**/logs/**",
+    "**/tmp/**",
+    "**/temp/**",
+    "**/_build/**",
+    "**/docs/_build/**",
+    "**/site/**"
+  ],
+  "languages": [],
+  "frameworks": [],
+  "maxFileSize": 1048576,
+  "extractDocstrings": true,
+  "trackCallSites": true
+}