fix(distribution): move the rules exports out of agents/; check plugin installs in CI

5a56f5e put the AGENTS.md and Copilot exports under agents/. Claude Code
loads every agents/*.md in a plugin as a subagent, so the plugin would have
shipped a bogus AGENTS subagent. claude plugin validate --strict caught it
("No description in frontmatter ... this agent"). The exports now live in
exports/, with a comment in build_plugin_dist.py saying why. The Claude
marketplace also gains the metadata.description that --strict asked for.

New plugin-install.yml (#497): build plugin-dist, run claude plugin validate
--strict on the root plugin, live-session and the marketplace, then install
both plugins into a throwaway CLAUDE_CONFIG_DIR and check they are listed.
The weekly run also installs from the published plugin-dist branch.
Verified locally with Claude Code 2.1.296: all three validate strictly,
both plugins install from a fresh dist.

Closes #497

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: TM Hospitality Strategies <TMHospitalityStrategies@gmail.com>

Author: TMHSDigital

.claude-plugin/marketplace.json

@@ -4,6 +4,9 @@
     "name": "TMHSDigital",
     "url": "https://github.com/TMHSDigital"
   },
+  "metadata": {
+    "description": "Blender Python skills and rules for AI agents (blender-developer-tools), plus the opt-in Blender Lab MCP live session (blender-live-session)."
+  },
   "plugins": [
     {
       "name": "blender-developer-tools",

.github/workflows/plugin-install.yml

@@ -0,0 +1,85 @@
+name: Plugin install check
+
+# ROADMAP 1.0 criterion: "Install paths that work and are tested" (#497).
+# Builds the plugin-dist tree, validates every manifest with Claude Code's own
+# validator in --strict mode, then installs both plugins into a throwaway
+# config directory and checks they are listed and enabled. On the weekly run
+# it also installs from the published plugin-dist branch, which is what users
+# actually add. No account or API key is involved: plugin commands are local.
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 10 * * 3"   # weekly, Wednesday 10:00 UTC
+  push:
+    branches: [main]
+    paths:
+      - ".claude-plugin/**"
+      - ".cursor-plugin/**"
+      - "live-session/**"
+      - "skills/**"
+      - "claude/**"
+      - "exports/**"
+      - "scripts/build_plugin_dist.py"
+      - ".github/workflows/plugin-install.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - ".claude-plugin/**"
+      - ".cursor-plugin/**"
+      - "live-session/**"
+      - "skills/**"
+      - "claude/**"
+      - "exports/**"
+      - "scripts/build_plugin_dist.py"
+      - ".github/workflows/plugin-install.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  install:
+    name: Validate and install the plugins (Claude Code)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      CLAUDE_CODE_VERSION: "2.1.296"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Install the Claude Code CLI (pinned)
+        run: npm install -g "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}"
+
+      - name: Build plugin-dist and validate it strictly
+        run: |
+          set -euo pipefail
+          python3 scripts/build_plugin_dist.py --out "$RUNNER_TEMP/dist"
+          for target in "$RUNNER_TEMP/dist" "$RUNNER_TEMP/dist/live-session" \
+                        "$RUNNER_TEMP/dist/.claude-plugin/marketplace.json"; do
+            claude plugin validate --strict "$target"
+          done
+
+      - name: Install both plugins from the build into a clean profile
+        env:
+          CLAUDE_CONFIG_DIR: ${{ runner.temp }}/claude-cfg-local
+        run: |
+          set -euo pipefail
+          claude plugin marketplace add "$RUNNER_TEMP/dist"
+          claude plugin install blender-developer-tools@blender-developer-tools
+          claude plugin install blender-live-session@blender-developer-tools
+          list=$(claude plugin list)
+          echo "$list"
+          for p in blender-developer-tools@blender-developer-tools blender-live-session@blender-developer-tools; do
+            echo "$list" | grep -qF "$p" || { echo "::error::$p is not listed after install"; exit 1; }
+          done
+
+      - name: Install from the published plugin-dist branch (weekly)
+        if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+        env:
+          CLAUDE_CONFIG_DIR: ${{ runner.temp }}/claude-cfg-published
+        run: |
+          set -euo pipefail
+          claude plugin marketplace add "TMHSDigital/Blender-Developer-Tools@plugin-dist"
+          claude plugin install blender-developer-tools@blender-developer-tools
+          claude plugin install blender-live-session@blender-developer-tools
+          claude plugin list

.github/workflows/validate.yml

@@ -364,7 +364,7 @@ jobs:
             exit 1
           fi
 
-      - name: Check the rules exports (claude/, agents/AGENTS.md, Copilot instructions) are regenerated from rules/*.mdc
+      - name: Check the rules exports (claude/, exports/AGENTS.md, Copilot instructions) are regenerated from rules/*.mdc
         run: python3 scripts/build_claude_rules.py --check
 
       - name: Check examples/index.json and each skill's Runnable examples section are regenerated

README.md

@@ -85,12 +85,12 @@ Neither agent needs a clone of `main`: both install the slim `plugin-dist` build
   # Skills: agents that read .agents/skills/ (Codex, Cursor project skills)
   mkdir -p .agents/skills && cp -r bdt/skills/* .agents/skills/
   # Rules: agents that read AGENTS.md (Codex, Windsurf, Gemini CLI, Copilot's coding agent)
-  cat bdt/agents/AGENTS.md >> AGENTS.md
+  cat bdt/exports/AGENTS.md >> AGENTS.md
   # Rules: GitHub Copilot path-scoped instructions (applies to **/*.py)
-  mkdir -p .github/instructions && cp bdt/agents/copilot/blender-python.instructions.md .github/instructions/
+  mkdir -p .github/instructions && cp bdt/exports/copilot/blender-python.instructions.md .github/instructions/
   ```
 
-  `agents/AGENTS.md` and the Copilot file are generated from `rules/` by `scripts/build_claude_rules.py`, and CI fails if they fall out of date. The plugin-dist build fails if either file is missing. The layouts follow each agent's documented conventions; CI does not run the agents themselves.
+  `exports/AGENTS.md` and the Copilot file are generated from `rules/` by `scripts/build_claude_rules.py`, and CI fails if they fall out of date. The plugin-dist build fails if either file is missing. The layouts follow each agent's documented conventions; CI does not run the agents themselves.
 
 ### Live Blender session (MCP)
 

agents/AGENTS.md exports/AGENTS.mdagents/AGENTS.md renamed to exports/AGENTS.md

@@ -10,9 +10,9 @@
   second clone; Claude loads it when writing or reviewing bpy code.
 - claude/blender-rules.md: for always-on use, imported from a project's
   CLAUDE.md with ``@path/to/Blender-Developer-Tools/claude/blender-rules.md``.
-- agents/AGENTS.md: for agents that read AGENTS.md (Codex, Windsurf, Gemini
+- exports/AGENTS.md: for agents that read AGENTS.md (Codex, Windsurf, Gemini
   CLI, Copilot's coding agent); append it to a project's AGENTS.md (#376).
-- agents/copilot/blender-python.instructions.md: a GitHub Copilot path-scoped
+- exports/copilot/blender-python.instructions.md: a GitHub Copilot path-scoped
   instructions file (``applyTo: "**/*.py"``, the rules' own scope) for a
   project's .github/instructions/.
 
@@ -32,8 +32,8 @@
 REPO = Path(__file__).resolve().parent.parent
 OUT = REPO / "claude" / "blender-rules.md"
 SKILL_OUT = REPO / "claude" / "skills" / "blender-rules" / "SKILL.md"
-AGENTS_OUT = REPO / "agents" / "AGENTS.md"
-COPILOT_OUT = REPO / "agents" / "copilot" / "blender-python.instructions.md"
+AGENTS_OUT = REPO / "exports" / "AGENTS.md"
+COPILOT_OUT = REPO / "exports" / "copilot" / "blender-python.instructions.md"
 COPILOT_FRONT = """---
 applyTo: "**/*.py"
 ---
@@ -102,7 +102,7 @@ def main() -> int:
             print(f"{', '.join(stale)} stale; run python scripts/build_claude_rules.py",
                   file=sys.stderr)
             return 1
-        print("rules exports (claude/, agents/AGENTS.md, agents/copilot/) are up to date")
+        print("rules exports (claude/, exports/AGENTS.md, exports/copilot/) are up to date")
         return 0
     for path, new in outputs().items():
         path.parent.mkdir(parents=True, exist_ok=True)

…s/copilot/blender-python.instructions.md …s/copilot/blender-python.instructions.mdagents/copilot/blender-python.instructions.md renamed to exports/copilot/blender-python.instructions.md agents/copilot/blender-python.instructions.md renamed to exports/copilot/blender-python.instructions.md

@@ -35,7 +35,7 @@
 # the Blender Lab MCP server (launched with uvx from a pinned upstream commit;
 # GPL, so referenced, never vendored) and its skill. It is opt-in, so the core
 # plugin starts no server (#483).
-DIRS = ("skills", "claude", "agents", "rules", "snippets", "templates", "live-session")
+DIRS = ("skills", "claude", "exports", "rules", "snippets", "templates", "live-session")
 # The Cursor manifest ships too, so Cursor users can install the same slim
 # tree as a local plugin (~/.cursor/plugins/local/) instead of the full repo.
 # assets/favicon.svg is the Cursor manifest's "logo".
@@ -168,8 +168,9 @@ def verify(out: Path, size: int) -> list[str]:
             errors.append(f"{d.relative_to(out)} has no SKILL.md")
     if not (out / "claude" / "skills" / "blender-rules" / "SKILL.md").is_file():
         errors.append("blender-rules skill missing")
-    # The README's "Other agents" commands copy these (#376).
-    for rel in ("agents/AGENTS.md", "agents/copilot/blender-python.instructions.md"):
+    # The README's "Other agents" commands copy these (#376). Not agents/:
+    # Claude Code would load every agents/*.md in the plugin as a subagent.
+    for rel in ("exports/AGENTS.md", "exports/copilot/blender-python.instructions.md"):
         if not (out / rel).is_file():
             errors.append(f"{rel} missing (the README's other-agents commands copy it)")
     cursor = json.loads((out / ".cursor-plugin" / "plugin.json").read_text(encoding="utf-8"))

scripts/build_claude_rules.py

@@ -20,7 +20,7 @@
   "installSteps": [
     "<strong>Claude Code:</strong> <code>/plugin marketplace add TMHSDigital/Blender-Developer-Tools@plugin-dist</code> then <code>/plugin install blender-developer-tools@blender-developer-tools</code>. The 20 skills load when a task matches; the rules come along as the <code>blender-rules</code> skill",
     "<strong>Cursor:</strong> <code>git clone --branch plugin-dist --single-branch https://github.com/TMHSDigital/Blender-Developer-Tools.git ~/.cursor/plugins/local/blender-developer-tools</code>, then reload the window; Customize lists the 20 skills and 11 rules, and the plugin applies the rules for you. This clones only the 0.3 MB plugin build, not <code>main</code>",
-    "<strong>Other agents (Codex, Copilot, Windsurf):</strong> clone the same slim build (<code>git clone --branch plugin-dist --single-branch https://github.com/TMHSDigital/Blender-Developer-Tools.git</code>) and copy its <code>skills/*</code> into <code>.agents/skills/</code>, append <code>agents/AGENTS.md</code> to your project's <code>AGENTS.md</code> for the rules, and for Copilot copy <code>agents/copilot/blender-python.instructions.md</code> into <code>.github/instructions/</code>",
+    "<strong>Other agents (Codex, Copilot, Windsurf):</strong> clone the same slim build (<code>git clone --branch plugin-dist --single-branch https://github.com/TMHSDigital/Blender-Developer-Tools.git</code>) and copy its <code>skills/*</code> into <code>.agents/skills/</code>, append <code>exports/AGENTS.md</code> to your project's <code>AGENTS.md</code> for the rules, and for Copilot copy <code>exports/copilot/blender-python.instructions.md</code> into <code>.github/instructions/</code>",
     "<strong>Optional, live session:</strong> <code>/plugin install blender-live-session@blender-developer-tools</code> adds the official Blender Lab MCP server (needs <code>uv</code> and Blender 5.1+ with its add-on) so the agent can inspect and drive your open scene, plus a skill that has it read before it mutates and prove changes headless. See the README's <a href=\"https://github.com/TMHSDigital/Blender-Developer-Tools#live-blender-session-mcp\">Live Blender session</a>",
     "Grab <code>snippets/</code> and <code>templates/</code> as starting points for add-ons and headless batch jobs"
   ],