@synap-core/workspace-templates 0.5.0 → 0.6.1

package/dist/index.d.ts

@@ -1,24 +1,741 @@
 /**
- * @synap-core/workspace-templates
+ * @synap-core/workspace-templates — Types
  *
- * Canonical workspace template definitions.
- * ==========================================
+ * Canonical shape of a workspace template.
+ * YAML source files validate against these types.
+ * Every consumer (browser, backend, CLI, marketplace) imports from here.
+ */
+type TemplateAppKind = 'native' | 'stored' | 'url';
+interface TemplateAppRef {
+    kind: TemplateAppKind;
+    /** For kind='native': the appId registered in the browser manifest */
+    appId?: string;
+    /** For kind='native': how the platform renders the app */
+    rendererType?: 'native' | 'external' | 'iframe-srcdoc';
+    /** For kind='stored': the cell key registered in the cell registry */
+    cellKey?: string;
+    /** For kind='stored': default props passed to the cell */
+    props?: Record<string, unknown>;
+    /** For kind='url': external URL to open */
+    url?: string;
+    /** Human label */
+    title?: string;
+}
+interface TemplateProperty {
+    slug: string;
+    label: string;
+    valueType: string;
+    inputType?: string;
+    placeholder?: string;
+    enumValues?: string[];
+    constraints?: Record<string, unknown>;
+    targetProfileSlug?: string;
+}
+interface TemplateProfile {
+    slug: string;
+    displayName: string;
+    icon?: string;
+    color?: string;
+    description?: string;
+    /** Visibility scope. Omit or "WORKSPACE" for workspace-scoped. */
+    scope?: string;
+    /** Semantic slug for system profiles. */
+    semanticSlug?: string;
+    /** Kind vs role profile. Omit for default ('kind'). */
+    profileKind?: "kind" | "role";
+    /** For profileKind='role': which base-kind profile slugs this role can attach to. */
+    applicableKinds?: string[];
+    properties: TemplateProperty[];
+}
+interface TemplateView {
+    name: string;
+    slug?: string;
+    type: string;
+    scopeProfileSlug?: string;
+    scopeProfileSlugs?: string[];
+    config?: Record<string, unknown>;
+    /** If true, this view auto-selected as the default view for this workspace */
+    defaultView?: boolean;
+    description?: string;
+    groupBy?: string;
+}
+interface TemplateEntityLink {
+    sourceProfileSlug: string;
+    targetProfileSlug: string;
+    type: string;
+    label?: string;
+}
+interface TemplateSeedEntity {
+    profileSlug: string;
+    title: string;
+    properties?: Record<string, unknown>;
+    content?: string;
+}
+/**
+ * Relations between seed entities, created on provisioning. `sourceRef`/
+ * `targetRef` reference seed-entity titles (or refs) defined in `seedEntities`.
+ * Mirrors `suggestedRelations` in synap-backend `create-workspace-from-definition.ts`.
+ */
+interface TemplateSuggestedRelation {
+    sourceRef: string;
+    targetRef: string;
+    type: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Entity-card display templates. Mirrors `displayTemplates` in synap-backend
+ * `create-workspace-from-definition.ts`.
+ */
+interface TemplateDisplayTemplate {
+    name: string;
+    description?: string;
+    entityType?: string;
+    targetType?: string;
+    isDefault?: boolean;
+    config: Record<string, unknown>;
+}
+interface TemplateSidebarSurface {
+    kind: 'cell' | 'view' | 'entity' | 'document' | 'channel' | 'app' | 'url';
+    cellKey?: string;
+    viewId?: string;
+    viewName?: string;
+    appId?: string;
+    url?: string;
+    rendererType?: 'native' | 'external' | 'iframe-srcdoc';
+    placement?: 'main' | 'side' | 'floating' | 'modal' | 'popover' | 'embed';
+    displayMode?: 'compact' | 'medium' | 'full';
+    props?: Record<string, unknown>;
+    title?: string;
+    meta?: Record<string, unknown>;
+}
+interface TemplateSidebarItem {
+    kind: 'app' | 'view' | 'profile' | 'external' | 'cell';
+    appId?: string;
+    viewName?: string;
+    viewId?: string;
+    profileSlug?: string;
+    url?: string;
+    cellKey?: string;
+    cellProps?: Record<string, unknown>;
+    /** When present, bypasses kind-based dispatch — full surface control */
+    surface?: TemplateSidebarSurface;
+    label?: string;
+    icon?: string;
+    section?: string;
+    matchUrls?: string[];
+}
+interface TemplateLayoutConfig {
+    pinnedApps?: string[];
+    defaultView?: string;
+    /** The first-screen app — auto-opened on workspace switch */
+    defaultApp?: string | null;
+    theme?: string;
+    sidebarItems?: TemplateSidebarItem[];
+}
+interface TemplateBentoBlock {
+    kind: 'view' | 'widget';
+    viewName?: string;
+    widgetType?: string;
+    pos: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    config?: Record<string, unknown>;
+    overrides?: Record<string, unknown>;
+}
+interface TemplateProfileEntityBentoTemplates {
+    [profileSlug: string]: {
+        blocks: Array<Record<string, unknown>>;
+    };
+}
+interface TemplateAutomation {
+    name: string;
+    description?: string;
+    trigger: string;
+    action: string;
+    config?: Record<string, unknown>;
+}
+/** Mirrors `WorkspaceSourceRole` in synap-backend `schema/workspaces.ts`. */
+type TemplateSourceRole = 'provider' | 'consumer' | 'provider-consumer';
+/** Mirrors `WorkspaceDefaultSource` in synap-backend `schema/workspaces.ts`. */
+interface TemplateDefaultSource {
+    /** The workspace id that supplies this capability domain. */
+    workspaceId: string;
+    /** The capability domain this source satisfies (e.g. "brand", "strategy"). */
+    capability?: string;
+    /** Optional profile slug the source resolves to. */
+    profileSlug?: string;
+    /** Human label for the source. */
+    label?: string;
+}
+interface TemplateOnboardingCollectTarget {
+    /** Profile slug to populate (e.g. "audience", "competitor"). */
+    profileSlug: string;
+    /** Human description of what to capture for this target. */
+    what: string;
+    /** Roughly how many to expect — guides interview depth. */
+    cardinality?: 'one' | 'few' | 'several';
+    /** Key fields the agent should make sure to fill. */
+    keyFields?: string[];
+}
+interface TemplateOnboardingExpertise {
+    /**
+     * Concrete starting points the agent PROPOSES instead of asking blank —
+     * "most X do Y, want that as a starting point?". Grounds the agent's
+     * proposals in real domain knowledge (never fabricates strategy — for
+     * mission/positioning these FRAME, they don't invent the answer).
+     */
+    starters?: string[];
+    /**
+     * Blind spots founders in this domain commonly miss. The agent proactively
+     * surfaces these if the founder hasn't — catching what they don't say.
+     */
+    blindSpots?: string[];
+    /** What a GREAT result looks like here — the bar the agent pushes toward. */
+    bar?: string;
+}
+interface TemplateOnboarding {
+    /** The outcome this onboarding achieves, in one sentence. */
+    goal: string;
+    /** Domain framing/voice the agent adopts for THIS workspace (the persona). */
+    framing: string;
+    /**
+     * Authored domain expertise the agent leads with (optional). Turns the
+     * interview from "extract what the founder knows" into "resolve what they
+     * lack". See the `onboard` skill's "Lead with your expertise" step.
+     */
+    expertise?: TemplateOnboardingExpertise;
+    /** What structured data to collect (entities to create + their key fields). */
+    collect: TemplateOnboardingCollectTarget[];
+    /** A few opening questions — the agent adapts from here, never rigid. */
+    openingQuestions?: string[];
+    /** "Done" signal the agent self-evaluates against. */
+    doneWhen?: string;
+}
+interface TemplatePlaybookParam {
+    name: string;
+    type: 'text' | 'number' | 'entity' | 'choice' | 'boolean';
+    label?: string;
+    required?: boolean;
+    defaultValue?: unknown;
+}
+interface TemplatePlaybook {
+    name: string;
+    description?: string;
+    goalTemplate: string;
+    params?: TemplatePlaybookParam[];
+    executor?: 'is-agent' | 'external-agent' | 'hybrid';
+    inputStrategy?: 'none' | 'static' | 'rotating' | 'query';
+    channelSpec?: {
+        type: 'GROUP' | 'AGENT_COLLAB' | 'THREAD';
+        members?: string[];
+        aiReactionMode?: 'on_mention' | 'always' | 'never';
+    };
+    schedule?: {
+        cron: string;
+    } | null;
+    /** tool/skill keys this playbook grants. */
+    grants?: string[];
+    status?: 'draft' | 'active' | 'paused';
+}
+interface TemplateIntegration {
+    /** Capability template key to install (matches a capability template). */
+    templateKey: string;
+    /** Override default params with {{var}} interpolation. */
+    params?: Record<string, string>;
+    /** "apply" (create+update) or "install" (create only). */
+    mode?: 'apply' | 'install';
+}
+interface TemplateExtendsRef {
+    source: string;
+    import?: {
+        profiles?: string[];
+        views?: string[];
+    };
+}
+/**
+ * A dependency this template declares on ANOTHER template/package. The install
+ * resolver (backend `POST /api/hub/packages/apply`) reads these to build the
+ * pod's template graph: every dependency is ensured present before this
+ * template is applied — missing ones install first (topologically) — and a
+ * `compose` dependency LAYERS this template's schema additively onto the
+ * dependency's workspace instead of creating a second workspace.
+ *
+ * This is the general composition primitive: a BASE template carries the
+ * agnostic data model; an OVERLAY template `compose`s onto it and adds the
+ * use-case-specific data (e.g. `blockchain-ecosystem` → `ecosystem`,
+ * `grants` → `operations`). Distinct from `extends` (which imports from a live
+ * workspace, tRPC-only) — `dependencies` is template→template.
+ */
+/**
+ * PACKAGE_DEPENDENCY_KINDS — the dependency-kind vocabulary, declared ONCE.
+ *
+ * This tuple exists so consumers can IMPORT the vocabulary instead of
+ * hand-copying it. `TemplateDependency` is currently mirrored by hand in six
+ * other places, four of which carry a comment promising they match "VERBATIM so
+ * the wire shape never drifts" — a comment doing a type's job. A comment cannot
+ * fail a build; an import can. Those mirrors live in repos this package does not
+ * own, so this tuple does not fix them by existing — it makes the fix possible:
+ *
+ *   - marketplace            `types.ts:102`
+ *   - onboarding             `workspace-templates.ts:27`
+ *   - synap-backend          `package-definition.ts:204` (exports its own
+ *                            `PackageDependencyKind` — the closest peer)
+ *   - hub-protocol REST      `rest/packages.ts:140` (zod enum)
+ *   - browser                `InstallPackageDialog.tsx:262`
+ *   - control-plane-api      `routes/packages.ts:436` (zod enum)
+ *
+ * ⚠️ `'automation'` IS RETIRED VOCABULARY, deliberately still listed here.
+ * CP migration `0049_package_vocabulary` retired the `automation` package
+ * category in favour of `workflow` ("workflow — a triggered/sequenced run
+ * (absorbs 'automation' + 'playbook')", `PACKAGE_TYPES` in CP
+ * `db/schema/packages.ts`). A dependency's `kind` names the TYPE of package it
+ * points at, so this vocabulary should track `PACKAGE_TYPES` — meaning the live
+ * spelling is `workflow`, not `automation`.
+ *
+ * It is NOT renamed here, on purpose. This is latent, not live: 0/21 templates
+ * declare any `kind` other than the default `'workspace'`. And all four wire
+ * enums (CP + hub zod, above) still accept `'automation'` and do NOT accept
+ * `'workflow'` — so emitting `'workflow'` today would be rejected with a 400 at
+ * both doors, and dropping `'automation'` from this tuple would make any
+ * consumer that derives a zod enum from it start rejecting a value the wire
+ * still legally accepts (a published third-party package may carry it; CP's own
+ * schema permits it). Narrowing must therefore follow the wire, not lead it.
+ *
+ * ORDERED FIX (each step deployable alone, no flag day):
+ *   1. Widen the CP + hub zod enums to accept BOTH `'automation'` and `'workflow'`.
+ *   2. Add `'workflow'` here; mark `'automation'` deprecated; migrate any authored use.
+ *   3. Once no payload carries `'automation'`, drop it from the wire enums and this tuple.
+ */
+declare const PACKAGE_DEPENDENCY_KINDS: readonly ["workspace", "capability", "automation"];
+/** What a `TemplateDependency` points at. Derived — never re-declare the list. */
+type PackageDependencyKind = (typeof PACKAGE_DEPENDENCY_KINDS)[number];
+interface TemplateDependency {
+    /** Slug of the template/package this one depends on. */
+    slug: string;
+    /**
+     * What the dependency is. Default `'workspace'`. Only `'workspace'`
+     * dependencies can be `compose`d; `'capability'`/`'automation'` are always
+     * `require`d present without merging.
+     */
+    kind?: PackageDependencyKind;
+    /**
+     * How this template relates to the dependency:
+     * - `'compose'`: this template is an OVERLAY on the dependency's workspace.
+     *   The base is installed first if absent, then this template's profiles /
+     *   roles / relations / views are applied ADDITIVELY onto the base workspace
+     *   — no separate workspace is created for this template.
+     * - `'require'` (default): the dependency must be present on the pod as its
+     *   own artifact, but this template does not merge into it.
+     */
+    relation?: 'compose' | 'require';
+    /**
+     * Short human reason shown in the install-time "this also installs…" prompt.
+     */
+    reason?: string;
+}
+interface TemplateMeta {
+    slug: string;
+    name: string;
+    description: string;
+    icon: string;
+    color: string;
+    tags?: string[];
+    isPublic?: boolean;
+}
+interface WorkspaceYaml {
+    /** Template metadata — not sent to backend, used for listing/UI */
+    meta: TemplateMeta;
+    /** The workspace definition sent to createFromDefinition */
+    workspace: {
+        name: string;
+        description: string;
+        proposalId?: string;
+        subtype?: string;
+        /**
+         * Workspace classifier — consumed by createFromDefinition (settings.workspaceType,
+         * creator-role + agent-workspace behavior). Mirrors the backend union.
+         */
+        workspaceType?: 'personal' | 'agent' | 'project' | 'operational';
+        visibility?: string;
+        /** Capabilities this workspace provides (e.g. "brand.library", "content.pipeline") */
+        capabilities?: string[];
+        /**
+         * Cross-workspace dependency roles.
+         * E.g. { brand: "consumer", content: "provider" }
+         * "consumer" = this workspace reads from another workspace of that capability
+         * "provider" = this workspace provides that capability to others
+         */
+        sourceRoles?: Record<string, TemplateSourceRole>;
+        /**
+         * Pins which workspace supplies each capability domain for this workspace.
+         * E.g. { brand: { workspaceId: "..." } } — read by the IS source resolver
+         * (resolveBrandWorkspaceId / resolveFoundationWorkspaceId) before falling
+         * back to provider role. Usually set at runtime, not in a template, but
+         * carried here so it round-trips through the canonical seam.
+         */
+        defaultSources?: Record<string, TemplateDefaultSource>;
+    };
+    /** Entity profiles — the data schema */
+    profiles: TemplateProfile[];
+    /** Curated views — only the ones that add value */
+    views?: TemplateView[];
+    /** Schema-level links between entity types */
+    entityLinks?: TemplateEntityLink[];
+    /** Initial data to seed on workspace creation */
+    seedEntities?: TemplateSeedEntity[];
+    /** Relations between seed entities, created on provisioning */
+    suggestedRelations?: TemplateSuggestedRelation[];
+    /** Entity-card display templates */
+    displayTemplates?: TemplateDisplayTemplate[];
+    /** App reference — what opens as first screen */
+    app?: TemplateAppRef;
+    /** Browser sidebar + layout config */
+    layout?: TemplateLayoutConfig;
+    /** Bento dashboard */
+    bento?: {
+        viewName?: string;
+        blocks?: TemplateBentoBlock[];
+    };
+    /** Per-profile entity bento layouts */
+    profileEntityBentoTemplates?: TemplateProfileEntityBentoTemplates;
+    /** Automations to install on workspace creation */
+    automations?: TemplateAutomation[];
+    /** Playbooks (session templates) seeded with the workspace */
+    playbooks?: TemplatePlaybook[];
+    /** Capability templates (tools/connectors) to install on provisioning */
+    integrations?: TemplateIntegration[];
+    /**
+     * Per-workspace onboarding context. Written to workspace.settings.onboarding
+     * and read by the shared `onboard` skill to run a domain-specific adaptive
+     * interview — no per-domain skill file needed.
+     */
+    onboarding?: TemplateOnboarding;
+    /** Inherit profiles/views from other workspaces */
+    extends?: TemplateExtendsRef[];
+    /**
+     * Template-composition dependencies — other templates this one needs. The
+     * install resolver installs missing dependencies first and, for a `compose`
+     * dependency, layers this template additively onto the dependency's
+     * workspace. See {@link TemplateDependency}.
+     */
+    dependencies?: TemplateDependency[];
+}
+
+declare const WORKSPACE_TEMPLATES: Record<string, WorkspaceYaml>;
+type WorkspaceTemplateSlug = keyof typeof WORKSPACE_TEMPLATES;
+declare function getWorkspaceTemplate(slug: string): WorkspaceYaml | undefined;
+declare function listWorkspaceTemplates(): WorkspaceYaml[];
+/**
+ * Public templates only (`meta.isPublic !== false`). This is a CONVENIENCE
+ * filter for the default picker — NOT a security boundary: the private YAML
+ * still ships in the published tarball, so anything that must not leak cannot
+ * rely on this. `listWorkspaceTemplates()` returns all of them (CLI, seeder,
+ * tripwire need the full set). Publicity is also expressed per-entry as
+ * `CatalogEntry.isPrivate` by `mergeCatalog()`, so a caller can pass ALL
+ * templates and filter at the presentation layer instead of choosing a list
+ * function up front — the merge door itself never filters (it stays pure).
+ */
+declare function listPublicTemplates(): WorkspaceYaml[];
+
+/**
+ * mergeCatalog — the ONE merge door for the workspace-template catalog.
+ * ====================================================================
+ *
+ * Both marketplace entry points (browser + CLI) and the pod need to show ONE
+ * list of installable workspace templates drawn from TWO sources:
  *
- * Usage (browser / backend / CLI):
+ *   1. BUNDLED — the canonical `@synap-core/workspace-templates` package that
+ *      ships inside every client (this package). Always present, zero network.
+ *   2. REMOTE  — rows in the control-plane package registry (`GET /api/packages`),
+ *      which includes both the official templates re-published by
+ *      `seed-templates.ts` AND private / third-party packages that never shipped
+ *      in the bundle.
  *
- *   import { getWorkspaceTemplate, listPublicTemplates } from '@synap-core/workspace-templates';
+ * The two overlap: every official template exists in BOTH sources (once bundled,
+ * once seeded to the CP). Naively concatenating them shows 21 duplicate cards.
+ * `mergeCatalog` de-dupes them into ONE catalog with a deterministic winner.
  *
- *   const template = getWorkspaceTemplate('brand-library');
- *   // template.workspace.name === 'Brand Library'
- *   // template.app.kind === 'native'
- *   // template.layout.defaultApp === 'brandLibrary'
+ * WHY THIS LIVES HERE (and is PURE):
+ *   This is the ONLY module the root `pnpm-workspace.yaml` lets `synap-cli`,
+ *   `browser`, `synap-control-plane-api`, AND `synap-backend/packages/api` all
+ *   resolve. `@synap-core/marketplace` pulls React and is `private: true`, so the
+ *   Node CLI cannot import it. Keep this file pure data — no fetch, no auth, no
+ *   React, no Node-only APIs. Each entry point has a DIFFERENT transport (browser
+ *   cookie/`cpFetch`, CLI Bearer, pod anonymous); a door that fetched would force
+ *   ONE auth model on all three and become the next lossy seam. Transport lives
+ *   in the consumers; this door only merges arrays they already fetched.
+ */
+
+/**
+ * A bundled template — the canonical `WorkspaceYaml` this package ships. Callers
+ * pass `listPublicTemplates()` (18) or `listWorkspaceTemplates()` (21); the door
+ * merges whatever it is given and does NOT filter (see the publicity note below).
+ */
+type BundledEntry = WorkspaceYaml;
+/**
+ * A control-plane registry row, mapped into the minimal shape the door needs.
+ * Consumers build this from a `MarketplacePackage` (browser) / the CP
+ * `GET /api/packages` JSON (CLI) — a thin, transport-specific projection.
+ *
+ * `definition` is carried OPAQUE: it is both (a) the install payload the consumer
+ * feeds back to the pod, and (b) the home of the ONE comparable version signal,
+ * `definition.sourcePackage.version` — the real npm semver of the published
+ * `@synap-core/workspace-templates` build that generated an official row
+ * (`seed-templates.ts` stamps it). The door only reads that one nested field; the
+ * rest of `definition` is passed through untouched.
+ */
+interface RemoteEntry {
+    slug: string;
+    name: string;
+    description?: string;
+    /** CP package category / type (e.g. `"workspace"`, `"view"`). */
+    category?: string;
+    tags?: string[];
+    icon?: string | null;
+    /**
+     * `true` when the CP row is not publicly listed (`isPublic === false`). Browse
+     * rows leave this `undefined` BY CONSTRUCTION — the browse route hard-filters
+     * `WHERE is_public = true`, so every browse row is public; `undefined` ⇒ public,
+     * never "unknown-so-hide".
+     */
+    isPrivate?: boolean;
+    /**
+     * The CP `definition` jsonb — opaque install payload. The door reads only
+     * `definition.sourcePackage.version` (the winner signal). Absent on browse rows
+     * (the list route strips `definition`), which is fine: absence ⇒ bundle wins.
+     */
+    definition?: {
+        sourcePackage?: {
+            name?: string;
+            version?: string;
+        };
+        [k: string]: unknown;
+    };
+}
+/** Whether the caller could reach / authenticate against the remote source. */
+type RemoteSourceStatus = "ok" | "unauthenticated" | "unreachable";
+interface MergeCatalogInput {
+    /** Bundled templates (this package). Always "ok" — it is in-process data. */
+    bundled: BundledEntry[];
+    /** Already-fetched CP rows. Empty/omitted when the fetch failed. */
+    remote?: RemoteEntry[];
+    /**
+     * This client's bundled-package version (`package.json` `version`, live `0.6.0`).
+     * Compared against each remote row's `sourcePackage.version` to decide whether
+     * THIS client's bundle is stale. Callers pass the compiled-in package version.
+     */
+    bundleVersion: string;
+    /**
+     * The transport's verdict on the remote fetch. `"ok"` (default) ⇒ merge the
+     * `remote` array. `"unauthenticated"` / `"unreachable"` ⇒ ignore `remote` and
+     * surface the degradation in `sources.remote`, so the consumer can render
+     * "18 available — private ones need login" instead of FAILING OPEN EMPTY.
+     */
+    remoteStatus?: RemoteSourceStatus;
+}
+interface CatalogEntryBase {
+    slug: string;
+    name: string;
+    description?: string;
+    /** Package category / type. Bundled templates are always `"workspace"`. */
+    category?: string;
+    tags: string[];
+    icon?: string | null;
+    /** `true` ⇒ not publicly listed (internal bundled template, or private CP row). */
+    isPrivate: boolean;
+}
+/** A catalog entry backed by a bundled template. Install via `toWorkspaceDefinition()` / `toPackageDefinition()` on `template`. */
+interface BundledCatalogEntry extends CatalogEntryBase {
+    source: "bundled";
+    template: WorkspaceYaml;
+}
+/** A catalog entry backed by a CP registry row. Install from `remote.definition`. */
+interface RemoteCatalogEntry extends CatalogEntryBase {
+    source: "remote";
+    remote: RemoteEntry;
+}
+/** One merged card. `source` discriminates the install path; common fields feed a picker. */
+type CatalogEntry = BundledCatalogEntry | RemoteCatalogEntry;
+interface MergeCatalogResult {
+    entries: CatalogEntry[];
+    /**
+     * Per-source health. LOAD-BEARING, not decoration: it is what lets a consumer
+     * distinguish "remote returned nothing" from "remote unreachable" and avoid the
+     * FAILS-OPEN-EMPTY trap (agent sees empty catalog → thinks pod is empty → dupes).
+     */
+    sources: {
+        bundled: "ok";
+        remote: RemoteSourceStatus;
+    };
+}
+/**
+ * Merge bundled + remote template catalogs into ONE de-duplicated list.
+ *
+ * DEDUPE KEY = `slug` — NOT `slug@version`. This is forced by the live data, not
+ * a preference: every CP flagship row is hardcoded `version: "1.0.0"`
+ * (`seed-templates.ts`) and `TemplateMeta` carries NO version field at all, so a
+ * `slug@version` key would collide on nothing → 21 duplicate cards. The real
+ * per-build version lives only in `definition.sourcePackage.version`, which is
+ * the WINNER signal, never the identity key.
  *
- * YAML source files live in src/*.yaml — AI-friendly, commentable, mergeable.
- * Run `pnpm build` to regenerate src/templates.ts from YAML.
+ * CONFLICT RESOLUTION (remote slug already claimed by a bundled template):
+ *   • remote `sourcePackage.version` strictly > `bundleVersion` → remote wins
+ *     (this client is stale — the CP has a fresher official build).
+ *   • otherwise (equal / older / no `sourcePackage`) → BUNDLE wins. The
+ *     no-`sourcePackage` case is a third-party package SQUATTING an official slug;
+ *     the bundle wins unconditionally (squatting defense).
+ *
+ * A remote slug that does NOT collide with any bundled template is a DISTINCT
+ * entry (a private or third-party package) and is always kept.
+ */
+declare function mergeCatalog(input: MergeCatalogInput): MergeCatalogResult;
+
+/**
+ * @synap-core/workspace-templates — Definition adapter
+ *
+ * Converts a YAML template (WorkspaceYaml) into the flat payload shape that
+ * the backend `workspaces.createFromDefinition` mutation + Hub REST
+ * `/workspaces/from-definition` endpoint expect.
+ *
+ * This is the single canonical seam: every consumer (browser app, onboarding,
+ * CLI, marketplace) provisions a workspace through this function so the wire
+ * shape never drifts per call-site.
+ */
+
+/** A widget block as the wire expects it: `bentoLayout[]`, keyed by `widgetType`. */
+interface BentoWidgetBlockWire {
+    widgetType: string;
+    pos: TemplateBentoBlock['pos'];
+    config?: Record<string, unknown>;
+}
+/** A view block as the wire expects it: `bentoViewBlocks[]`, keyed by `viewName`. */
+interface BentoViewBlockWire {
+    kind: 'view';
+    viewName: string;
+    pos: TemplateBentoBlock['pos'];
+    overrides?: Record<string, unknown>;
+}
+interface SplitBentoBlocks {
+    bentoLayout: BentoWidgetBlockWire[];
+    bentoViewBlocks: BentoViewBlockWire[];
+}
+declare function splitBentoBlocks(blocks: TemplateBentoBlock[] | undefined): SplitBentoBlocks;
+/** The flat definition object accepted by createFromDefinition. */
+interface WorkspaceDefinitionInput {
+    workspaceName: string;
+    description: string;
+    proposalId?: string;
+    profiles: WorkspaceYaml['profiles'];
+    views: NonNullable<WorkspaceYaml['views']>;
+    entityLinks: NonNullable<WorkspaceYaml['entityLinks']>;
+    seedEntities: NonNullable<WorkspaceYaml['seedEntities']>;
+    suggestedRelations?: WorkspaceYaml['suggestedRelations'];
+    displayTemplates?: WorkspaceYaml['displayTemplates'];
+    layoutConfig: WorkspaceYaml['layout'] | undefined;
+    bentoViewName?: string;
+    /**
+     * WIDGET half of the authored bento union. The door declares this field
+     * (`workspaces.createFromDefinition` zod) and the pod maps it as widgets via
+     * `widget.widgetType`. It was missing from this interface entirely, which is
+     * why `toWorkspaceDefinition` had nowhere to put widgets and dumped the whole
+     * union into `bentoViewBlocks` — where every widget was silently filtered out.
+     */
+    bentoLayout?: BentoWidgetBlockWire[];
+    /** VIEW half of the authored bento union — resolved against the viewMap. */
+    bentoViewBlocks?: BentoViewBlockWire[];
+    profileEntityBentoTemplates?: WorkspaceYaml['profileEntityBentoTemplates'];
+    workspaceSubtype?: string;
+    workspaceType?: NonNullable<WorkspaceYaml['workspace']>['workspaceType'];
+    workspaceVisibility?: string;
+    workspaceCapabilities?: string[];
+    sourceRoles?: NonNullable<WorkspaceYaml['workspace']>['sourceRoles'];
+    defaultSources?: NonNullable<WorkspaceYaml['workspace']>['defaultSources'];
+    /** Per-workspace onboarding context — written to settings.onboarding. */
+    onboarding?: WorkspaceYaml['onboarding'];
+    /**
+     * Template-composition dependencies. MUST be forwarded: the backend resolves
+     * these BEFORE materializing this workspace (`workspaces.createFromDefinition`
+     * → `materializeWorkspaceCore` Step 0 → `resolvePackageDependencies`), which
+     * is what installs a `require`d base FIRST and makes shared-profile base
+     * seeding deterministic. Dropping this field silently de-orders provisioning
+     * on the tRPC/UI door — see the note in `toWorkspaceDefinition`.
+     */
+    dependencies?: WorkspaceYaml['dependencies'];
+}
+interface ToDefinitionResult {
+    definition: WorkspaceDefinitionInput;
+    /** Stable idempotency key — the template's proposalId or slug. */
+    proposalId: string;
+    /** Display name for the new workspace. */
+    workspaceName: string;
+    /** Template id for telemetry / dedup. */
+    templateId: string;
+}
+/**
+ * Resolve a template (by slug or YAML object) into the createFromDefinition
+ * payload. Pass `nameOverride` to rename the workspace at creation time.
+ */
+declare function toWorkspaceDefinition(slugOrYaml: string | WorkspaceYaml, nameOverride?: string): ToDefinitionResult;
+/**
+ * The unified `PackageDefinition` shape consumed by `POST /api/hub/packages/apply`
+ * (CLI `synap launch`) and the CP package registry seeder. It composes the
+ * workspace definition with the capability/playbook/onboarding layers. Mirrors
+ * `PackageDefinition` in synap-backend `package-definition.ts`. Typed loosely on
+ * the layered fields to avoid a backend import; the wire validation lives in the
+ * apply endpoint.
+ */
+interface PackageDefinitionOutput {
+    _meta: {
+        slug: string;
+        icon?: string;
+        color?: string;
+        tags?: string[];
+        isPublic?: boolean;
+        requiredTier?: string | null;
+    };
+    workspaceName: string;
+    description: string;
+    workspaceType?: WorkspaceYaml['workspace']['workspaceType'];
+    workspaceSubtype?: string;
+    workspaceVisibility?: string;
+    workspaceCapabilities?: string[];
+    sourceRoles?: WorkspaceYaml['workspace']['sourceRoles'];
+    defaultSources?: WorkspaceYaml['workspace']['defaultSources'];
+    profiles: WorkspaceYaml['profiles'];
+    views: NonNullable<WorkspaceYaml['views']>;
+    suggestedEntities: NonNullable<WorkspaceYaml['seedEntities']>;
+    suggestedRelations?: WorkspaceYaml['suggestedRelations'];
+    displayTemplates?: WorkspaceYaml['displayTemplates'];
+    entityLinks?: WorkspaceYaml['entityLinks'];
+    /** WIDGET half of the authored bento union — mapped by the pod via `widgetType`. */
+    bentoLayout?: BentoWidgetBlockWire[];
+    /**
+     * VIEW half of the authored bento union. Widgets go to `bentoLayout`, views
+     * here — the pod splits by field (create-workspace-from-definition.ts:1373
+     * reads `bentoViewBlocks`), so both wire fields must be carried. The apply
+     * door's `PackageApplySchema` now declares this field (it is a plain
+     * `z.object`, so an undeclared field would be silently stripped) — the inbound
+     * seam is closed to match this outbound emit.
+     */
+    bentoViewBlocks?: BentoViewBlockWire[];
+    bentoViewName?: string;
+    profileEntityBentoTemplates?: WorkspaceYaml['profileEntityBentoTemplates'];
+    layoutConfig?: WorkspaceYaml['layout'];
+    capabilities?: WorkspaceYaml['integrations'];
+    playbooks?: WorkspaceYaml['playbooks'];
+    onboarding?: WorkspaceYaml['onboarding'];
+    /** Template-composition dependencies — resolved by the apply endpoint. */
+    dependencies?: WorkspaceYaml['dependencies'];
+}
+/**
+ * Resolve a template (by slug or YAML object) into the full `PackageDefinition`
+ * accepted by `POST /api/hub/packages/apply` and the CP registry seeder. This is
+ * the single seam the CLI and control-plane use so they read from the canonical
+ * package instead of disk-stored JSON.
  */
-export type { WorkspaceYaml, TemplateMeta, TemplateAppRef, TemplateAppKind, TemplateProfile, TemplateProperty, TemplateView, TemplateSidebarItem, TemplateSidebarSurface, TemplateLayoutConfig, TemplateBentoBlock, TemplateEntityLink, TemplateSeedEntity, TemplateSuggestedRelation, TemplateDisplayTemplate, TemplateIntegration, TemplateAutomation, TemplateExtendsRef, TemplateProfileEntityBentoTemplates, TemplateDefaultSource, TemplateSourceRole, TemplateOnboarding, TemplateOnboardingCollectTarget, TemplatePlaybook, TemplatePlaybookParam, } from './types.js';
-export { WORKSPACE_TEMPLATES, getWorkspaceTemplate, listWorkspaceTemplates, listPublicTemplates, } from './templates.js';
-export type { WorkspaceTemplateSlug } from './templates.js';
-export { toWorkspaceDefinition, toPackageDefinition } from './define.js';
-export type { WorkspaceDefinitionInput, ToDefinitionResult, PackageDefinitionOutput, } from './define.js';
-//# sourceMappingURL=index.d.ts.map
+declare function toPackageDefinition(slugOrYaml: string | WorkspaceYaml): PackageDefinitionOutput;
+
+export { type BentoViewBlockWire, type BentoWidgetBlockWire, type BundledCatalogEntry, type BundledEntry, type CatalogEntry, type MergeCatalogInput, type MergeCatalogResult, PACKAGE_DEPENDENCY_KINDS, type PackageDefinitionOutput, type PackageDependencyKind, type RemoteCatalogEntry, type RemoteEntry, type RemoteSourceStatus, type SplitBentoBlocks, type TemplateAppKind, type TemplateAppRef, type TemplateAutomation, type TemplateBentoBlock, type TemplateDefaultSource, type TemplateDependency, type TemplateDisplayTemplate, type TemplateEntityLink, type TemplateExtendsRef, type TemplateIntegration, type TemplateLayoutConfig, type TemplateMeta, type TemplateOnboarding, type TemplateOnboardingCollectTarget, type TemplatePlaybook, type TemplatePlaybookParam, type TemplateProfile, type TemplateProfileEntityBentoTemplates, type TemplateProperty, type TemplateSeedEntity, type TemplateSidebarItem, type TemplateSidebarSurface, type TemplateSourceRole, type TemplateSuggestedRelation, type TemplateView, type ToDefinitionResult, WORKSPACE_TEMPLATES, type WorkspaceDefinitionInput, type WorkspaceTemplateSlug, type WorkspaceYaml, getWorkspaceTemplate, listPublicTemplates, listWorkspaceTemplates, mergeCatalog, splitBentoBlocks, toPackageDefinition, toWorkspaceDefinition };