feat: docs generator and Docs Sync workflow for docs.piyaz.ai

[FrkAk]

Summary

Task Reference: [PYZ-63] — Set up docs.piyaz.ai

Adds the generator that produces the docs.piyaz.ai reference content from this repo's source of truth, the workflow that keeps the (private) piyaz-docs repo in sync, and the schema extraction that lets the docs generator and the MCP server share one source of truth.

Schema extraction (behavior-preserving)

• Moves the 6 MCP tool input schemas, DESCRIPTIONS, and LIMITS out of create-server.ts / tool-handlers.ts into a standalone lib/mcp/schemas.ts with no data-layer imports, so both the MCP server and the generator consume them. The move is byte-identical — every schema field, .describe() string, and limit verbatim; MCP server runtime unchanged.
• Adds a TOOLS catalog (name / title / description / inputSchema / discriminator) the generator renders from.

Docs generator — scripts/generate-docs.ts (bun run docs:gen)

• Renders the 6 MCP tool pages from the live Zod schemas (z.toJSONSchema): a values table labeled by each tool's discriminator (Actions for action tools, Depths for piyaz_context, Types for piyaz_analyze) plus a parameters table with types, required flags, and descriptions.
• Syncs the 4 Piyaz skill references (conventions / artifacts / lifecycle / resilience) into MDX, fence-aware: prose em/en-dashes are normalized and MDX-hostile < / { are escaped, while fenced code blocks and inline code spans (including indented fences) are left verbatim.
• Builds a skills/agents catalog from plugin frontmatter.
• Emits per-folder meta.json (tools and reference) for sidebar ordering. Frontmatter titles are quoted; --out with no value falls back instead of crashing.

Docs Sync workflow — .github/workflows/docs-sync.yml

• On push to main touching the schema / handler / plugin / generator sources (incl. lib/graph/identifier.ts, which shapes generated tool-param docs), regenerates and opens a PR against the private FrkAk/piyaz-docs repo via DOCS_REPO_TOKEN.
• Hardened for a public runner holding a private-repo write PAT: persist-credentials: false (the token never sits in docs-repo/.git/config while the generator and the third-party action run), token is step-scoped, repo-guarded (if: github.repository == 'FrkAk/piyaz'), and push / workflow_dispatch only (no pull_request_target).

PR template

• Adds a Docs impact section pointing at docs.piyaz.ai.

Type of change

• Bug fix
• New feature
• Refactor / cleanup
• Documentation

Testing

• bun test tests/scripts tests/plugins tests/api passes (142 tests)
• bun run typecheck, bun run lint, and bun run format:check pass
• bun run check:plugins reports in sync
• bun run docs:gen regenerates cleanly; verified output — discriminator-labeled value sections, per-folder meta.json, and fence-aware reference escaping that is a clean no-op on current content (zero entities introduced; indented fences left raw)

Notes for reviewer

• The lib/mcp/schemas.ts extraction is behavior-preserving — verified field-by-field; tests/plugins and tests/api cover the unchanged MCP server.
• docs-sync.yml needs a DOCS_REPO_TOKEN secret (fine-grained PAT: Contents + Pull requests read/write on piyaz-docs) and "Allow GitHub Actions to create pull requests" enabled on piyaz-docs before it can open sync PRs.
• Output is upsert, not full sync: removing a tool or reference leaves a stale page in piyaz-docs to delete by hand (documented in the generator header).
• references/artifacts.md and its three platform mirrors wrap banned-word examples in backticks so generated docs pass the docs style lint (check:plugins stays green). The cleaner fix — exempt generated pages in the docs-repo lint, then revert the backticks — lives in piyaz-docs.

Docs impact

• This PR is the docs tooling. Generated reference (MCP tools, skill references, skills/agents catalog) syncs automatically to docs.piyaz.ai via the Docs Sync workflow.