docs: sync contributor docs and resync docs.decdn.org with the protocol adrs

[yigitdot]

Two doc sets had drifted. One commit for each, so they can be reviewed separately.

docs(agents): README + AGENTS.md vs the codebase

Roughly 20 PRs landed since these were last touched (live stats #253, CSS layers/tokens #256, mobile menu #261, Geist Mono #266, Discord #269).

Fixes in AGENTS.md

• pnpm start: next start throws an error under output: "export". The entry now says so and points to npx serve@latest out.
• Duplicate bullet: scripts/ was listed twice in Layout; one entry is removed.
• Scripts entry:
  • check-out.mjs also asserts the PANEL_CAPTIONS strings in the built homepage.
  • Only check-og-image.mjs has a test.
• vitest bullet: the code spans were broken (**/\*.test.ts, missing spaces). They're fixed, and the bullet now covers hook-using client components, which are tested through a pure render half (FleetPanel).
• docs/ bullet: root vitest still collects docs/*.test.ts, and the docs workflow runs pnpm test.

New gotchas in AGENTS.md

• CSS @layer placement and the ease/font/radius tokens.
• Fonts are self-hosted via next/font, so the CSP only needs font-src 'self'.
• Social links have three consumers: links, sameAs, and the llms-full contact line.
• Dependabot ignores ESLint majors.

README.md

• Node ≥24 in the stack line.
• format:check, and both build guards.
• lib/stats.ts in the layout list.
• A live-stats / connect-src CSP gotcha.
• highlightBrand.

docs: docs.decdn.org vs the protocol ADRs

The source of truth is decdn/decdn/adr/, read from the local checkout at commit cdd1db5e (2026-10-08). The last resync was 2026-09-27 (#232, #251). Before each edit, the cited ADR passage was re-read.

Corrections

Items marked pre-resync were already wrong before that resync.

• Voting cap (pre-resync): 10% at launch, bounds 1–10%, decrease-only. It was 5% / 1–25% (ADR 036, 009).
• Rate floor (pre-resync):
  • A node advertises its rate verbatim and never raises it to the floor. A below-floor voucher still settles in full; only its vote-weight byte credit is clamped (ADR 003, 005).
  • The page now also mentions MAX_RATE_PER_MB.
• minBond entry floor: "rather than a flat minimum" is replaced in four places (ADR 026).
• Auto-ejection: keyed to bondFloorAtActivation, and recoverable by re-bonding.
• Origin-backed nodes (pre-resync): they decline blobs outside their backend by default (cache.relay_foreign_namespaces) (ADR 002).
• Client discovery (pre-resync): clients run no DHT lookup (ADR 039, 012).
• Capabilities: write-once with no renewal. Admission reads the signer's {cap, expiry, spent}, and a mid-stream cap breach returns SignerCapExhausted (ADR 003).
• Credit window: per stream, with a formula, a lane ramp-credit pool, and defaults (ADR 003).
• Multi-source fetch — rewritten to ADR 039:
  • Every fetch runs the scheduler, and the 64 MiB size floor is gone.
  • Coverage is a preference, not an exclusive claim.
  • Steals split in proportion to delivery rate, with 16 MiB / 4 MiB floors, plus slow-victim steals.
  • A 10 s watchdog, after which a source cools and rejoins.
  • A stop policy.
• Network (ADR 022, 001, 037, 019):
  • The origin fallback also applies to partial coverage.
  • A node refuses before commit.
  • Both address sources are named (registry multiaddrs and pkarr).
  • Client cooldown values are given.
  • The operator runs decdn node update-multiaddrs.
• Smaller fixes:
  • The docs.json description said "channels"; it now says a shared on-chain pool.
  • DHT records are published once a node holds one verified block.
  • The dormant 90/0/10 revenue split is noted.
  • minDeposit launches at 0.

Coverage added

Accepted ADRs only, as short paragraphs on existing pages:

• ADR 040 cache policy, in Participants → Nodes.
• ADR 041 refuse-to-serve margins, in How it works.

Notes for reviewers

• Draft-ADR gaps left out on purpose: ADR 037 proxy warming, and pool binding / expiry margin from ADR 003.
• ADR repo bug: decdn/adr/003-payments.md:49 still says a capability expires "when the owner does not renew it". Two lines later the same ADR says there is no renewal. The docs follow the write-once rule; the ADR line needs fixing in that repo.

Verification

• pnpm exec prettier --check .
• pnpm exec markdownlint-cli2
• pnpm lint
• pnpm test (521 passed)
• npx mintlify@4.2.555 broken-links (no broken links)

🤖 Generated with Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[cloudflare-workers-and-pages]

Deploying website with    Cloudflare Pages

Latest commit:	78980f0
Status:	✅  Deploy successful!
Preview URL:	https://9b65c24f.website-70y.pages.dev
Branch Preview URL:	https://claude-docs-update-614845.website-70y.pages.dev

View logs