docs: route schema authoring to the build-schema skill (ADR-0010)

[yuanwen-tian]

Supersedes #185 — same goal, skill layer only, zero CLI surface.

The problem #185 identified

The workflow is parse → schema → extract, and ade only ships two of the steps:

ade parse  →  [ you hand-write a JSON Schema ]  →  ade extract --schema
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
              entirely manual, unvalidated, and the hardest part

Meanwhile the build-schema skill (the landingai-ade plugin, mirrored from schema-loop) already does the middle step properly: it drives this very CLI through measured iteration — real extractions, reviewer-confirmed ground truth, negotiated per-field accuracy targets — and stops only converged with numbers or blocked with evidence. It delivers the final schema at <workspace>/deliverable/schema.json.

The two just didn't know about each other. That diagnosis, and all the context below, comes from #185.

What changed from #185

#185 bridged the gap in the CLI: a new ade schema build command, a post-parse "What next?" menu, agent adapters, PATH detection, new config.json keys, subprocess launching, and terminal gating — ~2,400 lines across 19 files.

This PR bridges it in the skill layer. The CLI is untouched: no new commands, no menus, no config keys, no subprocess launching, no agent detection. parse, extract, and the entire machine contract are byte-identical, because nothing in src/ changed.

The reasoning: the CLI's primary callers are agents, and an agent must never be handed an interactive foreground subprocess — #185 acknowledged this itself, gating the whole feature off under --json, --id-only, agent hosts, and CI, and telling agents in SKILL.md to invoke the skill directly instead of shelling out to the new command. That instruction was already the integration doing the real work for the primary caller. This PR keeps it and drops the CLI surface built around it.

What this PR does

Three files, no src/ changes:

SKILL.md — a new section, "No schema yet? Invoke the build-schema skill", sitting between the loop and the reuse posture. It tells an agent driving this CLI to invoke the build-schema skill rather than hand-authoring a schema and eyeballing the output; how to acquire the skill if the plugin isn't installed (local copy, else shallow-clone and follow plugins/landingai-ade/skills/build-schema/SKILL.md); and to hand the delivered deliverable/schema.json straight to ade extract.

It also carries two things an agent must surface before starting a run:

• It bills per iteration, not once. Every schema version is validated by a real extraction, so a converging loop costs roughly one extraction per document per iteration. The final extract is normally a free cache hit — the skill's last iteration already ran it. (feat: post-parse handoff to the build-schema agent skill (ADR-0010) #185 made the same disclosure across four CLI surfaces; here it belongs on the one surface the caller actually reads.)
• Seed it from the store. Pass the job_item_id of any parse already run, and its environment — re-runs are free, so the skill authors from the cached parse instead of re-billing one.

docs/adr/0010-schema-authoring-stays-in-the-skill-layer.md — the decision, including an explicit record of the CLI-side bridge and why it was rejected, so this doesn't get re-litigated from scratch. Notes that deliverable/schema.json is the one seam this repo trusts from the skill, with SKILL.md as the single place to follow if that layout ever changes; and that if a human-facing doorway is ever wanted, it is a separate decision that must revisit the rejection.

tests/test_help.py — one test in the existing SKILL.md narrative-guard band, pinning the routing, the skill's public location, the deliverable seam, and the cost disclosure.

What is not carried over

• No ade schema build command, no post-parse menu, no agents.py, no run_agent/which ports, no agent.default / agent.command / schema_prompt config keys.
• README.md is untouched. The README is user-facing, and this integration is agent-facing — a human without an agent session keeps the status quo.
• docs/reference/help.json needs no regeneration, since the command tree didn't change.

Testing

743 passed offline (tests/, integration excluded), plus the one new SKILL.md guard test. ruff check src tests and uvx ty check src are both clean.

No integration tests were needed or added: nothing in this PR executes, so there is no new seam to exercise against production and no credits are billed by the change.

🤖 Generated with Claude Code