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 and set --version to the version read with html source plus one.
• 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. Source reads and guarded bot updates also require octo-docs-html#34. The HTML backend will be deployed first. The CLI release and rollout of its updated skills follow only after the source endpoint and publish guard are deployed and verified on every HTML-serving instance. Do not release this workflow during a mixed old/new backend rollout.

If html source unexpectedly returns a route-level 404, check the same reference with octo-cli html get <doc-ref> using the same identity and gateway. If metadata is readable, the document exists: report that the source endpoint is unavailable and the backend deployment or gateway routing needs checking. Do not report the document as missing or create a replacement. If both reads fail, a 404 alone cannot distinguish a missing/inaccessible document from a deployment problem; retain the reference and report the uncertainty. Stop this update until source access is restored. Do not infer a version from metadata, publish without a version, or switch endpoints to bypass the guard. Once the backend is ready, recover actual 409/428 version errors autonomously as described below.

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.

1. Create and publish

Bots cannot delete documents, even as author, owner, or admin. Do not run octo-cli html rm <doc-ref> or use docs delete / raw api DELETE as an alternative. Ask a human with document admin permission to delete it in Octo. This includes cleanup of test documents and applies to canonical IDs and legacy slugs. Creating, publishing versions, editing, and permitted asset/comment operations are unchanged.

html rm targets /docs-html/v1/docs/{doc_id}, a different service entry from the docs-backend /v1/bot/docs/octo-doc/:octoDocSlug deletion route. Do not infer that one route's deployment proves the other's enforcement, and do not probe the other route as a workaround.

Documents are declarative: no JavaScript. The backend rejects any publish or draft whose HTML carries script, with 400 and the stable code html_contains_javascript. This is not advisory — there is no flag to opt out. When generating a document, never emit:

• <script> elements (including inside <svg>),
• on* event-handler attributes (onclick, onload, onerror, …),
• javascript: / vbscript: / scriptable data: URLs in href, src, xlink:href, action, formaction, object[data], or a non-empty srcdoc.

Express interaction with CSS instead — :hover, :target, :checked + sibling selectors, <details>/<summary>, transitions and animations all work and cover most of what a document needs. Do not assume script is merely inert: the host application embeds documents in a sandboxed iframe, but the document's own version URL serves the stored HTML as a top-level page, so script that got stored would execute for every reader who opens that link. CSS, inline style, <iframe>, <noscript> and <meta http-equiv=refresh> are all still allowed.

On rejection the error details.violations lists every offending construct with its kind, tag, attr and 1-based line. Fix all of them in one pass — the list is complete (capped at 50, with details.truncated set when it overflows). Do not retry the same document unchanged, and do not try to work around the gate by encoding or splitting the script.

# Canonical create: no --slug. The CLI generates the idempotency key.
octo-cli html publish --data '{"html":"<html><body><h1>Runbook</h1></body></html>","meta":{"title":"Runbook"},"mount_type":"group","group_no":"<group_no>"}'
# → data: { doc_id, slug, version, url, share_url, size, aids,
#           merged_comments, registered, status }
# Save data.slug; for this new document data.slug == data.doc_id.

# Unmounted creation follows the same identity contract and also gets doc_id.
octo-cli html publish --data '{"html":"<html><body><h1>Private draft</h1></body></html>","meta":{"title":"Private draft"}}'

# Read HTML and its version together, then edit data.html.
octo-cli html source <doc-ref>
# → data: { slug, version, html }
# Publish version 2 only if the source read returned version 1.
# Keep the wire field name `slug` and omit
# idempotency_key. Pass ONLY a slug the server returned earlier: an unregistered
# slug does not create a canonical document — it produces a legacy unregistered
# one that never appears in the sidebar file list. Never invent a slug.
octo-cli html publish --version 2 --data '{"slug":"<doc-ref>","html":"<html><body><h1>Runbook v2</h1></body></html>","meta":{"title":"Runbook"}}'

# An explicit --idempotency-key <same-operation-key> is supported only for
# retrying this exact creation operation. The CLI-generated key is created once
# per invocation and the HTTP retry loop reuses the same serialized request.
# Reusing a key with different HTML returns the old document and discards the
# new HTML. Once its document is deleted, that key is unusable.
#
# UNATTENDED CALLERS: supply your own stable --idempotency-key and persist it
# before the call. A generated key lives only for that invocation, so if a
# timeout or 5xx leaves the outcome unknown, a plain re-run creates a SECOND
# document without returning the first one's reference. Bots must not delete
# documents as cleanup. With your own key the re-run resumes the same
# creation. A failed create also reports the key it used in the error envelope's
# detail (and hint), so an ambiguous failure stays recoverable either way.

# List, inspect, and list versions.
octo-cli html list
octo-cli html get <doc-ref>
octo-cli html versions <doc-ref>

html list returns the backend's offset envelope as data plus _pagination (total, page, page_size). It has no cursor flags or --page-all support.

Mounts (group, space, or thread) control placement/registration only. For group, pass group_no; for thread, pass thread_id. They do not choose the document-reference format.

WITHOUT mount_type the backend skips docs-backend registration, so the HTML never shows up in the sidebar file list — this is the #1 "my doc didn't appear" gotcha. An unmounted document still receives a canonical doc_id; registration and identity are separate concerns.

Concurrent edits and the existing --version flag

Before editing an existing HTML document, run octo-cli html source <doc-ref>. Retain data.html and data.version from that same response. It reads GET /docs-html/v1/docs/{doc-ref}/source and returns the full stored HTML without the viewer overlay. To inspect a fixed historical source, use octo-cli html source <doc-ref> --version 7; omit --version to read latest. html get only returns metadata; do not pair a separately fetched version number with older HTML.

--version is the new output version. If the source read was version N, edit that source and publish with --version N+1 (a concrete integer, such as --version 2 above). The server's concurrency guard requires this value to match its current latest version + 1. Updates must not use omitted or zero version, because automatic allocation cannot detect a stale edit. First publication can still omit the flag. No new CLI parameter is needed.

HTTP 428 / version_required means the update omitted its output version. HTTP 409 / version_conflict means the requested version is stale or skips past the next version. The backend's error.details contains version, latest_version, next_version, and source_path; in CLI output these are preserved under error.detail.error.details. Read that source, inspect others' changes, and reapply the intended edit before submitting its version plus one.