# Working on this app

You are one of the crew on this repository. The forge runs the app for you:
production follows the default branch, and every pull you open gets a
preview at its own address, deployed from your branch as you push.

## The rules

- Work on the branch you were given. You cannot move the default branch;
  a person merges your pull once it is reviewed.
- Keep state under `FORGE_APP_DATA`. Never write elsewhere at runtime.
- Run `bun test` before you push. It is the check the pull shows, and every
  behaviour you add gets a test that would fail without it.
- `src/tty.ts` is the app's terminal interface. The exact command that
  reaches it is `FORGE_APP_SSH` at runtime; print that verbatim wherever the
  app tells people how to connect. Keep it working and keep it useful: what
  a person can do on the web page they should be able to do here too.
- Keep it dependency-free unless a dependency is clearly worth it, and say
  why in the pull. A dependency is code you now maintain.
- When you are done, push and stop. Your last message becomes the pull's
  description: say what changed, what you chose not to do, and what to look
  at in the preview.

## The bar

- Shape: small modules named after one concept, plain data in and out. When
  `src/server.ts` stops fitting in one read, split it — `src/db.ts` for
  the schema and queries, `src/pages/<page>.ts` for rendering,
  `src/routes.ts` for the table of paths — and keep the pattern you find.
- Security: every input is validated at the boundary and every output is
  escaped; every response carries the security floor in `src/server.ts`
  (keep it, extend it); a POST that is not same-origin is refused; secrets
  come from the environment, never the repository; no `eval`, no shell
  built from user text; a private thing needs a session in an HttpOnly cookie.
  Every request body is capped by the bytes actually read (`readBody` in
  `src/server.ts`) — never by a Content-Length, which a chunked request does
  not have and a lie does not honour. `HEAD` answers like `GET`.
  An app with an owner or admin is never claimed by whoever visits first:
  the first sign-in needs a secret only the operator holds — a password from
  the environment, or a one-time token printed to the run log and the app's
  terminal — and a generated password is shown there once, never on a page.
- Secrets come from the environment: the app's Settings → Environment
  (write-only), read at start-up; never the repository.
- Speed: the first paint is server-rendered HTML; JavaScript is small, in
  files under `static/` named by content and cached for a year; no layout
  shift; the common request answers in milliseconds; work that can wait is
  done after the response.
- A phone is a first-class client: the page works at 360px wide with no
  horizontal scroll, every control is at least 44px on a side, and the
  keyboard reaches everything a mouse does.
- Finish: the app boots, `/` answers, the README says how to use it and
  what is real versus simulated, `forge.json` says how to run it.