From 1f33d192bfba77043510896b489b2a5b4a33079b Mon Sep 17 00:00:00 2001
From: Niels Mokkenstorm <niels@mokkenstorm.dev>
Date: Fri, 10 Jul 2026 00:45:57 +0200
Subject: [PATCH] docs: product roadmap + spec accuracy pass; catalog-entities,
 catalog-browse, and bff-architecture specs

---
 README.md                 | 135 +++++++++---------------
 ROADMAP.md                | 212 ++++++++++++++++++++++++++++++++------
 docs/bff-architecture.md  | 170 ++++++++++++++++++++++++++++++
 docs/catalog-authority.md |  45 +++++---
 docs/catalog-browse.md    | 147 ++++++++++++++++++++++++++
 docs/catalog-entities.md  |  79 ++++++++++++++
 docs/discogs-import.md    | 137 +++++++++---------------
 docs/discogs-sync.md      |  18 ++--
 docs/shelf-events.md      |  54 ++++------
 9 files changed, 744 insertions(+), 253 deletions(-)
 create mode 100644 docs/bff-architecture.md
 create mode 100644 docs/catalog-browse.md
 create mode 100644 docs/catalog-entities.md

diff --git a/README.md b/README.md
index 402c8a6..709d9ed 100644
--- a/README.md
+++ b/README.md
@@ -1,91 +1,66 @@
 # at-record
 
 A Discogs-like, atproto-native record collection app, written in Gleam. Your
-crate (the vinyl kind) is stored as records (the atproto kind) in your own PDS.
-
-This is the Gleam reincarnation of the `crate` design: same lexicons
+crate (the vinyl kind) is stored as records (the atproto kind) in your own
+PDS. Gleam reincarnation of the `crate` design: same lexicons
 (`dev.mokkenstorm.crate.*`), same PDS-as-storage idea, different stack.
 
 ## What it does today
 
-- **Log in with atproto OAuth** (PAR + PKCE + DPoP, granular scopes). Tokens
-  and DPoP keys live server-side in an encrypted-at-rest store; the browser
-  only ever holds an opaque signed cookie.
-- **Your crate is an append-only event log.** Every mutation is an immutable
-  `shelf.entry` event; the first event for a copy (the genesis) has no
-  `subject`, its record TID is the entry's identity, and later events
-  reference it via a `com.atproto.repo.strongRef`. The current crate,
-  wishlist, and history are folds over the log ([spec](./docs/shelf-events.md)).
-- **Discogs seed search** on the add form, and **Discogs account connection +
-  collection import** (OAuth 1.0a): capped, resumable runs that dedup by
-  release id and upsert cover art onto existing entries
+- atproto OAuth login (PAR + PKCE + DPoP); tokens live server-side, encrypted
+  at rest.
+- Your crate is an append-only event log, folded into current crate,
+  wishlist, and history ([spec](./docs/shelf-events.md)).
+- Discogs seed search, account connection, and collection import
   ([spec](./docs/discogs-import.md)).
-- **Cover art is stored as blobs in your repo** (content-addressed, served via
-  `getBlob`), not hotlinked, so entries stay self-contained.
+- Barcode scan-to-import (Chromium's `BarcodeDetector` only, for now).
+- Cover art stored as blobs in your repo, not hotlinked.
+- `via @handle` attribution chip on entries adopted from someone else's
+  catalog release.
 
 ## Layout
 
-A Gleam multi-target monorepo. `server` and `web` depend on `shared` by path;
-the generic atproto plumbing comes from Hex.
-
-| Package  | Target     | What it is                                                                         |
-| -------- | ---------- | ---------------------------------------------------------------------------------- |
-| `shared` | erlang+js  | Generated lexicon codecs (`gen/`) + a hand-written `StoredItem` envelope.          |
-| `server` | erlang     | Wisp BFF: routes, OAuth, sessions, Discogs client. Uses `atproto/*` for PDS calls. |
-| `web`    | javascript | Lustre SPA (modem-routed pages), talks only to the BFF.                            |
-
-Lexicons live under `lexicons/` (our `dev.mokkenstorm.crate.*` plus vendored
-`com.atproto.*` refs like `strongRef`).
-
-## The gleam-atproto packages
-
-The atproto client and the lexicon codegen were built here and extracted to
-[gleam-atproto](https://tangled.org/@mokkenstorm.dev/gleam-atproto), publishing
-independently to Hex:
-
-- [`atproto_client`](https://hex.pm/packages/atproto_client): transport-agnostic
-  client (XRPC, identity via Slingshot, OAuth machinery, blobs, repo CRUD).
-  Dual-target; modules under the `atproto/` namespace.
-- [`atproto_codegen`](https://hex.pm/packages/atproto_codegen): lexicon-to-Gleam
-  types + JSON codecs.
+Gleam multi-target monorepo. `server`/`web` depend on `shared` by path; the
+generic atproto plumbing comes from Hex
+([gleam-atproto](https://tangled.org/@mokkenstorm.dev/gleam-atproto):
+[`atproto_client`](https://hex.pm/packages/atproto_client) +
+[`atproto_codegen`](https://hex.pm/packages/atproto_codegen)).
 
-## Lexicon codegen
+| Package  | Target     | What it is                                                                              |
+| -------- | ---------- | --------------------------------------------------------------------------------------- |
+| `shared` | erlang+js  | Generated lexicon codecs (`gen/`) + `StoredItem`.                                       |
+| `server` | erlang     | Wisp BFF: routes, OAuth, sessions, Discogs client.                                      |
+| `web`    | javascript | Lustre SPA, talks to the BFF (+ the public Bluesky AppView directly for handle search). |
 
-`shared/src/at_record/gen/` is **generated** and **gitignored**. `make gen`
-runs `atproto_codegen` (a dev dependency of `shared`) over `lexicons/`,
-emitting one module per lexicon: type + encoder + decoder, plus a `_fields`
-helper per def. Supported: record/object defs, scalars, arrays, refs
-(cross-lexicon), `cid-link`, `bytes`, `blob`, `unknown`, and **open unions**
-(a variant per ref plus an `Other(Dynamic)` that round-trips unknown
-`$type`s). Because the output is gitignored, **run `make gen` (or anything
-that depends on it, like `make test`) before building a fresh checkout.**
+Lexicons live under `lexicons/`. `shared/src/at_record/gen/` is
+**generated and gitignored**: `make gen` runs `atproto_codegen` over
+`lexicons/`. Run `make gen` (or `make test`, which depends on it) before
+building a fresh checkout.
 
 ## Run it locally
 
-Needs `gleam`, `erlang`, `node`, `docker` (for Postgres), and `make`
-(`make help` lists every target).
+Needs `gleam`, `erlang`, `node`, `docker`, `make`.
 
 ```sh
 make dev        # watch loop: Postgres in docker, rebuilds server/web on change
 ```
 
-Browse **http://127.0.0.1:8080** (not `localhost`: cookies are host-specific
-and every OAuth callback lands on the loopback IP; the server bounces
-`localhost` over for you). Sign in with your handle and authorize on your PDS.
+Browse **http://127.0.0.1:8080**, not `localhost` (cookies are host-specific
+and OAuth callbacks land on the loopback IP).
 
-Configuration comes from the environment; `scripts/dev.sh` and docker-compose
-provide dev defaults and read `.env` (gitignored) for secrets:
+Config comes from the environment (`scripts/dev.sh` / docker-compose provide
+dev defaults, read `.env` for secrets):
 
-| Variable                                           | Required | Purpose                                                                 |
-| -------------------------------------------------- | -------- | ----------------------------------------------------------------------- |
-| `SECRET_KEY_BASE`                                  | yes      | cookie signing secret                                                   |
-| `STORE_KEY`                                        | yes      | at-rest encryption key for sessions + Discogs tokens (base64, 32 bytes) |
-| `DATABASE_URL`                                     | no       | Postgres for persistent stores (in-memory fallback)                     |
-| `DISCOGS_CONSUMER_KEY` / `DISCOGS_CONSUMER_SECRET` | no       | Discogs app credential: search covers + account connect/import          |
-| `BASE_URL`, `OAUTH_CLIENT_JWK`                     | deploys  | https origin switches OAuth to the confidential client                  |
-| `PORT`, `SLINGSHOT_URL`                            | no       | port (8080) and identity resolver overrides                             |
+| Variable                                           | Required | Purpose                                   |
+| -------------------------------------------------- | -------- | ----------------------------------------- |
+| `SECRET_KEY_BASE`                                  | yes      | cookie signing secret                     |
+| `STORE_KEY`                                        | yes      | at-rest encryption key (base64, 32 bytes) |
+| `DATABASE_URL`                                     | no       | Postgres (in-memory fallback)             |
+| `DISCOGS_CONSUMER_KEY` / `DISCOGS_CONSUMER_SECRET` | no       | Discogs search + import                   |
+| `BASE_URL`, `OAUTH_CLIENT_JWK`                     | deploys  | switches OAuth to the confidential client |
+| `PORT`, `SLINGSHOT_URL`                            | no       | port/identity-resolver overrides          |
 
-Confirm independently that your data is really on your PDS:
+Confirm your data lives on your PDS:
 
 ```sh
 curl "https://<your-pds>/xrpc/com.atproto.repo.listRecords?repo=<your-did>&collection=dev.mokkenstorm.crate.shelf.entry"
@@ -99,29 +74,21 @@ make up                    # server + Postgres on http://localhost:8080
 make down
 ```
 
-A multi-stage build runs codegen + the Lustre bundle, then ships an Erlang
-release on `erlang:29-slim`. Crate data lives on your PDS; Postgres only holds
-the encrypted session and Discogs-token stores.
-
 ## Tests
 
 ```sh
 make test                  # codegen, then shared + server + web suites
 ```
 
-## Roadmap (from the `crate` design)
-
-Discogs account connection + collection import
-([spec](./docs/discogs-import.md)) -> scan-to-import flow (barcode shipped,
-photo mode design-ahead; see
-[ROADMAP.md](./ROADMAP.md#scan-to-import-flow-barcode-shipped-2026-07-zxing-fallback-outstanding))
--> catalog authority + lazy promotion
-([spec](./docs/catalog-authority.md)) -> two-way Discogs sync
-([spec](./docs/discogs-sync.md)) -> Jetstream indexer + cross-user
-search/appview -> social feed -> hybrid catalog edits. Mobile, when wanted, is
-the same Lustre app wrapped in Capacitor (see
-[ROADMAP.md](./ROADMAP.md#native-wrap-capacitor-over-tauri-deferred-until-scan-justifies-it));
-the camera-driven scan flow is the natural trigger.
-
-Engineering and architecture decisions (with rationale and triggers to revisit)
-live in [ROADMAP.md](./ROADMAP.md).
+Real OAuth and cross-account flows are covered by a separate
+[e2e suite](./e2e/README.md) against a pinned local atproto devnet:
+
+```sh
+make e2e-setup              # once
+make e2e
+```
+
+## Roadmap
+
+Product direction and engineering decisions live in
+[ROADMAP.md](./ROADMAP.md).
diff --git a/ROADMAP.md b/ROADMAP.md
index c1b4b5c..550723e 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -1,23 +1,151 @@
 # Roadmap & decisions
 
-Engineering and architecture decisions for at-record, with the reasoning and the
-**trigger to revisit** each. Product/feature direction lives in the
-[README "Roadmap"](./README.md#roadmap-from-the-crate-design) section.
+The product roadmap, then engineering and architecture decisions with the
+reasoning and the **trigger to revisit** each.
+
+## Product roadmap
+
+Shipped baseline: atproto OAuth login (with handle autocomplete), the
+append-only event-log crate, Discogs search/connect/import, barcode
+scan-to-import, adopt-or-mint catalog promotion with `via @handle`
+attribution, and the amend flow (own records superseded, foreign ones get
+`basedOn` + a `catalog.edit` proposal).
+
+Three axes from here. Cross-axis order: design catch-up and the UX-hole
+audit first, then data-model completeness, then catalog depth.
+
+### Clean design
+
+The direction is chosen and prototyped in Figma ("Zine × Greenhouse":
+parchment, bark ink, hard offset shadows; a design-system page with color,
+spacing, and stroke tokens plus components). The app's CSS mirrors the
+tokens but not yet the full system.
+
+- **Figma catch-up (Figma-side sync done 2026-07):** the prototype page now
+  matches shipped reality: a Login screen (handle autocomplete open, with
+  suggestion rows), a "Crate — account menu" popout state, the
+  `via @handle` chip on Record detail, a "Scan — scanned rows" states card
+  (looking up / matched / no match / adding / added), a "Buttons — busy
+  states" strip (SAVING…/PUBLISHING…), and the fake phone status bar
+  removed from all nine screens (the `Structure/Status bar` component on
+  the design-system page is now unused; retire it there too). The other
+  direction still stands: the app is missing states the prototype designed
+  ("did you mean" suggestions, manual-search fallback, drafts), which are
+  the UX-holes list below.
+- **UX flow holes** (filed 2026-07, tracked here):
+  - [x] Saving a record gives no feedback (done 2026-07: success notice
+        naming the saved title).
+  - [x] `dropped` (REMOVE) fires from a single tap (done 2026-07: two-tap
+        confirm, button arms to "CONFIRM REMOVE", disarms on navigation).
+  - [x] Scan no-match dead end, cheap fix (done 2026-07: SEARCH ghost
+        button linking to Add). Full fix stays open (needs the designed
+        "did you mean" flow + fuzzy matching, per the Figma no-match
+        screen).
+  - [ ] Login/OAuth failures surface only as a generic banner. Needs a
+        design pass first (see State design below).
+- **State design:** empty crate, loading, and error states are unstyled
+  afterthoughts today (loading labels only just landed). Design them as
+  first-class screens.
+- **Login screen:** skipped during the prototype round; it has since grown
+  handle autocomplete and deserves a real design pass.
+- **Component parity:** finish turning the prototype's ad-hoc frames into
+  real Figma components and rebuild the screens from them, so design changes
+  propagate instead of drifting.
+- **List view** as an alternative to the cover grid (long crates).
+- **Dark mode:** a second variable mode in the Figma collection, then a CSS
+  custom-property theme flip; the token indirection is already in place on
+  both sides.
+
+### Complete data model
+
+The lexicons are ahead of the app: several fields exist on `shelf.entry` and
+`catalog.release` that nothing writes or shows. Concretely, as of today:
+`sleeveGrade` is absent even from the web `Entry` type; `notes` and `folder`
+render when present but nothing can set them (the server's `annotated` and
+`moved` reducer actions have no UI that dispatches them); `price`,
+`counterparty`, and `acquiredAt` are wired end to end through lexicon and
+fold but appear nowhere.
+
+- **Widen the add/edit surface to the lexicon** (tracked in "API surface
+  gaps" below): `sleeveGrade`, `folder`, `rating`, `acquiredAt`, and `notes`
+  are not settable at genesis; only media grade and rating are editable
+  after. This pairs with the Figma catch-up: each field needs a home in a
+  designed screen, not just a form input bolted on.
+- **Money and provenance UI:** `price` and `counterparty` exist on
+  `shelf.entry` for acquired/sold events; no UI captures them. The event log
+  was designed for exactly this history ("bought 2019 for X, sold 2022 for
+  Y").
+- **Wantlist import:** `wanted` entries are modeled and viewable, but the
+  Discogs wantlist endpoint is not imported (cheap: same import machinery,
+  `action: "wanted"`).
+- **`artistDisplay` on `catalog.release`:** a plain display-string field
+  (additive), so releases render "Title, Artist" without artist entities
+  existing (see [catalog-browse](./docs/catalog-browse.md)).
+- **MusicBrainz ids as the cross-app bridge (before any shared lexicon):**
+  the atproto music ecosystem already converges on MBIDs as the neutral
+  key. teal.fm's `fm.teal.alpha.feed.play` carries `artistMbIds`,
+  `releaseMbId`, and `recordingMbId` (verified 2026-07; it has no
+  standalone artist records and no genre property), and our repeatable
+  `defs#externalId` was designed for exactly this (`provider:
+"musicbrainz"`). Capturing MBIDs on releases (MusicBrainz supports
+  barcode lookup, and maps Discogs URLs to releases) makes at-record
+  entries and teal.fm plays correlatable today via shared natural keys and
+  Constellation URL backlinks, with zero lexicon coordination.
+- **Artist + genre entities: PoC built and Discogs-fed 2026-07** (see
+  [catalog-entities](./docs/catalog-entities.md)): `catalog.artist` and
+  `catalog.genre` lexicons exist, and every mint path now fills them from
+  the (single, existing) per-release Discogs fetch: artists minted with
+  own-repo dedup and wired into `creditedArtists`; genres minted as
+  vocabulary from genre/style strings. Still open: cross-user artist
+  adoption via Constellation, MBIDs on artists, any read path, and
+  graduation past PoC (which means coordinating with teal.fm and similar
+  first; "required is forever" cuts both ways). Master and label entities
+  remain unbuilt (reserved in `catalog.edit`).
+
+### More complete catalog
+
+- **Enrich minted releases (mostly done 2026-07).** Minted releases now
+  carry `artistDisplay`, `country`, `released`, `genres`, `styles`,
+  barcode `identifiers`, and `creditedArtists`, all from the single
+  per-release Discogs fetch that was already made for cover art. Still
+  stubs: `tracklist`, `labels`, `master`.
+- **Barcodes as identifiers (capture done 2026-07):** scanned/imported
+  barcodes land in `catalog.release.identifiers`. The payoff half is
+  open: making the scan flow match the network catalog first and Discogs
+  second, which compounds as the catalog grows.
+- **Browsable catalog** ([spec sketch](./docs/catalog-browse.md)): v1 over
+  at-record's own known users, v2 a Jetstream-filtered indexer; want-it /
+  have-it straight from the browse grid.
+- **Adoption counts** via Constellation backlinks: "N people have this",
+  browse sorting, and the answer to the open canonical-selection decision.
+- **`catalog.edit` inbox:** amending a foreign record files a proposal
+  today, but the original author has no way to see or apply one. A
+  provider-side review/apply flow closes the loop (apply = mint +
+  `supersedes`).
+- **Dedup in browse:** group near-duplicate releases by shared
+  `externalIds` before real canonical convergence exists.
+
+Longer arc, unchanged: two-way Discogs sync
+([spec](./docs/discogs-sync.md)) -> cross-user discovery and social feed ->
+native wrap when scan justifies it (sections below). The
+[BFF-thinning work](./docs/bff-architecture.md) runs alongside as an
+architecture track, not a product one.
 
 ## Decisions made
 
-| Decision                                                                                                              | Why                                                                                                                                                        |
-| --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Extract a generic `atproto` package** (XRPC, identity, auth, repo CRUD)                                             | The generic plumbing is ~80% of a Gleam atproto SDK and none existed; isolating it keeps the app thin and the lib publishable.                             |
-| **Transport-agnostic client** (`xrpc.Client` wraps a `send` fn; server injects `httpc`)                               | No HTTP dependency in the core, so it compiles on both targets and a JS caller could supply `fetch`.                                                       |
-| **Generic `repo` CRUD** (collection NSID + row decoder, no lexicon knowledge)                                         | Keeps `atproto` free of `crate` types; the shelf-specific decoder lives in the server.                                                                     |
-| **Slingshot for identity resolution** (`com.bad-example.identity.resolveMiniDoc`)                                     | One call returns did+handle+pds, replacing the appview + `plc.directory` two-hop.                                                                          |
-| **MVU module split of the web app**                                                                                   | A 426-line single file became `model`/`msg`/`update`/`effects`/`view` + thin `main`.                                                                       |
-| **Docker** (multi-stage, `gleam export erlang-shipment`, `erlang:29-slim`, binds `0.0.0.0`) + **Makefile**            | Single-service deploy (storage is the PDS, no DB). `0.0.0.0` bind is required or the container is unreachable.                                             |
-| **codegen scalar sweep** (`cid-link`->`String`, `bytes`->`BitArray`, `unknown`->`Dynamic` via `internal` helpers)     | Removed the last skip (`catalog.edit`). `unknown` round-trips through a `dynamic_to_json` passthrough.                                                     |
-| **External IDs as a repeatable `externalId` ref** (`provider`+`id`+`url`), replacing scalar `discogsReleaseId`/`mbid` | Many providers per item (Discogs, MusicBrainz, ...) without a `V2` to add one; relaxes `catalog.release.required` to `[title, createdAt]`.                 |
-| **Finalised `required[]` + string limits** while pre-adoption (single-user)                                           | "Required is forever"; every free-text string now carries `maxGraphemes`/`maxLength` (~10:1). The window to do this closes once others adopt the lexicons. |
-| **Entry identity = genesis TID + `subject` strongRef** (replaced the client-minted `entryId`; BC break pre-adoption)  | Stable linkable at-uris per entry (Constellation backlinks for free), no minted id to thread through, appends validate their genesis via `getRecord`.      |
+| Decision                                                                                                              | Why                                                                                                                                                                                                                                                   |
+| --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Extract a generic `atproto` package** (XRPC, identity, auth, repo CRUD)                                             | The generic plumbing is ~80% of a Gleam atproto SDK and none existed; isolating it keeps the app thin and the lib publishable.                                                                                                                        |
+| **Transport-agnostic client** (`xrpc.Client` wraps a `send` fn; server injects `httpc`)                               | No HTTP dependency in the core, so it compiles on both targets and a JS caller could supply `fetch`.                                                                                                                                                  |
+| **Generic `repo` CRUD** (collection NSID + row decoder, no lexicon knowledge)                                         | Keeps `atproto` free of `crate` types; the shelf-specific decoder lives in the server.                                                                                                                                                                |
+| **Slingshot for identity resolution** (`com.bad-example.identity.resolveMiniDoc`)                                     | One call returns did+handle+pds, replacing the appview + `plc.directory` two-hop.                                                                                                                                                                     |
+| **MVU module split of the web app**                                                                                   | A 426-line single file became `model`/`msg`/`update`/`effects`/`view` + thin `main`.                                                                                                                                                                  |
+| **Docker** (multi-stage, `gleam export erlang-shipment`, `erlang:29-slim`, binds `0.0.0.0`) + **Makefile**            | Single-service deploy (storage is the PDS, no DB). `0.0.0.0` bind is required or the container is unreachable.                                                                                                                                        |
+| **codegen scalar sweep** (`cid-link`->`String`, `bytes`->`BitArray`, `unknown`->`Dynamic` via `internal` helpers)     | Removed the last skip (`catalog.edit`). `unknown` round-trips through a `dynamic_to_json` passthrough.                                                                                                                                                |
+| **External IDs as a repeatable `externalId` ref** (`provider`+`id`+`url`), replacing scalar `discogsReleaseId`/`mbid` | Many providers per item (Discogs, MusicBrainz, ...) without a `V2` to add one; relaxes `catalog.release.required` to `[title, createdAt]`.                                                                                                            |
+| **Finalised `required[]` + string limits** while pre-adoption (single-user)                                           | "Required is forever"; every free-text string now carries `maxGraphemes`/`maxLength` (~10:1). The window to do this closes once others adopt the lexicons.                                                                                            |
+| **Entry identity = genesis TID + `subject` strongRef** (replaced the client-minted `entryId`; BC break pre-adoption)  | Stable linkable at-uris per entry (Constellation backlinks for free), no minted id to thread through, appends validate their genesis via `getRecord`.                                                                                                 |
+| **Failure posture: best-effort for reads, accounted for writes** (decided 2026-07)                                    | Display reads (handle chip, avatar) may silently degrade. Writes that create immutable records must surface failures (counts in run results, user notices) or fail the item; 429s always propagate to run-level rate-limit handling, never swallowed. |
 
 ## Deferred / planned
 
@@ -85,17 +213,16 @@ in `server/src/at_record_server/oauth/`; discovery lives in the dual-target
 - **DPoP-authed PDS requests + token refresh** (a client wrapper, so the generic
   `repo` CRUD is reused unchanged).
 
-**Granular scopes (least privilege):** `atproto repo:dev.mokkenstorm.crate.shelf.item`
+**Granular scopes (least privilege):** `atproto repo:dev.mokkenstorm.crate.shelf.entry`,
+`repo:dev.mokkenstorm.crate.catalog.release`, `repo:dev.mokkenstorm.crate.catalog.edit`
 (defined as the `client_metadata.scopes` list). `repo:` is write-only; repo reads
 are public. This replaced the discouraged `transition:generic`.
 
-Scope follow-ups:
+Scope follow-up:
 
-- **When catalog writes land**, add `repo:dev.mokkenstorm.crate.catalog.release`
-  and `repo:dev.mokkenstorm.crate.catalog.edit` to `scopes`.
 - **Permission-set lexicon** (`include:dev.mokkenstorm.crate.<set>`) is the next
   step up: it bundles permissions under one branded entry in the consent UI.
-  Overkill for a single collection; worth it once the scope list grows.
+  Overkill for three collections; worth it once the scope list grows further.
 
 Session store is a swappable `sessions.Store` interface with **Postgres**
 (`sessions_postgres`, used when `DATABASE_URL` is set) and **in-memory**
@@ -109,6 +236,12 @@ Remaining:
 
 - Confidential deploys need a stable `OAUTH_CLIENT_JWK` and `BASE_URL`
   (`SECRET_KEY_BASE` and `STORE_KEY` are now required everywhere).
+- **Whether to stay confidential at all is now an open question** — see
+  [bff-architecture.md](./docs/bff-architecture.md) (sketch): most of the
+  server's logic doesn't need a server secret, and a public-client, browser-custodied
+  session is the more atproto-native shape. Blocked today on DPoP crypto having
+  no WebCrypto (browser) backing anywhere in the dependency chain, only
+  Node's `crypto`.
 
 ### API surface gaps
 
@@ -133,7 +266,7 @@ changelogs by hand. The atproto OAuth client machinery (PKCE, PAR, DPoP,
 tokens) was ported into `atproto_client`; migrating the server's `oauth/`
 modules onto it is the natural follow-up.
 
-### Scan-to-import flow (barcode shipped 2026-07; ZXing fallback outstanding)
+### Scan-to-import flow (barcode shipped 2026-07; universal scanner planned)
 
 The full flow is prototyped in
 [Figma](https://www.figma.com/design/xoAzpB0FCgpv4zzIZqA4TX/AT-Record?node-id=33-2):
@@ -149,13 +282,28 @@ review / duplicate rows, unresolved items saved as drafts) -> import done.
   only — the API is Chromium-only, never implemented by Firefox (desktop or
   Android) or Safari. Unsupported browsers get a graceful message pointing
   at manual add instead of a silent broken camera.
-- **ZXing (or similar) fallback (open).** Decode frames pulled off the
-  `<video>` element in JS/WASM instead of relying on the browser's native
-  detector, so Firefox and Safari work too. `startScanner`/`stopScanner` in
-  `web/src/at_record_web/ffi.mjs` already abstract the camera lifecycle from
-  the Gleam side (`effects.gleam`/`update.gleam` scan handlers don't know
-  which detection backend is running) — the native-detector check just needs
-  a fallback branch instead of going straight to `onUnsupported`.
+- **Universal scanner (planned, after the design/data-model work).** The
+  Gleam side needs zero changes: `start_scanner`/`stop_scanner` already hide
+  the backend from `effects.gleam`/`update.gleam`, so the whole change lives
+  inside `ffi.mjs`'s `startScanner`. Plan:
+  - **Ponyfill, not a hand-rolled interface:** the `barcode-detector` npm
+    package (built on `zxing-wasm`) implements the exact W3C
+    `BarcodeDetector` API. Resolution becomes one step: use
+    `window.BarcodeDetector` when present, else dynamically `import()` the
+    ponyfill. The polling loop, cooldown, and camera lifecycle stay
+    byte-identical since both accept an `HTMLVideoElement` in `detect()`,
+    and `ean_13`/`upc_a` are in ZXing's supported set.
+  - **Asset plumbing is the only real work:** there is no npm bundler
+    (`ffi.mjs` is plain ESM), so vendor the ponyfill's JS + `.wasm` into
+    `web/priv/static/vendor/` and load by URL at runtime. Lazy loading
+    means Chromium/Android users never download the WASM; only
+    Firefox/Safari pay the one-time few-hundred-KB fetch.
+  - **iOS Safari works:** `getUserMedia` is fine there (the `playsinline`
+    attribute it needs is already on the video element).
+  - **Future-proof:** the Capacitor ML Kit plugin (native-wrap section
+    below) becomes a third branch in the same resolver
+    (`isNativePlatform()` -> plugin, else native API, else WASM ponyfill),
+    still without touching any `.gleam` file.
 - **Photo mode is design-ahead.** Discogs has no image-match API; matching a
   sleeve photo needs a separate image-recognition service. Ship barcode-only
   and keep the mode toggle disabled until there is a backend for it.
@@ -172,7 +320,7 @@ review / duplicate rows, unresolved items saved as drafts) -> import done.
   (e.g. `@capacitor-mlkit/barcode-scanning`) bridges to **ML Kit** (Android)
   and **Vision** (iOS) — compiled native decoders, not a webview API. This
   sidesteps the Firefox/Safari `BarcodeDetector` gap entirely: ML Kit/Vision
-  exist on-device regardless of the webview's rendering engine, so the ZXing
+  exist on-device regardless of the webview's rendering engine, so the WASM
   fallback above stops mattering for native-app users specifically (it's
   still worth building for browser-only users in the meantime).
 - **The abstraction is already in place.** `startScanner`/`stopScanner` in
@@ -199,6 +347,12 @@ review / duplicate rows, unresolved items saved as drafts) -> import done.
 - **Caveat:** community infra run by a single operator. Both are open-source Rust
   and self-hostable (Constellation runs on a Raspberry Pi), so the escape hatch
   is running our own later.
+- **First crack in that reasoning:** a browsable catalog (see
+  [catalog-browse.md](./docs/catalog-browse.md), sketch only) needs to
+  enumerate `catalog.release` records across repos, which is a shape
+  Constellation's backlink index can't answer. Sketched v1 avoids a
+  Jetstream indexer by scoping to at-record's own known users instead;
+  a self-hosted Jetstream-filtered indexer is the v2 if that stops scaling.
 
 ### e2e devnet: publish pinned images instead of building from source (planned)
 
diff --git a/docs/bff-architecture.md b/docs/bff-architecture.md
new file mode 100644
index 0000000..03af2c4
--- /dev/null
+++ b/docs/bff-architecture.md
@@ -0,0 +1,170 @@
+# Sketch: how thin can the BFF get?
+
+Status: **sketch, not designed in detail** (a "what would it take" pass, same
+spirit as [catalog-browse.md](./catalog-browse.md)). Prompted by a fair
+question: in an atproto app, ideally the browser talks to the user's own PDS
+directly and there's no backend at all, unless something genuinely needs one
+(a secret, or cross-user indexing).
+
+## Goal
+
+Figure out how much of `server/` is load-bearing versus incidental — built
+server-side because that's where the original OAuth work landed, not because
+it has to be there — and what it would take to move the rest into the
+browser.
+
+Non-goals: a decision to actually do this. This is scoping, not a plan.
+
+## The honest answer: most of it is incidental, one piece is load-bearing
+
+Everything that reads/writes the user's own PDS — crate folding
+(`crate.gleam`), adopt-or-mint (`promotion.gleam`), amend, blob upload, cover
+backfill — already only needs the user's own DPoP-bound access token, not a
+server secret. This shows up cleanly in the code: `promotion.gleam`'s `Deps`
+port (`catalog_deps.gleam`) is two pure functions over **public** reads
+(Constellation backlinks, `getRecord` on any repo); the actual write still
+needs the session, but that's the user's own credential, not the server's.
+The DI refactor that separated these into ports (`Context`/`Deps`, a few
+commits back) turns out to double as exactly the seam a browser port would
+need — the business logic doesn't know or care that it's running server-side
+today.
+
+**The one thing that's genuinely, unavoidably server-only: Discogs OAuth.**
+`discogs_oauth.gleam` signs every request with
+`oauth_signature = consumer_secret & token_secret` (OAuth 1.0a PLAINTEXT —
+literally the app's secret concatenated into the request, not an HMAC of
+it). Shipping `DISCOGS_CONSUMER_SECRET` to a browser bundle means shipping it
+to every user. As long as Discogs import is a feature, something server-side
+has to hold that secret.
+
+Everything else server-side today is there because the app's atproto OAuth
+is a **confidential client with server-custodied sessions** — a deliberate,
+reasonable choice, but a choice, not a requirement. A **public client**
+(PKCE + DPoP, no client secret, tokens held by the browser) is the standard
+shape for a pure atproto SPA, and this app already runs in that mode for
+local dev (`config.gleam`'s public/confidential toggle keys off `BASE_URL`)
+— production just hasn't flipped it.
+
+## What's actually missing to go there
+
+Checked how much of the OAuth machinery in the `atproto_client` package (the
+one this app already depends on, extracted from an earlier version of this
+same codebase) would carry over to a browser build:
+
+- **OAuth flow orchestration, PAR/PKCE/token-exchange logic**: plain Gleam,
+  no `@external` calls anywhere in the package. Compiles for the JS target
+  today (confirmed: `web/build` already has working `.mjs` output for these
+  modules, from an incidental transitive dependency — nothing in `web/src`
+  calls them yet, but the compiler already proves they build).
+- **HTTP transport**: already abstracted (`xrpc.Client(send: fn(Request) ->
+Result(Response, String))`, explicitly documented as "bring your own
+  backend"). A browser build needs a `fetch`-based `Client` — doesn't exist
+  yet, but is a small, mechanical thing to write (the server's own
+  `atproto_client.gleam` is the `httpc`-based equivalent, ~20 lines, to
+  mirror).
+- **DPoP key crypto — the actual blocker.** DPoP signing goes through `gose`
+  → `kryptos` (third-party packages, not ours). `kryptos`'s JS FFI is real
+  and dual-target-shaped, but every operation (`generateKeyPairSync`,
+  `sign`, `createPrivateKey`) goes through Node's `crypto` module — there is
+  no WebCrypto (`SubtleCrypto`) implementation anywhere in it. This is not
+  "untested," it's "will not run in an actual browser" as shipped today. The
+  PKCE half of this same problem is smaller: the random-bytes side already
+  uses real WebCrypto (`crypto.getRandomValues`), only the SHA-256 challenge
+  hashing goes through Node's `createHash`.
+- **DPoP key persistence**: entirely unaddressed by the library (it signs;
+  storage is "the caller's job," per its own docs) — a browser build needs
+  to hand-roll IndexedDB storage of a non-extractable `CryptoKey`, from
+  scratch, either way.
+
+None of this is _hard_ — DPoP only needs a tiny crypto surface (generate one
+P-256 key, sign a compact JWS, export the public JWK), far smaller than
+`kryptos`'s full JOSE/COSE scope — but it's real, unstarted work, and it
+lives in a dependency this project doesn't own. The pragmatic path is
+probably a from-scratch minimal browser DPoP signer inside `atproto_client`
+itself (a JS-target-only `@external` function, bypassing `kryptos`
+entirely for this one use), not waiting on an upstream PR.
+
+## A security nuance worth being honest about
+
+The instinct is "browser-held keys are less safe than server-held ones." The
+real picture is more mixed. DPoP's whole point is sender-constraint: even
+under full XSS, a **non-extractable** `CryptoKey` can be used to sign
+requests live from the compromised page, but the raw key material can't be
+exfiltrated for offline replay — which is roughly the same blast radius as
+XSS against a server-cookie session (attacker acts as the user while present
+either way). The genuine costs of moving custody to the browser are
+different from "less secure": it's unbuilt engineering (above), weaker
+multi-device session continuity (no natural sync of browser-local storage
+across devices), and losing one layer of defense-in-depth (tokens simply
+never entering the JS runtime at all, today, is worth something even if the
+marginal risk reduction is smaller than intuition suggests).
+
+## Options
+
+**A. Status quo.** No work. Misaligned with "ideally no backend," and the
+server keeps doing session/token custody for zero architectural reason
+beyond "it was easiest to build this way."
+
+**B. Thin the BFF now, defer full browser-DPoP.** Move everything that
+doesn't need a secret _and_ doesn't need the atproto session — i.e. calls
+against genuinely public, CORS-open services — directly into the browser,
+without touching how atproto OAuth/sessions work at all:
+
+- **Done:** the handle-typeahead proxy (`identity.gleam`) was built
+  server-side purely for "web only talks to the BFF" tidiness, not
+  necessity. Verified `public.api.bsky.app` sends
+  `access-control-allow-origin: *` (curl bypasses CORS, so this needed an
+  actual header check, not just reachability) — deleted the server handler
+  and route, and `web/src/at_record_web/effects.gleam` now calls it
+  directly, with the AppView origin kept in one named constant
+  (`web/src/at_record_web/appview.gleam`) rather than inlined, so pointing
+  at a different AppView later is a one-line change.
+- Same likely applies to `handle_resolver.gleam`'s PLC directory lookup (the
+  attribution chip) — `plc.directory` is typically CORS-open too, though
+  worth confirming rather than assuming (see Open decisions).
+
+Small, immediately actionable, zero risk to the OAuth security model. Doesn't
+touch the bigger question at all, but stops making it worse.
+
+**C. Full public-client rearchitecture.** Browser holds the DPoP key and
+tokens; server shrinks to Discogs OAuth/API + whatever the
+[catalog-browse](./catalog-browse.md) appview eventually needs, nothing
+else. Real payoff (this really would be "no backend, atproto-native"), real
+cost (the DPoP crypto + storage work above, plus rewriting every handler in
+`server/src/at_record_server/handlers/` as browser-side calls against the
+user's own session — genuinely most of the app's current logic). Also
+changes the Discogs-import shape for the better regardless of whether the
+rest of C happens: the server's role there could shrink to "authenticated
+fetch of collection pages," with the browser doing the actual PDS
+writes/promotion/blob-upload using its own session — meaning even Discogs
+doesn't require the full import _pipeline_ server-side, just the
+OAuth-gated read.
+
+**Recommendation: B now, C as a deliberate future bet, not a foregone
+conclusion.** This app is personal-scale; the DPoP-in-browser work is real
+but bounded, and doing it well (non-extractable keys, careful IndexedDB
+handling) is worth taking slowly rather than rushing to hit "zero backend."
+B costs almost nothing and is directionally correct either way.
+
+## Open decisions
+
+- **Public vs. confidential client, for real, in production** — the app
+  already supports both modes; C requires committing to public. Confidential
+  gets a bit more trust in some AS consent UIs; public is the actually-honest
+  shape for a client with no server component.
+- **Does `plc.directory` send CORS headers?** Assumed yes (it's a public
+  read-only directory), not verified. Worth a quick check before moving
+  `handle_resolver.gleam`'s logic client-side.
+- **Does `i.discogs.com` (cover images) send CORS headers?** If not, even
+  under option C the browser can't `fetch()` the image bytes directly to
+  re-upload as a PDS blob, and _that specific step_ (not the whole import)
+  would need to stay server-proxied. Unverified.
+- **Where does the browser DPoP signer live?** Inside `atproto_client`
+  (benefits the published package, and any other Gleam atproto app) vs.
+  local to this repo (faster, no coordination with the upstream package's
+  maintainer). Leans toward upstream, given this codebase's own history of
+  extracting generically-useful atproto plumbing into `gleam-atproto`.
+- **Session durability under browser custody.** No multi-device sync,
+  logout-everywhere, or session recovery after clearing site data — is that
+  an acceptable UX regression for what this app is, or does it need a
+  fallback (e.g., still allow confidential-mode login as an option)?
diff --git a/docs/catalog-authority.md b/docs/catalog-authority.md
index 2d4dd0f..b9be60b 100644
--- a/docs/catalog-authority.md
+++ b/docs/catalog-authority.md
@@ -1,8 +1,11 @@
 # Spec: catalog authority (shared canonical releases)
 
-Status: **proposed** (not implemented). Builds on covers-as-blobs, the
-genesis-TID entry identity, open unions (`catalog.edit.fields`), and the
-existing immutable `catalog.release` + `defs#catalogRef` lexicons.
+Status: **mostly implemented**. Shipped: inline adopt-or-mint on genesis
+write, the `via @handle` attribution chip, `basedOn`/`supersedes`
+corrections through the amend flow, and a minimal read path (the
+record-detail view resolves the entry's `release` ref and shows the
+canonical genres/styles/country/released). **Not shipped:** list-level
+resolution, caching, and true field-level merge (see Serving/display).
 
 ## Goal
 
@@ -91,28 +94,42 @@ the proposal format anyone can publish against a `subject` catalogRef:
 - Anyone else's edit is advisory until applied; the edit log itself is public
   provenance of who proposed what and why (`rationale`).
 
-## Serving / display
+## Serving / display (minimal version built 2026-07)
 
-The BFF resolves `release` refs on read (public `getRecord`, Slingshot for
-other-repo fetches) with a short in-process cache, merges canonical fields
-over the snapshot, and falls back to the snapshot whenever resolution fails.
-Covers prefer the local blob, then the canonical record's blob.
+Built: the per-entry endpoint (`GET /api/shelf/:entryId`) resolves the
+entry's `release` ref via the catalog `Deps` port and returns a `release`
+object (`artistDisplay`, `genres`, `styles`, `country`, `released`) that
+the record-detail page renders as chips and detail rows. Best-effort read:
+a failed resolution omits the field and the snapshot carries the display.
+
+Still open from the original plan: resolution on the shelf _list_ (per-
+entry only today), an in-process cache, true field-level merging of
+canonical over snapshot (today they render side by side), and cover
+preference logic. The snapshot still refreshes only when the user amends.
 
 ## Build order
 
 1. Lexicons (all additive): `source` extension, `shelf.entry.source`,
-   `catalog.release.cover` blob + `supersedes` catalogRef.
-2. Inline adopt-or-mint in the genesis write paths; import/add attach `source`.
-3. BFF resolution + merged display (snapshot fallback).
+   `catalog.release.cover` blob + `supersedes` catalogRef. **Done.**
+2. Inline adopt-or-mint in the genesis write paths; import/add attach
+   `source`. **Done.**
+3. BFF resolution + merged display (snapshot fallback). **Partial:**
+   per-entry resolution on record detail is built (2026-07); list-level
+   resolution, caching, and field-level merge remain (see Serving/display).
 4. Adoption flow, manual first (paste/choose a canonical; blob copy).
-5. `catalog.edit` proposal UI + provider-side apply (mint + supersedes).
+   **Done** via the amend flow (`basedOn`/`supersedes`, blob copy for
+   foreign covers).
+5. `catalog.edit` proposal UI + provider-side apply. **Partial:** amending a
+   foreign record automatically files a `catalog.edit` proposal; there is no
+   UI yet for a provider to review/apply proposals filed against them.
 6. Discovery index via microcosm (deferred; revisit with cross-user work).
 
 ## Open decisions
 
 - **Snapshot refresh policy:** update the cached snapshot when the canonical
-  changes (event noise) vs render-time merge only (chosen above; snapshots
-  refresh only when the user acts on the entry).
+  changes (event noise) vs render-time merge only. Still open in practice —
+  render-time merge is the intended design but isn't built (see
+  Serving/display); today refresh only happens when the user amends.
 - **Master vs release:** Discogs distinguishes masters from pressings;
   `entity: "master"` is reserved in `catalog.edit` but no lexicon exists yet.
   Defer until the scan flow forces the pressing question.
diff --git a/docs/catalog-browse.md b/docs/catalog-browse.md
new file mode 100644
index 0000000..8947947
--- /dev/null
+++ b/docs/catalog-browse.md
@@ -0,0 +1,147 @@
+# Sketch: browsable catalog
+
+Status: **sketch, not designed in detail** (no lexicon or build order locked
+yet — this is the "what would it take" pass requested before committing to
+one). Builds on [catalog authority](./catalog-authority.md) (canonical
+`catalog.release` records, adopt-or-mint, the attribution chip) and reuses
+the amend flow's blob-copy machinery.
+
+## Goal
+
+A page where you can browse `catalog.release` records that exist across the
+network (not just your own crate) and, from that list, mark one as
+**wanted** or say **I have this** without going through Discogs search
+again — the release is already known, so adding it should be near-instant.
+
+Non-goals (v1): full-text/faceted search, browsing by artist as a first-class
+entity, ranking beyond "recently seen" or a rough adoption count.
+
+## The hard part: there is no index yet
+
+Every other read in this app is scoped to one user's own repo (`listRecords`
+against their PDS) or a single verified lookup (`getRecord` for one known
+at-uri). "Browse all known catalog releases" is a different shape of query —
+enumerate records of one type **across repos** — and nothing in the current
+stack answers that:
+
+- **Constellation** (already used in `promotion.gleam`'s adopt-or-mint) indexes
+  **backlinks**: "who references at-uri X." Great for "has anyone already
+  published this Discogs release" or "how many people own this release" (a
+  backlink count on the release's own at-uri). Not built for "list every
+  `catalog.release` record that exists."
+- **Jetstream** can filter its firehose by collection NSID
+  (`wantedCollections=dev.mokkenstorm.crate.catalog.release`), which _is_ the
+  right shape — a live stream of every new/updated release record
+  network-wide — but consuming it means running a persistent indexer and
+  materializing a searchable copy. This is the self-hosted appview the
+  [ROADMAP](../ROADMAP.md#cross-user--discovery-infrastructure) has so far
+  deferred, reasoning that leaning on microcosm's hosted services might make
+  it unnecessary. A browse index is the first requirement that doesn't fit
+  that reasoning — Constellation's backlink shape genuinely can't serve it.
+
+Two ways to get an index, worth picking based on scale rather than
+theorizing:
+
+### v1: index only the users at-record already knows about
+
+The server already learns a DID + handle on every OAuth login
+(`oauth/flow.gleam`); it just doesn't persist that list anywhere durable
+today (it's decrypted per-session, not queryable). Add a small `known_users`
+Postgres table (`did`, `handle`, `first_seen_at` — same idiom as
+`sessions_postgres.gleam`'s `table_store`), upserted on login. A browse
+endpoint then does a live (or periodically cached) `listRecords` against
+`catalog.release` for each known DID via their PDS and merges the results.
+
+Cheap, no new infrastructure, and honest about what it shows ("catalog
+entries from at-record users," not "the whole network") — which matches
+catalog-authority's already-stated posture: _"Non-goals (v1): a central
+catalog service, global dedup... convergence is social, not enforced."_ This
+degrades gracefully: it's just slow and repeats work as the user count
+grows, which is exactly the trigger to move to v2.
+
+### v2: Jetstream-filtered indexer
+
+When "known users" stops being enough users to be useful, or the live
+`listRecords` fan-out gets too slow: a small consumer subscribed to
+`catalog.release` (and maybe `shelf.entry`, for live adoption counts)
+writes into a Postgres materialized table (uri, cid, did, title, released,
+cover ref, indexed_at). This is the same shape of infra the e2e devnet
+already runs locally (jetstream + constellation, see
+[e2e/README.md](../e2e/README.md)) — running one in production is the
+actual scope increase, not the concept.
+
+**Recommendation: build v1 now, revisit v2 when the known-users fan-out
+demonstrably doesn't scale.** Don't build the indexer speculatively.
+
+## Gap: `catalog.release` has no queryable artist field
+
+`promotion.gleam`'s `mint` already has the artist as a plain string
+(`discogs_client.Release.artist`) at the point it writes the record, but
+`catalog.release`'s only artist field is `creditedArtists` — an array of
+`#credit` objects where each credit points at _another_ `catalogRef`,
+meaning artists would need to be first-class minted catalog entities before
+that field means anything. That's a bigger feature (and echoes the
+already-open "master vs release" entity question in catalog-authority's open
+decisions) — not worth doing just to render "Title — Artist" in a browse
+grid.
+
+**Cheaper fix:** add a plain `artistDisplay: string` field to
+`catalog.release` (additive, mirrors `shelf.entry.snapshot.artist_display`)
+and set it from `release.artist` in `mint`. One lexicon field, one line at
+the mint call site. `creditedArtists` stays reserved for whenever artist
+entities actually get built.
+
+## Actions from the browse page
+
+Both actions mint a `shelf.entry` genesis with `release: <catalogRef>`
+already set — no Discogs search, no adopt-or-mint discovery step, because
+the ref is already known from the index:
+
+- **Want it** → genesis with `action: "wanted"`.
+- **I have this** → genesis with `action: "acquired"`.
+
+Still worth a `getRecord` fetch against the ref before writing (the index
+can be stale or, in the v1 fan-out design, briefly wrong) — same
+verify-before-trust posture adopt-or-mint already uses, and the same
+blob-copy path `amend.gleam`'s `copy_foreign_cover` already implements
+(foreign cover bytes copied into the user's own repo so the entry stays
+self-contained even though the release wasn't minted by them).
+
+This is a thin addition to the existing add path — a variant of
+`add_shelf_item` that takes a `release` ref instead of a Discogs id, skips
+straight to genesis-with-known-ref instead of adopt-or-mint's discovery.
+
+## Adoption count (nice to have)
+
+Once a release has a real at-uri, "N people have this" is a Constellation
+backlink count on that at-uri (`getBacklinks(subject: <release-uri>)`) —
+the same query shape `promotion.gleam` already makes, just counting instead
+of verifying. Useful for sorting the browse grid by popularity, and it's the
+concrete answer to catalog-authority's still-open "canonical selection: rank
+by adoption count" decision.
+
+## UI sketch
+
+A `/browse` route reusing the existing visual language: the same
+`cover_card` grid the crate view uses, a text filter over the (client-held
+or server-searched) title/artist strings, and per-card quick actions instead
+of a link into the add form — `WANT IT` / `I HAVE THIS` buttons, with a
+badge instead of the buttons when the release is already in the viewer's own
+crate (owned or wanted). Picking either action is a single write, no
+intermediate form, since every field the add form normally collects already
+exists on the canonical record.
+
+## Open decisions
+
+- **v1 fan-out cost:** live `listRecords`-per-known-user on every browse
+  load vs a periodic cache refresh (cron-ish, or refresh-on-login). Live is
+  simplest; cache is the obvious next step once the known-users list is more
+  than a handful of people.
+- **Dedup across users' `catalog.release`s:** v1 will show near-duplicate
+  releases minted by different users pointing at the same Discogs id (no
+  global dedup, per catalog-authority's stated posture). Worth grouping by
+  `externalIds` match in the browse view even before real dedup exists —
+  cheap, and avoids an obviously repetitive grid.
+- **`artistDisplay` vs waiting for `creditedArtists`:** recommended above;
+  flagging as a decision since it's a lexicon change that should be made
+  deliberately, not as a drive-by.
diff --git a/docs/catalog-entities.md b/docs/catalog-entities.md
new file mode 100644
index 0000000..3664887
--- /dev/null
+++ b/docs/catalog-entities.md
@@ -0,0 +1,79 @@
+# Spec: artist + genre entities (proof of concept)
+
+Status: **PoC, Discogs-fed** (lexicons + write path built 2026-07). Every
+mint path (import, scan add, manual add with a Discogs id) now widens the
+existing per-release Discogs fetch into a `ReleaseDetails` and, before
+minting the release: mints/reuses `catalog.artist` records (own-repo dedup
+keyed on Discogs artist id) wired into the release's `creditedArtists` as
+bare refs, and mints `catalog.genre` vocabulary records from
+genres+styles strings (releases keep their plain strings). The same
+details enrich the minted release (`artistDisplay`, `country`, `released`,
+`genres`, `styles`, barcode `identifiers`). Zero additional Discogs API
+calls per item. Scopes cover both new collections (re-login required for
+existing sessions). No UI reads any of it yet.
+
+Failure posture (per the "accounted for writes" decision in ROADMAP): a
+PDS 429 on an entity write aborts the item before the shelf event, so the
+run stops cleanly and the item retries next run; non-429 entity failures
+are counted and surfaced in the import run's note; failed mints never
+enter the dedup dict, so the next reference retries.
+
+## Why a PoC and not the real thing
+
+If artist/genre ever become real record types, they're exactly the shapes
+other atproto music apps would want too, and "required is forever" cuts
+both ways: a `dev.mokkenstorm.crate.artist` nobody else adopts is wasted,
+and an ecosystem lexicon designed alone is presumptuous. Checked 2026-07:
+teal.fm's `fm.teal.alpha.feed.play` has no standalone artist records and no
+genre property at all; its whole interop surface is MusicBrainz ids
+(`artistMbIds`, `releaseMbId`, `recordingMbId`) plus inline name strings.
+
+So the PoC settles what the shapes look like in our own namespace while the
+pre-adoption window keeps iteration free, and the actual interop story
+stays **MBIDs in `externalIds`**, which needs zero lexicon coordination.
+Before these graduate past PoC, coordinate with teal.fm (they develop in
+the open on tangled) and similar apps.
+
+## The shapes
+
+Both records: `key: tid`, `required: [name, createdAt]`, everything else
+optional (default-to-optional), repeatable `externalIds`
+(`defs#externalId`: provider + id + url, with `musicbrainz` as the
+canonical provider for cross-app identity).
+
+- **`catalog.artist`**: `name`, `sortName` (collation: "Beatles, The"),
+  `disambiguation` (MusicBrainz-style clarifier for name collisions),
+  `externalIds`, `thumbUrl`, and the same `supersedes`/`basedOn`
+  correction lineage `catalog.release` has, so artist corrections work
+  like release corrections from day one.
+- **`catalog.genre`**: deliberately thinner: `name`, `description`,
+  `externalIds`. Genres on releases stay plain strings; this exists to
+  explore what a shared vocabulary entity would look like. MusicBrainz's
+  genre list is the natural external target.
+
+## What's built vs. still open
+
+Built (2026-07): own-repo artist mint/reuse at release-mint time keyed on
+Discogs artist id, `creditedArtists` population as bare refs
+(`credit.required` was relaxed to `[artist]`, dropping the ill-fitting
+mandatory snapshot), genre vocabulary minting from Discogs genre/style
+strings, and the scopes. Implementation lives in
+`server/src/at_record_server/catalog_entities.gleam` (dedup planning is
+the pure, tested `distinct_missing`) and threads through
+`promotion.adopt_or_mint`, which now returns an `Outcome` carrying the
+grown dedup dicts and a `MintReport`.
+
+Still open:
+
+1. **Cross-user artist adoption** via Constellation backlinks on the
+   external-id URL (the same discover-verify-adopt shape release
+   promotion uses); today artists are own-repo only, so two users minting
+   the same artist do not converge.
+2. **MBIDs on artists**: only Discogs ids are captured; MusicBrainz ids
+   (the actual cross-app key, see above) need a Discogs-to-MB mapping
+   pass, which pairs with the MBID roadmap item for releases.
+3. **Genre migration to refs**: releases keep genres as plain strings;
+   migrating to genre refs is a breaking change only worth doing with
+   cross-app agreement.
+4. **Any read path**: nothing displays artists or genres as entities yet
+   (browse-by-artist is the natural first consumer).
diff --git a/docs/discogs-import.md b/docs/discogs-import.md
index 70be343..e88f9b5 100644
--- a/docs/discogs-import.md
+++ b/docs/discogs-import.md
@@ -1,16 +1,15 @@
 # Spec: Discogs account connection + collection import
 
-Status: **implemented** (build-order steps 0-5), with one deliberate cut:
+Status: **implemented**, with one deliberate cut:
 
 - **Rate limiting is cap + resume, no pacer.** Each run writes at most
   `?limit=` records (default 100, max 500); any 429 (Discogs read or PDS
   write) stops the run early and the response says to run again. Dedup makes
   re-running free, so the pacer and header-driven backoff remain follow-ups.
 
-Covers are stored as blobs (step 0: `atproto/blob` + `repo.upload_blob` +
-codegen `blob` support): add/import fetch the image (`cover_image` preferred
-over the 150px thumb), upload it to the user's repo, and embed the ref in the
-snapshot; reads resolve it to the PDS `getBlob` URL. Fetch/size/upload
+Covers are stored as blobs: add/import fetch the image (`cover_image`
+preferred over the 150px thumb), upload it to the user's repo, and embed the
+ref in the snapshot; reads resolve it to the PDS `getBlob` URL. Fetch/size/upload
 failures fall back to the `thumbUrl` hotlink instead of failing the write.
 Stored Discogs creds are encrypted at rest (`sealed_store`, `STORE_KEY`).
 
@@ -38,9 +37,9 @@ this much cheaper than the atproto OAuth we already built:
 
 - **App-level** (operator, one-time): register an app at
   discogs.com/settings/developers → `DISCOGS_CONSUMER_KEY` + `DISCOGS_CONSUMER_SECRET`
-  (env). This can also replace the personal `DISCOGS_TOKEN`: passing the consumer
-  key/secret unlocks cover images + the 60/min rate limit for search too, so we
-  end up with **one** credential set.
+  (env). This also replaces the personal `DISCOGS_TOKEN`: passing the consumer
+  key/secret unlocks cover images + the 60/min rate limit for search too, so
+  it's **one** credential set.
 - **Per-user** (obtained via the flow): `access_token` + `access_token_secret` +
   `username`, stored keyed by the user's DID.
 
@@ -77,57 +76,49 @@ The request-token-secret from step 1 is needed in step 4 but lives across a
 redirect: stash it in a **signed cookie** alongside a CSRF value (exactly like
 the atproto `state` cookie), so the callback can recover it without server state.
 
-## Modules / surface
+## Modules
 
-| Piece                                                                     | Size      | Reuses                                                                            |
-| ------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------- |
-| `discogs_oauth.gleam`: header signing, request/access token, `signed_get` | medium    | `ctx.client.send`, `crypto.strong_random_bytes` (nonce), `gleam/time` (timestamp) |
-| `DiscogsStore` (did → creds), memory + postgres                           | small     | mirrors `sessions.Store` / `sessions_postgres` / `sessions_memory`                |
-| Routes: connect / callback / disconnect / import / status                 | small     | near-clone of `oauth_login` / `oauth_callback`, cookie/CSRF helpers               |
-| Import: paginate → map → dedup → `write_event`                            | medium    | the genesis path (`do_add` / `write_event`), `crate.fold` for dedup               |
-| Frontend: connect/disconnect + import button + progress                   | small     | the existing Discogs card                                                         |
-| codegen `blob` type + `atproto/repo` `upload_blob`                        | small-med | shared atproto `Blob` type; `uploadBlob` rides the DPoP/token path                |
-| `ratelimit.gleam` pacer + 429 backoff on writes                           | small-med | bucket actor like the session stores; new path (see Rate limiting)                |
-| Tests: golden signing header, import mapping, dedup                       | small     |                                                                                   |
-
-Lexicon delta: `shelf.entry` already has `externalIds` + `snapshot`; the only
-add is a `cover` blob field on the snapshot (see Covers as blobs).
+`discogs_oauth.gleam` (PLAINTEXT header signing), `DiscogsStore` (did →
+creds, memory + postgres, mirrors `sessions.Store`), the
+connect/callback/disconnect/import/status routes (cookie/CSRF handling
+mirrors the atproto OAuth routes), and `catalog_import.gleam` (paginate →
+map → dedup → `write_event`, reusing the genesis path and `crate.fold` for
+dedup). The only lexicon addition was the `cover` blob field on
+`shelf.entry`'s snapshot (`externalIds` already existed) — see Covers as
+blobs.
 
 ## Covers as blobs
 
 Hotlinking `i.discogs.com` URLs leaves a hole in "your data on your PDS": the
 cover rots when Discogs reorganizes and vanishes if they block or disappear.
-Instead, store the bytes as a **blob in the user's repo** so the record is
-self-contained.
+Instead the bytes are stored as a **blob in the user's repo** so the record
+is self-contained.
 
 Plumbing (identical wherever the ref lives):
 
-1. **Codegen `blob` type.** Today codegen handles string/int/array/ref/object.
-   atproto blobs serialize as
-   `{"$type":"blob","ref":{"$link":"<cid>"},"mimeType":...,"size":...}`. Add a
-   shared `Blob` type (atproto package) + a `blob` case in codegen.
+1. **Codegen `blob` type.** atproto blobs serialize as
+   `{"$type":"blob","ref":{"$link":"<cid>"},"mimeType":...,"size":...}`; a
+   shared `Blob` type (atproto package) plus a `blob` case in codegen.
 2. **Lexicon:** a `cover` blob field (`{"type":"blob","accept":["image/*"],
 "maxSize":...}`) replacing the `thumbUrl: uri` string on the snapshot.
 3. **`atproto/repo.upload_blob(client, pds, token, did, bytes, mime)`** →
-   `com.atproto.repo.uploadBlob`, returns the blob ref. Authenticated, rides the
-   existing DPoP/token path.
+   `com.atproto.repo.uploadBlob`, returns the blob ref. Authenticated, rides
+   the existing DPoP/token path.
 4. **Seed/import:** fetch the Discogs image bytes (CDN, not API-rate-limited) →
    `upload_blob` → embed the returned ref in the record.
 5. **Display:** the cover URL becomes the PDS's public
    `com.atproto.sync.getBlob?did=<did>&cid=<cid>`. The server knows did + pds, so
    when it folds/encodes an entry it resolves the blob to that URL string; the
-   frontend keeps consuming a URL string and barely changes.
+   frontend just consumes a URL string.
 
 Content-addressed blobs dedup by CID within a repo, so owning two copies of a
-release does not double storage (only transfer). Blobs must be referenced by a
-record or the PDS garbage-collects them; embedding the ref in the genesis event
-references it.
+release does not double storage (only transfer). Blobs must be referenced by
+a record or the PDS garbage-collects them; embedding the ref in the genesis
+event references it.
 
-**Open: where the ref lives.** (a) on the `shelf.entry` snapshot now (works
-immediately; migrates to `catalog.release` when Option C lands) vs (b) bring a
-minimal `catalog.release` forward to hold the canonical cover and reference it
-via `catalogRef`. The plumbing above is identical either way, so (a) wastes no
-work. Recommended: (a).
+The ref lives on the `shelf.entry` snapshot (not a separate
+`catalog.release`) — see [catalog authority](./catalog-authority.md), which
+now carries its own `cover` blob field for the canonical-record path.
 
 ## Import
 
@@ -171,54 +162,28 @@ more than an hour. Blobs add an `uploadBlob` request per cover on top. And these
 limits **vary by host** (self-hosted PDS may have none), so the limiter must be
 adaptive, not a hardcoded number.
 
-**New mechanism.** `atproto_client` retries _transport_ failures
-(connect/timeout). A rate limit is an `HTTP 429` with `ratelimit-reset` headers,
-which returns as a _successful_ response (`BadStatus(429)`) and sails past that
-retry. Rate handling is a distinct path on the write side.
-
-**Posture: adaptive-reactive first, gentle pacer second.**
-
-- _Reactive (must-have):_ on PDS `429`, read `ratelimit-reset` / `retry-after`,
-  sleep until then, retry. On Discogs, slow when `-Remaining` is low. Robust
-  because it adapts to the host's actual (unknown) limit.
-- _Proactive (smoother):_ a token-bucket pacer in front of import writes, as a
-  small `ratelimit.gleam` bucket actor (same shape as the session-store actors).
-- _Resumable (free safety net):_ dedup-on-resume lets a capped or interrupted
-  import continue, so a per-run cap + "run again" turns a 2,000-record
-  collection into a few runs that never trip a limit.
-
-v1: adaptive 429-backoff on the write path + a paced, resumable import with a
-per-run cap and progress count, honoring Discogs' remaining-header on reads. Skip
-a global proactive limiter until there is real contention.
-
-## Build order
-
-0. codegen `blob` type + shared atproto `Blob` + `repo.upload_blob` (foundation
-   for covers).
-1. `discogs_oauth` signing module + golden-header tests (pure, no network).
-2. `DiscogsStore` (memory + postgres).
-3. connect / callback / disconnect routes + signed-cookie CSRF.
-4. status surfaced + frontend connect/disconnect.
-5. import: paginate / map / dedup / fetch+upload cover / `write_event`, plus the
-   frontend import button.
-6. rate limiting: 429 backoff on writes + import pacer; cap logging; (later)
-   backgrounding.
+A rate limit is an `HTTP 429` with `ratelimit-reset` headers, which returns as
+a _successful_ response (`BadStatus(429)`), not a transport failure — so it
+needs its own handling distinct from `atproto_client`'s transport retries.
+
+**Posture: adaptive-reactive first, gentle pacer second (still not built —
+see the cut at the top).**
+
+- _Reactive (must-have, shipped):_ on PDS `429`, stop the run early instead of
+  retrying blind; the response tells the caller to run again.
+- _Proactive (smoother, not built):_ a token-bucket pacer in front of import
+  writes, and reading `ratelimit-reset` to sleep-and-retry instead of just
+  stopping.
+- _Resumable (free safety net, shipped):_ dedup-on-resume lets a capped or
+  interrupted import continue, so a per-run cap + "run again" turns a
+  2,000-record collection into a few runs that never trip a limit.
 
 ## Open decisions
 
-- **Unify on consumer key/secret** and drop the personal `DISCOGS_TOKEN`?
-  **Decided: yes** (operator registered an app credential). Search switches to
-  `Discogs key=…, secret=…`, which also unlocks its cover images.
-- **Cover blob home:** **Decided: (a) snapshot** (shipped). Migrates to
-  `catalog.release` when the catalog authority lands; the plumbing carries
-  over unchanged.
 - **Wantlist too?** `GET users/{u}/wants` → genesis with `action: "wanted"`.
-  Cheap to add; v1 optional.
-- **Folder selection?** Users have custom collection folders. v1 imports folder
-  0 (all); folder picker later.
-- **Per-instance fields?** Discogs collection instances can carry rating / notes /
-  condition (media grade). `basic_information` omits them; fetching them is extra
-  calls. v1 imports snapshot + `acquired` only; grades/rating as a later pass.
-- **Token encryption at rest.** **Decided: done.** Both the session and the
-  Discogs credential stores are wrapped by `sealed_store` (A256GCM JWEs), keyed
-  by the mandatory `STORE_KEY`.
+  Cheap to add; still v1-optional, not built.
+- **Folder selection?** Users have custom collection folders. Still imports
+  folder 0 (all); folder picker not built.
+- **Per-instance fields?** Discogs collection instances can carry rating /
+  notes / condition (media grade). `basic_information` omits them; fetching
+  them is extra calls. Still imports snapshot + `acquired` only.
diff --git a/docs/discogs-sync.md b/docs/discogs-sync.md
index cc4c059..b609101 100644
--- a/docs/discogs-sync.md
+++ b/docs/discogs-sync.md
@@ -71,14 +71,16 @@ matching one-entry-per-copy.
 
 ## Build order
 
-1. Capture `discogs-instance` external ids on new imports (done). Reconciling
-   already-imported entries is still open.
-2. `origin` extension lands (done, see catalog spec).
-3. Shadow table + cursor; pull-only sync (supersedes Import in the UI).
-4. discogs_client write methods (instance add/remove/fields/rating, folders,
-   wantlist) behind the existing OAuth 1.0a signing.
-5. Push side off the cursor; pull-then-push runs.
-6. Scheduled sync (deferred).
+Done: `discogs-instance` external id capture on new imports, and the
+`origin` extension (see catalog-authority spec). Remaining:
+
+1. Reconcile already-imported entries against instance ids (see Identity
+   prerequisite).
+2. Shadow table + cursor; pull-only sync (supersedes Import in the UI).
+3. `discogs_client` write methods (instance add/remove/fields/rating,
+   folders, wantlist) behind the existing OAuth 1.0a signing.
+4. Push side off the cursor; pull-then-push runs.
+5. Scheduled sync (deferred).
 
 ## Open decisions
 
diff --git a/docs/shelf-events.md b/docs/shelf-events.md
index ce2b926..228ee2a 100644
--- a/docs/shelf-events.md
+++ b/docs/shelf-events.md
@@ -1,7 +1,7 @@
 # Spec: the shelf as an event stream
 
-Status: **proposed** (not implemented). Supersedes the mutable `shelf.item` +
-`deleted` soft-delete flag. Consistent with immutable `catalog.release`.
+Status: **implemented**. Replaced the earlier mutable `shelf.item` +
+`deleted` soft-delete flag; consistent with immutable `catalog.release`.
 
 ## Model
 
@@ -54,9 +54,9 @@ collection → one `listRecords` → one fold. Extensible via `knownValues`.
   "createdAt": "2026-06-28T…", // required; event time (informational; order by rkey)
 
   "release": {/* catalogRef */}, // optional soft link to the catalog release
-  "snapshot": {/* snapshot   */}, // denormalized display; client includes on
-  // genesis (render + pre-promotion); on later
-  // events optional (see decision 5)
+  "snapshot": {/* snapshot   */}, // denormalized display; genesis-only in practice
+  "externalIds": [{/* externalId */}], // provider ids captured at creation (e.g. discogs:12345)
+  "source": {/* source */}, // provenance: who/what wrote this event and from where
 
   // optional, action-relevant payload (a field is "set" by the event that carries it):
   "mediaGrade": "VG+",
@@ -69,8 +69,8 @@ collection → one `listRecords` → one fold. Extensible via `knownValues`.
 }
 ```
 
-Required: `action`, `createdAt`. Everything else optional
-(default-to-optional), including `price` and `counterparty`. Status is **not stored** — it is implied by `action`.
+Required: `action`, `createdAt`. Everything else optional (default-to-optional).
+Status is **not stored** — it is implied by `action`.
 
 ### Action set + reducer semantics
 
@@ -85,6 +85,7 @@ Events for one entry (genesis + its subject-refs), ordered by **`rkey` (TID, mon
 | `rated`     | set rating.                                                                           |
 | `moved`     | set folder.                                                                           |
 | `annotated` | set notes.                                                                            |
+| `updated`   | refresh snapshot/cover only (e.g. import backfill). status unchanged.                 |
 | `sold`      | status → `gone` (sold). May set price, counterparty. Leaves history intact.           |
 | `dropped`   | status → `gone` (gave up / removed, no sale).                                         |
 
@@ -143,11 +144,13 @@ Writes (each appends one immutable event; nothing mutates):
 No `PUT`. "Edit" = append a corrective event. "Remove from crate" = a `sold` /
 `dropped` event.
 
-## Migration from the current mutable `shelf.item`
+## Migration from the former mutable `shelf.item`
 
-- `shelf.entry` is a **new collection** (`…crate.shelf.entry`); the old
-  `…crate.shelf.item` is retired, not changed (so "required is forever" is moot —
-  it's a fresh lexicon).
+- `shelf.entry` was a **new collection** (`…crate.shelf.entry`), not a change
+  to `…crate.shelf.item` (so "required is forever" was moot — a fresh
+  lexicon). Pre-adoption (single-user, no one else depended on the old
+  shape), so the `shelf.item` lexicon file itself has since been deleted
+  rather than kept as a frozen artifact.
 - One-time migration: read existing `shelf.item` records → write one `acquired`
   (or `wanted`) `shelf.entry` genesis per item, copying snapshot/grades/notes and
   preserving `createdAt`. Optionally `deleteRecord` the
@@ -156,30 +159,17 @@ No `PUT`. "Edit" = append a corrective event. "Remove from crate" = a `sold` /
   too (it's immutable; deletion = tombstone/`deleteRecord`, correction = new
   record + optional `supersedes`).
 
-## Open decisions to confirm before building
-
-1. **Entry identity**: ~~client-minted `entryId`~~ **decided: the genesis
-   event's rkey (TID)**, with appends carrying a `subject` strongRef. More
-   atproto-native: stable linkable at-uris, free backlinks, no minted id.
-2. **Wishlist placement**: `wanted` entries in the same collection/feed as owned
-   (one log, filtered by status) vs a separate wishlist concept. (Recommend: one
-   log.)
-3. **Order/tie-break**: fold by `rkey` (TID, monotonic, clock-fudge-proof) with
-   `createdAt` informational. (Recommend as written.)
-4. **Money / transaction detail**: include `price` (an `{amount, currency}`
-   object, minor units) and `counterparty` (a string), both **optional**.
-5. **Snapshot**: keep it (lets an entry render standalone, survive a dangling or
-   foreign `release` ref, and exist pre-promotion). Required on the genesis event
-   by client convention. Whether later events repeat it is a render-cost vs
-   lookup knob, **not a lexicon decision** (snapshot is optional) — so default to
-   **genesis-only now**, and add it to feed events later with no schema change.
-6. **Action set openness**: keep `action` open `knownValues` so new verbs don't
-   need a lexicon bump. (Recommend: open.)
+## Design notes
+
+- **Wishlist is not a separate concept.** `wanted` entries live in the same
+  log as owned ones, filtered by folded status.
+- **Snapshot is genesis-only by client convention** (lexicon leaves it
+  optional on every event). Cheapest render-cost/lookup tradeoff; nothing
+  stops a later event from repeating it if that changes.
 
 ## Consequences
 
-- Supersedes the mutable `shelf.item` + `deleted` soft-delete.
-- Whole system becomes append-only + derived: immutable `shelf.entry` (this) and
+- Whole system is append-only + derived: immutable `shelf.entry` (this) and
   immutable `catalog.release`; the appview/BFF is the lens.
 - Reads become O(events) folded (fine at personal scale; grows forever; the BFF
   folds). A future appview can materialize the fold for efficiency.
-- 
2.51.2