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

package/README.md

@@ -1,5 +1,7 @@
 # MNSTRY Atelier
 
+`0.2.0-alpha.15` adds a [graph workspace](docs/guides/graph-workspace.md) (a constellation of every readable record, a focused authoring workbench and a review room, built from primitives coaches and owners can compose), renderer-neutral graph views and an [extension SDK and Postgres project workflow](docs/guides/extensions.md). Native host qualification remains a separate gate.
+
 **Turn a repository into a living, governed system.**
 
 Important bodies of work often begin as files: methods, research, programs,
@@ -31,11 +33,15 @@ that must stay legible, internally connected, privacy-aware, and usable across
 many interfaces. Methodology authoring is one application of the system, not
 its definition or ceiling.
 
-See the [responsibility architecture](docs/architecture.md) for Inquiry, Knowledge
-Stewardship, Practical Judgment, Creation and Delivery, Capability Stewardship,
+See the [responsibility architecture](docs/reference/architecture.md) for Inquiry, Knowledge
+Stewardship, [Phronesis — practical judgment](docs/reference/phronesis.md), Creation and Delivery, Capability Stewardship,
 Reflection, Interaction and Coordination. Start a provider-neutral research
-workflow with the [research starter](docs/research-starter.md).
-Use [portable template profiles](docs/template-profile.md) to bind semantic and
+workflow with the [research starter](docs/guides/research-starter.md).
+Knowledge Stewardship is the broader responsibility; the Knowledge Graph is a
+shared representation used across responsibilities. Phronesis draws on and
+contributes to that graph through existing owners. It supplies no automatic
+wisdom or universal score.
+Use [portable template profiles](docs/reference/template-profile.md) to bind semantic and
 surface roles to canonical sources, with optional advisory decisions and
 separate host and release validation.
 
@@ -59,23 +65,23 @@ when a maintainer starts it by hand.
 ## From files to a working system
 
 Start with a question that changes useful work. The
-[knowledge setup workflow](docs/knowledge-setup.md) supplies an editable ontology
+[knowledge setup workflow](docs/start/knowledge-setup.md) supplies an editable ontology
 plan, a fictional starter, and CLI checks that connect concepts to questions.
 `atelier knowledge context` selects complete, source-linked evidence within a
 byte budget; `atelier knowledge evaluate` compares lexical and graph retrieval
 without provider calls. A passing check is structural evidence; useful answers
 and efficient token usage still need measurement in real work.
 
-For local-harness authoring, see [durable coauthor sessions](docs/coauthor-session.md)
-and [skill stewardship and managed installation](docs/skill-steward.md).
-The next-release [capability stewardship foundation](docs/capability-stewardship.md)
+For local-harness authoring, see [durable coauthor sessions](docs/reference/coauthor-session.md)
+and [skill stewardship and managed installation](docs/guides/skill-steward.md).
+The next-release [capability stewardship foundation](docs/guides/capability-stewardship.md)
 adds portable packages, repository-owned adoption and version-bound evidence
 alongside existing skills and tools.
-[Learning from feedback](docs/learning.md) connects private observations to
+[Learning from feedback](docs/guides/learning.md) connects private observations to
 reviewed lessons and explicitly activated harness context, with a local CLI.
-[Progressive local ingestion](docs/ingestion.md) preserves selected sources and
+[Progressive local ingestion](docs/guides/ingestion.md) preserves selected sources and
 provides bounded text, CSV and JSON evidence search before interpretation.
-[Immutable intake and guide contracts](docs/intake-and-guides.md) extend existing
+[Immutable intake and guide contracts](docs/reference/intake-and-guides.md) extend existing
 processing and hosted-tool adapters without adding remote execution or publication
 authority. These alpha capabilities require explicit consumer integration.
 
@@ -94,7 +100,7 @@ governed projections
 You can see the complete loop in a disposable sample workspace:
 
 ```bash
-npm install --save-dev @mnstry/atelier@0.2.0-alpha.13
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.14
 npx mnstry-atelier init --fixture=sample-workspace --target ./sample
 npx mnstry-atelier graph --project ./sample/atelier.project.json
 npx mnstry-atelier project --project ./sample/atelier.project.json
@@ -169,6 +175,42 @@ That distinction matters whenever several interfaces share one body of work.
 A public site, an internal review tool, and an agent session can all use the
 same graph while receiving different, mechanically checked projections.
 
+## Readable by people, checkable by machines
+
+A governed file is plain text with a small header. The text is the author's:
+they open, read and correct it with no tool between them and the words. The
+header is the machine's: what the file is, who it is written for and what it
+depends on, compiled by the builder into the graph. The graph check refuses a
+header that names a node which does not exist (configured external targets
+aside), and an agent follows the same
+lines to every file declared to depend on it. One artifact is both the human
+record and the machine index, versioned by Git, diffable line by line, and
+portable by copying the folder that holds the record and its history.
+
+## One working surface
+
+The day-to-day surface is the coding harness you already use, Claude Code,
+Codex or another coding harness, opened on the repository with the Atelier's
+skills installed in the workspace. Behind it sits the projection served from your files, and
+beyond it whatever systems you connect through the harness. From one
+conversation an agent reaches the local files, the projected pages, and your
+connected tools. The files are yours. The package supplies the graph, the
+checks and the pages. The harness supplies the model, the tools and the
+conversation.
+
+Skills carry the workflows an agent runs: opening a source, guiding an
+authoring session, running a readiness review, keeping the public boundary.
+They are delivered from the package as an audited set of skill files,
+installed into the workspace by a plan whose content digest is confirmed
+before it applies, and pinned by a lock, so the installed skill files are known
+and reviewable. Whether a given harness discovers and follows them is separate
+evidence. Enforcement never rests in a skill. Where they are wired into the
+commit path or CI, the graph check, the boundary guard and the export validator
+run whether or not an agent followed its instructions, and they fail closed. See
+[Co-authoring with agents](docs/guides/co-authoring.md) for the loop this makes
+reliable, and [Describing the Atelier](docs/maintainers/describing-the-atelier.md) for
+the judgment behind these sentences.
+
 ## The system beneath it
 
 ### 1. The repository becomes an ontology
@@ -224,7 +266,7 @@ graph. The library exposes the same project, graph, validation, and projection
 primitives to code.
 
 Consumer-owned authoring or review services that need a separate durable
-lifecycle follow [the managed local-service contract](./docs/local-services.md).
+lifecycle follow [the managed local-service contract](docs/reference/local-services.md).
 That contract standardizes process ownership, private local state, and browser
 recovery without putting a tenant's service details into Atelier.
 
@@ -237,7 +279,7 @@ The separate headless repository supervisor can observe one explicitly
 enrolled Git repository, fetch and fast-forward it, and prepare a bounded
 commit plan. A commit still requires an exact user confirmation and an
 unchanged re-observation; the loopback browser receives no apply endpoint.
-See [Atelier Sync: Deliverable Zero](docs/atelier-sync.md).
+See [Atelier Sync: headless repository supervisor](docs/guides/atelier-sync.md).
 
 ### 5. The repository can power another product
 
@@ -250,9 +292,9 @@ That tool may be private, open source, or commercial. Apache-2.0 permits all
 three. Conformance to the public Atelier contracts does not require a MNSTRY
 account or service.
 
-Read [the design document](./docs/design.md) for the five-part architecture and
-[the ontology](./docs/ontology.md) and
-[contract-stability policy](./docs/contract-stability.md) for the stable
+Read [the design document](docs/reference/design.md) for the five-part architecture and
+[the ontology](docs/reference/ontology.md) and
+[contract-stability policy](docs/reference/contract-stability.md) for the stable
 boundaries.
 
 ## Build your own tool on it
@@ -276,13 +318,30 @@ if (graph.errors.length > 0) throw new Error(graph.errors.join('\n'))
 console.log(graph.nodes)
 ```
 
+Interfaces that need the same control grammar as Atelier's generated tooling
+can import the additive UI subpath. The stylesheet contains no brand copy or
+publication semantics; map its `--system-control-*` properties to the
+consumer's own theme:
+
+```js
+import {
+  atelierControlStyles,
+  renderActionGroup,
+} from '@mnstry/atelier/ui'
+
+const navigation = renderActionGroup([
+  { label: 'Library', href: '/library/' },
+  { label: 'Concepts', href: '/concepts/' },
+], { label: 'Browse the workspace' })
+```
+
 The package exports change over the alpha series, so pin the exact prerelease
 version and treat the package export map and shipped source modules as the
-executable API reference. [Distribution contracts](./docs/distributions.md) explain
+executable API reference. [Distribution contracts](docs/guides/distributions.md) explain
 how a governed subset can be packaged for another surface without widening its
 audience.
 
-The [advisory decision contract](./docs/decisions.md) gives hosts bounded
+The [advisory decision contract](docs/reference/decisions.md) gives hosts bounded
 choice, score and boolean questions with evidence references and recorded
 uncertainty. `@mnstry/atelier/decisions` validates these records offline.
 The host supplies optional provider execution and retains authorization;
@@ -307,10 +366,10 @@ Installation, host discovery and successful exercise are separate evidence.
 Content-free observations can guide improvement, and draft graph records keep
 provenance connected to adoption and outcomes. Publisher authentication, live
 host evaluation and human acceptance require their own evidence. This source
-capability is intended for the next release; alpha.7 does not expose its command.
+capability has shipped as the `capability` command since 0.2.0-alpha.13.
 <!-- atelier:block:capability-stewardship:end -->
 
-See [capability stewardship](docs/capability-stewardship.md) for the operating guide.
+See [capability stewardship](docs/guides/capability-stewardship.md) for the operating guide.
 
 ## Discovery and research
 
@@ -336,7 +395,7 @@ pack retains its Discovery Engine title, identifiers and original digest, so
 existing release locks can use the governed upgrade path without a separate repin.
 <!-- atelier:block:inquiry-harnesses:end -->
 
-See [Discovery and Research Harnesses](docs/inquiry-harnesses.md) for the local workflow.
+See [Discovery and Research Harnesses](docs/guides/inquiry-harnesses.md) for the local workflow.
 
 ## Where the Atelier stops
 
@@ -372,7 +431,7 @@ platform logins must uniquely match declared login mappings. Repository identity
 checks may invoke `gh api repos/...` to resolve a canonical GitHub identity.
 Those authenticated requests use your own `gh` credentials. Recorded repository
 identities let identity checks keep working when the provider is unavailable.
-See `docs/install.md` for the full attribution precedence and mode semantics.
+See `docs/start/install.md` for the full attribution precedence and mode semantics.
 Explicitly enrolled Atelier Sync may also run bounded Git fetches
 for observation/reconciliation and one non-force push only when the exact
 reviewed commit plan requested and confirmed it, no earlier local commit is
@@ -427,7 +486,7 @@ service, no network:
 atelier dry-run ./atelier-export.json
 ```
 
-`docs/continuity.md` records the distribution commitments behind these
+`docs/reference/continuity.md` records the distribution commitments behind these
 claims, including the perpetual Apache-2.0 grant on every tagged release you
 receive.
 <!-- atelier:block:claims:end -->
@@ -469,7 +528,7 @@ Admission is a narrower, opt-in decision: whether a MNSTRY governed runtime
 accepts a document for delivery to the people it serves. That is what
 admission buys — delivery through a runtime that enforces consent and
 visibility at serve time — and it takes the form of a signed MNSTRY
-attestation against criteria this package publishes (`docs/attestation.md`).
+attestation against criteria this package publishes (`docs/reference/attestation.md`).
 The criteria are public, the checker is private, and the rejection message
 is part of the contract. You can build on the Atelier without ever talking
 to MNSTRY, and a document MNSTRY declines can still be fully conformant.
@@ -481,26 +540,17 @@ Node.js 22 (22.18.0 or later) or Node.js 24 (24.13.1 or later) is required.
 Pin the prerelease while the package remains in alpha:
 
 ```bash
-npm install --save-dev @mnstry/atelier@0.2.0-alpha.13
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.14
 ```
 
-Then choose the path that matches what you are building:
-
-- [Installation and first run](./docs/install.md)
-- [Design and architecture](./docs/design.md)
-- [Knowledge graph and source model](./docs/knowledge-graph.md)
-- [Local runtime and agent boundary](./docs/atelier-runtime.md)
-- [Distribution contracts](./docs/distributions.md)
-- [Conformance and attestation](./docs/attestation.md)
-- [Continuity commitments](./docs/continuity.md)
-- [Assurance controls and evidence map](./docs/assurance-controls.md)
-- [Upgrade notes](./docs/upgrade.md)
-- [Upgrade with your agent](./docs/guided-upgrades.md)
-- [Obsidian projection](./docs/obsidian.md)
+Start with [independent setup](./docs/start/independent-start.md) or
+[installation and first run](./docs/start/install.md). The
+[documentation index](./docs/README.md) organizes the maintained guides,
+API and architecture references, and maintainer controls.
 
 ## Status and command reference
 
-Current package: `@mnstry/atelier@0.2.0-alpha.13`.
+Current package: `@mnstry/atelier@0.2.0-alpha.14`.
 
 The alpha package is usable and contract-tested, but its library API may still
 change before a stable release. Pin the exact version in production toolchains.
@@ -541,7 +591,7 @@ MNSTRY Atelier is released under [Apache-2.0](./LICENSE).
 
 ## Experimental hosted vault contract
 
-An optional [private artifact vault service](docs/vault-service.md) supplies a
+An optional [private artifact vault service](docs/reference/vault-service.md) supplies a
 provider-independent ownership boundary and explicit Vercel/Cloudflare storage
 bindings. It is not enabled by local CLI commands. Hosting adapters can perform
 network I/O only when explicitly installed and invoked by a consuming host.
@@ -556,12 +606,12 @@ to its source manually or under a scoped policy the user installs; anything
 structural stays a copy-only proposal. Atelier never commits to Git for it.
 It is disabled unless a project enables it, and it is proven on one platform
 and one app version. Every vault it publishes carries
-[Atelier's own Obsidian plugin](docs/obsidian-plugin.md), which Obsidian asks
+[Atelier's own Obsidian plugin](docs/reference/obsidian-plugin.md), which Obsidian asks
 you to trust once per vault; it shows whether the view is current, writes
 nothing, and talks only to the local maintenance service, and the projection
-works the same without it. Read [what it does and its known limits](docs/obsidian.md),
-the [contract](docs/obsidian-contract.md) and the
-[maintenance service](docs/local-services.md) before relying on it. The
+works the same without it. Read [what it does and its known limits](docs/guides/obsidian.md),
+the [contract](docs/reference/obsidian-contract.md) and the
+[maintenance service](docs/reference/local-services.md) before relying on it. The
 package subpaths are `@mnstry/atelier/obsidian` and
 `@mnstry/atelier/obsidian/*`.
 
@@ -578,22 +628,22 @@ attempts and distinct verification gates. Its coordination proposal can be read
 by Fabric or another adapter. The shared harness contract connects these workflows
 to Discovery, Research and Skill Steward without replacing their domain records.
 
-These are local, provider-neutral source capabilities for the next release.
+These are local, provider-neutral capabilities, shipped since 0.2.0-alpha.13.
 Handoffs preserve exact pins, and explicit source snapshots reveal corrections
 that require downstream reconsideration. Graph outputs remain draft proposals.
 Recorded acceptance is not authenticated authority, and local checks do not prove
 research quality or recipient acceptance. Hosted execution remains adapter-owned.
 <!-- atelier:block:learning-harnesses:end -->
 
-Read the [Knowledge and Build Harness guide](docs/learning-harnesses.md) for the complete local learning cycle.
+Read the [Knowledge and Build Harness guide](docs/guides/learning-harnesses.md) for the complete local learning cycle.
 
-The [research quickstart](docs/research-starter-quickstart.md) explains how to use
+The [research quickstart](docs/start/research-starter-quickstart.md) explains how to use
 a supplied candidate packet with existing tools and skills. See
-[Trackables](docs/trackables.md), [Interaction and Reflection](docs/interaction-and-reflection.md)
-and [Coordination](docs/coordination.md) for portable runtime profiles and host obligations.
+[Trackables](docs/reference/trackables.md), [Interaction and Reflection](docs/reference/interaction-and-reflection.md)
+and [Coordination](docs/reference/coordination.md) for portable runtime profiles and host obligations.
 
-The optional [knowledge workspace](docs/knowledge-workspace.md) connects
+The optional [knowledge workspace](docs/guides/knowledge-workspace.md) connects
 onboarding, ontology modeling, evidence deepening, application, and outcome
 learning with shared private coauthor sessions for people and agents.
 
-The [public workshop profile](docs/knowledge-health/devday/public-default.md) uses the existing Knowledge host to retain ordinary drafts and one copy-only source-owner handoff as a local proposal.
+The [public workshop profile](docs/knowledge-health/quickstart.md) uses the existing Knowledge host to retain ordinary drafts and one copy-only source-owner handoff as a local proposal.

package/SECURITY.md

@@ -90,7 +90,7 @@ make a released tarball differ from the reviewed tag.
 
 The package is alpha. Only the latest tagged release receives fixes; there
 are no backports to earlier tags. Published contracts carry a separate and
-stronger promise — `docs/contract-stability.md` and `docs/continuity.md`
+stronger promise — `docs/reference/contract-stability.md` and `docs/reference/continuity.md`
 record it — and that promise is not weakened by a security fix.
 
 ## Received advisories

package/TRADEMARKS.md

@@ -69,7 +69,7 @@ The sanctioned phrasing for a compatibility claim is:
     implements atelier contracts v1
 
 Conformance is public and offline: anyone can run the published validators in
-this package and reach the same answer (see `docs/attestation.md`). No
+this package and reach the same answer (see `docs/reference/attestation.md`). No
 permission is needed to make a truthful compatibility claim in this form, and
 no attestation can substitute for it.
 
@@ -77,7 +77,7 @@ no attestation can substitute for it.
 
 The phrases "MNSTRY certified" and "MNSTRY admitted" (and equivalents) are
 reserved to holders of a signed MNSTRY attestation that verifies per the
-procedure in `docs/attestation.md`. Self-issued or unsigned attestations
+procedure in `docs/reference/attestation.md`. Self-issued or unsigned attestations
 confer no such claim: an attestation with `"signature": null` is
 non-authoritative by definition, and a signature is only meaningful under a
 key the relying party recognizes as MNSTRY's.