# Study proposals and run pages

How a study's proposal is stored and accepted, and how a page a run publishes is kept from reaching the board, for
people changing that code. How a study is kept from pushing, and its mock folder, are in
[How a study is kept from pushing](https://andon-docs.pages.dev/contributing/study-sandbox.md). The user guides are [Studies](https://andon-docs.pages.dev/guide/studies.md) and
[Recipes](https://andon-docs.pages.dev/guide/recipes.md#pages).

## The proposal

`propose_project {name, description, cards:[{key, title, notes, depends_on, migration, protected_paths}],
questions:[{question, cards}]}` writes a `project_proposals` row through `machine_propose_project`. The database
refuses a missing name or title, more than 30 cards, a dependency on a card outside the proposal, and a cycle. A card
holds one pending proposal; a later call replaces it. A headless Claude run gets `mcp__andon__propose_project`
pre-approved when the machine's `allowedToolsCeiling` allows it.

**Ask for a change** calls `ask_for_change(card, comment, anchor)`: it rejects the proposal page with the comment as
its note and reuses the outputs' reject-and-revise path (into the live session, a resumed one, or a fresh run in the
card's worktree). The revise prompt carries the current proposal and asks for `proposal-vN.html` and a new
`propose_project`. A pinned part is kept in `run_outputs.review_anchor`. `private.study_max_versions()` stops at five.

**Accept** (`accept_project_proposal`, the study card's owner, once the study has finished its turn) and **Dismiss**
(`dismiss_project_proposal`) are each one statement: if any part fails nothing is left behind. Accept also renders the
project's plan (`project_proposals.plan`), which the board proposes to the team's repository as a `plan` proposal;
until it merges, runs get it through `boardProjectPlan`.

## Pages in the board

A page is one self-contained `.html` file, at most 5 MB. The machine refuses a page that loads a script, stylesheet,
image, font, frame or `@import` from a URL or a neighbouring file, and uploads an accepted one as it is to the private
`outputs` bucket under `<org>/<card>/<run>/<output>/preview.html`.

The board shows it in a frame that can't read the session or call out (`apps/board/src/lib/page-frame.ts`):

- no cookies or storage, no access to the board, no fetch, XHR, WebSocket, images or beacons from anywhere, no forms,
  popups or top navigation;
- a script that sends its own frame elsewhere is refused before any request;
- WebRTC, which no browser lets a policy block, is taken from the page's scripts, and a frame the page adds inside
  itself is removed before it loads, so a page can't embed frames;
- links open in a new tab (http, https and mailto); `#section` links scroll within the page.

Selecting text for **Ask for a change** goes through the page's guard script, which runs before the page's own: it
posts the selection to the board signed with the frame's nonce, and only after the person's own click, key or touch.
The board takes the text and nothing else.

A page with dark styles (`prefers-color-scheme`, a `color-scheme` meta, or a `.dark` class or `[data-theme]` selector)
has its `prefers-color-scheme` queries answered with the board's theme, and its root gets a `dark` or `light` class and
`data-theme`.

## Where it lives

| Piece | Files |
|---|---|
| The Study recipe and its prompt | `db/migrations/20261110075452_study_recipe.sql` |
| Study it first | `apps/board/src/lib/start-work.ts`, `apps/board/src/components/start-work/StartWorkDialog.tsx` |
| The proposal view, versions, Ask for a change, Accept and Dismiss | `apps/board/src/components/card/ProposalView.tsx`, `apps/board/src/lib/project-proposal.ts` |
| Accept, Dismiss and the plan | migrations `20261110172944_accept_project_proposal.sql`, `20261110174607_study_plan.sql` |
| The plan on the project page | `apps/board/src/components/project/ProjectPlan.tsx`, `ProjectRail.tsx` |
| The page frame | `apps/board/public/page-frame.html`, fed by `apps/board/src/lib/page-frame.ts` |
| Tests | `apps/board/e2e/proposal.spec.ts`, `start-work.spec.ts`; `apps/server/test/rls/project-proposals.test.ts`, `accept-project-proposal.test.ts`, `study-plan.test.ts` |
