Skip to content

Maintaining the Contracts docs

The published Contracts section contains reader-facing Markdown and the function browser. Raw ABIs, generated catalogs, fixtures, manifests, source hashes, and generator inputs stay local; they are ignored by Git and excluded from MkDocs.

Content boundaries

  • Edit product, architecture, integration, indexing, operations, and security pages directly.
  • Treat docs/contracts/interfaces/functions/ as generated reader-facing documentation. Do not hand-edit those pages.
  • Keep local generation inputs under .local/contracts-inputs/, or point KURU_CONTRACTS_DOCS_SOURCE at another local input directory.
  • Never link a published page to the local input directory or copy raw artifacts into docs/.

Refresh the function browser

When the callable surface or function semantics change, refresh the local source input and run:

node scripts/generate-function-docs.mjs
node scripts/generate-function-docs.mjs --check

The generator requires one meaningful description and one selector-stable entry for every ABI function. It also validates the explicit user-function taxonomy and rejects missing, duplicate, or read-only allowlist entries.

Review checklist

  1. Trace the complete user call through authorization, local mutation, custody or risk mutation, and events.
  2. Check pause behavior for risk-increasing, release, and cancellation paths.
  3. Check units, sentinel values, and every rounding direction at the boundary where it is used.
  4. Reconcile free balance, Spot reserves, passive inventory, Perp margin, fee reserves, fee collector, and builder accrual.
  5. Test packed layouts, slot bounds, duplicate handling, and stale-size behavior.
  6. For upgrades, compare storage layouts on populated proxies and test initialization or migration calldata.
  7. For event changes, update decoder tests and replay at least one complete state transition.

Validate the published site

node scripts/validate-contracts-docs.mjs
mkdocs build --strict

The repository validator checks navigation coverage, local links, absence of source-artifact links, and the committed function-browser shape. Source-pack validation remains a separate local contracts-maintainer task and is not part of the documentation build.