Build desk: @Build

Register id build.desk · kind construction · cadence when the site, the tools or the pipeline change

Mission

Keep the machine that turns the desks' files into a site honest: the build, the validator, the reading room, offline-first, and the release pipeline.

The central claim, written as a failure condition

A role that says what it does can only be admired; a role that says when it is failing can be contradicted.

This role is failing when: The site does not open from file:// with the network off, or a gate passes something the house rules forbid.

Gravity

Offline first; the gate never weakens.

Reads

brief/03-the-site.md
AUTHORING.md
the validator's output

Writes (its mandate: the validator holds a run record to these)

tools/
.github/
.claude/
agents/
run-local.sh
README.md
AUTHORING.md
CLAUDE.md
data/network.json
assets/
data/releases.json
data/keys.json

Plus what every run shares: runs/, site/, version.txt, data/loose-ends.json, issues/. Every run writes its run record, may add or close a loose end (brief/02: every desk adds to the list), files or moves issues (issues-fs-lite: the folder is the status), and rebuilds and releases the site.

Produces

tools/.py, tools/.css, tools/*.js
agents/ (rendered from data/agents.json)

How a run goes

Change the tooling, then python3 tools/build.py && python3 tools/validate.py.
Check offline: open site/index.html from disk with the network off.
A construction run moves no loose end, writes no edition and fetches no source.

Works with

every desk: whose files the build renders
@Editor: who decides what the gate should refuse

The mandate, what this role refuses and whose work it is not: MANDATE.md.

Build desk: mandate

Register id build.desk. A run record for this role names "agent": "build.desk".

Not responsible for

Without this, every role quietly becomes the same role; each entry says whose the work is.

Any edition, story, signal or history piece Belongs to: the desk that owns it

The register of agents Belongs to: @Editor: a new agent is an editorial decision

Refuses

Weakening a gate to make a build pass
Loading anything from the network in a page
Hand-editing site/

Wrong when

The site does not open from file:// with the network off, or a gate passes something the house rules forbid.

May write

tools/
.github/
.claude/
agents/
run-local.sh
README.md
AUTHORING.md
CLAUDE.md
data/network.json
assets/
data/releases.json
data/keys.json
runs/
site/
version.txt
data/loose-ends.json
issues/

Anything else in a run record's folders_changed fails tools/validate.py.

Runs (23)

2026-09-26T10:31:00Z · construction · The drain refused a message for naming a key prefix; align relay.py's credential check with the validator's.
- relay.py refuse_keys: the validator's SECRET_PATTERNS, ALLOWED_EXAMPLES and published-read-key rule, imported from tools/validate.py; naming sgit_private_vault_ is allowed, key material is refused. The v3 message then drained, verified and filed.
2026-09-26T10:01:00Z · construction · Fix the lane numbering @Cowork noticed.
- relay.py lane: the next number follows the highest outgoing lane Message-ID (sent: 1, 2, 3, 6; next 7); before, incoming messages with a lane field were counted too.
2026-09-26T00:51:00Z · construction · Give the session inbox's registry entry an expiry, as the review proposes.
- data/keys.json: identities.newsroom.sgit.inbox.expires = 2026-09-26T12:00Z, with a note that the session closes it sooner.
2026-09-26T00:40:00Z · construction · Drain the session inbox; verify signers by fingerprint, as @Cowork's note and the v2 write-up advise.
- relay.py inbox drain: 1 message from @Cowork, verified, filed, purged.
- relay.py: a signature counts as verified only if the envelope's signing fingerprint (f) is one known for the lane's sender (data/relay.json peers.*.signing_fingerprints); sgit's label is kept for reading only.
- Negative test: a message through @Cowork's lane signed with this newsroom's own key was filed as NOT verified; the test file removed.
2026-09-26T00:16:00Z · construction · Drain the session inbox, and fix what @Cowork's reply reported.
- relay.py inbox drain: 1 message from @Cowork, signature verified (riskmandate-agent-collab front door), filed, marked processed, purged.
- relay.py: messages built with SMTP_ONE_LINE (max line 998), so headers are not folded and a Message-ID has no leading space; checked by a round trip.
2026-09-26T00:05:00Z · construction · The ephemeral inbox (issue 049): open, self-test, drain and close a vault made for one session, with its key held inside the tool.
- tools/relay.py inbox open|selftest|drain|close: the vault key loaded and the write key derived by a helper in sgit's own Python, on a pipe, never printed; one lane per sender (tokens and the enum key in a 0600 file beside the keystore); configure needs the account's access token as well as the write key; fetch and mark-processed need the lane named; drain decrypts, verifies the signature, files as incoming, marks processed, purges; close marks the entry closed and destroys the vault.
- Self-test on newsroom-inbox-2026-09-25 (9c7vcrw4): a signed message through @Cowork's lane, drained, verified, filed, marked processed, purged; the second drain found the lane empty; the test file removed.
- tools/relay.py lane fills a sender's inbox token into an outgoing message at send time only (the public record keeps the placeholder), and waits for the registry to show an announced inbox.
- tools/build.py: the keys page shows the inbox. data/keys.json: the inbox entry (vault, endpoint, encrypt_to, senders, status).
2026-09-25T19:10:00Z · construction · Drop the HMAC from the key registry, as the editor of record decided, and publish the current signing key as serial 1.
- tools/relay.py rotate: no token needed and nothing derived from one; the registry states the four checks. tools/build.py: the keys page without a binding row.
- Retested on a throwaway keystore (serial 1, no binding field), then data/keys.json written for the real key: newsroom.sgit serial 1, sha256:9b69885b35612bdd, signing sha256:f791a1cfb957d58f.
- The build publishes keys/agents.json (the URL to pin) and keys/index.html.
2026-09-25T18:45:00Z · construction · Key rotation without a hand-off: a published registry of the newsroom's agent keys, and a rotate command.
- tools/build.py build_keys: data/keys.json becomes keys/agents.json (the URL a postmaster pins) and keys/index.html; no file, no output.
- tools/relay.py rotate [--new]: optional fresh key pair (the front door imported into a new keystore), the next serial with the old key retired, an HMAC-SHA256 token binding, data/keys.json and data/relay.json updated; lane waits for the pinned URL to show an announced serial before sending.
- Tested twice with a throwaway keystore and a fake token: serial 1 then 2, key 1 retired, HMAC recomputed and matching, the front door among the keystore's contacts; the data files restored.
- Not run with the real token: the session's permission layer refused publishing a value derived from it. No data/keys.json exists yet.
- agents/ re-rendered (the Build desk may write data/keys.json).
2026-09-25T18:00:00Z · construction · Send through the append lane: encrypted to the front door, signed with this newsroom's key.
- tools/relay.py lane: builds a single-part .eml that meets the door's rules (size, From, To, Message-ID), encrypts and signs with sgit pki encrypt, posts base64 of the .enc to dev.send.sgraph.ai, marks the message sent on exactly {"ok": true}; --dry-run writes the .eml and .enc and posts nothing. The token is read from the environment and never written or printed.
- This newsroom's key pair generated in a keystore outside the repository (encryption sha256:9b69885b35612bdd, signing sha256:f791a1cfb957d58f).
- The first message sent: 7064 bytes of payload, answer {"ok": true}.
- relay.py status shows the vault recipient; slugs no longer end in a dash.
2026-09-25T15:20:00Z · construction · The first check-in as one command, so the join can run on a machine allowed to hold the key.
- tools/relay.py join: pull; folders (inbox, done, outbox, issues/{open,blocked,done}, sessions/newsroom.sgit); brief.md written once and notes.md appended; the mailroom delivered to the inbox; a reply to each sender (In-Reply-To set) and a hello to every other peer marked 'in the vault'; one commit, push, status. Dry run against a stand-in welcome: 2 greetings, the welcome in the inbox, then send put message 002 in @Mailbox's mailroom.
- Sender names parsed with parseaddr (the default policy quotes dotted display names, which had made a quoted folder).
- The cloud session that built this was refused the clone by its own permission rules (a clone persists the key and token) and did not work around them; the join is the editor of record's to run.
2026-09-25T15:05:00Z · construction · Emphasis that runs over a wrapped line rendered as plain asterisks (seen on the relayed message's note).
- tools/mdlite.py: bold and italic may span a line break inside a paragraph (the desks and the source sites wrap at ~110 columns); 651 more emphasis runs across 611 pages, spot-checked.
2026-09-25T14:50:00Z · construction · Tooling for the relay (issue 024): send and check messages over the relay vault; show message states on the briefing pages.
- tools/relay.py (standard library): send (unsent briefings/<site>/inbox/*.md to .eml in mail/mailroom/<peer>/ and mail/newsroom.sgit/outbox/<peer>/, notes.md line, sgit commit and push, mark sent with Message-ID and vault path), check (sgit pull; delivered when the mailroom copy is gone, handled when in the peer's done/; deliver own mailroom to inbox and mirror each received .eml as an incoming page), status, --dry-run; refuses a folder without .sg_vault/ and any credential-shaped string. Dry run produced message 001 as an RFC 2822 file.
- tools/build.py: briefing pages show each message's direction, state, timestamps and Message-ID, a note on the channel linking brief/08, and the relay block in the JSON twin; tools/style.css: incoming messages.
- .claude/skills/newsroom-run: relay check and send when NEWSROOM_RELAY_VAULT is set, else report unsent.
- agents/ re-rendered (editor.desk may write data/relay.json).
2026-09-25T13:40:00Z · construction · Screenshots of the pages the desks cite (issue 015): make tools/screenshots.js survive the network and the target sites, capture the set, ship it under every piece's byline.
- tools/screenshots.js: manifest saved after every page (an interrupted run keeps what it took); browser context recycled every 10 pages and third-party requests blocked (one long-lived browser wore the proxy's tunnels out after ~40 pages); one retry on a fresh context; .md fallback when a site serves no .html twin (riskmandate.ai/versions/*: 43 pages); waits for networkidle (sgit.ai fetches and injects its css after load; a 500ms wait caught 68 blank or unstyled frames).
- assets/shots/: 191 of 191 cited pages captured as jpeg 1200x750 (about 16 MB), assets/shots/manifest.json with the capture time per page.
- Issue 015 moved to done.
- .gitignore: the stock 'build/' pattern hid two shots under a cited github.com/.../build/ path and site/src/sites/games.sgit.ai/build/ from git, so CI's build differed from the committed site (v0.1.12 red); assets/shots/**, site/src/** and site/assets/** un-ignored.
2026-09-25T13:10:00Z · construction · Fourth batch of the flight notes: briefing cards and the semantic twin (renderer and validator), the Cartographer's helpers, screenshots of cited pages, this newsroom's releases as part of what it reports.
- AUTHORING.md: 'cards:' front matter (tiles under the byline) and the semantic twin (<piece>.json: typed nodes and edges); tools/build.py renders both, tools/validate.py checks the twin's schema.
- tools/diagrams.py: wardley(), timeline(), graph(), mindmap(), network_from_json() turn data into Mermaid text (tested: all four render offline). The Cartographer's mandate: no page without a visual.
- tools/screenshots.js: captures the live pages the desks cite into assets/shots/ with a manifest; the build shows a strip of them under a piece's byline.
- data/releases.json (appended by tools/release.sh; the build never runs git): admin/versions.html, and this newsroom's releases in the reading list as a site of its own (principle 5).
- Issue 030 moved to done; 015 when the screenshots land.
2026-09-25T12:50:00Z · construction · Third batch of the flight notes: the side pane (peek a link beside the page, notes, chat), the tier 0 and tier 1 chat with tools over the site, briefing pages per target site with JSON twins.
- tools/panel.js (assets/panel.js): a pane on the right of every page, width dragged and remembered; Peek opens any local link in an iframe beside the page (offline) with 'open as the page', links carry the reader's read and note marks; Notes moves the page's feedback bar into the pane; Chat: tier 0 matches the site's own index with no key, tier 1 calls openrouter.ai with the reader's key (kept in the browser) and tools search, open_page, my_feedback, file_feedback, read_next, falling back to tier 0 on failure; a message starting 'For the <site> agent:' is filed as a relay.
- tools/build.py: briefings/<site>.html and .json for every site or team with a brief, an inbox message, a signal addressed to it or a loose end waiting on it; briefings/index.html.
- A page shown inside the pane hides the newsroom's chrome. 'Copy for Claude' carries relayed messages.
- Issues 012, 013, 023, 025 moved to done.
- The newsroom-run skill: the Editor step files relay lines from a Copy for Claude paste into briefings/<site>/inbox and reports messages still unsent.
2026-09-25T12:35:00Z · construction · Second batch of the flight notes: the word ban in the validator, the history index as cards with lessons markable one by one, the network map clickable and its table sortable, a badge on every source page naming the target site, images not in the snapshot said so.
- tools/validate.py fails a banned word (brief/07) in a desk's own prose, allowing quotations.
- history/index.html: tiles (decisions, questions, lessons, contradictions) and cards; lessons, decisions and open questions: each ### item is a section the reader marks read on its own, hidden in the reader's view.
- maps/network.html: nodes link to each site's reading-room page (Mermaid antiscript), the table sorts on any column and a row opens the site's strongest links in and out.
- Source pages: a 'From <site>, as fetched on <date>' badge on the sheet with the live link; a remote image the snapshot did not bring home renders as a labelled placeholder.
- Issues 027, 031, 034, 014, 028 moved to done.
2026-09-25T12:20:00Z · construction · Implement the first batch of the flight notes: the approved front page, a sheet and byline on every piece, feedback on every piece, read hides in the reader's view, two views, a history with undo and redo.
- Front page in the approved layout (nameplate, dateline, section band, review line, lead with its map and 'also in this edition', the Historian beside it, signals as a list, the week in editions with change bars, card sections, a rail).
- Every desk page: a byline block (desk with a link to its role, date, section, standfirst, sources, read time, review state) and the article on a white sheet; the feedback bar on stories, editions, history, maps and signals; the read control reads 'Mark as read' / 'Read, mark unread'.
- feedback.js: a view switch in the header (Editor's / Mine); in Mine, pieces marked read are hidden from the front page and every card section, with a clue and a link to feedback/read.html; feedback/history.html lists every action with undo (appends the inverse, keeps the log) and redo.
- Issues 041, 009, 010, 011, 017, 018, 019 moved to done.
2026-09-25T12:10:00Z · construction · Capture the editor of record's notes of 25 September (read offline on a plane) as issues, and give the back office an issues board.
- issues/: 45 issues in issues-fs-lite form (8 epics, 33 tasks, 4 briefs for agent@riskmandate.ai); 41 open, 2 blocked, 2 done.
- tools/build.py renders admin/issues/ (kanban by status with epic, owner and priority filters) and a page per issue; tools/validate.py checks every issue has created and priority and a real parent.
2026-09-25T09:30:00Z · construction · Newsroom workflow infrastructure: bundled Mermaid, maps, the magazine front page, News, the admin back office, sections-driven navigation.
- tools/vendor/mermaid.min.js (Mermaid 12.0.0, MIT) and assets/diagrams.js: diagrams render offline; tested wardley-beta, flowchart, timeline, mindmap from file://.
- tools/build.py: maps/ as a desk folder; maps/network.html computed from data/network.json; front page composed from data/frontpage.json; news/index.html; admin/ (desks, review queue, front page, notes, prompts, inbox); navigation from data/sections.json.
- AUTHORING.md: standfirst and section, maps and the Mermaid rules, frontpage.json. The newsroom-run skill now runs the Cartographer every day and the Editor last.
2026-09-25T08:24:17Z · construction · Frame the vault apps inside the newsroom; vaults as cards.
- vaults/app/<slug>.html for the five seed vaults, sandboxed frame; the vaults page as 36 cards.
2026-09-25T08:20:29Z · construction · Build the reading-list design: filters and feedback kept on the device.
- tools/feedback.js; reading list on the reading room and the new-pages page; feedback bar on every source page; documents on a white sheet.
2026-09-25T08:02:03Z · construction · Add run-local.sh and bring home the .md twins of linked network pages.
- run-local.sh and tools/fetch_missing.py; the build keeps a heading's own anchor, resolves riskmandate.ai release-note links from the site root, ASCII section file names.
2026-09-25T00:20:23Z · construction · Build the first version from the seed pack: build, validator, librarian tool, CI.
- tools/mdlite.py, build.py, validate.py, librarian.py; .github/workflows/deploy-pages.yml (validate, tag, deploy).