Billing webhook contract
docs/billing/webhooks.md
current · re-read 2 days ago
Cited by 4 beliefs. Anchored to the section, not the whole file.
Continuity / Library
Docs an agentcan actually cite.
An agent quoting your architecture doc from eight months ago is worse than one that admits it does not know. Library keeps a catalog of the documents your project owns, records when each was last read, and puts that freshness in the answer — not in a log.
Evolving · legal gate not builtADR-018zephr_docsteam docs first
The mechanism
From a document to a citation with a date on it.
The catalog is not a search index with extra steps. Every entry keeps its fetch time and content digest, so a citation can be checked rather than trusted.
- 01
Admit the docs, not the internet
A catalog starts from the docs your project already owns. Nothing enters because it happened to be reachable.
- 02
Read and record when
Each document is stored with its fetch time and a content digest, so "how old is this?" has an answer instead of an estimate.
- 03
Cite sections, not files
Citations point at the section that actually says the thing, so a change elsewhere in a long document does not invalidate an unrelated claim.
- 04
Track freshness and deprecation
A changed source marks its citations stale. A document that declares itself deprecated carries that forward and names its successor.
- 05
Surface the signal at recall
Freshness travels with the answer. An agent quoting a stale runbook is told it is quoting a stale runbook, in the same result.
- 06
Degrade out loud
When the catalog is unreachable or a source cannot be re-read, the tool returns an explicit degraded state — never a confident answer from a cached guess.
The specimen
The catalog, with its gate.
Four team documents in four different states of freshness, and one entry that is deliberately not there.
Docs catalog · apps/billing
Every row carries the time it was last read and what has happened to the source since. The stale runbook is still returned — labelled stale, with the changed section named — because withholding it entirely would lose real information.
Team docVerified Team docVerified ADR-014 — Continuity Format
docs/adr/ADR-014-continuity-format.md
current · unchanged since capture
Cited by the handoff verification path.
Team docStale Internal auth runbook
docs/runbooks/auth.md
stale · source changed 19 days ago
Recall still returns it, flagged stale, with the changed section named.
Team docUnreviewed Payments provider API guide
docs/vendors/payments-migration.md
deprecated · superseded by v3 guide
Marked deprecated at the source. The successor is linked, not silently substituted.
Third-party docWithheld Third-party framework docs
curated external catalog
withheld · legal gate not built
Not crawled, not served, not counted. The gate that would permit this does not exist yet.
never fetched
Legal gate — not builtCurated third-party catalog
Curated third-party documentation needs per-source licensing review, attribution, and an org-level opt-out before a single page is crawled. That gate is designed and not implemented, so the third-party catalog is empty rather than provisional. It is listed here as withheld instead of quietly omitted, because an empty section with no explanation reads as a capability that works.
Illustrative example — not live data
What Library owns
A catalog, its freshness, and a gate that is still shut.
The crawler and the docs tool are real and shipped with honest degraded states. Curated third-party documentation is not served, because the legal gate that would make serving it defensible has not been built — and shipping it first would be exactly the shortcut this product refuses.
Team-private docs first
ShippedYour own docs, ADRs, and runbooks are the primary catalog. They are the ones agents get wrong most expensively, and they carry no licensing question.
crawler + zephr_docs · ADR-018
The zephr_docs tool
ShippedA dedicated docs tier in the tool contract: remote and full-catalog in cloud mode, local and project-docs-only in local mode.
docs tier of the tool contract · ADR-004
Honest degraded states
ShippedWhen the catalog is unreachable or a source cannot be re-read, the tool says so. There is no cached-and-confident fallback path.
honest-or-absent law · ADR-016
Freshness signals in recall
Signals shipped · recall wiring partialFetch time and content digest travel with every citation, so a stale document is labelled stale in the answer rather than in a dashboard nobody opens.
freshness migration shipped; end-to-end wiring in progress
Deprecation signals
EvolvingA document that declares itself superseded carries that forward and names its successor, instead of quietly ranking below it.
source-declared deprecation parsed; propagation being tuned
Section-level anchoring
EvolvingCitations point at sections, so an edit elsewhere in a long document does not falsely invalidate an unrelated claim.
shares the anchor substrate with Memory · ADR-029
Curated third-party docs
Planned — legal gate missingFramework and library documentation, curated and kept fresh alongside your own. It is not served today because the legal gate that would permit it is not built.
blocked on the ADR-018 legal gate
Legal gate
PlannedPer-source licensing review, attribution, and org-level opt-out, deciding what may be crawled, stored, and quoted back. Until it exists, third-party docs stay out of the catalog.
ADR-018 · scheduled with the R4 catalog work
A citation is only worth its date.
Library feeds the same evidence graph Memory writes to, which is why a doc citation and a belief can contradict each other visibly instead of silently.