Skip to content

STD-GC-002: Gas City CLI-First Operating Standard

Core Rule

UPSTREAM CLI FIRST.
If gc or bd owns an operation, use it.
Only modify source/config when the CLI operation represents runtime convergence
from that source.
Do not reproduce upstream behavior with shell scripts.

Gas City Docs Authority

Context Resolution Precedence

Gas City's resolver:

explicit --context / --city-url
↓
explicit environment (GC_CITY, etc.)
↓
local city discovered from CWD
↓
sticky default context
  • Inside a City checkout, gc --context oracle ... for Oracle operations.
  • Do NOT delete city.toml or .gc/ to defeat normal CWD discovery.
  • Do NOT treat CWD precedence as a defect.

Native Command Map

Need Native Command
What City will this command target? gc context current
Configure remote Oracle gc context add/use/show/list
Show registered local Cities gc cities list
Remove Mac supervisor registration gc unregister <path>
Stop a local City cleanly gc stop <path>
Validate resolved config gc config show --validate
Config provenance gc config show --provenance
Explain agent provider gc config explain --agent <name>
Explain provider inheritance gc config explain --provider <name>
Bind City to external Dolt gc beads city use-external --host --port
Preview that bind gc beads city use-external ... --dry-run
Return rig to City inheritance gc rig set-endpoint <rig> --inherit
Preview rig endpoint change gc rig set-endpoint <rig> --inherit --dry-run
Inspect rigs gc rig list --json / gc rig status <rig>
Adopt existing rig gc rig add <path> --adopt
Remote rig provisioning gc rig add --git-url ...
Check Beads provider gc beads health --json
City-wide Beads listing gc beads list
City-wide ready queue UNAVAILABLE in pinned gc 1.4.2
Beads ready queue bd ready, scoped through gc bd where required
Agent routed work gc hook <agent>
Dependency graph gc graph
Correct rig-scoped bd gc bd --rig <rig> <command>
Force HQ bd scope gc bd --city /path/to/city <command>
Beads effective backend bd context
Beads location bd where
DB details bd info
Connectivity bd ping
Diagnostics bd doctor
First-time Beads workspace bd init
Existing-workspace recovery bd bootstrap
Schema/layout upgrade bd migrate <prescribed operation>
GitLab integration gc bd gitlab status/projects/pull/push/sync

Prohibited Operations

Do NOT hand-edit:

  • .beads/config.yaml endpoint fields
  • .beads/dolt-server.port
  • .gc/runtime/packs/dolt/*
  • Dolt pid files
  • Supervisor registries

Do NOT run:

  • bd dolt start (rig-local Dolt server)
  • bd dolt set port
  • bd init on an existing Bluefly scope / recovery (use bd bootstrap)
  • bd rename-prefix without a proven migration contract
  • gc beads city use-managed (not the Bluefly target)
  • gc beads city migrate-proxied without proven preconditions

--dolt-auto-commit

This flag requires a value: off, on, or batch. Default is on.

# WRONG
bd list --dolt-auto-commit

# RIGHT
bd list --dolt-auto-commit=on

UPSTREAM_FIRST Gate

Before adding ANY script, wrapper, hook, daemon, sync utility, or recovery helper:

REQUIRED_CAPABILITY=
GC_NATIVE_COMMAND=
BD_NATIVE_COMMAND=
WHY_NATIVE_IS_INSUFFICIENT=
UPSTREAM_ISSUE=
CUSTOM_CODE_REQUIRED=YES|NO

If the capability exists natively: CUSTOM_CODE_REQUIRED=NO. Use it.

Mac Factory Authority Gate

ALLOWED ON MAC:
  git | ddev | composer/npm | local OS/fs inspection
  gc --context oracle <SUPPORTED REMOTE COMMAND>

FORBIDDEN AS FACTORY AUTHORITY ON MAC:
  bare gc | bare bd
  gc cities | gc supervisor | gc start | gc rig add
  bd ready | bd list | bd context | bd prime (as Factory selector)
  local Dolt | local Beads mutation | local City/session/claim/sling

If a gc operation does not support --context oracle, do NOT fall back to running it locally. Route to Mayor or an admitted Agent on Oracle.

Bluefly Target Topology

City runtime:       Oracle /opt/bluefly/blucity
Canonical Dolt:     127.0.0.1:3308
City database:      hq
Rig endpoints:      inherited_city
Rig databases:      dedicated per rig (from beads-topology.yaml)
Gas City runtime:   YES
Gas Town runtime:   NO

Gas Town Retirement

Gas Town roles and mechanics became configuration on Gas City. Mayor, Witness, Deacon, Polecat are configured agents/behaviors. Orchestration belongs to Gas City.

Before retiring any legacy component:

  1. Inventory every component
  2. Determine whether Gas City currently consumes it
  3. Separate SERVICE FUNCTION from LEGACY SERVICE NAME
  4. If dolt-gt.service owns canonical 3308, transfer lifecycle ownership to governed Gas City/Bluefly IaC — do NOT move or destroy the database

GitLab Integration

Before building or maintaining custom GitLab-Beads synchronization:

gc bd gitlab status
gc bd gitlab projects
gc bd gitlab sync --help
gc bd gitlab pull --help
gc bd gitlab push --help

Prove whether upstream satisfies the requirement before retaining custom code.

CLI Version Authority Rule

installed gc 1.4.2 --help > current upstream docs > our assumptions

When deciding what commands this City can execute, installed binary behavior wins over upstream web documentation.

Phase 0 Diagnostic Findings (2026-10-08)

gc v1.4.2 — Remote command gaps

Most gc commands do not support --context oracle yet. The CLI reports:

this command does not support a remote city (--city-url/--context) yet; remote support is being enabled incrementally

Commands that DO NOT support remote: config show, config explain, doctor, beads health, status, rig list, rig set-endpoint, bd, graph

Commands that DO support remote (or attempt remote supervisor API): beads list, beads show, events, convoy list

Supervisor API status: Requests to https://city.blutown.ai currently return HTTP 404 for attempted Gas City API paths. This proves REMOTE_GC_API_PATH_NOT_FUNCTIONING. It does NOT prove the supervisor process is stopped on Oracle (it may be a listener configuration, Cloudflare origin/path mismatch, or route prefix issue). Oracle process/listener inspection is required to classify.

Implication: Phase 1–8 operations must execute directly on Oracle (via admitted agents on bluefly-platform), not via gc --context oracle from Mac.

gc ready vs bd ready vs gc hook

gc ready is unavailable in gc v1.4.2 (GC_1_4_2_READY_AVAILABLE=NO). - bd ready: Beads store-level ready queue (scoped through gc bd where required). - gc hook <agent>: Finds routed work using the agent's work_query config (gc hook --claim runs startup claim). These are distinct commands and not semantically interchangeable.

Mac runtime

Mac City is already retired: gc cities list returns "No cities registered." No local Dolt server running. No Mac runtime retirement action needed.

CWD context behavior confirmed

From estate root: sticky default oracle wins. From inside BluCity: local city discovery wins, oracle shadowed. gc --context oracle from inside BluCity: explicit flag wins. This is upstream design, not a defect.