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

package/src/graph-workspace/model.mjs

@@ -0,0 +1,109 @@
+// Workspace model: the shared read model behind every graph-workspace room.
+//
+// Input is an Atelier knowledge graph (`mnstry.atelier-knowledge-graph@v1`) that a
+// host has already limited to what the reader may see, plus an optional knowledge
+// plan. Output is plain data the browser rooms can draw. This module reads no files,
+// grants nothing and infers no relation:
+// - zones come only from the owner's folder structure (a zone rule),
+// - concept membership comes only from a record's own `concept:<id>` tag,
+// - edges keep their declared direction and fall into three classes.
+
+const SCHEMA = 'mnstry.atelier-knowledge-graph@v1'
+export const EDGE_CLASSES = Object.freeze(['link', 'containment', 'relation'])
+
+/** `related` is a written link, `belongs_to` is folder containment, anything else is a declared relation. */
+export function edgeClass(type) {
+  if (type === 'related') return 'link'
+  if (type === 'belongs_to') return 'containment'
+  return 'relation'
+}
+
+const humanize = folder => folder.replace(/^[_\d-]+/, '').replace(/[-_]+/g, ' ').replace(/^\w/, c => c.toUpperCase()) || 'Other'
+
+export function validateZoneRule(rule = {}) {
+  const prefix = rule.prefix ?? ''
+  const depth = rule.depth ?? 1
+  if (typeof prefix !== 'string' || prefix.includes('..') || prefix.startsWith('/')) throw new TypeError('Zone rule prefix must be a relative path prefix')
+  if (!Number.isInteger(depth) || depth < 1 || depth > 4) throw new TypeError('Zone rule depth must be an integer from 1 to 4')
+  const labels = rule.labels ?? {}
+  if (typeof labels !== 'object' || Array.isArray(labels) || Object.values(labels).some(v => typeof v !== 'string' || v.length > 80)) throw new TypeError('Zone rule labels must map folders to short names')
+  return { prefix, depth, labels: Object.assign(Object.create(null), labels), rootLabel: typeof rule.rootLabel === 'string' ? rule.rootLabel.slice(0, 80) : 'Workspace root' }
+}
+
+/** The zone of records outside the folder rule. No folder id can be '/'. */
+export const ROOT_ZONE = '/'
+
+/** The owner-configured zone of a record path. Records outside the prefix share one root zone. */
+export function zoneOf(path, rule) {
+  const r = validateZoneRule(rule)
+  if (typeof path !== 'string' || !path.startsWith(r.prefix)) return { id: ROOT_ZONE, label: r.rootLabel }
+  const parts = path.slice(r.prefix.length).split('/')
+  if (parts.length <= r.depth) return { id: ROOT_ZONE, label: r.rootLabel }
+  const folder = parts.slice(0, r.depth).join('/')
+  return { id: folder, label: Object.hasOwn(r.labels, folder) ? r.labels[folder] : humanize(folder.split('/').at(-1)) }
+}
+
+export function buildWorkspaceModel({ graph, plan = null, zoneRule = {}, summaryLength = 280 }) {
+  if (graph?.schema !== SCHEMA || !Array.isArray(graph.nodes) || !Array.isArray(graph.edges)) throw new TypeError('An Atelier knowledge graph v1 is required')
+  const rule = validateZoneRule(zoneRule)
+  const seenIds = new Set()
+  const nodes = graph.nodes.map(n => {
+    if (typeof n.id !== 'string' || !n.id || seenIds.has(n.id)) throw new TypeError('Knowledge graph node ids must be unique non-empty strings')
+    seenIds.add(n.id)
+    const zone = zoneOf(n.path ?? '', rule)
+    const tags = Array.isArray(n.tags) ? n.tags.filter(t => typeof t === 'string') : []
+    return {
+      id: n.id, title: typeof n.title === 'string' && n.title ? n.title : n.id,
+      summary: typeof n.summary === 'string' ? n.summary.split('\n')[0].slice(0, summaryLength) : '',
+      type: n.type ?? 'document', status: n.status ?? null, audience: n.audience ?? null, path: n.path ?? null,
+      tags: tags.filter(t => !t.startsWith('concept:')).slice(0, 8),
+      concepts: tags.filter(t => t.startsWith('concept:')).map(t => t.slice(8)),
+      zone: zone.id, zoneLabel: zone.label, degree: 0, relationDegree: 0,
+    }
+  })
+  const byId = new Map(nodes.map(n => [n.id, n]))
+  const edges = []
+  const seen = new Set()
+  let outside = 0
+  for (const e of graph.edges) {
+    if (!byId.has(e.source) || !byId.has(e.target)) { outside++; continue }
+    if (e.source === e.target) continue
+    const key = `${e.source}\u0000${e.target}\u0000${e.type}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    const kind = edgeClass(e.type)
+    edges.push({ id: 'e' + edges.length, source: e.source, target: e.target, type: e.type, kind, declared: e.declared !== false })
+    for (const id of [e.source, e.target]) { const n = byId.get(id); n.degree++; if (kind === 'relation') n.relationDegree++ }
+  }
+  const counts = new Map()
+  for (const n of nodes) counts.set(n.zone, { id: n.zone, label: n.zoneLabel, count: (counts.get(n.zone)?.count ?? 0) + 1 })
+  const zones = [...counts.values()].sort((a, b) => b.count - a.count || (a.id < b.id ? -1 : 1)).map((z, index) => ({ ...z, index }))
+  return {
+    schema: 'atelier.graph-workspace-model@v1',
+    coverage: { records: nodes.length, links: edges.length, linksOutsideReadableSet: outside, byClass: Object.fromEntries(EDGE_CLASSES.map(k => [k, edges.filter(e => e.kind === k).length])) },
+    nodes, edges, zones,
+    plan: plan ? planModel(plan, nodes) : null,
+  }
+}
+
+function planModel(plan, nodes) {
+  const concepts = Array.isArray(plan.concepts) ? plan.concepts.filter(c => typeof c?.id === 'string') : []
+  const ids = new Set(concepts.map(c => c.id))
+  return {
+    purpose: typeof plan.purpose === 'string' ? plan.purpose : null,
+    concepts: concepts.map(c => ({
+      id: c.id, title: typeof c.title === 'string' ? c.title : c.id.replace(/-/g, ' ').replace(/^\w/, x => x.toUpperCase()),
+      definition: c.definition ?? '', identityRule: c.identityRule ?? '',
+      declaredBy: nodes.filter(n => n.concepts.includes(c.id)).map(n => n.id),
+    })),
+    relations: (plan.relations ?? []).filter(r => ids.has(r.from) && ids.has(r.to)).map(r => ({ id: r.id, predicate: r.predicate, from: r.from, to: r.to, meaning: r.meaning ?? '' })),
+    questions: (plan.questions ?? []).map(q => ({ id: q.id, question: q.question ?? q.title ?? q.id, concepts: (q.concepts ?? []).filter(id => ids.has(id)), relations: q.relations ?? [] })),
+  }
+}
+
+/** Neighbour ids of a record, in either direction, without duplicates. */
+export function neighbours(model, id) {
+  const out = new Set()
+  for (const e of model.edges) { if (e.source === id) out.add(e.target); else if (e.target === id) out.add(e.source) }
+  return [...out]
+}

package/src/graph-workspace/recipes.mjs

@@ -0,0 +1,88 @@
+// Work recipes, layered: Atelier ships defaults, a cohort coach adds or adjusts,
+// and the owner has the final say. A recipe is data that chooses the room, the lens
+// and the one primary action. Every resolved field records which layer set it.
+
+export const ROOMS = Object.freeze(['constellation', 'workbench', 'review'])
+export const LENSES = Object.freeze([null, 'question', 'concept', 'zone'])
+export const SUBJECTS = Object.freeze([null, 'record', 'concept', 'relation'])
+export const LAYERS = Object.freeze(['atelier', 'coach', 'owner'])
+/** The single emphasised action of a recipe. The default shell implements each one. */
+export const PRIMARY_ACTIONS = Object.freeze(['search', 'open-evidence', 'next-step', 'walk', 'review', 'pick'])
+
+/** The primary actions the default shell honours for a recipe's room, lens and subject. */
+export function primaryActionsFor({ room, lens = null, subject = null }) {
+  if (room === 'review') return ['review']
+  if (room === 'workbench') return subject === 'record' ? ['walk'] : ['next-step']
+  if (lens === 'zone') return ['pick', 'search']
+  if (lens) return ['open-evidence', 'pick', 'search']
+  return ['search']
+}
+
+export const DEFAULT_RECIPES = Object.freeze([
+  { id: 'explore', label: 'Explore', room: 'constellation', lens: null, subject: null, primary: 'search', description: 'Wander the whole graph. Zones on, search ready.' },
+  { id: 'question', label: 'Answer a question', room: 'constellation', lens: 'question', subject: null, primary: 'open-evidence', description: 'Light the records that declare a question’s concepts.' },
+  { id: 'refine', label: 'Refine a concept', room: 'workbench', lens: null, subject: 'concept', primary: 'next-step', description: 'One concept, one step at a time.' },
+  { id: 'inspect', label: 'Inspect a record', room: 'workbench', lens: null, subject: 'record', primary: 'walk', description: 'A record and its closest links, with room to read.' },
+].map(Object.freeze))
+
+const FIELDS = ['label', 'room', 'lens', 'subject', 'primary', 'description']
+const text = (v, max) => typeof v === 'string' && v.trim().length > 0 && v.length <= max
+
+export function validateRecipe(recipe, { partial = false } = {}) {
+  const problems = []
+  if (!recipe || typeof recipe !== 'object' || Array.isArray(recipe)) return ['recipe must be an object']
+  if (!/^[a-z][a-z0-9-]{0,47}$/.test(recipe.id ?? '')) problems.push('id must be a short lowercase slug')
+  for (const key of Object.keys(recipe)) if (!['id', 'hidden', ...FIELDS].includes(key)) problems.push(`unknown field ${key}`)
+  const need = !partial
+  if ((need || 'label' in recipe) && !text(recipe.label, 60)) problems.push('label must be 1–60 characters')
+  if ((need || 'description' in recipe) && !text(recipe.description, 200)) problems.push('description must be 1–200 characters')
+  if ((need || 'room' in recipe) && !ROOMS.includes(recipe.room)) problems.push(`room must be one of ${ROOMS.join(', ')}`)
+  if ('lens' in recipe && !LENSES.includes(recipe.lens)) problems.push('unknown lens')
+  if ('subject' in recipe && !SUBJECTS.includes(recipe.subject)) problems.push('unknown subject')
+  if ((need || 'primary' in recipe) && !PRIMARY_ACTIONS.includes(recipe.primary)) problems.push(`primary must be one of ${PRIMARY_ACTIONS.join(', ')}`)
+  if ('hidden' in recipe && typeof recipe.hidden !== 'boolean') problems.push('hidden must be true or false')
+  return problems
+}
+
+/**
+ * Compose recipe layers. Each layer is a list; an entry with an existing id adjusts
+ * it (partial), a new id adds a complete recipe, and `hidden: true` removes it from
+ * what the owner sees. Later layers win. Throws on any invalid entry.
+ */
+export function composeRecipes({ atelier = DEFAULT_RECIPES, coach = [], owner = [] } = {}) {
+  const resolved = new Map()
+  const provenance = new Map()
+  for (const [layer, list] of [['atelier', atelier], ['coach', coach], ['owner', owner]]) {
+    if (!Array.isArray(list)) throw new TypeError(`${layer} recipes must be a list`)
+    for (const entry of list) {
+      const existing = resolved.get(entry?.id)
+      const problems = validateRecipe(entry, { partial: !!existing })
+      if (problems.length) throw new TypeError(`${layer} recipe ${entry?.id ?? '(no id)'}: ${problems.join('; ')}`)
+      const next = { lens: null, subject: null, hidden: false, ...(existing ?? {}), ...entry }
+      // Only combinations a shell can honour: lenses belong to the constellation,
+      // subjects to the workbench, and the review room takes neither.
+      if (next.room === 'workbench' && !next.subject) throw new TypeError(`${layer} recipe ${entry.id}: a workbench recipe needs a subject`)
+      if (next.room !== 'workbench' && next.subject) throw new TypeError(`${layer} recipe ${entry.id}: only a workbench recipe takes a subject`)
+      if (next.room !== 'constellation' && next.lens) throw new TypeError(`${layer} recipe ${entry.id}: only a constellation recipe takes a lens`)
+      const actions = primaryActionsFor(next)
+      if (!actions.includes(next.primary)) throw new TypeError(`${layer} recipe ${entry.id}: primary ${next.primary} is not available here; use ${actions.join(' or ')}`)
+      resolved.set(entry.id, next)
+      const fields = provenance.get(entry.id) ?? {}
+      for (const key of Object.keys(entry)) if (key !== 'id') fields[key] = layer
+      if (!existing) for (const key of FIELDS) fields[key] ??= layer
+      provenance.set(entry.id, fields)
+    }
+  }
+  const visible = [...resolved.values()].filter(r => !r.hidden)
+  return { recipes: visible.map(r => ({ ...r, setBy: { ...provenance.get(r.id) } })), hidden: [...resolved.values()].filter(r => r.hidden).map(r => r.id) }
+}
+
+/** Recipes a workspace can actually run: concept work needs a plan with concepts. */
+export function availableRecipes(recipes, model) {
+  const concepts = !!model.plan?.concepts.length, relations = !!model.plan?.relations.length, questions = !!model.plan?.questions.length
+  return recipes.filter(r =>
+    (r.subject !== 'concept' || concepts) && (r.subject !== 'relation' || relations) &&
+    (r.lens !== 'question' || questions) && (r.lens !== 'concept' || concepts) &&
+    (r.room !== 'review' || concepts) && (r.subject !== 'record' || model.nodes.length > 0) &&
+    (r.lens !== 'zone' || model.zones?.length > 0))
+}

package/src/graph-workspace/scale.mjs

@@ -0,0 +1,95 @@
+// Scale primitives for workspaces with tens of thousands of records.
+//
+// A constellation draws every readable record while that stays legible and fast.
+// Beyond a budget, the whole is shown as zones (with honest counts and directed
+// bundles between them) and a person opens one zone at a time. Nothing here hides
+// a record silently: every bounded result states what it left out.
+
+export const DEFAULT_BUDGET = Object.freeze({ records: 12000, links: 60000 })
+
+/** Decide how the whole should be drawn for this model and budget. */
+export function planConstellation(model, budget = DEFAULT_BUDGET) {
+  const records = model.nodes.length, links = model.edges.length
+  if (records <= budget.records && links <= budget.links) return { mode: 'records', records, links }
+  return { mode: 'zones', records, links, reason: records > budget.records ? 'records-over-budget' : 'links-over-budget', budget: { ...budget } }
+}
+
+/** Zone-level summary of the whole: counts by type and directed bundles by edge class. */
+export function aggregateZones(model) {
+  const zoneOfId = new Map(model.nodes.map(n => [n.id, n.zone]))
+  const zones = model.zones.map(z => ({ id: z.id, label: z.label, index: z.index, count: z.count, types: Object.create(null), declaredRelations: 0 }))
+  const byId = new Map(zones.map(z => [z.id, z]))
+  for (const n of model.nodes) { const z = byId.get(n.zone); z.types[n.type] = (z.types[n.type] ?? 0) + 1 }
+  const bundles = new Map()
+  let internal = 0
+  for (const e of model.edges) {
+    const a = zoneOfId.get(e.source), b = zoneOfId.get(e.target)
+    if (a === b) { internal++; if (e.kind === 'relation') byId.get(a).declaredRelations++; continue }
+    const key = a + '\u0000' + b
+    const bundle = bundles.get(key) ?? { from: a, to: b, total: 0, link: 0, containment: 0, relation: 0 }
+    bundle.total++; bundle[e.kind]++
+    bundles.set(key, bundle)
+  }
+  return {
+    schema: 'atelier.graph-workspace-zones@v1',
+    coverage: { records: model.nodes.length, zones: zones.length, linksInsideZones: internal, linksBetweenZones: model.edges.length - internal, linksOutsideReadableSet: model.coverage.linksOutsideReadableSet },
+    zones,
+    bundles: [...bundles.values()].sort((x, y) => y.total - x.total || (x.from + x.to < y.from + y.to ? -1 : 1)),
+  }
+}
+
+/** Records ranked by connection count, then title, for budgets and label priority. */
+export function rankRecords(model) {
+  return [...model.nodes].sort((a, b) => b.degree - a.degree || (a.title < b.title ? -1 : a.title > b.title ? 1 : 0))
+}
+
+/**
+ * A bounded sub-model for one zone. Members are kept by rank up to `limit`.
+ * Every link touching the zone is accounted for exactly once:
+ *   drawn (both ends kept) + omittedInsideZone + toOtherZones + omittedToOtherZones = links touching the zone.
+ * Plan concept declarations are projected onto the kept records, with omissions counted.
+ */
+export function zoneSlice(model, zoneId, { limit = DEFAULT_BUDGET.records } = {}) {
+  const members = rankRecords(model).filter(n => n.zone === zoneId)
+  const kept = members.slice(0, limit)
+  const keep = new Set(kept.map(n => n.id))
+  const inZone = new Set(members.map(n => n.id))
+  const zoneOfId = new Map(model.nodes.map(n => [n.id, n.zone]))
+  const edges = []
+  const boundary = new Map()
+  let omittedInsideZone = 0, omittedToOtherZones = 0, touching = 0
+  for (const e of model.edges) {
+    const s = inZone.has(e.source), t = inZone.has(e.target)
+    if (!s && !t) continue
+    touching++
+    if (keep.has(e.source) && keep.has(e.target)) { edges.push(e); continue }
+    if (s && t) { omittedInsideZone++; continue }
+    const memberEnd = s ? e.source : e.target
+    if (!keep.has(memberEnd)) { omittedToOtherZones++; continue }
+    const other = zoneOfId.get(s ? e.target : e.source)
+    boundary.set(other, (boundary.get(other) ?? 0) + 1)
+  }
+  const toOtherZones = [...boundary.values()].reduce((a, b) => a + b, 0)
+  const byClass = { link: 0, containment: 0, relation: 0 }
+  for (const e of edges) byClass[e.kind]++
+  const plan = model.plan ? {
+    ...model.plan,
+    concepts: model.plan.concepts.map(c => {
+      const declaredBy = c.declaredBy.filter(id => keep.has(id))
+      return { ...c, declaredBy, omittedDeclarations: c.declaredBy.length - declaredBy.length }
+    }),
+  } : null
+  return {
+    ...model,
+    nodes: kept.map(n => ({ ...n })),
+    edges,
+    zones: model.zones.filter(z => z.id === zoneId).map(z => ({ ...z, count: kept.length })),
+    plan,
+    coverage: { records: kept.length, links: edges.length, byClass, linksOutsideReadableSet: model.coverage.linksOutsideReadableSet },
+    slice: {
+      zone: zoneId, membersInZone: members.length, omittedRecords: members.length - kept.length,
+      linksTouchingZone: touching, omittedLinksInsideZone: omittedInsideZone, omittedLinksToOtherZones: omittedToOtherZones, linksToOtherZonesCount: toOtherZones,
+      linksToOtherZones: [...boundary.entries()].map(([zone, count]) => ({ zone, count })).sort((a, b) => b.count - a.count),
+    },
+  }
+}

package/src/graph-workspace/theme.mjs

@@ -0,0 +1,156 @@
+// Graph-workspace themes: resolved token data, never stylesheets.
+// Atelier ships two neutral defaults, `night` (the default) and `paper`. A coach or
+// owner theme overrides values by name; the result is validated, including text
+// contrast, before any room applies it as CSS custom properties.
+
+const CSS_VARS = ['--canvas', '--surface', '--surface-2', '--surface-glass', '--ink', '--ink-2', '--ink-3', '--line', '--line-strong', '--accent', '--accent-ink', '--focus', '--warn', '--danger', '--ok', '--font-sans', '--font-display', '--radius', '--radius-lg', '--shadow', '--motion', '--ease']
+const GRAPH = ['canvas', 'edge', 'edgeStructural', 'dim', 'label', 'labelHalo', 'selection']
+
+const night = {
+  vars: {
+    '--canvas': '#0b0e14', '--surface': '#131823', '--surface-2': '#1a2030', '--surface-glass': 'rgba(19,24,35,0.82)',
+    '--ink': '#eef1f7', '--ink-2': '#b9c1d3', '--ink-3': '#8d97ad', '--line': 'rgba(238,241,247,0.12)', '--line-strong': 'rgba(238,241,247,0.26)',
+    '--accent': '#9cc4ff', '--accent-ink': '#08101d', '--focus': '#ffd479', '--warn': '#ffc46b', '--danger': '#ff9a8a', '--ok': '#8fe0b0',
+    '--font-sans': 'Inter, "SF Pro Text", -apple-system, system-ui, sans-serif', '--font-display': '"SF Pro Display", Inter, -apple-system, system-ui, sans-serif',
+    '--radius': '10px', '--radius-lg': '16px', '--shadow': '0 12px 40px rgba(0,0,0,0.45)', '--motion': '240ms', '--ease': 'cubic-bezier(0.2, 0, 0, 1)',
+  },
+  graph: { canvas: '#0b0e14', edge: '#7d88a3', edgeStructural: '#c9d2e6', dim: '#283044', label: '#e6eaf2', labelHalo: '#0b0e14', selection: '#ffd479',
+    zones: ['#7aa7ff', '#5fd1b0', '#f2a65a', '#c792ea', '#ff8fa3', '#e6d36a', '#6fd3f2', '#a4e07a', '#f28fd2', '#b0b8c8'] },
+}
+const paper = {
+  vars: {
+    ...night.vars,
+    '--canvas': '#f5f3ee', '--surface': '#ffffff', '--surface-2': '#f0ede6', '--surface-glass': 'rgba(255,255,255,0.86)',
+    '--ink': '#1a1d24', '--ink-2': '#454b58', '--ink-3': '#5f6676', '--line': 'rgba(26,29,36,0.12)', '--line-strong': 'rgba(26,29,36,0.28)',
+    '--accent': '#2c55a8', '--accent-ink': '#ffffff', '--focus': '#a05a00', '--warn': '#8a4a00', '--danger': '#a32121', '--ok': '#1f6b3c', '--shadow': '0 12px 36px rgba(20,22,30,0.14)',
+  },
+  graph: { canvas: '#f5f3ee', edge: '#9aa1ae', edgeStructural: '#4a5162', dim: '#dcd8cf', label: '#1a1d24', labelHalo: '#f5f3ee', selection: '#a05a00',
+    zones: ['#2f62c9', '#0f7259', '#9a4f0c', '#7a45a8', '#b83255', '#6f5d00', '#0f6a85', '#3f6c14', '#a3337f', '#5d6577'] },
+}
+
+export const DEFAULT_THEME = Object.freeze({
+  schema: 'atelier.graph-workspace-theme@v1', id: 'atelier-night', version: '1', defaultScheme: 'dark',
+  schemes: Object.freeze({ dark: night, light: paper }),
+})
+
+// Every token has one type. Only colours, lengths, durations, an easing and font
+// family names are accepted, so no theme value can load a resource or inject CSS.
+const HEX = /^#[0-9a-f]{6}$/i
+const RGBA = /^rgba\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*(?:0|1|0?\.\d{1,3})\s*\)$/i
+const COLOR = v => HEX.test(v)
+const SOFT_COLOR = v => HEX.test(v) || RGBA.test(v)
+const FONT = v => /^[A-Za-z0-9 "',.-]{1,160}$/.test(v) && !/["']{2}/.test(v)
+const LENGTH = v => /^\d{1,2}(?:\.\d{1,2})?px$/.test(v)
+const SHADOW = v => v === 'none' || v.split(/,(?![^()]*\))/).every(part => /^\s*(?:(?:0|-?\d{1,3}(?:\.\d{1,2})?px)\s+){2,4}(?:rgba\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*(?:0|1|0?\.\d{1,3})\s*\)|#[0-9a-f]{6})\s*$/i.test(part))
+const DURATION = v => /^\d{1,4}ms$/.test(v)
+const EASE = v => /^(?:ease|linear|ease-in|ease-out|ease-in-out|cubic-bezier\(\s*-?\d(?:\.\d{1,3})?\s*,\s*-?\d(?:\.\d{1,3})?\s*,\s*-?\d(?:\.\d{1,3})?\s*,\s*-?\d(?:\.\d{1,3})?\s*\))$/.test(v)
+export const TOKEN_TYPES = Object.freeze({
+  '--canvas': COLOR, '--surface': COLOR, '--surface-2': COLOR, '--surface-glass': SOFT_COLOR,
+  '--ink': COLOR, '--ink-2': COLOR, '--ink-3': COLOR, '--line': SOFT_COLOR, '--line-strong': SOFT_COLOR,
+  '--accent': COLOR, '--accent-ink': COLOR, '--focus': COLOR, '--warn': COLOR, '--danger': COLOR, '--ok': COLOR,
+  '--font-sans': FONT, '--font-display': FONT, '--radius': LENGTH, '--radius-lg': LENGTH, '--shadow': SHADOW, '--motion': DURATION, '--ease': EASE,
+})
+const LAYER_FIELDS = ['id', 'version', 'defaultScheme', 'schemes']
+const SCHEME_FIELDS = ['vars', 'graph']
+// Text and the surfaces it is drawn on in the rooms, with the minimum ratio for its size.
+const TEXT_PAIRS = [
+  ['--ink', '--canvas', 7], ['--ink', '--surface', 7], ['--ink', '--surface-2', 7],
+  ['--ink-2', '--canvas', 4.5], ['--ink-2', '--surface', 4.5], ['--ink-2', '--surface-2', 4.5],
+  ['--ink-3', '--canvas', 4.5], ['--ink-3', '--surface', 4.5], ['--ink-3', '--surface-2', 4.5],
+  ['--accent-ink', '--accent', 4.5], ['--accent', '--canvas', 4.5], ['--accent', '--surface', 4.5],
+  ['--warn', '--surface', 4.5], ['--danger', '--surface', 4.5], ['--ok', '--surface', 4.5],
+]
+// Text on the translucent chrome (pills, command bar, selection card), composited
+// over each backdrop it floats on.
+const GLASS_TEXT = [['--ink', 4.5], ['--ink-2', 4.5], ['--ink-3', 4.5]]
+const GLASS_BACKDROPS = ['--canvas', '--surface-2']
+function composite(over, under) {
+  const rgb = h => { const n = parseInt(h.slice(1, 7), 16); return [n >> 16, (n >> 8) & 255, n & 255] }
+  const m = RGBA.test(over) ? over.match(/[\d.]+/g).map(Number) : [...rgb(over), 1]
+  const [r, g, b, a] = [Math.min(255, m[0]), Math.min(255, m[1]), Math.min(255, m[2]), Math.min(1, m[3])]
+  const base = rgb(under)
+  return '#' + [r, g, b].map((v, i) => Math.round(v * a + base[i] * (1 - a)).toString(16).padStart(2, '0')).join('')
+}
+
+function layerProblems(layer, { partial }) {
+  const problems = []
+  if (!layer || typeof layer !== 'object' || Array.isArray(layer)) return ['theme layer must be an object']
+  for (const key of Object.keys(layer)) if (!LAYER_FIELDS.includes(key) && !(key === 'schema' && !partial)) problems.push(`unknown theme field ${key}`)
+  if ('id' in layer && !/^[a-z][a-z0-9-]{0,47}$/.test(layer.id ?? '')) problems.push('id must be a short lowercase slug')
+  if ('version' in layer && !/^[\w.-]{1,32}$/.test(layer.version ?? '')) problems.push('version must be a short label')
+  if ('defaultScheme' in layer && !['dark', 'light'].includes(layer.defaultScheme)) problems.push('defaultScheme must be dark or light')
+  if ('schemes' in layer) {
+    if (!layer.schemes || typeof layer.schemes !== 'object' || Array.isArray(layer.schemes)) problems.push('schemes must be an object')
+    else for (const [scheme, value] of Object.entries(layer.schemes)) {
+      if (!['dark', 'light'].includes(scheme)) { problems.push(`unknown scheme ${scheme}`); continue }
+      if (!value || typeof value !== 'object' || Array.isArray(value)) { problems.push(`${scheme}: must be an object`); continue }
+      for (const key of Object.keys(value)) if (!SCHEME_FIELDS.includes(key)) problems.push(`${scheme}: unknown field ${key}`)
+      for (const [k, v] of Object.entries(value.vars ?? {})) {
+        if (!Object.hasOwn(TOKEN_TYPES, k)) problems.push(`${scheme}: unknown token ${k}`)
+        else if (typeof v !== 'string' || !TOKEN_TYPES[k](v)) problems.push(`${scheme}: rejected ${k}`)
+      }
+      for (const [k, v] of Object.entries(value.graph ?? {})) {
+        if (k === 'zones') { if (!Array.isArray(v) || v.length < 4 || v.length > 16 || !v.every(z => typeof z === 'string' && HEX.test(z))) problems.push(`${scheme}: graph.zones needs 4–16 #rrggbb colours`) }
+        else if (!GRAPH.includes(k)) problems.push(`${scheme}: unknown graph key ${k}`)
+        else if (typeof v !== 'string' || !HEX.test(v)) problems.push(`${scheme}: graph.${k} must be #rrggbb`)
+      }
+    }
+  }
+  return problems
+}
+
+export function validateTheme(theme) {
+  const problems = []
+  if (theme?.schema !== 'atelier.graph-workspace-theme@v1') problems.push('schema must be atelier.graph-workspace-theme@v1')
+  problems.push(...layerProblems(theme, { partial: false }))
+  if (!['dark', 'light'].includes(theme?.defaultScheme)) problems.push('defaultScheme must be dark or light')
+  for (const scheme of ['dark', 'light']) {
+    const s = theme?.schemes?.[scheme]
+    if (!s) { problems.push(`missing ${scheme} scheme`); continue }
+    for (const k of Object.keys(TOKEN_TYPES)) if (!(k in (s.vars ?? {}))) problems.push(`${scheme}: missing ${k}`)
+    for (const k of GRAPH) if (!(k in (s.graph ?? {}))) problems.push(`${scheme}: missing graph.${k}`)
+    if (!Array.isArray(s.graph?.zones)) problems.push(`${scheme}: missing graph.zones`)
+  }
+  if (problems.length) return [...new Set(problems)]
+  for (const scheme of ['dark', 'light']) {
+    const { vars, graph } = theme.schemes[scheme]
+    if (vars['--canvas'].toLowerCase() !== graph.canvas.toLowerCase()) problems.push(`${scheme}: --canvas and graph.canvas must be the same colour`)
+    for (const [fg, bg, min] of TEXT_PAIRS) if (contrastRatio(vars[fg], vars[bg]) < min) problems.push(`${scheme}: ${fg} on ${bg} is below ${min}:1`)
+    for (const backdrop of GLASS_BACKDROPS) {
+      const glass = composite(vars['--surface-glass'], vars[backdrop])
+      for (const [fg, min] of GLASS_TEXT) if (contrastRatio(vars[fg], glass) < min) problems.push(`${scheme}: ${fg} on --surface-glass over ${backdrop} is below ${min}:1`)
+    }
+    if (contrastRatio(graph.label, graph.canvas) < 7) problems.push(`${scheme}: label contrast on the canvas is below 7:1`)
+    if (Math.min(...graph.zones.map(z => contrastRatio(z, graph.canvas))) < 3) problems.push(`${scheme}: a zone colour is below 3:1 on the canvas (zone names are large text)`)
+  }
+  return problems
+}
+
+/** Override a base theme by layer (coach, then owner). Each layer is validated before it is applied. */
+export function composeTheme(base = DEFAULT_THEME, ...layers) {
+  const baseProblems = validateTheme(base)
+  if (baseProblems.length) throw new TypeError('Base theme refused: ' + baseProblems.join('; '))
+  const out = structuredClone(base)
+  layers.filter(Boolean).forEach((layer, index) => {
+    const problems = layerProblems(layer, { partial: true })
+    if (problems.length) throw new TypeError(`Theme layer ${index + 1} refused: ${problems.join('; ')}`)
+    if (layer.id) out.id = layer.id
+    if (layer.version) out.version = layer.version
+    if (layer.defaultScheme) out.defaultScheme = layer.defaultScheme
+    for (const scheme of ['dark', 'light']) {
+      const s = layer.schemes?.[scheme]
+      if (!s) continue
+      Object.assign(out.schemes[scheme].vars, s.vars ?? {})
+      Object.assign(out.schemes[scheme].graph, s.graph ?? {})
+    }
+  })
+  const problems = validateTheme(out)
+  if (problems.length) throw new TypeError('Theme refused: ' + problems.join('; '))
+  return out
+}
+
+export function contrastRatio(a, b) {
+  const lum = h => { const n = parseInt(h.slice(1, 7), 16); return [n >> 16, (n >> 8) & 255, n & 255].map(v => { v /= 255; return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4 }).reduce((s, v, i) => s + v * [0.2126, 0.7152, 0.0722][i], 0) }
+  const [x, y] = [lum(a), lum(b)].sort((p, q) => q - p)
+  return (x + 0.05) / (y + 0.05)
+}

package/src/knowledge/ontology-guide.mjs

@@ -0,0 +1,152 @@
+import { createHash } from 'node:crypto'
+import { isDeepStrictEqual } from 'node:util'
+import { validateKnowledgePlan as validatePlan } from './plan.mjs'
+import { knowledgeQuestionContext as contextForQuestion } from './workspace.mjs'
+
+const sha256 = bytes => createHash('sha256').update(bytes).digest('hex')
+const filled = value => typeof value === 'string' && value.trim().length > 0
+const clone = value => structuredClone(value)
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value)
+
+// A draft adapter for the existing local workspace. It owns no source store,
+// accepted concept identity, access decision, semantic verdict or apply path.
+export function createOntologyGuide() {
+  function bind(workspace, questionId) {
+    const errors = validatePlan(workspace.plan)
+    if (errors.length) throw new Error(`invalid current plan: ${errors.join('; ')}`)
+    const question = workspace.plan.questions.find(q => q.id === questionId)
+    if (!question) throw new Error('unknown knowledge question')
+    const context = contextForQuestion(workspace, questionId)
+    if (context.schema !== 'atelier-knowledge-context@v1' || context.planSha256 !== workspace.sha256)
+      throw new Error('context is not bound to the current plan')
+    return { question, context }
+  }
+
+  function prompts(workspace, questionId, entry = 'corpus') {
+    const { question } = bind(workspace, questionId)
+    if (!['corpus', 'blank'].includes(entry)) throw new Error('unknown entry route')
+    return [
+      { id: 'decision', view: 'onboard', field: 'concept', question: 'What decision will this help?', hint: question.work },
+      { id: 'concept', view: 'model', field: 'concept', question: 'What is the thing you are naming?', hint: 'Choose an existing concept by identity; propose a definition only where it leaves a concrete gap.' },
+      { id: 'identity', view: 'model', field: 'identity', question: 'How would you recognize the same thing next week?', hint: 'Give a stable identifying observation or key, and an example. A similar name or alias alone does not establish identity.' },
+      { id: 'counterexample', view: 'model', field: 'identity', question: 'What close example should stay separate?', hint: 'Explain the difference and name any existing concept with which it could be confused.' },
+      { id: 'evidence', view: 'deepen', field: 'test', question: 'Which source supports it?', hint: entry === 'blank' ? 'Write a permitted observation or interview note, or keep the answer unknown. A synthetic practice note stays labelled synthetic.' : 'Choose a permitted source already read by the current context; inspect the exact passage and qualifications.' },
+      { id: 'relation', view: 'model', field: 'relation', question: 'What does this relationship mean in each direction?', hint: 'Describe the forward claim and how to read it from the other endpoint. The reverse reading creates no inverse assertion.' },
+      { id: 'change', view: 'apply', field: 'test', question: 'What would change your mind?', hint: 'Give a disconfirming observation, unresolved evidence and next test; return to Learn after the outcome is observed.' },
+    ]
+  }
+
+  function inspect(workspace, questionId, draft) {
+    const { question, context } = bind(workspace, questionId)
+    const diagnostics = []
+    const add = (code, field, next) => diagnostics.push({ code, field, next })
+    if (!object(draft)) return { status: 'needs-guidance', diagnostics: [{ code: 'draft-required', field: 'draft', next: 'Start a structured draft from the current question and workspace.' }], evidence: [], contextStatus: context.status }
+    if (draft.snapshot !== workspace.snapshot || draft.basePlanSha256 !== workspace.sha256)
+      add('changed-source', 'snapshot', 'Refresh the workspace, inspect changed sources and rebind a new draft; retain this one as historical.')
+    if (!['corpus', 'blank'].includes(draft.entry)) add('entry-required', 'entry', 'Choose an existing corpus or a blank workspace.')
+    if (!filled(draft.decision)) add('decision-required', 'decision', 'Name the decision this question could change.')
+    const proposedPlan = draft.proposedPlan ?? workspace.plan
+    const planErrors = validatePlan(proposedPlan)
+    for (const error of planErrors) add('invalid-proposed-plan', 'proposedPlan', error)
+    if (planErrors.length) return { status: 'needs-guidance', diagnostics, evidence: [], contextStatus: context.status }
+    const proposedQuestion = proposedPlan.questions.find(q => q.id === question.id)
+    if (!proposedQuestion) add('question-removed', 'proposedPlan', 'Retain the current question or propose its retirement separately with the source owner.')
+    const concepts = proposedPlan.concepts
+    const selected = draft.concepts ?? []
+    if (!Array.isArray(selected) || !selected.length) add('concept-required', 'concepts', 'Choose the smallest existing concept set needed by this question.')
+    const seen = new Set()
+    for (const choice of Array.isArray(selected) ? selected : []) {
+      if (!object(choice)) { add('invalid-concept-choice', 'concepts', 'Choose a concept by its exact plan identity.'); continue }
+      const concept = concepts.find(c => c.id === choice.id)
+      if (!concept) { add('unknown-concept', 'concepts', 'Select an exact concept ID; a name or alias is not an identity mapping.'); continue }
+      if (seen.has(choice.id)) add('duplicate-concept', 'concepts', 'Keep one selection per concept identity.')
+      seen.add(choice.id)
+      for (const field of ['example', 'counterexample', 'identityBasis']) {
+        if (!filled(choice[field])) add(`${field}-required`, `concepts.${choice.id}`, `Give a concrete ${field} for ${choice.id}; review its definition and identity rule.`)
+      }
+      if (filled(choice.example) && choice.example.trim() === choice.counterexample?.trim())
+        add('indistinguishable-example', `concepts.${choice.id}`, 'Use a near miss that the stated identity rule actually keeps separate.')
+      const collisions = concepts.filter(c => c.id !== concept.id && (c.definition.trim().toLowerCase() === concept.definition.trim().toLowerCase() || c.identityRule.trim().toLowerCase() === concept.identityRule.trim().toLowerCase()))
+      for (const other of collisions) {
+        if (!Array.isArray(choice.distinctFrom) || !choice.distinctFrom.some(x => object(x) && x.id === other.id && filled(x.reason)))
+          add('ambiguous-identity', `concepts.${choice.id}`, `Explain how ${choice.id} differs from ${other.id}, or send an explicit mapping proposal for source-owner review. Do not merge them by name.`)
+      }
+      if (!proposedQuestion?.concepts.includes(choice.id)) add('orphan-concept', `concepts.${choice.id}`, 'Link the concept to the current question or remove it from this draft.')
+    }
+    for (const id of proposedQuestion?.concepts ?? []) {
+      if (!seen.has(id)) add('untested-concept', 'concepts', `Inspect the definition, identity and near miss for ${id}.`)
+    }
+    for (const id of proposedQuestion?.relations ?? []) {
+      const relation = proposedPlan.relations.find(r => r.id === id)
+      const reading = Array.isArray(draft.relations) ? draft.relations.find(r => object(r) && r.id === id) : null
+      if (!reading || !filled(reading.forward) || !filled(reading.reverse))
+        add('directed-meaning-required', 'relations', `Explain ${relation.from} → ${relation.to} (${relation.predicate}) and its reverse reading; neither wording proves an accepted edge.`)
+    }
+    const evidence = []
+    if (!Array.isArray(draft.evidence)) add('evidence-list-required', 'evidence', 'Select exact passages, or retain an empty list for an honest unknown.')
+    for (const pin of Array.isArray(draft.evidence) ? draft.evidence : []) {
+      if (!object(pin)) { add('invalid-evidence-pin', 'evidence', 'Choose a current source digest and exact passage.'); continue }
+      const matches = context.sources.filter(s => s.id === pin.id)
+      if (matches.length !== 1) { add('unavailable-or-ambiguous-source', 'evidence', 'Select one unambiguous source from the current permitted context; inspect omissions separately.'); continue }
+      const source = matches[0]
+      if (pin.sha256 !== source.sha256) { add('stale-evidence', 'evidence', 'Read the changed source and propose new pins explicitly; keep the old pin in history.'); continue }
+      const lines = source.text.split('\n')
+      if (source.text.endsWith('\n')) lines.pop()
+      if (!Number.isSafeInteger(pin.start) || !Number.isSafeInteger(pin.end) || pin.start < 1 || pin.end < pin.start || pin.end > lines.length) {
+        add('invalid-passage', 'evidence', 'Choose a complete existing line range in the selected source.'); continue
+      }
+      const passage = lines.slice(pin.start - 1, pin.end).join('\n')
+      if (!filled(pin.quote) || pin.quote !== passage) { add('changed-passage', 'evidence', 'Copy the exact current passage, including its qualifications.'); continue }
+      evidence.push({ id: source.id, repo: source.repo, path: source.path, sha256: source.sha256, start: pin.start, end: pin.end, quote: passage })
+    }
+    if (!['supported', 'abstain'].includes(draft.answer?.status) || !filled(draft.answer?.text))
+      add('answer-required', 'answer', 'Write a source-supported proposed answer or an explicit abstention.')
+    if (draft.answer?.status === 'supported' && !evidence.length)
+      add('unsupported-answer', 'answer', 'Narrow the claim to an inspected source, or abstain and name the evidence needed.')
+    if (draft.answer?.certainty !== 'qualified' || !filled(draft.answer?.limits))
+      add('unsupported-certainty', 'answer', 'State scope, uncertainty, contradictions and alternative explanations. A retrieved passage alone does not establish certainty.')
+    if (!filled(draft.wouldChangeMind)) add('disconfirmation-required', 'wouldChangeMind', 'Name an observation that could disconfirm the answer, or the next evidence needed to resolve the unknown.')
+    return {
+      status: diagnostics.length ? 'needs-guidance' : 'ready-for-human-review', diagnostics, evidence,
+      contextStatus: context.status, coverage: clone(context.coverage), omissions: clone(context.omissions),
+      abstention: draft.answer?.status === 'abstain' ? context.coverage.omitted ? 'unverified-omissions' : 'proposed' : null,
+      assurance: 'Draft completeness and source binding only. The reviewer judges support, identity, meaning and the decision.',
+    }
+  }
+
+  function prepareReview(workspace, questionId, draft, { basePlanText, planRef = 'knowledge-plan.json' }) {
+    const result = inspect(workspace, questionId, draft)
+    if (result.diagnostics.length) return { ok: false, ...result }
+    if (sha256(Buffer.from(basePlanText, 'utf8')) !== workspace.sha256 || !isDeepStrictEqual(JSON.parse(basePlanText.replace(/^\uFEFF/, '')), workspace.plan))
+      throw new Error('raw plan bytes differ from the bound source')
+    if (!filled(planRef) || planRef.length > 500 || planRef.includes('\\') || planRef.split('/').some(p => !p || p.startsWith('.')) || planRef.startsWith('/'))
+      throw new Error('visible workspace-relative plan reference required')
+    const next = draft.proposedPlan ?? workspace.plan
+    const proposedText = isDeepStrictEqual(next, workspace.plan) ? basePlanText : `${JSON.stringify(next, null, 2)}\n`
+    const changes = Object.keys(next).filter(key => !isDeepStrictEqual(workspace.plan[key], next[key])).sort()
+      .map(key => ({ path: `/${key}`, before: clone(workspace.plan[key]), after: clone(next[key]) }))
+    const payload = {
+      kind: 'ontology-guidance-draft', basePlanSha256: workspace.sha256, snapshot: workspace.snapshot, questionId,
+      sourceEditsApplied: false, canonicalAdmission: false, reviewRequired: true,
+      beforeText: basePlanText, proposedText, changes, evidence: result.evidence,
+      retrieval: { status: result.contextStatus, coverage: result.coverage, omissions: result.omissions, abstention: result.abstention },
+      guidance: { entry: draft.entry, decision: draft.decision, concepts: draft.concepts, relations: draft.relations ?? [], answer: draft.answer, wouldChangeMind: draft.wouldChangeMind },
+      coauthor: { flow: 'model', fields: {
+        concept: JSON.stringify({ decision: draft.decision, concepts: draft.concepts }),
+        identity: JSON.stringify(draft.concepts.map(({ id, identityBasis, example, counterexample, distinctFrom }) => ({ id, identityBasis, example, counterexample, distinctFrom: distinctFrom ?? [] }))),
+        relation: JSON.stringify(draft.relations ?? []),
+        test: JSON.stringify({ evidence: result.evidence, answer: draft.answer, wouldChangeMind: draft.wouldChangeMind }),
+      } },
+    }
+    // Existing copy-only store bounds each JSON/text payload at 50,000 chars.
+    // Refuse rather than silently truncate the reviewable source or draft.
+    const diff = JSON.stringify(changes, null, 2)
+    if (JSON.stringify(payload).length > 49000 || diff.length > 49000) throw new Error('review draft exceeds the copy-only store bound; narrow the change')
+    return { ok: true, status: 'proposed', sourceEditsApplied: false,
+      body: { path: planRef, action: 'copy.repoPath', intent: 'Review a source-bound knowledge-plan proposal',
+        capability: 'proposal.copy-only', directWrite: false, applyEndpoint: null,
+        diff, proposal: payload },
+    }
+  }
+  return { prompts, inspect, prepareReview }
+}

package/src/knowledge-health/proof/installed-check.mjs

@@ -33,7 +33,7 @@ await scenario('public-quickstart',async()=>{
   return {init,graph:shellBin(['graph'],workspace),project:shellBin(['project'],workspace),scope:'Exact macOS public quickstart command sequence, supported baseline only'};
 });
 await scenario('installed-document-references',async()=>{
-  const references=['README.md','docs/knowledge-graph.md','docs/coauthor-session.md'];
+  const references=['README.md','docs/reference/knowledge-graph.md','docs/reference/coauthor-session.md'];
   const documents=references.map(relativePath=>{const file=fs.realpathSync(path.join(packageRoot,relativePath));assert.ok(file.startsWith(fs.realpathSync(packageRoot)+path.sep));const bytes=fs.readFileSync(file);return {relativePath,bytes:bytes.length,sha256:digest(bytes)};});
   for(const subpath of ['./graph','./project','./coauthor']){assert.ok(pkg.exports[subpath]);await import(pkg.name+'/'+subpath.slice(2));}
   return {documents,apiReferences:['@mnstry/atelier/graph','@mnstry/atelier/project','@mnstry/atelier/coauthor'],scope:'Public quickstart references resolve in the actual installed package'};
@@ -72,7 +72,7 @@ await scenario('installed-public-graph-project-baseline',async()=>{
   assert.ok(Array.isArray(graph.nodes));assert.ok(Array.isArray(graph.edges));assert.ok(Array.isArray(graph.errors));assert.equal(graph.errors.length,0);
   return {init,graphCommand,projectCommand,graph,agentCIOutput:'Actual machine-readable canonical graph; structural evidence only, no model/provider or semantic acceptance.'};
 });
-const docs=[];for(const candidate of ['README.md','docs/knowledge.md','docs/coauthor.md','docs/coauthor-session.md','docs/upgrade.md','docs/graph.md','docs/knowledge-graph.md','docs/release-engineering.md']){const full=path.join(packageRoot,candidate);if(fs.existsSync(full)){const b=fs.readFileSync(full);docs.push({path:candidate,sha256:digest(b),bytes:b.length});}}
+const docs=[];for(const candidate of ['README.md','docs/guides/knowledge-workspace.md','docs/reference/coauthor-session.md','docs/guides/upgrade.md','docs/reference/knowledge-graph.md','docs/maintainers/release-engineering.md']){const full=path.join(packageRoot,candidate);if(fs.existsSync(full)){const b=fs.readFileSync(full);docs.push({path:candidate,sha256:digest(b),bytes:b.length});}}
 for(const id of ['assessment-to-guided-authoring','full-native-finding-reference','preview-owning-source-correction-readback-reassessment','keyboard-focus-undo','native-withdrawal-recovery','participant-usefulness'])gaps.push({id,owner:id==='participant-usefulness'?'Facilitator/participant':'Foundation and existing AW Integration/Journey',action:'Receive exact public Dev Day installed entry/bindings and native allocation; inherited native or fixture proof cannot satisfy installed or human evidence.'});
 const bindings=profile.deliveryBindings;
 if(bindings){