@heart-of-gold/toolkit 0.1.35 → 0.1.37

package/.claude-plugin/marketplace.json

@@ -15,19 +15,19 @@
       "name": "deep-thought",
       "source": "./plugins/deep-thought",
       "description": "The Answer Computer — reasoning tools for brainstorming, planning, and deep thinking",
-      "version": "0.2.5"
+      "version": "0.2.7"
     },
     {
       "name": "marvin",
       "source": "./plugins/marvin",
       "description": "The Paranoid Android — quality tools for code review, knowledge compounding, and work execution",
-      "version": "0.3.5"
+      "version": "0.3.7"
     },
     {
       "name": "babel-fish",
       "source": "./plugins/babel-fish",
       "description": "Universal Translator — media generation tools for audio, image, and video content",
-      "version": "0.2.3"
+      "version": "0.2.5"
     },
     {
       "name": "quellis",

package/README.md

@@ -26,13 +26,16 @@ bunx @heart-of-gold/toolkit install --to opencode
 
 ### Pi Coding Agent
 ```bash
-# Install shared skills into Pi's native skill directory
-bunx @heart-of-gold/toolkit install --to pi
-
-# Or install the package directly in Pi to get skills + pi-native extensions
+# Option A: install the package directly in Pi to get skills + pi-native extensions
 pi install npm:@heart-of-gold/toolkit
+
+# Option B: install shared skills only into Pi's native skill directory
+bunx @heart-of-gold/toolkit install --to pi
 ```
 
+**Important:** choose one Pi install path or the other.
+Do **not** use both the Pi package install and `install --to pi` at the same time, or Pi will report duplicate skill collisions on reload.
+
 Pi also discovers skills from the shared `~/.agents/skills/` location, so installs done with the OpenCode target are usable from Pi too.
 
 When installed as a Pi package, Heart of Gold exposes Pi-native extension commands for the flagship workflows:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heart-of-gold/toolkit",
-  "version": "0.1.35",
+  "version": "0.1.37",
   "type": "module",
   "description": "Cross-platform installer for Heart of Gold skills — works with Codex, OpenCode, Pi, Claude Code, and more",
   "bin": {

package/plugins/babel-fish/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "babel-fish",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Universal Translator — media generation tools for audio, image, video, and visualization",
   "author": {
     "name": "ondrej-svec",

package/plugins/babel-fish/skills/visualize/SKILL.md

@@ -21,6 +21,7 @@ Translating structured text into spatial understanding. The job is not to "turn
 Create one clear, polished, shareable visual artifact that:
 - matches the user's actual need
 - feels intentionally designed, not markdown restyled in boxes
+- is authored deliberately by the coding agent whenever possible
 - summarizes before detailing
 - uses browser HTML as the primary medium for substantial artifacts
 - falls back to terminal rendering only when that is the better fit
@@ -34,12 +35,16 @@ Create one clear, polished, shareable visual artifact that:
 
 Do **not** mirror the source document structure one-to-one unless the user explicitly wants a document view.
 
+The coding agent should be the **author** of the visual artifact.
+The renderer is a **finisher/fallback**, not the brain.
+
 Instead:
 1. understand the source
 2. decide what the artifact is trying to communicate
 3. choose the visual form that best serves that goal
-4. compress and reshape the content into a stronger visual story
-5. keep raw/source detail secondary or collapsible when possible
+4. author the HTML artifact directly when practical
+5. use toolkit renderers only as helpers or fallback paths
+6. keep raw/source detail secondary or collapsible when possible
 
 HTML should feel like:
 - a dashboard
@@ -115,6 +120,26 @@ Apply these defaults unless the user asks for something else:
 See also:
 - `docs/architecture/visualize-design-rules.md`
 
+## Writing Tone
+
+Write artifact copy like a strong product/design-systems editor:
+- concise
+- confident
+- specific
+- implementation-aware
+- high signal-to-noise
+
+Prefer lines like:
+- `One code change, bounded migration risk`
+- `Three priority tiers, one direction`
+- `Deferred — tracked, not scheduled`
+
+Avoid:
+- fluffy marketing copy
+- generic AI hype
+- long throat-clearing intros
+- repeating the source document verbatim
+
 ## Rules: Do
 
 - Decide the communication goal before choosing the renderer.
@@ -125,6 +150,7 @@ See also:
 - Use `roadmap` or richer execution-oriented views for plans when that improves understanding.
 - Use `architecture` views for system/design-heavy documents.
 - Keep raw source detail available, but secondary.
+- Make section labels do real editorial work: `Scope at a glance`, `Why this shape`, `What could go wrong`, `Deferred — tracked, not scheduled`.
 - Briefly explain why you chose the visualization mode when sharing the result.
 
 ## Rules: Don't
@@ -136,6 +162,8 @@ See also:
 - Do not use flashy gradients, glass, shadows, or color noise unless they clearly improve hierarchy.
 - Do not silently guess when the visualization choice is materially ambiguous.
 - Do not create multiple competing artifacts unless the user explicitly asks for comparison.
+- Do not preserve source heading order if a clearer narrative order exists.
+- Do not expose every extracted detail at the same visual weight.
 
 ## Expected Behavior
 
@@ -150,8 +178,9 @@ When invoked, behave like a visual editor, not a format converter.
    - UI/product visualization
 3. Choose the best artifact family.
 4. If uncertain, ask one concise question.
-5. Generate one HTML artifact first when browser rendering will help.
-6. Fall back to terminal rendering when browser/share is unavailable or explicitly not wanted.
+5. Prefer **agent-authored HTML** when browser rendering will help and the artifact needs real design judgment.
+6. Use toolkit renderers as a fallback when a quick structured artifact is sufficient.
+7. Fall back to terminal rendering when browser/share is unavailable or explicitly not wanted.
 
 If the user says "you decide," choose the clearest non-gimmicky artifact, not the fanciest one.
 
@@ -189,12 +218,15 @@ If the user does not care or says "you decide," choose the safest useful mode:
 - use `architecture` for clearly system-design-heavy docs
 - use `mindmap` only when the artifact is genuinely concise and branchy
 
-## Renderers
+## Authoring & Renderers
 
-Visualization has two implementation layers:
-- `scripts/smart-render.js` — renders one HTML artifact using the mode the coding agent chose, with a safe fallback
+Preferred implementation order:
+- **Agent-authored HTML** — primary path for high-quality shareable artifacts
+- `scripts/smart-render.js` — fallback renderer when the agent wants a quick scaffold or safe structured default
 - `scripts/render-mindmap/index.js` — specialized mind-map renderer for branchy content
 
+The key rule: if the artifact needs real design judgment, the coding agent should author the HTML directly instead of delegating the whole job to a parser.
+
 **Locations:**
 - `scripts/smart-render.js`
 - `scripts/render-mindmap/index.js`
@@ -220,6 +252,31 @@ fi
 
 ## Usage
 
+### Preferred: agent-authored HTML
+
+When quality matters more than speed, start from the shared authored-artifact template, write the HTML directly, then publish it.
+
+**Cross-platform preferred path:** use the Node helpers first. They work better across macOS, Linux, Windows, Codex, Claude Code, and Pi than shell-specific one-liners.
+
+```bash
+# 1. Print a fresh temp HTML path based on the shared template
+node /absolute/path/to/new-authored-artifact.js
+
+# 2. After editing the file, publish it
+node /absolute/path/to/publish-authored-html.js --url-only /tmp/path/from-step-1/artifact.html
+```
+
+**Shell fallback:** if Node helper usage is awkward in a specific harness, the `.sh` helpers are still available.
+
+Template and helper files:
+- `scripts/agent-artifact-template.html`
+- `scripts/new-authored-artifact.js`
+- `scripts/publish-authored-html.js`
+- `scripts/new-authored-artifact.sh`
+- `scripts/publish-authored-html.sh`
+
+### Fallback: toolkit renderer
+
 ```bash
 # Generate a safe default HTML visualization for a markdown file
 node "$SCRIPT" path/to/file.md --out /tmp/view.html
@@ -236,7 +293,29 @@ node "$(dirname "$SCRIPT")/render-mindmap/index.js" --html /tmp/map.html path/to
 
 ## HTML Share Flow
 
-Use the helper script when the user wants a browser URL and the share server is already configured:
+### Preferred share flow: publish agent-authored HTML
+
+Use this when the artifact needs stronger design judgment than the fallback renderer can provide.
+
+1. Create the scaffold with a standalone cross-platform command:
+   ```bash
+   node /absolute/path/to/new-authored-artifact.js
+   ```
+2. Read the printed temp path from stdout.
+3. Author the HTML artifact directly into that file.
+4. Publish it with a standalone cross-platform command:
+   ```bash
+   node /absolute/path/to/publish-authored-html.js --url-only /tmp/your-artifact.html
+   ```
+5. Read the returned URL from stdout.
+6. Return that URL to the user as the primary result.
+7. Briefly explain what was published and why this visual form was chosen.
+
+Shell helpers remain available as a fallback if a harness prefers `bash`.
+
+### Fallback share flow: render then publish
+
+Use the helper script when the user wants a browser URL and the fallback renderer is sufficient:
 
 ```bash
 bash scripts/render-and-share.sh path/to/file.md
@@ -249,18 +328,6 @@ This script:
 4. publishes the artifact to the configured local share server
 5. prints the publish result so you can return the URL
 
-### Recommended share flow
-
-1. Verify or assume the input markdown is ready.
-2. Choose the mode from context.
-3. Run:
-   ```bash
-   bash scripts/render-and-share.sh --mode <chosen-mode> --url-only [file]
-   ```
-4. Read the returned URL from stdout.
-5. Return that URL to the user as the primary result.
-6. Briefly explain what was published and why this mode was chosen.
-
 If publishing fails because the share server is not configured, say so clearly and fall back to terminal rendering unless the user wants to stop and run `share-server-setup` first.
 
 ## Terminal Rendering
@@ -289,6 +356,34 @@ Many harness bash panels truncate long output and wrap wide content, breaking al
 
 The default mode is vertical layout — boxes on main branches, compact leaves, about 40 chars wide.
 
+## Agent-Authored HTML Workflow
+
+When authoring HTML directly, follow this sequence:
+
+1. Read the source and decide the artifact family.
+2. Decide the audience and the first question the page should answer.
+3. Create the scaffold with `new-authored-artifact.js` or `new-authored-artifact.sh`.
+4. Draft the page in three layers:
+   - **summary layer** — what matters first
+   - **decision / execution layer** — the main story
+   - **source layer** — appendix, evidence, or raw detail
+5. Replace the template content with a real designed artifact.
+6. Keep source detail secondary.
+7. Publish with `publish-authored-html.js` or `publish-authored-html.sh`.
+
+Harness note:
+- prefer separate commands over complex one-liners
+- prefer the Node helpers for cross-platform behavior
+- avoid assuming `mktemp /tmp/name-XXXXXX.html` works on every shell; use the provided helper instead
+- if a harness only supports shell comfortably, use the `.sh` helpers as fallback
+
+For plans specifically:
+- do not dump the full task prose into the primary lanes
+- summarize workstreams into short cards or task tiles
+- show dependencies, risks, and acceptance separately
+- keep raw markdown only in an appendix or disclosure block
+- compress long task descriptions into one-sentence operational summaries first
+
 ## Required Output Structure
 
 For substantial HTML artifacts, prefer this structure:
@@ -319,6 +414,53 @@ For substantial HTML artifacts, prefer this structure:
 - what happens next
 - supporting source detail below
 
+## Expected Behavior by Artifact Family
+
+### Plan / roadmap artifacts
+Must usually include:
+- a top-line mission
+- scope or execution stats
+- grouped workstreams or phases
+- key decisions / rationale
+- explicit risks / acceptance posture
+- deferred or out-of-scope work if relevant
+
+### Architecture artifacts
+Must usually include:
+- system framing
+- major components / boundaries
+- integration or dependency context
+- key tradeoffs / decisions
+- assumptions / risks
+
+### Explainers
+Must usually include:
+- what this is
+- why it matters
+- the recommendation or conclusion
+- supporting evidence
+- what happens next
+
+## Recommended Authoring Moves
+
+When the artifact still feels too markdown-like, do one or more of these:
+- replace raw section names with editorial section labels
+- compress paragraphs into 1–3 sentence summary cards
+- convert repeated prose into chips, bullets, metrics, or compact lists
+- surface one key takeaway per section before the detail
+- split `what / why / risk / next` into separate visual units
+- move citations, raw notes, and source text into a secondary appendix
+
+## Guideline Authoring Workflow
+
+1. Restate the artifact purpose in one sentence.
+2. Decide the audience and primary question.
+3. Choose the artifact family and page shape.
+4. Extract only what is needed for the summary layer.
+5. Build the main body around grouped visual units, not source sections.
+6. Add source appendix or evidence only after the main page works.
+7. Run the quality gates before publishing.
+
 ## Quality Gates
 
 Before returning a shared HTML result, check mentally:
@@ -330,9 +472,37 @@ Before returning a shared HTML result, check mentally:
 - Is the chosen mode actually appropriate for the content?
 - If this is a plan, does it foreground execution rather than document order?
 - If this is a brainstorm, is it actually branch-shaped enough for a mind map?
+- Do the section titles help scanning?
+- Is secondary detail actually secondary?
 
 If the answer to several of these is no, reconsider the mode or ask the user.
 
+## Pattern Examples
+
+### Good plan framing
+- `Scope at a glance`
+- `Three priority tiers, one direction`
+- `What could go wrong`
+- `Deferred — tracked, not scheduled`
+
+### Good risk cards
+- short risk title
+- severity or posture badge
+- one-sentence mitigation
+- accepted vs mitigated distinction when relevant
+
+### Good summary stats
+- workstreams
+- tasks
+- code edits
+- new files
+- doctrine docs touched
+
+### Good appendix behavior
+- source plan path
+- cited references
+- raw plan or evidence hidden behind disclosure
+
 ## Input Formats
 
 ### Markdown (primary)

package/plugins/babel-fish/skills/visualize/scripts/agent-artifact-template.html

@@ -0,0 +1,169 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Heart of Gold Visual Artifact</title>
+  <style>
+    :root {
+      --bg: #09111f;
+      --bg-2: #0f1a31;
+      --panel: rgba(255,255,255,0.06);
+      --panel-soft: rgba(255,255,255,0.04);
+      --text: #eef2ff;
+      --muted: #b8c0d9;
+      --muted-2: #91a1c2;
+      --border: rgba(255,255,255,0.11);
+      --accent: #7c9cff;
+      --accent-2: #80e0d0;
+      --success: #86efac;
+      --warn: #fbbf24;
+      --danger: #fca5a5;
+      --shadow: 0 24px 80px rgba(0,0,0,0.34);
+      --radius-xl: 28px;
+      --radius-lg: 20px;
+      --radius-md: 16px;
+    }
+    * { box-sizing: border-box; }
+    html, body { margin: 0; padding: 0; }
+    html { color-scheme: dark; }
+    body {
+      font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      line-height: 1.55;
+      color: var(--text);
+      background:
+        radial-gradient(circle at top left, rgba(124,156,255,0.18), transparent 32%),
+        radial-gradient(circle at top right, rgba(128,224,208,0.12), transparent 24%),
+        linear-gradient(180deg, var(--bg-2) 0%, var(--bg) 100%);
+    }
+    main { max-width: 1480px; margin: 0 auto; padding: 36px 22px 84px; }
+    .hero, .section, .rail-card, .card, .stat, .chip, .callout {
+      border: 1px solid var(--border);
+      box-shadow: var(--shadow);
+      backdrop-filter: blur(14px);
+    }
+    .hero, .section, .rail-card { background: var(--panel); }
+    .hero {
+      padding: 28px;
+      border-radius: 32px;
+      margin-bottom: 24px;
+      display: grid;
+      gap: 16px;
+    }
+    .eyebrow {
+      color: var(--accent-2);
+      text-transform: uppercase;
+      letter-spacing: 0.16em;
+      font-size: 12px;
+      font-weight: 700;
+    }
+    h1 { margin: 0; font-size: clamp(34px, 4vw, 62px); line-height: 1.02; text-wrap: balance; }
+    h2 { margin: 0 0 12px; font-size: clamp(22px, 2vw, 32px); text-wrap: balance; }
+    h3 { margin: 0 0 10px; font-size: 18px; }
+    p { margin: 0; color: var(--muted); }
+    .hero p { max-width: 78ch; font-size: 17px; }
+    .page { display: grid; grid-template-columns: minmax(0, 1fr) minmax(260px, 320px); gap: 24px; align-items: start; }
+    .rail { position: sticky; top: 16px; display: grid; gap: 16px; }
+    .rail-card, .section { padding: 22px; border-radius: var(--radius-xl); }
+    .section { margin-bottom: 20px; }
+    .grid-2, .grid-3, .grid-4, .lane-grid { display: grid; gap: 16px; }
+    .grid-2 { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+    .grid-3 { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+    .grid-4 { grid-template-columns: repeat(4, minmax(0, 1fr)); }
+    .lane-grid { grid-template-columns: repeat(auto-fit, minmax(260px, 1fr)); }
+    .card, .stat, .lane, .callout {
+      padding: 18px;
+      border-radius: var(--radius-md);
+      background: var(--panel-soft);
+    }
+    .label {
+      color: var(--accent-2);
+      text-transform: uppercase;
+      letter-spacing: 0.11em;
+      font-size: 12px;
+      margin-bottom: 8px;
+    }
+    .stat .value { font-size: 28px; font-weight: 700; color: var(--text); margin-top: 6px; }
+    .stat .hint { color: var(--muted-2); font-size: 13px; margin-top: 6px; }
+    .chip-row { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 12px; }
+    .chip {
+      display: inline-flex; align-items: center; gap: 6px; padding: 8px 10px; border-radius: 999px;
+      background: rgba(255,255,255,0.05); color: var(--muted-2); font-size: 12px;
+    }
+    .chip.good { color: #c7ffd7; }
+    .chip.warn { color: #ffd88d; }
+    .chip.danger { color: #ffd1d1; }
+    details { margin-top: 12px; }
+    summary { cursor: pointer; font-weight: 600; }
+    .raw {
+      margin-top: 12px; padding: 14px; border-radius: 14px; border: 1px solid var(--border);
+      background: rgba(0,0,0,0.22); color: #d8e1fb; white-space: pre-wrap;
+      font: 13px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace;
+    }
+    a { color: #dce6ff; }
+    ul { margin: 0; padding-left: 18px; color: var(--muted); }
+    @media (max-width: 1080px) {
+      .page { grid-template-columns: 1fr; }
+      .rail { position: static; }
+      .grid-4 { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+    }
+    @media (max-width: 720px) {
+      main { padding: 20px 14px 60px; }
+      .hero, .section, .rail-card { padding: 18px; }
+      .grid-2, .grid-3, .grid-4 { grid-template-columns: 1fr; }
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <section class="hero">
+      <div class="eyebrow">Artifact Family</div>
+      <h1>Title</h1>
+      <p>One-line framing that explains what this artifact is, why it matters, and how to read it.</p>
+      <div class="chip-row">
+        <span class="chip">Mode</span>
+        <span class="chip">Audience</span>
+        <span class="chip">Purpose</span>
+      </div>
+    </section>
+
+    <div class="page">
+      <section>
+        <section class="section">
+          <div class="label">Summary</div>
+          <h2>Start With the Story</h2>
+          <div class="grid-4">
+            <div class="stat"><div class="label">Stat</div><div class="value">4</div><div class="hint">What this number means</div></div>
+            <div class="stat"><div class="label">Stat</div><div class="value">18</div><div class="hint">What this number means</div></div>
+            <div class="stat"><div class="label">Stat</div><div class="value">11</div><div class="hint">What this number means</div></div>
+            <div class="stat"><div class="label">Stat</div><div class="value">2</div><div class="hint">What this number means</div></div>
+          </div>
+        </section>
+
+        <section class="section">
+          <div class="label">Main Body</div>
+          <h2>Transform the Source</h2>
+          <div class="grid-2">
+            <div class="card">
+              <div class="label">Use cards</div>
+              <p>Summaries, priorities, risks, decisions, and recommendations should be grouped into visual units rather than dumped as prose.</p>
+            </div>
+            <div class="card">
+              <div class="label">Use disclosure</div>
+              <p>Keep raw source detail secondary. Put it behind details/summary or a source appendix.</p>
+            </div>
+          </div>
+        </section>
+      </section>
+
+      <aside class="rail">
+        <section class="rail-card">
+          <div class="label">Rail</div>
+          <h3>Keep It Focused</h3>
+          <p>Use the right rail for compact metadata, jump links, or decision context — not for a massive table of contents.</p>
+        </section>
+      </aside>
+    </div>
+  </main>
+</body>
+</html>

package/plugins/babel-fish/skills/visualize/scripts/new-authored-artifact.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+import { copyFileSync, mkdirSync, mkdtempSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { tmpdir } from 'node:os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const templatePath = join(__dirname, 'agent-artifact-template.html');
+const providedPath = process.argv[2] ? resolve(process.argv[2]) : null;
+
+const outPath = (() => {
+  if (providedPath) return providedPath;
+  const tempDir = mkdtempSync(join(tmpdir(), 'hog-visualize-artifact-'));
+  return join(tempDir, 'artifact.html');
+})();
+
+mkdirSync(dirname(outPath), { recursive: true });
+copyFileSync(templatePath, outPath);
+process.stdout.write(`${outPath}\n`);

package/plugins/babel-fish/skills/visualize/scripts/new-authored-artifact.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+TEMPLATE="$SCRIPT_DIR/agent-artifact-template.html"
+OUT_PATH="${1:-}"
+
+if [[ -z "$OUT_PATH" ]]; then
+  TEMP_BASE="$(mktemp /tmp/hog-visualize-artifact-XXXXXX)"
+  OUT_PATH="${TEMP_BASE}.html"
+fi
+
+cp "$TEMPLATE" "$OUT_PATH"
+printf '%s\n' "$OUT_PATH"

package/plugins/babel-fish/skills/visualize/scripts/publish-authored-html.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { homedir } from 'node:os';
+
+function fail(code, message, status = 1) {
+  process.stdout.write(`${JSON.stringify({ ok: false, error: { code, message } })}\n`);
+  process.exit(status);
+}
+
+function parseArgs(argv) {
+  const opts = {
+    htmlPath: null,
+    configPath: resolve(homedir(), '.agent-share', 'config.json'),
+    slug: '',
+    title: '',
+    alias: '',
+    urlOnly: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--config' && i + 1 < argv.length) opts.configPath = resolve(argv[++i]);
+    else if (arg === '--slug' && i + 1 < argv.length) opts.slug = argv[++i];
+    else if (arg === '--title' && i + 1 < argv.length) opts.title = argv[++i];
+    else if (arg === '--alias' && i + 1 < argv.length) opts.alias = argv[++i];
+    else if (arg === '--url-only') opts.urlOnly = true;
+    else if (arg === '--help') {
+      process.stdout.write('Usage: publish-authored-html.js <html-file> [--config PATH] [--slug STEM] [--title TITLE] [--alias ALIAS] [--url-only]\n');
+      process.exit(0);
+    } else if (!arg.startsWith('-') && !opts.htmlPath) {
+      opts.htmlPath = resolve(arg);
+    } else {
+      fail('INVALID_ARGS', `Unknown or misplaced argument: ${arg}`);
+    }
+  }
+
+  return opts;
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+
+  if (!opts.htmlPath) fail('MISSING_PATH', 'HTML file path is required.');
+  if (!existsSync(opts.configPath)) fail('MISSING_CONFIG', 'Share server config not found. Run share-server-setup first.');
+  if (!existsSync(opts.htmlPath)) fail('MISSING_PATH', `HTML file does not exist: ${opts.htmlPath}`);
+  if (!opts.htmlPath.toLowerCase().endsWith('.html')) fail('UNSUPPORTED_ARTIFACT', 'Only .html files are supported for authored artifact publishing.');
+
+  const cfg = JSON.parse(readFileSync(opts.configPath, 'utf8'));
+  const apiUrl = String(cfg?.server?.apiUrl || '').replace(/\/$/, '');
+  if (!apiUrl) fail('INVALID_CONFIG', 'share server apiUrl missing from config.');
+
+  const htmlBuffer = readFileSync(opts.htmlPath);
+  const form = new FormData();
+  form.append('artifact', new Blob([htmlBuffer], { type: 'text/html' }), basename(opts.htmlPath));
+  form.append('artifactType', 'html-file');
+  if (opts.slug) form.append('slug', opts.slug);
+  if (opts.title) form.append('title', opts.title);
+  if (opts.alias) form.append('alias', opts.alias);
+
+  const response = await fetch(`${apiUrl}/publish`, { method: 'POST', body: form });
+  const text = await response.text();
+
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    fail('INVALID_RESPONSE', `Share server returned non-JSON response: ${text}`, 1);
+  }
+
+  if (!response.ok || payload?.ok === false) {
+    process.stdout.write(`${JSON.stringify(payload)}\n`);
+    process.exit(1);
+  }
+
+  if (opts.urlOnly) {
+    process.stdout.write(`${payload.url || payload.viewerUrl || ''}\n`);
+    return;
+  }
+
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+}
+
+main().catch((error) => {
+  fail('PUBLISH_FAILED', error instanceof Error ? error.message : String(error));
+});

package/plugins/babel-fish/skills/visualize/scripts/publish-authored-html.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+HTML_PATH=""
+SLUG=""
+TITLE=""
+ALIAS=""
+URL_ONLY=0
+
+usage() {
+  cat <<'EOF'
+Usage: publish-authored-html.sh <html-file> [--slug STEM] [--title TITLE] [--alias ALIAS] [--url-only]
+
+Publish an already-authored HTML artifact via share-html.
+Use this when the coding agent wrote the HTML directly and only needs the share pipeline.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --slug) SLUG="$2"; shift 2 ;;
+    --title) TITLE="$2"; shift 2 ;;
+    --alias) ALIAS="$2"; shift 2 ;;
+    --url-only) URL_ONLY=1; shift ;;
+    --help) usage; exit 0 ;;
+    --*) echo "Unknown argument: $1" >&2; exit 1 ;;
+    *)
+      if [[ -z "$HTML_PATH" ]]; then
+        HTML_PATH="$1"
+        shift
+      else
+        echo "Unexpected positional argument: $1" >&2
+        exit 1
+      fi
+      ;;
+  esac
+done
+
+if [[ -z "$HTML_PATH" ]]; then
+  usage >&2
+  exit 1
+fi
+
+if [[ ! -f "$HTML_PATH" ]]; then
+  echo "HTML file does not exist: $HTML_PATH" >&2
+  exit 1
+fi
+
+find_share_publish_script() {
+  local candidates=(
+    "$SCRIPT_DIR/../../share-html/scripts/publish.sh"
+    "$SCRIPT_DIR/../../../marvin/skills/share-html/scripts/publish.sh"
+    "$SCRIPT_DIR/../../../../marvin/skills/share-html/scripts/publish.sh"
+    "$HOME/.agents/skills/share-html/scripts/publish.sh"
+    "$HOME/.pi/agent/skills/share-html/scripts/publish.sh"
+  )
+
+  for candidate in "${candidates[@]}"; do
+    if [[ -f "$candidate" ]]; then
+      printf '%s\n' "$candidate"
+      return 0
+    fi
+  done
+
+  find "$(cd "$SCRIPT_DIR/../../../../.." && pwd)" -path '*/share-html/scripts/publish.sh' 2>/dev/null | head -1
+}
+
+PUBLISH_SCRIPT="$(find_share_publish_script)"
+if [[ -z "$PUBLISH_SCRIPT" || ! -f "$PUBLISH_SCRIPT" ]]; then
+  echo '{"ok":false,"error":{"code":"MISSING_SHARE_HTML","message":"Could not find share-html publish.sh. Install the share-html skill first."}}'
+  exit 1
+fi
+
+CMD=(bash "$PUBLISH_SCRIPT" "$HTML_PATH")
+if [[ -n "$SLUG" ]]; then CMD+=(--slug "$SLUG"); fi
+if [[ -n "$TITLE" ]]; then CMD+=(--title "$TITLE"); fi
+if [[ -n "$ALIAS" ]]; then CMD+=(--alias "$ALIAS"); fi
+
+PUBLISH_JSON="$(${CMD[@]})"
+
+if [[ "$URL_ONLY" -eq 1 ]]; then
+  python3 - <<'PY' "$PUBLISH_JSON"
+import json, sys
+payload = json.loads(sys.argv[1])
+if not payload.get("ok", True):
+    print(json.dumps(payload))
+    raise SystemExit(1)
+print(payload.get("url") or payload.get("viewerUrl") or "")
+PY
+else
+  printf '%s\n' "$PUBLISH_JSON"
+fi

package/plugins/deep-thought/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "deep-thought",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "The Answer Computer — reasoning tools for brainstorming, planning, architecture design, and deep thinking",
   "author": {
     "name": "ondrej-svec",

package/plugins/marvin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "marvin",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "The Paranoid Android — quality tools for code review, knowledge compounding, and work execution",
   "author": {
     "name": "ondrej-svec",

package/src/commands/install.ts

@@ -1,7 +1,9 @@
 import { defineCommand } from "citty";
 import { loadAllPlugins, loadPlugin } from "../parsers/claude";
 import { targets } from "../targets/index";
-import { resolve } from "path";
+import { resolve, join } from "path";
+import { existsSync } from "fs";
+import { execSync } from "child_process";
 
 export const installCommand = defineCommand({
   meta: {
@@ -27,6 +29,20 @@ export const installCommand = defineCommand({
   },
   async run({ args }) {
     const targetName = args.to;
+
+    if (targetName === "pi") {
+      try {
+        const npmRoot = execSync("npm root -g", { encoding: "utf8" }).trim();
+        const packagePath = join(npmRoot, "@heart-of-gold", "toolkit", "package.json");
+        if (existsSync(packagePath)) {
+          console.warn("Warning: @heart-of-gold/toolkit is already installed as a Pi package.");
+          console.warn("Using 'install --to pi' as well will create duplicate Pi skill collisions on reload.");
+          console.warn("Prefer one Pi install path: either 'pi install npm:@heart-of-gold/toolkit' or 'bunx @heart-of-gold/toolkit install --to pi'.\n");
+        }
+      } catch {
+        // ignore detection failures and proceed normally
+      }
+    }
     const target = targets[targetName];
     if (!target) {
       const available = Object.keys(targets).join(", ");