system-atlas

1// Single source of truth for one atlas. Copy to <atlas home>/data.mjs and edit.2// Build: bun <atlas home>/build.mjs  → writes ../SYSTEM.md and ../atlas.html3// The atlas home is docs/<system>/atlas/ in repos that commit design docs, or a4// git-ignored scratch directory in repos that only commit ADRs + CONTEXT.md.5 6export const META = {7  title: 'Example Agent',                 // "<title> Atlas" in the tab; "<title> — System Definition" in SYSTEM.md8  artifactUrl: '',                        // fill after first publish; keep it stable across rebuilds9  sourcePath: 'docs/example/atlas/data.mjs',10  buildCmd: 'bun docs/example/atlas/build.mjs',11  stats: [{ k: 'System', v: 'example · v0' }, { k: 'Model roles', v: '2' }], // static top-strip stats; chapter/shown/questions are added automatically12  intro: `_**This file is the living source of truth for the design.** The interactive atlas is built from the same data._`,13  onePara: `One paragraph a newcomer can read in 30 seconds: what the system is, what the loop is, what is not built yet.`,14  costModel: ['Optional: cost assumptions and a table. Leave [] to omit.'],15  deepDive: '',                           // optional: summary + links to research/16  platformGives: 'What the runtime/framework provides for free.',17  weOwn: 'What we have to build ourselves.',18  filesystem: `apps/example/\n  agent/…`,19};20 21// Decisions render as the SYSTEM.md table and as chapter-10's "Decisions locked" list.22export const DECISIONS = [23  { axis: 'Runtime', decision: 'What and why, in one line', adr: '[0001](./adr/0001-slug.md)' },24];25 26export const GROUPS = [27  { id: 'loop', title: 'The main loop' },28  { id: 'mem', title: 'Memory' },29  { id: 'sup', title: 'Supporting the loop' },30  { id: 'off', title: 'Not yet switched on' },31];32 33// Structure = one isometric box. Fields:34//   id/code: 1–2 letters shown on the box · name · short (≤14 chars, canvas label) · group35//   gx,gy: grid position · w,d: footprint · h: height px · kind: box|tall|store|cards|slab|screen|gate|job36//   ghost: true → dashed "designed for, not built"37//   one: one-sentence summary (shown first) · what: plain description · how: implementation (may use <code>, <mark>)38//   steps: [[name, desc], …] → the "go inside" view39//   cond: questions — string (open) | {q, r} (resolved, r = answer + date) | {q, to} (routed to a named next step)40export const NODES = [41  { id: 'U', code: 'U', name: 'Web chat', short: 'WEB CHAT', group: 'loop', gx: 1.5, gy: 7.5, w: 2, d: 2, h: 44, kind: 'screen',42    one: 'The page where you talk to the agent.',43    what: 'Plain-language description for a non-engineer.',44    how: 'Implementation with <code>identifiers</code> and <mark>key phrases</mark>.',45    steps: [['Open', 'Create or continue a session.'], ['Stream', 'Render deltas.']],46    cond: ['Where does the page live?', { q: 'Auth scheme?', r: 'Reuse existing session JWT (2026-01-01).' }] },47  { id: 'I', code: 'I', name: 'Root agent', short: 'AGENT', group: 'loop', gx: 10, gy: 2.5, w: 3, d: 3, h: 64, kind: 'tall',48    one: 'The brain — one durable conversation per person.', what: '…', how: '…', steps: [['turn.started', '…'], ['Model call', '…'], ['Tools', '…'], ['Stream', '…']], cond: [] },49  { id: 'M', code: 'M', name: 'Memory', short: 'MEMORY', group: 'mem', gx: 6.5, gy: 9.5, w: 3, d: 3, h: 24, kind: 'store',50    one: 'What the agent knows about you.', what: '…', how: '…', steps: [['Write', '…'], ['Read', '…']], cond: [{ q: 'Vendor?', to: 'Memory deep dive' }] },51  { id: 'P', code: 'P', name: 'Proactive', short: 'PROACTIVE', group: 'off', ghost: true, gx: 12.5, gy: -1, w: 2, d: 2, h: 34,52    one: 'Later: the agent reaches out on a schedule.', what: '…', how: '…', steps: [['Tick', '…']], cond: ['Notification etiquette.'] },53];54 55// Flows for the final "whole system" chapter. Hop = [from, to, label, payload, bend('xy'|'yx')]56export const FLOWS = [57  { id: 'turn', name: 'One turn', hops: [58    ['U', 'I', 'user message', { message: 'can you move my 3pm?' }, 'yx'],59    ['I', 'M', 'recall', { query: 'move my 3pm', k: 12 }, 'xy'],60    ['M', 'I', 'memories', { hits: 2 }, 'xy'],61    ['I', 'U', 'message.appended', { delta: 'Sure —' }, 'yx'],62  ] },63];64 65// Chapters = progressive disclosure. Each reveals a few structures and runs ONE small flow among revealed ones.66// The last chapter has reveal: [] and flow: null → shows everything with a flow picker.67export const CH = [68  { id: 'you', title: 'You and the agent', reveal: ['U', 'I'],69    lede: `Strip everything away and this is the system: you type, it answers.`,70    story: `<p>Two or three sentences. <mark>Highlight</mark> the one idea this chapter adds.</p>`,71    flow: [['U', 'I', 'user message', { message: '…' }], ['I', 'U', 'reply', { delta: '…' }]] },72  { id: 'know', title: 'Knowing you', reveal: ['M'],73    lede: `Before answering, the agent recalls what it knows about you.`,74    story: `<p>…</p>`,75    flow: [['U', 'I', 'user message', { message: '…' }], ['I', 'M', 'recall', { k: 12 }], ['M', 'I', 'memories', { hits: 2 }], ['I', 'U', 'reply', { delta: '…' }]] },76  { id: 'later', title: 'Later', reveal: ['P'],77    lede: `Designed for, not switched on.`, story: `<p>…</p>`,78    flow: [['P', 'I', 'scheduled turn', { kind: 'morning_brief' }]] },79  { id: 'all', title: 'The whole system', reveal: [],80    lede: `Everything at once, for free exploration.`,81    story: `<p>Choose which flow runs (bottom left). Hover anything; click to pin; → goes inside. The <mark>Open questions</mark> tab lists every question by ID.</p>`,82    flow: null },83];84 85// "How it's built" tab with nothing selected (HTML).86export const HOW_HTML = `<div class="eyebrow">Example · v0</div><h1 class="t">How it's built</h1><div class="sub">the shape and what sits around it</div>87<h3 class="sec">Filesystem</h3><pre>apps/example/…</pre>`;88