docs/development/non-container.md

@@ -15,9 +15,9 @@ The workspace is a pnpm monorepo with three package groups:
 
 | Group | Path | Purpose |
 | --- | --- | --- |
-| `apps/` | `apps/server` (`@personal-blog/server`) | Public server application. Serves the application health endpoint (E00-S02-T03) gated on the startup migration run (E00-S03-T06); the Fastify 5 application shell lands in a later story. |
+| `apps/` | `apps/server` (`@personal-blog/server`) | Public server application. Serves the application health endpoint (E00-S02-T03) gated on the startup migration run (E00-S03-T06), and fails fast at startup with a field-specific error when a required setting is missing (E00-S04-T02); the Fastify 5 application shell lands in a later story. |
 | `packages/` | `packages/core` (`@personal-blog/core`) | Application core (site identity, content primitives). Bootstrap placeholder. |
-| `packages/` | `packages/config` (`@personal-blog/config`) | Configuration service. Owns the TypeBox/Ajv configuration schema for the validated config fields (E00-S04-T01); the environment adapter (E00-S04-T04), field-specific startup errors (E00-S04-T02) and secret redaction (E00-S04-T03) land in later tasks. |
+| `packages/` | `packages/config` (`@personal-blog/config`) | Configuration service. Owns the TypeBox/Ajv configuration schema for the validated config fields (E00-S04-T01) and the field-specific startup error for a missing required setting (E00-S04-T02); the environment adapter (E00-S04-T04) and secret redaction (E00-S04-T03) land in later tasks. |
 | `packages/` | `packages/database-postgres` (`@personal-blog/database-postgres`) | PostgreSQL database adapter package. Single owner of the `pg`/Kysely driver imports (E00-S03-T02); the migration ledger (`schema_migrations`, E00-S03-T03), the migration advisory lock (E00-S03-T04) and the migration runner with its failure diagnostic (E00-S03-T05) are implemented here. The server depends on this package to run the startup migrations behind its readiness gate (E00-S03-T06). |
 | `extensions/` | `extensions/example` (`@personal-blog/example-extension`) | Example extension exercising the `extensions/` group. Bootstrap placeholder. |
 
@@ -85,15 +85,23 @@ Expected result: `apps/server/dist/`, `packages/core/dist/`,
 
 ```sh
 # Run the compiled public server entrypoint
-pnpm --filter @personal-blog/server start
+EPPP_SESSION_SECRET='change-me-0123456789abcdefghijklmnopqrstuvwxyz' pnpm --filter @personal-blog/server start
 ```
 
 This runs the `start` script of `apps/server` (`node dist/index.js`), i.e. the
-compiled application entrypoint. Two things to know:
+compiled application entrypoint. Three things to know:
 
 1. The command **must follow `pnpm build`** — the `start` script executes the
    compiled artifact in `dist/`, it does not compile first.
-2. Since [E00-S02-T03], `apps/server` serves the **application health
+2. Since [E00-S04-T02] the server validates its **required settings at
+   startup**: the admin-session secret `EPPP_SESSION_SECRET` (the config
+   schema's required field, ≥ 32 characters, Security-and-Operations §32/§26)
+   must be set in the environment — if it is missing, the process fails fast
+   with a field-specific startup error (`missing required setting:
+   sessionSecret`) that names the missing field instead of booting. Provide it
+   in your shell or a local `.env` file (the `.env.example` template lands in
+   E00-S04).
+3. Since [E00-S02-T03], `apps/server` serves the **application health
    endpoint**: starting it opens an HTTP server on port 3000 answering
    `GET /health`, so the process stays up. Since [E00-S03-T06] the endpoint
    is the **readiness probe**: when a `DATABASE_URL` is configured, the app
@@ -131,7 +139,7 @@ pnpm install --frozen-lockfile   # exit 0, lockfile untouched
 pnpm build                       # 5/5 packages emit dist/, exit 0
 pnpm typecheck                   # 5/5 packages pass --noEmit, exit 0
 pnpm test                        # 10/10 pass, exit 0
-pnpm --filter @personal-blog/server start   # serves GET /health on port 3000, stays up
+pnpm --filter @personal-blog/server start   # requires EPPP_SESSION_SECRET (see [Run](#run)); serves GET /health on port 3000, stays up
 ```
 
 ## Troubleshooting
@@ -142,6 +150,7 @@ pnpm --filter @personal-blog/server start   # serves GET /health on port 3000, s
 | `ERR_PNPM_OUTDATED_LOCKFILE` | `pnpm-lock.yaml` is out of date with the manifests. Run `pnpm install` (unfrozen) and commit the lockfile update. |
 | `ERR_PNPM_UNSUPPORTED_ENGINE` on install | Your Node version is outside the supported 24.x engine line (`engines.node` in the root `package.json`, enforced by `engineStrict: true` in `pnpm-workspace.yaml`). Install Node 24.x (e.g. via `nvm`, `fnm` or another version manager). |
 | `start` exits immediately with no output | The server crashed or exited at startup — check the process output. Since [E00-S02-T03] the entrypoint serves `GET /health` on port 3000 and stays up; a missing `pnpm build` (stale/absent `dist/`) is the usual cause (see [Run](#run)). |
+| `start` fails with `missing required setting: sessionSecret` | Since [E00-S04-T02] the server validates its required settings at startup: the admin-session secret `EPPP_SESSION_SECRET` (≥ 32 chars) is missing or too short — set it in your shell or a local `.env` file (see [Run](#run)). |
 | `.env` files | `.env`/`.env.*` are git-ignored; a committed `.env.example` template lands with the environment story (E00-S04). |
 
 ## Out of scope