UPDATE Document canonical palette.db build + runtime paths

Signed-off-by: ParleSec <mason@masonparle.com>

Author: ParleSec

CONTRIBUTING.md

@@ -198,7 +198,7 @@ Run the smallest set that covers your change. CI may run additional checks, but
 | Docker or service topology | `cd docker && docker compose config` and, when practical, `docker compose up -d` |
 | OID4VCI/OID4VP protocol behavior | `cd backend && go test ./internal/protocols/oid4vci ./internal/protocols/oid4vp -count=1` |
 | Palette content (`content/**`) | `cd backend && go run ./cmd/content-validate -content ../content && go test ./internal/palette/...` |
-| Palette indexer or query service | `cd backend && go test ./internal/palette/... && go run ./cmd/palette-indexer -content ../content -out ../frontend/public/palette.db` |
+| Palette indexer or query service | `cd backend && go test ./internal/palette/... && go run ./cmd/palette-indexer -content ../content -out ./dist/palette.db` |
 
 When Snyk or other security scans are skipped for forked PRs because repository secrets are unavailable, maintainers may rerun or review those checks after initial triage.
 
@@ -298,15 +298,19 @@ A deploy-time Go binary builds the runtime SQLite file:
 
 ```bash
 cd backend
-go run ./cmd/palette-indexer -content ../content -out ../frontend/public/palette.db
+go run ./cmd/palette-indexer -content ../content -out ./dist/palette.db
 ```
 
 The build is idempotent — same input produces byte-identical output. Backed by SQLite FTS5 plus structured tables (`artefacts`, `axis_values`, `edges`, `aliases`).
 
+**Canonical paths:** local and CI builds write `backend/dist/palette.db`. Production Docker images (`docker/Dockerfile.backend`, `docker/Dockerfile.fly`) run the indexer at image build time and copy the file to `/app/palette.db`, exposed via `SHOWCASE_PALETTE_DB=/app/palette.db`. Content changes require a backend image rebuild (or a mounted volume at that path for self-hosted monoliths).
+
 ### Query service
 
 Mounted at `POST /api/palette/query`. Implementation lives in `backend/internal/palette/`. The pipeline is parse → candidates → rank → match-reason emission → refinement chips. P99 latency budget is 20ms in-process. Tunable weights live in `rank.go`.
 
+Production requires `SHOWCASE_PALETTE_DB` pointing at a readable index file; the server refuses to start in `SHOWCASE_ENV=production` if the path is missing or unreadable. Docker images built from `docker/Dockerfile.backend` and `docker/Dockerfile.fly` bake `/app/palette.db` and set the variable automatically. Verify with `GET /health` (`palette.loaded`) or `GET /api` (`endpoints.palette`).
+
 ### Frontend surfaces
 
 Two mount points share one component (`frontend/src/components/palette/Palette.tsx`):

backend/cmd/palette-indexer/main.go

@@ -2,6 +2,14 @@
 // content tree. The output file is deterministic for fixed input: running the
 // indexer twice on the same tree produces a byte-identical database, which is
 // what lets CI compare deploy artefacts.
+//
+// Canonical paths:
+//   - Build-time output (local/CI): backend/dist/palette.db  (-out ./dist/palette.db from backend/)
+//   - Container build output:       /app/palette.db           (Dockerfile.backend / Dockerfile.fly)
+//   - Runtime (containers):         /app/palette.db           (SHOWCASE_PALETTE_DB)
+//
+// The index is a backend artefact served by Go at POST /api/palette/query, not
+// a frontend static file.
 package main
 
 import (

docs/starlight/astro.config.mjs

@@ -88,6 +88,7 @@ export default defineConfig({
             { slug: 'deploy/deployment-models' },
             { slug: 'deploy/release-and-tag-policy' },
             { slug: 'deploy/environment-variables' },
+            { slug: 'deploy/palette-index' },
             {
               label: 'Services',
               items: [

docs/starlight/src/content/docs/deploy/deployment-models.mdx

@@ -65,6 +65,8 @@ docker compose -f docker-compose.simple.yml up -d
 
 **Best for:** Quick evaluation of core federation protocols without multi-service overhead.
 
+The simple monolith image builds the [palette content index](/deploy/palette-index/) at image build time (`/app/palette.db`). Homepage search and cmd+K require that file and `SHOWCASE_PALETTE_DB`.
+
 ## Model 4: Custom Topology
 
 Combine selected GHCR images with your own infrastructure.

docs/starlight/src/content/docs/deploy/environment-variables.mdx

@@ -17,6 +17,7 @@ All ProtocolSoup backend services share a common set of core variables. Individu
 | `SHOWCASE_ENV` | `demo` | Runtime environment. |
 | `SHOWCASE_MOCK_IDP` | `true` | Enable built-in mock identity provider with demo users and clients. |
 | `SHOWCASE_DEBUG` | `false` | Enable debug logging. |
+| `SHOWCASE_PALETTE_DB` | *(empty — palette disabled)* | Path to the prebuilt palette SQLite index. Required in `SHOWCASE_ENV=production` when palette search is enabled. Docker images built from `Dockerfile.backend` and `Dockerfile.fly` default to `/app/palette.db`. See [Palette content index](/deploy/palette-index/). |
 
 ## Gateway
 

docs/starlight/src/content/docs/deploy/palette-index.mdx

@@ -0,0 +1,64 @@
+---
+title: "Palette content index"
+description: "How monolith deployments ship and mount the palette SQLite index for homepage search and cmd+K."
+---
+
+# Palette content index
+
+The homepage search bar and global **cmd+K** palette query a prebuilt SQLite index (`palette.db`) produced from the repository `content/` tree. The index is a **backend artefact**: Go serves `POST /api/palette/query`; it is not bundled as a Next.js static file.
+
+## Canonical paths
+
+| Context | Path |
+|---------|------|
+| Local / CI build output | `backend/dist/palette.db` |
+| Baked into Docker images | `/app/palette.db` |
+| Runtime configuration | `SHOWCASE_PALETTE_DB=/app/palette.db` |
+
+Build the index locally:
+
+```bash
+cd backend
+go run ./cmd/palette-indexer -content ../content -out ./dist/palette.db
+```
+
+## Baked into the image (recommended)
+
+`docker/Dockerfile.backend` and `docker/Dockerfile.fly` compile `palette-indexer`, run it against `/content` at **image build time**, copy `/app/palette.db` into the runtime layer, and set `SHOWCASE_PALETTE_DB=/app/palette.db`.
+
+**Implication:** changing `content/` requires rebuilding the backend (or monolith) image even when no Go source changed.
+
+Verify after deploy:
+
+```bash
+curl -s https://your-host/health | jq '.palette'
+curl -s https://your-host/api | jq '.endpoints.palette'
+curl -sf -X POST https://your-host/api/palette/query \
+  -H 'content-type: application/json' \
+  -d '{"q":"pkce"}' | jq '.results | length'
+```
+
+In `SHOWCASE_ENV=production`, the server **refuses to start** if `SHOWCASE_PALETTE_DB` is unset or the file cannot be opened.
+
+## Mounted as a volume (self-hosted)
+
+For custom monolith deployments, build the index on a host or in CI and mount it at the canonical path:
+
+```yaml
+services:
+  backend:
+    image: ghcr.io/parlesec/protocolsoup-federation:latest
+    environment:
+      SHOWCASE_ENV: production
+      SHOWCASE_PALETTE_DB: /app/palette.db
+    volumes:
+      - ./backend/dist/palette.db:/app/palette.db:ro
+```
+
+Rebuild the index whenever `content/` changes, then restart the backend.
+
+## Related
+
+- [Deployment models](/deploy/deployment-models/) — Model 3 (simple monolith) includes the baked index via `Dockerfile.backend`
+- [Environment variables](/deploy/environment-variables/) — `SHOWCASE_PALETTE_DB`
+- Contributor guide: palette section in the repository `CONTRIBUTING.md`

docs/starlight/src/content/docs/developers/development-setup.mdx

@@ -79,7 +79,7 @@ Run the smallest set that covers your change before requesting review.
 | Docker or service topology | `cd docker && docker compose config` |
 | OID4VCI/OID4VP conformance | `cd backend && go test ./internal/protocols/oid4vci ./internal/protocols/oid4vp -count=1` |
 | Palette content (`content/**`) | `cd backend && go run ./cmd/content-validate -content ../content && go test ./internal/palette/...` |
-| Palette indexer or query service | `cd backend && go test ./internal/palette/... && go run ./cmd/palette-indexer -content ../content -out ../frontend/public/palette.db` |
+| Palette indexer or query service | `cd backend && go test ./internal/palette/... && go run ./cmd/palette-indexer -content ../content -out ./dist/palette.db` |
 
 The canonical contract for palette artefacts lives in [`content/SCHEMA.md`](https://github.com/ParleSec/ProtocolSoup/blob/master/content/SCHEMA.md). New axis values must be added to `content/taxonomy.yaml`, and synonyms to `content/aliases.yaml`. Both files are validated in CI by `cmd/content-validate`.