artifacty 0.1.0 → 0.1.2

package/README.md

@@ -1,5 +1,10 @@
 # Artifacty
 
+[![Publish](https://github.com/raeseoklee/artifacty/actions/workflows/publish.yml/badge.svg)](https://github.com/raeseoklee/artifacty/actions/workflows/publish.yml)
+[![npm version](https://img.shields.io/npm/v/artifacty.svg)](https://www.npmjs.com/package/artifacty)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node.js >=22.5](https://img.shields.io/badge/node-%3E%3D22.5-339933.svg)](package.json)
+
 Artifacty is a local, agent-to-agent artifact exchange for LLM workflows. Claude, Codex, Gemini, and other MCP-capable tools can publish an artifact once, then other agents can list, read, update, and continue from it without copying content through chat.
 
 ![Artifacty overview showing multiple AI agents sharing artifacts through a local exchange](docs/assets/artifacty.png)
@@ -8,100 +13,197 @@ Artifacty is a local, agent-to-agent artifact exchange for LLM workflows. Claude
 
 Claude Code artifacts are useful because they turn session output into shareable, versioned pages. Artifacty keeps that local and cross-agent: the browser server renders artifacts for people, while the MCP stdio server gives agents a common tool interface.
 
-## Quick Start
+## Installation
+
+Artifacty requires Node.js 22.5 or newer.
 
-Install and start Artifacty:
+Install the CLI globally from npm:
 
 ```bash
 npm install -g artifacty
-artifacty serve
+artifacty --help
 ```
 
-For local development from a checkout:
+Run it without a global install:
 
 ```bash
-npm install
-npm test
-npm start
+npx artifacty@latest serve
+```
+
+Start the local dashboard:
+
+```bash
+artifacty serve
 ```
 
 Open the URL printed by the server. Artifacty prefers `http://127.0.0.1:8787`; if that default port is busy and no explicit port was configured, it starts on the next available local port and records the actual URL for CLI and MCP responses.
 
-Run the production-readiness check:
+Run it in the background and return to your prompt:
 
 ```bash
-npm run release:check
+artifacty start
+artifacty status
+artifacty stop
 ```
 
+`artifacty serve --detach` is equivalent to `artifacty start`. Logs are written under `~/.artifacty/logs/`.
+These lifecycle commands use Node's detached process support and work on macOS, Linux, and Windows. `artifacty stop` uses Windows `taskkill` on Windows and process-group signals on macOS/Linux.
+
+Generate an API token at startup when you want to protect HTTP API and browser write routes:
+
+```bash
+artifacty serve --generate-token
+artifacty serve --host 0.0.0.0 --share-mode lan --generate-token
+npm start -- --generate-token
+```
+
+The server prints the generated token plus `/new?token=...` and `/import?token=...` URLs. For scripts or background services that need a stable token, generate one first:
+
+```bash
+artifacty token
+artifacty start --api-token "$(artifacty token --raw)"
+```
+
+Install MCP configuration for local agents:
+
+```bash
+artifacty install claude
+artifacty install codex --dry-run
+artifacty install gemini
+artifacty install all
+artifacty check
+```
+
+Use `artifacty install codex --timeout 30000` or
+`artifacty install gemini --timeout 30000` to tune supported MCP client timeouts.
+
+See [docs/integrations.md](docs/integrations.md) for Claude Code, Codex, and Gemini CLI setup.
+
+## Quick Start
+
 Create an artifact in the browser:
 
 ```text
 http://127.0.0.1:8787/new
 ```
 
+For local development from a checkout:
+
+```bash
+npm install
+npm test
+npm start
+```
+
+Run the production-readiness check:
+
+```bash
+npm run release:check
+```
+
 Publish from the CLI:
 
 ```bash
-node src/cli.js publish --title "handoff note" --format markdown --source codex --content "# Next step\nReview the API plan."
+artifacty publish --title "handoff note" --format markdown --source codex --content "# Next step\nReview the API plan."
 ```
 
 Import an artifact produced by another agent and convert it to Artifacty format:
 
 ```bash
-node src/cli.js import --agent claude --file ./deploy-failures.html --tag review
-node src/cli.js import --agent gemini --content '{"title":"Plan","returnDisplay":"# Plan\n- Ship it"}'
+artifacty import --agent claude --file ./deploy-failures.html --tag review
+artifacty import --agent gemini --content '{"title":"Plan","returnDisplay":"# Plan\n- Ship it"}'
+artifacty import --agent codex --content '{"agent":"codex","title":"Implementation Handoff","goal":"Continue Phase 3","changedFiles":[{"path":"src/lib/render.js","status":"modified"}],"nextSteps":["Add CodeMirror read-only viewer"]}'
 ```
 
-List artifacts:
+Codex structured payloads can become `handoff`, `bundle`, `diff-walkthrough`,
+`code-review`, or `test-report` artifacts when the payload explicitly identifies
+Codex through `agent` or `sourceAgent`. Plain Codex Markdown stays a normal
+`document` unless you pass an explicit `artifactType`.
+
+## Agent Handoff Example
+
+One agent can publish a continuation artifact, then another agent can discover it, read the context, and append the next version.
+
+Codex publishes the handoff:
 
 ```bash
-node src/cli.js list
+artifacty import --agent codex --tag handoff --content '{
+  "agent": "codex",
+  "title": "Release Handoff",
+  "goal": "Prepare Artifacty for an npm release",
+  "changedFiles": [
+    { "path": "src/lib/converters.js", "status": "modified", "summary": "Normalize agent outputs" }
+  ],
+  "commands": [
+    { "command": "npm run release:check", "status": "passed" }
+  ],
+  "nextSteps": [
+    "Review README",
+    "Publish package"
+  ]
+}'
 ```
 
-Run the MCP server:
+Claude or Gemini finds the handoff and continues from the same artifact:
 
 ```bash
-node src/mcp-server.js
+artifacty list --tag handoff
+artifacty show release-handoff-abc12345 --raw
+artifacty update release-handoff-abc12345 \
+  --format markdown \
+  --source claude \
+  --tag handoff \
+  --content "# Release Handoff\n\nReviewed README and prepared publish notes."
 ```
 
-MCP clients can create artifacts with `artifacty_create`. `artifacty_publish` remains as a backwards-compatible alias.
+List artifacts:
 
-Install MCP configuration for local agents:
+```bash
+artifacty list
+```
+
+Run the MCP server:
 
 ```bash
-node src/cli.js install claude
-node src/cli.js install codex --dry-run
-node src/cli.js install gemini
-node src/cli.js install all
-node src/cli.js check
+artifacty-mcp
 ```
 
-See [docs/integrations.md](docs/integrations.md) for Claude Code, Codex, and Gemini CLI setup.
+MCP clients can create artifacts with `artifacty_create`. `artifacty_publish` remains as a backwards-compatible alias.
 
 Operational commands:
 
 ```bash
-node src/cli.js audit --limit 20
-node src/cli.js backup
-node src/cli.js export --file ./artifacty-backup.json
-node src/cli.js import-store --file ./artifacty-backup.json
-node src/cli.js service install --dry-run
+artifacty audit --limit 20
+artifacty backup
+artifacty export --file ./artifacty-backup.json
+artifacty import-store --file ./artifacty-backup.json
+artifacty start
+artifacty status
+artifacty stop
+artifacty service install --dry-run
 ```
 
-After global installation, the same commands are available as `artifacty` and `artifacty-mcp`.
+When working from a source checkout without global installation, replace `artifacty` with `node src/cli.js` and `artifacty-mcp` with `node src/mcp-server.js`.
 
 ## Storage
 
 By default Artifacty stores files under `~/.artifacty`.
 
 ```bash
-ARTIFACTY_HOME=/path/to/shared/store npm start
+ARTIFACTY_HOME=/path/to/shared/store artifacty serve
 ```
 
 Artifact metadata is stored in `artifacty.sqlite`; artifact content is stored as immutable version files under `artifacts/`. The current browser server URL is written to `server.json` so MCP tools can return the correct links when the default port falls back. Existing `index.json` stores are migrated automatically on first access.
 
 ## API Example
 
+Start a protected server in another terminal, or generate a reusable shell token first:
+
+```bash
+artifacty serve --generate-token
+export ARTIFACTY_API_TOKEN="$(artifacty token --raw)"
+```
+
 ```bash
 curl -s http://127.0.0.1:8787/api/artifacts \
   -H 'content-type: application/json' \
@@ -134,7 +236,7 @@ Browser routes:
 - `/`: list artifacts with search, tag, and source filters.
 - `/new`: create an Artifacty-native artifact with the CodeMirror editor.
 - `/import`: paste an external agent artifact and convert it with automatic editor mode detection.
-- `/artifacts/:id/edit`: save a new version with Markdown, HTML, JSON, or text syntax support.
+- `/artifacts/:id/edit`: save a new version with Markdown, HTML, JSON, text, code, SVG, Mermaid, or React syntax support.
 - `/artifacts/:id/diff`: compare versions.
 - `/api/audit`: list audit events.
 
@@ -147,18 +249,25 @@ Schema and storage:
 - Metadata lives in SQLite with `schemaVersion: 1`, `artifactType`, and `archivedAt`.
 - Archive hides artifacts from default lists without deleting versions.
 - Bundle artifacts store multiple files or base64 assets as portable JSON.
+- Supported formats are `html`, `markdown`, `text`, `json`, `code`, `svg`, `mermaid`, and `react`.
+- Diagram, component, and source snippet artifacts use `diagram`, `component`, and `snippet` artifact types.
 - See [docs/artifact-schema-v1.md](docs/artifact-schema-v1.md).
+- See [docs/sarif-csv-artifact-plan.md](docs/sarif-csv-artifact-plan.md) for the SARIF/CSV output artifact roadmap.
 
 ## Security Model
 
 - The HTTP server binds to `127.0.0.1` by default.
 - If `ARTIFACTY_API_TOKEN` is set, HTTP API routes require `Authorization: Bearer <token>` or `x-artifacty-token`.
 - Binding outside localhost requires both `ARTIFACTY_SHARE_MODE=lan` or `team` and `ARTIFACTY_API_TOKEN`.
+- Non-local sharing is intended for trusted LAN or VPN sessions. Prefer a specific interface IP over `0.0.0.0`, keep React rendering disabled, and see [docs/network-sharing.md](docs/network-sharing.md).
 - Artifact content is scanned for common API keys and private keys before storage. Use `--allow-secrets` or `ARTIFACTY_ALLOW_SECRETS=true` only for intentional exceptions.
 - Creates, updates, reads, imports, archives, and restores write audit events to SQLite.
-- CodeMirror editor assets are served from local npm dependencies through a package allowlist, not from a public CDN.
+- CodeMirror editor/viewer and renderer assets are served from local npm dependencies through a package allowlist, not from a public CDN. JavaScript asset routes answer `Origin: null` requests with `Access-Control-Allow-Origin: null` so sandboxed renderer iframes can import local ESM without `allow-same-origin`.
 - Mutating HTTP routes reject non-local browser origins.
 - HTML artifacts render in a sandboxed iframe.
+- SVG artifacts render in a scriptless sandboxed iframe and are sanitized for `<script>`, `on*` attributes, and `javascript:` links in the viewer. The raw source remains unchanged.
+- Mermaid artifacts render with the vendored local Mermaid package in a sandboxed iframe without `allow-same-origin`.
+- React artifacts are source-only by default. Set `ARTIFACTY_ENABLE_REACT_RENDERER=true` to execute them in a sandboxed frame with a frame-scoped CSP that permits JSX transformation.
 - Artifact content should still be treated as untrusted; use the raw view when handing content back to an agent.
 
 See [docs/release-checklist.md](docs/release-checklist.md) before publishing or running a shared instance.

package/docs/artifact-schema-v1.md

@@ -32,6 +32,9 @@ Allowed `artifactType` values:
 - `diff-walkthrough`
 - `bundle`
 - `asset`
+- `diagram`
+- `component`
+- `snippet`
 - `unknown`
 
 Unknown legacy or external types should be mapped to `unknown`, not rejected during conversion. Native create/update rejects unsupported explicit types.
@@ -53,7 +56,24 @@ Each version is immutable and points at one content file.
 }
 ```
 
-Allowed `format` values are `html`, `markdown`, `text`, and `json`.
+Allowed `format` values are `html`, `markdown`, `text`, `json`, `code`, `svg`,
+`mermaid`, and `react`.
+
+## Renderer Policy
+
+Storage preserves artifact source as immutable content. Browser rendering is a
+viewer concern and must treat all source as untrusted:
+
+- `code`: read-only CodeMirror viewer with escaped source fallback.
+- `svg`: scriptless sandboxed iframe after viewer-side sanitization; `/raw`
+  preserves the original source.
+- `mermaid`: vendored local Mermaid bundle in a sandboxed iframe without
+  `allow-same-origin`. Local JavaScript assets use
+  `Access-Control-Allow-Origin: null` for `Origin: null` requests so the
+  opaque-origin frame can import ESM.
+- `react`: source-only by default. `ARTIFACTY_ENABLE_REACT_RENDERER=true`
+  enables a separate sandboxed frame with frame-scoped CSP for JSX transform and
+  execution.
 
 ## Metadata
 
@@ -63,6 +83,11 @@ Metadata is free-form JSON, but converter-generated metadata uses these keys:
 - `originalPayloadShape`: original payload family, such as `gemini-llmContent`, `content`, or `artifact-bundle`.
 - `assetPolicy`: how embedded assets were preserved.
 - `bundlePolicy`: how bundled files were preserved.
+- `language`: source language for code or component artifacts when supplied by an
+  upstream agent.
+- `codexContinuation`: structured Codex handoff metadata such as changed files,
+  commands, tests, blockers, decisions, next steps, findings, diff text, and
+  residual risk.
 
 ## Archive Semantics
 

package/docs/integrations.md

@@ -10,9 +10,39 @@ npm start
 
 The dashboard prefers `http://127.0.0.1:8787`. If that port is busy and no explicit port is configured, the server starts on the next available local port and records the actual URL in the store. The store defaults to `~/.artifacty`; set `ARTIFACTY_HOME` to share a different local directory.
 
+Use a generated startup token when running a protected foreground server:
+
+```bash
+node src/cli.js serve --generate-token
+node src/cli.js serve --host 0.0.0.0 --share-mode lan --generate-token
+npm start -- --generate-token
+```
+
+The generated token is printed with ready-to-open create and import URLs.
+
+For prompt-friendly local background runs, use the lifecycle commands:
+
+```bash
+node src/cli.js start --port 8787
+node src/cli.js status
+node src/cli.js stop
+```
+
+`serve --detach` uses the same detached-process path as `start`. It writes `server.pid`, `server.json`, and logs under `ARTIFACTY_HOME` (default `~/.artifacty`). Prefer `start --api-token "$(node src/cli.js token --raw)"` when a background server needs API protection, because generated startup tokens are only visible in the server log.
+
+The lifecycle commands are intended to be cross-platform:
+
+- macOS and Linux: `stop` signals the detached process group first, then falls back to the server process id.
+- Windows: `start` hides the child console window, and `stop` uses `taskkill /PID <pid> /T`; `--force` adds `/F`.
+- All platforms: `status` combines the managed pid file with the HTTP `/health` endpoint, so a stale pid alone is not reported as healthy.
+
+For login/startup persistence, use the operating system's service manager. Artifacty's `service` command currently generates a macOS LaunchAgent plist; Linux systemd user units and Windows Task Scheduler/Service wrappers should be configured explicitly until first-class installers are added.
+
 Create artifacts directly in the browser at `http://127.0.0.1:8787/new`.
 
-The browser create/import/edit screens use CodeMirror 6 for Markdown, HTML, JSON, and plain text editing. Editor assets are served from local npm dependencies through `/assets/editor.js` and allowlisted `/vendor/npm/*` module routes.
+For LAN or VPN sharing, keep the default local binding unless you intentionally need another machine to reach the server. See [network-sharing.md](network-sharing.md) before using `--host 0.0.0.0`.
+
+The browser create/import/edit screens use CodeMirror 6 for Markdown, HTML, JSON, source-like text, SVG, Mermaid, and React artifact editing. Editor and renderer assets are served from local npm dependencies through `/assets/*.js` and allowlisted `/vendor/npm/*` module routes. For sandboxed iframe imports, `Origin: null` requests receive `Access-Control-Allow-Origin: null`, which lets opaque-origin iframes import local ESM without `allow-same-origin`.
 
 The browser UI defaults to English. Add `?lang=ko` to browser routes to use Korean UI labels; API and MCP payloads are not localized.
 
@@ -28,7 +58,7 @@ Useful environment variables:
 
 - `ARTIFACTY_HOME`: store directory, shared by all agents.
 - `ARTIFACTY_URL`: optional browser URL override. Leave it unset to let MCP read the last running server URL from `server.json`.
-- `ARTIFACTY_API_TOKEN`: required token for HTTP API routes when configured.
+- `ARTIFACTY_API_TOKEN`: required token for HTTP API routes when configured. Generate one with `node src/cli.js token --raw`.
 - `ARTIFACTY_SHARE_MODE`: set to `lan` or `team` before binding outside localhost.
 - `ARTIFACTY_ALLOW_SECRETS`: set to `true` only when intentionally storing detected secrets.
 
@@ -44,12 +74,22 @@ node src/cli.js install all
 node src/cli.js check
 ```
 
-- Claude: writes project `.mcp.json`.
-- Codex: writes or replaces the `[mcp_servers.artifacty]` block in `~/.codex/config.toml` unless `--config` is provided.
-- Gemini: writes project `.gemini/settings.json`.
+- Claude: writes project `.mcp.json`. Claude Code's startup timeout is controlled by the parent `MCP_TIMEOUT` environment variable and defaults to 30 seconds, so Artifacty does not add a per-server `.mcp.json` `timeout` field.
+- Codex: writes or replaces the `[mcp_servers.artifacty]` block in `~/.codex/config.toml` unless `--config` is provided. The generated block uses a 30 second startup timeout so slower Windows or cold-start environments can load the MCP server reliably.
+- Gemini: writes project `.gemini/settings.json` with a 30 second timeout.
 - `--dry-run` returns the generated config without writing it.
+- `--timeout <ms>` adjusts Codex `startup_timeout_sec` and Gemini `timeout`. It does not change Claude Code startup behavior; set `MCP_TIMEOUT` before launching Claude Code if you need a larger value there.
 - `check` starts the local MCP server and verifies required tools through `initialize` and `tools/list`.
 
+Generate a token for protected HTTP routes:
+
+```bash
+node src/cli.js token
+node src/cli.js serve --generate-token
+npm start -- --generate-token
+ARTIFACTY_API_TOKEN="$(node src/cli.js token --raw)" node src/cli.js serve
+```
+
 ## Claude Code
 
 Manual local stdio MCP server:
@@ -76,6 +116,11 @@ Project-scoped `.mcp.json` shape:
 
 Claude plugins can bundle MCP servers, so this MCP server can later be wrapped as a plugin. The MVP keeps the server standalone so Claude, Codex, Gemini, and other MCP clients use the same integration surface.
 
+Claude Code uses a 30 second MCP startup timeout by default. If a slower
+environment needs more time, launch Claude Code with a larger `MCP_TIMEOUT`
+value, for example `MCP_TIMEOUT=45000 claude`. Do not add a `.mcp.json`
+`timeout` field for startup; that field is for tool execution timeout.
+
 ## Codex
 
 Add a local MCP server entry to the Codex config:
@@ -84,12 +129,32 @@ Add a local MCP server entry to the Codex config:
 [mcp_servers.artifacty]
 command = "node"
 args = ["/path/to/artifacty/src/mcp-server.js"]
-startup_timeout_sec = 5.0
+startup_timeout_sec = 30.0
 env = { ARTIFACTY_HOME = "/absolute/path/to/artifacty-store" }
 ```
 
 Restart the Codex session after editing config so the MCP server is loaded.
 
+Codex can publish continuation artifacts directly through MCP. Prefer explicit
+`sourceAgent: "codex"` and an `artifactType` when the content is already
+Markdown:
+
+```json
+{
+  "title": "Implementation Handoff",
+  "content": "# Handoff\n\n- Continue Phase 3.",
+  "format": "markdown",
+  "artifactType": "handoff",
+  "sourceAgent": "codex",
+  "tags": ["handoff"]
+}
+```
+
+For structured continuation payloads, use `artifacty_import` with `agent:
+"codex"`. Artifacty converts handoffs, file bundles, diff walkthroughs, code
+reviews, and verification reports into the shared schema while preserving
+changed files, commands, tests, blockers, and next steps in metadata.
+
 ## Gemini CLI
 
 Add a server to `~/.gemini/settings.json` or `.gemini/settings.json`:
@@ -134,13 +199,14 @@ Use `artifacty_import` or the CLI `import` command when the artifact was produce
 ```bash
 node src/cli.js import --agent claude --file ./artifact.html --tag review
 node src/cli.js import --agent codex --file ./handoff.md --tag handoff
+node src/cli.js import --agent codex --content '{"agent":"codex","title":"Verification","verification":{"status":"passed","commands":[{"command":"npm test","status":"passed"}]}}'
 node src/cli.js import --agent gemini --content '{"title":"Options","returnDisplay":"# Options\n- A\n- B"}'
 ```
 
 Supported converter inputs:
 
-- Claude: local `.html`, `.htm`, `.md`, or JSON payloads with `title`/`content`.
-- Codex: markdown/text/json handoff files, or JSON payloads with `title`, `content`, `format`, `sourceAgent`, and `tags`.
+- Claude: local `.html`, `.htm`, `.md`, `.svg`, `.mmd`, `.jsx`, `.tsx`, source files, or JSON payloads with `title`/`content`/Claude artifact `type`.
+- Codex: markdown/text/json handoff files; Artifacty-compatible JSON payloads; structured handoff, bundle, diff, review, and verification JSON payloads with `agent` or `sourceAgent` set to `codex`.
 - Gemini: `returnDisplay`, `llmContent`, text blocks, or local markdown/text/json files.
 - Generic: file extension, content type, HTML doctype, JSON shape, and markdown headings are used to infer format and title.
 
@@ -163,6 +229,7 @@ The converter adds `imported` and source-agent tags, preserves the raw content a
 - `POST /api/artifacts/:id/restore`: restore an archived artifact.
 - `GET /api/audit`: list recent audit events, optionally filtered by `artifactId`.
 - `GET /artifacts/:id`: browser viewer.
+- `GET /artifacts/:id/react-frame?version=n`: gated React renderer frame. Returns content only when `ARTIFACTY_ENABLE_REACT_RENDERER=true`.
 - `GET /artifacts/:id/edit`: browser version editor.
 - `POST /artifacts/:id/edit`: append a version from the browser editor.
 - `POST /artifacts/:id/archive`: archive from the browser.
@@ -172,6 +239,13 @@ The converter adds `imported` and source-agent tags, preserves the raw content a
 
 When `ARTIFACTY_API_TOKEN` is configured, `/api/*` routes require either `Authorization: Bearer <token>` or `x-artifacty-token: <token>`. Browser forms can also carry `?token=<token>` in the URL, which is copied to hidden form fields for local team workflows.
 
+Renderer notes:
+
+- `code` artifacts use a read-only CodeMirror viewer with escaped source fallback.
+- `svg` artifacts render in a scriptless sandboxed iframe after viewer-side sanitization; `/raw` still returns the original SVG.
+- `mermaid` artifacts load the vendored local Mermaid bundle from `/vendor/npm/mermaid/...` in a sandboxed iframe without `allow-same-origin`. The JavaScript asset route answers the iframe's `Origin: null` module request with `Access-Control-Allow-Origin: null`.
+- `react` artifacts are source-only unless `ARTIFACTY_ENABLE_REACT_RENDERER=true` is set. When enabled, JSX transformation and React execution happen only in `/artifacts/:id/react-frame`, with `unsafe-eval` scoped to that frame CSP.
+
 ## Background Service
 
 Generate or install a macOS LaunchAgent plist:
@@ -184,6 +258,8 @@ node src/cli.js service install
 
 The generated service runs `src/server.js` with explicit `--host` and `--home` arguments. It includes `--port` only when you configure a port, which keeps the default port fallback available. Load or unload it manually with the `launchctl` commands returned by `service install`.
 
+For background services, prefer a stable `ARTIFACTY_API_TOKEN` in the service environment. `serve --generate-token` is intended for foreground runs where the operator can read the generated token from startup output.
+
 ## Backup and Audit
 
 ```bash

package/docs/network-sharing.md

@@ -0,0 +1,41 @@
+# Network Sharing
+
+Artifacty is local-first. The default server binds to `127.0.0.1` and is intended for a single machine. Binding to a non-local address is supported for short, intentional sharing sessions, but it increases the exposed surface area.
+
+## Recommended Defaults
+
+Use the local server for normal work:
+
+```bash
+artifacty serve
+```
+
+If another device on a trusted LAN or private VPN needs read access, prefer binding to a specific interface address instead of every interface:
+
+```bash
+artifacty serve --host 192.168.1.20 --share-mode lan --generate-token
+```
+
+Use `0.0.0.0` only when you intentionally want Artifacty to listen on every network interface:
+
+```bash
+artifacty serve --host 0.0.0.0 --share-mode lan --generate-token
+```
+
+## Required Safeguards
+
+Non-local hosts require both `ARTIFACTY_SHARE_MODE=lan|team` and an API token. This prevents accidentally exposing an unauthenticated Artifacty server.
+
+The generated token protects HTTP API routes and browser write forms. Prefer the `x-artifacty-token` or `Authorization: Bearer <token>` header for scripts. URLs with `?token=...` are convenient for local foreground sessions, but can be stored in browser history, shell history, reverse-proxy logs, or referrers.
+
+Artifacty does not terminate TLS. Do not expose it directly on the public internet. If a shared instance must cross an untrusted network, put it behind a TLS reverse proxy or a private VPN.
+
+## Browser Write Behavior
+
+Remote browsers can read shared pages, but write actions are intentionally conservative. Mutating browser routes reject non-local `Origin` headers to reduce CSRF risk. For LAN sharing, prefer API or MCP writes with an explicit token header.
+
+Do not relax the origin check just to make remote browser writes easier. A future team dashboard should use a dedicated policy that combines same-origin remote requests, explicit token validation, and clear operator intent.
+
+## Renderer Guidance
+
+Artifact content is untrusted. HTML, SVG, Mermaid, and React artifacts are rendered with sandboxing and CSP controls, but shared viewing still means content reaches another user's browser. Keep `ARTIFACTY_ENABLE_REACT_RENDERER` disabled for LAN sessions unless every viewer trusts the artifact source.

package/docs/release-checklist.md

@@ -14,6 +14,9 @@ This runs syntax checks, the full Node test suite, and a local smoke test that s
 
 - Confirm `package.json` `version` and `files` are intentional.
 - Run `npm pack --dry-run` and inspect the included paths.
+- Review package size after renderer dependencies. Mermaid is a default dependency;
+  React, ReactDOM, and Babel standalone are optional dependencies used only by the
+  gated React renderer.
 - Verify the global commands resolve after install: `artifacty`, `artifacty-mcp`.
 
 ## Security
@@ -22,6 +25,16 @@ This runs syntax checks, the full Node test suite, and a local smoke test that s
 - Require `ARTIFACTY_API_TOKEN` and `ARTIFACTY_SHARE_MODE=lan` or `team` before binding to `0.0.0.0`.
 - Review secret-scan bypasses. `--allow-secrets` and `ARTIFACTY_ALLOW_SECRETS=true` should be deliberate and temporary.
 - Treat artifact HTML and imported agent payloads as untrusted content.
+- Confirm scripted artifact iframes never include `allow-same-origin`.
+- Confirm `/assets/*` and `/vendor/npm/*` JavaScript responses return
+  `Access-Control-Allow-Origin: null` only for `Origin: null` requests, so
+  opaque-origin sandbox iframes can import local ESM without weakening sandbox
+  flags or using a wildcard CORS policy.
+- Confirm SVG viewer output strips `<script>`, `on*` attributes, and `javascript:` links while `/raw` preserves original source.
+- Browser-smoke each renderer that executes client code. Route status alone does
+  not prove Mermaid or React rendered inside the iframe.
+- Keep `ARTIFACTY_ENABLE_REACT_RENDERER` disabled by default. Enable it only when the operator accepts arbitrary component execution risk.
+- Confirm parent app CSP does not include `unsafe-eval`; it should appear only on the React frame response CSP.
 
 ## Operations
 

package/docs/sarif-csv-artifact-plan.md

@@ -0,0 +1,65 @@
+# SARIF and CSV Artifact Support Plan
+
+This plan scopes SARIF and CSV support to **output artifacts** that Codex or
+other agents generate for downstream review. It does not cover Codex input
+context, appshots, thread state, or client-specific UI state.
+
+## Goals
+
+- Preserve SARIF and CSV files as immutable Artifacty versions.
+- Classify common Codex Security exports without requiring manual
+  `artifactType` overrides.
+- Render CSV outputs in a readable table view while keeping `/raw` unchanged.
+- Keep SARIF as JSON-first, with future room for a findings-focused viewer.
+
+## Current Behavior
+
+- `.sarif` content is stored as `json` when the payload is valid JSON, but it
+  currently falls back to `artifactType: "unknown"`.
+- `.csv` and `text/csv` content can be stored as `text`, but there is no CSV
+  detection, table renderer, or artifact-type inference.
+- Security findings exported as JSON, CSV, or SARIF can be shared today, but the
+  browsing experience is not yet tailored to review workflows.
+
+## Phase 1: Detection and Taxonomy
+
+- Detect `.sarif` and `application/sarif+json` as `json`.
+- Detect SARIF shape (`version`, `runs[]`, `tool.driver`) and classify as
+  `code-review`.
+- Detect `.csv` and `text/csv` as either a new `csv` format or `text` with
+  `metadata.delimitedText`.
+- Infer `code-review` for CSV/SARIF files named like `findings`, `security`,
+  `review`, or containing columns such as `severity`, `file`, and `message`.
+
+Exit criteria: CLI, HTTP, and MCP imports classify SARIF and common findings CSV
+without explicit overrides.
+
+## Phase 2: CSV Viewer
+
+- Add a lightweight RFC 4180-style CSV parser for browser rendering.
+- Render CSV as a scrollable table with sticky headers and escaped cell content.
+- Cap rendered rows and columns for very large files, with a visible truncation
+  notice and a link to `/raw`.
+- Preserve plain text fallback when parsing fails.
+
+Exit criteria: CSV artifacts are readable in the browser and raw fidelity is
+unchanged.
+
+## Phase 3: SARIF Summary Viewer
+
+- Keep SARIF source as JSON.
+- Add an optional summary above the JSON view: rule id, severity/level, message,
+  file URI, region, and result count by level.
+- Avoid implementing the complete SARIF spec in v1; parse only stable top-level
+  fields and fail closed to JSON rendering.
+
+Exit criteria: SARIF exports are useful for quick triage while preserving the
+full JSON source.
+
+## Tests
+
+- Converter fixtures: Codex Security SARIF, findings CSV, generic CSV, malformed
+  CSV, and large CSV.
+- Storage round trips: content type, extension, size, hash, and `/raw` fidelity.
+- Server rendering: CSV table escaping, truncation notice, SARIF summary fallback.
+- MCP schema and import tests for explicit and inferred artifact types.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artifacty",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Local artifact exchange for heterogeneous LLM agents via HTTP and MCP.",
   "type": "module",
   "keywords": [
@@ -34,7 +34,12 @@
   },
   "files": [
     "src",
-    "docs",
+    "docs/artifact-schema-v1.md",
+    "docs/assets/artifacty.png",
+    "docs/integrations.md",
+    "docs/network-sharing.md",
+    "docs/release-checklist.md",
+    "docs/sarif-csv-artifact-plan.md",
     "scripts/smoke.sh",
     "README.md",
     "LICENSE",
@@ -48,8 +53,15 @@
   "license": "MIT",
   "dependencies": {
     "@codemirror/lang-html": "^6.4.11",
+    "@codemirror/lang-javascript": "^6.2.5",
     "@codemirror/lang-json": "^6.0.2",
     "@codemirror/lang-markdown": "^6.5.0",
-    "codemirror": "^6.0.2"
+    "codemirror": "^6.0.2",
+    "mermaid": "^11.15.0"
+  },
+  "optionalDependencies": {
+    "@babel/standalone": "^7.29.7",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
   }
 }