feat: M4 polish — pip-resolvable /simple/, llms.txt, catalog.json, md twins

Completes the machine-usability story for tools.culture.dev.

pip-resolvable /simple/:
- `index build` now emits a Cloudflare `_redirects` file mapping each certified
  tool's `/simple/<name>/` (both trailing-slash forms) to its PyPI simple page,
  so `pip install --index-url https://tools.culture.dev/simple/ <tool>` resolves
  a certified tool's real files from PyPI. Only listed tools get a rule → the
  index stays curated; uncertified names 404.
- Dropped the static per-tool `/simple/<name>/` pages: a static asset shadows the
  redirect (Cloudflare applies `_redirects` only after an exact asset miss), so a
  page there would break pip-resolvability. New `render_redirects()` replaces
  `render_project`/`pypi_links`. sync-catalog.sh + catalog-refresh CI distribute
  the file to public/_redirects.

Agent affordances on the site:
- `/llms.txt` — the agent-facing index, built from the catalog.
- `/catalog.json` — the machine-readable catalog as a stable endpoint.
- markdown twins — `/index.md` and `/tools/<name>.md` (append `.md` to any page).
- Footer links the new endpoints.

48 pytest (render_redirects + build assertions updated); astro check 0 errors,
build green (new routes: llms.txt, catalog.json, *.md); lint + rubric +
markdownlint clean. Version 0.5.1 -> 0.6.0; catalog regenerated to match.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LdsNvR24i1fGosuQ9AgtVG

Author: OriNachum

.github/workflows/catalog-refresh.yml

@@ -99,6 +99,7 @@ jobs:
           cp _stage/catalog.json site-astro/src/data/catalog.json
           rm -rf site-astro/public/simple
           cp -r _stage/simple site-astro/public/simple
+          cp _stage/_redirects site-astro/public/_redirects
           rm -rf _siblings _stage
 
       - name: Open a PR if the catalog changed

CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2026-06-22
+
+### Added
+
+- **pip-resolvable `/simple/` (M4).** `index build` now emits a Cloudflare
+  `_redirects` file mapping each certified tool's `/simple/<name>/` to its PyPI
+  simple page, so `pip install --index-url https://tools.culture.dev/simple/
+  <tool>` resolves a certified tool's real files from PyPI. Only listed tools get
+  a rule, so the index stays curated; uncertified names fall through to 404. The
+  static per-tool `/simple/<name>/` pages are gone — a static asset would shadow
+  the redirect (Cloudflare applies `_redirects` only after an exact asset miss).
+  New `render_redirects()` in `culture_tools.index._simple`; `sync-catalog.sh`
+  and the catalog-refresh CI distribute the file to `public/_redirects`.
+- **Agent affordances on the site (M4):** `/llms.txt` (the agent-facing index,
+  built from the catalog), `/catalog.json` (the machine-readable catalog as a
+  stable endpoint), and **markdown twins** — append `.md` to any page
+  (`/index.md`, `/tools/<name>.md`) for raw-markdown versions. Footer links the
+  new endpoints.
+
 ## [0.5.1] - 2026-06-22
 
 ### Added

culture_tools/index/_build.py

@@ -21,11 +21,7 @@
 from culture_tools.index._conformance import Runner, gate
 from culture_tools.index._introspect import introspect
 from culture_tools.index._manifest import Tool, candidates, default_repos_dir
-from culture_tools.index._simple import normalize, pypi_links, render_project, render_root
-
-_SIMPLE_NOTE = (
-    "Distribution files are served by PyPI; tools.culture.dev certifies the AgentFront contract."
-)
+from culture_tools.index._simple import render_redirects, render_root
 
 
 def build(
@@ -58,23 +54,25 @@ def build(
     catalog_path = out_dir / "catalog.json"
     catalog_path.write_text(json.dumps(catalog, indent=2) + "\n", encoding="utf-8")
 
+    # PEP 503 is keyed by the installable (PyPI) name, and so is pip's request
+    # path — so the root listing and the redirect rules both key on tool.pypi.
+    pypi_names = [t.pypi for t in listed_tools]
+
     simple_dir = out_dir / "simple"
     simple_dir.mkdir(parents=True, exist_ok=True)
-    (simple_dir / "index.html").write_text(
-        render_root([t.name for t in listed_tools]), encoding="utf-8"
-    )
-    for tool in listed_tools:
-        project_dir = simple_dir / normalize(tool.name)
-        project_dir.mkdir(parents=True, exist_ok=True)
-        (project_dir / "index.html").write_text(
-            render_project(tool.name, pypi_links(tool.pypi), note=_SIMPLE_NOTE),
-            encoding="utf-8",
-        )
+    (simple_dir / "index.html").write_text(render_root(pypi_names), encoding="utf-8")
+
+    # pip-resolvability: /simple/<name>/ → PyPI, as a Cloudflare _redirects file at
+    # the site root. No static per-tool page is written — a static asset would
+    # shadow the redirect (Cloudflare applies _redirects only after an asset miss).
+    redirects_path = out_dir / "_redirects"
+    redirects_path.write_text(render_redirects(pypi_names), encoding="utf-8")
 
     return {
         "out": str(out_dir),
         "catalog": str(catalog_path),
         "simple": str(simple_dir),
+        "redirects": str(redirects_path),
         "listed": len(entries),
         "excluded": len(excluded),
         "candidates": len(manifest),

culture_tools/index/_simple.py

@@ -1,37 +1,34 @@
-"""Static PEP 503 ``/simple/`` emitter.
+"""Static PEP 503 ``/simple/`` emitter + the pip-resolvability ``_redirects``.
 
 Pure string builders — no I/O, no deps — so they unit-test cleanly. Ported from
-``../auntiepypi``'s index logic (PEP 503 name normalization + the root/project
-HTML), adapted to emit *static* files at build time rather than serve them from a
+``../auntiepypi``'s index logic (PEP 503 name normalization + the root HTML),
+adapted to emit *static* files at build time rather than serve them from a
 running ``http.server``.
 
-v1 does not host wheels: each project page links out to the tool's canonical PyPI
-distribution page. The pip-resolvable ``/simple/<name>/`` → PyPI proxy is a
-deploy-layer concern (a Cloudflare ``_redirects`` rule), handled in M3.
+The index does not host wheels. To make ``/simple/`` **pip-resolvable** without
+hosting files, each certified tool's ``/simple/<name>/`` is a Cloudflare
+``_redirects`` rule pointing at the tool's real PyPI simple page. Only listed
+tools get a rule, so the index stays curated — ``pip install --index-url
+https://tools.culture.dev/simple/ <tool>`` resolves a certified tool's files from
+PyPI, and anything uncertified falls through to 404. There is deliberately **no
+static page** at ``/simple/<name>/``: a static asset would shadow the redirect
+(Cloudflare applies ``_redirects`` only after an exact static-asset miss).
 """
 
 from __future__ import annotations
 
 import html
 import re
-from dataclasses import dataclass
 
 _NORMALIZE_RE = re.compile(r"[-_.]+")
+_PYPI_SIMPLE = "https://pypi.org/simple"
 
 
 def normalize(name: str) -> str:
     """PEP 503 normalized project name: lowercase, runs of ``[-_.]`` → single ``-``."""
     return _NORMALIZE_RE.sub("-", name).lower()
 
 
-@dataclass(frozen=True)
-class DistLink:
-    """One anchor on a project page (a distribution file, or a PyPI pointer)."""
-
-    label: str
-    href: str
-
-
 def render_root(project_names: list[str]) -> str:
     """The ``/simple/index.html`` root: one anchor per project, sorted, normalized."""
     rows = [
@@ -54,37 +51,23 @@ def render_root(project_names: list[str]) -> str:
     )
 
 
-def render_project(name: str, links: list[DistLink], *, note: str = "") -> str:
-    """A ``/simple/<name>/index.html`` page listing distribution anchors."""
-    rows = [
-        f'    <a href="{html.escape(link.href)}">{html.escape(link.label)}</a><br/>'
-        for link in links
-    ]
-    body = "\n".join(rows) if rows else "    <!-- no distributions -->"
-    note_html = f"    <!-- {html.escape(note)} -->\n" if note else ""
-    return (
-        "<!DOCTYPE html>\n"
-        '<html lang="en">\n'
-        "  <head>\n"
-        '    <meta charset="utf-8" />\n'
-        '    <meta name="pypi:repository-version" content="1.0" />\n'
-        f"    <title>Links for {html.escape(name)}</title>\n"
-        "  </head>\n"
-        "  <body>\n"
-        f"    <h1>Links for {html.escape(name)}</h1>\n"
-        f"{note_html}"
-        f"{body}\n"
-        "  </body>\n"
-        "</html>\n"
-    )
-
+def render_redirects(project_names: list[str]) -> str:
+    """The Cloudflare ``_redirects`` file making ``/simple/`` pip-resolvable.
 
-def pypi_links(pypi_name: str) -> list[DistLink]:
-    """v1 project-page links: point at the tool's canonical PyPI home."""
-    return [
-        DistLink(f"{pypi_name} on PyPI", f"https://pypi.org/project/{pypi_name}/"),
-        DistLink(
-            "PyPI simple index (installable files)",
-            f"https://pypi.org/simple/{normalize(pypi_name)}/",
-        ),
+    One rule per certified tool, mapping ``/simple/<name>/`` (and the
+    trailing-slash-less form pip may also request) to the tool's PyPI simple page.
+    Sorted + normalized; only listed tools resolve.
+    """
+    lines = [
+        "# Generated by `culture-tools index build` — do not edit by hand.",
+        "# pip-resolvable /simple/: each AgentFront-certified tool redirects to its",
+        "# PyPI simple page (the real distribution files). Only listed tools resolve,",
+        "# so the index stays curated; uncertified names fall through to 404.",
     ]
+    for name in sorted(project_names, key=normalize):
+        norm = normalize(name)
+        target = f"{_PYPI_SIMPLE}/{norm}/"
+        lines.append(f"/simple/{norm}/   {target}   302")
+        lines.append(f"/simple/{norm}    {target}   302")
+    lines.append("")
+    return "\n".join(lines)

docs/design/tools-culture-dev.md

@@ -114,8 +114,12 @@ Each milestone is one PR (this repo bumps the version every PR; the
   live conformance via `index build --repos-dir <cloned siblings>` and opens a PR
   (human-reviewed before a merge triggers the rebuild). Still open: `_redirects`
   for a pip-resolvable `/simple/`.
-- **M4 — Polish.** Agent affordances: `llms.txt`, markdown twins, sitemap,
-  conformance badges, SEO. (S3 durable tier can land here or later.)
+- **M4 — Polish.** *In progress.* Done: **pip-resolvable `/simple/`** (a
+  Cloudflare `_redirects` file maps each certified tool's `/simple/<name>/` to its
+  PyPI simple page — curated, so only listed tools resolve), **`/llms.txt`**, a
+  **`/catalog.json`** endpoint, and **markdown twins** (`/index.md`,
+  `/tools/<name>.md`). Sitemap shipped in M2. Remaining: conformance badge SVGs,
+  richer SEO, and the S3 durable tier.
 
 ## Open items (deferred, not blocking M1)
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "culture-tools"
-version = "0.5.1"
+version = "0.6.0"
 description = "tools.culture.dev — the package index for agent-first CLI tools that conform to the agentfront contract."
 readme = "README.md"
 license = "Apache-2.0"

site-astro/public/_redirects

@@ -0,0 +1,10 @@
+# Generated by `culture-tools index build` — do not edit by hand.
+# pip-resolvable /simple/: each AgentFront-certified tool redirects to its
+# PyPI simple page (the real distribution files). Only listed tools resolve,
+# so the index stays curated; uncertified names fall through to 404.
+/simple/agentfront/   https://pypi.org/simple/agentfront/   302
+/simple/agentfront    https://pypi.org/simple/agentfront/   302
+/simple/colleague/   https://pypi.org/simple/colleague/   302
+/simple/colleague    https://pypi.org/simple/colleague/   302
+/simple/culture-tools/   https://pypi.org/simple/culture-tools/   302
+/simple/culture-tools    https://pypi.org/simple/culture-tools/   302