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.

bashCopy code
# 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.

Recover version errors autonomously

The bot MUST recover from version_conflict and version_required within the same task. Do not end the task by reporting the raw version error to the user or ask the user to perform a routine reread/retry. CLI exit code 2 is a tool result for the bot to handle, not the final answer to the user. Only these specific version error codes trigger this recovery workflow.

1. Keep the original source, the intended edit, and the same document reference.
2. Run octo-cli html source <doc-ref> again without --version. Retain the fresh data.html and data.version together; the version and fixed source_path in the earlier error may already be outdated.
3. Compare the original source, your proposed edit, and the fresh source. Reapply only the user's intended changes to the fresh HTML, preserving concurrent edits. If the requested result is already present, verify it and report completion without publishing a duplicate version.
4. Publish the newly merged HTML to the same --slug, with the fresh version plus one. Do not create a new document or reuse a create idempotency_key for this update.
5. If another version error occurs, repeat from step 2. Make up to three recovery attempts after the initial rejection; each attempt must reread and merge again. This is a bot workflow, not a CLI HTTP retry of the same body.
6. After a successful publish, verify the returned version's source and report the completed update and document URL. Mark an edit/comment as applied only after verifying that it was published.

Involve the user only when overlapping changes have incompatible meanings that cannot be resolved from their request, another error prevents completion, or all three recovery attempts still conflict. Explain the specific unresolved change or ongoing contention instead of simply forwarding a version error.

Never just increase --version and resend stale HTML. Do not switch to publication through drafts or element replacement to bypass a rejected update; draft promotion and element replacement do not substitute for guarded full-document publishing. Element replacement's base_version locates source content; it is not this publish precondition.

2. Author drafts

A draft is an author-only working slot and does not mint an immutable version until promoted.

bashCopy code
# Create a canonical draft without a document reference. Save response data.slug.
octo-cli html draft create --html '<html><body><h1>WIP</h1></body></html>'

octo-cli html draft save <doc-ref> --data '{"html":"<html><body><h1>WIP</h1></body></html>"}'
octo-cli html draft promote <doc-ref>

3. Sharing and grants

bashCopy code
# Mint/rotate or revoke a bearer share code.
octo-cli html share <doc-ref>
octo-cli html unshare <doc-ref>

# Grant/list/revoke named-reader access.
octo-cli html grant add <doc-ref> --uid <uid> --role reader
octo-cli html grant list <doc-ref>
octo-cli html grant rm <doc-ref> <uid>

4. Media assets

bashCopy code
octo-cli html asset ls <doc-ref>
octo-cli html asset add <doc-ref> --file ./chart.png
octo-cli html asset rm <doc-ref> <sha256>

5. Comments

The wire parameter remains slug; pass the saved document reference.

bashCopy code
octo-cli html comment list --slug <doc-ref> [--version all]
octo-cli html comment add --data '{"slug":"<doc-ref>","text":"Please clarify this","anchor":{"kind":"element","aid":"<content-hash>"}}'

html comment list likewise preserves offset metadata in _pagination; it has no cursor flags or --page-all support.

6. Agent element edit and reply

bashCopy code
# Read one stamped artifact (version 0 or omitted means latest).
octo-cli html element get --data '{"slug":"<doc-ref>","aid":"<content-hash>"}'

# Replace exactly one safe top-level element and publish a new version.
octo-cli html element replace --data '{"slug":"<doc-ref>","aid":"<content-hash>","new_html":"<section>updated body</section>"}'

# Reply to a comment thread with an optional applied/partial/question verdict.
octo-cli html reply --data '{"slug":"<doc-ref>","parent_id":"<comment-root-id>","text":"Done.","status":"applied"}'

To preserve comment anchors, prefer narrow element replacements; avoid changing an element's tag or nearby heading unless necessary.

Errors

• 428 VALIDATION_ERROR, with error.detail.error.details.code=version_required — a bot update omitted its output version or sent zero. Read with html source, edit that source, then publish its version plus one autonomously using the recovery workflow above; do not stop at the tool error.

• 409 CONFLICT, with error.detail.error.details.code=version_conflict — the output version is stale or skips ahead. Read the latest source and reapply the intended edit while preserving others' changes. Never just increase --version and resend stale HTML. Both errors exit with code 2; the backend recovery hint is preserved at error.detail.error.hint and version/source fields at error.detail.error.details. Complete the recovery workflow above before reporting the result to the user.

• 403 bot_delete_forbidden — terminal bot-deletion policy denial, including already-deleted retries on the docs-backend routes. Do not retry, change roles/identity/Space, or switch endpoints; ask a human document admin to delete it. This is not a successful deletion or a missing-membership problem.

• 401 / 403 — missing or insufficient capability.

• 404 — the requested document, comment, or aid may be missing or inaccessible. A route-level 404 from html source can instead indicate an unavailable source endpoint. Follow the rollout check above before diagnosing the document as missing: readable metadata confirms it exists but is never a source/version fallback. Do not create a replacement document or publish without the guard.

• 400 html_contains_javascript — the published or draft HTML carries JavaScript (see the no-JavaScript rule in §1). details.violations names every offending construct with its kind / tag / attr / line; regenerate the document without script rather than retrying it unchanged.

• Element replacement rejects multiple top-level elements, scripts/styles, inline event handlers, and javascript: URLs.

Schema lookup

bashCopy code
octo-cli schema --list html
octo-cli schema html.source
octo-cli schema html.publish
octo-cli schema html.element.replace
octo-cli schema html.reply