docs site: user-friendly mdBook at journal.eamann.com (Catppuccin Latte) + warmer prose

[claude]

🤖 Agent-Generated PR

Closes #34
Agent Used: Claude Code
Complexity: high

---

Summary

Adds a user-facing documentation site at https://journal.eamann.com built with mdBook and styled with Catppuccin Latte. The existing docs/ tree is untouched — this is an additive layer written for a non-technical audience.

• Warm, second-person prose across 14 chapters covering install, capture, search, synthesis, meetings, configuration, and integrations
• Catppuccin v4.0.0 vendored (all four flavors; Latte as default, Mocha as preferred dark)
• book/src/CNAME carries journal.eamann.com into the built artifact
• README gets a docs site badge and link

Implementation Notes

• default-theme = "latte" matches the Catppuccin v4 CSS class names (.latte { … })
• preferred-dark-scheme = "mocha" is the correct mdBook key (vs preferred-dark-theme which is silently ignored)
• [preprocessor.linkcheck] with warning-policy = "error" and follow-web-links = false validates internal links without making network calls
• The footer external-URL SUMMARY link was removed — mdBook v0.4.40 creates a stub file for external URLs in that position

⚠️ Workflow file — maintainer action required

The GitHub App token does not have workflows write permission, so .github/workflows/docs.yml could not be committed directly. Please add the file below to complete the deployment pipeline, then merge.

.github/workflows/docs.yml — click to expand

name: Docs

on:
  push:
    branches: [main]
    paths:
      - "book/**"
      - ".github/workflows/docs.yml"
  pull_request:
    branches: [main]
    paths:
      - "book/**"
      - ".github/workflows/docs.yml"

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
  MDBOOK_VERSION: "0.4.40"
  MDBOOK_LINKCHECK_VERSION: "0.7.7"

jobs:
  build:
    name: build docs
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install mdBook
        run: |
          url="https://github.com/rust-lang/mdBook/releases/download/v${MDBOOK_VERSION}/mdbook-v${MDBOOK_VERSION}-x86_64-unknown-linux-gnu.tar.gz"
          curl -sSL "$url" | tar xz
          mv mdbook /usr/local/bin/

      - name: Install mdbook-linkcheck
        run: |
          url="https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases/download/v${MDBOOK_LINKCHECK_VERSION}/mdbook-linkcheck.x86_64-unknown-linux-gnu.zip"
          curl -sSL "$url" -o linkcheck.zip
          unzip -q linkcheck.zip -d /tmp/linkcheck
          mv /tmp/linkcheck/mdbook-linkcheck /usr/local/bin/
          chmod +x /usr/local/bin/mdbook-linkcheck

      - name: Build
        run: mdbook build book/

      - name: Upload artifact
        if: github.ref == 'refs/heads/main'
        uses: actions/upload-pages-artifact@v3
        with:
          path: book/book/

  deploy:
    name: deploy to Pages
    if: github.ref == 'refs/heads/main'
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Changes

• book/book.toml — mdBook config (Catppuccin Latte default, linkcheck)
• book/src/SUMMARY.md — 14-chapter IA
• book/src/CNAME — journal.eamann.com
• book/src/*.md + book/src/integrations/*.md — all chapter pages
• book/theme/catppuccin.css — vendored Catppuccin v4.0.0
• book/theme/index.hbs — custom template for Catppuccin theme class support
• .gitignore — add book/book/
• README.md — docs site badge + link

Testing

Automated:

• mdbook build book/ exits 0 (verified locally)
• make vet and make fmt exit 0 (no Go changes)
• CI linkcheck (runs when workflow file is added)
• Pages deploy (requires maintainer steps below)

Manual testing performed:

• Built locally with mdBook v0.4.40 — clean build, correct CNAME in output, Catppuccin CSS referenced

Maintainer steps to go live

1. Add the workflow file from the collapsible above at .github/workflows/docs.yml
2. Enable GitHub Pages in repo Settings → Pages → Source: GitHub Actions
3. Create the github-pages environment in Settings → Environments (if not already present)
4. Add the Cloudflare CNAME journal.eamann.com → ericmann.github.io

---

Review Checklist

Correctness

• Code actually solves the issue
• Acceptance criteria are met (pending workflow + DNS)
• Existing docs/ tree unchanged

Code Quality

• Follows existing codebase patterns (pinned action versions, FORCE_JAVASCRIPT_ACTIONS_TO_NODE24)
• Warm, accessible second-person prose throughout
• No unnecessary complexity

Security

• No secrets or credentials
• No cloud dependency added for search/retrieval

Tests

• make test unaffected (no Go changes)
• mdBook build clean

[claude]

Retro: no durable lesson (merged clean / one-off).