Skip to content

ADR-004 — Direct-use and repository-native surfaces replace programmatic SEO

Status: Accepted, 2026-09-06 Amended: 2026-09-09 by ADR-012; CLI and MCP remain the primary direct-use surfaces, and the GitHub Action is the repository-native integration and acquisition surface Affects: Target Architecture §12 (ordering only, no removal); Phase Plan Phase 1, Phase 2, 90-day checkpoint

Context

Phase Plan v1.3 made generated model and error pages with a six-row indexing-gate table a Phase 1 deliverable and treated exact-error search as the acquisition surface. Verification on 2026-09-06 found: Google served an AI Overview containing the exact fix flags on four of four vLLM error queries tested live; organic click-through on such queries is 0.5 to 0.7 percent; at least six programmatic vLLM error hubs launched since April 2026; the March 2026 core update penalized sites repackaging stronger sources; vLLM's own troubleshooting doc is structured and its RunLLM bot answers most community questions; Stack Overflow new questions fell 99 percent from peak. The consumer of deployment output is now predominantly a coding agent.

Decision

  1. Phase 1 primary direct-use surfaces are the CLI and local MCP server, exposing resolve, plan, render, deploy, verify, diagnose, and evidence retrieval. A coding agent must be able to run the whole loop without a human translating output.
  2. Generated model pages, generated error pages, the indexing-gate table, canonical lineage pages, and near-duplicate inheritance are removed from Phase 1 and are not scheduled. §12's web application remains in the architecture as a human planning surface and is delivered in Phase 2 as a thin view over the same core, not as an acquisition system.
  3. Public exposure of evidence is through the dataset (ADR-002), the MCP server, and the interop formats, not through indexed advice pages. Amendment (2026-09-06): every record, and every model-hardware-engine combination, has a stable permalink that returns the raw record, JSON first with minimal HTML around it, showing revision, engine tag and digest, hardware, exact command, predicted beside measured, method, date, evidence level, and lifecycle state. No prose, no advice, no generated explanation. This is discoverability for agents that find results through web search and cite URLs; it is not the programmatic-SEO system removed in point 2. The Hub dataset viewer satisfies most of it; the remainder is a static export. Amendment 2 (2026-09-06): verified records are additionally rendered into a recipes-style catalogue: per model and per card, the Compose file and serve command that booted, with measured memory and throughput beside them and the record permalink. club-3090 is the observed precedent for adoption of this form factor in the consumer and professional niche; its volatile popularity count is not an architectural premise. The catalogue is generated by the existing renderers from records only; no entry exists without a boot record, no prose, no advice. It is the artifact in the place people copy from, not an acquisition page.
  4. The 90-day checkpoint replaces "exact-error search impressions and qualified entrances" with completed CLI/MCP planning, diagnosis or verification operations; completed material repository checks; and records consumed by external tools or cited in external issues. Marketplace impressions, workflow references, badge views and skipped jobs do not count. The unsolicited-reference target is unchanged.
  5. ADR-012 adds a repository-native surface without restoring programmatic SEO: mondegreens/apron-action adapts the same released core and schemas into GitHub Checks for model, engine, artifact, workload and deployment changes. Its first release is GPU-free and distinguishes calculation from validation; authorized GPU execution uses the ordinary execution-target contract. Marketplace discovery, workflow references and badges are distribution signals, not proof of a successful plan or qualification.

Consequences

  • Phase 1 scope shrinks by one subsystem (page generation and canonicalization).
  • The 90-day counting rules are re-specified for agent invocations; instrumentation is a named Phase 1 deliverable.
  • Nothing is removed from the target architecture; §12 keeps every interface over the common core.
  • Repository users can receive continuous qualification feedback where configuration changes occur, while CLI, MCP, Action, API and web remain views over one decision authority.