FIN Intra GTM Planning To Codebase Gap Audit

Date: 2026-05-13 Status: Draft v0.1 Primary workspace: /Users/robert/Projects/FIN/_03_Dev/fin-agentic Planning source folder: FIN Intra_GTM/

1. Purpose

This audit compares the FIN Intra_GTM planning set against the active fin-agentic codebase. The goal is not only to audit the central intranet, projection, and MCP thesis. The goal is to preserve the whole planning session: agentic system design, external MCP products, Knowledge Forge and FIN Central KB strategy, Nathel anchor sequencing, customer and employee portals, executive agent offers, FIN Central operations, Cloudflare/Neon/Orgo deployment planning, federal positioning, and solo-operator execution discipline.

The output of this audit should become the input to:

• docs/design/FIN_INTRANET_HUMAN_AGENT_PROJECTION_LAYER_DESIGN_2026-05-13.md
• docs/engineering/FIN_INTRANET_HUMAN_AGENT_PROJECTION_ENGINEERING_SPEC_2026-05-13.md
• docs/processes/FIN_INTRANET_HUMAN_AGENT_PROJECTION_EXECUTION_PROGRAM_2026-05-13.md

2. Source Inventory Reviewed

2.1 Markdown Planning Documents

File	Primary topics	Audit status
FIN Intra_GTM/FIN Intranet Layer.md	Intranet, projections, GitHub vault, Quartz, doc MCP, portals, marketplace, HR, editor distinction	Reviewed
FIN Intra_GTM/FIN - Part 1 - Technical Architecture.md	Event sourcing, three data planes, MCP catalog, Cloudflare/Neon tiers, tenant GitHub repos, Obsidian, comms, Orgo, external MCP	Reviewed
FIN Intra_GTM/FIN - Part 2 - Offerings and GTM.md	Tier 0-4 offers, pricing, support, Nathel, ICPs, federal, FIN Central operations, Orgo	Reviewed
FIN Intra_GTM/FIN - Comprehensive Synthesis and Program Design.md	Decision canon, end-to-end architecture, strategic synthesis, execution phases	Reviewed
FIN Intra_GTM/FIN - Map of Content.md	Planning index, graph anchors, active threads	Reviewed
FIN Intra_GTM/The Three Data Planes.md	Plane 1 private workspace, Plane 2 relationship data, Plane 3 universal intelligence	Reviewed
FIN Intra_GTM/FIN Central.md	Operator footprint, cloud footprint, tenant relationship, operations gaps	Reviewed
FIN Intra_GTM/FIN Federal Pipeline.md	VOSB/TAA/NDAA posture, target agencies, federal product shape, 18-month roadmap	Reviewed
FIN Intra_GTM/Nathel Anchor Strategy.md	Live test, stakeholder value proof, strategic customer structure, post-Nathel expansion	Reviewed
FIN Intra_GTM/Tier 2 - Produce Agent Pro.md	Pro offer, live Obsidian sync, multi-vendor, voice/WhatsApp, migration path	Reviewed
FIN Intra_GTM/Burnout Protection.md	Operator discipline, live test constraints, first hire discipline	Reviewed

2.2 DOCX Planning Documents

File	Relationship to Markdown	Audit status
FIN Intra_GTM/FIN_Part1_Technical_Architecture.docx	DOCX companion to Part 1. Extracted text is shorter than Markdown, so it is not proven identical.	Needs canonicality check
FIN Intra_GTM/FIN_Part2_Offerings_and_GTM.docx	DOCX companion to Part 2. Extracted text is shorter than Markdown, so it is not proven identical.	Needs canonicality check

2.3 Current Codebase Evidence Anchors

Area	Evidence
Architecture law	AGENTS.md, db/schema.sql
Artifact schema	packages/shared/src/schemas/contracts/artifact.ts
Artifact MCP tools	packages/mcp-server/src/tools/artifacts.ts, packages/mcp-server/src/tools/index.ts
Artifact HTTP routes	packages/mcp-server/src/routes/artifacts.ts
Source artifact ingestion	packages/mcp-server/src/ingestion/source-artifacts.ts, packages/shared/src/email-parsing.ts
Workspace file UI	packages/workspace/src/components/files/NativeFileExplorer.tsx, packages/workspace/src/mobile/MobileFilesPanel.tsx, packages/workspace/src/components/right-rail/FilesTab.tsx
Workspace route map	packages/workspace/src/App.tsx
FIN Central event surface	packages/workspace/src/pages/fin-central/EventLogPage.tsx, packages/mcp-server/src/platform/handlers/platform-events.ts
FIN Central knowledge surface	packages/workspace/src/pages/fin-central/KnowledgeBasePage.tsx, packages/mcp-server/src/platform/handlers/platform-knowledge.ts
Authoring primitive	packages/workspace/src/components/authoring/CollaborativeAuthoringPanel.tsx
Existing artifact catalog design	docs/engineering/FINN-AGENTIC-OPERATING-LAYER-ARTIFACT-CATALOG-INTEGRATION-2026-04-29.md

3. Executive Findings

F-001: The strategic vision is coherent and differentiated

The planning set repeatedly converges on the same core product idea: FIN is not only an ERP or an agent. FIN is an event-sourced operational core that produces human-readable, agent-readable, role-scoped projections across multiple surfaces. This is coherent with the existing architecture and with the current artifact catalog work.

F-002: The largest planning/code mismatch is the proposed documents table

FIN Intranet Layer.md proposes storing parsed markdown in a Neon documents table. That conflicts with the active four-table architecture law in AGENTS.md. The correct path is to represent intranet documents as knowledge rows, record document lifecycle in events, store chunks and embeddings in operational_memory, and keep bytes/source files behind StorageProvider.

This is not a small naming fix. It affects the ingest pipeline, MCP tools, Quartz rebuild triggers, audit events, and FIN Central admin design.

F-003: The codebase already has a strong file/artifact foundation

The current codebase already implements:

• knowledge.domain = artifact
• knowledge.domain = artifact_collection
• artifact visibility and lifecycle fields
• source attribution
• version history
• thread linking
• MCP tools for list/get/import/version/archive/delete/link
• desktop and mobile file browsers
• upload and route integration

This should be extended into the intranet/content graph. It should not be replaced by a parallel document subsystem.

F-004: The current file viewer is not yet the intranet

The file viewer is an operational artifact browser. It is not yet a GitHub-backed markdown vault reader, document graph explorer, decision log, Quartz projection, or agent-augmented editor.

Important gaps:

• no markdown/docx/xlsx/html upload support in the upload route
• no GitHub source adapter
• no frontmatter/wikilink/backlink parser
• no doc graph tools
• no /files/:artifactId route despite generated share links
• no general document editor or Git-backed review workflow

F-005: FIN Central exists, but not as the planned multi-tenant control plane

FIN Central currently has admin surfaces for events, knowledge health, sessions, tenants, actors, and evals. The planning set asks for a broader operations surface: tenant provisioning, channel health, tenant runbooks, KB editing, federal tracker, Cloudflare/Neon/Orgo control, deployment status, and customer success visibility. Those are mostly not yet implemented as a unified operator system.

F-006: The Tier 0 MCP product needs a public-contract layer

The codebase has many MCP/runtime tools, but the Tier 0 product needs a different layer:

• stable external MCP contract versioning
• public docs/examples
• rate limits and billing meters
• self-service keys
• tenant-neutral public produce intelligence
• strict separation from internal write tools and tenant data

Planning identifies the product, but implementation work remains.

F-007: Nathel is the right anchor, but the proof loop needs tighter artifacts

The Nathel plan is strategically sound. It needs a proof ledger that connects:

• live test actions
• stakeholder-specific value proofs
• screenshots/API/browser evidence
• financial or operational value claims
• case-study-ready narratives
• next commercial ask

This should live in FIN Central and in a Git-tracked planning/proof package.

F-008: Customer portals, employee portals, and marketplace are currently product tracks, not one feature

The intranet layer frames seven connected surfaces. That is useful, but implementation should separate them:

• internal intranet and FIN canon
• employee portal
• customer portal
• verified-customer marketplace
• PWA operational interface
• public marketing site
• FIN Central admin portal

Each surface has different latency, privacy, pricing, and agent-role rules.

F-009: Executive agents and Orgo are under-specified in code

The planning set includes Tier 3 executive agents, Orgo cloud workstation visibility, real-time voice, and deeply customized workflows. Current code has agent runtime, comms, and workspace pieces, but no explicit Orgo integration contract, exec-agent provisioning model, visible workstation audit trail, or Tier 3 service boundary.

F-010: Knowledge Forge and FIN Central KB need a formal relationship contract

The planning set depends on a shared produce KB plus tenant-scoped private and relationship data. The repo already has Knowledge Forge readers and source artifact patterns, but the product contract should specify:

• what flows from Knowledge Forge into FIN Central
• what tenant learnings can become aggregate/public intelligence
• what is never allowed to cross tenant boundaries
• how citations and source freshness are represented in MCP results

F-011: Federal path requires earlier runtime flags than the plan states

The federal lane cannot be bolted on later. The plan mentions US-origin models, TAA/NDAA posture, read-only intelligence MCP, and recall/traceability. Runtime work should include early flags for:

• federal-safe model routing
• federal-safe embedding path
• data residency notes
• audit export
• SBOM/provenance
• tenant isolation proof

F-012: Solo-operator constraints should become execution gates

Burnout Protection.md is not a side note. It should become a program constraint: no sprawling implementation without proof milestones, no new features during live test unless they support the proof loop, explicit stop conditions, and first-hire trigger criteria.

4. Planning Theme Audit Matrix

4.1 Intranet, GitHub Vault, Markdown Projection

Planning claim	Current evidence	Gap	Recommendation
Canonical markdown plus event history lives in private GitHub repos	Planning docs only	No GitHub webhook/source adapter found in runtime	Add github_vault source adapter and store commit SHA/path in knowledge.domain = doc
Human-authored and system-projected markdown coexist	Planning docs only	No projection writer for markdown docs	Define doc.projection_generated events and deterministic projection jobs
Ingest parses frontmatter, wikilinks, tags, backlinks	Planning docs only	No parser/runtime implementation found	Add parser package with tests using real FIN Intra_GTM fixtures
Parsed structure stored in documents table	Conflicts with AGENTS.md	Would violate four-table rule	Store doc index as knowledge JSONB and chunks in operational_memory
Quartz human renderer for pilot	Planning docs only	No Quartz fork or deployment config found	Treat Quartz as Phase 0 pilot renderer, not source of truth
Obsidian is editor, not data store	Planning and architecture agree	Needs code guardrails	Make GitHub commit history the authored-doc ledger; Obsidian remains replaceable

4.2 File Viewer, File Editor, Content Graph

Planning claim	Current evidence	Gap	Recommendation
File viewer exists in operational PWA	NativeFileExplorer, MobileFilesPanel, FilesTab	Viewer is artifact-centric, not intranet-doc-centric	Extend viewer into content explorer with artifact/doc modes
Files should be versioned and agent-readable	Artifact schema has version and source attribution	No markdown/doc graph version semantics	Add doc version fields: commit SHA, source repo, source path, generated-from event IDs
Shareable file links	Viewer generates /files/:artifactId	App routes do not define /files/:artifactId	Add deep-link route and permission-gated artifact/doc reader
Users need an editor, not only viewer	CollaborativeAuthoringPanel exists	It drafts prose but is not a document editor	Build DocEditorPanel using agent draft + Git commit/review workflow
Enterprise correspondence should be captured	Source artifact/email ingestion exists	Needs unified content graph and policy controls	Link correspondence artifacts to docs/work threads/events with explicit privacy class

4.3 MCP System

Planning claim	Current evidence	Gap	Recommendation
MCP is the contract layer	Existing tool catalog is broad	External MCP product surface is not isolated enough	Define internal, tenant, and public MCP surfaces
Doc MCP tools expose the intranet	No search_docs, get_doc, get_backlinks, get_doc_graph, get_decisions found	Missing central agent-facing intranet surface	Implement doc tools as pure functions over knowledge and operational_memory
Tool contracts are versioned	Planning says versioned	Existing tools are not uniformly exposed as public versioned contracts	Add external MCP version registry and compatibility tests
Every MCP call is audited and metered	Some event patterns exist	Tier 0 billing/metering not productized	Add mcp.call_logged, mcp.usage_metered, and dashboard views

4.4 Agentic System And Multi-Channel Comms

Planning claim	Current evidence	Gap	Recommendation
Agents issue commands, do not bypass deterministic logic	Existing agent/tool architecture aligns	Needs explicit alignment in new doc/editor tools	Make all doc mutations event-backed and policy-gated
Tiered agents have email/SMS/voice/WhatsApp	Repo has comms, Telnyx, inbox, webhooks work	Offering-specific provisioning not unified	Add tenant provisioning checklist and channel readiness dashboard
Exec agents can use Orgo	Planning docs only	No Orgo integration contract found	Define Orgo as premium visible-operation adapter with audit events
Agents need provenance and citations	Existing cards/artifacts include source attribution	Doc MCP result citations not implemented	Require citations on every doc/search/MCP response

4.5 Knowledge Forge, KB, And Three Data Planes

Planning claim	Current evidence	Gap	Recommendation
Plane 3 produce intelligence powers all tiers	Knowledge Forge readers and KB surfaces exist	Product boundary is not fully specified	Add KB source/freshness/citation contract
Plane 1 private workspace stores tenant/user knowledge	Actors memory and artifacts exist	Doc/wiki private workspace is not modeled	Add doc_scope = private_workspace and actor/tenant permission mapping
Plane 2 relationship data powers portals	Some customer/vendor/event code exists	Portal projections not defined in doc/content layer	Define relationship-scoped doc and artifact filters
Tenant learnings may enrich FIN Central	Strategic idea exists	Risk of cross-tenant leakage	Add opt-in aggregate learning policy and deterministic anonymization gate

4.6 Nathel Anchor And Customer/Portal Strategy

Planning claim	Current evidence	Gap	Recommendation
Nathel live test validates value	Planning docs only in this folder	Proof artifacts are not centralized in repo/runtime	Add Nathel proof ledger and FIN Central pilot dashboard
Some Nathel customers get agents + portals, others portal only	Planning docs imply segmentation	No customer portal entitlement model found for this program	Define portal-only, portal-plus-agent, and internal-user entitlement tiers
Anchor funding conversation follows proof	Strategic plan exists	Needs evidence package template	Build case-study package template and value proof schema
Tier 4 rollout follows post-funding sequence	Planning docs	Needs implementation waves	Tie Tier 4 rollout to execution program tracks

4.7 FIN Central Operations

Planning claim	Current evidence	Gap	Recommendation
FIN Central manages tenants	Tenant admin pages exist	Provisioning workflow not end-to-end	Add tenant readiness lifecycle and provisioning runbook UI
FIN Central manages channel health	Some health/admin surfaces exist	Channel-level health not unified	Add email/SMS/voice/GitHub/Quartz/MCP status panels
FIN Central edits KB and tracks federal pipeline	Knowledge page exists	KB editing and federal tracker not implemented as operational tools	Add read-only dashboards first, mutating workflows later
FIN Central controls Cloudflare/Neon/Orgo deployment state	Planning only	No unified adapter/status model	Add deployment inventory projection from events/config

4.8 GTM, Pricing, And Offers

Planning claim	Current evidence	Gap	Recommendation
Five tiers are configurations of one platform	Planning docs	Runtime entitlements not mapped to tier configs	Add tier capability matrix and provisioning templates
Tier 0 MCP monetizes KB	Planning docs	Public MCP product missing	Start with private beta, docs, usage events, and key management
Tier 2 Pro is economic anchor	Planning docs	Needs repeatable onboarding and service boundaries	Encode onboarding checklist and support SLA into FIN Central
Tier 3 exec agent is premium relationship product	Planning docs	Needs Orgo/voice/calendar/email integration contract	Treat as separate track after Tier 2 proof
Tier 4 ERP is destination	PWA/runtime exist in pieces	Needs phased customer-facing surfaces	Sequence from intranet + proof + portal before marketplace

4.9 Federal Pipeline

Planning claim	Current evidence	Gap	Recommendation
VOSB/TAA/NDAA posture differentiates FIN	Planning docs	Runtime federal mode not explicit	Add federal readiness controls to design/spec
Read-only intelligence MCP is federal entry	Planning docs	Public/federal MCP surface missing	Use Tier 0 MCP contract as base with federal-safe provider route
Recall/traceability tooling matters	Existing recall/event concepts in repo	Federal product package not assembled	Add federal proof bundle track after doc/MCP foundation

4.10 Operator Discipline

Planning claim	Current evidence	Gap	Recommendation
Solo operator through early phase	Planning docs	Execution docs often sprawl	Make execution program explicitly wave-gated
No new features during live test	Planning docs	Needs program stop rules	Add stop conditions and proof-first gates
First hire after proof/revenue	Planning docs	No hiring trigger ledger	Add first-hire trigger criteria to execution program

5. Architecture Reconciliation Decisions

ARD-001: No new documents table

Decision: Replace the planned documents table with knowledge.domain = doc or equivalent doc content domain. Use operational_memory for chunks and embeddings. Use events for lifecycle.

Rationale: Preserves the four-table law and aligns with the existing artifact catalog addendum.

ARD-002: GitHub is the authored-document ledger, not the operational source of truth

Decision: Authored markdown source history lives in GitHub. Operational truth remains the event store. The knowledge doc row is an index/projection that can be rebuilt from GitHub plus events.

Rationale: Prevents a false choice between Git history and event sourcing.

ARD-003: Obsidian and Quartz are replaceable interfaces

Decision: Obsidian is an authoring client. Quartz is the pilot reader. Neither owns product truth.

Rationale: Preserves portability and avoids vendor/editor lock-in.

ARD-004: Artifact and doc models should converge as content nodes

Decision: Keep current artifact schema, but introduce a shared content-node concept in design/spec language. Artifacts are binary/source files. Docs are markdown/rendered textual nodes. Both participate in graph/search/provenance.

Rationale: This avoids splitting the user experience into “files” and “wiki” when users need one company knowledge surface.

ARD-005: FIN Central is the control plane for multi-tenant rollout

Decision: Build FIN Central readiness before broad tenant rollout. It should track tenant state, channels, portal entitlements, MCP keys, GitHub vault state, Quartz/render status, KB freshness, and proof packages.

Rationale: Multi-tenant deployments without an operator control plane will turn into manual consulting chaos.

6. Priority Gap List

Priority	Gap	Why it matters
P0	Planning/code conflict around documents table	Must settle before any ingest implementation
P0	No GitHub vault adapter or doc schema	Blocks intranet/MCP/doc graph
P0	No doc MCP tools	Blocks agentic intranet value
P0	No permission model for docs/folders/portals	Blocks customer/employee/vendor surfaces
P1	File viewer deep-link route missing	Breaks shareable file experience
P1	Upload/content support excludes markdown/docx/xlsx/html	Blocks enterprise doc ingestion
P1	FIN Central lacks tenant/channel/readiness control plane	Blocks multi-tenant rollout
P1	Tier 0 public MCP contract not isolated	Blocks self-service/public product
P1	Nathel proof ledger not formalized	Weakens anchor conversion
P2	Orgo exec-agent integration not specified	Blocks Tier 3 premium offer
P2	Federal-safe runtime mode not explicit	Weakens federal path
P2	DOCX/Markdown canonicality unresolved	Creates source sprawl

7. Recommended Deliverable Sequence

1. Design doc: define the human-agent projection layer and reconcile the four-table model with GitHub/Quartz/Obsidian.
2. Engineering spec: specify schemas, event types, routes, tools, parser, UI, FIN Central additions, tests, and proof gates.
3. Execution program: break work into waves that protect the live Nathel proof loop and avoid solo-operator overload.
4. Canonicality pass: decide whether Markdown or DOCX is source of truth, then convert the other to generated/export status.
5. Implementation wave 1: doc schema/parser/tools plus deep-link fix.

8. Open Decisions

ID	Decision	Default recommendation
OD-001	Is Markdown canonical over DOCX?	Yes. DOCX should become generated export.
OD-002	What is the doc knowledge domain name?	doc, unless local naming prefers intranet_doc.
OD-003	Should FIN Canon live in this repo or a separate private repo?	Separate private repo for pilot; index into FIN.
OD-004	Is Quartz a product dependency or pilot accelerator?	Pilot accelerator.
OD-005	What doc types ship first?	Decision records, SOP/runbook, Nathel proof package, system-projected daily summary.
OD-006	What gets surfaced to Nathel customers first?	Portal-only read views before agent-enabled portal flows.
OD-007	How much reverse projection is allowed in v1?	Draft/review only. Avoid automatic two-way writes until policy gates are proven.

9. Audit Conclusion

The planning set is strategically strong and internally mostly coherent. The codebase already contains the key foundations: event store discipline, knowledge rows as mutable projections, operational memory, artifact catalog, file viewer, agent runtime, MCP tools, and FIN Central admin surfaces.

The gap is not that the codebase lacks everything. The gap is that the planning session created a broad product vision faster than the runtime has been shaped into a unified content/control plane. The next step is to formalize that plane without violating the four-table architecture, then implement it in proof-led waves.