Editorial UI refresh + local-dev QoL (frontmatter, mermaid zoom, filterable branches, env passphrase, discoverBranches)

.gitignore

@@ -34,6 +34,9 @@ yarn-error.log*
 .env.test.local
 .env.production.local
 
+# local-dev projectpages.config with real passphrases — sibling of .env.local
+projectpages.config.local
+
 # vercel
 .vercel
 

README.md

@@ -1,21 +1,22 @@
 # Project Pages
 
-A Next.js portal that turns a private GitHub repository into a clean, branded documentation site. Content is fetched live via the GitHub API. Access is controlled by passphrases — each passphrase maps to a Git branch, so different audiences see different content from the same repository.
+A Next.js portal that turns a private GitHub repository into a clean, branded documentation site. Content is fetched live via the GitHub API. Access is controlled by passphrases — each user group can be granted access to one or more Git branches, so different audiences see different content from the same repository.
 
 ---
 
 ## How it works
 
-1. You define Git branches in your docs repo (e.g. `master`, `client`), one per audience.
-2. Each branch gets a passphrase in `projectpages.config`.
-3. A visitor enters their passphrase → the app resolves the matching branch → that branch's content is shown for the lifetime of their session.
+1. You define Git branches in your docs repo (e.g. `master`, `client`), one per audience — or set `discoverBranches: true` and every branch is auto-exposed.
+2. Each user group gets a passphrase. Passphrases can live in `projectpages.config`, or (recommended) in an environment variable named `PROJECTPAGES_PASSPHRASE_<GROUP>` so no secret ever ships in the docs repo.
+3. A visitor enters their passphrase → the app resolves the user group → that group's accessible branches are exposed in a searchable top-nav switcher → the first branch's content is shown for the session.
 4. Push to any branch → GitHub webhook fires → Vercel rebuilds → content is fresh.
 
 ```
 docs-repo (GitHub)
-  ├── master            ← full internal content
-  ├── client            ← curated for the client
-  └── projectpages.config ← declares branches, passphrases, file filters
+  ├── master              ← full internal content
+  ├── client              ← curated for the client
+  └── projectpages.config ← user groups, branches, file filters
+                            (passphrases can live in env instead)
 
 Project Pages (Vercel)
   └── reads config → authenticates → serves the right branch per session
@@ -24,7 +25,16 @@ Project Pages (Vercel)
 
 ---
 
-## Quick start
+## Features
+
+- **Editorial UI** — warm cream paper, near-black ink, ochre accent. Fraunces (variable serif) + DM Sans + JetBrains Mono loaded via `next/font`. Split editorial sign-in cover, ink-on-paper top-nav masthead, sidebar that auto-expands and highlights the currently-viewed file.
+- **Frontmatter rendering** — YAML frontmatter is parsed and rendered as an "At a glance" block above the content: serif title, italic description, metadata grid, tag chips, and full-width one-per-line sections for long arrays like `related` and `applies_to`. A duplicate `# Title` in the body is stripped when frontmatter carries the same title.
+- **Filterable branch switcher** — search box with match highlighting, current branch pinned to the top, Enter selects the first match, Escape clears. Pairs with `discoverBranches: true` so the switcher can auto-list every branch on the repo.
+- **Mermaid with zoom + colour** — fullscreen overlay via `createPortal` with wheel-zoom, drag-pan, HUD, and Escape-to-close. Participants in sequence diagrams and nodes in flowcharts are auto-cycled through a distinct colour palette so multi-actor diagrams read at a glance.
+
+---
+
+## Quick start (production)
 
 ```bash
 cp .env.local.example .env.local
@@ -41,6 +51,57 @@ Then add a `projectpages.config` to your docs repository — copy [`projectpages
 
 ---
 
+## Quick start (local, no config in the docs repository)
+
+For local development you can skip the "config lives in the docs repo" round-trip entirely — point the app at a config file on disk and provide the passphrase via env:
+
+```bash
+cp .env.local.example .env.local
+# add to .env.local:
+#   DOCS_REPO=<your-org>/<your-docs-repo>
+#   GITHUB_TOKEN=<a PAT with `repo` read scope>
+#   NEXTAUTH_SECRET=$(openssl rand -base64 32)
+#   NEXTAUTH_URL=http://localhost:3000
+#   PROJECTPAGES_LOCAL_CONFIG=/absolute/path/to/projectpages.config.local
+#   PROJECTPAGES_PASSPHRASE_VAIMO=some-shared-secret
+
+cp projectpages.config.example projectpages.config.local
+# edit projectpages.config.local — leave the user group's passphrase
+# empty (the env var wins), and set `discoverBranches: true` if you
+# want every branch of your docs repo to appear in the switcher.
+
+npm install
+npm run dev
+```
+
+Content (file tree + Markdown bodies) still comes from GitHub via the API — only the config lookup is short-circuited. That means the docs repo stays clean (no `projectpages.config` committed) but you still need commits pushed to see them in the app.
+
+`projectpages.config.local` is git-ignored in this repo (sibling of the local env file convention). Never commit it — it may hold real passphrases.
+
+### Local-development environment variables
+
+The full production list lives in [Deployment → Environment variables](./docs/deployment.md#environment-variables). These are the local-development toggles introduced alongside them:
+
+| Variable | Purpose |
+|---|---|
+| `PROJECTPAGES_LOCAL_CONFIG` | Absolute path to a `projectpages.config`-shaped YAML file. When set, the app reads config from disk instead of the GitHub API — nothing needs to be committed to the docs repository. |
+| `PROJECTPAGES_PASSPHRASE_<GROUP>` | Per-user-group passphrase override. Group name is upper-cased and non-alphanumerics become underscores — e.g. `vaimo` → `PROJECTPAGES_PASSPHRASE_VAIMO`, `external-partner` → `PROJECTPAGES_PASSPHRASE_EXTERNAL_PARTNER`. Wins over the config file when non-empty. Recommended so real secrets never live in the docs repo. |
+| `DEV_AUTH_BYPASS` | Set to `1` to skip the passphrase check entirely and log in as the first user group. Development only — never set in production. |
+
+### Auto-discover branches
+
+Add a top-level flag to your `projectpages.config` (or `projectpages.config.local`):
+
+```yaml
+discoverBranches: true
+```
+
+When set, the config loader calls the GitHub `listBranches` API for `DOCS_REPO` and merges every branch into the branch list. Explicit `branches:` entries stay in place and act as templates for permissions/comments/chat; discovered branches inherit those settings from the first explicit entry. Fails soft — if the API call errors, the app falls back to the declared list.
+
+Combined with the search-enabled top-nav switcher, this makes it easy to work across a repo with dozens of feature/chore branches without hand-listing each one.
+
+---
+
 ## Documentation
 
 | Topic | Description |