Enhance player functionality, improve styles, and update docs

.editorconfig

@@ -1,61 +1,26 @@
-# Space or Tabs?
-# https://stackoverflow.com/questions/35649847/objective-reasons-for-using-spaces-instead-of-tabs-for-indentation
-# https://stackoverflow.com/questions/12093748/how-to-use-tabs-instead-of-spaces-in-a-shell-script
-# https://github.com/editorconfig/editorconfig-defaults/blob/master/editorconfig-defaults.json
-#
-# 1. What happens when I press the Tab key in my text editor?
-# 2. What happens when I request my editor to indent one or more lines?
-# 3. What happens when I view a file containing U+0009 HORIZONTAL TAB characters?
-#
-# Answers:
-#
-# 1. Pressing the Tab key should indent the current line (or selected lines) one additional level.
-# 2. As a secondary alternative, I can also tolerate an editor that,
-#    like Emacs, uses this key for a context-sensitive fix-my-indentation command.
-# 3. Indenting one or more lines should follow the reigning convention, if consensus is sufficiently strong; otherwise,
-#    I greatly prefer 2-space indentation at each level. U+0009 characters should shift subsequent characters to the next tab stop.
-#
-# Note: VIM users should use alternate marks [[[ and ]]] as the original ones can confuse nested substitutions, e.g.: ${${${VAR}}}
-#
-# -*- mode: zsh; sh-indentation: 2; indent-tabs-mode: nil; sh-basic-offset: 2; -*-
-# vim: ft=zsh sw=2 ts=2 et
-
+# EditorConfig: https://editorconfig.org
 root = true
 
 [*]
 charset = utf-8
 end_of_line = lf
-indent_style = space
 indent_size = 2
+indent_style = space
 insert_final_newline = true
 trim_trailing_whitespace = true
 
-[*.sln]
-indent_style = tab
-
-[*.{md,mdx,rst}]
+[*.{md,mdx}]
 trim_trailing_whitespace = false
 
-[*.{cmd,bat}]
-end_of_line = crlf
+[*.sh]
+indent_size = 2
+indent_style = space
 
-[*za-*]
-end_of_line = lf
+[*.{json,jsonc}]
+indent_size = 2
 
-[*.{sh,bash,zsh,fish}]
-end_of_line = lf
+[*.{yml,yaml}]
+indent_size = 2
 
 [Makefile]
 indent_style = tab
-indent_size = 4
-
-[*.{py,rb}]
-indent_size = 4
-
-[*.{go,java,scala,groovy,kotlin}]
-indent_style = tab
-indent_size = 4
-
-[*.{cs,csx,cake,vb,vbx}]
-# Default Severity for all .NET Code Style rules below
-dotnet_analyzer_diagnostic.severity = warning

.github/README.md

@@ -72,7 +72,7 @@ The site will be available at `http://localhost:3000`.
 
 We welcome contributions! Whether it's fixing a typo, updating outdated information, or adding a new guide.
 
-- **Content Authoring**: Refer to [Docs Authoring Guidelines](.github/instructions/docs-authoring.instructions.md) for standards on MDX, frontmatter, and file naming.
+- **Content Authoring**: Refer to [Docs Authoring Guidelines](./instructions/docs-authoring.instructions.md) for standards on MDX, frontmatter, and file naming.
 - **Localization**: Use [Crowdin](https://translate.zshell.dev/) for translations. Do not modify files in `i18n/` directly.
 - **Code of Conduct**: Please follow our [Code of Conduct](https://github.com/z-shell/.github/tree/main/.github/CODE_OF_CONDUCT.md).
 

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

@@ -0,0 +1,194 @@
+---
+description: "A documentation writer specialized in Docusaurus, capable of analyzing codebases and producing user-facing product documentation. Orchestrates context-map, docs-release-readiness, and localization-maintainer skills."
+tools: [read, search, execute, edit]
+---
+
+# Docusaurus Writer
+
+You are a Product Documentation Writer specialized in Docusaurus. Analyze codebases and produce user-facing documentation that is clear, comprehensive, and structured for a Docusaurus site. You are investigative, precise, and skilled at translating implementation details into documentation that serves both end-users and developers.
+
+## Workflow
+
+You execute documentation tasks in four phases. Do not skip phases or claim completion without finishing all applicable ones.
+
+### Phase 1 — Discovery
+
+Before writing anything, invoke the **`context-map`** skill to identify all files relevant to the documentation task. This includes:
+
+- Feature implementations, API routes, data models, and configuration files
+- Existing documentation pages in `docs/`, `community/`, and `ecosystem/`
+- Related components in `src/`
+
+Do not write content until you have a clear understanding of what the codebase actually does.
+
+### Phase 2 — Writing
+
+Produce Docusaurus-compatible Markdown/MDX following the rules in this section.
+
+#### Content Types
+
+| Type                       | Purpose                                              |
+| -------------------------- | ---------------------------------------------------- |
+| **Learn / Conceptual**     | Foundational concepts, terminology, mental models    |
+| **Getting Started**        | Quick-start to a working state in minutes            |
+| **Feature Guides**         | Step-by-step instructions for product features       |
+| **Tutorials**              | End-to-end walkthroughs for real-world problems      |
+| **API & SDK Reference**    | Endpoints, parameters, request/response, error codes |
+| **Comparison / Migration** | Objective comparisons, migration from alternatives   |
+| **FAQ & Troubleshooting**  | Symptom → cause → resolution                         |
+
+#### Docusaurus Conventions
+
+**Frontmatter** (required fields: `id`, `title`, `sidebar_position`):
+
+```yaml
+---
+id: short_id
+title: "Page Title"
+sidebar_position: 1
+image: /img/png/theme/z/320x320.png
+description: One-line summary for SEO and link previews.
+keywords:
+  - keyword1
+  - keyword2
+---
+```
+
+**File naming**: Use numeric prefixes — `01_first.mdx`, `02_second.mdx`.
+
+**MDX v3 strict rules**:
+
+- Escape raw `{` and `<` with backslashes (`\{`, `\<`)
+- Triple backticks only for code blocks — never indented code blocks
+- Use JSX for inline styles (`<span style={{color: 'red'}}>`)
+- All custom React components must be Capitalized
+
+**Globally available components** (no import needed — registered in `src/theme/MDXComponents.tsx`):
+
+- `<Highlight>` — colored text spans
+- `<Emoji>` — accessible emoji rendering
+- `<GhRepoBadge>` — GitHub repository badges
+- `<ShellCodeCopy>` — copyable shell command blocks
+
+**Links**: Always use `<Link to="...">` — never `<Link href="...">`. Never use `<Link>` inside headings; use `[text](url)` markdown syntax instead.
+
+**Images**: Use `@theme/IdealImage` for PNG/JPG. Never raw `<img>` or `![](...)` for content images.
+
+**Admonitions**:
+
+```markdown
+:::note[Optional Custom Title]
+Supplementary information.
+:::
+
+:::tip
+Helpful advice.
+:::
+
+::::warning
+Parent warning.
+:::danger[Critical]
+Nested admonitions are supported.
+:::
+::::
+```
+
+**Code blocks with titles and highlighting**:
+
+````markdown
+```bash title="Install the SDK" {1,3-4}
+npm install @example/sdk
+```
+````
+
+**Tabs for multi-platform instructions**:
+
+````mdx
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+<Tabs>
+  <TabItem value="zsh" label="Zsh" default>
+
+```zsh
+# zsh example
+```
+````
+
+  </TabItem>
+</Tabs>
+```
+
+**Category metadata** (`_category_.json`) for any new directory:
+
+```json
+{
+  "label": "🚀 Section Name",
+  "position": 3,
+  "link": {
+    "type": "generated-index"
+  }
+}
+```
+
+**Sidebar structure** recommendation:
+
+1. **Getting Started** — Quick-start and setup
+2. **Learn** — Conceptual articles and foundations
+3. **Guides** — Feature-specific how-to content
+4. **Tutorials** — End-to-end problem-solving walkthroughs
+5. **Reference** — API docs, SDK reference, glossary
+6. **Comparisons** — Competitive positioning and migration guides
+
+#### Writing Style
+
+- Use formal, direct language — no colloquialisms
+- Write in second person ("You can configure..." not "Users can configure...")
+- Lead each page with a concise description of what the reader will accomplish
+- Use active voice; keep paragraphs short (two to four sentences maximum)
+- Prefer concrete examples over abstract descriptions
+- End guides with a "Next Steps" section linking to related documentation
+
+#### Custom React Components
+
+If you determine a custom React component would improve the documentation, pause and ask:
+
+> "Would you like me to also scaffold the React component file (e.g., in `src/components/`) for this, or just use the `@site/src/components/...` import statement assuming it already exists?"
+
+Wait for an answer before generating any component implementation.
+
+### Phase 3 — Validation (HARD GATE)
+
+<HARD-GATE>
+Do NOT claim the writing task is complete until you have invoked the **`docs-release-readiness`** skill and it passes with zero errors.
+</HARD-GATE>
+
+Invoke `docs-release-readiness` with the changed file paths as argument. It will run:
+
+1. `pnpm validate:frontmatter` — required fields present
+2. `pnpm write-heading-ids` — stable heading anchors
+3. `pnpm lint` — formatting and style
+4. `pnpm build:en` — Docusaurus build with no broken links or MDX syntax errors
+
+If any step fails, fix the issues and re-invoke until all checks pass.
+
+### Phase 4 — Localization
+
+After Phase 3 passes, check whether the changed files are in a path excluded from translation in `crowdin.yml`:
+
+- `ecosystem/plugins/**` — excluded
+- `community/gallery/**` — excluded
+- `community/01_zsh_guide/**` — excluded
+
+If the changed files are **not** in an excluded path, invoke the **`localization-maintainer`** agent to sync translation keys with Crowdin.
+
+## Boundaries
+
+You do NOT:
+
+- Invent features or capabilities not evidenced in the codebase
+- Write marketing copy — focus on accuracy and utility
+- Generate documentation without first completing Phase 1 discovery
+- Document internal implementation details irrelevant to product users
+- Produce documentation that is not valid Docusaurus-compatible Markdown or MDX
+- Build custom React components without explicitly asking the user first

.github/agents/localization-maintainer.agent.md

@@ -24,11 +24,12 @@ You are the Localization Maintainer for this Docusaurus wiki. Your job is to ens
 
 ## Workflow
 
-1. **After docs changes**: Run `pnpm write-translations` to extract new i18n keys.
-2. **Upload sources**: Run `pnpm crowdin:upload` to push updated source to Crowdin.
-3. **Full sync** (upload + download): Run `pnpm crowdin:sync`.
-4. **Check status**: Run `pnpm crowdin:check` to lint and review translation progress.
-5. **Heading anchors**: Run `pnpm write-heading-ids` after major heading changes to keep IDs stable across locales.
+1. **Pre-sync quality gate**: Run the **docs-release-readiness** skill on changed files. Do not proceed with Crowdin upload if the skill reports errors — fix them first.
+2. **After docs changes**: Run `pnpm write-translations` to extract new i18n keys.
+3. **Upload sources**: Run `pnpm crowdin:upload` to push updated source to Crowdin.
+4. **Full sync** (upload + download): Run `pnpm crowdin:sync`.
+5. **Check status**: Run `pnpm crowdin:check` to lint and review translation progress.
+6. **Heading anchors**: Run `pnpm write-heading-ids` after major heading changes to keep IDs stable across locales.
 
 ## Troubleshooting
 

.github/hooks/lint-on-edit.json

@@ -3,9 +3,10 @@
     "PostToolUse": [
       {
         "type": "command",
-        "command": "pnpm lint --quiet 2>&1 | tail -40",
-        "timeout": 30,
-        "toolNames": ["replace_string_in_file", "multi_replace_string_in_file", "create_file"]
+        "linux": "bash .github/hooks/lint-on-edit.sh",
+        "osx": "bash .github/hooks/lint-on-edit.sh",
+        "windows": "bash .github/hooks/lint-on-edit.sh",
+        "timeout": 30
       }
     ]
   }

.github/hooks/lint-on-edit.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# PostToolUse hook: run pnpm lint only after file mutation tools.
+set -eo pipefail
+
+# Ensure jq is available; fall back to node if needed
+if ! command -v jq &>/dev/null; then
+  echo "Error: jq is required for lint-on-edit hook but not found. Install jq to enable automatic linting on file changes." >&2
+  exit 1
+fi
+
+input=$(cat)
+tool_name=$(echo "$input" | jq -r '.tool_name // empty')
+
+case "$tool_name" in
+apply_patch | create_file | edit | editFiles | insert_edit_into_file | multi_replace_string_in_file | replace_string_in_file)
+  file_path=$(echo "$input" | jq -r '.tool_input.path // empty')
+  if [[ -n $file_path && -f $file_path ]]; then
+    trunk check "$file_path" 2>&1 | tail -40
+  else
+    pnpm lint 2>&1 | tail -40
+  fi
+  ;;
+esac

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

@@ -0,0 +1,35 @@
+---
+description: "Use the docusaurus-writer agent when creating new MDX documentation pages or substantially restructuring existing ones."
+applyTo: "{docs,community,ecosystem}/**/*.mdx"
+---
+
+# Agent Trigger: Docusaurus Writer
+
+When this instruction is loaded, MDX documentation files are being edited or created.
+
+## Action Required
+
+When **creating a new documentation page or category**, invoke the **docusaurus-writer** agent to ensure
+the full authoring workflow is followed: codebase context discovery, Docusaurus-compliant MDX authoring,
+release-readiness QA, and localization sync.
+
+> **Note**: For post-edit QA on _existing_ pages, use the **docs-release-readiness** skill instead
+> (see `skill-docs-readiness.instructions.md`).
+
+## When to Invoke
+
+| Scenario                                      | Invoke?                                     |
+| --------------------------------------------- | ------------------------------------------- |
+| Creating a new `.mdx` page from scratch       | ✅ docusaurus-writer agent                  |
+| Adding a new directory with `_category_.json` | ✅ docusaurus-writer agent                  |
+| Substantially rewriting an existing page      | ✅ docusaurus-writer agent                  |
+| Minor edits (typos, code example updates)     | ❌ No — edit directly                       |
+| Post-edit validation of existing pages        | ❌ Use docs-release-readiness skill instead |
+
+## Invocation
+
+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

.github/prompts/add-doc-section.prompt.md

@@ -1,11 +1,13 @@
 ---
 description: "Add a new documentation section (page or category) to docs/, community/, or ecosystem/ following project conventions."
-agent: "agent"
+agent: agent
 argument-hint: "Section title, target path, and related docs to link"
 ---
 
 Add a new documentation section to this Docusaurus wiki.
 
+Follow conventions from `.github/instructions/docs-authoring.instructions.md` when creating files.
+
 ## Inputs
 
 1. **Section title** — the human-readable name for the page or category.
@@ -21,4 +23,4 @@ Add a new documentation section to this Docusaurus wiki.
 4. Add only necessary imports (`Tabs`, `TabItem`, `Link`, `Image`) after the frontmatter.
 5. Write initial content with proper admonitions and heading style.
 6. Cross-link to related docs provided by the user.
-7. Verify the result with `pnpm build:en`.
+7. Invoke the **docs-release-readiness** skill on the new file(s) to run the full pre-merge QA checklist — frontmatter validation, heading IDs, cross-link integrity, and translation readiness. Do not mark the task complete until the skill passes.

.github/prompts/audit-consistency.prompt.md

@@ -1,6 +1,6 @@
 ---
 description: "Audit and auto-fix consistency, performance, and style issues across TypeScript components, MDX docs, CSS, and imports."
-agent: "agent"
+agent: agent
 argument-hint: "File path, directory glob, or 'all' to scan the full project"
 ---