routegraph 0.0.0-stage → 0.1.0

package/AGENTS.md

@@ -0,0 +1,42 @@
+# AGENTS.md
+
+Guidance for AI coding agents. Part 1 is for projects that use routegraph. Part 2 is for working on the routegraph repository itself.
+
+## Part 1: Using routegraph in a project
+
+routegraph models an app as a directed graph of screens (`.navgraph` text), finds routes, and emits JSON instructions. Read `llms.txt` in this package for the full cheat sheet, and `README.md` for the reference.
+
+Checklist when generating or editing a `.navgraph`:
+1. Start with `NAVGRAPH/2`. Declare every `VAR` that a `$NAME$` reference uses.
+2. Declare each `SCREEN` once. Edge endpoints must be declared screens.
+3. Write both directions explicitly. Reverse edges are never inferred.
+4. Every `DO TYPE` must exist in the active schema, and payloads must satisfy its `required` and `properties`.
+5. Costs are non-negative numbers. Use cost for "how bad is this transition", not for action counts.
+6. Quote `if=` expressions that contain commas or brackets.
+7. Validate with `validateGraph(parseGraph(text))` or `indexTreeFromText(text, { diagnostics: "collect" })` and read `diagnostics` (each has code, line, column).
+
+Checklist when writing code against the API:
+- Routes are synchronous. Instruction building is async by default (`buildInstructions`) with a sync twin (`buildInstructionsSync`).
+- React Native: use `indexTreeFromText` with bundled text, or pass `readFile` to `indexTree`.
+- Extensions are local trusted code passed in `buildInstructions(path, { extensions })`. Never place code in a `.navgraph`.
+- Use `tryCalculatePath` when "no route" is an expected outcome.
+
+## Part 2: Working on this repository
+
+Commands:
+- `npm install`
+- `npm run typecheck` (strict TS, includes tests)
+- `npm test` (vitest, 88 tests)
+- `npm run build` (tsup, CJS plus ESM plus d.ts into `dist/`)
+- `npm run prepublishOnly` runs all of the above
+
+Layout (`src/`): `parser.ts` (navgraph text to Graph IR), `schema.ts` (default schema, inheritance, payload validation), `graph.ts` (validation, indexing, `NavigationTree`), `conditions.ts` (safe expression language), `variables.ts` (scopes and `$VAR$` resolution), `pathfinding.ts` (A*, Dijkstra, BFS, heap), `extensions.ts` and `instructions.ts` (hooks and builder), `drive.ts` (generator drivers), `runtime.ts` (optional executor), `index.ts` (public exports).
+
+Rules to preserve:
+- No Node-only APIs in the core. File access goes through `files.ts` and the `readFile` option. No `require`, no dynamic `import()` with variables (Metro rejects them).
+- Sync and async builders share one generator implementation in `drive.ts`. Do not fork logic between them.
+- Parser and pathfinder stay deterministic. Tie breaking is by estimate, heuristic, then discovery order.
+- Output stays plain JSON. Extension output is namespaced and validated.
+- Graph files never execute code.
+- Copy and docs style: plain prose, no em dashes, no emoji, no ASCII art.
+- New behavior needs a test in `tests/`. Keep `npm run typecheck` clean.

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+Keep a Changelog and the project follows semantic versioning.
+
+## 0.1.0
+
+Initial release.
+
+- `.navgraph` (NAVGRAPH/2) parser with line and column errors.
+- JSON based `.navschema` with `extends`, explicit `overrides` and `remove`.
+- Typed variables with defaults, route inputs and runtime values.
+- Safe condition language (no eval) with custom word operators.
+- A*, Dijkstra and BFS pathfinding with deterministic tie breaking, custom algorithms, cost functions and edge filters.
+- Instruction generation with action, step and route extension hooks, dependencies, validation and an error policy.
+- Synchronous and asynchronous builders that share one implementation.
+- Optional, opt-in action runtime with timeouts, retries and abort support.
+- Dual CJS and ESM build with bundled type declarations. No Node only APIs in the core, so it runs in React Native.

package/CLAUDE.md

@@ -0,0 +1,11 @@
+# CLAUDE.md
+
+@AGENTS.md
+
+## Notes for Claude
+
+- If asked about the `routegraph` package, read `llms.txt` first. It is a complete cheat sheet and is accurate for this version.
+- When writing a `.navgraph`, validate it before presenting it: run `validateGraph(parseGraph(text))` or build the tree with `diagnostics: "collect"` and fix every error.
+- Prefer `indexTreeFromText` and `buildInstructionsSync` in React Native examples unless extensions are async.
+- Do not invent actions. Check the active schema; the default set is TAP, LONG_PRESS, TYPE, SWIPE, SCROLL, BACK, WAIT, SET_STATE, ASSERT.
+- When changing the repo, run `npm run typecheck && npm test` before finishing.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sorren
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,440 @@
-# Temporary Holding Version
+# routegraph
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed navigation graphs for apps. Describe your screens and the transitions between them in a small text format, ask for a route, and get back a plain JSON instruction tree you can use for tutorials, UI automation, narration, analytics, or anything else.
+
+- Compact `.navgraph` format that is easy to read, diff, and generate with an LLM.
+- Deterministic parsing, validation, and pathfinding (A*, Dijkstra, BFS, or your own). No LLM is ever involved in finding a route.
+- Typed variables with `$NAME$` substitution.
+- Extension hooks that add data to actions, steps, or whole routes while the instructions are generated.
+- Works the same in React Native, browsers, and Node. Every entry point that can be synchronous has a synchronous form.
+- Zero runtime dependencies, dual ESM and CommonJS build, full TypeScript declarations.
+
+routegraph does not drive a UI by itself. An optional runtime is included if you want to execute instructions through handlers you register.
+
+## Working with AI assistants
+
+The package ships `llms.txt` (a complete cheat sheet), `AGENTS.md`, and `CLAUDE.md`. Assistants that read `node_modules/routegraph` pick up the format, API, and common mistakes without further prompting. Point other tools at `node_modules/routegraph/llms.txt`.
+
+## Install
+
+```sh
+npm install routegraph
+```
+
+Requires Node 18 or newer for tooling. The library itself uses only ES2020 features and no Node APIs, so it runs on Hermes and in browsers.
+
+## Quick start
+
+`example.navgraph`:
+
+```
+NAVGRAPH/2
+APP "Example Store"
+
+VAR PRODUCT_ID : string
+VAR QUANTITY : number = 1
+
+SCREEN home "Home"
+SCREEN shop "Shop"
+SCREEN product "Product Details"
+SCREEN cart "Cart"
+
+home -> shop { DO TAP { "target": "Shop" } }
+shop -> home { DO BACK {} }
+shop -> product {
+  DO TAP { "target": "Product Card", "match": { "productId": "$PRODUCT_ID$" } }
+  DO WAIT { "until": "screen:product", "timeoutMs": 5000 }
+}
+product -> cart {
+  DO TAP { "target": "Add to Cart" }
+  DO SET_STATE { "key": "cart.quantity", "value": "$QUANTITY$" }
+}
+END
+```
+
+```ts
+import * as AppNav from "routegraph";
+
+const tree = await AppNav.indexTree("./example.navgraph");
+
+const path = AppNav.calculatePath(tree, "home", "cart", AppNav.ASTAR, {
+  variables: { PRODUCT_ID: "PRODUCT_123" },
+});
+
+const instructions = await AppNav.buildInstructions(path);
+console.log(JSON.stringify(instructions, null, 2));
+```
+
+Named imports and the namespace object both work:
+
+```ts
+import { indexTree, calculatePath, buildInstructions, AppNav } from "routegraph";
+```
+
+## React Native
+
+React Native has no filesystem API in the JavaScript runtime, so there are two ways to load a graph.
+
+**1. Bundle the text and use the synchronous API.** This is the simplest option and needs no async code at all.
+
+```ts
+import { indexTreeFromText, calculatePath, buildInstructionsSync } from "routegraph";
+import graphText from "./app.navgraph.txt"; // or a plain .ts file that exports a string
+
+const tree = indexTreeFromText(graphText);
+const path = calculatePath(tree, "home", "cart", "astar", { variables: { PRODUCT_ID: "42" } });
+const instructions = buildInstructionsSync(path);
+```
+
+Metro does not load `.navgraph` files out of the box. Either export the text from a `.ts` file, or add the extension to `metro.config.js` with a small transformer for raw text.
+
+**2. Supply a `readFile` function and use the async API.** Any function that returns a promise of a string works.
+
+```ts
+import * as FileSystem from "expo-file-system";
+import { indexTree } from "routegraph";
+
+const tree = await indexTree(`${FileSystem.documentDirectory}app.navgraph`, {
+  readFile: (p) => FileSystem.readAsStringAsync(p),
+  schema: `${FileSystem.documentDirectory}app.navschema`,
+});
+```
+
+`readFile` is also used for schema files and schema `extends` chains.
+
+### Sync and async at a glance
+
+| Task | Synchronous | Asynchronous |
+| --- | --- | --- |
+| Load a graph | `indexTreeFromText(text, options)` | `indexTree(path, options)` |
+| Load a schema | `resolveSchema(definition)` | `loadSchema(pathOrDefinition)` |
+| Find a route | `calculatePath`, `tryCalculatePath` | not needed, always synchronous |
+| Build instructions | `buildInstructionsSync(path, options)` | `buildInstructions(path, options)` |
+| Execute instructions | `runtime.executeSync(instructions)` | `runtime.execute(instructions)` |
+
+`buildInstructions` always returns a promise, so you never have to guess. `buildInstructionsSync` throws an `AsyncExtensionError` if an extension hook returns a promise. Both are driven by the same generator, so their behavior cannot drift apart.
+
+## The .navgraph format
+
+```
+NAVGRAPH/2                      header, required, first non-comment line
+APP "Name"                      optional
+VAR NAME : type [= json]        zero or more
+SCREEN id "Display Name" [{json metadata}]
+src -> dst [attrs] [{ DO TYPE {json} ... }]
+END                             optional, nothing may follow it
+```
+
+General rules:
+
+- Comments start with `#` and run to the end of the line. A `#` inside a string is not a comment.
+- Whitespace and line breaks are free between tokens. `APP`, `VAR`, and `SCREEN` declarations must end at a line break.
+- Strings are JSON strings, so JSON escapes apply. JSON payloads may span many lines.
+- Screen ids match `[A-Za-z_][A-Za-z0-9_.:]*`. Variable names match `[A-Za-z_][A-Za-z0-9_]*`.
+- Edges are directed. Reverse travel needs its own edge. Nothing is ever inferred.
+- An edge with no block has no actions, which is valid. `DO BACK` without braces is the same as `DO BACK {}`.
+- Several edges may connect the same pair of screens. Each edge has a unique id: the one you give it with `id=`, or `src->dst`, with `#2`, `#3` and so on added for repeats.
+
+### Edge attributes
+
+```
+a -> b [cost=2, if=SIGNED_IN, id=hop, label="Go", weight=7]
+```
+
+| Attribute | Meaning |
+| --- | --- |
+| `cost` | Finite number, zero or more. Default is 1, changeable with the `defaultCost` option. |
+| `if` | Condition expression. The edge is only available when it is true. |
+| `id` | Explicit unique edge id. |
+| anything else | Free metadata, stored on `edge.meta`. Can be validated by a schema. |
+
+The cost belongs to the edge, not to the actions. An edge with three actions and `cost=3` is still one transition.
+
+### Conditions
+
+Conditions use a small, safe expression language. There is no `eval` and no JavaScript.
+
+```
+expr    := or
+or      := and (("||" | "or") and)*
+and     := not (("&&" | "and") not)*
+not     := ("!" | "not") not | compare
+compare := primary [op primary]            op: == != < <= > >=  or a word operator
+primary := "text" | 'text' | number | true | false | null | path | "(" expr ")"
+path    := name ("." name)*
+```
+
+Names are looked up in the route variables first, then in the `state` object you pass to `calculatePath`. Dotted paths walk into objects. A flat state key such as `"cart.notEmpty"` also works.
+
+Unknown values are `undefined`. Undefined is falsy, every comparison with undefined is false except `!=`, which is true. Pass `strictConditions: true` to throw instead.
+
+Built in word operators are `in` and `contains`. Add your own:
+
+```ts
+calculatePath(tree, "home", "admin", "astar", {
+  state: { role: "staff" },
+  conditionOperators: { startsWith: (l, r) => String(l).startsWith(String(r)) },
+});
+```
+
+Conditions inside `[...]` that contain a comma or square bracket should be quoted: `if="role in roles"`.
+
+## Variables
+
+```
+VAR USER_NAME : string = "Aspen"
+VAR PRODUCT_ID : string
+VAR QUANTITY : number = 3
+```
+
+Types are `string`, `number`, `boolean`, `null`, `object`, `array`, and `any`. A variable without a default is required whenever something needs its value.
+
+Substitution happens inside action payload strings:
+
+| Payload value | Result with `PRODUCT_ID="SKU-123"`, `QUANTITY=3` |
+| --- | --- |
+| `"$QUANTITY$"` | `3` (the native number) |
+| `"Product $PRODUCT_ID$"` | `"Product SKU-123"` (interpolated text) |
+| `"$$PRODUCT_ID$$"` | `"$PRODUCT_ID$"` (escaped literal) |
+| `"costs $5"` | `"costs $5"` (a lone `$` is left alone) |
+
+A string that is exactly one reference gets the variable's native type. Embedded references use the string form, with objects and arrays written as JSON. Only values are substituted, never object keys. Undefined variables and missing required values throw a `VariableError` instead of producing an empty string.
+
+Precedence, lowest to highest:
+
+1. Defaults declared in the graph.
+2. Route inputs (`variables` option).
+3. Runtime values (`runtime` option).
+
+Supplied values for declared variables are type checked. Values for undeclared variables are accepted unless you pass `strictVariables: true`. The graph validator rejects payload references to undeclared variables by default.
+
+Extension configuration is a separate scope. It never changes route variables.
+
+## Schemas
+
+A schema declares which action types are valid and what their payloads look like. A bundled default covers `TAP`, `LONG_PRESS`, `TYPE`, `SWIPE`, `SCROLL`, `BACK`, `WAIT`, `SET_STATE`, and `ASSERT`. Add your own:
+
+```json
+{
+  "schemaVersion": 1,
+  "name": "my-app",
+  "extends": "default",
+  "actions": {
+    "SCAN_QR": {
+      "description": "Project specific QR scan action",
+      "required": ["camera"],
+      "properties": {
+        "camera": { "type": "string" },
+        "timeoutMs": { "type": "number" }
+      }
+    }
+  },
+  "edgeMetadata": { "label": { "type": "string" } },
+  "screenMetadata": { "icon": { "type": "string" } }
+}
+```
+
+```ts
+const tree = await indexTree("./app.navgraph", { schema: "./app.navschema" });
+// or, with no filesystem:
+const tree = indexTreeFromText(text, { schema: mySchemaObject });
+```
+
+Inheritance rules:
+
+- Adding an action is always allowed.
+- Redefining an inherited action with an identical definition is allowed.
+- Redefining it differently is an error unless the action is listed in `overrides`.
+- Removing an inherited action requires listing it in `remove`.
+- `extends` can be `"default"`, the name of a schema registered with `registerSchema`, or (with `loadSchema`) a file path.
+
+Property definitions support `type` (including `integer`, and arrays of types), `enum`, `minimum`, `maximum`, `required`, `properties`, `additionalProperties`, and `items`. Unknown properties are allowed by default so payloads can carry extra data. Set `"additionalProperties": false` to forbid them. A JSON Schema for editor support is shipped at `routegraph/schemas/navschema-v1.schema.json`.
+
+A schema describes what is valid. It does not implement anything. Declaring `SCAN_QR` does not give you a camera.
+
+## Validation and diagnostics
+
+`indexTree` and `indexTreeFromText` validate by default and throw a `ValidationError` that carries every diagnostic. For tooling, use collect mode or validate directly:
+
+```ts
+const tree = indexTreeFromText(text, { diagnostics: "collect" });
+tree.diagnostics; // errors and warnings with file, line, column, and ids
+
+const result = validateGraph(parseGraph(text), schema);
+if (!result.ok) console.log(result.errors);
+```
+
+Checks include: unsupported version, duplicate screens, edges, and variables, unknown screens in edges, invalid or negative costs, invalid conditions and operators, unknown action types, missing or mistyped payload properties, undeclared variables, and variables whose declared type does not fit the payload property.
+
+Every thrown error extends `AppNavError` and has `code`, and where possible `file`, `line`, `column`, and `ids`.
+
+## Pathfinding
+
+```ts
+const path = calculatePath(tree, "home", "checkout", AppNav.ASTAR, options);
+```
+
+Algorithms: `ASTAR` (default), `DIJKSTRA`, `BFS` (fewest edges, ignores cost for the search), or any function matching `PathfindingAlgorithm`. Register one by name with `registerAlgorithm`.
+
+Options:
+
+| Option | Purpose |
+| --- | --- |
+| `variables`, `runtime`, `state` | Context for conditions. |
+| `heuristic(from, goal, tree)` | A* heuristic. Must be admissible for optimal routes. Defaults to 0, which makes A* behave like Dijkstra. |
+| `costFn(edge)` | Replace edge costs, for example to penalise risky transitions. Must be finite and non-negative. |
+| `edgeFilter(edge)` | Veto edges. |
+| `conditionOperators`, `strictConditions` | Condition behavior. |
+
+Notes:
+
+- `calculatePath` throws `NoPathError` when there is no route. `tryCalculatePath` returns `{ ok: true, path }` or `{ ok: false, error }` instead.
+- Ties are broken deterministically: lower total estimate, then lower heuristic, then the order edges were discovered, which follows declaration order. Equal inputs always give the same route.
+- One call finds one route for one pair of screens. There is no all pairs mode and no hidden caching.
+- `path.variables` stores the route inputs, so `buildInstructions(path)` works without repeating them. Anything passed to `buildInstructions` overrides it.
+- `findReachable(tree, start, options)` lists the screens you can get to.
+
+## Instruction output
+
+```json
+{
+  "from": "home",
+  "to": "checkout",
+  "path": ["home", "shop", "cart", "checkout"],
+  "steps": [
+    {
+      "n": 1,
+      "from": "home",
+      "to": "shop",
+      "edge": "home->shop",
+      "cost": 1,
+      "actions": [
+        { "type": "TAP", "data": { "target": "Shop" }, "extensions": {} }
+      ],
+      "extensions": {}
+    }
+  ],
+  "cost": 3,
+  "extensions": {},
+  "meta": { "app": "Example Store", "algorithm": "astar", "generator": "routegraph" }
+}
+```
+
+It is ordinary JSON. Options for `buildInstructions`: `variables`, `runtime`, `extensions`, `extensionVariables`, `onError`, `includeUnresolved` (keeps the original payload on each action as `unresolved`, handy for debugging), and `strictVariables`.
+
+Narrow actions with `isAction`:
+
+```ts
+for (const step of instructions.steps) {
+  for (const action of step.actions) {
+    if (isAction(action, "TAP")) action.data.target; // string
+  }
+}
+// For custom actions pass your own map:
+interface MyActions { SCAN_QR: { camera: string } }
+if (isAction<MyActions, "SCAN_QR">(action, "SCAN_QR")) action.data.camera;
+```
+
+## Extensions
+
+Extensions add data while instructions are generated. Their output lands under `extensions[<name>]` so extensions cannot overwrite each other or the core data.
+
+```ts
+import { defineExtension, buildInstructions, getExtensionOutput } from "routegraph";
+
+const narration = defineExtension({
+  name: "narration",
+  variables: { style: "concise" },
+  run({ action, from, to, variables }) {
+    return { text: `${variables.style}: tap ${String(action.data.target)} to reach ${to.name}.` };
+  },
+});
+
+const out = await buildInstructions(path, { extensions: [narration] });
+getExtensionOutput(out.steps[0]!.actions[0]!, narration)?.text; // typed as string
+```
+
+The inline form is equivalent and convenient for one off use: `extensions: { narration: { variables: {...}, run(ctx) {...} } }`.
+
+Hooks, in the order they run:
+
+| Hook | Runs | Context highlights |
+| --- | --- | --- |
+| `run` or `action` | once per action | `action`, `actionIndex`, `step`, `edge`, `from`, `to` |
+| `step` | once per transition, after its actions | `step` including action output |
+| `route` | once, after everything else | `instructions` including all earlier output |
+
+For each step the order is: every extension's action hooks for each action, then every extension's step hooks, then after all steps the route hooks. Within a level, extensions run in the order you gave, adjusted only by `dependsOn`.
+
+Semantics:
+
+- Hooks see variables after substitution, so they get usable values.
+- Context objects are deep frozen copies. Mutating them throws, and a hook cannot change the path, the cost, or other extensions' output. Return data instead.
+- Hooks can be sync or async. Use `buildInstructions` for async hooks and `buildInstructionsSync` when all hooks are sync.
+- `ctx.variables` is the extension's own configuration, optionally overridden per build with `extensionVariables: { narration: { style: "verbose" } }`.
+- Extensions do not see each other by default. Declare `dependsOn: ["other"]` to read that extension's output for the same node from `ctx.outputs`. Missing and circular dependencies are errors.
+- Return `undefined` to attach nothing. Anything else must be JSON compatible (finite numbers, plain objects and arrays, no cycles), otherwise an `ExtensionError` is raised.
+- `validate(output)` can return `true` or a string describing the problem.
+- Errors throw an `ExtensionError` by default. With `onError: "collect"` the failing output is skipped and a warning is added to `instructions.warnings`.
+- Extensions are trusted local code. They are passed in from your program and can never be loaded from a `.navgraph` file.
+
+Typing note: `defineExtension` infers the output type from what your hooks return. If different hooks return different shapes, give the output type explicitly, for example `defineExtension<"summary", JsonObject>({...})`.
+
+## Runtime (optional)
+
+Core routegraph never executes anything. If you want to run instructions, register handlers explicitly:
+
+```ts
+import { createRuntime } from "routegraph";
+
+const runtime = createRuntime<{ driver: MyDriver }>({
+  TAP: ({ action, context }) => context.driver.tap(String(action.data.target)),
+  WAIT: { handler: ({ action }) => waitFor(action.data), options: { timeoutMs: 8000, retries: 1 } },
+});
+
+const result = await runtime.execute(instructions, { context: { driver }, continueOnError: false });
+// or, with only synchronous handlers:
+runtime.executeSync(instructions, { context: { driver } });
+```
+
+Handlers get the validated, resolved payload plus your context. Options include `timeoutMs`, `retries`, `retryDelayMs`, `skipUnhandled`, `continueOnError`, `signal` (an `AbortSignal`), and an `onAction` callback. A global registry is available through `registerActionHandler` for apps that prefer one.
+
+## Typing and extensibility
+
+- `indexTree<"home" | "cart">(...)` gives typed `tree.home` and `tree.cart` shortcuts. Without the type argument use `tree.screen("home")`, or `tree.screens.get("home")`, which is the authoritative lookup. Shortcuts exist only for ids that are valid JavaScript identifiers and do not collide with tree members, and they are not enumerable.
+- Everything public is exported as a type: `Graph`, `Edge`, `Screen`, `Path`, `Instructions`, `PathfindingAlgorithm`, `ConditionOperator`, `Extension`, `ActionHandler`, and more.
+- Extension points: custom schemas, schema registry, custom algorithms, heuristics, cost functions, edge filters, condition operators, instruction extensions, action handlers, a pluggable `readFile`.
+
+## Decisions made for the open questions
+
+The design document left a number of questions open. These are the choices this release makes.
+
+1. Grammar: documented above. JSON blocks may span lines. Strings use JSON escapes.
+2. `END` is optional. Nothing may follow it.
+3. `APP` is optional.
+4. Variable types: `string`, `number`, `boolean`, `null`, `object`, `array`, `any`.
+5. Conditions: the grammar above. Unknown values are falsy unless strict mode is on.
+6. Edge cost defaults to 1, configurable with `defaultCost`.
+7. No route: `calculatePath` throws `NoPathError`, `tryCalculatePath` returns a result object.
+8. `buildInstructions` is always async. `buildInstructionsSync` is the synchronous twin.
+9. Schemas use a small JSON format modelled on a subset of JSON Schema, plus a real JSON Schema for validating the schema files themselves.
+10. Extension dependencies are explicit through `dependsOn`.
+11. The action runtime ships in the same package but is opt-in and tree shakeable.
+12. Imports between graph files are not part of v1. Merge text before indexing if you need it.
+13. `tree.<id>` shortcuts are defined only for safe identifiers.
+14. Unresolved payloads are available through `includeUnresolved`.
+
+## Development
+
+```sh
+npm install
+npm run typecheck
+npm test
+npm run build
+```
+
+`npm publish` runs the typecheck, tests, and build first through `prepublishOnly`. The included GitHub workflows run CI on Node 18, 20, and 22 and publish to npm with provenance when a release is created (add an `NPM_TOKEN` secret).
+
+## License
+
+MIT