hanna/fabrica

feat: initial commit

870bb7b · hanna committed on 2026-07-25

Signed by hannaSSH key fingerprint: SHA256:4g9cWhkAAw8gwqhJUcVbSnGEvdGwklW+1Aa/fMUu59k

CLAUDE.md +175 −0

spec.md +1166 −0

+# CLAUDE.md
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+## Project status: greenfield
+The repository currently contains **only `spec.md`** — a 1166-line implementation contract. No
+code, flake, crates, or `Cargo.toml` exist yet. `spec.md` is the source of truth: read it before
+doing anything. Where it says **MUST**, treat it as a hard requirement; **SHOULD** deviations
+must be logged in `docs/decisions.md` (once that file exists).
+`fabrica` is a self-hosted git server: a single Rust binary that serves repos over HTTPS (read)
+and SSH (read + write) with a fast, themeable, htmx-driven web UI. Private by default, no sign-up.
+Build order is fixed — see **Implementation phases** below.
+## What this project deliberately is NOT
+Do not build: issues, pull/merge requests, merge machinery, GitHub-style orgs, web sign-up/self-
+registration, forks, stars, activity feeds, wikis, releases, git-LFS, webhooks, federation. When
+a feature is ambiguous, choose the simpler behaviour. CI is **deferred** — design the seams for it
+(reserve the `runs` nav slot, `/-/runs` routes, `runs`/`jobs` tables, `post-receive` hook entry
+point) but ship them inert behind `ui.show_runs = false`. Do not implement CI until phase 18 is done.
+## Commands
+None run today (no code). Once the workspace exists, the **quality gate** below must pass after
+every unit of work — no exceptions, no deferrals:
+```
+cargo fmt --all -- --check
+cargo check --workspace --all-targets
+cargo clippy --workspace --all-targets -- -D warnings
+cargo test --workspace
+```
+A `justfile` must expose `just check` running all four; use it. `nix flake check` is the superset
+(`checks.{clippy,fmt,test,deny,doc}`) and must be green before any phase is called done. Tests use
+`cargo-nextest` in the dev shell; keep the full suite under two minutes. `cargo test` alone must
+suffice with no external services (Postgres tests are feature-gated behind `postgres-tests` /
+`FABRICA_TEST_POSTGRES_URL`; integration tests gate on `git`/`ssh` being present and skip cleanly).
+Toolchain: Rust **nightly** via fenix (pinned in `flake.lock`), edition 2024, resolver 3. Nightly
+is a currency preference only — **no `#![feature(...)]` gates**; code must compile on stable.
+Workspace lints forbid `unsafe_code`; deny `clippy::all`, `unwrap_used`, `panic`, `todo`.
+`unwrap_used` may be locally allowed inside `#[cfg(test)]`.
+## Architecture
+Single root package `fabrica` (`src/main.rs` = arg-parse → dispatch into `cli`, nothing else).
+All library code lives in `crates/` with **unprefixed** names. Dependency direction is strictly
+one-way and enforced:
+```
+model  ←  store / git / auth  ←  web / api / ssh / cli
+```
+`model` depends on nothing in-tree; **no crate may depend on `web`**. Never name a crate `core`,
+`std`, `alloc`, `test`, or `proc_macro` (sysroot collisions).
+Crates: `config` (figment TOML+env), `store` (sqlx, SQLite+Postgres), `model` (domain types, no
+I/O), `git` (libgit2 reads + subprocess pack transport), `highlight` (inkjet/tree-sitter),
+`auth` (argon2id, sessions, JWT), `mail` (lettre), `ssh` (russh), `web` (axum + maud + htmx),
+`api` (`/api/v1` JSON), `cli` (clap).
+### The central architectural fact: git plumbing is split
+`libgit2` (via `git2`) is **client-only for transport** — it has no server-side `upload-pack`/
+`receive-pack`. So:
+- **In-process `git2`**: browsing, log, diff, refs/trees/blobs, signature extraction, `init_bare`.
+- **Spawned `git` subprocess**: clone/fetch (`git upload-pack --stateless-rpc`), push
+  (`git receive-pack`), maintenance (`git gc`/`git repack`). One code path:
+  `git::pack::spawn(kind, repo_path, env, stdio)`.
+Therefore the `git` binary **MUST** be on `PATH` at runtime — the Nix derivation wraps the binary
+with git on PATH, the Dockerfile verifies `git --version` at build time. Resolve it once at
+startup (config `git.binary`, require ≥ 2.41), surface in `/healthz` and `fabrica doctor`.
+Pack transport rules that are easy to get wrong: **authorize before spawning** (the subprocess
+never makes an access decision); **stream both directions, never buffer a pack in memory**; HTTP
+push (`git-receive-pack`) returns a deliberate `403` pointing at the SSH URL; dumb HTTP is
+disabled. A reverse proxy in front **must not buffer** `/git-upload-pack` bodies or clones stall.
+### Repos are stored by id, not name
+On disk: `{storage.repo_dir}/{id[0..2]}/{id}.git` where `id` is a lowercase ULID. The **database
+is the only name→path authority**, so renames and group moves are metadata-only. The tree is not
+human-browsable by design — `fabrica repo path <user> <name>` resolves it for operators.
+### Groups make repo paths variable-length → the `/-/` separator
+Group nesting means repo paths have unknown depth. Routes disambiguate with the GitLab `/-/`
+convention: everything before `/-/` is the repo path, everything after is the view
+(`/{owner}/{path..}/-/blob/{ref}/{p..}`). Path resolution: look up `repos` by `(owner_id, path)`;
+on miss look up `groups` and render a group listing; on miss `404`.
+### Store portability (SQLite + Postgres, one schema)
+Do **not** use sqlx compile-time-checked macros against two dialects. Define a `Store` trait with
+`Sqlite`/`Postgres` impls (or runtime queries over `AnyPool`); every statement stays in the
+portable SQL subset. Timestamps are `BIGINT` unix **milliseconds** UTC (no `DATETIME`/`TIMESTAMPTZ`).
+Ids are `TEXT` ULIDs (26 chars, lexicographically sortable — use for ordering). No `AUTOINCREMENT`/
+`SERIAL`. Case-insensitive uniqueness via a normalized `*_lower` column + unique index, not collation.
+Migrations: `migrations/{sqlite,postgres}/NNNN_name.sql`, selected at runtime via `sqlx::migrate!`.
+### Permission model: one function, exhaustively tested
+```rust
+pub enum Access { None, Read, Write, Admin }
+pub fn access(viewer: Option<&Viewer>, repo: &Repo) -> Access
+```
+Order: admin → owner → explicit collaborator row → public+anonymous-allowed = Read → None.
+`None` on a private repo **MUST render 404, not 403** — never leak existence (this holds for the
+web UI and the API alike). The `access()` test is the security-critical one: enumerate the full
+matrix (viewer kind × visibility × collaborator permission), don't sample it.
+### Highlighting: line-addressable, per-side in diffs
+`inkjet`/tree-sitter. Two hard requirements drive the design: **every emitted line must be
+independently valid balanced HTML** (spans crossing a newline are split and the capture stack
+re-opened on the next line — see `fix(highlight): reopen capture stack across line breaks`), and
+diffs highlight the **pre- and post-image of each file as whole documents**, never per-hunk, then
+zip lines with hunks. Stable theme-driven class names (`hl-keyword`, `hl-string`, …) mapped from
+tree-sitter captures in one table. Highlighting **MUST NOT** be able to fail a page render — skip
+oversized/binary/minified files and fall back to escaped plain text on any grammar panic.
+Language resolution has a fixed precedence (§8.1): `.gitattributes fabrica-language` > `linguist-
+language` > shebang > modeline > exact filename > extension (longest match) > plain text.
+### Web UI: server-rendered, htmx-enhanced, no build step
+`axum` + `maud` (compile-time-checked templates) + **htmx 2 vendored into `assets/`** (no CDN, no
+npm, no WASM, no SPA). Hand-written vanilla JS is capped at < 200 lines total in `assets/fabrica.js`
+(mobile drawer, theme picker, clipboard, keyboard shortcuts). **Every interactive element must work
+without JavaScript** — htmx enhances links/forms, it is not the substrate. Handlers detect the
+`HX-Request` header and return a partial, else the full page; write this as one `respond(page,
+partial)` helper so no route drifts.
+Theming re-brands with no rebuild: `assets/base.css` is structure-only with **no literal colours**,
+written entirely against custom properties. Themes are single CSS files defining `--fb-*` tokens;
+drop one in `ui.themes_dir` and `SIGHUP` to load it. A theme that sets only the documented `--fb-*`
+tokens MUST yield a complete UI — that is the themeability acceptance test. No web fonts, no network
+requests from any page.
+## CLI operates directly on the store — no IPC with the server
+Every `fabrica` subcommand touches the store/filesystem directly (SQLite WAL and Postgres both
+tolerate concurrent writers); there is no IPC with a running `serve`. Mutations a live server
+caches (repo rename/delete, user disable) bump a `cache_epoch` row that `serve` polls. `serve` runs
+in the **foreground** by default (correct for systemd/Docker); there is no `stop` subcommand —
+signal the pid. Destructive commands prompt on a TTY and require `--yes` otherwise.
+## Working conventions
+- **Commits**: Conventional Commits, one logical change each, committed **as work happens** (not
+  batched). Scope is the crate/area: `feat(git):`, `fix(web):`, `build(nix):`. Imperative, lowercase,
+  ≤ 72 chars, no trailing period. **Never commit with failing checks** — a needed `#[allow]` is
+  justified in the commit body.
+- **Errors**: `thiserror` (one enum per crate) in libraries; `anyhow` only at the binary boundary
+  (`main.rs`, CLI). `tracing` with structured fields — request-id span per HTTP request, session
+  span per SSH connection. User-facing error pages are templated/themed, never expose internals
+  (detail → log with the request id, page shows the id).
+- **Docs**: `docs/decisions.md` is a running log (date, decision, alternatives, rationale). Seed it
+  with the decisions the spec already makes (subprocess pack transport, id-based repo dirs, `/-/`
+  separator, epoch-ms timestamps, `serve` with no `stop`, linear search). Update on any deviation.
+## Implementation phases (build in this order)
+Each phase ends with the full gate green and its own commits; do not start a phase before the
+previous is clean:
+. Scaffold (flake + fenix + crane, empty crates, lints, justfile, MPL-2.0) 2. config 3. store
+. auth 5. git reads 6. highlight 7. git signatures 8. cli core 9. mail 10. web shell 11. web repo
+views 12. web commit view 13. pack transport 14. ssh 15. search 16. api 17. deployment 18. polish.
+Then, and only then, CI (HCL config via `hcl-rs`, Docker execution via `bollard`).

+# fabrica — implementation spec
+`fabrica` (Latin: *forge*) is a self-hosted git server. Single binary, private by default, no
+sign-up. It serves repositories over HTTPS (read) and SSH (read + write) and provides a fast,
+themeable web UI for browsing code.
+This document is the implementation contract. Follow it section by section. Where it says
+**MUST**, treat it as a hard requirement; where it says **SHOULD**, deviate only with a note in
+`docs/decisions.md`.
+---
+## 1. Goals and non-goals
+### Goals
+- Host git repositories for a small, fixed set of users (personal / small-team private instance).
+- Browse code, history, diffs, branches, and tags in a UI that is fast on desktop and mobile.
+- Syntax highlighting everywhere code appears, including inside diffs.
+- Show whether each commit is cryptographically signed, via SSH or GPG.
+- Organize repositories under nested, user-owned groups.
+- Re-theme and re-brand without recompiling.
+- One binary, one config file, one data directory.
+### Non-goals (do not build these)
+- **Issues.** Not planned.
+- **Pull requests / merge requests.** Not planned. No merge machinery, no review flow.
+- **Organizations** in the GitHub sense. Repos belong to a user; groups provide the hierarchy.
+- Web sign-up, public registration, or self-service account creation of any kind.
+- Forks, stars, followers, activity feeds, notifications, wikis, releases-as-a-feature,
+  git-LFS, webhooks, mirroring, federation.
+- Being Forgejo/Gitea/GitLab/GitHub. When a feature is ambiguous, choose the simpler behaviour.
+### Deferred (design for, do not implement)
+- **CI.** Config in **HCL** (not YAML), Docker as the execution backend for stages and jobs.
+  Reserve the `runs` nav slot, the `/-/runs` route family, the `runs`/`jobs` tables, and the
+  `post-receive` hook entry point. Ship them inert behind `ui.show_runs = false`.
+---
+## 2. Toolchain, build, and repository layout
+### 2.1 Workspace
+Root package `fabrica` produces the single binary. All library code lives in `crates/`, with
+**unprefixed crate names**:
+```
+fabrica/
+├── flake.nix
+├── flake.lock
+├── Cargo.toml                # workspace root, package `fabrica`, src/main.rs only
+├── Cargo.lock
+├── rust-toolchain.toml
+├── src/main.rs               # arg parse -> dispatch into `cli`; nothing else
+├── crates/
+│   ├── config/               # TOML + env config load, validation, path resolution
+│   ├── store/                # database: schema, migrations, queries (SQLite + Postgres)
+│   ├── model/                # shared domain types, no I/O
+│   ├── git/                  # libgit2 reads, attributes, signatures, pack transport spawn
+│   ├── highlight/            # inkjet/tree-sitter, language resolution, line-aware output
+│   ├── auth/                 # argon2id, sessions, JWT, permission checks
+│   ├── mail/                 # SMTP + templates
+│   ├── ssh/                  # russh server, publickey auth, exec -> pack processes
+│   ├── web/                  # axum router, maud templates, htmx partials, assets, theming
+│   ├── api/                  # /api/v1 JSON handlers
+│   └── cli/                  # clap command tree, all subcommands
+├── assets/                   # embedded defaults (base.css, theme.css, htmx.min.js, icons)
+├── migrations/
+│   ├── sqlite/
+│   └── postgres/
+├── docs/
+│   ├── configuration.md
+│   ├── theming.md
+│   ├── deployment.md
+│   └── decisions.md
+├── Dockerfile
+├── compose.yml
+├── fabrica.example.toml
+└── LICENSE                   # MPL-2.0
+```
+Naming constraints: **MUST NOT** name a crate `core`, `std`, `alloc`, `test`, or `proc_macro` —
+these collide with sysroot crates. `git` and `api` are fine.
+Dependency direction is strictly one-way: `model` ← `store`/`git`/`auth` ← `web`/`api`/`ssh`/`cli`.
+No crate may depend on `web`. `model` depends on nothing in-tree.
+### 2.2 Toolchain
+- Rust **nightly** via **fenix**, pinned through `flake.lock`. Nightly is a currency preference,
+  not a feature dependency: the code **MUST NOT** use `#![feature(...)]` gates. It should compile
+  on current stable too; treat any nightly-only construct as a bug.
+- `rust-toolchain.toml` declares `channel = "nightly"` with components `rustfmt`, `clippy`,
+  `rust-src`, `rust-analyzer` for non-Nix users.
+- Edition 2024, resolver 3.
+- Workspace lints in root `Cargo.toml`:
+```toml
+[workspace.lints.rust]
+unsafe_code = "forbid"
+missing_docs = "warn"
+[workspace.lints.clippy]
+all = { level = "deny", priority = -1 }
+pedantic = "warn"
+unwrap_used = "deny"
+expect_used = "warn"
+panic = "deny"
+todo = "deny"
+```
+`unwrap_used` is denied in library code; `#[cfg(test)]` blocks may allow it locally.
+### 2.3 Nix flake
+Inputs: `nixpkgs` (unstable), `fenix`, `crane`, `flake-utils` (or `flake-parts` — pick one and
+be consistent).
+The flake **MUST** expose:
+- `packages.default` — the wrapped binary.
+- `packages.fabrica` — alias of the above.
+- `packages.container` — `pkgs.dockerTools.buildLayeredImage`, as a Nix-native alternative to
+  the `Dockerfile`.
+- `devShells.default` — toolchain + `sqlx-cli`, `sqlite`, `postgresql`, `git`, `openssh`,
+  `gnupg`, `cargo-nextest`, `cargo-deny`, `just`.
+- `checks.{clippy,fmt,test,deny,doc}` — so `nix flake check` runs the full gate.
+- `formatter` — `nixpkgs-fmt` or `alejandra`.
+Build shape:
+```nix
+craneLib = (crane.mkLib pkgs).overrideToolchain fenixToolchain;
+commonArgs = {
+  src = craneLib.cleanCargoSource ./.;
+  strictDeps = true;
+  nativeBuildInputs = [ pkgs.pkg-config pkgs.makeWrapper ];
+  buildInputs = [ pkgs.libgit2 pkgs.zlib pkgs.openssl ];
+  # use system libgit2 rather than the vendored copy
+  LIBGIT2_NO_VENDOR = "1";
+};
+cargoArtifacts = craneLib.buildDepsOnly commonArgs;
+```
+The final derivation **MUST** wrap the binary so the git plumbing is always reachable:
+```nix
+postInstall = ''
+  wrapProgram $out/bin/fabrica \
+    --prefix PATH : ${lib.makeBinPath [ pkgs.git ]}
+'';
+```
+Also expose a **NixOS module** at `nixosModules.default` providing `services.fabrica` with
+`enable`, `settings` (TOML-typed, rendered via `pkgs.formats.toml`), `user`, `group`,
+`dataDir`, `environmentFile` (for secrets), a hardened `systemd.services.fabrica` unit
+(`DynamicUser` off, `StateDirectory=fabrica`, `ProtectSystem=strict`, `NoNewPrivileges`,
+`AmbientCapabilities=CAP_NET_BIND_SERVICE` only if a privileged port is configured), and
+`openFirewall`.
+---
+## 3. Git layer (`crates/git`)
+### 3.1 Division of responsibility — read this carefully
+`libgit2` (via `git2`) is the object-model library: refs, trees, blobs, commits, revwalks,
+diffs, attributes, signature extraction. **libgit2 does not implement the server side of the
+pack protocol.** There is no `upload-pack`/`receive-pack` in libgit2 — it is client-only for
+transport. Therefore:
+| Concern | Implementation |
+| --- | --- |
+| Browsing, log, diff, blame-free reads | `git2` in-process |
+| Signature extraction | `git2` (`Repository::extract_signature`) |
+| Attribute resolution | own resolver over tree blobs (§3.5) |
+| Clone/fetch (HTTPS) | spawn `git upload-pack --stateless-rpc` |
+| Push (SSH) | spawn `git receive-pack` |
+| Fetch over SSH | spawn `git upload-pack` |
+| Repo creation, gc, repack | `git2` for init; spawn `git gc`/`git repack` for maintenance |
+`git` **MUST** be present on `PATH` at runtime. Resolve it once at startup:
+- config key `git.binary` (default `"git"`),
+- resolve via `which`, verify `git --version` >= 2.41,
+- fail startup with a clear, actionable error if absent.
+Record the discovered path and version in `/healthz` output and in `fabrica doctor`.
+### 3.2 On-disk layout
+Repositories are stored by **id**, not by name, so renames and group moves never touch the
+filesystem:
+```
+{storage.repo_dir}/{id[0..2]}/{id}.git
+```
+where `id` is a lowercase ULID. The database is the only name→path authority. Document the
+tradeoff in `docs/decisions.md`: the tree is not human-browsable, in exchange for atomic,
+metadata-only renames. `fabrica repo path <user> <name>` prints the resolved directory for
+operators.
+Repo creation:
+. `git2::Repository::init_bare`.
+. Set `HEAD` to `refs/heads/{default_branch}` (config: `instance.default_branch`, default `main`).
+. Write config: `core.logAllRefUpdates=true`, `receive.denyNonFastForwards=false`,
+   `gc.auto=0` (maintenance is driven by fabrica, not by pushes).
+. Install hooks (§3.4).
+. Insert the DB row in the same transaction; on any failure, remove the directory.
+Deletion moves the directory to `{storage.data_dir}/trash/{id}-{timestamp}.git` and deletes the
+row; a `fabrica gc --trash-older-than 30d` command reaps it. `repo del --purge` skips the trash.
+### 3.3 Pack transport
+Everything below shares one code path: `git::pack::spawn(kind, repo_path, env, stdio)`.
+**Common rules**
+- Never interpolate a user-supplied path into a shell. Use `tokio::process::Command` with
+  explicit args, no shell.
+- Authorize *before* spawning. The subprocess never makes an access decision.
+- Set on every child: `GIT_DIR={resolved path}`, `GIT_PROTOCOL` passed through when the client
+  requested v2, `GIT_TERMINAL_PROMPT=0`, `GIT_CONFIG_NOSYSTEM=1`, `HOME={data_dir}/tmp`,
+  and the identity vars `FABRICA_USER_ID`, `FABRICA_USER_NAME`, `FABRICA_REPO_ID`,
+  `FABRICA_KEY_ID` (for hook consumption).
+- Enforce `git.max_pack_size_bytes` (default 512 MiB) and `git.transport_timeout_secs`
+  (default 3600); kill the process group on timeout and log it.
+- Clean up: always `kill_on_drop(true)`; reap children.
+**HTTPS smart protocol (read-only)**
+Implement only the v0/v1/v2 smart paths; dumb HTTP **MUST** be disabled.
+```
+GET  /{owner}/{path}.git/info/refs?service=git-upload-pack
+POST /{owner}/{path}.git/git-upload-pack
+```
+- `info/refs`: spawn `git upload-pack --stateless-rpc --advertise-refs {dir}`, prefix the body
+  with the pkt-line `# service=git-upload-pack\n` + flush, `Content-Type:
+  application/x-git-upload-pack-advertisement`, `Cache-Control: no-cache`.
+- `git-upload-pack`: stream the request body to the child's stdin and the child's stdout back as
+  the response body, `Content-Type: application/x-git-upload-pack-result`. **Stream both
+  directions** — never buffer a pack in memory. Support `Content-Encoding: gzip` on the request.
+- Also accept the same routes without the `.git` suffix.
+- `POST /{owner}/{path}.git/git-receive-pack` and `info/refs?service=git-receive-pack`
+  **MUST** return `403` with a plain-text body explaining that push over HTTPS is disabled and
+  giving the correct SSH remote URL. This is a deliberate, discoverable failure.
+- Private repos require auth: HTTP Basic with username + (password or API token), or a session
+  cookie. Anonymous access to a private repo returns `401` with
+  `WWW-Authenticate: Basic realm="fabrica"`.
+**SSH (read + write)**
+`crates/ssh` runs a `russh` server.
+- Host key at `ssh.host_key_path`; generate an ed25519 key on first start with mode `0600`.
+- Only `publickey` auth. `auth_password` and `auth_none` always reject. Offer ed25519,
+  ecdsa-sha2-nistp256, and rsa-sha2-256/512; refuse `ssh-rsa` (SHA-1) and DSA.
+- On offered key: compute the SHA256 fingerprint, look it up in `keys` where `kind = 'ssh'`.
+  Unknown fingerprint → reject. Match → bind the user to the session, update `last_used_at`.
+- Handle the `exec` channel request only. Parse the command with shell-word splitting and accept
+  exactly:
+  - `git-upload-pack '<path>'`
+  - `git-receive-pack '<path>'`
+  - `git-upload-archive '<path>'`
+  Anything else (including an interactive shell request) → write a friendly banner to stderr
+  (`Hi {user}! fabrica does not provide shell access.`), exit status 1, close.
+- Normalize `<path>`: strip a leading `/` and a trailing `.git`, reject `..` and absolute paths,
+  resolve `owner/group…/repo` through the store.
+- Permission: `upload-pack` needs `read`, `receive-pack` needs `write`. Deny with a clear
+  stderr message and non-zero exit.
+- Pipe channel data ↔ child stdio; forward child stderr to the channel's extended data so
+  hook output reaches the user's terminal. Send `exit-status` on completion.
+- Support `ssh.clone_host` / `ssh.clone_port` for the clone URLs shown in the UI, separate from
+  the bind address, so a reverse proxy or port forward can be reflected accurately.
+### 3.4 Hooks
+Install `hooks/post-receive` (and a no-op `pre-receive` reserved for future branch protection)
+as a two-line script:
+```sh
+#!/bin/sh
+exec fabrica hook post-receive
+```
+`fabrica hook post-receive` reads the `<old> <new> <ref>` lines from stdin and:
+- updates `repos.pushed_at`, `repos.size_bytes`, and the cached default-branch head,
+- invalidates the repo's caches,
+- enqueues a `runs` row **only** when CI ships (inert for the MVP),
+- exits 0 even on internal error, logging loudly — a hook failure **MUST NOT** reject a push
+  that git already accepted.
+The hook path must locate the running binary reliably: write the absolute path of the current
+executable at repo-init time (`std::env::current_exe`), falling back to `git.hook_binary` config.
+### 3.5 Attributes (`.gitattributes`)
+libgit2's attribute lookup is oriented toward a working tree; bare repos and per-ref accuracy
+make it unreliable here. Implement an own resolver:
+- For a given `(repo, tree_oid)`, walk the tree and collect every `.gitattributes` blob with its
+  directory prefix.
+- Parse into ordered rules (pattern, attribute assignments), respecting gitattributes semantics:
+  later rules win, deeper directories win over shallower, `!` negation, `/`-anchored patterns,
+  `**`, and macro-free simple assignment (`key=value`, `key`, `-key`, `!key`).
+- Match with `globset`, honouring the "no slash in pattern → match basename at any depth" rule.
+- Cache resolved rule sets in a `moka` cache keyed by `(repo_id, tree_oid)`.
+- Consumers: language override for highlighting, `binary`/`-text` for "binary file, not shown",
+  `linguist-generated` / `fabrica-generated` for collapsing diffs by default,
+  `linguist-vendored` for excluding from search.
+Unit tests **MUST** cover: precedence between nested files, negation, anchored vs floating
+patterns, and `-diff` suppressing diff rendering.
+### 3.6 Signature verification
+Read the signature with `Repository::extract_signature(oid, None)`, which yields
+`(signature, signed_payload)`. Dispatch on the armor header.
+**SSH** (`-----BEGIN SSH SIGNATURE-----`): parse with the `ssh-key` crate's `SshSig`. Verify with
+namespace `"git"` against candidate public keys. Reject if the sig's hash algorithm is not
+sha256/sha512.
+**GPG** (`-----BEGIN PGP SIGNATURE-----`): verify with `sequoia-openpgp` against registered
+public keys. Check the signature's creation time against key validity and expiry; treat expired
+or revoked keys as unverified, not verified.
+Result type:
+```rust
+pub enum SignatureState {
+    Unsigned,
+    /// Valid signature, key registered on this instance.
+    Verified { user_id: Ulid, key_id: Ulid, kind: KeyKind, fingerprint: String },
+    /// Valid signature, key not known to this instance.
+    UnknownKey { kind: KeyKind, fingerprint: String },
+    /// Signature present but cryptographically invalid, malformed, or expired.
+    Invalid { kind: Option<KeyKind>, reason: String },
+}
+```
+UI mapping, matching the reference screenshots: `Verified` renders a green **Verified** badge;
+everything else that carries a signature renders an amber **Unverified** badge; `Unsigned`
+renders an amber **Unverified** badge as well. The tooltip / detail line distinguishes the four
+cases precisely ("Signed by an unrecognized key `SHA256:…`", "Signature could not be verified:
+…", "This commit is not signed"). Do not silently collapse `Invalid` into `Unsigned`.
+Verification is expensive; cache per commit oid in a bounded `moka` cache and, for list views,
+verify lazily in a bounded-concurrency batch (`ui.signature_batch_concurrency`, default 8).
+Additionally verify tag signatures for annotated tags and show the same badge on the tags page.
+### 3.7 Reads
+Expose a narrow, testable API — no `git2` types in the public signatures, so `web` never links
+against libgit2 semantics:
+```rust
+pub fn resolve_ref(&self, r: &str) -> Result<Resolved>;           // branch | tag | oid | HEAD
+pub fn tree_entries(&self, rev: &Resolved, path: &Path) -> Result<Vec<TreeEntry>>;
+pub fn blob(&self, rev: &Resolved, path: &Path) -> Result<Blob>;  // + is_binary, size, lfs-ignored
+pub fn commits(&self, rev: &Resolved, path: Option<&Path>, page: Page) -> Result<Vec<CommitSummary>>;
+pub fn commit(&self, oid: Oid) -> Result<CommitDetail>;
+pub fn diff(&self, base: Option<Oid>, head: Oid, opts: DiffOpts) -> Result<FileDiffs>;
+pub fn diff_context(&self, head: Oid, file: &Path, from: u32, to: u32) -> Result<Vec<DiffLine>>;
+pub fn branches(&self) -> Result<Vec<BranchInfo>>;                // + ahead/behind vs default
+pub fn tags(&self) -> Result<Vec<TagInfo>>;
+pub fn last_commit_per_entry(&self, rev: &Resolved, path: &Path) -> Result<HashMap<..>>;
+```
+Notes:
+- Blocking libgit2 calls **MUST** run on `tokio::task::spawn_blocking`, or on a dedicated
+  `rayon` pool with a bounded queue. Never block the async runtime.
+- `Repository` handles are not `Sync`; use a small per-repo pool or open-per-operation. Measure
+  before optimizing; open-per-operation is acceptable for the MVP if documented.
+- Branch ahead/behind uses `graph_ahead_behind` against the default branch (the screenshot shows
+  `10 ahead`).
+- `last_commit_per_entry` powers the file tree's "latest change" column; it is the classic
+  performance trap. Implement as a single revwalk with path filtering, capped by
+  `ui.tree_history_limit` (default 1000 commits), and degrade gracefully to no column when the
+  cap is hit.
+---
+## 4. Configuration (`crates/config`)
+TOML file plus environment overrides via `figment`. Resolution order (later wins): built-in
+defaults → `/etc/fabrica/fabrica.toml` → `$XDG_CONFIG_HOME/fabrica/fabrica.toml` → `--config
+<path>` → `FABRICA__*` env vars. Nested keys use double underscores:
+`FABRICA__SERVER__PORT=8080`.
+Any `*_file` key reads its value from a file (for agenix/systemd-creds/Docker secrets) and takes
+precedence over its inline sibling. Secrets **MUST NOT** be logged, echoed by `config show`
+(print `<redacted>`), or included in error messages.
+`fabrica.example.toml` — ship this, fully commented:
+```toml
+[instance]
+name            = "fabrica"          # shown in the header and page titles
+url             = "https://git.example.com"
+description     = "A small, private forge."
+default_branch  = "main"
+allow_anonymous = true               # anonymous browse + clone of public repos
+[server]
+address                = "0.0.0.0"
+port                   = 8080
+behind_proxy           = false       # trust X-Forwarded-For / X-Forwarded-Proto
+graceful_shutdown_secs = 20
+max_body_bytes          = 1048576    # non-pack routes only
+[ssh]
+enabled       = true
+address       = "0.0.0.0"
+port          = 2222
+host_key_path = "/var/lib/fabrica/ssh/host_ed25519"
+clone_host    = "git.example.com"    # what the UI shows, may differ from bind
+clone_port    = 22
+[storage]
+data_dir = "/var/lib/fabrica"
+repo_dir = "/var/lib/fabrica/repos"
+[database]
+url             = "sqlite:///var/lib/fabrica/fabrica.db"
+max_connections = 16
+# SQLite is opened with journal_mode=WAL, synchronous=NORMAL, foreign_keys=ON,
+# busy_timeout=5000. Postgres URLs (postgres://…) are detected automatically.
+[auth]
+secret_file       = "/var/lib/fabrica/secret"   # HS256 key, generated on first run, 0600
+session_ttl_days  = 30
+token_ttl_days    = 90
+cookie_name       = "fabrica_session"
+cookie_secure     = true
+argon2_m_cost     = 19456
+argon2_t_cost     = 2
+argon2_p_cost     = 1
+[mail]
+backend       = "smtp"               # smtp | stdout | none
+from          = "fabrica@example.com"
+host          = "smtp.example.com"
+port          = 587
+username      = "fabrica"
+password_file = "/run/secrets/fabrica-smtp"
+encryption    = "starttls"           # starttls | tls | none
+timeout_secs  = 15
+[ui]
+theme                = "dark"        # file stem in themes_dir, or an embedded theme name
+themes_dir           = "/var/lib/fabrica/themes"
+assets_dir           = "/var/lib/fabrica/assets"
+allow_theme_choice   = true          # show the theme picker; persists in a cookie
+show_runs            = false         # CI nav slot, inert until the CI ships
+diff_context_lines   = 3
+max_highlight_bytes  = 1048576
+max_diff_bytes       = 5242880
+tree_history_limit   = 1000
+[git]
+binary                 = "git"
+transport_timeout_secs = 3600
+max_pack_size_bytes    = 536870912
+[log]
+level  = "info"                      # trace|debug|info|warn|error, RUST_LOG also honoured
+format = "pretty"                    # pretty | json
+```
+Validation at startup **MUST** be strict and fail fast with actionable messages: unknown keys
+are an error (catch typos), `instance.url` must parse and must not have a trailing slash,
+directories must exist or be creatable, `mail.backend = "smtp"` requires host/from,
+`auth.cookie_secure = true` with a non-HTTPS `instance.url` is a warning.
+`fabrica config check` validates and exits; `fabrica config show` prints the effective merged
+config with secrets redacted.
+---
+## 5. Data model (`crates/store`)
+`sqlx` with both backends. Do **not** use compile-time-checked macros against two dialects —
+define a `Store` trait with `Sqlite` and `Postgres` implementations behind it, or use runtime
+queries over `AnyPool`; keep every statement inside the portable SQL subset.
+Portability rules, enforced by review:
+- Timestamps are `BIGINT` unix **milliseconds**, UTC. No `DATETIME`, no `TIMESTAMPTZ`.
+- Ids are `TEXT` ULIDs (26 chars, lexicographically sortable — use them for ordering).
+- Booleans are `INTEGER` 0/1 in SQLite, `BOOLEAN` in Postgres; the trait maps them.
+- No `AUTOINCREMENT`, no `SERIAL`, no `RETURNING` outside a helper that both dialects support
+  (both do support `RETURNING` — using it is fine).
+- Case-insensitive uniqueness on usernames and emails is enforced by storing a normalized
+  `*_lower` column with a unique index, not by collation.
+Migrations live in `migrations/{sqlite,postgres}/NNNN_name.sql`, applied with `sqlx::migrate!`
+selected at runtime. `fabrica migrate` runs them; `serve` runs them automatically unless
+`--no-migrate`.
+### Schema
+```sql
+users (
+  id TEXT PRIMARY KEY,
+  username TEXT NOT NULL, username_lower TEXT NOT NULL UNIQUE,
+  email TEXT NOT NULL, email_lower TEXT NOT NULL UNIQUE,
+  display_name TEXT,
+  password_hash TEXT,                 -- NULL until the invite is completed
+  must_change_password INTEGER NOT NULL DEFAULT 0,
+  is_admin INTEGER NOT NULL DEFAULT 0,
+  disabled_at BIGINT,
+  created_at BIGINT NOT NULL, updated_at BIGINT NOT NULL
+)
+invites (                             -- password-setup / activation links
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  token_hash TEXT NOT NULL UNIQUE,    -- SHA-256 of the emailed token
+  purpose TEXT NOT NULL,              -- 'activate' | 'reset'
+  expires_at BIGINT NOT NULL, used_at BIGINT,
+  created_at BIGINT NOT NULL
+)
+sessions (
+  id TEXT PRIMARY KEY,                -- SHA-256 of the cookie value
+  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  user_agent TEXT, ip TEXT,
+  created_at BIGINT NOT NULL, last_seen_at BIGINT NOT NULL, expires_at BIGINT NOT NULL
+)
+api_tokens (
+  id TEXT PRIMARY KEY,                -- the JWT `jti`
+  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  scopes TEXT NOT NULL,               -- comma-separated
+  expires_at BIGINT, revoked_at BIGINT, last_used_at BIGINT,
+  created_at BIGINT NOT NULL
+)
+keys (
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  kind TEXT NOT NULL,                 -- 'ssh' | 'gpg'
+  name TEXT,
+  fingerprint TEXT NOT NULL,          -- SHA256:… for ssh, full hex fp for gpg
+  public_key TEXT NOT NULL,           -- authorized_keys line or ASCII-armored pgp block
+  ordinal INTEGER NOT NULL,           -- stable 1-based index per (user, kind) for `key del`
+  last_used_at BIGINT,
+  created_at BIGINT NOT NULL,
+  UNIQUE (kind, fingerprint),
+  UNIQUE (user_id, kind, ordinal)
+)
+groups (
+  id TEXT PRIMARY KEY,
+  owner_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  parent_id TEXT REFERENCES groups(id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  path TEXT NOT NULL,                 -- materialized 'group/sub/leaf'
+  description TEXT,
+  created_at BIGINT NOT NULL,
+  UNIQUE (owner_id, path)
+)
+repos (
+  id TEXT PRIMARY KEY,
+  owner_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  group_id TEXT REFERENCES groups(id) ON DELETE SET NULL,
+  name TEXT NOT NULL,
+  path TEXT NOT NULL,                 -- materialized 'group/sub/repo' (== name when ungrouped)
+  description TEXT,
+  is_private INTEGER NOT NULL DEFAULT 1,
+  default_branch TEXT NOT NULL,
+  archived_at BIGINT,
+  size_bytes BIGINT NOT NULL DEFAULT 0,
+  pushed_at BIGINT,
+  created_at BIGINT NOT NULL, updated_at BIGINT NOT NULL,
+  UNIQUE (owner_id, path)
+)
+repo_collaborators (
+  repo_id TEXT NOT NULL REFERENCES repos(id) ON DELETE CASCADE,
+  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  permission TEXT NOT NULL,           -- 'read' | 'write' | 'admin'
+  created_at BIGINT NOT NULL,
+  PRIMARY KEY (repo_id, user_id)
+)
+-- reserved, inert until the CI ships
+runs  (id TEXT PRIMARY KEY, repo_id TEXT NOT NULL, ref TEXT NOT NULL, commit_sha TEXT NOT NULL,
+       status TEXT NOT NULL, started_at BIGINT, finished_at BIGINT, created_at BIGINT NOT NULL)
+jobs  (id TEXT PRIMARY KEY, run_id TEXT NOT NULL REFERENCES runs(id) ON DELETE CASCADE,
+       stage TEXT NOT NULL, name TEXT NOT NULL, status TEXT NOT NULL,
+       log_path TEXT, started_at BIGINT, finished_at BIGINT)
+```
+Indexes: `repos(owner_id, path)`, `repos(is_private, pushed_at DESC)`, `groups(owner_id, parent_id)`,
+`keys(user_id, kind)`, `sessions(user_id)`, `sessions(expires_at)`, `api_tokens(user_id)`.
+Name validation (single place in `model`, used by CLI, API, and web): usernames and repo/group
+names match `^[A-Za-z0-9][A-Za-z0-9._-]{0,38}$`, must not be `.`/`..`, must not end in `.git`
+or `.`, and are rejected against a reserved list: `api`, `assets`, `login`, `logout`, `search`,
+`settings`, `admin`, `static`, `healthz`, `invite`, `-`.
+---
+## 6. Auth and permissions (`crates/auth`)
+- **Passwords**: `argon2` crate, Argon2id, params from config. Hashes stored in PHC string
+  format. Verification is constant-time; on a missing user, still perform a dummy hash to avoid
+  timing disclosure.
+- **Sessions**: 32 bytes from `OsRng`, base64url-encoded in the cookie; the DB stores only the
+  SHA-256. Cookie is `HttpOnly`, `SameSite=Lax`, `Secure` per config, `Path=/`. Rotate the id on
+  login and on password change; delete all sessions for the user on password change.
+- **CSRF**: double-submit token in a non-HttpOnly cookie plus an `X-CSRF-Token` header injected
+  by htmx (`hx-headers` on `<body>`); required on every non-GET web route. The API is exempt
+  (bearer tokens only) but **MUST** reject cookie-authenticated non-GET requests without the
+  header.
+- **API tokens**: JWT, HS256, signed with the instance secret. Claims: `sub` (user id), `jti`
+  (row id in `api_tokens`), `scopes`, `iat`, `exp`. Every request validates the signature *and*
+  checks the `jti` row for `revoked_at IS NULL` — this is what makes revocation real. Update
+  `last_used_at` at most once a minute per token.
+- **Scopes**: `repo:read`, `repo:write`, `repo:admin`, `user:read`, `user:write`, `admin`.
+- **Rate limiting**: `tower_governor` on `/login`, `/invite/*`, and Basic-auth pack routes; a
+  per-username exponential backoff on failed logins recorded in memory.
+Permission resolution — one function, used everywhere, unit tested exhaustively:
+```rust
+pub enum Access { None, Read, Write, Admin }
+pub fn access(viewer: Option<&Viewer>, repo: &Repo) -> Access
+```
+Rules, in order:
+. `viewer.is_admin` → `Admin`.
+. `viewer.id == repo.owner_id` → `Admin`.
+. explicit `repo_collaborators` row → that permission.
+. `!repo.is_private && instance.allow_anonymous` → `Read`.
+. otherwise `None`.
+Anonymous viewers can only ever reach `Read`, and only on public repos. Every mutating route
+asserts at least `Write`; creation routes assert an authenticated viewer. `None` on a private
+repo **MUST** render `404`, not `403` — do not leak existence.
+---
+## 7. Mail (`crates/mail`)
+Required for the MVP: `user add` without `--pass` emails the user an activation link.
+- `lettre` with the `tokio1-rustls` transport. Backends: `smtp`, `stdout` (development — print
+  the rendered mail and the link), `none` (reject flows that need mail with a clear error).
+- Templates: plain-text primary, minimal HTML alternative, both rendered from the same data with
+  `instance.name` and `instance.url` interpolated. Ship `activate` and `reset`.
+- Activation link: `{instance.url}/invite/{token}`, token = 32 random bytes base64url, TTL 72h
+  (config `auth.invite_ttl_hours`), single-use, stored hashed.
+- Sending is **best-effort and out-of-band**: never block a CLI command or HTTP response on SMTP.
+  Spawn the send, log failures loudly, and always print the activation URL to stdout in the CLI
+  so an operator can deliver it manually when SMTP is down.
+- Unit tests use the `stdout` backend and assert the rendered body contains a well-formed link.
+---
+## 8. Highlighting (`crates/highlight`)
+`inkjet` (tree-sitter) for highlighting. This crate has two hard requirements that drive its
+design: **line-addressable output** (for blob views with anchors) and **per-side highlighting
+inside diffs**.
+Implementation:
+. Resolve the language (§8.1) → `inkjet::Language`.
+. Highlight the full text once, producing a flat sequence of `(byte_range, capture_stack)`.
+. Convert to `Vec<HighlightedLine>`, where each line is `Vec<Span { class, text }>`. Spans that
+   cross a newline are **split**, and the open capture stack is re-opened on the next line. This
+   is the crux: every emitted line must be independently valid HTML with balanced tags.
+. Cache by `(blob_oid, language)` in a bounded `moka` cache.
+For diffs, highlight the **pre-image and post-image of each file as whole documents** — never
+per-hunk, or context-dependent grammars produce garbage — then index the resulting lines by line
+number and zip them with the diff hunks. Added/removed backgrounds are applied to the row, and
+highlight spans live inside it, exactly as in the reference screenshots.
+Class names are stable and theme-driven: `hl-keyword`, `hl-function`, `hl-type`, `hl-string`,
+`hl-number`, `hl-comment`, `hl-constant`, `hl-variable`, `hl-operator`, `hl-punctuation`,
+`hl-attribute`, `hl-tag`. Map inkjet's capture names onto this fixed set in one table so themes
+never need to know tree-sitter internals. Document the full list in `docs/theming.md`.
+Guards: skip files over `ui.max_highlight_bytes`, skip files detected as binary (NUL in the
+first 8 KiB), skip minified files (any line > 5000 bytes), and fall back to escaped plain text on
+any grammar panic — highlighting **MUST NOT** be able to fail a page render. Enforce a per-file
+timeout and fall back on expiry.
+### 8.1 Language resolution order
+. `.gitattributes` `fabrica-language=<name>` (own attribute, highest precedence).
+. `.gitattributes` `linguist-language=<name>` (GitHub compatibility).
+. `.gitattributes` `-diff` / `binary` → no highlighting, render as binary.
+. Shebang line (`#!/usr/bin/env python3` → python).
+. Vim/Emacs modeline in the first or last 5 lines.
+. Exact filename (`Dockerfile`, `Makefile`, `flake.lock`, `Cargo.lock`, `PKGBUILD`).
+. Extension, longest match first (`.tar.gz` before `.gz`, `.d.ts` before `.ts`).
+. Plain text.
+Name matching is case-insensitive with an alias table (`rs`/`rust`, `py`/`python`,
+`ts`/`typescript`, `nix`, `gleam`, `hcl`/`terraform`, …). An unknown language name in
+`.gitattributes` logs a debug line and falls through, rather than erroring.
+Unit tests: one per resolution step, plus a test asserting `fabrica-language` beats
+`linguist-language` and both beat the extension.
+---
+## 9. Web UI (`crates/web`)
+### 9.1 Stack
+- `axum` + `tower-http` (compression, tracing, request id, timeout).
+- `maud` for templates — compile-time-checked, no runtime template files, and it composes
+  naturally into htmx partials.
+- **htmx 2** for reactivity, vendored into `assets/` (no CDN). A small amount of hand-written
+  vanilla JS (< 200 lines total, in `assets/fabrica.js`) for: the mobile nav drawer, the theme
+  picker, clipboard buttons, and keyboard shortcuts. **No SPA, no WASM, no build step, no npm.**
+- Every interactive element **MUST** work without JavaScript. htmx enhances; links and forms are
+  the substrate. `hx-boost` is not used for full-page navigation.
+### 9.2 Routing
+Group nesting makes repo paths variable-length, which collides with sub-resources. Resolve it
+with a **`/-/` separator** (the GitLab convention): everything before `/-/` is the repo path,
+everything after is the view.
+```
+/                                   home: your repos + public repos
+/login  /logout  /invite/{token}
+/search?q=&scope=                   global search
+/settings                           profile, password
+/settings/keys                      ssh + gpg keys
+/settings/tokens                    API tokens
+/admin/users                        admin only
+/healthz  /version
+/assets/*                           overridable assets
+/{owner}                            user page: groups + repos
+/{owner}/{path..}                   repo home (or group listing if path resolves to a group)
+/{owner}/{path..}.git/*             pack transport (§3.3)
+/{owner}/{path..}/-/tree/{ref}/{p..}
+/{owner}/{path..}/-/blob/{ref}/{p..}
+/{owner}/{path..}/-/raw/{ref}/{p..}
+/{owner}/{path..}/-/commits/{ref}
+/{owner}/{path..}/-/commit/{sha}
+/{owner}/{path..}/-/commit/{sha}/context      (partial: expanded diff context)
+/{owner}/{path..}/-/branches
+/{owner}/{path..}/-/tags
+/{owner}/{path..}/-/search?q=
+/{owner}/{path..}/-/settings
+/{owner}/{path..}/-/runs                      (inert; 404 unless ui.show_runs)
+```
+Path resolution: given `{owner}` and the segments before `/-/`, look up `repos` by
+`(owner_id, path)`; on miss, look up `groups` by `(owner_id, path)` and render a group listing;
+on miss, `404`. One store query each, both indexed.
+### 9.3 Layout
+Match the reference screenshots.
+**Chrome**: a slim top bar — sidebar toggle at the far left, `{owner}/{repo}` slug next to it,
+tabs centred (`Code`, `Search`, `Branches`, `Tags`, and `Runs` when enabled), home icon at the
+right. The left sidebar is an off-canvas drawer holding instance name, organization-free nav
+(Home, your repos), the theme picker, Settings, and Log out.
+**Code view**: two panes. Left is the file tree (`Files` header with a `Commits` toggle button on
+the right); right is the content pane — README rendered on the repo root, blob contents on a
+file, or the commit list when `Commits` is active. A branch/tag picker pill sits above both.
+Tree rows carry filetype icons; directories expand in place via htmx rather than navigating.
+**Commit list**: flat rows — subject, then a `Verified`/`Unverified` badge, then a second line of
+short sha · author · date. Infinite scroll via `hx-trigger="revealed"` on the last row.
+**Commit page**: title + badge, short sha, `{author} committed on {datetime}`. A collapsible
+`Files Changed` section with `N files changed`, `+adds`/`−dels`, and a `Unified`/`Split` toggle.
+A changed-files tree in the left sidebar that anchors to each file's diff. Each file collapses
+independently, shows its own `+/−` counts, and offers `expand N hidden lines` rows with up/down
+directional expanders.
+**Diff context expansion** hits `/-/commit/{sha}/context?file=&from=&to=&side=`, which returns a
+rendered partial of highlighted context lines and swaps the expander row via `hx-swap="outerHTML"`.
+The expander tracks the current window in `data-` attributes so repeated expansion walks outward.
+Expanding beyond the file bounds removes the expander.
+**Blob view**: line numbers as a separate non-selectable column, anchors `#L12` and ranges
+`#L12-L20` (click, then shift-click) with the range highlighted and reflected into the URL, raw
+and copy buttons, and a byte/line count header. Images render inline; other binaries show a
+"binary file not shown" notice with a download link.
+**Branches**: name, `N ahead` vs default (green), default badge, last-updated author and date —
+per the screenshot. **Tags**: name, short sha, signature badge, updated author and date.
+### 9.4 Reactivity patterns
+| Interaction | Mechanism |
+| --- | --- |
+| Directory expand in tree | `hx-get` returns `<ul>` children, swapped `innerHTML` |
+| Blob / README / commit-list pane swap | `hx-get` + `hx-target="#pane"` + `hx-push-url="true"` |
+| Commit list pagination | `hx-trigger="revealed"` on the sentinel row |
+| Diff context expansion | `hx-swap="outerHTML"` on the expander row |
+| Unified ↔ Split | `hx-get` with `?view=split`, re-renders the diff region, persists in a cookie |
+| Search | `hx-trigger="keyup changed delay:300ms"` into a results region |
+| Branch/tag picker | `hx-get` filtered list into a popover |
+| Theme switch | client-side attribute swap + cookie, no request |
+Handlers detect `HX-Request` and return the partial; the same handler without the header returns
+the full page. Write this as one helper (`fn respond(page, partial)`) so no route can drift.
+### 9.5 Theming and assets
+- `assets/base.css` — layout and structure, embedded via `rust-embed`. Written entirely against
+  custom properties; contains **no literal colours**.
+- Themes are single CSS files defining custom properties under `:root` (and optionally
+  `@media (prefers-color-scheme: light)`). Ship `dark` (default, matching the screenshots) and
+  `light` embedded.
+- At startup, scan `ui.themes_dir` for `*.css`; each becomes a selectable theme named by its file
+  stem. Disk themes override embedded ones with the same name. Rescan on `SIGHUP` and expose
+  `fabrica theme list`.
+- `ui.assets_dir` overrides any embedded asset by path (`logo.svg`, `favicon.ico`,
+  `custom.css` — the last is injected after the theme if present). Resolution is
+  disk-then-embedded, with path traversal rejected.
+- Theme selection: `ui.theme` is the instance default; if `ui.allow_theme_choice`, a picker
+  writes a `fabrica_theme` cookie which wins per-visitor. Emit
+  `<html data-theme="{name}" style="color-scheme: {dark|light}">`.
+- Token naming, documented in `docs/theming.md`: `--fb-bg`, `--fb-bg-raised`, `--fb-bg-inset`,
+  `--fb-border`, `--fb-fg`, `--fb-fg-muted`, `--fb-accent`, `--fb-success`, `--fb-warning`,
+  `--fb-danger`, `--fb-diff-add-bg`, `--fb-diff-del-bg`, `--fb-diff-add-fg`, `--fb-diff-del-fg`,
+  plus the `--fb-hl-*` family mirroring §8's class list. A theme that sets only these
+  **MUST** produce a complete, coherent UI — that is the acceptance test for themeability.
+- Fonts: system UI stack for prose, system monospace stack for code. No web fonts, no network
+  requests from any page.
+### 9.6 Responsive
+Single breakpoint at 48rem. Below it: the file tree becomes a drawer over the content pane, the
+tab bar scrolls horizontally, the commit-page sidebar collapses into a dropdown, diffs force
+unified regardless of the toggle, and touch targets are ≥ 44px. Test at 380px wide.
+### 9.7 Rendering markdown
+`comrak` with GFM extensions (tables, strikethrough, task lists, autolinks, footnotes), output
+sanitized with `ammonia`. Heading anchors, relative link and image rewriting to
+`/-/raw/{ref}/…`, and highlighted fenced code blocks via `crates/highlight`. Raw HTML in
+markdown is stripped, not escaped-and-shown. README lookup order: `README.md`, `README`,
+`readme.md`, `README.txt`.
+---
+## 10. Search
+Two scopes, one engine, no index for the MVP.
+- **In-repo** (`/{owner}/{path}/-/search?q=`): walk the tree at the default branch (or `?ref=`),
+  skip binaries, files over 1 MiB, and `linguist-vendored`/`linguist-generated` paths; match
+  content with `grep-searcher` + `grep-regex`, and paths with a substring/fuzzy match. Return
+  grouped results — file path, then matching lines with 1 line of context, highlighted.
+- **Global** (`/search?q=`): match repo names, group names, usernames, and descriptions first,
+  then run the in-repo content search across every repo the viewer can read, with a bounded
+  worker pool (`search.concurrency`, default 4), a total time budget
+  (`search.timeout_secs`, default 10), and a result cap (`search.max_results`, default 200).
+  When the budget is exhausted, return partial results with an explicit "search timed out,
+  showing partial results" notice — never silently truncate.
+- **Qualifiers**, parsed with a tiny hand-written parser (unit tested): `repo:owner/path`,
+  `user:name`, `path:glob`, `lang:name`, `case:yes`, `regex:yes`. Bare terms are literal and
+  case-insensitive by default.
+- Document in `docs/decisions.md` that this is a linear scan appropriate to a private instance,
+  and that a `tantivy` index is the intended path if it stops being fast enough.
+---
+## 11. API (`crates/api`)
+`/api/v1`, JSON, `Bearer` JWT. Purpose: automation parity with the CLI, not a public platform.
+```
+GET    /api/v1/version
+GET    /api/v1/user                          # current token's user
+GET    /api/v1/users                         # admin
+POST   /api/v1/users                         # admin
+DELETE /api/v1/users/{name}?purge=           # admin
+GET    /api/v1/users/{name}/keys
+POST   /api/v1/users/{name}/keys
+DELETE /api/v1/users/{name}/keys/{ordinal}
+GET    /api/v1/repos                         # visible to the token
+POST   /api/v1/repos
+GET    /api/v1/repos/{owner}/{path..}
+PATCH  /api/v1/repos/{owner}/{path..}
+DELETE /api/v1/repos/{owner}/{path..}?purge=
+GET    /api/v1/repos/{owner}/{path..}/branches
+GET    /api/v1/repos/{owner}/{path..}/tags
+GET    /api/v1/repos/{owner}/{path..}/commits?ref=&page=
+GET    /api/v1/repos/{owner}/{path..}/commits/{sha}
+GET    /api/v1/repos/{owner}/{path..}/tree/{ref}/{p..}
+GET    /api/v1/repos/{owner}/{path..}/raw/{ref}/{p..}
+GET    /api/v1/groups/{owner}
+POST   /api/v1/groups
+DELETE /api/v1/groups/{owner}/{path..}
+GET    /api/v1/search?q=&scope=
+```
+Conventions: `snake_case` fields; errors as
+`{"error": {"code": "not_found", "message": "…", "details": {}}}` with correct status codes;
+cursor pagination via `?page=&per_page=` (max 100) plus `X-Total-Count`; `404` (not `403`) for
+unauthorized private resources; all timestamps RFC 3339 strings on the wire even though they are
+epoch-ms at rest.
+---
+## 12. CLI (`crates/cli`)
+`clap` derive, colour-aware, `--config`, `--log-level`, `--json` (machine-readable output for
+every list command). All commands operate **directly** on the store and filesystem — no IPC with
+a running server is required, since SQLite WAL and Postgres both tolerate concurrent writers.
+Mutations that a live server caches (repo rename, delete, user disable) bump a `cache_epoch` row
+that `serve` polls every few seconds.
+```
+fabrica serve [--detach] [--no-migrate]
+fabrica user add <name> <email> [--pass <password>] [--admin] [--display-name <s>]
+fabrica user del <name> [--purge]
+fabrica user list
+fabrica user passwd <name> [--pass <password>]
+fabrica user disable <name> | enable <name>
+fabrica key add --type <ssh|gpg> <user> <public-key|@path|->
+fabrica key del <user> <index>
+fabrica key list <user>
+fabrica repo add <user> <name> [--private|--public] [--description <s>] [--default-branch <b>]
+fabrica repo del <user> <name> [--purge]
+fabrica repo list [--user <name>]
+fabrica repo rename <user> <name> <new-name>
+fabrica repo path <user> <name>
+fabrica group add <user> <path>
+fabrica group del <user> <path>
+fabrica group list <user>
+fabrica token add <user> <name> [--scopes <list>] [--expires <duration>]
+fabrica token del <user> <index>
+fabrica token list <user>
+fabrica theme list
+fabrica config check | show
+fabrica migrate
+fabrica doctor
+fabrica gc [--trash-older-than <duration>]
+fabrica hook post-receive          # internal, hidden from help
+```
+Behaviour notes:
+- `serve` runs in the **foreground** by default — correct for systemd and Docker — handling
+  `SIGTERM`/`SIGINT` with graceful shutdown (stop accepting, drain in-flight requests up to
+  `server.graceful_shutdown_secs`, wait on active pack subprocesses, close pools). `--detach`
+  double-forks and writes `{data_dir}/fabrica.pid`; there is no `stop` subcommand — signal the
+  pid. Document this deviation from the original `server start`/`server stop` sketch in
+  `docs/decisions.md`.
+- `user add` without `--pass`: create the user with `password_hash = NULL`, mint an invite,
+  email it, **and** print the activation URL to stdout.
+- `key add` accepts a literal key, `@path`, or `-` for stdin; parses and validates it before
+  insert (ssh via `ssh-key`, gpg via `sequoia-openpgp`); rejects duplicates by fingerprint with a
+  message naming the existing owner.
+- `key del <user> <index>` uses the 1-based `ordinal` shown by `key list`. Ordinals are stable —
+  deleting one does **not** renumber the others; new keys take `max(ordinal) + 1`. State this in
+  the help text.
+- `repo add <user> <name>` accepts a group path in `name` (`fabrica repo add hanna
+  backend/api`), creating missing intermediate groups.
+- `user del` without `--purge` refuses when the user owns repos, listing them; `--purge` deletes
+  repos, keys, tokens, and sessions.
+- Every destructive command prompts for confirmation on a TTY and requires `--yes` when not
+  attached to one.
+---
+## 13. Deployment artifacts
+### Dockerfile
+Multi-stage, no Nix in the image:
+- Builder: `rust:slim` (or `rustlang/rust:nightly-slim`), install `pkg-config`, `libssl-dev`,
+  `cmake`, `git`; `cargo build --release --features vendored`. The `vendored` feature turns on
+  `git2/vendored-libgit2` so the runtime image needs no libgit2.
+- Cache dependency layers first (copy manifests, build a dummy target, then copy sources) or use
+  `cargo-chef`.
+- Runtime: `debian:stable-slim` with `git`, `ca-certificates`, `tini`. Non-root user `fabrica`
+  (uid 10001). `VOLUME /var/lib/fabrica`. `EXPOSE 8080 2222`.
+  `HEALTHCHECK CMD ["fabrica","doctor","--quiet"]` or a curl of `/healthz`.
+  `ENTRYPOINT ["/usr/bin/tini","--","fabrica"]`, `CMD ["serve"]`.
+- Verify `git --version` in the final image at build time so a missing plumbing binary is a build
+  failure, not a runtime surprise.
+### compose.yml
+Two services: `fabrica` (image or `build: .`), and `postgres` behind a `postgres` profile so the
+default path is pure SQLite. Named volumes for `data` and `repos`. Config supplied by bind-mounting
+`fabrica.toml` and overriding a couple of keys via `FABRICA__*` env vars, to demonstrate both
+mechanisms. Map SSH as `2222:2222` with a comment explaining `ssh.clone_port`. Include a commented
+reverse-proxy block noting that the proxy **MUST NOT** buffer request or response bodies on
+`/git-upload-pack` (`proxy_buffering off`, `proxy_request_buffering off`) or clones will stall.
+---
+## 14. Testing
+Every crate carries unit tests; **no functionality ships untested**. `cargo test` alone must be
+sufficient (no external services required by default).
+- **`git`**: build fixture repos programmatically in `tempfile::TempDir` — commits, branches,
+  tags, merges, renames, binary files, a file with CRLF, a submodule entry. Fixtures for
+  signatures: generate an ed25519 key at test time, sign with `ssh-keygen -Y sign`, and
+  ship a small static GPG-signed fixture. Assert all four `SignatureState` variants.
+- **`highlight`**: snapshot tests (`insta`) over a fixture file per language. A dedicated test
+  asserts a multi-line string literal produces balanced spans on every line. A test asserts a
+  grammar failure degrades to plain text.
+- **Attributes**: table-driven tests over the precedence rules in §3.5.
+- **`store`**: run the full suite against SQLite in-memory *and* file-backed; Postgres tests
+  behind `#[cfg_attr(not(feature = "postgres-tests"), ignore)]`, driven by
+  `FABRICA_TEST_POSTGRES_URL`, and exercised in the dev shell. A migration test asserts both
+  dialects' migrations produce equivalent schemas.
+- **`auth`**: exhaustive matrix over `access()` — every viewer kind × visibility × collaborator
+  permission. This is the security-critical test; enumerate it, don't sample it.
+- **`web`**: `axum::Router` + `tower::ServiceExt::oneshot` for handler tests. Assert that
+  `HX-Request` yields a partial and its absence a full document, that private repos 404 for
+  anonymous viewers, and that CSRF rejection works. `insta` snapshots for key partials.
+- **`cli`**: `assert_cmd` + `predicates` against a temp data dir.
+- **Integration** (`tests/`): boot the server on port 0 and run real git against it —
+  `git clone` over HTTP, `git push`/`git clone` over SSH using a generated key, a push that
+  triggers the post-receive hook, and an HTTP push attempt asserting the 403 with a helpful body.
+  Gate these on `git` and `ssh` being present, skipping with a clear message otherwise.
+- `cargo-nextest` in the dev shell; keep the full suite under two minutes.
+---
+## 15. Working conventions
+### 15.1 Quality gate
+After **every** unit of work, all four must pass — no exceptions, no deferrals:
+```
+cargo fmt --all -- --check
+cargo check --workspace --all-targets
+cargo clippy --workspace --all-targets -- -D warnings
+cargo test --workspace
+```
+`nix flake check` is the superset and must pass before any phase is called done. Add a `justfile`
+with `just check` running all four, and use it.
+### 15.2 Commits
+**Conventional Commits**, one logical change per commit, committed **as work happens** rather
+than batched at the end.
+- Types: `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `build`, `chore`, `style`.
+- Scope is the crate or area: `feat(git):`, `fix(web):`, `build(nix):`, `docs(theming):`.
+- Imperative mood, lowercase subject, no trailing period, ≤ 72 chars.
+- Body explains *why* when non-obvious; footers `BREAKING CHANGE:` and `Refs:` as needed.
+- **Never commit with failing checks.** If a commit needs a `#[allow]`, justify it in the body.
+Examples:
+```
+feat(git): resolve gitattributes from tree blobs
+feat(ssh): accept git-upload-pack over exec channels
+fix(highlight): reopen capture stack across line breaks
+build(nix): wrap the binary with git on PATH
+test(auth): enumerate the access matrix
+```
+### 15.3 Error handling
+`thiserror` for library errors, one enum per crate; `anyhow` only at the binary boundary
+(`main.rs`, CLI commands). `tracing` for logging with structured fields; a request-id span on
+every HTTP request and a session span on every SSH connection. User-facing error pages are
+templated, themed, and never expose internals — the detail goes to the log with the request id,
+and the page shows the id.
+### 15.4 Docs
+`docs/decisions.md` is a running log: date, decision, alternatives, rationale. Seed it with the
+decisions this spec already makes — pack transport via subprocess, id-based repo directories,
+`/-/` route separator, epoch-ms timestamps, `serve` with no `stop`, linear search. Update it
+whenever you deviate from this spec.
+---
+## 16. Implementation phases
+Each phase ends with the full gate green and its own commits. Do not start a phase before the
+previous one is clean.
+. **Scaffold** — flake (fenix + crane), workspace with empty crates, `rust-toolchain.toml`,
+   lints, `justfile`, MPL-2.0 `LICENSE` and per-file headers, CI-less `nix flake check` passing.
+   `build: initialize workspace and nix flake`
+. **config** — TOML + env loading, validation, `config check`/`show`, example file, docs.
+. **store** — schema, both migration sets, `Store` trait, both backends, name validation, tests.
+. **auth** — argon2id, sessions, JWT, `access()`, the full permission matrix test.
+. **git reads** — open/init bare, refs, trees, blobs, log, diff, context expansion, branch
+   ahead/behind, fixture harness.
+. **highlight** — inkjet integration, line-aware output, language resolution, attributes
+   resolver, snapshot tests.
+. **git signatures** — SSH and GPG verification against registered keys, all four states.
+. **cli core** — clap tree, `user`/`key`/`repo`/`group`/`token` commands against the store,
+   `doctor`, `migrate`.
+. **mail** — lettre, templates, invite tokens, `stdout` backend, wire into `user add`.
+. **web shell** — axum, maud layout, top bar, drawer, theming pipeline, asset overrides,
+    embedded + disk themes, login/logout/invite, error pages, `/healthz`.
+. **web repo views** — repo home + README, tree, blob with anchors, raw, commit list with
+    badges, branches, tags. htmx partials throughout.
+. **web commit view** — file diffs, changed-files tree, per-file collapse, unified **and**
+    split, highlighted diff rows, context expansion endpoint.
+. **pack transport** — `git` discovery, subprocess wrapper, smart HTTP read routes, the
+    deliberate 403 on HTTP push, hooks installed at init, `hook post-receive`.
+. **ssh** — russh server, host key generation, publickey auth against `keys`, exec dispatch to
+    pack processes, permission enforcement, banner for shell attempts.
+. **search** — in-repo, global, qualifier parser, budgets and partial-result reporting.
+. **api** — `/api/v1` surface, JWT middleware, scopes, error shape.
+. **deployment** — Dockerfile, compose.yml, `packages.container`, NixOS module, deployment docs.
+. **polish** — mobile pass at 380px, caching (`moka` where measured), graceful shutdown,
+    accessibility (focus rings, skip link, ARIA on the drawer and tabs, keyboard nav), a
+    second theme proving `docs/theming.md` is complete.
+Then, and only then, the CI: HCL config parsed with `hcl-rs`, Docker execution via `bollard`,
+stages and jobs, log streaming into the reserved `runs` view.
+---
+## 17. Definition of done for the MVP
+- `nix build` produces a single wrapped binary; `nix flake check` is green.
+- `fabrica user add`, `key add`, `repo add` work; the emailed invite completes activation.
+- `git clone https://…` works for public repos anonymously and private repos with Basic auth.
+- `git push` over SSH works with a registered key and is rejected for an unregistered one.
+- `git push` over HTTPS fails with a 403 that tells the user the SSH URL.
+- The web UI browses trees, blobs, history, branches, and tags with highlighting, and renders
+  commit diffs unified and split with working context expansion and highlighted rows.
+- Signature badges are correct across all four states.
+- Nested groups resolve in the UI, in clone URLs, and in the CLI.
+- Dropping a CSS file in `themes_dir` re-themes the whole UI with no rebuild and no restart
+  beyond a `SIGHUP`.
+- Changing `instance.name` rebrands the UI everywhere.
+- The UI is usable at 380px wide.
+- Docker Compose brings up a working instance from the example config.
+- Every crate has tests; all four cargo checks pass; every commit is conventional.