P3AK Documentation

P3AK is the AI data foundation every organization needs. Not an AI wrapper — the data layer underneath every AI wrapper. Three products, one platform. Get your data right once and every AI tool you use gets smarter. Forever.

Quick Start

From zero to a searchable encrypted knowledge base in under 5 minutes.

1 — Install

# Install the CLI via Cargo
$ cargo install p3ak-vault

# Verify
$ p3ak-vault --version
p3ak-vault 0.1.0

2 — Create a vault

$ p3ak-vault create --path company.vault --passphrase $VAULT_KEY
{"ok":true,"encrypted":true,"path":"company.vault"}

3 — Ingest documents

# Single file (39 formats supported)
$ p3ak-vault ingest --path company.vault --file term-sheet.pdf --room legal

# Entire directory
$ p3ak-vault ingest --path company.vault --dir ./documents --room legal
{"added":14,"skipped":0,"formats":["pdf","docx","md","mdr"]}

4 — Search

$ p3ak-vault search --path company.vault --query "renewal terms" --mode hybrid
[{
  "score": 1.41,
  "filename": "services-agreement.mdr",
  "room": "legal",
  "snippet": "The initial term is 12 months, auto-renewing..."
}]

How It Fits Together

P3AK is three independent products connected by the .mdr format and the vault API.

P3AK harness  (orchestration — CREST protocol, Pi/Claude)
      ↓ vault_search / vault_write via Pi extension
      ↓ room REST API (gaps, documents, analysis)
────────────────────────────────────────────────
P3AK room     (application — Next.js 14, 5 tributaries)
      ↓ POST /api/companies/[slug]/vault-push
      ↓ GET  /api/companies/[slug]/export?format=mdr
────────────────────────────────────────────────
P3AK vault    (infrastructure — Rust, single .vault file)
      p3ak-vault ingest --file doc.mdr --room legal
      p3ak-vault search --query "..." --mode hybrid
      p3ak-vault serve  --port 8080
────────────────────────────────────────────────
.mdr format   (bridge — room creates, vault ingests, harness reads)

vault — Overview

A single encrypted binary file that stores, indexes, and retrieves your entire knowledge base. No database. No cloud. No SaaS. Yours.

Installation

From crates.io (recommended)

$ cargo install p3ak-vault

From source

$ git clone https://github.com/siliconbayou/p3ak-vault
$ cd p3ak-vault
$ cargo build --release
$ cp target/release/p3ak-vault /usr/local/bin/

Environment variables

CLI Commands

create

p3ak-vault create --path <PATH> [--passphrase <P>]

Creates a new empty vault. With --passphrase, the vault is AES-256-GCM encrypted. Without, it is stored unencrypted with a warning.

ingest

# Single file
p3ak-vault ingest --path <VAULT> --file <FILE> [--room <R>] [--upsert]

# Directory (recursive)
p3ak-vault ingest --path <VAULT> --dir <DIR> [--room <R>]

Ingests a file or directory. Content is normalized to markdown, SHA-256 deduped, indexed, and appended to the vault. Supports 39 file formats. Returns {"action":"added"|"skipped"|"updated"}.

search

p3ak-vault search --path <VAULT> --query <Q>
  [--limit <N>] [--mode flat|pageindex|hybrid] [--room <R>]

Searches the vault using the specified mode. Returns a JSON array sorted by relevance score. Use --room to scope the search to a specific tributary.

serve

p3ak-vault serve --path <VAULT> [--port 8080] [--bind 127.0.0.1]

Starts a synchronous HTTP server exposing the vault over REST. Binds to 127.0.0.1 by default. See REST API for available endpoints.

watch

p3ak-vault watch --path <VAULT> --dir <DIR> [--room <R>]

Watches a directory for file changes and automatically ingests new or modified files. Ctrl-C to stop.

read

p3ak-vault read --path <VAULT> --type goals|docs|wal

Reads structured sections of the vault. docs lists all ingested documents. wal shows the hash-linked write-ahead log. goals returns stored goal entries.

write

p3ak-vault write --path <VAULT> --type goal|doc|plan|review --payload '{"title":"..."}'
# Or pipe JSON from stdin
echo '{"title":"Q1 goals"}' | p3ak-vault write --path vault --type goal --payload -

canary-check

p3ak-vault canary-check --path <VAULT> [--threshold 0.8]

Runs the embedded canary query set and measures retrieval accuracy. Exit code 0 = passing, 2 = recall below threshold, 1 = fatal error.

sync

p3ak-vault sync --path <VAULT>

Flushes the WAL, rebuilds the index, and compacts the vault file. Run after bulk ingests.

export

p3ak-vault export --path <VAULT> [--format json|md] [--out <FILE>]

accuracy-test

p3ak-vault accuracy-test --path <VAULT> --ground-truth ground-truth.json [--mode hybrid]

Runs a structured accuracy benchmark against a ground-truth JSON file. See testdata/fixtures/ground-truth.json for format.

Search Modes

P3AK vault supports three search modes. Hybrid is recommended for production.

File Formats (39)

P3AK vault normalizes all formats to markdown before indexing. Tier 1 & 2 work with zero extra deps. Tier 3 needs an OS tool. Tier 4 uses the markitdown bridge — pip install 'p3ak-vault[markitdown]'.

markitdown Bridge TIER 4

Three formats — Excel workbooks, and ZIP archives — are handled by Microsoft's markitdown library via a lightweight Python bridge. PPTX uses markitdown as its primary converter with pandoc as fallback.

Why a separate dep instead of built-in? Excel and ZIP require parsing libraries that add significant binary weight to the Rust core. markitdown is maintained by Microsoft's AutoGen team (87K+ stars), updated frequently, and handles edge cases we'd never cover ourselves. The right call is to depend on it, not duplicate it.

# Add markitdown support to p3ak-vault Python SDK
pip install 'p3ak-vault[markitdown]'

# Or install markitdown directly (same result)
pip install 'markitdown[all]'

# Keep updated — Microsoft's releases, not ours
pip install --upgrade 'markitdown[all]'

# Rust CLI detects .xlsx / .pptx / .zip extension
# Calls: python -m p3ak_vault.convert <file>
# Bridge outputs JSON to stdout:
{
  "markdown":      "| Quarter | MRR | ARR |\n|---|---|---|\n...",
  "title":         "financials-q4",
  "source_format": "xlsx_markitdown",
  "extra_meta":    { "converter": "markitdown", "word_count": 420 }
}
# Rust parses JSON → Converted struct → normal ingest pipeline

Exit codes

Python override

Set P3AK_PYTHON=/path/to/python3 to use a specific interpreter (venv, conda, pyenv). The bridge searches $P3AK_PYTHON → python3 → python in that order.

from p3ak_vault import convert_file, markitdown_available

if markitdown_available():
    result = convert_file("financials-q4.xlsx")
    # result["markdown"] → table markdown ready for vault ingest
    # result["source_format"] → "xlsx_markitdown"
    # result["extra_meta"]["word_count"] → 420
else:
    print("Install: pip install 'p3ak-vault[markitdown]'")

REST API

Start the API server with p3ak-vault serve --path vault.vault --port 8080. All endpoints return JSON.

Python SDK

Installation

$ pip install p3ak-vault   # subprocess wrapper (zero deps)

Usage

from p3ak_vault import VaultClient

client = VaultClient("company.vault", passphrase="your-key")

# Ingest
client.ingest("term-sheet.pdf", room="legal")

# Search
results = client.search("renewal terms", mode="hybrid", limit=5)
for r in results:
    print(r["filename"], r["score"], r["snippet"])

Configuration

P3AK vault reads configuration from ~/.p3ak/config.toml.

# Default vault path
default_vault = "~/vaults/main.vault"

# Default search mode
search_mode = "hybrid"

# LLM classification (optional)
anthropic_model = "claude-3-haiku-20240307"

Classification Engine

Every document ingested into P3AK vault is automatically assigned to a three-level taxonomy: Store → Category → Subcategory. Classification runs at ingest time (rules-based, instant) and optionally at query time (LLM-enhanced, async). No manual filing required.

Each classification result includes:

• store / storeName — top-level taxonomy domain
• category / categoryLabel — mid-level grouping
• subcategory — specific document type
• confidence — 0.0–1.0 float; rules-based typically 0.91–0.98
• signals[] — human-readable list of what triggered classification
• canonicalName — normalized vault path: store/category/filename_org_date.ext
• breadcrumb[] — display array: ["Legal","Contracts & Agreements","PSA"]

{
  "store":         "LG",
  "storeName":     "Legal",
  "category":      "contracts",
  "categoryLabel": "Contracts & Agreements",
  "subcategory":   "Professional Services Agreement",
  "confidence":    0.96,
  "signals": [
    "parties clause detected",
    "effective date present",
    "governing law clause",
    "signature block"
  ],
  "canonicalName": "legal/contracts/psa_acme-corp_2025-11-01.md",
  "breadcrumb": ["Legal", "Contracts & Agreements", "PSA"]
}

The classifier evaluates documents in priority order: board governance → security policy → hiring → architecture → investor materials → financial statements → legal contracts → company profile → fallback. Order prevents false positives when documents contain cross-domain vocabulary (e.g., a board resolution that discusses a contract renewal).

Entity Intelligence Phase 7

The entity vault profile treats a company as a living organism — with formation records, a compliance nervous system, and a completeness score that tells you exactly what's missing.

# 1. Create entity vault
p3ak-vault create --path company.vault --profile entity

# 2. Initialize company metadata
p3ak-vault entity --path company.vault init \
  --name "Silicon Bayou LLC" --entity-type LLC \
  --state Louisiana --stage pre-seed

# 3. Ingest founding documents
p3ak-vault ingest --path company.vault --file articles-of-organization.pdf

# 4. Check completeness (what required docs are present vs. missing)
p3ak-vault entity --path company.vault completeness
{"overall_pct":100,"total_found":7,"total_required":7,"legal":{"score_pct":100},...}

# 5. View applicable obligations
p3ak-vault entity --path company.vault obligations
{"obligation_count":9,"obligations":[{"name":"Louisiana LLC Annual Report",...}]}

Obligation Catalog

The static obligation catalog covers 21 obligations across three jurisdictions: Federal (Form 1065/1120/940/941/1099-NEC/I-9/W-4/W-2), Louisiana (LLC Annual Report, Corp Annual Report, state income tax, sales tax), and Delaware (C-Corp Annual Report + franchise tax, LLC $300 annual tax, registered agent). Additional states are additive.

Completeness Scoring

The completeness engine scans all ingested vault documents against 13 document requirements (Legal: articles, operating agreement, registered agent, IP assignment, NDA, cap table, board minutes, DPA — Finance: EIN, financials, bank account — Operations: employee handbook, offer letter). Each requirement has a set of search keywords; a document counts as "found" if any keyword matches in any vault document. Scores update automatically as documents are ingested.

CREST Skills (P3AK harness)

Two Pi skills automate the weekly compliance loop. Agents propose. Humans verify. No autonomous filing, payment, or legal action ever.

• /skill:crest-entity-review — weekly sweep: obligations due, document gaps, proposed action checklist, review written to org-brain vault
• /skill:crest-deadline-alert — 30/7/1-day deadline radar: resolves concrete calendar dates, tiers by urgency (🚨/🔴/🟡/🟢), ICS-compatible calendar event output

→ Full Entity Intelligence case study — Silicon Bayou LLC, the first live customer

Document Viewer

The P3AK vault document viewer renders every format as a clean, readable web page — no raw code, no pipe-separated text, no visible markup.

The viewer panel has five layers:

1. Header — format badge (color-coded by type), original filename, canonical vault path
2. Metadata strip — source format, file size, extracted author, classification confidence, taxonomy breadcrumb
3. Search Context card — AI reasoning narrative (see Search Intelligence)
4. Document body — format-aware rendered content with query terms highlighted in gold
5. Bookmark bar — persistent status flags and category tags (see Bookmarks & Flags)

Author Extraction

The viewer automatically extracts document authorship from:

• **Author:** Name or Author: Name headers
• Prepared by: Name and Approved by Name patterns
• Signature table rows: | Name | CEO | Date |
• Named individuals in content (configurable list)

Search Intelligence

When a document is opened from a search result, P3AK generates a context card that explains exactly why the document was retrieved and how it relates to the query.

You searched for "renewal terms auto-renew 30 days." This
Professional Services Agreement between Acme Corp and Silicon
Bayou LLC dated November 1, 2025 is classified under Legal ›
Contracts & Agreements › PSA. It ranked as the top result
(94% relevance) through exact keyword match — a key figure
in this document is $12,500. Look for "renewal" in the
highlighted passages below.

The context card is generated client-side from:

• The search query verbatim
• The document's classification data (type, parties, date)
• The search scores (BM25, ZVec, PageIndex, combined)
• The first money amount found in the document (if any)
• Which scoring dimension drove the match (keyword vs semantic vs structural)

All query terms are highlighted gold in both the matched excerpt and throughout the full rendered document body. The highlight engine skips HTML tags using a lookahead regex to prevent breaking markup.

Bookmarks & Flags

Every document in the viewer can be flagged with a status and optional category tag. Flags are stored in localStorage under the key p3ak-bookmarks-v1 and persist across sessions without any server-side storage.

Each bookmark record stores: { filename, status, category, query, updatedAt }. The query field captures what was being searched when the flag was set, creating a breadcrumb of intent. The category input field accepts any free-text tag (e.g. "Due Diligence", "Board Review", "Q1 Legal").

Toggling an active status removes the flag entirely. The bookmark bar is always visible at the bottom of the viewer panel regardless of scroll position.

room — Overview

AI-native knowledge organization for any business. Five tributaries structure your company's intelligence, version-control every document, track what's missing, and export everything as portable .mdr files for vault ingestion. Built for companies that need their data organized — whether for investors, acquirers, partners, or themselves.

5 Tributaries

Every organization's knowledge is organized into five tributaries — the five areas that matter most, whether you're running day-to-day operations, preparing for investment, or just need everything in one place.

API Reference

All routes are under /api/companies/[slug]/.

.mdr Export

Export any document as a .mdr file — the P3AK portable document format.

# Export single file as .mdr
GET /api/companies/acme/export?format=mdr&file=01-Legal/operating-agreement.md

# Export all files as .mdr ZIP
GET /api/companies/acme/export?format=mdr

Vault Bridge

Push all data room documents directly into a P3AK vault with one API call.

POST /api/companies/acme/vault-push
{
  "vaultPath": "/Users/you/vaults/acme.vault",
  "passphrase": "your-vault-key",
  "room": "legal",   // optional — scopes to one tributary
  "dryRun": false
}

// Response
{
  "pushed": 14,
  "skipped": 2,
  "errors": 0,
  "documents": [{ "file": "operating-agreement.md", "action": "added" }, ...]
}

harness — Overview

The reasoning layer. Your AI co-pilot with permanent memory — using the CREST protocol for systematic reasoning, vault as long-term memory, and room as the document source. Works with any model. The operating system for how your organization thinks, plans, and executes.

CREST Protocol

CREST is a five-phase systematic reasoning cycle for turning intentions into executed strategy.

# Open Pi in p3ak-harness directory, then:
/skill:crest-clarify
# → Pi asks for your intention, creates SMART goal, writes to vault

/skill:crest-risks
# → Pi reads the goal from vault, maps obstacles, writes analysis

/skill:crest-sprints
# → Pi creates quarterly/sprint roadmap based on goal + obstacles

Domain Agents

The CAIO operates across six domains, each with its own vault.

Pi Skills

Skills are registered in .pi/skills/ and auto-discovered by Pi. Each skill is a directory with a SKILL.md file.

crest-clarify/SKILL.md
crest-risks/SKILL.md
crest-establish/SKILL.md
crest-sprints/SKILL.md
crest-tune/SKILL.md

Session Start Protocol

Every Pi session opened in p3ak-harness runs this four-step protocol automatically.

.mdr Format

The P3AK Document format. A portable, human-readable file containing your document's content, version history, and access-tier layers. Created by room, ingested by vault, queried by harness. Readable in any text editor.

Structure

+++mdr
format_version: 1
doc_id: "acme-series-a-term-sheet"
title: "Series A Term Sheet"
created: "2025-11-01T00:00:00Z"
created_by: "p3ak-room"
current_layer: internal
current_version: 3
tributaries: ["legal"]
tags: ["term-sheet", "series-a", "legal"]
layers:
  - id: public
  - id: internal
    restricted: true
  - id: legal
    privileged: true
+++

@@@ layer:internal version:3 author:alice ts:2025-11-01T00:00:00Z @@@

# Series A Term Sheet

Pre-money valuation: $8M. Investment: $2M.
Auto-conversion at Series B...

@@@ layer:internal version:2 author:alice ts:2025-10-15T00:00:00Z @@@

# Series A Term Sheet (Draft 2)

...

Header Fields

Security

Vault Encryption

Audit Log (WAL)

Every read and write is recorded in a hash-linked Write-Ahead Log. Each entry contains a SHA-256 hash of the previous entry, making the log tamper-evident. Use p3ak-vault read --type wal to inspect.

Privacy Model

• No telemetry. No phone-home. Zero network requests from the vault binary.
• REST API binds to 127.0.0.1 by default — never exposed externally without explicit config.
• The .vault file is a single portable binary you own entirely — move it, back it up, delete it. No SaaS, no cloud, no lock-in.
• Per-room isolation: documents tagged with --room are searchable independently. Cross-room queries require explicit --room removal.