@damiangilgonzalez/harness 1.3.7

package/skills/marketing/scripts/verify.sh

@@ -0,0 +1,233 @@
+#!/usr/bin/env bash
+#
+# verify.sh — copy QA gate for the `marketing` skill.
+#
+# WHAT IT DOES (read-only; never edits a file)
+#   Static, network-free grep checks over the copy in your project:
+#     1. Ban-list hype words (revolutionary, game-changer, cutting-edge, world-class,
+#        seamless, unlock, supercharge, "Excited to share", "not just X", "In today's …").
+#     2. Generic / un-earned CTAs ("Learn more", "Click here", "Submit").
+#     3. Weasel words / vague benefits (very, really, world-class, "best-in-class",
+#        "thousands trust", "industry-leading", "robust solution").
+#     4. Passive-voice flags (heuristic: "is/are/was/were/be/been + past participle").
+#     5. Structure heuristics on HTML/JSX/MD pages: missing <h1>, more than one <h1>,
+#        no obvious CTA verb.
+#     5b. JSON-LD/schema presence: landing-style pages (<section>) with no
+#         application/ld+json get a GEO/SEO warning (detect-or-skip; see seo-geo.md).
+#     6. Brand-grounding presence: warns if no docs/wiki/brand/ study is found.
+#
+#   Every finding is a WARNING by default (copy is judgement, not pass/fail).
+#   Use --strict to turn warnings into a failure (exit 1) so CI can gate on it.
+#   A missing tool is reported yellow and SKIPPED — never a failure.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh                 # scan ./ for copy in *.{md,mdx,html,tsx,jsx,vue,svelte,txt}
+#   ./verify.sh --path src      # scan a subdirectory
+#   ./verify.sh --strict        # treat any warning as a failure (exit 1)
+#
+# EXIT CODES
+#   0  clean, or warnings only without --strict
+#   1  a real failure, or --strict with any warning
+#   2  bad usage
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays, arrays are
+# initialised and only expanded when non-empty under `set -u`.
+
+set -euo pipefail
+
+# --- color helpers (no escape codes when not a TTY) -------------------------
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+ok_count=0; skip_count=0; warn_count=0; fail_count=0
+
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; ok_count=$((ok_count + 1)); }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; skip_count=$((skip_count + 1)); }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+usage() {
+  # print the header comment block (lines 2..34), stripping the leading "# "
+  sed -n '2,34p' "$0" | sed 's/^# \{0,1\}//'
+}
+
+# --- arg parse --------------------------------------------------------------
+SCAN_PATH="."
+STRICT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --path)    SCAN_PATH="${2:?--path needs a value}"; shift 2 ;;
+    --strict)  STRICT=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) printf '%sUnknown argument: %s%s\n\n' "$RED" "$1" "$NC"; usage; exit 2 ;;
+  esac
+done
+
+if [ ! -e "$SCAN_PATH" ]; then
+  printf '%sPath not found: %s%s\n' "$RED" "$SCAN_PATH" "$NC"; exit 2
+fi
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+# count_lines <file>: number of non-empty-aware lines in a file; 0 if missing/empty.
+# Robust across BSD/GNU: wc -l can print leading spaces, so strip non-digits.
+count_lines() {
+  if [ -s "$1" ]; then
+    wc -l < "$1" 2>/dev/null | tr -dc '0-9'
+  else
+    printf '0'
+  fi
+}
+
+# Copy-bearing extensions are restricted via glob flags in search() below.
+# JSX/TSX/Vue/Svelte/HTML carry on-page copy; md/mdx/txt carry content + references.
+
+# search <pattern>: case-insensitive, whole-tree, copy files only. Prints file:line:match.
+# Uses ripgrep if present (faster, respects .gitignore), else portable grep -rnE.
+# Never errors out the script: a no-match grep returns 1, which we swallow.
+search() {
+  pattern="$1"
+  if have rg; then
+    rg -n --no-heading -i -e "$pattern" \
+       -g '*.md' -g '*.mdx' -g '*.html' -g '*.htm' \
+       -g '*.tsx' -g '*.jsx' -g '*.vue' -g '*.svelte' -g '*.txt' \
+       "$SCAN_PATH" 2>/dev/null || true
+  else
+    # --include globs restrict to copy files by filename (BSD + GNU grep);
+    # this avoids matching the extension against the file:line:content output.
+    grep -rniE \
+      --include='*.md' --include='*.mdx' --include='*.html' --include='*.htm' \
+      --include='*.tsx' --include='*.jsx' --include='*.vue' --include='*.svelte' \
+      --include='*.txt' \
+      -e "$pattern" "$SCAN_PATH" 2>/dev/null || true
+  fi
+}
+
+# report <label> <pattern>: warn (with up to 5 example lines) if the pattern is found.
+report() {
+  label="$1"; pattern="$2"
+  hits="$(search "$pattern")"
+  if [ -n "$hits" ]; then
+    warn "$label:"
+    printf '%s\n' "$hits" | head -n 5 | sed 's/^/        /'
+  else
+    ok "no $label"
+  fi
+}
+
+# --- ensure we have a searcher ----------------------------------------------
+if ! have rg && ! have grep; then
+  skip "neither ripgrep nor grep found — cannot scan; install ripgrep or grep"
+  printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+  exit 0
+fi
+
+printf 'Scanning copy under: %s\n\n' "$SCAN_PATH"
+
+# --- 1. ban-list hype words -------------------------------------------------
+report "ban-list hype words" \
+  'revolutionary|game.?changer|cutting.edge|world.class|next.level|seamless|supercharge|elevate|unlock|excited to share|not just |in today.?s (landscape|fast.paced|competitive|digital)'
+
+# --- 2. generic / un-earned CTAs --------------------------------------------
+report "generic CTAs (use a value verb instead)" \
+  '>[[:space:]]*(learn more|click here|submit|read more|find out more)[[:space:]]*<|"(learn more|click here|submit)"'
+
+# --- 3. weasel words / vague benefits ---------------------------------------
+report "weasel words / vague benefits (replace with a number or mechanism)" \
+  'industry.leading|best.in.class|robust solution|powerful (platform|solution|tool)|thousands (of teams )?(trust|use)|trusted by thousands|very (fast|easy|powerful|simple)|really (fast|easy|good)'
+
+# --- 4. passive-voice flags (heuristic) -------------------------------------
+report "possible passive voice (prefer active: who does what)" \
+  '\b(is|are|was|were|be|been|being)\b +([a-z]+ed|built|made|done|driven|shipped|run|known|seen|given)\b'
+
+# --- 5. structure heuristics (per page) -------------------------------------
+# Subshells in a pipe can't mutate warn_count under bash 3.2, so each per-file
+# loop appends one line per finding to a temp file, then we add the line count
+# to warn_count in the parent shell. Each scan runs exactly once.
+TMPDIR_V="$(mktemp -d 2>/dev/null || printf '/tmp/verify.%s' "$$")"
+mkdir -p "$TMPDIR_V" 2>/dev/null || true
+H1_HITS="$TMPDIR_V/h1"; CTA_HITS="$TMPDIR_V/cta"
+: > "$H1_HITS"; : > "$CTA_HITS"
+cleanup() { rm -rf "$TMPDIR_V" 2>/dev/null || true; }
+trap cleanup EXIT
+
+# Duplicate <h1> in HTML/JSX-ish pages (should be exactly one per page).
+h1_files="$(search '<h1' | sed 's/:.*//' | sort -u)"
+if [ -z "$h1_files" ]; then
+  ok "h1 check: no HTML/JSX pages with <h1> to inspect"
+else
+  printf '%s\n' "$h1_files" | while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    case "$f" in *.tsx|*.jsx|*.html|*.htm|*.vue|*.svelte) : ;; *) continue ;; esac
+    # count occurrences, not matching lines: two <h1> on one line must still trip this.
+    n="$(grep -o '<h1' "$f" 2>/dev/null | wc -l | tr -dc '0-9')"
+    [ -z "$n" ] && n=0
+    if [ "$n" -gt 1 ]; then
+      printf '%s[warn]%s multiple <h1> in one page (should be exactly one): %s\n' "$YELLOW" "$NC" "$f"
+      printf '%s\n' "$f" >> "$H1_HITS"
+    fi
+  done
+  n_h1="$(count_lines "$H1_HITS")"
+  if [ "$n_h1" -gt 0 ]; then warn_count=$((warn_count + n_h1)); else ok "h1 check: exactly one <h1> per page"; fi
+fi
+
+# Landing-style pages (have <section>) with no clear CTA verb anywhere.
+cta_verbs='start free|get started|book a demo|see (it|a) (live|demo)|get my|try it|sign up|join the'
+pages="$(search '<section' | sed 's/:.*//' | sort -u)"
+if [ -z "$pages" ]; then
+  ok "CTA check: no landing-style pages (<section>) to inspect"
+else
+  printf '%s\n' "$pages" | while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    if ! grep -iE "$cta_verbs" "$f" >/dev/null 2>&1; then
+      printf '%s[warn]%s page has <section> markup but no clear CTA verb: %s\n' "$YELLOW" "$NC" "$f"
+      printf '%s\n' "$f" >> "$CTA_HITS"
+    fi
+  done
+  n_cta="$(count_lines "$CTA_HITS")"
+  if [ "$n_cta" -gt 0 ]; then warn_count=$((warn_count + n_cta)); else ok "CTA check: every landing page has a CTA verb"; fi
+fi
+
+# --- 5b. JSON-LD / schema presence on landing-style pages (GEO signal) -------
+# Detect-or-skip: only judges pages that already look like landing pages (<section>).
+# A landing page with no application/ld+json is a missed GEO/SEO opportunity (warn),
+# not a failure. Pages without <section> are not inspected (skip), so non-web repos
+# never trip this. See references/seo-geo.md for the schema templates.
+SCHEMA_HITS="$TMPDIR_V/schema"; : > "$SCHEMA_HITS"
+schema_pages="$(search '<section' | sed 's/:.*//' | sort -u)"
+if [ -z "$schema_pages" ]; then
+  skip "JSON-LD check: no landing-style pages (<section>) to inspect"
+else
+  printf '%s\n' "$schema_pages" | while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    if ! grep -iE 'application/ld\+json' "$f" >/dev/null 2>&1; then
+      printf '%s[warn]%s landing page has no JSON-LD schema (add FAQPage/Article — see seo-geo.md): %s\n' "$YELLOW" "$NC" "$f"
+      printf '%s\n' "$f" >> "$SCHEMA_HITS"
+    fi
+  done
+  n_schema="$(count_lines "$SCHEMA_HITS")"
+  if [ "$n_schema" -gt 0 ]; then warn_count=$((warn_count + n_schema)); else ok "JSON-LD check: every landing page carries schema markup"; fi
+fi
+
+# --- 6. brand-grounding presence --------------------------------------------
+if [ -d "$SCAN_PATH/docs/wiki/brand" ] || [ -d "docs/wiki/brand" ]; then
+  ok "brand study found under docs/wiki/brand/"
+else
+  warn "no brand study at docs/wiki/brand/ — run the brand-grounding gate before shipping copy"
+fi
+
+# --- summary ----------------------------------------------------------------
+printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+
+cat <<'EOF'
+
+Note: every finding above is a heuristic WARNING — copy is judgement, not pass/fail.
+Review each, then fix or justify. Re-run with --strict to gate CI on a clean pass.
+EOF
+
+if [ "$fail_count" -gt 0 ]; then exit 1; fi
+if [ "$STRICT" -eq 1 ] && [ "$warn_count" -gt 0 ]; then exit 1; fi
+exit 0

package/skills/medium-publishing/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: medium-publishing
+description: "Use when a finished article has to land on Medium correctly — profile vs publication, cross-posting under a canonical link so your own site keeps the SEO credit, import-tool failures, the 5-tag cap, pseudo-Markdown gotchas. NOT writing or headlining the piece (that is `medium-writing`), NOT cadence or earnings (that is `medium-strategy`)."
+tags: [medium, publishing, cross-posting, canonical-url, seo, import-tool]
+recommends: [medium-writing, medium-strategy, seo-geo, social-publisher]
+origin: risco
+---
+
+# Medium publishing
+
+Land a finished article on Medium with correct metadata: right destination, no duplicate-content penalty, valid tags, intact formatting. Writing the article is `../medium-writing/SKILL.md`; deciding when/where/how-often to publish and how it grows is `../medium-strategy/SKILL.md`. This skill is only the mechanics of getting bytes onto the platform with the right metadata attached.
+
+## Reality check (2025-2026)
+
+**The Medium API is closed to new integrations.** As of 2025-01-01 Medium issues no new integration tokens and accepts no new integrations; only tokens minted before that date still work. Why it matters: any plan that starts with "register a Medium API token and automate it" is dead on arrival for anyone who didn't already have one. Integration platforms confirm this — the Medium app in Make is marked legacy, and n8n's Medium credentials can no longer be newly configured.
+
+So the default publishing path is **web editor + import tool + canonical link**, done through the UI. Treat the API as a legacy escape hatch (last section), not the plan — when asked "can I get a token and automate this?", the honest answer is almost always no, so say why and route to the import path below rather than promising automation.
+
+## Decision table — pick your path
+
+Branch on where the article already lives and what you control:
+
+| Situation | Path | Canonical handling |
+|---|---|---|
+| Article only ever lives on Medium | Write or paste natively in the web editor, publish | None needed — Medium *is* the original |
+| Article already published on your own site/blog | **Import tool**: paste the original URL | Auto-set to that URL + auto-backdated |
+| Import tool fails (403/404/timeout) | Native paste, then set canonical by hand | Manual: Story settings -> Customize canonical link |
+| You hold a pre-2025 API token and want automation | Legacy `POST /v1/users/{id}/posts` | `canonicalUrl` field in the request body |
+| Destination is a publication you write for | Submit draft to the publication | Same as above; submission is separate from canonical |
+
+## Cross-post without an SEO penalty (the core job)
+
+When the article already lives on your own site, you must tell search engines that the **origin** — your page, never the Medium URL — is canonical, or Google sees two copies and may credit Medium or neither. Two mechanisms, in order of preference:
+
+**1. Import tool (preferred).** Pasting the original URL into Medium's import field does three things at once:
+- imports the rendered content into a new draft,
+- sets the story's canonical link to that original URL (search engines keep crediting your site),
+- backdates the Medium post to your original publish date by reading the page's `article:published_time` meta tag.
+
+Path: New story -> import icon (or `medium.com/p/import`) -> paste the original URL -> Import. Review the draft, then publish.
+
+**2. Manual canonical (fallback).** If you drafted natively or the import failed, set it per story: **More options (•••) -> Story settings -> advanced/edit -> "Customize canonical link"**, paste the origin URL, then publish. This is per-story; there is no global default.
+
+```text
+Bad:  Open a new Medium story, paste the article body, hit Publish.
+      -> Duplicate content, no canonical, wrong date. Your own page now
+         competes with Medium for its own ranking.
+Good: Use the import tool (canonical + backdate set automatically), or if
+      you paste natively, set "Customize canonical link" to the origin URL
+      BEFORE publishing.
+```
+
+## When the import fails
+
+The importer is an HTTP crawler hitting your URL; failures are crawl failures, not Medium bugs. Map the symptom to the cause:
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| 400 / 404 | URL unreachable, redirected, or page metadata missing | Verify the URL loads anonymously; ensure `<link rel="canonical">` and `article:published_time` exist |
+| 403 | Bot-blocking (WAF, Cloudflare challenge, login wall) | Serve a clean static copy the crawler can reach, or paste natively + set canonical manually |
+| 500 / 504 | Crawl timeout — heavy JS, slow page | Provide a lightweight static HTML version of the article |
+| Imports but body is empty/garbled | Content rendered client-side only (JS) | Same: static HTML with the content in the initial markup |
+
+The reliable workaround for stubborn pages: publish a minimal static HTML page of the article carrying `<link rel="canonical">` and `<meta property="article:published_time">`, import *that*, then you can take it down. Full recipe and the complete error -> cause -> fix matrix are in `references/cross-post-and-canonical.md`.
+
+## Tags & formatting at publish time
+
+**Five tags, exactly.** Medium allows up to 5 tags per story; they drive topic distribution and discovery, so they are functional metadata, not decoration. Pick 5 real topics readers browse, not keyword-stuffed variants.
+
+```text
+Bad:  tags: react, reactjs, react.js, react-hooks, javascript, frontend, webdev  (7, redundant)
+Good: tags: react, javascript, web-development, frontend, programming           (5, distinct surfaces)
+```
+
+**Medium is NOT a full Markdown editor.** The web editor interprets a *subset* of Markdown shortcuts as you type, and silently ignores the rest. Know the gotchas:
+
+- Headings (`#`, `##`), blockquote (`>`), emphasis (`*`/`_`), ordered/bulleted lists (`1.`, `*`), and the `---` separator work as you type.
+- **No Markdown tables.** Pasting a `| col | col |` table renders as plain text. Restructure into a list, or insert the table as an image.
+- **Code blocks**: type triple-backtick then content, or `Cmd/Ctrl + Option + 6`. Do not rely on indentation-based code.
+- **Embeds**: paste a bare URL on its own line (YouTube, gist, tweet) and Medium expands it. A URL inside a sentence stays a plain link.
+
+```text
+Bad:  Paste a raw Markdown table and assume it renders as a table.
+Good: Convert the table to a labeled list, or screenshot/export it as an
+      image and insert the image. Reserve real tables for the original site.
+```
+
+(The legacy API's `contentFormat: markdown` is more permissive than the web editor — but that path is closed to new users.)
+
+## Publications
+
+Two outcomes, often confused:
+
+- **Self-publish** puts the story on your own profile immediately.
+- **Submit to a publication** routes the draft to that publication's editors, where it stays **pending** — not live — until one of them publishes it. A publication is editorially controlled, so submission is a request, not a publish action, and it only works if you are already an accepted writer there. If you're not, request access first; submitting otherwise goes nowhere.
+
+## Legacy API — only if you hold a pre-2025 token
+
+Do **not** attempt to register a new token; it will be refused. This applies *only* to tokens minted before 2025-01-01.
+
+```bash
+# 1. Resolve your user id
+curl -s -H "Authorization: Bearer $MEDIUM_TOKEN" \
+  https://api.medium.com/v1/me
+# -> { "data": { "id": "<userId>", ... } }
+
+# 2. Create a post with canonical + publish status
+curl -s -X POST \
+  -H "Authorization: Bearer $MEDIUM_TOKEN" \
+  -H "Content-Type: application/json" \
+  https://api.medium.com/v1/users/<userId>/posts \
+  -d '{
+    "title": "My title",
+    "contentFormat": "markdown",
+    "content": "# My title\n\nBody...",
+    "canonicalUrl": "https://mysite.com/original-post",
+    "tags": ["react", "javascript", "web-development"],
+    "publishStatus": "draft"
+  }'
+```
+
+`publishStatus` is `public` | `draft` | `unlisted`. For a publication, POST to `/v1/publications/{publicationId}/posts`; a `draft` there stays pending an editor. Full field reference and response shapes are in `references/legacy-api.md`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong | Do instead |
+|---|---|---|
+| Paste a copy of your own article, publish with no canonical | Duplicate content; your site loses ranking credit | Import tool, or set canonical to the origin before publishing |
+| Plan an automated pipeline on a freshly registered API token | No new tokens since 2025-01-01; it will never authorize | Use the import tool / web editor; reserve API only for pre-2025 tokens |
+| Cram 6+ tags or keyword-stuff the tag slots | Max is 5; redundant tags waste distribution surface | Pick 5 distinct topics readers actually browse |
+| Paste a raw Markdown table and assume it renders | The web editor has no table support | List or image; keep the table on the origin site |
+| Submit to a publication and assume it goes live | Submission is pending until an editor acts; needs writer access | Self-publish for instant, or submit only as an accepted writer |
+| Set canonical to the Medium URL | Points credit at Medium, defeating the cross-post | Canonical must point to your origin site |
+| Native paste of a backdated piece without checking the date | Manual paste does not backdate; canonical/date mismatch | Use import (auto-backdate) or set the date deliberately |
+
+## Post-publish verify checklist
+
+A correctly cross-posted article passes all of these:
+
+- [ ] Canonical link present **and pointing to the origin** (your site), not the Medium URL.
+- [ ] Publish date matches the original (backdated correctly if cross-posted).
+- [ ] 5 tags or fewer, all distinct real topics.
+- [ ] Code blocks render as code; embeds expanded; no broken Markdown tables.
+- [ ] Correct destination — your profile, or the intended publication (and it actually went live, not stuck pending).

package/skills/medium-publishing/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — medium-publishing
+
+These cases check routing and capability for the `medium-publishing` skill. Run them through the skill-eval harness: each `should_trigger` prompt should fire this skill; each `should_not_trigger` prompt should route to the named sibling instead (`medium-writing` for the article's craft, `medium-strategy` for growth/cadence, `social-publisher` for multi-platform scheduling, `seo-geo` for site-wide SEO). The `capability` case is rubric-graded — feed the scenario to the skill and check the response covers every `must_include` item (closed API, import-tool-first, auto canonical + backdate, manual canonical fallback, 5-tag limit, formatting gotchas, and no false promise of API automation). There is no `verify.sh`: this is a process/operational skill whose output is an article published on a third-party platform via UI steps, so rigor lives in this capability rubric and the post-publish checklist in SKILL.md.

package/skills/medium-publishing/evals/cases.yaml

@@ -0,0 +1,42 @@
+skill: medium-publishing
+
+should_trigger:
+  - prompt: "Cross-post my blog post to Medium without hurting my own site's SEO."
+    why: Core canonical/import case — getting a piece that lives on the user's site onto Medium without duplicate-content penalty.
+  - prompt: "The Medium import tool failed with a 403 on my article — how do I get it in?"
+    why: Non-obvious failure-mode trigger; the answer is the bot-block/static-HTML workaround, squarely this skill's mechanics.
+  - prompt: "Can I still get a Medium API token to auto-publish my posts from a script?"
+    why: Must surface the closed-API reality (no new tokens since 2025-01-01) and route to the import path. Non-obvious — the user assumes automation is possible.
+  - prompt: "Submit my draft to the Better Programming publication on Medium."
+    why: Publication submission path — self-publish vs pending-until-editor distinction.
+  - prompt: "Why do my code blocks and tables look broken after I published on Medium?"
+    why: Publish-time formatting gotchas (pseudo-Markdown editor, no tables, code-block method).
+  - prompt: "Importar mi artículo de mi web a Medium con enlace canónico para no duplicar contenido."
+    why: Spanish trigger for the canonical cross-post mechanic.
+  - prompt: "Republish this on Medium with a canonical link pointing back to my original."
+    why: Direct canonical-link request — the manual fallback or import path.
+
+should_not_trigger:
+  - prompt: "Write me a compelling Medium article about distributed systems and fix my intro."
+    route_to: medium-writing
+    why: Drafting, structuring, and headlining the piece is the writing craft, not the publish mechanics.
+  - prompt: "How often should I post on Medium and how do I grow my following and Partner Program earnings?"
+    route_to: medium-strategy
+    why: Cadence, audience growth, and monetization are distribution strategy, not getting one article onto the platform.
+  - prompt: "Schedule this same post across LinkedIn, X, and Medium from one content queue."
+    route_to: social-publisher
+    why: Cross-channel scheduling across many platforms is the multi-platform publisher, not Medium-specific mechanics.
+  - prompt: "Audit my whole site's canonical tags and fix duplicate-content issues across all pages."
+    route_to: seo-geo
+    why: Site-wide canonical/SEO auditing is general SEO; this skill only handles the Medium-side canonical mechanic.
+
+capability:
+  - scenario: "I published this article on my own blog last month. Put it on Medium without an SEO penalty, with the right tags."
+    must_include:
+      - States the Medium API is closed to new integrations (no new tokens since 2025-01-01).
+      - Chooses the import tool as the primary path for a piece that already lives on the user's site.
+      - Confirms the import auto-sets the canonical link to the origin URL and backdates from article:published_time.
+      - Gives the manual canonical fallback location (Story settings -> Customize canonical link) for when import fails.
+      - Enforces the 5-tag maximum and picks distinct topics, not keyword-stuffed variants.
+      - Flags the no-Markdown-tables and code-block formatting gotchas.
+      - Does NOT promise or attempt API automation via a newly registered token.

package/skills/medium-publishing/references/cross-post-and-canonical.md

@@ -0,0 +1,65 @@
+# Cross-posting & canonical — deep reference
+
+Detail for the import tool, manual canonical, and the static-HTML workaround for stubborn imports. The SKILL.md body covers the happy path; come here when the import fails or you need the exact UI walkthrough.
+
+## Import tool — step by step
+
+1. Go to **New story -> import icon**, or directly to `https://medium.com/p/import`.
+2. Paste the **original article URL** (the one on your own site).
+3. Click **Import**. Medium crawls the page and creates a draft.
+4. What it sets automatically:
+   - **Canonical link** -> the URL you pasted (your origin keeps SEO credit).
+   - **Publish date** -> backdated, read from the page's `article:published_time` meta tag.
+5. Review the draft for formatting drift (see the formatting gotchas in SKILL.md), set up to 5 tags, then **Publish**.
+
+The import is a one-time content copy plus metadata. Editing the Medium draft afterward does not sync back to your site, and vice versa.
+
+## Manual canonical link — exact UI path
+
+Use this when you drafted natively in Medium, or after a failed import where you pasted the body manually.
+
+1. Open the story in the editor (draft or published).
+2. Click **More options (•••)** in the top bar.
+3. **Story settings** -> the advanced/edit settings panel.
+4. Find **"Customize canonical link"**, paste the **origin URL**, save.
+5. Publish (or update if already published).
+
+This is per-story. There is no account-wide canonical default. The canonical must always point at the *original* location, never at the Medium story itself.
+
+Manual paste does **not** backdate. If the date matters, the import tool is the only path that backdates automatically; otherwise the Medium publish date is "now".
+
+## Static-HTML workaround for stubborn imports
+
+When the importer can't crawl your real page (JS-only rendering, bot wall, login wall, timeout), give it a clean page it *can* read:
+
+1. Export the article to a single static HTML file — content in the initial server markup (no client-side hydration required).
+2. Include both metadata tags the importer relies on:
+
+```html
+<link rel="canonical" href="https://mysite.com/original-post" />
+<meta property="article:published_time" content="2026-04-12T09:00:00Z" />
+```
+
+3. Host it at a public, anonymously reachable URL (a temporary path is fine).
+4. Run the import against **that** URL. Canonical and backdate come from the tags above, so they still point at your real origin and your real date.
+5. Once the Medium draft exists with correct metadata, you can take the temporary static page down.
+
+The canonical in the static page should still be your *real* origin URL, not the temporary static page — that's what search engines will credit.
+
+## HTTP error -> cause -> fix matrix
+
+| HTTP / symptom | Root cause | Fix |
+|---|---|---|
+| 400 | Malformed/redirecting URL, or required page metadata absent | Use the final canonical URL; confirm `<link rel="canonical">` and `article:published_time` present |
+| 404 | Page not reachable for the crawler (private, moved, geo/IP-blocked) | Make it publicly reachable, or use the static-HTML workaround |
+| 403 | Bot-blocking — WAF, Cloudflare challenge, login/paywall | Allowlist the crawler, serve a clean static copy, or paste natively + set canonical manually |
+| 500 | Origin server error during crawl | Retry; if persistent, serve a lightweight static version |
+| 504 | Crawl timeout — heavy JS, slow TTFB | Provide a fast static HTML version with content in initial markup |
+| Imports but body empty/garbled | Content rendered client-side only | Static HTML with the article text in the server-rendered markup |
+| Catch-all "couldn't import" | Any of the above combined | Fall back to native paste + manual "Customize canonical link" |
+
+## Verify a cross-post
+
+- View source / story settings on the published Medium story; confirm canonical resolves to the origin URL.
+- Confirm the displayed publish date matches the original.
+- Confirm <=5 tags, code blocks intact, no broken tables.

package/skills/medium-publishing/references/legacy-api.md

@@ -0,0 +1,100 @@
+# Legacy Medium API — pre-2025-token holders only
+
+> **Closed to new integrations.** As of **2025-01-01** Medium issues no new integration tokens and accepts no new integrations. Only tokens minted before that date still authenticate. Do not attempt to register a new token — it will be refused. This reference is useful **only** if you already hold a pre-2025 token. For everyone else, the publishing path is the web editor + import tool (see `cross-post-and-canonical.md`).
+
+## Auth
+
+All requests use a Bearer integration token:
+
+```
+Authorization: Bearer <MEDIUM_INTEGRATION_TOKEN>
+Content-Type: application/json
+Accept: application/json
+```
+
+Base URL: `https://api.medium.com/v1`.
+
+## Resolve the user id
+
+You need your `userId` before posting. Get it from `/me`:
+
+```bash
+curl -s -H "Authorization: Bearer $MEDIUM_TOKEN" \
+  https://api.medium.com/v1/me
+```
+
+```json
+{
+  "data": {
+    "id": "5303d74c64f66366f00cb9b2a94f3251bf5",
+    "username": "yourhandle",
+    "name": "Your Name",
+    "url": "https://medium.com/@yourhandle",
+    "imageUrl": "https://cdn-images-1.medium.com/..."
+  }
+}
+```
+
+## Create a post on your profile
+
+`POST /v1/users/{userId}/posts`
+
+```bash
+curl -s -X POST \
+  -H "Authorization: Bearer $MEDIUM_TOKEN" \
+  -H "Content-Type: application/json" \
+  https://api.medium.com/v1/users/<userId>/posts \
+  -d '{
+    "title": "My title",
+    "contentFormat": "markdown",
+    "content": "# My title\n\nBody in markdown...",
+    "canonicalUrl": "https://mysite.com/original-post",
+    "tags": ["react", "javascript", "web-development"],
+    "publishStatus": "draft",
+    "license": "all-rights-reserved"
+  }'
+```
+
+### Request fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `title` | string | Story title (also used for the SEO title) |
+| `contentFormat` | string | `html` or `markdown`. Markdown here is more permissive than the web editor |
+| `content` | string | The body, in the chosen format |
+| `canonicalUrl` | string | Set to the **origin** URL for a cross-post — preserves your site's SEO credit |
+| `tags` | string[] | Up to 5; extras are dropped |
+| `publishStatus` | string | `public` \| `draft` \| `unlisted` |
+| `license` | string | e.g. `all-rights-reserved`, `cc-40-by`, `public-domain` |
+| `notifyFollowers` | boolean | Whether followers are notified |
+
+### Response (success)
+
+```json
+{
+  "data": {
+    "id": "e6f36a",
+    "title": "My title",
+    "authorId": "5303d74c64f66366f00cb9b2a94f3251bf5",
+    "url": "https://medium.com/@yourhandle/my-title-e6f36a",
+    "canonicalUrl": "https://mysite.com/original-post",
+    "publishStatus": "draft",
+    "tags": ["react", "javascript", "web-development"],
+    "license": "all-rights-reserved"
+  }
+}
+```
+
+## Create a post in a publication
+
+`POST /v1/publications/{publicationId}/posts` — same body shape.
+
+A `publishStatus: "draft"` under a publication remains **pending** an editor's action; it is not live until an editor publishes it, and you must be an accepted writer for that publication.
+
+## Why automation plans usually fail in 2026
+
+- New tokens: refused (closed since 2025-01-01).
+- Make: the Medium app is legacy — only pre-existing connections work.
+- n8n: Medium credentials still listed but cannot be newly configured.
+
+If the user has no pre-2025 token, route them to the import-tool path. Do not build a pipeline that assumes a new token.