@cynodia/axiom 0.9.0-alpha.1 → 0.9.0-alpha.2

package/AGENTS.md

@@ -0,0 +1,68 @@
+# Instructions for AI coding agents
+
+You are consuming **Axiom** as an application framework. This file is routing only; the
+contract lives in `docs/`.
+
+## Read this first
+
+**Read [`docs/AGENT_REFERENCE.md`](docs/AGENT_REFERENCE.md), in full, before writing any
+application code.** It is the compressed operational contract for application authors and it
+ships inside this package.
+
+Then escalate in this order, and only as far as the question requires:
+
+1. **`docs/AGENT_REFERENCE.md`** — the contract. Start here, every time.
+2. **The `.d.ts` declarations in `dist/`** — the API contract. Signatures, unions and
+   branded types are authoritative there.
+3. **The focused document in `docs/`** for the topic — the full contract for one area. See
+   the map in [`README.md`](README.md#documentation-map).
+4. **A minimal public-API probe** — build the smallest graph that isolates the question,
+   call `validateGraph` and read the returned codes. Diagnostics are structured and name
+   what is wrong.
+
+Only if all four leave the question open is reading framework implementation source
+justified. That is framework debugging, not application authoring.
+
+## Do not
+
+- **Do not clone or reverse-engineer the Axiom repository to learn normal usage.** Everything
+  needed to author an application is in this package. There is no published Axiom CLI.
+- **Do not search the web or scrape npm for documentation.** This package is the primary
+  source, and it describes this exact version.
+- **Do not read, edit or patch generated output.** The emitted JavaScript, HTML and CSS are
+  build products. Nothing is authored there.
+- **Do not guess the API from React, Vue, Angular, Svelte or Express conventions.** Axiom has
+  no component, no hook, no JSX, no route handler, no ORM and no callback anywhere in the
+  graph. Guessing from those conventions produces graphs `validateGraph` rejects.
+- **Do not reach for an escape hatch.** There is no `formatter: fn`, no `validator: fn`, no
+  raw-CSS channel and no stored closure. If a capability seems missing, it is expressed as a
+  graph node; look it up rather than working around it.
+
+## Prefer canonical Axiom semantics
+
+Each row is a pointer, not the rule. The rule itself lives in
+[`docs/AGENT_REFERENCE.md`](docs/AGENT_REFERENCE.md) and in the topic document; read it
+there rather than treating this table as a specification.
+
+| Instead of | Use |
+| --- | --- |
+| Mutating an object an expression returned | A `Location`, addressing the writable position |
+| A field name key in a record | The `FieldId` — runtime records are keyed by field id |
+| A hand-written validation function | A `ConstraintDef` or `TransitionConstraintDef` |
+| A hidden control to forbid an operation | A guard or a transition constraint. `hidden` is not `forbidden` |
+| CSS, a colour or a length | A presentation role or token, and a `Theme` |
+| A route handler, controller or SQL statement | `StateDef.authority` plus an `ActionDef` |
+| A callback for new capability | The graph node that expresses it |
+
+## When something fails
+
+`validateGraph` and the runtime both report structured diagnostics with a code and a path.
+Match on the code, never on the message, and look the code up:
+[`docs/VALIDATION.md`](docs/VALIDATION.md) for authoring-time codes,
+[`docs/RUNTIME.md`](docs/RUNTIME.md) for runtime codes. A construct that validates and then
+does nothing is a framework defect, not something to work around — report it.
+
+Mistakes that compile but are wrong are collected in
+[`docs/ANTI_PATTERNS.md`](docs/ANTI_PATTERNS.md). Read it before the **first** attempt, not the
+second: collection nulls, how a `repeat` binds its current item, and addressing a collection
+member by identity rather than index all shape a first draft rather than repairing it.

package/README.md

@@ -1,13 +1,39 @@
 # Axiom
 
-AI-native semantic application framework.
+AI-native semantic application framework. An application is a typed semantic graph, not
+source files.
 
-Axiom represents application behavior, state, UI structure and presentation as structured
-semantic data executed by generic runtimes. An application is a typed graph, not source
-files: the JavaScript and HTML that reach the browser are output, and are never edited.
+## AI agents: read this first
+
+**Read [`docs/AGENT_REFERENCE.md`](docs/AGENT_REFERENCE.md) before writing any Axiom code.**
+It ships inside this package, so no repository access, web search or framework source
+inspection is needed to obtain the contract.
+
+| | |
+| --- | --- |
+| **What** | A semantic application framework. State, behavior, constraints, UI structure, presentation and authority are structured data executed by generic runtimes. |
+| **Who for** | AI-authored applications. The primary author of an Axiom application is a coding agent; human readability is explicitly not the optimization target. |
+| **Start** | [`docs/AGENT_REFERENCE.md`](docs/AGENT_REFERENCE.md) — the compressed operational contract for application authors. |
+| **API contract** | The published `.d.ts` declarations in `dist/`. Authoritative for signatures, unions and branded types. |
+| **Deeper semantics** | The focused documents in `docs/` — [map below](#documentation-map). |
+| **Escalation** | `docs/AGENT_REFERENCE.md` → `.d.ts` → the focused `docs/` document for the topic → a minimal public-API probe. |
+
+Axiom's vocabulary is deliberately unlike React, Vue, Angular, Svelte or Express: there is no
+component, no hook, no JSX, no route handler, no ORM and no callback anywhere in the graph.
+Guessing the API from those conventions produces graphs `validateGraph` rejects, so reading
+the reference first is cheaper than any number of attempts.
+
+**Reading the framework's implementation source should not be necessary to author an
+application.** `docs/` plus the `.d.ts` declarations are intended to be sufficient on their
+own. Source inspection is a legitimate tool for debugging Axiom itself; it is not the way to
+discover normal consumer usage, and cloning the repository for that purpose is a sign the
+documentation above was missed.
+
+Shorter forms of the same routing: [`AGENTS.md`](AGENTS.md) and [`llms.txt`](llms.txt), both
+at this package's root.
 
 **Status: experimental / alpha.** The API may change between alpha releases. The
-documentation in `docs/` describes this exact version.
+documentation in `docs/` describes this exact version, `0.9.0-alpha.2`.
 
 ## Installation
 
@@ -17,6 +43,17 @@ npm install @cynodia/axiom-ui         # semantic UI authoring patterns (build ti
 npm install @cynodia/axiom-server     # only if the application has an authority
 ```
 
+Every release of this project is a pre-release and npm's `latest` tag points at it, so the
+plain command above installs the current version. **There is no `alpha` dist-tag** — the tag
+was removed once it stopped tracking releases, and `npm install @cynodia/axiom@alpha` now
+fails with a 404. Pin the exact version instead when one is needed:
+`npm install @cynodia/axiom@0.9.0-alpha.2`.
+
+These are ES modules compiled to ES2022; import them with `import`, not `require`. There is
+no published Axiom CLI. `@cynodia/axiom-server`'s SQLite persistence adapter additionally
+needs a Node build that provides `node:sqlite` (Node 22 or newer); `isSqliteAvailable()`
+reports its absence rather than failing at import.
+
 ## Canonical mental model
 
 | Concept | Is |
@@ -124,30 +161,39 @@ console.log(app.getState(COUNT)); // 1
 
 `compileToHtml(graph)` emits the same application as one self-contained page.
 
-## Documentation
+## Documentation map
 
-The complete operational contract ships with this package, in `docs/`.
+The complete operational contract ships with this package, in `docs/`. Every path below
+resolves inside the installed package. Read `docs/AGENT_REFERENCE.md` first; reach for a
+focused document when the reference is not specific enough for the question at hand.
 
 | Need to understand | Read |
 | --- | --- |
-| Compressed reference for authoring or modifying an app | `docs/AGENT_REFERENCE.md` |
-| Exact runtime guarantees | `docs/SEMANTIC_CONTRACT.md` |
-| Graph, ids, types, entity value representation | `docs/GRAPH_MODEL.md` |
-| Every expression kind, builtin and scope rule | `docs/EXPRESSIONS.md` |
-| Addressing writable positions | `docs/LOCATIONS.md` |
-| Stored, derived, draft and ephemeral state | `docs/STATE.md` |
-| Actions, operations, transactions, iteration | `docs/ACTIONS_TRANSACTIONS.md` |
-| Constraints and transition constraints | `docs/CONSTRAINTS.md` |
-| Semantic UI nodes and bindings | `docs/UI.md` |
-| Presentation, UX intent, themes, formatting | `docs/PRESENTATION.md` |
-| Runtime API and diagnostic codes | `docs/RUNTIME.md` |
-| Server authority, Server IR, the protocol and persistence | `docs/AUTHORITY.md` |
-| Machine queries and graph transformations | `docs/AGENT_API.md` |
-| Validation codes | `docs/VALIDATION.md` |
-| Mistakes that compile but are wrong | `docs/ANTI_PATTERNS.md` |
-
-Start with `docs/AGENT_REFERENCE.md`. It plus the `.d.ts` declarations are intended to be
-sufficient on their own.
+| **Compressed contract for authoring or modifying an app — start here** | [`docs/AGENT_REFERENCE.md`](docs/AGENT_REFERENCE.md) |
+| Exact runtime guarantees, stated formally | [`docs/SEMANTIC_CONTRACT.md`](docs/SEMANTIC_CONTRACT.md) |
+| Mistakes that compile but are wrong | [`docs/ANTI_PATTERNS.md`](docs/ANTI_PATTERNS.md) |
+| Graph, node kinds, ids, types, entity value representation | [`docs/GRAPH_MODEL.md`](docs/GRAPH_MODEL.md) |
+| Every expression kind, builtin, scope, presence and null rule | [`docs/EXPRESSIONS.md`](docs/EXPRESSIONS.md) |
+| Addressing writable positions | [`docs/LOCATIONS.md`](docs/LOCATIONS.md) |
+| Stored, derived, draft and ephemeral state | [`docs/STATE.md`](docs/STATE.md) |
+| Actions, operations, guards, transactions, iteration | [`docs/ACTIONS_TRANSACTIONS.md`](docs/ACTIONS_TRANSACTIONS.md) |
+| Constraints and transition constraints | [`docs/CONSTRAINTS.md`](docs/CONSTRAINTS.md) |
+| Semantic UI nodes, interaction primitives and bindings | [`docs/UI.md`](docs/UI.md) |
+| Presentation, UX intent, themes, value formatting | [`docs/PRESENTATION.md`](docs/PRESENTATION.md) |
+| Runtime API, startup lifecycle and diagnostic codes | [`docs/RUNTIME.md`](docs/RUNTIME.md) |
+| Validation codes and what rejects a graph | [`docs/VALIDATION.md`](docs/VALIDATION.md) |
+| Server authority, the trust boundary, Server IR, the protocol, persistence, deployment | [`docs/AUTHORITY.md`](docs/AUTHORITY.md) |
+| External systems: integration definitions, query operations, adapters, secrets | [`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md) |
+| External effects: the outbox, retries, delivery guarantees, outcomes | [`docs/EFFECTS.md`](docs/EFFECTS.md) |
+| Typed events, webhooks, the dispatch pipeline | [`docs/EVENTS.md`](docs/EVENTS.md) |
+| Timed and lifecycle execution, event-invoked actions | [`docs/TRIGGERS.md`](docs/TRIGGERS.md) |
+| Live inbound streams: lifecycle, delivery, deduplication, backpressure | [`docs/SUBSCRIPTIONS.md`](docs/SUBSCRIPTIONS.md) |
+| Binary data: `BlobRef`, upload, download, authorization, orphans | [`docs/STORAGE.md`](docs/STORAGE.md) |
+| Machine queries, mutation impact and graph transformations | [`docs/AGENT_API.md`](docs/AGENT_API.md) |
+
+`docs/AGENT_REFERENCE.md` plus the `.d.ts` declarations are intended to be sufficient on
+their own. If they are not, that is a documentation defect worth reporting rather than a
+reason to read framework source.
 
 ## What is in the box
 

package/docs/ACTIONS_TRANSACTIONS.md

@@ -1,6 +1,6 @@
 # Actions and transactions
 
-Axiom 0.9.0-alpha.1. An action is behavior expressed as data, executed as a transaction.
+Axiom 0.9.0-alpha.2. An action is behavior expressed as data, executed as a transaction.
 
 ```ts
 {

package/docs/AGENT_API.md

@@ -1,6 +1,6 @@
 # Agent API
 
-Axiom 0.9.0-alpha.1. The machine-facing interface. Agents query semantics and apply
+Axiom 0.9.0-alpha.2. The machine-facing interface. Agents query semantics and apply
 structural transformations; they never edit generated code.
 
 ```ts

package/docs/AGENT_REFERENCE.md

@@ -1,11 +1,45 @@
 # Agent reference
 
-Axiom 0.9.0-alpha.1. Compressed operational contract. Read this plus the `.d.ts`
+Axiom 0.9.0-alpha.2. Compressed operational contract. Read this plus the `.d.ts`
 declarations before authoring or modifying an Axiom application.
 
 Formal guarantees: [`SEMANTIC_CONTRACT.md`](SEMANTIC_CONTRACT.md). Mistakes that compile:
 [`ANTI_PATTERNS.md`](ANTI_PATTERNS.md).
 
+## Start here
+
+```bash
+npm install @cynodia/axiom            # graph, compiler, runtime, agent API
+npm install @cynodia/axiom-ui         # semantic UI authoring patterns, build time only
+npm install @cynodia/axiom-server     # only if a StateDef declares server authority
+```
+
+Everything is imported from `@cynodia/axiom`; the four re-exported packages need not be
+installed individually. There is no published CLI.
+
+A complete runnable skeleton — graph, state, action, UI, route, compile, run — is the
+minimal application in [`../README.md`](../README.md). Read this document for the rules;
+copy that for the shape.
+
+**Escalation order.** This document → the `.d.ts` declarations → the focused document for the
+topic → a minimal public-API probe: build the smallest graph that isolates the question, call
+`validateGraph`, read the returned codes. Reading Axiom's own implementation source is for
+debugging the framework, not for authoring an application.
+
+**How much of this to read.** Everything up to and including
+[Agent API](#agent-api) applies to every Axiom application. If no `StateDef` declares
+`authority: 'server'`, the application is client-only and
+[SERVER AUTHORITY](#server-authority) onwards — authority, integrations, effects, triggers,
+subscriptions, storage — describes capability it does not use; skim the headings and stop.
+Read [`ANTI_PATTERNS.md`](ANTI_PATTERNS.md) **before** the first attempt, not the second:
+collection nulls, repeat scope binding and identity-over-index selectors all shape a first
+draft.
+
+**Do not guess from React, Vue, Angular, Svelte or Express.** Axiom has no component, no hook,
+no JSX, no route handler, no ORM and no callback in the graph. There is no `formatter: fn`, no
+`validator: fn`, no raw-CSS channel and no stored closure anywhere; new capability arrives as
+an inspectable node, never as a function you supply.
+
 ## Glossary
 
 One canonical term per concept. These are not interchangeable.
@@ -31,7 +65,7 @@ One canonical term per concept. These are not interchangeable.
 ## Graph construction
 
 ```ts
-const graph = new ApplicationGraph(id, name);      // version defaults to '0.8.2'
+const graph = new ApplicationGraph(id, name);      // version defaults to '0.9.0'
 graph.addNode<StateDef>({ id, kind: 'state', ... }); // returns NodeId; throws if id exists
 graph.getNode<StateDef>(id);                        // deep clone, or undefined
 graph.updateNode(node);                             // write a modified node back
@@ -323,6 +357,13 @@ boolean types (`TYPE_MISMATCH`).
 Every kind is in `UI_NODE_KINDS`: `view` `container` `text` `repeat` `field-display` `form`
 `input` `button` `conditional` `diagnostic` `dialog`. Detail: [`UI.md`](UI.md).
 
+Every kind carries the same base, and `visibleWhen` lives here rather than in
+`presentation`:
+
+```ts
+{ id, kind, name?, visibleWhen?: Expression, presentation?: Presentation, metadata? }
+```
+
 - `RepeatNode` binds the current item to **the repeat node's own id**; the template refers to it as `ref(repeatNodeId)`.
 - `InputNode.binding` is `{ location }` — no expression, no field id. An input write goes through the same mutation engine and transaction as an action.
 - `ButtonNode.arguments` is keyed by **action parameter id**.
@@ -412,6 +453,22 @@ presentation: {
 }
 ```
 
+Every value is a closed vocabulary, exported as an array; a token outside it is a validation
+**error**, never a silently ignored value. The four an application reaches for constantly:
+
+| Property | Vocabulary | Array |
+| --- | --- | --- |
+| `layout` | `vertical` `horizontal` `grid` `stack` | `LAYOUT_KINDS` |
+| `gap`, `padding` | `none` `xsmall` `small` `medium` `large` `xlarge` | `SPACING_TOKENS` |
+| `textRole` | `body` `caption` `label` `heading` `title` `display` | `TEXT_ROLES` |
+| `density` | `compact` `comfortable` `spacious` | `DENSITIES` |
+
+`layout: 'horizontal'` is shorthand for `layout: { kind: 'horizontal', gap?, align?, justify?,
+wrap?, columns? }` — a bare token or the object, never a third form. `stack` is a tight
+vertical column, not overlapping children. Every other vocabulary — roles, UX roles, surfaces,
+treatments, icons, control variants, sizing, value formats, device classes —
+is in [`PRESENTATION.md`](PRESENTATION.md); read it before guessing a token.
+
 Resolution precedence, lowest first:
 
 ```text

package/docs/ANTI_PATTERNS.md

@@ -1,6 +1,6 @@
 # Anti-patterns
 
-Axiom 0.9.0-alpha.1. Each of these compiles. Each is wrong. Each is followed by the correct
+Axiom 0.9.0-alpha.2. Each of these compiles. Each is wrong. Each is followed by the correct
 alternative.
 
 ## 1. Field names as entity runtime keys

package/docs/AUTHORITY.md

@@ -1,6 +1,6 @@
 # Authority
 
-Axiom 0.9.0-alpha.1. How an application crosses the trust boundary.
+Axiom 0.9.0-alpha.2. How an application crosses the trust boundary.
 
 Until 0.5.x an Axiom application executed locally. 0.6 adds an **authority**: a generic
 runtime that owns state, decides mutations and persists them. The same semantic graph

package/docs/CONSTRAINTS.md

@@ -1,6 +1,6 @@
 # Constraints
 
-Axiom 0.9.0-alpha.1. Two constructs, answering different questions. They are not
+Axiom 0.9.0-alpha.2. Two constructs, answering different questions. They are not
 interchangeable.
 
 | | Question | Sees |

package/docs/EFFECTS.md

@@ -1,6 +1,6 @@
 # Effects
 
-Axiom 0.9.0-alpha.1. External effects are not rollback-capable state mutations. This file
+Axiom 0.9.0-alpha.2. External effects are not rollback-capable state mutations. This file
 is the delivery model; [`AUTHORITY.md`](AUTHORITY.md#external-effects) is the load-bearing
 statement of why, and [`INTEGRATIONS.md`](INTEGRATIONS.md) is the operation vocabulary this
 builds on.

package/docs/EVENTS.md

@@ -1,6 +1,6 @@
 # Events
 
-Axiom 0.9.0-alpha.1. An event is a typed fact — something that happened — never work
+Axiom 0.9.0-alpha.2. An event is a typed fact — something that happened — never work
 itself. [`AUTHORITY.md`](AUTHORITY.md#external-events) is the load-bearing statement;
 this file is the vocabulary and the webhook delivery mechanism. A **subscription** is the
 other way an external fact becomes an `EventDef` payload — see

package/docs/EXPRESSIONS.md

@@ -1,6 +1,6 @@
 # Expressions
 
-Axiom 0.9.0-alpha.1. An expression describes **what value is computed**. It is a tree of
+Axiom 0.9.0-alpha.2. An expression describes **what value is computed**. It is a tree of
 plain data, never source text and never a callback. Evaluation is pure: an expression MUST
 NOT change state.
 

package/docs/GRAPH_MODEL.md

@@ -1,6 +1,6 @@
 # Graph model
 
-Axiom 0.9.0-alpha.1. The `ApplicationGraph` is the authoritative representation of an
+Axiom 0.9.0-alpha.2. The `ApplicationGraph` is the authoritative representation of an
 application. Everything else — the IR, the page, the DOM — is derived from it and is never
 edited.
 

package/docs/INTEGRATIONS.md

@@ -1,6 +1,6 @@
 # Integrations
 
-Axiom 0.9.0-alpha.1. How an application declares and calls an external system, without
+Axiom 0.9.0-alpha.2. How an application declares and calls an external system, without
 embedding a transport, an SDK or a secret in the graph. The authority boundary this
 depends on is [`AUTHORITY.md`](AUTHORITY.md#external-systems); this file is the vocabulary.
 

package/docs/LOCATIONS.md

@@ -1,6 +1,6 @@
 # Locations
 
-Axiom 0.9.0-alpha.1.
+Axiom 0.9.0-alpha.2.
 
 ```text
 Expression = a value

package/docs/PRESENTATION.md

@@ -1,6 +1,6 @@
 # Presentation
 
-Axiom 0.9.0-alpha.1. Presentation is **semantic UX intent**, expressed as data on a UI
+Axiom 0.9.0-alpha.2. Presentation is **semantic UX intent**, expressed as data on a UI
 node. It names roles, tokens and device classes. It never names a colour, a length, a media
 query or a CSS property.
 

package/docs/RUNTIME.md

@@ -1,6 +1,6 @@
 # Runtime
 
-Axiom 0.9.0-alpha.1. The runtime executes an `ApplicationIR`. It is domain-independent: it
+Axiom 0.9.0-alpha.2. The runtime executes an `ApplicationIR`. It is domain-independent: it
 contains no knowledge of any application.
 
 ## Constructing

package/docs/SEMANTIC_CONTRACT.md

@@ -1,6 +1,6 @@
 # Semantic contract
 
-Axiom 0.9.0-alpha.1. Runtime guarantees, stated formally. This file defines behavior; it
+Axiom 0.9.0-alpha.2. Runtime guarantees, stated formally. This file defines behavior; it
 does not teach. Where this file and any specification in `../specs/` disagree, this file
 describes the implementation and is authoritative.
 

package/docs/STATE.md

@@ -1,6 +1,6 @@
 # State
 
-Axiom 0.9.0-alpha.1. A `StateDef` is a named application value: stored, or computed from
+Axiom 0.9.0-alpha.2. A `StateDef` is a named application value: stored, or computed from
 other state.
 
 ```ts

package/docs/STORAGE.md

@@ -1,6 +1,6 @@
 # Storage and blobs
 
-Axiom 0.9.0-alpha.1. How an application stores, references, serves and deletes binary data —
+Axiom 0.9.0-alpha.2. How an application stores, references, serves and deletes binary data —
 an attachment, a document, a photograph, a diagnostic log — with no filesystem path, no
 upload route and no download route anywhere in it.
 

package/docs/SUBSCRIPTIONS.md

@@ -1,6 +1,6 @@
 # Subscriptions
 
-Axiom 0.9.0-alpha.1. How an application receives a stream of external events — an MQTT
+Axiom 0.9.0-alpha.2. How an application receives a stream of external events — an MQTT
 topic, a WebSocket feed, a queue consumer, a filesystem watcher, a serial port — without a
 client, a socket or a callback anywhere in the graph.
 

package/docs/TRIGGERS.md

@@ -1,6 +1,6 @@
 # Triggers
 
-Axiom 0.9.0-alpha.1. A `TriggerDef` says **when** an action should be invoked, without
+Axiom 0.9.0-alpha.2. A `TriggerDef` says **when** an action should be invoked, without
 embedding callback code. `docs/AUTHORITY.md`
 [§ Triggers](AUTHORITY.md#triggers) is the load-bearing statement of the execution model;
 this file is the vocabulary.

package/docs/UI.md

@@ -1,6 +1,6 @@
 # UI
 
-Axiom 0.9.0-alpha.1. Eleven semantic UI node kinds describe **what exists and what it does**.
+Axiom 0.9.0-alpha.2. Eleven semantic UI node kinds describe **what exists and what it does**.
 How it looks is [presentation](PRESENTATION.md).
 
 All eleven share `UIBase`:
@@ -326,8 +326,10 @@ A pattern is an authoring abstraction and nothing else: after expansion the appl
 ordinary Axiom application, and `validateGraph`, `compileToIR`, `AgentAPI` and the runtime know
 nothing about patterns. Ownership defaults to the **declaration**, so editing a generated node
 is drift rather than an edit. The contract travels with the package rather than being restated here: install
-`@cynodia/axiom-ui` and read its `README.md`, `docs/TOOLKIT_AGENT_REFERENCE.md` and
-`docs/PATTERN_CATALOG.json` — the last is addressable as `@cynodia/axiom-ui/catalog`.
+`@cynodia/axiom-ui` and read, inside **that** package,
+`@cynodia/axiom-ui/docs/TOOLKIT_AGENT_REFERENCE.md`, its `README.md` and
+`@cynodia/axiom-ui/docs/PATTERN_CATALOG.json` — the last is addressable as
+`@cynodia/axiom-ui/catalog`. None of the three is in this package.
 
 ## Containment
 

package/docs/VALIDATION.md

@@ -1,6 +1,6 @@
 # Validation
 
-Axiom 0.9.0-alpha.1. Validation is authoring-time structural checking. It is not the same
+Axiom 0.9.0-alpha.2. Validation is authoring-time structural checking. It is not the same
 as runtime constraint evaluation — see [`CONSTRAINTS.md`](CONSTRAINTS.md) for the four
 layers of correctness.
 

package/llms.txt

@@ -0,0 +1,65 @@
+# Axiom
+
+> AI-native semantic application framework, version 0.9.0-alpha.2. An Axiom application is a
+> typed semantic graph — state, behavior, constraints, UI structure, presentation and
+> authority as structured data — executed by generic runtimes. The JavaScript, HTML and CSS
+> that reach a browser are compiler output and are never authored or edited. The primary
+> author of an Axiom application is an AI coding agent.
+
+Start with docs/AGENT_REFERENCE.md. Every path below is relative to this package root and
+resolves inside the installed package: no repository access, web search or framework source
+inspection is required to obtain the contract.
+
+Escalation order: docs/AGENT_REFERENCE.md → the `.d.ts` declarations in dist/ → the focused
+document for the topic → a minimal public-API probe (build the smallest graph, call
+`validateGraph`, read the codes). Framework implementation source is for debugging Axiom
+itself, not for authoring an application.
+
+## Start here
+
+- [docs/AGENT_REFERENCE.md](docs/AGENT_REFERENCE.md): The compressed operational contract for application authors. Read first, in full.
+- [AGENTS.md](AGENTS.md): Short routing and prohibition list for coding agents.
+- [README.md](README.md): Mental model, load-bearing invariants, one runnable minimal application, the documentation map.
+- [docs/ANTI_PATTERNS.md](docs/ANTI_PATTERNS.md): Mistakes that compile but are wrong. Read before a second attempt.
+
+## API contract
+
+- dist/index.d.ts: The public TypeScript declarations. Authoritative for signatures, unions and branded types.
+- [docs/SEMANTIC_CONTRACT.md](docs/SEMANTIC_CONTRACT.md): The runtime guarantees, stated formally.
+- [docs/VALIDATION.md](docs/VALIDATION.md): Every authoring-time validation code and what rejects a graph.
+- [docs/RUNTIME.md](docs/RUNTIME.md): The runtime API, startup lifecycle and every runtime diagnostic code.
+
+## Semantics
+
+- [docs/GRAPH_MODEL.md](docs/GRAPH_MODEL.md): Graph, node kinds, ids, structured types, entity value representation.
+- [docs/EXPRESSIONS.md](docs/EXPRESSIONS.md): Every expression kind, builtin, scope rule, presence and collection-null semantics.
+- [docs/LOCATIONS.md](docs/LOCATIONS.md): Addressing writable positions. Expressions produce values; locations name where a value lives.
+- [docs/STATE.md](docs/STATE.md): Stored, derived, draft and ephemeral state.
+- [docs/ACTIONS_TRANSACTIONS.md](docs/ACTIONS_TRANSACTIONS.md): Actions, operations, guards, transactions, `for-each` iteration.
+- [docs/CONSTRAINTS.md](docs/CONSTRAINTS.md): Constraints over proposed state and transition constraints over a change.
+
+## UI and presentation
+
+- [docs/UI.md](docs/UI.md): Semantic UI node kinds, interaction primitives, input bindings, pattern authoring.
+- [docs/PRESENTATION.md](docs/PRESENTATION.md): Semantic UX intent, roles, tokens, device classes, themes, value formatting. No CSS in the graph.
+
+## Server, external world, tooling
+
+- [docs/AUTHORITY.md](docs/AUTHORITY.md): State authority, the trust boundary, Server IR, the semantic protocol, persistence, authorization, deployment, conformance.
+- [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md): Integration definitions, query operations, adapters, secrets.
+- [docs/EFFECTS.md](docs/EFFECTS.md): Post-commit effects, the transactional outbox, retries, delivery guarantees, effect outcomes.
+- [docs/EVENTS.md](docs/EVENTS.md): Typed event definitions, webhooks, the event dispatch pipeline.
+- [docs/TRIGGERS.md](docs/TRIGGERS.md): Interval, delay, lifecycle and event triggers invoking actions under a system principal.
+- [docs/SUBSCRIPTIONS.md](docs/SUBSCRIPTIONS.md): Live inbound streams, the six-state lifecycle, at-least-once delivery, deduplication, backpressure.
+- [docs/STORAGE.md](docs/STORAGE.md): Portable binary object storage, `BlobRef`, staged-then-committed uploads, read and upload authorization, orphans.
+- [docs/AGENT_API.md](docs/AGENT_API.md): Machine queries over a graph, mutation-impact analysis, transactional graph transformations.
+
+## Packages
+
+- @cynodia/axiom: This package. Re-exports the graph, compiler, runtime and agent API. Installing it is normally enough.
+- @cynodia/axiom-server: The authoritative runtime. Install separately, only if the application declares server-owned state.
+- @cynodia/axiom-ui: Semantic UI authoring patterns, expanded into canonical nodes at build time. Install separately, needed only while authoring.
+
+## Optional
+
+- [docs/AGENT_REFERENCE.md](docs/AGENT_REFERENCE.md): Also the index of the vocabulary tables — expression kinds, operation kinds, diagnostic codes, presentation tokens.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cynodia/axiom",
-  "version": "0.9.0-alpha.1",
+  "version": "0.9.0-alpha.2",
   "description": "AI-native semantic web application framework.",
   "license": "MIT",
   "author": "AskTech AS",
@@ -21,6 +21,8 @@
     "dist/**/*.d.ts",
     "docs/*.md",
     "README.md",
+    "AGENTS.md",
+    "llms.txt",
     "LICENSE"
   ],
   "main": "./dist/index.js",
@@ -32,10 +34,10 @@
     }
   },
   "dependencies": {
-    "@cynodia/axiom-core": "0.9.0-alpha.1",
-    "@cynodia/axiom-runtime": "0.9.0-alpha.1",
-    "@cynodia/axiom-compiler": "0.9.0-alpha.1",
-    "@cynodia/axiom-agent-api": "0.9.0-alpha.1"
+    "@cynodia/axiom-core": "0.9.0-alpha.2",
+    "@cynodia/axiom-runtime": "0.9.0-alpha.2",
+    "@cynodia/axiom-compiler": "0.9.0-alpha.2",
+    "@cynodia/axiom-agent-api": "0.9.0-alpha.2"
   },
   "scripts": {
     "build": "tsc -b tsconfig.json"