@synap-core/workspace-templates 0.12.0 → 0.23.0

package/src/types.ts

@@ -1,3 +1,21 @@
+import type { ProfilePresentation } from "@synap-core/types/presentation";
+import type {
+  SpaceBrief,
+  SpaceBriefAnchor,
+  SpaceBriefCollectTarget,
+  SpaceBriefExpertise,
+  SpaceBriefFetchHint,
+  SpaceTemplateRule,
+  SpaceTemplateSkill,
+} from "@synap-core/types/space-brief";
+
+// The intent vocabulary is imported as a TYPE here (no runtime import), so this
+// file keeps its "zero runtime imports" property that `build.mjs` depends on —
+// it loads `validate.ts` under Node's type-stripper BEFORE `tsup` builds dist/.
+// The RUNTIME membership test lives in `validate.ts`, which is the only place
+// that needs a value.
+import type { CapabilityIntentSlug } from "@synap-core/types/capability-intents";
+
 /**
  * @synap-core/workspace-templates — Types
  *
@@ -71,6 +89,14 @@ export type WorkspacePrimarySurface =
       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";
@@ -152,6 +178,79 @@ export interface TemplateProfile {
   /** 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). */
+export type TemplateLifecycleCategory = "open" | "active" | "paused" | "done" | "lost";
+
+export 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`). */
+export 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;
+}
+
+export interface TemplateLifecycle {
+  /** The lifecycle property's slug (a select of this profile). */
+  property: string;
+  options: TemplateLifecycleOption[];
 }
 
 export interface TemplateView {
@@ -172,6 +271,16 @@ export interface TemplateEntityLink {
   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;
 }
 
 /**
@@ -320,65 +429,40 @@ export interface TemplateDefaultSource {
 }
 
 // ============================================================================
-// Onboarding spec — the per-workspace dynamic onboarding CONTEXT
+// The space brief — `onboarding:` in a template, stored at
+// workspace.settings.onboarding.
 //
-// Written to workspace.settings.onboarding. The SHARED `onboard` skill (the
-// reusable adaptive interview PROCESS) reads this to know WHAT a given
-// workspace needs — without a per-domain skill file. The domain knowledge
-// lives here as data, declared by each template. Mirrors `OnboardingSpec` in
-// synap-backend `package-definition.ts` so the wire shape never drifts.
+// ONE type: `SpaceBrief` in `@synap-core/types/space-brief` (type-only import;
+// tsup inlines it into this package's .d.ts, so there is no runtime
+// dependency). The interview fields (goal / collect / openingQuestions /
+// doneWhen) are the brief's ONBOARDING MODE, read by the shared `onboard`
+// skill; purpose / anchors / fetch are its steady state, read by every agent
+// that enters the space. The names below are aliases, not declarations.
 // ============================================================================
 
-export 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[];
-}
-
-// Authored domain expertise the onboarding agent LEADS with — so it resolves
-// the founder's gaps (brings best practices they lack, surfaces what they miss)
-// instead of only extracting what they already know. Consumed by the `onboard`
-// skill; see its "Lead with your expertise" step.
-export 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;
-}
-
-export 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;
-}
+export type TemplateOnboardingCollectTarget = SpaceBriefCollectTarget;
+export type TemplateOnboardingExpertise = SpaceBriefExpertise;
+export type TemplateBriefAnchor = SpaceBriefAnchor;
+export type TemplateBriefFetchHint = SpaceBriefFetchHint;
+/**
+ * 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export type TemplateSkill = SpaceTemplateSkill;
 
 // ============================================================================
 // Playbooks — session templates seeded with the workspace
@@ -402,7 +486,23 @@ export interface TemplatePlaybook {
   goalTemplate: string;
   params?: TemplatePlaybookParam[];
   executor?: "is-agent" | "external-agent" | "hybrid";
-  inputStrategy?: "none" | "static" | "rotating" | "query";
+  /**
+   * 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[];
@@ -423,16 +523,183 @@ export interface TemplatePlaybook {
    * 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>;
+  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; filter?: Record<string, unknown> };
+  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.
+ */
+export 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.
+ */
+export 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`. */
+export 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). */
+export 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. */
+export interface TemplatePlaybookLineage {
+  apqc?: string;
+  method?: string;
+  onet?: string[];
 }
 
 // ============================================================================
@@ -612,7 +879,7 @@ export interface TemplateExtendsRef {
  * 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,components/WorkspacePreview}.ts(x)`
+ *   - 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)
@@ -697,12 +964,80 @@ export interface TemplateMeta {
    * 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. */
+export const START_VIEWS_MAX = 3;
+export const START_EXAMPLE_RANGE = [4, 6] as const;
+export const START_STARTERS_RANGE = [3, 6] as const;
+
+/** `meta.start` — see {@link TemplateMeta.start}. */
+export 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>". */
+export const INTENT_LABEL_MAX = 24;
+
+/** `meta.intent` — see {@link TemplateMeta.intent}. */
+export interface TemplateIntent {
+  /** ≤ {@link INTENT_LABEL_MAX} chars. */
+  label: string;
+  produces?: Array<{ profile: string }>;
 }
 
 export 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;
@@ -807,6 +1142,27 @@ export interface WorkspaceYaml {
    */
   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[];
 
@@ -819,6 +1175,33 @@ export interface WorkspaceYaml {
   dependencies?: TemplateDependency[];
 }
 
+// ============================================================================
+// Space package — the space's experience as built code
+// ============================================================================
+
+/**
+ * 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.
+ */
+export 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). */
+export interface TemplateSpacePackage {
+  cells: TemplateSpacePackageCell[];
+}
+
 // ============================================================================
 // Resolved template — meta + fully typed definition ready for provisioning
 // ============================================================================