opencode-skills-collection 4.0.4 → 4.0.5

package/bundled-skills/game-development/engine-selection/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: engine-selection
+description: >-
+  Selects game engines and frameworks by platform, genre, and architecture
+  (full canvas shell vs hybrid DOM shell + guest viewport). Covers Phaser,
+  PixiJS, Kaplay, Canvas/WebGL, Three.js, Babylon.js, Godot, Unity, Ink, Twine.
+  Use when choosing a stack or comparing runtimes before implementation.
+risk: safe
+source: self
+date_added: "2026-07-17"
+---
+
+# Engine selection
+
+> Pick tools that match **delivery target**, **interaction model**, and **team constraints**. Engines serve the game type — not the reverse.
+
+---
+
+## Fit questions (ask first)
+
+1. **Platform:** Web, mobile, PC, console, VR?
+2. **Primary loop:** Action/physics, turn-based, narrative branch, management/UI, hybrid?
+3. **Presentation:** Full-screen canvas, DOM/UI chrome, or both?
+4. **Toolchain:** No-build / ESM OK, or bundler + editor OK?
+5. **Authoring:** Code-only, or designers need Twine/Ink/Godot/Unity editors?
+
+---
+
+## Architecture patterns
+
+| Pattern | When | Notes |
+|---------|------|-------|
+| **Full engine shell** | Game *is* the canvas/scene | Phaser, Godot, Unity, Kaplay as app root |
+| **Renderer + custom logic** | You want draw power, own gameplay | PixiJS, Three.js + your systems |
+| **Hybrid shell + guest** | Dense UI/text + occasional skill-checks | DOM/app shell; mount canvas engines in modals/viewports only |
+| **Narrative runtime** | Branching prose is the product | Ink, Twine; host chrome separately |
+| **Content-as-data** | Levels/events authored as packs | JSON/YAML + thin loader; engine optional |
+
+---
+
+## Web — decision tree
+
+```
+What type of game?
+│
+├── Mostly DOM / panels / forms / text UI
+│   ├── + small arcade/spatial challenges
+│   │     └── Hybrid: custom shell + guest
+│   │         Raw Canvas/WebGL → Kaplay → Phaser → PixiJS
+│   └── + branching story
+│         └── Ink (inkjs) or Twine export → host in DOM
+│
+├── Full-screen 2D game
+│   ├── Full gameplay features (scenes, physics, input)
+│   │     └── Phaser 4  (or Kaplay if you want lighter/faster prototype)
+│   └── Mostly rendering / custom systems
+│         └── PixiJS 8  (or Raw Canvas/WebGL if tiny scope)
+│
+└── Full-screen 3D game
+    ├── Full engine / physics / XR
+    │     └── Babylon.js
+    └── Rendering-focused / lighter
+          └── Three.js
+```
+
+---
+
+## Quick comparison (web & common exports)
+
+| Tool | Type | Best for | Watch-outs |
+|------|------|----------|------------|
+| **Raw Canvas / WebGL** | 2D/low-level | Tiny games, learning, no framework tax | You own everything |
+| **Kaplay** (ex-Kaboom) | 2D toolkit | Fast prototypes, jam games | Less “full product” structure than Phaser |
+| **Phaser 4** | 2D engine | Complete 2D features | Heavier; often bundled |
+| **PixiJS 8** | 2D renderer | Performance, custom game code | Not a full gameplay framework alone |
+| **Three.js** | 3D renderer | Visuals, lightweight 3D | You add gameplay systems |
+| **Babylon.js** | 3D engine | Fuller 3D + XR | Heavier than Three for simple scenes |
+| **Ink + inkjs** | Narrative | Complex branching prose | Weak for real-time multi-entity sims |
+| **Twine / Twison / TweeJS** | Narrative | Educator-friendly branches | Export/host glue; not a physics engine |
+| **Godot 4** | Full engine | 2D/3D indie, open source | Web export iteration cost |
+| **Unity** | Full engine | Large teams, multi-platform | Heavy for simple web UI games |
+
+Editor-first web shells (**Construct**, **GDevelop**) fit visual prototyping; weaker when you need versioned code-first content pipelines.
+
+---
+
+## Non-web defaults (see also platform skills)
+
+| Target | Lean toward |
+|--------|-------------|
+| PC indie / open source | Godot 4 |
+| PC large team / multi-platform | Unity |
+| Mobile | See `game-development/mobile-games` (touch, stores, battery) |
+| VR/AR | See `game-development/vr-ar` (+ Babylon/Three on web) |
+
+---
+
+## Anti-patterns
+
+| Don't | Do |
+|-------|-----|
+| Choose Unity/Godot for a form-heavy browser tool | Prefer DOM/hybrid |
+| Force Ink to run real-time concurrent simulations | Use narrative tools for branches; custom/sim code for clocks & entities |
+| Use Phaser as “the whole app” when the surrounding UI is HTML | Prefer a hybrid guest viewport |
+| Optimize for WebGPU on day one | Ship WebGL; add WebGPU + fallback when needed |
+
+## When to Use
+
+Use when choosing or comparing game engines/frameworks before implementation, especially for hybrid DOM+canvas or narrative-first products.
+
+## Limitations
+
+- Does not replace platform skills (`game-development/web-games`, `game-development/pc-games`, …).
+- Final choice still depends on team skill and shipping constraints.
+- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

package/bundled-skills/game-development/web-games/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: web-games
-description: "Web browser game development principles. Framework selection, WebGPU, optimization, PWA."
+description: >-
+  Web browser game development. Framework selection (Phaser, PixiJS, Kaplay,
+  Canvas/WebGL, Three.js, Babylon.js), hybrid DOM+canvas, WebGPU, optimization,
+  PWA, audio unlock. Use when building HTML5/WebGL/WebGPU games or choosing a
+  browser runtime.
 risk: unknown
 source: community
 date_added: "2026-02-27"
@@ -8,7 +12,7 @@ date_added: "2026-02-27"
 
 # Web Browser Game Development
 
-> Framework selection and browser-specific principles.
+> Framework selection and browser-specific principles. For stack choice details see `game-development/engine-selection`.
 
 ---
 
@@ -20,25 +24,43 @@ date_added: "2026-02-27"
 What type of game?
 │
 ├── 2D Game
-│   ├── Full game engine features? → Phaser
-│   └── Raw rendering power? → PixiJS
+│   ├── Full game engine features? → Phaser 4
+│   ├── Fast prototype / jam?      → Kaplay
+│   ├── Raw rendering power?       → PixiJS 8
+│   └── Tiny / no dependency?      → Raw Canvas / WebGL
 │
 ├── 3D Game
 │   ├── Full engine (physics, XR)? → Babylon.js
-│   └── Rendering focused? → Three.js
+│   └── Rendering focused?         → Three.js
 │
-└── Hybrid / Canvas
-    └── Custom → Raw Canvas/WebGL
+├── Hybrid (DOM UI + canvas moments)
+│   └── Custom shell + guest viewport
+│       (Canvas/Kaplay/Phaser/Pixi inside a region/modal)
+│
+└── Narrative-first
+    └── Ink (inkjs) or Twine export + DOM host
 ```
 
-### Comparison (2025)
+### Comparison
 
 | Framework | Type | Best For |
 |-----------|------|----------|
-| **Phaser 4** | 2D | Full game features |
-| **PixiJS 8** | 2D | Rendering, UI |
-| **Three.js** | 3D | Visualizations, lightweight |
-| **Babylon.js 7** | 3D | Full engine, XR |
+| **Raw Canvas / WebGL** | 2D / low-level | Small scope, full control |
+| **Kaplay** | 2D toolkit | Rapid prototypes |
+| **Phaser 4** | 2D engine | Full game features |
+| **PixiJS 8** | 2D renderer | Rendering, custom systems |
+| **Three.js** | 3D renderer | Visualizations, lightweight 3D |
+| **Babylon.js** | 3D engine | Full engine, XR |
+
+### Hybrid shell + guest
+
+Use when chrome is HTML (menus, inventories, text, dashboards) but bursts of play need a canvas:
+
+1. Mount guest in a container; pass context in.
+2. Run a **local** game loop in the guest.
+3. Return results (score, pass/fail); **destroy** guest (RAF, listeners, GL context as needed).
+
+Do not let the guest own global app routing unless the product *is* a full-screen game.
 
 ---
 
@@ -56,8 +78,8 @@ What type of game?
 
 ### Decision
 
-- **New projects**: Use WebGPU with WebGL fallback
-- **Legacy support**: Start with WebGL
+- **New GPU-heavy projects**: Use WebGPU with WebGL fallback
+- **Broad legacy / simple 2D**: Start with WebGL or Canvas 2D
 - **Feature detection**: Check `navigator.gpu`
 
 ---
@@ -69,7 +91,7 @@ What type of game?
 | Constraint | Strategy |
 |------------|----------|
 | No local file access | Asset bundling, CDN |
-| Tab throttling | Pause when hidden |
+| Tab throttling | Pause when hidden (`visibilitychange`) |
 | Mobile data limits | Compress assets |
 | Audio autoplay | Require user interaction |
 
@@ -85,16 +107,12 @@ What type of game?
 
 ## 4. Asset Strategy
 
-### Compression Formats
-
 | Type | Format |
 |------|--------|
-| Textures | KTX2 + Basis Universal |
+| Textures | KTX2 + Basis Universal (or WebP/PNG for simple 2D) |
 | Audio | WebM/Opus (fallback: MP3) |
 | 3D Models | glTF + Draco/Meshopt |
 
-### Loading Strategy
-
 | Phase | Load |
 |-------|------|
 | Startup | Core assets, <2MB |
@@ -105,35 +123,16 @@ What type of game?
 
 ## 5. PWA for Games
 
-### Benefits
-
-- Offline play
-- Install to home screen
-- Full screen mode
-- Push notifications
-
-### Requirements
-
-- Service worker for caching
-- Web app manifest
-- HTTPS
+**Benefits:** offline play, install, fullscreen, optional push.
+**Requirements:** service worker, web app manifest, HTTPS.
 
 ---
 
 ## 6. Audio Handling
 
-### Browser Requirements
-
-- Audio context requires user interaction
-- Create AudioContext on first click/tap
-- Resume context if suspended
-
-### Best Practices
-
-- Use Web Audio API
-- Pool audio sources
-- Preload common sounds
-- Compress with WebM/Opus
+- Create/resume `AudioContext` on first click/tap
+- Prefer Web Audio API; pool sources; preload common SFX
+- Compress with WebM/Opus when possible
 
 ---
 
@@ -146,15 +145,18 @@ What type of game?
 | Block on audio load | Lazy load audio |
 | Skip compression | Compress everything |
 | Assume fast connection | Handle slow networks |
+| Leave canvas engines running off-screen | Tear down guests |
 
 ---
 
 > **Remember:** Browser is the most accessible platform. Respect its constraints.
 
 ## When to Use
-This skill is applicable to execute the workflow or actions described in the overview.
+
+Use when building HTML5/WebGL/WebGPU games, choosing a browser runtime, or wiring hybrid DOM+canvas guests.
 
 ## Limitations
+
 - Use this skill only when the task clearly matches the scope described above.
 - Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
 - Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

package/bundled-skills/git-advanced-workflows/SKILL.md

@@ -20,9 +20,8 @@ Master advanced Git techniques to maintain clean history, collaborate effectivel
 - Clarify goals, constraints, and required inputs.
 - Apply relevant best practices and validate outcomes.
 - Provide actionable steps and verification.
-- If detailed examples are required, open `resources/implementation-playbook.md`.
 
-## Use this skill when
+## When to Use
 
 - Cleaning up commit history before merging
 - Applying specific commits across branches
@@ -405,15 +404,6 @@ git reflog
 git branch recovered-branch abc123
 ```
 
-## Resources
-
-- **references/git-rebase-guide.md**: Deep dive into interactive rebase
-- **references/git-conflict-resolution.md**: Advanced conflict resolution strategies
-- **references/git-history-rewriting.md**: Safely rewriting Git history
-- **assets/git-workflow-checklist.md**: Pre-PR cleanup checklist
-- **assets/git-aliases.md**: Useful Git aliases for advanced workflows
-- **scripts/git-clean-branches.sh**: Clean up merged and stale branches
-
 ## Limitations
 - Use this skill only when the task clearly matches the scope described above.
 - Do not treat the output as a substitute for environment-specific validation, testing, or expert review.

package/bundled-skills/git-pushing/SKILL.md

@@ -32,22 +32,22 @@ Do not use this skill for a maintainer merge batch, canonical synchronization, v
 
 ## Workflow
 
-Use the helper only after the safety gates pass. With no paths it stages all current changes, so use that form only when every dirty file belongs to the requested commit:
+Use the helper only after the safety gates pass. Resolve the installed directory that contains this `SKILL.md` and substitute its absolute path for `<skill-directory>` below; do not assume the current working directory is the catalog repository. With no paths the helper stages all current changes, so use that form only when every dirty file belongs to the requested commit:
 
 ```bash
-bash skills/git-pushing/scripts/smart_commit.sh
+bash "<skill-directory>/scripts/smart_commit.sh"
 ```
 
 With custom message:
 
 ```bash
-bash skills/git-pushing/scripts/smart_commit.sh "feat: add feature"
+bash "<skill-directory>/scripts/smart_commit.sh" "feat: add feature"
 ```
 
 To stage only named files, pass them after `--`:
 
 ```bash
-bash skills/git-pushing/scripts/smart_commit.sh "fix: scope change" -- path/to/file
+bash "<skill-directory>/scripts/smart_commit.sh" "fix: scope change" -- path/to/file
 ```
 
 The helper handles isolated staging, commit creation, and push; it does not replace validation, release tooling, or a rebase required by an advanced upstream branch.

package/bundled-skills/modellix/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: modellix
+description: "Integrate Modellix unified API/CLI for async AI image and video generation (model run --wait, task download)."
+category: creative
+risk: critical
+source: community
+source_repo: Modellix/modellix-skill
+source_type: official
+date_added: "2026-07-16"
+author: Modellix
+tags: [image-generation, video-generation, modellix, cli, api]
+tools: [claude, cursor, gemini]
+license: "MIT"
+license_source: "https://github.com/Modellix/modellix-skill/blob/main/LICENSE"
+---
+
+# Modellix
+
+## Overview
+
+Modellix is a Model-as-a-Service platform for AI image and video generation. This skill teaches agents to use the official `modellix-cli` workflow (doctor → model run --wait → task download).
+
+Upstream package: https://github.com/Modellix/modellix-skill/tree/main/modellix-skill
+
+## When to Use This Skill
+
+- Generate images from text prompts
+- Generate or edit videos from text or images
+- Call Modellix models through a unified API/CLI
+- The user mentions Modellix, Seedream, Seedance, Nano Banana, or similar providers via Modellix
+
+## How It Works
+
+1. Authenticate with `MODELLIX_API_KEY` or `modellix-cli auth login`
+2. Run `modellix-cli doctor --json`
+3. Use default models when unspecified (T2I: `google/nano-banana-2-lite`, T2V: `bytedance/seedance-2.0-mini-t2v`)
+4. Submit with `modellix-cli model run --wait --json`
+5. Persist outputs with `modellix-cli task download`
+
+## Examples
+
+### Text-to-image
+
+```bash
+modellix-cli model run \
+  --model-slug google/nano-banana-2-lite \
+  --body '{"prompt":"A cinematic sunset over a futuristic city"}' \
+  --wait --timeout 5m --json
+```
+
+### Text-to-video
+
+```bash
+modellix-cli model run \
+  --model-slug bytedance/seedance-2.0-mini-t2v \
+  --body '{"prompt":"Ocean waves under a cloudy sunset"}' \
+  --wait --timeout 10m --json
+```
+
+## Best Practices
+
+- Prefer CLI `model run --wait` over hand-rolled polling
+- Before a paid submission, disclose the provider, model, prompt or source media that will leave the machine, expected cost, and output path; obtain explicit user approval
+- Prefer session-scoped API-key use; run `modellix-cli auth login` only when the user approves persistent local credential storage
+- Do not blindly retry paid submissions after unknown outcomes — check `task history`
+- Confirm the destination and overwrite policy before `task download`; never replace an existing file without explicit approval
+- Fetch request schemas from `model describe` `docs_url` or https://docs.modellix.ai/llms.txt
+
+## Security & Safety Notes
+
+- Requires a Modellix API key; never print secrets in logs
+- Prompts and uploaded source media leave the machine for `api.modellix.ai` and Modellix CDN processing
+- Paid generation consumes account balance and must not be submitted or retried without the approval described above
+
+## Limitations
+
+- Requires a Modellix account, network access, a valid API key, and sufficient account balance.
+- Model availability, request schemas, pricing, quotas, moderation, and generation time are controlled by Modellix and may change.
+- Generated outputs require human review for quality, rights, privacy, and policy compliance before publication.
+- This skill documents the CLI workflow only; it does not define a REST fallback or guarantee that a completed remote task downloads successfully.

package/bundled-skills/pptx-deck-creation/SKILL.md

@@ -154,8 +154,10 @@ Own net-new PPTX creation in this workflow. When a PPTX file is required,
 create a small task-specific builder with the user's approved environment. Start
 slides from a blank layout and create native objects from the final bounding
 boxes. Enable word wrap, disable automatic text resizing, set text insets and
-alignment explicitly, and reject zero or negative bounding boxes before
-building.
+alignment explicitly, and reject zero or negative bounding boxes for non-line
+objects before building. Validate lines by requiring two distinct endpoints;
+horizontal and vertical lines may have a zero-height or zero-width bounding
+box.
 
 Save the authored specification, PPTX, build manifest, audit records, and
 source manifest together. Do not add a large shared renderer or copy source
@@ -181,7 +183,11 @@ with the slide ID, object ID, reason, owner, and review date.
 
 The skill provides a read-only analysis contract, not packaged code. For a
 specific task, use `python-pptx` and the Office Open XML package to inspect a
-presentation. Produce only the context needed for the task:
+presentation. Use OOXML package inspection when `python-pptx` cannot expose
+theme, master, layout, relationship, notes, comments, animation, media, or
+non-modeled formatting evidence. Resolve the package relationship graph;
+never infer slide order from filenames or copy source package parts. Produce
+only the context needed for the task:
 
 * Compact prompt context with slide count, styles, brands, template, and layout
 * Full extraction with `layout_tree`, summary metrics, and render-aware elements
@@ -189,8 +195,10 @@ presentation. Produce only the context needed for the task:
 * Style-master analysis with colors, fonts, layout usage, and flow patterns
 
 Use [reference-deck analysis recipes](references/reference-deck-analysis.md)
-and [Python guidance](references/python-snippets.md) as static implementation
-references. Keep all extraction read-only.
+and [reference-deck analysis patterns](references/reference-deck-analysis-patterns.md) as static implementation
+references. Use the bundled `references/ooxml-parsing.md` guidance for the
+package-part map, relationship resolution, namespace, and secure parsing
+requirements. Keep all extraction read-only.
 
 ## Visual Assets
 
@@ -208,8 +216,8 @@ objects.
 Before any external generation call, disclose the provider and model, what
 prompt or source material will leave the machine, the likely cost, and the
 output path. Obtain explicit confirmation unless the user already authorized
-that exact operation. Never overwrite an existing output without separate
-confirmation.
+that exact operation. Never overwrite an existing output or manifest without
+separate explicit confirmation.
 
 ## Examples
 

package/bundled-skills/pptx-deck-creation/references/audit-checklist.md

@@ -20,16 +20,20 @@ A.y < B.y + B.h  AND  B.y < A.y + A.h
 For each text object estimate whether its text fits within its bbox.
 
 Rough capacity (Latin):
-- Characters per line ≈ `(bbox.w × 72) / (font_size × 0.5)`, using `0.5 em` as an average Latin glyph-width factor
+- Characters per line ≈ `(bbox.w × 72) / (font_size × 0.5)`, using `0.5 em`
+  as an average Latin glyph-width factor
 - Lines available ≈ `(bbox.h × 72) / (font_size × 1.2)`
   _(bbox in inches, font_size in pt)_
 
 Adjustments:
-- **CJK / full-width text:** use a glyph-width factor near `1.0 em` instead of `0.5 em`. The extractor reports `non_ascii_text` — use it to flag CJK-heavy slides.
+- **CJK / full-width text:** halve the characters-per-line value (full-width glyphs ≈ 2× Latin advance). The extractor reports `non_ascii_text` — use it to flag CJK-heavy slides.
 - **Text on a shape/card:** subtract ≈0.1 in of inner padding from each side of the shape before computing capacity; the text occupies the inset inner area, not the full shape.
 
 - **Pass:** estimated text volume ≤ available capacity.
-- **Warning:** likely overflow → inspect the generated PPTX or rendered preview, then shorten bullets, enlarge the bbox, or split the slide when clipping is confirmed. This estimate is a triage heuristic, not a deterministic failure by itself.
+- **Warning:** likely overflow → inspect the generated PPTX or rendered preview,
+  then shorten bullets, enlarge the bbox, or split the slide when clipping is
+  confirmed. This estimate is a triage heuristic, not a deterministic failure
+  by itself.
   **Never set `font_size` below 9 pt for `classification: "content"` objects.**
 
 ## 3. Font Size Minimums

package/bundled-skills/pptx-deck-creation/references/ooxml-parsing.md

@@ -0,0 +1,58 @@
+# OOXML Parsing Reference
+
+A `.pptx` is an Open Packaging Conventions ZIP archive. Inspect it read-only
+by resolving its relationship graph; do not assume sequential filenames or
+copy package parts into a generated deck.
+
+## Package-Part Map
+
+| Need | Parts |
+| --- | --- |
+| Slide order | `ppt/presentation.xml`, `ppt/_rels/presentation.xml.rels` |
+| Slide text and shapes | Slide parts resolved from presentation relationships (commonly `ppt/slides/slideN.xml`) |
+| Layout, notes, images, charts | The slide's relationship part (commonly `ppt/slides/_rels/slideN.xml.rels`) |
+| Template geometry | `ppt/slideLayouts/`, `ppt/slideMasters/` |
+| Colors and fonts | Theme parts resolved from presentation/master relationships (commonly under `ppt/theme/`) |
+| Notes and comments | `ppt/notesSlides/`, `ppt/comments/` |
+| Media and embeddings | `ppt/media/`, `ppt/embeddings/` |
+
+## Relationship Resolution
+
+1. Start with `ppt/presentation.xml`; use its slide ID list and
+   `ppt/_rels/presentation.xml.rels` to resolve slides in presentation order.
+2. For every part that needs linked content, resolve targets from that part's
+   `.rels` file relative to the owning part rather than from a hard-coded path.
+3. Retain the relationship ID, type, resolved target, and any unreadable or
+   missing target in the analysis result.
+4. Treat raw element ordering as evidence for rendering, not as a reason to
+   reproduce a source slide or its package XML.
+
+## Namespaces
+
+- PresentationML: `http://schemas.openxmlformats.org/presentationml/2006/main`
+- DrawingML: `http://schemas.openxmlformats.org/drawingml/2006/main`
+- Office relationships: `http://schemas.openxmlformats.org/officeDocument/2006/relationships`
+- Package relationships: `http://schemas.openxmlformats.org/package/2006/relationships`
+
+## Analysis Output Guidance
+
+For a read-only extraction, retain the slide number, resolved relationship
+target, concatenated text, shape counts, notes, relationship types, and
+OOXML-only markers such as animations, comments, transitions, unsupported
+shapes, and non-modeled formatting. For design context, retain theme
+color/font tokens without inventing an RGB value when a scheme or system color
+cannot be fully resolved.
+
+Record the input deck path, inspected parts, relationship-resolution errors,
+and unreadable XML in the analysis manifest. Keep the result limited to the
+evidence needed for the requested analysis.
+
+## Secure, Read-Only Handling
+
+- Treat a source deck as untrusted input. Reject path traversal, symlinks,
+  oversized members, and compressed archive bombs before reading ZIP members.
+- Parse XML with a secure parser. Disable DTD loading, entity expansion, and
+  network access.
+- Preserve `xml:space="preserve"` semantics when collecting text.
+- Do not modify the source archive, overwrite it, or blindly copy XML, media,
+  fonts, images, or embedded files into a new deck.

package/bundled-skills/pptx-deck-creation/references/{python-snippets.md → reference-deck-analysis-patterns.md}

@@ -1,4 +1,4 @@
-# PPTX Python Snippets
+# Reference-Deck Analysis Patterns
 
 It describes how to approach PPTX extraction and style analysis with `python-pptx`, using short illustrative
 snippets — not a packaged module to copy wholesale.

package/bundled-skills/pptx-deck-creation/references/reference-deck-analysis.md

@@ -6,8 +6,9 @@ This file is static guidance for inspecting existing `.pptx` files and defining
 
 - Keep only static guidance for reference-deck prompt context, extraction, folder analysis, and style-master inspection.
 - Do not place runtime scripts, model assets, importable Python modules, or generated artifacts here.
-- This skill ships no importable code; implement the extraction/style-analysis contract on demand with `python-pptx`.
-- `python-snippets.md` holds documentation-only `python-pptx` guidance — approach notes plus short illustrative snippets. Do not import from it or recreate packaged `.py` resources from it.
+- This skill ships no importable code; implement the extraction/style-analysis and read-only OOXML inspection contracts on demand with `python-pptx`, `zipfile`, and a secure XML parser.
+- `reference-deck-analysis-patterns.md` holds documentation-only `python-pptx` guidance — approach notes plus short illustrative snippets. Do not import from it or recreate packaged `.py` resources from it.
+- `ooxml-parsing.md` holds documentation-only package-part, relationship, namespace, and security guidance. It is not a runtime dependency or script template.
 
 ## Analysis Recipes
 
@@ -28,15 +29,34 @@ Produce a full JSON extraction including:
 - `summary` complexity metrics
 - `slides[*].layout_tree` with groups/objects
 - `ooxml_elements` for render-aware inspection
+- resolved package relationships, OOXML-only markers, and parsing exceptions
 
-### 3. Folder Batch Recipe
+### 3. OOXML Package Inspection Recipe
+
+Use read-only package inspection when high-level APIs do not expose the needed
+evidence: slide order, theme tokens, masters/layouts, notes, comments,
+animations, media, charts, or non-modeled formatting.
+
+- Resolve slide order from `ppt/presentation.xml` and its relationship part.
+	Do not derive it from `slideN.xml` filenames.
+- Resolve every relationship target relative to its owning source part, not its
+	`.rels` part. Retain the relationship type, target, and unreadable XML errors
+	in the result.
+- Preserve theme colors and fonts as tokens when they cannot be reliably
+	resolved to RGB values.
+- Parse untrusted XML with a secure parser; do not enable DTDs, entity
+	expansion, or network access.
+- Keep the source package read-only and never copy its XML parts into a new
+	deck.
+
+### 4. Folder Batch Recipe
 
 Process a folder of decks to produce:
 
 - One `.pptx-spec.json` file per deck
 - A `manifest.json` to track outputs
 
-### 4. Style Master Recipe
+### 5. Style Master Recipe
 
 Run style-only analysis when you need design lock signals:
 
@@ -44,7 +64,7 @@ Run style-only analysis when you need design lock signals:
 - Typography and font-size distribution
 - Master/layout usage and flow patterns
 
-### 5. Reference Template Catalog Recipe
+### 6. Reference Template Catalog Recipe
 
 When a reference deck should inform a new deck's layout rhythm, produce a
 human-readable catalog from the existing prompt-context, extraction, and
@@ -83,9 +103,11 @@ Suggested catalog shape:
 ## Related Responsibilities
 
 This reference covers PPTX prompt context, extraction, folder batch analysis,
-style-master inspection, and the derived reference-template catalog only.
+style-master inspection, read-only OOXML package inspection, and the derived
+reference-template catalog only. See [OOXML parsing guidance](ooxml-parsing.md)
+for the package-part map and parser safety rules.
 
 - Use the parent `pptx-deck-creation` workflow for narrative/source preparation,
-  together with [design profiles](design-profiles.md) for profile selection.
+	together with [design profiles](design-profiles.md) for profile selection.
 - Use [visual asset guidelines](visual-asset-adapters.md) for acquiring and
-  placing icons, images, SVGs, and infographics.
+	placing icons, images, SVGs, and infographics.