forge-openclaw-plugin 0.2.69 → 0.2.71

package/dist/server/src/lib/psyche-schemas.js

@@ -0,0 +1,177 @@
+import { z } from "zod";
+const trimmed = z.string().trim();
+const nonEmpty = trimmed.min(1);
+const uniqueStrings = z.array(nonEmpty).transform((values) => Array.from(new Set(values)));
+const ownedUserId = z.string().trim().min(1).nullable().optional();
+export const psycheValueSchema = z.object({
+    title: nonEmpty,
+    description: trimmed,
+    valuedDirection: nonEmpty,
+    whyItMatters: trimmed,
+    linkedGoalIds: z.array(z.string()).default([]),
+    linkedProjectIds: z.array(z.string()).default([]),
+    linkedTaskIds: z.array(z.string()).default([]),
+    committedActions: z.array(trimmed).default([]),
+    userId: ownedUserId
+});
+export const behaviorPatternSchema = z.object({
+    title: nonEmpty,
+    description: trimmed,
+    targetBehavior: nonEmpty,
+    cueContexts: z.array(trimmed).default([]),
+    shortTermPayoff: trimmed,
+    longTermCost: trimmed,
+    preferredResponse: nonEmpty,
+    linkedValueIds: z.array(z.string()).default([]),
+    linkedSchemaLabels: uniqueStrings.default([]),
+    linkedModeIds: z.array(z.string()).default([]),
+    linkedBeliefIds: z.array(z.string()).default([]),
+    userId: ownedUserId
+});
+export const behaviorSchema = z.object({
+    kind: z.enum(["away", "committed", "recovery"]),
+    title: nonEmpty,
+    description: trimmed,
+    commonCues: z.array(trimmed).default([]),
+    urgeStory: trimmed,
+    shortTermPayoff: trimmed,
+    longTermCost: trimmed,
+    replacementMove: trimmed,
+    repairPlan: trimmed,
+    linkedPatternIds: z.array(z.string()).default([]),
+    linkedValueIds: z.array(z.string()).default([]),
+    linkedSchemaIds: z.array(z.string()).default([]),
+    linkedModeIds: z.array(z.string()).default([]),
+    userId: ownedUserId
+});
+export const beliefEntrySchema = z.object({
+    schemaId: z.string().nullable(),
+    statement: nonEmpty,
+    beliefType: z.enum(["absolute", "conditional"]),
+    originNote: trimmed,
+    confidence: z.number().int().min(0).max(100),
+    evidenceFor: z.array(trimmed).default([]),
+    evidenceAgainst: z.array(trimmed).default([]),
+    flexibleAlternative: trimmed,
+    linkedValueIds: z.array(z.string()).default([]),
+    linkedBehaviorIds: z.array(z.string()).default([]),
+    linkedModeIds: z.array(z.string()).default([]),
+    linkedReportIds: z.array(z.string()).default([]),
+    userId: ownedUserId
+});
+export const modeProfileSchema = z.object({
+    family: z.enum(["coping", "child", "critic_parent", "healthy_adult", "happy_child"]),
+    archetype: trimmed,
+    title: nonEmpty,
+    persona: trimmed,
+    imagery: trimmed,
+    symbolicForm: trimmed,
+    facialExpression: trimmed,
+    fear: trimmed,
+    burden: trimmed,
+    protectiveJob: trimmed,
+    originContext: trimmed,
+    firstAppearanceAt: z.string().trim().nullable(),
+    linkedPatternIds: z.array(z.string()).default([]),
+    linkedBehaviorIds: z.array(z.string()).default([]),
+    linkedValueIds: z.array(z.string()).default([]),
+    userId: ownedUserId
+});
+export const modeGuideSessionSchema = z.object({
+    summary: nonEmpty,
+    answers: z.array(z.object({
+        questionKey: nonEmpty,
+        value: nonEmpty
+    })).min(1),
+    userId: ownedUserId
+});
+export const flashcardSchema = z.object({
+    title: trimmed.default(""),
+    message: nonEmpty,
+    triggerSentence: trimmed.default(""),
+    triggerSituation: trimmed.default(""),
+    tags: z.array(trimmed).default([]),
+    backgroundColor: trimmed.default("#f8fafc"),
+    textColor: trimmed.default("#111827"),
+    accentColor: trimmed.default("#6ee7b7"),
+    typography: z.enum(["serif", "sans", "mono", "display"]).default("serif"),
+    imageUrl: trimmed.default(""),
+    imageAlt: trimmed.default(""),
+    layout: z.enum(["centered", "top_left", "image_split", "poster"]).default("centered"),
+    visualStyle: z.enum(["calm", "urgent", "warm", "clinical", "playful"]).default("calm"),
+    linkedValueIds: z.array(z.string()).default([]),
+    linkedBehaviorIds: z.array(z.string()).default([]),
+    linkedPatternIds: z.array(z.string()).default([]),
+    linkedBeliefIds: z.array(z.string()).default([]),
+    linkedModeIds: z.array(z.string()).default([]),
+    linkedReportIds: z.array(z.string()).default([]),
+    userId: ownedUserId
+});
+export const eventTypeSchema = z.object({
+    label: nonEmpty,
+    description: trimmed,
+    userId: ownedUserId
+});
+export const emotionDefinitionSchema = z.object({
+    label: nonEmpty,
+    description: trimmed,
+    category: trimmed,
+    userId: ownedUserId
+});
+export const triggerEmotionSchema = z.object({
+    id: nonEmpty,
+    emotionDefinitionId: z.string().nullable(),
+    label: nonEmpty,
+    intensity: z.number().int().min(0).max(100),
+    note: trimmed
+});
+export const triggerThoughtSchema = z.object({
+    id: nonEmpty,
+    text: nonEmpty,
+    parentMode: trimmed,
+    criticMode: trimmed,
+    beliefId: z.string().nullable()
+});
+export const triggerBehaviorSchema = z.object({
+    id: nonEmpty,
+    text: nonEmpty,
+    mode: trimmed,
+    behaviorId: z.string().nullable()
+});
+export const modeTimelineEntrySchema = z.object({
+    id: nonEmpty,
+    stage: nonEmpty,
+    modeId: z.string().nullable(),
+    label: nonEmpty,
+    note: trimmed
+});
+export const triggerReportSchema = z.object({
+    title: nonEmpty,
+    status: z.enum(["draft", "reviewed", "integrated"]).default("draft"),
+    eventTypeId: z.string().nullable(),
+    customEventType: trimmed,
+    eventSituation: nonEmpty,
+    occurredAt: z.string().trim().nullable(),
+    emotions: z.array(triggerEmotionSchema).default([]),
+    thoughts: z.array(triggerThoughtSchema).default([]),
+    behaviors: z.array(triggerBehaviorSchema).default([]),
+    consequences: z.object({
+        selfShortTerm: z.array(trimmed).default([]),
+        selfLongTerm: z.array(trimmed).default([]),
+        othersShortTerm: z.array(trimmed).default([]),
+        othersLongTerm: z.array(trimmed).default([])
+    }),
+    linkedPatternIds: z.array(z.string()).default([]),
+    linkedValueIds: z.array(z.string()).default([]),
+    linkedGoalIds: z.array(z.string()).default([]),
+    linkedProjectIds: z.array(z.string()).default([]),
+    linkedTaskIds: z.array(z.string()).default([]),
+    linkedBehaviorIds: z.array(z.string()).default([]),
+    linkedBeliefIds: z.array(z.string()).default([]),
+    linkedModeIds: z.array(z.string()).default([]),
+    modeOverlays: z.array(trimmed).default([]),
+    schemaLinks: z.array(trimmed).default([]),
+    modeTimeline: z.array(modeTimelineEntrySchema).default([]),
+    nextMoves: z.array(trimmed).default([]),
+    userId: ownedUserId
+});

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "forge-openclaw-plugin",
   "name": "Forge",
   "description": "Curated OpenClaw adapter for the Forge collaboration API, UI entrypoint, and localhost auto-start runtime.",
-  "version": "0.2.69",
+  "version": "0.2.71",
   "activation": {
     "onStartup": true,
     "onCapabilities": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-openclaw-plugin",
-  "version": "0.2.69",
+  "version": "0.2.71",
   "description": "Curated OpenClaw adapter for the Forge collaboration API, UI entrypoint, and localhost auto-start runtime.",
   "type": "module",
   "license": "Apache-2.0",
@@ -105,6 +105,7 @@
     "follow-redirects": "^1.16.0",
     "hono": "^4.12.18",
     "ip-address": "^10.2.0",
+    "ws": "^8.20.1",
     "uuid": "^14.0.0"
   },
   "scripts": {

package/server/migrations/062_health_mobile_sync_sessions.sql

@@ -0,0 +1,55 @@
+CREATE TABLE IF NOT EXISTS health_mobile_sync_sessions (
+  id TEXT PRIMARY KEY,
+  pairing_session_id TEXT NOT NULL REFERENCES companion_pairing_sessions(id) ON DELETE CASCADE,
+  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  status TEXT NOT NULL DEFAULT 'running',
+  schema_version TEXT NOT NULL DEFAULT 'healthkit-sync-v2',
+  requested_families_json TEXT NOT NULL DEFAULT '[]',
+  source_metadata_json TEXT NOT NULL DEFAULT '{}',
+  expected_counts_json TEXT NOT NULL DEFAULT '{}',
+  received_counts_json TEXT NOT NULL DEFAULT '{}',
+  byte_totals_json TEXT NOT NULL DEFAULT '{}',
+  affected_workout_ids_json TEXT NOT NULL DEFAULT '[]',
+  error_json TEXT NOT NULL DEFAULT '{}',
+  started_at TEXT NOT NULL,
+  completed_at TEXT,
+  failed_at TEXT,
+  aborted_at TEXT,
+  expired_at TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_health_mobile_sync_sessions_pairing_status
+  ON health_mobile_sync_sessions(pairing_session_id, status, started_at DESC);
+
+CREATE TABLE IF NOT EXISTS health_mobile_sync_chunks (
+  id TEXT PRIMARY KEY,
+  sync_session_id TEXT NOT NULL REFERENCES health_mobile_sync_sessions(id) ON DELETE CASCADE,
+  chunk_id TEXT NOT NULL,
+  sequence INTEGER NOT NULL,
+  family TEXT NOT NULL,
+  checksum_sha256 TEXT NOT NULL,
+  record_count INTEGER NOT NULL DEFAULT 0,
+  byte_count INTEGER NOT NULL DEFAULT 0,
+  payload_json TEXT NOT NULL DEFAULT '{}',
+  payload_summary_json TEXT NOT NULL DEFAULT '{}',
+  received_at TEXT NOT NULL,
+  applied_at TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  UNIQUE(sync_session_id, chunk_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_health_mobile_sync_chunks_session_sequence
+  ON health_mobile_sync_chunks(sync_session_id, sequence);
+
+CREATE TABLE IF NOT EXISTS health_mobile_sync_family_cursors (
+  id TEXT PRIMARY KEY,
+  pairing_session_id TEXT NOT NULL REFERENCES companion_pairing_sessions(id) ON DELETE CASCADE,
+  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  family TEXT NOT NULL,
+  cursor_json TEXT NOT NULL DEFAULT '{}',
+  updated_at TEXT NOT NULL,
+  UNIQUE(pairing_session_id, family)
+);

package/server/migrations/063_psyche_flashcards.sql

@@ -0,0 +1,31 @@
+CREATE TABLE IF NOT EXISTS psyche_flashcards (
+  id TEXT PRIMARY KEY,
+  domain_id TEXT NOT NULL REFERENCES domains(id) ON DELETE CASCADE,
+  title TEXT NOT NULL DEFAULT '',
+  message TEXT NOT NULL,
+  trigger_sentence TEXT NOT NULL DEFAULT '',
+  trigger_situation TEXT NOT NULL DEFAULT '',
+  tags_json TEXT NOT NULL DEFAULT '[]',
+  background_color TEXT NOT NULL DEFAULT '#f8fafc',
+  text_color TEXT NOT NULL DEFAULT '#111827',
+  accent_color TEXT NOT NULL DEFAULT '#6ee7b7',
+  typography TEXT NOT NULL DEFAULT 'serif',
+  image_url TEXT NOT NULL DEFAULT '',
+  image_alt TEXT NOT NULL DEFAULT '',
+  layout TEXT NOT NULL DEFAULT 'centered',
+  visual_style TEXT NOT NULL DEFAULT 'calm',
+  linked_value_ids_json TEXT NOT NULL DEFAULT '[]',
+  linked_behavior_ids_json TEXT NOT NULL DEFAULT '[]',
+  linked_pattern_ids_json TEXT NOT NULL DEFAULT '[]',
+  linked_belief_ids_json TEXT NOT NULL DEFAULT '[]',
+  linked_mode_ids_json TEXT NOT NULL DEFAULT '[]',
+  linked_report_ids_json TEXT NOT NULL DEFAULT '[]',
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_psyche_flashcards_domain_updated
+  ON psyche_flashcards(domain_id, updated_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_psyche_flashcards_trigger_sentence
+  ON psyche_flashcards(trigger_sentence);

package/skills/forge-openclaw/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: forge-openclaw-plugin
-description: use when the user wants to save, search, update, review, start, stop, reward, explain, compare, or run Forge records, or when the conversation is clearly about a Forge entity or domain surface such as a goal, project, strategy, task, habit, note, wiki_page, calendar_event, calendar_connection, work_block_template, task_timebox, task_run, work_adjustment, insight, preference item, preference context, preference catalog, preference judgment, preference signal, questionnaire instrument, questionnaire run, self observation, movement, life_force, workbench, psyche_value, behavior_pattern, behavior, belief_entry, mode_profile, mode_guide_session, trigger_report, event_type, emotion_definition, sleep_session, or workout_session. identify the exact Forge object or specialized surface, keep the main conversation natural, guide psyche intake with active listening before storing it, and for psyche issues that need understanding first usually begin with one exploratory question before any formulation or save suggestion.
+description: use when the user wants to save, search, update, review, start, stop, reward, explain, compare, or run Forge records, or when the conversation is clearly about a Forge entity or domain surface such as a goal, project, strategy, task, habit, note, wiki_page, calendar_event, calendar_connection, work_block_template, task_timebox, task_run, work_adjustment, insight, preference item, preference context, preference catalog, preference judgment, preference signal, questionnaire instrument, questionnaire run, self observation, movement, life_force, workbench, psyche_value, behavior_pattern, behavior, belief_entry, mode_profile, mode_guide_session, flashcard, trigger_report, event_type, emotion_definition, sleep_session, or workout_session. identify the exact Forge object or specialized surface, keep the main conversation natural, guide psyche intake with active listening before storing it, and for psyche issues that need understanding first usually begin with one exploratory question before any formulation or save suggestion.
 ---
 
 Forge is the user's structured system for planning work, doing work, reflecting on patterns, and keeping a truthful record of what is happening. Use it when the user is clearly working inside that system, or when they are describing something that naturally belongs there and would benefit from being stored, updated, reviewed, or acted on in Forge. Keep the conversation natural first. Do not turn every message into intake. When a real Forge entity is clearly present, name the exact entity type plainly, help with the substance of the conversation, and then offer Forge once, lightly, if storing it would genuinely help.
@@ -59,7 +59,7 @@ PM surface rule:
   human/bot ownership filters.
 - Guided modal flows handle create, edit, move, link, and closeout actions.
 
-Forge has four major stored-entity surfaces and three specialized domain surfaces. The planning side covers goals, projects, strategies, tasks, habits, notes, calendar events, recurring work blocks, task timeboxes, live work sessions, and agent-authored insights. The Health side covers sleep sessions, sports and workout sessions, companion pairing, and habit-generated workout records that should still stay linked to the broader Forge graph. The Preferences side covers contextual taste modeling, pairwise comparisons, direct signals, editable concept libraries, and preference items that can come from Forge entities or seeded concept domains such as food, activities, places, countries, fashion, people, media, and tools. The Psyche side covers values, patterns, behaviors, beliefs, modes, guided mode sessions, trigger reports, event types, and reusable emotion definitions. The specialized domain surfaces are Movement, Life Force, and Workbench; agents must use their dedicated route families instead of forcing them through batch CRUD. Forge also has a SQLite-backed Wiki memory layer with explicit spaces, Markdown content in database rows, backlinks, optional embeddings, and structured links back to Forge entities. Forge is also multi-user: every entity can belong to a typed `human` or `bot` user through `userId`, and read routes can scope to one or many users with `userId` or repeated `userIds`. The current access posture is configurable through a directional user graph, but the live default is still permissive: Forge can list users directly, every relationship edge starts open, and a user can read or affect another user's linked records when the route explicitly asks for them. Use `forge_get_user_directory` when owner identity or cross-user access matters. Strategies can also be locked into a contract with `isLocked`; once locked, do not mutate the graph or target structure unless the user explicitly wants the strategy unlocked first. The model should use the real entity names, not vague substitutes. Say `project`, not “initiative”. Say `behavior_pattern`, not “theme”. Say `trigger_report`, not “incident note”.
+Forge has four major stored-entity surfaces and three specialized domain surfaces. The planning side covers goals, projects, strategies, tasks, habits, notes, calendar events, recurring work blocks, task timeboxes, live work sessions, and agent-authored insights. The Health side covers sleep sessions, sports and workout sessions, companion pairing, and habit-generated workout records that should still stay linked to the broader Forge graph. The Preferences side covers contextual taste modeling, pairwise comparisons, direct signals, editable concept libraries, and preference items that can come from Forge entities or seeded concept domains such as food, activities, places, countries, fashion, people, media, and tools. The Psyche side covers values, patterns, behaviors, beliefs, modes, guided mode sessions, flashcards, trigger reports, event types, and reusable emotion definitions. The specialized domain surfaces are Movement, Life Force, and Workbench; agents must use their dedicated route families instead of forcing them through batch CRUD. Forge also has a SQLite-backed Wiki memory layer with explicit spaces, Markdown content in database rows, backlinks, optional embeddings, and structured links back to Forge entities. Forge is also multi-user: every entity can belong to a typed `human` or `bot` user through `userId`, and read routes can scope to one or many users with `userId` or repeated `userIds`. The current access posture is configurable through a directional user graph, but the live default is still permissive: Forge can list users directly, every relationship edge starts open, and a user can read or affect another user's linked records when the route explicitly asks for them. Use `forge_get_user_directory` when owner identity or cross-user access matters. Strategies can also be locked into a contract with `isLocked`; once locked, do not mutate the graph or target structure unless the user explicitly wants the strategy unlocked first. The model should use the real entity names, not vague substitutes. Say `project`, not “initiative”. Say `behavior_pattern`, not “theme”. Say `trigger_report`, not “incident note”.
 Habits are a first-class recurring entity in the planning side.
 NEGATIVE HABIT CHECK-IN RULE: for a `negative` habit, the correct aligned/resisted outcome is `missed`. `missed` means the bad habit was resisted, the user stayed aligned, and the habit should award its XP bonus.
 
@@ -185,11 +185,16 @@ Health rule:
 
 - Sleep and sports records are first-class health surfaces, not generic notes or tasks.
 - Use `forge_get_sleep_overview` and `forge_get_sports_overview` for review and trend reading.
-- In `forge_get_agent_onboarding.entityRouteModel.readModelOnlySurfaces`, the health
-  overview routes are published under both the plain names `sleepOverview` and
-  `sportsOverview` and the entity-style aliases `sleep_overview` and
-  `sports_overview`. Treat those as read-only overview surfaces, not batch CRUD
-  entities.
+- In `forge_get_agent_onboarding.entityRouteModel.readModelOnlySurfaces`, operator,
+  calendar, self-observation, sleep, and sports read models are published with
+  both camelCase names and entity-style aliases where useful, including
+  `operatorOverview`, `operatorContext`, `calendarOverview`, `sleepOverview`,
+  `sportsOverview`, `operator_overview`, `operator_context`,
+  `calendar_overview`, `self_observation`, `sleep_overview`, and
+  `sports_overview`. Treat those as read-only surfaces, not batch CRUD entities.
+- Use `forge_get_operator_overview` for a broad Forge status read, `forge_get_operator_context`
+  for current work and risk, and `forge_get_calendar_overview` before calendar-aware
+  planning or scheduling mutations.
 - Use the shared batch entity tools for ordinary `sleep_session` and `workout_session` create, update, delete, and search work. Do not force agents into a large one-route-per-entity mental model when the batch routes already cover the record cleanly.
 - Use `forge_update_sleep_session` and `forge_update_workout_session` only when the job is reflective enrichment on one existing health record after review, such as attaching notes, tags, mood, meaning, or Forge links.
 - Habit-generated workouts and imported HealthKit workouts belong to the same workout record model, so do not invent a separate storage path for sport sessions.
@@ -232,7 +237,7 @@ Forge data location rule:
 
 Psyche interview rule:
 
-- For `psyche_value`, `behavior_pattern`, `behavior`, `belief_entry`, `mode_profile`, `mode_guide_session`, `trigger_report`, `event_type`, and `emotion_definition`, do not jump straight to raw field collection.
+- For `psyche_value`, `behavior_pattern`, `behavior`, `belief_entry`, `mode_profile`, `mode_guide_session`, `flashcard`, `trigger_report`, `event_type`, and `emotion_definition`, do not jump straight to raw field collection.
 - Treat `event_type` and `emotion_definition` as psychologically meaningful Psyche records, not cold taxonomy labels; start from the repeated lived moment or felt signature before wording the reusable label.
 - First use the active-listening playbooks in [`psyche_entity_playbooks.md`](./psyche_entity_playbooks.md).
 - Ask permission before going deeper, ask one or two focused questions at a time, reflect back what you heard, and summarize before moving on.
@@ -271,6 +276,8 @@ Self-observation rule:
 - If the core is a sentence the user believes, prefer `belief_entry`.
 - If a part-state, protector, critic, child state, or healthy-adult stance is active,
   prefer `mode_guide_session` or `mode_profile`.
+- If the user needs a brief rehearsable message during an urge, trigger, belief
+  activation, mode shift, or relapse-prevention moment, prefer `flashcard`.
 - If a schema theme is visible, do not bury it in self-observation: preserve it as
   the belief, recurring pattern, active mode, guided mode session, trigger report, or
   wiki explanation that best matches the material.
@@ -313,6 +320,10 @@ Use these exact entity meanings when deciding what the user is describing.
 
 `mode_guide_session` is a guided exploration record used to understand what mode may be active right now. It is a structured worksheet, not the final durable profile unless the user wants it that way.
 
+`flashcard` is a small therapeutic reminder card. Use it when the user wants a sentence or short message that can be shown back during an urge, trigger, mode activation, belief activation, or values-based pivot. The message is the main content; title is optional and compact. Tags, trigger sentence, trigger situation, and Psyche links matter most for retrieval. Styling fields such as colors, typography, layout, visual tone, and image make the card easier to recognize but should come after the therapeutic sentence is clear.
+
+When a user says something like "I feel the urge to drink" or "help me not do this", search existing `flashcard` records first with `forge_search_entities` using `entityTypes: ["flashcard"]` and the user's urge, trigger words, tags, and situation language. If a matching card exists, show the flashcard message first, then add brief psychotherapy-informed support around it: grounding, urge surfing, cognitive defusion, schema/mode-aware reflection, or a values pivot. Do not create a new card until you have checked whether an existing one already fits.
+
 `trigger_report` is one specific emotionally meaningful episode described as what happened, what was felt, what was thought, what was done, what happened next, and what would help next time.
 
 `event_type` is a reusable category for trigger reports, such as rejection, criticism, conflict, uncertainty, or abandonment cue.
@@ -435,6 +446,16 @@ Only ask if missing or unclear:
 2. If it had a voice, what would it say, fear, or need?
 3. Would it help if we suggested one or two candidate mode labels, with reasons, before deciding whether to store a durable profile?
 
+`flashcard`
+Use for a small therapeutic card to retrieve during an urge, trigger, mode activation, belief activation, or values-based pivot.
+Minimum field: `message`
+Usually useful: `triggerSentence`, `triggerSituation`, `tags`, optional compact `title`, visual styling, optional `imageUrl`, links to values, behaviors, patterns, beliefs, modes, or reports
+Only ask if missing or unclear:
+
+1. What exact urge sentence, trigger, or situation should bring this card up?
+2. What one simple message should be centered on the card when that moment hits?
+3. What tags or trigger wording will help us find it later, and only then what visual tone, colors, typography, or image should it use?
+
 `trigger_report`
 Use for one specific emotionally important episode.
 Minimum field: `title`
@@ -475,7 +496,7 @@ Use the batch entity tools for stored records:
 `forge_search_entities`, `forge_create_entities`, `forge_update_entities`, `forge_delete_entities`, `forge_restore_entities`
 
 These tools operate on:
-`goal`, `project`, `strategy`, `task`, `habit`, `tag`, `note`, `insight`, `calendar_event`, `work_block_template`, `task_timebox`, `psyche_value`, `behavior_pattern`, `behavior`, `belief_entry`, `mode_profile`, `mode_guide_session`, `trigger_report`, `event_type`, `emotion_definition`, `preference_catalog`, `preference_catalog_item`, `preference_context`, `preference_item`, `questionnaire_instrument`, `sleep_session`, `workout_session`
+`goal`, `project`, `strategy`, `task`, `habit`, `tag`, `note`, `insight`, `calendar_event`, `work_block_template`, `task_timebox`, `psyche_value`, `behavior_pattern`, `behavior`, `belief_entry`, `mode_profile`, `mode_guide_session`, `flashcard`, `trigger_report`, `event_type`, `emotion_definition`, `preference_catalog`, `preference_catalog_item`, `preference_context`, `preference_item`, `questionnaire_instrument`, `sleep_session`, `workout_session`
 
 Use the wiki tools for SQLite-backed memory work:
 `forge_get_wiki_settings`, `forge_list_wiki_pages`, `forge_get_wiki_page`, `forge_search_wiki`, `forge_upsert_wiki_page`, `forge_get_wiki_health`, `forge_sync_wiki_vault`, `forge_reindex_wiki_embeddings`, `forge_ingest_wiki_source`

package/skills/forge-openclaw/entity_conversation_playbooks.md

@@ -237,10 +237,11 @@ Use this quick split before the conversation gets too detailed.
   `preference_signal`, and `self_observation` are action workflows. Start from what
   the user is trying to do, then use the dedicated action tool or note-backed write
   model.
-- `sleep_overview` and `sports_overview` are read-model-only surfaces. Use them when
-  the user wants to review nights, workouts, training load, recovery context, or
-  health patterns before deciding whether one stored `sleep_session` or
-  `workout_session` needs enrichment.
+- `operator_overview`, `operator_context`, `calendar_overview`, `sleep_overview`,
+  and `sports_overview` are read-model-only surfaces. Use them when the user wants
+  to understand current Forge state, work risk, calendar commitments, nights,
+  workouts, training load, recovery context, or health patterns before deciding
+  whether a stored entity needs creation or enrichment.
 - Movement, Life Force, and Workbench are specialized domain areas. Use their
   dedicated route families for timelines and overlays, energy profile/templates and
   fatigue signals, and Workbench flow execution or result artifacts. When available,
@@ -274,7 +275,8 @@ still knowing the exact write/read family before it acts.
   CRUD. Use health overview/read helpers for review and reflective update helpers only
   when enriching one already-known record after review.
 - `psyche_value`, `behavior_pattern`, `behavior`, `belief_entry`, `mode_profile`,
-  `mode_guide_session`, `trigger_report`, `event_type`, and `emotion_definition`:
+  `mode_guide_session`, `flashcard`, `trigger_report`, `event_type`, and
+  `emotion_definition`:
   psychologically meaningful records, but normal stored entities for API purposes.
   Search and mutate through shared batch entity routes after the formulation is clear.
 - `wiki_page`: specialized CRUD. Use wiki page/search/upsert routes so page rows,
@@ -282,6 +284,19 @@ still knowing the exact write/read family before it acts.
 - `calendar_connection`: specialized CRUD. Use provider discovery, connection CRUD,
   selected-calendar rediscovery, sync, and delete routes rather than batch entity
   tools.
+- `operator_overview`: read-model-only operator surface. Use
+  `forge_get_operator_overview` or `/api/v1/operator/overview` when the user wants
+  the current Forge picture, attention cues, or broad status before choosing a
+  specific entity action.
+- `operator_context`: read-model-only operator surface. Use
+  `forge_get_operator_context` or `/api/v1/operator/context` when the user wants
+  current work, active runs, risks, board context, or next moves before mutating
+  anything.
+- `calendar_overview`: read-model-only calendar surface. Use
+  `forge_get_calendar_overview` or `/api/v1/calendar/overview` when the user wants
+  mirrored events, work blocks, timeboxes, provider state, or availability before
+  creating a `calendar_event`, `work_block_template`, `task_timebox`, or
+  `calendar_connection`.
 - `task_run`: action workflow. Use task-run start, heartbeat, focus, complete, and
   release routes; never treat status changes as proof of live work.
 - `work_adjustment`: action workflow. Use the signed work-adjustment route for real
@@ -1061,6 +1076,81 @@ Preferred opening question:
 
 - "Which task or project should this time correction belong to?"
 
+## Operator Overview
+
+Aim: read the broad Forge state before choosing a specific action, without turning a
+status check into generic intake.
+
+Arc:
+
+1. Ask what the user is trying to understand about Forge overall.
+2. Read the operator overview before asking the user to reconstruct active work,
+   attention cues, or broad status from memory.
+3. Reflect the practical decision the overview should support.
+4. Move into a specific entity flow only when the overview points to a concrete goal,
+   project, task, habit, note, Psyche record, or follow-up action.
+
+Helpful follow-up lanes:
+
+- whether the user wants a broad status read, a priority decision, or a handoff
+- which owner or user scope matters if several humans or bots are involved
+- what decision the overview should help them make next
+
+Route note:
+
+- `operator_overview` is a read-model-only operator surface. Use
+  `forge_get_operator_overview` or `/api/v1/operator/overview`; do not create,
+  update, or delete `operator_overview` through batch CRUD.
+- If the read reveals a specific record that needs work, switch to that record's
+  normal route posture after the user chooses the follow-up.
+
+Ready to review when:
+
+- the broad question is clear enough
+- any owner or user scope that changes the read is clear enough
+
+Preferred opening question:
+
+- "What are you trying to understand about Forge overall right now?"
+
+## Operator Context
+
+Aim: inspect current work, active runs, risk, and next moves before changing records.
+
+Arc:
+
+1. Ask whether the user is checking current work, risk, blockers, active sessions, or
+   the next move.
+2. Read operator context before reopening a create or update intake.
+3. Reflect what the read is meant to decide: continue, stop, reprioritize, update, or
+   create.
+4. Move to task-run, work-adjustment, task, project, or note flow only when one
+   concrete follow-up is visible.
+
+Helpful follow-up lanes:
+
+- current task or active run
+- blocked or stale work
+- next move versus broad review
+- owner or user scope when bot and human work are both present
+
+Route note:
+
+- `operator_context` is a read-model-only operator surface. Use
+  `forge_get_operator_context` or `/api/v1/operator/context`; do not mutate it
+  through batch CRUD.
+- If the user decides to start, complete, release, or adjust work after the read,
+  switch to the dedicated action workflow for that operation.
+
+Ready to review when:
+
+- the current-work question is clear
+- any user or owner scope is clear enough
+
+Preferred opening question:
+
+- "What current work, risk, or next move are you trying to check?"
+
 ## Self Observation
 
 Aim: capture one observed episode in a structured chain without letting a loose note
@@ -1081,7 +1171,8 @@ Arc:
    visible.
 6. Decide whether this should stay a lightweight self-observation or become a
    `trigger_report`, `behavior_pattern`, `behavior`, `belief_entry`, `mode_profile`,
-   `mode_guide_session`, `event_type`, `emotion_definition`, or wiki page.
+   `mode_guide_session`, `flashcard`, `event_type`, `emotion_definition`, or wiki
+   page.
 7. Link the observation to the structured record when the structured record is the
    real container.
 
@@ -1104,7 +1195,8 @@ Route note:
 - Do not promote self-observation over functional analysis. If the user is describing
   a loop, use `behavior_pattern`; if they are describing one emotionally meaningful
   episode, use `trigger_report`; if a part-state is central, use `mode_guide_session`
-  or `mode_profile`; if a belief sentence is central, use `belief_entry`.
+  or `mode_profile`; if a belief sentence is central, use `belief_entry`; if the
+  user needs a rehearsable reminder during the trigger or urge, use `flashcard`.
 - If the user wants to remember a source, concept, book, article, or durable personal
   explanation, use `wiki_page` rather than self-observation.
 
@@ -1251,6 +1343,46 @@ Preferred opening question:
 
 - "What are you trying to understand from your workout picture right now?"
 
+## Calendar Overview
+
+Aim: review commitments, work blocks, provider state, and existing timeboxes before
+creating or changing calendar records.
+
+Arc:
+
+1. Ask what the user is trying to understand or decide from the calendar picture.
+2. Ask for the date range or owner scope only if it changes the read.
+3. Read the calendar overview before asking the user to recreate availability from
+   memory.
+4. Reflect the practical decision the overview should support.
+5. Move to `calendar_event`, `work_block_template`, `task_timebox`, or
+   `calendar_connection` only when a specific follow-up action is visible.
+
+Helpful follow-up lanes:
+
+- which day, week, or date range matters
+- whether the question is availability, conflicts, provider health, work blocks, or
+  existing timeboxes
+- what scheduling or planning decision the review should support
+
+Route note:
+
+- `calendar_overview` is a read-model-only calendar surface. Use
+  `forge_get_calendar_overview` or `/api/v1/calendar/overview`; do not create,
+  update, or delete `calendar_overview` through batch CRUD.
+- If the review reveals a concrete scheduling action, switch to the stored
+  `calendar_event`, `work_block_template`, or `task_timebox` batch route, or to the
+  specialized `calendar_connection` lifecycle route.
+
+Ready to review when:
+
+- the user's practical calendar question is clear
+- the relevant date range or owner scope is clear enough
+
+Preferred opening question:
+
+- "What are you trying to understand or decide from your calendar picture?"
+
 ## Calendar Connection
 
 Aim: connect the right provider deliberately without turning setup into a credential