forge-openclaw-plugin 0.3.13 → 0.3.15

package/skills/forge-openclaw/SKILL.md.bak-20260415

@@ -1,552 +0,0 @@
----
-name: forge-openclaw
-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 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, questionnaire instrument, questionnaire run, self observation, 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, 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 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 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.
-
-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.
-- Before you ask, decide the exact missing thing you need and how that answer will help you name, place, or save the record.
-- Prefer a progression of:
-  concrete example or intent -> working name -> purpose or meaning -> placement in Forge -> operational details -> linked context.
-- Use those same playbooks for action-heavy non-Psyche flows such as `work_adjustment`, `preference_judgment`, `preference_signal`, and specialized `movement`, `life_force`, or `workbench` requests so the conversation starts from what the user is trying to understand, change, add, update, link, or run before you choose the route.
-- When the operation is not already explicit, identify the job first:
-  add, update, review, compare, navigate, link, or run. Skip that meta question
-  when the action is already obvious from the user's wording.
-- For emotionally meaningful non-Psyche records such as goals, habits, and notes, reflect the meaning before you ask for structure.
-- When the user is vague, ask for one small concrete example, stake, or desired outcome before you ask them to name the record.
-- When the user is clear, say what the record seems to be becoming and ask only for the last missing detail.
-- When the user wants to review, compare, inspect, or navigate an existing Forge
-  record, ask what they are trying to understand first and prefer the read path before
-  you reopen create or update intake.
-- 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:
-
-- 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
-
-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.
-- Sound professionally warm and therapist-like: grounded, accurate, reflective, and intentional, not clinical, vague, or lecture-like.
-- After the first real answer, choose one follow-up lane at a time: situation, sequence, meaning, protection, cost, longing/value, or tentative name.
-- For Psyche updates, start with what feels newly true, newly visible, or newly inaccurate, then ask what should stay true before changing the formulation.
-- 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.
-
-`goal` is a meaningful long-horizon direction or outcome. Use it for “be a great father”, “create meaningfully”, or “build a beautiful family”, not for one-off action items.
-
-`project` is a bounded workstream under a goal. Use it for “launch Forge plugin”, “plan summer move”, or “repair relationship with X”. Project lifecycle is status-driven: `active` means in play, `paused` means suspended, and `completed` means finished. Setting a project to `completed` auto-completes linked unfinished tasks through Forge's normal task-completion path.
-
-`task` is a concrete action item or deliverable. Use it for “draft the plugin README”, “call the landlord”, or “book therapy session”.
-
-`task_run` is one truthful live work session on a task. It is not the same thing as task status.
-
-`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.
-
-`work_block_template` is a recurring work-availability template such as Main Activity, Secondary Activity, Third Activity, Rest, Holiday, or Custom.
-
-`task_timebox` is a planned or live calendar slot attached to a task. It is scheduling structure, not proof that work actually started.
-
-`psyche_value` is a direction the user wants to live toward, such as honesty, courage, steadiness, compassion, or creativity.
-
-`behavior_pattern` is a recurring loop across situations. Think in terms of cue, emotion, thought, action, short-term payoff, long-term cost, and preferred replacement response.
-
-`behavior` is one recurring action tendency or move, such as withdrawing, appeasing, attacking, numbing out, or taking a regulating walk.
-
-`belief_entry` is one explicit belief sentence the user carries, such as “If I disappoint people, they will leave me.”
-
-`mode_profile` is one recurring state, voice, or inner role, such as inner critic, abandoned child, detached protector, overcontroller, or healthy adult.
-
-`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.
-
-`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.
-
-`emotion_definition` is a reusable emotion entry, such as fear, shame, anger, grief, relief, or disgust.
-
-Use this intake map when the user agrees to save or update something.
-
-`goal`
-Use for a meaningful direction over time.
-Minimum field: `title`
-Usually useful: `description`, `horizon`, `status`
-Ask:
-
-1. What should this goal be called?
-2. Why does it matter to you?
-3. Is this a quarter, year, or lifetime horizon?
-
-`project`
-Use for a bounded workstream under a goal.
-Minimum field: `title`
-Usually useful: `goalId`, `description`, `status`
-Ask:
-
-1. What should this project be called?
-2. Which goal does it support?
-3. What outcome should it produce?
-
-`task`
-Use for one concrete action or deliverable.
-Minimum field: `title`
-Usually useful: `projectId`, `goalId`, `priority`, `dueDate`, `status`, `owner`
-Ask:
-
-1. What is the task in one concrete sentence?
-2. Should it live under an existing goal or project?
-3. Does it need a due date, priority, or owner?
-
-`habit`
-Use for a recurring commitment or recurring slip with explicit cadence and XP consequences.
-Minimum field: `title`
-Usually useful: `polarity`, `frequency`
-CRITICAL NEGATIVE-HABIT CHECK-IN RULE:
-
-- For a `negative` habit, the correct check-in outcome is `missed`.
-- On a `negative` habit, `missed` means the habit was resisted, the user stayed aligned, and the habit earns its XP bonus.
-- Do not treat `missed` on a `negative` habit as failure. In this case, `missed` is the successful outcome.
-  Ask:
-
-1. What is the recurring behavior in one concrete sentence?
-2. Is doing it good (`positive`) or a slip (`negative`)?
-3. What cadence should it follow?
-
-`task_run`
-Use for live work happening now.
-Required fields to start: `taskId`, `actor`
-Ask only what is needed to start the run, such as the task, the actor, and whether the run is planned or unlimited.
-
-`psyche_value`
-Use for a value or committed direction.
-Minimum field: `title`
-Usually useful: `description`, `valuedDirection`, `whyItMatters`, links to goals, projects, or tasks
-Ask:
-
-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.
-Minimum field: `title`
-Usually useful: `description`, `targetBehavior`, `cueContexts`, `shortTermPayoff`, `longTermCost`, `preferredResponse`
-Ask:
-
-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.
-Minimum fields: `kind`, `title`
-Usually useful: `commonCues`, `urgeStory`, `shortTermPayoff`, `longTermCost`, `replacementMove`, `repairPlan`
-Ask:
-
-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.
-Minimum fields: `statement`, `beliefType`
-Usually useful: `confidence`, `evidenceFor`, `evidenceAgainst`, `flexibleAlternative`, `originNote`
-Ask:
-
-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 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.
-Minimum fields: `family`, `title`
-Usually useful: `fear`, `burden`, `protectiveJob`, `originContext`, links to patterns, behaviors, and values
-Ask:
-
-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`
-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.
-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, 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.
-Minimum field: `label`
-Usually useful: `description`
-Ask:
-
-1. What kind of repeated moment or incident do you want future reports to name the same way?
-2. What would count as inside this category, and what should stay outside it?
-3. If the meaning is clear but the wording is not, would you like me to suggest a concise label?
-
-`emotion_definition`
-Use for a reusable emotion vocabulary entry.
-Minimum field: `label`
-Usually useful: `description`, `category`
-Ask:
-
-1. When this feeling is present, what tells you it is this feeling and not a nearby one?
-2. What would you want a later trigger report to mean when it uses this label?
-3. If the felt meaning is clear but the wording is not, would you like me to suggest a concise label or broader category?
-
-Use these rules when choosing tools.
-
-Read first with `forge_get_operator_overview`, `forge_get_operator_context`, or `forge_get_current_work` unless the user is clearly asking for one exact known record or one exact write.
-
-Before creating or updating an ambiguous stored entity, use `forge_search_entities` to check for duplicates.
-
-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`
-
-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`
-
-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 the dedicated domain routes for specialized surfaces that are not simple batch entities:
-
-- Movement lives under `/api/v1/movement/*`. Treat it as a dedicated timeline of `stays` and `trips`, not as generic batch CRUD. A `stay` means the user remained in the same place for a span of time. A `trip` means the user traveled between places. Use the movement routes when the user wants to understand time in place, travel behavior, specific stays or trips, known places, or selected-span aggregates such as "how long was I at home in the past 2 weeks?" or "when did I travel last month?".
-- In the live onboarding catalog, Movement, Life Force, and Workbench should appear as `specialized_domain_surface`. If the classification and route family disagree, trust the specialized route family and fix the contract mismatch instead of inventing a batch CRUD path.
-- Movement user actions are: query movement behavior, add a place or manual stay/trip overlay, update an existing stay/trip/place, or link a specific movement item to another Forge entity. Keep the explanation user-facing: where they stayed, when they traveled, what changed, and what this movement should be linked to.
-- Movement read lanes map cleanly to the dedicated routes:
-  `/api/v1/movement/day`, `/api/v1/movement/month`, `/api/v1/movement/all-time`,
-  `/api/v1/movement/timeline`, `/api/v1/movement/places`,
-  `/api/v1/movement/selection`, and `/api/v1/movement/trips/:id`.
-- When the user is filling a missing-data gap, the default write path is a user-defined overlay box, not a raw stay or trip patch. Use `POST /api/v1/movement/user-boxes/preflight` if you need to confirm overlap or snap to the nearest missing interval, then `POST /api/v1/movement/user-boxes` with `kind: "stay"` or `kind: "trip"`.
-- When the user is repairing already-saved movement data, use the repair routes that match the saved object:
-  `PATCH /api/v1/movement/user-boxes/:id`,
-  `POST /api/v1/movement/automatic-boxes/:id/invalidate`,
-  `PATCH /api/v1/movement/stays/:id`,
-  `PATCH /api/v1/movement/trips/:id`, or
-  `PATCH /api/v1/movement/trips/:id/points/:pointId`.
-- Use `PATCH /api/v1/movement/stays/:id` or `PATCH /api/v1/movement/trips/:id` only when the user is editing an existing recorded stay or recorded trip. Do not use those routes to fill a missing span.
-- If the user says something as explicit as "that missing block was me staying home", do not reopen broad intake. Confirm the interval or place only if it is still ambiguous, then create the overlay and read the timeline back.
-- Life Force lives under `/api/v1/life-force*`. Use `GET /api/v1/life-force` for the current energy overview, `PATCH /api/v1/life-force/profile` for durable profile changes, `PUT /api/v1/life-force/templates/:weekday` for weekday curve edits, and `POST /api/v1/life-force/fatigue-signals` for real-time tired or recovered signals.
-- Workbench lives under `/api/v1/workbench/*`. Use those dedicated routes for flow catalog reads, flow CRUD, runs, published outputs, node results, and latest-node-output reads instead of trying to force Workbench through the batch entity routes.
-- Workbench lane hints:
-  use `/api/v1/workbench/flows` for flow catalog and CRUD,
-  `/api/v1/workbench/flows/:id/run` or `/api/v1/workbench/run` for execution,
-  `/api/v1/workbench/flows/:id/output` for published outputs, and the run/node routes
-  under `/api/v1/workbench/flows/:id` for run history and node-level inspection.
-- If you are unsure which specialized route family applies, check `forge_get_agent_onboarding` and use its `entityRouteModel.specializedDomainSurfaces` section before guessing.
-
-Use live work tools for `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_adjust_work_minutes` for `work_adjustment` when the user wants a truthful signed minute correction on an existing task or project rather than a fake live run or a retroactive new task.
-
-Use the dedicated Preferences action tools for `preference_judgment` and `preference_signal`:
-`forge_submit_preferences_judgment`, `forge_submit_preferences_signal`, `forge_update_preferences_score`
-
-Use `forge_post_insight` for `insight`.
-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`
-
-Do not say you lack a creation path when these tools cover the request. Do not open the Forge UI or a browser for normal creation or updates that the tools already support. Use `forge_get_ui_entrypoint` only when visual review, Kanban movement, graph exploration, or complex multi-record editing would genuinely be easier there.
-
-Use these exact payload expectations.
-
-`forge_search_entities` expects a top-level `searches` array.
-
-`forge_create_entities`, `forge_update_entities`, `forge_delete_entities`, and `forge_restore_entities` expect a top-level `operations` array.
-
-For create operations, each item must include `entityType` and `data`.
-
-Calendar entity CRUD uses these same batch tools:
-
-- create a native event with `forge_create_entities` and `entityType: "calendar_event"`
-- update or move an event with `forge_update_entities` and `entityType: "calendar_event"`
-- delete an event with `forge_delete_entities` and `entityType: "calendar_event"`
-- create, update, or delete recurring work blocks with `entityType: "work_block_template"`
-- create or update planned task slots with `entityType: "task_timebox"`
-
-Forge still runs the downstream calendar behavior after these generic mutations. For `calendar_event`, that includes provider projection sync on create or update and remote projection deletion on delete.
-Calendar date/time rule: when the user gives a local time such as “1pm”, interpret it in the user's timezone, not UTC. Set the payload `timezone` to the user's real timezone and serialize `startAt`, `endAt`, `startsAt`, and `endsAt` so they represent that local wall-clock time correctly. Do not silently treat unspecified local times as `UTC+0`.
-Calendar sync default: unless the user explicitly asks for Forge-only storage, do not set `preferredCalendarId` to `null`. Omit `preferredCalendarId` on event creation so Forge can use the default writable connected calendar automatically. Use `preferredCalendarId: null` only when the user clearly wants the event to stay Forge-only.
-
-When creating `goal`, `project`, or `task`, the create payload may also include `notes: [{ contentMarkdown, author?, tags?, destroyAt?, links? }]`. Forge will create real linked `note` entities automatically and attach them to the new parent record.
-
-To create a standalone note directly, use `forge_create_entities` with `entityType: "note"` and `data: { contentMarkdown, author?, tags?, destroyAt?, links }`. `links` should point at one or more real Forge entities so the note remains connected and searchable across the graph. Use `tags` for built-in memory-system labels or custom note labels. Use `destroyAt` only when the note should be ephemeral scratch memory that self-destructs later.
-
-For update operations, each item must include `entityType`, `id`, and `patch`.
-
-For project lifecycle changes, prefer generic updates:
-
-- suspend a project with `forge_update_entities` and `patch: { status: "paused" }`
-- finish a project with `forge_update_entities` and `patch: { status: "completed" }`
-- restart a project with `forge_update_entities` and `patch: { status: "active" }`
-- set project calendar defaults with `forge_update_entities` and `patch: { schedulingRules: ... }`
-- set task-specific scheduling with `forge_update_entities` and `patch: { schedulingRules: ..., plannedDurationSeconds: ... }`
-
-For delete operations, each item must include `entityType` and `id`. Delete is soft by default unless the user explicitly wants hard delete.
-
-For project deletion and recovery, prefer the generic delete and restore tools:
-
-- soft delete with `forge_delete_entities`
-- hard delete only when the user is explicitly asking for permanent removal, using `mode: "hard"`
-- restore with `forge_restore_entities`
-
-For restore operations, each item must include `entityType` and `id`.
-
-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.
-
-Use these live work rules.
-
-A `task_run` is the truthful way to represent live work. Do not pretend that changing task status is the same as starting or stopping a work session.
-
-Use `forge_start_task_run` to begin live work. Required fields: `taskId`, `actor`. If `timerMode` is `planned`, include `plannedDurationSeconds`. If `timerMode` is `unlimited`, omit `plannedDurationSeconds` or set it to null. If calendar rules currently block the task and the user still wants to proceed, include `overrideReason`.
-
-Use `forge_heartbeat_task_run` to keep an active run alive.
-
-Use `forge_focus_task_run` when one active run should become the current visible run.
-
-Use `forge_complete_task_run` to finish live work. When the user or agent wants to preserve what was done, include `closeoutNote` so Forge creates a real linked `note` instead of losing that explanation inside ephemeral run metadata. `closeoutNote` supports the same note fields as normal note creation, including `tags` and `destroyAt`.
-
-Use `forge_release_task_run` to stop live work without completing the task. `closeoutNote` is also available there for handoff or pause context, including note tags or an ephemeral destroy time when that handoff note should self-delete later.
-
-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 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
-- `forge_connect_calendar_provider` only when the operator explicitly wants a new Google, Apple, Exchange Online, or custom CalDAV connection and the discovery choices are already known
-- `forge_sync_calendar_connection` after a provider connection is created or when the calendar needs a fresh pull/push cycle
-- `forge_create_work_block_template` as a convenience helper for Main Activity, Secondary Activity, Third Activity, Rest, Holiday, or Custom recurring blocks
-- `forge_recommend_task_timeboxes` to find future slots that satisfy current rules when the user wants suggestions or when the agent needs help narrowing options
-- `forge_create_task_timebox` as the main direct route for manual timeboxing once the slot is known; use it after reasoning from the live calendar overview or after accepting a suggested slot
-
-Timebox planning rules for agents:
-
-- prefer manual timeboxing when the agent already has enough calendar context to choose the slot itself
-- use `forge_get_calendar_overview` first when the current day or week matters; reason over mirrored events, work blocks, existing timeboxes, and availability before placing the block
-- use `forge_create_task_timebox` directly for the manual path with explicit `startsAt` and `endsAt`
-- use `forge_recommend_task_timeboxes` only for the assisted path, then confirm one returned slot with `forge_create_task_timebox`
-- when manually timeboxing, keep the title specific and task-shaped, not generic
-- if the block needs a special Action Point profile, pass `activityPresetKey` and/or `customSustainRateApPerHour`
-- if the user wants a note about why this slot exists, pass `overrideReason`
-
-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 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`
-- `weekDays` uses Sunday=`0` through Saturday=`6`
-- `startMinute` and `endMinute` are minutes from midnight in the selected `timezone`
-- `startsOn` and `endsOn` are optional `YYYY-MM-DD` bounds on the recurring template
-- if `endsOn` is omitted or null, the block repeats indefinitely
-- holidays should usually use `kind: "holiday"`, `weekDays: [0,1,2,3,4,5,6]`, `startMinute: 0`, and `endMinute: 1440`
-- work blocks are compact recurring templates inside Forge, not repeated stored events for every day
-
-Provider-specific expectations:
-
-- Google and Apple plus writable custom CalDAV connections can mirror selected calendars and publish Forge-owned work blocks or timeboxes into a dedicated `Forge` calendar.
-- Exchange Online uses Microsoft Graph and is read-only in the current Forge implementation. It mirrors the selected calendars into Forge but does not publish work blocks, timeboxes, or native events back to Microsoft.
-- Exchange Online connection setup is guided and interactive. In normal self-hosted local use, the operator must first save the Microsoft client ID, tenant, and redirect URI in `Settings -> Calendar`, then continue through the popup sign-in flow backed by a local MSAL public-client configuration.
-- If an interactive Microsoft auth session has already been completed and the backend gave you an `authSessionId`, then `forge_connect_calendar_provider` accepts `provider: "microsoft"` with `label`, `authSessionId`, and `selectedCalendarUrls`.
-
-Use these exact calendar batch payload shapes when working generically:
-
-- create a native event:
-  `{"operations":[{"entityType":"calendar_event","data":{"title":"Weekly research supervision","startAt":"2026-04-06T06:00:00.000Z","endAt":"2026-04-06T07:00:00.000Z","timezone":"Europe/Zurich","links":[{"entityType":"project","entityId":"project_123","relationshipType":"meeting_for"}]}}]}`
-- update or move an event:
-  `{"operations":[{"entityType":"calendar_event","id":"calevent_123","patch":{"startAt":"2026-04-06T06:30:00.000Z","endAt":"2026-04-06T07:30:00.000Z","timezone":"Europe/Zurich","preferredCalendarId":"calendar_123"}}]}`
-- delete an event:
-  `{"operations":[{"entityType":"calendar_event","id":"calevent_123"}]}`
-- create a recurring work block:
-  `{"operations":[{"entityType":"work_block_template","data":{"title":"Main Activity","kind":"main_activity","color":"#f97316","timezone":"Europe/Zurich","weekDays":[1,2,3,4,5],"startMinute":480,"endMinute":720,"startsOn":"2026-04-06","endsOn":null,"blockingState":"blocked"}}]}`
-- create a holiday block:
-  `{"operations":[{"entityType":"work_block_template","data":{"title":"Summer holiday","kind":"holiday","color":"#14b8a6","timezone":"Europe/Zurich","weekDays":[0,1,2,3,4,5,6],"startMinute":0,"endMinute":1440,"startsOn":"2026-08-01","endsOn":"2026-08-16","blockingState":"blocked"}}]}`
-- 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"}}]}`
-
-Use these exact timebox helper payload shapes when the dedicated helper is simpler than batch CRUD:
-
-- create a manual task timebox directly:
-  `{"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":"manual","overrideReason":"Protected writing block before clinic.","activityPresetKey":"deep_work","customSustainRateApPerHour":6.5}`
-- create a suggested task timebox after reviewing recommendations:
-  `{"taskId":"task_123","projectId":"project_456","title":"Draft the methods section","startsAt":"2026-04-03T08:00:00.000Z","endsAt":"2026-04-03T09:30:00.000Z","source":"suggested"}`
-
-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.
-
-Good examples:
-“This is a `project` in Forge. Do you want to save it?”
-“This sounds like a `behavior_pattern`. Do you want to map it and save it?”
-“This is a `trigger_report`. Do you want to capture it in Forge?”
-
-Bad behavior:
-interrupting too early
-asking for every optional field
-using vague labels instead of the real entity name
-repeating the Forge prompt after the user has declined
-
-Treat Psyche as structured reflective work, not as casual metadata. When the user is distressed, prioritize support and clarity over structure. Only suggest storage when the user seems ready.
-
-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_update_sleep_session`
-`forge_update_workout_session`
-`forge_log_work`
-`forge_start_task_run`
-`forge_heartbeat_task_run`
-`forge_focus_task_run`
-`forge_complete_task_run`
-`forge_release_task_run`
-`forge_post_insight`
-`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`
-
-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. 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.