genesis-stack 1.3.1 → 1.4.0

package/README.md

@@ -37,10 +37,15 @@ any resolvable package may declare one when selecting that piece should install
 that skill. Documentation alone does not require a skill declaration or a
 catalog dependency.
 
-With Genesis 1.4 or newer, `genesis templates list` also lists the JSKIT starters
-in `genesis.templates.json`. Both variants come from
+With Genesis 1.4 or newer, `genesis templates list` also lists the starters
+in `genesis.templates.json`. The JSKIT ones come first, from
 the [JSKIT seed repository](https://github.com/vibe64-dev/seed-jskit):
-`official:jskit/public` and `official:jskit/accounts`. Apply one to an empty
+`official:jskit/public`, `official:jskit/database`, `official:jskit/accounts`
+and `official:jskit/accounts-hub`.
+Then each framework component has one Basic app, from the `basic` branch of its
+`vibe64-dev/seed-<technology>` repository: `official:django/basic`,
+`official:rails/basic`, `official:spring-boot/basic`, `official:express/basic`
+and `official:nextjs/basic`. Apply one to an empty
 Git/Genesis bootstrap project with `genesis templates apply <id>`. Template IDs
 name complete applications; selecting a Skill never silently chooses a starter.
 

package/genesis.templates.json

@@ -24,6 +24,54 @@
       "description": "Sign-up, login, a private home, MySQL persistence and isolated database/browser tests.",
       "repository": "https://github.com/vibe64-dev/seed-jskit.git",
       "branch": "accounts"
+    },
+    {
+      "id": "jskit/accounts-hub",
+      "technology": "jskit",
+      "name": "JSKIT · Accounts hub",
+      "description": "One sign-in for all your apps: your own accounts service with email sign-in, optional Google, and an Apps page where you approve each app.",
+      "repository": "https://github.com/vibe64-dev/seed-jskit.git",
+      "branch": "accounts-hub"
+    },
+    {
+      "id": "django/basic",
+      "technology": "django",
+      "name": "Django · Basic app",
+      "description": "Notes form persisted to SQLite, admin site, unit and HTTP tests. No accounts.",
+      "repository": "https://github.com/vibe64-dev/seed-django.git",
+      "branch": "basic"
+    },
+    {
+      "id": "rails/basic",
+      "technology": "rails",
+      "name": "Rails · Basic app",
+      "description": "Notes form saved to SQLite, sign-in with a seeded development account, ready model and HTTP tests.",
+      "repository": "https://github.com/vibe64-dev/seed-rails.git",
+      "branch": "basic"
+    },
+    {
+      "id": "spring-boot/basic",
+      "technology": "spring-boot",
+      "name": "Spring Boot · Basic app",
+      "description": "Notes page with a CSRF-protected form, MySQL/MariaDB via JPA and Flyway, and ready unit and HTTP tests. No accounts.",
+      "repository": "https://github.com/vibe64-dev/seed-spring-boot.git",
+      "branch": "basic"
+    },
+    {
+      "id": "express/basic",
+      "technology": "express",
+      "name": "Express · Basic app",
+      "description": "A small Express notes app that saves a form to SQLite, with unit and HTTP tests. No accounts.",
+      "repository": "https://github.com/vibe64-dev/seed-express.git",
+      "branch": "basic"
+    },
+    {
+      "id": "nextjs/basic",
+      "technology": "nextjs",
+      "name": "Next.js · Basic app",
+      "description": "A Next.js app with one form that saves notes to SQLite through a Server Action. No accounts.",
+      "repository": "https://github.com/vibe64-dev/seed-nextjs.git",
+      "branch": "basic"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-stack",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "The optional curated technology Stack catalog for Genesis projects.",
   "type": "module",
   "repository": {

package/stacks/pieces/django.md

@@ -70,10 +70,9 @@ https://docs.djangoproject.com/
   after `SecurityMiddleware`; `runserver` serves static files only while
   `DEBUG` is on. Keep `STATIC_ROOT` and media uploads out of Git.
 - Tests: `manage.py test` creates `test_<NAME>` and needs permission to
-  create databases. When the environment supplies a separate disposable test
-  database instead, set `DATABASES["default"]["TEST"]["NAME"]` from it and keep
-  `--keepdb`, which reuses an existing database rather than creating or
-  dropping one. Never point tests at the development or production database.
+  create databases; the database integration says how a supplied test
+  database replaces it. Never point tests at the development or production
+  database.
   Suites that create users spend most of their time hashing passwords: set
   `PASSWORD_HASHERS = ["django.contrib.auth.hashers.MD5PasswordHasher"]` only
   in a test settings module or under `if sys.argv[1:2] == ["test"]:`; never
@@ -87,9 +86,10 @@ https://docs.djangoproject.com/
   review `manage.py check --deploy`. It rejects the console email backend that
   recent `startproject` templates configure (`MAILERS` or `EMAIL_BACKEND`), so
   select the production email backend and its credentials from the
-  environment. When `SECURE_SSL_REDIRECT` is on, add the
-  readiness path to `SECURE_REDIRECT_EXEMPT` so a plain loopback probe is not
-  redirected.
+  environment. When `SECURE_SSL_REDIRECT` is on, exempt the
+  readiness path so a plain loopback probe is not redirected; entries are
+  regexes matched against the path without its leading slash, so use
+  `SECURE_REDIRECT_EXEMPT = [r"^admin/login/$"]`.
 - The proposed readiness path is the admin login page `/admin/login/`. An
   application without `django.contrib.admin` adds a small unauthenticated
   health view and updates its Outputs and Deployment readiness to it.

package/stacks/pieces/express.md

@@ -49,10 +49,19 @@ documentation: https://expressjs.com/
   for form posts; an `Origin` check must accept the origin built from the
   trusted forwarded host as well as the raw `Host`, because a development
   proxy may present same-origin requests with a loopback `Origin`. A host or
-  CORS allow-list must also admit loopback for the health probe.
+  CORS allow-list must also admit loopback for the health probe. helmet's
+  default `Referrer-Policy: no-referrer` makes browsers send `Origin: null` on
+  same-origin form posts, so an `Origin` check refuses every form: set
+  `referrerPolicy: { policy: 'same-origin' }` when the app checks `Origin`.
+- helmet sends `X-Frame-Options: SAMEORIGIN` and a Content-Security-Policy with
+  `frame-ancestors 'self'`, so a development tool that shows the application
+  inside a frame on another origin stays blank. Only when `NODE_ENV` is not
+  `production`, pass `frameguard: false` and
+  `contentSecurityPolicy: { directives: { frameAncestors: null } }`; production
+  keeps both.
 - Sessions use `express-session` with `secret: process.env.SESSION_SECRET`,
-  generated with `openssl rand -base64 32`, supplied through the environment,
-  never committed and never written into a generated dotenv file; refuse to
+  generated with `openssl rand -base64 32`, supplied through the environment
+  and never committed (a dotenv file holding it stays ignored); refuse to
   start in production without it. Development may fall back to a random
   per-process secret, which ends sessions on restart. Use
   `cookie: { secure: 'auto', httpOnly: true, sameSite: 'lax' }`; `'auto'`
@@ -65,8 +74,12 @@ documentation: https://expressjs.com/
   with another health path changes both.
 - Serve static files with `express.static(path.join(__dirname, 'public'))`
   or the ESM equivalent. A bundler or TypeScript build adds a Workspace setup
-  step and a Deployment Build step and serves the compiled output.
-- Express has no ORM. Select the database component and record the app's own
+  step and a Deployment Build step and serves the compiled output; build tools
+  are usually devDependencies, so Deployment then installs with plain `npm ci`,
+  builds, and may prune with `npm prune --omit=dev` before Serve.
+- Express has no ORM. Select the database component, declare its database
+  Resource in the project Stack with the environment names the app reads (no
+  Express database component declares it for you), and record the app's own
   migration tool (Prisma, Drizzle, Knex, Sequelize, TypeORM) as Workspace
   setup and Deployment Migrate steps, for example `prisma migrate deploy` or
   `knex migrate:latest`. Never run `prisma migrate dev`, `prisma db push` or
@@ -85,6 +98,11 @@ documentation: https://expressjs.com/
   role. Seed one development administrator and one ordinary user through an
   idempotent script that reads their passwords from the environment; never
   hard-code production credentials.
+- Commands that run outside the server (migrations, seeds, administrative or
+  development sign-in helpers) use the server's database and secrets from the
+  same environment variables. A command started without that environment loads
+  the ignored dotenv the host generates with `process.loadEnvFile()` rather than
+  falling back to a different database file or connection.
 
 ## Adoption
 

package/stacks/pieces/jskit.md

@@ -32,6 +32,15 @@ https://mobily-enterprises.github.io/jskit-ai/
   `AUTH_LOCAL_SESSION_SECRET` as a required environment name in the project's
   established environment contract and committed environment example. Never
   commit or invent its value.
+- An application with accounts always has the host's browser-preview login,
+  without waiting to be asked: when adding authentication, add the
+  `auth/auth-surface` pattern's executable `tools/preview-identity` and copy its
+  exact `#### Preview identity` block (Command `tools/preview-identity`,
+  Protocol `vibe64.preview-identity.command.v1`, Identity types `email`
+  `user-id`, Enabled environment `AUTH_DEV_BYPASS_ENABLED`, Secret environment
+  `AUTH_DEV_BYPASS_SECRET`, Runtimes `nodejs`) under the web `Outputs` target.
+  Which existing accounts the preview uses stays the person's choice; never
+  create users for it.
 - Before creating or modifying JSKIT Vue/Vuetify UI, read the Material 3
   contract at
   `https://mobily-enterprises.github.io/jskit-ai/guide/framework/material-3`
@@ -77,6 +86,25 @@ https://mobily-enterprises.github.io/jskit-ai/
   input fields never grant administrator access. Verify the requested provider
   outcomes and denied access with controlled fixtures. Genesis transports
   guidance and opaque declarations; it does not execute integrations or payments.
+- Shipping the app to phones ("install on my phone"): the host-owned
+  `## Packaging` section is written only when the person adds a mobile target.
+  It declares a separate `web-bundle` package whose Build produces the bundled
+  client (Output its build folder) with the absolute HTTPS API base the client
+  calls, then a `capacitor` package with `Content: package <that id>`,
+  `Platforms: android`, a permanent reverse-DNS `Id`, `Name`, a committed
+  1024x1024 PNG `Icon` without transparency, `Version from: package.json` and
+  one `Permission` line, with a plain reason, per native capability. The host
+  generates and discards the native project on every build: never commit
+  `android/`, `ios/`, `capacitor.config.*`, Gradle files, build numbers or
+  signing keys. Native plugins are ordinary client dependencies at the exact
+  versions in `package-lock.json`, and the host's shell is Capacitor 8; it
+  blocks a lockfile mismatch or another major. `@jskit-ai/mobile-capacitor` is
+  still on Capacitor 7, so propose mobile packaging for a JSKIT client only
+  once its Capacitor dependencies are 8.x. A deep-link scheme and app-link
+  domains live once in `## Environment defaults` (for example `APP_URL_SCHEME`,
+  `APP_LINK_DOMAINS`) and Packaging names them with `Deep link scheme from` and
+  `App link domains from`; the server's CORS and OAuth callbacks must accept
+  the app's origin and scheme.
 
 ## Adoption
 
@@ -96,7 +124,9 @@ https://mobily-enterprises.github.io/jskit-ai/
   component when the script or preparation file does not exist.
 - When the project declares an application-owned identity exchange for a host's
   browser preview, preserve its command, selectors, protocol, environment names,
-  runtime and timeout in the project's existing section.
+  runtime and timeout in the project's existing section. When an application
+  with JSKIT accounts lacks it, add it from the `auth/auth-surface` pattern as
+  in Guidance.
   A host-saved identity name/value is not a substitute for this application
   contract.
 - Treat generator descriptors, receipts, sync commands, legacy service

package/stacks/pieces/nextjs.md

@@ -42,12 +42,19 @@ framework documentation: https://nextjs.org/docs
   WebSocket host for the proxy.
 - Server Actions reject a POST whose `Origin` host differs from
   `X-Forwarded-Host` (or `Host` without it) with "Invalid Server Actions
-  request". When a development proxy rewrites `Origin` to the loopback address
-  while forwarding the browser host, admit exactly that loopback host in
-  `experimental.serverActions.allowedOrigins` in development only, for example
-  `` process.env.NODE_ENV === "development" && process.env.PORT ? [`127.0.0.1:${process.env.PORT}`] : [] ``
-  (ports cannot be wildcarded). The list also applies in production; never
-  admit arbitrary origins there.
+  request". A proxy that forwards both unchanged, or presents a same-origin
+  request entirely on the loopback origin (loopback `Origin` and `Host`, no
+  forwarded host), needs no setting. Add an exact host to
+  `experimental.serverActions.allowedOrigins` only for a real reported
+  mismatch, in development only (ports cannot be wildcarded); the list also
+  applies in production, so never admit arbitrary origins.
+- Redirect with relative paths. A Server Action's redirect travels in a
+  framework response header, not `Location`, so a proxy does not rewrite it,
+  and Auth.js `signIn`/`signOut` with `redirectTo` build an absolute URL from
+  the request's host headers, which a proxy may present as the loopback
+  address. Call them with `redirect: false`, then `redirect("/path")`.
+  `request.nextUrl` in `proxy`/middleware names the server's own host, so an
+  Auth.js `callbackUrl` may be a loopback URL: use only its path.
 - `NEXT_PUBLIC_*` variables are inlined into client bundles at build time:
   never put secrets in them, and their production values must exist when
   `next build` runs, not only at start. Server-only values are read from
@@ -58,6 +65,13 @@ framework documentation: https://nextjs.org/docs
   file instead) and set `AUTH_TRUST_HOST=true` when the app is served behind a
   trusted reverse proxy, so callback and redirect URLs use the forwarded
   origin. Other auth libraries need their equivalent trusted-host setting.
+- With `cacheComponents` enabled (the recent `create-next-app` default),
+  pages that read the session must render at request time: call
+  `await connection()` before `auth()`, wrap the read in `<Suspense>`, or
+  export `instant = false`; otherwise `next build` fails. Gate protected
+  routes in `proxy`/middleware (Auth.js `authorized` callback), not only with
+  `redirect()` during render: the client router can replay a cached
+  render-time redirect to the login page after sign-in.
 - Readiness and health probes must reach a public route: middleware (or
   `proxy`) that redirects `/` to a login page makes a `GET /` probe fail.
   Exclude the probe path from the auth matcher, or add a small public route
@@ -86,6 +100,20 @@ framework documentation: https://nextjs.org/docs
   for development through an idempotent seed script with credentials from the
   environment, and keep role checks on the server (Server Components, route
   handlers, Server Actions), not only in client components.
+- Shipping the app to phones ("install on my phone") needs a static client:
+  `output: "export"` (no Server Actions, route handlers, middleware or
+  request-time rendering in that build), with API calls going to an absolute
+  HTTPS base read from a `NEXT_PUBLIC_*` variable. The host-owned
+  `## Packaging` section, written only when the person adds a mobile target,
+  declares a `web-bundle` package (Build `npm` `run` `build`, Output `out`)
+  and a `capacitor` package with `Content: package <that id>`,
+  `Platforms: android`, a permanent reverse-DNS `Id`, `Name`, a committed
+  1024x1024 PNG `Icon` without transparency, `Version from: package.json` and
+  one `Permission` line per native capability. Native plugins are ordinary
+  dependencies at exact `package-lock.json` versions on Capacitor 8; the host
+  generates and discards the native project, so never commit `android/`,
+  `capacitor.config.*` or signing keys. A server-rendered app is not yet
+  supported as a phone app: it needs a separate static client first.
 
 ## Adoption
 
@@ -138,7 +166,7 @@ framework documentation: https://nextjs.org/docs
 - Ready when: `GET` `/` returns `200`
 - Prepare `Install dependencies`: `npm` `ci`
 - Build `Build`: `npm` `run` `build`
-- Serve `Start`: `npm` `start` `--` `--hostname` `127.0.0.1`
+- Serve `Start`: `sh` `-c` `exec npm start -- --hostname "$HOST"`
 
 ## Deslop
 

package/stacks/pieces/nodejs.md

@@ -41,6 +41,17 @@ Node.js package, command, module, dependency, and test conventions.
   `package.json` and `package-lock.json` stay unchanged; Verify resolves each
   package from the application root and fails unless it resolves to its
   connected source root. An ordinary `npm ci` restores the published packages.
+- Publishing a library to npm: the host-owned `## Packaging` section declares
+  the package (`npm` packer, its Workdir, `Version from: package.json`) only
+  when a publishing target is added; the host builds with `npm pack` from the
+  saved commit and owns tags, credentials and uploads. Keep `name`, `version`,
+  `license`, `files` (or `.npmignore`) and an `exports`/`main` entry correct in
+  `package.json`; never commit tarballs, tokens or `.npmrc` credentials, and
+  remove `"private": true` only for a package that is really published. A
+  build step before packing (TypeScript, bundling) is a declared Build command
+  such as `npm run build`, not a `prepublishOnly` script. A project using
+  Changesets or release-please keeps that tool and declares
+  `Version from: external`.
 - Long-running web processes accept their listen host and port from arguments
   or the environment rather than hard-coding them, and fail if the port is
   taken instead of silently choosing another. For Express or Next.js select

package/stacks/pieces/python.md

@@ -42,6 +42,21 @@ Python package, module, callable, dependency, and test conventions.
   PEP 610 `direct_url.json` is editable with the source root's `file:` URL and
   that its modules import from there. Do not use `uv sync`, which needs tracked
   `[tool.uv.sources]` and lockfile changes.
+- Publishing a library to PyPI: the host-owned `## Packaging` section declares
+  the package (`python-dist` packer, `Runtimes: python`, its `dist` Output,
+  `Version from: pyproject.toml`) only when a publishing target is added; the
+  host builds the sdist and wheel from the saved commit and owns tags,
+  credentials and uploads. The build runs in a clean copy where `build` is
+  not installed, and managed Pythons refuse a bare `pip install` (PEP 668), so
+  a plain `python3 -m build` fails. The package installs its own throwaway
+  tools: Prepare `python3 -m venv .build-tools`, Prepare
+  `.build-tools/bin/python -m pip install --quiet build`, Build
+  `.build-tools/bin/python -m build`; add `.build-tools/` to `.gitignore`. Keep a PEP 621
+  `[project]` table with a static `version`, `readme`, `license` and
+  `requires-python` so `twine check --strict` passes; versions use PEP 440
+  (`1.5.0rc1`). Never commit `dist/`, tokens or `.pypirc`. A project with a
+  dynamic version (setuptools-scm, hatch-vcs) declares
+  `Version from: external`.
 - Running a web process: bind the supplied listen host and port, trust forwarded
   headers only from a loopback proxy, and read secrets from the environment.
   For Django select `django`; its piece owns the framework traps. Flask uses

package/stacks/pieces/rails-mysql.md

@@ -39,7 +39,10 @@ Rails MySQL connection, Active Record migration, and database environment conven
       "allowEmpty": ["password"],
       "preferred": true
     }
-  ]
+  ],
+  "optionalBindings": {
+    "testDatabase": "TEST_DB_NAME"
+  }
 }
 ```
 
@@ -51,13 +54,15 @@ Rails MySQL connection, Active Record migration, and database environment conven
   `port: <%= ENV.fetch("DB_PORT", 3306) %>`,
   `username: <%= ENV["DB_USERNAME"] %>`, `password: <%= ENV["DB_PASSWORD"] %>`;
   and `database: <%= ENV["DB_DATABASE"] %>` for development and the
-  production primary. Keep `test` on its own disposable database name.
+  production primary. Point `test` at
+  `<%= ENV.fetch("TEST_DB_NAME", "<app>_test") %>`, never at the development
+  or production database.
 - Keep `encoding: utf8mb4`. `mysql2` compiles against the MySQL client
   library; `trilogy` (Rails 7.1+) is pure Ruby and avoids it. Do not switch an
   existing app's adapter without testing it.
-- `bin/rails test` purges and recreates the test database, which needs
-  `CREATE`/`DROP` privileges unless the test database is supplied and
-  disposable.
+- `bin/rails test` purges the test database whenever its schema is out of
+  date by dropping and recreating it, so the user needs `CREATE` and `DROP`
+  on that database name even when `TEST_DB_NAME` names it.
 - Rails 8 production declares separate `cache`, `queue` and `cable`
   databases. When only one database is supplied, follow the Solid Cache, Solid
   Queue and Solid Cable single-database instructions (their schemas become

package/stacks/pieces/rails-postgresql.md

@@ -39,7 +39,10 @@ Rails PostgreSQL connection, Active Record migration, and database environment c
       "allowEmpty": ["password"],
       "preferred": true
     }
-  ]
+  ],
+  "optionalBindings": {
+    "testDatabase": "TEST_DB_NAME"
+  }
 }
 ```
 
@@ -51,9 +54,18 @@ Rails PostgreSQL connection, Active Record migration, and database environment c
   `port: <%= ENV.fetch("DB_PORT", 5432) %>`,
   `username: <%= ENV["DB_USERNAME"] %>`, `password: <%= ENV["DB_PASSWORD"] %>`;
   and `database: <%= ENV["DB_DATABASE"] %>` for development and the
-  production primary. Keep `test` on its own disposable database name.
-- `bin/rails test` purges and recreates the test database, which needs the
-  `CREATEDB` privilege unless the test database is supplied and disposable.
+  production primary. Point `test` at
+  `<%= ENV.fetch("TEST_DB_NAME", "<app>_test") %>`, never at the development
+  or production database.
+- `bin/rails test` purges the test database whenever its schema is out of
+  date by dropping and recreating it, so the role needs `CREATEDB` (and must
+  own the database) even when `TEST_DB_NAME` names it.
+- After loading fixtures, Rails checks their foreign keys
+  (`verify_foreign_keys_for_fixtures`, on by default) by updating
+  `pg_catalog.pg_constraint`, which only a superuser may do. With an ordinary
+  `CREATEDB` role every fixture test fails with `permission denied for table
+  pg_constraint`; set `config.active_record.verify_foreign_keys_for_fixtures =
+  false` in `config/environments/test.rb` rather than granting superuser.
 - Rails 8 production declares separate `cache`, `queue` and `cable`
   databases. When only one database is supplied, follow the Solid Cache, Solid
   Queue and Solid Cable single-database instructions (their schemas become

package/stacks/pieces/rails.md

@@ -44,6 +44,11 @@ Authoritative framework documentation: https://guides.rubyonrails.org/
   same way: allow the observed development origin in
   `config.action_cable.allowed_request_origins` rather than disabling its
   forgery protection.
+- Rails sends `X-Frame-Options: SAMEORIGIN`, so a host that shows development
+  pages inside a frame on another origin gets a blank frame. Only in
+  `development.rb`, drop it with
+  `config.action_dispatch.default_headers.delete("X-Frame-Options")`;
+  production keeps the header.
 - Secrets: development uses `tmp/local_secret.txt`. Production needs
   `SECRET_KEY_BASE` (generate with `bin/rails secret`) or `RAILS_MASTER_KEY`
   for `config/credentials.yml.enc`, supplied through the deployment
@@ -55,13 +60,19 @@ Authoritative framework documentation: https://guides.rubyonrails.org/
   Ask for the key or move the needed values to environment variables.
 - `bin/rails db:prepare` creates the database, loads the schema and runs
   `db/seeds.rb` when it is new, and migrates it otherwise, so repeated setup is
-  safe. Seeds must be idempotent (`find_or_create_by!`). Commit generated
+  safe. It seeds only a database without a `schema_migrations` table: one that
+  already has it (a development server's pending-migration check creates it on
+  the first request) is only migrated, so setup also runs `bin/rails db:seed`.
+  Seeds must therefore be idempotent (`find_or_create_by!`) and guard
+  development-only records with `Rails.env.development?`. In development every
+  request, including `/up`, fails with a pending-migration error until
+  `db:prepare` has run against the supplied database. Commit generated
   migrations and `db/schema.rb`; never run `db:reset`, `db:setup`,
   `db:schema:load`, `db:drop` or edit an applied migration as routine setup.
 - `DATABASE_URL` overrides the connection of every environment, including
   `test`. Keep it unset where tests run, and point `test` in
-  `config/database.yml` at its own disposable database (a supplied disposable
-  test database name when the environment declares one), never at the
+  `config/database.yml` at its own disposable database (the database
+  integration's test database binding when it is supplied), never at the
   development or production database. `bin/rails test` recreates the test
   schema.
 - Mode is set per environment: `RAILS_ENV=production` belongs in the
@@ -78,9 +89,18 @@ Authoritative framework documentation: https://guides.rubyonrails.org/
   a precompiled gem. Dependency installation therefore also uses `cpp`.
   `trilogy` avoids the MySQL client library. A `Gemfile.lock` resolved only on
   another platform needs `bundle lock --add-platform x86_64-linux` (or the
-  deployment platform) before frozen deployment installs.
-- Production: `bin/rails server -e production` reads `PORT`; bind loopback
-  with `-b`. Rails 8 enables `assume_ssl`/`force_ssl`; with `force_ssl` but no
+  deployment platform) before frozen deployment installs. `rails new` also
+  adds `image_processing`, which needs the libvips library for Active Storage
+  variants: provide libvips where variants are used, or remove the gem.
+- Install gems into the project's `vendor/bundle` (the proposed Prepare sets
+  `bundle config set --local path vendor/bundle`), as deployment does: the
+  Ruby installation's own gem directory is often read-only (a system or
+  packaged Ruby), and `bundle install` then fails with
+  `Bundler::PermissionError`. Keep `/vendor/bundle` and `/.bundle` in
+  `.gitignore`.
+- Production: `bin/rails server -e production` reads `PORT` but not `HOST`;
+  pass the supplied host with `-b`, as the proposed Serve does. Rails 7.1+
+  generates `force_ssl` and Rails 8 also `assume_ssl`; with `force_ssl` but no
   `assume_ssl`, exclude `/up` from the redirect:
   `config.ssl_options = { redirect: { exclude: ->(request) { request.path == "/up" } } }`.
   Rails 8 runs Solid Queue jobs inside Puma only with `SOLID_QUEUE_IN_PUMA=1`
@@ -89,12 +109,17 @@ Authoritative framework documentation: https://guides.rubyonrails.org/
   Older apps add an equivalent route and update the Outputs and Deployment
   readiness.
 - Login: Rails 8 `bin/rails generate authentication`, Devise or the app's own
-  `has_secure_password`. Seed one administrator (an `admin` boolean or role)
+  `has_secure_password`. Controllers generated after authentication require a
+  signed-in user, so their tests sign in first (`sign_in_as(users(:one))` from
+  the generated session test helper). Seed one administrator (an `admin` boolean or role)
   and one ordinary user idempotently in `db/seeds.rb` for development only,
   with passwords from the environment; never seed production credentials.
 - The JavaScript dependency step assumes npm. A `yarn.lock` or `bun.lockb`
   means that line uses the matching tool; importmap apps have no
-  `package.json` and skip it.
+  `package.json` and skip it. The proposed Deployment assumes importmap: with
+  `jsbundling-rails`, `cssbundling-rails` or another `package.json` build, add
+  `nodejs` to its Runtimes and a Prepare `npm ci` step before
+  `assets:precompile`.
 
 ## Adoption
 
@@ -114,9 +139,11 @@ Authoritative framework documentation: https://guides.rubyonrails.org/
 
 ## Workspace setup
 
+- Prepare `Keep gems inside the project` with `ruby` when `Gemfile` exists: `bundle` `config` `set` `--local` `path` `vendor/bundle`
 - Prepare `Install Ruby dependencies` with `ruby` `cpp` when `Gemfile` exists: `bundle` `install`
 - Prepare `Install JavaScript dependencies` with `nodejs` if `package.json` exists: `npm` `install`
 - Prepare `Prepare database` with `ruby` when `bin/rails` exists: `bin/rails` `db:prepare`
+- Prepare `Seed development data` with `ruby` when `bin/rails` exists: `bin/rails` `db:seed`
 
 ## Outputs
 
@@ -148,7 +175,7 @@ Authoritative framework documentation: https://guides.rubyonrails.org/
 - Prepare `Install Ruby dependencies`: `bundle` `install`
 - Build `Precompile assets`: `bin/rails` `assets:precompile` `RAILS_ENV=production`
 - Migrate `Prepare database`: `bin/rails` `db:prepare` `RAILS_ENV=production`
-- Serve `Start`: `bin/rails` `server` `-e` `production` `-b` `127.0.0.1`
+- Serve `Start`: `sh` `-c` `exec bin/rails server -e production -b "$HOST" -p "$PORT"`
 
 ## Deslop
 

package/stacks/pieces/spring-boot.md

@@ -48,6 +48,12 @@ https://docs.spring.io/spring-boot/
   such a proxy. A proxy may present same-origin requests with an `Origin`
   rewritten to the loopback address; keep CORS configuration for genuine
   cross-origin clients rather than comparing `Origin` with the request host.
+- Spring Security answers `X-Frame-Options: DENY`, so a development tool that
+  shows the application inside a frame stays blank. When that is needed,
+  disable frame options only through a property set in the `dev` profile
+  (for example `app.allow-framing=true`, read by the security configuration
+  before `http.headers(h -> h.frameOptions(f -> f.disable()))`); production
+  keeps `DENY`.
 - Add `spring-boot-starter-actuator`, expose
   `management.endpoints.web.exposure.include=health`, and let Spring Security
   `permitAll` `/actuator/health`; the proposed readiness checks use it. Its

package/stacks/pieces/sqlite.md

@@ -21,6 +21,12 @@ SQLite file-backed persistence, migrations, and backup conventions.
   persistent database filename through the `database` resource semantic and
   the environment name the application actually reads. A driver selector such
   as `DB_CONNECTION=sqlite` is configuration, not a database filename.
+- When no framework database component declares that resource (an Express,
+  Next.js or plain Node.js app, for example), the project Stack declares it
+  under `## Resources` as one fenced `json genesis-resource` block, such as
+  `{"id": "database", "kind": "sqlite", "environmentAlternatives": [{"bindings": {"database": "DB_DATABASE"}, "preferred": true}]}`.
+  The application opens the filename in that variable; a gitignored
+  repository-relative file is only a fallback for a checkout without it.
 - Keep durable database files outside disposable build and release directories.
   A host may supply a persistent filename; do not replace that value with a
   repository-relative default or recreate an existing database during setup.