aeoptimize 0.5.3 → 0.6.1

package/.claude-plugin/marketplace.json

@@ -4,18 +4,18 @@
     "name": "Te-Shu Wang"
   },
   "metadata": {
-    "description": "AI search optimization: scan, generate, and transform website content for AI readability",
-    "version": "0.5.3"
+    "description": "Content-readiness lint with evidence-bounded AI discovery experiments",
+    "version": "0.6.1"
   },
   "plugins": [
     {
       "name": "aeoptimize",
       "source": "./",
-      "description": "CLI toolkit + Claude Code skills for transforming SEO-optimized websites into AI-search-ready content",
+      "description": "CLI and Claude Code skills for reproducible content-readiness checks",
       "category": "seo",
       "tags": ["aeo", "seo", "ai-search", "llms-txt", "structured-data"],
-      "homepage": "https://github.com/dexuwang627-cloud/aeoptimize",
-      "repository": "https://github.com/dexuwang627-cloud/aeoptimize"
+      "homepage": "https://github.com/cucuwang/aeoptimize",
+      "repository": "https://github.com/cucuwang/aeoptimize"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,12 +1,12 @@
 {
   "name": "aeoptimize",
-  "description": "AI search optimization toolkit: scan, generate, and transform website content for AI readability",
-  "version": "0.5.3",
+  "description": "Content-readiness lint and evidence-bounded discovery experiments",
+  "version": "0.6.1",
   "author": {
     "name": "Te-Shu Wang"
   },
-  "homepage": "https://github.com/dexuwang627-cloud/aeoptimize",
-  "repository": "https://github.com/dexuwang627-cloud/aeoptimize",
+  "homepage": "https://github.com/cucuwang/aeoptimize",
+  "repository": "https://github.com/cucuwang/aeoptimize",
   "license": "MIT",
   "keywords": ["aeo", "seo", "ai-search", "llms-txt", "structured-data", "claude-code-skill"],
   "commands": [

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable user-visible changes will be documented here. The project follows Semantic Versioning after the v0.6 evidence baseline is released.
+
+## 0.6.1
+
+### Fixed
+
+- Bound public CLI verification to the downloaded tarball that passed SHA-256 verification.
+- Added an executable clean-worktree release candidate gate and cross-Node package reproducibility check.
+- Exercised the public rule corpus across the HTML parser boundary and strengthened release verifier failure tests.
+
+## 0.6.0
+
+### Changed
+
+- Reframed the score as deterministic content readiness rather than a prediction of ranking or AI citation.
+- Classified FAQ and `llms.txt` as optional, zero-point signals.
+- Removed the exact-one-H1 and fixed meta-description-length assumptions.
+- Changed quantitative-content guidance to flag unsourced claims instead of rewarding more numbers.
+- Stopped inferring `FAQPage` structured data from question headings.
+- Limited CI support to maintained Node.js LTS lines and refreshed dependencies.
+- Added methodology, contribution, security, roadmap, and root GitHub Action files.
+- Made the GitHub Action advisory by default, with explicit blocking mode, version-matched package installation, stable outputs, and contract fixtures.
+- Added a public positive, negative, and false-positive boundary corpus for every scored rule.
+- Added a copyable end-to-end GitHub Action sample plus release and rollback instructions.
+
+### Security
+
+- Updated runtime and development dependencies to remove known npm audit findings present in the previous lockfile.
+
+## 0.5.3 — 2026-04-15
+
+- Added the `aeoptimize` executable alias.
+- Synchronized CLI, Action, and plugin version metadata.

package/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing
+
+Contributions that make `aeoptimize` more reproducible, explainable, or easier to adopt are welcome.
+
+## Development setup
+
+Use Node.js 22.12 or newer. Node 24 LTS is the recommended development version.
+
+```bash
+npm ci
+npm run check
+npm pack --dry-run
+npm audit --audit-level=high
+```
+
+Do not commit `node_modules`, `dist`, package tarballs, credentials, or reports containing private URLs.
+
+## Pull requests
+
+Keep each pull request focused. Include:
+
+- the problem and user workflow;
+- tests or fixtures that fail before the change and pass after it;
+- JSON/output compatibility notes;
+- documentation updates for user-visible behavior;
+- the source and evidence class for any scoring-rule change.
+
+Rule proposals must follow [docs/methodology.md](docs/methodology.md). Unsupported ranking, citation, adoption, or performance claims will not be accepted. Do not add fabricated statistics to examples or fixtures.
+
+## Commit and review expectations
+
+- Run `npm run check`, `npm pack --dry-run`, and `npm audit --audit-level=high`.
+- Preserve deterministic output unless the pull request explicitly versions the methodology change.
+- Treat generated JSON-LD and crawler policy as reviewable candidates, never universal defaults.
+- Add a changelog entry for behavior, compatibility, security, or methodology changes.
+
+Opening an issue before a large change is recommended so scope and compatibility can be agreed first.

package/README.md

@@ -1,204 +1,160 @@
 # aeoptimize
 
 [![npm version](https://img.shields.io/npm/v/aeoptimize.svg)](https://www.npmjs.com/package/aeoptimize)
-[![CI](https://github.com/dexuwang627-cloud/aeoptimize/actions/workflows/ci.yml/badge.svg)](https://github.com/dexuwang627-cloud/aeoptimize/actions/workflows/ci.yml)
-[![license](https://img.shields.io/npm/l/aeoptimize.svg)](https://github.com/dexuwang627-cloud/aeoptimize/blob/main/LICENSE)
+[![CI](https://github.com/cucuwang/aeoptimize/actions/workflows/ci.yml/badge.svg)](https://github.com/cucuwang/aeoptimize/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/aeoptimize.svg)](https://github.com/cucuwang/aeoptimize/blob/main/LICENSE)
 
-**CLI toolkit + Claude Code skills that transform SEO-optimized websites into AI-search-ready content.**
+Deterministic content-readiness lint for static websites and documentation.
 
-## Why AEO?
+`aeoptimize` checks reproducible properties such as document structure, sourced quantitative claims, structured-data hygiene, indexing controls, metadata quality, and repetitive wording. It is intended for local development and CI regression checks.
 
-| | SEO | AEO |
-|---|---|---|
-| **Goal** | Rank higher | Get cited |
-| **Audience** | Search crawler | Language model |
-| **Key metric** | Position | Citation accuracy |
-| **Content style** | Keyword-rich | Self-contained, structured |
-| **Structured data** | Nice to have | Essential |
+It does **not** predict ranking, indexing, rich results, Google AI Overviews, or citation by ChatGPT, Perplexity, or another AI system. Google states that its AI search features need no special AI text file or schema, and valid structured data does not guarantee a search feature. See [methodology and limitations](docs/methodology.md).
 
-67% of users now get their first answer from AI. If your content can't be extracted and cited, it's invisible.
+## Quick start
 
-AI search engines (ChatGPT, Perplexity, Google AI Overview) don't rank pages — they **cite** content. `aeoptimize` helps you make your content citable.
-
-## Quick Start
+Requires Node.js 22.12 or newer.
 
 ```bash
-npx aeoptimize scan your-site.com
+npx aeoptimize scan https://example.com
+npx aeoptimize scan ./dist --dir
+npx aeoptimize scan ./dist --dir --json
 ```
 
-```
-AEO Readability Report
-Score: 61/100  AI Readability: Good
-
-  Structure        ██████████████░░░░░░ 18/25
-  Citability       ████████████░░░░░░░░ 16/25
-  Schema           ███████░░░░░░░░░░░░░  7/20
-  AI Metadata      ███████░░░░░░░░░░░░░  8/15
-  Content Density  ███████████████░░░░░ 12/15
-
-Top Suggestions:
-  → Add FAQ section with question-format headings
-  → Add AI-relevant schema types
-  → Create and link an llms.txt file
+Example output:
+
+```text
+Content Readiness Report
+Score: 71/100
+
+Structure        20/25
+Citability       18/25
+Schema           16/20
+AI Metadata      10/15
+Content Density   7/15
 ```
 
-## Features
+The score is a versioned heuristic for catching regressions within the same project. Do not treat it as a percentage chance of search or AI visibility, and do not compare unrelated sites as if it were an outcome metric.
 
-### Scan — AI Readability Audit
+## What is scored
 
-17 rules across 5 dimensions, 0-100 score. Zero cost, offline capable, deterministic.
+| Dimension | Max | Scope |
+| --- | ---: | --- |
+| Structure | 25 | Document outline and readability heuristics |
+| Citability | 25 | Claim specificity, source signals, definitions, attribution |
+| Schema | 20 | JSON-LD structural hygiene when present; absence is not penalized |
+| AI Metadata | 15 | Page-level indexing control and description quality |
+| Content Density | 15 | Content/boilerplate and repetition heuristics |
 
-```bash
-npx aeoptimize scan https://example.com          # Remote URL
-npx aeoptimize scan ./dist --dir                   # Local directory
-npx aeoptimize scan ./dist --dir --json            # Machine-readable
-```
+Two often-promoted AEO signals are deliberately excluded from the score:
+
+- FAQ content and `FAQPage` schema are optional. The generator does not infer FAQ schema from question headings.
+- `llms.txt` is an experimental proposal. Generating or publishing it does not add points.
 
-| Dimension | Max | What it measures |
-|-----------|-----|------------------|
-| **Structure** | 25 | Heading hierarchy, paragraph length, FAQ presence |
-| **Citability** | 25 | Self-contained statements, data/stats, definitions |
-| **Schema** | 20 | JSON-LD presence, completeness, AI-relevant types |
-| **AI Metadata** | 15 | llms.txt, robots.txt AI config, meta description |
-| **Content Density** | 15 | Content vs boilerplate, keyword stuffing detection |
+Every rule, its evidence class, and known false-positive boundary is documented in [docs/methodology.md](docs/methodology.md) and exercised by the [versioned public fixture corpus](fixtures/v0.6/rule-corpus.ts).
 
-### Multi-AI Scoring
+## CI contract
 
-Score with multiple AI engines simultaneously. Detects `gemini` and `copilot` CLIs, dispatches parallel scoring, merges with rule engine.
+`--json` is the stable automation surface. A non-zero threshold is useful only after your team reviews the baseline and accepts the current methodology version.
 
 ```bash
-npx aeoptimize scan https://example.com --multi-ai
+npx aeoptimize scan ./dist --dir --json > aeoptimize-report.json
+node -e "const r=require('./aeoptimize-report.json'); process.exit(r.overall.total < 60 ? 1 : 0)"
 ```
 
+The v0.6 GitHub Action is advisory by default. It reports findings without blocking the workflow:
+
+```yaml
+- uses: cucuwang/aeoptimize@v0.6.1
+  with:
+    path: dist
 ```
-Score: 72/100 (Rule Engine: 61 | AI Consensus: 83)
 
-  Rule Engine      ████████████░░░░░░░░ 61/100
-  Claude           ████████████████░░░░ 85/100
-  Gemini           ████████████████░░░░ 81/100
+Projects can explicitly choose blocking mode after accepting a baseline:
 
-AI Insights:
-  Claude:  "FAQ section lacks schema markup"
-  Gemini:  "Missing llms.txt reduces discoverability"
+```yaml
+- uses: cucuwang/aeoptimize@v0.6.1
+  with:
+    path: dist
+    fail-on-low-score: 'true'
+    min-score: '60'
 ```
 
-| Scenario | Weighting |
-|----------|-----------|
-| Rule engine + 2+ AIs | 50% rules + 50% AI average |
-| Rule engine + 1 AI | 60% rules + 40% AI |
-| Rule engine only | 100% rules |
+The Action exposes `score` and `report` outputs in both modes. Its release is reproducible only when the Action tag and matching npm package version both exist. Before pinning a version, verify both artifacts; if either is missing, use the CLI directly.
+
+A copyable advisory workflow and controlled input are available in the [end-to-end Action sample](examples/github-action-sample/README.md).
 
-### Generate — AI Infrastructure Files
+## Optional generators
 
 ```bash
-npx aeoptimize generate ./dist --dry-run           # Preview
-npx aeoptimize generate ./dist                    # Write files
+npx aeoptimize generate ./dist --dry-run
+npx aeoptimize generate ./dist
 ```
 
-Generates:
-- **llms.txt** — Machine-readable site summary ([llmstxt.org](https://llmstxt.org) standard)
-- **llms-full.txt** — Full content for deep AI consumption
-- **JSON-LD schemas** — Article, FAQPage, BreadcrumbList
-- **robots.txt suggestions** — AI crawler allow/deny rules
-
-### Transform — AI Content Restructuring (Claude Code Skill)
+The generator can create:
 
-Uses your existing Claude subscription — zero extra cost:
+- `llms.txt` and `llms-full.txt` as experimental outputs based on the [llms.txt proposal](https://llmstxt.org/);
+- candidate `Article` and `BreadcrumbList` JSON-LD for manual review;
+- crawler-specific `robots.txt` suggestions, printed but never applied automatically.
 
-- Split long paragraphs into citable statements
-- Extract implicit Q&A into FAQ schema
-- Remove keyword stuffing
-- Fix dangling references ("This...", "It...", "They...")
-- Inject structured data
+Generated structured data must be reviewed against visible content and the applicable search-engine documentation. The generator intentionally does not create `FAQPage` from headings alone.
 
-## Framework Plugins
+## Framework integrations
 
 ### Vite
 
 ```ts
-// vite.config.ts
+import { defineConfig } from 'vite';
 import { aeoPlugin } from 'aeoptimize/vite';
 
 export default defineConfig({
-  plugins: [aeoPlugin()]
+  plugins: [aeoPlugin()],
 });
 ```
 
 ### Next.js
 
-```ts
-// next.config.mjs
+```js
 import { withAeo } from 'aeoptimize/next';
 
 export default withAeo({});
 ```
 
-Build 時自動生成 `llms.txt`、`llms-full.txt`、`_aeo/generated-schemas.json` 並印出 AEO 分數。
-
-Options: `{ silent?: boolean; outDir?: string }`
-
-## Guardrails
-
-### Pre-commit Hook
-
-```bash
-npx aeoptimize hook install                # Default: min score 60
-npx aeoptimize hook install --min-score 80 # Custom threshold
-npx aeoptimize hook uninstall              # Remove hook
-```
+Both integrations scan the build output and generate the same optional artifacts as the CLI. Options: `{ silent?: boolean; outDir?: string }`.
 
-Automatically checks AEO score of staged `.html` and `.md` files before each commit. Blocks commit if any file scores below the threshold.
+## Experimental AI review
 
-Works with husky too — add to your `.husky/pre-commit`:
 ```bash
-npx aeoptimize scan ./dist --dir --json | node -e "const j=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); if(j.overall.total<60){console.error('AEO score too low:',j.overall.total);process.exit(1)}"
+npx aeoptimize scan https://example.com --multi-ai
 ```
 
-### GitHub Action
-
-```yaml
-# .github/workflows/aeo.yml
-name: AEO Check
-on: [pull_request]
-jobs:
-  aeo:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: dexuwang627-cloud/aeoptimize/action@v0.5.3
-        with:
-          path: dist
-          min-score: 60
-```
+When supported local AI CLIs are available, this adds a subjective review and reports an experimental blend. Model output can vary and is not ground truth. The deterministic rule score remains visible separately.
 
-## Claude Code Skills
+## Pre-commit hook
 
 ```bash
-claude plugin marketplace add dexuwang627-cloud/aeoptimize
+npx aeoptimize hook install
+npx aeoptimize hook install --min-score 60
+npx aeoptimize hook uninstall
 ```
 
-- `/aeo-scan` — Interactive audit with multi-AI scoring
-- `/aeo-generate` — Guided file generation with preview
-- `/aeo-transform` — AI-powered content restructuring
+The hook checks staged `.html`, `.htm`, `.md`, and `.mdx` content. Review the baseline before using a threshold to block commits; `git commit --no-verify` remains an explicit escape hatch.
 
-## Help
+## Claude Code skills
 
 ```bash
-npx aeoptimize --help            # All commands
-npx aeoptimize scan --help       # Scan options
-npx aeoptimize generate --help   # Generate options
+claude plugin marketplace add cucuwang/aeoptimize
 ```
 
-## Contributing
+- `/aeo-scan` — deterministic readiness audit with optional experimental review
+- `/aeo-generate` — preview optional discovery artifacts
+- `/aeo-transform` — propose content edits without inventing claims
+
+## Project status
 
-Contributions are welcome! Feel free to open issues or pull requests.
+The v0.6 evidence baseline focuses on methodology, reproducible fixtures, CI compatibility, packaging, and external adoption—not more scoring rules. Release acceptance and rollback are documented in [docs/release-v0.6.md](docs/release-v0.6.md); longer-term adoption work remains in [ROADMAP.md](ROADMAP.md).
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing`)
-3. Run tests (`npm test`)
-4. Commit your changes
-5. Open a Pull Request
+Contributions are welcome. Rule changes require an evidence note and positive/negative fixtures; see [CONTRIBUTING.md](CONTRIBUTING.md). Report vulnerabilities through the process in [SECURITY.md](SECURITY.md).
 
 ## License
 
-MIT
+MIT

package/ROADMAP.md

@@ -0,0 +1,31 @@
+# Roadmap
+
+## v0.6 — Evidence Release
+
+The release goal is a trustworthy CI lint contract, not additional AEO claims.
+
+Release gates:
+
+- current repository identity across npm, README, Action, and Claude plugin metadata;
+- green CI on supported Node.js LTS releases;
+- zero high or critical npm audit findings at release time;
+- versioned methodology with evidence classes and explicit non-goals;
+- public positive, negative, and false-positive fixtures for every scored rule;
+- root GitHub Action metadata and an end-to-end sample repository;
+- stable JSON output, changelog, release notes, and rollback instructions.
+
+The code-level gates are enforced by `npm run release:check`, `src/core/__tests__/release-contract.test.ts`, the versioned corpus in `fixtures/v0.6/`, and the local composite Action contract. CI compares real Node.js 22 and 24 package manifests and hashes. Repository rulesets and the release runbook remain separate maintainer controls.
+
+## Product validation after v0.6
+
+- Validate one core workflow: static site or documentation CI content-readiness lint.
+- Obtain three independently controlled public adoption examples.
+- Triage external issues and document support boundaries before adding framework breadth.
+- Measure technical outcomes such as a caught `noindex` regression or schema/content mismatch. Keep ranking and citation outcomes separate.
+
+## Not planned without new evidence
+
+- claiming that a readiness score predicts search position or AI citation;
+- awarding points for `llms.txt`, FAQ count, schema count, or a fixed meta-description length;
+- automatic deployment of generated JSON-LD or crawler policy;
+- adding more AI scorers and calling their average consensus.

package/SECURITY.md

@@ -0,0 +1,15 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are applied to the latest published minor release. Older releases may be asked to upgrade when a backport is not practical.
+
+## Reporting a vulnerability
+
+Use GitHub's private vulnerability reporting for `cucuwang/aeoptimize` when available. If the repository does not show a private reporting option, open a minimal issue asking for a private contact channel; do not include exploit details, credentials, private URLs, or user data in a public issue.
+
+Include the affected version, environment, reproduction preconditions, impact, and the smallest safe proof of concept. You should receive an acknowledgement within seven days. A remediation timeline depends on severity and reproducibility.
+
+## Scope notes
+
+`aeoptimize` can fetch remote pages, invoke a local browser, read build output, and install a Git hook. Reports may contain URLs and excerpts from scanned content. Review artifacts before publishing them and never scan private systems without authorization.

package/agents/aeo-ai-scorer.md

@@ -1,48 +1,19 @@
 ---
 name: aeo-ai-scorer
-description: Use when scoring a webpage's AI readability using Claude's language understanding, as part of the multi-AI scoring workflow in aeo-scan
+description: Use only for an explicitly requested experimental content-quality review alongside the deterministic aeoptimize report
 model: inherit
 ---
 
-You are an AEO (Answer Engine Optimization) scoring engine. Your job is to evaluate a webpage's AI search readiness and return a structured score.
+You are an experimental content-quality reviewer. Your output is subjective and must not be presented as a prediction of ranking, indexing, rich results, visibility, or citation.
 
-## Input
+Review the supplied content for:
 
-You will receive:
-1. The page's HTML content (or text extract)
-2. The rule engine's scan report (JSON)
+- descriptive hierarchy, readability, and semantically appropriate lists;
+- self-contained statements, sourced quantitative claims, definitions, and attribution;
+- structured data that matches visible content;
+- intentional indexing controls and page-specific descriptions;
+- boilerplate and repetitive wording.
 
-## Scoring Dimensions
+FAQ content is optional. `llms.txt` is an unscored proposal. Do not impose a fixed meta-description length, exact H1 count, keyword-density threshold, or schema count.
 
-Score each dimension on its scale:
-- **structure** (0-25): Heading hierarchy quality, paragraph length (ideal: 40-80 words), FAQ sections, list usage
-- **citability** (0-25): Self-contained statements (no dangling "This...", "It..."), data/statistics, clear definitions ("X is Y"), source attribution
-- **schema** (0-20): JSON-LD presence and completeness, AI-relevant types (Article, FAQPage, HowTo, Product)
-- **aiMetadata** (0-15): llms.txt reference, robots.txt AI crawler configuration, meta description quality (50-160 chars)
-- **contentDensity** (0-15): Content vs boilerplate ratio, keyword stuffing (>3% = bad), content uniqueness signals
-
-## Output Format
-
-Respond with ONLY valid JSON:
-
-```json
-{
-  "score": <total 0-100>,
-  "structure": <0-25>,
-  "citability": <0-25>,
-  "schema": <0-20>,
-  "aiMetadata": <0-15>,
-  "contentDensity": <0-15>,
-  "insight": "<one sentence: the single most impactful thing to fix>"
-}
-```
-
-## Guidelines
-
-- Be objective and consistent — same content should get same score
-- Compare against an ideal AEO-optimized page, not against average websites
-- The rule engine already checks structural patterns; focus on semantic quality that rules can't measure:
-  - Can you actually extract a citable quote from each paragraph?
-  - Does the content answer a specific question or just ramble?
-  - Would you cite this page when answering a user's question?
-- Do NOT inflate scores to be nice — a typical unoptimized page should score 30-50
+Return only the JSON shape requested by the caller. State the most important evidence-backed issue in `insight`. Repeated model runs may differ; the deterministic report remains the CI source of truth.

package/agents/aeo-analyzer.md

@@ -1,63 +1,17 @@
 ---
 name: aeo-analyzer
-description: Use when deep-analyzing a specific page for AI optimization opportunities, dispatched by aeo-scan for detailed per-page analysis
+description: Use when an explicit qualitative review is needed for a page after the deterministic readiness scan
 model: inherit
 ---
 
-You are an AEO (Answer Engine Optimization) specialist. Your job is to analyze a single web page and produce a detailed, actionable report on how to improve its AI search readability.
+You are a content-readiness reviewer. Separate deterministic findings, heuristics, and experiments; do not predict ranking or citation.
 
-## Your Analysis Should Cover
+For each proposed change:
 
-1. **Issue-by-Issue Breakdown**
-   - For each issue found by the scanner, explain WHY it matters for AI citation
-   - Reference specific content in the page (quote the problematic text)
-   - Rate fix difficulty: easy (5 min), medium (30 min), hard (1+ hour)
+1. quote the smallest relevant source passage;
+2. name the evidence class and false-positive boundary;
+3. provide a focused before/after diff;
+4. preserve meaning, voice, and factual provenance;
+5. state a deterministic score change only when the same scan reproduces it.
 
-2. **Prioritized Fix Recommendations**
-   - Order by: (impact on score) × (ease of implementation)
-   - Group related fixes together
-   - Estimate score improvement per fix
-
-3. **Before/After Examples**
-   - For the top 3 improvements, show exactly how the content should change
-   - Use diff format: what to remove vs what to add
-   - Explain why the "after" version is more AI-friendly
-
-4. **Content Strategy Notes**
-   - What type of AI queries would this page answer?
-   - What's missing that would make it the definitive source?
-   - Are there FAQ opportunities hidden in the content?
-
-## Output Format
-
-Structure your analysis as:
-
-```
-## Page: [title]
-Current Score: [X]/100
-
-### Priority Fixes
-
-#### 1. [Fix Name] — Expected improvement: +N points
-**Issue:** [what's wrong]
-**Why it matters:** [AI search impact]
-**Fix:**
-- Before: [quoted original]
-- After: [suggested replacement]
-
-[repeat for each fix]
-
-### Quick Wins (under 5 minutes each)
-- [list of easy fixes]
-
-### Summary
-- Current: X/100 → Estimated after fixes: Y/100
-- Most impactful change: [one sentence]
-```
-
-## Guidelines
-
-- Be specific — quote actual content, don't speak in generalities
-- Focus on what AI engines actually care about, not traditional SEO metrics
-- If the page is already well-optimized (>80), say so and suggest only minor refinements
-- Never suggest adding false claims or misleading structured data
+Prioritize unsupported quantitative claims, unintended indexing controls, structured data that conflicts with visible content, and clear readability regressions. Never invent claims, sources, authors, dates, FAQ content, or benefits. Use primary documentation for technical assertions.