### Basic Formula Installation Example

Source: https://github.com/gastownhall/gastown/blob/main/docs/design/mol-mall-design.md

Demonstrates the output of a basic formula installation, showing resolution, download progress, verification, and installation path.

```bash
$ gt formula install mol-polecat-code-review

Resolving mol-polecat-code-review...
  Registry: molmall.gastown.io
  Version:  1.2.0 (latest)
  Author:   steve@gastown.io
  Skills:   code-review, security

Downloading... ████████████████████ 100%
Verifying checksum... ✓

Installed to: ~/gt/.beads/formulas/mol-polecat-code-review.formula.toml

```

--------------------------------

### Wasteland Configuration File Example

Source: https://github.com/gastownhall/gastown/blob/main/docs/WASTELAND.md

Example JSON configuration for the Gas Town workspace, used after manual setup.

```json
{
  "upstream": "hop/wl-commons",
  "fork_org": "your-dolthub-org",
  "fork_db": "wl-commons",
  "local_dir": "/path/to/your/gt/.wasteland/hop/wl-commons",
  "rig_handle": "your-dolthub-org",
  "joined_at": "2026-01-01T00:00:00Z"
}
```

--------------------------------

### Complete Workflow Example

Source: https://github.com/gastownhall/gastown/blob/main/docs/WASTELAND.md

End-to-end flow for a first contribution, from setup to submitting completion evidence.

```bash
# 1. Set up environment (one-time)
export DOLTHUB_ORG="your-username"
export DOLTHUB_TOKEN="dhat.v1.your-token"

# 2. Join the wasteland (one-time, from Gas Town workspace)
cd ~/
gt
gt wl join hop/wl-commons

# 3. Browse for work
gt wl browse --type docs

# 4. Claim an item
gt wl claim w-abc123

# 5. Do the work (in the relevant repo)
cd ~/path/to/relevant/repo
git checkout -b docs/my-contribution
# ... make changes ...
git add . && git commit -m "Add my contribution"
git push -u origin HEAD

# 6. Open a PR on GitHub
gh pr create --title "docs: My contribution"

# 7. Submit completion evidence (back in Gas Town workspace)
cd ~/
gt
gt wl done w-abc123 --evidence "https://github.com/org/repo/pull/123"

# 8. Sync to see updated state
gt wl sync
```

--------------------------------

### Start Gas Town Proxy Server

Source: https://github.com/gastownhall/gastown/blob/main/docs/proxy-server.md

Installs the CA on first run and starts the proxy server listening on the specified address and port.

```bash
# Installs the CA on first run
gt-proxy-server --listen 0.0.0.0:9876

# The CA cert is now at ~/gt/.runtime/ca/ca.crt
```

--------------------------------

### Install Prerequisites on Linux (Debian/Ubuntu)

Source: https://github.com/gastownhall/gastown/blob/main/docs/INSTALLING.md

Installs Git and tmux. Downloads and installs a specific Go version, updating the PATH. Instructions for Dolt installation are referenced.

```bash
# Required
sudo apt update
sudo apt install -y git

# Install Go (apt version may be outdated, use official installer)
wget https://go.dev/dl/go1.25.8.linux-amd64.tar.gz
sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.25.8.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin' >> ~/.bashrc
source ~/.bashrc

# Install Dolt: see https://github.com/dolthub/dolt?tab=readme-ov-file#installation

# Optional (for full stack mode)
sudo apt install -y tmux
```

--------------------------------

### Install Prerequisites on Linux (Fedora/RHEL)

Source: https://github.com/gastownhall/gastown/blob/main/docs/INSTALLING.md

Installs Git and Go using dnf. Installs tmux for optional full-stack mode. Instructions for Dolt installation are referenced.

```bash
# Required
sudo dnf install -y git golang
# Install Dolt: see https://github.com/dolthub/dolt?tab=readme-ov-file#installation

# Optional
sudo dnf install -y tmux
```

--------------------------------

### Install Homebrew and Prerequisites on macOS

Source: https://github.com/gastownhall/gastown/blob/main/docs/INSTALLING.md

Installs Homebrew if needed, then installs Go, Git, and Dolt. Also installs tmux for optional full-stack mode.

```bash
# Install Homebrew if needed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Required
brew install go git dolt

# Optional (for full stack mode)
brew install tmux
```

--------------------------------

### Verify Prerequisites Installation

Source: https://github.com/gastownhall/gastown/blob/main/docs/INSTALLING.md

Commands to check the installed versions of Go, Git, Dolt, and optionally tmux.

```bash
# Check all prerequisites
go version        # Should show go1.25.8 or higher
git --version     # Should show 2.20 or higher
dolt version      # Should show 2.0.7 or higher
tmux -V           # (Optional) Should show 3.0 or higher
```

--------------------------------

### Example: Feature Development Workflow

Source: https://github.com/gastownhall/gastown/blob/main/README.md

Demonstrates a typical feature development process using Gas Town commands. This includes starting the Mayor, creating convoys, assigning work, and monitoring progress.

```bash
# 1. Start the Mayor
gt mayor attach

# 2. In Mayor session, create a convoy with bead IDs
gt convoy create "Feature X" gt-abc12 gt-def34 --notify --human

# 3. Assign work to an agent
gt sling gt-abc12 myproject

# 4. Track progress
gt convoy list

# 5. Monitor agents
gt agents
```

--------------------------------

### Install and Initialize Gas Town

Source: https://github.com/gastownhall/gastown/blob/main/README.md

Installs Gas Town from Git, configures agents, and attaches to the Mayor. Use this to begin your Gas Town setup.

```shell
gt install ~/gt --git &&
cd ~/gt &&
gt config agent list &&
gt mayor attach
```

--------------------------------

### TypeScript Project Build Pipeline Configuration

Source: https://github.com/gastownhall/gastown/blob/main/docs/concepts/integration-branches.md

Example configuration for a TypeScript project, specifying all five pipeline commands: setup, typecheck, lint, test, and build.

```json
{
  "merge_queue": {
    "setup_command": "pnpm install",
    "typecheck_command": "tsc --noEmit",
    "lint_command": "eslint .",
    "test_command": "pnpm test:unit",
    "build_command": "pnpm build"
  }
}
```

--------------------------------

### Dolt Backup Plugin Usage Examples

Source: https://github.com/gastownhall/gastown/blob/main/plugins/dolt-backup/plugin.md

Examples of how to execute the Dolt Backup plugin script with different options.

```bash
./run.sh
```

```bash
./run.sh --dry-run
```

```bash
./run.sh --databases hq,beads
```

--------------------------------

### Version Pinning and Listing Installed Formulas

Source: https://github.com/gastownhall/gastown/blob/main/docs/design/mol-mall-design.md

Shows how to install a specific version of a formula and then list all installed formulas with their versions and pinning status.

```bash
$ gt formula install mol-polecat-work@4.0.0

Installing mol-polecat-work@4.0.0 (pinned)...
✓ Installed

$ gt formula list --installed
  mol-polecat-work           4.0.0   [pinned]
  mol-polecat-code-review    1.2.0   [latest]

```

--------------------------------

### Install a Single File Formula

Source: https://github.com/gastownhall/gastown/blob/main/docs/design/mol-mall-design.md

Installs a formula from the registry. The formula is downloaded as a single .formula.toml file.

```bash
gt formula install mol-polecat-code-review
# Downloads mol-polecat-code-review.formula.toml to ~/gt/.beads/formulas/

```

--------------------------------

### Docker Compose Setup and Execution

Source: https://github.com/gastownhall/gastown/blob/main/README.md

Configure environment variables for Git user and email, and optionally the dashboard port. Build and start the Docker Compose services, then access the container's shell.

```bash
export GIT_USER="<your name>"
export GIT_EMAIL="<your email>"
export DASHBOARD_PORT=8080  # optional, host port for the web dashboard

docker compose build              # only needed on first run or after code changes
docker compose up -d

docker compose exec gastown zsh   # or bash
```

--------------------------------

### Start gt-proxy-server

Source: https://github.com/gastownhall/gastown/blob/main/docs/proxy-server.md

Starts the gt-proxy-server with specified listen address, CA directory, allowed commands, and town root.

```bash
gt-proxy-server \
  --listen 0.0.0.0:9876 \
  --ca-dir ~/gt/.runtime/ca \
  --allowed-cmds gt,bd \
  --town-root ~/gt
```

--------------------------------

### Example plugin.md Content with TOML Frontmatter

Source: https://github.com/gastownhall/gastown/blob/main/docs/design/plugin-system.md

Shows a complete example of a plugin.md file, including TOML frontmatter for configuration and a markdown section for instructions.

```markdown
+++
name = "rebuild-gt"
description = "Rebuild stale gt binary from source"
version = 1

[gate]
type = "cooldown"
duration = "1h"

[tracking]
labels = ["plugin:rebuild-gt", "rig:gastown", "category:maintenance"]
digest = true

[execution]
timeout = "5m"
notify_on_failure = true
+++

# Rebuild gt Binary

Instructions for the dog worker to execute...
```

--------------------------------

### Install Dependencies and Build from Source

Source: https://github.com/gastownhall/gastown/blob/main/docs/INSTALLING.md

Installs dependencies (dolt, bd) and builds Gas Town from source using make. Ensures the Go bin directory is in the PATH.

```bash
brew install dolt
go install github.com/steveyegge/beads/cmd/bd@latest
export PATH="$HOME/.local/bin:$PATH:$HOME/go/bin"
git clone https://github.com/steveyegge/gastown.git
cd gastown
make install
```

--------------------------------

### Install Gas Town via Homebrew, npm, or Go

Source: https://github.com/gastownhall/gastown/blob/main/README.md

Choose the recommended Homebrew installation or use npm or Go for installation. Note macOS limitations with `go install`.

```bash
# Install Gas Town
$ brew install gastown                                    # Homebrew (recommended)
$ npm install -g @gastown/gt                              # npm
$ go install github.com/steveyegge/gastown/cmd/gt@latest  # From source (Linux only)
```

--------------------------------

### Registry and Install Hooks

Source: https://github.com/gastownhall/gastown/blob/main/docs/HOOKS.md

Allows browsing available hooks in the registry and installing a selected hook into the base configuration. Provide the hook's ID when installing.

```bash
gt hooks registry                  # List available hooks
gt hooks install <hook-id>         # Install a hook to base config
```

--------------------------------

### Install Beads CLI

Source: https://github.com/gastownhall/gastown/blob/main/docs/INSTALLING.md

Install the Beads CLI using Go if 'bd: command not found' error occurs.

```bash
go install github.com/steveyegge/beads/cmd/bd@latest
```

--------------------------------

### Install Gas Town CLI with Homebrew

Source: https://github.com/gastownhall/gastown/blob/main/docs/INSTALLING.md

Installs the Gas Town CLI using Homebrew and verifies the installation of gt, bd, and dolt.

```bash
# Install Gas Town CLI
brew install gastown

# Verify installation
gt version
bd version
dolt version
```

--------------------------------

### Gate Type Configuration Examples

Source: https://github.com/gastownhall/gastown/blob/main/docs/design/plugin-system.md

Provides examples of configuration for different gate types, including cooldown, cron, condition, event, and manual dispatch.

```markdown
| Type | Config |
|------|--------|
| `cooldown` | `duration = "1h"` |
| `cron` | `schedule = "0 9 * * *"` |
| `condition` | `check = "cmd"` |
| `event` | `on = "startup"` |
| `manual` | (no gate section) |
```

--------------------------------

### Install Formulas from Mol Mall

Source: https://github.com/gastownhall/gastown/blob/main/docs/design/formula-resolution.md

Use `gt formula install` to add formulas from the Mol Mall. You can specify a formula name or a specific version. Remote installations via URLs are also supported.

```bash
# Install from Mol Mall
gt formula install mol-code-review-strict
gt formula install mol-code-review-strict@2.0.0
gt formula install hop://acme.corp/formulas/mol-deploy
```

--------------------------------

### Beads Show Command Examples

Source: https://github.com/gastownhall/gastown/blob/main/docs/design/architecture.md

Examples of using the 'bd show' command to display beads information, demonstrating routing to different rig locations.

```bash
bd show hq-mayor
bd show gt-xyz
```

--------------------------------

### Install Formula Using HOP URI

Source: https://github.com/gastownhall/gastown/blob/main/docs/design/mol-mall-design.md

Install a formula by specifying its full HOP URI, which includes the registry, organization, name, and version.

```bash
# Full HOP URI
gt formula install hop://molmall.acme.corp/formulas/@acme/mol-deploy@2.1.0
```

--------------------------------

### Daemon Rig Service Start Logic

Source: https://github.com/gastownhall/gastown/blob/main/docs/design/property-layers.md

Go function that checks rig configuration before starting services. Skips startup if the rig is parked or docked.

```go
func (d *Daemon) maybeStartRigServices(rig string) {
    r := d.getRig(rig)

    status := r.GetConfig("status")
    if status == "parked" || status == "docked" {
        log.Info("Rig %s is offline, skipping auto-start", rig)
        return
    }

    d.ensureWitness(rig)
    d.ensureRefinery(rig)
}
```

--------------------------------

### Runtime Configuration Example

Source: https://github.com/gastownhall/gastown/blob/main/README.md

Example JSON configuration for the Codex runtime provider. This specifies the command, arguments, and prompt mode.

```json
{
  "runtime": {
    "provider": "codex",
    "command": "codex",
    "args": [],
    "prompt_mode": "none"
  }
}
```

--------------------------------

### Enable Gas Town and Start Services

Source: https://github.com/gastownhall/gastown/blob/main/docs/INSTALLING.md

Enables Gas Town system-wide, initializes a Git repository for the HQ, and starts all Gas Town services. Use 'gt down' or 'gt shutdown' to stop services.

```bash
cd ~/gt

gt enable              # enable Gas Town system-wide
gt git-init            # initialize a git repo for your HQ
gt up                  # Start all services. Use gt down or gt shutdown for stopping.
```

--------------------------------

### Rebuild and Install gt Binary

Source: https://github.com/gastownhall/gastown/blob/main/plugins/rebuild-gt/plugin.md

Execute the build and safe installation commands from the canonical source directory. Use 'make safe-install' to replace the binary without restarting the daemon.

```bash
cd ~/gt/gastown/mayor/rig && make build && make safe-install
```

--------------------------------

### Mol Mall URI Scheme Examples

Source: https://github.com/gastownhall/gastown/blob/main/docs/design/mol-mall-design.md

Examples demonstrating the structure of Mol Mall URIs, including full and short forms.

```text
hop://molmall.gastown.io/formulas/mol-polecat-work@4.0.0
       └──────────────────┘         └──────────────┘ └───┘
           registry host              formula name   version

# Short forms
mol-polecat-work                    # Default registry, latest version
mol-polecat-work@4                  # Major version
mol-polecat-work@4.0.0              # Exact version
@acme/mol-deploy                    # Scoped to publisher
hop://acme.corp/formulas/mol-deploy # Full HOP URI
```

--------------------------------

### Quick Start: Parse and Execute Workflow

Source: https://github.com/gastownhall/gastown/blob/main/internal/formula/README.md

Demonstrates parsing a workflow formula file, determining execution order, and simulating step execution based on dependencies.

```go
// Parse a formula file
f, err := formula.ParseFile("workflow.formula.toml")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Formula: %s (type: %s)\n", f.Name, f.Type)

// Get execution order
order, _ := f.TopologicalSort()
fmt.Printf("Execution order: %v\n", order)

// Track and execute
completed := make(map[string]bool)
for len(completed) < len(order) {
    ready := f.ReadySteps(completed)
    // Execute ready steps (can be parallel)
    for _, id := range ready {
        step := f.GetStep(id)
        fmt.Printf("Executing: %s\n", step.Title)
        completed[id] = true
    }
}

```

--------------------------------

### Install Prerequisites for Gas Town and NOS Town

Source: https://github.com/gastownhall/gastown/blob/main/docs/runtimes/NOS_TOWN.md

Installs the necessary Gas Town dependencies, NOS Town CLI, and sets the Groq API key environment variable.

```bash
# Gas Town deps (same as standard install)
go install github.com/kab0rn/gastown/cmd/gt@latest
go install github.com/steveyegge/beads/cmd/bd@latest

# NOS Town CLI
go install github.com/kab0rn/nostown/cmd/nos@latest

# Set Groq API key
export GROQ_API_KEY="your-api-key"
```

--------------------------------

### Basic Workflow Example

Source: https://github.com/gastownhall/gastown/blob/main/docs/INSTALLING.md

Demonstrates creating a test task and a convoy using Gas Town and Beads.

```bash
bd create "Test task"
gt convoy create "Test" <bead-id>
```

--------------------------------

### CLI Output Example with Step Constraints

Source: https://github.com/gastownhall/gastown/blob/main/docs/design/model-aware-molecules.md

Illustrates how `gt prime` output displays step constraints, recommended models, and fallbacks based on MMLU scores and pricing.

```text
### Step 2: Analyze requirements
  Constraint: model=auto, min_mmlu=85
  Recommended: claude-opus-4-5 (subscription, $0.00)
  Fallback: claude-sonnet-4-5 (api_key, $0.003/1K)

### Step 3: Code generation
  Constraint: provider=openai, requires=[code_execution]
  Recommended: gpt-4o ($0.0025/1K in)

```

--------------------------------

### Registering a Hook Installer in Go

Source: https://github.com/gastownhall/gastown/blob/main/docs/agent-provider-integration.md

Example of registering a hook installer function in Go using `config.RegisterHookInstaller`. This function ensures settings are correctly managed for a specific role.

```go
config.RegisterHookInstaller("kiro", func(settingsDir, workDir, role, hooksDir, hooksFile string) error {
    // Write your settings file to the appropriate location
    return kiro.EnsureSettingsForRoleAt(settingsDir, role, hooksDir, hooksFile)
})

```

--------------------------------

### Gastown Formulas Lock File Structure

Source: https://github.com/gastownhall/gastown/blob/main/docs/design/mol-mall-design.md

Example JSON structure of the .lock.json file used to track installed formulas, their versions, pinning status, checksums, and installation sources.

```json
// ~/gt/.beads/formulas/.lock.json
{
  "version": 1,
  "formulas": {
    "mol-polecat-work": {
      "version": "4.0.0",
      "pinned": true,
      "checksum": "sha256:abc123...",
      "installed_at": "2026-01-10T00:00:00Z",
      "source": "hop://molmall.gastown.io/formulas/mol-polecat-work@4.0.0"
    },
    "mol-polecat-code-review": {
      "version": "1.3.0",
      "pinned": false,
      "checksum": "sha256:def456...",
      "installed_at": "2026-01-10T12:00:00Z",
      "source": "hop://molmall.gastown.io/formulas/mol-polecat-code-review@1.3.0"
    }
  }
}

```

--------------------------------

### Gastown Integration Create Command Examples

Source: https://github.com/gastownhall/gastown/blob/main/docs/concepts/integration-branches.md

Demonstrates the default branch template, custom configuration, and overriding with the --branch flag.

```bash
# Default template (uses epic title)
gt mq integration create gt-auth-epic
# → integration/add-user-authentication  (from epic title)

# Custom template in config: "{user}/{prefix}/{epic}"
gt mq integration create RA-123
# → klauern/RA/RA-123

# Override with --branch flag
gt mq integration create RA-123 --branch "feature/{epic}"
# → feature/RA-123
```

--------------------------------

### Display Patrol Checklist

Source: https://github.com/gastownhall/gastown/blob/main/docs/reference.md

Shows the patrol checklist inline to guide the setup process.

```bash
gt prime                    # Shows patrol checklist inline
```

--------------------------------

### Example Base Hook Configuration

Source: https://github.com/gastownhall/gastown/blob/main/docs/HOOKS.md

This JSON object represents a base configuration for session start hooks, defining a command to be executed.

```json
{
  "SessionStart": [
    { "matcher": "", "hooks": [{ "type": "command", "command": "gt prime" }] }
  ]
}
```

--------------------------------

### Git Smart HTTP Protocol Requests

Source: https://github.com/gastownhall/gastown/blob/main/docs/proxy-server.md

Examples of GET and POST requests made by git clients for cloning, fetching, and pushing.

```http
# Clone / fetch
GET  /v1/git/MyRig/info/refs?service=git-upload-pack
POST /v1/git/MyRig/git-upload-pack
```

```http
# Push
GET  /v1/git/MyRig/info/refs?service=git-receive-pack
POST /v1/git/MyRig/git-receive-pack
```

--------------------------------

### Manual Build for macOS and Windows

Source: https://github.com/gastownhall/gastown/blob/main/README.md

For macOS users encountering issues with `go install`, or for Windows users, clone the repository and build manually. Ensure the binary is added to your PATH.

```bash
# macOS: go install produces unsigned binaries that macOS will SIGKILL.
# Use brew install (above) or install Dolt and clone/build with make:
$ brew install dolt
$ git clone https://github.com/steveyegge/gastown.git && cd gastown
$ make build && mv gt $HOME/go/bin/

# Windows (or if go install fails): clone and build manually
$ git clone https://github.com/steveyegge/gastown.git && cd gastown
$ go build -o gt.exe ./cmd/gt
$ mv gt.exe $HOME/go/bin/  # or add gastown to PATH
```

--------------------------------

### Initialize Workspace and Add Project

Source: https://github.com/gastownhall/gastown/blob/main/README.md

Create a new Gas Town workspace, initialize it with Git, and add your first project by providing a name and its repository URL.

```bash
# Create workspace with git initialization
gt install ~/gt --git
cd ~/gt

# Add your first project
gt rig add myproject https://github.com/you/repo.git
```

--------------------------------

### Polecat Devcontainer Setup Script

Source: https://github.com/gastownhall/gastown/blob/main/docs/design/sandboxed-polecat-execution.md

Installs necessary tools like the Claude code assistant and the GasTown proxy client within the devcontainer.

```bash
# .devcontainer/gastown-polecat/setup.sh
set -e
npm install -g @anthropic-ai/claude-code
curl -fsSL https://releases.gastown.dev/gt-proxy-client/latest/linux-amd64 -o /usr/local/bin/gt
chmod +x /usr/local/bin/gt
ln -sf /usr/local/bin/gt /usr/local/bin/bd
apt-get install -y git
```

--------------------------------

### Local vs. Wrapped Startup Commands

Source: https://github.com/gastownhall/gastown/blob/main/docs/design/sandboxed-polecat-execution.md

Illustrates how startup commands differ between a local environment and when wrapped by exitbox or daytona execution environments.

```shell
# Local (no wrapper):
exec env GT_RIG=gastown GT_POLECAT=furiosa ... claude --mode=direct

# exitbox:
exec env GT_RIG=gastown GT_POLECAT=furiosa ... \
    exitbox run --profile=gastown-polecat -- claude --mode=direct

# daytona:
exec env GT_RIG=gastown GT_POLECAT=furiosa ... \
    daytona exec furiosa-ws -- claude --mode=direct
```

--------------------------------

### Setup Fork, Clone, and Register Rig

Source: https://github.com/gastownhall/gastown/blob/main/docs/guides/mvgt-integration.md

This script performs the one-time setup for a new repository. It forks the upstream repository, clones the fork, adds the upstream remote, and registers a new rig in the database. Ensure the fork is created manually on the DoltHub website before running.

```bash
#!/usr/bin/env bash
set -euo pipefail

UPSTREAM="steveyegge/wl-commons"
FORK_OWNER="myhandle"
CLONE_DIR="/opt/wasteland/wl-commons"

# Fork via DoltHub website (API for forking is not yet stable)
# Then clone your fork:
dolt clone "${FORK_OWNER}/wl-commons" "$CLONE_DIR"
cd "$CLONE_DIR"

# Add upstream remote
dolt remote add upstream "https://doltremoteapi.dolthub.com/${UPSTREAM}"

# Register your rig
dolt sql -q "
  INSERT INTO rigs (handle, display_name, dolthub_org, trust_level, rig_type, registered_at, last_seen)
  VALUES ('${FORK_OWNER}', 'My Rig', '${FORK_OWNER}', 0, 'human', NOW(), NOW());
"

dolt add .
dolt commit -m "Register rig: ${FORK_OWNER}"
dolt push origin main

```

--------------------------------

### CrewAI Flow Example

Source: https://github.com/gastownhall/gastown/blob/main/docs/research/w-gc-004-agent-framework-survey.md

Demonstrates a simple event-driven flow in CrewAI using @start and @listen decorators. Use this for more granular control over task execution based on events.

```python
from crewai.flow.flow import Flow, listen, start

class ResearchFlow(Flow):
    @start()
    def gather_data(self):
        return search("agent frameworks 2026")

    @listen(gather_data)      # triggered when gather_data completes
    def analyze(self, data):
        return summarize(data)
```

--------------------------------

### Example Witness Override Hook Configuration

Source: https://github.com/gastownhall/gastown/blob/main/docs/HOOKS.md

This JSON object demonstrates an override for session start hooks specifically for a witness, replacing the base configuration with a witness-specific command.

```json
{
  "SessionStart": [
    { "matcher": "", "hooks": [{ "type": "command", "command": "gt prime --witness" }] }
  ]
}
```

--------------------------------

### Manual DoltHub Setup for `gt wl join`

Source: https://github.com/gastownhall/gastown/blob/main/docs/WASTELAND.md

Workaround for `gt wl join` failures by manually cloning, registering, and pushing to DoltHub.

```bash
# Clone upstream directly
dolt clone hop/wl-commons /tmp/wl-setup/wl-commons
cd /tmp/wl-setup/wl-commons

# Register your rig (trust_level=1 matches what gt wl join sets)
dolt sql -q "INSERT INTO rigs (handle, display_name, dolthub_org, \
  trust_level, registered_at, last_seen) \
  VALUES ('$DOLTHUB_ORG', 'Your Name', '$DOLTHUB_ORG', 1, NOW(), NOW());"
dolt add -A && dolt commit -m "Register rig: $DOLTHUB_ORG"

# Push to your DoltHub org as a fork
dolt remote add myfork https://doltremoteapi.dolthub.com/$DOLTHUB_ORG/wl-commons
dolt push myfork main

# Place the clone where gt wl join would put it
mkdir -p ~/gt/.wasteland/hop
cp -r /tmp/wl-setup/wl-commons ~/gt/.wasteland/hop/wl-commons
cd ~/gt/.wasteland/hop/wl-commons

# Fix remotes: origin must point to your fork (gt wl join clones the
# fork, so origin = fork by default; our clone has origin = upstream)
dolt remote remove origin
dolt remote add origin https://doltremoteapi.dolthub.com/$DOLTHUB_ORG/wl-commons
dolt remote add upstream https://doltremoteapi.dolthub.com/hop/wl-commons

# Clean up
rm -rf /tmp/wl-setup
```

--------------------------------

### Local Build and Daemon Restart

Source: https://github.com/gastownhall/gastown/blob/main/RELEASING.md

After manual Git operations, run these commands to build, codesign, and install the project locally, then stop and start the Gas Town daemon.

```bash
make install
gt daemon stop && gt daemon start
```

--------------------------------

### Spawn Polecat Teammate

Source: https://github.com/gastownhall/gastown/blob/main/docs/design/witness-at-team-lead.md

Defines the parameters for spawning a polecat teammate, including its type, team, name, model, and prompt. The prompt guides the polecat's workflow and environment setup.

```javascript
Task({
  subagent_type: "polecat",
  team_name: "<rig>-work",
  name: "<polecat-name>",
  model: "sonnet",
  prompt: "You are polecat <name>. Your worktree is <path>.\n\nAssigned issue: <id> - <title>\n<description>\n\nWorkflow:\n1. cd <worktree>\n2. Run `gt prime` for full context\n3. Follow mol-polecat-work steps\n4. When done: commit, push, run `gt done`"
})
```

--------------------------------

### Informational Hook Instructions for Copilot

Source: https://github.com/gastownhall/gastown/blob/main/docs/agent-provider-integration.md

Markdown content for informational hooks, providing startup instructions for agents that read instruction files. It guides the agent to run 'gt prime' on session start or after compaction.

```markdown
# Gas Town Agent Context

You are running inside Gas Town, a multi-agent workspace manager.

## Startup Protocol

On session start or after compaction, run:
\`\`\`
gt prime
\`\`\`
This loads your full role context, mail, and pending work.

```

--------------------------------

### Example plugin.md File Structure

Source: https://github.com/gastownhall/gastown/blob/main/docs/design/plugin-system.md

Illustrates the basic file structure for a plugin, with a TOML frontmatter definition and markdown instructions.

```markdown
rebuild-gt/
└── plugin.md      # Definition with TOML frontmatter
```

--------------------------------

### Full Provisioning Sequence at `gt sling`

Source: https://github.com/gastownhall/gastown/blob/main/docs/design/sandboxed-polecat-execution.md

Details the step-by-step process initiated by `gt sling` for provisioning a Daytona workspace. This includes creating a polecat branch, issuing certificates, provisioning the Daytona workspace, injecting certificates, post-create setup, registering the agent, and starting a tmux pane for direct mode execution.

```text
gt sling <bead> --daytona
  │
  ├─ 1. Create polecat branch (host, instant):
  │       git -C ~/gt/<rig>/.repo.git fetch origin
  │       git -C ~/gt/<rig>/.repo.git branch polecat/<name>-<ts> origin/main
  │
  ├─ 2. Issue polecat mTLS cert (host, instant)
  │
  ├─ 3. Provision daytona workspace (slow: 30–120s):
  │       daytona create https://<host>:9876/v1/git/<rig>
  │         --name gt-<rig>-<polecat>
  │         --branch polecat/<name>-<ts>
  │         --devcontainer-path .devcontainer/gastown-polecat
  │       (clones from proxy → .repo.git; runs onCreateCommand)
  │
  ├─ 4. Inject cert into workspace:
  │       daytona exec gt-<rig>-<polecat> -- mkdir -p /run/gt-proxy
  │       daytona exec gt-<rig>-<polecat> -- tee /run/gt-proxy/client.crt < <cert>
  │       daytona exec gt-<rig>-<polecat> -- tee /run/gt-proxy/client.key < <key>
  │       daytona exec gt-<rig>-<polecat> -- tee /run/gt-proxy/ca.crt < <ca>
  │
  ├─ 5. Post-create setup:
  │       daytona exec gt-<rig>-<polecat> -- gt prime --write-prime-md
  │       daytona exec gt-<rig>-<polecat> -- [overlay files, setup hooks]
  │
  ├─ 6. Register agent bead via proxy:
  │       (proxy client calls bd create/update with state=spawning)
  │
  └─ 7. Start tmux pane:
          tmux new-window -n <polecat>
          tmux send-keys "daytona exec gt-<rig>-<polecat> \
            --env GT_RIG=<rig> --env GT_POLECAT=<name> \
            --env GT_PROXY_URL=... --env GT_PROXY_CERT=... \
            --env GT_PROXY_KEY=... --env GIT_SSL_CERT=... \
            --env GIT_SSL_KEY=... --env GIT_SSL_CAINFO=... \
            -- claude --mode=direct" Enter

```

--------------------------------

### Initialize Mol Mall Publishing

Source: https://github.com/gastownhall/gastown/blob/main/docs/design/mol-mall-design.md

Run this command to set up Mol Mall publishing for the first time. It guides you through account creation, API token generation, and logging in.

```bash
$ gt formula publish --init

Setting up Mol Mall publishing...

1. Create account at https://molmall.gastown.io/signup
2. Generate API token at https://molmall.gastown.io/settings/tokens
3. Run: gt formula login

$ gt formula login
Token: ********
Logged in as: steve@gastown.io
```

--------------------------------

### Agent Step Rendering Example

Source: https://github.com/gastownhall/gastown/blob/main/docs/concepts/molecules.md

Shows how agents interact with formula steps, which are rendered inline as a checklist when `gt prime` is executed, rather than using explicit commands for each step.

```text
**Formula Checklist** (10 steps from mol-polecat-work):

### Step 1: Load context and verify assignment
Initialize your session and understand your assignment...

### Step 2: Set up working branch
Ensure you're on a clean feature branch...
```

--------------------------------

### Verify npm Installation

Source: https://github.com/gastownhall/gastown/blob/main/RELEASING.md

Commands to check the installed version of the @gastown/gt npm package and install it globally.

```bash
npm view @gastown/gt version
npm install -g @gastown/gt
gt version
```

--------------------------------

### Install Client Binary in Container

Source: https://github.com/gastownhall/gastown/blob/main/docs/proxy-server.md

Copies the gt-proxy-client binary into the container's PATH. Two options are provided: copying twice or copying once and creating symbolic links.

```bash
# Option A: Copy the binary twice
cp gt-proxy-client /usr/local/bin/gt
cp gt-proxy-client /usr/local/bin/bd

# Option B: Copy once and symlink
cp gt-proxy-client /usr/local/bin/gt-proxy-client
ln -s gt-proxy-client /usr/local/bin/gt
ln -s gt-proxy-client /usr/local/bin/bd

# If the real gt binary should be accessible as a fallback:
mv /usr/local/bin/gt.original /usr/local/bin/gt.real
```

--------------------------------

### Install Dolt CLI on macOS

Source: https://github.com/gastownhall/gastown/blob/main/docs/guides/mvgt-integration.md

Installs the Dolt CLI on macOS using the Homebrew package manager. Ensure Homebrew is installed.

```bash
brew install dolt
```

--------------------------------

### Witness Startup Flow

Source: https://github.com/gastownhall/gastown/blob/main/docs/design/witness-at-team-lead.md

Illustrates the sequence of operations when a Witness session starts, from daemon management to work handling and teammate spawning.

```text
Witness session starts (managed by daemon)
    │
    ├── SessionStart hook: gt prime --hook
    │   └── Loads role context, checks hook
    │
    ├── Check for work:
    │   ├── gt mail inbox (convoy dispatch, priority changes)
    │   ├── bd ready (unblocked issues)
    │   └── gt hook (hooked work)
    │
    ├── If work available:
    │   │
    │   ├── Create AT team:
    │   │   Teammate({ operation: "spawnTeam", team_name: "<rig>-work" })
    │   │
    │   ├── Create AT tasks from beads issues:
    │   │   For each issue: TaskCreate({ subject, description, metadata: { bead_id } })
    │   │   Set dependencies: TaskUpdate({ addBlockedBy: [...] })
    │   │
    │   ├── Create worktrees for polecats:
    │   │   For each polecat: git worktree add ...
    │   │
    │   ├── Spawn polecat teammates:
    │   │   For each (up to max_teammates):
    │   │     Task({ subagent_type: "polecat", team_name: "...", name: "..." })
    │   │
    │   └── Enter monitoring loop:
    │       ├── Watch AT task list for completions
    │       ├── Handle teammate crashes (SubagentStop)
    │       ├── Relay gt mail ↔ AT messages
    │       ├── Check for new convoy arrivals
    │       └── When all tasks done: cleanup and report
    │
    └── If no work:
        └── Stop hook checks for queued work periodically
            └── If work arrives: wake and create team
```

--------------------------------

### Install Dolt CLI on Linux

Source: https://github.com/gastownhall/gastown/blob/main/docs/guides/mvgt-integration.md

Installs the Dolt CLI on Linux systems using a script from GitHub. Ensure you have bash and curl installed.

```bash
sudo bash -c 'curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash'
```

--------------------------------

### Project-Wide Maintenance Example

Source: https://github.com/gastownhall/gastown/blob/main/docs/design/property-layers.md

Illustrates using 'gt rig dock' and 'gt rig undock' for project-wide maintenance, ensuring all clones pause and then resume operation. Includes a 'bd sync' command for broader synchronization.

```bash
# Major refactor in progress, all clones should pause
gt rig dock gastown

# Syncs via git - other towns see the rig as docked
bd sync

# When done:
gt rig undock gastown
bd sync
```

--------------------------------

### Go Project Build Pipeline Configuration

Source: https://github.com/gastownhall/gastown/blob/main/docs/concepts/integration-branches.md

Example configuration for a Go project, specifying test, lint, and build commands. Other commands are empty by default.

```json
{
  "merge_queue": {
    "test_command": "go test ./...",
    "lint_command": "golangci-lint run ./...",
    "build_command": "go build ./..."
  }
}
```

--------------------------------

### Install Dolt on Windows

Source: https://github.com/gastownhall/gastown/blob/main/docs/guides/mvgt-integration.md

Install Dolt on Windows using Chocolatey or by downloading the MSI.

```powershell
choco install dolt
```

--------------------------------

### Install Gastown via Homebrew Core

Source: https://github.com/gastownhall/gastown/blob/main/RELEASING.md

Installs Gastown from the main homebrew-core repository.

```bash
brew install gastown
```

--------------------------------

### Manage Installed Formulas

Source: https://github.com/gastownhall/gastown/blob/main/docs/design/formula-resolution.md

Commands like `gt formula list --installed`, `gt formula upgrade`, `gt formula pin`, and `gt formula uninstall` are used to manage formulas that have been installed locally.

```bash
# Manage installed formulas
gt formula list --installed              # What's in town-level
gt formula upgrade mol-polecat-work      # Update to latest
gt formula pin mol-polecat-work@4.0.0    # Lock version
gt formula uninstall mol-code-review-strict
```

--------------------------------

### Install Polecat PR Flow Harness

Source: https://github.com/gastownhall/gastown/blob/main/docs/contrib-harnesses/polecat-pr-flow/README.md

Installs the role directive and formula overlay for the polecat PR flow. Replace `<rig>` with your rig's name. For town-wide installation, omit the `<rig>/` segment, but this is rarely recommended.

```bash
# Role directive (rig-scoped)
mkdir -p ~/gt/<rig>/directives
cp polecat.md ~/gt/<rig>/directives/polecat.md

# Formula overlay (rig-scoped)
mkdir -p ~/gt/<rig>/formula-overlays
cp mol-polecat-work.toml ~/gt/<rig>/formula-overlays/mol-polecat-work.toml
```

--------------------------------

### Parameter Usage in Sandbox Profiles

Source: https://github.com/gastownhall/gastown/blob/main/docs/research/macos-sandbox-exec.md

Illustrates how to use parameters passed via the command line within sandbox profiles for dynamic configuration.

```scheme
;; CLI: sandbox-exec -D KEY=value -f profile.sb command
(allow file-read* file-write* (subpath (param "PROJECT_DIR")))

;; Conditional logic
(if (equal? (param "FEATURE") "YES")
  (allow network-outbound))
```

--------------------------------

### Local Maintenance Example

Source: https://github.com/gastownhall/gastown/blob/main/docs/design/property-layers.md

Shows how to use 'gt rig park' and 'gt rig unpark' to prevent service restarts during local maintenance.

```bash
# I'm upgrading the local clone, don't restart services
gt rig park gastown

# ... do maintenance ...

gt rig unpark gastown
```

--------------------------------

### Initialize Base Configuration

Source: https://github.com/gastownhall/gastown/blob/main/docs/HOOKS.md

Bootstraps the base configuration and overrides by analyzing existing `settings.local.json` files. This command only works when no base config exists. Use `--dry-run` to preview the actions.

```bash
gt hooks init             # Bootstrap base and overrides
gt hooks init --dry-run   # Preview what would be created
```

--------------------------------

### Verify Homebrew Installation

Source: https://github.com/gastownhall/gastown/blob/main/RELEASING.md

Commands to update Homebrew, check the installed Gastown version, and upgrade if necessary.

```bash
brew update
brew info gastown    # Check version
brew upgrade gastown # Upgrade if installed
```

--------------------------------

### Creating a Plugin Run Wisp

Source: https://github.com/gastownhall/gastown/blob/main/docs/design/plugin-system.md

Example of creating a wisp on the ledger to record a plugin run's outcome and metadata.

```bash
bd create --wisp-type patrol \
  --labels type:plugin-run,plugin:rebuild-gt,rig:gastown,result:success \
  --description "Rebuilt gt: abc123 → def456 (5 commits)" \
  "Plugin: rebuild-gt [success]"
```

--------------------------------

### Polecat Startup Protocol

Source: https://github.com/gastownhall/gastown/blob/main/internal/templates/polecat-CLAUDE.md

Steps to follow when starting a Polecat agent, including announcements, running prime, and checking hooks.

```bash
# 1. Announce: "Polecat {{name}}, checking in."
gt prime
gt hook
```

--------------------------------

### Install Gastown via Homebrew Tap

Source: https://github.com/gastownhall/gastown/blob/main/RELEASING.md

Installs Gastown using the dedicated gastownhall/gastown Homebrew tap.

```bash
brew install gastownhall/gastown/gastown
```