@cleocode/skills 2026.5.84 → 2026.5.87

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/skills",
-  "version": "2026.5.84",
+  "version": "2026.5.87",
   "description": "CLEO skill definitions - bundled with CLEO monorepo",
   "main": "index.js",
   "types": "index.d.ts",

package/skills/ct-adr-recorder/SKILL.md

@@ -93,6 +93,80 @@ Flags specs T4776, T4781; decomposition epic T4772; live impl T4790.
 
 A longer, realistic example with all six sections filled out lives in [references/examples.md](references/examples.md).
 
+## Through SDK (preferred)
+
+ADRs are first-class docs SSoT records — drafted via
+`cleo docs add --type adr`, attached to the originating consensus task,
+and numbered through the slug. This is the canonical write path; the
+legacy "write to `docs/adr/ADR-NNNN.md` and commit" pattern is
+deprecated below.
+
+### Draft the ADR attached to its consensus task
+
+```bash
+cleo docs add T4798 docs/adr/ADR-0042.md \
+  --type adr \
+  --slug adr-0042-drizzle-v1-beta \
+  --desc "ADR-0042: Adopt Drizzle ORM v1 beta for all SQLite access (status: proposed)" \
+  --labels "adr,proposed"
+```
+
+- `--type adr` is the canonical taxonomy value. The closed set is
+  `spec | adr | research | handoff | note | llm-readme`.
+- `--slug` MUST follow `adr-<NNNN>-<short-topic>`. The numeric segment
+  is the canonical ADR id; the topic segment makes the slug human
+  readable. Collisions return `E_SLUG_TAKEN` with 3 alternatives.
+- The owner ID is the consensus task whose verdict drives the ADR
+  (`T4798` above). This is how downstream supersession cascades find
+  the chain — never attach an ADR to an arbitrary task.
+
+### Persist the decision row alongside the doc blob
+
+`cleo docs add --type adr` writes the document and the docs-side
+manifest entry, but per Immutable Constraint ADR-006 the canonical
+`decisions` table MUST also be populated via Drizzle. The two writes
+are paired: doc blob first (SSoT-of-the-prose), then the relational
+row (SSoT-of-the-decision). Skipping either is a validation failure.
+
+### Publish the ADR to a git-tracked path
+
+```bash
+cleo docs publish --for T4798 --to docs/adr/ADR-0042.md
+```
+
+Atomic tmp-then-rename. The published file lands in the next commit;
+the SSoT blob remains the canonical version-history root.
+
+### Fetch the ADR back by slug (for HITL review + downstream supersession)
+
+```bash
+cleo docs fetch adr-0042-drizzle-v1-beta     # latest version
+cleo docs versions --for T4798               # every SHA version
+```
+
+The HITL reviewer reads the proposed ADR via `cleo docs fetch` rather
+than the on-disk file so the review anchors on the canonical SSoT
+blob — drift between the published file and the blob is its own
+review finding.
+
+### List ADRs by type or status
+
+```bash
+cleo docs list --type adr --project          # every ADR in the project
+cleo docs list --task T4798 --type adr       # ADRs attached to T4798
+```
+
+## Deprecated: Direct filesystem write
+
+The legacy "write to `docs/adr/ADR-NNNN.md` and commit" pattern is
+deprecated. The on-disk file drifts from the SSoT, the ADR has no
+slug for the supersession cascade to retrieve it by, and the
+consensus-task↔ADR linkage exists only as a frontmatter field
+(`consensus_manifest_id`) rather than a relational owner edge.
+Migrate to `cleo docs add --type adr --slug adr-<NNNN>-<topic>` for
+every new ADR — and use `cleo docs sync --from docs/adr/ADR-NNNN.md
+--for <taskId>` to back-fill existing on-disk ADRs into the SSoT.
+
 ## HITL Approval Gate
 
 When a draft reaches `proposed`, the skill MUST:

package/skills/ct-adr-recorder/__tests__/skill-adr-recorder.test.ts

@@ -0,0 +1,65 @@
+/**
+ * Regression test for ct-adr-recorder/SKILL.md (T9643 / Epic T9629 / Saga T9625).
+ *
+ * Pins the SDK-first ADR contract: ADRs MUST be drafted via
+ * `cleo docs add --type adr --slug adr-<NNNN>-<topic>` so the document
+ * is owned by the originating consensus task and addressable by slug
+ * for the HITL approval gate and the downstream supersession cascade.
+ * The relational `decisions` row (ADR-006) is paired with the doc blob
+ * but persisted separately via Drizzle.
+ *
+ * @task T9643
+ * @epic T9629
+ * @saga T9625
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const thisFile = fileURLToPath(import.meta.url);
+const skillRoot = resolve(dirname(thisFile), '..');
+const skillPath = join(skillRoot, 'SKILL.md');
+const skillContent = readFileSync(skillPath, 'utf-8');
+
+describe('ct-adr-recorder SKILL.md — SDK-first contract (T9643)', () => {
+  it('teaches `cleo docs add --type adr` as the canonical write path', () => {
+    expect(skillContent).toMatch(/cleo docs add[\s\S]+--type adr/);
+  });
+
+  it('shows the `adr-<NNNN>-<topic>` slug convention', () => {
+    expect(skillContent).toMatch(/adr-<NNNN>-<.*?topic/i);
+  });
+
+  it('attaches the ADR to the consensus task via the owner ID', () => {
+    // The example MUST use a T### owner ID to demonstrate consensus-task linkage
+    expect(skillContent).toMatch(/cleo docs add\s+T\d+\s/);
+  });
+
+  it('keeps the relational `decisions` write paired with the doc blob (ADR-006)', () => {
+    expect(skillContent).toMatch(/decisions[\s\S]+Drizzle/i);
+    expect(skillContent).toContain('ADR-006');
+  });
+
+  it('shows `cleo docs publish --for ... --to docs/adr/...` for git publication', () => {
+    expect(skillContent).toMatch(/cleo docs publish[\s\S]+--for[\s\S]+--to[\s\S]+docs\/adr/);
+  });
+
+  it('shows `cleo docs fetch <slug>` for HITL review + supersession', () => {
+    expect(skillContent).toContain('cleo docs fetch');
+  });
+
+  it('shows `cleo docs list --type adr` for ADR discovery', () => {
+    expect(skillContent).toMatch(/cleo docs list[\s\S]+--type adr/);
+  });
+
+  it('marks the old direct-filesystem write as deprecated with a migration note', () => {
+    expect(skillContent).toContain('Deprecated: Direct filesystem write');
+    expect(skillContent).toMatch(/cleo docs (add|sync)/);
+  });
+
+  it('references E_SLUG_TAKEN for collision handling', () => {
+    expect(skillContent).toContain('E_SLUG_TAKEN');
+  });
+});

package/skills/ct-docs-lookup/SKILL.md

@@ -63,4 +63,119 @@ Incorporate the fetched documentation into your response:
 
 - **Be specific**: Pass the user's full question as the query for better results
 - **Version awareness**: When users mention versions ("Next.js 15", "React 19"), use version-specific library IDs if available from the resolution step
-- **Prefer official sources**: When multiple matches exist, prefer official/primary packages over community forks
+- **Prefer official sources**: When multiple matches exist, prefer official/primary packages over community forks
+
+## Why Context7 (not training data)
+
+The user's global rule is explicit: prefer Context7 over training data for any
+library, framework, SDK, API, CLI tool, or cloud service — even well-known ones
+like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This
+includes API syntax, configuration, version migration, library-specific
+debugging, setup instructions, and CLI tool usage. Use even when you think
+you know the answer; training data may not reflect recent changes.
+
+## Three-Command Budget
+
+The user rules cap a docs lookup at three CLI invocations per question. The
+budget fits the standard workflow:
+
+1. `npx ctx7@latest library "<name>" "<question>"` — one call to resolve.
+2. `npx ctx7@latest docs <id> "<question>"` — one call to fetch.
+3. (Optional) `npx ctx7@latest docs <id> "<question>" --research` — one
+   retry with sandboxed agents pulling source + web search.
+
+Going over budget is a signal: the library name is wrong, the question
+is too broad, or Context7 doesn't cover this library. In any of those
+cases, refine before retrying — don't burn more calls.
+
+## When NOT to Use This Skill
+
+The user rules explicitly exclude these from docs-lookup:
+
+- **Refactoring** — re-shaping existing code; no library lookup needed.
+- **Scripts written from scratch** — general programming, not library API.
+- **Debugging business logic** — use codebase tools (Grep, GitNexus), not
+  external docs.
+- **Code review** — quality assessment, not library reference.
+- **General programming concepts** — pure CS questions; training data is fine.
+
+Use docs-lookup ONLY for: API syntax, configuration questions, version
+migration issues, library-specific debugging, setup instructions, and CLI
+tool usage.
+
+## Authentication and Quotas
+
+The `ctx7` CLI runs anonymously with a limited free quota. When quota
+exhausts:
+
+```text
+Error: Quota exceeded.
+  Run `npx ctx7@latest login` for higher limits.
+  Or set CONTEXT7_API_KEY env var with your key.
+```
+
+Surface the error to the user (or include in `needs_followup`). NEVER
+silently fall back to training data — that violates the skill's contract.
+
+## Sensitive Data
+
+Queries to Context7 are logged on the Context7 side. Never include:
+
+- API keys, tokens, passwords
+- Internal hostnames or URLs
+- Customer-identifying data
+- Source code excerpts from private repos
+
+Use generic phrasing. If the actual API call needs a specific value,
+describe it abstractly ("how do I authenticate with an API key" instead
+of "use API key sk_live_abc123 to...").
+
+## Multi-Library Composition
+
+A single question may touch multiple libraries — common in modern stacks
+(SvelteKit + Better-Auth + Drizzle, Next.js + Prisma + Tailwind, etc.).
+Resolve each library independently with the right version pin, then
+synthesize.
+
+The three-command budget applies per-library; a question spanning
+three libraries gets nine commands. Stay focused — fetch the specific
+integration point each time, not the entire library surface.
+
+## Citing Versions in Answers
+
+Every code example produced from a version-pinned fetch MUST cite the
+version. The reader copies the code and runs it; when their version
+differs, the citation is the first thing they check.
+
+```markdown
+Use `defineRelations` (Drizzle ORM v1.0.0-beta and later):
+
+```typescript
+import { defineRelations } from "drizzle-orm";
+// ...
+```
+```
+
+Without the version note, the reader who is on Drizzle 0.x will be
+confused when the import fails.
+
+## Common Failure Modes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| "Library not found" | Wrong name format | Use official punctuation: "Next.js" not "nextjs" |
+| Stale answer | No version pin | Detect installed version from lockfile, pin |
+| Generic answer when specifics needed | Vague query | Pass full question text, not single words |
+| Quota exceeded | Anonymous over-use | `ctx7 login` or set `CONTEXT7_API_KEY` |
+| Hallucinated API | Skipped Context7 | Always run Step 1+2 before answering library questions |
+| Wrong fork picked | Took top result blindly | Read descriptions; prefer official org |
+
+---
+
+## See references/
+
+Progressive disclosure — load on demand only:
+
+- `references/ctx7-workflow.md` — two-step loop, query formatting, research mode, budget
+- `references/library-id-resolution.md` — signals for picking the right ID; disambiguation procedure
+- `references/version-specific-docs.md` — version pinning, migrations, deprecations, drift detection

package/skills/ct-docs-lookup/references/ctx7-workflow.md

@@ -0,0 +1,198 @@
+# ctx7 Workflow
+
+`ct-docs-lookup` is the CLEO-side wrapper around the `ctx7` CLI. The
+underlying contract is set in the user's global rules
+(`~/.claude/rules/context7.md`) and the project's `MCP_Context7.md`.
+This reference codifies the workflow with concrete examples and
+recovery procedures.
+
+## Why Context7
+
+The skill's purpose statement is direct: when the user asks about a
+library, framework, or needs code examples, fetch current documentation
+instead of relying on training data. Training data is stale — the
+project's user rules say so explicitly.
+
+This applies even when you think you know the answer. API surfaces of
+React, Next.js, Prisma, Tailwind, Drizzle, Svelte, Supabase, and friends
+move faster than any model's cutoff. Verify against current docs.
+
+## The Two-Step Loop
+
+The ctx7 CLI is shipped as `npx ctx7@latest`. The workflow is two calls.
+
+```bash
+# Step 1 — resolve the official library ID
+npx ctx7@latest library "<library-name>" "<user-question>"
+
+# Step 2 — fetch docs for the resolved ID
+npx ctx7@latest docs <libraryId> "<user-question>"
+```
+
+The output of Step 1 is a list of candidate library IDs in the form
+`/org/project`. Pick the best match (see `library-id-resolution.md` for
+the heuristics) and pass it to Step 2.
+
+## Step 1: Library Resolution
+
+Use the official library name with proper punctuation:
+
+| ❌ Wrong | ✅ Correct |
+|----------|------------|
+| `"nextjs"` | `"Next.js"` |
+| `"customerio"` | `"Customer.io"` |
+| `"threejs"` | `"Three.js"` |
+| `"reactdom"` | `"React DOM"` |
+| `"vuejs"` | `"Vue.js"` |
+| `"tailwindcss"` | `"Tailwind CSS"` |
+
+The library name matches what the project documents itself as. When
+unsure, search the project's GitHub README for the official name.
+
+Pass the user's full question as the second arg — specific queries
+return better matches than single words.
+
+```bash
+# GOOD
+npx ctx7@latest library "Drizzle ORM" "how do I define relations in v1"
+
+# BAD — too generic, ranks poorly
+npx ctx7@latest library "drizzle" "relations"
+```
+
+## Step 1 Output Interpretation
+
+The CLI returns candidates with several signals — pick by:
+
+1. **Exact name match.** "Next.js" should resolve to `/vercel/next.js`
+   over `/some-fork/next.js-clone`.
+2. **Source reputation.** Look for High or Medium source labels.
+3. **Code snippet count.** More snippets = better-indexed library.
+4. **Benchmark score.** Higher is better; reflects retrieval quality.
+
+If the top candidate doesn't match exactly what the user asked for —
+e.g., they said "Next.js 15" and the top candidate is generic — try
+again with refined terms or version-specific names.
+
+## Step 2: Docs Fetch
+
+Once you have the library ID:
+
+```bash
+npx ctx7@latest docs /vercel/next.js "how do I configure middleware to inject auth headers"
+```
+
+The output is documentation excerpts with citations. Use these directly
+in your answer — they are current, sourced, and citable.
+
+## Version-Specific Docs
+
+When the user names a version, use the version-specific form:
+
+```bash
+# General
+npx ctx7@latest docs /vercel/next.js "..."
+
+# Pinned to v14.3.0
+npx ctx7@latest docs /vercel/next.js/v14.3.0 "..."
+
+# Pinned to v15 (latest 15.x)
+npx ctx7@latest docs /vercel/next.js/v15 "..."
+```
+
+The Step 1 output enumerates available versions. Pick the version
+matching the project's actual installed version (check
+`package.json` / `Cargo.toml` / `requirements.txt`).
+
+## Research Mode (Fallback)
+
+If the default fetch doesn't satisfy the question, retry with
+`--research`:
+
+```bash
+npx ctx7@latest docs /vercel/next.js "..." --research
+```
+
+This launches sandboxed agents that git-pull the actual source repos
+plus live web search, then synthesizes a fresh answer. More costly
+(longer, more tokens), so use only when:
+
+- Default fetch returned a generic answer when specifics were needed.
+- The question references a recent change that may not be indexed yet.
+- The user explicitly asked for research-grade depth.
+
+## Auth and Quotas
+
+The `ctx7` CLI runs anonymously by default with limited quota. When
+quota is exhausted:
+
+```bash
+# Error message will be something like:
+# Error: Quota exceeded. Run `npx ctx7@latest login` or set CONTEXT7_API_KEY
+```
+
+Instruct the user (or surface in `needs_followup`) to either:
+- Run `npx ctx7@latest login` (one-time browser auth)
+- Set `CONTEXT7_API_KEY` env var with their key
+
+Do NOT silently fall back to training data — that violates the skill's
+contract. The whole point is current docs, not stale recall.
+
+## Budget Discipline
+
+The user rules cap the workflow at "no more than 3 commands per
+question". For most lookups this is plenty:
+- 1 call: library resolution
+- 1 call: docs fetch
+- 1 call (optional): retry with `--research` if needed
+
+Going over budget signals one of:
+- Wrong library name (refine and retry)
+- Question too broad (narrow the question first)
+- Genuine library mismatch (Context7 doesn't cover this library — use
+  web search via WebSearch/WebFetch as alternative)
+
+## Sensitive Data
+
+Never include API keys, passwords, credentials, or internal URLs in
+queries. The query is logged on the Context7 side.
+
+```bash
+# WRONG
+npx ctx7@latest docs /supabase/supabase "use API key sk_live_abc123 to..."
+
+# RIGHT
+npx ctx7@latest docs /supabase/supabase "how do I authenticate the client with an API key"
+```
+
+## End-to-End Example
+
+```bash
+# User asked: "How do I do streaming server actions in Next.js 15?"
+
+# Step 1 — resolve
+$ npx ctx7@latest library "Next.js" "How do I do streaming server actions in Next.js 15?"
+> /vercel/next.js/v15 (benchmark 0.87, snippets 1240, source: High)
+> /vercel/next.js     (benchmark 0.85, snippets 5230, source: High)
+> ...
+
+# Step 2 — fetch (use version-pinned ID)
+$ npx ctx7@latest docs /vercel/next.js/v15 "How do I do streaming server actions in Next.js 15?"
+> [docs excerpt with streaming example, citation]
+
+# Compose answer using the fetched docs, citing version
+```
+
+## When NOT to Use This Skill
+
+See `library-id-resolution.md` for the boundary with debugging tasks,
+and `version-specific-docs.md` for when the answer doesn't depend on
+a specific library. Quick summary:
+
+- ❌ Don't use for refactoring (no library lookup needed)
+- ❌ Don't use for scripts written from scratch
+- ❌ Don't use for debugging business logic (use codebase tools)
+- ❌ Don't use for code review
+- ❌ Don't use for general programming concepts
+- ✅ Use for API syntax, configuration, version migration, library-specific
+  debugging, setup instructions, CLI tool usage

package/skills/ct-docs-lookup/references/library-id-resolution.md

@@ -0,0 +1,217 @@
+# Library ID Resolution
+
+The Context7 library catalog uses `/org/project` IDs. Picking the right
+ID is the difference between fetching authoritative docs and fetching
+a community fork's stale README. This reference codifies the
+disambiguation heuristics with concrete examples.
+
+## ID Anatomy
+
+```
+/vercel/next.js
+└org─┘ └proj─┘
+
+/vercel/next.js/v14.3.0
+└org─┘ └proj─┘ └version┘
+```
+
+- The `org` is typically the GitHub org or the company name.
+- The `project` is the official package name.
+- The optional `version` is a tag or release branch.
+
+## Resolution Output Format
+
+A typical Step 1 (`ctx7 library`) output:
+
+```text
+Top matches for "Next.js" against query "configure middleware":
+
+1. /vercel/next.js
+   - Source: High
+   - Description: The React Framework for the Web.
+   - Code snippets: 5230
+   - Benchmark: 0.85
+
+2. /vercel/next.js/v15
+   - Source: High
+   - Description: Next.js v15 release line.
+   - Code snippets: 1240
+   - Benchmark: 0.87
+
+3. /community/next-with-foo
+   - Source: Medium
+   - Description: Next.js + Foo starter template.
+   - Code snippets: 87
+   - Benchmark: 0.42
+
+4. /old-org/nextjs-legacy
+   - Source: Low
+   - Description: Pre-app-router Next.js patterns.
+   - Code snippets: 412
+   - Benchmark: 0.39
+```
+
+Five signals to weigh.
+
+## Signal 1: Exact Name Match
+
+The user said "Next.js". Candidates 1 and 2 are exact matches; 3 is
+"next-with-foo" (a derivative); 4 is "nextjs-legacy" (suffixed).
+
+Prefer the canonical name. The derivative or suffixed projects are
+appropriate ONLY when the user explicitly named them.
+
+## Signal 2: Source Reputation
+
+`High` > `Medium` > `Low`. Source reputation reflects how authoritative
+Context7 considers the project. Official org-owned repos are High.
+Community forks are typically Medium. Abandoned or low-quality projects
+are Low.
+
+When multiple High candidates exist, look further. When the only
+High candidate is the obvious one, pick it.
+
+## Signal 3: Code Snippet Count
+
+More snippets = better-indexed library = higher chance of finding the
+exact API the user asked about. The unversioned ID usually has higher
+snippet counts than version-pinned IDs because it aggregates across
+versions.
+
+For general questions, prefer unversioned IDs. For version-specific
+questions, accept the lower snippet count of the pinned ID.
+
+## Signal 4: Benchmark Score
+
+The benchmark is a retrieval-quality measure produced by Context7 —
+higher means the candidate library has good documentation that
+indexes well. Use as a tiebreaker only.
+
+In the example above, candidate 2 has a slightly higher benchmark
+(0.87) than candidate 1 (0.85) because v15-specific queries score
+better against the pinned slice. For a v15-specific question, prefer
+candidate 2.
+
+## Signal 5: Query Alignment
+
+The user's query in Step 1 affects ranking. If the query mentioned
+"middleware", candidates whose docs cover middleware will rank higher.
+This is why passing the FULL user question (not a single word) yields
+better resolution.
+
+## Common Pitfalls
+
+### Pitfall: Picking the version-pinned ID for a general question
+
+The user asked "What does Next.js do?" — a general question.
+
+- ❌ Pick `/vercel/next.js/v15` — too narrow; misses cross-version context.
+- ✅ Pick `/vercel/next.js` — covers the whole project.
+
+### Pitfall: Picking the unversioned ID for a version-specific question
+
+The user asked "How do I migrate from Next.js 14 to 15?"
+
+- ❌ Pick `/vercel/next.js` — might return mixed-version docs.
+- ✅ Pick `/vercel/next.js/v15` — gets the migration guide for 15.
+- ✅ Better: pick `/vercel/next.js/v15` for "to" and `/vercel/next.js/v14`
+  for "from", and run two fetches.
+
+### Pitfall: Picking the community fork when the user wants the official
+
+The user asked "How do I use Tailwind utilities?"
+
+- ❌ Pick `/some-community/tailwind-with-extras` — not what they meant.
+- ✅ Pick `/tailwindlabs/tailwindcss` — the official.
+
+Community forks rank LOW on the "what user meant" axis even when they
+rank high on other signals. Default to the official.
+
+### Pitfall: Picking the highest snippet count regardless of relevance
+
+The user asked about Vue 3 composition API.
+
+- ❌ Pick `/vuejs/vue` (high snippet count, but it's the Vue 2 line).
+- ✅ Pick `/vuejs/core` or `/vuejs/vue-next` (Vue 3).
+
+Always read the description, not just the count. Old projects accumulate
+snippets because they've been around longer — they may no longer be
+current.
+
+## Disambiguation Procedure
+
+When two candidates look equally good:
+
+1. **Read the descriptions.** They usually disambiguate.
+2. **Check the org.** Official org = the project's home; community
+   org = derivative.
+3. **Check the project's GitHub URL** if Context7 includes it. The URL
+   matches what the project's README cites.
+4. **Try both.** Compare the outputs of Step 2 for each candidate. The
+   one that better answers the question is the right one.
+
+## When Resolution Fails
+
+Sometimes Step 1 returns no good match. The library may not be in
+Context7's catalog, or the name was wrong. Recovery:
+
+```bash
+# Retry with the formal name from the project's GitHub
+npx ctx7@latest library "TanStack Query" "..."   # not "react-query"
+
+# Retry with the alternative spelling
+npx ctx7@latest library "GitHub Actions" "..."   # not "gh-actions"
+
+# Retry with a more specific query
+npx ctx7@latest library "Next.js" "App Router middleware in v15"
+
+# If all retries fail, fall back to WebSearch / WebFetch
+# (but tell the user the library isn't in Context7's catalog)
+```
+
+## Version Resolution Specifics
+
+When a project has many versions, Step 1's output lists them. Pick by:
+
+1. **Match the project's installed version.** Check `package.json`,
+   `Cargo.toml`, `requirements.txt`, etc.
+2. **If the user named a version, use that.**
+3. **If neither, use the latest stable (highest version number that
+   isn't pre-release).**
+
+```bash
+# Project installed Next.js 14.3.x
+$ jq '.dependencies.next' package.json
+"14.3.0"
+
+# Use the pinned version
+npx ctx7@latest docs /vercel/next.js/v14.3.0 "..."
+```
+
+This catches the case where the user asks about behavior that differs
+between versions; using the wrong version pin gives a confidently
+wrong answer.
+
+## Caching
+
+Library IDs rarely change. If you resolved `/vercel/next.js/v15` for
+one query, you can re-use it for the next query about the same library
+without running Step 1 again. Just remember to refresh the resolution
+when:
+
+- Asking about a different major version.
+- The project's installed version changed.
+- The previous fetch didn't satisfy the question (maybe the wrong ID
+  was picked).
+
+## When NOT to Use Library Lookup
+
+The user rules are explicit: not for refactoring, scripts-from-scratch,
+business-logic debugging, code review, or general programming concepts.
+
+If the question is "how do I structure my repository?" — that is a
+general programming question. Use general knowledge plus codebase
+inspection, not Context7.
+
+If the question is "how does Next.js's app router handle parallel
+routes?" — that is a library API question. Use Context7.