octo-html

octo-html — interactive HTML documents

This is NOT the octo-docs body-editing domain. octo-cli html … talks to octo-doc, where a document is a self-contained HTML page published as immutable versions. octo-cli docs … talks to the separate CRDT/Yjs backend.

All commands call $OCTO_API_BASE_URL/docs-html/v1/* and return the standard {ok, identity, data, ...} success envelope.

Document-reference contract

• Canonical create has no document reference. Omit slug and provide html. The CLI generates idempotency_key; an explicit key is optional. A display name belongs in meta.title; it is metadata, not identity.
• Save data.slug from the response. New documents always return data.doc_id and data.slug, with data.slug == data.doc_id, whether mounted or unmounted. Use data.slug for every later operation.
• Legacy documents keep their old reference. For an old document, use its legacy slug wherever this skill says <doc-ref>.
• No alias identity and no same-name republish. Creating again with the same meta.title creates a different document. To publish another version, supply the saved data.slug in the server's legacy-named slug field.
• Do not infer a mode from mount_type, registered, status, or whether data.doc_id is non-empty. registered and status report operational state, not identity.

Query and JSON-body fields remain named slug for wire compatibility. Put the saved document reference in them. Path help displays <doc-ref>, and old legacy slugs are accepted. The CLI does not persist the reference.

Minimum rollout dependency: this contract requires the canonical-create server changes in octo-docs-backend#166 and octo-docs-html#33 to be merged and deployed before this CLI is released.

Auth & space

• Authenticate with a stored bot profile (--profile / --bot-id) or OCTO_BOT_TOKEN; confirm the selected identity with octo-cli config show.
• Do not pass --space. octo-doc resolves identity and space server-side.
• Write operations require author/write capability. Reads need at least reader capability; backend failures are normalized into the CLI's {ok:false,error:{type,code,message,hint,detail}} envelope.