seo-fix · diff

git:20261105.f7f8170 to git:20261105.12a3bbd

1 added, 1 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: seo-fix
description: Preview and safely apply additive HTML metadata remediations (charset, viewport, lang, title, description, canonical, Open Graph, Twitter card, favicon) on local files using one-step-seo fix.
---
# 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
```bash
# 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 melihat/inspecting the image), never rewrites existing short/long titles or descriptions, and never overwrites non-UTF-8 encodings.
+ - **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
```bash
# 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
```