hd-garden 0.7.0 → 0.8.0

package/docs/handbook/en/deploy.md

@@ -0,0 +1,273 @@
+---
+title: Deploy to GitHub Pages
+navTitle: Deploy to GitHub Pages
+description: Configure a GitHub Actions workflow that supports either a single public repository or a private source repo paired with a public Pages repo.
+section: getting-started
+order: 4
+---
+
+`npx hd-garden init` does not create `.github/workflows/pages.yml` automatically. Add this file to your site repository when you are ready to publish to GitHub Pages. The same workflow supports both a **single public repository** and a **private source repository + public Pages repository**, switching automatically based on whether the `PAGES_REPOSITORY` variable is set.
+
+The workflow below matches Garden's own `.github/workflows/pages.yml` with two adjustments for a site repo: it omits `paths-ignore`, `npm run lint`, and `npm test` (which only apply to the engine repo), and its `publish-repository` job installs dependencies before running `npx garden pages:prepare static-site pages-repository` (the same `scripts/prepare-pages-output.mjs` script Garden calls directly). Commit `package-lock.json` after your first `npm install` so `npm ci` can run in CI.
+
+The `build` job runs only when the repository is named `<owner>.github.io`, or when the `SITE_URL` or `PAGES_REPOSITORY` variable is set.
+
+## 1. Full `.github/workflows/pages.yml` Workflow
+
+Create `.github/workflows/pages.yml` in your site repository:
+
+```yaml
+name: Verify and publish blog
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish-blog
+  cancel-in-progress: true
+
+jobs:
+  build:
+    if: github.event.repository.name == format('{0}.github.io', github.repository_owner) || vars.SITE_URL != '' || vars.PAGES_REPOSITORY != ''
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
+
+      - run: npm ci
+
+      - name: Resolve the public URL
+        env:
+          SITE_URL_OVERRIDE: ${{ vars.SITE_URL }}
+          ADMIN_URL_OVERRIDE: ${{ vars.ADMIN_URL }}
+          GISCUS_REPO: ${{ vars.GISCUS_REPO }}
+          GISCUS_REPO_ID: ${{ vars.GISCUS_REPO_ID }}
+          GISCUS_CATEGORY: ${{ vars.GISCUS_CATEGORY }}
+          GISCUS_CATEGORY_ID: ${{ vars.GISCUS_CATEGORY_ID }}
+          GISCUS_DISABLED: ${{ vars.GISCUS_DISABLED }}
+          WEBMENTION_IO_DOMAIN: ${{ vars.WEBMENTION_IO_DOMAIN }}
+          ANALYTICS_DOMAIN: ${{ vars.ANALYTICS_DOMAIN }}
+          ANALYTICS_SCRIPT: ${{ vars.ANALYTICS_SCRIPT }}
+        run: |
+          owner="$GITHUB_REPOSITORY_OWNER"
+          default_url="https://$owner.github.io"
+          giscus_ready=1
+          if [ -z "$GISCUS_REPO" ] || [ "$GISCUS_REPO" = "owner/repository" ]; then giscus_ready=0; fi
+          if [ -z "$GISCUS_REPO_ID" ] || [ "$GISCUS_REPO_ID" = "R_xxxxxxxxxx" ]; then giscus_ready=0; fi
+          if [ -z "$GISCUS_CATEGORY" ]; then giscus_ready=0; fi
+          if [ -z "$GISCUS_CATEGORY_ID" ] || [ "$GISCUS_CATEGORY_ID" = "DIC_xxxxxxxxxx" ]; then giscus_ready=0; fi
+          if [ "$giscus_ready" != 1 ]; then
+            if [ "$GISCUS_DISABLED" = "1" ]; then
+              GISCUS_REPO=
+              GISCUS_REPO_ID=
+              GISCUS_CATEGORY=
+              GISCUS_CATEGORY_ID=
+              echo "GISCUS_DISABLED=1，本次构建不开放评论。"
+            else
+              echo "评论还没有配置，构建已停止。"
+              echo "1. 准备一个公开 GitHub 仓库，并开启 Discussions。"
+              echo "2. 打开 https://giscus.app/zh-CN ，安装 Giscus App，选中该仓库和分类。"
+              echo "3. 在 Settings → Secrets and variables → Actions → Variables 写入："
+              echo "   GISCUS_REPO、GISCUS_REPO_ID、GISCUS_CATEGORY、GISCUS_CATEGORY_ID"
+              echo "确定不开放评论时，把 GISCUS_DISABLED 设为 1。留空和示例值 owner/repository 都不会通过。"
+              exit 1
+            fi
+          fi
+          {
+            echo "SITE_URL=${SITE_URL_OVERRIDE:-$default_url}"
+            echo "NEXT_PUBLIC_SITE_URL=${SITE_URL_OVERRIDE:-$default_url}"
+            echo "ADMIN_URL=$ADMIN_URL_OVERRIDE"
+            echo "GISCUS_REPO=$GISCUS_REPO"
+            echo "GISCUS_REPO_ID=$GISCUS_REPO_ID"
+            echo "GISCUS_CATEGORY=$GISCUS_CATEGORY"
+            echo "GISCUS_CATEGORY_ID=$GISCUS_CATEGORY_ID"
+            echo "NEXT_PUBLIC_GISCUS_REPO=$GISCUS_REPO"
+            echo "NEXT_PUBLIC_GISCUS_REPO_ID=$GISCUS_REPO_ID"
+            echo "NEXT_PUBLIC_GISCUS_CATEGORY=$GISCUS_CATEGORY"
+            echo "NEXT_PUBLIC_GISCUS_CATEGORY_ID=$GISCUS_CATEGORY_ID"
+            echo "WEBMENTION_IO_DOMAIN=$WEBMENTION_IO_DOMAIN"
+            echo "NEXT_PUBLIC_ANALYTICS_DOMAIN=$ANALYTICS_DOMAIN"
+            echo "NEXT_PUBLIC_ANALYTICS_SCRIPT=$ANALYTICS_SCRIPT"
+            echo "STATIC_EXPORT=1"
+          } >> "$GITHUB_ENV"
+
+      - name: Build the public site
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: npm run build
+
+      - name: Validate the static output
+        run: npm run pages:validate
+
+      - name: Configure GitHub Pages
+        if: ${{ vars.PAGES_REPOSITORY == '' }}
+        uses: actions/configure-pages@v6
+
+      - name: Upload the GitHub Pages artifact
+        if: ${{ vars.PAGES_REPOSITORY == '' }}
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: dist/client
+
+      - name: Upload the public-repository artifact
+        if: ${{ vars.PAGES_REPOSITORY != '' }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: static-site
+          path: dist/client
+          include-hidden-files: true
+          if-no-files-found: error
+          retention-days: 1
+
+  deploy-pages:
+    if: ${{ vars.PAGES_REPOSITORY == '' }}
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy the GitHub Pages artifact
+        id: deployment
+        uses: actions/deploy-pages@v5
+
+  publish-repository:
+    if: ${{ vars.PAGES_REPOSITORY != '' }}
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
+
+      - run: npm ci
+
+      - name: Check the split-repository configuration
+        env:
+          PAGES_DEPLOY_KEY: ${{ secrets.PAGES_DEPLOY_KEY }}
+          TARGET_REPOSITORY: ${{ vars.PAGES_REPOSITORY }}
+        run: |
+          test -n "$PAGES_DEPLOY_KEY" || { echo "缺少 PAGES_DEPLOY_KEY Secret"; exit 1; }
+          [[ "$TARGET_REPOSITORY" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || {
+            echo "PAGES_REPOSITORY 格式无效"
+            exit 1
+          }
+
+      - uses: actions/download-artifact@v8
+        with:
+          name: static-site
+          path: static-site
+
+      - name: Check out the public output repository
+        uses: actions/checkout@v7
+        with:
+          repository: ${{ vars.PAGES_REPOSITORY }}
+          ssh-key: ${{ secrets.PAGES_DEPLOY_KEY }}
+          path: pages-repository
+          fetch-depth: 1
+
+      - name: Start a clean rolling deployment
+        working-directory: pages-repository
+        env:
+          TARGET_REPOSITORY: ${{ vars.PAGES_REPOSITORY }}
+        run: |
+          expected_remote="git@github.com:$TARGET_REPOSITORY.git"
+          actual_remote="$(git remote get-url origin)"
+          test "$actual_remote" = "$expected_remote" || {
+            echo "拒绝发布到非目标仓库：$actual_remote"
+            exit 1
+          }
+          echo "PAGES_PREVIOUS_TREE=$(git rev-parse 'HEAD^{tree}')" >> "$GITHUB_ENV"
+          git checkout --orphan pages-deploy
+          git rm -q -r -f .
+
+      - name: Prepare generated-only repository contents
+        run: npx garden pages:prepare static-site pages-repository
+
+      - name: Publish the rolling deployment commit
+        working-directory: pages-repository
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add -A
+          new_tree="$(git write-tree)"
+          if [ "$new_tree" = "$PAGES_PREVIOUS_TREE" ]; then
+            echo "静态产物没有变化，无需发布"
+            exit 0
+          fi
+          git commit -m "Deploy ${GITHUB_SHA}"
+          git push --force origin HEAD:main
+```
+
+## 2. Setting Up Each Deployment Mode
+
+### Mode 1: Single Public Repository (`PAGES_REPOSITORY` Left Empty)
+
+If your source repository is public, name it `<owner>.github.io`. If you use another repository name, attach a custom domain to Pages and set the `SITE_URL` variable to that domain, or the `build` job will not run (Garden does not support subpath deployments such as `/<repo>/`):
+
+1. Open **Settings → Pages** in the repository and set **Source** to **GitHub Actions**.
+2. In **Settings → Secrets and variables → Actions → Variables**, add `GISCUS_DISABLED=1` (or set the 4 `GISCUS_*` variables below).
+3. Push to `main`; the workflow runs `deploy-pages` to publish directly.
+
+### Mode 2: Private Source Repository + Public Pages Repository
+
+To keep drafts (`draft: true`) and commit history private, store your source files in a private repository (such as `blog-source`) and push only the generated static files to a public `<owner>.github.io` repository:
+
+1. **Generate an SSH deploy key** locally:
+   ```bash
+   ssh-keygen -t ed25519 -C "garden-pages-deploy" -f ./pages_deploy_key
+   ```
+2. **Add the public key to the public repository**: Open **Settings → Deploy keys → Add deploy key** in `<owner>.github.io`, paste `pages_deploy_key.pub`, and check **Allow write access**.
+3. **Configure Pages on the public repository**: Open **Settings → Pages** in `<owner>.github.io`, set **Source** to **Deploy from a branch**, and select `main` with `/ (root)`.
+4. **Configure variables and secrets on the private repository**: Open **Settings → Secrets and variables → Actions** in the private source repo:
+   - Under **Variables**, add `PAGES_REPOSITORY` set to `<owner>/<owner>.github.io` (along with `GISCUS_DISABLED=1` or the 4 `GISCUS_*` variables).
+   - Under **Secrets**, add `PAGES_DEPLOY_KEY` with the full contents of the private key file `pages_deploy_key`.
+5. On every push to the private repo, the `publish-repository` job checks out the public repository using `PAGES_DEPLOY_KEY`, verifies that `PAGES_DEPLOY_KEY` is present, `PAGES_REPOSITORY` matches `owner/repo`, and the remote URL matches the target repository, then runs `npx garden pages:prepare static-site pages-repository` to write the static output, `.nojekyll`, and a short `README.md` before force-pushing a single orphan commit to `main`.
+
+## 3. Giscus Comments Configuration
+
+Article comments use GitHub Discussions via [Giscus](https://giscus.app). The application code reads `GISCUS_REPO`, `GISCUS_REPO_ID`, `GISCUS_CATEGORY`, and `GISCUS_CATEGORY_ID` (and their `NEXT_PUBLIC_GISCUS_*` counterparts), while the `Resolve the public URL` step in `pages.yml` checks that all four values are present before building:
+
+- **Disable comments**: Set `GISCUS_DISABLED=1` in GitHub Actions Variables; the workflow clears `GISCUS_*` and omits the comment section.
+- **Enable comments**: Enable Discussions on a public repository, install the Giscus App, and copy the four values into GitHub Actions Variables.
+
+> [!NOTE] Note
+> `npx garden pages:validate` inspects the `dist/client` directory (verifying that `index.html` exists and that no symlinks, `.env` files, `node_modules`, `.git`, `app`, `content`, `.md`, `.map`, or `.ts` files leaked into the export, apart from `.md` attachments under `media/`). It does not check Giscus variables itself.
+
+## 4. Environment Variables Reference
+
+All environment variables can be placed in a local `.env.local` file (never committed to Git) or in your deployment platform's Variables and Secrets:
+
+| Variable | Purpose |
+| :--- | :--- |
+| `SITE_URL` / `NEXT_PUBLIC_SITE_URL` | Public root URL of the site (such as `https://example.com`), used for canonical URLs, RSS feeds, and `sitemap.xml` |
+| `NEXT_PUBLIC_BASE_PATH` | Optional base path prefix (empty by default) |
+| `STATIC_EXPORT` | Set to `1` to export static HTML and enable trailing slashes on internal links |
+| `TRAILING_SLASH` | Set to `1` in server builds to enable trailing slashes on internal links (already on when `STATIC_EXPORT=1`) |
+| `CONTENT_INCLUDE_DRAFTS` | Set to `1` to include `draft: true` drafts and future `publishAt` posts in the build |
+| `GITHUB_TOKEN` | Fetches public GitHub profile data and pinned repositories at build time (pass `${{ github.token }}` in GitHub Actions) |
+| `GISCUS_DISABLED` | Read by the `pages.yml` workflow script: set to `1` to build without the 4 `GISCUS_*` variables |
+| `GISCUS_REPO` / `GISCUS_REPO_ID` | Public GitHub repository (`owner/repo`) and Repository ID for Giscus |
+| `GISCUS_CATEGORY` / `GISCUS_CATEGORY_ID` | Discussions category name and Category ID for Giscus |
+| `WEBMENTION_IO_DOMAIN` / `WEBMENTION_ENDPOINT` | Domain registered with Webmention.io (such as `example.com`) and custom endpoint override |
+| `ADMIN_URL` | Public URL of a separately deployed `/admin` instance |
+| `CONTENT_REPOSITORY` / `CONTENT_BRANCH` | Target GitHub repository (`owner/repo`) and branch (defaults to `main`) where `/admin` commits content |
+| `CONTENT_GITHUB_TOKEN` | Fine-grained GitHub PAT used by `/admin` to commit thoughts and assets |
+| `GITHUB_OAUTH_CLIENT_ID` / `GITHUB_OAUTH_CLIENT_SECRET` | Client ID and Secret of the GitHub OAuth App for `/admin` sign-in |
+| `GITHUB_SESSION_SECRET` | Random secret string used to sign `/admin` session cookies |
+| `ADMIN_GITHUB_LOGINS` | Comma-separated allowlist of GitHub usernames permitted to sign in to `/admin` |

package/docs/handbook/en/design.md

@@ -0,0 +1,81 @@
+---
+title: How the Reading Layout Works
+navTitle: How the Reading Layout Works
+description: Three-tier 740/1040/1340px adaptive widths, two-line title splitting, zero-CLS image sizing, dark-mode image backing, and warm paper tokens.
+section: writing-and-reading
+order: 11
+---
+
+Garden automates several layout details for long-form technical reading. Blog posts, column entries, and this handbook share the same stylesheets and measurement scripts.
+
+## 1. Three-tier Adaptive Widths: `740px` / `1040px` / `1340px`
+
+An article page consists of a centered reading column and a floating right-hand table of contents (`200px`). On load and window resize, the `ArticleMeasure` script measures wide figures and tables in the body and expands them symmetrically into the available horizontal margins:
+
+| Element | Max Width | Expansion Rule and Boundaries |
+| :--- | :--- | :--- |
+| Paragraphs, lists, code blocks, built-in components | `740px` | Body text uses `17px` font size and `1.75` line height (or `1.6` on English handbook pages) and stays inside the reading column |
+| Wide figures (`.fig`) | `1040px` | Retina screenshots default to half their pixel width (`naturalWidth / 2`); when wider than the column on viewports `>= 900px`, they extend up to `150px` on each side (keeping at least `24px` from the viewport edge, or staying between the sidebar and TOC on handbook pages) |
+| Wide tables (`.table-wrap`) | `1340px` | Measured at `max-content` without wrapping; when wider than `740px` on viewports `>= 900px`, tables extend up to `300px` on each side |
+| Floating table of contents (`.toc`) | `200px` | On standalone post pages, when a widened figure or table approaches the TOC, the TOC shifts right to clear it or hides temporarily if the viewport has no room, reappearing once scrolled past |
+
+## 2. Two-line Title Splitting and Font Scaling
+
+The `ArticleTitle` component applies two rules to headings:
+
+1. **With a delimiter (` | ` with surrounding spaces)**: Splits the title into two lines at the first delimiter and computes the `--l` scaling variable from the wider line's character width (counting CJK characters as `1`, uppercase letters as `0.68`, other characters as `0.58`, and spaces as `0.3`) so the longer line fits without wrapping again. Screen readers still read the full title with the delimiter.
+2. **Without a delimiter**: Renders a single `<h1>` with CSS `text-wrap: balance`, never splitting automatically on colons or dashes and never rescaling the font size.
+
+> [!NOTE] Note
+> If a title includes a split delimiter with an empty left or right side, `npx garden check` emits a `title-split` warning requiring text on both sides of the delimiter.
+
+## 3. Build-time Image Dimensions and Lightbox Zoom
+
+When `npx garden sync` runs, the build script reads the pixel width and height of every local image (PNG, JPEG, WebP, GIF, and SVG) and writes them into the `imageSizes` map in `.garden/generated-content.ts`:
+
+```garden figure
+caption: Click the buttons above to inspect the three stages from build to browser render
+svg: |
+  <svg viewBox="0 0 680 110" xmlns="http://www.w3.org/2000/svg" font-family="var(--sans)">
+    <rect data-p="sync" x="12" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
+    <text data-p="sync" x="110" y="50" text-anchor="middle" font-size="14" font-weight="600" fill="var(--ink)">1. Build-time Sizing</text>
+    <text data-p="sync" x="110" y="72" text-anchor="middle" font-size="12" fill="var(--muted)">Emit width / height &amp; --wl</text>
+    <path d="M214 55 H236" stroke="var(--muted)" stroke-width="1.5"/>
+    <rect data-p="measure" x="242" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
+    <text data-p="measure" x="340" y="50" text-anchor="middle" font-size="14" font-weight="600" fill="var(--ink)">2. Client Measurement</text>
+    <text data-p="measure" x="340" y="72" text-anchor="middle" font-size="12" fill="var(--muted)">Fit wide figures &amp; TOC</text>
+    <path d="M444 55 H466" stroke="var(--muted)" stroke-width="1.5"/>
+    <rect data-p="dark" x="472" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
+    <text data-p="dark" x="570" y="50" text-anchor="middle" font-size="14" font-weight="600" fill="var(--ink)">3. Dark Backing &amp; Zoom</text>
+    <text data-p="dark" x="570" y="72" text-anchor="middle" font-size="12" fill="var(--muted)">Pad #faf9f5 · Click to zoom</text>
+  </svg>
+parts:
+  - id: sync
+    label: 1. Build-time Sizing
+    text: Server-rendered HTML already carries the image's `width`, `height`, `data-nw`, `data-bw`, and initial `--wl` / `--wr`, preventing layout shift before the image finishes downloading.
+  - id: measure
+    label: 2. Client Measurement
+    text: After load, `ArticleMeasure` recomputes the expansion margins for the current viewport width and checks on scroll whether a wide figure overlaps the floating table of contents.
+  - id: dark
+    label: 3. Dark Backing & Zoom
+    text: "Clicking any article figure opens it in a full-screen lightbox (press `Esc` or click the backdrop to close); dark mode sets `--image-backing: #faf9f5` behind figures."
+```
+
+## 4. Dark-mode Image Backing and Warm Paper Tokens
+
+Technical posts frequently include transparent-background architecture diagrams or equation screenshots drawn with dark lines. On a dark page background those dark lines disappear, while a CSS `filter: invert` distorts full-color screenshots.
+
+In dark mode, Garden sets `background: var(--image-backing)` (`#faf9f5`) on article figures and lightbox images without applying color inversion or extra padding. Transparent dark-line diagrams stay legible, and opaque screenshots look unchanged. Site favicons share the same backing token, whereas post covers, avatars, and link card thumbnails do not.
+
+The site palette is defined in `app/styles/tokens.css` without brand blue:
+
+| Token | Light Mode | Dark Mode | Purpose |
+| :--- | :--- | :--- | :--- |
+| `--paper` | `#faf9f5` | `#1f1e1d` | Primary page background (`--image-backing` in dark mode also uses `#faf9f5`) |
+| `--paper-deep` / `--well` | `#f0eee6` | `#262624` | Code block and recessed well background |
+| `--chip` | `#f0eee6` | `#30302e` | Tag pills and button fills |
+| `--card` | `#ffffff` | `#262624` | Elevated cards, figure frames, and dialogs |
+| `--ink` | `#1b1a18` | `#eeece7` | Headings, strong emphasis, and primary interactive ink |
+| `--text` / `--soft` | `#2d2c29` / `#4a4844` | `#dcd9d2` / `#bdb9b0` | Body paragraphs and secondary copy |
+| `--muted` | `#6e6b64` | `#a09b91` | Dates, captions, and table headers (meeting WCAG AA 4.5:1 contrast) |
+| `--rule` / `--rule-strong` | `#e6e3dc` / `#d6d2c9` | `#3d3d3a` / `#4d4c48` | `1px` hairlines, card borders, and emphasized strokes |

package/docs/handbook/en/index.md

@@ -0,0 +1,192 @@
+---
+title: Write in Markdown | Push to Update the Site
+description: Write posts, short notes, and columns in Markdown inside your own Git repository.
+section: overview
+order: 0
+---
+
+Garden is a Claude-style blog framework where you write posts in Markdown and describe components in plain language.
+
+## A Complete Example
+
+The four steps in this section come from a real post, and every command output is taken verbatim from an actual run.
+
+### 1. The Author Writes an Idea
+
+Drop an unnamed `garden` fence where the interactive block should go and state what the reader adjusts and sees:
+
+````markdown
+## Writing Pace
+
+```garden
+Let the reader drag daily word count and writing days per week to see how many weeks an 8,000-word article takes.
+```
+````
+
+### 2. The Agent Scans and Writes Back the Component
+
+Tell the Agent to compile `content/posts/writing-pace.md`. Following the `garden-ui` skill in the repository, the Agent first runs `npx garden ui scan` to read the line number, original wording, and hash:
+
+```console
+$ npx garden ui scan content/posts/writing-pace.md
+{
+  "file": "content/posts/writing-pace.md",
+  "draft": false,
+  "blocks": [
+    {
+      "lang": "garden-idea",
+      "status": "uncompiled",
+      "startLine": 9,
+      "intentHash": "8866427a",
+      "intent": "Let the reader drag daily word count and writing days per week to see how many weeks an 8,000-word article takes.",
+      "section": "Writing Pace"
+    }
+  ]
+}
+```
+
+Next, the Agent reads the component catalog from `npx garden ui prompt`, writes a `garden interactive` block, and runs `npx garden ui apply` with `--intent-hash` to replace only that fence while leaving the rest of the file byte-for-byte untouched:
+
+```console
+$ npx garden ui apply content/posts/writing-pace.md --intent-hash 8866427a --file new.md
+{"ok":true,"file":"content/posts/writing-pace.md","kind":"garden","line":9}
+```
+
+### 3. The Pre-commit Hook Checks and Prints a Fix Prompt
+
+On the first `garden sync` or `garden dev` run, Garden writes `exec npx --no-install garden ui check --staged --quiet` to `.git/hooks/pre-commit`. If the author commits before step 2, the hook blocks the commit and prints a ready-to-paste prompt for the AI:
+
+```console
+$ git commit -m "Writing pace"
+content/posts/writing-pace.md:9  -  garden-idea  uncompiled idea remaining
+
+──────────────────────── Fix prompt for AI ────────────────────────
+Handle the Garden post blocks listed below: compile uncompiled ideas, and fix interactive blocks that have errors.
+
+Rules:
+- First run npx garden ui prompt and read the component catalog and rules; if the repo has the garden-ui skill, follow its flow.
+- Change only the listed blocks. Write them back with npx garden ui apply <post> --id <id> (use --intent-hash for ideas without an id). Do not edit the post by hand.
+- Keep the author's meaning. When done, run npx garden ui check <post> until it passes.
+- If you cannot access this repository, reply with only the finished fence for each block.
+
+1. content/posts/writing-pace.md, lines 9–11, intent-hash: 8866427a
+   - garden-idea: this idea is not compiled yet; compile it into garden interactive or another garden component (or put the sentence back into the prose).
+
+Current fence:
+
+```garden
+Let the reader drag daily word count and writing days per week to see how many weeks an 8,000-word article takes.
+```
+────────────────────────────────────────────────────────────
+Wrote .garden/ui-fix-prompt.md. To commit anyway, run git commit --no-verify.
+```
+
+The same prompt is saved to `.garden/ui-fix-prompt.md` and copied to the clipboard when a clipboard command is available. Once the Agent applies the block and the author commits again, the hook exits silently with code `0`.
+
+### 4. The Rendered Result
+
+The `garden interactive` fence written back in step 2 renders directly on the article page as an interactive calculator:
+
+```garden interactive #writing-pace
+caption: Writing a few hundred extra words each day finishes sooner than adding another writing day per week.
+intent: |
+  Let the reader drag daily word count and writing days per week to see how many weeks an 8,000-word article takes.
+---
+<State daily={500} days={3} />
+<Let weekly={daily * days} />
+<Let weeks={ceil(8000 / weekly)} />
+
+<Slider bind="daily" label="Words per day" min={200} max={2000} step={100} unit="words" />
+<Slider bind="days" label="Days per week" min={1} max={7} step={1} unit="days" />
+
+<Stat label="Weeks to finish 8,000 words" value={weeks} unit="weeks" hint="Rounded up to full weeks" />
+```
+
+> [!IMPORTANT] Humans and Agents Share the Same Tools
+> The `npx garden ui scan`, `npx garden ui apply`, and `npx garden ui check` commands used by the Agent are the exact commands run by the author's pre-commit hook. When the hook stops a commit, its output is the instruction for the Agent's next step. See [Writing with AI](/garden/en/ai-writing).
+
+The remaining sections cover the layout and component rules that work out of the box without an Agent.
+
+## Two-line Titles and the `740px` Reading Column
+
+Write ` | ` (with spaces on both sides) inside a title to split it across two lines and scale the font size to fit the longer line. Body copy stays inside a `740px` column, while wide figures expand symmetrically into the side margins without overlapping the navigation or table of contents.
+
+Transparent-background line drawings automatically get a warm paper backing in dark mode, so you do not need separate dark assets:
+
+![Diagram of the 740px reading column, 1040px wide figure zone, and 1340px wide table zone (transparent-background dark-line SVG, backed with #faf9f5 in dark mode).](../assets/reading-layout.svg)
+
+## Wide Tables Expand Symmetrically
+
+When a table is wider than the reading column without wrapping, it expands into both margins up to `1340px` on desktop:
+
+| Content Type | Source Location | How the Page Handles Long-form and Media Details | Typical Use |
+| :--- | :--- | :--- | :--- |
+| Long-form posts | `content/posts/<slug>.md` and a matching asset folder | Reads local image dimensions at build time to prevent layout shift, splits titles on ` \| `, widens figures and tables, and renders KaTeX math and Mermaid diagrams | System design notes, code walkthroughs, debugging postmortems, and book notes |
+| Short thoughts | `content/thoughts/<slug>.md` | Renders multi-image grids, native `image` / `audio` / `video` players, and external `link` preview cards | Short observations, terminal screenshots, audio clips, and saved links |
+| Ordered columns | `content/columns.yaml` | Chains multiple posts from `content/posts/` in reading order with series progress and previous/next navigation | Multi-part tutorials, topic series, and chaptered notes |
+
+## Code Blocks and the Diff Toggle
+
+Write a one-sentence `garden` idea right below an updated code block to describe what changed, and the Agent generates the adjacent `diff` fence; you can also write the `diff` fence by hand. When a code block is immediately followed by a `diff` block, the page combines them into a single frame with tabs for the full code and the diff against the previous version, while the copy button always copies the new code.
+
+```yaml
+pages:
+  garden:
+    title: "Write in Markdown | Push to Update the Site"
+    subtitle: "Write posts, short notes, and columns in Markdown inside your own Git repository."
+```
+
+```diff
+ pages:
+   garden:
+-    title: "Write in Markdown.\nPush to update the site."
+-    subtitle: ""
++    title: "Write in Markdown | Push to Update the Site"
++    subtitle: "Write posts, short notes, and columns in Markdown inside your own Git repository."
+```
+
+> [!NOTE] Note
+> A `diff` fence must sit immediately after a complete code block; a standalone `diff` fence triggers a `diff-orphan` error in `npx garden check`.
+
+> [!TIP] Custom Callout Titles
+> Write text on the same line after `> [!TIP]` (or place a bold line immediately below) to replace the default callout title. Supported types include `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, and `CAUTION`.
+
+## Structured Components in Markdown
+
+Use ```` ```garden <name> ```` fences to insert metrics, side-by-side comparisons, timelines, or charts. Here is a `garden stat` block:
+
+```garden stat
+items:
+  - label: Reading Column
+    value: "740"
+    unit: px
+    caption: Default width for paragraphs, code blocks, and lists
+  - label: Wide Figure Zone
+    value: "1040"
+    unit: px
+    caption: Screenshots display at half their pixel width and expand up to this limit above ~2000px
+  - label: Wide Table Zone
+    value: "1340"
+    unit: px
+    caption: Maximum width for wide multi-column tables expanding symmetrically on desktop
+```
+
+See [Components Overview](/garden/en/components) in the sidebar for all 9 built-in components and their live examples.
+
+<h2 id="garden-admin-title">From Init to Daily Writing</h2>
+
+Your site repository stores only configuration, Markdown posts, and static assets, while `hd-garden` provides the renderer and build scripts. Initialize and preview a site locally:
+
+```bash
+npx hd-garden init my-blog
+cd my-blog
+npm install
+make dev
+```
+
+Run `make update` when a post is ready; it runs the full check and build before committing and pushing. Read the chapters for details:
+
+- **[Quick Start](/garden/en/start)**: Directory layout, creating posts with `make new`, previewing drafts, and daily commands.
+- **[Site & Column Config](/garden/en/config)**: Every field in `site.config.yaml`, custom SVG icons, and ordering series in `content/columns.yaml`.
+- **[Deploy to GitHub Pages](/garden/en/deploy)**: A single GitHub Actions workflow that supports both one public repository and a private source repo paired with a public Pages repo.
+- **[Writing Posts & Thoughts](/garden/en/writing)** and **[How the Reading Layout Works](/garden/en/design)**: Front Matter fields, external link cards, three-tier adaptive widths, and color tokens.

package/docs/handbook/en/start.md

@@ -0,0 +1,92 @@
+---
+title: Quick Start
+navTitle: Quick Start
+description: Initialize a site directory with npx hd-garden init, preview locally, create posts, and push updates.
+section: getting-started
+order: 1
+---
+
+Garden is a personal blog tool written in Markdown and managed with Git. An initialized site repository holds only your configuration files, Markdown content, and static assets, while the rendering and build pipeline comes from the `hd-garden` package.
+
+## 1. Requirements and Initialization
+
+Install **Node.js `>= 22.13.0`**, **Git**, and **GNU Make** first. Run the following commands in your terminal to create a site directory:
+
+```bash
+npx hd-garden init my-blog
+cd my-blog
+npm install
+make dev
+```
+
+`npx hd-garden init` copies the site template into `my-blog` and writes the helper skills under `.agents/skills/`. It does not run `npm install` automatically, and it does not create `.github/workflows/pages.yml` (see [Deploy to GitHub Pages](/garden/en/deploy) for the workflow file).
+
+On the first `make dev` run, if `node_modules` is missing, `make prepare` in the `Makefile` runs `npm install` before invoking `npx garden dev` (which syncs content first) and starting the local dev server at `http://localhost:3000`.
+
+## 2. Directory Structure
+
+An initialized site repository has the following layout:
+
+```text
+my-blog/
+├── site.config.yaml        # Site name, author info, and titles/subtitles for top-level pages
+├── content/
+│   ├── columns.yaml        # Column definitions and reading order
+│   ├── covers/             # Cover images for posts and columns
+│   ├── posts/              # Long-form posts (.md) and matching sidecar folders
+│   └── thoughts/           # Short notes (.md) and media attachments
+├── public/                 # Static files served at their root paths (such as icons)
+├── Makefile                # Daily commands for previewing, creating posts, checking, and pushing
+└── package.json            # Depends only on hd-garden
+```
+
+## 3. Creating Posts and Thoughts
+
+### Creating a Post (`make new`)
+
+Run `make new` to create a draft in `content/posts/` pre-filled with the date, title, and a commented component cheat sheet:
+
+```bash
+make new SLUG=tcp-bbr TITLE="TCP BBR Notes"
+```
+
+To place the post inside a subdirectory (such as `content/posts/network/tcp-bbr.md`), pass `DIR`:
+
+```bash
+make new DIR=network SLUG=tcp-bbr TITLE="TCP BBR Notes"
+```
+
+> [!NOTE] Note
+> `SLUG` may only contain lowercase letters, digits, and hyphens (`a-z`, `0-9`, `-`), never `/`; pass subdirectories via `DIR`. `make new` reads only `SLUG`, `TITLE`, and `DIR`.
+
+Newly created files default to `draft: true`. Set `CONTENT_INCLUDE_DRAFTS=1` to preview drafts or future-dated (`publishAt`) posts locally:
+
+```bash
+CONTENT_INCLUDE_DRAFTS=1 make dev
+```
+
+### Creating a Thought
+
+Thoughts live in `content/thoughts/`. Create a `.md` file directly in `content/thoughts/` (for example `content/thoughts/2026-10-19-note.md`) with `title` and `date` in its Front Matter, or publish from the browser after configuring `/admin`. See [Writing Posts & Thoughts](/garden/en/writing) for the supported fields.
+
+## 4. Daily Commands and Upgrading
+
+The site `Makefile` and `garden` CLI provide these commands:
+
+| Command | What It Runs |
+| :--- | :--- |
+| `make dev` | Runs `make prepare` to check dependencies, then runs `npx garden dev` (which syncs content and starts the dev server) |
+| `CONTENT_INCLUDE_DRAFTS=1 make dev` | Previews `draft: true` drafts and future `publishAt` posts alongside published content |
+| `make new SLUG=xxx TITLE="Title" DIR=subdir` | Calls `npx garden new` to create a draft post under `content/posts/` (`DIR` is optional) |
+| `make check` | Runs `npx garden sync && npx garden build` in the site repo to verify content sync and the production build |
+| `npx garden check content/posts/xxx.md` | Checks a single Markdown post's title, component fields, code diffs, and local asset paths |
+| `make update MESSAGE="Commit message"` | Runs `make check`, then `git add -A`, `git commit -m "$(MESSAGE)"`, and `git push origin HEAD` |
+
+### Upgrading `hd-garden`
+
+To upgrade the engine, edit `package.json` in your site root, update the `"hd-garden"` version string, and run `npm install`:
+
+```bash
+npm install
+make check
+```