artifacty 0.11.1 → 0.13.0

package/docs/artifact-schema-v1.md

@@ -1,6 +1,7 @@
 # Artifact Schema v1
 
-Artifacty schema v1 defines the stable envelope shared by HTTP, CLI, MCP, converters, and SQLite storage.
+Artifacty schema v1 defines the stable record structure for HTTP, CLI, MCP,
+converters, and SQLite storage.
 
 ## Artifact Record
 
@@ -45,45 +46,59 @@ Allowed `artifactType` values:
 - `table`
 - `unknown`
 
-Unknown legacy or external types should be mapped to `unknown`, not rejected during conversion. Native create/update rejects unsupported explicit types.
+Converters should map unknown legacy or external types to `unknown`. They should
+not reject those types. Native create and update operations reject unsupported
+explicit types.
 
 `sourceAgent` identifies the tool or model surface that produced the artifact,
 such as `codex` or `claude`. `publisherId` identifies who published it to the
-Artifacty store. For authenticated central servers this is the personal token
-owner's email; `publisherName` and `publisherUserId` are included when the
-server can map the request to a local user record. Legacy artifacts are
-best-effort backfilled from the first `create` or `import` audit actor.
+Artifacty store. On an authenticated central server, this is the personal token
+owner's email. If the server maps the request to a local user record, it also
+includes `publisherName` and `publisherUserId`. For legacy artifacts, the server
+tries to fill these fields from the first `create` or `import` audit actor.
 Known source-agent aliases are canonicalized before storage. For example,
 `claude-code`, `Claude Code`, and `anthropic` become `claude`;
 `github-copilot` becomes `copilot`; and `gemini-cli` becomes `gemini`.
 Existing `unknown` rows are upgraded only when version metadata, audit data, or
 source-agent tags provide one of the known agent identities.
 
-`visibility` is `"private"` or `"team"` (default `"team"`) and `ownerUserId`
-identifies the artifact's owner. Once any user account exists, `team`
-artifacts are readable and writable by any authenticated principal (writes
-can be restricted to the owner or an admin with `ARTIFACTY_TEAM_WRITE=owner`);
-`private` artifacts are readable and writable only by their owner or an
-admin. Archiving, restoring, and changing visibility or ownership always
-require the owner or an admin. In single-user mode (no user accounts) these
-checks do not apply. `ownerUserId` defaults to the creating user (from
-`publisherUserId`) and is backfilled the same way on migration for older
-rows. See the Security Model section of the README for the full rule table.
+`visibility` is `"private"` or `"team"` (default `"team"`). `ownerUserId`
+identifies the owner. In public site mode, `private` artifacts require the owner
+or an administrator through normal artifact routes. Anonymous browser visitors can read `team` artifacts.
+Authenticated principals can write them. API authentication requirements still
+apply. Set `ARTIFACTY_TEAM_WRITE=owner` to restrict these writes to the owner
+or an administrator.
+
+Private site mode requires a personal identity. Owners and administrators retain
+access. Other users need a direct or team grant with read, comment, or edit
+permission. Artifacty applies the strongest matching grant. Archiving, restoring,
+sharing, and changes to visibility or ownership require the owner or an
+administrator in both modes. Token scopes can further restrict access.
+
+Owner-created share links provide a separate read-only access path. In private
+site mode, these links require administrator opt-in. See
+[Public share links](threat-model.md#public-share-links-and-network-restrictions) for their expiry and revocation rules.
+
+In public mode with no user accounts, user access checks do not apply.
+`ownerUserId` defaults to the creating user, from `publisherUserId`. Migration
+uses the same rule to fill this field in older records. See the README Security
+Model section for the full rule table.
 
 `reviewStatus` is one of `none` (default), `pending`, `changes-requested`, or
-`approved`. It is set explicitly via `POST /api/artifacts/:id/review-status`
-(or `artifacty_set_review_status`, or `artifacty review-status`), which
-requires the artifact's owner or an admin, and resets to `pending`
-automatically — noted in that `update` audit row's metadata as
-`reviewStatusReset: { from: "approved", to: "pending" }` — whenever a new
-version is appended after an `approved` status.
+`approved`. The owner or an administrator can set it through
+`POST /api/artifacts/:id/review-status`, `artifacty_set_review_status`, or
+`artifacty review-status`.
+
+If a new version follows an `approved` version, Artifacty resets the status to
+`pending`. The `update` audit row records
+`reviewStatusReset: { from: "approved", to: "pending" }` in its metadata.
 
 ## Version Record
 
-Normal create and update flows append versions, and each version points at one
-content file. Administrator repair/delete actions are exceptional maintenance
-operations for correcting accidental or sensitive historical versions; they
-write `version-repair` or `version-delete` audit events.
+Normal create and update operations append versions. Each version points to one
+content file. Administrators can repair or delete historical versions to correct
+accidental or sensitive content. These exceptional maintenance operations write
+`version-repair` or `version-delete` audit events.
 
 ```json
 {
@@ -107,8 +122,8 @@ Common `artifactType` values include `document`, `handoff`, `code-review`,
 
 ## Renderer Policy
 
-Storage preserves artifact source as immutable content. Browser rendering is a
-viewer concern and must treat all source as untrusted:
+Storage preserves artifact source as immutable content. The browser viewer must
+treat all source as untrusted:
 
 - `code`: read-only CodeMirror viewer with escaped source fallback.
 - `svg`: scriptless sandboxed iframe after viewer-side sanitization; `/raw`
@@ -197,10 +212,10 @@ updated. `getArtifact` responses include:
 }
 ```
 
-`artifact` is a summary of the other side of the link, or `null` with
-`missing: true` when the target artifact no longer exists — a dangling
-relation is reported, not silently dropped. Self-links (`fromId === toId`) and
-relation names outside the closed set are rejected.
+`artifact` contains a summary of the linked artifact. If the target no longer
+exists, `artifact` is `null` and `missing` is `true`. The response keeps the
+dangling relation. Artifacty rejects self-links (`fromId === toId`) and relation
+names outside the closed set.
 
 `GET /api/artifacts` and `artifacty_list` accept `relatedTo=<id>` (and
 optionally `relation=<name>`) to restrict results to artifacts linked, in
@@ -233,23 +248,24 @@ Comments are lightweight, version-anchored notes stored in an
 ```
 
 - `version` defaults to the artifact's `latestVersion` when omitted.
-- `body` is Markdown, rendered through the same sanitized Markdown pipeline as
-  markdown-format artifact content, and capped at 16 KB (`MAX_COMMENT_BYTES`).
+- `body` is Markdown with a 16 KB limit (`MAX_COMMENT_BYTES`). The viewer uses
+  the same sanitized Markdown renderer as markdown-format artifacts.
 - `anchor` is optional and format-specific — `{ "line": 42 }` for text
   formats, `{ "path": "$.runs[0].results[3]" }` for JSON/SARIF, `{ "row": 7 }`
   for CSV — and is a rendering hint only, not validated against the
   artifact's actual content.
-- Threads are one level deep: `parentId`, when set, must point to a comment
-  that itself has no `parentId` (a root comment); replying to a reply is
-  rejected with `code: "THREAD_TOO_DEEP"`.
+- Threads are one level deep. If supplied, `parentId` must identify a root
+  comment, which has no `parentId`. A reply to another reply returns
+  `code: "THREAD_TOO_DEEP"`.
 - `status` is `"open"` or `"resolved"`, set via the resolve action
   (`resolvedAt`/`resolvedBy` are then populated).
-- Deleting a comment is a soft delete: `deletedAt` is set and the row is
-  hidden from `listComments`/`GET .../comments` by default (pass
-  `includeDeleted: true` to see it), but the comment row and its
-  `comment-delete` audit-log entry are both kept.
-- Comments on a `private` artifact are readable and writable under the same
-  owner/admin rules as the artifact itself (see Visibility above).
+- Comment deletion is a soft delete. Artifacty sets `deletedAt` and hides the
+  row from `listComments` and `GET .../comments` by default. Pass
+  `includeDeleted: true` to include it. Artifacty keeps the comment row and its
+  `comment-delete` audit entry.
+- Comment reads require access to the artifact. In private site mode, new
+  comments require comment or edit permission, or the owner or administrator
+  role. Comment grants allow users to resolve their own comments.
 - `author_label` is derived from the caller's audit context (the
   authenticated user's display name/email, falling back to the publisher id,
   the `sourceAgent`, or `"anonymous"`).
@@ -264,11 +280,16 @@ no HTTP equivalent flag — fetch `GET /api/artifacts/:id/comments` separately).
 
 ## 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`. Regular archive/restore leaves versions and content files unchanged. Administrators may repair or delete individual versions from `/admin/artifacts/:id/versions`; the last remaining version cannot be deleted.
+Archive sets `archivedAt` and hides the artifact from default list results.
+Use `includeArchived=true` to include archived records. Restore clears
+`archivedAt`. Normal archive and restore operations do not delete artifacts or
+change version files. Administrators may repair or delete individual versions
+from `/admin/artifacts/:id/versions`. They cannot delete the last version.
 
 ## Bundle Format
 
-Bundles are JSON artifacts with `artifactType: "bundle"` and content type `application/vnd.artifacty.bundle+json; charset=utf-8`.
+Bundles are JSON artifacts with `artifactType: "bundle"`. Their content type is
+`application/vnd.artifacty.bundle+json; charset=utf-8`.
 
 ```json
 {
@@ -329,14 +350,16 @@ The viewer renders PDF entries in a sandboxed iframe (no `allow-same-origin`,
 no scripts) pointing at `GET /artifacts/:id/raw?file=<path>`; other document
 types show metadata and a download link to the same route. That route
 responds with the entry's `contentType`, `X-Content-Type-Options: nosniff`,
-`Cache-Control: private`, and `Content-Disposition: inline` for PDFs or
-`attachment` otherwise. It honors the same `access` rules as other artifact
-reads (private-artifact non-owners get 404), and returns 404 for an unknown
-`file` name.
+`Cache-Control: no-store`, and `Content-Disposition: inline` for PDFs or
+`attachment` otherwise. It applies the same `access` rules as other artifact
+reads. It returns 404 when the caller cannot read the artifact or the `file`
+name is unknown.
 
 ## Asset Policy
 
-Base64 assets are preserved inline inside bundle JSON with `encoding: "base64"`, `mimeType`, `sizeBytes`, and `sha256`. Consumers must treat decoded assets as untrusted.
+Bundle JSON preserves base64 assets inline. Each asset has `encoding: "base64"`,
+`mimeType`, `sizeBytes`, and `sha256`. Consumers must treat decoded assets as
+untrusted.
 
 First-class `image` and `video` artifacts store base64 content in the immutable
 version file. Importers should set `metadata.encoding: "base64"` and

package/docs/central-team-deployment-design.md

@@ -1,21 +1,22 @@
 # Central Team Deployment Design
 
-This document defines the design for running Artifacty as a shared internal
-service, where many users connect Claude Code, Codex, Gemini, GitHub Copilot,
-Cursor, or another MCP client to one central Artifacty server.
+This document defines the design for a shared internal Artifacty service.
+Users connect Claude Code, Codex, Gemini, GitHub Copilot, Cursor, or another MCP
+client to one central Artifacty server.
 
 ## Problem
 
-Artifacty is local-first by default. The HTTP server can listen on a LAN
-address, and the MCP server can either read and write the local `ARTIFACTY_HOME`
-store directly or run as a stdio bridge to a central `/mcp` endpoint. The
-installer `--url` option only controls the browser URL returned in MCP
-responses; central MCP mode is selected with `--mcp-url`.
+Artifacty uses a local store by default. The HTTP server can listen on a LAN
+address. The MCP server can read and write the local `ARTIFACTY_HOME` store
+directly. It can also run as a stdio bridge to a central `/mcp` endpoint.
+
+The installer `--url` option controls only the browser URL in MCP responses.
+Use `--mcp-url` to select central MCP mode.
 
 For a central deployment, every MCP client must write through the central
-service instead of touching local SQLite or shared network files. The preferred
-central surface is the native HTTP `/mcp` endpoint. A local stdio bridge remains
-the default installer path for broad client compatibility.
+service. Clients must not write to local SQLite or shared network files. Use
+the native HTTP `/mcp` endpoint when the client supports it. The installer
+uses a local stdio bridge by default for compatibility with more clients.
 
 ## Goals
 
@@ -24,9 +25,10 @@ the default installer path for broad client compatibility.
 - Per-user local stdio bridge compatibility for clients that only support local
   stdio MCP configuration.
 - Stable install commands that can target a central server.
-- Token-authenticated HTTP writes with no token leakage through query strings.
+- HTTP writes authenticated by tokens. Query strings must not contain tokens.
 - Clear audit attribution for user, agent, host, and client surface.
-- Safe defaults for LAN/team operation without weakening local-first behavior.
+- Safe defaults for LAN and team operation. Local operation must retain its
+  existing protections.
 
 ## Non-Goals
 
@@ -50,10 +52,10 @@ MCP client with stdio-only support
   -> same central MCP handler
 ```
 
-The central MCP handler is the canonical team integration surface. HTTP JSON API
-routes remain useful for scripts, browser workflows, and compatibility, but MCP
-tool semantics should not be reimplemented separately in a REST-only bridge.
-Both stdio and Streamable HTTP should share the same tool/resource/prompt
+The central MCP handler is the main team integration interface. HTTP JSON API
+routes remain available for scripts, browser workflows, and compatibility.
+A REST-only bridge should not implement a separate set of MCP tool behavior.
+Both stdio and Streamable HTTP should use the same tool, resource, and prompt
 dispatcher.
 
 ## Runtime Modes
@@ -66,9 +68,9 @@ Artifacty supports these explicit MCP operation modes:
 - `bridge`: local stdio process forwards MCP JSON-RPC to a remote `/mcp`
   endpoint for clients that cannot connect to remote MCP directly.
 
-Mode selection should be explicit. `ARTIFACTY_URL` must remain the public
-browser URL override for backwards compatibility. New variables should define
-remote MCP behavior:
+Select the mode explicitly. For backward compatibility, `ARTIFACTY_URL` must
+remain the public browser URL override. Use new variables to define remote
+MCP behavior:
 
 ```bash
 ARTIFACTY_MCP_MODE=bridge
@@ -76,8 +78,8 @@ ARTIFACTY_MCP_URL=https://artifacty.internal/mcp
 ARTIFACTY_API_TOKEN=...
 ```
 
-`ARTIFACTY_URL` may default to the central browser URL when not set, but browser
-links and MCP transport URLs should stay separate in the code and documentation.
+If `ARTIFACTY_URL` is not set, it may default to the central browser URL. Keep
+browser links separate from MCP transport URLs in the code and documentation.
 
 ## Installer UX
 
@@ -106,8 +108,8 @@ The installer should continue to support `--url` for link-only overrides.
 
 ## Central Server Operation
 
-A minimal LAN deployment should bind to a specific internal interface and require
-token auth:
+For a minimal LAN deployment, bind to a specific internal interface. Require
+token authentication:
 
 ```bash
 ARTIFACTY_API_TOKEN="$(artifacty token --raw)"
@@ -121,20 +123,23 @@ artifacty serve \
 
 Open `/login` after the server starts. If no users exist, the first successful
 login form creates an administrator. Administrators can create users from
-`/admin/users`, paste-import users from CSV, and every user can create or
-revoke personal API tokens from `/account`. CSV imports support
-`email,name,role,password,password_reset_required`; blank passwords are
-generated once and require a password change on first sign-in. Use personal
-tokens for `artifacty install ... --api-token` so MCP and API audit logs record
-the user's email as `actor` and created artifacts record the same email as
-`publisherId`.
-
-Production-like internal deployments should run Artifacty behind a TLS reverse
-proxy, keep `ARTIFACTY_ENABLE_REACT_RENDERER` disabled unless the team trusts
-all artifact authors, and store `ARTIFACTY_HOME` on local server disk with
-regular backups. Administrators can export and restore artifact backup bundles
-from `/admin/backup`; large migrations can use `artifacty backup` on the old
-server and `artifacty import-store --file <backup.json>` on the new server.
+`/admin/users` or paste CSV data to import users. Each user can create or revoke
+personal API tokens from `/account`.
+
+CSV imports support `email,name,role,password,password_reset_required`. If a
+password is blank, the importer generates it once. The user must change that
+password at first sign-in. Use personal tokens with
+`artifacty install ... --api-token`. MCP and API audit logs then record the
+user's email as `actor`. Created artifacts record the same email as `publisherId`.
+
+For internal production deployments, run Artifacty behind a TLS reverse proxy.
+Keep `ARTIFACTY_ENABLE_REACT_RENDERER` disabled unless the team trusts all
+artifact authors. Store `ARTIFACTY_HOME` on the server's local disk and make
+regular backups.
+
+Administrators can export and restore artifact backup bundles from
+`/admin/backup`. For large migrations, run `artifacty backup` on the old server.
+Then run `artifacty import-store --file <backup.json>` on the new server.
 
 For Linux user-service deployments, enable systemd lingering for the service
 account:
@@ -145,13 +150,13 @@ loginctl show-user artifacty -p Linger
 ```
 
 Use the actual service account name. Without lingering, `systemctl --user`
-services are tied to the user's login manager and can stop after logout, making
-the central dashboard and `/mcp` endpoint unavailable until that user logs in
-again. A system-level unit is another valid option for central servers.
+services depend on the user's login manager. They can stop after logout. The
+central dashboard and `/mcp` endpoint then remain unavailable until that user
+logs in again. A system-level unit is another option for central servers.
 
-The central server exposes `/mcp` only when explicitly enabled. This keeps the
-local browser/API server behavior unchanged while making team MCP exposure an
-intentional operating mode.
+The central server exposes `/mcp` only when explicitly enabled. This requirement
+keeps the local browser and API behavior unchanged. Operators must choose to
+enable MCP access for a team.
 
 ## MCP Requirements
 
@@ -161,12 +166,11 @@ Remote MCP mode needs complete parity with local MCP tools:
 - resources: recent artifact list, artifact by ID, schema
 - prompts: handoff, review, test report, visual QA, release notes
 
-The stdio server and `/mcp` HTTP endpoint call the same dispatcher so tool
-schemas, resources, prompts, validation, and audit behavior cannot drift.
+The stdio server and `/mcp` HTTP endpoint call the same dispatcher. This keeps
+tool schemas, resources, prompts, validation, and audit behavior consistent.
 
 All remote MCP requests must send `Authorization: Bearer` or an equivalent
-header accepted by the central endpoint. Remote MCP should never place tokens in
-URLs.
+header that the central endpoint accepts. Remote MCP must not put tokens in URLs.
 
 ## Audit and Identity
 
@@ -184,8 +188,8 @@ remains a compatibility fallback for the bootstrap/global token path.
 
 ## Security Model
 
-Central mode increases the trust boundary from one machine to a team network.
-Required safeguards:
+Central mode extends access from one machine to a team network. It requires
+these safeguards:
 
 - non-loopback binding still requires `ARTIFACTY_SHARE_MODE=lan|team`
 - central API always requires `ARTIFACTY_API_TOKEN`
@@ -194,8 +198,8 @@ Required safeguards:
 - browser-origin protections remain in place
 - artifact renderers continue treating stored content as untrusted
 
-For larger organizations, the next step after personal tokens is scoped tokens,
-token rotation policy, and SSO/OIDC.
+For larger organizations, the planned next steps after personal tokens are
+scoped tokens, a token rotation policy, and SSO/OIDC.
 
 ## Current Implementation
 

package/docs/integrations.md

@@ -2,13 +2,15 @@
 
 Artifacty exposes one shared MCP stdio server and one local browser server.
 
+Use Node.js 22.12.0 or newer. The optional Babel 8 React renderer requires Node `^22.18.0 || >=24.11.0`. Mermaid 12.1.0 requires an ES2024-capable browser, such as Safari 17.4 or newer.
+
 ## 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.
+The dashboard prefers `http://127.0.0.1:8787`. If that port is busy and you did not configure a port, the server uses the next available local port. It records the actual URL in the store. The default store is `~/.artifacty`. To use a different local directory, set `ARTIFACTY_HOME`.
 
 Use a generated startup token when running a protected foreground server:
 
@@ -20,7 +22,7 @@ npm start -- --generate-token
 
 Foreground runs print the generated token with ready-to-open create and import URLs. Background runs return the same values in JSON.
 
-For prompt-friendly local background runs, use the lifecycle commands:
+To run the local server in the background, use these lifecycle commands:
 
 ```bash
 node src/cli.js serve --port 8787
@@ -29,13 +31,13 @@ node src/cli.js status
 node src/cli.js stop
 ```
 
-`serve`, `serve --detach`, and `start` use the same detached-process path. They write `server.pid`, `server.json`, and logs under `ARTIFACTY_HOME` (default `~/.artifacty`). `serve --generate-token` and `start --generate-token` generate the API token in the parent CLI process and return it in JSON along with ready-to-open create/import URLs. Use `serve --foreground` when you want attached logs for debugging.
+`serve`, `serve --detach`, and `start` use the same detached-process path. They write `server.pid`, `server.json`, and logs under `ARTIFACTY_HOME` (default `~/.artifacty`). With `--generate-token`, `serve` and `start` generate the API token in the parent CLI process. The JSON response contains the token and create/import URLs. To see attached logs during debugging, use `serve --foreground`.
 
 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`, falling back to `/F` when Windows requires forceful termination. `--force` uses `/F` immediately.
-- All platforms: `status` combines the managed pid file with the HTTP `/health` endpoint, so a stale pid alone is not reported as healthy.
+- Windows: `start` hides the child console window. `stop` uses `taskkill /PID <pid> /T`. If Windows requires forceful termination, `stop` retries with `/F`. `--force` uses `/F` immediately.
+- All platforms: `status` checks the managed PID file and the HTTP `/health` endpoint. A stale PID alone does not produce a healthy status.
 
 Run diagnostics when setup behaves unexpectedly:
 
@@ -52,7 +54,7 @@ Create artifacts directly in the browser at `http://127.0.0.1:8787/new`.
 
 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, React, SARIF, CSV, image, and video 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 create/import/edit screens use CodeMirror 6. They support Markdown, HTML, JSON, source-like text, SVG, Mermaid, React, SARIF, CSV, image, and video artifacts. Artifacty serves editor and renderer assets from local npm dependencies. It uses `/assets/*.js` and allowlisted `/vendor/npm/*` module routes. For sandboxed iframe imports, `Origin: null` requests receive `Access-Control-Allow-Origin: null`. This 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.
 
@@ -116,12 +118,12 @@ admin2@example.com,Admin Two,admin,temporary-password,true
 artifacty users import --file users.csv
 ```
 
-Rows without a password receive a generated temporary password. Generated
-passwords are shown only in the import result, and imported users must change
-their password before they can continue to `/account` and issue MCP/API tokens.
+If a row has no password, Artifacty generates a temporary password. It shows
+this password only in the import result. Imported users must change their
+password before they can open `/account` and issue MCP/API tokens.
 
-- 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.
+- Claude: writes project `.mcp.json`. The parent `MCP_TIMEOUT` environment variable controls the startup timeout. The default is 30 seconds. Artifacty does not add a per-server `.mcp.json` `timeout` field.
+- Codex: writes or replaces `[mcp_servers.artifacty]` in `~/.codex/config.toml`. To use another file, pass `--config`. The generated block uses a 30-second startup timeout for slower Windows or cold-start environments.
 - Gemini: writes project `.gemini/settings.json` with a 30 second timeout.
 - GitHub Copilot in VS Code: writes workspace `.vscode/mcp.json` using the VS Code `servers` shape. Pass `--config` to target a user-profile `mcp.json` instead.
 - Cursor: writes project `.cursor/mcp.json` using the Cursor `mcpServers` shape. Pass `--config ~/.cursor/mcp.json` for global Cursor setup.
@@ -129,7 +131,7 @@ their password before they can continue to `/account` and issue MCP/API tokens.
 - `--mcp-url <url>` installs stdio bridge mode for central Artifacty. If the URL has no path, `/mcp` is appended.
 - `--api-token <token>` is written into the generated MCP environment for bridge mode. For central servers, prefer a personal token issued from `/account`.
 - `--url <url>` remains a browser-link override and does not enable central MCP by itself.
-- `--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.
+- `--timeout <ms>` adjusts Codex `startup_timeout_sec` and Gemini `timeout`. It does not change the Claude Code startup timeout. To increase that timeout, set `MCP_TIMEOUT` before launching Claude Code.
 - Do not use `artifacty install all --config <path>`. Each MCP client uses a
   different config file shape, so shared config overrides are rejected. Use
   `artifacty install <agent> --config <path>` only when targeting one agent.
@@ -163,9 +165,9 @@ artifacty install codex \
 | GitHub Copilot in VS Code | `.vscode/mcp.json` `servers` | workspace or user profile | client-managed | reload VS Code MCP server | tools are the primary tested surface |
 | Cursor | `.cursor/mcp.json` `mcpServers` | workspace or global | client-managed | restart/reload Cursor MCP | tools are the primary tested surface |
 
-All clients should support MCP tools. Resource and prompt display varies by
-client, so Artifacty's core workflows continue to work through tools even when a
-client does not expose resources or prompts in its UI.
+All clients should support MCP tools. Each client displays resources and
+prompts differently. Artifacty's core workflows use tools and still work when a
+client does not display resources or prompts.
 
 Generate a token for protected HTTP routes:
 
@@ -238,8 +240,8 @@ Markdown:
 
 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.
+reviews, and verification reports into the shared schema. Metadata preserves
+changed files, commands, tests, blockers, and next steps.
 
 ## Gemini CLI
 
@@ -321,7 +323,7 @@ Supported converter inputs:
 - Gemini: `returnDisplay`, `llmContent`, text blocks, or local markdown/text/json files.
 - Generic: file extension, content type, HTML doctype/fragments, JSON shape, media data URLs, and markdown headings are used to infer format and title. Generic `text/plain` uploads are upgraded to a more specific format, such as `html`, when filename or content makes that clear.
 
-The converter canonicalizes source-agent aliases, adds `imported` and source-agent tags, preserves the raw content as an immutable Artifacty version, and records source details under `metadata.artifactyImport`. For example, `claude-code` and `Claude Code` are stored as `claude`.
+The converter normalizes source-agent aliases. For example, it stores `claude-code` and `Claude Code` as `claude`. It adds `imported` and source-agent tags. It preserves the raw content as an immutable Artifacty version and records source details under `metadata.artifactyImport`.
 
 Fixture examples for Copilot/Cursor PR review, screenshot, demo recording, and
 visual evidence bundle live under `test/fixtures/` and are covered by converter
@@ -356,7 +358,7 @@ tests.
 - `POST /admin/artifacts/:id/versions/:version/repair`: administrator-only replacement of one version's content and format.
 - `POST /admin/artifacts/:id/versions/:version/delete`: administrator-only deletion of one version. The last remaining version cannot be deleted.
 
-When `ARTIFACTY_API_TOKEN` is configured, `/api/*` routes require either `Authorization: Bearer <token>` or `x-artifacty-token: <token>`. When users exist, personal tokens issued from `/account` also authenticate API and MCP requests, set created artifacts' `publisherId` to the token owner's email, and map audit `actor` to the same identity. Browser forms can also carry `?token=<token>` in the URL, which is copied to hidden form fields for local team workflows.
+If `ARTIFACTY_API_TOKEN` is configured, `/api/*` routes require `Authorization: Bearer <token>` or `x-artifacty-token: <token>`. If users exist, personal tokens from `/account` also authenticate API and MCP requests. New artifacts record the token owner's email as `publisherId`. Audit entries use the same identity as `actor`. Browser forms can also accept `?token=<token>` in the URL. Artifacty copies the token to hidden form fields for local team workflows.
 
 Renderer notes:
 
@@ -388,7 +390,7 @@ node src/cli.js service uninstall --dry-run
 
 Use `--platform macos|linux|windows` when preparing a definition for another host. Use `--path` to choose the output path, or the platform-specific aliases `--plist`, `--unit`, and `--script`.
 
-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. `--api-token`, `--share-mode`, and `--allow-secrets` are preserved in the generated definition when explicitly provided.
+The generated service runs `src/server.js` with explicit `--host` and `--home` arguments. If you configure a port, it also includes `--port`. Otherwise, the default port fallback remains available. If you provide `--api-token`, `--share-mode`, or `--allow-secrets`, the generated definition preserves those values.
 
 Activation is still delegated to the OS service manager:
 
@@ -396,7 +398,7 @@ Activation is still delegated to the OS service manager:
 - Linux: `sudo loginctl enable-linger $USER`, then `systemctl --user enable --now com.artifacty.server.service`
 - Windows: run the generated PowerShell script, which registers and starts the `ArtifactyServer` scheduled task.
 
-On Linux central servers, user services stop when the user's systemd manager exits unless lingering is enabled. Verify durable operation with `loginctl show-user $USER -p Linger`; it should report `Linger=yes`. Without lingering, Artifacty may be unavailable after logout and appear to recover only after the user logs back in.
+On Linux central servers, user services stop when the user's systemd manager exits unless lingering is enabled. Run `loginctl show-user $USER -p Linger` to check this setting. The result should be `Linger=yes`. Without lingering, Artifacty may stop after logout and become available only after the user signs in again.
 
 For background services, prefer a stable `ARTIFACTY_API_TOKEN` or `--api-token` value. `serve --generate-token` is intended for temporary interactive sessions; the parent CLI returns the generated token in JSON.
 
@@ -413,8 +415,10 @@ node src/cli.js export --file ./artifacty-backup.json
 node src/cli.js import-store --file ./artifacty-backup.json
 ```
 
-Backups include artifact metadata plus immutable version file contents in one
-JSON bundle. They do not include users, sessions, API token records, or audit
-logs. Importing a store replaces the target artifact records and prunes
-unreferenced version files, so run it against a new or intentionally chosen
+The default backup contains artifact metadata and immutable version contents
+in one JSON bundle. It excludes users, sessions, API token records, and audit
+logs. A store import replaces the target artifact records and removes
+unreferenced version files. Before importing, select a new or intended
 `ARTIFACTY_HOME`.
+
+Upgrade snapshots protect schema migrations and optionally application updates. They preserve raw database security state and differ from JSON export backups. Stop all server and MCP processes before recovery. See [upgrade snapshots and recovery](upgrade-backups.md).