goatchain-cli-darwin-arm64 0.0.73-beta.9 → 0.1.1

package/bin/skills-assets/pdf/scripts/render_cover.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * render_cover.js — Render cover.html → cover.pdf via Playwright.
+ *
+ * Usage:
+ *   node render_cover.js --input cover.html --out cover.pdf
+ *   node render_cover.js --input cover.html --out cover.pdf --wait 1200
+ *
+ * Exit codes: 0 success, 1 bad args, 2 dependency missing, 3 render error
+ */
+
+const path = require("path");
+const fs   = require("fs");
+
+function usage() {
+  console.error("Usage: node render_cover.js --input <file.html> --out <file.pdf> [--wait <ms>]");
+  process.exit(1);
+}
+
+// ── Arg parsing ────────────────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+let inputFile = null, outFile = null, waitMs = 800;
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--input" && args[i + 1]) { inputFile = args[++i]; }
+  else if (args[i] === "--out"   && args[i + 1]) { outFile   = args[++i]; }
+  else if (args[i] === "--wait"  && args[i + 1]) { waitMs    = parseInt(args[++i], 10); }
+}
+
+if (!inputFile || !outFile) usage();
+if (!fs.existsSync(inputFile)) {
+  console.error(JSON.stringify({ status: "error", error: `File not found: ${inputFile}` }));
+  process.exit(1);
+}
+
+// ── Playwright loader (tolerates global npm installs) ─────────────────────────
+function loadPlaywright() {
+  const { execSync } = require("child_process");
+  try { return require("playwright"); } catch (_) {}
+  try {
+    const root = execSync("npm root -g", { stdio: ["ignore","pipe","ignore"] }).toString().trim();
+    return require(path.join(root, "playwright"));
+  } catch (_) {}
+  console.error(JSON.stringify({
+    status: "error",
+    error: "playwright not found",
+    hint: "Run: npm install -g playwright && npx playwright install chromium"
+  }));
+  process.exit(2);
+}
+
+// ── Main ───────────────────────────────────────────────────────────────────────
+(async () => {
+  const { chromium } = loadPlaywright();
+
+  let browser;
+  try {
+    browser = await chromium.launch();
+  } catch (e) {
+    // Chromium binary missing — try installing
+    const { spawnSync } = require("child_process");
+    const r = spawnSync("npx", ["playwright", "install", "chromium"], { stdio: "inherit", shell: true });
+    if (r.status !== 0) {
+      console.error(JSON.stringify({
+        status: "error",
+        error: "Chromium not installed and auto-install failed",
+        hint: "Run: npx playwright install chromium"
+      }));
+      process.exit(2);
+    }
+    browser = await chromium.launch();
+  }
+
+  try {
+    const page = await browser.newPage();
+    const fileUrl = "file://" + path.resolve(inputFile);
+    await page.goto(fileUrl);
+    await page.waitForTimeout(waitMs);   // let CSS + any JS settle
+
+    await page.pdf({
+      path:            outFile,
+      width:           "794px",
+      height:          "1123px",
+      printBackground: true,
+    });
+
+    await browser.close();
+
+    // Basic sanity: output file must exist and be > 5 KB
+    const stat = fs.statSync(outFile);
+    if (stat.size < 5000) {
+      console.error(JSON.stringify({
+        status: "error",
+        error: "Output PDF is suspiciously small — cover may be blank",
+        hint:  "Check cover.html for render errors"
+      }));
+      process.exit(3);
+    }
+
+    console.log(JSON.stringify({
+      status: "ok",
+      out:    outFile,
+      size_kb: Math.round(stat.size / 1024),
+    }));
+
+  } catch (e) {
+    if (browser) await browser.close().catch(() => {});
+    console.error(JSON.stringify({ status: "error", error: String(e) }));
+    process.exit(3);
+  }
+})();

package/bin/skills-assets/plugin-creator/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: plugin-creator
+description: Create and scaffold Dim plugin directories with a required `.claude-plugin/plugin.json` manifest, optional skills/hooks/MCP components, and valid manifest defaults. Use when the user wants to create a new Dim plugin, add skills/hooks/MCP servers to a plugin, validate a plugin before sharing, or set up a plugin for local development under `~/.agents/plugins`.
+metadata:
+  short-description: Create or scaffold a Dim plugin
+---
+
+# Plugin Creator
+
+Scaffold a Dim plugin: a directory with a `.claude-plugin/plugin.json` manifest plus
+optional `skills/`, a `hooks` file, and an `.mcp.json`. Dim discovers plugins from
+`~/.agents/plugins/<name>/`: each plugin folder is self-describing, so placing one under
+`~/.agents/plugins` makes its skills, hooks, and MCP servers load on the next session.
+
+## Quick Start
+
+1. Scaffold the plugin. By default it is created live under `~/.agents/plugins/<name>/`,
+   so a new session picks it up immediately.
+
+```bash
+# Names are normalized to lower-case hyphen-case (<= 64 chars). The folder name and the
+# manifest `name` are always identical. Run from the skill root (the directory holding
+# this SKILL.md).
+python3 scripts/create_basic_plugin.py <plugin-name>
+```
+
+2. Edit `<plugin-path>/.claude-plugin/plugin.json` when the request gives specific
+   metadata (description, display name, version). The scaffold starts with valid defaults
+   and must not contain `[TODO: ...]` placeholders.
+
+3. Add the components the plugin needs:
+
+```bash
+python3 scripts/create_basic_plugin.py <plugin-name> \
+  --with-skills --with-hooks --with-mcp --with-assets
+```
+
+   - `--with-skills` creates `skills/<plugin-name>/SKILL.md`, a working starter skill, and
+     sets manifest `"skills": "./skills/"`.
+   - `--with-hooks` creates `hooks.json` and sets manifest `"hooks": "./hooks.json"`.
+   - `--with-mcp` creates `.mcp.json` and sets manifest `"mcpServers": "./.mcp.json"`.
+   - `--with-assets` creates an `assets/` folder for icons/logos.
+
+4. Build a plugin for git distribution instead of local dev with `--path`:
+
+```bash
+# Create under a repo or scratch directory you will push to git.
+python3 scripts/create_basic_plugin.py <plugin-name> --path <parent-directory>
+```
+
+5. Validate before handing back or sharing:
+
+```bash
+python3 scripts/validate_plugin.py <plugin-path>
+```
+
+6. **Tell the user to start a new session/thread.** Dim loads a plugin's skills, hooks, and
+   MCP servers when a session starts, so a plugin created or changed in the *current* session
+   only becomes usable in the *next* one. If you scaffolded the plugin mid-conversation, the
+   skill will not be callable here yet — the user must open a new session to use it.
+
+## What this skill creates
+
+- Plugin root at `<parent-directory>/<plugin-name>/` (default parent `~/.agents/plugins`).
+- Always `<plugin-root>/.claude-plugin/plugin.json` with the manifest shape Dim reads.
+- `<plugin-name>` is normalized:
+  - `My Plugin` → `my-plugin`
+  - `My--Plugin` → `my-plugin`
+  - underscores, spaces, and punctuation become `-`; consecutive hyphens collapse; result is
+    lower-case.
+- Optional, created only when requested:
+  - `skills/<plugin-name>/SKILL.md` (a starter skill)
+  - `hooks.json`
+  - `.mcp.json`
+  - `assets/`
+
+## Manifest
+
+Dim reads a small set of fields from `plugin.json`. The scaffold writes valid defaults for
+all of them:
+
+```json
+{
+  "name": "my-plugin",
+  "version": "0.1.0",
+  "description": "My Plugin plugin",
+  "interface": {
+    "displayName": "My Plugin",
+    "shortDescription": "Use My Plugin in Dim."
+  },
+  "skills": "./skills/",
+  "hooks": "./hooks.json",
+  "mcpServers": "./.mcp.json"
+}
+```
+
+Component paths (`skills`, `hooks`, `mcpServers`) appear only when their files exist. See
+`references/plugin-json-spec.md` for the full field guide and the exact sample.
+
+## Components
+
+- **Skills** — directories under `skills/<name>/` each containing a `SKILL.md` with valid
+  frontmatter (`name`, `description`). Dim discovers them automatically and loads them into
+  the system prompt.
+- **Hooks** — a JSON file (manifest `hooks` field) mapping lifecycle events to commands. Use
+  `${CLAUDE_PLUGIN_ROOT}` in command paths; Dim substitutes the plugin's absolute root at
+  runtime, e.g. `node "${CLAUDE_PLUGIN_ROOT}/hooks/on-start.js"`.
+- **MCP** — an `.mcp.json` with an `mcpServers` object. Server ids are namespaced as
+  `plugin:<plugin-name>/<serverId>`. Command paths support the same `${CLAUDE_PLUGIN_ROOT}`
+  substitution.
+
+## Required behavior
+
+- The outer folder name and `plugin.json` `"name"` are always the same normalized name.
+- Keep `.claude-plugin/plugin.json` present; never remove the required manifest.
+- Do not leave `[TODO: ...]` placeholders in the manifest.
+- Add a component path to the manifest only when its file actually exists. Keep `skills`,
+  `hooks`, and `mcpServers` out of the manifest when their companion files were not created.
+- Use `--force` only when overwriting an existing plugin path is intentional.
+- After creating or modifying a plugin, end by telling the user to start a new session/thread.
+  The current session loaded its skills, hooks, and MCP servers at startup and will not pick up
+  the new ones until a fresh session — do not claim the new skill is usable in this session.
+
+## Install and update
+
+For the full local-development loop, the git-sharing path, and component toggling, see
+`references/installing-and-updating.md`. In short:
+
+- **Local dev** — scaffold into `~/.agents/plugins/<name>/`, then start a new session. Dim
+  re-scans the directory and loads the plugin's skills, hooks, and MCP servers. Editing files
+  in place and starting another session picks up the changes.
+- **Share** — push the plugin directory to a git repo, then in the Dim desktop app open
+  Plugins → Add plugin and paste the git URL (`owner/repo` or a full URL). Dim reads the
+  manifest and installs the plugin into `~/.agents/plugins`.
+
+## Validation
+
+After editing this `SKILL.md`, run:
+
+```bash
+python3 ../skill-creator/scripts/quick_validate.py .
+```
+
+Before handing back a generated plugin, run:
+
+```bash
+python3 scripts/validate_plugin.py <plugin-path>
+```

package/bin/skills-assets/plugin-creator/references/installing-and-updating.md

@@ -0,0 +1,66 @@
+# Installing and updating Dim plugins
+
+A Dim plugin is a self-describing directory under `~/.agents/plugins/<name>/`. Disk is the
+single source of truth: Dim scans that directory, reads each `.claude-plugin/plugin.json`, and
+loads the plugin's components. Installing a plugin means placing its folder there; removing the
+folder removes the plugin.
+
+## Local development
+
+1. Scaffold the plugin directly under `~/.agents/plugins/<name>/` (the default of
+   `scripts/create_basic_plugin.py`):
+
+```bash
+python3 scripts/create_basic_plugin.py my-plugin --with-skills
+```
+
+2. Edit the manifest and component files.
+
+3. Start a **new session**. Dim re-scans `~/.agents/plugins`, and the plugin's skills, hooks,
+   and MCP servers load. A new session is the boundary at which changes are picked up.
+
+To iterate, edit files in place and start another session. Removing the plugin directory
+removes the plugin.
+
+## Activation by component
+
+- **Skills** — discovered from `~/.agents/plugins/*/skills/` and loaded into the system prompt
+  automatically. They also appear in the desktop Skills list.
+- **Hooks** — read from the file named by the manifest `hooks` field and registered on session
+  start. Command paths use `${CLAUDE_PLUGIN_ROOT}`, which Dim replaces with the plugin's
+  absolute root.
+- **MCP servers** — read from the `.mcp.json` file named by the manifest `mcpServers` field and
+  merged into the MCP runtime. An inline `mcpServers` object in `plugin.json` itself is not
+  supported — Dim silently ignores it (no error), so the component never loads. Server ids are
+  namespaced `plugin:<plugin-name>/<serverId>`.
+
+## Toggling components
+
+In the Dim desktop app, open Plugins → select the plugin to see its detail page. Each skill,
+hook, and MCP server has its own on/off switch, plus a master switch to enable or disable all
+components at once.
+
+## Sharing via git
+
+To distribute a plugin to other users:
+
+1. Build the plugin in a directory you will push to git (use `--path`):
+
+```bash
+python3 scripts/create_basic_plugin.py my-plugin --path ./plugins --with-skills
+```
+
+2. Commit and push the plugin directory (including `.claude-plugin/plugin.json`) to a git repo.
+
+3. In the Dim desktop app, open Plugins → Add plugin and paste the git source — either
+   `owner/repo` or a full git URL, with an optional ref (branch/tag). Dim clones the repo,
+   reads the manifest, and installs the plugin into `~/.agents/plugins/<name>/`, recording the
+   source in a `dim-install.json` provenance file.
+
+Updating a git-installed plugin is done from the same Add-plugin flow (reinstall from the
+source) or by editing the on-disk copy under `~/.agents/plugins` for local tweaks.
+
+The desktop app also has a separate Plugin Store tab that installs from a hosted marketplace
+(a zip archive, not a git clone) and marks the install with its own `.dimcode-market.json`
+provenance file instead of `dim-install.json`. That path is unrelated to plugin *creation* —
+it only matters if you're pointing a user at how to distribute a finished plugin.

package/bin/skills-assets/plugin-creator/references/plugin-json-spec.md

@@ -0,0 +1,148 @@
+# Plugin manifest spec (`.claude-plugin/plugin.json`)
+
+Dim recognizes a plugin by the presence of `.claude-plugin/plugin.json` at the plugin root (it
+also accepts the Codex-format `.codex-plugin/plugin.json` at the same root — this skill always
+scaffolds the Claude format, which both Dim and Claude Code read). It parses only the fields
+below; any other field is ignored. Keep the manifest minimal and valid.
+
+```json
+{
+  "name": "my-plugin",
+  "version": "0.1.0",
+  "description": "Brief plugin description",
+  "interface": {
+    "displayName": "My Plugin",
+    "shortDescription": "Short subtitle shown in the plugin list",
+    "logo": "./assets/logo.png"
+  },
+  "skills": "./skills/",
+  "hooks": "./hooks.json",
+  "mcpServers": "./.mcp.json"
+}
+```
+
+## Field guide
+
+### Top-level fields
+
+- `name` (`string`, required): Plugin identifier (lower-case hyphen-case, no spaces). Matches
+  the plugin folder name. Sanitized to `[A-Za-z0-9._-]`, max 128 chars.
+- `version` (`string`, optional): Strict semver, e.g. `0.1.0`.
+- `description` (`string`, optional): Short purpose summary. Falls back to
+  `interface.shortDescription` in the UI when absent.
+- `interface` (`object`, optional): Presentation metadata (see below).
+- `skills` (`string`, optional): Relative path to the skills directory, normally `./skills/`.
+- `hooks` (`string`, optional): Relative path to the hooks config file, e.g. `./hooks.json`.
+- `mcpServers` (`string`, optional): Relative path to an `.mcp.json` file, e.g. `./.mcp.json`.
+  An inline object is not supported — the runtime loads only a path string.
+
+### `interface` fields
+
+- `displayName` (`string`): User-facing title. Defaults to `name` when absent.
+- `shortDescription` (`string`): Brief subtitle for compact views.
+- `logo` (`string`): Relative path to a logo asset inside the plugin (for example
+  `./assets/logo.png`).
+
+### Path conventions
+
+- Component path values are relative to the plugin root and begin with `./`.
+- A component path appears in the manifest only when its file/directory exists. Do not declare
+  `skills`, `hooks`, or `mcpServers` when their companion files were not created.
+
+## Components
+
+### Skills
+
+Skills live under `skills/<skill-name>/SKILL.md`. Each `SKILL.md` starts with YAML
+frontmatter:
+
+```markdown
+---
+name: my-skill
+description: What it does and when to use it.
+---
+
+# My Skill
+
+Instructions for the assistant.
+```
+
+Dim discovers plugin skills automatically from `~/.agents/plugins/*/skills/` and loads them
+into the system prompt.
+
+### Hooks
+
+`hooks` points to a JSON file mapping lifecycle events to commands. Use
+`${CLAUDE_PLUGIN_ROOT}` in command paths — Dim substitutes the plugin's absolute root at
+runtime:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/on-start.js\"" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Only these event names are recognized: `SessionStart`, `SubagentStart`, `PreToolUse`,
+`PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`, `UserPromptSubmit`,
+`SubagentStop`, `Stop`. An unrecognized event name is not a partial failure — Dim drops every
+hook in that `hooks.json` file (logs a warning, registers nothing). Do not invent event names;
+when unsure which event fits, ask rather than guess.
+
+`type` must be the literal string `"command"` and `command` must be a non-empty string; that is
+the only spec shape Dim parses. Plugin hooks run with the same full host environment as the
+user's own hooks (not a restricted subset), so a plugin hook can read provider keys/tokens from
+the process env — call this out to the user if the plugin's hook touches secrets.
+
+### MCP servers
+
+`mcpServers` points to an `.mcp.json` file — a relative path string, never an inline object (an
+inline `mcpServers` object in `plugin.json` is silently ignored, not an error). Server ids are
+namespaced as `plugin:<plugin-name>/<serverId>`. Command paths support the same
+`${CLAUDE_PLUGIN_ROOT}` substitution (it resolves through the same `${VAR}` template mechanism as
+any other env var, so other `${VAR}` references also resolve against the host environment). The
+referenced `.mcp.json` has this shape:
+
+```json
+{
+  "mcpServers": {
+    "example": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/server.js"]
+    }
+  }
+}
+```
+
+`type: "http"` is also supported (`{"type": "http", "url": "...", "headers": {...}}`, optionally
+`"auth": {"type": "bearer", "token": "..."}`); `sse` / `streamable-http` are not supported.
+
+## Validation notes
+
+- `name` must be a non-empty string; the folder name must match it. Dim does not verify this
+  invariant itself — for a locally-placed plugin, mismatched folder/`name` silently uses the
+  folder name for skills/hooks/mcp resolution while the manifest `name` becomes only a display
+  label. Keep the two in lockstep.
+- `version`, when present, must be strict semver by this skill's convention. Dim's runtime does
+  not itself validate `version` — it accepts any non-empty string — so this rule is a
+  authoring-quality convention, not something a load failure would confirm.
+- `interface.logo` and any declared component path must point to real files/directories inside
+  the plugin.
+- The manifest `skills` field only toggles a UI "has skills" indicator; skill discovery always
+  scans `<plugin-root>/skills` regardless of this field's value or presence. Keep skills at
+  `./skills/` — pointing `skills` elsewhere does not relocate discovery.
+- Sub-skill `SKILL.md` files must have non-empty `name` and `description` frontmatter, and a
+  non-empty body after the closing `---`. A frontmatter-only file with no body is silently
+  dropped (not an error) — the skill just never appears.
+- The manifest must not contain `[TODO: ...]` placeholders.
+
+Run `scripts/validate_plugin.py <plugin-path>` before handing back a generated plugin.

package/bin/skills-assets/plugin-creator/scripts/create_basic_plugin.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+"""Scaffold a Dim plugin directory with a `.claude-plugin/plugin.json` manifest.
+
+Dim discovers plugins from ``~/.agents/plugins/<name>/``. The default parent is
+``~/.agents/plugins`` so a scaffolded plugin is live on the next session. Pass ``--path`` to
+build a plugin elsewhere (e.g. a git repo to share).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+
+MAX_PLUGIN_NAME_LENGTH = 64
+DEFAULT_PLUGIN_PARENT = Path.home() / ".agents" / "plugins"
+MANIFEST_DIR = ".claude-plugin"
+MANIFEST_FILE = "plugin.json"
+
+
+def normalize_plugin_name(plugin_name: str) -> str:
+    """Normalize a plugin name to lowercase hyphen-case."""
+    normalized = plugin_name.strip().lower()
+    normalized = re.sub(r"[^a-z0-9]+", "-", normalized)
+    normalized = normalized.strip("-")
+    normalized = re.sub(r"-{2,}", "-", normalized)
+    return normalized
+
+
+def validate_plugin_name(plugin_name: str) -> None:
+    if not plugin_name:
+        raise ValueError("Plugin name must include at least one letter or digit.")
+    if len(plugin_name) > MAX_PLUGIN_NAME_LENGTH:
+        raise ValueError(
+            f"Plugin name '{plugin_name}' is too long ({len(plugin_name)} characters). "
+            f"Maximum is {MAX_PLUGIN_NAME_LENGTH} characters."
+        )
+
+
+def display_name_from_plugin_name(plugin_name: str) -> str:
+    return " ".join(part.capitalize() for part in re.split(r"[-_]+", plugin_name))
+
+
+def build_plugin_json(
+    plugin_name: str,
+    *,
+    with_skills: bool,
+    with_hooks: bool,
+    with_mcp: bool,
+) -> dict[str, Any]:
+    """Build the manifest Dim reads. Only the fields Dim parses are written."""
+    display_name = display_name_from_plugin_name(plugin_name)
+    payload: dict[str, Any] = {
+        "name": plugin_name,
+        "version": "0.1.0",
+        "description": f"{display_name} plugin",
+        "interface": {
+            "displayName": display_name,
+            "shortDescription": f"Use {display_name} in Dim.",
+        },
+    }
+    # Component paths are added only when their companion files are created, so the manifest
+    # never points at something that does not exist.
+    if with_skills:
+        payload["skills"] = "./skills/"
+    if with_hooks:
+        payload["hooks"] = "./hooks.json"
+    if with_mcp:
+        payload["mcpServers"] = "./.mcp.json"
+    return payload
+
+
+def build_starter_skill(plugin_name: str) -> str:
+    """A minimal, valid starter skill so the plugin contributes something usable."""
+    display_name = display_name_from_plugin_name(plugin_name)
+    return (
+        "---\n"
+        f"name: {plugin_name}\n"
+        f"description: {display_name} starter skill. Replace this description with the real "
+        f"trigger so Dim knows when to use {display_name}.\n"
+        "---\n\n"
+        f"# {display_name}\n\n"
+        "Describe what this skill does and the steps the assistant should follow when it is "
+        "invoked. Keep instructions concrete and task-focused.\n"
+    )
+
+
+def write_json(path: Path, data: dict, force: bool) -> None:
+    if path.exists() and not force:
+        raise FileExistsError(f"{path} already exists. Use --force to overwrite.")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as handle:
+        json.dump(data, handle, indent=2)
+        handle.write("\n")
+
+
+def write_text(path: Path, text: str, force: bool) -> None:
+    if path.exists() and not force:
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Create a Dim plugin skeleton with a validation-ready plugin.json."
+    )
+    parser.add_argument("plugin_name")
+    parser.add_argument(
+        "--path",
+        default=str(DEFAULT_PLUGIN_PARENT),
+        help=(
+            "Parent directory for the plugin (defaults to ~/.agents/plugins, where Dim "
+            "discovers plugins). Pass another directory to build a plugin for git sharing."
+        ),
+    )
+    parser.add_argument(
+        "--with-skills",
+        action="store_true",
+        help="Create skills/<name>/SKILL.md starter skill and set manifest `skills`.",
+    )
+    parser.add_argument(
+        "--with-hooks",
+        action="store_true",
+        help="Create hooks.json and set manifest `hooks`.",
+    )
+    parser.add_argument(
+        "--with-mcp",
+        action="store_true",
+        help="Create .mcp.json and set manifest `mcpServers`.",
+    )
+    parser.add_argument(
+        "--with-assets",
+        action="store_true",
+        help="Create an assets/ directory for icons and logos.",
+    )
+    parser.add_argument("--force", action="store_true", help="Overwrite existing files")
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    raw_plugin_name = args.plugin_name
+    plugin_name = normalize_plugin_name(raw_plugin_name)
+    if plugin_name != raw_plugin_name:
+        print(f"Note: Normalized plugin name from '{raw_plugin_name}' to '{plugin_name}'.")
+    validate_plugin_name(plugin_name)
+
+    plugin_root = Path(args.path).expanduser().resolve() / plugin_name
+    plugin_root.mkdir(parents=True, exist_ok=True)
+
+    manifest_path = plugin_root / MANIFEST_DIR / MANIFEST_FILE
+    write_json(
+        manifest_path,
+        build_plugin_json(
+            plugin_name,
+            with_skills=args.with_skills,
+            with_hooks=args.with_hooks,
+            with_mcp=args.with_mcp,
+        ),
+        args.force,
+    )
+
+    if args.with_skills:
+        write_text(
+            plugin_root / "skills" / plugin_name / "SKILL.md",
+            build_starter_skill(plugin_name),
+            args.force,
+        )
+
+    if args.with_hooks:
+        # Empty hooks map; fill events with commands that use ${CLAUDE_PLUGIN_ROOT} paths.
+        write_json(plugin_root / "hooks.json", {"hooks": {}}, args.force)
+
+    if args.with_mcp:
+        write_json(plugin_root / ".mcp.json", {"mcpServers": {}}, args.force)
+
+    if args.with_assets:
+        (plugin_root / "assets").mkdir(parents=True, exist_ok=True)
+
+    print(f"Created plugin scaffold: {plugin_root}")
+    print(f"plugin manifest: {manifest_path}")
+
+
+if __name__ == "__main__":
+    main()