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.

flake.lock

@@ -109,23 +109,6 @@
         "type": "github"
       }
     },
-    "context7": {
-      "flake": false,
-      "locked": {
-        "lastModified": 1791560179,
-        "narHash": "sha256-cChMAOd8cYTcNZt0AaUcJ4G+tT0w/64PRsbKJ3ADeY8=",
-        "owner": "upstash",
-        "repo": "context7",
-        "rev": "522c4db4fa2e1e31f1b320f09fa8c8fab376987a",
-        "type": "github"
-      },
-      "original": {
-        "owner": "upstash",
-        "repo": "context7",
-        "rev": "522c4db4fa2e1e31f1b320f09fa8c8fab376987a",
-        "type": "github"
-      }
-    },
     "crane": {
       "locked": {
         "lastModified": 1781825982,
@@ -1143,7 +1126,6 @@
         "agenix": "agenix",
         "catppuccin": "catppuccin",
         "colmena": "colmena",
-        "context7": "context7",
         "disko": "disko",
         "fcitx5-vinput": "fcitx5-vinput",
         "haumea": "haumea",

flake.nix

@@ -193,11 +193,6 @@
       url = "github:DietrichGebert/ponytail/v5.1.0";
       flake = false;
     };
-    # context7's release tags predate skills/find-docs, so pin a commit.
-    context7 = {
-      url = "github:upstash/context7/522c4db4fa2e1e31f1b320f09fa8c8fab376987a";
-      flake = false;
-    };
 
     ########################  My own repositories  #########################################
 

home/base/tui/agents/packages.nix

@@ -17,6 +17,10 @@ in
     # (node-addon-require-builtin probe), this one shims it.
     nur-ryan4yin.packages.${pkgs.stdenv.hostPlatform.system}.dsh
 
+    # Docs lookup CLI behind the find-docs skill (agents/skills/find-docs). The skill's flags are
+    # written against this package, not against upstream's npx instructions.
+    pkgs.ctx7
+
     # MCP servers, configured project-scoped in opencode.jsonc / .codex/config.toml
     pkgs.mcp-grafana
   ];

home/base/tui/agents/skills.nix

@@ -5,7 +5,6 @@
   i-have-adhd,
   humanizer,
   ponytail,
-  context7,
   ...
 }:
 let
@@ -39,7 +38,6 @@ let
       writing-for-agents = "${mp}/productivity/writing-for-agents";
 
       i-have-adhd = "${i-have-adhd}/skills/i-have-adhd";
-      find-docs = "${context7}/skills/find-docs";
       ponytail-review = "${ponytail}/skills/ponytail-review";
     };
 

hosts/idols-ai/preservation.nix

@@ -182,7 +182,16 @@ in
         ".local/share/opencode"
         ".local/state/opencode"
 
-        ".context7" # up-to-date docs and code examples for for LLMs & agents
+        # ctx7 docs lookup login
+        {
+          directory = ".config/context7";
+          mode = "0700";
+        }
+        # Legacy ctx7 login, still read: ctx7 cannot rename it across the two bind mounts.
+        {
+          directory = ".context7";
+          mode = "0700";
+        }
 
         # nvim
         ".local/share/nvim"