FIN Intranet Human-Agent Projection Layer Design

Date: 2026-05-13 Status: Draft v0.1 Related audit: docs/audits/FIN_INTRA_GTM_PLANNING_CODEBASE_GAP_AUDIT_2026-05-13.md

1. Design Goal

Build a company knowledge surface that is equally usable by humans and agents. The system must let a user inspect operational truth, planning docs, correspondence, generated summaries, decisions, SOPs, and artifacts in one coherent intranet. Agents must be able to query the same corpus through stable MCP tools with citations, permissions, and audit logs.

The design must preserve FIN architecture law:

• no new runtime table for documents
• no new database for the core product
• operational truth remains in events
• mutable index/projection state lives in knowledge
• embedded text and semantic search material lives in operational_memory
• actor-specific state lives in actors.memory
• bytes live behind StorageProvider

2. Product Principle

FIN should not ask users to understand whether something is an event, a file, a markdown note, an email attachment, a generated report, or a knowledge-base row. Users should browse a company memory graph. Agents should query a typed content graph. The implementation can keep strict domains underneath.

3. Sources Of Truth

Layer	Authority	Examples
Operational source of truth	events	order created, artifact imported, doc indexed, portal viewed, agent action
Authored document source	GitHub commit history	SOP markdown, decision record, planning doc, runbook
Mutable query index	knowledge	doc rows, artifact rows, collections, tenant config projections
Semantic text/chunks	operational_memory	extracted email text, doc chunks, artifact OCR chunks
Actor state	actors.memory	pins, recents, preferred doc lenses, last viewed docs
Bytes	StorageProvider	PDFs, images, DOCX exports, source attachments
Human static renderer	Quartz first, custom React later	FIN Canon, tenant intranet
Human operational renderer	Workspace/PWA/FIN Central	file explorer, doc reader, event narrative, admin panels
Agent renderer	MCP tools	search, get, graph, decision lookup

4. Content Node Model

The design introduces a shared product concept, not necessarily one physical schema: ContentNode.

4.1 Content Node Kinds

Kind	Storage pattern	Notes
doc	knowledge.domain = doc	Markdown-authored or system-projected document
artifact	Existing knowledge.domain = artifact	Managed file with bytes behind storage
artifact_collection	Existing knowledge.domain = artifact_collection	Saved/curated file lens
event_projection	knowledge.domain = doc, content.doc_kind = event_projection	Human digest generated from events
decision_record	knowledge.domain = doc, content.doc_kind = decision_record	Authored or generated decision log
runbook	knowledge.domain = doc, content.doc_kind = runbook	Operational runbook
proof_package	knowledge.domain = doc, linked artifacts/events	Nathel or federal proof packet

4.2 Content Node Required Fields

Every content node must carry:

• tenant_id
• stable ID
• source type
• title
• visibility/classification
• lifecycle status
• source attribution
• linked entities
• tags
• created/updated timestamps
• provenance pointers
• permission-relevant scope

Docs also carry:

• source repository
• source path
• commit SHA
• frontmatter
• outbound links
• inbound backlinks
• generated-from event IDs, if projected
• rendered URL, if published
• chunk IDs in operational_memory

Artifacts already carry many of these fields. The design should extend rather than replace the current artifact schema.

5. Ingestion Architecture

5.1 GitHub Vault Ingest

Trigger: GitHub webhook on push or pull request merge.

Flow:

1. Resolve tenant and repo from webhook signature/config.
2. Fetch changed markdown files.
3. Parse frontmatter, body, wikilinks, tags, headings, and anchors.
4. Resolve wikilinks to canonical source paths.
5. Update doc row in knowledge.
6. Write chunks to operational_memory.
7. Recompute backlinks for affected docs.
8. Emit doc.indexed.
9. Queue renderer rebuild for affected paths.
10. Emit doc.render_requested.

5.2 Event Projection Ingest

Trigger: selected event types.

Flow:

1. Event consumer receives domain event.
2. Projection policy determines affected doc types.
3. Deterministic renderer creates markdown from event/query context.
4. Generated markdown is committed to GitHub or stored as generated doc row, depending on doc type.
5. Doc row records generated_from_event_ids.
6. Emit doc.projection_generated.
7. Index as normal doc.

5.3 Artifact Ingest

Current artifact ingest remains the file foundation. It should gain:

• markdown support
• DOCX support
• XLSX support
• HTML support
• GitHub source system
• source repo/path/commit metadata
• linked doc/content node metadata

5.4 Correspondence Ingest

Email, Teams, SMS, and voice artifacts should enter as:

• raw source artifact or managed artifact
• extracted text in operational_memory
• linked work thread or communication thread
• optional generated doc summary when user-facing

The agent may summarize correspondence into a doc, but the raw source remains an artifact/source artifact with retention and privacy controls.

6. Human Surfaces

6.1 Internal Intranet

Audience: tenant employees, managers, FIN partners.

Purpose:

• SOPs
• planning docs
• decision records
• runbooks
• system-projected summaries
• proof packages
• agent skill docs

Initial renderer: Quartz behind Cloudflare Access.

Product renderer: Workspace/React document reader integrated with file explorer.

6.2 Employee Portal

Audience: tenant operational staff.

Purpose:

• today’s tasks
• inbound loads
• QC priorities
• FSMA paperwork
• communications
• narrow operational docs

Principle: employee portal is a role-scoped projection, not the full intranet.

6.3 Customer Portal

Audience: tenant customers.

Purpose:

• their orders
• their invoices
• delivery status
• permitted communications
• customer-safe documents

Principle: never expose vendor identity, cost basis, margins, exact inventory, internal communications, actor memory, or other customers’ data.

6.4 Marketplace

Audience: verified customers only.

Purpose:

• inventory discovery
• dynamic customer-specific price reveal
• commitment-gated pricing

Principle: marketplace projection has stricter latency and privacy rules than the intranet.

6.5 FIN Central

Audience: FIN operators.

Purpose:

• tenant readiness
• channel health
• KB health
• vault/render/MCP status
• federal tracker
• Nathel proof package
• eval/CI/deploy visibility

FIN Central is the control plane for multi-tenant rollout.

7. Agent Surfaces

7.1 Internal Runtime Tools

Internal agents need privileged tools for:

• doc search
• doc retrieval
• draft creation
• artifact linking
• event narrative generation
• proof package assembly
• tenant readiness checks

7.2 Tenant-Scoped MCP Tools

Tenant agents need:

• search_docs
• get_doc
• get_doc_graph
• get_backlinks
• list_by_tag
• get_decisions
• list_recent_changes
• search_content

All responses must include citations and source attribution.

7.3 Public/Tier 0 MCP Tools

Public external agents should only receive Plane 3 produce intelligence through stable, versioned, read-only tools. They must not share the same surface as tenant-private doc tools.

8. Permissions And Policy

8.1 Classification

Every content node has:

• visibility: personal, company, customer_visible, restricted, confidential
• data plane: private_workspace, relationship_data, universal_intelligence
• audience: internal, employee, customer, vendor, FIN operator, public MCP
• source trust: authored, system_projected, imported, external_source

8.2 Access Evaluation

Access is determined by:

1. tenant scope
2. actor role
3. content visibility
4. linked entity relationship
5. surface being served
6. external sharing policy
7. customer information boundary rules

8.3 Audit

Read and write actions emit events:

• doc.viewed
• doc.queried
• doc.indexed
• doc.rendered
• doc.draft_created
• doc.edit_proposed
• doc.version_committed
• artifact.viewed
• portal.viewed
• mcp.call_logged
• mcp.usage_metered

9. Renderer Strategy

9.1 Phase 0 Renderer

Use Quartz for the FIN Canon pilot because it quickly provides:

• markdown pages
• backlinks
• graph view
• tags
• mobile-friendly navigation
• Obsidian-compatible conventions

9.2 Phase 1 Product Renderer

Build a Workspace document reader that reuses:

• NativeFileExplorer
• MobileFilesPanel
• artifact catalog API
• source attribution/provenance UI
• role-aware auth

9.3 Phase 2 Custom Intranet Renderer

Replace or supplement Quartz when tenant-specific product needs outgrow the pilot:

• document-level permissions
• portal-specific filtering
• integrated editor
• agent sidecar
• event timeline overlays
• proof package exports

10. FIN Central Control Plane

FIN Central should grow from admin dashboard into operations control plane.

Required modules:

• tenant provisioning checklist
• tenant tier/capability matrix
• channel health: email, SMS, voice, WhatsApp
• GitHub vault status
• doc ingest status
• Quartz/render status
• MCP key status
• KB freshness and Knowledge Forge import status
• Nathel proof ledger
• federal readiness tracker
• Orgo exec-agent status

11. Nathel Anchor Design

Nathel should be treated as the first proof-led program:

• internal FIN/Nathel canon intranet
• selected internal employee portal slices
• customer portal-only pilots
• customer portal-plus-agent pilots
• executive-agent pilot for select leaders
• proof package showing operational value by stakeholder

The first release should avoid marketplace complexity unless it directly supports a proof milestone.

12. Non-Goals For First Build

• automatic two-way Obsidian reverse projection without review
• marketplace checkout
• full HR replacement
• generic document management clone
• broad custom tenant theming
• federal certification claims beyond readiness artifacts
• direct exposure of raw event JSON to non-admin humans

13. Design Conclusion

The human-agent projection layer should be implemented as a content graph over existing FIN primitives. GitHub gives authored documents version control. Events give operational truth. Knowledge gives queryable projections. Operational memory gives semantic retrieval. Storage gives bytes. FIN Central gives operations control. MCP gives agents a stable contract. Human renderers give people a digestible company memory surface.