@mnstry/atelier 0.2.0-alpha.5 → 0.2.0-alpha.8

package/docs/portable-presentation.md

@@ -0,0 +1,328 @@
+# Portable presentation v1
+
+Status: opt-in implementation candidate, not a published or adopted interface.
+Contract discussion: [issue 39](https://github.com/MNSTRY/atelier/issues/39).
+Current corrections and remaining adoption conditions:
+[review disposition](presentation-review-disposition.md).
+
+## Placement and authority
+
+Atelier owns the domain-neutral presentation model, bounded validators, neutral
+tokens, reference views and proof mechanisms in this module. A host supplies
+meaning, capabilities, action references, data, business validation, persistence,
+operation outcomes and receipts. A renderer cannot promote a request into an
+operation, permission, accepted decision or publication.
+
+This implementation was independently derived from generic presentation
+requirements and public accessibility standards. The paper-shape fixture is
+invented. No client implementation, brand palette, information architecture or
+methodology was imported. The existing CLI, sidecar HTML helpers and unpublished
+control-grammar work are not replaced or silently adopted. This is a new optional
+subpath, not a second semantic interpretation or route-adoption authority.
+
+Source reservation: `src/ui/presentation/**`, the two presentation schemas,
+`fixtures/ui/presentation/**`, the presentation tests and proof/generation scripts,
+and this document. Package exports, pinned test-only dependencies, the local
+proof command, and contract-corpus entries are scoped shared-file hunks. No runtime, server, command catalog, existing UI
+helper, release guard, route, template or consumer source is changed.
+
+## API and host connection
+
+```js
+import { assertPresentation, renderPresentation } from '@mnstry/atelier/presentation'
+import { bindPresentation } from '@mnstry/atelier/presentation/browser'
+
+assertPresentation(model)
+container.innerHTML = renderPresentation(model)
+const binding = bindPresentation(container.querySelector('[data-ap-root]'), model, {
+  onRequest: request => host.receivePresentationRequest(request),
+})
+// Refresh the same presentation without losing drafts, focus or selection:
+binding.update(nextModel)
+// For a host-approved draft reset, use { discardDrafts: true } explicitly.
+// Before a genuine unmount or a change of presentation identity:
+binding.dispose()
+```
+
+`host` is a consumer-owned port, not a shipped implementation. Do not pass
+arbitrary HTML; only the validated renderer output is intended for insertion.
+Give simultaneously mounted models distinct IDs. Styles and DOM IDs are scoped
+by that identity. Callers embedding more than one workspace must supply an
+appropriate page-level landmark hierarchy; the document renderer emits a main
+landmark for one workspace.
+
+Required model identity is `schema: "atelier.presentation/v1"` and
+`version: "1.0.0"`. Optional `contractVersion` follows the repository's schema
+epoch convention; it is metadata, not an alternative version-negotiation path.
+Optional `ext` containers are retained, bounded plain JSON and never interpreted,
+rendered or used to authorize an action. Unknown ordinary fields and unsupported
+versions refuse. Validation, serialization and parsing share a 1 MiB UTF-8 limit
+on the canonical model; parsing also bounds the incoming bytes (including extra
+whitespace). Canonical serialization does not mean signing or acceptance.
+
+All callback requests carry `schema: "atelier.presentation-request/v1"`,
+`version: "1.0.0"`, `presentationId`, `status: "proposed"`, and
+`executionAuthority: false`. Kinds and payloads:
+
+| Kind | Payload | Host obligation |
+| --- | --- | --- |
+| action | `id`, opaque `actionRef`, optional `presentationConfirmed: true` | Resolve current permission, operation and final outcome independently |
+| selection | `id`, `itemId` | Return authoritative selection; do not infer persistence |
+| resize | pane `id`, bounded percentage `value` | Apply current host geometry rules and return the next model |
+| edit | field/editor `id`, string `value` | Maintain local draft promptly; validate and persist through existing authority |
+| move | sequence `id`, `itemId`, zero-based `position` | Recheck eligibility and current ordering; apply only through the host |
+| navigation | native `id`, `paneId`, or `itemId` and local `href` | Resolve host navigation and focus; never create a global shortcut bridge |
+
+Callback resolution confirms delivery only. Rejection reports delivery failure,
+not business refusal or rollback. Both projections use one delivery-message
+function: each settlement describes its own outcome and identifies other pending
+requests; an unrelated earlier failure cannot relabel a later successful delivery.
+Repeated pending actions are suppressed without
+disabling the focused web control. Every valid edit is delivered synchronously to
+the host callback, including during earlier async delivery; there is no hidden
+coalescing queue to lose at unmount. The host must capture drafts on callback
+entry and order acknowledgements through its existing concurrency mechanism.
+Out-of-order persistence responses must not replace a newer accepted host state.
+Unmount removes scoped
+listeners and pending visual flags but cannot cancel a callback already delivered
+to a host. Host operations therefore need their own concurrency, idempotency,
+authorization and outcome-recovery controls. Use `binding.update(nextModel)` for
+same-ID refreshes: it closes obsolete confirmations, preserves surviving control
+focus/selection, and retains each draft until the model acknowledges that value.
+Removed nodes and changed input kinds lose their local drafts. A same-ID host reset must explicitly pass
+`discardDrafts: true`; a different document must use a new presentation identity.
+During IME composition, updates validate immediately and retain only the latest
+valid model without replacing the composing DOM. `isComposing` and
+`hasPendingUpdate` expose this lifecycle. On `compositionend`, the final draft
+is delivered before applying that model; a synchronous newer host update wins.
+Removal, disable, input-kind change or `discardDrafts` in the queued model
+suppresses the obsolete edit. Other widget requests wait without dispatch while
+an update is queued. Disposal clears the queue; it is not durable draft storage.
+Email/number fields retain the same focused input element on compatible refresh
+because those types expose no selection API. A host reset or input-kind change
+does not promise caret continuity. Token overrides must be supplied again on
+update if used.
+Dispose/re-render is an unmount, not the controlled-update path. The native
+component must be keyed to its model identity; its host resets use a React key
+change, and draft acknowledgement follows the same value-matching rule.
+
+The edit limit is 32,768 Unicode code points, matching the schema rather than
+UTF-16 code units. Over-limit or incomplete Unicode input remains visible locally
+with an error and is not sent; it is never silently shortened. Web composition
+is evaluated when composition ends. Local drafts are not durable persistence.
+
+The module installs no transport, storage, process, global keyboard handler,
+telemetry, hosted account, command registration or navigation service. Web links
+are local paths or fragments and use ordinary browser navigation: they do not
+emit `onRequest` navigation events. Native links require the host's navigation
+request port because native has no browser default. A web host with unsaved work
+must omit item hrefs until safe navigation is available through its existing
+route/draft authority; this module does not install an unsaved-work route guard.
+Do not infer identical web/native navigation interception from shared labels.
+Media resolves only local paths; hosts must prevent
+those routes from redirecting outside their intended boundary. The model is not
+a network-security boundary for a consumer's asset server.
+
+## Tokens, composition and component families
+
+One checked token source covers typography, light/dark color, spacing, layout,
+density, elevation, borders, motion and state. Overrides are restricted to known
+keys and safe values. Text/background pairs have a 4.5:1 floor, control boundaries
+and focus have 3:1, and reference controls have 44-unit minimum targets in both
+densities. Compact density changes spacing, not target or type floors. A host's
+font metrics, zoom, transparency and surrounding surface still need verification.
+
+One primary pane is required. Context/utility panes remain linear and reachable
+at narrow container widths; resizing is hidden when panes stack. Width values are
+relative flex weights after gaps, not independent percentages plus gaps. Missing
+weights default to 50. A 60/40 pair shares one row; allocations below the minimum
+pane width wrap rather than crushing controls. The native host supplies its measured
+container width; the web projection uses the presentation root's content box.
+Panes accept block IDs,
+not executable routes, business schemas or workspace-allocation commands.
+
+Implemented reference families: text, collection, ordered sequence, graph node
+list with relationship table, media, action, status, refusal, decision, receipt,
+offer, field, editor, preview, diff, review and publication. The latter names are
+display slots: their text, tone and actions come from the host. No business
+lifecycle is defined. Graph lists and relationship tables are the accessible
+baseline; a force layout, query engine, graph editing and virtualization are not
+implemented by this reference. Rich text/media editors likewise belong in
+separately proved adapters, not in an unbounded interpretation of a text field.
+
+Only host-selected blocks should enter a workspace. The all-family fixture is a
+coverage gallery, not a recommended product screen. Use the workspace's primary
+task and context needs to limit simultaneous controls; preserve visible reasons,
+action consequences and recovery state when applying progressive disclosure.
+
+## Interaction and accessibility contract
+
+Hover, focus, pressed, selected, disabled, pending, invalid and dragging are
+independent axes; selection must not erase focus. Web focus is visible, pressed
+feedback differs from hover, and reduced-motion preference removes transitions.
+Forced-color mode retains focus and selection boundaries. Ordinary keys and Tab
+remain native; only a focused range's Arrow/Home/End keys and the confirmation
+dialog's Tab endpoints are locally handled. Host-resolved shortcut display and
+ARIA hints register no commands and promise no shortcut implementation.
+
+Confirmation shows host-supplied consequences, initially focuses Cancel, contains
+Tab, accepts Escape and restores the opener (or surviving pane). Confirmation is
+never an authorization or successful irreversible operation. A missing native
+confirmation port refuses to send. A host still owns reauthentication, irreversible
+action eligibility, last-moment checks, receipt interpretation and recovery.
+
+Sequences optionally expose drag requests and equivalent earlier/later buttons.
+Drop handling accepts only an active drag begun in the same bound sequence; it
+never imports external drop data. Touch and keyboard users need not drag. Bounds
+and order remain host-controlled after either interaction. Browser/native
+platforms may supply additional drag affordances only after equivalent proof.
+
+The reference follows the intent of W3C guidance on
+[modal dialogs](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/),
+[range/separator interaction](https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/),
+[non-drag alternatives](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements.html)
+and [target size](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html).
+The range is a labelled native range, not an assertion of splitter-pattern
+conformance. Automated checks do not establish WCAG certification or assistive
+technology acceptance.
+
+## Host projections and explicit exceptions
+
+| Host | Implemented projection | Remaining receiving-host proof |
+| --- | --- | --- |
+| Web | Semantic HTML, scoped CSS and local binder | Real route, keyboard catalogue, assistive technology and host updates |
+| Desktop webview | Same optional web module | Webview version, OS shortcuts/focus, process and broker isolation; no Desktop runtime included |
+| Native | Injected React/native-compatible primitives, tokens, requests, linear graph/diff, pane layout | Actual framework build, font scaling, screen reader, keyboard/focus, dialogs, touch and device proof |
+| Documents | `renderReadOnlyDocument`, linear content and print styles | Exact PDF/export pipeline, tagging, pagination, font embedding and document semantics |
+
+`createNativePresentation` accepts the consumer's existing `React`, `View`,
+`Text`, `Pressable`, `TextInput`, `ScrollView`, and `Image`; compatible wrappers
+can use existing Tamagui primitives. Atelier takes no runtime framework dependency;
+React and React DOM are pinned development-only proof dependencies.
+`Pressable` must support React Native's state-function style. The host supplies
+measured `containerWidth`, `resolveAsset` and a `confirm` port implementing cancel
+initial focus and focus restoration. Native uses step/move buttons instead of a
+browser range/drag API. Focus treatment and OS keyboard behavior remain native
+host obligations; injected-tree tests cannot prove them. The proof runner also
+mounts real React against deliberately minimal DOM bindings to exercise stale
+confirmation rejection and concurrent pending state; this is lifecycle proof,
+not React Native or Tamagui compatibility. Committed model changes invalidate
+an outstanding native confirmation conservatively, with a visible explanation.
+Equivalent-model rerenders with fresh callback identities do not revoke it;
+delivery uses the latest committed callback. Removing either host port refuses
+confirmation. Request settlement remains visible across model updates, with
+each settlement's own outcome reported independently of other request failures.
+Do not claim compatibility
+with a specific framework version until its mounted adapter has been tested.
+
+Document output has no edit, resize, confirmation or move controls. It preserves
+host status text but cannot create a receipt. Print neutralizes dark colors and
+hides navigation and interactive buttons, retaining action explanations and
+unavailability reasons. This is HTML suitable for an existing export
+pipeline, not a new semantic document or PDF authority.
+
+## Proof and visual-regression governance
+
+Browser proof envelopes now use `atelier.presentation-browser-proof/v3`.
+The envelope records `sourceDirty`; comparison requires it to be explicitly false.
+Dirty-tree runs can provide development evidence but cannot compare as unchanged.
+The runner eagerly decodes fixture images and waits for fonts before measuring,
+then verifies stable document dimensions across capture against the PNG header.
+Each frame records pixel dimensions and document scroll dimensions separately
+from viewport conditions. Old v1/v2 receipts remain historical evidence, but compare
+as incomparable: recapture under v3 rather than automatically accepting them.
+Dimension assertions and hashes do not establish image custody or owner approval.
+
+Run from a source checkout using Node 22.18.0:
+
+```sh
+node scripts/generate-presentation-schema.mjs --check
+node --test test/ui-presentation.test.mjs test/contract-hygiene.test.mjs
+node scripts/prove-presentation-browser.mjs
+npm run contract:compat
+npm run public-api:compat
+npm run syntax:check
+npm test
+```
+
+The browser runner is also exposed as `npm run presentation:proof`. `npm ci`
+installs lockfile-pinned Playwright, React, React DOM and esbuild as development
+dependencies; no framework is added to the distributed runtime dependency set.
+Provision matching browser binaries separately with `npx playwright install
+chromium firefox webkit` (CI Linux images may also need `--with-deps`). The proof
+command itself performs no browser download or server startup. An optional
+`ATELIER_PLAYWRIGHT_MODULE` selects an explicitly provisioned runtime. All requests
+are intercepted to invented fixtures, with other
+origins refused. Default engines: Chromium, Firefox, WebKit. Optional
+`ATELIER_PROOF_BROWSERS` narrows coverage and must remain visible in the receipt.
+
+Outputs live in ignored `.artifacts/presentation-browser` (override with
+`ATELIER_PROOF_OUTPUT`). A receipt records exact source-module and fixture hashes,
+Git HEAD, browser versions, named assertions and screenshot hashes. Each frame
+records viewport, theme, density, motion, locale, scale and font conditions. A
+separate runner digest binds the assertions, mounted React fixture and lockfile.
+Missing/null/unknown proof fields refuse comparison rather than yielding a green
+result. During development HEAD
+alone does not identify the working source; freeze a commit and rerun before
+using it for acceptance. Successful rendering explicitly does not accept a
+visual baseline, native device, or downstream adopter.
+
+This local gate now exercises controlled host refresh, pending focus, full
+Unicode input/refusal, composition boundaries, embedded container geometry,
+invalid-state styles, read-only print visibility and real React callback lifetime.
+Text-size proof measures all rendered text categories at twice the reference
+root font size; it remains synthetic CSS scaling, not platform zoom or WCAG
+certification. Remote CI wiring and accepted screenshot baselines remain explicit
+integration gates, not claims made by a successful local run.
+
+Baseline governance is deliberate: never auto-update expected images after a
+failure. Store a baseline's exact source/fixture/environment identity and its
+reviewing owner's disposition outside generated output. Compare at equal engine
+version, viewport, scale, locale, theme, density, motion and font environment.
+Changed pixels require explanation and a retained before/after pair. Keep
+geometry, accessible names, focus, behavior and content assertions alongside
+images; screenshot equality alone is insufficient. A host with no accepted
+baseline remains unaccepted, not silently green. Actual device and assistive
+technology runs are separate required evidence for those adoption claims.
+
+`comparePresentationProofs(baseline, candidate)` returns `incomparable` for missing
+or changed coverage, `review-required` for changed screenshot digests, or
+`unchanged`. It always reports `baselineApprovalVerified: false` and
+`executionAuthority: false`. The calling proof owner must verify the referenced
+image bytes and baseline provenance; matching self-reported digests are not
+proof of image custody or an accepted design.
+
+Reference chrome is currently English. `lang` and `direction` preserve host
+content language and logical layout, not complete translated control copy.
+Localization, rich editor composition, large-graph exploration, native hover and
+keyboard-focus treatment, and a mounted framework-specific adapter remain
+explicit extensions requiring focused proof before those capabilities are claimed.
+
+## Versioning, migration and adoption
+
+The implementation uses presentation v1.0.0 but does not publish a new package
+version. Existing published subpaths retain the repository's compatibility gate;
+new presentation contracts have no historical baseline yet. Changes to token
+meaning, state behavior, focus, required labels, request payloads or host defaults
+must be treated as compatibility changes even when TypeScript would accept them.
+
+An adoption handoff must pin package/source/tree, model and token version,
+consumer source/tree, exact write set, host/framework versions, supported family
+set, shortcut/focus owner, business request resolver, proof matrix and rollback.
+Adapter conversion is explicit: validate both input and output, retain the old
+source and rendered evidence, and migrate one synthetic consumer before any
+real content. There is no automatic data migration, global token switch, route
+replacement or private adapter import in this module.
+
+Completion ladder:
+
+1. Root source, schema parity, neutral reference rendering and defensive tests.
+2. Exact committed source, full existing suite, private disclosure scan and
+   tarball inspection; maintainer integration review and actual CI separately.
+3. A bounded consumer adapter with explicit business/keyboard/focus handoffs.
+4. Mounted host/browser/device/document proofs and accepted visual baselines.
+5. Separately authorized package publication, route adoption and activation.
+
+Only the root implementation is allocated here. Other owners' source stays
+read-only. A local proof, commit, package audit or issue does not advance the
+later milestones by implication.

package/docs/presentation-consumer-boundaries.md

@@ -0,0 +1,75 @@
+# Presentation and public-page consumers
+
+Status: compatibility reference, not consumer migration or acceptance.
+
+The portable presentation API serves both workspaces and simpler consumers.
+Public pages may consume resolved tokens without rendering a workspace or
+shipping a framework hydration runtime. The Astro example demonstrates that
+build-time boundary with invented content and native HTML controls.
+
+| Concern | Owning layer | Integration rule |
+| --- | --- | --- |
+| Neutral color, type, spacing and accessibility floors | Atelier token API | Map roles explicitly; retain consumer aliases until migration is proved |
+| Workspace requests, pending and presentation confirmation | Atelier presentation API | Requests carry no operation authority; host decides outcomes |
+| Public-page navigation, scroll and overlay lifecycle | Existing consumer framework | Never attach a second global focus/keyboard/scroll controller |
+| Reading geometry, editorial sections and brand fonts | Consumer | No tenant palette, content, private methodology or layout is promoted by copying |
+| Production forms, identity, persistence and publication | Host/business authority | A reference form is not a transport or successful submission |
+| Responsive and visual proof | Shared proof mechanism plus consumer fixtures | Accepted baselines and real-host accessibility remain separate |
+
+## Compatibility constraints
+
+Current root colors accept validated six-digit hexadecimal values. A consumer
+using another color representation needs an explicitly verified mapping; its
+stylesheets cannot be passed through as token overrides. Typography family is
+currently limited to generic serif, sans-serif and monospace. Custom brand-font
+delivery is not silently supported by that restriction. Do not widen the API
+or lower a floor to make an adapter appear compatible.
+
+The example uses native document scrolling and a non-overlay disclosure menu.
+This is a fixture choice, not a ruling that overrides a consumer framework's
+bounded scroll owner or overlay lifecycle. It has no reveal effects or custom
+font loads; no-JavaScript readability and absence of motion are the baseline.
+
+## Migration gates
+
+1. Pin the clean supplier and consumer commits plus their adopted-practice
+   manifests; a package version alone is insufficient.
+2. Record shared roles, intentional exceptions, and which controller owns each
+   interaction. Preserve existing behavior and compatibility aliases.
+3. Test a representative consumer under its existing framework. Verify actual
+   rendered contrast, keyboard, form failure, reflow, reduced motion and page
+   weight, not just token arithmetic.
+4. Review before/after frames and accept the exact baseline explicitly. Retain
+   rollback to the previous dependency and adapter as one reversible unit.
+5. Obtain the separate source, CI, maintainer and deployment authorities. The
+   reference consumer neither allocates a product path nor activates a site.
+
+## CI integration handoff
+
+The existing workflow does not yet execute either browser proof. A maintainer
+must allocate a bounded browser-proof job using the repository's approved
+runner and required-check policy; this document does not create or dispatch it.
+Use one job, read-only repository permissions, a finite timeout, no application
+credentials and no deployment steps. Retain receipts and screenshots even on
+failure. A successful CI exit does not establish visual-baseline acceptance.
+
+The execution sequence, from the checked-out candidate root, is:
+
+```sh
+# Node 22.18.0: existing root proof runtime.
+npm ci --ignore-scripts
+npx --no-install playwright install --with-deps chromium firefox webkit
+node scripts/prove-presentation-browser.mjs
+# Node 22.22.2: isolated Astro build; keep the root runtime contract unchanged.
+npm ci --ignore-scripts --prefix examples/astro-presentation
+ASTRO_TELEMETRY_DISABLED=1 npm run build --prefix examples/astro-presentation
+# Return to Node 22.18.0 for the same proof runtime used locally.
+node scripts/prove-astro-presentation.mjs
+```
+
+Archive `.artifacts/presentation-browser/` and `.artifacts/astro-presentation/`.
+Browser binary versions are determined by the root lockfile. Linux and macOS
+frames are separate environments, not interchangeable visual baselines. On
+macOS WebKit the synthetic keyboard script uses Option-Tab for link navigation
+when system full keyboard access is disabled. This is a host exception, not a
+new global keyboard handler.

package/docs/presentation-review-disposition.md

@@ -0,0 +1,47 @@
+# Presentation correction disposition — 2026-09-15
+
+Status: bounded root correction, not maintainer acceptance, release or adoption.
+Reviewed source: `9ea81f087131e909e22fbcff50df1b57050c76af`.
+
+The returned manual defensive review conditionally accepted that source for root
+integration and found no new critical/high issue. It ran no tests or live sites;
+its visual inspection was partial. The source owner independently verified and
+corrected the following findings. Those corrections are a successor, not covered
+by an inherited approval of the prior commit.
+
+| Finding | Source disposition | Regression evidence |
+| --- | --- | --- |
+| S1/S2: native failure contamination and web/native concurrent-delivery drift | Fixed using shared delivery-message logic; current settlement and remaining pending deliveries are distinct from business state | A regression first reproduced failure A contaminating successful B; focused unit tests and both actual web binder and React-backed native fixture exercise settlement |
+| S3: schema-dependent attribute safety | Escaped string attributes and generated DOM identifiers in addition to retaining strict validation | Existing text/attribute refusal/escaping tests and browser proof |
+| S4: HEAD without dirty-source marker | Proof v3 requires explicit sourceDirty:false for comparison; missing/dirty/old envelopes remain incomparable | Negative comparison cases; dirty development proofs cannot become unchanged baselines |
+| S6: implicit form submit without scripts | Static example uses a labelled group and explicit local input validation, not a submitting form | All three engines exercise Enter with scripts both off and on; navigation, retained value and absent form checked |
+| N9: repeated pending resize silently dropped | Suppression now gives explicit no-additional-request feedback; host still owns geometry | Shared message test; no optimistic resize or queue added |
+| N5: host refresh during IME throws | Queue latest validated model, expose composition state, flush after final edit; newer synchronous host updates win | Browser cases for unchanged composing DOM, latest/invalid model ordering, no stale widget dispatch, removal/disable/reset/disposal |
+| N6: email/number caret continuity | Confirmed email regression; retain compatible focused DOM input without calling unsupported selection APIs | Actual key events insert consecutive characters mid-value during controlled refresh in all three engines |
+| N7/N8: neutral-looking warnings and inconsistent chrome | Shared tone labels, dashed warning edge, focus-revealed skip link, aligned header and distinct link/action styling | Web/document/native label assertions; focus/geometry/style/print checks; new before/after frames retained without accepting a baseline |
+| N10: printed skip chrome | Skip link excluded in print | Print visibility assertion |
+
+## Conditions retained before controlled-host adoption
+
+- Synthetic composition events prove the binder lifecycle, not a real OS IME or
+  assistive-technology session. Receiving hosts still need their actual input,
+  device and screen-reader proof, including real navigation/draft lifecycle.
+- Visual changes have new before/after frames, not a newly accepted baseline.
+- N10 performance: retain the bounded per-render signature used to invalidate
+  stale native confirmations. Object-identity memoization would miss in-place
+  host mutation. Actual native profiling is still needed before replacing this
+  correctness guard; local browser/React fixture proof is not native performance
+  acceptance.
+- S5: screen-reader busy announcements remain an assistive-technology hypothesis.
+  Do not remove pending semantics on the strength of an unrun AT scenario.
+- S7: actual browser-proof CI integration remains unimplemented; use the bounded
+  receiving-owner recipe in [consumer boundaries](presentation-consumer-boundaries.md).
+
+No source in existing server, harness, vault, coauthor, runtime, private auth,
+business, keyboard, Desktop or downstream site implementations changes here.
+Connected component placement and portable auth remain a separate unimplemented
+proposal. Shape checks of that proposal do not establish enforcement or admission.
+
+The remaining integration gates are exact host proof, maintainer integration,
+visual-baseline disposition and actual CI. Local testing and a
+source commit do not publish a package, accept a visual baseline or deploy a site.

package/docs/project-command-inventory.md

@@ -0,0 +1,38 @@
+# Project option and command inventory
+
+`--project PATH` and `--project-config PATH` select the first explicit config.
+Repeated `--repo-path NAME=PATH` uses the last value for each name; paths resolve
+from the invocation's current directory. Both separated and equals forms work.
+Resolution precedence is CLI override, ignored local overlay, tracked relative
+location, then declared sibling discovery. Overrides do not declare repositories
+or widen read boundaries. Missing required sources still fail.
+
+`atelier config check --explain` reports logical names, resolution sources,
+resolved state and read boundary without machine paths. Normal config diagnostics
+remain local. `MNSTRY_ATELIER_PROJECT_CONFIG` and local overlays retain their established
+resolver behavior. Shared options are parsed by the resolver, including direct
+module calls and branded `runCli` wrappers; wrapper authors must forward argv.
+
+| Family (aliases share implementation) | Location and side effects |
+| --- | --- |
+| graph; project/build; readiness/generated; context/resolve/capabilities/proposal | Shared project resolver. Graph/projection/readiness and proposal operations can create local outputs/history. |
+| dev/server | Shared project resolver; foreground loopback service. `--review` opts into local review ledgers. |
+| config/manifest; extension-pack/list/validate | Shared resolver; project resolution may ensure ignored local state. Pack loading is declarative, with no extension execution. |
+| support/bundle; analysis/analyze | Project-aware implementation; local previews/explicit output or disabled-by-default analysis contracts retain their existing controls. |
+| boundary/check/doctor/push-check/audit/install-hooks; promote | Project-aware implementation; checks and explicit hook/promotion operations retain their own mutation guards. |
+| lock/check/write; upgrade | Shared project resolver, except standalone `lock provenance`. Lock write and upgrade apply retain their explicit operation semantics. |
+| review run/history/handoff/packs/export | Shared resolver; bound runs and contributions use ignored state. Export previews unless explicitly written. |
+| review inspect | Standalone inert file inspection; does not resolve a project or create active review state. |
+| coauthor | Current Git workspace only; JSON stdin. Explicit start/event/recover writes ignored private drafts and ledger events. Never relocates or edits canonical sources. |
+| init; setup/adopt/doctor | Scaffold/adoption-specific target handling; no new universal target semantics. |
+| sync | Repository-operation interface owns `--repo`; enrollment accepts its existing project-config option. It is not an adapter source relocation command. |
+| distribution; disclosure; attestation; feedback; announcements; egress; contract; export/dry-run | Artifact/package/repository-specific entry points retain their own targets and option validation. |
+
+Command-specific parsers retain ownership of their options. The shared project
+parser never globally allows arbitrary flags. The strict extension-pack and new
+review interfaces reject unknown options before operation. Legacy permissive
+entry points retain compatibility rather than gaining an unrelated syntax change.
+Regression coverage exercises moved sources through the published CLI, legacy
+alias, branded wrapper and direct pack module, plus project command families.
+The installed consumer gate repeats the external adapter journey across two
+source locations and checks that missing or stale inputs cannot gain authority.

package/docs/project-options.md

@@ -0,0 +1,53 @@
+# Project location and repository overrides
+
+Project-aware commands share these options through the project resolver:
+
+```sh
+atelier extension-pack validate --project adapter/atelier.project.json --repo-path content=../source
+atelier graph --project-config=adapter/atelier.project.json --repo-path=content=../source
+atelier config check --project adapter/atelier.project.json --explain
+```
+
+Both `--flag=value` and `--flag value` work. Repeat `--repo-path NAME=PATH`
+for multiple logical repositories. Names must already be declared in the
+project; an undeclared name adds no repository or read authority. The last
+override for a name wins. The first `--project` or `--project-config` selection
+wins, preserving existing alias behavior. Missing or malformed values now fail
+with `project-option-invalid` instead of silently falling back to another path.
+Paths may contain spaces or equals signs; quote them as your shell requires.
+
+Resolution precedence is CLI override, ignored local overlay, tracked relative
+path, then sibling discovery. CLI paths resolve from the working directory;
+tracked and overlay paths resolve from the project config directory. Sibling
+discovery checks the declared remote when one is supplied. An override does not
+change the repo's declared identity or read boundary; downstream graph and
+boundary checks still apply. `kind: external` means unmanaged with no read
+boundary, not an adapter for reading arbitrary external content.
+
+`config check --explain` shows logical names, resolution sources and declared
+read boundaries without machine paths or remote URLs. `resolved` means a path
+was selected, not that the repo exists or passed identity and content checks.
+Resolution may create ignored `.atelier-local/` directories; this diagnostic is
+not a promise of a write-free invocation. The ordinary config report retains
+its existing shape and local config path.
+
+## Command inventory
+
+| Family | Project handling | Other effects |
+| --- | --- | --- |
+| config, graph, project/build | Shared resolver | Validation or generated artifacts |
+| readiness, generated aliases | Shared resolver; protocol listing can be standalone | Runs, packets, generated artifacts |
+| extension-pack list/validate | Shared resolver and strict command options | Loads declared packs locally |
+| setup, doctor | Shared resolver | Ignored state repair when requested |
+| boundary, promote | Shared resolver | Boundary checks, explicit hooks or ledger operations |
+| upgrade, lock | Shared resolver | Explicit lock/upgrade operations |
+| dev/server, support | Forward project arguments to the shared resolver | Local listener or local support preview |
+| context/resolve/capabilities/proposal | Shared resolver | Local context envelope or capabilities report |
+| init/adopt | Target/template inputs; generated config then resolved | Creates starter/config files |
+| contract, export/dry-run, analysis, egress, distribution, disclosure, attestation, feedback, announcements, sync | File/repo-specific inputs | Follow their own command contracts |
+
+The shared options do not turn standalone commands into project consumers.
+Command-specific parsers retain their existing behavior; in particular the
+extension-pack allowlist still refuses unknown options. Public and legacy CLI
+names, `runCli` distribution wrappers, and direct project-aware modules all
+reach the same resolver.