seo-fix — Conservative Preview-First Remediation

1. Description & Activation Criteria

Use seo-fix when:

• An audit (report.json) has identified fixable HTML <head> defects on local .html/.htm files or a static build directory.
• The user asks to remediate, patch, or auto-fix SEO findings in their project.

Always run in preview (dry-run) mode first and obtain explicit user confirmation before passing --apply.

2. Inputs & Prerequisites

• Target path (required): Local .html/.htm file, directory, or file:// URL.
• Explicit metadata flags (recommended so values are never guessed):
  • --url <https://...>: Canonical and og:url target.
  • --lang <bcp47>: Document language for <html lang="..."> (required for lang fixer; never guessed).
  • --title <text>: Explicit <title> (otherwise derived conservatively from the first <h1>).
  • --description <text>: Explicit meta description (otherwise derived from opening body prose >=40 chars).
  • --og-image <https://...>: Absolute image URL for og:image.
  • --only <fixers>: Comma-separated subset of fixers (charset,viewport,lang,title,description,canonical,og,og-url,twitter-card,favicon).

3. Step-by-Step Workflow

1. Inspect current git status:
   • Check git status --short on the target files so uncommitted work is noted before any edits.
2. Run a dry-run preview (no --apply):
   • Execute npx one-step-seo fix <path> --url <canonical-url> --lang <lang> (without --apply).
   • Inspect the planned fixes, skipped fixers (with reasons), and unified diff output.
3. Present the diff and request approval:
   • Show the user the exact unified diff and list which finding IDs (T10-charset, T11-viewport, T09-lang, O01-title-missing, O02-meta-missing, T08-canonical, O06-og, W02-og-url, W01-social, O07-favicon) will be cleared.
   • For findings that fix intentionally refuses to auto-edit (e.g., O08-alt, T07-noindex, C01-thin, S01-none), present copy-paste snippets from report.md / lib/finding-meta.mjs.
4. Apply approved fixes with backups:
   • Once approved, run npx one-step-seo fix <path> ... --apply.
   • Confirm in-memory verification marks (verified: ... check) and .bak backup creation.
5. Re-audit to verify score improvement:
   • Run npx one-step-seo page <path> --offline and compare against the pre-fix report.json using npx one-step-seo diff old-report.json new-report.json.

4. Tools & CLI Commands

# Step 1: Dry-run preview (default, writes nothing)
npx one-step-seo fix ./dist/index.html --url https://example.com/ --lang en

# Step 2: Machine-readable fix plan for agent inspection
npx one-step-seo fix ./dist --url https://example.com/ --lang en --json

# Step 3: Apply after user approval (writes *.bak backups by default)
npx one-step-seo fix ./dist/index.html --url https://example.com/ --lang en --apply

5. Evidence Requirements

• Cite every planned fixer by its name, findingId, and summary from the one-step-seo fix output.
• Report every skipped fixer and its exact reason (e.g., --lang not provided (language is never guessed) or existing non-UTF-8 charset is never overwritten).
• Show the before/after Search SEO and AI Visibility scores from re-auditing the patched file.

6. Expected Outputs

1. Planned Fix Table: Fixer name, target finding ID, action summary, and verification status (cleared: true | partial).
2. Unified Diff Preview: Exact <head> insertions to be made.
3. Manual Remediation Snippets: Structured JSON-LD or content recommendations for issues outside the 10 additive fixers.
4. Post-Apply Verification: Output of one-step-seo diff confirming resolved findings and zero regressions.

7. Limitations & External Data

• Additive <head> fixes only: one-step-seo fix only inserts missing metadata into local HTML files containing a <head> tag.
• Refused by design: Never removes noindex, never fabricates image alt text (O08-alt requires inspecting the image), never rewrites existing short/long titles or descriptions, and never overwrites non-UTF-8 encodings.
• Framework templates: If ./dist is generated by Next.js, Astro, Remix, or WordPress, inform the user that patching ./dist proves the fix, and help port the metadata tags to their source layout component.

8. Safety & Approval Rules

• Never run --apply without prior user approval of the dry-run diff.
• Keep backups enabled: Do not pass --no-backup unless the user explicitly asks to omit .bak files in a clean git working tree.
• Never invent facts: Never pass made-up company names, phone numbers, pricing, or ratings into --title, --description, or schema snippets.

9. Examples

# Preview only canonical and Open Graph fixes on a local file
npx one-step-seo fix ./public/pricing.html \
  --only canonical,og,og-url,twitter-card \
  --url https://example.com/pricing \
  --og-image https://example.com/images/pricing-og.png

# Apply approved fixes and verify with diff
npx one-step-seo fix ./public/pricing.html \
  --only canonical,og,og-url,twitter-card \
  --url https://example.com/pricing \
  --og-image https://example.com/images/pricing-og.png \
  --apply