Documentary record · claude-library (clib) · April – July 2026
Every load-bearing claim in clib's history — who asserted it, who challenged it, how it was tested, and what survived. Each piece of evidence is attributed to one of six source classes, because the record shows the classes have very different track records. Purpose: this is a field guide for teams adopting Anthropic tooling — one real project's paper trail of what model-driven development gets right, where it silently drifts, and how to catch it. The transferable cautions are at the end.
One claim, one verdict. An exhibit that involves more than one claim states each claim and stamps each separately — a verdict never has two resolutions. Findings that emerge alongside a verdict (a bonus discovery, a real defect behind a wrong attribution) are recorded as evidence, not stamped.
claude -p probes, error output proving execution, scratch-DB migration runs, the interpreter's own AST. Never overturned in this record. Highest authority.fix4, overhaul again, well well well well well, and diffs that visibly flip decisions back and forth are the seam lines between sessions that shared no memory. REPO is not an independent witness; it's model output that survived long enough to be treated as consensus.Exhibit letters are stable citation anchors assigned at admission; presentation order is severity. The keystone comes first, minor claims last.
This is the central premise of the entire tool: deferring loads. Get it wrong and every downstream function breaks at once — importing (inert @import lines, Exhibit A is the syntax facet of this same premise), deploying and injecting (eager @import regions defeating the budget), maintaining (eject anchored to the wrong inventory), and back-referencing the catalog (CLAUDE.md region vs filesystem vs DB disagreeing about what's installed). Every other exhibit is a component failure; this one is the load-bearing wall.
springbig.members is not only wrong depending on postgres vs redshift…") and asked how org knowledge could be reused without contaminating generic skills — the challenge that forced the layering.inject gained a CLAUDE.md @import region for skills — force-loading bodies native discovery would lazy-load. Author: a later Claude implementation session contradicting an earlier Claude design session, with no shared context between them to catch it.@import <path> as CLAUDE.md import syntax@import ~/.claude/domains/springbig/…. Never demonstrated working in the session.@import; clib emits f"@import {path}" and its parser expects the same prefix. The consensus inherited the untested assertion.@path; an @import … line is inert text. Every context "imported" through the region silently never loaded.@import asserted repeatedly, never once observed loading content. No working-era evidence exists. Ironic corollary: the harmful inject region used correct bare-@ and worked; the legitimate contexts region used @import and never did.@path, parser reads both forms, legacy regions self-heal. EMPIRICAL · JUL 12 post-fix, clib imports add wrote a valid @/Users/…/contexts/personal/defaults.md line — contexts loadable for the first time.{command, timeout: 10000}marker key), neither aware of the other. Author: Claude, in later implementation sessions now lost to transcript retention — writing from memory instead of the founding session's own correct nested examples. Model-to-model drift across sessions that shared no context.SessionStart:startup hook error — Failed with non-blocking status code is proof of firing. The repo diverged from its own source material.{matcher, hooks:[{type, command, timeout(seconds)}]} since hooks shipped (v1.0.38). Flat shapes silently ignored; timeout: 10000 also ms-vs-seconds confused.application/hooks.py helper — nested schema, seconds, mutual idempotency, in-place upgrade of legacy entries. 9 unit tests.{category}-{name} live in that session; REPO clib inherited it as symlink_name..claude/skills/ loading added ~v2.1.190+" — suggesting the limitation may have lifted and flattening might now be legacy cruft.claude -p run: flat skills/flat-probe/ ✓ discovered · nested skills/nested/depth-probe/ ✗ absent. (The symlink probe from the same run is Exhibit H — a separate finding.)skills/ a flat namespace with zero hierarchy: no grouping by domain, vertical, or class; taxonomy demoted to name-mangling conventions (data-dba, lang-python); and common task names across domains can only coexist as atomic files that risk clobbering each other in the one shared namespace. This is a standing platform deficiency, not a solved problem — and it is a load-bearing part of clib's necessity case: the catalog's namespace/section/rules model is the hierarchy layer the platform lacks, with flattened symlink names as mere wire format. Recorded as a structural consequence, not stamped: it's an assessment, not a testable claim.deployer.py's copytree path, the deprecated deploy/auto commands, and profile use --apply.clib inject has been symlink-based since.~/.mcp.json). The two behaviors this setup most depends on are the two the docs don't mention.skills/linked-probe → elsewhere ✓ discovered by name+description like any real directory.claude -p invocation).store/agent/<name>/ dir malformed into a flat copy of all 11 agents with no AGENT.md → provision agents silently skipped all of them → 11 dangling symlinks → zero agents in context. Content intact throughout; contract broken. REVIEW · JUL 12The re-keying timing (May 5 / Jun 4) aligns with clib's own v7 migration — the drift was internal to the amnesiac-session pipeline, not a Claude Code update.clib doctor (P1).BinderException on first write. No warning at any point.SchemaIntegrityError sentinel checks now fail loudly at open, naming the missing features. Tested for phantom and honest-v1 paths.~/.mcp.json is honored by Claude Code~/.mcp.json makes servers available in all projects" — and generated one (context7, clickup, cloudflare, postman, codebranch) with env-var token references. REPO · surfaces.pyCodified as clib's mcp_global surface and a config-doc table row.~/.claude.json via claude mcp add --scope user." The findings register stamped this NEVER TRUE and queued a P0 fix to re-point the surface.~/.mcp.json holds exactly codebranch + telnyx; ~/.claude.json has an empty mcpServers; no project .mcp.json — yet codebranch connected in a live Claude Code session. Only possible source: the "nonexistent" file.~/.claude/settings.local.json as a user-level scope.claude/settings.local.json." Register initially agreed: remove from the doc.disabledMcpjsonServers, enableAllProjectMcpServers, permissions.allow.env block — two claims, one test"PATH": ".../proto/shims:${PATH}", claiming expansion works ("the ${PATH} version is self-maintaining").SessionStart:startup hook error — env: bash: No such file or directory / python3: command not found. PATH had been set to the literal string. The model corrected on the evidence: settings.json does NOT expand ${VAR}; .mcp.json does.clib env sync / env_mgr.py, on the theory that "the static block drifts by design, so tooling must re-sync it."paths.d/*), so zsh-configured environment — and sometimes zsh syntax — was being run through bash. R5 was designed against a partially mischaracterized mechanism, and env sync has barely been used since. The correct diagnosis was scattered through the founding transcript the whole time (Dock launches get the bare system env; Claude Code hardcodes ~/.zshrc and ignores ZDOTDIR, issue #11635; the Bash tool uses bash) — but no session assembled it into the requirement. EMPIRICAL · this sessionCorroborated live today: a Bash-tool subshell failed with command not found: curl/head before absolute paths succeeded — same failure class, still occurring.env block is honored by Claude Code. The failure is the proof: a mis-set PATH could only break hook execution if the block were applied. Also closed today's last open schema question. VALIDATED${VAR} expands inside that block. Refuted by Bill's own deployment minutes after the model asserted it — PATH was set to the literal string. (.mcp.json does expand ${VAR}; the two files parse differently.) DEBUNKEDprofiles.py:54 "real bug" (Python-2 except binding)except orjson.JSONDecodeError, OSError: binds OSError as a variable and catches only the first type — "verified empirically on 3.14.4."Tuple(ValueError, OSError), handler name None. Runtime: both exception types caught. Python 3.14.4, this repo's interpreter.attribution: "false" as a string value~/.claude/settings.json today; the model conceded "your real-world testing is more reliable than my inference from search results."--init/--maintenance; SessionStart + matcher startup is correct per-session. MISLEADING — WRONG USAGE$CLAUDE_FILE_PATH / $CLAUDE_TOOL_INPUT. ANTHROPIC · hooks docsHooks receive stdin JSON; no evidence these vars ever existed in any source class. DEBUNKEDEMPIRICAL is undefeated. No observation of the machine was ever overturned in this record — not the in-session hook failures, not the live filesystem reads, not the headless probes, not the scratch-DB reproductions. Everything else was overturned at least once.
BILL is the continuity layer, and that — not omniscience — is why the challenges landed. The user was navigating an unfamiliar tool, not adjudicating it; but as the only participant present across every session, he was also the only place cross-session contradictions could surface. The domain-bleed catch created the contexts layer (Exhibit F); the symlink suggestion replaced a copy design that would have drifted (H); the attribution pushback beat model inference (L); the settings.local.json challenge exposed a model self-contradiction (D); "you'll excuse me if I'm skeptical" overturned two fact-check verdicts (C, D); and even the shorthand of Exhibit I was a correct reading of the observable symptom. In a system where every other author is amnesiac, the human's accumulated friction is the institutional memory.
ANTHROPIC docs are necessary but describe a subset of the product. They correctly killed @import and the flat hook schema — and were contradicted by the machine on ~/.mcp.json and user-level settings.local.json. Observed behavior is a superset of documentation.
REPO artifacts are consensus snapshots, not truth — and they're Claude's writing too. The config doc and clib's code (both model-authored, Bill-curated) faithfully preserved the good empirical lessons (flattening, env sync) alongside the untested model assertions (@import) — and added drift of their own (flat hooks, skill @imports) where a later Claude session, writing without the earlier session's context, contradicted the earlier Claude's correct work.
MODEL and REVIEW assertions are hypotheses until tested. April's model was right about ~/.mcp.json and wrong about ${VAR} expansion; July's reviewers were right about hooks and wrong about ~/.mcp.json. Same class, same failure mode, opposite directions — which is why the class, not the date, is what the chips track.
The uncomfortable census: of the six classes, four — MODEL, REVIEW, REPO, and even the config doc this audit began by fact-checking — are Claude's own output at different moments, checking and contradicting itself across sessions that share no memory. The only independent witnesses in the entire record are BILL, ANTHROPIC, and the machine itself. That is the structural argument for the evidence hierarchy: when four of your six sources are the same fallible author wearing different timestamps, you privilege the two that aren't — and the machine outranks everyone.
What this record generalizes to. Each caution cites the exhibits that earned it.
1. Treat model-asserted configuration as a hypothesis, and test it the moment it's written. The most expensive errors here were schemas Claude stated confidently and nobody ran: an import keyword that was never real (A), a hook shape no version ever accepted (B). Both were cheap to verify at generation time — a one-line probe, a read of the file another tool actually consumes. The cost of not verifying was months of a silently dead feature. (Exhibits A, B, E2)
2. Don't trust the docs as a ceiling either — the product's observed behavior is a superset of its documentation. Two "the docs say this doesn't exist" verdicts died on contact with the live machine (C, D). Before ripping out something that works, or building on something documented, check what the machine actually does: read the real config files, run a headless probe, watch what loads. (Exhibits C, D, G, H)
3. Session amnesia is the root hazard of model-driven development. Every session starts with no memory of the last one. This repo's git log is the fossil record: 24 commits, each a discrete Claude session, with diffs that flip prior decisions and messages that chart the frustration. A later session contradicted an earlier session's correct design (F) and its correct hook examples (B) because nothing carried the context forward. Mitigations: persist decisions in repo docs the next session will read, review diffs specifically for silent reversals, and keep one human continuously in the loop — their accumulated friction is the only institutional memory the system has. (Exhibits B, F; the git log)
4. Expect failures to be silent, and build fail-loud checks into anything that writes config another system consumes. Claude Code ignores invalid config rather than rejecting it: bad hooks are skipped, inert import lines render as text, malformed stores provision zero assets without a word. Every breakage in this record announced nothing, which is why each one read as "the product broke." If your tool writes settings, hooks, or assets for another system, ship a doctor command that asserts the contract end-to-end. (Exhibits A, B, I, J)
5. Prefer the platform's native primitives over re-implementing them — but know where the primitives end. The single largest blast radius here (F) came from re-implementing loading that the platform had made native — auto-discovery and progressive disclosure. The founding design got this right; a later implementation session drifted into fighting the platform. At the same time, the primitives have real gaps teams will hit at scale: skills/ is a flat, one-level namespace with no hierarchy — no grouping by domain or vertical, taxonomy only by naming convention, and collision risk once multiple teams contribute skills. Plan a taxonomy layer (a catalog, a naming contract, or both) before your skill count grows past what one flat directory can carry. And favor symlinks over copies for anything deployed from a shared library — copies drift, and the platform discovers symlinked dirs even though the docs don't say so. (Exhibits F, G, H)
6. Read user reports as symptom descriptions, not literal mechanism claims. "It dropped my agents" meant "the deployed catalog no longer matches the contract, so it's absent from context" — accurate observation, compressed. Triage the observable symptom (what's missing from context, what file diverged from what schema) before litigating the attribution. (Exhibit I)