@mnstry/atelier 0.2.0-alpha.1

package/docs/repo-boundary-guard.md

@@ -0,0 +1,199 @@
+# Repo Boundary Guard V1
+
+Repo Boundary Guard V1 is the Atelier workspace convention for separating
+private domain source from shared project source before anything reaches the
+MNSTRY runtime.
+
+## Boundary Model
+
+- Private domain material lives in one private Git repository per user.
+- Shared project material lives in shared project repositories.
+- Git repository access is the source read boundary.
+- `kg.audience` is local projection metadata, not a permission system.
+- Runtime/export `visibility` remains reserved for MNSTRY runtime objects.
+
+If a file is private, place it in the user's private domain repo. Do not rely on
+front matter, generated projections, readiness output, browser views, or local
+HTML hiding to protect source material inside a shared repo.
+
+## Guard Rules
+
+- Private or sensitive source belongs in a repo with `readBoundary: "private"`.
+- Shared project source may use `team`, `operator`, `staff`, or `public`
+  audiences when the repository readership matches that exposure.
+- Local source metadata must use `kg.audience`.
+- Local source metadata must not use `kg.visibility`.
+- Dry-run exports may contain runtime `visibility` only on export/runtime
+  objects.
+- Generated outputs are projections and should be reproducible from source.
+
+## External Repos
+
+Real workspaces accumulate git folders that are not Atelier repos: vendored
+checkouts, app-builder exports, scratch clones. Declare one in
+`atelier.project.json` with `kind: "external"`:
+
+```json
+{ "name": "external-vendor-site", "path": "external-vendor-site", "kind": "external" }
+```
+
+An external repo is acknowledged, not managed. It implies **no** read boundary,
+so it must not declare `readBoundary`, must not appear in `repo-access.v1.json`,
+and must not appear in the boundary policy — declaring a boundary for a repo
+nobody manages is exactly the confusion this classification removes. Its files
+are excluded from graph walking, sidecar requirements, and projection, and the
+staged guard and hook installer skip it entirely.
+
+An undeclared git folder in the workspace remains an error. Forcing an explicit
+decision is the point: it is how a repo pushing to an unexpected host gets
+noticed. `atelier graph` prints the remote host of each external repo for the
+same reason — a workspace should know where its folders push, especially when a
+host is a lookalike of a familiar one.
+
+At least one repo must remain managed; a workspace of only external repos is
+not an Atelier workspace.
+
+## Staged Boundary Field Review
+
+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`.
+
+It distinguishes two cases:
+
+- **Initialization.** A boundary field added with no prior value, set to a
+  value that discloses nothing (`private` or `sensitive` for `audience`), is
+  recorded as a fail-closed default rather than a disclosure decision. It
+  commits without review. This is what tooling writes when it fills in missing
+  front matter, so kit-generated metadata never needs a human to unjam it.
+- **Change.** Anything else — widening, narrowing, removing an existing value,
+  or introducing a field already set to a disclosing value — needs a human.
+
+To approve a change, put a review marker in the diff:
+
+```
+<!-- Atelier-Boundary-Review: approved — why this exposure is correct -->
+```
+
+The marker must travel **in the same file's diff** as the change it approves.
+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.
+
+## Non-Goals
+
+Repo Boundary Guard V1 does not:
+
+- create, invite, or permission GitHub users;
+- move files between repositories automatically;
+- write to the MNSTRY runtime;
+- send telemetry;
+- contact cloud services;
+- mutate browser state or write directly from a browser view.
+
+## Review Checklist
+
+Use this as a defensive review before copying preview content into real repos:
+
+- Every private user has exactly one private domain repo entry.
+- Private domain repos use `readBoundary: "private"`.
+- Shared project repos do not contain private or sensitive source nodes.
+- `rg -n "kg.visibility|visibility:"` over source files finds no local source
+  front matter misuse.
+- `repo-access.v1.json` covers every repo listed in `atelier.project.json`.
+- `atelier.lock.json` is written in the copied workspace with
+  `atelier lock write`, not copied from the package root.
+- Generated `atelier-output/` files are not treated as source authority.
+
+When in doubt, fail closed: move the source into the private domain repo first,
+then project a reviewed summary into shared project material later.
+
+## Upgrade Review
+
+When upgrading a copied workspace, review package, lockfile, and boundary
+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.
+
+## Repo Identity
+
+Every Atelier-side reference to a repository used to key on its name. Hosting
+providers let repos be renamed and redirect the old URL indefinitely, so a
+rename leaves stale clones that keep fetching happily under a name that no
+longer exists — the failure is silent, which is why two client-zero repos stopped
+syncing for weeks before anyone noticed.
+
+Record a provider-stable identity in `atelier.project.json`:
+
+```json
+{
+  "name": "studio-journal",
+  "path": "studio-journal",
+  "readBoundary": "team",
+  "identity": { "provider": "github", "id": "900001" },
+  "aliases": ["journal", "press"]
+}
+```
+
+Get the id with `gh api repos/{owner}/{name} --jq .id`. It survives renames;
+the name does not.
+
+`resolveRepoIdentity(cloneDir)` answers from the provider's stable id when the
+provider is reachable, then from the recorded identity, then from declared
+aliases, and reports which of those it used in `source` rather than guessing
+silently. **It never keys on the root commit.** Repos created from one template
+share a root commit, so that heuristic reports false duplicates; it also cannot
+see a rename at all. A rename is a metadata update, not a new identity.
+
+`atelier doctor` reports:
+
+- `repo-renamed-upstream` — the provider's canonical name has moved on
+- `repo-folder-name-stale` — the config name is not the canonical name
+- `repo-name-alias-deprecated` — resolved through a recorded alias
+- `repo-identity-duplicate` — two clones are one repository; park the retired one
+- `repo-identity-undeclared` — no recorded id, so a rename during an outage is unresolvable
+- `repo-identity-unresolved` — no origin remote to identify the clone by
+
+## Content Rules and Exceptions
+
+Content rules judge **what is being pushed**, not the whole tree. A whole-tree
+scan cannot tell "you are about to push a new violation" from "a known, accepted
+usage exists", so one legitimate use anywhere blocks every push of everything in
+that repo, forever — including work that has nothing to do with the finding.
+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.
+- `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.
+- `atelier boundary audit` scans the whole tree and **reports without blocking**,
+  listing both matches and declared exceptions with their reasons.
+
+If the guard cannot work out which repo it is running in, it fails closed. A
+guard that silently judges nothing is worse than one that stops you.
+
+### Declaring an exception
+
+Exceptions live in the boundary policy, not in the guard script. A repo-specific
+product decision must not require editing shared infrastructure that every repo
+runs:
+
+```json
+"contentRuleExceptions": [
+  {
+    "rule": "browser-persistence",
+    "repo": "example-site",
+    "paths": ["src/scripts/cart.ts"],
+    "reason": "owner-authorized mock cart on a public demo site; localStorage is its whole design"
+  }
+]
+```
+
+Every field is required, because the exception **is** the approval record. There
+is no blanket repo-wide skip: `paths` must name real paths, and a bare `*` or
+`**` is rejected as disabling the rule rather than excepting it. `reason` must
+say something a reviewer can act on. Removing the exception re-blocks the path.

package/docs/tenant-readiness.md

@@ -0,0 +1,64 @@
+# Tenant Readiness Guide
+
+Use this guide when preparing a tenant or project workspace for an Atelier
+readiness review. The review is local-only and evidence-first: it does not
+provision repositories, contact external services, mutate a MNSTRY runtime, or
+write through a browser view.
+
+## Authority Order
+
+1. Treat local source files, Git history, `atelier.project.json`,
+   `repo-access.v1.json`, `boundary-policy.v1.json`, and `atelier.lock.json` as
+   review authority.
+2. Treat generated graph, projection, support, and readiness files as evidence
+   from the current package checks.
+3. Treat optional model/provider analysis as proposed `atelier-claim@v1`
+   records only. Proposed claims cannot define tenant semantics, mutate
+   canonical source, or bypass project-owner review.
+4. Treat runtime identity, consent, visibility, provisioning, bookings,
+   commerce, sessions, audit, and client-grade sharing as MNSTRY runtime
+   authority.
+
+## Local Review Pass
+
+Run checks from the copied workspace:
+
+```bash
+atelier graph --project ./atelier.project.json
+atelier project --project ./atelier.project.json
+atelier readiness --project ./atelier.project.json
+atelier boundary check --project ./atelier.project.json
+atelier lock check --project ./atelier.project.json
+atelier upgrade --dry-run --project ./atelier.project.json
+```
+
+Use `--check` modes where available when validating committed generated output.
+If a command is unavailable in an older workspace, report the exact command and
+stderr instead of substituting a new protocol.
+
+## Claim-First Output
+
+Readiness summaries should lead with claims, then evidence:
+
+- Claim: the specific readiness statement.
+- Evidence: file paths, schema names, command output, or observed generated
+  artifact state.
+- Authority: source, generated evidence, proposed claim, or runtime-owned.
+- Status: ready, warning, blocked, or proposed.
+- Fix path: the smallest next reviewable change.
+
+Do not invent independent tenant semantics. Use the Atelier contracts,
+readiness report, boundary policy, and local source as the vocabulary.
+
+## Review Hygiene
+
+- Keep package docs, fixtures, skills, and release notes generic.
+- Do not include person-specific, tenant-private, project-private, support
+  bundle, transcript, absolute local path, agent-local state, key, token, or
+  credential material.
+- Prefer static inspection and existing defensive tests for security-sensitive
+  review work.
+- Frame boundary checks as verifying that a control refuses, blocks, or fails
+  closed.
+- Findings still need concrete evidence, severity, confidence, impact, and a
+  fix path.

package/docs/upgrade.md

@@ -0,0 +1,124 @@
+# Upgrade Guide
+
+Use this guide when upgrading a copied private-domain or shared-project starter
+workspace between Atelier package releases. The flow is local-only: it does not
+provision repositories, contact a Git host, mutate the MNSTRY runtime, or write
+through a browser view.
+
+## Upgrading to 0.2.0-alpha.1
+
+No contract changes and no authored-content changes: documents valid against
+`0.2.0-alpha.0` remain valid, and `npm run contract:compat` is clean against
+the same epoch baseline. Upgrading is a dependency bump.
+
+Two things worth knowing. The package is now on the npm registry, so the
+install command changes from a Git reference to `@mnstry/atelier@0.2.0-alpha.1`
+— keep the `@mnstry/` scope, since the unscoped name belongs to an unrelated
+package. And a local sidecar that previously exited on a malformed request now
+answers it, so anything that supervised `atelier dev` through restarts can stop
+compensating for that.
+
+## Upgrading to 0.2.0-alpha.0
+
+This release breaks the export vocabulary. The runtime owner names are now
+the vendor-neutral domain terms `identity`, `catalog`, `commitments`,
+`events`, `projection`, `consent`, `messaging`, `providers`, and `audit`
+(defined in `docs/ontology.md`), and documents written against
+`v0.1.0-alpha.2` do not validate here. Regenerate exports and projections rather than hand-editing
+them, and update any consumer that pins an owner name. `CHANGELOG.md` lists
+every breaking change in this release, including the contract-stability epoch
+(`contractVersion`, `ext`) and the schema const alignments.
+
+Contract compatibility is now gated. `npm run contract:compat` validates the
+current corpus against the validators of the baseline recorded in
+`contracts/compat-baseline.json`. The baseline is set at release time: cutting
+a tag sets `baselineTag` to that tag in the release commit, so the following
+development cycle is checked against the released validators. Until the first
+post-epoch tag is cut the baseline is null and the gate is inert by design.
+See `docs/contract-stability.md`.
+
+## Before You Upgrade
+
+- Start from a clean Git status in the copied workspace.
+- Confirm Node.js matches the package range: `>=22.18.0 <23`.
+- Keep this package root and copied starter workspaces separate.
+- Keep upgrade diffs generic: placeholders only, no project-specific private
+  material, transcripts, support bundles, local absolute paths, local agent
+  state, keys, or credential assignments.
+
+## Refresh The Atelier Lockfile
+
+`atelier.lock.json` records the installed Atelier package version, source,
+contract versions, template lineage, extension packs, and applied migrations.
+New workspaces get this file from `atelier init`. Existing workspaces can
+backfill it without changing source content:
+
+```bash
+atelier lock write --project ./atelier.project.json
+atelier lock check --project ./atelier.project.json
+```
+
+For registry installs, pin the exact version and record the resolved version
+in the lockfile:
+
+```bash
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.1
+npx atelier lock write --project ./atelier.project.json
+```
+
+For Git installs, pin the release tag rather than a branch, so the lock file
+records exactly what was reviewed:
+
+```bash
+npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.1"
+npx atelier lock write --project ./atelier.project.json
+```
+
+Before accepting upstream changes, run the non-mutating upgrade planner:
+
+```bash
+atelier upgrade --dry-run --project ./atelier.project.json
+```
+
+Apply upgrades only after reviewing the plan:
+
+```bash
+atelier upgrade --apply --project ./atelier.project.json
+```
+
+The apply path creates a branch, refuses unsafe dirty state, regenerates
+projections, runs checks, and leaves a reviewable commit.
+
+## Re-run Local Checks
+
+Run checks from the copied workspace after refreshing dependencies:
+
+```bash
+atelier graph --project ./atelier.project.json
+atelier project --project ./atelier.project.json
+atelier readiness --project ./atelier.project.json
+atelier lock check --project ./atelier.project.json
+atelier upgrade --dry-run --project ./atelier.project.json
+atelier boundary check --project ./atelier.project.json
+atelier boundary check --staged --project ./atelier.project.json
+```
+
+Generated `atelier-output/` files are projections. Treat source files,
+`atelier.project.json`, `repo-access.v1.json`, `boundary-policy.v1.json`, and
+`atelier.lock.json` as the review authority.
+
+`atelier` is the primary command. `mnstry-atelier` remains a legacy alias for
+older workspaces and should not be used in new docs or package scripts.
+
+## Boundary Review
+
+- Verify every repo in `atelier.project.json` is covered by `repo-access.v1.json`.
+- Verify private-domain repos still use `readBoundary: "private"`.
+- Verify shared-project repos do not contain private or sensitive source nodes.
+- Verify local source front matter uses `kg.audience`, not `kg.visibility`.
+- Verify upgrade diffs do not add project-specific private material to package
+  docs, fixtures, or templates.
+
+When unsure, fail closed: keep source in the private-domain workspace and move
+only a reviewed summary into the shared-project workspace through ordinary Git
+review.

package/fixtures/analysis/invalid/native-graph.v1.json

@@ -0,0 +1,4 @@
+{
+  "nodes": [],
+  "edges": []
+}

package/fixtures/analysis/invalid/promoted-claim.v1.json

@@ -0,0 +1,17 @@
+[
+  {
+    "schema": "atelier-claim@v1",
+    "claimId": "claim:analysis:2026-06-17:test",
+    "subject": "project:source-node",
+    "predicate": "supports",
+    "object": "project:claim-target",
+    "provider": "analysis",
+    "status": "proposed",
+    "promoted": true,
+    "confidence": 0.6,
+    "evidence": [
+      "docs/source.md#claim"
+    ],
+    "createdAt": "2026-06-17T00:00:00Z"
+  }
+]

package/fixtures/analysis/invalid/runtime-import.v1.json

@@ -0,0 +1,20 @@
+[
+  {
+    "schema": "atelier-claim@v1",
+    "claimId": "claim:analysis:2026-06-17:test",
+    "subject": "project:source-node",
+    "predicate": "supports",
+    "object": "project:claim-target",
+    "provider": "analysis",
+    "status": "proposed",
+    "promoted": false,
+    "confidence": 0.6,
+    "evidence": [
+      "docs/source.md#claim"
+    ],
+    "createdAt": "2026-06-17T00:00:00Z",
+    "runtimeImport": {
+      "mode": "apply"
+    }
+  }
+]

package/fixtures/analysis/valid/output.claims.v1.json

@@ -0,0 +1,17 @@
+[
+  {
+    "schema": "atelier-claim@v1",
+    "claimId": "claim:analysis:2026-06-17:test",
+    "subject": "project:source-node",
+    "predicate": "supports",
+    "object": "project:claim-target",
+    "provider": "analysis",
+    "status": "proposed",
+    "promoted": false,
+    "confidence": 0.6,
+    "evidence": [
+      "docs/source.md#claim"
+    ],
+    "createdAt": "2026-06-17T00:00:00Z"
+  }
+]

package/fixtures/analysis-adapter/invalid/manifest-hidden-provider.v1.json

@@ -0,0 +1,24 @@
+{
+  "schema": "analysis-adapter-manifest@v1",
+  "provider": "analysis",
+  "enabled": true,
+  "outputRoot": ".mnstry/atelier/analysis/output",
+  "claimContract": "atelier-claim@v1",
+  "harness": {
+    "policy": "active-agentic-harness-only",
+    "hiddenModelProvider": true,
+    "network": "none",
+    "analysisExecution": false,
+    "modelProvider": "openai"
+  },
+  "canonicalMutation": false,
+  "authority": {
+    "claimOnly": true,
+    "frontMatterMutation": false,
+    "graphRelationMutation": false,
+    "publicExportFeed": false,
+    "mcpFeed": false,
+    "runtimeImport": false,
+    "directCanonicalWrite": false
+  }
+}

package/fixtures/analysis-adapter/invalid/output-frontmatter-mutation.v1.json

@@ -0,0 +1,21 @@
+[
+  {
+    "schema": "atelier-claim@v1",
+    "claimId": "claim:analysis:2026-06-12:invalid-frontmatter",
+    "subject": "sample-architecture:atelier-analysis-optional-install-decision",
+    "predicate": "supports",
+    "object": "sample-architecture:local-git-generated-db-hybrid",
+    "provider": "analysis",
+    "status": "proposed",
+    "promoted": false,
+    "frontmatter": {
+      "kg": {
+        "relations": {
+          "supports": [
+            "sample-architecture:local-git-generated-db-hybrid"
+          ]
+        }
+      }
+    }
+  }
+]

package/fixtures/analysis-adapter/invalid/output-native-graph.v1.json

@@ -0,0 +1,14 @@
+{
+  "nodes": [
+    {
+      "id": "sample-architecture:atelier-analysis-optional-install-decision"
+    }
+  ],
+  "edges": [
+    {
+      "source": "sample-architecture:atelier-analysis-optional-install-decision",
+      "target": "sample-architecture:local-git-generated-db-hybrid",
+      "type": "supports"
+    }
+  ]
+}

package/fixtures/analysis-adapter/manifest.disabled.v1.json

@@ -0,0 +1,22 @@
+{
+  "schema": "analysis-adapter-manifest@v1",
+  "provider": "analysis",
+  "outputRoot": ".mnstry/atelier/analysis/output",
+  "claimContract": "atelier-claim@v1",
+  "harness": {
+    "policy": "active-agentic-harness-only",
+    "hiddenModelProvider": false,
+    "network": "none",
+    "analysisExecution": false
+  },
+  "canonicalMutation": false,
+  "authority": {
+    "claimOnly": true,
+    "frontMatterMutation": false,
+    "graphRelationMutation": false,
+    "publicExportFeed": false,
+    "mcpFeed": false,
+    "runtimeImport": false,
+    "directCanonicalWrite": false
+  }
+}

package/fixtures/analysis-adapter/manifest.enabled-local.v1.json

@@ -0,0 +1,23 @@
+{
+  "schema": "analysis-adapter-manifest@v1",
+  "provider": "analysis",
+  "enabled": true,
+  "outputRoot": ".mnstry/atelier/analysis/pilot",
+  "claimContract": "atelier-claim@v1",
+  "harness": {
+    "policy": "active-agentic-harness-only",
+    "hiddenModelProvider": false,
+    "network": "none",
+    "analysisExecution": false
+  },
+  "canonicalMutation": false,
+  "authority": {
+    "claimOnly": true,
+    "frontMatterMutation": false,
+    "graphRelationMutation": false,
+    "publicExportFeed": false,
+    "mcpFeed": false,
+    "runtimeImport": false,
+    "directCanonicalWrite": false
+  }
+}

package/fixtures/analysis-adapter/output.claims.v1.json

@@ -0,0 +1,21 @@
+[
+  {
+    "schema": "atelier-claim@v1",
+    "claimId": "claim:analysis:2026-06-12:adapter-pilot-supports-local-hybrid",
+    "subject": "sample-architecture:atelier-analysis-optional-install-decision",
+    "predicate": "supports",
+    "object": "sample-architecture:local-git-generated-db-hybrid",
+    "provider": "analysis",
+    "status": "proposed",
+    "promoted": false,
+    "confidence": 0.71,
+    "evidence": [
+      "ATELIER-ANALYSIS-OPTIONAL-INSTALL-DECISION.md#authority-boundary",
+      "LOCAL-GIT-GENERATED-DB-HYBRID.md#optional-discovery-graph-providers"
+    ],
+    "notes": [
+      "Adapter fixture only. This is not model-assisted analysis execution output."
+    ],
+    "createdAt": "2026-06-12T00:00:00Z"
+  }
+]

package/fixtures/atelier-action-intent/invalid/runtime-mutation-authority.v1.json

@@ -0,0 +1,16 @@
+{
+  "schema": "atelier-action-intent@v1",
+  "id": "atelier.action.copy-repo-path",
+  "kind": "copy.repoPath",
+  "label": "Copy repo path",
+  "appliesTo": {
+    "scopes": ["entry"]
+  },
+  "reads": ["kg.id", "repoPath"],
+  "writes": ["clipboard"],
+  "authority": {
+    "label": "Copy only; no runtime mutation",
+    "runtimeMutation": true
+  },
+  "deniedWhen": []
+}

package/fixtures/atelier-action-intent/invalid/unknown-top-level-field.v1.json

@@ -0,0 +1,17 @@
+{
+  "schema": "atelier-action-intent@v1",
+  "id": "atelier.action.copy-repo-path",
+  "kind": "copy.repoPath",
+  "label": "Copy repo path",
+  "appliesTo": {
+    "scopes": ["entry"]
+  },
+  "reads": ["kg.id", "repoPath"],
+  "writes": ["clipboard"],
+  "authority": {
+    "label": "Copy only; no runtime mutation",
+    "runtimeMutation": false
+  },
+  "deniedWhen": [],
+  "applyEndpoint": "/api/apply"
+}

package/fixtures/atelier-action-intent/invalid/writes-beyond-clipboard.v1.json

@@ -0,0 +1,16 @@
+{
+  "schema": "atelier-action-intent@v1",
+  "id": "atelier.action.copy-repo-path",
+  "kind": "copy.repoPath",
+  "label": "Copy repo path",
+  "appliesTo": {
+    "scopes": ["entry"]
+  },
+  "reads": ["kg.id", "repoPath"],
+  "writes": ["clipboard", "filesystem"],
+  "authority": {
+    "label": "Copy only; no runtime mutation",
+    "runtimeMutation": false
+  },
+  "deniedWhen": []
+}

package/fixtures/atelier-action-intent/valid/copy-agent-prompt.v1.json

@@ -0,0 +1,16 @@
+{
+  "schema": "atelier-action-intent@v1",
+  "id": "atelier.action.copy-agent-prompt",
+  "kind": "copy.agentPrompt",
+  "label": "Copy agent prompt",
+  "appliesTo": {
+    "scopes": ["entry", "realm"]
+  },
+  "reads": ["kg.id", "title", "repoPath"],
+  "writes": ["clipboard"],
+  "authority": {
+    "label": "Copy only; no runtime mutation",
+    "runtimeMutation": false
+  },
+  "deniedWhen": []
+}