docs: full API reference + capabilities; export PartialGraphContext

docs/API.md is the authoritative interface reference: exports, Arbiter
methods, check options/result shape with contract invariants, all ten
relation configuration formats, valueManager, partial graphs (raw spec
+ pre-built context, precedence contract), snapshots (format, frozen
restore, trust boundary), reachability (null-defer contract), OWAFusion,
audit hook, errors, reason codes, and the validity taxonomy.

README gains a capabilities section (what the engine does and does not
do) and links the reference, per the map-vs-manual split.

The reference pass surfaced one interface gap: PartialGraphContext —
a first-class public type used in the pre-built overlay form — was not
exported. It is now part of the public surface.

Verified claims against source (overlay spec keys: challenges/
challengeProofs not proofs; qualitative routing via qualitative: true /
scaleName; simpleBinary shape; reason enum; config formats). Rigor
251/251, full suite 853/791/0.

README.md

@@ -72,23 +72,27 @@ Denied decisions never leak a source's reliability. `includeMeta: true` adds `me
 
 ## API
 
-The public surface is the `Arbiter` class:
+The full reference — every export, method signature, option, result shape, configuration format, error, and reason code — is in [docs/API.md](./docs/API.md). The public surface at a glance:
 
 - **Graph**: `addNode`, `addRelation`, `removeRelation`, `setRelationConfig`, `getNodeData`, `resolveNodeId`, `resolveKey`
 - **Check**: `check(userKey, relation, objectKey, options)`, `explain` (enriches `meta`), `binary` mode (fast path, marks results `binary: true`)
 - **Reachability**: `isReachable`, `getReachableNodes`, `getReachingNodes`, `shortestPathLength`, `estimateGraphDistance` (`isReachable` returns `null` when no PLTC index is available — a signal to defer to rule evaluation)
 - **Snapshots**: `enableCondensedSnapshot`, `toSnapshotBinary`, `Arbiter.fromSnapshotBinary` (lossless: carries relation metadata, TTLs, and validity; malformed buffers fail fast with clean errors)
-- **Value context**: `valueManager` (TTL-gated evidence), `getSituationTree`, `monteCarloWalk`
+- **Value context**: `valueManager` (TTL-gated evidence), `PartialGraphContext` (overlays), `getSituationTree`, `monteCarloWalk`
 
-Check `options`:
+## Capabilities
 
-| Option | Type | Default | Meaning |
-|--------|------|---------|---------|
-| `includeMeta` | `boolean` | `false` | Attach full provenance in `meta` |
-| `explain` | `boolean` | `false` | Enrich `meta` with the evaluation trace |
-| `binary` | `boolean` | `false` | Binary fast path; results marked `binary: true` |
-| `now` | `number` | engine clock | Pinned temporal context for TTL gates |
-| `partialGraphContext` | `PartialGraphContext` | none | Overlay taking precedence over the base graph |
+The engine derives authorization decisions from a relation graph. What it does, in one pass:
+
+- **Ten policy kinds** compose arbitrarily: direct, tuple-to-userset (groups), chain, multi-hop, defeasible (when/unless/never/always/requires), union/intersection/exclusion (with OWA fusion), relational comparator (ABAC over values), qualitative comparator (decaying scales), challenge (proofs/MFA), parent.
+- **Possibilistic semantics**: decisions are maxitive rankings in `[0,1]`, not booleans — with reliability, validity provenance, and reason codes on every result.
+- **Caller-owned time**: every TTL gate, decay, and proof expiry honors the caller's pinned `{ now }`; a rerun reproduces the decision.
+- **Overlays**: evaluate "what if this evidence existed" without mutating the graph; caller-supplied facts ride the policy's direct relations.
+- **Lossless snapshots**: condensed binary serialization (~170 bytes/node) with frozen restore; malformed input fails fast and bounded.
+- **Reachability**: exact PLTC index with sound fast-fail and a documented `null`-defer contract.
+- **Determinism**: 251 seeded rigor campaigns — parity across normal/binary/snapshot-restored evaluation, mutation freshness, TTL contracts, complexity classes, and adversarial snapshot fuzzing.
+
+What it does **not** do: no storage, no transport, no policy source of truth, no user/group management — it is a library that answers one question: *may user U perform relation R on object O?*
 
 ## Development