@manudota/artist-mcp 2.0.1-staging.94 → 2.1.0

package/agent-pack/.artist/policies/PATCH.md

@@ -1,9 +1,13 @@
 # Patch
 
 Once the musician has decided something, hand them the smallest fragment that
-records it, and say which part of the page it goes under. They paste it. The
-page is unchanged until they do, and nothing here can change it — so a patch is
-written as something to paste, never as something that has happened.
+records it, and say which part of the page it goes under.
+
+Usually they paste it, and the page is unchanged until they do. On the pages
+this tool made itself it can apply the fragment instead, having shown it and
+been told yes. Which of the two applies is decided in "Whose page is it" below,
+and it is the only thing about a patch that changed: everything else here was
+never a consequence of being unable to write.
 
 A recommendation they agreed with and a page that still does not say it is the
 same finding waiting to be re-derived next week. The page is the state. Ending
@@ -22,6 +26,13 @@ Offer once, alongside the answer, and do not ask again if they leave it. Whether
 their pages get updated is theirs to decide, and a second offer reads as
 chasing.
 
+Applying is not a lighter kind of offering. Show the change and wait for a yes
+in words, every time, exactly as creating a page and every calendar write does —
+an edit is smaller and that is not a reason to ask less. The confirmation the
+tool requires is a check that the values are the ones displayed; it cannot tell
+whether anybody read them. A patch they leave is left, and one they decline is
+not applied later because the conversation moved on.
+
 **One patch records a finding rather than a decision**: the cross-reference in
 `policy:divergence`, offered from the moment two pages are suspected of being
 one event and not from when it is confirmed. It is the exception because it
@@ -30,6 +41,28 @@ they later conclude. Everything above still applies to it. Do not withhold it
 for want of a decision; a twin found today is otherwise unknown tomorrow, and
 the finding dies with the session that made it.
 
+## Whose page is it
+
+An install granted `onenote-edit` can change **pages this tool created** and no
+others. Microsoft refuses the rest, so that is not a rule to keep — but it is
+also not a rule you can check, because **reading a page always works and only
+writing is refused.** A preview of an edit to the musician's own page will
+succeed, show a change and invite a yes, and the refusal lands afterwards.
+
+So offer to apply only where you can see the page is this tool's own:
+
+- **A page created in this conversation** — a consolidated page, a filled-out
+  template — may be offered as an applied change.
+- **Everywhere else, hand it over to be pasted.** Their pages, pages from
+  earlier sessions, pages you merely believe this tool made: a fragment, as
+  always. This is narrower than the tool permits, deliberately. A needless paste
+  costs a moment; an offer that fails after they have said yes costs their trust
+  in every offer after it.
+
+Never say which of the two it will be until you know. "I can update that for
+you" about a page you have not established is this tool's own is a promise made
+before the fact.
+
 ## The smallest fragment that records it
 
 A one-line decision is one line. Never restate the page around the change, and
@@ -93,8 +126,15 @@ decision next to it.
 
 ## Form
 
-A patch is handed over the way a template is: as a file, following Delivery and
-Shape in `policy:intake` rather than a second convention invented here.
+An applied patch has no file. The preview is its form: it shows the text that
+would be overwritten and the text replacing it, and that is what the musician
+approves. Do not also produce a file for it — a fragment to paste alongside a
+change already made is a second copy of the same decision, and the one they
+paste will duplicate it.
+
+A patch to be pasted is handed over the way a template is: as a file, following
+Delivery and Shape in `policy:intake` rather than a second convention invented
+here.
 Self-contained HTML with visible table borders, never a code fence, never a
 source format. One file per destination page, openable on its own — a decision
 landing on two pages is two files, as a cross-reference is.
@@ -137,13 +177,27 @@ page says nothing about any of this until they paste it.
 
 ## Boundaries
 
-- Never claim a page was changed. Not "added", not "updated", not "recorded on
-  the page" — it is offered, and it stays offered until they say otherwise.
+- Never claim a page was changed unless the tool reported changing it. A patch
+  offered, or previewed, or agreed to and not yet applied, is not a page that
+  says anything new.
+- Never call a change undoable. OneNote keeps no version of a page and a recycle
+  bin does not catch what this writes; what was overwritten is kept in this
+  install's own write log, which is a real recovery and not one the musician can
+  perform in OneNote. Say that, rather than "I can put it back".
 - Never track what was pasted or assume an earlier fragment landed. Nothing here
-  remembers, and a page that looks patched is a page you have re-read.
+  remembers, and a page that looks patched is a page you have re-read. This now
+  has a second reason: the ids that address a page's parts move every time it is
+  written to, so anything remembered about its structure is stale the moment it
+  changes.
 - Never patch two pages into agreement with each other. Where two records of one
   event conflict, `policy:divergence` governs, and a cross-reference is the only
   fragment offered before the fields are settled.
-- Never delete or replace what is on the page as part of a patch. Where a
-  decision contradicts a value already written, say both and let them choose
-  what to do with the old one.
+- Never delete anything. Not a page, not a section of one, and there is no tool
+  that can — a deleted page is not in the notebook's recycle bin.
+- Replace only text **this tool itself wrote**, and only where the musician has
+  now settled it differently — correcting a fee on a page it generated is the
+  case this exists for. A page it created is its own output right up until they
+  write on it, and their words are theirs wherever they put them.
+- Where a decision contradicts a value already on the page and that value is not
+  this tool's own text, say both and let them choose what to do with the old
+  one. Unchanged, and it is the common case.

package/agent-pack/registry.json

@@ -45,9 +45,9 @@
       "id": "policy:patch",
       "kind": "policy",
       "name": "Patch",
-      "description": "Once the musician has decided something, hand them the smallest fragment that records it, and say which part of the page it goes under. They paste it. The page is unchanged until they do, and nothing here can change it — so a patch is written as something to paste, never as something that has happened.",
+      "description": "Once the musician has decided something, hand them the smallest fragment that records it, and say which part of the page it goes under.",
       "file": ".artist/policies/PATCH.md",
-      "sha256": "b5da16f37d6210d93d323e181c08cf98b0bf4f3a0d9b77518bdf343296122b9f"
+      "sha256": "d844496f2720befd02efa0ae940355e569acf2467e18906bad7e0769350653e2"
     },
     {
       "id": "project-type:concert",

package/dist/api.d.ts

@@ -73,3 +73,40 @@ export declare const CALENDAR_LIST_NEED: ScopeNeed;
  * See docs/decisions/0003-onenote-writes.md.
  */
 export declare const onenoteCreatePage: (sectionId: string, xhtml: string, token: string) => Promise<Response>;
+/**
+ * Read a page back with the ids a patch can aim at.
+ *
+ * `includeIDs=true` is not optional and not a nicety: without it Graph returns
+ * only the `data-id` values the page was created with, and a replace requires
+ * the generated `id`. Microsoft warns those "might change after a page update",
+ * so this is called immediately before the command that uses what it returns —
+ * never once per session, and never carried across a write.
+ *
+ * The ETag comes back too, because it is the only thing that can tell us the
+ * page moved between the read and the write. Verified honoured: a stale
+ * `If-Match` is answered 412 rather than ignored.
+ */
+export declare const onenotePageContent: (pageId: string, token: string) => Promise<{
+    html: string;
+    etag: string | null;
+}>;
+/**
+ * Apply patch commands to one page.
+ *
+ * Narrow in the same way `onenoteCreatePage` is, and here the narrowness is
+ * load-bearing rather than defensive: this is the only function in the package
+ * that can destroy something a musician might want back. A general
+ * `graphPatch(path)` would make that reachable from anywhere.
+ *
+ * Not retried. A 5xx does not say whether the patch landed, and a repeated
+ * replace against an id read before the first attempt would aim at whatever
+ * that id points at now. Where a caller wants to try again it must read the
+ * page again first, which is the same rule the ids themselves impose.
+ *
+ * See docs/decisions/0004-onenote-page-maintenance.md.
+ */
+export declare const onenotePatchPage: (pageId: string, commands: readonly {
+    target: string;
+    action: string;
+    content: string;
+}[], token: string, etag: string | null) => Promise<void>;

package/dist/api.js

@@ -304,3 +304,86 @@ export const onenoteCreatePage = async (sectionId, xhtml, token) => {
     }
     throw new GraphError(`OneNote refused to create the page (${res.status}). ${detail}`, false);
 };
+/**
+ * Read a page back with the ids a patch can aim at.
+ *
+ * `includeIDs=true` is not optional and not a nicety: without it Graph returns
+ * only the `data-id` values the page was created with, and a replace requires
+ * the generated `id`. Microsoft warns those "might change after a page update",
+ * so this is called immediately before the command that uses what it returns —
+ * never once per session, and never carried across a write.
+ *
+ * The ETag comes back too, because it is the only thing that can tell us the
+ * page moved between the read and the write. Verified honoured: a stale
+ * `If-Match` is answered 412 rather than ignored.
+ */
+export const onenotePageContent = async (pageId, token) => {
+    // graphGet rather than a bare path: getWithRetry takes a whole URL, and the
+    // throttling and scope handling live in that wrapper.
+    const res = await graphGet(`/me/onenote/pages/${encodeURIComponent(pageId)}/content?includeIDs=true`, token);
+    return { html: await res.text(), etag: res.headers.get('etag') };
+};
+/**
+ * Apply patch commands to one page.
+ *
+ * Narrow in the same way `onenoteCreatePage` is, and here the narrowness is
+ * load-bearing rather than defensive: this is the only function in the package
+ * that can destroy something a musician might want back. A general
+ * `graphPatch(path)` would make that reachable from anywhere.
+ *
+ * Not retried. A 5xx does not say whether the patch landed, and a repeated
+ * replace against an id read before the first attempt would aim at whatever
+ * that id points at now. Where a caller wants to try again it must read the
+ * page again first, which is the same rule the ids themselves impose.
+ *
+ * See docs/decisions/0004-onenote-page-maintenance.md.
+ */
+export const onenotePatchPage = async (pageId, commands, token, etag) => {
+    const res = await fetch(`${GRAPH}/me/onenote/pages/${encodeURIComponent(pageId)}/content`, {
+        method: 'PATCH',
+        headers: {
+            authorization: `Bearer ${token}`,
+            'content-type': 'application/json',
+            ...(etag === null ? {} : { 'if-match': etag }),
+        },
+        body: JSON.stringify(commands),
+    });
+    if (res.status === 204)
+        return;
+    const detail = (await res.text().catch(() => '')).slice(0, 300);
+    // The page changed under us. Reported as what it is rather than retried: the
+    // musician typing in OneNote while this ran is the likeliest cause, and
+    // writing over that is the exact harm the header exists to prevent.
+    if (res.status === 412) {
+        throw new GraphError('That page changed while this change was being prepared, so nothing was ' +
+            'written — the edit would have overwritten whatever was just done to it. ' +
+            'Ask again to work from the current version of the page.', false);
+    }
+    // 40003 is a page the musician wrote; 40006 is a page another application
+    // created. Both are Microsoft refusing on ownership, which is the boundary
+    // this capability rests on, so neither is reported as a fault.
+    if ((res.status === 401 || res.status === 403) && /40003|40006/.test(detail)) {
+        throw new GraphError('That page was not created by artist-mcp, so it cannot be changed. This ' +
+            'tool can only edit its own pages — a page you wrote is refused by ' +
+            'Microsoft, not by this tool, and that is deliberate.', false);
+    }
+    if ((res.status === 401 || res.status === 403) && /40004|scope/i.test(detail)) {
+        throw new ScopeError('This Microsoft connection cannot edit OneNote pages. Reconnect with ' +
+            '`artist-mcp connect microsoft` — a refresh token carries the scopes it ' +
+            'was granted with, so an existing connection cannot edit until renewed.', 'edit OneNote pages', false);
+    }
+    // 20134 means the target did not resolve, which for a data-id is the missing
+    // '#' and for a generated id means it moved since the read. 20138 means the
+    // element resolved and does not support that action. They read alike and are
+    // not alike, so they are told apart here rather than in a log nobody reads.
+    if (/20134/.test(detail)) {
+        throw new GraphError('That part of the page could not be found, which usually means the page ' +
+            'changed since it was read. Nothing was written. Ask again to work from ' +
+            'the current version.', false);
+    }
+    if (/20138/.test(detail)) {
+        throw new GraphError('That part of the page cannot be changed in that way — OneNote does not ' +
+            'allow it for that kind of element. Nothing was written.', false);
+    }
+    throw new GraphError(`OneNote refused to change the page (${res.status}). ${detail}`, false);
+};

package/dist/audit.d.ts

@@ -42,6 +42,22 @@ export type WriteRecord = {
      * docs/decisions/0003-onenote-writes.md.
      */
     created_by_app_id?: string | null;
+    /**
+     * For a replaced OneNote element: exactly what was on the page beforehand.
+     *
+     * This is the undo, and there is no other one. OneNote keeps no version of a
+     * page and a Graph write leaves nothing in the recycle bin, so what stood
+     * where the change landed exists nowhere else the moment the PATCH returns
+     * 204. The audit line is not a note about the write here — it *is* the
+     * recovery, which is what the header of this file has always claimed the
+     * point of these records to be.
+     *
+     * Held as the element's HTML rather than its text, because restoring it means
+     * writing it back. It restores content and not bytes: OneNote rewrites the
+     * markup it stores, so a restored paragraph comes back carrying its words and
+     * not its original HTML. See docs/decisions/0004-onenote-page-maintenance.md.
+     */
+    pre_image?: string | null;
 };
 /**
  * Record a write that has already happened.

package/dist/connect.js

@@ -49,13 +49,28 @@ export const runConnect = async (input) => {
     else {
         // Named, because the consent screen the user just approved was wider than
         // the one every other install sees, and they should be able to tell why.
+        // What Microsoft consent covered depends on which OneNote grants are held,
+        // and the difference is exactly the thing a user would want to know. This
+        // said unconditionally that no page could be changed "including the ones it
+        // creates — the permission it holds cannot express that", which was true of
+        // `Notes.Create` alone and becomes a false reassurance the moment
+        // `onenote-edit` is granted. A sentence that is wrong only for the widest
+        // install is the worst possible place to be wrong.
+        const canEdit = relevant.includes('onenote-edit');
+        const microsoft = canEdit
+            ? 'creating OneNote pages and changing the ones it created. It cannot ' +
+                'touch a page you wrote or one another app created — Microsoft refuses ' +
+                'those — and it cannot delete anything. A change it makes to its own ' +
+                'page overwrites what was there, and OneNote keeps no version, so what ' +
+                'it replaced is kept only in this install\'s write log.'
+            : 'creating OneNote pages. No page can be changed or deleted by this ' +
+                'tool, including the ones it creates — the permission it holds cannot ' +
+                'express that.';
         console.log(`This install was granted ${relevant.join(', ')}, so consent included ` +
-            `${provider === 'microsoft' ? 'creating OneNote pages' : 'creating calendar events'}. ` +
             (provider === 'microsoft'
-                ? 'No page can be changed or deleted by this tool, including the ones ' +
-                    'it creates — the permission it holds cannot express that.'
-                : 'Nothing else is ever written back: not mail, and no event is ' +
-                    'changed except by the reschedule you granted.'));
+                ? microsoft
+                : 'creating calendar events. Nothing else is ever written back: not ' +
+                    'mail, and no event is changed except by the reschedule you granted.'));
     }
     // Said at the one moment the user is certainly reading, which is the whole
     // point: #94 describes a connection that dies weekly, an error that correctly

package/dist/dispatch.d.ts

@@ -110,6 +110,14 @@ export declare const OPERATIONS: {
         readonly provider: "microsoft";
         readonly effect: "write";
     };
+    readonly preview_onenote_edit: {
+        readonly provider: "microsoft";
+        readonly effect: "read";
+    };
+    readonly edit_onenote_page: {
+        readonly provider: "microsoft";
+        readonly effect: "write";
+    };
 };
 export type Operation = keyof typeof OPERATIONS;
 /**

package/dist/dispatch.js

@@ -17,6 +17,7 @@ import { oneNoteLoader } from './page-attachments.js';
 import { createEvent, deleteEvent, listCalendars, listEvents, previewDeleteEvent, previewEvent, previewRescheduleEvent, readEvent, rescheduleEvent, } from './calendar.js';
 import { listEmails, readEmail } from './mail.js';
 import { listNotes, mapNotes, readNote } from './notes.js';
+import { applyEdit, previewEdit } from './onenote-patch.js';
 import { createPage, previewPage } from './onenote-write.js';
 import { accessTokenFor } from './oauth.js';
 import { loadTokens } from './tokens.js';
@@ -78,6 +79,16 @@ export const OPERATIONS = {
     // `Notes.Create` cannot express an edit or a delete, so there is no sibling
     // row here to refuse. See docs/decisions/0003-onenote-writes.md.
     create_onenote_page: { provider: 'microsoft', effect: 'write' },
+    // Reads the page and shows the change against what is actually written there
+    // now. A read, and necessarily so: it is what has to happen before a write is
+    // allowed, and gating it would gate the safeguard rather than the danger.
+    preview_onenote_edit: { provider: 'microsoft', effect: 'read' },
+    // The first row here that can destroy something. Both actions ride one row
+    // and one grant because no scope separates them, so the distinction is made
+    // where it can be enforced — in the operation itself, where a replace cannot
+    // proceed unless what it would overwrite has been captured first.
+    // See docs/decisions/0004-onenote-page-maintenance.md.
+    edit_onenote_page: { provider: 'microsoft', effect: 'write' },
 };
 /** Kept as its own export: callers ask "which token" far more than "which effect". */
 const PROVIDER_FOR = Object.fromEntries(Object.entries(OPERATIONS).map(([op, meta]) => [op, meta.provider]));
@@ -140,6 +151,10 @@ export const dispatchWith = (resolve, record = recordWrite) => async (op, params
             return (await previewPage(token, params));
         case 'create_onenote_page':
             return (await createPage(token, params, record));
+        case 'preview_onenote_edit':
+            return (await previewEdit(token, params));
+        case 'edit_onenote_page':
+            return (await applyEdit(token, params, record));
         case 'list_calendars':
             // No parameters by design: the whole value is knowing the full set, and
             // a filtered list of what exists is the reach problem again.

package/dist/grants.d.ts

@@ -31,6 +31,7 @@ export declare const WRITE_CAPABILITIES: {
     readonly 'calendar-create': "add a single event to a Google Calendar, after showing it to you first";
     readonly 'calendar-delete': string;
     readonly 'onenote-create': string;
+    readonly 'onenote-edit': string;
 };
 export type WriteCapability = keyof typeof WRITE_CAPABILITIES;
 /** Whether a bare token names a capability, for untangling mangled arguments. */

package/dist/grants.js

@@ -39,6 +39,19 @@ export const WRITE_CAPABILITIES = {
     // See docs/decisions/0003-onenote-writes.md.
     'onenote-create': 'add a new page to a OneNote section, after showing it to you first. ' +
         'It cannot change or delete any page, including the ones it made.',
+    // Also not this file's boundary to keep, and for a stronger reason than
+    // `onenote-create`: `Notes.ReadWrite.CreatedByApp` distinguishes *this* app
+    // from every other, so a page the musician wrote is refused by Microsoft
+    // before our code is reached — verified as 401 40003, not assumed.
+    //
+    // One capability covering both actions rather than two. No scope separates
+    // appending from replacing, so a second grant would be a promise this
+    // repository keeps while reading like the provider-enforced kind, which is
+    // the confusion 0003 exists to prevent. What makes a replace survivable is
+    // the pre-image, not the name it was granted under.
+    // See docs/decisions/0004-onenote-page-maintenance.md.
+    'onenote-edit': 'change a page that artist-mcp itself created, after showing it to you first. ' +
+        'It cannot touch a page you wrote, and it cannot delete anything.',
 };
 /** Whether a bare token names a capability, for untangling mangled arguments. */
 export const isWriteCapability = (value) => typeof value === 'string' && Object.keys(WRITE_CAPABILITIES).includes(value);

package/dist/oauth.js

@@ -157,6 +157,18 @@ export const WRITE_SCOPES = {
     // Microsoft. Asking for `Notes.ReadWrite` instead would hand back exactly
     // the position 0001 was stuck in. See docs/decisions/0003-onenote-writes.md.
     'onenote-create': { provider: 'microsoft', scopes: ['Notes.Create'] },
+    // Named in the body of Microsoft's own 403 for PATCH and DELETE, and absent
+    // from the documentation for the operations it enables — the permissions
+    // table for page-delete lists only Notes.ReadWrite and Notes.ReadWrite.All,
+    // and says higher privileges are "not available" for a personal account,
+    // while a personal account edits with this one. Treat that reference as
+    // describing intent and probe for behaviour; scripts/spike-onenote-patch.mjs
+    // is that probe.
+    //
+    // Enforced per-app, not per-scope-holder: a page another application created
+    // is refused with 403 40006, and one the musician wrote with 401 40003.
+    // Consent for it folds in Notes.Create unasked, observed on every run.
+    'onenote-edit': { provider: 'microsoft', scopes: ['Notes.ReadWrite.CreatedByApp'] },
 };
 /**
  * What to ask consent for, given what this install was granted.

package/dist/onenote-patch.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Editing a page this tool created, and only such a page.
+ *
+ * Like `onenote-write.ts`, there is no ownership boundary in this file, and for
+ * the same reason: `Notes.ReadWrite.CreatedByApp` refuses a page the musician
+ * wrote before our code is consulted — verified as `401 40003` against a real
+ * notebook. What *is* here is the machinery that makes a replace permissible at
+ * all, which is a different question and ours to get right. See
+ * docs/decisions/0004-onenote-page-maintenance.md.
+ *
+ * The rule that record rests on: **a replace may not proceed unless the content
+ * it is about to destroy has been captured first.** OneNote keeps no version and
+ * no recycle bin, so the pre-image is the only undo that exists. It is not a
+ * feature attached to replacing; it is the reason replacing is allowed.
+ *
+ * Three facts about Graph's patch API are encoded below rather than remembered,
+ * because two probe runs concluded the opposite of the truth from them:
+ *
+ *   1. A `data-id` target must carry a `#`. Without it the target does not
+ *      resolve and Graph answers `20134`, which reads like "this element cannot
+ *      be edited" and means "there is no such target".
+ *   2. `20138` is the *other* thing — the element resolved and does not support
+ *      that action. A paragraph returns it for `append` and always will, which
+ *      is documented behaviour and not a sign anything is wrong.
+ *   3. Replace requires the **generated** id, never a `data-id`, for everything
+ *      except the title and images inside a div. Generated ids are returned only
+ *      with `includeIDs=true`, and Microsoft warns they "might change after a
+ *      page update" — so they are read immediately before the command that uses
+ *      them, never carried across a write.
+ */
+import { type RecordWrite } from './audit.js';
+export declare const isGeneratedId: (id: string) => boolean;
+export type PageTargets = {
+    /** Author-supplied, addressed with a leading `#`. Usable for append only. */
+    dataIds: string[];
+    /** Graph-generated, addressed bare. Required for replace. */
+    generatedIds: string[];
+};
+/**
+ * What the page currently offers as targets.
+ *
+ * Read from the output of `GET .../content?includeIDs=true`. Both attributes
+ * are collected because they are not interchangeable: `data-id` is ours and
+ * survives a round trip, `id` is Graph's and moves. A caller wanting to replace
+ * needs the second even when it labelled the element with the first.
+ */
+export declare const readTargets: (html: string) => PageTargets;
+/**
+ * Cut one element, with its children, out of the page HTML.
+ *
+ * Depth-counted rather than matched with a lazy regex. A non-greedy match to
+ * the first closing tag returns a fragment whenever the target has children,
+ * and a fragment restores as silent truncation — which is the precise failure
+ * a pre-image exists to prevent. Returns undefined rather than guessing when
+ * the markup does not balance.
+ */
+export declare const extractElement: (html: string, attr: "id" | "data-id", value: string) => string | undefined;
+/**
+ * The content a replace is about to destroy, or a refusal.
+ *
+ * Throws rather than returning undefined, because every caller must treat a
+ * failed capture as a reason not to write. Making that the return type would
+ * let a caller carry on with `?? ''` and destroy a paragraph with nothing held
+ * back, which is exactly the outcome 0004 forbids.
+ */
+export declare const preImage: (html: string, generatedId: string) => string;
+export type PatchCommand = {
+    target: string;
+    action: 'append' | 'replace';
+    content: string;
+};
+/**
+ * Append to a container.
+ *
+ * `body` and `title` are keywords and take no prefix; everything else appended
+ * to is addressed by `data-id`, which does. Getting this wrong is not a visible
+ * error — it is a `20134` that reads as though the element were uneditable.
+ */
+export declare const appendCommand: (target: string, contentHtml: string) => PatchCommand;
+/**
+ * Replace one element, named by its generated id.
+ *
+ * `data-id` is refused rather than translated. Graph accepts a `data-id` for a
+ * replace on images and objects only, and silently doing the wrong thing for
+ * every other element would mean a command that looks right and either fails
+ * confusingly or hits something other than what was meant.
+ */
+export declare const replaceCommand: (generatedId: string, contentHtml: string) => PatchCommand;
+/**
+ * Plain text as a single paragraph, which is what replaces a paragraph.
+ *
+ * A replace must yield an element of a kind the target supports, so this is
+ * deliberately not general: one `<p>`, with line breaks preserved and nothing
+ * else interpreted. Anything richer is a different operation and should be
+ * decided rather than smuggled in through the content string.
+ */
+export declare const paragraph: (text: string) => string;
+export type EditDraft = {
+    page_id: string;
+    action: 'append' | 'replace';
+    /** The generated id of the element to replace. Absent for an append. */
+    element_id: string | null;
+    text: string;
+    source_page: string | null;
+};
+export declare const editFrom: (params: Record<string, unknown>) => EditDraft;
+/**
+ * The token a preview returns and an edit must carry back.
+ *
+ * Derived from the payload **and from what the change would destroy**, which is
+ * the one difference from the create token and the reason this is not shared
+ * with `onenote-write.ts`. A create can only be wrong about what it writes. A
+ * replace can also be wrong about what it overwrites — and the id naming that
+ * content moves after every page update, so an id that was correct at preview
+ * may point at something else by the time the edit is applied.
+ *
+ * Hashing the pre-image makes that case fail closed: the edit is refused unless
+ * the element still holds exactly what the musician was shown.
+ */
+export declare const editToken: (draft: EditDraft, preImageHtml: string) => Promise<string>;
+/**
+ * What the page currently says, element by element, so a caller can name the
+ * part to change without guessing an id.
+ *
+ * Every id here is read in this call and is only good for the next one. They
+ * are not stable identifiers and must never be stored, handed to a musician, or
+ * quoted back in a later session — Microsoft says they "might change after a
+ * page update", and that was observed rather than merely read.
+ */
+export declare const readEditableParts: (token: string, pageId: string) => Promise<{
+    html: string;
+    etag: string | null;
+    parts: {
+        element_id: string;
+        text: string;
+    }[];
+}>;
+/**
+ * Show the change that would be made, and hand back the token making it needs.
+ *
+ * A read despite the name, exactly as the calendar and create previews are.
+ */
+export declare function previewEdit(token: string, params: Record<string, unknown>): Promise<{
+    preview: null;
+    page_id: string;
+    parts: {
+        element_id: string;
+        text: string;
+    }[];
+    confirmation_token: null;
+    note: string;
+} | {
+    preview: string;
+    page_id: string;
+    parts: {
+        element_id: string;
+        text: string;
+    }[];
+    confirmation_token: string;
+    note: string;
+}>;
+/**
+ * Apply the change, having shown it.
+ *
+ * The page is read again here rather than trusted from the preview, and that is
+ * not caution: generated ids move after any page update, so an id that was
+ * right at preview may name something else by now. Re-reading also produces the
+ * ETag that goes out as `If-Match`, which is what makes the musician typing in
+ * OneNote between the two calls a refusal rather than a silent overwrite.
+ *
+ * The confirmation token is checked against the payload *and* the pre-image, so
+ * an element whose content changed since the preview fails closed.
+ */
+export declare function applyEdit(token: string, params: Record<string, unknown>, record: RecordWrite): Promise<{
+    changed: boolean;
+    page_id: string;
+    note: string;
+}>;

package/dist/onenote-patch.js

@@ -0,0 +1,403 @@
+/**
+ * Editing a page this tool created, and only such a page.
+ *
+ * Like `onenote-write.ts`, there is no ownership boundary in this file, and for
+ * the same reason: `Notes.ReadWrite.CreatedByApp` refuses a page the musician
+ * wrote before our code is consulted — verified as `401 40003` against a real
+ * notebook. What *is* here is the machinery that makes a replace permissible at
+ * all, which is a different question and ours to get right. See
+ * docs/decisions/0004-onenote-page-maintenance.md.
+ *
+ * The rule that record rests on: **a replace may not proceed unless the content
+ * it is about to destroy has been captured first.** OneNote keeps no version and
+ * no recycle bin, so the pre-image is the only undo that exists. It is not a
+ * feature attached to replacing; it is the reason replacing is allowed.
+ *
+ * Three facts about Graph's patch API are encoded below rather than remembered,
+ * because two probe runs concluded the opposite of the truth from them:
+ *
+ *   1. A `data-id` target must carry a `#`. Without it the target does not
+ *      resolve and Graph answers `20134`, which reads like "this element cannot
+ *      be edited" and means "there is no such target".
+ *   2. `20138` is the *other* thing — the element resolved and does not support
+ *      that action. A paragraph returns it for `append` and always will, which
+ *      is documented behaviour and not a sign anything is wrong.
+ *   3. Replace requires the **generated** id, never a `data-id`, for everything
+ *      except the title and images inside a div. Generated ids are returned only
+ *      with `includeIDs=true`, and Microsoft warns they "might change after a
+ *      page update" — so they are read immediately before the command that uses
+ *      them, never carried across a write.
+ */
+import { onenotePageContent, onenotePatchPage } from './api.js';
+import { GraphError } from './client.js';
+const failure = (message) => new GraphError(message, false);
+/**
+ * A generated id as Graph emits it: `p:{guid}{40}`, and for a div nested in a
+ * div, the doubled `div:{guid}{42}:{guid}{45}`.
+ *
+ * Shape-checked because it is concatenated into a JSON command that Graph acts
+ * on, and because it is the one value here that decides what gets destroyed. A
+ * caller that has invented an id, or kept one across a write, should be refused
+ * rather than allowed to overwrite whatever that id now points at.
+ */
+const GENERATED_ID = /^(?:p|div|ol|ul|li|table|img|object|h[1-6]):\{[0-9a-fA-F-]{36}\}\{\d+\}(?::\{[0-9a-fA-F-]{36}\}\{\d+\})?$/;
+export const isGeneratedId = (id) => GENERATED_ID.test(id);
+/**
+ * What the page currently offers as targets.
+ *
+ * Read from the output of `GET .../content?includeIDs=true`. Both attributes
+ * are collected because they are not interchangeable: `data-id` is ours and
+ * survives a round trip, `id` is Graph's and moves. A caller wanting to replace
+ * needs the second even when it labelled the element with the first.
+ */
+export const readTargets = (html) => ({
+    dataIds: [...html.matchAll(/\sdata-id="([^"]+)"/g)].map((m) => m[1]),
+    generatedIds: [...html.matchAll(/\sid="([^"]+)"/g)]
+        .map((m) => m[1])
+        .filter((id) => isGeneratedId(id)),
+});
+/**
+ * Cut one element, with its children, out of the page HTML.
+ *
+ * Depth-counted rather than matched with a lazy regex. A non-greedy match to
+ * the first closing tag returns a fragment whenever the target has children,
+ * and a fragment restores as silent truncation — which is the precise failure
+ * a pre-image exists to prevent. Returns undefined rather than guessing when
+ * the markup does not balance.
+ */
+export const extractElement = (html, attr, value) => {
+    const quoted = value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const open = new RegExp(`<([a-z][a-z0-9]*)\\b[^>]*\\b${attr}="${quoted}"[^>]*>`, 'i').exec(html);
+    if (open === null)
+        return undefined;
+    const tag = open[1];
+    const step = new RegExp(`<(/?)${tag}\\b[^>]*?(/?)>`, 'gi');
+    step.lastIndex = open.index;
+    let depth = 0;
+    let match;
+    while ((match = step.exec(html)) !== null) {
+        // A self-closing tag enters and leaves in one token.
+        if (match[2] === '/')
+            continue;
+        depth += match[1] === '/' ? -1 : 1;
+        if (depth === 0)
+            return html.slice(open.index, match.index + match[0].length);
+    }
+    return undefined;
+};
+/**
+ * The content a replace is about to destroy, or a refusal.
+ *
+ * Throws rather than returning undefined, because every caller must treat a
+ * failed capture as a reason not to write. Making that the return type would
+ * let a caller carry on with `?? ''` and destroy a paragraph with nothing held
+ * back, which is exactly the outcome 0004 forbids.
+ */
+export const preImage = (html, generatedId) => {
+    if (!isGeneratedId(generatedId)) {
+        throw failure(`"${generatedId}" is not a generated element id. A replace has to name one, ` +
+            'read from the page immediately beforehand.');
+    }
+    const captured = extractElement(html, 'id', generatedId);
+    if (captured === undefined) {
+        throw failure('The element to be replaced could not be read back from the page, so what ' +
+            'the change would overwrite cannot be captured. Nothing was changed. ' +
+            'OneNote keeps no version of a page, so a replace without that capture ' +
+            'would be unrecoverable.');
+    }
+    return captured;
+};
+/**
+ * Append to a container.
+ *
+ * `body` and `title` are keywords and take no prefix; everything else appended
+ * to is addressed by `data-id`, which does. Getting this wrong is not a visible
+ * error — it is a `20134` that reads as though the element were uneditable.
+ */
+export const appendCommand = (target, contentHtml) => {
+    if (target === 'title') {
+        throw failure('A title cannot be appended to; it can only be replaced.');
+    }
+    return {
+        target: target === 'body' || isGeneratedId(target) ? target : `#${target.replace(/^#/, '')}`,
+        action: 'append',
+        content: contentHtml,
+    };
+};
+/**
+ * Replace one element, named by its generated id.
+ *
+ * `data-id` is refused rather than translated. Graph accepts a `data-id` for a
+ * replace on images and objects only, and silently doing the wrong thing for
+ * every other element would mean a command that looks right and either fails
+ * confusingly or hits something other than what was meant.
+ */
+export const replaceCommand = (generatedId, contentHtml) => {
+    if (!isGeneratedId(generatedId)) {
+        throw failure(`A replace must name a generated element id, not "${generatedId}". Read the ` +
+            'page with includeIDs=true and use the id it reports for the element.');
+    }
+    return { target: generatedId, action: 'replace', content: contentHtml };
+};
+/**
+ * XHTML entities, as in onenote-write.ts and for the same reason: a model
+ * composing a correction from an email is passing through text it did not
+ * author, and unescaped markup would let that text decide what the page says.
+ */
+const escapeXml = (value) => value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+/**
+ * Plain text as a single paragraph, which is what replaces a paragraph.
+ *
+ * A replace must yield an element of a kind the target supports, so this is
+ * deliberately not general: one `<p>`, with line breaks preserved and nothing
+ * else interpreted. Anything richer is a different operation and should be
+ * decided rather than smuggled in through the content string.
+ */
+export const paragraph = (text) => {
+    const trimmed = text.trim();
+    if (trimmed === '')
+        throw failure('There is no text to write.');
+    return `<p>${escapeXml(trimmed).replace(/\n/g, '<br/>')}</p>`;
+};
+/** As in onenote-write.ts: opaque, but concatenated into URLs. */
+const ONENOTE_ID = /^[A-Za-z0-9!._~-]{1,300}$/;
+const MAX_TEXT_CHARS = 4_000;
+export const editFrom = (params) => {
+    const pageId = params.page_id;
+    if (typeof pageId !== 'string' || !ONENOTE_ID.test(pageId)) {
+        throw failure('page_id is required, and must name the page to change.');
+    }
+    const action = params.action;
+    if (action !== 'append' && action !== 'replace') {
+        throw failure("action must be either 'append' or 'replace'. Nothing else can be done to a page.");
+    }
+    const text = params.text;
+    if (typeof text !== 'string' || text.trim() === '') {
+        throw failure('text is required: there is nothing to write.');
+    }
+    if (text.length > MAX_TEXT_CHARS) {
+        throw failure(`That is ${text.length} characters. An edit records a decision, not a page — ` +
+            `${MAX_TEXT_CHARS} is the most. A longer change is a new page.`);
+    }
+    const elementId = params.element_id;
+    if (action === 'replace') {
+        if (typeof elementId !== 'string' || !isGeneratedId(elementId)) {
+            throw failure('A replace needs element_id: the generated id of the part to change, as ' +
+                'preview_onenote_edit reports it. Read the page again if you do not have one.');
+        }
+    }
+    else if (elementId !== undefined && elementId !== null && elementId !== '') {
+        throw failure('An append goes at the end of the page and takes no element_id. To change ' +
+            'something already written, use replace.');
+    }
+    const source = params.source_page;
+    if (source !== undefined && source !== null && source !== '') {
+        if (typeof source !== 'string' || !ONENOTE_ID.test(source)) {
+            throw failure('source_page is malformed.');
+        }
+    }
+    return {
+        page_id: pageId,
+        action,
+        element_id: action === 'replace' ? elementId : null,
+        text,
+        source_page: typeof source === 'string' && source !== '' ? source : null,
+    };
+};
+const base32hex = (bytes) => {
+    const alphabet = '0123456789abcdefghijklmnopqrstuv';
+    let bits = 0;
+    let value = 0;
+    let out = '';
+    for (const byte of bytes) {
+        value = (value << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            out += alphabet[(value >>> (bits - 5)) & 31];
+            bits -= 5;
+        }
+    }
+    return out;
+};
+/**
+ * The token a preview returns and an edit must carry back.
+ *
+ * Derived from the payload **and from what the change would destroy**, which is
+ * the one difference from the create token and the reason this is not shared
+ * with `onenote-write.ts`. A create can only be wrong about what it writes. A
+ * replace can also be wrong about what it overwrites — and the id naming that
+ * content moves after every page update, so an id that was correct at preview
+ * may point at something else by the time the edit is applied.
+ *
+ * Hashing the pre-image makes that case fail closed: the edit is refused unless
+ * the element still holds exactly what the musician was shown.
+ */
+export const editToken = async (draft, preImageHtml) => {
+    const canonical = [draft.page_id, draft.action, draft.element_id ?? '', draft.text].join(' ');
+    const data = new TextEncoder().encode(`confirm-edit ${canonical} ${preImageHtml}`);
+    return base32hex(new Uint8Array(await crypto.subtle.digest('SHA-256', data)));
+};
+/**
+ * Strip tags for display. The page is shown as the musician reads it, not as
+ * HTML — and this text is what they approve a destructive change against, so
+ * markup leaking into it is not cosmetic.
+ *
+ * Numeric entities are decoded as well as named ones. We write `&apos;`, but
+ * OneNote stores an apostrophe as `&#39;` and hands it back that way, so a
+ * decoder built only from what this file emits showed a preview reading
+ * "the product&#39;s own tool path" — observed on a real page.
+ *
+ * Ampersand last, or the entities the earlier passes produce get decoded again.
+ */
+const asText = (html) => html
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(/<[^>]+>/g, '')
+    .replace(/&#x([0-9a-f]+);/gi, (_, hex) => String.fromCodePoint(parseInt(hex, 16)))
+    .replace(/&#(\d+);/g, (_, dec) => String.fromCodePoint(Number(dec)))
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+    .trim();
+/**
+ * What the page currently says, element by element, so a caller can name the
+ * part to change without guessing an id.
+ *
+ * Every id here is read in this call and is only good for the next one. They
+ * are not stable identifiers and must never be stored, handed to a musician, or
+ * quoted back in a later session — Microsoft says they "might change after a
+ * page update", and that was observed rather than merely read.
+ */
+export const readEditableParts = async (token, pageId) => {
+    const { html, etag } = await onenotePageContent(pageId, token);
+    const parts = readTargets(html)
+        .generatedIds.filter((id) => /^(?:p|h[1-6]|li):/.test(id))
+        .map((id) => {
+        const element = extractElement(html, 'id', id);
+        return { element_id: id, text: element === undefined ? '' : asText(element) };
+    })
+        .filter((part) => part.text !== '');
+    return { html, etag, parts };
+};
+/**
+ * Show the change that would be made, and hand back the token making it needs.
+ *
+ * A read despite the name, exactly as the calendar and create previews are.
+ */
+export async function previewEdit(token, params) {
+    // Naming a part to replace requires knowing its id, and an id is only
+    // knowable by reading the page. So a replace with no element_id is not a
+    // malformed call — it is the first half of the only workflow available, and
+    // the tool text says so. It used to be refused here, which meant a model
+    // following that text got an error and had to guess its way out.
+    //
+    // No confirmation token comes back from this branch. Nothing has been chosen
+    // yet, and a token would be one for a change nobody has described.
+    const wantsPart = params.action === 'replace' &&
+        (params.element_id === undefined || params.element_id === null || params.element_id === '');
+    if (wantsPart) {
+        const pageId = params.page_id;
+        if (typeof pageId !== 'string' || !ONENOTE_ID.test(pageId)) {
+            throw failure('page_id is required, and must name the page to change.');
+        }
+        const { parts } = await readEditableParts(token, pageId);
+        return {
+            preview: null,
+            page_id: pageId,
+            parts,
+            confirmation_token: null,
+            note: parts.length === 0
+                ? 'This page has no separately editable parts, so nothing on it can be ' +
+                    'replaced. An append can still add to the end of it.'
+                : 'Nothing has been previewed yet. These are the parts of the page as it ' +
+                    'stands. Name one as element_id and preview again to see the change ' +
+                    'itself. The ids were read just now and are good only for the next call.',
+        };
+    }
+    const draft = editFrom(params);
+    const { html, parts } = await readEditableParts(token, draft.page_id);
+    if (draft.action === 'append') {
+        return {
+            preview: `Add to the end of the page:\n\n${draft.text.trim()}`,
+            page_id: draft.page_id,
+            parts,
+            confirmation_token: await editToken(draft, ''),
+            note: 'Show this to the musician and wait for their yes. Nothing on the page is ' +
+                'changed or removed by an append — it adds to the end.',
+        };
+    }
+    const captured = preImage(html, draft.element_id);
+    return {
+        preview: `Replace this:\n\n${asText(captured)}\n\nWith this:\n\n${draft.text.trim()}`,
+        page_id: draft.page_id,
+        parts,
+        confirmation_token: await editToken(draft, captured),
+        note: 'Show this to the musician and wait for their yes. This overwrites what is ' +
+            'quoted above, and OneNote keeps no version of a page — what it replaces is ' +
+            'kept in this install\'s own write log and nowhere else.',
+    };
+}
+/**
+ * Apply the change, having shown it.
+ *
+ * The page is read again here rather than trusted from the preview, and that is
+ * not caution: generated ids move after any page update, so an id that was
+ * right at preview may name something else by now. Re-reading also produces the
+ * ETag that goes out as `If-Match`, which is what makes the musician typing in
+ * OneNote between the two calls a refusal rather than a silent overwrite.
+ *
+ * The confirmation token is checked against the payload *and* the pre-image, so
+ * an element whose content changed since the preview fails closed.
+ */
+export async function applyEdit(token, params, record) {
+    const draft = editFrom(params);
+    const { html, etag } = await onenotePageContent(draft.page_id, token);
+    const captured = draft.action === 'replace' ? preImage(html, draft.element_id) : '';
+    const expected = await editToken(draft, captured);
+    if (params.confirmation_token !== expected) {
+        throw failure(draft.action === 'replace'
+            ? 'That part of the page is not what was previewed — either the values ' +
+                'changed, or the page did since it was shown. Nothing was written. Call ' +
+                'preview_onenote_edit again and show the musician what it returns now.'
+            : 'The confirmation token does not match these values. Call ' +
+                'preview_onenote_edit again with exactly what should be written, show the ' +
+                'musician what it returns, then apply it with those same values.');
+    }
+    const command = draft.action === 'append'
+        ? appendCommand('body', paragraph(draft.text))
+        : replaceCommand(draft.element_id, paragraph(draft.text));
+    await onenotePatchPage(draft.page_id, [command], token, etag);
+    // After the write, and carrying what it destroyed. For a replace this line is
+    // the only copy of the previous content that exists anywhere.
+    await record({
+        operation: draft.action === 'append' ? 'append_onenote_page' : 'replace_onenote_element',
+        // The text itself, not merely that something happened. `summary` is
+        // documented as what was written "as the user would read it back", and the
+        // calendar rows honour that while these two originally named only the page
+        // id — so the log recorded the replaced text in `pre_image` and left the
+        // replacing text nowhere at all. Someone reading this line back is
+        // reconstructing an edit they cannot see any other way.
+        summary: draft.action === 'append'
+            ? `Added to the end of the page: ${draft.text.trim()}`
+            : `Replaced "${asText(captured)}" with "${draft.text.trim()}"`,
+        target: draft.page_id,
+        source_page: draft.source_page,
+        pre_image: draft.action === 'replace' ? captured : null,
+    });
+    return {
+        changed: true,
+        page_id: draft.page_id,
+        note: draft.action === 'append'
+            ? 'The page now carries this at the end. Nothing was removed.'
+            : 'The page now says this. What it said before is in this install\'s write ' +
+                'log and nowhere else — OneNote keeps no version of a page, so tell the ' +
+                'musician that rather than implying it can be undone in OneNote.',
+    };
+}

package/dist/server.js

@@ -164,7 +164,7 @@ const renderChangedSections = (chosen, notebook, since) => {
         caveats.join("\n\n"),
     ].join("\n\n");
 };
-const serverVersion = '2.0.1-staging.94'; // x-release-please-version
+const serverVersion = '2.1.0'; // x-release-please-version
 const errorResult = (err) => {
     const message = err instanceof GraphError ? err.message : `Unexpected error: ${err}`;
     return { content: [{ type: "text", text: message }], isError: true };
@@ -1480,7 +1480,11 @@ const createServer = async (call, grants = []) => {
             "holds, not a policy it follows, so a page created by mistake stays " +
             "until the musician removes it in OneNote themselves. There is no bulk " +
             "form. It never changes an existing page, so it is not a way to add a " +
-            "line to one: paste that for the musician as always. Requires the " +
+            "line to one: " +
+            (isGranted(grants, "onenote-edit")
+                ? "use preview_onenote_edit and edit_onenote_page for that. "
+                : "paste that for the musician as always. ") +
+            "Requires the " +
             "confirmation_token from a preview of these exact values; change any " +
             "field and the token stops matching, which means preview again and show " +
             "the musician the new version. Never write a value the musician chose in " +
@@ -1522,6 +1526,117 @@ const createServer = async (call, grants = []) => {
             }
         });
     }
+    /**
+     * Editing a page this tool wrote.
+     *
+     * Everything the create tools lean on inverts here. There, the strongest
+     * thing the text could say was that a mistake is permanent, because a model
+     * that believes a mistake is repairable creates more freely. Here a mistake
+     * *is* repairable, and the danger runs the other way: a model that believes
+     * an edit is free will make more of them, and a replace destroys what it
+     * overwrites with only this install's own write log standing behind it.
+     *
+     * So the text below says the opposite thing plainly — that OneNote keeps no
+     * version, that the record of what was overwritten lives here and nowhere
+     * else, and that a page the musician wrote is unreachable no matter how the
+     * request is phrased. See docs/decisions/0004-onenote-page-maintenance.md.
+     */
+    if (isGranted(grants, "onenote-edit")) {
+        server.tool("preview_onenote_edit", "Call this before edit_onenote_page — it is the only way to obtain the confirmation_token that one requires, and it is what puts the exact change in front of the musician. SHOW THE MUSICIAN WHAT IT RETURNS AND WAIT FOR THEIR YES. " +
+            "Reads the page as it stands right now and shows what the change would " +
+            "do to it. Changes nothing. For a replace it quotes the text that would " +
+            "be overwritten, which is the part the musician has to agree to. It also " +
+            "returns the page's editable parts with an element_id for each, so pass " +
+            "action 'replace' with no element_id first if you do not know which part " +
+            "to change, read the parts back, then preview again naming one. Those " +
+            "ids are read fresh each call and are good only for the next call — " +
+            "never store one, repeat one to the musician, or reuse one from earlier " +
+            "in the conversation.", {
+            page_id: z
+                .string()
+                .describe("The page to change, by id from list_notes or read_note. The id, not the title"),
+            action: z
+                .enum(["append", "replace"])
+                .describe("append adds a paragraph at the end and removes nothing. replace " +
+                "overwrites one existing element and is the destructive one"),
+            text: z.string().describe("The new text, plain. Markdown and HTML are NOT interpreted"),
+            element_id: z
+                .string()
+                .optional()
+                .describe("For replace only: which part to overwrite, using an element_id this " +
+                "tool reported in the parts list on a previous call"),
+            source_page: z
+                .string()
+                .optional()
+                .describe("The page this change was decided from, so the write can be traced back"),
+        }, async (params) => {
+            try {
+                const { preview, confirmation_token, parts, note } = await call("preview_onenote_edit", params);
+                const listed = parts.length === 0
+                    ? ""
+                    : "\n\nThe editable parts of this page right now:\n" +
+                        parts.map((p) => `  ${p.element_id}\n    ${p.text}`).join("\n");
+                // No token means nothing has been chosen yet: this was the call that
+                // asks which part to change. Saying "wait for their yes" here would
+                // be asking the musician to approve a change nobody has described.
+                if (confirmation_token === null) {
+                    return { content: [{ type: "text", text: `${note}${listed}` }] };
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${preview}${listed}\n\n` +
+                                "Show this to the musician and wait for their yes. If this is a " +
+                                "replace, say plainly what it overwrites: OneNote keeps no " +
+                                "version of a page, so the previous text will exist only in this " +
+                                "install's write log afterwards. If they agree, call " +
+                                "edit_onenote_page with the SAME values and:\n" +
+                                `  confirmation_token: ${confirmation_token}`,
+                        },
+                    ],
+                };
+            }
+            catch (err) {
+                return errorResult(err);
+            }
+        });
+        server.tool("edit_onenote_page", "Only call this after preview_onenote_edit AND after the musician has said yes to what the preview showed. Never call it to find out whether it would work. " +
+            "Changes ONE page that artist-mcp itself created. It CANNOT touch a page " +
+            "the musician wrote or one another app created — Microsoft refuses those, " +
+            "not this tool — and it cannot delete anything. 'append' adds a paragraph " +
+            "at the end and removes nothing. 'replace' overwrites one element and is " +
+            "destructive: OneNote keeps no page version and a replaced paragraph is " +
+            "recoverable only from this install's own write log, so never describe it " +
+            "as undoable in OneNote. Requires the confirmation_token from a preview " +
+            "of these exact values; if the page changed since that preview the token " +
+            "stops matching and nothing is written, which means preview again and " +
+            "show the musician the new version. Never write a value the musician " +
+            "chose in chat to break a tie between pages that still disagree.", {
+            page_id: z.string().describe("Exactly what the preview showed"),
+            action: z.enum(["append", "replace"]).describe("Exactly what the preview showed"),
+            text: z.string().describe("Exactly what the preview showed"),
+            element_id: z
+                .string()
+                .optional()
+                .describe("For replace: the same element_id the preview was given"),
+            source_page: z
+                .string()
+                .optional()
+                .describe("The page this change was decided from, so the write can be traced back"),
+            confirmation_token: z
+                .string()
+                .describe("The token preview_onenote_edit returned for these exact values"),
+        }, async (params) => {
+            try {
+                const { note } = await call("edit_onenote_page", params);
+                return { content: [{ type: "text", text: note }] };
+            }
+            catch (err) {
+                return errorResult(err);
+            }
+        });
+    }
     server.tool("list_calendars", "Call this before concluding that something is NOT in the calendar. A search of one calendar that finds nothing is not evidence of absence — it is evidence about one calendar. Gigs commonly sit on a band, venue or shared calendar rather than the primary one. " +
         "Lists the Google calendars this musician has, with which one is primary " +
         "and whether each is writable by them. Read-only: this never creates, " +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manudota/artist-mcp",
-  "version": "2.0.1-staging.94",
+  "version": "2.1.0",
   "description": "MCP server that reads your OneNote notes, with optional Gmail and Calendar as supporting evidence, via a hosted connection.",
   "repository": {
     "type": "git",