@mnstry/atelier 0.2.0-alpha.6 → 0.2.0-alpha.8

package/skills/codex/atelier-guided-coauthor/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: atelier-guided-coauthor
+description: Guide an author through a selected packet in Codex, retaining private source-bound draft answers and resuming through the local Atelier coauthor CLI.
+---
+
+# Guided coauthor
+
+Use the installed `atelier coauthor` command, not a browser conversation service.
+The author chooses the packet and may read it normally without this workflow.
+
+Check the repository's instructions and local package first. Run
+`./node_modules/.bin/atelier coauthor --help` from the intended repository.
+Do not download another package if the command is unavailable. Explain that the
+installed version needs the coauthor capability and preserve ordinary packet review.
+
+## Start or resume
+
+- Require an existing Git workspace with ignored, untracked `.atelier-local/`.
+  Do not change global skills, sibling repositories, credentials or remote access.
+- Read the selected packet. Use consumer-owned field ids and workspace-relative
+  source references. Compute SHA-256 over each source file's exact UTF-8 bytes.
+  Send a `start` request containing `config: {id, fields}`; each field has
+  `id` and `source: {ref, digest}`. Packet structure stays in the consumer.
+- Requests are JSON on stdin; responses are JSON. Use an ignored request file
+  when needed, not shell interpolation of the author's text. Read the returned
+  state and revision. `read` takes `sessionId` and resumes retained history.
+- Ask one useful question at a time. Record the author's exact answer with an
+  `answer` event; events carry a unique `id`, `expectedRevision` and `type`.
+  Do not infer an answer or approval from silence.
+- If proposing edited wording, use `propose` and show the change. Wait for the
+  author's explicit confirmation before `confirm`. `reject` restores the
+  original. Even apparently stylistic rewrites need confirmation.
+- Send `save` only for the agreed draft. Say “saved as a private draft” only
+  after the command returns a saved receipt. The source packet is never edited.
+  `continueAfterSave: true` on an answer retains the author's advance intent;
+  otherwise `advance` is explicit.
+- `pause` and `resume` preserve the current phase. On restart, a `saving`
+  state may use `recover` to reconcile the pending private write. A
+  `recovery` state requires explicit `retry`, with one retry available.
+  Stop retrying when exhausted and retain all artifacts for inspection.
+
+## Boundaries
+
+Never submit store-owned receipt/failure events or fabricate persistence evidence.
+A stale source or revision is a visible conflict, not permission to overwrite it.
+Keep the old history and obtain a newly bound session for revised sources.
+Saved answers are proposals for later owner review, not publication, canonical
+acceptance, guide access, or a completed packet. No saved-answer undo is provided;
+do not erase history to simulate it. Summarize unresolved questions for the meeting.

package/skills/codex/atelier-guided-upgrade/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: atelier-guided-upgrade
+description: Prepare and explain an Atelier package upgrade in an isolated candidate, retain the owner decision, and apply only the approved effects. Use for owners asking to update an existing Atelier.
+---
+
+# Guided Atelier upgrade
+
+The default outcome is a reviewable candidate and an owner decision. Preserve the
+owner's actual request and existing scoped authority; no per-command approval
+loop is needed for actions already authorized. Preparation alone never authorizes
+changing the working installation, merging, publishing or restarting a service.
+
+## Establish the source and workspace
+
+Read the selected repository's instructions and upgrade procedure. Identify its
+actual installed scoped package, package-manager lock, Atelier lock, Git state,
+project roots, packs, overlays and running-service ownership. Resolve the package
+from that workspace (including a parent install); never use global Atelier,
+unscoped registry fallback or the first sibling checkout found on disk.
+Read `docs/guided-upgrades.md` and `docs/exact-upgrades.md` from the selected
+installed package when present. If an old install lacks this skill or commands,
+use the owner-selected new package's documentation only after verifying its
+source. Repository instructions and owner authority still govern.
+
+Select an exact release through a source already trusted by the owner. Record
+version, source commit when verified, artifact URL/integrity and the dependency
+lock. Mutable dist-tags are discovery hints, not final pins. A declaration in a
+lock or a digest supplied beside a download does not authenticate a publisher.
+An unpublished candidate must be labeled as such; use it only in an expressly
+selected rehearsal. Never invent a release or replace a pinned install with main.
+
+## Prepare without disturbing authoring
+
+Use a separate candidate with an identified base. Preserve dirty source and
+private answers; do not stash, reset, clean, stop services or commit another
+writer's edits to create eligibility. If using a snapshot of current edits,
+record and recheck its exact manifest; it is a snapshot, not an adopted commit.
+Ignored answers, browser storage and runtime credentials are not in a Git clone.
+Record that gap without importing them into a public report or projection.
+
+Stage the selected package using the owner's package manager and lock procedure,
+with lifecycle scripts disabled; investigate any required scripts before execution.
+Verify the resolved identity and inventory before running its commands. Inspect
+migration/compatibility effects before rewriting the old Atelier lock. Retain the
+old lock and all lineage. Keep installation changes distinct from generated files.
+
+Check exact-plan eligibility: Linux/macOS, one managed repository at `.`, config
+and workspace at its root, linked candidate worktree, clean state and supported
+Git settings. Packs, overlays and other unsupported participants require the
+repository's explicit operator procedure. Do not broaden graph roots, remove
+policies or disable filters/hooks to force eligibility. Never silently fall back
+to legacy `upgrade --apply`; it has different guarantees.
+
+For an eligible candidate, prepare `upgrade plan --save`, then use
+`upgrade explain --plan SAVED_PLAN_PATH` (JSON) and `--format markdown` (owner
+view). Invoke the verified installed binary with the explicit project path.
+Inspect `bindingsCurrent` and blockers even when the explanation exits zero.
+Keep source/pin/policy installation commits and the saved projection plan separate.
+For an operator procedure, retain an exact before/after file manifest and named
+commands instead; do not call it an exact-plan transaction or invent its digest.
+
+## Explain and retain consent
+
+Present the local benefit, exact target, changed files, preserved customizations,
+checks, known limits, recovery coverage and proposed effects. Show installation,
+local commit, merge, publication and activation separately. Ask one concrete
+question covering the effects that still need authority. A permission to prepare
+or a generic earlier “go” does not approve a newly introduced material effect.
+A prior explicit approval of this same current plan and effects remains valid.
+
+Retain a new decision record in ignored, untracked
+`.atelier-local/guided-upgrades/` (or a private sibling evidence directory):
+`kind: owner-decision`, report and plan/manifest SHA-256, candidate base, target
+identity, exact owner words, conversation reference, observation time, decision
+(approve/defer/decline), allowed effects, and
+`humanApprovalAuthenticated: false`, `recordedBy: agent`.
+Do not invent identity, words, references or approvals; missing provenance is a
+reported gap. This is an agent-attested record, not an authenticated signature or
+an execution grant. Keep existing records immutable. Silence conveys no consent.
+
+## Apply, validate and close
+
+After actual approval, use the saved path and exact confirmation digest literally.
+Recheck bindings; changed or expired plans require a fresh explanation and any
+newly necessary decision. A consumed plan is inspected, never replayed.
+Run the repository's documented acceptance checks and inspect the actual diff.
+Only a verified terminal transaction receipt means a candidate commit completed.
+Honor existing hooks and keep source/answer files within their ownership boundary.
+An operator procedure has its own validation evidence, not a transaction receipt.
+
+Continue authorized merge/activation steps only when included in the owner's
+scope. Report prepared, installed-in-candidate, committed, merged and running as
+separate observed states. A local preview passing is not recipient acceptance.
+On failure, preserve the candidate, backups and receipts; explain what changed
+and the next safe action. Recovery inspection does not automatically restore
+files or reset Git. Do not publish source, restart an existing service or advance
+an author's workflow phase merely because upgrade checks passed.

package/skills/codex/atelier-open/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: atelier-open
+description: Open the local Atelier preview in the current client when asked to show the portal or current page.
+---
+
 # Open the Atelier
 
 Use this skill when someone says "open the atelier", "pull up the atelier",

package/skills/codex/atelier-skill-steward/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: atelier-skill-steward
+description: Audit, create, improve, reconcile, retire, or update an Atelier-backed agent skill catalog using evidence thresholds, behavioral checks, and reversible managed projections.
+---
+
+# Atelier skill steward
+
+Use this skill when a repository should maintain its agent skills as a coherent,
+self-improving catalog. Do not use it to turn a one-off preference into a skill,
+capture prompts or transcripts, or grant a skill new authority implicitly.
+
+## Route the work
+
+- Audit the current catalog with `atelier skills audit --json`.
+- Record only a content-free signal with `atelier skills observe`; use a stable
+  workflow key, enumerated signal, optional skill name, and outcome. Never put a
+  summary, prompt, source excerpt, person, client, or private method in the key.
+- Find evidence-thresholded work with `atelier skills candidates --json`.
+- Create or improve an authored skill only when the candidate evidence and the
+  current task establish a repeatable input, workflow, and success condition.
+- Update a repo-scoped deployed catalog with `atelier skills sync`. Review the
+  plan, then repeat its exact digest with `--apply --confirm`. Never manufacture
+  confirmation before inspecting blockers and actions.
+
+## Authoring boundary
+
+Keep each skill focused. Give `SKILL.md` lowercase kebab-case `name` and a
+discriminating `description`; put only decision-changing guidance in the body.
+Add scripts or references only when deterministic reuse or progressive
+disclosure justifies them. Test direct triggers, indirect triggers, incomplete
+inputs, non-triggers, and risky edge cases.
+
+In the public Atelier repository, read `AGENTS.md`, `CONTRIBUTING.md`, and
+`docs/release-engineering.md` before editing. Re-derive private lessons as
+generic invariants with invented fixtures. Keep Codex and Claude bundles
+byte-identical and run the repository disclosure and release gates required by
+those documents.
+
+## Promotion policy
+
+An instruction-only change that retains the same tools, data boundary, and
+external authority may advance after its behavioral checks and catalog audit
+pass. New scripts, tool dependencies, network access, filesystem scope,
+external messages, spending, destructive operations, credential handling, or
+audience changes require explicit human authorization immediately before that
+authority is introduced.
+
+Do not treat an audit pass as proof of behavioral quality. Compare the candidate
+against representative positive and negative requests. Reject it when it only
+memorizes one incident, broadens its trigger, weakens a refusal, or cannot name
+observable improvement.
+
+## Retirement and updates
+
+Remove obsolete skills from active discovery only after checking dependents and
+supersession. Preserve recovery through Git or the sync quarantine; never
+permanently delete a managed deployed bundle during sync. A locally drifted or
+unmanaged target is a blocker, not permission to overwrite it.
+
+The steward has no model provider, telemetry, send path, browser apply endpoint,
+or hidden source-mutation authority. Scheduling may invoke this workflow, but a
+schedule does not widen its permissions or lower its evidence gates.

package/skills/codex/mnstry-readiness/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: mnstry-readiness
+description: Prepare or review Atelier readiness outputs for a project workspace using its readiness protocols.
+---
+
 # MNSTRY Readiness
 
 Use this skill when preparing or reviewing MNSTRY Atelier readiness outputs for

package/src/access/preview-enforcer.mjs

@@ -0,0 +1,84 @@
+import { parseRequest, parseBoundedJSON, need, isRef, isDigest, canonical, deepFreeze, MODES } from '../composition/wire.mjs';
+import { digestBytes } from '../composition/registry.mjs';
+
+const messages = Object.freeze({ loading: 'Checking access.', ready: 'Preview ready.', unauthenticated: 'Sign in to preview.',
+  forbidden: 'Preview is not permitted.', expired: 'Session expired.', unavailable: 'Preview unavailable.', stale: 'Preview changed. Refresh to continue.' });
+export class PreviewRefusal extends Error {
+  constructor(state) { super('Preview refused'); need(Object.hasOwn(messages, state) && !['ready', 'loading'].includes(state)); this.state = state; }
+}
+function principal(p) { need(p && isRef(p.issuer) && isRef(p.subject) && ['human', 'agent', 'service', 'local-owner'].includes(p.kind)); }
+function sessionCheck(s, now) {
+  need(s && Number.isSafeInteger(s.generation) && s.generation >= 0 && Number.isFinite(s.expiresAt));
+  for (const k of ['sessionRef', 'workspaceRef', 'audienceRef', 'policyRevision']) need(isRef(s[k]));
+  need(s.tenantRef === null || isRef(s.tenantRef));
+  // This prototype deliberately cannot admit production or implicit public access.
+  need(s.plane === 'preview');
+  if (!s.principal) throw new PreviewRefusal('unauthenticated');
+  principal(s.principal); principal(s.representedPrincipal);
+  if (s.expiresAt <= now) throw new PreviewRefusal('expired');
+}
+function checkDelegation(s, request, target, now) {
+  const d = s.delegation;
+  if (!d) {
+    need(s.principal.kind !== 'agent' && canonical(s.principal) === canonical(s.representedPrincipal)); return;
+  }
+  need(s.principal.kind === 'agent' && d.active === true && d.redelegationAllowed === false && isRef(d.ref) && isRef(d.revision));
+  need(Number.isFinite(d.expiresAt) && d.expiresAt > now && d.expiresAt <= s.expiresAt);
+  need(canonical(d.actor) === canonical(s.principal) && canonical(d.representedPrincipal) === canonical(s.representedPrincipal));
+  for (const key of ['sessionRef', 'generation', 'tenantRef', 'workspaceRef', 'audienceRef', 'plane']) need(d[key] === s[key]);
+  for (const key of ['modes', 'operationRefs', 'resourceRefs']) need(Array.isArray(d[key]) && d[key].length <= 64 && new Set(d[key]).size === d[key].length);
+  need(d.modes.every(m => MODES.includes(m)) && d.operationRefs.every(isRef) && d.resourceRefs.every(isRef));
+  if (!d.modes.includes(request.mode) || !d.operationRefs.includes(target.operationRef) || !d.resourceRefs.includes(target.resourceRef)) throw new PreviewRefusal('forbidden');
+}
+export function createPreviewEnforcer(ports, { now = Date.now } = {}) {
+  for (const key of ['authenticate', 'resolveTarget', 'authorize', 'revalidate', 'perform', 'projectResult', 'audit']) need(typeof ports?.[key] === 'function');
+  return Object.freeze({ async handle(channel, bytes, signal) {
+    let request, binding, phase = 'parse', performed = false;
+    const generation = Number.isSafeInteger(channel?.generation) && channel.generation >= 0 ? channel.generation : 0;
+    const state = (name, projectedData) => deepFreeze({ state: {
+      schema: 'atelier-preview-state/proposal-v1', requestId: request?.requestId || 'invalid', placementId: request?.placementId || 'invalid',
+      sourceDigest: request?.sourceDigest || '0'.repeat(64), mode: request?.mode || 'synthetic', state: name,
+      sessionGeneration: generation, publicMessage: messages[name],
+    }, ...(name === 'ready' ? { projectedData } : {}) });
+    const live = () => { if (signal?.aborted) throw new PreviewRefusal('stale'); if (binding && binding.expiresAt <= now()) throw new PreviewRefusal('expired'); };
+    const fresh = async () => { live(); if (await ports.revalidate(binding, signal) !== true) throw new PreviewRefusal('stale'); live(); };
+    const audit = (stage, outcome) => ports.audit(deepFreeze({ binding, phase: stage, outcome }));
+    try {
+      request = deepFreeze(parseRequest(bytes)); live(); phase = 'authenticate';
+      const s = deepFreeze(structuredClone(await ports.authenticate(channel, signal)));
+      sessionCheck(s, now()); live(); phase = 'resolve';
+      const t = deepFreeze(structuredClone(await ports.resolveTarget(s, request, signal)));
+      for (const key of ['resourceRef', 'operationRef', 'serviceRef', 'sourceRef', 'placementRef', 'registryRevision']) need(isRef(t?.[key]));
+      for (const key of ['sourceDigest', 'descriptorDigest', 'rendererDigest']) need(isDigest(t[key]));
+      need(t.sourceDigest === request.sourceDigest && t.placementRef === request.placementId);
+      checkDelegation(s, request, t, now());
+      binding = deepFreeze({ sessionRef: s.sessionRef, generation: s.generation, principal: s.principal, representedPrincipal: s.representedPrincipal,
+        delegationRef: s.delegation?.ref || null, delegationRevision: s.delegation?.revision || null,
+        tenantRef: s.tenantRef, workspaceRef: s.workspaceRef, plane: s.plane, mode: request.mode, audienceRef: s.audienceRef,
+        target: t, requestRef: request.requestId, requestDigest: digestBytes(canonical(request)), policyRevision: s.policyRevision,
+        expiresAt: Math.min(s.expiresAt, s.delegation?.expiresAt ?? Infinity) });
+      phase = 'authorize'; live(); await audit('requested', 'pending');
+      const decision = deepFreeze(structuredClone(await ports.authorize(binding, signal))); live();
+      need(canonical(decision?.binding) === canonical(binding));
+      if (decision.outcome !== 'allow') throw new PreviewRefusal(decision.outcome === 'deny' ? 'forbidden' : decision.outcome === 'reauth-required' ? 'expired' : 'unavailable');
+      await audit('authorized', 'allowed'); await fresh(); phase = 'perform'; performed = true;
+      const raw = await ports.perform(s, request, decision, signal);
+      await fresh(); phase = 'project';
+      const projected = await ports.projectResult(binding, raw, signal);
+      // Trusted projector owns the field allowlist. Root still enforces JSON,
+      // byte/depth bounds and cannot accidentally serialize result metadata.
+      const data = parseBoundedJSON(JSON.stringify(projected));
+      // Preparation is not a browser delivery acknowledgement. Keep the last
+      // asynchronous audit inside the revalidation boundary before returning.
+      await fresh(); await audit('settled', 'prepared'); await fresh();
+      return state('ready', data);
+    } catch (error) {
+      const name = error instanceof PreviewRefusal ? error.state : 'unavailable';
+      if (binding) {
+        try { await audit('settled', performed ? 'uncertain' : name === 'stale' ? 'stale' : phase === 'authorize' ? 'denied' : 'failed'); }
+        catch { /* No output or automatic effect retry if audit storage fails. */ }
+      }
+      return state(name);
+    }
+  } });
+}

package/src/boundary/policy.mjs

@@ -146,7 +146,7 @@ export function validateBoundaryPolicy(policy, project = null) {
     const declaredRepos = isObject(repos) ? repos : {}
     for (const [index, exception] of policy.contentRuleExceptions.entries()) {
       const name = firstString(exception?.repo)
-      if (name && Object.keys(declaredRepos).length && !declaredRepos[name]) {
+      if (name && Object.keys(declaredRepos).length && !Object.hasOwn(declaredRepos, name)) {
         errors.push(`contentRuleExceptions[${index}].repo ${name} is not declared in repos`)
       }
     }
@@ -163,7 +163,7 @@ export function validateBoundaryPolicy(policy, project = null) {
     }
     if (!firstString(actor.privateDomainRepo)) errors.push(`actors.${actorId}.privateDomainRepo is required`)
     if (firstString(actor.privateDomainRepo) && isObject(repos)) {
-      const privateRepo = repos[actor.privateDomainRepo]
+      const privateRepo = Object.hasOwn(repos, actor.privateDomainRepo) ? repos[actor.privateDomainRepo] : null
       if (!privateRepo) {
         errors.push(`actors.${actorId}.privateDomainRepo ${actor.privateDomainRepo} is not declared in repos`)
       } else if (privateRepo.kind !== 'private_domain') {
@@ -188,7 +188,7 @@ export function validateBoundaryPolicy(policy, project = null) {
     errors.push(...validAudienceList(repo.forbiddenAudiences, `repos.${repoName}.forbiddenAudiences`))
     if (repo.kind === 'private_domain') {
       if (!firstString(repo.ownerActor)) errors.push(`repos.${repoName}.ownerActor is required for private_domain repos`)
-      if (repo.ownerActor && isObject(actors) && !actors[repo.ownerActor]) errors.push(`repos.${repoName}.ownerActor ${repo.ownerActor} is not declared`)
+      if (repo.ownerActor && isObject(actors) && !Object.hasOwn(actors, repo.ownerActor)) errors.push(`repos.${repoName}.ownerActor ${repo.ownerActor} is not declared`)
     }
   }
 
@@ -197,35 +197,61 @@ export function validateBoundaryPolicy(policy, project = null) {
       if (repo.external) {
         // Declaring a boundary for a repo nobody manages is the confusion the
         // external kind exists to remove.
-        if (repos[repo.name]) errors.push(`policy repos.${repo.name} must not be declared; it is an external (unmanaged) repo`)
+        if (Object.hasOwn(repos, repo.name)) errors.push(`policy repos.${repo.name} must not be declared; it is an external (unmanaged) repo`)
         continue
       }
-      if (!repos[repo.name]) errors.push(`policy repos.${repo.name} must be declared`)
+      if (!Object.hasOwn(repos, repo.name)) errors.push(`policy repos.${repo.name} must be declared`)
     }
   }
 
   return errors
 }
 
-export function resolveCurrentActor({ policy, project, actor = null, env = process.env, gitExecutable = 'git', allowNetworkActorResolution = true, allowHistoryActorResolution = true } = {}) {
+function resolveExplicitActor({ policy, actor, env }) {
   const actors = policy?.actors ?? {}
-  const explicit = actor || env.MNSTRY_ATELIER_ACTOR || env.GITHUB_ACTOR
-  if (explicit && actors[explicit]) return { actorId: explicit, source: 'explicit' }
-  const gitEmails = gitEmailsForProject(project, { gitExecutable, env, allowHistoryActorResolution })
-  for (const [actorId, info] of Object.entries(actors)) {
-    const actorEmails = new Set(asArray(info.gitEmails).map((email) => email.toLowerCase()))
-    if (gitEmails.some((email) => actorEmails.has(email.toLowerCase()))) return { actorId, source: 'git-email', gitEmails }
+  const explicit = actor || env.MNSTRY_ATELIER_ACTOR
+  const unverified = (reason) => ({ actorId: null, source: 'unverified', reason })
+  if (actor && env.MNSTRY_ATELIER_ACTOR && actor !== env.MNSTRY_ATELIER_ACTOR) {
+    return unverified('conflicting-explicit-actors')
   }
-  const login = env.GITHUB_ACTOR || (allowNetworkActorResolution ? ghLogin() : null)
+  if (explicit && !Object.hasOwn(actors, explicit)) return unverified('unknown-explicit-actor')
+  return explicit ? { actorId: explicit, source: 'explicit' } : null
+}
+
+export function resolveCurrentActor({ policy, project, actor = null, env = process.env, gitExecutable = 'git', allowNetworkActorResolution = true, allowHistoryActorResolution = false } = {}) {
+  const actors = policy?.actors ?? {}
+  const explicit = resolveExplicitActor({ policy, actor, env })
+  if (explicit) return explicit
+  const unverified = (reason) => ({ actorId: null, source: 'unverified', reason })
+  // Without an explicit local selector, a platform login precedes Git metadata.
+  // It is platform attribution only; this function cannot authenticate its env.
+  const platformLogin = env.GITHUB_ACTOR
+  if (platformLogin) {
+    const matches = Object.entries(actors).filter(([, info]) =>
+      !String(info.githubLogin || '').endsWith('_GITHUB_LOGIN_PLACEHOLDER') &&
+      String(info.githubLogin || '').toLowerCase() === String(platformLogin).toLowerCase())
+    if (matches.length !== 1) return unverified(matches.length ? 'ambiguous-platform-actor' : 'unknown-platform-actor')
+    return { actorId: matches[0][0], source: 'github-login', githubLogin: platformLogin }
+  }
+  // Keep the legacy option accepted by the API, but history is never evidence
+  // of the person currently operating a checkout.
+  const gitEmails = gitEmailsForProject(project, { gitExecutable, env, allowHistoryActorResolution: false })
+  const matches = Object.entries(actors).filter(([, info]) => {
+    const actorEmails = new Set(asArray(info.gitEmails).map((email) => email.toLowerCase()))
+    return gitEmails.some((email) => actorEmails.has(email.toLowerCase()))
+  })
+  if (matches.length > 1) return unverified('ambiguous-git-actor')
+  if (matches.length === 1) return { actorId: matches[0][0], source: 'git-email', gitEmails }
+  const login = allowNetworkActorResolution ? ghLogin() : null
   if (login) {
-    for (const [actorId, info] of Object.entries(actors)) {
-      if (String(info.githubLogin || '').toLowerCase() === String(login).toLowerCase()) return { actorId, source: 'github-login', githubLogin: login }
-    }
+    const matches = Object.entries(actors).filter(([, info]) => !String(info.githubLogin || '').endsWith('_GITHUB_LOGIN_PLACEHOLDER') && String(info.githubLogin || '').toLowerCase() === String(login).toLowerCase())
+    if (matches.length !== 1) return unverified(matches.length ? 'ambiguous-platform-actor' : 'unknown-platform-actor')
+    return { actorId: matches[0][0], source: 'github-login', githubLogin: login }
   }
-  return { actorId: null, source: 'unverified', gitEmails, githubLogin: login || null }
+  return { actorId: null, source: 'unverified', gitEmails, githubLogin: null }
 }
 
-function gitEmailsForProject(project, { gitExecutable = 'git', env = process.env, allowHistoryActorResolution = true } = {}) {
+function gitEmailsForProject(project, { gitExecutable = 'git', env = process.env, allowHistoryActorResolution = false } = {}) {
   const roots = unique([project?.repoOpsRoot, project?.workspaceRoot, ...managedRepos(project).map((repo) => repo.path)])
   const emails = []
   for (const root of roots) {
@@ -249,7 +275,7 @@ function ghLogin() {
 }
 
 function repoPolicy(policy, repoName) {
-  return policy?.repos?.[repoName] ?? null
+  return policy?.repos && Object.hasOwn(policy.repos, repoName) ? policy.repos[repoName] : null
 }
 
 function finding({ severity = 'error', code, message, repo = null, path: itemPath = null, node = null, details = {} }) {
@@ -282,13 +308,19 @@ function nodePlacementFindings({ node, policy }) {
 
 function actorFindings({ policy, project, actor, gitExecutable, allowNetworkActorResolution, allowHistoryActorResolution, forceActorErrors }) {
   const findings = []
-  const current = resolveCurrentActor({ policy, project, actor, gitExecutable, allowNetworkActorResolution, allowHistoryActorResolution })
+  const operatedRepos = new Set(managedRepos(project).map((repo) => repo.name))
+  const ownedRepos = Object.entries(policy.repos ?? {}).filter(([name, repo]) =>
+    operatedRepos.has(name) && repo?.kind === 'private_domain' && repo.ownerActor)
+  const explicit = resolveExplicitActor({ policy, actor, env: process.env })
+  if (explicit?.reason) return [finding({ severity: 'error', code: 'actor-resolution-refused', message: explicit.reason })]
+  // Shared-only work needs no derived identity and must not invoke Git or gh.
+  if (!ownedRepos.length) return findings
+  const current = explicit || resolveCurrentActor({ policy, project, actor, gitExecutable, allowNetworkActorResolution, allowHistoryActorResolution })
   const severity = forceActorErrors ? 'error' : severityFor(policy)
-  for (const [repoName, repo] of Object.entries(policy.repos ?? {})) {
-    if (repo.kind !== 'private_domain') continue
-    if (!repo.ownerActor) continue
+  for (const [repoName, repo] of ownedRepos) {
     if (!current.actorId) {
-      findings.push(finding({ severity, code: 'private-domain-actor-unverified', repo: repoName, message: `${repoName}: could not verify local actor for private domain repo owned by ${repo.ownerActor}` }))
+      findings.push(finding({ severity, code: 'private-domain-actor-unverified', repo: repoName,
+        message: `${repoName}: could not verify local actor for private domain repo owned by ${repo.ownerActor}${current.reason ? ` (${current.reason})` : ''}` }))
     } else if (current.actorId !== repo.ownerActor) {
       findings.push(finding({ severity, code: 'private-domain-actor-mismatch', repo: repoName, message: `${repoName}: private domain repo is owned by ${repo.ownerActor}, but current actor is ${current.actorId}` }))
     }
@@ -603,7 +635,7 @@ function promotionFindings({ policy, project, graph }) {
   return findings
 }
 
-export function checkBoundaryPolicy({ project, policy, staged = false, stagedOnly = false, actor = null, gitExecutable = 'git', allowNetworkActorResolution = true, allowHistoryActorResolution = true, forceActorErrors = false } = {}) {
+export function checkBoundaryPolicy({ project, policy, staged = false, stagedOnly = false, actor = null, gitExecutable = 'git', allowNetworkActorResolution = true, allowHistoryActorResolution = false, forceActorErrors = false } = {}) {
   const validationErrors = validateBoundaryPolicy(policy, project)
   let graph = null
   const findings = validationErrors.map((message) => finding({ severity: 'error', code: 'boundary-policy-invalid', message }))

package/src/cli/project-options.mjs

@@ -0,0 +1,58 @@
+// Shared project-location syntax. Command-specific arguments remain owned by
+// their command; this parser does not make unknown options globally valid.
+export const PROJECT_OPTION_SPEC = Object.freeze({
+  project: 'value',
+  'project-config': 'value',
+  'repo-path': 'value',
+})
+
+function invalid(message) {
+  const error = new Error(message)
+  error.code = 'project-option-invalid'
+  error.exitCode = 2
+  throw error
+}
+
+export function projectOptionAt(argv, index, configArgPrefix = '--project-config=') {
+  const arg = argv[index]
+  if (typeof arg !== 'string' || !arg.startsWith('--')) return null
+  const name = arg.slice(2).split('=')[0]
+  const custom = configArgPrefix !== '--project-config=' && arg.startsWith(configArgPrefix)
+  if (!custom && !Object.hasOwn(PROJECT_OPTION_SPEC, name)) return null
+  const inline = custom || arg.includes('=')
+  const value = custom ? arg.slice(configArgPrefix.length) : inline ? arg.slice(arg.indexOf('=') + 1) : argv[index + 1]
+  if (typeof value !== 'string' || !value.trim() || value.startsWith('--')) {
+    invalid(`--${custom ? 'project-config' : name} requires a non-empty value`)
+  }
+  const option = custom ? 'project-config' : name
+  if (option === 'repo-path') {
+    const separator = value.indexOf('=')
+    if (separator < 1 || !value.slice(0, separator).trim() || !value.slice(separator + 1).trim()) {
+      invalid('--repo-path requires NAME=PATH')
+    }
+  }
+  return { name: option, value, nextIndex: index + (inline ? 1 : 2) }
+}
+
+export function parseProjectOptions(argv = [], configArgPrefix = '--project-config=') {
+  let project = null
+  const repoPaths = new Map()
+  const remaining = []
+  for (let index = 0; index < argv.length;) {
+    const option = projectOptionAt(argv, index, configArgPrefix)
+    if (!option) {
+      remaining.push(argv[index++])
+      continue
+    }
+    if (option.name === 'repo-path') {
+      const separator = option.value.indexOf('=')
+      repoPaths.set(option.value.slice(0, separator).trim(), option.value.slice(separator + 1))
+    } else if (project === null) {
+      // Preserve the resolver's first project selection and last named repo
+      // override behavior, including aliases in the same invocation.
+      project = option.value.trim()
+    }
+    index = option.nextIndex
+  }
+  return { project, repoPaths, remaining }
+}

package/src/cli/run.mjs

@@ -59,6 +59,10 @@ export const commandMap = new Map([
   ['announcements', ['src/commands/announcements.mjs']],
   ['announcements:list', ['src/commands/announcements.mjs', 'list']],
   ['sync', ['src/commands/sync.mjs']],
+  ['review', ['src/commands/review.mjs']],
+  ['coauthor', ['src/commands/coauthor.mjs']],
+  ['skills', ['src/commands/skills.mjs']],
+  ['obsidian', ['src/commands/obsidian.mjs']],
 ])
 
 function isDefaultBrand(brand) {
@@ -122,14 +126,24 @@ Core commands:
   sync plan                       Prepare one bounded, reviewable commit plan.
   sync commit                     Execute an exactly confirmed commit plan.
   sync run --once                 Run one full-state supervisor cycle.
+  obsidian status|open|apply      Maintain and open Obsidian views of the corpus; apply edits made in them.
   egress check                    Check extracted Atelier paths for forbidden egress.
   boundary check                  Enforce private/shared repo placement rules.
   boundary audit                  Report content-rule matches tree-wide without blocking.
   boundary install-hooks          Install staged/private-domain Git guards.
   promote                         Record a git.promote disclosure event.
-  upgrade --dry-run               Plan a safe package/template upgrade.
+  upgrade plan --save             Save an exact local candidate plan.
+  upgrade explain --plan          Explain saved changes and consent without writes.
+  upgrade apply --plan --confirm   Apply the selected plan through commit hooks.
+  upgrade status|recover          Inspect receipts or preview recovery.
+  upgrade --dry-run               Plan a legacy package/template upgrade.
   upgrade --apply                 Apply a branch-based reviewable upgrade.
   lock check|write                Verify or create atelier.lock.json.
+  lock provenance                Inspect actual installed package identity.
+  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.
+  skills audit|observe|candidates|sync Audit and manage local skill projections.
   config check                    Validate project config.
   extension-pack validate         Validate declared extension packs.
   extension-pack list             List declared extension packs.
@@ -145,6 +159,9 @@ Attestation commands:
 Commands whose usage names --project accept --project=PATH or --project PATH.
 The project resolver also accepts --project-config=PATH and
 MNSTRY_ATELIER_PROJECT_CONFIG=PATH; each command's own help is authoritative.
+Project-aware commands accept repeated --repo-path NAME=PATH or
+--repo-path=NAME=PATH. Overrides change location, never declared read authority.
+Run config check --explain for path-free resolution sources.
 Machine-local repo paths belong in
 .atelier-local/, atelier.local.json, or atelier.workspace.local.json.`
 }
@@ -152,7 +169,14 @@ Machine-local repo paths belong in
 export function buildCommandHelpText(command, brand = DEFAULT_BRAND) {
   const c = brand.command
   const help = {
-    init: `Usage: ${c} init [--template private-domain|shared-project|sample-workspace|distribution] [--target DIR] [--actor ID]
+    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.
+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]
 
 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]
@@ -183,7 +207,7 @@ Runs the bundled MNSTRY readiness pack claim-first. Protocol state and packet dr
   ${c} extension-pack validate [--json] [--project ./atelier.project.json]
   ${c} extension-pack list [--json] [--project ./atelier.project.json]
 
-Loads every extension pack declared under ext["mnstry.atelier"].extensionPacks in the tracked project config and reports one line per pack. Packs load additively alongside the bundled MNSTRY protocols and can never replace them. list is the default subcommand.`,
+Loads every extension pack declared under ext["mnstry.atelier"].extensionPacks in the tracked project config and reports one line per pack. Packs load additively alongside the bundled MNSTRY protocols and can never replace them. list is the default subcommand. Shared --project-config and repeated --repo-path NAME=PATH options are supported in both space and equals forms.`,
     distribution: `Usage: ${c} distribution check [--target DIR] [--pack DIR]
 
 Checks a distribution package for the required MNSTRY attribution markers. Blocking: the distribution README.md byte check, and a CLI probe that EXECUTES the target's declared bin with --version (spawned with the current Node, cwd set to the target — only run this against distributions you trust) and requires the attribution in its output; a target that looks like a distribution but declares no probe-able bin, or ships a malformed package.json, is also blocking. The extension-pack manifest attribution key is advisory and reported only. The normative wording lives in TRADEMARKS.md under "Required attribution"; see also docs/attestation.md and docs/distributions.md.`,
@@ -205,6 +229,22 @@ 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]
+
+  ${c} obsidian status
+  ${c} obsidian scope list | scope show ID
+  ${c} obsidian audience show | set 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 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.`,
     sync: `Usage:
   ${c} sync enroll --repo DIR [--project atelier.project.json] [--git ABSOLUTE_PATH]
   ${c} sync status --repo DIR