Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Reorganize CLAUDE.md for clearer workflow documentation
Maximilian Roos19020aebd956
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.mdindex 657dcc3b1..b8853b358 100644--- a/docs/CLAUDE.md+++ b/docs/CLAUDE.md@@ -1,51 +1,20 @@# Docs Site-## Demo GIF workflow--**For local development**, fetch existing assets from the CDN:--```bash-./scripts/fetch-assets # Download assets for local dev-```--**To update demos**, see `dev/wt-demo/CLAUDE.md` for the full workflow:--```bash-./dev/wt-demo-build # Build new demo (auto-copies to docs/static/assets/)-./scripts/publish-assets # Publish to assets repo-```--View at http://127.0.0.1:1111/why-worktrunk/-------This is an initial scaffolding of the documentation site. The content was auto-generated from the main README and has not been reviewed for accuracy.--**Do not trust any content here.** Before this is production-ready:--- Survey all pages for accuracy-- Verify code examples work-- Check command output matches current behavior-- Review configuration options against actual implementation--This is being merged to enable iteration, not as finished documentation.+This is the Zola-based documentation site for Worktrunk, published at worktrunk.dev.## Development workflow-When making changes to the docs, **ensure the dev server is running before returning to the user** so they can review changes in their browser.+Start the dev server from the docs directory:```bash-# Start the dev server from the docs directory (runs on http://127.0.0.1:1111)-cd docs && zola serve+cd docs && zola serve # Runs on http://127.0.0.1:1111```-If the server isn't already running, start it as a background process or in a separate terminal session before completing work. The user should be able to immediately see rendered changes without needing to manually start the server.-### Verifying changes-**Text-only changes** (prose edits, content rewrites, documentation fixes): Run pre-commit and provide the dev server link. Playwright verification is not required — the user can review rendered content directly.+**Text-only changes** (prose edits, content rewrites): Run pre-commit and provide the dev server link. Playwright verification is not required.-**Visual changes** (CSS, layout, templates, responsive breakpoints): Use Playwright MCP to verify before returning. Visual bugs often hide in CSS specificity, template inheritance, and responsive behavior that aren't apparent from reading code.+**Visual changes** (CSS, layout, templates, responsive breakpoints): Use Playwright MCP to verify before returning. Visual bugs often hide in CSS specificity, template inheritance, and responsive behavior.Playwright workflow for visual changes:1. Navigate to affected page(s)@@ -72,7 +41,7 @@ The docs use a "warm workbench" theme built on top of the Juice Zola theme. Key|------|---------|| `templates/_variables.html` | CSS custom properties (colors, layout, typography) || `sass/custom.scss` | All styling, organized by section |-| `templates/base.html` | Head overrides, IntersectionObserver disable |+| `templates/base.html` | Head overrides, iOS viewport polyfill || `templates/index.html` | Homepage hero and animations || `templates/page.html` | Doc page TOC rendering |@@ -97,6 +66,7 @@ When either variable changes (including via media queries), all dependent values3. **IntersectionObserver intercept** - Disables Juice's scroll-spy which conflicts with our TOC styling4. **Logo preload** - Prevents flash when navigating between pages5. **WCAG AA colors** - `--wt-color-text-soft` is #78716a for 4.5:1 contrast+6. **iOS viewport polyfill** - Sets stable `--vh-full` variable for Firefox iOS and Chrome iOS### Responsive breakpoints@@ -215,3 +185,21 @@ The generated files contain this warning comment in the Command Reference sectio```html<!-- ⚠️ AUTO-GENERATED from `wt <command> --help-page` — edit cli.rs to update -->```++## Demo GIF workflow++Demo GIFs (~2MB each) are stored in a separate `worktrunk-assets` repo to avoid bloating git history.++**For local development:**+```bash+./scripts/fetch-assets # Download to docs/static/assets/ (gitignored)+```++**To update demos:**+```bash+./demos/wt-demo/build # Build from VHS tape file+./demos/wt-select/build # Build select demo+./scripts/publish-assets # Push to assets repo+```++Deploy runs `fetch-assets` before building.