ci(project): add tracker auto-add workflow

.github/README.md

@@ -92,15 +92,16 @@ steps:
 
 Starter workflows available in every org repository under **Actions > New workflow**:
 
-| Template      | Description                 |
-| ------------- | --------------------------- |
-| Trunk         | Trunk code-quality workflow |
-| Zsh CI        | Starter Zsh CI workflow     |
-| Rclone Action | File sync with rclone       |
+| Template        | Description                                            |
+| --------------- | ------------------------------------------------------ |
+| Trunk           | Trunk code-quality workflow                            |
+| Zsh CI          | Starter Zsh CI workflow                                |
+| Rclone Action   | File sync with rclone                                  |
+| Project Tracker | Adds `meta:org-tracked` issues to the org-wide tracker |
 
 Label definitions live in [`./lib/labels.yml`](lib/labels.yml) and should be applied through org maintenance scripts or API-driven automation, not via a generic starter workflow template.
 
-Tracker and project automation should be configured at the project or owning-repository level, then documented here when it becomes a shared org convention.
+Tracker and project automation are documented in [`../runbooks/project-tracker.md`](../runbooks/project-tracker.md). Project 28 is the org-wide tracker, and issues labelled `meta:org-tracked` should be added there automatically by either the Project v2 built-in workflow or the repository workflow fallback.
 
 ## Renovate
 
@@ -123,6 +124,7 @@ This repository is the right place for any **organization-level** configuration:
 - **Updating agent instructions, ADRs, runbooks, or patterns** — edit `AGENTS.md`, `decisions/`, `runbooks/`, or `PATTERNS.md`
 - **Defining weekly review, ADR, or release coordination workflows** — add or update the relevant file under `runbooks/`
 - **Recording cross-agent progress** — follow `.github/AGENT_MEMORY.md` and keep active state in issues, PRs, and the Z-Shell Tracker
+- **Configuring tracker auto-add** — follow `../runbooks/project-tracker.md`
 - **Updating the shared label set** — edit `.github/lib/labels.yml` and roll it out via the org's maintenance automation
 - **Cleaning legacy labels** — follow `../runbooks/labels.md` before deleting labels from live repositories
 - **Creating a reusable CI action** — add a composite action under `actions/<name>/action.yml`

.github/workflows/project-tracker.yml

@@ -0,0 +1,55 @@
+---
+name: Project Tracker
+
+on:
+  issues:
+    types: [opened, labeled, reopened]
+  workflow_call:
+    inputs:
+      issue_url:
+        description: Issue URL to add to the Z-Shell Tracker.
+        required: true
+        type: string
+      project_owner:
+        description: Project owner login.
+        required: false
+        type: string
+        default: z-shell
+      project_number:
+        description: Project number.
+        required: false
+        type: string
+        default: "28"
+    secrets:
+      Z_SHELL_PROJECT_TOKEN:
+        description: Token with write access to the organization Project v2 board.
+        required: false
+
+permissions:
+  contents: read
+  issues: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.issue.node_id || inputs.issue_url }}
+  cancel-in-progress: true
+
+jobs:
+  add-tracked-issue:
+    name: Add tracked issue
+    if: >-
+      ${{
+        github.event_name == 'workflow_call' ||
+        contains(github.event.issue.labels.*.name, 'meta:org-tracked')
+      }}
+    runs-on: ubuntu-latest
+    env:
+      GH_TOKEN: ${{ secrets.Z_SHELL_PROJECT_TOKEN || github.token }}
+      ISSUE_URL: ${{ inputs.issue_url || github.event.issue.html_url }}
+      PROJECT_OWNER: ${{ inputs.project_owner || 'z-shell' }}
+      PROJECT_NUMBER: ${{ inputs.project_number || '28' }}
+    steps:
+      - name: Add issue to project
+        run: |
+          gh project item-add "${PROJECT_NUMBER}" \
+            --owner "${PROJECT_OWNER}" \
+            --url "${ISSUE_URL}"

AGENTS.md

@@ -95,6 +95,7 @@ For recurring organization workflows, prefer the runbooks and keep the first pas
 - weekly org review: `runbooks/org-review.md`
 - issue and PR triage: `runbooks/triage.md`
 - label maintenance: `runbooks/labels.md`
+- project tracker automation: `runbooks/project-tracker.md`
 - ADR drafting: `runbooks/adr.md`
 - release coordination and release-model classification: `runbooks/release.md`
 
@@ -137,5 +138,6 @@ Do not silently work around drift. Open or update an issue in `z-shell/.github`,
 - `runbooks/org-review.md`
 - `runbooks/adr.md`
 - `runbooks/labels.md`
+- `runbooks/project-tracker.md`
 - `runbooks/release.md`
 - `runbooks/triage.md`

PATTERNS.md

@@ -82,20 +82,42 @@ fi
 
 Prefer the simpler Zi-aware form when the repository is clearly targeting Zi-managed loading.
 
-## Provide an unload function for side-effectful plugins
+## Mandatory SHA-pinning for GitHub Actions
 
 Observed in:
 
-- `zsh-plugins/zsh-eza/zsh-eza.plugin.zsh`
-- `zsh-plugins/zsh-fancy-completions/zsh-fancy-completions.plugin.zsh`
+- `zd/.github/workflows/`
+- `src/.github/workflows/`
+- `wiki/.github/workflows/`
+- `zunit/.github/workflows/`
+- `zi/.github/workflows/`
 
 Pattern:
 
-- provide `<plugin-name>_plugin_unload`
-- remove `fpath` additions
-- undo hooks, widgets, aliases, and globals
-- self-destruct with `unfunction`
+- Pin all external and internal GitHub Action references to a full 40-character commit SHA.
+- Append a version or branch comment (e.g., `# v4` or `# main`) to the end of the line for human readability.
+
+```yaml
+# Good: pinned to SHA with version comment
+uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+# Bad: mutable tag
+uses: actions/checkout@v4
+```
+
+This ensures maximum security against tag-switching attacks and guarantees that CI runs are reproducible across time.
+
+## Debian-based CI/Docker Environments
+
+Observed in:
+
+- `zd/docker/Dockerfile`
+- `src/.github/workflows/`
+- `zunit/.github/workflows/`
+
+Pattern:
 
-This keeps plugin behavior reversible and makes side effects explicit.
+- Prefer `debian:trixie-slim` (or current stable) or `ubuntu-latest` over Alpine Linux for CI/Docker environments.
+- Ensure `glibc` compatibility and standard GNU userland tools (e.g., `apt-get`, `autoreconf`, `make`) are available to support consistent compilation and testing of Zsh and its modules.
 
-Reference: <https://wiki.zshell.dev/community/zsh_plugin_standard#unload-function>
+This reduces toolchain fragmentation and prevents subtle bugs caused by `musl` libc differences when testing Zsh plugins that rely on compiled modules or specific system behaviors.

decisions/0004-dependabot-unification.md

@@ -0,0 +1,68 @@
+# 4. Standardize on Dependabot for Dependency Management
+
+- **Status:** ACCEPTED
+- **Date:** 2026-05-20
+- **Deciders:** ss-o, Gemini CLI
+- **Supersedes:** None
+- **Superseded by:** None
+
+## Context
+
+Managing dependencies across 96+ repositories in the z-shell organization was inconsistent. Repositories were using a mix of:
+
+- **Renovate:** Used in `src` and `z-shell-dot-github`.
+- **Dependabot:** Used in `wiki`, `zd`, `zi`, and others.
+- **Manual updates:** Used in many smaller plugins and annexes.
+
+This fragmentation led to:
+
+- High maintenance overhead (managing multiple tool configurations).
+- Inconsistent update schedules and PR volumes.
+- Increased risk of missing security patches in repositories without automated tracking.
+- Redundant CI noise from competing update tools.
+
+Organization guidelines emphasize better reuse, better verification, and reducing architectural drift.
+
+## Decision
+
+Standardize exclusively on **GitHub native Dependabot** for dependency management across all organization repositories.
+
+1. **Remove Renovate:** Delete all `renovate.json` and `renovate-config.json` files from the workspace.
+2. **Universal Dependabot:** Deploy `dependabot.yml` to every repository in the organization.
+3. **Canonical Schedule:** Align all updates to a weekly schedule (Monday 05:00 UTC for `npm`, 05:30 UTC for `github-actions`).
+4. **Grouped Updates:** Use Dependabot groups (e.g., `github-actions`, `npm` packages) to minimize PR noise.
+5. **Ecosystem Coverage:**
+   - Always track `github-actions` at the root (`/`).
+   - Track `npm` where a `package.json` exists.
+   - Track other ecosystems (Go, Cargo, etc.) only where explicitly required by the repository's source.
+
+## Consequences
+
+### Positive
+
+- **Simplicity:** Dependabot is built into GitHub, requiring no external service or PAT management.
+- **Consistency:** All repositories now follow the same update schedule and grouping logic.
+- **Reduced Noise:** Grouping related updates significantly reduces the number of open PRs.
+- **Security:** Automated security updates are now active across the entire project ecosystem.
+- **Clean Workspace:** Removed Renovate-specific boilerplate and configuration drift.
+
+### Negative / costs
+
+- Loss of some granular configuration features unique to Renovate (e.g., more complex auto-merge rules).
+- One-time effort to migrate and standardize configuration files.
+
+### Neutral
+
+- Dependabot PRs still require manual or automated verification through existing CI workflows.
+
+## Alternatives considered
+
+1. **Standardize on Renovate:** Rejected because Renovate requires more complex configuration and often external hosting/tokens, whereas Dependabot is native to the platform.
+2. **Maintain mixed tools:** Rejected because it perpetuates architectural drift and maintenance overhead.
+3. **No automated updates:** Rejected as it creates a significant security and maintenance backlog.
+
+## References
+
+- `AGENTS.md`
+- `z-shell-dot-github/decisions/0001-meta-repo-and-agents-md.md`
+- `plan/z-shell-llm-management-plan.md`

memory/MEMORY.md

@@ -0,0 +1,7 @@
+# Z-Shell Workspace Memory
+
+- [Wiki Syntax Highlighting PR](project-wiki-highlight-pr.md) — PR #728 is the canonical syntax highlighting PR; PR #729 closed as superseded
+- [Wiki Prism Grammar](project-wiki-prism.md) — z-shell-languages.ts registers zsh/zi/zunit Prism languages with token colors in custom.css
+- [User Profile](user-profile.md) — email: sall@w-ss.io; works on Z-Shell ecosystem (zi plugin manager, wiki, zunit)
+- [No zdharma-continuum](feedback-no-zdharma.md) — never mention, link, or reference zdharma-continuum in any Z-Shell project
+- [Agent file rules](feedback-agent-files.md) — only AGENTS.md at root and .github/ files; never create CLAUDE.md or GEMINI.md at repo root

memory/feedback-agent-files.md

@@ -0,0 +1,21 @@
+---
+name: feedback-agent-files
+description: Which agent instruction files are allowed in Z-Shell repos and where
+metadata: 
+  node_type: memory
+  type: feedback
+  originSessionId: fe8731b7-1077-4aa3-864d-f92ef1951286
+---
+
+Only these agent instruction files are permitted in Z-Shell repos:
+
+- `AGENTS.md` — at repo root
+- Files under `.github/` — e.g. `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md`
+
+**Never create** `CLAUDE.md`, `GEMINI.md`, or any other root-level agent file.
+
+**Why:** User's explicit rule. These files were created by mistake during zsh-eza cleanup and had to be removed.
+
+**How to apply:** When working in any Z-Shell repo, do not create `CLAUDE.md` or `GEMINI.md` at the root. If found, remove them. Keep agent context in `AGENTS.md` or `.github/` only.
+
+Also: never use relative paths like `../../CLAUDE.md` in `AGENTS.md` — those are local workspace paths that break on GitHub. Reference external rules via full GitHub URLs (e.g. `https://github.com/z-shell/.github`).

memory/feedback-no-zdharma.md

@@ -0,0 +1,14 @@
+---
+name: feedback-no-zdharma
+description: "Never reference zdharma-continuum in Z-Shell projects — not in docs, code, links, or commit messages"
+metadata: 
+  node_type: memory
+  type: feedback
+  originSessionId: 9ed562a1-d641-4e02-a61a-787bce3fd736
+---
+
+Never mention, include, or refer to `zdharma-continuum` in any Z-Shell project.
+
+**Why:** Explicit org-level policy from the user.
+
+**How to apply:** When resolving conflicts, editing docs, or writing any content across all Z-Shell repos — if a reference to `zdharma-continuum` appears, remove it or replace it with an appropriate alternative (z-shell/ org repo if one exists, or plain text with no link). Do not "fix" dead links by pointing them at zdharma-continuum. The feature branch approach of removing the link entirely is correct in this case.

memory/project-wiki-highlight-pr.md

@@ -0,0 +1,14 @@
+---
+name: project-wiki-highlight-pr
+description: Wiki syntax highlighting — MERGED 2026-05-19
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: 4d49a48e-3672-4e20-a4d8-771b3a0317e2
+---
+
+PR #728 (`feature-syntax-highlighting`) was squash-merged into `next` on 2026-05-19. Work is complete.
+
+**What landed:** Zsh/Zi/ZUnit Prism grammar (`src/prism/z-shell-languages.ts`), community section restructuring (new `00_contributing/` section), `ecosystem/plugins/zsh_startify.mdx` deleted (violated no-zdharma-continuum policy), `zdharma-continuum` references removed from `06_plugins.mdx`.
+
+**How to apply:** No further action needed for this PR. The `next` branch is up to date.

memory/project-wiki-prism.md

@@ -0,0 +1,21 @@
+---
+name: project-wiki-prism
+description: Prism syntax highlighting implementation for wiki — TypeScript grammar + CSS token palette
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: 4d49a48e-3672-4e20-a4d8-771b3a0317e2
+---
+
+The wiki (Docusaurus 3) has a custom Prism grammar for ZSH, Zi, and ZUnit code blocks.
+
+**Key files:**
+- `src/prism/z-shell-languages.ts` — exports `registerZShellLanguages(Prism)`, defines 3 languages
+- `src/theme/prism-include-languages.ts` — swizzled Docusaurus loader, delegates to original then calls `registerZShellLanguages`
+- `src/css/custom.css` — CSS variables `--site-zsh-builtin-color`, `--site-zi-command-color`, etc. with `:is(code[class*="language-zsh"], ...)` selectors
+
+**Token map:** `zsh-builtin`→teal, `zsh-expansion-flag`→purple, `zsh-special-parameter`→amber, `zsh-glob-qualifier`→magenta, `zi-command`→gold (bold), `zi-ice`→teal-green, `zunit-command`→coral, `zunit-directive`→royal-blue, `zunit-assertion`→emerald.
+
+**Why:** Prism's bash theme colors too many tokens identically — they "blend in". Named CSS variables override per-class colors for both light (GitHub) and dark (Dracula) themes.
+
+**How to apply:** When editing syntax highlighting, use `insertBefore()` with named capture groups (ESLint `prefer-named-capture-group` is enforced — use `(?<lb>...)` not `(...)` for lookbehind groups).

memory/user-profile.md

@@ -0,0 +1,8 @@
+---
+name: user-profile
+description: Who the user is and how to work with them effectively
+metadata:
+  type: user
+---
+
+Email: sall@w-ss.io. Works on the Z-Shell ecosystem — zi plugin manager, wiki, zunit, and related plugins.