docs(skills): clarify wrapper-only catalog entries have no generator path (#1056)

46481718d35784638998c38cd00fab022bacbd79 · 2026-05-11 10:17:42 -0700 · Trevin Chow

The Wrapper-only branch in Phase 1's catalog-check section claimed Phase 3
generation reads the captured `implementation` field to decide whether to
`go get` a wrapper, emit a subprocess shell-out, or emit HTML-scrape code.
`printing-press generate` only consumes `--spec` and has no wrapper-mode
plumbing, so the skill silently dead-ended users on `google-flights`-style
entries.

Update the prose to match reality: wrapper-only catalog entries are
discovery aids only, the user has to choose between browser-sniffing the
upstream to author a spec or hand-writing a Go module that imports the
wrapper, and the `state.json.implementation` field is now described as
skill bookkeeping rather than generator input.

Refs #870

Files touched

M skills/printing-press/SKILL.md

Diff

commit 46481718d35784638998c38cd00fab022bacbd79
Author: Trevin Chow <trevin@trevinchow.com>
Date:   Mon May 11 10:17:42 2026 -0700

    docs(skills): clarify wrapper-only catalog entries have no generator path (#1056)
    
    The Wrapper-only branch in Phase 1's catalog-check section claimed Phase 3
    generation reads the captured `implementation` field to decide whether to
    `go get` a wrapper, emit a subprocess shell-out, or emit HTML-scrape code.
    `printing-press generate` only consumes `--spec` and has no wrapper-mode
    plumbing, so the skill silently dead-ended users on `google-flights`-style
    entries.
    
    Update the prose to match reality: wrapper-only catalog entries are
    discovery aids only, the user has to choose between browser-sniffing the
    upstream to author a spec or hand-writing a Go module that imports the
    wrapper, and the `state.json.implementation` field is now described as
    skill bookkeeping rather than generator input.
    
    Refs #870
---
 skills/printing-press/SKILL.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/skills/printing-press/SKILL.md b/skills/printing-press/SKILL.md
index d04ff3f1..28156f95 100644
--- a/skills/printing-press/SKILL.md
+++ b/skills/printing-press/SKILL.md
@@ -695,14 +695,14 @@ If the catalog has an entry for this API, branch on the entry type:
 - If catalog config: use the spec_url from the catalog entry, skip the research/discovery phase
 - If full discovery: proceed with the normal research workflow
 
-**Wrapper-only entry** (no `spec_url`, `wrapper_libraries` populated) — this is a reverse-engineered API that has no official spec but has known community libraries the generator can use as implementation backing. Do not try to resolve or browser-sniff a spec. Instead, surface the wrapper options to the user via `AskUserQuestion`:
+**Wrapper-only entry** (no `spec_url`, `wrapper_libraries` populated) — this is a reverse-engineered API that has no official spec but has known community libraries. The catalog entry is a **discovery aid only**: `printing-press generate` requires `--spec` and does not consume wrapper-library metadata, so there is no direct generation path from a wrapper-only entry today. Tell the user this up front via `AskUserQuestion`:
 
-> "<API> has no official spec. The catalog knows about these community-maintained implementations:"
+> "<API> has no official spec. The catalog knows about these community-maintained wrappers, but the Printing Press cannot generate a CLI directly from a wrapper. The next step has to be either browser-sniffing the upstream to author an internal YAML spec, or hand-writing a Go module that imports the wrapper. Which path do you want?"
 
-Present each `wrapper_libraries` entry as a selectable option with language, integration mode, and notes. Example for `google-flights`:
+Present each `wrapper_libraries` entry alongside the question with language, integration mode, and notes so the user can see what implementation backing exists. Example for `google-flights`:
 - **krisukox/google-flights-api** (Go, native, MIT) — Pure Go, importable; single-binary CLI with no runtime deps.
 
-Capture the user's choice and record it in `$API_RUN_DIR/state.json` under an `implementation` field: `{ "library": "<name>", "url": "<url>", "integration_mode": "native|subprocess|html-scrape" }`. Phase 3 generation reads this to decide whether to `go get` a wrapper, emit a subprocess shell-out, or emit HTML-scrape code. Skip the spec-analysis step entirely — there is no spec.
+Record the user's choice (and the selected wrapper, when relevant) in `$API_RUN_DIR/state.json` under an `implementation` field so later phases can read it: `{ "library": "<name>", "url": "<url>", "integration_mode": "native|subprocess|html-scrape", "next_step": "browser-sniff|hand-written-module" }`. This field is for skill bookkeeping; the generator does not currently read it. If the user picks browser-sniff, route into the Phase 1.7 browser-sniff path to produce a spec, then run `generate --spec` against it. If the user picks a hand-written module, stop the press here and hand off — there is no generator path to drop them into.
 
 **No catalog hit** — proceed normally without mentioning the catalog.

← 24962b7c feat(cli): sync.walker spec parameter for hierarchical APIs · back to Cli Printing Press · fix(cli): skip Windows Python Store stub in verify-skill (#1 27ad2dda →