@mnstry/atelier 0.2.0-alpha.13 → 0.2.0-alpha.15

package/docs/reference/edge-policy.md

@@ -0,0 +1,151 @@
+# Experimental edge policy adapter
+
+This additive module computes eligibility over repository-owned source records
+and signed decisions. It is not a new ontology canonical, key registry, identity
+provider, access host or source writer. No CLI, browser endpoint, root export or
+existing graph/proposal behavior changes. Import the modules within an admitted
+source integration; this experimental seam is not a published package subpath.
+
+## Authority reused
+
+Repository sources and the existing graph vocabulary own declarations and
+identity. Federation supplies `{repoId,localId}`; local titles, aliases and root
+commits do not establish repository identity. The adapter reuses the existing
+`attestation/jcs.mjs` RFC8785 canonicalization and `attestation/sign.mjs` detached
+signature verification. Existing collaboration proposals remain copy-only.
+Local review artifacts and boundary actor delegations remain attribution-grade;
+they cannot stand in for authenticated steward approval.
+
+Koiné contribution acceptance is unchanged. Withdrawing an edge's eligibility
+does not withdraw or mutate an accepted Koiné proposal. Hosts retain their
+existing proposal, receipt, withdrawal and source-owner incorporation paths.
+This public adapter has no dependency on Koiné, a private bridge or MNSTRY.
+
+## Record and decision contract
+
+`contract.mjs` validates closed experimental shapes. `edgeIdentity(record)` is
+the full RFC8785 SHA-256 of the immutable record, prefixed `edge:`. These are
+projection identities, never replacements for source node or repository IDs.
+
+An edge record has:
+
+- `schema: 'atelier-edge-record@experimental-v1'`, `family`, `subject`,
+  `predicate`, `object`, and `qualifications[]`;
+- `home: {repoId,path,readership}`, `origin`, and `supports: [{id,source}]`;
+- `policyDigest`, `proposalRef` and `sourceChange` (nullable only where review
+  is unnecessary). `sourceChange` preserves `{repoId,path,baseRevision,
+  diffDigest,reviewRef}` for the source owner's normal diff/PR path.
+
+Each source reference contains `{repoId,path,revision,fileDigest,
+locator:{byteStart,byteEnd},citedDigest}`. Byte offsets are zero-based with an
+exclusive end. File and cited-span digests cover the exact raw bytes, without
+normalization. A revision is the producer's exact snapshot revision, including
+dirty-tree scope when applicable. Adapters must preserve the federation's raw
+file digest separately from its normalized text digest. A pointer-only location
+must be resolved to an exact raw-byte range before admission; do not guess a
+range from reserialized front matter or JSON. Unknown, changed or absent sources
+stay pending/stale. The origin occurrence is always retained along with every
+support occurrence, even when two occur in the same file.
+
+Families remain separate:
+
+| Family | Meaning while eligible | Required review |
+| --- | --- | --- |
+| `hyperlink` | Navigation with predicate `links-to` | No semantic approval is claimed. Exact extracted origin and safe home remain required. |
+| `source-declaration` | Native source relation | Same-repository declarations need no invented review. Every cross-repository declaration needs governed review. |
+| `reviewed-assertion` | Policy-reviewed semantic assertion | Home-owner and applicable endpoint-steward review, followed by home-owner acceptance. |
+
+The default policy rejects proposer self-review and a common steward for two
+repository endpoints unless explicitly delegated by the trusted policy. Policy
+is `{version,allowProposerReview,allowSharedSteward}`; its full digest is pinned.
+Policy values come from the host, never the record. The version is a receiving
+host's existing policy reference, not an admitted shared policy canonical.
+
+Decisions use `atelier-edge-decision@experimental-v1` with `recordDigest`,
+`sequence`, `previousDigest`, `action`, `actorId`, `at`, `policyDigest`, `reason`,
+`roles[]` and the existing detached `signature` shape. Sign with the existing
+`signDocument` procedure; private keys stay in the host's existing custody.
+Approval roles are `{repoId,role:'home-owner'|'endpoint-steward'}`. The host
+binds each role to its current actor. One verified actor may approve several
+explicitly delegated roles, but a signature alone never creates that delegation.
+This adapter's roles are repository-scoped. Conflicting endpoint steward IDs
+inside one repository refuse instead of dropping one required review. A host
+with finer resource stewardship needs an explicitly admitted mapping before use.
+
+The chain begins with `propose`, followed by required `approve` decisions and
+`accept`. The adapter derives `draft`, `awaiting-endpoint-review`, `active`,
+`rejected`, `suspended`, `withdrawn` and `superseded` states. Changed citations
+derive `stale`. Rejection, suspension, withdrawal and supersession are terminal
+for that immutable chain. Revalidation/correction requires a new record and
+ordinary source review; no accepted record, evidence pin or event is overwritten.
+Retain all original records and chains in their safe source home. This module
+does not persist, compact or modify them.
+
+## Trusted host ports
+
+Call `await evaluateEdge({record,events}, host)` only after the access composer
+has current recipient grants for the home, both endpoints and every source.
+Evaluation is eligibility, not an ACL verdict. The host must maintain one
+coherent current snapshot throughout the call. It supplies:
+
+| Port / value | Required behavior and result |
+| --- | --- |
+| `policy`, `now`, `bindingId` | Current trusted policy, trusted ISO time and the access lane's current principal/grant/source snapshot binding. Never a browser assertion. |
+| `readRecordHead({edgeId,recordDigest})` | Read the actual source home and complete current log head; return `{recordDigest,eventCount,eventDigest}`. Last-event digest is null only for an empty log. A caller's truncated history cannot replace the stored head. |
+| `verifyOrigin({record,edgeId,recordDigest,policyDigest})` | Verify the exact extracted origin family, triple and occurrence against the source contribution, or the exact reviewed assertion source record; return `{recordDigest,bindingId,matches:true}` only on a match. Hashes alone do not prove that a link or relation actually declares this triple. |
+| `checkSourceHome({record,edgeId,recordDigest,policyDigest})` | Check the home's entire intended readership can know every endpoint and provenance field, including evidence, qualifications, proposal/PR references and actor identities. Return `{recordDigest,policyDigest,bindingId,allowed:true}` only when safe. A current reader's larger access does not make a broad shared home safe. |
+| `resolveEndpoint(ref)` | Exact current source identity, not an alias or external prefix; return `{ref,current:true,stewardId}`. Deleted/migrated identities refuse until explicitly revalidated. |
+| `resolveHomeOwner(repoId)` | Current source-home ownership: `{actorId}`. |
+| `readSource(source)` | Read that exact current authorized raw file, returning `{revision,bytes:Uint8Array}`. Recheck exact revision, file digest, byte bounds and cited bytes. Never silently replace pins. |
+| `resolveActorKey({actorId,keyId,at})` | Use the existing trusted host registry to bind the exact actor/key and current revocation state: `{actorId,publicKey,revoked:false,notBefore,expiresAt}`. `publicKey` is the existing `verifyDocument` public-key document. The key must cover the decision time and remain valid now. Never accept a caller-supplied key registry. |
+| `authorizeDecision({event,record,required,policyDigest})` | Verify current action/role scope, principal/key rights and revocation. Return `{eventDigest,policyDigest,bindingId,allowed:true,revoked:false,notBefore,expiresAt}` bound to that exact signed event and policy. Historical or expired rights cannot sustain an active edge. |
+
+Missing ports, exceptions and malformed results fail closed. Key/reviewer/grant
+changes, stale policy, missing endpoints, unsafe homes and invalid chains never
+remain eligible. Port implementations are host-specific acceptance obligations;
+synthetic test hosts do not qualify an actual Git provider or shared service.
+
+## Composer and projection seam
+
+The immutable evaluation result contains `edgeId`, `recordDigest`, `policyDigest`,
+`state`, `eligible`, `family`, `triple`, `supportRefs`, `reviewRefs`,
+`qualifications`, source-owner handoff and full signed `history`. Failed
+verification can return only a generic suspended result. This is an **owner
+audit** object, not a response for an arbitrary reader.
+
+`displayEligibleEdge(result)` accepts only an original in-process evaluated
+eligible result. Deserialized or fabricated `eligible:true` objects are refused.
+It returns `{edgeId,source,target,predicate,family,acceptanceState,assurance,
+supportRefs,sourceRef,reviewRefs,qualifications,recordDigest,policyDigest,
+verification:{checkedAt,bindingId}}`, with evidence and review references only.
+`sourceRef` is the origin's evidence ID. Each evidence occurrence has a
+content-bound ID namespaced to its assertion and original occurrence ID;
+evaluation `supportRefs` retain the actual exact source refs for the authorized
+evidence adapter. No raw decision body, source path, diff or private key reaches
+the display shape. Evidence rows must undergo the access lane's own disclosure
+filter before serialization.
+
+The access host evaluates again for each new delivery and validates the binding
+at use time. Do not persist eligibility decisions as reusable authority or serve
+a cached result after a grant/source change. In-process provenance is a guard
+against accidental data promotion, not a security sandbox against malicious
+code executing inside the trusted host.
+
+`groupEligibleEdges(results)` is an optional view grouping helper. It retains
+every distinct assertion with all support occurrences and signed history,
+orders deterministically, refuses conflicting results and never merges families
+or qualifications. It only accepts evaluated results already authorized for one
+reader in one host snapshot. Group output is also owner/audit data; renderers
+consume bounded display edges, retaining distinct edge IDs for the same triple.
+The helper explicitly refuses mixed binding IDs or policy digests.
+
+## Verification and integration limits
+
+Run `node --test test/edge-policy.test.mjs`. Fixtures generate ephemeral signing
+keys at runtime and use synthetic repositories, observations and actors. They
+verify the control's refusal behavior without touching a live provider.
+
+The graph builder, collaboration stores, Koiné operations, public package
+exports, current host bindings, shared-view access service and source-owner Git
+application are separate receiving work. Neither a local test pass nor a signed
+decision proves deployment, human acceptance or source incorporation.

package/docs/reference/graph-view-structured.md

@@ -0,0 +1,119 @@
+# Structured graph explorer
+
+The structured explorer is a browser DOM consumer of `atelier.graph-view@v1`.
+It provides record search, keyboard navigation, a directed relationship table,
+questions, diagnostics and a shared evidence inspector without WebGL. It emits
+presentation intents; it does not read repositories, accept assertions, perform
+access checks, or create source records.
+
+## Host integration
+
+The source entry is `src/graph-view/structured/browser.mjs`:
+
+```js
+const explorer = mountStructuredGraphView(element, {
+  view: authorizedView,
+  selection: { projectionDigest: authorizedView.projectionDigest, ref },
+  onIntent: handleIntent,
+})
+explorer.update({ view: nextAuthorizedView, selection: nextSelection })
+explorer.clear()
+explorer.destroy()
+```
+
+This source seam is awaiting a package export and a consuming browser host.
+A source import or local test does not establish published package availability.
+The host validates the complete versioned envelope and digest before delivery.
+The component checks its required presentation shape, copies received values,
+and presents source text as inert DOM text. It is not a browser authorization
+control. Never deliver a combined graph and ask this component to hide denied
+records. The access and projection owners must remove denied topology before
+any bytes, counts, diagnostics, source references or cursors reach the browser.
+
+`onIntent` receives the producer's digest-bound intents: `select` with exactly
+one qualified `ref` or `edgeId`; `openEvidence` with an `evidenceId`;
+`setQuestion` with a `questionId`; and `expand` with a qualified `ref` and
+`direction` of `in`, `out` or `both`. Qualified refs use `{repoId, localId}`.
+The component uses the producer's browser-safe intent validator. The host revalidates current grants and source before handling an intent.
+Selection is controlled by `update`; a request never optimistically accepts an
+assertion or changes source. Focus and selection are separate. Keyboard arrows,
+Home and End move list focus; Enter or Space requests selection.
+
+Host selection is `{projectionDigest, ref|edgeId|evidenceId|questionId}` with
+exactly one target available in the delivered slice. Stale or unavailable
+selection is cleared without rendering its identity or a placeholder.
+Host updates preserve focus where the corresponding control remains available.
+If it disappears, focus moves to the inspector. Search applies only to the
+records already delivered, and it is labelled accordingly.
+
+On grant loss or withdrawal, call `clear()` immediately and discard host caches.
+The component clears source pins, controls, search text and selection. A late
+intent callback cannot update the component's status after withdrawal. The host
+must also cancel or reject stale query results and must not call `update` with
+previously withdrawn bytes. `destroy()` removes the entire mounted DOM and
+releases the mount reservation; no global listener or transport was installed.
+
+## Provenance and honest states
+
+Each relationship retains its producer `edgeId`, direction, predicate, family,
+assurance and acceptance state. Equal endpoint/predicate triples remain separate
+rows. Origin and support IDs resolve into authorized evidence records, including
+repository, path, exact source revision, content digest and structured locator.
+Review receipt digests, policy/record digests, qualifications and check time
+are displayed as supplied. An active source-declared edge is not labelled a
+reviewed assertion. No source passage is invented when a view supplies only pins.
+
+The initial producer fixture provides no edge currency field. The inspector
+therefore says that staleness is not supplied and must not be assumed current.
+It displays each support record's independent verification state. A host can also pass `refreshStatus` from the existing refresh controller's read result. A stale source view and rebuild failure receive explicit labels, including in the edge inspector; arbitrary failure details are never echoed. Selection updates for the same projection preserve that status, and a new projection or withdrawal clears it. A verification
+check time is not a currentness guarantee. Explicit edge currency remains a
+producer dependency.
+
+Questions retain coverage, gaps, omissions and supporting/contradicting evidence.
+An abstention states that the sources do not establish an answer. Authorized
+diagnostics remain visible with record and evidence controls. A bounded view
+states its truncation and omitted counts; search and counts never imply whole-corpus completeness. A host may supply onPage({projectionDigest, cursor}) to receive the visible Load next page control. Without a cursor, the view explains that a broader host query is needed.
+
+## Acceptance and limits
+
+Run the opt-in network-blocked proof using the repository's locked Playwright
+runtime and an installed Chromium. It does not download browsers or start a
+service:
+
+```sh
+ATELIER_STRUCTURED_BROWSER_PROOF=1 node --test test/graph-view-structured-browser.test.mjs
+```
+
+The default shared fixture is `fixtures/graph-view/synthetic-view.v1.json`, owned
+by the projection lane. `ATELIER_GRAPH_VIEW_FIXTURE` may select its exact received
+file before the producer dependency lands. The test independently verifies the
+fixture digest and records the file hash. `ATELIER_STRUCTURED_PROOF_OUTPUT`
+selects the output directory; the default is `output/playwright/graph-structured`.
+
+The proof exercises question/source/relationship/contradiction tasks, abstention,
+qualified identity, repeated-edge provenance, keyboard selection and independent
+focus, native accessibility-tree semantics, touch without dragging, 44px targets,
+forced colors, reduced motion, 320px reflow, 200% CSS layout zoom, WebGL disabled,
+withdrawal, failed/late delivery and disposal. CSS layout zoom supplements the
+manual browser zoom test; it is not a claim of operating-system magnification.
+Automated accessibility-tree inspection is not a human screen-reader result.
+
+Before human acceptance, use the same reserved unseen task in the Babylon host
+and structured explorer: locate a question, inspect a source, traverse a directed
+relationship, recognize a contradiction or missing support, and explain the next
+decision or abstention. Retain exact source/projection/browser identities. Run
+keyboard only, a named screen reader, actual browser zoom at 200%, high contrast,
+reduced motion, touch without dragging and WebGL disabled. Record correctness,
+source trace, wrong turns and time separately. Keep A-only and A+B host views
+separate; the A-only participant must receive no clue that B exists. A local
+synthetic consumer test does not qualify that access boundary or pass an unseen
+human task. The cohort validation owner retains that acceptance work.
+
+## Reused authority
+
+Source records and predicates remain governed by `src/graph/knowledge-graph.mjs`.
+Questions and expected evidence remain knowledge-plan projections. Graph-view
+owns the qualified identity, envelope and intent contract; the host owns access
+and delivery. Existing presentation semantics distinguish focused and selected
+state. This component adds a presentation seam, not an ontology canonical or a
+second authoring desk. Babylon scene and lifecycle remain with its owning lane.

package/docs/reference/graph-view.md

@@ -0,0 +1,139 @@
+# Renderer-neutral graph view
+
+`atelier.graph-view@v1` is an additive, bounded JSON projection for independent
+renderers. The source graph, repository identities, knowledge plan, edge policy
+and consuming host retain their respective authority. The existing `atelier graph`
+artifact and knowledge outputs remain unchanged. This module does not extract
+sources, verify grants, admit assertions or fetch source bodies.
+
+The implementation lives in `src/graph-view/index.mjs`; package export and shared
+CLI dispatch adoption require the owning program's separate integration. No
+published release or hosted permission implementation is established by this source.
+The schema is `contracts/atelier-graph-view.v1.schema.json`. Optional epoch
+`contractVersion` and empty `ext` containers follow existing schema conventions;
+nonempty request/output extensions are unsupported at this boundary. The two fixtures under
+`fixtures/graph-view/` are invented data, not access grants or provider receipts.
+
+## Host binding
+
+The host creates a reader with closures over its actual authenticated context:
+
+```js
+const reader = createGraphViewReader({
+  loadAuthorizedGraph: options => access.loadAuthorizedGraph(trustedContext, options),
+  revalidate: binding => access.revalidate(binding),
+})
+const view = await reader.readGraphView({ focusRef, direction: 'out', depth: 1, limit: 50 })
+const bytes = await reader.exportGraphView({ snapshot: view.snapshot, limit: 50 })
+```
+
+The loader returns `{graph,binding}`. Only the already-authorized graph enters the
+query. The binding stays private and is revalidated after preparation, immediately
+before return, including when query preparation fails. Expired or revoked bindings
+refuse delivery. Host failures produce fixed errors without raw exception details.
+No cache exists here. A receiving host still owns current access checks, output
+transport, separately authorized evidence reads, and clearing previous views after
+access changes. Parsing an existing file does not authorize reading or sharing it.
+
+Browser requests cannot supply `readerScope`, identity, grant data, a graph payload
+or a host binding. Unknown request fields refuse. The trusted access adapter is
+responsible for excluding denied repositories, nodes, edge homes, endpoints,
+evidence, text, diagnostics and suggestions before the serializer is called.
+Closed serialization removes body fields, raw relations, arbitrary extensions,
+principal identity and private edge binding IDs. It cannot detect confidential
+information embedded inside metadata that an upstream host incorrectly admits.
+
+## Projection and provenance
+
+Qualified references are `{repoId,localId}` from the source owner. Two repositories
+with the same local identifier remain distinct. A source pointer is
+`{repoId,path,revision,digest,locator?}`. `revision` is the exact repository snapshot
+digest, including dirty bytes; `digest` is the file's raw-byte digest. Both are
+`sha256:` followed by 64 lowercase hex digits. A locator retains the source owner's
+`pointer`, half-open `range`, and/or `targetRange`; ranges preserve text offsets and
+optional raw-byte offsets. Optional `rangeDigest` preserves the source producer's
+digest of the exact raw byte slice in `locator.range`. No passage or full body is included.
+
+`sourceSnapshot.repositories` preserves each delivered source snapshot's repo id,
+HEAD, tree, dirty observation, scope and full snapshot digest. Its file list contains
+only source pins needed by this slice; `omittedFiles` reports the other authorized
+files. `inputs.config` and `inputs.plan` are exact verified source pointers or null;
+no global config or plan pin is invented. The full snapshot digest still identifies
+the complete input observation. An approved but unavailable repository has no
+invented snapshot: `completeness` becomes `incomplete`, with one fixed authorized
+unavailable diagnostic. Denied repositories have no placeholders or count effects.
+
+Distinct edges retain `edgeId`, qualified directed endpoints, native predicate,
+family, assurance, active admission state, every support and review reference,
+qualifications, and record/policy digests. Families are `hyperlink`,
+`source-declaration`, and `reviewed-assertion`. An edge's `sourceRef` is its origin
+**evidence ID**, included in `supportRefs`; node/evidence `sourceRef` is the source
+pointer object. Equivalent triples are not merged. Supporting evidence pointers
+must all be present for an emitted edge. This projection does not infer review,
+semantic acceptance or continuing currency. Optional `verification.checkedAt` means
+verified at that time; absence means unavailable. A live currency claim requires
+an actual current host binding.
+
+Questions preserve decision, node/evidence refs, contradicting evidence refs,
+coverage (`supported`, `partial`, `abstain`, `unknown`), omission state and modeling
+gaps. Bounded node omissions are labelled on the question. An explicit abstention
+can have no sources. The current access adapter supplies no question records;
+an authorized knowledge-output binding is a separate receiving dependency.
+
+## Requests, bounds and determinism
+
+`readGraphView` and `exportGraphView` accept only `snapshot`, `questionId`,
+`focusRef`, `relationFilter`, `direction` (`in`, `out`, `both`), `depth`, `limit`,
+`cursor` and metadata `search`. Search covers title, summary and tags. Focused
+queries traverse admitted directed edges, with optional native predicate filters.
+Questions select their declared source refs. Incoming focus expansion supplies
+source-impact navigation; edge supports supply the pointer path to evidence.
+
+Depth is at most two. A page contains at most 500 nodes (default 100), 2,000 edges,
+4,000 evidence pointers, 100 questions and 500 diagnostics, and canonical output
+is at most 2 MiB. Hosts may lower node/depth limits. An individual record exceeding
+the closed schema or an unrepresentable evidence closure refuses rather than
+silently trimming provenance. File paths are portable relative paths. Queries
+consume at most 20,000 input records in each table; the host owns source loading
+budgets. Camera state, temporary clusters and visual coordinates are not graph data.
+
+Ordering uses stable qualified refs and identifiers. Set-valued metadata is sorted.
+The existing RFC 8785 serializer supplies canonical JSON. `projectionDigest` hashes
+the entire payload with only that field excluded; exported bytes add one newline.
+`snapshot` hashes the complete normalized authorized input, including access context,
+source pins and producer version. Same inputs/request produce identical bytes.
+Source or grant changes invalidate requested snapshots and cursors. Cursors are
+opaque pagination recipes bound to that snapshot and query; they grant no authority.
+
+`page.returned` counts emitted records. `page.omitted.nodes/edges` counts records
+from the authorized matching query absent from this page; other omitted counters
+refer to the authorized input universe. Counts include records on other pages and
+never denied records. `nextCursor` pages nodes; cross-page edges are intentionally
+omitted because both endpoints must be in the emitted slice. Use focused expansion
+to inspect a particular relationship. `truncated` means any authorized records were
+omitted; an exhausted node cursor alone does not imply all related data was emitted.
+
+## Consumer intents and command adapter
+
+The browser-safe `src/graph-view/intents.mjs` exports `assertGraphViewIntent`.
+Every intent binds `projectionDigest`. `select` carries exactly one `ref` or
+`edgeId`; `expand` carries `ref` and `direction`; `openEvidence` carries `evidenceId`;
+`setQuestion` carries `questionId`. `compareSnapshots` carries two snapshot digests;
+`proposeModelChange` carries a draft ref and requires the host-advertised capability.
+Validation returns data only; it performs no action and confers no write rights.
+Focus and selection remain consumer state. A stale-sensitive host operation must
+revalidate current source/access even when an intent passed structural validation.
+
+`runGraphViewCommand(argv,{reader,...io})` is a host-injected CLI adapter. `--request`
+reads a closed query and `--out` writes an authorized export to a new file with
+exclusive creation and private permissions; existing files are never overwritten.
+Without a bound reader, export refuses. The local fixture validator runs as:
+
+```sh
+node src/graph-view/cli.mjs --validate fixtures/graph-view/synthetic-view.v1.json
+```
+
+Validation prints only a fixed success label; it cannot write or re-export the file.
+`parseGraphView` verifies schema, digest and reference closure, and
+`serializeGraphView` emits canonical bytes. These functions verify a transport
+contract, not host grants, provenance authenticity, semantic acceptance or live ACLs.

package/docs/reference/graph-workspace.md

@@ -0,0 +1,37 @@
+# Graph workspace reference
+
+Two package subpaths. The first is pure and runs anywhere; the second needs a browser and injected renderer packages.
+
+## `@mnstry/atelier/graph-workspace`
+
+| Export | Purpose |
+| --- | --- |
+| `buildWorkspaceModel({ graph, plan?, zoneRule?, summaryLength? })` | Read model `atelier.graph-workspace-model@v1` from an `mnstry.atelier-knowledge-graph@v1` graph and optional knowledge plan. Refuses duplicate ids and other schemas. |
+| `zoneOf(path, rule)`, `validateZoneRule(rule)`, `ROOT_ZONE` | Zones from folders: `{ prefix, depth (1–4), labels, rootLabel }`. Records outside the rule share the zone `ROOT_ZONE` (`'/'`), which no folder can be. |
+| `edgeClass(type)`, `EDGE_CLASSES` | `related` → `link`, `belongs_to` → `containment`, others → `relation`. |
+| `neighbours(model, id)` | Neighbour ids in either direction. |
+| `seedPositions`, `layoutWorkspace(model, { Graph, forceAtlas2, seed?, iterations?, settings? })`, `normalizePositions`, `LAYOUT_WEIGHTS` | Deterministic zone-seeded ForceAtlas2 layout (injected), normalised to a 1,000-unit frame. |
+| `zoneGeometry(model, { cell? })` | Density blobs and a label anchor per zone. |
+| `planConstellation(model, budget?)`, `DEFAULT_BUDGET` | `records` or `zones` mode for the whole view. |
+| `aggregateZones(model)` | `atelier.graph-workspace-zones@v1`: counts by zone and type, directed bundles by edge class, coverage. |
+| `zoneSlice(model, zoneId, { limit })` | Bounded sub-model. `slice` reports `linksTouchingZone` = drawn + `omittedLinksInsideZone` + `linksToOtherZonesCount` + `omittedLinksToOtherZones`, with `linksToOtherZones` per zone. `coverage.byClass` counts the drawn links. Plan concepts keep only kept declaring records, with `omittedDeclarations`. |
+| `rankRecords(model)` | Records by connection count, then title. |
+| `placeLabels({ candidates, measure, width, height, reserved?, budget?, threshold? })` | Collision-free label placement with four slots per label. Pure. |
+| `labelThreshold(ratio, boost?)`, `labelBudget(width, height, ratio, boost?)`, `overlaps` | Defaults for zoom-dependent label density. |
+| `DEFAULT_RECIPES`, `composeRecipes({ atelier?, coach?, owner? })`, `validateRecipe`, `availableRecipes(recipes, model)` | Layered recipes with per-field provenance (`setBy`). Rooms: `constellation`, `workbench`, `review`; lenses (constellation only): `question`, `concept`, `zone`; subjects (workbench only, required there): `record`, `concept`, `relation`; primary actions (`PRIMARY_ACTIONS`): `search`, `open-evidence`, `next-step`, `walk`, `review`, `pick`, of which `primaryActionsFor(recipe)` names those the shell honours in a recipe's room (review: `review`; workbench: `next-step`, or `walk` for a record; zone lens: `pick`, `search`; question or concept lens: `open-evidence`, `pick`, `search`; no lens: `search`). `composeRecipes` throws on any other combination; `availableRecipes` drops recipes the model cannot run (concept, relation or question work without them in the plan, a review without concepts, a zone lens without zones, a record subject without records). |
+| `DEFAULT_THEME`, `composeTheme(base, ...layers)`, `validateTheme`, `contrastRatio` | `atelier.graph-workspace-theme@v1`, night (dark) by default with a paper (light) scheme. Every layer is checked before and after composing. Each CSS custom property has a declared type (colour, font list, length, shadow, duration, easing), so URLs, `image-set()` and other resource loads are refused, as are unknown fields, schemes and tokens. `--canvas` must equal `graph.canvas`; interface text must reach 4.5:1 on the canvas and surfaces, and on `--surface-glass` composited over the canvas and `--surface-2`; labels need 7:1 and zone colours 3:1. |
+| `conceptSteps`, `relationSteps`, `guideConcept`, `guideRelation`, `stepState`, `readiness(plan, store, readableIds)` | Focused authoring steps and structural guidance. `readiness` needs the `Set` of record ids this reader can open; for concepts and relations alike, missing or unreadable evidence and a missing disconfirming case are errors, so `ready-for-human-review` means every step is complete and every citation is readable here. |
+| `createDraftStore({ storage, key, identity, persistence?, delayMs? })`, `memoryStorage()` | Drafts behind a storage port `{ getItem, setItem, removeItem }`, saved in an `atelier.graph-workspace-draft@v1` envelope bound to `identity` (`{ workspace, ...scope }`); a draft saved under another identity is never restored. `persistence` is `tab`, `browser` or `host`. Status: `empty`, `restored`, `saving`, `saved`, `unavailable`. |
+| `fingerprintsFrom({ graph?, plan?, names?, extra? })`, `scanForFingerprints(files, fingerprints)` | Shareable-content gate with masked findings. |
+
+## `@mnstry/atelier/graph-workspace/browser`
+
+| Export | Purpose |
+| --- | --- |
+| `mountGraphWorkspace(element, { model, deps, recipes?, theme?, scheme?, profile?, storage?, draftIdentity?, persistence?, draftKey?, initialRecipe?, intro?, webgl? })` | Default shell with the three rooms, command bar, display menu, question, concept and zone lenses, the recipe's primary action, selection card and Text view. Drafts stay in the tab unless `draftIdentity` or `profile.id` names the workspace; a host `storage` port requires one. Returns `{ state, recipes, store, constellation, workbench, select, openWorkbench, openReview, setRecipe, runPrimary, backToConstellation, toggleText, setScheme, readiness, destroy }`. One per document. |
+| `createConstellation({ container, model, palette, deps, font?, reserveSelector?, onSelect?, onHover?, onOpen? })` | The constellation room alone. `deps = { Sigma, Graph, EdgeArrowProgram, FA2Layout? }`. Elements matching `reserveSelector` (default `[data-graph-reserve]`) are kept free of labels. |
+| `createWorkbench(...)`, `renderReview(...)` | The other two rooms, for custom shells. |
+| `applyTheme(theme, scheme, element)` | Validate and apply a theme scheme as custom properties; returns the graph palette. |
+| `GRAPH_WORKSPACE_CSS`, `injectGraphWorkspaceStyles(document)` | Styles scoped under `.atelier-gw`, responsive by container size. |
+
+The opt-in browser acceptance test is `ATELIER_GRAPH_WORKSPACE_BROWSER_PROOF=1 node --test test/graph-workspace-browser.test.mjs`. It uses an invented fixture and makes no claim about human usefulness, screen-reader parity or a hosted deployment.

package/docs/{intake-and-guides.md → reference/intake-and-guides.md}

@@ -30,10 +30,9 @@ structure, missing-asset evidence, and format-specific completeness checks.
 Do not flatten a conversation export merely to satisfy a text-output API.
 Packet authoring can proceed before corpus ingestion.
 
-The [progressive ingestion proposal](progressive-ingestion.md) describes a
-possible coverage, routing and incremental-processing layer over this store.
-It is a design proposal; those orchestration capabilities are not supplied by
-the current intake API.
+The [local ingestion runner](../guides/ingestion.md) composes this store with selected-file
+planning, bounded deterministic extraction and lexical retrieval. The intake API
+itself supplies no connector census, provider routing or processing orchestration.
 
 ## Guides and private implementations
 

package/docs/{knowledge-graph.md → reference/knowledge-graph.md}

@@ -1,12 +1,17 @@
 # MNSTRY Atelier Knowledge Graph
 
-The Atelier knowledge graph is a local, Git-backed operating model for project
-source material. It is not a taxonomy and it is not runtime retrieval. It is a
-durable model of source nodes, evidence, relationships, diagnostics, and
-projection readiness.
+The Atelier Knowledge Graph is the shared, local, Git-backed representation of
+project source material: source nodes, evidence, relationships, diagnostics and
+projection readiness. It is not a taxonomy or runtime retrieval.
+
+Knowledge Stewardship is the broader responsibility governing knowledge inclusion
+and applicability. [Phronesis — practical judgment](phronesis.md) draws on this
+graph and contributes through the existing Knowledge review and activation
+routes. It creates no separate graph, store or canonical authority. Structural
+graph checks do not establish semantic acceptance, wisdom or a universal score.
 
 For setting up useful domain concepts and testing whether the graph helps answer
-work questions, follow [knowledge setup](knowledge-setup.md). It builds on this
+work questions, follow [knowledge setup](../start/knowledge-setup.md). It builds on this
 canonical source graph and keeps domain concepts, source types, semantic
 acceptance, and runtime authority distinct.
 
@@ -70,6 +75,115 @@ a schema-checked JSON sidecar is the trust boundary. Richer format adapters
 that derive metadata from asset contents belong to extension packs
 (`atelier-extension-pack.v1`), not the kit core.
 
+## A worked example
+
+The policy below is invented to show the shape. Once a body of work is
+authored, a policy file looks like this:
+
+```
+policy/expenses/approval.md
+---
+title: Expense approval policy
+summary: Version 3 of who approves an expense claim, with the limits it depends on.
+tags: [policy, expenses]
+kg:
+  id: example:policy:expense-approval
+  type: document
+  status: active
+  audience: team
+  relations:
+    depends_on: [example:limits:expense-approval-v3]
+---
+## Rule 4
+A claim up to the team limit needs one approver, the claimant's lead.
+A claim over the team limit also needs the department head.
+A claim over the department limit also needs the finance lead.
+A claim without a receipt is held: neither approved nor refused.
+```
+
+The limits live in their own file. The file itself is data a product reads:
+
+```
+policy/limits/expense-approval-v3.json
+{ "version": 3, "limits": { "team": 500, "department": 5000 }, "holdWhenReceiptMissing": true }
+```
+
+A sidecar beside it makes it a governed node, so the relationship between
+rule, limits and test cases is declared rather than remembered:
+
+```
+policy/limits/expense-approval-v3.json.kg.json
+{
+  "schema": "mnstry.source-sidecar@v1",
+  "asset": "expense-approval-v3.json",
+  "title": "Approval limits, version 3",
+  "summary": "Amount limits and the missing-receipt hold for the expense approval policy.",
+  "tags": ["policy", "limits"],
+  "kg": {
+    "id": "example:limits:expense-approval-v3",
+    "type": "manifest",
+    "domain": "example",
+    "lifecycle": "active",
+    "status": "active",
+    "audience": "team",
+    "relations": {
+      "implements": ["example:policy:expense-approval"]
+    }
+  }
+}
+```
+
+A sidecar carries `lifecycle` as well as `status` because the sidecar
+contract requires both; Markdown headers carry `status` alone.
+
+The test cases are a third source, a table of sample claims with the approvals
+they need, declared as evidence for the limits:
+
+```
+policy/cases/expense-approval-v3.md
+---
+title: Test cases, expense approval v3
+summary: Sample claims with the approvals each one needs under version 3.
+tags: [policy, cases]
+kg:
+  id: example:cases:expense-approval-v3
+  type: evidence
+  status: active
+  audience: team
+  relations:
+    evidences: [example:limits:expense-approval-v3]
+---
+| Claim | Receipt | Approvers |
+| --- | --- | --- |
+| 500 | yes | lead |
+| 1800 | yes | lead, department head |
+| 9000 | yes | lead, department head, finance lead |
+| 300 | missing | none yet; held |
+```
+
+From those headers the builder compiles three edges: the policy depends on the
+limits, the limits implement the policy, and the test cases evidence the
+limits. Ask an agent to revise Rule 4 and it follows those edges from the
+policy to the limits it depends on, and from the limits to the test cases that
+evidence them, then revises the affected files and runs the graph check against
+the result. The graph check refuses a header that names a node which does not
+exist, apart from configured external targets; what an export may include
+across audiences is stated in the README's audience-visibility block.
+
+To try it: the first line inside each fence above is the file's path relative
+to the workspace's `content/` directory, not part of the file. Copy a
+`fixtures/projects/sample-workspace`, save the lines after each path line as
+that file under `content/` (so the policy lands at
+`content/policy/expenses/approval.md`), then run
+`atelier graph --project ./atelier.project.json` from the copy. With all four
+files present the graph builds with no diagnostics, its edges include the
+three above, and
+`atelier graph --check` passes against the result. Remove the limits `.json`
+and the build is refused: the sidecar has no asset (`sidecar has no matching
+source asset`), and the two headers that name the limits no longer resolve.
+Point the policy's `depends_on` at an id that does not exist and the build is
+refused (`declared depends_on target ... was not found`).
+
 ## Census Rules
 
 Graph and projection walks skip git-ignored paths. A committed artifact must
@@ -89,7 +203,7 @@ treated exactly like a Git-ignored one (no node, no sidecar demand, no orphan
 error, no link or embed target). A sidecar follows its source. The scope is
 tracked for the same reason ignored paths are skipped: every machine must walk
 the same files. The rules and the decision behind them are in
-[install](install.md#scoping-what-the-graph-reads).
+[install](../start/install.md#scoping-what-the-graph-reads).
 
 `atelier enroll documents` writes the sidecar the census demands of every
 non-Markdown document that has none, as the smallest classification that