docs: refresh project documentation against current codebase

README.md

@@ -96,6 +96,8 @@ docker-compose.dev.yml   Dev overrides (bind-mount src/, expose DB/Redis ports)
 | `pnpm typecheck`                            | Type-check all workspaces                             |
 | `pnpm format`                               | Reformat all files with Prettier                      |
 | `pnpm format:check`                         | Check formatting without writing (used in CI)         |
+| `pnpm md:lint`                              | Lint Markdown files with markdownlint-cli2            |
+| `pnpm generate-secrets`                     | Generate random secrets for `.env` setup              |
 | `pnpm --filter @familysync/api db:generate` | Generate Drizzle migration from schema changes        |
 | `pnpm --filter @familysync/api db:migrate`  | Apply pending migrations to MariaDB                   |
 
@@ -128,15 +130,17 @@ See [`docs/deployment.md`](docs/deployment.md) for Unraid/Docker Compose deploym
 
 ## CI
 
-Every PR to `main` must pass three required checks before it can merge:
+Every PR to `main` must pass four jobs before it can merge:
 
-| Job                | What it runs                                                               |
-| ------------------ | -------------------------------------------------------------------------- |
-| `CI / fast-checks` | `pnpm lint`, `pnpm format:check`, `pnpm typecheck`, PWA unit tests         |
-| `CI / api`         | DB migrations + API test suite against a real MariaDB 11 service container |
-| `CI / harness`     | Playwright end-to-end harness (WebKit iPhone + Chromium Pixel)             |
+| Job                  | What it runs                                                               |
+| -------------------- | -------------------------------------------------------------------------- |
+| `CI / fast-checks`   | `pnpm lint`, `pnpm format:check`, `pnpm md:lint`, `pnpm typecheck`, PWA unit tests |
+| `CI / api`           | DB migrations + API test suite against a real MariaDB 11 service container |
+| `CI / harness`       | Playwright end-to-end harness (WebKit iPhone + Chromium Pixel)             |
+| `CI / security`      | Gitleaks secret scan (all PRs) + `pnpm audit` + outdated report (code PRs) |
+| `CI / gate`          | Aggregate: asserts all jobs above passed or were legitimately skipped      |
 
-`fast-checks` and `api`/`harness` run in parallel. Defined in `.gitea/workflows/ci.yml`.
+`fast-checks` and `security` always run. `api` and `harness` are skipped for doc-only PRs (no changes outside `.gitea/`, `.planning/`, or `*.md`). The `gate` job is the single required check for merge. Defined in `.gitea/workflows/ci.yml`.
 
 ## Publishing / Releases
 
@@ -151,7 +155,7 @@ Publishing happens automatically on every push to `main` — i.e. when a PR merg
 
 **Required secret:** `REGISTRY_PAT` — a Gitea Actions secret holding a PAT with `write:package` scope. Named `REGISTRY_PAT` (not `GITEA_*`): Gitea reserves the `GITEA_` prefix for secret names, so `GITEA_`-prefixed names cannot be created. `GITEA_TOKEN` / `GITHUB_TOKEN` cannot push packages.
 
-**Safety gate:** Branch protection on `main`, not a `needs:` dependency in `publish.yml`. The PR test jobs (`fast-checks`, `api`, `harness` in `ci.yml`) run on `pull_request` — they never run in the same workflow invocation as `publish.yml`. Tests gate the PR; `main` is trusted to be green because direct push and force push are blocked and the three required checks (`CI / fast-checks (pull_request)`, `CI / api (pull_request)`, `CI / harness (pull_request)`) must pass before merge.
+**Safety gate:** Branch protection on `main`, not a `needs:` dependency in `publish.yml`. The PR test jobs (`fast-checks`, `api`, `harness`, `security`, `gate` in `ci.yml`) run on `pull_request` — they never run in the same workflow invocation as `publish.yml`. Tests gate the PR; `main` is trusted to be green because direct push and force push are blocked and the two required checks (`CI / fast-checks` and `CI / gate`) must pass before merge. `CI / api` and `CI / harness` are conditionally skipped on doc-only PRs and are gated via the always-running `CI / gate` aggregate.
 
 **To bump the milestone tag** at a milestone boundary: edit the `MILESTONE` env value at the top of `.gitea/workflows/publish.yml`.