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

•
Read plan.md for the feature overview, architecture decisions, and edge cases.
•
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)
•
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
•
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
•
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
•
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)
•
Read package.json for available scripts and dependencies.
•
Read scripts/deploy.js for deployment details.
•
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}

code


## 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):

{real code example extracted from test file}

Edge Cases:

•{what happens on invalid input}
•{what happens on insufficient balance, etc.}

{repeat for every script}

Device Reference (if applicable)

dev_{name}.erl

{What this device does}

Function	Input	Output	Description
{function}	{params}	{return}	{what it does}

{repeat for every device}

Custom Module Reference (if applicable)

{module_name}

{What this module does, how it differs from standard AOS}

Frontend (if applicable)

{What the app looks like, what users can do}

Components

•{component} — {what it renders}

Hooks

•{hook} — {what state it manages}

Testing

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

Deploy

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)

How Deploy Works

{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.}

Verify

•aolink — inspect AOS process
•lunar — inspect HyperBEAM process

Built With

•WAO — SDK for AO and HyperBEAM
•AOS — Lua processes on the AO computer {add others as relevant}

code


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

11. Update the task status to `"done"` in `tasks.json`.