altitude-design 0.2.0 → 0.3.0

package/dist/guidance/patterns/settings.json

@@ -0,0 +1,78 @@
+{
+  "schemaVersion": 1,
+  "id": "settings",
+  "version": 1,
+  "title": "Settings",
+  "intents": [
+    "settings",
+    "preferences",
+    "workspace settings",
+    "account settings",
+    "danger zone"
+  ],
+  "purpose": "Change how a workspace or account behaves, deciding per section whether changes apply now or save together.",
+  "useWhen": [
+    "A page of settings mixes standalone preferences, records saved together and destructive actions."
+  ],
+  "avoidWhen": [
+    "A single record form with no standalone preferences; use the edit-record contract alone."
+  ],
+  "alternatives": [
+    "Use the edit-record contract for one record's form, and the consequential-action contract for a single destructive action outside settings."
+  ],
+  "requiredInputs": [
+    "current settings and who may change each section",
+    "a save adapter per record saved together",
+    "a write adapter per apply-now preference",
+    "consequence and execute adapter per destructive action"
+  ],
+  "states": [
+    "loading",
+    "ready",
+    "apply-pending",
+    "apply-committed",
+    "apply-failed",
+    "draft-dirty",
+    "draft-submitting",
+    "draft-failed",
+    "read-only",
+    "concurrent-change"
+  ],
+  "transitions": [
+    "ready → apply-pending when an apply-now control changes",
+    "apply-pending → apply-committed on acknowledgement, or apply-failed with the control restored",
+    "ready → draft-dirty when a field saved together changes",
+    "draft-dirty → draft-submitting on save, or ready on discard",
+    "draft-submitting → ready on success, or draft-failed with the draft kept"
+  ],
+  "rules": [
+    "ALT-SETTINGS-001",
+    "ALT-EDIT-001",
+    "ALT-EDIT-002",
+    "ALT-ACTION-001",
+    "ALT-STATUS-001",
+    "ALT-VISUAL-003"
+  ],
+  "sources": [
+    "nng-toggle",
+    "govuk-validation",
+    "altitude-elevation",
+    "task-review"
+  ],
+  "authority": "contextual-pattern",
+  "applicability": "Settings pages that combine standalone preferences, records saved together and destructive actions.",
+  "exceptions": [
+    "Require only states supported by the application; a page with only one mode needs only that mode's states."
+  ],
+  "maturity": "provisional",
+  "evidenceStatus": "engineering-fixtures; human-effectiveness-unmeasured",
+  "document": "patterns/settings.md",
+  "implementation": "project/components/src/settings.tsx",
+  "examples": [
+    "build/fixtures/patterns/settings.jsx"
+  ],
+  "verification": [
+    "build/checks/settings-pattern.mjs",
+    "build/checks/pattern-types.mjs"
+  ]
+}

package/dist/guidance/patterns/settings.md

@@ -0,0 +1,32 @@
+# Settings
+
+Help someone review and change how a workspace, account or product behaves: sections of settings, some applied the moment they change and some saved together, with destructive actions kept apart. It composes [Edit record](edit-record.md) for fields saved together and [Consequential action](consequential-action.md) for the danger zone; this contract says which applies where. Use a route per settings area; don't put settings in a dialog.
+
+## Inputs and ownership
+
+Supply the current settings, which person may change which section, a save adapter for each record saved together, a write adapter for each apply-now preference, and the consequence and execute adapter for each destructive action. The application owns authorization (read-only sections must also be rejected by the server), persistence, concurrency between two people editing the same settings, and navigation guards. A switch that appears saved is not saved until its write is acknowledged.
+
+## States and transitions
+
+Decide each section's mode before building it, and never mix the two inside one section:
+
+- **Apply now**: a preference that stands alone (a notification, a theme, a toggle for one feature). `Switch`, `RadioGroup` or `Select` changes it immediately and the row reports the write through `SettingsRow status`: pending hovers (after the grace period, so fast writes never flicker), committed lands with "Saved", failed drops into a trench with the reason, and the control returns to its last saved value.
+- **Save together**: fields that form one record (workspace name and URL, a billing address). They join one draft, follow the edit-record states (editing, invalid, submitting, saved, failed) and are saved or discarded once with `SaveBar`, which appears when the draft has changed. Navigation away with unsaved changes asks before discarding.
+
+Other applicable states: loading (each section's card stays up with its body as an imprint), read-only (`SettingsSection readOnlyReason` disables the rows and says why in words, for example "Only workspace owners can change billing details"), save failure (the draft is kept and the bar says what failed), and a concurrent change by someone else (show the newer value and who changed it; don't overwrite it silently).
+
+## Layout, keyboard, focus and announcements
+
+Lay out sections as `SettingsSection` cards, each with a heading that names its region, navigated by in-page links, `Tabs` or a sidebar for long pages. Each setting is a `SettingsRow`: label and description on the start side, the control on the end side, stacked on narrow screens; the row's label names the control and its description describes it. Put destructive actions last, in a section titled "Danger zone" (`tone="critical"`): the same height as every other section, a critical rim, and each action named by its outcome ("Delete workspace") with its consequence in words. Delete, transfer and similar actions follow the consequential-action contract: a typed confirmation in a stationary `Dialog`, or a `HoldButton`, and success reported only after the service confirms it.
+
+Tab follows the visual order; every control is reachable and named. An invalid save moves focus to the error summary; an apply-now write announces its result politely beside the control without moving focus. Long labels and values wrap; at 320px rows stack. Verify forced colors (the critical rim stays visible), reduced motion (a pending row holds still, raised), zoom and RTL.
+
+## Recovery and working implementation
+
+A failed apply-now write puts the control back and says why; trying again is the same change. A failed save keeps the draft; retry resubmits it. A failed destructive action says nothing was removed and offers to try again. The working example in `build/fixtures/patterns/settings.jsx` (shipped as `references/build/fixtures/patterns/settings.jsx`) composes general fields saved together, apply-now notification switches, a read-only billing section and a typed-confirmation delete, with a demo service that can fail. It is also the Storybook preview "Patterns/SettingsPattern". [Metadata](settings.json) names the runtime and verification sources.
+
+## Rules, verification and evidence
+
+`ALT-SETTINGS-001` covers the mode decision and the danger zone; `ALT-EDIT-001` and `ALT-EDIT-002` cover the draft saved together; `ALT-ACTION-001` covers destructive actions; `ALT-STATUS-001` covers announcements; `ALT-VISUAL-003` covers what must not rise. `build/checks/settings-pattern.mjs` checks the example in a browser: named regions, labelled rows, the apply-now write's three states, the read-only reason, the danger zone's height and rim, the SaveBar draft and the typed confirmation. See [rules](../rules.json) for source authority and applicability. Whether people understand which settings apply immediately still needs evaluation with representative users.
+
+See [running examples and verification](../principles.md#run-the-examples-and-verification) for the installed example command, repository test command, and the limits of shipped test-reference snapshots.

package/dist/guidance/patterns/sync.json

@@ -0,0 +1,77 @@
+{
+  "schemaVersion": 1,
+  "id": "sync",
+  "version": 1,
+  "title": "Sync",
+  "intents": [
+    "autosave",
+    "offline",
+    "sync",
+    "conflict",
+    "session timeout",
+    "session expiry",
+    "local-first",
+    "optimistic"
+  ],
+  "purpose": "Say truthfully what has reached the server, through offline queues, conflicts and expiring sessions.",
+  "useWhen": [
+    "Work is saved continuously or optimistically, may go offline, or may be edited by two people at once."
+  ],
+  "avoidWhen": [
+    "Forms saved once with an explicit button; use the edit-record contract."
+  ],
+  "alternatives": [
+    "Use the edit-record contract for explicit saves, and SyncIndicator alone for a single autosaving document."
+  ],
+  "requiredInputs": [
+    "each change's write and acknowledgement",
+    "the connection state",
+    "the queue of unacknowledged changes",
+    "conflict detection with both versions and the other author",
+    "session expiry time and a way to extend it"
+  ],
+  "states": [
+    "saved",
+    "pending",
+    "failed",
+    "offline-queued",
+    "replaying",
+    "conflict",
+    "resolved",
+    "session-expiring",
+    "session-expired"
+  ],
+  "transitions": [
+    "saved → pending on a change → saved when acknowledged, or failed with Retry",
+    "pending → offline-queued when the connection drops",
+    "offline-queued → replaying → saved when it returns",
+    "pending → conflict when another version arrived → resolved by keep mine, theirs or both",
+    "session-expiring → saved on Stay signed in, or session-expired keeping the draft"
+  ],
+  "rules": [
+    "ALT-SYNC-001",
+    "ALT-EDIT-001",
+    "ALT-STATUS-001"
+  ],
+  "sources": [
+    "altitude-elevation",
+    "task-review",
+    "wcag22"
+  ],
+  "authority": "contextual-pattern",
+  "applicability": "Autosaving, optimistic or local-first work, and sessions that expire.",
+  "exceptions": [
+    "Require only states supported by the application; online-only apps skip the offline states but still never claim unacknowledged work is saved."
+  ],
+  "maturity": "provisional",
+  "evidenceStatus": "engineering-fixtures; human-effectiveness-unmeasured",
+  "document": "patterns/sync.md",
+  "implementation": "build/fixtures/patterns/sync.jsx",
+  "examples": [
+    "build/fixtures/patterns/sync.jsx"
+  ],
+  "verification": [
+    "build/checks/sync-pattern.mjs",
+    "build/checks/pattern-types.mjs"
+  ]
+}

package/dist/guidance/patterns/sync.md

@@ -0,0 +1,31 @@
+# Sync
+
+Help someone trust what has reached the server: autosaving editors, optimistic lists and local-first apps that survive going offline, resolve the rare edit conflict without dropping anyone's work, and keep a draft through an expired session. It extends the persistence rules of [Edit record](edit-record.md) to work saved continuously.
+
+## Inputs and ownership
+
+Supply each change's write and its acknowledgement, the connection state, the queue of changes not yet acknowledged, conflict detection with both versions and who made the other one, and the session's expiry time with a way to extend it. The application owns the merge strategy (CRDT, operational transform, last write wins or a three-way merge), the durability of the local queue across reloads, idempotent replays, and re-authentication. A timer or a local write doesn't prove persistence; only the server's acknowledgement does.
+
+## States and transitions
+
+**Per item**: a change is `status="pending"` from the moment it's made until the server acknowledges it (it hovers, after the grace period so fast writes never flicker), then committed (it lands), or failed (it drops into a trench with Retry). **Globally**, `SyncIndicator` ties the items together: it counts the queue, says "Saved" only when the queue is empty and acknowledged (and announces "Saved" at most every few seconds), and offers Retry when sending fails.
+
+**Offline**: queued changes stay pending and say "Waiting to sync"; the indicator says "Offline" with the count; nothing claims to be saved. Coming back online replays the queue in order; each item lands as it's acknowledged.
+
+**Conflicts**: resolve automatically wherever the merge strategy can. For the rest, show both versions in place, as `EditRegion` does: the conflict asks for action (raised, level 1, "Changed by Jane Park while you were editing"); the other person's version wears their `presence-*` colour and name, because it's their hold on the record. Offer "Keep mine", "Keep theirs" and, where meaningful, "Keep both". Never drop an edit silently: say where the other version went ("Yours is in the history"). The indicator counts unresolved conflicts and takes you to them.
+
+**Session expiry**: before the session ends, a stationary `Dialog` that Escape doesn't dismiss says the time left in words ("Your session ends in 2 minutes") with "Stay signed in" as primary. Any draft is kept locally across re-authentication, and the dialog says so. After expiry, signing in again returns to the same draft.
+
+## Content, keyboard, focus and announcements
+
+Going offline and conflicts are announced immediately; "Saved" is debounced. The indicator's plate is a button when there's something to show (the queue, the conflicts). Resolving a conflict moves focus to the resolved field's heading. Pending items keep their content readable; nothing is disabled just because it's waiting. Verify forced colors (pending items keep a dotted border, failed ones dashed), reduced motion (pending holds still, raised), zoom and RTL.
+
+## Recovery and working implementation
+
+A failed write offers Retry and keeps the change queued. A failed replay after reconnecting leaves the remaining items pending and says how many are waiting. The working example in `build/fixtures/patterns/sync.jsx` (shipped as `references/build/fixtures/patterns/sync.jsx`) composes pending items with a demo server, an offline queue, a conflict with keep mine, keep theirs or keep both, and an expiring session. It is also the Storybook preview "Patterns/SyncPattern". [Metadata](sync.json) names the runtime and verification sources.
+
+## Rules, verification and evidence
+
+`ALT-SYNC-001` covers pending until acknowledged, offline queues and conflicts that never drop work; `ALT-EDIT-001` covers truthful persistence; `ALT-STATUS-001` covers announcements. WCAG 2.2's timing-adjustable criterion applies to session expiry. `build/checks/sync-pattern.mjs` checks the example in a browser. See [rules](../rules.json). Whether people understand conflict choices still needs evaluation with representative users.
+
+See [running examples and verification](../principles.md#run-the-examples-and-verification) for the installed example command, repository test command, and the limits of shipped test-reference snapshots.

package/dist/guidance/principles.md

@@ -0,0 +1,23 @@
+# Scope and ownership
+
+Altitude supplies native/control semantics, keyboard and focus contracts, operation state, and reusable compositions. Applications supply authorization, validation, durable persistence, identity, service concurrency, routing/history, and the truth of content. People validate whether a task and its language fit their context.
+
+Keep the ground as the record. Unsaved input is local editing; pending starts when a write is dispatched. Show committed only after the service confirms the promised outcome. Pair elevation with text, state, icons or borders. Follow the existing Elevation guide, shipped as `visual/Elevation.md` in package guidance; this framework adds no tier.
+
+Rule authority is explicit: normative standards retain their applicability and exceptions; informative implementation patterns and heuristics are contextual; Altitude visual policies govern this library; experimental hypotheses are not established human-performance findings. A rule's diagnostic class is separate from its authority. Deterministic violations can fail checks; application integration obligations need service fixtures; contextual findings need product review.
+
+The machine-readable sources are `patterns/*.json`, `rules.json`, `evidence.json`, and their schemas. Pattern Markdown explains those contracts. Runtime sources and executable fixtures implement them; tests establish only the behavior they exercise. Package builds copy prose and generate indexes, versions, hashes, and reference snapshots. Do not hand-edit `dist/guidance`.
+
+For each supported journey test narrow viewports (320 CSS px with touch; see `project/Mobile.md` and `build/checks/phone.mjs`), long translated content, RTL, zoom, reduced motion and forced colors. Keep controls and status reachable without relying on hover, color or depth. Test with keyboard and relevant assistive technology; record browser/AT versions and remaining gaps. A passing scan is not a conformance claim.
+
+## Run the examples and verification
+
+The package includes runnable example compositions with public imports. In a consumer project with React, React DOM and Altitude installed, add the example bundler as a development dependency (`npm install --save-dev esbuild`), then run:
+
+```sh
+node node_modules/altitude-design/dist/guidance/references/scripts/build-framework-fixture.mjs --out work/altitude-examples
+```
+
+Open the generated `work/altitude-examples/index.html` in a browser. The helper aliases React, React DOM and Altitude to the consuming project's installed copies, avoiding duplicate providers or React instances. Its in-memory service demonstrates delays, rejection, real mutation and recovery; it does not supply production persistence. The same helper in the repository is `node scripts/build-framework-fixture.mjs --out work/altitude-examples`, after `npm run build`.
+
+Files under `references/build/checks/` are version-matched evidence snapshots for inspection, not standalone installed test commands: they depend on repository tooling and fixtures. Maintainers run `node build/checks/pattern-workflows.mjs` in the repository after installing root and build dependencies, with a supported Playwright browser (or the `CHROME` executable environment variable). Consumers should adapt these scenarios into their own test runner using public exports and their actual service/navigation adapters; exercise delayed rejection, retry, retained data, keyboard and the real persistence outcome. `altitude doctor` checks installation and setup only. It does not run those application integration checks.

package/dist/guidance/references/build/checks/agent-action-pattern.mjs

@@ -0,0 +1,57 @@
+// Agent action pattern: steps map to one reading each (planned, running, awaiting approval, done, failed); a reversible
+// step runs without asking and offers Undo; sending email waits for approval as a Proposed card (raised, never hovering),
+// hovers as pending only once approved, and lands with what happened; deleting for good asks in a stationary dialog; a
+// failed step says nothing changed and retries; the changed record carries an AI label naming the approver. Run after a
+// render of every preview (it opens test/p-AgentActionPattern-daylight.html); exits non-zero on a failure.
+import { chromium } from 'playwright-core';
+const browser = await chromium.launch(process.env.CHROME ? { executablePath: process.env.CHROME } : {});
+const T = new URL('../test/', import.meta.url).pathname;
+let pass = 0, fail = 0;
+const expect = (c, m) => { if (c) pass++; else { fail++; console.log('FAIL', m); } };
+const page = await browser.newPage({ viewport: { width: 960, height: 1100 } });
+await page.goto(`file://${T}p-AgentActionPattern-daylight.html`);
+await page.waitForTimeout(300);
+const steps = () => page.evaluate(() => [...document.querySelectorAll('.alt-trace-item')].map((s) => s.dataset.trace));
+const confirm = (n) => page.evaluate((n) => { const c = document.querySelectorAll('.alt-confirm')[n]; return c && { state: c.dataset.state, status: c.dataset.status || '', anim: getComputedStyle(c).animationName, text: c.textContent }; }, n);
+
+expect((await steps()).join() === 'running,planned,planned,planned', `planned steps wait while the first runs (${await steps()})`);
+await page.waitForTimeout(2000);
+expect((await steps()).join() === 'done,done,awaiting-approval,planned', `a reversible step runs without asking (${await steps()})`);
+expect(/4 leads archived\. You can undo this for 30 days\./.test(await page.evaluate(() => document.querySelector('.ag-receipt').textContent)), 'and says what it did, with Undo');
+let c = await confirm(0);
+expect(c.state === 'requested' && c.status === '' && c.anim !== 'alt-hover' && /Theo Marsh, Ines Duarte and Sam Okafor/.test(c.text), `sending email waits as a Proposed card, never hovering (${JSON.stringify({ ...c, text: '' })})`);
+await page.getByRole('button', { name: 'Send 3 emails' }).click();
+await page.waitForTimeout(400);
+c = await confirm(0);
+expect(c.state === 'running' && c.status === 'pending', `approved, it hovers as pending (${c.state}/${c.status})`);
+await page.waitForTimeout(900);
+c = await confirm(0);
+expect(c.state === 'done' && /3 emails sent/.test(c.text), 'then lands with what happened');
+
+await page.getByRole('button', { name: 'Delete list' }).click();
+await page.waitForTimeout(500);
+const dialog = page.getByRole('dialog', { name: 'Delete the “Summer import” list' });
+expect(await dialog.count() === 1 && await page.locator('[data-receded]').count() === 0, 'deleting for good asks in a stationary dialog');
+await dialog.getByRole('button', { name: 'Delete list' }).click();
+await page.waitForTimeout(1300);
+expect((await steps()).join() === 'done,done,done,done', `every step lands (${await steps()})`);
+
+const record = await page.evaluate(() => { const r = document.querySelector('.ag-record'); return r && { label: r.querySelector('.alt-ailabel')?.textContent, text: r.textContent }; });
+expect(record && record.label === 'Drafted with AI' && /approved by Maya Chen/.test(record.text), 'the changed record carries provenance and its approver');
+
+await page.getByRole('button', { name: 'Undo archive' }).click();
+await page.waitForTimeout(200);
+expect(/Archive undone/.test(await page.evaluate(() => document.querySelector('.ag-receipt').textContent)), 'Undo reverses the reversible step');
+
+await page.getByRole('switch', { name: 'Make the next step fail' }).click();
+await page.getByRole('button', { name: 'Run again' }).click();
+await page.waitForTimeout(1100);
+const failed = await page.evaluate(() => { const s = document.querySelector('.alt-trace-item'); return { state: s.dataset.trace, text: s.textContent }; });
+expect(failed.state === 'failed' && /Nothing was changed/.test(failed.text), 'a failed step sinks and says nothing changed');
+await page.getByRole('button', { name: /Retry/ }).first().click();
+await page.waitForTimeout(1900);
+expect((await steps()).slice(0, 2).join() === 'done,done', 'and Retry runs it again');
+
+console.log(`Agent action pattern: ${pass} passed, ${fail} failed`);
+if (fail) process.exitCode = 1;
+await browser.close();

package/dist/guidance/references/build/checks/agent-setup.mjs

@@ -0,0 +1,78 @@
+// Exercises the actual packed-and-installed Node CLI and its two instruction adapters.
+import assert from 'node:assert/strict';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, writeFileSync, rmSync, symlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import { root } from '../../scripts/build-guidance.mjs';
+// npm 11 and earlier print an array from `pack --json`; npm 12 keys the result by package name.
+const firstPacked=result=>Array.isArray(result)?result[0]:Object.values(result)[0];
+const dir=mkdtempSync(resolve(tmpdir(),'altitude-agent-setup-'));
+try {
+  const pack=firstPacked(JSON.parse(execFileSync('npm',['pack','--json','--pack-destination',dir],{cwd:root,encoding:'utf8'})));
+  writeFileSync(resolve(dir,'package.json'),'{"name":"altitude-setup-consumer","private":true,"version":"1.0.0"}\n');
+  execFileSync('npm',['install','--ignore-scripts','--legacy-peer-deps','--no-audit','--no-fund',resolve(dir,pack.filename)],{cwd:dir,stdio:'pipe'});
+  const cli=resolve(dir,'node_modules/altitude-design/dist/cli/altitude.mjs');
+  assert.ok(existsSync(cli));
+  function run(args,ok=true){const r=spawnSync(process.execPath,[cli,...args],{cwd:dir,encoding:'utf8'});assert.equal(r.status,ok?0:1,`${args}: ${r.stdout}\n${r.stderr}`);return JSON.parse(r.stdout);}
+  const version=JSON.parse(readFileSync(resolve(root,'package.json'),'utf8')).version;
+  for(const [client,file]of [['codex','AGENTS.md'],['claude','CLAUDE.md']]) {
+    const p=resolve(dir,file),original='# Existing instructions\r\nKeep this exact text without trailing newline';
+    writeFileSync(p,original);
+    const preview=run(['init','--client',client]);assert.equal(preview.mode,'preview');assert.equal(readFileSync(p,'utf8'),original);
+    assert.ok(preview.changes[0].after.includes(`Altitude framework (${version})`));
+    run(['init','--client',client,'--apply']);const installed=readFileSync(p,'utf8');assert.ok(installed.startsWith(original));
+    const again=run(['init','--client',client,'--apply']);assert.equal(again.changes[0].action,'unchanged');assert.equal(readFileSync(p,'utf8'),installed);
+    assert.ok(run(['doctor','--json']).ok);
+    // Later user additions survive removal byte-for-byte.
+    writeFileSync(p,installed+'\nLater project instructions.');
+    run(['init','--client',client,'--remove']);assert.ok(readFileSync(p,'utf8').includes('altitude:start'));
+    run(['init','--client',client,'--remove','--apply']);assert.equal(readFileSync(p,'utf8'),original+'\nLater project instructions.');
+    rmSync(p);run(['init','--client',client,'--apply']);run(['init','--client',client,'--remove','--apply']);assert.ok(!existsSync(p),'remove newly created file');
+    run(['init','--client',client,'--apply']);writeFileSync(p,readFileSync(p,'utf8').replace('For UI tasks','My changed content'));
+    run(['init','--client',client,'--apply'],false);assert.equal(run(['doctor','--json'],false).ok,false);rmSync(p);
+  }
+  const discovery=run(['patterns','edit settings','--json']);assert.equal(discovery.patterns[0].id,'edit-record');assert.equal(discovery.version,version);
+  assert.equal(run(['patterns','unmatched-gibberish','--json']).patterns.length,0);
+  assert.equal(run(['explain','ALT-EDIT-001','--json']).diagnosticClass,'application-integration');
+  run(['explain','unknown'],false);
+  const report=run(['doctor','--json']);assert.ok(report.findings.some(f=>f.kind==='contextual-review'&&f.status==='unverified'));assert.ok(report.findings.some(f=>f.kind==='application-integration'));
+  // Reject conflicting markers and symlinks without overwriting user-owned instructions.
+  writeFileSync(resolve(dir,'AGENTS.md'),'<!-- altitude:start -->');run(['init','--client','all','--apply'],false);assert.ok(!existsSync(resolve(dir,'CLAUDE.md')));rmSync(resolve(dir,'AGENTS.md'));
+  writeFileSync(resolve(dir,'outside.md'),'Keep');symlinkSync(resolve(dir,'outside.md'),resolve(dir,'AGENTS.md'));run(['init','--client','codex','--apply'],false);assert.equal(readFileSync(resolve(dir,'outside.md'),'utf8'),'Keep');rmSync(resolve(dir,'AGENTS.md'));
+  // Dangling links must not create their destination through writeFileSync.
+  symlinkSync(resolve(dir,'missing-target.md'),resolve(dir,'AGENTS.md'));run(['init','--client','codex','--apply'],false);assert.ok(!existsSync(resolve(dir,'missing-target.md')));rmSync(resolve(dir,'AGENTS.md'));
+  // Codex gives nonempty overrides precedence over AGENTS.md in the same directory.
+  writeFileSync(resolve(dir,'AGENTS.md'),'Ordinary instructions');writeFileSync(resolve(dir,'AGENTS.override.md'),'Active override');
+  const overridden=run(['init','--client','codex','--apply']);assert.ok(overridden.changes[0].path.endsWith('AGENTS.override.md'));
+  assert.equal(readFileSync(resolve(dir,'AGENTS.md'),'utf8'),'Ordinary instructions');assert.ok(run(['doctor','--json']).ok);
+  run(['init','--client','codex','--remove','--apply']);assert.equal(readFileSync(resolve(dir,'AGENTS.override.md'),'utf8'),'Active override');
+  rmSync(resolve(dir,'AGENTS.md'));rmSync(resolve(dir,'AGENTS.override.md'));
+  // Removal finds owned blocks even after the client switches instruction targets.
+  const ordinaryPath=resolve(dir,'AGENTS.md'),overridePath=resolve(dir,'AGENTS.override.md');
+  const ordinary='Original ordinary instructions\r\nNo trailing newline',override='Later override instructions';
+  writeFileSync(ordinaryPath,ordinary);run(['init','--client','codex','--apply']);
+  writeFileSync(overridePath,override);
+  const hiddenPreview=run(['init','--client','codex','--remove']);
+  assert.ok(hiddenPreview.changes.some(change=>change.path.endsWith('/AGENTS.md')&&change.action==='update'));
+  assert.ok(readFileSync(ordinaryPath,'utf8').includes('altitude:start'),'preview keeps inactive owned block');
+  run(['init','--client','codex','--remove','--apply']);
+  assert.equal(readFileSync(ordinaryPath,'utf8'),ordinary);assert.equal(readFileSync(overridePath,'utf8'),override);
+  // A managed block may exist in both files after setup follows a newly added override.
+  rmSync(overridePath);run(['init','--client','codex','--apply']);writeFileSync(overridePath,override);run(['init','--client','codex','--apply']);
+  const bothPreview=run(['init','--client','codex','--remove']);
+  assert.equal(bothPreview.changes.filter(change=>change.action==='update').length,2);
+  const intactOrdinary=readFileSync(ordinaryPath,'utf8'),intactOverride=readFileSync(overridePath,'utf8');
+  writeFileSync(ordinaryPath,intactOrdinary.replace('For UI tasks','User edited managed block'));
+  run(['init','--client','codex','--remove','--apply'],false);
+  assert.equal(readFileSync(overridePath,'utf8'),intactOverride,'invalid inactive block prevents partial removal');
+  writeFileSync(ordinaryPath,intactOrdinary);run(['init','--client','codex','--remove','--apply']);
+  assert.equal(readFileSync(ordinaryPath,'utf8'),ordinary);assert.equal(readFileSync(overridePath,'utf8'),override);
+  assert.ok(run(['init','--client','codex','--remove','--apply']).changes.every(change=>change.action==='unchanged'));
+  rmSync(ordinaryPath);rmSync(overridePath);
+  // Version mismatch and changed source detection are deterministic failures.
+  const indexPath=resolve(dir,'node_modules/altitude-design/dist/guidance/index.json'),originalIndex=readFileSync(indexPath,'utf8');
+  const index=JSON.parse(originalIndex);index.version='0.0.0';writeFileSync(indexPath,JSON.stringify(index));assert.ok(run(['doctor','--json'],false).findings.some(f=>f.observed.includes('0.0.0')));writeFileSync(indexPath,originalIndex);
+  const entry=resolve(dir,'node_modules/altitude-design/dist/guidance/README.md');writeFileSync(entry,'stale');assert.ok(run(['doctor','--json'],false).findings.some(f=>f.observed.includes('README.md')));
+  console.log('agent setup: packed install, Codex + Claude preview/apply/idempotence/removal/preservation/discovery/diagnostics pass');
+} finally {rmSync(dir,{recursive:true,force:true});}

package/dist/guidance/references/build/checks/assistant-conversation-pattern.mjs

@@ -0,0 +1,49 @@
+// Assistant conversation pattern (#285): in its preview, a send shows the person's message and streams the answer on
+// a dashed rule; a double Enter sends once; Stop keeps the partial answer as "Stopped" with Retry; offline and rate
+// limited failures keep the message in the composer and say what happened in words; context full offers a new
+// conversation; reloading mid-answer shows it "Interrupted" with Retry, never complete; the context Meter speaks in
+// words. Run after a render of every preview (it opens test/p-AssistantConversationPattern-daylight.html); exits
+// non-zero on a failure.
+import { chromium } from 'playwright-core';
+const browser = await chromium.launch(process.env.CHROME ? { executablePath: process.env.CHROME } : {});
+const T = new URL('../test/', import.meta.url).pathname;
+let pass = 0, fail = 0;
+const expect = (c, m) => { if (c) pass++; else { fail++; console.log('FAIL', m); } };
+const page = await browser.newPage({ viewport: { width: 960, height: 900 } });
+const errors = []; page.on('pageerror', (e) => errors.push(e.message));
+await page.goto(`file://${T}p-AssistantConversationPattern-daylight.html`); await page.waitForTimeout(400);
+const box = page.locator('.alt-prompt textarea');
+const read = () => page.evaluate(() => ({ user: [...document.querySelectorAll('.alt-msg[data-from="user"]')].map((m) => m.textContent), answer: document.querySelector('.alt-msg[data-from="assistant"]'), alert: document.querySelector('.alt-alert')?.textContent ?? null, draft: document.querySelector('.alt-prompt textarea').value }))
+  .then((r) => r);
+const answer = () => page.evaluate(() => { const m = document.querySelector('.alt-msg[data-from="assistant"]'); return m ? { stream: m.dataset.stream, text: m.querySelector('.alt-msg-content')?.textContent ?? '', caption: m.querySelector('.alt-msg-caption')?.textContent ?? '', retry: !!m.querySelector('button') } : null; });
+await box.fill('What are the open risks?'); await box.press('Enter'); await box.press('Enter'); await page.waitForTimeout(600);
+let a = await answer();
+expect((await read()).user.length === 1 && a?.stream === 'streaming', `a send streams the answer, and a double Enter sends once (${JSON.stringify(a)})`);
+await page.click('.alt-prompt button[aria-label*="Stop" i]'); await page.waitForTimeout(150);
+a = await answer();
+expect(a.stream === 'stopped' && a.text.length > 0 && /Stopped/.test(a.caption) && a.retry, `Stop keeps the partial answer as "Stopped" with Retry (${JSON.stringify(a)})`);
+await page.click('.alt-msg[data-from="assistant"] button:has-text("Retry")'); await page.waitForTimeout(3200);
+a = await answer();
+expect(a.stream === 'complete' && a.text.includes('decision from legal by Friday'), `Retry completes the answer (${a.stream})`);
+// Offline: the message stays in the composer, said in words.
+await page.click('[role="radio"]:has-text("Offline"), button:has-text("Offline")'); await page.waitForTimeout(100);
+await box.fill('Summarise it'); await box.press('Enter'); await page.waitForTimeout(700);
+let r = await read();
+expect(/We can't reach the assistant/.test(r.alert ?? '') && r.draft === 'Summarise it', `offline keeps the message and says so (${JSON.stringify({ alert: r.alert, draft: r.draft })})`);
+await page.click('button:has-text("Rate limited")'); await page.waitForTimeout(100);
+await box.press('Enter'); await page.waitForTimeout(700);
+r = await read();
+expect(/You've reached this hour's limit\. Try again at/.test(r.alert ?? '') && r.draft === 'Summarise it', `a rate limit says when (${r.alert})`);
+await page.click('button:has-text("Context full")'); await page.waitForTimeout(100);
+await box.press('Enter'); await page.waitForTimeout(700);
+r = await read();
+expect(/too long to continue/.test(r.alert ?? '') && await page.locator('.alt-alert button:has-text("Start a new conversation")').count() === 1, 'context full offers a new conversation');
+const meter = await page.evaluate(() => document.querySelector('.ac-context [role="meter"], .ac-context[role="meter"]')?.getAttribute('aria-valuetext') ?? document.querySelector('.ac-context')?.textContent);
+expect(/% of context used/.test(meter ?? ''), `the context meter speaks in words (${meter})`);
+await page.click('button:has-text("Reload mid-answer")'); await page.waitForTimeout(300);
+a = await answer();
+expect(a.stream === 'error' && /Interrupted/.test(await page.evaluate(() => document.querySelector('.ac-note')?.textContent ?? '')) && a.retry, `after a reload, an unfinished answer is interrupted with Retry (${JSON.stringify(a)})`);
+expect(!errors.length, `no page errors (${errors.join('; ')})`);
+console.log(`Assistant conversation pattern: ${pass} passed, ${fail} failed`);
+if (fail) process.exitCode = 1;
+await browser.close();

package/dist/guidance/references/build/checks/audit-log-pattern.mjs

@@ -0,0 +1,63 @@
+// Audit log pattern: entries are the record, flush rows that read as one sentence and never lift; an entry expands to
+// show what changed; the server pages the log, holding the rows while the next page loads; filtering narrows it and
+// returns to the first page; exporting runs as a task (Progress with its percentage), then a toast offers the download
+// and the export is logged; a record's activity is a Timeline whose times have their exact value. Run after a render of
+// every preview (it opens test/p-AuditLogPattern-daylight.html); exits non-zero on a failure.
+import { chromium } from 'playwright-core';
+const browser = await chromium.launch(process.env.CHROME ? { executablePath: process.env.CHROME } : {});
+const T = new URL('../test/', import.meta.url).pathname;
+let pass = 0, fail = 0;
+const expect = (c, m) => { if (c) pass++; else { fail++; console.log('FAIL', m); } };
+const page = await browser.newPage({ viewport: { width: 960, height: 1000 } });
+await page.goto(`file://${T}p-AuditLogPattern-daylight.html`);
+await page.waitForTimeout(500);
+const table = page.getByRole('table', { name: 'Audit log events' });
+const events = () => table.locator('tbody tr:not(.alt-dt-detail-row) td:nth-child(2)').allTextContents();
+
+let first = await events();
+expect(first.length === 5 && /^Maya Chen changed Ines Duarte’s role from Member to Admin$/.test(first[0]), `each entry reads as one sentence (${first[0]})`);
+await table.locator('tbody tr').nth(1).hover();
+await page.waitForTimeout(250);
+const flush = await table.locator('tbody tr').nth(1).evaluate((r) => ({ t: getComputedStyle(r).transform, button: r.querySelector('[role="button"], a') !== null }));
+expect(flush.t === 'none' && !flush.button, `entries are flush and don’t lift (${JSON.stringify(flush)})`);
+
+await table.getByRole('button', { name: /Maya Chen changed Ines Duarte’s role/ }).first().click();
+await page.waitForTimeout(400);
+const diff = await page.evaluate(() => document.querySelector('.alt-diff')?.textContent || '');
+expect(/Member/.test(diff) && /Admin/.test(diff), 'an entry expands to show what changed');
+
+await page.getByRole('button', { name: 'Next page' }).click();
+await page.waitForTimeout(150);
+expect(await page.evaluate(() => !!document.querySelector('[aria-busy="true"], [data-loading]')), 'the next page loads with the rows held');
+await page.waitForTimeout(500);
+const second = await events();
+expect(second.length === 5 && second[0] !== first[0], 'the server pages the log');
+
+await page.getByRole('button', { name: 'Export CSV' }).click();
+await page.waitForTimeout(600);
+const job = await page.evaluate(() => ({ bar: !!document.querySelector('.al-export [role="progressbar"]'), words: document.querySelector('.al-export [role="status"]')?.textContent }));
+expect(job.bar && /^Preparing export, \d+%$/.test(job.words || ''), `exporting is a task with its percentage (${JSON.stringify(job)})`);
+await page.waitForTimeout(1400);
+expect(await page.getByRole('button', { name: 'Download' }).count() === 1, 'a toast offers the download');
+await page.getByRole('button', { name: 'Page 1' }).click().catch(() => {});
+await page.waitForTimeout(600);
+expect((await events())[0] === 'Maya Chen exported 22 audit log events as CSV', 'and the export is itself logged');
+
+await page.getByRole('button', { name: 'Next page' }).click();
+await page.waitForTimeout(600);
+expect(await page.locator('[aria-current="page"]').first().textContent() === '2', 'on page 2 before filtering');
+await page.getByRole('button', { name: 'Add filter' }).click();
+await page.getByRole('option', { name: 'Actor' }).click();
+await page.getByRole('dialog', { name: 'Actor is' }).waitFor();
+await page.getByRole('option', { name: 'Theo Marsh' }).click();
+await page.waitForTimeout(300);
+const theo = await events();
+expect(theo.length > 0 && theo.every((e) => e.startsWith('Theo Marsh')), `filtering narrows the log (${theo.length} rows)`);
+expect(await page.locator('[aria-current="page"]').first().textContent() === '1', 'and returns to the first page');
+
+const times = await page.evaluate(() => [...document.querySelectorAll('.al-record time')].map((t) => t.getAttribute('datetime')));
+expect(times.length === 3 && times.every(Boolean), 'record activity is a Timeline whose times carry their exact value');
+
+console.log(`Audit log pattern: ${pass} passed, ${fail} failed`);
+if (fail) process.exitCode = 1;
+await browser.close();

package/dist/guidance/references/build/checks/auth-pattern.mjs

@@ -0,0 +1,67 @@
+// Auth pattern: the form is on a raised Card, never a dialog; every field has its autocomplete token; an empty submit
+// focuses the error summary; a wrong password never says whether the account exists, clears only the password and keeps
+// the email; repeated failures are rate limited with the wait in words; an emailed link says "if that address has an
+// account", counts down before a resend in words, and keeps the email when you go back; two-factor isn't submitted for
+// you, a wrong code says so, and the right one signs in; sign-up shows the password rules and asks for a new password.
+// Run after a render of every preview (it opens test/p-AuthPattern-daylight.html); exits non-zero on a failure.
+import { chromium } from 'playwright-core';
+const browser = await chromium.launch(process.env.CHROME ? { executablePath: process.env.CHROME } : {});
+const T = new URL('../test/', import.meta.url).pathname;
+let pass = 0, fail = 0;
+const expect = (c, m) => { if (c) pass++; else { fail++; console.log('FAIL', m); } };
+const page = await browser.newPage({ viewport: { width: 960, height: 800 } });
+await page.goto(`file://${T}p-AuthPattern-daylight.html`);
+await page.waitForTimeout(400);
+const focused = () => page.evaluate(() => document.activeElement.textContent || document.activeElement.className);
+const text = () => page.evaluate(() => document.querySelector('.au-card').textContent);
+const signIn = async (email, password) => {
+  await page.fill('#au-email', email); await page.fill('#au-password', password);
+  await page.getByRole('button', { name: 'Sign in', exact: true }).click(); await page.waitForTimeout(1000);
+};
+
+expect(await page.locator('[role="dialog"]').count() === 0 && await page.locator('.au-card.alt-card').count() === 1, 'sign-in is on a raised card, not a dialog');
+expect(await page.getAttribute('#au-email', 'autocomplete') === 'username' && await page.getAttribute('#au-password', 'autocomplete') === 'current-password', 'fields carry autocomplete tokens');
+await page.getByRole('button', { name: 'Sign in', exact: true }).click();
+await page.waitForTimeout(300);
+expect(await page.evaluate(() => !!document.activeElement.closest('.alt-error-summary')), 'an empty submit focuses the error summary');
+await signIn('maya@acme.dev', 'wrong');
+let t = await text();
+expect(/That email and password don’t match/.test(t) && !/no account|not found|doesn’t exist/i.test(t), 'a wrong password never says whether the account exists');
+expect(await page.inputValue('#au-email') === 'maya@acme.dev' && await page.inputValue('#au-password') === '', 'it keeps the email and clears only the password');
+await signIn('maya@acme.dev', 'altitude');
+expect(await focused() === 'Enter your code', 'the right password moves to two-factor, focusing its heading');
+expect(await page.getAttribute('#au-code', 'autocomplete') === 'one-time-code', 'the code field asks for a one-time code');
+const verify = page.getByRole('button', { name: 'Verify', exact: true });
+await page.locator('#au-code').pressSequentially('000000');
+await page.waitForTimeout(300);
+expect(await page.getByRole('heading', { name: 'You’re signed in' }).count() === 0 && !(await verify.isDisabled()), 'a complete code isn’t submitted for you');
+await verify.click();
+await page.waitForTimeout(1000);
+expect(/That code didn’t work/.test(await text()), 'a wrong code says so');
+await page.locator('#au-code').pressSequentially('123456');
+await verify.click();
+await page.waitForTimeout(1000);
+expect(await page.getByRole('heading', { name: 'You’re signed in' }).count() === 1, 'the right code signs in');
+await page.getByRole('button', { name: 'Sign out' }).click();
+await page.waitForTimeout(200);
+
+for (let i = 0; i < 3; i++) await signIn('maya@acme.dev', 'nope');
+await signIn('maya@acme.dev', 'nope');
+expect(/Too many attempts\. Wait 5 minutes/.test(await text()), 'repeated failures are rate limited, with the wait in words');
+
+await page.getByRole('button', { name: 'Email me a sign-in link' }).click();
+await page.waitForTimeout(1000);
+t = await text();
+expect(await focused() === 'Check your email' && /If maya@acme\.dev has an Acme account, we’ve sent a sign-in link/.test(t), 'the link screen never says whether the account exists');
+expect(/You can resend the email in (30|29) seconds\./.test(t), 'a resend waits, with the time in words');
+await page.getByRole('button', { name: 'Use a different email address' }).click();
+await page.waitForTimeout(200);
+expect(await page.inputValue('#au-email') === 'maya@acme.dev', 'going back keeps the email');
+
+await page.getByRole('button', { name: 'Create an account' }).click();
+await page.waitForTimeout(200);
+expect(await page.getAttribute('#au-password', 'autocomplete') === 'new-password' && /At least 12 characters/.test(await text()), 'sign-up asks for a new password and shows its rules');
+
+console.log(`Auth pattern: ${pass} passed, ${fail} failed`);
+if (fail) process.exitCode = 1;
+await browser.close();