Ten31 Venture CRM + Agentic System — AGENTS.md

The foundation is a self-hosted venture-fund CRM — a purpose-built fundraising tool that replaced Airtable to (1) keep sensitive LP/prospect data off third-party servers, (2) drop subscription cost, and (3) fit the fund's workflow: managing ~150 existing LPs, tracking 250+ prospects, and running the capital-raise pipeline. Core CRM domain: contacts (investor/prospect/advisor), organizations, opportunities (the deal pipeline), and communications; investor commitments live in the canonical fundraising_* grid (the legacy single-fund lp_profiles table was retired in v0.1.0:78). The fund (Ten31, ~$200M AUM, bitcoin/energy/AI thesis) runs it on a Start9 box, accessed over ClearNet (StartOS StartTunnel) with app-level user auth by a team of ~5 (Tailscale is not in use). Schema/API tour: docs/crm-overview.md.

The agentic system is new functionality built on top of that CRM — an in-house AI layer to widen the fundraising funnel, sharpen the thesis, and automate outreach drafting. Frontier reasoning runs on Claude (Agent SDK/API); privacy-sensitive and bulk work runs on local DGX Spark models via the Spark Control gateway. Phase 0/1 — no live outward-facing agents; agents draft, humans send.

Inbox check: At session start, if ~/Projects/standards/INBOX.md exists, scan it for items tagged (CRM) and surface them before proposing next steps; triage with /triage.

Stack (versions that matter)

Python 3.11, standard library only at runtime. The CRM is one monolith, backend/server.py (~5k lines): a stdlib http.server.ThreadingHTTPServer + hand-written CRMHandler with manual path dispatch (do_GET/do_POST). Not FastAPI. backend/requirements.txt lists FastAPI/SQLAlchemy/Alembic/Pydantic/pytest-style deps but none are imported at runtime (vestigial).
SQLite at data/crm.db (WAL, foreign_keys=ON), opened per-request via get_db(). Schema via ordered migrations.
Frontend: single frontend/index.html, inline-Babel React. No build step.
Optional runtime deps, used only if present: bcrypt, PyJWT (jwt), cryptography (Gmail module).
MCP + ingest (in the Docker image, not the bare CRM): mcp==1.2.0 (FastMCP, backend/mcp/server.py), fastembed==0.4.2, anthropic, cryptography==42.0.5.
Packaging: StartOS 0.4, TypeScript SDK (@start9labs/start-sdk) under start9/0.4/startos/. Live target is start9/0.4/.
Local models (bge-m3 embeddings, bge-reranker-v2-m3, /api/search, Qdrant): always via Spark Control. Contract: docs/EMBEDDINGS.md.

Commands

# Run locally (dev, port 8080; or ./start.sh <port>) — runs python3 backend/server.py
./start.sh
# Run prod-mode (beta) — requires CRM_SECRET_KEY
./start_beta.sh
# Sanity-check edits (there is no compiler/build for the CRM)
python3 -m py_compile backend/server.py
# Run ONE test (tests are standalone scripts with `if __name__ == "__main__"`; no pytest installed)
python3 backend/redaction/test_scrub_leak.py        # substitute any backend/**/test_*.py
# Run all tests (aggregate runner — runs each backend/**/test_*.py in its own subprocess)
python3 backend/run_tests.py                         # add substrings to filter, e.g. `... soft_delete redaction`
# Build + install the s9pk — BUMP THE VERSION FIRST. See docs/guides/packaging.md.
cd start9/0.4 && make

Migrations apply automatically at startup (backend/core_migrations.py, schema_migrations ledger). See docs/guides/migrations.md before adding one.
Lint: none configured.

Directory layout (day-one)

backend/server.py — the CRM monolith: HTTP handler, route dispatch, init_db(), auth (username/password → HS256 JWT, roles admin/member/bot).
backend/core_migrations.py + backend/migrations/NNNN_*.sql (+ paired .down.sql) — additive schema migrations, applied at startup.
backend/thesis_seed.py — Thesis Workshop seed + idempotent ensure_* one-time seeders, wired in server.init_db().
backend/thesis_review.py — thesis version review/approval (human dual sign-off → canonical).
backend/mcp/ — architect_agent.py (Claude thesis copilot), architect_tools.py, outreach_agent.py (LP draft assistant), architect_grounding.py, crm_tools.py, server.py (FastMCP).
backend/email_integration/ — Gmail capture via domain-wide delegation + Tier-B draft creation (compose.py).
backend/redaction/ — scrub.py + client.py: the scrub→Claude→re-hydrate privacy boundary.
backend/ingest/ — chunk→embed→Qdrant + retrieval modes.
backend/entity_*.py — entity resolution/merge (the two-investor-model reconciliation).
backend/nl_query/ — read-only natural-language query (W2): intents.py (curated parameterized query catalog), runner.py (slot validator = trust boundary), translate.py (local-Qwen question→{intent,slots}). See the nl-query guide.
backend/matrix_intake/ — Matrix intake bot (separate process; matrix-nio, isolated to this component): typed message → local-Qwen parse → in-thread approve → write via the CRM's own log-communication. See the matrix-intake guide.
frontend/index.html — the entire UI.
docs/ — architecture, phase plans, contracts, runbooks (see Deeper docs). docs/guides/ — scoped subsystem rules (see below).
start9/0.4/ — StartOS package (startos/utils.ts holds PACKAGE_VERSION).
data/crm.db — the live DB (gitignored). .env / .env.example — config (.env gitignored).

Scoped guides

Subsystem rules live in docs/guides/ and lazy-load in Claude Code via .claude/rules/ symlinks (scoped by paths: frontmatter). Read the guide before editing that area:

Migrations or seeders (backend/migrations/, core_migrations.py, thesis_seed.py) → docs/guides/migrations.md
Thesis logic (backend/thesis_*.py, backend/mcp/architect_*.py) → docs/guides/thesis.md
Redaction or any MCP/Claude path (backend/redaction/, backend/mcp/) → docs/guides/redaction.md
Ingest / retrieval (backend/ingest/) → docs/guides/spark-ingest.md
Email capture / drafts + digest send (backend/email_integration/, backend/digest_mailer.py, backend/smtp_send.py) → docs/guides/email.md
Building or deploying the s9pk (start9/) → docs/guides/packaging.md
Matrix intake bot (backend/matrix_intake/) → docs/guides/matrix-intake.md
Natural-language query (backend/nl_query/) → docs/guides/nl-query.md

Conventions

Investor model — the grid is canonical (since v0.1.0:78). The fundraising_* grid is the system of record: an investor entity (row) → many contact "pills" → per-fund commitments. The classic contacts table is a read-only per-person directory, auto-populated from the grid — create/edit people in the grid, not the Contacts page. Email capture rolls multiple people up to one investor. The legacy single-fund lp_profiles model is retired (empty table kept, per never-hard-delete). Reconciling grid ↔ classic contacts to canonical IDs is the core entity-resolution task — see docs/crm-overview.md. Derived read-only columns (pipeline, pipeline_stage, opportunity_id, reminder_status, existing_investor, last_activity_at, staleness) are computed live and injected on GET, never persisted — any new one MUST be added to BOTH strip points (server.py _computed_row_values + frontend stripComputedRows) or it dirties the autosave / leaks into the blob. Pipeline stage is the 4-stage funnel lead→engaged→diligence→commitment (PIPELINE_STAGES), terminal at commitment.
Soft-delete only: deleted_at and/or status='retired'; never hard-delete. Every READ path must filter deleted_at IS NULL — list handlers, get-by-id, nested related-data sub-selects, and aggregate sub-selects (COUNT/SUM/MAX). Audits found leaks in all of these (2026-06-12 detail + nested; 2026-06-13 list-view contact_count/total_funded/comm_count); the opportunities/pipeline aggregates were fixed in v0.1.0:87 (handle_pipeline_report + dashboard pipeline metrics now filter deleted_at), but the reports subsystem's communications-side aggregates (dashboard recent_comms/comms_this_month/meetings_this_month, activity report) still leak (see Current state). Regression-guarded by backend/test_soft_delete_reads.py (+ test_reminders.py for the reminders read paths, incl. the recency rollup whose email-activity liveness signal is email_account_messages.deleted_at, not emails). (Thesis has a subtlety here — see the thesis guide.)
Env: secrets in .env (gitignored); names in .env.example. Verified names: ANTHROPIC_API_KEY, SPARK_CONTROL_URL, SPARK_CONTROL_VERIFY_TLS, QDRANT_URL, X_API_KEY, CRM_DB_PATH, CRM_DEV_DB_PATH. Also used: CRM_SECRET_KEY (beta/prod), CRM_HOST/CRM_PORT, CRM_DATA_DIR; digest mailer: CRM_DIGEST_SENDER (DWD impersonation sender) + SMTP_HOST/SMTP_PORT/SMTP_SECURITY/SMTP_FROM/SMTP_USERNAME/SMTP_PASSWORD (SMTP fallback); daily digest (Phase B): CRM_DIGEST_ENABLED + CRM_DIGEST_SEND_HOUR only seed the first-boot default — the live control is the DB policy (app_settings.digest_policy, set in Settings → Admin).
Config placement: operational/feature toggles live in the admin panel, DB-backed via app_settings (read-merge through a load_*_policy(conn) helper shared by the API + any scheduler; precedence DB-row → env-seed → default), so they're discoverable and take effect live. Reserve StartOS actions / env for secrets and deploy-time config (SMTP creds, API keys, DWD sender). Precedent: digest_policy (GET/PATCH /api/admin/digest/policy), fundraising_backup_policy.
Agent/bot API access — three roles now (admin/member/bot). require_admin is the only hard gate; everything else is "authenticated" (member, admin, and bot all pass). The bot role (added v0.1.0:89) is authenticated-but-never-admin: require_bot_or_admin gates agent-facing endpoints (e.g. /api/intake/email-proposals*) so a bot credential reaches only what it needs, never user-management/settings/security. Provision it via Settings → Admin edit-user dropdown (kept out of the teammate-invite form). Two axes to keep separate as more agent capability lands: the role controls reach (which endpoints); the per-feature human draft→approve gate controls autonomy (acting unattended). Money/merge/delete mutations stay behind the approval gate regardless of role. Don't build a finer capability/scope system until real NL-mutation endpoints exist to scope against.
Design: before building or changing any user-facing UI, read design/DESIGN.md and design/tokens.tokens.json and conform to them. The mobile-first redesign landed (Claude Design round-trip distilled into the contract 2026-06-19): the authority for mobile/responsive work is DESIGN.md §8 + the tokens mobile and color.light groups; design/BRIEF.md is the input brief and design/_imports/2026-06-19/ the provenance + per-surface interaction reference (the comps are Claude Design runtime prototypes — re-author each surface in the app's React idiom + real API, not drop-in). A light theme is built (P6): it lives in :root[data-theme="light"] (set by a pre-paint boot script from localStorage.venture_crm_theme; dark is the default), with an app-wide toggle in the desktop sidebar footer + the mobile top bar. Colors are theme vars now — any new UI color MUST use a :root var (grow the set if needed), never a literal, or it won't flip in light (chips/badges flip via .stage-chip--{stage} + the --chip-*/--note-*/--badge-priority-*/--rem-*/--money/--recency-*/--due-soon slots; authoritative dark+light pairs are in the Claude Design export design/_imports/2026-06-19_zip-file/ store.js + *App.dc.html). Mobile light is complete; desktop has known unthemed shades (Phase 7). (Note: inline style={{}} objects can't respond to media queries; responsive layout belongs in the CSS <style> block. The mobile foundation primitives are built — CSS: .bottom-tab-bar, the .bottom-sheet primitive, .mobile-only/.desktop-only, :root mobile vars; React (Phase 2): <BottomSheet> (scrim/Escape/drag-to-dismiss) + useIsMobile() (768px) + the MobileDetailRow/.fs-detail full-screen-detail + .contact-card/.az-header list patterns — build new mobile surfaces on these (P3 Grid reuses them directly; swap surfaces via a rules-of-hooks-safe useIsMobile() wrapper that mounts a Mobile*/Desktop* pair, never a per-component hook toggle). The inline-style→CSS migration is scoped, per-surface (~114 styles across 4 surfaces+shell, not ~1,300), folded into each surface's build; see ROADMAP.md.)
Commit style: imperative subject, concise body explaining the why; put the package version in the subject (… (v0.1.0:NN)) for shippable changes. No AI co-author / attribution trailers — commits are authored by the user.

Always

Verify before shipping: python3 -m py_compile the edited files; for DB logic, run the change against a copy of data/crm.db, never production.
Keep real LP data out of Claude: develop only on code/schema/synthetic-or-locally-redacted data; route any real record substance through backend/redaction first.
Get explicit user authorization before any production deploy/install to $START9_BOX_HOST.

Never

Never treat Qdrant (or any derived index) as source of truth — the CRM/SQLite is canonical and rebuildable-from.
Never hard-delete CRM records or thesis history — soft-delete/archive only.
Never let an agent send email, post, or contact an LP autonomously — agents draft; a human approves and sends.
Never set a thesis_version canonical from code/seeds — that is human dual sign-off.
Never call a Spark directly — go through Spark Control (SPARK_CONTROL_URL).
Never commit secrets, data/crm.db, .env, or data/backups/ (all gitignored). Scan staged files before committing. (.claude/ is tracked — launch.json and rules/ symlinks ship with the repo; keep local-only settings in .claude/settings.local.json.)
Never bulk-export the LP list to any third party; send only minimal non-sensitive context to Claude.
Never assume FastAPI / SQLAlchemy / pytest are in play — they sit in requirements.txt unused; runtime is stdlib + SQLite.
Never add a Co-Authored-By / "Generated with" trailer to commits or PRs — commits are the user's.

Deeper docs

Full constitution + guardrails: docs/ten31-constitution.md
Architecture & rationale: docs/Ten31_Agentic_Build_Plan.md
Retrieval/embeddings contract: docs/EMBEDDINGS.md
CRM schema/API tour: docs/crm-overview.md
Current thesis handoff: docs/thesis-handoff.md
Operations & runbooks: docs/OPERATIONS.md, docs/go-live-runbook.md, docs/gmail-enablement-runbook.md

Current state

Box live at v0.1.0:94; main ahead by mobile Phases 0–6 + P3b name/pill edit + drag-reorder views — all deploy-pending (no s9pk built yet). The fundraising grid + email capture is the canonical system of record. Active thread: mobile-first redesign — all 4 surfaces + light theme + P3b (name/pill edit) done; BRIEF §3a editable set complete. Plan (Grant, 2026-06-19): finish features first — P3b done → Phase 7 design-conformance pass next — then Grant does device testing + deploy (NOT before; everything is unverified on a real phone). Per-phase detail + backlog: ROADMAP.md / EVALUATION.md; history: git log + start9/0.4/startos/versions/.

Mobile redesign — all 4 core surfaces built + committed (Grid · Contacts · Pipeline · Reminders). Each is a rules-of-hooks-safe useIsMobile() wrapper → Mobile*/Desktop* pair (desktop untouched), re-authored against the real API on shared primitives <BottomSheet>/useIsMobile()/StageChip/MobileDetailRow. Foundation: bottom-tab bar + :root mobile vars (P1); 4-stage enum + read-only derived grid signals (existing_investor/last_activity_at/staleness/opportunity_id) injected on GET, stripped on write at both points (P0/P3a _computed_row_values + stripComputedRows). Mobile writes use one-row endpoints only — never whole-grid PUT (BRIEF §3a): log-communication, pipeline link/stage, reminders, and now POST /api/fundraising/update-row (P3b name/pill edit). Per-phase detail in ROADMAP.md.
This session — P3b investor name + contact-pill edit (committed 3f93daf, frontend + backend). New version-safe POST /api/fundraising/update-row (handle_update_fundraising_row) — the one-row read-fresh-modify-write twin of handle_log_fundraising_communication: reads the canonical grid blob server-side, mutates ONLY the target row's investor_name/contacts, writes back with a version bump + sync_fundraising_relational. Never a whole-grid payload → can't clobber concurrent edits to other rows (BRIEF §3a). Server-side _sanitize_fundraising_contacts (9-field whitelist; drops name+email-empty pills) is the trust boundary. Frontend: MobileFundraisingGrid detail gains an Edit bottom-sheet (investor-name input + pill add/edit/remove of name·email·title, preserving each pill's location/LinkedIn fields, client-side dedup by email→name) → saves through update-row → reloads; money stays desktop-only. Pill removal is soft on the classic contacts directory (only the grid pill + fundraising_contacts row drop). New CSS is theme-var-only (.pill-edit*/.sheet-addbtn/.fs-detail-edit). Verified: backend/test_fundraising_update_row.py (24 assertions over real HTTP — rename/add/edit/remove, other-row-untouched, relational + classic-contacts sync, soft-remove, name-only-pill kept, 5 guards); full suite 37/37; render-smoke green; throwaway jsdom-375px harness drove the real edit flow (14/14: open→edit→rename→remove→add→save, asserted POST update-row + no whole-grid PUT + preserved fields). Reviewer-passed (nits were deliberate sibling-pattern parity). No real-phone check.
Prior session (e6a8945) — P6 light theme (frontend-only). App-wide light theme behind :root[data-theme="light"] (dark default; pre-paint boot script reads localStorage.venture_crm_theme); toggle in desktop sidebar footer + mobile top bar off one App theme state. 44 themed :root slots (dark == originals byte-for-byte), 319 hex→var() migrated, StageChip className-based. Mobile light complete; desktop-light rough edges (bespoke <style> shades: login glow/scrollbar/table-hover/KPI green, legacy off-palette .badge-*, dark shadows) → Phase 7. Verified render-smoke + jsdom toggle harness (7/7). No real-phone check. Earlier (ee9db64): P4 Pipeline + P5 Reminders (swipe-done/snooze) — detail in ROADMAP.md.
Live (deployed): W2 NL query (v94; remaining: in-room smoke + web "Ask" box); W1 reminders (v93); grid Pipeline (v88); Matrix intake + Gmail capture (DWD) + daily digest; Thesis/Architect (dual-approval); outreach — all draft-only.
Tests: 37/37 backend green (python3 backend/run_tests.py; +test_fundraising_update_row.py), py_compile clean, render-smoke green, fresh-DB migrate clean.
Next (next session = finish features): 1) Phase 7 design-conformance pass against the full Claude Design export (design/_imports/2026-06-19_zip-file/) — buttons/colors/spacing/functionality across all surfaces, incl. finishing the P6 desktop-light rough edges (run design-checker). Then (Grant, after feature-complete): deploy P0–P6 + P3b + view-reorder in one s9pk (authorize + version-bump first) and device-test light/dark on a real phone. Later backlog: W2 web Ask box + smoke; W3 bot grid-mutations; W1b nurture-gap.
Open / risks: all mobile work + P6 light theme + P3b edit built but never deployed or tested on a real phone/browser (render-smoke + jsdom only — verify on a device, both themes); P6 desktop-light has known rough edges (bespoke <style> shades, legacy .badge-* family, dark shadows → Phase 7); W2 happy-path only; Claude/Architect path unverified live on the box; v2.0 reserve-asset spine not canonical (needs dual sign-off); doc drift — crm-overview.md/EVALUATION.md still call lp_profiles live.

20 KiB Raw Blame History Unescape Escape