docs(zsh-lint): update the guide for v1.6.0 and the MCP server

[ss-o]

Summary

Closes #946.

The Zsh Lint guide described v1.3.0 and Go 1.25. This updates it for the published v1.6.0, whose module requires Go 1.27, and documents the new zsh-lint mcp subcommand. The generated rule reference (08_rule_reference.mdx) is unchanged here; it was updated to v1.6.0 by #947.

• Install commands for zsh-lint and zsh-lint-survey, the CI example and every version statement use v1.6.0. The Go requirement and the CI example's go-version are 1.27. The historical notes that project configuration needs v1.3.0 or newer are kept.
• -h and --help are documented in Getting started, CI and JSON, and Troubleshooting: they print usage to standard output and exit 0 for zsh-lint and zsh-lint mcp, while other usage errors still exit 2.
• Getting started, Project configuration and Rules and suppressions now say that quoting/unquoted-var reports only for sources under a project configuration, at Info severity, so such a finding alone leaves the exit status at 0.
• Parser survey shows the survey's actual output format.
• New page 09_mcp_server.mdx, linked from the guide index and from Getting started, covers starting the stdio server and how a client launches it (command zsh-lint, arguments ["mcp"]). It documents the two tools with their arguments, results and errors, the --zsh startup option, and the limits of the native checks. It adds no client-specific configuration format.

Verification

Verified commit: 5a4b084e05d73b7002dd78d3b76280f918c96afe, based on main at 4187d03d162c2fa6b1469d9f692df42655dafad2.

• Every statement was checked against the v1.6.0 source (README.md, docs/project/output-contract.md, cmd/zsh-lint and the rule doc comments) and against binaries installed with go install ...@v1.6.0. With those binaries: --help exits 0 on standard output; print -r -- $name on line 4 of a configured plugin source reports hello.zsh:4:13: [quoting/unquoted-var] Variable expansion should be double-quoted at Info with exit 0, and nothing without configuration; the JSON envelope matches the example's fields; the survey prints OK <file> lines and 2 file(s) surveyed, 2 ok, 0 failed.
• Passed: node scripts/validate-frontmatter.mjs, node scripts/validate-code-fences.mjs, no-fix Trunk on the changed pages, and git diff --check.
• Not run locally: a full Docusaurus build. The Cloudflare Pages preview build on this pull request compiles the pages.

[cloudflare-workers-and-pages]

Deploying zsh with    Cloudflare Pages

Latest commit:	5a4b084
Status:	✅  Deploy successful!
Preview URL:	https://5f0c1fdb.zsh.pages.dev
Branch Preview URL:	https://docs-zsh-lint-guide-v1-6-0.zsh.pages.dev

View logs

[ss-o]

Fallback review under ADR-0026: Copilot request not registered on 5a4b084

Sole-maintainer exception

The maintainer elected the ADR-0035 sole-maintainer exception for this pull request at head 5a4b084. No second human reviewer is available, and the configured Copilot request on this head did not register (requested 2026-10-19T19:50:51Z, no review_requested event for Copilot; cause unconfirmed). A new head voids this election and this review.

Findings

No actionable findings.

Scope: the complete diff from main at 4187d03 to 5a4b084: community/04_zsh_lint/index.mdx, the guide pages 01 to 07, and the new 09_mcp_server.mdx, against the acceptance criteria of #946.

Note

This fallback review and the exact-head review below are not a human review or an approval to merge.

Exact-head read-only review

A read-only exact-head review of this commit, in its own reviewing session using the organization code-review checklist, reported no actionable findings. Its evidence:

• CLI and help statements match cmd/zsh-lint/main.go and mcp.go at v1.6.0; --help and mcp --help were run with the installed v1.6.0 binaries.
• The quoting/unquoted-var statements (project configuration only, Info severity, exit status 0) match internal/rules/unquoted_var.go and a binary run with and without --no-config. Go 1.27 matches go.mod.
• The MCP page matches docs/project/output-contract.md and mcp.go: two tools, their arguments and results, isError handling with partial envelopes, --zsh, zsh -f -n and zcompile -U -R, the empty-stderr validity rule, and the native-check limits. Its statements were also exercised over stdio.
• Example outputs (hello.zsh:4:13, the survey's OK lines and summary, the zsh_syntax JSON shape) match the binaries' output.
• Frontmatter, sidebar positions (09_mcp_server.mdx is 10, after the rule reference at 9), relative links, the index Card target and icon, and code-fence languages are valid. validate-frontmatter.mjs, validate-code-fences.mjs and its tests pass. The diff has no em dash.
• Unavailable there: a full Docusaurus build, because that read-only session had no installed dependencies.

Validation

• Passed on the head: all 12 pull-request checks, including Branch Name, Issue Link, PR Title, Commits, Trunk Code Quality, CodeQL, Org Routing, Validate Corpus and the Cloudflare Pages preview build.
• Reproduced for this review: the preview deployment serves the new page at /community/zsh_lint/zsh-lint-mcp-server with its MCP server heading and tool sections, and Getting started shows v1.6.0. The examples were re-run with binaries installed by go install ...@v1.6.0.

Checklist verdicts and supporting evidence

• Accuracy: pass. Every changed statement traces to the v1.6.0 README, output contract, command source or rule doc comments, or to a binary run.
• Scope: pass. Only the guide pages under community/04_zsh_lint/ changed; the generated rule reference, configuration and other content roots are untouched.
• Rendering and navigation: pass. The preview build compiled every page, the new page is reachable from the index Card and from Getting started, and its sidebar position follows the rule reference.
• Security and trust boundaries: pass. The MCP page states that native checks run the system zshenv, are not a sandbox for hostile source, and need trusted inputs, Zsh executable and startup configuration, consistent with the README.
• Traceability: pass. The body closes #946, whose criteria are the version, Go requirement, MCP documentation and changed-behaviour corrections.

Limits and recovery

• Unavailable: a full local Docusaurus build. The Cloudflare Pages preview build on this head is the build evidence.
• Recovery: if a deployed page is wrong after merge, revert the squash commit on main; the previous guide text returns with the next deployment.