Gas City Catalog¶

Status: Catalog index (documentation)
Scope: Bluefly Gas City / BluCity composition (Gas City 1.4.x & Beads 1.2.2)
Authority: BluCity-Docs Engineering Standard
Upstream: docs.gascity.com — do not clone upstream docs here

This directory catalogs the durable Gas City composition surface used by Bluefly.

Thin index. Upstream owns Gas City behavior. Bluefly owns declarative inputs, shared CI projection, and IaC host layout.

Canonical catalog files¶

File	Purpose	Dynamic?
gc-rigs.md	Git-backed work/source domains attached to a city (on-demand & pinned)	Partly
packs.md	Reusable capability/configuration bundles	No
gc-formulas.md	Reusable multi-step workflows (admission + pointers)	No
gc-agents.md	Gas City agent roles (5-axis model) and pack-projected specialists	No
gc-orders.md	Trigger/schedule bindings that invoke formulas	No
gc-events.md	Canonical event vocabulary used to trigger or record orchestration	No
gc-cities.md	City declarations, environment projections, and binding expectations	Partly
gc-integrations.md	External systems, MCP endpoints, session providers, and adapter ownership	Partly

Primitive model (Gas City 1.4.x & Beads 1.2.2)¶

Gas City has exactly six primitives (How Gas City Works):

Agent: WHO — configured worker defined across the 5-axis model (HARNESS, MODEL, UPSTREAM, TRANSPORT, RUNTIME).
Bead: WHAT — durable work unit; convoys, tasks, issues, and decisions are beads by type.
Formula: HOW — reusable workflow DAG (v2 compiler); materializes root and step beads.
Rig: WHERE — external git project workspace, provisioned on-demand (gc rig add --git-url) or declared in city.toml.
Pack: CONFIGURES — reusable capabilities, roles, formulas, and orders (pack.toml).
Event: OBSERVE — immutable event notification feeding the supervisor dispatch loop.

A City is the local/root Pack plus deployment details (pack.toml + city.toml). It is not a seventh primitive. Roles (Mayor, Witness, Refinery, Polecat, Deacon) are Agent configurations supplied by a Pack. Session, Order, Sling, Convoy, Drain, Provider, and Supervisor are mechanisms around the six primitives.

Split Storage Architecture¶

Gas City 1.4.x / Beads 1.2.2 enforces a two-tier split storage class: - High-Churn Infrastructure (SQLite): Located at <city>/.gc/store/ (and $WORKSPACE_ROOT/.gc/store/), managing high-frequency ephemeral activity: session state, graph cache, messaging queues, orders, and supervisor nudges without bloating versioned history. - Durable Work Graph (Dolt): Authoritative relational/versioned ledger for durable Beads work items, handoffs, and receipts via shared Dolt server.

On-Demand Rig Provisioning¶

Gas City 1.4.x supports on-demand rig provisioning (gc rig add --git-url <url>), eliminating the historical requirement for 136+ permanent estate clones on local workstations or runtime hosts. Rigs are declared portably in city.toml and bound dynamically on host environments via $WORKSPACE_ROOT/.gc/site.toml.

Work discovery & Dispatch Loop (Pull/Claim)¶

Agents do not browse a global backlog. The supervisor dispatches work via native orders and events:

EVENT / TRIGGER -> ORDER -> FORMULA -> gc sling <agent> <bead> -> gc hook -> bd show -> bd update --claim -> GitLab MR -> bd close

Coordinators route with gc sling. Workers pull via gc hook, then bd show and bd update --claim. bd ready is the Beads graph primitive that work_query uses; it is not the worker session-start command. Execution contract: beads-work-ownership-contract.md. Feature/fix/chore MRs target release/v0.1.x, never main.

Mountain, Product, Project, and Convoy (below) are not Gas City primitives — they are Bluefly portfolio taxonomy layered on top of the primitive list.

Bluefly Portfolio Taxonomy (Mountain / Product / Project / Convoy)¶

Gas City primitives (Agent, Bead, Formula, Rig, Pack, Event) describe how work executes. A City is the deployed local/root Pack, not a seventh primitive. Bluefly also organizes its portfolio in a separate vocabulary that describes what the work belongs to. The two vocabularies compose — a Convoy can span several Rigs; a Rig does not require a 1:1 Mountain relationship.

Term	Lifetime	Meaning	Gas City primitive?	Example
Mountain	Years	Bluefly portfolio/program/product-family domain	No	AMCS, DevOps, OSSA Ecosystem
Product	Long-lived	User/customer-facing product or coherent platform offering	No	AgentBlu.ai, ContextControl.ai
Project/Repository	Long-lived	A GitLab source-controlled artifact — not automatically a Mountain or Rig just because it exists	No	`recipe_amcs`, `context-cli`
Rig	Long-lived while actively operated	Git-backed engineering domain with a durable Beads scope + logical Dolt database, inheriting the shared City Dolt endpoint	Yes	`amcs`, `iac`, `duadp`
Pack	Long-lived reusable	Reusable Gas City behavior/configuration a City imports	Yes	`amcs` pack, `organization`
Convoy	Days/weeks	A bounded mission of related Beads, may span several Rigs — never a permanent portfolio name	No (a Bluefly usage of Beads)	"AMCS v0.2 release", "Shared CI Estate Convergence"
Bead	Hours/days	One durable unit of work	Yes	"Fix Composer package provenance"
Formula	Reusable	HOW a class of work is executed	Yes	`drupal-change`
Order	Reusable/triggered	WHEN/WHERE/WHAT POOL invokes a Formula	Bluefly-cataloged (see Primitive model)	`amcs-release-validation-manual`
City	Long-lived	Local/root Pack plus deployment details — not a seventh primitive	No (deployed Pack + `city.toml`)	`blucity` on Oracle

Hard relationship rules¶

One Project belongs to one primary Mountain. Secondary relationships are tags/dependencies, not co-ownership.
One Mountain can contain many Projects, many Rigs, many Packs, many Convoys.
One Rig usually maps to one primary GitLab repository.
One Convoy can span many Rigs.
A Project does not automatically become a Rig, and a Mountain does not automatically become a Rig — see the admission test in gc-rigs.md.
BluCity is the City itself — not a Rig, not a Convoy, and not merely a Mountain member. See gc-cities.md.
Rig/Pack counts stay intentionally small. Do not manufacture one Rig per Mountain or one Rig per repository.

Mountains (working list — portfolio-owned, not exhaustive, not a Gas City primitive)¶

BLU, AMCS, Drupal CMS, OSSA Ecosystem, ContractPlane, ContextControl, Compliance, DevOps, OpenClaw, AgentSocial, Marketplaces, Site Factory, OSX/Apple, Automation & Testing, BluGuide, Acquia, BluTown, Brand, Hackathons/Labs.

Known overlaps and open calls (portfolio-taxonomy-owner decision — not resolved here):

blucity, blucity-packs, blu-cli, blu-chat, blu-studio sit under the BLU Mountain as Projects/Rigs — BluCity itself is still the City, not "just another BLU project."
ContextControl.ai, context-cli, contextcontrol_theme are one Mountain (ContextControl), not two.
Compliance may cover ComplianceEngine + ContractPlane as one Mountain, or two if independently owned — open, not decided here.
cedar_policies is a standalone Rig that can also participate in Compliance/ContractPlane Convoys — a Rig does not need a 1:1 Mountain relationship.
OSSA Ecosystem contains the ossa Rig (proposed, not yet in the deployed 14-Rig matrix — see gc-rigs.md) plus Projects: openstandardagents, openstandardagents.org, openstandard-gitlab-agent, ossa-studio, ossa-deploy, ai_agents_ossa, duadp, duadp.org, duadp_client.

Worked example: AMCS¶

Mountain=AMCS · Projects=site_template_amcs, recipe_amcs, agentic_canvas_blocks, agentic_canvas_theme · Rig=amcs (deployed) · Pack=amcs · Convoy="AMCS Composer convergence" (Beads: repair package provenance → converge composer.lock → fresh-install proof → DDEV acceptance → MR/release proof) · Formula=drupal-change · Order=amcs-release-validation-manual (confirmed in gc-orders.md).

Worked example: DevOps¶

Mountain=DevOps · Projects=iac, agent-docker, gitlab_components, agent-tailscale, Cloudflare config source · Rigs=iac, agent-docker, gitlab_components (all deployed) · Convoy="Shared CI Estate Convergence" (Beads: classify broken MRs → fix shared component → publish version → retry consumers → verify estate cohort) · Formula=shared-ci-migration (illustrative — not confirmed as a pack-defined formula; verify per gc-formulas.md before authoring it). No Rig is named "DevOps" — DevOps is a Mountain, not a Rig.

Ownership (binding)¶

Concern	Owner
Declarative city source	`blueflyio/blu/blucity` (`city.toml`, `pack.toml`, `deploy/oracle/beads-topology.yaml`)
Pack composition	`blueflyio/blu/blucity-packs`
Generic site/endpoint projection	`gitlab_components` / `gc-site-bind` component
Runtime semantics	Gas City (upstream + installed Oracle build)
Host / Dolt server process	IaC / agent-docker as applicable
Durable work graph	Beads (`bd`) on Dolt
High-churn infra store	SQLite at `<city>/.gc/store`
Source / CI / release	GitLab

Rules¶

A GitLab project is not automatically a rig; on-demand provisioning (gc rig add --git-url) is preferred for task-scoped workspaces over permanent checkouts.
A service is not automatically a pack.
A shell script is not automatically a formula.
A cron job is not automatically an order.
A product-specific agent does not automatically become an organization-level role.
Runtime state must not be made canonical merely because it is observable.
Catalogs describe authority and intended composition; environment-specific state belongs in receipts/Fact Boards.
Generated inventories should reconcile against GitLab, pack manifests, and deployed topology rather than being maintained by memory.
Prefer upstream docs → config → shared components → IaC before Bluefly custom code.
No personal home paths or workstation absolute paths in this catalog (use $WORKSPACE_ROOT).

Beads/Dolt: durable work graph and execution receipts.
GitLab: source, package, merge, CI/CD, and release authority.
BluCity Packs: Gas City reusable composition authority (blueflyio/blu/blucity-packs).
BluCity: city source / declarative topology (blueflyio/blu/blucity).
BluCity Docs (blueflyio/blu/blucity-docs): architecture and governance authority.