bg3-mod-studio 1.0.0b1__tar.gz

bg3_mod_studio-1.0.0b1/.agents/skills/bg3-check-mod-conflicts/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: bg3-check-mod-conflicts
+description: Evaluate BG3 mod compatibility and conflicts against mods/library.md or between candidates with console load order rules. Use on /check_conflicts or when searching mods.
+---
+
+# BG3 Mod Conflict & Compatibility Checker (`bg3-check-mod-conflicts`)
+
+Evaluates compatibility and detects potential conflicts for *Baldur's Gate 3* mods. Invocable by the [`bg3-search-mods`](../bg3-search-mods/SKILL.md) orchestrator or directly.
+
+Refer to domain specifications:
+- Methodology & Vectors: [Conflict Methodology](./references/conflict_methodology.md)
+- Message Formats & Patches: [Remediation Templates](./resources/remediation_patch_template.md)
+
+---
+
+> [!TIP]
+> Query the studio tool registry with `bg3 tools search "<intent>" --json`.
+
+## Workflow
+
+```mermaid
+flowchart TD
+    Start["Receive Query & Platform"] --> CheckLib["Check Tracked mods/library.md"]
+    CheckLib --> Inspect["Inspect Metadata & Subsystems"]
+    Inspect --> Detect["Run Deterministic Conflict Detection"]
+    Detect --> Format["Format Standardized Return Message"]
+```
+
+### 1. Hybrid Conflict Inspection
+Run deterministic inspection against cataloged workspace mods or candidate pairs:
+- **Candidate vs Tracked Library**: Execute `bg3 mod conflict "<MOD_SLUG>" --against-library --json`
+- **Candidate vs Candidate**: Execute `bg3 mod conflict "<MOD1>" --mod2 "<MOD2>" --json`
+
+### 2. Remediation & Patch Generation
+When actionable stat collisions occur, offer automated patch generation:
+- Execute `bg3 mod patch --mod1 <mod1> --mod2 <mod2> --name "<Mod1><Mod2>Patch" --mode standalone --json`
+
+---
+
+## Verification Gate
+
+Always verify automated conflict output and status formatting before returning:
+1. Verify `bg3 mod conflict` exits with code 0 and valid JSON.
+2. Confirm console tags (`[Console Load Order]`) are applied when target platform is console.
+3. Validate return messages match schemas in [Remediation Templates](./resources/remediation_patch_template.md).

bg3_mod_studio-1.0.0b1/.agents/skills/bg3-check-mod-conflicts/references/conflict_methodology.md

@@ -0,0 +1,33 @@
+# BG3 Mod Conflict Detection Methodology
+
+## 1. Conflict Vectors
+
+Common BG3 conflict sources include:
+- **Direct Stated Incompatibility**: Author explicitly lists incompatibilities in mod descriptions.
+- **Missing Prerequisites**: Missing frameworks (*Community Library*, *Compatibility Framework*, *5e Spells*, *BG3 Script Extender*).
+- **Progression Table Clashes**: Both mods edit the same class/subclass node in `Progressions.lsx` without Compatibility Framework.
+- **Vanilla Asset Overwrites**: Both mods overwrite identical spell, status, or item root templates.
+
+---
+
+## 2. Mode 1: Candidate vs. Existing Library
+
+1. **Library Verification**: Check categorized rows in `Mods/subscribed/library.md`. Inspect specs in `Mods/subscribed/`.
+2. **Metadata Inspection**:
+   ```bash
+   uv run bg3 modio search "<MOD_SLUG>" --platform "<PLATFORM>" --json
+   ```
+3. **Subsystem Audit**:
+   - **Progressions & Rules**: Level curves, spell slots, feat intervals.
+   - **Classes & Subclasses**: Class overrides and spell lists.
+   - **Spells & Gear**: Overlapping spell entries or treasure tables.
+4. **Console Platform Rules**:
+   - **No Manual Load Order**: Console players cannot reorder mods; priority conflicts cannot be resolved manually. Tag with `[Console Load Order]`.
+   - **No Script Extender (BG3SE)**: Native PC DLL dependencies fail on console.
+
+---
+
+## 3. Mode 2: Cross-Candidate Batch Conflicts
+
+1. **Pairwise Analysis**: Compare pairs across candidate sets for shared class, cantrip, or subsystem replacements.
+2. **Order Constraints**: Identify inter-dependencies requiring strict load ordering. On console, flag any priority constraint with `[Console Load Order]`.

bg3_mod_studio-1.0.0b1/.agents/skills/bg3-check-mod-conflicts/resources/remediation_patch_template.md

@@ -0,0 +1,43 @@
+# Remediation & Return Message Templates
+
+## Standardized Return Messages
+
+### Mode 1: Candidate vs. Library
+- Clean:
+  ```text
+  No conflicts found with existing mods
+  ```
+- Conflict Detected:
+  ```text
+  Possible conflict found: <Tracked Mod Name> - <Brief description of the issue>
+  ```
+- Console Load Order Conflict:
+  ```text
+  Possible conflict found: <Tracked Mod Name> - <Brief description of issue> [Console Load Order: cannot reorder on console to ensure proper override]
+  ```
+
+### Mode 2: Cross-Candidate Batch
+- Clean Batch:
+  ```text
+  No conflicts found between candidate mods
+  ```
+- Conflict Detected:
+  ```text
+  Possible conflict found: <Candidate Mod 1> vs <Candidate Mod 2> - <Brief description of the conflict>
+  ```
+- Console Conflict Detected:
+  ```text
+  Possible conflict found: <Candidate Mod 1> vs <Candidate Mod 2> - <Brief description of issue> [Console Load Order: cannot reorder on console to resolve override order]
+  ```
+
+---
+
+## Automated Patch Generation Commands
+
+```bash
+# Generate standalone compatibility override patch mod
+uv run bg3 mod compat-patch --mod1 <mod1> --mod2 <mod2> --name "<Mod1><Mod2>Patch" --mode standalone --json
+
+# Generate Compatibility Framework config payload
+uv run bg3 mod compat-patch --mod1 <mod1> --mod2 <mod2> --mode cf --json
+```

bg3_mod_studio-1.0.0b1/.agents/skills/bg3-create-build-guide/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: bg3-create-build-guide
+description: Generate Level 20 BG3 build guides with Best-in-Slot modded gear, progression tables, and Turn 1 combat sequences. Use on /build_guide or when creating build guides.
+---
+
+# BG3 Level 20 Build Guide Generator (`bg3-create-build-guide`)
+
+Generates comprehensive, mathematical 20-level character build guides for Baldur's Gate 3 leveraging unlocked level progression (e.g. *UnlockLevelCurve*) and community modded equipment.
+
+Refer to companion resources:
+- Formatting Standards: [Build Guide Template](./resources/build_guide_template.md)
+- Math & Level Rules: [Build Conventions](./references/build_conventions.md)
+
+---
+
+> [!TIP]
+> Query the studio tool registry with `bg3 tools search "<intent>" --json`.
+
+## Workflow Overview
+
+1. **Parameters & Role**: Determine class split (totaling 20), starting class, archetype (Caster, Hybrid, Pure Melee).
+2. **Mod & Gear Inspection**: Inspect cataloged mods for mod items. Fall back to top-tier vanilla gear.
+3. **Synergy Simulation**: Calculate Turn 1 DPR, Spell DC, and slot matrices:
+   - Execute `bg3 build simulate --classes "<Class=Level,...>" --stats "<S=N,D=N,C=N,I=N,W=N,Ch=N>" --gear "<Items>" --dpr-sequence <melee_burst|eldritch_blast> --json`
+4. **Draft Guide**: Populate the 5 standardized sections following the [Build Guide Template](./resources/build_guide_template.md).
+5. **Artifact Delivery**: Write the complete document to disk under `$BG3_STUDIO_DIR/Build_Guides/<category>/build_guide_<classes>.md`. Deliver concise executive summary in chat with file link.
+
+---
+
+## Verification Gate
+
+Always verify the generated build guide before concluding:
+1. Verify simulator command exits with code 0 and valid metrics.
+2. Confirm all 20 progression levels are represented and total exactly 20.
+3. Confirm Pure Melee guides omit spell columns per [Build Conventions](./references/build_conventions.md).
+4. Verify all referenced mods in `Mods/subscribed/` resolve correctly.

bg3_mod_studio-1.0.0b1/.agents/skills/bg3-create-build-guide/references/build_conventions.md

@@ -0,0 +1,38 @@
+# Build Guide Conventions & Mechanics
+
+## 1. Feat Strategy & Stat Conventions
+
+### Ability Scores
+- **Primary Setup**: Assumes `Choose Your Stats` mod sets primary stat to 20, freeing all Feat slots from ASIs for high-impact combat/mobility passives.
+- **Fallback Setup**: Always provide a standard 27 Point Buy allocation for unmodded play.
+
+### Feat Priorities
+- **High-Impact Passives**: Alert (+5 initiative), War Caster (advantage on concentration), Spell Sniper (crit threshold reduction), Savage Attacker (reroll melee damage), Sentinel (reaction lockdown), Dual Wielder, Resilient (Wisdom).
+- **Progression Intervals**: Standard levels 4, 8, 12, 16, 19 (plus Fighter 6 & 14, Rogue 10).
+
+---
+
+## 2. Progression Table Schema
+
+### Caster & Hybrid Builds (5 Columns)
+```markdown
+| Total Level | Class & Level | Cantrips Gained | Vanilla Spells Learned / Prepared | Feats & Key Features |
+| :---: | :--- | :--- | :--- | :--- |
+| **1** | **Fighter 1** | — | — | **Fighting Style**: Defense (+1 AC); Second Wind; **CON Save** |
+```
+
+### Pure Melee Builds (4 Columns)
+Omit cantrips and spell columns entirely:
+```markdown
+| Total Level | Class & Level | Class Features & Maneuvers | Feats & Key Features |
+| :---: | :--- | :--- | :--- |
+| **1** | **Fighter 1** | Fighting Style: Great Weapon Fighting; Second Wind | **STR & CON Save**; All Armor & Weapons |
+```
+
+---
+
+## 3. Level 13–20 Mechanics (`UnlockLevelCurve`)
+
+- Full casters unlock 7th and 8th level spell slots for upcasting or modded spells.
+- Cantrips scale to 4 dice/beams at Character Level 17.
+- Incorporate extended subclass capstones where appropriate.

bg3_mod_studio-1.0.0b1/.agents/skills/bg3-create-build-guide/resources/build_guide_template.md

@@ -0,0 +1,116 @@
+# Standard Level 20 Build Guide Template
+
+Use this markdown structure when generating complete Level 20 *Baldur's Gate 3* build guides.
+
+```markdown
+# Build Guide: [Build Title / Name]
+### [Class 1] [Level] / [Class 2] [Level] ...
+**Platform**: Xbox Series S & PC | **Max Level**: 20 (*UnlockLevelCurve*) | **Role**: [Role Description]
+
+---
+
+## 1. Build Archetype & Concept
+
+[2-3 paragraphs explaining the core concept, mechanics, and party role]
+
+* **[Key Synergy 1]**: [Description]
+* **[Key Synergy 2]**: [Description]
+* **[Key Synergy 3]**: [Description]
+* **Zero Gear Contention with Party**: [Explanation of gear compatibility]
+
+### Required Mods (Xbox Series S Verified)
+1. **`UnlockLevelCurve - Level 13-20`** (mod.io ID: `4166963`) — Unlocks progression to Level 20.
+2. **`Sets of Faerun`** (mod.io ID: `4467214`) — [If mod items are equipped].
+3. **`Choose Your Stats`** (slug: `chooseyourstats_modio`) — Used to set starting ability scores, freeing all Feat slots from ASIs.
+4. **`Fade's Camp Chest`** (mod.io ID: `4838986`) — Spawns gear bags cleanly at camp.
+[Include any additional mods referenced from mods/]
+
+---
+
+## 2. Character Creation & Starting Stats
+
+### Optimal Starting Class
+* **[Class Name (Level 1)]**: **MANDATORY starting class**. [Rationale: saving throws, proficiencies, armor/shields].
+
+### Optimal Starting Race
+1. **[Top Race]**: [Racial traits and rationale].
+2. **[Second Race]**: [Racial traits and rationale].
+3. **[Third Race]**: [Racial traits and rationale].
+
+### Starting Ability Scores
+If setting stats with **Choose Your Stats**:
+* **[Primary Stat]**: 20 (scales with gear/Mirror of Loss)
+* **[Secondary Stat]**: 16
+* **[Tertiary Stat]**: 16
+* **[Other Stats]**: ...
+
+*Point Buy Default (if not using stat editor)*:
+* STR: [x] | DEX: [x] | CON: [x] | INT: [x] | WIS: [x] | CHA: [x]
+
+---
+
+## 3. Best-in-Slot (BiS) Gear Loadout
+
+[Introductory paragraph explaining gear synergy, set bonuses, or defense ratings]
+
+| Equipment Slot | Item Name | Mod / Vanilla Source | Key Passives & Stats | Role in Build |
+| :--- | :--- | :--- | :--- | :--- |
+| **Main Hand** | ... | ... | ... | ... |
+| **Off Hand** | ... | ... | ... | ... |
+| **Chest** | ... | ... | ... | ... |
+| **Head** | ... | ... | ... | ... |
+| **Cloak** | ... | ... | ... | ... |
+| **Gloves** | ... | ... | ... | ... |
+| **Boots** | ... | ... | ... | ... |
+| **Amulet** | ... | ... | ... | ... |
+| **Ring 1** | ... | ... | ... | ... |
+| **Ring 2** | ... | ... | ... | ... |
+| **[Set Bonus / Extra Slot]** | ... | ... | ... | ... |
+
+---
+
+## 4. Level 1–20 Progression Table (Vanilla BG3 Spells)
+
+[Note explaining spell rules, upcasting, and feat choices]
+
+### For Caster & Hybrid Builds (5 Columns)
+| Total Level | Class & Level | Cantrips Gained | Vanilla Spells Learned / Prepared | Feats & Key Features |
+| :---: | :--- | :--- | :--- | :--- |
+| **1** | **Fighter 1** | — | — | **Fighting Style**: Defense (+1 AC); Second Wind; **CON Save Proficiency** |
+| ... | ... | ... | ... | ... |
+
+### For Pure Melee Builds (4 Columns)
+| Total Level | Class & Level | Class Features & Maneuvers | Feats & Key Features |
+| :---: | :--- | :--- | :--- |
+| **1** | **Fighter 1** | Fighting Style: Great Weapon Fighting; Second Wind | **STR & CON Save Proficiency**; All Armor & Weapons |
+| ... | ... | ... | ... |
+
+---
+
+## 5. Turn 1 Combat Sequence Example
+
+### Setup Before Combat
+1. [Pre-buffs, stances, elixir/weapon coat recommendations].
+2. [Positioning notes].
+
+### Round 1 Execution: [Sequence Name]
+
+```text
+[COMBAT INITIATIVE]
+[Initiative breakdown and positioning]
+
+Step 1: Standard Action
+- [Action taken, spells/attacks, modifiers, synergies]
+
+Step 2: Bonus Action
+- [Bonus action taken, mobility, quickened spells, or buffs]
+
+Step 3: Extra Actions / Reactions (Action Surge, Fast Hands, etc.)
+- [Additional steps]
+
+[ROUND 1 RESULT]:
+- [Summary of damage, status effects, party buffs, and defensive state]
+```
+
+[Follow-up turns / rotation notes]
+```

bg3_mod_studio-1.0.0b1/.agents/skills/bg3-create-mod/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: bg3-create-mod
+description: Orchestrate concurrent subagents to grill, plan, scaffold, author, and validate BG3 mods in my_mods/<ModSlug>. Use on /bg3-create-mod or when creating new BG3 mods.
+---
+
+# BG3 Mod Creator Orchestrator (`bg3-create-mod`)
+
+Top-level orchestration skill for Stage 1 of the BG3 mod creation lifecycle. Translates creative concepts into fully authored, statically verified mods inside `my_mods/<ModSlug>`.
+
+Refer to companion resources:
+- Interview Protocol: [Design Interview Protocol](./references/grill_me_interview_protocol.md)
+- Subagent Prompts: [Subagent Launch Templates](./resources/subagent_templates.md)
+- Shift-Left Rules: [Mod Architecture Rules](../../../../../docs/ARCHITECTURE.md)
+
+---
+
+> [!TIP]
+> Query the studio tool registry with `bg3 tools search "<intent>" --json`.
+
+## Workflow
+
+```mermaid
+flowchart TD
+    Prompt["User Idea / Prompt"] --> Interview["1. Clarification & Deep Grill Interview"]
+    Interview --> Plan["2. Technical Specification & Implementation Plan"]
+    Plan --> Scaffold["3. Workspace Scaffolding"]
+    Scaffold --> Dispatch["4. Concurrent Specialist Subagents"]
+    Dispatch --> Verify["5. Static Validation Smoke Check"]
+    Verify --> Handoff["6. Progressive Gate Handoff to Stage 2"]
+```
+
+### 1. Design Interview & Plan Approval
+Conduct structured design interview following [Design Interview Protocol](./references/grill_me_interview_protocol.md). Formulate technical specification and await explicit user approval before scaffolding.
+
+### 2. Workspace Scaffolding
+After approval, run the scaffolding tool:
+- Execute `bg3 mod create "<ModName>" [--slug "<slug>"] --description "<Desc>" [--unlock-level-curve] --json`
+
+### 3. Concurrent Subagent Dispatch
+Launch the 4 specialist subagents in parallel following [Subagent Launch Templates](./resources/subagent_templates.md) (Stats & Spells, Progression & Lists, Localization, Documentation). Ensure all subagents inherit model configuration (`Model: "inherit"`). Await reactive completion notifications without polling.
+
+---
+
+## Verification Gate
+
+Once subagents complete, run read-only static verification before handoff:
+1. Validate mod structure and XML schemas: `bg3 mod validate <mod-slug> --json`
+2. Audit localization handle integrity: `bg3 mod sync-loca <mod-slug> --check --json`
+3. Check for stat collisions against tracked library: `bg3 mod conflict <mod-slug> --against-library --json`
+
+Verify:
+- XML/LSX schema adherence and valid localization handles.
+- Zero collisions with `Mods/subscribed/library.md`.
+
+After clean validation, prompt user to transition to **Stage 2 Diagnostics** ([`bg3-diagnose-mod`](../bg3-diagnose-mod/SKILL.md)).

bg3_mod_studio-1.0.0b1/.agents/skills/bg3-create-mod/references/grill_me_interview_protocol.md

@@ -0,0 +1,15 @@
+# Mod Design Interview Protocol (`grill-me`)
+
+Before authoring, walk down each branch of the mod design tree one question at a time:
+
+### Design Tree Branches
+1. **Branch A (Mod Identity & Theme)**: Name (PascalCase, e.g. `ArcaneProgression`), summary, and character fantasy.
+2. **Branch B (Classes & Progression)**: Target classes/subclasses, level bounds (1-12 vanilla vs. 13-20 `UnlockLevelCurve`), progression unlock levels.
+3. **Branch C (Spells, Passives & Abilities)**: Action economy (Action, Bonus Action, Reaction), resource costs (Spell slots, Ki, Charges), damage/status effects.
+4. **Branch D (Parent Dependencies)**: Base game only (`GustavDev`), `UnlockLevelCurve` (`a2ffd0e4-c407-8642-2611-c934ea0b0a77`), or cataloged community mods in `mods/library.md`.
+5. **Branch E (In-Game Acquisition & Item Drops)**: Container drop locations (Tutorial Chest, Camp Chest, vendors like Arron or Dammon) for `bg3 mod inject-treasure`.
+
+### Interview Formatting
+- List recommended option first with `(Recommended)`.
+- Format all options as direct user responses.
+- Synthesize responses into a structured implementation plan and obtain explicit user approval before authoring.

bg3_mod_studio-1.0.0b1/.agents/skills/bg3-create-mod/resources/subagent_templates.md

@@ -0,0 +1,40 @@
+# Specialist Subagent Launch Templates (`bg3-create-mod`)
+
+Reference definitions for the 4 concurrent subagents dispatched during Stage 1 mod creation.
+
+All subagents must be launched with `"Model": "inherit"` and `"Workspace": "inherit"` in accordance with agentic guidelines.
+
+```json
+{
+  "Subagents": [
+    {
+      "TypeName": "self",
+      "Role": "Stats & Spells Specialist - <ModName>",
+      "Prompt": "Author the BG3 stat entries in <stats_dir>. Mod: <ModName>, UUID: <UUID>.\nTo ensure 100% engine compliance and valid localization handle allocation, use:\n  uv run bg3 scaffold stat --mod <ModName> --type <weapon|armor|amulet|ring|spell_target|passivedata> --name <Id> --display-name \"<Name>\" --description \"<Desc>\" --props \"<Props>\"\nFor weapons/armor/objects, bind 3D visual models using:\n  uv run bg3 scaffold root-template --mod <ModName> --item <Id> --visual-preset <greatsword|longsword|staff|plate|robe|amulet|ring|boots|cloak>\nFor custom item container/vendor drops, inject drops using:\n  uv run bg3 mod inject-treasure --mod <ModName> --item <ItemName> --container <tutorial_chest|camp_chest|vendor_...>\nRefer to the approved plan for exact mechanics.",
+      "Workspace": "inherit",
+      "Model": "inherit"
+    },
+    {
+      "TypeName": "self",
+      "Role": "Progression & Lists Specialist - <ModName>",
+      "Prompt": "Author Progressions.lsx and SpellLists.lsx for Mod: <ModName>, UUID: <UUID>.\nTo scaffold class progression levels without manual UUID errors, use:\n  uv run bg3 scaffold progression --mod <ModName> --class-name <Class> --level <N> --progression-type <0|1> --boosts \"<Boosts>\" --passives \"<Passives>\" --selectors \"<Selectors>\"\nEnsure UnlockLevelCurve compat if level > 12. Refer to the approved plan for exact progression nodes.",
+      "Workspace": "inherit",
+      "Model": "inherit"
+    },
+    {
+      "TypeName": "self",
+      "Role": "Localization Specialist - <ModName>",
+      "Prompt": "Audit and synchronize string handles in Localization/English/<ModName>.xml for Mod: <ModName>.\nEnsure all Stat entries, Spells, and Progression nodes have valid UUID handles (h...). Verify handle uniqueness and compile binary loca check:\n  uv run bg3 mod sync-localization --mod <ModSlug> --check --json",
+      "Workspace": "inherit",
+      "Model": "inherit"
+    },
+    {
+      "TypeName": "self",
+      "Role": "Documentation Specialist - <ModName>",
+      "Prompt": "Draft the root README.md for my_mods/<ModSlug>/README.md adhering to the Rich Feature Schema:\n- Overview & lore context\n- Verified feature tables (Stat ID, Slot/Type, Mechanics, Acquisition)\n- Installation & Xbox Series S compatibility notes\n- Render mod.io description preview: uv run bg3 mod render-description --mod <ModSlug> --write --json",
+      "Workspace": "inherit",
+      "Model": "inherit"
+    }
+  ]
+}
+```

bg3_mod_studio-1.0.0b1/.agents/skills/bg3-create-modio-collection/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: bg3-create-modio-collection
+description: Create or update a public Baldur's Gate 3 mod.io collection from mods documented in mods/library.md. Use on /bg3-create-modio-collection or when creating a mod.io collection.
+---
+
+# Create a BG3 mod.io Collection (`bg3-create-modio-collection`)
+
+Creates a public BG3 collection or updates one of the authenticated user's collections using numeric Mod ID values from `Mods/subscribed/library.md`.
+
+---
+
+## Safety and Credentials Invariants
+
+1. **Environment Authentication**: Require `MODIO_PAT` in the process environment. Keep token values masked in all logs and outputs.
+2. **Game Guard**: Ensure selected mod profiles and collections belong strictly to Baldur's Gate 3 (Game ID `6715`).
+3. **Explicit Approval Gate**: Present the complete change preview to the user. Await affirmative confirmation in chat before executing live API writes.
+4. **Dry-Run Parity**: Execute `--dry-run` first to preview additions and removals. Continue live execution only when live preview matches the approved dry-run.
+
+---
+
+> [!TIP]
+> Query the studio tool registry with `uv run bg3 tools search "<intent>" --json`.
+
+## Workflow
+
+### 1. Verification & Dry Run Preview
+Confirm `MODIO_PAT` is present, then execute dry run:
+- Run dry-run collection assembly: `uv run bg3 modio create-collection --dry-run`
+- The script confirms BG3 collection membership and checks numeric Mod IDs from `Mods/subscribed/library.md`.
+
+### 2. User Approval & Live Execution
+1. Present the complete preview (selected mods, additions, removals) to the user.
+2. Upon user approval, rerun with confirmation:
+   - Run live collection creation: `uv run bg3 modio create-collection --yes`
+3. Confirm that the live preview matches the approved dry-run preview.
+
+---
+
+## Verification Gate
+
+Always verify collection state and API responses:
+1. Verify `create-collection` exits with code 0.
+2. Confirm the collection URL and ID are displayed and operational.
+3. Verify all selected mods were added to the target collection.
+4. If missing numeric IDs were reported, verify IDs against trusted mod documentation before updating `Mods/subscribed/library.md`.

bg3_mod_studio-1.0.0b1/.agents/skills/bg3-diagnose-mod/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: bg3-diagnose-mod
+description: Diagnose BG3 mod issues, missing localization, load order errors, and stat collisions with automated fixes (Stage 2). Use on /bg3-diagnose-mod or after mod authoring.
+---
+
+# BG3 Mod Diagnostics & Toolkit Verification (Stage 2) (`bg3-diagnose-mod`)
+
+Stage 2 verification gate and diagnostic doctor for *Baldur's Gate 3* mods. Coordinates User-Action Gate 1 (Toolkit diagnostics) and runtime log remediation.
+
+Refer to deep triage reference:
+- Log Analysis & Circuit Breakers: [Log Triage Reference](./references/runtime_log_triage.md)
+
+---
+
+> [!TIP]
+> Query the studio tool registry with `uv run bg3 tools search "<intent>" --json`.
+
+## Workflow
+
+```mermaid
+flowchart TD
+    Start["/bg3-diagnose-mod <slug>"] --> Preflight["1. Workspace Assertion (validate)"]
+    Preflight --> Sync["2. Sync Unpacked Assets & .loca to Data/"]
+    Sync --> UserAction["3. User Loads Mod in Glasses.exe"]
+    UserAction --> Triage["4. Diagnose Toolkit Runtime Logs"]
+    Triage --> Clean{"Logs Clean?"}
+    Clean -->|"Fixes Needed"| Patch["Patch in my_mods/ and Re-sync"]
+    Patch --> Preflight
+    Clean -->|"Clean / Skipped"| Gate["5. Stage 3 Testing Handoff"]
+```
+
+### Phase 2A: Workspace Assertion & Game Data Sync
+1. Run rapid static pre-flight validation on `my_mods/<slug>/`:
+   - Execute `uv run bg3 mod validate <mod-slug> --json`
+2. Synchronize unpacked assets and compiled binary `.loca` to `<Game>/Data/`:
+   - Execute `uv run bg3 mod sync-game --mods <mod-slug> --json`
+3. Instruct user to open `<ModName>` in Baldur's Gate 3 Toolkit (`Glasses.exe`) to generate engine runtime logs.
+
+### Phase 2B: Runtime Log Diagnosis
+1. Inspect generated Toolkit logs per [Log Triage Reference](./references/runtime_log_triage.md):
+   - Execute `uv run bg3 mod diagnose-logs <mod-slug> --severity warning --json`
+2. Apply targeted fixes in `my_mods/<mod-slug>/`, re-sync, and confirm resolution (bounded by 3-iteration circuit breaker).
+
+---
+
+## Verification Gate
+
+Always verify mod diagnostics state before transitioning:
+1. Verify `bg3 mod validate` exits with code 0.
+2. Confirm game synchronization (`sync-game`) exits with code 0 and binary `.loca` compiled.
+3. Confirm Toolkit logs show 0 warnings or user explicitly skipped runtime log triage.
+4. Prompt user to transition to **Stage 3: In-Game Testing** ([`bg3-test-mod`](../bg3-test-mod/SKILL.md)).

bg3_mod_studio-1.0.0b1/.agents/skills/bg3-diagnose-mod/references/runtime_log_triage.md

@@ -0,0 +1,30 @@
+# Toolkit Runtime Log Diagnosis & Triage Reference
+
+## 1. Engine Log Inspection
+
+Execute deterministic triage against BG3 Toolkit (`Glasses.exe`) sessions:
+```bash
+# General warning/error triage
+uv run bg3 mod diagnose-logs --mod <mod-slug> --severity warning --json
+
+# Filter by engine subsystem
+uv run bg3 mod diagnose-logs --subsystem Boosts --mod <mod-slug> --json
+uv run bg3 mod diagnose-logs --subsystem Stats --mod <mod-slug> --json
+uv run bg3 mod diagnose-logs --subsystem Osiris --mod <mod-slug> --json
+
+# Live stream active session
+uv run bg3 mod diagnose-logs --follow
+```
+
+---
+
+## 2. Automated Remediation Guidelines
+
+1. **Missing String Handles**: If logs indicate missing localization handles, run:
+   ```bash
+   uv run bg3 mod sync-localization --mod <mod-slug> --write --json
+   ```
+2. **Stat Typo / Missing Reference**: Correlate logged IDs to `Public/<ModName>_<UUID>/Stats/Generated/Data/`.
+3. **Circuit Breaker Guardrail**:
+   - Limit continuous diagnostic cycles to 3 iterations.
+   - If identical error signatures persist across 2 cycles, halt and prompt the user with log traces.

bg3_mod_studio-1.0.0b1/.agents/skills/bg3-document-mods/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: bg3-document-mods
+description: Orchestrate concurrent subagents to download, unpack, validate, and document BG3 mods into mods/<name>/README.md and update library.md. Use on /bg3-document-mods.
+---
+
+# BG3 Mod Documentation Orchestrator (`bg3-document-mods`)
+
+Coordinates concurrent worker subagents to fetch, unpack, validate, and document *Baldur's Gate 3* mods from `https://mod.io/g/baldursgate3`.
+
+Refer to specifications:
+- Subagent Launch Schema: [Subagent Launch Template](./resources/document_subagent_template.json)
+- Catalog Columns & Categories: [Catalog Specification](./references/library_catalog_spec.md)
+
+---
+
+> [!TIP]
+> Query the studio tool registry with `uv run bg3 tools search "<intent>" --json`.
+
+## Workflow
+
+```mermaid
+flowchart TD
+    Start["User triggers /bg3-document-mods"] --> Resolve["1. Resolve Mod Queries & Slugs"]
+    Resolve --> Dispatch["2. Launch Concurrent Subagents in Parallel"]
+    Dispatch --> Wait["3. Reactive Wait for Notifications"]
+    Wait --> Catalog["4. Update Catalog & Reindex Query DB"]
+    Catalog --> Present["5. Present Summary Results Table"]
+```
+
+### 1. Query Resolution & Subagent Dispatch
+Resolve mod titles, slugs, or numeric IDs. Launch one worker subagent per mod in parallel using the schema defined in [Subagent Launch Template](./resources/document_subagent_template.json), directing each worker to follow [`bg3-document-single-mod`](../bg3-document-single-mod/SKILL.md). Ensure all subagents inherit model configuration (`Model: "inherit"`).
+
+Stop calling tools and await reactive completion notifications without polling.
+
+### 2. Catalog & Reindex
+Once all subagents report status, update the centralized catalog and warm the query cache:
+- Update master catalog: `uv run bg3 modio update-catalog --write --json`
+- Reindex high-speed query database: `uv run bg3 query --reindex --json`
+
+### 3. Summary Presentation
+Deliver an executive summary table detailing mod name, status (Success/Failed), category, and relative spec link.
+
+---
+
+## Verification Gate
+
+Always verify catalog and cache updates before concluding:
+1. Verify `update-catalog` and `query --reindex` exit with code 0.
+2. Confirm all documented mods appear in `Mods/subscribed/library.md` under correct categories.
+3. Validate that relative links to `mods/<slug>/README.md` resolve to existing files.

bg3_mod_studio-1.0.0b1/.agents/skills/bg3-document-mods/references/library_catalog_spec.md

@@ -0,0 +1,22 @@
+# Library Catalog Specification & Categories
+
+## 1. Six-Column Schema (`mods/library.md`)
+
+Each cataloged mod row contains:
+1. **Mod Id**: Verified numeric mod.io ID.
+2. **Mod Name**: Formatted name of the mod.
+3. **Mod Slug**: Workspace folder slug.
+4. **Description**: Concise summary of mod features.
+5. **Features Documented**: Quantified count of implemented features.
+6. **Spec Link**: Relative markdown link to `mods/<slug>/README.md`.
+
+---
+
+## 2. Catalog Categories
+
+Mods are partitioned into 5 standardized markdown tables:
+- **Gear**: Weapons, armor, jewelry, vanity equipment.
+- **Spells**: Cantrips, level 1–9 spells, spell overhauls.
+- **Classes & Subclasses**: Classes, subclasses, custom progression trees.
+- **Progression & Rules**: Level cap extensions, feat intervals, stat curve mods.
+- **Utilities & Cheats**: Quality of life, convenience containers, respec tools.

bg3_mod_studio-1.0.0b1/.agents/skills/bg3-document-mods/resources/document_subagent_template.json

@@ -0,0 +1,11 @@
+{
+  "Subagents": [
+    {
+      "TypeName": "self",
+      "Role": "Mod Documenter - <Mod_Name>",
+      "Prompt": "Document the Baldur's Gate 3 mod: <MOD_QUERY>.\n1. Read and follow instructions in worker skill bg3-document-single-mod.\n2. Run: uv run bg3 modio extract --query \"<MOD_QUERY>\" --write-spec --json\n3. Confirm mods/<mod_slug>/README.md adheres to the Rich Features Schema.\n4. Return standardized status message:\n   - On Success: mod '<Mod Name>' successfully added to library — <Brief description>\n   - On Failure: mod '<Mod Name>' failed: <Brief explanation>",
+      "Workspace": "inherit",
+      "Model": "inherit"
+    }
+  ]
+}