docs: refresh project documentation against current codebase

docs/deployment.md

@@ -30,21 +30,23 @@ FamilySync uses a self-hosted Gitea Actions runner. Two workflows govern the rel
 
 ### PR gate — `.gitea/workflows/ci.yml`
 
-Triggered on every pull request targeting `main`. Three jobs run in parallel; all three must pass before the PR can be merged:
+Triggered on every pull request targeting `main`. The workflow runs a `changes` filter job first, then launches the following jobs in parallel:
 
-| Job           | What it checks                                                                    |
-| ------------- | --------------------------------------------------------------------------------- |
-| `fast-checks` | Lint (`pnpm lint`), format check (`pnpm format:check`), typecheck, PWA unit tests |
-| `api`         | DB migrations + API integration tests against a live MariaDB service container    |
-| `harness`     | Full Playwright E2E suite (iPhone + Pixel profiles) against the compiled API      |
+| Job           | Runs when            | What it checks                                                                                            |
+| ------------- | -------------------- | --------------------------------------------------------------------------------------------------------- |
+| `fast-checks` | Always               | Lint (`pnpm lint`), format check (`pnpm format:check`), markdown lint (`pnpm md:lint`), typecheck, PWA unit tests |
+| `api`         | Code-changing PRs only | DB migrations + API integration tests against a live MariaDB service container                          |
+| `harness`     | Code-changing PRs only | Full Playwright E2E suite (iPhone + Pixel + desktop profiles) against the compiled API                  |
+| `security`    | Always               | Secret scan (gitleaks, PR diff); dependency audit and outdated report on code-changing PRs               |
+| `gate`        | Always               | Aggregates results — fails if any non-skipped required job did not succeed                               |
 
-A PR with lint or format violations is blocked from merging by the `fast-checks` job.
+The `api` and `harness` jobs are **skipped on doc-only PRs** (changes confined to `.gitea/**`, `.planning/**`, or `*.md` files). A doc-only PR must pass `fast-checks` and `security`; the heavy jobs are not required.
 
-Branch protection on `main` blocks direct push and force push. Only PRs with all three required checks (`CI / fast-checks`, `CI / api`, `CI / harness`) passing can merge.
+Branch protection on `main` blocks direct push and force push. Only PRs where both `CI / fast-checks` and `CI / gate` pass can merge.
 
 ### Publish — `.gitea/workflows/publish.yml`
 
-Triggered on push to `main` (i.e., when any PR merges). Builds the `apps/api` Docker image and pushes it to the Gitea container registry.
+Triggered on push to `main` (i.e., when any PR merges). Skipped when every changed file is under `.gitea/**` or `.planning/**`. Builds the `apps/api` Docker image and pushes it to the Gitea container registry.
 
 **Registry:** `git.bergerhouse.net/luckberg/familysync-api`
 
@@ -59,6 +61,10 @@ The current milestone prefix (`v1.1`) is set in the `MILESTONE` env var at the t
 
 The immutable `:<milestone>-<sha>` tag is pushed first. `:latest` is only moved after the immutable tag has landed, so a failed second push can never leave `:latest` advanced without a corresponding rollback tag.
 
+Before pushing, the workflow runs two image hygiene assertions:
+1. **Static assertions** — verifies `.dockerignore` contains all required exclusion patterns and that the build targets `--target production`.
+2. **Boot-smoke** — starts the image with `NODE_ENV=production` and `DEV_AUTH_BYPASS=true` and asserts that it refuses to start (confirming the D-08 guard fires in the shipped image).
+
 **Authentication — `REGISTRY_PAT` secret:**
 
 The workflow authenticates with the Gitea container registry using a PAT stored in the `REGISTRY_PAT` Actions secret. The secret must have `write:package` scope. It is named `REGISTRY_PAT` — not `GITEA_REGISTRY_PAT` or any `GITEA_`-prefixed name, because Gitea reserves the `GITEA_` prefix and will reject those names at secret-creation time. `GITEA_TOKEN` and `GITHUB_TOKEN` cannot push packages.
@@ -178,7 +184,7 @@ See [docs/CONFIGURATION.md](CONFIGURATION.md) for the full variable reference in
 
 The production image does **not** auto-migrate on startup. Migrations must be applied manually before the first container start and again after any schema change.
 
-Migrations are run with `drizzle-kit`, which is a **devDependency**. The production image is built with `pnpm install --prod` (see `apps/api/Dockerfile`), so `drizzle-kit` is **not** present inside the running `api` container — you cannot migrate by exec-ing into it. Instead, run migrations from a host that has the full (dev) dependencies and can reach MariaDB.
+Migrations are run with `drizzle-kit`, which is a **devDependency**. The production image is built with `pnpm install --frozen-lockfile --prod` (see `apps/api/Dockerfile`), so `drizzle-kit` is **not** present inside the running `api` container — you cannot migrate by exec-ing into it. Instead, run migrations from a host that has the full (dev) dependencies and can reach MariaDB.
 
 The production `docker-compose.yml` does not expose the MariaDB port externally, so bring the database up with the dev compose override (which binds port 3306), apply the migrations from the host, then start the rest of the stack:
 
@@ -265,7 +271,7 @@ The Dockerfile uses a multi-stage build:
 
 1. `builder` — compiles the TypeScript API (`pnpm --filter @familysync/api build`).
 2. `pwa-builder` — builds the React PWA with Vite (`pnpm --filter @familysync/pwa build`).
-3. `production` — installs production-only dependencies, copies the compiled API and the built PWA into `./public`. The API serves the PWA at `/` via `serveStatic`.
+3. `production` — installs production-only dependencies (`pnpm install --frozen-lockfile --prod`), copies the compiled API and the built PWA into `./public`. The API serves the PWA at `/` via `serveStatic`.
 
 Both `builder` and `pwa-builder` stages run in parallel under BuildKit.