@jairodri/huckleberry-cli 1.0.2 → 1.1.0

package/skills/summarize/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: summarize
+description: "Summarize any block of text using the `summarize` CLI (chained-in from steipete/summarize — npm package `@steipete/summarize`)."
+argument-hint: "[text-file-path OR stdin OR pasted text]"
+allowed-tools:
+  - Bash(summarize *)
+  - Bash(npx @steipete/summarize *)
+---
+
+# /summarize — text → TL;DR via steipete/summarize
+
+You are summarizing arbitrary text using the `summarize` CLI from github.com/steipete/summarize (npm: `@steipete/summarize`). This skill is a **chain-in wrapper** — mktg does not fork or vendor the tool; it orchestrates it when the user has it installed.
+
+## On Activation
+
+1. **Preflight:** Run `summarize --version` via the Bash tool.
+   - If the command is not found, print the short install hint below and stop. Offer to walk the user through [rules/install.md](rules/install.md) if they want the long version.
+     ```
+     summarize CLI not installed. Quickest path:
+       npm i -g @steipete/summarize   (requires Node 22+)
+       brew install summarize         (macOS)
+     Then rerun. Full install guide: skills/summarize/rules/install.md
+     ```
+   - If it prints a version, continue.
+2. **Read `brand/voice-profile.md` if it exists.** At L1+ you should quietly align the TL;DR's *voice* to the brand (tone, energy, diction). At L0 (no brand memory), just produce a neutral summary — do not invent voice.
+3. **Resolve the input.** Accept any of:
+   - A **file path**: pass it directly to summarize (e.g. `summarize /tmp/article.md --length short --plain`)
+   - **Stdin / pasted text**: pipe through `-` (e.g. `cat /tmp/article.md | summarize - --length short --plain`)
+   - **Inline argument text**: write to a scratch file in `.summarize/` first, then pass the path — do not shell-interpolate large blobs of text
+4. **Short-circuit check.** If the input is clearly under ~500 words (or under ~3,000 characters), do **not** run summarize. Return the content as-is and tell the user it was already short enough. Running summarize on tiny inputs wastes latency and the upstream CLI itself returns short content as-is by default unless `--force-summary` is set.
+5. **Run summarize.** Prefer structured output for agent consumption:
+   ```bash
+   summarize <input> --length <preset> --plain --json
+   ```
+   - `--length short|medium|long|xl|xxl` — pick one based on the caller's ask (default: `medium`)
+   - `--plain` — raw output, no ANSI/OSC markdown rendering (agents want plain text)
+   - `--json` — machine-readable envelope with the summary, metrics, and prompt (only when the caller needs metadata; omit for simple TL;DRs)
+   - `--no-color` — belt-and-suspenders if you're capturing stdout
+   - `--timeout 2m` — keep the default unless you know the input is huge
+6. **Capture and return structured output.** The skill's contract with callers:
+   ```
+   {
+     "summary": "<the condensed text>",
+     "input_chars": <int>,
+     "output_chars": <int>,
+     "compression_ratio": <float>,
+     "length_preset": "<short|medium|long|xl|xxl>",
+     "source": "<path or 'stdin'>"
+   }
+   ```
+7. **Never dump huge outputs into context.** Write long outputs to `.summarize/<slug>.md` and return a path + head. Agents should treat the scratch dir like firecrawl's `.firecrawl/` — gitignored, isolated, cleaned on demand.
+
+## How summarize works
+
+`@steipete/summarize` is a Node-22+ CLI that takes a URL, file, or stdin and returns a condensed version rendered as streaming Markdown (or raw JSON when `--json` is set). Under the hood it routes text through an LLM backend — by default `auto` picks the best available provider (cloud key, local endpoint, or a chained coding CLI like Claude/Codex/Gemini/OpenCode). When only offline coding CLIs are available, it falls back to them automatically.
+
+For Pillar 3 (this skill) mktg uses only the **text → summary** surface of the tool. The upstream CLI can also fetch URLs, transcribe YouTube videos, extract PDFs, and run OCR on video slides — but **those jobs belong to other pillars in mktg**:
+
+- URL fetching → `firecrawl` skill
+- YouTube / podcast / TikTok / audio transcription → `mktg-transcribe`
+- X/Twitter reading → `mktg-x`
+
+summarize's role inside mktg is narrower: **take text that another pillar already extracted, return a shorter version**. Keeping the role small keeps the chain-in surface predictable and prevents overlap with mktg's first-class capabilities.
+
+Upstream repo: https://github.com/steipete/summarize
+NPM package: `@steipete/summarize`
+Author: Peter Steinberger (@steipete)
+License: see upstream (chain-in, not vendored)
+
+## Usage patterns
+
+### Pattern A — summarize a local article/markdown file
+
+```bash
+summarize /path/to/article.md --length short --plain
+```
+
+Use when a source-digestion workflow has scraped a long blog post via firecrawl and the source extractor wants a TL;DR to attach to the grounding memo alongside the full extract.
+
+### Pattern B — summarize stdin (pasted text, piped output)
+
+```bash
+cat /tmp/transcript.txt | summarize - --length medium --plain
+pbpaste | summarize - --length short --plain
+```
+
+Use for ad-hoc "the user pasted a giant blob, condense it" requests. Remember: stdin has a 50MB cap upstream, and whitespace-only input is rejected.
+
+### Pattern C — chain-in from mktg-transcribe
+
+```bash
+mktg transcribe "https://youtu.be/<id>" --json \
+  | jq -r .data.transcript \
+  | summarize - --length medium --plain \
+  > .summarize/youtube-<id>-tldr.md
+```
+
+This is the `mktg-transcribe --summarize` flow. Transcribe pipes the transcript text, summarize compresses it, the result is a one-page TL;DR attached to the grounding memo.
+
+### Pattern D — JSON envelope for agent consumption
+
+```bash
+summarize /tmp/long-article.md --length short --plain --json \
+  > .summarize/article-summary.json
+```
+
+When a source-digestion workflow needs the summary plus metrics (input char count, model used, latency) for telemetry or caching, prefer `--json`. Parse `.summary`, `.metrics`, and `.prompt` fields downstream.
+
+### Pattern E — preset selection cheat sheet
+
+| Caller intent | `--length` | Why |
+|---|---|---|
+| "one-sentence gist" | `short` | ~900 char target, fast |
+| "executive summary" | `medium` | ~1,800 char target, default |
+| "detailed digest" | `long` | ~4,200 char target |
+| "thorough condensation" | `xl` | ~9,000 char target |
+| "near-full summary" | `xxl` | ~17,000 char target |
+| "I need exactly N chars" | numeric (`--length 2500`) | character target, >= 50 |
+
+## Chain-in role in the mktg multimedia digestion system
+
+This skill is Pillar 3 of the four-pillar digestion system (see `docs/plans/2026-04-11-002-feat-mktg-multimedia-digestion-plan.md`). Its job is **text compression**, not source ingestion.
+
+**Who calls summarize:**
+
+- **`mktg-transcribe`** — optionally pipes its transcript output through summarize when `--summarize` is passed. This is how video source digestion produces both a full transcript and a TL;DR in a single agent hop.
+- **Source extractors** — when a firecrawl-scraped article is long and the grounding memo would overflow, the source extractor summarizes the extract and attaches both.
+- **Any skill producing long-form text** — `seo-content`, `newsletter`, `direct-response-copy` outputs can be summarized for preview cards, hooks, or social atomization.
+
+**Who does NOT call summarize:**
+
+- Anything dealing with structured data (JSON/CSV/code) — summarize is tuned for prose, not data schemas.
+- Skills that need the full content preserved (brand memory, legal-critical docs, verbatim quotes).
+- Short-input skills where the LLM round-trip isn't worth the latency.
+
+**Default posture:** summarize is an *enhancement*, not a gate. If it's missing, the calling skill still ships the full content — just without a TL;DR. Progressive enhancement applies here the same way brand memory does.
+
+## Anti-Patterns
+
+1. **Running summarize on structured data.** JSON, CSV, code, SQL — don't. **Why:** the tool is tuned for prose. Structured data loses its schema semantics through an LLM condenser and the output is unreliable. If the user wants "the gist of this JSON", explain what the data represents in natural language yourself; don't route it through summarize.
+
+2. **Summarizing already-short text.** If input is under ~500 words (~3,000 chars), skip the call entirely. **Why:** adds latency and cost with no value. Upstream summarize itself returns short content as-is by default. Be honest with the user: "this is already a short read, no TL;DR needed."
+
+3. **Mandating summarization for every long text.** Never default-summarize a skill's output. Offer it as an option. **Why:** many skills want the full content — brand extraction, legal copy, launch memos. Silently truncating them via summarize corrupts the downstream pipeline. Let the caller explicitly ask for a TL;DR.
+
+4. **Forgetting attribution.** summarize is a third-party tool maintained by @steipete. **Why:** mktg ships as a curation layer. When we chain in external tools we credit them so maintainers get recognition and users can upstream issues correctly. Every reference to summarize in generated content must link back to https://github.com/steipete/summarize.
+
+5. **Dumping huge `--json` outputs directly into agent context.** Write to `.summarize/<slug>.json` and return head/tail slices. **Why:** a single summarize `--json` call can easily exceed 10KB of metrics + prompt + summary. Pouring that into an agent's context burns tokens and masks the actual TL;DR. Treat it like firecrawl output: file-based isolation, incremental reads.
+
+6. **Using summarize as a URL fetcher even though it technically can.** Upstream summarize accepts URLs, YouTube, podcasts, and PDFs directly. **Why:** mktg reserves ingestion for its own pillars (firecrawl, mktg-transcribe, mktg-x) so the digestion matrix has exactly one owner per source type. Letting summarize also fetch URLs creates two sources of truth for "who scraped this blog" and breaks source-type routing. Scope this skill to text-in → text-out.
+
+7. **Skipping the install preflight.** Always run `summarize --version` first. **Why:** the tool is an *optional* chain-in. Silent failures ("the summary never came back") are worse than a clear "not installed, here's how to install" message. `mktg doctor` will also flag it, but the skill itself should fail fast.
+
+## References
+
+- [rules/install.md](rules/install.md) — how to install `@steipete/summarize`, verify the binary, and handle install failures on macOS/Linux/WSL.
+- [rules/usage.md](rules/usage.md) — idiomatic usage patterns, flag combinations, output shapes, and when to prefer summarize over direct LLM summarization.
+
+## Attribution
+
+**Source:** https://github.com/steipete/summarize
+**NPM package:** `@steipete/summarize`
+**Homepage:** https://summarize.sh
+**Author:** Peter Steinberger ([@steipete](https://github.com/steipete))
+**Type:** CLI tool (Node 22+)
+**License:** see upstream (`repos/steipete/summarize` — "Other" per GitHub; check upstream LICENSE file)
+**Relationship to mktg:** chained-in (upstream-only — mktg does not fork or vendor the code; users install `@steipete/summarize` separately and mktg orchestrates it)
+**Date wrapped:** 2026-04-11
+**Wrapped by:** mktg source-digestion workflows, Pillar 3 of the multimedia digestion plan
+**Plan reference:** `docs/plans/2026-04-11-002-feat-mktg-multimedia-digestion-plan.md`

package/skills/summarize/rules/install.md

@@ -0,0 +1,157 @@
+---
+name: summarize-cli-installation
+description: |
+  Install the `summarize` CLI (chained-in from steipete/summarize) and verify it is ready for mktg to orchestrate.
+  Package: https://www.npmjs.com/package/@steipete/summarize
+  Source: https://github.com/steipete/summarize
+  Homepage: https://summarize.sh
+---
+
+# summarize CLI Installation
+
+`summarize` is a **chained-in** CLI — mktg does not vendor or fork it. The user installs it once from upstream and mktg orchestrates it. This mirrors how the `firecrawl` skill works.
+
+## Prerequisites
+
+- **Node.js 22+** is required. Check with `node --version`. If missing, install via:
+  - macOS: `brew install node@22`
+  - Linux/WSL: use [nvm](https://github.com/nvm-sh/nvm) → `nvm install 22 && nvm use 22`
+  - Windows: https://nodejs.org/en/download
+- **A working shell and `PATH`** that picks up global npm or Homebrew binaries.
+
+## Quick install (recommended)
+
+Pick ONE of the three paths below.
+
+### Option 1 — npm global (cross-platform, easiest)
+
+```bash
+npm i -g @steipete/summarize
+```
+
+### Option 2 — Homebrew (macOS / Linuxbrew)
+
+```bash
+brew install summarize
+```
+
+Homebrew ships `summarize` from `homebrew/core`.
+
+### Option 3 — npx (no install, every invocation re-downloads)
+
+```bash
+npx -y @steipete/summarize "<input>"
+```
+
+Use this only for one-off trials. For anything mktg routes through, prefer Option 1 or 2 so the binary stays resident.
+
+## Verify
+
+```bash
+summarize --version
+```
+
+Expected: a version string like `1.x.x` on stdout, exit code 0. If you see `command not found`, skip to "If installation fails" below.
+
+Additional readiness check:
+
+```bash
+summarize --help | head -20
+```
+
+Should print the help banner with `Usage: summarize <input> [flags]`.
+
+## Optional local dependencies (NOT required for mktg's Pillar 3 role)
+
+Upstream `summarize` can also transcribe audio, extract slides, and fetch URLs. mktg **does not use those features** — Pillar 1 (`mktg-transcribe`), Pillar 4 (`firecrawl`), and Pillar 2 (`mktg-x`) own ingestion. You can skip all of these and still have a fully working mktg chain-in:
+
+- `ffmpeg` — only needed for upstream's `--slides` mode (not used by mktg)
+- `yt-dlp` — only needed for upstream's YouTube slide extraction (not used by mktg)
+- `tesseract` — only needed for upstream's `--slides-ocr` (not used by mktg)
+
+If you also want to use upstream `summarize` directly for URL/YouTube/PDF work outside mktg, install `ffmpeg` + `yt-dlp` via Homebrew. For mktg purposes, they are not dependencies.
+
+## Optional model provider credentials
+
+`summarize` routes text through an LLM. It auto-selects the best available provider from what you've configured. For mktg's needs, you can use **any** of:
+
+- **Coding CLI providers** (zero API key, uses your existing login):
+  - `claude` — Claude Code CLI, authenticated via `claude auth`
+  - `codex` — Codex CLI, authenticated via `codex login`
+  - `gemini` — Gemini CLI
+  - `opencode` — OpenCode runtime
+- **API keys** (if you prefer cloud models):
+  - `OPENAI_API_KEY`
+  - `ANTHROPIC_API_KEY`
+  - `GOOGLE_API_KEY` / `GEMINI_API_KEY`
+  - `GROQ_API_KEY`
+  - `OPENROUTER_API_KEY` (free tier: `summarize refresh-free`)
+
+**mktg recommendation:** if you already have Claude Code installed (which you almost certainly do if you're reading this), let `summarize` fall back to `--cli claude`. Zero new keys, zero new bills, zero new auth flows. Set it once:
+
+```bash
+summarize /tmp/test.txt --cli claude --plain
+```
+
+If the run succeeds, you're done — `--model auto` will prefer `claude` automatically in the future.
+
+## If installation fails
+
+### `command not found: summarize`
+
+1. Check your npm global bin path is on `PATH`:
+   ```bash
+   npm bin -g
+   echo $PATH
+   ```
+   If the global bin dir is missing, add it to `~/.zshrc` / `~/.bashrc`.
+2. Try npx as a sanity check:
+   ```bash
+   npx -y @steipete/summarize --version
+   ```
+   If that works but `summarize` alone doesn't, the binary never got symlinked — reinstall with `npm i -g --force @steipete/summarize`.
+3. On Homebrew: run `brew doctor` and `brew link summarize`.
+
+### `node: not found` or Node version errors
+
+The package requires **Node 22+**. Upgrade:
+- `brew install node@22 && brew link --overwrite node@22`
+- `nvm install 22 && nvm alias default 22`
+
+### `EACCES` permission errors on global install
+
+Do NOT use `sudo`. Instead, fix npm's global prefix:
+```bash
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
+source ~/.zshrc
+npm i -g @steipete/summarize
+```
+
+### "No model provider available"
+
+If `summarize --version` works but running it fails with "no provider", configure one — see "Optional model provider credentials" above. The fastest path is `--cli claude` if Claude Code is installed.
+
+### Windows / WSL notes
+
+- WSL2 on Ubuntu: install Node 22 via `nvm`, then `npm i -g @steipete/summarize`. Homebrew on Linuxbrew works too.
+- Native Windows PowerShell: use `npm i -g @steipete/summarize`. Make sure `%APPDATA%\npm` is on your PATH.
+
+## Verify from mktg
+
+After install, run `mktg doctor` — the summarize chain-in check turns green when the doctor entry is present. Until then, verify manually:
+
+```bash
+summarize --version && echo "OK: summarize is chained in"
+```
+
+## Upgrade path
+
+```bash
+npm update -g @steipete/summarize
+# or
+brew upgrade summarize
+```
+
+Upstream releases are frequent; upgrade every few weeks to pick up new provider and model support. mktg tracks a review interval of 180 days on the skill manifest — treat that as the *minimum* cadence for re-reading this file, not the upper bound.

package/skills/summarize/rules/usage.md

@@ -0,0 +1,207 @@
+---
+name: summarize-cli-usage
+description: |
+  Idiomatic usage patterns, flag combinations, and output shapes for the `summarize` CLI when orchestrated from mktg.
+  Package: https://www.npmjs.com/package/@steipete/summarize
+  Source: https://github.com/steipete/summarize
+---
+
+# summarize CLI Usage Patterns
+
+How mktg skills and orchestrators should drive `summarize` in practice. Read [install.md](install.md) first if the binary is not present.
+
+## Input shapes
+
+`summarize` accepts three input modes. Use them in this order of preference for mktg work:
+
+### 1. File path (preferred)
+
+```bash
+summarize /path/to/input.md --length short --plain
+```
+
+- Cleanest for agents. No quoting hell, no size limits beyond the LLM provider's own.
+- Writes output to stdout. Redirect with `>` or `-o` patterns.
+- Works with `.md`, `.txt`, `.json`, `.yaml`, `.xml`, plus `.pdf` if you want the upstream provider routing — but for mktg's Pillar 3 role, stick to plain text/markdown.
+
+### 2. Stdin via `-`
+
+```bash
+cat /tmp/article.md | summarize - --length medium --plain
+pbpaste | summarize - --length short --plain
+mktg transcribe "<url>" --json | jq -r '.data.transcript' | summarize - --plain
+```
+
+- Use for piped chains (most common in mktg: `mktg-transcribe` → `summarize`).
+- **50MB cap** upstream. Huge transcripts should be written to a file first, then use mode 1.
+- Whitespace-only stdin is rejected with an error — don't pipe blank input.
+- The literal `-` argument is how you tell summarize to read stdin. Forget it and you'll get "missing input".
+
+### 3. URL / direct media (AVOID in mktg)
+
+Upstream summarize accepts URLs, YouTube, podcasts, and PDFs directly. **Do not use this mode in mktg skills.** Pillar 1 (`mktg-transcribe`), Pillar 4 (`firecrawl`), and Pillar 2 (`mktg-x`) own ingestion. Let them extract, then hand the raw text to summarize.
+
+## Output shapes
+
+### Plain text (default for Pillar 3 chains)
+
+```bash
+summarize input.md --length short --plain --no-color
+```
+
+- `--plain` strips ANSI/OSC markdown rendering. Agents want the raw text.
+- `--no-color` is belt-and-suspenders — some TTYs sneak color back in.
+- Output goes to stdout. Redirect or capture as needed.
+
+### JSON envelope (for agent consumption with metadata)
+
+```bash
+summarize input.md --length short --plain --json > .summarize/out.json
+```
+
+Produces a machine-readable envelope. Parse it with `jq`:
+
+```bash
+jq -r '.summary' .summarize/out.json       # the actual condensed text
+jq '.metrics' .summarize/out.json          # model used, tokens, latency
+jq -r '.prompt' .summarize/out.json        # the prompt sent to the LLM
+```
+
+- **Always write JSON output to `.summarize/`**, never into stdout-to-context. A single run can exceed 10KB of envelope noise.
+- `.summarize/` should be in `.gitignore`. Treat it the same way firecrawl treats `.firecrawl/`.
+
+### Extract-only (skip summarization, get the raw extract)
+
+```bash
+summarize "<url>" --extract --format md
+```
+
+Not used by mktg — this is the upstream URL fetching path, which belongs to firecrawl in our system. Documented here for completeness.
+
+## Length presets
+
+`--length` is a **guideline**, not a hard cap. Upstream picks a character target:
+
+| Preset | Target chars | When to use |
+|---|---|---|
+| `short` (or `s`) | ~900 (600–1,200) | Preview cards, hooks, one-sentence-gist requests |
+| `medium` (or `m`) | ~1,800 (1,200–2,500) | **Default.** Exec summaries, TL;DR at the top of a memo |
+| `long` (or `l`) | ~4,200 (2,500–6,000) | Detailed digests, newsletter intros, podcast rundowns |
+| `xl` | ~9,000 (6,000–14,000) | Thorough condensations, long-form pre-reads |
+| `xxl` | ~17,000 (14,000–22,000) | Near-full summaries (rare — if you want this, you probably want the full text) |
+| Numeric (`--length 2500`) | Exact char target | When you have a specific UI slot to fill. Minimum 50. |
+
+**Hard cap:** if you truly need the output to never exceed N tokens, add `--max-output-tokens <count>` (minimum 16). Prefer `--length` unless you need a provider-enforced ceiling.
+
+**Short-input behavior:** when the extracted content is shorter than the requested length, upstream returns the content as-is without calling the LLM. Override with `--force-summary` if you need the LLM to run regardless (rare). mktg's On Activation check catches this *before* the subprocess call anyway — aim to not waste the round-trip.
+
+## Model selection
+
+mktg defaults to `--model auto` (which upstream picks automatically — you don't need to pass it). Auto ordering:
+
+1. If `--cli <provider>` is explicit, use that.
+2. If `cli.enabled` is set in `~/.summarize/config.json`, use those CLI providers in order.
+3. If API keys are set for cloud providers, use them.
+4. Fallback: try coding CLI providers (`claude`, `gemini`, `codex`, `agent`, `openclaw`, `opencode`) in order.
+
+**Recommended default for mktg:**
+
+```bash
+summarize <input> --cli claude --plain --length short
+```
+
+`--cli claude` routes to Claude Code (which the user almost certainly already has authenticated if they're using mktg). Zero new credentials, zero new rate limits.
+
+To force a specific model:
+
+```bash
+summarize input.md --model anthropic/claude-sonnet-4-5 --plain
+summarize input.md --model openai/gpt-5-mini --plain
+summarize input.md --model google/gemini-3-flash --plain
+```
+
+Model IDs follow `<provider>/<model>`. Full list in upstream README. Don't hard-code a specific model in skills — let `--model auto` + `--cli claude` do the right thing.
+
+## Timeouts and retries
+
+```bash
+summarize input.md --timeout 2m --retries 1
+```
+
+- `--timeout` accepts `30s`, `2m`, `5000ms`. Default is `2m`.
+- `--retries` sets LLM retry attempts on timeout. Default is `1`.
+- For agent loops, bump to `--timeout 5m --retries 2` if inputs are large (>20K chars).
+
+## Verbose / diagnostics
+
+```bash
+summarize input.md --plain --verbose
+```
+
+- `--verbose` writes debug/diagnostics to **stderr**. Never parse stderr as the summary.
+- Useful when debugging "why did this pick model X" or "why did it fail silently".
+- `--metrics detailed` prints extra metrics. Default is `on`.
+
+## When to prefer summarize vs direct LLM summarization
+
+**Prefer summarize (chain-in) when:**
+- You want consistent output shape across agent loops (same CLI, same flags, same provider selection).
+- You want free provider fallback via `--cli claude` / `--cli codex` / `--cli gemini`.
+- You're in a pipeline (`mktg-transcribe | summarize | ...`) where a dedicated subprocess is cleaner than an inline LLM call.
+- You want metrics/telemetry for summarization specifically (input chars, output chars, model, latency).
+
+**Prefer direct LLM summarization (no chain-in) when:**
+- The calling skill already has an LLM round-trip in flight and the summary is a byproduct.
+- The input is short enough that the subprocess overhead outweighs the LLM call cost.
+- The user doesn't have `summarize` installed and you're at L0 progressive-enhancement degradation — write the summary inline.
+
+**Never use summarize when:**
+- The content is structured data (JSON/CSV/code). Explain it natively instead.
+- The input is already short (<500 words, <3000 chars). Return as-is.
+- The caller explicitly wants the full content preserved (brand memory, legal, verbatim quotes).
+
+## Common pitfalls
+
+1. **Forgetting `--plain`.** Without it, output is streamed ANSI/OSC markdown with cursor codes. Looks pretty in a TTY, breaks in agent loops. Always pass `--plain` for programmatic consumption.
+2. **Forgetting the `-` for stdin.** `cat foo | summarize` fails. You need `cat foo | summarize -`.
+3. **Piping huge blobs directly into shell args.** Never `summarize "$(cat bigfile)"`. Always use mode 1 (file path) or mode 2 (stdin `-`). Shell argv has limits and escaping is a nightmare.
+4. **Reading long summaries into agent context.** Use `.summarize/` file output + `head`/`grep` like firecrawl does.
+5. **Assuming `--json` gives you just the summary.** The envelope includes metrics, prompt, and diagnostics. Use `jq -r '.summary'` to pluck the condensed text.
+6. **Using upstream's URL/YouTube/PDF modes inside mktg.** Ingestion belongs to other pillars. Keep this skill scoped to text-in → text-out.
+7. **Chaining `--force-summary` by default.** Only use it when you have a specific reason to force the LLM call over short content. Default off.
+8. **Not handling exit codes.** If `summarize` fails (timeout, provider error, no content), it exits non-zero. Agents should check `$?` or equivalent and degrade gracefully — the caller's original content is still valid without a TL;DR.
+
+## Parallelization
+
+Independent summarization calls can run in parallel:
+
+```bash
+summarize article-1.md --plain --length short > .summarize/1.md &
+summarize article-2.md --plain --length short > .summarize/2.md &
+summarize article-3.md --plain --length short > .summarize/3.md &
+wait
+```
+
+Watch out for provider rate limits — if you're using the same API key across 10 parallel calls, you'll hit 429s. Coding CLI providers (`--cli claude` etc.) are serialized locally so parallelism there is capped by your local CLI runtime.
+
+## Cheat sheet
+
+```bash
+# Default mktg invocation
+summarize input.md --plain --length short
+
+# With claude fallback (zero new auth)
+summarize input.md --cli claude --plain --length short
+
+# Stdin from a pipe
+cat input.md | summarize - --plain --length medium
+
+# JSON envelope for telemetry
+summarize input.md --plain --length short --json > .summarize/out.json
+
+# Long-form digest
+summarize input.md --plain --length long
+
+# Hard token cap for UI slots
+summarize input.md --plain --length 1200 --max-output-tokens 400
+```