Rust off Rails 0.7.3

What's new

• Snippets beside generators. cargo offrails snippets lists small, tested recipes (an Atom feed, slugs, Markdown, pagination, a theme toggle, backdated seeds, a public page by slug, a CRUD resource); snippet show prints one to read or copy, snippet add copies and wires it, snippet remove takes it back. Both snippets and generators are optional starting points.
• Generated code is small files with clear insert and remove points. A resource is a folder per layer (controllers per action pair, the model's entity, params and queries, a routes file, tests by concern), and every line it adds to a shared file is marked with the feature's name, so destroy or a person can find and remove it. Path parameters work in g controller and g page.
• Polish from one file and a component kit. brand.toml with cargo offrails brand sets the colors (contrast-checked), fonts, radius, logo, favicon set and social card; five layouts (top nav, sidebar, marketing, auth, docs); a kit of Askama components (forms with errors, tables, pagination, cards, modals, a confirm dialog, toasts) shown in every state at /dev/components. Generated and snippet pages are built from the kit, in a layout you pick with --layout.
• cargo offrails prove. With the app running, it screenshots every page at desktop and phone width in light and dark, checks console errors, CSP, accessibility (axe), links and sideways scrolling, and writes docs/proof/PROOF.md, which ties each acceptance criterion to its passing tests and the pages they touch.
• Invite-only sign-up is a setting. DEFAULT_SIGNUP in src/config.rs (or APP_AUTH_SIGNUP=open|invite) closes sign-up for every sign-in method, and app task auth_invite <email> lets people in; cargo offrails new … --invite starts an app that way.
• Security review fixes (template, tooling and guides): an unset APP_ENV now refuses to boot instead of defaulting to development; APP_TRUSTED_PROXY_HOPS picks which X-Forwarded-For hop is the client behind several proxies; /static marks a URL immutable only when its ?v= is the file's current digest; Cache::delete_prefix is one escaped LIKE delete; cargo offrails verify names every skipped step in its verdict and never probes a local Postgres; --pitch is validated like the title; the Claude Code hook guards canonicalize paths and match pkill behind paths, quotes and subshells, and fail closed without jq. Guides corrected: sea-orm-migration takes no lock, so exactly one process migrates per deploy; every proxy needs APP_TRUSTED_PROXY=true; blob downloads are no-store; API tokens die with a password reset and expire by default; webhook routes verify signatures; search escapes LIKE wildcards; the realtime guide says plainly that its signals/streams design is a spec the parts do not implement yet.
• Fixes from real builds and upgrades: a huge ?page= no longer crashes generated lists, an upgraded app no longer runs the previous release's cargo offrails, verify --full accepts a separate coverage toolchain, the browser smokes find any password sign-in form, the Dockerfile stops compiling dependencies twice, and offrails-check warns about hx-trigger filters that the CSP setup silently disables.

Breaking changes

• Generators and snippet add need two 0.7.3 template changes first, and refuse (naming what's missing) without them: the feature routes anchors in src/routes.rs (ROUTES becomes APP_ROUTES + TABLES; steps 3–4 below), and the component kit (templates/components/ui.html and its helpers; step 6).
• The generated file layout changed. New generations write small files per feature; destroy of a resource, model, controller, page or api generated before 0.7.3 refuses and lists its files (delete them by hand, then destroy … --forget).
• The ACCOUNTS header has new words: sign-in methods joined by +, then invite (signup → password, invite → password invite, magic-link-invite → magic-link invite). add-part reads the old ones; rewrite the line (step 8).
• Build the new release's offrails-gen in its own target directory (target/offrails-gen-<version>) when upgrading, not target/offrails-gen.
• APP_ENV is required. app … fails with APP_ENV is not set when neither the environment nor .env sets it. Every server already sets APP_ENV=production (the Dockerfile does); locally bin/setup writes APP_ENV=development to .env. CI scripts that ran the binary without it must set it.
• Config gains trusted_proxy_hops: u8 (default 1); Config::boot_warnings no longer warns about an unset APP_ENV, and env_defaulted is always false.
• No MSRV or toolchain change.

Upgrading

Follow the numbered steps below in order (each names the entry whose App migration has the details), and upgrade for the whole procedure (/offrails:upgrade runs it).

Upgrading an app to 0.7.3, in order (each step's Detect/Converge/Prove is in the entry it names below; upgrade is the whole procedure). $FW is the new framework. Build the new release's offrails-gen in its own target directory, --target-dir "target/offrails-gen-$(cat "$FW/VERSION")", never target/offrails-gen (From a real app's upgrade, below).

1. Parts first, before re-vendoring, as in 0.7.2: cargo offrails update-part <each installed part> --framework "$FW" --dry-run, then without it. The parts are synced from samples 2bc93ad (Parts below: invite-only as a switch, paths::after_sign_in()/account() in their tests, the mailbox, phone widths). An app on 0.7.1 or older runs the new release's offrails-gen for this one step (upgrade step 6).
2. Re-vendor: cargo run -q --manifest-path "$FW/tools/offrails-gen/Cargo.toml" --target-dir "target/offrails-gen-$(cat "$FW/VERSION")" -- vendor --framework "$FW". cargo offrails snippets, snippet …, path params, --layout and new --invite now work.
3. Feature routes files (Generators → App migration): src/routes.rs gets route mods and route tables anchors and ROUTES becomes APP_ROUTES + TABLES. Required before the first generate resource|controller|page|api or snippet add (they refuse and name the anchor without it).
4. The route sweeps fill any {param}, and the mounted-route check reads src/routes/ (same entry): required with the step above.
5. samples: app js at the end of static/app.js (Snippets → App migration): required before snippet add theme-toggle.
6. The component kit (Polish and proof → App migration, Layouts and components, and Generators and snippets on the kit → App migration): required before generate resource|controller|page (they refuse without it, naming the files) and before snippet add resource|pagination|public-show-by-slug. brand.toml, the other layouts and prove stay optional.
7. Template fixes (Template → App migration, and From a real app's upgrade → App migration): the ?page= clamp (do this one: every generated index answers a huge page with a 500 otherwise), the pending-migration and seed tests, the AGENTS.md placeholder, COPY .cargo .cargo in the Dockerfile's dependency layer, the .scroll box in static/kernel/admin.css. Each is independent.
8. The ACCOUNTS header (Accounts → App migration): rewrite it in the new grammar (signup → password, invite → password invite, magic-link-invite → magic-link invite); an invite-only app sets DEFAULT_SIGNUP = Signup::Invite (after step 1 brought auth-core's switch).
9. Generations recorded before 0.7.3 keep working as code; destroy of a resource/model/controller/page/api from before refuses and lists its files (Generators → App migration).
10. Optional polish (Polish and proof → App migration): brand.toml (cargo offrails brand --init), the layouts, and cargo offrails prove, which verify --full runs when BASE is set.
11. Security review (Security review fixes, above): Add trusted_proxy_hops: 1 to any hand-built Config literal (Config::test() has it). Set APP_TRUSTED_PROXY_HOPS where more than one proxy appends to X-Forwarded-For. Replace the an_unset_app_env_warns_at_boot unit test with an_unset_app_env_refuses_to_boot in tests/app/kernel_test.rs (config.md shows it).
12. Prove it: cargo offrails verify --full is green on SQLite and Postgres, sh .offrails/tools/offrails-check reports 0 errors, BASE=… cargo offrails prove says proven, and docs/decisions.md has YYYY-MM-DD: upgraded to framework 0.7.3.

Full list of changes

• Snippets: small, tested code to copy (snippets). The human, after a timed blog build on 0.7.2 (43 min, most of it friction, ~2,240 hand-written lines): "make generators kinda optional, i guess i still prefer snippets to generators... or generators that have good insertion or removal points. ideally multiple smaller files." The blog had hand-written (or fought) a feed, slugs, Markdown, the pager, a theme button, backdated seeds and a public page by slug. Each is now a snippet in template/snippets/<name>/: a README (what, when, the files, the anchors it wires into, how to remove it), a snippet.toml in a part's sample.toml format (plus as, the model --as renames, and snippets, the snippets it builds on) and files/ at app paths.

  • The eight: resource (htmx CRUD for notes, public: exactly the files g resource notes title:string body:text --public writes; a test in offrails-gen keeps the two identical), atom-feed (GET /feed.xml, escaped by Askama, RFC 3339 dates, newest 20, <link rel="alternate"> on every page), slug (slugify, accents folded, 80 chars; unique(base, query): -2, -3…, per owner or global), markdown (pulldown-cmark + ammonia; tests for <script>, on*=, javascript:, iframes, styles), pagination (Pager and shared/_pager.html, per kept, the ?page clamp), theme-toggle (an app-side partial and one delegated handler in static/app.js; no-JS POST to /theme; a test that the script and the server agree on the cookie), seed-backdated (backdate::<E>(db, id, days_ago(30)) after the model's create; it needs no resource: its test makes a table of a generated table's shape, so it adds to an app whose resources are generated and owner-scoped, which refused before because it required the resource snippet, found by the 0.7.3 blog build), public-show-by-slug (GET /read/notes/{slug}: a route with a path param end to end, a nullable unique slug column, slugs that never move; it builds on the resource snippet's public notes, and its README says how to do the same for a generated owner-scoped resource, which it doesn't take).
  • The CLI: cargo offrails snippets (list, with what each needs and whether it's in), snippet show <name> (the README, every file, every wire: to read or copy by hand), snippet add <name> [--as <model>] [--dry-run], snippet remove <name>. add is a recorded generation (kind snippet in docs/generated.toml): checked first (anchors, files in the way, the parts and snippets it needs), re-adding is a no-op, remove deletes the unchanged files and the marked lines. --as article renames on word boundaries (note/notes/Note/Notes: NoteParams, /notes/{id}, "Note was saved"), one-word names.
  • CI: tools/ci/test-template.sh snippets adds every snippet (resource twice: as notes and --as article) into a bare app and into an app with every part, runs fmt, clippy, the suite on SQLite and Postgres and offrails-check, re-adds each (no-op), removes them all in reverse and checks the app is byte-for-byte the baseline; it refuses a shipped snippet missing from its list.
  • App migration: Detect: grep -c "samples: app js" static/app.js is 0. Converge: add // samples: app js as the last line of static/app.js (its comment words must pass public_scripts_have_no_comment_words_zap_flags: the template's line above it reads "More behaviors (snippets, your own) go above this line, each one delegated listener."). The other snippets need only the 0.7.3 routes anchors (Generators below). Prove it: cargo offrails snippet add theme-toggle --dry-run lists its wires and refuses nothing.

• Generators: optional, small files per feature, clean insertion and removal points (generators). AGENTS.md prime directive 2 was "Generate before you hand-write"; it is now "Start app code from a snippet or a generator (both tested, both yours once copied); hand-write the rest." Neither is mandatory. The same message in CHEATSHEET, workflow (the loop's PLAN and START steps), new step 8, the app AGENTS.md blueprint, the feature, generate, scaffold and new skills, RAILS_MAP, template, cli; no doc says "generate before you hand-write" any more.

  • The split, and why this one. A resource used to be one 400–900-line controller, a 300–500-line model, one 250-line request test, and rows inserted into the big src/routes.rs. Now (g resource posts …): src/controllers/posts/{mod,index,show,new,edit,destroy}.rs (one file per action pair: new.rs is new + create and edit.rs is edit + update, because each pair shares its form, its 422 re-render and its imports, and splitting them would duplicate both); src/models/post/{mod,params,queries}.rs (the entity and its relations; the untrusted input and its validation with its unit tests; the queries, which are what a reviewer audits for scoping); src/routes/posts.rs (its router, paths:: helpers and ROUTES rows); src/views/posts.rs (one file: the page structs are small); templates/posts/*; tests/app/posts/{mod,read_test,write_test,access_test}.rs (read, write, and who-may: the access tests are the security review's); tests/app/factories/post.rs. Each file is under ~150 lines for a typical model (a 12-field model's params.rs is longer: validation is per field). Rejected: one file per action (seven files for one form, imports repeated seven times), and per-feature crates (one crate is one compile unit; a workspace per feature would multiply link times). Callers see one module either way (post::find_for, post::PostParams, factories::post).
  • Routes per feature. ROUTES is now APP_ROUTES (the kernel's and the parts' rows, as before) followed by each feature's table, listed in TABLES and concatenated at compile time by two const fns, so it stays one &[Route] that every test, app routes, docs/routes.md and the parts' own tests iterate unchanged. Generators (and snippets) wire a feature with one line at each of samples: route mods, routes, paths and route tables. g controller, g page and g api (the API kernel's routes in a shared src/routes/api.rs, each resource in src/routes/api_v1_<p>.rs) do the same. g page is one set of files per page (src/controllers/pages/<page>.rs, src/views/pages/<page>.rs, tests/app/pages/<page>_test.rs) instead of functions appended to shared files.
  • Every wiring line names its owner. A one-line statement or declaration ends with // posts ({# posts #} in HTML); a list element, field, match arm or block gets a // posts line above it (rustfmt aligns a comment that follows a trailing one in a list, and drags it onto the anchor). Declarations (pub mod x;, pub use …;) are inserted in sorted position, because rustfmt reordering a marked last line moves its comment onto another line (found by the CI: pub mod recurring; // notify_post_published). destroy, and a human, find a feature's lines by name; adding touches a shared file only through these one-line inserts (two for a factory, a few in the tenancy suite and the parent model's has_many). Golden files and the byte-identical-after-destroy CI keep both guarantees.
  • Path params for g controller and g page: g controller blog index show:/blog/{slug} (or --path /blog/{slug} for one action), g page profile --path /people/{handle}. The handler takes Path(slug): Path<String> ({id} and {…_id} are i64; several: a tuple), the page struct gets the field (escaped by Askama), the helper is paths::blog_show(slug: &str), the test requests paths::blog_show("example") and finds it on the page. A page with a parameter gets no sitemap entry; a signed-in page with one is listed in the tenancy suite's NOT_TENANT_IDS. --nav refuses a first action with parameters.
  • The generated HTML is in two files, tools/offrails-gen/src/generate/files/html/resource.html and pages.html (one section per piece: the index, its header and cells, show and its rows, new, edit, the form, each control, the nav link, the controller and page templates), with __NAME__ tokens, instead of format strings inside the generators. Swapping the markup is editing those two files; the golden files show the result. The split itself was byte-identical (the goldens didn't move); the kit came next (Generators and snippets on the kit, below).
  • Other generator fixes: a generated boolean checkbox has its dark: partner (accent-indigo-600 dark:accent-indigo-400); every generated index has a test that a huge ?page= answers 200; the next steps say to commit right after the run.
  • App migration:
    • Feature routes files. Detect: grep -c "samples: route mods" src/routes.rs is 0. Converge: from .offrails/template/app/src/routes.rs, copy the // samples: route mods block (after the use lines), pub type Route, pub const ROUTES (the concat line), TABLES with // samples: route tables, and the two const fns at the end; rename the app's existing table pub const ROUTES: &[(&str, &str, &str, Access)] = &[ to const APP_ROUTES: &[Route] = &[ (its rows and its // samples: routes table stay). Prove it: cargo run -q -- routes lists the same rows as before, and cargo nextest run security_test smoke_test passes.
    • Route sweeps. Detect: grep -c "src/routes" tests/app/security_test.rs is 0. Converge: take concrete() (any other {param} becomes example, or 1 for an id) and every_mounted_route_is_in_the_routes_table (it also reads every src/routes/*.rs) from the template's tests/app/security_test.rs, and make smoke_test.rs's every_listed_route_is_routable_in_development call crate::security_test::concrete(path). Prove it: the two tests pass; after a g controller x show:/x/{slug}, both still pass.
    • Generations recorded before 0.7.3. Detect: entries in docs/generated.toml of kind resource, model, controller, page or api without layout = "2". Converge: nothing, if you keep them (the code is yours; it compiles as it is). To remove one, destroy refuses with its file list: delete those files and its lines in the shared files by hand, then cargo offrails destroy <kind> <name> --forget drops the record. Migrations, jobs, mailers, channels and tests from before destroy as they did. Prove it: cargo offrails g resource … of a new feature writes the split layout, and destroy of it leaves git status clean.
    • Agents. Log in docs/decisions.md: YYYY-MM-DD: snippets and generators are optional starting points (framework 0.7.3); features are small files per feature with owner-marked wiring.
  • Changed code: tools/offrails-gen (generate/feature.rs routes files and path params, generate/snippet.rs, plan.rs markers and sorted inserts, model.rs/resource.rs/controller.rs/page.rs/api.rs the split, routes_md.rs reading every routes file, golden files for path params and a test that the resource snippet is the generator's output).

• The blog build's friction, fixed in the framework (the list from the 0.7.2 rebuild; the samples-repo items, invite-only auth, the parts' hard-coded /account, the dev mailbox's "CODE 2026" and the AI briefing card, came with the parts sync below):

  • Template: Page clamps ?page= to 1..=Page::MAX_PAGE (100 000): ?page=18446744073709551615 overflowed (page − 1) × per, a panic and a 500 on every generated index (unit test a_huge_page_is_clamped_not_overflowed; generated a_page_past_the_end_is_empty). The production pending-migration test requests /robots.txt, not / (an app's home that reads a generated table broke it). tasks_run_by_name_and_refuse_unknown_ones runs seed under a development config (seeds may refuse outside development). static/app.js ends with the samples: app js anchor.
  • new: the generated AGENTS.md no longer shows the raw {{TS modes only…}} placeholder; --pitch also replaces the home page's sentence, the sentence forms (description, home) are capitalized with their period, and the tagline is one value, brand.toml's tagline (the pitch capitalized, without its period), which config::APP_TAGLINE now is (pub const APP_TAGLINE: &str = crate::brand::TAGLINE;), so the home page title, the social card and a nav that shows the tagline agree (--pitch wrote the pitch as typed, often lowercase, into APP_TAGLINE beside brand.toml's capitalized sentence, which nothing but the social card read; found by the 0.7.3 blog build; unit tests check the template still has every token and APP_TAGLINE is the brand's); a pitch with quotes, braces or angle brackets is refused; on macOS it writes target/.metadata_never_index so Spotlight doesn't index build output.
  • Browser smokes: smoke-dev-tools.mjs accepts the dev mailbox's test button landing on the message it sent (dev-mailbox 0.7.2+) as well as on the list; smoke-dev-tools.mjs judges Clear all, Back and Forward by the cleared messages' ids, not by an empty list (in verify --full with an auth part, the other smokes' sign-ins send "New sign-in" emails at the same moment, and Back/Forward failed on them; found verifying a 0.7.3 app with every auth part); run.sh copies each run's scripts into its own directory (parallel smokes overwrote a shared lib.mjs while another read it) and exits 77 (skip) when Node is older than 22.12; verify reports the kernel-page smoke and the a11y smoke as skipped on 77, never failed or passed. The a11y smoke finds axe-core the way Node finds puppeteer-core, from the nearest node_modules up (the cache): lib.mjs read ./node_modules/axe-core next to itself, which the per-run copy doesn't have, so verify --full's "browser a11y" failed with ENOENT on every app (found by the 0.7.3 blog build); test-template.sh prove now runs run.sh a11y with a scenario, as verify does. The puppeteer smokes (run.sh dev-tools | live-tabs | login | a11y) find Chrome the same way as the CDP smokes (cdp.mjs: CHROME_PATH/CHROME, else the usual places on macOS, Linux and Windows) instead of defaulting to the macOS path, and skip (exit 77) when there is none.
  • Coverage with Homebrew's rust: verify --full points cargo-llvm-cov at Homebrew's llvm (LLVM_COV, LLVM_PROFDATA) when the active rustc's sysroot has no llvm-tools (rustc --print sysroot, then lib/rustlib/<host>/bin/llvm-cov) and they aren't set (testing). Deciding by whether rustup exists, as first written, missed the common case found by the 0.7.3 blog build: rustup installed but Homebrew's rustc first on PATH, where llvm-cov failed until both were set by hand (unit test llvm_tools_are_looked_for_in_the_active_sysroot).
  • Flaky tests show why: verify runs nextest at --status-level retry, so a test that fails and then passes on retry keeps its failed attempt's output in target/verify/tests-*.log (before, only the FLAKY line), and the template CI prints that output when a flaky test is not a known one.
  • Docs: SMOKE_EMAIL/SMOKE_PASSWORD (and SMOKE_PATHS) in the Definition of Done table; the assert_text apostrophe gotcha (it escapes like Askama, so literal template text needs assert_contains; testing, CHEATSHEET 26); one span rule everywhere (skip_all on actions and public model fns, level = "debug", skip_all on per-row helpers; errors-and-logging, CHEATSHEET 27); commit after each generator or snippet run (workflow, generators); how a sub-agent hands a running dev server back (detached with nohup, its PID file and log, cli); upgrade step 6's 0.7.1 caveat for update-part; authentication rewritten around the auth parts (what they do, what's left: invite-only, roles, teams), and new (steps 2–3 and Tests) and auth point at the parts too: they still said authentication.md builds the guard and tenancy suites (the first owner-scoped g resource writes them) and "generates" accounts (found by the 0.7.3 blog build); routing, structure, models, testing and controller for the new layout.
  • A framework checkout is vendored from HEAD, and says so. new §1 told agents to export "the tag matching VERSION", which on a release branch before tagging is the previous release (the 0.7.3 blog build vendored git archive 044d7eb by hand and logged why). new, vendor and update-part now handle a --framework/OFFRAILS_FW (or the generator's own root) that is a git checkout themselves: they use HEAD's committed files (git archive HEAD | tar -x, as tools/release/release.sh builds the tarball), never the working tree (uncommitted changes are named and left out), and new/vendor write the commit as .offrails/VERSION's third line and in the new log line: from git v0.7.3 (<sha>) at the tag, from git <sha> (unreleased: HEAD is not the v0.7.3 tag; VERSION names the last release) past it. VERSION's first line (and the FRAMEWORK header) stay the version, so offrails-check and upgrade --check read it as before; release installs (the plugin, ~/.offrails/current, a tag export: no .git) are copied as before, with nothing added. --worktree uses the working tree as it is, recorded as such: test-template.sh passes it, since CI tests uncommitted changes (unit test a_framework_checkout_is_vendored_from_head_with_its_commit; upgrade).
  • CI: test-template.sh takes OFFRAILS_CI_TAG (a suffix for the apps' crate names, so two checkouts' runs on one Postgres server never share test databases) and OFFRAILS_CI_PORT (the smokes' first port).
  • App migration:
    • The ?page clamp. Detect: grep -c MAX_PAGE src/models/mod.rs is 0. Converge: in Page, add pub const MAX_PAGE: u64 = 100_000; and make number() self.page.unwrap_or(1).clamp(1, Self::MAX_PAGE); copy the template's a_huge_page_is_clamped_not_overflowed test. Prove it: curl -s -o /dev/null -w '%{http_code}' "$URL/<a list>?page=18446744073709551615" prints 200.
    • Tests that assume the home page and the seed. Detect: grep -n 'app.get("/").await.assert_ok()' tests/app/kernel_web_test.rs inside production_with_a_pending_migration_is_unhealthy_but_serves, and TestApp::new() in tasks_run_by_name_and_refuse_unknown_ones. Converge: /robots.txt there; TestApp::with_config(Config { env: AppEnv::Development, ..Config::test() }) here. Prove it: both pass.
    • AGENTS.md. Detect: grep -c "TS modes only" AGENTS.md. Converge: delete {{TS modes only: ", or :5173 via Vite"; htmx: nothing}} (htmx), or replace it with , or :5173 via Vite (inertia, spa). Prove it: grep -c "{{" AGENTS.md is 0.
    • The smokes, verify and the docs arrive with re-vendoring; nothing to converge.

• Polish and proof: one file rebrands the app, five layouts, a component kit, and cargo offrails prove (views, testing). The human: "make it quick and easy to polish an app ... layout, branding ... components ... FOR AI. how to make agents move fast and precisely, and test, take screenshots, build a guide proving what they build works."

  • brand.toml + cargo offrails brand (std-only, in offrails-gen; new runs it). Name, tagline, primary/accent/neutral colors, optional on_primary, font stacks, radius, and the logo (a 1–2 character mark or a square SVG). It renders assets/brand.css (Tailwind @theme: primary-* and accent-* scales built in OKLCH with 600 exactly the brand color, gray-* = the neutral, indigo-* = primary so parts and older templates follow, on-primary, primary-hover, fonts, radius; semantic --brand-* tokens for light and dark), src/brand.rs (NAME is now config::APP_NAME; THEME_COLOR feeds the theme-color meta; brand::email::* colors, and the mailer part's header is pointed at them), static/favicon.svg, and the social card assets/brand/og.svg. Before writing anything it checks 16 text/surface pairs the components use (body, muted, links, badges, button text and its hover; light and dark) against WCAG AA 4.5:1 and refuses with the pair, its ratio and a color that passes; the scales are built so that the shades holding text pass for any base color (a yellow brand gets near-black button text). PNGs (favicon.ico, apple-touch-icon.png, icon-512.png, og.png) are rasterized by the installed Chrome/Chromium/Edge (headless) or rsvg-convert; with neither the SVGs are current and it says the PNGs aren't (no image crate: a text mark needs a font rasterizer). --check fails when a generated file is stale (verify --full runs it). tools/brand/render.sh is superseded (kept for apps without a brand.toml; assets/brand/og.html left the template). 24 unit tests (color math against WCAG reference values, scales, contrast refusals and fixes, the TOML subset, outputs, the ICO container, rustfmt-stable brand.rs).
  • Layouts (templates/layouts/): application.html is now the shell (head, skip link, icon sprite, overlay slots, dev footer) whose body block is the top-nav layout; sidebar.html (folds behind Menu on a phone), marketing.html (hero, nav, CTA, footer), auth.html (centered card), docs.html (table of contents beside the article). One <head> for all of them (boosted links), a skip link to <main id="main">, landmarks, dark mode, no sideways scroll at 360–390 px. Pages pick one with {% extends %}.
  • Component kit (templates/components/ui.html, one import): button (variants, sizes, icon, disabled), link_button, icon_button, confirm_button, icon; field (text/email/password/…), textarea, select, checkbox, radios (labels, hints, errors with aria-invalid/aria-describedby, values kept on a 422, passwords never echoed), form_actions; alert, flash, toast/toast_oob; card, badge, stat, table (caption, sortable header links with aria-sort, empty state), pagination (helpers::Pager), empty_state, avatar; breadcrumbs, page_header, nav_tabs, tabs/tab_panel, dropdown/menu_item; modal (native <dialog>: inert page, focus kept inside, Esc, focus returned), modal_button, modal_link (htmx-loaded, opens itself, leaves when closed), modal_close, and the layout-wide confirm dialog for every data-confirm and hx-confirm. Styles are component classes in assets/app.css (brand tokens, light + dark); behaviors are static/components.js (delegated; the data-confirm handler moved there from app.js, which now keeps aria-expanded in step for data-toggle). Every component in every state at /dev/components (?theme=light|dark), each layout at /dev/layouts/<name> (development only, Access::Dev); guides/views.md has the signatures as one table.
  • Tests: theme_test renders the gallery and the layout demos and checks every class list for its dark: partner and its rule in the built CSS; components_test (skip link, landmarks and one <head> in every layout, the 422 keeps values, sort and pagination, development only); tools/browser-smoke/smoke-components.mjs drives the modal (Tab, Esc, focus return), the htmx modal, the confirm dialog (Cancel and Confirm) and the 422 on a full load and after a boosted link; the boosted smoke covers the gallery's dropdowns, tabs, toggles and dismiss buttons.
  • offrails-check [classes] (a warning, never an error): a <button>, <input>, <select>, <textarea> or button-like <a> with more than eight utilities (CLASS_LIST_MAX) in an app template outside templates/components, kernel, mailers; {# offrails-check: classes ok #} on the line silences it. A line an installed part ships as it is (in its copy of the same file in .offrails/template/parts/<part>/files/, crate names aside: the base update-part merges from, or in a part's wiring in sample.toml, since parts wire into each other's templates, e.g. shared/_auth_nav.html) is skipped and counted (skipped N line(s) the installed parts ship): the auth parts' own password_sessions/_confirm.html, _form.html, passwords/_new_password.html, registrations/verify.html and security/not_me.html warned in every app that installed them (found by the 0.7.3 blog build); moving them onto the kit is a samples change. A line the app wrote or edited is checked. In tools/ci/test-offrails-check.sh (a part's unmodified line, an edited one, and a wired one).
  • cargo offrails prove (offrails-gen launches tools/browser-smoke/prove.mjs: Node ≥ 18 and the installed Chrome over the DevTools Protocol, the driver and browser discovery every smoke shares (tools/browser-smoke/cdp.mjs, below), no npm install; exit 77 without them). It starts nothing: with BASE set it visits every GET page of docs/routes.md (plus SMOKE_PATHS, minus SMOKE_SKIP) as the visitor who can see it (signed in as the demo account when a page sends you to sign in), takes full-page screenshots at desktop 1280 and mobile 390 in light and dark, and fails on console errors, uncaught exceptions, CSP violations, axe-core violations (WCAG 2.2 AA, light and dark; the a11y smoke's pinned axe from the smokes' cache, installed there once if missing), broken same-site links and #anchors, and sideways scroll at 390 px (naming the elements that stick out; on kernel pages, which apps don't own, a warning unless --strict: its first run on the all-parts app found the dev dashboard's requests and lab pages and /admin/jobs, /admin/jobs/cron scrolling sideways on a phone, a samples fix to make upstream). Each screenshot is diffed against the previous run's (PNG decode/encode with node:zlib, a per-pixel threshold): reported with a diff image, failing only with --strict. It writes docs/proof/PROOF.md (result, checks, pages with their four screenshots and changes, and every acceptance criterion → the tests citing it with their result from the last verify → the pages they request with screenshots) and proof.json; PNGs are git-ignored unless --commit-screenshots. verify --full runs brand --check, the component smoke and prove when BASE is set (a separate polish_steps block); workflow.md's Definition of Done has the proof row and the final message links PROOF.md.
  • Measured (M2, 8 cores, other agents building on the machine): the bare app, 9 pages, 36 screenshots, axe on 18 loads: 13 s at load ~15, 20 s (first run) and 24 s (second run, with the diffs) at load ~50; the app with every part, 63 pages (57 signed out, 6 signed in as the demo account), 252 screenshots: 165 s and 216 s at load 50–70. Its second run reported 82 changed screenshots out of 252 (the dev dashboard's live charts, timestamps, uptime): reported, not failed, as designed.
  • CI: tools/ci/test-template.sh prove (its apps' crate names take OFFRAILS_CI_TAG and its two servers the ports after the smokes', OFFRAILS_CI_PORT + 2 and + 3, like the other targets) generates the bare app and the app with every part, adds a fixture feature whose two criteria cite request tests, runs verify (SQLite + Postgres) and offrails-check, serves each in development, runs the component smoke and prove twice, and checks that PROOF.md says PROVEN, has four screenshots per page, traces AC-home-1 to its passing test and to /, that the second run compared screenshots, and that the PNGs are git-ignored. Its fixture also has a helper whose doc comment cites AC-home-2, which PROOF.md must not list: prove counted the first fn after any AC id as a citing test, so handlers and helpers whose comments name a criterion (session_delete in src/routes.rs, queries, module docs, string literals in the dev dashboard's tests) showed up as its tests (found by the 0.7.3 blog build). In Rust it now counts only test functions: a test attribute (#[test], #[tokio::test], #[sqlx::test], #[rstest], …) among the citation's attributes and comments, only those between it and the fn, and in src/ a #[cfg(test)] module (testing). Its apps use a sticky-footer layout (<body> a flex column, <main> w-full flex-1, as apps often make it), and /dev/components and every /dev/layouts/* page must be ok in PROOF.md (no sideways scroll at 390 px): /dev/components' own <main> had mx-auto without w-full, so in such a layout it shrank to its content and the table's min-content made it 396 px wide at 390 px, which prove counts as a failure (a boosted page; found by the 0.7.3 blog build). It has w-full now.

  App migration (an app on 0.7.2; optional, but verify --full runs the new steps once re-vendored):

  • Brand. Detect: no brand.toml at the app root. Converge: re-vendor, then cargo offrails brand --init (writes brand.toml with the name from src/config.rs and the description from src/views/mod.rs, without its period, as the tagline); put the app's tagline in brand.toml's tagline (the one in APP_TAGLINE, capitalized); set the colors you use (the template default primary is #4f46e5); copy @import "./brand.css"; (after @import "tailwindcss";) and @source "../static/components.js"; into assets/app.css; add pub mod brand; to src/lib.rs; set pub const APP_NAME: &str = crate::brand::NAME; and pub const APP_TAGLINE: &str = crate::brand::TAGLINE; in src/config.rs (a smoke test that asserts the home page title then sees the capitalized tagline); replace the layout's <meta name="theme-color" content="#…"> with {{ crate::brand::THEME_COLOR }}; run cargo offrails brand. Prove: cargo offrails brand --check prints "is current" and cargo nextest run theme_test passes.
  • Layouts and components. Detect: no templates/components/ui.html. Converge: copy from .offrails/template/app/: templates/components/, templates/layouts/{sidebar,marketing,auth,docs}.html, templates/shared/{_brand,_notices,_sidebar}.html, static/components.js, the component layer of assets/app.css (keep your own classes), src/views/helpers.rs's component helpers (same, tone_icon, initials, PageNumber, Pager), the components_js asset (src/kernel/assets.rs: the field and the "components.js" key in the same position), and the gallery (src/controllers/gallery.rs, src/views/gallery.rs, templates/dev/, its routes in controllers/dev.rs, ROUTES and paths); then make templates/layouts/application.html the shell: wrap its nav-and-main in {% block body %}…{% endblock %}, give <main> id="main", and add the skip link, {% include "components/_icons.html" %}, {% include "components/_overlays.html" %} and the components.js script as the template's does (keep the samples: anchors). Delete the data-confirm listener from static/app.js (components.js has it). Copy tests/app/components_test.rs and the gallery test in tests/app/theme_test.rs. Prove: cargo offrails verify, then with bin/dev running BASE=… node .offrails/tools/browser-smoke/smoke-components.mjs.
  • Proof. Detect: cargo offrails prove --help is unknown. Converge: re-vendor. Prove: BASE=<bin/dev's URL> cargo offrails prove prints proven and writes docs/proof/PROOF.md; link it in your final message from now on. Log YYYY-MM-DD: upgraded to framework 0.7.3 (brand.toml, layouts, component kit, prove) in docs/decisions.md.

• Generators and snippets build their pages from the component kit, in a layout you pick (generators, views). The two branches met here: the generators' markup had just moved into files/html/{resource,pages}.html, and the kit had just landed. Every generated page now calls the kit, so it follows brand.toml, both themes and the kit's accessibility, and offrails-check [classes] finds nothing in it (0 warnings on an app with a resource of every field type, a references chain, pages and controllers; was 0 before too, but only because the old markup was hand-checked).

  • Index: ui::page_header with a ui::link_button ("New post", plus icon); ui::table (caption, the list's columns; the actions column is gone: Edit is on the show page) or, empty, ui::empty_state with its call to action; ui::pagination with pages() = this page + 1 when the query found more (the generated all returns more, no COUNT) and page_base(). Before → after (templates/posts/index.html, abridged):

    <div class="flex flex-wrap items-end justify-between gap-4">
      <h1 class="text-3xl font-semibold tracking-tight">Posts</h1>
      <a href="{{ paths::new_post() }}" class="btn">New post</a>
    </div>
    {% if posts.is_empty() %}<p class="mt-10 rounded-xl border border-dashed … p-10 text-center …">No posts yet. …</p>{% else %}
    <div class="mt-8 overflow-x-auto rounded-xl border …"><table class="min-w-full divide-y …">…</table></div>{% endif %}
    {% if newer().is_some() || older().is_some() %}<nav …>← Newer … Older →</nav>{% endif %}

    {% import "components/ui.html" as ui %}
    {% call ui::page_header("Posts") %}{% call ui::link_button("New post", paths::new_post(), icon = "plus") %}{% endcall %}{% endcall %}
    {% if posts.is_empty() %}{% call ui::empty_state("No posts yet", "Create the first one.", "New post", paths::new_post()) %}{% endcall %}
    {% else %}{% call ui::table("Posts, newest first", [("", "Name"), ("", "Title")]) %}<tr id="post_{{ post.id }}"><td>…</td></tr>{% endcall %}{% endif %}
    {% call ui::pagination(page, pages(), page_base()) %}{% endcall %}

  • Show: ui::page_header with Edit (link_button) and Delete (ui::confirm_button, the layout's confirm dialog); the fields in a ui::card. New/edit: ui::page_header and the form in a ui::card. Form: ui::field (text, number with step/inputmode, decimal, money with a 0.00 placeholder, datetime-local, date, a monospace uuid), ui::textarea (text; json monospace), ui::checkbox (boolean), ui::select (an optional boolean: Not set/Yes/No; a reference: its choices), each with its label, the required mark, aria-invalid/aria-describedby and its errors; ui::form_actions (Save, Cancel). g controller / g page: ui::page_header and the placeholder paragraph. The flash is the layout's: shared/_flash.html is now the kit's ui::flash (dismissible).
  • --layout application|sidebar|marketing|auth|docs on g resource, g controller and g page (default application, the top nav; recorded as page_layout in docs/generated.toml, so a re-run and destroy see the same pages). A layout the app doesn't have is refused.
  • The kit, for generated forms: field takes maxlength, inputmode, step, mono (monospace, no autocorrect) and key (the errors' key when it isn't the input's name: a book_id select reports on book); textarea takes mono and key; select takes key, and its option values may be ids (helpers::same compares any Display, so Vec<(i64, String)> choices work as they are); page_header's title wraps (break-words). helpers::error_key is new, with unit tests.
  • Snippets: resource is re-exported from the generator (the unit test that it equals g resource notes title:string body:text --public still passes); pagination is views::pager::PageLinks { number, pages, base } (renamed from Pager, which is the kit's helper) and shared/_pager.html is one ui::pagination call (?per= kept in base, tests for the links, per, the clamp and the partial); public-show-by-slug's page uses ui::page_header; theme-toggle's button is the kit's btn-ghost btn-sm (the kit has no theme switch of its own; it had 11 utilities, an offrails-check [classes] warning).
  • Proof: the goldens (resource_items, page_about, page_profile_param, controller_reports, controller_blog_params) show every page; an app with a resource of every field type, a references chain, a docs-layout page and a sidebar-layout controller: 194 tests green, theme_test included, 0 [classes] warnings, the boosted smoke and the component smoke green, prove proven (24 pages, 96 screenshots, show and edit pages through SMOKE_PATHS); test-template.sh generators and snippets keep the byte-identical-after-destroy/remove checks.
  • App migration: Detect: grep -c error_key templates/components/ui.html src/views/helpers.rs is 0 (or no kit). Converge: copy templates/components/ui.html and src/views/helpers.rs's same and error_key (and their test lines) from .offrails/template/app/, and templates/shared/_flash.html. Pages generated before keep their markup (they're yours); g resource of a new feature writes the kit's. Prove it: cargo offrails g resource probes name:string --public --dry-run refuses nothing, and after a real run and cargo offrails verify, destroy resource probes leaves git status clean.

• One browser driver for the zero-dependency smokes (tools/browser-smoke/cdp.mjs). smoke-boosted.mjs and prove.mjs each carried their own copy of the Chrome discovery, the DevTools Protocol pipe and the tab (console errors, CSP, eval, goto, settle), and smoke-components.mjs imported prove's. Now all three import findChrome, requireChrome (skip: no Chrome, exit 77), launch (a throwaway profile, headless, Linux CI's --no-sandbox, closed and deleted afterwards), Cdp, Tab (viewport, screenshot, an ignore pattern, the boosted smoke's phase prefix) and signInPost from it. selftest-boosted.mjs (4/4) and selftest-prove.mjs pass; the three smokes and prove are green against a bare app and one with every part.

• From a real app's 0.7.1 → 0.7.2 upgrade (1,530 tests, green after it; six things it tripped on):

  • Release fixes: a stale cargo offrails after an upgrade. Every file in the release tarball had mtime 2000-01-01, older than an app's cached offrails-gen binary, so Cargo reused the previous release's (update-part: "unknown command" until target/offrails-gen was deleted). tools/release/release.sh now stamps the files with the release commit's time (still deterministic), install.sh unpacks with tar -m (the files get the time they were unpacked), offrails-gen's Cargo.toml version follows VERSION (it's in Cargo's fingerprint; release.sh refuses a mismatch; the README's release steps say so), and upgrade builds the new release's offrails-gen in target/offrails-gen-<version>.
  • verify --full and a coverage toolchain. With RUSTUP_TOOLCHAIN set for cargo-llvm-cov (a toolchain with llvm-tools, often without rustfmt or clippy), fmt and clippy failed. That toolchain (or OFFRAILS_COVERAGE_TOOLCHAIN) now goes to the coverage step only; every other step runs without it, and verify says so (unit test the_coverage_toolchain_is_for_the_coverage_step_only; testing).
  • The smokes find the sign-in form. smoke-boosted.mjs and prove signed in only when docs/routes.md had POST /session/password; that app signs in at POST /session. They now try when it has /session/password, /session, /sessions, /login, /sign_in or /users/sign_in, or SMOKE_SIGNIN_PATH names the route, and submit the password form found on SMOKE_LOGIN, whatever its action (testing).
  • run.sh dev-tools needed a visible /dev link on /. It opens /dev directly, in a desktop window; each "Send test email" must land on /dev/mailbox/<id> with the flash "Sent a test email to your mailbox." and the list must show at least 3 rows (the mailbox's current markup, #mbx-list); the jobs steps run only when /dev has a test-job button (no part has one now: it says skip) (dev-tools).
  • The template Dockerfile compiled every dependency twice: its dependency layer had no .cargo/, so it and the final build used different rustflags. It now copies .cargo before building the dependencies.
  • hx-trigger filters never fire. keyup[key=='Enter'] needs eval, which the template's htmx-config turns off for the CSP (allowEval:false), so the trigger silently does nothing. A gotcha in frontend-htmx and CHEATSHEET 28, and offrails-check [htmx] warns on a filter in templates/ (a fixture case in test-offrails-check.sh).
  • App migration: Dockerfile. Detect: grep -c 'COPY .cargo .cargo' Dockerfile is 0. Converge: add COPY .cargo .cargo after COPY Cargo.toml Cargo.lock ./ (before the dependency cargo build). Prove it: docker build . twice after a code change: the second build's dependency layer is cached and its final step compiles only the app. The others arrive with re-vendoring; nothing to converge (an upgrade from 0.7.2 builds the new offrails-gen in target/offrails-gen-0.7.3 once).

• Accounts: invite-only is a switch; the ACCOUNTS grammar (auth, authentication). With the parts synced below, auth-core has one switch for every sign-in method: DEFAULT_SIGNUP in src/config.rs (Signup::Open or Signup::Invite), overridden per deploy by APP_AUTH_SIGNUP=open|invite; invite-only, the sign-up pages answer 404 and their links hide (ctx.signup_open), magic links go only to existing accounts, and app task auth_invite <email> lets people in. The framework side:

  • The header names methods, then invite: ACCOUNTS: password, magic-link, password+magic-link, magic-link invite, password+totp invite. The old words map: signup = password, invite = password invite, magic-link-invite = magic-link invite. The blueprint, the interview, the auth variants table (old anchors kept for the parts' links), authentication (invite-only is a switch now, not a list of edits), template and api use it. add-part auth-password / auth-magic-link writes it, adding a method to the ones there and normalizing old words (unit test the_accounts_header_grammar_and_its_old_words).
  • new --invite: sets DEFAULT_SIGNUP = Signup::Invite and ACCOUNTS: … invite; refused without auth-password or auth-magic-link among the parts.
  • App migration: Detect: grep -E '^ACCOUNTS: +(signup|invite|magic-link-invite)\b' AGENTS.md. Converge: rewrite the words as above; an invite-only app also sets DEFAULT_SIGNUP = Signup::Invite in src/config.rs and drops any hand-made invite-only edits the old authentication told it to make (restored /registration* routes and links are hidden by the switch). Prove it: sh .offrails/tools/offrails-check passes [header]; invite-only: curl -s -o /dev/null -w '%{http_code}' $URL/registration/new prints 404.

• Parts synced from samples 2bc93ad (tools/sync-parts.sh): two auth-magic-link tests create their account first, so they pass in invite-only apps too (samples CI now reruns the auth suites with DEFAULT_SIGNUP = Signup::Invite); dev-dashboard's jobs_are_traced_with_their_sql picks its trace by request id and prints every trace it held if it fails (reported flaky once in CI, not reproduced); invite-only as the switch above (auth_invite task, Signup, SignupOpen, ctx.signup_open); part tests that use paths::after_sign_in()/paths::account() instead of a hard-coded /account; the dev mailbox's code detection (no more "CODE 2026"); the dev dashboard's AI briefing summarized on load; phone widths: a .scroll box contains its table's visually-hidden labels in dashboard.css and jobs.css, and every dashboard tab, the jobs pages, /dev and the mailbox fit 390 px. The same containment for the template's own static/kernel/admin.css (.scroll { position: relative; max-width: 100% }): prove on the app with every part reports 0 kernel pages with warnings (it listed /admin/jobs, /admin/jobs/cron and the dashboard's requests and lab pages before). App migration (admin.css): Detect: grep -n '^\.scroll' static/kernel/admin.css shows no position: relative. Converge: .scroll { position: relative; max-width: 100%; overflow-x: auto; }. Prove it: prove reports no sideways scroll at 390 px.

• Dev-dashboard flakes fixed at their cause; parts synced from samples 393408b. Three dev-dashboard tests failed once and passed on retry in this CI (a_trace_expands_inline_with_repeats_folded, jobs_are_traced_with_their_sql, the_checkout_fan_out_traces_four_upstreams; reproduced locally under parallel load, about 1 run in 300), and a fourth under the same load locally (every_tool_answers_within_its_cap: cap() kept 60 characters for its 61-character cut note, so a trace that filled the room came out one over; fixed, with a test at the boundary). Not shared on-disk state: other threads hold clones of a span, and a span closes at its last clone's drop. The SQLite driver's worker thread keeps the span each query ran in until its next command; with the tests' thread-local subscriber (set_default), a span dropped last there closed its parent through that thread's (empty) default, so the handler and the methods above the last query never closed and the waterfall had no handler row. hyper spawns the connection a request opens with the current span and pools it, so an outbound call that opened a connection lasted as long as the connection and overlapped the next calls; and the sequential-calls check wanted under 5 ms of wall clock between two calls, which a loaded machine exceeds with nothing in between. Fixed in the part: the tests' traced() installs the subscriber as the process's global default (as main does); a request trace records the spans still open when its response is done (trace::flush_open; a counter per span says whether to look); kernel::outbound sends from a task of its own (aborted with the call), so the pooled connection holds no span; calls are sequential when nothing of the handler's (a query, a method, a template) ran between them (SEQUENTIAL_GAP_US is gone); the job test pings the database (the SQLite worker answers only after it let go of the job span) before it looks. test-template.sh's KNOWN_FLAKY is empty: its two entries (run_history_is_capped_redacted_and_reopened, bench_drives_a_running_server) shared storage/dashboard/, which the part already keeps per test process, and neither has flaked in CI since; the gate (one retry, any flaky test not listed fails the run) stays. App migration (apps with the dev-dashboard part): Detect: grep -c flush_open src/kernel/dashboard/trace.rs is 0. Converge: cargo offrails update-part dev-dashboard. Prove it: cargo offrails verify --fast.

• Docs, one story across both branches: start from a snippet or a generator (both optional), build pages from the component kit in a layout, prove with cargo offrails prove. AGENTS.md (prime directive 2 and the load table), CHEATSHEET (the kit, the layouts, brand), workflow (BUILD and VERIFY), template, README, generators, scaffold, controller, views (Layout & partials and Forms rewritten on the kit; the stale layout listing, its per-page head scripts and _pagination.html are gone), testing, models. tools/ci/check-links.py counts <a id="…"></a> anchors (kept for renamed headings): 0 broken links; every shellcheck line in CI is clean.