Rust off Rails 0.7.3

What's new

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

Breaking changes

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

Upgrading

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

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

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

Full list of changes

• Snippets: small, tested code to copy (snippets). The human, after a timed blog build on 0.7.2 (43 min, most of it friction, ~2,240 hand-written lines): "make generators kinda optional, i guess i still prefer snippets to generators... or generators that have good insertion or removal points. ideally multiple smaller files." The blog had hand-written (or fought) a feed, slugs, Markdown, the pager, a theme button, backdated seeds and a public page by slug. Each is now a snippet in template/snippets/<name>/: a README (what, when, the files, the anchors it wires into, how to remove it), a snippet.toml in a part's sample.toml format (plus as, the model --as renames, and snippets, the snippets it builds on) and files/ at app paths.
  • The eight: resource (htmx CRUD for notes, public: exactly the files g resource notes title:string body:text --public writes; a test in offrails-gen keeps the two identical), atom-feed (GET /feed.xml, escaped by Askama, RFC 3339 dates, newest 20, <link rel="alternate"> on every page), slug (slugify, accents folded, 80 chars; unique(base, query): -2, -3…, per owner or global), markdown (pulldown-cmark + ammonia; tests for <script>, `o...

Rust off Rails 0.7.2

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.

    Step	Bare, old	Bare, new	Every part, old	Every part, new
    Cold build (cargo build, then the test targets)	217 s + 38 s (load 22–45)	same dependencies, same	180 s + 59 s (load 31–53)	same
    Cold build, a second app on the machine	293 s (load 121)	128 s with sccache (opt-in; load 127)	n/m	n/m
    No-op rebuild of the tests	0.5–0.7 s	same	0.65 s	same
    One-line change, test build	3.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 change	1.9 s	1.1–2.3 s, beside the build	8.1 s	7.7–9.5 s, beside the build
    SQLite suite	1.3 s (121 tests)	1.4 s	8.0–10.4 s (652 tests)	8.5–9.5 s
    Postgres suite	8.0 / 11.9 s (load 15–18)	1.7 / 1.8 s	149 / 46 s (load 12–37)	21 / 14 s (load 17–20)
    The fast loop: fmt, clippy, test build, SQLite, Postgres after a one-line change	140 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 unde...

Rust off Rails 0.7.1

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 ...

Rust off Rails 0.7.0

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](guides/auth.md#claiming-an-un...

Rust off Rails 0.6.2

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...

Rust off Rails 0.6.1

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](guides/realtime.md#render-once-per-version-the-thunder...

Rust off Rails 0.6.0

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 thei...

Rust off Rails 0.5.0

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).

Rust off Rails 0.4.0

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/.

Fixes from the Linkdrop build (a fresh agent, magic-link accounts)

• 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 fir...

Rust off Rails 0.3.0

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 `guide...