# Plan 005: Fix onboarding docs — README, AGENTS.md, .env.example, BUILD-NOTES

> **Drift check**:
> `git diff --stat 74051ba..HEAD -- README.md BUILD-NOTES.md package.json apps/web/package.json`

## Status

- **Priority**: P2
- **Effort**: S–M
- **Risk**: LOW
- **Depends on**: none
- **Category**: docs / dx
- **Planned at**: commit `74051ba`, 2026-07-09

## Why this matters

Root `README.md` is still the TanStack Start template (“Welcome to your new
TanStack Start app!”) mixed with real deploy notes. `BUILD-NOTES.md` still
documents Zustand as server store (pre ADR-0006). No root `AGENTS.md` /
`.env.example`. Agents and humans follow actively wrong contracts.

## Current state

- README: template fluff + real Convex/Firebase deploy + LP notes.
- Root scripts: `dev`, `dev:mobile`, `build`, `test`, `typecheck` — **no** root `start`
  (start is `apps/web`).
- `BUILD-NOTES.md`: `useStore` for deliveries/actions — false today
  (`apps/web/src/lib/store.ts` is theme + `currentCompanyId` only).
- Env used in code: `VITE_CONVEX_URL`, `VITE_CONVEX_SITE_URL`, PostHog,
  Typeform, Resend, Slack, Typeform webhook secret — no root example file.
- Mobile has partial `.env.example`.
- Three files named `docs/adr/0005-*` (numbering collision) — renumber if touching ADRs.

## Commands

| Purpose | Command | Expected |
|---------|---------|----------|
| Links sanity | open README in editor; paths exist | no phantom `src/routes/demo` |
| Dev (manual) | `bun install && bun run dev` | starts per turbo |

## Steps

### 1. Rewrite root README

- Product one-liner (Dudata Hub faces).
- Monorepo map: `apps/web`, `apps/mobile`, `packages/backend`, `packages/shared`.
- Setup: bun only, Node ≥ 22.12 for Start, `bun install`, `bun run dev` / `dev:mobile`.
- Test/typecheck/build commands that match root `package.json`.
- Keep **deploy seguro** section (Convex prod + Firebase) — it is valuable.
- Keep LP static note.
- Delete “Removing Tailwind”, demo routes, generic Server Functions tutorial.

### 2. Add root `AGENTS.md`

- Package graph + verification commands.
- Domain points to `CONTEXT.md` + `@dudata/shared`.
- Authz reality: **must** be server-side (after 001) / current debt until then.
- SSR rule: framework `defaultSsr: false`, never `typeof window`.
- Object-param functions; pt-BR; kebab-case.
- Pointers to ADRs and `plans/`.

### 3. `.env.example` (names only — never real secrets)

Document purpose one-liners for web + Convex env vars used in repo. Link from README.

### 4. Refresh or archive BUILD-NOTES

Replace store section with ADR-0006 model (RQ + useMe + UI zustand). Point domain
to shared. Remove proto-bar references. Or fold into AGENTS.md and leave a stub
pointer.

### 5. Optional: ADR renumber

If easy: unique numbers for the three `0005-*` files + fix cross-links. If
risky for history, add a note in `docs/adr/README` listing collisions.

### 6. Optional CI PR workflow

Add `.github/workflows/ci.yml` on `pull_request` running `bun run test` +
`typecheck` (DX-04). Deploy workflow stays main-only.

## Out of scope

- Implementing authz (001)
- Enabling eslint monorepo-wide (DX-02) — separate plan if desired
- Rewriting all PRDs

## STOP conditions

- Do not commit real secret values into `.env.example`.
- Do not delete the production deploy runbook from README.

## Done criteria

- [ ] README describes this monorepo accurately; no “Welcome to your new TanStack Start app”.
- [ ] AGENTS.md exists at root with commands + domain pointers.
- [ ] `.env.example` lists required var **names**.
- [ ] BUILD-NOTES no longer instructs Zustand server mutations.
- [ ] No secret values in any new doc.

## Maintenance

When ADR-0006-class architecture changes, update AGENTS.md in the same PR.