The official website for Gas Town - an orchestration layer for AI coding agents.

Live site: https://gastownhall.ai

npm install          # Installs all dependencies (monorepo with npm workspaces)
npm run dev          # Main site at localhost:4321
npm run dev:docs     # Docs site at localhost:4322

To preview production builds locally before deploying:

npm run build && npm run preview           # Main site
npm run build:docs && npm run preview:docs # Docs site

Build pipelines:

• Main site: copy-assets → llms → astro build → deploy/
• Docs subdomain: llms → astro build → deploy-docs/ (content is COMMITTED, no gt needed)

Both sites auto-deploy to Cloudflare Pages on push to main.

Manual deploys:

• npm run deploy - Deploy main site
• npm run deploy:docs - Deploy docs subdomain

Redirects: gastownhall.com → gastownhall.ai

This is an npm workspaces monorepo with two Astro projects:

├── package.json             # Root package with workspaces: ["docs"]
├── src/                     # Main site source
│   ├── site.config.ts       # Site configuration (URLs, social links)
│   ├── pages/               # Astro pages (file-based routing)
│   ├── layouts/             # Page layouts (BaseLayout, BlogLayout)
│   └── components/          # Reusable components
├── docs/                    # Docs subdomain (Astro Starlight workspace)
│   ├── package.json         # Workspace package (docs-specific deps)
│   ├── astro.config.mjs     # Starlight config with sidebar
│   ├── src/content/docs/    # Markdown content (committed)
│   └── scripts/             # Docs build scripts
├── scripts/
│   ├── copy-assets.mjs      # Copy src/static/ → tmp/public/
│   ├── sync-gastown-docs.mjs # Sync docs from gastown repo
│   ├── generate-llms.mjs    # Generate /llms.txt
│   └── lib/                 # Shared utilities and tests
├── src/static/              # Static assets (source of truth)
├── docs-fodder/
│   ├── gastown-docs/        # Documentation markdown source
│   ├── steve-blog-posts/    # Medium blog post markdown
│   └── youtube/             # YouTube video metadata markdown
├── deploy/                  # Main site build output
└── deploy-docs/             # Docs subdomain build output

Docs use Astro Starlight for a modern documentation experience with built-in search, dark mode, and automatic navigation.

npm run build:docs - Builds from COMMITTED content. No gt CLI needed. Used by Cloudflare.

npm run sync-docs - Regenerates content from gastown repo. Requires gt CLI. LOCAL ONLY.

LOCAL (when gastown docs change):
  npm run sync-docs     # Regenerate content (requires gt CLI)
  git commit + push     # Commit the updated content

CLOUDFLARE (automatic on push):
  npm run build:docs    # Build from committed content (no gt needed)

The docs/src/content/docs/ directory is committed. Cloudflare builds from these committed files.

# 1. Pull latest gastown
cd ~/Code/Cache/steveyegge/gastown && git pull && cd -

# 2. Sync docs from gastown repo (requires gt CLI)
npm run sync-docs

# 3. Preview locally
npm run build:docs && npm run preview:docs

# 4. Commit the updated docs
git add docs/src/content/docs/ && git commit -m "Sync docs from gastown"

# 5. Push to main - CF auto-builds both sites
git push

To edit documentation without syncing from gastown:

1. Edit markdown files directly in docs/src/content/docs/
2. Run npm run dev:docs to preview
3. Commit your changes

The homepage "Town Crier" section displays blog posts and videos from the blogPosts array in site.config.json. Content source files live in docs-fodder/steve-blog-posts/ (Medium posts) and docs-fodder/youtube/ (YouTube videos).

To add new content, use the Claude Code skill: add-content (in .claude/skills/add-content/SKILL.md), or follow these steps manually:

1. Extract metadata (title, date, URL, description, lead image) from the docs-fodder/ markdown files
2. Add entries to the blogPosts array in site.config.json (newest first)
3. Download images to src/static/images/blog/ and tmp/public/images/blog/ (both required — see skill for details)
4. Verify with npm run dev at localhost:4321

Images display as 112x112px squares with object-fit: cover. Use mqdefault.jpg for YouTube thumbnails (not hqdefault.jpg, which has letterboxing).

Single source of truth: site.config.json contains all site metadata.

• src/site.config.ts - Re-exports JSON for Astro components
• scripts/lib/config.mjs - Imports JSON for build scripts
• docs/astro.config.mjs - Starlight sidebar configuration

• npm workspaces - Monorepo management
• Astro - Static site generator
• Astro Starlight - Documentation framework
• Plausible - Privacy-friendly analytics
• ESLint + Prettier - Linting and formatting
• Playwright - E2E testing
• Husky - Git hooks
• Node.js test runner - Unit testing

A pre-commit hook runs npm run check automatically on commits to main branch, which includes:

• ESLint
• Prettier format check
• Unit tests
• Security audit (fails on high/critical vulnerabilities)

To bypass temporarily: git commit --no-verify

This website is licensed under the MIT License.

Content Attribution: All documentation content from the Gas Town repository and blog posts by Steve Yegge are copyright Steve Yegge and are reproduced on this website with permission. The MIT license applies only to the website code, design, and infrastructure - not to the Gas Town documentation content.

For the Gas Town software license, see the Gas Town repository.