Skip to content

Bluefly Platform Glossary

Overview

This document defines the canonical vocabulary for the Bluefly platform. It establishes standard terminology across the Governance Plane, Execution Plane, and Runtime Plane to ensure consistency in engineering communications, standards, and contracts.

Fences, Not Permission Queues (operator, 2026-08-24, binding — supersedes prior per-instance approval habits)

Bluefly is a Light Factory: autonomous work inside explicit, observable, auditable authority boundaries — not humans approving every move. Thomas defines the fences. Agents work freely inside them. Only crossing a fence requires Thomas.

Human approval is a fence, not a default. Required only for genuine boundary crossings: release/v0.1.x → main where explicitly reserved, destructive loss of authoritative state, changing an authority model, external/public representation as Thomas, material production action outside standing delegated authority, granting materially broader credentials, irreversible customer/business decisions, exceptions to locked product scope. Not required for: agent-to-agent communication, read-only investigation, checking another worker's status, normal feature→release delivery already authorized, CI observation, evidence gathering, rerunning a failed bounded test, routing work to the correct specialist, continuing another ready task while one waits, updating a projection from authoritative evidence, or any action already inside an agent's defined authority. A tool reporting "message requires human approval" is a BLOCKED_CAPABILITY=CROSS_SESSION_MESSAGE_TRANSPORT — a tool limit, not a governance requirement; use another path or continue other work. Do not turn Thomas into the transport layer.

No idle waiting. "Waiting on X" / "standing by" / "holding" are not valid states while ready work exists. Loop: rescan → claim ready work → route → verify → replenish → continue. If a dependency is running, check it, then work another ready node — don't sit idle watching it.

Fences by role (illustrative, not exhaustive — extend by the same pattern): Refinery may operate MR source branches, may not force-push main. Mayor may execute authorized Oracle runtime operations, may not redefine tracked source. Forge may build disposable DDEV environments, may not invent production architecture. Harbormaster may write governed backup artifacts to NAS, may not mutate Beads work state. Drupal may implement Drupal-native behavior, may not create a parallel orchestration platform.

Boards are projections, not authority. Beads/Dolt, GitLab, Gas City runtime, and deployment/runtime evidence are the authoritative inputs; a board (including the two canonical operator-designated boards) must be reproducible from them. No human or agent "owns truth" by manually maintaining a board. An unverified session claiming an identity (e.g. "Gas City Agent") does not gain write authority merely by claiming the name — require role/identity/canonical-agent-definition/authority resolved against the canonical OSSA/agent definition first; BLU + Mayor + Witness can resolve this from evidence without escalating to Thomas unless two authoritative definitions genuinely conflict.

Receipts, not narration. Minimum: OBJECTIVE= OWNER= AUTHORITY= SOURCE_SHA= ACTION= RESULT= EVIDENCE= NEXT_ACTION= HUMAN_GATE=. HUMAN_GATE is normally NONE; if not, include EXACT_DECISION= WHY_EXISTING_AUTHORITY_CANNOT_RESOLVE_IT= CONSEQUENCE_OF_YES= CONSEQUENCE_OF_NO=. Never send Thomas a choice another existing authority can decide.

Governing metric stays dollars per closed MVP blocker — not agents active, tokens spent, or messages generated. Deduplicate repeated findings; cache known capability gaps; reassign work with no new evidence within its time-box rather than let it sit.

MVP Scope Lock (operator, 2026-08-24, supersedes all other engineering priority until it closes)

The MVP is one narrow, sellable claim, proven end-to-end — not "the whole Bluefly platform works":

From clean source, manufacture a governed AMCS Drupal site twice, from the same canonical composition, with no hand assembly, and produce an auditable receipt.

Concretely: canonical AMCS source correct → empty DDEV Run 001 passes → destroy → empty DDEV Run 002 passes from identical source → behavior checks pass → Witness independently accepts → one customer/design-partner proof ready to show.

No fourth engineering lane until Lane 1 or Lane 2 closes. Only three lanes exist: - Lane 1 — AMCS Factory (the MVP itself): DRUPAL → FORGE → REFINERY → WITNESS - Lane 2 — P0 production safety: MAYOR / SENTINEL / HARBORMASTER - Lane 3 — Customer proof: BLU / Thomas

Anything not directly unblocking the MVP proof, production safety, or a customer conversation is deprioritized — including estate-wide MR convergence and the Cedar/compliance-engine/contractplane-sdk integration chain, unless a specific piece of either directly blocks Lane 1 or is a live P0. Broad audits, doctrine consolidation, and architecture-ambiguity closure (today's earlier work) are real and correct but not MVP-critical — they resume once Lane 1 or Lane 2 closes, not before.

Authority split for engineering spend: Dispatch = token budget/concurrency/timing supervisor (decides how many agents run, kills/reassigns low-yield loops). BLU = value authority (decides whether source work is MVP-relevant, duplicated, or stale). MAYOR = P0 runtime override only. Each specialist = local efficiency responsibility (stop when re-deriving, repeating tool calls, or blocked on a capability it doesn't own). Thomas = budget ceiling and business priority only, not token-by-token execution.

Governing metric: dollars per closed MVP blocker, not tokens per agent, not agent count. Dispatch owns that metric.

Default concurrency: 2 executors, 1 verifier, 1 supervisor, max 4 active specialists — increase only when work is truly independent and MVP-critical. Idle agents consume zero work; do not keep all specialists "alive" because they exist.

Every active agent answers: MVP_BLOCKER= EXPECTED_VALUE= NEXT_PROOF= TIME_BOX= STOP_CONDITION=. If MVP_BLOCKER=NO, suspend unless P0. Time-boxes: 15min diagnostic must show new evidence; 30min must show root cause narrowed / owner identified / fix underway / explicit blocker; 45min with no measurable progress stops and reassigns — do not reward persistence that produces no new evidence.

Report to Thomas only: MVP_PERCENT= BURNING_AGENTS= ESTIMATED_ACTIVE_LANES= CURRENT_MVP_BLOCKER= NEXT_PROOF= HUMAN_DECISION_REQUIRED= WASTE_STOPPED=. Not token-level chatter. Terminal state: MVP_MOVING — SPEND_BOUNDED.

Standing Constraint (operator, 2026-08-24, binding on all agents and all work)

"NO NEW PROJECTS, NO NEW MODULES, NO NEW RECIPES OR TEMPLATES. UPDATE CURATE AND OPTIMIZE WHAT WE HAVE"

Not scoped to the release path or to today — binds every agent, every task. If a task appears to require a new project, module, recipe, or template, that requirement is a signal to find the existing thing it duplicates, not a license to create one. Sits directly under the standing custom-code reduction standard: Bluefly should own less tomorrow than it owns today.

Why this is not abstract: the three architecture ambiguities closed via source audit on 2026-08-24 (contextcontrol_amcs, the AMC schema, the archived AMCS-ARCHITECTURE.md enforcement chain — see below) were all cases of a document describing an artifact that did not exist or was not what the document claimed. The estate has been accumulating described artifacts faster than real ones. This constraint is the direct corrective. It also means an archived document describing unbuilt machinery (ubuntu-1vfr) is doubly out of bounds — not current architecture, and not a specification to build to under this constraint.

Extended (operator, same day): also covers site templates — no new site templates. Diagnostic sharpened: if a task appears to require a new project/module/recipe/template/site template, treat that as a signal that ownership is wrong, or that a duplicate capability already exists — not as permission to create. Permitted actions: update, curate, optimize, consolidate, delete.

Source authority order, binding for every claim in this glossary and in any audit that feeds it: LIVE RUNTIME READBACK → CURRENT GITLAB SOURCE → OWNING IMPLEMENTATION → CI EVIDENCE → DURABLE STANDARDS → GENERATED/ARCHIVED MATERIAL → CONVERSATION

Human/team ownership fields (operator, 2026-08-24): Bluefly is a solo-developer estate — there is one human, the bluefly GitLab account. Do not return UNABLE_TO_VERIFY for a human/team owner field and do not check CODEOWNERS-style entries for confirmation; every such entry resolves to the same one person, and checking adds nothing. The only ownership question that actually matters is which existing repository or artifact is the canonical implementation of a capability — a source question, answerable from current source, distinct from "which person." Any process step phrased as needing "Maintainer sign-off" or naming a team (@blueflyio/security-team, etc.) describes an organizational structure that does not exist — a false-authority problem in the same family as a false-artifact claim, and in scope of the no-new-artifacts constraint above (false structure, not just false code). Every source claim carries PROJECT= PATH= BRANCH= SHA=. Two explicit prohibitions: do not infer behavior from a project/module/service name; do not treat _ARCHIVE content as current architecture (this is ubuntu-1vfr's finding promoted to standing doctrine, not a one-off).

Canonical Definitions

Planes of Operation

  • Governance Plane: The control layer (owned by Bluefly) responsible for defining policy, auditing, approvals, and enforcing Desired State. It does not execute workloads.
  • Execution Plane: The orchestration layer (owned by Gas City) responsible for reading the Desired State, reconciling dependencies, and driving agents to achieve the state.
  • Runtime Plane: The physical or virtual infrastructure where workloads and agents actually execute. It is disposable, immutable, and owns no state.

Core Architecture Entities

  • Bluefly: The business authority and Governance Plane. It defines the object graph, policies, and Desired State, but delegates execution to Gas City.
  • Gas City: The orchestration platform that operates the Execution Plane. It reads Bluefly's Release Bundles and reconciles them into the Runtime Plane.
  • Oracle: The disposable, immutable infrastructure provider hosting the Runtime Plane. It holds no Git repositories, no manual deployment scripts, and is rebuilt entirely from IaC.

State & Deployment

  • Business Intent: The strategic goal or operational outcome required by Bluefly, declared asynchronously and abstractly, distinct from implementation details.
  • Desired State: The exact, versioned, declarative configuration required to fulfill Business Intent. This is compiled by Bluefly and governs what must exist.
  • Release Bundle: An immutable, versioned artifact containing the compiled Desired State, configurations, and pack references required for a Deployment.
  • Deployment: The act of transitioning a Target Environment to a specific Release Bundle via Governance Plane approval. Deployments are never manual script executions.
  • Environment: A bounded operational domain (e.g., Development, Staging, Production) governed by policies.
  • Reconciliation: The continuous, autonomous process (performed by Gas City) of comparing Runtime Plane realities against the Desired State and executing formulas to eliminate drift.

Capabilities & Contracts

  • Capability: A defined, reusable business function or technical service. Every Capability has exactly one authoritative owner.
  • Pack: A portable, version-controlled unit of agent behavior, formulas, and skills used by Gas City to orchestrate work.
  • Contract: A declarative standard defining how agents behave, communicate, and resolve dependencies.
  • Authority: A system acting as the definitive source of truth for deployment, work tracking, or state orchestration.

Standards & Product Terminology (Founder-locked, 2026-08-24)

  • OSSA: Open Standard for Software Agents. Use exactly this expansion everywhere unless the public standards site (openstandardagents.org) declares a different one, in which case that site wins.
  • DUADP: Decentralized Universal AI Discovery Protocol. Public protocol definition wins. "Deterministic Universal Agent Deployment Pattern" is a retired, incorrect expansion — do not use.
  • AMCS: Agent-Managed Content System.
  • AMC: Agent Marketplace Contract. CLOSED, AMC_SCHEMA=NO_CURRENT_CANONICAL_AMC_SCHEMA_FOUND (BLU fork audit, 2026-08-24, group-wide blob search for "Agent Marketplace Contract"/AMC bundle/schema artifacts, zero hits). No canonical AMC schema exists to require anything — do not describe kagent/LiteLLM/agentgateway as "AMC primitives" (required or optional) until a real schema exists; describe them by their actual current posture instead: KAGENT_OSSA_CLASSIFICATION=EXTENSION (spec/v0.5/extensions/kagent/kagent.schema.json, not in any base/required OSSA schema), KAGENT_DRUPAL_CLASSIFICATION=OPTIONAL_INTEGRATION (ai_agents_kagent depends on ai_agents_ossa, not the reverse; lifecycle: experimental; absent from recipe_blucity/recipe_amcs requirements), LITELLM_CLASSIFICATION=OPTIONAL_PROVIDER (ai_provider_litellm, standard Drupal AI provider plugin, not a dependency other modules require), AGENTGATEWAY_CLASSIFICATION=OPTIONAL_GATEWAY (MCP policy-gateway integration, its own docs describe it as a setup demo for Cedar-gated MCP federation, not a mandated dependency). Grounded in prior practice too (Foundry, 2026-08-24): ossa-deploy/OWNERSHIP.md lists these as named, separate, optional integration modules alongside many peers, none privileged as required core.
  • Canvas: drupal/canvas. "Experience Builder" is historic/frozen terminology and must not appear as a description of the current implementation.
  • Gas City: Canonical term for the orchestration platform. "Gas Town" is historical/reference-pack terminology — do not describe Gas Town as the substrate underneath Gas City.
  • Light / Dark Factory: A public operating metaphor only. Not a second runtime or architecture layer — do not use in architecture topology docs. "Dark Factory" describes an operating mode, not infrastructure. Origin, verified against both primary sources (BLU, 2026-08-24): Yegge coined "dark factory" as unobserved background agent work, then described Gas City itself as a "Light Factory" — a dark factory built with observability maximized ("Gas City: The Light Factory... I have begun to think of Gas City as a Light Factory... or at least, a very well-lit dark one"). Scola's article borrows that same distinction by analogy and applies it to Drupal's governance posture, not to Gas City's own architecture. Binding synthesis (Scola's proposed wording, confirmed against both sources): Gas City supplies the role-agnostic orchestration substrate; Gas Town supplies one opinionated operating pack and vocabulary; Bluefly's Light Factory is the governed operating model applied across that substrate — explicit authority, durable work, observable execution, verifiable handoffs, policy enforcement, auditable receipts; Drupal is the first durable customer product manufactured and operated through that model. Neither source frames Light Factory as a competing runtime to Gas City — a diagram may label a deployment/operating posture Light or Dark, but must never draw them as separate orchestration systems.

OSSA / DUADP / Gas City / Drupal Layering (operator doctrine, routed via Forge, 2026-08-24)

  • Layering: OSSA (portable agent/skill/tool contract) → DUADP (discovery, federation, resolution) → runtimes (Gas City execution/orchestration, Drupal business/content plane, other runtimes: Kubernetes/MCP/A2A/etc). OSSA is the sole authoritative agent-definition source — Gas City agent.toml, Drupal config entities, and DUADP registry rows are projections of it, never independent sources of truth. DUADP is the sole authoritative discovery contract (a conforming node exposes /.well-known/duadp.json plus at least one OSSA-formatted resource endpoint). Gas City is an execution projection of OSSA/DUADP into its native primitives (agents, packs, formulas, orders, sessions, beads) — do not put DUADP inside Gas City core, do not build a second registry inside Gas City, do not build a Bluefly scheduler/discovery daemon around it. Drupal is the business-facing DUADP node and OSSA bridge via ai_agents_ossa (OSSA↔Drupal AI Agent projection only, not a discovery implementation) and drupal/duadp (registry/discovery/federation only, not an agent runtime).
  • Discovery is not execution (governance chain, binding): DISCOVER → RESOLVE DID/GAID → VERIFY SIGNATURE + LIFECYCLE → VALIDATE OSSA → EVALUATE CEDAR/GOVERNANCE POLICY → IMPORT/PROJECT → OPERATOR OR POLICY-GATED EXECUTION → GAS CITY SESSION/FORMULA → RECEIPT. A discovered resource must never execute merely because it was discovered. Not yet true in the reference implementation (Refinery source audit, 2026-08-24, tracked as ubuntu-7lk2 P1): drupal/duadp's federation endpoints (registerPeer, receiveRevocation) have zero auth check, every DUADP route declares _access: TRUE bypassing Drupal's route-level access entirely, and a public_key is advertised in the manifest but never used — no signature verification exists anywhere in the codebase. The VERIFY SIGNATURE + LIFECYCLE step above is aspirational until this is fixed; do not treat federation trust as enforced.
  • Orchestration-creep boundary: DUADP discovers orchestration capabilities; it must not become an orchestrator itself. Endpoints like /api/v1/delegate and /api/v1/orchestration in the DUADP root README are flagged as non-core-extension candidates or removal candidates from the normative protocol — DUADP owning execution DAG semantics recreates the exact ownership overlap the platform is eliminating (Gas City = orchestration, DUADP = discovery, OSSA = definition, MCP/A2A = invocation, Drupal = business authority).
  • DUADP normative-spec contradictions (BLU direct verification against openstandardagents.org and openstandardagents.org/duadp/, 2026-08-24 — supersedes the earlier unverified list): (1) CONFIRMED — the live openstandardagents.org/duadp/ page itself already reads "Powered by the Open Standard for Software Agents (OSSA)" and titles itself "Decentralized Universal AI Discovery Protocol (DUADP)" — both expansions match founder decision exactly. If any other copy of the normative spec text differs from this, that copy is the stale one to fix, not the live public site. (2) RESOLVED (Sentinel, 2026-08-24, source-verified): the live spec's own self-claim naming ai_agents_marketplace as the DUADP reference implementation does NOT survive a source check — project 80431142's ai_agents_marketplace module contains zero DUADP code (verified group-wide within that repo). The real protocol node is duadp (project 80049553, machine name duadp not duadp_client — earlier reference to "duadp_client" was a naming error, corrected here), evidenced by duadp.services.yml's federation HTTP client, a DuadpNode config entity + AgentManager, the four protocol-verb Tool plugins (DuadpDiscover/DuadpRegister/DuadpResolve/DuadpPublish), Drush commands, and a discovery-telemetry Grafana dashboard. ai_agents_marketplace is a genuinely different capability — a Drupal-native OSSA-agent catalog built on content entities, views, facets, and analytics, with dependencies on node/taxonomy/field/views/search_api/facets/ai_agents_orchestra. These are not duplicates and coexist by design — merging them would create the duplicate the standing constraint exists to prevent, not remove one. Per the source authority order (current GitLab source outranks durable standards), the spec's self-claim is what needs correcting, not the code — same shape as ubuntu-1vfr (a document asserting an implementation into existence). NOT_ESTABLISHED, stated rather than glossed over: whether ai_agents_marketplace is supposed to speak DUADP and simply doesn't yet — source proves it doesn't today, source cannot prove intent; if that gap is real, the fix extends the existing module, never adds a third one. Refinery's federation auth-gap audit (ubuntu-7lk2) was correctly aimed at duadp, the real protocol node — not affected by this correction. (3) the payload-format MUST-vs-README contradiction is independently confirmed: the official conformance table states OSSA-formatted payloads (apiVersion: ossa/v0.4 or later) as a MUST-level requirement — if any README elsewhere says "any payload format" that contradicts the live spec, the live spec's MUST wins.
  • Foundation-vs-domain recipe placement: recipe_blucity (foundation) should require/configure the provider-neutral platform capability — drupal/ai, drupal/ai_agents, drupal/ai_agents_ossa, drupal/duadp, drupal/tool, drupal/key — once audited as actually absent from the canonical source (not assumed). recipe_amcs (domain) contains only AMCS-specific agent manifests, discovery policy, and product behavior. Do not manually add DUADP to amcs-demo. Not yet actioned — this is an audit-then-add sequence, not standing authorization to modify recipe_blucity today.
  • OSSA → Gas City projection gap: no exporter from OSSA to Gas City primitives currently exists in the public OSSA package material. If built, it belongs in the OSSA-owning repo as a thin adapter/exporter (conceptually ossa export agent.ossa.yaml --to gascity), not as Gas City source code, and DUADP resolution/sync on the Gas City side should be exec orders, not a standing agent. Not yet built — bounded platform-adapter gap, not authorization to start building it.
  • End-to-end proof target (not yet executed): publish an OSSA agent in Drupal → Drupal DUADP exposes it → Gas City resolves the GAID through DUADP → verifies OSSA + DID + policy → projects the agent into Gas City → executes one bead/formula → result returns to Drupal → signed/auditable receipt. This is the bounded transaction that would demonstrate "define once with OSSA, discover anywhere with DUADP, execute through Gas City, govern and productize through Drupal" — requires operator authorization before implementation, same as any other cross-repo execution work.

Commercial Model (Founder-locked, 2026-08-24)

  • Bluefly's 2026 commercial motion: sells governed modernization outcomes (customer-owned Drupal modernization delivered through the Bluefly Factory), not a marketplace/orchestration-seat product. Sequence: modernization lane → operate retainer → reusable product package → design-partner proof → repeatable platform capability. Standards/governance (OSSA, DUADP, ContextControl, ContractPlane/Cedar, evidence, certification, marketplace) are the moat and eventual scaling mechanism — they do not need to carry revenue before the company has customers.
  • Drupal's role: Drupal is Bluefly's first-class customer product substrate and business authority — the first reference implementation of the wider governed-organization contract. It is not the Bluefly control plane. Drupal may own business state, structured content, access, workflow, editorial experience, Canvas/SDC experience, Recipes/configuration, and customer-specific product behavior. Drupal must not become the owner of universal agent identity, cross-runtime discovery, generic policy engines, orchestration, durable platform evidence infrastructure, or runtime-independent governance contracts (the "Drupal Gravity" guardrail).
  • Immediate product proof: the Bluefly Drupal Launch Factory, demonstrated through AMCS. Layering: site_template_amcs (canonical reusable product) composes recipe_amcs (domain composition) which composes recipe_blucity (platform foundation). Acceptance proof is two independently created, customer-shaped governed Drupal sites built from the same canonical foundation with no hand assembly — not merely "a Recipe that works."
  • Canonical chain and gap classification (operator, 2026-08-24): the full chain is site_template_amcs → recipe_blucity → recipe_amcs → existing contrib modules → Canvas / SDC / theme → clean consumer. amcs-demo is explicitly disposable — never patch it manually. Any missing capability is a CANONICAL_PRODUCT_COMPOSITION_GAP, assigned to exactly one existing owner from that chain; never fixed by creating another site template, recipe, module, or project — if an existing owner can be extended, that is the required path. Consequence, binding: a finding phrased as "amcs-demo needs X" is misclassified by construction — the defect is always upstream of the demo, in whichever link of the chain owns the capability. Route findings there, not to the demo.
  • MASTER-PROMPT.md: does not exist. Do not reference it as authoritative and do not recreate it to satisfy old references — replace those back-references with the actual canonical doctrine/registry they meant to point to.
  • site_template_amcs path: blueflyio/amcs/site_template_amcs is authoritative. Correct stale references rather than maintaining aliases.
  • contextcontrol_amcs: CLOSED (BLU fork audit, 2026-08-24, GitLab source verified group-wide, zero exclusions). MODULE_EXISTS=NO — no contextcontrol_amcs.info.yml, no implementation, no config export reference exists anywhere in current non-archived source. BOOTSTRAP_BREAKING=NOT_ESTABLISHED, confirmed correct. Only live-source occurrence is doc text on blucity-docs main (stale, release/v0.1.x already corrected — tracked as ubuntu-o87w). ContextControl-the-product is confirmed distinct and real (blueflyio/contextcontrol.ai/contextcontrol-ai, context-cli). No adapter-naming action needed — there is no module to rename.
  • Six trust vocabularies (identity assurance, runtime autonomy/posture, policy sensitivity, constitutional authority, OSSA conformance, registry/supply-chain trust): do not merge into one ladder — they are different dimensions. Represent as a Trust Model Matrix with explicit crosswalks, not a seventh hierarchy.
  • Cedar policy helpers (local_evaluator, dev_policy_sync, gitlab_policy_sync, cedar_policy module project 76284311): CLOSED (BLU fork audit, 2026-08-24, source verified). These are real, non-stub, production-routable code — not "dev/test only" doctrine. All three: PRODUCTION_CAPABLE — NOT YET AUTHORIZED AS PRODUCTION AUTHORITY (technically callable in production today via real controllers/forms/ECA/Tool API, zero environment guard; dev_policy_sync and gitlab_policy_sync mutate real remote/local state; none of the three read any config key literally named enforcement_mode — the module defines no such key). Technical capability and governance authorization are separate axes; do not conflate "runs in dev-named code paths" with "cannot run in production" — it can. Real defect, not doctrine: zero environment guard exists (ubuntu-bnug, P1). Separately, archived AMCS-ARCHITECTURE.md describes a fail-closed enforcement_mode chain across these services that was never built (ubuntu-1vfr) — do not cite that archive as current architecture.
  • Composer registry endpoint (Foundry, 2026-08-24): the "group vs groups" split is folklore — GitLab's documented endpoint is singular group (.../api/v4/group/<group_id>/-/packages/composer/packages.json), confirmed against 3 real consumer composer.json files (app.drupl.ai, contractplane.ai-website, marketplace-app.drupl.ai), none of which use groups. The real inconsistency is the trailing /packages.json: present (canonical) in 2 of the 3, absent in app.drupl.ai — unverified whether GitLab still resolves without it. Auth: app.drupl.ai's CI correctly sets composer config --global gitlab-token.gitlab.com, but its composer.json also embeds a redundant Authorization: Bearer header in the repository's options.http block (env-interpolated, not a literal secret, but two auth paths layered where there should be one). Publish side (Foundry, follow-up): consistent and clean across 5 checked repos — curl -X POST "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/composer?tag=${CI_COMMIT_TAG}" -H "JOB-TOKEN: ${CI_JOB_TOKEN}" on semver tag push, CI_JOB_TOKEN only, no fix needed. Publish being per-project while consume is group-scoped is GitLab's actual Composer registry model (publish per-project, group endpoint aggregates for discovery) — not an inconsistency to "fix" into one endpoint. Third consume-side inconsistency: openclaw's example uses the numeric group ID (87749026) where 3 other consumer repos use the name (blueflyio) — standardize on the name.

Upstream Canonical Terminology (Gas City / Beads glossary, RETRIEVED 2026-09-02)

Sourced directly from the upstream canonical glossary and product pages (gascity.com/guide/software-factory-glossary/, gascity.com/guide/gas-city-gas-town-gasworks-whos-who/, gascity.com/about/) — cite these, do not re-derive local paraphrases that drift from them.

  • Bead: "A durable unit of structured agent work" recording title, status, priority, assignee, notes, and relationships. RETRIEVED.
  • Beads (the protocol): "The open protocol for durable agent work and the open-source work-state substrate." Distinct from a single bead. RETRIEVED.
  • Formula: "Gas City's technical definition of a workflow: a readable TOML graph" declaring steps, dependencies, routing, and control flow; compiles into a materialized bead graph ("local run") of root + child step beads. RETRIEVED.
  • Order: "Gas City's technical automation definition" pairing a trigger (schedule, event, condition, or manual) with an action (a formula or a command). RETRIEVED — corrects any local phrasing that describes Orders only as "cron/event/cooldown"; cooldown is a Bluefly usage pattern of the condition/event trigger types, not a fourth upstream trigger kind.
  • Rig: "A project, repository, or workspace registered with Gas City" providing work and agent scope. RETRIEVED.
  • Pack: "A reusable bundle of factory configuration: agent templates, workflows, automations, prompts, and supporting assets." RETRIEVED.
  • Agent (upstream usage): "A configured coding agent" — CLI harness + provider + model + permissions + skills. RETRIEVED.
  • Event (upstream usage): "An immutable notification fired by Gas City activity," exposed via list/stream/cursor APIs — local observation, not a retained enterprise audit record. RETRIEVED.
  • Convoy: "A bead-backed grouping of related work used to track a larger delivery." Not previously catalogued here. RETRIEVED.
  • Claim: "An atomic assignment operation in Beads" (bd update <id> --claim) preventing duplicate work assignment. RETRIEVED.
  • Gate: "A condition that must be satisfied before dependent work proceeds," materializing as a blocking bead. RETRIEVED.
  • Ready frontier: "The work that an agent can claim now because it has no open blocker," computed via bd ready / work_query. Workers discover that frontier through gc hook, not by browsing fleet-wide bd ready. RETRIEVED; Bluefly session-start law: beads-work-ownership-contract.md.
  • Work graph (edge types): "Beads connected by parent-child structure, blocking dependencies, provenance, validation, and other typed relationships" — parent-child (scope/hierarchy, no sequencing implied), blocking (ordering constraints, drives bd ready), and provenance/discovered-from (records why work exists without forcing it into the original plan). RETRIEVED, gascity.com/guide/agent-work-graphs/.
  • Session vs. Bead: "A live coding-agent process" (Session) is temporary; a Bead is durable. Default claim lease is five minutes (heartbeat-refreshed) with a ten-minute grace period before bd reclaim returns an abandoned bead to open. RETRIEVED, gascity.com/guide/coding-agent-crash-recovery/.
  • Gas City vs. Gas Town vs. Gasworks (canonical relationship, RETRIEVED): Beads is the foundation (open protocol/substrate). Gas City is "the MIT-licensed open software factory platform that runs on Beads" and is the primary orchestration product. Gas Town is upstream's own predecessor project — "the predecessor software-factory project that inspired Gas City" — whose architecture Gas City "restructured... into configurable primitives"; Gas Town's operating vocabulary remains available as an importable pack for migration only, not a compatibility layer Gas City runs underneath. Gasworks is downstream — the "coming soon" multi-operator/team expansion of Gas City, bundling Beads Team Server. This refines the "Gas Town is historical/reference-pack terminology" bullet above: Gas Town is the historical predecessor, not merely a reference pack, and it inspired rather than underlies Gas City. "Gas City, Inc. is the company. Gas City without Inc. is the open-source product." Source: gascity.com/guide/gas-city-gas-town-gasworks-whos-who/, gascity.com/about/.
  • Beads Team Server / Gasworks (commercial products, RETRIEVED 2026-09-02, early access/waitlist as published): Beads Team Server is in early access/design-partnership preview (SaaS or self-hosted VPC), adding governed shared work, provenance, visibility, Kanban/dependency-graph/Gantt views, and Run-level tracing of agent sessions, artifacts, model/token/spend. Gasworks is "coming soon" (waitlist), bundles Beads Team Server, and is positioned "bring your own keys, zero markup" (no token tolls). Both are commercial extensions on top of the unchanged OSS Gas City/Beads component map — not required to use the OSS platform. Source: gascity.com/beads-team-server/, gascity.com/gasworks/.
  • Three separate "history" surfaces (do not conflate, RETRIEVED): (1) Beads work graph = durable work memory (crash recovery); (2) Gas City local dashboard/events = local execution projection, explicitly "not a retained enterprise audit record"; (3) Beads Team Server Run record = governed organizational audit/compliance record (sessions, artifacts, outcomes, spend). Source: gascity.com/guide/durable-agent-memory-audit-trail/.
  • Beads vs. hosted trackers, operating rule (RETRIEVED): "Use the hosted tracker for work that the organization promises, funds, reviews, or reports. Use Beads for work that agents must safely claim, block, discover, resume, and hand off." Native sync commands exist for bd jira, bd linear (bidirectional, MCP-integrated), and bd github (bidirectional/pull-only/push-only/selective) — see gc-integrations.md. Source: gascity.com/guide/beads-with-jira-linear-github-issues/.

Legacy Concepts (Archived)

  • Manual deployments, mutable production servers, and SSH-based configuration have been deprecated and replaced by Release Bundles and IaC.