@heart-of-gold/toolkit 0.1.35 → 0.1.36

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.6"
     },
     {
       "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.6"
     },
     {
       "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.4"
     },
     {
       "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.36",
   "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.4",
   "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
@@ -150,8 +155,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 +195,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 +229,23 @@ 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.
+
+```bash
+HTML_OUT="$(bash "$(dirname "$SCRIPT")/new-authored-artifact.sh")"
+# edit the generated template at $HTML_OUT
+bash "$(dirname "$SCRIPT")/publish-authored-html.sh" --url-only "$HTML_OUT"
+```
+
+Template and helper files:
+- `scripts/agent-artifact-template.html`
+- `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 +262,26 @@ 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:
+   ```bash
+   HTML_OUT="$(bash "$(dirname "$SCRIPT")/new-authored-artifact.sh")"
+   ```
+2. Author the HTML artifact directly into that file.
+3. Publish it:
+   ```bash
+   bash "$(dirname "$SCRIPT")/publish-authored-html.sh" --url-only "$HTML_OUT"
+   ```
+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 visual form was chosen.
+
+### 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 +294,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 +322,23 @@ 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.sh`.
+4. Replace the template content with a real designed artifact.
+5. Keep source detail secondary.
+6. Publish with `publish-authored-html.sh`.
+
+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
+
 ## Required Output Structure
 
 For substantial HTML artifacts, prefer this structure:

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.sh

@@ -0,0 +1,13 @@
+#!/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
+  OUT_PATH="$(mktemp /tmp/hog-visualize-artifact-XXXXXX.html)"
+fi
+
+cp "$TEMPLATE" "$OUT_PATH"
+printf '%s\n' "$OUT_PATH"

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.6",
   "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.6",
   "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(", ");