@synap-core/workspace-templates 0.8.0 → 0.9.0

package/src/types.ts

@@ -49,8 +49,30 @@ export interface TemplateProfile {
   icon?: string;
   color?: string;
   description?: string;
-  /** Visibility scope. Omit or "WORKSPACE" for workspace-scoped. */
+  /**
+   * 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'). */
@@ -284,9 +306,23 @@ export interface TemplatePlaybook {
     members?: string[];
     aiReactionMode?: 'on_mention' | 'always' | 'never';
   };
-  schedule?: { cron: string } | null;
+  /**
+   * 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.
+   */
+  metadata?: Record<string, unknown>;
   /**
    * The entity kind this playbook operates over, persisted to
    * `playbooks.subject_profile`. Makes the playbook matchable by