altitude-design 0.2.1 → 0.3.1

package/dist/guidance/manifest.json

@@ -0,0 +1,92 @@
+{
+  "schemaVersion": 1,
+  "version": "0.3.1",
+  "files": {
+    "agent-setup.md": "5b300079b150d6416b6dd00280a42110559c85d50b84a13ac6cf9e0329be9a21",
+    "app-skeleton.md": "bc70896a86f4c1dbd3467620562eec62ccf99a9356ff72a7eab8621f492554d9",
+    "evidence.json": "ac99cfcca61219a4a25c75adf84c89f6c3e47b3713a8fb8209180c824d565b1b",
+    "index.json": "8a840db2e00c75b87fe6aca5e066cc0af1d59305f0789a9f845b77e5330113f4",
+    "llms.txt": "c58ed1e25f99aed16c1003777230df4af94cdeabb39db73bc0122dd0885671b0",
+    "pattern.schema.json": "abcb37bd5de4a74f27ac079e587e5d288b23e491569a73971f1a31131a37d309",
+    "patterns/agent-action.json": "532915c25183d1a6093d9e14b929f3e49d29e400b116ef0612d933d70d49b09a",
+    "patterns/agent-action.md": "a11e9d98a84d8a0fae755bae3e618e7daa2608f1f853cfe88e2e58ee74cc01e7",
+    "patterns/assistant-conversation.json": "63d7321b87e90f0bbeaf75f12dcb6ffd5cee40dccd769b2b2062932f0b40f226",
+    "patterns/assistant-conversation.md": "41fa199f874b1849b3afe19d5c6cc498ddfd20c7cae198b4a2a1feac6747849d",
+    "patterns/async-collection.json": "b004d1edd6d9b5f03f4db5092bcd896914d66c8575da9efde47c9654ca3b83e6",
+    "patterns/async-collection.md": "4bcb8612436af5b730999d5a31e1f25eaad2ded4862c7639136a2f83b11cac4a",
+    "patterns/audit-log.json": "661471f05d07fae8ae0b920c5e1e674906e98829a3e6eed4f01b39c8d053d58a",
+    "patterns/audit-log.md": "2d245c2537fd874e09a44004c11a57a6a6b9504330df86263842a84afb0541af",
+    "patterns/auth.json": "c9439ecf8196750d887d7a99b135de89d926b365acfecc9a6f7b66d2bbb8c679",
+    "patterns/auth.md": "aba431dd58284485f6ae8472056342f72c643eeb7d77edd1eb92336f5bf1d5da",
+    "patterns/billing.json": "8a72249c29ebb5b5eefbd98294e3fcfe45b5ddcebf4f7f7e8aa409388bc882e5",
+    "patterns/billing.md": "9b9c639d868a0735d8be88d030fdec1db1f43e2bedb9dcb014e39ca79c1fe5bf",
+    "patterns/consequential-action.json": "e5a61a89753efed1408cf0b1a5826b607b19c3fbbabf7d3f0b1b2586df24b506",
+    "patterns/consequential-action.md": "f4efb5000325416d1b44c7f2ea906420cf8c1fd7b330e7754fac0ba5025c1fc4",
+    "patterns/developer-settings.json": "54443991d65410c20b2285caa2265b1662d60188b084969cad3dc6fe6a681fa1",
+    "patterns/developer-settings.md": "22eb20642649ad872a53771fd56bfd8051d18bb8cdf4756ccb6581c886db319b",
+    "patterns/edit-record.json": "7d4249bbbd1c0c09afc8e4f3d1e6e688d2404db29e17db44cd5445427c570537",
+    "patterns/edit-record.md": "a999de3810380ac20ae4045e5cb2dc3fae9d4d654f55a8d7da2fea4dfc3e746f",
+    "patterns/import.json": "d1a47a24a15bee87d177b173327d0ba4f9791b7345e3d33f3c97aa960816761f",
+    "patterns/import.md": "c44373f9639707b7b8e4ededdf3c3426dc3a75cd5e2b62577fdac4853c3cbaa1",
+    "patterns/members.json": "f2567081cd05f65c64f92890a79afd64864992ec66903755a20a7c1d4411702a",
+    "patterns/members.md": "b2a42c5f470ce8fd6d96d9630b5c6be452716053f9085cbc6ce87372087d5a43",
+    "patterns/onboarding.json": "e831f904db32cb01a48f11cba9ef77704d986e0adb8d53a139a54bd4124704ba",
+    "patterns/onboarding.md": "6948c0d7bc99334af1132d41f28b6ea9399b7491115160d5e664280131bad4c4",
+    "patterns/review-submit.json": "79b15332acc57fb48b0b99ba98a195d5f913e7875293b0acb6aa42f5425a982b",
+    "patterns/review-submit.md": "6a9d1886a48cad9e82da5c8b04d179425ec4fa925105d6f9ee50d4605dab3d87",
+    "patterns/screen-layout.json": "199ca3f20a7af1983bc7211406bbf87e43328e3d57c48d29524191de86507782",
+    "patterns/screen-layout.md": "7a6dd92249e1b8acbb5ab16afb15f5d3aa25e46fedf8d59eb40a4d892b22310e",
+    "patterns/settings.json": "9ae72e95cb61b5f41a22053d408c2a634c18746661fa1c2e41e98a5ef2b6e08f",
+    "patterns/settings.md": "dea76175e2b1b4347414c3716f0ff61fd584bf10b8fd45548449694c86027bbf",
+    "patterns/sync.json": "e127992aaba5ad797a0c27ff0f7903619511e9a02379b6932c66084d3690660e",
+    "patterns/sync.md": "9b6c6928fe19c6f28b88bd092997c0c0645aedddf02a25327a1c7c60969e3729",
+    "principles.md": "1c57c684c4b0029012a79d6a38b26b8821abf75852b14db2b18b7e7f6d364b32",
+    "README.md": "2b37096e2c13fbff4578c53ebbc38329f49a4050b9d1757125a42ab778785125",
+    "references/build/checks/agent-action-pattern.mjs": "166f5765839d2f60e7bd84cda2a834100306b3d5a80b4b45b79f2c2d33fce1e7",
+    "references/build/checks/agent-setup.mjs": "670c0786bdfc5739fceae14bd234a2a2c9c6672fbe6fd4e72b15f85647f4a1dd",
+    "references/build/checks/assistant-conversation-pattern.mjs": "f289529c2ee594ad28269337da762f00ae1143f8bb217cf36b1596a5a5363618",
+    "references/build/checks/audit-log-pattern.mjs": "af7770e7bf08caa9e1875161e4fc39509e4f0a84e612cdf79cb547cb6046af74",
+    "references/build/checks/auth-pattern.mjs": "7406cfa7c29c3bb3ac9075c8af079c6f7fd0bc296e81fef1c62667ec245c660b",
+    "references/build/checks/billing-pattern.mjs": "75e1809769420bc4c714ba0ddb1298489af7152603018d980182e6131182edc2",
+    "references/build/checks/developer-settings-pattern.mjs": "946cf163177db4aa4dfa30dac754d0229bc4b703ef1eac17a17dc35d19e2f093",
+    "references/build/checks/guidance.mjs": "65bca118879294288c14f296db3ba225ed953fb295e4010487fb7bae16c1bf51",
+    "references/build/checks/import-pattern.mjs": "6b98c0533bb0d8584ba0d677e579a0fdfdbdb5bd4663f261ecbdfb39181c45f6",
+    "references/build/checks/members-pattern.mjs": "bd550c7315dd6298efc1d524364dcfb505884a2e32bb9ed7c4995b53cc61a2a5",
+    "references/build/checks/onboarding-pattern.mjs": "721ef5a202365d3597985bff9ade68bf3312c309687e846ce9a1669dcc00cae2",
+    "references/build/checks/pattern-types.mjs": "858431d8b622af096b8a41f35df1789343f96aa07433e8a98185b8740a1ded19",
+    "references/build/checks/pattern-workflows.mjs": "72e708399c0141c2b62ca94ab96382eb0e000df9d5a54045be814e261d9a9bdc",
+    "references/build/checks/primary-scope.mjs": "b70634020cd8480ca97e7ee6350fdc9231684888009a6bd8d9ed216505aa2349",
+    "references/build/checks/render-tells.mjs": "93eae3f005f2a93654e111627a343440a7d87fa4b11c7c9403283b627fc1834c",
+    "references/build/checks/screen-layout-pattern.mjs": "c744bb32b29da50e2a1d852c1005b42addc0e1d7a98297e168f8ce7d51e4ad93",
+    "references/build/checks/semantics.mjs": "2ee7689b0472dba2e782ff19304e01018ca470b252fe7137e82bb36a3e0042c0",
+    "references/build/checks/settings-pattern.mjs": "77a8d8e431e5e25e4f4af5c92e7be1e664dbab5aac9f587b7819bd9c196b3907",
+    "references/build/checks/sync-pattern.mjs": "2cf9f1ac96be6c48948dea0ffab0fda0a909b5ff19e3e3f9835b6d8bcdd7fbef",
+    "references/build/checks/tells-lint.mjs": "f254fa9166f65a085d78cecf7ca66145151cd8b7868c732c25c44bbec2c2deac",
+    "references/build/fixtures/pattern-workflows.tsx": "6781938d83aa85f48c63fff98f9eb5b45fcb5531b6a49f902ec9d497f6e65265",
+    "references/build/fixtures/patterns/agent-action.jsx": "96d07566b1eb498be16436b9ce1d8b4148c0841cb73b3d421c8ab240bd115559",
+    "references/build/fixtures/patterns/app-skeleton.jsx": "d2d8e7d5373ee4d65c2e0ecc69451f35d9dfd4bed9f04cf66405cbe9c9478825",
+    "references/build/fixtures/patterns/assistant-conversation.jsx": "fda1f5ce21a8eb2f0f5da730cad9eb0ab65c91c9e46d69a88f9f6715434eda8a",
+    "references/build/fixtures/patterns/audit-log.jsx": "ec1183de4c94c0309824b4187c082f7ea76d50a09953224e4164b4fc5fa70780",
+    "references/build/fixtures/patterns/auth.jsx": "1b41c43b734deb75acd8bfd34dae445e627381884abd23512e37bfb1d644eabe",
+    "references/build/fixtures/patterns/billing.jsx": "8f56ab9e6d09d73f1ae9ad5d690ff20372f9279d23010d6db7ef5e2a79d0100a",
+    "references/build/fixtures/patterns/developer-settings.jsx": "7803d792f516b5a1ee823436c505802954865720f7c8dbae0742a1adc0b2d490",
+    "references/build/fixtures/patterns/import.jsx": "3b4148a99bf90a477ae01a0905cae75200bc53427ea197cc2bcda0a9c2469ca2",
+    "references/build/fixtures/patterns/members.jsx": "2b25e2f0734a273b6d7366c746573a906b90d613164b7003fe6fd3e426496286",
+    "references/build/fixtures/patterns/onboarding.jsx": "3ae1325880efa862b84b5d9bcc0691bf6029e1f1ac031bb99adb6c0527c498a9",
+    "references/build/fixtures/patterns/screen-layout-decision.jsx": "409d5ce48ddef3ca5de3427155e901f06d142938474894e9eabbc167c910c47a",
+    "references/build/fixtures/patterns/screen-layout-editor.jsx": "a93c41d7590fd98fae48403c49e4d4e793b4e92e4cf5b8cc66e30ed0aa55ba68",
+    "references/build/fixtures/patterns/screen-layout-report.jsx": "5de2691104456175ef51d2e1d11c85b4075341457e8acd3d5495615c2fbeb0a9",
+    "references/build/fixtures/patterns/settings.jsx": "92b9b472351f9a8a3479ab04f7890b1b3cbc356cf81926ff0c280f1bdbf0c435",
+    "references/build/fixtures/patterns/sync.jsx": "8474f762f7c63c4bd99fd337b080df1a788b4b92b2ced7fac5aaa1379b1a1eaf",
+    "references/project/components/src/pattern-async-collection.tsx": "9e4df2265d1de6f269278eb4a42d8d63b3ef74a881a455eb17102be477ecbf4d",
+    "references/project/components/src/pattern-consequential-action.tsx": "ffe49b7a9fa978e9177c6f3d839d311bdd3da913a6eeedc241800b10fc3287f7",
+    "references/project/components/src/pattern-edit-record.tsx": "7e83cfdfdb85f6927667dae58f7392c1738dd05ff7a53c75209a875779c9db9d",
+    "references/project/components/src/pattern-review-submit.tsx": "b452f90e7a160774678aa886626aa48dea535211bc367a17d628ac84bed5ee58",
+    "references/project/components/src/settings.tsx": "957a04e37936746f2b6b4086d8e2f866ce71f7fb9dded8ba81fff56840206e01",
+    "references/scripts/build-framework-fixture.mjs": "1b4a2d7ece0459d2c4df2ec067d8d3b9d00110f2af1cef3be6042ab8f9ea90c9",
+    "rules.json": "607eed605aa834ab2e6557b44df0899a3851b684060566c73fbe1639df4575ae",
+    "visual/Elevation.md": "100532c631803e9a97018b9da5ffff60acf7d80559f9f162ba9e371f5510371f",
+    "visual/Fundamentals.md": "65120fd170ff8ea9f50b1498bfedc8c45dbe1a616bfccc32664213e5404d3a32",
+    "visual/Research.md": "ca9931eb15547b86cff525126cba2a09e6e0751ad2739a60f453c83ed8d84216"
+  }
+}

package/dist/guidance/pattern.schema.json

@@ -0,0 +1,181 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Altitude task pattern",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "id",
+    "version",
+    "title",
+    "purpose",
+    "authority",
+    "applicability",
+    "maturity",
+    "evidenceStatus",
+    "document",
+    "implementation",
+    "intents",
+    "useWhen",
+    "avoidWhen",
+    "alternatives",
+    "requiredInputs",
+    "states",
+    "transitions",
+    "rules",
+    "sources",
+    "exceptions",
+    "examples",
+    "verification"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "integer",
+      "const": 1
+    },
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[a-z]+(?:-[a-z]+)*$"
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "purpose": {
+      "type": "string",
+      "minLength": 1
+    },
+    "authority": {
+      "type": "string",
+      "minLength": 1,
+      "enum": [
+        "normative-standard",
+        "contextual-pattern",
+        "heuristic",
+        "altitude-policy",
+        "experimental-hypothesis"
+      ]
+    },
+    "applicability": {
+      "type": "string",
+      "minLength": 1
+    },
+    "maturity": {
+      "type": "string",
+      "minLength": 1
+    },
+    "evidenceStatus": {
+      "type": "string",
+      "minLength": 1
+    },
+    "document": {
+      "type": "string",
+      "minLength": 1
+    },
+    "implementation": {
+      "type": "string",
+      "minLength": 1
+    },
+    "intents": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "useWhen": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "avoidWhen": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "alternatives": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "requiredInputs": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "states": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "transitions": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "rules": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "sources": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "exceptions": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "examples": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "verification": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    }
+  }
+}

package/dist/guidance/patterns/agent-action.json

@@ -0,0 +1,77 @@
+{
+  "schemaVersion": 1,
+  "id": "agent-action",
+  "version": 1,
+  "title": "Agent action",
+  "intents": [
+    "agent",
+    "ai assistant",
+    "assistant",
+    "tool approval",
+    "human in the loop",
+    "copilot",
+    "ai action"
+  ],
+  "purpose": "Let an agent propose, wait for approval, run, recover and leave provenance, with each state drawn as one reading.",
+  "useWhen": [
+    "An embedded agent takes actions (sends, edits, deletes, runs code) on someone's behalf."
+  ],
+  "avoidWhen": [
+    "An assistant that only answers in text; use Conversation and PromptInput."
+  ],
+  "alternatives": [
+    "Use Conversation for answers only, and the consequential-action contract for a person's own destructive actions."
+  ],
+  "requiredInputs": [
+    "the plan as steps with tool calls",
+    "each step's runtime state",
+    "each step's consequence class",
+    "approve, reject and retry handlers",
+    "provenance of every change"
+  ],
+  "states": [
+    "planned",
+    "running",
+    "approval-requested",
+    "approved",
+    "executing",
+    "done",
+    "failed",
+    "rejected",
+    "undone"
+  ],
+  "transitions": [
+    "planned → running → done for a reversible step, with Undo",
+    "running → approval-requested for an external or irreversible step",
+    "approval-requested → approved → executing → done or failed",
+    "approval-requested → rejected",
+    "failed → running on Retry"
+  ],
+  "rules": [
+    "ALT-AGENT-001",
+    "ALT-ACTION-001",
+    "ALT-STATUS-001",
+    "ALT-VISUAL-003"
+  ],
+  "sources": [
+    "altitude-elevation",
+    "task-review",
+    "wcag22"
+  ],
+  "authority": "contextual-pattern",
+  "applicability": "Embedded agents that take actions on someone's behalf.",
+  "exceptions": [
+    "Require only states the agent runtime reports; what runs without approval is the application's decision."
+  ],
+  "maturity": "provisional",
+  "evidenceStatus": "engineering-fixtures; human-effectiveness-unmeasured",
+  "document": "patterns/agent-action.md",
+  "implementation": "build/fixtures/patterns/agent-action.jsx",
+  "examples": [
+    "build/fixtures/patterns/agent-action.jsx"
+  ],
+  "verification": [
+    "build/checks/agent-action-pattern.mjs",
+    "build/checks/pattern-types.mjs"
+  ]
+}

package/dist/guidance/patterns/agent-action.md

@@ -0,0 +1,39 @@
+# Agent action
+
+Help someone delegate work to an agent that acts: it plans, shows its steps, waits for approval where the consequence warrants it, runs what's approved, reports back, recovers from failure, and leaves a record of who did what. It composes `Trace`, `Confirmation`, `AILabel` and, for the request, `PromptInput` and `Conversation`; destructive steps follow [Consequential action](consequential-action.md).
+
+## Inputs and ownership
+
+Supply the agent's plan as steps with their tool calls, each step's state from the agent runtime, each step's consequence class (reversible with a real undo, external, or irreversible), approve and reject handlers that reach the runtime, a retry handler, and the provenance of every change (agent, model, approver, time). The application owns the agent runtime, tool permissions, what runs without approval, idempotent retries, the undo that makes a step reversible, and the audit trail. The interface never decides on its own that an action is safe.
+
+## States and transitions
+
+Map each tool-call state to exactly one reading:
+
+| Runtime state | Reading |
+|---|---|
+| planned | imprint: the step is there but nothing happened |
+| running | the current step, raised on its wall, with its tool call behind a lid |
+| approval-requested | **Proposed**: a raised `Confirmation` that asks, **never pending** |
+| approved / executing | **pending**: it hovers until the result arrives |
+| done | lands and settles, with what happened in words |
+| failed | sinks into a trench, says what (and that nothing changed, when true), with Retry |
+| rejected | flush, "Rejected", and the step says what didn't happen |
+
+**Escalate by consequence.** A reversible step with a real undo may run without approval; it reports its result with Undo, as a `RemovalReceipt` does ("4 leads archived. You can undo this for 30 days."). An external or irreversible step (send, pay, delete, publish) requires a `Confirmation` that states the consequence concretely ("Theo Marsh, Ines Duarte and Sam Okafor will get an email…") with an approve button named by the outcome ("Send 3 emails"). The most severe use `escalate="hold"` or `escalate="dialog"` (a stationary Dialog).
+
+**Never claim success the runtime hasn't confirmed**, and never let a streamed answer look like the record before it completes (`Message` streams on a dashed rule). **Provenance**: everything an agent changed carries an `AILabel` on the result ("Drafted with AI" once a person approved it) and an activity entry naming the agent and the approver.
+
+## Content, keyboard, focus and announcements
+
+Steps are an ordered list; the current step is `aria-current`. Step changes are announced politely and throttled; approvals and failures immediately; never token by token. Approve and reject are ordinary buttons reachable by keyboard; a hold has a keyboard equivalent; focus stays where the person is unless a dialog opens. Tool-call input and output stay behind a disclosure, readable as text. Verify forced colors (Proposed, pending and failed stay distinguishable without colour), reduced motion (pending holds still, raised; no glow or gradient anywhere), zoom and RTL.
+
+## Recovery and working implementation
+
+A failed step offers Retry and says whether anything changed. A rejected step leaves the rest of the plan to the runtime: it may continue, re-plan or stop, and the trace says which. An undone step says so. The working example in `build/fixtures/patterns/agent-action.jsx` (shipped as `references/build/fixtures/patterns/agent-action.jsx`) composes a run with a search, a reversible archive with Undo, an email that waits for approval, a permanent delete behind a stationary dialog, a failure with Retry, and a changed record with provenance. It is also the Storybook preview "Patterns/AgentActionPattern". [Metadata](agent-action.json) names the runtime and verification sources.
+
+## Rules, verification and evidence
+
+`ALT-AGENT-001` covers the state mapping, escalation by consequence and provenance; `ALT-ACTION-001` covers consequential steps; `ALT-STATUS-001` covers announcements; `ALT-VISUAL-003` covers what must not rise (a proposal is not pending). `build/checks/agent-action-pattern.mjs` checks the example in a browser. See [rules](../rules.json) and Elevation.md's Proposed and Streaming readings. How much approval people want for which actions 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/assistant-conversation.json

@@ -0,0 +1,77 @@
+{
+  "schemaVersion": 1,
+  "id": "assistant-conversation",
+  "version": 1,
+  "title": "Assistant conversation",
+  "intents": [
+    "chat",
+    "assistant",
+    "copilot",
+    "chatbot",
+    "agent conversation",
+    "ai chat"
+  ],
+  "purpose": "Send, stream, stop, retry and recover in a conversation with an assistant, without losing the person's words or claiming an answer is complete before it is.",
+  "useWhen": [
+    "A person writes to an assistant and reads its answers as they stream."
+  ],
+  "avoidWhen": [
+    "The agent's actions themselves (approve, run, recover); use the agent-action contract alongside this one."
+  ],
+  "alternatives": [
+    "Use agent-action for what the agent does, and consequential-action for a person's own destructive actions."
+  ],
+  "requiredInputs": [
+    "a stream that yields text and resolves only when complete",
+    "errors classified as offline, rate limited, context full, refused or outage",
+    "the restored answer and whether it completed, after a reload",
+    "the context window used, when known"
+  ],
+  "states": [
+    "ready",
+    "submitted",
+    "streaming",
+    "complete",
+    "stopped",
+    "failed",
+    "interrupted",
+    "awaiting-input",
+    "queued"
+  ],
+  "transitions": [
+    "ready → submitted → streaming → complete",
+    "streaming → stopped on Stop, keeping the partial answer",
+    "submitted or streaming → failed, keeping the message, with Retry",
+    "streaming → awaiting-input while a Confirmation or Question is open, then back",
+    "a reload during streaming → interrupted, with Retry",
+    "a message written while streaming → queued, sent when the turn ends"
+  ],
+  "rules": [
+    "ALT-CONVO-001",
+    "ALT-AGENT-001",
+    "ALT-STATUS-001",
+    "ALT-VISUAL-003"
+  ],
+  "sources": [
+    "altitude-elevation",
+    "task-review",
+    "wcag22"
+  ],
+  "authority": "contextual-pattern",
+  "applicability": "Conversations with an assistant, in products and harnesses.",
+  "exceptions": [
+    "Persistence, retention and the transport are the application's; the contract covers what the person sees."
+  ],
+  "maturity": "provisional",
+  "evidenceStatus": "engineering-fixtures; human-effectiveness-unmeasured",
+  "document": "patterns/assistant-conversation.md",
+  "implementation": "build/fixtures/patterns/assistant-conversation.jsx",
+  "examples": [
+    "build/fixtures/patterns/assistant-conversation.jsx"
+  ],
+  "verification": [
+    "build/checks/assistant-conversation-pattern.mjs",
+    "build/checks/pattern-types.mjs",
+    "build/checks/pattern-workflows.mjs"
+  ]
+}

package/dist/guidance/patterns/assistant-conversation.md

@@ -0,0 +1,50 @@
+# Assistant conversation
+
+Help someone talk to an assistant: send, read the answer as it streams, stop it, retry, edit, and recover from every way a turn can fail, without losing their words or being told an answer is finished before it is. It composes `PromptInput`, `Conversation`, `Message`, `Markdown`, `ConversationQueue`, `ConversationCheckpoint`, `Alert` and `Meter`; what the agent *does* follows [Agent action](agent-action.md). The hook `useAssistantTurn` holds the turn.
+
+## Inputs and ownership
+
+Supply a stream that yields text as it arrives and resolves only when the provider says the answer is complete (throw an `AssistantError` with its kind when it fails), the restored answer and whether it completed when the page reloads, and the context window used when you know it. The application owns the transport, persistence, retention, what "complete" means for its provider, compaction, and limits. The interface never marks an answer complete on its own.
+
+## States and transitions
+
+| State | PromptInput | Message | Reading |
+|---|---|---|---|
+| ready | `ready` | — | the composer, its Send the view's one primary |
+| submitted | `submitted` (Send is Stop) | — | the person's message in the log at once |
+| streaming | `streaming` | `streaming` | the answer on the ground on a dashed rule, "Generating…" |
+| complete | `ready` | `complete` | the rule goes solid, one afterglow, announced once |
+| stopped | `ready` | `stopped` | the partial answer kept, "Stopped", Retry |
+| failed | `error` | `error` | the message kept in the composer; the error in words, with what to do |
+| interrupted | `ready` | `error` | after a reload: "Interrupted", Retry; never shown as complete |
+| awaiting-input | `streaming` | `streaming` | a `Confirmation` or `Question` is open; the turn waits |
+| queued | `streaming` | — | `ConversationQueue`: written, not sent |
+
+**Never lose the person's words.** A double Enter sends once. A failed send keeps the message (`turn.input`): put it back in the composer. Stop keeps the partial answer as "Stopped". Regenerating and editing keep versions (`MessageActions versions`, `onEdit`); rewinding sets turns aside (`ConversationCheckpoint`) rather than deleting them.
+
+**Completion is the stream's to say.** An answer settles only when the stream resolves. Late events from a turn that was stopped or superseded are dropped. After a reload, an answer that hadn't completed is "Interrupted" with Retry.
+
+**Errors in words, each its own state:**
+- **offline**: "We can't reach the assistant. Your message is kept; try again when you're back online."
+- **rate limited**: "You've reached this hour's limit. Try again at 3:40 PM."
+- **context full**: "This conversation is too long to continue. Start a new one with a summary."
+- **refused**: the provider's words, or "The assistant can't help with that request."
+- **outage**: "The assistant is unavailable right now. Your message is kept; try again in a few minutes."
+
+Say them in an `Alert` resting on the page above the composer, with the action that helps (Retry, Start a new conversation), not as one generic "Something went wrong".
+
+**The context window.** When you know how much is used, show a `Meter` in the composer toolbar with notches at 80% (caution) and 95% (critical), and say it ("80% of context used"). When the app compacts, mark the place with a checkpoint ("Summarised earlier messages").
+
+## Content, keyboard, focus and announcements
+
+Focus stays in the composer through a turn. Each answer is announced once, on completion, never token by token; Stop and failure are announced. Enter during IME composition never sends. Escape closes an open list first, stops listening second, and only then stops generating. Verify forced colours (streaming dashed, stopped and failed distinguishable without colour), reduced motion, zoom and RTL.
+
+## Recovery and working implementation
+
+Retry sends the kept input again; for rate limits it waits for the time it names. The working example in `build/fixtures/patterns/assistant-conversation.jsx` (also the Storybook preview "Patterns/AssistantConversationPattern") streams answers, stops, fails as offline, rate limited and context full, and restores an interrupted answer. [Metadata](assistant-conversation.json) names its sources and verification.
+
+## Rules, verification and evidence
+
+`ALT-CONVO-001` covers the turn: no double sends, no lost words, truthful completion, errors in words. `ALT-AGENT-001` covers what the agent does; `ALT-STATUS-001` covers announcements; `ALT-VISUAL-003` covers what mustn't rise (a streaming answer isn't pending). `build/checks/assistant-conversation-pattern.mjs` checks the example in a browser; `build/checks/pattern-workflows.mjs` drives the hook through a double submit, a stale stream, a reload mid-stream and a rate limit. Whether these words help people recover faster 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/async-collection.json

@@ -0,0 +1,71 @@
+{
+  "schemaVersion": 1,
+  "id": "async-collection",
+  "version": 1,
+  "title": "Async collection",
+  "intents": [
+    "search",
+    "filter",
+    "browse",
+    "list",
+    "records",
+    "collection"
+  ],
+  "purpose": "Find records while understanding loading, empty and failure states.",
+  "useWhen": [
+    "Records arrive asynchronously and can be searched or refreshed."
+  ],
+  "avoidWhen": [
+    "Use static content for a known local list; use pagination when the service requires it."
+  ],
+  "alternatives": [
+    "Use static content for a known local list; use pagination when the service requires it."
+  ],
+  "requiredInputs": [
+    "load callback",
+    "stable getKey",
+    "query semantics",
+    "selection policy",
+    "permissions and pagination"
+  ],
+  "states": [
+    "initial-loading",
+    "populated",
+    "refreshing",
+    "first-use-empty",
+    "no-results",
+    "failure"
+  ],
+  "transitions": [
+    "initial-loading \u2192 populated or empty or failure",
+    "populated \u2192 refreshing \u2192 populated or failure",
+    "query change \u2192 loading \u2192 results or no-results",
+    "failure \u2192 retry; reset clears query"
+  ],
+  "rules": [
+    "ALT-COLLECTION-001",
+    "ALT-STATUS-001",
+    "ALT-VISUAL-001"
+  ],
+  "sources": [
+    "altitude-elevation",
+    "task-review",
+    "wcag22"
+  ],
+  "authority": "contextual-pattern",
+  "applicability": "Records arrive asynchronously and can be searched or refreshed.",
+  "exceptions": [
+    "Require only states supported by the application; do not fabricate capabilities."
+  ],
+  "maturity": "provisional",
+  "evidenceStatus": "engineering-fixtures; human-effectiveness-unmeasured",
+  "document": "patterns/async-collection.md",
+  "implementation": "project/components/src/pattern-async-collection.tsx",
+  "examples": [
+    "build/fixtures/pattern-workflows.tsx",
+    "scripts/build-framework-fixture.mjs"
+  ],
+  "verification": [
+    "build/checks/pattern-workflows.mjs"
+  ]
+}

package/dist/guidance/patterns/async-collection.md

@@ -0,0 +1,29 @@
+# Async collection
+
+Help someone find and act on records while the data changes. Use asynchronous collections for search, filtering and browsing. A known local static list may need no loading state. Large service-backed datasets may need pagination or virtualization chosen by the application; this hook does not fetch every page or invent total counts.
+
+## Inputs and ownership
+
+Supply a `load` adapter, query, stable `getKey` and explicit selection policy. IDs must identify entities across sorting and refresh; array indexes do not. The app owns permission filtering, query parsing, pagination/cursors, URL/history, caching and whether reset means all records or an initial query. Never show an authorization failure as an empty dataset. Confirm which search fields and scopes the service supports.
+
+## States and transitions
+
+Runtime phases are `loading`, `populated`, `refreshing`, `empty`, `no-results` and `failed`. Distinguish initial loading, populated, refreshing with retained content, first-use empty, filtered no-results and failure. First-use empty invites the relevant next action; no-results offers query correction/reset. A failed refresh retains prior results and identifies their staleness. A new query invalidates an older response. Retry repeats the current request; reset returns to the initial query. Selection either clears on query changes or is explicitly preserved; explain selected items outside the visible result set and reconcile removal by stable ID. Do not imply selection means permission to act.
+
+## Content, keyboard, focus and announcements
+
+Label search and filters by their actual scope. Announce concise settled result counts, loading completion and failure through `WorkflowStatus`, avoiding noisy per-keystroke announcements. Use real links for record navigation, named buttons for actions, and native checkboxes for selection. Preserve focus in the search/filter control after updates; removal needs a deliberate next focus target. Use a semantic table for tabular relationships and a list for simple records; do not add grid keyboard behavior accidentally.
+
+At narrow widths retain names, selection state and actions; wrap long text or supply an equivalent accessible detail view. Keep reading order logical in RTL. Test long queries, translated status, zoom, forced colors and reduced motion. A skeleton alone does not communicate loading to assistive technology.
+
+## Recovery and working implementation
+
+Use `useAsyncCollection` with application-supplied loading and stable keys. Render every applicable `phase`, call `refresh` for retry, `reset` for query reset, and `toggleSelection` according to the chosen policy. Import the runtime from the main package export. The complete working composition, including controlled delay/rejection/recovery, is `build/fixtures/pattern-workflows.tsx`; its installed snapshot is under `references/build/fixtures/pattern-workflows.tsx`. Source and fixture paths are indexed in [metadata](async-collection.json). It demonstrates actual result state, not a decorative loading timer.
+
+The application must connect query changes to its URL/history policy and verify Back/forward, deep links and reload where supported. Pagination must retain the correct query and selection semantics; a stale page response must not restore a prior filter. Cached data can remain usable on failure only when permission and freshness policies allow it.
+
+## Rules, verification and evidence
+
+`ALT-COLLECTION-001` is an application integration obligation: test all applicable states, delayed responses, query changes, stable selection and reset against service fixtures. `ALT-STATUS-001` checks feedback semantics; `ALT-VISUAL-001` requires contextual visual review. See [metadata](async-collection.json) and [rules](../rules.json) for sources, exceptions and linked checks. This is a provisional contextual pattern, not a standard mandating every listed state in every product. Test actual search success and comprehension with representative people; engineering checks cannot determine appropriate information architecture.
+
+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.