@heart-of-gold/toolkit 0.1.36 → 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.6"
+      "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.6"
+      "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.4"
+      "version": "0.2.5"
     },
     {
       "name": "quellis",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heart-of-gold/toolkit",
-  "version": "0.1.36",
+  "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.4",
+  "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

@@ -120,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.
@@ -130,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
@@ -141,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
 
@@ -233,14 +256,22 @@ fi
 
 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
-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"
+# 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`
 
@@ -266,18 +297,21 @@ node "$(dirname "$SCRIPT")/render-mindmap/index.js" --html /tmp/map.html path/to
 
 Use this when the artifact needs stronger design judgment than the fallback renderer can provide.
 
-1. Create the scaffold:
+1. Create the scaffold with a standalone cross-platform command:
    ```bash
-   HTML_OUT="$(bash "$(dirname "$SCRIPT")/new-authored-artifact.sh")"
+   node /absolute/path/to/new-authored-artifact.js
    ```
-2. Author the HTML artifact directly into that file.
-3. Publish it:
+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
-   bash "$(dirname "$SCRIPT")/publish-authored-html.sh" --url-only "$HTML_OUT"
+   node /absolute/path/to/publish-authored-html.js --url-only /tmp/your-artifact.html
    ```
-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.
+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
 
@@ -328,16 +362,27 @@ 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`.
+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
 
@@ -369,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:
@@ -380,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/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

@@ -6,7 +6,8 @@ TEMPLATE="$SCRIPT_DIR/agent-artifact-template.html"
 OUT_PATH="${1:-}"
 
 if [[ -z "$OUT_PATH" ]]; then
-  OUT_PATH="$(mktemp /tmp/hog-visualize-artifact-XXXXXX.html)"
+  TEMP_BASE="$(mktemp /tmp/hog-visualize-artifact-XXXXXX)"
+  OUT_PATH="${TEMP_BASE}.html"
 fi
 
 cp "$TEMPLATE" "$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/deep-thought/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "deep-thought",
-  "version": "0.2.6",
+  "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.6",
+  "version": "0.3.7",
   "description": "The Paranoid Android — quality tools for code review, knowledge compounding, and work execution",
   "author": {
     "name": "ondrej-svec",