### Install and Prepare Gas City Example

Source: https://github.com/gastownhall/gascity/blob/main/examples/t3bridge-gastown/README.md

Install the Gas City CLI and copy the t3bridge-gastown example into a temporary directory. This sets up the necessary files for running the example.

```sh
go install ./cmd/gc
tmp="$(mktemp -d)"
cp -R examples/t3bridge-gastown "$tmp/city"
```

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

### Initialize Lifecycle Demo

Source: https://github.com/gastownhall/gascity/blob/main/examples/lifecycle/README.md

Initializes a new demo city from the lifecycle example and starts the service.

```bash
gc init --from examples/lifecycle ~/demo-city
cd ~/demo-city
gc start
```

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

### Install Gas City Binary to PATH

Source: https://github.com/gastownhall/gascity/blob/main/docs/getting-started/troubleshooting.md

If the `gc` command is not found after installation, ensure the binary is in a directory listed in your system's PATH. This example shows how to install it to `~/.local/bin/gc`.

```bash
install -m 755 gc ~/.local/bin/gc   # or /usr/local/bin/gc
```

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

### Setup Local Tools and Git Hooks

Source: https://github.com/gastownhall/gascity/blob/main/CONTRIBUTING.md

Installs necessary local development tools and configures git hooks for automated formatting and checks.

```bash
make setup
```

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

### Route Existing Bead Example

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

Example of routing an existing bead to a target.

```bash
gc sling my-rig/claude BL-42
```

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

### Build and Install Gas City from Source

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

Builds Gas City from source using make and then installs it. Assumes Go 1.25+ is available.

```bash
make install
```

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

### Pool Agent Configuration Example

Source: https://github.com/gastownhall/gascity/blob/main/engdocs/architecture/dispatch.md

Example configuration for a pool agent, demonstrating pool settings and default query generation.

```toml
[[agent]]
name = "coder"
pool = { min = 1, max = 3, check = "echo 2" }
# Default sling_query: bd update {} --set-metadata gc.routed_to=coder
# Default work_query: bd ready --include-ephemeral --metadata-field gc.routed_to=coder
#   --unassigned --exclude-type=epic --json --sort oldest --limit=1,
```

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

### Example Command Usage

Source: https://github.com/gastownhall/gascity/blob/main/engdocs/design/packv2/doc-commands.md

Concrete examples of using commands exposed through import bindings. The first word after 'gc' represents the import binding.

```text
gc gastown status
gc gs status
gc dolt sql
```

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

### Route Bead from Text Example

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

Example of creating a bead from inline text and routing it to a target.

```bash
gc sling my-rig/claude "write a README"
```

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

### Start Operation JSON Configuration

Source: https://github.com/gastownhall/gascity/blob/main/docs/reference/exec-session-provider.md

The 'start' operation receives a JSON object on stdin detailing the session configuration. All fields are optional and can be omitted when empty.

```json
{
  "work_dir": "/path/to/working/directory",
  "command": "claude --dangerously-skip-permissions",
  "env": {"GC_AGENT": "mayor", "GC_CITY": "/home/user/bright-lights"},
  "lifecycle": "one_shot",
  "process_names": ["claude", "node"],
  "nudge": "initial prompt text",
  "pre_start": ["mkdir -p /workspace", "git clone repo /workspace"]
}
```

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

### Preview Documentation Locally

Source: https://github.com/gastownhall/gascity/blob/main/CONTRIBUTING.md

Navigates to the docs directory and starts a local development server to preview Mintlify-based documentation.

```bash
cd docs && ./mint.sh dev
```

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

### Pack V2 Command Structure Example

Source: https://github.com/gastownhall/gascity/blob/main/engdocs/design/packv2/doc-commands.md

Illustrates the default script-backed command structure where 'run.sh' is the entrypoint.

```text
commands/status/
└── run.sh
```

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

### Install Gas City Supervisor Service

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

Installs the machine-wide supervisor as a platform service that starts automatically on login.

```bash
gc supervisor install
```

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

### Agent Endpoints Example

Source: https://github.com/gastownhall/gascity/blob/main/plans/archive/huma-openapi-migration-history.md

Provides concrete examples of input and output types for agent-related API operations, including GET, CREATE, and UPDATE.

```APIDOC
## Agent Endpoints Example

### Description
This section details the input and output structures for agent-related API operations, demonstrating how Huma defines API contracts using Go types.

### Input Types

#### AgentGetInput
```go
type AgentGetInput struct {
    Name string `path:"name" doc:"Agent name" example:"deacon-1"`
}
```

#### AgentCreateInput
```go
type AgentCreateInput struct {
    Body struct {
        Name     string `json:"name" minLength:"1" doc:"Agent name"`
        Provider string `json:"provider,omitempty" doc:"Provider name"`
        Dir      string `json:"dir,omitempty" doc:"Working directory"`
    }
}
```

#### AgentUpdateInput
```go
type AgentUpdateInput struct {
    Name string `path:"name" doc:"Agent name"`
    Body struct {
        Provider  string `json:"provider,omitempty"`
        Suspended *bool  `json:"suspended,omitempty"`
    }
}
```

### Output Types

#### AgentResponse
```go
type AgentResponse struct {
    Name        string       `json:"name" doc:"Agent name"`
    Description string       `json:"description,omitempty" doc:"Agent description"`
    Running     bool         `json:"running" doc:"Whether agent is actively running"`
    Suspended   bool         `json:"suspended" doc:"Whether agent is suspended"`
    Rig         string       `json:"rig,omitempty" doc:"Associated rig"`
    Pool        string       `json:"pool,omitempty" doc:"Pool membership"`
    Provider    string       `json:"provider,omitempty" doc:"Provider name"`
    State       string       `json:"state,omitempty" doc:"Current state"`
    Session     *SessionInfo `json:"session,omitempty" doc:"Active session info"`
}
```

### Handler Example (Agent List)
```go
// GET /v0/agents handler:
func (s *Server) handleAgentList(ctx context.Context, input *AgentListInput) (*ListOutput[AgentResponse], error) {
    // ... business logic ...
    return &ListOutput[AgentResponse]{
        Index: idx,
        Body: struct {
            Items      []AgentResponse `json:"items"`
            Total      int             `json:"total"`
            NextCursor string          `json:"next_cursor,omitempty"`
        }{Items: agents, Total: len(agents)},
    }, nil
}
```
```

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

### Initialize Dashboard with API

Source: https://github.com/gastownhall/gascity/blob/main/engdocs/design/machine-wide-supervisor-v0.md

Command to connect the dashboard to the supervisor API.

```bash
gc dashboard --api http://localhost:8080
# Queries GET /v0/cities, picks the first one,
# prefixes all API calls with /v0/city/{name}/...
# City switcher is follow-on work.
```

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

### Initialize and Start Gas City Project

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

Initializes a new Gas City project in a specified directory, starts the Gas City service, and adds the current directory as a rig.

```bash
gc init ~/bright-lights
cd ~/bright-lights
gc start

mkdir hello-world
cd hello-world
git init
gc rig add .
```

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

### Agent Patch Definition

Source: https://github.com/gastownhall/gascity/blob/main/docs/guides/understanding-packs.md

Applies a patch to an existing agent, modifying its properties. This example changes the provider and appends to session setup.

```toml
[[patches.agent]]
name = "reviewer"
provider = "codex"
session_setup_append = ["tmux set status-left '[review]' "]

```

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

### Basic Testscript Example

Source: https://github.com/gastownhall/gascity/blob/main/TESTING.md

This example demonstrates initializing a city, adding a rig, creating a build, and asserting the expected stdout for each command. It uses fake backend defaults for session, beads, and dolt.

```bash
env GC_SESSION=fake

exec gc init $WORK/bright-lights
stdout 'City initialized'

exec gc rig add $WORK/tower-of-hanoi
stdout 'Adding rig'

exec bd create 'Build a Tower of Hanoi app'
stdout 'status: open'
```

```text
-- $WORK/tower-of-hanoi/.git/HEAD --
ref: refs/heads/main
```

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

### Enhanced Agent Status Response

Source: https://github.com/gastownhall/gascity/blob/main/engdocs/design/api-ops-design.md

This is an example of an enhanced response from GET /v0/agent/{name}. It provides detailed runtime status and configuration information for an agent.

```json
{
  "name": "payments/reviewer-1",
  "running": true,
  "suspended": false,
  "draining": false,
  "quarantined": false,
  "drift_detected": false,
  "origin": "inline",
  "provider": "claude",
  "pool": "payments/reviewer",
  "rig": "payments",
  "config_hash": "abc123",
  "restart_count": 2,
  "idle_timeout": "30m",
  "session": {
    "name": "city--payments--reviewer-1",
    "last_activity": "2026-03-06T10:30:00Z",
    "attached": false,
    "uptime": "2h15m"
  },
  "active_bead": "pay-42"
}
```

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

### Provider Resolution Example

Source: https://github.com/gastownhall/gascity/blob/main/engdocs/design/provider-inheritance.md

Illustrates the accumulation of 'args' and 'args_append' across provider inheritance layers. Shows how 'args' replaces and 'args_append' extends the command line arguments.

```go
builtin codex:         args = nil,    args_append = nil     → []
[providers.codex]:     args = ["run","codex","--"]           → ["run","codex","--"]
                       args_append = nil
[providers.codex-max]: args = nil,    args_append = ["-m","gpt-5.4"]
                                                             → ["run","codex","--","-m","gpt-5.4"]
```

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

### Initialize a Gas City

Source: https://github.com/gastownhall/gascity/blob/main/docs/getting-started/quickstart.md

Bootstrap a new city directory, register it with the supervisor, and start the controller.

```bash
gc init ~/bright-lights
cd ~/bright-lights
```

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

### Verify Gas City Installation

Source: https://github.com/gastownhall/gascity/blob/main/docs/getting-started/installation.md

After installation, run this command to verify that Gas City is installed correctly and to check its version. This is useful for confirming a successful Homebrew installation or direct download.

```bash
gc version
```

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

### Start mcp_agent_mail and Gas City

Source: https://github.com/gastownhall/gascity/blob/main/contrib/mail-scripts/README.md

Commands to start the mcp_agent_mail server and then start the Gas City service using it as the mail backend. Ensure mcp_agent_mail is running in a separate terminal before starting Gas City.

```bash
# Start mcp_agent_mail server (separate terminal)
am  # or: uv run python -m mcp_agent_mail.http

# Start city with mcp_agent_mail as mail backend
GC_MAIL=exec:contrib/mail-scripts/gc-mail-mcp-agent-mail \
  gc start --foreground
```

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

### Agent Configuration Example

Source: https://github.com/gastownhall/gascity/blob/main/engdocs/architecture/prompt-templates.md

Illustrates how an agent's configuration points to a prompt template file.

```toml
prompt_template = "prompts/agent.template.md"
```

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

### Route Registration: After

Source: https://github.com/gastownhall/gascity/blob/main/plans/archive/huma-openapi-migration-history.md

Demonstrates Huma's declarative approach to route registration using `huma.Get`.

```go
huma.Get(api, "/v0/agents", s.handleAgentList)
```

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

### Install Gas City from Homebrew

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

Installs the Gas City CLI using Homebrew and verifies the installation by checking the version.

```bash
brew install gastownhall/gascity/gascity
gc version
```

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

### Install Gas City with Homebrew

Source: https://github.com/gastownhall/gascity/wiki/Home

Installs the Gas City CLI using Homebrew. Ensure Homebrew is installed and updated before running.

```sh
brew install gastownhall/gascity/gascity
```

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

### Start Agent Session Request Body

Source: https://github.com/gastownhall/gascity/blob/main/engdocs/design/api-ops-design.md

Use this JSON to start agent sessions. For pool agents, you can specify the number of instances to start.

```json
{"count": 2}
```

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

### Preview Application Locally

Source: https://github.com/gastownhall/gascity/blob/main/release-gates/ga-a6tul7-native-beads-store-selection-e2e-gate.md

Starts a local preview of the application using npm, binding it to a specific host and port. Use this to test the frontend in a development environment.

```text
npm run preview -- --host 127.0.0.1 --port 4187
```

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

### Molecule Instantiation via MolCook

Source: https://github.com/gastownhall/gascity/blob/main/engdocs/architecture/beads.md

Describes the process of molecule instantiation, including how BdStore shells out to the 'bd' CLI, MemStore creates a root bead, and exec.Store resolves and composes formulas.

```go
MolCook(formulaName, title, vars)
  --> BdStore: shells out to "bd mol cook --formula=<name>"
  --> MemStore: creates a bead with Type="molecule", Ref=formulaName
  --> exec.Store (with resolver): calls formula.ComposeMolCook which:
      1. Resolves the formula by name
      2. Substitutes {{key}} vars in step descriptions
      3. Creates root bead (type="molecule", Ref=formulaName)
      4. Creates one child bead per step (type="task", ParentID=root, Ref=stepID)
      --> returns root bead ID
```

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

### Capture GC Start Failure Log

Source: https://github.com/gastownhall/gascity/blob/main/docs/troubleshooting/gc-start-walkthrough.mdx

Redirect standard error to 'gc-start.log' when running 'gc start' to capture detailed output for troubleshooting failed starts.

```bash
gc start 2> gc-start.log
```

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

### Install Gas City via Homebrew Core (Future)

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

This is the intended long-term installation path via Homebrew core. Users will eventually be able to install Gas City with this command.

```bash
brew install gascity
```

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

### Run Go Tests for Documentation Sync and Examples

Source: https://github.com/gastownhall/gascity/blob/main/release-gates/ga-hivi-probe-user-db-gate.md

Execute Go tests for the documentation sync module and example directories. The `-count=1` flag ensures each test runs only once.

```go
go test ./test/docsync -count=1
```

```go
go test ./examples/dolt ./examples/gastown -count=1
```

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

### Install flock on macOS

Source: https://github.com/gastownhall/gascity/blob/main/docs/getting-started/troubleshooting.md

Installs the flock package on macOS using Homebrew.

```bash
brew install flock
```

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

### Initialize Sling with Dependencies

Source: https://github.com/gastownhall/gascity/blob/main/plans/archive/shared-object-model-ops-layer.md

Instantiate the sling client with necessary dependencies. This should be done once to validate dependencies.

```go
s, _ := sling.New(deps)
```

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

### Initialize a New City with Interactive Prompts

Source: https://github.com/gastownhall/gascity/blob/main/docs/tutorials/01-cities-and-rigs.md

Use `gc init` to create a new city. This command guides you through selecting a configuration template and a coding agent.

```shell
~
$ gc init ~/my-city
Welcome to Gas City SDK!

Choose a config template:
  1. minimal   — default coding agent (default)
  2. gastown   — multi-agent orchestration pack
  3. custom    — empty workspace, configure it yourself
Template [1]:

Choose your coding agent:
  1. Claude Code  (default)
  2. Codex CLI
  3. Gemini CLI
  4. Cursor Agent
  5. GitHub Copilot
  6. Sourcegraph AMP
  7. OpenCode
  8. Auggie CLI
  9. Pi Coding Agent
  10. Oh My Pi (OMP)
  11. Custom command
Agent [1]:
[1/8] Creating runtime scaffold
[2/8] Installing hooks (Claude Code)
[3/8] Scaffolding agent prompts
[4/8] Writing pack.toml
[5/8] Writing city configuration
Created minimal config (Level 1) in "my-city".
[6/8] Checking provider readiness
[7/8] Registering city with supervisor
Registered city 'my-city' (/Users/csells/my-city)
Installed launchd service: /Users/csells/Library/LaunchAgents/com.gascity.supervisor.plist
[8/8] Waiting for supervisor to start city

~
$ gc cities
NAME        PATH
my-city     /Users/csells/my-city

```

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

### Install dolt on macOS

Source: https://github.com/gastownhall/gascity/blob/main/docs/getting-started/troubleshooting.md

Installs the dolt package on macOS using Homebrew.

```bash
brew install dolt
```

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

### Install jq on macOS

Source: https://github.com/gastownhall/gascity/blob/main/docs/getting-started/troubleshooting.md

Installs the jq package on macOS using Homebrew.

```bash
brew install jq
```

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

### Install tmux on macOS

Source: https://github.com/gastownhall/gascity/blob/main/docs/getting-started/troubleshooting.md

Installs the tmux package on macOS using Homebrew.

```bash
brew install tmux
```

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

### Bash Autocompletion Script Setup

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

Provides instructions and commands for setting up bash autocompletion for gc. This involves sourcing the completion script in the current session or saving it to a system directory for persistent completion.

```bash
source <(gc completion bash)
```

```bash
gc completion bash > /etc/bash_completion.d/gc
```

```bash
gc completion bash > $(brew --prefix)/etc/bash_completion.d/gc
```

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

### Storage Layout Example

Source: https://github.com/gastownhall/gascity/blob/main/engdocs/design/packv2/doc-packman.md

Illustrates the directory structure for a PackV2 city, including configuration files, the lock file, and the local cache.

```text
my-city/
├── pack.toml
├── city.toml
├── packs.lock
└── .gc/
    └── cache/
        └── repos/
            ├── <sha256(normalized-clone-url+commit)>/
            └── ...

```

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

### Install pack imports

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

Installs pack imports defined in pack.toml and packs.lock files.

```bash
gc import install
```

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

### Example Named Session Configurations

Source: https://github.com/gastownhall/gascity/blob/main/engdocs/design/session-model-unification.md

Demonstrates how to declare named sessions, specifying their backing agent configuration and operational mode. Multiple named sessions can share a single agent configuration.

```toml
[["agent"]]
name = "reviewer"

[[named_session]]
name = "mayor"
template = "reviewer"
mode = "on_demand"

[[named_session]]
name = "triage"
template = "reviewer"
mode = "always"
```

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

### Start the City

Source: https://github.com/gastownhall/gascity/blob/main/test/acceptance/tutorial_goldens/testdata/140d5ac39/docs/tutorials/07-orders.md

Command to start the City environment. This is a prerequisite for interacting with other City commands.

```shell
~/my-city
$ gc start
City 'my-city' started
```

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

### Route Registration: Before

Source: https://github.com/gastownhall/gascity/blob/main/plans/archive/huma-openapi-migration-history.md

Shows the traditional method of registering routes with `http.ServeMux`.

```go
s.mux.HandleFunc("GET /v0/agents", s.handleAgentList)
```

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

### Route Formula Wisp Example

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

Example of instantiating a formula into a wisp and routing it to a target.

```bash
gc sling mayor code-review --formula
```

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

### Mail check examples

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

Examples demonstrating how to use the 'gc mail check' command.

```bash
gc mail check
  gc mail check --inject
  gc mail check mayor
```

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

### Start a Gas City Instance

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

Starts a Gas City instance. Requires an existing city bootstrapped by 'gc init'. It fetches remote packs, registers the city, ensures the supervisor is running, and triggers reconciliation. Use 'gc supervisor run' for foreground operation.

```bash
gc start [path] [flags]
```

```bash
gc start
  gc start ~/my-city
  gc start --dry-run
  gc supervisor run
```

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

### Install gh CLI on macOS

Source: https://github.com/gastownhall/gascity/blob/main/docs/getting-started/troubleshooting.md

Installs the GitHub CLI (`gh`) on macOS using Homebrew.

```bash
brew install gh
```

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

### Install lsof on Debian/Ubuntu

Source: https://github.com/gastownhall/gascity/blob/main/docs/getting-started/troubleshooting.md

Installs the lsof package on Debian or Ubuntu systems using apt.

```bash
apt install lsof
```

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

### Rig Registry Model Example

Source: https://github.com/gastownhall/gascity/blob/main/engdocs/design/packv2/doc-rig-binding-phases.md

Illustrates the TOML structure for a shared rig directory, including its path, bindings, and default binding.

```toml
[[rigs]]
path = "/Users/dbox/src/shared-rig"

bindings = [
  { city = "/Users/dbox/repos/gc/cities/backstage", rig = "api-server" },
  { city = "/Users/dbox/repos/gc/cities/switchboard", rig = "api-server" },
]

default_binding = { city = "/Users/dbox/repos/gc/cities/backstage", rig = "api-server" }
```

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

### Install git on Debian/Ubuntu

Source: https://github.com/gastownhall/gascity/blob/main/docs/getting-started/troubleshooting.md

Installs the git package on Debian or Ubuntu systems using apt.

```bash
apt install git
```

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

### Install and Run Dashboard SPA

Source: https://github.com/gastownhall/gascity/blob/main/cmd/gc/dashboard/web/README.md

Commands to install dependencies, regenerate schema types, type check, build, and run the development server for the dashboard SPA.

```bash
npm install          # one-time
npm run gen          # regenerate src/generated/schema.d.ts from the spec
npm run typecheck    # tsc --noEmit
npm run build        # Vite production build → dist/
npm run dev          # Vite dev server with HMR on :5173
```

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

### Route Bead from Stdin Example

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

Example of reading bead text from stdin and routing it to a target.

```bash
echo "fix login" | gc sling mayor --stdin
```