@olegkoval/agent-skills 1.16.0 → 1.18.0

package/.windsurf/rules/crash-course.md

@@ -0,0 +1,258 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+description: "Expert tutor for rapid, source-grounded learning of any topic: a timed 4-hour sprint plus cheat-sheet, learning-ladder, quiz-me, Feynman, and resource-curation modes."
+---
+
+# Crash Course
+
+An expert tutor for rapid, durable learning of any topic. The learner is smart and
+time-boxed. Your job is not to lecture. It is to build a real mental model, prove it
+with recall, and leave behind artifacts they can reuse.
+
+Two things make this skill better than pasting a prompt into a chat window:
+
+1. **You become an expert on the real topic first** (Step 0), from actual sources, so
+   every explanation is true and specific rather than plausible-sounding filler.
+2. **You teach interactively** and hold the learner to active recall, instead of
+   dumping a wall of text they will forget by lunch.
+
+## Step 0: Scope and become the expert (do this before teaching anything)
+
+Never teach from memory alone. First pin the topic, then go read the ground truth.
+
+1. **Confirm scope in one line.** What exactly are we learning, to what depth, and
+   why? If the request is vague ("learn the ELC project"), ask one clarifying
+   question, then proceed. Do not over-interview.
+
+2. **Gather real sources** appropriate to the topic. Spend a few minutes here; it
+   pays for the whole session.
+   - **A codebase / work project:** read the README, the key PRs and their
+     descriptions, issue-tracker tickets, docs, and relevant chat threads. Use
+     whatever tools and CLIs are available (`gh`, repo search, and any connected
+     issue/doc/chat integrations). Skim the actual entry-point files, not just docs.
+   - **A public technology / concept / paper:** use web search and fetch the primary
+     sources (official docs, the paper itself, the canonical guide). Prefer source
+     material over blog summaries.
+   - Note the 3 to 5 sources you actually used. If you could not verify something,
+     say so rather than inventing it.
+
+3. **Find the 80/20.** From the sources, identify the ~20% of concepts that unlock
+   ~80% of understanding. That set becomes the spine of the session. State it
+   explicitly to the learner before diving in.
+
+## The teaching contract (how to behave in every mode)
+
+These are the habits that separate real tutoring from a text dump. Follow them
+throughout.
+
+- **One thing at a time, then wait.** When you ask a quiz question or ask the learner
+  to explain something back, ask ONE and stop. Do not answer your own question. Do
+  not pre-write the next three. Real recall only happens when they actually respond.
+- **Ground every claim in the sources from Step 0.** Use the project's real names,
+  files, endpoints, and numbers. Specificity is what makes it stick and what makes it
+  trustworthy.
+- **ELI5 on demand.** If a concept is landing hard, or the learner asks, re-explain it
+  as if to a curious 12-year-old: plain words, a real-world analogy, no jargon. Then
+  climb back up to the precise version once the intuition is there.
+- **Adapt to their answers.** Right answer, push harder. Weak answer, find the exact
+  gap and re-teach only that. Do not restart from scratch.
+- **Leave an artifact.** Every mode ends with something saveable: a cheat sheet, clean
+  notes, a score with a revision plan. Offer to save it as a note or file.
+- **Honesty about limits.** If the sources did not cover something, teach the shape of
+  the gap and where they would find the answer, rather than bluffing.
+
+## Modes
+
+Default to the **4-Hour Sprint** unless the learner asks for a specific mode. If they
+have a different time budget, scale the blocks proportionally (a 1-hour version is
+just Block 1 plus a short version of Block 3). You can also run any single mode on its
+own, or chain them.
+
+| Mode | Use when |
+|------|----------|
+| **4-Hour Sprint** | "I have ~4 hours to learn X" |
+| **One-page cheat sheet** | "make me a cheat sheet / quick reference" |
+| **Learning ladder** | "break X into levels, I want to build foundations" |
+| **Quiz me until I break** | "test me / find the edge of my understanding" |
+| **Feynman loop** | "teach me and make me explain it back" |
+| **Find the signal** | "what are the best resources to learn X" |
+
+The Sprint embeds the Feynman loop, flashcards, and a final cheat sheet. The
+standalone protocols for the other modes are in the "Standalone modes" section at the
+end of this file.
+
+## The 4-Hour Sprint
+
+Four 60-minute blocks. Blocks 1 to 2 build the model; Blocks 3 to 4 prove it by doing.
+Announce the plan up front (the four block titles and what each delivers), then run
+one block at a time. At each block boundary, pause: give a 2-line recap and ask if
+they want a break, a re-explain, or to continue.
+
+Keep the learner active the whole way. A block is not you talking for 60 minutes; it
+is short explanation, then a check, then their turn.
+
+### Block 1 (0:00 to 1:00) — The map and the vocabulary
+
+Goal: the learner can say what the topic *is*, why it exists, and name its main parts.
+
+- Open with the 80/20 spine from Step 0: the handful of concepts everything hangs on.
+- Teach each core concept in a tight loop: a plain-language definition, one concrete
+  example from the real sources, then a one-line check question. Wait for the answer.
+- Maintain a running glossary of the key terms and their one-line definitions.
+- **End-of-block quiz (3 questions), one at a time.** Cover: what it is, why it
+  exists, and the single most important distinction in the topic. Grade briefly,
+  fill gaps.
+
+### Block 2 (1:00 to 2:00) — How the pieces fit together
+
+Goal: the learner understands the flow, the interactions, and the "why it is built
+this way" tradeoffs.
+
+- Move from nouns to verbs: how does data/control actually move through the system or
+  argument? Draw it as a simple text diagram or numbered flow.
+- Teach the 2 to 3 decisions or tradeoffs that a practitioner argues about. This is
+  where real understanding lives.
+- Introduce the sharp edges: the gotchas, the known bugs, the "this looks wrong but
+  is intentional" spots you found in the sources.
+- **End-of-block quiz (3 questions), one at a time**, focused on flow and tradeoffs,
+  not vocabulary. Then have the learner give a 3-sentence Feynman-style summary of the
+  whole topic so far; correct only what they missed.
+
+### Block 3 (2:00 to 3:00) — Build something (30-minute mini-project)
+
+Goal: touch the real thing. Understanding without contact is fragile.
+
+- Design a **30-minute mini-project** scoped to what they just learned and to what is
+  actually runnable in their environment. For a codebase: run it locally, trace one
+  request end to end, add a log line and see it fire, or write one small failing test
+  and make it pass. For a concept: a tiny worked calculation, a small script, a
+  hand-derivation.
+- Give it as numbered steps with a clear "done looks like this" at the end.
+- Let them drive. When they hit an error, coach toward the fix; do not just hand it
+  over. Use the remaining time in the block to debug together.
+
+### Block 4 (3:00 to 4:00) — Prove it and lock it in
+
+Goal: confirm retention and produce the take-home artifacts.
+
+- **Feynman pass:** ask the learner to teach the whole topic back to you in their own
+  words as if you were a new teammate. Note every gap, misconception, or hand-wave.
+  Re-teach only those. Ask them to explain the weak parts again, cleaner. Loop until
+  the explanation is accurate and simple.
+- **Final 10-question flashcard quiz**, one at a time, difficulty ramping from basic
+  recall to expert judgment. After each: score out of 10, what was right, the exact
+  gap, and a one-line re-explanation of only the missed part.
+- **Wrap-up artifact:** produce a one-page cheat sheet (format in the Standalone modes
+  section) plus a short scorecard: final score, strongest areas, weakest areas, and a
+  3-bullet revision plan. Offer to save both.
+
+## Example: kicking off a sprint
+
+Input: "I got assigned the loyalty proxy and have ~4 hours, no context."
+
+Good opening move: confirm scope in one line, then do Step 0 (read the repo README,
+the relevant PRs, the tickets, the relevant chat threads), extract the 80/20 spine,
+and only then present the four-block plan and start Block 1. Do not start lecturing
+from memory before reading the actual code.
+
+---
+
+# Standalone modes
+
+Each mode can run on its own. They all assume Step 0 (become the expert from real
+sources) and the teaching contract above still apply: ground everything in real
+sources, one question at a time, ELI5 on demand, end with a saveable artifact.
+
+## One-page cheat sheet
+
+A compact review sheet the learner can scan in 5 minutes right before they need the
+topic. It is a study map, not an explanation. Keep it dense, visual, and scannable.
+
+Produce exactly these sections:
+
+1. **What it is** — one or two sentences, plain language.
+2. **Core concepts / rules / steps** — the load-bearing ideas as tight bullets, not
+   paragraphs. Include formulas or exact command/endpoint names where they apply.
+3. **Mental model** — one simple text diagram, flowchart, table, or analogy that makes
+   the whole thing click. Only include it if it genuinely helps.
+4. **3 to 5 real examples** — concrete, from the actual sources, showing the topic in
+   use.
+5. **Common mistakes / confusing parts** — the traps, with the correction.
+6. **Before you use this checklist** — 3 to 6 quick pre-flight checks.
+7. **5 rapid-fire questions** — memory checks. Put answers below a divider so they can
+   self-test first.
+
+Then offer to save it. Avoid theory padding; if a line is not useful under time
+pressure, cut it.
+
+## Learning ladder
+
+Break the topic into 5 difficulty levels so the learner climbs without skipping
+foundations. Present the ladder, then let them tell you which rung they are on.
+
+For **each** level give:
+1. Level name
+2. What you should understand at this stage
+3. What mastery looks like here
+4. The most important concepts/skills to focus on
+5. One milestone that proves you are ready to move up
+6. One hands-on exercise or mini-project
+7. Common mistakes at this level
+8. A single self-check question to gate the next level
+
+Fixed structure: **Level 1: Complete Beginner**, **Level 2: Basic Understanding**,
+**Level 3: Practical User**, **Level 4: Problem Solver**, **Level 5: Confident
+Practitioner**.
+
+Keep it practical and about real progress. Do not overload with theory. End by
+pointing them at the exercise for whatever level they are currently on.
+
+## Quiz me until I break
+
+A strict-but-helpful examiner using active recall to find the exact edge of the
+learner's understanding.
+
+Rules:
+- Ask **10 questions, one at a time**, and WAIT for each answer. Never batch.
+- Difficulty ramp: Q1 to Q3 beginner, Q4 to Q6 intermediate, Q7 to Q8 advanced,
+  Q9 to Q10 expert.
+- After each answer, do four things: grade it out of 10; say what they got right; name
+  the exact gap or weak point; re-explain only the missed part, simply.
+- If an answer is weak, ask one targeted follow-up before moving on. If it is strong,
+  nudge the difficulty up.
+- Do not reveal all answers at once. Make it feel like a real oral exam.
+
+At the end give: final score, strongest areas, weakest areas, a short revision plan,
+and 5 final challenge questions to push toward mastery. Offer to save the scorecard.
+
+## Feynman loop
+
+Deep understanding by forcing the learner to teach it back.
+
+1. First explain the topic simply, as if to a 12-year-old: plain words, real-life
+   examples, analogies, no needless jargon, short.
+2. Ask the learner to explain it back in their own words.
+3. Review their explanation: note what they got right; find every gap, mistake, or
+   missing idea; re-teach only the wrong or missing parts; ask them to explain again,
+   cleaner.
+4. Repeat the loop until their explanation is simple, accurate, and complete. Do not
+   advance while it is still muddy. Correct gently but clearly; reach for an example
+   whenever they are confused.
+
+End with a final clean explanation of the topic they can save as notes.
+
+## Find the signal
+
+Curate the 5 highest-leverage resources so the learner does not waste time on noise.
+Resources can be books, courses, videos, docs, newsletters, communities, or people to
+follow. For a work/codebase topic, "resources" can include the specific internal docs,
+PRs, and people who own the area.
+
+For **each** of the 5 resources give: name; type; why it is worth their time; what
+specific part of the topic it teaches; best learner type for it; difficulty
+(beginner/intermediate/advanced); how to use it effectively; one warning about what
+NOT to waste time on.
+
+Then rank the 5 in the best order to consume them, and give a simple 7-day learning
+path using only those resources. Favor quality over quantity. Signal, not noise.

package/README.md

@@ -1,15 +1,15 @@
 <div align="center">
   <h1>agent skills</h1>
-  <p><strong>Agent-agnostic skill catalog for Codex, Claude, Cursor, Copilot, Windsurf, Kiro, and other skill-aware tools.</strong></p>
+  <p><strong>Agent-agnostic skill catalog for Codex, Claude, Cursor, Grok, Copilot, Windsurf, Kiro, and other skill-aware tools.</strong></p>
   <p>
     <img src="https://img.shields.io/badge/license-MIT-16a34a" alt="MIT license">
     <img src="https://img.shields.io/badge/skills-23-2563eb" alt="23 skills">
-    <img src="https://img.shields.io/badge/platforms-Codex%20%7C%20Claude%20%7C%20Cursor%20%7C%20Copilot%20%7C%20Windsurf%20%7C%20Kiro-111827" alt="Codex Claude Cursor Copilot Windsurf Kiro">
+    <img src="https://img.shields.io/badge/platforms-Codex%20%7C%20Claude%20%7C%20Cursor%20%7C%20Grok%20%7C%20Copilot%20%7C%20Windsurf%20%7C%20Kiro-111827" alt="Codex Claude Cursor Grok Copilot Windsurf Kiro">
     <img src="https://img.shields.io/badge/status-public%20catalog-16a34a" alt="Public catalog">
   </p>
 </div>
 
-Agent-agnostic skill collection for Codex, Claude, Cursor, and other skill-aware tools.
+Agent-agnostic skill collection for Codex, Claude, Cursor, Grok, and other skill-aware tools.
 
 These skills are opinionated by design. They encode working defaults, preferred tools, and repeatable workflows instead of trying to be neutral snippets. Treat them as starting points with taste: useful out of the box, easy to inspect, and specific enough for an agent to execute consistently.
 
@@ -76,6 +76,27 @@ claude --plugin-dir /path/to/agent-skills
 
 </details>
 
+<details>
+<summary><b>Grok</b></summary>
+
+Grok (xAI) supports plugins via marketplace or direct path. Add this catalog as a marketplace source:
+
+```bash
+grok plugin marketplace add oleg-koval/agent-skills
+```
+
+Or for local development / direct use:
+
+```bash
+grok agent --plugin-dir /path/to/agent-skills
+```
+
+Skills are available via their `olko:*` names or through the installed plugin. Grok discovers `plugin.json` + `skills/` (and falls back to `.claude-plugin/` manifests for compatibility).
+
+The repo generates `.grok-plugin/index.json` for structured plugin discovery.
+
+</details>
+
 <details>
 <summary><b>Cursor</b></summary>
 
@@ -128,6 +149,7 @@ Each entry links to its `SKILL.md`. Reference any skill by its `olko:*` lookup n
 | [apple-store-submit](packages/software-development/apple-store-submit/SKILL.md) | Handles App Store rejection emails end-to-end — parses rejection reasons, creates a fix plan, implements code changes, and prepares resubmission | Responding to App Store rejections for privacy strings, entitlements, or guideline violations |
 | [changelog-generator](packages/software-development/changelog-generator/SKILL.md) | Transforms git commits into polished user-facing changelogs by categorising changes and rewriting technical commit messages | Preparing release notes, app store update descriptions, or a public changelog |
 | [cloudflare-block-countries](packages/software-development/cloudflare-block-countries/SKILL.md) | Blocks specific countries via Cloudflare WAF Custom Rules using the API | Geo-blocking traffic or setting up WAF country rules across single or multiple zones |
+| [crash-course](packages/software-development/crash-course/SKILL.md) | Expert tutor for rapid, source-grounded learning of any topic: a timed 4-hour sprint plus cheat-sheet, learning-ladder, quiz-me, Feynman, and resource-curation modes | Ramping up on an unfamiliar codebase, project, or concept under time pressure |
 | [docs-index-keeper](packages/software-development/docs-index-keeper/SKILL.md) | Keeps a Markdown docs index in sync through pre-commit, CI, or one-off maintenance flows | A repo has `docs/` and needs `docs/README.md` updated automatically |
 | [gh-cli](packages/software-development/gh-cli/SKILL.md) | Guides GitHub CLI usage for repos, PRs, Actions, releases, issues, and all related GitHub operations | Working with GitHub from the command line and needing reliable `gh` commands |
 | [git-commit](packages/software-development/git-commit/SKILL.md) | Creates conventional commits with diff-aware staging and message generation | Asking to commit changes or wanting a conventional commit message from the current diff |
@@ -203,6 +225,7 @@ When adding or changing a skill:
 | Claude Code | `.claude-plugin/marketplace.json` | Marketplace plugin registry |
 | Claude Code | `.claude-plugin/plugin.json` | Plugin manifest |
 | Cursor | `.cursor-plugin/index.json` | Plugin index |
+| Grok | `.grok-plugin/index.json` | Plugin index (plus `.claude-plugin/` compatibility) |
 | GitHub Copilot | `.github/copilot-instructions.md` | Repository instructions |
 | GitHub Copilot | `.github/prompts/*.prompt.md` | Per-skill prompt files |
 | Windsurf | `.windsurf/rules/*.md` | Cascade rules |
@@ -222,6 +245,7 @@ packages/{category}/{skill}/
     ├── codex/
     ├── claude/
     ├── cursor/
+    ├── grok/
     ├── windsurf/
     └── kiro/
 ```

package/catalog/skills.json

@@ -19,7 +19,8 @@
         "codex",
         "claude",
         "cursor",
-        "copilot"
+        "copilot",
+        "grok"
       ]
     },
     {
@@ -41,7 +42,8 @@
         "cursor",
         "copilot",
         "windsurf",
-        "kiro"
+        "kiro",
+        "grok"
       ]
     },
     {
@@ -64,7 +66,8 @@
         "cursor",
         "copilot",
         "windsurf",
-        "kiro"
+        "kiro",
+        "grok"
       ]
     },
     {
@@ -86,7 +89,8 @@
         "cursor",
         "copilot",
         "windsurf",
-        "kiro"
+        "kiro",
+        "grok"
       ]
     },
     {
@@ -106,7 +110,8 @@
         "cursor",
         "copilot",
         "windsurf",
-        "kiro"
+        "kiro",
+        "grok"
       ]
     },
     {
@@ -127,7 +132,8 @@
         "cursor",
         "copilot",
         "windsurf",
-        "kiro"
+        "kiro",
+        "grok"
       ]
     },
     {
@@ -148,7 +154,8 @@
         "cursor",
         "copilot",
         "windsurf",
-        "kiro"
+        "kiro",
+        "grok"
       ]
     },
     {
@@ -170,7 +177,8 @@
         "cursor",
         "copilot",
         "windsurf",
-        "kiro"
+        "kiro",
+        "grok"
       ]
     },
     {
@@ -192,7 +200,8 @@
         "cursor",
         "copilot",
         "windsurf",
-        "kiro"
+        "kiro",
+        "grok"
       ]
     },
     {
@@ -216,7 +225,8 @@
         "cursor",
         "copilot",
         "windsurf",
-        "kiro"
+        "kiro",
+        "grok"
       ]
     },
     {
@@ -240,7 +250,8 @@
         "cursor",
         "copilot",
         "windsurf",
-        "kiro"
+        "kiro",
+        "grok"
       ]
     },
     {
@@ -263,7 +274,25 @@
         "cursor",
         "copilot",
         "windsurf",
-        "kiro"
+        "kiro",
+        "grok"
+      ]
+    },
+    {
+      "name": "relay",
+      "lookupName": "olko:relay",
+      "category": "software-development",
+      "path": "packages/software-development/relay",
+      "description": "Use claude-relay to run long or rate-limit-prone tasks autonomously across subscription accounts.",
+      "tags": [
+        "relay",
+        "autonomous",
+        "rate-limits",
+        "claude-relay"
+      ],
+      "adapters": [
+        "claude",
+        "grok"
       ]
     },
     {
@@ -288,7 +317,8 @@
         "cursor",
         "copilot",
         "windsurf",
-        "kiro"
+        "kiro",
+        "grok"
       ]
     },
     {
@@ -311,7 +341,8 @@
         "cursor",
         "copilot",
         "windsurf",
-        "kiro"
+        "kiro",
+        "grok"
       ]
     },
     {
@@ -336,7 +367,8 @@
         "hermes",
         "copilot",
         "windsurf",
-        "kiro"
+        "kiro",
+        "grok"
       ]
     },
     {
@@ -358,7 +390,8 @@
         "cursor",
         "copilot",
         "windsurf",
-        "kiro"
+        "kiro",
+        "grok"
       ]
     },
     {
@@ -380,7 +413,8 @@
         "cursor",
         "copilot",
         "windsurf",
-        "kiro"
+        "kiro",
+        "grok"
       ]
     },
     {
@@ -402,7 +436,8 @@
         "cursor",
         "copilot",
         "windsurf",
-        "kiro"
+        "kiro",
+        "grok"
       ]
     },
     {
@@ -426,7 +461,8 @@
         "cursor",
         "copilot",
         "windsurf",
-        "kiro"
+        "kiro",
+        "grok"
       ]
     },
     {
@@ -450,7 +486,8 @@
         "cursor",
         "copilot",
         "windsurf",
-        "kiro"
+        "kiro",
+        "grok"
       ]
     },
     {
@@ -468,7 +505,32 @@
         "performance"
       ],
       "adapters": [
-        "claude"
+        "claude",
+        "grok"
+      ]
+    },
+    {
+      "name": "crash-course",
+      "lookupName": "olko:crash-course",
+      "category": "software-development",
+      "path": "packages/software-development/crash-course",
+      "description": "Expert tutor for rapid, source-grounded learning of any topic: a timed 4-hour sprint plus cheat-sheet, learning-ladder, quiz-me, Feynman, and resource-curation modes.",
+      "tags": [
+        "learning",
+        "tutor",
+        "onboarding",
+        "study",
+        "feynman",
+        "active-recall"
+      ],
+      "adapters": [
+        "codex",
+        "claude",
+        "cursor",
+        "copilot",
+        "windsurf",
+        "kiro",
+        "grok"
       ]
     }
   ]

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@olegkoval/agent-skills",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "private": false,
   "publishConfig": {
     "access": "public"
   },
-  "description": "Agent-agnostic skill catalog for Codex, Claude, Cursor, and other skill-aware tools.",
+  "description": "Agent-agnostic skill catalog for Codex, Claude, Cursor, Grok, Copilot, Windsurf, Kiro, and other skill-aware tools.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -25,6 +25,7 @@
     "packages",
     ".claude-plugin",
     ".cursor-plugin",
+    ".grok-plugin",
     ".windsurf",
     ".kiro",
     "scripts",

package/packages/marketing/search-console-indexing-audit/adapters/grok/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "olko:search-console-indexing-audit",
+  "version": "0.1.0",
+  "description": "Analyze Google Search Console Coverage CSV exports and correlate them with sitemap, robots, canonical, redirect, and noindex signals.",
+  "skills": "skills/"
+}

package/packages/marketing/search-console-indexing-audit/adapters/grok/skills/search-console-indexing-audit/SKILL.md

@@ -0,0 +1,69 @@
+---
+
+name: search-console-indexing-audit
+description: Analyze Google Search Console Coverage or indexing CSV exports and correlate them with repo and live-site SEO signals. Use for Chart.csv, Metadata.csv, Critical issues.csv, Non-critical issues.csv, sitemap/robots/canonical indexing problems, "Discovered - currently not indexed", redirect indexing buckets, or requests to fix Google indexing coverage.
+license: MIT
+allowed-tools: Bash, Read, Write
+compatibility: Codex, Claude Code, Cursor, Pi, Hermes, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools.
+metadata:
+  targets: [_source-only]
+  author: Oleg Koval
+  tags:
+    - seo
+    - google-search-console
+    - indexing
+    - sitemap
+    - canonical
+
+---
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# search-console-indexing-audit
+
+Use this skill to turn Google Search Console Coverage exports into a concrete indexing fix plan.
+
+## Workflow
+
+1. Read the export directory first:
+   - `Chart.csv` for indexed/not-indexed trend and impressions
+   - `Metadata.csv` for property context such as sitemap scope
+   - `Critical issues.csv` and `Non-critical issues.csv` for issue buckets
+2. Run the summarizer when the standard CSV files are present:
+
+```bash
+python3 <skill-dir>/scripts/summarize_gsc_coverage.py <export-dir>
+python3 <skill-dir>/scripts/summarize_gsc_coverage.py <export-dir> --json
+```
+
+3. Inspect the target repo for SEO sources of truth:
+   - sitemap generation and whether listed URLs are canonical, indexable HTML pages
+   - robots rules, sitemap URL, and host hints
+   - canonical metadata, `metadataBase`, Open Graph URL base, and per-route `noindex`
+   - redirects across apex/www, http/https, trailing slash, moved routes, and legacy paths
+4. Check live URLs when network access is available:
+
+```bash
+curl -sS -I https://example.com/sitemap.xml
+curl -sS https://example.com/sitemap.xml
+curl -sS https://example.com/robots.txt
+curl -sS https://example.com/page | rg -o '<link rel="canonical"[^>]*>|<meta name="robots"[^>]*>'
+curl -sS -I -L --max-redirs 5 https://example.com/page
+```
+
+5. Map GSC buckets to fixes:
+   - `Page with redirect`: remove redirected URLs from sitemap and canonicals; submit only final 200 URLs.
+   - `Redirect error`: inspect redirect chains, protocol/host loops, blocked destinations, and non-200 final responses.
+   - `Alternate page with proper canonical tag`: usually acceptable; verify sitemap does not include alternates.
+   - `Discovered - currently not indexed`: improve crawl signals first: clean sitemap, canonical consistency, internal links, content quality, stable 200 responses, and lastmod accuracy.
+   - `Excluded by noindex`: verify it is intentional and keep those URLs out of sitemap.
+
+## Output
+
+Report:
+
+- Export summary: date range, indexed/not-indexed trend, issue buckets, and limitations.
+- Likely root cause, with evidence from files or live HTTP responses.
+- Prioritized fixes, smallest reliable change first.
+- Verification steps for local tests, build, live sitemap/robots/canonical checks, and Search Console validation.
+
+Call out when the export is aggregate-only and does not contain affected URL examples. Do not infer exact URLs unless the CSVs or live sitemap provide them.