The Stack (the "Gemfile") #

One crate per job. Add each one with cargo add (and JS packages with pnpm add). Never write version numbers from memory.

Selection rubric (how these were chosen; do not re-run it) #

1. The model knows it. Crates with huge training-data presence produce fewer hallucinated APIs.
2. Types over strings. Prefer APIs where mistakes are compile errors.
3. Portable. The same code must run on SQLite (local, tests, small prod) and Postgres (prod).
4. Stable API. Crates that churn break agent-written code.
5. Fewer crates. If ~150 lines of generated code replace a niche crate, generate the code from a spec (see "Kernel" below).

Blessed crates #

"Added by" says when a crate enters the app: new adds the first group (exact commands in generators/new.md); the rest arrive with the generator or first feature that needs them. Adding everything up front costs compile time, and object_store brings a second TLS crypto provider (below).

Verified against (2026-10-12) #

The bookshelf reference app (htmx, SQLite + Postgres 18) was generated from these docs with cargo add and compiled, linted (clippy -D warnings) and tested on both databases with these resolved versions. This table is orientation, not a pin. Agents still cargo add and read Cargo.lock. When a resolved major/minor differs from this table, read that crate's changelog before writing code against it.

Exercised by the reference app's auth branch (2026-10-12): argon2 0.6.0, object_store 0.14.2, bytes 1.12. Resolved but not yet exercised: pulldown-cmark 0.13, ammonia 4.2. (ts-rs is exercised on the reference app's inertia branch; set TS_RS_LARGE_INT = "number", see frontend-inertia.)

Version gotchas found while verifying #

• MSRV-aware resolver. Edition 2024 resolves dependencies to versions compatible with the workspace's rust-version. sea-orm-cli migrate init writes rust-version = "1.85.0" into migration/Cargo.toml, which silently downgrades crates (e.g. uuid). Delete that line (new.md step 3).
• sea-query 1.0 (SeaORM 2): expression methods (.add(), .eq() on Expr) live on the ExprTrait trait. Importing it at module level makes i32::max/min ambiguous, so import it inside the function that needs it. LIKE … ESCAPE is Column::X.like(LikeExpr::new(pattern).escape('\\')).
• SeaORM 2 raw statements: ConnectionTrait::execute/query_one/query_all now take a query builder. For a Statement, use execute_raw / query_one_raw / query_all_raw (execute_unprepared(&str) is unchanged).
• SeaORM SQLite pool: if max_connections isn't set, SeaORM uses 1 for SQLite. kernel/db.rs always sets it.
• tower-http 0.7: TimeoutLayer::new is deprecated; use TimeoutLayer::with_status_code(StatusCode::REQUEST_TIMEOUT, d). The compression layer now answers 406 when a client refuses every encoding.
• Two rustls crypto providers. lettre/sqlx use ring; object_store (via reqwest 0.13) brings aws-lc-rs (cargo tree -i aws-lc-rs). A rustls client built from the process default provider would panic with both compiled in ("no process-level CryptoProvider"). Checked 2026-10-12 with object_store 0.14.2 and lettre 0.11.23: no panic. Real TLS handshakes to S3 and to SMTPS (port 465) succeeded without install_default, because both crates pass their provider explicitly. Re-check after upgrading either crate. If it ever panics, cargo add rustls --no-default-features --features ring and call let _ = rustls::crypto::ring::default_provider().install_default(); first in main and TestApp::new. (aws-lc-sys also needs cmake and a C compiler at build time. The rust:*-trixie image has them.)

Databases #

Portability rules are in guides/database.md. In short: everything goes through SeaORM, backend-specific SQL is allowed only in src/kernel/ or behind an explicit match on the backend, and the test suite proves both backends.

Frontend modes #

Every app has exactly one FRONTEND_MODE, chosen during the interview and recorded in the app's AGENTS.md. Don't mix modes. Islands are the one sanctioned hybrid. Modes with a JS UI (inertia, spa, islands) also have one UI_LIBRARY: react (default) or svelte (frontend-svelte). The mode decides the architecture, and the library decides only what web/ components are written in.

| api | No UI: the product is an API for mobile apps, partners or scripts (rails new --api) | Rust JSON API only: REST /api/v1 + OpenAPI and/or GraphQL (API header), bearer tokens. No templates, Tailwind or web/; kernel pages (/dev, /admin/jobs) still exist | api, graphql |

If the human says "React" or "Svelte" without a reason that points to spa, choose inertia with that UI_LIBRARY. A public API is a separate axis, API: none | rest | graphql | both, which any mode can have (api).

Blessed JS packages (inertia, spa, islands) #

Last verified 2026-10-12 (versions are for orientation only; always pnpm add without a version).

With UI_LIBRARY: svelte, these rows replace their React counterparts (details: frontend-svelte):

htmx mode (no Node): htmx 2.x (htmx.org@2; 4.x is not adopted) + htmx-ext-sse 2.x, vendored; Tailwind v4 standalone CLI pinned by TAILWIND_VERSION in bin/setup-tailwind. Verified: htmx 2.0.11, htmx-ext-sse 2.2.4, Tailwind 4.3.3.

Required tooling (install once per machine) #

cargo install --locked sea-orm-cli cargo-nextest cargo-watch
cargo install --locked cargo-llvm-cov cargo-mutants   # coverage gate + weekly mutation run (test-standards.md §5)
cargo install --locked cargo-deny                     # or `brew install cargo-deny` (verified 0.20.2): deny.toml gate
# gitleaks (verified 8.30.1: `brew install gitleaks`, or CI's ghcr.io/gitleaks/gitleaks:v8.30.1 image): secrets in history
# OWASP ZAP baseline: Docker image ghcr.io/zaproxy/zaproxy:stable (security.md#automated-enforcement)
# htmx mode: bin/setup downloads the Tailwind standalone binary to bin/tailwindcss
# inertia/react/islands: Node 24 LTS (fnm/nvm/mise/Homebrew), then pnpm:
#   corepack enable pnpm        # Node ≤ 24 ships corepack; Node 25+ doesn't, so there use: npm install -g pnpm
# Deploy CLIs only for the chosen target: flyctl, kamal (gem), railway, render — installed when DEPLOY_TARGET is set
# Postgres locally is optional: `docker compose up -d db` when testing against it
# Optional, any mode: Node ≥ 22.12 + an installed Chrome for .offrails/tools/browser-smoke/run.sh
#   (puppeteer-core is cached in ~/.cache/offrails, never added to the app; guides/dev-tools.md#browser-smoke)

The Kernel: code you generate instead of depending on #

These pieces are small, easy to get wrong in a generic crate, and central to the Rails experience. Generate them into src/kernel/ from the specs in the guides. The specs are the framework, and the code is your rendering of them. (CSRF used to be here; tower-http 0.7 now ships the same design as CsrfLayer, so it's a dependency instead.)

Banned (don't add these, don't propose them) #

Enforced mechanically: deny.toml [bans] fails CI if any of these appears anywhere in the dependency tree. Crates that healthy dependencies pull in transitively (lazy_static, once_cell, async-trait, log) are banned as direct dependencies only, which the plugin hook and /offrails:doctor check (security).

Adding a crate not on this list #

Only when a product/ spec requires a capability nothing above provides (for example, PDF generation or Stripe). Then:

1. Pick the most-downloaded, most-boring option.
2. cargo add it.
3. Add a line to the app's docs/decisions.md: YYYY-MM-DD: added <crate> for <spec>, because <reason>.