# Local onboarding architecture

Reviewed 2026-10-31 against `brief.md`, `constitution.md`, actual source and the installed architecture-blueprint-generator. This is a bounded synthetic review; no interview, human approval or implementation completion is claimed.

AgentBay selected-upstream verification used `source-map.json`, without catalogue search: `github/awesome-copilot`, commit `5269f7ea2d6c3a9bfda5ed878b6726cf509121fd`, `skills/architecture-blueprint-generator/SKILL.md`. Installed `.agents/skills/architecture-blueprint-generator/SKILL.md` SHA-256 matches `a6a6f7a3b7a8210a9a391f2da3f3945bf86505341fd677eb2eb62e599520f512`; Git blob matches `a9a24b0e85fbd1d2e39851cc12ec266f3a55794d`. AgentBay's installed hash also matches. The provider has no companion resources. Native skill listing includes it; no installation was performed.

The current application is a browser-local, event-driven prototype in plain HTML/CSS/JavaScript. `prototype.html` owns presentation, navigation, validation and async coordination; it imports the immutable `src/storage.js`. There is no backend, authentication, remote API or deployment architecture.

```mermaid
flowchart TD
    U[User input] --> P[prototype.html: welcome and form]
    P --> V[Trim and validate title]
    V -->|invalid| E[Inline error; retain input]
    V -->|valid; set busy| W[src/storage.js: writeTask]
    W --> T[350 ms delay; optional demo failure]
    T -->|failure| E
    T -->|success| R[readTasks]
    L[(localStorage: agentbay-demo-tasks)] --> R
    R --> A[Append UUID and title]
    A -->|JSON setItem| L
    W -->|resolved| D[showTasks: readTasks and textContent]
    L --> D
    P -->|initial readTasks finds saved rows| D
    E -->|explicit resubmit| V
```

The prototype is disposable design work. `index.html` is a placeholder loading `src/app.js`, which contains only an implementation comment. `src/task.js` currently only coerces and trims; it does not enforce the final validation contract.

Planned final structure: `index.html` supplies accessible markup and presentation; `src/app.js` imports `validateTitle` from `src/task.js` and adapter functions from `src/storage.js`. App owns screen state, focus, errors, pending state and rendering. Task owns pure validation: trim, reject empty with `Enter a task name.`, reject over 80 characters with `Use 80 characters or fewer.`, return valid text. Storage remains unchanged. Domain validation must not depend on DOM or persistence. Render titles through `textContent` as the prototype does.

The adapter stores JSON arrays of `{id,title}` under `agentbay-demo-tasks`. Reads are synchronous; missing, malformed or inaccessible storage becomes an empty array. Filtering checks only a nonempty string title. Writes wait 350 ms, optionally throw `Save failed. Try again.`, then read, append a random UUID and synchronously persist. Reload reads saved tasks. Reset removes the key.

The prototype sets its busy guard before awaiting, disables Create task and navigation/edit/reset controls, and displays Saving…. Hidden-form and busy checks reject duplicate submission within that page. Failure retains input; the demo failure flag is consumed once, and `finally` unlocks controls for explicit retry. Planned app must preserve these boundaries. Neither adapter nor UUID provides idempotency or coordination across tabs.

Decisions and tradeoffs:

- Immediate task creation delivers the first saved task without signup friction; identity and cross-device continuity are absent.
- Separate pure validation, DOM coordination and persistence in final modules; extra boundaries require wiring but make contracts independently testable.
- Keep local storage and explicit retry; setup stays minimal, while durability and recovery visibility remain limited.
- Keep the prototype separate from final modules; behavior must be deliberately carried over and verified.

Concrete risks: cross-tab read/modify/write can lose updates; corrupt or denied reads silently hide data and a later write may replace it; quota/security failures reject saves; persisted rows bypass title-length validation; current final stubs lack required behavior. The prototype reports all save exceptions identically. No runtime checks were executed in this documentation stage. Existing Node tests and browser verifiers provide future validation boundaries; local Node is 26.5.1 versus required Node 24. Refresh this blueprint after final implementation.