From 4eb290b0dd1d209e61da0c6a5577f0543f5432ca Mon Sep 17 00:00:00 2001
From: kyscott18 <43524469+kyscott18@users.noreply.github.com>
Date: Tue, 13 Oct 2026 19:51:28 +0000
Subject: [PATCH] chore: remove AGENTS.md files

---
 AGENTS.md                           | 117 ---------------------------
 apps/order-book/AGENTS.md           |  56 -------------
 apps/order-book/contracts/AGENTS.md |  19 -----
 apps/order-book/scripts/AGENTS.md   |  13 ---
 packages/storage-layout/AGENTS.md   |  73 -----------------
 packages/typewriter/AGENTS.md       | 118 ----------------------------
 6 files changed, 396 deletions(-)
 delete mode 100644 AGENTS.md
 delete mode 100644 apps/order-book/AGENTS.md
 delete mode 100644 apps/order-book/contracts/AGENTS.md
 delete mode 100644 apps/order-book/scripts/AGENTS.md
 delete mode 100644 packages/storage-layout/AGENTS.md
 delete mode 100644 packages/typewriter/AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
deleted file mode 100644
index d758d1a2..00000000
--- a/AGENTS.md
+++ /dev/null
@@ -1,117 +0,0 @@
-# AGENTS.md
-
-Repo-wide guidance. Per-app specifics live in each workspace's own `AGENTS.md` / `README.md`.
-
-## Layout
-
-A Bun monorepo. Apps live under `apps/*`; reusable framework code lives under `packages/*`. The current state is one app (`order-book-*`) plus a framework package (`typewriter`) being extracted from it. The repo root also defines a Cargo workspace (`Cargo.toml`) whose only member is the Rust crate at `packages/typewriter-evm`.
-
-## Docs
-
-`README.md` and `packages/typewriter/README.md` are copies of each other. Keep them in sync when editing either file.
-
-## Common commands
-
-Run from the repo root:
-
-```bash
-bun install
-bun run lint        # biome + per-workspace lint
-bun run typecheck   # tsc --noEmit per workspace
-bun run build       # per-workspace builds
-```
-
-The root `typecheck` script is intentionally sequential instead of
-`bun run --filter '*' typecheck`: Bun can run filtered workspace scripts in
-parallel, which makes dependent workspaces typecheck `storage-layout` at the
-same time and can create enough TypeScript memory pressure to crash small remote
-instances. Keep it one workspace at a time unless the type setup changes to use
-project references or declaration boundaries.
-
-## Before declaring work complete
-
-Run all three checks at the repo root before saying a task is done — not just one:
-
-- `bun run lint` — Biome formatter + linter (catches formatting drift, unused vars, style violations)
-- `bun run typecheck` — `tsc --noEmit` per workspace
-- `bun run test` — per-workspace test scripts
-
-For type-only changes (`.d.ts`, type tests, or purely compile-time inference
-work), `bun run test` is not required when `bun run lint` and
-`bun run typecheck` pass. Say explicitly that tests were skipped because the
-change is type-only.
-
-`bun run typecheck` alone is not sufficient: Biome catches things TS doesn't (formatting, unused imports under different rules), and TS catches things Biome doesn't (`noUnusedLocals`, type narrowing). Pre-existing failures unrelated to your changes are fine to flag and skip past, but don't introduce new ones.
-
-## Bun-first conventions
-
-This is a Bun project; default to Bun APIs over Node/npm equivalents.
-
-- Run files with `bun <file>`, not `node` or `ts-node`.
-- `bun install` / `bun run <script>` / `bunx <pkg>` instead of npm/yarn/pnpm/npx.
-- `bun test` — not jest/vitest. Tests use `import { test, expect } from "bun:test"`.
-- `bun build` — not webpack/esbuild.
-- Don't add `dotenv`; Bun loads `.env` automatically.
-- Server: `Bun.serve()`. Don't add `express`.
-- DB: `Bun.SQL` for Postgres (wired into Drizzle). Don't add `pg` or `postgres.js`.
-- Files: prefer `Bun.file` over `node:fs`. Shell: `Bun.$` over `execa`.
-- WebSockets: built-in `WebSocket`, no `ws`.
-- Frontend: HTML imports with `Bun.serve()` (no Vite). `<script type="module" src="./frontend.tsx">` and `import './index.css'` work directly.
-
-## Crypto libraries
-
-Prefer **ox** over **viem** wherever both work. ox is lower-level and lighter-weight — primitives only (`Hex`, `Address`, `Secp256k1`, `Signature`, `AbiParameters`, etc.). viem stays where an actual RPC client is needed (`createPublicClient`, `createWalletClient`, `sendRawTransactionSync`). New framework or SDK code should target ox; viem belongs at the app's runtime edge.
-
-## Shared dependency versions
-
-Cross-workspace dependency versions live in the root `package.json`'s `"catalog"` field. Workspaces reference them as `"<pkg>": "catalog:"`. Add a package to the catalog when it's used in 2+ workspaces; don't move things in speculatively. `@types/bun` is declared once at the root only — it hoists to the root `node_modules` and TS finds it from any workspace.
-
-## Adding new dependencies
-
-Don't add a new dependency unless explicitly directed. Before reaching for `bun add`, check whether the runtime, Bun's stdlib, or an already-installed package covers the need (e.g. Bun ships `expectTypeOf` in `bun:test`, so `expect-type` isn't needed). If a new dependency seems warranted, ask first.
-
-Pin exact versions for security — no `^` or `~` ranges. `bun add` defaults to a caret range; strip it after install. The lockfile gives reproducibility, but exact versions in `package.json` make supply-chain review easier and prevent silent minor-version drift on fresh installs that race the lockfile.
-
-## Tests
-
-Run workspace-local test suites from that workspace's directory, or through the
-workspace script (`bun run --filter <workspace> test`). Do **not** run tests from
-the repo root by passing a workspace path (for example, avoid
-`bun test packages/typewriter`): Bun may skip the workspace's local `bunfig.toml`, so
-preloaded setup hooks can run with the wrong lifecycle.
-
-For the whole repo, run `bun run test` from the root, not raw `bun test`. The
-root script dispatches each workspace's own `test` script, preserving workspace
-timeouts and preload/setup behavior; raw root `bun test` discovers tests directly
-and can produce misleading setup failures.
-
-Prefer `.toMatchInlineSnapshot()` over hand-written equality assertions when the expected value is non-trivial. Snapshots are easier to read, easier to update, and surface unintended diffs faster than `.toEqual({...})` against a hand-maintained literal.
-
-When a suite-wide test run reports many failures, especially with `beforeEach`/`afterEach` timeouts or "Unhandled error between tests", run a single test in isolation to see the actual error. Cascading setup failures hide the root cause — `bun test -t "name fragment"` (or `bun test path/to/file.test.ts`) cuts through the noise and surfaces the real exception in the first failing test.
-
-If a suite-wide test run hits two timeout failures, cancel the process early; the rest are likely to timeout for the same reason.
-
-## Lint / format
-
-Biome 2.x (`biome.json`) for JS/TS/CSS; `forge fmt` for Solidity. `noNonNullAssertion` is off — `!` is allowed.
-
-## Foundry
-
-Use the Monad version of Foundry for all `forge` and `anvil` commands. The contracts and tests rely on Monad-specific gas rules and Monad/RIP-7212 behavior, including the P-256 precompile at `address(0x100)`, so upstream stable Foundry is not sufficient.
-
-Prefer specific validity checks over truthy/falsy shortcuts: `if (mutation === undefined)` over `if (!mutation)`, `if (xs.length === 0)` over `if (!xs.length)`. `!x` collapses undefined / null / 0 / "" / false / NaN into one branch — for domain values that could legitimately be `0` or `""` it silently wrong-paths, and even when those cases can't occur the explicit form makes the intended invariant readable. Reach for `!x` only on actual booleans.
-
-## Gotcha: `bun install` blocked by `minimum-release-age`
-
-The repo's `bunfig.toml` enforces `minimumReleaseAge = 2419200` (28 days) as a supply-chain defense — bun refuses any version younger than that. If `bun.lock` or a `package.json` constraint pins a too-recent version, install fails with "No version matching X found / blocked by minimum-release-age". Fix: `bun remove <pkg> && bun add <pkg>` — `bun add` walks back to find a version that satisfies the constraint *and* clears the age gate.
-
-## Gotcha: `bun.lock` merge conflicts
-
-Don't hand-resolve `bun.lock` during a merge or rebase. The file is generated, internally consistent in ways that aren't obvious from the diff, and `<<<<<<< / >>>>>>>` markers will leave it parse-broken. Resolve the `package.json` conflicts manually, then run `bun install` — bun will regenerate `bun.lock` from the merged `package.json` state. If a leftover conflict marker keeps bun from parsing the file at all, `rm bun.lock && bun install` to rebuild from scratch.
-
-## Available CLIs
-
-Two authenticated CLIs are expected. Validate before relying on them; if a check fails, **stop and ask the user to fix it** rather than working around it.
-
-- **`gh`** — GitHub CLI. Repo is `monad-exp/order-book`. Validate with `gh auth status` (needs `repo`, `workflow`, `read:org` scopes). If not logged in, ask the user to install (`brew install gh` / [cli.github.com](https://cli.github.com/)) and run `gh auth login`. If authed but lacking org access, ask for a `monad-exp` invite.
-- **`railway`** — Railway CLI. Repo should be linked to the `order book` project (`production`) under the `MF Experimental` team. Link config lives in `~/.railway/config.json`. **No default service is set** — always pass `--service <name>` (e.g. `railway logs --service backend`). Deploys go through the Railway GitHub App on pushes to `main`, so prefer read-only commands. Validate with `railway whoami` and `railway status`. If `railway status` reports no linked project, ask the user to run `railway link` from the repo root (interactive). If they can't see the project, they likely need an invite to the `MF Experimental` team.
diff --git a/apps/order-book/AGENTS.md b/apps/order-book/AGENTS.md
deleted file mode 100644
index 15c3a73e..00000000
--- a/apps/order-book/AGENTS.md
+++ /dev/null
@@ -1,56 +0,0 @@
-# AGENTS.md - order-book
-
-Order book implementation using `typewriter` as the runtime. The app owns order-book domain logic, persistence hooks, HTTP routes, frontend serving, scripts, SDK helpers, and signature/account verification. Do not change `packages/typewriter` from this workspace.
-
-## Layout
-
-- `src/` — app state model, mutation config, HTTP routes, persistence hooks, constants, signature helpers.
-- `frontend/` — React UI served by `src/index.ts` with Bun HTML imports.
-- `sdk/` — shared order-book constants, EIP-712 types, ABI, and math helpers. It is folded into this package; the `order-book-sdk` import is a TS path alias.
-- `scripts/` — participant scripts that drive the app HTTP API.
-- `contracts/` — Typewriter-backed `OrderBook.sol`, deploy script, contract docs, and active Foundry tests.
-- `docs/` — migration notes and app-specific context not covered by `packages/typewriter` docs.
-
-## Dev Loop
-
-Three terminals:
-
-```bash
-anvil --network monad --block-time 0.3
-cd apps/order-book && cp .env.example.local .env && bun run deploy
-cd apps/order-book && cp .env.example.local .env && bun dev
-```
-
-Open <http://localhost:3000>. The same process serves the API, frontend, and Typewriter runtime.
-
-## Tests
-
-Run from `apps/order-book` unless noted:
-
-```bash
-bun test
-DATABASE_URL=postgresql://ubuntu@localhost:5432/postgres bun test
-forge test --root contracts
-forge test --root contracts --match-test testFillsAtUniformPrice
-```
-
-From the repo root, prefer workspace scripts:
-
-```bash
-bun run --filter order-book typecheck
-bun run --filter order-book test
-```
-
-## App Model
-
-Accounts are 32-byte ids, not EOAs. Each account holds root/delegate keys with permission masks and expiries. Frontend sign-in uses WebAuthn passkeys and ephemeral P-256 session keys stored in IndexedDB via `frontend/lib/sessionKey*.ts`. EIP-712 typed-data signing is in `frontend/lib/eip712.ts`; mutation types live in `sdk/index.ts` as `EIP712_TYPES`. Nonces are parallel and keyed by `(account, keyIndex)` so concurrent mutations do not serialize.
-
-Mutation types are `initialize`, `authorize`, `revoke`, `addInstrument`, `deposit`, `withdrawal`, `limitOrder`, `marketOrder`, and `closeOrder`. Contract/batch sequencing is cancel -> limit -> market with uniform clearing for market orders.
-
-Frontend uses `Bun.serve` + HTML imports, no Vite. Entry is `frontend/index.html` mounted at `/*`. React 19, TanStack Query, Tailwind v4 via `bun-plugin-tailwind` in `bunfig.toml`. The `/about` page is the canonical architecture walkthrough; edit it rather than creating parallel user-facing prose about lifecycle, force-exit, or gas figures.
-
-## Gotchas
-
-- A new mutation type touches `contracts/src/OrderBook.sol`, EIP-712 types in `sdk/index.ts`, mutation config in `src/app.ts` (`order_book_mutations`), HTTP/read model wiring in `src/index.ts`, and frontend builders/renderers. Typewriter generates the per-mutation persistence schema from `order_book_mutations`; the app accesses it through `app.schema`.
-- Keep contract changes in `contracts/src` source-compatible with active tests in `contracts/test` where possible.
-- Do not reintroduce app-specific code into `packages/typewriter`.
diff --git a/apps/order-book/contracts/AGENTS.md b/apps/order-book/contracts/AGENTS.md
deleted file mode 100644
index 7d95afe0..00000000
--- a/apps/order-book/contracts/AGENTS.md
+++ /dev/null
@@ -1,19 +0,0 @@
-# AGENTS.md — order-book/contracts
-
-Solidity (Foundry). Typewriter-backed `OrderBook.sol` plus account primitives imported from `packages/typewriter`. Batched execution via a privileged scheduler, EIP-712 signed mutations, P-256/WebAuthn/secp256k1 keys with permission masks, parallel-nonce account model, and a force-exit queue so users can bypass the scheduler.
-
-## Foundry nightly required
-
-`foundryup --install nightly`. The OrderBook uses the P-256 precompile at `address(0x100)` (RIP-7212), which stable Foundry (1.5.1) does not include. Both `forge test` and `anvil` need the nightly build.
-
-## Tests
-
-```bash
-forge test
-forge test --match-test testFillsAtUniformPrice
-forge test -vvv                                   # traces on failure
-```
-
-Run package scripts from `apps/order-book`: `bun run contracts:build`, `bun run contracts:lint`, and `bun run deploy`.
-
-The pre-Typewriter contract tests have been reconciled into `test/`; keep new contract behavior covered there.
diff --git a/apps/order-book/scripts/AGENTS.md b/apps/order-book/scripts/AGENTS.md
deleted file mode 100644
index 0c6ff325..00000000
--- a/apps/order-book/scripts/AGENTS.md
+++ /dev/null
@@ -1,13 +0,0 @@
-# AGENTS.md — order-book/scripts
-
-TS scripts emulating market participants (limit, market, market-maker, retail, arbitrage, gas). Drives the order-book HTTP API.
-
-## Running
-
-From `apps/order-book`:
-
-```bash
-bun scripts/add-instrument.ts                                                   # run first
-PRICE=2400 SIDE=buy QUANTITY=1 INSTRUMENT=GOLD/USD bun scripts/limit-order.ts
-SIDE=buy QUANTITY=0.5 INSTRUMENT=GOLD/USD bun scripts/market-order.ts
-```
diff --git a/packages/storage-layout/AGENTS.md b/packages/storage-layout/AGENTS.md
deleted file mode 100644
index 1dba7d2a..00000000
--- a/packages/storage-layout/AGENTS.md
+++ /dev/null
@@ -1,73 +0,0 @@
-# AGENTS.md - storage-layout
-
-`storage-layout` turns Solidity compiler `storageLayout` JSON into decoded storage values, typed storage selectors, and a lazy object view of contract storage.
-
-The public API is `decodeStorageVariable`, `createStorageView`, the viem actions (`readStorageVariable`, `readStorageVariables`), the enumeration helpers (`enumerateMappingKeys`, `getDynamicArrayLength`), and the types exported from `src/index.ts`. Keep the export surface small: export a helper only when a concrete caller needs it.
-
-## Core Model
-
-The public abstraction is a storage variable selector string:
-
-- `totalSupply`
-- `metadata.lastUpdate`
-- `balances[0x1234]`
-- `accounts[0xabcd].orders[3].price`
-
-Path syntax is syntactic only. Whether `[3]` is an array index or mapping key is determined by the current Solidity storage type during resolution.
-
-## Boundaries
-
-The selector string is the only external path format. Internally a path exists only as a resolved `StorageLocation` (`{ type, slot, offset, selector }`); there is no parsed, unresolved path type.
-
-- `storage-path.ts` owns selector syntax: the lexing primitives (`readIdentifier`, `readSubscript`, `parseSubscript`), subscript formatting, and the type-level `ParseStoragePath`.
-- `storage-layout.ts` owns the compiler JSON types and resolution. `resolveRoot`, `resolveField`, and `resolveSubscript` each step one level from a parent location, and are the only code that hashes (one keccak256 per mapping key or dynamic array element). `resolveStoragePath` lexes a selector and folds those steps.
-- Callers resolve once and pass the location on: the view keeps a location per node and steps from it, and `decodeStorageLocation` / `decodeDynamicArrayLength` decode from a location without resolving again. Keep it that way; a cache belongs in the step functions, not in callers.
-- `types.ts` owns the type-level API: selector extraction and Solidity-to-TypeScript value types.
-- `solidity-encoding.ts` owns low-level Solidity rules shared by the modules above: value-type classification (`parseValueType`), the mapping-key codec (`encodeMappingKey` / `decodeMappingKey`, which must stay exact inverses), and slot math.
-- `decodeStorageVariable.ts` owns leaf decoding, including the `bytes`/`string` length rules (`MAX_BYTES_LENGTH`). The view and the viem actions get data slots from `bytesDataSlots`, which uses the same rules, so a check added there covers every API.
-- `account-storage.ts` reads slot words from `AccountStorage` with keys in any hex form, and owns the slot getter types and `fetchStorage` (dedupe, call the getter, check one value per slot) that the view and the viem actions share. Sync and async getters are handled with an explicit `instanceof Promise` branch where needed, not a generic continuation helper.
-- `readStorageVariable.ts` / `readStorageVariables.ts` validate selectors before any request, read root slots, then read `bytes`/`string` data slots. They assume that all requests see the same state, by choice for now: they do not detect a new block between requests.
-- Concrete leaf validation belongs with the function that needs a leaf (for example `decodeStorageVariable`), not path parsing or resolution.
-
-## Mapping Limitation
-
-`storageLayout + slot => variable` is not generally possible.
-
-Mapping slots hash keys into one-way storage locations, so mapping keys cannot be recovered from raw slots. Keys are known only from keccak256 preimages that the caller captured during execution (`enumerateMappingKeys`, and enumeration in `createStorageView`). Do not try to recover keys from slots or storage values alone.
-
-Two known limits, documented in the README and not handled for now:
-
-- With the optimizer on, solc hashes a constant key (`m[1]`, `roles[ADMIN]`) at compile time. No `KECCAK256` step runs, so a trace has no preimage for that key.
-- `bytes`/`string` mapping keys are not supported. Their preimage is the unpadded key data followed by the slot, so it does not fit the 64-byte model.
-
-Dynamic array `.length` is different: it lives at the array root slot and can be read directly.
-
-## Testing
-
-- Run tests with `bun run test` from this directory, not raw `bun test`: the script runs `contracts:build` first. Foundry (`forge`, `anvil`) must be on `PATH`.
-- `bun run contracts:build` runs `forge build --root test/contracts` and `scripts/generateTypedArtifacts.ts`, which writes the gitignored `test/contracts/generated.ts` (ABI, bytecode, and solc `storageLayout` as `as const` literals). `typecheck` and `build` also run it, because tests import that file.
-- `test/anvil.ts` follows viem's test setup: a prool proxy server with one anvil instance per pool id. `test/setup.ts` (preloaded by `bunfig.toml`) starts one proxy per test process on a free port, so `bun test --parallel` is safe. Anvil starts lazily, on the first RPC request. `stepsTracing` is on so `debug_traceTransaction` returns struct logs with memory.
-- `src/ground-truth.test.ts` is the source of truth for encoding rules. It compares every decoded value with the Solidity getter of `StorageFixture.sol`, and mapping enumeration with preimages from the `populate()` trace. When you add support for a Solidity type, add a variable of that type to `StorageFixture.sol`, write it in `populate()`, and compare it with its getter there. Hand-written layouts in `test/utils.ts` are for focused unit cases only.
-- Prefer one shared fixture contract over many small ones: solc assigns the slots, so a new variable does not need test updates elsewhere.
-
-## Type Performance
-
-The selector types expand every path of a layout, so careless generics make `tsc` very slow. A full package typecheck is about 0.3M instantiations and under 1 s. If it grows by a large amount, find the cause with `tsc --extendedDiagnostics` and `--generateTrace`. Keep these rules:
-
-- In a public generic function, pass a generic selector to a `string` parameter as `variable as unknown as string`, and cast results the same way. Relating `variable extends ConcreteStorageVariable<layout>` to `string` directly makes TypeScript expand the selector types for a loose layout, which costs seconds per call site.
-- Type aliases that take a selector (`StorageVariableToPrimitiveType`, `MappingEntryVariable`, the read parameter types) leave it unconstrained and narrow with `variable extends string` inside, for the same reason.
-- Wrap computed public return types in `NoInfer<...>`. Without it, a call nested in another generic call (`expect(decodeStorageVariable(...))`, `Promise.all([...])`) makes TypeScript walk the return type before it infers the selector: millions of instantiations per call site.
-
-## Performance Notes
-
-- `bun run benchmark` (`scripts/benchmark.ts`) replays the read patterns of `apps/order-book` (linked-list price walks, depth, order and credential scans, mapping enumeration) against `test/contracts/src/OrderBookFixture.sol`, with a global `preimages` set like the typewriter runtime's. It reports time, getter calls, and slots read per call. Run it before and after a performance change, and profile one case with `BENCH_CASE=<name> bun --cpu-prof-md scripts/benchmark.ts`.
-- The storage view is deliberately stateless: no cache and no key index. Each leaf access issues one getter call. `preimages` is a `Set` of lowercase hex, so a membership check is one lookup, and mapping enumeration reads the set once. `Object.keys` checks membership once per listed key, so it costs one pass plus one lookup per key. Do not change `hasMappingKey` back to a scan: that makes `Object.keys` quadratic.
-- A known but unimplemented improvement is to coalesce parallel async leaf reads, such as `Promise.all(...)`, into a single deduped slot request.
-
-## Design Constraints
-
-- Keep the package generic Solidity/storage logic; do not include app-specific vocabulary.
-- Prefer focused vertical slices with runtime and type tests.
-- Preserve loud failures for unsupported or non-concrete decode paths.
-- Use `abitype` for Solidity-to-TypeScript primitive mapping where appropriate, but keep storage-specific handling for packing, signed integers, mappings, arrays, structs, and `bytes`/`string`.
-- Prefer Bun and `ox` in `src/`. `viem` is a peer dependency (`^2.56.9`, the first version with `getStorageValues`) used only by the viem actions; keep it out of the decoders. `prool` is a dev dependency for the anvil tests.
diff --git a/packages/typewriter/AGENTS.md b/packages/typewriter/AGENTS.md
deleted file mode 100644
index 1d26e53b..00000000
--- a/packages/typewriter/AGENTS.md
+++ /dev/null
@@ -1,118 +0,0 @@
-# AGENTS.md — typewriter
-
-Instructions for agents working on `packages/typewriter`.
-
-## What this package is
-
-`typewriter` ("framework for crypto apps") is a prescriptive framework, not a generic engine that adapts to arbitrary contracts. It prescribes the shape of the contracts that use it — execution surface, storage layout conventions, event conventions — so that the runtime, decode layer, and tooling above it can be sharp and opinionated rather than defensive. Conformance is the API.
-
-## Motivations
-
-Building a production crypto app today means assembling a stack of disconnected systems — sequencing, account abstraction, settlement, layer 2 scaling, indexing — and carrying the hard-won knowledge of how they fit together. The result is fragmented even when it works, and the assembly is the reason apps ship with a less ambitious product than they originally planned.
-
-typewriter is a full-stack framework that unifies that stack behind a single opinionated runtime — one that abstracts transaction submission the way React's runtime abstracted DOM rendering. Developers describe their app's state and the mutations that change it; the runtime owns ordering, confirmation, and settlement. Applications are the fundamental unit to optimize for: they define the requirements that everything below them — sequencing, accounts, confirmations, settlement — has to answer to.
-
-## Beliefs
-
-What we believe that makes typewriter different.
-
-- **Compete on technical merit, not ideology.** The next generation of crypto apps will be defined by what works, not by adherence to existing camps.
-- **Blockchains are the database, not the backend.** They occupy the persistence layer of the stack; everything else — sequencing, validation, application logic — lives above them.
-- **Write logic once.** Contract and backend shouldn't duplicate the same logic in two places. Pick one home for each piece and let the other defer to it.
-- **A handful of apps, not contracts for everyone.** Only a few crypto apps of real consequence will be built. typewriter optimizes for taking the best teams from idea to production as fast as possible — and for letting those apps show what a chain can do beyond "EVM, but faster" — rather than putting contract authorship in everyone's hands.
-- **Focus compounds.** Outcomes follow a power law, so doubling down on the core idea beats spreading thin across adjacent ones. Every new surface dilutes the one that matters.
-- **Pragmatism over assembly.** Everything typewriter enables is technically possible today by stitching together L2 rollups, account abstraction providers, and other middleware. typewriter delivers the same results without the cruft.
-
-## Feedback loops
-
-High-level signals for whether typewriter is on the right track. None are precisely measurable; they're the lenses to evaluate work through.
-
-- **AI legibility.** Can an agent read this codebase and understand the motivations and decision-making behind it well enough to make good calls? If an agent has to guess at intent, the docs or the code are failing.
-- **Focus.** Are the ideas distilled to their simplest possible form? Every added concept dilutes the surface; the bar for introducing one should be high.
-- **Developer experience.** Deployment, environment setup, and modularity should feel simple and composable — small pieces that snap together, with the developer ultimately in control.
-- **Performance.** Transaction latency and gas costs. The ceiling typewriter raises is partly a performance ceiling — slow or expensive paths cap what apps can be.
-
-## Tests
-
-`bunfig.toml` preloads `test/setup.ts`, which compiles the test contracts (`test/contracts/`), boots anvil via `prool` on a free random port, creates an isolated Postgres database per test from `DATABASE_URL`, and registers a global `beforeEach` that snapshot-reverts chain state between tests. Each test deploys its own contracts via `deployCounter` / `deployHarness` from `test/utils.ts` — there's no shared deployment to remember.
-
-Run typewriter tests from `packages/typewriter` (`bun test`) or through the workspace script
-(`bun run --filter typewriter test`). Do not run `bun test packages/typewriter` from the repo
-root: that does not load `packages/typewriter/bunfig.toml`, so the preload hooks can
-tear down Anvil/Postgres before later files run.
-
-Run the native account Solidity suite with `forge test --root test/contracts`.
-The fixture project's `test` path points at `src/Typewriter.t.sol`.
-
-If broad test runs fail during setup, run `DATABASE_URL=postgresql://ubuntu@localhost:5432/postgres bun test packages/typewriter/test/setup.test.ts` first to isolate Anvil/Postgres environment failures before debugging app logic.
-
-## Roadmap
-
-The frame: every change is purpose-built for making it easier to build apps with typewriter, or for making the apps built better. Apps come first; the framework follows them. The goal is to keep the consuming apps (`apps/order-book`, and the minimal `apps/token`) demo-grade while extracting reusable framework seams into typewriter.
-
-### Next Step
-
-Add more testing around Solidity parsing. The current implementation can import an existing Solidity entrypoint, run Forge, read artifacts/ASTs, and derive runtime metadata that used to be copied into TypeScript by hand. Before expanding the surface, tighten coverage around the supported contract shape and the failure modes developers will actually hit: invalid/missing `Mutation` enums, unsupported `dispatch`/`abi.decode` forms, nested struct params, signature struct extraction, storage-layout flattening, multiple candidate contracts, and developer-facing parser errors.
-
-The larger follow-on items are server-managed deployment and Solidity codegen. Deployment should bind runtime startup to a persisted artifact/deployed-bytecode match instead of copied addresses. Codegen should remove the remaining hand-authored protocol boilerplate (`execute`, `enqueue`, `forceExecute`, dispatch, scheduler access control, force-inclusion queue/events) once the parsed contract conventions are proven by tests.
-
-### Lanes
-
-The work catalog. Non-sequenced — items in different lanes can run in parallel.
-
-**1. Missing implementation.** Things that are part of the framework but aren't there yet.
-- Reorg recovery beyond detection/fatal runtime failure
-- Signed receipts / client-side equivocation proving
-- Signature validation at execute time. EIP-712, native signature verification, and the wire-format codec are in place; the unresolved question is whether typewriter should validate signatures during `execute()` admission, instead of waiting until batch-submission time or on-chain execution.
-
-**2. Production readiness.** Hardening for running real apps.
-- Shutdown testing (deterministic drain)
-- Scheduler KMS / better account system
-
-**3. Developer experience.** Usability — make the framework feel small and composable.
-- State sync (granular slot subscriptions; falls out of revm)
-- More Solidity parsing test coverage and clearer convention-focused parser errors
-- AST parsing for additional conformance/runtime values, including EIP-712 domain extraction
-- Zod schemas for HTTP endpoint enforcement
-- Automatic deployment management (no copying addresses into env vars)
-- CLI scaffolding (`typewriter dev` with anvil + fixture contract)
-
-### Initiatives
-
-Multi-week projects that span lanes. Each has its own internal sequence.
-
-**Account/signature boundary.** typewriter owns the account registry, credential
-lifecycle, packed parallel nonces, expirations, mutation permission bitsets, and
-the fixed EIP-712 `Authorization` envelope. It supports P-256, WebAuthn-P256,
-and secp256k1. Apps receive the authenticated `bytes32 accountID` in their
-execution callback instead of implementing account policy.
-
-**Server-managed deployment.** Runtime startup should eventually deploy or load the matching compiled artifact, persist deployment metadata, and verify deployed bytecode against the artifact before starting. This removes copied contract addresses from app env/config and prevents the server from running against stale generated artifacts or stale deployed bytecode.
-
-**Solidity codegen.** Once Solidity parsing is well-tested, generate the typewriter-owned protocol shell instead of requiring apps to hand-author it. The first target is removing dispatch boilerplate: derive mutation tags and params from the parsed contract, generate the `dispatch` branch/`abi.decode` wiring, and keep app contracts focused on business logic. Larger codegen can then absorb `execute`, `enqueue`, `forceExecute`, scheduler access control, force-inclusion queue/events, and server-consumable artifacts.
-
-**Scheduler key management.** Today `TypewriterConfig.account: PrivateKeyAccount` is in-process key material — fine for dev, a footgun for production. Three pieces share the same seam (the framework's signing identity): KMS / remote signer support, nonce recovery on conflict, and user-shaped signing on-contract (scheduler key in the same registry as user keys, with rotation/expiry/scopes).
-
-**Equivocation receipts.** Unbuilt. The goal is settled — signed accepted receipts let users prove the scheduler accepted one mutation and settled another — but receipt shape/hashing, observability, proof scope, and signing identity are open (see Open decisions and `PLAN_equivocation.md`).
-
-**Runtime failure policy.** Today submit/watch failures can still kill the runtime fiber after mutations have already been accepted. Define the lifecycle for accepted-but-not-submitted batches: retry forever, mark failed, dead-letter, or emit a recoverable status. Clients need a clear way to observe the outcome.
-
-### Open decisions
-
-Forks that gate sequencing. Listed so they don't get rediscovered every session.
-
-- **Execute-time signature validation.** Should typewriter validate signatures during `execute()` admission, or leave validation to on-chain execution? Execute-time validation gives faster rejection and avoids queueing obviously invalid mutations, but it requires a state-side key lookup seam or a user-supplied validator. Batch/settlement-time validation keeps the framework boundary smaller and user-owned, but invalid signatures can enter the queue and only fail later.
-- **Equivocation receipt observability.** Should settled mutation hashes be exposed through events, storage commitments, decoded calldata, or app-owned HTTP routes? This determines how clients/watchers compare accepted receipts to chain reality.
-- **Equivocation proof scope.** Should typewriter stop at client-side/social proof helpers, or add optional onchain proof storage/events for receipt-vs-settlement conflicts?
-- **Server receipt identity.** What key signs accepted receipts, how is that key advertised, rotated, and scoped to an app/deployment?
-- **Onchain-only recovery.** Can typewriter recover entirely from chain data plus contract storage/account roots, treating the database as a rebuildable cache rather than a required recovery source?
-- **revm block context.** Before broadcast, what `block.number` and `block.timestamp` does revm execute against: latest+1, wall-clock values, or scheduler-controlled block context?
-- **revm divergence detection.** Can revm detect onchain/offchain divergence by comparing account roots, or does typewriter need another settlement/reconciliation signal?
-
-## Working in this package
-
-- **Don't add speculative surface.** Every exported type, function, and config field must have a real call site that needs it. If nothing in the order-book app (or another consumer) calls it, delete it. We'll build the surface up one extraction at a time.
-- **Don't write README/doc sections ahead of code.** Document features after they work, not before.
-- **The README is evidence, not argument.** It should describe what typewriter is and does so readers can draw their own conclusions about why it's impactful. Don't editorialize or make the case for the framework in it.
-- **Don't leak order-book vocabulary.** No mention of `instrument`, `order`, `fill`, `tick`, etc. in typewriter code. If a concept feels generic but the only example is order-book, it probably isn't generic yet.
-- **Prefer ox over viem.** See root `AGENTS.md`.