genesis-stack 1.2.1 → 1.3.1

package/stacks/pieces/nextjs.md

@@ -0,0 +1,153 @@
+# Stack piece: nextjs
+
+## Description
+
+Next.js React application conventions: App Router or Pages Router, the
+`next` CLI, Server Actions, middleware, environment variables, builds and
+production serving. A Next.js application has `next` in `package.json`
+dependencies and usually a `next.config.js`, `next.config.mjs` or
+`next.config.ts` file and an `app/` or `pages/` directory. Authoritative
+framework documentation: https://nextjs.org/docs
+
+## Requires
+
+- `nodejs`
+
+## Conflicts
+
+- `express`
+
+## Guidance
+
+- Match the installed Next.js major version and the router the application
+  already uses (`app/` App Router or `pages/` Pages Router). Recent releases
+  ship version-matched documentation in `node_modules/next/dist/docs/`; read
+  the relevant guide there before relying on remembered APIs. `next dev` may
+  write a framework-owned agent-rules block into `AGENTS.md`; commit it rather
+  than repeatedly removing it.
+- Bind the development server to the host and port it is given:
+  `next dev --hostname <host> --port <port>` (the proposed Run passes them
+  through `npm run dev --`). Without `--hostname`, `next dev` and `next start`
+  listen on every interface. Never hard-code a port in `package.json` scripts.
+- Behind a development reverse proxy on loopback that rewrites `Host` and sends
+  `X-Forwarded-Host`, `X-Forwarded-Proto` and `X-Forwarded-Port`, Next.js
+  builds request URLs from the forwarded headers. The development server blocks
+  requests for its own development resources (the `/_next/hmr` WebSocket and
+  other `/_next/*` dev endpoints) whose `Origin` hostname is not `localhost`,
+  the hostname it was started with, or an `allowedDevOrigins` entry. A proxy
+  that rewrites the browser's `Origin` to the loopback address needs no entry;
+  otherwise add the browser-facing hostname pattern to `allowedDevOrigins`,
+  read from an environment variable rather than hard-coded. The HMR client
+  connects through the page's own origin; do not hard-code an asset prefix or
+  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.
+- `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
+  `process.env` at request time. Next.js reads `.env*` files but the
+  environment wins; keep real values out of committed `.env*` files.
+- With Auth.js (`next-auth` v5), supply `AUTH_SECRET` through the environment
+  (generate with `openssl rand -base64 33`; `npx auth secret` writes it into a
+  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.
+- 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
+  handler (for example `app/health/route.ts`) and point the Outputs and
+  Deployment readiness checks at it.
+- Database access goes through the application's ORM (Prisma, Drizzle, Kysely
+  or another). Its schema migrations are application-owned: deployment runs the
+  non-interactive apply command (for example `prisma migrate deploy`), never
+  `prisma migrate dev` or `prisma db push` against supplied data. Seed scripts
+  must be idempotent. Tests use a disposable database supplied for them, never
+  the development or production database. Declare the database Resources in
+  the project Stack; this piece does not choose a database.
+- Production: `next build` then `next start`. `next start` reads `PORT` but not
+  `HOST`; bind it explicitly (`next start --hostname <host>`), as the proposed
+  Serve does. Set `NODE_ENV=production` only through the production
+  environment, never as a project-wide default; `next build` and `next start`
+  set it themselves. `output: "standalone"` changes the start command to
+  `node .next/standalone/server.js` (which reads `HOSTNAME` and `PORT`) and
+  requires copying `public/` and `.next/static/`; update Deployment if the
+  application uses it. `output: "export"` produces static files with no server.
+- Do not run `next build` into the same `.next` directory a running `next dev`
+  uses unless the installed major isolates development output (Next.js 16 and
+  later write development output to `.next/dev`); with older majors stop the
+  development server first or build into a separate `distDir`.
+- When the application has login, seed one administrator and one ordinary user
+  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.
+
+## Adoption
+
+- Inventory the real files before changing project contracts: the installed
+  `next` version in the lockfile, `app/` or `pages/`, `next.config.*` (`output`,
+  `basePath`, `distDir`, `experimental`), `middleware.*`/`proxy.*`, the auth
+  library and its environment names, the ORM and its migration commands, and
+  the real `dev`, `build`, `start`, `lint` and `test` scripts.
+- Identify the package manager from the lockfile and replace every proposed
+  `npm` line when the project uses pnpm, Yarn or Bun. Next.js 16 removed
+  `next lint`; if the `lint` script is missing, remove that Verification line
+  instead of inventing one, and add the project's real test command when it
+  has one.
+- Replace the readiness path when `/` is not publicly reachable, a `basePath`
+  is set, or a dedicated health route exists. Replace the Serve line for
+  `output: "standalone"`, a custom server, or `output: "export"`.
+- A custom Next.js server built on Express is a project-owned decision: keep
+  this piece and describe that server's real commands in the project's own
+  sections.
+
+## Workspace setup
+
+- Prepare `Install dependencies` with `nodejs` when `package.json` exists: `npm` `install`
+
+## Outputs
+
+### Target `app`: Run Next.js app
+
+- Default.
+- Mode: `interactive`
+- Runtimes: `nodejs`
+- Run `Develop`: `npm` `run` `dev` `--` `--hostname` `{host}` `--port` `{port}`
+
+#### Presentation
+
+- Kind: `web`
+- Preferred port: `3000`
+- URL path: `/`
+- Ready when: `GET` `/` returns `200`
+
+## Verification
+
+- Verify `lint`: `npm` `run` `lint`
+- Verify `build`: `npm` `run` `build`
+
+## Deployment
+
+- Runtimes: `nodejs`
+- Recreate on restore: `node_modules` `.next/cache`
+- Ready when: `GET` `/` returns `200`
+- Prepare `Install dependencies`: `npm` `ci`
+- Build `Build`: `npm` `run` `build`
+- Serve `Start`: `npm` `start` `--` `--hostname` `127.0.0.1`
+
+## Deslop
+
+- Keep data fetching in Server Components, route handlers and Server Actions
+  where the router supports it; remove client-side fetch wrappers that only
+  duplicate a server read.
+- Keep `"use client"` boundaries as low in the tree as possible and do not mark
+  whole layouts as client components to reach one interactive widget.
+- Use the framework's `Link`, `Image`, `Script`, metadata and font facilities
+  instead of hand-written equivalents.
+- Remove abandoned starter content, unused route segments and duplicate
+  environment readers only when routes, redirects and tests stay unchanged.

package/stacks/pieces/nodejs.md

@@ -43,7 +43,8 @@ Node.js package, command, module, dependency, and test conventions.
   connected source root. An ordinary `npm ci` restores the published packages.
 - 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.
+  taken instead of silently choosing another. For Express or Next.js select
+  `express` or `nextjs`; that piece owns the framework traps.
 
 ## Adoption
 

package/stacks/pieces/python.md

@@ -44,11 +44,9 @@ Python package, module, callable, dependency, and test conventions.
   `[tool.uv.sources]` and lockfile changes.
 - 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.
-  Django: set `ALLOWED_HOSTS` and `CSRF_TRUSTED_ORIGINS` for the served origin
-  (`ALLOWED_HOSTS` also lists the loopback host the proxy connects to),
-  `SECURE_PROXY_SSL_HEADER` and `USE_X_FORWARDED_HOST` only behind that trusted
-  proxy, and read `SECRET_KEY` from the environment. Flask uses Werkzeug's
-  `ProxyFix`; Uvicorn uses `--proxy-headers --forwarded-allow-ips 127.0.0.1`.
+  For Django select `django`; its piece owns the framework traps. Flask uses
+  Werkzeug's `ProxyFix`; Uvicorn uses `--proxy-headers --forwarded-allow-ips
+  127.0.0.1`.
 
 ## Connected development
 

package/stacks/pieces/rails-mysql.md

@@ -0,0 +1,76 @@
+# Stack piece: rails-mysql
+
+## Description
+
+Rails MySQL connection, Active Record migration, and database environment conventions.
+
+## Requires
+
+- `rails`
+- `mysql`
+
+## Conflicts
+
+- `rails-postgresql`
+- `rails-sqlite`
+
+## Environment defaults
+
+- Default `DB_HOST`: `127.0.0.1`
+- Default `DB_PORT`: `3306`
+- Default `DB_DATABASE`: `rails`
+- Default `DB_USERNAME`: `root`
+
+## Resources
+
+```json genesis-resource
+{
+  "id": "database",
+  "kind": "mysql",
+  "environmentAlternatives": [
+    {
+      "bindings": {
+        "database": "DB_DATABASE",
+        "host": "DB_HOST",
+        "password": "DB_PASSWORD",
+        "port": "DB_PORT",
+        "username": "DB_USERNAME"
+      },
+      "allowEmpty": ["password"],
+      "preferred": true
+    }
+  ]
+}
+```
+
+## Guidance
+
+- `rails new -d mysql` (adapter `mysql2`) or `-d trilogy` hard-codes database
+  names. Make `config/database.yml` read the resource names: under `default`,
+  `host: <%= ENV.fetch("DB_HOST", "127.0.0.1") %>`,
+  `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.
+- 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.
+- 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
+  ordinary migrations and their `connects_to` settings are removed) instead of
+  inventing extra database names.
+- Use the inherited Rails migration and seed guidance. Keep connection,
+  integration and payment records in this database through Active Record
+  migrations and transactions; test uniqueness and concurrent updates on MySQL
+  itself.
+
+## Adoption
+
+- Confirm the adapter, every environment's database, username, password, host
+  and port expressions in `config/database.yml`, and whether `DATABASE_URL` is
+  read, before declaring readiness or connecting. Align the project Resource
+  bindings with the names the file actually reads.

package/stacks/pieces/rails-postgresql.md

@@ -0,0 +1,74 @@
+# Stack piece: rails-postgresql
+
+## Description
+
+Rails PostgreSQL connection, Active Record migration, and database environment conventions.
+
+## Requires
+
+- `rails`
+- `postgresql`
+
+## Conflicts
+
+- `rails-mysql`
+- `rails-sqlite`
+
+## Environment defaults
+
+- Default `DB_HOST`: `127.0.0.1`
+- Default `DB_PORT`: `5432`
+- Default `DB_DATABASE`: `rails`
+- Default `DB_USERNAME`: `postgres`
+
+## Resources
+
+```json genesis-resource
+{
+  "id": "database",
+  "kind": "postgresql",
+  "environmentAlternatives": [
+    {
+      "bindings": {
+        "database": "DB_DATABASE",
+        "host": "DB_HOST",
+        "password": "DB_PASSWORD",
+        "port": "DB_PORT",
+        "username": "DB_USERNAME"
+      },
+      "allowEmpty": ["password"],
+      "preferred": true
+    }
+  ]
+}
+```
+
+## Guidance
+
+- `rails new -d postgresql` hard-codes database names and reads only a
+  production password variable. Make `config/database.yml` read the resource
+  names: under `default`, `host: <%= ENV.fetch("DB_HOST", "127.0.0.1") %>`,
+  `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.
+- 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
+  ordinary migrations and their `connects_to` settings are removed) instead of
+  inventing extra database names.
+- The `pg` gem compiles against libpq unless the locked version ships a
+  precompiled gem for the platform.
+- Use the inherited Rails migration and seed guidance. Keep connection,
+  integration and payment records in this database through Active Record
+  migrations and transactions; test uniqueness and concurrent updates on
+  PostgreSQL itself.
+
+## Adoption
+
+- Confirm the adapter, every environment's database, username, password, host
+  and port expressions in `config/database.yml`, and whether `DATABASE_URL` is
+  read, before declaring readiness or connecting. Align the project Resource
+  bindings with the names the file actually reads.

package/stacks/pieces/rails-sqlite.md

@@ -0,0 +1,60 @@
+# Stack piece: rails-sqlite
+
+## Description
+
+Rails SQLite connection, Active Record migration, and database filename conventions.
+
+## Requires
+
+- `rails`
+- `sqlite`
+
+## Conflicts
+
+- `rails-mysql`
+- `rails-postgresql`
+
+## Resources
+
+```json genesis-resource
+{
+  "id": "database",
+  "kind": "sqlite",
+  "environmentAlternatives": [
+    {
+      "bindings": {
+        "database": "DB_DATABASE"
+      },
+      "preferred": true
+    }
+  ]
+}
+```
+
+## Guidance
+
+- `rails new` (SQLite is the default) writes repository-relative files under
+  `storage/`, and Rails 8.1 leaves the production files unset. Make the
+  development and production primary read the supplied filename with the
+  generated name as fallback, for example
+  `database: <%= ENV.fetch("DB_DATABASE", "storage/development.sqlite3") %>`.
+  A bare `ENV.fetch("DB_DATABASE")` raises while `database.yml` loads and
+  breaks generators and asset builds that run without the variable. Keep `test`
+  on its own file such as `storage/test.sqlite3`.
+- Rails 8 production also declares `cache`, `queue` and `cable` SQLite
+  databases. Keep them next to the primary file, for example
+  `<%= File.join(File.dirname(ENV.fetch("DB_DATABASE", "storage/production.sqlite3")), "production_cache.sqlite3") %>`,
+  so they persist with it; never leave them in a disposable release directory.
+- Do not replace a supplied filename with a repository-relative default or
+  delete an existing file. `bin/rails db:prepare` creates a missing file and
+  its schema and migrates an existing one.
+- The `sqlite3` gem normally installs a precompiled native gem; a source build
+  needs the SQLite headers. Use the inherited Rails migration and seed
+  guidance and test concurrent writes on SQLite itself.
+
+## Adoption
+
+- Read `config/database.yml` for every environment's filename, including the
+  Rails 8 cache, queue and cable files, and preserve existing data: snapshot
+  it before moving to a supplied filename. Do not switch an existing app to an
+  empty database.

package/stacks/pieces/rails.md

@@ -0,0 +1,161 @@
+# 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.
+- 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. Seeds must be idempotent (`find_or_create_by!`). 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
+  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.
+- Production: `bin/rails server -e production` reads `PORT`; bind loopback
+  with `-b`. Rails 8 enables `assume_ssl`/`force_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`. 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.
+
+## 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 `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`
+
+## 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`: `bin/rails` `server` `-e` `production` `-b` `127.0.0.1`
+
+## 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.