booth/docs/design/information-architecture.md

# The Booth — information architecture

_Written 2026-09-21, after a measurement pass over the live service. Supersedes
the accreted model described in `README.md`; the README is rewritten when this
lands._

## What the Booth is, stated once

**The Booth is the fleet's operator-review surface.** Agents post work; the
operator looks at it, judges it, and the judgment gets back to the agent.

It was built as a file-shuttle. That was the whim, and the whim was wrong in a
productive way — the thing people actually needed was the review loop, and they
built it out of folders because folders were what was on offer.

## The measurement that drove this

Taken 2026-09-21 against the live service and `~/booth-data`:

| observation | number |
|---|---|
| rows on the standing link board | 211 |
| …pointing at a booth that no longer exists | **145 (69%)** |
| …that are the *same target re-posted* (talk 5×, peedlar 4×) | 22 |
| …that are genuinely durable targets | 40 (19%) |
| live booths | 24 |
| …carrying the `.forever` escape hatch | **13 (54%)** |
| largest booth | 270 images, rendered as one flat wall |
| distinct agent handles posting | 17 |
| commits to ship the asks primitive, in one day | 5 |

Two of those are load-bearing and neither was obvious before counting:

- **69% rot is structural, not drift.** `booth link` is an `O_APPEND` write with
  no identity and no stated rule, so re-announcing a bench creates a row rather
  than updating one, and a booth URL rots the moment its booth is swept.
- **54% kept means the escape hatch is carrying the main load.** A 24h TTL with
  a boolean override is not "ephemeral with an exception"; it is two lifetimes
  wearing one lifetime's clothes, and the operator is doing the sorting by hand.

## The defect behind every tacked-on part

> **One lifetime (24h from last touch) and one shape (a folder), serving five
> jobs with different lifetimes and different shapes.**

Every bolt-on is a correct local fix to that one global mismatch:

| bolt-on | the mismatch it patches |
|---|---|
| `.forever` | "this one shouldn't expire" |
| the link board | "this one isn't a folder" |
| `inline.py` (a placeholder DSL) | "this one isn't a gallery" |
| `wrap_verbatim_html` (6 regexes into arbitrary HTML) | "the Booth doesn't own this page" |
| the floating amber asks chip + `/b/<n>/asks` | "the operator can't see the question" |

Five mechanisms exist to get **one question next to one artifact**. That is the
definition of accretion, and the git log shows its signature: every feature
ships, then takes 2–5 patches for cases the single shape did not anticipate.

## The five jobs

| # | job | example on the live service | what it needs |
|---|---|---|---|
| 1 | **Review a set** | `sindra20-engines` (197 files), `pancake-v3-full` (270) | grid, sections, zoom, filter, flag-the-winners |
| 2 | **Review a change** | `pancake-v3-full` **vs** `pancake-v4-full` | pairing by name, A/B |
| 3 | **Read a report** | `pewpew-ui-brief`, `run07-decisions` | prose + figures + nav, chrome the Booth owns |
| 4 | **Decide** | asks | the question beside the artifact |
| 5 | **Announce** | *145 dead link rows* | "operator, look at this" |

Job 5 is the one nobody named. The link board was absorbing it: an agent posts a
booth URL because **a booth has no way to announce itself** — the index card
shows a name, an item count and a countdown, but not who made it or what it is
for. Enforcing the link rule without giving job 5 a home just makes it homeless.

---

# The model

Four nouns. Everything else is a view over them.

## 1. Booth — a review surface with a derived lifetime

A folder, as before. What changes is that **lifetime is derived from state, not
set by a boolean**:

- Default: swept 24h after last activity. Unchanged, and still the contract that
  means nobody cleans up after themselves.
- **An open mark pins its booth.** A booth the operator still owes an answer to
  cannot be swept. (Today it can — a real defect, and one of the reasons
  `.forever` gets pressed.)
- **Viewing a booth page is activity.** If he is still looking at it, it is still
  alive. Deliberate act, so it cannot be triggered by browsing the index.
- `keep` survives as an explicit, reasoned pin — not as the only way to say
  "not yet".

> Expected effect: the 54% kept rate falls to the booths that are genuinely
> durable references. **This is a prediction, and it is measurable** — re-count
> the `.forever` rate a fortnight after this lands. If it does not move, the
> diagnosis was wrong and the boolean was doing something else.

Each booth carries `.booth.json`: `{handle, title, why, created}` — written by
the CLI from `$ALTHING_HANDLE`. **This is what closes job 5.** The index card
gains provenance and a one-line purpose, and the index becomes the "what landed"
feed the link board was being used as.

## 2. Item — one record, resolved once, carried everywhere

Today `build_gallery()` folds a `.txt` sidecar into an item — and
`booth_view_file()` passes only `{name, file, file_url}` to the zoom template.
**The caption is not lost in rendering; it is never sent.** Same for the doc view.

So: one `booth_items(booth)` resolver returns the full record —
`{rel, kind, caption, marks, flagged, blurred, section, url}` — and the gallery,
the zoom view, the doc view, the compare view and the zip manifest all read from
it. The zoom-loses-annotation bug is then fixed *by construction*, not by
patching one more template and hoping the next one remembers.

**Sections come from subfolders, which already exist on disk and are currently
thrown away.** `pewpew-ui-brief` has `integration/` and `blueprint/`;
`dfa-concepts` has `source/`. `rglob` flattens them into one wall. Rendering the
structure the poster already created costs nothing and is most of the navigation
fix.

## 3. Mark — operator judgment attached to a target

The unification, and the reason "comments, votes and asks" stop being three
tacked-on things:

> **An ask is the session asking the operator. An annotation is the operator
> telling the session. A vote is the operator pointing at the good ones.** All
> three are *operator judgment attached to an artifact*. One primitive.

```
MARK
  target : the booth, or one item in it
  shape  : pick  — one of N options the session declared in advance   (was: ask)
           note  — free text the operator volunteered                 (was: comment)
           flag  — this one / not this one                            (was: vote)
  writer : the operator, in the browser
  reader : the session — `booth marks <booth> [--wait]`
```

One storage model, one read path, one rendering slot (beside the artifact), one
place where "is anything still open?" is computed. `pick` keeps today's ask
semantics wholesale, including partial answers and the multi-question form — that
behaviour is operator-settled (2026-09-09) and is preserved, not redesigned.

`flag` is the one that makes a 270-image booth tractable, and it closes a loop
that is currently running through chat: `golden-candidates`, `sindra-finalists`
and the `pancake-*` ladders are all the operator picking winners from a set and
then *telling the session in conversation*. Flags make that readable by the
session that posted the set.

## 4. Bench — a running thing, registered

**Not a booth.** The operator's rule, stated by him and now enforced in code:

> Links are for durable middle-to-long-term testing surfaces — jackdaw's current
> bench, talk's current bench — the things that get promoted to Homepage when
> fully deployed.

```
BENCH
  id     : normalized URL (the identity — re-posting UPDATES, never appends)
           NORMALIZED MEANS THE FULL URL, NOT THE ORIGIN — see below
  name   : what it is
  owner  : the agent handle that registered it
  state  : live → promoted (to Homepage) → retired
  health : last_checked, last_ok   (probed; flagged when dead, never auto-deleted)
```

- Stored at `~/booth-data/.benches.json` — a dotfile, outside the booth
  namespace, so it can neither be swept nor mistaken for a booth.
- `booth bench add <url> "<what>"` upserts on the normalized URL. The 5 `talk`
  rows and 4 `peedlar` rows collapse to one each, by construction.
- **`booth link` refuses a `…:8090/b/…` URL** and names the right surface. It
  is **not deprecated** — 17 handles have the muscle memory, the teaching moment
  belongs at the point of use, and (corrected 2026-09-22, U6) the board has a
  legitimate residual job: of the 35 distinct non-booth targets on it, roughly
  **14 are reference bookmarks** — gitea repositories, HuggingFace model cards,
  a vLLM recipe, a Headscale setup page — for which the board is the right and
  only home. Deprecating it would evict a third of its live content. It loses
  exactly one shape, the booth URL, and keeps the rest.

### What "normalized URL" means, and why it is not the origin

Corrected 2026-09-22 while U6 was being contracted. This doc said *normalized
URL* and left it there; the obvious reading is the origin
(`scheme://host:port`), and that reading is **measurably destructive**.

Collapsing the board's 43 non-booth rows by origin yields 19 groups; by full
URL, 35. The 16-group difference is not duplication:

| what origin identity would merge | rows |
|---|---|
| eight distinct gitea repositories, issues and package versions | 8 → 1 |
| three unrelated HuggingFace model cards | 3 → 1 |
| **the two LRPG surfaces on `10.100.10.50:8321`** — this doc's own example of two real benches | 2 → 1 |
| two different claude.ai artifact briefs | 2 → 1 |

Full-URL identity still collapses both cases this doc names — `talk` 5 rows to
1, Peedlar's root 3 to 1 — which is the entire win, without the losses.

The **query string is part of the identity** and the **fragment is not**: three
ShutterChute rows differ only by `?token=` and are three genuinely different
one-shot links, while a fragment is a position inside a page. Credentials in a
URL are **refused rather than stripped** — stripping registers a bench whose URL
no longer works while telling the poster it succeeded.

### One number that was two defects

This doc's headline **69% rot** is two different defects wearing one number, and
U5 already closed the cause of the larger one:

| defect | rows (2026-09-22) | what fixes it |
|---|---|---|
| **booth-announcement rot** — a session posts a booth URL because a booth cannot announce itself | 178 rows, 156 already dead | **U5** gave job 5 a home; U6's refusal stops the habit; U6's dead marker clears what landed |
| **bench re-post** — an append log with no identity | 8 rows | U6's registry |

Worth stating plainly because the single figure implies the registry is the big
half. It is the smaller one.
- Liveness is *flagged*, not enforced. A bench that stops answering gets a
  marker and a date; deleting is the operator's call. Nothing here deletes the
  operator's data on a timer.

### Migrating the 211 existing rows

1. `links.md` is archived verbatim to `~/booth-data/links/links-archive-<date>.md`
   **and** committed to this repo. Nothing the operator wrote is destroyed.
2. The ~40 durable rows seed the registry, deduplicated.
3. The 145 dead rows and 26 live booth-links are not carried over — the first
   point at nothing, the second are booths, which the index now announces itself.

---

# The frame: who owns the page

Operator ruling, 2026-09-21: **the page declares itself, the Booth mounts into
it.**

A report includes one line:

```html
<script src="/_booth/embed.js" defer></script>
```

…and the Booth's chrome — nav, marks, annotations, the way home — mounts through
a real DOM API. Marks land at `data-booth-mark="<id>"` anchors, which keeps the
2026-09-09 ruling that *asks render inline beside the artifact, not on a separate
page*. If the line is absent, the Booth injects it at **one** insertion point, so
every existing verbatim booth keeps working untouched.

**What this deleted** — landed as U3, 2026-09-22:

- `booth/inline.py` — 119 lines of placeholder DSL, entirely. One line survived:
  `form_id`, which builds the shared `<form>` id scattered question groups bind
  to, and which moved to `app.py` beside the route that renders them.
- `wrap_verbatim_html` and its six regexes against arbitrary HTML
  (`_HEAD_CLOSE_RE`, `_HTML_OPEN_RE`, `_DOCTYPE_RE`, `_BODY_CLOSE_RE`,
  `_HTML_CLOSE_RE`, `_ICON_RE`) **and both of the constraints they were
  threading.** Not satisfied more carefully — gone: nothing can displace a
  leading doctype into quirks mode and nothing can push the charset `<meta>`
  out of its detection window, because the Booth only ever APPENDS now.
- `_BACK_CHIP`, `asks_chip` — two floating chips positioned by guessed offsets.
  embed.js builds both in the DOM.
- the `styles()` macro. The scoped `.bk-ask-*` rules live in embed.js next to
  the code that mounts them, emitted once by construction instead of by a
  seen-set.
- `GET /b/<name>/asks` was already a 308 into `/marks` by U2; this unit left it
  there. The standalone page it named is gone, but the URL is in the operator's
  history and in landed reports, and a dead link teaches nothing.

**What replaced them is a substring test and a `+`.** `if EMBED_SRC not in
html: html += EMBED_SCRIPT_TAG`. A page that declares the line is served with
nothing added to it at all.

Regex-injecting into arbitrary author HTML was the single most fragile thing in
the service, and it was load-bearing for the operator's most important workflow.
A declared seam costs the author one line and removes the whole class.

**What it cost, stated because it is real.** The verbatim path used to work with
no JavaScript: an ask rendered server-side and submitted through a plain form.
It now needs the script. The guarantee that an ask is never invisible survives
in a weaker and still-true form through surfaces that need no script — the index
card's open-mark badge, and `/b/<name>/marks`, which renders every mark
server-side.

---

# Navigation

Sized for the real case — 270 items — not the demo case.

- **Sections** from subfolders (free; the data is already there).
- **A sticky rail**: total, per-section counts, and filters — all / flagged /
  annotated / unanswered. Jump-to-section.
- **Keyboard in the grid, not only in the viewer.** Today prev/next exists only
  *inside* the zoom view: `←/→` move, `f` flags, `n` opens a note, `Enter`
  zooms, `Esc` backs out. A 270-item review is a keyboard task.
- **Zoom keeps the item's annotations** — the same item record, so the caption,
  notes and flag state are all present at full size.
- **Compare**, detected rather than configured: when two subfolders share
  filenames, offer pair-by-name A/B. This is the `pancake-v3-full` /
  `pancake-v4-full` dance — currently four separate booths diffed by eye across
  two browser tabs — collapsed into one booth with two subfolders.

---

# Non-goals, kept from the original and still right

- **No auth.** LAN/mesh-internal, and blur stays explicitly cosmetic. Anything
  that must not be seen by whoever can reach `:8090` must not be in a booth.
- **No database.** The filesystem stays the state; `ls ~/booth-data` still tells
  you everything. Marks, benches and booth metadata are all flat files.
- **No upload API for booths.** A session makes a folder. That is the whole API,
  and it is why every agent family can use this without a client.