Library Wiki

library-wiki

The wiki at docs/graph/libraries/ is this project's source of truth for every external dependency. Each library used directly by the project has a page; each page is local, version-pinned, sourced, and compounding.

This skill is the discipline of building and maintaining those pages. It is invoked from the ingest-library protocol and any time an agent uses a library and realizes the page is missing or stale.

When to apply this skill

• A new dependency is being added → create a page.
• A pinned version is bumped → refresh the page.
• A new idiom for using a library was just adopted → record it.
• An agent ran into a behavior the page doesn't cover → add a pitfall entry, dated.
• A security advisory affects a wikified library → update §7 and notify grill.md §11.
• The page is older than the project's review cadence → refresh.

The discipline

1. The wiki is local, not a mirror

A wiki page is not a copy of upstream documentation. It is the narrow slice of the library that this project uses, plus the project-local idioms, pitfalls, and history. The whole upstream goes in docs/graph/sources/raw/ and docs/graph/sources/normalized/; the page in docs/graph/libraries/ is the project's distillation.

If a wiki page reads like a tutorial for someone who has never used the library, it has drifted from the discipline.

2. Pin to a version

Every page pins the exact version the project depends on. "Latest" is not a version. When the project upgrades, the page updates the pin and adds an §8 (Upgrade path) entry summarizing what changed between the previous and current pin.

3. Cite, don't paraphrase

Every claim on the page has a citation in §10 (References) — a URL, a retrieval date, and (when the source is paywalled or transient) a local snapshot path in docs/graph/sources/raw/.

Do not paraphrase upstream text closely; either cite a quote (short, in quotes, with citation) or rewrite the idea in the project's own words. Most pages need very little upstream text.

4. Compound, don't restart

When a new file starts using a new name from the library, add a line to §3 (Used API surface) — do not list the whole upstream API preemptively. When a new idiom is adopted, add it to §4 — do not predict idioms before they're real. When a pitfall is hit, add it to §5 with a date — do not list theoretical pitfalls.

The page grows with the project. A bare page that says only "we use library X for Y, install with Z" is a perfectly acceptable starting point.

5. Validate before publishing

A wiki page is not authoritative until a smoke test confirms the pinned version works. The smoke test:

• Imports the library at the pin.
• Calls one or two of the names in §3.
• Runs in the project's normal test harness.

If the smoke test fails, the page is wrong (or the install is wrong); fix one of them before promoting the page.

Workflow

Creating and refreshing a page — which phase, which owner, which spawn waits for which — are ingest-library.flow and ingest-library.refresh in docs/graph/protocols/ingest-library.md, and are not restated here: a second copy of a sequence drifts. What this skill adds to the scout's draft, section by section: §0 (Pin) and §1 (Role) from the lockfile and the architect's brief; §2 (Install) from a command actually run in a clean environment, recorded exactly as it worked; §3 (Used API surface) from the current code that uses the library — or, when the page precedes the code, the names from the brief marked "planned"; §10 (References) from the sources research-scout staged in docs/graph/sources/. The smoke test that makes the page authoritative is the tester's phase of the same pass.

When to also create a best-practices/ page

The library wiki is per-dependency. When a concern spans multiple libraries and needs a cohesive guidance (e.g. "how this project handles HTTP errors across our two HTTP clients"), that's a docs/graph/best-practices/<concern>.md. It links to the relevant wiki pages; it does not duplicate them.

Anti-patterns

• Page is a tutorial. Tutorials belong upstream; the page is the project's distillation.
• Page covers names we don't use. §3 lists what the codebase actually imports; not the whole upstream surface.
• Page has no citations. Cite or it didn't happen.
• Page lists pitfalls we haven't hit. Theoretical pitfalls aren't useful; real ones, with dates, are.
• Page never updated after creation. A static page diverges from the code within weeks. The implementer and reviewer keep it current.

Reference files

• docs/graph/templates/library-page.template.md — the page template.
• docs/graph/protocols/ingest-library.md — the ingest workflow.
• docs/graph/agents/09-docs-librarian.md — the agent that owns the wiki.
• docs/graph/agents/10-research-scout.md — the agent that fetches sources.