docs: move maintainer tooling to community/ and define content-root boundaries#736
Merged
Conversation
docs/ is Zi user docs only; maintainer operational guides belong in community/. Discards a stale untracked community/maintainers duplicate using outdated SUPABASE_SERVICE_ROLE_KEY naming; keeps the canonical SB_SECRET_KEY copy.
Deploying zsh with
|
| Latest commit: |
cf8d830
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://bf6d26f9.zsh.pages.dev |
| Branch Preview URL: | https://feature-wiki-maintainers-pla.zsh.pages.dev |
Contributor
There was a problem hiding this comment.
Pull request overview
Moves the canonical Supabase Knowledge Search maintainer guide into the community/ content root and updates contributor/agent instructions to enforce clear boundaries between docs/, community/, and ecosystem/ so maintainer/operational docs don’t drift back into docs/.
Changes:
- Adds
community/10_maintainers/with a generated-index category and the Supabase Knowledge Search maintainer page. - Updates
AGENTS.mdto explicitly define the fixed scope of each content root and adds a checklist for keeping instructions in sync. - Updates authoring/agent instruction files to include a content-root selection rule and prohibition against placing maintainer docs under
docs/.
Reviewed changes
Copilot reviewed 3 out of 5 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| community/10_maintainers/01_supabase_knowledge_search.mdx | Adds maintainer guide for Supabase-backed knowledge search (secrets, indexing, querying, access control). |
| community/10_maintainers/category.json | Creates a “Maintainers” category with a generated index in the community root. |
| AGENTS.md | Defines content-root scope boundaries and adds guidance on updating instruction sources. |
| .github/instructions/docs-authoring.instructions.md | Adds a Content Root Selection table and an explicit prohibition for maintainer docs under docs/. |
| .github/instructions/agent-docusaurus-writer.instructions.md | Adds an explicit root-selection rule for the docusaurus-writer agent. |
ss-o
added a commit
that referenced
this pull request
May 22, 2026
* docs(annexes): update available meta-plugins list
Signed-off-by: Salvydas Lukosius <ss-o@users.noreply.github.com>
* docs: update Zi paths to XDG base dir defaults and refresh short URLs
- Replace hardcoded ~/.zi paths with ${XDG_DATA_HOME:-$HOME/.local/share}/zi
- Update ZI[HOME_DIR]/ZI[BIN_DIR] defaults in installation and commands guides
- Update ZPFX/polaris references across plugin standard, customization,
bin-gem-node annex, syntax guide, and zi_console docs
- Replace deprecated git.io short URLs with zshell.dev equivalents
* docs(community): add ZUnit testing framework section
Introduces community/04_zunit/ with eight pages covering installation,
test syntax, assertions, running tests, configuration, and CI integration.
* docs: update raw GitHub URLs from zi-src to source
* fix(docs): correct raw GitHub URLs from zi-src to src
* fix(docs): repair zunit community links (#727)
Co-authored-by: ss-o <ss-o@users.noreply.github.com>
* docs(gallery): fix zsh-eza repository reference
* fix(gallery): replace dead startify reference
* fix(ci): disable stale trunk cache
* fix(docs): update legacy startify references
* feat(docs): add syntax highlighting + restructure community contributing section (#728)
* feat(docs): add z-shell syntax highlighting
* docs(community): restructure contributing section with SVG illustrations
- Create community/00_contributing/ as first-priority section
- index.mdx: overview with banner SVG + card grid layout
- 01_getting_started.mdx: org-wide fork/branch/commit/PR guide
- 02_contributing_to_zi.mdx: zi-specific contributing guide
- 03_zsh_plugin_standard.mdx: moved from community root (slug preserved)
- 04_contributing_docs.mdx: wiki MDX authoring and Crowdin guide
- 05_project_management.mdx: absorbs project tracker + labels content
- Add six SVG illustrations to static/img/svg/community/:
- contributing-banner.svg: wide workflow diagram (fork→code→PR→merge)
- contributing-getting-started.svg: git branch tree (120×120)
- contributing-zi.svg: gear with zi logo (120×120)
- contributing-plugin-standard.svg: plug/socket icon (120×120)
- contributing-docs.svg: document with pen (120×120)
- contributing-project-management.svg: kanban board (120×120)
- Renumber community top-level:
- 02_zsh_plugin_standard.mdx removed (moved into 00_contributing/)
- 03_zsh_native_scripting_handbook.mdx → 02_
- 04_zunit/ → 03_zunit/ (update _category_.json position + doc link)
- Fix ZUnit broken links in index.mdx, 01_installation.mdx, 04_running-tests.mdx
by adding .mdx extension (forces correct file-based resolution)
- Update community/index.mdx with contributing CTA section
Closes: docs/project-tracker-and-labels branch (content absorbed)
* feat(highlight): unified zsh/zi/zunit prism grammar with token colors
- Expand zsh grammar: adds zsh-builtin (30+ builtins), zsh-expansion-flag,
zsh-special-parameter, zsh-glob-qualifier alongside existing zi/zunit tokens
- Simplify prism-include-languages.ts to swizzle delegation pattern
- Add comprehensive CSS token palette (9 token types, light + dark themes)
- Fix dead link in zsh_startify.mdx (z-shell/zsh-startify repo is gone)
- Migrate 44 MDX files from shell to zsh/zi/zunit language fences
* fix(docs): remove dead links to non-existent GitHub repositories
- ecosystem/plugins/zsh_startify.mdx: remove link to z-shell/zsh-startify (404)
and remove FontAwesome icon from heading (FA kit removed from wiki)
- community/gallery/collection/06_plugins.mdx: remove hyperlink from
zsh-startify heading (repo no longer exists)
- community/00_contributing/index.mdx: fix broken CODE_OF_CONDUCT link
(z-shell/zi repo has no CODE_OF_CONDUCT.md) — use contributor-covenant.org
- community/00_contributing/02_contributing_to_zi.mdx: fix same broken
CODE_OF_CONDUCT link; remove link to z-shell/community guidelines (repo 404)
* feat(highlight): implement zsh/zi/zunit prism grammar and token CSS
- z-shell-languages.ts: rewrite grammar using named capture groups for
ESLint prefer-named-capture-group compliance; expand zsh-builtin list
to 50+ builtins; rename zsh-keyword → zsh-builtin; add zsh-expansion-flag
token; reorganize insertBefore calls for correct priority ordering
- prism-include-languages.ts: replace manual additionalLanguages loop with
clean swizzle delegation to @theme-original/prism-include-languages
- custom.css: add 9-token semantic color palette (light + dark) for
zsh-builtin, zsh-expansion-flag, zsh-special-parameter, zsh-glob-qualifier,
zi-command keyword, zi-command subcommand function, zi-ice, zunit-command,
zunit-directive, zunit-assertion; uses CSS custom properties and nested rules
* fix(docs): fix admonition titles and lychee exclusion
- Convert space-separated admonition titles to bracket syntax (MDX v3
requirement): :::note Title -> :::note[Title] in 4 files
- Add z-shell/zsh-startify to lychee exclude list — repo is archived/removed
and is referenced in existing docs on the target (next) branch; Trunk
checks both PR and base versions, causing false CI failures
* fix(ci): correct build-script for compressed-size-action
The action prepends 'pnpm run' to the build-script value, so passing
'pnpm build:en' ran 'pnpm run pnpm build:en' — a non-existent script.
Change to the bare script name 'build:en' so the action runs
'pnpm run build:en' correctly.
* fix(highlight): correct CSS selector and override inline Prism theme colors
prism-react-renderer applies inline style="color:..." to token spans
using the Dracula/GitHub theme's alias colors, which beats plain CSS rules.
Two fixes:
- Selector: token colors were targeting <code> but Docusaurus puts
language-* on <pre>; change to pre.language-* selectors.
- Override: add !important to all custom token color declarations so
they win over the inline styles.
Also migrate z-shell/community membership links to z-shell/.github
(community repo is private; .github has the same 05_membership.yml
template and public issues enabled).
* fix(highlight): flatten CSS selectors — Docusaurus pipeline strips CSS nesting
Nested rules inside :is() and block selectors were mangled by the build,
producing invalid CSS like `.language-zsh,...) .token.zsh-builtin` with
the `pre` and `:is(` prefix stripped. Flattened all token color rules to
standard descendant selectors which the pipeline processes correctly.
* fix(highlight): expand zi/zunit grammar coverage
zi-command: add light-mode, self-update, cdreplay, cdlist, status
zi-ice: add compile, eval, extract, has, if, nocd, sbin, svn (all
appear in ecosystem/docs pages but were tokenized as plain text)
zunit-command: broaden pattern from strict lookahead to match bare
zunit and any subcommand/flag, using lookbehind for boundary
* feat(docs): redesign four landing pages with banner SVGs and card grids
Each page now matches the contributing page pattern:
- Full-width 720×140 banner SVG illustrating the section topic
- :::info/:::tip admonition with key links or quick facts
- CSS grid of cards (icon + title + description + arrow link)
Pages updated: docs/, ecosystem/, community/, community/zunit/
SVGs created: docs-banner, ecosystem-banner, community-banner, zunit-banner
All card links verified against actual built URLs.
* fix(highlight): fix zi-command compound selector and zi-ice token priority
prism-react-renderer v2 renders `inside` tokens as compound classes on the
same span, not nested spans — fix CSS to use .token.zi-command.keyword
instead of descendant .token.zi-command .token.keyword.
Move zi-ice insertBefore to fire before zsh-builtin so ice modifiers like
'wait' and 'src' are not mis-tokenized as shell builtins in zi blocks.
Also redesign docs/ecosystem/community/zunit banner SVGs with distinct
color palettes (blue/amber/purple/teal-red) so each section has a unique
visual identity.
* fix(docs): remove zsh-startify — plugin not under z-shell org
Remove ecosystem/plugins/zsh_startify.mdx (was draft: true) and the
corresponding gallery entry in 06_plugins.mdx. The plugin is hosted
under a third-party org that we do not reference in Z-Shell docs.
---------
Co-authored-by: ss-o <ss-o@users.noreply.github.com>
* docs(wiki): address PR 732 review feedback
* chore(meta): secure workflows and unify agent instructions
* chore(meta): update legacy zdharma references to z-shell
* chore(meta): final zdharma archival cleanup
* fix(docs): repair broken revolver and color snippet links
* fix(docs): pin snippet links to SHA to resolve 404s
* chore: remove unused codebase boilerplate templates
* chore(ci): remove emoji prefixes from workflow and job names
* feat(search): add Supabase knowledge search
* fix(search): use Supabase secret key
* chore(cf): generate Pages Function env types from wrangler bindings
* chore(cf): gitignore generated worker-env.d.ts
* feat(cf): add Pages Function to proxy offloaded R2 assets
* fix(cf): add CORS and robots headers, add functions tsconfig
* fix(cf): standalone functions tsconfig and OPTIONS preflight handler
* fix(cf): align module/moduleResolution in functions tsconfig
* fix(cf): guard non-GET/HEAD methods and add Allow-Headers to preflight
* fix(ci): re-pin GitHub Actions to valid commit SHAs (#739)
Re-pinned every action (workflows + .trunk/setup-ci) to verified release SHAs; fixes Trunk Check + CodeQL failing at job setup. Closes #738.
* docs: move maintainer tooling to community/ and define content-root boundaries (#736)
Reconciles the divergent docs/maintainers vs community/maintainers duplicate (kept canonical SB_SECRET_KEY copy), moves it to community/10_maintainers/, and hardens AGENTS.md + authoring instructions so docs/ stays Zi-user-docs-only.
* fix(search): harden Edge Function + indexer and add local Supabase config
- query.mjs: parse response as text first; surface HTTP status + body on non-JSON errors instead of crashing
- index.ts: wrap the Edge Function handler in try/catch returning internal_error
- migration: schema-qualify vector distance as OPERATOR(extensions.<=>) so match_public_docs works under 'set search_path = '''
- add supabase/config.toml (local CLI config) and supabase/.gitignore
* fix: address PR #740 review feedback
- functions/[[path]].ts: implement Range + If-None-Match handling (206/304) so the advertised preflight headers are actually supported; add Accept-Ranges
- prism: use plain capturing groups instead of named groups for Prism lookbehind (older-browser regex compatibility)
- embed-docs: skip re-embedding sources whose content_hash is unchanged, and batch embeddings into one request per document instead of one per chunk
* docs: move maintainer runbook out of the wiki
The Supabase Knowledge Search maintainer guide is operational documentation
(secret names, infra topology, ops CLIs) and does not belong on the public wiki.
Relocated to z-shell/.github/runbooks/supabase-knowledge-search.md. Updates the
content-root boundaries: community/ holds community content only; maintainer /
operational runbooks live in z-shell/.github/runbooks/. Refs ADR 0006.
* fix(deps): regenerate pnpm-lock.yaml after next<-main merge
The lockfile auto-merge left a dangling ws@8.20.0 reference (main bumped ws to
8.20.1), breaking 'pnpm i --frozen-lockfile' in CI. Re-resolved the lockfile.
* fix(search): do not expose internal error details in Edge Function responses
Addresses CodeQL 'information exposure through a stack trace': log error
details server-side and return only a generic error code to the client.
* fix(prism): keep named capture groups for lookbehind patterns
Reverts the plain-capture-group change: the repo's eslint config enforces
prefer-named-capture-group, and Prism's lookbehind:true requires a capturing
(not non-capturing) group, so named groups are the only option that satisfies
both. Named capture groups are ES2018 and supported across the project's
browserslist targets.
---------
Signed-off-by: Salvydas Lukosius <ss-o@users.noreply.github.com>
Co-authored-by: Salvydas Lukosius <ss-o@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Reconciles a divergent, half-finished doc move and locks the wiki content-root boundaries into instructions so it cannot recur.
The bug
The Supabase Knowledge Search maintainer guide existed in two places with divergent content:
docs/maintainers/(tracked) — canonical,SB_SECRET_KEY/SUPABASE_SECRET_KEY(matchessupabase/functions/knowledge-search/index.tsandscripts/knowledge-search/query.mjs)community/maintainers/(untracked, no history) — stale, used the outdatedSUPABASE_SERVICE_ROLE_KEYnamingFollowing the earlier "move" literally would have shipped the stale secret-key names.
Changes
docs/maintainers/→community/10_maintainers/(canonical copy), discarding the stale untracked duplicate.docs/is Zi user docs only; maintainer/operational guides belong incommunity/.AGENTS.md(andCLAUDE.md, a symlink),docs-authoring.instructions.md(Content Root Selection table + prohibition), andagent-docusaurus-writer.instructions.md(root-selection rule).Verification
pnpm validate:frontmatter— passespnpm build:en— succeeds, no broken-link warnings/community/maintainers/supabase_knowledge_searchpresent; old/docs/maintainers/...absent;docs/clean of maintainer pagesid)Companion governance (ADR 0006 + instruction-update runbook + MCP-plugin instructions) lands separately in
z-shell/.github.