Source of Truth — learn-gh-helm

Mission

Build a public tutorial site that teaches developers how to use gh-helm, while being built by gh-helm itself. The repo history, project board, issues, and PRs serve as living proof of the tool working.

Tech Stack

• Jekyll static site generator with just-the-docs remote theme
• Hosted on GitHub Pages from the main branch
• All content is Markdown files with Jekyll front matter
• Site URL: https://maxbeizer.github.io/learn-gh-helm/

Content Guidelines

• Each page lives as a .md file in the repo root or docs/ directory
• Every markdown file MUST have Jekyll front matter at the top:

  ---
  layout: default
  title: Page Title
  nav_order: N
  parent: Parent Page (if nested)
  ---
  

• nav_order controls sidebar ordering (1 = Home, 2 = Getting Started, etc.)
• Use clear, friendly tutorial tone — the audience is developers new to gh-helm
• Include real gh helm command examples in fenced code blocks
• Reference the gh-helm repo as maxbeizer/gh-helm
• Do NOT generate HTML — only markdown

Narrative Arc

The site tells a story:

1. The hook — “This site was built by gh-helm” (Home page)
2. The problem — Managing agent-driven development is hard without tooling
3. The solution — gh-helm automates the work and the watching
4. How to use it — Step-by-step setup and usage (Getting Started, Project Agent, Manager Agent)
5. Reference — Configuration details for power users
6. Proof — “Here’s exactly how this site was built” (Meta page)

Each page builds on the previous one. A reader should be able to go top-to-bottom and understand everything.

File Structure

index.md                    # Home page (nav_order: 1)
docs/getting-started.md     # Getting Started (nav_order: 2)
docs/project-agent.md       # Project Agent (nav_order: 3)
docs/manager-agent.md       # Manager Agent (nav_order: 4)
docs/configuration.md       # Configuration Reference (nav_order: 5)
docs/gh-planning.md         # Pairs Well With: gh-planning (nav_order: 6)
docs/how-it-was-built.md    # How This Site Was Built (nav_order: 7)
docs/SOURCE_OF_TRUTH.md     # This file (excluded from nav)
_config.yml                 # Jekyll configuration
helm.toml                   # gh-helm agent configuration

Current Focus

Generate all 7 tutorial pages using gh-helm’s project agent. Each page is filed as an issue on the project board. The agent picks up issues marked “Ready” with the “agent-ready” label, generates the markdown, and opens a draft PR for human review.

Success Metrics

• All 7 pages published and live on GitHub Pages
• Every page was generated by a gh-helm PR (visible in git history)
• A new developer can follow the Getting Started guide and have gh-helm running in under 10 minutes

Risks & Blockers

• AI-generated markdown may need front matter corrections (nav_order, parent)
• Code examples in tutorials need to be accurate and tested
• just-the-docs theme may need configuration tweaks for navigation

Next Up

• After all pages land, add search and cross-page navigation improvements
• Consider adding a “Cookbook” section with common recipes