ryugi-artifacts

Server, viewer and CLI for Ryugi's artifacts: artboards, documents and HTML pages that a coding agent writes into a project and you open in the browser.

npx ryugi-artifacts         # open the library of the current project
npx ryugi-artifacts monitor # list running project servers

The server reads .ryugi/artifacts/ in the selected project. Ryugi's skills start it for you; this package also runs standalone. Node.js is required.

Full command reference: docs/artifacts-cli.md. Project overview and install: Innei/ryugi.

License

Proprietary — see LICENSE. Ryugi's skills and harness integrations remain MIT in Innei/ryugi.

Output protocol

All commands use the same output pipeline. Brief is the default, including in non-TTY shells. --json is shorthand for --format json. Select another mode with --format brief|table|json|jsonl|raw, --quiet, or get --source. Each operation declares its supported formats; unsupported modes fail before work starts. There is no alternate legacy protocol or release gate.

ryugi-artifacts check --artifact document/plan --format brief
ryugi-artifacts publish --list --limit 10 --visibility private --format json
ryugi-artifacts get https://ryugi.innei.dev/a/ID --format brief
ryugi-artifacts get ID --detail --snapshot TOKEN --format json
ryugi-artifacts get ID --download --out ./new-download --format json
ryugi-artifacts config --output-format brief --project

Selection order is explicit option, RYUGI_ARTIFACTS_FORMAT, project .ryugi/config.json output.format, global Ryugi config output.format, then the Brief default. Persistent modes are brief, json, and jsonl; project inherit removes its override. A configuration write reports using the format selected before the write. A non-TTY stream does not change the explicit semantic format.

Semantic JSON uses schema: "ryugi.cli/v1". JSONL has ordered seq events and one terminal result; foreground services use JSONL or Brief. Exit codes are 0 for success, 1 for command failure, 2 for required user action, 3 for validation issues, 4 for incomplete evidence, 5 for partial completion, and 130/143 for signals. Consult outcome, effects, page scope, omissions, and suggested actions together. A successful operation can still have unresolved validation evidence.

Review reads are read-only. Preview a bounded page, read complete evidence, then explicitly acknowledge its receipt after using that evidence:

For a complete review in one request, run ryugi-artifacts comment list --artifact document/plan --sections all --detail. Documents include threads/asks; artboards include threads/groups/rounds. Each collection retains its own page, snapshot and continuation. Only a complete unread thread page issues a receipt; state collections do not. Follow every relevant continuation before concluding. Filters, fields and existing cursors or snapshots require the single-collection form below.

ryugi-artifacts comment list --artifact document/plan --section threads --format brief
ryugi-artifacts comment read --artifact document/plan --thread THREAD --detail
ryugi-artifacts comment ack --artifact document/plan --receipt RECEIPT
ryugi-artifacts changes --artifact document/plan --detail
ryugi-artifacts changes ack --artifact document/plan --receipt RECEIPT

--all and projected reads never issue receipts. Asks, groups and rounds are independent state collections, with no read acknowledgement. Tokens are scoped to an agent and artifact and expire after 24 hours. Unexpected API schemas are rejected; reads never fall back to a consumptive endpoint.

Cloud summaries transfer bounded outlines or manifests and do not download files. Use --section files for a document's independent file page. Snapshots pin the published version for detail, block, source and download. get --source is a pure LiteXML stream; --save <new-file> --source leaves stdout empty. Downloads require a new destination directory. Save operations never overwrite files. Cloud progressive reads require the matching server deployment and database migration 0014_semantic_read_snapshots.sql.

Commands share typed results, the normalizer, effect journal, view sections, renderers and asynchronous writer in src/cli/output/. A command supplies one handler and presenter; JSON does not call the presenter, and renderers do not branch on command names. The installer uses the generated output-bootstrap.cjs subset of the same protocol. See the architecture document in docs/ryugi/specs/2026-11-04-artifacts-cli-output-architecture-design.md in the source repository for extension rules.

Integration fixture

CI checks out the immutable Innei/ryugi commit in test/plugin-revision for launcher, hook and receipt integration tests. Update this revision with consumer changes to the CLI contract and validate both repositories together. This keeps unrelated plugin branch updates from changing a CLI test run.

For local development, RYUGI_PLUGIN_DIR=/absolute/path/to/ryugi selects the companion source tree. Builds mirror generated bundles there; use an isolated copy when a running development launcher must keep its current bundles.