forge-openclaw-plugin 0.2.49 → 0.2.51

package/dist/server/server/src/services/legacy-wiki-markdown-import.js

@@ -0,0 +1,328 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { cp, mkdir, readdir, readFile, rm } from "node:fs/promises";
+import path from "node:path";
+import { getDatabase, getEffectiveDataRoot } from "../db.js";
+import { getNoteById } from "../repositories/notes.js";
+import { syncNoteWikiArtifacts } from "../repositories/wiki-memory.js";
+const startupImportMarkerId = "runtime:legacy-wiki-markdown-import:v1";
+function parseFrontmatter(markdown) {
+    const normalized = markdown.replace(/\r\n/g, "\n");
+    const match = normalized.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    if (!match) {
+        return { frontmatter: {}, body: normalized };
+    }
+    const frontmatter = {};
+    for (const line of match[1].split("\n")) {
+        const separatorIndex = line.indexOf(":");
+        if (separatorIndex <= 0) {
+            throw new Error(`Malformed frontmatter line: ${line}`);
+        }
+        const key = line.slice(0, separatorIndex).trim();
+        const rawValue = line.slice(separatorIndex + 1).trim();
+        if (!key) {
+            throw new Error(`Malformed empty frontmatter key: ${line}`);
+        }
+        try {
+            frontmatter[key] = JSON.parse(rawValue);
+        }
+        catch {
+            frontmatter[key] = rawValue.replace(/^"(.*)"$/, "$1");
+        }
+    }
+    return { frontmatter, body: match[2] };
+}
+function slugify(value) {
+    const normalized = value
+        .toLowerCase()
+        .normalize("NFKD")
+        .replace(/[^\w\s-]/g, "")
+        .trim()
+        .replace(/[\s_]+/g, "-")
+        .replace(/-+/g, "-");
+    return normalized || "imported-page";
+}
+function stripMarkdown(markdown) {
+    return markdown
+        .replace(/```[\s\S]*?```/g, " ")
+        .replace(/`([^`]+)`/g, "$1")
+        .replace(/!\[[^\]]*\]\([^)]*\)/g, " ")
+        .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1")
+        .replace(/[#>*_\-~]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function inferTitle(markdown, fallback) {
+    const heading = markdown.match(/^#\s+(.+)$/m)?.[1]?.trim();
+    return heading || fallback.trim() || "Imported wiki page";
+}
+function inferSummary(markdown) {
+    return stripMarkdown(markdown).slice(0, 240);
+}
+function normalizeStringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((entry) => typeof entry === "string")
+        : [];
+}
+function normalizeLinkedEntities(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.flatMap((entry) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+            return [];
+        }
+        const record = entry;
+        if (typeof record.entityType !== "string" ||
+            typeof record.entityId !== "string") {
+            return [];
+        }
+        return [
+            {
+                entityType: record.entityType,
+                entityId: record.entityId,
+                anchorKey: typeof record.anchorKey === "string" ? record.anchorKey : ""
+            }
+        ];
+    });
+}
+async function walkMarkdownFiles(root) {
+    const results = [];
+    async function visit(directory) {
+        if (!existsSync(directory)) {
+            return;
+        }
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            const entryPath = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                await visit(entryPath);
+                continue;
+            }
+            if (entry.isFile() && entry.name.endsWith(".md")) {
+                results.push(entryPath);
+            }
+        }
+    }
+    await visit(root);
+    return results.sort();
+}
+function findSpaceForFile(dataRoot, filePath, parsed) {
+    const explicitSpaceId = typeof parsed.frontmatter.spaceId === "string"
+        ? parsed.frontmatter.spaceId
+        : "";
+    if (explicitSpaceId) {
+        const row = getDatabase()
+            .prepare("SELECT id FROM wiki_spaces WHERE id = ?")
+            .get(explicitSpaceId);
+        if (row) {
+            return row.id;
+        }
+    }
+    const relative = path.relative(path.join(dataRoot, "wiki"), filePath);
+    const parts = relative.split(path.sep);
+    if (parts[0] === "shared" && parts[1]) {
+        const row = getDatabase()
+            .prepare("SELECT id FROM wiki_spaces WHERE visibility = 'shared' AND slug = ?")
+            .get(parts[1]);
+        if (row) {
+            return row.id;
+        }
+    }
+    if (parts[0] === "users" && parts[1]) {
+        const row = getDatabase()
+            .prepare("SELECT id FROM wiki_spaces WHERE owner_user_id = ? OR slug = ?")
+            .get(parts[1], parts[1]);
+        if (row) {
+            return row.id;
+        }
+    }
+    return "wiki_space_shared";
+}
+function findExistingNote(input) {
+    if (input.id) {
+        const byId = getDatabase()
+            .prepare("SELECT id FROM notes WHERE id = ?")
+            .get(input.id);
+        if (byId) {
+            return byId.id;
+        }
+    }
+    const bySlug = getDatabase()
+        .prepare("SELECT id FROM notes WHERE space_id = ? AND slug = ?")
+        .get(input.spaceId, input.slug);
+    return bySlug?.id ?? null;
+}
+function upsertLinks(noteId, links) {
+    getDatabase().prepare("DELETE FROM note_links WHERE note_id = ?").run(noteId);
+    const createdAt = new Date().toISOString();
+    const statement = getDatabase().prepare(`INSERT OR IGNORE INTO note_links (note_id, entity_type, entity_id, anchor_key, created_at)
+     VALUES (?, ?, ?, ?, ?)`);
+    for (const link of links) {
+        statement.run(noteId, link.entityType, link.entityId, link.anchorKey, createdAt);
+    }
+}
+function legacyBackupPath(dataRoot, backupLabel) {
+    return path.join(dataRoot, "backups", backupLabel, "wiki");
+}
+async function backupWikiRootOnce(input) {
+    const backupPath = legacyBackupPath(input.dataRoot, input.backupLabel);
+    if (existsSync(backupPath)) {
+        return { backupPath, backedUp: false };
+    }
+    await mkdir(path.dirname(backupPath), { recursive: true });
+    await cp(input.wikiRoot, backupPath, { recursive: true, force: false });
+    return { backupPath, backedUp: true };
+}
+export async function importLegacyWikiMarkdownToSqlite(input = {}) {
+    const options = {
+        dataRoot: path.resolve(input.dataRoot ?? getEffectiveDataRoot()),
+        apply: input.apply ?? false,
+        deleteFiles: input.deleteFiles ?? false,
+        backupBeforeApply: input.backupBeforeApply ?? false,
+        backupLabel: input.backupLabel ?? "legacy-wiki-markdown-pre-sqlite-import"
+    };
+    const wikiRoot = path.join(options.dataRoot, "wiki");
+    const files = await walkMarkdownFiles(wikiRoot);
+    let scanned = 0;
+    let inserted = 0;
+    let updated = 0;
+    let deleted = 0;
+    let backupPath = legacyBackupPath(options.dataRoot, options.backupLabel);
+    let backedUp = false;
+    if (options.apply && options.backupBeforeApply && files.length > 0) {
+        const backup = await backupWikiRootOnce({
+            wikiRoot,
+            dataRoot: options.dataRoot,
+            backupLabel: options.backupLabel
+        });
+        backupPath = backup.backupPath;
+        backedUp = backup.backedUp;
+    }
+    for (const filePath of files) {
+        scanned += 1;
+        const parsed = parseFrontmatter(await readFile(filePath, "utf8"));
+        const kind = filePath.includes(`${path.sep}pages${path.sep}`)
+            ? "wiki"
+            : "evidence";
+        const spaceId = findSpaceForFile(options.dataRoot, filePath, parsed);
+        const markdown = parsed.body.trim();
+        const id = typeof parsed.frontmatter.id === "string" && parsed.frontmatter.id.trim()
+            ? parsed.frontmatter.id.trim()
+            : `note_${createHash("sha1").update(filePath).digest("hex").slice(0, 10)}`;
+        const title = typeof parsed.frontmatter.title === "string"
+            ? parsed.frontmatter.title
+            : inferTitle(markdown, path.basename(filePath, ".md"));
+        const slug = typeof parsed.frontmatter.slug === "string"
+            ? parsed.frontmatter.slug
+            : slugify(path.basename(filePath, ".md"));
+        const aliases = normalizeStringArray(parsed.frontmatter.aliases);
+        const tags = normalizeStringArray(parsed.frontmatter.tags);
+        const summary = typeof parsed.frontmatter.summary === "string"
+            ? parsed.frontmatter.summary
+            : inferSummary(markdown);
+        const contentPlain = stripMarkdown(markdown);
+        const links = normalizeLinkedEntities(parsed.frontmatter.linkedEntities);
+        const noteId = findExistingNote({ id, spaceId, slug });
+        const now = new Date().toISOString();
+        if (!options.apply) {
+            if (noteId) {
+                updated += 1;
+            }
+            else {
+                inserted += 1;
+            }
+            continue;
+        }
+        if (noteId) {
+            getDatabase()
+                .prepare(`UPDATE notes
+           SET kind = ?, title = ?, slug = ?, space_id = ?, parent_slug = ?, index_order = ?, show_in_index = ?,
+               aliases_json = ?, summary = ?, content_markdown = ?, content_plain = ?, tags_json = ?,
+               source_path = '', frontmatter_json = ?, updated_at = ?
+           WHERE id = ?`)
+                .run(kind, title, slug, spaceId, typeof parsed.frontmatter.parentSlug === "string"
+                ? parsed.frontmatter.parentSlug
+                : null, typeof parsed.frontmatter.indexOrder === "number"
+                ? Math.trunc(parsed.frontmatter.indexOrder)
+                : 0, parsed.frontmatter.showInIndex === false ? 0 : 1, JSON.stringify(aliases), summary, markdown, contentPlain, JSON.stringify(tags), JSON.stringify(parsed.frontmatter), now, noteId);
+            upsertLinks(noteId, links);
+            const note = getNoteById(noteId, { skipCleanup: true });
+            if (note) {
+                syncNoteWikiArtifacts(note);
+            }
+            updated += 1;
+        }
+        else {
+            getDatabase()
+                .prepare(`INSERT INTO notes (
+            id, kind, title, slug, space_id, parent_slug, index_order, show_in_index, aliases_json, summary,
+            content_markdown, content_plain, author, source, tags_json, destroy_at, source_path, frontmatter_json,
+            revision_hash, last_synced_at, created_at, updated_at
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, '', ?, '', NULL, ?, ?)`)
+                .run(id, kind, title, slug, spaceId, typeof parsed.frontmatter.parentSlug === "string"
+                ? parsed.frontmatter.parentSlug
+                : null, typeof parsed.frontmatter.indexOrder === "number"
+                ? Math.trunc(parsed.frontmatter.indexOrder)
+                : 0, parsed.frontmatter.showInIndex === false ? 0 : 1, JSON.stringify(aliases), summary, markdown, contentPlain, typeof parsed.frontmatter.author === "string"
+                ? parsed.frontmatter.author
+                : null, "system", JSON.stringify(tags), null, JSON.stringify(parsed.frontmatter), now, now);
+            upsertLinks(id, links);
+            const note = getNoteById(id, { skipCleanup: true });
+            if (note) {
+                syncNoteWikiArtifacts(note);
+            }
+            inserted += 1;
+        }
+        if (options.deleteFiles) {
+            await rm(filePath, { force: true });
+            deleted += 1;
+        }
+    }
+    return {
+        dataRoot: options.dataRoot,
+        scanned,
+        wouldApply: options.apply,
+        wouldDelete: options.deleteFiles,
+        inserted,
+        updated,
+        deleted,
+        backupPath,
+        backedUp,
+        skippedAlreadyImported: false
+    };
+}
+function hasStartupImportMarker() {
+    const row = getDatabase()
+        .prepare("SELECT id FROM migrations WHERE id = ?")
+        .get(startupImportMarkerId);
+    return Boolean(row);
+}
+function markStartupImportComplete() {
+    getDatabase()
+        .prepare("INSERT OR IGNORE INTO migrations (id, applied_at) VALUES (?, ?)")
+        .run(startupImportMarkerId, new Date().toISOString());
+}
+export async function importLegacyWikiMarkdownOnStartup(dataRoot = getEffectiveDataRoot()) {
+    if (hasStartupImportMarker()) {
+        return {
+            dataRoot: path.resolve(dataRoot),
+            scanned: 0,
+            wouldApply: true,
+            wouldDelete: false,
+            inserted: 0,
+            updated: 0,
+            deleted: 0,
+            backupPath: legacyBackupPath(path.resolve(dataRoot), "legacy-wiki-markdown-pre-sqlite-import"),
+            backedUp: false,
+            skippedAlreadyImported: true
+        };
+    }
+    const result = await importLegacyWikiMarkdownToSqlite({
+        dataRoot,
+        apply: true,
+        deleteFiles: false,
+        backupBeforeApply: true
+    });
+    markStartupImportComplete();
+    return result;
+}

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "forge-openclaw-plugin",
   "name": "Forge",
   "description": "Curated OpenClaw adapter for the Forge collaboration API, UI entrypoint, and localhost auto-start runtime.",
-  "version": "0.2.49",
+  "version": "0.2.51",
   "skills": [
     "./skills"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-openclaw-plugin",
-  "version": "0.2.49",
+  "version": "0.2.51",
   "description": "Curated OpenClaw adapter for the Forge collaboration API, UI entrypoint, and localhost auto-start runtime.",
   "type": "module",
   "license": "MIT",

package/server/migrations/019_wiki_memory.sql

@@ -57,7 +57,7 @@ VALUES (
   'wiki_space_shared',
   'shared',
   'Shared Forge Memory',
-  'Shared wiki space for file-backed Forge knowledge.',
+  'Shared wiki space for SQLite-backed Forge knowledge.',
   NULL,
   'shared',
   CURRENT_TIMESTAMP,

package/server/migrations/054_sqlite_backed_wiki_memory.sql

@@ -0,0 +1,8 @@
+UPDATE wiki_spaces
+SET description = 'Shared wiki space for SQLite-backed Forge knowledge.'
+WHERE id = 'wiki_space_shared'
+  AND description != 'Shared wiki space for SQLite-backed Forge knowledge.';
+
+UPDATE notes
+SET source_path = ''
+WHERE source_path != '';

package/skills/forge-openclaw/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: forge-openclaw
+name: forge-openclaw-plugin
 description: use when the user wants to save, search, update, review, start, stop, reward, explain, compare, or run Forge records, or when the conversation is clearly about a Forge entity 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.
 ---
 
@@ -59,7 +59,7 @@ PM surface rule:
   human/bot ownership filters.
 - Guided modal flows handle create, edit, move, link, and closeout actions.
 
-Forge has four major 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”.
+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 SQLite-backed Wiki memory layer with explicit spaces, Markdown content in database rows, backlinks, optional embeddings, and structured links back to Forge entities. Forge is also multi-user: every entity can belong to a typed `human` or `bot` user through `userId`, and read routes can scope to one or many users with `userId` or repeated `userIds`. The current access posture is configurable through a directional user graph, but the live default is still permissive: Forge can list users directly, every relationship edge starts open, and a user can read or affect another user's linked records when the route explicitly asks for them. Use `forge_get_user_directory` when owner identity or cross-user access matters. Strategies can also be locked into a contract with `isLocked`; once locked, do not mutate the graph or target structure unless the user explicitly wants the strategy unlocked first. The model should use the real entity names, not vague substitutes. Say `project`, not “initiative”. Say `behavior_pattern`, not “theme”. Say `trigger_report`, not “incident note”.
 Habits are a first-class recurring entity in the planning side.
 NEGATIVE HABIT CHECK-IN RULE: for a `negative` habit, the correct aligned/resisted outcome is `missed`. `missed` means the bad habit was resisted, the user stayed aligned, and the habit should award its XP bonus.
 
@@ -74,9 +74,9 @@ Preferences rule:
 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.
+- Use the wiki tools when the user wants SQLite-backed 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.
+- Keep evidence notes and wiki pages conceptually distinct: evidence notes are linked operating records, while wiki pages are curated long-form memory.
 
 Wiki navigation and search rule:
 
@@ -90,7 +90,7 @@ Wiki navigation and search rule:
 - 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.
+- Use `forge_get_wiki_settings` or `forge_get_wiki_health` when the task is about wiki maintenance, indexing, unresolved links, ingest setup, or memory integrity rather than content recall.
 
 Health rule:
 
@@ -353,7 +353,7 @@ Use the batch entity tools for stored records:
 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:
+Use the wiki tools for SQLite-backed memory work:
 `forge_get_wiki_settings`, `forge_list_wiki_pages`, `forge_get_wiki_page`, `forge_search_wiki`, `forge_upsert_wiki_page`, `forge_get_wiki_health`, `forge_sync_wiki_vault`, `forge_reindex_wiki_embeddings`, `forge_ingest_wiki_source`
 
 Use the health tools for review and reflective enrichment, not as the default CRUD architecture:

package/skills/forge-openclaw/entity_conversation_playbooks.md

@@ -63,6 +63,11 @@ Forge correctly, and gather only the structure that still matters.
   and then act.
 - Once the route family is clear, say it plainly enough that another agent could follow
   the same path without guessing.
+- For updates, start with the smallest thing that now feels wrong, newly true, or
+  newly visible. Do not make the user retell the whole record unless the change is
+  genuinely structural.
+- For review requests, ask what practical question they want the read to answer before
+  you ask for more scope.
 - For meaning-bearing updates, especially in Psyche-adjacent work, briefly say what
   feels newly true before you ask for the one structural detail that still changes the
   save.
@@ -222,6 +227,31 @@ When you are about to save:
   enough or needs one correction
 - if the user confirms it, stop asking and save
 
+## Update And Review Shortcuts
+
+Use these when the user is correcting, reviewing, or tightening something that already
+exists.
+
+- When the user already gave the correction in usable language, reflect what still
+  seems true, then ask only for the one thing that no longer fits.
+- A good narrow update line is:
+  "I can stay narrow here. What is the one thing that no longer fits?"
+- When the user is revising placement, timing, or ownership rather than meaning, do
+  not reopen the whole story. Confirm only the parent, interval, owner, or route scope
+  that changes the write.
+- When the record is abstract or reusable and the user wants an update, ask what
+  future decision, comparison, or retrieval moment got muddy with the old wording.
+- When the user wants review rather than mutation, ask what answer they need from the
+  read:
+  what this would help them decide later is often the clearest scope signal.
+- For specialized surfaces, ask what exact saved object, span, weekday, flow, run, or
+  node the user wants to check before you ask why it matters.
+- 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.
+
 When an adjacent record becomes visible:
 
 - name it gently and ask whether it should be linked now, saved separately later, or

package/skills/forge-openclaw/psyche_entity_playbooks.md

@@ -72,6 +72,10 @@ Forge without turning the conversation into a worksheet.
   container first and hold the others lightly until the user wants to map them.
 - When the user has said enough for an accurate working formulation, stop deepening and
   help them name it cleanly.
+- For Psyche updates, begin with the smallest part of the old wording that no longer
+  fits instead of reopening the whole formulation immediately.
+- Do not reopen the full origin story when the update is really about one changed
+  meaning, one newly visible protection, or one new sentence the user can already say.
 
 ## First reflection menu
 
@@ -193,6 +197,23 @@ opening:
 - one missing-detail question
 - then move toward the write instead of forcing exploration
 
+## Update micro-openers
+
+Use these when the user is revising an existing Psyche record and the tone should stay
+therapist-like without becoming expansive again.
+
+- "Something about the old wording no longer holds the whole experience. What felt
+  different in the moment that made that visible?"
+- "The old name was trying to protect something real. What part of the recent episode
+  made it feel too small or off?"
+- "It sounds like the same pain, but not quite the same meaning. What changed in what
+  it started to say?"
+- If the user already gave the new sentence in usable language, reflect it once, ask
+  what part of the old wording it replaces, and then save.
+- If the user wants review rather than storage, ask whether they need clearer
+  language, better understanding, or next-step help before you reopen the whole
+  formulation.
+
 ## Therapeutic turn shapes
 
 Keep the pacing human and intentional.