steid

ab7fea9chore: plans setup1mo	1	# Progress
	2
	3	## This attempt (#3, Topcoat)
	4
0aca94efeat: a repository is one place, and its landing page says what it is17h	5	467 tests. Active milestone in [current.md](current.md).
88583f2docs: bring tracking docs up to date with milestone 11mo	6
c974d80feat: every read-side git process is bounded, and a timeout is not a fault17h	7	### Section 1 wave — read-only browsing · in progress
	8
	9	Every read-side `git` process is now bounded at 20 s (`GIT_TIMEOUT` in
	10	`git_query.rs`), and the child is `kill_on_drop` so a cancelled request takes git with
	11	it. Added before blame and grep arrived, because those are the first reads that can
	12	run long on a big repository, and five agents each adding their own bound would have
	13	produced five. `GitQueryError::is_timeout()` is how a page tells "asked too much"
	14	(render a state, offer less) from "git failed" (a 500). Tokio's `time` feature was
	15	enabled for it.
	16
6f0a608docs: fold the highlighting handover into plans17h	17	Syntax highlighting (merged 2026-09-05). `syntect` with the pure-Rust `default-fancy`
	18	engine plus `two-face` (`syntect-fancy` feature) for the grammars the default set lacks —
	19	TOML, Dockerfile, TypeScript — at +0.59 MiB on the binary. Decisions worth keeping:
	20
	21	- Classes, never inline colours. Output is `ClassStyle::SpacedPrefixed { prefix: "hl-" }`
	22	and every colour is a `--syntax-*` token in `styles.css`, so the palette follows the
	23	theme. `ClassedHTMLGenerator` cannot be used because its spans cross line boundaries
	24	and the blob view is one table row per line; `highlight.rs` drives `ParseState` +
	25	`ScopeStack` itself, carrying parse state across lines but closing and reopening the
	26	markup at each line end.
	27	- `hl-` classes are scope atoms, not positional, so `.hl-function` alone would colour
	28	every `meta.function` body. Single-atom selectors only for an atom that leads its scope;
	29	the rest are compounds. Rule order in `styles.css` is load-bearing: `.hl-string` is
	30	written after `.hl-punctuation` so a quote reads as its string, and the comment rule is
	31	last.
	32	- The trailing newline is dropped by character, not `trim_end` — the `_newlines`
	33	syntaxes need it fed in, and it comes back escaped inside the output, sometimes before a
	34	closing span. Left in, every row renders double-spaced.
	35	- Caps are 512 KiB and 10,000 lines, both, because cost is per byte and per line.
	36	Plain text is returned as `Plain` lines, not wrapped in colourless spans.
	37	- ~87 ms per 1,255-line file in release, uncached, paid on every view; debug is ~8×
	38	slower and not the number to plan against. If it matters: cache per blob object id.
	39
9b1feb6docs: fold the branches and tags handover into plans16h	40	Branches and tags pages (merged 2026-09-05). `/branches` and `/tags`, one
	41	`for-each-ref` each, and the counts beside the switcher and in the sidebar are links.
	42
	43	- `%(HEAD)` is why the page is one process: `for-each-ref` marks the default branch,
	44	so nothing calls `symbolic-ref` on the happy path, and the compare link's base is read
	45	from the pinned row.
	46	- Keep empty fields when splitting `for-each-ref` output. A lightweight tag's
	47	`%(*objectname)` is empty; filtering empties shifts its date into the id slot. There is
	48	a test for exactly this.
	49	- Ordering is git's (`--sort=-committerdate`), pinning is the use case's. The default
	50	branch is a display decision, a stable partition in `list_branches`.
	51	- A lightweight tag's `%(contents:subject)` is the commit's subject, so it is read only
	52	when `%(objecttype)` is `tag`. `annotated` is its own field because an annotated tag may
	53	carry an empty message. The row shows the peeled `%(*objectname)` so the sha is browsable.
	54	- "No tags yet" and "nothing pushed yet" are different sentences; telling them apart
	55	costs one `default_branch` call, only when the list is empty.
	56	- `refs.rs::timed_out` is the first web-layer place that renders a timeout as a state
	57	rather than a 500. When a second page wants it, move it to `web::context`.
	58
4e4ba31docs: fold the archive and search handover into plans16h	59	Archive download and code search (merged 2026-09-05). `/archive/{rev}.tar.gz`
	60	and `.zip` streamed from `git archive`; `/search?q=&rev=` over `git grep -F`.
	61
	62	- `GitArchive` is a fourth narrow port, not a `GitQuery` method. `GitQuery`'s contract
	63	is capped bytes, collected; an archive is as large as the repository. It lives in
	64	`infrastructure/git.rs` beside the protocol server and reuses `web::git::GitBody`, so
	65	"one subprocess's stdout becomes a response body" is written once and used twice.
	66	- The archive use case is two steps, which is what makes the `ETag` cheap.
	67	`archive_repo` authorizes and resolves into an `ArchiveTarget` nothing else can
	68	construct; `open_archive` runs git. A conditional request is answered from step one,
	69	so re-downloading a tag costs one `cat-file`. The `ETag` is the resolved commit.
	70	- `git grep` is the one command whose exit status is an answer (1 = no matches).
	71	`run_within_allowing` takes an allowed-exit list and `NO_MATCHES` names the exception
	72	at the call site, so the module's rule stays visible where it is broken.
	73	- `git grep -z` is not optional: a path may contain colons, so the colon-separated
	74	form has no unambiguous reading. The parser walks NULs.
	75	- `RepoPath` refuses a colon, so `a:b.rs` is unsearchable as well as unbrowsable; the
	76	parser drops those hits rather than link to a 404. Pinned by a test.
	77	- A search timeout is a page state (`Searched::TimedOut`), the first real consumer of
	78	`GitQueryError::is_timeout`.
	79	- Archive and search 404 a private repository for a stranger, matching every other
	80	read page rather than 0007's uniform 401, which exists so a git client can offer a
	81	credential; a browser link gets no benefit from it.
	82	- `topcoat dev` in a worktree exited rather than restarting after some source edits and
	83	had to be relaunched by hand. Possibly two instances sharing a `target/`. Watch it.
	84
88583f2docs: bring tracking docs up to date with milestone 11mo	85	### Milestone 0 — Skeleton · done
	86
	87	Topcoat 0.5 app serving pages, `AppConfig` from `STEID_*` env, SQLite pool in app
	88	context. Split into a library plus a thin binary — the domain layer had no consumers
	89	yet and read as ~30 dead-code warnings in a bare binary, and it unlocks `tests/`.
	90	Topcoat's link-time page discovery works from a library; that was checked, not assumed.
	91
	92	Requires rustc ≥ 1.95. On older toolchains `cargo add topcoat` silently resolves to
	93	an empty `topcoat v0.0.0` placeholder instead of failing.
	94
076dbc9docs: close milestone 1, open milestone 21mo	95	### Milestone 1 — Identity, thin · done
88583f2docs: bring tracking docs up to date with milestone 11mo	96
	97	Domain. Typed IDs, `Email`, `PasswordHash`, `OrgName`, `Organization`, `User`,
	98	`Membership`, `Role`, `Actor`, `Session`, `SetupToken`, `DomainError`. Value objects
	99	pair `new()` (validates) with `from_trusted()` (skips, for rows already validated).
	100
	101	Application. `claim_instance`, `login`, `resolve_actor`, `record_session`,
	102	`end_session`, `sweep_expired`. `PasswordHasher` port with Argon2 and a stub.
	103
	104	Infrastructure. Migrations for orgs, users, memberships, sessions. In-memory and
076dbc9docs: close milestone 1, open milestone 21mo	105	SQLite implementations of every port. Root layout, `/setup`, `/login`, `/logout`, home,
	106	and `/api/me`.
	107
	108	`describe_identity` is the first use case with two consumers — the home page and
	109	`/api/me` both read through it. Until that existed, "the application layer is
	110	transport-neutral" was an assertion with one caller behind it.
88583f2docs: bring tracking docs up to date with milestone 11mo	111
	112	Verified in a browser and by curl: wrong token refused with nothing written;
	113	correct token creates org + user + owner membership and signs the owner in; session
	114	authenticates; logout clears cookie and row; wrong password bounces; right one signs
	115	in; re-claiming a claimed instance is refused.
	116
	117	#### Decisions worth remembering
	118
	119	- `Actor` is an enum with an explicit `Anonymous`, not `Option<UserId>`. Attempt #2
	120	used a placeholder `UserId("ssh-anonymous")` and it became a security hole. A variant
	121	can't be forgotten the way a sentinel can.
	122	- `login` verifies a dummy hash when no user matched. Returning early on the
	123	unknown-email path makes it measurably faster and leaks which addresses have
	124	accounts. A test pins that the dummy stays parseable — if it stops being, `verify`
	125	bails early and the defence dies silently.
	126	- `SetupToken` compares in constant time. An early-return comparison leaks how much
	127	of the token is right, which recovers it a character at a time.
	128	- The setup token is only in app context while unclaimed, so a claimed instance has
	129	nothing for a claim attempt to match.
	130	- SQLite ignores foreign keys unless asked, per connection. `foreign_keys(true)`
	131	plus a test that a user pointing at a missing org is refused.
	132	- `sqlx migrate add` stamps versions to the second — three calls in one second
	133	collide, leaving apply order ambiguous between tables that reference each other.
	134	- An unparseable role surfaces as an error, never as "no membership". The latter
	135	silently downgrades an owner to no access.
	136	- `Secure` session cookies over plain-HTTP localhost fail silently. See
	137	[runbook.md](runbook.md#steid_insecure_cookies--development-only). This one actually
	138	bit, and it looked exactly like broken auth logic.
ab7fea9chore: plans setup1mo	139
c50d9adfeat: profile settings with flash feedback24d	140	### Milestone 2 — Profile page · done
3954b45docs: record milestone 2 phase 125d	141
	142	`/{handle}` is the real profile page: label, handle, bio, and the section frame for
	143	repositories, writing, and projects. Public, renders signed out, 404s on an unknown
	144	handle, and resolves regardless of casing. `/` forwards a signed-in owner to their own
	145	profile. `/api/users/{handle}` serves the same read model as JSON.
	146
	147	URLs settled as root handles with grouped application routes
	148	([0004](decisions/0004-root-handles-grouped-routes.md)), superseding
	149	[0003](decisions/0003-scoped-urls.md) the same day. A twenty-word reserved list in
	150	`OrgName::new` keeps handles from shadowing routes.
	151
	152	#### Decisions worth remembering
	153
	154	- `PublicProfile` has no email field, deliberately. `Identity` does, and `/api/me`
	155	returns it, because that endpoint describes the caller to themselves. Giving the type
	156	that reaches the page nowhere to put an email makes the leak impossible rather than
	157	merely avoided.
	158	- `viewer_is_owner` is decided in the use case, so the web form and `/api` cannot
	159	disagree about who may edit. Tested for a signed-in stranger and a non-owner member —
	160	"signed in" quietly becoming "allowed" is the usual failure.
	161	- `Organization::update_profile` clears on blank input rather than storing
	162	whitespace, so cleared and never-set are one state and the page renders one case. A
	163	rejected edit applies nothing.
	164	- Bio length counts characters, not bytes. A byte check would reject a bio of
	165	accented text well under the limit.
	166	- `path_param` is an attribute macro in 0.5, not function-like. The vendored crate
	167	is the authority for the pinned version, not the docs on `main`.
c50d9adfeat: profile settings with flash feedback24d	168	- Components are invoked bare inside `view!`, and `if`/`match`/`for`/`let` are
	169	native to the macro.
	170	- `#[query_params]` needs `error = …` to work with `?`; otherwise the error borrows
	171	from `cx` and escapes the handler.
	172	- Forms re-render on failure and redirect on success. Redirecting after a
	173	validation error throws away what was typed and hides the reason.
	174	- Styling is Tailwind via Topcoat's build script, with registry components copied
	175	in rather than depended on ([0005](decisions/0005-tailwind-and-copied-components.md)).
	176	Components reference theme tokens, never raw colours.
3954b45docs: record milestone 2 phase 125d	177
6a2a925docs: close Milestone 3, plan Milestone 4a8d	178	### Milestone 3 — Repo model · done
02eb2e4feat: GitStorage port and DiskGitStorage24d	179
6a2a925docs: close Milestone 3, plan Milestone 4a8d	180	Repositories exist as records and as bare repos on disk, and they appear on the
	181	profile. Domain, both persistence adapters, `GitStorage` with `DiskGitStorage` behind
	182	it, `create_repo` / `view_repo` / `list_repos`, the `/{handle}/repos/new` form and
	183	`/{handle}/repos/{name}` page, the profile's Repositories section, and
	184	`/api/users/{handle}/repos`. How git is invoked is recorded in
02eb2e4feat: GitStorage port and DiskGitStorage24d	185	[0006](decisions/0006-git-binary-behind-narrow-ports.md).
	186
6a2a925docs: close Milestone 3, plan Milestone 4a8d	187	Verified in a browser and by curl: the owner creates a repo through the form, a
	188	bare repo appears at `{data_dir}/{handle}/{name}.git`, and it lists on the profile; a
	189	private repo is absent for a signed-out visitor on both the page and `/api`; an unknown
	190	handle 404s rather than answering `[]`. `git clone` does not work yet — Milestone 4.
	191
02eb2e4feat: GitStorage port and DiskGitStorage24d	192	#### Decisions worth remembering
	193
	194	- `git init` on an existing repository exits 0 and re-initialises in silence.
	195	Measured, not assumed. So `AlreadyExists` has to be our own `path.exists()` check —
	196	there is no exit code to key off. Refusing rather than adopting matters because a
	197	directory with no matching row is an orphan from a crashed create, and re-initialising
	198	it would resurface a private repository's objects under a fresh record.
	199	- `git init` creates missing parent directories itself, so there is no
	200	`create_dir_all` before it. This was in the plan and the probe removed it.
	201	- `--template=` takes a new bare repo from 18 files to 2. The default seeds sixteen
	202	`.sample` hooks. Timed at 15.2ms against 13.1ms across 20 runs — so the ~2ms is not
	203	the reason; Steid installs its own hooks later and the samples would be noise to work
	204	around.
	205	- `--initial-branch=main` is explicit so the host's `init.defaultBranch` cannot
	206	decide it. This machine's git already says `main`, which is precisely why a drift
	207	would go unnoticed — hence the test.
	208	- `GIT_CONFIG_GLOBAL` and `GIT_CONFIG_SYSTEM` are pointed at `/dev/null`, and the
	209	five `GIT_*` variables that redirect object storage are removed from the child
	210	environment. `GIT_DIR` was checked and does not override an explicit path argument,
	211	but `GIT_OBJECT_DIRECTORY` does redirect where objects land, and the failure is
	212	silent — the repository just looks empty.
	213	- One `run_git` owns the invocation. With a single caller this looks premature; it
	214	is a private function rather than a public abstraction for that reason. The point is
	215	that Milestone 4's `http-backend` spawn cannot quietly disagree about isolation.
	216	- `tokio::process` and `tokio::fs`, never the `std` equivalents. `init_bare` is not
	217	hot — ~13ms, once per repository — but `remove_dir_all` on a repo with real history
	218	walks every loose object and would stall a runtime worker. The performance that
	219	matters is Milestone 4's per-request spawn, not this.
	220	- `tempfile` for test fixtures, not `target/`. Parallel-safe by construction and
	221	self-cleaning on panic. Debris under `target/` would be actively harmful here, since
	222	`init_bare` refuses a path that already exists.
0c5ca49feat: list repositories on the profile8d	223	- Membership is resolved once per listing, not once per row. Obvious in hindsight;
	224	the shape that invites the mistake is filtering inside a loop that can `await`.
	225	- One empty state serves "no repositories" and "none you may see". A distinct
	226	message for the second — or any count — leaks that private repositories exist and how
	227	many. Tested, because it is the kind of thing a later "helpful" tweak would undo.
285f5fdfeat: create and view repositories through the browser24d	228	- `redirect()` is a 307, and 307 preserves the method. Post/redirect/get needs a
	229	303, or the browser re-POSTs the form to its redirect target. Milestone 2's settings
	230	form shipped with this and nothing caught it — every test passed, because the tests
	231	are on the use case and the bug is in the reply. Found by following the redirect with
	232	curl. The fix is a `StatusCode::SEE_OTHER` plus a `Location` pair inside `view!`,
	233	wrapped as `web::context::location`, because `see_other()` is a response type and
	234	`#[page]` must return a view for the layout to wrap the failure re-render.
	235	`RedirectError::new` is private, so a 303 cannot be built as an error, and the
	236	error-to-response path only downcasts topcoat's own error types — a custom one
	237	becomes a 500.
	238	- `#[page]` returns a view; `#[route]` returns a response. That is the whole reason
	239	the redirect is spelled awkwardly: a form handler needs both a redirect and a
	240	full-page re-render, and only the view path gets the layout.
	241	- Boolean HTML attributes take an explicit value in `view!` — `required=(true)`, not
	242	bare `required`, which fails to parse. `false` omits the attribute entirely, so
	243	`selected=(bool)` on an `<option>` is correct rather than rendering `selected="false"`.
	244	- `topcoat ui add select` needs the `icon-iconify` feature and a staged icon set.
	245	The chevron comes from `feather`, staged in `build.rs`. No new crates, but the build
	246	fails with a clear message until the set is staged.
11e7a39feat: create_repo use case24d	247	- `is_org_owner` moved to `application/authz.rs` on its second caller. Owner-ness
	248	gates the profile edit, repo creation, and later PATs and push; two copies of an
	249	authorization predicate drift, and the direction they drift is open.
	250	- The compensating transaction is safe to do by path. `remove` after a failed save
	251	can only ever delete what `init_bare` just created, because the loser of a concurrent
	252	create never gets past `init_bare`. Non-obvious enough that it is commented in the
	253	code as well as here.
	254	- Compensation is best-effort. If the removal also fails, the caller still gets the
	255	error that started it — an orphaned directory is the documented failure mode, and
	256	replacing the real error with the cleanup's error would hide the cause.
	257	- `InMemoryGitStorage` enforces `AlreadyExists` too. A permissive fake would let
	258	`create_repo` pass while the real adapter refused. The fake mirroring the rule is the
	259	point of having two implementations.
6a2a925docs: close Milestone 3, plan Milestone 4a8d	260	- `/api` resolves the handle without loading a profile. `handle_param` split out
	261	of `profile_for` so the repo listing route 404s on `list_repos`' own `None`. Routing
	262	it through the profile would have made that `None` unreachable and left the page and
	263	`/api` disagreeing about what an empty portfolio means — the exact duplication
	264	`architecture.md` says to watch for.
	265	- The `/api` listing is a bare array, not an envelope. Matches `/api/users/{handle}`
	266	returning a bare object. Pagination later means a wrapper and a breaking change; taken
	267	knowingly, since personal-first means a handful of repositories and there are no
	268	consumers yet.
02eb2e4feat: GitStorage port and DiskGitStorage24d	269	- `Repository::description` stays. Added unrequested and flagged; kept on review
	270	because this milestone's own "Done when" puts repositories on the profile, which
	271	makes it a consumer inside the milestone rather than speculation. Worth noting the
	272	window that closed: the repositories migration had not yet been applied to the dev
	273	database, so removing the column would have been a free in-place edit rather than a
	274	second migration.
	275
e0856ebfeat: clone a public repository over HTTP8d	276	### Milestone 4a — Clone over HTTP · done
	277
	278	`git clone` works against a public repository, for anyone, with no credentials.
	279	`GitProtocolServer` (CGI-shaped) with `GitHttpBackend` behind it, the `serve_git` use
	280	case, and three routes under `/{handle}/repos/{name}.git/`. Bodies stream both
	281	directions.
	282
	283	Verified against a real client, not only by unit test: an anonymous `git clone` of a
	284	201-ref repository returns 201 commits and 203 refs with `HEAD` matching the origin, on
	285	protocol v2 and on v0; a private repository answers 404 to an anonymous clone but 200 to
	286	its owner's browser session; `git push` is refused with 403; and unknown repo, unknown
	287	handle, missing `service`, an unknown service, a missing `.git` suffix, and a
	288	dumb-protocol object path all answer 404 while the repository page still answers 200.
8ed37b0docs: probe git http-backend's CGI contract8d	289
	290	`git http-backend`'s contract, probed against git 2.50.1 by driving the CGI from a
	291	throwaway server and cloning through it. Everything below is measured, not read.
	292
	293	#### The contract
	294
	295	- `HTTP_CONTENT_ENCODING`, not `CONTENT_ENCODING`. CGI gives only `Content-Type` and
	296	`Content-Length` unprefixed names; every other request header is `HTTP_`-prefixed, and
	297	`http-backend` looks for the prefixed one. **This is the finding that would have cost a
	298	day.** With the wrong name, `http-backend` hands the still-compressed body to
	299	`upload-pack`, which dies with `bad line length character` and the client reports
	300	`fatal: expected 'packfile'` — nothing names gzip, or the environment, anywhere in the
	301	failure. And it only happens once a repository has enough refs for the client to bother
	302	compressing: a one-ref test repo passes.
	303	- `HTTP_GIT_PROTOCOL` carries `version=2` through to `upload-pack`. Clones verified
	304	on v2 and on `protocol.version=0`, both 201 commits, both gzipped.
	305	- `GIT_PROJECT_ROOT` plus `PATH_INFO`, where `PATH_INFO` is the on-disk path relative
	306	to the root. Steid's URL and its storage layout differ — `/{handle}/repos/{name}.git/…`
	307	against `{data_dir}/{handle}/{name}.git` — so the adapter rewrites the middle segment
	308	out. `GIT_PROJECT_ROOT` is the data directory.
	309	- `GIT_HTTP_EXPORT_ALL=1` is required. Without it every repository answers `Status:
	310	404 Not Found` and `Repository not exported`, unless a `git-daemon-export-ok` marker
	311	file sits in the bare repo (confirmed: dropping that file in re-enables it).
	312	- Headers are CRLF-terminated and end at `\r\n\r\n`. No bare-LF variant was
	313	observed, but the adapter should accept one rather than hang.
	314	- `Status:` appears only on failure. Its absence means 200, and it must be
	315	translated, not forwarded as a header.
	316	- `http-backend` sets its own `Content-Type` and cache headers — `Expires: Fri, 01
	317	Jan 1980`, `Pragma: no-cache`, `Cache-Control: no-cache, max-age=0, must-revalidate`.
	318	Steid forwards them rather than inventing its own.
	319
	320	#### Decisions worth remembering
	321
	322	- `GIT_HTTP_EXPORT_ALL`, never `git-daemon-export-ok`. The marker file is git's own
	323	visibility mechanism and it looks tempting, but visibility lives in the `repositories`
	324	table and the use case is what enforces it. A marker file would be a second source of
	325	truth for the same question, free to drift from the first, and the drift direction is
	326	"private repository still clonable". Steid decides; git is told to stop asking.
	327	- `receive-pack` is refused by default — `Status: 403 Forbidden`, `Service not
	328	enabled: 'receive-pack'`, without any configuration. Convenient for 4a, but the routes
	329	still refuse writes explicitly rather than leaning on it: a default that helpfully
	330	changes is not an authorization decision.
	331	- A non-zero exit can arrive after the headers are already out. The gzip failure
	332	exited 1 having emitted a complete, successful-looking header block. So the exit code
	333	cannot gate the response — by the time it is known, the status is sent. It belongs in
	334	the log.
	335	- A missing repository is `Status: 404` with exit 0. Failure is reported in the
	336	CGI stream, not the exit code, and the two disagree in both directions.
e0856ebfeat: clone a public repository over HTTP8d	337	- The router is the allowlist. Only `info/refs`, `git-upload-pack` and
	338	`git-receive-pack` are routed. Handed any other path, `http-backend` serves
	339	dumb-protocol object files straight off disk — a read of a repository nothing
	340	authorized. Verified: `/….git/objects/info/packs` answers 404.
	341	- The endpoint is named by the route, not parsed from the path. Three routes, three
	342	literal `GitEndpoint` values, and `serve_git` rebuilds `path_info` from the validated
	343	handle and name. The string that decides authorization and the string handed to git
	344	are therefore the same string.
	345	- Existence is settled before permission. A push to a repository the actor cannot
	346	see answers 404, not 403 — a 403 would confirm a private repository by that name
	347	exists. Costs nothing to get right at the start and is invisible to test later.
	348	- `BufReader` is what makes the header/body split safe. The reader keeps whatever it
	349	read past the blank line, so handing the reader itself back as the response body
	350	carries the already-buffered first bytes of the pack with it. Parsing headers into a
	351	separate buffer and then streaming the rest would silently drop them.
	352	- The child's exit code cannot gate the response. A protocol failure exits non-zero
	353	after a complete, successful-looking header block has been written. By the time the
	354	status is known it has been sent, so the exit code goes to the log and nowhere else.
	355	- Stderr must be drained, not merely piped. An unread pipe fills and blocks the
	356	backend mid-transfer. It is read in the same task that reaps the child.
	357	- `body_limit` does not exist in `topcoat-router` 0.5.0 — the warning carried from
	358	[0001](decisions/0001-git-over-http-not-ssh.md) is stale. Bodies are read by the
	359	handler with a caller-chosen limit via `to_bytes`, and the git routes take `Body`
	360	unbuffered so no limit applies at all.
	361	- `impl<B> IntoResponse for http::Response<B>` means a handler can return its own
	362	`http_body::Body` and Topcoat re-bodies it. That is what lets the pack stream without
	363	a framework-specific body type.
8ed37b0docs: probe git http-backend's CGI contract8d	364
a814db5feat: push and clone private repositories with a token8d	365	### Milestone 4b — Push and tokens · done
	366
	367	`git push` works over HTTP for the owner, and a private repository is clonable by
	368	someone holding a token for it. `PersonalAccessToken` with both storage adapters,
	369	`issue_token` / `list_tokens` / `revoke_token` / `authenticate_token`, HTTP Basic on the
	370	git routes, and token management at `/{handle}/settings/tokens`. Decisions recorded in
	371	[0007](decisions/0007-tokens-over-http-basic.md).
	372
	373	Verified end to end, issuing the token through the UI rather than seeding one:
	374	push of 201 refs to a public repo and to a private one; clone of the private repo
	375	returning 201 commits; anonymous clone of the public repo still open with no prompt;
	376	401 with `WWW-Authenticate: Basic` for a private repo, a nonexistent repo, an
	377	unknown handle and a push advertisement alike; a wrong token challenged rather than
	378	accepted; and after revoking, both clone and push answer 401 while the public repo stays
	379	open. The token is shown once and never again on reload, the revoke button disappears
	380	from the list, and the page is 403 for anyone else.
	381
	382	#### Decisions worth remembering
	383
	384	- **`http-backend` refuses `receive-pack` by default, and Steid authorizing the push is
	385	not enough.** The symptom is a 403 that looks like Steid's own refusal but is git's:
	386	`Service not enabled: 'receive-pack'`. It needs `-c http.receivepack=true` before
	387	the subcommand. That flag is set from a `GitRequest` field the use case turns on only
	388	after the authorization check passes, so git remains a second refusal behind Steid's
	389	rather than being switched on wholesale — if the rules are ever wrong, git still says
	390	no.
	391	- The uniform 401 is what makes authenticated cloning possible at all. A git client
	392	offers a credential only after a 401, so the 4a behaviour of answering 404 for a
	393	private repository made an authenticated private clone unreachable. Extending the 401
	394	to repositories that do not exist is what keeps it from leaking which private names
	395	are real.
	396	- A bad credential falls through to anonymous rather than failing. The caller then
	397	gets the same challenge as someone who presented nothing and can try again, which is
	398	also how a stale session cookie behaves.
	399	- Basic accepts the token in the password field, or in the username with no password.
	400	Git puts it in the password; people paste it into the username. The alternative is an
	401	authentication failure with nothing to explain it.
	402	- Issuing a token deliberately does not redirect, unlike every other form here. The
	403	secret exists only in that response, and surviving a redirect would mean putting a live
	404	credential in a URL — browser history, logs, referrers. Reloading issues a second
	405	token, which is harmless and visible in the list.
	406	- Revoking someone else's token is `NotFound`, not `Forbidden`. That a token id
	407	exists but belongs to another user is not a fact worth confirming.
	408	- Tokens do not expire. A credential pasted into a machine and forgotten is worth
	409	less if it stops working silently; revocation is the control that matters.
	410	- `in_memory.rs` keeps `mod tests` in the middle of the file, like `sqlite.rs`.
	411	Appending an implementation to the end lands it inside a later impl block.
	412
338102bdocs: plan Milestone 5, with the fork/exec cost measured8d	413	#### Measured, for Milestone 5
	414
	415	Taken at the end of 4b, on a 201-commit repository, 50 runs averaged per command:
	416
	417	\| Command \| Per call \|
	418	\|---\|---\|
	419	\| `git rev-parse HEAD` \| 11.2 ms \|
	420	\| `git ls-tree -l HEAD` \| 11.7 ms \|
	421	\| `git cat-file -p HEAD:` \| 11.6 ms \|
	422	\| `git log -20 --format=…` \| 11.8 ms \|
	423	\| `git for-each-ref` \| 14.4 ms \|
	424
	425	The cost is starting git, not the query — every command lands in the same band
	426	regardless of the work it does, matching the ~13ms `git init --bare` from Milestone 3.
	427	A three-call page is therefore ~35ms of pure overhead, and a per-file last-commit column
	428	at one call per entry would be ~230ms for twenty files. This is the input
	429	[0006](decisions/0006-git-binary-behind-narrow-ports.md) asked for before reconsidering
	430	`gix` on the read path.
	431
dce0bf3feat: browse a repository's files and history8d	432	### Milestone 5 — Repo browsing · done
	433
	434	A repository is readable on the web: the file tree at a revision, a file's contents with
	435	line numbers, and the commit log. `ObjectId` / `RefName` / `RepoPath` / `EntryKind` /
	436	`TreeEntry` / `CommitSummary` in the domain, a `GitQuery` port with `DiskGitQuery` and an
	437	in-memory fake behind it, `browse_repo` and `repo_log` read models, and pages at
	438	`/{handle}/repos/{name}`, `/tree/{rev}`, `/tree/{rev}/-/{path}`, `/log` and `/log/{rev}`.
	439	The read-path decision and its upgrade ladder are in
	440	[0006](decisions/0006-git-binary-behind-narrow-ports.md#amendment--20260829-the-milestone-5-read-path).
	441
	442	Verified against Steid's own repository, hosted on Steid. A freshly created repo
	443	shows push instructions; after pushing 57 commits the page lists the tree; directories
	444	descend and breadcrumb back; `src/domain/session.rs` renders with line numbers and
	445	correct HTML escaping; the log shows 50 commits with author and relative time. Unknown
	446	revision, unknown path, `../etc/passwd`, unknown repo and unknown handle all 404, clone
	447	still works, and a private repository answers 404 to an anonymous visitor on every
	448	browse route while its owner sees it.
	449
	450	#### Decisions worth remembering
	451
	452	- `cat-file --batch-check` with the spec on stdin is the lookup primitive. It exits
	453	0 and prints `<spec> missing` for anything unresolvable, which is what makes "not
	454	found" a value read off stdout rather than an exit code to interpret. The rule the
	455	adapter follows: **a non-zero exit is always an error; absence is a marker in the
	456	output** (`missing`, `ambiguous`, `dangling`, `notdir`). The obvious alternatives are
	457	worse — `rev-parse --verify --quiet` returns 1 for an unknown ref but 128 for a missing
	458	repository, and `ls-tree` pointed at a blob is a `fatal:` for what is, to a visitor, a
	459	404. Passing the spec on stdin also means no revision or path can ever be read as a
	460	flag, whatever validation upstream does or stops doing.
	461	- `git log` in a repository with no commits is a fatal error, not empty output, hence
	462	resolving the revision first. An extra fork, in exchange for not reading meaning out of
	463	a localised stderr string.
	464	- *`%s` is git's subject, not the first line* — with no blank line in the message it
	465	joins the whole first paragraph with spaces. The adapter takes `.lines().next()` rather
	466	than trusting that.
	467	- Negative `%ct` exists in imported histories and would panic `UNIX_EPOCH + Duration`.
	468	- A symlink is indistinguishable from a file in the object store — both are blobs — so
	469	`read_blob` returns a symlink's target path as its content. Deliberate; making it
	470	`Ok(None)` would cost an extra `ls-tree` of the parent.
	471	- The empty repository is a first-class state, not an error. Steid creates
	472	repositories empty and Milestone 4 made it easy to have one never pushed to, so
	473	`default_branch` returning `None` means "no commits" and the page offers the three
	474	commands to push rather than a broken listing.
	475	- `%2F` in a revision segment survives routing. Topcoat matches on the raw path and
	476	percent-decodes after, so a slashed branch works as a single segment — which is what
	477	makes the `/-/` separator sufficient without a ref lookup.
	478	- Three agents worked in parallel on disjoint files, with the port, the fake and a
	479	non-panicking stub adapter written first so neither branch could break the other's
	480	build. The stub answering "nothing there" rather than `todo!()` is what let the pages
	481	be developed and run before the adapter existed.
	482
3dd7293feat: ship Steid as an installable binary8d	483	### Milestone 5b — Deployable by anyone · in progress
	484
	485	Distributed as a binary plus its `assets/` directory, installed by one command, behind
	486	Caddy for automatic HTTPS. `release.sh`, `install.sh`, `deploy/`, a `README.md`, and the
	487	operability the service needs: `/healthz`, `STEID_SETUP_TOKEN`, and rate limiting.
	488
	489	#### Topcoat findings, both load-bearing
	490
	491	- `topcoat::start()` already handles SIGTERM. `serve()` calls `serve_until(…,
	492	shutdown_signal())`, and that selects on Ctrl+C and SIGTERM on Unix: it stops
	493	accepting, drops the listener so a replacement process can bind the port, and drains
	494	in-flight requests up to `shutdown_timeout`. So systemd stop/restart does not cut a
	495	clone mid-pack, and no wiring was needed — the work was finding this out rather
	496	than building it.
	497	- The peer socket address is not reachable from a handler. `internal_serve` discards
	498	it at accept time (`let (stream, _remote) = accepted?;`) and never puts it on the
	499	request extensions; the context exposes only parts, method, uri, headers and
	500	extensions. Any IP-based decision in Steid is therefore header-based by necessity,
	501	not by choice, and closing that would take an upstream change.
	502
	503	#### Decisions worth remembering
	504
	505	- *The rate limiter keys on the rightmost* `X-Forwarded-For` entry.** A proxy
	506	appends the address it accepted from, so the last entry is the one the nearest proxy
	507	wrote and the only one a client cannot forge. The leftmost — what "the real client IP"
	508	usually means — is exactly the attacker-controlled one. Two proxy hops collapse clients
	509	onto the inner proxy's address, which is stricter, so being wrong that way is safe.
	510	- A global cap backs the per-key one, because without a peer address a forged key
	511	cannot be disproved. It turns key forgery from a total bypass into a modest speed-up.
	512	The cost is that a flood can lock the login form for a minute — a recoverable denial
	513	against an unrecoverable guessed password.
	514	- The limiter's map is bounded. An unbounded map keyed by attacker-controlled values
	515	is itself the denial of service; at the cap it sweeps expired entries and otherwise
	516	falls through to the global window, which is stricter rather than permissive.
	517	- glibc on bullseye, not static musl. musl failed on `ring` (Debian's `musl-gcc`
	518	rejects `-m64`), but the decisive argument is that **musl buys a dependency-free binary
	519	and Steid hard-requires `git` on PATH** — the portability is unusable. Bullseye pins the
	520	glibc floor at 2.31, covering Debian 11+ and Ubuntu 20.04+; bookworm would need 2.36
	521	and silently exclude Ubuntu 22.04.
	522	- The runtime binary links a TLS stack it never uses. `ring` ← `rustls` ← `ureq` ←
	523	Topcoat's `icon-iconify`/`tailwind`, whose `ureq` downloads the Tailwind CLI *at build
	524	time*. Those features are on the normal dependency as well as the build one, so the
	525	crypto ships too. Moving them would shrink the binary and drop an unused dependency
	526	from the attack surface. Not attempted; it is also what made the musl build fail where
	527	it did.
	528	- `STEID_SETUP_TOKEN` does not undermine [0002](decisions/0002-first-run-claim-not-config-bootstrap.md).
	529	What that ADR refused to put in configuration was the owner's password — long-lived,
	530	goes stale, ends up in a repository. This is the one-time claim secret the operator was
	531	already copying out of a log line. It is validated for strength, never printed, and
	532	ignored entirely once claimed.
	533
4ef3945feat: repository settings, README rendering, branch switcher, raw files7d	534	### Gap-filling while 5b was blocked on DNS · done
	535
	536	Built while the domain transfer was in flight, so none of it belongs to a milestone.
	537	Three things: repository settings, browse usability, and README rendering — the last of
	538	which is Milestone 6's markdown pipeline arriving early because a repository page needed
	539	it.
	540
	541	#### Repository settings — a hole, not a feature
	542
	543	Repositories were create-only. No edit, no delete, and therefore **no way to
	544	un-publish something published by accident**. Now: description and visibility are
	545	editable, and a repository can be deleted behind a type-the-name confirmation.
	546
	547	- Delete writes the row first, then the directory best-effort. An orphaned directory
	548	only blocks reusing that name and is already `create_repo`'s documented failure mode;
	549	an orphaned row is a repository that lists on the profile and 404s when clicked. The
	550	visible failure is the worse one, so the ordering avoids it.
	551	- Two different refusals, deliberately. A repository the actor may not see is
	552	`NotFound` (a 403 would confirm a private repo by that name exists); one they can see
	553	but do not own is `Forbidden`, matching `create_repo`, because the resource is public
	554	anyway. The page collapses both to 404.
	555	- Renaming is still impossible, now with a comment saying why. The bare repo lives at
	556	`{data_dir}/{handle}/{name}.git`, so a rename is a directory move that breaks every
	557	existing clone — and doing the row half only breaks them silently.
	558
	559	#### Markdown — raw HTML is structurally impossible, not merely disabled
	560
	561	- `pulldown-cmark` does not sanitise URLs. Its `escape_href` only percent-escapes, so
	562	`javascript:` would have survived into a rendered README. The renderer uses a scheme
	563	allowlist (`http`, `https`, `mailto`, `ftp`, `ftps`, `tel`) and strips ASCII control
	564	characters before the check as well as on output, because browsers strip them too and
	565	`java script:` is otherwise a live bypass.
	566	- Adding the crate with `default-features = false` turned off its `html` feature, so
	567	`push_html` does not exist in this build. The renderer therefore walks the event stream
	568	and writes every tag itself. Forced rather than chosen, and better: the emittable tag
	569	set is exactly what the writer spells out, so raw HTML cannot pass through by
	570	construction. `Event::Html` is written as text, so `<script>` is visible and inert
	571	rather than silently vanishing.
	572	- Escaping goes through `topcoat::view::HtmlContext`, the same escaper `view!` uses —
	573	not a hand-rolled one.
	574	- Smart punctuation is off: it rewrites `--flag` to an en dash, quietly corrupting CLI
	575	flags in README prose.
	576	- Relative links are rewritten into tree URLs; relative images are deliberately left
	577	alone, because a tree URL serves a page and rewriting would swap a 404 for a broken
	578	image. Pointing them at `/raw/` is the obvious follow-up now that route exists.
	579
	580	#### Browse — the switcher and raw files
	581
	582	- `for-each-ref` asks only for `%(refname)`. `%(objecttype)` is `commit` for both a
	583	branch and a lightweight tag, so the namespace is the only thing that answers
	584	branch-versus-tag.
	585	- Raw files are served as `application/octet-stream`, always — never the file's own
	586	type and never guessed from an extension — with `nosniff`, `Content-Disposition:
	587	attachment` and `default-src 'none'; sandbox`. A repository-supplied `.html` or `.svg`
	588	served as its real type on this origin is stored XSS against the viewer's session.
	589	`text/plain` was rejected because browsers render it and have been talked into sniffing
	590	it as HTML. The filename is repository content arriving in a header, so it is reduced to
	591	`[A-Za-z0-9._-]` against header injection.
	592	- The switcher costs one more fork (~13ms) on tree and log pages, measured
	593	interleaved against `ls-tree` to cancel out load — same band, confirming again that the
	594	fork is the cost. It is not called on the repository page or an empty repository.
	595
	596	#### Verified
	597
	598	Against a running instance with a deliberately hostile README: **zero real `<script>` or
	599	`<img>` tags in the output**, the markup present once as escaped inert text, the
	600	`javascript:` link stripped of its `href` while `https://example.com` survived, the table
	601	rendered, raw bytes SHA-256 identical with the headers above, the switcher listing a
	602	branch and a tag, and the Settings link visible to the owner and absent for anonymous.
	603
ef23868feat: rebuild the profile page on flat navigation7d	604	### The profile page, rebuilt · done
	605
	606	Flat navigation, per [ui.md](ui.md#the-profile-page). Tabs instead of stacked sections,
	607	one lead item distinguished by weight and space rather than size, hairlines instead of
	608	boxes, and a `/{handle}/repos` index for the tab to point at.
	609
	610	#### Decisions worth remembering
	611
	612	- Existing rows were stamped with the migration time, not left at 0. A repository
	613	pushed to for months would otherwise read "updated 56 years ago" on the very page the
	614	column exists to order. Wrong by a bounded amount and self-correcting on the first
	615	push, against wrong forever and looking broken.
	616	- The single-pin invariant lives in the use case, not in a constraint. The rule is
	617	"pinning this unpins that", and a unique index can only refuse, never unpin. The two
	618	writes are not one transaction; a crash between them leaves nothing pinned, which is
	619	the harmless direction.
	620	- `updated_at` is touched on the authorized write path, before the protocol is
	621	reached — so a clone never moves it and neither does a refused push. It records that a
	622	push was authorized, not that it succeeded; waiting for the subprocess would be a
	623	much larger change for a small gain. A failed touch is logged and does not fail the
	624	push.
	625	- The lead is picked out of the listing, not fetched separately, so the lead and the
	626	list cannot disagree about which repository is pinned.
	627	- Ordering changed from name to recency, and two existing tests had been passing by
	628	accident: everything created inside one second tied and fell back to the alphabet.
	629
	630	#### Two Topcoat traps, both silent
	631
	632	- **`let profile = …` in a module with `#[page] async fn profile` is a unit-struct
	633	pattern, not a binding.** The page's name is a unit struct in module scope. The error
	634	points at neither the page nor the shadowing.
	635	- **Forgetting `topcoat asset bundle` after `cargo build` produces a broken-looking
	636	page, not an error.** New utility classes are simply absent, so gaps collapse and type
	637	falls back to browser defaults — it reads as a design mistake. Cost one confused
	638	screenshot.
	639
0f19654feat: security headers on every response1d	640	### Security review before going public · done
	641
	642	Attempted with three blind reviewer agents; all three died to the machine sleeping, so
	643	the review was done directly instead. **Findings were verified by attacking a running
	644	instance, not by reading comments** — the codebase argues confidently for its own
	645	safety and those arguments are exactly what needed testing.
	646
	647	#### What held, demonstrated rather than assumed
	648
	649	\| Probe \| Result \|
	650	\|---\|---\|
	651	\| Private repo: page, tree, log, settings, raw, `/api` \| 404 on every surface; `/api` does not leak the name \|
	652	\| `rev=--upload-pack=touch /tmp/pwned` and five other injections \| 404, no execution \|
	653	\| Four path-traversal spellings incl. `%2e%2e` and `....//` \| 404 \|
	654	\| Login brute force \| 10 attempts then 429 \|
	655	\| Error bodies \| bare "not found", nothing internal \|
	656	\| Raw `.html` and `.svg` from a repo \| `octet-stream` + `nosniff` + `attachment` + sandbox CSP \|
	657	\| Filename `ev"il; drop.txt` in a header \| sanitised to `ev_il__drop.txt`, no header injection \|
	658	\| `<script>` in a viewed file \| escaped, zero live tags \|
	659
	660	The production cookie is `__Host-session; HttpOnly; Secure; SameSite=Lax; Path=/` —
	661	the strictest cookie form available, and it forbids a `Domain` attribute so a
	662	compromised subdomain cannot inject one.
	663
	664	A near-miss worth recording: the first check appeared to show production serving
	665	`steid-dev-session` with no `Secure`. It was a testing error — **`dotenvy` reads `.env`
	666	from the working directory**, and running the binary from the repo root picked up the
	667	gitignored dev `.env`. Verify from a neutral directory, and note the same trap applies
	668	to the deployment: the systemd unit's `WorkingDirectory=/opt/steid` means a stray `.env`
	669	there would silently override the environment file.
	670
	671	#### The one real finding: no security headers on HTML
	672
	673	Fixed with a layer, deliberately a layer rather than a per-handler concern — a page
	674	added without them would simply not have them and nothing would fail.
	675
	676	- Steid renders no JavaScript at all, not a script tag on any page, so
	677	`default-src 'none'` is a policy the product can genuinely keep. That is far stricter
	678	than a typical CSP and worth defending: if a feature ever needs script, weakening it
	679	should be a deliberate decision.
	680	- `'unsafe-inline'` is granted for styles only, and only because Topcoat's icon
	681	macro emits `style="vertical-align: -0.125em"`. A framework constraint, not a choice.
	682	- `Referrer-Policy: no-referrer`, not the usual `strict-origin-when-cross-origin`: a
	683	private repository's URL contains its name, and a README may link anywhere, so a
	684	referrer would hand that name to whatever the visitor clicked.
	685	- Headers are set with `entry().or_insert()`, never `insert()` — the raw endpoint's own
	686	stricter `default-src 'none'; sandbox` must not be relaxed by a blanket overwrite.
	687	Verified that it survives.
	688
	689	#### Not covered, and why
	690
	691	- The member-but-not-owner path could not be demonstrated. There is no registration,
	692	so a second account cannot exist until Milestone 7. It is covered by use-case tests and
	693	nothing else — re-verify for real the moment a second account is possible.
	694	- No automated test asserts the headers. There is no HTTP-level test harness in this
	695	project, so a regression here would be silent. That is a gap, not a decision.
	696	- No dependency audit (`cargo audit` was not run), and no review of the deployment
	697	scripts beyond the earlier container dry-run.
	698
4414bbadocs: record the first real deployment22h	699	### Deployed · jpgill.dev, 2026-09-04
	700
	701	Steid runs on the public internet at https://jpgill.dev, on AWS Lightsail (Debian 13,
	702	x86_64, 1 GB), behind Caddy with a Let's Encrypt certificate, hosting its own source.
	703	Installed with `install.sh --tarball`, since the instance that will serve the releases is
	704	the one being installed.
	705
	706	#### What the first real deployment taught
	707
	708	- A domain transfer moves the registrar, not the nameservers. The transfer to Amazon
	709	Registrar completed, the Route 53 zone held the right records, and every public resolver
	710	returned nothing — because the `.dev` registry still delegated to the old provider's
	711	nameservers. Diagnosed with `dig +trace`, which shows the delegation the world actually
	712	follows rather than the zone you are looking at.
	713	- The domain was `jpgill.dev`, not `jpgilldev.com`. Inferred from an email address and
	714	never confirmed, and by then it was baked into `install.sh`'s release URL and the
	715	systemd unit. Ask what the domain is.
	716	- `.dev` is HSTS-preloaded. Browsers refuse plain HTTP with no click-through, so the
	717	certificate is not optional — until Caddy has one the site is simply unreachable.
	718	- The uniform 401 cost real time. Pushing to a mistyped handle answered
	719	`Authentication failed` rather than "no such repository", because
	720	[0007](decisions/0007-tokens-over-http-basic.md) deliberately makes an absent repository
	721	indistinguishable from a private one. That trade was recorded as costing "a prompt on a
	722	typo"; in practice it cost ten minutes and a confident wrong diagnosis, with someone
	723	watching who knew the design. A stranger has nobody to ask.
	724	- An upgrade silently discarded the operator's Caddyfile. `install.sh` kept
	725	`steid.env` across a re-run but rewrote the Caddyfile unconditionally, so a hand-added
	726	`www` redirect vanished on the next upgrade and took the hostname with it. Now written
	727	on first install only, with `--force-caddyfile` and `--www`. Found by testing the
	728	upgrade path rather than waiting for it to happen.
	729	- The upgrade path works and is verified: claim, database, repositories, `steid.env`
	730	and Caddyfile all survive `install.sh` re-run against a newer tarball.
	731
	732	#### Renaming a handle, done by hand
	733
	734	`current.md` recorded a rename as "a directory move, not a row update". That was exercised
	735	for real, renaming `jpgilldev` to `jamesgill` on the live instance: **one `UPDATE orgs SET
	736	name` and one `mv` of `{data_dir}/{handle}/`**. Everything else — users, repositories,
	737	tokens, sessions — keys off ids, so nothing else moved, and the account, password and
	738	access token all survived.
	739
	740	So a rename feature is genuinely two writes. What makes it more than that is the
	741	consequence: every existing clone URL breaks, and there is no redirect from the old
	742	handle. That is the part to design, not the mechanics.
	743
5d3dfa5feat: a global top bar, and pages choose their own width22h	744	### The shell: top bar and per-page widths · done (2026-09-05)
	745
	746	The root layout gained a slim global top bar — wordmark to `/`, and either "Sign in"
	747	or `@handle` / Settings / Sign out — and stopped imposing a width. Pages now choose
	748	their own column via two components in `layout.rs`: `narrow` (48rem — profile, forms,
	749	settings) and `wide` (80rem — tree, blob, log, the repo page). Verified in the
	750	browser across visitor and owner states, including sign-out.
	751
	752	#### Decisions worth remembering
	753
	754	- A slim bar plus contextual tabs, deliberately not an app shell. The reasoning
	755	lives in [ui.md](ui.md#the-shell); the short form is that Steid's first audience is
	756	an anonymous reader of someone's site, and GitLab-style rail chrome tells that
	757	visitor they've landed in an admin tool.
	758	- A `#[layout]` may take `cx: &Cx` alongside `slot` — both recognized by name, no
	759	other parameters. Documented in the vendored `topcoat-router-macro` docs, not
	760	obvious from the README example.
	761	- The layout imposes no width; pages wrap themselves. Same philosophy as request
	762	helpers being functions: a page that forgets a container renders full-bleed, which
	763	is immediately visible, rather than silently inheriting a wrong one.
	764	- The top bar costs an identity lookup on every page render (session hash plus a
	765	user row). Fine over local SQLite; worth remembering if page queries are ever
	766	counted.
	767
0aca94efeat: a repository is one place, and its landing page says what it is17h	768	### The repository landing page · done (2026-09-05)
	769
	770	`/{handle}/repos/{name}` became two columns — the file list and README on the left, an
	771	About sidebar on the right — and every repository page (tree, blob, log) picked up the
	772	same header and `Code` / `Commits` tab strip. New: a toolbar row carrying the revision
	773	switcher and branch/tag counts, a latest-commit bar, an About block with the
	774	description and detected licence, a facts list (commits, branches, tags, latest tag,
	775	pushed), and the clone URL moved into the sidebar.
	776
	777	The layout and the map of where the next features slot in are in
	778	[ui.md](ui.md#the-repository-page). What is here is what the next session should not
	779	have to rediscover.
	780
	781	Verified with the app running from a worktree on port 3100: this repository's own
	782	history pushed into it with two annotated tags and three branches, plus an empty
	783	repository and one with no README and no licence. Screenshots taken headless at 1280px
	784	and 800px, in both colour schemes, of the landing page, the empty and sparse states, a
	785	tree subpath, a blob and the log; the owner's view (with the Settings button) checked
	786	signed in. `cargo test` 467 passing, clippy clean.
	787
	788	#### Decisions worth remembering
	789
	790	- The subprocess count was measured, not estimated. A `git` shim on `PATH` logging
	791	every invocation: 15 processes for a repository with a README and a licence, 10
	792	without them, 1 for an empty one — up from 7. Worth repeating the trick; it took
	793	two minutes and contradicted a careful hand-count.
	794	- The description has exactly one home, and it is the sidebar. Putting it in the
	795	header too makes the header tallest on the repositories with the most to say, which
	796	pushes the code below the fold on exactly the pages that deserve it least.
	797	- `repo_summary` takes the revision and the root listing the page already read. A
	798	self-contained use case would have spent two more processes re-reading what the caller
	799	had in hand. The five calls it does make run under one `tokio::try_join!`.
	800	- `organise_refs` was split out of `list_refs` so the landing page gets the counts
	801	and the switcher's list from one `for-each-ref`. Two places deciding ref order is two
	802	places to change it.
	803	- **A `#[component]`'s name is a unit struct in module scope, and the copied-in
	804	components are in that scope too.** A parameter named `label` inside `repo.rs` does
	805	not bind — it parses as the `label` component's unit struct, and the error says
	806	"expected `str`, found `label`" without naming the component. The fix was renaming the
	807	parameter to `term`. This is the same trap `CLAUDE.md` records for pages; registry
	808	components widen it to every file that imports one.
	809	- `bg-muted` is not a token. Three `<pre>` blocks have been rendering with no
	810	background since they were written, silently — the exact failure `ui.md` describes for
	811	Tailwind classes the build never ships. `bg-surface` is the token. Two were fixed here;
	812	`token.rs` still has one.
	813	- The clone URL wraps rather than scrolls. In an 18rem column an `overflow-x-auto`
	814	URL looks like a truncated one, and the part hidden is the repository's own name.
	815	- Light mode was checked by flipping the layout's `class="dark"` and rebuilding,
	816	because there is no toggle. Nothing was wrong on these pages. That is the cheapest way
	817	to check it until a toggle exists, and it is worth doing before each UI step rather
	818	than after several.
	819
ab7fea9chore: plans setup1mo	820	---
	821
	822	## Reference: what attempt #2 proved
	823
	824	Not this repo's progress. This is a catalogue of what was built and verified working
	825	in `steid-backup-2026-07-31`, so the rebuild can crib rather than rediscover.
	826
	827	Final state: single crate, ~4,200 LOC, 60 passing tests, five milestones.
	828
	829	### Identity
	830
	831	Domain model (User, Organization, Membership, Actor, Role), `Email` and
	832	`PasswordHash` value objects, typed IDs, `DomainError`, four repository ports with
	833	in-memory and SQLite implementations each. `RegistrationPolicy` (Personal / Invite /
	834	Open) driving which routes exist. Argon2 hashing behind a `PasswordHasher` port with a
	835	stub for tests. Use cases: `bootstrap_owner`, `register_user`, `login`, `create_invite`.
	836	Signed-cookie sessions via an `AuthUser` extractor.
	837
	838	Gotcha: organizations must be saved before users — the FK runs that direction.
	839	Both `bootstrap_owner` and `register_user` had to be fixed for this.
	840
	841	### Repo model
	842
	843	`Repository` entity, `RepoId`, `Visibility` (Public/Private), `RepoRepository` port,
	844	migration `006_create_repositories.sql`. `create_repo` use case validates the name,
	845	rejects duplicates, and initialises the bare repo on disk in the same call. Bare repos
	846	live at `{data_dir}/{org}/{repo}.git`, `data_dir` defaulting to `./data`. Repos are
	847	created empty, no initial commit, like GitHub.
	848
	849	### Git over SSH
	850
	851	`GitStorage` port (`init_bare`, `repo_path`) with `DiskGitStorage` shelling out to
	852	`git init --bare`. `GitProtocolServer` port (`upload_pack`, `receive_pack`) with
	853	`GitBinary` spawning `git upload-pack` / `git receive-pack` via
	854	`tokio::process::Command` and pumping stdio with `tokio::io::copy`.
	855
	856	`serve_clone` and `serve_push` use cases enforce visibility and actor checks **before
	857	any protocol byte flows** — that ordering is the whole point of putting them in the
	858	application layer.
	859
	860	#### SSH channel bridging
	861
ca76e1bdocs: fix milestone cross-references after the reorder24d	862	The fiddly part, and worth re-reading if SSH ever returns as a transport
	863	(milestone 8+ — [0001](decisions/0001-git-over-http-not-ssh.md) chose HTTP):
ab7fea9chore: plans setup1mo	864
	865	- Store `Channel<Msg>` per `ChannelId` in the handler's map on `channel_open_session`
	866	- On `exec_request`, take the channel, split it with `into_stream()` +
	867	`tokio::io::split`
	868	- Take stderr via `make_writer_ext(Some(1))` before `into_stream()` — that call
	869	consumes the channel, so the order is not optional
	870	- No `data()` or `channel_eof()` handlers needed once the streams are split
	871
	872	An earlier iteration used mpsc channels, custom `ChannelReader`/`ChannelWriter`, and a
	873	`spawn_blocking` thread. All of it was deleted and the result was simpler.
	874
	875	### SSH key auth and authorization
	876
	877	`SshKey { id, user_id, name, fingerprint, openssh }` + port, migration
	878	`007_create_ssh_keys.sql` (`fingerprint` UNIQUE). Fingerprints are SHA256 via
	879	`russh::keys::ssh_key::PublicKey::fingerprint(HashAlg::Sha256)`, stored as `SHA256:…`.
	880	`add_ssh_key` parses the openssh blob, dedupes on fingerprint, and re-encodes to a
	881	canonical form before storing.
	882
	883	`auth_none` rejects. `auth_publickey` fingerprints the offered key, looks it up, and
	884	on a match stores `user_id` on the handler; `exec_request` builds the real `Actor`
	885	from it.
	886
	887	Authorization rules as shipped:
	888
	889	\| Operation \| Requirement \|
	890	\|---\|---\|
	891	\| Clone, public repo \| open \|
	892	\| Clone, private repo \| any membership in the repo's org \|
	893	\| Push \| `Role::Owner` membership in the repo's org \|
	894
	895	Web UI at `/{owner}/keys` — owner-only, lists fingerprints, accepts openssh via
	896	textarea, revokes per-row.
	897
	898	Verified end-to-end: clone with an unregistered key → `Permission denied` (exit
	899	128); register via web UI → clone and push both succeed; second unregistered key →
	900	rejected at auth; revoke via web UI → subsequent clone rejected at auth.
	901
	902	### Security notes
	903
	904	Attempt #2 ran with a named, deliberate backdoor between milestones: SSH accepted
	905	any connection and passed a placeholder `Actor` (`UserId("ssh-anonymous")`), leaving
	906	push open to anyone who could reach the port. It was recorded with an explicit
	907	tightening point (`ssh.rs::exec_request`) and a closing milestone, and it did close.
	908
	909	That practice is worth keeping. When this attempt opens a hole to make progress, name
	910	it, name the line that closes it, and name the milestone.
	911
	912	### Never built
	913
	914	Repo browsing (tree/blob/log), HTTP smart protocol, personal access tokens, flash
	915	messages, issues, PRs, blogs, pages, project showcases. Milestones 5–8 in
	916	[ROADMAP.md](ROADMAP.md) are all greenfield.