@book.dev/sdk 1.76.1 → 2.0.0

package/dist/templates.d.ts

@@ -5,32 +5,59 @@ import type { StoredPage } from './types';
  * through the normal data APIs (no server involvement, same as the sample
  * document). Two shapes:
  *
- *  - **Block-doc artifacts** (the five showcases) ship a native block-editor
+ *  - **Block-doc artifacts** (the showcases) ship a native block-editor
  *    JSON projection in `blockdoc: {blocks}`. They lean on the whole editor:
  *    reactive inputs feeding *collapsed* live-code, status lights, info/link/
  *    tooltip cards, charts, progress bars, multi-column layouts, callouts, and
  *    `divider`/`notes` blocks so every page doubles as a slide deck with
  *    speaker notes (see blockeditor/present.ts).
- *  - **Databases** (roadmap, field map) ship a schema, views, and sample rows;
- *    they back the swimlane and map e2e fixtures.
+ *  - **Databases** (task board, reading list, roadmap, field map) ship a
+ *    schema, views, and sample rows; roadmap and field map back the swimlane
+ *    and map e2e fixtures.
  *
  * Ids are stable so the gallery, its i18n keys, and the e2e suite can reference
  * a template without depending on display strings.
  */
+/**
+ * What a template demonstrates, surfaced as gallery chips so the reader knows
+ * what a card is before inserting it:
+ *  - `interactive` — reactive inputs feeding live code, charts, status lights.
+ *  - `slides` — divider-cut slides with speaker notes (present-mode ready).
+ *  - `database` — a schema with views and sample rows.
+ */
+export type TemplateTag = 'interactive' | 'slides' | 'database';
 export interface PageTemplate {
     /** Stable identifier (i18n keys + tests hang off this). */
-    id: 'grocery-tracker' | 'task-board' | 'reading-list' | 'project-intake' | 'savings-planner' | 'roadmap' | 'field-map';
+    id: 'grocery-tracker' | 'task-board' | 'reading-list' | 'project-intake' | 'savings-planner' | 'roadmap' | 'field-map' | 'pitch-deck' | 'compound-growth' | 'team-status' | 'product-hq';
     /** Emoji shown on the gallery card and applied to the created page. */
     icon: string;
     /** Canonical (English) page name; suffixed when it collides. */
     pageName: string;
-    /** Creates the page (and database, if any) and returns the stored page. */
-    create: (client: DataClient, name: string) => Promise<StoredPage>;
+    /** What the template shows off — rendered as chips on the gallery card. */
+    tags: TemplateTag[];
+    /**
+     * Canonical (English) text of the leading "how to use this" callout, for
+     * templates that don't already open with strong in-doc guidance (the five
+     * database fixtures). The gallery passes a localized override through
+     * {@link instantiateTemplate}; `create` bakes this English text in by
+     * default. Templates whose documents already guide (grocery, pitch deck,
+     * team status, and the sample-document copy — which opens with its own
+     * intro paragraph) leave it unset.
+     */
+    guidance?: string;
+    /** Creates the page (and database, if any) and returns the stored page.
+     *  `guidance` overrides the template's canonical guidance-callout text
+     *  (ignored by templates that define none). */
+    create: (client: DataClient, name: string, guidance?: string) => Promise<StoredPage>;
 }
 export declare const PAGE_TEMPLATES: PageTemplate[];
 /**
  * Instantiate a template: pick a distinct display name (courtesy numbering —
  * duplicates are allowed but unhelpful for ready-made pages) and build the page
- * through the client, retrying transient failures.
+ * through the client, retrying transient failures. `opts.guidance` localizes
+ * the leading guidance callout of templates that carry one (the gallery passes
+ * the user's locale text; absent, the canonical English default applies).
  */
-export declare function instantiateTemplate(client: DataClient, template: PageTemplate): Promise<StoredPage>;
+export declare function instantiateTemplate(client: DataClient, template: PageTemplate, opts?: {
+    guidance?: string;
+}): Promise<StoredPage>;

package/dist/templates.js

@@ -1,8 +1,36 @@
+import { TITLE_PROPERTY_ID } from './database';
+import { buildSampleDocument } from './sampleDocument';
 const emptySnapshot = (blocks) => ({
     editorjs: { blocks },
     values: [],
     names: [],
 });
+// ── The standardized "how to use this" guidance callout ─────────────────────
+//
+// The five database fixtures — which don't open with strong in-doc guidance of
+// their own — lead with one consistent `info` callout: what the template
+// demonstrates, then how to try it. The English text below is the canonical
+// default; the gallery passes a localized override at instantiation (the ui
+// package's `templates.<id>.guidance` i18n keys mirror these strings).
+const GUIDANCE = {
+    taskBoard: 'This template shows a task database: the Status property drives the kanban columns, and the same rows back the Table and Calendar views. Try it: drag a card to another column, switch views, or right-click the view to export CSV.',
+    readingList: 'Each shelf is a gallery group, and the same books also list in a Table view. Try it: rate a book, move one to another shelf, or add your own.',
+    roadmap: 'This template shows swimlanes: the Timeline bands and the Board lanes both split by Area. Try it: drag a bar to reschedule, collapse a lane, or move a card between stages.',
+    fieldMap: 'This template shows a map database: rows with a location render as region-coloured pins, and the address-only row waits under Unplaced. Try it: click a pin, geocode the unplaced row, or switch to the Table view.',
+    productHq: 'This template shows two linked databases: each initiative relates to tasks on the Tasks sub-page, and the Progress and Task count columns roll those tasks up. Try it: tick a task done on the sub-page and watch the rollup move, or open the Tasks timeline for the dependency arrows.',
+};
+/** The guidance callout as a block-doc block (ids are stable per template). */
+const guidanceCallout = (id, text) => ({
+    id,
+    type: 'callout',
+    text: [{ t: text }],
+    props: { variant: 'info' },
+});
+/** A host-page snapshot: empty, or a single leading guidance callout rendered
+ *  (block-doc) above the hosted database view. */
+const guidanceSnapshot = (guide) => guide
+    ? { editorjs: { blocks: [] }, values: [], names: [], editor: 'blocks', blockdoc: { blocks: [guidanceCallout(guide.id, guide.text)] } }
+    : emptySnapshot([]);
 /** A local `YYYY-MM-DD` day string offset by `days` from today. */
 const day = (days) => {
     const d = new Date();
@@ -304,6 +332,151 @@ const SAVINGS_BLOCKS = [
     { id: 's-link', type: 'linkcard', props: { title: 'How compound interest works', description: 'A plain-English primer.', url: 'https://www.investor.gov/financial-tools-calculators/calculators/compound-interest-calculator' } },
     { id: 's-notes-4', type: 'notes', text: [{ t: 'One ask to close on: automate the monthly contribution so the plan happens without willpower.' }] },
 ];
+// ── 📽️ Pitch deck ────────────────────────────────────────────────────────────
+// A present-first showcase: five slides (title · agenda · a live revenue-mix
+// donut · a quote · the ask), each with a speaker `notes` block, so the ⋯ →
+// Present flow lands on a real deck. The donut slide is the interactive core:
+// three sliders feed the chart and a recurring-revenue status light.
+const PITCH_DECK_BLOCKS = [
+    // Slide 1 — title
+    { id: 'pd-h1', type: 'heading', text: [{ t: 'Brightloop' }], props: { level: 1 } },
+    { id: 'pd-tag', type: 'paragraph', text: [{ t: 'The pitch as a ' }, { t: 'live document', a: { b: true } }, { t: ' — the numbers on slide 3 recompute while you talk.' }] },
+    { id: 'pd-call', type: 'callout', text: [{ t: 'Open the ⋯ menu → Present to run this as a deck.' }], props: { variant: 'info' } },
+    { id: 'pd-notes-1', type: 'notes', text: [{ t: 'Thirty seconds, tops: who you are, what Brightloop is, why the room should care. Land the tagline, then advance — the deck itself makes the “live document” point on slide 3.' }] },
+    { id: 'pd-div-1', type: 'divider' },
+    // Slide 2 — agenda
+    { id: 'pd-h2', type: 'heading', text: [{ t: 'Agenda' }], props: { level: 2 } },
+    { id: 'pd-ag1', type: 'list', text: [{ t: 'The problem — decks go stale the moment they’re exported.' }], props: { kind: 'number' } },
+    { id: 'pd-ag2', type: 'list', text: [{ t: 'The product — one page that is both the model and the deck.' }], props: { kind: 'number' } },
+    { id: 'pd-ag3', type: 'list', text: [{ t: 'Revenue mix — live, draggable, no screenshots.' }], props: { kind: 'number' } },
+    { id: 'pd-ag4', type: 'list', text: [{ t: 'What early users say.' }], props: { kind: 'number' } },
+    { id: 'pd-ag5', type: 'list', text: [{ t: 'The ask.' }], props: { kind: 'number' } },
+    { id: 'pd-notes-2', type: 'notes', text: [{ t: 'Signpost, don’t read: five stops, four minutes. Flag that slide 3 is interactive so nobody mistakes the demo for a rehearsed video.' }] },
+    { id: 'pd-div-2', type: 'divider' },
+    // Slide 3 — the live donut
+    { id: 'pd-h3', type: 'heading', text: [{ t: 'Revenue mix — live' }], props: { level: 2 } },
+    { id: 'pd-recurring', type: 'code', text: [{ t: 'Math.round(subs / (subs + services + partners) * 100)' }], props: { live: true, name: 'recurring', language: 'js', collapsed: true } },
+    {
+        id: 'pd-cols',
+        type: 'columns',
+        children: [
+            {
+                id: 'pd-col-l',
+                type: 'column',
+                props: { span: 5 },
+                children: [
+                    { id: 'pd-subs', type: 'slider', props: { name: 'subs', label: 'Subscriptions (£k/yr)', value: 62, min: 0, max: 200 } },
+                    { id: 'pd-services', type: 'slider', props: { name: 'services', label: 'Services (£k/yr)', value: 26, min: 0, max: 200 } },
+                    { id: 'pd-partners', type: 'slider', props: { name: 'partners', label: 'Partnerships (£k/yr)', value: 12, min: 0, max: 200 } },
+                ],
+            },
+            {
+                id: 'pd-col-r',
+                type: 'column',
+                props: { span: 7 },
+                children: [
+                    { id: 'pd-donut', type: 'kitchart', props: { kind: 'donut', title: 'Revenue by stream (£k/yr)', labels: 'Subscriptions, Services, Partnerships', source: '[subs, services, partners]' } },
+                    { id: 'pd-status', type: 'statuslight', props: { label: 'Recurring revenue ≥ 60%', source: 'recurring', okAt: 60, warnAt: 45 } },
+                ],
+            },
+        ],
+    },
+    { id: 'pd-notes-3', type: 'notes', text: [{ t: 'The money moment: drag Services up until the light drops to amber, then pull Subscriptions back up until recurring clears 60% and watch it recover. The maths is a one-line code block above the columns — open it if anyone asks.' }] },
+    { id: 'pd-div-3', type: 'divider' },
+    // Slide 4 — the quote
+    { id: 'pd-h4', type: 'heading', text: [{ t: 'What early users say' }], props: { level: 2 } },
+    { id: 'pd-quote', type: 'quote', text: [{ t: 'We pitched with the model itself — when the room asked “what if churn doubles?”, we dragged a slider instead of promising a follow-up.' }] },
+    { id: 'pd-notes-4', type: 'notes', text: [{ t: 'Pause after reading the quote — let it sit. If pressed for attribution, it’s a composite of three design-partner calls; offer intros rather than names.' }] },
+    { id: 'pd-div-4', type: 'divider' },
+    // Slide 5 — the ask
+    { id: 'pd-h5', type: 'heading', text: [{ t: 'The ask' }], props: { level: 2 } },
+    { id: 'pd-ask', type: 'paragraph', text: [{ t: 'We’re raising ' }, { t: '£1.2M', a: { b: true } }, { t: ' to take Brightloop from private beta to launch: two engineers, one designer, and twelve months of runway.' }] },
+    { id: 'pd-call2', type: 'callout', text: [{ t: 'Make it yours: duplicate this page, swap in your numbers, and pitch with live charts instead of screenshots.' }], props: { variant: 'success' } },
+    { id: 'pd-notes-5', type: 'notes', text: [{ t: 'Close with the concrete next step: a 30-minute working session in the live model this week. Stop talking after the ask.' }] },
+];
+// ── 🚦 Team status dashboard ─────────────────────────────────────────────────
+// The kit-breadth showcase, as a single-page dashboard (no slides): a **locked
+// group** whose controls stay live for readers (toggle, dropdown, a kudos
+// counter driven by an action button, a formula and a status light reading it),
+// a **funnel** chart (a kind no other template uses), a **tabs** container, and
+// a cross-page **sync** key — the same Pulse group pasted on another page stays
+// in lockstep under `team-pulse`.
+const TEAM_STATUS_BLOCKS = [
+    { id: 'td-tag', type: 'paragraph', text: [{ t: 'One page the whole team reads: a ' }, { t: 'locked', a: { b: true } }, { t: ' Pulse panel whose controls stay live, a delivery funnel, and the week’s rituals in tabs.' }] },
+    { id: 'td-call', type: 'callout', text: [{ t: 'The Pulse group is locked (the 🔒 in its header): its text and layout are frozen, but readers keep every control. It also syncs across pages under the sync key “team-pulse” — paste the same group on another page and the two stay in lockstep.' }], props: { variant: 'info' } },
+    // The locked, synced control panel.
+    { id: 'td-h2', type: 'heading', text: [{ t: 'Team pulse' }], props: { level: 2 } },
+    {
+        id: 'td-group',
+        type: 'group',
+        props: { name: 'Pulse', locked: true, sync: 'team-pulse' },
+        children: [
+            { id: 'td-g-note', type: 'paragraph', text: [{ t: 'This panel is locked — this very sentence can’t be edited in place — yet every control below still works.' }] },
+            { id: 'td-oncall', type: 'toggle', props: { name: 'onCall', label: 'On-call rotation active', value: true } },
+            { id: 'td-focus', type: 'dropdown', props: { name: 'focus', label: 'Focus this week', value: 'shipping', opts: [{ label: 'Shipping' }, { label: 'Stability' }, { label: 'Growth' }] } },
+            { id: 'td-kudos', type: 'number', props: { name: 'kudos', label: 'Kudos given', value: 2, min: 0, max: 99, step: 1 } },
+            { id: 'td-give', type: 'actionbutton', props: { btnlabel: 'Give kudos', action: 'increment', target: 'kudos', amount: 1 } },
+            // Inputs inside a named group publish namespaced — pulse.kudos.value —
+            // which is exactly what this formula (and the light below) read.
+            { id: 'td-score', type: 'formula', props: { name: 'morale', source: 'pulse.kudos.value * 10 + (pulse.onCall.value ? 5 : 0)' } },
+            { id: 'td-light', type: 'statuslight', props: { label: 'Momentum', source: 'pulse.kudos.value', okAt: 3, warnAt: 1 } },
+        ],
+    },
+    // The delivery funnel: a chart kind no other template exercises.
+    { id: 'td-h3', type: 'heading', text: [{ t: 'Delivery pipeline' }], props: { level: 2 } },
+    { id: 'td-pipe', type: 'code', text: [{ t: '({Ideas: 24, Building: 12, "In review": 7, Shipped: shipped})' }], props: { live: true, name: 'pipeline', language: 'js', collapsed: true } },
+    {
+        id: 'td-cols',
+        type: 'columns',
+        children: [
+            {
+                id: 'td-col-l',
+                type: 'column',
+                props: { span: 5 },
+                children: [
+                    { id: 'td-shipped', type: 'number', props: { name: 'shipped', label: 'Shipped this quarter', value: 5, min: 0, max: 50, step: 1 } },
+                    { id: 'td-tip', type: 'tooltipcard', props: { term: 'Funnel', tip: 'Each stage narrows: ideas → building → review → shipped. Step the shipped count and the funnel redraws.' } },
+                ],
+            },
+            {
+                id: 'td-col-r',
+                type: 'column',
+                props: { span: 7 },
+                children: [
+                    { id: 'td-funnel', type: 'kitchart', props: { kind: 'funnel', title: 'Ideas → Shipped', source: 'pipeline' } },
+                ],
+            },
+        ],
+    },
+    // The week's rituals, in a tabs container.
+    { id: 'td-h4', type: 'heading', text: [{ t: 'Rituals' }], props: { level: 2 } },
+    {
+        id: 'td-tabs',
+        type: 'tabs',
+        props: { name: 'Rituals', active: 0 },
+        children: [
+            {
+                id: 'td-tab-week',
+                type: 'tab',
+                props: { label: 'This week' },
+                children: [
+                    { id: 'td-t1', type: 'todo', text: [{ t: 'Monday kick-off — pick the focus in the Pulse panel' }], props: { checked: true } },
+                    { id: 'td-t2', type: 'todo', text: [{ t: 'Thursday demo — show, don’t tell' }], props: { checked: false } },
+                ],
+            },
+            {
+                id: 'td-tab-next',
+                type: 'tab',
+                props: { label: 'Next week' },
+                children: [
+                    { id: 'td-n1', type: 'list', text: [{ t: 'Rotate the on-call — flip the Pulse toggle' }], props: { kind: 'bullet' } },
+                    { id: 'td-n2', type: 'list', text: [{ t: 'Reset the kudos counter at retro' }], props: { kind: 'bullet' } },
+                ],
+            },
+        ],
+    },
+    { id: 'td-call2', type: 'callout', text: [{ t: 'Make it yours: rename the Pulse group, change its sync key, and unlock it (the 🔓 in the group header) to re-arrange the controls.' }], props: { variant: 'success' } },
+];
 // ════════════════════════════════════════════════════════════════════════════
 // Databases (the task board, reading list, and the swimlane + map e2e fixtures)
 // ════════════════════════════════════════════════════════════════════════════
@@ -337,9 +510,11 @@ const TASK_BOARD_SCHEMA = {
         { id: 'p_effort', name: 'Effort', type: 'number', numberDisplay: 'bar', numberTarget: 8 },
     ],
     views: [
-        // Board first → the page opens as a kanban grouped by status; a table backs it.
+        // Board first → the page opens as a kanban grouped by status; a table backs
+        // it, and a calendar lays the same tasks out on a month grid by due date.
         { id: 'v_board', name: 'Board', type: 'board', filters: [], sorts: [], groupByPropertyId: 'p_status' },
         { id: 'v_table', name: 'Table', type: 'table', filters: [], sorts: [] },
+        { id: 'v_calendar', name: 'Calendar', type: 'calendar', filters: [], sorts: [], datePropertyId: 'p_due' },
     ],
 };
 const TASK_BOARD_ROWS = [
@@ -353,6 +528,19 @@ const TASK_BOARD_ROWS = [
 ];
 // ── 📚 Reading list ──────────────────────────────────────────────────────────
 // A shelf-grouped gallery of books, with authors and star ratings; a table backs it.
+//
+// Covers (so the gallery renders real cards, not empty slots): tiny (<300 B) raster
+// PNGs, inlined as `data:` URLs on the `files`-typed `p_cover` cells. Deliberately
+// NOT routed through the content-addressed asset store — the `files` property and
+// the gallery cover render a URL string straight into `<img src>` with no
+// asset-resolution seam, so a store `assetId` wouldn't load there, and this seeds
+// identically on both transports (web PGlite + desktop IPC) with no upload call.
+// PNG, never SVG — honouring the store's image allowlist even though nothing is
+// stored (an `<img src="data:image/png…">` executes no script). One per shelf so
+// each gallery group leads with a cover.
+const COVER_TEAL = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAFAAAAB4CAIAAADqjOKhAAAAsklEQVR42u3ZMQ2AMBRF0YpgR1INoAQPGKidrt2R0KQq2FlJmvJzkmvgjC8vbUd+tV9n4BIwMDAwMDAwMDAwMDAwMDAwMDAwMDAw8BLge/S/BAwMDAwMDAwMDAwMDAwMDAwMDAwMHADseQAGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYG/gIurc4PGBgYGBgYGBgYOADYWgIGBgYGBgYGBgYGBgYO0wNsxNp6TrTOmAAAAABJRU5ErkJggg==';
+const COVER_ORANGE = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAFAAAAB4CAIAAADqjOKhAAAAsklEQVR42u3ZMQ2AMBRF0SpBAlKqBw24wEo1dKkClu5d2VlJmvJzkmvgjC8vnXl7VY89cAkYGBgYGBgYGBgYGBgYGBgYGBgYGBgYeAnwuNtfAgYGBgYGBgYGBgYGBgYGBgYGBgYGDgD2PAADAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDfwH3cs0PGBgYGBgYGBgYOADYWgIGBgYGBgYGBgYGBgYO0wM4vRK/kEih/QAAAABJRU5ErkJggg==';
+const COVER_BLUE = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAFAAAAB4CAIAAADqjOKhAAAAsklEQVR42u3ZMQ2AMBRF0WpBAxqqBgEIQkSXGunCVANVwM5K0pSfk1wDZ3x5acvnq/0ogUvAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwEuAWx9/CRgYGBgYGBgYGBgYGBgYGBgYGBgYOADY8wAMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwM/AV81Xt+wMDAwMDAwMDAwAHA1hIwMDAwMDAwMDAwMDBwmB4f7fGQa+V+2QAAAABJRU5ErkJggg==';
 const READING_SCHEMA = {
     properties: [
         {
@@ -375,11 +563,11 @@ const READING_SCHEMA = {
     ],
 };
 const READING_ROWS = [
-    { name: 'The Design of Everyday Things', properties: { p_shelf: 'opt_reading', p_author: 'Don Norman', p_rating: 4 } },
+    { name: 'The Design of Everyday Things', properties: { p_shelf: 'opt_reading', p_author: 'Don Norman', p_rating: 4, p_cover: [COVER_ORANGE] } },
     { name: 'Project Hail Mary', properties: { p_shelf: 'opt_reading', p_author: 'Andy Weir', p_rating: 5 } },
-    { name: 'Thinking, Fast and Slow', properties: { p_shelf: 'opt_toread', p_author: 'Daniel Kahneman' } },
+    { name: 'Thinking, Fast and Slow', properties: { p_shelf: 'opt_toread', p_author: 'Daniel Kahneman', p_cover: [COVER_TEAL] } },
     { name: 'Designing Data-Intensive Applications', properties: { p_shelf: 'opt_toread', p_author: 'Martin Kleppmann' } },
-    { name: 'The Pragmatic Programmer', properties: { p_shelf: 'opt_done', p_author: 'Hunt & Thomas', p_rating: 5 } },
+    { name: 'The Pragmatic Programmer', properties: { p_shelf: 'opt_done', p_author: 'Hunt & Thomas', p_rating: 5, p_cover: [COVER_BLUE] } },
     { name: 'Deep Work', properties: { p_shelf: 'opt_done', p_author: 'Cal Newport', p_rating: 4 } },
 ];
 // ── Product roadmap ──────────────────────────────────────────────────────────
@@ -485,14 +673,98 @@ const FIELD_MAP_ROWS = [
     { name: 'Tokyo office', properties: { p_region: 'opt_apac', p_kind: 'opt_office', p_headcount: 85, p_address: 'Chiyoda, Tokyo', p_place: { lat: 35.6814, lng: 139.7670, label: 'Tokyo office' } } },
     { name: 'Sydney partner', properties: { p_region: 'opt_apac', p_kind: 'opt_partner', p_headcount: 15, p_address: 'Circular Quay, Sydney', p_place: { lat: -33.8610, lng: 151.2100, label: 'Sydney partner' } } },
 ];
+// ── 🎯 Product HQ ────────────────────────────────────────────────────────────
+// Two databases wired together: Initiatives (the page you land on) and Tasks
+// (a sub-page). A 1:n relation links them BOTH ways (forward `Tasks` column +
+// reverse `Initiative` column), two rollups on Initiatives fold the linked
+// tasks (% done + task count), and a `dependency` property chains the tasks —
+// surfaced as arrows on the Tasks page's timeline view.
+/** Initiatives: status + the forward 1:n relation to Tasks + two rollups over it. */
+const productHqInitiativesSchema = (tasksDbId) => ({
+    properties: [
+        {
+            id: 'p_status',
+            name: 'Status',
+            type: 'status',
+            options: [
+                { id: 'opt_next', label: 'Up next', color: 'gray', group: 'todo' },
+                { id: 'opt_track', label: 'On track', color: 'blue', group: 'in_progress' },
+                { id: 'opt_risk', label: 'At risk', color: 'red', group: 'in_progress' },
+                { id: 'opt_shipped', label: 'Shipped', color: 'green', group: 'complete' },
+            ],
+        },
+        // The forward side of the two-way link: one initiative → many tasks.
+        { id: 'p_tasks', name: 'Tasks', type: 'relation', relationDatabaseId: tasksDbId, relationCardinality: '1:n', reversePropertyId: 'p_initiative' },
+        // Rollups fold the linked tasks: how done, and how many.
+        { id: 'p_progress', name: 'Progress', type: 'rollup', rollup: { relationPropertyId: 'p_tasks', targetPropertyId: 'p_done', function: 'percent_checked' } },
+        { id: 'p_count', name: 'Task count', type: 'rollup', rollup: { relationPropertyId: 'p_tasks', targetPropertyId: TITLE_PROPERTY_ID, function: 'count' } },
+    ],
+    views: [
+        // The table leads (relation chips + rollups in one glance); a board backs it.
+        { id: 'v_table', name: 'Table', type: 'table', filters: [], sorts: [] },
+        { id: 'v_board', name: 'Board', type: 'board', filters: [], sorts: [], groupByPropertyId: 'p_status' },
+    ],
+});
+/** Tasks: the reverse (single) side of the relation, a Done checkbox the
+ *  rollup folds, a date range, and the dependency chain the timeline draws. */
+const productHqTasksSchema = (initiativesDbId) => ({
+    properties: [
+        { id: 'p_initiative', name: 'Initiative', type: 'relation', relationDatabaseId: initiativesDbId, relationSingle: true, reversePropertyId: 'p_tasks' },
+        { id: 'p_owner', name: 'Owner', type: 'text' },
+        { id: 'p_done', name: 'Done', type: 'checkbox' },
+        { id: 'p_when', name: 'When', type: 'date', dateRange: true },
+        { id: 'p_blockedby', name: 'Blocked by', type: 'dependency' },
+    ],
+    views: [
+        // Timeline first: bars from the `When` range, dependency arrows from
+        // `Blocked by` (predecessor end → dependent start).
+        { id: 'v_timeline', name: 'Timeline', type: 'timeline', filters: [], sorts: [], datePropertyId: 'p_when', dependencyPropertyId: 'p_blockedby' },
+        { id: 'v_table', name: 'Table', type: 'table', filters: [], sorts: [] },
+    ],
+});
+/** Build the two databases, then seed rows across both so the relation, the
+ *  rollups, and the dependency arrows all render non-empty out of the box. */
+const createProductHq = async (client, name, guidance = GUIDANCE.productHq) => {
+    // Pre-minted ids let each schema reference the OTHER database with no
+    // second-pass schema update (createDatabase honours a client-supplied id).
+    const initiativesDbId = globalThis.crypto.randomUUID();
+    const tasksDbId = globalThis.crypto.randomUUID();
+    const tasksName = `${name} Tasks`;
+    // The guidance callout leads the Initiatives host page; the Tasks sub-page
+    // stays bare (it's reached from the guided page).
+    const page = await client.savePage({ name, data: guidanceSnapshot({ id: 'hq-guide', text: guidance }) });
+    const tasksPage = await client.savePage({ name: tasksName, data: emptySnapshot([]), parentId: page.id });
+    await client.createDatabase({ id: initiativesDbId, pageId: page.id, name, schema: productHqInitiativesSchema(tasksDbId) });
+    await client.createDatabase({ id: tasksDbId, pageId: tasksPage.id, name: tasksName, schema: productHqTasksSchema(initiativesDbId) });
+    const seedRow = async (dbId, rowName, properties) => (await client.createRow(dbId, { name: rowName, properties })).id;
+    // Initiatives first (the tasks link back to them)…
+    const revamp = await seedRow(initiativesDbId, 'Onboarding revamp', { p_status: 'opt_track' });
+    const perf = await seedRow(initiativesDbId, 'Performance push', { p_status: 'opt_risk' });
+    const billing = await seedRow(initiativesDbId, 'Billing v2', { p_status: 'opt_shipped' });
+    // …then the tasks: linked 1:n, dated for the timeline, chained by `Blocked by`.
+    const t1 = await seedRow(tasksDbId, 'Ship onboarding checklist', { p_initiative: [revamp], p_owner: 'Ada', p_done: true, p_when: { start: day(-10), end: day(-3) } });
+    const t2 = await seedRow(tasksDbId, 'Guided first-run tour', { p_initiative: [revamp], p_owner: 'Lin', p_done: false, p_when: { start: day(-2), end: day(6) }, p_blockedby: [t1] });
+    const t3 = await seedRow(tasksDbId, 'Profile the hot paths', { p_initiative: [perf], p_owner: 'Sam', p_done: false, p_when: { start: day(1), end: day(5) } });
+    const t4 = await seedRow(tasksDbId, 'Cache the page list', { p_initiative: [perf], p_owner: 'Sam', p_done: false, p_when: { start: day(6), end: day(12) }, p_blockedby: [t3] });
+    const t5 = await seedRow(tasksDbId, 'Migrate legacy invoices', { p_initiative: [billing], p_owner: 'Lin', p_done: true, p_when: { start: day(-20), end: day(-12) } });
+    // Mirror the reverse side of the two-way link. Seeding writes both sides
+    // explicitly — the live mirror only runs on relation-cell edits. (updateRow
+    // replaces the whole properties bag, so re-send the status too.)
+    await client.updateRow(initiativesDbId, revamp, { properties: { p_status: 'opt_track', p_tasks: [t1, t2] } });
+    await client.updateRow(initiativesDbId, perf, { properties: { p_status: 'opt_risk', p_tasks: [t3, t4] } });
+    await client.updateRow(initiativesDbId, billing, { properties: { p_status: 'opt_shipped', p_tasks: [t5] } });
+    return page;
+};
 // ── The gallery ──────────────────────────────────────────────────────────────
 /** Create a block-editor template page from a JSON block projection. */
 const createBlockDocPage = (blocks) => (client, name) => client.savePage({ name, data: { editorjs: { blocks: [] }, values: [], names: [], editor: 'blocks', blockdoc: { blocks } } });
 /** Create a database template: host page + database + sample rows. Names are
  *  not unique, so a plain create always lands; the retry ladder below survives
- *  transient failures (untitled as a last resort). */
-const createDatabasePage = (schema, rows) => async (client, name) => {
-    const page = await client.savePage({ name, data: emptySnapshot([]) });
+ *  transient failures (untitled as a last resort). `guide` (id + canonical
+ *  English text) puts the standardized guidance callout on the host page —
+ *  where a database template's doc surface renders, above the view. */
+const createDatabasePage = (schema, rows, guide) => async (client, name, guidance) => {
+    const page = await client.savePage({ name, data: guidanceSnapshot(guide && { id: guide.id, text: guidance ?? guide.text }) });
     const db = await client.createDatabase({ pageId: page.id, name, schema });
     for (const row of rows) {
         let rowName = row.name;
@@ -512,14 +784,30 @@ const createDatabasePage = (schema, rows) => async (client, name) => {
     }
     return page;
 };
+/** A fresh copy of the sample document under its own gallery name. It already
+ *  opens with its own intro paragraph (`sample-intro`), so — unlike the database
+ *  fixtures — it carries no standardized guidance callout of its own (that would
+ *  double-guide, stacking a near-duplicate lead above the intro). */
+const createCompoundGrowth = (client, name) => {
+    const input = buildSampleDocument();
+    return client.savePage({ ...input, name });
+};
 export const PAGE_TEMPLATES = [
-    { id: 'grocery-tracker', icon: '🛒', pageName: 'Grocery price tracker', create: createBlockDocPage(GROCERY_BLOCKS) },
-    { id: 'task-board', icon: '🗂️', pageName: 'Project task board', create: createDatabasePage(TASK_BOARD_SCHEMA, TASK_BOARD_ROWS) },
-    { id: 'reading-list', icon: '📚', pageName: 'Reading list', create: createDatabasePage(READING_SCHEMA, READING_ROWS) },
-    { id: 'project-intake', icon: '📋', pageName: 'Project intake', create: createBlockDocPage(PROJECT_INTAKE_BLOCKS) },
-    { id: 'savings-planner', icon: '💰', pageName: 'Savings & investing', create: createBlockDocPage(SAVINGS_BLOCKS) },
-    { id: 'roadmap', icon: '🗺️', pageName: 'Product roadmap', create: createDatabasePage(ROADMAP_SCHEMA, ROADMAP_ROWS) },
-    { id: 'field-map', icon: '📍', pageName: 'Field map', create: createDatabasePage(FIELD_MAP_SCHEMA, FIELD_MAP_ROWS) },
+    { id: 'grocery-tracker', icon: '🛒', pageName: 'Grocery price tracker', tags: ['interactive', 'slides'], create: createBlockDocPage(GROCERY_BLOCKS) },
+    { id: 'task-board', icon: '🗂️', pageName: 'Project task board', tags: ['database'], guidance: GUIDANCE.taskBoard, create: createDatabasePage(TASK_BOARD_SCHEMA, TASK_BOARD_ROWS, { id: 'tb-guide', text: GUIDANCE.taskBoard }) },
+    { id: 'reading-list', icon: '📚', pageName: 'Reading list', tags: ['database'], guidance: GUIDANCE.readingList, create: createDatabasePage(READING_SCHEMA, READING_ROWS, { id: 'rl-guide', text: GUIDANCE.readingList }) },
+    { id: 'project-intake', icon: '📋', pageName: 'Project intake', tags: ['interactive', 'slides'], create: createBlockDocPage(PROJECT_INTAKE_BLOCKS) },
+    { id: 'savings-planner', icon: '💰', pageName: 'Savings & investing', tags: ['interactive', 'slides'], create: createBlockDocPage(SAVINGS_BLOCKS) },
+    { id: 'roadmap', icon: '🗺️', pageName: 'Product roadmap', tags: ['database'], guidance: GUIDANCE.roadmap, create: createDatabasePage(ROADMAP_SCHEMA, ROADMAP_ROWS, { id: 'rm-guide', text: GUIDANCE.roadmap }) },
+    { id: 'field-map', icon: '📍', pageName: 'Field map', tags: ['database'], guidance: GUIDANCE.fieldMap, create: createDatabasePage(FIELD_MAP_SCHEMA, FIELD_MAP_ROWS, { id: 'fm-guide', text: GUIDANCE.fieldMap }) },
+    { id: 'pitch-deck', icon: '📽️', pageName: 'Pitch deck', tags: ['interactive', 'slides'], create: createBlockDocPage(PITCH_DECK_BLOCKS) },
+    { id: 'team-status', icon: '🚦', pageName: 'Team status dashboard', tags: ['interactive'], create: createBlockDocPage(TEAM_STATUS_BLOCKS) },
+    { id: 'product-hq', icon: '🎯', pageName: 'Product HQ', tags: ['database'], guidance: GUIDANCE.productHq, create: createProductHq },
+    // The classic sample document, folded into the gallery. Unlike the Home
+    // starter's open-or-create (which targets the canonical sample name and never
+    // overwrites), the gallery card always mints a FRESH copy under its own
+    // display name — the two entry points never race or shadow each other.
+    { id: 'compound-growth', icon: '📈', pageName: 'Compound growth', tags: ['interactive'], create: createCompoundGrowth },
 ];
 /** Courtesy numbering (names are not unique): a second instance becomes
  *  `name 2`, `name 3`… so repeated instantiations stay tellable-apart. */
@@ -536,13 +824,15 @@ async function availableName(client, base) {
 /**
  * Instantiate a template: pick a distinct display name (courtesy numbering —
  * duplicates are allowed but unhelpful for ready-made pages) and build the page
- * through the client, retrying transient failures.
+ * through the client, retrying transient failures. `opts.guidance` localizes
+ * the leading guidance callout of templates that carry one (the gallery passes
+ * the user's locale text; absent, the canonical English default applies).
  */
-export async function instantiateTemplate(client, template) {
+export async function instantiateTemplate(client, template, opts) {
     let name = await availableName(client, template.pageName);
     for (let attempt = 0;; attempt += 1) {
         try {
-            return await template.create(client, name);
+            return await template.create(client, name, opts?.guidance);
         }
         catch (err) {
             // A concurrent create can win the name between the check and the save;