Synergy

Synergy is Phase 3: how any entity in any module links to any other. Scope: the entity index and version log, links and relation types, staleness, lists, mentions and anchors, delete and restore, and tags, built in two parts (3a the store and its API, 3b resolving and rendering links).

Milestone: Synergy is live in packages/platform/synergy. Any entity can be linked to any other entity and tagged, links stay true when their targets change, and every module renders a link the same way. It is proven across a module boundary by two mock providers, before Taxila becomes the first real tenant.

Learning payoff: graph modelling in Postgres (recursive CTEs, composite foreign keys, partial unique indexes), concurrency (advisory locks, stale-write checks, race tests with two connections), an outbox, per-package migrations, layered packages enforced by lint, and contracts shared by server and browser.

The design is settled: the Synergy PRD and spec say what Synergy does, and the Synergy system design (1.3.0) and its decisions say how. This plan turns that design into lessons.

Phase 3 has two parts. 3a builds the store, its rules and its API. 3b resolves and renders links. Only 3a is planned in lessons now: what 3b needs depends on how 3a gets built, so Checkpoint 3a plans 3b (Pratik, 2026-11-01).

Lessons (3a: the store and its API)

Lessons run one at a time, in this order, each in its own thread, on Pratik's Mac through Remote Control. A lesson starts only after the previous lesson's PRs merge. Each one ends at a check Pratik can run, and depends only on the lessons above it.

To start a lesson, open a new thread and paste this, changing the lesson number:

Coach me through Phase 3 lesson 1. Read AGENTS.md, the Phase 3 plan
(docs/04-phases/03-synergy/00-plan.md) and that lesson's
brief (the plan's Lessons table links each one) before we start.

How we build

Phase 3 follows Phase 2's how we build, in the style Pratik chose from Phase 2 lesson 4 on, and the agent guide's Working with Pratik:

• Pratik writes the code. The coach gives exactly what to write for one small piece, then explains it below: what each part does, why, the concepts, the consequences and the alternatives rejected. No quiz questions. Design questions come as recommendations; Pratik decides. A brief's "good to write yourself" steps are ones worth designing before seeing the coach's version.
• Explain backend mechanisms from first principles: the concept, then the problem as a practical story, then the fix, then ask to agree.
• One piece at a time. Nothing lands in the repo until Pratik agrees to it. Pratik commits, pushes and opens the PR unless they ask otherwise.
• Tests go through the guarded API wherever a route exists (testing layers). Whether a pure function also gets a unit test is Pratik's call in each lesson; the briefs point out the candidates.
• The design can change. When Pratik's design wins in a lesson, the coach updates the Synergy overview (or the decision it touches) and bumps its version in the lesson's arkive PR, so later lessons build on what was built.
• Every lesson ends with one arkive PR: a walkthrough at 04-phases/03-synergy/00-lessons/lesson-N-<slug>/01-walkthrough.md, a learnings note at 04-phases/03-synergy/00-lessons/lesson-N-<slug>/02-notes.md (publish: false) holding everything explained in the lesson, the lesson marked ✅ in the table above, and a "Handover from lesson N" section in the next brief. A fix that changes an earlier lesson's or phase's result adds a post note to that walkthrough. Verify with npm run build (Astro and the privacy gate).

Exit criteria

From scope and phases. Integration tests through the public API only prove that:

Checkpoint 3a re-proves the 3a rows on main. The phase closes with a close-out lesson at the end of 3b, like Phase 2's lesson 8.

3b: resolving and rendering links (planned at Checkpoint 3a)

Candidates from the planning handover, to be merged, split or reordered at the checkpoint. None has a brief yet.

• One React: a pnpm catalog for react, react-dom and @types/react; apps/web uses catalog:; @sidekick/ui and @sidekick/synergy list React as a peer (decision). Check: pnpm why react resolves to one version.
• Resolve and the React registry: resolve on LinkableTypeServer (batched per provider), LinkableTypeReact, the registry assembling both maps, POST /api/synergy/links/resolve, the resolved-link zod schema frozen in /contracts.
• Sandbox renderers: resolve and render for the sandbox notes and tasks.
• Sneak Peek Link: the /react component with pure render, an injected resolveLinks transport and labels from packages/copy, tested in Vitest browser mode with Testing Library and MSW.
• Render cache and backlinks: cache keyed by (entity, content_seq, display type); backlinks list live links only.
• Links by type across the graph: GET /api/synergy/links?type=, cursor-paged, with a (user_id, type) index, so one list shows every open violation from any module (decision).
• Search: simple full-text plus pg_trgm on display names, btree_gin indexes leading with user_id, GET /api/synergy/search, and the test pinning spec story 71 (trigram word_similarity).
• Playground and the RLS uuid fix: a playground page in apps/web behind the sandbox entitlements, built on the public API; Sidekick migrations 0002 and 0007 compare uuids directly instead of casting to text.
• A test that no API response carries label text (keys, never copy), once the resolved link exists.

Decisions made while planning

Settled with Pratik on 2026-10-31 and 2026-11-01. Each can be revisited in its lesson.

• The mock providers are feature packages, not ops. Nothing may import packages/ops, which holds the privileged postgres client, so neither apps/web nor the registry could use mocks there. They live in packages/features/_sandbox/notes and packages/features/_sandbox/tasks: the underscore marks them dev-only, and retiring them deletes one folder. Two packages, not one, because a single provider and entitlement can't prove that disabling a module locks its links: revoking it would hide the note too. Provider and feature keys are sandbox-notes and sandbox-tasks. This overrides the PRD and spec (provider ops, entitlement sandbox).
• Routes in every lesson, not one API lesson at the end. Each lesson adds the routes for what it builds, and its tests go through them. Lesson 3 is the exception: entities are created through provider routes, which arrive in lesson 4, so lesson 3 tests the repository directly.
• Lesson size. The handover's 10 candidates for 3a became 13 lessons: relationships split into links, staleness, and lists with supersede; the save call split into mentions and anchors; the API lesson spread over the others; the outbox moved up so each later lesson writes its own events.
• The server half of the registry lands in 3a (lesson 6), because POST /links refuses locked and only a type's registration names its entitlement. addAnchor joins it in lesson 10; resolve and the React half are 3b.
• One Phase 3, with Checkpoint 3a. 3b is part of Phase 3's exit criteria, not a new phase, because Phase 4 needs its renderers and a new phase would renumber Phases 4 to 12. 3b is planned at the checkpoint.
• Delete models are chosen, not drifted into (Pratik, 2026-11-01). Lesson 3 revises row-level security and soft-delete support into explicit variants, with a guide for choosing among hard delete, soft delete with tombstones hidden (the default) and soft delete with tombstones visible. The guide lists every table and its model; each Drizzle schema file and each new migration names its model. Applied migrations are not edited.
• Cloudflare builds arkive on Node 24. undici 8 (through Astro's unifont) needs Node 22.19 or later, and Pages built on 22.12. Cloudflare reads the version from the repo's .node-version (was 22, now 24), not from a dashboard setting; arkive's engines asks for >=22.19.0.
• violates and exception-to are in Phase 3 (Pratik, 2026-11-01). Dogfooding Synergy on Arkive found two gaps in the vocabulary: no directed violation and no exception. Both types are seeded in lesson 6. A violation has no status: unlinking resolves it, retyping it to exception-to waives it, and that retype takes a fresh snapshot. The graph-wide list of links by type (every open violation, from any module) is a 3b candidate; issue tracking is post-MVP (Violations and exceptions).
• Deferred to Checkpoint 3a: whether the shared editor moves ahead of Taxila's passages (Phase 4) or the passages move to Phase 5, and which lessons retire the sandbox providers. Both shape Phase 4, not 3a; mock note bodies are minimal Tiptap JSON either way.

Handover from system design

Every item from the system-design session, and where it is built.