GroundTruth OS

What is GroundTruth OS?

GroundTruth OS is a knowledge distillation platform that transforms a founder's scattered documents, decks, and notes into a structured canonical knowledge base, then uses that knowledge base to power AI agents for sales, marketing, support, and product.

Think of it as your company's single source of truth. Instead of tribal knowledge living in someone's head, a forgotten Google Doc, or a half-finished Notion page, GroundTruth OS extracts, organises, and maintains 16 canonical documents that fully describe your business.

The Problem

Early-stage companies have a knowledge problem:

• Business context is fragmented across pitch decks, strategy docs, Slack threads, and the founder's memory
• Every new hire, advisor, or AI tool needs the same context, and gets an incomplete, inconsistent version of it
• When you use AI agents (for outreach, content, support), they hallucinate because they don't have the ground truth about your business
• Decisions get made without precedent. The same debates happen over and over

The Solution

GroundTruth OS runs a Distillation Bootstrap: a structured process that takes what you already have and turns it into a complete, consistent, actionable knowledge base in under 90 minutes.

Getting Started

When you sign up for GroundTruth OS, you'll go through a guided onboarding:

1. Create your organization. Name your workspace (this is where your team's knowledge lives)
2. See how it works. A quick visual walkthrough of the Ingest → Distill → Export pipeline
3. Upload your first documents. Drop in any existing business docs, or skip and explore first

Once you're in, the dashboard shows an onboarding checklist tracking your progress:

• Upload your first document
• Review extracted knowledge
• Run an AI interview session
• Export your first agent prompt

The checklist auto-completes as you work and can be dismissed when you're ready.

The 16 Canonical Documents

Your knowledge base consists of 16 documents in two categories. Each has required fields that must be populated and optional fields for depth. Use gthos docs templates to see all available types, and gthos docs init to create any that haven't been initialized yet.

Business Documents (10)

Engineering Documents (6)

The web UI shows [All] [Business] [Engineering] tabs on the Canonical Documents page to filter by category.

How It Works

The Distillation Bootstrap follows a five-step workflow:

Step 1: Ingest

Upload your existing documents or import from Google Drive. GroundTruth OS accepts:

• PDF files (pitch decks, strategy docs, investor updates)
• Word documents (.docx, business plans, proposals)
• Plain text and Markdown (notes, outlines, braindumps)
• Pasted text (copy-paste from Google Docs, Notion, email threads)
• Google Docs (imported directly via Google Drive integration)

Upload everything you have. The more context, the better the extraction. Don't worry about duplicates or messy formatting. The AI handles it.

Google Drive Import

If you connect Google Drive (Settings → Integrations), you'll see an Add from Google Drive button in the Ingest sheet. This lets you search and browse your Drive files, select the ones you want, and import them directly. No downloading required. Google Docs are automatically exported as text.

Step 2: Extract

Once your documents are uploaded, hit Run Extraction. The AI reads through all your source material and:

• Maps every piece of business-relevant information to the correct canonical document and field
• Rates its confidence on each extraction (high / medium / low)
• Flags conflicts where two documents say different things about the same topic
• Identifies gaps: required fields that couldn't be populated from the source material

This typically takes 30-60 seconds depending on document volume.

Step 3: Interview

This is where the magic happens. An AI interviewer conducts a structured conversation with you to:

1. Resolve conflicts. "Your pitch deck says X but your strategy doc says Y. Which is current?"
2. Fill required gaps. "I couldn't find your unit economics anywhere. What's your current CAC and LTV?"
3. Add depth. "You mentioned three competitors. Are there others your prospects compare you to?"

The interview follows a priority order (North Star first, then ICP, Business Model, etc.) and asks one question at a time. It's designed to be conversational and efficient. Expect 20-40 minutes for a thorough session.

As you answer, fields are populated in real-time. You'll see toast notifications as each field is captured.

Step 4: Review

Once the interview is complete, review your canonical documents in the Knowledge Base, a two-panel layout with all 16 documents in the sidebar and content on the right:

• Browse: click any document in the sidebar to see its content instantly. Documents with unread changes (from teammates, CLI, or API) show a blue dot.
• Edit any field directly: click a field value to edit it inline. Changes auto-save when you click away.
• Commit: click the Commit button to snapshot the current version. Optionally add a note via "Add note".

Step 5: Export

With your canonical documents committed, you can:

• Generate agent system prompts. Select an agent type (Sales, Marketing, Support, Product) and get a compiled system prompt that includes all relevant canonical context. Copy it directly into any AI tool.
• Export the full package. Download all 16 documents as a ZIP (JSON + human-readable Markdown)
• Export the Decisions Log. Clean Markdown for board meetings or due diligence

Tips for Getting the Best Results

Before You Start

• Gather everything. Pitch decks, business plans, strategy docs, competitive analyses, customer interview notes, pricing spreadsheets, board decks. The more you upload, the less you'll need to answer manually.
• Recent is better. If you have multiple versions of a document, upload the most recent. The AI will flag conflicts if older versions contain contradictory information.
• Don't clean up your docs first. The AI is good at extracting signal from messy, informal documents. Raw notes are fine.

During the Interview

• Be specific. When the AI asks "Who is your customer?", don't say "SMBs". Say "Head of Marketing at B2B SaaS companies with 50-200 employees who currently manage outbound manually."
• It's OK to say "I don't know yet." The AI will mark the field as incomplete and move on. You can come back to it later.
• Push back if the question doesn't fit. Not every field will be relevant to every business. Tell the AI if something doesn't apply and it will adapt.
• Use the conflict cards. When the AI surfaces a contradiction, take a moment to think about which version is actually current. These are often the most valuable moments in the process.

After the Interview

• Edit before committing. The AI's phrasing might not match how you'd say it. Edit fields to use your authentic voice. These documents will power your agents.
• Commit documents you're confident in. You don't need to commit all 16 at once. Start with North Star and ICP, then work outward.
• Re-run the interview. You can start a new interview session any time to fill gaps or update fields as your business evolves.
• Test your agent prompts. After exporting a Sales agent prompt, paste it into Claude or your AI tool of choice and run a few test conversations. If the agent gets something wrong, go back and update the canonical doc.

Ongoing Usage

GroundTruth OS is designed to be a living system, not a one-time exercise. As your business evolves:

• Upload new documents (investor updates, new research, revised decks) and re-run extraction
• Run focused interviews to update specific areas
• Use the Decisions Log to record significant business decisions with context and rationale. This becomes your company's institutional memory
• Re-export agent prompts after major updates to keep your AI tools current

CLI

The gthos CLI lets you access your canonical knowledge base from the terminal. Useful for AI agents (Claude Code, research bots), automation, and quick lookups.

Installation

cd cli && npm install && npm run build
# Then from the cli/ directory:
node dist/index.js --help

Login

gthos auth login

This opens your browser to the normal login page. Sign in with Google (or magic link), and the CLI automatically receives your session. No API keys needed. The session lasts 30 days.

For CI/headless environments, use an API key instead:

gthos auth login --key gthos_sk_...

Document Templates & Initialization

GroundTruth OS ships with 16 canonical document templates in two categories:

Business (10 docs): North Star, Business Model & Metrics, ICP & Personas, Competitive Landscape, Customer Research, Messaging & Positioning, Sales Playbook, Channel & Growth, Product Roadmap, Decisions Log

Engineering (6 docs): Technical Architecture, PRDs, Implementation Plans, Software Changelog, Error & Incident Log, Dev Standards

To see all available templates:

gthos docs templates

To create document instances for any templates not yet initialized in your workspace:

gthos docs init

This is safe to run at any time. It only creates docs that don't already exist. Documents are created from the template with empty default fields. The web UI and AI extraction also create documents automatically, but docs init lets you ensure all 16 types are available immediately.

Common Commands

# List all canonical docs with completeness
gthos docs list

# See available templates (even ones not yet created)
gthos docs templates

# Create any missing docs from templates
gthos docs init

# Read a specific document
gthos docs get north_star
gthos docs get icp_personas --field buyer_personas

# Read all docs (pipe into an agent)
gthos docs get --all --format markdown

# Update a field
gthos docs update dev_standards --field code_conventions --value "TypeScript strict, no any types, semantic color tokens"

# Commit a document
gthos docs commit technical_architecture --rationale "Initial architecture documented"

# Compile a system prompt for an agent
gthos export prompt sales
gthos export prompt engineering

# Record a decision
gthos decisions add --doc-type business_model \
  --question "Free tier?" --resolution "Yes, 1 workspace"

# Check workspace status
gthos workspace info

Output Formats

All read commands default to JSON (pipe-friendly). Use --format markdown for human reading.

gthos docs get north_star --format markdown
gthos export package --format markdown

Activity Log

The Activity Log tracks all changes to your knowledge base (creates, updates, deletes, and exports) across all access methods. Navigate to Activity in the sidebar or go to /activity.

What's Tracked

Every mutation is logged with:

• Action: create, update, delete, or export
• Resource: which canonical doc, source document, interview, decision, workspace, member, or API key was affected
• Who: the user's name and email
• How: whether the action came from the Web UI, CLI, MCP, or an API key
• When: timestamp
• Metadata: action-specific details like doc type, completeness, field counts (click to expand)

Read events (viewing pages, opening documents) are not logged in the activity feed. They're tracked via PostHog analytics instead.

Filtering

Use the dropdown filters at the top of the page to narrow by:

• Source: Web UI, CLI, MCP, or API Key
• Action: Create, Update, Delete, Export
• Resource type: Canonical Docs, Source Documents, Interview, Decisions, Extraction, Agent Prompt, Package, Workspace, Member, API Key

Changes API

CLI tools, MCP servers, and API agents can query what's changed since they last checked:

• GET /api/changes?workspaceId=...&since=... returns mutations since a timestamp. Add &excludeSelf=true to filter out your own changes.
• POST /api/changes/ack updates your "last seen" checkpoint so the next call only returns new changes.

Unread Detection

Canonical docs show an unread indicator (blue dot) when another user or agent has updated them since you last viewed the knowledge base. Your own changes never trigger unread badges.

MCP Client Detection

For MCP server integrations, send X-Client-Type: mcp as a request header so the audit log correctly identifies the source. CLI and API key requests are detected automatically from the authorization method.

Google Drive Integration

Connect your Google Drive to import documents without downloading and re-uploading.

Connecting

1. Go to Settings → Integrations (or navigate to /settings/integrations)
2. Click Connect Google Drive
3. Sign in with your Google account and grant read-only access
4. You'll be redirected back with a "Connected" status

Importing Files

Once connected, the Ingest sheet shows an Add from Google Drive button. Click it to:

• Search your Drive by file name
• Browse recent files sorted by last modified
• Select multiple files (Google Docs, PDFs, DOCX, TXT, MD)
• Click Import to pull them into your workspace as source documents

Imported files go through the same extraction pipeline as uploaded files. Google Docs are automatically exported as plain text.

Folder Sync

For bulk imports, use the folder sync in Settings → Integrations:

1. Click Select folders to choose which Drive folders to watch
2. Click Sync Now to pull all supported files from those folders
3. On subsequent syncs, only new or modified files are downloaded

Disconnecting

Click Disconnect on the integrations page. Previously synced documents remain in your workspace.

API Keys

API keys are for CI pipelines, cron jobs, and headless environments where a browser login isn't possible.

Creating a Key

1. Go to Settings → API Keys (or navigate to /settings/keys)
2. Enter a descriptive name (e.g. "CI Pipeline", "Research Bot")
3. Click Create key
4. Copy the key immediately. It's shown only once. The key looks like gthos_sk_a1b2c3d4...
5. Click Done once you've saved it somewhere safe

Using a Key

With the CLI:

gthos auth login --key gthos_sk_...

Or directly via HTTP:

curl -H "Authorization: Bearer gthos_sk_..." https://your-app.com/api/canonical?workspaceId=...

Revoking a Key

On the API Keys settings page, click Revoke next to any active key. Revocation is immediate and permanent. Create a new key if needed.

Product Analytics

GroundTruth OS uses PostHog for product analytics. This helps the team understand how users interact with the platform, identify friction points, and prioritize features.

What's Tracked

• Page views: every page navigation
• Clicks: automatic capture of all user interactions (buttons, links, form inputs)
• Core workflow events: document uploads, AI extractions, interview sessions, knowledge base edits/commits, agent prompt compilations, Google Drive imports
• Web vitals: Core Web Vitals performance metrics (LCP, FID, CLS)

Privacy

• Only identified users are tracked (no anonymous visitor profiles)
• Session replay and heatmaps are available but controlled from the PostHog dashboard
• PostHog requests are proxied through the app's own domain (/ingest) for reliability