Tool Authority Index¶

Scope: Bluefly tool ownership and authority routing. Authority: upstream documentation and official CLI behavior for each tool.

This document is an index. It does not duplicate CLI references.

Upstream-Owned Tools¶

Tool	Upstream authority	Bluefly posture
`gc`	https://docs.gascity.com/	Use official Gas City docs and CLI output. Do not redefine behavior locally.
`gt`	https://docs.gascityhall.ai/	Use official Gas City docs and CLI output. Do not redefine behavior locally.
`bd`	https://beads.gascity.com/	Use official Beads docs and CLI output. Do not mutate storage internals.
`git`	Git documentation and owning repository policy	Source control only; repository state is verified in Git.
`glab`	GitLab CLI / GitLab API docs	GitLab MR, approval, pipeline, and deployment state.
`docker` / Compose	Docker documentation	Container runtime and service composition.
`terraform`	Terraform provider docs	Infrastructure provisioning.
`ddev` / `drush` / Composer	Drupal/DDEV/Composer docs	Drupal runtime and dependency operations.
`qmd`	Local qmd CLI and indexed collections	Semantic retrieval over local Bluefly knowledge.

Bluefly-Owned Tools¶

Bluefly tools are integration surfaces. They may wrap or compose upstream tools, but they must not replace upstream behavior.

Tool	Bluefly role
`blu-cli`	Operator facade and integration wrapper.
`agent-buildkit`	Repeatable Bluefly engineering execution surface.
ContextControl CLI	ContextControl integration and tenant operations.

Selection Rule¶

Use the highest-authority existing tool that owns the behavior. If an upstream CLI owns the lifecycle, use that CLI and its official documentation. If no upstream or Bluefly-owned tool exists, record the gap instead of creating a new path inside Engineering-Standard.

Mutation Boundary¶

Before a mutation, verify:

the owning repository,
the active branch,
the path scope,
the authoritative tool,
the verification command,
the expected passing condition.

Do not infer GitLab MR state from Git refs. Use GitLab UI/API or glab.

Do not manually modify runtime state owned by gc, gt, or bd.

1Password `op` CLI — Agent Behavior Rules¶

Secret value prohibition (P0)¶

Agents MUST NOT print, echo, or expose secret values in any output — including command output, logs, transcripts, or MR descriptions.

Prohibited patterns:

# NEVER do these:
op read op://vault/item/field         # prints the value
printenv SECRET_VAR                   # prints the value
echo $SECRET_VAR                      # prints the value
cat /path/to/secret/file              # may print the value
jq '.token' secrets.json              # prints the value

Required pattern — boolean/length verification only:

# Prove state without revealing value:
op read op://vault/item/field > /dev/null && echo resolved || echo empty
op run -- sh -c '[ -n "$VAR" ] && echo populated || echo empty'

Any violation is a P0 defect. Operators must rotate tokens when a value leaks — this is an operational cost, not a warning.

Secret injection — `op run` over `op read`¶

Use op run -- to inject secrets as environment variables into processes. Do not use op read to capture a value into a shell variable and pass it on.

# Correct:
op run -- docker compose up -d
op run -- env | grep -c SOME_SECRET_VAR

# Incorrect:
SECRET=$(op read op://vault/item/field)
docker compose up -d  # $SECRET now in shell environment history

`op whoami` — requires operator-initiated CLI session¶

op whoami and interactive op commands require a real CLI session, established by the operator running:

eval $(op signin)

Agents CANNOT perform this step — it requires interactive terminal input that must be run by the human operator directly. op read works via Desktop app integration without an active CLI session, but interactive commands do not.

Agents MUST NOT suggest or attempt eval $(op signin) themselves. If a real session is required for provisioning secrets to a remote host, instruct the operator to run it directly.

These rules govern how this Mac/agent handles op values. They do not cover how a value, once resolved, may safely reach a Gas City execution surface (order exec, provider script, hook, gc sling) — that command-construction boundary is Gas City's own upstream doctrine: gas-city-command-execution-trust-boundaries.md.

`gc` CLI — Remote Developer Constraint¶

The gc CLI is designed for local operation only. Global flags are limited to --city, --rig, and --json-schema. There is no --server flag or GC_SUPERVISOR environment variable for remote operation.

The Gas City supervisor API binds to loopback 127.0.0.1:8372 by default. It is designed for single-operator local use and has no real authentication beyond an anti-CSRF header.

Consequence: A workstation cannot invoke gc against a remote Oracle supervisor directly.

Correct pattern: SSH into Oracle and run gc there:

ssh oracle-host
gc status
gc sling my-rig/claude "..."

Prohibited pattern (CORRECTED — do not attempt): - Expose the supervisor API on a non-loopback interface - Run gc init on a workstation to create a "local city" mirroring Oracle - Create any competing runtime authority on the workstation

Oracle is the single authoritative City. Workstations author source (GitLab) and SSH to Oracle for runtime commands. No competing runtime authorities.