.offrails/CHANGELOG.md

Changelog

Each entry lists convention changes and what an existing app must do about them. /offrails:upgrade reads this file, so write the App migration notes as instructions for an agent.

Every release section has the same shape, in this order, because tools/release/release.sh copies it verbatim into the GitHub Release: What's new (4–6 plain bullets: what you can do now and why it matters), Breaking changes (what an existing app must act on, or "None."), Upgrading (a pointer to the ordered steps and upgrade), then Full list of changes (the detailed entries with their App migration notes). Subsections are ###, so the release script's ## <version> ( heading match still finds the section's end.

0.7.3 (2026-10-19)

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.

0.7.2 (2026-10-18)

What's new

  • cargo offrails verify runs the Definition of Done in parallel in one command. --fast (after every change) runs fmt, clippy and the SQLite and Postgres suites at the same time; --full (once, at the end) adds coverage, cargo deny, gitleaks and the other checks. A bare app's loop after a one-line change went from 140 s to about 6 s.
  • Generators: cargo offrails generate <kind> (g) writes migrations, models, CRUD resources, controllers, pages, APIs, jobs, mailers, channels and tests that follow the guides and come with their tests. cargo offrails destroy (d) removes exactly what was generated and is still unchanged.
  • cargo offrails update-part brings a newer version of an installed part into the app with a three-way merge: clean changes apply, overlapping edits get conflict markers, and the app's own changes are never silently overwritten.
  • Faster Postgres tests: the suite migrates once into a template database and reuses locked slot databases reset before each test, instead of creating and migrating a database per test.
  • A browser smoke for boosted navigation catches page JavaScript that works on a fresh load but is dead after a boosted link. Page scripts now load from the layout and bind by delegation.
  • Template speed-ups: one CI test job instead of two, a cached Docker dependency layer, and a cached development CSS check.

Breaking changes

Nothing is required to keep an existing app working. Before using the new tools:

  • Generators need the // samples: anchors in the shared files; a generator that lacks one refuses and names it.
  • The route-sweep tests (smoke_test.rs, security_test.rs) must send each route's own method before the first cargo offrails g api.
  • Parts updated to this release load their page scripts at a new samples: app head anchor in the layout.
  • split-debuginfo left [profile.dev] in the template; an app built on Windows must remove it too.

Upgrading

Follow the ordered list below; each step's Detect/Converge/Prove is in the entry it names under Full list of changes, and upgrade is the whole procedure. $FW is the new framework.

  1. Parts first, before re-vendoring: update-part merges against the part as installed in .offrails/, so run it while .offrails/ is still the old release: cargo offrails update-part <each installed part> --framework "$FW" --dry-run, then without --dry-run. Resolve any <<<<<<< markers, then cargo fmt --all and cargo run -q -- db migrate. (An app on 0.7.1 or older has no update-part yet: run the new release's, cargo run -q --manifest-path "$FW/tools/offrails-gen/Cargo.toml" -- update-part <part>… --framework "$FW" --app ..)
  2. Re-vendor: offrails-gen vendor --framework "$FW". cargo offrails verify, generate, destroy and update-part now work.
  3. Generator anchors (Generators → App migration): add every missing // samples: anchor. A generator that needs a missing one refuses and names it, so this can wait until the first generate.
  4. Route sweeps send each route's own method (same entry): required before the first cargo offrails g api.
  5. Optional speed-ups (Fast loop → App migration): Postgres test slots, the CSS check cache, the split-debuginfo move (needed for Windows builds), and the one-job CI.
  6. Prove it: cargo offrails verify --full is green on SQLite and Postgres, sh .offrails/tools/offrails-check reports 0 errors, and docs/decisions.md has YYYY-MM-DD: upgraded to framework 0.7.2 plus the generators line.

Full list of changes

  • A fast loop: cargo offrails verify (workflow). A human, after a 41-minute agent build and 4+ minute CI runs: "we need CI to run in 10 seconds or less, can't we parallelize or something". The Definition of Done ran sequentially (fmt, clippy, SQLite suite, Postgres suite, coverage, deny, gitleaks, browser smokes), and the docs had agents run all of it after every change. Now one cross-platform command (in offrails-gen, so cargo offrails verify works in every template app) runs it in parallel:

    • --fast (default; after every slice): cargo fmt --check, the CSS build (htmx), clippy -D warnings in its own target dir (target/clippy, so it compiles while the tests build), the test binaries once, then the SQLite and Postgres suites at the same time (nextest; Postgres runs the integration tests, since unit tests never read TEST_DATABASE_URL). One line per step with its time and test counts, the tail of each failure, logs in target/verify/, non-zero exit on any failure. Postgres comes from TEST_DATABASE_URL (environment or .env) or the compose URL when localhost:${DB_PORT:-5432} answers; otherwise it says skipped.

    • --full (once, at the end): also offrails-check, coverage (it is the SQLite run, instrumented with cargo llvm-cov nextest --fail-under-lines 80), cargo deny, gitleaks, the no-unwrap/expect review, routes vs docs/routes.md, the TS checks when there is a web/, and the browser smoke when BASE names the running app. Missing tools are reported as skip with the install command, never as passed.

    • The guidance changed with it: workflow (the loop's VERIFY step, the Definition of Done, "iterate fast, verify fully once": one test with cargo nextest run <name> while red, verify after each slice, coverage/deny/gitleaks/full browser smokes only in --full), CHEATSHEET, /offrails:check, the app AGENTS.md blueprint, new step 5, offrails-gen new's next steps, tools/ci/test-template.sh (now runs verify, still failing on any flaky test outside its known list).

    • Measured on generated apps (Apple M2, 8 cores, macOS; other agents were compiling on the same machine the whole time, so each row gives the load average, and old and new were run back to back under the same load). "Old" is 0.7.1's template and its sequential Definition of Done; "new" is this release.

      StepBare, oldBare, newEvery part, oldEvery part, new
      Cold build (cargo build, then the test targets)217 s + 38 s (load 22–45)same dependencies, same180 s + 59 s (load 31–53)same
      Cold build, a second app on the machine293 s (load 121)128 s with sccache (opt-in; load 127)n/mn/m
      No-op rebuild of the tests0.5–0.7 ssame0.65 ssame
      One-line change, test build3.7–5.4 s (load 40–65)3.2–3.8 s inside verify (load 11)12.3 s (load 36)12.2–15.9 s inside verify (load 9–11)
      Clippy after a one-line change1.9 s1.1–2.3 s, beside the build8.1 s7.7–9.5 s, beside the build
      SQLite suite1.3 s (121 tests)1.4 s8.0–10.4 s (652 tests)8.5–9.5 s
      Postgres suite8.0 / 11.9 s (load 15–18)1.7 / 1.8 s149 / 46 s (load 12–37)21 / 14 s (load 17–20)
      The fast loop: fmt, clippy, test build, SQLite, Postgres after a one-line change140 s, sequential (load 19–33)5.5–6.7 s (verify, load 11)76–179 s, sequential (sum of the rows above)33.5–36.5 s (verify, load 9–11)
      The whole Definition of Done after a one-line change (+ offrails-check, coverage, deny, gitleaks)157.7 s (load 19–33)20.1 s (verify --full, load 14–18)not run (the instrumented build needs another ~5 GB; the disk was full)—

      Where an all-parts app's 34 s go: the test build (~12 s, the app crate compiled as lib and as lib-test in parallel, then the test binary), then the Postgres suite (~20 s beside SQLite, ~14 s alone; 461 integration tests, the longest single tests 4–5 s of real timeouts in the parts' own tests). The 10 s target holds for the bare app, not for one with every part.

  • Postgres tests: no CREATE DATABASE and no migrations per test (testing). Each test used to create test_<crate>_<uuid>, migrate it and drop it. CREATE DATABASE copies and fsyncs a template (measured on this machine under load: 1.2–3.8 s for one empty database), so the Postgres run degraded badly when the machine was busy (a 541-test blog: 42.5 s quiet, 335 s at load ~68). Now support.rs migrates once into test_<crate>_<tag>_tpl (<tag>: a hash of the migration names and files, so an edited migration builds a new one; built under an advisory lock and renamed into place, so concurrent first tests wait and a killed build leaves nothing half-migrated), each concurrent test locks a slot test_<crate>_<tag>_<n> (pg_try_advisory_lock), cloned from the template once and reused across tests and runs, with synchronous_commit = off, and offrails_test.reset() puts the slot back to the just-migrated state before every test: tables with rows truncated, the migrations' seed rows and every sequence restored. A schema fingerprint makes the reset refuse a slot a test changed (rolled a migration back, created a table), and the harness re-clones it. Still every test on both databases, isolated. Also evaluated: a rollback transaction per test (rejected: the app's own transactions, the job worker and realtime use other connections) and CREATE DATABASE … TEMPLATE per test (keeps the fsync cost). SQLite stays in-memory and migrated per test: the migrations are ~5 ms of a ~40 ms median test. The new SQL is in kernel::db (database_exists, create_database_from, rename_database, advisory_lock/try_advisory_lock/advisory_unlock, skip_commit_flush, install_test_reset/reset_test_database, drop_idle_stale_test_databases), with a kernel test (the_postgres_test_reset_empties_tables_and_refuses_a_changed_schema).

  • The development CSS check is cached (views). kernel::css::css_warning read every template and the built CSS on every development page (~85 ms in a grown app; 97% of the CPU under load). It now recomputes only when a template, assets/app.css or static/app.css changes (size and mtime), with a unit test.

  • Template CI: one test job (testing). The sqlite and postgres jobs each compiled the tests; the new test job runs cargo offrails verify --fast against a Postgres service on tmpfs, with rust-cache keeping target and target/clippy, after the migration guard, offrails-check and a cargo metadata --locked check. The Docker job's Dockerfile builds the dependencies in a layer of their own (a placeholder src/), which the gha layer cache keeps; the old --mount=type=cache target was never in that cache, so every run compiled every dependency in release mode. Locally (Docker on the M2, bare app, load 18→77): the first image build 352 s, a rebuild after a one-line code change 156 s with the dependency layer reused (the app crate's release compile and the CSS), and the image boots (/up 200). Not measured on GitHub (no runner available to this change): expected, from the local split, that a code-only push skips the release dependency build (most of the Docker job) and compiles the tests once instead of twice.

  • A dev-dashboard test failed for good after ~50 runs in one working copy (run_history_is_capped_redacted_and_reopened). It saved a run dated 2027 into the real storage/dashboard/ai-runs/ and never removed it; once MAX_HISTORY of them piled up they outranked and pruned the run the test makes. It now deletes its file. A local change to template/parts/dev-dashboard (the samples repo needs the same one-line fix; tools/sync-parts.sh would undo it). Its other flake (another test process pruning the shared history) remains in test-template.sh's known list.

  • Build settings (testing). split-debuginfo = "unpacked" left [profile.dev]: Windows MSVC refuses it, and it is macOS's default anyway; Linux gets it from .cargo/config.toml ([target.'cfg(target_os = "linux")']). Faster linkers stay opt-in per machine (~/.cargo/config.toml; x86_64 Linux already uses rust-lld since Rust 1.90). sccache is documented as an optional shared cache for a second app on one machine; a shared CARGO_TARGET_DIR is not recommended (one build lock for every app and agent).

    App migration (optional; every item makes an existing app faster, none is required):

    • The verify command. Detect: cargo offrails help | grep -c verify is 0, or .offrails/tools/offrails-gen/src/verify.rs is missing. Converge: re-vendor (offrails-gen vendor --framework "$FW", the upgrade does this); the alias in .cargo/config.toml already runs the vendored offrails-gen. Apps without the alias add it from .offrails/template/app/.cargo/config.toml. Prove it: cargo offrails verify prints a line per step and green.
    • Postgres test slots. Detect: grep -c offrails_test src/kernel/db.rs is 0, or tests/app/support.rs still calls create_database per test. Converge: copy from .offrails/template/app/src/kernel/db.rs the functions from drop_idle_stale_test_databases through TEST_RESET_SQL (keep the app's own changes to the rest of the file), and replace in tests/app/support.rs everything from pub struct DbGuard to impl TestApp { with the template's (DbGuard, PgSlot, test_database, checkout_postgres_slot, test_db_prefix, fnv1a, migration_tag, database_url, lock_slot, ensure_template). TestApp keeps its db_guard field and on_sqlite(). If the app's support.rs creates databases elsewhere (a second pool, a fixture), route it through test_database(). Copy the kernel test from the template's tests/app/kernel_test.rs. Then app task test_db_cleanup <admin url> once to drop the old test_<crate>_<hex> leftovers. Prove it: the suite on Postgres twice (the second run creates no database: psql -Atc "select count(*) from pg_database where datname like 'test_%'" is unchanged), a test that runs Migrator::down still passes, and the kernel test passes on both databases.
    • CSS check cache. Detect: grep -c inputs_key src/kernel/css.rs is 0. Converge: port css_warning, cached_warning, inputs_key, html_files_under and the test from the template's src/kernel/css.rs. Prove it: cargo nextest run the_css_warning_is_recomputed_only_when.
    • Profiles. Detect: grep -n split-debuginfo Cargo.toml. Converge: remove that line from [profile.dev] and add the Linux [target.'cfg(target_os = "linux")'] block from the template's .cargo/config.toml. Prove it: cargo build (and on Windows, a build that no longer stops at -Csplit-debuginfo).
    • CI. Detect: .github/workflows/ci.yml has separate sqlite and postgres jobs. Converge: replace them with the template's test job (keep the app's own extra steps, such as the TS steps, after verify), and take the Dockerfile's dependency layer (rename offrails_app to the crate). Prove it: the workflow is green on the next push and its test job shows one compile.

  • Generators you run, not recipes you copy: cargo offrails generate <kind> … (g) and cargo offrails destroy <kind> <name> (d) (generators). The human: "can we add actual code generators similar to rails? so the agent can invoke those instead of just copying? like db migrations, new controller, new api route, new page, and especially the parts… i hope this would make things even faster." Kinds: migration (create_x / add_y_to_x / remove_y_from_x / blank, each with a working down), model (migration + entity + Params → validate() → New + scoped queries + factory + model tests), resource (alias scaffold: the model plus htmx CRUD with the seven actions, forms that re-render with errors and the input, flash, nav link, request tests), controller, page, api (/api/v1 with bearer tokens and scopes, ApiJson, {"data": …} + page info, OpenAPI via utoipa with a drift test, and the API kernel on first use), job, mailer (HTML + text, previews), channel (a realtime topic with authorization) and test. Field types: string text integer bigint boolean decimal{p.s} money datetime date uuid json references{model} with ?/:optional, :unique, :index, each mapped to its column, Rust type, form control, validation and factory value. Generated code follows the guides exactly: 64-bit ids and FKs (offrails-check [ids]), per-user scoping when the app has accounts (find_for, raw find model-private, another user's id is 404, unique-per-owner indexes, references checked against the actor), Access rows, paths:: helpers, docs/routes.md, #[instrument(skip_all)] on every action and model fn, no unwrap/expect outside tests, templates in the design tokens with every dark: partner, and request tests for happy paths, 422s, sign-in, tenancy (guard_test.rs + an anchored tenancy_test.rs), escaping and the N+1 guard, on SQLite and Postgres. Without accounts, model/resource refuse until you add them or pass --public.

    • Safe to run: everything is rendered in memory first (a missing anchor is a refusal naming the file and spot; nothing written), --dry-run prints the plan, re-running is a no-op, --force regenerates only over files nobody changed, and docs/generated.toml records each generation (arguments, choices, formatted-file hashes) so destroy removes exactly the unchanged files and wiring and reports what it kept. rustfmt runs afterwards; next steps are printed (migrate, Tailwind, cargo offrails verify --fast, what to customize: the // APP: lines).
    • Parts are first-class in the same CLI: cargo offrails parts (alias of list-parts), cargo offrails add <part> (alias of add-part), and new cargo offrails update-part <part>… --framework <newer>: a three-way merge per file (the part as installed in .offrails/, the newer part, the app's copy): clean hunks apply, overlapping edits get <<<<<<</|||||||/=======/>>>>>>> markers and exit 1, changed wiring is swapped where the old text stands; an app change is never silently overwritten. add-part and new now refresh docs/routes.md (the first offrails-check no longer warns [routes]).
    • Measured (macOS, Apple silicon, 8 cores, load average ~20 from other agents, cold target dir, warm crates.io cache): a blog-equivalent built only with generators (new --parts auth-core,auth-magic-link,jobs, then g resource posts title:string slug:string:unique body:text 'published_at:datetime?', g page about, g mailer post_mailer published, g job notify_post_published post_id:bigint --queue mailers): new 8 s, the four generators 4 s, then green on SQLite after 200 s (the first compile; 357 tests in 4.8 s) and on Postgres 9 s later (7.7 s), offrails-check 0 errors: 221 s from nothing to green on both databases. The generators wrote 1,865 lines in 38 files (migration, model with validation and scoped queries, controller, views, 5 templates, routes, factory, model/request/tenancy/guard tests, page, mailer with previews, job), with 24 // APP: decisions marked. The 0.7.1 blog's hand-written equivalent of those files was ~2,100 lines; what an agent still writes for that blog is the domain on top (public reading by slug, publish/unpublish, slug from the title, excerpt and reading time, Markdown, the feed, the mail's words, enqueueing the job in the publish transaction, the spec's own tests): roughly 700–900 lines, by the blog's own counts.
    • App migration: existing apps get the generators by re-vendoring (.offrails/tools/offrails-gen); cargo offrails g --help works at once. Then:
      • Detect the anchors generators need: grep -n "samples: \(model mods\|model aliases\|controller mods\|view mods\|routes\|paths\|routes table\|test mods\|factories\|migration mods\|migrations\)" src/models/mod.rs src/controllers/mod.rs src/views/mod.rs src/routes.rs tests/app/main.rs tests/app/factories.rs migration/src/lib.rs (and nav links in templates/shared/_nav.html, sitemap paths in src/controllers/meta.rs, test support in tests/app/support.rs). Converge: add each missing one on a line of its own where new.md#anchors says; a generator that lacks one refuses and names it. migration/src/lib.rs rewritten by sea-orm-cli is healed automatically; from now on generate migrations with cargo offrails g migration, never sea-orm-cli migrate generate.
      • Detect tests/app/smoke_test.rs / security_test.rs sweeping ROUTES with app.post_form for every non-GET row. Converge (needed before generate api, whose routes use PATCH/DELETE): copy TestApp::request_method and send_json from .offrails/template/app/tests/app/support.rs into support.rs, and send each row's own method (other => app.request_method(other, &path).await) as the template's two tests now do. (generate api inserts send_json itself when it's missing.)
      • Detect a hand-written tests/app/tenancy_test.rs without // samples: tenant fill. Converge: nothing required; generate resource then prints the Tenant/fill lines to add for each new resource (or replace the file with the generated one, keeping your EXPECTED rows).
      • Agents: build features with generators from now on (AGENTS.md prime directive 2; workflow loop step 3). Log in docs/decisions.md: YYYY-MM-DD: generators adopted (framework 0.7.2): new features start from cargo offrails generate.
    • Changed docs: generators/README (the command table, field types, what generators decide), new migration, controller (and pages), api recipes; scaffold, job, mailer (sends from a job with state.mailer.deliver, no nonexistent deliver_later), channel start with the command; new (build features with generators after the parts; generator anchors), upgrade (step 6: update-part before re-vendoring), AGENTS.md (prime directive 2: generate before hand-writing), CHEATSHEET, workflow (PLAN/GENERATE), RAILS_MAP (rails generate ↔ cargo offrails g, rails destroy), cli, structure, template, the generate and scaffold skills.
    • Template: TestApp::request_method (the route sweeps send each row's own method) and TestApp::send_json (JSON with headers, no cookies).
    • CI: tools/ci/test-template.sh generators generates every kind into a bare app (a --public references chain, a resource with every field type, page, controller, migrations) and into an app with every part (scoped resources, api, job, mailer, channel, model, test), runs fmt, clippy, the suite on SQLite and Postgres and offrails-check, re-runs every generator (no-op), destroys everything in reverse and checks the app is byte-for-byte the baseline; update-part merges a synthetic newer part cleanly and then reports a conflict with markers. offrails-gen has golden files for every generator (tools/offrails-gen/testdata/golden/, UPDATE_GOLDEN=1 cargo test golden).

  • A browser smoke for boosted navigation: every page must work after a boosted link, not only on a fresh load (frontend-htmx, testing). The layout boosts every link, and a boosted click swaps <body> and runs nothing from the next page's <head>; DOMContentLoaded never fires again. The sign-in page's password Show button worked on a direct load and was dead after clicking through to the page: auth.js loaded in the page's {% block head %}. Request tests and screenshots can't see it.

    • .offrails/tools/browser-smoke/smoke-boosted.mjs: for each GET route in docs/routes.md without a parameter that is a boosted HTML page (kernel pages, JSON and streams are skipped and listed; a route that redirects smokes the page it lands on), it clicks the page's live elements after a full load and records which react (DOM or attribute change, print, copy, dialog), then loads /, follows a boosted link to the page and clicks them again. It fails on an element that is dead after the boosted link, on a script or stylesheet the page loads in its own <head>, and on any console error, uncaught exception or CSP violation on either path. With password sign-in it runs signed out, then signed in as the demo account. Zero dependencies: Node ≥ 18 and the installed Chrome, Chromium or Edge (CHROME_PATH, else the usual places on macOS, Linux and Windows), driven over the DevTools Protocol on a pipe; it never downloads a browser. Without one it prints skip: no Chrome and exits 77.
    • The live-element convention: every element page JS reacts to on click is a <button type="button"> or carries data-js (or data-toggle, role="button"), and the JS binds by delegation on document.
    • cargo offrails verify --full with BASE set runs it as browser smoke (boosted) beside the kernel-page smoke; exit 77 is reported as skip, never passed (Step::skip_on, with a test). run.sh is POSIX sh now and has run.sh boosted.
    • Template: the layout has a samples: app head anchor (a part's scripts load on every page), static/app.js states the rule, and tests/app/smoke_test.rs has two static guards: app_pages_load_no_scripts_or_stylesheets_in_their_head_block and page_scripts_never_bind_only_on_dom_content_loaded.
    • Parts: the parts synced from samples ee71024 load their page scripts at samples: app head (auth-core's auth.js, realtime's channels.js and live_room.js, the dev-dashboard's browser beacon) instead of page head blocks; that wiring needs the anchor above.
    • CI: tools/ci/test-template.sh serves the bare and the all-parts apps (development, their own SQLite file, the demo account seeded) and runs the smoke against them; without Chrome or Node the summary says browser smoke SKIPPED. The framework's CI runs tools/browser-smoke/selftest-boosted.mjs, which serves a tiny htmx site and proves the smoke passes a delegated Show button and fails a head-block script binding on DOMContentLoaded, a layout script binding on DOMContentLoaded, and a console error.
    • Measured (M2, load 13–25): the all-parts app, 18 page visits signed out and in, every Show and Copy button on the auth pages clicked on both paths, 25–28 s; the bare app (one page, /) 4.7 s; the selftest's four cases 25 s. Reintroducing the bug in an all-parts app (auth.js back in sessions/new.html's head block) fails it with /session/new (signed out): loads /static/auth.js in its <head>… and button[data-reveal="signin_password"] "Show password" reacts on a full load and is DEAD after a boosted link; putting it back passes.
    • App migration:
      • Page scripts. Detect: grep -rln "{% block head %}" templates | xargs grep -l "<script\|stylesheet", and grep -rln DOMContentLoaded static --exclude-dir=vendor. Converge: move each page's head-block <script>/stylesheet into templates/layouts/application.html (after app.js; add {# samples: app head #} on a line of its own there if missing), digested through ctx like app_js; rewrite a script that binds elements on DOMContentLoaded as delegated listeners on document (e.target.closest("[data-…]")), or also start it on htmx:load. For the auth and realtime parts, cargo offrails update-part auth-core (and auth-password, auth-totp, realtime) brings the samples' fix. Prove it: copy the two tests from the end of .offrails/template/app/tests/app/smoke_test.rs (with files_with_extension) into tests/app/smoke_test.rs; both pass.
      • The smoke. Re-vendor (the upgrade does). Prove it: with bin/dev running, BASE=<its URL> node .offrails/tools/browser-smoke/smoke-boosted.mjs ends with 0 failure(s) (seed the demo account first with cargo run -- task auth_demo when the app has password sign-in). Log YYYY-MM-DD: page JS loads from the layout and binds by delegation (framework 0.7.2, boosted navigation) in docs/decisions.md.

0.7.1 (2026-10-17)

What's new

  • New apps start from a tested template. offrails-gen new copies a complete, compiling htmx app (the whole kernel, tests, CI, Dockerfile and compose) instead of an agent retyping it from Markdown. A fresh app is green on SQLite and Postgres in 2 min 53 s, most of it the first compile.
  • Parts: the mailer, dev mailbox, jobs, jobs dashboard, sign-in methods, realtime and dev dashboard ship as installable parts. The agent proposes the ones the product needs, and cargo offrails add-part <name> adds one later (it changes nothing if an anchor is missing). cargo offrails list-parts shows what is installed.
  • Cross-platform tooling: offrails-gen is a standard-library-only Rust tool, so new, add-part, list-parts and vendor run the same on Linux, macOS and Windows.
  • Lean memory defaults: 2 worker threads, 16 blocking threads and a smaller SQLite pool and cache. A bare release build uses 15 MiB after 1000 requests, and CI fails a build over its memory budget.
  • Tracing spans by default on template actions, so the dev dashboard's traces work out of the box.
  • Upgrades can diff the old template against the new one to see every kernel change in a release.

Breaking changes

None. Existing apps keep working; the template alias, the memory settings and the parts are optional to adopt.

Upgrading

Optional: the App migration note at the end of the first entry below (compare with the template, add the cargo offrails alias, the memory settings). The whole procedure is in upgrade.

Full list of changes

  • New apps start from a tested template, not from Markdown retyped token by token (template, new). The framework now ships its app skeleton as real files: template/app/ is a complete, compiling app (htmx) with the whole kernel (config, errors, the security header matrix and CSP, CSRF, cookies and flash, the development Host allowlist and 127.0.0.1 bind, rate limiting, log and error-text redaction, SQLite + Postgres pools with per-test Postgres databases, introspection, /dev with the pending-migrations guard, the theme switch, direct TLS), the layout, error pages, Tailwind, bin/, the migration crate, tests/app/ with every kernel suite, deny.toml, CI, Dockerfile and compose, and every samples: anchor. It was the samples repo's host/, proven on both databases, and the framework's from now on. Building the skeleton from 0.7.0's Markdown cost an agent 50+ minutes; generating it takes seconds, and a fresh app is green on SQLite and Postgres in 2 min 53 s from the generator's start (5 min 46 s with every part; macOS, Apple silicon, 8 cores, cold target dir, warm crates.io cache), most of it the first compile. The human's decision: "add the full skeleton as templates… we are not a codeless framework anymore but it's fine." The guides stay the spec for why; doctrine §7 is rewritten to match: agents copy the template, adapt it and own it; humans still write no code.

    • How: after the interview, cargo run -q --manifest-path "$FW/tools/offrails-gen/Cargo.toml" --target-dir <dir>/target/offrails-gen -- new <dir> <crate_name> "<Display Name>" --pitch "<line>" --parts <a,b> (or sh "$FW/tools/new-app.sh" …). It copies the template, renames its tokens (offrails_app, offrails-app, Offrails App), vendors .offrails/, writes AGENTS.md and product/README.md from the blueprints, adds the parts, runs cargo fmt and git inits.
    • Parts, proposed by default. The base is lean: no job queue, mailer, accounts or realtime. Those are parts, the samples from rust-off-rails/samples vendored into the release (template/parts/). The agent proposes the ones the product implies, using a decision table (template → choosing parts: dev-dashboard for every app, mailer + dev-mailbox for email, jobs + jobs-dashboard for slow or scheduled work, auth-core + a method for sign-in, realtime for pushed updates), shows the human the samples link (screenshots of every screen), and the human confirms or opts out. This flips 0.7.0's head start, whose recommended answer was "build from the guides": a real run of a blog skipped every sample because of it.
    • Easy to add later: cargo offrails add-part <name> in any template app (the alias in .cargo/config.toml), with dependencies first, checks before changes (a missing anchor or a conflicting file refuses and changes nothing), the docs/decisions.md line, the AGENTS.md header (EMAIL, ACCOUNTS), cargo fmt, and the exact next steps. Re-running is a no-op. cargo offrails list-parts shows installed vs available. It is the samples' tools/install.sh mechanism in Rust (same format, same record line), and new --parts uses the same code path. workflow and every guide with a part (mailers, jobs, jobs-dashboard, auth, channels, realtime, dev-tools, errors-and-logging) now say: when the product grows the need, add the part; check list-parts before hand-writing kernel code.
    • Cross-platform generators. tools/offrails-gen is a standard-library-only Rust tool (new, add-part, list-parts, vendor), so it runs the same on Linux, macOS and Windows: no sed -i, paths through std::path, CRLF kept where a file has it. The template and the framework carry .gitattributes (* text=auto eol=lf). The app's bin/ scripts and offrails-check remain POSIX shell; Windows steps and the known gaps are in template → Windows.
    • Lean memory defaults, measured. main builds the Tokio runtime from Config: APP_WORKER_THREADS (default 2) and APP_BLOCKING_THREADS (default 16) instead of one worker per core and 512 blocking threads; SQLite gets cache_size 1 MiB per connection, a default pool of 4 (DATABASE_POOL; Postgres keeps 10) and a 60 s idle timeout (database, config). tools/ci/memory-budget.sh boots a release build in production mode, serves 1000 requests and fails over budget. Measured on macOS (Apple silicon, 8 cores): bare, release, 14 MiB RSS after boot and 15 MiB after 1000 requests (debug 16 / 17); every part, release, 18 / 20 MiB (debug 24 / 26). With the old thread and pool settings the same runs were 16 and 21 MiB after load: the saving is small on an 8-core laptop and grows with the core count. Budgets: 24 MiB bare, 32 MiB with every part.
    • Spans by default. Template actions carry #[tracing::instrument(skip_all)], and the guides make it the convention for actions and model fns, with the rule "never put secrets or personal data in span fields" (errors-and-logging), so the dev dashboard's traces work out of the box.
    • Upgrades: an app can diff .offrails/template/app (old) against $FW/template/app (new) to see every kernel change of a release, as a reference to port, never an overwrite (upgrade); step 7b now offers parts and adopts them with add-part (upgrade). offrails-gen vendor --framework "$FW" re-vendors on any OS.
    • CI: tools/ci/test-template.sh generates the bare app, the app with every part (every sample installed into a fresh template app), and a bare app with each part added afterwards and then added again (which must change nothing), then runs fmt, clippy (with the no-unwrap/expect gate), the suite on SQLite and Postgres, offrails-check and the memory budget. The framework workflow runs it (template), plus template-os: Linux, macOS and Windows generate, build, lint and run the SQLite suite, bare and with every part. test-install.sh checks the release carries the template, the parts and offrails-gen without build output; shellcheck covers the new scripts. tools/sync-parts.sh refreshes template/parts/ from a samples commit (recorded in template/parts/SOURCE).
    • Changed docs: new (generate, then fill the header, parts, verify; a reference of what the template contains, including the anchors table), interview (parts in the plan), samples, upgrade, workflow, doctrine, database (points at the template's db.rs instead of a copy), config, README, AGENTS.md (prime directive 8), CHEATSHEET, cli, CONTRIBUTING, blueprints/AGENTS.md, /offrails:new and /offrails:feature.
    • Not yet: a scaffold template (resources are still built from scaffold); full templates for inertia, spa and api (new --mode generates the htmx template and logs the conversion, per template → other modes); the guides other than database.md still carry long excerpts of files the template ships (the template wins where they differ).

    App migration (optional; no app needs to change):

    • Existing apps keep working as they are. After re-vendoring, .offrails/template/ holds this release's template and parts.
    • Optional, compare: diff -ru -x target -x .git -x .offrails -x storage .offrails/template/app . shows where the app's kernel differs from the tested template; port what you want as ordinary, tested changes (never copy a template file over an app file).
    • Optional, the alias: copy the [alias] from .offrails/template/app/.cargo/config.toml into the app's .cargo/config.toml (and .gitattributes beside it), then cargo offrails list-parts. An app generated from 0.7.0's guides may lack anchors or shapes the parts wire into; add-part names each and changes nothing (samples → using one).
    • Optional, memory: add worker_threads/blocking_threads to Config and build the runtime from them as the template's main.rs does; set the SQLite cache_size pragma and idle timeout in kernel/db.rs. Prove it with sh .offrails/tools/ci/memory-budget.sh . <budget> (Linux, macOS).

0.7.0 (2026-10-16)

What's new

  • Security fix: development is reachable only from this machine. serve binds 127.0.0.1 in development (APP_BIND) and answers only local and configured host names (APP_ALLOWED_HOSTS), so another device on the network or a DNS-rebinding page can no longer open /dev (where the mailbox shows sign-in links). A new offrails-check [bind] rule enforces it.
  • Signing in replaces the previous session: the old session in that browser is destroyed and its sockets and streams are closed.
  • Emailed links are limited per address, with a cap of 20 emails per address per day for login and reset links.
  • Unverified accounts can't be pre-hijacked: users.email_verified_at stays empty until a link sent to the address is used, and that first use drops every session, API token and pending link set up before it.
  • Less leakage: job errors are stored redacted, Config's Debug prints only settings that can never hold a secret, and presence labels never come from an email address.
  • Samples: optional, tested reference code for the mailer, jobs, sign-in, realtime and a dev dashboard in rust-off-rails/samples. Upgrading offers them per area.

Breaking changes

  • Every app: the development server must bind APP_BIND (default 127.0.0.1 in development) and check Host; offrails-check fails with [bind] until it does. A dev container, tunnel or LAN workflow now needs APP_BIND=0.0.0.0 plus APP_ALLOWED_HOSTS.
  • Apps with accounts: sign-in destroys the old session; reset and login links get per-address and daily limits; apps with signup (or both passwords and login links) add a nullable email_verified_at column, and a user's first reset after the upgrade also revokes their API tokens.
  • Apps with a manual theme toggle: the cookie is renamed from theme to offrails_theme (read the old one for one release).
  • Every app also ports the security fixes: job errors stored redacted, Config's Debug as an allowlist, and (apps with channels) presence labels that don't come from the email.

Upgrading

Do the first entry's App migration (the development bind and Host check) first, then each entry's own App migration below. The procedure, including step 7b that offers the samples, is in upgrade.

Full list of changes

  • Security fix (P0): development was reachable from the LAN and through DNS rebinding. An independent review of generated apps found that serve bound 0.0.0.0 in every environment (cli said so) and nothing checked Host. /dev has no login: the mailbox shows every magic link and reset link, introspection shows the app's state, and /admin/jobs is open in development. So anyone on the same Wi-Fi could open http://<your-ip>:3000/dev/mailbox and sign in as you. A page on evil.example that re-points its own name at 127.0.0.1 (DNS rebinding) reached it too: the browser sends Host: evil.example same-origin, so CORS doesn't apply, and Fetch Metadata says same-origin, so the CsrfLayer lets its POSTs through. Now, in development only (security, new non-negotiable 13):

    • serve binds config.bind: APP_BIND, default 127.0.0.1 in development and 0.0.0.0 in production. A dev container sets APP_BIND=0.0.0.0 (config, deployment).
    • kernel/hosts.rs (whole file in the guide, like Rails' HostAuthorization) answers only localhost, 127.0.0.1, [::1], *.localhost, APP_URL's host and APP_ALLOWED_HOSTS (a leading . allows subdomains). Any other Host gets a 403 page that says how to allow it. It's mounted right inside the security middleware (routing).
    • An unset APP_ENV still means development, but Config::boot_warnings now logs that at every boot. On a server it's a missing setting that mounts /dev.
    • New offrails-check rule [bind], with fixtures. It fails a literal 0.0.0.0 bind in src/ ([0, 0, 0, 0], "0.0.0.0:…", Ipv4Addr::UNSPECIFIED outside config.rs), a config.rs that never reads APP_BIND, and an app with no Host check. A 0.0.0.0 that isn't the server's bind ends its line with // not the server bind.

    Also updated: new (steps 4 and 7 and the verify step), cli, dev-tools, the CHEATSHEET, the app AGENTS.md NEVER list, /offrails:security, and TestApp gains get_with_headers/post_form_with_headers. Changed: the macOS port-collision note in cli. A 127.0.0.1:$PORT bind succeeds while another process holds *:$PORT, because tokio sets SO_REUSEADDR; then localhost over IPv6 may reach the other app. Verified on macOS 2026-10-16, so lsof before starting still matters. The code is from an app generated from these docs, where the five new tests pass: development_refuses_a_rebound_host_name, development_answers_local_and_configured_hosts, production_and_test_answer_any_host, development_binds_loopback_unless_told_otherwise and an_unset_app_env_warns_at_boot, plus hosts.rs's two unit tests. The running server listened on 127.0.0.1 only, refused its LAN IP, answered Host: evil.test with 403 and printed the boot warning.

    App migration (every app; security, do it first):

    • Detect: sh .offrails/tools/offrails-check prints [bind], or grep -rnE '\[0, *0, *0, *0\]|"0\.0\.0\.0' src matches, or grep -c APP_BIND src/config.rs is 0.
    • Converge:
      1. Add bind, allowed_hosts and env_defaulted to Config, with bind_address, parse_allowed_hosts, boot_warnings and their two tests, copied from config. Add the APP_BIND and APP_ALLOWED_HOSTS lines to .env.example.
      2. In main.rs, log boot_warnings() after init_tracing. Every listener binds SocketAddr::new(config.bind, port): the main port, APP_DEV_HTTP_PORT, and kernel::server::run if the app has one.
      3. Copy src/kernel/hosts.rs whole from security, add pub mod hosts;, and mount it just inside security::middleware in routes.rs.
      4. Add the three request tests to security_test.rs, and get_with_headers/post_form_with_headers to TestApp if they're missing.
      5. Anything that runs development in a container (a dev container, a compose override with APP_ENV: development) sets APP_BIND: 0.0.0.0, publishes on 127.0.0.1: only, and lists any non-localhost name in APP_ALLOWED_HOSTS. Production compose and the Dockerfile need no change: they set APP_ENV=production, which binds 0.0.0.0.
      6. A docs/decisions.md line, a tunnel or a LAN workflow that relied on 0.0.0.0 becomes APP_BIND=0.0.0.0 + APP_ALLOWED_HOSTS=<name> in .env. Say so to the human: that network can then read the mailbox.
    • Prove it: the suite on both databases, then with the app running in development: lsof -nP -iTCP:$PORT -sTCP:LISTEN shows 127.0.0.1:$PORT (not *:$PORT); curl -s -o /dev/null -w '%{http_code}\n' -H 'Host: evil.test' $URL/dev prints 403; curl -m 3 http://$(ipconfig getifaddr en0 || hostname -I | cut -d' ' -f1):$PORT/up is refused; starting with APP_ENV unset logs APP_ENV is not set; sh .offrails/tools/offrails-check shows ok [bind].

  • Security: signing in over a session now ends that session and closes its connections (auth, item 5). This came from the same review, applied to the samples' auth. On a shared computer, Ann signs in (password, magic link or reset) while Bob's session is still in the browser. The guide said "replace that session", and an app that only overwrote the cookie left Bob's session row alive, along with any copy of its token and his open sockets and streams, until the next revalidation. Now the sign-in transaction calls session::destroy on the old session, which writes the session-ended signal. App migration (apps with accounts): Detect: the sign-in handlers (sessions::create, login_links::consume, the reset's update) don't take Option<CurrentSession>, or set the new cookie without destroying the old session. Converge: destroy it in the sign-in transaction, before session::start. Prove it: a test signs in as A, opens a stream or socket as A, then signs in as B in the same TestApp: A's connection gets bye revoked, and A's old cookie, set back with set_cookie, is logged out.

  • Security: emailed links are limited per address, with a daily cap (auth). Password reset requests were limited per IP only, so a flood from many IPs could fill one inbox without limit. Login links allowed 10 per 3 minutes per address, which is still 4,800 emails a day. Reset requests now get the per-address limit too (10 per 3 minutes), and both share a cap of 20 emails per address per day (emails/day:{email}, a one-day window on the existing rate limiter). Over the cap it sends nothing and answers 429 like the other limits, which says nothing about whether the address exists. App migration (apps with accounts): Detect: grep -rn 'emails/day' src finds nothing. Converge: add the per-address key to passwords::create and the daily key to both handlers. Prove it: link_requests_are_capped_per_address_per_day: 21 requests for one address from different IPs (APP_TRUSTED_PROXY=true, varied X-Forwarded-For); the 21st sends nothing (drain_jobs, then sent_emails) and gets the 429 form, for a registered and an unregistered address alike.

  • Security: claiming an unverified account (pre-hijacking) (auth). In signup, anyone could register a victim's address with a password they know and set things up on the account, such as an API token. When the owner later got in by a reset link, the reset ended the sessions but not the token, so the attacker kept access. The same goes for an app that offers both a password and a magic link. Now users.email_verified_at stays NULL until something sent to the address is used. The first proof (consuming a reset or a login link, accepting an invite) runs user::claim_unverified in its transaction, and when that claims the account it drops every session, API token, pending link and mail redirect set up before. A link sign-in also clears the password. Magic-link-only and invite-only apps have nothing to claim. The rule comes from the samples' auth-core (claim_unverified_account), where cross-method tests prove it; it is new here as a spec. App migration (ACCOUNTS: signup, or an app with both passwords and login links): Detect: grep -rn email_verified_at migration/src src/models/user.rs finds nothing. Converge: a migration adds the nullable column, backfilled NULL: never mark existing accounts verified, because that would bless an attacker's pre-registered one. A real user's first reset after the upgrade then also revokes their API tokens; tell the human. Add claim_unverified, call it in password_reset::consume and login_link::consume, and drop the pre-claim credentials on true. Magic-link first logins create users verified. Prove it: an_api_token_made_before_the_first_reset_is_revoked (apps with an API) or a_password_set_before_verification_dies_when_the_owner_signs_in_by_link (both methods), plus a second reset that keeps the tokens, on both databases.

  • Security: job errors are stored redacted (jobs, errors-and-logging). From the samples' review: a failure message often quotes the URL that failed, credentials and tokens included (https://deploy:hunter2@api…?token=…). The executor stored it in jobs.errors, which /admin/jobs shows and searches and app jobs show prints. Errors now go through the new kernel::redact::text before they're stored or logged. It redacts URL userinfo, random-looking path segments, secret-named query values and key=value pairs, and long random words. The whole file is in the guide, trimmed from the samples' host and tested on its own. App migration: Detect: grep -rn 'redact::text' src/kernel/jobs finds nothing. Converge: add src/kernel/redact.rs from the guide, and call redact::text on the message in the executor's error push and its job.exception log; existing rows stay as they are (offer the human a one-off task that rewrites errors through it, or let the Pruner age them out). Prove it: job_errors_are_stored_redacted on both databases. Not ported: the samples' search over redacted args. The framework's dashboard shows args unredacted, because secrets never go in args (rule 7), so searching raw args reveals nothing the page doesn't.

  • Security: Config's Debug is an allowlist (config). From the samples' review of their dev dashboard's config page. The guide said to print [redacted] for three named fields, a denylist. The next secret someone adds (a Stripe key, a webhook signing secret) then went out in full on /dev/introspect.json and app introspect. Now Debug prints values only for settings that can never hold a secret, and set/not set for the rest. App migration: Detect: src/config.rs's impl fmt::Debug for Config prints a String or Option<String> field outside the allowlist with &self.<field>. Converge: print set/not set for those. Prove it: debug_shows_no_secret_values (a sentinel in every non-allowlisted string field, none in format!("{c:?}")), then curl -s $URL/dev/introspect.json | grep -c sentinel is 0 with a sentinel in .env.

  • Presence never derives a label from the email (channels). Also from the samples' review. The guide's member_for built presence initials from u.email, and ann.lee@… → "AL" tells a room who's there. Presence now uses a display name the person chose (or its initials), else a neutral Member <n>. App migration (apps with channels): Detect: grep -rn 'initials(&u.email\|initials(&user.email' src. Converge: derive it from the user's own name field, or Member <id> when there is none. Prove it: the presence test asserts no @ and, for a user without a name, Member.

  • Samples: optional, tested reference code (samples). The parts most apps need now exist as code that was built, tested on SQLite and Postgres, given a STRIDE threat model and reviewed adversarially, in a separate public repo, rust-off-rails/samples, tagged per framework release: mailer, dev-mailbox, jobs, jobs-dashboard, auth-core, auth-password, auth-magic-link, auth-totp, realtime and dev-dashboard. Each has a README (Adapting it, Do not change), a CHECKS.md whose every row cites a test, a PROMPT.md and a sample.toml; tools/install.sh there installs one by its // samples: <anchor> comments. The framework stays Markdown and the guides stay the spec. A sample is never required and never vendored automatically, and an agent offers it and never imposes it. New: guides/samples.md (rules, how to adopt one, the anchors, what each sample adds); a Reference implementation (optional) note in mailers, jobs, jobs-dashboard, auth, channels, realtime, dev-tools and errors-and-logging; a head start question with the plan in the interview (default: build from the guides), and in new, the head-start path that takes the mailer, mailbox, jobs and dashboard from the samples (same profile, same rules). Sample anchors in new apps (new, step 13): one-line samples: <anchor> comments in the shared files, each on a line of its own. rustfmt (1.99, checked) leaves a standalone comment in place, but carries a trailing one with its line: pub mod z; // samples: kernel mods moves when the mod lines are sorted. So anchors never trail code, and the step ends with a grep that proves it. The logging init is now a registry with the samples: tracing layers list, added through sample_layers() as an Option: an empty Vec layer silences every log line (found in the samples' host; an_app_without_sample_layers_still_logs, compiled with tracing-subscriber 0.3.23). One caveat, stated in the guide: samples are proven in the samples repo's host/, which is new without the mailer, mailbox and jobs kernel, plus a few pieces they build on (the theme switch, kernel/cookie.rs, kernel/redact.rs, Chrome::stylesheet), so adopting one may mean porting those first. App migration: nothing is required. Detect: every app. Converge: run upgrade step 7b (next entry). Add the anchors from new step 13 only if the human adopts a sample and you install it with install.sh. An app that keeps its own init_tracing keeps it; switch to the registry form only together with a sample that adds a layer.

  • Upgrading to 0.7.0 offers the samples (upgrade, step 7b). This is optional, and the human decides each area. App migration (every app):

    • Detect: the areas the app has: mailer (ls src/kernel/mailer.rs src/mailers/mod.rs), dev mailbox (grep -rln '"/dev/mailbox' src), jobs (ls -d src/kernel/jobs), jobs dashboard (grep -rln '"/admin/jobs' src), accounts (the ACCOUNTS: header line; password_digest, src/models/login_link.rs, totp), realtime (ls -d src/channels src/kernel/channels.rs), and a dev dashboard (grep -rn '"/dev/dashboard' src; usually none).
    • Converge: for each area found, read the sample's README and compare it with what the app has. Then, in the same message as the upgrade plan, tell the human in a sentence or two per area what the sample would add to this app, and what adopting costs. A mailbox with HTML, text and source views and a 320 px phone lint; jobs on the database with a dashboard that groups errors by root cause; accounts with TOTP, recovery codes, magic link + code and an account security page; channels with presence and authorization on every join; a LiveDashboard-style dev dashboard with traces, SQL with N+1 detection, a log tail and a routes explorer. Be enthusiastic where it's genuinely better and plain about the cost (files replaced, tables to reconcile, more code to own). Leave out what the app already does as well. Ask per area: adopt, borrow ideas or skip. Never replace working code without that yes, and in a non-interactive run install nothing: put the offer in the report.
    • If adopting: one slice per sample, after the convergence slices. Use the samples tag that matches .offrails/VERSION, install its dependencies first, and never copy a migration for a table the app already has (reconcile it). Port the sample's tests and its CHECKS.md rows into the feature spec's ## Security table, keep its // SECURITY: markers, and delete the replaced code only once the sample's and the app's tests are green. Then the Definition of Done on SQLite and Postgres.
    • Prove it: docs/decisions.md has YYYY-MM-DD: samples offered on upgrade to 0.7.0: <sample> adopted|borrowed|skipped, …. For each adopted sample, its tests run green in the app's suite on both databases, and sh .offrails/tools/offrails-check passes with its Security rows.

  • Route sweeps skip reading SSE bodies (test-standards §3, new). Agents reported that the "every ROUTES entry is routable" sweep and the access matrix hang forever on streaming routes (/streams/{stream}, /socket/sse, a mailbox events stream): TestApp::get waits for a body that never ends. Streaming routes now go through TestApp::request_head, which is in the TestApp spec now with the reference signature (path, headers) -> (StatusCode, HeaderMap), chosen by a STREAMING list next to the test, plus a check that every Sse<…> handler is on that list. App migration (apps with SSE): Detect: cargo nextest run security_test hangs, or grep -rn 'Sse<' src finds handlers that aren't in a STREAMING list in tests/app/security_test.rs. Converge: add the list and use request_head for those routes. Prove it: the security suite finishes on both databases.

  • The theme cookie is offrails_theme (views). The manual-toggle recipe said theme (light | dark, absent = system), and the samples' kernel pages use offrails_theme=system|light|dark, so an app and its kernel pages could disagree. Now there's one cookie and one switch: offrails_theme, values system|light|dark (anything else means system), not HttpOnly (the script writes it), exempted by exact name from the production HttpOnly backstop, with the server rendering data-theme and color-scheme, and POST /theme without JS taking only a same-site return_to. App migration (apps with a manual theme toggle): Detect: grep -rn '"theme"' src static/app.js finds the cookie name. Converge: rename it to offrails_theme. For one release, also read the old theme cookie when the new one is absent, so nobody's choice resets. Add the exemption and its production test. Prove it: the production cookie test, then run.sh a11y in both schemes with the switch forcing each.

  • Doc gaps from agents, checked: (1) new builds the mailer and jobs into every app. That's deliberate ("one profile", new) and stays, because the second feature of most apps needs one of them. What's new is the head start, which takes that kernel from the samples instead of from prose. (2) The mailers guide assumes jobs. True, and correct for every app new makes. mailers now says so, and says what to do without a queue (the mailer sample alone). (3) rustfmt moves anchor comments. Only trailing ones, and only with their line; anchors stand alone now (samples). (4) Node 22.12 vs 20.19. 20.19 is Vite 8's own engines (^20.19.0 || >=22.12.0, checked in 8.2.2), not the stack's floor. stack and new now say that TS apps need ≥ 22.22, the smokes ≥ 22.12, and Node 24 LTS for both. App migration: none.

0.6.2 (2026-10-13)

What's new

  • offrails-check catches 32-bit ids ([ids]), which pass on SQLite and break every Postgres write, and test suites that never run on Postgres ([postgres]).
  • bin/dev manages its own process: it writes a PID file per server, refuses to start twice on one port, and on exit stops only its own process tree. Agents stop a server with kill "$(cat storage/pids/…)".
  • Seeds can be re-run after a half-failed run: one transaction, each record found or created by a natural key.
  • WebSockets sized for many sockets: smaller per-socket buffers took 10,000 sockets from 1.37 GB to 160–225 MB.
  • Whole files in the guides for kernel/tls.rs and kernel/introspect.rs, and a pattern for live boards over a channel (snapshot, patches, reducer).
  • Parallel helpers only after the skeleton compiles, each with its own files.

Breaking changes

  • offrails-check fails on the new [ids] and [postgres] rules: an app with 32-bit ids adds a widening migration (never edits the applied ones), and tests/app/support.rs must read TEST_DATABASE_URL.
  • bin/dev no longer uses trap 'kill 0' (it could kill the caller's shell); copy the new top of the script.

Upgrading

Each entry's App migration note below, then upgrade. This release also corrects the 0.6.1 steps in place.

Full list of changes

  • Parallel helpers only after the skeleton compiles (workflow). A real migration (Fizzy → Rust off Rails, run in opencode) had three helpers writing the jobs executor, the jobs dashboard and the dev mailbox into one uncompiled crate at once. Each tripped over the others' half-written files, and two built stub crates in /tmp just to type-check their own part. Now: the coordinator builds the skeleton alone, up to the first green cargo check and the baseline commit. After that it runs at most one helper per vertical slice, with each helper's files listed. Shared registries (routes.rs, mod.rs files, migration/src/lib.rs, Cargo.toml) stay with the coordinator, and a helper blocked by another's file stops and reports. App migration: docs only. Detect: the app's AGENTS.md or any decision line telling agents to fan out helpers on code before the tree compiles. Converge: drop it and follow the workflow rule.
  • Fixed (P0): 32-bit ids passed on SQLite and broke every Postgres write. A peer's Kanban (0.3.0 → 0.6.1) used .integer() for ids and foreign keys. SQLite's INTEGER is 64-bit, so the suite was green; on Postgres the columns were INT4 and every write that returned an id was a 500. Its tests had never run on Postgres: support.rs hard-coded sqlite::memory:. Two new offrails-check rules, with fixtures: [ids] fails an id/*_id column defined with integer/small_integer/tiny_integer (helper or ColumnDef chain, across lines, Alias::new("x_id") too) or pk_auto, and an i32/i16 id field in src/; [postgres] fails a tests/app/support.rs that never reads TEST_DATABASE_URL. A migration repaired by a later one carries // offrails-check: ids widened in m<…> (migrations, with the widen_ids template, its SQL verified on Postgres 18). App migration: Detect: sh .offrails/tools/offrails-check prints [ids] or [postgres]. Converge: [postgres]: TestApp::new per testing first, then run the suite on Postgres and fix what it finds. [ids]: never edit the applied migrations; add widen_ids (Postgres only; ALTER SEQUENCE … AS bigint for pk_auto tables), put the waiver comment in each repaired file, change entity fields to i64, then db rollback --steps 1 && db migrate and the suite on both databases.
  • Seeds retry after a half-failed run. The same app's seed_if_empty returned early when any team existed, so a seed that failed after the first team never ran again. tasks/seed.rs now runs in one kernel::db::begin transaction and finds-or-creates each record by a natural key (cli; scaffold and new updated). App migration: Detect: grep -nE 'count|is_empty|exists' src/tasks/seed.rs gating the whole seed with an early return. Converge: one transaction, find-or-create per record; prove it by running app db seed twice (no change) and after deleting one seeded row (it comes back).
  • One PID file per server; cli.md and the NEVER list now agree on how to stop one. cli.md said to stop bin/dev by its own process; the NEVER list and the hook said lsof … | xargs kill on the listener, which leaves cargo watch and Tailwind running. A peer's agent (dev-92, opencode) also broke the name rule with pkill -f and killed the human's demo: the hook that blocks pkill exists only in Claude Code. Now bin/dev writes storage/pids/dev-<port>.pid, refuses to start when that PID is alive or the port is taken, and on exit stops only its own process tree (leaves first) and removes the file. A plain serve is started as sh -c 'echo $$ > storage/pids/serve-<port>.pid; exec cargo run -q -- serve' (cargo run execs the app, so the PID is the server's; verified). Stop either with kill "$(cat storage/pids/…)" (cli; the NEVER line, CHEATSHEET 14 and the hook message match). Also fixed: 0.6.1's trap 'kill 0' EXIT signals the whole process group, and a bin/dev started from an agent's shell isn't a group leader, so stopping it also killed the caller's shell (reproduced with a mock tree). App migration: Detect: grep -n "kill 0" bin/dev, or grep -c 'storage/pids' bin/dev is 0. Converge: copy the top of bin/dev from dev-tools (PID file, port check, cleanup trap) and the app's AGENTS.md NEVER line from blueprints/AGENTS.md. Prove it from a non-interactive shell: start bin/dev in the background, kill "$(cat storage/pids/dev-$PORT.pid)", then lsof -nP -iTCP:$PORT -sTCP:LISTEN prints nothing, no cargo watch/tailwindcss of this app is left, and the shell that ran it is still alive.
  • Fixed: bin/dev's Tailwind watcher overwrote the minified CSS with an unminified build. The watcher now runs with --minify, like the production build (verified with Tailwind 4.3.3: rebuilds after a template edit stay minified) (dev-tools). App migration: Detect: grep -n 'tailwindcss.*--watch' bin/dev | grep -v -- --minify. Converge: add --minify to that line.
  • kernel/tls.rs and kernel/introspect.rs are whole files in the guides, not sketches pointing at "the reference app's file", which an upgrading agent can't see. deployment has the full HttpToHttps acceptor with its four tests; dev-tools has the full introspect.rs (with // APP: marking the realtime part), the two handlers, the app introspect arm and kernel::css::css_warning() for the banner. Both come from an app that implemented them from the 0.6.1 spec (axum-server 0.8.0, sea-orm 2.0.4), generalized. PubSub gains streams() for the introspection's realtime part. App migration: Detect: an app that wrote either file from the 0.6.1 sketch. Converge: diff it against the guide's file; adopt the guide's tests if yours has fewer. Nothing to do if they match.
  • Upgrade notes that fit apps without every feature (from the website's 0.6.0 → 0.6.1 upgrade: no accounts, no live pages, no pending-migrations page, no CSS banner). The 0.6.1 App migration steps below are corrected in place: step 11 is split into 11 (every app: 503 + Retry-After, the pool's acquire_timeout, AppError::Unavailable) and 11b (only apps with live regions: X-Live-Refresh and the gate), since its old detect matched every app; step 5 also detects an app with no CSS banner and says how to add one; step 6 exempts the dev routes from the pending-migrations guard only if the app has one; step 2's proof for apps without accounts is run.sh a11y. upgrade gains the rule behind these (a step applies only where its Detect matches; otherwise it's n/a, with the reason, in the plan) and a preconditions paragraph. App migration: none; upgrades from 0.6.0 follow the corrected steps.
  • The browser smokes need Node ≥ 22.12, and now say so everywhere they're a proof (upgrade, the 0.6.1 steps, dev-tools). Fixed: run.sh only checked the major version, so Node 22.0–22.11 passed the gate and failed inside puppeteer; it now compares major and minor. App migration: none (.offrails/ is re-vendored).
  • The stale-CSS guard says to delete dead classes. It lists template classes with no CSS rule, and the guide only offered the HOOK_CLASSES allowlist, so dead classes got allowlisted. Now, per class: delete it if nothing uses it, rebuild the CSS for a real utility, allowlist only JS/test hooks with a reason (test-standards §11; the template's failure message says the same). App migration: Detect: each HOOK_CLASSES entry. Converge: grep -rn '<class>' static/*.js web/src tests finds no use → remove the entry and the class from the template; update theme_test.rs's failure message.
  • WebSocket buffers sized for many sockets (from a peer's 10,000-socket run on 0.6.1). kernel::channels::upgrade sets .read_buffer_size(4 * 1024).write_buffer_size(0).max_write_buffer_size(256 * 1024) (plus message and frame size = max_frame); axum's defaults are 128 KiB each way per socket. Measured at 10,000 sockets: 1.37 GB → 160–225 MB, failed handshakes 17 → 0, fan-out p50 320–590 → 58–88 ms (channels; the methods checked against axum 0.8.9). App migration (apps with channels): Detect: grep -n 'read_buffer_size' src/kernel/channels.rs finds nothing. Converge: add the five calls before on_upgrade; the wire tests must stay green (an oversized frame still closes the socket).
  • Fixed: forwarders replayed history after a restart. A row forwarder with a look-back window (outboxes, board events, chat rows written over HTTP) deduped with an in-memory set that starts empty, so its first poll after boot re-sent the whole window. Seed the set from the window at start (channels, with the test: 3 events of history, a restart, a 4th event → exactly the 4th is delivered). The pub/sub poller was never affected (it seeks to the end). App migration: Detect: a task that reads rows newer than now - <window> (or the last K ids) and keeps a HashSet of sent ids, built empty. Converge: fill the set from the window in its constructor, before the first poll; add the restart test.
  • Live boards over a channel: snapshot, patches, reducer (channels). The pattern a peer measured at 10,000 watchers (p50 58–88 ms, zero re-fetches): the join's ok.data is the snapshot and its seq without since, or seq + replayed patches with it; patches carry the final list order and go through one pure, idempotent reducer; actions stay HTTP POSTs, optimistic and confirmed by the channel; a JSON snapshot is polled while the socket is down. App migration: none (a pattern for new live boards); an existing board that re-fetches HTML per signal keeps working.
  • Load testing: the per-user cap explains "closed" counts. At 128 connections per user, N connections need ⌈N/128⌉ users; the tools/loadgen spec now says so and requires the generator to print the cap as the reason for refused or closed connections (realtime, channels). App migration: none.
  • README: "~50 Markdown files", not ~30 (27 guides, 15 root docs, 8 generators, 4 blueprints). App migration: none.

0.6.1 (2026-10-13)

What's new

  • Sign-in over dev HTTPS works again: development serves HTTPS only with a locally trusted (mkcert) certificate, and otherwise plain HTTP with a message saying why. APP_DEV_HTTP_PORT serves plain HTTP beside TLS.
  • Dark mode that stays readable: a palette, layout skeletons and components checked with axe in both color schemes, plus guard tests for unpaired colors and for stale compiled CSS (also shown as a development banner).
  • Hot reload and introspection: open tabs reload after an edit, and /dev/introspect.json and app introspect tell an agent the app's routes, config, migrations, jobs and realtime state.
  • The offrails command is safe to script: every subcommand answers --help without side effects, unknown flags exit 2, and new and upgrade never start an agent from a non-interactive shell without --yes.
  • Realtime at scale (5,000 watchers on one box): pub/sub per stream, live regions rendered once per version, a gate so re-fetches can't starve user requests, and overload answered with 503 and Retry-After.
  • Rate limits never extend a lockout, and offrails-check gains an [env] rule for variables missing from .env.example.

Breaking changes

  • offrails new and offrails upgrade in scripts or CI exit 3 without --yes (or OFFRAILS_YES=1).
  • bin/dev-cert no longer falls back to a self-signed certificate; without mkcert, development serves plain HTTP (or set DEV_CERT_SELF_SIGNED=1). Delete old certificates in storage/dev-certs.
  • A request timeout or an exhausted database pool answers 503 with Retry-After, not 408.
  • offrails-check fails on a missing .env.example variable ([env]) and on a bare n/a STRIDE row.
  • New settings APP_SHUTDOWN_DRAIN_SECS and APP_DEV_HTTP_PORT; development allows 1000 attempts per rate-limit window.

Upgrading

The numbered App migration list (steps 1–16) at the end of this section, for 0.6.0 apps; older apps apply 0.6.0's steps first. The procedure is in upgrade.

Full list of changes

Fixes from a peer's Kanban on 0.6.0 (and its 5,000-watcher load test), from the website's upgrade to 0.6.0, and two agent-experience requests. Every app-facing fix is proven in the reference app (bookshelf) unless marked otherwise.

  • Fixed (P0): login silently failed over dev HTTPS. 0.6.0's bin/dev-cert fell back to an openssl self-signed certificate when mkcert was missing. After "Proceed to localhost (unsafe)", Chrome drops Set-Cookie: the magic link returned 303, the account was created, and the user bounced back to login. Our smoke missed it because it ran Chrome with --ignore-certificate-errors. Now dev serves HTTPS only with a locally trusted certificate: bin/dev-cert uses mkcert and refuses (exit 3) when mkcert is missing or its CA isn't installed, unless DEV_CERT_SELF_SIGNED=1; bin/dev runs it on every start and otherwise serves plain HTTP/1.1, saying why, how to install mkcert, and that HTTP/1.1 limits live pages to ~6 tabs. It prints the exact URL with its scheme, again as ✓ ready: … once the port answers (dev-tools).
  • Dev HTTP beside TLS (from a peer, verified in a stock Chrome profile and here): APP_DEV_HTTP_PORT (development only) serves the same router and AppState on plain HTTP next to the TLS port. bin/dev sets it with DEV_CERT_SELF_SIGNED=1 and tells the user to open the http URL; scripts keep h2 on the TLS port.
  • A bare localhost:PORT on the TLS port no longer shows ERR_INVALID_HTTP_RESPONSE: kernel/tls.rs sniffs the first byte and answers plain HTTP with a 307 to https:// (deployment).
  • Fixed: new.md step 4.12 bound the port twice (bind_rustls(addr) after binding a listener). Bind once; the TLS branch uses axum_server::from_tcp(listener.into_std()?) with the sniffing acceptor (verified with axum-server 0.8.0).
  • Browser smokes never ignore certificate errors. Every smoke in tools/browser-smoke/ launches Chrome with no certificate overrides and fails at a preflight on an untrusted certificate. New smokes: run.sh login (logs in through the real form, then proves a fresh page load is still logged in) and run.sh a11y (axe-core 4.13.0, WCAG 2.2 AA, every path in light and dark). Verified: against a forced self-signed certificate login and live-tabs fail; over the http fallback and a trusted certificate both pass, and live-tabs reaches 12/12 tabs over h2. The trusted-certificate run emulated trust with Chrome's SPKI pin, since installing a CA on the verification machine wasn't authorized (dev-tools, test-standards §9).
  • Fixed: dark mode shipped unreadable (bg-white with no dark: partner under a body that turned dark: 1.09:1). views now has the palette (light/dark pairs per role), the skeletons (body, nav, flash, error summary, mailbox hint, lists, auth footers) and the component layer (.label, .input, .btn*, .link, which is now underlined because axe flags color-only links), all verified with axe in both schemes. The inertia and svelte snippets are fixed too. New guard-test template tests/app/theme_test.rs (test-standards §11): (a) a light surface needs a dark:bg-*; (b) dark text needs a dark:text-*; (c) faint tones need a dark:text-*. It reads the templates and @apply lists. In the reference app it listed 75 unpaired tones, and with one partner removed axe failed dark at 1.07:1 while light passed.
  • Fixed: stale compiled CSS failed silently. A second guard in theme_test.rs checks that every template class has its escaped selector in static/app.css (skipped when unbuilt). The same check (kernel/css.rs) drives a development banner and /dev/introspect.json's css.stale. In the reference app it listed the 67 new dark: classes until Tailwind ran. bin/dev keeps Tailwind in --watch.
  • Hot reload in development: cargo watch rebuilds and restarts on Rust and template edits, Tailwind watches CSS, and static/dev-reload.js reloads open tabs when GET /dev/reload changes (boot id + newest mtime under static/). It's a 1 s poll, not a held stream, because a stream per tab would eat the HTTP/1.1 connection budget. Measured: a CSS edit reached an open tab in 0.6 s, a template edit in ~17 s. The skeleton Cargo.toml gets [profile.dev] debug = "line-tables-only" and split-debuginfo = "unpacked": a peer measured template edits going from 16–23 s to 3.6–5.9 s; not reproduced in the smaller reference app (~5 s incremental builds either way). lldb loses locals; use CARGO_PROFILE_DEV_DEBUG=true (dev-tools).
  • Introspection for agents: GET /dev/introspect.json (development only, absent in production and test, tested) and app introspect report routes, redacted config, migrations, jobs, realtime (signal subscribers, connections per member and transport, topics), assets, the browser protocol and CSS staleness. The workflow loop, the Definition of Done, cli.md and the app's AGENTS.md tell agents to ask it before guessing (dev-tools).
  • Fixed: offrails upgrade --help launched the upgrade agent (0.5.0 ignored upgrade's arguments; in 0.6.0, update --help still ran the installer and check --help ran the checker). Every subcommand now answers -h/--help (and offrails help <command>) with its own help, exits 0 and does nothing else. Unknown commands and flags exit 2 with usage, and update validates installer flags before downloading. new and upgrade never start an agent from a non-interactive shell without --yes (or OFFRAILS_YES=1): they print the command they would run and exit 3. Exit codes: 0 ok, 1 error, 2 usage, 3 needs --yes, 10 upgrade due (INSTALL). tools/ci/test-install.sh runs -h and --help on every subcommand with fake agents on PATH and asserts none starts.
  • --fw on an old CLI: an installed offrails older than 0.6.0 silently ignores --fw and compares against ~/.offrails/current. upgrade now says to run the target release's own script (sh "$FW/tools/offrails" upgrade --check --fw "$FW") or offrails update first.
  • Realtime at scale (measured by a peer: 5,000 SSE watchers on one box, 154 MB, fan-out p50 ≈ 40 ms; the database and rendering were the bottleneck, not streams). Pub/sub keeps one sender per stream (pubsub.subscribe(&stream), swept when its last receiver goes), so a signal wakes only that stream's watchers. Hub revocations are keyed per member the same way. Shutdown ends every stream at once (SSE with no bye, so browsers reconnect and resume; sockets bye restart 1012), then drains for at most APP_SHUTDOWN_DRAIN_SECS (5); on 0.6.0 it took 10–35 s with 5,000 streams. The drain is proven here: 2.1 s with a stuck connection and a 2 s bound (realtime).
  • Fixed: the thundering herd on live pages. Every watcher re-fetched and re-rendered the same fragment after a signal. With 5,000 watchers on one board, one card move cost ~5,000 renders, page loads took 12–25 s and requests timed out. Live regions many people watch now render once per stream version. Pub/sub keeps a per-stream version, bumped in poll_once where the committed row is observed, before the signal is sent (never at write time). The fragment handler caches the HTML in moka keyed (stream, version) with try_get_with (single-flight), authorizes every request first, and filtered views bypass the cache. Measured after: GET 10–107 ms, move 10–264 ms, 0 pool-acquire warnings (realtime).
  • Live re-fetches can't starve user requests, and overload is 503, not 408. Live regions send X-Live-Refresh, and kernel::live::gate caps those requests to a third of the pool. The pool's acquire_timeout is 5 s, mapped to AppError::Unavailable. The request timeout answers 503, and any 503 gets Retry-After (realtime, errors).
  • Presence over SSE, for pages that already stream signals and only show a count. Each stream holds a join guard whose Drop is the leave; people and tabs are counted; joins and leaves only mark a room dirty; one task publishes one label per dirty room every 250 ms. A connecting tab gets the current label at once. Without coalescing, 5,000 arrivals woke 5,000 receivers 5,000 times. Per process; multi-node needs the pub/sub table (channels).
  • No full reload after a mutation: move the DOM optimistically, then re-fetch the live region in place with htmx.ajax (frontend-htmx).
  • Load testing spec (tools/loadgen): N watchers, M mutations, per-event delivery latency, a presence assertion, and server RSS/fd sampling, with client CPU reported separately. Lessons: pick the target explicitly, cache sessions between runs, about 5,000 TLS+h2 streams per Node process, and never ignore certificate errors on login checks (realtime). Measured capacity is reported as reached, not guaranteed, with the open unknowns: 10–49 of 5,000 connections failed client-side on some restarts.
  • Rate limits never extend a lockout. The window is fixed from the first counted attempt and refused attempts aren't counted, so retrying while locked out doesn't push the unlock back. Development allows 1000 per window (test and production unchanged), decided once in RateLimiter::new(config.env) and pinned by a test (security).
  • n/a threats in the STRIDE table are written | <Category> | n/a: <why> | — | — |. offrails-check accepts that form, counts the rows, and fails a bare n/a/none/— row or a named threat whose test is — (feature-spec).
  • Fixed: the Definition of Done's .env.example check never found a missing variable in configs that read through a helper (parse("PORT", "3000")); it only grepped var("…"). It's now offrails-check's [env] rule: every "SCREAMING_SNAKE" literal in src/config.rs must be in .env.example, with fixture tests. In the reference app it sees 27 variables where the old grep saw 23.

App migration (0.6.0 apps; earlier apps first apply 0.6.0's notes; reconcile: detect → final shape → converge, one slice each, green between them):

  1. Run the check. sh "$FW/tools/offrails-check" (new: [env], the n/a rule). After re-vendoring it's sh .offrails/tools/offrails-check, and it must exit 0 at the end. Upgrading with an installed offrails older than 0.6.0: detect offrails version below 0.6.0; converge offrails update, or run sh "$FW/tools/offrails" upgrade --check --fw "$FW".
  2. Dev TLS: trusted or nothing. Detect: grep -n 'openssl req' bin/dev-cert finds the unconditional fallback, or grep -n 'DEV_CERT_SELF_SIGNED' bin/dev-cert finds nothing, or bin/dev tests [ -f storage/dev-certs/cert.pem ] || bin/dev-cert. Final shape: bin/dev-cert from realtime and bin/dev from dev-tools. Converge: copy both, then rm -rf storage/dev-certs so a 0.6.0 self-signed pair can't be reused. Prove it: without mkcert, bin/dev prints the http fallback message; SCENARIO=tests/e2e/smoke.scenario.mjs BASE=<printed URL> bash .offrails/tools/browser-smoke/run.sh login passes. Apps without accounts (ACCOUNTS: none) have no login to prove: run run.sh a11y against the printed URL instead (its preflight fails on an untrusted certificate, so a pass proves the browser trusts it). The smokes need Node ≥ 22.12 (Node 24 LTS recommended); run.sh refuses older. Never tell a human to click through a certificate warning.
  3. serve: one bind, drain, sniffing acceptor, dev http port. Detect: grep -n 'bind_rustls' src/main.rs, or grep -n 'from_secs(30)' src/main.rs, or no src/kernel/tls.rs. Final shape: new step 4.12, kernel/tls.rs (deployment), Config.shutdown_drain (APP_SHUTDOWN_DRAIN_SECS) and Config.dev_http_port (APP_DEV_HTTP_PORT, refused outside development) in Config and .env.example; the CSRF layer trusts http://localhost:<port> when it's set. Converge: write kernel/tls.rs with its tests, replace the branch, and add a config test for both variables. Prove it: curl -si http://localhost:$PORT/ on the TLS port answers 307.
  4. Dark mode. (UI apps.) Detect: grep -rLn 'dark:' templates/layouts templates/shared lists files, or grep -c 'color-scheme' templates/layouts/application.html is 0, or no tests/app/theme_test.rs. Final shape: the palette, skeletons and component layer in views; kernel/css.rs and theme_test.rs from test-standards §11. Converge: add the guards first and let them list the work (rule a/b/c with file:line), fix every template and @apply list, rebuild the CSS, then run run.sh a11y (or the app's Playwright a11y suite) in light and dark. When the stale-CSS guard lists a class no rule exists for, first ask whether anything uses it: delete a dead class from the template (most are leftovers); rebuild the CSS for a real one; only a JS/test hook class goes in HOOK_CLASSES, with its reason. TS modes: apply the palette to web/src components and extend the guard to className=.
  5. Stale-CSS banner (UI apps). Detect: grep -rn css_warning src finds nothing (the app has no banner at all), or Ctx.css_warning is only app_css_problem(). Converge: add kernel::css::css_warning() and the Ctx.css_warning field, set only in development and rendered first in <main>, per dev-tools.
  6. Hot reload and introspection (development only). Detect: no /dev/introspect.json in ROUTES, or no static/dev-reload.js. Final shape: kernel/introspect.rs, the two dev.rs handlers with ROUTES rows (Access::Dev), both paths exempt from the pending-migrations guard if the app has one (grep -n 'fn guard' src/controllers/migrations.rs; an app without the development pending-migrations page has nothing to exempt, and gets the page only when it adopts dev-tools), the layout's {% if ctx.dev %} script tag, app introspect in main.rs, and [profile.dev] in Cargo.toml. Converge: copy kernel/introspect.rs and the handlers from dev-tools (whole files since 0.6.2) and #hot-reload; add both kernel_web_test.rs tests: present in development without secrets, 404 in production and test.
  7. Smoke scenario (Node ≥ 22.12 to run it). Detect: no tests/e2e/smoke.scenario.mjs, or a scenario whose login posts with fetch instead of the real form. Converge: export login(page, base) (fill and submit the form), loggedIn(page), a11yPaths, a11yAuthPaths; run run.sh login and run.sh a11y against the URL bin/dev printed. Without accounts: only a11yPaths, and only run.sh a11y.
  8. Per-stream pub/sub (apps with signals). Detect: grep -n 'tx: broadcast::Sender<Signal>' src/kernel/pubsub.rs, or grep -rn 'pubsub.subscribe()' src. Converge: replace tx with the topics/prefixes maps; subscribe(&stream) at every stream endpoint; hub.watch_revocations(pubsub.subscribe_prefix("member:")) in AppState::new; poll_once dispatches per stream and sweeps; add topic_count() and the per-stream and sweep tests (realtime).
  9. Keyed revocations (apps with channels). Detect: grep -n 'revocations: broadcast::Sender<String>' src/kernel/hub.rs. Converge: a per-key sender map, swept on unregister, plus the keyed wake-up test (channels).
  10. Render once per version (apps with live regions). Detect: grep -rn 'hx-trigger="sse:' templates finds regions while grep -n 'fn version' src/kernel/pubsub.rs and grep -rn 'try_get_with' src/controllers find nothing. Converge: add observed and Topic.version to pubsub, bumped in poll_once before the send; AppState.fragments; in each live region's GET, authorize first, then try_get_with((stream, version), render), with ?q= bypassing the cache; add the two test templates.
  11. Overload is 503, not 408 (every app). Detect: grep -n 'REQUEST_TIMEOUT' src/routes.rs finds the timeout status, or grep -n acquire_timeout src/kernel/db.rs finds nothing, or grep -n Unavailable src/error.rs finds nothing. Converge: TimeoutLayer::with_status_code(StatusCode::SERVICE_UNAVAILABLE, …) plus map_response(error::retry_after) outside it; opts.acquire_timeout(5s); AppError::Unavailable and its From<DbErr> arm (pool timeout → 503 + Retry-After) (errors). 11b. The live re-fetch gate (only apps with live regions). Detect: grep -rlE 'sse-connect|hx-trigger="sse:' templates lists files and grep -rn X-Live-Refresh templates finds nothing. No live regions: skip this step. Converge: hx-headers='{"X-Live-Refresh": "1"}' on live regions; kernel::live::gate with refresh_permits and Config.refresh_wait (realtime).
  12. SSE presence (if the app counts viewers over SSE). Detect: a per-stream presence count that sends on every join or leave, with no flush ticker. Converge: kernel/presence.rs per channels, with its tests.
  13. Reload after a mutation. Detect: grep -n 'location.reload' static/app.js outside the pageshow guard (and dev-reload.js). Converge: an optimistic DOM move, then htmx.ajax into the live region.
  14. Rate limits. Detect: grep -n 'fetch_add' src/kernel/rate_limit.rs with no load check before it, any expire_after_update/time_to_idle in that file, or grep -n 'RateLimiter::default()' src/state.rs. Converge: refuse before incrementing; keep expiry on create only; add RateLimiter::new(env), DEV_LIMIT = 1000 and limit() used by check and exhausted; add the kernel_test.rs cases (development 1000 vs test/production 10; a short window that unlocks on time while hammered).
  15. Specs and env. Detect: grep -nE '^\|[^|]*\|[[:space:]]*(n/a|N/A|none|—)[[:space:]]*\|' product/features/*.md, or offrails-check's [security] … says "n/a" with no reason or [env] .env.example is missing variable(s). Converge: | <Category> | n/a: <why it can't happen here> | — | — | (a real threat gets its test, never —); add each missing variable to .env.example (NAME=value or # NAME=value); a non-env "SCREAMING_SNAKE" literal in config.rs gets // not an env var.
  16. Scripts and CI calling offrails non-interactively. Detect: offrails upgrade/offrails new in scripts or CI without --yes. Converge: add --yes (or OFFRAILS_YES=1); without it they now exit 3 and start no agent.

0.6.0 (2026-10-13)

What's new

  • Live pages no longer stall past about 6 tabs: serve speaks HTTP/2 over direct TLS, and bin/dev serves HTTPS by default.
  • tools/offrails-check (offrails check): a script that fails on an inconsistent AGENTS.md header, uncited acceptance criteria, feature specs without a STRIDE table, missing tenancy suites and unscoped lookups. It is the first step of the Definition of Done and of CI.
  • Tenancy enforced by the compiler and tests: with accounts, model lookups take the actor (find_for, all_for, destroy_for), and every app with accounts gets tenancy_test.rs and guard_test.rs.
  • Fixes from apps that shipped "green": a user locked out at about 5 tabs (connection cap 8, now 128), pages loading without htmx, a fresh database crashing serve, and a logged-out stream redirecting instead of answering 401.
  • offrails upgrade --check --fw <dir> checks or upgrades against any release and exits 10 when an upgrade is due.
  • Rules for weaker models: a NEVER list in the app's AGENTS.md, a command for every Definition of Done item, and evidence before any retry, sleep or raised limit.

Breaking changes

  • Direct TLS: new APP_TLS_CERT/APP_TLS_KEY settings, bin/dev-cert, and bin/dev serving HTTPS unless APP_TLS=off.
  • Apps with accounts: raw model find/destroy become pub(in crate::models), so handlers must move to the scoped functions (the compiler lists every caller), and the two tenancy suites are required.
  • offrails-check runs first in the Definition of Done and in CI, and fails until the app passes it.
  • A logged-out request to /streams/… answers 401, not 303 to the login page.

Upgrading

The numbered App migration list (steps 1–14) after the entries, for 0.3.x, 0.4.x and 0.5.0 apps, plus the instant-navigation note at the end. The procedure is in upgrade.

Full list of changes

Hardening from a 0.3.0 Kanban built by another agent that shipped "green" with three P0 defects. The rule this release follows: mechanical over prose. Each fix is a command that proves it, a template, a compile error or a failing check.

  • Fixed: live pages stalled past ~6 tabs. Browsers allow about 6 HTTP/1.1 connections per origin across all tabs, and each live page holds one or two open (signals + socket). The 7th tab's stream, then its page loads, queued forever. Browsers only speak HTTP/2 over TLS, so serve now does direct TLS with HTTP/2 (axum-server + rustls, ALPN h2, APP_TLS_CERT/APP_TLS_KEY), bin/dev serves HTTPS by default (bin/dev-cert makes a local certificate with mkcert or openssl; APP_TLS=off for http), and APP_URL's scheme follows. Measured in the reference app: HTTP/1.1 5 of 12 tabs updated; HTTP/2 12/12 and 40/40 (realtime). A multi-tab smoke ships with it (tools/browser-smoke/run.sh live-tabs).
  • Fixed: the per-user connection cap (8) locked a user out at ~5 tabs (429 on /streams). It's 128 now: sized for tabs, still bounded.
  • Fixed: pages randomly had no htmx and the live badge stayed on "connecting…" (0.3.x apps). assets() picked "vendor/htmx-" by prefix from a HashMap, which also matches vendor/htmx-ext-sse-…; depending on iteration order a page got the sse extension twice and no htmx. Assets now use exact keys (vendor/htmx-2.), a test asserts each key matches exactly one file, and the catalog is built once at boot (frontend-htmx; CHEATSHEET gotcha 17).
  • Scoped lookups: with accounts, the public model lookups take the actor (find_for(db, &user, id), all_for, destroy_for); raw find/destroy are pub(in crate::models), so a handler can't compile an unscoped call (models).
  • Tenancy suites for every app with accounts (not just teams): tests/app/tenancy_test.rs requests every id route in ROUTES with another tenant's ids (404, or the status an AC specs), and tests/app/guard_test.rs fails on unscoped lookups in handlers. Both are templates in test-standards §4, generated by authentication, extended by scaffold.
  • tools/offrails-check (also offrails check): a POSIX script that fails on an inconsistent header (ISLANDS: yes without UI_LIBRARY/web/, FRAMEWORK behind .offrails/VERSION), any uncited AC-…, a feature without the STRIDE Security table or naming a test that doesn't exist, missing tenancy suites, and unscoped lookups; it warns on a stale docs/routes.md. First step of the Definition of Done, in generated CI, /offrails:check and /offrails:doctor. The framework's CI tests it against a passing tree and a failing fixture per rule.
  • Weak-model rails: a NEVER list atop the app's AGENTS.md; a command for every Definition of Done item; evidence first (a retry, watchdog, reload cap, sleep or raised limit needs the captured failure and a decision line citing it); docs/decisions.md lines are superseded, never edited; upgrades reconcile stale decisions.

From Railboard, a Kanban built by headless Claude on 0.5.0:

  • Fixed: a fresh database crashed serve at boot (no such table: broadcasts): realtime's pub/sub read its table before the pending-migrations page could render, and bin/dev hid it by migrating first. Realtime now starts only once migrations are current (otherwise it waits like the worker and starts after the page's button runs them), and new apps get a fresh-database smoke (dev-tools, realtime). Reproduced and fixed in the reference app.
  • Fixed: a logged-out stream answered 303 to the login page. EventSource can't follow it, so it retried forever, and the stream path became the after-login page. /streams/ and Accept: text/event-stream now get the API flavor: 401, no redirect, no return_to (errors-and-logging). Fixed in the reference app.
  • Presence: every (re)join gets a snapshot that includes the joiner before any diff; the client buffers diffs until it arrives; reconnects jitter; after a restart, both clients must see each other within backoff + 1 s (channels).
  • /dev/sockets' frame log is specified (types, limits, where frames are recorded, tests) instead of only being promised.
  • Islands develop with vite build --watch, never the Vite dev server: the dev CSP stays the production CSP, one origin over HTTPS (frontend-htmx). spa dev serves the Rust app over http behind Vite's proxy.
  • Non-interactive agent runs (claude -p, opencode run) stop every server they started before finishing, or the run never exits (cli).
  • tools/brand/render.sh works without Chrome: rsvg-convert rasterizes the SVGs, else a neutral set from tools/brand/default/ is copied.
  • ts-rs without .cargo/config.toml: per-type #[ts(export, export_to = …)] and #[ts(type = "number")] on every i64 (frontend-inertia).
  • Models rule 8: inserts that can hit a unique index use on_conflict_do_nothing_on(..) (SeaORM 2.0.4 TryInsertResult), never insert-then-catch (models).

From the website's upgrade to 0.5.0:

  • offrails upgrade [--check] --fw <dir> checks or upgrades against any release (a tag export, the plugin root), not only ~/.offrails/current; --check exits 0 when current, 10 when an upgrade is due (upgrade).
  • The Definition of Done and testing.md say what to do when localhost:5432 is taken: run the compose db on another port (DB_PORT=54329 docker compose up -d db) and point TEST_DATABASE_URL at it; never stop someone else's Postgres.

App migration (0.3.x, 0.4.x and 0.5.0 apps; reconcile: detect → final shape → converge, one slice each, green between them):

  1. Run the check. sh "$FW/tools/offrails-check" (before re-vendoring) lists most of the work below. After re-vendoring it's sh .offrails/tools/offrails-check, and it must exit 0 at the end.
  2. HTTP/2 + TLS. Detect: grep -n bind_rustls src/main.rs finds nothing, or bin/dev has no APP_TLS. Final shape: Config.tls: Option<TlsFiles> from APP_TLS_CERT/APP_TLS_KEY (both or neither); serve branches to axum_server::bind_rustls (crypto provider installed first, graceful shutdown through a Handle); bin/dev-cert; bin/dev exports the pair unless APP_TLS=off; dev APP_URL is https:// with TLS; both vars commented in .env.example (new step 4.12, deployment). Converge: cargo add axum-server --features tls-rustls and cargo add rustls --no-default-features --features aws_lc_rs,std, then the code. Prove: curl -sk -o /dev/null -w '%{http_version}\n' https://localhost:<port>/up prints 2, and run.sh live-tabs passes with 12 tabs.
  3. Connection cap. Detect: max_conns_per_user: 8. Converge: 128, and the cap test reads the configured value instead of a literal.
  4. Assets (0.3.x). Detect: grep -n 'vendor/htmx-"' src/kernel/assets.rs, or a catalog built per request (AssetCatalog::load in an extractor). Final shape: ASSET_KEYS with exact prefixes (vendor/htmx-2., vendor/htmx-ext-sse-), the uniqueness test, the catalog in AppState (rebuilt per request only in development). Converge: per frontend-htmx.
  5. Live-region workarounds. Detect: stall watchdogs, reload caps or reconnect retries in static/app.js added for tabs that stopped updating. Converge: after step 2, reproduce with run.sh live-tabs; if it passes without them, remove them and supersede their decision lines. Keep the 0.5.0 ping watchdog (it covers dead proxies, not tabs).
  6. Scoped lookups (TENANCY isn't none). Detect: offrails-check's [guard] lines. Final shape: the table in models. Converge: per model, add find_for/all_for/destroy_for, make find/destroy pub(in crate::models), let the compiler list every caller, and move each to the scoped fn (tests read through Entity::find_by_id, a reload_<model> factory helper). Mark lines that are public by spec // unscoped: <AC id>.
  7. Tenancy suites. Detect: no tests/app/tenancy_test.rs or guard_test.rs. Converge: copy both from §4, fill Tenant, EXPECTED (from the ACs), NOT_TENANT_IDS, fill and call, register them in tests/app/main.rs, then prove the suite bites (remove one policy check, watch it fail, restore). A failure here is a real cross-tenant bug: fix the handler, never the expectation, unless an AC says the route is shared.
  8. Specs ↔ tests. Detect: [ac] and [security] lines. Converge: write the missing tests; turn prose Security sections into the STRIDE table (feature-spec) with a real test name per threat; tick ACs whose tests pass on both databases.
  9. Header. Detect: [header] lines. Converge: make ISLANDS, UI_LIBRARY and FRONTEND_MODE describe the code that exists (record a decision if you change a mode), and set FRAMEWORK to .offrails/VERSION after re-vendoring.
  10. Agent rails. Add the NEVER list from blueprints/AGENTS.md to the app's AGENTS.md, add sh .offrails/tools/offrails-check as the first step of the SQLite CI job (testing), and reconcile docs/decisions.md (upgrade step 8).
  11. Boot on a fresh database (apps with channels or signals). Detect: serve awaits pubsub.start() (or cluster::start) unconditionally. Converge: the gated start in realtime sharing the worker's wait_for_migrations; run the fresh-database smoke.
  12. Logged-out streams. Detect: a logged-out GET /streams/<x> answers 303. Converge: /streams/ and Accept: text/event-stream take the Api flavor in ResponseFlavor::of; the stream auth test expects 401 with no Location and no _return_to cookie.
  13. Presence. Detect: presence_here_frame computed before hub.track, or a client Presence that applies diffs before here. Converge: per channels; add the restart convergence test.
  14. Islands (ISLANDS: yes). Detect: localhost:5173 in the dev CSP or bin/dev. Converge: vite build --watch in bin/dev, the manifest path in development, and the production CSP everywhere.
  • Instant navigation recipe (guides/frontend-htmx.md), gotcha from CI: wrap document.startViewTransition so a transition skipped by a quick second click doesn't leave unhandled AbortError rejections (htmx drops the transition object); make the last boosted click win. App migration: apps that adopted the recipe: detect globalViewTransitions without a startViewTransition wrapper in static/app.js; converge per step 6 of the recipe.

0.5.0 (2026-10-13)

What's new

  • An accessibility gate: axe-core (WCAG 2.2 AA) on every route, in light and dark, on desktop and mobile, with a required a11y CI job.
  • Less for agents to read: a two-page CHEATSHEET.md is the first thing to load, and every guide and generator opens with a TL;DR.
  • Robust live regions: no leaking EventSources, a ping heartbeat with a watchdog, hx-sync, a connection badge and one stream per page.
  • Instant navigation for content sites (optional): View Transitions, a CSS-only progress bar, a service worker and prefetch on intent.
  • Repairing a migration: the repair's down restores the earlier schema, so a full rollback still works.
  • rustoffrails.org runs on the framework, with a hosted read-only MCP server at https://rustoffrails.org/mcp.

Breaking changes

None required. The docs now call the compose Postgres service db, so scripts that run docker compose up -d postgres should use db.

Upgrading

The App migration notes at the end of this section: nothing required; apps with a UI add the accessibility suite, and apps with live regions apply the live-region fixes. The procedure is in upgrade.

Full list of changes

Learned from real apps built by other agents and from a real upgrade: an accessibility gate in both themes, robust live regions (from a Kanban built with opencode), a context diet for agents (CHEATSHEET.md + a TL;DR on every guide), instant navigation for content sites, and a migration repair convention. rustoffrails.org runs it, with a hosted read-only MCP server at https://rustoffrails.org/mcp.

  • Docs: the Postgres compose service is db everywhere (docker compose up -d db); fingerprint.sh ignores a .git file (worktrees, submodules); the Copilot pointer file has an exact body; generators/upgrade.md defines a non-interactive path; the pre-deploy checklist requires green CI on the exact commit.

  • Fixes from a real 0.3.0 → 0.4.0 upgrade (bookshelf, via /offrails:upgrade): fingerprint.sh and vendoring ignore the plugin cache's .in_use/ marker; the error-page app.js snippet is now shown in errors-and-logging; ZAP's "Suspicious Comments" gotcha; the 0.4.0 migration notes' detect lines for #2, #3 and #6 are greppable (and HX-Push-Url lives at the end of error::shape_errors); the test-harness DB helpers are named (create_database, drop_database); a macOS ZAP variant; a deterministic first-login transaction test; the upgrade recipe adds a missing "Post-upgrade checks" section.

  • Robust live regions (guides/realtime.md), from a Kanban built with opencode + Muse Spark on 0.3.0: never reconnect by editing sse-connect (it leaks EventSources), the ~6-per-origin connection budget (one stream per page), hx-sync on live regions, a named ping heartbeat event (+ a hidden sse-swap="ping" hx-swap="none" observer and a 60s watchdog), a connection-state badge, and the pageshow guard in the app layout.

  • Context diet: a two-page CHEATSHEET.md (stack, layout, naming, DoD, security non-negotiables, the 15 costliest gotchas, commands) is now step 0 of the load order, and every guide and generator opens with a TL;DR (what to do, what never to do, when to read the rest). Agents read a full guide only when the task touches it. No app migration.

  • Accessibility gate (guides/test-standards.md §10): axe-core (WCAG 2.2 AA) on every route, in light and dark, desktop and mobile; keyboard, motion and form rules; a required a11y CI job. Lighthouse checks one color scheme only, which let a light-theme contrast bug through on rustoffrails.org.

  • Instant navigation for content sites (guides/frontend-htmx.md, optional recipe, from rustoffrails.org): View Transitions (cross-document + htmx globalViewTransitions) with a fixed header, a CSS-only progress bar via hx-indicator, focus to the new h1 after boosted navigations, a per-deploy versioned stale-while-revalidate service worker (precache, theme-cookie rewrite, offline page, never caching no-store/cookie responses), and prefetch on intent. Optional; not for apps with per-user pages.

  • Migrations: repairing an earlier migration: the repair's down restores the predecessor's exact schema, so full rollback works (guides/migrations.md rule 2).

App migration: none required. If your app's docs or scripts say docker compose up -d postgres, use db.

Apps with a UI: detect no axe suite, or one that runs a single color scheme. Converge: add the §10 suite and the a11y CI job, then fix what it finds.

Apps with live regions: detect sse-connect attributes changed from JS, live regions without hx-sync, or a stream with no named ping event. Converge per "Robust live regions"; add the ping merge to the stream endpoint and the badge + watchdog to static/app.js; add the pageshow guard to the layout's script. Apps upgraded from 0.3.0 should double-check 0.4.0 note #5 (the first-login race: a caught unique violation aborts a Postgres transaction).

0.4.0 (2026-10-13)

What's new

  • Realtime has its own wire protocol, offrails.v1: typed channels, self-describing JSON frames and stable error codes, replacing the Phoenix v2 format.
  • Nothing is lost while a tab is disconnected: signals carry ids, pages render a cursor, and reconnects replay what was missed. Live regions also keep working after a boosted navigation.
  • Automatic transport fallback: WebSocket, then SSE + POST, then long-polling.
  • Connection security: logout, a password change or a revocation closes that session's sockets and streams at once; pushes are re-authorized, and each user has connection and join caps.
  • Upgrade from any agent: offrails upgrade launches Claude Code, opencode or Codex with the agent-neutral upgrade recipe, and vendoring uses anchored excludes from a release tag.
  • Magic-link sign-in verified by a fresh agent's build, with its doc findings fixed.

Breaking changes

  • Apps with channels: client and server must switch to offrails.v1 together; old clients get bye protocol and close 1002. Rooms become typed In/Out enums.
  • Apps with SSE: Signal gains an id, pages with sse-connect render a ?since= cursor, and the sse extension moves from a page's head block into the layout.
  • New settings APP_REALTIME_REVALIDATE_SECS and APP_REALTIME_TRANSPORTS.
  • Smaller fixes to adopt: raw SQL in controllers and tasks moves into kernel::db, panics render the 500 page, the pending-migrations guard goes after the fallback, and /dev/mailers answers 301.

Upgrading

The two numbered App migration lists below (realtime, steps 1–7; the Linkdrop fixes, steps 1–7) and the vendoring note. The procedure is in upgrade.

Full list of changes

Realtime gets its own wire protocol, offrails.v1: typed channels, sequence-based resume after downtime (WebSocket since, SSE Last-Event-ID), automatic fallback to SSE + POST and then long-polling, and connection security (logout or a password change closes that session's sockets and streams; per-user caps; re-authorized pushes). The security hardening was merged with it and re-verified end to end in the reference app (233 tests on Postgres, ZAP 0 warnings, cargo-deny, gitleaks, browser smoke). Apps can be upgraded from any agent with offrails upgrade (Claude Code, opencode, Codex) and the agent-neutral generators/upgrade.md; vendoring now uses anchored excludes from a release tag. The magic-link accounts variant is verified by a fresh agent's build (Linkdrop), and its 24 doc findings are fixed below.

Realtime: the Off Rails Wire protocol (offrails.v1), resume after downtime, transport fallback, connection security

Spec: guides/channels.md (protocol, transports, security), guides/realtime.md (resume). Verified in the reference app: 223 tests on SQLite and Postgres 18 (39 realtime: conformance, security, all three transports, a 3-node failover), two Playwright specs (a server restart with changes made while it was down; WebSocket → SSE → long-polling), and a two-context Chrome session.

  • Fixed: signals sent while a tab was disconnected were lost (a deploy, a restart, a blip): live regions silently went stale. Every signal now carries its id; pages render a cursor (?since=); reconnects replay what was missed (or refresh); app.js carries the cursor across htmx-ext-sse's reconnects.
  • Fixed: live regions were dead after a boosted navigation. The sse extension was loaded in a page's own <head>, which a boosted swap never runs. It's in the layout now.
  • Our own protocol, offrails.v1 (replaces the Phoenix v2 array format): negotiated subprotocol, self-describing JSON object frames (join/leave/push/ping up; ok/err/event/presence/pong/slow/bye down), stable error codes, bye before every close, seq resume, WebSocket ping control frames instead of app heartbeats.
  • Typed channels: rooms declare In/Out serde enums (#[derive(TS)] in TS modes); undeclared events are refused before the room runs.
  • Transport fallback: WebSocket → SSE + POST → long-polling, chosen automatically, remembered per tab, upgraded back when possible. APP_REALTIME_TRANSPORTS lists what the server offers.
  • Connection security: logout, password change and revocation close that session's sockets and streams at once (4401), across processes and nodes; periodic revalidation closes expired sessions (APP_REALTIME_REVALIDATE_SECS); pushes re-authorized against current state; per-user caps (connections, topics, joins/min); presence never carries emails; cross-site refused on every transport.
  • /dev/sockets shows each connection's transport and a live decoded frame log (development only).

App migration (reconcile, don't re-create; apps without channels do steps 1–3 only):

  1. SSE resume. Detect pub struct Signal { pub stream, pub event } in src/kernel/pubsub.rs. Final shape: Signal { id, stream, event } (row id), plus pubsub::high_water and pubsub::missed (realtime.md#kernel-spec). Converge: add the field (set it in poll_once), add the two functions; in channels::stream take Query<StreamQuery> + HeaderMap, subscribe first, replay missed with ids (or refresh), send ready with the cursor, add .id(sig.id) to live events, skip only exact replayed ids. No migration (the broadcasts.id column already exists).
  2. Pages render a cursor. For every page with sse-connect: read pubsub::high_water(&db) before the page's data and render sse-connect="…?since={cursor}". Add the createEventSource override and the bye listener to static/app.js (realtime.md#client-side). Inertia/SPA: pass the cursor as a prop and use it in ?since=.
  3. The sse extension in the layout. Detect htmx_sse inside a template's {% block head %}: move the script tag into templates/layouts/application.html (after htmx) and delete the block. Add the "every page loads the live-update extension" test.
  4. Channels: switch client and server together (the formats are incompatible, and old clients now get bye protocol "subprotocol offrails.v1 required" + close 1002). Replace kernel/hub.rs, kernel/channels.rs and static/channels.js (or web/src/lib/socket.ts) per channels.md; convert each room to typed In/Out enums, joined(.., since) returning Joined, handle_in(.., msg: Self::In, out: &mut Outbox<Self::Out>) returning Result<Payload, Rejection>, out.emit(seq, …); rename events on the page (ch.channel(topic, { since }), ch.on("<out event>"), ch.push("<in event>"), errors are {code, message}). cluster.rs only changes String errors to Rejection.
  5. Connection security. Member gains #[serde(skip)] session: Option<i64>; add SessionAndUser; session::destroy/destroy_all_for_user write the member:<id> / session-ended signal; AppState::new calls hub.watch_revocations(pubsub.subscribe()) and hub.log_frames(is_development); Channels gains session_valid; the SSE stream ends with bye on session_ended. Config: APP_REALTIME_REVALIDATE_SECS (60), APP_REALTIME_TRANSPORTS (all), in Config and .env.example.
  6. Fallback transports. Add the four routes (/socket/sse, /socket/sse/{conn}, /socket/poll, /socket/poll/{conn} GET+POST) with ROUTES rows, and the handlers calling kchannels::sse_open / relay_post / poll_open / poll_get.
  7. Tests: port support::Ws to offrails.v1, add wire_test.rs and the resume/session cases in kernel_pubsub_test.rs, and tests/e2e/realtime.spec.ts (channels.md#testing).

Upgrading apps from any agent

  • generators/upgrade.md: the upgrade recipe, agent-neutral (Claude Code, Codex, opencode, Cursor). /offrails:upgrade now runs it.
  • offrails upgrade [--check] in an app: compares content fingerprints with the installed framework, then launches Claude Code (/offrails:upgrade), opencode or Codex with the recipe, or prints the prompt. offrails new supports opencode too.
  • Vendoring: the rsync excludes are anchored (/skills, /hooks, /evals, /brand…), so tools/brand/ is kept, and --delete removes files dropped upstream. Vendor a release tag, never a moving working tree. .github/ is vendored on purpose, so fingerprints match the release.

App migration: none required. Next time you upgrade, vendor with the anchored excludes (generators/new.md step 1); tools/brand/ reappears in .offrails/.

  • kernel::db::ping (for /up) and kernel::db::drop_idle_test_databases (for test_db_cleanup): no raw SQL outside the kernel.
  • Panics render the standalone 500 page via CatchPanicLayer::custom(error::panic_response).
  • Pending-migrations guard is layered after the fallback, so unknown paths show the page too.
  • /dev/mailers answers 301 explicitly (Redirect::permanent is 308).
  • Magic links: consume is one transaction returning user, session and token; first-login user creation uses ON CONFLICT DO NOTHING (a unique violation aborts a Postgres transaction; a general rule in models.md); Option<CurrentSession> needs OptionalFromRequestParts in axum 0.8; token pages send Cache-Control: no-store and Referrer-Policy: no-referrer. The variant is now verified (168 tests, both databases, real browser).
  • htmx: a 422 re-render sends HX-Push-Url: false, so the address bar keeps the form's URL.
  • Error pages load app.js, so Forward from a 404 works; test-standards §9 checks it.
  • Tests: wait_until(what, f: impl AsyncFn() -> bool); enqueued returns (job::Model, W); per-email rate limits are tested across IPs with APP_TRUSTED_PROXY + X-Forwarded-For.
  • Docs: #[rustfmt::skip] on ROUTES; kernel pages use no confirm() dialogs (data-confirm pattern for app pages); the e2e package arrives with the first critical flow; port checks with lsof -sTCP:LISTEN; direct TLS is added on first use; dates are UTC; guidance for interview answers relayed by another agent.

App migration (reconcile, don't re-create):

  1. Detect: grep -rn "execute_unprepared" src/controllers src/tasks. Converge: move each into kernel::db (ping, drop_idle_test_databases) and call those.
  2. Detect: CatchPanicLayer::new() in src/routes.rs, or a CatchPanicLayer::custom(|_| …) closure that ignores the panic payload or doesn't render errors/500.html. Converge: CatchPanicLayer::custom(error::panic_response), rendering errors/500.html; add a test that a panicking handler returns the 500 page.
  3. Detect: migrations::guard is layered before .fallback(...) in src/routes.rs (structural), or, with the app running and a pending migration, GET /no-such-path returns 404 instead of the pending page. Converge: apply migrations::guard after .fallback(...).
  4. Detect: GET /dev/mailers returns 308. Converge: return 301 explicitly.
  5. Magic-link apps: detect a sign-up path that catches a unique violation inside a transaction. Converge: on_conflict_do_nothing_on([Column::Email]) + select. Add no-store and Referrer-Policy: no-referrer to the token pages, with a test.
  6. htmx apps: detect a 422 re-render without HX-Push-Url: false. Converge: set it once, at the end of error::shape_errors (it sees every 422, whether a handler rendered it or AppError::Invalid did, and covers future forms); add a request test asserting the header on a 422 from an htmx request.
  7. Detect: templates/errors/*.html without /static/app.js. Converge: add <script src="/static/app.js" defer></script>; extend the browser smoke with Forward from a 404.

0.3.0 (2026-10-13)

What's new

  • Open source (MIT OR Apache-2.0), with a one-line install (curl -fsSL https://rustoffrails.org/install.sh | sh) and the offrails command (new, doctor, version, update, uninstall).
  • Security headers in one middleware (kernel/security.rs), a __Host- session cookie in production, a STRIDE section in every feature spec, and CI that runs cargo-deny, gitleaks and a ZAP scan.
  • API-only apps and a public API: FRONTEND_MODE: api and an API: none | rest | graphql | both header line; REST under /api/v1 with bearer tokens and OpenAPI, or GraphQL.
  • Svelte as a UI library, chosen with a new UI_LIBRARY header line.
  • Realtime channels: one WebSocket per tab, rooms with presence, an opt-in Postgres cluster layer, and faster signals (NOTIFY on Postgres: 238 ms to 2.1 ms).
  • compose.yaml runs the whole app, and every app with pages gets favicons, social cards, robots.txt and a sitemap from day one.

Breaking changes

  • FRONTEND_MODE: react is renamed spa, and the app's AGENTS.md header gains UI_LIBRARY and API lines.
  • The production session cookie is renamed __Host-session_token: deploying logs everyone out once.
  • The frontend type-check is pnpm --dir web typecheck; web/package.json needs a typecheck script.
  • Every mounted route must have a ROUTES row (a new test fails otherwise).

Upgrading

Each subsection's App migration list below. The procedure is in upgrade.

Full list of changes

The open-source release. Rust off Rails is public at https://github.com/rust-off-rails/rustoffrails and installs with one line: curl -fsSL https://rustoffrails.org/install.sh | sh.

One-line install and the offrails command

  • install.sh (POSIX sh): shows its plan first, --dry-run, --yes; Rust via rustup (no sudo); sea-orm-cli, cargo-nextest and cargo-watch as prebuilt binaries via cargo-binstall; a SHA-256-verified framework release in ~/.offrails/<version> with a current symlink; installs the Claude Code plugin when claude is present; prints the AGENTS.md prompt for Codex and Cursor. Idempotent, no telemetry. See INSTALL.md.
  • offrails: new <name> "<pitch>", doctor, version, update, uninstall.
  • New apps also get .cursor/rules/offrails.mdc and .github/copilot-instructions.md, pointing to AGENTS.md.

App migration: optional. Add the two agent pointer files above.

Open source

  • Dual licensed MIT OR Apache-2.0; SECURITY.md (GitHub private vulnerability reporting), CONTRIBUTING.md (contributions are intent plus evidence), Code of Conduct, issue forms ("Agent got stuck" first), and CI: links, hook tests, plugin validation, gitleaks, installer tests, OpenSSF Scorecard.
  • Brand: the \R/ derailing mark and the hopping "off" wordmark, drawn as code (brand/).
  • Doctrine §0, "All code is written by AI", is now the founding rule.
  • Plugin: /offrails:security skill; hooks for security tripwires, banned crates in Cargo.toml, append-only committed migrations, raw .begin(), and no pkill; content-fingerprint drift detection; /offrails:upgrade reconciles instead of re-creating.

Security as the gold standard: Non-negotiables, the header matrix, automated enforcement

Spec: guides/security.md (Non-negotiables, the header matrix, Automated enforcement, Gotchas), plus blueprints/feature-spec.md (a ## Security STRIDE section), workflow.md, guides/test-standards.md §3, guides/testing.md CI, generators/new.md, stack.md, structure.md, guides/routing.md and guides/auth.md. Plugin: the /offrails:security skill and security tripwires in the hooks. Verified on the reference app (branch security): 207 tests on SQLite and Postgres 18; cargo-deny advisories/bans/licenses/sources ok; gitleaks clean over the history; ZAP baseline 0 FAIL, 0 WARN, 61 PASS; checked in Chrome.

  • kernel/security.rs, one middleware outside the panic and timeout layers:
    • the full header matrix, adding object-src 'none', COOP and CORP to what was there;
    • upgrade-insecure-requests and HSTS only with an https APP_URL;
    • no-store on every authenticated response;
    • production cookies forced to Secure; HttpOnly; SameSite=Lax.
  • Session cookie: __Host-session_token in production, and production ignores the plain name.
  • CI:
    • a security job (cargo-deny + gitleaks over the full history);
    • the Docker job boots the production image and runs the ZAP baseline;
    • Dependabot.
  • Findings fixed:
    • the flash cookie had no Secure in production;
    • authenticated pages were cacheable;
    • panic 500s and timeout 408s had no security headers.

App migration (reconcile, don't re-create):

  1. Header middleware. Detect: src/kernel/security.rs.
    • Missing: generate it per guides/security.md#the-header-matrix. In routes.rs, replace the per-header SetResponseHeaderLayers and the CSP const with one .layer(from_fn_with_state(security::Hardening::new(&config), security::middleware)) placed after (outside) CatchPanicLayer.
    • If a route sets its own CSP (the mailbox viewer), keep it. The middleware only fills in missing headers.
  2. Session cookie. Detect PROD_COOKIE in kernel/session.rs. Missing: add name(secure) and make read(headers, secure) accept only name(secure). Update cookie/clear_cookie, the load_session caller and any WebSocket upgrade that reads the cookie. Tests use ksession::name(config.is_production()). Deploying logs everyone out once, because the cookie name changes. Say so to the human.
  3. tests/app/headers_test.rs. Add it (one row per response class the app has), plus TestApp::request_head. Production rows use an https:// APP_URL. Make it fail first if the middleware is off.
  4. Scanner configs. Add deny.toml (copy the reference in security.md; keep any [bans] the app already has), with publish = false in both crates. Add .gitleaks.toml, .zap/rules.tsv (+ .zap/.gitignore) and .github/dependabot.yml. Run each scanner locally. Fix findings, or triage them with a reason in the config.
  5. CI. Add the security job and the Docker job's boot + ZAP steps from guides/testing.md#ci. Lint with actionlint.
  6. Feature specs. Add a ## Security section to every product/features/*.md (blueprints/feature-spec.md). Each threat gets a control and a test. A threat without a test is a finding.

API-only apps, the API axis (REST + OpenAPI, GraphQL), Docker compose, day-one meta and favicons

Spec: guides/api.md and guides/graphql.md (new), tools/brand/render.sh (new), plus interview.md, blueprints/AGENTS.md, generators/new.md, generators/scaffold.md, guides/views.md, guides/deployment.md, guides/auth.md, guides/controllers.md, guides/config.md, guides/test-standards.md, stack.md, structure.md, cli.md, RAILS_MAP.md. Verified with the offrails-api-demo app (FRONTEND_MODE: api, API: both): 151 tests green on SQLite and Postgres 18, clippy clean, GraphiQL and the Scalar reference checked in Chrome, docker compose up --build from scratch plus the mail and worker profiles, and direct TLS (h2 via ALPN).

  • FRONTEND_MODE: api (rails new --api): no UI, JSON errors everywhere except /dev and /admin, GET / as a JSON index, /robots.txt disallowing all.
  • API: none | rest | graphql | both, a separate header line, chosen in the interview. REST lives under /api/v1:
    • bearer API tokens (api_tokens, SHA-256 digests, scopes, expiry);
    • ApiJson (JSON error shape for bad bodies) and {"data": …} envelopes;
    • an OpenAPI document via utoipa, committed as docs/openapi.json with a drift test, plus Scalar at /dev/api-docs.
  • GraphQL lives at POST /graphql: async-graphql, DataLoaders, depth (≥ 13, or introspection breaks) and complexity limits, payload UserErrors, docs/schema.graphql with a drift test, GraphiQL at /dev/graphiql.
  • CORS comes from APP_CORS_ORIGINS: exact origins, also trusted by CSRF, no credentials. Per-token rate limits.
  • compose.yaml runs the whole app: the production image plus Postgres with healthchecks, and profiles worker and mail. New app health subcommand for container healthchecks.
  • Day-one brand and meta for every mode with pages:
    • tools/brand/render.sh writes favicon.svg, favicon.ico, apple-touch-icon.png, icon-512.png and og.png;
    • Ctx carries the title, description and canonical URL;
    • the layout has Open Graph and Twitter tags;
    • /robots.txt and /sitemap.xml;
    • smoke tests assert all of it.
  • Web server: documented as axum on hyper (HTTP/1.1 + h2c); optional direct TLS via APP_TLS_CERT/APP_TLS_KEY (axum-server + rustls).
  • Fixed: serde_html_form is a kernel dependency (the jobs dashboard's filter links). new adds it again, which corrects the earlier doc-fix pass.

App migration (reconcile, don't re-create):

  1. Header. If AGENTS.md has no API: line, add API: none under ISLANDS:. An app that already serves a public API (tokens, /api/v1) records rest, and follows guides/api.md for anything it lacks.
  2. compose.yaml. Detect: grep -q '^ app:' compose.yaml.
    • If it has only postgres/db, replace it with the shape in guides/deployment.md#docker-compose-the-whole-app-locally. Keep the existing Postgres major and volume name (renaming the volume loses local data; say so).
    • Add app health to src/main.rs if missing.
    • Verify with docker compose up --build, then down -v.
  3. Brand and meta (modes with pages).
    • Detect: static/og.png, static/apple-touch-icon.png, and og:image in the layout or shell.
    • Missing: run bash .offrails/tools/brand/render.sh "<APP_NAME>" "<accent from the layout>" "<pitch from product/README.md>" static, add the <head> tags and the Ctx meta fields from guides/views.md#meta-favicon-and-social-cards-every-app-with-pages, route /favicon.ico, /robots.txt, /sitemap.xml, and add the smoke-test assertions.
    • An existing hand-made favicon or OG image wins. Don't overwrite it; only fill in what's missing.
  4. serde_html_form. Ensure it's in Cargo.toml (cargo add serde_html_form). It's harmless if already present.
  5. Adding API: rest | graphql to an existing app is a feature, never part of an upgrade. Spec it, then follow guides/api.md / guides/graphql.md and generators/scaffold.md step 9b per resource.

Svelte as a UI library; the react mode is renamed spa

Spec: guides/frontend-svelte.md (new); stack.md, interview.md, blueprints/AGENTS.md, structure.md, generators/new.md and generators/scaffold.md updated. Verified in Chrome:

  • Inertia + Svelte 5 on the reference app: every protocol check, 409 redeploy reload, HMR, Playwright, 75 Rust tests on SQLite and Postgres;

  • a SvelteKit SPA served by Rust under a strict hashed CSP;

  • a Svelte island.

  • The app header gains UI_LIBRARY: react | svelte | none. FRONTEND_MODE values are now htmx | inertia | spa | api (api is specified by the API-only work).

  • FRONTEND_MODE: react is now spa. Same architecture; the name no longer implies the library.

  • The DoD's frontend type-check is pnpm --dir web typecheck. React keeps "typecheck": "tsc -b"; Svelte uses svelte-check --fail-on-warnings.

App migration (existing apps; reconcile, don't regenerate):

  1. Detect FRONTEND_MODE: in AGENTS.md.
    • If it says react, change it to spa and add UI_LIBRARY: react under it.
    • If it says inertia, or ISLANDS: yes, add UI_LIBRARY: react.
    • Otherwise add UI_LIBRARY: none. No code changes. Log the header change in docs/decisions.md.
  2. If web/package.json has no typecheck script, add "typecheck": "tsc -b". CI and the DoD now call pnpm --dir web typecheck; update .github/workflows/ci.yml if it runs exec tsc -b directly.
  3. Switching an existing app to Svelte is a human decision, never part of an upgrade. If asked, follow guides/frontend-svelte.md: the Rust side changes only VITE_ENTRY and drops the React refresh preamble route.

Realtime: channels, presence, the hub, the cluster layer

Spec: guides/channels.md (new), plus changes to guides/realtime.md. Verified in the reference app (book page: "reading now" avatars and a live discussion), with 21 tests on SQLite and Postgres 18 including a 3-node failover, a Playwright smoke, and a manual server-restart check in Chrome.

  • Signals got fast. pubsub::broadcast now wakes the poller: NOTIFY at commit on Postgres (238 ms → 2.1 ms) and an in-process Notify on SQLite (→ 0.24 ms). The 250ms poll remains as a backstop. New PubSub::start_with(poll_every).
  • Channels:
    • GET /socket: one WebSocket per tab, Phoenix v2 wire format, topics joined with authorization;
    • kernel/hub.rs: a room actor per topic, supervised; serialize-once fan-out; slow consumers dropped; presence by person;
    • kernel/channels.rs: Origin check, auth at upgrade, frame and rate limits;
    • static/channels.js, and /dev/sockets.
  • Cluster (opt-in, Postgres): kernel/cluster.rs, with cluster_nodes heartbeats, a NOTIFY bus, rendezvous ownership, forwarded calls, presence cleanup and failover. Settings: APP_CLUSTER, APP_NODE.
  • Fixed: the reference app's ROUTES table had no rows for books, reviews, blobs or streams, so the access matrix never tested them. New test every_mounted_route_is_in_the_routes_table parses src/routes.rs and fails on any mounted path missing from ROUTES.

App migration (an agent upgrading an existing app; reconcile, don't re-create):

  1. Every app: route table drift.
    • Detect: any .route("…") path in src/routes.rs without a ROUTES row.
    • Converge: add the rows with their real Access (check each handler's extractor). Then add the every_mounted_route_is_in_the_routes_table test from guides/test-standards.md §3 (tests/app/security_test.rs), and run the security suite, which may now fail on routes it never covered. Fix those routes, not the test.
  2. Apps with SSE channels: faster signals.
    • Detect: kernel/pubsub.rs without pg_notify / WAKE.
    • Converge: add the NOTIFY (Postgres) and WAKE (SQLite) calls in broadcast, start_with, and the dedicated listener task, per realtime.md's kernel spec.
    • Tests: the wake-up test (start_with(60s)) and the rollback test.
    • No schema change.
  3. Apps that need rooms or presence: only when a spec asks for them. Run generators/channel.md → room recipe.
    • Detect: an existing hand-rolled axum::extract::ws handler.
    • Converge: move its topics into Room impls behind /socket. Keep the old route as long as clients depend on it, and log the deviation.

0.2.0 (2026-10-12)

What's new

  • A full persistent job queue (Oban-style: queues, timeouts, cancellation, cron, unique jobs, graceful shutdown) and the /admin/jobs dashboard to inspect and act on it.
  • A dev mailbox at /dev/mailbox: every email sent in development, as HTML, text or raw, on desktop or mobile, with previews and JSON for agents.
  • /dev and a pending-migrations page: in development, pending migrations show a page with a Run button instead of a broken app.
  • Magic-link sign-in as a first-class accounts variant, and a TENANCY header line.
  • Safer data changes: every transaction starts with kernel::db::begin (BEGIN IMMEDIATE on SQLite, so the job worker can't cause "database is locked"), and committed migrations are append-only.
  • Test standards: acceptance-criteria ids, an access matrix over every route, tenant isolation, coverage gates and a real-browser smoke.

Breaking changes

  • DeliverEmailJob becomes a struct (rows already queued still decode), mailer selection moves to state::select_mailer, and development always uses the local mailbox.
  • /dev/mailers becomes a 301 to /dev/mailbox/previews.
  • A plain db.begin() outside the kernel is flagged; use kernel::db::begin. Edits to committed migrations fail CI and are blocked by the plugin.
  • The migration crate drops its cli feature and migration/src/main.rs.
  • Postgres test databases are named test_<crate>_<hex>.
  • New settings MAILER and APP_REVISION; APP_URL defaults to localhost in development; production refuses to boot without static/app.css.

Upgrading

The numbered App migration list (steps 1–20) at the end of this section. The procedure is in upgrade.

Full list of changes

The kernel UIs, verified end to end in a real app (bookshelf, htmx, SQLite + Postgres 18, Chrome): the full Oban-style queue and /admin/jobs, a Swoosh-grade dev mailbox, /dev, and a pending-migrations page. Specs: guides/jobs.md, guides/jobs-dashboard.md, guides/mailers.md, guides/dev-tools.md.

  • Jobs: producers per queue with semaphores, an optimistic claim, timeouts, panic capture, cancellation of executing jobs (Heartbeat aborts), snooze/cancel/discard, the Stager/Lifeline/Pruner/Cron plugins as plain functions, uniqueness via on_conflict_do_nothing_on → TryInsertResult::Conflicted (sea-orm 2), and graceful shutdown. JobBuilder is non-generic (JobDefaults + serialized args). Recurring { key, cron, job: fn() -> JobBuilder }; cron jobs are tagged cron with meta.cron = key.
  • /admin/jobs: overview (counters, throughput SVG, queues, nodes), filtered list with bulk actions and an "all matching" confirmation page, job timeline + error history, cron page, live polling, flashes, no-store.
  • Dev mailbox: two panes (Inbox/Previews), Cc/Bcc/Reply-To, attachments, HTML/Text/Raw, Desktop/Mobile, links, .eml at /dev/mailbox/{id}/message.eml, new-mail banner, test-email button, JSON for agents. /dev/mailers → Previews tab.
  • Mailer selection: development is always Mailer::Local (MAILER=smtp|local|log overrides); Log is only the production fallback. Selection moved from the kernel into state::select_mailer.
  • Email: Email gains cc, bcc, reply_to, attachments (all #[serde(default)]). DeliverEmailJob becomes { #[serde(flatten)] email, expires_at } with MAX_ATTEMPTS = 10; mailers::deliver_later_until for time-limited mail without secrets. Token emails use dedicated ids-only jobs (no secrets in job args). The one mail layout is templates/mailers/layout.html.
  • Back/Forward and hx-boost: kernel routers are no-store, the kernel layout has historyCacheSize: 0 and static/kernel/admin.js (pageshow reload), gone records redirect with a flash, and app links into kernel pages carry hx-boost="false".
  • Pending migrations: a dev-only page with a Run button, /up 503 while pending, the worker waits, and bin/dev migrates.
  • Config: in development APP_URL defaults to http://localhost:{PORT}. New MAILER, APP_REVISION.
  • Migration crate: sea-orm-migration without its cli feature; no migration/src/main.rs.
  • Tooling: .offrails/tools/browser-smoke/ (optional; puppeteer-core cached outside the app).
  • SQLite transactions: every transaction starts with kernel::db::begin(&db) (BEGIN IMMEDIATE on SQLite). A plain db.begin() is deferred and fails with "database is locked" when the job worker writes between your read and your write. Tests missed it because the in-memory test database has one connection; a regression test now uses a real file. The plugin flags .begin().await outside the kernel.
  • Migrations are append-only once committed. Edited applied migrations never reach existing databases. CI fails a change that modifies a committed migration, and the plugin blocks such edits.
  • Errors on boosted pages are visible. static/app.js shows the server's error page for 5xx on boosted requests, and the layout's responseHandling swaps 422 and 429.
  • Auth:
    • magic-link login is a first-class variant (ACCOUNTS: magic-link | magic-link-invite), recommended in the interview. It's fully specified in auth.md: POST to consume, single use, 15 minutes, enumeration-safe, rate-limited per IP and per email;
    • the dev "check your mailbox" hint on every auth screen that sends email;
    • every auth email has a mailer preview;
    • failed admin Basic-auth passwords are rate-limited (10 per 3 minutes per IP);
    • TENANCY: per-user | teams | shared | none.
  • Live updates (SSE): events carry non-empty data (browsers drop empty ones); one /streams/{stream} route; streams end on shutdown; the app layout uses historyCacheSize: 0 and refreshOnHistoryMiss: true.
  • CSS check: development warns and shows a banner when static/app.css is missing or empty; production refuses to boot without it.
  • Errors: the 422 fallback renders templates/errors/_invalid.html (never HTML from format!). The router fallback marks its 404 with x-route-fallback: 1, so the routability test is exact for parameterized routes.
  • Tests: test-standards.md (AC IDs, archetype suites, the access matrix over ROUTES with an Access column, tenant isolation, coverage and mutation gates with a per-path jq check, query-count guard, real-browser smoke). TestApp gains assert_text, without_fetch_metadata, post_multipart, get_htmx and SSE helpers. Postgres test databases are test_<crate>_<hex>, and test_db_cleanup drops only this app's idle ones.
  • New guidance: dark mode (OS-following by default; a no-flash cookie toggle with a verified Tailwind 4 variant); public pages (meta, OG image, canonical, robots, sitemap, self-hosted fonts, Lighthouse ≥ 95); trusted vs user Markdown (heading ids, ammonia builder); runtime-read directories in the Dockerfile; how an agent runs, checks and stops the app (never pkill by name).
  • Plugin: drift is detected by content fingerprint, not just the version line. Hooks block pkill/killall by name and edits to committed migrations, and flag .begin() outside the kernel and sleep in tests. /offrails:upgrade reconciles instead of recreating.
  • Docs fixes: sea-orm 2 pitfalls (ActiveModel::default() ambiguity, OFFSET without LIMIT on SQLite, jsonb text search), axum's whole-segment params, the CSP ⇄ htmx-config pairing (verified in Chrome), lettre quoted-printable links.

App migration (reconcile, don't recreate). For each item: detect what the app already has, compare with the final shape, then converge. Classify each as new, present-conforming, present-divergent or conflicting. Never edit or re-run an applied migration; add a new one. Commit per item, green on both databases.

  1. mailbox_messages table. Detect: the table exists (any m…_create_mailbox_messages, applied). Final columns: id, to_addr, from_addr, cc json [] , bcc json [], reply_to string null, subject, html text, text text, headers json, eml text, attachments json [], read_at timestamptz null, created_at. Converge: generate m<ts>_alter_mailbox_messages that adds only the missing columns (SQLite-safe: one ALTER TABLE … ADD COLUMN per column, with defaults; nullable read_at). If the app named the raw message something else (e.g. raw_eml), keep the column and map the entity field with #[sea_orm(column_name = "raw_eml")] pub eml: String rather than renaming. Missing table: new, so generate create_mailbox_messages.
  2. Email and delivery. Detect: src/kernel/mailer.rs::Email fields, Mailer variants, whether selection lives in the kernel (Mailer::from_config). Converge: add the four #[serde(default)] fields and Attachment; extend build() (Cc/Bcc/Reply-To, multipart/mixed); add constructors Mailer::smtp/local/memory; move selection to state::select_mailer with the table in mailers.md. Delete any file-writing/"logged locally" dev mailer: development must be Local. Update the EMAIL header line to dev: local mailbox (/dev/mailbox); prod: ….
  3. DeliverEmailJob. Detect: tuple struct DeliverEmailJob(Email). Converge: struct DeliverEmailJob { #[serde(flatten)] email: Email, #[serde(default)] expires_at } (rows already queued as a bare Email still decode; add the decode test), MAX_ATTEMPTS = 10, expiry discard; add mailers::deliver_later_until for time-limited mail without secrets. Any email carrying a token (password reset, login link, confirmation, invitation) must not be enqueued rendered: detect deliver_later(…) calls whose email embeds a token, and replace each with a dedicated ids-only job (5 attempts, discard when stale) that mints the token, stores its digest and delivers (guides/auth.md).
  4. Dev mailbox UI. Detect: kernel/mailbox.rs routes (/dev/mailbox, /dev/mailbox/{id}, any /{id}.eml or /{id}/raw), templates under templates/kernel/mailbox/ or elsewhere, a separate /dev/mailers page. Final: the route table in mailers.md (/dev/mailbox, /{id}, /{id}/message.eml, /{id}/html, /{id}/attachments/{n}, /{id}/delete, /clear, /test, /previews, /previews/{*name}, .json, /latest.json), kernel::mailbox::router(PREVIEWS) with .layer(ui::no_store()), the templates and kernel/ui.rs chrome. Converge: replace the module and templates with the spec (the table is the only state). Keep any existing .eml/raw URL as a redirect to /message.eml if anything links to it. Move previews: create src/mailers/previews.rs with PREVIEWS (port each existing preview fn), make GET /dev/mailers a 301 to /dev/mailbox/previews, and delete the old previews page and templates.
  5. Links into kernel pages. Detect: grep -rn 'href="/dev\|href="/admin' templates/ web/src/ (the footer "Dev tools" link, mailbox hints on /session/new, /login-links/sent, nav to /admin/jobs). Converge: add hx-boost="false" (htmx) or use a plain <a> (TS modes); use paths::dev_mailbox(); add app_links_into_kernel_pages_are_not_boosted.
  6. Jobs kernel. Detect: src/kernel/jobs/ files, the jobs columns (compare with jobs.md, Tables), job_queues/job_nodes/recurring_executions. Converge: missing tables or columns via a new migration; then replace kernel/jobs/ with mod.rs/executor.rs/plugins.rs/admin.rs/web.rs per the spec. Adapt src/jobs/mod.rs (into_job → JobBuilder::new(JobDefaults{…}, serde_json::to_value(&self)), fn unique(), worker_config → WorkerConfig::default() fallback), recurring.rs to &[Recurring], and main.rs's WorkerOptions and app jobs … CLI. Keep every existing Worker::NAME.
  7. /admin/jobs, /dev, pending migrations. Detect: kernel/jobs/web.rs, controllers/dev.rs routes, controllers/migrations.rs. Converge to jobs-dashboard.md and dev-tools.md: route_layer(AdminAccess), no_store() on each kernel router, the test buttons, /dev/system via get_*_migrations_read_only, the migrations::guard layer (development only), /up 503 while pending, the worker waiting for migrations, bin/dev migrating first. Add every new route to ROUTES (Access::Admin / Access::Dev).
  8. Assets and layout. Add admin_js to Assets, static/kernel/admin.js, historyCacheSize: 0 in templates/kernel/layout.html's htmx-config, templates/mailers/layout.html (move an existing templates/layouts/mailer.html there and update {% extends %}).
  9. Config. APP_URL defaults to dev_app_url(PORT) in development (parse PORT first); add mailer (MAILER) and revision (APP_REVISION) to Config, .env.example and the deploy config.
  10. Migration crate. If migration/Cargo.toml uses default features: set default-features = false and delete migration/src/main.rs (check nothing runs cargo run -p migration).
  11. Transactions. Detect: grep -rn '\.begin()\.await' src/ | grep -v src/kernel/. Converge: add kernel::db::begin (database.md: begin_with_options with SqliteTransactionMode::Immediate; Postgres ignores the mode) and replace every call site. Add the file-backed SQLite regression test (a write racing a read-then-write transaction).
  12. Append-only migrations. Detect: git log --diff-filter=M -- migration/src/m*.rs (edits to migrations after their first commit). Any hit is present-divergent: restore the committed original and move the change into a new alter migration. Then add the CI guard step from testing.md (fails when a committed migration file is modified).
  13. Boosted errors. Detect: static/app.js lacks an htmx:responseError/htmx:beforeSwap handler for 5xx; the layout's htmx-config lacks responseHandling for 422/429. Converge to frontend-htmx.md (both pieces), and check in a browser that a forced 500 on a boosted form shows the error page.
  14. Auth (only if ACCOUNTS isn't none). Detect the variant actually built (password tables, login_links/login_tokens). Record it in ACCOUNTS (an improvised passwordless flow = magic-link). Converge to auth.md's variant: token digest only, single use, the TTL, GET → confirm page → POST consumes, the same response for known and unknown emails, rate limits per IP and per email, and the token minted inside its job. Add a mailer preview for every auth email, and the dev mailbox hint (templates/shared/_dev_mailbox_hint.html, development + Mailer::Local only) with its present-in-dev/absent-in-prod test. Admin Basic auth: add the failed-attempt limiter (security.md).
  15. SSE. Detect: Event::default().event(…) without .data(…), or per-resource stream routes. Converge to realtime.md: non-empty data, one /streams/{stream} route, take_until(pubsub.closed()), and the app layout's historyCacheSize: 0 + refreshOnHistoryMiss: true.
  16. Errors and routing. Converge controllers::errors::not_found to return the x-route-fallback marker, have shape_errors keep it, and tighten every_route_is_routable_in_development to use it. Render the 422 fallback with templates/errors/_invalid.html. Delete any format!-built HTML.
  17. Postgres test databases. Detect: test_<hex> names in tests/app/support.rs. Converge to test_<crate>_<hex>, the joined-thread Drop, and the scoped, idle-only test_db_cleanup (testing.md#database-per-test).
  18. Env files. In .env.example (and the human's .env, if present and if they agree), comment out APP_URL for development; keep it required in production.
  19. CSS check. Converge kernel/assets.rs to warn and show a banner only when static/app.css is missing or empty (never by timestamp: Tailwind 4 doesn't rewrite unchanged output), and to fail boot in production.
  20. Tests. Bring tests/app/kernel_jobs_test.rs and kernel_web_test.rs to the lists in new.md step 7 (both backends), and support.rs to the job helpers + wait_until. Then the Definition of Done, and, if Node ≥ 22.12 and Chrome are present, bash .offrails/tools/browser-smoke/run.sh.

0.1.0 (2026-10-12)

What's new

  • The framework docs: the conventions, guides and recipes an agent follows to build a Rust web app.
  • The Claude Code plugin: the new, feature, scaffold, generate, check, doctor, deploy and upgrade skills, and the convention hooks.
  • Ideas borrowed from Phoenix/Elixir: Oban-style persistent jobs with the /admin/jobs dashboard, a Swoosh-style /dev/mailbox, and a /dev toolbox.

Breaking changes

None (first release).

Upgrading

Nothing to upgrade: this is the baseline.

Full list of changes

First release:

  • The framework docs.
  • The Claude Code plugin:
    • skills: new, feature, scaffold, generate, check, doctor, deploy, upgrade;
    • the convention hooks.
  • Borrowed from Phoenix/Elixir:
    • Oban-style persistent jobs: a state machine, history, queues with pause/resume, unique jobs, snooze/cancel/discard, the Stager/Lifeline/Pruner/Cron helpers, and Oban.Testing-style helpers;
    • the /admin/jobs dashboard (Oban Web);
    • the Swoosh-style /dev/mailbox;
    • a /dev toolbox.

App migration: none (baseline).