docs(sheaves): add INTRODUCTION.md and fix doc links

INTRODUCTION.md frames the sheaf as the construction that asserts
alignment of overlapping ocap surfaces — the case where you want
attenuation-style coherence but don't share a common base. README is
updated to point at it and to use the correct documents/ subpath for
USAGE.md and POLICY.md (the LIFT.md link was stale after the earlier
rename).

Author: grypez

packages/sheaves/README.md

@@ -6,8 +6,10 @@ Runtime capability routing adapted from sheaf theory in algebraic topology.
 over a collection of capability providers. The sheaf produces dispatch sections via
 `getSection`, each of which routes invocations through the provider set.
 
-See [USAGE.md](./USAGE.md) for annotated examples and [POLICY.md](./POLICY.md) for
-the policy coroutine protocol and semantic equivalence assumption.
+See [INTRODUCTION.md](./documents/INTRODUCTION.md) for what a sheaf is and when to
+reach for one, [USAGE.md](./documents/USAGE.md) for annotated examples, and
+[POLICY.md](./documents/POLICY.md) for the policy coroutine protocol and semantic
+equivalence assumption.
 
 ## Install
 
@@ -46,9 +48,9 @@ entries.
 > stalk at `("transfer", ...)` might contain one.
 
 **Policy** — An `async function*` coroutine that yields candidates from a
-multi-candidate stalk in preference order. See [LIFT.md](./LIFT.md) for the
-coroutine protocol, `PolicyContext`, and the semantic equivalence assumption
-required of all policies.
+multi-candidate stalk in preference order. See [POLICY.md](./documents/POLICY.md)
+for the coroutine protocol, `PolicyContext`, and the semantic equivalence
+assumption required of all policies.
 
 At dispatch time, metadata is decomposed into **constraints** (keys with the
 same value across every candidate — topologically determined, not a choice) and

packages/sheaves/documents/INTRODUCTION.md

@@ -0,0 +1,85 @@
+# What a sheaf is
+
+`@metamask/sheaves` lets you stitch a single dispatch surface from a
+collection of capabilities that _ought to_ do the same thing — even when
+they don't literally share an implementation.
+
+This doc explains the problem the sheaf solves and when you'd reach for one.
+
+## Attenuation: the ocap baseline
+
+In object-capability programming, you restrict authority by **attenuating** a
+capability: wrapping it in a proxy that exposes a strict subset of its powers.
+A `FileSystem` capability becomes a `Read("/home/alice")` capability by
+wrapping it in something that forwards only read operations under
+`/home/alice` and refuses everything else.
+
+The attenuator never adds authority. An attenuated capability is a narrower
+projection of the same underlying object.
+
+## Strict attenuations compose for free
+
+When two capabilities are strict proxy attenuations of the **same** base,
+their overlapping surfaces necessarily agree — both forward to the same
+underlying implementation, so behavior is identical wherever their scopes
+intersect.
+
+Composition is then a matter of bookkeeping. If `aliceCap = Read("foo/bar")`
+and `bobCap = Read("foo/baz")` are both attenuations of the same
+`FileSystem`, their union is `Read("foo/{bar,baz}")`. Where the scopes
+overlap (here: the `foo/` prefix), the shared base ensures coherent behavior
+— there is nothing to reconcile.
+
+This is the easy case, and the one ocap programming is built around.
+
+## Sheaves: alignment without a shared base
+
+Often you want to behave _as if_ you had a common base when you don't. Two
+implementations of a wallet API; a local exo and a remote capability over
+CapTP; replicas with different cost profiles. No shared origin to inherit
+alignment from — but the surfaces are supposed to mean the same thing, and
+the caller wants a single capability that routes invocations to whichever
+provider is right.
+
+A **sheaf** is the construction that lets you assert this alignment by
+contract instead of proving it by attenuation. You hand `sheafify` a set
+of providers — each a capability with a guard describing the open set of
+invocations it supports, plus optional metadata distinguishing it from its
+peers — and you get back an authority manager that glues these pieces into
+a single dispatch surface.
+
+The alignment is the load-bearing assumption (the **sheaf condition**):
+two providers that both cover the same `(method, args)` point are presumed
+to produce equivalent observable effects. The system trusts that contract;
+that trust is what makes the framework work without a literal shared base.
+
+## The dispatch surface is a section
+
+What you get back from the sheaf is a **section** — a capability covering
+some open set of the combined surface, restricted by an explicit guard:
+
+```ts
+const sheaf = sheafify({ name: 'Wallet', providers });
+const userFacing = sheaf.getSection({ guard: userGuard, lift: policy });
+```
+
+`getSection` is itself attenuation: it takes the full combined surface that
+the sheaf has glued together and hands back a narrower view restricted by
+`userGuard`. The sheaf has done the hard part — asserting alignment so the
+providers can be treated as one — and `getSection` carves a slice out of
+that unified surface for the caller. The result is that you can attenuate
+a composition of capabilities the same way you would attenuate a single
+one.
+
+The guard determines what is invokable through `userFacing`. Anything
+outside the guard is simply not in the interface — there is no extra
+authorization step, no access check. Unauthorized invocations are
+unsupported in the same flat sense that calling a missing method on any
+ocap is unsupported.
+
+Where multiple providers cover the same invocation, a caller-supplied
+**policy** selects which one runs (see [POLICY.md](./POLICY.md)). Where
+exactly one covers it, the choice is forced. And because the returned
+section is itself a capability, it can be a provider to another sheaf —
+the construction composes with itself. See [USAGE.md](./USAGE.md) for
+worked examples.