diff --git a/agents/README.md b/agents/README.md index 0fd0c587..6d683e53 100644 --- a/agents/README.md +++ b/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 diff --git a/agents/skills/README.md b/agents/skills/README.md index 1ce458d7..ee9df5a5 100644 --- a/agents/skills/README.md +++ b/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. diff --git a/agents/skills/find-docs/SKILL.md b/agents/skills/find-docs/SKILL.md new file mode 100644 index 00000000..77edbe8b --- /dev/null +++ b/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 "" +ctx7 docs "" +``` + +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. diff --git a/flake.lock b/flake.lock index eeec27f4..c85af856 100644 --- a/flake.lock +++ b/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", diff --git a/flake.nix b/flake.nix index b0ffa8d8..d904d761 100644 --- a/flake.nix +++ b/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 ######################################### diff --git a/home/base/tui/agents/packages.nix b/home/base/tui/agents/packages.nix index 5d42982a..f52bbf6c 100644 --- a/home/base/tui/agents/packages.nix +++ b/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 ]; diff --git a/home/base/tui/agents/skills.nix b/home/base/tui/agents/skills.nix index c4558cee..22cd9050 100644 --- a/home/base/tui/agents/skills.nix +++ b/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"; }; diff --git a/hosts/idols-ai/preservation.nix b/hosts/idols-ai/preservation.nix index 990fe2d6..c23674de 100644 --- a/hosts/idols-ai/preservation.nix +++ b/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"