slides-mcp 0.2.0__tar.gz

slides_mcp-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,129 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          python-version: '3.12'
+
+      - name: Verify tag matches pyproject.toml version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Tag ($TAG_VERSION) != pyproject.toml ($PKG_VERSION). Bump pyproject.toml before tagging."
+            exit 1
+          fi
+
+      - name: Install deps
+        run: uv sync --frozen
+
+      - name: Run tests
+        run: uv run pytest tests/unit/ -q
+
+      - name: Ruff lint
+        run: uv run ruff check src/ tests/
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Upload dist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  release:
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Generate categorized release notes from conventional commits
+        run: |
+          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
+          TAG="${{ github.ref_name }}"
+          {
+            if [ -z "$PREV_TAG" ]; then
+              echo "🎉 Initial release"
+              echo ""
+              echo "**Full Changelog**: https://github.com/${{ github.repository }}/commits/${TAG}"
+            else
+              echo "## What's Changed"
+              echo ""
+              for prefix_label in "feat:✨ Features" "fix:🐛 Bug Fixes" "perf:⚡ Performance" "docs:📖 Documentation"; do
+                prefix="${prefix_label%%:*}"
+                label="${prefix_label#*:}"
+                items=$(git log "$PREV_TAG..$TAG" --format="- %s (%h)" --grep="^${prefix}" 2>/dev/null || true)
+                if [ -n "$items" ]; then
+                  echo "### $label"
+                  echo "$items"
+                  echo ""
+                fi
+              done
+              uncategorized=$(git log "$PREV_TAG..$TAG" --format="- %s (%h)" \
+                --invert-grep --grep="^feat" --grep="^fix" --grep="^perf" --grep="^docs" 2>/dev/null || true)
+              if [ -n "$uncategorized" ]; then
+                echo "### 🔧 Other Changes"
+                echo "$uncategorized"
+                echo ""
+              fi
+              echo "### 📊 Diff Summary"
+              echo '```'
+              git diff --stat "$PREV_TAG..$TAG" | tail -1
+              echo '```'
+              echo ""
+              echo "**Full Changelog**: https://github.com/${{ github.repository }}/compare/${PREV_TAG}...${TAG}"
+            fi
+          } > /tmp/release-body.md
+          cat /tmp/release-body.md
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "${{ github.ref_name }}" \
+            --title "${{ github.ref_name }}" \
+            --notes-file /tmp/release-body.md \
+            dist/*
+
+  # PyPI publish via OIDC Trusted Publisher (Pending Publisher registered on pypi.org).
+  publish:
+    runs-on: ubuntu-latest
+    needs: [build, release]
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI (OIDC Trusted Publisher)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

slides_mcp-0.2.0/.gitignore

@@ -0,0 +1,34 @@
+# Privacy-sensitive (NEVER ship)
+.claude/
+gsd-lite/
+samples/
+
+# Secrets
+token.json
+client_secret*.json
+credentials*.json
+*.env
+.env
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+.venv-*/
+*.egg-info/
+dist/
+build/
+
+# Tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Editor
+.vscode/
+.idea/
+*.swp
+.DS_Store

slides_mcp-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12

slides_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The slides-mcp contributors
+
+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 OUTSIDE OF THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

slides_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: slides-mcp
+Version: 0.2.0
+Summary: Google Slides MCP server with compact YAML DSL and brand-theme enforcement
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: google-api-python-client>=2.140
+Requires-Dist: google-auth-httplib2>=0.2
+Requires-Dist: google-auth-oauthlib>=1.2
+Requires-Dist: google-auth>=2.34
+Requires-Dist: mcp[cli]>=1.2.0
+Requires-Dist: pydantic>=2.8
+Requires-Dist: pyyaml>=6.0

slides_mcp-0.2.0/README.md

@@ -0,0 +1,140 @@
+# slides-mcp
+
+An MCP server that lets Claude (and other agents) edit Google Slides through a compact YAML DSL. Built for multi-hundred-turn editing sessions without token bloat, with first-class brand-theme enforcement, presenter-note support, and a true bidirectional agent loop — the agent can **see** the rendered slide (native `ImageContent`) AND **move** shapes (coordinate-level writes) in the same session.
+
+## Why this exists
+
+Existing Google Slides MCP servers are thin JSON passthroughs over the Slides REST API. A single text edit costs ~2,000 tokens (1K to read + 1K to write), and a rendered slide costs another round-trip. That math kills 100-turn editing sessions.
+
+This server projects each slide into ~100–150 tokens of structured YAML, keyed to a small vocabulary of **archetypes** (layout templates) and a **theme** (palette + fonts). Writes produce the updated DSL and (for geometry changes) a rendered thumbnail in a single call. Thumbnails return as native MCP `ImageContent` — no URL-fetch round-trip.
+
+## Core ideas
+
+- **Archetypes over layouts.** PowerPoint/Slides layout names are unreliable (one real deck used `CUSTOM_7_1_1_1_1_1_1_1_1_1_1_1_1_1_1_1` as the name for 11 structurally-different slides). The classifier reasons about element topology — column counts, separator lines, picture-to-text ratios — not layout strings.
+- **Theme roles, not hex codes.** A slide references `palette.brand_accent`, not `#3366CC`. Change the theme once; the deck follows. Drift (hex values not in the theme) is surfaced by `audit_deck_colors` and can be accepted via `promote_to_theme`.
+- **Presenter notes are first-class.** Read path preserves the full notes body on every slide (no truncation). Write-side emission is landing incrementally — current state is *detected and flagged* on diff; explicit emission is the next small task.
+- **Bidi geometry.** Opt-in `include_elements=True` on `get_slide` returns `elements: [{id, at:[x,y,w,h]}]`. Editing those values produces `updatePageElementTransform` requests in `RELATIVE` mode, preserving scale and rotation on the underlying shape.
+- **Privacy boundary.** Bundled theme + archetypes are generic. Your real brand theme lives in `~/.config/slides-mcp/themes/` and never enters the repo. Research artifacts, session state, and real client decks stay in local-only directories that are in `.gitignore`.
+
+## What the MVP does
+
+- Read a deck outline (1 call, whole deck, ~40 tok/slide) — `get_deck_outline`
+- Read one slide as compact YAML (~100–150 tok typical) — `get_slide`
+- Search a deck for text substrings — `search_deck`
+- Patch a slide (text edits + translation of existing elements) in one call — `patch_slide`
+- Render a slide as native `ImageContent` for visual verification — `render_thumbnail`
+- Audit every color and font in the deck against the active theme — `audit_deck_colors`
+- Promote a drift value to the theme as a named role — `promote_to_theme`
+- Copy a deck via Drive — `clone_deck`
+- List themes / archetypes / deck archetype inventory — `list_themes`, `list_archetypes`, `list_deck_layouts`
+- Diagnostic: `auth_status`
+
+## What the MVP does NOT do (yet)
+
+By design, the current scope is tightly scoped to "edit an existing brownfield deck." The following are deliberately deferred — if you need them, watch the roadmap issues:
+
+- **Creating slides from scratch** (no `distill_doc_to_deck`, no `create_from_markdown`)
+- **Inserting new shapes or icons** via DSL (moving existing elements works; creating new ones doesn't)
+- **Resizing / rotating** elements (warn-only in diff; translation-only writes in MVP)
+- **Archetype swap** ("relayout this slide to 3 columns" is a Phase 2 primitive)
+- **Template replacement map** (`clone_deck` copies only; per-slide text replacements are multiple calls today)
+- **Writing presenter notes** (reads work; write emission is a known ~15-line follow-up)
+- **Slide variant ideation** ("give me 3 alternative versions of this slide")
+- **`.pptx` target** (Google Slides only in this version)
+
+## Status
+
+MVP shipped. 13 MCP tools, 45 unit tests, live-verified bidi loop on real decks (read → edit → render → move → re-render, all in token budget). Still pre-v1: no public releases cut, no committed production users, tests cover the core layers but integration tests against live decks are empty. Use at your own risk and expect rough edges — especially on the text-edit side where `replaceAllText` is currently slide-scoped.
+
+## Installation
+
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/YOUR-USER/slides-mcp.git
+cd slides-mcp
+uv sync
+```
+
+## Auth setup (one-time)
+
+The MCP uses user-OAuth to access Google Slides. You need a Google Cloud project with the Slides + Drive APIs enabled and a desktop OAuth client.
+
+1. Create a Google Cloud project; enable `slides.googleapis.com` and `drive.googleapis.com`
+2. Create an OAuth 2.0 client (type: **Desktop app**), download `client_secret.json`
+3. On any machine with a browser, run:
+
+    ```bash
+    uv run slides-mcp-auth --client-secret /path/to/client_secret.json --out ./token.json
+    ```
+
+    This opens a browser, you consent, and `token.json` is written. The refresh token inside is long-lived.
+
+4. If your MCP server runs on a headless host (devcontainer, VPS), copy `token.json` over, e.g. `scp token.json user@devbox:~/.config/slides-mcp/token.json`. Point the server at it via `$SLIDES_MCP_TOKEN_PATH`.
+
+## MCP client configuration
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "slides": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/slides-mcp", "slides-mcp"],
+      "env": {
+        "SLIDES_MCP_TOKEN_PATH": "/path/to/token.json",
+        "SLIDES_MCP_THEMES_DIR": "/path/to/your/private/themes"
+      }
+    }
+  }
+}
+```
+
+## Theme setup
+
+The bundled theme at `src/slides_mcp/themes/example.yaml` is a generic placeholder. For your real brand, drop a theme file into one of these locations (first match wins):
+
+1. `$SLIDES_MCP_THEMES_DIR`
+2. `$XDG_CONFIG_HOME/slides-mcp/themes` (default: `~/.config/slides-mcp/themes`)
+3. `./slides-mcp-themes` (project-local; add it to your own `.gitignore`)
+4. Bundled `example.yaml` (fallback only)
+
+Theme files are never committed to this repo. See `src/slides_mcp/themes/example.yaml` for the schema.
+
+## MCP tool reference
+
+| Tool | Purpose |
+|------|---------|
+| `list_themes()` | All theme files discoverable in the search paths |
+| `list_archetypes()` | Archetype templates (bundled + any user overrides) |
+| `list_deck_layouts(deck_url)` | Archetype inventory of a deck, with counts and slide IDs |
+| `get_deck_outline(deck_url, theme?, sub_theme?)` | Compact index of all slides — one call for whole-deck reasoning |
+| `get_slide(deck_url, slide_id, theme?, sub_theme?, mode?, include_elements?)` | Single slide as YAML; `mode='faithful'` preserves raw geometry; `include_elements=True` opts in to the geometry channel |
+| `search_deck(deck_url, query)` | Find slides whose text contains `query` |
+| `patch_slide(deck_url, slide_id, new_dsl_yaml, theme?, sub_theme?, verify?)` | Apply a DSL patch (text + element translation). Returns new YAML + auto-thumbnail when geometry changed |
+| `render_thumbnail(deck_url, slide_id, size?)` | Rendered PNG as native MCP `ImageContent` |
+| `render_thumbnail_url(deck_url, slide_id, size?)` | Same, but returns a URL (for non-agent callers) |
+| `audit_deck_colors(deck_url, theme?, sub_theme?)` | Report colors and fonts not in the active theme, with nearest-role suggestions |
+| `promote_to_theme(theme, sub_theme, role_name, kind, value)` | Add a drift value (color hex or font spec) to the user theme file under a named role |
+| `clone_deck(src_url, new_title)` | Copy a deck via Drive; returns new deck ID + URL |
+| `auth_status()` | Diagnostic — token path, scopes, expiry (no secrets) |
+
+## Architecture
+
+A four-layer design:
+
+1. **Google Slides + auth** — REST wrapper with FieldMask-projected GETs + `batchUpdate`; token.json load + silent refresh
+2. **DSL projection + diff** — `pageElement` → `FlatShape` → archetype classifier (topology-based) → compact YAML; YAML diff → `batchUpdate` requests
+3. **Theme + archetype registry** — YAML-driven, user-overridable
+4. **FastMCP tool surface** — 13 tools over stdio
+
+See `src/slides_mcp/server.py` for the tool definitions and `src/slides_mcp/projection.py` for the compression core.
+
+## Contributing
+
+Early project. Issues welcome. PRs should include tests — the unit suite runs `pytest tests/unit/` in under a second and uses mocked Slides API JSON fixtures (no network).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

slides_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "slides-mcp"
+version = "0.2.0"
+description = "Google Slides MCP server with compact YAML DSL and brand-theme enforcement"
+requires-python = ">=3.11"
+dependencies = [
+    "mcp[cli]>=1.2.0",
+    "google-api-python-client>=2.140",
+    "google-auth>=2.34",
+    "google-auth-oauthlib>=1.2",
+    "google-auth-httplib2>=0.2",
+    "pyyaml>=6.0",
+    "pydantic>=2.8",
+]
+
+[project.scripts]
+slides-mcp = "slides_mcp.cli:main"
+slides-mcp-auth = "slides_mcp.bootstrap:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/slides_mcp"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"skills" = "slides_mcp/_skills_data"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "python-pptx>=1.0",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP", "B"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+asyncio_mode = "auto"

slides_mcp-0.2.0/releases/v0.2.0.md

@@ -0,0 +1,64 @@
+# v0.2.0 — Skill package: `uvx slides-mcp install`
+
+This release adds a **Claude Code skill** describing how to use slides-mcp's 17 tools effectively, and the **`uvx slides-mcp install`** command to drop it into any project (or your user-level skills directory).
+
+## The story
+
+slides-mcp v0.1.1 shipped 17 tools across a 4-layer architecture (auth → DSL → theme → MCP surface). What it didn't ship: *how to USE those tools effectively.* Tool descriptions alone don't cover:
+
+- Which tool to reach for first (bespoke beats escape-hatch; `patch_slide` beats hand-rolled `batchUpdate`)
+- When to flip the opt-in `include_elements` geometry channel
+- How to navigate clean / faithful / `_object_ids` read modes
+- The audit → promote-OR-fix theme-hygiene loop
+- `exec_batch_update` dry-run discipline
+
+v0.2.0 packages all of that as a Claude Code skill: one `SKILL.md` + six `rules/*.md` files, installed via:
+
+```bash
+uvx slides-mcp install              # $CWD/.claude/skills/slides-mcp/
+uvx slides-mcp install --global     # ~/.claude/skills/slides-mcp/
+uvx slides-mcp install --path /custom/dir
+```
+
+## New CLI surface
+
+`slides-mcp` is now a subcommand dispatcher:
+
+| Invocation | Effect |
+|------------|--------|
+| `slides-mcp` (no args) | Start the MCP stdio server (unchanged behavior for MCP clients) |
+| `slides-mcp install` | Install the skill docs (NEW) |
+| `slides-mcp auth ...` | Run OAuth consent (moved under the dispatcher; back-compat `slides-mcp-auth` entry preserved) |
+
+The previous `slides-mcp = "slides_mcp.server:main"` script is now `slides-mcp = "slides_mcp.cli:main"`. MCP clients that invoke `slides-mcp` with no args get the identical stdio server as before.
+
+## What's in the skill
+
+`skills/slides-mcp/SKILL.md` — tool priority table ("bespoke first, escape hatch last"), tools overview (17 entries, 1-liner each), and links out to:
+
+- `rules/workflow.md` — decision tree: "I want to X, use Y"
+- `rules/read-deck.md` — outline, slide, search, faithful vs clean, `include_elements` gating
+- `rules/write-deck.md` — `patch_slide` semantics, `_object_ids`, translation writes, `clone_deck` replacements
+- `rules/theme-hygiene.md` — audit → decide per-drift → promote OR fix
+- `rules/bidi-edit.md` — the see-and-move loop; why RELATIVE transform matters; EMU math
+- `rules/escape-hatch.md` — `exec_batch_update` safety; destructive denylist; audit log
+
+## Packaging notes
+
+The `skills/` directory lives at the repo root (peer of `src/`). Hatchling `force-include` mounts it at `slides_mcp/_skills_data/` inside the built wheel so the install command can find it whether you ran `uv sync` (editable) or `uv pip install slides-mcp` (wheel).
+
+Source-of-truth lives at `skills/slides-mcp/` in the repo. `.claude/skills/` is the install *target*, not stored in this repo.
+
+## What's NOT in this release (deliberate)
+
+- **No PyPI publish wiring.** The `publish:` job in `.github/workflows/release.yml` remains commented out pending OIDC Trusted Publisher setup on pypi.org. Wheel + sdist are still attached to the GitHub Release; `uv tool install` from the GitHub artifact URL works today.
+- **No MCP server auto-registration.** `slides-mcp install` copies skill docs only; it never touches your MCP client config. If you want the slides-mcp server wired into Claude Code, run `claude mcp add slides-mcp uvx slides-mcp` yourself.
+- **No re-install / uninstall subcommands.** Install is idempotent (overwrites). For uninstall: `rm -rf .claude/skills/slides-mcp/`.
+
+## Design notes
+
+The shape follows `looker-mcp-shim` (Node, the sibling project): one namespace, `SKILL.md` + `rules/*.md` split, three target modes (`--global` / `--path` / default-cwd), hardcoded `.claude/skills/` destination. The install layer is Claude-Code-specific today because only Claude Code auto-loads skills from a well-known directory; the *content* of the skill is framework-agnostic (no Claude-specific jargon) so it can be broadened to other MCP clients later without rewriting the rules.
+
+## Full changelog
+
+See auto-generated notes (from conventional commit prefixes) below the narrative.

slides_mcp-0.2.0/skills/slides-mcp/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: slides-mcp
+description: REQUIRED before using any slides-mcp tools. Covers reading decks as compact YAML, text edits, translation writes, theme hygiene, thumbnail rendering, and the exec_batch_update escape hatch. Read rules/*.md for the workflow slices.
+metadata:
+  tags: slides, google-slides, mcp, presentation, deck, theme, bidi-edit
+---
+
+## When to use
+
+ALWAYS read this skill BEFORE calling any slides-mcp tool. Use when:
+
+- Reading a deck outline or individual slides as compact YAML DSL
+- Editing slide text, moving shapes, or cloning decks for new clients
+- Auditing color / font drift against a brand theme and promoting drift to the theme
+- Rendering slide thumbnails for visual verification (bidi loop)
+- Running arbitrary Slides API requests via the `exec_batch_update` escape hatch
+
+**CRITICAL:** The DSL is ~100–150 tok/slide in `clean` mode. Use `faithful` mode only when you need raw geometry. Set `include_elements=True` on `get_slide` only when you intend to MOVE shapes next — the geometry channel costs ~50 extra tokens per slide.
+
+## Tool Priority — Bespoke First, Escape Hatch Last
+
+The bespoke tools (`patch_slide`, `create_shape`, `duplicate_slot`, `clone_deck`) are always preferred over `exec_batch_update`. They are type-safe, theme-aware, and emit minimal requests. `exec_batch_update` is the escape hatch for rare operations outside the happy path — NOT the default.
+
+| Need | Use | NOT (escape hatch) | Why bespoke wins |
+|------|-----|-------------------|------------------|
+| Text edit a slot | `patch_slide` with DSL change | hand-rolled `replaceAllText` | Uses `_object_ids` to avoid duplicate-hit |
+| Move an existing shape | `patch_slide` with `elements[].at` diff | `updatePageElementTransform` | Emits RELATIVE mode — preserves scale/rotation |
+| Add a new shape | `create_shape` | `createShape + updateShapeProperties + insertText` | One tool, theme-aware fills |
+| Duplicate an existing shape | `duplicate_slot` | `duplicateObject + updatePageElementTransform` | Handles objectIds map + optional translation |
+| Clone a deck (template) | `clone_deck` (with optional `replacements` map) | Drive copy + manual replaceAllText per pair | Batched cmd+F replacement in one call |
+| Notes edit | `patch_slide` (notes field in DSL) | `deleteText + insertText` on notesPage | Threaded through `notes_object_id` |
+| Any other Slides API Request | `exec_batch_update` (with `dry_run=True` first) | N/A | No bespoke wrapper — dry-run before firing |
+
+**Rule:** If a bespoke tool exists for your task, use it. Only reach for `exec_batch_update` when none of the bespoke tools cover your operation (e.g. `updateTextStyle`, `insertTableRows`, `updateTableCellProperties`).
+
+## Tools Overview
+
+| Tool | Purpose |
+|------|---------|
+| `auth_status` | Diagnostic: report token.json state without exposing secrets |
+| `list_themes` / `list_archetypes` | Discover bundled + user themes / archetype YAMLs |
+| `list_deck_layouts` / `list_slides_by` | Archetype inventory + structural grep over a deck |
+| `get_deck_outline` | Whole-deck index, ~20 tok/slide |
+| `get_slide` | One slide as compact YAML; `mode=clean/faithful`, opt-in `include_elements` |
+| `search_deck` | Text substring search across slides |
+| `patch_slide` | Apply DSL patch — text edits + translation writes in one call |
+| `create_shape` | Insert a new shape at `[l,t,w,h]` with optional text / fill |
+| `duplicate_slot` | Duplicate an existing pageElement, optionally translate by delta |
+| `clone_deck` | Drive copy a deck, optionally with cmd+F-style text replacements |
+| `audit_deck_colors` | Walk the whole deck, report colors / fonts not in the active theme |
+| `promote_to_theme` | Add a drift value to the theme as a named role (writes to user config) |
+| `render_thumbnail` | Render a slide as PNG and return as native MCP `ImageContent` |
+| `render_thumbnail_url` | Return the short-lived contentUrl only (for non-agent callers) |
+| `exec_batch_update` | Raw batchUpdate passthrough — ALWAYS `dry_run=True` on first call |
+
+## Workflow Guides
+
+Read these before starting. Each rule doc is scoped to one axis of the workflow:
+
+- [rules/workflow.md](rules/workflow.md) — **Start here.** Decision tree: what to use when
+- [rules/read-deck.md](rules/read-deck.md) — Outline, slide, search, list_slides_by; clean vs faithful; `include_elements` gating
+- [rules/write-deck.md](rules/write-deck.md) — `patch_slide` semantics; text edits, translation, `_object_ids`, `clone_deck` replacements
+- [rules/theme-hygiene.md](rules/theme-hygiene.md) — `audit_deck_colors` + `promote_to_theme`; the living-theme workflow
+- [rules/bidi-edit.md](rules/bidi-edit.md) — The see-and-move loop: `render_thumbnail` + `include_elements` + RELATIVE transforms
+- [rules/escape-hatch.md](rules/escape-hatch.md) — `exec_batch_update` safely: `dry_run`, destructive denylist, audit log

slides_mcp-0.2.0/skills/slides-mcp/rules/bidi-edit.md

@@ -0,0 +1,75 @@
+# Bidi editing — see and move
+
+The killer feature: you can SEE the rendered slide natively AND MOVE shapes by editing coordinates, in the same MCP session.
+
+## The loop
+
+```
+1. get_slide(deck_url, slide_id, include_elements=True)
+   → DSL with elements: [{id, at:[x,y,w,h]}]
+   → also auto-includes _object_ids for text slots
+
+2. render_thumbnail(deck_url, slide_id, size="MEDIUM")
+   → MCP ImageContent (PNG bytes) — agent sees it natively
+
+3. Decide: "move the JOON block 0.5in up and left"
+
+4. Modify elements[N].at in the DSL
+
+5. patch_slide(deck_url, slide_id, new_dsl_yaml, verify="auto")
+   → emits updatePageElementTransform with translateX/Y in EMU, applyMode: RELATIVE
+   → auto-renders a fresh thumbnail (verify=auto fires on any geometry diff)
+
+6. Consume the new thumbnail — was the move correct?
+
+7. If no: goto 4. If yes: done.
+```
+
+## Why RELATIVE mode matters
+
+The Slides API `updatePageElementTransform` has two modes:
+
+- **ABSOLUTE** — replaces the entire transform. You MUST specify scale / rotation or they reset to 1 / 0.
+- **RELATIVE** — composed with the existing transform. If the shape was scaled 0.72× and rotated 15°, those stick; only the translation adds.
+
+`patch_slide` always emits RELATIVE with `scaleX: 1, scaleY: 1, translateX: Δ, translateY: Δ`. This is correct for translation-only writes. If you need to resize or rotate, you have to use `exec_batch_update` with an ABSOLUTE transform (and handle scale / rotation yourself) — resize/rotate writes are deferred to Phase 2.
+
+## EMU units
+
+The Slides API uses EMU (English Metric Units). `patch_slide` handles the conversion for you:
+
+- 914,400 EMU = 1 inch
+- 12,700 EMU = 1 pt
+
+You edit `at` in inches in the DSL; the writer converts to EMU in the request.
+
+## What's NOT a bidi edit (yet)
+
+- Resize (width / height change in `elements[].at`) → warning, no write
+- Rotate / shear → no DSL channel; use `exec_batch_update` with full transform
+- Add a new shape → `create_shape`, not DSL add-element
+- Remove a shape → `exec_batch_update` with `deleteObject` + `confirm_destructive=True`
+
+## Render tiers
+
+```
+render_thumbnail(deck_url, slide_id, size="SMALL")   # fastest, low-res
+render_thumbnail(deck_url, slide_id, size="MEDIUM")  # default, balanced
+render_thumbnail(deck_url, slide_id, size="LARGE")   # high-res, slowest
+```
+
+MEDIUM is fine for most visual verification. Go LARGE only when you need to read small body text in the image.
+
+## URL-only sibling
+
+```
+render_thumbnail_url(deck_url, slide_id, size="MEDIUM")
+```
+
+Returns just the short-lived contentUrl (no bytes). Use this for dashboard embeds or pipelines where you don't need the image in-context. Agents should use `render_thumbnail` (native bytes), not this URL form.
+
+## Token budget note
+
+Thumbnails are expensive — ~640 tok on SMALL up to ~2,765 tok on LARGE. The auto-rendering gate in `patch_slide` only fires on geometry changes for exactly this reason. For text-only edits, no thumbnail is rendered by default.
+
+If you're in a many-turn session and the token budget is tight, pass `verify="never"` to suppress the auto-thumbnail, then render on-demand later with `render_thumbnail` when you actually need to see the result.