wao 0.40.0 → 0.40.2

package/cjs/workspace/docs/wao-sdk.md

@@ -100,7 +100,7 @@ const { mid, res, err, out } = await ao.res({
 Paginated results for a process.
 
 ```js
-const { err, out, res, next } = await ao.ress({ pid, limit: 10, asc: true, cursor: null })
+const { err, out, res, next } = await ao.ress({ pid, limit: 10, asc: true, from: null })
 const page2 = next ? await next() : null
 ```
 

package/cjs/workspace/package.json

@@ -13,6 +13,6 @@
   },
   "dependencies": {
     "hbsig": "0.3.0",
-    "wao": "0.40.0"
+    "wao": "0.40.2"
   }
 }

package/esm/ao.js

@@ -793,7 +793,7 @@ class AO {
     return { res, err, out }
   }
 
-  async ress({ pid, limit, asc, cursor }) {
+  async ress({ pid, limit, asc, from }) {
     let err = null
     let msgs = null
     let next = null
@@ -801,9 +801,9 @@ class AO {
     try {
       let sort = asc ? "ASC" : "DESC"
       if (this.hb) {
-        res = await this.hb.results({ process: pid, limit, sort, from: cursor })
+        res = await this.hb.results({ process: pid, limit, sort, from })
       } else {
-        res = await this.results({ process: pid, limit, sort, from: cursor })
+        res = await this.results({ process: pid, limit, sort, from })
       }
       if (!res.edges) return null
       msgs = map(v => ({ cursor: v.cursor, ...v.node }))(res.edges)

package/esm/create.js

@@ -286,6 +286,9 @@ const main = async () => {
       t.fail("Failed to install dependencies")
       return
     }
+    t.sub("root dependencies installed")
+    await exec(`cd "${appdir}/dashboard" && npm install`)
+    t.sub("dashboard dependencies installed")
     t.done()
 
     let hbWarnings = []

package/esm/workspace/.claude/agents/builder.md

@@ -35,8 +35,10 @@ Read these before building:
    - **aos**: Write AOS scripts in `src/` with input validation
    - **aos-test**: Write in-memory tests in `test/`, iterate until `yarn test` passes
    - **aos-integration**: Write HyperBEAM tests, iterate until they pass
-   - **device**: Write Erlang module, compile with `rebar3 as genesis_wasm compile`
-   - **device-test**: Write eunit tests, iterate until `rebar3 eunit` passes
+   - **module-lua**: Write standalone Lua module in `custom-lua/`, no AOS framework
+   - **module-wasm**: Write Rust WASM64 module in `custom-wasm/`, `#![no_std]`
+   - **module-test**: Write HyperBEAM integration tests for custom modules
+   - **device**: Write Erlang device + inline eunit tests in same `.erl` file, compile with `rebar3 as genesis_wasm compile`, iterate until `rebar3 eunit` passes
    - **device-integration**: Write WAO SDK integration tests against running HyperBEAM
    - **frontend**: Write React components with `wao/web`
    - **frontend-test**: Write vitest tests, iterate until they pass

package/esm/workspace/.claude/skills/build/SKILL.md

@@ -31,7 +31,20 @@ Full build orchestrator. Sequences through plan → build → test → validate
 
 ### 1. Check for existing plan (resume support)
 
-Read `plan.md` and `tasks.json` at the project root. If both exist and tasks.json has `"current_step"`, resume from that step — skip to the first task with `"status": "pending"` or `"in_progress"`.
+Read `plan.md` and `tasks.json` at the project root. If both exist and tasks.json has `"current_step"`, resume:
+
+1. Find the first task with `"status": "in_progress"` — resume debugging that task immediately.
+2. If no `in_progress` task, find the first task with `"status": "pending"` — start it.
+3. If ALL tasks are `"done"`, **re-verify every test task** by running its tests:
+   - `aos-test` → `yarn test <files>`
+   - `aos-integration` → `yarn test <files>`
+   - `device` → `cd $HB_DIR && rebar3 eunit --module=<module>`
+   - `device-integration` → `yarn test <files>`
+   - `frontend-test` → `cd frontend && npm run test:unit`
+   - `frontend-integration` → `cd frontend && npm run test:e2e`
+   - `validate` → run all validation gates
+
+   If any test task fails, set that task back to `"in_progress"` in tasks.json and resume debugging it. Do NOT skip over failing tests just because the task was previously marked done.
 
 If no plan exists, proceed to step 2.
 
@@ -75,7 +88,7 @@ Before starting the build loop, check which tracks are selected and verify their
 grep '^CWD=' .env.hyperbeam 2>/dev/null | cut -d= -f2-
 ```
 
-If the plan includes `device`, `device-test`, `device-integration`, `aos-integration`, `module-lua`, `module-wasm`, or `module-test` tasks, verify:
+If the plan includes `device`, `device-integration`, `aos-integration`, `module-lua`, `module-wasm`, or `module-test` tasks, verify:
 
 1. `.env.hyperbeam` exists and has a `CWD` value
 2. The `CWD` path points to a valid HyperBEAM directory (`$CWD/src` exists)
@@ -108,8 +121,7 @@ b. Read the skill file for this task's type and follow its instructions. The map
 | `module-lua` | `.claude/skills/build-module/SKILL.md` |
 | `module-wasm` | `.claude/skills/build-module/SKILL.md` |
 | `module-test` | `.claude/skills/build-module/SKILL.md` |
-| `device` | `.claude/skills/build-device/SKILL.md` |
-| `device-test` | `.claude/skills/build-device/SKILL.md` |
+| `device` | `.claude/skills/build-device/SKILL.md` (eunit tests are inline — same file) |
 | `device-integration` | `.claude/skills/test-device/SKILL.md` |
 | `frontend` | `.claude/skills/build-frontend/SKILL.md` |
 | `frontend-test` | `.claude/skills/build-frontend/SKILL.md` |
@@ -125,12 +137,21 @@ d. After completing, verify the task's `done_when` criteria are met:
 
 e. If the criteria are met, update the task status to `"done"` in `tasks.json`.
 
-f. If a step fails, retry up to 3 times. On each retry:
-   - Read the error output
-   - Fix the code
-   - Re-run
-
-g. If still failing after 3 attempts, **stop and ask the user**: retry, skip, or debug manually?
+f. **If tests fail, keep debugging.** Do not stop. On each iteration:
+   1. Read the full error output — stack traces, assertion messages, log lines
+   2. Identify the root cause (wrong logic, missing handler, bad import, timing issue, etc.)
+   3. Fix the code — not the test, unless the test itself has a bug
+   4. Re-run the failing test file specifically (faster feedback than full suite)
+   5. If the same error persists after 3 different fix attempts, step back:
+      - Re-read the relevant docs (AOS patterns, HyperBEAM device protocol, etc.)
+      - Check if the plan itself has a wrong assumption
+      - Try a completely different approach
+   6. Continue iterating until all tests pass — there is no retry limit
+
+g. Only escalate to the user if:
+   - The failure is environmental (port conflict, missing binary, permissions)
+   - The test requires user input (wallet, external service URL)
+   - You've tried 10+ iterations with no progress on the same error
 
 h. Move to the next task.
 
@@ -161,7 +182,8 @@ Overall: PASS / FAIL
 
 ## Failure handling
 
-- If a skill exits with test failures, read the output, fix the code, and re-run.
+- **Test failures are expected.** The build loop is: write code → run tests → read failures → fix → re-run. This is the core loop — never skip it, never give up early.
+- If a skill exits with test failures, read the full output, diagnose the root cause, fix the code (not the test), and re-run. Keep iterating until 100% pass.
 - If a skill cannot be dispatched (unknown type), skip and warn.
 - If the user interrupts, save current state to tasks.json so the next session can resume.
 
@@ -180,7 +202,7 @@ Never force a task to `done` status with failing tests. The TaskCompleted hook w
 
 ### Build stalls on a single task
 - Check if it's a test failure loop — read the last test output
-- If the same error repeats 3 times, the issue may be in the plan, not the code
+- If the same error persists after 3 different fix attempts, step back and reconsider — the plan may have a wrong assumption
 - Run `/debug` to diagnose port/process/WASM issues
 
 ### Resume doesn't pick up the right task

package/esm/workspace/.claude/skills/build-aos/SKILL.md

@@ -117,4 +117,13 @@ For each test-fix cycle:
 3. Classify: is the bug in source code or test code?
 4. Fix ONE issue per iteration (don't change multiple things at once)
 5. Re-run only the failing test first, then full suite
-6. If the same test fails 3 times with the same error, stop and reconsider the approach — the plan may need updating
+6. If the same error persists after 3 different fix attempts, step back:
+   - Re-read the relevant docs (AOS patterns, Lua conventions, etc.)
+   - Check if the plan itself has a wrong assumption
+   - Try a completely different approach
+7. Continue iterating until all tests pass — there is no retry limit
+
+Only escalate to the user if:
+- The failure is environmental (missing binary, permissions, port conflict)
+- The test requires user input (wallet, external service URL)
+- You've tried 10+ iterations with no progress on the same error

package/esm/workspace/.claude/skills/build-device/SKILL.md

@@ -59,7 +59,7 @@ Do NOT mark the task as done if any prerequisite fails. Set the task status to `
 
 3. Read `docs/hyperbeam-dev.md` for the device protocol (arity/3 functions, state management, auth patterns).
 
-4. **If the task type is `device`** — write the Erlang device:
+4. Write the Erlang device with **inline eunit tests** (HyperBEAM convention — device and tests live in the same file):
 
    Write `$HB_DIR/src/dev_{name}.erl`:
 
@@ -67,6 +67,9 @@ Do NOT mark the task as done if any prerequisite fails. Set the task status to `
    -module(dev_{name}).
    -export([info/3, init/3, compute/3]).
    -include("include/hb.hrl").
+   -ifdef(TEST).
+   -include_lib("eunit/include/eunit.hrl").
+   -endif.
 
    %% Exports: list available keys
    info(_Msg1, _Msg2, Opts) ->
@@ -88,35 +91,37 @@ Do NOT mark the task as done if any prerequisite fails. Set the task status to `
        {ok, Msg1};
    handle_action(_, Msg1, _Msg2, _Opts) ->
        {ok, hb_maps:put(<<"Error">>, <<"Unknown action">>, Msg1)}.
-   ```
-
-   Key patterns:
-   - Use `hb_maps` for state (not plain maps)
-   - Use `hb_private` for secrets
-   - Use `ar_wallet` for auth/signing
-   - Route actions via `hb_ao:get(<<"Action">>, Msg2, Opts)`
-   - Return `{ok, UpdatedMsg}` or `{error, Reason}`
-
-5. **If the task type is `device-test`** — write eunit tests:
-
-   Write `$HB_DIR/test/dev_{name}_tests.erl`:
 
-   ```erlang
-   -module(dev_{name}_tests).
-   -include_lib("eunit/include/eunit.hrl").
+   %%%===================================================================
+   %%% EUnit Tests (inline — HyperBEAM convention)
+   %%%===================================================================
+   -ifdef(TEST).
 
    info_test() ->
-       {ok, Info} = dev_{name}:info(#{}, #{}, #{}),
+       {ok, Info} = info(#{}, #{}, #{}),
        ?assertMatch(#{<<"exports">> := _}, Info).
 
    compute_test() ->
-       {ok, State} = dev_{name}:init(#{}, #{}, #{}),
+       {ok, State} = init(#{}, #{}, #{}),
        Msg = #{<<"Action">> => <<"MyAction">>},
-       {ok, Result} = dev_{name}:compute(State, Msg, #{}),
+       {ok, Result} = compute(State, Msg, #{}),
        ?assertMatch(#{}, Result).
+
+   -endif.
    ```
 
-6. Compile (use the `$HB_DIR` path):
+   Key patterns:
+   - **Device + tests in same file** — use `-ifdef(TEST).` / `-endif.` guards
+   - Tests call local functions directly (no `module:function` prefix needed)
+   - Use `hb_maps` for state (not plain maps)
+   - Use `hb_private` for secrets
+   - Use `ar_wallet` for auth/signing
+   - Route actions via `hb_ao:get(<<"Action">>, Msg2, Opts)`
+   - Return `{ok, UpdatedMsg}` or `{error, Reason}`
+
+   **Do NOT create separate test files** in `$HB_DIR/test/`. All eunit tests go inline in the device source file.
+
+5. Compile (use the `$HB_DIR` path):
 
    ```bash
    cd $HB_DIR && rebar3 as genesis_wasm compile
@@ -130,10 +135,10 @@ Do NOT mark the task as done if any prerequisite fails. Set the task status to `
 
    If the beam file is missing, compilation failed silently. Read the full output and fix.
 
-7. Run eunit tests:
+6. Run eunit tests (note: test the device module directly, not a separate test module):
 
    ```bash
-   cd $HB_DIR && rebar3 eunit --module=dev_{name}_tests
+   cd $HB_DIR && rebar3 eunit --module=dev_{name}
    ```
 
 8. If compilation errors or test failures:
@@ -175,4 +180,13 @@ For each test-fix cycle:
 3. Classify: is the bug in source code or test code?
 4. Fix ONE issue per iteration (don't change multiple things at once)
 5. Re-run only the failing test first, then full suite
-6. If the same test fails 3 times with the same error, stop and reconsider the approach — the plan may need updating
+6. If the same error persists after 3 different fix attempts, step back:
+   - Re-read the relevant docs (HyperBEAM device protocol, Erlang patterns, etc.)
+   - Check if the plan itself has a wrong assumption
+   - Try a completely different approach
+7. Continue iterating until all tests pass — there is no retry limit
+
+Only escalate to the user if:
+- The failure is environmental (rebar3 missing, Erlang version, port conflict)
+- The test requires user input (wallet, external service URL)
+- You've tried 10+ iterations with no progress on the same error

package/esm/workspace/.claude/skills/build-frontend/SKILL.md

@@ -112,20 +112,23 @@ cd frontend && npx playwright --version 2>/dev/null || echo "Playwright not inst
    cd frontend && npm run test:unit
    ```
 
-7. If any tests fail:
-   - Read the error output
-   - Fix the component or test code
-   - Re-run tests
-   - Repeat until **100% pass**
+7. **If tests fail, keep debugging.** Do not stop. On each iteration:
+   1. Read the full error output — stack traces, assertion messages, log lines
+   2. Identify the FIRST failing test (fix failures in order)
+   3. Classify: is the bug in component code or test code?
+   4. Fix ONE issue per iteration (don't change multiple things at once)
+   5. Re-run the failing test file specifically (faster feedback than full suite)
+   6. If the same error persists after 3 different fix attempts, step back:
+      - Re-read the relevant docs (`wao/web` patterns, React testing library, vitest mocking)
+      - Check if the plan itself has a wrong assumption
+      - Try a completely different approach
+   7. Continue iterating until all tests pass — there is no retry limit
+
+   Only escalate to the user if:
+   - The failure is environmental (missing dependency, port conflict, permissions)
+   - The test requires user input (wallet, external service URL)
+   - You've tried 10+ iterations with no progress on the same error
 
 8. Update the task status to `"done"` in `tasks.json`.
 
-## Iteration Protocol
-
-For each test-fix cycle:
-1. Run tests and capture FULL output
-2. Identify the FIRST failing test (fix failures in order)
-3. Classify: is the bug in source code or test code?
-4. Fix ONE issue per iteration (don't change multiple things at once)
-5. Re-run only the failing test first, then full suite
-6. If the same test fails 3 times with the same error, stop and reconsider the approach — the plan may need updating
+    **IMPORTANT**: Only mark done if all tests pass 100%.

package/esm/workspace/.claude/skills/build-module/SKILL.md

@@ -244,7 +244,16 @@ For each test-fix cycle:
 3. Classify: is the bug in module code or test code?
 4. Fix ONE issue per iteration (don't change multiple things at once)
 5. Re-run only the failing test first, then full suite
-6. If the same test fails 3 times with the same error, stop and reconsider the approach — the plan may need updating
+6. If the same error persists after 3 different fix attempts, step back:
+   - Re-read the relevant docs (custom module patterns, WASM64/Lua conventions, etc.)
+   - Check if the plan itself has a wrong assumption
+   - Try a completely different approach
+7. Continue iterating until all tests pass — there is no retry limit
+
+Only escalate to the user if:
+- The failure is environmental (cargo missing, WASM build tools, port conflict)
+- The test requires user input (wallet, external service URL)
+- You've tried 10+ iterations with no progress on the same error
 
 ## Troubleshooting
 

package/esm/workspace/.claude/skills/plan/SKILL.md

@@ -119,8 +119,7 @@ Plan a feature before building it. The plan and tasks are written to files so an
 | `module-lua` | `/build-module` |
 | `module-wasm` | `/build-module` |
 | `module-test` | `/build-module` |
-| `device` | `/build-device` |
-| `device-test` | `/build-device` |
+| `device` | `/build-device` (eunit tests inline — same file) |
 | `device-integration` | `/test-device` |
 | `frontend` | `/build-frontend` |
 | `frontend-test` | `/build-frontend` |
@@ -134,8 +133,8 @@ Plan a feature before building it. The plan and tasks are written to files so an
 - Tests: `{ "type": "module-test", "skill": "/build-module", "files": ["test/{name}-module.test.js"], "done_when": "yarn test test/{name}-module.test.js — all pass" }`
 
 **Device tasks** (if building Erlang devices) — add `"device"` to `tracks` array and add these to `tasks`:
-- `{ "type": "device", "skill": "/build-device", "files": ["HyperBEAM/src/dev_{name}.erl"], "done_when": "rebar3 as genesis_wasm compile — no errors" }`
-- `{ "type": "device-test", "skill": "/build-device", "files": ["HyperBEAM/test/dev_{name}_tests.erl"], "done_when": "rebar3 eunit — all pass" }`
+- `{ "type": "device", "skill": "/build-device", "files": ["HyperBEAM/src/dev_{name}.erl"], "done_when": "rebar3 compile + eunit — all pass" }`
+  - **HyperBEAM convention**: device source and eunit tests live in the same `.erl` file using `-ifdef(TEST).` guards. Do NOT create separate test files in `HyperBEAM/test/`.
 - `{ "type": "device-integration", "skill": "/test-device", "files": ["test/{name}-device.test.js"], "done_when": "yarn test test/{name}-device.test.js — all pass" }`
 
 **Frontend tasks** (if building frontend) — add `"frontend"` to `tracks` array and add these to `tasks`:
@@ -149,6 +148,15 @@ Plan a feature before building it. The plan and tasks are written to files so an
 **Final validation** — always the last task:
 - `{ "type": "validate", "skill": "/validate", "done_when": "overall PASS" }`
 
+### IMPORTANT: Replace all placeholders with actual names
+
+The templates above use `{name}` as a placeholder. When writing `tasks.json`, replace ALL placeholders with the actual file names from the plan. For example:
+- `"files": ["src/{name}.lua"]` → `"files": ["src/token.lua", "src/registry.lua"]`
+- `"files": ["test/{name}.test.js"]` → `"files": ["test/token.test.js", "test/registry.test.js"]`
+- `"done_when": "yarn test test/{name}.test.js — all pass"` → `"done_when": "yarn test test/token.test.js test/registry.test.js — all pass"`
+
+The `files` array must list every actual file the task will create. The `done_when` must reference the actual test commands. Never leave `{name}` as a literal string in the output.
+
 ### Task ordering rules
 
 The build order matters. Within each component:

package/esm/workspace/.claude/skills/readme/SKILL.md

@@ -5,76 +5,182 @@ disable-model-invocation: true
 allowed-tools: Read, Write, Glob, Grep
 ---
 
-Generate a comprehensive README.md from the project's plan, code, and test files.
+Generate a comprehensive README.md that explains the project thoroughly — what it does, why it exists, how it works, and complete API references for every script, device, and module.
+
+## Performance Notes
+- Read every source file before writing — the README must be accurate, not guessed
+- Include real code examples extracted from test files
+- Document every handler/action, not just the main ones
 
 ## Steps
 
-1. Read `plan.md` for the feature overview, components, and architecture.
+1. Read `plan.md` for the feature overview, architecture decisions, and edge cases.
+
+2. Read **every** AOS script in `src/*.lua`. For each script, extract:
+   - Purpose and what problem it solves
+   - Every `Handlers.add()` — action name, expected tags, return data, error cases
+   - State shape (what globals/tables the script maintains)
+   - Interactions with other scripts (cross-process messages)
+
+3. Read **every** test file in `test/*.test.js`. Extract:
+   - Real usage examples (deploy, message, dry-run patterns)
+   - Edge cases being tested (what fails, what's validated)
+   - Multi-user scenarios
+
+4. If `custom-lua/` or `custom-wasm/` exist, read the module source:
+   - What the module does (compute function, state handling)
+   - Input/output format
+   - How it differs from standard AOS
+
+5. If `HyperBEAM/src/dev_*.erl` files exist, read each device:
+   - Device purpose and when to use it
+   - Exported functions and their signatures
+   - State structure and lifecycle
+   - HTTP endpoints it exposes
+
+6. If `frontend/src/` exists, read key components and hooks:
+   - What the app does from a user perspective
+   - How it connects to AOS (which hooks, which actions)
+   - Wallet integration (ArConnect)
+
+7. Read `package.json` for available scripts and dependencies.
+
+8. Read `scripts/deploy.js` for deployment details.
+
+9. **Write `README.md`** at the project root with ALL of these sections:
+
+```markdown
+# {Project Name}
+
+{2-3 sentence description: what it does, what platform it runs on, who it's for}
+
+## Overview
+
+{Expanded explanation — what problem does this solve? What are the key features?
+List each major capability as a bullet point with a brief explanation.}
+
+## How It Works
+
+{Explain the architecture in plain language:
+- What happens when a user interacts with the app
+- How AOS scripts process messages
+- How state is maintained
+- If HyperBEAM: how devices fit in the pipeline
+- If frontend: how the browser connects to AOS}
+
+## Project Structure
+
+```
+{file tree with inline comments for every important file}
+```
+
+## Prerequisites
+
+- Node.js 20+
+- Arweave wallet (`yarn keygen` to generate)
+- {Erlang/OTP 27+ if devices}
+- {ArConnect browser extension if frontend}
+
+## Setup
+
+```bash
+yarn install
+yarn keygen
+```
+
+## AOS Script Reference
+
+### {script_name}.lua
+
+{What this script does and why it exists}
+
+**State**: {describe the tables/globals maintained}
+
+| Action | Tags | Returns | Description |
+|--------|------|---------|-------------|
+| {action} | {required tags} | {return data} | {what it does} |
+
+**Example** (from tests):
+```js
+{real code example extracted from test file}
+```
+
+**Edge Cases**:
+- {what happens on invalid input}
+- {what happens on insufficient balance, etc.}
 
-2. Read all AOS scripts in `src/*.lua` — extract script names, actions, input/output.
+{repeat for every script}
 
-3. Read test files in `test/*.test.js` — extract usage examples and test scenarios.
+## Device Reference (if applicable)
 
-4. Read `package.json` for available scripts and dependencies.
+### dev_{name}.erl
 
-5. If `HyperBEAM/src/dev_*.erl` files exist, read them for device reference.
+{What this device does}
 
-6. If `frontend/src/` exists, read key components for frontend usage.
+| Function | Input | Output | Description |
+|----------|-------|--------|-------------|
+| {function} | {params} | {return} | {what it does} |
 
-7. **Write `README.md`** at the project root with these sections:
+{repeat for every device}
 
-   ```markdown
-   # {Project Name}
+## Custom Module Reference (if applicable)
 
-   {1-2 sentence description from plan.md}
+### {module_name}
 
-   ## Architecture
+{What this module does, how it differs from standard AOS}
 
-   {Diagram or description of which tracks are included: AOS / Device / Frontend}
-   {How they connect: AOS scripts ↔ HyperBEAM devices ↔ Frontend}
+## Frontend (if applicable)
 
-   ## Prerequisites
+{What the app looks like, what users can do}
 
-   - Node.js 20+
-   - Arweave wallet (auto-generated at `.wallet.json`)
-   - Erlang/OTP 27+ (if using HyperBEAM devices)
+### Components
+- {component} — {what it renders}
 
-   ## Setup
+### Hooks
+- {hook} — {what state it manages}
 
-   ```bash
-   yarn install
-   ```
+## Testing
 
-   ## AOS Scripts
+```bash
+yarn test test/aos.test.js          # in-memory AOS (fast)
+yarn test test/{script}.test.js     # specific script tests
+yarn test test/hyperbeam.test.js    # HyperBEAM integration
+cd frontend && npm run test:unit    # frontend vitest
+cd frontend && npm run test:e2e     # Playwright E2E
+```
 
-   | Script | Action | Input Tags | Output |
-   |---------|--------|------------|--------|
-   {table from Lua source}
+## Deploy
 
-   ## Devices (if applicable)
+```bash
+yarn keygen                        # generate wallet (first time only)
+yarn deploy                        # all scripts to AO testnet
+yarn deploy src/{script}.lua       # single script
+yarn deploy --local-hb             # local HyperBEAM
+yarn deploy --mainnet              # remote HyperBEAM (production)
+```
 
-   | Device | Module | Actions | Description |
-   |--------|--------|---------|-------------|
-   {table from Erlang source}
+### How Deploy Works
 
-   ## Frontend (if applicable)
+{Explain: reads src/*.lua, spawns a process per file.
+On testnet: Eval message. On HyperBEAM: ao.deploy().
+Each script gets its own process ID printed to console.}
 
-   {Component overview, how to run dev server}
+### Verify
 
-   ## Testing
+- [aolink](https://aolink.ar.io/#/entity/{PROCESS_ID}) — inspect AOS process
+- [lunar](https://lunar.ar.io/#/process/{PROCESS_ID}) — inspect HyperBEAM process
 
-   ```bash
-   yarn test                              # in-memory AOS tests
-   yarn test test/hyperbeam.test.js       # HyperBEAM integration
-   cd frontend && npm run test:unit       # frontend vitest
-   cd frontend && npm run test:e2e        # Playwright E2E
-   ```
+## Built With
 
-   ## Deployment
+- [WAO](https://docs.wao.eco) — SDK for AO and HyperBEAM
+- [AOS](https://ao.arweave.dev) — Lua processes on the AO computer
+{add others as relevant}
+```
 
-   ```bash
-   yarn deploy src/{script}.lua
-   ```
-   ```
+10. After writing, re-read the README and verify:
+    - Every AOS action from every script is documented
+    - Every device function is documented
+    - Code examples are real (from test files), not made up
+    - Edge cases are mentioned
 
-8. Update the task status to `"done"` in `tasks.json`.
+11. Update the task status to `"done"` in `tasks.json`.

package/esm/workspace/.claude/skills/report/SKILL.md

@@ -41,7 +41,8 @@ Components:
 
 5. If any task is `in_progress`, run a quick check on its "done when" condition:
    - aos-test: run `yarn test` and report pass/fail count
-   - device-test: run `rebar3 eunit` and report
+   - device: run `rebar3 eunit --module=dev_{name}` and report (eunit tests are inline)
+   - module-test: run `yarn test test/{name}-module.test.js` and report
    - frontend-test: run `cd frontend && npm run test:unit` and report
    - For other types, just report the status