Pocket CFO

Pocket CFO is an evidence-native finance cockpit that turns raw company exports and documents into a persisted Finance Twin, a compiled CFO Wiki, and proof-backed answers a human can review outside chat.

Problem And Niche

Small-company finance work often lives in fragile spreadsheets, email attachments, bank exports, board materials, policy docs, and half-remembered context. The hard part is not making an assistant sound finance-fluent. The hard part is keeping evidence, freshness, limitations, and review boundaries intact while answering real operating questions.

Pocket CFO is aimed at a single finance operator or founder who needs a local, auditable system for:

• registering raw finance source truth
• deriving deterministic structured finance state
• compiling readable finance knowledge pages
• answering supported finance questions with provenance
• producing durable proof, memo, packet, monitoring, and readiness artifacts without pretending those are external actions

Hero Demo Story

A founder drops a bundle of bank-account summaries, receivables aging, payables aging, ledger exports, policy documents, board materials, and lender documents into Pocket CFO.

Pocket CFO registers each raw file with checksum and provenance, syncs supported CSVs into the Finance Twin, compiles the CFO Wiki, runs deterministic discovery and monitor paths, and returns a source-backed answer such as cash posture or collections pressure with freshness, limitations, related wiki pages, and proof references. A human can then inspect the evidence bundle before using any conclusion elsewhere.

Shipped Today

The current v1 repository is shipped at the proof and handoff layer, not as a public hosted deployment.

Shipped capabilities include:

• Source Registry for immutable raw source registration, snapshots, checksums, and provenance.
• Finance Twin reads for account catalogs, general ledger state, trial-balance and reconciliation posture, cash, receivables, payables, spend, contracts, obligations, and source-backed balance proof.
• CFO Wiki compilation for company, period, source coverage, source digest, concept, metric-definition, policy, lint, export, and filed artifact pages.
• Mission Engine support for typed finance discovery, reporting, packets, review/readiness posture, and deterministic monitor handoffs.
• Evidence and proof bundles that expose source lineage, freshness or missing-source posture, limitations, and absence boundaries.
• Operator UI read-only truthfulness polish from F9, without backend runtime expansion.
• Source-pack proof commands for bank/card, receivables/payables, contract/obligation, ledger/reconciliation, policy/covenant documents, and board/lender documents.
• Fixed shipped monitor families: cash_posture, collections_pressure, payables_pressure, and policy_covenant_threshold.
• Fixed shipped discovery families: cash_posture, collections_pressure, payables_pressure, spend_posture, obligation_calendar_review, and policy_lookup.

For the phase ledger and exact shipped records, see docs/PROJECT_STATE.md.

What Pocket CFO Is Not

Pocket CFO is not:

• a generic finance chatbot
• an autonomous accountant
• a bank, payment, accounting, tax, legal, or assurance agent
• a multi-tenant SaaS product in the current boundary
• a provider-integration or external-delivery system
• a certification, sign-off, close-complete, legal-opinion, or audit-opinion engine
• a system where an LLM answer becomes source truth

Quick Local Setup

Requirements: Node/pnpm, Docker, and the local Postgres plus S3-compatible object storage services from this repo.

cp .env.example .env
docker compose up -d
pnpm install
pnpm db:generate
pnpm db:migrate
pnpm dev

Use docs/ops/local-dev.md for the current local operating pattern and docs/ops/self-host-baseline.md for the local-only self-host boundary.

Core Validation

The broad repo gates are:

pnpm lint
pnpm typecheck
pnpm test
pnpm ci:repro:current

The core finance proof spine also includes the direct source-pack proofs:

pnpm exec tsx tools/board-lender-document-source-pack-proof.mjs
pnpm exec tsx tools/policy-covenant-document-source-pack-proof.mjs
pnpm exec tsx tools/ledger-reconciliation-source-pack-proof.mjs
pnpm exec tsx tools/bank-card-source-pack-proof.mjs
pnpm exec tsx tools/receivables-payables-source-pack-proof.mjs
pnpm exec tsx tools/contract-obligation-source-pack-proof.mjs

See the active Finance Plan and docs/PROJECT_STATE.md for the full validation ladder that belongs to a given slice.

Architecture Overview

Pocket CFO is organized around six product planes:

• Source Registry: raw uploads, snapshots, checksums, source roles, provenance, and immutable source artifacts.
• Finance Twin: deterministic structured finance facts, lineage, freshness posture, and company-scoped read models.
• CFO Wiki: compiler-owned markdown knowledge pages derived from source inventory, deterministic document extracts, and Finance Twin state.
• Mission Engine: typed discovery, reporting, monitoring, close/control, and readiness workflows with replay-aware state transitions.
• Evidence/proof layer: answer artifacts, proof bundles, evidence sections, limitations, freshness posture, and absence boundaries.
• Operator UI: read-only operator surfaces for source, mission, wiki, evidence, and safety-boundary posture.

The Codex runtime seam is bounded: it is an operator/coding seam for session transport, draft assistance where a future plan permits it, and developer workflow. It is not the source of finance truth and does not authorize autonomous finance actions.

Current Boundaries

The current product boundary is intentionally narrow:

• one company
• one operator and one trust boundary
• file-first/manual export default
• raw sources are authoritative for document claims
• the Finance Twin is authoritative for structured finance facts
• the CFO Wiki is compiled and derived
• no autonomous bank, accounting, tax, legal, provider, delivery, certification, payment, or customer-contact actions
• no package-scope rename yet; internal packages remain @pocket-cto/* and the root package name remains pocket-cto

V2 Roadmap Summary

F11 closed public repo hygiene and V2 transition framing. F12 closed the manual UI/demo-readiness audit in docs/qa/v1-ui-demo-readiness-audit.md without starting V2 implementation.

FP-0080 is the shipped first V2A EvidenceIndex and document-map foundation record. It adds a native deterministic read-only anchor/trace layer for supported markdown/plain-text source text, evidence cards, source coverage posture, and a direct proof command without adding UI, routes, schema, migrations, package scripts, fixture files, OCR, vector search, PageIndex, MCP, ChatGPT App, provider behavior, certification, delivery, source mutation, finance writes, generated product prose, or autonomous action.

Current V2 sequence after the shipped FP-0083 baseline:

• V2B document precision adapters foundation through FP-0081, shipped as one narrow deterministic TextPdfAdapter candidate over EvidenceIndex for policy/covenant text-PDF sources under strict fail-closed quality gates
• V2C read-only agent/MCP/ChatGPT Evidence App alpha through FP-0082, shipped as a local/internal read-only evidence-tool contract and direct proof over existing EvidenceIndex/TextPdfAdapter outputs, with no public MCP server, ChatGPT App, Apps SDK UI, routes, schema, migrations, package scripts, fixtures, OpenAI API/file-search/vector integration, OCR, PageIndex, provider behavior, certification, delivery, report release, source mutation, finance writes, generated product prose, runtime-Codex finance output, or autonomous action
• OSS demo/self-host/security baseline through FP-0083, shipped as docs-only SECURITY.md, PRIVACY.md, CONTRIBUTING.md, demo-data policy, local demo journey, self-host guidance, and finance-data/read-only-agent threat models before public app or deployment work
• V2D Evidence Atlas UI through FP-0084, shipped as one read-only apps/web route at /evidence-atlas plus modular UI components and focused specs for evidence/source coverage/timeline/document map/evidence card/answer anatomy/capability-boundary posture. It adds no backend route, web API route, schema, migrations, package scripts, fixtures, sample data, public app, MCP, OpenAI vector/file-search, source mutation, finance write, LLM orchestration, or autonomous action
• V2E bounded LLM orchestration through FP-0085, shipped as a local/internal proof-only QueryPlanner, fixed read-only V2C tool plan, deterministic evidence selection handoff, bounded summary/refusal contract, local audit event, and deterministic grade posture
• V2F benchmark/community pack foundation through FP-0086, shipped as a SafeDemoDataPolicy-first docs/proof-only benchmark/community manifest contract foundation. It adds pure benchmark/community contracts, focused specs, and one direct proof command without adding eval datasets, fixtures, sample data, public demo source packs, package scripts, smoke aliases, model calls, OpenAI API calls, public app/MCP, source mutation, finance writes, or autonomous action
• V2G read-only ChatGPT App/MCP contracts through FP-0087, shipped as a local proof-only contract foundation plus read-only MCP descriptor/response-envelope foundation. It adds pure domain contracts for read-only app/MCP plans, exact tool allowlists, forbidden tools, local proof-only MCP descriptors, strict descriptor input/output schemas, app/MCP response envelopes, refusal/privacy/no-runtime/deferred boundaries, threat-model questions, focused specs, V2F typed boundary hardening, and direct proof commands. It adds no public app implementation, MCP server runtime, endpoint, Apps SDK iframe/UI, OAuth, app submission, schema, migrations, package scripts, eval datasets, fixtures, sample data, public demo data, source-pack behavior, OpenAI API/model calls, hosted tools, vector/file-search integration, OCR, PageIndex, provider behavior, certification, delivery, deployment, external communications, source mutation, finance writes, generated product prose, runtime-Codex finance output, or autonomous action
• V2H premium read-only ChatGPT App/MCP UI and security readiness through FP-0088, shipped as a docs-and-plan plus proof-gate compatibility record only. It plans premium UI and app/MCP security readiness without implementing UI, endpoints, remote MCP, OAuth, app submission, OpenAI API/model calls, package scripts, datasets, fixtures, sample data, source packs, source mutation, finance writes, generated product prose, runtime-Codex finance output, or autonomous action
• V2I premium read-only ChatGPT App/MCP UI design-system readiness through FP-0089, shipped as a docs-and-plan plus proof-gate compatibility record only. It plans design tokens, semantic color, spacing, typography, evidence hierarchy, component taxonomy, accessibility, refusal-state grammar, and future QA gates without implementing UI, Apps SDK iframe/UI, endpoints, remote MCP, OAuth, app submission, OpenAI API/model calls, package scripts, datasets, fixtures, sample data, source packs, source mutation, finance writes, generated product prose, runtime-Codex finance output, or autonomous action
• V2J premium read-only ChatGPT App/MCP UI implementation readiness through FP-0090, shipped as a docs-and-plan plus proof-gate compatibility record only. It defines the future local/proof-only/read-only UI implementation boundary without implementing UI, Apps SDK iframe/UI, endpoints, remote MCP, OAuth, app submission, OpenAI API/model calls, data files, source mutation, finance writes, generated product prose, runtime-Codex finance output, or autonomous action
• V2K premium read-only ChatGPT App/MCP UI component foundation through FP-0091, shipped as the first local/proof-only/read-only component implementation slice. It adds local React components and focused component tests under apps/web/components/read-only-app-mcp/** without adding routes, endpoints, remote MCP, Apps SDK iframe/UI resources, OAuth, app submission, OpenAI API/model calls, data files, source mutation, finance writes, generated product prose, runtime-Codex finance output, autonomous action, or public app implementation
• V2L premium read-only ChatGPT App/MCP UI composition/accessibility foundation through FP-0092, shipped as a local/proof-only/read-only composition and accessibility hardening slice. It composes the FP-0091 components, adds heading-level control, scoped section IDs, evidence hierarchy, contrast/token, responsive structure, raw/private-field, no-control, and no-advice-copy tests without adding routes, endpoints, remote MCP, Apps SDK iframe/UI resources, OAuth, app submission, OpenAI API/model calls, data files, source mutation, finance writes, generated product prose, runtime-Codex finance output, autonomous action, or public app implementation
• V2M premium read-only ChatGPT App/MCP local UI preview route master-plan through FP-0093, shipped as docs-and-plan plus proof-gate compatibility only. It planned a local read-only preview route boundary without implementing route code, app routes, API routes, backend routes, endpoints, remote MCP, Apps SDK iframe/UI resources, OAuth, app submission, OpenAI API/model calls, data files, source mutation, finance writes, generated product prose, runtime-Codex finance output, autonomous action, public app implementation, screenshots, images, or public app assets
• V2N premium read-only ChatGPT App/MCP local UI preview route foundation through FP-0094, shipped as exactly one local/proof-only/read-only preview route at apps/web/app/read-only-app-mcp-preview/page.tsx. It renders shipped FP-0091/FP-0092 components from in-memory synthetic contract-shaped examples with focused route tests and no fetch, API call, POST, form, button, upload, server action, endpoint, backend route, remote MCP, Apps SDK iframe/resource, OAuth, app submission, OpenAI API/model call, source mutation, finance write, public asset, or public app implementation
• V2O premium read-only ChatGPT App/MCP local UI preview route state-matrix master-plan through FP-0095, shipped as docs-and-plan plus proof-gate compatibility only. It planned a future local state matrix, noindex/local-only posture, and premium visual QA hardening without implementing route code, endpoints, remote MCP, Apps SDK iframe/UI resources, OAuth, app submission, OpenAI API/model calls, screenshots, images, public assets, source mutation, finance writes, product runtime behavior, or public app implementation
• V2P premium read-only ChatGPT App/MCP local UI preview route state-matrix foundation through FP-0096, shipped as local/proof-only/read-only implementation on the existing preview route only. It adds no additional route, API/backend route, endpoint, remote MCP, Apps SDK iframe/UI resource, OAuth, app submission, OpenAI API/model call, screenshot, generated image, public asset, source mutation, finance write, product runtime behavior beyond the local route preview, or public app implementation
• V2Q premium read-only ChatGPT App/MCP local UI preview route visual QA foundation through FP-0097, shipped as local/proof-only/read-only screenshotless visual QA and accessibility hardening on the existing preview route only. It adds no additional route, API/backend route, endpoint, remote MCP, Apps SDK iframe/UI resource, OAuth, app submission, OpenAI API/model call, screenshot, generated image, public asset, source mutation, finance write, product runtime behavior beyond local route hardening, or public app implementation
• V2R read-only ChatGPT App/MCP public-app readiness through FP-0098, shipped as docs-and-plan plus proof-gate compatibility only. It plans future public-app readiness, security posture, and submission-boundary questions without implementing public app behavior, Apps SDK iframe/resources, remote MCP, endpoints, OAuth, app submission, OpenAI API/model calls, screenshots, listing assets, source mutation, finance writes, product runtime behavior, or public app implementation
• V2S read-only ChatGPT App/MCP public-app security threat-model through FP-0099, shipped as docs-and-plan plus proof-gate compatibility only. It plans future public-app/MCP security threat-model and platform-boundary questions without implementing endpoints, OAuth, remote MCP, Apps SDK iframe/resources, public app behavior, app submission, OpenAI API/model calls, screenshots, listing assets, source mutation, finance writes, product runtime behavior, or public app implementation
• V2T read-only ChatGPT App/MCP public-app security boundary contracts through FP-0100, shipped as local/proof-only/read-only pure domain contracts, focused specs, and direct proof tooling without implementing endpoints, OAuth, remote MCP, Apps SDK iframe/resources, public app behavior, app submission, OpenAI API/model calls, screenshots, listing assets, source mutation, finance writes, product runtime behavior, or public app implementation
• V2U read-only ChatGPT App/MCP public-app implementation sequencing through FP-0101, shipped as docs-and-plan plus proof-gate compatibility only. It sequences future endpoint/OAuth/remote-MCP, Apps SDK resource, public app implementation, and submission lanes without implementing endpoints, OAuth, remote MCP, Apps SDK iframe/resources, public app behavior, app submission, OpenAI API/model calls, screenshots, listing assets, source mutation, finance writes, product runtime behavior, or public app implementation
• V2V read-only ChatGPT App/MCP endpoint/OAuth/remote-MCP architecture through FP-0102, shipped as docs-and-plan plus proof-gate compatibility only. It defines future endpoint, OAuth/token/session, remote MCP, descriptor/tool allowlist, privacy/security, and proof gates without implementing endpoints, OAuth, token/session handling, remote MCP deployment, Apps SDK iframe/resources, public app behavior, app submission, OpenAI API/model calls, screenshots, listing assets, public assets, source mutation, finance writes, product runtime behavior, or public app implementation
• V2W read-only ChatGPT App/MCP endpoint architecture proof contracts through FP-0103, shipped as local/proof-only/read-only pure domain contracts and direct proof tooling. It proves endpoint inventory deferral, future endpoint path preconditions, endpoint trust model, future transport/TLS requirements, request/response envelope requirements, evidence/freshness/limitations fields, refusal/failure posture, read-only allowlist preservation, and no-runtime/no-route/no-endpoint posture without implementing endpoints, routes, OAuth, token/session handling, remote MCP deployment, Apps SDK resources, public app behavior, app submission, OpenAI API/model calls, public assets, source mutation, finance writes, product runtime behavior, or public app implementation
• V2X read-only ChatGPT App/MCP endpoint implementation readiness through FP-0104, shipped as docs-and-plan plus proof-gate compatibility only. It names /mcp as the only future ChatGPT-facing public connector endpoint path that is safe to name from current repo truth and official docs, records route ownership, request/response envelope, refusal/failure, auth, transport/TLS, logging, and proof-gate requirements, and adds no endpoint, route, OAuth/token/session handling, remote MCP deployment, Apps SDK resource, public app behavior, app submission, OpenAI API/model call, public asset, source mutation, finance write, product runtime behavior, or public app implementation
• V2Y read-only ChatGPT App/MCP endpoint route ownership and transport-adapter proof contracts through FP-0105, shipped as local/proof-only/read-only pure domain contracts and direct proof tooling. It names apps/control-plane Fastify as the documentation-only future /mcp route owner family, defines thin transport-adapter, service-dispatch, envelope, refusal, auth-deferral, logging-redaction, deployment-deferral, and rollback proof boundaries, and adds no endpoint, route, OAuth/token/session handling, remote MCP deployment, Apps SDK resource, public app behavior, app submission, OpenAI API/model call, public asset, source mutation, finance write, product runtime behavior, or public app implementation
• V2Z read-only ChatGPT App/MCP protocol envelope and tool-dispatch proof contracts through FP-0106, shipped as local/proof-only/read-only pure domain contracts and direct proof tooling. It defines the future /mcp protocol envelope, required future MCP methods, the ping liveness utility boundary, rejected MCP methods, exact V2G read-only tool dispatch, structured evidence/refusal envelopes, argument validation, auth deferral, logging redaction, no-route/no-runtime posture, and the pre-FP-0107 successor boundary while adding no endpoint, route, OAuth/token/session handling, remote MCP deployment, Apps SDK resource, public app behavior, app submission, OpenAI API/model call, public asset, source mutation, finance write, product runtime behavior, or public app implementation
• V2AA read-only ChatGPT App/MCP local Fastify route adapter foundation through FP-0107, shipped as exactly one local/control-plane /mcp protocol shell. POST /mcp remains the only JSON-RPC request entrypoint; GET /mcp is handled only as SSE-unavailable HTTP 405 with Allow: POST; accepted notifications return HTTP 202 with no body; non-local Origin headers fail closed. It handles JSON-RPC shape for initialize, ping, notifications/initialized, tools/list, structured fail-closed errors, and fail-closed tools/call without OAuth/token/session handling, remote MCP deployment, Apps SDK resources, public app behavior, app submission, OpenAI API/model calls, source mutation, finance writes, provider calls, external communications, public assets, or real read-only evidence dispatch
• V2AB read-only ChatGPT App/MCP evidence tool dispatch contracts through FP-0108, shipped as local/proof-only/read-only domain contracts and direct proof tooling for the future /mcp tools/call implementation. It defines exact V2G tool-to-service mappings, strict argument schemas, future read-only service dependency lanes, structured evidence/refusal envelopes, freshness/source-anchor requirements, and no-raw-dump/no-advice/no-mutation/no-write/no-provider/no-external-call/no-OpenAI/model boundaries while preserving the FP-0107 route shell fail-closed and adding no runtime dispatch, route behavior, endpoint expansion, OAuth/token/session handling, remote MCP deployment, Apps SDK resource, public app behavior, app submission, public asset, source mutation, finance write, or real read-only evidence dispatch
• V2AC read-only ChatGPT App/MCP evidence tool dispatch adapter through FP-0109, shipped as a local-only/read-only/dependency-injected adapter for the existing /mcp tools/call service path. It maps the exact V2G tools to ReadOnlyEvidenceToolService, enforces expected companyKey before dispatch, honors declared arguments or fails closed including fetch_source_coverage sourceId and unsupported periodKey, mirrors structuredContent with bounded JSON text, preserves structured evidence/refusal envelopes, keeps default registration fail-closed unless a dispatcher is explicitly injected, and adds no route path, GET behavior change, DB query, schema/migration, package script, fixture, sample data, source pack, public asset, OAuth/token/session handling, remote MCP deployment, Apps SDK resource, public app behavior, app submission, provider/external/OpenAI/model call, source mutation, finance write, generated finance advice, or autonomous action
• V2AD read-only ChatGPT App/MCP default local evidence dispatch enablement master plan through FP-0110, shipped as docs-and-plan plus proof-gate compatibility only. It plans how a future local implementation may bind one companyKey, obtain local read-only evidence artifacts through explicit app construction, preserve no-real-finance-data/no-public-demo-data posture, and prove readiness before default dispatch wiring, while keeping the existing /mcp route fail-closed by default and adding no runtime dispatch, route behavior change, endpoint, DB query, schema/migration, package script, fixture, sample data, source pack, public asset, OAuth/token/session, remote MCP deployment, Apps SDK resource, public app behavior, app submission, OpenAI API/model call, provider call, external communication, source mutation, finance write, generated finance advice, runtime-Codex finance output, autonomous action, or FP-0111
• V2AE read-only ChatGPT App/MCP default local evidence dispatch wiring through FP-0111, shipped as a local-only/read-only explicit app-construction wiring slice. buildApp({ container }) can pass an explicitly supplied read-only MCP endpoint service into the existing /mcp route; default buildApp() remains fail-closed without that dependency. It adds no route path, GET behavior change, DB query, schema/migration, package script, fixture, sample data, source pack, public asset, OAuth/token/session, remote MCP deployment, Apps SDK resource, public app behavior, app submission, provider/external/OpenAI/model call, source mutation, finance write, generated finance advice, or autonomous action
• V2AF read-only ChatGPT App/MCP remote/public deployment OAuth readiness through FP-0112, shipped as docs-and-plan plus proof-gate compatibility only. It plans remote/public MCP host readiness, OAuth/token/session prerequisites, company/user/org binding, CORS/CSP/TLS/rate-limit/logging/rollback gates, no-real-finance-data posture, and app-submission blockers while preserving the local /mcp route and adding no route behavior change, remote MCP deployment, OAuth/token/session implementation, Apps SDK resource, public app behavior, app submission, public assets, DB query, schema/migration, package script, OpenAI API/model call, provider/external call, source mutation, finance write, or autonomous action
• V2AG read-only ChatGPT App/MCP OAuth/token/session security contracts through FP-0113, shipped as local/proof-only/read-only pure domain contracts and direct proof tooling. It proves OAuth, token/session, auth middleware, and remote deployment deferral; authenticated user/org/company binding requirements; client companyKey selector fail-closed behavior; minimized scopes; audience validation; token passthrough prohibition; token failure modes; token storage/redaction/revocation/rotation contract posture; no-token-leakage surfaces; public exposure block; and no-real-finance-data posture while adding no route behavior change, OAuth/token/session implementation, auth middleware, remote MCP deployment, Apps SDK resource, public app behavior, app submission, DB query, schema/migration, package script, OpenAI API/model call, provider/external call, source mutation, finance write, public asset, or autonomous action
• V2AH read-only ChatGPT App/MCP remote host readiness security contracts through FP-0114, shipped as local/proof-only/read-only pure domain contracts and direct proof tooling. It proves remote MCP deployment deferral, current local /mcp non-exposability, stable HTTPS/TLS and canonical resource URI prerequisites, /mcp as the only future public MCP endpoint path, Streamable HTTP compatibility, GET SSE deferral, Origin/CORS/CSP requirements, rate-limit/abuse controls, logging redaction, observability/audit correlation, rollback/incident response, health/readiness deferral, no-real-finance-data/no-public-demo-data posture, OAuth/security prerequisites, no remote runtime, and a docs-only FP-0115 successor boundary while adding no route behavior change, new route path, deployment config, OAuth/token/session/auth middleware implementation, Apps SDK resource, public app behavior, app submission, DB query, schema/migration, package script, OpenAI API/model call, provider/external call, source mutation, finance write, public asset, or autonomous action
• V2AI read-only ChatGPT App/MCP remote host implementation sequencing through FP-0115, shipped as docs-and-plan plus proof-gate compatibility only. It decides remote MCP host implementation cannot start from current repo truth, the current local /mcp route can not be exposed remotely as-is, host/provider ownership remains provider-neutral and unresolved, candidate host/provider analysis is recorded, canonical resource URI and public /mcp prerequisites must be proven, and OAuth/token/session/auth middleware, deployment config, Apps SDK resources, public app behavior, app submission, public assets, screenshots, listing copy, generated public prose, DB queries, schemas, migrations, package scripts, source packs, OpenAI API/model calls, provider calls, source mutation, finance writes, and autonomous action remain future-only
• V2AJ read-only ChatGPT App/MCP remote host resource contracts through FP-0116, shipped as local/proof-only/read-only pure domain contracts and direct proof tooling. It keeps host owner unresolved with implementation blocked, preserves provider neutrality, requires a future exact stable HTTPS canonical resource URI, keeps public /mcp as the only future public MCP endpoint path, requires OAuth protected-resource metadata and WWW-Authenticate resource_metadata, rejects workspace/tenant URL templates, treats local tunnels as development-only, and adds no route behavior change, new route path, remote MCP deployment, deployment config, OAuth/token/session/auth middleware implementation, Apps SDK resource, app submission, DB query, schema/migration, package script, public asset, listing copy, generated public prose, OpenAI API/model call, provider call, source mutation, finance write, or autonomous action
• V2AK read-only ChatGPT App/MCP OAuth/token/session/auth implementation sequencing through FP-0117, shipped as docs-and-plan plus proof-gate compatibility only. It plans protected-resource metadata, WWW-Authenticate resource_metadata, authorization-server discovery, scope challenge handling, audience/resource validation, token failure modes, token/session storage/redaction/revocation/rotation/replay prerequisites, auth middleware prerequisites, and authenticated company binding gates while adding no route behavior change, route expansion, protected-resource metadata route, WWW-Authenticate behavior, OAuth/token/session/auth middleware implementation, remote MCP deployment, deployment config, Apps SDK resource, public app behavior, app submission, DB query, schema/migration, package script, public asset, listing copy, generated public prose, OpenAI API/model call, provider call, source mutation, finance write, generated finance advice, runtime-Codex finance output, or autonomous action
• V2AL read-only ChatGPT App/MCP protected-resource metadata auth challenge readiness contracts through FP-0118, shipped as local/proof-only/read-only pure domain contracts and direct proof tooling. It proves protected-resource metadata document shape, canonical resource URI dependency, authorization_servers, read-only least-privilege scopes_supported, header-only bearer method posture, WWW-Authenticate resource_metadata challenge readiness, metadata discovery, scope challenge readiness, token failure challenge posture, no-token-leakage, route deferral, WWW-Authenticate route deferral, and no-runtime posture while adding no route behavior change, route expansion, protected-resource metadata route, WWW-Authenticate route behavior, OAuth/token/session/auth middleware implementation, remote MCP deployment, deployment config, Apps SDK resource, public app behavior, app submission, DB query, schema/migration, package script, fixture, sample data, source pack, public asset, listing copy, generated public prose, OpenAI API/model call, provider call, source mutation, finance write, generated finance advice, runtime-Codex finance output, or autonomous action
• V2AM read-only ChatGPT App/MCP protected-resource metadata route implementation sequencing through FP-0119, shipped as docs-and-plan plus proof-gate compatibility only. It plans protected-resource metadata route implementation sequencing and WWW-Authenticate resource_metadata challenge sequencing, decides route implementation cannot start from current repo truth until canonical public resource URI and route proof gates are green, keeps WWW-Authenticate behavior in a later/separate lane, and adds no route behavior change, route expansion, protected-resource metadata route, WWW-Authenticate route behavior, OAuth/token/session/auth middleware implementation, remote MCP deployment, deployment config, Apps SDK resource, public app behavior, app submission, DB query, schema/migration, package script, fixture, sample data, source pack, public asset, listing copy, generated public prose, OpenAI API/model call, provider call, source mutation, finance write, generated finance advice, runtime-Codex finance output, or autonomous action
• V2AN read-only ChatGPT App/MCP canonical resource/auth-server readiness through FP-0120, shipped as local/proof-only/read-only pure domain contracts and direct proof tooling. It proves canonical public MCP resource URI requirements, deferred exact stable HTTPS URI decision, no selector/query/fragment/local-tunnel authority, required but unresolved provider-neutral authorization_servers, RFC 9728 route-path derivation, WWW-Authenticate resource_metadata URL readiness, durable known-safe route inventory proofing, validation-gated metadata URL derivation, no route runtime, no route behavior change, no OAuth/token/session/auth middleware, no remote deployment/config, no Apps SDK resources, no app submission/assets, no OpenAI API/model/provider calls, no source mutation, and no finance write
• V2AO read-only ChatGPT App/MCP protected-resource metadata route implementation planning through FP-0121, shipped as docs-and-plan plus proof-gate compatibility only. It plans future protected-resource metadata route implementation readiness, canonical URI and authorization_servers prerequisites, route path decision gates, route tests, metadata document tests, no-token-leakage proof, /mcp unchanged-behavior proof, and authenticated company binding without implementing routes, WWW-Authenticate behavior, OAuth/token/session/auth middleware, remote deployment/config, Apps SDK resources, public app behavior, app submission, DB/schema/package work, public assets, OpenAI API/model/provider calls, source mutation, finance writes, or FP-0122 runtime scope
• V2AP read-only ChatGPT App/MCP protected-resource metadata document-builder contracts through FP-0122, shipped as local/proof-only/read-only domain contract and proof tooling only, with post-merge credential/userinfo hardening. It adds a bounded metadata document builder and deferred route-response contract foundation without adding route behavior, route paths, protected-resource metadata routes, WWW-Authenticate behavior, OAuth/token/session/auth middleware, remote deployment/config, Apps SDK resources, public app behavior, app submission, DB/schema/package work, public assets, OpenAI API/model/provider calls, source mutation, or finance writes
• V2AQ read-only ChatGPT App/MCP protected-resource metadata route-input evidence contracts through FP-0123, shipped as local/proof-only/read-only domain contract and proof tooling only. It adds route-input evidence bundle and route-path decision contracts for accepted canonical URI evidence, credential-free authorization_servers, FP-0122 builder output/input dependency, no-token-leakage, authenticated company-binding prerequisite, /mcp unchanged prerequisite, and no-runtime posture while adding no route behavior, route path, protected-resource metadata route, WWW-Authenticate behavior, OAuth/token/session/auth middleware, remote deployment/config, Apps SDK resources, public app behavior, app submission, DB/schema/package/data/source-pack changes, public assets/listing copy/generated public prose, OpenAI API/model/provider calls, source mutation, or finance writes
• V2AR read-only ChatGPT App/MCP protected-resource metadata route implementation planning through FP-0124, shipped as docs-and-plan plus proof-gate compatibility only. It planned a future narrow local-only route implementation lane using an explicit FP-0123 route-input evidence bundle dependency and fail-closed canonical URI/auth-server/builder-output/no-token-leakage/company-binding//mcp unchanged gates, while deferring WWW-Authenticate behavior, remote/public host work, OAuth/token/session/auth middleware, Apps SDK resources, public app behavior, and app submission
• V2AS read-only ChatGPT App/MCP protected-resource metadata local route implementation through FP-0125, shipped as a local-only/read-only explicit-dependency route slice. It registers GET /.well-known/oauth-protected-resource/mcp only when app construction supplies a valid FP-0123 route-input evidence bundle; default buildApp() does not register it, the response is limited to resource, authorization_servers, scopes_supported, and bearer_methods_supported, and /mcp behavior remains unchanged. It adds no WWW-Authenticate behavior, OAuth/token/session/auth middleware, remote MCP deployment, deployment config, Apps SDK resources, public app behavior, app submission, DB/schema/package/data/source-pack work, public assets, OpenAI API/model/provider calls, source mutation, finance writes, generated advice, or autonomous action
• V2AT read-only ChatGPT App/MCP WWW-Authenticate auth-challenge sequencing through FP-0126, shipped as docs-and-plan plus proof-gate compatibility only. It plans future WWW-Authenticate resource_metadata challenge sequencing while keeping FP-0125 metadata route behavior, /mcp behavior, OAuth/token/session/auth middleware, remote/public host work, Apps SDK resources, app submission, DB/schema/package work, public assets, OpenAI API/model/provider calls, source mutation, finance writes, and autonomous action absent
• V2AU read-only ChatGPT App/MCP WWW-Authenticate auth-challenge contracts through FP-0127, shipped as local/proof-only/read-only pure domain contracts and direct proof tooling. It proves future Bearer challenge shape, required resource_metadata reference posture, local-vs-public metadata reference boundaries, missing/invalid token contract posture, future-only token failure modes, read-only least-privilege scope challenge guidance, no-token-leakage, unchanged /mcp, and no-runtime posture while adding no route behavior, WWW-Authenticate header emission, protected-resource metadata route behavior change, OAuth/token/session/auth middleware, token validation runtime, remote deployment/config, Apps SDK resource, public app behavior, app submission, DB/schema/package/data/source-pack work, public assets/listing copy/generated public prose, OpenAI API/model/provider calls, source mutation, finance writes, or autonomous action
• V2AV read-only ChatGPT App/MCP token-validation failure readiness contracts through FP-0128, shipped as local/proof-only/read-only pure domain contracts and direct proof tooling. It proves token-validation and token-parsing deferral, token/session storage and auth middleware deferral, token failure taxonomy, audience/resource validation prerequisites, read-only scope challenge prerequisites, authenticated user/org/company binding, client companyKey selector-only posture, token passthrough prohibition, no-token-leakage, no-runtime posture, and FP-0127 challenge contract preservation while adding no route behavior, WWW-Authenticate header emission, protected-resource metadata route behavior change, OAuth/token/session/auth middleware, token validation runtime, token parsing runtime, remote deployment/config, Apps SDK resource, public app behavior, app submission, DB/schema/package/data/source-pack work, public assets/listing copy/generated public prose, OpenAI API/model/provider calls, source mutation, finance writes, or autonomous action
• V2AW read-only ChatGPT App/MCP WWW-Authenticate challenge implementation sequencing through FP-0129, shipped as docs-and-plan plus proof-gate compatibility only. It sequences future missing-token and invalid-token challenge implementation, keeps malformed/expired/wrong-audience/wrong-resource/wrong-scope/wrong-org/revoked/replayed/token-passthrough modes in the later token-validation runtime lane, separates JSON-RPC refusal semantics from auth challenge emission, preserves FP-0128/FP-0127/FP-0125 boundaries, and adds no route behavior, header emission, protected-resource metadata route behavior change, OAuth/token/session/auth middleware, token validation runtime, token parsing runtime, remote deployment/config, Apps SDK resource, public app behavior, app submission, DB/schema/package/data/source-pack work, public assets/listing copy/generated public prose, OpenAI API/model/provider calls, source mutation, finance writes, or autonomous action
• V2AX read-only ChatGPT App/MCP missing-token WWW-Authenticate challenge through FP-0130, shipped as a local-only/read-only explicit-dependency route slice for the existing /mcp POST path. Default buildApp() and default /mcp behavior remain unchanged; only explicit app construction that co-supplies readOnlyAppMcpLocalProofGatedMissingTokenChallenge and an accepted readOnlyAppMcpProtectedResourceMetadataRouteInputEvidenceBundle can emit a bounded 401 Bearer WWW-Authenticate challenge with resource_metadata="/.well-known/oauth-protected-resource/mcp" for missing Authorization; challenge-only construction fails closed before route registration. Requests with an Authorization header fail closed without parsing, decoding, validating, introspecting, storing, forwarding, or relying on the token. It adds no new route path, protected-resource metadata route behavior change, OAuth/token/session/auth middleware, token validation runtime, token parsing runtime, remote deployment/config, Apps SDK resource, public app behavior, app submission, DB/schema/package/data/source-pack work, public assets/listing copy/generated public prose, OpenAI API/model/provider calls, source mutation, finance writes, or autonomous action
• V2AY through V2BB read-only ChatGPT App/MCP token-validation sequencing, runtime contracts, test-double contracts, and synthetic evaluator through FP-0131, FP-0132, FP-0133, and FP-0134, shipped without route consumption, token parser, JWT decoder, token validation runtime, token introspection, OAuth/token/session/auth middleware, invalid-token route behavior, remote MCP deployment, Apps SDK resources, public app behavior, app submission, DB/schema/package work, OpenAI API/model/provider calls, source mutation, finance writes, or autonomous action
• V2BC read-only ChatGPT App/MCP invalid-token challenge sequencing through FP-0135, shipped as docs-and-plan plus proof-gate compatibility only. It plans invalid-token WWW-Authenticate sequencing, 401/403 mapping posture, resource_metadata and scope challenge alignment, JSON-RPC refusal separation, no token echo tests, no route consumption of test doubles, and the future FP-0136 gate without adding route behavior, protected-resource metadata route behavior change, missing-token behavior change, invalid-token runtime behavior, token parser, JWT decoder, token validation runtime, token introspection, OAuth/token/session/auth middleware, DB/schema/package work, public assets, OpenAI API/model/provider calls, source mutation, finance writes, or autonomous action
• V2BD read-only ChatGPT App/MCP invalid-token challenge contracts through FP-0136, shipped as local/proof-only/read-only domain contracts and direct proof tooling only. It proves invalid-token failure taxonomy, future 401/403/400 mapping, future WWW-Authenticate Bearer parameter posture, resource_metadata alignment, challenged-scope authority, JSON-RPC refusal separation, no-token-echo, no route consumption of synthetic test doubles, and no-runtime posture without adding route behavior, protected-resource metadata route behavior change, missing-token behavior change, invalid-token header emission, token parser, JWT decoder, token validation runtime, token introspection, OAuth/token/session/auth middleware, DB/schema/package/data work, public assets, OpenAI API/model/provider calls, source mutation, finance writes, external communications, or autonomous action
• V2BE read-only ChatGPT App/MCP invalid-token challenge implementation readiness through FP-0137, shipped as docs-and-plan plus proof-gate compatibility only. It decides invalid-token route behavior cannot start from current repo truth, token-validation runtime result envelopes should precede 401/403/400 route mapping, HTTP challenge headers and JSON-RPC refusal envelopes remain separate, missing-token and protected-resource metadata route behavior remain unchanged, and synthetic test doubles stay out of routes without adding invalid-token headers, token parser, JWT decoder, token validation runtime, token introspection, OAuth/token/session/auth middleware, route changes, DB/schema/package work, OpenAI API/model/provider calls, source mutation, finance writes, public assets, external communications, or autonomous action
• V2BF read-only ChatGPT App/MCP token-validation runtime implementation planning through FP-0138, shipped as docs-and-plan plus proof-gate compatibility only. It decides the next safe lane is local proof-mode validation result envelope implementation planning, keeps production token validation blocked until issuer/audience/resource/scope, user-org-company, revocation/replay, provider/auth-server, canonical resource URI, and no-token-leakage gates are proven, keeps synthetic test-double evaluator output out of routes, and keeps invalid-token route behavior blocked until validation result envelopes exist without adding token parser, JWT decoder, token validation runtime, token introspection, invalid-token runtime behavior, OAuth/token/session/auth middleware, route changes, DB/schema/package work, OpenAI API/model/provider calls, source mutation, finance writes, public assets, external communications, or autonomous action
• V2BG read-only ChatGPT App/MCP token-validation result envelopes through FP-0139, shipped as local/proof-only/read-only pure domain contracts, builder/evaluator logic, focused specs, and direct proof tooling. It accepts sanitized descriptor inputs only, emits deterministic accepted/rejected token-validation result envelopes, keeps the failure taxonomy and HTTP posture recommendation symbolic/proof-only, and adds no raw token material, Bearer/JWT-like examples, token parser, JWT decoder, token validation runtime, token introspection, invalid-token route behavior, WWW-Authenticate header emission, OAuth/token/session/auth middleware, route changes, DB/schema/package work, OpenAI API/model/provider calls, source mutation, finance writes, public assets, external communications, or autonomous action
• V2BH read-only ChatGPT App/MCP invalid-token challenge implementation planning through FP-0140, shipped as docs-and-plan plus proof-gate compatibility only. It plans future invalid-token challenge implementation after FP-0139 result envelopes, decides future route behavior must consume FP-0139 result envelopes only, maps failure modes to future 400/401/403 posture and symbolic WWW-Authenticate errors without emitting headers, keeps FP-0134 synthetic evaluator output out of routes, preserves missing-token and protected-resource metadata route behavior, and adds no invalid-token runtime behavior, WWW-Authenticate header runtime, token parser, JWT decoder, token validation runtime, token introspection, OAuth/token/session/auth middleware, route changes, DB/schema/package work, OpenAI API/model/provider calls, source mutation, finance writes, public assets, external communications, or autonomous action
• V2BI read-only ChatGPT App/MCP invalid-token challenge local runtime through FP-0141, shipped as a local-only/read-only explicit-dependency adapter for existing POST /mcp. It consumes sanitized FP-0139 result envelopes only, maps malformed authorization/invalid_request to 400, invalid/expired/revoked token posture to 401, and insufficient scope to 403 with sanitized required-scope guidance, preserves the local resource_metadata dependency, keeps missing-token and protected-resource metadata route behavior separate, keeps JSON-RPC refusal separate, and adds no production token validation, token parser, JWT decoder, token introspection, OAuth/token/session/auth middleware, route expansion, DB/schema/package work, OpenAI API/model/provider calls, source mutation, finance writes, public assets, external communications, autonomous action, route integration implementation, or default app wiring
• V2BJ read-only ChatGPT App/MCP invalid-token route integration sequencing through FP-0142, shipped as docs-and-plan plus proof-gate compatibility only. It records Authorization-present activation, missing-token precedence, protected-resource metadata separation, FP-0139 result-envelope-only source posture, app-construction co-registration prerequisites, and failure taxonomy / HTTP / WWW-Authenticate consistency gates without changing /mcp, metadata route, or missing-token behavior and without adding production token validation, token parsing, JWT decoding, token introspection, OAuth/token/session/auth middleware, route integration implementation, default app wiring, DB/schema/package work, OpenAI API/model/provider calls, source mutation, finance writes, public assets, external communications, autonomous action, or FP-0143
• V2BK through V2CH read-only ChatGPT App/MCP invalid-token wiring, token-validation runtime-contract hardening, Authorization parser contracts/readiness/provider evidence, pure-domain parser implementation, parser route sequencing/readiness/integration, explicit app-construction parser route-decision pass-through, local adapter construction-readiness, explicit local adapter implementation/factory, runtime-safe local adapter factory import isolation, explicit opt-in app-construction adapter injection, local auth demo/smoke harness, local Evidence App demo bridge, local preview/demo UI bridge readiness, local preview/demo UI bridge implementation, local preview/demo visual QA/accessibility hardening, local Apps SDK component-resource readiness planning, local Apps SDK component-resource skeleton, explicit local Apps SDK component-resource registration, local render tool descriptor readiness, and local render tool descriptor skeleton through FP-0143, FP-0144, FP-0145, FP-0146, FP-0147, FP-0148, FP-0149, FP-0150, FP-0151, FP-0152, FP-0153, FP-0154, FP-0155, FP-0156, FP-0157, FP-0158, FP-0159, FP-0160, FP-0161, FP-0162, FP-0163, FP-0164, FP-0165, and FP-0166, shipped as local-only explicit dependency wiring plus proof/readiness/demo/skeleton/registration/descriptor-readiness contracts. FP-0160 adds only a static synthetic local preview/demo UI bridge on the existing preview route/components. FP-0161 adds only screenshotless local DOM/style visual QA and accessibility hardening for that bridge. FP-0162 adds only read-only local Apps SDK component-resource readiness planning. FP-0163 adds only a pure-domain inert local component-resource skeleton object with deterministic URI/MIME, static script-free HTML, empty CSP domain arrays, no public widget domain, and no server registration. FP-0164 adds only runtime-safe skeleton builder isolation and an explicit caller-provided registerResource helper for the same inert local skeleton. FP-0165 adds only proof/readiness planning for a future local render tool descriptor boundary. FP-0166 adds only a deterministic inert local render tool descriptor skeleton with sanitized local preview structuredContent schemas, read-only annotations, and a local resource URI/outputTemplate alias on that skeleton only. These records add no default MCP server resource registration, new route or API route, backend route behavior, live /mcp fetch, request-time harness execution, Apps SDK public iframe/resource runtime, render tool runtime, registerTool wiring, MCP server tool registration, output templates attached to data tools, component bundle, default auth adapter wiring, default evidence dispatch wiring, buildApp() or /mcp behavior change, authenticated evidence-tool execution, production token validation, token parser implementation, JWT decoder, JWKS fetch/cache implementation, token introspection, OAuth/session/auth middleware, provider selection/calls, DB/schema/package work, OpenAI API/model/provider calls, source mutation, finance writes, public assets, screenshots, generated public prose, app submission, external communications, or autonomous action.

Any implementation beyond the active FP-0166 local render tool descriptor skeleton boundary, shipped FP-0165 local render tool descriptor readiness boundary, shipped FP-0164 explicit local Apps SDK component-resource registration boundary, shipped FP-0163 local Apps SDK component-resource skeleton boundary, shipped FP-0162 local Apps SDK component-resource readiness planning boundary, shipped FP-0161 local preview/demo visual QA/accessibility hardening boundary, shipped FP-0160 local preview/demo UI bridge implementation boundary, shipped FP-0159 readiness boundary, shipped FP-0158 local Evidence App demo bridge, shipped FP-0157 local auth demo/smoke harness and helper hardening boundary, shipped FP-0156 explicit app-construction adapter injection boundary, shipped FP-0155 explicit local adapter implementation/factory boundary, shipped FP-0154 construction-readiness/proof boundary, shipped FP-0153 explicit app-construction parser route-decision pass-through and co-registration-hardening boundary, shipped FP-0152 explicit-dependency route-integration boundary, shipped FP-0151 route-integration implementation-readiness boundary, shipped FP-0150 parser material-observation/route-integration sequencing boundary, shipped FP-0149 pure-domain parser implementation boundary, and prior shipped V2 records remains future-plan-only. Public ChatGPT App implementation/submission, local preview/demo UI bridge expansion beyond FP-0161, default/public/server registerResource wiring, MCP server resource registration, MCP resource templates, render tool runtime, registerTool wiring, MCP server tool registration, output templates attached to data tools, default adapter wiring, default evidence dispatch wiring, production token validation runtime, token parsing runtime, OAuth/token/session/auth middleware implementation, provider selection/calls, route behavior expansion beyond the shipped explicit local lanes, remote MCP deployment, public Apps SDK resources, and any WWW-Authenticate behavior beyond FP-0130 missing-token and FP-0141/FP-0143/FP-0152 invalid-token explicit local preview gates remain absent. See docs/V2_BOUNDARY.md.

Screenshots And Demo Audit

The F12 manual UI/demo-readiness audit is recorded in docs/qa/v1-ui-demo-readiness-audit.md. Screenshot artifacts were not invented; the audit records the local browser screenshot-capture limitation and the remaining public demo polish needs.

For Codex Operators

Codex/operator workflow guidance lives in CODEX_README.md. The active guidance order is tracked in docs/ACTIVE_DOCS.md.

Contribution, Security, And Privacy

Contribution, security, and privacy policies are formalized in CONTRIBUTING.md, SECURITY.md, and PRIVACY.md. Demo and self-host guidance lives in docs/demo/local-demo-operator-journey.md, docs/demo/demo-data-policy.md, and docs/ops/self-host-baseline.md.

Finance-data privacy warning: do not commit real company exports, bank data, payroll data, customer/vendor lists, tax records, legal materials, credentials, or private board/lender materials. Use synthetic, fixture, or explicitly approved data only.

License

Apache-2.0. See LICENSE.