forge-openclaw-plugin 0.2.19 → 0.2.21

package/skills/forge-openclaw/SKILL.md

@@ -1,17 +1,63 @@
 ---
 name: forge-openclaw
-description: use when the user wants to save, search, update, review, start, stop, reward, or explain work or psyche records inside forge, or when the conversation is clearly about a forge entity such as a goal, project, task, habit, note, calendar_event, work_block_template, task_timebox, task_run, insight, psyche_value, behavior_pattern, behavior, belief_entry, mode_profile, mode_guide_session, trigger_report, event_type, or emotion_definition. identify the exact forge entity, keep the main conversation natural, offer saving once when helpful, ask only for missing fields, and use the correct forge tool and payload shape.
+description: use when the user wants to save, search, update, review, start, stop, reward, explain, or compare Forge records, or when the conversation is clearly about a Forge entity such as a goal, project, strategy, task, habit, note, calendar_event, work_block_template, task_timebox, task_run, insight, preference item, preference context, preference catalog, psyche_value, behavior_pattern, behavior, belief_entry, mode_profile, mode_guide_session, trigger_report, event_type, or emotion_definition. identify the exact Forge object, 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.
 
-Forge has two major domains. The planning side covers goals, projects, tasks, habits, notes, calendar events, recurring work blocks, task timeboxes, live work sessions, and agent-authored insights. The Psyche side covers values, patterns, behaviors, beliefs, modes, guided mode sessions, trigger reports, event types, and reusable emotion definitions. 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. They can link directly to goals, projects, tasks, values, patterns, behaviors, beliefs, modes, and trigger reports, and they participate in the same searchable noteable graph as the rest of Forge.
+Forge has four major 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. Forge also has a file-first Wiki memory layer with explicit spaces, local markdown pages, 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.
 
+Preferences rule:
+
+- When the user wants to understand or refine taste, ranking, recommendation fit, or “what Forge thinks I like”, treat that as the Preferences surface rather than a normal planning intake.
+- The default Preferences UX starts from what Forge already knows and then offers one prominent `Start the game` action.
+- The comparison flow is visual and modal. Prefer opening the Forge UI when the user wants to play comparisons directly.
+- For Forge-native domains, Forge can seed items from existing entities automatically.
+- For broader domains such as food or activities, Forge can use seeded concept libraries that the user can later edit.
+
+Wiki rule:
+
+- Treat the Wiki as the canonical long-form memory surface, not as a loose note dump.
+- Use the wiki tools when the user wants file-first reference pages, backlink-aware recall, ingest from a URL or local file, or wiki maintenance work such as unresolved-link cleanup.
+- `forge_ingest_wiki_source` now queues the ingest as background work; use the Forge UI handoff when the user wants to review or keep only selected wiki/entity candidates after the ingest finishes.
+- Keep evidence notes and wiki pages conceptually distinct: evidence notes are linked operating records, while wiki pages are the curated memory vault.
+
+Wiki navigation and search rule:
+
+- The wiki has a stable top-level structure. The home page is `index`, and the default high-level branches are `people`, `projects`, `concepts`, `sources`, and `chronicle`.
+- `people` is for durable person pages and relationship context. `projects` is for ongoing initiatives and bounded workstreams. `concepts` is for reusable ideas, methods, and frameworks. `sources` is for raw materials and imports. `chronicle` is for timeline-style logs and ongoing narrative.
+- Treat `wiki` pages as canonical synthesis and `evidence` notes as supporting records. If the user wants the durable summary, search the wiki pages first. If they want raw supporting context or operational detail, evidence notes may be the better target.
+- When the user wants a person, search the full name first, then obvious aliases, nicknames, or paired context such as collaborator names or city. Person pages often sit under the `people` branch but the reliable method is still search-first.
+- When the user wants a conversation or chat, search the conversation name, the participant names, and any distinctive nickname used in the thread. Group-chat imports often become a durable synthesis page with a normalized title rather than the raw file name.
+- When the user wants a concept, search the exact phrase first, then close variants, abbreviations, and adjacent terms. Concept pages often live under `concepts`, but search is still better than assuming the parent branch.
+- When the user wants one exact page and already knows the title or slug, search that exact title or slug first, then open the best wiki page result instead of broad browsing.
+- Use `forge_search_wiki` as the default wiki recall tool. It is the main route for people, conversations, concepts, and exact page lookup.
+- Use `forge_list_wiki_pages` when the user wants to browse structure, inspect a branch, or understand how pages are organized rather than search by phrase.
+- Use `forge_get_wiki_page` after search yields a likely hit, or when the user already identified the page to open.
+- Use `forge_get_wiki_settings` or `forge_get_wiki_health` when the task is about wiki maintenance, indexing, unresolved links, ingest setup, or vault integrity rather than content recall.
+
+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.
+- Use `forge_update_sleep_session` and `forge_update_workout_session` when the user wants to attach reflective context, tags, or Forge links to an existing health record.
+- 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.
+
 Write to Forge only with clear user consent. If the user is just thinking aloud, helping first is usually better than writing immediately. After helping, you may offer one short Forge prompt if the match is strong. If the user agrees, ask only for the missing fields and only one to three focused questions at a time. Do not offer Forge again after a decline unless the user reopens it.
 
-Optional recurring automation templates live in `cron_jobs.md` next to this skill. Use that file only when the user explicitly asks for recurring Forge automations, cron jobs, scheduled check-ins, or a recurring synthesis workflow. Those entries are rich examples, not defaults: adapt personal details such as names, recipients, phone numbers, or project titles to the current user, but preserve the intended tone, operational logic, and any example naming conventions when the user chooses to adopt that pattern.
+Entity conversation rule:
+
+- For all entity creation or update flows, first use [`entity_conversation_playbooks.md`](./entity_conversation_playbooks.md) to decide the next best question.
+- Ask only for what is missing or unclear. Do not walk through every schema field.
+- Let each question have one job. Know what you are trying to clarify before you ask it.
+- Prefer a progression of:
+  concrete example or intent -> working name -> purpose or meaning -> placement in Forge -> operational details -> linked context.
+- For emotionally meaningful non-Psyche records such as goals, habits, and notes, reflect the meaning before you ask for structure.
+- When updating an entity, start with what is changing, what should stay true, and what prompted the update now.
+- When enough is clear, briefly summarize what you heard in the user's own language before asking for the last missing structural detail.
+- The quick intake prompts later in this file are fallback checkpoints, not a script to read aloud.
 
 Forge data location rule:
 
@@ -20,8 +66,24 @@ Forge data location rule:
 - on a linked repo-local install, this usually means `<repo>/openclaw-plugin/data/forge.sqlite`
 - if the user wants the data somewhere else for persistence, backup, or manual control, tell them to set `plugins.entries["forge-openclaw-plugin"].config.dataRoot` and restart the OpenClaw gateway
 - if the user asks where the data is stored or how to move it, explain the current default plainly and show the exact config field
-- if the user wants to manage a plugin-managed local Forge runtime cleanly, tell them to run `openclaw forge start`, `openclaw forge stop`, `openclaw forge restart`, or `openclaw forge status`
-- these commands only manage a runtime that the OpenClaw plugin auto-started itself; if Forge was started manually elsewhere, they will say so instead of killing random local processes
+
+Psyche interview rule:
+
+- For `psyche_value`, `behavior_pattern`, `behavior`, `belief_entry`, `mode_profile`, `mode_guide_session`, and `trigger_report`, do not jump straight to raw field collection.
+- 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.
+- Start from a recent concrete example before naming an abstract pattern, belief, or mode.
+- After the first real answer, choose one follow-up lane at a time: situation, sequence, meaning, protection, cost, longing/value, or tentative name.
+- If the user says they want help understanding a Psyche issue before saving it, ask one orienting question first instead of jumping straight into a full interpretation, diagnosis-like label, save suggestion, replacement belief, or suggested title.
+- In that first exploratory turn, keep the reflection to one or two short sentences, avoid numbered lists or schema dumps, and wait for the user's answer before offering a fuller formulation.
+- In that first exploratory turn, stay in plain prose, end with one question, and do not mention Forge fields or save formatting yet unless the user interrupts to save immediately.
+- In that first exploratory turn, keep the whole reply short, usually under 90 words, and anchor it in one concrete-example question rather than a conceptual lecture.
+- In that first exploratory turn, ask only one question, do not search Forge or mention whether a matching entity exists, and avoid openings like "This sounds like" or "What you're describing is".
+- In that first exploratory turn, prefer exactly two sentences: one brief empathic reflection and one concrete question. Avoid colons because they tend to trigger list-like answers.
+- Follow the preferred opening-question patterns in [`psyche_entity_playbooks.md`](./psyche_entity_playbooks.md) when they fit the entity the user is exploring.
+- When the conversation reveals an adjacent entity such as a linked belief, mode, value, pattern, or note, name that gently and ask whether the user wants to map it too.
+- If nuance matters, preserve it in a linked Markdown `note` instead of forcing every detail into normalized fields.
+- If the user shows imminent risk of self-harm, suicide, violence, inability to stay safe, or severe disorientation, stop normal intake and prioritize urgent human support or emergency help instead.
 
 Use these exact entity meanings when deciding what the user is describing.
 
@@ -35,6 +97,10 @@ Use these exact entity meanings when deciding what the user is describing.
 
 `note` is a first-class Markdown entity that can link to one or many other entities. Use it for work summaries, context, progress logs, handoff explanations, wiki-style reference pages, or reflective detail that should stay searchable and attached to the right records. Notes also support note-owned `tags` for memory-system labels such as `Working memory`, `Short-term memory`, `Episodic memory`, `Semantic memory`, and `Procedural memory`, plus custom tags. Notes may be durable or ephemeral: if `destroyAt` is set, Forge will delete the note automatically after that time.
 
+`sleep_session` is a first-class health record for one night. It can hold recovery metrics, stage breakdown, annotations, and links back to goals, projects, tasks, habits, notes, and Psyche records.
+
+`workout_session` is a first-class sports record. It can come from HealthKit import or from a completed habit, and it can carry subjective effort, mood, meaning, tags, and links back into Forge.
+
 `insight` is an agent-authored observation, recommendation, or warning grounded in Forge data. It does not replace a requested goal, project, task, pattern, belief, or trigger report.
 
 `calendar_event` is a canonical Forge event record. It lives in Forge first and can later project to a writable provider calendar.
@@ -96,7 +162,7 @@ Ask:
 `habit`
 Use for a recurring commitment or recurring slip with explicit cadence and XP consequences.
 Minimum field: `title`
-Usually useful: `polarity`, `frequency`, `linkedGoalIds`, `linkedProjectIds`, `linkedTaskIds`, `linkedValueIds`, `linkedPatternIds`, `linkedBehaviorIds`, `linkedBeliefIds`, `linkedModeIds`, `linkedReportIds`
+Usually useful: `polarity`, `frequency`
 CRITICAL NEGATIVE-HABIT CHECK-IN RULE:
 
 - For a `negative` habit, the correct check-in outcome is `missed`.
@@ -106,7 +172,7 @@ CRITICAL NEGATIVE-HABIT CHECK-IN RULE:
 
 1. What is the recurring behavior in one concrete sentence?
 2. Is doing it good (`positive`) or a slip (`negative`)?
-3. What should it link back to in Forge or Psyche?
+3. What cadence should it follow?
 
 `task_run`
 Use for live work happening now.
@@ -119,9 +185,9 @@ Minimum field: `title`
 Usually useful: `description`, `valuedDirection`, `whyItMatters`, links to goals, projects, or tasks
 Ask:
 
-1. What value or direction is this?
-2. How would you describe it in your own words?
-3. Why does it matter now?
+1. What feels deeply important here, and what would you call that value or direction?
+2. If you were living it a little more this week, what would someone actually see?
+3. Why does it matter now, and what one action would move toward it?
 
 `behavior_pattern`
 Use for a recurring loop across situations.
@@ -129,9 +195,9 @@ Minimum field: `title`
 Usually useful: `description`, `targetBehavior`, `cueContexts`, `shortTermPayoff`, `longTermCost`, `preferredResponse`
 Ask:
 
-1. What would you call this pattern?
-2. What usually sets it off, and what tends to happen next?
-3. What does it give you in the short term, what does it cost later, and what response would you rather make?
+1. Can we slow this down using one recent example first?
+2. What usually sets the loop off, and what tends to happen in thoughts, feelings, body, and actions next?
+3. What does it do for you immediately, what does it cost later, and what belief, mode, or value seems bound up in it?
 
 `behavior`
 Use for one recurring move or action tendency.
@@ -139,9 +205,9 @@ Minimum fields: `kind`, `title`
 Usually useful: `commonCues`, `urgeStory`, `shortTermPayoff`, `longTermCost`, `replacementMove`, `repairPlan`
 Ask:
 
-1. What happened, in plain language?
-2. Is it an `away`, `committed`, or `recovery` behavior?
-3. What cues show up, and what move would you want available instead?
+1. What does this behavior actually look like in plain language?
+2. What cues or urges usually pull you toward it, and what does it do for you in the moment?
+3. Is it an `away`, `committed`, or `recovery` behavior, and what move would you want available instead?
 
 `belief_entry`
 Use for one explicit belief sentence.
@@ -149,9 +215,9 @@ Minimum fields: `statement`, `beliefType`
 Usually useful: `confidence`, `evidenceFor`, `evidenceAgainst`, `flexibleAlternative`, `originNote`
 Ask:
 
-1. What is the belief in one sentence?
+1. If we turn that reaction into one sentence, what does the belief sound like in your own words?
 2. Is it `absolute` or `conditional`, and how true does it feel from 0 to 100?
-3. What supports it, what weakens it, and what would be a more flexible alternative?
+3. What seems to support it, what weakens it, where did you learn it, and what would be a more flexible alternative?
 
 `mode_profile`
 Use for a recurring part-state or inner role.
@@ -159,14 +225,18 @@ Minimum fields: `family`, `title`
 Usually useful: `fear`, `burden`, `protectiveJob`, `originContext`, links to patterns, behaviors, and values
 Ask:
 
-1. What kind of mode is this: `coping`, `child`, `critic_parent`, `healthy_adult`, or `happy_child`?
-2. What should this mode be called?
-3. What does it fear, carry, or try to protect?
+1. When this part shows up, what is it like from the inside and what should it be called?
+2. What kind of mode is this: `coping`, `child`, `critic_parent`, `healthy_adult`, or `happy_child`?
+3. What does it fear, carry, or try to protect, and when did you first need it?
 
 `mode_guide_session`
 Use for guided exploration before or alongside a durable mode profile.
-Minimum fields: `summary`, `answers`, `results`
-Ask only what is needed to capture the guided exploration and the candidate interpretations.
+Minimum fields: `summary`, `answers`
+Ask:
+
+1. What just happened that brought this part online right now?
+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?
 
 `trigger_report`
 Use for one specific emotionally important episode.
@@ -174,9 +244,9 @@ Minimum field: `title`
 Usually useful: `eventSituation`, `occurredAt`, `emotions`, `thoughts`, `behaviors`, `consequences`, `nextMoves`, links to values, beliefs, patterns, modes, goals, projects, or tasks
 Ask:
 
-1. What happened?
-2. What emotions were present, and how intense were they?
-3. What thoughts showed up, what did you do next, and what would be the useful next move now?
+1. What happened, as concretely as you can say it?
+2. What emotions were present, how intense were they, and what thoughts or meanings showed up?
+3. What did you do next, what did that do short term and long term, and what pattern, belief, or mode seems most active here?
 
 `event_type`
 Use for a reusable trigger category.
@@ -209,11 +279,16 @@ Use the batch entity tools for stored records:
 These tools operate on:
 `goal`, `project`, `task`, `habit`, `note`, `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`
 
+Use the wiki tools for file-first 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`
+
+Sleep and workout sessions are not batch entities. Use the health tools instead:
+`forge_get_sleep_overview`, `forge_get_sports_overview`, `forge_update_sleep_session`, `forge_update_workout_session`
+
 Use live work tools for `task_run`:
-`forge_adjust_work_minutes`, `forge_log_work`, `forge_start_task_run`, `forge_heartbeat_task_run`, `forge_focus_task_run`, `forge_complete_task_run`, `forge_release_task_run`
+`forge_log_work`, `forge_start_task_run`, `forge_heartbeat_task_run`, `forge_focus_task_run`, `forge_complete_task_run`, `forge_release_task_run`
 
 Use `forge_post_insight` for `insight`.
-Use `forge_grant_reward_bonus` only for explicit manual XP bonuses or penalties that should be auditable and cannot be expressed through the normal task-run or habit check-in routes.
 Use the calendar tools for provider sync and planning:
 `forge_get_calendar_overview`, `forge_connect_calendar_provider`, `forge_sync_calendar_connection`, `forge_create_work_block_template`, `forge_recommend_task_timeboxes`, `forge_create_task_timebox`
 
@@ -283,8 +358,6 @@ Use `forge_release_task_run` to stop live work without completing the task. `clo
 
 Use `forge_log_work` only for retroactive work that already happened. If the user explains the work in a way that should be preserved, include `closeoutNote`.
 
-Use `forge_adjust_work_minutes` when the task or project already exists and the user only needs tracked minutes corrected up or down. This is the truthful path for signed retrospective minute adjustments and it automatically applies symmetric XP changes when reward buckets are crossed.
-
 Use the calendar tools when the request is about planning or availability rather than entity storage:
 
 - `forge_get_calendar_overview` to inspect mirrored events, work blocks, provider connections, and existing timeboxes
@@ -294,6 +367,14 @@ Use the calendar tools when the request is about planning or availability rather
 - `forge_recommend_task_timeboxes` to find future slots that satisfy current rules
 - `forge_create_task_timebox` as a convenience helper to confirm a selected slot into a real planned timebox
 
+Use the health tools when the request is about sleep or sports review:
+
+- `forge_get_sleep_overview` to inspect recent nights, averages, regularity, stage breakdown, and linked reflective context
+- `forge_get_sports_overview` to inspect training volume, workout types, effort trends, habit-generated sessions, and linked context
+- `forge_update_sleep_session` to add sleep-quality notes, tags, or links back to Forge entities
+- `forge_update_workout_session` to add subjective effort, mood, meaning, tags, or links on one workout
+- remember that the UI route is `/sports` while the backend overview route is `/api/v1/health/fitness`
+
 Work-block payload guidance:
 
 - `kind` must be one of `main_activity`, `secondary_activity`, `third_activity`, `rest`, `holiday`, or `custom`
@@ -326,8 +407,6 @@ Use these exact calendar batch payload shapes when working generically:
 - create a planned task slot:
   `{"operations":[{"entityType":"task_timebox","data":{"taskId":"task_123","projectId":"project_456","title":"Draft the methods section","startsAt":"2026-04-03T06:00:00.000Z","endsAt":"2026-04-03T07:30:00.000Z","source":"suggested"}}]}`
 
-Do not use `forge_adjust_work_minutes` to simulate a live session. Live work still belongs in `forge_start_task_run` and the rest of the task-run workflow.
-
 Use these interaction rules.
 
 Keep the main discussion natural. Do not turn every conversation into a form. Do not offer Forge for every passing mention. Offer it once, near the end, only when the signal is strong and storing would help.
@@ -349,18 +428,31 @@ When the user asks which Forge tools are available, list exactly these tools:
 `forge_get_operator_overview`
 `forge_get_operator_context`
 `forge_get_agent_onboarding`
+`forge_get_user_directory`
 `forge_get_psyche_overview`
+`forge_get_sleep_overview`
+`forge_get_sports_overview`
 `forge_get_xp_metrics`
 `forge_get_weekly_review`
 `forge_get_current_work`
 `forge_get_ui_entrypoint`
+`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`
 `forge_search_entities`
 `forge_create_entities`
 `forge_update_entities`
 `forge_delete_entities`
 `forge_restore_entities`
 `forge_grant_reward_bonus`
-`forge_adjust_work_minutes`
+`forge_update_sleep_session`
+`forge_update_workout_session`
 `forge_log_work`
 `forge_start_task_run`
 `forge_heartbeat_task_run`

package/skills/forge-openclaw/entity_conversation_playbooks.md

@@ -0,0 +1,337 @@
+# Entity Conversation Playbooks
+
+Use this file whenever the user is creating or updating a Forge entity outside the
+deeper Psyche exploration flow. The point is to keep the conversation natural and
+intentional while still gathering enough structure to store the right record.
+
+## Interaction stance
+
+- Ask only for what is missing or still unclear.
+- Lead the user somewhere. Know whether you are trying to clarify the name, the role,
+  the outcome, the placement, the timing, the success condition, or the links.
+- Let each question have one job. If you cannot say what the question is trying to
+  clarify, ask a different question.
+- Ask one to three focused questions at a time. One is usually best when the user is
+  unsure or emotionally loaded.
+- Reflect briefly before the next question when the user gives nuance that matters.
+- For emotionally meaningful planning records such as goals, habits, and notes, reflect
+  the meaning first and then ask for the structure.
+- Do not read schema fields out loud unless the user explicitly wants a mechanical
+  checklist.
+- Prefer a progression of:
+  recent intent or concrete example -> working name -> purpose or outcome -> placement
+  in Forge -> operational details -> linked context.
+- If the user already gave a usable title, timing, or parent context, do not ask for it
+  again just because the schema has that field.
+- When the user says "save something about..." and the record is still fuzzy, help them
+  sharpen what they are trying to preserve before you ask for the final Forge shape.
+- When the meaning is clearer than the wording, offer a tentative title or summary
+  yourself and ask whether it fits. Do not make the user do all the naming work alone.
+- Before saving, offer a short working summary in the user's own language when that
+  would reduce ambiguity.
+- When updating, start with:
+  what is changing,
+  what should stay true,
+  and what prompted the update now.
+
+## Question design rules
+
+- Prefer one clean question over a stacked sentence with multiple asks.
+- For straightforward logistical entities such as tasks, calendar events, work blocks,
+  timeboxes, and task runs, use the fast path: confirm what is already clear and ask
+  for only the one missing operational detail.
+- When you need two details, ask for the more meaning-bearing one first.
+- If the user sounds uncertain, ask for an example before an abstraction.
+- If the user sounds clear and decisive, confirm the working formulation and move to the
+  one missing structural detail.
+- A good next question usually clarifies one of these:
+  what this is,
+  why it matters,
+  where it belongs,
+  what success looks like,
+  when it should happen,
+  or what should stay linked.
+- Before the final save question, it is often better to offer a tentative formulation
+  than to ask for a raw title. Example shape:
+  "This sounds like a project about repairing trust with Lea, not just a loose note.
+  Does that fit, and if so what outcome would tell you it is moving?"
+- Avoid dead-form prompts like "What should this be called?" when the user is still
+  figuring out what the thing is. Name first, then ask for correction.
+
+## Update loop
+
+Use this when the user is updating an existing record rather than creating a new one.
+
+1. Ask what feels newly true, newly urgent, or newly clear.
+2. Ask what should stay intact so the record does not lose its core meaning.
+3. Ask for the concrete trigger for the update if it matters.
+4. Then ask only for the missing structural detail required by the change.
+
+## Goal
+
+Aim: clarify the direction and why it matters, not just produce a title.
+
+Arc:
+
+1. Ask what direction or outcome the user wants to keep in view.
+2. Ask why it matters now.
+3. Distinguish the goal from a project or task.
+4. Clarify horizon and status only after the meaning is clear.
+
+Ready to save when:
+
+- the goal has a stable name
+- the direction is understandable in plain language
+- the horizon is clear enough if it matters
+
+Preferred opening question:
+
+- "What direction are you trying to hold onto here, in a way you would want future-you to keep seeing?"
+
+## Project
+
+Aim: turn an intention into a bounded workstream with a clear outcome.
+
+Arc:
+
+1. Ask what this piece of work should be called.
+2. Ask what outcome would make the project feel real or complete for now.
+3. Ask which goal it belongs under.
+4. Clarify status, owner, and notes only after the scope is clear.
+
+Ready to save when:
+
+- the project has a clear name
+- the outcome is concrete enough to recognize later
+- its parent goal is known or intentionally absent pending follow-up
+
+Preferred opening question:
+
+- "If this becomes a real project in Forge, what outcome would make it feel genuinely underway or complete?"
+
+## Strategy
+
+Aim: turn a vague plan into a deliberate sequence toward a real end state.
+
+Arc:
+
+1. Ask what end state the strategy is trying to land.
+2. Ask which goals or projects are the true targets.
+3. Ask what the major steps or nodes are.
+4. Ask about order, dependencies, and anything that must not be skipped.
+5. Clarify linked entities or ownership once the sequence itself makes sense.
+
+Ready to save when:
+
+- the strategy has a stable name
+- the end state is concrete enough to test
+- the directed sequence is sketched clearly enough to build the graph
+
+Preferred opening question:
+
+- "What future state is this strategy supposed to make real?"
+
+## Task
+
+Aim: identify the next concrete move, not just capture a vague obligation.
+
+Arc:
+
+1. Ask what the next concrete action is.
+2. Ask where it belongs: project, goal, both, or standalone.
+3. Ask what would make it easier to do: due date, priority, owner, or brief context.
+
+Ready to save when:
+
+- the task is phrased as an actionable move
+- placement is clear enough
+- any crucial timing or priority is captured
+
+Preferred opening question:
+
+- "What is the next concrete move you want to remember or do?"
+
+## Habit
+
+Aim: define the recurring behavior and the cadence in a way that makes later check-ins unambiguous.
+
+Arc:
+
+1. Ask what the recurring behavior is in plain language.
+2. Ask whether doing it is aligned or a slip.
+3. Ask about cadence and what counts as success in practice.
+4. Ask about links to goals, tasks, or Psyche entities only if that would help later review.
+
+Ready to save when:
+
+- the recurring behavior is specific
+- polarity is clear
+- the cadence and success condition are clear enough to check in honestly
+
+Preferred opening question:
+
+- "What is the recurring behavior you want Forge to keep track of?"
+
+## Note
+
+Aim: preserve the useful context and link it to the right places without turning the note into a dumping ground.
+
+Arc:
+
+1. Ask what the note needs to preserve.
+2. Ask what entities it should stay attached to.
+3. Ask whether it should be durable or temporary.
+4. Ask about tags or author only if they help retrieval or handoff.
+
+Ready to save when:
+
+- the note body captures the important point
+- the links are clear
+- durability versus ephemeral memory is clear when relevant
+
+Preferred opening question:
+
+- "What feels important to preserve from this?"
+
+## Insight
+
+Aim: capture one grounded observation or recommendation clearly enough that it remains useful later.
+
+Arc:
+
+1. Ask what pattern, tension, or observation should be remembered.
+2. Ask what entity or timeframe it belongs to, if any.
+3. Ask what recommendation, caution, or invitation should remain explicit.
+
+Ready to save when:
+
+- the observation has a stable title or phrase
+- the summary is clear
+- the recommendation is explicit
+
+Preferred opening question:
+
+- "What is the clearest thing you want future-you or the agent to remember from this?"
+
+## Calendar Event
+
+Aim: make the event legible as a real commitment in time, with the right timezone and links.
+
+Arc:
+
+1. Ask what the event is.
+2. Ask when it starts and ends in local time.
+3. Ask where it belongs or what it supports.
+4. Ask whether it should stay Forge-only only if that choice matters.
+
+Ready to save when:
+
+- the title is clear
+- the start and end are clear in the user's timezone
+- any important links or storage preference are known
+
+Preferred opening question:
+
+- "What is the event, and when should it happen in your local time?"
+
+## Work Block Template
+
+Aim: define a reusable availability rule, not a one-off event.
+
+Arc:
+
+1. Ask what kind of block it is and what it should be called.
+2. Ask on which days and at what local times it should repeat.
+3. Ask whether it allows or blocks work.
+4. Ask whether it has a start or end date.
+
+Ready to save when:
+
+- the block has a clear purpose
+- recurrence timing is clear
+- blocking state is clear
+
+Preferred opening question:
+
+- "What recurring block do you want to set up, and when should it repeat?"
+
+## Task Timebox
+
+Aim: reserve real time for one task without confusing planned work with completed work.
+
+Arc:
+
+1. Ask which task the slot belongs to.
+2. Ask when the slot should start and end.
+3. Ask whether this is a manual reservation, a suggestion, or a live-run alignment only if relevant.
+4. Ask about override reason only if calendar rules are being bypassed.
+
+Ready to save when:
+
+- the task is known
+- the time window is clear
+- any special scheduling context is explicit
+
+Preferred opening question:
+
+- "Which task are you trying to make time for, and when should the slot be?"
+
+## Task Run
+
+Aim: start truthful live work with as little friction as possible while still knowing
+what is being worked on and by whom.
+
+Arc:
+
+1. Confirm the task.
+2. Confirm the actor only if it is not already obvious.
+3. Ask whether the run should be planned or unlimited only if that changes the action.
+4. Start the run instead of turning it into intake.
+
+Ready to start when:
+
+- the task is identified clearly enough
+- the actor is clear enough
+- any timer mode choice that matters is explicit
+
+Preferred opening question:
+
+- "Which task should I start?"
+
+## Event Type
+
+Aim: create a reusable incident category that will actually help future reports stay consistent.
+
+Arc:
+
+1. Ask what category the label should capture.
+2. Ask how narrow or broad it should be.
+3. Ask for a short description only if the label could be ambiguous later.
+
+Ready to save when:
+
+- the label is stable
+- the category boundary is clear enough to reuse
+
+Preferred opening question:
+
+- "What kind of incident should this category stand for?"
+
+## Emotion Definition
+
+Aim: create a reusable emotion label with enough clarity to use consistently later.
+
+Arc:
+
+1. Ask what emotion label the user wants to preserve.
+2. Ask what distinguishes it from nearby emotions.
+3. Ask for a broader category only if it will help later browsing or reporting.
+
+Ready to save when:
+
+- the label is stable
+- the meaning is clear enough to reuse
+
+Preferred opening question:
+
+- "What emotion label do you want to keep reusable in Forge?"