@heart-of-gold/toolkit 0.1.34 → 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.4"
+      "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.4"
+      "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.2"
+      "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.34",
+  "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.2",
+  "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

@@ -1,10 +1,10 @@
 ---
 name: visualize
 description: >
-  Render mind maps and tree visualizations from markdown. Prefer shareable HTML first for brainstorms, plans,
-  architecture docs, and other structured workflow artifacts when share-html infrastructure is configured;
-  otherwise fall back to terminal output for quick local inspection. Works on markdown files or any structured
-  content. Triggers: visualize, mindmap, mind map, show me the structure, draw a map.
+  Create shareable HTML visual artifacts from markdown, plans, architecture docs, brainstorms, and other structured
+  content. Prefer browser-viewable HTML first when it will materially improve clarity or sharing; otherwise fall back
+  to terminal rendering. Triggers: visualize, mindmap, mind map, show me the structure, draw a map, make this clear,
+  make this visual.
 allowed-tools:
   - Read
   - Bash
@@ -14,24 +14,202 @@ allowed-tools:
 
 # Visualize — Babel Fish
 
-Translating structured text into spatial understanding. Because walls of text hide structure that pictures reveal.
+Translating structured text into spatial understanding. The job is not to "turn markdown into HTML." The job is to create a visual artifact that helps a human understand the material faster.
+
+## Mission
+
+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
 
 ## Boundaries
 
 - MAY: read files, generate terminal mind maps, generate temporary HTML artifacts, run renderer/share scripts via bash
 - MAY NOT: modify project files, create persistent files outside temp/output artifacts, install unrelated packages
 
-## The Renderers
+## Core Principle
+
+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. 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
+- an explainer
+- a roadmap
+- an architecture brief
+- a deliberate mind map
+
+Not like:
+- a markdown page with nicer CSS
+
+## Artifact Families
+
+These are guidance categories for the coding agent. They are not rigid parser outputs.
+
+### `outline`
+Use when the user wants:
+- document structure
+- a reading aid
+- a faithful but polished source-oriented view
+- a safe fallback when a richer artifact is not justified
+
+### `roadmap`
+Use when the source is best understood as:
+- phases
+- priorities
+- sequencing
+- workstreams
+- execution flow
+
+### `architecture`
+Use when the source is best understood as:
+- components
+- boundaries
+- integrations
+- decisions
+- responsibilities
+
+### `mindmap`
+Use only when the content is genuinely:
+- concise
+- branchy
+- idea-oriented
+- better understood spatially than sequentially
+
+### `explainer`
+Use when the artifact should help another human quickly understand:
+- the recommendation
+- tradeoffs
+- key decisions
+- what matters and why
+
+### `mockup`
+Use when the user really wants:
+- product/UI concept visualization
+- believable interface framing
+- layout and interaction-oriented representation
+
+## Style Foundations
+
+Apply these defaults unless the user asks for something else:
+
+- calm, high-contrast visual language
+- restrained accent usage
+- strong hierarchy and generous spacing
+- summary-first information architecture
+- progressive disclosure for dense detail
+- cards, panels, lanes, chips, and callouts over markdown-heavy paragraphs
+- readable max-widths for prose
+- sticky navigation only when it helps, never as the dominant element
+- polished but restrained effects; no gimmicky AI-demo chrome
+
+See also:
+- `docs/architecture/visualize-design-rules.md`
+
+## Rules: Do
+
+- Decide the communication goal before choosing the renderer.
+- Prefer shareable HTML for substantial workflow artifacts when `share-html` is configured.
+- Transform the source into a view model in your head before rendering: summary, priorities, risks, dependencies, decisions, outcomes.
+- Lead with a strong first screen: title, one-line mission, key takeaways, and obvious next scan targets.
+- Convert dense content into visual units where appropriate: cards, grouped sections, lanes, side panels, chips, callouts, expandable details.
+- 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.
+- Briefly explain why you chose the visualization mode when sharing the result.
+
+## Rules: Don't
+
+- Do not treat HTML generation as a markdown restyling task.
+- Do not dump long raw paragraphs into large cards as the main UI.
+- Do not let the table of contents dominate the page.
+- Do not force a mind map onto content that is not naturally branch-shaped.
+- 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.
+
+## Expected Behavior
+
+When invoked, behave like a visual editor, not a format converter.
+
+1. Read the source or infer the source from context.
+2. Decide whether the user needs:
+   - structure comprehension
+   - execution clarity
+   - system understanding
+   - stakeholder explanation
+   - UI/product visualization
+3. Choose the best artifact family.
+4. If uncertain, ask one concise question.
+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.
+
+## Uncertainty Protocol
+
+When the best visualization is not clear, do **not** silently guess if the choice would materially affect usefulness.
 
-Visualization now has two layers:
-- `scripts/smart-render.js` — renders one HTML artifact using the mode the coding agent chose (or a safe fallback)
+Ask **one concise question at a time**:
+- state the decision in plain language
+- offer 2-4 explicit options
+- include a recommended option when you have one
+- keep option labels outcome-focused, not renderer-jargon-first
+
+Good pattern:
+- "Which would help most here?"
+- `Roadmap` — show phases, sequencing, and implementation progress
+- `Outline` — show the document structure clearly
+- `Mind map` — show branching ideas and relationships
+- `Architecture view` — show components, boundaries, and decisions
+
+If the harness supports structured choices, use them.
+If not, use a short plain-text question such as:
+
+```text
+I can visualize this a few different ways. Which would be most useful?
+1. Roadmap — phases and tasks
+2. Outline — document structure
+3. Mind map — branching ideas
+4. Architecture view — components and boundaries
+```
+
+If the user does not care or says "you decide," choose the safest useful mode:
+- default to `outline`
+- use `roadmap` for clearly execution-heavy plans
+- use `architecture` for clearly system-design-heavy docs
+- use `mindmap` only when the artifact is genuinely concise and branchy
+
+## Authoring & Renderers
+
+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`
 
-**To find the smart renderer path**, locate it by searching for `smart-render.js`:
+To find the smart renderer path:
+
 ```bash
 # Option 1: Use CLAUDE_PLUGIN_ROOT if available
 SCRIPT="${CLAUDE_PLUGIN_ROOT}/skills/visualize/scripts/smart-render.js"
@@ -40,7 +218,8 @@ SCRIPT="${CLAUDE_PLUGIN_ROOT}/skills/visualize/scripts/smart-render.js"
 SCRIPT=$(find ~/.claude/plugins -path "*/babel-fish/skills/visualize/scripts/smart-render.js" 2>/dev/null | head -1)
 ```
 
-**First run:** If `node_modules/` doesn't exist in the mind-map renderer directory, run `npm install` there first:
+First run for the mind-map renderer:
+
 ```bash
 RENDER_DIR=$(dirname "$SCRIPT")/render-mindmap
 if [ ! -d "$RENDER_DIR/node_modules" ]; then
@@ -50,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
@@ -64,9 +260,28 @@ node "$SCRIPT" path/to/file.md --mode mindmap --out /tmp/view.html
 node "$(dirname "$SCRIPT")/render-mindmap/index.js" --html /tmp/map.html path/to/file.md
 ```
 
-### Shareable HTML flow
+## HTML Share Flow
+
+### 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 share server is already configured. It now generates one polished HTML artifact first, then publishes it:
+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
@@ -79,201 +294,112 @@ This script:
 4. publishes the artifact to the configured local share server
 5. prints the publish result so you can return the URL
 
-## Rendering Behavior
-
-- **Auto-depth:** If no `--depth` is specified, the renderer tries depths 3, 2, 1 and picks the deepest that fits the terminal width.
-- **Pruning:** Long labels are truncated with `…`. Nodes with many children show the first few plus `+N more`.
-- **Colors** (via ANSI, visible in Claude Code bash output):
-  - Root: bold white on blue
-  - Depth 1: bold cyan
-  - Depth 2: green
-  - Depth 3: yellow
-  - Depth 4+: dim
-
-## Phase 0 — Determine What to Visualize
-
-First decide whether this should be a browser/shareable HTML view or a quick terminal view.
+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.
 
-**Prefer browser/shareable HTML first when:**
-- the source is a brainstorm, plan, architecture doc, or other structured workflow artifact
-- the user asks to open it in a browser
-- the user wants to share the result with another person or device
-- the structure is large enough that browser navigation is more useful than terminal rendering
-- `share-html` is configured
+## Terminal Rendering
 
-**Prefer terminal rendering when:**
+Use terminal rendering when:
 - share-html is not configured
-- the user explicitly wants a quick terminal-only look
-- the environment is SSH-heavy and the browser/share path is not requested
+- the user explicitly wants terminal-only output
+- a quick local structural check is more useful than a browser view
 
-When invoked as `/visualize [path]`:
-
-**If a file path is provided:**
-1. Read the file
-2. Decide what kind of visual artifact would help most from context
-3. If confidence is high enough, choose the mode and generate/share HTML first
-4. If confidence is not high enough, ask the user which direction would help most
-5. If sharing is unavailable or the user explicitly wants terminal output, fall back appropriately
-
-**If no path is provided:**
-1. Check if there's a recent brainstorm or plan document in the conversation context
-2. If yes: use that document's path
-3. If no: summarize the current conversation topic into a markdown structure with headings, write it to a temp file, then render
-
-**If the user says "visualize this" or "show me a mind map":**
-1. Look at what was just discussed or created
-2. Generate an appropriate markdown structure
-3. Render it
-
-## Phase 1 — Render or Share
-
-### Path A — Terminal rendering
-
-**IMPORTANT: Output the mind map in the assistant response text, NOT as raw bash tool output.**
+**IMPORTANT:** Output the mind map in the assistant response text, not as raw bash tool output.
 
 Many harness bash panels truncate long output and wrap wide content, breaking alignment. Instead:
 
-1. Locate the renderer script (see above)
-2. Ensure dependencies are installed
+1. Locate the renderer script.
+2. Ensure dependencies are installed.
 3. Run the renderer with `--no-color`, redirect to a temp file:
    ```bash
    node "$SCRIPT" --no-color [file] > /tmp/mindmap-result.txt 2>&1
    ```
-4. Read `/tmp/mindmap-result.txt`
-5. Output the contents inside a markdown fenced code block in your response text
-6. Clean up: `rm -f /tmp/mindmap-result.txt`
-
-The default mode is **vertical layout** — boxes on main branches, compact leaves, ~40 chars wide.
-
-### Path B — Shareable HTML
-
-For substantial artifacts, prefer this path first when `share-html` is configured.
-
-The coding agent should choose the mode from context. Toolkit guidance:
-- plans often fit `roadmap` or `outline`
-- architecture docs often fit `architecture` or `outline`
-- concise branchy brainstorms may fit `mindmap`
-- product/UI concepts may fit `mockup`
-- stakeholder-friendly summaries may fit `explainer`
-
-If uncertain, ask the user using the harness's structured choice UI when available; otherwise present concise plain-text options.
-
-### Uncertainty protocol
-
-When the best visualization is not clear, do **not** silently guess if the choice would materially affect usefulness.
-
-Ask **one concise question at a time**:
-- state the decision in plain language
-- offer 2-4 explicit options
-- include a recommended option when you have one
-- keep option labels outcome-focused, not renderer-jargon-first
-
-Good pattern:
-- "Which would help most here?"
-- `Roadmap` — show phases, sequencing, and implementation progress
-- `Outline` — show the document structure clearly
-- `Mind map` — show branching ideas and relationships
-- `Architecture view` — show components, boundaries, and decisions
-
-If the harness supports structured choices, use them.
-If not, use a short plain-text question such as:
-
-```text
-I can visualize this a few different ways. Which would be most useful?
-1. Roadmap — phases and tasks
-2. Outline — document structure
-3. Mind map — branching ideas
-4. Architecture view — components and boundaries
-```
-
-If the user does not care or says "you decide," choose the safest useful mode:
-- default to `outline`
-- use `roadmap` for clearly execution-heavy plans
-- use `architecture` for clearly system-design-heavy docs
-- use `mindmap` only when the artifact is genuinely concise and branchy
-
-1. Verify or assume the input markdown is ready
-2. Run:
+4. Read `/tmp/mindmap-result.txt`.
+5. Output the contents inside a fenced code block.
+6. Clean up:
    ```bash
-   bash scripts/render-and-share.sh --mode <chosen-mode> --url-only [file]
+   rm -f /tmp/mindmap-result.txt
    ```
-3. Read the returned URL from stdout
-4. Return that URL to the user as the primary result
-5. Briefly explain what was published and why this mode was chosen
-
-If you need more detail for debugging, you may run the helper without `--url-only` and inspect the returned JSON.
-
-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.
-
-**For shell usage** (not through assistant panels): terminal rendering can use ANSI colors, or `--horizontal` for the wide spatial layout.
-
-## Current HTML modes
 
-- `outline` — safe default for dense or unknown structured docs
-- `roadmap` — useful for plans and phased execution views
-- `architecture` — useful for architecture docs and architect outputs
-- `mindmap` — useful for concise branchy artifacts where it truly helps
-- `mockup` — reserved for future product/UI concept views
-- `explainer` — reserved for future stakeholder/narrative views
-
-## Phase 2 — Offer Next Steps
-
-After rendering or sharing, briefly note:
-- for terminal mode: "Use `--depth N` to see more/less detail"
-- for terminal mode: "Use `--width N` to fit a different terminal size"
-- for shared HTML: return the final browser URL as the main result and say whether it is local-only or publicly reachable on the user's tailnet
-- if publishing failed due to missing share infrastructure: suggest `share-server-setup`
-- if the source was a brainstorm/plan/architecture doc, offer to continue the workflow (e.g., proceed to `/plan`, `/work`, or implementation)
+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:
+- strong title + one-line framing
+- summary layer first
+- main visual body second
+- dense details compressed or collapsible
+- source-faithful appendix only if needed
+
+### Plan-oriented artifact target shape
+- title + mission
+- key stats or scope summary
+- priorities / phases / workstreams
+- dependencies / risks / acceptance gates
+- expandable detail or appendix
+
+### Architecture-oriented artifact target shape
+- title + system framing
+- major components / boundaries / integrations
+- key decisions and tradeoffs
+- risks / assumptions
+- supporting detail below
+
+### Explainer target shape
+- title + recommendation
+- why this matters
+- options / comparison / decision
+- what happens next
+- supporting source detail below
+
+## Quality Gates
+
+Before returning a shared HTML result, check mentally:
+- Does the first screen explain the artifact in under 10 seconds?
+- Does this feel designed, not like markdown with nicer CSS?
+- Is hierarchy obvious?
+- Is summary ahead of detail?
+- Are dense sections compressed into meaningful visual units?
+- 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?
+
+If the answer to several of these is no, reconsider the mode or ask the user.
 
 ## Input Formats
 
 ### Markdown (primary)
-Standard markdown with `#` headings defining hierarchy:
-```markdown
-# Root Topic
-## Branch A
-- Detail 1
-- Detail 2
-## Branch B
-### Sub-branch
-- Detail 3
-```
+Standard markdown with `#` headings defining hierarchy.
 
 ### JSON
-Tree structure with `label` and `children`:
-```json
-{
-  "label": "Root",
-  "children": [
-    { "label": "Branch A", "children": [] },
-    { "label": "Branch B", "children": [
-      { "label": "Sub-branch", "children": [] }
-    ]}
-  ]
-}
-```
-
-## Generating Structure from Context
-
-When visualizing conversation context (no file path), create a markdown structure that captures:
-
-**For brainstorm content:**
-- Root = topic
-- Branches = key decisions or themes
-- Leaves = specific choices or details
+Tree structure with `label` and `children`.
 
-**For plan content:**
-- Root = project name
-- Branches = phases
-- Leaves = tasks within each phase
+## Generating Structure From Context
 
-**For general discussion:**
-- Root = main topic
-- Branches = subtopics discussed
-- Leaves = key points or conclusions
+When visualizing conversation context with no file path:
+- brainstorms: root = topic, branches = key themes, leaves = concrete ideas
+- plans: root = project, branches = priorities/phases, leaves = tasks
+- general discussion: root = main topic, branches = subtopics, leaves = key takeaways
 
 Write the generated markdown to `/tmp/mindmap-XXXXXX.md`, render it, then clean up.
 
 ## What Makes This Babel Fish
 
-The Babel Fish translates between languages. This skill translates between *modalities* — from linear text to spatial structure, and now from private working docs to shareable browser views. It makes the invisible visible: the hierarchy, the relationships, the gaps that only show up when you see the shape of the thinking.
+The Babel Fish translates between languages. This skill translates between modalities — from linear text to spatial understanding, and from private working notes to clear shareable browser artifacts.