v1.35.0.0 feat: add /document-generate skill + enhance /document-release with Diataxis coverage map (#1477)

* feat(document-release): add Diataxis coverage map, diagram drift detection, and docs debt tracking

Inspired by @doodlestein's documentation-website skill. Three key ideas incorporated:

1. Step 1.5: Coverage Map (Blast-Radius Analysis) — before editing any docs,
   scan the diff for new public surface and assess documentation coverage across
   Diataxis quadrants (reference/how-to/tutorial/explanation). Flags gaps without
   auto-generating content.

2. Architecture diagram drift detection — extracts entity names from ASCII/Mermaid
   diagrams and cross-references against the diff to catch stale diagrams.

3. Enhanced CHANGELOG sell test — Diataxis rubric scoring (0-3) replaces the
   subjective 'would a user want this?' check.

4. Documentation Debt section in PR body — surfaces coverage gaps and diagram
   drift as actionable items for future work.

All changes are audit-only: the skill flags what's missing, never auto-generates
missing documentation pages. Stays in its lane as a post-ship updater.

Co-Authored-By: Hermes Agent <agent@nousresearch.com>

* feat(document-generate): add Diataxis documentation generation skill

New /document-generate skill, the companion to /document-release. While
/document-release audits and fixes existing docs post-ship, /document-generate
writes missing documentation from scratch using the Diataxis framework.

Inspired by doodlestein documentation-website-for-software-project skill.

Co-Authored-By: Hermes Agent <agent@nousresearch.com>

* chore(docs): regenerate gstack/llms.txt with /document-generate entry

CI's check-freshness step ran gen:skill-docs and found llms.txt stale —
the index wasn't regenerated when /document-generate was added in the
preceding commit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore(docs): regen document-generate/SKILL.md after merging main

Main brought in the Non-ASCII characters directive in the AskUserQuestion
Format resolver (scripts/resolvers/preamble/generate-ask-user-format.ts).
Regenerating document-generate/SKILL.md propagates the new section into
the generated output. check-freshness should now pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(CLAUDE.md): add workflow for fork PRs from garrytan-agents

Fork PRs from non-collaborators don't get base-repo secrets passed to
their CI workflows, so eval/E2E jobs fail with empty-env auth. New
section: when checking out a PR from garrytan-agents, push the branch
to garrytan/gstack and re-target the PR from there.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: sync project docs for v1.35.0.0 + bump VERSION

- README.md: add /document-generate to skills table (Technical Writer
  category) + install-command skill lists
- CLAUDE.md: add document-generate/ to project structure tree
- SKILL.md.tmpl + regenerated SKILL.md: add /document-generate routing
  line ("write docs from scratch")
- VERSION: 1.34.0.0 → 1.35.0.0 (MINOR: new skill + enhancement)

CHANGELOG entry deferred to /ship.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: bump version and changelog (v1.35.0.0)

CHANGELOG entry for the document-generate skill + document-release
Diataxis enhancements. package.json synced to VERSION (drift repair
after merging main which had bumped pkg to 1.34.2.0).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: generate /document-generate Diataxis docs (tutorial + how-to + explanation)

Fills the documentation debt items flagged by /document-release in PR #1477:
critical-gap tutorial coverage and common-gap explanation coverage for the
new /document-generate skill.

Quadrants: tutorial, how-to, explanation (reference already covered by
document-generate/SKILL.md).

- docs/tutorial-document-generate.md (1009 words): newcomer 90-second flow
- docs/howto-document-a-shipped-feature.md (770 words): post-ship audit + fill workflow
- docs/explanation-diataxis-in-gstack.md (1106 words): why Diataxis, trade-offs, alternatives
- README.md: links the three docs from the /document-generate skills-table row

All cross-links verified — every Related section points at an existing file.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Hermes Agent <agent@nousresearch.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## [1.35.0.0] - 2026-05-13
+
+## **Docs become a tracked surface, not an afterthought. `/document-generate` writes them from scratch, `/document-release` audits coverage in four Diataxis quadrants.**
+## **Every PR now ships a coverage map of what got documented vs what shipped. New skill generates tutorials, how-tos, references, and explanations from code. Both speak the same vocabulary, so gaps become visible in the PR body instead of accumulating silently.**
+
+You can now run `/document-generate` to write missing documentation from scratch. The skill reads your code first (the codebase archaeology step is non-skippable), maps the public surface, then writes docs in the four Diataxis quadrants: tutorial (newcomer walkthrough), how-to (task-oriented), reference (factual API description), explanation (design rationale). It runs standalone or chains automatically from `/document-release` when the coverage map finds gaps. `/document-release` got a Step 1.5 coverage map that scores every new entity across the four quadrants. Items with zero coverage show up as critical gaps in the PR body. Items with reference-only coverage show up as common gaps. Architecture diagrams get scanned for entity-name drift against the diff. The CHANGELOG voice check now uses a 0-3 sell-test rubric: 1 point each for "what changed?", "why care?", and "how to use it?". Entries below 2 get rewritten.
+
+A new section in CLAUDE.md documents the fork-PR workflow for `garrytan-agents` PRs: push the branch to `garrytan/gstack` and re-target so eval CI can access secrets. The pattern keeps secret distribution scoped to one branch instead of broadening it to all forks.
+
+### The numbers that matter
+
+Source: this PR's diff against `origin/main` and the new skill template at `document-generate/SKILL.md.tmpl`.
+
+| Surface | Before | After |
+|---------|--------|-------|
+| Doc-generation skills | 1 (`/document-release`) | 2 (`/document-generate` + enhanced `/document-release`) |
+| Diataxis quadrants surfaced in PR body | 0 | 4 (tutorial / how-to / reference / explanation) |
+| `/document-release` workflow steps | 9 | 9 + new Step 1.5 (coverage map) |
+| CHANGELOG voice scoring | gut-check ("would a user think 'oh nice'?") | 0-3 rubric (3 = reference + explanation + how-to all present) |
+| Architecture diagram drift detection | none | scans ARCHITECTURE.md against diff for renamed/removed entities |
+| Doc-debt visibility in PR | none | `### Documentation Debt` subsection with critical + common gaps per Diataxis quadrant |
+
+`/document-generate` is 446 lines of new template producing a 1184-line generated SKILL.md. The Diataxis vocabulary makes "did docs get updated?" a visible answer instead of an implicit one.
+
+### What this means for downstream gstack users
+
+You stop guessing whether your docs are complete. When you ship a new skill, `/document-release` shows you which quadrants you covered and which you skipped, and the gaps land in the PR body where reviewers see them. When you want to bootstrap docs for an existing project, `/document-generate` walks you from zero to four-quadrant coverage in one session. Diataxis becomes the shared vocabulary across `/ship`, `/document-release`, `/document-generate`, and whatever skill comes next that needs to know whether you have a tutorial.
+
+To use: run `/document-release` after `/ship` (or let `/ship` auto-invoke it), see the coverage map in the PR body, then run `/document-generate` if it flags critical gaps.
+
+### Itemized changes
+
+#### Added
+- **`/document-generate` skill** (`document-generate/SKILL.md.tmpl`, 446 lines): Diataxis-based documentation generator with 9-step workflow — scope, codebase archaeology, partition, reference, explanation, how-to, tutorial, cross-linking, quality self-review. Reads the full codebase before writing a single line of docs.
+- **`/document-release` Step 1.5 — Coverage Map**: scans diff for new public surface (skills, CLI flags, config options, API endpoints), classifies each entity by Diataxis quadrant coverage, flags zero-coverage items as critical gaps and reference-only as common gaps. Output feeds the PR body.
+- **`/document-release` Architecture diagram drift detection**: extracts entity names from ASCII/Mermaid blocks in ARCHITECTURE.md, cross-references against the diff, flags renamed/removed entities.
+- **`/document-release` `### Documentation Debt` section in PR body**: surfaces critical gaps, common gaps, and stale diagrams with a one-line description + Diataxis quadrant per item. Suggests adding a `docs-debt` label.
+- **`/document-release` CHANGELOG sell-test rubric**: 0-3 scoring per entry (1 point each for reference / explanation / how-to coverage). Entries below 2 get rewritten.
+- **Skill routing entry**: `/document-generate` added to `SKILL.md` routing rules and `README.md` skills table (Technical Writer category).
+- **CLAUDE.md fork-PR workflow section**: documents how to handle "check out <PR link>" when the PR is from a non-collaborator fork. Push the branch to `garrytan/gstack`, close the fork PR, open a new PR from the base-repo branch. Keeps secret distribution scoped.
+
+#### Changed
+- `/document-release` description and triggers updated to reference the coverage map and `/document-generate` chaining.
+- README.md skills table grouping: `/document-release` and `/document-generate` now appear under the Technical Writer category.
+
+#### For contributors
+- `document-generate/SKILL.md` is generated from `document-generate/SKILL.md.tmpl`. Do not edit the `.md` directly. Run `bun run gen:skill-docs` after template edits.
+- `gstack/llms.txt` now lists `/document-generate` (auto-regenerated from the skill template).
+
 ## [1.34.2.0] - 2026-05-13
 
 ## **Three filed bugs land in one PR. `/codex review`, `/investigate` learnings, and `/sync-gbrain` engine detection all work again.**