AI Search Visibility

Lesson 5 · Discover · $ai-search-visibility

Audit selected page snapshots for target-question answerability, entity positioning, headings, evidence and cross-page consistency, then recheck the same scope after edits. Use for AEO content review; do not promise search ranking, AI citations, indexing or publication.

Prerequisites and five-minute quickstart

Requires the course foundation (#222), Lesson 5 packages and Python 3.10+. Commands run from the handbook root; Windows users may substitute python/py for python3. Use synthetic fixtures and an isolated student workspace. Social browser-adapter contract tests also need Node.js; actual browser execution needs separately provisioned demo backend capability and a signed-in Host session.

python3 skills/ai-search-visibility/scripts/aeo_audit.py --site skills/ai-search-visibility/examples/site --spec skills/ai-search-visibility/examples/audit-spec.json
python3 skills/course-support/scripts/course_store.py read aeo_audits course-aeo

Expected: five structural findings in the imperfect two-page fixture: missing entity introduction, skipped heading level, missing evidence attribution, an unanswered build question, and conflicting duration values (90/120 minutes). Each finding has source evidence or explicitly notes the missing signal. Files remain unchanged; no site was fetched, indexed or published.

Sample Codex prompt:

Use $ai-search-visibility on this package's two local sample pages and target-query spec. Explain each finding with its page and line evidence, then save and read back the local audit. After I edit a copy, recheck the same audit id and scope. Do not alter the original pages or claim an improvement in live search rankings.

20–30 minute exercise and one modification

Spend 5 minutes reviewing the target questions, 10 minutes checking findings against both pages, 5 minutes correcting a copy of the duration/entity/heading/build-answer issues using the synthetic fact brief, and 5 minutes rerunning the same audit id with --expected-revision 1. The brief explicitly supplies the example build deliverable; do not infer workshop facts from campaign drafts. Those four supported fixes should resolve four findings. Leave missing evidence attribution open unless you have a relevant reviewed source; an unrelated external link is not a fix. Modification: change the target-query set and observe that removed findings are not called resolved. Evidence quality still requires human judgment.

Persistence, readback and recovery

aeo_audits stores target queries, scope hash, page source hashes/URLs, structural signals, short evidence excerpts, findings, recommendations and recheck comparison under a stable audit id/revision. skill_runs records each audit. Local snapshots are never uploaded as raw HTML, and the audit does not modify them. New reports are saved separately.

Select global --storage local|prompthon, organization, workspace and state directory before subcommands; use the same scope for readback. The default is local/offline. Remote API/auth/Neon deployment is not created by installing these packages. A failed remote write does not silently become local success. See shared setup.

Read runs with python3 skills/course-support/scripts/course_store.py runs --skill ai-search-visibility. Every reported id must come from the actual tool response; fixture domains and mock receipts are not live results.

Reset and instructor notes

Preview the shared course_store.py reset, review its scope, then confirm the selected demo workspace with --confirm demo-student. It removes all course records in that workspace, not files, web pages, canonical Social campaigns/posts or external deliveries. Use a fresh workspace for repeat exercises and the owning app's separately authorized cleanup flow for actual Social objects; never silently delete them.

Review the actual source, plan, canonical records and audit/report evidence. A content calendar is not a schedule; a course simulation is not public publication; an AEO heuristic is not measured ranking. English lab · 中文课堂指引.

Validate with python3 -m unittest discover -s skills/content-strategy/tests -p 'test_*.py' -v. This includes an entirely mocked Node Social contract harness; no external delivery is performed. See safety, persistence, and sources.