forge-openclaw-plugin 0.2.70 → 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.70",
+  "version": "0.2.71",
   "activation": {
     "onStartup": true,
     "onCapabilities": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-openclaw-plugin",
-  "version": "0.2.70",
+  "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",

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.
 
@@ -237,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.
@@ -276,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.
@@ -318,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.
@@ -440,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`
@@ -480,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

@@ -275,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,
@@ -1170,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.
 
@@ -1193,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.
 

package/skills/forge-openclaw/psyche_entity_playbooks.md

@@ -237,6 +237,9 @@ short, tentative, and correctable.
   possible mode family only after the part's lived voice or posture is visible.
 - `mode_guide_session`: hypothesize about what the active part is trying to stop,
   force, prevent, or secure right now while keeping candidate mode labels provisional.
+- `flashcard`: hypothesize about the cue, urge sentence, mode/belief activation, or
+  values pivot the card should meet, then help craft one brief message the user can
+  recognize in that moment.
 - `trigger_report`: hypothesize about the episode chain only after the situation,
   felt stake, meaning, action, and consequence are at least partly visible.
 - `event_type`: hypothesize about the repeated emotional or relational stake that
@@ -384,8 +387,9 @@ will preserve the structure best.
 Psyche records are psychologically meaningful, but they are still normal stored Forge
 entities for API purposes. Once the formulation is clear and the user has consented to
 save or update it, use the shared batch entity routes for `psyche_value`,
-`behavior_pattern`, `behavior`, `belief_entry`, `mode_profile`,
-`mode_guide_session`, `trigger_report`, `event_type`, and `emotion_definition`.
+  `behavior_pattern`, `behavior`, `belief_entry`, `mode_profile`,
+`mode_guide_session`, `flashcard`, `trigger_report`, `event_type`, and
+`emotion_definition`.
 
 Keep the route decision internal. With the user, keep talking about the lived moment,
 belief sentence, pattern, mode, value, report, event kind, or feeling signature.
@@ -400,7 +404,15 @@ Do not divert Psyche material into `self_observation` just because it started as
 episode. Use `trigger_report` for one emotionally meaningful incident, use
 `behavior_pattern` for a recurring functional loop, use `belief_entry` for one
 explicit sentence, and use `mode_guide_session` or `mode_profile` when a part-state is
-central.
+central. Use `flashcard` when the user needs a small rehearsable message to retrieve
+during an urge, trigger, mode activation, belief activation, or values-based pivot.
+
+When a user says they feel an urge or asks for help not doing something, search
+existing `flashcard` records before creating a new one. Use `forge_search_entities`
+with `entityTypes: ["flashcard"]` and query text from the urge, tags, trigger
+sentence, trigger situation, and user's own words. If a card matches, show the card's
+message first, then add brief grounding, urge-surfing, cognitive defusion,
+schema/mode-aware reflection, or values-based coaching around it.
 
 ## Lane chooser
 
@@ -829,6 +841,55 @@ Preferred opening question:
 
 - "What just happened, and what is this part trying to get you to do or stop doing right now?"
 
+## Flashcard
+
+Aim: craft a small therapeutic card that can be retrieved during a specific urge,
+trigger, belief activation, mode shift, or values-based pivot.
+
+Arc:
+
+1. Start from the exact moment the card should help: the urge sentence, trigger cue,
+   mode activation, belief activation, or situation.
+2. Reflect what the card is trying to interrupt, steady, help the user tolerate, or
+   help the user choose.
+3. Ask for the one simple message that should be centered on the card, or offer one
+   concise working sentence if the user's meaning is clearer than their wording.
+4. Ask for tags, trigger sentence, and trigger situation before the title, because
+   retrieval matters more than the title.
+5. Ask about color, background, typography, image, layout, and visual tone only after
+   the message and retrieval cues are clear.
+6. If the user is in an urge right now, search existing flashcards first, show the
+   matching message first, then support it with brief psychotherapy-informed guidance.
+
+Helpful follow-up lanes:
+
+- the exact urge sentence or trigger cue
+- what the card should help the user remember when the urge is strongest
+- whether the card should interrupt an urge, comfort a part, challenge a belief, or
+  pivot toward a value
+- tags and trigger wording for future retrieval
+- visual tone, colors, typography, layout, or image after the message is clear
+
+Likely linked entities:
+
+- `behavior` when the card supports interrupting or replacing one recurring move
+- `behavior_pattern` when the card belongs to a larger loop
+- `belief_entry` when the card answers one activated belief sentence
+- `mode_profile` when the card speaks to a recurring part-state
+- `psyche_value` when the card points back to a chosen value
+- `trigger_report` when the card was created from one meaningful episode
+
+Ready to save when:
+
+- the main `message` is clear enough to show back during the hard moment
+- at least one retrieval cue is clear: tag, trigger sentence, trigger situation, or
+  linked Psyche record
+- title and visual styling are either chosen or intentionally left for later
+
+Preferred opening question:
+
+- "What exact urge sentence or situation should make this card appear?"
+
 ## Trigger Report
 
 Aim: capture one emotionally meaningful episode clearly enough that it can teach the