git:20260908.531773d to git:20260909.ed513fe

61 added, 60 removed. Audit A to A.

---

name: openartifacts

- description: Publish, update, list, fetch, or unshare OpenArtifacts documents with rendered review before publication.

+ description: Render a document to HTML, let the user review the file, then publish it as a public OpenArtifacts page. Update or unshare published pages.

metadata:

hermes:

category: productivity

- tags: [publishing, markdown, artifacts]

+ tags: [publishing, html, artifacts]

---

# OpenArtifacts

- ## Shared publishing rules

+ Turn a document into a public web page. You render the HTML; OpenArtifacts hosts it.

+ The CLI is `openartifacts` when installed, otherwise `npx --yes openartifacts@latest`.

+ It only sends the HTML file you give it. Never run Node scripts of your own against

+ the API.

- Host adapters follow these rules and replace the standalone CLI

- instructions below with their own execution, authentication, document identity,

- and approval UI. Never run standalone commands when a host adapter supplies them.

+ ## 1. Render the page

- Before every publish or update:

+ Read the source the user points at and write one complete, self-contained HTML

+ document. Preserve the content faithfully. Inline your CSS. Scripts and external

+ resources are allowed and are published unchanged.

- 1. Prepare the requested page, preserving the source content. Themes are optional;

- a missing theme must not block publishing. HTML is accepted unchanged, including

- CSS, scripts, forms, frames, and external resources.

- 2. Present a protected local browser preview before publishing. The review copy

- must block page scripts, network requests, and navigation. This shows the static

- appearance; interactive behavior and external resources are unavailable during

- review. Never open the unrestricted source HTML as a fallback. Showing source,

- a path, or a summary does not count as a rendered preview. If the protected

- preview cannot be presented, stop; never publish to obtain a preview.

- 3. Wait for the user's explicit approval of the displayed page. The initial publish

- request and sign-in approval do not replace review. Hosts may enforce approval

- in an existing confirmation dialog. Never simulate the user's confirmation.

- 4. Publish the original reviewed HTML, without the preview's restrictions or shell.

- If the content changes, generate and present another preview and obtain fresh

- approval. Host branding may be added by the publishing integration; OpenArtifacts

- serving decorations need not appear in the local preview.

+ Themes are design specs written for you. If the user names one, read

+ `themes/<name>.md` next to this file and follow it. `research-memo` is bundled.

+ If the named theme does not exist, say so and continue with clean, readable

+ defaults of your own. A missing theme never blocks publishing.

- Preserve source identity so repeat publishing updates the same document. Keep the

- prepared artifact on cancellation or failure so review can be reopened. Hosts may

- remove temporary staged copies after confirmed success or explicit discard, but

- must retain the original source document. Return only the successful publisher's

- public URL. A pending review is not a successful publish.

+ ## 2. Let the user review

- Report actual failures without guessing causes, removing styling, bypassing review,

- or blindly retrying. If an update returns `not_found`, stop; do not create a replacement

- without the user's explicit request. For `quota_exceeded`, report whether to wait or

- remove an unused document. For `limit_reached`, show the supplied limit and upgrade

- link, and retry only after the user confirms the limit changed. Do not read credential

- files, print tokens, or ask the user to copy credentials.

+ Write the HTML to a new file next to the source, for example `notes.html` for

+ `notes.md`. Never overwrite the source. Tell the user the absolute path and that

+ opening it in a browser shows the page as it will be uploaded; OpenArtifacts adds its

+ own header and footer bylines when it serves the page. Then end your turn.

- ## Standalone CLI

+ Never publish in the same turn that produced the HTML. Publish only when a later

+ message from the user clearly asks to publish this page. Treat anything else as

+ feedback (revise the same file and repeat this step) or as a cancellation. When

+ unsure whether a message is an approval, ask once. Never simulate the user's

+ approval.

- This section applies only when no host adapter supplies execution instructions.

- Use `openartifacts` when installed, otherwise `npx --yes openartifacts@latest`.

+ ## 3. Publish

- - Preview Markdown or HTML locally: `openartifacts preview <file>`

- - Publish Markdown or HTML after review: `openartifacts publish <file>`

- - List documents: `openartifacts list`

- - Fetch current HTML: `openartifacts get <docId>`

- - Withdraw a document: `openartifacts unshare <docId>`

- - List machine tokens: `openartifacts tokens`

- - Revoke one: `openartifacts revoke <tokenId>`

- - Sign in again after an `unauthorized` response: `openartifacts login`

+ ```

+ openartifacts publish <file.html> --title "Page title"

+ ```

+ The command prints `{"docId":"…","url":"…","version":1}`. Give the user the url.

- Run `openartifacts preview <file> > <separate-review.html>`. Never overwrite the

- source. The command runs without authentication and prints the reviewed HTML's

- SHA-256 to stderr. Open the protected review file in a user-visible browser and

- wait for explicit approval. If `preview` is unavailable, use a release supporting

- it or stop. After approval, run

- `openartifacts publish <original-file> --reviewed-sha256 <printed-hash>`.

- A changed source is rejected before authentication or upload; preview it again.

- Keep the original source path so repeat publishing preserves document identity.

+ To update a page the user already published, pass its id so the same url gets the

+ next version:

- The first authenticated command may wait for browser sign-in approval. Relay both

- sign-in URLs and the user code printed by the CLI, then keep waiting. Browser

- sign-in is separate from approval of the rendered page.

+ ```

+ openartifacts publish <file.html> --title "Page title" --doc-id <docId>

+ ```

- Markdown uses ordinary Markdown rendering; Obsidian wikilinks, embeds, and callouts

- are not expanded. If the user explicitly requests a replacement after `not_found`,

- run `openartifacts unshare <oldDocId>` to forget the stale local mapping, then repeat

- preview, approval, and publishing. Never take that recovery path automatically.

+ Take the docId from the url you reported earlier (`…/d/<docId>`) or from

+ `openartifacts list`. Never guess a docId. If an update answers `not_found`, stop

+ and tell the user; do not publish a replacement unless they explicitly ask.

+ ## 4. Withdraw

+ ```

+ openartifacts unshare <docId>

+ ```

+ The url then answers 410 Gone. Copies readers already downloaded cannot be recalled.

+ ## Credentials

+ The CLI reads `OPENARTIFACTS_TOKEN` from the environment. It accepts an OpenArtifacts

+ token or a Brevilabs license key. Without it, the first authenticated command starts a

+ browser sign-in: relay both urls and the code the CLI prints, then keep waiting.

+ Publishing needs a paid OpenArtifacts plan. On `unauthorized`, tell the user they need a

+ credential with publishing access before anything can be published. Never read

+ credential files, print tokens, or ask the user to paste a credential into the chat.

+ ## Errors

+ Relay the CLI's message verbatim and do not retry blindly. For `quota_exceeded`, say

+ whether to wait or unshare an unused page. For `limit_reached`, show the limit and the

+ upgrade link the CLI prints.