Update Library Documentation

Update documentation in .claude/docs/libraries/ with latest information.

Steps

1. Inventory Library Docs

Run lib_inventory.py instead of eyeballing the directory — it scans each doc's > **Last Updated** / > **Version Checked** metadata, resolves the version the project declares and locks, and cross-checks declared dependencies:

python3 .claude/skills/update-lib-docs/lib_inventory.py \
  [--stale-days N] [--today YYYY-MM-DD] [--library NAME] [--project-root DIR]

Emits {ok, libraries_dir, stale_days, today, library, libraries, counts, missing_metadata, undocumented, declared_dependencies, dependencies, sources, manifest_errors, warnings, artifacts}.

stale is the OR of two signals, and stale_reasons says which fired:

• age — age_days > --stale-days (default 90).
• version_drift — version_checked disagrees with locked_version, with a pinned declared_spec, or falls below the spec's lower bound. version_drift is true/false only when the comparison is decidable; null plus version_drift_note means it is not (no lockfile behind an open range, a non-numeric version). null is not "clean" — read the note.

Exit codes: 0 ok, 1 bad argument (--today not YYYY-MM-DD, --library not a package name, --project-root missing), 2 a manifest or lockfile could not be parsed, 3 a library doc could not be read. If ok is false, stop and report the manifest_errors / read_error entries — an empty scope from a broken manifest is not success.

This run's scope is the union of three lists from that output: entries with stale: true, every doc in missing_metadata, and every name in undocumented. Everything else is already current — skip it.

2. Web Search for Latest Info

For each library in scope, search for:

• Breaking changes
• Deprecated features
• New features
• Security updates
• Newer upstream releases (an upgrade consideration, not the version recorded in the doc — > **Version Checked**: is the version this project uses, which the inventory already resolved)

3. Update Documents

Derive each doc path from the same authority research-lib uses, so an update and a creation can never disagree about the filename:

python3 .claude/skills/_shared/workspace.py --skill research-lib \
  --title "{library}" --create

Then, for each stale library, update paths.lib_doc; for each undocumented dependency, create it following the same template (see research-lib's documentation template for the full section layout):

1. Update > **Version Checked**: to the inventory's locked_version (or the version satisfying declared_spec when nothing is locked)
2. Update > **Last Updated**: to today
3. Add new features/constraints
4. Mark deprecated APIs
5. Update code examples if needed

4. Validate Updated Documents

After updating or creating a doc, validate it against the lib-doc contract:

python3 .claude/skills/_shared/validate_doc.py --contract lib-doc \
  --file <paths.lib_doc>

Exit 0 means the four required ## sections (Overview, Core Features, Constraints & Notes, References) and the Last Updated / Version Checked metadata lines are all present. Exit 1 means the file does not exist or could not be read (there is no sections_missing on that path — check the path before editing anything). Exit 2 means the doc violates the contract: sections_missing lists absent sections, metadata_missing lists absent metadata lines. Fill both in; do not report the update as complete with either non-empty.

Re-running step 1 is the completion check: a doc you updated must no longer appear in stale, missing_metadata, or undocumented.

5. Check Impact on Code

After updating docs, verify:

• Using any deprecated APIs?
• Any breaking change impacts?
• Need to update project dependencies?

Editing a manifest or source file is outside this skill's documentation scope. If step 5 leads to any change outside .claude/docs/libraries/, run the gates before reporting:

bash .claude/skills/_shared/verify.sh

Exit 0 means the gates passed; exit 2 means a gate failed or no gates ran. Do not report completion on a non-zero exit.

Key Items to Check

Update Format

There is one library-doc template, in research-lib/SKILL.md under ## Documentation Template, and it is the version pinned by tests/test_validate_doc.py against the lib-doc contract. Do not keep a second copy here: a template that no test pins is how the two skills came to disagree about the metadata block in the first place.

An update edits the existing document in place:

• Refresh the > **Last Updated** / > **Version Checked** blockquote that already sits directly under the H1 — it is the only place a version lives, so do not add a second version line anywhere.
• Optionally add a ## Recent Changes list after the blockquote; it is not a contract section, so keep the four required sections intact.

Report

After updating, report to the user per .claude/rules/language.md:

• Which libraries were updated
• Significant changes found
• Any action items for the project