forge-openclaw-plugin 0.2.26 → 0.2.27

package/server/migrations/042_movement_boxes.sql

@@ -0,0 +1,47 @@
+CREATE TABLE IF NOT EXISTS movement_boxes (
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL,
+  kind TEXT NOT NULL CHECK (kind IN ('stay', 'trip', 'missing')),
+  source_kind TEXT NOT NULL CHECK (source_kind IN ('automatic', 'user_defined')),
+  origin TEXT NOT NULL CHECK (
+    origin IN (
+      'recorded',
+      'continued_stay',
+      'repaired_gap',
+      'missing',
+      'user_defined',
+      'user_invalidated'
+    )
+  ),
+  started_at TEXT NOT NULL,
+  ended_at TEXT NOT NULL,
+  title TEXT NOT NULL DEFAULT '',
+  subtitle TEXT NOT NULL DEFAULT '',
+  place_label TEXT,
+  anchor_external_uid TEXT,
+  tags_json TEXT NOT NULL DEFAULT '[]',
+  distance_meters REAL,
+  average_speed_mps REAL,
+  editable INTEGER NOT NULL DEFAULT 0,
+  override_count INTEGER NOT NULL DEFAULT 0,
+  overridden_automatic_box_ids_json TEXT NOT NULL DEFAULT '[]',
+  raw_stay_ids_json TEXT NOT NULL DEFAULT '[]',
+  raw_trip_ids_json TEXT NOT NULL DEFAULT '[]',
+  raw_point_count INTEGER NOT NULL DEFAULT 0,
+  has_legacy_corrections INTEGER NOT NULL DEFAULT 0,
+  legacy_origin_key TEXT,
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  deleted_at TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_movement_boxes_user_time
+ON movement_boxes(user_id, started_at, ended_at);
+
+CREATE INDEX IF NOT EXISTS idx_movement_boxes_user_source
+ON movement_boxes(user_id, source_kind, deleted_at, started_at);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_movement_boxes_legacy_origin
+ON movement_boxes(user_id, legacy_origin_key)
+WHERE legacy_origin_key IS NOT NULL;

package/server/migrations/043_movement_box_overlap_overrides.sql

@@ -0,0 +1,26 @@
+ALTER TABLE movement_boxes
+ADD COLUMN true_started_at TEXT;
+
+ALTER TABLE movement_boxes
+ADD COLUMN true_ended_at TEXT;
+
+ALTER TABLE movement_boxes
+ADD COLUMN overridden_started_at TEXT;
+
+ALTER TABLE movement_boxes
+ADD COLUMN overridden_ended_at TEXT;
+
+ALTER TABLE movement_boxes
+ADD COLUMN overridden_by_box_id TEXT;
+
+ALTER TABLE movement_boxes
+ADD COLUMN overridden_user_box_ids_json TEXT NOT NULL DEFAULT '[]';
+
+ALTER TABLE movement_boxes
+ADD COLUMN override_ranges_json TEXT NOT NULL DEFAULT '[]';
+
+ALTER TABLE movement_boxes
+ADD COLUMN is_overridden INTEGER NOT NULL DEFAULT 0;
+
+ALTER TABLE movement_boxes
+ADD COLUMN is_fully_hidden INTEGER NOT NULL DEFAULT 0;

package/skills/forge-openclaw/SKILL.md

@@ -41,8 +41,9 @@ Wiki navigation and search rule:
 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.
+- Use `forge_get_sleep_overview` and `forge_get_sports_overview` for review and trend reading.
+- 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.
 
 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.
@@ -64,9 +65,9 @@ Entity conversation rule:
 
 Forge data location rule:
 
-- by default, Forge stores data under the active runtime root at `data/forge.sqlite`
-- on a normal OpenClaw install, this usually means `~/.openclaw/extensions/forge-openclaw-plugin/data/forge.sqlite`
-- on a linked repo-local install, this usually means `<repo>/openclaw-plugin/data/forge.sqlite`
+- by default, Forge stores data under the active runtime root at `forge.sqlite`
+- on a normal OpenClaw install, this usually means `~/.openclaw/extensions/forge-openclaw-plugin/forge.sqlite`
+- on a linked repo-local install, this usually means `<repo>/openclaw-plugin/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
 
@@ -282,12 +283,12 @@ 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`, `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`
+`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`
 
 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:
+Use the health tools for review and reflective enrichment, not as the default CRUD architecture:
 `forge_get_sleep_overview`, `forge_get_sports_overview`, `forge_update_sleep_session`, `forge_update_workout_session`
 
 Use live work tools for `task_run`:
@@ -343,7 +344,7 @@ For project deletion and recovery, prefer the generic delete and restore tools:
 
 For restore operations, each item must include `entityType` and `id`.
 
-Batch tools do not create or control `task_run` or `insight`.
+Batch tools do not create or control `task_run`.
 
 Use the exact route-facing field names. Do not invent friendlier aliases. If a field name is unclear, use `forge_get_agent_onboarding` as the schema source of truth.
 
@@ -376,10 +377,21 @@ 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
+- `forge_update_sleep_session` to add sleep-quality notes, tags, or links back to Forge entities after review
+- `forge_update_workout_session` to add subjective effort, mood, meaning, tags, or links on one workout after review
 - remember that the UI route is `/sports` while the backend overview route is `/api/v1/health/fitness`
 
+Use these exact health batch payload shapes when the user is creating or editing the stored records themselves:
+
+- create a manual sleep session:
+  `{"operations":[{"entityType":"sleep_session","data":{"startedAt":"2026-04-10T22:45:00.000Z","endedAt":"2026-04-11T06:45:00.000Z","qualitySummary":"Slept cleanly after a light evening.","links":[{"entityType":"habit","entityId":"habit_sleep_hygiene","relationshipType":"supports"}]}}]}`
+- update a sleep session through batch CRUD:
+  `{"operations":[{"entityType":"sleep_session","id":"sleep_123","patch":{"notes":"Woke once around 03:00 but settled quickly.","tags":["travel","recovered"]}}]}`
+- create a manual workout session:
+  `{"operations":[{"entityType":"workout_session","data":{"workoutType":"walk","startedAt":"2026-04-11T10:00:00.000Z","endedAt":"2026-04-11T10:45:00.000Z","subjectiveEffort":6,"meaningText":"Reset after a long planning block.","links":[{"entityType":"task","entityId":"task_123","relationshipType":"supports"}]}}]}`
+- update a workout session through batch CRUD:
+  `{"operations":[{"entityType":"workout_session","id":"workout_123","patch":{"moodAfter":"clear","tags":["zone2"]}}]}`
+
 Work-block payload guidance:
 
 - `kind` must be one of `main_activity`, `secondary_activity`, `third_activity`, `rest`, `holiday`, or `custom`
@@ -476,7 +488,8 @@ Additional first-class surfaces:
 
 - Use the high-level batch routes for basic Preferences CRUD. `preference_catalog`, `preference_catalog_item`, `preference_context`, and `preference_item` all go through `forge_create_entities`, `forge_update_entities`, and `forge_delete_entities`.
 - Use the high-level batch routes for basic questionnaire CRUD too. `questionnaire_instrument` goes through `forge_create_entities`, `forge_update_entities`, and `forge_delete_entities`.
+- Use the high-level batch routes for ordinary health-session CRUD too. `sleep_session` and `workout_session` go through `forge_search_entities`, `forge_create_entities`, `forge_update_entities`, and `forge_delete_entities` by default. Keep the dedicated health tools for review surfaces and reflective enrichment on one record.
 - Keep the dedicated Preferences tools only for real preference actions and read models: `forge_get_preferences_workspace`, `forge_start_preferences_game`, `forge_merge_preferences_contexts`, `forge_enqueue_preferences_item_from_entity`, `forge_submit_preferences_judgment`, `forge_submit_preferences_signal`, and `forge_update_preferences_score`.
 - Keep the dedicated questionnaire tools only for real flow actions and read models: `forge_list_questionnaires`, `forge_get_questionnaire`, `forge_clone_questionnaire`, `forge_ensure_questionnaire_draft`, `forge_publish_questionnaire_draft`, `forge_start_questionnaire_run`, `forge_get_questionnaire_run`, `forge_update_questionnaire_run`, and `forge_complete_questionnaire_run`.
 - Self-observation is note-backed. Read the calendar through `forge_get_self_observation_calendar`, but create or update the stored observation as a `note` tagged `Self-observation` with `frontmatter.observedAt` and links to the relevant `behavior_pattern`, `trigger_report`, or other Forge records.
-- `sleep_session` and `workout_session` are first-class health records. Review them through the dedicated health tools instead of treating them like loose notes.
+- `sleep_session` and `workout_session` are first-class health records. Treat them like ordinary stored entities for CRUD, and use the dedicated health tools for read models or post-review enrichment rather than pretending they live on a special mutation island.

package/skills/forge-openclaw/entity_conversation_playbooks.md

@@ -9,8 +9,12 @@ Forge correctly, and gather only the structure that still matters.
 
 - Lead with what the user is trying to preserve, change, resolve, or make true, not
   with the entity label.
+- Start by saying what seems to matter here or what the record is becoming, then ask
+  the next useful question.
 - Ask only for what is missing or still unclear.
 - Before every question, decide the one missing thing you are trying to clarify.
+- Ask first for the missing thing that would change the record shape, title, or next
+  action most, not just the easiest field to fill.
 - Know where the conversation is headed before you ask the next question.
 - Prefer one clean question to a stacked sentence with several asks.
 - Reflect briefly when the user gives meaning, ambivalence, or emotionally loaded
@@ -33,16 +37,24 @@ Forge correctly, and gather only the structure that still matters.
   task runs, use a fast path:
   one brief confirming sentence -> one operational question.
 - Do not read schema fields out loud unless the user explicitly wants a checklist.
+- One focused question is the default. Ask two only when both questions serve the same
+  job and the user is steady enough for it.
 - Do not ask the user to do naming work alone when the meaning is already clear. Offer
   a tentative title or formulation and invite correction.
 - When the meaning is clearer than the wording, offer a tentative title or summary
   yourself and ask whether it fits.
+- After each substantive answer, briefly say what is becoming clearer before you ask
+  for the next missing detail.
+- Let the user feel the direction of the intake. The next question should make sense
+  because of what just became clearer, not because a hidden checklist says it is next.
 - If the user already answered the usual opening question, do not repeat the stock
   opener. Move straight to the next missing clarification.
 - After a substantive answer, briefly say what is becoming clear so the user can
   correct the direction early.
 - Once the record is clear enough to name, stop exploring broadly and ask only for the
   last missing structural detail.
+- When the record is already clear enough to save, save it instead of performing a
+  ceremonial extra question.
 
 ## Conversation arc
 
@@ -79,6 +91,28 @@ Update record:
 
 - "Before I change it, what feels newly true now, and what should stay intact?"
 
+## Turn shapes
+
+Use these as small conversation molds when you need the next turn to feel guided
+rather than mechanical.
+
+Opening turn:
+
+- briefly reflect what seems to matter here
+- ask the one question that clarifies shape, stake, or outcome most
+
+Middle turn:
+
+- say what is becoming clearer
+- name the one thing that still needs to be known
+- ask only for that
+
+Closing turn:
+
+- offer the working title, summary, or record shape in plain language
+- ask whether it feels true enough to save or needs one correction
+- if the user says yes, move to the write instead of reopening the intake
+
 ## Steering moves
 
 Use these small moves to keep the intake natural and intentional.
@@ -107,12 +141,73 @@ When you are about to save:
 
 - give one short working summary in the user's language and ask whether it feels true
   enough or needs one correction
+- if the user confirms it, stop asking and save
 
 When an adjacent record becomes visible:
 
 - name it gently and ask whether it should be linked now, saved separately later, or
   left alone for now
 
+## Question Calibration Loop
+
+Use this quick internal check before every follow-up question.
+
+1. What is the one thing still unknown?
+2. Does that unknown affect the entity shape, the wording, the placement, or the
+   operational detail?
+3. What is the smallest question that would answer that unknown?
+4. If the user already gave enough to act, stop asking and move to a short summary or
+   the write.
+
+Useful calibration heuristics:
+
+- If the unknown changes whether this is a goal, project, task, note, or Psyche
+  record, ask that first.
+- If the shape is already clear but the wording is soft, offer a candidate title or
+  formulation rather than asking the user to invent one from scratch.
+- If the wording is clear but the placement is missing, ask only for the parent,
+  timing, owner, or linked context that will make the record usable later.
+- If the user is emotionally invested but the entity is not Psyche, reflect the stake
+  once and then return to the one missing structural detail.
+- If the next question would only decorate the record and not change its usefulness,
+  skip it.
+
+## Abstract And Reusable Record Moves
+
+Use this posture for tags, event types, emotion definitions, preference contexts,
+preference catalogs, preference items, questionnaire instruments, and similar
+reusable records.
+
+- Start from the future use, decision, or repeated moment the record should clarify,
+  not from the label alone.
+- Ask what distinction this record should help the user notice, compare, sort, or
+  retrieve later.
+- For collection records, ask what they are meant to help decide before you ask what
+  belongs inside them.
+- For vocabulary records, ask what counts as inside versus outside the term before you
+  settle the wording.
+- If the user already proposes a label, keep it provisional until the boundary and
+  future use are clear.
+- Once the distinction is clear, offer a candidate label yourself and invite
+  correction instead of making the user wordsmith alone.
+
+## Name, Define, Connect
+
+Once the core record is visible, use this short checkpoint.
+
+Name:
+
+- offer a working title or label if the user has the meaning but not the wording yet
+
+Define:
+
+- ask what belongs inside this record and what would make it stop being this record
+
+Connect:
+
+- ask about links only after the record itself feels named and defined enough to stay
+  stable
+
 ## Question design rules
 
 - Let each question have one job:
@@ -124,6 +219,8 @@ When an adjacent record becomes visible:
   or clarify the links.
 - Do not over-warm or over-therapize logistical records. For those flows, one brief
   confirming sentence plus one question is usually enough.
+- The first question should usually clarify lived meaning, use, stake, or timing, not
+  ask the user to invent a title from scratch.
 - Ask the more meaning-bearing question before the more administrative one.
 - Prefer "what", "when", and "how" before "why" when the user's meaning is still
   forming. "Why" is often better after the experience or outcome is already clear.
@@ -134,6 +231,8 @@ When an adjacent record becomes visible:
   figuring out what the thing is.
 - For labels such as `tag`, `event_type`, and `emotion_definition`, do not open with a
   naming question unless the meaning is already clear and only the wording is missing.
+- For reusable records, help the user define the boundary before you settle the final
+  label.
 - Before the final save question, it is often better to offer a candidate formulation
   than to ask for raw wording from scratch.
 - When useful, say what you think the record is becoming before asking the next
@@ -148,6 +247,8 @@ When an adjacent record becomes visible:
 - For collection-like records such as `preference_catalog` and
   `questionnaire_instrument`, ask what they are for before you ask what should go
   inside them.
+- After the user answers, prefer "what is becoming clearer is..." over a cold jump to
+  the next field.
 
 ## Ready-to-save check
 
@@ -165,6 +266,9 @@ Before the final write, it is usually worth asking one light confirmation such a
 - "That sounds like the right shape to save. Do you want to keep it that way, or is
   there one thing you want adjusted first?"
 
+If an adjacent goal, project, task, note, value, pattern, or tag became visible, ask
+about linking only after the main record already feels named and steady.
+
 ## Update loop
 
 Use this when the user is updating an existing record rather than creating a new one.
@@ -184,9 +288,10 @@ 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 if needed.
-4. Clarify horizon and status only after the meaning is clear.
+2. Reflect back the deeper stake in plain language before moving on.
+3. Ask why it matters now.
+4. Distinguish the goal from a project or task if needed.
+5. Clarify horizon and status only after the meaning is clear.
 
 Helpful follow-up lanes:
 
@@ -202,7 +307,7 @@ Ready to save when:
 
 Preferred opening question:
 
-- "What direction here feels important enough that you want to keep it in view?"
+- "What direction are you trying to keep hold of here?"
 
 ## Project
 
@@ -211,10 +316,11 @@ Aim: turn an intention into a bounded workstream with a clear outcome.
 Arc:
 
 1. Ask what this piece of work is trying to make true.
-2. Ask what outcome would make it feel real or complete for now.
-3. Ask which goal it belongs under.
-4. Land on a working name once the scope is clear.
-5. Clarify status, owner, and notes only after the scope is clear.
+2. Reflect the emerging boundary so the user can hear what is in scope.
+3. Ask what outcome would make it feel real or complete for now.
+4. Ask which goal it belongs under.
+5. Land on a working name once the scope is clear.
+6. Clarify status, owner, and notes only after the scope is clear.
 
 Helpful follow-up lanes:
 
@@ -230,7 +336,7 @@ Ready to save when:
 
 Preferred opening question:
 
-- "If this became a real project, what would you be trying to make true?"
+- "If this became a real project, what would you be trying to make true in your life or work?"
 
 ## Strategy
 
@@ -239,10 +345,11 @@ Aim: turn a vague plan into a deliberate sequence toward a real end state.
 Arc:
 
 1. Ask what future state the strategy is trying to make real.
-2. Ask which goals or projects are the true targets.
-3. Ask what the major steps or phases are.
-4. Ask about order, dependencies, and anything that must not be skipped.
-5. Clarify links or ownership once the sequence itself makes sense.
+2. Reflect the destination in plain language so the user can correct it early.
+3. Ask which goals or projects are the true targets.
+4. Ask what the major steps or phases are.
+5. Ask about order, dependencies, and anything that must not be skipped.
+6. Clarify links or ownership once the sequence itself makes sense.
 
 Helpful follow-up lanes:
 
@@ -259,7 +366,7 @@ Ready to save when:
 
 Preferred opening question:
 
-- "What future state is this strategy supposed to make real?"
+- "What future state are you actually trying to arrive at with this strategy?"
 
 ## Task
 
@@ -286,7 +393,7 @@ Ready to save when:
 
 Preferred opening question:
 
-- "What is the next concrete move you want to remember or do?"
+- "What is the next concrete move here?"
 
 ## Habit
 
@@ -315,7 +422,7 @@ Ready to save when:
 
 Preferred opening question:
 
-- "What recurring move are you trying to strengthen or loosen?"
+- "What recurring move are you trying to strengthen or interrupt?"
 
 ## Tag
 
@@ -362,6 +469,8 @@ Helpful follow-up lanes:
 - what the note is for later
 - what should stay linked
 - whether it is durable or should expire
+- whether part of the detail belongs in a note while the cleaner structure belongs on
+  another entity
 
 Ready to save when:
 
@@ -371,7 +480,36 @@ Ready to save when:
 
 Preferred opening question:
 
-- "What feels important enough here that you would want to be able to find it again later?"
+- "What about this feels worth preserving in a note?"
+
+## Wiki Page
+
+Aim: create a durable reference page with a clear scope instead of dumping raw notes
+into the wiki.
+
+Arc:
+
+1. Ask what topic this page should become the canonical place for.
+2. Ask whether it is a durable wiki page or supporting evidence.
+3. Ask what future lookup, decision, or collaboration this page should support.
+4. Ask about linked entities, aliases, or tags only if they will make the page more
+   navigable later.
+
+Helpful follow-up lanes:
+
+- what this page should be the home for
+- what should belong on the page versus remain linked evidence
+- who would open this page later and what they should quickly understand
+
+Ready to save when:
+
+- the page scope is clear
+- the page kind is clear enough
+- the title is stable enough to find later
+
+Preferred opening question:
+
+- "What should this page become the main reference for?"
 
 ## Insight
 
@@ -514,9 +652,10 @@ without pretending it is already a full interpretation.
 Arc:
 
 1. Ask what was observed.
-2. Ask when it happened or became noticeable.
-3. Ask what it may connect to: pattern, belief, value, mode, task, project, or note.
-4. Ask for tags or extra context only if that will help later review.
+2. Reflect the moment without pretending it is already a finished interpretation.
+3. Ask when it happened or became noticeable.
+4. Ask what it may connect to: pattern, belief, value, mode, task, project, or note.
+5. Ask for tags or extra context only if that will help later review.
 
 If the user already gave the moment or timing, move straight to what they noticed most
 clearly instead of re-asking when.
@@ -529,7 +668,7 @@ Ready to save when:
 
 Preferred opening question:
 
-- "What did you notice that feels worth capturing?"
+- "What did you notice most clearly in that moment?"
 
 ## Sleep Session
 
@@ -572,6 +711,36 @@ Preferred opening question:
 
 - "What about this workout feels most worth remembering or connecting?"
 
+## Calendar Connection
+
+Aim: connect the right provider deliberately without turning setup into a credential
+dump.
+
+Arc:
+
+1. Ask which provider the user wants to connect and what they want Forge to do with
+   it.
+2. Ask whether the goal is read-only visibility, writable planning, or both.
+3. Ask only for the next provider-specific step that still matters, such as auth flow,
+   label, or calendar selection.
+4. Move into the actual connection flow once the setup goal is clear.
+
+Helpful follow-up lanes:
+
+- what calendar workflow the user wants to unlock
+- whether writable projection matters
+- whether the provider requires a local sign-in step instead of manual fields
+
+Ready to act when:
+
+- the provider is clear
+- the intended sync behavior is clear enough
+- the next setup step is obvious
+
+Preferred opening question:
+
+- "Which calendar provider are you trying to connect, and what do you want Forge to do with it?"
+
 ## Preference Catalog
 
 Aim: define a useful comparison pool, not just a list with no decision purpose.
@@ -597,7 +766,7 @@ Ready to save when:
 
 Preferred opening question:
 
-- "What preference question do you want this catalog to help answer?"
+- "What decision or taste question should this catalog help with?"
 
 ## Preference Catalog Item
 
@@ -624,7 +793,7 @@ Ready to save when:
 
 Preferred opening question:
 
-- "What makes this item worth comparing in that catalog?"
+- "What makes this option meaningfully worth comparing?"
 
 ## Preference Context
 
@@ -633,9 +802,10 @@ Aim: define a real operating mode for preferences, not a decorative label.
 Arc:
 
 1. Ask what situation or mode this context is meant to represent.
-2. Ask what should count inside that context and what should stay outside it.
-3. Ask whether it should be active, default, or kept separate from other evidence.
-4. Offer a concise name if the mode is clearer than the wording.
+2. Ask what decisions or comparisons should feel different inside that context.
+3. Ask what should count inside that context and what should stay outside it.
+4. Ask whether it should be active, default, or kept separate from other evidence.
+5. Offer a concise name if the mode is clearer than the wording.
 
 Helpful follow-up lanes:
 
@@ -651,7 +821,7 @@ Ready to save when:
 
 Preferred opening question:
 
-- "What situation or mode should this context help Forge treat differently?"
+- "In what situation should Forge treat your preferences differently here?"
 
 ## Preference Item
 
@@ -695,9 +865,10 @@ Arc:
 
 1. Ask what the questionnaire is meant to measure or surface.
 2. Ask who it is for and when it should be used.
-3. Ask what kind of questions would make it honest and useful before getting into
-   item wording.
-4. Move to draft creation once the purpose is clear.
+3. Ask what kind of honest moment or decision it should help someone answer before
+   getting into item wording.
+4. Reflect the practical use case back in plain language.
+5. Move to draft creation once the purpose is clear.
 
 Ready to act when:
 
@@ -707,7 +878,7 @@ Ready to act when:
 
 Preferred opening question:
 
-- "What is this questionnaire meant to help surface or measure?"
+- "What would this questionnaire help someone notice or track?"
 
 ## Questionnaire Run
 
@@ -726,7 +897,7 @@ Ready to act when:
 
 Preferred opening question:
 
-- "Are you trying to start a questionnaire, continue one, or review a finished run?"
+- "Do you want to start, continue, review, or finish a questionnaire run?"
 
 ## Event Type
 
@@ -751,7 +922,7 @@ Ready to save when:
 
 Preferred opening question:
 
-- "What kind of moment do you want this event type to help you name more consistently?"
+- "What kind of moment keeps happening that you want future reports to name the same way each time?"
 
 ## Emotion Definition
 
@@ -763,6 +934,11 @@ Arc:
 2. Ask what distinguishes it from nearby emotions if that matters.
 3. Ask for a short description only if later reports would benefit from it.
 
+Helpful follow-up lanes:
+
+- what tells the user this is that feeling and not a nearby one
+- what kind of moments this emotion name should be used for later
+
 Ready to save when:
 
 - the label is clear
@@ -770,4 +946,4 @@ Ready to save when:
 
 Preferred opening question:
 
-- "When you say this feeling, what does it actually feel like for you?"
+- "When this feeling is present, what tells you it is this feeling and not a nearby one?"