Publishing and Updating Artifacts

/publish uploads a self-contained HTML artifact and returns a permanent share URL. It is an interactive HiPMMCode slash command: start a HiPMMCode session and enter it at the prompt, rather than invoking a shell subcommand.

Configure the artifact host

Add artifactHost to ~/.hipmmcode/config.json:

{
  "artifactHost": {
    "origin": "https://www.hipmmai.com",
    "apiKey": "your-api-key",
    "public": false
  }
}

The API key must have the artifact permission. You may override only the configured key through the environment:

export HIPMMCODE_ARTIFACT_KEY="your-api-key"

artifactHost.origin must remain in the configuration; the environment override applies only to the API key.

Use natural language

You do not need to remember /publish flags for the common Artifact lifecycle. In an interactive HiPMMCode session, requests such as these invoke the corresponding Artifact operation:

Publish README.md as a public Artifact titled "Project overview".
Turn ownership-plan.md into a professional infographic and publish it as an Artifact.
Update https://example.com/a/<hash> from dashboard.html and keep the same URL.
List my 10 most recent Artifacts.
Make the Artifact at <hash> private.
Make the Artifact at <hash> public and discoverable.
Delete the Artifact at <hash>.

HiPMMCode calls its first-class Artifact tool with the publish, update, list, set_visibility, or delete action. It does not construct or type a /publish command and does not start a nested HiPMMCode process. Deletion is irreversible and still requires explicit confirmation; permission granted for another Artifact action does not pre-authorize a later deletion.

The natural-language path accepts an explicit source file or inline Markdown/HTML/SVG for publishing and updating. Requests for professional infographics, visual comparisons, ownership structures, metric dashboards, or visual plans select the Visualizer renderer. After the first successful publish, it can also update by hash alone from the stable locally managed source. It is not a complete replacement for every conversation-source selector: publishing the last assistant reply with bare /publish, generating a conversation report with --report, and publishing the full transcript with --all remain available through the slash command. /publish is retained for users who want explicit, reproducible command syntax or those conversation-derived sources.

Command syntax

/publish [--file PATH|--report|--all]
         [--template morning-brief|plan|dataviz|visualizer|--enhance]
         [--public] [--discoverable]
         [--title TITLE]
         [--update HASH]

The command rejects unknown or duplicate flags and incompatible combinations before reading a file or uploading data.

Choose the source

# The last assistant reply
/publish

# An explicitly named file
/publish --file document.md
/publish --file dashboard.html
/publish --file ownership.svg

# A model-organized Markdown report of the conversation
/publish --report

# The complete conversation transcript as Markdown
/publish --all

A bare /publish always means the last assistant reply. It never scans a reply for a file path. Use --file explicitly to publish a file; relative paths resolve from the session's current working directory.

--file, --report, and --all are mutually exclusive. If report generation is unavailable, --report falls back to the last assistant reply.

Explicit files are limited to these case-insensitive extensions:

• .md and .markdown, rendered as Markdown;
• .html and .htm, used as complete HTML documents;
• .svg, validated and wrapped as a responsive Visualizer Artifact.

Other file types are rejected. Both the source and the rendered HTML must be no larger than 16 MiB. The host validates the final stored page again.

Local managed source and remote page

A successful publish creates two representations of the same Artifact:

• the editable managed source at ~/.hipmmcode/artifacts/<origin-id>/<hash>/source.md, source.html, or source.svg;
• the rendered HTML on the host at the stable /a/<hash> URL; capable hosts safely externalize exact known runtime bundles.

When a file is published from Desktop or any other location, HiPMMCode copies it into the managed directory after the remote operation succeeds; it never moves or deletes the original. A later bare /publish --update <hash> or natural-language update reads the managed copy. Supplying --file again explicitly imports a new file. Artifact listings include the local path and states such as current, modified, missing, and deleted. Deleting the remote Artifact retains its local source for recovery or republishing.

The host isolates remote content by account: database metadata is bound to the publisher's userId, and HTML lives at {UPLOAD_DIR}/{userId}/artifacts/{hash}.html. Listing, updating, changing visibility, and deleting require authentication as the original publisher. A public short link only resolves the file selected by its unguessable hash. Shared interactive runtimes are read-only site assets and contain no user content.

Title and visibility

/publish --title "API Reference"
/publish --public --title "Team Status"
/publish --discoverable --title "Quarterly Metrics"

When --title is omitted, HiPMMCode opens an interactive picker containing model suggestions and a derived default.

• The default is private: anyone with the share URL can open it, but it is not listed publicly.
• --public lists the artifact in the publisher's public gallery.
• --discoverable implies public and submits the artifact for moderation before it can appear in the global explore feed.
• artifactHost.public: true makes new artifacts public by default.

Templates and Visualizer

The static templates work only with Markdown. visualizer is a separate infographic renderer that accepts Markdown, complete HTML, and standalone SVG:

/publish --template morning-brief
/publish --file design.md --template plan --public
/publish --report --template dataviz --discoverable
/publish --file ownership-plan.md --template visualizer
/publish --file dashboard.html --template visualizer
/publish --file ownership.svg

The renderer names are morning-brief, plan, dataviz, and visualizer. Visualizer asks the active model to create a professional self-contained infographic with comparison cards, segmented bars, metric cards, responsive layouts, and inline SVG. If Markdown generation fails or is rejected by validation, HiPMMCode reports the reason and publishes the deterministic DataViz fallback while preserving Visualizer for future updates.

Standalone SVG automatically selects Visualizer. It must contain one <svg> root with a valid viewBox and no external resources; invalid SVG is not uploaded. Complete HTML selected as Visualizer remains author-controlled and receives the Visualizer marker and existing local runtime support.

AI-enhanced artifacts

--enhance asks the active model to turn Markdown into a polished, complete document with inline CSS and optional inline JavaScript:

/publish --file product.md --enhance --public

It is Markdown-only and mutually exclusive with --template. AI enhancement accepts at most 120,000 Markdown characters, and the generated document is checked for completeness, size, remote resources, and network APIs. If the input exceeds that enhancement limit, generation is unavailable, or validation fails, HiPMMCode reports the reason and falls back to its standard Markdown renderer. Pressing Ctrl+C during generation cancels the entire publish instead of uploading a fallback page.

Interactive runtimes and hosted size

Local previews and exported HTML remain fully self-contained and do not depend on a CDN. The standard Markdown shell includes local highlight.js; templates, direct HTML, and enhanced HTML add it when a language-* code block is present. Other local runtimes are added on demand:

• Mermaid when Markdown contains a mermaid fenced block;
• Chart.js when the document declares a data-chart-runtime JSON specification.

The Chart.js adapter reads one #primary-chart host and a JSON script such as:

<div id="primary-chart"></div>
<script type="application/json" data-chart-runtime>
{
  "type": "line",
  "series": [
    {"name": "Requests", "points": [["Mon", 12], ["Tue", 18]]}
  ]
}
</script>

The same runtime injection is applied to standard Markdown, templates, direct HTML, and successfully enhanced HTML. Keep direct HTML self-contained: the host's CSP blocks third-party scripts, styles, frames, and network requests.

In a local self-contained file or on an older host, these runtimes count toward the Artifact size: Mermaid is about 3.16 MiB, highlight.js about 0.94 MiB, and Chart.js about 0.20 MiB. An older Mermaid page is therefore commonly around 3.2 MiB, or around 4.1 MiB with a supported-language code block. This is runtime code, not duplicated prose.

A host advertising hipmmcode-artifact-runtime-v1 externalizes exact known runtimes to same-origin, content-addressed, read-only assets protected by SHA-256 SRI. The newly stored page is normally close to its actual content size; each runtime is stored once for the site and cached immutably. Brotli sizes are about 669 KiB for Mermaid, 239 KiB for highlight.js, and 60 KiB for Chart.js. Older hosts, failed negotiation, and unknown runtimes safely retain the original self-contained HTML.

Update an existing artifact

Copy the hash from the end of /a/<hash>, then publish replacement content:

# The locally managed source for this hash
/publish --update <hash>

# Explicit HTML and a new title
/publish --update <hash> --file dashboard.html --title "Dashboard v2"

# Other valid Markdown workflows
/publish --update <hash> --report --template plan
/publish --update <hash> --all --enhance

--update supports --file, --report, --all, --template, --enhance, and --title. With no source selector, a locally managed source must already exist; HiPMMCode does not overwrite an existing Artifact with an unrelated last assistant reply. The owner-only update replaces content and may update its title while preserving the hash, URL, and existing public/discoverable state. Consequently, --public and --discoverable are rejected when --update is present.

Hosting security and caching

Artifact responses use a strict Content Security Policy and sandbox. Inline script and style execution remains available for self-contained interaction, while external connections, forms, nested frames, object loading, and access to platform same-origin state are blocked. The host also sends X-Content-Type-Options: nosniff and Referrer-Policy: no-referrer.

Responses use Cache-Control: private, no-cache, must-revalidate plus a content-derived ETag. Clients therefore revalidate instead of retaining an immutable copy; matching conditional requests receive 304, and an update changes the ETag while keeping the URL.

Common errors

• Artifact host not configured: set artifactHost.origin and an API key in ~/.hipmmcode/config.json, or provide the key through HIPMMCODE_ARTIFACT_KEY.
• Unsupported artifact file type: use .md, .markdown, .html, .htm, or .svg with --file.
• Artifact source is empty: complete an assistant reply or choose a non-empty explicit source.
• Artifact too large: reduce embedded content until both the source and final document are at most 16 MiB.
• Update failed with 404/403: verify the URL hash and use the API key belonging to the original publisher.