@utsu-ri/cli 0.2.0 → 0.3.1

package/README.md

@@ -1,6 +1,6 @@
 <!-- doc-language: en; canonical: true -->
 
-[English](https://github.com/hokupod/utsuri/blob/v0.2.0/README.md) | [日本語](https://github.com/hokupod/utsuri/blob/v0.2.0/README.ja.md) | [简体中文](https://github.com/hokupod/utsuri/blob/v0.2.0/README.zh-CN.md)
+[English](https://github.com/hokupod/utsuri/blob/v0.3.1/README.md) | [日本語](https://github.com/hokupod/utsuri/blob/v0.3.1/README.ja.md) | [简体中文](https://github.com/hokupod/utsuri/blob/v0.3.1/README.zh-CN.md)
 
 # Utsuri
 
@@ -14,6 +14,10 @@ Utsuri turns a Git change into a local review that connects code, browser captur
 
 Use it when a code or UI change needs a durable report, a clear list of review gaps, or structured questions returned to the coding session that created the report.
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hokupod/utsuri/main/docs/assets/utsuri.jpg" alt="Two figures facing each other across a folded mirror" width="480">
+</p>
+
 <a id="availability-requirements"></a><!-- section:availability-requirements -->
 
 ## Availability and requirements
@@ -21,9 +25,9 @@ Use it when a code or UI change needs a durable report, a clear list of review g
 <!-- availability:git-marketplace-source-ready-cli-publication-pending -->
 <!-- support-contract:macos-linux-windows-unsupported -->
 
-The source contains a Git Plugin that exact-pins the matching published `@utsu-ri/cli` release. Public Git installation remains gated until that CLI release is published and the Plugin source is merged. The commands below are verified host command shapes; do not substitute `latest`, a range, or another package.
+The source contains a Git Plugin that exact-pins its matching `@utsu-ri/cli` release. When the source version is newer than the latest verified public release, Git installation of that source remains gated until the exact CLI is published and the Plugin source is publicly reachable. The commands below are verified host command shapes; do not substitute `latest`, a range, or another package.
 
-- A Codex or Claude Code release listed in the [runtime compatibility record](https://github.com/hokupod/utsuri/blob/v0.2.0/docs/compatibility/plugin-runtime.json).
+- A Codex or Claude Code release listed in the [runtime compatibility record](https://github.com/hokupod/utsuri/blob/v0.3.1/docs/compatibility/plugin-runtime.json).
 - macOS or Linux, Node.js 22 or later, and `npx` for first MCP startup.
 - An existing compatible Chrome/Chromium installation for browser capture. Utsuri never downloads a browser.
 - Optional Docker or Podman capability for the isolated container capture mode. Utsuri never pulls an image.
@@ -49,7 +53,7 @@ codex plugin marketplace add hokupod/utsuri
 codex plugin add utsuri@utsuri
 ```
 
-Installation enables the Plugin. In the Codex app, the Plugin UI is also the supported place to inspect or change its enabled state.
+Installation enables the Plugin. In the Codex app, the Plugin UI is also the supported place to inspect or change its enabled state. Codex uses the Utsuri product illustration as both the composer icon and Plugin logo.
 
 ### Claude Code
 
@@ -65,6 +69,8 @@ claude plugin marketplace add hokupod/utsuri
 claude plugin install utsuri@utsuri
 ```
 
+Claude Code's current Plugin manifest does not expose an icon or logo field, so Utsuri does not add unsupported image metadata there.
+
 Restart the host after an install or update when it asks you to do so. The Plugin starts the exact CLI through native `npx`; a global Utsuri installation is neither required nor used.
 
 <a id="first-review"></a><!-- section:first-review -->
@@ -76,29 +82,33 @@ Open the repository in Codex or Claude Code, start a new session with Utsuri ena
 <!-- sync-command:first-review-prompt -->
 
 ```text
-Review the current change with Utsuri. Create a local evidence-backed report and call out every incomplete or uncovered check.
+Review the current change with Utsuri. Create and validate an evidence-backed report, explain each change in my language, start the local report viewer, verify that the diff loads, and return its live URL with every incomplete or uncovered check.
 ```
 
 Utsuri first checks available capabilities without installing anything. It can produce a code-only report when browser evidence was not requested or is unavailable. For browser evidence, start any required before/after application yourself and approve only explicit commands you trust.
 
-The final response gives you the local report location, confirmed coverage, findings, failures, and gaps. Opening or serving the report remains a separate explicit action.
+In a human conversation, the Agent authors the evidence-backed interpretation in your selected language, strictly validates the report, starts the appropriate persistent loopback viewer, verifies that the report and diff load, and returns the live URL with confirmed coverage, findings, failures, and gaps. A filesystem path alone is not a completed handoff. Serving is skipped only for an explicitly requested artifact-only or CI workflow.
 
 <a id="how-it-works"></a><!-- section:how-it-works -->
 
 ## How it works
 
 1. **Collect** — reads the requested patch, worktree, range, or merge base into a bounded run.
-2. **Capture** — records separately isolated before/after browser evidence only when configured and authorized.
-3. **Discover and compare** — maps changed code to targets, then compares pixels, DOM, ARIA, styles, accessibility, runtime, network, and overflow evidence.
-4. **Finalize** — publishes an immutable, hash-validated local `report/`; failed or partial evidence is preserved.
-5. **Review and return feedback** — stores viewed state, human judgment, and comments outside `report/`. Agent questions can return only to the registered originating project and session.
+2. **Interpret** — the current Agent uses the conversation, diff, and indexed evidence to group causally related hunks across files into semantic changes, explains each change, and adds a concise purpose and meaning for every hunk without inventing unsupported intent.
+3. **Capture** — records separately isolated before/after browser evidence only when configured and authorized.
+4. **Discover and compare** — maps changed code to targets, then compares pixels, DOM, ARIA, styles, accessibility, runtime, network, and overflow evidence.
+5. **Finalize** — publishes an immutable, hash-validated local `report/` with the Agent-authored annotations; failed or partial evidence is preserved.
+6. **Serve and verify** — keeps the appropriate loopback viewer alive, confirms that the review brief, first semantic change, code diff, and Agent interpretation load, then returns the live URL.
+7. **Review and return feedback** — stores viewed state, human judgment, and comments outside `report/`. Agent questions can return only to the registered originating project and session.
 
-[The detailed design](https://github.com/hokupod/utsuri/blob/v0.2.0/docs/design.md) defines the data model and security boundaries. [The CLI contract](https://github.com/hokupod/utsuri/blob/v0.2.0/skills/utsuri-review/references/cli-contract.md) documents machine-facing behavior.
+[The detailed design](https://github.com/hokupod/utsuri/blob/v0.3.1/docs/design.md) defines the data model and security boundaries. [The CLI contract](https://github.com/hokupod/utsuri/blob/v0.3.1/skills/utsuri-review/references/cli-contract.md) documents machine-facing behavior.
 
 <a id="understand-report"></a><!-- section:understand-report -->
 
 ## Understand the report
 
+- **Review brief** combines the Agent-authored overview, deterministic evidence posture, and a prioritized map of semantic changes. One semantic change may span several files; file and hunk links are evidence, not review boundaries.
+- **Hunk explanations** put the Agent-authored purpose and meaning immediately before each annotated code hunk. New annotations that omit or duplicate a collected hunk are rejected; `unclassifiedHunkRefs` is reserved for deterministic fallback reports created without annotations. Older reports without these fields remain viewable and omit the panel.
 - **Findings** are evidence-backed observations, not automatic proof of a regression.
 - **`INCOMPLETE`** means required evidence failed, was malformed, exceeded a limit, or was unavailable. It is never converted to pass.
 - **`UNCOVERED`** means changed code has no verified target or the coverage denominator is unknown.
@@ -119,10 +129,11 @@ The report preserves source identity, evidence hashes, and review gaps so anothe
 - MCP tools can use only schema-valid reports registered for the canonical current project and the same Origin Session. Cross-project, cross-host, cross-session, stale, or swapped registrations fail closed.
 - Raw host session values are used only for equality checking and opaque hashing. They are not persisted, logged, diagnosed, or returned by tools.
 - The Marketplace broker accepts only `CODEX_THREAD_ID` or the `CLAUDE_CODE_SESSION_ID` + `CLAUDE_PROJECT_DIR` host contract. Fixed-run `finalize`, `feedback`, and `review-mcp` also retain `UTSURI_CODEX_SESSION_ID` and `CLAUDE_SESSION_ID` compatibility; conflicting legacy/new values are rejected. Claude Plugin finalization always binds to the canonical host project root, including when launched from a child directory.
+- Release artifacts include deterministic SPDX and license inventories for the production dependency graph. Its identity uses exact lockfile integrity values and installed package bytes; unrelated development-only lock changes do not alter the published inventory.
 
 Claude Code may pass other ambient variables to MCP subprocesses. Utsuri does not use them as identity or expose them. `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1` is optional host hardening when supported by your Claude Code installation; the Plugin cannot enforce host-wide environment scrubbing.
 
-See the [threat model](https://github.com/hokupod/utsuri/blob/v0.2.0/docs/threat-model.md), [capture boundaries](https://github.com/hokupod/utsuri/blob/v0.2.0/skills/utsuri-review/references/capture-modes.md), and [feedback boundary](https://github.com/hokupod/utsuri/blob/v0.2.0/skills/utsuri-review/references/feedback.md) before handling untrusted projects.
+See the [threat model](https://github.com/hokupod/utsuri/blob/v0.3.1/docs/threat-model.md), [capture boundaries](https://github.com/hokupod/utsuri/blob/v0.3.1/skills/utsuri-review/references/capture-modes.md), and [feedback boundary](https://github.com/hokupod/utsuri/blob/v0.3.1/skills/utsuri-review/references/feedback.md) before handling untrusted projects.
 
 <a id="troubleshooting-lifecycle"></a><!-- section:troubleshooting-lifecycle -->
 
@@ -175,10 +186,10 @@ claude plugin uninstall utsuri@utsuri
 
 ## Documentation, contributing, and license
 
-- [Contributing and developer setup](https://github.com/hokupod/utsuri/blob/v0.2.0/CONTRIBUTING.md)
-- [Detailed design](https://github.com/hokupod/utsuri/blob/v0.2.0/docs/design.md)
-- [Release and distribution operations](https://github.com/hokupod/utsuri/blob/v0.2.0/docs/release.md)
-- [UI guidelines](https://github.com/hokupod/utsuri/blob/v0.2.0/docs/ui-guidelines.md)
-- [Skill contract](https://github.com/hokupod/utsuri/blob/v0.2.0/skills/utsuri-review/SKILL.md)
+- [Contributing and developer setup](https://github.com/hokupod/utsuri/blob/v0.3.1/CONTRIBUTING.md)
+- [Detailed design](https://github.com/hokupod/utsuri/blob/v0.3.1/docs/design.md)
+- [Release and distribution operations](https://github.com/hokupod/utsuri/blob/v0.3.1/docs/release.md)
+- [UI guidelines](https://github.com/hokupod/utsuri/blob/v0.3.1/docs/ui-guidelines.md)
+- [Skill contract](https://github.com/hokupod/utsuri/blob/v0.3.1/skills/utsuri-review/SKILL.md)
 
 Utsuri is licensed under `AGPL-3.0-or-later`. The publisher is `hokupod`. CLI publication, Git Plugin promotion, Git push, tags, and releases are separate operator-authorized actions; source changes alone perform none of them.