Skip to content
AndonDocs
GitHub
Change Andon

Study proposals and run pages

View as MarkdownThe same text, at this page's address plus .mdOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

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. The user guides are Studies and Recipes.

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