feat(agents): rewrite find-docs onto the nixpkgs ctx7 CLI

Assisted-by: DeepSeek Harness (claude-opus-5-5, deepseek-flash, qwen3.8-flash-next iq3)

agents/README.md

@@ -89,13 +89,14 @@ secret handling.
 Remaining work on the agent context, ordered by expected payoff. The goal is fewer tokens per
 session and closer adherence to these rules. Done so far: the rules source rename, the move of
 global skills to flake inputs (dropping superpowers, `find-skills`, and `caveman`), the i-have-adhd
-always-on block, and the table-padding and duplication cleanup in the repo skills. Historical
-[behavioral runs](evals/global-rules.md) cover tool-execution compression, whole-file compression,
-and boundaries for readiness waits, process inspection, and shell command sequencing on
-`gpt-6-luna`, the local model, and `gpt-6.1-sol`. A later full-table paper pass ran on
-`DeepSeek-V41-Flash`, with focused verification on that model and `gpt-6-luna`. The added boundaries
-cost more than the compression saved; revision-specific sizes, results, and coverage limits are
-recorded in [#428](https://github.com/ryan4yin/nix-config/pull/428).
+always-on block, `find-docs` rewritten onto the nixpkgs `ctx7` CLI, the table-padding and
+duplication cleanup in the repo skills. Historical [behavioral runs](evals/global-rules.md) cover
+tool-execution compression, whole-file compression, and boundaries for readiness waits, process
+inspection, and shell command sequencing on `gpt-6-luna`, the local model, and `gpt-6.1-sol`. A
+later full-table paper pass ran on `DeepSeek-V41-Flash`, with focused verification on that model and
+`gpt-6-luna`. The added boundaries cost more than the compression saved; revision-specific sizes,
+results, and coverage limits are recorded in
+[#428](https://github.com/ryan4yin/nix-config/pull/428).
 
 - **Fold `mattpocock/skills` `pr` into `git-delivery`**: before/after evidence, one-way or two-way
   door, and blast radius for PR bodies.
@@ -111,8 +112,6 @@ recorded in [#428](https://github.com/ryan4yin/nix-config/pull/428).
 - **Adapt `domain-modeling` in the fork** to record decisions in the repository's existing documents
   (here `AGENTS.md`, `WORKAROUNDS.md`, `SECURITY.md`, READMEs) and create `GLOSSARY.md` or ADRs only
   where none exist.
-- **Trim `find-docs`**: its description (~930 characters) is the longest in the catalog and says
-  "always use", and its body runs `npx ctx7@latest` unpinned and suggests `npm install -g`.
 - **Borrow small gstack ideas into the rules**: completion statuses (done, done with concerns,
   blocked, needs context); never call a failure pre-existing without running the same check on the
   base branch; a subagent with no one to ask takes the recommended option but never a destructive or

agents/skills/README.md

@@ -26,7 +26,6 @@ Repository-scoped skills do not belong here; they live in the owning repository'
 | `writing-for-agents`       | `mattpocock-skills` | same                                                                                      |
 | `i-have-adhd`              | `i-have-adhd`       | [ryan4yin/i-have-adhd](https://github.com/ryan4yin/i-have-adhd) `main` (fork)             |
 | `humanizer`                | `humanizer`         | [blader/humanizer](https://github.com/blader/humanizer) `v3.1.0`                          |
-| `find-docs`                | `context7`          | [upstash/context7](https://github.com/upstash/context7) commit `522c4db4`                 |
 | `ponytail-review`          | `ponytail`          | [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) `v5.1.0`            |
 
 Dependencies travel together: `grill-with-docs` and `wayfinder` call `grilling` and
@@ -51,5 +50,12 @@ the pinned tag/commit in `flake.nix`) and check `git diff flake.lock`.
 replies, and cleanup after merge, all following the target repository's conventions. Edit it in
 place; the change reaches the next agent session without a switch.
 
+`find-docs` is a rewrite of `upstash/context7` `skills/find-docs` (MIT), vendored because the
+upstream body drives the CLI with `npx ctx7@latest` and suggests a global `npm install`, both of
+which the global rules forbid. This one calls the `ctx7` that Home Manager installs from nixpkgs
+(see [`packages.nix`](../../home/base/tui/agents/packages.nix)), and its flags match the packaged
+version: 0.5.12 has no `--language`, which upstream documents. Re-check `ctx7 --help` when nixpkgs
+bumps it.
+
 A third-party skill starts here only when it is being rewritten. Until then, pin it as a flake input
 so the license and provenance stay with the upstream repository and the diff stays reviewable.

agents/skills/find-docs/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: find-docs
+description: >-
+  Look up current documentation and code examples for a library, framework, SDK, CLI tool, or cloud
+  service with the Context7 CLI. Use whenever a question names a specific technology — API syntax,
+  configuration options, version migrations, library-specific debugging, setup, CLI usage —
+  including well-known ones: training data goes stale on these details.
+---
+
+# Documentation lookup
+
+`ctx7` is on PATH (Home Manager, from nixpkgs). Run it as it is; the package is Nix-managed, so skip
+the `setup` and `upgrade` commands its `--help` advertises.
+
+Two steps: resolve the library ID, then query with it.
+
+```bash
+ctx7 library <name> "<query>"
+ctx7 docs <libraryId> "<query>"
+```
+
+Skip step 1 only when the user supplies an ID as `/org/project` or `/org/project/version`. Add
+`--json` to either step when you will parse the output rather than read it.
+
+A query leaves the machine: keep internal identifiers, private-repository paths, and credentials out
+of it.
+
+## Step 1: resolve the ID
+
+Pass a `query` every time — it ranks the matches, so it also separates libraries that share a name.
+Use the official spelling ("Next.js", not "nextjs"); when results look wrong, retry the name before
+rewriting the query.
+
+```bash
+ctx7 library "Next.js" "how to set up app router middleware"
+```
+
+Each match carries `id`, `title`, `description`, `totalSnippets`, `trustScore`, `benchmarkScore`,
+and `versions`. Prefer an exact name match with a high `trustScore` and more `totalSnippets`. When
+the user names a version, take the closest entry in `versions` and use `/org/project/version` as the
+ID.
+
+Stop after three attempts and use the best match you have. When none is usable, say so and suggest a
+sharper name instead of guessing.
+
+## Step 2: query the docs
+
+One topic per `docs` call: split unrelated concepts into separate calls, unless the question is
+about how they interact. Describe what to look up in the documentation rather than the task to
+complete — `"React useEffect cleanup function with async operations"` ranks, `"hooks"` returns
+generic results.
+
+```bash
+ctx7 docs /vercel/next.js "how to add middleware"
+```
+
+The output is markdown: titled code snippets and prose snippets, each with the source URL it came
+from. Cite that URL when the answer rests on it.
+
+## When it fails
+
+Lookups work without a login, at a lower rate limit. On a quota error, tell the user to run
+`ctx7 login` themselves; never ask them to paste a token into chat. If they do not authenticate,
+answer from training knowledge and say it may be outdated — do not fall back silently.