docs: move maintainer tooling to community/ and define content-root boundaries

.github/instructions/agent-docusaurus-writer.instructions.md

@@ -33,3 +33,13 @@ Invoke the `docusaurus-writer` agent and provide:
 1. The target content root and directory (`docs/`, `community/`, `ecosystem/`)
 2. The page or section title
 3. Any existing pages to cross-link
+
+### Choosing the content root
+
+Before creating a page, select the root:
+
+- Admin / tooling / operational / infrastructure → `community/`.
+- Zi plugin-manager user docs → `docs/`.
+- Third-party ecosystem (annexes, packages, plugins) → `ecosystem/`.
+
+`docs/` is Zi user docs only — never put maintainer tooling there.

.github/instructions/docs-authoring.instructions.md

@@ -5,6 +5,20 @@ applyTo: "{docs,community,ecosystem}/**/*.mdx"
 
 # Docs Authoring
 
+## Content Root Selection
+
+Choose the content root before writing. The roots are not interchangeable:
+
+| Content type                                       | Root                                            |
+| -------------------------------------------------- | ----------------------------------------------- |
+| Zi plugin-manager install / commands / usage       | `docs/`                                         |
+| Contributing, Zsh handbook, plugin standard, ZUnit | `community/`                                    |
+| Maintainer / operational / infrastructure guides   | `community/` (e.g. `community/10_maintainers/`) |
+| Third-party annexes, packages, plugins             | `ecosystem/`                                    |
+
+**Prohibition:** Never place maintainer, operational, or infrastructure
+documentation under `docs/`. `docs/` is Zi end-user documentation only.
+
 ## Frontmatter
 
 Every MDX page starts with YAML frontmatter, then imports, then content:

AGENTS.md

@@ -17,10 +17,15 @@ This project follows the organization-wide [Z-Shell Organization Guidelines](htt
 
 ## Architecture
 
-- Docusaurus site with three independent docs content roots:
-  - `docs/` → `/docs` (core documentation, getting started, guides)
-  - `community/` → `/community` (community guides, Zsh plugin standard)
-  - `ecosystem/` → `/ecosystem` (annexes, packages, plugins)
+- Docusaurus site with three independent docs content roots. Each root has a
+  fixed scope — do not cross these boundaries:
+  - `docs/` → `/docs` — **Zi plugin manager user documentation only**
+    (installation, commands, usage guides). Do NOT place maintainer,
+    operational, or infrastructure guides here.
+  - `community/` → `/community` — Z-Shell ecosystem community content:
+    contributing, the Zsh handbook/plugin standard, ZUnit, and **maintainer /
+    operational tooling guides** (e.g. `community/10_maintainers/`).
+  - `ecosystem/` → `/ecosystem` — third-party catalog: annexes, packages, plugins.
 - Each content root uses the shared `sidebars.ts` (autogenerated from directory structure) plus local `_category_.json` files for ordering.
 - Site config, plugins, and routing: `docusaurus.config.ts`. See `.github/instructions/docusaurus-config.instructions.md` for config structure, feature flags, and constraints.
 - Docusaurus client API (components, hooks, theme imports): `.github/instructions/docusaurus-api.instructions.md` — prefer native Docusaurus components over raw HTML equivalents.
@@ -31,6 +36,19 @@ This project follows the organization-wide [Z-Shell Organization Guidelines](htt
   - `<ShellCodeCopy>` — copyable shell command blocks
 - Localization uses Crowdin (`crowdin.yml`). Never edit files under `i18n/` directly.
 
+## Adding New Content or Infrastructure
+
+When you add a new content area, feature, or infrastructure component, pick the
+content root using the scope rule above, then review and update these files so
+guidance stays current:
+
+- `AGENTS.md` (this file; `CLAUDE.md` is a symlink to it) — content-root scope and conventions.
+- `.github/instructions/docs-authoring.instructions.md` — Content Root Selection.
+- `.github/instructions/agent-docusaurus-writer.instructions.md` — root selection.
+
+See the org runbook `runbooks/instruction-update.md` in `z-shell/.github` for the
+full cross-repo checklist.
+
 ## Conventions
 
 ### Documentation (MDX)