projectionlab-mcp 1.1.0 → 1.2.0

package/dist/types/wire.js

@@ -7,7 +7,9 @@
  *
  * Transport: JSON text frames over ws://127.0.0.1:<port>. The browser side is
  * always the WebSocket client. The server accepts one active executor
- * connection at a time (newest wins).
+ * connection at a time. The incumbent keeps it: a second authenticated
+ * executor is refused with 4004 and retries until the incumbent goes away,
+ * unless it requests takeover or repeats the incumbent's instanceId.
  */
 /** Bumped on any breaking change to frame shapes or semantics. */
 export const PROTOCOL_VERSION = 1;
@@ -21,7 +23,9 @@ export const CLOSE_CODES = {
     AUTH_FAILED: 4001,
     /** Protocol version mismatch. */
     VERSION_MISMATCH: 4002,
-    /** A newer executor connected and replaced this one. */
+    /** A takeover replaced this executor; retry slowly, the next attempt normally gets BUSY. */
     REPLACED: 4003,
+    /** Another executor holds the connection; retry later. */
+    BUSY: 4004,
 };
 //# sourceMappingURL=wire.js.map

package/dist/types/wire.js.map

@@ -1 +1 @@
-{"version":3,"file":"wire.js","sourceRoot":"","sources":["../../src/types/wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,kEAAkE;AAClE,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAElC,kFAAkF;AAClF,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC;AAEpC,kFAAkF;AAClF,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAgF5C,gDAAgD;AAChD,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,8FAA8F;IAC9F,WAAW,EAAE,IAAI;IACjB,iCAAiC;IACjC,gBAAgB,EAAE,IAAI;IACtB,wDAAwD;IACxD,QAAQ,EAAE,IAAI;CACN,CAAC"}
+{"version":3,"file":"wire.js","sourceRoot":"","sources":["../../src/types/wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,kEAAkE;AAClE,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAElC,kFAAkF;AAClF,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC;AAEpC,kFAAkF;AAClF,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAqG5C,gDAAgD;AAChD,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,8FAA8F;IAC9F,WAAW,EAAE,IAAI;IACjB,iCAAiC;IACjC,gBAAgB,EAAE,IAAI;IACtB,4FAA4F;IAC5F,QAAQ,EAAE,IAAI;IACd,0DAA0D;IAC1D,IAAI,EAAE,IAAI;CACF,CAAC"}

package/dist/updateCheck.d.ts

@@ -0,0 +1,22 @@
+export type FetchLike = (url: string, init: {
+    headers: Record<string, string>;
+    signal: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    json(): Promise<unknown>;
+}>;
+/**
+ * Read the `version` field of the registry's latest-release document.
+ * Any failure (offline, timeout, non-200, bad JSON, missing or unparsable
+ * version) resolves to null; this never rejects.
+ */
+export declare function fetchLatestVersion(fetchImpl?: FetchLike, timeoutMs?: number): Promise<string | null>;
+export interface UpdateCheck {
+    /** Start the lookup; without PL_UPDATE_CHECK=false and at most once. */
+    start(fetchImpl?: FetchLike): void;
+    /** The latest version found, or null while unknown or disabled. */
+    latest(): string | null;
+}
+/** A fresh holder; the module-level one is what the server uses. */
+export declare function createUpdateCheck(): UpdateCheck;
+export declare const updateCheck: UpdateCheck;

package/dist/updateCheck.js

@@ -0,0 +1,58 @@
+// One request per server process asks the npm registry for the latest
+// published version of this package, so check_connection can tell the user
+// an update is available. The request carries no user data: no query string,
+// no custom headers beyond Accept, nothing from config or the plan.
+// PL_UPDATE_CHECK=false turns the lookup off entirely.
+import { config } from "./config.js";
+import { log } from "./logger.js";
+import { compareVersions } from "./versionCompare.js";
+import { VERSION } from "./version.js";
+const REGISTRY_URL = "https://registry.npmjs.org/projectionlab-mcp/latest";
+const DEFAULT_TIMEOUT_MS = 3000;
+/**
+ * Read the `version` field of the registry's latest-release document.
+ * Any failure (offline, timeout, non-200, bad JSON, missing or unparsable
+ * version) resolves to null; this never rejects.
+ */
+export async function fetchLatestVersion(fetchImpl = fetch, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    try {
+        const response = await fetchImpl(REGISTRY_URL, {
+            headers: { Accept: "application/json" },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok)
+            return null;
+        const body = (await response.json());
+        if (typeof body?.version !== "string")
+            return null;
+        // Unparsable versions are as good as unknown.
+        return compareVersions(body.version, "0.0.0") === null ? null : body.version;
+    }
+    catch (err) {
+        log.debug("updateCheck", `update lookup failed: ${err}`);
+        return null;
+    }
+}
+/** A fresh holder; the module-level one is what the server uses. */
+export function createUpdateCheck() {
+    let latest = null;
+    let started = false;
+    return {
+        start(fetchImpl = fetch) {
+            if (started || !config.updateCheck)
+                return;
+            started = true;
+            void fetchLatestVersion(fetchImpl).then((found) => {
+                latest = found;
+                if (found && compareVersions(found, VERSION) === 1) {
+                    log.info("updateCheck", `projectionlab-mcp ${found} is available (running ${VERSION})`);
+                }
+            });
+        },
+        latest() {
+            return latest;
+        },
+    };
+}
+export const updateCheck = createUpdateCheck();
+//# sourceMappingURL=updateCheck.js.map

package/dist/updateCheck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateCheck.js","sourceRoot":"","sources":["../src/updateCheck.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,2EAA2E;AAC3E,6EAA6E;AAC7E,oEAAoE;AACpE,uDAAuD;AAEvD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,MAAM,YAAY,GAAG,qDAAqD,CAAC;AAC3E,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAUhC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,YAAuB,KAA6B,EACpD,YAAoB,kBAAkB;IAEtC,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,YAAY,EAAE;YAC7C,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE;YACvC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC;SACvC,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QAC9B,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAA0B,CAAC;QAC9D,IAAI,OAAO,IAAI,EAAE,OAAO,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACnD,8CAA8C;QAC9C,OAAO,eAAe,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;IAC/E,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,KAAK,CAAC,aAAa,EAAE,yBAAyB,GAAG,EAAE,CAAC,CAAC;QACzD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AASD,oEAAoE;AACpE,MAAM,UAAU,iBAAiB;IAC/B,IAAI,MAAM,GAAkB,IAAI,CAAC;IACjC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,OAAO;QACL,KAAK,CAAC,YAAuB,KAA6B;YACxD,IAAI,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW;gBAAE,OAAO;YAC3C,OAAO,GAAG,IAAI,CAAC;YACf,KAAK,kBAAkB,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE;gBAChD,MAAM,GAAG,KAAK,CAAC;gBACf,IAAI,KAAK,IAAI,eAAe,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;oBACnD,GAAG,CAAC,IAAI,CACN,aAAa,EACb,qBAAqB,KAAK,0BAA0B,OAAO,GAAG,CAC/D,CAAC;gBACJ,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC;QACD,MAAM;YACJ,OAAO,MAAM,CAAC;QAChB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,WAAW,GAAG,iBAAiB,EAAE,CAAC"}

package/dist/versionCompare.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Compare two `major.minor.patch` versions numerically. Returns -1, 0, or 1,
+ * or null when either input is not three dot-separated non-negative integers.
+ */
+export declare function compareVersions(a: string, b: string): -1 | 0 | 1 | null;

package/dist/versionCompare.js

@@ -0,0 +1,33 @@
+// Release versions are major.minor.patch triples of non-negative integers.
+// Anything else (a leading v, prerelease or build suffixes, extra segments)
+// is unparsable, and callers treat unparsable as "say nothing".
+function parse(version) {
+    if (typeof version !== "string")
+        return null;
+    const parts = version.split(".");
+    if (parts.length !== 3)
+        return null;
+    const numbers = [];
+    for (const part of parts) {
+        if (!/^(0|[1-9]\d*)$/.test(part))
+            return null;
+        numbers.push(Number(part));
+    }
+    return [numbers[0], numbers[1], numbers[2]];
+}
+/**
+ * Compare two `major.minor.patch` versions numerically. Returns -1, 0, or 1,
+ * or null when either input is not three dot-separated non-negative integers.
+ */
+export function compareVersions(a, b) {
+    const left = parse(a);
+    const right = parse(b);
+    if (!left || !right)
+        return null;
+    for (let i = 0; i < 3; i++) {
+        if (left[i] !== right[i])
+            return left[i] < right[i] ? -1 : 1;
+    }
+    return 0;
+}
+//# sourceMappingURL=versionCompare.js.map

package/dist/versionCompare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versionCompare.js","sourceRoot":"","sources":["../src/versionCompare.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,4EAA4E;AAC5E,gEAAgE;AAEhE,SAAS,KAAK,CAAC,OAAe;IAC5B,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC7C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QAC9C,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,CAAS,EAAE,CAAS;IAClD,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACtB,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACvB,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACjC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/versionNotices.d.ts

@@ -0,0 +1,9 @@
+export interface VersionInfo {
+    /** The server's own release. */
+    server: string;
+    /** Connected executor, "extension/<v>" or "bootstrap/<v>", or null. */
+    executor: string | null;
+    /** Newest release on npm, or null when unknown or the check is off. */
+    latest: string | null;
+}
+export declare function versionNotices(info: VersionInfo): string[];

package/dist/versionNotices.js

@@ -0,0 +1,42 @@
+// Plain-language update notices for projectionlab_check_connection. Each
+// rule says nothing whenever a needed comparison is unparsable or a version
+// is unknown; being out of date is never reported as a connection failure.
+import { compareVersions } from "./versionCompare.js";
+const SERVER_FIX = "To update it, fully quit and reopen the AI assistant's host so npx fetches the new release; " +
+    "if the old version is still reported afterwards, set the server args in the host " +
+    "configuration to -y projectionlab-mcp@latest.";
+const EXTENSION_FIX = "To update it, download the zip for the browser from " +
+    "https://github.com/Backroads4Me/projectionlab-mcp/releases/latest, replace the unpacked " +
+    "extension folder with its contents, and reload the extension from the browser's extensions " +
+    "page. Settings are kept.";
+export function versionNotices(info) {
+    const notices = [];
+    const serverOutOfDate = info.latest !== null && compareVersions(info.latest, info.server) === 1;
+    if (serverOutOfDate) {
+        notices.push(`The ProjectionLab MCP server is running version ${info.server}, but version ` +
+            `${info.latest} is available on npm. ${SERVER_FIX}`);
+    }
+    if (info.executor) {
+        const slash = info.executor.lastIndexOf("/");
+        const kind = slash === -1 ? "" : info.executor.slice(0, slash);
+        const version = slash === -1 ? "" : info.executor.slice(slash + 1);
+        const cmp = compareVersions(version, info.server);
+        if (kind === "extension" && cmp === -1) {
+            notices.push(`The ProjectionLab browser extension is version ${version}, older than the server ` +
+                `(${info.server}). ${EXTENSION_FIX}`);
+        }
+        else if (kind === "extension" && cmp === 1 && !serverOutOfDate) {
+            // Only worth saying when npm has nothing newer to offer as well.
+            notices.push(`The ProjectionLab MCP server is version ${info.server}, older than the browser ` +
+                `extension (${version}). ${SERVER_FIX}`);
+        }
+        else if (kind === "bootstrap" && cmp !== null && cmp !== 0) {
+            notices.push(`The bootstrap snippet in the ProjectionLab tab is version ${version}, pasted from a ` +
+                `different server release than the running server (${info.server}). Ask the user to ` +
+                `reload the tab, then call projectionlab_get_bootstrap and paste the fresh snippet ` +
+                `into the browser console.`);
+        }
+    }
+    return notices;
+}
+//# sourceMappingURL=versionNotices.js.map

package/dist/versionNotices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versionNotices.js","sourceRoot":"","sources":["../src/versionNotices.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,4EAA4E;AAC5E,2EAA2E;AAE3E,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,MAAM,UAAU,GACd,8FAA8F;IAC9F,mFAAmF;IACnF,+CAA+C,CAAC;AAClD,MAAM,aAAa,GACjB,sDAAsD;IACtD,0FAA0F;IAC1F,6FAA6F;IAC7F,0BAA0B,CAAC;AAW7B,MAAM,UAAU,cAAc,CAAC,IAAiB;IAC9C,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,eAAe,GACnB,IAAI,CAAC,MAAM,KAAK,IAAI,IAAI,eAAe,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAE1E,IAAI,eAAe,EAAE,CAAC;QACpB,OAAO,CAAC,IAAI,CACV,mDAAmD,IAAI,CAAC,MAAM,gBAAgB;YAC5E,GAAG,IAAI,CAAC,MAAM,yBAAyB,UAAU,EAAE,CACtD,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAC7C,MAAM,IAAI,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QAC/D,MAAM,OAAO,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QACnE,MAAM,GAAG,GAAG,eAAe,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAClD,IAAI,IAAI,KAAK,WAAW,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;YACvC,OAAO,CAAC,IAAI,CACV,kDAAkD,OAAO,0BAA0B;gBACjF,IAAI,IAAI,CAAC,MAAM,MAAM,aAAa,EAAE,CACvC,CAAC;QACJ,CAAC;aAAM,IAAI,IAAI,KAAK,WAAW,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;YACjE,iEAAiE;YACjE,OAAO,CAAC,IAAI,CACV,2CAA2C,IAAI,CAAC,MAAM,2BAA2B;gBAC/E,cAAc,OAAO,MAAM,UAAU,EAAE,CAC1C,CAAC;QACJ,CAAC;aAAM,IAAI,IAAI,KAAK,WAAW,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC;YAC7D,OAAO,CAAC,IAAI,CACV,6DAA6D,OAAO,kBAAkB;gBACpF,qDAAqD,IAAI,CAAC,MAAM,qBAAqB;gBACrF,oFAAoF;gBACpF,2BAA2B,CAC9B,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectionlab-mcp",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "MCP server for ProjectionLab: read and safely edit your retirement plan from any MCP-compatible AI assistant",
   "type": "module",
   "license": "MIT",

package/skills/projectionlab/SKILL.md

@@ -21,9 +21,22 @@ also serves this guide as the MCP resource `projectionlab://guide`.
 ## Start every session with a connection check
 
 Call `projectionlab_check_connection` before any other ProjectionLab tool. It
-returns `browser`, `pageLoaded`, `apiAvailable`, `apiKeyValid`, `errors` and
-`writesEnabled`. When the first four flags are `true`, proceed. Otherwise fix
-the first failing item with the user, one step at a time, then check again.
+returns `browser`, `pageLoaded`, `apiAvailable`, `apiKeyValid`, `errors`,
+`writesEnabled`, `versions` and `notices`. When the first four flags are
+`true`, proceed. Otherwise fix the first failing item with the user, one step
+at a time, then check again.
+
+`notices` are plain sentences about releases, never connection failures. When
+the list is not empty, tell the user each one once, in plain words, then
+carry on; do not repeat them later in the session and do not refuse to work
+because of them. The two fixes: an out-of-date server is updated by fully
+quitting and reopening the AI assistant's host so `npx` fetches the new
+release (if it still reports the old version, set the server args to
+`["-y", "projectionlab-mcp@latest"]`); an out-of-date extension is updated by
+downloading the browser zip from
+`https://github.com/Backroads4Me/projectionlab-mcp/releases/latest`,
+replacing the unpacked extension folder with its contents, and reloading the
+extension from the browser's extensions page (settings are kept).
 
 | Failing item | What it means | What to do with the user |
 |---|---|---|
@@ -66,6 +79,11 @@ Recommended, persistent: the **MCP Bridge for ProjectionLab** browser extension.
    check.
 4. Open https://app.projectionlab.com and log in.
 
+If another browser is already connected to the server, the status reads
+**Standing by** instead: that extension connects on its own when the other
+browser disconnects, and pressing Save on the options page makes this
+browser the active one now.
+
 A Firefox user whose setup worked before only needs step 2 again after
 restarting Firefox: load `manifest.json` from the same folder, and re-enter
 the port and token if the options page is empty. Do not repeat the rest of
@@ -77,9 +95,12 @@ Console). It must be pasted again after every page reload.
 
 ## Reading the plan
 
-Plans are addressed by `planIdentifier`: a plan name (case-insensitive,
-partial match) or an exact plan ID. Prefer the narrowest read that answers the
-question.
+Plans are addressed by `planIdentifier`: a plan name (case-insensitive; a
+partial match must identify exactly one plan, and an ambiguous one is refused
+with the candidates listed) or an exact plan ID. The same rule covers
+`eventIdentifier` and the `planA`/`planB` names of `projectionlab_diff`, so a
+read and the following write can never target different items. Prefer the
+narrowest read that answers the question.
 
 | Question | Tool |
 |---|---|
@@ -150,8 +171,8 @@ question.
   what to use when the user wants to know whether two plans agree without sending
   their contents to the model.
 - Results over about 100,000 characters are written to
-  `~/.projectionlab-mcp/exports/` and returned as a file path. Read the parts
-  you need from the file.
+  `~/.projectionlab-mcp/exports/` and returned as a file path (pruned
+  automatically after 30 days). Read the parts you need from the file.
 - `projectionlab_describe_plugin_api` lists the Plugin API methods the running
   app exposes. Use it before concluding that a capability does not exist.
 
@@ -227,6 +248,9 @@ Change the plan only when the user explicitly asks for that change.
 - Never replace a whole section when a targeted tool can make the change.
   `projectionlab_update_plan_section` overwrites the complete array, so any
   event missing from what you send is gone.
+- Never write payloads carrying `[REDACTED]` under secret fields. Reads scrub
+  secrets with this placeholder, and write tools refuse payloads containing it
+  to prevent overwriting real credentials or keys with placeholder text.
 
 **Writes are off by default.** `writesEnabled` in the connection check shows
 the current mode. While it is `false`, every write tool, dry runs included,
@@ -276,12 +300,18 @@ values intact. Paths must already exist and keep their JSON type; get them from
 the matching read tool (`get_plan_settings`, `get_plan_section` with
 `listPaths: true`, or `get_current_finances` with `listPaths: true`). The
 older `patch` (events) and `data` (accounts) inputs merge top-level fields
-only; supply exactly one of the patch inputs.
+only; existing fields keep their JSON type and are validated like
+`pathChanges`, and new fields must be plain, non-secret names. Supply
+exactly one of the patch inputs.
 
 Milestones: ProjectionLab always keeps a Retirement and a Life Expectancy
 milestone and disables deleting them in the app, so never remove either one.
 `projectionlab_update_plan_section` replaces the whole `milestones` array, so
-send both of them back in it.
+send both of them back in it. Its `sectionData` must also match the section's
+current container shape - an array for milestones, an object with an `events`
+array for event sections, an object for `variables`, `montecarlo` and
+`withdrawalStrategy` - or it is refused with `INVALID_INPUT`, dry runs
+included.
 
 To explore a what-if without touching the original, clone the plan first and
 patch the copy.
@@ -294,6 +324,13 @@ refuses the last remaining plan. Its snapshot lets
 `projectionlab_restore_progress` and `projectionlab_restore_settings` replace
 an entire data area. Use them only when the user wants exactly that.
 
+Reads hide secret values: a secret-named field reads back as `[REDACTED]`. A
+`sectionData` or `restore_*` payload that still carries that sentinel under a
+secret-named key is refused with `INVALID_INPUT`, dry runs included, naming the
+paths. Type the real value or change single fields with
+`projectionlab_update_plan_event` or `projectionlab_update_plan_settings`,
+which patch by path and never round-trip hidden values.
+
 ### Change workflow
 
 Copy this checklist and work through it for each change:
@@ -365,8 +402,10 @@ Retire at 55 plan."
 2. `projectionlab_update_plan_event` with
    `{"planIdentifier": "Retire at 55", "section": "expenses", "eventIdentifier": "Groceries", "pathChanges": {"amount": 600}}`
    returns `dryRun: true`, the `planName`, `section`, the `event` label, and
-   `changes` such as `{"amount": {"before": 500, "after": 600}}`. Use
-   `pathChanges`, not `patch`, so sibling fields are kept. Show the before and
+   `changes` such as `{"amount": {"before": 500, "after": 600}}`; the `patch`
+   input reports the same before/after objects, and a field it adds reports
+   `"before": "[ABSENT]"`. Use `pathChanges`, not `patch`, so sibling fields
+   are kept. Show the before and
    after values to the user in plain words: "In Retire at 55, Groceries goes
    from $500 to $600 a month. Want me to make that change?"
 3. After the user approves, repeat the call with `"confirm": true`. The reply
@@ -448,9 +487,10 @@ at 60."
    and picks the same snapshot, so its field-level list of what differs from the
    live data shows exactly what that rollback would undo. Show it with the
    preview when the user asks what will come back.
-4. After the user approves, repeat with `{"nBack": 1, "confirm": true}`. A
-   confirmed rollback saves the current state first, so another `nBack: 1`
-   right after a rollback undoes that rollback.
+4. After the user approves, repeat with `{"nBack": 1, "confirm": true}`. The
+   reply reports `verified: true` (or lists `unverifiedSections` if the
+   re-read differed). A confirmed rollback saves the current state first, so
+   another `nBack: 1` right after a rollback undoes that rollback.
 5. `snapshotId` names one id from the list. `beforeTime` takes an ISO 8601
    time carrying a `Z` or `±HH:MM` offset, such as `2026-11-08T15:30:00Z`,
    and restores the latest snapshot strictly before it; a time with no