feat(docs): add syntax highlighting + restructure community contributing section

.github/copilot-instructions.md

@@ -0,0 +1 @@
+../AGENTS.md

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

@@ -87,6 +87,21 @@ Only import what is used on the page.
 - Heading IDs are managed by `pnpm write-heading-ids`; add explicit `{#custom-id}` only when needed.
 - For HTML elements in MDX (`<kbd>`, `<details>`, `<samp>`, `<dl>`, etc.), refer to the [GitHub Flavored Markdown spec](https://github.github.com/gfm/#raw-html) for supported tags.
 
+## Code Blocks
+
+Always choose the most specific accurate fence language so examples receive the
+right highlighting:
+
+- `zsh` — generic Zsh syntax and shell snippets
+- `zi` — Zi commands, ice modifiers, and Zi-oriented examples
+- `zunit` — ZUnit test files and ZUnit CLI examples
+- `sh` — portable POSIX shell
+- `bash` — Bash-specific syntax
+- `yaml`, `json`, `diff`, etc. — non-shell formats
+
+Do not use `shell` when the snippet is specifically Zsh, Zi, ZUnit, Bash, or
+POSIX `sh`; reserve it for genuinely shell-agnostic examples.
+
 ## Localization Awareness
 
 - Edit only English source files in `docs/`, `community/`, `ecosystem/`.

.github/workflows/ci-perf.yml

@@ -59,7 +59,7 @@ jobs:
       - uses: preactjs/compressed-size-action@v3
         with:
           install-script: pnpm i --frozen-lockfile
-          build-script: "pnpm build:en"
+          build-script: "build:en"
           pattern: "{build/assets/js/*.js,build/assets/css/*.css,build/**/*.html,.docusaurus/globalData.json,build/blog/**/swiss-army-knife-for-zsh/*}"
           exclude: "{./build/manifest.json,./build/**/*.xml,**/*.map,**/node_modules/**,build/assets/**/*.ttf}"
           strip-hash: '\.([^;]\w{7})\.'

.trunk/configs/.lychee.toml

@@ -115,6 +115,9 @@ exclude = [
 
   # Asciinema (embeds, not navigational links)
   'https://asciinema\.org',
+
+  # Archived/removed z-shell repositories that are referenced in docs for historical context
+  'https://github\.com/z-shell/zsh-startify',
 ]
 
 # Exclude paths from being checked (regex patterns)

AGENTS.md

@@ -0,0 +1,74 @@
+# Project Guidelines
+
+## Build, Lint, and Dev Commands
+
+- Use Node >= 20 and pnpm >= 10 (see `engines` in `package.json`).
+- Install dependencies with `pnpm install`.
+- `pnpm start` — local dev server at `http://localhost:3000`.
+- `pnpm build` — full production build (run before finishing substantial changes).
+- `pnpm build:en` — English-only build, faster for docs-only checks.
+- `pnpm serve` — serve the production build locally for verification.
+- `pnpm clear` — clear Docusaurus cache; use when the site behaves inconsistently after config or theme changes.
+- `pnpm lint` — Unified linting with Trunk (configs in `.trunk/configs/`). Fix with `pnpm lint:fix`.
+- `pnpm write-heading-ids` — regenerate heading IDs across all docs.
+- Trunk CI runs pre-commit formatting and pre-push linting (config: `.trunk/trunk.yaml`).
+
+## 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)
+- 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.
+- Custom MDX components are globally available via `src/theme/MDXComponents.tsx` — no import needed in `.mdx` files:
+  - `<Highlight>` — colored text spans
+  - `<Emoji>` — accessible emoji rendering
+  - `<GhRepoBadge>` — GitHub repository badges
+  - `<ShellCodeCopy>` — copyable shell command blocks
+- Localization uses Crowdin (`crowdin.yml`). Never edit files under `i18n/` directly.
+
+## Conventions
+
+### Documentation (MDX)
+
+- Numeric file prefixes control sidebar order: `01_first.mdx`, `02_second.mdx`.
+- Page structure: frontmatter → imports → content. Required frontmatter: `id`, `title`, `sidebar_position`.
+- Create `_category_.json` when adding new directories.
+- Use admonitions (`:::tip`, `:::info`, `:::warning`) for callouts.
+- Only edit English source files. Use `pnpm crowdin:sync` for localization.
+- Detailed patterns: `.github/instructions/docs-authoring.instructions.md`.
+
+### TypeScript / React
+
+- Use `type` declarations for props (not `interface`).
+- One default function component export per file.
+- Destructure props in the function signature; return type `React.JSX.Element`.
+- Import order enforced by ESLint: builtins → external (`react`, `clsx`) → internal (`@theme/*`, `@site/*`) → relative → types → styles.
+- Detailed patterns: `.github/instructions/frontend-components.instructions.md`.
+
+### CSS
+
+- Prefer CSS Modules (`.module.css`) co-located with the component.
+- Global overrides go in `src/css/custom.css`.
+- Colors must use HSL format (enforced by Stylelint).
+- Support both light and dark themes via `[data-theme]` selectors.
+
+### Formatting
+
+- Prettier: double quotes, semicolons, 2-space indent, 120 char print width, trailing commas (config: `.prettierrc.json`).
+- EditorConfig: UTF-8, spaces, final newline, trim trailing whitespace (except `.md`/`.mdx`).
+
+### Branching
+
+- `next` — active development. `main` — production.
+- Branch naming: `feature-<id>`, `bug-<id>`, `hotfix-<id>`.
+- Hotfixes branch from `main`; everything else from `next`.
+
+## Agent Notes
+
+- Prefer small, scoped edits that match surrounding MDX and TypeScript style.
+- Link to existing docs rather than duplicating long guidance.
+- Scoped instruction files in `.github/instructions/` are auto-applied by file glob — prefer updating those for domain-specific guidance over modifying this file.
+- Do not introduce new global instruction files (e.g., `AGENTS.md`) unless explicitly requested.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

GEMINI.md

@@ -0,0 +1 @@
+AGENTS.md

community/00_contributing/01_getting_started.mdx

@@ -0,0 +1,133 @@
+---
+id: getting_started
+title: "🚀 Getting Started"
+sidebar_position: 1
+image: /img/png/theme/z/320x320.png
+description: General contributor setup — branch model, commit conventions, and pull request workflow for all Z-Shell repositories.
+keywords:
+  - contributing
+  - getting-started
+  - branch-model
+  - conventional-commits
+  - pull-request
+---
+
+{/* @format */}
+
+import useBaseUrl from "@docusaurus/useBaseUrl";
+
+<div style={{float: "right", marginLeft: "1.5rem", marginBottom: "1rem"}}>
+  <img src={useBaseUrl("/img/svg/community/contributing-getting-started.svg")} alt="" width="100" height="100" style={{borderRadius: "16px"}}/>
+</div>
+
+This guide applies to **all repositories** in the Z-Shell organization. Repo-specific additions (zi, wiki, etc.) are documented in their own sub-pages.
+
+## Prerequisites
+
+- [Git](https://git-scm.com/) ≥ 2.30
+- [Zsh](https://www.zsh.org/) ≥ 5.8
+- A [GitHub](https://github.com) account
+
+## Fork and Clone
+
+```shell
+# 1. Fork the repo on GitHub, then clone your fork
+git clone https://github.com/<your-username>/<repo>.git
+cd <repo>
+
+# 2. Add the upstream remote
+git remote add upstream https://github.com/z-shell/<repo>.git
+```
+
+## Branch Model
+
+All repositories follow the same two-branch model:
+
+```text
+main  ←─── production (tagged releases only)
+  ↑
+next  ←─── integration branch  ← open all PRs here
+  ↑
+  ├── feat/<name>      new features
+  ├── fix/<name>       bug fixes
+  ├── perf/<name>      performance improvements
+  ├── refactor/<name>  code refactors
+  ├── docs/<name>      documentation updates
+  └── ci/<name>        CI / workflow changes
+```
+
+**Rules:**
+
+1. **Always branch from `next`**: `git checkout -b fix/my-issue next`
+2. **Open PRs targeting `next`** — never target `main` directly
+3. `next` → `main` happens via a release PR once `next` is stable
+4. **Hotfixes** are the only exception — branch from `main` and open a PR against `main`
+
+## Commit Message Format
+
+All commits must follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```text
+type(scope): short description
+
+Optional body — explain what and why, not how.
+Wrap at 72 characters.
+
+Optional footer(s):
+Fixes #123
+BREAKING CHANGE: description of what breaks
+```
+
+### Allowed Types
+
+| Type | Purpose |
+| --- | --- |
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `perf` | Performance improvement |
+| `refactor` | Code restructure, no behavior change |
+| `docs` | Documentation only |
+| `test` | Test additions or corrections |
+| `ci` | CI/CD pipeline changes |
+| `chore` | Routine maintenance |
+| `revert` | Revert a previous commit |
+
+### Rules
+
+- Subject line: imperative mood, ≤ 72 characters, no trailing period
+- Breaking changes: use `!` suffix (`feat!:`) **and** add a `BREAKING CHANGE:` footer
+- **Do not add `Co-authored-by` trailers** — this is enforced by CI
+
+To tidy commits before opening a PR:
+
+```shell
+git rebase -i $(git merge-base HEAD next)
+```
+
+## What Not to Add
+
+- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, or any AI-specific config files
+- Secrets, credentials, or API tokens of any kind
+- Binary files unrelated to the project
+
+## Pull Request Checklist
+
+Before opening a PR:
+
+- [ ] Branched from `next` (or `main` for a hotfix)
+- [ ] PR targets `next`
+- [ ] Commits follow Conventional Commits
+- [ ] No secrets or AI config files added
+- [ ] Relevant docs or tests updated
+- [ ] All CI checks pass
+
+## Keeping Your Fork Up to Date
+
+```shell
+git fetch upstream
+git rebase upstream/next  # for feature branches
+```
+
+## Discussion First
+
+Before starting significant work, [open an issue](https://github.com/z-shell/zi/issues/new/choose) to discuss the change. This avoids duplicated effort and ensures alignment with the project roadmap.