@synap-core/workspace-templates 0.12.0 → 0.24.0

package/dist/define-DqoItRiR.d.ts

@@ -0,0 +1,1370 @@
+import { ProfilePresentation } from '@synap-core/types/presentation';
+import { SpaceBrief, SpaceTemplateRule, SpaceTemplateSkill, SpaceBriefCollectTarget } from '@synap-core/types/space-brief';
+import { CapabilityIntentSlug } from '@synap-core/types/capability-intents';
+
+/**
+ * @synap-core/workspace-templates — Types
+ *
+ * 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, WorkspaceJsonValue>;
+    /** For kind='url': external URL to open */
+    url?: string;
+    /** Human label */
+    title?: string;
+}
+type WorkspaceJsonValue = string | number | boolean | null | WorkspaceJsonValue[] | {
+    [key: string]: WorkspaceJsonValue;
+};
+type WorkspacePrimarySurface = {
+    kind: "app";
+    appId: string;
+    rendererType: "native";
+    title?: string;
+    props?: Record<string, WorkspaceJsonValue>;
+} | {
+    kind: "app";
+    appId: string;
+    rendererType: "external";
+    url: string;
+    title?: string;
+    props?: Record<string, WorkspaceJsonValue>;
+} | {
+    kind: "cell";
+    cellKey: string;
+    title?: string;
+    props?: Record<string, WorkspaceJsonValue>;
+} | {
+    /**
+     * Ordinary website. Unlike an external `app`, this has no trusted app
+     * identity and is always opened through the Browser's unprivileged URL
+     * surface.
+     */
+    kind: "url";
+    url: string;
+    title?: string;
+    /**
+     * The pod app this website is (spec 17 §7.1): its Client ID Metadata
+     * Document URL. A launch hint only: the Browser opens the site with the
+     * space's pod `iss` so the app starts that pod's OAuth flow. It grants
+     * no identity, bridge or credential; the site stays an unprivileged URL.
+     * Mirrors the pod's `WorkspacePrimarySurface` (@synap/database).
+     */
+    podApp?: {
+        clientId: string;
+    };
+} | {
+    kind: "view";
+    viewId: string;
+    title?: string;
+};
+/**
+ * Authoring-time view reference. View IDs do not exist until provisioning, so
+ * templates and packages address a view by its stable authored name and/or
+ * slug. The pod resolves this to `WorkspacePrimarySurface` before persistence.
+ */
+type WorkspacePrimarySurfaceViewReference = {
+    kind: "view";
+    viewName: string;
+    viewSlug?: string;
+    title?: string;
+} | {
+    kind: "view";
+    viewName?: string;
+    viewSlug: string;
+    title?: string;
+};
+type TemplatePrimarySurface = WorkspacePrimarySurface | WorkspacePrimarySurfaceViewReference;
+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 of the profile DEFINITION — who can USE this vocabulary.
+     * `system` = pod-wide; `shared` = ONE row reachable from other workspaces via
+     * a `profile_workspace_access` grant; omit or `workspace` = this workspace
+     * only. Orthogonal to `entityScope` below — do not conflate the two axes. */
+    scope?: string;
+    /**
+     * Placement of the profile's ENTITY ROWS — where the data LANDS.
+     * `pod` → entities are created with `workspace_id = NULL` and are therefore
+     * visible in every workspace; `workspace` (the backend default when omitted)
+     * → entities belong to the workspace that created them.
+     *
+     * Independent of `scope`: a `shared` profile can still mint workspace-scoped
+     * rows, and a `workspace`-scoped profile could in principle mint pod-wide
+     * ones. Both provisioning doors thread this verbatim into
+     * `ProfileRepository.create` (`create-workspace-from-definition.ts:1149`,
+     * `reconcile-workspace-from-definition.ts:319`) — omitting it inherits the
+     * repo default (`workspace`), which is the unchanged behaviour for templates
+     * that do not declare it. Applied on CREATE only: neither door flips the
+     * `entity_scope` of an existing profile (a divergence is reported as an
+     * advisory `scopeConflict` and the live row is left alone).
+     */
+    entityScope?: "pod" | "workspace";
+    /** 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[];
+    /**
+     * The kind's / role's ONE lifecycle (work model L1): which select property it
+     * is, and a category for each of its options. The pod folds the options onto
+     * that property and declares it (`declareLifecycle`); boards, pipelines and
+     * governance then read the category, never the option name.
+     * `validate.ts` (`lifecycle-*` rules) requires the option keys to be the
+     * property's `enumValues`, same order, and every template that declares this
+     * profile to declare the same lifecycle.
+     *
+     * This is the COMPILED shape. The YAML may instead adopt one of the ten base
+     * lifecycles (`TemplateLifecycleAdoption`, `lifecycle-presets.ts`) and may
+     * omit the select's `enumValues`; `resolveLifecyclePresets` compiles both
+     * into this shape before validation, generation and publish.
+     */
+    lifecycle?: TemplateLifecycle;
+    /**
+     * How entities of this kind PRESENT themselves (entity rendering, decision
+     * 8): the family (media · document · link · record · work), where its media
+     * lives, and optional per-altitude fields. Stored on the pod as
+     * `uiHints.presentation` and converged on every apply. Parsed by the ONE
+     * parser, `parseProfilePresentation` (`@synap-core/types/presentation`);
+     * `validate.ts` (`presentation-*` rules) also requires every named property
+     * to exist on this profile and every declaration of the slug to agree.
+     */
+    presentation?: ProfilePresentation;
+}
+/** Fixed categories (`@synap-core/types/lifecycle` LIFECYCLE_CATEGORIES). */
+type TemplateLifecycleCategory = "open" | "active" | "paused" | "done" | "lost";
+interface TemplateLifecycleOption {
+    /** The stored value — one of the property's `enumValues`. */
+    key: string;
+    label?: string;
+    category: TemplateLifecycleCategory;
+    /** A `UnitTone` token; absent ⇒ the category's default tone. */
+    tone?: string;
+    /** Only a person may move a thing INTO this option. */
+    humanOnly?: boolean;
+    /**
+     * Days a thing may sit in this option before it is STUCK (an intent
+     * surface's Stuck count). Whole days, 1–3650; open/active/paused only.
+     */
+    stuckAfterDays?: number;
+    /**
+     * The date property this step is bound to (an invoice's `dueDate` while
+     * `sent`): the thing is LATE once that date passes while it stands here.
+     * A property slug; open/active/paused only.
+     */
+    dateBinding?: string;
+    /**
+     * The wait this step declares: an ACTIVE step such as "sent" waits on
+     * someone without being a pause. Open/active/paused only.
+     */
+    waits?: TemplateLifecycleOptionWaits;
+}
+/** A step's declared wait (the pod's `LifecycleOptionWaits`). */
+interface TemplateLifecycleOptionWaits {
+    /** A hold's `on`, never `unspecified`: person · agent · external · thing · decision · date · nobody. */
+    on: "person" | "agent" | "external" | "thing" | "decision" | "date" | "nobody";
+    /** The finer kind (`WAIT_KINDS`: "signature", "payment"…); absent ⇒ derived from `on`. */
+    waitKind?: string;
+    /** The property or relation naming WHO or WHAT is waited on (a deal's `contactId`). */
+    refFrom?: string;
+    /** The date property that ends the wait (a lead's `nextActionAt`). */
+    dateBinding?: string;
+}
+interface TemplateLifecycle {
+    /** The lifecycle property's slug (a select of this profile). */
+    property: string;
+    options: TemplateLifecycleOption[];
+}
+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;
+}
+/**
+ * A document a template carries. Mirrors `WorkspaceDocumentInput`
+ * (synap-backend `@synap-core/types/workspaces/definition`) VERBATIM; the pod
+ * installs it through `utils/template-documents.ts` (the one create door,
+ * system-authored, owned by the installer, identified in the space by `slug`).
+ */
+interface TemplateDocument {
+    /** Stable id inside the template, kebab-case. Never rename it: the space knows the document by it. */
+    slug: string;
+    /** The document's name (its one title). */
+    title: string;
+    /** Markdown body; may carry `synap-cell` / `synap-section` embeds. */
+    content: string;
+    /**
+     * What its embeds read (a living document's scope): `space` = the space it
+     * is installed in, `pod` = the whole pod. Absent = no scope.
+     */
+    scope?: "space" | "pod";
+}
+interface TemplateEntityLink {
+    sourceProfileSlug: string;
+    targetProfileSlug: string;
+    type: string;
+    label?: string;
+    /**
+     * Every record of the source kind should carry this link (an edge of `type`
+     * to the target kind). Several rows of one source kind and one `type` are ONE
+     * rule, met by an edge to any of their targets. The pod's template reconcile
+     * stores it on `profile_relations.metadata` (`required`, `requiredBy`); its
+     * create doors warn when a new record leaves it out (never refuse yet) and
+     * template health lists the records missing it. Omitted = says nothing (a
+     * mark another template set stays); `false` clears the mark.
+     */
+    required?: boolean;
+}
+/**
+ * A domain-level relation TYPE definition — a `relation_defs` row, the workspace's
+ * relation vocabulary. Distinct from {@link TemplateEntityLink}, which is a
+ * profile→profile EDGE (and only carries `type` + `label`). A relation def stands
+ * alone: it has no source/target profile pairing and it carries the rich metadata
+ * (`description`, `isDirectional`, `uiHints`) that the entity-link path drops.
+ *
+ * Mirrors `DefaultRelationDef` in synap-backend
+ * `packages/database/src/utils/default-relation-defs.ts` VERBATIM — the door
+ * find-or-creates a `relation_defs` row from each entry (idempotent by
+ * `slug` within the workspace), which is `ensureDefaultRelationDefs`'s body.
+ */
+interface TemplateRelationDef {
+    slug: string;
+    displayName: string;
+    description?: string;
+    isDirectional?: boolean;
+    uiHints?: {
+        category?: "workflow" | "social" | "reference" | "hierarchy";
+        inverseLabel?: 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" | "document";
+    appId?: string;
+    viewName?: string;
+    viewId?: string;
+    /** kind "document": the `documents[].slug` it opens (the pod stores its id beside it). */
+    documentSlug?: 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;
+    /**
+     * Canonical first screen for this workspace.
+     *
+     * `undefined` means the template has no opinion during reconciliation,
+     * `null` explicitly returns the workspace to its home surface, and a
+     * descriptor replaces the current primary surface. */
+    primarySurface?: TemplatePrimarySurface | null;
+    /** Compatibility input only. New templates should use `app:` or `primarySurface`. */
+    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>>;
+    };
+}
+/** 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;
+}
+type TemplateOnboardingCollectTarget = SpaceBriefCollectTarget;
+/**
+ * A template's brief. `rules` is NOT authored here — a template declares its
+ * rules at the top level (`rules:`); the pod stores only refs to them.
+ */
+type TemplateOnboarding = Omit<SpaceBrief, "rules">;
+/**
+ * A rule a template installs in its space — applied through the pod's ONE rule
+ * door, stamped so a later template update never overwrites a rule the user
+ * edited. `key` is its stable identity across template versions.
+ */
+type TemplateRule = SpaceTemplateRule;
+/**
+ * A SKILL a template declares for its space (`skills:`). Same shape as a rule —
+ * the template declares, the pod LINKS the skill to the space at install and
+ * keeps a ref in the brief. `mode: "always"` is prepended to every session or
+ * run started in the space; `on-demand` is surfaced and ranked first instead.
+ * Validation (`validateSpaceSkillDeclaration`) is shared with the pod's applier.
+ */
+type TemplateSkill = SpaceTemplateSkill;
+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";
+    /**
+     * Legacy fan-out modes stay strings. `pinned` is an object: first eligible
+     * pin, then `fallback`. Entity ids are not part of this shape.
+     */
+    inputStrategy?: "none" | "static" | "rotating" | "query" | {
+        kind: "pinned";
+        fallback?: {
+            filter?: Record<string, unknown>;
+            orderBy?: string;
+            orderDir?: "asc" | "desc";
+        };
+    };
+    channelSpec?: {
+        type: "GROUP" | "AGENT_COLLAB" | "THREAD";
+        members?: string[];
+        aiReactionMode?: "on_mention" | "always" | "never";
+    };
+    /**
+     * A cron schedule that maintains ONE backing cron automation (a single
+     * `playbook_run` node) which the pod's `automation-cron-scheduler` fires.
+     * `enabled` is read STRICTLY (`materializePlaybookCronAutomation` requires
+     * `enabled === true`) — omit it and the backing cron is NEVER created, so the
+     * playbook silently never fires. Always set it explicitly.
+     */
+    schedule?: {
+        cron: string;
+        enabled: boolean;
+    } | null;
+    /** tool/skill keys this playbook grants. */
+    grants?: string[];
+    /**
+     * Free-form playbook metadata → `playbooks.metadata`. Carries the propose-only
+     * governance marker for unattended maintenance playbooks:
+     * `{ governance: { forceProposeWrites: true } }` — every agent write in the
+     * playbook's scheduled sessions then routes to a reviewable proposal.
+     * `lineage` is a CONVENTION (no reader enforces it): where the process comes
+     * from (an APQC PCF id, a named method, O*NET task ids).
+     */
+    metadata?: Record<string, unknown> & {
+        lineage?: TemplatePlaybookLineage;
+    };
+    /**
+     * The entity kind this playbook operates over, persisted to
+     * `playbooks.subject_profile`. Makes the playbook matchable by
+     * `playbooks.matchForEntity` (filters `subject_profile->>'profileSlug'`), so a
+     * captured entity of this kind can auto-launch the playbook as a session.
+     *
+     * `statusProperty` names the subject kind's SELECT property that holds its
+     * lifecycle (e.g. `post-status`). It is what ties `stages[].subjectStatus`
+     * to the subject: advancing into a stage writes that value (governed), and
+     * the subject entering the value advances an open run to the stage.
+     * `validate.ts` checks it is a select property of the kind, and that every
+     * `subjectStatus` / activator `status` is one of its enum values.
+     */
+    subjectProfile?: {
+        profileSlug: string;
+        /**
+         * Narrows a kind-bound SCHEDULE's fan-out: a JSON string of
+         * `{ "properties.<key>": value }`. A STRING, because the pod's cron door
+         * keeps only a string (`readSubjectProfile`, synap-backend
+         * cron-automation.ts) — an object would be dropped, and an unfiltered AI
+         * fan-out is refused, so the schedule would silently never be created.
+         */
+        filter?: string;
+        statusProperty?: string;
+    };
+    /**
+     * Playbook-level slots: what a run of this process is expected to produce.
+     * Instantiated as the session's owed slots (`sanitizeDeclaredOutputs`).
+     */
+    expectedOutputs?: TemplateExpectedOutput[];
+    /** Binary acceptance criteria every run is graded against (pod `sessionCriteriaSchema`). */
+    criteria?: TemplateCriterion[];
+    /**
+     * The abstract intents the process needs the pod to be able to do — the
+     * closed `capability_intents` vocabulary (`@synap-core/types/capability-intents`).
+     */
+    requiredIntents?: string[];
+    /**
+     * DECLARATIONS of when the process starts. Compiled at install/apply into
+     * governed rules through the pod's ONE rule door and linked in
+     * `playbook_automations` (role `activator`) — never hand-written template
+     * `automations:`. Public templates default to `mode: propose`.
+     */
+    activators?: TemplatePlaybookActivator[];
+    /**
+     * TEMPLATE-AUTHORING ONLY. Values of `subjectProfile.statusProperty` that no
+     * stage owns because a PERSON sets them (e.g. Idea, Archived). The lifecycle
+     * coverage ratchet (`lifecycle-coverage.test.ts`) requires every enum value
+     * of the status property to be either a stage's `subjectStatus` or listed
+     * here, so a lifecycle state can never be silently orphaned by a process.
+     */
+    humanOnlyStatuses?: string[];
+    status?: "draft" | "active" | "paused";
+    /**
+     * `project` = a TRACK template (a method a project runs over its `stages`);
+     * `session` / omitted = a work template. The kind is DERIVED from this, never
+     * declared elsewhere (concepts.md).
+     */
+    scope?: "session" | "project";
+    /** Ordered steps. Validated at the pod door by `playbookStageSchema`. */
+    stages?: TemplatePlaybookStage[];
+}
+/**
+ * One step of a playbook. Mirrors the pod's `PlaybookStage` (@synap/playbooks)
+ * for the fields templates author; the pod schema stays the authority.
+ */
+interface TemplatePlaybookStage {
+    key: string;
+    name: string;
+    category: "backlog" | "planned" | "started" | "paused" | "completed" | "canceled";
+    description?: string;
+    goal?: string;
+    suggestedTasks?: string[];
+    indefinite?: boolean;
+    /**
+     * The DOMAIN the step is worked in: a workspace TEMPLATE slug that becomes a
+     * workspace's `package_slug` (e.g. `foundation`, `finance`) — never an
+     * overlay's slug (an overlay never owns a workspace), a workspace id or a
+     * display name. `validate.ts` rule `stage-domain-*` enforces it.
+     */
+    domain?: string;
+    expectedOutputs?: TemplateExpectedOutput[];
+    /** Binary acceptance criteria of THIS stage (a `check` gate evaluates them). */
+    criteria?: TemplateCriterion[];
+    /**
+     * Entry gate. `human` files a review; `check` evaluates the criteria of the
+     * stage being LEFT before the run may continue (pod `stage-gate.ts`).
+     */
+    gate?: {
+        kind: "human" | "check";
+        proposalType?: "playbook.stage_gate";
+    };
+    /**
+     * The value of the playbook's `subjectProfile.statusProperty` this stage
+     * corresponds to. Advancing INTO the stage writes it to the subject
+     * (governed); the subject ENTERING it advances an open run to the stage.
+     */
+    subjectStatus?: string;
+    /** Where a rejected human gate / failed check sends the run back (a stage key or name). */
+    onFail?: {
+        toStage: string;
+    };
+    [key: string]: unknown;
+}
+/**
+ * One declared output slot (playbook- or stage-level). Mirrors the pod's
+ * `ExpectedOutput` (@synap/playbooks) for the fields templates author.
+ */
+interface TemplateExpectedOutput {
+    /** The output's kind — a profile slug for entities. */
+    kind: string;
+    label: string;
+    icon?: string;
+    owner?: "human" | "agent";
+    key?: string;
+    /**
+     * Relation type written output → subject when the slot is satisfied (e.g.
+     * `made_for`, `derived_from`). Must resolve to a relation the corpus defines
+     * (`entityLinks[].type` / `relationDefs[].slug`). `none` = deliberately no
+     * edge (a playbook with no subject, whose outputs stand alone).
+     */
+    relationToSubject?: string;
+    /**
+     * `true` = nobody owes this slot (synap-backend 30a9ab85): no needs-you row,
+     * never an unmet outcome at a gate or at completion; filled, it counts like
+     * any slot. Absent = required. Read STRICTLY — only a boolean `true`
+     * (validate.ts `output-optional-not-boolean`). A BIRTH declaration: a change
+     * reaches new runs and new stage entries only.
+     */
+    optional?: boolean;
+    [key: string]: unknown;
+}
+/** A binary acceptance criterion — mirrors the pod's strict `sessionCriterionSchema`. */
+interface TemplateCriterion {
+    /** Lowercase slug, unique within the list. */
+    key: string;
+    statement: string;
+    required?: boolean;
+    check: {
+        kind: "evidence" | "capability" | "judge" | "human";
+        capability?: string;
+        evidenceKey?: string;
+        hint?: string;
+    };
+    stageKey?: string;
+}
+/** A declared process activator (compiled to a governed rule at install). */
+interface TemplatePlaybookActivator {
+    /**
+     * `created` / `enters_status` per thing; `count` (≥ `min` things in
+     * `status`) and `schedule` (on `cron`) over the whole set; `manual` a
+     * button that compiles no rule. The pod's grammar (`ACTIVATOR_ON`).
+     */
+    on: "created" | "enters_status" | "count" | "schedule" | "manual";
+    /** Required for `enters_status` / `count`, optional for `schedule`: a value of the status property. */
+    status?: string;
+    /** Required for `schedule` (UTC). */
+    cron?: string;
+    /** Required for `count`. */
+    min?: number;
+    /** `per_thing` (default) or `per_moment`; count/schedule are per_moment. */
+    size?: "per_thing" | "per_moment";
+    mode: "run" | "propose";
+    /** Pending approvals before the worker stops starting runs (default 20). */
+    maxPendingApprovals?: number;
+    /** Per-thing `created` / `enters_status` only: leave out a thing that carries this property. */
+    unless?: {
+        property: string;
+        present: true;
+    };
+}
+/** Where a process comes from — convention only, read by nobody yet. */
+interface TemplatePlaybookLineage {
+    apqc?: string;
+    method?: string;
+    onet?: string[];
+}
+interface TemplateAutomation {
+    /** Stable local key (unused on the wire today — reserved for dedup/refs). */
+    key?: string;
+    name: string;
+    description?: string;
+    triggerType: "event" | "cron" | "webhook" | "manual";
+    triggerConfig?: Record<string, unknown>;
+    flow: {
+        nodes: unknown[];
+        edges: unknown[];
+        precondition?: string;
+    };
+    status?: "draft" | "active" | "paused";
+}
+interface TemplateCommandDerivedInput {
+    name: string;
+    label?: string;
+    /** Mirrors `DerivedInput.type` (text | number | entity | view | choice). */
+    type?: string;
+}
+interface TemplateCommand {
+    title: string;
+    promptTemplate: string;
+    derivedInputs?: TemplateCommandDerivedInput[];
+    /** text | proposal | view */
+    outputMode?: string;
+    canCreateViews?: boolean;
+    /** read_only | propose_writes */
+    permissionsProfile?: string;
+}
+interface TemplateActionPlacement {
+    /** Entity kind whose detail surface this action appears on. */
+    profileSlug: string;
+    /** Where the action renders. Only "entity-detail" is consumed today. */
+    surface: "entity-detail" | string;
+    /** What the action does when clicked. */
+    kind: "capability" | "playbook" | "automation";
+    /**
+     * Reference to the thing to run: a capability verb key, or a playbook /
+     * automation NAME (resolved to a row id at apply time).
+     */
+    ref: string;
+    /** Human label shown on the action button. */
+    label: string;
+    /** Additional entity-state requirements, evaluated by the rendering surface. */
+    when?: {
+        /** All listed workspace facets must be present on the entity. */
+        requiredFacetSlugs?: string[];
+        /** Entity property values that must equal their configured literal values. */
+        propertyEquals?: Record<string, unknown>;
+        /** Any configured property/value match makes the action applicable. */
+        propertyAnyEquals?: Record<string, unknown[]>;
+        /** Entity property values that must not equal their configured literal values. */
+        propertyNotEquals?: Record<string, unknown>;
+    };
+    /** Explicit intent required before a consequential action is launched. */
+    confirmation?: {
+        title: string;
+        description?: string;
+        confirmLabel?: string;
+    };
+}
+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 mirrored by hand in several other
+ * places — a comment cannot fail a build, an import can, but these mirrors live
+ * in repos this package does not own, so they must match this list EXACTLY:
+ *
+ *   - marketplace            `features/marketplace/src/types.ts`
+ *   - onboarding             `features/onboarding/src/templates/workspace-templates.ts`
+ *   - browser                `InstallPackageDialog.tsx`
+ *   - synap-backend          `package-definition.ts` (`PackageDependencyKind`)
+ *   - hub-protocol REST      `rest/packages.ts` (zod enum)
+ *   - control-plane-api      `db/schema/packages.ts` (`TemplateDependency` type)
+ *                            + `routes/packages.ts` (`DEPENDENCY_KINDS` zod enum)
+ *
+ * These are the 7 literals the wire accepts, in lockstep with the CP publish
+ * enum (`DEPENDENCY_KINDS = [...PACKAGE_TYPES, "automation"]`, CP
+ * `routes/packages.ts`), the hub install enum (`rest/packages.ts`), and the
+ * backend resolver's `PackageDependencyKind` (`@synap/database`).
+ *
+ * Resolver behaviour (backend `package-dependency-resolver.ts`):
+ *   - `workspace`         → resolve+install; the ONLY kind that may `compose`.
+ *   - `capability` / `cell` → resolve+install, always `require`d (presence).
+ *   - `skill` / `workflow` / `view` / `automation` → ACCEPTED and `require`d
+ *     present, surfaced as `required-absent` (non-fatal) — no standalone by-slug
+ *     applier on the pod yet; when one grows, give the kind its own branch.
+ *
+ * `'automation'` is legacy vocabulary: CP migration `0049_package_vocabulary`
+ * renamed the `automation` package category → `workflow` (which absorbs
+ * automation + playbook, `PACKAGE_TYPES` in CP `db/schema/packages.ts`). It
+ * stays accepted on the wire — and therefore in this tuple — for back-compat
+ * with dependencies published before the rename.
+ */
+declare const PACKAGE_DEPENDENCY_KINDS: readonly ["workspace", "capability", "skill", "workflow", "view", "cell", "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; every other kind is 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;
+    /**
+     * Human-facing subject area used to SECTION the marketplace (CLI `market
+     * list`, browser New Space + catalog). Authored here so grouping is a
+     * property of the template, read by every surface — never re-derived from a
+     * hardcoded slug→group map in a consumer. NOT `category` (that is the
+     * PACKAGE TYPE — `workspace`/`capability`/…). Optional and open: an unknown
+     * or missing value is grouped, never dropped — see `./domains.ts`.
+     */
+    domain?: string;
+    /**
+     * WHAT THE SPACE PRODUCES — the purpose word shown first ("Product · Dev")
+     * and the kinds/roles it makes, in order. An empty `produces` (or none) makes
+     * the space a LIBRARY. Every produced profile is the template's own or one
+     * it depends on, and declares a lifecycle (`validate.ts` `intent-*` rules).
+     * Forwarded to the pod (top-level `intent` on both doors), which projects it into
+     * `workspaces.settings.intent`.
+     */
+    intent?: TemplateIntent;
+    /**
+     * An ONBOARDING START: this space offers itself as a first thing to run
+     * ("What should Synap run first?"). Declared once here, read by the pod, the
+     * CP and the landing. Rules: `validate.ts` `start-*`. Forwarded as top-level
+     * `start` on the package door, never in `_meta`.
+     */
+    start?: TemplateStart;
+}
+/** `meta.start.label` reuses {@link INTENT_LABEL_MAX}; these bound the lists. */
+declare const START_VIEWS_MAX = 3;
+declare const START_EXAMPLE_RANGE: readonly [4, 6];
+declare const START_STARTERS_RANGE: readonly [3, 6];
+/** `meta.start` — see {@link TemplateMeta.start}. */
+interface TemplateStart {
+    /** Card order; unique across the catalog's starts. */
+    order: number;
+    /** ≤ {@link INTENT_LABEL_MAX} chars. */
+    label: string;
+    promise: string;
+    /** Identity ids this start is suggested for; each id belongs to one start. */
+    suggestFor: string[];
+    /** The produced kind the views and the first session are about. */
+    profile: string;
+    /** 1-3 slugs of THIS template's views, scoped to `profile`; first = default. */
+    views: string[];
+    /** Preview rows, never written. `values` keys are properties of `profile`. */
+    example: Array<{
+        title: string;
+        values?: Record<string, unknown>;
+    }>;
+    firstSession: {
+        title: string;
+        goal: string;
+    };
+    /** "Build it with me" chips. */
+    starters: string[];
+}
+/** `meta.intent.label` max — the purpose word must fit before " · <name>". */
+declare const INTENT_LABEL_MAX = 24;
+/** `meta.intent` — see {@link TemplateMeta.intent}. */
+interface TemplateIntent {
+    /** ≤ {@link INTENT_LABEL_MAX} chars. */
+    label: string;
+    produces?: Array<{
+        profile: string;
+    }>;
+}
+interface WorkspaceYaml {
+    /** Template metadata — not sent to backend, used for listing/UI */
+    meta: TemplateMeta;
+    /**
+     * THE WORKSPACE'S TASK REQUIREMENTS — the specific intents (closed
+     * vocabulary, `@synap-core/types/capability-intents`) this workspace needs to
+     * function. The SSOT for WHAT THE SPACE REQUIRES, as distinct from
+     * `workspace.capabilities`, which names what it PROVIDES to others.
+     *
+     * Every value is validated against the closed vocabulary by
+     * `validateTemplate` (`task-intent-unknown`), so a typo fails at authoring
+     * time rather than installing a capability axis nobody can route.
+     *
+     * Deliberately NOT forwarded by either converter yet: the backend has no
+     * `taskIntents` sink on `createFromDefinition` (see `WorkspaceDefinitionDropped`
+     * in `define.ts`, which records that). Phase 1 is the declaration + its
+     * guard; wiring it to a sink is a follow-up that must edit that ledger.
+     */
+    taskIntents?: CapabilityIntentSlug[];
+    /** 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[];
+    /**
+     * Documents the space carries (plan 9ad4b2fc §5 lane 12, P4: a pinned set of
+     * documents hosts a space package). Installed by the pod with the views:
+     * created once per `slug` in the space, never rewritten by an update. A
+     * sidebar item `{kind: "document", documentSlug}` opens one. See
+     * {@link TemplateDocument}.
+     */
+    documents?: TemplateDocument[];
+    /** Schema-level links between entity types */
+    entityLinks?: TemplateEntityLink[];
+    /**
+     * Domain-level relation TYPE vocabulary seeded into the workspace's
+     * `relation_defs`. Distinct from `entityLinks` (profile→profile edges): a
+     * relation def stands alone and carries `description`/`isDirectional`/`uiHints`.
+     * The `base` template carries the universal defaults. See {@link TemplateRelationDef}.
+     */
+    relationDefs?: TemplateRelationDef[];
+    /**
+     * Workspace-scoped intelligence commands (prompt-template "Default Command
+     * Pack") seeded with the workspace. The `base` template carries the universal
+     * pack. See {@link TemplateCommand}.
+     */
+    commands?: TemplateCommand[];
+    /** 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;
+    /** Playbooks (session templates) seeded with the workspace */
+    playbooks?: TemplatePlaybook[];
+    /**
+     * Flow-based automations (WHEN→THEN triggers) seeded with the workspace.
+     * Applier-only — see {@link TemplateAutomation}.
+     */
+    automations?: TemplateAutomation[];
+    /**
+     * Entity-detail action placements seeded into `settings.actionPlacements`.
+     * See {@link TemplateActionPlacement}.
+     */
+    actionPlacements?: TemplateActionPlacement[];
+    /** 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;
+    /**
+     * Rules this template installs in its space (package `rules[]`). See
+     * {@link TemplateRule}.
+     */
+    rules?: TemplateRule[];
+    /**
+     * Skills this template declares for its space (package `skills[]`). The pod
+     * links each to the new space at install, approved skills only, so every AI
+     * working there is told them. See {@link TemplateSkill}.
+     */
+    skills?: TemplateSkill[];
+    /**
+     * The space's own experience as CODE: the modules this template builds into
+     * sandboxed frame cells and installs in its space (package `cells[]`, typeKey
+     * `cell:<meta.slug>:<key>`). The template's `app: {kind: stored, cellKey}`
+     * opens one of them. See {@link TemplateSpacePackage}.
+     */
+    spacePackage?: TemplateSpacePackage;
+    /** 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[];
+}
+/**
+ * One module of a space package. `source` is the entry file, relative to the
+ * synap-app repo root and under `packages/web/src/space-packages/`, so the
+ * package is built from the SAME shared components every surface uses, never
+ * from a copy. `scripts/build-space-packages.mjs` bundles it (React external,
+ * host-inlined in the frame; its CSS injected by the module) into
+ * `src/space-packages.generated.ts`, and `toPackageDefinition` carries it as a
+ * `frame` cell.
+ */
+interface TemplateSpacePackageCell {
+    /** Cell key inside the package: the installed typeKey is `cell:<meta.slug>:<key>`. */
+    key: string;
+    /** Display name of the installed cell. */
+    name: string;
+    /** Entry module, repo-relative (`packages/web/src/space-packages/<pkg>/<file>.tsx`). */
+    source: string;
+}
+/** The space package a template installs (base layer; the person's overlay comes later). */
+interface TemplateSpacePackage {
+    cells: TemplateSpacePackageCell[];
+}
+
+/**
+ * Space packages: the built code a template installs in its space.
+ *
+ * `scripts/build-space-packages.mjs` bundles each template's
+ * `spacePackage.cells[]` into `space-packages.generated.ts` (committed, like
+ * `templates.ts`, so every consumer of `toPackageDefinition` gets the same
+ * cells without a bundler). This module reads that output for the converter.
+ */
+
+/** One built module: the declared cell plus its bundled ES module source. */
+interface BuiltSpacePackageCell {
+    key: string;
+    name: string;
+    source: string;
+    /** The ES module the frame runs (default export = a React component). */
+    code: string;
+    /**
+     * Every name the module imports from the host's `@synap/kit` frame module:
+     * the kit contract it was built against (the build refused any name the kit
+     * did not export).
+     */
+    kitImports: string[];
+}
+/**
+ * A template's built space package. It bundles only its own modules
+ * (`packages/web/src/space-packages/`): the shared layers come from the host's
+ * kit, whose own build record is `FRAME_HOST_MODULES_BUILD`
+ * (`@synap-core/web` cell-runtime).
+ */
+interface BuiltSpacePackage {
+    cells: BuiltSpacePackageCell[];
+    /** sha256 of every synap-app file the bundles read (repo-relative path → hex). */
+    inputs: Record<string, string>;
+}
+/**
+ * A space package cell on the package wire (`PackageDefinition.cells[]`, the
+ * pod's `PackageCellDef`): a sandboxed `frame` cell. No `externalHosts`: a
+ * space package is network-contained; its only data path is the host bridge.
+ */
+interface SpacePackageCellWire {
+    key: string;
+    name: string;
+    code: string;
+    rendererType: 'frame';
+}
+/**
+ * The cells a template's space package installs, or `undefined` when it has
+ * none. Throws when a declared cell was never built (or was built from another
+ * source): a template must never ship an entry that opens "Unknown cell".
+ */
+declare function spacePackageCells(tpl: WorkspaceYaml, built?: Record<string, BuiltSpacePackage>): SpacePackageCellWire[] | undefined;
+
+/**
+ * @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 `TemplateAutomation` as the apply door expects it: `flowDefinition`, not
+ * the authored `flow` (mirrors `PackagePostWorkspaceBody['automations'][number]`
+ * / the Hub `POST /packages/apply` `AutomationSchema`).
+ */
+interface PackageAutomationWire {
+    /** Stable template identity; names may be edited without orphaning the flow. */
+    key?: string;
+    name: string;
+    description?: string;
+    triggerType: TemplateAutomation['triggerType'];
+    triggerConfig?: Record<string, unknown>;
+    flowDefinition?: {
+        nodes: unknown[];
+        edges: unknown[];
+        precondition?: string;
+    };
+    status?: TemplateAutomation['status'];
+}
+/** The ONE automation projection (authored `flow` → wire `flowDefinition`), shared by workspaces and standalone automation packages. */
+declare function toAutomationWire(automations: TemplateAutomation[] | undefined): PackageAutomationWire[] | undefined;
+/** 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[];
+}
+/**
+ * Produce the canonical persisted layout. A template may author either the
+ * top-level `app:` shorthand or an explicit `layout.primarySurface`, never both.
+ * Legacy `defaultApp` is the final compatibility fallback. Keeping the property
+ * absent preserves a live workspace value during reconciliation; an authored
+ * null is retained as an explicit clear.
+ */
+declare function normalizeTemplateLayout(layout: TemplateLayoutConfig | undefined, app: TemplateAppRef | undefined): TemplateLayoutConfig | undefined;
+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']>;
+    /** Template documents — created by the pod with the views (`utils/template-documents.ts`). */
+    documents?: WorkspaceYaml['documents'];
+    entityLinks: NonNullable<WorkspaceYaml['entityLinks']>;
+    seedEntities: NonNullable<WorkspaceYaml['seedEntities']>;
+    suggestedRelations?: WorkspaceYaml['suggestedRelations'];
+    displayTemplates?: WorkspaceYaml['displayTemplates'];
+    /**
+     * Domain-level relation TYPE vocabulary — the door find-or-creates a
+     * `relation_defs` row per entry (idempotent by slug within the workspace). NOT
+     * `entityLinks` (those are profile→profile edges and drop the rich metadata).
+     * Carried verbatim; the authored form IS the wire form.
+     */
+    relationDefs?: WorkspaceYaml['relationDefs'];
+    /**
+     * Workspace intelligence commands — the door find-or-creates an
+     * `intelligence_commands` row per entry (idempotent by title). Carried
+     * verbatim; the authored form IS the wire form.
+     */
+    commands?: WorkspaceYaml['commands'];
+    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'];
+    /**
+     * Capability integrations (→ tools + skills + vault + capability-embedded
+     * automations/playbooks). Emitted from the template's `integrations:` list —
+     * IDENTICAL to what `toPackageDefinition` puts in its `capabilities` field. The
+     * tRPC door (`workspaces.createFromDefinition`) now declares `capabilities` in
+     * its zod input and installs them via the SHARED `applyPackagePostWorkspace`
+     * door (same as Hub `/packages/apply`). It was missing from this interface, so
+     * `toWorkspaceDefinition` had nowhere to put integrations and the browser
+     * BUNDLED install path carried NO capabilities — every capability's
+     * tools/skills/automations silently dropped on that door.
+     */
+    capabilities?: WorkspaceYaml['integrations'];
+    /** Playbooks normalized to the workspace-create input contract. */
+    playbooks?: Array<Record<string, unknown>>;
+    /**
+     * Entity-detail action placements — forwarded verbatim to
+     * `applyPackagePostWorkspace`, which merges them into
+     * `settings.actionPlacements`. The tRPC door (`createFromDefinition`)
+     * declares `actionPlacements` in its zod input and carries them through the
+     * shared apply door. No shape transform: the authored form IS the wire form.
+     */
+    actionPlacements?: WorkspaceYaml['actionPlacements'];
+    /**
+     * Graph-based automations. Deliberately distinct from the legacy
+     * `automations` loop/playbook-trigger wire shape accepted by this door.
+     */
+    flowAutomations?: PackageAutomationWire[];
+    workspaceSubtype?: string;
+    workspaceType?: NonNullable<WorkspaceYaml['workspace']>['workspaceType'];
+    workspaceVisibility?: string;
+    workspaceCapabilities?: string[];
+    /**
+     * THE DECLARED INTENT SINK (Phase 3). `taskIntents` is authored at the TOP
+     * level of the template, not inside `workspace`, and is forwarded verbatim to
+     * `workspaces.createFromDefinition`, which persists it to
+     * `settings.taskIntents` — where the intent resolver joins it against what is
+     * actually installed. No shape transform: the authored form IS the wire form.
+     */
+    taskIntents?: WorkspaceYaml['taskIntents'];
+    /**
+     * What the space PRODUCES (`meta.intent`), forwarded verbatim; the pod
+     * projects it into `settings.intent`. Same top-level field on the package
+     * door.
+     */
+    intent?: WorkspaceYaml['meta']['intent'];
+    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;
+        /** The PACKAGE's own name (meta.name). For an overlay this differs from
+         *  `workspaceName`, which names the workspace it composes onto. */
+        name?: string;
+        /** The PACKAGE's own description (meta.description) — what the catalog
+         *  lists. Top-level `description` stays the workspace's (install copy). */
+        description?: string;
+        icon?: string;
+        color?: string;
+        domain?: string;
+        tags?: string[];
+        isPublic?: boolean;
+        requiredTier?: string | null;
+    };
+    workspaceName: string;
+    description: string;
+    workspaceType?: WorkspaceYaml['workspace']['workspaceType'];
+    workspaceSubtype?: string;
+    workspaceVisibility?: string;
+    workspaceCapabilities?: string[];
+    /**
+     * The DECLARED intents, carried to the marketplace/CLI install path too.
+     * Without it here, a workspace installed from the marketplace would LOSE its
+     * declaration while a bundled one kept it — the same field behaving
+     * differently per install route, which is precisely the fork this package
+     * exists to prevent.
+     */
+    taskIntents?: WorkspaceYaml['taskIntents'];
+    /**
+     * What the space PRODUCES (`meta.intent`), TOP-LEVEL like `taskIntents` —
+     * never in `_meta`, which the CP rebuilds from its row columns on serve
+     * (`normalizePublishedDefinition`), so a key there never reaches a pod.
+     */
+    intent?: WorkspaceYaml['meta']['intent'];
+    /**
+     * The onboarding start (`meta.start`), TOP-LEVEL for the same reason as
+     * `intent`. Package door only: the pod and the CP read starts off the package.
+     */
+    start?: WorkspaceYaml['meta']['start'];
+    sourceRoles?: WorkspaceYaml['workspace']['sourceRoles'];
+    defaultSources?: WorkspaceYaml['workspace']['defaultSources'];
+    profiles: WorkspaceYaml['profiles'];
+    views: NonNullable<WorkspaceYaml['views']>;
+    /**
+     * Template documents — created by the pod with the views
+     * (`utils/template-documents.ts`); the Hub `PackageApplySchema` slots them.
+     * The CP publish door does NOT yet (it strips the field and refuses a
+     * `kind: "document"` sidebar item), so no official template may declare
+     * documents until it does.
+     */
+    documents?: WorkspaceYaml['documents'];
+    suggestedEntities: NonNullable<WorkspaceYaml['seedEntities']>;
+    suggestedRelations?: WorkspaceYaml['suggestedRelations'];
+    displayTemplates?: WorkspaceYaml['displayTemplates'];
+    entityLinks?: WorkspaceYaml['entityLinks'];
+    /** Relation-type vocabulary — carried verbatim (authored form IS the wire form). */
+    relationDefs?: WorkspaceYaml['relationDefs'];
+    /** Intelligence commands — carried verbatim (authored form IS the wire form). */
+    commands?: WorkspaceYaml['commands'];
+    /** 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'];
+    /** Flow-based automations — mapped to the apply door's `flowDefinition` field. */
+    automations?: PackageAutomationWire[];
+    /**
+     * Entity-detail action placements — carried verbatim (authored form IS the
+     * wire form). The Hub `PackageApplySchema` (synap-backend
+     * `hub-protocol/rest/packages.ts`) now declares `actionPlacements`
+     * (`z.array(ActionPlacementSchema).optional()`), so BOTH the tRPC
+     * `createFromDefinition` door and the CLI/Hub install path carry it through to
+     * `applyPackagePostWorkspace` — the parity is closed.
+     */
+    actionPlacements?: WorkspaceYaml['actionPlacements'];
+    onboarding?: WorkspaceYaml['onboarding'];
+    /**
+     * Rules the template installs in its space — applied by the pod's
+     * `applyPackagePostWorkspace` through the ONE rule door and converged by the
+     * template-rule reconcile (three-way stamp on `metadata.rule.seed`).
+     */
+    rules?: WorkspaceYaml['rules'];
+    /**
+     * Skills the template declares for its space — linked to the new space by the
+     * pod's `applyPackagePostWorkspace` (approved skills only), which is why they
+     * travel on the PACKAGE definition and not the workspace door's input.
+     */
+    skills?: WorkspaceYaml['skills'];
+    /**
+     * The space package's built modules (`spacePackage` → `space-packages.ts`),
+     * installed by the pod's `applyPackagePostWorkspace` as sandboxed frame cells
+     * `cell:<_meta.slug>:<key>` — what the template's `app: {kind: stored}` opens.
+     */
+    cells?: SpacePackageCellWire[];
+    /** 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.
+ */
+declare function toPackageDefinition(slugOrYaml: string | WorkspaceYaml): PackageDefinitionOutput;
+
+export { normalizeTemplateLayout as $, type TemplateOnboardingCollectTarget as A, type BentoViewBlockWire as B, type TemplatePlaybook as C, type TemplatePlaybookParam as D, type TemplatePrimarySurface as E, type TemplateProfile as F, type TemplateProfileEntityBentoTemplates as G, type TemplateProperty as H, INTENT_LABEL_MAX as I, type TemplateSeedEntity as J, type TemplateSidebarItem as K, type TemplateSidebarSurface as L, type TemplateSourceRole as M, type TemplateSpacePackage as N, type TemplateSpacePackageCell as O, PACKAGE_DEPENDENCY_KINDS as P, type TemplateStart as Q, type TemplateSuggestedRelation as R, START_EXAMPLE_RANGE as S, type TemplateDependency as T, type TemplateView as U, type ToDefinitionResult as V, type WorkspaceYaml as W, type WorkspaceDefinitionInput as X, type WorkspaceJsonValue as Y, type WorkspacePrimarySurface as Z, type WorkspacePrimarySurfaceViewReference as _, type TemplateLifecycleOption as a, spacePackageCells as a0, splitBentoBlocks as a1, toAutomationWire as a2, toPackageDefinition as a3, toWorkspaceDefinition as a4, type TemplateLifecycleOptionWaits as b, type BentoWidgetBlockWire as c, type BuiltSpacePackage as d, type BuiltSpacePackageCell as e, type PackageAutomationWire as f, type PackageDefinitionOutput as g, type PackageDependencyKind as h, START_STARTERS_RANGE as i, START_VIEWS_MAX as j, type SpacePackageCellWire as k, type SplitBentoBlocks as l, type TemplateActionPlacement as m, type TemplateAppKind as n, type TemplateAppRef as o, type TemplateAutomation as p, type TemplateBentoBlock as q, type TemplateDefaultSource as r, type TemplateDisplayTemplate as s, type TemplateEntityLink as t, type TemplateExtendsRef as u, type TemplateIntegration as v, type TemplateIntent as w, type TemplateLayoutConfig as x, type TemplateMeta as y, type TemplateOnboarding as z };