GaiaFTCL CLI Reference — Swift M⁸

Every executable the cell ships is declared as a .executable product in

cells/xcode/Package.swift.

This page is the canonical list of those CLI members: what each one is, how it is

invoked, the exact argument grammar, and the substrate subjects / receipts it touches.

Patents: USPTO 19/460,960 | USPTO 19/096,071 — © 2026 Richard Gillespie

Build any member from the cell root:

cd cells/xcode
swift build --product <Name>
.build/debug/<Name> [args]

---

Member index

Verdict tokens are uniform across the cell: CALORIE (cleared / cure), REFUSED

(ran to the frontier without clearing, frontier named honestly), BLOCKED (bad input

or execution error).

---

VQbitVM

The vQbit virtual machine. It accumulates S⁴ deltas per prim, fires the full M⁸

pipeline when a prim's four-axis mask saturates, runs the Bell/CHSH gate plus the

constitutional invariants, and publishes the resulting C⁴ projection.

Source: Sources/VQbitVM/ · Form: .build/debug/VQbitVM (daemon, runs continuously)

Configuration is by environment, not flags:

• GAIAFTCL_TENSOR_N — qualified manifold row count. Required; the VM exits 2 if unset.
• GAIAFTCL_TENSOR_PATH — manifold tensor path (defaults via GaiaInstallPaths).
• GAIAFTCL_OVERFLOW_MAP_PATH — overflow map URL (optional).
• GAIAFTCL_VQBIT_POINTS_LOG — vQbit points log path (optional).

Subscribes: SubstrateWireSubjects.s4Delta, gaiaftcl.tau.sync.state,

gaiaftcl.franklin.stage.moored, gaiaftcl.franklin.stage.unmoored.

Publishes: SubstrateWireSubjects.c4Projection, gaiaftcl.vqbit.vm.ready,

gaiaftcl.vqbit.vm.heartbeat.

---

GaiaRTMGate

Confirms the Requirements Traceability Matrix exists at the expected path and is valid

JSON, then returns terminal state. Used as a qualification gate.

Source: Sources/GaiaRTMGate/

.build/debug/GaiaRTMGate [--repo-root=PATH]

--repo-root defaults to the current directory. Exit 0 = CALORIE, 1 = REFUSED.

---

FranklinConsciousnessService

Drives the Franklin consciousness actor. Either runs one preflight cycle and prints a

JSON report, or awakens the actor continuously.

Source: Sources/FranklinConsciousnessService/

.build/debug/FranklinConsciousnessService --preflight-once   # one JSON report, then exit
.build/debug/FranklinConsciousnessService                    # continuous awakening loop

Delegates to FranklinConsciousnessActor.shared.

---

GaiaFTCLApp

The full macOS SwiftUI application — Franklin consciousness, language-game contracts,

the M⁸ manifold renderer, and in-app IQ/OQ/PQ qualification. Enforces single-instance

via an advisory lock at /tmp/franklin.sovereign.lock; closing a side window does not

terminate the app.

Source: Sources/GaiaFTCLApp/

.build/debug/GaiaFTCLApp      # launches the macOS window

No CLI flags. Subscribes to substrate NATS subjects internally via FranklinDriver

and LocalC4Subscriber.

---

S4DegradeInject

Publishes low S⁴ deltas (0.05 on all axes) for every active

language_game_contracts row, to drive vQbit VM C⁴ projections.

Source: Sources/S4DegradeInject/

.build/debug/S4DegradeInject

Connects to NATS at 127.0.0.1:4222 and reads the substrate DB.

Publishes: SubstrateWireSubjects.s4Delta.

Exit 0 published · 2 NATS not connected · 3 no active contracts · 1 error.

---

QuantumOQInjector

Operational-qualification runner for the quantum-domain contracts. Injects S⁴ deltas,

waits for the matching C⁴ projection, and validates the terminal state against the

selected test spec.

Source: Sources/QuantumOQInjector/

Status probes (run and exit):

.build/debug/QuantumOQInjector --ping            # NATS + τ/mooring status
.build/debug/QuantumOQInjector --tau-status      # τ block height and source
.build/debug/QuantumOQInjector --mooring-status  # cell latitude/longitude/s3_spatial

Tests select with --test <ID>:

# OQ-QM-001 — terminal states at fixed s-mean values
.build/debug/QuantumOQInjector --test OQ-QM-001 --prim ProjectionProbe --s-mean 0.85 [--runs N] [--timeout SEC]

# OQ-QM-002 — monotonic c3_closure across a sequence; all terminal states observed
.build/debug/QuantumOQInjector --test OQ-QM-002 --prim CircuitFamily --s-mean-sequence 0.85,0.66,0.20,0.05

# OQ-QM-003 — S⁸ stability across a Franklin cycle
.build/debug/QuantumOQInjector --test OQ-QM-003 --prim VariationalFamily --inject s1=0.85,s2=0.66,s3=0.20,s4=0.05 [--wait-franklin-cycle]

# OQ-QM-004 — single projection at given s-mean
.build/debug/QuantumOQInjector --test OQ-QM-004 --prim LinearAlgebraFamily --s-mean 0.85

# OQ-QM-005 — c3_closure improvement post-cycle with receipt validation
.build/debug/QuantumOQInjector --test OQ-QM-005 --prim SimulationFamily --s-mean 0.85 [--wait-franklin-cycle]

# OQ-QM-006 — monotonic ascending c3_closure over a sequence
.build/debug/QuantumOQInjector --test OQ-QM-006 --prim BosonicFamily --s-mean-sequence 0.20,0.66,0.85

# OQ-QM-007 — algorithm-count sum, residual terminal check, closure_residual_max
.build/debug/QuantumOQInjector --test OQ-QM-007 --db /path/substrate.sqlite --log /path/vqbit.log

Predefined --prim roles: ProjectionProbe, CircuitFamily, VariationalFamily,

LinearAlgebraFamily, SimulationFamily, BosonicFamily, ErrorCorrectionFamily,

Tokamak (a raw game_id is also accepted).

Other flags: --runs N (default 1) · --timeout SEC (C⁴ wait, default 10) ·

--db PATH · --log PATH · --wait-franklin-cycle · --help/-h.

Subscribes: SubstrateWireSubjects.c4Projection, optionally

gaiaftcl.franklin.monologue. Publishes: SubstrateWireSubjects.s4Delta.

Exit 0 CALORIE · 2 REFUSED (assertion failed) · 1 BLOCKED.

---

XcodeSubstrateCLI

Sovereign wrapper for every Xcode build / test / sign operation. Routes each one through

the constitutional gate and seals a receipt in franklin_xcode_receipts.

Source: Sources/XcodeSubstrateCLI/

.build/debug/XcodeSubstrateCLI build  [--scheme=NAME] [--config=debug|release] [--package-path=PATH]
.build/debug/XcodeSubstrateCLI test   [--filter=FILTER] [--expected=COUNT] [--package-path=PATH]
.build/debug/XcodeSubstrateCLI sign   --path=PATH [--identity=IDENTITY]
.build/debug/XcodeSubstrateCLI reflect [--package-path=PATH]
.build/debug/XcodeSubstrateCLI probe   [--package-path=PATH]

--config defaults to debug; --identity defaults to - (auto); --package-path is

auto-discovered when omitted. Exit 0 CALORIE · 2 REFUSED (gate blocked) · 1 BLOCKED.

---

FranklinBTCMiner

Sovereign Bitcoin proof-of-work nonce searcher. Double-SHA256 grind dispatched through

the substrate's vQbit invariant (or a forced classical path), reporting the substrate's

measured rate; the verdict is whatever it produces.

Source: Sources/FranklinBTCMiner/

.build/debug/FranklinBTCMiner mine   --header=HEX160 (--target=HEX64 | --bits=N) [--threads=N] [--seconds=N] [--classical] [--netdiff=F]
.build/debug/FranklinBTCMiner moor   --header=HEX160 (--target=HEX64 | --bits=N) [--reader=ID] [--priority=...] [--threads=N] [--seconds=N] [--classical]
.build/debug/FranklinBTCMiner verify --header=HEX160 (--target=HEX64 | --bits=N)
.build/debug/FranklinBTCMiner bench  [--seconds=N] [--threads=N]
.build/debug/FranklinBTCMiner selftest [--bits=N] [--threads=N] [--seconds=N]
.build/debug/FranklinBTCMiner pool   --url=HOST:PORT (--worker=NAME | --wallets=a,b,…) [--password=...] [--netdiff=F] [--btcusd=F]
.build/debug/FranklinBTCMiner close  --header=HEX160 (--target=HEX64 | --bits=N) [--threads=N] [--seconds=N] [--wallet=ADDR] [--node-endpoint=URL] [--netdiff=F] [--classical]
.build/debug/FranklinBTCMiner bench-algos [--seconds=N] [--threads=N] [--header=HEX160]
.build/debug/FranklinBTCMiner schedule --miner-pid=PID [--threshold=F] [--poll=N]
.build/debug/FranklinBTCMiner reinvest --btc=AMOUNT --target=NAME [--usd=F] [--exchange=...] [--experiment=...] [--confirm]
.build/debug/FranklinBTCMiner bridge
.build/debug/FranklinBTCMiner stratum-selftest

Subcommand intents: mine solo grind against a target · moor measurement mode

(registers the game, no broadcast, internal CALORIE on first clear) · verify check a

header against target · bench pure throughput · selftest grind against N leading

zero bits · pool Stratum v1 with wallet rotation · close one-gate closure (grind +

eight-axis verdict) · bench-algos benchmark every algorithm · schedule background

monitor of a miner PID · reinvest record a reinvestment link (no money moves;

dry-run unless --confirm) · bridge render the funding bridge · stratum-selftest

exercise the Stratum v1 protocol.

Key flags: --header=HEX160 (80-byte header, 160 hex chars) · --target=HEX64 or

--bits=N (one required for the grinding subcommands) · --threads=N (default = core

count) · --seconds=N (time budget) · --classical (force classical SHA256d) ·

--reader=ID (default operator-wallet-Rick-only) · --priority=citizen-background|userInitiated.

Wallet addresses are never generated by this tool. Pool wallets come from

--wallets; closure reporting takes --wallet=ADDR. Authoritative addresses are

produced only by substrate-resident wallet operations.

Receipts: private receipts sealed to btc_mining_receipts/<UTC>.json; game

definition moored to discovery_game_definitions/btc_mining_loop.json.

Exit 0 CALORIE · 2 REFUSED (deadline reached, frontier named) · 1 BLOCKED.

---

NonceArchaeology

Fetches real historical mainnet block headers and winning nonces, then runs uniformity

(χ²) and correlation (Pearson r) tests looking for exploitable structure. Fetches are

cached so a range is pulled once.

Source: Sources/NonceArchaeology/

.build/debug/NonceArchaeology --from=0 --to=2000        # analyze a height range
.build/debug/NonceArchaeology --tip --count=2000        # analyze recent blocks from the tip
.build/debug/NonceArchaeology --from=0 --to=200 --verify # reconstruct headers, prove the data is real

--from (default 0) · --to (default 2000) · --tip · --count=N (with --tip,

default 2000) · --verify. Cache at nonce_archaeology/cache/blocks_<lo>_<hi>.json.

Exit 0 analyzed · 1 no blocks fetched / network error.

---

GroverCircuit

Exact state-vector measurement of the BTC-mining Grover circuit. Measures τ (wall-clock

per iteration), runs it head-to-head against brute force, and seals a private receipt

with the measured τ and the honest scaling to 2⁵⁹ iterations.

Source: Sources/GroverCircuit/

.build/debug/GroverCircuit --qubits=16
.build/debug/GroverCircuit --qubits=16 --header=<HEX> --zerobits=K

--qubits=N register size 4–28, default 16 (state vector = 2ᴺ amplitudes) ·

--header=HEX (default 0xa7 × 76 bytes) · --zerobits=K target difficulty in leading

zero bits (default = qubits ≈ one marked state).

Receipt: btc_mining_receipts/GROVER-<timestamp>.json. Exit 0 (receipt sealed).

---

VQbitGameCircuit

The vQbit LVC game circuit in exact rationals — no Float. N=4 instance: Hadamard init,

phase oracle, diffusion, vQbit measurement, the eight-axis verdict, and a falsifier check

on the exact-Rat algebra.

Source: Sources/VQbitGameCircuit/

.build/debug/VQbitGameCircuit       # N=4 fixed instance

Prints the state vector at each gate, the measurement, and the eight-axis verdict

(Trust, Identity, Closure, Consequence, Fidelity, Transfer, Completeness,

Frontier-honesty). Closure requires the final state to equal |11⟩ exactly (GTWED

distance 0); Frontier-honesty seals the result at the N=4 instance only — no general-N or

hardware-advantage claim. Exit 0 CALORIE (all axes pass, falsifier intact) ·

1 REFUSED.

---

Adding a new CLI member

A new executable becomes a documented CLI member in three steps:

1. Add Sources/<Name>/main.swift (or an @main entry point) under cells/xcode/Sources/.

2. Declare it as .executable(name: "<Name>", targets: ["<Name>"]) plus a matching

.executableTarget in Package.swift.

3. Add a section to this page following the same shape: source path, invocation grammar

in a fenced block, flags, substrate subjects / receipts, and exit semantics — then add

the row to the member index.