ryugi-artifacts 1.59.1 → 1.61.0

package/README.md

@@ -19,3 +19,83 @@ Project overview and install: [Innei/ryugi](https://github.com/Innei/ryugi).
 
 Proprietary — see [LICENSE](LICENSE). Ryugi's skills and harness integrations
 remain MIT in [Innei/ryugi](https://github.com/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.
+
+```sh
+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.
+
+```sh
+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.