@book.dev/sdk 2.0.0 → 2.2.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export type { PageSnapshot, PageMeta, StoredPage, PageInput, ServerInfo, ServerControls, PageVisibility, Visibility, MemberRole, EffectiveRole, MemberStatus, MemberSource, AclLevel, Member, PageAcl, } from './types';
 export { emptyPageSnapshot, PAGE_VISIBILITIES } from './types';
 export { API, type ApiError, type CompactResult } from './routes';
-export type { DataClient, PageSubscription, FetchLike, LiveSourceLike, HttpDataClientOptions, IdentityCredential } from './client';
+export type { DataClient, PageSubscription, FetchLike, LiveSourceLike, HttpDataClientOptions, IdentityCredential, CreateAgentTokenInput, CreatedAgentToken, AgentTokenList } from './client';
 export { HttpDataClient } from './client';
 export { ForwardingApiError, ForwardingClient, TunnelClient, MemoryKeyStore, SITE_VISIBILITIES, mintSiteKeypair, signWithSiteKey, verifyWithSiteKey, FORWARDED_HEADER, signRosterAssertion, verifyRosterAssertion, isAcceptedRosterVersion, ROSTER_ASSERTION_VERSION, ROSTER_ASSERTION_V2, ACCEPTED_ROSTER_VERSIONS, ROSTER_ASSERTION_SKEW_MS, type KeyStore, type SiteIdentity, type SiteVisibility, type ForwardingClientOptions, type TunnelStatus, type RosterAssertionVersion, type RosterAssertionPayload, type RosterAssertionV1Payload, type RosterAssertionV2Payload, type SignRosterAssertionInput, type VerifyRosterAssertionInput, type VerifiedRosterAssertion, } from './forwarding';
 export { DATA_PALETTE, DATA_COLOR_TOKENS, DATA_COLOR_SCHEMES, DEFAULT_DATA_COLOR_SCHEME, SERIES_ORDER, DATA_STROKE, STATUS_TOKENS, dataStroke, isDataColorToken, seriesColor, statusColor, hexAlpha, type DataColorToken, type DataColorScheme, type DataColor, type ChipColors, } from './dataColors';
@@ -11,7 +11,7 @@ export { evaluateFormula, formulaReferences, FormulaError, type FormulaValue, ty
 export { OWNER_PROPERTY_ID, VERIFICATION_PROPERTY_ID, BACKLINKS_PROPERTY_ID, THEME_PROPERTY_ID, COVER_PROPERTY_ID, FONTS_PROPERTY_ID, ICON_PROPERTY_ID, FULLWIDTH_PROPERTY_ID, SYSTEM_PAGE_PROPERTIES, isVerified, verificationExpired, isVerificationActive, makeVerification, extractMentionIds, propertiesReferencePage, type VerificationValue, } from './pageProperties';
 export { getServerUrlOverride, setServerUrlOverride, getServerTokenOverride, setServerTokenOverride, getIdentityCredential, setIdentityToken, setGuestName, getForwardingAudience, setForwardingAudience, isMixedContentBlocked } from './connection';
 export { AccountClient, AccountError, DEFAULT_ACCOUNT_URL, getAccountUrlOverride, setAccountUrlOverride, resolveAccountUrl, type AccountSettings, type IdentityTokenResult, } from './account';
-export { guestPrincipal, localPrincipal, principalId, verifiedSubject, colorForIdentity, IDENTITY_COLORS, mintIdentityKeypair, signIdentity, decodeIdentity, verifyIdentity, verifyRevocations, signRevocations, principalFromClaims, unverifiedPrincipalFromClaims, LOCAL_OWNER_HEADER, type Principal, type PrincipalKind, type VerifiedVia, type IdentityHeader, type IdentityClaims, type Jwk, type Jwks, type RevocationEntry, type RevocationSet, type IdentityKeypair, type VerifyOptions, type VerifyResult, type VerifyFailure, } from './identity';
+export { guestPrincipal, localPrincipal, principalId, verifiedSubject, colorForIdentity, IDENTITY_COLORS, mintIdentityKeypair, signIdentity, decodeIdentity, verifyIdentity, verifyRevocations, signRevocations, principalFromClaims, unverifiedPrincipalFromClaims, LOCAL_OWNER_HEADER, type Principal, type PrincipalKind, type VerifiedVia, type AgentTokenScope, type AgentTokenMeta, type IdentityHeader, type IdentityClaims, type Jwk, type Jwks, type RevocationEntry, type RevocationSet, type IdentityKeypair, type VerifyOptions, type VerifyResult, type VerifyFailure, } from './identity';
 export { DEFAULT_INSTANCE_CONFIG, type GuestAccess, type TrustedIssuerConfig, type InstanceConfig, type InstanceInfo, type StoredEdit, type LibraryBinding, type LibraryRoster, type LibraryRosterEntry, } from './provenance';
 export { authorize, isEmailAuthoritative, type Role, type EffectiveVisibility, type AclEntry, type AccessPage, type AccessCtx, type Decision, } from './authorize';
 export { snapshotText, paragraphBlocks, textSnapshot, appendTextToSnapshot, appendBlocksToSnapshot, type AppendBlock } from './content';
@@ -29,5 +29,5 @@ export { markdownToBlocks, markdownToImportedDoc, type MarkdownImportOptions } f
 export { notionExportToImportedDoc, parseCsv } from './notionImport';
 export { rehydrateImageUrls, rehydrateStoredImages, importedImageBlock, imagePlaceholderMeta, mimeFromRef, notionAssetResolver, urlAssetResolver, isHttpUrl, isDataUrlRef, IMAGE_BLOCK_TYPE, DEFAULT_MAX_ASSET_BYTES, type RehydrateUrlOptions, type RehydrateStoredClient, type RehydrateStoredOptions, type RehydrateStoredResult, type ImportAssetResolver, type AssetBytes, } from './importAssets';
 export { BACKUP_VERSION, BACKUP_CADENCES, BACKUP_CADENCE_MS, DEFAULT_BACKUP_CONFIG, remapBundle, type LibraryBackup, type ImportMode, type ImportRequest, type ImportResult, type BackupCadence, type BackupConfig, type BackupCadenceStatus, type BackupStatus, } from './backup';
-export type { AgentChatEvent, AgentChatMessage, AgentChatOptions, AgentProposal, InterviewStep, AiProvider, AiConfig, AiProviderSettings, AiEffort, AiSkill, AiStatus, AiSearchResult, AiSearchResponse, AiTasksResponse, AiStreamEvent, AiModelPrice, AiPricingTable, AiPricingResponse, AiUsageRow, AiUsageTotals, AiUsageResponse, } from './ai';
+export type { AgentChatEvent, AgentChatMessage, AgentChatOptions, AgentProposal, InterviewStep, AiProvider, AiConfig, AiProviderSettings, AiEffort, AiSkill, AiStatus, AiSearchResult, AiSearchResponse, AiTasksResponse, AiStreamEvent, AiModelPrice, AiPricingTable, AiPricingResponse, AiUsageRow, AiUsageTotals, AiUsageResponse, McpTransport, McpServerConfig, McpClientConfig, McpConfigResponse, McpTestResult, } from './ai';
 export { providerSettings, isPaidProvider } from './ai';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/routes.d.ts

@@ -98,6 +98,16 @@ export declare const API: {
     readonly aiModelDownload: "/api/ai/models/download";
     /** The agent harness: `POST` `{messages, effort?, thinking?, skills?}` → SSE tool/reasoning/proposal/final events. */
     readonly agentChat: "/api/agent/chat";
+    /**
+     * External tools (MCP client) config (admin only): `GET` returns
+     * {@link McpConfigResponse} (redacted config + `stdioAllowed`); `PUT`
+     * `{enabled, servers}` merges it (write-only auth tokens preserved/replaced/
+     * cleared) and returns the redacted result. Managing external tool servers is
+     * host command-execution territory — gated by `requireInstanceAdmin`. */
+    readonly aiMcp: "/api/ai/mcp";
+    /** Dry-run one MCP server config (admin only): `POST` a {@link McpServerConfig}
+     *  → {@link McpTestResult} (connect + list tools; never returns secrets). */
+    readonly aiMcpTest: "/api/ai/mcp/test";
     /** User-authored prompt/recipe skills: `GET` (list) / `PUT` `{skill}` (upsert). */
     readonly aiSkills: "/api/ai/skills";
     /** One skill by name: `DELETE`. */
@@ -191,6 +201,21 @@ export declare const API: {
     readonly backups: "/api/backups";
     /** Run a backup immediately: `POST` `{cadence?}` → the written file's name. */
     readonly backupRun: "/api/backups/run";
+    /**
+     * Agent Personal-Access-Token management (admin only — `requireInstanceAdmin`;
+     * a PAT can never reach this route, both by `requireInstanceAdmin` and the
+     * scope-gate). `GET` → `{enabled, tokens}` (redacted list + the `agentApi`
+     * on/off state); `PUT` `{enabled}` toggles the dark `agentApi` setting; `POST`
+     * `{name, scope?, expiresInDays?}` mints a token (404 while `agentApi` is off) and
+     * returns the plaintext exactly ONCE. */
+    readonly agentTokens: "/api/agent-tokens";
+    /** Revoke one agent token by id: `DELETE`. `true` if one was removed. */
+    readonly agentToken: (id: string) => string;
+    /**
+     * Remote streamable-HTTP MCP transport (AGENT-5 — handler built separately).
+     * Declared here so the AGENT-6 scope-gate can allowlist it; harmless until the
+     * handler is mounted. */
+    readonly mcp: "/api/mcp";
 };
 /** Result of a {@link API.compact} run: the database's on-disk size before/after,
  *  in bytes, and how much was reclaimed. */

package/dist/routes.js

@@ -100,6 +100,16 @@ export const API = {
     aiModelDownload: '/api/ai/models/download',
     /** The agent harness: `POST` `{messages, effort?, thinking?, skills?}` → SSE tool/reasoning/proposal/final events. */
     agentChat: '/api/agent/chat',
+    /**
+     * External tools (MCP client) config (admin only): `GET` returns
+     * {@link McpConfigResponse} (redacted config + `stdioAllowed`); `PUT`
+     * `{enabled, servers}` merges it (write-only auth tokens preserved/replaced/
+     * cleared) and returns the redacted result. Managing external tool servers is
+     * host command-execution territory — gated by `requireInstanceAdmin`. */
+    aiMcp: '/api/ai/mcp',
+    /** Dry-run one MCP server config (admin only): `POST` a {@link McpServerConfig}
+     *  → {@link McpTestResult} (connect + list tools; never returns secrets). */
+    aiMcpTest: '/api/ai/mcp/test',
     /** User-authored prompt/recipe skills: `GET` (list) / `PUT` `{skill}` (upsert). */
     aiSkills: '/api/ai/skills',
     /** One skill by name: `DELETE`. */
@@ -199,5 +209,21 @@ export const API = {
     backups: '/api/backups',
     /** Run a backup immediately: `POST` `{cadence?}` → the written file's name. */
     backupRun: '/api/backups/run',
+    // ── Agent access: PAT credential management (AGENT-6) ─────────────────────────
+    /**
+     * Agent Personal-Access-Token management (admin only — `requireInstanceAdmin`;
+     * a PAT can never reach this route, both by `requireInstanceAdmin` and the
+     * scope-gate). `GET` → `{enabled, tokens}` (redacted list + the `agentApi`
+     * on/off state); `PUT` `{enabled}` toggles the dark `agentApi` setting; `POST`
+     * `{name, scope?, expiresInDays?}` mints a token (404 while `agentApi` is off) and
+     * returns the plaintext exactly ONCE. */
+    agentTokens: '/api/agent-tokens',
+    /** Revoke one agent token by id: `DELETE`. `true` if one was removed. */
+    agentToken: (id) => `/api/agent-tokens/${encodeURIComponent(id)}`,
+    /**
+     * Remote streamable-HTTP MCP transport (AGENT-5 — handler built separately).
+     * Declared here so the AGENT-6 scope-gate can allowlist it; harmless until the
+     * handler is mounted. */
+    mcp: '/api/mcp',
 };
 //# sourceMappingURL=routes.js.map

package/dist/routes.js.map

@@ -1 +1 @@
-{"version":3,"file":"routes.js","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"routes.js","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"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"}

package/dist/templates.d.ts

@@ -28,7 +28,7 @@ import type { StoredPage } from './types';
 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' | 'pitch-deck' | 'compound-growth' | 'team-status' | 'product-hq';
+    id: 'grocery-tracker' | 'task-board' | 'reading-list' | 'project-intake' | 'savings-planner' | 'roadmap' | 'field-map' | 'pitch-deck' | 'compound-growth' | 'team-status' | 'product-hq' | 'dashboard';
     /** Emoji shown on the gallery card and applied to the created page. */
     icon: string;
     /** Canonical (English) page name; suffixed when it collides. */

package/dist/templates.js

@@ -18,6 +18,7 @@ const GUIDANCE = {
     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.',
+    dashboard: 'This dashboard reads a sample sales database: the KPI tiles total the rows, and the bar, pie and trend charts group them — all live. Try it: pick a quarter in the control at the top and every tile and chart re-scopes to it at once — or edit a deal on the “… data” sub-page and watch a tile move.',
 };
 /** The guidance callout as a block-doc block (ids are stable per template). */
 const guidanceCallout = (id, text) => ({
@@ -755,6 +756,191 @@ const createProductHq = async (client, name, guidance = GUIDANCE.productHq) => {
     await client.updateRow(initiativesDbId, billing, { properties: { p_status: 'opt_shipped', p_tasks: [t5] } });
     return page;
 };
+// ── 📊 Dashboard ─────────────────────────────────────────────────────────────
+// A composite dashboard: a KPI row + DB-backed bar/pie/trend charts laid out in
+// the 12-col column blocks, all reading LIVE from a sample "sales" database the
+// template also seeds (a sub-page). The charts are ordinary in-doc `kitchart`
+// blocks in DATABASE source mode (DASH-3) — their `dbId` is stamped at
+// instantiation, when the sample database's id is minted. Unlike the database
+// fixtures you land on a composed DOCUMENT, not a table/board.
+/** The sample sales database the dashboard charts. One row = one deal, with a
+ *  Region/Channel/Stage/Quarter to group by and Amount/Units to total. */
+const SALES_SCHEMA = {
+    properties: [
+        {
+            id: 'p_region',
+            name: 'Region',
+            type: 'select',
+            options: [
+                { id: 'opt_north', label: 'North', color: 'blue' },
+                { id: 'opt_south', label: 'South', color: 'green' },
+                { id: 'opt_east', label: 'East', color: 'orange' },
+                { id: 'opt_west', label: 'West', color: 'purple' },
+            ],
+        },
+        {
+            id: 'p_channel',
+            name: 'Channel',
+            type: 'select',
+            options: [
+                { id: 'opt_online', label: 'Online', color: 'blue' },
+                { id: 'opt_retail', label: 'Retail', color: 'pink' },
+                { id: 'opt_partner', label: 'Partner', color: 'yellow' },
+            ],
+        },
+        {
+            id: 'p_stage',
+            name: 'Stage',
+            type: 'status',
+            options: [
+                { id: 'opt_pipeline', label: 'Pipeline', color: 'gray', group: 'todo' },
+                { id: 'opt_committed', label: 'Committed', color: 'blue', group: 'in_progress' },
+                { id: 'opt_won', label: 'Won', color: 'green', group: 'complete' },
+            ],
+        },
+        {
+            id: 'p_quarter',
+            name: 'Quarter',
+            type: 'select',
+            options: [
+                { id: 'opt_q1', label: 'Q1', color: 'gray' },
+                { id: 'opt_q2', label: 'Q2', color: 'gray' },
+                { id: 'opt_q3', label: 'Q3', color: 'gray' },
+                { id: 'opt_q4', label: 'Q4', color: 'gray' },
+            ],
+        },
+        { id: 'p_amount', name: 'Amount', type: 'number', numberDisplay: 'number' },
+        { id: 'p_units', name: 'Units', type: 'number' },
+    ],
+    views: [
+        // The data page opens on the table; a bar view backs it (and exercises the
+        // DB chart-view kit engine on the sample data itself).
+        { id: 'v_table', name: 'Table', type: 'table', filters: [], sorts: [] },
+        { id: 'v_bar', name: 'By region', type: 'bar', filters: [], sorts: [], groupByPropertyId: 'p_region', aggregate: { type: 'sum', propertyId: 'p_amount' } },
+    ],
+};
+const SALES_ROWS = [
+    { name: 'Northwind renewal', properties: { p_region: 'opt_north', p_channel: 'opt_online', p_stage: 'opt_won', p_quarter: 'opt_q1', p_amount: 24000, p_units: 120 } },
+    { name: 'Acme retail order', properties: { p_region: 'opt_north', p_channel: 'opt_retail', p_stage: 'opt_committed', p_quarter: 'opt_q2', p_amount: 18000, p_units: 90 } },
+    { name: 'Globex expansion', properties: { p_region: 'opt_south', p_channel: 'opt_online', p_stage: 'opt_won', p_quarter: 'opt_q1', p_amount: 31000, p_units: 150 } },
+    { name: 'Initech pilot', properties: { p_region: 'opt_south', p_channel: 'opt_partner', p_stage: 'opt_pipeline', p_quarter: 'opt_q3', p_amount: 12000, p_units: 60 } },
+    { name: 'Umbrella upsell', properties: { p_region: 'opt_east', p_channel: 'opt_online', p_stage: 'opt_committed', p_quarter: 'opt_q2', p_amount: 27000, p_units: 130 } },
+    { name: 'Soylent reorder', properties: { p_region: 'opt_east', p_channel: 'opt_retail', p_stage: 'opt_won', p_quarter: 'opt_q4', p_amount: 22000, p_units: 110 } },
+    { name: 'Hooli trial', properties: { p_region: 'opt_west', p_channel: 'opt_partner', p_stage: 'opt_pipeline', p_quarter: 'opt_q3', p_amount: 9000, p_units: 45 } },
+    { name: 'Stark contract', properties: { p_region: 'opt_west', p_channel: 'opt_online', p_stage: 'opt_won', p_quarter: 'opt_q4', p_amount: 35000, p_units: 170 } },
+    { name: 'Wayne partnership', properties: { p_region: 'opt_north', p_channel: 'opt_partner', p_stage: 'opt_committed', p_quarter: 'opt_q2', p_amount: 15000, p_units: 70 } },
+    { name: 'Cyberdyne restock', properties: { p_region: 'opt_south', p_channel: 'opt_retail', p_stage: 'opt_won', p_quarter: 'opt_q1', p_amount: 20000, p_units: 100 } },
+    { name: 'Tyrell evaluation', properties: { p_region: 'opt_east', p_channel: 'opt_online', p_stage: 'opt_pipeline', p_quarter: 'opt_q3', p_amount: 14000, p_units: 68 } },
+    { name: 'Massive Dynamic order', properties: { p_region: 'opt_west', p_channel: 'opt_retail', p_stage: 'opt_committed', p_quarter: 'opt_q4', p_amount: 17000, p_units: 82 } },
+];
+/** A database-bound `kitchart` block (DASH-3 source mode). `dbId` is stamped at
+ *  instantiation; `count` needs no numeric property, so `aggProp` is optional. A
+ *  one-line `description` keeps the edit view clean (no ghost "Add a description…"). */
+const dashboardChart = (dbId, id, kind, title, description, groupBy, aggType, aggProp, 
+/** Cross-filter (DASH-7): bind the chart to a named input + a property so a
+ *  top-of-dashboard control re-scopes it. Omitted → the chart is unfiltered. */
+filter) => ({
+    id,
+    type: 'kitchart',
+    props: {
+        kind,
+        title,
+        description,
+        sourceMode: 'database',
+        dbId,
+        dbGroupBy: groupBy,
+        dbAggType: aggType,
+        ...(aggProp ? { dbAggProp: aggProp } : {}),
+        ...(filter ? { dbFilterInput: filter.input, dbFilterProp: filter.prop } : {}),
+    },
+});
+/** The dashboard document: a leading guidance callout, a KPI row across the top
+ *  (three tiles in a 12-col columns block), then the bar+pie pair and a
+ *  full-width quarterly trend — every chart bound to the seeded sales database. */
+const dashboardBlocks = (dbId, guidance) => {
+    // The cross-filter (DASH-7): a Quarter control published as `quarter`. Every
+    // chart below (except the quarterly trend, which IS the quarter axis) binds to
+    // it on the Quarter property, so picking a quarter re-scopes the whole board.
+    const QUARTER_FILTER = { input: 'quarter', prop: 'p_quarter' };
+    const chart = (id, kind, title, description, groupBy, aggType, aggProp, filter = QUARTER_FILTER) => dashboardChart(dbId, id, kind, title, description, groupBy, aggType, aggProp, filter ?? undefined);
+    return [
+        guidanceCallout('db-guide', guidance),
+        // Cross-filter control: a dropdown that publishes `quarter`. "All quarters"
+        // (value `all`) is the default and reads as inactive, so the board opens
+        // showing the whole year; picking Q1–Q4 scopes every bound chart at once.
+        {
+            id: 'db-filter',
+            type: 'dropdown',
+            props: {
+                name: 'quarter',
+                label: 'Quarter',
+                value: 'all',
+                opts: [{ label: 'All quarters', value: 'all' }, { label: 'Q1' }, { label: 'Q2' }, { label: 'Q3' }, { label: 'Q4' }],
+            },
+        },
+        { id: 'db-h1', type: 'heading', text: [{ t: 'This quarter at a glance' }], props: { level: 2 } },
+        // KPI row — three number tiles across the top (the DASH-5 `kpi` kind). Each
+        // folds a grouped DB series to one grand total; the tile's title names it.
+        // All three bind to the Quarter cross-filter (default `chart` filter).
+        {
+            id: 'db-kpis',
+            type: 'columns',
+            children: [
+                { id: 'db-kc1', type: 'column', props: { span: 4 }, children: [chart('db-k-rev', 'kpi', 'Total revenue (£)', 'Summed across every region', 'p_region', 'sum', 'p_amount')] },
+                { id: 'db-kc2', type: 'column', props: { span: 4 }, children: [chart('db-k-deals', 'kpi', 'Deals', 'Every row, across all stages', 'p_stage', 'count')] },
+                { id: 'db-kc3', type: 'column', props: { span: 4 }, children: [chart('db-k-units', 'kpi', 'Units sold', 'Summed across every channel', 'p_channel', 'sum', 'p_units')] },
+            ],
+        },
+        { id: 'db-h2', type: 'heading', text: [{ t: 'Breakdown' }], props: { level: 2 } },
+        // Bar + pie side by side in a 6/6 split — both scoped by the Quarter filter.
+        {
+            id: 'db-cols',
+            type: 'columns',
+            children: [
+                { id: 'db-cl', type: 'column', props: { span: 6 }, children: [chart('db-bar', 'bar', 'Revenue by region (£)', 'Amount summed per sales region', 'p_region', 'sum', 'p_amount')] },
+                { id: 'db-cr', type: 'column', props: { span: 6 }, children: [chart('db-pie', 'pie', 'Deals by channel', 'Share of deals won online, retail and via partners', 'p_channel', 'count')] },
+            ],
+        },
+        // A full-width quarterly trend closes the dashboard. It is NOT bound to the
+        // Quarter filter (it is already the quarter axis) — it stays full-year, giving
+        // context while the tiles + breakdowns above slice to the chosen quarter.
+        chart('db-line', 'line', 'Revenue by quarter (£)', 'Amount summed by quarter, Q1 → Q4', 'p_quarter', 'sum', 'p_amount', null),
+        // Trailing pointer: how to ADD a chart (distinct from the lead callout, which
+        // is about editing the data). The slash menu inserts a Chart, then its ⚙
+        // Source toggle switches it to Database — there is no "/chart → Database".
+        { id: 'db-note', type: 'callout', text: [{ t: 'Want another cut of the data? Type /chart to insert one, then switch its Source to Database in the chart’s ⚙ settings and pick this database.' }], props: { variant: 'info' } },
+    ];
+};
+/** Build the dashboard document, then seed the sample sales database it charts.
+ *  The dashboard host page is saved FIRST (so its charts' `dbId` is the minted
+ *  sample-db id), and the sample database lands on a sub-page. */
+const createDashboard = async (client, name, guidance = GUIDANCE.dashboard) => {
+    const dataDbId = globalThis.crypto.randomUUID();
+    const dataName = `${name} data`;
+    const page = await client.savePage({
+        name,
+        data: { editorjs: { blocks: [] }, values: [], names: [], editor: 'blocks', blockdoc: { blocks: dashboardBlocks(dataDbId, guidance) } },
+    });
+    const dataPage = await client.savePage({ name: dataName, data: emptySnapshot([]), parentId: page.id });
+    await client.createDatabase({ id: dataDbId, pageId: dataPage.id, name: dataName, schema: SALES_SCHEMA });
+    for (const row of SALES_ROWS) {
+        let rowName = row.name;
+        for (let attempt = 2;; attempt += 1) {
+            try {
+                await client.createRow(dataDbId, { ...row, name: rowName });
+                break;
+            }
+            catch {
+                if (attempt > 5) {
+                    await client.createRow(dataDbId, { ...row, name: null });
+                    break;
+                }
+                rowName = `${row.name} ${attempt}`;
+            }
+        }
+    }
+    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 } } });
@@ -803,6 +989,10 @@ export const PAGE_TEMPLATES = [
     { 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 },
+    // A composite dashboard: KPI tiles + DB-backed charts over a seeded sales
+    // database. Tagged `interactive` (you land on a document, not a table), so it
+    // groups under Interactive documents; the description names its data backing.
+    { id: 'dashboard', icon: '📊', pageName: 'Sales dashboard', tags: ['interactive'], guidance: GUIDANCE.dashboard, create: createDashboard },
     // 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