Skip to content

Thinklio: Changelog

Status: Living Document Format: Reverse chronological. Most recent entries first.

Changed

  • 16-chats-channels-and-identity.md — added a companion note in §8 and a Cross-references entry pointing to the Interaction Protocol (dev/docs/interaction-protocol.md, outside this repo), the product-neutral contract (canonical envelope, input lanes, affordance schema/lifecycle, render→respond→handle, versioning) shared with Twikka and Couple Tools. Doc 16 is Thinklio's instance; the protocol wins on the shared contract.
  • 06-events-channels-and-messaging.md — precis now notes this layer instantiates the Interaction Protocol, pointing to it and to doc 16 §8.
  • Reciprocal links added in the protocol doc back to docs 16, 06, 15 (it lives outside the mkdocs site, so those are real relative links; the Thinklio→protocol references are non-link paths to avoid breaking the build).

2026-06-05 -- Doc set aligned to the channels→chats rename

Changed

  • Root CLAUDE.md — the messaging-first bullet now says "chats with user and agent participants" (with a note that "channel" = transport, pointing to doc 16), and the database-naming example join table is chat_members (was channel_members).
  • apps/web/CLAUDE.md — messaging route description updated to "chat list, /messages/[chatId]".
  • Live numbered docs (02, 03, 05, 06, 07, 10, 11) — schema and code examples aligned to the rename: channelId→chatId, channel_members/channel_member→chat_members/chat_member, by_channel*→by_chat*, requireChannelMember→requireChatMember, v.id("channel(s)")→v.id("chats"), and the container messaging API in doc 10 (api.channels.sendMessage etc.)→api.chats.*. Only unambiguous container identifiers were changed; transport-meaning uses of "channel" were deliberately preserved per World B (ADR-023) — e.g. channel_identity/user_channel, channelType (the transport kind — telegram/email — in channel_config/user_channel and the Telegram ingest flow; note the chat-type field is named type, never channelType), outbound/delivery "channels" (email/push/in-app/Telegram), the settings "Connected Channels" surface, api.channels.connect/listMine (the transport-connect/OTP flow), and api.channels.telegram.ingest.
  • archive/ left frozen; changelog.md/decision-log.md retain old→new names where they document the rename.

Known gap (pre-existing, not from this rename)

  • 04-data-model.md does not define the chat container tables (chats, chat_members, messages) that exist in convex/schema.ts; its section 12 models only the transport tables (channel_config, user_channel). This data-model/code gap predates the rename and is flagged for the next data-model pass.

2026-06-05 -- Doc 16 added: Chats, Channels & Identity

Added

  • 16-chats-channels-and-identity.md (v1.1.0, layer: architecture). New canonical doc, expanding the set from 15 to 16. Captures the channel/chat design worked out across the audit: World B terminology (channel = transport, chat = container; rename map in §9); chat as the canonical, channel-agnostic container with three channel binding modes (Mirror / Relay / Injection) and the resulting per-chat agent memory; chat types, roles & a role-keyed postPolicy (everyone | admins) for broadcast/announcement chats, with a worked validation mapping a real clinic's group and 1:1 chats onto chat types (§2.1–2.2); the verified deep-link identity-binding flow (Telegram worked example) and the channel_identity table; the principal model in which inbound identity and outbound credentials are polymorphic over user / account / agent, with agent identity/credentials attaching at assignment scope and the borrow-vs-own distinction; and the delivery & capability model (§8) — the universal semantic message (prose + typed affordances + text-fallback invariant), compose-once/render-by-binding-mode, the channel adapter contract, the native-only Mirror posture for v1 (non-native I/O = Relay/Injection only), and edit/routing defaults. Includes a worked-examples map, a current-vs-target status/rename section, and deferred items (multi-account routing, one-bot-many-agents, group-from-channel UX, external-party contacts). Supersedes doc 06 on terminology and the channel↔chat relationship; cross-references 04, 06, 07, 09, 15.
  • decision-log.md — ADR-023 (channel = transport / chat = container), ADR-024 (chat canonical + Mirror/Relay/Injection binding modes), ADR-025 (principal-polymorphic identity & credentials, verified-link binding), ADR-026 (universal semantic message; compose once, render per channel), and ADR-027 (native-only conversational Mirror for v1; non-native I/O is Relay/Injection) added.

Note

  • The channels → chats rename (ADR-023) is decided but not yet applied to code; convex/schema.ts still uses the old names. Doc 16 §8 is explicit about this to avoid new doc-vs-code drift. The rename should land as one mechanical migration before any non-web channel is built.

2026-06-05 -- Doc 15 added: Tenancy & Deployment Topology

Added

  • 15-tenancy-and-deployment-topology.md (v1.0.0, layer: architecture). New canonical doc, expanding the set from 14 to 15. Documents how Thinklio implements multi-tenancy today — a single pooled Convex deployment with JWT-derived accountId isolation middleware, tenant-leading index discipline, and post-get ownership re-checks — and why that is correct at the expected scale (a few thousand small B2B orgs). Defines the cell pattern for graduating a tenant per-demand to a dedicated deployment (T2) or a customer-owned Convex account (T3), the provisioning flow for each topology, and the pooled-to-dedicated migration procedure (per-tenant export + hard-delete, reused from GDPR tooling), including the ID-remapping, Agent-component, RAG, and R2 complexities. Cross-references docs 02, 04, 07.
  • decision-log.md — ADR-022 added recording the single-pooled-deployment decision and the graduation path.

2026-04-17 -- Doc 04 rewritten for Convex-native representation

Rewritten

  • 04-data-model.md bumped to v2.0.0. The old doc described every entity using SQL-flavoured field types (UUID, JSONB, TIMESTAMPTZ, decimal, enum) and 266 SQL-type tokens despite the platform's Convex-first pivot. Full rewrite replaces all 61 entity tables with Convex defineTable validator blocks matching convex/schema.ts: v.id("table") for foreign keys, v.union(v.literal(...)) for enums, v.number() for timestamps and amounts, v.any() or v.object({...}) for JSON, v.array(v.float64()) with vectorIndex for embeddings. Every entity now declares its indexes explicitly. Section 2 adds a full SQL-to-Convex type mapping table for readers migrating between representations. Section 16.5 secret entity added to complete the vault cross-reference (the legacy doc referenced it from other sections but never defined it). Conceptual model, relationships, scope and visibility rules, and lifecycle semantics are unchanged; only the schema representation changes. Line count grew from 1936 to 2449 reflecting the more verbose Convex validator syntax.

Added

  • archive/legacy-sql-data-model.md. The previous doc 04 preserved verbatim with an archival banner. Registered in archive/README.md.

Stack-audit snapshot after this rewrite

Doc Convex Postgres Redis Supabase
04 Data Model 23 1 2 0

Remaining Postgres/Redis mentions are contextual (SQL-to-Convex mapping table, legacy comparison in section 2). The 827 Convex validator tokens (defineTable, v.id, v.string, etc.) now dominate the schema representation.

Verified

  • python scripts/build-doc-index.py --check: passes cleanly on all 14 docs.
  • mkdocs build: completes without errors; 04-data-model/index.html renders all 61 defineTable blocks with syntax highlighting.
  • Archive file correctly excluded from the built site.

2026-04-17 -- Docs 06, 08, 09, 13 retargeted for Convex-first runtime

Rewritten

  • 06-events-channels-and-messaging.md bumped to v2.0.0. The old doc described the Redis Streams event bus and the Go HarnessExecutor. Full rewrite replaces both with their Convex-native equivalents: the event table plus reactive queries for distribution, the Convex Workflow component for the durable harness, and HTTP actions for channel ingress. Channel identity, multi-channel delivery, Postmark email, and messaging UX conventions carry forward. A new Tier 3 promotion section explicitly documents when a dedicated Go service (channel ingress at scale, API surface under load, voice streams) becomes an analytics-driven next step.

Added

  • archive/legacy-event-system-harness-design.md. The previous doc 06 preserved with an archival banner. Registered in archive/README.md.

Updated

  • 08-agents-catalogue-and-platform-services.md section 3 Predictive Planning. Outcome Collector retargeted from a Redis Streams consumer group to a Convex scheduled function reading the event table against a persisted cursor. plan_score Redis cache replaced with Convex's reactive query cache. Supabase Vault references updated to the Convex-era secrets vault. Credential-security subsection rewritten for the Convex-first vault implementation. Phase 5 deploy note updated to describe the Score Service as a Convex query.
  • 09-external-api-and-tool-integration.md. Redis Streams references in section 1 (API strategy) and section 6 (Internal Service APIs) replaced with Convex reactive queries and the shared event table. Webhook delivery retargeted to a Convex scheduled function plus delivery actions, with the Tier 3 Go-service promotion path documented.
  • 13-implementation-plan-and-status.md. Added pre-pivot banner to section 2 (Implementation Phases) clarifying the VPS/Redis/Coolify bullets are archival while the capability outcomes are current. Added the same banner to section 3 (March 2026 Implementation Summary). Section 7 (Future Phases) now cross-references the Convex-era phases in doc 02 and explicitly flags voice and high-volume ingress as Tier 3 Go-service candidates.

Verified

  • python scripts/build-doc-index.py --check: passes cleanly on all 14 docs.
  • mkdocs build completes without errors.
  • Final per-doc audit: Convex mentions dominate across docs 02, 03, 05, 06, 10, 11, 12; remaining Postgres/Redis/Supabase mentions are either contextual (legacy comparisons, archive pointers) or explicitly framed as archival by a banner in the same section.

2026-04-17 -- Doc 05 rewritten for Convex-first persistence

Rewritten

  • 05-persistence-and-storage.md bumped to v2.0.0. The consolidation landed the old doc 06 (Persistence & Caching), 20 (Document Ingestion), 24 (Supabase Platform), and 41 (Document Intelligence) as-is, which meant doc 05 still read as a Postgres + Supabase + Redis reference despite the platform's Convex-first pivot (ADR-017). Full rewrite now covers Convex as the platform database, R2 as the file layer, native vector search, the ingestion pipeline built on the Workflow component, and execution-tier budgeting for ingestion. 21 sections, all Convex-era. The remaining Postgres/Redis/Supabase mentions are contextual (archive pointers and legacy comparisons).

Added

  • archive/legacy-postgres-persistence-design.md. The previous doc 05 content preserved verbatim under the archive with a clear "do not treat as current design guidance" banner. Retained because the Postgres schema, RLS, media pipeline, and document intelligence concepts carry forward conceptually into the Convex era.
  • archive/README.md registers the new archival file.

Fixed

  • Plain-text filename typos across docs 07, 10, and 12. References to 05-persistence-storage-and-ingestion.md, 08-agents-catalogue.md, and 09-external-api-tool-integration.md (all broken) updated to the correct filenames. These were in prose inline-code spans so they didn't show up in the earlier broken-link sweep.

Added

  • Doc 05 style overrides. Added docs/product/stylesheets/extra.css wired in mkdocs.yml via extra_css, giving the primary and secondary sidebars independent scroll so long navs and long ToCs reach the bottom on short pages.
  • Pygments 2.16.1 pin in docs/requirements.txt to work around a Pygments 2.17 regression that broke mkdocs build on unlanguaged code fences.

Verified

  • python scripts/build-doc-index.py --check clean.
  • mkdocs build completes without errors; 05-persistence-and-storage/index.html renders Convex-era content.
  • Archive file is correctly excluded from the built site.

2026-04-17 -- Post-consolidation audit and cleanup

Fixed

  • Cross-references across docs 01, 05, 06, 08, 09, 13. Seven broken links pointing at non-existent filenames (03-agent-architecture-and-extensibility.md, 07-security-and-governance.md) now resolve. Kept the existing short filename convention; updated the references.
  • Frontmatter drift across the set. All 14 canonical docs now carry the full schema (title, description, number, version, status, layer, tags, owners, supersedes, depends_on, last_updated). supersedes and depends_on are uniform integer arrays instead of the mixed integer/slug form that had emerged during consolidation. Leading-zero edge cases (e.g. [08, ...]) normalised to bare integers.
  • Doc 05 missing revision history. Added section 20 and matching ToC entry.
  • depends_on cycles. Cleaned up 02 ↔ 03, 07 ↔ 09, 02 ↔ 11 back-references so the dependency graph is a proper DAG. Reading order now topologically sorts without cycle fallbacks.

Added

  • scripts/build-doc-index.py full implementation. Replaces the step-2 placeholder. Parses every canonical doc's frontmatter, validates the schema (required fields, valid status and layer, ISO-8601 dates, duplicate numbers, numeric-sequence gaps, broken depends_on refs), and regenerates index.md with a document registry, layer-grouped authority map, Mermaid dependency graph, and topologically sorted reading order. Exits non-zero on validation failure so CI can gate on it. Supports --check and --json modes.
  • Pygments 2.16.1 pin in docs/requirements.txt. Pygments 2.17+ regressed on HtmlFormatter(filename=None) which pymdownx.highlight triggers on unlanguaged code fences. The pin restores clean mkdocs build.

Updated

  • docs/product/index.md. Regenerated from frontmatter via the build script. Now includes the agent-specs section and a clean reading order.
  • thinklio-docs-maintainer skill. Rewritten for the new structure. Knows about the 14-doc canonical set, the frontmatter schema, the build script workflow, semver-bump rules, and the archive read-only policy. Both .skill zip bundles rebuilt.
  • Root CLAUDE.md, apps/web/CLAUDE.md, and docs/README.md. No longer reference archived files (00-document-index-v01.md, 10-implementation-plan-v02.md). docs/README.md now describes the 14-doc layout and how to run MkDocs locally.

Verified

  • python scripts/build-doc-index.py --check: passes cleanly on all 14 docs.
  • No broken relative file references remain in any canonical doc.
  • mkdocs build completes without errors once Pygments is pinned.

2026-04-17 -- Documentation consolidation complete

Consolidated

The Thinklio documentation set was consolidated from 56 numbered files into 14 canonical documents plus three living files (this changelog, the decision log, and the doc index). The consolidation was executed across multiple sessions from 2026-04-16 to 2026-04-17. Every byte of original content is preserved in archive/old-numbering/.

New canonical documents:

Doc Title Absorbs old docs
01 Product & Strategy 01, 03, 22, 26, 38
02 System Architecture 02 (tombstone), 04, 43, 44, 54
03 Agent Architecture & Extensibility 15, 33, 37, 40, 42, 45, 46
04 Data Model 05, 32
05 Persistence, Storage & Ingestion 06, 20, 24, 41
06 Events, Channels & Messaging 07, 25, 27, 49
07 Security & Governance 08, 36, 47, 52
08 Agents Catalogue & Platform Services 19, 21, 30, 31
09 External API & Tool Integration 09, 16, 28, 51, 53
10 Client Applications & UX 12, 18, 23, 29
11 Convex Reference 43a, 48
12 Developer Guide 14, 35, 50, 55
13 Implementation Plan & Status 10, 34, 39
14 Thinklio Reference 17 (regenerated from docs 01--13)

Living files created:

  • index.md -- doc set homepage with reading order guidance, regenerated from frontmatter
  • changelog.md -- this file, carrying forward all history from old doc 13
  • decision-log.md -- ADR records carried forward from old doc 11, with new ADRs 017--021 added for the Convex-first pivot

Archive created:

  • archive/old-numbering/ -- all 57 original files preserved with git history intact
  • archive/README.md -- old-to-new mapping table with landed status for every source document

Key decisions recorded

  • ADR-017: Convex-first greenfield rebuild (supersedes ADR-005, 006, 007, 008, 015)
  • ADR-018: Three-tier execution model (interactive fast path, durable workflow, external queue)
  • ADR-019: Clerk for identity and organisation management
  • ADR-020: Messaging-first core abstraction
  • ADR-021: MCP tool permission intersection in shared channels

Context

The consolidation was triggered by the March 2026 docs audit which identified significant overlap, inconsistency, and drift across the growing document set. The plan reduced 56 files to 14 by grouping them into coherent domains. Each consolidated document carries YAML frontmatter (title, number, status, supersedes, depends_on) enabling automated index generation. The archive preserves full recovery capability.

2026-04-16 -- Numbering housekeeping and registry corrections

Renamed

  • 43-testing-observability-v01.md to 55-testing-observability-v01.md -- Resolved a document number collision. The testing and observability document had been created in late March with the same number (43) as the Convex Migration Architecture document, and was never added to the index. Renumbered to 55 so it occupies the next free slot in the registry.

Updated

  • 00-document-index-v01.md -- Registered doc 55 (Testing & Observability) across the Document Registry, Layer 9 (Developer Guides), Authority Map, and LLM Reading Order (Tier 9). Also corrected the Current Version for doc 50 (Convex + Clerk Setup Guide) from v01 to v02 to reflect the v02 file that now lives on disk.

Removed

  • 50-convex-clerk-setup-guide-v01.md -- Superseded on disk by the v02 file previously added in the 2026-04-10 update; the stale v01 file is now removed from the repo.

Context

Routine housekeeping ahead of a planned consolidation pass over the documentation set. The main action was resolving a numbering collision that had existed since late March (two documents sharing number 43, only one of which appeared in the index). No content changes to individual documents, only renaming, index updates, and removal of a superseded file.

2026-04-07 -- Governance Policy Framework expanded to v02

Updated

  • 47-governance-policy-framework-v01.md to v02 -- Three significant additions. (1) New section 4 (Rule Type Definitions): formal TypeScript interfaces for every rule body across all eight policy categories, plus shared types (PermissionLevel, BudgetPeriod, Classification, ThresholdCondition, etc.) and a top-level PolicyRule discriminated union. This gives implementers a concrete contract rather than inferring shapes from inline examples. (2) Expanded section 5.4 (Default Templates): nine complete policy_templates records with full rule bodies covering the baseline governance set applied to all new accounts: external comms require confirmation, per-user daily budgets tiered by subscription plan ($5 Starter / $20 Professional / $50 Business), baseline brand voice, audit logging at both depths, learn-then-trust approval for the first 5 outbound messages, delegation origin restrictions, trust escalation cap, and cost attribution to the originating user. (3) New section 5.5 (Industry Template Packs): full rule bodies for healthcare (7 policies covering PII redaction, classification ceiling, external processing restriction, mandatory health disclaimer, no-diagnosis topic restriction, 7-year audit retention, AI disclosure on outbound comms), finance (7 policies covering transaction approval gates, compliance delegation restriction, full audit trace, 7-year retention, daily outbound cap, no-advice topic restriction, external party gate), and legal (8 policies covering classification ceiling, strict cross-channel isolation, external processing restriction, full audit trace, 7-year retention, no-advice topic restriction, always-on AI disclaimer, document edit review trigger). Sections renumbered (old 4-7 became 5-8). Revision history table added.
  • 00-document-index-v01.md -- Registry updated to show doc 47 at v02.

Context

The v01 governance framework had solid category definitions and inline examples, but two gaps would have caused friction during implementation. First, the rule bodies used v.any() in the Convex schema with no formal type definitions, meaning an LLM implementing different parts of the codebase could produce inconsistent rule shapes. Second, the default and industry templates were described in prose ("sensible per-user daily budget", "PII redaction in broad channels") without concrete rule objects, so there was no actual seed data to implement. This revision closes both gaps: typed interfaces provide the contract, and the template bodies provide the seed data.

2026-04-06 -- MCP integration suite, execution tiers, messaging UX reference, and Convex setup guide

Added

  • 49-messaging-ux-state-of-the-art-v01.md -- Survey of messaging UX patterns across nine major platforms (Apple Messages, WhatsApp, Telegram, Signal, Discord, Slack, Google Messages, Microsoft Teams, Meta Messenger) as of April 2026. Covers message composition, threading, reactions, read receipts, voice messages, search, AI integration, and accessibility. Intended as a planning reference for Thinklio's messaging-first UI.
  • 50-convex-clerk-setup-guide-v01.md -- Internal setup guide covering the complete Convex + Clerk integration for development and production environments. Includes JWT validation, webhook sync for user/org lifecycle events, Next.js middleware configuration, and environment variable reference.
  • 52-mcp-credential-and-permission-model-v01.md -- Defines the credential layer (three scopes: platform, account, user; injection via HTTP headers; OAuth token refresh lifecycle) and the permission layer (channel-aware tool visibility resolution based on user permissions, agent configuration, and channel participant membership). Child of doc 51.
  • 53-mcp-server-reference-v01.md -- Reference for the three Go MCP servers maintained in thinklio-services: Cliniko (6 tools, user-scoped), Notion (15 tools, account-scoped), and Xero (18 tools, account-scoped OAuth). Documents the common architecture (single Go binary, /mcp + /health + /meta endpoints, Streamable HTTP transport), tool inventories with trust levels, deployment configuration, and Docker/health check setup.
  • 54-execution-tiers-workflow-budget-v01.md -- Establishes a three-tier execution model to manage Convex's 100-slot workflow/workpool ceiling on the Professional plan. Tier 1 (fast path) uses direct actions with the Action Retrier for interactive chat; Tier 2 (durable workflow) uses Convex Workflow for delegation chains, email processing, and knowledge indexing; Tier 3 (external queue) provides an escape hatch for high-volume workloads. Includes channel classification table, slot budget allocation (55 allocated, 45 headroom), monitoring thresholds, and the growth path to Enterprise/self-hosted.

Updated

  • 51-tool-integration-developer-guide-v01.md to v02 -- Major revision. Added Streamable HTTP transport section (replacing ambiguous stdio/remote mix). Rewrote the server example to use StreamableHTTPServerTransport with Express. Changed credential injection from environment variables to HTTP headers. Added sections on authentication between Thinklio and MCP servers (bearer token and OAuth 2.1), tool call timeouts (60-second limit), idempotency and retry design for write operations, tool discovery and update lifecycle (24-hour re-discovery cycle), and a note that Cliniko API examples are illustrative rather than production-ready.
  • 00-document-index-v01.md -- Docs 49 through 54 added to registry. Layer assignments: 49 to Layer 5 (Client Applications), 50/51/53 to Layer 9 (Developer Guides), 52/54 to Layer 2 (Platform Design). Authority map, dependency map, and LLM reading order updated. Five selective reading rows added. "Adding a new external integration" update trigger updated to reference docs 51, 52, 53.
  • README.md -- Document count updated from 40 to 49.

Removed

  • 52-cliniko-mcp-server-plan-v01.md -- Superseded by docs 52 (MCP Credential and Permission Model) and 53 (MCP Server Reference), which cover the broader integration pattern rather than a single server's implementation plan.

Key Decisions Recorded

  • Interactive agent turns (web app, Telegram) bypass Convex Workflow entirely, using direct actions with the Action Retrier for LLM call resilience
  • Workflow slots are reserved for work that genuinely needs durability: delegation chains, email processing, document indexing
  • Notifications are always separate from the work that triggers them (decoupled failure domains, no workflow slot consumption for standard notifications)
  • MCP servers use Streamable HTTP transport (the current MCP standard); SSE-based transport is deprecated
  • Credentials are injected via HTTP headers per request; MCP servers never store credentials
  • MCP tool permission resolution is channel-aware: agents only use tools that every channel participant is permitted to see
  • Calendar, Mail, and File Storage are platform internals (Convex tools with provider abstraction), not MCP servers, because they require multi-account OAuth, reactivity, and deep platform integration

Context

This batch of changes came out of a design session focused on three questions: how to keep chat interactions maximally responsive on Convex's Professional plan, how to structure the MCP integration stack now that working servers exist (Cliniko, Notion, Xero), and which integrations should be MCP servers vs platform internals. The execution tiers doc (54) addresses the first question by splitting work into fast path (no workflow slots), durable path (budgeted workflow slots), and external queue (zero slots, for when volume demands it). The MCP docs (51 v02, 52, 53) address the second by documenting the transport model, credential/permission system, and server reference as a coherent suite. The third question led to a taxonomy: foundational capabilities (calendar, mail, files) stay internal because they need OAuth, reactivity, and deep identity coupling; vertical API integrations (practice management, accounting, project tools) are MCP servers because they're stateless and credential-simple.

2026-04-03 -- Convex Component Directory added

Added

  • 48-convex-component-directory-v01.md -- Comprehensive catalogue of all 75 Convex components available on convex.dev/components, organised into eight categories: AI (13), Authentication (12), Backend (10), Collaboration (6), Database (8), Durable Functions (6), Integrations (13), and Payments (7). Each component entry includes npm package name, version, weekly downloads, author, licence, GitHub URL, description, installation command, and use cases. The document is designed primarily for LLM context windows, giving agents a complete picture of what Convex components exist and when to use them. Covers both official get-convex components and community contributions. Includes installation patterns, the convex.config.ts configuration approach, and links to machine-readable llms.txt endpoints for each component. Written in Australian English.

Updated

  • 00-document-index-v01.md -- Doc 48 added to registry (Active), Layer 2 (Platform Design), authority map (authoritative for the Convex component ecosystem), dependency map (reads from 43a), and LLM reading order (Tier 3, item 18, subsequent items renumbered). Two selective reading rows added/updated for browsing Convex components and understanding Convex platform capabilities.
  • README.md -- Document count updated from 39 to 40.

Context

The Convex component ecosystem is a key part of Thinklio's platform infrastructure now that the project has moved to a Convex-first architecture (doc 44). Having a comprehensive, LLM-consumable catalogue of all available components means that coding agents like Claude Code can make informed decisions about which components to integrate when implementing features, rather than discovering them ad hoc. The document complements doc 43a (Convex Capability Statement) which covers the platform itself, while doc 48 focuses specifically on the component marketplace. A companion skill (convex-component-updater) was also created to refresh the document periodically as new components are published.

2026-04-03 -- Governance Policy Framework added

Added

  • 47-governance-policy-framework-v01.md -- Comprehensive governance framework defining eight policy categories for controlling agent behaviour: (1) Action permissions with five-level autonomy gradient (deny, read, draft, confirm, autonomous) covering mail, calendar, CRM, and clinical data examples; (2) Cost limits covering per-interaction, per-period, per-user, per-team, and per-tool budgets plus model tier restrictions; (3) Data boundaries for classification ceilings, PII handling, external processing restrictions, data residency, and cross-channel isolation; (4) Temporal constraints for operating hours, cooldown periods, quiet hours, and rate-of-action limits; (5) Delegation constraints for external agent restrictions, trust escalation prevention, prohibited combinations, and cost attribution; (6) Content policies for brand voice, topic restrictions, mandatory disclaimers, response format, and language; (7) Audit requirements for logging depth, review triggers, disclosure requirements, periodic review thresholds, and retention policies; (8) Approval gates with action-type, first-of-type (learn-then-trust), confidence, external-party, and escalation triggers. Also defines the policy evaluation model (four evaluation points during agent turns), layered resolution with most-restrictive-wins rule, policy scoping (agent, channel, tool, user dimensions), approval state tracking with workflow integration, policy templates for new accounts and industry-specific packs (healthcare, finance, legal), governance UI concepts, and performance considerations. Three new schema tables: extended account_policies and team_policies with full category set and scoping, pending_approvals for human-in-the-loop state, and policy_templates for reusable governance patterns.

Updated

  • 00-document-index-v01.md -- Doc 47 added to registry, Layer 2 (Platform Design), authority map, dependency map (reads from docs 46, 45, 08, 44, 38), and LLM reading order (Tier 3, item 19, subsequent items renumbered). Three selective reading rows added for governance configuration, data boundaries, and approval gates.

Key Decisions Recorded

  • Eight policy categories cover all governance concerns without requiring custom code
  • Five-level autonomy gradient (deny/read/draft/confirm/autonomous) provides the right granularity for action permissions
  • Most-restrictive-wins resolution across account, team, and user layers
  • Policy resolution is snapshotted once at turn start, not re-evaluated per step
  • Approval gates pause workflows via awaitEvent and surface confirmations in the channel
  • Policy templates ship with the platform for new accounts, with industry-specific packs for regulated sectors
  • Team policies support a subset of categories (delegation constraints and audit requirements are account-level only)

Context

This document was prompted by a discussion about what governance constraints organisations would need beyond the obvious email send-with-permission example. The eight categories emerged from working through real scenarios: healthcare practices needing PII controls and clinical data access restrictions, financial services needing transaction approval thresholds and compliance audit trails, and general business needs around operating hours, cost management, and brand voice enforcement. The framework is designed so that all governance is declarative data (not code), evaluated by lightweight matching logic, and configurable through the admin UI without developer involvement.

2026-04-02 -- Agent Extensibility and Composability Model added

Added

  • 46-agent-extensibility-composability-v01.md -- Unified model for how all functionality is constructed, composed, extended, and executed in Thinklio. Covers five extensibility layers: (1) Tools as stateless capabilities with three types (internal Convex functions, external REST endpoints, MCP-discovered tools) sharing a single invocation interface; (2) Agents as declarative reasoning entities with three construction patterns (catalogue, composed, custom); (3) External orchestration via a generic dispatch/callback/status contract for n8n, Go services, and any HTTP-callable system; (4) Custom Convex components for isolated reusable infrastructure (governance engine, usage metering, document parser, dispatch manager); (5) Platform agent catalogue as the composition surface. Also defines five trigger types (channel message, external webhook, scheduled cron, dispatch callback, internal system event), MCP server integration with dynamic tool discovery, agent versioning policy (config snapshot at turn start, changes apply on next turn), durability and recovery patterns (workflow journalling, tool call recovery, dispatch timeout handling), and the performance tier model inherited from doc 42 (sub-10ms computational parser, sub-500ms fast execution, full LLM reasoning). Introduces four new schema tables: dispatch_log, event_triggers, scheduled_agent_runs, mcp_servers. Extends the tools table with MCP type and auth config. Concludes with Agent Studio implications: if primitives are correct, Agent Studio is a configuration and composition surface, not a programming environment.

Updated

  • 00-document-index-v01.md -- Doc 46 added to registry, Layer 4 (Agents), authority map, dependency map (reads from docs 45, 44, 40, 33, 42, 07, 16), and LLM reading order (Tier 5, item 32, subsequent items renumbered). Five selective reading rows added for extensibility model, external integration, external orchestration, and custom agent building.

Key Decisions Recorded

  • Tools and agents remain distinct entities (not unified into a single "capabilities" concept) but share a uniform invocation interface through the tool resolver
  • Agent delegation is invoked through the same tool-calling interface as regular tools, preserving a flat tool list from the agent's perspective
  • External orchestration uses a generic dispatch/callback contract regardless of target system (n8n, Go, external)
  • MCP servers are a first-class tool source alongside internal and external REST tools
  • Agent versioning uses config-snapshot-at-turn-start rather than explicit version numbers
  • Graceful degradation for partial failures is handled by agent reasoning (option 2), not special infrastructure
  • Custom Convex components are reserved for cross-cutting infrastructure, not for individual agents or business tools

Context

This document emerged from a design discussion about how Thinklio's agent primitives, tool types, and execution models fit together into a unified extensibility model. The discussion identified that if the primitives are correct, the Agent Studio becomes a composition surface rather than a programming environment. The five-layer model covers the full spectrum from simple stateless API calls through to complex multi-agent orchestration with external workflow dispatch. The document also addresses performance concerns (triage tiers ensure quick things stay quick), durability (workflow journalling, dispatch recovery), and real-world integration patterns (e.g. a podiatry practice connecting its patient management system's REST API as external tools for a custom Practice Assistant agent). The dispatch/callback contract was designed to be generic enough for n8n, Go services, and any future external orchestration target.

2026-04-02 -- Agent Component Integration Plan added with UX model refinements

Added

  • 45-agent-component-integration-v01.md -- Implementation playbook for Phase 2 (Agents) of the greenfield Convex-first architecture. Covers two major areas:
  • UX model (section 2): Defines agents as first-class participants in message channels, added and managed like any other user. Three trigger modes (mention-only, proactive, silent) per agent per channel, respecting a governance hierarchy where organisation policies set the ceiling and teams/users can tighten within those bounds. Introduces the agent catalogue concept (platform-level templates that organisations activate and customise), user-level agent configuration (personal credentials such as connected email accounts), composable agent delegation with privilege isolation, channel-scoped knowledge retrieval (knowledge context derived from where the chat happens, not agent config), and notification/interruption control (inline, threaded, DM, or silent response modes).
  • Implementation plan (sections 3-9): Maps five Convex components (Agent, Workflow, RAG, Rate Limiter, Sharded Counter) to Thinklio's architecture. Defines three integration callbacks (usageHandler for cost accounting, rawResponseHandler for audit, contextHandler for knowledge injection with channel-derived scoping). Specifies the channel-to-thread bridge linking the UI message stream to Agent component execution threads. Adds nine new schema tables: agent_catalog (platform-level templates), agents (account installations with catalogEntryId, defaultTriggerMode), tools, agent_tools, agent_threads (with per-channel triggerMode), agent_assignments, user_agent_config (personal credentials and preference overrides), team_policies (tighten-only within account bounds), and additions to account_policies (trigger_mode_restriction, notification_default types). Twelve incremental implementation steps from component installation through governance policy enforcement. Risk register covering proactive agent noise, policy layering complexity, and delegation visibility.

Updated

  • 00-document-index-v01.md -- Doc 45 added to registry. Added to Layer 4 (Agents). Authority map entry added. Dependency map entry added under Agent Layer Dependencies. LLM reading order updated (doc 45 inserted into Tier 5 as item 31, subsequent items renumbered through Tier 9). Two selective reading rows added for agent implementation on Convex and agent trigger modes/governance.

Key Decisions Recorded

  • Agents are channel participants, not a separate interaction surface: same channels, same message streams, same permission model
  • Three trigger modes (mention, proactive, silent) configurable per agent per channel, with governance hierarchy enforcement
  • Platform agent catalogue model: off-the-shelf agents as templates, organisation "installs" and customises them
  • Knowledge context derived from channel scope (team channel = account + team knowledge), not from agent configuration
  • Layered governance: account policies set the ceiling, team policies tighten, user preferences tighten further; no layer can loosen restrictions set above it
  • User-level agent credentials (e.g. connected email accounts) stored separately from agent config and governance
  • Delegation does not transfer privileges: delegate agents are governed by their own trust level and account policies regardless of the invoking agent

Context

This document was drafted after a design discussion about the user experience model for agents in Thinklio. The original v0.1.0 covered the technical component integration but lacked the UX framing: how users discover, add, and interact with agents in channels; how proactive vs explicit interaction works; how personal configuration (credentials, preferences) fits alongside organisational governance; and how the agent library/installation model works. The v0.2.0 revision adds section 2 (UX Model) addressing all of these, updates the schema to include agent_catalog, user_agent_config, team_policies, trigger modes, and notification modes, and refines the contextHandler to derive knowledge scope from channel context rather than agent configuration. The implementation steps and risk register were also updated to reflect these additions.

2026-04-01 -- Greenfield Convex-first architecture proposed; Convex capability statement and migration analysis added

Added

  • 43-convex-migration-architecture-v01.md -- Initial analysis of migrating Thinklio's agent execution layer to Convex.dev. Proposed a two-plane architecture (Agent Plane in Convex, Platform Plane in Go/Postgres/Redis) with Keycloak for auth. Covers the performance problem (7-hop latency chain), component mapping, cross-plane communication flows, risks, and a five-phase implementation plan. This document is now superseded by doc 44, which takes a more aggressive Convex-first approach, but it is retained as a record of the analysis that led to that decision.
  • 43a-convex-capability-statement-v01.md -- Comprehensive reference for Convex platform capabilities as assessed in April 2026. Covers: core database (OCC/MVCC, indexes, queries/mutations/actions), reactivity and real-time, search (text + vector), file storage, scheduling, authentication (OIDC/Clerk), the convex-helpers library (custom functions, RLS, relationships, CRUD, Zod, Hono, triggers), the full component ecosystem (first-party and community), data streaming (log streams, Fivetran/Airbyte), self-hosted deployment (pros/cons/limitations), pricing, platform guarantees, best practices and anti-patterns, and client libraries including Flutter/Dart community packages.
  • 44-greenfield-convex-architecture-v01.md -- Proposed greenfield rebuild of Thinklio's architecture centred on three managed services: Convex for all application logic and data, Clerk for authentication and organisation management, and Cloudflare R2 for file storage. Eliminates Redis, Go services, Supabase, and the custom event bus. Key design decisions: messaging-first model where channels are the core abstraction and agents are first-class participants alongside users; single Convex project with reactive caching replacing Redis and multi-tier caching; Clerk Organisations mapping to Thinklio accounts with RBAC; governance enforced as custom function middleware reading reactively cached policy documents; four-layer knowledge model preserved with Convex native vector search and RAG component; document ingestion via Workpool; audit trail via triggers with Fivetran CDC export. Includes full Convex schema definitions (18 tables), five-phase build plan with exit criteria, six resolved design questions, and a self-hosted Hetzner deployment option for enterprise customers.

Updated

  • 00-document-index-v01.md -- Docs 43, 43a, and 44 added to registry. Doc 43 marked as superseded by 44. Docs 43a and 44 added to Layer 2 (Platform Design). Authority map entries added for both active docs. Dependency map entries added for all three. LLM reading order updated (43a and 44 inserted into Tier 3 as items 17–18, subsequent items renumbered through Tier 9). Selective reading rows added for Convex architecture and capabilities.

Key Decisions Recorded

  • Convex Cloud (Ireland) as the primary application platform, replacing Go services, Supabase, and Redis
  • Clerk for authentication and organisation management, replacing Supabase Auth and the planned Keycloak deployment
  • Messaging-first architecture: channels with user and agent participants as the core interaction model
  • Single Convex project (consolidation over partitioning) for reactive caching performance and LLM-friendly development
  • Go services deferred: not required for initial build, available as a scale optimisation later
  • Flutter mobile app with convex_flutter, validated via proof-of-concept in Phase 1; Swift/Kotlin native as fallback

Context

This is a significant architectural pivot. The prior design (Go services, Supabase Postgres/Auth, Redis Streams event bus, pgvector, multi-tier caching) was sound but introduced structural latency and operational complexity that would slow both development and runtime performance. The Convex-first approach collapses six Go services, Redis, and Supabase into a single reactive backend with managed auth. The analysis progressed through three stages: doc 43 (conservative two-plane split with Convex for agents only), then broadening Convex's role to include governance and permissions (leveraging reactive query caching for policy enforcement), and finally doc 44 (greenfield rebuild with Convex, Clerk, and R2 as the entire stack). The primary motivations are agent interaction latency, development velocity for a small team, and the LLM-assisted development advantage of a single-codebase architecture.

2026-03-27 -- Smart input triage architecture added

Added

  • 42-smart-input-triage-v01.md -- Design document for a three-tier message routing system that classifies user input before any LLM call is made. Tier 1 is a computational parser running in under 10ms using lexicon lookups and regex to detect intent (knowledge lookup, knowledge store, greeting, tool request, time query, complex reasoning, etc.) and assign a confidence score. High-confidence simple intents are routed to Tier 2 for direct tool execution or template responses (target under 500ms). Low-confidence or complex intents fall through to Tier 3 for full LLM reasoning via Claude/OpenRouter. The motivation is that the current uniform execution path takes 2.5–8 seconds regardless of message complexity; triage eliminates that overhead for the majority of common interactions.

Updated

  • 00-document-index-v01.md -- Doc 42 added to registry, Layer 3 groupings, authority map, dependency map, and LLM reading order (Tier 4, item 24). Reading order renumbered throughout subsequent tiers. Selective reading row added for message routing and execution performance.

Context

Smart input triage is an execution-layer optimisation that sits upstream of the harness. It does not change what agents can do, only the latency profile for common interactions. The design is presented as a companion to the event system and harness docs (07, 15).

2026-03-27 -- Document intelligence architecture added; doc 20 updated to v02

Added

  • 41-document-intelligence-v01.md -- New companion document to doc 20. Covers the document intelligence layer: what it is, why parsing quality sets the ceiling for all downstream operations, and how parsing is structured as a tiered, upstream stage separate from the enrichment and indexing pipeline. Defines two document classes (uploaded vs. generated), three parsing tiers (Tier 1 local spatial parsing via LiteParse/PDF.js/Tesseract.js, Tier 2 agentic OCR via LlamaParse API, Tier 3 fallback), the Parse Orchestrator that selects tier based on complexity signals and account data policy, and the allow_external_processing account flag that governs whether documents can be sent to external parsing APIs. Also specifies the parsed_content intermediate representation format and how generated documents bypass the parse step entirely.

Updated

  • 20-document-ingestion-storage-v02.md (bumped to 0.3.0) -- Revised to align with the new document intelligence architecture. pdf_extract processor replaced with document_parse throughout; chunking strategy updated to format-aware (consuming structured output from the parser rather than raw text); allow_external_processing account flag and is_external processor flag added; MediaProcessingJob status enum extended; implementation phases updated to reference doc 41 for the parse layer; architecture diagram updated.
  • 00-document-index-v01.md (bumped to 0.2.1) -- Doc 20 version updated to v02. Doc 41 added to registry, Layer 3 groupings, authority map, dependency map, and LLM reading order (Tier 4, after doc 20). LLM reading order item numbers incremented throughout subsequent tiers. Selective reading row added for document parsing and intelligence.

Context

The document intelligence architecture separates parsing (the derivation of a high-quality structured text representation from a raw file) from the enrichment and indexing pipeline that follows it. This split clarifies ownership: doc 20 owns the storage, processing pipeline mechanics, library system, and retrieval layer; doc 41 owns the parsing layer upstream of all of that. The key design decision captured in doc 41 is that parsing tier is determined by document complexity and account data policy, not by file type, and that the default path runs entirely on Novansa-managed infrastructure with external API parsing as an explicit opt-in.

2026-03-26 -- Documentation audit and rewrite: five-sprint revision of the full doc set

Added

  • 40-agent-architecture-v01.md -- New conceptual reference for the agent layer. Covers: what an agent is; the two execution models (platform-executed vs. externally-executed); the four knowledge layers (Agent, Account, Team, User) and their runtime resolution; channel architecture and multi-channel delivery; agent composition and the coordinator pattern; governance (trust levels, policies, cost controls, audit trail); the Tier 1/Tier 2 agent taxonomy; and the agent lifecycle. This doc is the entry point for understanding how agents work and where to find agent specifications.
  • docs-audit-march-2026.md -- Audit report recording all inconsistencies identified, the five-sprint rewrite plan, the implementation reconciliation (phases 0–3 complete, 4–5 partial, 6 not started), and the five structural decisions made before work began.

Updated (full rewrite)

  • 04-system-architecture-v02.md (bumped to 0.3.0) -- Complete merge and rewrite of former doc 02 (Architecture Overview) and doc 04 (System Architecture). Now the single authoritative architecture document. Key corrections: admin/ replaced with apps/web/ and apps/mobile/; PostgreSQL Docker container removed; single-binary + Supabase Cloud deployment documented; config struct updated with SupabaseURL, SupabaseServiceKey, DatabaseURL, DatabasePoolURL; new event types added (note.shared, comm.dispatched, mention.created). 17 sections including Go service interfaces, communication patterns, deployment architecture, and technology stack.

Updated (targeted corrections)

  • 03-prd-specification-v02.md (bumped to 0.2.1) -- Account roles corrected from owner, admin, member to owner, admin, editor, viewer (FR-09.2). Constraints section updated: self-hosted PostgreSQL replaced with Supabase Cloud (PostgreSQL 16 + Auth + Vault, Frankfurt EU, Supavisor pooling, pgvector). Five remaining "organisation/organisations" occurrences corrected to "account/accounts".
  • 09-api-contracts-v03.md (bumped to 0.3.1) -- "registered_by": "org-uuid" corrected to "registered_by": "account-uuid" in Integration API tool registration response. March 2026 addendum restructured from "Addendum" to "Complete Endpoint Reference" with proper framing. All footer cross-references updated with correct version suffixes. Status changed from Draft to Active.
  • 07-event-system-harness-v03.md (bumped to 0.3.1) -- Footer cross-references updated with correct version suffixes.
  • 14-deployment-administration-v03.md (bumped to 0.3.1) -- Repository structure corrected: admin/ replaced with apps/web/ and apps/mobile/ in the directory tree. Footer cross-references updated with correct version suffixes.
  • 01-product-overview-v02.md (bumped to 0.2.1) -- Placeholder pricing section replaced with the real four-tier structure (Free, Team, Account, Enterprise) and a pointer to doc 38 for full details. Footer references updated: 02-architecture-overview.md replaced with 04-system-architecture-v02.md; version suffix added to doc 03 link.
  • 24-supabase-platform-database-auth-v02.md -- Five broken cross-reference filenames corrected in section 7 and footer.
  • 38-subscription-plans-enforcement-v01.md -- H1 heading number corrected from 37 to 38.
  • 39-monorepo-migration-plan-v01.md -- Status updated from Proposed to Completed.

Tombstoned

  • 02-architecture-overview-v03.md -- Replaced with tombstone redirecting to doc 04 (v0.3.1). The document set no longer maintains doc 02 as an active document; doc 04 (System Architecture) is the sole authoritative architecture reference.

Out-of-date notices added

  • 17-thinklio-reference-v03.md -- Banner added at top directing readers to doc 00 for reading order and noting the reference is pending regeneration.
  • 10-implementation-plan-v02.md -- Banner added pointing to doc 34 for current implementation status.

Updated (index and metadata)

  • agent-specs/00-index.md (bumped to 0.2.0) -- Full rewrite. Replaced production-order groupings with Tier 1 / Tier 2 structure. Tier 1 (11 fundamental agents): Research, Writer, Fact Checker, Data, Taskmaster, Rolodex, Keeper, Mail, Calendar, Messenger, Knowledge Base. Tier 2 (26 applied agents) across six sub-groups: Content Pipeline, Engagement & Support, Coordinator, Synthesis & Communications, Business Intelligence, Creative, Platform & Executive. Complete agent list runs to 37 named agents. Points to doc 40 for conceptual context and doc 33 for the manifest format.
  • 00-document-index-v01.md (bumped to 0.2.0) -- Docs 36–40 added to registry. Doc 02 marked as Tombstone. Doc 32 status corrected from Draft to Active. Document Groupings updated: Layer 1 corrected (doc 02 removed, doc 38 added), Layer 4 extended with doc 40 and agent-specs reference, Layers 10–11 added. Authority map: doc 02 row corrected to point at doc 04; new authority rows added for docs 36, 37, 38, and 40. Dependency map: doc 40 added to Agent Layer block. LLM Reading Order: Tier 1 now references doc 04 rather than tombstoned doc 02; Tier 5 leads with doc 40 and includes agent-specs reference; subsequent tier numbering corrected throughout. Selective reading table updated.

Context

This revision was triggered by accumulated inconsistencies across the 40-document set following the Supabase migration, single-binary consolidation, org-to-account rename, and monorepo restructure. A formal audit pass (docs-audit-march-2026.md) identified 15 specific inconsistencies. Work proceeded across five sprints with explicit sign-off between each. The most significant structural output is doc 40 (Agent Architecture) and the rewritten agent-specs index, which together give the agent layer a proper conceptual home in the doc set. The most significant correction was the full rewrite of doc 04, which had drifted substantially from the implemented architecture.

2026-03-21 -- Comprehensive doc revision: org-to-account rename, Supabase migration, v03 updates

Added

  • 34-implementation-summary-march-2026-v01.md -- Point-in-time snapshot of what's been built, what's pending, and the key architectural decisions made up to March 2026. Covers the single-binary consolidation, Supabase Cloud migration, account rename, 63-table schema, and the four source-of-truth documents (02, 09, 32, 34).
  • 35-programming-guide-v01.md -- Skeletal developer reference for the Go backend and custom agent development. Covers repository structure, dev environment setup, architecture conventions, database layer, event bus, auth, harness, agent system, tool system, knowledge system, job system, channel system, core data structures API, platform services, predictive planning, custom agent development, integration API guide, app UI integration, and deployment. Each section has TODO markers for the implementation agent to fill in from the codebase.

Updated (version bumps)

  • 02-architecture-overview-v03.md -- Updated for March 2026 implementation status, single binary model, Supabase Cloud migration.
  • 05-data-model-v03.md -- Complete rewrite. Organisation renamed to Account throughout. Four-tier roles (owner/admin/editor/viewer). user_profile entity synced from Supabase Auth. 24 new entities added (tasks, contacts, items, notes, tags, channels, communications, planning, platform services, invitations, credit ledger). All tables use singular naming. Updated ER diagram.
  • 06-persistence-caching-v03.md -- Complete rewrite of SQL schemas with singular table names and account_id scoping. All new CREATE TABLE statements with indexes and constraints. RLS policies updated to auth.uid() pattern. Connection pooling updated for Supavisor. New data classification entries for tasks, contacts, items, notes, and planning tables.
  • 07-event-system-harness-v03.md -- OrgID renamed to AccountID in all Go structs and code. 11 new event types added (note.shared, note.mentioned, comm.dispatched/delivered/failed, agent_event.received, task/contact/item CRUD events). Updated consumer group table.
  • 08-security-model-v03.md -- Authentication section rewritten for Supabase Auth. JWT structure updated to Supabase format. Four-tier RBAC model. Secret management rewritten for Supabase Vault. RLS enforcement updated to auth.uid() pattern. Inter-service auth updated for single binary. Added note sharing visibility rules.
  • 09-api-contracts-v03.md -- Cleaned 13 stale organisation references in pre-addendum sections (Platform API auth, knowledge scope, Organisation Management endpoints renamed to Account Management, internal service APIs).
  • 14-deployment-administration-v03.md -- Single Go binary replaces 6 separate binaries. PostgreSQL removed from local deployment (now Supabase Cloud). Docker Compose simplified to 4 services. Environment variables restructured for Supabase. Backup and migration sections updated.
  • 17-thinklio-reference-v03.md -- Comprehensive update across all sections. 22+ org-to-account replacements. New sections for Core Data Structures, Predictive Planning, and Unified Capability Model. Technology stack updated for Supabase Cloud and single binary. Document lineage extended to docs 17-35.
  • 24-supabase-platform-database-auth-v02.md -- Table name fix (public.users to user_profile). Complete 63-table list grouped by domain. Four-tier roles documented. Cross-references to docs 28 and 32.
  • 28-api-reference-accounts-onboarding-v02.md -- Added missing GET endpoint response body. Added Related API Documents section with cross-references to docs 09, 31, 32, 33.

Updated (content changes, no version bump)

  • 01-product-overview-v02.md -- Organisation renamed to Account throughout.
  • 03-prd-specification-v02.md -- Organisation renamed to Account (24 occurrences).
  • 04-system-architecture-v02.md -- Organisation renamed to Account.
  • 10-implementation-plan-v02.md -- Organisation renamed to Account.
  • 11-decision-log-v02.md -- Organisation renamed to Account.
  • 12-user-guide-v02.md -- Organisation renamed to Account.
  • 15-job-system-agent-composition-v02.md -- Organisation renamed to Account.
  • 16-external-api-strategy-v02.md -- Organisation renamed to Account.
  • 18-thinklio-internationalisation-v02.md -- Organisation renamed to Account.
  • 19-starter-agent-catalogue-v01.md -- Organisation renamed to Account; fixed Knowledge Base Agent tagline.
  • 20-document-ingestion-storage-v01.md -- Organisation renamed to Account.
  • 22-thinklio-pricing-revision-v01.md -- Organisation renamed to Account.
  • 23-thinklio-app-ui-specification-v03.md -- 7 manual edits: Agent roster grouping, knowledge scope tab, Settings tab, Profile card field, Predictive Planner setting, User data model field, OrgSettings type renamed to AccountSettings.

Updated (index and metadata)

  • 00-document-index-v01.md -- Registered docs 34 and 35. Version bumps for 8 documents (02, 05, 06, 07, 08, 09, 14, 17 to v03; 24, 28 to v02). Promoted docs 14, 23, 24, 28 from Draft to Active. Added Layer 9 (Developer Guides). Updated dependency map. Extended reading order to Tier 9.

Context

This is a comprehensive pre-deployment revision of the entire documentation set. The trigger was the need to ensure all 35 documents are consistent and up to date before initial backend deployment and app integration testing. The three major changes that cascaded through the full set were: the organisation-to-account rename (245 occurrences across 25 files), the Supabase Cloud migration (affecting auth, database, secrets, and deployment docs), and the addition of 24 new entities to the data model (tasks, contacts, items, notes, planning, channels, communications, and platform services). Doc 35 (Programming Guide) was created as a skeletal structure for the backend coding agent to fill in from the actual codebase during implementation.

2026-03-20 -- Docs 31–33, agent definition spec, platform services, core data structures

Added

  • 31-platform-services-llm-credits-admin-v01.md -- External service management, LLM model selection, credit-based billing (platform-managed vs BYOK), and app administration configuration. Defines the two billing modes (platform-managed with 2% margin, bring-your-own-key), model routing, cost tracking, and admin settings.
  • 32-core-data-structures-tasks-contacts-items-v01.md -- Four universal data structures for agents: tasks (with lists, status, priority, assignment), contacts (person/organisation, visibility model, CRM sync), items (generic ticketing/request entity), and notes (free-form with linking). Agent-first design with UI as secondary interface.
  • 33-agent-definition-extensibility-v01.md -- Universal agent definition format and extensibility specification. Defines the agent manifest (YAML), two execution models (platform-executed via system prompt, externally-executed via HTTP endpoint), the external agent execution contract (synchronous and deferred patterns with callbacks), agent registration and lifecycle, and agent UI views as a content type. Views use declarative definitions for standard types (kanban, calendar, table, summary, detail, timeline) and sandboxed iframes for custom components. Includes seven open questions for backend team review.

Updated

  • 23-thinklio-app-ui-specification-v03.md -- Version bump from v02 to v03 with backend integration addendum (role model standardisation, API endpoint mapping for all pages, Supabase Auth integration, onboarding flow, agent lifecycle states).
  • 00-document-index-v01.md -- Registered docs 31–33 across all sections. Updated doc 23 to v03. Total document count now 34 (docs 00–33).
  • README.md -- Updated document count to 34.

Key Decisions Recorded

  • Agent manifest is YAML-based, portable, and the same format for built-in, custom, and external agents (doc 33)
  • UI is a content type alongside text, audio, and documents; channels render what they support (doc 33, section 7)
  • Agent views use two data paths: conversational (agent-mediated, governed) and direct (API, authenticated but not governed) (doc 33, section 7.2)
  • Task agent designated as the proof of concept for agent UI views (doc 33, section 7.9)

Context

Three new documents and a version bump. Doc 31 specifies how the platform manages external service credentials and billing. Doc 32 defines the lightweight data structures (tasks, contacts, items, notes) that agents operate on. Doc 33 is the most significant addition: it proposes a universal agent definition format that works across all agent types (built-in, Studio compositions, and external autonomous agents), defines the external agent execution contract extending the existing Integration API, and introduces agent UI views as a first-class content type where agents can declare structured visual representations of their data. The task agent with kanban, calendar, list, and summary views is the designated proof of concept.

2026-03-20 -- Docs 22–30, unified app UI, Supabase platform, channels, email, predictive planning

Added

  • 22-thinklio-pricing-revision-v01.md -- Pricing tiers, credit model, LLM cost pass-through, plan structure and pricing page specification
  • 23-thinklio-user-app-spec-v01.md -- Full UI/UX prototype specification for the user-facing client app (navigation, layout, interaction patterns, design system)
  • 24-supabase-platform-database-auth-v01.md -- Replaces self-managed PostgreSQL and custom authentication with Supabase Cloud. Covers Supabase Auth integration (email/OTP, Google, Apple, SSO), managed PostgreSQL with native RLS via auth.uid(), account/team/user lifecycle, invitation system, role management, JWT enrichment, and account_id multi-tenancy via RLS. Renames "organisation" to "account" throughout the platform.
  • 25-channel-architecture-v01.md -- Channel identity linking and verification (user_channels model), connection lifecycle state machine, OTP verification flows, admin controls for channel suspension/revocation, multi-channel response delivery with status tracking, and agent channel context injection.
  • 26-feature-ideas-backlog-v01.md -- Living document for capturing uncommitted feature ideas and product concepts. Initial entry: MCP Server for Thinklio.
  • 27-email-channel-postmark-v01.md -- Bidirectional email channel via Postmark. Agent email alias model, per-account alias namespaces, inbound routing via Postmark Inbound webhooks, outbound construction with threading headers, email thread and message data model, domain configuration, security, and unsubscribe compliance.
  • 28-api-reference-accounts-onboarding-v01.md -- Concrete API endpoint specifications for account creation, onboarding flow, user/team management, invitations, and role model. Four-tier role system (owner, admin, editor, viewer) at both account and team level.
  • 29-docs-and-developer-ui-v01.md -- Thinklio website documentation and developer docs UI. Defines /docs (user) and /developer (API reference) routes, unified data model (doc_sections, doc_pages, api_endpoints, api_code_examples), two-column code panel layout. UI complete, backend integration pending.
  • 30-predictive-planning-system-v01.md -- Complete rewrite from outline to full specification. Defines what a "plan" is in Thinklio terms (canonicalised tool sequences from the Harness think step), what "success" means (composite signal from interaction state, step outcomes, user feedback), and the three-component architecture: Outcome Collector (event-driven, subscribes to existing Redis Streams), Score Service (internal API with Redis cache, sub-5ms p99), and Learning Engine (background Bayesian updates with hierarchical priors at four levels: global, account, agent, context). Phase 1 (implement now): data collection, Beta-Binomial scoring, Harness integration. Phase 2 (design now, implement later): gradient-boosted ML model with score blending. All tables use account_id scoping with RLS. Includes score decay, de-identified global priors, opt-in/opt-out governance, and data retention policies.

Replaced

  • 23-thinklio-app-ui-specification-v02.md -- Replaces 23-thinklio-user-app-spec-v01.md. The separate admin and client apps have been merged into a single unified app at app.thinklio.ai. New spec covers: agent gallery with four tabs (active, available, studio, installed), Agent Studio for custom agent creation, agent lifecycle model (origin types, deployment states), client-side agent onboarding with configurationSchema, Predictive Planner organisation opt-in/out setting, outcome feedback (thumbs up/down) on agent messages, artefact cards, and completed jobs. Also documents the full technology stack, component library, Zustand stores, file structure, and responsive behaviour for the merged app.

Updated

  • 00-document-index-v01.md -- Registered docs 22–30, updated doc 23 to v02 with new title and expanded authority/dependency entries. across all sections (registry, layers, authority map, dependency map, reading order, selective reading, update triggers). Added Layer 5 (Client Applications) and renumbered subsequent layers. Added update triggers for database/auth platform changes and channel modifications. Total document count now 31 (docs 00–30).
  • README.md -- Updated document count to 31, restructured the contents section, added consuming projects table.

Key Decisions Recorded

  • Supabase Cloud adopted as platform database and authentication provider (doc 24)
  • "Organisation" renamed to "account" across the platform (doc 24, section 3.3)
  • Channel identity model separated from platform authentication (doc 25)
  • Agent email aliases scoped per account, routed via sender identity lookup (doc 27)
  • Postmark selected for both inbound and outbound agent email (doc 27)
  • agents.thinklio.com subdomain recommended for initial email deployment (doc 27)
  • Four-tier role model (owner/admin/editor/viewer) for accounts and teams (doc 28)

Context

Nine new documents added in this batch. Docs 22 and 23 were produced in earlier sessions but not yet registered in the index. Docs 24 and 25 came from an architecture session that moved to Supabase Cloud for database and auth, and defined a proper channel identity model. Doc 26 is a lightweight backlog for feature ideas. Doc 27 extends the channel architecture with bidirectional email via Postmark and the agent alias model. Doc 28 provides concrete API endpoint specifications for the account and team management flows introduced by doc 24. Doc 29 specifies the website documentation UI (user-facing and developer docs). Doc 30 describes a predictive planning system for agents to learn from past executions and improve plan selection over time. Three documents that were previously all numbered 28 were renumbered to 28, 29, and 30; the predictive planning doc also had its filename corrected to include the v01 version suffix.

2026-03-14 -- Document Set v0.2.0

Added

  • 15-job-system-agent-composition.md -- Job system for deferred and long-running work, agent-as-tool composition model, observer pattern, execution modes, delegation governance, Agent Studio concept, per-assignment tool restrictions, scenario walkthroughs
  • 16-external-api-strategy.md -- Three API surface strategy (Channel API, Platform API, Integration API), cross-cutting concerns (auth, governance, cost attribution, versioning), design implications for existing architecture

Updated (cascading from docs 15 and 16)

05-data-model.md (v0.2.0) - Added Job, Subjob, and JobObserver entities - Added agent as a tool type (alongside internal and external) - Added tool_restrictions field to AgentAssignment - Added parent_interaction_id and delegation_depth fields to Interaction - Added execution_mode and job_id fields to Step - Added default_execution_mode and registered_by fields to Tool - Added delegation_config field to AgentTemplate - Extended failure reasons to include delegation_depth_exceeded and delegation_cycle_detected - Updated knowledge isolation rules for delegate agents - Updated data lifecycle tables for jobs and subjobs - Updated GDPR deletion procedures to include job observer cleanup

06-persistence-caching.md (v0.2.0) - Added PostgreSQL schema for jobs, subjobs, and job_observers tables - Extended interactions table with parent_interaction_id and delegation_depth - Extended steps table with execution_mode and job_id - Extended tools table with type 'agent', default_execution_mode, and registered_by - Extended agent_assignments table with tool_restrictions - Added agent_templates table with delegation_config - Added RLS policies for jobs - Added Redis key patterns for active job store - Added job lifecycle documentation (active in Redis, terminal flushed to PostgreSQL) - Added operational store cache pattern for active jobs - Added job archival SQL - Added indexes for parent interactions, job references, and job events - Updated monitoring metrics to include job system and flush latency

07-event-system-harness.md (v0.2.0) - Added job-related event types (job.created, job.dispatched, job.state_changed, job.resolved, job.failed, job.cancelled, job.timed_out) - Added agent service subscription to job notification events - Documented three step execution modes (immediate, deferred, interactive) with mixed mode support - Extended harness executor to handle deferred dispatch, job creation, and execution mode routing - Added dispatchDeferredWork function - Added resolveExecutionMode function - Added follow-up interaction trigger mechanism (HandleJobNotification) - Updated interaction lifecycle diagram to show deferred and follow-up flows - Extended failure reasons in error_data schema - Updated timeout documentation to distinguish immediate vs deferred step timeouts

09-api-contracts.md (v0.2.0) - Restructured around three API surfaces (Channel, Platform, Integration) - Added Channel API endpoints (send message, get interaction, get history) - Extended Platform API with job dispatch, job status, job results, job cancellation, and observer registration endpoints - Added bulk knowledge import endpoint - Added delegation-related fields to agent management endpoints (tool type, assignment tool_restrictions) - Added Integration API section (tool registration, tool execution contract, event subscription) - Added webhook delivery service description - Extended internal tool service API with delegation chain, delegation depth, and assignment tool restrictions - Extended internal usage service API with parent_interaction_id and job_id - Extended internal context service API with job_data for follow-up interactions - Updated contract change policy for independent surface versioning

03-prd-specification.md (v0.2.0) - Added product principle 6 (simple agents pay no complexity tax) - Added FR-01.5: Agent Composition (Agent Studio) - Added FR-04.6: Step Execution Modes - Added FR-05.1: agent tool type and dynamic registration - Added FR-05.2: per-assignment tool restrictions in policy evaluation - Added FR-06.5: Delegation Governance - Added FR-07: Job System (FR-07.1 through FR-07.4) - Replaced FR-09 (API) with FR-10 covering three API surfaces (FR-10.1 through FR-10.4) - Updated success criteria for Phases 3 and 4 to reflect job system and composition - Updated NFR-01 with job dispatch latency target - Updated NFR-04 with delegation chain validation - Updated NFR-06 with delegation chain tracing and job metrics

04-system-architecture.md (v0.2.0) - Added internal/jobs and internal/delegation packages to monorepo structure - Added admin/ directory description (includes Agent Studio) - Extended gateway service with APISurfaceRouter and WebhookDelivery - Extended agent service with DeferredMode, JobNotificationHandler, JobStore - Extended context service with JobContextLoader - Extended tool service with AgentExecutor, DelegationDepthRule, DelegationCycleRule, AssignmentRestrictions, HealthMonitor, CircuitBreaker - Extended queue service with JobTimeoutMonitor - Extended usage service with delegation cost rollup - Updated policy decision flow to include assignment restrictions and delegation rules - Added job-related event types to event type list - Added service-to-service pattern for Agent to Job Store (Redis) - Added configuration fields for job system and delegation - Updated logging fields for delegations and jobs - Updated metrics for job system

08-security-model.md (v0.2.0) - Added security principle 6 (delegation does not escalate) - Added job data and delegation chains to asset table - Added malicious delegate agent and malicious external tool to threat actors - Added delegation escalation and external tool injection to attack vectors - Restructured authentication section around three API surfaces - Added assignment-level authorisation (four-level model instead of three) - Added per-assignment tool restrictions documentation - Added delegation security section (depth limits, cycle detection, permission narrowing, context isolation) - Added external tool security section - Added Integration API rate limiting - Added job dispatch rate limiting - Updated GDPR section for job observer cleanup

10-implementation-plan.md (v0.2.0) - Added Phase 4: Jobs & Composition (between Multi-Tenancy and API & Channels) - Renumbered Phase 4 (API & Channels) to Phase 5 - Renumbered Phase 5 (Production Hardening) to Phase 6 - Phase 3 extended with per-assignment tool restrictions - Phase 4 includes job system, deferred execution, agent-as-tool delegation, delegation governance, Agent Studio - Phase 5 restructured around three API surfaces (Channel, Platform, Integration) - Phase 6 extended with job system resilience, delegation chain testing, external tool security - Added risks: job system complexity, delegation chain bugs, external tool reliability - Updated future phases with composed agent blueprints and delegation chain analysis

11-decision-log.md (v0.2.0) - Added ADR-012: Job System for Deferred and Long-Running Work - Added ADR-013: Agent-as-Tool Composition Model - Added ADR-014: Three External API Surfaces - Added ADR-015: Redis as Operational Store for Active Jobs - Added ADR-016: Per-Assignment Tool Restrictions

02-architecture-overview.md (v0.2.0) - Extended gateway service description with API surface routing and webhook delivery - Extended agent service description with delegation and job system - Extended context service description with job context injection - Extended tool service description with three tool types, delegation governance, dynamic registration - Extended queue service description with job timeout monitoring - Extended usage service description with delegation cost rollup - Added step execution modes section - Added job system section - Added agent composition section - Extended knowledge architecture with delegation isolation - Extended tenancy model with per-assignment tool restrictions - Extended API architecture with three surfaces - Extended security architecture with delegation security - Updated technology stack (Redis role includes job store)

01-product-overview.md (v0.2.0) - Added agent composition section (Agent Studio, delegation, composition) - Added deferred work and long-running tasks section - Extended governance section with delegation limits and deferred work cost tracking - Extended service provider persona with Integration API - Extended integration section with three API surfaces - Updated "What's Next" with job system, agent composition, and composed agent blueprints

12-user-guide.md (v0.2.0) - Added Agent Composition and Delegation section - Added Agent Studio section (skeletal) - Added Jobs and Deferred Work section - Extended administrator getting-started with composition and delegation - Updated agent capabilities list with delegation and deferred work - Extended knowledge section with delegation isolation explanation - Extended governance section with delegation limits - Extended tips with progress checking for deferred work - Updated troubleshooting with job system issues

14-deployment-administration.md (v0.2.0) - Updated system components table with delegation and job responsibilities - Added job system environment variables - Extended admin dashboard sections with Agent Studio, job monitoring, delegation graph - Added job operations CLI commands - Updated backup notes for active jobs in Redis - Updated upgrade notes for Redis persistence of active jobs - Extended vertical scaling indicators with Redis job store memory - Extended monitoring metrics with job system and webhook delivery - Added job system alerts (timeout rate, Redis memory, webhook failures) - Extended routine maintenance with terminal job archival - Added job system troubleshooting section - Updated security operations with external tool deregistration and job cancellation on kill switch

Key Decisions Recorded

  • ADR-012: Job system with Redis operational store and PostgreSQL durable store
  • ADR-013: Agent-as-tool composition model (agents registered as tools, same governance path)
  • ADR-014: Three external API surfaces (Channel, Platform, Integration)
  • ADR-015: Redis as operational store for active jobs (flush to Postgres on terminal)
  • ADR-016: Per-assignment tool restrictions (narrow only, never widen)

Context

Documents 15 and 16 produced from a follow-up design session extending the initial architecture with: - Deferred and long-running work support via job system - Agent-to-agent delegation via agent-as-tool pattern in the existing tool registry - Observer model decoupling job creation from consumption - Three explicit step execution modes (immediate, deferred, interactive) - Per-assignment tool restrictions for context-specific capability narrowing - Three distinct external API surfaces designed as first-class architectural concerns - External tool dynamic registration via Integration API

All existing documents (01 through 14) updated to reflect the implications of these two new documents.

2026-03-13 -- Document Set v0.1.0 (Initial)

Created

  • 14-deployment-administration.md -- Deployment, scaling, admin dashboard, maintenance, and troubleshooting guide
  • 01-product-overview.md -- Non-technical stakeholder description of Thinklio
  • 02-architecture-overview.md -- Technical stakeholder architecture description (no proprietary detail)
  • 03-prd-specification.md -- Product requirements and specification
  • 04-system-architecture.md -- Full internal system architecture
  • 05-data-model.md -- Entity relationships and knowledge model
  • 06-persistence-caching.md -- PostgreSQL schema, Redis caching, data lifecycle
  • 07-event-system-harness.md -- Event bus design and durable execution harness
  • 08-security-model.md -- Trust model, authentication, authorisation, data isolation
  • 09-api-contracts.md -- External and internal service API definitions
  • 10-implementation-plan.md -- Phased build-out roadmap
  • 11-decision-log.md -- Architectural decision records (ADR-001 through ADR-011)
  • 12-user-guide.md -- Initial user guide skeleton
  • 13-changelog.md -- This file

Key Decisions Recorded

  • ADR-001: Platform named "Thinklio"
  • ADR-002: Agents as first-class platform entities (Model C)
  • ADR-003: Four-layer knowledge model (agent, org, team, user)
  • ADR-004: Step-level state machine harness (created to running to success/failed)
  • ADR-005: Go for all services
  • ADR-006: Redis Streams directly (no separate event bus service)
  • ADR-007: Single Redis instance initially
  • ADR-008: Hetzner/Coolify deployment
  • ADR-009: Agent capability levels as policy configuration
  • ADR-010: No calendar-bound timeline
  • ADR-011: Built from scratch, not migrated from MyAI

Context

Document set produced from comprehensive design session covering: - Review of original MyAI audit documents (6 documents) - Reframing from migration plan to new platform architecture - Tenancy model design (agents as independent entities, assigned to contexts) - Knowledge layer design (four layers with privacy, precedence, portability rules) - Harness design (step-level state machine with durability and cost tracking) - Agent capability level progression (tools to workflow to experimental to learning) - Implementation phasing (foundation-first, no fixed dates)

Entries are added as documents are updated, decisions are made, or implementation progresses.