forge-openclaw-plugin 0.2.60 → 0.2.61

package/dist/server/server/src/services/gamification.js

@@ -1,10 +1,41 @@
 import { getDatabase } from "../db.js";
 import { enqueueGamificationCelebration, getGamificationEquipment, insertGamificationUnlock, listGamificationDailyActivity, listGamificationUnlocks, listUnseenGamificationCelebrations, replaceGamificationDailyActivity, upsertGamificationEquipment } from "../repositories/gamification.js";
-import { getDailyAmbientXp, listRewardRules } from "../repositories/rewards.js";
+import { getDailyAmbientXp, listRewardRules, recordEntityCreationReward } from "../repositories/rewards.js";
 import { getDefaultUser, listUsers, listUsersByIds } from "../repositories/users.js";
 import { GAMIFICATION_CATALOG, GAMIFICATION_STREAK_AWAY_DAY_KEYS, GAMIFICATION_STREAK_POWER_DAY_KEYS } from "../../../src/lib/gamification-catalog.js";
 import { achievementSignalSchema, gamificationCatalogPayloadSchema, gamificationProfileSchema, milestoneRewardSchema, rewardLedgerEventSchema } from "../types.js";
 const XP_CURVE_VERSION = "smith-forge";
+const ENTITY_CREATION_REWARD_SOURCES = [
+    { entityType: "goal", tableName: "goals", titleColumn: "title" },
+    { entityType: "project", tableName: "projects", titleColumn: "title" },
+    { entityType: "strategy", tableName: "strategies", titleColumn: "title" },
+    { entityType: "task", tableName: "tasks", titleColumn: "title" },
+    { entityType: "habit", tableName: "habits", titleColumn: "title" },
+    { entityType: "note", tableName: "notes", titleColumn: "content_plain" },
+    { entityType: "tag", tableName: "tags", titleColumn: "name" },
+    { entityType: "calendar_event", tableName: "calendar_events", titleColumn: "title" },
+    {
+        entityType: "work_block_template",
+        tableName: "work_block_templates",
+        titleColumn: "title"
+    },
+    { entityType: "task_timebox", tableName: "task_timeboxes", titleColumn: "title" },
+    {
+        entityType: "questionnaire_instrument",
+        tableName: "questionnaire_instruments",
+        titleColumn: "title"
+    },
+    { entityType: "psyche_value", tableName: "psyche_values", titleColumn: "title" },
+    {
+        entityType: "behavior_pattern",
+        tableName: "behavior_patterns",
+        titleColumn: "title"
+    },
+    { entityType: "behavior", tableName: "psyche_behaviors", titleColumn: "title" },
+    { entityType: "belief_entry", tableName: "belief_entries", titleColumn: "statement" },
+    { entityType: "mode_profile", tableName: "mode_profiles", titleColumn: "title" },
+    { entityType: "trigger_report", tableName: "trigger_reports", titleColumn: "title" }
+];
 function startOfWeek(date) {
     const clone = new Date(date);
     const day = clone.getDay();
@@ -209,6 +240,42 @@ function loadScopedRewardEvents(scope) {
         ? true
         : event.ownerUserId !== null && scopeUserIds.has(event.ownerUserId));
 }
+function syncEntityCreationRewards(scope) {
+    const database = getDatabase();
+    const scopeUserIds = [...new Set(scope.userIds)];
+    const scopePlaceholders = scopeUserIds.map(() => "?").join(", ");
+    for (const source of ENTITY_CREATION_REWARD_SOURCES) {
+        const scopedWhere = scopeUserIds.length > 0
+            ? `WHERE (
+             entity_owners.user_id IN (${scopePlaceholders})
+             OR (entity_owners.user_id IS NULL AND ? IS NOT NULL)
+           )`
+            : "";
+        const params = scopeUserIds.length > 0
+            ? [source.entityType, ...scopeUserIds, scopeUserIds[0] ?? null]
+            : [source.entityType];
+        const rows = database
+            .prepare(`SELECT
+           ${source.tableName}.id AS id,
+           ${source.tableName}.${source.titleColumn} AS title,
+           ${source.tableName}.created_at AS created_at
+         FROM ${source.tableName}
+         LEFT JOIN entity_owners
+           ON entity_owners.entity_type = ?
+          AND entity_owners.entity_id = ${source.tableName}.id
+         ${scopedWhere}`)
+            .all(...params);
+        for (const row of rows) {
+            recordEntityCreationReward({
+                entityType: source.entityType,
+                entityId: row.id,
+                title: row.title,
+                source: "system",
+                createdAt: row.created_at
+            });
+        }
+    }
+}
 function isQualifyingStreakReward(event) {
     return (event.deltaXp > 0 &&
         event.reversedByRewardId === null &&
@@ -245,8 +312,9 @@ function syncDailyActivity(userId, scopedRewards, timezone) {
 }
 function calculateStreakFromActivity(activeDateKeys, now, timezone) {
     const today = dateKeyInTimezone(now, timezone);
+    const yesterday = subtractDaysFromDateKey(today, 1);
     let streak = 0;
-    let cursor = today;
+    let cursor = activeDateKeys.has(today) ? today : yesterday;
     while (activeDateKeys.has(cursor)) {
         streak += 1;
         cursor = subtractDaysFromDateKey(cursor, 1);
@@ -297,8 +365,11 @@ function calculateMissedDays(activeDateKeys, now, timezone) {
     if (!latest || latest === today) {
         return { missedDays: 0, lastActiveDateKey: latest };
     }
+    if (latest === subtractDaysFromDateKey(today, 1)) {
+        return { missedDays: 0, lastActiveDateKey: latest };
+    }
     return {
-        missedDays: Math.max(0, daysBetweenDateKeys(latest, today)),
+        missedDays: Math.max(0, daysBetweenDateKeys(latest, today) - 1),
         lastActiveDateKey: latest
     };
 }
@@ -746,6 +817,7 @@ function syncCatalog(input) {
 function buildGamificationState(goals, tasks, habits, options = {}) {
     const now = options.now ?? new Date();
     const scope = resolveGamificationScope(options.userIds);
+    syncEntityCreationRewards(scope);
     const scopedRewards = loadScopedRewardEvents(scope);
     const timezone = resolveTimezone();
     const primaryUserId = scope.userIds[0] ?? "aggregate";

package/dist/server/src/lib/api.js

@@ -1515,6 +1515,15 @@ export function getOperatorOverview() {
 export function getSettings() {
     return request("/api/v1/settings");
 }
+export function getForgeDoctor() {
+    return request("/api/v1/doctor");
+}
+export function applyForgeDoctorFixes(input) {
+    return request("/api/v1/doctor/fixes", {
+        method: "POST",
+        body: JSON.stringify(input)
+    });
+}
 export function saveAiModelConnection(input) {
     return request("/api/v1/settings/models/connections", {
         method: "POST",

package/dist/server/src/lib/gamification-catalog.js

@@ -222,7 +222,7 @@ const PSYCHE_TROPHIES = [
     trophy("psyche", "Value Blade", allOf(metric("psycheValueCount", 10), metric("goalLinkedTaskCompletionCount", 100)), "Create 10 values and complete 100 goal-linked tasks.", "Values and work started cutting in the same direction."),
     trophy("psyche", "Shadow Temper", allOf(metric("modeProfileCount", 12), metric("triggerReportRichCount", 50)), "Create 12 modes and 50 rich trigger reports.", "Shadow material became usable steel."),
     trophy("psyche", "Inner Forge", allOf(metric("psycheValueCount", 12), metric("behaviorPatternCount", 25), metric("beliefFlexibleAlternativeCount", 30)), "Create 12 values, 25 patterns, and 30 flexible beliefs.", "A full inner forge takes shape."),
-    trophy("psyche", "Schema Bell", metric("questionnaireRunCount", 10), "Complete 10 questionnaire runs.", "Structured self-observation rang the bell repeatedly."),
+    trophy("psyche", "Schema Bell", metric("questionnaireRunCount", 40), "Complete 40 questionnaire runs.", "Structured self-observation rang the bell repeatedly."),
     trophy("psyche", "Mode Guide", metric("modeGuideSessionCount", 5), "Complete 5 mode guide sessions.", "Guided mode work became an actual practice."),
     trophy("psyche", "Repair Script", metric("behaviorCount", 10), "Create 10 Psyche behaviors.", "Behaviors now carry repair plans, not just names."),
     trophy("psyche", "Flexible Self", metric("beliefFlexibleAlternativeCount", 50), "Create 50 beliefs with flexible alternatives.", "A trophy for not letting old beliefs remain iron cages."),

package/openclaw.plugin.json

@@ -2,10 +2,92 @@
   "id": "forge-openclaw-plugin",
   "name": "Forge",
   "description": "Curated OpenClaw adapter for the Forge collaboration API, UI entrypoint, and localhost auto-start runtime.",
-  "version": "0.2.60",
+  "version": "0.2.61",
+  "activation": {
+    "onStartup": true,
+    "onCapabilities": [
+      "tool"
+    ],
+    "onCommands": [
+      "forge"
+    ]
+  },
   "skills": [
     "./skills"
   ],
+  "commandAliases": [
+    {
+      "name": "forge"
+    }
+  ],
+  "contracts": {
+    "tools": [
+      "forge_adjust_work_minutes",
+      "forge_apply_doctor_fix",
+      "forge_call_life_force_route",
+      "forge_call_movement_route",
+      "forge_call_workbench_route",
+      "forge_clone_questionnaire",
+      "forge_complete_questionnaire_run",
+      "forge_complete_task_run",
+      "forge_connect_calendar_provider",
+      "forge_create_entities",
+      "forge_create_task_timebox",
+      "forge_create_work_block_template",
+      "forge_delete_entities",
+      "forge_enqueue_preferences_item_from_entity",
+      "forge_ensure_questionnaire_draft",
+      "forge_focus_task_run",
+      "forge_get_agent_onboarding",
+      "forge_get_calendar_overview",
+      "forge_get_current_work",
+      "forge_get_doctor",
+      "forge_get_operator_context",
+      "forge_get_operator_overview",
+      "forge_get_preferences_workspace",
+      "forge_get_psyche_overview",
+      "forge_get_questionnaire",
+      "forge_get_questionnaire_run",
+      "forge_get_self_observation_calendar",
+      "forge_get_sleep_overview",
+      "forge_get_sports_overview",
+      "forge_get_ui_entrypoint",
+      "forge_get_user_directory",
+      "forge_get_weekly_review",
+      "forge_get_wiki_health",
+      "forge_get_wiki_page",
+      "forge_get_wiki_settings",
+      "forge_get_xp_metrics",
+      "forge_grant_reward_bonus",
+      "forge_heartbeat_task_run",
+      "forge_ingest_wiki_source",
+      "forge_list_questionnaires",
+      "forge_list_wiki_pages",
+      "forge_log_work",
+      "forge_merge_preferences_contexts",
+      "forge_post_insight",
+      "forge_publish_questionnaire_draft",
+      "forge_recommend_task_timeboxes",
+      "forge_reindex_wiki_embeddings",
+      "forge_release_task_run",
+      "forge_restore_entities",
+      "forge_search_entities",
+      "forge_search_wiki",
+      "forge_start_preferences_game",
+      "forge_start_questionnaire_run",
+      "forge_start_task_run",
+      "forge_submit_preferences_judgment",
+      "forge_submit_preferences_signal",
+      "forge_sync_calendar_connection",
+      "forge_sync_wiki_vault",
+      "forge_update_entities",
+      "forge_update_preferences_score",
+      "forge_update_questionnaire_run",
+      "forge_update_sleep_session",
+      "forge_update_workout_session",
+      "forge_upsert_wiki_page"
+    ]
+  },
   "uiHints": {
     "origin": {
       "label": "Forge Origin",
@@ -19,7 +101,7 @@
     },
     "dataRoot": {
       "label": "Forge Data Root",
-      "help": "Absolute folder path for the shared Forge home. Local installs default to ~/.forge so OpenClaw, Hermes, and Codex automatically meet in one runtime.",
+      "help": "Optional absolute folder path for Forge data. Defaults to ~/.forge. When set, Forge stores forge.sqlite directly in this folder; use the same value across adapters that should share one database.",
       "placeholder": "~/.forge",
       "advanced": true
     },
@@ -63,7 +145,7 @@
       "dataRoot": {
         "type": "string",
         "default": "~/.forge",
-        "description": "Absolute path for the shared Forge data root. Defaults to ~/.forge so local OpenClaw, Hermes, and Codex installs converge on one runtime."
+        "description": "Absolute path for the shared Forge data root. Defaults to ~/.forge. Explicit values override that default; use the same value across local adapters that should share one database."
       },
       "apiToken": {
         "type": "string",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-openclaw-plugin",
-  "version": "0.2.60",
+  "version": "0.2.61",
   "description": "Curated OpenClaw adapter for the Forge collaboration API, UI entrypoint, and localhost auto-start runtime.",
   "type": "module",
   "license": "MIT",
@@ -38,10 +38,13 @@
   "openclaw": {
     "extensions": [
       "./dist/openclaw/index.js"
-    ]
+    ],
+    "install": {
+      "minHostVersion": ">=2026.5.4"
+    }
   },
   "peerDependencies": {
-    "openclaw": "2026.4.15"
+    "openclaw": "2026.5.4"
   },
   "dependencies": {
     "@dnd-kit/core": "^6.3.1",
@@ -97,10 +100,11 @@
   "overrides": {
     "@aws-sdk/xml-builder": "^3.972.19",
     "basic-ftp": "^5.3.0",
-    "axios": "^1.15.0",
+    "axios": "^1.16.0",
     "fast-xml-parser": "^5.7.1",
     "follow-redirects": "^1.16.0",
     "hono": "4.12.14",
+    "ip-address": "^10.2.0",
     "uuid": "^14.0.0"
   },
   "scripts": {

package/server/migrations/059_data_backup_retention.sql

@@ -0,0 +1,2 @@
+ALTER TABLE data_management_settings
+ADD COLUMN backup_retention_days INTEGER DEFAULT 30;

package/skills/forge-openclaw/SKILL.md

@@ -87,6 +87,16 @@ guessing.
   `forge_call_life_force_route`, or `forge_call_workbench_route`, use those
   route-key tools after the conversation has selected the lane; otherwise use the
   exact `/api/v1/*` route or OpenClaw `/forge/v1/*` mirror published in onboarding.
+  Life Force may be keyed as `lifeForce` and as the entity-style alias `life_force`;
+  both point to the same `/api/v1/life-force/*` route family.
+- The specialized route-key tool schemas include the exact route-key to method/path
+  map. When a route key's exact path contains placeholders such as `:id`,
+  `:weekday`, `:runId`, or `:nodeId`, pass those values in `pathParams` using the
+  placeholder names exactly. Do not place IDs inside `routeKey`, invent a raw route
+  string, or ask the user to choose an endpoint when the lane already selects one. If
+  that schema and live onboarding disagree, trust the live onboarding for the current
+  call and treat the disagreement as a Forge contract bug to fix, not as a reason to
+  guess a nearby route.
 
 Preferences rule:
 
@@ -156,11 +166,15 @@ Entity conversation rule:
 
 Forge data location rule:
 
-- by default, current Forge plugins converge on the shared local Forge home at `~/.forge/forge.sqlite`
-- the exact storage root is the active runtime `dataRoot`; when `dataRoot` is set in plugin config, Forge stores `forge.sqlite` directly inside that folder
-- on repo-local development installs, keep using the configured shared `dataRoot` unless the user explicitly asks to move data
-- 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
+- never answer from a generic default. First check the actual configured `dataRoot` and, when possible, the live runtime file handle.
+- the default local Forge data root is `~/.forge`, so the default database is `~/.forge/forge.sqlite`.
+- the user can override that default. Determine the effective storage root from the active adapter config or runtime environment first: OpenClaw `plugins.entries["forge-openclaw-plugin"].config.dataRoot`, Hermes `~/.hermes/forge/config.json.dataRoot`, `FORGE_DATA_ROOT`, or the runtime's reported storage path.
+- when `dataRoot` is set, Forge stores `forge.sqlite` directly inside that folder. That explicit setting overrides generic defaults.
+- when a Forge server is running locally, verify the actual open database with a process/file-handle check such as `lsof -p <forge-pid> | rg 'forge.sqlite|forge.json'`.
+- treat plugin extension folders, package-local `data/`, or adapter-local data folders as only possible candidates until config or live process evidence proves they are active.
+- if the user wants to choose the data folder or configure backups from the UI, point them to Forge `Settings -> Data`. That page shows the live data folder, can move current data or adopt an existing Forge data folder, creates manual backups, enables recurring automatic backups, and lets the user choose how many days of automatic backups to keep.
+- before changing data roots, restoring, or merging data, create backups of every candidate Forge database plus OpenClaw/Hermes config files. Do not merge side databases unless an ID/content-level audit proves relevant user data is missing from the selected active database.
+- if the user asks where Forge data is stored, state both the configured path and the live verified database path, or say that the live path has not yet been verified.
 
 Psyche interview rule:
 
@@ -251,13 +265,16 @@ Use these exact entity meanings when deciding what the user is describing.
 
 `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.
+Minimum-field checkpoint, not a question script: use this only after the
+conversation has enough shape to save or update something. Do not ask every listed
+item. Choose the single missing lane that affects the write, and stop when the
+record is clear enough to persist.
 
 `goal`
 Use for a meaningful direction over time.
 Minimum field: `title`
 Usually useful: `description`, `horizon`, `status`
-Ask:
+Only ask if missing or unclear:
 
 1. What should this goal be called?
 2. Why does it matter to you?
@@ -267,7 +284,7 @@ Ask:
 Use for a bounded workstream under a goal.
 Minimum field: `title`
 Usually useful: `goalId`, `description`, `status`
-Ask:
+Only ask if missing or unclear:
 
 1. What should this project be called?
 2. Which goal does it support?
@@ -277,7 +294,7 @@ Ask:
 Use for one concrete action or deliverable.
 Minimum field: `title`
 Usually useful: `projectId`, `goalId`, `priority`, `dueDate`, `status`, `owner`
-Ask:
+Only ask if missing or unclear:
 
 1. What is the task in one concrete sentence?
 2. Should it live under an existing goal or project?
@@ -294,7 +311,7 @@ CRITICAL NEGATIVE-HABIT CHECK-IN RULE:
 - Do not treat `missed` on a `negative` habit as failure. In this case, `missed` is the successful outcome.
 - In OpenClaw, official habit outcome logging should go through `forge_update_entities` on `entityType: "habit"` with `patch: { checkIn: { status, dateKey?, note?, description? } }`.
 - Do not bypass the shared tool model with raw habit routes when the batch entity update already covers the write cleanly.
-  Ask:
+  Only ask if missing or unclear:
 
 1. What is the recurring behavior in one concrete sentence?
 2. Is doing it good (`positive`) or a slip (`negative`)?
@@ -309,7 +326,7 @@ Ask only what is needed to start the run, such as the task, the actor, and wheth
 Use for a value or committed direction.
 Minimum field: `title`
 Usually useful: `description`, `valuedDirection`, `whyItMatters`, links to goals, projects, or tasks
-Ask:
+Only ask if missing or unclear:
 
 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?
@@ -319,7 +336,7 @@ Ask:
 Use for a recurring loop across situations.
 Minimum field: `title`
 Usually useful: `description`, `targetBehavior`, `cueContexts`, `shortTermPayoff`, `longTermCost`, `preferredResponse`
-Ask:
+Only ask if missing or unclear:
 
 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?
@@ -329,7 +346,7 @@ Ask:
 Use for one recurring move or action tendency.
 Minimum fields: `kind`, `title`
 Usually useful: `commonCues`, `urgeStory`, `shortTermPayoff`, `longTermCost`, `replacementMove`, `repairPlan`
-Ask:
+Only ask if missing or unclear:
 
 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?
@@ -339,7 +356,7 @@ Ask:
 Use for one explicit belief sentence.
 Minimum fields: `statement`, `beliefType`
 Usually useful: `confidence`, `evidenceFor`, `evidenceAgainst`, `flexibleAlternative`, `originNote`
-Ask:
+Only ask if missing or unclear:
 
 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?
@@ -349,7 +366,7 @@ Ask:
 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:
+Only ask if missing or unclear:
 
 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`?
@@ -358,7 +375,7 @@ Ask:
 `mode_guide_session`
 Use for guided exploration before or alongside a durable mode profile.
 Minimum fields: `summary`, `answers`
-Ask:
+Only ask if missing or unclear:
 
 1. What just happened that brought this part online right now?
 2. If it had a voice, what would it say, fear, or need?
@@ -368,7 +385,7 @@ Ask:
 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:
+Only ask if missing or unclear:
 
 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?
@@ -378,7 +395,7 @@ Ask:
 Use for a reusable trigger category.
 Minimum field: `label`
 Usually useful: `description`
-Ask:
+Only ask if missing or unclear:
 
 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?
@@ -388,7 +405,7 @@ Ask:
 Use for a reusable emotion vocabulary entry.
 Minimum field: `label`
 Usually useful: `description`, `category`
-Ask:
+Only ask if missing or unclear:
 
 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?
@@ -628,6 +645,8 @@ 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_doctor`
+`forge_apply_doctor_fix`
 `forge_call_movement_route`
 `forge_call_life_force_route`
 `forge_call_workbench_route`

package/skills/forge-openclaw/entity_conversation_playbooks.md

@@ -18,6 +18,12 @@ Forge correctly, and gather only the structure that still matters.
 - The first question should usually clarify whether the user is trying to understand,
   preserve, decide, schedule, or change something, not just which field or provider
   they want.
+- Before asking, decide the API posture internally: shared batch entity route,
+  specialized CRUD surface, action workflow, or specialized domain route. If that
+  posture is unclear, ask the one user-facing question that will choose it.
+- Do not let API uncertainty leak out as vague wording. With the user, ask about the
+  real thing: the time window, flow, run, feeling, boundary, owner, or decision that
+  would change the action.
 - First identify the user's job when the lane is not already explicit:
   are they trying to add, update, review, compare, navigate, link, or run something?
 - Before every question, decide the one missing thing you are trying to clarify.
@@ -27,6 +33,9 @@ Forge correctly, and gather only the structure that still matters.
 - Prefer one clean question to a stacked sentence with several asks.
 - Reflect briefly when the user gives meaning, ambivalence, or emotionally loaded
   context that matters to the record.
+- Avoid generic reflections such as "that sounds important" unless you name what is
+  important in plain language. A useful reflection should make the next question feel
+  earned.
 - Especially for goals, habits, notes, and updates, reflect what the user is trying to
   preserve, change, or make true before you ask for structure.
 - For emotionally meaningful non-Psyche records such as goals, habits, notes, and many
@@ -200,6 +209,9 @@ Use this quick split before the conversation gets too detailed.
   `/api/v1/entities/search`, `/api/v1/entities/create`,
   `/api/v1/entities/update`, `/api/v1/entities/delete`, and
   `/api/v1/entities/restore`.
+- Every normal entity section below inherits that batch-route default unless its own
+  route note says otherwise. Do not invent one-off entity endpoints for ordinary
+  stored records.
 - `wiki_page` and `calendar_connection` are specialized CRUD areas. Use the wiki
   page routes and calendar connection setup or sync routes instead of pretending they
   are simple batch records.
@@ -216,6 +228,8 @@ Use this quick split before the conversation gets too detailed.
 - Once the route posture is clear, keep the questioning focused on the missing detail
   that selects the route or payload. Do not ask route-neutral reflective questions
   after the action path is already obvious.
+- If the tool schema and live onboarding disagree about a specialized route key or
+  path, treat that as a contract mismatch to fix. Do not guess a nearby route.
 
 ## Active-listening patterns
 
@@ -314,8 +328,8 @@ exists.
 - If the next answer would not change the route, wording, timing, links, or useful
   interpretation, stop asking and act.
 - Close cleanly:
-  once the user says the wording or route lands, summarize once and move to the read
-  or write.
+  once the user says the wording or next action lands, summarize once and move to the
+  read or write.
 
 When an adjacent record becomes visible:
 
@@ -344,8 +358,10 @@ 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
+3. Does it affect the API posture: batch CRUD, specialized CRUD, action workflow, or
+   specialized domain route?
+4. What is the smallest question that would answer that unknown?
+5. If the user already gave enough to act, stop asking and move to a short summary or
    the write.
 
 Useful calibration heuristics:
@@ -360,6 +376,8 @@ Useful calibration heuristics:
   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.
+- If the next question would not change the API path, payload, wording, timing, or
+  useful links, skip it.
 
 ## Abstract And Reusable Record Moves
 
@@ -777,6 +795,8 @@ Routing rule:
   book or article, keep a concept, or build a reusable explanation, consider
   `wiki_page` before `note`. Use `note` for temporary evidence, work logs, or linked
   detail; use `wiki_page` for durable memory.
+- Use the wiki tools and `/api/v1/wiki/pages` family for page reads and writes. Do
+  not route `wiki_page` through batch entity CRUD.
 
 Ready to save when:
 
@@ -922,6 +942,13 @@ Preferred opening question:
 
 - "Which task should I start?"
 
+Route note:
+
+- `task_run` is an action workflow. Start live work with `/api/v1/tasks/:id/runs`.
+  Use `/api/v1/task-runs/:id/heartbeat`, `/focus`, `/complete`, and `/release` for
+  the rest of the run lifecycle. Do not represent live work by only changing task
+  status.
+
 ## Work Adjustment
 
 Aim: correct tracked minutes truthfully without pretending a live run happened.
@@ -939,6 +966,12 @@ Helpful follow-up lanes:
 - whether the adjustment is positive or negative
 - what truthful reason should stay attached to the correction
 
+Route note:
+
+- `work_adjustment` is an action workflow. Use the dedicated work-adjustment tool or
+  `/api/v1/work-adjustments` path after the target and signed minute correction are
+  clear. Do not create a fake task run or invent a standalone batch CRUD entity.
+
 Ready to act when:
 
 - the target task or project is clear
@@ -987,7 +1020,8 @@ Route note:
 
 - `self_observation` is note-backed. Read the calendar first, then create or update an
   observed `note` with `frontmatter.observedAt` instead of inventing a standalone CRUD
-  write.
+  write. The read path is `/api/v1/psyche/self-observation/calendar`; the stored
+  write is a linked `note` through the shared batch entity route.
 - Do not promote self-observation over functional analysis. If the user is describing
   a loop, use `behavior_pattern`; if they are describing one emotionally meaningful
   episode, use `trigger_report`; if a part-state is central, use `mode_guide_session`
@@ -1076,13 +1110,29 @@ Arc:
    real use case.
 4. Ask only for the next provider-specific step that still matters, such as auth flow,
    label, or calendar selection.
-5. Move into the actual connection flow once the setup goal is clear.
+5. If the user is updating or removing an existing connection, ask which connection
+   and what exact lifecycle action they want before touching credentials or sync.
+6. 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
+- whether this is new setup, rediscovery, selected-calendar update, sync, or removal
+
+Route note:
+
+- `calendar_connection` is a specialized CRUD surface, not a batch CRUD entity.
+- Use `GET /api/v1/calendar/connections` to read existing connections.
+- Use `POST /api/v1/calendar/discovery` for Apple or custom CalDAV discovery and
+  `GET /api/v1/calendar/macos-local/discovery` for calendars already configured on
+  this Mac.
+- Use `GET /api/v1/calendar/connections/:id/discovery` before changing selected
+  calendars on an existing connection.
+- Use `POST /api/v1/calendar/connections`, `PATCH /api/v1/calendar/connections/:id`,
+  `POST /api/v1/calendar/connections/:id/sync`, or
+  `DELETE /api/v1/calendar/connections/:id` for the connection lifecycle.
 
 Ready to act when:
 
@@ -1301,6 +1351,9 @@ Lane-to-route map:
 
 Direct action rules:
 
+- In onboarding, this surface may be keyed as `lifeForce` and also as the entity-style
+  alias `life_force`. Treat both names as the same dedicated Life Force route family,
+  not as batch CRUD.
 - If the user is describing a durable baseline such as work capacity, recovery style,
   or action-point assumptions, patch the profile instead of logging a fatigue signal.
 - If the user is describing a repeatable weekday rhythm, update that weekday template
@@ -1566,7 +1619,9 @@ Route note:
 
 - `questionnaire_instrument` is normal stored CRUD for ordinary create, update,
   delete, and search work. Use clone, draft, and publish action routes only when the
-  user is working with instrument version state.
+  user is working with instrument version state. Questionnaire action paths live under
+  `/api/v1/psyche/questionnaires`, including `/:id/clone`, `/:id/draft`, and
+  `/:id/publish`.
 
 Ready to act when:
 
@@ -1599,7 +1654,10 @@ Helpful follow-up lanes:
 Route note:
 
 - `questionnaire_run` is an action workflow. Use the questionnaire run start, read,
-  update, and complete routes instead of treating answers as generic batch CRUD.
+  update, and complete routes instead of treating answers as generic batch CRUD:
+  `/api/v1/psyche/questionnaires/:id/runs`,
+  `/api/v1/psyche/questionnaire-runs/:id`, and
+  `/api/v1/psyche/questionnaire-runs/:id/complete`.
 
 Ready to act when: