README.md

Bitcode Repository

BITCODE_SPEC.txt is the canonical pointer for active-system work. It currently resolves to V27; V28 is the active draft target for commercial MVP QA, hardening, and surface cleanup.

Current Product Posture

Bitcode is the protocol and the commercial source tree implements it in-place. The primary operator routes are:

• /terminal for depositing, reading, transaction work, and protocol follow-through.
• /auxillaries for Wallet, Externals, Profile, and Interfaces support surfaces.

Exchange and website Conversations remain in source as deferred commercial work, but V28 closure focuses on Terminal, Auxillaries, wallet/BTC testnet, MCP API, and ChatGPT App MVP behavior.

The protocol demonstration remains the minimal deterministic reference for the same protocol. Commercial code may mount or compare against demonstration runtime facts, but commercial source should name the owning product surface directly: Terminal, Exchange, Auxillaries, Conversations, API, MCP, or ChatGPT App.

Repository Rules

• Ground new work in BITCODE_SPEC.txt and the active specification family.
• Treat _legacy/ as non-canonical.
• Do not add explicit versioned source routes or compatibility source names.
• Update source in-place to match the active canon and current draft target.
• Keep specification notes, QA ledgers, tests, and implementation synchronized.

Key Surfaces

• BITCODE_SPEC.txt is the canonical version pointer.
• BITCODE_SPEC_V27.md is the active promoted spec family.
• BITCODE_SPEC_V28.md is the active draft target.
• BITCODE_V28_QA.md tracks commercial MVP QA.
• uapi/README.md documents the commercial website/API surface.
• uapi/app/terminal/README.md documents Terminal.
• uapi/app/exchange/README.md documents Exchange.
• uapi/app/auxillaries/README.md documents Auxillaries.
• protocol-demonstration/README.md documents the deterministic demonstration.

Repository Map

• uapi/: commercial website, API routes, Terminal, Exchange, Auxillaries, Conversations, public docs, and shared UI systems.
• protocol-demonstration/: deterministic Bitcode demonstration, proof generator inputs, and standalone validation runtime.
• packages/*: protocol, storage, inference, conversation, BTD, API, MCP, ChatGPT App, and integration package owners.
• .bitcode/: generated proof, checkpoint, and spec-family artifacts.

Common Commands

Mock-mode commercial review:

cd uapi
NEXT_PUBLIC_MASTER_MOCK_MODE=true \
NEXT_PUBLIC_ENABLE_MOCKS=true \
NEXT_PUBLIC_MOCK_USER_ORBITAL=true \
NEXT_PUBLIC_MOCK_USER_ORBITAL_SCENARIO=demo \
NEXT_PUBLIC_MOCK_SCENARIO=demo \
NEXT_PUBLIC_MOCK_GITHUB_ACCOUNTS=true \
NEXT_PUBLIC_MOCK_GITHUB_REPOS=true \
HOST=127.0.0.1 PORT=3000 pnpm dev:remote

Commercial verification:

cd uapi
pnpm exec tsc --noEmit --pretty false
pnpm run test:e2e:commercial-mvp

Demonstration verification:

cd protocol-demonstration
pnpm test:integration
pnpm test:v28-commercial-mvp-qa