Documentation

Reference material for the agent. Less narrative than the course; more "where is the thing I'm looking for."

CLI reference

Command	What it does
`agent ping`	Smoke-test the LLM gateway.
`agent discover`	Stage 1: run the 7-filter niche vetting + produce a markdown niche report.
`agent gather`	Stage 2: fetch listings from OpenStreetMap.
`agent build`	Stages 4+5: emit an Astro project + generate per-listing copy.
`agent release-build`	Stage 7: production build (npm + astro) + smoke test.
`agent release-deploy`	Stage 7: deploy to Cloudflare Pages, a tarball, or local preview.
`agent analytics-inject`	Stage 6: inject Plausible analytics tag into the layout.
`agent gsc-instructions`	Stage 6: print Google Search Console setup steps.
`agent monitor-rank`	Stage 10/12: poll Google SERP for your site's rank on each keyword.
`agent monitor-digest`	Stage 12: write a weekly markdown digest of rank deltas.
`agent outreach-draft`	Stage 11: draft a cold-pitch outreach email; queues for HITL review.
`agent reddit-draft`	Stage 8: draft a Reddit seed post; queues for HITL.
`agent state`	Show JSON state for a project.

Module map

Module	What's in it
`lib/`	Shared infrastructure: LLM gateway, browser context, state file, human-cursor helpers.
`discover/`	Stage 1: SERP scrape, keyword volume estimation, KD estimate, social-signal probe, filter orchestrator.
`data/`	Stage 2: OpenStreetMap loader, deduplication, custom-source extension point.
`build/`	Stage 4: Astro template strings, scaffold generator, helpers.
`seo/`	Stage 5: keyword clusters, copywriter, FAQ generator, internal-link planner.
`analytics/`	Stage 6: Plausible injection, GSC setup helpers.
`release/`	Stage 7: production build + deploy targets.
`seed/`	Stage 8: Reddit-seed planner.
`monitor/`	Stages 10+12: rank tracker, digest writer.
`links/`	Stage 11: qualify, outreach drafter, badge generator.

Configuration

All defaults live in config/default.yaml. Override anything per-run via env vars (see the file for which keys are env-overridable). The most common change is the LLM model:

llm:
  planner_model: "qwen2.5:32b-instruct"   # or qwen2.5:14b-instruct, llama3.1:8b
  base_url: "http://localhost:11434/v1"   # Ollama default; swap for hosted

Project state

Each project gets a directory under projects/<name>/ containing:

state.json — append-only record of which stages have run.
listings.jsonl — raw listings from Stage 2.
listings.csv — for spreadsheet review.
site/ — the generated Astro project (after Stage 4).
site_manifest.json — summary of what the build emitted.
content_cache.json — LLM-generated copy cache (so re-runs are free).
rank_history.csv — daily rank checks (Stage 10/12).
digests/<date>.md — weekly markdown digests.
outreach_queue/, reddit_queue/ — drafts pending your review.

Extension points

Adding a new niche — OSM tag or custom data source.
Customizing the Astro template — themes, components, custom fields.
Scaling to a portfolio — multi-directory operations.

Troubleshooting

See the install lesson for common errors (connection refused, command not found, npm install fails) and fixes.