@mnstry/atelier 0.2.0-alpha.14 → 0.2.0-alpha.16

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

package/docs/{local-services.md → reference/local-services.md}

@@ -486,7 +486,7 @@ error, 3 the operation ran and its answer is not success.
 | `status` | enablement, machine settings, what was decided, proven service state, per-view freshness with its diagnostics (a code, the rule and the in-view note concerned, never a value; see [the Obsidian contract](obsidian-contract.md#notes-that-were-laid-out-anyway)), whether an apply operation exists | nothing |
 | `settings` | what this machine remembers for the workspace (who may see, where vaults live, start at login, the adapter), who allowed the service, and how each answer is changed | nothing |
 | `scope list`, `scope show ID` (also `view list`, `view show ID`) | the declared views | nothing |
-| `view add ID (--all \| --folder PATH [--folder PATH ...] [--repo R] \| --tag T) [--expand DEPTH:MAX] [--default] [--allow-empty] [--yes]` | adds a view to the project configuration, after showing the change and how many notes the view would show; refuses a view that would show no note unless `--allow-empty` (see [Adding a view](obsidian.md#adding-a-view)) | `atelier.project.json`, and `.gitignore` when `.atelier-local/` is not ignored. Never committed |
+| `view add ID (--all \| --folder PATH [--folder PATH ...] [--repo R] \| --tag T) [--expand DEPTH:MAX] [--default] [--allow-empty] [--yes]` | adds a view to the project configuration, after showing the change and how many notes the view would show; refuses a view that would show no note unless `--allow-empty` (see [Adding a view](../guides/obsidian.md#adding-a-view)) | `atelier.project.json`, and `.gitignore` when `.atelier-local/` is not ignored. Never committed |
 | `audience show`, `audience set me\|A,B`, `audience clear` | the audiences this machine lets into a view; none by default, which publishes an empty view. `me` is only you: every audience but `sensitive`, which is added by name. The answer is remembered as the person's decision. A change invalidates every view at the next tick | private machine settings |
 | `location show`, `location set DIR [--allow-synced-location]` | where this workspace's vaults live; each view not published yet gets `<project> (<view>)` there at its first publication, and a vault published already stays where it is | private machine settings |
 | `mode show`, `mode set manual\|automatic` | `automatic` refuses without an installed, matching, active automatic policy | private machine settings |

package/docs/{obsidian-contract.md → reference/obsidian-contract.md}

@@ -5,7 +5,7 @@ feasibility track. It states what is proven, on what, and what is not. Nothing
 here enables a feature. The publisher under
 `src/projection/obsidian/publication/` is called by the maintenance service
 (`atelier obsidian service start`) and so by `atelier obsidian open`; see
-[obsidian.md](obsidian.md).
+[obsidian.md](../guides/obsidian.md).
 
 ## Registered shapes
 
@@ -868,7 +868,7 @@ written meanwhile.
 
 macOS (Darwin 25, arm64) with Obsidian 1.13.7 (installer 1.12.7), CLI enabled,
 no community plugin. Sixteen interleavings, 25 rounds for each racing case, in
-four complete clean runs of the prototype in `experiments/obsidian-publication/`
+four complete clean runs of the historical publication feasibility prototype
 at commits `34f5fab` and `c5142e7`. The receipts record those same trees under their
 pre-sign-off identities `5930f85` and `93303ff`; the branch was rewritten only to add
 sign-off trailers, with identical content. Receipt SHA-256 digests:
@@ -880,11 +880,13 @@ sign-off trailers, with identical content. Receipt SHA-256 digests:
 
 A fifth run aborted because the harness could not open a note after the
 second-window case; no bytes were involved. The receipts are maintainer-held
-and are not part of this repository.
+and are not part of this repository. Current desktop qualification uses
+`scripts/obsidian/desktop-receipts.mjs`. These historical receipts do not qualify
+a later candidate or a different host.
 
 Every vault Atelier publishes now carries Atelier's own plugin
 ([obsidian-plugin.md](obsidian-plugin.md)), so a trusted vault runs one
-community plugin. In phase 1 it registers no editor extension, no vault event
+community plugin. The current plugin registers no editor extension, no vault event
 handler and nothing that writes; it only talks to the maintenance service over
 loopback. The protocol cases above have not been re-run with it loaded; that
 run is gate G20, before the plugin carries any part of publication.

package/docs/{obsidian-plugin.md → reference/obsidian-plugin.md}

@@ -5,11 +5,11 @@ finds or installs it: the maintenance service puts it into the vault with the
 notes, and Obsidian asks once per vault whether to trust the vault's plugins.
 Until the person says yes, and whenever the plugin is absent, turned off or
 running in an app that is too old, everything works as it did before through
-the command-line path described in [obsidian.md](obsidian.md).
+the command-line path described in [obsidian.md](../guides/obsidian.md).
 
-This is phase 1: the plugin is present, reports status and holds a channel to
-the service. It decides nothing and writes nothing. Phase 2, planned at the
-end of this document, moves the in-app part of publication into it.
+The plugin reports status and holds a channel to the service. It decides
+nothing and writes nothing. Publication uses the existing command-line or
+app-free path; the plugin does not perform its critical section.
 
 The source is `plugins/obsidian/` in the package: `manifest.json`, `main.js`
 and `styles.css`, plain JavaScript with no build step. The channel it speaks
@@ -413,7 +413,7 @@ every two seconds for every open vault, so the project is kept:
   loader: it starts from the home alone, and its plugins are told about a view
   once two of the loads that compose the confirmed generation have agreed. A
   service given only a loader that answers a promise still refuses to start
-  (see "Personal workspaces" in [obsidian.md](obsidian.md)).
+  (see "Personal workspaces" in [obsidian.md](../guides/obsidian.md)).
 - **A load that fails** (it throws, it is refused, it is given up, or a file
   vouches for nothing under a loader that answers a promise) ends whatever
   was kept, and is asked for again after two seconds, then four, up to
@@ -767,64 +767,3 @@ note open in the editor.
   storage. Writing the profile's local storage would mean editing a LevelDB
   database behind the app's back, and calling `app.plugins.setEnable(true)`
   would skip the prompt altogether.
-
-## Phase 2 plan
-
-Phase 2 moves the in-app critical section of publication into the plugin, and
-closes gates G20 and G21 of the initiative. Nothing below is implemented.
-
-1. Commands. The channel gains the publication protocol's three operations,
-   `inspect`, `publish` (`replace` and `remove`) and `collect`, with the
-   payloads the command-line path validates today (`validatePayload`), and a
-   protocol variant, `obsidian-plugin-critical-section/v1`, recorded in every
-   journal it writes. The service stays the only client that starts work; the
-   plugin fetches work with a bounded long poll (`POST /plugin/work`) and
-   answers with `POST /plugin/result`, both sealed under the session's key
-   like every command of phase 1, so the plugin never listens on a port and
-   takes work only from a service that proved it holds the vault's key.
-   At most one operation per vault is in flight, every operation has an
-   identity, a lost answer is recovered with `collect`, and a publish is never
-   sent twice.
-2. The critical section. The plugin runs the same synchronous body the
-   command-line path sends through `eval` (`criticalSection` in
-   `bridge-script.mjs`), shipped in `main.js` rather than sent: refuse on a
-   dirty or differing editor in any window, refuse on changed bytes on disk,
-   exchange atomically, update open editors in one transaction of minimal
-   hunks and record `lastSavedData`, record the outcome, reply at once. The
-   late-writer re-check and the manifest commit stay in the publisher.
-3. Path selection. With a live lease from a plugin whose protocol matches, the
-   publisher uses the plugin channel; otherwise the command-line path, and
-   with no app running, the app-free path, exactly as today. A refusal is
-   never relaxed by switching paths.
-4. Live edit preservation. The plugin forwards the vault's `modify` events and
-   the editor's dirty state for Atelier's notes to the service as they happen,
-   so an edit is preserved in recovery before any maintenance tick looks for
-   it. The service still decides what an edit is.
-5. G20. The complete G00 interleaving suite (sixteen interleavings, racing
-   cases repeated) and the G04 production-publisher suite run in plugin mode
-   on a real isolated app, unchanged, with zero lost bytes. A case that passes
-   on the command-line path and fails in plugin mode fails the gate; the suite
-   is not narrowed.
-6. G21. Apply and Discard in the status window for held edits, forwarded to
-   the service's existing apply operation, which decides; then the procedure
-   AP-08: enable, disable, uninstall and an app below the floor on one vault
-   with pending edits and recovery bytes, comparing manifests, path
-   allocations, pending edits and recovery digests with the command-line path
-   after each step.
-
-Open questions for phase 2: when, if ever, plugin files are removed from a
-vault; and how an upgraded service answers an older `main.js` that the app
-keeps running until it reloads the plugin (the hello carries the plugin
-version and the protocol for that).
-
-### Deviations from the track plan
-
-The obsidian-plugin track planned an optional enhanced mode. The owner's
-decision of 2026-09-24 made the plugin the primary in-app half, shipped in
-every managed vault, with the command-line path as the fallback. Phase 1 here
-therefore builds the plugin, its delivery and a presence and status channel
-before the publication commands the plan's first phase describes; the parity
-held today is between the plugin's constants and the channel contract, and the
-refusal parity with the command-line path belongs to phase 2, when the plugin
-carries publication commands. Fixtures are generated in temporary directories
-rather than kept under `fixtures/obsidian/plugin/`.

package/docs/{practical-judgment.md → reference/phronesis.md}

@@ -1,15 +1,24 @@
-# Practical Judgment and practice adoption
+# Phronesis — practical judgment
 
-Practical Judgment supports deciding what matters and what is fitting in a
+Phronesis supports deciding what matters and what is fitting in a
 particular situation. It also supports cultivation: contrasting cases, warranted
 exceptions, questions, distinct voices and reflection on consequences. A useful
 deliberation can remain open or produce an action without producing a rule.
 
+Phronesis is a responsibility; the [Knowledge Graph](knowledge-graph.md) is a
+shared representation. Knowledge Stewardship remains the broader responsibility
+for knowledge inclusion and applicability. Phronesis draws on the shared graph
+and contributes cases, decisions and learning through existing Knowledge records,
+review and activation. It introduces no new store or canonical authority and
+does not supply automatic wisdom or a universal score.
+
 `@mnstry/atelier/judgment` validates portable cases and native architecture
 decision snapshots. `inspectPracticalCase` preserves purpose, values, evidence,
 alternatives, dissent, cultivation exercises and reconsideration conditions.
 It does not score wisdom. The invented workshop fixtures demonstrate an open
 deliberation and a decision whose implementation is still planned.
+The API and the `atelier-practical-judgment` skill identity retain their existing
+names and compatibility obligations.
 
 ## Architecture decisions
 
@@ -31,7 +40,7 @@ review and dependency reconsideration. Do not change an old record in place.
 
 ## From feedback to intrinsic practice
 
-The [learning lifecycle](learning.md) captures an observation, proposes a scoped
+The [learning lifecycle](../guides/learning.md) captures an observation, proposes a scoped
 lesson, records an exact decision, then activates the accepted version for a
 named harness. `capabilityEventToLearningInput` bridges version-bound capability
 metadata into that lifecycle. It retains the reported cause, binding, release,

package/docs/reference/portability.md

@@ -0,0 +1,92 @@
+# Portability: what a record holds and what the checks prove
+
+An Atelier workspace is meant to be enough for another team to build from,
+without rediscovering the work it describes. This page says what a complete
+record holds, what each check proves about it, and where the line between the
+record and a running product falls. `docs/reference/continuity.md` covers the
+package's own continuity commitments; this page covers yours.
+
+## What a complete record holds
+
+| What the record must hold | What another team needs from it |
+| --- | --- |
+| Rules and calculations | The rules the product applies, their inputs, how each result is computed and interpreted, exceptions and versions. |
+| Agent behavior | Instructions, tone, context requirements, permitted actions and example exchanges. |
+| Product and interface | Screens and flows, state changes, saved results, access rules, and what one person or a group can do. |
+| Content and brand | Copy, published material, design references and assets, with ownership or license terms. |
+| Business workflows | Processes, responsibilities, handoffs and approval rules. |
+| Data and connections | Your systems' data formats, identifiers, relationships and export instructions, plus the service interfaces and dependencies a replacement would reconnect. |
+| Tests and decisions | Representative inputs and expected results, quality criteria, accepted decisions and relevant revision history. |
+
+**Every custom rule has a retained explanation.** If a rule determines a
+result, a reply, access or a next step, its meaning belongs in the authored
+record, including when software executes it.
+
+## How the record is checked
+
+In three parts. The first two are package commands; the third is not.
+
+The export validator checks conformance: the record is in the published
+format and every reference resolves to a declared source. What it refuses
+across a source's `audience` and an export's `visibility` is stated in the
+README's audience-visibility block.
+
+```bash
+atelier dry-run ./atelier-export.json
+```
+
+The report says `accepted`, and separately whether the artifact is
+`importable`. The validator resolves references to declared provenance
+entries, not to packaged content, so it proves the artifact's shape and its
+references, not that everything necessary was written down.
+
+The readiness protocols check coverage inputs: a supplied answers file is
+checked against each protocol's required inputs, and the missing ones are
+listed. An answer being present is not evidence that it is right.
+
+```bash
+atelier readiness run PROTOCOL_ID --answers answers.json --project ./atelier.project.json
+```
+
+That run is an input-completeness check and is not evidence-bound. For a run
+bound to its sources, `atelier review run PROTOCOL_ID --answers answers.json`
+records that source-bound run. Accepting one of its claims in the review
+workspace checks source linkage. A linked source establishes which
+bytes were read, not whether they logically support the proposed claim
+(`docs/guides/local-review.md`). The responsible people review coverage; an
+issuer can record its admission decision in an attestation bound to the canonical form of the document it
+judged (`docs/reference/attestation.md`).
+
+The record also carries its own tests. A complete record gives every
+documented rule representative inputs and expected results beside it. The
+package keeps these cases and links them to their rules; it does not run them.
+Whatever executes the rules runs them, so name that runner when you cite this
+check.
+
+Together the three show what has been delivered and what remains unresolved,
+in the record rather than in someone's memory. A rebuild also needs the authored
+rules, their representative tests, the data exports, the dependencies and the
+operating instructions, reviewed together against the agreed scope. No
+validator can supply that review.
+
+## The dividing line
+
+If it describes how the work is done, it is a file in the Atelier. If it
+records what happened to a particular person, or has to be enforced at the
+moment of use, it lives in a product runtime. A folder of files cannot
+decide, while two people are in a session, which of them may see what;
+cannot hold a payment; and cannot be the consistent, recoverable record when
+several parties write at once.
+
+The Atelier holds how the work is done and the documentation of your systems'
+data: formats, identifiers, relationships and export instructions. Records
+about particular people live in the systems you run. What the package will
+and will not do toward any runtime is stated once, in the README's
+will-not-do block; this page adds nothing to it.
+
+## Copying the record
+
+The repository is the store, Git is the history, and a copy of the folder is a
+copy of the whole record. A copied folder carries the record and its history,
+not remote data or assets stored elsewhere; the data-and-connections row above
+is where those are described so a replacement knows where to look.

package/docs/{portable-presentation.md → reference/portable-presentation.md}

@@ -2,8 +2,8 @@
 
 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).
+Current compatibility and adoption conditions are in
+[consumer boundaries](presentation-consumer-boundaries.md).
 
 ## Placement and authority
 

package/docs/{presentation-consumer-boundaries.md → reference/presentation-consumer-boundaries.md}

@@ -44,6 +44,11 @@ font loads; no-JavaScript readability and absence of motion are the baseline.
 5. Obtain the separate source, CI, maintainer and deployment authorities. The
    reference consumer neither allocates a product path nor activates a site.
 
+Synthetic composition events and browser/React fixtures do not establish real
+OS input, screen-reader behavior or native performance. Verify pending/busy
+announcements with actual assistive technology and profile the receiving native
+host before changing its confirmation guards.
+
 ## CI integration handoff
 
 The existing workflow does not yet execute either browser proof. A maintainer

package/docs/{project-options.md → reference/project-options.md}

@@ -31,6 +31,23 @@ 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.
 
+## Bundled readiness selection
+
+The tracked `atelier.project.json` may set
+`ext["mnstry.atelier"].readiness.includeBundled` to `false` to deselect the bundled
+MNSTRY readiness pack. An absent setting or explicit `true` preserves the
+existing default. `readiness` must be an object and `includeBundled` a boolean;
+invalid values fail with `readiness-selection-invalid`. This is a project
+setting, not a CLI flag or local preference.
+
+Project-aware protocol listing and runs then use only selected custom packs;
+generic graph, projection and readiness checks remain available without the
+MNSTRY tenant journey. A bare protocol listing without a project selection
+retains its standalone bundled list. Review selection changes and run
+`atelier lock write --project ./atelier.project.json`; see
+[readiness pack selection](../guides/tenant-readiness.md#select-the-readiness-pack)
+for lock checks and commands that require the bundle.
+
 ## Command inventory
 
 | Family | Project handling | Other effects |

package/docs/{repo-boundary-guard.md → reference/repo-boundary-guard.md}

@@ -59,6 +59,13 @@ The staged guard (`atelier boundary check --staged`) inspects every staged
 `*.md` and `*.kg.json` diff for changes to boundary fields — `kg.audience`,
 `audience`, `handling`, `sensitivity`, `data_boundary`.
 
+Only a literal field assignment is a review signal; an ordinary mention such
+as a title about audience research is not. Compact JSON and escaped JSON field
+names are inspected too. A diff cannot establish the quote or comment context
+before a changed line, so an assignment written as an example still counts.
+The complete value suffix is kept; an incomplete collection or comment is not
+silently treated as a private initialization default.
+
 It distinguishes two cases:
 
 - **Initialization.** A boundary field added with no prior value, set to a
@@ -80,6 +87,14 @@ A marker committed in a sibling file, or already sitting elsewhere in a file
 that this commit does not touch, approves nothing — the guard reads the diff,
 not the working tree.
 
+Removed declarations still require review when a classified document is
+deleted, renamed or changed to another file type. Staged paths are acquired
+without folding renames, including type changes, from the index actually being
+committed. A missing configured repository, unresolved committing repository,
+failed listing or incomplete NUL-delimited listing refuses the check rather
+than yielding partial clean evidence. Git's path quoting is pinned for diff
+acquisition regardless of the repository's display configuration.
+
 ## Owner-signed operator delegation
 
 A private-domain repository names one `ownerActor`. When anyone else runs
@@ -209,7 +224,7 @@ changes together. The `atelier.lock.json` refresh should be limited to the
 copied workspace's Atelier package metadata, contracts, and migration state,
 while private-domain and shared-project source boundaries remain unchanged.
 
-See `docs/upgrade.md` for the upgrade sequence.
+See `docs/guides/upgrade.md` for the upgrade sequence.
 
 ## Repo Identity
 
@@ -279,9 +294,17 @@ machine for weeks.
   remote's tracking refs, so reinstall it (`atelier boundary install-hooks`)
   for history that only another remote holds to be judged on its way to a new
   one. A brand-new branch is diffed against the empty tree, in SHA-1 and SHA-256
-  repositories alike, so nothing slips through unscanned. A push carrying more
-  than 1000 such commits, or more evidence than the aggregate budget, is
-  refused; push it in smaller parts, an earlier commit first. Each diff reads
+  repositories alike, so nothing slips through unscanned. A ref update carrying
+  more than 1000 such commits, or a push whose refs together carry more
+  evidence than the aggregate budget, is refused with `content-scan-incomplete`;
+  push it in smaller parts, an earlier commit first. The aggregate counts the
+  net change and the additional evidence read from individual commits. If the
+  net change together with a commit's evidence exceeds that budget, merge in
+  smaller steps, or rebase onto the remote, and push again. `limitBytes` names
+  the full aggregate budget, including when earlier refs have used part of it.
+  The text output lists blocking errors before warnings, with incomplete or
+  unresolved evidence first within each group, and at most 50 findings;
+  `--json` lists every finding in the report's original order. Each diff reads
   what it needs, so a history that swaps large binaries back and forth makes
   the hook slow, within the commit cap and per-diff limits. The remote's
   tracking refs are found by name: a remote whose fetch refspec writes into

package/docs/{review-portability.md → reference/review-portability.md}

@@ -37,6 +37,10 @@ state. Foreign decisions remain visibly unverified historical assertions. The
 format carries no trusted signature: there is no applicable signer authorization
 or attestation to verify. Valid hashes prove internal consistency only.
 
+Inspection never overwrites active state or transfers execution authority,
+secrets or current local approval. Existing domain ledgers remain authoritative;
+the bundle is a selected historical record, not a replacement review store.
+
 The `atelier-review.v1.schema.json` contract defines these separate artifacts.
 Evidence and contributions use the existing JCS implementation; the bundle hash
 covers every top-level member except `digest`. A member hash covers its complete

package/docs/{template-profile.md → reference/template-profile.md}

@@ -155,7 +155,7 @@ installed source-apply owner, rejects the stale binding, and checks idempotence
 and preservation of an unrelated source. Atomic exchange is required for the
 write portion; other platforms retain the read-only checks.
 
-The built-in [template adoption participant](template-upgrades.md) connects local
+The built-in [template adoption participant](../guides/template-upgrades.md) connects local
 profile adoption, exact locks, retained history and read-only projections to the
 existing upgrade transaction engine. External packs, runtime extensions and
 automatic restoration remain unsupported.

package/docs/{trackables.md → reference/trackables.md}

@@ -62,8 +62,8 @@ history; this adapter does not claim secure erasure or automated retention.
 A command has `schema: "atelier-trackable-command@v1"`, `requestId`,
 `expectedRevision`, `operation` and `input`. Operations are `release`,
 `instantiate`, `adopt`, `record`, `correct`, `lifecycle` and `disposition`.
-The exported [schema](../contracts/atelier-trackable.v1.schema.json) and
-[fixtures](../fixtures/atelier-trackable) specify exact fields.
+The exported [schema](../../contracts/atelier-trackable.v1.schema.json) and
+[fixtures](../../fixtures/atelier-trackable) specify exact fields.
 
 `execute` locks the selected scope, verifies history, applies the shared reducer,
 atomically publishes one event and reads it back. Replaying the same request and

package/docs/start/independent-start.md

@@ -0,0 +1,89 @@
+# Start Atelier independently
+
+Atelier runs locally with readable files and Git as the source of record. The
+CLI, library and contracts work without a MNSTRY account, hosted service or
+desktop utility. Installing the package uses the npm registry; the authoring
+commands below run locally.
+
+## Find the source and choose a release
+
+The maintained public source is [MNSTRY/atelier](https://github.com/MNSTRY/atelier),
+on `main`. Its package manifest names the version being prepared; a version in
+source is not a publication receipt.
+The example below pins the published `0.2.0-alpha.14` alpha release. Registry
+`latest` and `alpha` are separate channels; check them before choosing an upgrade:
+
+```bash
+npm view @mnstry/atelier dist-tags --json
+```
+
+Use Node.js `>=22.18.0 <23` or `>=24.13.1 <25`, as declared by the current
+source package. See [installation](install.md) and [upgrades](../guides/upgrade.md) for
+release identity, workspace locks and migration checks.
+
+## Create a disposable example
+
+Run these commands in a new directory:
+
+```bash
+npm init -y
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.14
+npx mnstry-atelier init --template sample-workspace --target ./sample
+npx mnstry-atelier graph --project ./sample/atelier.project.json
+npx mnstry-atelier build --project ./sample/atelier.project.json
+```
+
+Inspect the readable sources in `sample/` and the generated graph and projection
+under `sample/atelier-output/`. Generated output is rebuildable; it does not
+replace source files. To view it in an optional foreground browser service:
+
+```bash
+npx mnstry-atelier dev --project ./sample/atelier.project.json --port=0
+```
+
+Open the printed `127.0.0.1` URL and stop the service with Ctrl-C. Build first:
+`dev` serves an existing projection. These commands need no MNSTRY environment
+variables or canonical-repository credentials.
+
+Keep the `@mnstry/` package scope. After installation, `npx mnstry-atelier`
+selects the shipped binary; the unscoped npm package `atelier` is unrelated.
+
+## Adopt a small scope in an existing repository
+
+From the intended repository, install the same pinned package, then select the
+actual documents you want the graph to read:
+
+```bash
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.14
+npx mnstry-atelier adopt --profile single-repo --target . --include 'docs/**' --yes
+```
+
+`adopt` prepares the project configuration and ignored local bindings. Review
+its diff and the selected sources before building the graph. Existing documents
+need the appropriate metadata or sidecars; use the [knowledge setup workflow](knowledge-setup.md)
+to author that model. `init` is for a new starter and refuses existing Atelier
+configuration. Neither path requires enabling [Sync](../guides/atelier-sync.md).
+
+## Public tooling and consuming hosts
+
+The complete export list is in `package.json`. Choose the surface that matches
+the work:
+
+| Surface | Existing examples | Boundary |
+| --- | --- | --- |
+| Local authoring and contracts | Root API, `./project`, `./graph`, `./projection`, versioned `./contracts/` subpaths | Files, Git and adopted contracts retain authority. |
+| Optional local interfaces | `./cli`, `./server`, `./ui`, `./presentation`, `./presentation/browser`, `./presentation/native` | A host selects and qualifies its presentation and lifecycle. |
+| Optional supervision and integrations | `./runtime`, `./runtime/git`, `./extension-packs`, `./extensions`, `./extensions/client`, `./vault` | Git synchronization and host-bound providers require explicit configuration; the host supplies provider SDKs and credentials. |
+| Local proposals and learning | `./collaboration`, `./learning` | Proposal acceptance is copy-only; learning activation supplies scoped context. Neither grants source-write authority. |
+
+Generic headless startup, editor and native-presentation bindings remain public
+tooling. MNSTRY's desktop utility is a separate proprietary consumer. A host's
+authentication, integrated capture, provider access and managed data stay with
+that host. See the [responsibility architecture](../reference/architecture.md),
+[learning boundary](../guides/learning.md) and [local-service contract](../reference/local-services.md).
+
+Repository read access exposes its files. Audience metadata governs projections;
+it does not hide private files from someone who can read the repository. Share
+only an explicitly prepared bounded view, and retain owner-controlled source
+application. Public tooling does not supply a managed MNSTRY runtime or confer
+runtime admission.