genesis-stack 1.3.0 → 1.4.0

package/stacks/pieces/rails.md

@@ -0,0 +1,188 @@
+# Stack piece: rails
+
+## Description
+
+Ruby on Rails application, Bundler, Active Record, Action Pack, assets, and
+framework lifecycle conventions. Identified by `Gemfile.lock` listing `rails`,
+`bin/rails`, `config/application.rb`, and `config/database.yml`.
+Authoritative framework documentation: https://guides.rubyonrails.org/
+
+## Requires
+
+- `ruby`
+
+## Guidance
+
+- Use the Rails version locked in `Gemfile.lock` and its matching guides and
+  API documentation. Preserve Rails conventions (MVC, Active Record, concerns,
+  jobs, mailers, generators, `bin/rails` tasks) instead of adding parallel
+  framework plumbing.
+- The development server binds the supplied host and port:
+  `bin/rails server -b <host> -p <port>`. Without `-p` Rails reads `PORT`;
+  it never reads `HOST` (only `BINDING`, and production defaults to
+  `0.0.0.0`), so pass `-b` explicitly. A server reachable only on loopback
+  is what makes trusting proxy headers safe.
+- Behind a loopback development reverse proxy that rewrites `Host` and sends
+  `X-Forwarded-Host`, `X-Forwarded-Proto` and `X-Forwarded-Port`, Rails derives
+  `request.host`, `request.base_url` and generated URLs from those headers
+  natively (loopback is a trusted proxy by default). Do not hard-code
+  `default_url_options` hosts for development.
+- Host authorization then sees the browser-facing host and answers "Blocked
+  hosts". In development, list that host (or `.parent.domain`) in
+  `RAILS_DEVELOPMENT_HOSTS`, or, when the server binds only loopback, add
+  `config.hosts.clear` to `config/environments/development.rb` only. In
+  production set `config.hosts` explicitly from the environment and exclude the
+  health route:
+  `config.host_authorization = { exclude: ->(request) { request.path == "/up" } }`.
+- CSRF compares the `Origin` header with `request.base_url`. Some development
+  proxies rewrite a same-origin `Origin` to the upstream loopback address while
+  forwarding the browser host; form posts then fail with "HTTP Origin header
+  ... didn't match request.base_url". Only in that case, and only in
+  `development.rb`, set
+  `config.action_controller.forgery_protection_origin_check = false`; the
+  authenticity token still protects forms. Action Cable compares origins the
+  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
+  environment, never committed. `assets:precompile` in production also aborts
+  without it; a build that must not see the real secret can use
+  `SECRET_KEY_BASE_DUMMY=1`. When an
+  imported app lacks `config/master.key`, never run `bin/rails credentials:edit`
+  or delete the encrypted file to "fix" it: that destroys the existing values.
+  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. 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 (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
+  production environment and its commands, never in a project-wide default.
+- Assets: never commit `public/assets`; a stale local `public/assets` shadows
+  development changes. Propshaft/Sprockets serve sources in development;
+  `tailwindcss-rails`, `cssbundling-rails` and `jsbundling-rails` need their
+  build or watcher (`bin/dev` runs them from `Procfile.dev`). When the Develop
+  command becomes `bin/dev`, confirm its web process still binds loopback and
+  the supplied `PORT`. Rails before 7.1 needs `RAILS_SERVE_STATIC_FILES=1` in
+  production without a front web server.
+- Native gems need a C toolchain and headers: `psych` needs libyaml, `pg`
+  needs libpq, `mysql2` needs the MySQL client library, `sqlite3` usually ships
+  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. `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`
+  in the production environment; otherwise run `bin/jobs` as its own process.
+- Keep the `/up` health route (`rails/health#show`, Rails 7.1+) unauthenticated.
+  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`. 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. 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
+
+- Read `Gemfile`, `Gemfile.lock` (Rails and Ruby versions, database adapter
+  gem, asset and JavaScript tooling), `config/database.yml`,
+  `config/environments/*.rb`, `config/puma.rb`, `Procfile.dev`/`bin/dev`,
+  `config/routes.rb` (health route) and whether `config/master.key` or
+  `config/credentials/*.key` exist before changing project contracts.
+- Replace each proposed setup, Outputs, Verification and Deployment line that
+  does not match the app: RSpec apps verify with `bundle` `exec` `rspec`;
+  API-only apps have no `assets:precompile`; a different health route changes
+  both readiness lines; a different JavaScript package manager changes the
+  install step.
+- Select the matching database integration (`rails-postgresql`,
+  `rails-mysql` or `rails-sqlite`) and align `config/database.yml` with its
+  environment names. Preserve existing data and the credentials file.
+
+## 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
+
+### Target `app`: Run Rails app
+
+- Default.
+- Mode: `interactive`
+- Runtimes: `ruby`
+- Run `Develop`: `bin/rails` `server` `-b` `{host}` `-p` `{port}`
+
+#### Presentation
+
+- Kind: `web`
+- Preferred port: `3000`
+- URL path: `/`
+- Ready when: `GET` `/up` returns `200`
+
+## Verification
+
+- Verify `application`: `bin/rails` `test`
+
+## Deployment
+
+- Runtimes: `ruby` `cpp`
+- Recreate on restore: `vendor/bundle` `node_modules` `tmp` `log`
+- Ready when: `GET` `/up` returns `200`
+- Prepare `Use deployment bundle`: `bundle` `config` `set` `--local` `deployment` `true`
+- Prepare `Exclude development gems`: `bundle` `config` `set` `--local` `without` `development test`
+- 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`: `sh` `-c` `exec bin/rails server -e production -b "$HOST" -p "$PORT"`
+
+## Deslop
+
+- Preserve Rails conventions: models, concerns, controllers, callbacks,
+  validations, strong parameters, jobs, mailers and routes stay where Rails
+  expects them.
+- Remove service objects, decorators or wrappers that only forward to Active
+  Record or Action Pack without protecting a real application seam.
+- Preserve migration history, `db/schema.rb`, credentials and seed
+  idempotence; cleanup is not permission for destructive schema changes.

package/stacks/pieces/ruby.md

@@ -45,10 +45,7 @@ Ruby module, class, callable, dependency, lifecycle, and test conventions.
   only git sources. Verify that each spec loads from its source root.
 - 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.
-  Rails: allow the served host and the proxy's loopback host in `config.hosts`
-  (Rails honours `X-Forwarded-Host`), read `SECRET_KEY_BASE` from the
-  environment (generate it with `bin/rails secret`), and use
-  `bin/rails db:prepare` for setup.
+  For Rails select `rails`; its piece owns the framework traps.
 
 ## Connected development
 

package/stacks/pieces/spring-boot-mysql.md

@@ -0,0 +1,74 @@
+# Stack piece: spring-boot-mysql
+
+## Description
+
+Spring Boot MySQL or MariaDB datasource, JDBC driver, Flyway, JPA, and database
+environment conventions.
+
+## Requires
+
+- `spring-boot`
+- `mysql`
+
+## Conflicts
+
+- `spring-boot-postgresql`
+
+## Environment defaults
+
+- Default `DB_HOST`: `127.0.0.1`
+- Default `DB_PORT`: `3306`
+- Default `DB_NAME`: `spring`
+- Default `DB_USERNAME`: `root`
+
+## Resources
+
+```json genesis-resource
+{
+  "id": "database",
+  "kind": "mysql",
+  "environmentAlternatives": [
+    {
+      "bindings": {
+        "database": "DB_NAME",
+        "host": "DB_HOST",
+        "password": "DB_PASSWORD",
+        "port": "DB_PORT",
+        "username": "DB_USERNAME"
+      },
+      "allowEmpty": ["password"],
+      "preferred": true
+    }
+  ],
+  "optionalBindings": {
+    "testDatabase": "TEST_DB_NAME"
+  }
+}
+```
+
+## Guidance
+
+- Compose the JDBC URL from the individual names in `application.properties`:
+  `spring.datasource.url=jdbc:mysql://${DB_HOST}:${DB_PORT}/${DB_NAME}`,
+  `spring.datasource.username=${DB_USERNAME}` and
+  `spring.datasource.password=${DB_PASSWORD:}`. A `mysql://` connection URL is
+  not a JDBC URL; do not feed one to `spring.datasource.url`.
+- Match the driver to the server: check `SELECT VERSION()`. MySQL uses the
+  `com.mysql:mysql-connector-j` runtime driver. A MariaDB server needs
+  `org.mariadb.jdbc:mariadb-java-client` with a `jdbc:mariadb://` URL;
+  `mysql-connector-j` can fail against current MariaDB while Hibernate reads
+  connection metadata ("Unable to determine Dialect"). Flyway 10 and later
+  also need `org.flywaydb:flyway-mysql`, which covers both servers.
+- Create databases with `utf8mb4`.
+- When `TEST_DB_NAME` is supplied, the `test` profile's
+  `src/test/resources/application-test.properties` sets
+  `spring.datasource.url` to the same JDBC URL with `${TEST_DB_NAME}` in place
+  of `${DB_NAME}`. Flyway migrates that existing database; the database user
+  may lack permission to create databases. Never point tests at `DB_NAME`.
+
+## Adoption
+
+- Confirm the server (MySQL or MariaDB), the datasource properties, the
+  environment names they read, the driver and Flyway or Liquibase modules, and
+  every profile's overrides from source before declaring readiness or
+  connecting to the database.

package/stacks/pieces/spring-boot-postgresql.md

@@ -0,0 +1,68 @@
+# Stack piece: spring-boot-postgresql
+
+## Description
+
+Spring Boot PostgreSQL datasource, JDBC driver, Flyway, JPA, and database
+environment conventions.
+
+## Requires
+
+- `spring-boot`
+- `postgresql`
+
+## Conflicts
+
+- `spring-boot-mysql`
+
+## Environment defaults
+
+- Default `DB_HOST`: `127.0.0.1`
+- Default `DB_PORT`: `5432`
+- Default `DB_NAME`: `spring`
+- Default `DB_USERNAME`: `postgres`
+
+## Resources
+
+```json genesis-resource
+{
+  "id": "database",
+  "kind": "postgresql",
+  "environmentAlternatives": [
+    {
+      "bindings": {
+        "database": "DB_NAME",
+        "host": "DB_HOST",
+        "password": "DB_PASSWORD",
+        "port": "DB_PORT",
+        "username": "DB_USERNAME"
+      },
+      "allowEmpty": ["password"],
+      "preferred": true
+    }
+  ],
+  "optionalBindings": {
+    "testDatabase": "TEST_DB_NAME"
+  }
+}
+```
+
+## Guidance
+
+- Compose the JDBC URL from the individual names in `application.properties`:
+  `spring.datasource.url=jdbc:postgresql://${DB_HOST}:${DB_PORT}/${DB_NAME}`,
+  `spring.datasource.username=${DB_USERNAME}` and
+  `spring.datasource.password=${DB_PASSWORD:}`. A `postgres://` connection URL
+  is not a JDBC URL; do not feed one to `spring.datasource.url`.
+- Use the `org.postgresql:postgresql` runtime driver. Flyway 10 and later also
+  need `org.flywaydb:flyway-database-postgresql` next to the Flyway starter.
+- When `TEST_DB_NAME` is supplied, the `test` profile's
+  `src/test/resources/application-test.properties` sets
+  `spring.datasource.url` to the same JDBC URL with `${TEST_DB_NAME}` in place
+  of `${DB_NAME}`. Flyway migrates that existing database; the database role
+  may lack permission to create databases. Never point tests at `DB_NAME`.
+
+## Adoption
+
+- Confirm the datasource properties, the environment names they read, the
+  driver and Flyway or Liquibase modules, and every profile's overrides from
+  source before declaring readiness or connecting to the database.

package/stacks/pieces/spring-boot.md

@@ -0,0 +1,154 @@
+# Stack piece: spring-boot
+
+## Description
+
+Spring Boot web application, Spring MVC, Spring Security, Actuator, profiles,
+Maven or Gradle wrapper, and schema-migration conventions. Identified by a
+`pom.xml` or `build.gradle(.kts)` using the Spring Boot parent or plugin and an
+`@SpringBootApplication` class. Authoritative framework documentation:
+https://docs.spring.io/spring-boot/
+
+## Requires
+
+- `java`
+
+## Guidance
+
+- Use the Spring Boot version selected by the build and follow its matching
+  official documentation. Boot 4 splits auto-configuration into per-technology
+  starters (`spring-boot-starter-webmvc`, `spring-boot-starter-flyway`, ...):
+  a bare `flyway-core` dependency no longer runs migrations, so add the
+  matching starter instead of hand-written configuration. Preserve Spring's
+  dependency injection, configuration properties, Spring Data repositories,
+  Spring Security and Actuator instead of adding parallel plumbing.
+- Building and running need a full JDK (`javac`), not only a Java runtime.
+  Keep the Maven wrapper (`mvnw`, `.mvn/wrapper`) committed and executable;
+  the proposed operations call `./mvnw`.
+- Bind the listen address and port from the environment in
+  `application.properties`: `server.address=${HOST:127.0.0.1}` and
+  `server.port=${PORT:8080}`. Spring reads `SERVER_PORT`, not `PORT`, by
+  itself. The proposed development run also passes both as
+  `--server.address`/`--server.port` application arguments.
+- Behind a development or production reverse proxy on the same machine that
+  rewrites `Host` and sends `X-Forwarded-Host`, `X-Forwarded-Proto` and
+  `X-Forwarded-Port`, set `server.forward-headers-strategy=native`,
+  `server.tomcat.remoteip.host-header=X-Forwarded-Host` and
+  `server.tomcat.remoteip.port-header=X-Forwarded-Port`. Embedded Tomcat then
+  trusts those headers only from loopback and private internal proxies, so
+  login redirects, `ServletUriComponentsBuilder` URLs and the `Secure` session
+  cookie use the browser-facing origin. Without it, Spring Security redirects
+  to the loopback address. Use `framework` only for a non-Tomcat server, and
+  only while the server is reachable solely through that proxy.
+- Also set `server.tomcat.use-relative-redirects=true`. A proxy may send a
+  same-origin form post with the forwarded host and port removed and `Origin`
+  rewritten to the loopback address, so Tomcat would turn the redirect after
+  login or after any POST into `https://127.0.0.1/...`; a relative `Location`
+  lets the browser resolve it against its own origin.
+- Spring Security's CSRF protection is token based (`_csrf`) and works behind
+  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
+  status includes the datasource, so readiness also proves the database
+  connection. An application that must not expose Actuator replaces both
+  readiness lines with another unauthenticated route.
+- Select profiles with `SPRING_PROFILES_ACTIVE` set separately in each
+  environment (for example `dev` locally); never make a development profile
+  the project-wide default, because defaults also reach deployment. Keep
+  profile-specific values in `application-<profile>.properties`.
+- Read credentials from the environment through property placeholders; never
+  commit passwords or tokens in `application*.properties`. Spring Boot has no
+  framework secret key of its own; application secrets, such as a token
+  signing key, are generated with `openssl rand -base64 32` and supplied
+  through the environment.
+- Flyway or Liquibase owns the schema and runs at application startup, so the
+  proposed deployment has no separate migration step. Add new migrations;
+  never edit an applied one (its checksum is validated). Use
+  `spring.jpa.hibernate.ddl-auto=validate` and never `create`, `create-drop`
+  or `update` against supplied data; set `spring.jpa.open-in-view=false`.
+  Seeds are idempotent: repeatable migrations or a startup runner that checks
+  before inserting.
+- Keep tests off development data: a `test` profile
+  (`src/test/resources/application-test.properties`, activated with
+  `@ActiveProfiles("test")` or Surefire's `spring.profiles.active`) points the
+  datasource at a disposable test database supplied by the environment
+  (`TEST_DB_NAME` with the database integrations below). Do not
+  add `src/test/resources/application.properties`, which replaces the main file
+  on the test classpath. Testcontainers needs a container runtime the
+  environment may not provide.
+- Deployment serves the executable jar. Set `<finalName>app</finalName>` in the
+  Maven `<build>` so the proposed Serve step finds `target/app.jar`; the jar
+  reads `HOST` and `PORT` through the properties above.
+- When the app has login, use Spring Security users with `ADMIN` and `USER`
+  roles and a delegating `PasswordEncoder`. Seed one administrator and one
+  ordinary user for development from a `dev`-profile runner or seed migration
+  that reads the password from the environment and creates each user only
+  when absent. Never use `{noop}` passwords or seeded credentials outside
+  development.
+- A Gradle project replaces the proposals with the wrapper equivalents:
+  `./gradlew` `bootRun` `--args=--server.address={host} --server.port={port}`,
+  `./gradlew` `test`, and `./gradlew` `bootJar` with
+  `bootJar { archiveFileName = 'app.jar' }` serving `build/libs/app.jar`.
+
+## Adoption
+
+- Inspect `pom.xml` or `build.gradle(.kts)`, the wrapper, the Spring Boot and
+  Java versions, `application.properties`/`application.yml` and every profile
+  file, the security configuration, the embedded server, the packaging (`jar`
+  or `war`) and the migration tool before changing project contracts. Preserve
+  the build tool and Boot major version.
+- Replace any proposed setup, run, readiness, verification or deployment line
+  that does not match the application before claiming readiness, including
+  the jar name, the health route and the address/port properties.
+- When the app uses PostgreSQL or MySQL, select the matching Spring Boot
+  database integration so its datasource environment names become explicit.
+
+## Workspace setup
+
+- Prepare `Compile application` with `java` when `pom.xml` exists: `./mvnw` `-B` `-DskipTests` `compile`
+
+## Outputs
+
+### Target `app`: Run Spring Boot app
+
+- Default.
+- Mode: `interactive`
+- Runtimes: `java`
+- Run `Develop`: `./mvnw` `-B` `spring-boot:run` `-Dspring-boot.run.arguments=--server.address={host} --server.port={port}`
+
+#### Presentation
+
+- Kind: `web`
+- Preferred port: `8080`
+- URL path: `/`
+- Ready when: `GET` `/actuator/health` returns `200`
+
+## Verification
+
+- Verify `application`: `./mvnw` `-B` `test`
+
+## Deployment
+
+- Runtimes: `java`
+- Ready when: `GET` `/actuator/health` returns `200`
+- Build `Package`: `./mvnw` `-B` `-DskipTests` `package`
+- Serve `Start`: `java` `-jar` `target/app.jar`
+
+## Deslop
+
+- Preserve Spring's constructor injection, configuration properties,
+  component boundaries, Spring Data repositories, transaction boundaries and
+  security configuration.
+- Keep `@Transactional` at service boundaries and validation at controller or
+  configuration-properties boundaries. Remove service, mapper or DTO layers only
+  when they duplicate framework behavior without protecting a real seam.
+- Preserve migration history and entity mappings; cleanup is not permission to
+  edit applied migrations or loosen `ddl-auto`.

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.