artifacty 0.1.0

package/AGENTS.md

@@ -0,0 +1,52 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+Artifacty shares LLM artifacts over HTTP, CLI, and MCP.
+
+- `src/server.js`: localhost HTTP server, browser routes, and JSON API.
+- `src/mcp-server.js`: MCP stdio server exposing Artifacty tools.
+- `src/cli.js`: command-line interface for serving, publishing, importing, listing, and reading artifacts.
+- `src/lib/storage.js`: SQLite metadata store and immutable version-file handling.
+- `src/lib/converters.js`: agent artifact conversion rules for Claude, Codex, Gemini, and generic payloads.
+- `src/lib/installer.js`: MCP config installers for Claude, Codex, and Gemini.
+- `src/lib/render.js`: server-rendered dashboard, viewer, and editor HTML.
+- `test/*.test.js`: Node test runner suites.
+- `docs/integrations.md`: setup notes for Claude Code, Codex, and Gemini CLI.
+
+## Build, Test, and Development Commands
+
+- `npm start`: run the HTTP dashboard on `127.0.0.1:8787`.
+- `npm test`: run all tests with Node’s built-in test runner.
+- `npm run lint`: syntax-check source and test files with `node --check`.
+- `node src/mcp-server.js`: run the MCP stdio server.
+- `node src/cli.js import --agent claude --file artifact.html`: convert and store an external artifact.
+- `node src/cli.js install claude --dry-run`: preview generated MCP config.
+- `node src/cli.js check`: verify MCP tool discovery.
+
+## Coding Style & Naming Conventions
+
+Use modern ESM JavaScript and Node built-ins where practical. Keep modules small and route shared behavior through `src/lib/*` instead of duplicating logic in CLI, HTTP, and MCP layers. Use two-space indentation, semicolons only where already present, `camelCase` for functions and variables, and descriptive tool names such as `artifacty_create`.
+
+Do not add new dependencies unless the operational value clearly outweighs the extra install and security surface.
+
+## Testing Guidelines
+
+Use `node:test` and `node:assert/strict`. Name tests `*.test.js` and keep them close to verified behavior: storage, converters, installers, HTTP routes, and MCP protocol flow. Add regression tests for every new artifact format, route, tool, installer, migration, or storage behavior. Run `npm run lint` and `npm test` before reporting completion.
+
+## Commit & Pull Request Guidelines
+
+This repository has no existing Git history to infer from. Use concise, intent-first commit messages, and include useful trailers when relevant:
+
+```text
+Add MCP artifact creation tool
+
+Tested: npm test
+Scope-risk: narrow
+```
+
+PRs should explain behavior, changed surfaces, verification, and security or compatibility risks.
+
+## Security & Configuration Tips
+
+Artifact content is untrusted. HTML renders in a sandboxed iframe, and the server binds to localhost by default. Keep `ARTIFACTY_HOME` private unless intentionally sharing a store, and avoid exposing the HTTP server on `0.0.0.0` without authentication.

package/CLAUDE.md

@@ -0,0 +1,64 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with this repository.
+
+Artifacty is a local, agent-to-agent artifact exchange for LLM workflows. One agent publishes an artifact once; others list, read, import, update, and continue from it without copying content through chat. It exposes one shared store over HTTP/browser, CLI, and MCP stdio surfaces.
+
+See `AGENTS.md` for repository structure, coding-style conventions, and commit/PR guidelines.
+
+## Commands
+
+- `npm test` — run all tests with `node --test`.
+- `npm run lint` — syntax-check source and tests with `node --check`.
+- `npm run smoke` — start a temporary token-protected server and verify core HTTP, backup, and MCP behavior.
+- `npm run release:check` — run lint, tests, and smoke together.
+- `npm start` — run the HTTP dashboard. It prefers `127.0.0.1:8787` and falls back when the default port is busy.
+- `node src/mcp-server.js` or `npm run mcp` — run the MCP stdio server.
+- `node src/cli.js help` — inspect CLI usage.
+
+Run `npm run release:check` before claiming a release-ready change. There is no build step; this is plain ESM run directly by Node `>=22.5`.
+
+## Architecture
+
+### Shared Library Funnel
+
+The three entry points are thin adapters:
+
+- `src/server.js` handles HTTP/browser routes and JSON API.
+- `src/cli.js` handles command-line workflows.
+- `src/mcp-server.js` handles MCP JSON-RPC over stdio.
+
+Shared behavior belongs in `src/lib/*`. Storage logic lives in `src/lib/storage.js`, conversion logic in `src/lib/converters.js`, installer logic in `src/lib/installer.js`, security checks in `src/lib/security.js`, and server URL discovery in `src/lib/server-state.js`.
+
+### Storage Model
+
+The store lives at `ARTIFACTY_HOME` or `~/.artifacty` by default.
+
+- SQLite metadata is stored in `artifacty.sqlite`.
+- Immutable version files are stored under `artifacts/<id>/v<n>.<ext>`.
+- `server.json` records the currently running browser server URL so CLI and MCP responses keep working when the default port falls back.
+- Legacy `index.json` stores migrate automatically on first access.
+
+Versions are append-only. Do not mutate prior content files.
+
+### Security Model
+
+- The HTTP server binds to `127.0.0.1` by default.
+- Non-local bind addresses require `ARTIFACTY_SHARE_MODE=lan` or `team` plus `ARTIFACTY_API_TOKEN`.
+- API routes require token auth when `ARTIFACTY_API_TOKEN` is configured.
+- Storage rejects common secret patterns before persisting content unless an explicit allow flag is used.
+- HTML artifacts render in sandboxed iframes and must remain treated as untrusted.
+
+### Browser Editor
+
+The create/import/edit screens use CodeMirror 6 for Markdown, HTML, JSON, and text editing. CodeMirror assets are served locally through allowlisted `/vendor/npm/*` routes, not from a CDN. UI text defaults to English and supports Korean with `?lang=ko`; documentation stays English-only.
+
+### MCP Server
+
+The MCP server is a hand-rolled line-delimited JSON-RPC 2.0 implementation using protocol version `2025-06-18`. Tool results include both `content[].text` and `structuredContent`. Keep `artifacty_publish` as a backwards-compatible alias for `artifacty_create`.
+
+When `ARTIFACTY_URL` is unset, MCP reads the current browser URL from `server.json`. Do not reintroduce a hard-coded `http://127.0.0.1:8787` default into generated MCP configs.
+
+### Tests
+
+Tests use `node:test` and `node:assert/strict`. Add regression tests for every new route, CLI command, MCP tool, converter behavior, security rule, migration, or storage change. Keep tests isolated with temporary stores and cleanup in `finally`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raeseok Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# Artifacty
+
+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)
+
+## Why MCP
+
+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
+
+Install and start Artifacty:
+
+```bash
+npm install -g artifacty
+artifacty serve
+```
+
+For local development from a checkout:
+
+```bash
+npm install
+npm test
+npm start
+```
+
+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:
+
+```bash
+npm run release:check
+```
+
+Create an artifact in the browser:
+
+```text
+http://127.0.0.1:8787/new
+```
+
+Publish from the CLI:
+
+```bash
+node src/cli.js 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"}'
+```
+
+List artifacts:
+
+```bash
+node src/cli.js list
+```
+
+Run the MCP server:
+
+```bash
+node src/mcp-server.js
+```
+
+MCP clients can create artifacts with `artifacty_create`. `artifacty_publish` remains as a backwards-compatible alias.
+
+Install MCP configuration for local agents:
+
+```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
+```
+
+See [docs/integrations.md](docs/integrations.md) for Claude Code, Codex, and Gemini CLI setup.
+
+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
+```
+
+After global installation, the same commands are available as `artifacty` and `artifacty-mcp`.
+
+## Storage
+
+By default Artifacty stores files under `~/.artifacty`.
+
+```bash
+ARTIFACTY_HOME=/path/to/shared/store npm start
+```
+
+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
+
+```bash
+curl -s http://127.0.0.1:8787/api/artifacts \
+  -H 'content-type: application/json' \
+  -H "x-artifacty-token: $ARTIFACTY_API_TOKEN" \
+  -d '{
+    "title": "PR review dashboard",
+    "content": "<h1>Review</h1>",
+    "format": "html",
+    "sourceAgent": "claude",
+    "tags": ["review"]
+  }'
+```
+
+Convert-and-save an external agent artifact:
+
+```bash
+curl -s http://127.0.0.1:8787/api/import \
+  -H 'content-type: application/json' \
+  -H "x-artifacty-token: $ARTIFACTY_API_TOKEN" \
+  -d '{
+    "agent": "claude",
+    "fileName": "deploy-failures.html",
+    "content": "<html><head><title>Deploy failures</title></head><body>...</body></html>",
+    "tags": ["review"]
+  }'
+```
+
+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/diff`: compare versions.
+- `/api/audit`: list audit events.
+
+## Interface Language
+
+The browser UI defaults to English. Add `?lang=ko` to any browser route to use Korean, for example `http://127.0.0.1:8787/new?lang=ko`. Forms and in-app links preserve the selected language. Documentation is maintained in English only.
+
+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.
+- See [docs/artifact-schema-v1.md](docs/artifact-schema-v1.md).
+
+## 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`.
+- 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.
+- Mutating HTTP routes reject non-local browser origins.
+- HTML artifacts render in a sandboxed iframe.
+- 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/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,8 @@
+# Third Party Notices
+
+Artifacty includes CodeMirror 6 packages for the browser editor.
+
+- CodeMirror and `@codemirror/*` packages are distributed under the MIT License.
+- Lezer parser packages used by CodeMirror are distributed under the MIT License.
+
+The installed package metadata and license files are retained through npm dependency installation.

package/docs/artifact-schema-v1.md

@@ -0,0 +1,96 @@
+# Artifact Schema v1
+
+Artifacty schema v1 defines the stable envelope shared by HTTP, CLI, MCP, converters, and SQLite storage.
+
+## Artifact Record
+
+```json
+{
+  "id": "artifact-id",
+  "schemaVersion": 1,
+  "artifactType": "document",
+  "title": "Readable title",
+  "sourceAgent": "codex",
+  "tags": ["handoff"],
+  "createdAt": "2026-06-24T00:00:00.000Z",
+  "updatedAt": "2026-06-24T00:00:00.000Z",
+  "archivedAt": null,
+  "latestVersion": 1,
+  "versions": []
+}
+```
+
+Allowed `artifactType` values:
+
+- `document`
+- `html-page`
+- `handoff`
+- `code-review`
+- `test-report`
+- `dashboard`
+- `design-option`
+- `diff-walkthrough`
+- `bundle`
+- `asset`
+- `unknown`
+
+Unknown legacy or external types should be mapped to `unknown`, not rejected during conversion. Native create/update rejects unsupported explicit types.
+
+## Version Record
+
+Each version is immutable and points at one content file.
+
+```json
+{
+  "version": 1,
+  "createdAt": "2026-06-24T00:00:00.000Z",
+  "format": "markdown",
+  "contentType": "text/markdown; charset=utf-8",
+  "path": "artifacts/id/v1.md",
+  "sizeBytes": 128,
+  "sha256": "...",
+  "metadata": {}
+}
+```
+
+Allowed `format` values are `html`, `markdown`, `text`, and `json`.
+
+## Metadata
+
+Metadata is free-form JSON, but converter-generated metadata uses these keys:
+
+- `artifactyImport`: converter name, original/source agent, file name/path, content type, artifact type, and conversion timestamp.
+- `originalPayloadShape`: original payload family, such as `gemini-llmContent`, `content`, or `artifact-bundle`.
+- `assetPolicy`: how embedded assets were preserved.
+- `bundlePolicy`: how bundled files were preserved.
+
+## Archive Semantics
+
+Artifacts are not deleted by P0 behavior. Archive sets `archivedAt` and hides the artifact from default list results. `includeArchived=true` includes archived records. Restore clears `archivedAt`. Versions and content files remain unchanged.
+
+## Bundle Format
+
+Bundles are JSON artifacts with `artifactType: "bundle"` and content type `application/vnd.artifacty.bundle+json; charset=utf-8`.
+
+```json
+{
+  "schemaVersion": 1,
+  "artifactType": "bundle",
+  "title": "Patch bundle",
+  "files": [
+    {
+      "path": "README.md",
+      "content": "# Readme",
+      "contentType": "text/markdown; charset=utf-8",
+      "sizeBytes": 8,
+      "sha256": "..."
+    }
+  ]
+}
+```
+
+Gemini multimodal payloads use the same bundle type with `parts` and `assets`.
+
+## Asset Policy
+
+Base64 assets are preserved inline inside bundle JSON with `encoding: "base64"`, `mimeType`, `sizeBytes`, and `sha256`. Consumers must treat decoded assets as untrusted. Large binary asset externalization is intentionally deferred; schema v1 keeps all converted assets inspectable and portable.

package/docs/integrations.md

@@ -0,0 +1,196 @@
+# Agent Integration
+
+Artifacty exposes one shared MCP stdio server and one local browser server.
+
+## Start the Browser Server
+
+```bash
+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.
+
+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.
+
+The browser UI defaults to English. Add `?lang=ko` to browser routes to use Korean UI labels; API and MCP payloads are not localized.
+
+## MCP Server Command
+
+Use this stdio command from this repository root:
+
+```bash
+node /path/to/artifacty/src/mcp-server.js
+```
+
+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_SHARE_MODE`: set to `lan` or `team` before binding outside localhost.
+- `ARTIFACTY_ALLOW_SECRETS`: set to `true` only when intentionally storing detected secrets.
+
+## Automatic Install
+
+Artifacty can write MCP configuration for supported local agents:
+
+```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
+```
+
+- 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`.
+- `--dry-run` returns the generated config without writing it.
+- `check` starts the local MCP server and verifies required tools through `initialize` and `tools/list`.
+
+## Claude Code
+
+Manual local stdio MCP server:
+
+```bash
+claude mcp add --transport stdio artifacty -- node /path/to/artifacty/src/mcp-server.js
+```
+
+Project-scoped `.mcp.json` shape:
+
+```json
+{
+  "mcpServers": {
+    "artifacty": {
+      "command": "node",
+      "args": ["/path/to/artifacty/src/mcp-server.js"],
+      "env": {
+        "ARTIFACTY_HOME": "/absolute/path/to/artifacty-store"
+      }
+    }
+  }
+}
+```
+
+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.
+
+## Codex
+
+Add a local MCP server entry to the Codex config:
+
+```toml
+[mcp_servers.artifacty]
+command = "node"
+args = ["/path/to/artifacty/src/mcp-server.js"]
+startup_timeout_sec = 5.0
+env = { ARTIFACTY_HOME = "/absolute/path/to/artifacty-store" }
+```
+
+Restart the Codex session after editing config so the MCP server is loaded.
+
+## Gemini CLI
+
+Add a server to `~/.gemini/settings.json` or `.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "artifacty": {
+      "command": "node",
+      "args": ["/path/to/artifacty/src/mcp-server.js"],
+      "env": {
+        "ARTIFACTY_HOME": "/absolute/path/to/artifacty-store"
+      },
+      "timeout": 30000,
+      "trust": false
+    }
+  }
+}
+```
+
+Then run `/mcp` inside Gemini CLI to confirm that the Artifacty tools are connected.
+
+## MCP Tools
+
+- `artifacty_create`: create a new Artifacty-native artifact.
+- `artifacty_publish`: backwards-compatible alias for `artifacty_create`.
+- `artifacty_import`: convert a Claude, Codex, Gemini, Artifacty, or generic artifact payload into Artifacty format and save it.
+- `artifacty_list`: discover artifacts by query, tag, or source agent.
+- `artifacty_get`: read artifact metadata and content.
+- `artifacty_update`: append a new version.
+- `artifacty_archive`: hide an artifact without deleting versions.
+- `artifacty_restore`: clear archive state.
+- `artifacty_audit`: list recent audit events.
+- `artifacty_info`: inspect local server/store settings.
+
+Mutating MCP tools scan content for common API keys and private keys before storage. Pass `allowSecrets: true` only for intentional exceptions.
+
+## Importing Agent Artifacts
+
+Use `artifacty_import` or the CLI `import` command when the artifact was produced by another agent and needs normalization before sharing.
+
+```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 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`.
+- 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.
+
+The converter adds `imported` and source-agent tags, preserves the raw content as an immutable Artifacty version, and records source details under `metadata.artifactyImport`.
+
+## HTTP API
+
+- `GET /`: dashboard.
+- `GET /new`: browser artifact editor.
+- `POST /new`: create from the browser editor and redirect to the artifact.
+- `GET /import`: browser artifact import form.
+- `POST /import`: convert and save pasted agent output.
+- `GET /health`: health check.
+- `GET /api/artifacts`: list artifacts.
+- `POST /api/artifacts`: create artifact.
+- `POST /api/import`: convert and save an agent-produced artifact.
+- `GET /api/artifacts/:id`: read metadata and content.
+- `POST /api/artifacts/:id`: append a version.
+- `POST /api/artifacts/:id/archive`: archive without deleting versions.
+- `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/edit`: browser version editor.
+- `POST /artifacts/:id/edit`: append a version from the browser editor.
+- `POST /artifacts/:id/archive`: archive from the browser.
+- `POST /artifacts/:id/restore`: restore from the browser.
+- `GET /artifacts/:id/diff`: compare two versions.
+- `GET /artifacts/:id/raw?version=n`: raw content.
+
+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.
+
+## Background Service
+
+Generate or install a macOS LaunchAgent plist:
+
+```bash
+node src/cli.js service plist
+node src/cli.js service install --dry-run
+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`.
+
+## Backup and Audit
+
+```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
+```
+
+Backups include SQLite metadata plus immutable version file contents in one JSON bundle. Importing a store replaces the target store index, so run it against a new or intentionally chosen `ARTIFACTY_HOME`.

package/docs/release-checklist.md

@@ -0,0 +1,30 @@
+# Release Checklist
+
+Use this checklist before publishing or distributing Artifacty.
+
+## Required Verification
+
+```bash
+npm run release:check
+```
+
+This runs syntax checks, the full Node test suite, and a local smoke test that starts the HTTP server with token auth enabled, creates an artifact, verifies secret blocking, reads audit logs, writes a backup, and checks MCP tool discovery.
+
+## Packaging
+
+- Confirm `package.json` `version` and `files` are intentional.
+- Run `npm pack --dry-run` and inspect the included paths.
+- Verify the global commands resolve after install: `artifacty`, `artifacty-mcp`.
+
+## Security
+
+- Keep the default HTTP bind address at `127.0.0.1`.
+- 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.
+
+## Operations
+
+- Export a backup before upgrades: `artifacty backup`.
+- Confirm `artifacty audit --limit 20` shows recent create/update/read/archive events.
+- For macOS background service installs, dry-run first: `artifacty service install --dry-run`.