z-shell · ss-o · May 22, 2026 · May 22, 2026 · May 22, 2026
@@ -16,21 +16,25 @@ That ambiguity caused a concrete failure. A maintainer guide (Supabase Knowledge
 
 The three content roots have fixed, non-overlapping scopes:
 
-1. `docs/` is **Zi plugin-manager user documentation only** — installation, commands, usage guides. No maintainer, operational, or infrastructure guides.
-2. `community/` holds Z-Shell ecosystem community content (contributing, the Zsh handbook/plugin standard, ZUnit) and **maintainer / operational tooling guides** (e.g. `community/10_maintainers/`).
+1. `docs/` is **Zi plugin-manager user documentation only** — installation, commands, usage guides.
+2. `community/` holds **Z-Shell ecosystem community content only** — contributing, the Zsh handbook/plugin standard, ZUnit.
 3. `ecosystem/` holds the third-party catalog: annexes, packages, plugins.
 
+Maintainer, operational, and infrastructure runbooks do not belong on the public wiki at all. They live in `z-shell/.github/runbooks/` (e.g. `runbooks/supabase-knowledge-search.md`), which is the established home for operational documentation. Feature *implementation* (Edge Functions, migrations, scripts) still lives in the owning repository.
+
 These boundaries are recorded in the wiki `AGENTS.md` (with `CLAUDE.md` as a symlink to it) and the wiki authoring instructions (`docs-authoring.instructions.md`, `agent-docusaurus-writer.instructions.md`).
 
 ## Consequences
 
-- Maintainer tooling guides live under `community/`, not `docs/`.
-- Authoring instructions gain a Content Root Selection table and an explicit prohibition against maintainer/operational content in `docs/`.
+- Maintainer/operational runbooks live in `z-shell/.github/runbooks/`, not anywhere in the public wiki. The Supabase Knowledge Search guide was relocated from `wiki/community/10_maintainers/` to `runbooks/supabase-knowledge-search.md`.
+- Authoring instructions gain a Content Root Selection table; `docs/` and `community/` both exclude maintainer/operational content.
 - The `runbooks/instruction-update.md` runbook keeps instructions in sync when new features or content areas are added.
 
+> **Revision (2026-05-22):** An earlier draft placed maintainer/operational tooling under `community/`. Review concluded such content (secret names, infrastructure topology, ops CLIs) should not be published on the public wiki at all, so it now routes to `z-shell/.github/runbooks/`.
+
 ## Alternatives considered
 
-- **Add a fourth `maintainers/` content root.** Rejected: more navbar/config surface for a small amount of content; `community/` already fits operational/community material.
+- **Add a fourth `maintainers/` content root.** Rejected: more navbar/config surface for a small amount of content, and it would still publish maintainer/operational surface on the public wiki.
 - **Leave the guide in `docs/` and document an exception.** Rejected: keeps the ambiguity that caused the incident and invites future drift.
 - **CI placement guard only (no instruction change).** Deferred: automation without a documented rule is brittle; document first, automate later if manual enforcement proves insufficient.
 

@@ -18,7 +18,7 @@ convention.
 
 ## Wiki (`z-shell/wiki`) checklist
 
-- [ ] Pick the correct content root: `docs/` = Zi user docs only; `community/` = community + maintainer/operational; `ecosystem/` = third-party catalog. (See ADR `decisions/0006-wiki-content-root-boundaries.md`.)
+- [ ] Pick the correct content root: `docs/` = Zi user docs only; `community/` = community content only; `ecosystem/` = third-party catalog. Maintainer/operational runbooks go in this repo's `runbooks/`, not the wiki. (See ADR `decisions/0006-wiki-content-root-boundaries.md`.)
 - [ ] Update `AGENTS.md` if scope or conventions changed. `CLAUDE.md` is a symlink to `AGENTS.md`, so it updates automatically.
 - [ ] Update `.github/instructions/docs-authoring.instructions.md` (Content Root Selection, frontmatter, naming).
 - [ ] Update `.github/instructions/agent-docusaurus-writer.instructions.md` (root selection, invocation).

@@ -0,0 +1,57 @@
+# Runbook — Supabase Knowledge Search
+
+Operational guide for the Supabase-backed Z-Shell documentation search index.
+This is maintainer/operational documentation; it lives here rather than on the
+public wiki (see ADR `decisions/0006-wiki-content-root-boundaries.md`).
+
+Z-Shell Knowledge Search indexes public wiki documentation into Supabase so
+maintainers can run source-linked semantic search across the docs. The
+implementation (Edge Function, migrations, indexer CLI) lives in the
+`z-shell/wiki` repository under `supabase/` and `scripts/knowledge-search/`.
+
+GitHub repositories and the wiki remain the source of truth. Supabase stores
+derived metadata, chunks, and embeddings only.
+
+## Secrets
+
+- `SUPABASE_URL`: Supabase project API URL.
+- `SUPABASE_DB_URL`: direct Postgres connection string for server-side ingestion.
+- `SUPABASE_SECRET_KEY`: server-only `sb_secret_*` API key for maintainer CLI calls.
+- `SB_SECRET_KEY`: the same `sb_secret_*` value exposed to the `knowledge-search` Edge Function.
+- `OPENAI_API_KEY`: embedding provider key.
+
+Do not expose server-side secrets in browser code.
+
+## Index
+
+Run from the `z-shell/wiki` repository:
+
+```sh
+pnpm knowledge-search:index
+```
+
+The indexer scans `docs/`, `community/`, and `ecosystem/` Markdown and MDX
+files, chunks the content, generates embeddings, and upserts rows into the
+private `docs_search` schema. Sources whose content hash is unchanged since the
+last run are skipped to avoid unnecessary embedding calls.
+
+## Query
+
+```sh
+pnpm knowledge-search:query "release policy"
+```
+
+The query command calls the `knowledge-search` Edge Function with
+`SUPABASE_SECRET_KEY` in the `apikey` header and prints source-linked results.
+
+## Access Control
+
+The `docs_search` schema is private. Public search uses the
+`public.match_public_docs` function, which returns only sources marked `public`.
+
+The `knowledge-search` Edge Function has `verify_jwt = false` because Supabase
+secret keys are API keys, not JWTs. The function checks the `apikey` header
+itself before running a query.
+
+The SQL function keeps `set search_path = ''` for definer safety, so vector
+distance uses the schema-qualified `OPERATOR(extensions.<=>)` form.