z-shell · ss-o · May 22, 2026 · May 22, 2026 · May 22, 2026
@@ -0,0 +1,64 @@
+---
+description: "When and how to use the project MCP plugins (Context7, Supabase, Cloudflare, Greptile) and Claude Code toolkits (pr-review-toolkit, hookify, security-guidance) across the Z-Shell workspace."
+applyTo: "**"
+---
+
+# Project MCP Plugins
+
+Guidance for the MCP servers and Claude Code plugins enabled in the Z-Shell
+maintainer workspace. Prefer these over guesswork or generic web search.
+
+## General rules
+
+- Prefer Context7 over web search for any library, framework, or API documentation.
+- Treat every OAuth-gated plugin (Supabase, Cloudflare, Greptile) as touching a
+  **live external service**. Read-only by default; confirm with the user before
+  any write, deploy, secret change, or other outward-facing action.
+- GitHub, the wiki, and the Z-Shell Tracker remain the source of truth. Record
+  plugin-derived findings in PRs and issues, not only in local agent memory.
+
+## Context7 (no auth)
+
+- **Purpose:** current docs and code examples for libraries and frameworks
+  (Docusaurus, Supabase JS, React, wrangler, etc.).
+- **When to use:** before assuming API or config behavior; version migrations;
+  setup and CLI usage questions.
+- **When NOT to use:** business-logic debugging, refactoring, or general
+  programming concepts.
+
+## Supabase (OAuth)
+
+- **Purpose:** the live Z-Shell wiki Supabase project — database, migrations,
+  Edge Functions, secrets, analytics.
+- **When to use:** verify Edge Function env/secret names (e.g. `SB_SECRET_KEY`),
+  inspect schema and migrations, check the knowledge-search index.
+- **When NOT to use:** never run destructive SQL or write/rotate secrets without
+  explicit user confirmation. Supabase stores only derived embeddings and
+  metadata; GitHub and the wiki are canonical.
+- **Auth required:** yes (OAuth; the granted scope is broad — stay read-only by
+  default and confirm before any write).
+
+## Cloudflare (OAuth)
+
+- **Purpose:** Pages, Workers, R2, and observability for the wiki, which
+  continuously deploys from `main`.
+- **When to use:** verify Pages deployments, inspect logs, R2 work (see the
+  `wiki-r2-proxy` spec), and debug Pages Functions.
+- **When NOT to use:** no production deploys or binding changes without
+  confirmation.
+- **Auth required:** yes (OAuth).
+
+## Greptile (OAuth)
+
+- **Purpose:** semantic code search across the **multi-repo** workspace.
+- **When to use:** cross-repo reference scans before moves or renames; locating
+  patterns that span repositories.
+- **When NOT to use:** single-file lookups where local grep or Read is faster.
+- **Auth required:** yes (OAuth). Read-only.
+
+## Claude Code toolkits
+
+- **pr-review-toolkit:** reviewer, silent-failure, type-design, test, and
+  comment subagents. Run on a diff before requesting human review.
+- **hookify:** generate Claude Code hooks from recurring conversation mistakes.
+- **security-guidance:** security review of pending changes before merge.
@@ -0,0 +1,40 @@
+# 6. Wiki Content-Root Boundaries
+
+- **Status:** PROPOSED
+- **Date:** 2026-05-22
+- **Deciders:** ss-o, Claude Code
+- **Supersedes:** None
+- **Superseded by:** None
+
+## Context
+
+The Docusaurus wiki (`z-shell/wiki`) has three independent content roots — `docs/`, `community/`, and `ecosystem/`. The wiki `AGENTS.md` described `docs/` only as "core documentation, getting started, guides", which is ambiguous: it does not distinguish Zi end-user documentation from maintainer or operational content.
+
+That ambiguity caused a concrete failure. A maintainer guide (Supabase Knowledge Search) was placed under `docs/maintainers/`, then half-moved to `community/`, leaving a divergent duplicate. The `community/` copy was untracked and carried stale secret-key naming (`SUPABASE_SERVICE_ROLE_KEY`), while the canonical `docs/` copy matched the code (`SB_SECRET_KEY` / `SUPABASE_SECRET_KEY`). A literal "move" would have shipped the stale naming.
+
+## Decision
+
+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/`).
+3. `ecosystem/` holds the third-party catalog: annexes, packages, plugins.
+
+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/`.
+- The `runbooks/instruction-update.md` runbook keeps instructions in sync when new features or content areas are added.
+
+## 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.
+- **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.
+
+## References
+
+- `z-shell/wiki` PR #736 — move maintainer tooling to `community/` and define content-root boundaries.
+- `runbooks/instruction-update.md` — the maintenance routine this ADR establishes.
@@ -0,0 +1,46 @@
+# Runbook — Instruction Update
+
+Use this workflow to keep agent and contributor instructions current when the
+codebase gains a feature, infrastructure component, or new content area. It is
+the living checklist that answers "which instruction files need updating when I
+change something?"
+
+## When to use this
+
+Run this before opening a PR that:
+
+- adds a new content area, page section, or directory to a repository
+- introduces a new feature, service, or infrastructure component
+- changes a convention, boundary, or workflow that an instruction file describes
+
+Skip it for pure bug fixes or content edits that do not change any documented
+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`.)
+- [ ] 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).
+- [ ] Run `pnpm validate:frontmatter` and `pnpm build:en`.
+
+## Org (`z-shell/.github`) checklist
+
+- [ ] Decision-level change? Draft an ADR — see `runbooks/adr.md` (status starts `PROPOSED`).
+- [ ] Update affected runbooks and `.github/instructions/`.
+- [ ] New tooling/plugin? Update `.github/instructions/mcp-plugins.instructions.md`.
+
+## Other repos
+
+- [ ] Update the repo's `AGENTS.md` / `.github/copilot-instructions.md` and any scoped `.github/instructions/*.instructions.md` that describe the changed area.
+- [ ] Prefer linking to canonical org/wiki guidance over duplicating it.
+
+## Template prompt for agents
+
+```text
+I am adding <feature / content area>. Per runbooks/instruction-update.md:
+- which content root applies (wiki)?
+- which instruction files and ADRs need updating?
+- does this decision warrant a new ADR?
+List the files to touch before writing code.
+```