Thinklio Documentation¶

Welcome to the Thinklio product documentation. This is the single source of truth for all product, architecture, and platform design.

This page is generated by scripts/build-doc-index.py from the frontmatter of each canonical document. Do not edit it by hand — re-run the build script after any doc change.

Canonical document set¶

The documentation is organised into 16 numbered documents, each covering a distinct domain. Read them in order for a complete picture, or jump to the area you need.

Authority map¶

Each doc is authoritative for the domain named in its title. When two docs touch the same concept, the owning doc wins and the other should cross-reference.

Strategy¶

• 01 Product & Strategy — What Thinklio is, who it serves, the functional specification, pricing model and plan enforcement, and the feature backlog.

Architecture¶

• 02 System Architecture — The service topology, platform stack, execution model, and deployment topology for Thinklio. Covers the Convex-first reactive backend, Clerk identity, messaging-first core, durable workflows, execution tiers and workflow budget, observability, and the archival Go service design.
• 03 Agent Architecture & Extensibility — The agent model, execution contract, composition and delegation, job system, smart input triage, attention surfacing, extensibility layers, MCP integration, Convex component integration, and agent views.
• 04 Data Model — The Convex-native data model for Thinklio: every entity expressed as a Convex defineTable with validators and indexes, the relationships between them, scope and visibility rules, agent tool integration, and data lifecycle.
• 05 Persistence, Storage & Ingestion — How Thinklio persists data in Convex, stores files in Cloudflare R2, and ingests documents through the media and library pipeline. Covers index design, reactive queries, vector search, file lifecycle, document intelligence, retrieval, backup, and operational concerns.
• 06 Events, Channels & Messaging — How Thinklio models events, runs durable agent execution, and handles inbound and outbound messages across channels. Covers the event table and reactive event distribution, the Convex Workflow component as the harness, channel identity and lifecycle, multi-channel delivery, the Postmark email channel, and messaging UX conventions.
• 07 Security & Governance — Thinklio's security model, governance policy framework, credential management, secrets vault, and MCP tool permission architecture.
• 15 Tenancy & Deployment Topology — How Thinklio implements multi-tenancy today (a single pooled Convex deployment with application-layer isolation), why that is the right choice at current scale, and the planned paths for graduating a tenant to a dedicated Convex deployment or a customer-owned Convex account — including new-tenant provisioning and the pooled-to-dedicated migration procedure.
• 16 Chats, Channels & Identity — The canonical model for how Thinklio chats relate to the channels (transports) that reach them, and how identities and credentials attach to principals. Establishes World B terminology (channel = transport, chat = container), chat-as-canonical with three channel binding modes (mirror, relay, injection), the verified deep-link identity-binding flow, the principal model in which identity and credentials are polymorphic over user/account/agent, the universal semantic-message and compose-once/render-by-binding-mode delivery model with its channel adapter contract, and the native-only Mirror posture for v1.

Capabilities¶

• 08 Agents Catalogue & Platform Services — The 23 starter agent templates, implementation logistics, the predictive planning system, and platform services for LLM configuration, credentials, credits, and administration.

Interfaces¶

• 09 External API & Tool Integration — The three API surfaces (Channel, Platform, Integration), the endpoint reference, the tool developer guide, and the built-in MCP server reference.
• 10 Client Applications & UX — End-user guide, Thinklio app UI specification, documentation and developer portal UI, and internationalisation architecture.

Developer¶

• 11 Convex Reference — Platform capabilities, conventions, and component directory for the Thinklio Convex backend.
• 12 Developer Guide — The working reference for developers building, running, testing, deploying, and operating Thinklio. Covers repository layout, Convex + Clerk setup, programming conventions, custom agent development, testing and observability, and deployment lifecycle.

Meta¶

• 13 Implementation Plan & Status — The phased implementation roadmap, the March 2026 implementation summary, and the monorepo migration.
• 14 Thinklio Reference — Synthesised single-source reference covering the full product, architecture, data model, security, pricing, and roadmap. Regenerated from the canonical set.

Dependency graph¶

Edges are declared in each doc's depends_on frontmatter. A → B means A builds on concepts defined in B.

graph LR
  D1["01 Product & Strategy"]
  D2["02 System Architecture"]
  D3["03 Agent Architecture & Extensibility"]
  D4["04 Data Model"]
  D5["05 Persistence, Storage & Ingestion"]
  D6["06 Events, Channels & Messaging"]
  D7["07 Security & Governance"]
  D8["08 Agents Catalogue & Platform Services"]
  D9["09 External API & Tool Integration"]
  D10["10 Client Applications & UX"]
  D11["11 Convex Reference"]
  D12["12 Developer Guide"]
  D13["13 Implementation Plan & Status"]
  D14["14 Thinklio Reference"]
  D15["15 Tenancy & Deployment Topology"]
  D16["16 Chats, Channels & Identity"]
  D2 --> D1
  D2 --> D4
  D2 --> D11
  D3 --> D1
  D3 --> D2
  D3 --> D4
  D3 --> D7
  D3 --> D11
  D4 --> D1
  D5 --> D2
  D5 --> D4
  D5 --> D11
  D6 --> D2
  D6 --> D4
  D6 --> D5
  D6 --> D7
  D7 --> D2
  D7 --> D4
  D7 --> D11
  D8 --> D2
  D8 --> D3
  D8 --> D4
  D8 --> D5
  D8 --> D7
  D9 --> D2
  D9 --> D3
  D9 --> D4
  D9 --> D5
  D9 --> D7
  D9 --> D8
  D10 --> D1
  D10 --> D2
  D10 --> D4
  D10 --> D7
  D10 --> D9
  D12 --> D2
  D12 --> D3
  D12 --> D4
  D12 --> D7
  D12 --> D9
  D12 --> D10
  D12 --> D11
  D13 --> D1
  D13 --> D2
  D13 --> D3
  D13 --> D4
  D13 --> D5
  D13 --> D6
  D13 --> D7
  D13 --> D8
  D13 --> D9
  D14 --> D1
  D14 --> D2
  D14 --> D3
  D14 --> D4
  D14 --> D5
  D14 --> D6
  D14 --> D7
  D14 --> D8
  D14 --> D9
  D14 --> D10
  D14 --> D11
  D14 --> D12
  D14 --> D13
  D15 --> D2
  D15 --> D4
  D15 --> D7
  D16 --> D4
  D16 --> D6
  D16 --> D7

Suggested reading order¶

This order respects the dependency graph so later docs never depend on earlier ones you have not yet read.

1. 01 Product & Strategy
2. 11 Convex Reference
3. 04 Data Model
4. 02 System Architecture
5. 05 Persistence, Storage & Ingestion
6. 07 Security & Governance
7. 03 Agent Architecture & Extensibility
8. 06 Events, Channels & Messaging
9. 15 Tenancy & Deployment Topology
10. 08 Agents Catalogue & Platform Services
11. 16 Chats, Channels & Identity
12. 09 External API & Tool Integration
13. 10 Client Applications & UX
14. 13 Implementation Plan & Status
15. 12 Developer Guide
16. 14 Thinklio Reference

Living documents¶

These documents are updated continuously and are not versioned with the numbered set:

• Decision Log — ADR-style records of significant architectural and product decisions
• Changelog — Reverse-chronological record of documentation changes

Agent specifications¶

Individual agent specifications live under agent-specs/. Start with the index doc for the governance model and catalogue.

Archive¶

The archive/ directory preserves the pre-consolidation documentation set. See archive/README.md for the old-to-new mapping and recovery instructions.

Running the docs locally¶

# From repo root
pip install -r docs/requirements.txt
mkdocs serve
# Browse http://127.0.0.1:8000/

To regenerate this page after doc changes:

python scripts/build-doc-index.py