# Working on HUD For every agent working here: CLAUDE.md is this file, imported. What HUD is and how it is run is in `README.md` and the pages in `docs/`. ## Layout - `crates/hud-core`: everything that is not HTTP: configuration, the outbound client and its address filter, identity resolution, lexicons, PDS reads, XRPC queries (`xrpc.rs`: services, params and answers checked against lexicons), blob-ref rewriting, the audio blob cache, views (their validation, the component catalog, the join engine, summaries), the kit each tree is fitted to (`kit.rs`: the renderer's version a client says, a view's gates on it, what stands for a component newer than it, and `hud check`'s warnings for an app's oldest kit), the tools, the three that write (`writes.rs`, a text's facets made by `richtext.rs`, a composer's writes template filled by `compose.rs`), a link's card (`cards.rs`) and places (`places.rs`) for a composer, the procedures a trusted view calls (`procedures.rs`), the operator's apps and views (`operator.rs`, `HUD_APPS`, checked as the bundled views' tests check them, with the lexicons they ship and the HUD versions they run on), the JSON Schemas of an app file and a view (`schema.rs`), the workspace's canvases (`canvas/`: the engine, each person's tabs and live stream, placement on the strip of columns in `strip.rs`, the `Store` trait and its file backend, the space backend in `space.rs`, with `HUD_SPACES=on`, the tools), apps' icons (`icons.rs`: favicons, kept on disk), the workspace's themes (`theme.rs`: HUD's, people's `place.hud.theme` records, their contrast check, and each person's choice of one), what HUD keeps of a person and its deletion (`account.rs`), the space client (`space.rs`: `com.atproto.space.*` as the account), the scope sign-in asks for (`scope.rs`: atproto's permissions, built from the trusted views, through the permission sets their app files name, and whether a sign-in is behind them), and sign-in (`oauth/`: the MCP authorization server in `issuer.rs`, the atproto OAuth client in `client.rs`, sessions on disk in `store.rs`, MCP sessions and the workspace's web sessions alike, and their offline tests against a fake PDS in `tests.rs`, its spaces and the space backend's tests in `tests/spaces.rs`). - `crates/hud-server`: the HTTP surface: `POST /mcp` (and its sign-in challenges), `GET /blob/{did}/{cid}`, `GET /_health`, the terms, privacy policy and guidelines, `GET /{terms,privacy,guidelines}` (`policies.rs`, each page's HTML in `policies/`), HUD's icon, `/favicon.svg`, the playground, `/playground` (`playground.rs`), HUD's methods, `/xrpc/place.hud.*` (`xrpc.rs`, its tests through the router in `xrpc/tests.rs`: the playground's and `searchActors` anyone's, the workspace's with sign-in on alone), and apps' icons, `/icon/{domain}` (`icon.rs`); and with sign-in on `/oauth/*` and `/.well-known/oauth-*` (`oauth.rs`, with the sign-in page MCP clients see), the workspace's page, `/workspace` (where `/` goes; signed out, the landing), the sign-in dialog's app logos, `/workspace/atmo/*` (`crates/hud-server/atmo/`), the landing's picture, `/workspace/hero/*` (`crates/hud-server/hero/`, made by `just hero`), and its sign-in, switching and sign-out, `/workspace/{signin,switch,signout}`, its sessions' cookies `hud_session` and `hud_accounts` (`workspace.rs`); with `HUD_WEB`, the operator's web app's pages, `/`, the icons and every request no route takes, handed on and streamed back (`web.rs`, its tests against a fake app in `web/tests.rs`); its `build.rs` embeds `web/dist/index.html`, `web/dist/workspace.html`, `web/dist/playground.html` and `web/dist/favicon.svg`. - `crates/hud`: the binary, `hud serve`; `hud resolve`, which gives a recorded answer its `_meta.ui`, for the harnesses; `hud check `, which loads a directory of apps as `hud serve` loads `HUD_APPS`, naming every problem; and `hud schema app|view`. - `web/renderer` (`@hud/renderer`): the renderers as Svelte components, with no dependency on MCP, so another app can reuse them, drawn on a server (`svelte/server`) as in the browser: nothing touches a browser's globals as it loads or draws, nothing is kept on a server, and the browser's first drawing is the server's (`Tree`'s `now`, dates fixed until mounted). Its server test, `web/renderer/test/ssr.mjs` (`cd web && npm run ssr`), draws Grain's trees in `web/renderer/test/trees` (made by `just ssr-data`, `harness/ssr/data.mjs`) in Node and hydrates them in happy-dom. - `web/renderer`, `web/shell` and `web/shared` are HUD's web packages, published (`docs/sdk.md`): each package's `src` built by `svelte-package` into its `dist` (`cd web && npm run package`), which its exports name; inside `web/` they resolve to `src` by the `@hud/source` condition (`vite.config.ts`, `tsconfig.json`, the server tests' builds). Code in `web/` imports one by its name (`@hud/shared/result`), never by a path into it. - `web/shell` (`@hud/shell`): an app drawn as a web app from its app file (`docs/views.md`, "The frame"): `Shell`, its frame (the tabs as a bar, a rail or a sidebar by the window's width, decided in CSS, `frame.ts`) and each tab's nav stack of tool results drawn with the renderer, server-rendered and hydrated as the renderer is; and `@hud/shell/server`, what an app's server reads for a page, and its sessions at HUD (`session.ts`: the browser's accounts, sealed in a cookie, `seal.ts`, `accounts.ts`; signing in as HUD's MCP client, `oauth.ts`). Its host gives it its router and routes its endpoints (Grain's `next/`). Its server test, `web/shell/test/ssr.mjs` (in `npm run ssr`), draws a sample app at three widths and hydrates it; `npm run unit` its unit tests. - `web/src`: the view, which talks to its host through `@modelcontextprotocol/ext-apps` and draws with the renderer. - `web/workspace`: the workspace's page, which calls its own server's `/xrpc/place.hud.*` and draws with the renderer, and the playground's (`web/playground.html`, `Playground.svelte`), built of the same components: a view written beside what it draws (`previewView`); `web/shared` (`@hud/shared`), what it, the view and the shell share: reading a tool result (`result.ts`), a person's interactions (`interactions.ts`) and `Result.svelte`; `web/public/favicon.svg`, HUD's icon, which Vite copies into `web/dist` as it is. - `web/dev`: a dev host for the view (`just dev`), against `just serve`. - `lexicons/`: the bundled lexicons, written by `just lexicons`; never edited by hand. `schemas/`: our own lexicons (`place.hud.*`: the records, the workspace's methods, `defs`, and `ui`, the resolved tree a result's `_meta.ui` holds, which `hud_core::ui::check` holds the resolver's trees to in its tests), written by hand, embedded beside them; `just lexicons` never touches it. `schemas/json/`: the JSON Schemas of an app file and a view (`hud_core::schema`), no lexicons, written by `just json-schemas` and held current by a test. - `harness/`: checks beside cargo's, each a node script whose header says what it checks and how to run it, run by the Justfile: `lexicons.mjs`, `answers.mjs` and `schemas.mjs` (`just lex`), `layers.mjs`, `contrast.mjs` and `docs.mjs` (`just lint`), `look.mjs` (`just look`), `scroll.mjs` (`just scroll`, a long feed scrolled, page in `harness/scroll/`), `gallery.mjs` (`just gallery`: every drawing HUD makes as a tile, side by side, from the answers in `harness/gallery/` given their trees by `just gallery-data`; the iOS app draws the same file, Debug builds' Settings → Development → Gallery). `cd harness && npm ci` once. Against a PDS of HUD's own: `pds.mjs` (the reference PDS and PLC, alice, bob and carol), the e2e world over it (`e2e/world.mjs`, `just e2e`), and the same kept running with a browser at it, and with `--ios` the app on a simulator, to try by hand (`local.mjs`, `just local`). HUD is served there at `hud.harness.internal` with a certificate of the checkout's own authority (`tls.mjs`, kept in `.local/tls/`), which a simulator is told to trust. Each takes the spaces alpha with HUD_DEV_ENV (`harness/spaces`; `just e2e-spaces`, `just local --spaces`), where HUD keeps canvases in people's spaces. `just local-setup` once per checkout and Mac: the packages, the authority, and that hostname in /etc/hosts. - `views/`: the bundled views, one JSON file per view, named as its id, each a `place.hud.view` document; embedded by hud-core and checked by its tests. An operator's views (`HUD_APPS`) replace or add to them at startup, held to the same checks (`view::trusted_problems`, `view::conflicts`). - `docs/`: the docs, one page per topic, each fact in one page, written and checked (`harness/docs.mjs`) as `docs/_style.md` asks, which says which page owns what; `README.md` points at them. A change to a tool, a default or a mechanism changes the page that owns it. - `themes/`: HUD's own themes, one JSON file per theme, named as its key, each a `place.hud.defs#theme`: light and dark, HUD's own look, with no palette, and the rest each a palette; embedded by hud-core, checked by its tests, and handed to the page and the iOS app by `getWorkspace`, so no client keeps a copy. People's are records in their own repositories (`place.hud.theme`), held to the same contrast. - `ios/`: the iOS app. `ios/HUDKit`, a Swift package: the renderer in SwiftUI, a port of `web/renderer` (`Tree/` draws the tree the server resolved, `Embed/` its embeds), what `web/shared/src/result.ts` and `interactions.ts` do (`Data/`), the client that calls the tools over `/mcp`, an operator's app file's routes and push for an app built on HUDKit (`Data/Routes.swift`, `Data/Push.swift`: the device registered as its `push` says, a tapped notification opened as a route), and the workspace's client and model (`Workspace/`: its XRPC methods and event stream as the signed-in account, by Bearer, and its theme, `Theme.swift`); its tests in `Tests/`. A palette reaches the views through `Support/Surface.swift` (`.hudTheme`, and `HUDColor`, a role's colour or the native one): a colour a palette names is never a system colour in a view. `ios/App`, the app around it: signed in, the workspace (canvases as tabs, a strip of columns, one a screen on a phone, each tile a tool call), Home and Settings (accounts, theme) sheets over it; signed out, signing in by handle; its icon in `App/Assets.xcassets`, the same as the favicon, square, as iOS masks it. `ios/project.yml` makes the Xcode project (`just ios`; the project is gitignored); `just ios-test` runs HUDKit's tests. - `android/`: the Android app, a Gradle project. `android/hudkit` (`place.hud.kit`): the renderer in Jetpack Compose, a port of `ios/HUDKit` as that is of `web/renderer`: `tree/` draws the tree the server resolved (`TreeView.kt`'s `ResolvedNode`, a component a function), `parts/` and `embed/` its pieces, `data/` what `web/shared/src/result.ts` does, `support/` the surfaces by role (`Surface.kt`'s `HudColors`, a palette's colour or Material's), type, icons (`Glyphs.kt`, the web's own paths) and pictures (Coil); its tests in `src/test`, on the JVM under Robolectric, reading iOS's fixtures. `android/app`, the app around it: for now the gallery, the sample tiles of `just gallery-data` a debug build carries (`just android `; `just android-test` runs hudkit's tests). A new crate goes in `crates/`, named as its directory, with its versions in the root `Cargo.toml`'s `[workspace.dependencies]`. ## Versioning HUD has one version, its SDK's: the crates', the web packages', HUDKit's and hudkit's (`knope.toml` names every file that holds it). A pull that changes what an app built on HUD sees (a component, a prop, what a tree draws, a tool's shape) adds a change file under `.changeset/`, as `knope document-change` writes one: `default: patch`, `minor` or `major` in its front matter, then a heading and a line for the app's authors. `release-pull.yml`, asked for at main, turns them into the version and CHANGELOG.md in a `Release ` pull; `release.yml`, asked for at main once that lands, publishes every package. Never bump a version by hand. `docs/sdk.md` has the rest. ## Rules - Cargo through rustup: `rustup run stable cargo` (the Justfile's `cargo`). Node is the version `.node-version` names; `cd web && npm ci` once. - `just check` is what a change must pass: rustfmt, clippy with warnings denied, the tests under `just cov`'s gate, svelte-check, the renderer's server test (`npm run ssr`), `just lint` and `just lex`. The runner (runner.knotless.dev) runs the same on pushes to main and pulls into it (`.knotless/workflows/`): `check`, `test` and `web` as the merge queue's pre-flights, `lexicons`, `docs`, `e2e` (`just e2e`) and `e2e-spaces` (`just e2e-spaces`). `main` takes pulls only through the merge queue, each once review.knotless.dev has reviewed its head, and each push to it deploys hud.place (`deploy`, on ci.knotless.dev). A workflow's shared steps are pinned in `.knotless/uses.lock` (`knotless workflow pin`). - `just cov` fails under 100% of lines or functions, workspace-wide: a line no test runs is a case nobody checked, so test it with what a consumer would notice, never lower the gate or hide code from it. Where no test can sensibly reach a line, write it so the path does not exist: `cargo fmt` can put a `?` on a line of its own, which counts as a line never run (bind the value first), and since Rust 1.100 coverage counts the closing `}` of an `if` with no `else` as the path where the condition is false, and each match arm on its own. The `hud` binary counts too: its tests run it (`CARGO_BIN_EXE_hud`), and stop `hud serve` by SIGTERM so its profile is written. - A lexicon in `schemas/` follows the Lexicon Style Guide (https://atproto.com/guides/lexinomicon) and passes `just lex`: goat's lint (less the warnings `harness/lexicons.mjs` keeps, each with why), `knownValues` not `enum`, objects in arrays, open unions, a description on every `main` saying whether it needs auth, a `maxLength` on every string without a format people write, accounts by DID; and only grows from main's once published. Every answer the server's tests receive is held to its method's lexicon (`harness/answers.mjs`), so a method's tests call it through the router (`xrpc/tests.rs`'s `ask`). - The server keeps no database: caches only, in memory, and the lexicon, audio blob and apps' icon caches on disk under `HUD_CACHE_DIR`; and, with sign-in on, sign-ins under `HUD_DATA_DIR/oauth/` (`hud_core::oauth`), the workspace's canvases and each person's index of them and their tabs under `HUD_DATA_DIR/canvas/` (`hud_core::canvas`), and each person's theme under `HUD_DATA_DIR/theme/` (`hud_core::theme`), each file mode 0600 and written whole; with `HUD_SPACES=on`, a canvas its owner alone is in goes in their own space instead. The one database is the operators' copy of the log, with `HUD_LOGS=on`: `HUD_DATA_DIR/logs.db` (`hud_core::logs`), SQLite, mode 0600, holding the lines stderr has and nothing more, so never a token, a query's secret, a header or a body; read by `HUD_OPERATOR_DIDS` alone. Lines are logged through `hud_core::telemetry` (`docs/observability.md`), every outbound call through `hud_core::net`. Never log a token, or keep one of HUD's own (a web session's cookie too) but as its SHA-256. The `query` tool calls queries alone, never a procedure; a caller goes through `xrpc::Caller`, as no one or as the signed-in account through its PDS, the one place they differ. Writes go through `create_record`, `apply_writes` and `delete_record` alone, as the account, to its own repository, each record checked against its lexicon first (its `{"$facets": key}` fields made the text's facets before), and a composer's pictures through `place.hud.uploadBlob` alone, to the account's PDS, never logged; but a procedure a trusted view calls (`Action`'s `call`, `Messages`' `send`), or an operator's app file registers a device for push with (its `push`), through `call_procedure` (`hud_core::procedures`) alone, the view's, sent through the account's PDS only if a trusted view or app file calls that method of that service, its input checked against its lexicon first, neither input nor answer logged; what a trusted view's `deletes` plans (an `Action`'s), through `call_procedure` alone too, its query asked as the account only if a trusted view deletes by it, its deletes committed in one `applyWrites` of the account's own repository, each of a collection the scope asks to write or delete (`Hud::delete_planned`); and the canvases' records through `hud_core::space`, as the account, to its own repo in its own spaces, each checked against its lexicon (`schemas/`) first. The space scope stays one constant (`config::SPACE_SCOPE`), never asked for by default. - A tool that needs an account answers `Refusal::SignIn` without one, which `/mcp` turns into the HTTP 401 challenge, never a tool error. No OAuth or MCP SDK crates: sign-in is built on the `atproto` crate's `jose` and `keys`. - Anything a DID document, lexicon or service says is untrusted. Outbound requests go through hud-core's client, which refuses non-public addresses, but for the operator's own web app (`HUD_WEB`), its origin the operator's, reached through a client of its own for it alone (`net::Web`); a service's answer is checked against its query's lexicon; lexicon `description`s reach the view only, as plain text, never a tool's `content`, description or `structuredContent` (`describe_collection` and `describe_method` strip them). - A tool's text `content` is a short summary a person could read; its data is `structuredContent`; what only the view needs is `_meta`. - The view loads nothing but its own inline code, and images and audio from the server's blob proxy, and public records' images from the image CDN (`HUD_IMAGE_CDN`), and public posts' videos from Bluesky's video service and CDN (HLS); it reaches the server only through its host's tool calls. No `fetch` from the view but a `Map`'s vector tiles, from `catalog::MAP_TILES` alone (in the CSP's `connectDomains`). - `blobs::rewrite` is told whether what it rewrites was read where anyone can (`Visibility::Public`: `com.atproto.repo.*`, the AppView) or not (`Private`: a space, a service's answer to the account): a private record's blobs never get a CDN URL. - The workspace's page reaches its own server alone, its XRPC methods as its web session; their procedures by the cookie carry `X-HUD: 1`, and the server takes them from its own `Origin` only. A HUD access token as `Bearer` calls them too, as an app of the person's would. A canvas tile names a read tool and its arguments, never a result: the page calls the tool (`callTool`) to draw it. Tiles are placed on the server (`canvas::strip`), so a person and an agent place them alike. - A change to a tool, its shapes or the view's renderers changes both sides in one change. - Views are data. No code names a collection a bundled view draws: a record type gets its own drawing by a view in `views/`, written with the catalog's components, not by a renderer of its own. Where a query draws a record richer (a post's thread), the record opens as that query: its method view names the collection in `records`, and no collection view draws it. Collections themselves are never shown: a profile shows apps, sections and activity, never a list of collections. - A tile is one thing. A view draws what belongs to its subject in itself, by a join: a post's replies, a gallery's photos and comments, an issue's conversation. It opens a new tile (`open`) only for another thing: another record, account, feed or app. - An account opens where it is read: a name in a bundled view's drawing opens their page in that view's app (`ui::Ctx::people`), else their profile across apps (`describe_repo`), which a tile's @handle opens too. A view names an account by `href`, never by an app's own query. - Only the bundled views and the operator's (`HUD_APPS`, `hud_core::operator`) are trusted, and HUD refuses to start unless the operator's pass what the bundled views' tests hold them to, through the same code. Every read of them goes through `view::bundled()`, the bundled views as the operator's replace and add to them. No HUD code names an operator's app. A view given inline is checked exactly as a bundled one is, but may name only `origins` a trusted view names (so it never widens the CSP), and its description reaches no tool description or instructions. A result says which it is (`_meta.ui.trusted`): the view asks the person to confirm an untrusted view's `Action` before it writes. - Views are resolved on the server: a view's layout is read against its data in `hud-core/src/ui/` into `_meta.ui`, a tree the clients only draw (no client binds a view or fetches for one). The component catalog lives in four places that change together: the Rust constant (`hud-core/src/catalog.rs`), which validates layouts and is what `describe_collection` and `describe_method` hand a model, with the resolver (`hud-core/src/ui/`) that reads it into the tree; and the three that draw the tree, `web/renderer` (`src/tree/`), `ios/HUDKit` (`Tree/`) and `android/hudkit` (`tree/`). A component or prop added to the catalog says the version it arrives in (`since`): a build of an older kit is sent its children, its fallback or nothing in its place (`hud-core/src/kit.rs`). A look is the platform's own, but the surfaces are one: a grey canvas, a tile's body lighter in front of it, a card in a tile that body's colour inside a hairline (iOS's `HUDKit/Support/Surface.swift`, Android's `support/Surface.kt`). ## Web pages The workspace (`web/workspace`) follows knotless's web practices (`~/code/knotless/web/AGENTS.md`, its `ui` skill): - **Layers:** components live in `web/workspace/lib/{atoms,molecules, organisms,templates}`; each uses its own layer and those below, never one above (`harness/layers.mjs`, in `just lint`). Pages in `web/workspace/*.svelte` fill the template; modules in `lib/` (state, the stream, `xrpc.ts`) belong to no layer. - **Tokens:** every value in its CSS is a token from `web/workspace/tokens.css` (knotless's, by the same names), a colour by its role, never its hue, as `light-dark()`; add one there when none fits. The renderer's MCP Apps host variables are set from them in `app.css`, so tiles and chrome are one look, and a theme's palette (`lib/theme.ts`) is written over them, so it colours both. Every text colour reads at 4.5:1 in light, dark and every palette: `harness/contrast.mjs` checks the pairs `harness/contrast.json` names in light and dark, and `hud_core::theme::problems` its `PAIRS` in a palette; a new colour that is text goes in the first, and in the palette and the second if a theme colours it. - **Icons:** Lucide's, through `lib/icons.ts`, one per thing, the same everywhere; an icon without its word has an `aria-label`. An app's icon is its favicon (`AppIcon`, HUD's `/icon/`), its kind's Lucide icon where it has none. - **Data:** the page reaches only its own server's XRPC methods, typed by `npm run lex` (gitignored `lib/lexicons`), through `lib/xrpc.ts`. - **Words and menus:** sentence case, labels without a full stop, empty states that say what is empty where the rows would be, one primary button a view; a menu that opens is a `
`, a sheet on a phone. - **Memory:** what a page holds follows what is on screen (`docs/memory.md`). A tile keeps its answer as read (`$state.raw`, a page more replacing it, never mutating it) and draws it only while `live`; a component's state a person changes (a like, a reveal) is kept with `remembered` (renderer `view/remember.svelte.ts`), as it is unmounted and drawn again; a long list goes through `ListWindow` (`view/window.ts`); a picture drawn small takes `source(…, 'small')`, a blob's `thumb` or a URL by the view's `thumbnails`, and `Picture` falls back once to a blob's `proxy`; media load nothing until played. A server cache is a `cache::Ttl`, bounded by entries and bytes, its share of `HUD_CACHE_MEMORY_BYTES`. Check a change with `just memory`, and one to a long list's drawing with `just scroll` (no long tasks while scrolling, p95 frame under 20 ms, no blank frames). - **Looking:** `just look [--set …] [--events …] [--click …] [--press …]` draws the workspace from `web/dist` in front of `harness/look/` (no PDS, no server: each answer given its `_meta.ui` by `hud resolve`) into `target/look`. Look at every state you touch, desktop light and phone dark, and have the pictures critiqued by an agent that did not write them. ## atproto's primitives DIDs, handles, NSIDs, record keys, CIDs and DID documents' services come from the `atproto` crate (knotless.dev/chadtmiller.com/atproto), published to that repository's Cargo registry, which `.cargo/config.toml` names. A primitive HUD needs that the crate lacks goes there first, as a new version.