Confluence API Doc

Publish API docs to Confluence — from the docs/api/*.yaml custom-YAML api-spec — one endpoint = one page, grouped under domain parents, with the service overview on the parent page. The full procedure (auth, source-select, page-tree mapping, the source→storage conversion rules, REST calls, round-trip normalization) is the single source in references/publish-reference.md — follow it; the steps below are the spine. Every push is gated on deterministic checks (pre-flight + round-trip) + an independent fresh-eyes pass + a completeness sweep, never on an HTTP 200.

ASSET_DIR = <skill base dir>/assets, SKILL_DIR = <skill base dir> (the skill-load message gives the "Base directory for this skill"). Input is the docs/api/*.yaml custom-YAML api-spec (authored by neo's Architect).

The spine

1. Gather — the source is the api-spec at docs/api/*.yaml (_meta.yaml + <domain>/<endpoint>.yaml); if it does not exist → STOP (run neo to author it). Then take the Confluence parent-page URL → page ID.
2. Auth — acli auth status → CONFLUENCE_URL + EMAIL; resolve the write token ($CONFLUENCE_API_TOKEN or ask once) at push time.
3. Scan — endpoint pages titled <METHOD>: <path>, one per group; parent page = the service overview. Title from the endpoint's method + path; assemble the page body from the endpoint YAML — description → intro, path_params/query_params/request_body.fields/responses[].fields → field tables, request_body.example / responses[].example → example blocks, business_logic → its own section, errors[] → the Error Responses table; parent body = _meta.overview + _meta.field_info + _meta.common_errors. Skip health/. (Full rules: publish-reference.md § Step P3.)
4. Map — fetch existing children (curl GET …?expand=space,children.page), match by exact title, plan create/update; create groups before endpoints.
5. Versions — acli confluence page view --id <id> --include-version --json.
6. Convert — markdown → Confluence storage per publish-reference.md § P6 (code blocks → code macro/CDATA first, then inline rules; mind the nested-list rule). Stage each page in the gitignored .api-doc-publish/ as both a <page>.json manifest and a raw storage/<page>.xml (the latter feeds the round-trip).