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

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
 
@@ -260,10 +275,41 @@ That is how a public site's owner-authorized mock cart stranded real work on a
 machine for weeks.
 
 - `pre-commit` runs `atelier boundary check --staged` — added lines in the
-  staged diff.
+  index Git is committing, including the temporary index of `git commit -a`
+  or `git commit <paths>` and a linked worktree's own index.
 - `pre-push` runs `atelier boundary push-check` — git writes the ref updates to
-  the hook's stdin, and only that range is judged. A brand-new branch is diffed
-  against the empty tree, so nothing slips through unscanned.
+  the hook's stdin, and only that range is judged: the change from the
+  remote's commit to the pushed tip, and every commit the push carries that the
+  remote's tracking refs do not hold, each against its parent, so content added
+  and removed again within the push is still caught (the finding names its
+  commit). A merge is judged only for what is new against all of its parents,
+  so a pull merge into the branch you push is not refused for what the remote
+  already holds; merging another branch into a feature branch can still be
+  refused through the change from the remote's commit, as before. The hook
+  passes the remote Git names: a configured remote, or a URL matched to the
+  remote configured with it. Only that remote's tracking refs, stale ones
+  included, exclude commits (a remote whose `pushurl` names another
+  repository is still scoped by its fetch-side tracking refs); a URL no remote
+  is configured with excludes only the remote's commit. A hook installed before this judges against every
+  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 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
+  another remote's namespace, or two remote names that differ only in case on
+  a case-insensitive file system, can blur which history the remote holds.
 - `atelier boundary audit` scans the current working tree by default and
   **reports without blocking**, listing matches, incomplete-read diagnostics,
   and declared exceptions with their reasons. Use `--head` for a committed

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/{semantic-operation.md → reference/semantic-operation.md}

@@ -1,9 +1,10 @@
 # Semantic operation: internal vanilla profile
 
 `src/knowledge/semantic-operation.mjs` connects a host's extraction to the
-existing intake and knowledge owners. It is an internal library. There is no
-public export, registered schema or CLI command yet. The proposed consumer is
-an agent operating the experimental Atelier CLI after Foundation registers it.
+existing intake and knowledge owners. It is an internal library with no public
+export or registered schema. Since 0.2.0-alpha.13 the experimental CLI reaches
+it as `atelier knowledge semantic OPERATION`; an agent operating that command
+is its intended consumer.
 
 Atelier never invokes a model. The host supplies its raw output, its normalized
 candidate envelope, configuration pins and usage report. A deterministic or

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`. In the 20 October 2026 source/release snapshot, its package manifest
+describes the `0.2.0-alpha.15` candidate. 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.

package/docs/{install.md → start/install.md}

@@ -18,7 +18,7 @@ Git repository access is the hard read boundary for source files. Local
 from anyone who can read the repository.
 
 For adapters whose source repositories live elsewhere, see
-[project options](project-options.md) for shared CLI overrides, precedence and
+[project options](../reference/project-options.md) for shared CLI overrides, precedence and
 resolution diagnostics. Moving a repository does not change its read authority.
 
 Two command forms ship, and each has a place. Inside an installed
@@ -30,23 +30,23 @@ npm name `atelier` belongs to an unrelated third-party package, so a bare
 
 ## Install shape
 
-The registry is the distribution channel of record, as `docs/continuity.md`
+The registry is the distribution channel of record, as `docs/reference/continuity.md`
 commits:
 
 ```bash
-npm install --save-dev @mnstry/atelier@0.2.0-alpha.13
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.14
 ```
 
 Installing from the matching Git tag resolves to the same reviewed commit:
 
 ```bash
-npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.13"
+npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.14"
 ```
 
 Or over SSH:
 
 ```bash
-npm install --save-dev "git+ssh://git@github.com/MNSTRY/atelier.git#v0.2.0-alpha.13"
+npm install --save-dev "git+ssh://git@github.com/MNSTRY/atelier.git#v0.2.0-alpha.14"
 ```
 
 Keep the `@mnstry/` scope — see the command-form note above for why the
@@ -256,7 +256,7 @@ and `setup.exclude`, which `adopt --include` and `adopt --exclude` record.
   Adoption wrote them and the `monorepo` profile requires `--include`, but
   until this release nothing read them. Giving them their meaning does not
   widen the contract. A new field, or a list, would widen a closed object,
-  which [contract stability](contract-stability.md) makes a new major version.
+  which [contract stability](../reference/contract-stability.md) makes a new major version.
 
 Each value is a path pattern relative to the folder that holds
 `atelier.project.json`, in the dialect the boundary policy's `forbiddenPaths`
@@ -287,13 +287,13 @@ are reviewable. Refresh it from inside the copied workspace after choosing a
 registry or Git tag install. Local tarballs remain release-audit and
 smoke-test tools; they are not the default install path.
 
-See `docs/tenant-readiness.md` for the readiness review format and
-`docs/upgrade.md` for the full upgrade flow and boundary review checklist.
+See `docs/guides/tenant-readiness.md` for the readiness review format and
+`docs/guides/upgrade.md` for the full upgrade flow and boundary review checklist.
 
 ## External source adapters and local review
 
 Use `atelier init --template external-project --target NEW_DIRECTORY` for the
-invented adapter/source starter. See [local review](local-review.md) for the
+invented adapter/source starter. See [local review](../guides/local-review.md) for the
 complete installed workflow, source ownership, asserted identity and save/resume.
 `atelier lock provenance` distinguishes declared install origin, observed package
 bytes and verified clean-checkout binding. It never substitutes the consumer

package/docs/{knowledge-setup.md → start/knowledge-setup.md}

@@ -49,7 +49,7 @@ boundary. These commands do not implement recipient authorization or sharing.
    records cannot satisfy retrieval coverage. Duplicate mappings of a predicate
    and concept pair are refused; use assertion records for distinct meanings.
 5. Keep a small permitted slice of originals. Use Markdown front matter or
-   adjacent sidecars as described in [the source graph](knowledge-graph.md).
+   adjacent sidecars as described in [the source graph](../reference/knowledge-graph.md).
    Use `atelier adopt` for an existing workspace; do not initialize over it.
    Copy and adapt the starter plan, then use `--plan FILE` if it lives elsewhere.
 6. Compare retrieval on the questions before adding a model, vector index, or
@@ -64,7 +64,7 @@ boundary. These commands do not implement recipient authorization or sharing.
 For a real workspace, replace every fictional record, role, and case. In the
 starter, roles are examples and source rights are assumed only for its invented
 content. Add repository boundary policies and hooks through the existing
-[boundary workflow](repo-boundary-guard.md) when collaborating across trust domains.
+[boundary workflow](../reference/repo-boundary-guard.md) when collaborating across trust domains.
 Use actual access controls at the consuming host.
 
 ## Domain ontology and source graph are different layers
@@ -140,7 +140,7 @@ not a claim that the real-world fact does not exist. When search misses a
 qualification that a source owner has selected, a trusted host can read the
 complete cited unit exactly from an ingestion plan that includes the source
 with a completed attempt; see
-[read a complete selected citation](evidence-navigation.md#read-a-complete-selected-citation).
+[read a complete selected citation](../reference/evidence-navigation.md#read-a-complete-selected-citation).
 The line locations in this packet are not ingestion `line` locators: ingestion
 also splits on a lone CR and removes a leading BOM (U+FEFF). Map them
 explicitly; a wrong mapping fails safe, because the hash check withholds the
@@ -197,14 +197,14 @@ for that evidence.
 Use `atelier dev --knowledge` after graph/build to work through Onboard, Model,
 Deepen, Apply, and Learn. The browser and `knowledge session` CLI share
 source-bound private drafts, confirmation, and recovery. See
-[knowledge workspaces](knowledge-workspace.md) for the complete flow and limits.
+[knowledge workspaces](../guides/knowledge-workspace.md) for the complete flow and limits.
 
 ## Recording a host's semantic extraction
 
 `atelier knowledge semantic` records an extraction that your own tool or model
 ran, so a receiver can review it against the exact source. Atelier never runs
 the extraction. The runner, its request shapes and the receiver journey are
-described in [semantic operation](semantic-operation.md); this section covers
+described in [semantic operation](../reference/semantic-operation.md); this section covers
 the command.
 
 - Run it in the Git workspace where `atelier ingest` planned and ran the

package/docs/{research-starter-quickstart.md → start/research-starter-quickstart.md}

@@ -1,7 +1,7 @@
 # Start a research workspace
 
 This packet works with any topic and research tool. Read
-[the six-stage research starter](research-starter.md) for the prompts. The package
+[the six-stage research starter](../guides/research-starter.md) for the prompts. The package
 provides local evidence custody, governance, skills and contracts; your selected
 research tool and reviewers supply research and judgment.
 
@@ -45,11 +45,11 @@ compatibility and plan a destination-specific adoption. An installed skill is
 not automatically active in an agent. Keep local instructions and custom skills;
 review a concrete adoption plan before applying its exact digest.
 
-Use [ingestion](ingestion.md) for bounded local captures and
-[Knowledge and Build](learning-harnesses.md) for the current governed
-workflow. Practical lessons use [Practical Judgment](practical-judgment.md).
-[Trackables](trackables.md), [Interaction and Reflection](interaction-and-reflection.md)
-and [Coordination](coordination.md) describe supported reference profiles and
+Use [ingestion](../guides/ingestion.md) for bounded local captures and
+[Knowledge and Build](../guides/learning-harnesses.md) for the current governed
+workflow. Practical lessons use [Phronesis — practical judgment](../reference/phronesis.md).
+[Trackables](../reference/trackables.md), [Interaction and Reflection](../reference/interaction-and-reflection.md)
+and [Coordination](../reference/coordination.md) describe supported reference profiles and
 what an actual host must implement.
 
 ## What successful completion looks like

package/fixtures/atelier-architecture/catalog/invalid/document.json

@@ -27,9 +27,9 @@
     {
       "id": "practical-judgment",
       "kind": "responsibility",
-      "label": "Practical Judgment",
+      "label": "Phronesis",
       "aliases": [
-        "Phronesis"
+        "Practical Judgment"
       ],
       "purpose": "Discern fitting action, cultivate practice and learn from consequences.",
       "implementation": [

package/fixtures/atelier-architecture/catalog/valid/document.json

@@ -27,9 +27,9 @@
     {
       "id": "practical-judgment",
       "kind": "responsibility",
-      "label": "Practical Judgment",
+      "label": "Phronesis",
       "aliases": [
-        "Phronesis"
+        "Practical Judgment"
       ],
       "purpose": "Discern fitting action, cultivate practice and learn from consequences.",
       "implementation": [