diff --git a/decisions/0006-wiki-content-root-boundaries.md b/decisions/0006-wiki-content-root-boundaries.md index 94d2e3ced..d3f7fb886 100644 --- a/decisions/0006-wiki-content-root-boundaries.md +++ b/decisions/0006-wiki-content-root-boundaries.md @@ -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. diff --git a/runbooks/instruction-update.md b/runbooks/instruction-update.md index c88b9c7db..f8405c19a 100644 --- a/runbooks/instruction-update.md +++ b/runbooks/instruction-update.md @@ -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). diff --git a/runbooks/supabase-knowledge-search.md b/runbooks/supabase-knowledge-search.md new file mode 100644 index 000000000..fb4daf720 --- /dev/null +++ b/runbooks/supabase-knowledge-search.md @@ -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.