Novansa Pilot Build Plan¶

Status: approved 2026-10-05. Implements part of Work Model & IA (proposal) (§13 step 2–3) for a narrower first audience. Decisions D1–D6 are recorded in §3.

1. Goal¶

Andrew and Antonette stop using Notion, and each project's lists (roadmaps, tech debt, backlog, releases) are visible and kept current in Thinklio.

Social content is not migrated: the social boards are retired and that work moves to Ripplebase (decided 2026-10-05).
Ripplebase stays separate. External Ripplebase reviewers keep working in Ripplebase; deeper Thinklio–Ripplebase integration comes after this pilot.
Linear is cancelled (2026-10-05): planning and progress live in each project, and a separate tracker was another app to look at. So the repos keep owning their lists. Thinklio reads them, shows them read-only and keeps their history (D1); nobody changes how they work.

Done means: Notion is cancelled; the two of us open Thinklio first for tasks, meetings, docs and project lists; and every active repo's lists appear in Thinklio within a minute of a push.

2. What moves where¶

From a read-only inventory of the Notion workspace on 2026-10-05. Users: Andrew and Antonette are active; two older accounts have no edits since November 2025.

Notion	Size, last activity	Destination
Tasks Tracker (Novansa)	80 rows, 22 open; to 5 Oct	Tasks, in the matching space (its brand tags map to spaces)
Personal Tasks (Andrew, private)	27 rows, 18 open; to Mar	Tasks, Andrew's personal space
Internal Calendar	33 meetings with AI notes and Fathom links; to 5 Oct	List: Meetings (calendar view), notes in each record
Document Hub	20 docs; to 5 Oct	Wiki pages in the matching space
SOPs (+ nested Resources)	7 docs; to Sep	Wiki pages, Novansa space
FALL Marketing tree	6 section pages, 2 technical pages, Pilbara OH page; Sep	Wiki pages, FALL space
FALL Marketing Decision Log	database	List: Decisions, FALL space
Couple Tools Newsletters	33 rows; to Sep	List: Newsletter, Couple Tools space (its relations to Twikka databases are dropped)
FALL Image Options (nested in a task)	65 rows with files; Jun–Jul	List: Blog images, FALL space
Thinklio Home, Foot Scan App	link hubs, brand PDF, icons	Wiki pages + files
Brand assets (Couple Tools logos, PDFs)	files	Files on wiki pages
Home dashboard	linked views, synced block	Not migrated; replaced by My work and space pages
Projects, Goals Tracker, Couple Tools Plan	10 / 3 / 20 rows; Jan 2026	Archive (stale; see D4)
All social boards, Social Ideas, Reel Gallery, Ripplebase Prompts	255 rows across boards	Ripplebase (not migrated)
Twikka teamspace, Clindice pages, 2021–23 second brain, stale private pages	mostly 2025 or older	Archive

Archive means a full Notion export (Markdown & CSV with files), stored in Drive with a note in the Operations space wiki saying where. Nothing archived is imported.

Before cutover, check in the Notion app (the connection cannot see them): database automations and buttons (FALL Social Projects creates "New post" rows on a schedule; the "Alignment" tasks look recurring), and whether the LeadConnector (GHL), Make or Framer integrations write into Notion. The task "Log in for socials Antonette" probably holds credentials: move them to 1Password, not Thinklio.

Lists from the repos (read-only in Thinklio)¶

Repo source	Becomes
Ripplebase `apps/web/docs/tech-debt.md` (bugs, dead code, refactors, done)	Tech debt, Ripplebase space
Couple Tools `TECHNICAL_DEBT.md` (TD-1–12), `BACKLOG.md` (BL-1–9)	Tech debt and Backlog, Couple Tools space
Couple Tools `ROADMAP.md` release train (R0–R6)	Roadmap, Couple Tools space
Twikka `04-build-plan.md` "Open to-dos"	Open to-dos, Twikka space
FALL handover open items, Clindice migration phases	Open to-dos in those spaces
Thinklio `13-implementation-plan-and-status.md`, `decision-log.md`	Roadmap and Decisions, Thinklio space

Operations items (credentials, DNS, Coolify, Sentry) are not in any one repo's list today. They become an editable Renewals list and Tasks in the Operations space, with secrets linked from 1Password (D5).

3. Decisions needed¶

D1. The repos own their lists; Thinklio reads them and shows them read-only. Decided 2026-10-05. Claude sessions keep updating the Markdown in the same commit as the work, which already works. Thinklio refreshes on every push, keeps each list's history from the commits, and shows lists side by side across projects. Details in §5.3. Writing back from Thinklio (for example by opening a pull request) is not planned.
D2. Membership stays on Clerk organisations. Decided 2026-10-05. Moving membership into account_members / account_invitations (copying Ripplebase's tables) waits until more users join, and ideally lands together with the move to Convex Auth v2. D3–D6 were accepted with the plan on 2026-10-05.
D3. The MCP server is Go in thinklio-services, copied from the Notion service and calling Convex /v1 routes, matching every other MCP service and its deployment.
D4. Notion's Projects, Goals and Couple Tools Plan databases are archived, not imported. All three stopped in January; spaces now do the job Projects did.
D5. Secrets stay in 1Password. Thinklio records link to 1Password items (an external field, onepassword.item), and Renewals tracks expiry and owner. Values never enter Thinklio. A Thinklio vault (docs/secrets-vault-specification.md) is revisited only if a customer needs one.
D6. Spaces: Novansa, Operations, Thinklio, Ripplebase, Twikka, Couple Tools, Clindice, FALL (client work, no patient data), plus a personal space for each person. These match the Notion teamspaces.

4. Scope¶

4.1 In¶

Spaces with members; a personal space for each person.
Tasks in spaces, with a parent record, person assignees, in_review status and recurrence; My work.
Lists: collections, records, table / board / calendar views, group counts, CSV and Notion import.
Wiki: pages in a tree per space, Markdown editing, files, search, history.
The change log: one write path for tasks, records and pages, with history and undo on each.
Per-user API keys, /v1 routes and the Thinklio MCP server.
Navigation: My work, Spaces, Search, Settings (Briefing, Activity and agent-owned views are hidden, not deleted).

4.2 Out (comes after)¶

The Inbox and attention model, agent proposals and routines, Ripplebase integration, links beyond task-to-record parents, rollups, formulas, list rules, templates with task blueprints, per-space task fields, space policies, the Flutter app, leaving Clerk organisations, Cliniko patient names, regional deployments.

4.3 Small calls made here¶

Totals: group counts and column sums computed at read time; lists in this pilot hold hundreds of records at most. The Aggregate component is added when a list outgrows that.
Field types for the pilot: text, longtext, number, currency, select, multiselect, status, date (with optional end), checkbox, person, url, email, file, external (1Password item, GitHub link), and the system fields. relation and rollup follow with links.
Cross-project views: each repo list lives in its own space. "Changed this week" is the one cross-space view in the pilot; views such as "all open tech debt by size" come with portfolio views.

5. Phases¶

Each phase ends with something we use the next day.

5.0 Groundwork (about 2–3 days)¶

The code survey on 2026-10-05 found the foundations below need fixing first.

One task write path. Tasks are written from three places (tasksCrud.ts, tasksCrud.ingestTask, agentCrud.ts), and agentCrud.completeTask skips recurrence. Route all of them through one internal helper, which is where the change log attaches in 5.1.
Add the Migrations component (@convex-dev/migrations) for the widen–backfill–narrow changes to tasks.
Typecheck baseline. 76 tsc errors already exist, mostly createTool signature changes in tools/*.ts after an @convex-dev/agent upgrade. Fix them, so new work is checked cleanly and the agent tools match what the MCP server exposes.
Generic view layer. The task views are hard-coded to tasks. Build table (on @tanstack/react-table, already installed), board (add @dnd-kit) and calendar views driven by field definitions, used by both tasks and lists.

5.1 Spaces and tasks (about 1 week)¶

Schema: spaces, space_members (proposal §14); changes (proposal §14, used here with status applied / undone only); tasks widened with spaceId, parentType / parentId, assigneeType / assigneeId, status in_review; task_lists kept as sections within a space.
Write path: the helper from 5.0 writes the task and a changes row in the same transaction. Task history tab with undo for the last change.
Access: space membership checked in every task query and mutation (today nothing checks team-scoped access).
Web: Spaces in the sidebar; a space page with Tasks (table, board, calendar) and an Overview (pinned wiki page, open counts); My work grouped as overdue, today, this week, later, no date; quick add with space picker. listTasks gets pagination and a space filter (it is capped at 50 today).
Import: Notion Tasks Tracker and Personal Tasks (brand tag → space; Notion people → Clerk users; descriptions and page bodies → task description). Recurring tasks are re-created by hand with Thinklio recurrence.
Seed: the spaces in D6.
Use from here: Antonette and Andrew move daily tasks to Thinklio.

5.2 Lists, read-only first (about 1 week)¶

Schema: collections, collection_records, collection_views (proposal §14). Field IDs are stable; renaming never touches records. A collection has a source: manual, or repo (with repository, path, section and the last commit read). Records in a repo collection are read-only in the UI.
Record page: fields in schema order; notes (Markdown); history from changes; for repo records, a link to the file on GitHub at the row's line.
Views: table, board (group by select or status), calendar (by a date field); filters, sorts, visible fields, group counts and sums; saved per list, shared by default. Each space shows its lists; Changed this week shows recent changes across every list a person can see.

5.3 Project lists from the repos (about 1 week)¶

The first visible win: every project's tech debt, backlog, roadmap and open to-dos in one place, current within a minute of a push.

Each repo declares what Thinklio reads in a thinklio.yml at its root, so the repo stays in charge and a Claude session can add a list by editing it:

space: ripplebase
lists:
  - name: Tech debt
    file: apps/web/docs/tech-debt.md
    key: ID                # the column that identifies a row (B53, D10, R12)
    done_sections: [Done]  # rows under these headings count as done

Parser (no LLM). Markdown tables become records: the header row becomes fields, cells stay Markdown, the nearest heading becomes a Section field, and columns named Status, Priority or Size become select fields. Numbered or bulleted lists also work: a bold lead becomes the title and the number or an explicit ID becomes the key. A row under a done section, or wrapped in ~~strikethrough~~, is marked done.
Refresh. A GitHub push webhook (POST /github/push on Convex, HMAC-verified) re-reads only the declared files that the push changed, at that commit. An hourly sweep compares each file's blob SHA and re-reads only what moved, in case a webhook was missed. Each list has Refresh now.
History. Each read is compared with the records by key: new rows are created, changed rows updated, missing rows archived. Every difference is a changes row with actor integration:github and the commit (SHA, message, author) as its source, so a record's history reads like "Moved to Done in abc123: fix FALL push guards".
GitHub access for the pilot: a fine-grained token with read-only Contents on the chosen repos (Convex env GITHUB_TOKEN) and one webhook per repo (secret in GITHUB_WEBHOOK_SECRET). A GitHub App replaces both when other accounts need it.
First repos: Ripplebase, Couple Tools, Twikka, Thinklio, FALL, Clindice. Twikka's numbered to-dos parse as they are; converting them to a table later is one commit.

5.4 Editable lists and Notion import (about 1 week)¶

Editing: inline cell editing, record create and archive, all through the write path with undo; field management (add, rename, change compatible type, archive).
Import: CSV, and Notion databases through the Notion API (the thinklio-services Notion service already reads data sources and page Markdown; the importer either calls it or ports the calls into a Convex action). Files are downloaded during the run, because Notion's file links expire after five minutes.
Lists: Meetings, Decisions, Newsletter, Blog images (from Notion); Renewals (new, Operations space, with 1Password links).

5.4 Wiki (about 1 week)¶

Schema: pages with account, space, parent, title, slug, Markdown content, position, archived; a search index on content filtered by space, and one on title. Revisions as changes rows, coalesced so continuous typing by one person within ten minutes makes one revision.
Editor: the Lexical editor with Markdown round-trip already in packages/ui (lexical-editor.tsx); apps/web takes @novansa/ui as a dependency. Paste and drop images and files to R2.
Pages: tree in the space sidebar, breadcrumbs, links between pages and to tasks and records ([[ picker), "linked from" at the foot of each page.
Search: ⌘K across tasks, records and pages in the spaces a person can see.
Import: Document Hub, SOPs, the FALL Marketing tree, Thinklio Home, Foot Scan App, brand files. Notion's /pages/{id}/markdown keeps headings, lists, tables and links; Notion AI meeting-note blocks may come through as plain text.

5.6 API keys and the Thinklio MCP server (about 1 week)¶

Less urgent now that the repos own their lists (D1). It lets Claude sessions read across projects and work with tasks and the wiki.

api_keys table: per user and account; stored as a SHA-256 hash with a visible prefix; name, last used, revoked. Created and revoked in Settings → API keys. This replaces the shared INGEST_API_KEY for new routes (the existing POST /v1/tasks keeps working until n8n is switched).
/v1 routes (Convex HTTP, ADR-029 envelope): spaces; tasks list, get, create, update, complete, comment; lists and records read; pages search, get, create, update. Writes go through the same helper, with the change's source { kind: "mcp", ref: "<client>" } and the actor as the key's user.
thinklio MCP service in thinklio-services, copied from services/notion: streamable HTTP at /mcp, the key passed as X-Thinklio-Api-Key, deployed at thinklio.api.thinklio.ai, added to registry.yaml.

5.7 Notion cutover (about 2 days)¶

Re-run the imports for anything changed since the first run.
Check the Notion automations, buttons and integrations listed in §2; move anything still needed.
Take the full Notion export into Drive; add the archive page to the Operations wiki.
One working week on Thinklio alone, with Notion read-only.
Cancel Notion.

Total: about six to seven weeks of build. Daily tasks move after 5.1; project lists are visible after 5.3.

Progress¶

5.0 Groundwork: done (2026-10-05, deployed). One task write path; backend typecheck 76 → 0; four agent bugs fixed (knowledge search, policy-blocked replies, retrier callback, key dedupe); convex-test with tests. Production Convex was found four months stale and brought up to date (it held no data to migrate). Two items moved: the Migrations component is not needed yet (production had no tasks to backfill, and new task fields are optional), and views driven by field definitions move to 5.2, where lists need them; 5.1 made the task views take their tasks as input instead.
5.1 Spaces and tasks: done and in production (2026-10-05). Spaces and members, personal spaces, space access on every task read and write, the changes log with history and undo, My work as the home page, space pages (list, board, calendar, activity, members), the Spaces sidebar. The eight pilot spaces are seeded in the Novansa account, and the 40 open Notion tasks are imported (22 from the Tasks Tracker into the matching spaces, 18 from Andrew's Personal Tasks into his personal space), each linking back to its Notion page. Antonette's 10 tasks wait for her account: once she signs in, run spaces:seedSpaces with her as a member and imports:assignImported. Assigning tasks to agents (assigneeType) moves to the assistant's first slice (personal assistant proposal A0).
5.2 Lists and 5.3 project lists: done and in production (2026-10-05). Lists with typed fields, saved views (table with groups and totals, board, calendar), record pages with history and undo, list templates (Renewals, Meetings, Decisions), and "Changed this week". Six repos are connected with push webhooks and an hourly sweep; each has a thinklio.yml. Live lists: Ripplebase Tech debt (137), Twikka Open to-dos (32), Thinklio Tech debt (18, from the new docs/tech-debt.md), Couple Tools Tech debt (12) and Backlog (9), FALL Outstanding (8), Clindice Open items (6). Couple Tools' roadmap (headings, not a list) is not read yet.
Repo ingestion as a module (2026-10-05). Generalised for any account: Repo Ingestion (proposal). Spec thinklio-ingest v1 published at /v1/ingest/spec with JSON Schemas and a guide; files can opt in with front matter (thinklio: { ingest: list } or thinklioIngest: true); each connected repo has a default space. Thinklio's own register now declares itself with front matter. Next for the module: the Thinklio GitHub App and a Connections screen (proposal I1).
Module architecture and 5.4 Wiki: done and in production (2026-10-05). Module Architecture (proposal) (draft ADR-040): object types with one contract (object registry), connectors in mirror/import/link mode feeding one bundle applier, capabilities and surfaces. Pages built as the first module: tree per space, rich and Markdown editing with autosave, files in R2, search, history and undo. The Notion connector (import mode) is deployed with its import plan ready; it runs once a Notion integration token is set (NOTION_TOKEN) and the pages are shared with it.

6. After the pilot¶

In order: the Inbox (Needs you, Today, Waiting on, What changed) and the morning brief; a Renewals watcher as the first routine; Google Workspace (calendar into Today); membership out of Clerk organisations and per-space roles, ahead of more users; then Ripplebase integration (its review, failed-job and delivery items in the Inbox; brands as spaces), starting with a signed activity feed on the Ripplebase side. Proposal §13 steps 4–7 follow.

7. Risks¶

Repo formats drift. A Claude session reshapes a table and the parser misreads it. Mitigations: thinklio.yml names the key column; a read that would archive more than a third of a list's records is held, and shown on the list as a warning instead of applied.
Stale project lists if a webhook fails silently: the hourly sweep, and each list shows the commit and time it was last read.
Scope creep toward Notion. Fixed object types only: tasks, list records, pages. No blocks, no databases inside pages, no inline views.
Notion AI meeting notes and Home's synced blocks do not import cleanly; meetings keep a link back to the archived export for the transcript.
Typecheck noise if the 5.0 cleanup slips; check new files individually until it is done.

Cross-references¶

Work Model & IA (proposal): the model this implements (§3–§6, §14 schema)
Adoption strategy: the List Manager design and success indicators
09 External API & Tool Integration: Platform API envelope, MCP services
Decision log: ADR-029 (Platform API on Convex), ADR-030 (MCP services)
thinklio-services/docs/51-tool-integration-developer-guide-v02.md, 52-mcp-credential-and-permission-model-v01.md, 54-service-registry-and-ci-v01.md (outside this repo)