From aa996da3f7b7bde96e8452bd56d2b22742fa633c Mon Sep 17 00:00:00 2001 From: Salvydas Lukosius Date: Fri, 22 May 2026 06:01:20 +0100 Subject: [PATCH 1/2] docs: relocate Supabase Knowledge Search runbook from wiki; revise ADR 0006 Maintainer/operational runbooks should not be published on the public wiki. Adds runbooks/supabase-knowledge-search.md and revises ADR 0006 so community/ holds community content only and maintainer ops docs live in z-shell/.github/runbooks/. --- .../0006-wiki-content-root-boundaries.md | 11 ++-- runbooks/instruction-update.md | 2 +- runbooks/supabase-knowledge-search.md | 57 +++++++++++++++++++ 3 files changed, 65 insertions(+), 5 deletions(-) create mode 100644 runbooks/supabase-knowledge-search.md diff --git a/decisions/0006-wiki-content-root-boundaries.md b/decisions/0006-wiki-content-root-boundaries.md index 94d2e3ced..e740e1c43 100644 --- a/decisions/0006-wiki-content-root-boundaries.md +++ b/decisions/0006-wiki-content-root-boundaries.md @@ -16,18 +16,21 @@ 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. +4. **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. 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. From 3ec7f61e78ef3f883fc3b67f1263203b22143a63 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 22 May 2026 05:49:36 +0000 Subject: [PATCH 2/2] docs: resolve ADR 0006 review thread consistency issues Agent-Logs-Url: https://github.com/z-shell/.github/sessions/9210f5f4-27ca-4a82-b137-a93f11a5ad9c Co-authored-by: ss-o <59910950+ss-o@users.noreply.github.com> --- decisions/0006-wiki-content-root-boundaries.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/decisions/0006-wiki-content-root-boundaries.md b/decisions/0006-wiki-content-root-boundaries.md index e740e1c43..d3f7fb886 100644 --- a/decisions/0006-wiki-content-root-boundaries.md +++ b/decisions/0006-wiki-content-root-boundaries.md @@ -19,7 +19,8 @@ The three content roots have fixed, non-overlapping scopes: 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. -4. **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. + +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`). @@ -33,7 +34,7 @@ These boundaries are recorded in the wiki `AGENTS.md` (with `CLAUDE.md` as a sym ## 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.