@mnstry/atelier 0.2.0-alpha.1

package/contracts/git-promote-event.v1.schema.json

@@ -0,0 +1,145 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mnstry.ai/schemas/atelier/git-promote-event.v1.schema.json",
+  "$comment": "contract revision 1.1.0 (contract-stability epoch)",
+  "title": "Atelier Git Promote Event",
+  "description": "Append-only local Git disclosure event for promoting a source from one repo/read boundary to another.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "source",
+    "target",
+    "event"
+  ],
+  "properties": {
+    "schema": {
+      "const": "git-promote-event@v1"
+    },
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+\\.[0-9]+$"
+    },
+    "source": {
+      "$ref": "#/$defs/endpoint"
+    },
+    "target": {
+      "$ref": "#/$defs/endpoint"
+    },
+    "event": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "type",
+        "actor",
+        "sourceRepo",
+        "targetRepo",
+        "sourceKgId",
+        "targetKgId",
+        "sourceCommit",
+        "targetCommit",
+        "disclosure_class",
+        "revocable"
+      ],
+      "properties": {
+        "type": {
+          "const": "git.promote"
+        },
+        "actor": {
+          "type": "string",
+          "minLength": 1
+        },
+        "sourceRepo": {
+          "type": "string",
+          "minLength": 1
+        },
+        "targetRepo": {
+          "type": "string",
+          "minLength": 1
+        },
+        "sourceKgId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "targetKgId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "sourceCommit": {
+          "$ref": "#/$defs/commit"
+        },
+        "targetCommit": {
+          "$ref": "#/$defs/commit"
+        },
+        "disclosure_class": {
+          "const": "durable"
+        },
+        "revocable": {
+          "const": false
+        },
+        "ext": {
+          "type": "object",
+          "description": "Reserved extension container. Producers MAY add namespaced members (recommend vendor-prefixed keys). Consumers MUST ignore members they do not recognize. Contents are not validated at v1 and carry no authority over first-class fields."
+        }
+      }
+    },
+    "ext": {
+      "type": "object",
+      "description": "Reserved extension container. Producers MAY add namespaced members (recommend vendor-prefixed keys). Consumers MUST ignore members they do not recognize. Contents are not validated at v1 and carry no authority over first-class fields."
+    }
+  },
+  "$defs": {
+    "commit": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{40}$"
+    },
+    "endpoint": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "repo",
+        "repoAccess",
+        "kgId",
+        "audience",
+        "commit"
+      ],
+      "properties": {
+        "repo": {
+          "type": "string",
+          "minLength": 1
+        },
+        "repoAccess": {
+          "enum": [
+            "private",
+            "team",
+            "operator",
+            "staff",
+            "public",
+            "sensitive"
+          ]
+        },
+        "kgId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "audience": {
+          "enum": [
+            "private",
+            "team",
+            "operator",
+            "staff",
+            "public",
+            "sensitive"
+          ]
+        },
+        "commit": {
+          "$ref": "#/$defs/commit"
+        },
+        "ext": {
+          "type": "object",
+          "description": "Reserved extension container. Producers MAY add namespaced members (recommend vendor-prefixed keys). Consumers MUST ignore members they do not recognize. Contents are not validated at v1 and carry no authority over first-class fields."
+        }
+      }
+    }
+  }
+}

package/contracts/knowledge-source-sidecar.v1.schema.json

@@ -0,0 +1,157 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mnstry.ai/schemas/atelier/knowledge-source-sidecar.v1.schema.json",
+  "$comment": "contract revision 1.1.0 (contract-stability epoch)",
+  "title": "Atelier Source Sidecar",
+  "description": "Committed metadata sidecar for non-Markdown Atelier knowledge graph sources.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "asset",
+    "title",
+    "summary",
+    "tags",
+    "kg"
+  ],
+  "properties": {
+    "schema": {
+      "const": "mnstry.source-sidecar@v1"
+    },
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+\\.[0-9]+$"
+    },
+    "asset": {
+      "description": "Filename of the adjacent non-Markdown asset this sidecar identifies.",
+      "type": "string",
+      "minLength": 1
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "summary": {
+      "type": "string"
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    },
+    "kg": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "type",
+        "domain",
+        "lifecycle",
+        "status",
+        "audience",
+        "relations"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9-]*:[a-z0-9][a-z0-9:._/-]*$"
+        },
+        "type": {
+          "enum": [
+            "html",
+            "pdf",
+            "docx",
+            "artifact",
+            "evidence",
+            "source",
+            "prototype",
+            "research",
+            "report",
+            "manifest"
+          ]
+        },
+        "domain": {
+          "type": "string",
+          "minLength": 1
+        },
+        "lifecycle": {
+          "type": "string",
+          "minLength": 1
+        },
+        "status": {
+          "enum": [
+            "active",
+            "draft",
+            "archived",
+            "template"
+          ]
+        },
+        "audience": {
+          "enum": [
+            "private",
+            "team",
+            "operator",
+            "staff",
+            "public",
+            "sensitive"
+          ]
+        },
+        "relations": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "related": {
+              "$ref": "#/$defs/relationTargets"
+            },
+            "supports": {
+              "$ref": "#/$defs/relationTargets"
+            },
+            "supersedes": {
+              "$ref": "#/$defs/relationTargets"
+            },
+            "implements": {
+              "$ref": "#/$defs/relationTargets"
+            },
+            "depends_on": {
+              "$ref": "#/$defs/relationTargets"
+            },
+            "evidences": {
+              "$ref": "#/$defs/relationTargets"
+            },
+            "contradicts": {
+              "$ref": "#/$defs/relationTargets"
+            },
+            "belongs_to": {
+              "$ref": "#/$defs/relationTargets"
+            },
+            "ext": {
+              "type": "object",
+              "description": "Reserved extension container. Producers MAY add namespaced members (recommend vendor-prefixed keys). Consumers MUST ignore members they do not recognize. Contents are not validated at v1 and carry no authority over first-class fields."
+            }
+          }
+        },
+        "ext": {
+          "type": "object",
+          "description": "Reserved extension container. Producers MAY add namespaced members (recommend vendor-prefixed keys). Consumers MUST ignore members they do not recognize. Contents are not validated at v1 and carry no authority over first-class fields."
+        }
+      }
+    },
+    "ext": {
+      "type": "object",
+      "description": "Reserved extension container. Producers MAY add namespaced members (recommend vendor-prefixed keys). Consumers MUST ignore members they do not recognize. Contents are not validated at v1 and carry no authority over first-class fields."
+    }
+  },
+  "$defs": {
+    "relationTargets": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    }
+  }
+}

package/contracts/mnstry-atelier-semantic-profile.v1.json

@@ -0,0 +1,254 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mnstry.ai/schemas/atelier/mnstry-atelier-semantic-profile.v1.json",
+  "schema": "mnstry-atelier-semantic-profile@v1",
+  "version": "1.0.0",
+  "status": "draft",
+  "updatedAt": "2026-06-12",
+  "purpose": "Machine-readable semantic profile for the MNSTRY Atelier Kit to keep local Git/source vocabulary distinct from MNSTRY runtime authority vocabulary.",
+  "authorityPrinciples": [
+    {
+      "id": "repo-access-read-boundary",
+      "statement": "Git repository access is the hard read boundary for source files. Local audience labels and projection gates do not make a file secret from anyone who can clone or read the repository.",
+      "appliesTo": [
+        "source",
+        "git",
+        "projection"
+      ]
+    },
+    {
+      "id": "runtime-visibility-reserved",
+      "statement": "The word visibility is reserved for the MNSTRY runtime enum and for export artifacts that intentionally carry runtime visibility values.",
+      "appliesTo": [
+        "runtime",
+        "atelier-export@v1"
+      ]
+    },
+    {
+      "id": "local-audience-not-runtime-visibility",
+      "statement": "Local documentation and corpus classification use audience for intended readership/projection eligibility. Audience is not runtime visibility and is not a security boundary inside a readable Git repository.",
+      "appliesTo": [
+        "source",
+        "frontmatter",
+        "projection"
+      ]
+    },
+    {
+      "id": "runtime-dry-run-consumer",
+      "statement": "The first runtime consumer of this profile is the atelier-export@v1 dry-run importer. Until that importer exists, activation claims remain contract-level and fixture-level only.",
+      "appliesTo": [
+        "atelier-export@v1",
+        "runtime"
+      ]
+    }
+  ],
+  "terms": {
+    "audience": {
+      "tier": "local-source",
+      "owner": "atelier",
+      "replacesLocalUseOf": "visibility",
+      "description": "Intended local readership and projection eligibility for Atelier source documents.",
+      "allowedValues": [
+        "public",
+        "team",
+        "operator",
+        "staff",
+        "private",
+        "sensitive"
+      ],
+      "defaultPolicy": "fail-closed; unclassified content must not project publicly",
+      "securityBoundary": false,
+      "notes": [
+        "A private or sensitive audience value does not hide a file from users with Git repository access.",
+        "Projection gates may consume audience, but repository permissions remain the read boundary."
+      ]
+    },
+    "visibility": {
+      "tier": "runtime-authority",
+      "owner": "mnstry-runtime",
+      "description": "Runtime visibility enum on governed MNSTRY objects.",
+      "allowedValues": [
+        "private",
+        "shared",
+        "platform",
+        "public"
+      ],
+      "defaultPolicy": "runtime default is private",
+      "securityBoundary": true,
+      "runtimeReferences": [
+        {
+          "repo": "mnstry",
+          "path": "database/migrations/20260402020000_rebuild_08_core.sql",
+          "notes": "Core object visibility constraints and default private posture."
+        }
+      ],
+      "notes": [
+        "Use this word locally only when representing a runtime/export value verbatim.",
+        "Do not use runtime visibility values to describe source-document readership unless the document is an export fixture or dry-run object."
+      ]
+    },
+    "repo_access": {
+      "tier": "git-backed-analog",
+      "owner": "git-provider",
+      "description": "Actual read/write access to the Git repository or path substrate.",
+      "securityBoundary": true,
+      "allowedValues": [
+        "none",
+        "read",
+        "triage",
+        "write",
+        "maintain",
+        "admin"
+      ],
+      "notes": [
+        "For source files, repo_access determines who can read the material.",
+        "Projection labels cannot reduce access for users who already have repository read permissions."
+      ]
+    },
+    "git.promote": {
+      "tier": "git-backed-analog",
+      "owner": "atelier",
+      "description": "A durable disclosure event that moves or copies source material into a broader Git-readable or projection-eligible container.",
+      "substrate": "git",
+      "revocable": false,
+      "disclosureClass": "durable",
+      "mustNotBeNamed": [
+        "provision",
+        "provisioning_event"
+      ],
+      "notes": [
+        "A git.promote event may be homologous to runtime resource sharing, but it is not a runtime provision.",
+        "Undoing promotion requires a new Git history event and cannot guarantee unread by previous readers."
+      ]
+    },
+    "provision": {
+      "tier": "runtime-authority",
+      "owner": "mnstry-runtime",
+      "description": "Runtime resource-shared-into-space grant, not a local Git disclosure event.",
+      "substrate": "postgres",
+      "revocable": true,
+      "runtimeReferences": [
+        {
+          "repo": "mnstry",
+          "path": "database/migrations/20260402025000_rebuild_13_space.sql",
+          "notes": "space.provisions resource sharing table and validation trigger."
+        }
+      ],
+      "notes": [
+        "Keep the noun provision runtime-reserved.",
+        "Use git.promote for local durable disclosure."
+      ]
+    },
+    "sensitivity": {
+      "tier": "local-source",
+      "owner": "atelier",
+      "replacesLocalUseOf": "data_boundary",
+      "description": "Local handling risk classification for source documents and generated projections.",
+      "securityBoundary": false,
+      "notes": [
+        "Runtime data_boundary remains reserved for space descriptors using runtime enum values.",
+        "Use sensitivity for local document handling until a runtime import object requires data_boundary."
+      ]
+    },
+    "data_boundary": {
+      "tier": "runtime-authority",
+      "owner": "mnstry-runtime",
+      "description": "Runtime sharing-floor enum on spaces.",
+      "allowedValues": [
+        "public_shareable",
+        "member_shareable",
+        "client_visible",
+        "practitioner_private",
+        "specially_protected"
+      ],
+      "runtimeReferences": [
+        {
+          "repo": "mnstry",
+          "path": "database/migrations/20260402025000_rebuild_13_space.sql",
+          "notes": "space.spaces data_boundary values and cross-ministry membership guard."
+        }
+      ],
+      "notes": [
+        "Do not attach runtime data_boundary values to arbitrary source documents unless the object is a runtime space descriptor or export fixture."
+      ]
+    },
+    "egress_intent": {
+      "tier": "local-source",
+      "owner": "atelier",
+      "replacesLocalUseOf": "provider_egress",
+      "description": "Local declaration of intended provider/model/data egress posture before runtime enforcement exists.",
+      "securityBoundary": false,
+      "notes": [
+        "provider_egress is not a verified runtime canonical today.",
+        "Runtime provider controls must be represented by explicit runtime import fields when they exist."
+      ]
+    },
+    "runtime_object": {
+      "tier": "local-projection-of-runtime-canonical",
+      "owner": "atelier",
+      "replacesLocalUseOf": "semantic_object",
+      "description": "Local pointer to a real runtime table/object family.",
+      "allowedValueExamples": [
+        "content.material",
+        "core.artifact",
+        "core.thread",
+        "core.session",
+        "core.trackable",
+        "space.space"
+      ],
+      "allowedExportTargets": [
+        "content.material",
+        "core.artifact",
+        "core.trackable",
+        "scheduling.commitment",
+        "space.space",
+        "space.provision"
+      ],
+      "notes": [
+        "semantic_object is not a verified runtime canonical.",
+        "Team architecture documents should not default to core.artifact without an explicit personal-actor-content rationale."
+      ]
+    }
+  },
+  "optionalAdapters": {
+    "analysis": {
+      "status": "optional-experimental",
+      "role": "derived-discovery-graph",
+      "authority": "none",
+      "mayAnalyze": [
+        "allowlisted source repositories",
+        "sanitized contract fixtures",
+        "generated public or team-safe exports",
+        "development-only architecture maps"
+      ],
+      "mustNotAnalyzeOrGovern": [
+        "live runtime authority",
+        "production customer or member data",
+        "consent records",
+        "bookings, payments, refunds, or commerce truth",
+        "permission decisions",
+        "raw tenant-private runtime exports"
+      ],
+      "modelProviderPolicy": "model-assisted analysis must run through the active agentic harness and must not introduce a hidden model provider, second API key, or second inference boundary.",
+      "promotionRule": "Adapter suggestions become canonical only after reviewed promotion into source front matter or a governed runtime import path."
+    }
+  },
+  "consumers": {
+    "sourceValidation": {
+      "status": "implemented-in-sample-ops",
+      "description": "build-knowledge-graph.mjs validates mandatory kg.audience, rejects legacy kg.visibility, and checks declared graph relations."
+    },
+    "projectionGate": {
+      "status": "implemented-for-local-projections",
+      "description": "projection-policy.mjs gates public/team/operator/local graph, alignment, API, and export source eligibility."
+    },
+    "atelierExportV1": {
+      "status": "graph-resolved-fixture-level",
+      "description": "contracts:check resolves sourceRefs/sourceNodes against the Atelier knowledge graph and fails public objects with non-public source kgIds."
+    },
+    "runtimeDryRunImporter": {
+      "status": "implemented-non-mutating-dry-run",
+      "description": "MNSTRY runtime worktree provides a non-mutating atelier-export@v1 dry-run validator for enum/classification alignment."
+    }
+  }
+}

package/docs/announcements.md

@@ -0,0 +1,101 @@
+# Announcements
+
+MNSTRY communicates with kit users through signed announcement documents
+committed under `announcements/` in this repository. The channel is
+pull-only: an announcement reaches you when you run `git pull`, and pulling
+is the consent act. There is no push channel, no subscription list, no
+beacon, and no delivery receipt — and none is ever created.
+
+## The promise
+
+This channel is one-way, outbound from MNSTRY. It carries no tracking of any
+kind: reading, verifying, or ignoring an announcement produces no signal
+back to MNSTRY. The kit never fetches this channel — no command, hook, or
+background process contacts a network to look for announcements. The only
+transport is the git history you already chose to pull.
+
+## Document shape
+
+An announcement is a JSON document with the runtime-defined shape
+`mnstry.announcement@v1` (validated structurally in code by the verify path;
+deliberately not a `contracts/` schema, so the governed contract corpus
+stays stable):
+
+- `schema` — the constant `mnstry.announcement@v1`.
+- `announcementId` — a stable identifier with the `announcement:` prefix.
+- `publishedAt` — an ISO date string.
+- `title` — a non-empty string.
+- `body` — the announcement text, as markdown.
+- `signature` — a detached signature (`algorithm`, `keyId`, `value`), or
+  null only while unsigned. An unsigned announcement never verifies.
+
+Announcement files live directly in `announcements/`, named
+`YYYY-MM-DD-<slug>.v1.json`. The MNSTRY announcements public key is
+committed at `announcements/keys/mnstry-announcements.public.v1.json`; the
+private half is never in this repository and CI only ever verifies — it
+never re-signs.
+
+## Signing rule
+
+The signature covers the UTF-8 encoding of the RFC 8785 (JCS)
+canonicalization of the document with its `signature` member set to null —
+the same normative rule the attestation flow uses (see
+`docs/attestation.md`). The shared implementation is
+`signDocument`/`verifyDocument` in `src/attestation/sign.mjs`.
+
+## Verifying announcements
+
+List and verify everything at once:
+
+    atelier announcements list
+
+Every run opens with the key it verified against — the package-relative key
+path, the `keyId`, and whether that key is the committed default:
+
+    key: announcements/keys/mnstry-announcements.public.v1.json (keyId mnstry-announcements-2026, committed default key)
+
+Each verified announcement then prints its id, date, and title. A file that
+does not verify is flagged loudly and fails the exit code; treat its content
+as not from MNSTRY.
+
+`--dir DIR` changes only which documents are read. It never relocates the
+trust anchor: `list` verifies against the same committed key that `verify`
+and `show` use, so a public key sitting inside the directory being listed is
+ignored. Pointing `list` at an untrusted copy of an announcements tree is
+therefore safe — a forgery signed with a key planted in that tree fails, no
+matter that the key file is named correctly and carries the genuine `keyId`.
+
+Verify a single file (the committed key is the default; pass
+`--public-key FILE` to pin your own copy):
+
+    atelier announcements verify announcements/<file>.json
+
+Read one:
+
+    atelier announcements show announcements/<file>.json
+
+`show` prints the body only after the signature verifies. It refuses —
+without printing any content — otherwise.
+
+## Trust model
+
+- Verification is offline and local. Anyone with the repository can reach
+  the same verdict; no MNSTRY service participates.
+- The trust anchor is always the committed key, or a key you explicitly
+  passed with `--public-key`. Nothing else can become the anchor — in
+  particular no directory option, and no key file found next to the
+  documents being checked. A key that travels with the documents it signs
+  proves only that whoever wrote those documents also wrote that key.
+- Every `list` run names its anchor, so a non-default key is stated rather
+  than assumed. If the header does not say `committed default key`, the
+  verdicts came from a key you passed.
+- The committed public key travels with the repository. If you want
+  protection against a compromised repository rewriting both the key and
+  the announcements together, pin a known-good copy of the public key out
+  of band and pass it with `--public-key`.
+- The private half of the announcements key is not in this repository, and
+  a test sweeps every JSON under `announcements/` for a JWK private member
+  to keep it that way. CI only ever verifies; it never signs.
+- A document under `announcements/` that fails verification is noise, not
+  an announcement. The tooling never presents unverified content as if it
+  were from MNSTRY.

package/docs/atelier-runtime.md

@@ -0,0 +1,34 @@
+# MNSTRY Atelier Runtime
+
+MNSTRY Atelier is a local-first authoring and collaboration surface for
+Git-backed project workspaces. It prepares semantic meaning locally and keeps
+runtime enforcement in MNSTRY.
+
+The package owns reusable mechanics:
+
+- project configuration and adapter resolution;
+- knowledge graph indexing from front matter and sidecars;
+- generated workspace projections;
+- local sidecar serving over loopback only;
+- agent-harness context envelopes;
+- proposal-only collaboration metadata;
+- support-bundle dry runs with no send path;
+- export dry-run validation for `atelier-export@v1`.
+
+Project adapters own project facts: repo roster, source roots, read-boundary
+config, extension packs, brand language, and generated project outputs.
+
+## Local Authority
+
+Local files plus Git are the source authority. Generated JSON, HTML, SQLite,
+API, and support-bundle outputs are projections. Local view policies are not
+runtime permissions. Runtime-grade identity, consent, visibility, provision,
+bookings, commerce, sessions, audit, and client-grade sharing remain MNSTRY
+runtime authority.
+
+## Safety Posture
+
+The default package posture is no telemetry, no external network egress, no
+runtime mutation, no browser apply endpoint, and no model-assisted analysis execution.
+Provider analysis output may only enter as proposed `atelier-claim@v1` records
+until explicitly reviewed by the project owner.