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