docs: document the v1 API + add /api/v1/index.json discovery manifest

Two changes that make the v1 surface usable without first parsing skills.json:

1. README 'Public API (v1)' section lists every endpoint, the URL pattern (with {namespace}/{slug} placeholders), the stability contract, and copy-pasteable embed examples for both inline SVG and shields.io endpoint mode. Forks get the URL pattern unchanged: only the host swaps.

2. /api/v1/index.json is now generated alongside the rest of the tree by build-api-v1 (and write_api_v1). It carries the schema version, URL templates, and the current (namespace, slug) list - a single fetch a third-party consumer can use to learn the entire API surface and iterate over current skills without grabbing the heavier index.

Tests: 54 pytest (added two for build_v1_index covering history-on / history-off variants and URL-template shape), ruff clean, markdownlint clean. Real-payload smoke run now writes 18 files (was 17) under api/v1.

Author: DevelopmentCats

README.md

@@ -39,6 +39,49 @@ Stable URLs, no auth required:
 + Schema: `https://coder.github.io/coder-skill-scanner/schema.json` (v1)
 + Per-scan history (JSON): `https://coder.github.io/coder-skill-scanner/history/index.json`
 
+## Public API (v1)
+
+Under `/api/v1/`, every URL is constructible from `(namespace, slug)` alone
+— no lookup against the index is required to render a badge or read a
+single skill. Field names and URL shapes are committed to the `v1`
+stability contract; breaking changes move to a `v2` prefix.
+
+| URL | Shape | Use |
+| --- | --- | --- |
+| `/api/v1/index.json` | discovery manifest: URL templates + current `(ns, slug)` pairs | bootstrap a third-party consumer |
+| `/api/v1/skills.json` | compact index of every skill | listing / cache warmer |
+| `/api/v1/skills/<ns>/<slug>.json` | per-skill detail (reasons, findings, `links` block) | per-skill consumer |
+| `/api/v1/skills/<ns>/<slug>/badge/status.json` | shields.io endpoint payload | `img.shields.io/endpoint?url=...` |
+| `/api/v1/skills/<ns>/<slug>/badge/status.svg` | inline SVG | direct embed |
+| `/api/v1/skills/<ns>/<slug>/badge/score.json` | shields.io endpoint payload | same |
+| `/api/v1/skills/<ns>/<slug>/badge/score.svg` | inline SVG | direct embed |
+| `/api/v1/history.json` | reshape of history with absolute report URLs | history consumer |
+
+Two badges per skill:
+
++ **`status`** — the categorical scan outcome (`clean`, `suspicious`,
+  `malicious`, `unknown`). Colour follows the verdict 1:1.
++ **`score`** — the numeric SkillSpector risk score (`0/100` … `100/100`).
+  Colour is banded at the same 21 / 51 / 81 cutoffs the verdict policy
+  uses.
+
+Embed a status badge in a README:
+
+```markdown
+![skill scan](https://coder.github.io/coder-skill-scanner/api/v1/skills/coder/setup/badge/status.svg)
+```
+
+Or via shields.io if you want their renderer:
+
+```markdown
+![skill scan](https://img.shields.io/endpoint?url=https://coder.github.io/coder-skill-scanner/api/v1/skills/coder/setup/badge/status.json)
+```
+
+For a fork, swap the host: `https://<owner>.github.io/<repo>/api/v1/...`.
+The scanner derives the public base URL from `$GITHUB_REPOSITORY` at
+publish time, so the same URL pattern is correct for any fork without
+config changes.
+
 ## Running locally
 
 Requires Python 3.12+, Node 22+ (via `mise`), pnpm, and `git`.

scanner/api.py

@@ -2,6 +2,14 @@
 
 The v1 contract:
 
+- ``api/v1/index.json``                 Discovery manifest. Lists the URL
+                                        templates (with ``{namespace}`` and
+                                        ``{slug}`` placeholders) needed to
+                                        address every other endpoint, plus the
+                                        current ``(namespace, slug)`` pairs.
+                                        Bootstrap entry point for third-party
+                                        consumers - no other fetch required to
+                                        learn the URL conventions.
 - ``api/v1/skills.json``                Compact index of every skill in the most
                                         recent scan: namespace, slug, verdict,
                                         risk_score, source_repo, source_sha,
@@ -176,6 +184,44 @@ def build_history_index(
     }
 
 
+def build_v1_index(
+    report: dict[str, Any],
+    *,
+    public_base_url: str,
+    has_history: bool,
+    generated_at: str | None = None,
+) -> dict[str, Any]:
+    """Build the ``api/v1/index.json`` discovery manifest.
+
+    The manifest lists the URL templates a third-party consumer needs to
+    address every endpoint without first parsing ``skills.json``, plus the
+    current ``(namespace, slug)`` pairs so a programmatic consumer can iterate
+    without a second fetch. Field shapes are part of the v1 contract.
+    """
+    root = public_base_url.rstrip("/")
+    api_root = f"{root}/api/v1"
+    skills = sorted(
+        ({"namespace": s["namespace"], "slug": s["slug"]} for s in report.get("skills", [])),
+        key=lambda s: (s["namespace"], s["slug"]),
+    )
+    urls = {
+        "skills_index": f"{api_root}/skills.json",
+        "skill_detail": f"{api_root}/skills/{{namespace}}/{{slug}}.json",
+        "status_badge_json": f"{api_root}/skills/{{namespace}}/{{slug}}/badge/status.json",
+        "status_badge_svg": f"{api_root}/skills/{{namespace}}/{{slug}}/badge/status.svg",
+        "score_badge_json": f"{api_root}/skills/{{namespace}}/{{slug}}/badge/score.json",
+        "score_badge_svg": f"{api_root}/skills/{{namespace}}/{{slug}}/badge/score.svg",
+    }
+    if has_history:
+        urls["history"] = f"{api_root}/history.json"
+    return {
+        "schema_version": API_SCHEMA_VERSION,
+        "generated_at": generated_at or report.get("generated_at", ""),
+        "urls": urls,
+        "skills": skills,
+    }
+
+
 def write_api_v1(
     report: dict[str, Any],
     *,
@@ -195,6 +241,15 @@ def write_api_v1(
     skills_index_path.write_text(json.dumps(skills_index, indent=2) + "\n", encoding="utf-8")
     written.append(skills_index_path)
 
+    discovery = build_v1_index(
+        report,
+        public_base_url=public_base_url,
+        has_history=history_manifest is not None,
+    )
+    discovery_path = output_dir / "index.json"
+    discovery_path.write_text(json.dumps(discovery, indent=2) + "\n", encoding="utf-8")
+    written.append(discovery_path)
+
     for skill in report.get("skills", []):
         ns = _check_safe_segment("namespace", skill["namespace"])
         slug = _check_safe_segment("slug", skill["slug"])

tests/test_api.py

@@ -133,8 +133,9 @@ def test_write_api_v1_writes_full_tree(tmp_path: Path):
         history_manifest={"entries": []},
     )
 
-    # 1 (skills.json) + 3 skills * (1 detail + 4 badge files) + 1 (history.json) = 17.
-    assert len(written) == 17
+    # 1 (skills.json) + 1 (index.json) + 3 skills * (1 detail + 4 badge files) +
+    # 1 (history.json) = 18.
+    assert len(written) == 18
 
     # Index validates as parseable JSON, has the right schema_version.
     idx = json.loads((tmp_path / "skills.json").read_text())
@@ -167,8 +168,8 @@ def test_write_api_v1_skips_history_when_not_provided(tmp_path: Path):
     written = api.write_api_v1(
         report, output_dir=tmp_path, public_base_url="https://example.com/scanner"
     )
-    # 1 (skills.json) + 1 * (1 detail + 4 badge files) = 6
-    assert len(written) == 6
+    # 1 (skills.json) + 1 (index.json) + 1 * (1 detail + 4 badge files) = 7
+    assert len(written) == 7
     assert not (tmp_path / "history.json").exists()
 
 
@@ -188,3 +189,49 @@ def test_write_api_v1_rejects_path_traversal_slug(tmp_path: Path):
         api.write_api_v1(
             report, output_dir=tmp_path, public_base_url="https://example.com/x"
         )
+
+
+def test_build_v1_index_lists_url_templates_and_skills():
+    """The discovery manifest at /api/v1/index.json must let a third-party
+    consumer address every endpoint without first fetching skills.json."""
+    report = _report(
+        [
+            _skill("templates"),
+            _skill("modules"),
+            _skill("setup", verdict="malicious", risk=100),
+        ]
+    )
+    manifest = api.build_v1_index(
+        report,
+        public_base_url="https://example.com/scanner",
+        has_history=True,
+    )
+
+    assert manifest["schema_version"] == 1
+    # URL templates use {namespace} and {slug} placeholders, anchored at the
+    # caller-supplied base; consumers can substitute without knowing layout.
+    urls = manifest["urls"]
+    assert urls["skills_index"] == "https://example.com/scanner/api/v1/skills.json"
+    assert urls["skill_detail"].endswith("/api/v1/skills/{namespace}/{slug}.json")
+    assert urls["status_badge_svg"].endswith(
+        "/api/v1/skills/{namespace}/{slug}/badge/status.svg"
+    )
+    assert urls["score_badge_json"].endswith(
+        "/api/v1/skills/{namespace}/{slug}/badge/score.json"
+    )
+    # history URL is included only when a history manifest was supplied.
+    assert urls["history"].endswith("/api/v1/history.json")
+    # Skill list is sorted and contains only namespace/slug pairs.
+    assert manifest["skills"] == [
+        {"namespace": "coder", "slug": "modules"},
+        {"namespace": "coder", "slug": "setup"},
+        {"namespace": "coder", "slug": "templates"},
+    ]
+
+
+def test_build_v1_index_omits_history_url_when_no_history():
+    report = _report([_skill("modules")])
+    manifest = api.build_v1_index(
+        report, public_base_url="https://example.com/scanner", has_history=False
+    )
+    assert "history" not in manifest["urls"]