cto-legends · module specification · intelligence · v0.2.1
legends-github: GitHub SEO, DataForSEO Demand & Repository Audit CLI
Deterministic Python CLI for GitHub repository audits, DataForSEO keyword and SERP demand, 20-topic synthesis, non-destructive READMEs, and OG checks.
GitHub Repository (https://github.com/avalonreset/legends-github) · Handoff: cto-legends handoff legends-github
legends-github is a portable Python 3.11+ repository audit, measured GitHub SEO, and release readiness toolkit operated via python legends_github.py <workflow>. It replaces guesswork repository tagging and destructive README templates with 13 deterministic workflows (capabilities, verify, audit, research, seo, meta, readme, discover, social-preview, release, community, legal, empire, and cache-status) that isolate generated reports and cache artifacts outside the target checkout via --artifacts-dir without ever touching the target repository's .gitignore.
Architecturally, legends-github separates unverified local keyword hypotheses from measured search evidence collected through legends-dataforseo. Its audit engine produces versioned evidence records (FINDINGS.json, SUMMARY.json, GITHUB-AUDIT-REPORT.md) that strictly distinguish observed, missing, unavailable, and not_applicable states so offline or unauthenticated runs are never falsely penalized as missing repository files. For repository presentation and discoverability, it synthesizes up to 20 hyphenated GitHub topics ranked by verified search volume and commercial CPC while stripping build-tool noise, preserves existing custom README layouts and HTML embeds verbatim in preserve-existing mode, and verifies served 1280x640 Open Graph social preview images via GitHub GraphQL pixel-for-pixel comparison.
Deterministic Execution Boundary
Why Raw Frontier LLM Prompts Cannot Replace Deterministic Execution
Ask a raw Frontier LLM in a chat window to 'optimize my GitHub repo for SEO' and it will hallucinate search volumes, stuff build-tool tags like vite or eslint into your 20 GitHub topic slots, overwrite custom README layouts and video embeds, and assume a social preview upload succeeded without checking what GitHub's CDN actually serves. A static prompt cannot query live keyword demand, enforce cost ceilings, or verify pixel parity against GitHub GraphQL.
- Measured DataForSEO Keyword & SERP Evidence vs. Guessed Tags: Instead of guessing keywords from filenames, research estimates and executes bounded Google keyword overview (dataforseo_labs/google/keyword_overview/live) and organic SERP (serp/google/organic/live/advanced) batches with explicit --confirm-cost-usd ceilings and receipt.json cost accounting. seo imports those verified datasets to rank secondary keywords by monthly search volume and CPC and detect whether github.com already ranks in Google's top 10 (github_in_serp, github_serp_position).
- 20-Slot Topic Synthesis & Router-Pin De-Noising: seo and meta generate up to 20 clean, hyphenated GitHub repository topics from verified keyword clusters while deterministically stripping low-value build filler (vite, webpack, eslint, prospecting) and preventing vendored router pins (skills/cto-legends/SKILL.md) from misclassifying standalone applications or CLIs as agent skills.
- Four-State Evidence Classification & Isolated Artifacts: Every audit finding records its source, timestamp, confidence, verification method, and applicability state (observed, missing, unavailable, or not_applicable). Private-repo 404s or --offline runs are recorded as unavailable rather than falsified as missing files, and --artifacts-dir writes all caches under an isolated SHA-256 repo-identity path.
- Non-Destructive README Evaluation (preserve-existing Mode): When a repository already has a README.md, readme_repo.py defaults to preserve-existing mode—retaining custom layouts, HTML video embeds, badges, and section ordering verbatim—while evaluating both agent-first onboarding sections (Agent setup, Start here, Talk to your agent, What you can do) and traditional Installation/Usage headings.
- Pixel-for-Pixel Open Graph Social Preview Verification: social-preview validates local 1280x640 PNG artwork and, after upload via the host's browser/file-picker tool, --verify queries GitHub GraphQL to compare the live served Open Graph image's dimensions and decoded pixels against the local file so stale CDN caches or fallback avatars never pass silently.
CLI Subcommands & Capability Surface
python legends_github.py [--offline] [--artifacts-dir DIR] audit --path <repo> | verify | cache-status — Versioned Repository Evidence Audit: Inspects source manifests, README structure, metadata, licensing, community health files, CI workflows, and release readiness across libraries, CLIs, services, apps, skills, and monorepos. Emits FINDINGS.json, SUMMARY.json, and GITHUB-AUDIT-REPORT.md with strict observed, missing, unavailable, and not_applicable evidence states.python legends_github.py research --path <repo> --keyword <kw> --serp <query> [--execute --confirm-cost-usd <usd>] — Bounded DataForSEO Keyword & SERP Research: Previews modeled API costs offline by default, or executes bounded Google keyword overview and organic SERP batches through legends-dataforseo when --execute is supplied. Checks remaining budget between requests, never retries paid calls, and writes raw provider exports plus receipt.json with reported_cost_usd.python legends_github.py seo --path <repo> --keyword-data <json> --primary-keyword <kw> --serp-data <json> | meta --path <repo> [--apply] — Verified SEO Synthesis & GitHub Metadata Application: Synthesizes repository keyword candidates or imports verified DataForSEO keyword/SERP JSON exports to prioritize secondary keywords by search volume and CPC, check github.com top-10 SERP presence, draft an SEO-forward About description, and apply up to 20 filtered GitHub topics and homepage settings via gh repo edit.python legends_github.py readme --path <repo> [--write] | discover --path <repo> --audience <str> --category <str> --competitor <name> — Non-Destructive README Preservation & Organic Discovery Planning: Evaluates README structure across agent-first and traditional developer headings while preserving existing custom README content verbatim in preserve-existing mode. The discover workflow builds an evidence-backed organic discovery plan covering a reproducible first result, metered API cost transparency, a dated competitor matrix, and a 14-day gh api traffic baseline protocol.python legends_github.py social-preview --repo OWNER/REPO --image <path> [--verify] --output <json> — 1280x640 Social Preview Preparation & GraphQL Pixel Verification: Validates local 1280x640 social preview cards (including optional local rendering via github/scripts/render_social_preview.py and render_banner.py with a supplied font) and prepares host browser upload instructions. Running with --verify queries GitHub GraphQL and compares the served Open Graph image's dimensions and decoded pixels against the local file.python legends_github.py release | legal | community | empire --path <repo> — Release, Legal, Community & Multi-Repo Empire Governance: Audits and prepares CHANGELOG.md, semver tags, and draft or published GitHub releases (--create-release, --publish); inventories LICENSE, SECURITY.md, CITATION.cff, and upstream attributions without inventing legal claims; scaffolds CONTRIBUTING.md, CODE_OF_CONDUCT.md, SUPPORT.md, and issue forms; and aligns multi-repository portfolio presentation via empire.
Raw Frontier LLM vs. legends-github Execution Matrix
- GitHub Topic & Keyword Selection: Raw LLM (Guesses keywords from file names and stuffs build tools (vite, webpack, eslint) or internal skill pins into GitHub's 20-topic limit.) vs. Module (Imports live DataForSEO keyword overview and SERP JSON via research and seo, ranking terms by search volume and CPC while stripping build-tool noise.) — Outputs receipt.json with reported_cost_usd, SERP position checks (github_in_serp), and validated gh repo edit metadata plans.
- README Upgrades & Custom Layout Safety: Raw LLM (Rewrites the entire README from a generic boilerplate template, destroying custom HTML banners, video embeds, and curated sections.) vs. Module (readme_repo.py runs in preserve-existing mode whenever a README exists, scoring agent-first and traditional sections without clobbering existing prose.) — Generates non-destructive diagnostic reports in --artifacts-dir; local file rewrites occur only when --write is explicitly authorized.
- Offline vs. Live Evidence Accounting: Raw LLM (Conflates API authentication errors or offline runs with missing repository files, producing false-negative audit scores.) vs. Module (Classifies every check in FINDINGS.json as observed, missing, unavailable, or not_applicable, and blocks remote mutation flags when --offline is set.) — Exit code 2 immediately rejects --apply, --create-release, or --publish when combined with --offline.
- Social Preview Open Graph Integrity: Raw LLM (Assumes a browser file-input click updated the repo card without checking image dimensions or CDN propagation.) vs. Module (social-preview --verify fetches the live Open Graph image via GitHub GraphQL and compares decoded pixels and 1280x640 geometry against the local PNG.) — Writes a verified JSON receipt confirming exact dimensional and pixel parity between local artwork and GitHub's served OG asset.
Explicit Safety Boundaries & Exclusions
Operator FAQ
- Will legends-github readme overwrite my custom README layout or video embeds?
- No. When a repository already has a README.md, readme_repo.py runs in preserve-existing mode, preserving existing content, HTML embeds, badges, and section order verbatim while outputting diagnostic scoring so your coding agent can make surgical edits without clobbering your layout.
- Do I need DataForSEO credits to run a repository audit or metadata check?
- No. All 13 workflows run locally and offline for free (--offline). Live DataForSEO keyword and SERP collection (research --execute) is strictly opt-in, typically costs $0.014 to $0.03 per bounded batch, and enforces explicit cost ceilings (--confirm-cost-usd).
- How does social-preview --verify prevent stale or broken Open Graph cards?
- After the agent uploads your 1280x640 PNG through the host's authenticated browser tool, running social-preview --repo OWNER/REPO --image <path> --verify queries GitHub GraphQL for the live Open Graph image URL, downloads the served asset, and verifies that its dimensions (1280x640) and decoded pixels match your local file.
All 19 CTO Legends Packages (1 Router + 18 Modules)
cto-legends (v0.2.5) — Single-skill Python CLI router and isolated environment manager that resolves 18 SHA-256-pinned modules on demand without MCP startup bloat.legends-empire (v0.3.2) — SHA-256 Markdown knowledge foundation with recoverable NTFS and POSIX transactions, .raw/ evidence quarantine, and read-only vault stewardship.legends-hetzner (v0.1.3) — Hetzner Cloud CLI toolkit with Cost-Optimized CX/CAX stock radar, Fractional CTO sizing, SHA-256 server plans, 10-check preflight, and VPS sniping.legends-coolify (v0.2.1) — Read-only Coolify PaaS CLI for self-hosted app inventory, secret-free env key inspection, backup schedule audits, deployment history, and runbooks.legends-cloudflare (v0.1.1) — Zero-dependency Cloudflare DNS CLI enforcing SHA-256 preview-first single-record upserts, exact-ID deletes, setting preservation, and API readback.legends-astro (v0.2.1) — Astro v7 migration CLI that extracts HTML and WordPress source contracts, scaffolds Content Layer collections, and verifies dist/ build parity.legends-gohighlevel (v0.3.0) — Python 3.11+ GoHighLevel CLI for API v2 CRM, Workflows v3, Agent Studio AI, and 5-layer agency RBAC/1.05x rebilling with SHA-256 preview and readback.legends-geogrid (v0.2.2) — Circular-lattice Google Maps rank tracker, GBP name-stuffing audit workbench, and 18-page vector PDF strategy studio for coding agents.legends-dataforseo (v0.1.6) — Zero-dependency Python API and CLI for DataForSEO v3 SERP, Maps, GBP, and keyword research with offline previews and evidence banking.legends-firecrawl (v0.3.2) — Agent-first CLI wrapper (lfc and lax) for official Firecrawl web extraction and Alexandria queries with full local JSON evidence banking.legends-github (v0.2.1) — Deterministic Python CLI for GitHub repository audits, DataForSEO keyword and SERP demand, 20-topic synthesis, non-destructive READMEs, and OG checks.legends-grant (v0.3.0) — Standard-library Python CLI for 56-jurisdiction US grant discovery, SQLite evidence banking, qualification checks, and proposal verification.legends-jev (v0.2.1) — Zero-dependency Python CLI for TypeSafe Jev 1.14 optical recognition (OCR), storefront signage checks, pixel bounding boxes, and typed UI decisions.legends-obs (v0.1.2) — Guarded Windows OBS Studio CLI over WebSocket v5 for hardware encoder planning, pre-mutation rollback snapshots, and FFprobe-verified recording canaries.legends-captions (v0.1.1) — Deterministic video caption QA and ASS rendering CLI with contextual ASR repair, NeMo Forced Aligner word timing, spoken acronym locks, and proof frames.legends-yt-dlp (v0.1.2) — Paced yt-dlp orchestration CLI with SHA-256 binary verification, channel item ledgers, opt-in Mullvad Lockdown guards, and Parakeet/NFA word-level search.legends-stable-audio-3 (v0.1.3) — Hardware-aware Stable Audio 3 CLI for VRAM-calibrated local Medium batches, guarded Large REST jobs, cue-trimmed streaming mixes, and float WAV mastering.legends-hyperyap (v0.1.1) — Offline desktop dictation runtime running INT8 ONNX NVIDIA Parakeet TDT 0.6B v2 locally with CUDA-first inference, active-window paste, and terminal hooks.legends-ambient-intelligence (v0.1.1) — Passive audio pipeline CLI for SHA-256 deduplicated USB recorder ingest, offline Whisper/NeMo Parakeet ASR, rollover recovery, and vault distillation.