preview-og

name	preview-og
description	Previews, validates, and fixes Open Graph / Twitter share cards — how a link renders on Facebook, X, LinkedIn, and Discord/Slack. Runs the metaprev CLI to catch missing or broken og:image, relative URLs, wrong dimensions, oversized files, and weak titles, then applies fixes and re-verifies. Use before shipping a page or when a share preview looks broken. Not for page copy (use write-copy), search/AEO (use optimize-seo), og:image artwork (use produce-asset), or posting (use publish-social).
argument-hint	[url or localhost dev server]
allowed-tools	Read Edit Write Grep Glob Bash
metadata	{"version":"1.1.0","budget":"standard","estimated-cost":"$0.10-0.50"}

Preview OG — Share-Card Validation & Fix

Runs the metaprev CLI against a URL (local dev server or deployed), reads how the link renders on Facebook / X / LinkedIn / Discord-Slack, fixes what's broken in the codebase, then re-verifies. Routing: routing.yaml · why / when-not / install / pushback: references/playbook.md [PLAYBOOK].

Core question: When someone pastes this link into a chat or feed, does the card render — right image, right size, right title — or is it broken or blank?

Critical Gates — load first

1. CLI present before running. metaprev runs on Bun. Probe for it; install if missing — never stall on a missing tool. Exact probe + install commands: references/playbook.md § Install.
2. Verify after fixing (objective gate). Re-run metaprev after every fix; the tool, not the agent's judgment, is the pass/fail signal. The re-run passes only when:
   • metaprev issues <url> --json exits 0 — zero errors (advisory warns allowed)
   • og:image is an absolute URL returning HTTP 200 with an image content-type
   • declared og:image:width/og:image:height match the real file's dimensions Auto-fail: a 4th fix cycle — stop at 3 and report DONE_WITH_CONCERNS.
3. og:image must be an absolute URL. A relative /og.png resolves to nothing when a crawler fetches it standalone — the #1 silent break. Always emit a full https://….
4. Noise pushback. title is short / description is short are advisory SEO heuristics, not breaks — a canonical brand or product title is intentional. Surface them; never pad copy to hit a char count. § Pushback in the playbook.
5. Scope. Touch only the meta / OG surface (head tags, og:image config). No unrelated refactors.

Before Starting

Per references/_shared/before-starting-check.md [PROCEDURE]. Resolve the target: a localhost dev server (any framework / port) or a deployed URL. If none is derivable from the request or repo, ask once (Cold Start). Mode resolution per references/_shared/mode-resolver.md [PROCEDURE]; --fast runs one diagnose→fix→verify pass without the artifact write. Session execution profile (single-vs-multi): inherit per references/_shared/execution-policy.md.

Pre-Dispatch (Cold Start)

Needed dimensions — resolve from the repo / running dev server first, ask once (bundled) only for what's missing:

1. Target — localhost dev-server URL/port or deployed URL. → routing only
2. Canonical production origin — the absolute base URL og:image must resolve against (Gate 3). → technical
3. Platforms that matter — Facebook / X / LinkedIn / Discord-Slack (default: all four). → routing only

Pipeline

1. Resolve target — localhost dev server or deployed URL.
2. Ensure CLI — Gate 1.
3. Diagnose — bunx @hungv47/metaprev issues <url> --json for structured issues (exit 1 = at least one error). For a visual pass, bunx @hungv47/metaprev <url> -o docs/forsvn/artifacts/marketing/preview-og-<date>.html --no-open.
4. Triage — separate errors (real breaks) from advisory warns (Gate 4).
5. Fix — apply framework-aware fixes in the codebase: references/fixes.md [PROCEDURE] (Next / Astro / SvelteKit / Vite / plain HTML — absolute URL, dimensions, missing tags, content-type).
6. Re-verify — Gate 2. Loop until issues returns clean or only advisory warns remain (max 3 fix cycles, then DONE_WITH_CONCERNS).
7. Report — write the artifact + completion status.

Artifact Contract

Output: docs/forsvn/artifacts/marketing/preview-og-<YYYY-MM-DD>-<slug>.md. Frontmatter + sections (Target / Issues found / Fixes applied / Verification / Remaining advisory): references/format-conventions.md [PROCEDURE]. Skills emit Markdown only; the .html metaprev preview is a transient review surface, not the artifact.

Anti-Patterns

references/anti-patterns.md [ANTI-PATTERN] — top hits: padding title / description to silence advisory warns; declaring og:image:width/height that don't match the real file (Slack / Discord mis-crop); shipping a relative og:image; calling it done without the verify re-run.

Durable Rules (protected)

Completion Status

• DONE — metaprev re-run returns clean (or only advisory warns the operator chose to keep); fixes applied + artifact written.
• DONE_WITH_CONCERNS — fixes applied but one issue needs an asset the agent can't produce (a correctly-sized og:image → hand off to produce-asset), or a platform cache must clear before it shows.
• NEEDS_CONTEXT — no target URL resolvable; ask for the dev-server port or deployed URL.
• BLOCKED — target unreachable (auth wall / down), or Bun cannot be installed.

Worked Example

Relative og:image on a Next.js site → fix metadataBase → re-verify clean: references/examples/walkthrough.md [EXAMPLE].

References

• Playbook + install + pushback: references/playbook.md [PLAYBOOK]
• Fixes (framework recipes): references/fixes.md [PROCEDURE]
• Format: references/format-conventions.md [PROCEDURE]
• Anti-patterns: references/anti-patterns.md [ANTI-PATTERN]
• Example: references/examples/walkthrough.md [EXAMPLE]
• Shared: references/_shared/{before-starting-check, mode-resolver}.md