Publish rich work from any agent. Let people verify sources, request changes, approve outcomes, and send decisions back—without flattening the work into a PDF.
html-docsA capability-based model that makes agent access explicit, reviewable, and safe by default.
An agent, import, or person creates the same first-class artifact.
People verify evidence and request typed, owned changes in context.
The rationale, final version, and accepted patch become a durable record.
Reviews, approvals, mentions, and agent revisions in one queue.
Agent, import, and blank creation all become the same reviewable artifact.
The agent gets a live artifact URL, scoped workspace context, and a structured contract. You remain the owner of review and publication.
e5b39f9 · checked 3 min agoMove from route-specific ownership checks to explicit capabilities shared by humans, API keys, and agents.
HTML Docs now has multiple creation and mutation paths: the web editor, CLI, public API, Docsmith, and connected agents. Each path currently reconstructs authorization from route context.
Adopt a capability-based access policy that evaluates the actor, artifact, requested operation, and provenance in one transaction boundary. Begin with write operations and keep read compatibility during migration.
The structured editor gives human and agent actions a common command model. Authorization should attach to those commands—not to the UI surface that happened to issue them.
Move from route-specific ownership checks to explicit capabilities shared by humans, API keys, and agents.
Codex addressed both requested changes: the recommendation now names six capabilities, and the migration section separates enforcement from observability. No evidence sources changed.
Adopt six explicit capabilities evaluated at the shared transaction boundary for every human, key, and agent mutation. Begin with write operations and preserve read compatibility during migration.1
Approve the capability model and phase-one instrumentation. This decision does not authorize removal of existing ownership checks.
A review begins with a named decision, named accountable people, and a frozen comparison point. Conversation can be messy; the product state cannot. Every request is typed, every revision is previewed, and completion has explicit gates.
Owner, approvers, due date, decision statement, and review criteria are required before notifications go out.
Reviewers see a summary, provenance, source freshness, and exactly what changed since their last visit.
Question, change request, note, and decision are distinct objects with scope, owner, and resolution state.
A person or connected agent proposes small semantic patches. Reviewers accept, reject, or request another revision.
Required approvals, unresolved blockers, rationale, final version, and return-to-agent receipt form the decision record.
A reviewer can participate without being an approver. One accountable owner is responsible for getting the work to a decision.
Create artifacts, read feedback, propose scoped revisions, and receive decisions through one contract.
It is not an embedded chatbot. It is Codex, Claude, Cursor, or a custom workflow authenticated as a named integration, linked to the task that produced an artifact, and allowed to perform a small set of review-aware operations.
Publishes an artifact with source and task provenance.
Receives assigned questions and change requests.
Returns scoped, inspectable document operations.
A human accepts, rejects, or asks for revision.
The outcome and accepted patch return to the original task.
Integration name, provider, workspace, installation owner, and agent task are recorded on every mutation.
Explicit scopes such as create artifacts, read assigned feedback, or submit proposals—never a shared human session.
Artifact regions link back to repository files, source revisions, prompts, recipes, and the originating agent run.
MCP polling, webhooks, CLI watch, or task callbacks deliver feedback and the final decision upstream.
The same contract powers Codex, Claude, the CLI, and custom agents. Scopes remain explicit and revocable.
$ npx html-docs connect --mcp workspace acme-product scopes read:artifacts, write:proposals, read:feedback, read:decisions connected ✓ codex $ html-docs publish ./decision-brief.html created artifact hdoc_8c1d review https://html-docs.com/a/hdoc_8c1d
artifacts.createfeedback.listproposals.createdecisions.watchNo model lock-in. HTML and a documented contract are the shared surface.
Every mutation names its target, actor, diff, and inverse action.
Approval and publication are deliberate product states, not generic comments.
Artifact, evidence, review history, and rationale remain one addressable object.