@trypattern/sdk 0.1.37 → 0.1.39

package/docs/CHANGELOG.json

@@ -0,0 +1,331 @@
+{
+  "versions": [
+    {
+      "version": "0.1.39",
+      "added": [
+        "Pattern's guide ships inside Pattern: node_modules/@trypattern/sdk/docs/PATTERN.md, with references beside it, so it always matches the installed version.",
+        "app update prints what changed between the old and new Pattern and saves it to .pattern/update-report.md.",
+        "app migrate-instructions moves an older AGENTS.md onto the guide, keeping everything written for this site.",
+        "requestSource(), recordRequest() and requestSources([...]): your own server code (a custom checkout) records requests in the same batch as its rows, and declares its own owner actions.",
+        "deliverRequestNotices(c) sends the owner's email after the response, and Pattern keeps retrying on its own."
+      ],
+      "changed": [
+        "A project's AGENTS.md keeps only what's about the site and imports Pattern's guide. app check and app start say \"instructions migration incomplete\" until an older one is moved over."
+      ],
+      "visual": [],
+      "migrations": [
+        "Run app migrate-instructions, then follow .pattern/instructions-migration.md if it writes one."
+      ]
+    },
+    {
+      "version": "0.1.38",
+      "added": [
+        "Calendar weekStart=\"sunday\" starts its weeks on Sunday.",
+        "Select isLabelHidden={false} shows its label above it, like a TextField's.",
+        "corners.checkbox: a square Checkbox's corner, 4px whatever radii says."
+      ],
+      "changed": [
+        "Dialog scrolls its own content when it's taller than the screen, so nothing in a sheet is out of reach.",
+        "A sideways ScrollArea lets up-and-down scrolling reach the page."
+      ],
+      "visual": [
+        {
+          "what": "corners (Button, IconButton, TextField, Select, Menu, SegmentedControl)",
+          "before": "Since 0.1.28, buttons and fields kept Pattern's default corners even when the theme re-valued radii, so pill buttons became rounded rectangles.",
+          "after": "Buttons and fields follow the theme's radii again; a theme's own corners still win.",
+          "keep": "Set corners (buttonMd, fieldMd and the other sizes) in src/theme/theme.ts to the corners you had."
+        },
+        {
+          "what": "Checkbox shape=\"square\"",
+          "before": "Its corner came from radii.sm, so a theme with rounder cards made it round.",
+          "after": "It uses corners.checkbox (4px).",
+          "keep": "Re-value corners.checkbox in the theme."
+        }
+      ],
+      "migrations": []
+    },
+    {
+      "version": "0.1.37",
+      "added": [
+        "Skeleton text=\"heading\", \"lead\", \"label\" or another Text variant takes exactly one line of that text, so loading draws in the final layout.",
+        "app update waits and tries again when npm hasn't finished sharing a brand-new Pattern."
+      ],
+      "changed": [],
+      "visual": [],
+      "migrations": []
+    },
+    {
+      "version": "0.1.36",
+      "added": [
+        "colors.attentionSolid and colors.onAttentionSolidForeground: a blue for something waiting, whatever the brand colour.",
+        "fontSizes.badge (9px), for counts."
+      ],
+      "changed": [
+        "AppFrame links: countTone 'brand' is now countTone 'attention', a solid blue badge."
+      ],
+      "visual": [
+        {
+          "what": "Calendar",
+          "before": "Its days had a fixed width, so it didn't fill a wide sheet or panel.",
+          "after": "It fills the width it's given; each day keeps its size.",
+          "keep": "Give the Calendar a narrower parent."
+        },
+        {
+          "what": "Choice (selected)",
+          "before": "A 2px dark ring.",
+          "after": "A 1px ring.",
+          "keep": ""
+        },
+        {
+          "what": "Sidebar count badge",
+          "before": "18px, in the brand colour.",
+          "after": "16px, blue (attention), with a 9px number.",
+          "keep": ""
+        },
+        {
+          "what": "TableRow",
+          "before": "Hover and the open row used the standard grey highlight.",
+          "after": "A lighter highlight on white cards.",
+          "keep": ""
+        },
+        {
+          "what": "FilePicker",
+          "before": "A 1.5px dashed edge.",
+          "after": "A 1px dashed edge.",
+          "keep": ""
+        }
+      ],
+      "migrations": [
+        "Replace countTone: 'brand' with countTone: 'attention' in the layout model's links."
+      ]
+    },
+    {
+      "version": "0.1.35",
+      "added": [],
+      "changed": [],
+      "visual": [
+        {
+          "what": "Icon",
+          "before": "An icon made of several paths was drawn as separate lines, so their colour doubled where they overlapped.",
+          "after": "All of an icon's paths draw as one shape, in one even colour.",
+          "keep": ""
+        }
+      ],
+      "migrations": []
+    },
+    {
+      "version": "0.1.34",
+      "added": [
+        "Requests: inquiry() and inquiries([...]) declare forms visitors send; Pattern saves them, emails the owner and lists them on onpattern.app with bookings.",
+        "this.stores.inquiries.send(source, fields) sends a form.",
+        "app requests lists the live site's requests and drafts replies for the owner to send.",
+        "AppFrame links take countTone for a solid count badge; SegmentedControl options take a count; TableRow size=\"lg\"."
+      ],
+      "changed": [
+        "The bookings block is a request source: booking requests appear in Requests and the owner accepts or declines them there.",
+        "bookingTables now include requestTables."
+      ],
+      "visual": [],
+      "migrations": [
+        "A site with bookings or forms runs app migration (for example app migration pattern_requests) to create Pattern's request tables, then publishes."
+      ]
+    },
+    {
+      "version": "0.1.33",
+      "added": [
+        "FilePreview shows a picked photo straight away, before it uploads.",
+        "Image origin shows a photo from another site."
+      ],
+      "changed": [
+        "A new site's starting rows get the time of its first publish, not a fixed date in 2000."
+      ],
+      "visual": [
+        {
+          "what": "Menu and SegmentedControl",
+          "before": "Their buttons lost their round corners in 0.1.28.",
+          "after": "Round corners again.",
+          "keep": ""
+        }
+      ],
+      "migrations": []
+    },
+    {
+      "version": "0.1.32",
+      "added": [
+        "FilePicker (a drop zone with a button that picks a file), ProgressBar and TableRow.",
+        "Server calls can upload a file and report progress."
+      ],
+      "changed": [],
+      "visual": [],
+      "migrations": []
+    },
+    {
+      "version": "0.1.31",
+      "added": [
+        "Gallery: photos one at a time, swipe on phones, arrows on hover, dots and an \"N of M\" count.",
+        "Dialog placement=\"sheet\": a bottom sheet on phones with a grab handle to drag it closed.",
+        "Header: keeps a site's top bar at the top, frosted with a hairline once scrolled; layers.header."
+      ],
+      "changed": [],
+      "visual": [],
+      "migrations": []
+    },
+    {
+      "version": "0.1.30",
+      "added": [
+        "Card hover=\"zoom\" and hover=\"outline\", and isPressable, all still for people who turn motion off."
+      ],
+      "changed": [],
+      "visual": [],
+      "migrations": []
+    },
+    {
+      "version": "0.1.29",
+      "added": [
+        "Checkbox shape=\"square\".",
+        "IconButton variant=\"primary\" (brand-coloured) and shape=\"round\".",
+        "Button align=\"start\"."
+      ],
+      "changed": [],
+      "visual": [
+        {
+          "what": "Button isFullWidth",
+          "before": "The label sat at the start.",
+          "after": "The label is centred.",
+          "keep": "Add align=\"start\"."
+        }
+      ],
+      "migrations": []
+    },
+    {
+      "version": "0.1.28",
+      "added": [
+        "corners: buttons' and fields' own corner sizes in the theme, so pill buttons can sit beside squarer fields.",
+        "src/theme/colors.stylex.ts holds the business's own named colours."
+      ],
+      "changed": ["The theme may re-value fontWeights, trackings and corners."],
+      "visual": [
+        {
+          "what": "corners (Button, IconButton, TextField, Select)",
+          "before": "Buttons and fields took their corners from radii.",
+          "after": "They take them from corners, which kept Pattern's defaults even when the theme re-valued radii (fixed in 0.1.38).",
+          "keep": ""
+        }
+      ],
+      "migrations": []
+    },
+    {
+      "version": "0.1.27",
+      "added": [
+        "fonts.heading: a second font for the hero, display, section, heading and subheading variants.",
+        "Text weight (normal, medium, semibold, bold, heavy), and fontWeights.heading.",
+        "fontSizes.bodyCompact and lineHeights.bodyCompact: the body and label size on phones."
+      ],
+      "changed": [],
+      "visual": [],
+      "migrations": []
+    },
+    {
+      "version": "0.1.26",
+      "added": [
+        "The device store: state.today (kept current past midnight) and state.isCompact (phone width), readable in getters."
+      ],
+      "changed": [
+        "A table no longer needs an exported row type.",
+        "A store's this.services is typed with the app's own server calls."
+      ],
+      "visual": [],
+      "migrations": []
+    },
+    {
+      "version": "0.1.25",
+      "added": [
+        "A table's defaults: what rows that already exist start with when a required column is added."
+      ],
+      "changed": [
+        "app migration refuses a new required column without a default, because the live site has rows."
+      ],
+      "visual": [],
+      "migrations": []
+    },
+    {
+      "version": "0.1.24",
+      "added": [],
+      "changed": [
+        "Migrations give new required columns a starting value, so they work on tables that already have rows."
+      ],
+      "visual": [],
+      "migrations": []
+    },
+    {
+      "version": "0.1.23",
+      "added": [
+        "app start, check, publish and data say when a newer Pattern is out, and app update installs it."
+      ],
+      "changed": [],
+      "visual": [],
+      "migrations": []
+    },
+    {
+      "version": "0.1.22",
+      "added": [
+        "app data: Claude collects changes to the live site's rows and the owner approves them on onpattern.app."
+      ],
+      "changed": [],
+      "visual": [],
+      "migrations": []
+    },
+    {
+      "version": "0.1.21",
+      "added": [],
+      "changed": [
+        "Owner emails about bookings read like a person wrote them, link to Requests and reply to the customer."
+      ],
+      "visual": [],
+      "migrations": []
+    },
+    {
+      "version": "0.1.20",
+      "added": ["New booking requests email the site's owner."],
+      "changed": [],
+      "visual": [],
+      "migrations": []
+    },
+    {
+      "version": "0.1.19",
+      "added": [],
+      "changed": [
+        "An old copy of a site can't be published over the live one; app publish says to pull into a new folder."
+      ],
+      "visual": [],
+      "migrations": []
+    },
+    {
+      "version": "0.1.18",
+      "added": [],
+      "changed": [
+        "The site's owner on onpattern.app is an admin on the live site without being listed in admins."
+      ],
+      "visual": [],
+      "migrations": []
+    },
+    {
+      "version": "0.1.17",
+      "added": [
+        "ScrollArea resetOn goes back to the top when it changes, so a link lands at the top of the next page."
+      ],
+      "changed": [],
+      "visual": [],
+      "migrations": []
+    },
+    {
+      "version": "0.1.16",
+      "added": [],
+      "changed": [
+        "app pull picks a fresh folder (./<name>-2 and on) when ./<name> is taken."
+      ],
+      "visual": [],
+      "migrations": []
+    }
+  ]
+}

package/docs/PATTERN.md

@@ -0,0 +1,87 @@
+# Pattern
+
+Pattern (`@trypattern/sdk`) is the engine this project runs on: the screens, state, data, sign-in,
+look, checks and the `app` command. This guide ships inside Pattern, so it always describes the
+version installed here. The project's own `AGENTS.md` describes this site or app; this guide and the
+references beside it describe Pattern.
+
+## Working with the person
+
+- The person you work with may not be a developer. Explain what you are doing in plain words, one
+  short step at a time, and run every command yourself: never ask them to type one.
+- `app help` lists the commands and `app <command> --help` explains one. If `app` is not on your
+  PATH, run `./app setup` once.
+- Done = `app check` passes. Its errors explain every rule; fix the code, never the rule. A failing
+  step prints a `rerun:` command and, when one exists, a `fix:` command (`app fix`).
+- Publish only when the person says so (or the first change, which `app pull` says goes live
+  straight away), and only after `app check` passes.
+
+## When Pattern updates
+
+- When `app` says a newer Pattern is out, run `app update`. It installs the new version, prints what
+  changed and saves it to `.pattern/update-report.md`: what's new, what looks different and what to
+  do now (such as `app migration`). Do those, run `app check`, and tell the person in a few words.
+- After an update, reread this guide and the references you rely on: they changed with Pattern, and
+  what you remember of them is from the old version. Before deciding Pattern can't do something,
+  check the capability list below.
+- `app check` and `app start` say "instructions migration incomplete" while `AGENTS.md` still
+  carries Pattern's old rules. Run `app migrate-instructions` and follow what it prints.
+
+## Rules that always apply
+
+- State flows network → service → store → model → screen, and each layer reads only the one below
+  it. Screens read one model and arrange primitives; they have no styles and no plain elements.
+- Everything on screen is drawn by the primitives from `@trypattern/sdk/react`. A piece in
+  `src/components/` may draw a shape no primitive gives, with every style value a token. If no
+  primitive fits, the gap is in Pattern: never write `<button>`, `<input>`, `<p>` or `onClick` on
+  a `<div>`.
+- Every table says who may read and change it (`access`), and the server enforces it.
+- The live site's data is the owner's: change it only with `app data`, which the owner approves.
+- A new feature gets a command on a model and a flow that proves it.
+- Draw loading in the page's final layout (`Skeleton` lines where the words will be), never a
+  separate loader first.
+
+## Does Pattern already do this?
+
+| You want                                                          | Pattern has                                                                                   | Read                    |
+| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------- |
+| Change the live site's items, prices or other rows                | `app data`, approved by the owner on onpattern.app                                            | [data](data.md)         |
+| A photo on the site                                               | `app media add photo.jpg --alt '…' --live`, or the owner uploads it on onpattern.app          | [data](data.md)         |
+| A form visitors send: order, quote, contact, early access         | `inquiry()` and `inquiries([...])`; it lands in Requests                                      | [requests](requests.md) |
+| Bookings with availability                                        | the bookings block                                                                            | [requests](requests.md) |
+| Email the owner when something arrives                            | automatic for every request: never write it yourself                                          | [requests](requests.md) |
+| Your own server code (a custom checkout) taking in requests       | `requestSource()`, `recordRequest()` and `requestSources([...])`, with your own owner actions | [requests](requests.md) |
+| A reply drafted for the owner to send                             | `app requests draft`                                                                          | [requests](requests.md) |
+| Photos one at a time, swipe, dots and arrows                      | `Gallery`                                                                                     | [look](look.md)         |
+| A bottom sheet on phones that drags closed                        | `Dialog placement="sheet"`                                                                    | [look](look.md)         |
+| A header that stays at the top, frosted once scrolled             | `Header`                                                                                      | [look](look.md)         |
+| Hover zoom, a darker edge on hover, press-in                      | `Card` `hover="zoom"`, `hover="outline"`, `isPressable`                                       | [look](look.md)         |
+| Big type: the home page line, page titles, section headings       | `Text` variants `hero`, `display`, `section`, `intro`, `lead`                                 | [look](look.md)         |
+| Bold or semibold text                                             | `Text weight`, and the theme's `fontWeights`                                                  | [look](look.md)         |
+| A second font for headings                                        | the theme's `fonts.heading`                                                                   | [look](look.md)         |
+| Text that doesn't grow on phones                                  | the theme's `fontSizes.bodyCompact` and `lineHeights.bodyCompact`                             | [look](look.md)         |
+| Tighter or looser letter spacing                                  | the theme's `trackings`                                                                       | [look](look.md)         |
+| Pill buttons beside squarer fields                                | the theme's `corners`                                                                         | [look](look.md)         |
+| The business's own colour names                                   | `src/theme/colors.stylex.ts`                                                                  | [look](look.md)         |
+| A square checkbox                                                 | `Checkbox shape="square"`                                                                     | [look](look.md)         |
+| A brand-coloured round icon button                                | `IconButton variant="primary" shape="round"`                                                  | [look](look.md)         |
+| A full-width button with its label centred                        | `Button isFullWidth` (centred unless `align="start"`)                                         | [look](look.md)         |
+| A calendar starting on Sunday, with fully booked days crossed out | `Calendar weekStart="sunday"` and `full` days                                                 | [look](look.md)         |
+| A dropdown with a visible label                                   | `Select isLabelHidden={false}`                                                                | [look](look.md)         |
+| Picking and uploading a file                                      | `FilePicker`, `FilePreview`, `ProgressBar`                                                    | [look](look.md)         |
+| Today's date or a phone-width screen in a getter                  | `this.stores.device.state.today` and `.isCompact`                                             | [state](state.md)       |
+| Menu entries and keyboard shortcuts, ⌘K                           | actions                                                                                       | [state](state.md)       |
+| A new required column on a table that already has rows            | the table's `defaults`                                                                        | [data](data.md)         |
+| Search engines and shared links reading real words                | `server/pages.ts`                                                                             | [data](data.md)         |
+
+Not in Pattern, on purpose: the hand cursor on controls, breakpoints besides `breakpoints.compact`,
+inline `style` attributes, and font sizes outside the theme's scale. Not in Pattern yet: secrets on
+the live site (such as a Stripe key; payments will come through Pattern).
+
+## References
+
+- [The `app` command, going live and updating](app.md)
+- [State: stores, models, actions, screens and flows](state.md)
+- [Data: tables, access, migrations, photos, live data and sign-in](data.md)
+- [The look: primitives, theme, tokens and icons](look.md)
+- [Requests: forms, bookings and owner emails](requests.md)

package/docs/app.md

@@ -0,0 +1,74 @@
+# The `app` command
+
+The `app` command, the checks, the lint rules, the flow runner and the Vite setup all come from
+`@trypattern/sdk`, so a project has no scripts or tool configs of its own: `vite.config.ts` is
+`pattern({ tables, admins, seed })` and the tsconfigs extend Pattern's. Updating Pattern brings
+their fixes. `app help` lists every command and `app <command> --help` explains one.
+
+## Working on this computer
+
+- `app start` runs the dev server in the background and prints its address. `app status` prints
+  the address and the log's path; `app stop` stops it.
+- `app check` is the definition of done: typecheck, lint, Pattern's rules, format, flows and build.
+  It runs every step even when one fails; `app check <step>` runs one. `app fix` applies the
+  automatic fixes (formatting and the lint fixes that are safe).
+- `app test` runs every flow in about a second; `app test --visual` runs them in Chrome and saves a
+  screenshot of every step, with a contact sheet. `app screenshot <path>` shows one page at desktop
+  and phone sizes. Look at the PNGs to see a change.
+- `app send '<command json>'` sends a command to the running app, the same commands flows send.
+- `app sign-in [email]` signs the browser in as a dev user. Locally the emailed sign-in code prints
+  in the dev log.
+- `app reset` empties the local database and fills it again from `seed.ts` and `starter/`.
+- `app migration <name>` writes a migration after a table changes (see [data](data.md)).
+
+## Going live
+
+- `pattern.json` names the site (`<name>.onpattern.app`), the `title` an empty local database starts
+  with, and `blueprint`, the starter it began from (`website` or `web-app`).
+- When the person says publish (or put it live), run `app check`, then
+  `app publish --message '…'`: it builds, uploads and waits until the new version answers, printing
+  each step. The message is a few plain words for the owner about what changed, such as 'Pink brand
+  colour and a welcome line', never technical; onpattern.app shows it beside the version.
+- `app versions` lists what went live and `app restore <number>` puts an earlier version back. The
+  database is not rolled back.
+- When this computer isn't connected yet, these print a short code and open the browser: tell the
+  person to check the code matches and click Allow, then run the same command again straight away;
+  it waits for Allow.
+- An old copy of a site can't be published over the live one. If publish refuses, `app pull` the
+  site into a new folder and carry the change over.
+- `app pull <name>` downloads a live site into a new folder, ready for `app start`.
+
+## The live site's content
+
+- `app data` reads and changes the live site's rows, with the owner's approval (see
+  [data](data.md)).
+- `app media add photo.jpg --alt '…' --live` puts a photo on the live site.
+- `app requests` lists the live site's requests and drafts replies for the owner (see
+  [requests](requests.md)).
+
+## Updating Pattern
+
+- `app start`, `app check`, `app publish` and `app data` say when a newer Pattern is out. Run
+  `app update`: it installs the newest Pattern (waiting a moment if npm hasn't finished sharing a
+  brand-new version), prints what changed and saves the report to `.pattern/update-report.md`.
+- The report has what's new, what looks different (and how to keep the old look), and what to do
+  now. Do what it says, usually `app migration` with the name it gives (Pattern's own tables may
+  have changed, and it writes nothing when they didn't), then `app check`.
+- Then publish (straight away when nothing else is in progress) so the live site gets the new
+  Pattern too, and tell the person in a few words.
+- Reread [the guide](PATTERN.md) after an update: it changed with Pattern.
+- `app migrate-instructions` moves an older project's `AGENTS.md` onto this guide: it removes the
+  rules Pattern now ships, keeps everything written for this site, and writes
+  `.pattern/instructions-migration.md` for anything it couldn't decide. `app check` says
+  "instructions migration incomplete" until that's done.
+
+## Design system and analytics
+
+- `app build` (and so `app check`) writes `dist/design.json`, the app's design system as Pattern's
+  dashboard shows it: every token with the app's overrides marked, each primitive with the variants,
+  tones and sizes it is used with, the app's own pieces and the tokens they draw with, and its
+  icons. Write those props out where they are used (`variant="secondary"`, or a choice between two),
+  so the list is exact.
+- `startApp(App, { onInteraction })` receives a report from every primitive a person uses
+  (`{ primitive: 'Button', event: 'click', label: 'Send request', page: 'home' }`), never a
+  field's value, which is how analytics see every control.

package/docs/data.md

@@ -0,0 +1,109 @@
+# Data: tables, access, migrations, photos, live data and sign-in
+
+## Tables
+
+- Saved data lives in tables declared once in `schema.ts`. A table is `{ columns, access, writes }`:
+  `reviews: { columns: { name: z.string().min(1) }, access: { read: 'anyone', create: 'signedIn',
+update: 'admin', delete: 'admin' }, writes: 'confirmed' }`. Every row also gets `id` and
+  `createdAt`, which Pattern sets: `reviews.create({ name, … })`. A row type
+  (`export type Review = Row<typeof tables.reviews>`) is optional; export one where another file
+  uses it.
+- Every table says who may do what, or it does not compile. `access` gives `read`, `create`,
+  `update` and `delete` one of:
+  - `anyone` (signed out too);
+  - `signedIn`;
+  - `owner` (your own rows);
+  - `admin`: the site's owner on onpattern.app, who is an admin on the live site without being
+    listed, and the emails in `export const admins` in `schema.ts`, which is who is an admin locally
+    and in flows. Admins pass every rule except `server`;
+  - `server` (only Pattern's server code; a table nobody reads from the browser has no store).
+
+  The server enforces it and the flow runner's fake server uses the same rules, so read `access`
+  aloud before writing a screen around it.
+
+- `owned: true` gives every row an `ownerId` that the server fills from the session; the app never
+  sends it. With `read: 'owner'` the store holds only this person's rows (an admin's holds
+  everyone's), so a model never filters "mine" itself.
+- `public: ['chairId', 'date']` lets anyone see those columns of every row, through the read-only
+  `publicBookings` store, whose rows have only `id` and those columns (list `createdAt` too if it may
+  be seen).
+- `unique: [['chairId', 'date']]` makes the database refuse a second row with the same values.
+- `defaults: { colour: 'white' }` is what rows that already exist start with when a required column
+  is added or a column becomes required. `app migration` refuses without one, because the live site
+  has rows; pick a value that's true for the business, or make the column `.nullable()`.
+- `writes: 'optimistic'` shows a write at once and takes it back if the server refuses;
+  `writes: 'confirmed'` shows the row only once the server saved it, and a table with `unique` must be
+  confirmed. Meanwhile `pending` lists each unanswered write as `{ kind, id, row }`, so a screen can
+  say "Booking…".
+- `create`, `update` and `remove` return `'saved'`, `'conflict'` (a unique clash), `'forbidden'`,
+  `'missing'` (the row is gone or not yours) or `'failed'` (no connection). Show a toast for
+  anything but `'saved'`.
+- A table the person may not read yet stays `status: 'idle'` and loads once they sign in.
+- The server serves every table under `/api/tables/<name>`, the database columns come from the same
+  declaration, and each table gets a store of the same name.
+
+## Migrations
+
+- After changing a table, run `app migration <name>`. It writes the next file in
+  `server/migrations/`, the database's history, and refuses a change that would break the live
+  site's existing rows (see `defaults`).
+- Never put content in a migration to get it live: that's `app data`'s job.
+
+## Sample data and starting content
+
+- `seed.ts` is sample data for local work and flows and never ships. `app start` fills only empty
+  tables, so after changing `seed.ts` run `app reset`.
+- Seed rows of an owned table name their owner: `{ id: 'booking-1', owner: 'ada@acme.test', ... }`.
+- `flows/Access.flow.ts` checks every table's rules against the seed on each `app test` (signed
+  out, a stranger, each owner, an admin, public columns, a duplicate), so a broken rule fails by
+  name. `app check` requires it. The admin emails stay on the server and in tests; the browser only
+  learns whether the signed-in person is an admin, as `session.state.user.isAdmin`.
+- A website's `starter/` is the content a new site opens with, written once on its first publish and
+  then owned by the owner. Once the site is live the folder does nothing.
+
+## The live site's data
+
+The live site's data (its items, prices, bookings) is the owner's. To change it:
+
+1. `app data tables` and `app data list <table>` read it.
+2. `app data add`, `update` and `remove` collect the changes.
+3. `app data send --asked '<their request, in their words>'` sends them: the owner approves them on
+   onpattern.app, and it waits for their decision (`app data --help`).
+
+Never change live data any other way, and never put it in `seed.ts` or a migration to get it live.
+The owner can also change rows themselves on onpattern.app (Database).
+
+## Photos
+
+- Photos live in the `media` table (`{ ...defineTables({ … }), media }` in `schema.ts`), added with
+  `app media add photo.jpg --alt '…'`. `--live` also puts it on the live site, and the owner can
+  upload photos on onpattern.app (Database).
+- Show one with `<Image image={…} sizes="…" />`; `priority` on the first image of a page only; never
+  `<img>`, never a hard-coded image URL. Every photo has alt text written for someone who cannot see
+  it.
+- A row stores the photo's media `id`, and a model hands the media row to the screen.
+
+## The server
+
+- The server is `createServer({ tables, admins })` in `server/worker.ts` (a website adds `pages`), a
+  Cloudflare Worker that `app start` serves on the same origin under `/api`.
+- A website's `server/pages.ts` gives each public page its `<head>`: a title, a description, the
+  photo shown when the link is shared, structured data for search engines (`localBusiness`,
+  `product`) and the rows the page needs, so the page arrives filled in and search engines read real
+  words. A new public page gets an entry there, and its path goes in `run_worker_first` in
+  `wrangler.jsonc`.
+- Blocks such as `bookings(...)` and `inquiries([...])` go in `server/worker.ts`'s `blocks` (see
+  [requests](requests.md)).
+
+## Sign-in
+
+- Sign-in comes from Pattern and goes through auth.trypattern.ai: Google, or a 6-digit code emailed
+  to the person, and a dev-only sign-in. Locally the emailed code prints in the dev log instead, and
+  Google works only once the app is deployed.
+- Everything under `/api` needs a session except `/api/health`, `/api/auth/*`, reading `/api/app`
+  (renaming needs an admin) and the tables, which follow their `access`.
+- A session is a row in Pattern's `sessions` table: signing out deletes it, and a copied cookie
+  stops working within 15 minutes.
+- To test signed in, run `app sign-in [email]`. Flows and screenshots sign in as ada@acme.test by
+  default, and in flows the emailed code is always 123456.
+- The app holds no Google secrets: Pattern's deploy gives it an `AUTH_SECRET`.