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

package/src/cli/run.mjs

@@ -14,6 +14,8 @@ export const commandMap = new Map([
   ['export:dry-run', ['src/validate-atelier-export-dry-run.mjs']],
   ['dry-run', ['src/validate-atelier-export-dry-run.mjs']],
   ['graph', ['src/commands/graph.mjs']],
+  ['knowledge', ['src/commands/knowledge.mjs']],
+  ['enroll', ['src/commands/enroll.mjs']],
   ['project', ['src/commands/project.mjs']],
   ['build', ['src/commands/project.mjs']],
   ['dev', ['src/commands/server.mjs']],
@@ -61,7 +63,15 @@ export const commandMap = new Map([
   ['sync', ['src/commands/sync.mjs']],
   ['review', ['src/commands/review.mjs']],
   ['coauthor', ['src/commands/coauthor.mjs']],
+  ['architecture', ['src/commands/architecture.mjs']],
+  ['trackable', ['src/commands/trackable.mjs']],
+  ['practice', ['src/commands/practice.mjs']],
   ['skills', ['src/commands/skills.mjs']],
+  ['capability', ['src/commands/capability.mjs']],
+  ['inquiry', ['src/commands/inquiry.mjs']],
+  ['harness', ['src/commands/harness.mjs']],
+  ['learn', ['src/commands/learn.mjs']],
+  ['ingest', ['src/commands/ingest.mjs']],
   ['obsidian', ['src/commands/obsidian.mjs']],
 ])
 
@@ -105,6 +115,10 @@ Core commands:
   adopt                           Add Atelier to an existing repo/workspace.
   setup --yes                     Repair ignored local machine state.
   graph [--check]                 Build or check the knowledge graph.
+  knowledge check|context|evaluate Check an ontology plan and select bounded evidence.
+  knowledge dashboard|session     Inspect guided work and retain private drafts.
+  knowledge semantic OPERATION    Record a host-run semantic extraction for review.
+  enroll documents                Write private sidecars for documents missing one.
   project [--check]               Build or check the workspace projection.
   build [--check]                 Build or check a realm portal.
   dev                             Run the local Atelier sidecar.
@@ -143,7 +157,15 @@ Core commands:
   review run|history|handoff       Evidence-bound local human review.
   review export|inspect|packs      Preview inspection bundles and pack lifecycle.
   coauthor start|read|event|recover Save and resume private authoring drafts.
+  architecture catalog|entry|resolve Inspect responsibility names and consumer bindings.
+  trackable preview|execute|view     Follow adopted definitions and occurrence evidence.
+  practice plan|apply|status|context Adopt scoped instruction guidance and inspect use.
   skills audit|observe|candidates|sync Audit and manage local skill projections.
+  capability seal|plan|apply|status Publish local capability bundles and govern adoption.
+  harness                         Govern knowledge and build workflows.
+  inquiry append|handoff|status|graph Run the local Discovery and Research Harness workflow.
+  learn capture|propose|decide|activate|withdraw Manage scoped lessons and their evidence.
+  ingest plan|run|status|query     Preserve selected sources and search bounded evidence.
   config check                    Validate project config.
   extension-pack validate         Validate declared extension packs.
   extension-pack list             List declared extension packs.
@@ -168,7 +190,22 @@ Machine-local repo paths belong in
 
 export function buildCommandHelpText(command, brand = DEFAULT_BRAND) {
   const c = brand.command
+  const serverHelp = (name) => `Usage: ${c} ${name} [--project ./atelier.project.json] [--port=PORT] [--review] [--knowledge]
+
+Serves the project's built projection on 127.0.0.1 in the foreground until stopped. It builds nothing: run ${c} graph, then ${c} build, with the same --project path first. The port is --port=PORT, else the PORT environment variable, else 8137; 0 picks a free port, and the address printed on start names it. --review also serves the local review workspace at /review (docs/local-review.md). --knowledge adds guided knowledge dashboards and private coauthoring at /knowledge (docs/knowledge-workspace.md).`
   const help = {
+    capability: `Usage: ${c} capability seal|verify|inventory|plan|apply|status|observe|candidates|recover|fleet|graph|profiles
+Run ${c} capability help for options. Releases stay local; adoption is per repository
+and requires an exact plan digest. Installed bytes, host loading and successful
+exercise are separate evidence. No model execution or tool permission grants.`,
+    ingest: `Usage: ${c} ingest plan|run|status|query
+
+Read one bounded UTF-8 JSON object {workspaceId,input} from stdin inside the intended Git workspace. Plans bind explicit sources, scope and budgets. Run performs bounded local text, CSV and JSON extraction. Query returns source-bound lexical evidence with partial coverage; it does not synthesize or accept claims. Private state stays in ignored .atelier-local/. See docs/ingestion.md.`,
+    learn: `Usage: ${c} learn capture|propose|decide|activate|withdraw|list|context|render|graph|export|plan
+
+Read a bounded JSON object from stdin in the intended Git workspace. Every request includes workspaceId. Writes include actor, requestId, expectedRevision and input. Context and render include query. Local actor identity is asserted, not authenticated. State stays in ignored .atelier-local/. Accepted content becomes context only after explicit activation for a named harness; no permission grant, file installation or sending occurs. See docs/learning.md.`,
+    dev: serverHelp('dev'),
+    server: serverHelp('server'),
     skills: `Usage: ${c} skills audit|observe|candidates|sync
 Audit bundled skills or --root DIR [--peer DIR].
 Sync previews by default; applying requires --apply --confirm PLAN_DIGEST.
@@ -176,12 +213,22 @@ Observations are local metadata, never automatic telemetry.`,
     coauthor: `Usage: ${c} coauthor start|read|event|recover
 
 Read one JSON request from stdin (maximum 1 MiB). Start takes {"config":{"id":"SESSION","fields":[{"id":"FIELD","source":{"ref":"packet.md","digest":"SHA256"}}]}}. Read/recover take {"sessionId":"SESSION"}. Event takes {"sessionId":"SESSION","event":{"id":"UNIQUE","expectedRevision":0,"type":"answer","text":"ANSWER"}}. Run from the intended Git workspace with ignored .atelier-local/. Saves are private drafts, never canonical source edits.`,
-    init: `Usage: ${c} init [--template private-domain|shared-project|sample-workspace|distribution|external-project] [--target DIR] [--actor ID]
+    knowledge: `Usage: ${c} knowledge check|context|evaluate|dashboard [--project FILE] [--plan FILE]
+       ${c} knowledge session start|read|event|recover|list [--project FILE] [--plan FILE]
+       ${c} knowledge semantic begin|status|reconcile|complete|proposals|contribution|relation|record|cascade|context|project
+
+Start with ${c} init --template knowledge-workspace --target DIR.
+check reports ontology-to-question coverage against the current canonical graph.
+context --question TEXT [--mode graph|lexical] [--max-bytes N] prints a bounded JSON packet of complete active Markdown sources.
+evaluate compares lexical and graph selection on the plan's pinned evidence cases; exit 1 means missing or stale expected evidence, missing relationships, or an expected abstention that retrieved or omitted matching evidence.
+The packet is local operator context, may contain private material, and grants no sharing or execution authority. Payload bytes are exact; token estimates are not measured usage. Session operations read JSON on stdin (except list); saved answers are private drafts.
+semantic reads one JSON object {workspaceId, run, request} on stdin (at most 256 KiB) in the intended Git workspace, the one ingest uses. Each operation accepts exactly its documented request fields: required fields non-null, every field of its declared kind; anything else refuses as SEMANTIC_OPERATION_INVALID before anything is written. Formats such as timestamps are the runner's to check. Atelier calls no model: the host supplies its raw output, candidates and usage (null when unknown), and every interpretation stays pending until receiver records accept it; those records are caller assertions, not authenticated identity. Failures print {ok:false, code, error}, with recorded or captured details for reopening when the runner attached them. See docs/knowledge-setup.md, docs/knowledge-workspace.md and docs/semantic-operation.md.`,
+    init: `Usage: ${c} init [--template private-domain|shared-project|sample-workspace|distribution|external-project|knowledge-workspace] [--target DIR] [--actor ID]
 
 Creates tracked starter files and an Atelier lockfile. It does not install hooks unless asked separately. An unrecognized --template exits 1 and writes nothing; omit --template for the blank scaffold.`,
-    adopt: `Usage: ${c} adopt [--profile single-repo|private-domain|shared-project|multi-repo|monorepo|control-workspace] [--target DIR] [--yes]
+    adopt: `Usage: ${c} adopt [--profile single-repo|private-domain|shared-project|multi-repo|monorepo|control-workspace] [--target DIR] [--include PATTERN] [--exclude PATTERN] [--enroll-documents [--audience private]] [--yes]
 
-Creates or checks a tracked atelier.project.json for an existing workspace and writes machine-local path bindings only to ignored local overlay files.`,
+Creates or checks a tracked atelier.project.json for an existing workspace and writes machine-local path bindings only to ignored local overlay files. --include and --exclude record setup.include and setup.exclude, path patterns relative to the project config that scope which files the knowledge graph reads. --enroll-documents then runs ${c} enroll documents.`,
     setup: `Usage: ${c} setup --yes [--project ./atelier.project.json]
 
 Ensures ignored local Atelier state exists, verifies ignore coverage, and records unambiguous local repo path bindings.`,
@@ -194,6 +241,9 @@ check --staged judges the staged diff. push-check reads pre-push ref updates on
     graph: `Usage: ${c} graph [--check] [--project ./atelier.project.json]
 
 Builds or checks the project knowledge graph from tracked sources plus ignored local path bindings.`,
+    enroll: `Usage: ${c} enroll documents [--audience private] [--dry-run] [--json] [--project ./atelier.project.json]
+
+Writes a minimal <file>.kg.json sidecar next to every .html, .pdf and .docx document the knowledge graph reads that has none, so ${c} graph can pass. Each sidecar classifies its document for --audience (default private), which the repository's boundary policy must allow, and keeps the domain, lifecycle and status the graph infers. An existing sidecar, even one Git ignores, is never changed, and sources are never changed. --dry-run lists what would be written.`,
     readiness: `Usage:
   ${c} readiness [--check] [--project ./atelier.project.json]
   ${c} readiness protocols [--json]
@@ -229,22 +279,28 @@ Assembles a local feedback report under ignored .atelier-local/feedback/ (mode 0
     announcements: `Usage: ${c} announcements list [--dir DIR] [--public-key FILE] | verify <file> [--public-key FILE] [--json] | show <file> [--public-key FILE]
 
 MNSTRY announcements are a pull-only channel: signed JSON documents under announcements/ in the repository. The trust anchor is always the committed MNSTRY key, or one you pass explicitly with --public-key; --dir changes only where documents are read from and never which key verifies them. Every run names the key and keyId it used. The kit never fetches anything — receiving announcements is the git pull you chose to run, and show refuses to print a body whose signature does not verify.`,
-    obsidian: `Usage: ${c} obsidian status|scope|audience|mode|policy|service|open|apply|conflicts|apply-policy|selection|proposals [--project atelier.project.json] [--data-root DIR] [--json]
+    obsidian: `Usage: ${c} obsidian status|settings|location|scope|view|audience|mode|policy|service|open|uninstall|plugin|apply|conflicts|apply-policy|selection|proposals [--project atelier.project.json] [--data-root DIR] [--json] [--no-input]
 
   ${c} obsidian status
+  ${c} obsidian settings
+  ${c} obsidian location show | set DIR [--allow-synced-location]
   ${c} obsidian scope list | scope show ID
-  ${c} obsidian audience show | set A,B | clear
+  ${c} obsidian view add ID (--all | --folder PATH [--folder PATH ...] [--repo R] | --tag T) [--expand DEPTH:MAX] [--default] [--allow-empty] [--yes]
+  ${c} obsidian audience show | set me|A,B | clear
   ${c} obsidian mode show | set manual|automatic
-  ${c} obsidian policy show | install FILE | revoke
-  ${c} obsidian service start [--consent-actor ID] --adapter=obsidian-cli | status | stop | unit --print --adapter=obsidian-cli
-  ${c} obsidian open [--scope ID] [--consent-actor ID] [--allow-stale] --adapter=obsidian-cli
+  ${c} obsidian policy show | install FILE | revoke | digest FILE
+  ${c} obsidian service start [--consent-actor ID] [--adapter=obsidian-cli] | status | stop | unit --print [--adapter=obsidian-cli]
+  ${c} obsidian service unit --install [--consent-actor ID] [--adapter=obsidian-cli] | unit --remove
+  ${c} obsidian open [--scope ID] [--consent-actor ID] [--allow-stale] [--restart-obsidian] [--wait-ms MS] [--adapter=obsidian-cli]
+  ${c} obsidian uninstall
+  ${c} obsidian plugin show [--scope ID] | on [--scope ID] [--adapter=obsidian-cli]
   ${c} obsidian apply list | show EDIT | run EDIT [--actor ID] | recover
   ${c} obsidian conflicts [ID]
   ${c} obsidian apply-policy create FILE | show | revoke
   ${c} obsidian selection resolve ID | persist ID [allow-empty] | show ID | list
   ${c} obsidian proposals list | show OPERATION
 
-Noninteractive. With --json exactly one JSON document is printed, for a refusal too. status, scope, audience show, mode show, policy show and service status are read-only. open reports current only when the owned maintenance service ticked after the request, the view's trusted generation is the prepared one and reads back byte for byte, and the installed Obsidian meets the minimum version and answers for that vault; every other outcome is typed and exits 3. Reaching the installed app is never a default: open, service start and service unit need --adapter=obsidian-cli. Audiences, mode and the apply policy are private machine settings, never project configuration and never a note. apply, conflicts, apply-policy, selection and proposals are contributed operations registered from modules shipped under src/runtime/obsidian/contributions/; the built-in names cannot be replaced. While no apply operation is registered every apply reports apply-unavailable. Exit codes: 0 done, 1 internal error, 2 refusal or usage, 3 ran and the answer is not success.`,
+Every input is an argument. view add changes the project configuration, which you commit: it shows the change and how many notes the view would show, and asks a person at a terminal first (--yes answers beforehand); anyone else's command is their consent, and nothing is ever committed. With --json exactly one JSON document is printed, for a refusal too. status, settings, location show, scope, audience show, mode show, policy show, policy digest, plugin show and service status are read-only. open reports current only when the owned maintenance service ticked after the request, the view's trusted generation is the prepared one and reads back byte for byte, and the installed Obsidian meets the minimum version and answers for that vault; every other outcome is typed and exits 3. Reaching the installed app is never a default: open, service start and service unit need --adapter=obsidian-cli once for a workspace, which remembers it (never used under the test runner). service unit --install installs a login item on macOS (a launchd agent) or Linux (a systemd user unit) so maintenance starts when you log in, under a consent that covers startup; it runs the package installed in the project and is refused from a package runner's cache. Once installed, the service is started through it, and service start replaces a service of an earlier release. service unit --remove removes it and starts the service for this session only. uninstall removes the login item and stops the service, and keeps vaults, private state, the project file and Obsidian's vault list. Obsidian's own settings file is written only while no Obsidian runs, and every write is shown in open's answer: the view's vault is added to its list with a backup of the file as it was, its command line is turned on (cli: true), and for an Obsidian that never started the file is created. A running Obsidian that open cannot reach (its command line turned off, or no vault open) is quit and started again only with --restart-obsidian, which no other flag implies; otherwise open names that flag. --wait-ms bounds open's wait for maintenance's tick. The first start of the maintenance service records who allowed it: --consent-actor ID, or for a person at a terminal the account's name; --json, --no-input, CI or ATELIER_NONINTERACTIVE=1 mean nobody is at a terminal. Audiences (audience set me: only you, with the notes that carry no classification, which no other list shows), mode, the apply policy and what was decided are private machine settings, never project configuration and never a note. apply, conflicts, apply-policy, selection and proposals are contributed operations registered from modules shipped under src/runtime/obsidian/contributions/; the built-in names cannot be replaced. While no apply operation is registered every apply reports apply-unavailable. Exit codes: 0 done, 1 internal error, 2 refusal or usage, 3 ran and the answer is not success.`,
     sync: `Usage:
   ${c} sync enroll --repo DIR [--project atelier.project.json] [--git ABSOLUTE_PATH]
   ${c} sync status --repo DIR

package/src/coauthor/store.mjs

@@ -57,8 +57,7 @@ export function createCoauthorStore({ workspaceRoot = process.cwd() } = {}) {
     const lockPath = path.join(directory(), 'operation.lock');
     return withPrivateLock(lockPath, operation);
   }
-  function load(id) {
-    const result = ledger().eventsFor(aggregate(id));
+  function load(id, result = ledger().eventsFor(aggregate(id))) {
     if (!result.ok) throw new Error(result.error);
     if (!result.events.length) throw new Error('coauthor session not found');
     let state;
@@ -151,6 +150,48 @@ export function createCoauthorStore({ workspaceRoot = process.cwd() } = {}) {
       });
     },
     read(id) { return load(id).state; },
+    // Owning readback of the existing immutable values and verified event chain.
+    // Read only: missing values are unknown/unavailable, never repaired here.
+    readSavedFields(id) {
+      return locked(() => {
+        const state = load(id).state;
+        const values = state.saved.map(saved => {
+          const parents = ['.atelier-local', 'coauthor', 'values', contentDigest(id)];
+          let dir = root;
+          for (const part of parents) {
+            dir = path.join(dir, part);
+            const info = fs.lstatSync(dir);
+            if (!info.isDirectory() || info.isSymbolicLink()) throw new Error('redirected saved-value directory refused');
+          }
+          const raw = readText(path.join(dir, `${contentDigest(saved.receipt.requestId)}.json`));
+          const value = JSON.parse(raw);
+          validate(value, 'draft');
+          const expected = { schema: 'atelier-coauthor-draft@v1', status: 'draft', text: saved.text, receipt: saved.receipt };
+          if (raw !== canonicalize(expected) || canonicalize(value) !== canonicalize(expected)) throw new Error('saved value differs from owning event receipt');
+          return value;
+        });
+        return { state, values };
+      });
+    },
+    // One verified ledger snapshot for a bounded history listing. Keep failures
+    // per aggregate, and do not cache across calls or trust a caller's events.
+    readMany(ids) {
+      if (!Array.isArray(ids) || ids.length > 200 || ids.some(id => typeof id !== 'string' || !id))
+        throw new Error('session ids required and bounded');
+      if (!ids.length) return new Map();
+      const all = ledger().readAll();
+      const groups = new Map();
+      if (all.ok) for (const record of all.events) {
+        if (!groups.has(record.aggregateId)) groups.set(record.aggregateId, []);
+        groups.get(record.aggregateId).push(record);
+      }
+      return new Map(ids.map(id => {
+        try {
+          const state = load(id, all.ok ? { ok: true, events: groups.get(aggregate(id)) || [] } : all).state;
+          return [id, { ok: true, state }];
+        } catch (error) { return [id, { ok: false, error: error.message }]; }
+      }));
+    },
     dispatch(id, event) {
       return locked(() => {
         if (['receipt', 'failed'].includes(event?.type)) throw new Error('receipt and failure events are store-owned');

package/src/collaboration/proposals.mjs

@@ -1,6 +1,7 @@
 import crypto from 'node:crypto'
 import fs from 'node:fs'
 import path from 'node:path'
+import { canonicalize } from '../attestation/jcs.mjs'
 import { createCollaborationEventLedger } from './event-ledger.mjs'
 import {
   atomicReplacePrivateText,
@@ -12,6 +13,7 @@ export const ATELIER_PROPOSAL_SCHEMA = 'atelier-proposal@v1'
 export const ATELIER_PROPOSALS_SCHEMA = 'atelier-proposals@v1'
 export const PROPOSAL_REVIEW_STATUSES = new Set(['reviewed', 'accepted', 'rejected', 'superseded'])
 export const COPY_ONLY_PROPOSAL_CAPABILITY = 'proposal.copy-only'
+export const WORKSHOP_HANDOFF_RETENTION_KIND = 'workshop-handoff'
 const PROPOSAL_ID_PATTERN = /^proposal-[a-z0-9]+(?:-[a-z0-9]+)*$/
 
 function nowIso() {
@@ -383,6 +385,190 @@ export function createProposalStore({
     return { ok: true, status: 200, record, diagnostics }
   }
 
+  const RETAINED_FIELD_LIMITS = { sessionId: 120, viewId: 120, path: 500, action: 120, intent: 500, actor: 160 }
+  const sha256Hex = (text) => crypto.createHash('sha256').update(text, 'utf8').digest('hex')
+
+  // The original saved receipt that names one retained handoff. Nothing is
+  // trimmed: a value that is not already usable is not an identity.
+  function retentionIdentity(receipt) {
+    if (!isRecord(receipt)) return null
+    const { sessionId, requestId, valueDigest } = receipt
+    if (typeof sessionId !== 'string' || !sessionId || sessionId.length > 120) return null
+    if (typeof requestId !== 'string' || !requestId || requestId.length > 200) return null
+    if (typeof valueDigest !== 'string' || !/^[a-f0-9]{64}$/.test(valueDigest)) return null
+    return { kind: WORKSHOP_HANDOFF_RETENTION_KIND, sessionId, requestId, valueDigest }
+  }
+
+  // The value digest is not part of the id, so another value saved under the
+  // same original request meets the first record and is refused.
+  function retainedProposalId(identity) {
+    return proposalId(canonicalize({ kind: identity.kind, sessionId: identity.sessionId, requestId: identity.requestId }))
+  }
+
+  // The digest covers exactly what the record holds, so a lookup recomputes it.
+  function retainedDigest(record) {
+    const proposal = record.proposal
+    return sha256Hex(canonicalize({
+      sessionId: proposal.sessionId,
+      viewId: proposal.viewId,
+      path: proposal.path,
+      action: proposal.action,
+      intent: proposal.intent,
+      actor: record.retention.actor,
+      diff: record.diff,
+      payload: record.payload,
+    }))
+  }
+
+  // Lookup by the original saved receipt. Only the ledger answers: a
+  // compatibility snapshot is never a retained outcome, and a ledger that
+  // cannot be read is unknown, not absent.
+  function lookupRetainedProposal(receipt) {
+    const identity = retentionIdentity(receipt)
+    if (!identity) {
+      return { ok: false, status: 422, outcome: 'refused', error: 'selected draft receipt is not usable as a retention identity' }
+    }
+    const id = retainedProposalId(identity)
+    const found = materializedProposal(id)
+    if (!found.ok && found.status === 404) {
+      return fs.existsSync(proposalPath(id))
+        ? { ok: false, status: 409, outcome: 'unknown', id, error: 'a snapshot exists for this receipt without a ledger record; inspect it before retrying' }
+        : { ok: true, status: 200, outcome: 'not-found', id, record: null }
+    }
+    if (!found.ok) return { ok: false, status: found.status, outcome: 'unknown', id, error: found.error }
+    const kept = found.record?.retention
+    let digest = null
+    try {
+      digest = isRecord(kept) ? retainedDigest(found.record) : null
+    } catch {
+      digest = null
+    }
+    if (
+      !isRecord(kept) || kept.kind !== identity.kind || kept.sessionId !== identity.sessionId ||
+      kept.requestId !== identity.requestId || digest === null || digest !== kept.payloadDigest
+    ) {
+      return { ok: false, status: 422, outcome: 'unknown', id, error: 'the retained proposal does not match its own receipt identity or digest' }
+    }
+    if (kept.valueDigest !== identity.valueDigest) {
+      return { ok: false, status: 409, outcome: 'conflict', id, error: 'a different value is already retained for this original receipt' }
+    }
+    return { ok: true, status: 200, outcome: 'retained', id, record: found.record }
+  }
+
+  // The handoff as it was retained, for readback after a lost reply or a
+  // source change.
+  function retainedHandoff(record) {
+    const proposal = record.proposal
+    return {
+      sessionId: proposal.sessionId,
+      viewId: proposal.viewId,
+      path: proposal.path,
+      action: proposal.action,
+      actor: record.retention.actor,
+      intent: proposal.intent,
+      directWrite: false,
+      applyEndpoint: null,
+      diff: JSON.parse(record.diff),
+      proposal: record.payload,
+    }
+  }
+
+  // Retain one server-derived handoff once, keyed by its original saved
+  // receipt. The caller derives the handoff; this store never trims or cuts
+  // it. A field that would not fit is refused, and the ledger's own line
+  // ceiling refuses the rest. A retained record is `proposed`: it is neither a
+  // review decision nor a source change.
+  function retainProposal(handoff = {}) {
+    if (!isRecord(handoff) || !isRecord(handoff.proposal) || !isRecord(handoff.diff)) {
+      return { ok: false, status: 422, outcome: 'refused', error: 'handoff shape is not supported' }
+    }
+    const authority = validateCopyOnlyProposalAuthority({ ...handoff.proposal, ...handoff })
+    if (!authority.ok || handoff.directWrite !== false || handoff.applyEndpoint !== null) {
+      return { ok: false, status: 409, outcome: 'refused', error: 'proposal authority refused: a retained handoff is copy-only' }
+    }
+    for (const [field, max] of Object.entries(RETAINED_FIELD_LIMITS)) {
+      const value = handoff[field]
+      if (typeof value !== 'string' || !value || value !== value.trim() || value.length > max) {
+        return { ok: false, status: 413, outcome: 'refused', error: `handoff ${field} cannot be retained without changing it` }
+      }
+    }
+    const identity = retentionIdentity(handoff.proposal.selectedDraftReceipt)
+    if (!identity || identity.sessionId !== handoff.sessionId) {
+      return { ok: false, status: 422, outcome: 'refused', error: 'selected draft receipt is not usable as a retention identity' }
+    }
+    let record
+    try {
+      const diffText = JSON.stringify(handoff.diff, null, 2)
+      if (diffText.length > 50000) {
+        return { ok: false, status: 413, outcome: 'refused', error: 'handoff diff cannot be retained without truncation' }
+      }
+      const createdAt = nowIso()
+      record = {
+        schema: ATELIER_PROPOSAL_SCHEMA,
+        workspaceId,
+        proposal: {
+          id: retainedProposalId(identity),
+          status: 'proposed',
+          createdAt,
+          updatedAt: createdAt,
+          sessionId: handoff.sessionId,
+          viewId: handoff.viewId,
+          path: handoff.path,
+          action: handoff.action,
+          intent: handoff.intent,
+          reason: '',
+          storage: {
+            kind: 'local',
+            ignored: true,
+          },
+          authority: copyOnlyActionSummary(handoff.action),
+          eventVersion: 1,
+        },
+        diff: diffText,
+        payload: handoff.proposal,
+        retention: { ...identity, actor: handoff.actor, receipt: handoff.proposal.selectedDraftReceipt },
+      }
+      record.retention.payloadDigest = retainedDigest(record)
+    } catch {
+      return { ok: false, status: 422, outcome: 'refused', error: 'handoff cannot be canonicalized' }
+    }
+    const unknown = (error) => ({ ok: false, status: 409, outcome: 'unknown', error })
+    const settle = (known) => {
+      if (known.outcome !== 'retained') return known
+      return known.record.retention.payloadDigest === record.retention.payloadDigest
+        ? { ok: true, status: 200, outcome: 'existing', record: known.record, diagnostics: [] }
+        : { ok: false, status: 409, outcome: 'conflict', error: 'a different handoff is already retained for this original receipt' }
+    }
+    const known = lookupRetainedProposal(identity)
+    if (known.outcome !== 'not-found') return settle(known)
+    const appended = eventLedger.append({
+      aggregateId: record.proposal.id,
+      expectedVersion: 0,
+      type: 'proposal-created',
+      actor: handoff.actor,
+      at: record.proposal.createdAt,
+      payload: { record },
+    })
+    if (!appended.ok) {
+      // A version conflict means another writer appended first. Read back the
+      // original identity; never append again.
+      if (appended.status === 409) {
+        const again = lookupRetainedProposal(identity)
+        return again.outcome === 'retained'
+          ? settle(again)
+          : unknown('the append conflicted and the original receipt could not be read back; repeat the same request')
+      }
+      return { ok: false, status: appended.status, outcome: appended.status === 413 ? 'refused' : 'unknown', error: appended.error }
+    }
+    // Retention is acknowledged only from the ledger's own readback.
+    const back = lookupRetainedProposal(identity)
+    if (back.outcome !== 'retained' || back.record.retention.payloadDigest !== record.retention.payloadDigest) {
+      return unknown('the retained proposal could not be read back after its append; repeat the same request')
+    }
+    const diagnostics = writeSnapshotProjectionWith(snapshotWriter, proposalPath(record.proposal.id), back.record)
+    return { ok: true, status: 200, outcome: 'created', record: back.record, diagnostics }
+  }
+
   function reviewProposal(id, body = {}) {
     const read = readProposal(id)
     if (!read.ok) return read
@@ -457,6 +643,9 @@ export function createProposalStore({
     readProposal,
     listProposals,
     createProposal,
+    lookupRetainedProposal,
+    retainedHandoff,
+    retainProposal,
     reviewProposal,
   }
 }

package/src/commands/architecture.mjs

@@ -0,0 +1,27 @@
+import { architectureEntry, responsibilityCatalog, resolveBehaviorBinding } from '../architecture/index.mjs'
+import { reportCommandFailure, parseJsonRequest } from '../cli/command-failure.mjs'
+
+try {
+  const [command, name, ...rest] = process.argv.slice(2)
+  if (rest.length) throw new Error('unexpected architecture arguments')
+  let result
+  if (command === 'catalog' && name === undefined) result = responsibilityCatalog()
+  else if (command === 'entry' && name !== undefined) {
+    result = architectureEntry(name)
+    if (!result) throw new Error('unknown architecture name')
+  } else if (command === 'resolve' && name === undefined) {
+    const chunks = []; let bytes = 0
+    for await (const chunk of process.stdin) {
+      bytes += chunk.length
+      if (bytes > 256 * 1024) throw new Error('architecture request exceeds limit')
+      chunks.push(chunk)
+    }
+    const value = parseJsonRequest(Buffer.concat(chunks), 'architecture request')
+    if (!value || Object.keys(value).sort().join(',') !== 'binding,consumers') throw new Error('binding and consumers required')
+    result = resolveBehaviorBinding(value)
+    if (!result.resolved) process.exitCode = 1
+  } else throw new Error('Usage: atelier architecture catalog|entry NAME|resolve (JSON stdin)')
+  console.log(JSON.stringify(result, null, 2))
+} catch (error) {
+  reportCommandFailure(error)
+}

package/src/commands/boundary.mjs

@@ -6,6 +6,7 @@ import {
   runBoundaryInstallHooksCommand,
   runBoundaryPushCheckCommand,
 } from '../boundary/policy.mjs'
+import { runBoundaryDelegationCommand } from '../boundary/delegation-command.mjs'
 
 const args = parseArgs(process.argv.slice(2))
 const subcommand = args._[0] || 'check'
@@ -19,6 +20,8 @@ if (subcommand === 'check' || subcommand === 'doctor') {
   runBoundaryAuditCommand(rest('audit'))
 } else if (subcommand === 'install-hooks') {
   runBoundaryInstallHooksCommand(rest('install-hooks'))
+} else if (subcommand === 'delegation') {
+  runBoundaryDelegationCommand(rest('delegation'))
 } else {
   console.error(`Unknown boundary command: ${subcommand}`)
   process.exit(1)

package/src/commands/capability.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import fs from 'node:fs'
+import path from 'node:path'
+import * as capability from '../capabilities/index.mjs'
+import { jsonAt } from '../capabilities/files.mjs'
+import { reportCommandFailure } from '../cli/command-failure.mjs'
+
+const USAGE = `Usage: atelier capability <command> [options]
+
+seal --package DIR                     Seal a local package, without overwriting a release.
+verify --package DIR [--digest SHA]     Verify all payload bytes; no publisher authentication.
+inventory --surfaces FILE              Read only the explicitly listed skill surfaces.
+plan --adoption FILE [--source DIR ...] [--tool ID ...] [--notices FILE]
+apply --adoption FILE [--source DIR ...] [--tool ID ...] [--notices FILE] --confirm PLAN_DIGEST
+status [--session ID]                  Separate installation and caller-reported host evidence.
+observe --event FILE                   Record a content-free, version-bound evidence reference.
+candidates                            Propose cause-specific review from repeated evidence.
+recover [--confirm PLAN_DIGEST]        Preview recovery; exact confirmation restores prior state.
+fleet --repo DIR [--repo DIR ...]       Inspect explicitly selected repositories independently.
+graph --namespace ID [--audience private|team|public]
+                                      Emit draft graph source documents as JSON for review.
+profiles                              Show repository host projection profiles and their limits.
+
+All output is JSON. --workspace DIR defaults to the current repository.
+No command downloads packages, executes their scripts, probes a host, or grants tool authority.
+The --tool values are caller observations of available tools, not permission grants.
+Exit codes: 0 success, 1 refusal or blocked plan, 2 usage error.`
+
+const COMMANDS = {
+  seal: ['package'], verify: ['package', 'digest'], inventory: ['surfaces'],
+  plan: ['adoption', 'source', 'tool', 'notices'], apply: ['adoption', 'source', 'tool', 'notices', 'confirm'],
+  status: ['session'], observe: ['event'], candidates: [], recover: ['confirm'],
+  fleet: ['repo'], graph: ['namespace', 'audience'], profiles: [],
+}
+const argv = process.argv.slice(2), command = argv.shift()
+if (['--help', '-h', 'help'].includes(command) || argv.includes('--help')) { console.log(USAGE); process.exit(0) }
+function usage(message) { console.error(`${message}\n\n${USAGE}`); process.exit(2) }
+if (!Object.hasOwn(COMMANDS, command ?? '')) usage('unknown capability command')
+const options = {}, repeated = new Set(['source', 'tool', 'repo'])
+for (let index = 0; index < argv.length; index += 1) {
+  const match = /^--([a-z-]+)(?:=(.*))?$/.exec(argv[index])
+  if (!match || ![...COMMANDS[command], 'workspace', 'json'].includes(match[1])) usage('unknown capability option')
+  const key = match[1]
+  if (key === 'json') { if (match[2] !== undefined) usage('--json does not take a value'); continue }
+  const value = match[2] ?? argv[++index]
+  if (!value || value.startsWith('--')) usage('option requires a value')
+  if (repeated.has(key)) (options[key] ??= []).push(value)
+  else { if (options[key] !== undefined) usage('duplicate option'); options[key] = value }
+}
+function required(name) { if (!options[name]) usage(`--${name} is required`); return options[name] }
+function read(file) { const absolute = path.resolve(file); return jsonAt(fs.realpathSync(path.dirname(absolute)), path.basename(absolute)) }
+const common = { workspaceRoot: options.workspace ?? process.cwd() }
+try {
+  let result
+  if (command === 'seal') result = capability.sealCapabilityRelease({ packageRoot: required('package') })
+  if (command === 'verify') result = capability.verifyCapabilityRelease({ packageRoot: required('package'), expectedDigest: options.digest })
+  if (command === 'inventory') result = capability.inventorySkillSurfaces({ surfaces: read(required('surfaces')) })
+  if (['plan', 'apply'].includes(command)) {
+    const settings = { ...common, adoption: read(required('adoption')), sources: options.source ?? [], availableTools: options.tool ?? [], notices: options.notices ? read(options.notices) : [] }
+    result = command === 'plan' ? capability.planCapabilityAdoption(settings) : capability.applyCapabilityAdoption({ ...settings, confirm: required('confirm') })
+    if (result.applyAllowed === false) process.exitCode = 1
+  }
+  if (command === 'status') result = capability.capabilityEvidenceStatus({ ...common, session: options.session ?? null })
+  if (command === 'observe') result = capability.recordCapabilityEvent({ ...common, event: read(required('event')) })
+  if (command === 'candidates') result = capability.capabilityImprovementCandidates(common)
+  if (command === 'recover') result = options.confirm ? capability.recoverCapabilityAdoption({ ...common, confirm: options.confirm }) : capability.inspectCapabilityRecovery(common)
+  if (command === 'fleet') result = capability.inspectCapabilityFleet({ workspaces: required('repo') })
+  if (command === 'graph') result = capability.capabilityGraphSources({ ...common, namespace: required('namespace'), audience: options.audience ?? 'private' })
+  if (command === 'profiles') result = capability.HOST_PROFILES
+  console.log(JSON.stringify(result, null, 2))
+} catch (error) {
+  reportCommandFailure(error, 'stdout')
+}

package/src/commands/enroll.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runEnrollCommand } from '../graph/enroll.mjs'
+runEnrollCommand()

package/src/commands/harness.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+import fs from 'node:fs'
+import path from 'node:path'
+import * as harness from '../harnesses/index.mjs'
+import { knowledgeGraphProposal, prepareIntakeContribution, prepareKnowledgeImport } from '../knowledge/index.mjs'
+import { prepareGitCandidate } from '../build/git.mjs'
+import { jsonAt } from '../capabilities/files.mjs'
+import { reportCommandFailure } from '../cli/command-failure.mjs'
+const HELP = `Usage: atelier harness <command> [options]
+knowledge|build append --record FILE --confirm DIGEST [--workspace DIR]
+knowledge|build status|export --run ID [--workspace DIR]
+knowledge graph --run ID --activation ID --namespace ID [--dependencies FILE] [--workspace DIR]
+knowledge reconcile --run ID [--dependencies FILE] [--workspace DIR]
+knowledge intake --run ID --attempt ID --title TEXT --term ID [--workspace DIR]
+knowledge import --run ID --handoff FILE --history FILE --title TEXT --term ID [--dependencies FILE] [--workspace DIR]
+build readiness|coordination --run ID [--dependencies FILE] [--workspace DIR]
+build candidate --run ID --artifact FILE --writer FILE [--workspace DIR]
+inspect --profile knowledge|build|inquiry --history FILE
+validate --profile knowledge|build --record FILE
+handoff --profile PROFILE --history FILE --repository ID --subject ID --target-repository ID --target-profile PROFILE --purpose TEXT [--dependencies FILE]
+verify --handoff FILE --history FILE [--dependencies FILE]
+feedback --profile knowledge|build --history FILE --event FILE
+example
+
+History files are complete ledgers; dependencies are explicit repository/profile/records snapshots.
+The initial history digest is ${harness.EMPTY_HARNESS_HEAD}.
+All output is JSON. Proposals and reported acceptance never authorize execution.
+The existing atelier build command remains the workspace projection command.`
+const args = process.argv.slice(2), first = args.shift(), profile = ['knowledge', 'build'].includes(first) ? first : null
+const command = profile ? args.shift() : first, options = {}
+if (['help', '--help', '-h'].includes(first) || args.includes('--help')) { console.log(HELP); process.exit(0) }
+const common = { inspect: ['profile', 'history'], validate: ['profile', 'record'], handoff: ['profile', 'history', 'repository', 'subject', 'target-repository', 'target-profile', 'purpose', 'dependencies'], verify: ['handoff', 'history', 'dependencies'], feedback: ['profile', 'history', 'event'], example: [] }
+const domain = { append: ['record', 'confirm'], status: ['run'], export: ['run'], graph: ['run', 'activation', 'namespace', 'dependencies'], reconcile: ['run', 'dependencies'], intake: ['run', 'attempt', 'title', 'term'], import: ['run', 'handoff', 'history', 'title', 'term', 'dependencies'], readiness: ['run', 'dependencies'], coordination: ['run', 'dependencies'], candidate: ['run', 'artifact', 'writer'] }
+const allowed = profile ? domain[command] : common[command]
+const usage = message => { console.error(`${message}\n${HELP}`); process.exit(2) }
+if (!allowed || (profile === 'knowledge' && ['readiness', 'coordination', 'candidate'].includes(command)) || (profile === 'build' && ['graph', 'intake', 'import', 'reconcile'].includes(command))) usage('unknown harness command')
+for (let i = 0; i < args.length; i++) {
+  const key = args[i].startsWith('--') ? args[i].slice(2) : ''
+  if (![...allowed, ...(profile ? ['workspace'] : [])].includes(key) || Object.hasOwn(options, key)) usage('unknown or duplicate option')
+  const value = args[++i]; if (!value || value.startsWith('--')) usage('option requires a value'); options[key] = value
+}
+const need = key => { if (!options[key]) usage(`--${key} required`); return options[key] }
+const read = file => { const p = path.resolve(file); return jsonAt(fs.realpathSync(path.dirname(p)), path.basename(p)) }
+function history(file, selected) {
+  const ledger = read(file), p = selected ?? ledger.profile ?? (ledger.schema === 'atelier-inquiry-ledger@v1' ? 'inquiry' : null)
+  if (p === 'inquiry') {
+    if (ledger.schema !== 'atelier-inquiry-ledger@v1') throw new Error('invalid inquiry ledger')
+  } else if (harness.validateHarnessDocument(ledger, p, 'ledger').length) throw new Error('invalid harness ledger')
+  const state = harness.inspectHarness(p, ledger.records)
+  if (state.head !== ledger.head) throw new Error('history digest mismatch')
+  return state.records
+}
+try {
+  let result
+  const dependencySnapshots = options.dependencies ? read(options.dependencies) : []
+  const workspaceRoot = options.workspace ?? process.cwd()
+  if (profile) {
+    if (command === 'append') result = harness.appendHarness({ workspaceRoot, profile, record: read(need('record')), confirm: need('confirm') })
+    else {
+      const state = harness.readHarness({ workspaceRoot, profile, run: need('run') })
+      if (command !== 'status' && !state.establishment) throw new Error('harness run missing')
+      if (command === 'status') result = state
+      if (command === 'export') result = { schema: 'atelier-harness-ledger@v1', profile, records: state.records, head: state.head }
+      if (command === 'graph') result = knowledgeGraphProposal(state.records, { namespace: need('namespace'), activationId: need('activation'), dependencySnapshots })
+      if (command === 'reconcile') result = harness.reconcileKnowledge(state.records, { dependencySnapshots })
+      if (command === 'intake') result = prepareIntakeContribution({ workspaceRoot, records: state.records, attemptId: need('attempt'), title: need('title'), term: need('term') })
+      if (command === 'import') result = prepareKnowledgeImport({ records: state.records, handoff: read(need('handoff')), sourceRecords: history(need('history')), title: need('title'), term: need('term'), dependencySnapshots })
+      if (command === 'readiness') result = harness.buildReadiness(state.records, { dependencySnapshots })
+      if (command === 'coordination') result = harness.buildCoordinationProposal(state.records, { dependencySnapshots })
+      if (command === 'candidate') result = prepareGitCandidate({ workspaceRoot, records: state.records, artifact: need('artifact'), writer: read(need('writer')) })
+    }
+  } else if (command === 'example') result = JSON.parse(fs.readFileSync(new URL('../../fixtures/harnesses/learning-cycle.json', import.meta.url), 'utf8'))
+  else if (command === 'validate') { const errors = harness.validateHarnessDocument(read(need('record')), need('profile')); result = { valid: !errors.length, errors, assurance: 'shape-only' }; if (errors.length) process.exitCode = 1 }
+  else if (command === 'inspect') result = harness.inspectHarness(need('profile'), history(need('history'), options.profile))
+  else if (command === 'handoff') result = harness.createHarnessHandoff({ profile: need('profile'), repository: need('repository'), records: history(need('history'), options.profile), subjectId: need('subject'), target: { repository: need('target-repository'), profile: need('target-profile'), purpose: need('purpose') }, dependencySnapshots })
+  else if (command === 'verify') { const handoff = read(need('handoff')); result = harness.verifyHarnessHandoff({ handoff, records: history(need('history'), handoff.source.profile), dependencySnapshots }) }
+  else if (command === 'feedback') result = harness.prepareHarnessFeedback({ ...read(need('event')), profile: need('profile'), records: history(need('history'), options.profile) })
+  console.log(JSON.stringify(result, null, 2))
+} catch (error) { reportCommandFailure(error, 'stdout') }