Decisions

D001 — Name the project "pinata"

2026-09-04 · setup · accepted · Human directed

Problem

The project needed a name before a repository could be created, and the name would signal the product concept.

Decision

Name it `pinata`, read as a portmanteau of **pin** + **anno**tation + at **ya**.

Rationale

Specified by the human with the gloss already attached. The pun encodes the product thesis — annotations that get pinned somewhere and then come back at you — which is a useful constraint to design against.

D002 — Public GitHub repository under the lucasdickey account

2026-09-04 · setup · accepted · Human directed

Problem

Repository visibility and ownership had to be chosen at creation time, and visibility is awkward to reason about after secrets or history exist.

Decision

Create `github.com/lucasdickey/pinata` as a public repository from the outset.

Rationale

Specified by the human. Public from the first commit also means the full commit history is reviewable evidence that the work was built new.

D003 — Default branch left as master pending a call

2026-09-04 · setup · superseded · Raised and deferred

Problem

The local git config defaults to `master`, so the pushed repository has `master` as its default branch. Renaming is trivial now and annoying once branches and CI exist.

Decision

Left as `master` for the moment. Flagged to the human rather than renamed silently.

Rationale

A one-word question is cheaper than an unrequested change to something the human will see in the GitHub UI.

Superseded by D009.

D004 — Treat the decision trail as a shipped deliverable

2026-09-04 · setup · accepted · Human directed

Problem

Explaining the process and the decisions is part of the work. Reconstructing that narrative at the end of a build produces a sanitized story that omits the reversals, which are the interesting part.

Decision

Document decisions continuously as the build proceeds, in three forms: agent rules encoded in `AGENTS.md`, a plain-text Markdown log for reading afterwards, and an HTML dashboard that opens in a browser and can carry screenshots. Each decision is explicitly tagged with whether the human requested it or the agent proposed it and the human approved.

Rationale

Requested by the human. The provenance split is the load-bearing part: it makes the division of labor between human and agent auditable instead of asserted.

D005 — One JSON source of truth, both human-readable artifacts generated

2026-09-04 · setup · accepted · Agent decided alone

Problem

The human asked for two views of the same decision trail: a Markdown file and an HTML dashboard. Maintaining both by hand guarantees they drift, and drift in the artifact that is supposed to prove rigor is worse than having one view.

Decision

Hand-edit `docs/decisions/decisions.json` only. Generate `docs/DECISIONS.md` and `docs/dashboard/decisions-data.js` from it with `node scripts/build-docs.mjs`. Ship the dashboard as a static page that reads a generated JS data island so it opens over `file://` with no server and no dependencies.

Rationale

Chosen unilaterally because it is an implementation detail of a deliverable the human had already specified, it is fully reversible, and it adds no dependencies. Labeling it `agent-autonomous` rather than approved is the honest call: the human asked for the two artifacts, not for this mechanism.

D006 — Build the scaffolding before fixing the product concept

2026-09-04 · concept · accepted · Agent decided alone

Problem

The human asked to get the holistic structure in place and then start building, but the product concept was not yet stated beyond what the name implies. Guessing the concept risked building the wrong thing; waiting risked burning the turn on nothing.

Decision

Build the documentation apparatus first, deliberately concept-agnostic, and surface the product-direction question for the human to answer before any application code is written.

Rationale

The scaffolding has no coupling to the product, so doing it first is pure parallelism. The concept question is the one place where a wrong guess is expensive, so it is the one place worth blocking on.

D007 — One command is the quality gate: npm run validate

2026-09-04 · validate · accepted · Human directed

Problem

Factory refused to start a Mission here, warning that the folder was not a git repository and that Missions need strong validation capability or they will incorrectly infer how to QA the application. Two separate faults sat behind one warning. First, `/missions` was being run from `~/Documents/code`, which is a plain directory, while the actual repository is the `pinata` subdirectory. Second, and more seriously, the project genuinely had no way to tell a good change from a bad one: no tests, no lint, no build, nothing an autonomous agent could run to check its own work.

Decision

Run Missions from inside `pinata/`, and give the repository a real validation contract before any Mission touches it. `npm run validate` is the single gate, chaining `lint` then `docs:check` then `test`. It is documented in `AGENTS.md` section 3 as the authoritative answer to "how do I know a change is good?", and CI runs the identical command so local green and CI green mean the same thing.

Rationale

Requested by the human as an explicit precondition to running a Mission. The design principle chosen inside that request: validation has to be one command, dependency-free, and deterministic, because a gate that is slow, flaky, or awkward to run does not get run. Determinism specifically forced generated artifacts to embed a source hash rather than a wall-clock timestamp, since otherwise every build differs from the last and a staleness check can never pass.

D008 — Test the provenance rules, not just the code that renders them

2026-09-04 · validate · accepted · Agent decided alone

Problem

The decision log's value rests entirely on the provenance tags being trustworthy. Nothing stopped a future agent, including me, from tagging a choice `user-directed` with no quote behind it, or from quietly relabelling something it had decided alone as something the human approved. A convention written in prose in `AGENTS.md` is a convention that erodes.

Decision

Encode the section 2.3 rules as executable assertions. The validator rejects `user-directed` without `transcript.request`, rejects `agent-proposed-user-approved` unless both the proposal and the approval are quoted, holds `user-deferred` at `status: pending`, and refuses dangling or self-referential supersession pointers. `npm run validate` therefore fails on a dishonest record, not merely a malformed one. The suite also checks the real repository: gapless ids, screenshots that actually exist on disk, generated files that are not stale, and a dashboard that reads no field the generator stopped emitting.

Rationale

Decided without asking because it is a strictly stronger version of a protocol the human had already specified, and it constrains the agent rather than the human. Worth its own record because it earned its keep immediately: the suite caught a real bug where slugs collapsed runs of spaces into one hyphen while GitHub emits one per space, which would have silently broken every index link in `DECISIONS.md` for any title containing an em dash or an ampersand.

D009 — Rename the default branch to main

2026-09-04 · setup · accepted · Agent proposed, human approved

Problem

`D003` deferred this. The local git default produced a `master` branch, which stayed the default on a public repository that will be reviewed. Leaving it deferred meant CI had to trigger on two branch names and the answer would get more expensive the longer branches and history accumulated.

Decision

Rename to `main`. Done as a pointer move at the same commit — `git branch -m`, push `main`, set the GitHub default, delete the remote `master` — so no history was rewritten and the SHA is unchanged. CI now triggers on `main` only.

Rationale

The agent raised it, twice, and the human chose. Recorded as `agent-proposed-user-approved` rather than `user-directed` because the human never asked for a rename; they answered a question the agent put to them. The distinction is exactly what the origin field exists to preserve.

Supersedes D003.

D010 — Commit straight to main, with CI as the only gate

2026-09-04 · setup · accepted · Agent proposed, human approved

Problem

The first chunk of work went through a branch and a pull request, which produced a reviewable narrative but cost a round trip on a solo project inside a 4-hour timebox. The question was whether to keep paying that.

Decision

Commit directly to `main` from here on. No feature branches, no pull requests. `npm run validate` before every commit stays mandatory, and CI runs the same command on every push, so the gate is unchanged — only the ceremony is gone.

Rationale

The agent offered the options and the human picked. Worth recording because it removes a safety net: with no PR, the pre-commit `validate` run and CI are the only things standing between a bad change and the default branch. That trade is acceptable only because the gate is fast, deterministic, and dependency-free.

D011 — Commit and push early and often, especially at decision points

2026-09-08 · setup · accepted · Human directed

Problem

Work from Session 01 and afterward sat uncommitted in the working tree: a .gitignore update, a vendored agent skill, and a brand asset. The commit graph is itself part of the record (D002), so progress that exists only locally is invisible to anyone reading it and one accident away from being lost.

Decision

Commit and push to the remote frequently rather than batching — at minimum whenever a decision is recorded or implemented. Reversal is cheap with git, so the bias is toward publishing small commits early.

Rationale

Directed by the human, with the reasoning supplied: reversing a commit is easy, so there is no upside to sitting on uncommitted work. This also reinforces D002's consequence that the commit history is reviewable evidence the work was built new. Complements D010 (no PR ceremony) with the push-frequency half of the same hygiene rule. Originally drafted as D009 in a session whose tree pre-dated the published D009/D010; renumbered on merge, which is itself recorded in Session 03.

D012 — Define the product: directional feedback on friends' public websites

2026-09-08 · concept · accepted · Human directed

Problem

D006 left the product concept deliberately open, blocking all application code. The human stated the problem in their own words at the start of Mission planning (2026-09-06); recorded here on 2026-09-08 along with the rest of the planning decisions.

Decision

Pinata is a lightweight, Figma-like web workspace for giving directional feedback on friends' public SaaS, product, pricing, and documentation pages. Static full-page captures, pinned annotations with comments, and a simple founder reply loop. Explicitly out of scope: deterministic copy/style edits (the founder owns the edits), interaction or animation capture, and runtime AI — feedback stays human-authored and directional.

Rationale

Stated directly by the human in the mission brief, resolving D006 exactly as D006 predicted: the first product decision is user-directed. The concept matches the name thesis from D001 — annotations pinned to a page, coming back at the founder.

D013 — Chickpea is the canonical real-world test target

2026-09-08 · concept · accepted · Human directed

Problem

Evals against synthetic fixtures would not surface the failure modes that matter — lazy-loaded content, dense pricing tables, real CSS. And the product has a real first user with a real deadline behind it.

Decision

Use `https://chickpea.co/` plus the explicit URL array `/pricing`, `/about`, `/privacy` as the primary validation target throughout the build. The first real project is feedback for Chickpea's founder. Captures are internal test/demo material with source attribution, not reusable marketing assets.

Rationale

Directed by the human, who needs to send feedback to Chickpea's founder soon. This makes the eval target and the first real use case the same thing, which is the strongest kind of eval.

D014 — Next.js + React + TypeScript on Vercel is the application stack

2026-09-08 · design · accepted · Agent proposed, human approved

Problem

The product needed a stack that ships an MVP fast, integrates natively with the chosen storage services, and keeps authorization server-side without standing up a separate API.

Decision

Build the app with Next.js + React + TypeScript, deployed to Vercel. Server routes and actions authenticate actors, enforce role permissions, validate URLs and payloads, and mediate all storage access. Local development runs on `127.0.0.1:3100`; port 3000 and all pre-existing local processes are off-limits (approved separately).

Rationale

Proposed by the agent as part of the binding architecture and approved wholesale by the human. Next.js on Vercel collapses hosting, server-side authz, and the Blob/Turso integrations into one deploy target, which matters against a 4-hour-flavored budget even though the mission is allowed to run longer.

D015 — MIT React Flow is the canvas foundation

2026-09-08 · design · accepted · Agent proposed, human approved

Problem

The annotation canvas needs pan/zoom, custom nodes, and precise coordinate control. The obvious premium option charges license fees; the free options differ widely in fit.

Decision

Use MIT-licensed React Flow. Each page/device capture gets its own coordinate plane in screenshot-natural pixels, with pages grouped in a project sidebar rather than placed on one shared infinite canvas. Pins, rectangles, and circles are custom nodes parented to the screenshot; arrows are React Flow edges with draggable endpoint nodes.

Rationale

The human picked the option and supplied the reasoning: cost. Screenshot-natural coordinates mean browser size and canvas zoom never move a target, which is what makes deep-zoom feedback trustworthy.

D016 — Browserless captures screenshots and DOM manifests in one session

2026-09-08 · design · accepted · Agent proposed, human approved

Problem

The screenshot and the DOM metadata manifest must come from the same layout state or pins cannot be attached to elements reliably. Self-hosting headless Chromium is operational burden the MVP does not need.

Decision

Use the Browserless Function API: one fresh browser session per URL and viewport, desktop and mobile at CSS-pixel scale. Each session navigates to a validated public HTTPS URL, incrementally scrolls lazy content, freezes visual animation, extracts a bounded and sanitized element manifest, and captures the final image from that same state. Maximum two concurrent captures.

Rationale

Proposed by the agent and ratified through the umbrella architecture approval (there was no standalone Browserless question — recorded honestly). The manifest is deliberately bounded: tag, role, short visible text, accessible name, structural path, document-space rectangle. It excludes HTML source, cookies, storage, form values, hidden content, and cross-origin iframe internals.

D017 — Private Vercel Blob for images, Turso/libSQL + Drizzle for metadata

2026-09-08 · design · accepted · Agent proposed, human approved

Problem

Screenshots are large binary assets and project data is relational; both need managed, Vercel-friendly homes that stay within free tiers and require no server administration.

Decision

Store screenshots in private Vercel Blob and everything else — projects, pages, captures, annotation geometry, DOM metadata references, threads, actor roles, share-token digests, revisions — in Turso/libSQL via Drizzle. All reads and writes pass through authorized application routes.

Rationale

Proposed by the agent and approved wholesale. Both services completed real write/read/delete verification during mission readiness checks before this was recorded, so the choice is evidence-backed rather than brochure-backed.

D018 — Editor password prompt, persistent founder capability links, append-only threads

2026-09-08 · design · accepted · Agent proposed, human approved

Problem

The product needs exactly two roles — Lucas as editor, recipients as founders — without a signup system. Access control has to be real (server-enforced) while staying proportionate to a friends-and-founders tool.

Decision

Lucas authenticates through an in-app password prompt whose credential is checked server-side against an environment secret. Founders enter through high-entropy, unguessable project links that act as bearer capabilities and persist until Lucas rotates or revokes them. Threads are chronological and append-only: founders reply as `founder`, Lucas appends follow-ups, and founder replies are immutable for everyone — no update/delete endpoint exists for them.

Rationale

Two separate approval questions, answered directly by the human. Immutability of founder replies is the trust mechanism: feedback history cannot be rewritten by either side, which makes the tool safe to point at someone's product.

D019 — Standardize on Node 24 across app, CI, and Vercel

2026-09-08 · setup · accepted · Agent proposed, human approved

Problem

The scaffold was built on Node 20, Vercel deploys run Node 24, and the local machine drifted to Node 25 — under which `node --test test/` already broke once (Session 02). Three runtimes is a standing source of works-here failures.

Decision

Standardize the application, CI, and repository documentation on Node 24, matching Vercel.

Rationale

Proposed by the agent with an explicit recommendation; the human's answer was a delegation ("i defer to you") rather than a picked option, and it is recorded as approval-by-deferral for honesty. The recommendation stood because it removes a drift axis that had already produced a real failure.

D020 — Product-stack transition: Vitest and Playwright join the single validate gate

2026-09-08 · validate · accepted · Agent proposed, human approved

Problem

The zero-dependency `node:test` gate chosen in D007 cannot cover a Next.js application — no component tests, no browser flows, no typecheck. But multiplying entry points would break the single-command contract that makes the gate runnable.

Decision

`npm run validate` remains the single gate and grows to aggregate: ESLint plus repository integrity checks, TypeScript typecheck, Vitest suites, the deterministic docs check, the Next.js production build, and Playwright Chromium end-to-end tests. GitHub Actions runs the identical Node 24 command. The docs tooling itself stays zero-dependency, and the existing `node:test` suite keeps running until its assertions are migrated.

Rationale

Proposed by the agent, approved by the human with the full stack named. This reverses D007's rejection of a test framework — correct at the time, when the repo was dependency-free docs tooling — while preserving D007's actual decision, the single gate.

D021 — Re-scope the dependency ban to an approved pinned allowlist; ESLint covers JS, tsc covers TS

2026-09-08 · build · accepted · Agent decided alone

Problem

D020's first recorded consequence: the lint rule asserting empty dependency lists contradicts the approved application stack the moment Milestone 1 installs it. ESLint also needed a scope decision, because typescript-eslint and eslint-config-next are not in the approved dependency set.

Decision

package.json dependencies and devDependencies are limited to the mission-approved packages at exact pinned versions, enforced by lint against the single allowlist in scripts/lib/approved-deps.mjs (imported by both the lint gate and the integrity tests so they cannot drift). The docs tooling stays zero-dependency, now enforced by a test that scripts/ and docs/dashboard import only node: builtins or relative paths. ESLint lints the JavaScript surface only; TypeScript/TSX correctness is covered by tsc --noEmit. @types/node, @types/react, and @types/react-dom are admitted as part of the approved TypeScript toolchain.

Rationale

D020 explicitly deferred this re-scope to the Milestone 1 implementation, and the package set itself was approved during mission planning (D014-D017, D020). Choosing the enforcement mechanics is a mechanical choice inside an approved direction, per AGENTS.md section 4.

D022 — Serve /reqs from repository sources with a zero-dependency safe Markdown renderer

2026-09-08 · build · accepted · Agent decided alone

Problem

The approved architecture requires /reqs pages backed by docs/REQUIREMENTS.md, docs/ARCHITECTURE.md, docs/MILESTONES.md, and docs/EVALS.md with raw HTML disabled, and decisions rendered directly from docs/decisions/decisions.json. But the approved dependency allowlist (D021) contains no Markdown package, and hand-copying content into JSX would create a second dataset that drifts from the sources.

Decision

Implement a deliberately small Markdown renderer in src/lib/markdown.ts (headings, paragraphs, flat lists, pipe tables, fenced code, blockquotes, inline code/strong/em/links) that escapes every source character it does not emit itself, allow-lists link targets to https?/root-relative/relative/anchor, renders unsafe or malformed targets as inert text, adds target=_blank rel="noopener noreferrer" plus a visible host label to external links, and makes colliding heading anchors unique with deterministic -2/-3 suffixes. The hub's route table and dogfood URL array are exported constants in src/lib/requirements.ts that pages and tests share; /reqs/decisions imports docs/decisions/decisions.json directly.

Rationale

The direction (source-backed /reqs routes, raw HTML disabled, decisions from the JSON) was already fixed by the approved mission architecture; only the mechanism was open. Choosing the mechanism is a mechanical choice inside an approved direction per AGENTS.md section 4, it adds no dependencies, and it is fully reversible, so a unilateral call is safe and is labeled agent-autonomous honestly.

D023 — Publish one versioned validation boundary catalog as shared exported constants

2026-09-08 · build · accepted · Agent decided alone

Problem

The validation contract (VAL-REQS-007 plus the auth, capture, quota, geometry, and performance assertions) requires exact versioned values for session lifetime/renewal, URL limits and normalization fixtures, capture dimensions/time/bytes/attempts/concurrency/staleness, the manifest schema, the supported-motion matrix and tolerances, the capture outcome catalog, geometry minimums, login/reply quotas, the client timeout, the annotation maximum, hit targets, and the performance protocol/budgets — before the features that consume them exist. Without a single exported source, each consuming feature would invent and duplicate its own literals, and the docs and /reqs pages would silently drift from runtime behavior.

Decision

Create src/lib/boundaries/ as the only source of runtime policy values: focused modules (session, url, capture, manifest, motion, outcomes, geometry, quotas, feedback, interaction, performance) re-exported under one dated POLICY_VERSION (2026-09-08.1). Choose the concrete values now: a 12-hour renewable editor session with a 2-hour renewal threshold; 32 submitted rows, 16 unique URLs, 2,048 bytes per URL; 1440×900 and 390×844 DPR-1 viewports; 16,384 px height, 25,000,000 px area, 8 MiB image, 16 MiB provider response caps; 30 s navigation, 5 s network-idle, 800 px × 24-step × 250 ms lazy scroll, and a 90 s total capture deadline inside Browserless's 120 s session cap; 5 redirect hops; 64 attempts per project; 2 active captures; a 5-minute stale age; a 500-element / 256 KiB exact-key manifest schema; an eight-case motion matrix with 1 px anchor tolerance and 0.001 masked-diff ratio; an eighteen-code outcome catalog with 256-byte public messages; 8 px minimum shapes and 16 px minimum arrows; 5 failed logins per 15 minutes and 30 replies per hour; a 15 s client request timeout; 2,000-character feedback bodies; 200 annotations per capture; 8 nearby candidates; 24 px hit targets (WCAG 2.2 AA); and the tall-capture performance protocol and budgets. Publish the same values, fixtures, and policy enums in docs/EVALS.md and docs/ARCHITECTURE.md (which the /reqs routes render), and pin all three together with test/boundaries.test.ts, which imports the exported constants, checks the docs and rendered route HTML for the exact values, and scans the application for duplicated literals.

Rationale

The mission plan explicitly assigns defining this catalog to the validation-boundary-catalog feature, and the requirements session deliberately published policies without numbers until it landed. The values are constrained by documented provider limits (Browserless's two concurrent sessions and 120-second cap), the observed ~13,000 px Chickpea mobile page, WCAG 2.2 target-size minimums, and the approved architecture. Choosing them here is the assigned work, the choice is fully recorded, and it is reversible by editing one module, so a unilateral call is safe and is labeled agent-autonomous honestly.

D024 — Verify the editor password via fixed-length digests and bind sessions to a double-submit CSRF proof

2026-09-08 · build · accepted · Agent decided alone

Problem

The editor login (VAL-AUTH-001, VAL-AUTH-010) needs a server-only verifier that never leaks length or timing information about EDITOR_PASSWORD, a session format that supports the catalog's absolute-expiry/renewal policy plus authoritative logout before any durable store exists, and CSRF protection for cookie-authorized mutations now that SameSite=Strict and exact Origin checks alone would leave the later mutation surface without a session-bound proof.

Decision

Hash both the submitted password and EDITOR_PASSWORD with SHA-256 and compare the fixed-length digests with crypto.timingSafeEqual, so empty, unequal-length, oversized, and arbitrary-Unicode input can neither throw nor bypass. Issue sessions as HMAC-SHA256-signed v1.payload.signature tokens carrying a random session id, issued-at, absolute expiry, and a random CSRF proof; renewal keeps the session id and proof and resets the absolute expiry. Bind mutations with a double-submit pair: the proof rides in a browser-readable pinata_csrf cookie and must be echoed in the x-pinata-csrf header, compared timing-safely against the session payload. Logout revokes the session id in a per-process revocation set held until the session's absolute expiry, and always clears both cookies with matching attributes. Enforce exact same-origin Origin against the Host header (Next.js normalizes request.url's hostname), the 1,024-byte auth body cap, and a strict one-field Zod schema; add AUTH_REQUEST_MAX_BYTES and EDITOR_PASSWORD_MAX_CHARS to the boundary catalog and bump POLICY_VERSION to 2026-09-08.2. Keep every secret, verifier, and cookie serializer in src/lib/server/, guarded by a test that fails if any client module imports them.

Rationale

The architecture document already directs the password prompt, timing-safe comparison, SESSION_SECRET-signed cookies, and origin/CSRF protection, so this chooses only implementation mechanics inside that approved direction — a safe agent-autonomous call. The verifier and session format were proven with 44 focused tests before the full gate ran.

D025 — Persist the canonical model in committed Drizzle migrations with database-enforced thread immutability and injectable provider seams

2026-09-08 · build · accepted · Agent decided alone

Problem

Every capture, annotation, thread, sharing, and throttling feature needs one authoritative Turso/libSQL schema whose constraints (unique normalized pages, immutable capture attempts, append-only thread entries, capability digests, idempotency keys, durable rate-limit buckets) hold at the database boundary rather than by application convention, applied through committed repeatable migrations, with provider boundaries that focused tests can drive deterministically without letting mocks replace real Turso/Blob/Browserless proof.

Decision

Model the architecture's tables in src/lib/server/db/schema.ts (text UUID keys, epoch-ms UTC timestamps, explicit foreign keys, unique constraints, and CHECK constraints for capture variant/status, annotation kind, and thread role/label), generate committed SQL with drizzle-kit into drizzle/, and add a custom migration installing BEFORE UPDATE/DELETE triggers on thread_entries that RAISE(ABORT). Apply migrations with scripts/db-migrate.mjs (npm run db:migrate), a Node script using drizzle-orm's libSQL migrator over @libsql/client so reapplication is idempotent and credentials are never printed. Capture attempts carry a per-(page, variant) monotonic attempt number plus a unique idempotency key and a unique blob_path, so retries are new immutable rows. Add generic idempotency_keys ((scope, key) primary key plus payload digest) and digest-keyed rate_limit_buckets tables. Keep all database, Browserless, and private-Blob construction in server-only modules with dependency-injectable client/fetch/SDK seams; adapters map provider failures to bounded secret-free error codes and never cross provider URLs or tokens to callers.

Rationale

The architecture document already directs Turso/libSQL + Drizzle, committed migrations, the table set, digest-only capability storage, and database triggers; this record chooses only mechanics inside that approved direction (migration runner, attempt-number/idempotency columns, trigger SQL), which is safe to decide unilaterally. The schema, triggers, and provider seams were verified against the real configured Turso database and private Blob store with disposable run-scoped data and confirmed cleanup before the full gate ran.

D026 — Throttle editor logins with one durable digested global bucket and check secrets fail-closed before verification

2026-09-08 · build · superseded · Agent decided alone

Problem

VAL-AUTH-006 requires durable editor-login throttling that holds across tabs and at least two application instances, recovers after the exact published interval, and keeps passwords and secrets out of throttle evidence, plus fail-closed behavior when either editor auth secret is missing. The contract fixes the threshold (LOGIN_MAX_FAILURES) and window (LOGIN_WINDOW_MS) but not the bucket identity, window style, throttled-response shape, or misconfiguration ordering.

Decision

Enforce the login throttle in the approved Turso rate_limit_buckets table as one shared bucket keyed by the SHA-256 digest of the fixed editor-login scope (never a password, secret, or client identifier), with a fixed window anchored at the first failure: failures are registered by a single atomic INSERT ... ON CONFLICT ... DO UPDATE ... RETURNING statement that resets the window exactly at the boundary, throttled attempts receive a bounded generic 429 with a Retry-After header and never mutate or extend the window, a successful login deletes the bucket, and the route fails closed (bounded 503) when the durable store or SESSION_SECRET is unavailable. The SESSION_SECRET check runs before password verification so a misconfigured deployment answers every attempt with the identical 503 instead of becoming a password-correctness oracle. Tests and validation runs use run-scoped scopes so they never touch the production bucket.

Rationale

VAL-AUTH-006 and the approved schema (D025) already direct durable, digest-keyed throttling; this record chooses only the keying scope, window semantics, response shape, and check ordering inside that approved direction, which is safe to decide unilaterally because no user-facing product direction changes. The behavior was proven against the real configured Turso database (two independent clients sharing one run-scoped bucket, digest-only readback, verified cleanup) and end to end against the local server across a process restart before the full gate ran.

Superseded by D098.

D027 — Env-dependent tests skip rather than fail, so the CI gate needs no repository secrets

2026-09-08 · build · accepted · Agent decided alone

Problem

The gate is one command run in two places with different configuration. Locally .env.local supplies the editor secrets, Turso credentials, Blob token, and Browserless token; GitHub Actions holds none of them. The e2e auth specs read EDITOR_PASSWORD from .env.local and threw when it was absent, so `npm run validate` could never pass in CI. Either CI gets real secrets, or the suite has to state which parts it can prove without them.

Decision

Keep secrets out of CI entirely and make configuration-dependent tests skip with a name-only reason instead of failing. Playwright specs go through e2e/local-env.ts: localEnvGate([...names]) resolves each variable from the process environment first and .env.local second, reports the missing names, and the spec calls test.skip(!gate.ready, gate.reason) before reading any value through requireLocalEnvValue. No spec reads .env.local directly, and test/e2e-env-gate.test.ts enforces both that rule and the presence of the skip. This mirrors the describe.skipIf gating the Vitest integration suites already use. The unauthenticated e2e coverage — the login prompt shape, the 401 on the protected read, and the public HTML/bundle secret-name scan — stays unconditional and runs in CI.

Rationale

This is the gating pattern the repository already chose for the Turso and Blob integration suites, applied to Playwright, so it introduces no new direction; it is safe to decide unilaterally because it neither weakens an assertion nor changes product behavior. The skipped tests are named in the run output with the variables they need, which keeps the reduced CI coverage visible instead of silent, and no secret value reaches the workflow, the specs, or any committed file.

D028 — Projects take an explicit URL array; admission is a synchronous, network-free normalizer

2026-09-08 · build · accepted · Agent decided alone

Problem

A project needs more than one page, and the obvious way to get them is to crawl the root. Crawling is out of scope by product framing (the landing copy promises 'no crawling'), it turns project creation into an unbounded network operation, and it makes the page set non-deterministic. The creation boundary still has to decide, for every submitted string, whether it is a capturable destination — and it has to decide the same way every time so page identity is stable.

Decision

Project creation accepts exactly one required root URL plus an optional explicit array of additional URLs, and never discovers, infers, or follows a link. Every string goes through one synchronous normalizer (src/lib/url/normalize.ts) that performs no I/O: trim, byte cap, scheme check, a single WHATWG parse, https-only, no credentials, no non-443 port, trailing-dot strip, IP-literal rejection, empty-label rejection, single-label and reserved-suffix rejection, fragment dropped, empty query dropped, empty path normalized to '/'. The result is the page's identity, so two spellings that differ only by fragment collapse to one page. Every limit and every reject reason lives in the versioned boundary catalog (POLICY_VERSION 2026-09-08.3) with fixtures, and the route returns all offending rows at once as {field, index, code} without echoing the submitted text.

Rationale

This is the conservative reading of an existing product constraint rather than a new direction, so it was safe to decide unilaterally. Keeping admission synchronous and network-free means the boundary is fully testable from fixtures, the same function decides page identity and admission (so they cannot drift), and the genuinely network-dependent checks stay where they can be enforced — at capture time, against the address actually connected to.

D029 — A project, its pages, and two pending capture attempts per page are created in one transaction, keyed for idempotent retry

2026-09-08 · build · accepted · Agent decided alone

Problem

Creating a project writes to three tables, and capture dispatch reads what it wrote. A partial write leaves a project with no pages, or pages with no attempt rows that nothing will ever pick up — states the UI cannot represent and the capture worker cannot recover from. A double-submit or a retried request after a dropped response would otherwise create a second identical project.

Decision

One db.transaction writes the idempotency record, the project, every page in submission order (root first), and exactly two pending capture rows per page (desktop 1440x900, mobile 390x844, DPR 1, attempt 1) — or nothing. Capture dispatch happens strictly after the transaction commits. The client sends an idempotency key per creation intent: the same key with the same canonical payload digest replays the original identities with created:false and HTTP 200, the same key with a different digest is refused with 409, and a transaction failure re-reads the idempotency record so a concurrent winner converges instead of both callers failing.

Rationale

Atomicity plus an explicit key is the standard shape for a create-then-dispatch boundary and introduces no product direction, so it was safe to decide unilaterally. Writing the attempt rows inside the same transaction makes 'work is owed' a durable fact rather than an in-flight intention, which is what lets the capture worker be a plain queue reader and lets partial-status reporting be a query instead of an inference.

D030 — The active capture is the highest-numbered ready attempt, and staleness is computed at read time

2026-09-08 · build · accepted · Agent decided alone

Problem

Attempt rows are immutable history, so a page variant can hold several of them at once: a ready one, a newer failed one, and an abandoned capturing one whose worker died. Something has to decide which version the canvas shows and when a retry is offered. Choosing by completion time would let a late result from an abandoned older attempt overwrite a newer ready capture as the default, silently rebasing every annotation bound to it. Persisting a stale flag would need a background job the deployment does not have.

Decision

Selection is by attempt version, never by clock: the active capture for a (page, variant) is the ready attempt with the highest attempt number, so a late old result still persists on its own row and stays addressable but can never become the default. A capturing attempt older than STALE_CAPTURE_AGE_MS computes to stale on read rather than being written, and retry is offered only when the latest attempt is terminal or computed stale and the outcome catalog does not mark that failure non-retryable. Every persisted transition is a compare-and-set on one attempt id plus its expected status, so terminal rows can never be rewritten.

Rationale

Version-ordered selection plus read-time staleness makes both answers pure functions of committed rows, so two readers, two instances, and a reload cannot disagree, and no background process is required. This is an implementation of the immutability rule the architecture already fixed, not a product choice, so it was safe to decide unilaterally.

D031 — Retry is scoped to one page and one viewport, keyed to that exact target

2026-09-08 · build · accepted · Agent decided alone

Problem

When one of a project eight captures fails, resubmitting the project would re-run the seven that succeeded, burn Browserless quota, and replace ready captures that already carry annotations. A retry also needs a key so a double click or a retried request after a dropped response does not schedule two captures — but a key that is not bound to its target would let the same key silently schedule a different page or viewport.

Decision

POST /api/pages/[pageId]/captures names exactly one page and one variant. It writes one new pending attempt for that target only, never touching a sibling page or the other viewport. The client idempotency key is recorded in the shared idempotency_keys table under a capture-retry scope with a digest of {pageId, variant}: the same key with the same target replays the one created attempt, and the same key with a different target is refused with a bounded 409. Attempts are capped per project by MAX_CAPTURE_ATTEMPTS_PER_PROJECT, and a missing page, a non-retryable state, and a quota refusal all answer with the same generic bounded message.

Rationale

Scoping the mutation to the smallest addressable unit is what makes partial failure recoverable without collateral damage, and binding the key to the target keeps replay honest. Both follow directly from the approved capture model, so no product direction was decided here.

D032 — Capture admission is two defences: a bounded server-side check and an in-function request guard

2026-09-08 · build · accepted · Agent decided alone

Problem

Project creation admits URLs without touching the network, so a public hostname that resolves to a private address passes it. Capture then hands that hostname to Browserless, which runs in a different network from this application. A single application-side DNS check is not proof of anything the remote browser will do a moment later, and a purely remote check gives the application no bounded verdict before it spends provider quota.

Decision

Capture admission runs in two places. Server-side, admitCaptureTarget canonicalizes once with WHATWG URL, rejects every unsafe syntax and IP spelling, resolves a bounded CNAME chain plus A and AAAA under DNS_TIMEOUT_MS, refuses the host if any answer is non-public, then walks the redirect chain with redirect: manual, revalidating every top-level hop under the identical rules up to MAX_REDIRECT_HOPS. Only then is the attempt claimed as capturing with its requested and final public URL persisted. Inside the Browserless function, an emitted request guard revalidates every top-level navigation and aborts subresource requests to credentialed hosts, reserved hosts, non-HTTP(S)/WebSocket schemes, and IP-literal hosts, without disabling web security, TLS validation, sandboxing, or the provider blocklist.

Rationale

Neither side is sufficient alone and the two fail in different directions, so running both is what makes the boundary defensible. Both sides follow from the approved architecture, so no product direction was decided here.

D033 — DNS admission fails closed on any ambiguity, and one non-public answer rejects the host

2026-09-08 · build · accepted · Agent decided alone

Problem

A resolver can answer in more ways than yes and no. A host may return one public A record and a private AAAA record, a SERVFAIL for one family and an answer for the other, two CNAMEs, a chain that loops, or nothing at all within the budget. Treating any of those as good enough leaves a path where the browser picks the answer we did not check.

Decision

A host is admitted only when every answer parses as an address and every answer is public. A timeout, an ambiguous failure such as SERVFAIL or REFUSED from either family, more than one CNAME, a loop, a chain longer than MAX_CNAME_HOPS, an unparseable answer, and an empty result all reject the host. A definitive ENODATA/NXDOMAIN for one family is the one non-answer that is treated as information rather than ambiguity, so an IPv4-only host still resolves. Rejections report a bounded reason and never the resolved address.

Rationale

Every rejected case is one where the application cannot state what the browser will connect to, and the cost of refusing is one retryable failed attempt. The address catalog is published as enumerated policy so the refusal is auditable without disclosing any particular answer.

D034 — Capture screenshots are PNG, and only PNG or WebP may ever be stored

2026-09-09 · build · accepted · Agent decided alone

Problem

The capture pipeline has to decide what image format it asks Chromium for and what it will accept back. The choice is not cosmetic: the motion assertion compares two captures of one deterministic fixture pixel by pixel, and it also decides what a decoder has to be able to reject safely.

Decision

The published catalog gains ALLOWED_IMAGE_CONTENT_TYPES = [image/png, image/webp], and the first entry is what the capture function asks for. Only an allowlisted declared content type whose bytes decode as that same format, at exactly the document dimensions, can be stored. POLICY_VERSION moved to 2026-09-08.6.

Rationale

This is a mechanical choice inside an already approved direction, and it is reversible: WebP stays in the allowlist so a future feature can switch the produced format without touching the validator. PNG is lossless, so the pixel-diff assertion measures the page rather than the encoder, and the structural decoder that validates it is small enough to stay dependency-free.

D035 — Dispatch admits, captures, and finalizes in one request; there is no claim endpoint

2026-09-09 · build · accepted · Agent decided alone

Problem

Admission claimed an attempt and returned 202 with the row left in capturing, on the assumption that some later call would run the provider. That leaves a durable open claim whenever the second call never arrives, and it invites a second public endpoint whose only job is to finish someone else's claim.

Decision

POST /api/captures/:id/dispatch now runs the Browserless execution in the same request, immediately after dispatchCapture returns ok, and answers only once the row is ready or failed. Every exit from a claimed attempt is terminal: a missing provider credential, an untrustworthy envelope, a storage failure, and an unexpected throw all fail the row with a catalog outcome rather than leaving it capturing.

Rationale

The open claim was recorded as an open question by the previous feature, and closing it inside the existing endpoint changes no public contract beyond the success status. Deciding this unilaterally was safe because the alternative — a new endpoint — is the change that would have needed approval.

D036 — Browserless is authenticated with HTTP basic, because bearer fails and the URL is not an option

2026-09-09 · build · accepted · Agent decided alone

Problem

The provider documents its token as a query parameter, which this project refuses: a credential in a URL leaks into proxies, logs, and error reports. The adapter therefore sent it as a bearer credential in the Authorization header — and every real call failed. Measured against three regional endpoints, a bearer credential returns a gateway 500 while the same request with the token in the query string returns 200.

Decision

The adapter sends Authorization: Basic base64(token + ':') — the token as the basic username with an empty password. That form is accepted by the same gateway that rejects bearer, and it keeps the credential in the header. The fixed regional /function endpoint and the never-log rule are unchanged.

Rationale

This preserves the invariant that matters (the credential travels only in the Authorization header, never in a URL and never in a log) and changes only the scheme token inside that header. It was safe to decide alone because the alternative that needed judgement — a credential in the URL — was rejected, not chosen.

D037 — Controlled capture fixtures live in the repository and are published to a disposable public host per run

2026-09-09 · validate · superseded · Agent decided alone

Problem

Proving device emulation, context isolation, lazy loading, and motion stabilization needs pages that Browserless can actually load, which means public HTTPS. This project's own Vercel deployments sit behind deployment protection and answer an SSO redirect, no tunnel tooling is installed, and publishing fixtures through the application's own routes would put test pages on its public surface.

Decision

The fixtures are versioned files in test/fixtures/capture/ (echo-v1.html, tall-motion-v1.html). scripts/publish-capture-fixtures.mjs uploads them to a disposable public host with a one-hour lifetime, refuses to print a URL unless the served bytes hash to exactly the repository bytes and arrive as text/html, and the real-provider suite reads those URLs from the environment and skips when they are absent.

Rationale

The repository stays the source of truth for fixture behaviour — the host only serves a byte-identical copy for the length of a run — so the assertion remains reproducible from the tree. The uploaded content is inert markup with no secrets and no application data, and it expires on its own.

Superseded by D041.

D038 — The DOM manifest is bounded twice: in-page for response size, server-side for what is persisted

2026-09-09 · build · accepted · Agent decided alone

Problem

The manifest is produced by code running in a remote sandbox against a page Pinata does not control, then crosses a network. Trusting the in-page pass alone would let a hostile or drifting page write unbounded, markup-bearing, or privacy-compromising data straight into Turso; re-fetching metadata in a second provider call would break the same-layout correlation with the screenshot.

Decision

The single Function API execution builds the manifest in-page with effective-visibility clipping (ancestor overflow, closed details/dialog, off-canvas, clip-path), a closed attribute allowlist, visible-text-only assembly, and deterministic vertical-stride truncation, and draws the layout nonce into the screenshot while describing it as a pinned manifest element. Server-side, result.ts enforces the exact-key schema with finite bounded numbers, then boundManifest() in src/lib/server/captures/manifest.ts re-sanitizes every string and rectangle, re-applies both caps (500 elements, 262,144 UTF-8 bytes), re-samples with the same vertical stride, adds the manifest-truncated warning when it had to drop anything, and execute.ts refuses a ready transition unless the nonce survives in the bounded manifest. POLICY_VERSION moved to 2026-09-08.7 with three new constants: MANIFEST_HINT_MAX_CHARS, MANIFEST_MAX_COMBINING_MARKS, MANIFEST_RECT_MAX_PX.

Rationale

Defense in depth with distinct jobs at each layer: the page-side pass keeps the response small and does the layout-aware visibility work only a browser can do, while the server-side pass is the authority on what is persisted and can degrade rather than fail. The nonce element pinned ahead of sampled candidates makes image/manifest correlation survive worst-case truncation. This is safe to decide unilaterally: it implements the assigned feature's published assertions inside the already-approved architecture and constants discipline.

D039 — Track a known orphan object in its own bounded table, never by rewriting the terminal capture row

2026-09-09 · build · accepted · Agent decided alone

Problem

Turso and Blob are not transactional. A capture can upload a private object and then lose its finalization fence — the capture row is already terminal and immutable, so it can never reference the object, which makes the object an orphan. The object must be deleted, but the delete itself can fail. VAL-CAPTURE-009 requires a known orphan to be deleted or represented by bounded cleanup state, and VAL-CAPTURE-008 forbids rewriting a terminal row to carry that state.

Decision

A new capture_cleanups table records exactly one known orphan per internal blob pathname, with the uploading capture id for correlation, a bounded attempts counter, a retry deadline (the new CAPTURE_CLEANUP_WINDOW_MS = 3,600,000 ms), and a last-error label — no target URL, credential, or provider URL is ever persisted. execute.ts records a cleanup row when the fenced finalization's orphan delete fails, and reconcileCaptureCleanups() deletes pending orphans (an absent object completes cleanup), retries failures inside the window, and stops incrementing past the deadline while still deleting on sight. Cleanup state lives in its own table so terminal capture rows stay untouched. POLICY_VERSION moved to 2026-09-08.8.

Rationale

The table makes the orphan a first-class, durable, queryable fact instead of a side effect, which is what lets a later cleanup pass prove no untracked orphan remains. Keeping it off the capture row preserves terminal immutability, and the attempts-plus-deadline shape satisfies the bounded-cleanup requirement. This is safe to decide unilaterally: it implements the assigned feature's published assertion inside the approved persistence architecture, using the existing migration tooling.

D040 — Publish capture fixtures to a dedicated public Vercel Blob store

2026-09-09 · validate · superseded · Human directed

Problem

The disposable fixture host behind D037 died: litterbox.catbox.moe began refusing every upload with HTTP 403 behind a BunkerWeb anti-bot, and the alternates were unusable (0x0.st disabled uploads, x0.at serves text/plain + nosniff so Chromium will not render it, filebin.net forces a redirect plus attachment disposition, paste.rs fails TLS from this machine, no tunnel client is installed). Every real-provider capture suite was blocked, so a durable fixture host needed a user decision.

Decision

Per the user's direction, publish the fixtures to a dedicated public-access Vercel Blob store. The store pinata-fixtures (store_6lu0gxibrNzwskvk) was created and connected to the pinata project's Development environment under the FIXTURE_BLOB prefix, keeping it separate from the private capture store.

Rationale

The user chose the Blob store from the options presented. On execution it proved platform-incapable: Vercel Blob force-serves every HTML-family content type with Content-Disposition: attachment, a documented anti-phishing measure ('This also prevents hosting HTML pages on Vercel Blob'). A content-type matrix probe (text/html, text/html;charset, application/xhtml+xml all attachment; only displayable types like text/plain inline) and a real Playwright Chromium navigation (page.goto aborted with 'Download is starting', the download event fired, the h1 never rendered) confirmed no upload-time override exists in @vercel/blob 2.8.0. Upload and readback otherwise worked: exact sha256 match and declared text/html.

Superseded by D041.

D041 — Capture fixtures are served by a separate unprotected static Vercel project

2026-09-09 · validate · accepted · Human directed

Problem

The user's first directed durable host (D040, a public Vercel Blob store) was proven platform-incapable of serving renderable HTML — Blob forces Content-Disposition: attachment on every HTML-family content type, verified by a content-type matrix and a real Chromium navigation that downloaded instead of rendering. The real-provider fixture pipeline was still blocked and needed a re-decision.

Decision

Per the user's re-decision, the fixtures are served by a tiny separate Vercel project, pinata-fixtures, deploying test/fixtures/capture/ (echo-v1, tall-motion-v1, manifest-v1, links-v1) as static files with deployment protection disabled. npm run fixtures:publish ensures the project exists, disables its protection, deploys the exact repository bytes, and refuses to print a URL unless each fixture reads back as a direct 200 (no interstitial or SSO redirect), inline text/html with no attachment disposition, and a byte-exact sha256 match. The durable base URL is committed in test/fixtures/capture/host.json (public and non-secret), so fixture URLs no longer depend on a per-run host. The failed D040 store (store_6lu0gxibrNzwskvk) was deleted and .env.local re-verified to hold all required variable names afterwards. This also supersedes D037's disposable-per-run host mechanism; its fixture versioning, hash-verified readback, and environment handoff all carry forward.

Rationale

A separate unprotected project is the one option that satisfies every constraint at once: inline text/html (plain static file serving, no forced disposition), durable public HTTPS URLs reachable from Browserless's network, zero coupling to the main project's protection, and no fixture content in the private capture Blob store. The published content is inert versioned markup with no secrets and no application data, so an unprotected static host carries no meaningful exposure.

Supersedes D040.

D042 — Browserless concurrency is a durable two-slot lease table; the editor polls the hierarchy on a published backoff schedule

2026-09-09 · build · accepted · Agent decided alone

Problem

MAX_ACTIVE_CAPTURES was a published constant with no enforcement: dispatch admitted every pending attempt immediately, so two browsers or two application instances could overlap more than two Browserless jobs, and a quota-rejected attempt had no defined state. The editor also had no way to watch an attempt finish: creation redirected to a list that showed pending/capturing rows forever until a manual reload, and a naive fixed-interval poller could spin forever on abandoned work.

Decision

A durable capture_leases table (migration 0003) holds exactly MAX_ACTIVE_CAPTURES slots. A dispatch claims a slot with an atomic conditional upsert that only succeeds when the slot is free or expired, so the limit holds across clients and application instances without any in-process counter. A lease expires at the published stale age (STALE_CAPTURE_AGE_MS), so an abandoned attempt becomes reclaimable at exactly the instant its row computes stale; release is conditional on the capture id, so a late release from an abandoned worker cannot free a slot a newer attempt reclaimed. A quota-rejected attempt stays pending with the catalog's quota-exceeded outcome (429 plus bounded retry guidance), resumable by any later authorized client. The editor polls the hierarchy GET on the published schedule (2 s initial, doubling to a 10 s ceiling, 10 minute deadline) and stops as soon as every attempt is terminal or computed stale; polling is read-only and can never create an attempt. The outcome catalog drives the dispatch route end to end, and two real gaps found while proving it were closed: a throwing Blob put now maps to blob-failure, and a throwing orphan delete in the fenced path now records bounded cleanup state instead of escaping as a provider error. The fixture publish readback gained a bounded retry (6 attempts, 10 s apart) so post-deploy alias propagation lag cannot fail a publish.

Rationale

Safe to decide unilaterally: the mission fixes max-2 concurrency as binding architecture, and a lease table is the smallest durable mechanism that enforces it across instances while sharing its expiry with the computed-stale boundary the state machine already publishes. The polling schedule reuses the existing authorized hierarchy read, so no new endpoint or permission shape was introduced.

D043 — Remote-network safety is proven against the real provider with a two-page fixture split driven by the provider kill-switch map

2026-09-09 · build · accepted · Agent decided alone

Problem

The in-function request guard and server-side admission are proven by focused tests, but neither can prove what the provider network does when a public-shaped name resolves private a moment after admission, and a naive all-in-one attack fixture (18 probes against every private destination shape) was destroyed outright by the provider: Browserless returned HTTP 400 Target closed for the whole session, so no outcome at all was provable. The safety property had to be mapped empirically before it could be asserted.

Decision

Map the provider enforcement boundary with bounded instrumented runs, then encode the map as two version-pinned fixtures on the durable pinata-fixtures Vercel project. remote-network-v1 (expected ready) carries the survivable matrix: RFC1918-literal fetches, image, and frame that the in-function guard aborts (recorded as bounded blocked reasons), fetches to private-resolving names (static nip.io names plus the live-alternating rbndr.us name) and through the fixture host own 302 routes into private-resolving names, WebSocket handshakes the request guard cannot see, and a worker-internal fetch. Every probe cancels its own attempt on timeout (AbortController, socket close, worker terminate, frame removal) because a silently dropped private request otherwise pends forever and keeps the page network from ever going idle, which once stalled the capture until the total deadline. Private frame probes insert only after the window load event because a connected frame delays its parent load and a dropped destination would then stall navigation itself. remote-network-hard-v1 (expected bounded safe failure with zero artifacts) carries the session-fatal literals: loopback, link-local, metadata, and both IPv6-local forms, any one of which the provider answers by destroying the browser target. The live integration suite executes both against the real provider, scans the exact persisted manifest JSON and every decoded screenshot pixel for the runtime-assembled leak marker, asserts ordinary public subresources still load, and models the post-admission DNS-change window with seeded capturing rows.

Rationale

Safe to decide unilaterally: the mission contract (VAL-CAPTURE-013) fixes the property to prove and the durable fixture host as the publication mechanism; only the empirical provider behavior was unknown, and discovering it required exactly the bounded debug runs performed. The two-page split is the smallest fixture design that matches the observed enforcement boundary without weakening any probe.

D044 — Private screenshot delivery is one non-redirecting route that reauthorizes every request and revalidates bytes before serving

2026-09-09 · build · accepted · Agent decided alone

Problem

Captures are stored as private Vercel Blob objects, but the contract (VAL-CAPTURE-010, VAL-CAPTURE-014) requires that bytes reach a browser only through an authorized application route: provider URLs and pathnames may never be disclosed, a warmed cache or old URL must never replay an image after authority ends, and delivery must return exactly the bytes the capture validated. The range/conditional semantics, the cache policy, and the integrity posture all constrain the founder-capability work in milestone 2, so they needed to be fixed explicitly rather than improvised per caller.

Decision

Serve screenshots only from GET/HEAD /api/captures/<captureId>/asset. The route verifies the live editor session on every request — including ones answered 304, 206, or by HEAD — then resolves the capture through the project hierarchy: only a ready capture of a live project with a complete, policy-shaped storage record resolves; nonexistent, non-ready, deleted-project, and integrity-failed cases share one bounded generic 404, and anonymous, expired, or tampered sessions share one 401. Range support is exactly one bytes=<start>-<end?> range (206 with Content-Range); suffix, multi-range, reversed, and non-numeric ranges are 400, and an unsatisfiable range is 416 with the published length — all settled from the persisted record before any provider read. Conditionals (If-None-Match, weak forms and *, then If-Modified-Since) are answered from the persisted SHA-256 without fetching the object. When bytes are served they are revalidated against the persisted content type, byte length, and SHA-256, and the strong ETag is that SHA-256. Every response — success, denial, and 405 alike — carries Cache-Control: private, no-store, max-age=0, X-Content-Type-Options: nosniff, Vary: Cookie, and Accept-Ranges: bytes, published as ASSET_CACHE_CONTROL/ASSET_VARY/ASSET_RANGE_UNIT in the boundary catalog (POLICY_VERSION 2026-09-09.1, five-file change).

Rationale

Safe to decide unilaterally: the mission architecture already fixes private Blob storage behind authorized application routes, and the validation contract fixes the method/range/conditional/cache matrix and the exact-bytes requirement; this record pins the interpretation (single explicit-start ranges, hash-as-ETag, fail-closed integrity, deny-all-responses-cacheable-never) inside that approved direction.

D045 — Editor project entry is one explicit four-state list machine with a single-flight retry, and e2e run cleanup lives in teardown

2026-09-09 · build · accepted · Agent decided alone

Problem

VAL-AUTH-008/009 require the authenticated project list to have distinct, announced loading, empty, populated, and failure states, with a failure retry that cannot multiply reads and an empty state offering exactly one create action. Separately, two validation sessions leaked run-scoped rows into the real Turso database because run cleanup lived in a trailing Playwright test, which an aborted or failed run never reaches.

Decision

Model the project list in EditorHome as one explicit state machine (loading / ready-empty / ready-populated / failed) rendered inside the named Projects region with aria-busy: loading is a role=status line, failure is a role=alert plus a single-flight Try again button that is disabled while its one GET is in flight, and the single New project control lives inside the region so the empty state itself offers the primary action; a failed background read never unmounts or clears an open create form, and logout renders outside the list state entirely. In e2e, all run-scoped Turso deletion (captures, pages, projects, and idempotency keys matched by run id and by the run’s page ids, since capture-retry keys store page ids) runs in test.afterAll with absence assertions inside the hook, never in a trailing test.

Rationale

Safe to decide unilaterally: the state-machine shapes follow the experience worker’s scoped-deterministic-states rules, and teardown-based cleanup is explicit orchestrator guidance recorded in the mission AGENTS.md after the 2026-09-09 leak; both are mechanical choices inside the approved architecture that this record pins for future editor-surface work.

D046 — Markdown list loops absorb wrapped continuation lines, so a blank line is the only way to end a list

2026-09-09 · build · accepted · Agent decided alone

Problem

Milestone-1 scrutiny found the hand-rolled requirements renderer consuming only list-marker lines: indented continuation lines rendered as stray paragraphs (80 severed continuations across the four source docs) and every multi-line ordered item became its own single-item <ol>, so /reqs Functional requirements rendered as eight lists numbered 1. The defect shipped because the renderer had only ever been tested against synthetic single-line fixtures.

Decision

Both list loops in src/lib/markdown.ts now consume non-blank lines that do not start another block (fence, heading, blockquote, list marker, thematic break) into the current item, joining them with a single space like paragraph wrapping. A blank line is the only terminator of a list; a non-blank line directly after a list item is absorbed into that item, so the four source documents must separate a following paragraph from a list with a blank line. The renderer is now tested against the real source documents: a structural assertion recomputes expected <ul>/<ol>/<li>/<p> counts from each source and the Functional requirements section is pinned to one ordered list of eight items.

Rationale

Safe to decide unilaterally: the behavior was mandated by the milestone-1 scrutiny finding assigned to this feature, the absorption rule matches how the four source documents are actually written (verified: no list is followed by a non-blank non-marker line and no continuation line is table-like), and the change stays inside the renderer's existing allow-listed, raw-HTML-disabled contract.

D047 — Darken the brand accent token to WCAG AA, match the Markdown external-host treatment on decision artifact links, and repair heading order and landmark uniqueness on /reqs/decisions

2026-09-09 · validate · accepted · Agent decided alone

Problem

User-testing round 1 found four blocking defects on the /reqs surface. The three external decision-artifact links rendered by src/components/decisions-catalog.tsx showed no visible HTTPS destination, unlike links emitted by the Markdown renderer. The brand red #d1495b failed WCAG AA as link text on the cream background (4.06:1) and as the badge fill behind white nav text (4.29:1); both need 4.5:1. Decision card titles were h3 directly under the page h1 (a heading-order skip), and the repeated Artifacts/Provenance/Alternatives/Consequences <section> landmarks carried identical aria-labels across every card (landmark-unique).

Decision

Darken the single global --accent token in app/globals.css from #d1495b to #c43448, which keeps the warm brand red hue while reaching 4.98:1 on --bg and 5.25:1 with --surface text, fixing the links, wordmark, home h1, error text, and the current-page nav badge in one move because every surface reads the same token. In src/components/decisions-catalog.tsx, artifact links now append the same visible (host) suffix the Markdown renderer emits, computed with new URL(url).host; card titles become h2 with in-card section labels as h3 so no heading level is skipped under the page h1; and the repeated region landmarks are scoped per decision (for example "Artifacts for D002"). The new ratios and structure are locked by test/visual-tokens.test.ts and test/requirements-decisions.test.tsx.

Rationale

Safe to decide unilaterally: the violations were found by user testing against the already-approved WCAG AA and safe-rendering requirements (VAL-REQS-004 and VAL-REQS-006), so this is a correctness fix inside an approved direction, not a product choice. The only open parameter was the exact darker hex, which is constrained by the 4.5:1 floor and reversible by editing one token.

D048 — Make scrollable /reqs regions keyboard-focusable named groups and codify the axe sweep at desktop and 390px with @axe-core/playwright

2026-09-09 · validate · accepted · Agent decided alone

Problem

User-testing round 2 found the last blocking VAL-REQS-006 defect: at 390 CSS px, axe reported scrollable-region-focusable [serious, WCAG 2.1.1] on /reqs/architecture (the horizontally scrolling <pre> ASCII diagram) and /reqs/evals (a wide .table-scroll table). Keyboard-only users could not scroll these regions because they were not focusable. Round 1 had missed this because the axe sweep ran at desktop width only, so the narrow-viewport sweep also had to become a permanent, in-repo regression test rather than a manual validator step.

Decision

In src/lib/markdown.ts, fenced-code blocks now render as <pre tabindex="0" role="group" aria-label="Code sample"> and wide tables render inside <div class="table-scroll" tabindex="0" role="group" aria-label="Data table, scroll horizontally to view all columns">, so both potentially overflowing containers are in the tab order and carry an accessible name. The axe sweep is codified in e2e/requirements-a11y.spec.ts using @axe-core/playwright 4.13.0 (added to the approved dev-dependency allowlist in scripts/lib/approved-deps.mjs): all five /reqs routes are swept with wcag2a/wcag2aa tags at both 1440px and 390px and must show zero serious-or-critical violations, and the two known scrolling regions must prove real keyboard operability at 390px by receiving Tab focus and moving scrollLeft with ArrowRight.

Rationale

Safe to decide unilaterally: the feature assignment from user-testing round 2 directed both the focusable-scroll-region fix and the in-suite narrow axe sweep, so this implements an approved correction rather than a product choice. The only open parameters were the ARIA role/label wording and the specific axe package, both constrained by WCAG 2.1.1 and the existing validator tooling, and both reversible in one module.

D049 — Drive pending capture dispatch from the editor client, bounded by the durable lease cap and re-driven by the polling loop

2026-09-09 · build · accepted · Agent decided alone

Problem

User-testing round 1 found the capture-driver gap: project creation commits two pending attempts per page, but nothing ever dispatched them, so every capture sat in the Queued state forever unless someone hand-called POST /api/captures/:id/dispatch. The server deliberately schedules nothing itself — the durable two-slot lease table is the only concurrency authority — so the missing piece was a client that turns committed pending rows into dispatch requests, including after a reload or a return to the editor with work still pending.

Decision

The editor home now runs a dispatch driver next to the existing capture-progress poller, with the policy kept pure in src/lib/capture-dispatch.ts. Every hierarchy read that shows pending attempts (the initial load, the post-create re-read, a retry's re-read, or a poll tick) feeds pendingDispatchTargets, which lists pending attempts in deterministic project/page/device order, and nextDispatchBatch, which keeps at most MAX_ACTIVE_CAPTURES dispatches in flight from this client and skips attempts already in flight or inside their re-drive delay. A dispatch that settles (ready, or any attempt-consuming catalog outcome read from the response body) triggers one hierarchy re-read so the workspace surfaces the outcome and the freed slot drives the next pending attempt. A quota-exceeded 429 leaves the attempt pending and defers it for CAPTURE_DISPATCH_REDRIVE_DELAY_MS (defined as the published initial poll interval, not a new constant), so the polling loop is what re-drives it once a slot has had time to free; a 409 conflict or an untrustworthy answer defers the same way, which makes even a stale-read race a bounded one-attempt-per-poll-tick retry rather than a storm. No new endpoint exists, the hierarchy GET stays read-only, and provider execution still happens inside the dispatch request.

Rationale

Safe to decide unilaterally: the architecture document already states the client schedules captures at most two in parallel, and the feature assignment (from the user-testing round 1 finding) directed closing exactly this gap, so the remaining choices — deterministic target order, an in-flight guard, and a deferral window equal to the initial poll interval — are mechanical and reversible inside src/lib/capture-dispatch.ts.

D050 — Trim milestone 1: defer first Vercel deployment and the variant/retry integration matrix to milestone 2

2026-09-08 · build · accepted · Human directed

Problem

Milestone 1's critical path ran through its two longest-lead items before the user could ever see the product: a first Vercel production deployment carrying the real Chickpea project, and a standalone variant/retry integration matrix feature. Both were validation surfaces, not new product behavior — the underlying variant-isolation, stabilization, no-crawl, and partial-failure assertions were already covered by the surviving capture features — and waiting on them delayed the first live headed-browser checkpoint.

Decision

Per the user's scope trim, milestone 1 no longer includes a Vercel deployment or the standalone variant/retry integration feature. The capture-variant-partial-retry-integration and production-chickpea-capture-and-deployment features are cancelled with their assertions re-homed into the surviving capture features (no coverage lost). Milestone 1 validates the capture-and-organize slice locally as a production build on 127.0.0.1:3100, including live captures of Chickpea's root and its explicit /pricing, /about, and /privacy URL array. The first Vercel production deployment and the real production Chickpea project move to milestone 2 (real-chickpea-pin-and-founder-review), where deployment-backed assertions are re-verified against the real deployment.

Rationale

The user directed both the trim and its contents, so the decision is recorded as user-directed with the verbatim request. The trim is coverage-neutral by construction — every assertion from the cancelled features was re-homed — and it is reversible: milestone 2 reinstates the deployment and the production Chickpea project as its own validation surface.

D051 — Materially descope the post-milestone-1 roadmap: keep pins, pin comments, landing page, first deployment, short pins session, and closeout; punt everything else

2026-09-09 · validate · accepted · Human directed

Problem

After the milestone-1 capture checkpoint, the remaining roadmap (founder capability links and read/reply surface, append-only threads, rich marks, the warm visual system, performance and one-minute-demo work, milestone-3 accessibility, production hardening, editor session-lifecycle hardening, cross-surface auth/secret hardening, and the final production acceptance session) was larger than the user's remaining budget. The user wanted to validate only the two things the product exists for: the screenshot captures and pinned-annotation commenting.

Decision

Per the user's direction, the mission is materially descoped. In scope: the editor canvas with pins and pin comments, nearby-DOM metadata on pins, the branded landing page, the first Vercel production deployment with production Chickpea captures, a short headed pins session with the user, and final docs closeout. Punted for later revisit: founder capability links and the founder read/reply surface, append-only two-way threads, rich marks (rectangles, circles, arrows), the warm-visual-system milestone, performance/one-minute-demo, milestone-3 accessibility features, production hardening (partial-failure drills, redeployment continuity, capability rotation, dogfood project), editor session-lifecycle hardening, cross-surface auth/secret hardening, and the final production acceptance session (replaced by the short pins session).

Rationale

The user directed the descope verbatim after the milestone-1 checkpoint, so this is recorded as user-directed. The kept slice (captures plus pinned comments) is exactly what the user said they want to validate; everything else remains documented as the product vision for later revisit.

D052 — Add a temporary local-only editor auth bypass flag (PINATA_AUTH_DISABLED), default off, never in .env.local or any deployment

2026-09-09 · build · accepted · Human directed

Problem

For live local checkpoint sessions the user does not want to sign in through the editor password prompt every time; auth is deliberately low priority right now. But the real auth posture (anonymous denial, login, throttling) must keep being proven by the validation gate and validators, and production must keep auth.

Decision

Add PINATA_AUTH_DISABLED as a server-only environment flag, default OFF. When set to exactly '1' (inline on the server command line, e.g. PINATA_AUTH_DISABLED=1 npm run start), server-side session verification treats every request as an authenticated editor with a synthetic session: the landing page renders the editor workspace directly and all editor APIs authorize, with the double-submit CSRF proof skipped because no real session cookie exists (route-level same-origin checks still apply). When unset, behavior is byte-identical to before, and the login route keeps working in both modes. The flag is never a NEXT_PUBLIC_* variable, never read from client code, never added to .env.local (so the gate and validators keep proving real auth), and never set in any Vercel environment.

Rationale

The user directed the bypass verbatim and framed it as temporary ('for now'), so this is user-directed and scoped as narrowly as possible: one server-only check in the session guard and the landing route, default off, with focused tests proving both modes and source checks proving the flag never reaches client code or .env.local.

D053 — Correct the checkpoint capture target: the seeded and demonstrated Chickpea is https://chickpea.co, not chickpea.vercel.app

2026-09-10 · validate · accepted · Agent decided alone

Problem

The orchestrator's reopened milestone-1 checkpoint feature text named https://chickpea.vercel.app as the pre-seed capture target. That host is an unrelated third-party chickpea-exporter template whose /pricing, /about, and /privacy all return 404, so three of its four pages cannot produce meaningful captures at all. The mission's actual Chickpea product — the target used by every mission document and every prior capture validator — is https://chickpea.co ("Chickpea: AI teammates in Slack"), with all four pages live.

Decision

Seed and demonstrate https://chickpea.co (root plus /pricing, /about, /privacy) as the milestone-1 checkpoint project, and record this correction so the feature-text discrepancy stays auditable rather than silently resolved. The user confirmed the chickpea.co target during the 2026-09-09 checkpoint session.

Rationale

Safe to decide unilaterally: the choice was a factual correction to match the target the mission had always used, not a product-direction choice, and it was flagged to the user and orchestrator in the Phase A handoff rather than silently swapped. The origin stays agent-autonomous because the in-session user confirmation (2026-09-09) was relayed without a preserved verbatim quote, and this log does not upgrade provenance without the evidence the taxonomy requires.

D054 — Decide later whether an execution-time, provider-side unsafe-redirect should stay non-retryable

2026-09-10 · validate · superseded · Raised and deferred

Problem

During the user-directed pre-seed, the Chickpea Mobile-root capture attempt 1 failed with unsafe-redirect — an execution-time final-URL inconsistency inside the provider session, not reproducible via curl or Playwright mobile emulation, i.e. a transient provider-side flake rather than a genuinely unsafe target. The outcome catalog deliberately marks unsafe-redirect retryable:false (the catalog row exists so the admission layer cannot be used as an oracle), so the product offered no recovery path for what was effectively provider flake; the worker had to insert a pending attempt row directly in Turso and dispatch it through the real route to get the ready attempt 2. The failed attempt remains visible in the demo project tree.

Decision

Deferred. The question was raised to the user as a checkpoint talking point and the user never reacted to the failed Mobile-root attempt during the session, so it stays open: should an execution-time unsafe-redirect (raised after admission, inside the provider session) be distinguished from an admission-time unsafe target and made retryable, or should the catalog stay as is?

Rationale

Raised by the checkpoint worker in its Phase A handoff and carried by the orchestrator as a session talking point; the user did not answer it during the 2026-09-09/10 session. Per the provenance taxonomy a consciously postponed item is user-deferred with status pending until answered, then superseded by the record that answers it.

Superseded by D095.

D055 — The canvas opens every capture with the entire page in view (contain); width-fit and natural size remain named modes

2026-09-10 · build · superseded · Human directed

Problem

At the milestone-1 live checkpoint the human could not take in a tall capture (~9,000 px) without scrolling: the interim stage defaulted to a natural-size slice. The permanent React Flow canvas needed an initial camera, and a wrong default would enshrine the rejected behavior.

Decision

Every capture opens with the camera contain-fitted so the entire screenshot is inside the viewport with a small padding. Width-fit and natural-size stay reachable as named pressed-state modes; any pan/zoom gesture ends the mode's resize-follow until a mode is picked again. The camera is local UI state only: never persisted, never written to browser history, and issuing zero annotation mutations.

Rationale

Verbatim checkpoint instruction. Contain makes the first thing a reviewer sees the whole page, while the named modes keep precise inspection one click away.

Superseded by D145.

D056 — Pin geometry lives in a pure adapter (canonical tip plus zoom-aware hit box); annotation children carry no React Flow parent extent, and the drag grab offset is captured once per gesture

2026-09-10 · build · accepted · Agent decided alone

Problem

Bringing draft pins onto the canvas needed answers to three coupled questions: what the canonical geometry of a pin is (so persistence later stores one unambiguous fact), how a pin stays grabbable at every zoom without its anchor drifting, and who clamps drags at the frame edge. End-to-end testing then exposed that React Flow's parent-extent clamp rewrites emitted drag positions at the frame edge, which stranded the re-derived tip one grab offset inside the boundary (a tip dragged to the corner settled at natural (1.5, 3) instead of (0, 0)), and that React Flow re-emits the final drag position on pointer-up, which advanced a frame-clamped tip with no pointer movement at all.

Decision

The canonical pin fact is the tip in screenshot-natural CSS pixels. A pure adapter (src/lib/canvas/geometry.ts) owns all conversions: an inclusive document clamp, and a hit box whose on-screen edge never drops below the shared 24px minimum target (it grows in natural units as zoom deepens) while the tip stays recoverable exactly as box plus recorded offsets. Draft pin nodes are React Flow children of the screenshot frame WITHOUT extent: "parent" — the adapter is the single clamping authority. The drag grab offset is captured once at drag start and held for the whole gesture. Placement taps are disambiguated from drags by a 6px screen slop, and the draft is transient local UI state (one per plane, Escape clears, never persisted).

Rationale

These are technical choices inside the already-approved canvas-and-pins direction (D051, D055): they change no user-visible scope, add no dependency or server contract, and were forced by measured end-to-end behavior, so they were safe to decide without surfacing. A single pure adapter keeps every screen-to-natural conversion in one tested boundary, which is what makes the one-natural-pixel inverse-transform contract provable at 1x and 8x.

D057 — Capture-driver e2e asserts the server fence (one claiming answer, fenced redrives) instead of a fixed per-attempt dispatch count

2026-09-10 · build · accepted · Agent decided alone

Problem

Under full-suite parallel load the capture-driver e2e flaked on two counting assertions that encoded wrong premises: an in-flight watermark measured at requestfinished (but the client caps by promise settlement, and a 2xx fetch resolves at response headers, so body-delivery lag read as a phantom cap violation), and a hard bound of two dispatches per attempt (but a hierarchy read that still shows a just-claimed row as pending legitimately re-drives the attempt, and the reload race can hide the claiming 2xx from the page entirely). The durable contract — the server fence claims an attempt at most once and every later dispatch is fenced — was never actually broken.

Decision

The test now counts a dispatch as in flight only until the server answers (response event), and per attempt asserts the real invariant: at most one 2xx claiming answer, every other answer fenced (409 conflict or 429 quota), and a small absolute dispatch bound (8) so "never an unbounded retry" stays explicit.

Rationale

Test-only change that strengthens what is actually proven (the fence, the cap, the stand-down) while dropping a count bound whose premise read-after-write timing invalidates. Safe to decide unilaterally: no product code, route, or schema changes, and the new assertions fail loudly if the fence ever really breaks.

D058 — The canvas documents its own interactions on the page: pan, zoom, pin drop, comment, save, cancel, and opening a saved pin are all taught by persistent on-page instructions

2026-09-10 · build · accepted · Human directed

Problem

A first-time user opening a capture had no way to discover the pin workflow: the canvas supported pan, zoom, an explicit Place pin mode, drafts, and saving, but nothing on the page said so. The reviewer directive was explicit that the page itself must teach the workflow.

Decision

The workspace carries a persistent plain-language hint above the canvas that names every real interaction of this build: drag to pan, scroll or pinch to zoom, the camera buttons, Place pin mode with click/tap to drop a pin, writing a comment and pressing Save pin, Escape or Cancel discarding a draft, clicking a saved pin or its Pins-list entry to read its comment, and dragging a pin to move it. The empty pins panel repeats the discovery path, and the hint names no affordance that does not exist (no dead 'coming soon' features).

Rationale

Direct execution of the verbatim request. The hint is intentionally exhaustive about the current build and nothing beyond it, so it can never drift into promising dead affordances.

D059 — Pin persistence: server-assigned monotonic numbering inside the idempotency transaction, one create per saved draft, one revisioned write per drag, and authoritative reloads after failure

2026-09-10 · build · accepted · Agent decided alone

Problem

Persisting pins raised four coupled protocol questions: who assigns pin numbers (and how cancelled or failed drafts must never consume one), how a retried or double-submitted save stays exactly-once, how a drag move commits without write amplification, and what the UI shows when a write fails.

Decision

The server assigns numbers inside the create transaction as max(number)+1 over ALL rows of the capture including tombstones, backstopped by the (capture_id, number) unique index with a bounded collision retry, so deleted or failed numbers are never reused and drafts never reserve one. The annotations create route is idempotency-record-first: an exact replay returns the original record, a key reused with a different payload conflicts, and a failed validation consumes nothing. The client holds one idempotency key per draft intent, POSTs once per Save, and re-reads the capture's pin list after success rather than patching local state. A pin drag is local-only movement committed as exactly one revisioned PATCH at drag end (capture-bound, bounds-validated, revision-bumped); a failed move shows a bounded error and reloads the authoritative list so the pin snaps back. Camera, selection, and cancel paths issue zero writes.

Rationale

These are protocol choices inside the already-approved pins direction (D051) and the existing idempotency/revision pattern the capture and reply routes established; they change no user-visible scope and add no dependency, so they were safe to decide without surfacing. Reusing the established boundary order (same-origin, session+CSRF, content-type and byte cap, strict schema, durable write) keeps the new routes inside the reviewed envelope.

D060 — Navigate mode never moves a mark and a tap on a saved pin selects it; pin dragging lives in Place pin mode, and e2e specs share the seeded plane by horizontal bands

2026-09-10 · build · accepted · Agent decided alone

Problem

Once persisted pins existed on the seeded capture, the full parallel e2e suite exposed three interaction holes: a pin-mode tap on an existing pin both selected it AND stacked a hidden draft on it; a camera-spec pan that happened to press a pin badge dragged the pin and committed a real PATCH during what the user meant as navigation; and three specs independently aiming their taps at the default pane center collided with each other's pins (a badge's 24px hit box spans hundreds of natural pixels at overview zoom, so per-point margins cannot keep taps clear).

Decision

Persisted pins are draggable only in Place pin mode: in Navigate mode a press anywhere — including on a badge — pans, and camera work can never produce an annotation write. A pin-mode tap on a saved pin is selection, never placement. Draft pins stay draggable in any mode (adjusting a draft after switching back is the shipped flow) because drafts are transient and write nothing. In the e2e suite, gesture specs aim inside a middle document band while the pins spec writes into a bottom band via a shared lattice helper (findClearAim), making cross-spec collision structurally impossible rather than margin-unlikely.

Rationale

Measured end-to-end failures forced each half: the mode gating and tap-selects rule resolve real write-on-pan and draft-stacking behavior, and band separation is the only aim strategy that survives the hit box's natural-pixel size at overview zoom. Both are inside the already-approved canvas direction (D051, D055, D056) and change no shipped scope, so they were safe to decide unilaterally.

D061 — Pin mutation lifecycle: explicit context decision with server-derived snapshots, expectedRevision optimistic concurrency on move/edit/delete, tombstone deletes, and authoritative reloads after conflict

2026-09-10 · build · accepted · Agent decided alone

Problem

Comments and mutations on pins raised four coupled contract questions: how a draft's metadata decision stays explicit and honest (never a client-authored element object), how concurrent edits/moves/deletes of the same pin resolve without lost updates or ghost records, what a delete means for numbering, and what the UI shows when the write it attempted was already superseded. D059 had scoped the first build to create+move only; the comment lifecycle needed edit and delete to ship with the same safety properties.

Decision

A draft cannot save until Lucas explicitly chooses a nearby candidate or "No element"; only the candidate's capture-local id (or null) crosses the wire, and the server derives the bounded snapshot from the capture's own persisted manifest (an unknown id rejects the create and persists nothing). Candidates come from a new authorized read route that ranks the persisted manifest deterministically (containment, distance, area, depth, semantic kind, id tie-break) and caps the result at the shared limit. Every mutation carries expectedRevision and commits through one conditional UPDATE guarded by the current revision (drizzle .returning() pattern from the capture transitions): a stale or losing write gets 409 and changes nothing, a write against a foreign or tombstoned pin gets the generic 404, and the UI answers any conflict by reloading the authoritative list instead of overwriting it. Delete is a tombstone: the row stays, the number stays retired (D059 numbering already counts tombstones), and later writes against it are rejected. The context snapshot is immutable for the pin's life: moves and edits never re-query or rebind it. This extends D059's move-only scope note; its numbering and idempotency mechanics are unchanged.

Rationale

The validation contract (VAL-PIN-002/003/008/009) names exactly these behaviors — explicit decision, revisioned mutations, immutable capture-bound snapshots, one authoritative revision under concurrency — and the implementation reuses the already-approved conditional-write and boundary patterns, so no product-direction approval was needed. The e2e suite stages real two-session races (same browser, direct route writes) and asserts the UI settles on the winner.

D062 — Anchor node drags at pointer-down: React Flow nodeDragThreshold set to 0 after e2e caught every drop landing a few pixels short

2026-09-10 · build · accepted · Agent decided alone

Problem

The pin-lifecycle e2e measured a dragged pin landing exactly one pointermove step short of the drop point (3 screen px in a 50px drag) on every run. Reading the installed @xyflow/system source showed why: with the default nodeDragThreshold of 1, startDrag captures the drag origin at the first pointermove past the threshold, so the initial travel is never applied to the node — a systematic drop error, not jitter.

Decision

The canvas sets nodeDragThreshold={0} so drags anchor at pointer-down and the full pointer delta is applied. Click-versus-drag disambiguation stays with d3-drag's clickDistance, which already governs selection clicks, so tap-to-select is unchanged.

Rationale

The failure was measured end-to-end and the library source confirmed the mechanism; the fix is one prop inside the already-approved React Flow canvas, so it was safe to decide unilaterally. jsdom cannot run d3-drag, so the e2e drag assertions are the regression guard.

D063 — Fix the tall-motion-v1 focus flake in place: wire interaction counters before the scripted caret focus and exclude that focus by target

2026-09-10 · validate · accepted · Agent decided alone

Problem

The real-provider motion suite intermittently failed its zero-interaction-counters assertion: tall-motion-v1 focused #caret-box before wiring its interaction counters, and Chromium defers focusin delivery for a page that is not focused yet, so the fixture's own scripted focus could land after the listeners were attached and be counted as an interaction (the known flake from user-testing round 1).

Decision

Edit tall-motion-v1 in place rather than publishing a v2: the interaction counters are wired before the #caret-box focus call, and the focusin listener ignores events targeted at the fixture's own #caret-box, so the fixture's scripted focus is excluded deterministically no matter when Chromium delivers the event. Republished through npm run fixtures:publish, which re-verified a byte-exact readback and updated host.json.

Rationale

The mission feature fixture-tall-motion-focus-ordering, created from the user-testing round 1 handoff, directed the in-place ordering fix; the exclusion-by-target is the smallest mechanism that makes the counter deterministic under deferred event delivery. Safe to decide unilaterally: it is a fixture-only change with no product surface, and the real-provider suite proves it three consecutive runs.

D064 — Candidate context preview as a transient inert React Flow node, a quiescent marker for the context panel, and an authorized verbatim manifest read route

2026-09-10 · build · accepted · Agent decided alone

Problem

The nearby-DOM context selection feature needed three mechanisms that constrain every future canvas and panel change: how Lucas previews a candidate's captured bounds before choosing (without the preview ever persisting or intercepting canvas gestures), how e2e specs survive the context panel's async candidate render (a radio detached mid-click caused the known full-gate flake), and how the deferred HTTP-surface half of VAL-CAPTURE-006 (an authorized fetch of persisted manifest JSON scanned for forbidden-source values) can run at all when no manifest read route existed in milestone 1.

Decision

Preview is a dedicated contextPreview node type: a pointer-transparent, aria-hidden, non-draggable child of the capture frame whose position and size are exactly the candidate's persisted manifest rect, driven by transient workspace state that clears on hover/focus/touch end, choice, cancel, save, and plane switch. The context panel exposes a data-candidates-state quiescent marker (loading/ready/failed) and gives the No-element radio a stable key and value so the loading-to-ready transition can never detach it; all e2e radio interactions wait for the marker first. A new GET /api/captures/[captureId]/manifest route serves the persisted manifest bytes verbatim (no-store) under the same live-authority guard as the context route, making the sentinel scan a scan of the persisted record itself.

Rationale

The mission feature nearby-dom-context-selection directed all three mechanisms, including the quiescent marker and the deferred sentinel-scan evidence. Safe to decide unilaterally: every choice is inside the approved canvas architecture, adds no dependency, and is covered by focused Vitest suites plus three new e2e specs. One implementation discovery matters for the future: React Flow 12.11 computes a node wrapper's pointer-events from interactivity and ignores the Node pointerEvents field, so the preview's pointer-transparency is carried by node.style, which spreads after the computed value.

D065 — Run-scoped e2e cleanup runs in the Playwright global teardown, never in afterAll

2026-09-10 · build · accepted · Agent decided alone

Problem

Real-capture e2e suites create run-scoped Turso rows and Blob objects against the one shared local store while sibling specs observe it: every signed-in page auto-selects the newest project's first device. Two full-gate runs showed that deleting run rows in a spec's afterAll races sibling workers — projects.spec failed its console-error gate on a 404 from a capture its page was still displaying, and a hijacked pins.spec run left a stray pin that FK-blocked the captures delete. A run-scoped project whose root URL is a query-suffixed Chickpea URL also matched findReadyTarget's seeded-first regex, pulling concurrent specs onto the disposable plane.

Decision

Deletion is coordinated by timing, not scope: suites register their run id plus annotation body prefixes in a file registry (e2e/.run-cleanup/, gitignored) in afterAll — a fast local write that survives test failure — and the Playwright global teardown, which runs after every worker's last page has closed, deletes annotations, blobs, leases, captures, idempotency keys, pages, and projects by run id, verifies absence, removes the registry entry, and fails the run on any leftover. The registry lives outside test-results/ because Playwright wipes that directory at the next run's start, so a crashed run's entries survive to the next teardown, which mops them up idempotently. Run-scoped projects are additionally rooted on the fixtures host (links-v1, manifest-v1, tall-motion-v1) so their URLs can never match findReadyTarget's seeded Chickpea regex.

Rationale

Agent-autonomous inside the mission's sanctioned pattern (the mission explicitly anticipates an orchestrator-approved Playwright global teardown for cross-suite cleanup). The teardown hook is the single point where no browser page can still observe the store, and the file registry survives both individual test failures and whole-run crashes.

D066 — The root route is a branded landing page: the pinata mark directly above the URL capture entry, a brief value proposition, a fully static example of a marked-up capture, and a clear sign-in path

2026-09-10 · build · accepted · Human directed

Problem

The root route was a bare product blurb plus a password prompt. An anonymous visitor could not tell what Pinata does, and the URL capture entry — the product's front door — only existed behind sign-in. The user asked for a real landing page, deliberately saved for the end of the build and kept (small, already specified) through the D051 descope.

Decision

Rebuild / as the branded landing page for every visitor. The pinata mark — an accent tile carrying the product's own pin teardrop with a starburst, drawn once in src/lib/brand-mark.ts — renders inline above the capture entry and doubles as the favicon (app/icon.svg), with zero external image assets. The entry form takes a required root URL plus optional additional-URL rows with one visible primary action. Below the hero, a fully self-contained static example render (fixture data in src/lib/example-capture.ts) shows a screenshot region with two numbered pins, a two-entry comment thread, and a DOM metadata panel; it makes no /api/* request and no database access, and it depicts saved thread content only — no founder reply UI (D051). Anonymous visitors additionally get the editor sign-in prompt; a signed-in editor lands on the same branded page with the project form active, the project list below it, and the example after that.

Rationale

This is exactly what the user directed on 2026-09-08 and confirmed keeping on 2026-09-09; the implementation mechanics inside that direction are D067.

D067 — Anonymous capture entries park in same-tab sessionStorage and route to the on-page sign-in prompt; the editor form consumes the draft exactly once

2026-09-10 · build · superseded · Agent decided alone

Problem

VAL-LANDING-003 requires the anonymous capture entry to survive the sign-in round trip: submit as anonymous, sign in, land back on / with the URL input retained, then create the project with exactly one POST /api/projects. The handoff mechanism had to move user-typed URLs from the anonymous page to the post-login editor form without an unauthorized write.

Decision

The anonymous entry validates a non-blank root client-side, parks { rootUrl, urls } in sessionStorage under pinata:capture-draft, and routes to the existing on-page sign-in section by moving focus to the password field (scroll honoring prefers-reduced-motion) — no request is made. After sign-in, the server re-renders / for the verified session; the editor home reads and removes the draft in a mount effect (StrictMode-safe: the first read wins), and the always-active project form initializes straight from it. Creating the project is the form's existing single POST with its own idempotency key.

Rationale

Mechanical plumbing inside the user-directed landing direction (D066): it changes no product direction, touches no authorization rule, and the failure mode (storage unavailable or a malformed entry) degrades to a blank form. The consumed-once read prevents a reload from resurrecting a stale draft; malformed entries are validated and discarded, never thrown.

Superseded by D103.

D068 — Deploy to Vercel production behind SSO protection, fixing the framework preset and adding a Protection-Bypass-for-Automation secret for the smoke

2026-09-10 · build · accepted · Agent decided alone

Problem

The first production deployment (D051) had to satisfy two hard constraints at once: deployment protection stays ON for the pinata project, and the production smoke (editor login, real Chickpea capture, private asset denial, pin persistence, /reqs hub) must run against the real deployment. The project was also still on the "Other" framework preset from before the Next.js stack landed, so the GitHub-triggered production builds of the validated commit were failing with Error status.

Decision

Set the project framework preset to Next.js via the Vercel API, deployed the exact validated commit 523dcd9 with `vercel deploy --prod` (the CLI attaches the local git metadata, so VERCEL_GIT_COMMIT_SHA and the deployment record both carry the commit SHA the /reqs pages display), and enabled Vercel Protection Bypass for Automation: one high-entropy project secret, marked as the VERCEL_AUTOMATION_BYPASS_SECRET source, sent only as the x-vercel-protection-bypass header by the smoke tooling. SSO protection (all_except_custom_domains) is unchanged; the secret lives in Vercel and a local 0600 scratch file, never in the repository, logs, or .env.local.

Rationale

Protection Bypass for Automation is Vercel"s documented mechanism for exactly this situation: it keeps the SSO wall up for every party without the secret while letting automation through with a revocable, rotatable credential. Both hard constraints hold at once. The choice is mechanical execution inside the already-directed deployment scope (D051, and the readiness note that the deployment feature must fix the framework preset), not a product-direction change, so it was safe to decide without a round trip.

D069 — Split the public landing from the editor workspace: / stays marketing, /pins is the app, /pins/new holds the project form

2026-09-10 · build · accepted · Human directed

Problem

One route was doing three jobs. `/` rendered the branded hero, the always-active project form, the static example capture, and the whole project workspace stacked underneath. Every visit to the working surface therefore paid for a screenful of marketing before reaching the canvas, and the project form sat permanently open whether or not a project was being created. The landing's hub link had the same collapsing problem in miniature: the five titles 'Requirements, architecture, milestones, decisions, and evals' were one anchor pointing at /reqs, so clicking 'Architecture' landed on the hub rather than /reqs/architecture, even though all five routes already existed.

Decision

Three routes with one job each. `/` is the public landing only — hero, anonymous capture entry, static example, sign-in, and five separate hub links generated from REQUIREMENTS_NAV. A verified editor session at `/` is redirected to `/pins`. `/pins` is the working surface: a compact header (home, New project, Sign out), the project workspace, and nothing that competes with the canvas. `/pins/new` carries the project form on its own route and hands off to `/pins` once the project commits. Both editor routes redirect an unverified visitor back to `/`, and all three share one server-side predicate (src/lib/server/auth/editor-page.ts) so the boundary cannot drift between them. Sign-in navigates rather than re-rendering in place, and routes to `/pins/new` when a parked anonymous draft (D067) is waiting so that handoff still works.

Rationale

The user reported both symptoms together — the hub titles all landing on the same page, and the marketing surface crowding the app — and they have the same shape: one thing standing in for several. Splitting by route makes each surface addressable, lets the redirect rather than a conditional render carry the authorization boundary, and gives the 'New project' link somewhere to go.

D070 — Collapse the project rail into nested native disclosures, open only around the current selection

2026-09-10 · build · accepted · Human directed

Problem

The left rail printed every project's entire page and device tree at once. With more than a couple of projects the canvas was pushed off screen, and the rail gave no way to put a project away once its captures were reviewed.

Decision

Two levels of native <details>: one around the whole rail labelled 'Projects' with a count, and one per project around its pages and devices. The rail starts open; a project starts open only when it holds the current selection, and stays wherever the reader last put it. The disclosure state is session-only React state, never persisted. Each project keeps its heading for assistive technology, now visually hidden inside the disclosure while the summary carries the visible title.

Rationale

Native disclosures are keyboard-operable and correctly announced with no dependency and no script, which matches the repository's standing constraint. Anchoring the default to the selection means the rail is never hiding the thing the reader is looking at, while every other project folds away.

D071 — List every pin in a table below the canvas, with a Markdown export for pasting into an agentic IDE

2026-09-10 · build · accepted · Human directed

Problem

The side panel shows one pin at a time. That is right for editing, and useless for the thing the pins are ultimately for: handing a page's worth of feedback to a coding agent. Getting all of it out meant clicking each pin in turn and copying the comment by hand, losing the element context that makes a note actionable without the screenshot.

Decision

A table under the canvas listing every pin on the active capture — number, natural-pixel position, element summary and DOM path, and the comment — plus one 'Copy all as Markdown' control. The Markdown is produced by a pure function (src/lib/pin-export.ts) so the exact text that reaches the clipboard is unit-testable; it heads the block with the page, device, and version, and gives each pin its position, element, path, bounds, and its comment quoted verbatim. Selecting a row selects the pin everywhere else, so the table is a second route to the same state rather than a second copy of it.

Rationale

The element snapshot is the only durable record of where a note points — the capture is a screenshot and the manifest is never re-derived after save (VAL-PIN-003, VAL-PIN-008) — so an export that omits it is not actionable. Emitting the body inside a blockquote keeps arbitrary comment text intact without escaping the content that matters most.

D072 — Build a ten-slide interactive walkthrough of Pinata with Remotion, borrowing the repository's existing imagery

2026-09-10 · wrap · accepted · Human directed

Problem

Explaining the product and the process mattered as much as building it, and the only explainer surfaces were prose: README, the /reqs hub, and the decision log. Nothing walked a first-time viewer through what Pinata is and how the four steps fit together in a form that could be played, paused, and pointed at during a demo.

Decision

A Remotion composition of exactly ten slides (title, the problem, who it is for, the four steps, guardrails, the stack and gate, the decision trail), 1920 x 1080 at 30 fps, about 104 seconds end to end. Every slide paints with the application's own color tokens and the shared brand mark, and the imagery is borrowed rather than invented: the brand exploration board that was already committed at the repository root (cropped into tiles), and the two dashboard screenshots already attached to D004 and D066. One slide table (remotion/walkthrough/slides.ts) carries the chapter names, durations, and a prose transcript, and is the single source for the video, the chapter navigation, and the on-page notes.

Rationale

Directed by the user. Remotion keeps the walkthrough in code, typed by the same tsconfig as the app and covered by the same gate, and its Player lets the same composition run in the deployed product, so the walkthrough is demoable over a link rather than only from a checkout. Borrowing the committed board and screenshots keeps the visual language honest: it is the product's own material, not stock.

D073 — Host the walkthrough inside the app at /walkthrough through @remotion/player, keep the Remotion CLI dev-only, and widen the dependency allowlist to match

2026-09-10 · wrap · accepted · Agent decided alone

Problem

D072 asked for Remotion and for the walkthrough to be interactive, but not where it should live. Remotion can run three ways: in Studio from a checkout, as a rendered MP4, or in the browser through @remotion/player. Each has a different footprint on the one-lockfile, allowlisted-dependency repository, and only one of them is reachable from the deployed product.

Decision

The composition lives in remotion/ inside the one package, typed by the app's tsconfig. The Next.js app mounts it at the public route /walkthrough through @remotion/player, wrapped in a chapter list that seeks the player to a slide, Previous/Next controls, arrow-key navigation, and the transcript for the chapter on screen. remotion and @remotion/player join the application dependencies; @remotion/cli is a devDependency for Studio and the MP4 render. All three are pinned exactly and added to scripts/lib/approved-deps.mjs, the allowlist the gate enforces. The landing page links to the walkthrough; REQUIREMENTS_NAV is untouched because the walkthrough is not a Markdown-backed requirements source and must not enter the dogfood URL array.

Rationale

Decided without asking because the user had already fixed the direction (Remotion, interactive, about ten slides) and these are the mechanics inside it. The AGENTS.md rule is no unrequested dependencies; Remotion was requested, and the allowlist edit is the recorded mechanism for admitting it, not a new direction. Choosing the Player over Studio-only follows the standing demo-first rule. Keeping the CLI dev-only keeps the production bundle to what the page needs.

D074 — Drop a pin with one gesture: no interaction modes, a composer anchored at the pin, a pre-selected element with overrides, and keyboard equivalents

2026-09-12 · build · accepted · Agent proposed, human approved

Problem

Placing a pin took a mode switch (Navigate to Place pin), a click, a comment typed in the side panel far from the click, a mandatory choice between a nearby element and 'No element' before Save would enable, the save itself, and a switch back to Navigate to pan again. The on-page explanation of that ran to about 120 words. The milestone-1 live checkpoint (EVALS M1-LIVE-3, M1-LIVE-4) had already recorded the owner unable to discover the pin mechanism; adding the modes made it explainable, not discoverable.

Decision

One interaction model with no modes. A press on the screenshot that releases without moving past the placement slop drops a draft pin; a press that moves pans the camera; a saved pin drags by its badge in every state, committing one revisioned move at drag end as before. The comment composer opens in a popover anchored beside the draft badge, screen-fixed against the plane's transform so it never leaves the viewport; the side panel keeps the full detail view and the pins list. The nearby-element decision stays explicit in the data (the client still sends a candidate id or null and the server still derives the snapshot, D061) but the top-ranked candidate is pre-selected and shown as one chip with 'Change' and 'No element' controls, so the common case is type, then Enter. Keyboard: Enter saves a draft (Shift+Enter inserts a newline), Escape cancels, J/K or the arrow keys step through saved pins, N drops a draft at the viewport center. The two-mode toolbar and the long hint are removed; a short line under the canvas names the three verbs.

Rationale

Proposed by the agent from the code review and the checkpoint evidence, approved by the human in the same message as the rest of the overhaul. The data contract does not change: drafts still write nothing, one create per save, one move per drag, the snapshot still derives server-side from the persisted manifest. Only the number of user actions between intent and a saved pin changes, from six to two.

D075 — Close the feedback loop: a pin lifecycle (open, replied, resolved), per-role last-seen with unread counts, a founder pin list, and sharing in the project header

2026-09-12 · build · accepted · Agent proposed, human approved

Problem

The product promises the founder's reply, but a reply was invisible until the editor selected each pin and opened its thread. No count said where new replies were. Neither role could mark a note done, so a reviewed project looked identical to an unreviewed one. The founder had no list of the notes waiting for them, only badges on a screenshot. And 'Share with founder', the action that starts the loop, was inside the collapsed project rail.

Decision

Pins gain a status: open on create, replied when the other role appends to the thread, resolved when either role resolves it. Resolving and reopening are reversible and each writes an append-only thread entry of a new system kind naming who did it, so the immutable chronology (REQUIREMENTS 6) records the state change rather than a mutable column alone. Each role's last-seen time is stored per project (editor) and per capability session (founder); a reply is unread for a role when it postdates that role's last view of the pin. The hierarchy read returns unread and open counts per capture and per project so the rail, the overview, and the header can show them without extra requests; viewing a pin's thread marks it seen. The founder view gains a pin list above the canvas with comment excerpts, status, and unread markers, in pin-number order, each entry focusing its pin. 'Share with founder' moves to the project header next to the title with its state (no link, active vN, revoked) always visible; its panel behavior is unchanged.

Rationale

Proposed by the agent, approved by the human. Status and last-seen are additive columns and one new thread-entry kind; the append-only triggers and the founder's read/reply-only boundary are untouched. Counts ride on the existing hierarchy read so the workspace's default traffic does not grow.

D076 — Drive capture from the server with progress and one automatic retry; the browser tab is no longer required for a project to finish

2026-09-12 · build · accepted · Agent proposed, human approved

Problem

Capture dispatch was driven only by the editor's browser tab (D049): the client POSTed each pending attempt to the dispatch route, polled the hierarchy, and stopped polling after ten minutes. Closing the tab after creating a project stalled the remaining captures; an attempt that stopped responding waited for a manual retry; and after creation the editor saw rows reading 'Queued' with no sense of how long the project would take.

Decision

The server continues capture work after it has answered. Project creation and retry schedule the first dispatches to run after the response is written (Next.js after()), each dispatch schedules the next pending attempt of the same project when it finalizes, and a secret-protected sweep route re-drives any pending or stale attempt for a scheduled job to call, so a chain that dies mid-way is picked up. The durable two-lease cap remains the only concurrency authority. A retryable failure or a stale attempt is retried once automatically, recorded as a new attempt exactly as a manual retry is; a second failure surfaces with its catalog reason and a retry control at project level. The hierarchy read reports progress per project: attempts done, remaining, the page currently capturing, and an estimate from the median duration of this project's finished attempts. The client keeps its driver as a fallback re-driver, so nothing regresses where after() cannot run. Pinning is available on any ready capture while the rest continue.

Rationale

Proposed by the agent, approved by the human. The dispatch and execution modules already run a whole capture inside one request, so continuing that work after the response reuses the same code path with a different trigger. The one-retry policy mirrors what the owner did by hand in the checkpoint (M1-LIVE-5).

D077 — A project overview: capture grid with counts, device toggle per page, cross-capture next and previous pin, and project-scoped pin table and export

2026-09-12 · build · superseded · Agent proposed, human approved

Problem

Everything about pins was scoped to one capture: the list, the table, the Markdown export, the selection. A Chickpea project is four pages times two devices, so reviewing it meant visiting eight planes with no view of where the notes were or what was left to read.

Decision

The workspace opens on a project overview: one card per capture, in page order, Desktop then Mobile, showing a thumbnail, the page URL, capture state, and pin, open, and unread counts from D075; a card opens its capture in the canvas. Within a page, Desktop and Mobile become a toggle above the canvas instead of two rail entries, and the rail lists projects and pages only. Next pin and Previous pin controls (and J/K per D074) step through every pin in the project in page, device, number order, switching capture as needed and remembering each plane's camera. The pin table and 'Copy all as Markdown' move to project scope with page and device columns; the per-capture view filters the same table.

Rationale

Proposed by the agent, approved by the human, ordered after D074, D075, and D076 at the human's direction. The thumbnail is the existing private asset served through the authorizing route, sized by CSS; no new storage.

Superseded by D144.

D078 — Speak the user's language: pins named by their comment and element, internals behind a Details disclosure, and a reading-first founder view on phones

2026-09-12 · build · accepted · Agent proposed, human approved

Problem

Both views identified a pin as 'Pin 1 at natural pixel (462, 410)' and listed image hash, version, state, and natural size beside it. The founder, who is not a developer, saw the same. Two long instruction paragraphs explained interactions that D074 makes self-evident, and the founder view stacked a tall canvas above the panel, so on a phone the notes were a screen below the picture.

Decision

Pins are named by an excerpt of their comment and, when attached, the element's short label: 'Pin 3 · "Annual (save 20%)" toggle'. Coordinates, natural size, version, state, and image hash move behind one 'Details' disclosure in the editor panel and leave the founder view entirely. The instruction paragraphs are replaced by a one-line verb strip beside the controls (drop a pin: click the page · move: drag it · read: click a pin) and a keyboard list inside Details. The founder view on narrow widths puts the pin list (D075) first, the canvas second, and opens the canvas scrolled to the chosen pin when an entry is tapped.

Rationale

Proposed by the agent, approved by the human; sequenced last because it rewrites copy across the surfaces the other records change.

D079 — Rectangle marks: drag to draw a box, comment and context like a pin, shared numbering, resizable, readable by the founder

2026-09-12 · build · accepted · Human directed

Problem

The human asked for a square bounding box with a comment. The requirements and schema already anticipated rich marks (REQUIREMENTS 4, annotations.kind allows rectangle, MIN_SHAPE_SIZE_PX is published) but nothing drew, stored, listed, or exported one.

Decision

A rectangle is a second annotation kind on the same canvas and in the same numbering sequence as pins. Drawing: with the modeless model of D074, a press that moves on empty screenshot pans; holding Shift while pressing, or choosing the Box tool, draws a rectangle from press to release in natural pixels, clamped to the frame and rejected under MIN_SHAPE_SIZE_PX. The draft opens the same anchored composer; nearby candidates are ranked by overlap with the box instead of distance to a point, with the largest-overlap element pre-selected. Saved rectangles render as a stroked box with the number badge at the top-left corner, are movable by dragging the box and resizable by eight handles, each committing one revisioned geometry write. Geometry is {x, y, width, height} at geometry_version 1. Rectangles carry threads, status, unread, and resolve exactly as pins do, appear in the pin table and Markdown export with their bounds, and render read-only for the founder with no handles.

Rationale

Directed by the human. The persistence rules from D059 and D061 (server numbering, idempotent create, revisioned mutation, tombstone delete, server-derived snapshot) apply unchanged; only the geometry shape and the candidate ranking are new.

D080 — Project header feedback counts the current version, matching the rail badges

2026-09-13 · build · accepted · Agent decided alone

Problem

The project header summed feedback across every capture of a project, while the page rail badges and the overview cards summed only each device's selected (current) capture. Retrying a page that already had pins — the old attempt keeps its pins, the new attempt is selected and empty — made the header total exceed the sum of the badges beneath it, so the same screen disagreed with itself. Found in review of the D074–D079 pull request.

Decision

Compute the project header total (project.feedback on the hierarchy read) over each device's selected capture, the same basis the rail badges and overview cards already use. Pins on superseded attempts stay counted per capture (captureFeedback) and stay listed in the explicit all-versions pins table; they simply no longer inflate the current-state headline.

Rationale

Safe to decide unilaterally inside the granted latitude to tackle the review concerns: it aligns three existing UI surfaces onto the basis two of them already used, changes no schema or wire shape, and preserves the historical record — per-capture counts and the all-versions table still expose superseded pins. It is reversible in one function if the product later prefers the all-history reading.

D081 — Restate the milestones against what is actually built, add a fourth slice for depth on the loop, and hold accounts and multiple users until last

2026-09-15 · wrap · accepted · Human directed

Problem

The milestone document had gone stale enough to mislead. It called milestone 1 in progress and milestones 2 and 3 pending, while the repository had shipped the canvas, pins, element context, founder capability links, append-only threads, a production deployment, a project overview, rectangles, server-driven capture, and a six-record UX overhaul. The document is a deliverable rendered live at /reqs/milestones, so a reader checking status was being told something false. It also had no place to put the UX overhaul, which was not in the original three-slice plan, and no statement of what comes after milestone 3.

Decision

Rewrite the milestone document against the repository as it stands. Milestone 1 is complete and cites its live checkpoint. Milestone 2 is 'built, awaiting checkpoint': every item is implemented and covered by the gate, and none of it has been driven by the owner in a browser, so the document's own completion rule forbids calling it done. Milestone 3 lists what is finished and names three remaining items: circles and arrows, shipping the current build and running the deferred checkpoint against it, and the rectangle resize-handle ergonomics. The UX overhaul gets its own dated section between milestones 2 and 3 rather than being folded silently into either. A new milestone 4 collects depth on the feedback loop: the re-review loop after a founder ships a change, working a project at scale, and the editor on a phone. A new milestone 5 holds accounts, identity, per-user projects, and anything resembling multiplayer until everything above is done.

Rationale

Directed by the owner, who asked for a review of the log and the app and a decision on how to move forward, and who fixed the one ordering constraint: accounts and multiple users come last. The rest of the ordering follows from what changes whether the tool gets used. Shipping outranks new features because the live deployment is at commit 523dcd9 and everything since is invisible to anyone but a developer running the repository. Arrows outrank the re-review loop because 'move this there' is the one instruction the current mark vocabulary cannot express, and the product exists to make directional feedback unambiguous. The re-review loop outranks scale and mobile because the conversation currently has no ending.

D082 — Circle marks: a square-constrained ellipse drawn with an armed tool, sharing every rule rectangles already follow

2026-09-15 · build · accepted · Agent proposed, human approved

Problem

The published architecture and the geometry catalog have described circles since mission planning (MIN_SHAPE_SIZE_PX names them, 'circles stay square'), the annotations table has allowed kind='circle' since the first migration, and D079 made the whole annotation path kind-generic. Nothing drew one. A circle is the right mark for 'this region', where a rectangle's corners imply an alignment that is not being asserted.

Decision

A circle is a rectangle whose geometry is constrained square and whose renderer is an ellipse inscribed in that square. Geometry is {x, y, size} at geometry_version 1, where size is both the width and the height in screenshot-natural pixels, no smaller than MIN_SHAPE_SIZE_PX, clamped inside the frame. Drawing: an armed Circle tool in the mark-tool group beside the existing Box tool; the drag's larger dimension sets the size, so an off-square drag still yields a circle, and the tool disarms after one gesture or on Escape. Everything else is what a rectangle already does: the same anchored composer, nearby elements ranked by overlap with the circle's bounding square, shared per-capture numbering, the badge at the bounding square's top-left, move by the stroke, resize by the same handles constrained to stay square, one revisioned write per gesture, threads and status and unread exactly as pins and boxes have them, and a read-only rendering with no handles for the founder.

Rationale

Proposed by the agent as the cheap half of finishing the mark vocabulary, approved by the human in the same message that ordered the milestones. Constraining to a square keeps one resize contract, honours a boundary published before implementation, and makes the circle a renderer and a clamp rather than a new geometry family.

D083 — Arrow marks: a two-endpoint straight arrow whose head carries the meaning and the element context

2026-09-15 · build · accepted · Agent proposed, human approved

Problem

Every mark the product has is a place: a pin is a point, a rectangle and a circle are regions. None of them can say 'move this there', 'this should point at that', or 'these two are out of order' — the instructions that make feedback directional rather than merely located. The architecture has described arrows as straight edges between two draggable endpoints since mission planning, and MIN_ARROW_LENGTH_PX has been published since, but nothing drew one.

Decision

An arrow is two points and a direction. Geometry is {start: {x, y}, end: {x, y}} in screenshot-natural pixels at geometry_version 1, with the straight-line distance between them no smaller than MIN_ARROW_LENGTH_PX and both endpoints clamped inside the frame. The head is at `end`: that is where the arrow points, so that is what the mark is about. Nearby elements are ranked from the head point using the existing point ranking, not the overlap ranking, and the pre-selected candidate is the element under the head. Drawing: an armed Arrow tool; press sets the tail, release sets the head. Each endpoint is independently draggable after save and the whole arrow moves by its shaft, each gesture committing one revisioned write. The badge rides at the tail so it never covers the thing being pointed at. Rendering is a line with a filled head whose stroke and head scale with zoom to stay visible without changing the stored geometry, and the founder sees it read-only with no endpoint handles.

Rationale

Proposed by the agent and approved by the human as the item that most changes what the product can say. The straight-line constraint and the head-anchored context are what keep an arrow a directional instruction rather than a decoration.

D084 — Build the founder link and read/reply loop after all, on a parallel branch, partly un-deferring D051

2026-09-10 · build · accepted · Human directed

Problem

D051 descoped requirements 6 and 7 — persistent revocable founder links and append-only two-way threads — to fit the remaining budget, and the requirements, architecture, and eval documents were marked accordingly. But the founder's reply is the whole point of the product: without it Pinata is usable by the editor alone, and the owner wanted it usable with friends. Everything underneath the feature already existed: the schema carried the share columns and the thread_entries table with its reject-update and reject-delete triggers, and the boundary catalog already published a reply quota. What made it risky was timing, not difficulty — the demo build was working and a live pins checkpoint was still pending.

Decision

Build the founder stream in parallel on a branch (feat/founder-links) rather than deferring it further or interleaving it with the demo build, and keep it strictly additive so main's working behaviour cannot regress. The branch carries the same npm run validate gate as main. Its decision records stay in docs/decisions/drafts/ while it is in flight, so concurrent work never violates the sequential id rule, and are folded into the log with real ids at merge — which is what D085 through D090 are.

Rationale

The human directed the stream, its priority relative to the demo, and the branch shape. This is a bounded exception to D010's commit-straight-to-main, not a reversal of it: main keeps the gate before every commit, and the branch carries the same gate.

D085 — Founder capability sessions are stateless: a signed cookie bound to project id and capability version, re-checked against the project row on every request

2026-09-10 · build · accepted · Agent decided alone

Problem

A founder link must persist until rotated or revoked, and rotation or revocation must end every existing founder session at once. The editor session revokes through an in-memory denylist (a documented per-instance weakness); copying that for founders would let a rotated capability keep working on another serverless instance until absolute expiry.

Decision

Mirror the editor session code for signing, lifetime, renewal, cookie attributes, and the double-submit CSRF proof, but bind the founder payload to {project id, capability version} and have the guard re-read the project row on every request: the project must be live, the digest present, share_revoked_at null, and share_token_version equal to the session's version. No founder session state is persisted, so no migration is needed and no denylist exists to go stale.

Rationale

The brief explicitly says the version binding is what invalidates sessions, and the durable row is the only authority that changes on rotation; reading it per request is one indexed primary-key lookup. Safe to decide alone because it adds no schema, no dependency, and no new boundary constant.

D086 — No new boundary constants for founder links: reuse the editor session policy, AUTH_REQUEST_MAX_BYTES, ANNOTATION_REQUEST_MAX_BYTES, FEEDBACK_BODY_MAX_CHARS, and the published reply quota

2026-09-10 · build · accepted · Agent decided alone

Problem

The boundary catalog is versioned and drift-checked against docs/EVALS.md and docs/ARCHITECTURE.md; adding any constant requires a POLICY_VERSION bump published in both documents, and this branch is forbidden from editing ARCHITECTURE.md while another stream closes the docs out.

Decision

Every limit the founder and thread surfaces need already exists in the catalog: the exchange body is capped by AUTH_REQUEST_MAX_BYTES (a 43-character token fits comfortably), reply bodies by ANNOTATION_REQUEST_MAX_BYTES and FEEDBACK_BODY_MAX_CHARS, founder session lifetime by the editor session constants, and the founder reply quota by REPLY_MAX_PER_WINDOW / REPLY_WINDOW_MS. The token length itself (32 bytes, 43 base64url characters) lives in the capability module as an implementation constant, not a published boundary, because it is a cryptographic minimum rather than a tunable policy.

Rationale

The brief allows EVALS.md edits only when a drift test forces them; reusing constants means no drift test fires and the catalog stays at 2026-09-09.2. If the owner later wants a shorter founder lifetime, that is a one-constant catalog change with its own decision record.

D087 — Founder reads share the editor's capture routes through one editor-or-founder authorizer, with a founder-scoped hierarchy route and a same-origin exchange route under /api/founder

2026-09-10 · build · accepted · Agent decided alone

Problem

The founder view needs the project hierarchy, per-capture pin lists, private screenshot bytes, and per-pin threads. Duplicating those reads under a founder namespace would fork the list and delivery logic; admitting founders on the editor routes risks changing the editor-only denial shapes the existing tests pin.

Decision

One shared authorizer (src/lib/server/founder/reader.ts) tries the editor guard first and consults a founder cookie only when one is present; every founder failure answers with the editor's own denial, so anonymous, foreign-project, rotated, and revoked callers are byte-identical to what the routes always returned. The asset route, the pin-list GET, and the new thread route use it. The hierarchy read and the token exchange are founder-only and live under /api/founder/[publicId]; manifest and context reads stay editor-only because the read-only view never places a pin.

Rationale

The brief asks for the asset route to admit founders while denying everyone else exactly as today; a single authorizer that returns the editor's denial on any founder failure is the direct way to keep those denials identical, and the founder-specific asset tests prove one denial body for every failure case.

D088 — Thread replay is intent-bound without a digest column: the same key returns the committed entry only when body and role match, otherwise it conflicts

2026-09-10 · build · accepted · Agent decided alone

Problem

Thread appends must be idempotent per the existing (annotation_id, idempotency_key) unique index, and pin creation binds a key to a payload digest through the idempotency_keys table. thread_entries has no digest column and adding one means a migration for a table whose rows can never be updated.

Decision

Look up the existing entry by (annotation, key); replay it with 200 when its body and actor role equal the request's, answer 409 when they differ, and converge on the winner if the unique index fires under concurrency. The founder quota admission runs only after the replay check and validation, so a retried or invalid reply never consumes quota.

Rationale

The entry row is immutable, so comparing its stored body and role is exactly as strong as comparing a digest of them. Safe to decide alone: no schema change, and the behavior matches the pin store's replay-or-conflict contract.

D089 — The editor's share control is closed by default and reads nothing until opened; the workspace's default traffic is unchanged

2026-09-10 · build · accepted · Agent decided alone

Problem

The workspace tests stub fetch and count requests; an always-on per-project status read would add a request per project on every mount and change the default behavior the brief says must stay unchanged.

Decision

Render one Share with founder toggle per project in the tree; opening it reads the status once and offers Create/Rotate and Revoke; the issued link is composed client-side as origin + path + '#' + token, shown once in a read-only field with a Copy control, and forgotten when the control closes. The hierarchy payload is not extended with share status.

Rationale

Additive and minimal, as the brief asks; the only new default-path DOM is one button per project, and the existing workspace suite passes without modification.

D090 — Founder pages get their security headers from next.config.ts for /f/* and /api/founder/*: no referrer, no indexing, no framing, no caching; a full nonce-based CSP is deferred

2026-09-10 · build · accepted · Agent decided alone

Problem

Architecture requires founder capability pages to send no referrer and permit no indexing, and names a strict CSP with frame-ancestors 'none'. The application currently sets no response headers anywhere, and a strict script-src CSP would need per-request nonces threaded through the Next.js layout.

Decision

Add a headers() block to next.config.ts that sets Referrer-Policy: no-referrer, X-Robots-Tag: noindex, nofollow, noarchive, X-Frame-Options: DENY, Content-Security-Policy: frame-ancestors 'none', and Cache-Control: private, no-store, max-age=0 on /f/:path* and /api/founder/:path*; the founder page also declares robots noindex and referrer no-referrer in its metadata. The token never appears in a path or query, so no header can leak it.

Rationale

This satisfies the stated founder-page requirements with framework configuration only; the strict CSP remains a documented gap for a follow-up decision.

D091 — Disclose the tooling used after the Missions: Claude Code on mobile for the documentation closeout, and a second harness for the cross-review

2026-09-10 · wrap · accepted · Human directed

Problem

The project's records said every commit was authored through a Factory Droid session. That is no longer exactly true. Once the MVP was working, the owner did a documentation closeout and a repository-hygiene pass with Claude Code from a phone on a plane, because the network connection would not sustain a Factory session. The session log also had no top-level accounting of time: each Mission section reports agent time, which ran mostly unattended while the owner teed up a prompt and walked away, so the two measures were easy to confuse. Leaving either unsaid would make the process narrative inaccurate.

Decision

Record it plainly. The application code, capture pipeline, canvas, pins, founder links, landing page, and production deployment were built through Factory Droid Missions and Droid sessions. A documentation closeout and repository-hygiene pass were done with Claude Code on mobile, and that same harness produced the cross-review adopted in D093. docs/SESSION-LOG.md opens with a time-and-tooling ledger that keeps the human's wall-clock time apart from the agent time each session section reports.

Rationale

The human directed the disclosure, in the words quoted below. The decision costs nothing and makes the repository's own history and its narrative agree.

D092 — Flag the product and architecture decisions a reviewer should read first, and surface them ahead of the full log in Markdown, the dashboard, and /reqs/decisions

2026-09-10 · wrap · accepted · Human directed

Problem

The decision log exists to explain the process, but every surface rendered all seventy-plus records in one undifferentiated column, so a reader could not tell the two dozen decisions that shaped the product from the routine build calls. Curating that list in a page component would create a second decision dataset, which the single-source rule forbids.

Decision

Add an optional `key` boolean to the decision record schema, set on the product and architecture decisions a reviewer should read first. The validator accepts it and rejects non-boolean values; docs/DECISIONS.md gains a "Key decisions" section above the index; the dashboard gains a "Key decisions only" filter chip and a per-record pill; and /reqs/decisions opens with a nav landmark listing the same records, each linking to its card in the full catalog below. Records without the flag are unchanged.

Rationale

The human directed the substance: the decision log reachable in the app, focused on the critical product and architecture calls. Where the flag lives — in the source data rather than a component — is mechanical inside that direction, and putting it in the data is what lets all three surfaces agree.

D093 — Cross-review the repository with a second agent harness and adopt its findings selectively, rather than merging its branch

2026-09-10 · wrap · accepted · Human directed

Problem

An agent that reviews its own work is only checking itself. The owner ran a separate Claude Code session over the repository to audit it independently; that session pushed a branch carrying documentation reconciliation, repository hygiene, the key-decisions flag, and three new hub routes. By the time it was reviewed in Factory, main had moved on: the founder loop had merged, the landing/app split and the pin table had shipped, and main had independently reused the ids D069, D070, and D071 for different decisions. Merging the branch would have collided on those ids and reintroduced documentation asserting that the founder loop was still deferred.

Decision

Treat the branch as a review, not a patch. Adopt the findings that are still true and still valuable — the .gitignore ordering bug that made the committed .env.example unreachable, a checked-in .env.example of names only, .nvmrc pinning Node 24, moving a stray 1.5 MB PNG out of the repository root, the stale test/home.test.tsx reference and outdated layout tree in AGENTS.md, a Local setup section in the README, the time-and-tooling ledger and disclosure (D091), the honest additions to docs/NEXT.md, and the key-decisions flag (D092). Reject the three process routes at the owner's direction, reject every founder-is-deferred rewrite as now false, and renumber the branch's records instead of importing them. Fold the founder-links drafts into the log in the same pass, as D084 through D090, since nothing on main had recorded that stream at all.

Rationale

The owner asked for the second harness specifically to hold the work doubly accountable, so its findings deserved evaluation rather than either automatic merge or dismissal. Selecting file by file keeps the accepted changes attributable and leaves the rejections stated here instead of implied by a silent revert.

D094 — Defer runtime element matching with a System One model until the deterministic pre-selection has been measured

2026-09-19 · build · pending · Raised and deferred

Problem

The owner asked whether Jev, TypeSafe AI's System One model, should choose the nearest appropriate manifest element when a mark is placed. The fit is closer than a general language model's would be: Jev returns a typed choice among defined options with a confidence score, cannot hallucinate because the schema fixes the valid outputs, and costs a fraction of a cent for the eight candidates a query would carry. Two things argue against reaching for it now. The pre-selection has never been watched by a person, so there is no evidence the deterministic ranking is failing; and the cost of a wrong pick is one click, because the composer pre-selects the top candidate and offers Change and No element beside it.

Decision

Postponed, not rejected. The deferral is resolved by a number the checkpoint will produce: for each mark placed, whether the pre-selected element was the one the editor wanted. If the deterministic ranking is right nearly every time, there is nothing here to build. If it is not, the cheaper deterministic fixes come first: weight semantic kind harder so an interactive element beats the container wrapping it, prefer elements carrying an accessible name, and penalise layout containers with no text or role.

Rationale

Raised by the owner and consciously postponed in the same exchange. Recording it keeps the reasoning findable when the question returns, and names the measurement that settles it rather than leaving it to taste. Adopting it would reverse the 'no runtime AI or token-consuming product feature' non-goal published in the requirements, the walkthrough, and the live /reqs hub, so it would need a record superseding this one rather than a quiet dependency. Worth noting for whoever answers this: the valuable version re-ranks after the comment is written, which inverts today's flow, where pre-selection happens the moment a mark is dropped.

D095 — Recover captures on the server: retryable probe and provider failures, stale attempts treated as failed, a time budget per invocation, and freed slots shared across projects

2026-09-23 · build · accepted · Agent proposed, human approved

Problem

Five capture defects shared one pattern: a recoverable condition became a dead end or waited for the daily cron. A redirect probe that could not be read (a 5-second timeout, a TLS error, a reset connection) and an origin mismatch seen inside the Browserless session after admission had approved the target were both filed as unsafe-redirect, which is non-retryable, so a network blip left a capture the product could not recover (the open question in D054). A stale attempt counted as in progress, so the project read 'Capturing…' indefinitely and the bulk retry was hidden. Every continuation ran as a nested after() inside the invocation that started it, so an eight-capture project in four waves of up to 90 seconds could outrun the 300-second maxDuration and be killed mid-chain on Vercel while passing locally, where there is no limit. A project that found both capture slots busy was never resumed by the server. And a dispatcher that lost the fenced transition could release the winner's lease.

Decision

An unreadable redirect probe fails with a new retryable outcome, target-unreachable; unsafe-redirect stays non-retryable and is reserved for redirects the policy actually refused. An execution-time origin mismatch fails as browserless-provider, which is retryable, answering D054: admission-time rejection stays final, execution-time mismatch does not. Stale attempts count as failed and retryable in project progress and join the bulk retry, and the editor's hierarchy read gives a stale newest attempt the same one automatic retry the sweep would, idempotent per attempt. Each invocation records when it started; before scheduling another capture it checks that one whole capture plus a margin still fits in CAPTURE_INVOCATION_MAX_DURATION_MS, and when it does not it hands the chain once to a fresh invocation by calling its own sweep route with the sweep secret and, where deployment protection is on, the automation bypass header. When a finished attempt's project has nothing pending, the oldest pending attempts of any project take the free slots. A rejected dispatch releases its lease only when its own transition applied.

Rationale

Every recovery reuses a path that already existed and is already idempotent: the automatic-retry key derived from the attempt id, the fenced state transitions, and the two-slot lease cap. The hand-off falls back to today's behaviour when no origin or secret is available, so local development and tests are unchanged. The owner approved the review's recommendations as one pass rather than item by item; the specific calls inside it were the agent's, made inside that approval, and are listed here so they can be revisited.

Supersedes D054.

D096 — Canvas input: the composer keeps focus, handles only on the selected mark when they fit, one pointer and one button, exact minimums, and serialized moves

2026-09-23 · build · accepted · Agent proposed, human approved

Problem

Seven canvas defects, each confirmed in the code before it was fixed. The composer focused its textarea only on mount, so after a click moved an open draft, typing reached the canvas shortcuts: n re-placed the draft, b, c and a armed tools, and j or k stepped to another mark and could discard the draft and its comment. Every saved rectangle, circle and arrow carried resize handles at every zoom; at overview zoom on a tall page they covered small marks, swallowed pans, and saved a real resize from a one-pixel wobble. A second finger did not cancel the first, so a pinch could drop a pin. Right and middle clicks placed pins and started draws. A mark resized to the minimum could come out a rounding error short (7.999999999999999 for a box, 15.999999999999996 for an arrow) and fail server validation on every retry. A second move ending before the first save returned carried a stale revision and was lost to a false 'changed in another session'. And a click with a tool armed silently disarmed it.

Decision

The composer takes a placement counter and refocuses whenever the draft is placed or moved, and the canvas ignores single-letter shortcuts while a draft is open (Escape still works). Handles render only on the selected saved mark, and only when its shorter side, or an arrow's length, is at least 48 CSS pixels on screen; a mark keeps them until its own resize ends, and a resize released within PLACEMENT_SLOP_SCREEN_PX saves nothing. A non-primary pointerdown cancels the pending press and any gesture in progress. Only the primary button starts a press or a draw. The client snaps a minimum-size box and arrow exactly to the minimum, and the server's minimum checks allow 1e-6 of slack. Geometry saves queue per mark, sending only the latest pending geometry on the revision the previous save returned. A click with a tool armed leaves it armed.

Rationale

Each fix restores a rule the canvas already claimed: D074's distinction between a click and a drag, one write per settled gesture, and server validation that never rejects geometry the client itself produced. The owner approved the review's recommendations as one pass rather than item by item; the specific calls inside it were the agent's, made inside that approval, and are listed here so they can be revisited.

D097 — Both sides see replies without reloading, addresses are completed on the client, the founder arrives oriented, and link rotation asks first

2026-09-23 · build · accepted · Agent proposed, human approved

Problem

The editor's only timer was the capture poll, which stops once nothing is capturing, and the founder view had none, so a founder's reply, a status change, or an editor follow-up stayed invisible on the other side until a reload: the moment the product is named for failed silently. The address fields refused anything without https://, and the landing page parked input unchecked, so 'chickpea.co' and '/pricing' failed, the landing page's only after sign-in. A founder's own mark still read Open after they replied. Rotate and Revoke broke the link a friend already had in one click. A founder whose twelve-hour session had ended was told the link may have been replaced or turned off, when reopening it would have worked, and a founder arriving saw root/Desktop whether or not it had notes, with no word of how many notes were waiting. Thread times read like log lines, and the Markdown export dropped the conversation.

Decision

A shared visibility-aware refresh re-reads every LIVE_REFRESH_INTERVAL_MS (20 seconds) while the tab is visible and immediately on becoming visible or focused, pauses while hidden, runs one read at a time, and applies a result only if local state has not moved since the read began, so drafts, selection, typed text and the camera survive. The editor refreshes the hierarchy, the open capture's pins, the project pins and the open thread; the founder its hierarchy, pin list and thread. The client completes bare domains with https:// and resolves /path rows against the root, on blur and on submit, while the server normalizer stays strict; http:// is never added or upgraded. After a reply the founder view re-reads that capture's pins. Rotate and Revoke each take an inline confirmation. An ended session and a refused link get different messages, the first saying to reopen the link from Lucas's message. The founder view opens with a one-line summary of the notes waiting, shows per-page counts, and opens on the first capture with marks. Thread times are friendly local times with the ISO value in a time element. The project annotations read and both exports include each mark's thread.

Rationale

It reuses the reads that already exist and the unread and status rules of D075, costs nothing while a tab is hidden, and never lets a background read overwrite something the person is doing. The owner approved the review's recommendations as one pass rather than item by item; the specific calls inside it were the agent's, made inside that approval, and are listed here so they can be revisited.

D098 — Sign-in hardening: reserve each login attempt before checking it, per-client throttling with a global backstop, no bypass on Vercel, and CSRF renewed with the session

2026-09-23 · build · accepted · Agent proposed, human approved

Problem

Four defects in the password and session paths. PINATA_AUTH_DISABLED was honoured in any environment, so setting it in Vercel by mistake would open the editor to anyone. The login route read the throttle, checked the password, and counted a failure only afterwards, so a burst of parallel requests all passed the pre-check and a window allowed as many guesses as requests. One global bucket (D026) meant six wrong guesses every fifteen minutes from anywhere kept the owner from signing in, because a throttled pre-check refused even the right password. And renewing a session re-issued only the session cookie, so after about twelve hours of activity reads kept working while every write answered 403.

Decision

isAuthDisabled() returns false whenever VERCEL is set and logs one warning if the flag is present there; it does not consult NODE_ENV, because local live sessions run next start. Login now checks the signing secret, then a read-only throttle pre-check, then atomically reserves the attempt in two buckets before verifying the password: a per-client bucket keyed by a digest of Vercel's x-real-ip (else the first x-forwarded-for entry, else a fixed key) at LOGIN_MAX_FAILURES, and a global bucket at the new LOGIN_GLOBAL_MAX_FAILURES of 100. Either over its limit answers 429 without checking the password; success clears the client bucket and returns its slot to the global one. Every site that renews a session goes through one helper per role that writes the session and CSRF cookies together. A SESSION_SECRET shorter than 32 characters logs a warning but is not refused.

Rationale

Each change is the smallest one that makes its guarantee hold under concurrency and on a real deployment, and D026's protection against distributed guessing is kept with a ceiling one guesser cannot reach. The owner approved the review's recommendations as one pass rather than item by item; the specific calls inside it were the agent's, made inside that approval, and are listed here so they can be revisited.

Supersedes D026.

D099 — Put the migrate-then-deploy order and the Vercel settings in the runbook, serve founders from a custom domain, and disclose the Cursor commits

2026-09-23 · build · accepted · Agent proposed, human approved

Problem

Production had been on commit 523dcd9 since 2026-09-10 while main moved about forty commits ahead, and the runbook went straight from pushing to deploying. Migrations are not run by the build, so pushing main before migrating would break project creation, pins and the founder view on their first read. The four capture routes export maxDuration = 300, which Hobby accepts only with Fluid compute; CRON_SECRET was missing from .env.example, and without it the sweep answers 404. Deployment protection is all_except_custom_domains (D068), so every vercel.app address, production included, shows a Vercel sign-in wall to a founder, and the editor, signed in to Vercel, would never notice; because the share control builds the link from the page's origin (D089), a link issued on a vercel.app address points at the wall. Separately, the session log's tooling ledger cited D079 and D081 where it meant D091 and D093, and eight commits authored 'Cursor Agent' on pull requests 3, 5 and 6 appeared in no disclosure.

Decision

The README runbook now checks the Vercel project first (Fluid compute on, the seven Production variables present including CRON_SECRET, neither local-only flag set, the bypass for automation present, and whether recent pushes deployed at all), then validates, then migrates the shared database, listing applied migrations first because Drizzle skips one older than the newest recorded, then deploys, verifies, and rolls back without reversing additive migrations. A new README section says founders cannot reach a vercel.app address and that production needs a custom domain the editor also works from. .env.example names CRON_SECRET and CAPTURE_SWEEP_SECRET. The tooling ledger names the Claude Code and Cursor exceptions, cites the right records, and adds the Cursor work and this pass.

Rationale

These are the steps that stood between main and a first real test, and the gaps a reviewer would find first. Writing them down in the order they must happen removes the one ordering mistake that breaks production outright. The owner approved the review's recommendations as one pass rather than item by item; the specific calls inside it were the agent's, made inside that approval, and are listed here so they can be revisited.

D100 — Serve production at yourpinata.dev, and correct what D099 assumed about the deployment

2026-09-23 · build · accepted · Human directed

Problem

D099 was written from the repository alone, without access to the Vercel project or the database, and took three facts from older records that were no longer true. It said production had been on commit 523dcd9 since 2026-09-10; in fact pushes to main had been deploying to production all along, the last before this pass five days earlier. It said migrations 0004 to 0006 stood between main and production; the migration table showed all seven applied, 0004 to 0006 on 2026-09-12. And it said deployment protection was all_except_custom_domains (D068), so founders would meet a Vercel sign-in page; the project's ssoProtection was in fact off, and every vercel.app address answered publicly. Two things D099 named were genuinely missing: CRON_SECRET in Production, and a custom domain.

Decision

Attach yourpinata.dev, registered through Vercel Domains with Vercel's nameservers, to the pinata project as the production domain, with www.yourpinata.dev as a 308 redirect to it. Add CRON_SECRET to Production as a sensitive variable generated from 32 random bytes and never displayed, then redeploy the current production deployment so functions read it. Leave deployment protection off, as the owner had set it, and leave D099's runbook order and disclosure standing; correct its factual premises here and in the README, milestones, and next steps.

Rationale

The owner asked for the domain and for the remaining deploy steps to be carried out once a Vercel CLI was available. Checking the live project and database before acting showed which of D099's steps were real and which rested on stale records, which is the lesson worth keeping: verify deployment state against the platform, not against the decision log.

D101 — Raise the per-client editor login failure limit from 5 to 10, keeping the global backstop at 100

2026-09-25 · validate · accepted · Human directed

Problem

On the first turn of the milestone-2/3 live checkpoint the owner was locked out of editor sign-in after five failed attempts and told to wait thirteen minutes. The failures were mechanical rather than hostile: the agent had copied EDITOR_PASSWORD out of .env.local with its surrounding double quotes still attached, so several attempts could not have succeeded. D098 had already replaced D026's single shared bucket with a per-client bucket plus a global backstop, which stops one noisy client locking the editor out — but the per-client key falls back to a fixed key when there is no x-real-ip or x-forwarded-for, which is exactly the local checkpoint case. So the limit that stopped the owner is still five, and a solo operator running the checkpoint on 127.0.0.1 meets it as easily as before.

Decision

Raise LOGIN_MAX_FAILURES from 5 to 10. LOGIN_GLOBAL_MAX_FAILURES stays at 100, LOGIN_WINDOW_MS stays at 900,000 ms, and D098's reserve-then-verify ordering, two-bucket accounting, 429 answer, and success-clears-the-client-bucket behaviour are all untouched. POLICY_VERSION moves to 2026-09-25.1.

Rationale

Ten per client per fifteen minutes is still a hard ceiling against an eleven-character secret, and the control that actually matters against a distributed guesser — the global backstop of 100 — does not move at all. What changes is only how quickly a single well-meaning operator can lock themselves out, which is the whole of the observed problem. Ten is also the largest value D098's published invariant permits while leaving the global ceiling alone, so the change takes the available headroom rather than inventing new exposure. Every test imports LOGIN_MAX_FAILURES rather than hardcoding five, so no assertion weakens.

D102 — Take design direction from paper.design: a warm off-white sheet, near-black type in light weights, hairline rules, and one accent kept for the marks

2026-09-29 · build · accepted · Human directed

Problem

Pinata looked like a first build: a cream-and-brown palette with a red that also colored links, the wordmark, headings, selected tools and badges; a rounded system font; and buttons and inputs left almost entirely to the browser default, so every control looked slightly different. The owner asked for the landing page and the application to take their direction from paper.design, a design tool whose own site is a quiet, near-monochrome sheet with large light type.

Decision

Adopt Paper's system as direction, not as a copy. Paper's site was read from its published HTML and stylesheets (live screenshots were not possible from the build environment). Tokens: a warm off-white sheet (--bg #fcfcf9), white cards, a cream for anything raised (#f3f2eb), near-black ink (#141414), a neutral gray for secondary text (#666666, 5.59:1), a lighter gray only for the second tone of large headlines (#868682, 3.56:1), hairline rules (0.5px on high-density screens), 4/8/12px radii, and blue focus rings (#2d6fcd). The accent becomes #c9381a, the brand spark deepened until it clears 4.5:1 on every surface it sits on, and is reserved for the marks, badges, unread counts and errors; links, the wordmark, headings and selected controls go to ink. Type is Inter, self-hosted as one variable file under the SIL Open Font License, so the in-between weights Paper uses (360 for large headlines, 480 for controls, 550 for emphasis) are available with no third-party request. Buttons and inputs get one base style at zero specificity, so every existing component rule still wins: cream secondary buttons, solid-ink primary buttons, a press that scales to 97%. The landing gains a quiet top bar, a two-tone headline (the name in ink, the promise in gray at the same size), sections introduced by a plain lowercase line and a large light heading, a three-point 'how it works', and a footer. Inside the app, rail and list navigation read as rows rather than stacked buttons, selected tools and toggles are solid ink, capture cards are white paper cards, and the founder view's uppercase badge becomes a quiet lowercase line.

Rationale

Almost every color in the stylesheet already went through a custom property, so new token values carried the direction through the editor, the canvas panels, the founder view, the requirements hub and the walkthrough at once, and the few structural changes could concentrate on the landing. Every text pairing was measured against WCAG AA before it was chosen, and the tests that pin the tokens (visual-tokens, walkthrough-slides, brand-mark) now pin the new values.

D103 — Take project creation off the public landing, and make the example a readable captured page carrying one mark of each kind

2026-09-29 · build · accepted · Human directed

Problem

The public landing opened with a working capture form. An anonymous visitor could type addresses that were parked in the tab until they signed in (D067), so the first thing a stranger saw was a tool only the editor can use, and the page's top spent its space on a form rather than on showing what Pinata does. The static example below it was a gray wireframe with two pins: it showed that pins exist but not what a page looks like marked up, and none of the other three mark kinds appeared anywhere a visitor would see them.

Decision

The landing takes no address. Its hero ends in a call to sign in ('Sign in to start a review', a link to the sign-in form) beside a quiet link to the example; creating a project happens only on /pins/new, behind sign-in, and sign-in always lands on /pins. The anonymous entry form, the tab-scoped draft, and sign-in's draft routing are removed. The example becomes the hero's picture, placed directly under it: a readable captured pricing page (nav, headline, a monthly/annual toggle, three plan cards with prices, features, and buttons, a 'Most popular' tag) drawn in the captured site's own green palette so it reads as someone else's page, with one numbered mark of each kind drawn the way the canvas draws them — pin 1 on the toggle (the selected mark, with its thread and DOM context), circle 2 around a price that doesn't say per what, arrow 3 from 'Most popular' to the Pro plan, box 4 around the Pro card's call to action — and the panel lists all four by the product's own names.

Rationale

Only the editor can create a project, so the public page's job is to show the product and point to sign-in. The example now carries the whole vocabulary on a page a visitor can read, using the same mark geometry shapes, badge placement, and names the product uses, so it teaches the product truthfully rather than approximately.

Supersedes D067.

D104 — A dark theme that follows the device, with a toggle that remembers the visitor's choice

2026-09-30 · build · accepted · Human directed

Problem

Pinata had one theme. D102 left dark mode out because the brand mark, the canvas, and a handful of hard-coded colors each needed attention first, and Paper, the design direction, has a dark sheet of its own. The owner asked for a dark mode toggle.

Decision

Add a dark theme as a second set of token values, Paper's dark sheet as direction: page #181818, cards #1f1f1e, raised #2a2a27, cream ink #efefe4, gray #a8a8a2, a large-text gray #7c7c77, the accent lifted to #ff6b47 so it reads as text on dark and still carries dark text on pin badges, Paper's soft blue #81adec for focus, and dark-appropriate decision status colors. With no saved choice the page follows prefers-color-scheme; a toggle (a moon or sun icon button named 'Dark mode' whose pressed state says whether dark is showing) saves an explicit choice in localStorage. A small script in <head> copies the saved choice onto <html data-theme> before the first paint, following Next's 'preventing flash before hydration' guide, with suppressHydrationWarning on <html>. The toggle sits in the landing's top bar, the editor bar, the requirements hub header, and the founder view. The primary button's hover and the decision status colors became tokens so they flip with the theme; color-scheme makes native controls and scrollbars follow.

Rationale

Nearly every color already went through a custom property (D102), so a dark theme is a second value set rather than a second stylesheet. Every dark text pairing was measured before it was chosen and is locked by the same contrast suite as the light theme, and the public surfaces pass the same axe sweep in dark.

D105 — Give the canvas the window: a collapsible project sidebar, a fixed documentation footer, and a canvas as tall as the window allows

2026-09-30 · build · accepted · Human directed

Problem

The editor spent width and height on things that are not the canvas. D070 made the project rail a native disclosure, but collapsing it only folded the list vertically: the column kept its full 16–22rem width, so the canvas gained nothing. The documentation links took a whole row under the workspace, and the canvas was capped at 76% of the window height. The owner asked for the rail to collapse as a sidebar and the links to become a fixed footer, to maximize the editing area.

Decision

The rail becomes a sidebar that collapses as a whole: a 'Hide projects' chevron in its header shrinks the column to a 2.25rem strip holding 'Show projects', and the canvas column takes the rest. Both buttons carry aria-expanded and aria-controls. The choice is remembered in the browser (localStorage 'pinata:sidebar'), read after mount so the server and first client render agree; the per-project disclosures inside stay session-only as D070 set. The old root disclosure is removed so there is one way to collapse, not two. The open rail is sticky and scrolls on its own; on a phone, where it stacks above the canvas, it sits in the flow. The documentation links move into a thin fixed footer (2.5rem, hairline top, one line that scrolls sideways on a phone), and the page pads by its height. The canvas grows to min(100dvh − 11rem, 72rem), still bounded.

Rationale

Each change returns space to the canvas without removing anything: the rail is one click away, the links are still on every editor screen, and the canvas stays bounded so the page itself never scrolls for it.

D106 — The project rail becomes a drawer that overlays the canvas, so opening it never shifts the layout

2026-09-30 · build · accepted · Human directed

Problem

D105's collapsible sidebar took a grid column when open and a strip when collapsed, so every toggle reflowed the canvas and the panel sideways: the capture under the editor's cursor moved each time the rail opened or closed. The owner asked for the left navigation to be an overlay that sits on top of the canvas instead.

Decision

The workspace grid keeps one fixed 2.25rem strip for the toggle and never changes. The rail is a drawer that hangs from a sticky dock in that strip and overlays the canvas: a surface card with a shadow, above a faint veil that takes an outside click so it never reaches the canvas. It starts closed and closes itself when a page or an overview is chosen, on Escape, or on a click on the veil; focus moves to its 'Hide projects' control on open and back to 'Show projects' on close. Being transient, it is no longer remembered in the browser. On a phone the dock sits in the flow above the canvas and the drawer still overlays.

Rationale

The fixed strip is what removes the shift: nothing the drawer does changes a grid track, which the checks confirmed (the canvas column's box is identical with the drawer open and closed). Closing on a choice keeps the overlay out of the way of the work it serves.

D107 — Bring the piñata character into the public homepage with a coordinated illustration set

2026-09-30 · design · accepted · Agent proposed, human approved

Problem

The public homepage kept the brand character in its small header logo; long example metadata made the page feel text-heavy and left a large gap beside the capture.

Decision

Use the approved image-generation assets for a split hero, three illustrated process steps, a pencil mascot beside sign-in, a resting footer mascot, and a decorative burst from the asset sheet. Keep the example capture and comment thread visible and move its DOM context and mark list into a native details disclosure. Scope the layout to the anonymous root page. Use local Next Image assets, preload only the hero, reserve intrinsic dimensions, and keep pale paper illustration mats legible in both themes.

Rationale

The owner approved the paper-cut visual direction and generated assets, then explicitly requested implementation. An isolated checkout of current origin/main preserves the unrelated unfinished design checkout. Existing authentication, capture behavior, and editor styling remain in their established components.

D108 — Archive a project so it leaves the project list, as a separate column rather than a delete

2026-10-01 · build · accepted · Human directed

Problem

Every project the editor has ever made sits in the left-hand drawer, so the list grows with each friend's site and the ones still in play get harder to find. There was no way to put a finished project away short of deleting it, and the schema's deletedAt is a tombstone that every read treats as gone.

Decision

Projects gain a nullable archived_at column (migration 0007). POST /api/projects/[publicId]/archive stamps it, behind the standard editor mutation boundary (same origin, session, CSRF proof); archiving twice keeps the first timestamp, and a missing or deleted project is the generic 404. The editor's project list (GET /api/projects, listProjectHierarchies) leaves archived projects out. Nothing else changes: the single-project read, pages, captures, pins, threads, and the founder link all behave as before.

Rationale

One nullable column and one filter is the smallest change that takes a project out of the drawer while keeping it whole, so undoing it later is a matter of clearing that column.

D109 — Defer a way to unarchive a project

2026-10-01 · build · superseded · Raised and deferred

Problem

Archiving (D108) takes a project out of the list. Without a way back, an archive made by mistake can only be undone in the database.

Decision

Postponed by the owner in the same request that asked for archiving. The data is shaped for it: unarchiving is clearing projects.archived_at, and DELETE on /api/projects/[publicId]/archive is the natural route for it (it answers 405 until then). The interface needs a place to list archived projects to choose from.

Rationale

Recorded so the open question stays visible, and so the archive control's confirmation wording (nothing is lost) has a record to point at.

Superseded by D143.

D110 — Archive lives in the selected project's header, and an archived project's founder link keeps working

2026-10-01 · build · accepted · Agent proposed, human approved

Problem

Two choices inside D108: where the Archive control goes, and whether archiving should also end the founder's access.

Decision

An Archive button sits at the right end of the selected project's title row, beside the founder-link control, with the same inline Confirm / Cancel step that Rotate and Revoke use. Its confirmation says the project leaves the list and that pins, threads, and the founder link stay as they are. Archiving does not touch the founder capability: a founder holding the link can still open the project and reply.

Rationale

The header is where the other project-level actions already live, and keeping archive to the editor's own list makes it safe to do without thinking about who else holds a link.

D111 — Canvas controls float over the canvas as one compact toolbar

2026-10-02 · build · accepted · Human directed

Problem

Above the canvas sat a full-width hint line, a "Desktop — URL" heading, and two rows of text buttons (three fit modes, zoom out, zoom in, the zoom readout, then three draw tools), plus a row of text buttons for the overview and pin stepping. Together they took about 230px of height before the screenshot began. The owner also remembered an open request to move the canvas controls into overlays like Figma's or Paper's; no record of it existed, so this record is that request.

Decision

One floating toolbar sits over the bottom centre of the canvas: icon buttons for box, circle and arrow; zoom out; a "19% ▾" button that opens a small popup with Entire page, Fit width and Natural size; zoom in; and a "?" that opens the verb line which used to sit above the canvas. Icon buttons show their name and key in a tip on hover and keyboard focus, are solid ink while armed (D102), and take the shared blue focus ring. The row above the canvas becomes one compact line: a ‹ Overview button, the device toggle, the page address as a quiet caption (still the capture's h3, by the same name), and up/down buttons with "Pin 2 · 2 of 4". The canvas takes the height back (100dvh − 16rem).

Rationale

The owner asked for modern patterns: icons, clear interactive states, and dropdowns. Fit modes are used rarely, so they move behind the zoom readout as in Figma; the draw tools and zoom stay one click away. Every button keeps its accessible name as aria-label, so assistive tech and the tests address the same controls as before. The toolbar sits outside the canvas region's pointer handlers, so a press on it never drops a pin, and an open popup puts a clear veil over the canvas so an outside click closes it without reaching the canvas (as D106's drawer does). No dependency was added: the icons are inline SVG in the style of the drawer's chevron.

D112 — The capture panel collapses to a strip, and data keeps writing

2026-10-02 · build · accepted · Human directed

Problem

The right-hand panel (Selection, pins, Capture, Details) always took 17rem beside the canvas.

Decision

A toggle in the panel's top-right corner collapses it to a thin strip holding the toggle; the canvas widens to fill the space (this one reflows on purpose, unlike D106's drawer). Collapsing only hides the panel's content with the hidden attribute; the component stays mounted. The choice is remembered per browser in localStorage, read after mount, with every access in try/catch. A mark selected while collapsed shows as its number badge on the strip instead of forcing the panel open.

Rationale

The owner wants more room for the canvas and asked that collapsing never stop writes. All writes, seen-marking and live refresh live in the workspace, not the panel, and a test drops and saves a pin while the panel is collapsed.

D113 — Pin list rows in parts, and one spacing rhythm in the panel

2026-10-02 · build · accepted · Human directed

Problem

Each pin in the panel list read as one run-on line ("Pin 1 · “comment” · element text…") in the same color, and the last pin sat flush against the "Capture" heading.

Decision

Each row is in parts: a number badge in the accent color matching the canvas marker (quiet grey once resolved, squared for a box), the comment as the main line clamped to two lines, and the element as a smaller, dimmer line clamped to one. A resolved row says so, and unread replies show as a small "2 new" pill (D075). Rows are split by a hairline; hover and the selected fill are unchanged. Every heading in the panel gets the same space above it. The two .pin-list rule blocks are merged into one.

Rationale

The badge ties a row to its marker on the canvas at a glance; the comment is what the editor reads first. Each row's accessible name stays the mark's full label (D078), so screen readers and tests hear the same thing as before.

D114 — The selected pin's actions fit on one line

2026-10-02 · build · accepted · Human directed

Problem

In the 17rem panel, "Edit comment", "Delete pin" and "Resolve pin" each wrapped onto two lines and the last button spilled past the panel's edge.

Decision

The buttons show short words, "Resolve" (or "Reopen"), "Edit" and "Delete", and never wrap a label; a narrow panel wraps the row instead. Each keeps its full name ("Resolve pin", "Edit comment", "Delete box") as its accessible name, which begins with the visible word. Resolve comes first, in the solid primary style, as the usual next step; the edit and delete confirmations follow the same pattern.

Rationale

The owner pointed at the wrapped buttons in a screenshot. Short labels fit the panel at its width in both themes without widening it.

D115 — Pin text is never cut in the table, the Markdown, or the selection

2026-10-02 · build · accepted · Human directed

Problem

The pin table's Pin column, the copied Markdown's headings, and the panel's selection title all used the mark's short name (D078), which cuts the comment at 60 characters and the element at 40 with an ellipsis. The full comment was in the table, but in the last column, off the side of a wide table.

Decision

The table's Pin cell shows only the number badge and "Pin 1", and the whole comment moves to the column right after it (Page and Device stay first, D077). The Markdown heading is just "## Pin 1"; the element is on its own detail line and the comment is quoted in full under the details, with its replies after it (D097). The panel's selection title is the badge and "Pin 2"; the comment and element follow in full beneath it, and the pin-step line reads "Pin 2 · 2 of 4".

Rationale

The owner saw truncated pin text in the view and in the Markdown and called it out. The short name stays the accessible name of the list and table buttons, where brevity helps, but nothing visible or copied is cut.

D116 — Letting go of a selected pin: a × in the panel, and Escape

2026-10-02 · build · accepted · Human directed

Problem

Once a pin was selected there was no visible way to deselect it. Clicking empty canvas drops a new pin, and the only way out was clicking the same pin again in the list.

Decision

The panel's Selection heading carries a × "Clear selection" button while something is selected. Escape also lets go of the selection, as the last step after its existing order (a draw in progress, an armed tool, an open draft), and never while typing. An Escape that closes an open toolbar popup or the project drawer is used up there and does not also deselect.

Rationale

The owner could not find how to dismiss a selection. A visible control where the selection is shown, plus the key people already try, covers both pointer and keyboard.

D117 — The founder view shows pin text whole, and its page list gets its column back

2026-10-02 · build · accepted · Human directed

Problem

The founder's pin list and selection title still used the mark's short name (D078), which cuts the comment and the element with an ellipsis (left as a known gap by D115). Checking the founder page also showed its page list crushed into a 2.25rem column: D106 changed the shared .workspace grid for the editor's drawer toggle, and the founder page uses the same grid with a real list in that column.

Decision

The founder's list uses the same rows in parts as the editor's (D113), from one shared component, showing every status (Open, Replied, Resolved) since the founder acts on Open. The founder's selection title is the badge and "Pin 2", with "Points at: “…”" giving the element's text in full; the comment opens the thread below as before. The 2.25rem drawer strip moves to a .workspace-drawer modifier the editor alone uses, and .workspace returns to its 16–22rem first column for the founder.

Rationale

The owner asked for the founder view to match. One shared row component keeps the two lists from drifting apart. The grid regression came from D106 and was live in production; scoping the drawer grid to the editor restores the founder layout without touching the editor's.

D118 — Interactive patterns from Vercel's Geist: menu focus, tooltip timing, key caps

2026-10-02 · build · accepted · Agent decided alone

Problem

The owner invited using Vercel's design library and its interactive element patterns where they help ("if there's anything to be gained from using vercel's design library and interactive element patterns feel free"). The floating toolbar's popups (D111) left focus on their button, so a keyboard user had to Tab around, and focus fell to the page when a popup closed. Tooltips appeared instantly on hover, so sliding along the toolbar flashed every tip.

Decision

Adopt three Geist patterns without adding a dependency: the fit-mode popup behaves like a menu (focus moves to the pressed mode on open; arrow keys, Home and End move between modes; Escape or a choice returns focus to the button that opened it, and an outside press closes it without moving focus), and the help popup takes focus on open and returns it on Escape; tooltips show after a 400ms hover pause but at once on keyboard focus; shortcuts in tooltips are drawn as small key caps, as Geist's Kbd does.

Rationale

These are the patterns that change how the controls feel in use, especially from the keyboard, and they fit in a few dozen lines of the existing component and stylesheet. The rest of Geist's value is its visual language, which the owner already set differently.

D119 — A halftone wash in the piñata orange on the public landing

2026-10-02 · design · accepted · Human directed

Problem

The public landing's background was one flat colour: near-black in dark mode, which the owner found hard to look at, and plain cream in light. The piñata's orange appeared only in small accents and inside the illustrations.

Decision

Two decorative halftone washes in the accent orange: one behind the hero, strongest at the right edge beside the illustration and fading out before the sections below, with a faint second source low on the left; one inside the sign-in card, a halo around the mascot in the card's middle column (where #17 moved it), clear of the copy beside it; on a phone, around the mascot between the copy and the sign-in form. Dots grow where the wash is strong and vanish where it fades, as print halftone does, over a soft glow of the same orange (an ember on black, a warm tint on cream). Both are pure CSS: a grid of soft dots added to a large gradient and thresholded with a contrast filter, then coloured through blend modes so the ink is always the accent token. The top bar stays clear; on a phone the hero wash moves down behind the illustration, clear of the paragraph; forced-colors (high contrast) mode hides both.

Rationale

The owner asked for a second colour from the piñata palette, as dot-matrix gradient shading, paired with black or white, taking inspiration from a post on drawing patterns with code (generated SVG mosaics and backgrounds that cost less than an image). The accent orange is the piñata's own colour; orange on black in dark mode and orange on cream in light pair it with black and white as asked. The landing must make no third-party requests, which a CSS-only pattern keeps.

D120 — Hover a mark to read it, and see the element it points at

2026-10-04 · design · accepted · Human directed

Problem

Reading a note on the canvas meant clicking its mark, which also changed the selection and the panel; and nothing on the screenshot showed which element a note was about, only the element's text in the panel. A screen recording of Paper's comments showed both solved: a preview card on hover, and a dotted outline around the commented element.

Decision

Hovering a saved mark (pin, box, circle, or arrow) shows a small dark card beside it after a short pause: the mark's badge and title, its status and unread replies, the whole comment, and what it points at. Never during a draft, a draw, a drag, or with a toolbar popup open, and not for the mark the panel already shows. While a mark is hovered, or else while one is selected, the element it is attached to is outlined with a dashed line in the focus blue; a draft's nearby-candidate highlight keeps its orange fill so the two never read alike. Small polish alongside: saved markers lift slightly under the pointer, and the canvas behind the screenshot has a faint dot grid. Both views get it: the editor and the founder's page.

Rationale

The owner picked these two from the video review ("3 and 4 are spot on") and asked for slight visual and UX improvements alongside. The card reuses the draft composer's placement, which keeps a popover inside the canvas; the outline reuses the existing highlight node with a second variant. No dependency was added.

D121 — An agent link: a secret, read-only brief of the open marks

2026-10-04 · build · accepted · Human directed

Problem

Handing feedback to a coding agent meant copying the Markdown export and pasting screenshots in one at a time. The owner wanted an easier way to pass a project to an agent, without managing keys or accounts yet.

Decision

Each project can have an agent link, created from a new "Agent link" control beside "Share with founder". It is a secret URL, /a/<token>, that serves a live Markdown brief: a short "what to do" section, then one section per screenshot with a direct link to the image (/a/<token>/captures/<id>, no sign-in), then every open mark as the copy export writes it (status, position, element, path, the whole note, its replies). Resolved marks are left out and counted. Creating the link shows it once, with a one-line prompt to paste into an agent; Rotate and Revoke each ask first. It is stored like the founder link (only a SHA-256 digest, a version, a revoke time) in its own columns, so the two links never affect each other.

Rationale

The owner asked for something easier than Markdown copy and image paste, with no key management ("I just want to avoid key management for now"), and approved the agent link ("go ahead and build the agent link - great idea!"). It reuses the founder link's token scheme, the project pin read, the Markdown export, and the screenshot delivery code, and adds no dependency.

D122 — The project's link controls as pills with anchored cards

2026-10-05 · design · superseded · Human directed

Problem

"Share with founder" and "Agent link" each took a full row of plain buttons with their state in loose text, and opening one pushed a wide box of stacked labels, fields, and same-weight buttons into the page. The owner called it very clunky.

Decision

Both controls are now pills on one row under the project title: an icon, the name, and a caret, joined to a status dot and a short state (Off, Active · v4, Revoked). Opening one shows a card anchored under its pill, with a title and a close button, one line saying what the link is for or what state it is in, the new link in a field with its copy button attached, the agent prompt in a box whose footer holds the one emphasized button (Copy prompt), and Rotate and Revoke as quiet actions at the bottom, Revoke in the accent. Confirming a revoke turns the step into a tinted box with a solid red button. Escape or the close button closes the card and returns focus to the pill. On a phone, the card drops into the page at full width instead of floating.

Rationale

The owner asked for it directly ("let's update the sytles for this ... it's very clunky"). The pill-and-card pattern matches the canvas toolbar's popups (D111) and the icons come from the same set. Behavior, accessible names, and the one-time display are unchanged; only the short state words changed, so three tests that read them were updated. No dependency was added.

Superseded by D146.

D123 — The landing page's sign-in as one dialog

2026-10-06 · design · accepted · Human directed

Problem

PR #14 (from v0) moved the landing sign-in into a modal, but it was built on an older landing page, its CI was failing, and it turned the whole landing into a client component. Since the redesign (D119), the sign-in form sat inside the invitation card.

Decision

Every sign-in call on the landing page (the top bar, the hero button, a new button in the invitation card where the form was, and the footer) opens one shared dialog with the password form. It is the browser's own dialog opened as a modal: the page behind is inert, focus moves to the password field and back to the button that opened it, and Escape, the close button, or a click outside closes it. A link to /#editor-login still opens it. The landing page stays a server component; only the dialog and its buttons run in the browser.

Rationale

The owner asked to merge PR #14 and close it out ("merege and close", then "go ahead and do PR 14"). This keeps its intent and replaces its code.

D124 — Signing in again without losing work

2026-10-06 · build · accepted · Human directed

Problem

A tab left open past the end of the editor session still showed its screenshots and pins, but every new request was refused. Dropping a pin or drawing a box said only that nearby elements could not be loaded, and saving said it could not be saved, so it looked like a breaking change.

Decision

While the editor is open, any request to the editor's own API that comes back 401 opens a "Sign in again" dialog in place. The page is not reloaded, so the draft and its comment stay. Signing in sends the refused request again with the new session and CSRF proof, so the pin or box that failed to save simply saves; several refused requests wait on one sign-in. Closing the dialog lets them fail as before, draft still on screen. Because a new mark asks for nearby elements right away, an expired session shows up when the mark is dropped, before any typing. Separately, when nearby elements fail to load for any other reason the draft offers Try again, and the keyboard hint under the Save and Cancel buttons is gone.

Rationale

The owner confirmed the failures came from an expired sign-in and asked for the simple best practice: stop the work from going on silently, keep the change, and make them sign in again when it saves.

D125 — A box or circle can be attached to several elements

2026-10-06 · build · accepted · Human directed

Problem

Some notes are about the space between elements, like the gap between the hero headline and the shirt image, and the fix may need margin or padding on both. A mark could be attached to only one element, so the other side of the gap was never named for the agent or developer reading the note.

Decision

A box or circle draft lists its nearby elements as checkboxes: the first one ticked is the main element, and up to four more can be added; No element clears them all. The chip reads, for example, "2 elements · “Good clothes for…”". The server checks every extra id against the capture's own manifest and stores their snapshots in a new also_elements_json column (migration 0009); pins and arrows keep a single element. Hovering or selecting the mark outlines every attached element on the screenshot, and the details panel, pin table, hover card, Markdown export, and agent brief list each one with its path. While testing it, a long-standing bug surfaced and was fixed: the draft panel did not reposition when its element list opened, so the first click in the list moved the panel and missed.

Rationale

The owner asked for it directly: "can we make it so that the box / circle selectors allow for multi-select for near elements (optionally)? in this case, i want to call out space between dom objects, and it might requre margin/padding changes to both". No dependency was added.

D126 — The landing example uses the app's pin table; New project moves into the projects menu

2026-10-07 · design · accepted · Human directed

Problem

The landing page's "Explore the details behind each pin" showed a two-column layout (one mark's DOM context beside a numbered list) that looked rougher than the pin table in the app. Separately, "New project" sat in the editor's top bar, away from the list of projects it adds to.

Decision

The landing details now render the app's own PinTable, filled from the example fixture: page, device, badge, the whole comment, status, position, and element with its path, and a working "Copy all as Markdown". A mark with a founder reply in its thread reads Replied. In the editor, "New project" moves from the top bar to the top of the projects menu, just under its header. With no projects there is no menu, so the empty state's "Create your first project" stays the way in; when the project list fails to load, a "New project" link sits beside Try again.

Rationale

The owner asked for both: "in the app this table looks cleaner than it does on the sign-in page. please udpaet." and "let's move the \"new project\" button into this menu." No dependency was added.

D127 — Sentence case, "Pinata" capitalized, and a demo video on the landing

2026-10-07 · design · accepted · Human directed

Problem

Feedback left on yourpinata.dev itself, read through the agent link (D121): links, buttons, headings, and footer text were lowercase, several forced by CSS; the brand appeared as "pinata" in running text; and the example showed a still image of a finished review rather than the experience of making one.

Decision

Every visible label on the landing is in sentence case, and the CSS that forced lowercase on the top links, section eyebrows, footer headings, and the founder page's badge is gone. "Pinata" is capitalized everywhere except the logo's wordmark: the hero heading, page titles, the logo's spoken name, the footer, and the walkthrough heading. The landing example now plays an eighteen-second looping demo, drawn in the browser with Remotion from the same fixture as the table below it: a cursor picks each tool and adds a pin, a circle, an arrow, and a box, each comment types in, the link is sent, and the founder's reply lands on pin 1. It is muted and has play and pause controls; with reduced motion, or before script loads, the static example shows instead. The walkthrough's annotate slide and transcript, which still said circles and arrows were to come, now describe all four mark kinds.

Rationale

The owner left five marks on yourpinata.dev and handed them over through the agent link: "We need consistent casing for links/buttons. Let's go with sentence casing across the board.", "Pinata as a brand should be capitalized. only in the logo will it be call lower case.", "Let's sentence case all of this. not a fan of all lowercase.", "let's re-render this to include square and circles as well. in face, let's use remotion and render a simple walkthrough demo video of the experience here.", and "more sentence casing, please". No dependency was added.

D128 — The pin panel as one accordion; the projects menu as a switcher

2026-10-07 · design · accepted · Human directed

Problem

The pin panel showed the selected pin above the list, so picking another pin changed everything above the list and the row moved out from under the pointer; the comment appeared three times; fixed help text sat between the reader and the other pins. In the projects menu, clicking a name only opened or closed it, going to the project was a separate Overview button, pages were a third kind of button, the current-project bar and the open state were unrelated, and the page count looked like a feedback count.

Decision

Pin panel: one list where every mark is a row and the selected one opens in place — its status, the comment once, the element, Resolve / Edit / Delete, then its replies, which scroll inside the row starting at the latest, with the reply box behind a Reply button. Resolved marks gather in a closed "N resolved" group that opens when its mark is selected. The drag hints left the panel (the canvas help covers moving); the delete confirmation says the number is retired; page and device moved into Details. Projects menu (proposal B): a flat list of projects, each with its open-pins count; a click anywhere on the row shows that project's overview and closes the menu. Each project's addresses sit behind a small (i) beside its name, shown on hover or keyboard focus, so no URL takes room in the menu. A project's pages are picked in the project: its overview cards, or a page picker above the canvas (shown when there is more than one page). The project title in the header is now the project's heading. Along the way: signing out is a full page load (it no longer reopens the sign-in dialog from a cached /#editor-login), and several end-to-end specs that CI skips were brought up to date.

Rationale

The owner asked to rethink both: "the Pin menu behavior is really weird. it's hard to navigate. should we try an accordian wher ethe active pin takes up the bulk of the space, but you can still easily get to the others?" and "it's unclear what opens/closes the project entry vs. jumping into the entry itself. please revisit and come up with two proposals." Then chose: resolved pins in a closed group ("yes"), scrolling inside the row ("let's do this"), and "go with Proposal B. this sounds right." No dependency was added. On seeing the old menu live, the owner added: "let's move the URL into an onHover (i) icon next to the project name. it's cuombersome in the menu."

D129 — Add pages to an existing project

2026-10-07 · build · accepted · Human directed

Problem

A project's pages were fixed when it was created. The only place to enter addresses was the New project form, the server had no way to add a page to a project that already existed, and the overview had no control for it. The one related control, the scoped retry under a screenshot, did take a fresh screenshot of a page that had worked, but it was labelled "Retry", so it read as a failure-only action.

Decision

The project overview ends with an "Add pages" card, dashed like "+ New project" in the projects menu, which says how much room the project has left. Pressing it opens a form in its place across the row: URL rows like the New project form's, finished the same way (a bare domain gains https://, a path like /pricing resolves against the project's root, D097). POST /api/projects/[publicId]/pages adds the rows behind the same boundary as creation (same origin, session and CSRF proof, content type and byte cap, strict schema, per-row URL corrections by index with nothing echoed) and commits, in one transaction, the idempotency record, the new pages after the existing ones, and a pending Desktop and Mobile attempt for each, then drives them after the response (D076). An address the project already has is skipped and reported by row, never added twice; if every row is already a page, nothing is written and the form stays open with a note on each row. The project's limits hold across additions: 16 unique pages and 64 screenshots in all. An archived or deleted project takes no pages. Under a screenshot that worked, the scoped retry now reads "Take a new Desktop screenshot" (or Mobile); after a failure it still reads "Retry … capture".

Rationale

The owner asked: "We should have a means to add new images to an existing project. Am I missing that somewhere? Otherwise, we should definitely have an \"Add new\" screen or something like that, since we support multiple URLs." The proposal was a card at the end of the overview's page cards that opens a form in place, the server route mirroring creation, the limits shown on the card, already-present addresses skipped with a note, and the Retry rename. The owner answered: "i agree with you UX strategy. let's do it." No dependency and no database change: the pages and captures tables already allow more pages per project, and the unique page index is what refuses a second copy of an address.

D130 — Sign in once a week: editor sessions last 7 days

2026-10-10 · build · accepted · Human directed

Problem

An editor session lasted 12 hours and renewed only inside its last 2 hours, so a day away from Pinata meant signing in again. With a Chrome extension that signs in too (D132), that would have meant signing in twice as often.

Decision

EDITOR_SESSION_ABSOLUTE_LIFETIME_MS is 7 days (604,800,000 ms) and EDITOR_SESSION_RENEWAL_THRESHOLD_MS is 6 days (518,400,000 ms): any session at least a day old renews on its next request, with a fresh 7-day expiry. Signing in again is needed only after 7 days without using Pinata. The extension's token follows the same two constants. POLICY_VERSION moves to 2026-10-10.1; docs/EVALS.md and docs/ARCHITECTURE.md republish the values, and the tests that hardcoded 12-hour ages now derive them from the constants.

Rationale

The owner asked to change the re-auth window to 7 days. The renewal threshold keeps the existing design (renew inside a threshold, D024/D098) and sets it so the window slides with use; at most one renewal a day rewrites the cookie pair.

D131 — Screens behind a sign-in: a Chrome extension captures them, and Pinata imports captures

2026-10-10 · build · accepted · Agent proposed, human approved

Problem

Pinata's capture visits a page from a remote browser as a stranger, so anything behind a sign-in, on a staging host, or on the editor's machine came back as a sign-in page. The workaround was to save the pages as HTML, publish them on a public host, and capture those addresses. There was no way to comment on a screenshot taken any other way.

Decision

A Manifest V3 Chrome extension (extension/, loaded unpacked, no build step) captures the tab the editor is looking at. Through chrome.debugger it drives the tab the way the provider drives its browser: Desktop (1440) and Mobile (390) viewports at DPR 1, one lazy-scroll pass, animation disabled, the provider's own element pass (MANIFEST_INSPECT_SOURCE with the same limits, copied into extension/shared.generated.js and drift-checked by a test), and one full-page WebP screenshot of exactly the document that pass measured; then it restores the tab. It runs in the service worker, so closing the popup does not stop it. Its result goes one of two ways: "Send to Pinata" (D132), or "Download file", a .pinata.json capture file (format pinata-capture, version 1: the page address and title, the time, and per device the viewport, document size, element list, and base64 image). A failed send saves the file instead. Pinata imports both through POST /api/imports, one device per multipart request (a meta JSON part and an image part, D133), from the editor's page or the extension's token: the image is decoded structurally and must be exactly the document size it claims, the element list gets the provider envelope's schema and the same server-side bounding, the image is stored privately, and one transaction writes the idempotency record, a new project or page when needed, and the capture as the next ready attempt with origin upload. In the editor: an "Upload a capture" card on the overview (a capture file's address picks or makes the page), "Upload a new version" under every capture (always that page), and "Start from a capture file" on New project. A plain PNG, JPEG, or WebP uploads too: re-encoded in the browser as WebP (which drops its metadata), a high-DPR screenshot scaled to the device width, and no element list, so marks on it attach to no element. /pins?project=<publicId> opens a project, which is where the extension's "Open in Pinata" goes.

Rationale

The owner asked for a Chrome plugin that screenshots a page and pulls down the rendered DOM as one uploadable asset, image upload with comments, and feedback on whether authenticated capture would be better. The agent recommended the extension over authenticated capture, with the capture file, the upload card, origin upload, and no provider retry for uploads. The owner pulled Send to Pinata into scope and approved the rest. Chrome shows a "started debugging this browser" bar during a capture; that is the cost of the protocol, and the README says so.

D132 — The extension signs in to Pinata with its own token and sends captures directly

2026-10-10 · build · accepted · Human directed

Problem

Downloading a file and uploading it again is two steps for every capture. Sending straight from the extension needs it to act as the editor, but the editor's cookie is SameSite=Strict, every write checks the Origin and a CSRF proof, and an extension's requests come from its own origin.

Decision

The popup signs in with the editor password through POST /api/extension/session, which has the login route's boundary and shares its throttle buckets, and returns a bearer token, never a cookie. The token is the session's HMAC over SESSION_SECRET with its own version prefix (x1) and audience, so it never verifies as a cookie session and a cookie never verifies as it; it lasts 7 days and comes back renewed once a day old in the x-pinata-token response header (D130). It is kept in chrome.storage.local and sent in the Authorization header, which no browser attaches on its own, so those requests need no CSRF proof or Origin check. It opens only the extension's routes: GET/DELETE /api/extension/session (check or sign out), GET /api/extension/projects (live projects and their pages, to pick a target and spot a page the project already has), and POST /api/imports. The popup shows the tab's address (editable), a project (the one that already has this page, else the one this site went to last, else New project with a name), Desktop and Mobile, and Send to Pinata beside Download file; after a send it links to the project and selects it for the next send. The Pinata address defaults to https://yourpinata.dev; http://127.0.0.1:3100 works for local runs, and any other address asks Chrome for permission first.

Rationale

The owner pulled Send to Pinata into scope with sign-in for the one editor. A separate token kind keeps the cookie boundary exactly as it was, and the shared throttle means the extension adds no new way to guess the password.

D133 — Uploads go through Pinata's own route, one device per request, with a 4 MB image cap

2026-10-10 · build · accepted · Agent decided alone

Problem

A Vercel Function accepts at most 4.5 MB of request body, and a full-page screenshot plus its element list can be larger, especially as PNG.

Decision

Each device is its own request, and an uploaded image may be at most UPLOAD_IMAGE_MAX_BYTES (4,000,000 bytes) inside a request capped at UPLOAD_REQUEST_MAX_BYTES (4,450,000 bytes), enforced while the body is read. The extension screenshots as WebP and steps the quality down (90 to 40) until the image fits; a page too tall for WebP (over 16,383 pixels) falls back to PNG and fails if that does not fit. The upload form does the same for a plain image. MAX_IMAGE_BYTES still bounds everything stored.

Rationale

Inside the latitude the owner gave ("take this and run with it"): the server keeps its existing decode-then-store order (D044, VAL-CAPTURE-014) with no new storage pattern. Full-page WebP at DPR 1 is typically well under 1 MB (the end-to-end run measured 15 to 52 KB on Pinata's own pages).

D134 — An upload's address is a label: localhost, ports, and plain http are allowed

2026-10-10 · build · accepted · Agent decided alone

Problem

Page identity was defined by the project URL rule (public https only, no ports, no IP literals, no reserved names) because the provider fetches those addresses. Uploads exist for exactly the screens that rule refuses: a local build on http://localhost:3000, a staging host on a port, an intranet name.

Decision

normalizeUploadUrl gives an upload's page identity: wherever the project rule admits the address, its result exactly (so an upload of a page the project already has lands on that page); beyond it, http, ports, reserved names, and IP literals are allowed. Credentials, other schemes, oversize input, and fragments are still refused or dropped. Nothing fetches an upload's address, and an uploaded capture is never offered a provider retry (VariantSummary.retryable is false for origin upload); a page filed this way is captured by the provider only if its address also passes the project rule and the capture admission that runs before every provider call.

Rationale

Inside the latitude the owner gave: the address is only displayed and matched, and the provider-side guards (D043, the DNS and redirect admission) are unchanged, so a label cannot become a fetch.

D135 — Look at Codex's in-browser element comments

2026-10-10 · design · pending · Raised and deferred

Problem

The owner pointed at Codex's in-browser commenting: pick an element on the live page and type (or dictate) a comment in a bubble anchored to it. Pinata's extension captures the page and the comment happens on the canvas afterwards.

Decision

Deferred: compare later whether the extension should also take a comment on the live page, with the element picked there, and send it as a pin on the capture.

Rationale

Raised as a side note for later while the extension was being built.

D136 — Keep a brand reference at the repository root, updated with every material branding decision

2026-10-11 · design · accepted · Human directed

Problem

The brand lived in pieces: tokens and their contrast notes in app/globals.css, the mark in src/lib/brand-mark.ts, the illustration style in docs/brand/homepage-illustration-prompts.json, the voice and casing rules in D078 and D127, and the direction in D102, D104, D107 and D119. Nothing gathered them, so a new surface (the extension popup, the walkthrough) had to rediscover the rules and sometimes diverged.

Decision

brand.md at the repository root gathers the name and casing rules, taglines, voice, the mark, the light and dark tokens with their contrast contracts, the Inter weight scale and type sizes, shape and spacing, motion, how marks are drawn, the illustration style, theming, the accessibility floor, the surfaces that diverge on purpose, and a checklist for changing any of it. The sources stay authoritative (the stylesheet, the mark module, the decision log, the tests that lock them); brand.md explains them in one place. Any material branding decision gets a record here and an edit to brand.md in the same commit; AGENTS.md carries that rule.

Rationale

Requested by the owner. Writing it from what is already shipped, rather than from a fresh design pass, keeps it honest: every value in the file is one a test or a stylesheet already enforces, and the two places that drift (the extension popup, the walkthrough weights) are named rather than papered over.

D137 — Publish landing discovery metadata and public-only crawl entry points

2026-10-11 · build · accepted · Human directed

Problem

The landing had only a title and description. Search engines, social unfurls, and agents lacked an image, a canonical URL, and crawlable public entry points.

Decision

Set the production origin as the metadata base; give only the root page its canonical URL, Open Graph and Twitter cards using existing same-origin landing art. Publish robots.txt, a sitemap of the seven public pages, and a short llms.txt pointing at the landing, walkthrough, and requirements hub. Keep private workspace, founder, agent-capability, and API paths out of discovery.

Rationale

The owner explicitly asked for search, social, and agent discovery of the landing. Reusing the existing copy and art and limiting crawl entries to anonymous public routes makes this a bounded implementation choice without new product claims or dependencies.

D138 — The agent brief leads with text: nearby elements, screenshot sizes, and crop-before-viewing

2026-10-11 · build · accepted · Agent proposed, human approved

Problem

The owner noticed that a coding agent reading the agent link (D121) cuts each full-page screenshot into pieces and pays for every piece, and asked whether the hand-off could cost fewer tokens. A full-page capture is tall (the mobile Chickpea page is about 13,000 px), and a vision model shrinks any image to roughly 1,568 px on its long edge before reading it, so the whole image is unreadable and the agent has to crop around each mark. The brief told it to "download each screenshot" without saying how big the image was or that the element text and path were often enough.

Decision

The brief now leads with text. Each mark lists the elements around it from the capture's own persisted manifest (tag, text, position, size; the nearest four that have something to read, never the mark's own elements), ranked the way the composer ranks candidates. Each screenshot link names the image's pixel size. The "What to do" section says to start from the text, open the image only when the note cannot be understood without it, and crop about 1400 × 800 px around the mark before viewing. The copy export is unchanged: the nearby lines are an optional field it does not fill.

Rationale

The avoidable cost was around the crops, not in them: the wasted whole-image read, the tooling to crop, and crops for notes the text already explained. Nearby elements cost a few dozen tokens each and replace most crops; the size line lets an agent crop straight away when it does need to look. No dependency and no database change: the manifest and the document size were already persisted per capture.

D139 — Serving crops or tiles of a screenshot to agents

2026-10-11 · design · pending · Raised and deferred

Problem

Beyond the text-first brief (D138), the agent could be spared cropping altogether if Pinata served a crop around each mark, stored one per mark, or stored viewport tiles at capture time. Each needs either an image codec (a new native dependency) or more capture-time work and storage.

Decision

Deferred: revisit once the text-first brief has been used on a few projects. If agents still crop on most marks, pick between a crop route, a stored crop per mark, and capture-time tiles. The options, their costs, and what would make each worth doing are written up in docs/RECOMMENDATIONS.md (R001, R002, R003).

Rationale

The owner took the two no-dependency changes and asked for the rest to be logged for later rather than decided now.

D140 — The demo video opens the landing under the hero, filmed from the real product scene by scene

2026-10-15 · design · accepted · Human directed

Problem

The landing's demo (D127) was drawn in the browser from the example fixture: a toolbar of text buttons, dark comment bubbles, and a copied-link pill the product never had. As the product grew (the pin panel, the founder and agent links, capture import), the video showed less of it, and it sat third on the page, below the hero and three static illustrations. A drawn demo also has to be redrawn by hand whenever the interface changes.

Decision

The demo video now sits directly under the hero, at the full content width, with a button per chapter (Capture, Annotate, Share, Reply, Hand off). Every frame is a screen of the real product, filmed by `npm run demo:film` (scripts/demo/) from the production build on a scratch Pinata seeded with the demo data (D142): a project created and its page captured, a pin and a circle drawn and commented, the founder link created and copied, the founder replying in place, the reply arriving, and the agent link with the brief it returns. Remotion plays those screens with a cursor, typing, the circle being drawn, camera moves, and chapter titles, in the page's own theme; each screen is filmed in light and dark. The film is split into six scenes. Each scene records its screens' targets, text fields, and mark positions in remotion/demo/shots.json and lists the source files that draw them, so `--list` reports which scenes went stale and `--scenes` films only those, leaving the rest of the video as it was. Without script, and with reduced motion, the video is a still of the real workspace with a play button. This replaces the drawn demo from D127; that record's casing changes stand. The still example lower on the page keeps its capture, thread, and pin table.

Rationale

The owner asked for the video to move up because it represents the product better than the illustrations, for it to show the product as it is now, and for a reusable reference so that videos can be updated in part as the product changes. Filming the product itself answers the second; splitting the film into scenes, each with a recorded list of what is on its screens and which files draw them, answers the third: a changed screen is refilmed alone, and the cursor follows its buttons to wherever they moved.

D141 — A scratch Pinata can keep its screenshots on local disk

2026-10-15 · build · accepted · Agent decided alone

Problem

Every screenshot lives in private Vercel Blob, so a local run against a scratch database could create projects but never show a capture: the 2026-10-13 sandbox sessions noted the canvas showing only alt text. Filming the demo (D140) that way would have meant writing screenshots to the production store with the production token and deleting them afterwards, on every filming.

Decision

With PINATA_LOCAL_BLOB_DIR set, the server keeps screenshots in that folder through the same ScreenshotStore contract the Blob adapter has (put, head, get, delete, with the same results and error codes). The variable is honored only when TURSO_DATABASE_URL is a file: database and VERCEL is unset, and pathnames cannot leave the folder; both rules are enforced in code and tested. Unset, nothing changes. The file calls carry turbopackIgnore so the build does not trace the whole repository into the server functions that can reach the store. scripts/seed/scratch.mjs sets the variable for every scratch run.

Rationale

Safe to decide without asking: it is local tooling inside the owner's request for a reusable way to regenerate the video. It cannot take effect in production (refused on Vercel and beside any database that is not a local file), and with the variable unset the server behaves exactly as before.

D142 — Keep seed data in the repository and replay it into a scratch Pinata through the API

2026-10-15 · build · accepted · Human directed

Problem

Filming the demo (D140), checking a change locally, or giving another agent a realistic workspace all need a known state: a captured page, marks with notes and elements, a founder link, replies. That state existed only in the shared database, which local runs must not touch, and no script built one.

Decision

scripts/seed/ keeps one seed, chickpea.json: the Chickpea project, its pricing page (an HTML copy laid out so its elements sit where the landing's example puts them), and the four marks with their elements, notes, and the founder's replies, the same as the landing's example (a test keeps the two in step). apply.mjs replays it into a running Pinata through the product's own API in stages (empty, captured, marked, shared, replied, handed-off): the page is captured on desktop and mobile the way the Chrome extension captures one (D131) and imported, then the marks, links, and replies are created as the editor and the founder would. scratch.mjs starts a throwaway Pinata on a file database with screenshots on disk (D141) and applies a seed; `npm run seed` does both for a look around.

Rationale

The owner proposed keeping a seed in the repository to regenerate the video from as the application changes, updating the seed as it goes. Stages let any scene of the video start from its own point without replaying the ones before it through the interface.

D143 — Give editor project, page, device, and note durable addresses and restore archived projects

2026-10-15 · build · accepted · Agent proposed, human approved

Problem

Workspace navigation lived only in React state, so a reload or shared editor address lost its page, device, and note. Archiving hid a project without an editor control to bring it back (D109).

Decision

Keep the editor-only /pins route and its existing ?project= public-ID links. Extend its query with stable page ID, desktop or mobile device, optional capture version, and note ID. Browser history follows workspace navigation; a note resolves only against the authorized project's pins. GET /api/projects keeps active projects separate from archivedProjects for the editor, and DELETE /api/projects/[publicId]/archive restores an archive behind the same session, origin, and CSRF boundary as Archive. Archived pages, captures, pins, threads, and capability links are unchanged.

Rationale

The owner accepted the artifact's combined recommendation. Query parameters extend the existing /pins?project= link without new route authorization rules or a migration. The editor can find archived projects in a separate section and restore them without changing the founder's access.

Supersedes D109.

D144 — Show one overview card per page with a Desktop and Mobile preview toggle

2026-10-16 · build · accepted · Agent proposed, human approved

Problem

D077 showed a separate overview card for each Desktop and Mobile capture. Reviewing a multi-page project meant scanning duplicated page addresses and twice as many cards as pages.

Decision

Show one overview card for each submitted page in page order. A Desktop and Mobile toggle changes that card's authorized thumbnail, capture state, and stable editor link without leaving the overview. The card's feedback line sums the selected captures of both devices, including local seen adjustments. Opening the selected preview navigates to its page and device; a modified click can open the same durable address in another tab. The canvas device toggle, independent capture versions, project-wide pin stepping and table, and per-capture Markdown remain as before.

Rationale

The agent raised page cards as an alternative to D077, and the owner approved. The existing page-level feedback helper and D143 editor address contract support a page card without changing capture storage or authorizing a new image route. D077's per-capture card layout is superseded; its remaining canvas and project-wide navigation choices continue.

Supersedes D077.

D145 — Open new captures at fit width

2026-10-16 · build · accepted · Agent proposed, human approved

Problem

D055 starts tall captures in the Entire page view, which can shrink a page to a few percent of its natural size. The review proposed a readable initial camera without changing the remaining canvas layout.

Decision

A capture with no remembered camera starts in Fit width, with the top edge visible and its width inside the stage. Fit width never enlarges beyond 100%; narrow captures center at natural size. Entire page and Natural size remain available. Returning to a capture restores its own session camera; camera gestures still end resize-follow. Camera state stays session-local, never enters browser history, and never causes annotation mutations.

Rationale

The agent raised Fit width as a product question and the owner approved only this camera default. The approved recommendation also caps the view at 100% so a narrow screenshot does not blur from upscaling. This reverses D055's initial mode, not its other camera controls or its local-state boundary.

Supersedes D055.

D146 — Offer agent, person, and Markdown handoff from one Send sheet

2026-10-16 · design · accepted · Agent proposed, human approved

Problem

Two separate header pills hid the whole-project Markdown export in the pin table. Combining them risked suggesting a previously issued secret could be copied again, contrary to the capability contract.

Decision

Replace the two header entries with one Send button and one sheet with Coding agent, Person review, and Markdown choices. The first two use their existing independent capability endpoints, retain explicit confirmation before rotating or revoking an active link, and show a new URL only at issue time. Switching choices or closing the sheet forgets a new URL; reopening reads status but cannot recover the token. Markdown copies the existing complete project export after notes load and does not issue a capability. The agent brief and its screenshot links are unchanged.

Rationale

The review artifact proposed consolidation and the owner approved it only under today's token rules. Reusing existing capability operations keeps the old URL invalidation and independent agent/person semantics while changing only the editor presentation.

Supersedes D122.

D147 — Use draft pull requests for the approved editor overhaul only

2026-10-16 · build · accepted · Agent proposed, human approved

Problem

D010 usually commits directly to main, but the approved editor overhaul has independent changes to the camera, Send, navigation, and overview. Combining them before review risks destabilizing the working demo and obscures the decision trail.

Decision

For this editor overhaul, work on separate branches and deliver draft pull requests for human review. Keep Node 24 npm run validate as the gate before committing. Do not change D010 as the default rule for other work.

Rationale

The factory proposed a narrow exception, and the owner approved draft PRs for this overhaul. It is not a reversal of the general direct-to-main rule.

D148 — Remove the project-documentation links from the page footers

2026-10-20 · build · accepted · Human directed

Problem

The editor carried a fixed footer (D105) and the landing footer a "How it's built" column, both listing Requirements, Architecture, Milestones, Decisions and Evals. Those links date from the assignment that started the project and read as scaffolding to a product user.

Decision

Remove the editor's fixed footer and the landing footer's documentation column, along with the LandingLinks component and its styles. The /reqs pages stay, reachable from the landing top bar's "How it's built" link and their own sidebar.

Rationale

The owner called the footer links an artifact of where the project started.