@heart-of-gold/toolkit 0.1.40 → 0.1.42

package/.claude-plugin/marketplace.json

@@ -27,7 +27,7 @@
       "name": "babel-fish",
       "source": "./plugins/babel-fish",
       "description": "Universal Translator — media generation tools for audio, image, and video content",
-      "version": "0.2.8"
+      "version": "0.2.9"
     },
     {
       "name": "quellis",

package/README.md

@@ -2,7 +2,7 @@
 
 > **Don't Panic.**
 
-30 skills for AI coding agents. Five plugins. Works with **Claude Code, Codex, OpenCode, Pi**, and any tool supporting the [agentskills.io](https://agentskills.io) standard. Named after *The Hitchhiker's Guide to the Galaxy* because the universe is absurd and your tools should at least have personality.
+31 skills for AI coding agents. Five plugins. Works with **Claude Code, Codex, OpenCode, Pi**, and any tool supporting the [agentskills.io](https://agentskills.io) standard. Named after *The Hitchhiker's Guide to the Galaxy* because the universe is absurd and your tools should at least have personality.
 
 ## Installation
 
@@ -36,6 +36,8 @@ 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.
 
+The CLI now refuses `install --to pi` when your Pi settings already reference `@heart-of-gold/toolkit` as a package. If you intentionally want both paths for debugging, rerun with `--force`.
+
 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:
@@ -136,14 +138,15 @@ Configurable sources (RSS, Gmail, HN, web search), narrative briefs, LinkedIn dr
 
 ### [Babel Fish](plugins/babel-fish/) — Universal Translator
 
-Turn words into audio. Turn ideas into images. Visualize anything as a terminal mind map.
+Turn words into audio. Turn ideas into images. Visualize anything as a terminal mind map. Stitch screenshots into a LinkedIn-ready carousel PDF.
 
-3 skills
+4 skills
 
 ```
-/babel-fish:audio     # TTS, podcasts, voice cloning, sound effects
-/babel-fish:image     # AI image generation and editing
-/babel-fish:visualize # terminal mind maps from any structured content
+/babel-fish:audio             # TTS, podcasts, voice cloning, sound effects
+/babel-fish:image             # AI image generation and editing
+/babel-fish:visualize         # terminal mind maps from any structured content
+/babel-fish:linkedin-carousel # screenshots → LinkedIn document-post PDF with matched backgrounds
 ```
 
 ### [Quellis](plugins/quellis/) — AI Coaching Companion
@@ -167,7 +170,7 @@ The toolkit ships as an npm package with a CLI for installing skills into any su
 
 - `--to pi` installs to Pi's native `~/.pi/agent/skills/`
 - `--to opencode` installs to shared `~/.agents/skills/`, which Pi also discovers
-- `pi install npm:@heart-of-gold/toolkit` installs the package directly in Pi, including the shared skills plus pi-native extensions
+- `pi install npm:@heart-of-gold/toolkit` adds the package to Pi settings, then Pi installs and loads it as a package with shared skills plus pi-native extensions
 
 ```bash
 # Install all plugins into Codex

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heart-of-gold/toolkit",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "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.8",
+  "version": "0.2.9",
   "description": "Universal Translator — media generation tools for audio, image, video, and visualization",
   "author": {
     "name": "ondrej-svec",

package/plugins/babel-fish/README.md

@@ -3,7 +3,7 @@
 > "The Babel fish is small, yellow, leathery, and probably the oddest thing in the universe."
 > It also translates your words into audio and your ideas into images.
 
-A media generation plugin for Claude Code. Turns text into audio, ideas into images, and structured content into terminal mind maps.
+A media generation plugin for Claude Code. Turns text into audio, ideas into images, structured content into terminal mind maps, and screenshots into LinkedIn-ready carousel PDFs.
 
 ## Security & Trust
 
@@ -36,10 +36,14 @@ Supports Gemini and FLUX models via OpenRouter API.
 ### `/babel-fish:visualize`
 Render mind maps and tree visualizations directly in the terminal using Unicode box-drawing characters and ANSI colors. Works over SSH — no browser needed. Use it on brainstorm docs, plan docs, markdown files, or any structured content.
 
+### `/babel-fish:linkedin-carousel`
+Turn an ordered set of screenshots or images into a LinkedIn document-post PDF (carousel). Auto-samples each source's corner pixel so per-page padding blends invisibly into the image, picks a sensible canvas aspect from the source dimensions, and renders at 2× with Lanczos resampling. Powered by ImageMagick.
+
 ## Requirements
 
 - ElevenLabs API key (for audio)
 - OpenRouter API key (for image generation)
+- ImageMagick (`magick` on PATH) — for `linkedin-carousel`
 
 ## Install
 

package/plugins/babel-fish/skills/linkedin-carousel/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: linkedin-carousel
+description: >
+  Turn a set of screenshots or images into a LinkedIn document-post PDF (carousel)
+  with per-page background matching so padding disappears into the source.
+  Triggers: linkedin carousel, carousel pdf, document post, slide pdf, screenshots to pdf, linkedin pdf, carousel from images.
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+---
+
+# LinkedIn Carousel — Babel Fish
+
+Translating a stack of screenshots into a feed-ready document post. The trick isn't the PDF — it's making the padding invisible.
+
+## Boundaries
+
+- **MAY:** read source images, run `magick`, write PNGs and PDFs to the requested output path.
+- **MAY NOT:** upload to LinkedIn, post on the user's behalf, or modify the source images in place.
+
+## Prerequisites
+
+- ImageMagick installed (`magick` on PATH). Check with `which magick`.
+- Sources are raster images (PNG/JPG). For non-image inputs, ask the user to export first.
+
+## Phase 0 — Understand
+
+**Entry:** User asked for a LinkedIn carousel.
+
+Gather, asking only what's missing:
+
+- **Sources**: ordered list of image paths (order = page order in the carousel).
+- **Slug**: kebab-case filename for the PDF (e.g. `harness-lab-carousel`). If the user gives a topic, derive it; otherwise ask.
+- **Output path**: default `thoughts/social-media/carousels/<slug>.pdf` if the repo has that dir; otherwise ask.
+- **Aspect preference**: portrait (best feed performance), square, or landscape. If the user has no preference, **infer from sources** in Phase 1.
+
+**Exit:** Source list, output path, and aspect intent are known.
+
+## Phase 1 — Plan
+
+**Entry:** Inputs gathered.
+
+Reason step-by-step before generating:
+
+1. Run `magick identify` on each source to get width × height.
+2. **Pick canvas aspect** to minimize padding:
+   - User asked for portrait → `1080×1350` (×2 = `2160×2700`).
+   - User asked for square → `1080×1080` (×2 = `2160×2160`).
+   - **No preference** → if the sources cluster around one aspect, pick the **median** w/h ratio — this minimizes total padding across the deck. If sources span a wide range (e.g. 1.6:1 → 2.6:1), pick the aspect that makes the *most* pages padding-free, and accept that the outliers will get bands.
+3. **Sample background color per page** — the move that makes seams invisible. Need the dimensions first, then sample three corners:
+   ```bash
+   read W H < <(magick identify -format "%w %h" "$src")
+   magick "$src" -format \
+     "tl=%[pixel:p{5,5}] tr=%[pixel:p{$((W-5)),5}] bl=%[pixel:p{5,$((H-5))}]\n" \
+     info:
+   ```
+   If all three corners agree, use that color. If they disagree, the source has no clean border — fall back to `#F4EFE3` (or another neutral the user prefers) and tell them.
+4. Render at **2× target resolution** with Lanczos resampling. 300 DPI in the final PDF.
+
+**Exit:** Canvas dimensions chosen, per-page background colors sampled.
+
+## Phase 2 — Build
+
+**Entry:** Plan complete.
+
+Write the build script to a temp file (avoids shell quoting traps), then run it:
+
+```bash
+#!/bin/bash
+set -e
+OUT=/path/to/output/dir
+SLUG=harness-lab-carousel        # from Phase 0
+CANVAS=2160x2700                 # from Phase 1
+declare -a SRCS=(/path/1.png /path/2.png /path/3.png)
+declare -a BGS=('#EFF1F5' '#EFF1F5' '#F2ECEB')   # from Phase 1 sampling
+
+mkdir -p "$OUT"
+PAGES=()
+for i in "${!SRCS[@]}"; do
+  # Zero-pad page number so glob ordering survives 10+ pages.
+  n=$(printf "%02d" $((i+1)))
+  page="$OUT/page${n}.png"
+  magick "${SRCS[$i]}" \
+    -filter Lanczos \
+    -resize "$CANVAS" \
+    -background "${BGS[$i]}" \
+    -gravity center \
+    -extent "$CANVAS" \
+    -quality 95 \
+    "$page"
+  PAGES+=("$page")
+done
+
+# Pass pages explicitly in array order — never rely on shell glob ordering.
+magick "${PAGES[@]}" -density 300 -quality 95 "$OUT/${SLUG}.pdf"
+```
+
+**Notes:**
+- `-resize WxH` (without `>` or `!`) fits inside the box preserving aspect; `-extent` then pads to exact canvas using `-background`.
+- Pages are passed to the final `magick` call from the `PAGES` array, not via glob — `page*.png` would put `page10.png` before `page2.png` lexicographically and reorder the carousel.
+- Keep the intermediate `page*.png` files — useful for spot fixes without rebuilding everything.
+- LinkedIn document posts cap at **100 MB** and **300 pages**. A 3–10 page carousel at 2× is typically 1–5 MB.
+
+**Exit:** PDF and page PNGs exist at the output path.
+
+## Phase 3 — Review
+
+**Entry:** PDF built.
+
+Open the PDF for the user (`open <path>` on macOS). Report:
+
+- Output path
+- Page count, canvas dimensions, file size
+- Per-page background colors used
+- Any fallbacks (e.g., "page 2's corners disagreed — used neutral cream")
+
+Ask whether any page needs a different aspect or a tighter crop. Common follow-ups:
+
+- "Page X has too much padding" → re-sample with a different canvas aspect, or crop that source before rebuilding.
+- "Backgrounds don't match" → the source likely has anti-aliased edges; sample further from the corner (`{20,20}`).
+- "Quality looks soft" → confirm 2× and Lanczos; check the source isn't already low-res.
+
+## Constraints
+
+- Never modify source images in place.
+- Never upload, share, or post the output. Hand the file to the user.
+- Default to per-page background sampling. Single-color fallback only when sources disagree.
+- Always render at 2× target and downsample at PDF assembly time — not the other way around.
+- Keep the intermediate PNGs unless the user asks to clean them up.
+
+## Output
+
+The user receives:
+
+- `<output-dir>/<slug>.pdf` — the carousel, ready to upload via LinkedIn's "Add a document".
+- `<output-dir>/page1.png`, `page2.png`, … — per-page renders for inspection.
+- A short summary message with path, dimensions, page count, and any fallbacks taken.

package/src/commands/install.ts

@@ -1,9 +1,8 @@
 import { defineCommand } from "citty";
 import { loadAllPlugins, loadPlugin } from "../parsers/claude";
 import { targets } from "../targets/index";
-import { resolve, join } from "path";
-import { existsSync } from "fs";
-import { execSync } from "child_process";
+import { resolve } from "path";
+import { findHeartOfGoldPiPackageInstalls } from "../utils/pi-package-detection.js";
 
 export const installCommand = defineCommand({
   meta: {
@@ -26,21 +25,41 @@ export const installCommand = defineCommand({
       description: "Override output root directory",
       required: false,
     },
+    force: {
+      type: "boolean",
+      description: "Proceed even if Pi already loads @heart-of-gold/toolkit as a package",
+      required: false,
+      default: false,
+    },
   },
   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");
+      const matches = findHeartOfGoldPiPackageInstalls(process.cwd());
+      if (matches.length > 0) {
+        const locations = matches
+          .map(({ settingsPath, source }) => `  - ${settingsPath} → ${source}`)
+          .join("\n");
+
+        const message = [
+          "Refusing to install duplicate Pi skills.",
+          "Pi is already configured to load @heart-of-gold/toolkit as a package from:",
+          locations,
+          "",
+          "Choose one Pi install path:",
+          "  1. keep the Pi package:    pi install npm:@heart-of-gold/toolkit",
+          "  2. keep native skill copy: bunx @heart-of-gold/toolkit install --to pi",
+          "",
+          "Remove one side before continuing, or rerun with --force if you really want both.",
+        ].join("\n");
+
+        if (!args.force) {
+          console.error(message);
+          process.exit(1);
         }
-      } catch {
-        // ignore detection failures and proceed normally
+
+        console.warn(`${message}\n`);
       }
     }
     const target = targets[targetName];

package/src/index.ts

@@ -8,7 +8,7 @@ import { shareServerCommand } from "./commands/share-server";
 const main = defineCommand({
   meta: {
     name: "heart-of-gold",
-    version: "0.1.32",
+    version: "0.1.42",
     description:
       "Cross-platform installer for Heart of Gold skills — Codex, OpenCode, Pi, Claude Code, and more",
   },

package/src/utils/pi-package-detection.js

@@ -0,0 +1,81 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, parse, resolve } from "node:path";
+import { homedir } from "node:os";
+
+const HEART_OF_GOLD_PACKAGE_NAME = "@heart-of-gold/toolkit";
+const HEART_OF_GOLD_REPO_HINT = /(^|[/:])heart-of-gold-toolkit(?:$|[@/.#?])/i;
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function isLocalSource(source) {
+  return source.startsWith(".") || source.startsWith("/");
+}
+
+function localSourceIsHeartOfGold(source, settingsDir) {
+  const resolved = resolve(settingsDir, source);
+  const packageJsonPath = existsSync(resolved) && resolved.endsWith("package.json")
+    ? resolved
+    : join(resolved, "package.json");
+
+  if (!existsSync(packageJsonPath)) return false;
+
+  const manifest = readJson(packageJsonPath);
+  return manifest?.name === HEART_OF_GOLD_PACKAGE_NAME;
+}
+
+function sourceMatchesHeartOfGold(source, settingsDir) {
+  if (typeof source !== "string" || source.length === 0) return false;
+
+  if (source === HEART_OF_GOLD_PACKAGE_NAME) return true;
+  if (source.startsWith(`npm:${HEART_OF_GOLD_PACKAGE_NAME}`)) return true;
+  if (isLocalSource(source) && localSourceIsHeartOfGold(source, settingsDir)) return true;
+  if ((source.startsWith("git:") || source.startsWith("http://") || source.startsWith("https://") || source.startsWith("ssh://")) && HEART_OF_GOLD_REPO_HINT.test(source)) {
+    return true;
+  }
+
+  return false;
+}
+
+function collectMatchingPackageSources(settingsPath) {
+  if (!existsSync(settingsPath)) return [];
+
+  const settings = readJson(settingsPath);
+  const packages = Array.isArray(settings?.packages) ? settings.packages : [];
+  const settingsDir = dirname(settingsPath);
+  const matches = [];
+
+  for (const entry of packages) {
+    const source = typeof entry === "string" ? entry : entry?.source;
+    if (sourceMatchesHeartOfGold(source, settingsDir)) {
+      matches.push({ settingsPath, source });
+    }
+  }
+
+  return matches;
+}
+
+function findNearestProjectSettings(startDir = process.cwd()) {
+  let current = resolve(startDir);
+  const root = parse(current).root;
+
+  while (true) {
+    const candidate = join(current, ".pi", "settings.json");
+    if (existsSync(candidate)) return candidate;
+    if (current === root) return null;
+    current = dirname(current);
+  }
+}
+
+export function findHeartOfGoldPiPackageInstalls(startDir = process.cwd()) {
+  const globalSettings = join(homedir(), ".pi", "agent", "settings.json");
+  const projectSettings = findNearestProjectSettings(startDir);
+  const settingsPaths = [globalSettings, projectSettings].filter(Boolean);
+
+  return settingsPaths.flatMap((settingsPath) => collectMatchingPackageSources(settingsPath));
+}