docupuncture 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Catalyst Forge LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# Docupuncture
+
+Treat the document you already have.
+
+Insert precise edits without changing the theme, format, comments, or history.
+
+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.
+
+## The skills
+
+Copy a folder into Cursor, Claude Code, or anything else that reads `SKILL.md`. When someone asks for edits to an existing Workspace file, the agent writes a script instead of a new document.
+
+| 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-slides`](skills/docupuncture-slides/SKILL.md) | Google Slides | Text and content. Layout surgery is higher risk. |
+
+## Install
+
+```bash
+pnpm add docupuncture
+```
+
+Copy one folder from `node_modules/docupuncture/skills/` into the agent's skills directory.
+
+```bash
+git clone https://github.com/Catalyst-Forge-LLC/docupuncture.git
+# then copy skills/docupuncture-docs/  (or -sheets / -slides)
+```
+
+Site: [docupuncture.com](https://docupuncture.com)
+
+## 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.
+
+The script is safe to re-run. Missing anchors are logged. It never invents a location.
+
+## Why the name
+
+The other tools in the shop strike, press, or contain. A needle is still metal from the same fire, but you don't swing it. You place it.
+
+Acupuncture treats a living body in place: insert at a point, leave the rest alone. Docupuncture does that to a document you already care about.
+
+Closest cousin on the shelf is [TemperPass](https://temperpass.dev): a rule set you point an agent at.
+
+## License
+
+MIT. Built by [Catalyst Forge LLC](https://www.catalystforge.com).

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "docupuncture",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Insert precise edits without changing the theme, format, comments, or history.",
+  "license": "MIT",
+  "author": "Catalyst Forge LLC",
+  "keywords": [
+    "ai",
+    "agents",
+    "skills",
+    "cursor",
+    "claude",
+    "google-docs",
+    "google-sheets",
+    "google-slides",
+    "apps-script"
+  ],
+  "homepage": "https://docupuncture.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Catalyst-Forge-LLC/docupuncture.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Catalyst-Forge-LLC/docupuncture/issues"
+  },
+  "exports": {
+    "./skills/*": "./skills/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "site:dev": "pnpm --dir site dev",
+    "site:build": "pnpm --dir site run build",
+    "site:check": "pnpm --dir site check",
+    "site:preview": "pnpm --dir site preview",
+    "ship": "pnpm --dir site run ship"
+  }
+}

package/skills/docupuncture-docs/SKILL.md

@@ -0,0 +1,84 @@
+---
+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).
+---
+
+# Docupuncture for Docs
+
+Docupuncture = insert precise edits without changing the theme, format, comments, or history. 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.
+
+
+## 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.
+2. **New generated doc** — full regeneration (warn: loses theme/logo/comments).
+3. **Manual edit checklist** — exact paste-ready text.
+
+Skip the question and go straight to the script if the user says "docupuncture" or has already established this preference in the conversation.
+
+### Edit volume / risk guidance
+
+Before generating the script, quickly assess the size and nature of the requested changes:
+
+- **Low risk** (1–5 discrete edits, mostly text swaps or simple inserts/deletes): proceed with pure docupuncture.
+- **Medium risk** (6–10 edits or light structural work): still prefer docupuncture, but warn the user that a fresh re-read of the doc is required if they make manual changes between runs, and consider splitting into two smaller scripts if the anchors feel fragile.
+- **High risk** (>10 discrete edits, major restructuring, multi-section moves, or many interdependent changes): strongly recommend breaking into multiple sequential docupuncture rounds, or switching to a full regeneration / hybrid approach. Do not force a single massive script.
+
+If the set of changes is high-risk, surface this explicitly to the user before writing the script.
+
+## 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.
+
+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
+
+3. **Verify** after the user says they ran it: re-read the doc via MCP and confirm every edit landed.
+
+## Script rules
+
+- **Container-bound**: use `DocumentApp.getActiveDocument()` (opened from the doc's own Script editor) — minimal auth friction. Do not use `openById` unless the user wants a standalone script.
+
+- **Tabs**: if the doc has tabs, select the right one: `doc.getTabs()[i].asDocumentTab().getBody()`. Plain `doc.getBody()` only for untabbed docs. Prefer a small helper that iterates all tabs (and child tabs) and searches each body when the target tab is not known with certainty. Apps Script cannot delete tabs — flag tab deletion as a manual step.
+
+- **Anchors (critical)**: locate insertion / edit points with `body.findText(pattern)`.
+  - 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.
+
+- **Inserting paragraphs**: `body.getChildIndex(anchorElement.getParent())` then `body.insertParagraph(idx + 1, text)`. Copy formatting from a sibling: `newPara.setAttributes(sibling.getAttributes())`.
+
+- **Bullets**: use `body.insertListItem(idx, text)` and inherit list formatting: `.setListId(siblingListItem).setNestingLevel(siblingListItem.getNestingLevel()).setGlyphType(siblingListItem.getGlyphType())`, plus `setAttributes` from the sibling.
+
+- **Deleting elements**: find the anchor, walk up to the containing `LIST_ITEM` or `PARAGRAPH`, then `removeFromParent()`.
+
+- **Partial bolding / styling spans**: after inserting, use `para.editAsText().setBold(startOffset, endOffset, true)` (or other style methods) with carefully computed offsets.
+
+- **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.
+
+- **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')`.
+
+- **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.
+
+- **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.
+
+- **Never** hardcode credentials or API keys in the script.
+
+## Caveats to tell the user (once)
+
+- First run shows Google's authorization screen — the script runs entirely as them, on their doc.
+- 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.
+- After several iterative rounds, anchors can drift if the surrounding text has changed. A fresh read of the current document is always recommended before generating the next script.

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

@@ -0,0 +1,110 @@
+/**
+ * Docupuncture script skeleton (Docs)
+ *
+ * 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
+ * 5. Authorize on first run
+ *
+ * Each edit lives in its own named function so the log is human-readable
+ * and individual edits can be skipped or re-run safely.
+ */
+
+const DRY_RUN = true; // ← set to false to actually apply the edits
+
+function applyEdits() {
+  const doc = DocumentApp.getActiveDocument();
+  // Prefer the correct tab body when the document uses tabs
+  const body = getBodyForTab(doc /*, 'Preferred Tab Name' */);
+
+  let applied = 0;
+  let skipped = 0;
+
+  // ---- Individual edits ----
+  // Each named function returns true (applied / would apply) or false (skipped)
+  if (edit_AddIntroParagraph(body)) applied++; else skipped++;
+  // if (edit_UpdatePricingTable(body)) applied++; else skipped++;
+  // ... add more here
+
+  const mode = DRY_RUN ? 'DRY RUN — no changes made' : 'LIVE';
+  Logger.log(`Done (${mode}): ${applied} ${DRY_RUN ? 'would apply' : 'applied'}, ${skipped} skipped`);
+}
+
+/**
+ * Example edit function.
+ * Name it after the human description of the change.
+ * Always idempotent, always fail loudly, always escape anchors.
+ */
+function edit_AddIntroParagraph(body) {
+  const EDIT_NAME = 'AddIntroParagraph';
+
+  // 1. Check if the desired end state already exists (idempotency)
+  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`);
+    return false;
+  }
+
+  // 3. Dry run: report and stop before modifying anything
+  if (DRY_RUN) {
+    Logger.log(`→ WOULD APPLY: ${EDIT_NAME} (anchor found)`);
+    return true;
+  }
+
+  // 4. Perform the edit
+  const element = range.getElement();
+  const parent = element.getParent();
+  const idx = body.getChildIndex(parent);
+
+  const newPara = body.insertParagraph(idx + 1, 'Welcome to the new section. This is the injected content.');
+
+  // Optional: copy attributes from a sibling for consistent formatting
+  // newPara.setAttributes(parent.getAttributes());
+
+  Logger.log(`✓ APPLIED: ${EDIT_NAME}`);
+  return true;
+}
+
+/**
+ * Helper: safely escape a string for use in findText / replaceText regex.
+ * Use this on EVERY anchor literal — do not pass raw strings.
+ */
+function escapeRegExp(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Optional robust tab helper (use when the document may have tabs)
+ */
+function getBodyForTab(doc, preferredTabName) {
+  const tabs = doc.getTabs();
+  if (!tabs || tabs.length === 0) {
+    return doc.getBody();
+  }
+
+  // Prefer matching by name if provided
+  for (let i = 0; i < tabs.length; i++) {
+    const tab = tabs[i];
+    if (preferredTabName && tab.getTitle() === preferredTabName) {
+      return tab.asDocumentTab().getBody();
+    }
+  }
+
+  // Fallback: first tab (or implement recursive child-tab search if needed)
+  return tabs[0].asDocumentTab().getBody();
+}

package/skills/docupuncture-sheets/SKILL.md

@@ -0,0 +1,55 @@
+---
+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.
+---
+
+# 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.
+
+Use the name "docupuncture" (or "docupuncture on this sheet") when referring to this workflow.
+
+## When to offer
+
+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.
+2. **New generated sheet** — full regeneration (warn: loses most formatting, notes, validation, charts).
+3. **Manual edit checklist** — exact values/ranges to change.
+
+Skip the question if the user already said "docupuncture" or established the preference.
+
+### Edit volume / risk guidance
+
+- **Low risk** (1–6 discrete cell/range updates): pure docupuncture.
+- **Medium risk** (7–12 updates or light structural work such as inserting a few rows): still preferred, but warn about anchor drift.
+- **High risk** (large structural changes, many interdependent formulas, or wholesale table rewrites): recommend sequential smaller scripts or full regeneration.
+
+## Workflow
+
+1. **Read the sheet first** (via available tools or user-provided ranges/values). Confirm the exact current state and the requested changes.
+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.
+
+## 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.
+- **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.
+- 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.
+
+See `references/sample-skeleton.js` for a recommended starting template.

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

@@ -0,0 +1,69 @@
+/**
+ * Docupuncture for Sheets – sample skeleton
+ *
+ * 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.
+ */
+
+const DRY_RUN = true; // ← set to false to actually apply the edits
+
+function applyEdits() {
+  const ss = SpreadsheetApp.getActiveSpreadsheet();
+  const sheet = ss.getActiveSheet(); // or ss.getSheetByName('Specific Name')
+
+  let applied = 0;
+  let skipped = 0;
+
+  if (edit_UpdateStatusColumn(sheet)) applied++; else skipped++;
+  // if (edit_AddNewRowForItem(sheet)) applied++; else skipped++;
+
+  const mode = DRY_RUN ? 'DRY RUN — no changes made' : 'LIVE';
+  Logger.log(`Done (${mode}): ${applied} ${DRY_RUN ? 'would apply' : 'applied'}, ${skipped} skipped`);
+}
+
+/**
+ * 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.
+ */
+function edit_UpdateStatusColumn(sheet) {
+  const EDIT_NAME = 'UpdateStatusColumn';
+
+  // 1. Locate the row via a unique anchor value.
+  //    matchEntireCell(true) keeps plain-text matching safe; if you switch
+  //    to useRegularExpression(true), escape the anchor with escapeRegExp.
+  const finder = sheet.createTextFinder('PROJECT-1234').matchEntireCell(true);
+  const cell = finder.findNext();
+  if (!cell) {
+    Logger.log(`✗ SKIPPED: ${EDIT_NAME} — anchor not found`);
+    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
+  if (statusCell.getValue() === 'Completed') {
+    Logger.log(`✓ SKIPPED (already present): ${EDIT_NAME}`);
+    return false;
+  }
+
+  // 3. Dry run: report and stop before writing anything
+  if (DRY_RUN) {
+    Logger.log(`→ WOULD APPLY: ${EDIT_NAME} (row ${row}, col 5 → 'Completed')`);
+    return true;
+  }
+
+  // 4. Apply the change (formatting, notes, and validation on the cell stay intact)
+  statusCell.setValue('Completed');
+  Logger.log(`✓ APPLIED: ${EDIT_NAME} (row ${row})`);
+  return true;
+}
+
+/**
+ * Helper – escape a string for TextFinder in regex mode / RegExp use.
+ * Route every anchor through this whenever regex matching is enabled.
+ */
+function escapeRegExp(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/skills/docupuncture-slides/SKILL.md

@@ -0,0 +1,56 @@
+---
+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.
+---
+
+# 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.
+
+Use the name "docupuncture" (or "docupuncture on these slides") when referring to this workflow.
+
+## When to offer
+
+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.
+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.
+
+Skip the question if the user already said "docupuncture" or established the preference.
+
+### Edit volume / risk guidance
+
+- **Low risk** (1–6 text replacements or simple content updates on existing shapes): pure docupuncture.
+- **Medium risk** (7–12 changes or light additions of text boxes): still preferred.
+- **High risk** (major layout restructuring, many new slides, complex object insertion/repositioning): recommend sequential smaller scripts or full regeneration. Positioning is fragile.
+
+## Workflow
+
+1. **Read / understand the presentation first**. Confirm the exact current text content and the requested changes (slide numbers or unique text anchors help).
+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.
+
+## 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.
+- **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.
+- **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.
+
+## Caveats to tell the user (once)
+
+- First run shows Google’s authorization screen — the script runs as them.
+- 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.
+
+See `references/sample-skeleton.js` for a recommended starting template.

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

@@ -0,0 +1,103 @@
+/**
+ * Docupuncture for Slides – sample skeleton
+ *
+ * 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.
+ */
+
+const DRY_RUN = true; // ← set to false to actually apply the edits
+
+function applyEdits() {
+  const presentation = SlidesApp.getActivePresentation();
+  const slides = presentation.getSlides();
+
+  let applied = 0;
+  let skipped = 0;
+
+  if (edit_UpdateTitleOnSlide1(slides)) applied++; else skipped++;
+  // if (edit_ReplacePlaceholderAcrossDeck(presentation)) applied++; else skipped++;
+
+  const mode = DRY_RUN ? 'DRY RUN — no changes made' : 'LIVE';
+  Logger.log(`Done (${mode}): ${applied} ${DRY_RUN ? 'would apply' : 'applied'}, ${skipped} skipped`);
+}
+
+/**
+ * Example: find a shape containing specific text and update it.
+ *
+ * Styling note: getText().setText() flattens mixed character styling
+ * (e.g. one bolded word) to a single run. It is safe here only because
+ * the whole title is being replaced and titles are usually uniformly
+ * styled. For partial edits inside a shape with mixed styling, operate
+ * on a sub-TextRange around just the changed span instead.
+ */
+function edit_UpdateTitleOnSlide1(slides) {
+  const EDIT_NAME = 'UpdateTitleOnSlide1';
+  const targetSlide = slides[0]; // or find by content
+
+  const shapes = targetSlide.getShapes();
+  let targetShape = null;
+
+  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;
+    }
+  }
+
+  if (!targetShape) {
+    Logger.log(`✗ SKIPPED: ${EDIT_NAME} — anchor not found`);
+    return false;
+  }
+
+  const current = targetShape.getText().asString().trim();
+  if (current === 'New Title Text') {
+    Logger.log(`✓ SKIPPED (already present): ${EDIT_NAME}`);
+    return false;
+  }
+
+  if (DRY_RUN) {
+    Logger.log(`→ WOULD APPLY: ${EDIT_NAME} ('${current}' → 'New Title Text')`);
+    return true;
+  }
+
+  targetShape.getText().setText('New Title Text');
+  Logger.log(`✓ APPLIED: ${EDIT_NAME}`);
+  return true;
+}
+
+/**
+ * Example: replace text across the whole presentation.
+ * 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
+ * matches manually instead of calling it.
+ */
+function edit_ReplacePlaceholderAcrossDeck(presentation) {
+  const EDIT_NAME = 'ReplacePlaceholderAcrossDeck';
+
+  if (DRY_RUN) {
+    let matches = 0;
+    presentation.getSlides().forEach(function (slide) {
+      slide.getShapes().forEach(function (shape) {
+        matches += shape.getText().asString().split('{{CLIENT_NAME}}').length - 1;
+      });
+    });
+    if (matches === 0) {
+      Logger.log(`✗ SKIPPED: ${EDIT_NAME} — no matches found`);
+      return false;
+    }
+    Logger.log(`→ WOULD APPLY: ${EDIT_NAME} (${matches} replacements)`);
+    return true;
+  }
+
+  const count = presentation.replaceAllText('{{CLIENT_NAME}}', 'Acme Corp');
+  if (count === 0) {
+    Logger.log(`✗ SKIPPED: ${EDIT_NAME} — no matches found`);
+    return false;
+  }
+  Logger.log(`✓ APPLIED: ${EDIT_NAME} (${count} replacements)`);
+  return true;
+}