docupuncture 0.1.6 → 0.1.8

package/README.md

@@ -2,9 +2,9 @@
 
 Treat the document you already have.
 
-Insert precise edits without changing the theme, format, comments, or history.
+Make targeted edits in an existing Google Doc, Sheet, or Slides file using a reviewable Apps Script. DocuPuncture starts with a dry run and is designed to preserve surrounding structure for supported edit types.
 
-When an AI regenerates a Google Doc, Sheet, or deck, those things usually go with it. DocuPuncture writes a small Apps Script you paste and run on the live file.
+When an AI regenerates a Google Doc, Sheet, or deck, theme, format, comments, and the existing revision thread usually go with it. DocuPuncture writes a small Apps Script you paste and run on the live file.
 
 ## The skills
 
@@ -13,7 +13,7 @@ Copy a folder into Cursor, Claude Code, or anything else that reads `SKILL.md`.
 | Skill | Surface | Fit |
 | --- | --- | --- |
 | [`docupuncture-docs`](skills/docupuncture-docs/SKILL.md) | Google Docs | Comments, tabs, lists, partial styling. |
-| [`docupuncture-sheets`](skills/docupuncture-sheets/SKILL.md) | Google Sheets | Grid and ranges. Notes and validation stay. |
+| [`docupuncture-sheets`](skills/docupuncture-sheets/SKILL.md) | Google Sheets | Grid and ranges. Notes and validation stay on cells you do not rewrite. |
 | [`docupuncture-slides`](skills/docupuncture-slides/SKILL.md) | Google Slides | Text and content. Layout surgery is higher risk. |
 
 ## Install
@@ -33,12 +33,13 @@ Site: [docupuncture.dev](https://docupuncture.dev)
 
 ## How a run works
 
-1. The agent reads the live file and confirms the edits.
-2. It writes an Apps Script.
-3. You open the file → Extensions → Apps Script → paste → run `applyEdits`.
-4. First run is a dry run (`DRY_RUN = true`). Read the log, flip the flag, run again.
+1. Name the target file (URL or ID) and the intended changes.
+2. Give the agent exact current text for anchors, or let a host Drive connector read the file if you already have one. The skill does not grant Google access.
+3. Review the Apps Script it writes.
+4. Open the file → Extensions → Apps Script → paste → run `applyEdits`.
+5. First run is a dry run (`DRY_RUN = true`). Read the log, flip the flag, then run again.
 
-The script is safe to re-run. Missing anchors are logged. It never invents a location.
+The script runs as you. Missing or ambiguous anchors are logged. It never invents a location. For the showcased insert and update operations, a repeat run skips work that is already there.
 
 ## Why the name
 

package/package.json

@@ -1,9 +1,9 @@
 {
 	"name": "docupuncture",
-	"version": "0.1.6",
+	"version": "0.1.8",
 	"private": false,
 	"type": "module",
-	"description": "Insert precise edits without changing the theme, format, comments, or history.",
+	"description": "Targeted, reviewable Apps Script edits in an existing Google Doc, Sheet, or Slides file.",
 	"license": "MIT",
 	"author": "Catalyst Forge LLC",
 	"keywords": [

package/skills/docupuncture-docs/SKILL.md

@@ -1,20 +1,20 @@
 ---
 name: docupuncture-docs
-description: Precise in-place edits to an existing Google Doc via paste-and-run Apps Script. Use when the user wants edits, tweaks, or iterations to a Google Doc (or says "DocuPuncture") — deliver a self-contained script that patches the live doc while preserving all formatting, instead of regenerating a new document. Prefer this over full regeneration for formatted docs. Part of the DocuPuncture family (Docs, Sheets, Slides).
+description: Precise in-place edits to an existing Google Doc via paste-and-run Apps Script. Use when the user wants edits, tweaks, or iterations to a Google Doc (or says "DocuPuncture") — deliver a self-contained script that patches the live doc while preserving surrounding structure for supported edit types, instead of regenerating a new document. Prefer this over full regeneration for formatted docs. Part of the DocuPuncture family (Docs, Sheets, Slides).
 ---
 
 # DocuPuncture for Docs
 
-DocuPuncture = insert precise edits without changing the theme, format, comments, or history. This skill is the **Docs** implementation.
+DocuPuncture writes a reviewable Apps Script that patches an existing Google Doc in place. Surrounding structure is a design goal for supported edit types. An edit adds a revision. This skill is the **Docs** implementation.
 
-Deliver edits as a self-contained Apps Script the user pastes into Extensions → Apps Script and runs, instead of regenerating a new document. In-place patching preserves all formatting (fonts, colors, images, tables, comments, theme) that API imports and full regenerations destroy. Use the name "DocuPuncture" when referring to this workflow with the user.
+Deliver edits as a self-contained Apps Script the user pastes into Extensions → Apps Script and runs, instead of regenerating a new document. In-place patching is designed to keep theme, sibling formatting when copied, and comments on untouched text. It does not guarantee every format or comment anchor survives every edit. Use the name "DocuPuncture" when referring to this workflow with the user.
 
 
 ## When to offer
 
 Whenever the user asks for edits, tweaks, or iterations to an existing Google Doc — especially repeated iteration rounds — use AskUserQuestion to offer:
 
-1. **DocuPuncture: Apps Script patch** (recommended for formatted docs) — I generate a script; you run it once. Formatting preserved. First run requires a one-time authorization prompt.
+1. **DocuPuncture: Apps Script patch** (recommended for formatted docs) — I generate a script; you run it once. Surrounding structure stays for supported edits. First run requires a one-time authorization prompt.
 2. **New generated doc** — full regeneration (warn: loses theme/logo/comments).
 3. **Manual edit checklist** — exact paste-ready text.
 
@@ -32,15 +32,15 @@ If the set of changes is high-risk, surface this explicitly to the user before w
 
 ## Workflow
 
-1. **Read the doc first** via the Google Drive MCP `read_file_content` (extract the file ID from the URL). Get the EXACT current text — anchors must match character-for-character. Confirm with the user which edits to make before writing the script.
+1. **Identify the file and the exact current text.** Ask for the Doc URL or ID and the intended changes. If the host already has Google Drive MCP `read_file_content` (or another Drive connector) connected, use it. Otherwise require the user to paste the relevant passages. This skill does not grant Google access. Anchors must match character-for-character. Confirm which edits to make before writing the script.
 
 2. **Write the script** (rules below) and deliver it in a code block with run instructions:
    - Open the doc → Extensions → Apps Script
    - Delete any existing code, paste the script, click Run (▶) on `applyEdits`
    - First run: authorize when prompted (it runs as you, on your doc)
-   - Check the Execution log for the ✓/✗ summary
+   - Check the Execution log for the ✓/✗ summary. Keep `DRY_RUN = true` until that log matches the intended changes.
 
-3. **Verify** after the user says they ran it: re-read the doc via MCP and confirm every edit landed.
+3. **Verify** after the user says they ran it: re-read the doc via MCP if available, or ask the user to confirm each edit.
 
 ## Script rules
 
@@ -52,8 +52,10 @@ If the set of changes is high-risk, surface this explicitly to the user before w
   - Prefer a short, highly unique literal that is unlikely to change (section titles, distinctive phrases near the edit point, or rare words).
   - `findText` treats its pattern as a regex, so always route anchor literals through the `escapeRegExp` helper (see skeleton) rather than passing raw strings — a stray `(` or `?` in a section title will silently break the match otherwise.
   - Use a distinctive substring, never an entire long paragraph (text may span multiple runs).
-  - For higher robustness on medium/high-risk edits: make each edit function try a primary unique anchor, then a secondary nearby unique context string if the primary is missing. Log which strategy succeeded.
-  - Never invent a location if no anchor is found.
+  - For higher robustness on medium/high-risk edits: make each edit function try a primary unique anchor, then a secondary nearby unique context string if the primary is missing. Log which strategy succeeded. The backup must also be unique.
+  - If a targeted edit's anchor matches more than once, log `✗ SKIPPED: <edit name> — anchor is ambiguous` and skip. Do not take the first match.
+  - Never invent a location if no unique anchor is found.
+  - `replaceText` for a simple swap applies to every match. Use it only when the user asked for every occurrence, and say so in the log.
 
 - **Inserting paragraphs**: `body.getChildIndex(anchorElement.getParent())` then `body.insertParagraph(idx + 1, text)`. Copy formatting from a sibling: `newPara.setAttributes(sibling.getAttributes())`.
 
@@ -65,11 +67,11 @@ If the set of changes is high-risk, surface this explicitly to the user before w
 
 - **Replacements**: prefer `body.replaceText(escapedPattern, replacement)` for simple text swaps; for structural changes (splitting a bullet, inserting between existing items), edit the existing element's text and insert new siblings.
 
-- **Idempotent**: before each edit, check whether the target state already exists (`findText` for new content; absence for deletions) and skip with a log message if so. Re-running must never duplicate content.
+- **Repeat-run (showcased insert)**: before a targeted insert or swap, check whether the target state already exists (`findText` for new content, absence for deletions) and skip with a log message if so. The sample `edit_AddIntroParagraph` skips when the new paragraph is already there. Do not claim that guarantee for every script.
 
-- **Fail loudly**: if an anchor isn't found, log `✗ SKIPPED: <edit name> — anchor not found` and continue with the other edits. Never guess a location. End with a summary: `Logger.log('Done: X applied, Y skipped')`.
+- **Fail loudly**: if an anchor isn't found, or a targeted edit's anchor matches more than once, log `✗ SKIPPED: <edit name> — anchor not found` or `anchor is ambiguous` and continue with the other edits. Never guess a location. End with a summary: `Logger.log('Done: X applied, Y skipped')`.
 
-- **Dry run**: include a `DRY_RUN` flag (default `true`) at the top of the script. When on, each edit function locates its anchor and logs `→ WOULD APPLY: <edit name>` without modifying the document. The user reads the log, flips the flag to `false`, and runs again. This is a stronger safety story than "test on a copy" for important documents.
+- **Dry run**: include a `DRY_RUN` flag (default `true`) at the top of the script. When on, each edit function locates its anchor and logs `→ WOULD APPLY: <edit name>` without modifying the document. No write, insert, delete, or `replaceText` in this mode. The user reads the log, flips the flag to `false`, and runs again.
 
 - **Structure**: one `applyEdits()` entry function; each edit in its own small named function (or clearly-commented block) whose name matches how you described the edit to the user. See `references/sample-skeleton.js` for a recommended starting template.
 
@@ -78,6 +80,8 @@ If the set of changes is high-risk, surface this explicitly to the user before w
 ## Caveats to tell the user (once)
 
 - First run shows Google's authorization screen — the script runs entirely as them, on their doc.
+- This skill does not grant Google access. Live reads depend on a host connector or user-provided text.
+- An edit adds a revision. The existing file stays the same artifact.
 - Apps Script can't delete tabs or edit comments; those stay manual.
 - Comments are preserved in untouched regions, but an edit that deletes or replaces the exact text a comment is anchored to will orphan that comment. Flag this when an edit overlaps a commented range.
 - Suggest running on a copy the first time if the doc is important.

package/skills/docupuncture-docs/references/sample-skeleton.js

@@ -1,12 +1,18 @@
 /**
  * DocuPuncture script skeleton (Docs)
  *
+ * Protocol for this sample:
+ * - DRY_RUN = true locates anchors and logs. It must not mutate.
+ * - A missing or ambiguous targeted anchor is logged and skipped. Do not guess.
+ * - Repeat-run for edit_AddIntroParagraph: skip when the new paragraph
+ *   text is already present. That skip is for this insert, not every script.
+ *
  * Usage:
  * 1. Open the target Google Doc → Extensions → Apps Script
  * 2. Replace all code with this script
  * 3. Click Run ▶ on applyEdits — with DRY_RUN = true it only logs what it
  *    WOULD change, without touching the document
- * 4. Read the Execution log; if it looks right, set DRY_RUN = false and run again
+ * 4. Read the Execution log. If it looks right, set DRY_RUN = false and run again
  * 5. Authorize on first run
  *
  * Each edit lives in its own named function so the log is human-readable
@@ -34,29 +40,22 @@ function applyEdits() {
 }
 
 /**
- * Example edit function.
- * Name it after the human description of the change.
- * Always idempotent, always fail loudly, always escape anchors.
+ * Showcased insert: add a paragraph after a unique section heading.
+ * Repeat-run: skip when "Welcome to the new section" is already present.
  */
 function edit_AddIntroParagraph(body) {
   const EDIT_NAME = 'AddIntroParagraph';
 
-  // 1. Check if the desired end state already exists (idempotency)
+  // 1. Check if the desired end state already exists (repeat-run for this insert)
   if (body.findText(escapeRegExp('Welcome to the new section'))) {
     Logger.log(`✓ SKIPPED (already present): ${EDIT_NAME}`);
     return false;
   }
 
-  // 2. Locate a robust anchor (primary + optional secondary).
-  //    Always route anchor literals through escapeRegExp — findText treats
-  //    its pattern as a regex, and a stray '(' or '?' silently breaks the match.
-  let range = body.findText(escapeRegExp('Section 2: Overview'));   // primary unique literal
-  if (!range) {
-    range = body.findText(escapeRegExp('Overview of the system'));  // secondary nearby context
-  }
-
-  if (!range) {
-    Logger.log(`✗ SKIPPED: ${EDIT_NAME} — anchor not found`);
+  // 2. Locate a unique anchor (primary, then nearby backup if the primary is missing).
+  const found = findUniqueText(body, 'Section 2: Overview', 'Overview of the system');
+  if (found.skipReason) {
+    Logger.log(`✗ SKIPPED: ${EDIT_NAME} — ${found.skipReason}`);
     return false;
   }
 
@@ -67,7 +66,7 @@ function edit_AddIntroParagraph(body) {
   }
 
   // 4. Perform the edit
-  const element = range.getElement();
+  const element = found.range.getElement();
   const parent = element.getParent();
   const idx = body.getChildIndex(parent);
 
@@ -80,6 +79,43 @@ function edit_AddIntroParagraph(body) {
   return true;
 }
 
+/**
+ * Find a unique literal. If `primary` is missing, try `secondary`.
+ * Ambiguous (more than one match) is a skip, not a first-match guess.
+ */
+function findUniqueText(body, primary, secondary) {
+  const primaryResult = uniqueFindText(body, primary);
+  if (primaryResult.status === 'unique') {
+    return { range: primaryResult.range };
+  }
+  if (primaryResult.status === 'ambiguous') {
+    return { skipReason: 'anchor is ambiguous' };
+  }
+  if (secondary) {
+    const secondaryResult = uniqueFindText(body, secondary);
+    if (secondaryResult.status === 'unique') {
+      return { range: secondaryResult.range };
+    }
+    if (secondaryResult.status === 'ambiguous') {
+      return { skipReason: 'anchor is ambiguous' };
+    }
+  }
+  return { skipReason: 'anchor not found' };
+}
+
+function uniqueFindText(body, literal) {
+  const escaped = escapeRegExp(literal);
+  const first = body.findText(escaped);
+  if (!first) {
+    return { status: 'missing' };
+  }
+  const second = body.findText(escaped, first);
+  if (second) {
+    return { status: 'ambiguous' };
+  }
+  return { status: 'unique', range: first };
+}
+
 /**
  * Helper: safely escape a string for use in findText / replaceText regex.
  * Use this on EVERY anchor literal — do not pass raw strings.

package/skills/docupuncture-sheets/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: docupuncture-sheets
-description: Precise in-place edits to an existing Google Sheet via paste-and-run Apps Script. Use when the user wants edits, tweaks, or iterations to a Google Sheet (or says "DocuPuncture" in a sheets context) — deliver a self-contained script that patches the live spreadsheet while preserving formatting, notes, data validation, and structure, instead of regenerating a new sheet.
+description: Precise in-place edits to an existing Google Sheet via paste-and-run Apps Script. Use when the user wants edits, tweaks, or iterations to a Google Sheet (or says "DocuPuncture" in a sheets context) — deliver a self-contained script that patches the live spreadsheet while preserving surrounding structure for supported edit types, instead of regenerating a new sheet.
 ---
 
 # DocuPuncture for Sheets
 
-DocuPuncture applied to Google Sheets: insert precise edits without changing the theme, format, comments, or history. Notes, data validation, charts, and structure stay too. Deliver edits as a self-contained Apps Script the user pastes into Extensions → Apps Script and runs.
+DocuPuncture writes a reviewable Apps Script that patches an existing Google Sheet in place. Surrounding structure is a design goal for supported edit types. An edit adds a revision. Notes, data validation, charts, and structure are designed to stay when you update values on existing cells. Deliver edits as a self-contained Apps Script the user pastes into Extensions → Apps Script and runs.
 
 Use the name "DocuPuncture" (or "DocuPuncture on this sheet") when referring to this workflow.
 
@@ -13,7 +13,7 @@ Use the name "DocuPuncture" (or "DocuPuncture on this sheet") when referring to
 
 Whenever the user asks for edits, tweaks, or iterations to an existing Google Sheet — especially repeated rounds — offer:
 
-1. **DocuPuncture: Apps Script patch** (recommended) — I generate a script; you run it once. Formatting, notes, and validation preserved.
+1. **DocuPuncture: Apps Script patch** (recommended) — I generate a script; you run it once. Formatting, notes, and validation stay on cells you do not rewrite.
 2. **New generated sheet** — full regeneration (warn: loses most formatting, notes, validation, charts).
 3. **Manual edit checklist** — exact values/ranges to change.
 
@@ -27,28 +27,30 @@ Skip the question if the user already said "DocuPuncture" or established the pre
 
 ## Workflow
 
-1. **Read the sheet first** (via available tools or user-provided ranges/values). Confirm the exact current state and the requested changes.
+1. **Identify the file and the exact current values.** Ask for the spreadsheet URL or ID and the intended changes. If the host already has a Drive connector, use it. Otherwise require the user to paste the relevant ranges or values. This skill does not grant Google access.
 2. **Write the script** and deliver it with clear run instructions:
    - Open the spreadsheet → Extensions → Apps Script
    - Paste the script, run `applyEdits`
    - Authorize on first run
-   - Check the Execution log for the summary
-3. **Verify** after the user runs it by re-checking key cells/ranges if possible.
+   - Check the Execution log. Keep `DRY_RUN = true` until that log matches the intended changes.
+3. **Verify** after the user runs it by re-checking key cells or ranges if a connector is available, or ask the user to confirm.
 
 ## Script rules
 
 - **Container-bound**: use `SpreadsheetApp.getActiveSpreadsheet()` (and `getActiveSheet()` or named sheets). Prefer this over `openById` for minimal friction.
-- **Anchors**: locate targets with `sheet.createTextFinder(text).findNext()` or by stable headers + relative offsets. Prefer unique header values or distinctive cell content as anchors. Escape regex when needed.
-- **Preserve formatting**: when updating values, prefer patterns that keep existing formatting (e.g. `setValue` on already-formatted cells, or capture/re-apply RichTextValue / `copyTo` with format options when necessary). Explicitly preserve notes and data validation where the edit should not touch them.
-- **Idempotent**: before changing a cell or range, check whether the desired end state already exists and skip if so. Re-running must never create duplicate rows or overwrite correct data unnecessarily.
-- **Fail loudly**: if an anchor/header is missing, log `✗ SKIPPED: <edit name> — anchor not found` and continue. Never invent row/column numbers.
-- **Dry run**: include a `DRY_RUN` flag (default `true`). When on, each edit locates its anchor and logs `→ WOULD APPLY` without writing anything. User reads the log, flips to `false`, runs again.
+- **Anchors**: locate targets with `sheet.createTextFinder(text).findNext()` or by stable headers + relative offsets. Prefer unique header values or distinctive cell content as anchors. Escape regex when needed. If a targeted edit's finder matches more than once, log `✗ SKIPPED: <edit name> — anchor is ambiguous` and skip. Do not take the first match.
+- **Preserve formatting**: when updating values, prefer patterns that keep existing formatting (e.g. `setValue` on already-formatted cells, or capture/re-apply RichTextValue / `copyTo` with format options when necessary). Explicitly preserve notes and data validation where the edit should not touch them. Notes and validation on a rewritten range are not guaranteed.
+- **Repeat-run (showcased cell update)**: before changing a cell, check whether the desired end state already exists and skip if so. The sample `edit_UpdateStatusColumn` skips when the status cell is already `Completed`. Do not claim that guarantee for every script.
+- **Fail loudly**: if an anchor or header is missing, or a targeted finder matches more than once, log `✗ SKIPPED` with `anchor not found` or `anchor is ambiguous` and continue. Never invent row or column numbers.
+- **Dry run**: include a `DRY_RUN` flag (default `true`). When on, each edit locates its anchor and logs `→ WOULD APPLY` without writing anything. No `setValue`, `setValues`, insert, or delete in this mode. User reads the log, flips to `false`, runs again.
 - **Structure**: one `applyEdits()` entry point. Each logical change in its own named function that returns success/failure. End with a clear `Logger.log` summary.
 - **Never** hardcode credentials.
 
 ## Caveats to tell the user (once)
 
 - First run shows Google’s authorization screen — the script runs as them.
+- This skill does not grant Google access. Live reads depend on a host connector or user-provided ranges.
+- An edit adds a revision. The existing spreadsheet stays the same artifact.
 - Complex formula dependencies can still break if the structural change is large; prefer small, targeted needles.
 - Suggest testing on a copy first if the sheet is critical.
 

package/skills/docupuncture-sheets/references/sample-skeleton.js

@@ -1,9 +1,15 @@
 /**
  * DocuPuncture for Sheets – sample skeleton
  *
+ * Protocol for this sample:
+ * - DRY_RUN = true locates anchors and logs. It must not mutate.
+ * - A missing or ambiguous targeted anchor is logged and skipped. Do not guess.
+ * - Repeat-run for edit_UpdateStatusColumn: skip when column E is already
+ *   Completed. That skip is for this cell update, not every script.
+ *
  * Paste into the target spreadsheet's Extensions → Apps Script, then run
- * applyEdits. With DRY_RUN = true it only logs what it WOULD change;
- * read the log, set DRY_RUN = false, and run again to apply.
+ * applyEdits. With DRY_RUN = true it only logs what it WOULD change.
+ * Read the log, set DRY_RUN = false, and run again to apply.
  */
 
 const DRY_RUN = true; // ← set to false to actually apply the edits
@@ -23,8 +29,8 @@ function applyEdits() {
 }
 
 /**
- * Example: find a row by unique key and update a specific column.
- * Returns true if applied (or would apply in dry run), false if skipped.
+ * Showcased update: find a unique key and set its status cell.
+ * Repeat-run: skip when that status cell is already Completed.
  */
 function edit_UpdateStatusColumn(sheet) {
   const EDIT_NAME = 'UpdateStatusColumn';
@@ -38,11 +44,15 @@ function edit_UpdateStatusColumn(sheet) {
     Logger.log(`✗ SKIPPED: ${EDIT_NAME} — anchor not found`);
     return false;
   }
+  if (finder.findNext()) {
+    Logger.log(`✗ SKIPPED: ${EDIT_NAME} — anchor is ambiguous`);
+    return false;
+  }
 
   const row = cell.getRow();
   const statusCell = sheet.getRange(row, 5); // column E for status, adjust as needed
 
-  // 2. Idempotency: skip if already correct
+  // 2. Repeat-run for this update: skip if already correct
   if (statusCell.getValue() === 'Completed') {
     Logger.log(`✓ SKIPPED (already present): ${EDIT_NAME}`);
     return false;
@@ -54,7 +64,7 @@ function edit_UpdateStatusColumn(sheet) {
     return true;
   }
 
-  // 4. Apply the change (formatting, notes, and validation on the cell stay intact)
+  // 4. Apply the change (formatting, notes, and validation on this cell stay)
   statusCell.setValue('Completed');
   Logger.log(`✓ APPLIED: ${EDIT_NAME} (row ${row})`);
   return true;

package/skills/docupuncture-slides/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: docupuncture-slides
-description: Precise in-place edits to an existing Google Slides presentation via paste-and-run Apps Script. Use when the user wants edits, tweaks, or iterations to a Google Slides deck (or says "DocuPuncture" in a slides context) — deliver a self-contained script that patches the live presentation while preserving layout, styles, and structure, instead of regenerating a new deck.
+description: Precise in-place edits to an existing Google Slides presentation via paste-and-run Apps Script. Use when the user wants edits, tweaks, or iterations to a Google Slides deck (or says "DocuPuncture" in a slides context) — deliver a self-contained script that patches the live presentation while preserving surrounding structure for supported edit types, instead of regenerating a new deck.
 ---
 
 # DocuPuncture for Slides
 
-DocuPuncture applied to Google Slides: insert precise edits without changing the theme, format, comments, or history. Layout and speaker notes stay too. Deliver edits as a self-contained Apps Script the user pastes into Extensions → Apps Script and runs.
+DocuPuncture writes a reviewable Apps Script that patches an existing Google Slides deck in place. Surrounding structure is a design goal for supported text edits. An edit adds a revision. Theme, speaker notes, and the layout of unmoved objects are designed to stay. Deliver edits as a self-contained Apps Script the user pastes into Extensions → Apps Script and runs.
 
 Use the name "DocuPuncture" (or "DocuPuncture on these slides") when referring to this workflow.
 
@@ -13,7 +13,7 @@ Use the name "DocuPuncture" (or "DocuPuncture on these slides") when referring t
 
 Whenever the user asks for edits, tweaks, or iterations to an existing Google Slides presentation — especially repeated rounds — offer:
 
-1. **DocuPuncture: Apps Script patch** (recommended for content/text changes) — I generate a script; you run it once. Layout and theme preserved.
+1. **DocuPuncture: Apps Script patch** (recommended for content/text changes) — I generate a script; you run it once. Theme and unmoved layout stay for supported text edits.
 2. **New generated deck** — full regeneration (warn: loses theme, precise positioning, speaker notes, etc.).
 3. **Manual edit checklist** — exact text or slide-by-slide changes.
 
@@ -27,22 +27,22 @@ Skip the question if the user already said "DocuPuncture" or established the pre
 
 ## Workflow
 
-1. **Read / understand the presentation first**. Confirm the exact current text content and the requested changes (slide numbers or unique text anchors help).
+1. **Identify the file and the exact current text.** Ask for the presentation URL or ID and the intended changes. If the host already has a Drive connector, use it. Otherwise require the user to paste the relevant slide text. This skill does not grant Google access.
 2. **Write the script** and deliver it with clear run instructions:
    - Open the presentation → Extensions → Apps Script
    - Paste the script, run `applyEdits`
    - Authorize on first run
-   - Check the Execution log
-3. **Verify** after the user runs it if possible.
+   - Check the Execution log. Keep `DRY_RUN = true` until that log matches the intended changes.
+3. **Verify** after the user runs it if a connector is available, or ask the user to confirm.
 
 ## Script rules
 
 - **Container-bound**: use `SlidesApp.getActivePresentation()`. Prefer this over opening by ID.
-- **Anchors**: locate shapes by their text content (`shape.getText().asString()` or `find`). Prefer unique or distinctive phrases that are unlikely to change. For multi-slide decks, iterate slides and search each page’s shapes.
+- **Anchors**: locate shapes by their text content (`shape.getText().asString()` or `find`). Prefer unique or distinctive phrases that are unlikely to change. For multi-slide decks, iterate slides and search each page’s shapes. If a single-shape edit matches more than one shape, log `✗ SKIPPED: <edit name> — anchor is ambiguous` and skip. Do not take the first match. `replaceAllText` may apply to every match when that is the requested operation.
 - **Text edits**: prefer `TextRange` methods. **Warning**: `getText().setText()` on a shape with mixed character styling (e.g. one bolded word, an inline color) flattens it to a single run. For shapes with mixed styling, prefer `replaceAllText` on the shape, or targeted insert/delete on the sub-`TextRange` around only the changed span, so untouched runs keep their styling. Full `setText` is fine only when the shape's text is uniformly styled.
-- **Idempotent**: check whether the target text or state already exists before changing it. Re-running must not duplicate shapes or text.
-- **Fail loudly**: if a text anchor / shape is not found, log `✗ SKIPPED: <edit name> — anchor not found` and continue. Never guess slide indices or object IDs.
-- **Dry run**: include a `DRY_RUN` flag (default `true`). When on, each edit locates its anchor/shape and logs `→ WOULD APPLY` without modifying the deck. User reads the log, flips to `false`, runs again.
+- **Repeat-run (showcased title update)**: check whether the target text already exists before changing it. The sample `edit_UpdateTitleOnSlide1` skips when the shape already has the new title. Do not claim that guarantee for every script.
+- **Fail loudly**: if a text anchor or shape is not found, or a single-shape edit matches more than one shape, log `✗ SKIPPED` with `anchor not found` or `anchor is ambiguous` and continue. Never guess slide indices or object IDs.
+- **Dry run**: include a `DRY_RUN` flag (default `true`). When on, each edit locates its anchor or shape and logs `→ WOULD APPLY` without modifying the deck. Do not call `replaceAllText` or `setText` in this mode. Count matches by hand instead. User reads the log, flips to `false`, runs again.
 - **Structure**: one `applyEdits()` entry point. Each logical change in its own named function. End with a clear summary log.
 - **Scope note**: v1 focuses on text content and simple shape text updates. Complex layout surgery (moving/resizing many objects) is higher risk and should be flagged.
 - **Never** hardcode credentials.
@@ -50,6 +50,8 @@ Skip the question if the user already said "DocuPuncture" or established the pre
 ## Caveats to tell the user (once)
 
 - First run shows Google’s authorization screen — the script runs as them.
+- This skill does not grant Google access. Live reads depend on a host connector or user-provided text.
+- An edit adds a revision. The existing deck stays the same artifact.
 - Heavy layout changes are more fragile than pure text edits; prefer content-focused needles.
 - Suggest testing on a copy first if the presentation is important.
 

package/skills/docupuncture-slides/references/sample-skeleton.js

@@ -1,9 +1,18 @@
 /**
  * DocuPuncture for Slides – sample skeleton
  *
+ * Protocol for this sample:
+ * - DRY_RUN = true locates anchors and logs. It must not mutate.
+ * - A missing or ambiguous single-shape anchor is logged and skipped.
+ *   Do not guess a slide index or object ID.
+ * - Repeat-run for edit_UpdateTitleOnSlide1: skip when the shape already
+ *   has the new title. That skip is for this title update, not every script.
+ * - replaceAllText is a different operation. Multiple matches are intended.
+ *   Do not call it during a dry run. Count matches by hand instead.
+ *
  * Paste into the target presentation's Extensions → Apps Script, then run
- * applyEdits. With DRY_RUN = true it only logs what it WOULD change;
- * read the log, set DRY_RUN = false, and run again to apply.
+ * applyEdits. With DRY_RUN = true it only logs what it WOULD change.
+ * Read the log, set DRY_RUN = false, and run again to apply.
  */
 
 const DRY_RUN = true; // ← set to false to actually apply the edits
@@ -23,7 +32,8 @@ function applyEdits() {
 }
 
 /**
- * Example: find a shape containing specific text and update it.
+ * Showcased title update: one unique shape, then set its text.
+ * Repeat-run: skip when the shape already says New Title Text.
  *
  * Styling note: getText().setText() flattens mixed character styling
  * (e.g. one bolded word) to a single run. It is safe here only because
@@ -36,21 +46,25 @@ function edit_UpdateTitleOnSlide1(slides) {
   const targetSlide = slides[0]; // or find by content
 
   const shapes = targetSlide.getShapes();
-  let targetShape = null;
+  const matches = [];
 
   for (let i = 0; i < shapes.length; i++) {
     const text = shapes[i].getText().asString().trim();
     if (text.indexOf('Old Title Text') !== -1) {
-      targetShape = shapes[i];
-      break;
+      matches.push(shapes[i]);
     }
   }
 
-  if (!targetShape) {
+  if (matches.length === 0) {
     Logger.log(`✗ SKIPPED: ${EDIT_NAME} — anchor not found`);
     return false;
   }
+  if (matches.length > 1) {
+    Logger.log(`✗ SKIPPED: ${EDIT_NAME} — anchor is ambiguous`);
+    return false;
+  }
 
+  const targetShape = matches[0];
   const current = targetShape.getText().asString().trim();
   if (current === 'New Title Text') {
     Logger.log(`✓ SKIPPED (already present): ${EDIT_NAME}`);
@@ -72,7 +86,8 @@ function edit_UpdateTitleOnSlide1(slides) {
  * replaceAllText preserves each match's run styling, so it is the
  * preferred tool for text swaps inside shapes with mixed styling.
  *
- * Note: replaceAllText has no read-only mode, so in a dry run we count
+ * Multiple matches are the operation here, not an ambiguity.
+ * replaceAllText has no read-only mode, so in a dry run we count
  * matches manually instead of calling it.
  */
 function edit_ReplacePlaceholderAcrossDeck(presentation) {