docs(intelligence): rewrite the SDK doc to shipped truth — observe + delivery lanes, fenced design tail

[drewstone]

What

Rewrites docs/intelligence-sdk.md (238L wishlist labeled "target interface — wrapper not fully shipped") into a ~220L reference of what the /intelligence subpath actually exports today.

• Status header now says shipped: Observe + OFF billing floor + effort tiers + redaction + certified delivery + capability resolver. The unshipped Recommend/PR/Loop client verbs move to one fenced "Designed, not shipped" tail.
• Quickstart keeps the withTangleIntelligence snippet — verified verbatim against src/intelligence/index.ts — with the caveat that repo/checks/surfaces are doctor()-readiness inputs only, plus the $0 offline run line.
• Normative claims policy kept near-verbatim under an explicit heading — it is current policy and matches the delivery code (a CertifiedArtifact carries held-out gate lift, never a within-run claim).
• Observe section documents the real createIntelligenceClient surface: config fields, traceRun/TraceHandle, recordTrace (nested OTLP via buildLoopOtelSpans), doctor(), flush(), endpoint env resolution, the best-effort law, and the billing-split span attributes.
• NEW "Two lanes" section (~60L) — the largest shipped-but-undocumented surface: the plane pull contract, pullCertified (typed PullOutcome, 404-is-normal, 10s timeout), createCertifiedPromptSource (5m refresh, coalesced, keep-last-known), composeCertifiedPrompt (byte-stable fold, promptFoldTypes), withCertifiedDelivery, and the capability resolver (composeCertifiedProfile/FromWire, injected ResolveCtx, admitted binding kinds, CapabilityNotAdmittedError, fail-closed drops + drift check).
• Effort tiers table lifted verbatim from effort.ts presets; isIntelligenceOff, the clamp-on-export invariant, compileEffort, and the product-vs-experiment fail-closed distinction; the stale #268 EffortPolicy pointer is gone.
• Adoption ladder gains a Status column (shipped / partial / designed) mirroring doctor(); "What is live today" grounds each rung in the two $0 offline examples.
• Fenced tail holds the four unshipped verbs (flushRecommendations, runImprovementCycle, configureLoop, defineImprovementSurface) inside one code fence, each mapped to the substrate that exists underneath (recordTrace → analysts → improve(); doctor() PR readiness; improvementDriver/agenticGenerator/promotionGate).

Companion edits: docs/README.md index row updated; intelligence-sdk.md added to the freshness gate's curated set in scripts/check-docs-freshness.mjs, so every backticked symbol in the prose must now resolve to a real export (the fenced tail is skipped by design).

Verification

• pnpm run docs:check — OK, "prose symbols in 4 curated docs" (the doc is now gated and clean); generated docs/api byte-identical, no drift.
• pnpm run lint (362 files), pnpm run typecheck + typecheck:examples — clean.
• pnpm tsx examples/intelligence-drop-in/intelligence-drop-in.ts — exit 0, span read back with intelligence_usd = 0.
• pnpm tsx examples/intelligence-recommend/intelligence-recommend.ts — exit 0, trace → 2 findings → gated candidate shipped.
• Signatures spot-checked by reading current source: withTangleIntelligence (index.ts), pullCertified (delivery.ts), composeCertifiedProfile (resolver.ts), effort presets (effort.ts), defaultRedactor (redact.ts).
• Zero src/ hits for the four unshipped verbs re-confirmed (they exist only in this doc's fence).

[tangletools]

✅ Auto-approved drewstone PR — d95b7c7d

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: drewstone_author · 2026-07-02T22:16:44Z}

[tangletools]

✅ Auto-approved drewstone PR — f1d5e2c5

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: drewstone_author · 2026-07-02T22:31:13Z}