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).

Two more pieces of work run inside Phase 3, from the One Repo PRD. Lesson 0 moves Arkive into the Sidekick repo before lesson 1, so Synergy is built and recorded in one repo. The site lessons S1 to S7 rebuild the public site and move it to ossidekick.com, between Checkpoint 3a and 3b (Pratik, 2026-11-05). Just before them, lesson M1 replaces Mantine with native ui primitives (Pratik, 2026-11-06), and the i18n lessons I1 and I2 replace @sidekick/copy with next-intl and make the App i18n-ready (Pratik, 2026-11-05). The site is temporary and stays English with no catalogs (D256).

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
(content/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 docs PR, so later lessons build on what was built.
• Every lesson ends with one docs 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 pnpm turbo run build --filter=@sidekick/www (Astro and both gates).

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.

Native UI lesson

After Checkpoint 3a and before I1 (Pratik, 2026-11-06), the App leaves Mantine for ui primitives on native HTML (Native UI, D255), and ui gets its token contract and Sidekick's theme (Design tokens, D254). It comes first so I1 rewrites copy on Sidekick's own components with no Mantine direction provider, and S1 reuses the tokens. About two days. The coach writes the ui components and Pratik reviews them; Pratik rewires the screens.

M1's docs PR removes Mantine from every live doc it makes false: the agent guide (the depth list and the native-first rule), best practices, the tag taxonomy, Technology stack, CSS modules (the no-mantine-style-props line), Testing layers, Internationalization, the living plan and the Zinsser plan, and Sidekick's README. Finished plans, tasks and walkthroughs keep their historical text; the Front Door walkthrough gets a post note that Mantine was removed in M1. The same holds for every lesson: its docs PR updates each live doc the lesson makes false (Pratik, 2026-11-06).

i18n lessons

After Checkpoint 3a and before S1 (Pratik, 2026-11-05), Sidekick becomes i18n-ready as Internationalization (D240 to D248) describes: still English only, but a new language is new catalogs plus config. The App's screens from M1 are the first real user, then the Sneak Peek Link's words in 3b; lessons 1 to 13 have no UI, so nothing earlier needs it. The site stays out of it (D256). Each lesson gets a brief before it starts, written from what was built before it.

I1's docs PR also points the docs that name packages/copy at the new home: the Synergy overview (D201), the spec's relation-type labels, the agent guide, best practices (D23), the harness notes, the architecture invariants and lesson 1's move list (if lesson 1 has run, its walkthrough gets a post note). It retires Centralized Copy (status: deprecated) and adds a post note to the Front Door walkthrough's Task 1.17.

Site lessons (the redesign)

After Checkpoint 3a and the i18n lessons, and before 3b (Pratik, 2026-11-05), the public site is rebuilt from the design handover and moves to ossidekick.com, as the One Repo PRD and the spec's One Repo section describe. Until then arkive.blog keeps the current design, served from Sidekick since Lesson 0. Each lesson gets a brief before it starts, written from what the previous one built, and each keeps the sitemap diff empty. The site is temporary (D256): global stylesheets, English with no catalogs, and the contracts of D257 kept.

The sidekick:<name> components plugin and its map (D260) are built in whichever lesson first has an entry that needs one, not before.

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/app 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, plain link and words props, translateRefs, the App's client wrapper for the editor, and words from the providers' catalogs and the synergy catalog through message references (D250, D251), 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/app 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/app 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. Since lesson 0 the site is the Worker sidekick-www, built from the repo root with the root .nvmrc and engines 24.x (Hosting and domains).
• 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).
• Lesson 0 runs before lesson 1 (Pratik, 2026-11-03). Lesson 1's git mv work and the live recordings happen in the merged repo, and lessons 1 to 13 keep their numbers.
• The site lessons come after Checkpoint 3a (Pratik, 2026-11-05). After Lesson 0 the current site keeps working, so Synergy starts at once; the checkpoint is a natural break, and 3b is planned from what 3a built while the site is rebuilt.
• i18n-ready before the site lessons (Pratik, 2026-11-05). @sidekick/copy gives way to next-intl in the App and use-intl on the site, still English only: locale from the person in the App with no URL locales, catalogs colocated per package with shared words in @sidekick/i18n, logical CSS, an Arabic mock locale on dev-only test pages, and lint for all of it. Two lessons, I1 and I2, between Checkpoint 3a and S1, because the site lessons are the first to write interface text (Internationalization).
• The Phase 3 additions system-design pass (Pratik, 2026-11-06, handover): the site is temporary and exempt from the App's styling, i18n and strictness rules (D256), so the site no longer uses use-intl; Mantine leaves the App in a new lesson M1 before I1 (D255).
• 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.