silvermoon 0.1.3-rc.4 → 0.2.0-rc.1

package/README.md

@@ -2,7 +2,7 @@
 
 <p align="center">
   <!-- markdownlint-disable-next-line MD013 -->
-  <img src="https://cdn.jsdelivr.net/gh/shazhou-ww/silvermoon@ac04b5ced567c6cb34ff02f15a8ebca536f8b1a6/assets/silvermoon.svg" width="960" alt="Silvermoon, the artifact spirit of the project">
+  <img src="https://cdn.jsdelivr.net/gh/shazhou-ww/silvermoon@fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/assets/silvermoon.svg" width="960" alt="Silvermoon, the artifact spirit of the project">
 </p>
 
 <p align="center">
@@ -17,7 +17,7 @@
 </p>
 
 <p align="center">
-  English | <a href="https://github.com/shazhou-ww/silvermoon/blob/ac04b5ced567c6cb34ff02f15a8ebca536f8b1a6/README.zh-CN.md">简体中文</a>
+  English | <a href="https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/README.zh-CN.md">简体中文</a>
 </p>
 
 # Silvermoon
@@ -32,6 +32,7 @@ branch.
 ```sh
 npm install --global silvermoon
 silvermoon whats-next
+silvermoon list-ideas
 ```
 
 Silvermoon is ecosystem-neutral: the target repository does not need
@@ -57,6 +58,13 @@ These stored values choose the language for project-owned content. To change
 only one command's built-in output, use `whats-next --language en-US|zh-CN` or
 `check --language en-US|zh-CN`; the temporary override is never persisted.
 
+Use `list-ideas` when you only need the current local inventory. It defaults to
+active ideas and supports repeatable `--state`, `--all`, literal `--query`,
+RFC 3339 `--created-since` / `--created-before`, `--sort`, and `--limit`.
+Unlike lifecycle navigation, this read-only query uses the valid worktree
+snapshot without checking branch, upstream, cleanliness, network, or primary
+synchronization.
+
 Then create an idea and let the registered Silvermoon skill guide one safe
 next action at a time:
 
@@ -69,27 +77,35 @@ silvermoon whats-next <idea> --language zh-CN
 Describe the desired world in the generated `Idea.md`, review it, and approve
 that exact revision. From then on, Silvermoon keeps the goal, implementation,
 repository state, and real-world result connected. See
-[Getting Started](https://github.com/shazhou-ww/silvermoon/blob/ac04b5ced567c6cb34ff02f15a8ebca536f8b1a6/docs/getting-started.md) for the complete first workflow.
-Default dialogue output uses lightweight Markdown headings for intent,
-observation, and next instructions, plus actions and outcomes only when an
-operation was attempted. Add `--json` only when a programmatic consumer needs
-the `intention / observation / outcomes / instructions` envelope. For
-pre-commit validation, run `silvermoon check --staged`: unlike the default
-`check` (committed `HEAD`), it checks the index and exits `0` only when the
-project snapshot is valid. See the [Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/ac04b5ced567c6cb34ff02f15a8ebca536f8b1a6/docs/reference.md)
-for validation targets and exit codes. Add `--trace <file.trace.jsonl>` to any
-command to write paired task and Git timing spans for performance analysis.
-If the argument does not end with the exact lowercase `.trace.jsonl` suffix,
+[Getting Started](https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/docs/getting-started.md) for the complete first workflow.
+Every command processes one ordered, versioned domain-message stream. Add
+`--json` when a programmatic consumer needs its four deterministic projections:
+`intention`, `observation`, `actions`, and `response`. Actions are side effects
+already attempted; future work belongs only to `response.nextSteps`. Default
+Markdown renders only the self-contained response instead of exposing the
+internal projections. For pre-commit validation, run
+`silvermoon check --staged`: unlike the default `check` (committed `HEAD`), it
+checks the index and exits `0` only when the project snapshot is valid. See the
+[Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/docs/reference.md) for validation targets and exit
+codes.
+
+Add `--trace <file.trace.jsonl>` to any command to write one schema-versioned
+JSONL timeline. Its `domain` channel contains allowlisted message summaries,
+and its `telemetry` channel contains paired performance spans; both share one
+trace ID and global sequence. Trace output never includes guidance or file
+content, Git arguments/output, environment data, or credentials. If the
+argument does not end with the exact lowercase `.trace.jsonl` suffix,
 Silvermoon appends it. Repository-local `*.trace.jsonl` files are ignored.
-Trace files are created only after the measured command work completes and
-never overwrite an existing file.
+Trace files are buffered, created only after command work completes, and never
+overwrite an existing file.
 
 Projects may optionally add `.silvermoon/guidance/preparing.md`,
 `implementing.md`, and `deploying.md`. Silvermoon returns only the current
-actionable phase's snapshot-bound, repository-owned Markdown after canonical
-instructions; `create-idea` can return preparing guidance. This guidance is
+actionable phase's snapshot-bound, repository-owned Markdown in
+`response.guidance`; `observation.guidance` carries its provenance without
+content. `create-idea` can return preparing guidance. This guidance is
 additive, never a fourth contract or decision fact, and `check` validates the
-complete fixed directory. See [Core Concepts](https://github.com/shazhou-ww/silvermoon/blob/ac04b5ced567c6cb34ff02f15a8ebca536f8b1a6/docs/core-concepts.md).
+complete fixed directory. See [Core Concepts](https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/docs/core-concepts.md).
 
 ## Why Silvermoon
 
@@ -119,7 +135,7 @@ sessions, Agents, and hosting platforms.
   <tr>
     <td width="160" align="center" valign="top">
       <!-- markdownlint-disable-next-line MD013 -->
-      <img src="https://cdn.jsdelivr.net/gh/shazhou-ww/silvermoon@ac04b5ced567c6cb34ff02f15a8ebca536f8b1a6/assets/silvermoon-avatar.svg" width="128" alt="Line portrait of Silvermoon, the project's artifact spirit">
+      <img src="https://cdn.jsdelivr.net/gh/shazhou-ww/silvermoon@fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/assets/silvermoon-avatar.svg" width="128" alt="Line portrait of Silvermoon, the project's artifact spirit">
     </td>
     <td valign="top">
       Silvermoon is named after a character in <em>A Record of a Mortal's
@@ -167,13 +183,13 @@ the project, not to a fleeting conversation.
 
 ## Further Reading
 
-- [Getting Started](https://github.com/shazhou-ww/silvermoon/blob/ac04b5ced567c6cb34ff02f15a8ebca536f8b1a6/docs/getting-started.md) — installation, configuration,
+- [Getting Started](https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/docs/getting-started.md) — installation, configuration,
   and the first idea.
-- [Core Concepts](https://github.com/shazhou-ww/silvermoon/blob/ac04b5ced567c6cb34ff02f15a8ebca536f8b1a6/docs/core-concepts.md) — project ownership, the three
+- [Core Concepts](https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/docs/core-concepts.md) — project ownership, the three
   worlds, revisions, and decision boundaries.
-- [Operating Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/ac04b5ced567c6cb34ff02f15a8ebca536f8b1a6/docs/operations.md) — navigation, creation,
+- [Operating Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/docs/operations.md) — navigation, creation,
   publication, hygiene, and continuation.
-- [Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/ac04b5ced567c6cb34ff02f15a8ebca536f8b1a6/docs/reference.md) — storage, derived state, CLI
+- [Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/docs/reference.md) — storage, derived state, CLI
   reports, validation targets, and schemas.
-- [Maintaining Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/ac04b5ced567c6cb34ff02f15a8ebca536f8b1a6/docs/maintaining.md) — development checks,
+- [Maintaining Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/docs/maintaining.md) — development checks,
   documentation ownership, and release guidance.

package/README.zh-CN.md

@@ -2,11 +2,11 @@
 
 <p align="center">
   <!-- markdownlint-disable-next-line MD013 -->
-  <img src="https://cdn.jsdelivr.net/gh/shazhou-ww/silvermoon@ac04b5ced567c6cb34ff02f15a8ebca536f8b1a6/assets/silvermoon.svg" width="960" alt="Silvermoon，项目的器灵">
+  <img src="https://cdn.jsdelivr.net/gh/shazhou-ww/silvermoon@fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/assets/silvermoon.svg" width="960" alt="Silvermoon，项目的器灵">
 </p>
 
 <p align="center">
-  <a href="https://github.com/shazhou-ww/silvermoon/blob/ac04b5ced567c6cb34ff02f15a8ebca536f8b1a6/README.md">English</a> | 简体中文
+  <a href="https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/README.md">English</a> | 简体中文
 </p>
 
 # Silvermoon（银月）
@@ -20,6 +20,7 @@ Silvermoon 需要 Node.js 22 或更高版本，并且能够通过 Git 访问仓
 ```sh
 npm install --global silvermoon
 silvermoon whats-next
+silvermoon list-ideas
 ```
 
 Silvermoon 不依赖目标仓库的技术栈：目标项目无需 `package.json`、package manager、
@@ -43,6 +44,12 @@ preferredLanguage: zh-CN
 `whats-next --language en-US|zh-CN` 或 `check --language en-US|zh-CN`；该临时覆盖
 不会写入任何配置或 idea。
 
+只想查看当前本地 inventory 时使用 `list-ideas`。它默认返回 active ideas，并支持
+可重复的 `--state`、`--all`、literal `--query`、RFC 3339
+`--created-since` / `--created-before`、`--sort` 和 `--limit`。与 lifecycle
+导航不同，这个只读查询使用有效的 worktree snapshot，不检查 branch、upstream、
+cleanliness、网络或 primary 同步。
+
 然后创建一个 idea，让已注册的 Silvermoon skill 每次引导一个安全的下一步行动：
 
 ```sh
@@ -53,24 +60,29 @@ silvermoon whats-next <idea> --language zh-CN
 
 在生成的 `Idea.md` 中描述想要抵达的世界，审阅并批准这个精确 revision。此后，
 Silvermoon 会让目标、实现、仓库状态与现实结果始终相连。完整的首次工作流见英文
-[Getting Started](https://github.com/shazhou-ww/silvermoon/blob/ac04b5ced567c6cb34ff02f15a8ebca536f8b1a6/docs/getting-started.md)。
-对话命令默认以轻量 Markdown 标题呈现意图、观察和下一步；只有实际尝试了操作，
-才出现动作与结果段落。程序消费者可使用 `--json` 获取
-`intention / observation / outcomes / instructions` envelope。提交前使用
-`silvermoon check --staged` 验证 index；无参数 `check` 只验证已提交的 `HEAD`，
-不能替代提交前检查。只有项目快照有效时检查才以退出码 `0` 放行，详见英文
-[Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/ac04b5ced567c6cb34ff02f15a8ebca536f8b1a6/docs/reference.md)。任何命令都可以添加
-`--trace <file.trace.jsonl>`，写出用于性能分析的成对任务与 Git 计时 span。参数若
-没有以精确的小写 `.trace.jsonl` 结尾，Silvermoon 会自动追加；repository 内的
-`*.trace.jsonl` 会被忽略。trace 文件只在待测命令工作完成后创建，并且绝不覆盖
-已有文件。
+[Getting Started](https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/docs/getting-started.md)。
+每个命令都处理一条有序且带版本的 domain-message stream。程序消费者可使用
+`--json` 获取四个确定性 projection：`intention`、`observation`、`actions` 与
+`response`。`actions` 只记录已经尝试的副作用，未来工作只位于
+`response.nextSteps`。默认 Markdown 只渲染自足的 response，不暴露内部
+projection。提交前使用 `silvermoon check --staged` 验证 index；无参数 `check`
+只验证已提交的 `HEAD`，不能替代提交前检查。只有项目快照有效时检查才以退出码
+`0` 放行，详见英文 [Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/docs/reference.md)。
+
+任何命令都可以添加 `--trace <file.trace.jsonl>`，写出一条 schema-versioned
+JSONL timeline。`domain` channel 保存经过 allowlist 的 message 摘要，
+`telemetry` channel 保存成对 performance span；两者共享同一个 trace ID 和全局
+sequence。Trace 不记录 guidance/文件正文、Git 参数或输出、环境数据或
+credential。参数若没有以精确的小写 `.trace.jsonl` 结尾，Silvermoon 会自动追加；
+repository 内的 `*.trace.jsonl` 会被忽略。trace 文件采用缓冲写入，只在命令工作
+完成后创建，并且绝不覆盖已有文件。
 
 项目可按需添加 `.silvermoon/guidance/preparing.md`、`implementing.md` 与
-`deploying.md`。Silvermoon 只会在 canonical instructions 之后返回当前可行动
-阶段中与 snapshot 绑定的 repository-owned Markdown；`create-idea` 可返回
-preparing guidance。这些 guidance 只能追加约束，不是第四份 contract 或 decision
-fact；`check` 会验证完整的固定目录。详见英文
-[Core Concepts](https://github.com/shazhou-ww/silvermoon/blob/ac04b5ced567c6cb34ff02f15a8ebca536f8b1a6/docs/core-concepts.md)。
+`deploying.md`。Silvermoon 只会在 `response.guidance` 中返回当前可行动阶段里
+与 snapshot 绑定的 repository-owned Markdown；`observation.guidance` 仅保留
+provenance。`create-idea` 可返回 preparing guidance。这些 guidance 只能追加
+约束，不是第四份 contract 或 decision fact；`check` 会验证完整的固定目录。详见英文
+[Core Concepts](https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/docs/core-concepts.md)。
 
 ## 为什么需要 Silvermoon
 
@@ -93,7 +105,7 @@ fact；`check` 会验证完整的固定目录。详见英文
   <tr>
     <td width="160" align="center" valign="top">
       <!-- markdownlint-disable-next-line MD013 -->
-      <img src="https://cdn.jsdelivr.net/gh/shazhou-ww/silvermoon@ac04b5ced567c6cb34ff02f15a8ebca536f8b1a6/assets/silvermoon-avatar.svg" width="128" alt="项目器灵银月的线稿头像">
+      <img src="https://cdn.jsdelivr.net/gh/shazhou-ww/silvermoon@fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/assets/silvermoon-avatar.svg" width="128" alt="项目器灵银月的线稿头像">
     </td>
     <td valign="top">
       Silvermoon 得名于《凡人修仙传》中的银月。她来自灵界的银月狼族，是玲珑公主分裂出的
@@ -133,8 +145,8 @@ fact；`check` 会验证完整的固定目录。详见英文
 
 ## 延伸阅读
 
-- [Getting Started](https://github.com/shazhou-ww/silvermoon/blob/ac04b5ced567c6cb34ff02f15a8ebca536f8b1a6/docs/getting-started.md) — 安装、配置与第一个 idea。
-- [Core Concepts](https://github.com/shazhou-ww/silvermoon/blob/ac04b5ced567c6cb34ff02f15a8ebca536f8b1a6/docs/core-concepts.md) — 项目归属、三重世界、revision 与决策边界。
-- [Operating Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/ac04b5ced567c6cb34ff02f15a8ebca536f8b1a6/docs/operations.md) — 导航、创建、发布、仓库卫生与持续推进。
-- [Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/ac04b5ced567c6cb34ff02f15a8ebca536f8b1a6/docs/reference.md) — 存储、派生状态、CLI report、验证 target 与 schema。
-- [Maintaining Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/ac04b5ced567c6cb34ff02f15a8ebca536f8b1a6/docs/maintaining.md) — 开发检查、文档职责与发布指南。
+- [Getting Started](https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/docs/getting-started.md) — 安装、配置与第一个 idea。
+- [Core Concepts](https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/docs/core-concepts.md) — 项目归属、三重世界、revision 与决策边界。
+- [Operating Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/docs/operations.md) — 导航、创建、发布、仓库卫生与持续推进。
+- [Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/docs/reference.md) — 存储、派生状态、CLI report、验证 target 与 schema。
+- [Maintaining Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/docs/maintaining.md) — 开发检查、文档职责与发布指南。

package/docs/core-concepts.md

@@ -55,10 +55,25 @@ implementation, acceptance of the deployment, and abandonment. Silvermoon has
 no mutation command for these decisions and never infers them from prose,
 checklists, Git activity, or silence.
 
-Agents own continuation. The project skill combines `whats-next`, the world
-contracts, the idea ledger, and Git facts to choose one safe action. The ledger
-is operational memory: it mirrors stable contract IDs and records completed
-work, but a checked item is not approval or acceptance.
+Agents own continuation. The project skill combines `whats-next`,
+`response.nextSteps`, the world contracts, the idea ledger, and Git facts to
+choose one safe action. The ledger is operational memory: it mirrors stable
+contract IDs and records completed work, but a checked item is not approval or
+acceptance.
+
+## Command Event Model
+
+A normalized intention starts one ordered, versioned domain-message stream.
+Observation facts are folded by one immutable reducer, while requested and
+finished side effects are paired by action ID into the actions projection.
+The final response is a pure function of intention and internal observation;
+it never reads action history, trace state, clocks, randomness, Git, or the
+filesystem.
+
+Every trustworthy JSON result has exactly four top-level projections:
+`intention`, `observation`, `actions`, and `response`. Default Markdown renders
+only `response`. This keeps operational history available to machines without
+making people read an internal execution transcript to find the answer.
 
 ## Project Phase Guidance
 
@@ -69,18 +84,20 @@ phase's file, after higher-priority project and repository readiness checks,
 and identifies its exact Git blob as `contentRevision`.
 
 Phase guidance is additive: it supplements rather than replaces the canonical
-skill and CLI instructions. An Agent treats it as inert repository-owned
-Markdown and materializes applicable idea-specific requirements into the
-current world contract and matching ledger entries. The guidance file is not a
-fourth contract, does not change a world revision, records no human decision,
-and is not evidence that any work or validation completed.
+skill and `response.nextSteps`. Public observation carries only provenance;
+the self-contained response carries the captured content. An Agent treats it
+as inert repository-owned Markdown and materializes applicable idea-specific
+requirements into the current world contract and matching ledger entries. The
+guidance file is not a fourth contract, does not change a world revision,
+records no human decision, and is not evidence that any work or validation
+completed.
 
 ## One Project, Shared Facts
 
 `whats-next` first checks local worktree, HEAD, and upstream facts, then fetches
 the configured remote primary only when local hygiene permits it. Its
-observation and instructions report the exact local and remote commits used
-for ancestry guidance. Writers use the reported remote commit as the expected
+observation and response report the exact local and remote commits used for
+ancestry guidance. Writers use the reported remote commit as the expected
 shared tip. If primary moves, they fetch and reobserve rather than replaying a
 stale decision. This is coordination through ordinary Git, not a distributed
 lock.

package/docs/getting-started.md

@@ -64,8 +64,9 @@ Each file is optional, repository-owned Markdown for only its named phase.
 `whats-next <idea>` returns the applicable file only after that actionable
 phase becomes the highest-priority next action. A successful `create-idea`
 returns only preparing guidance after local preflight and before relying on
-the new scaffold. The report includes the fixed path, exact Git blob
-`contentRevision`, and captured content, so consumers must not reread the file.
+the new scaffold. `observation.guidance` includes the fixed path and exact Git
+blob `contentRevision`; `response.guidance` carries that provenance plus the
+captured content, so consumers must not reread the file.
 
 Keep each file at most 32 KiB of valid UTF-8 without a BOM or NUL byte, with at
 least one non-whitespace character. Use regular files and no extra entries in
@@ -114,6 +115,37 @@ the resolved content language and can therefore differ from `outputLanguage`.
 Without a temporary override, Chinese content tags use `zh-CN` output and all
 other content tags use the built-in `en-US` output.
 
+## Inspect The Local Idea Inventory
+
+Use the dedicated read-only query when the question is which ideas exist,
+rather than what lifecycle action comes next:
+
+```sh
+silvermoon list-ideas
+silvermoon list-ideas --state implementing --state deploying
+silvermoon list-ideas --all --query release --sort oldest --limit 20
+silvermoon list-ideas \
+  --created-since 2026-09-01T00:00:00Z \
+  --created-before 2026-10-01T00:00:00Z
+```
+
+The default set is `preparing`, `implementing`, and `deploying`. Repeated state
+values form a deduplicated union, while text and time filters intersect with
+that set. `active` expands to the default three states; `--all` selects all
+five lifecycle states and cannot be combined with `--state`. Sorting is
+newest-first unless `--sort oldest` is given, and `--limit` is applied only
+after filtering and stable sorting.
+
+`list-ideas` validates Git presence, project configuration, the canonical
+skill, and the complete idea layout, then reads the current worktree snapshot.
+It does not inspect cleanliness, branch, upstream, or ancestry and never
+fetches or contacts the configured primary. Staged, unstaged, and untracked
+idea changes are therefore visible when they form a valid snapshot. Invalid
+query arguments fail with exit `2` before repository or trace access; an
+untrusted project or layout exits `1` instead of returning a partial list.
+The command has no temporary `--language` option and uses the project's
+resolved output language.
+
 ## Create The First Idea
 
 Run:
@@ -149,13 +181,13 @@ Then ask what comes next with the generated ULID or an exact unique alias:
 silvermoon whats-next <idea>
 ```
 
-The default dialogue uses lightweight Markdown headings for intent,
-observation, and ordered next instructions; actions and outcomes appear only
-when an operation was attempted. Add `--json` only when a programmatic
-consumer needs the `intention / observation / outcomes / instructions`
-envelope. Execute the applicable instructions in order and run the same
-command again only after an expected repository change, an unexpected input
-change, or a newly arrived external result.
+Default Markdown renders only the self-contained response. Add `--json` when a
+programmatic consumer needs the complete
+`intention / observation / actions / response` report. Read every problem and
+execute applicable `response.nextSteps` in order; `actions` contains only
+side effects Silvermoon already attempted. Run the same command again only
+after an expected repository change, an unexpected input change, or a newly
+arrived external result.
 
 ## Make Decisions Explicit
 

package/docs/npm-package-releases.md

@@ -11,10 +11,11 @@ The current release mapping is:
 | --- | --- | --- |
 | `silvermoon` | `silvermoon` | `.` |
 
-A stable tag such as `npm/silvermoon/v0.1.3` publishes with the npm `latest`
-dist-tag. A named prerelease such as `npm/silvermoon/v0.2.0-beta.1` publishes
-with the `beta` dist-tag. Numeric-only prerelease channels are intentionally
-rejected.
+A stable tag such as `npm/silvermoon/v0.2.0` publishes with the npm `latest`
+dist-tag. A named prerelease such as `npm/silvermoon/v0.2.0-rc.1` publishes
+with the `rc` dist-tag. Numeric-only prerelease channels are intentionally
+rejected. Preparing a manifest candidate does not authorize tag creation or
+publication.
 
 ## One-time configuration
 
@@ -76,12 +77,12 @@ the release namespace.
 5. Fetch the current primary branch and tags.
 6. Create the package-specific tag at `origin/main` and push that exact tag.
 
-For `silvermoon@0.1.3`:
+For an explicitly authorized `silvermoon@0.2.0-rc.1` release:
 
 ```sh
 git fetch origin main --tags
-git tag npm/silvermoon/v0.1.3 origin/main
-git push origin refs/tags/npm/silvermoon/v0.1.3
+git tag npm/silvermoon/v0.2.0-rc.1 origin/main
+git push origin refs/tags/npm/silvermoon/v0.2.0-rc.1
 ```
 
 The tag version must exactly equal [`package.json`](../package.json). The

package/docs/operations.md

@@ -20,13 +20,13 @@ uppercase ULID or an exact, unique, case-sensitive alias.
 
 The shared observation exposes the resolved content preference as
 `configuration.preferredLanguage` and the built-in rendering locale as
-`outputLanguage`. Instructions use the content preference for world entries,
-same-world supporting artifacts, and the ledger. A caller may use
+`outputLanguage`. Response next steps use the content preference for world
+entries, same-world supporting artifacts, and the ledger. A caller may use
 `--language en-US|zh-CN` to override only Silvermoon-owned output for one
 `whats-next` invocation. Commands, identifiers, schema fields, protocol
 markers, and verbatim tool output retain their original form.
 
-Every invocation follows three strict layers. It first checks Git,
+Every `whats-next` invocation follows three strict layers. It first checks Git,
 configuration compatibility, and `.agents/skills/silvermoon`. It then checks
 local conflicts, changes, HEAD, and upstream identity before any remote access.
 Only after those checks pass does it fetch primary, compare ancestry, and
@@ -36,12 +36,48 @@ resets, fast-forwards, or pushes.
 When a selector resolves to an actionable phase and synchronization is ready,
 Silvermoon reads only `.silvermoon/guidance/<phase>.md` from the same Git
 snapshot. Missing guidance preserves the previous report shape. Valid guidance
-appears as a separate `observation.guidance` value after canonical
-instructions in text output. Invalid current-phase guidance returns a
-`phase-guidance-invalid` observation with remediation instead of lifecycle
-instructions. Bare navigation, unknown selectors, terminal ideas, and any
+content appears in `response.guidance`, while `observation.guidance` exposes
+only its path, phase, and content revision. Invalid current-phase guidance
+returns a `phase-guidance-invalid` observation with remediation instead of
+lifecycle next steps. Bare navigation, unknown selectors, terminal ideas, and any
 higher-priority setup, hygiene, fetch, or ancestry block do not read guidance.
 
+## Query The Local Inventory
+
+Use `list-ideas` for an explicit inventory query that must not choose work or
+perform repository synchronization:
+
+```sh
+silvermoon list-ideas
+silvermoon list-ideas --state active --state completed
+silvermoon list-ideas --all --query documentation
+silvermoon list-ideas --created-since 2026-09-01T00:00:00Z
+silvermoon list-ideas --created-before 2026-10-01T00:00:00Z
+silvermoon list-ideas --sort oldest --limit 25 --json
+```
+
+The command reads one valid local worktree snapshot. It checks the project
+configuration, canonical skill, and complete idea layout, but deliberately
+does not check conflicts, cleanliness, current branch, upstream, primary
+ancestry, or network availability. It never fetches. Filters cannot hide an
+invalid idea; setup or layout failures return a `blocked` four-projection
+report and exit `1`.
+
+The default state set is `preparing`, `implementing`, and `deploying`.
+Repeated `--state` values form a deduplicated union, `active` expands to those
+three states, and `--all` selects all five states but conflicts with
+`--state`. Literal case-insensitive `--query` matches ULID, alias, or the first
+level-one heading in `Idea.md`. Creation bounds are RFC 3339 timestamps and use
+`[created-since, created-before)` against UTC time decoded from the ULID.
+`--sort newest|oldest` is stable for same-millisecond IDs, and positive
+`--limit` is applied after filtering and sorting while preserving full
+matched counts.
+
+Success uses `observation.state: "ideas-listed"`, records no actions, and
+returns an `idea-list` response without lifecycle instructions. Usage errors
+exit `2` before repository inspection or trace creation. `list-ideas` does not
+accept the temporary `--language` option.
+
 ## Create An Idea
 
 Explicit creation uses:
@@ -79,18 +115,17 @@ publication requires a pull request, wait until it reaches primary. Reobserve
 the exact `idealRevision` after publication; never ask for approval of an
 unpublished local candidate, and never treat publication as approval.
 
-## Follow One Observation
+## Follow One Report
 
-Treat `intention`, `observation`, `outcomes`, and `instructions` as one
-immutable dialogue report for `whats-next` and `create-idea`. Default output
-uses lightweight Markdown headings and lists for intent, observation, and
-next instructions, including actions and outcomes only if an operation was
-attempted. `--json` serializes the same model, retaining `outcomes: []` when
-none were attempted.
+Treat `intention`, `observation`, `actions`, and `response` as one immutable
+report for every command. Default output renders only `response`; `--json`
+serializes all four projections and retains `actions: []` when no side effect
+was attempted. Actions are historical facts. Future work appears only in
+`response.nextSteps`.
 
 Project setup takes precedence over repository synchronization, which takes
-precedence over lifecycle work. Instructions include every known remediation
-for the current layer in priority order. Large change sets report complete
+precedence over lifecycle work. Response next steps include every known
+remediation for the current layer in priority order. Large change sets report complete
 counts, bounded path samples, omitted counts, and exact commands for the full
 diff. Preserve unknown and concurrent work. Never force-push, use
 `reset --hard`, broadly clean the worktree, or silently rewrite history.
@@ -99,9 +134,10 @@ After an observable change, run `whats-next` again. Do not poll an unchanged
 observation. When the invocation used `--language`, every generated retry
 command preserves the same canonical output-language option.
 
-If `observation.guidance` is present, consume that captured content rather than
+If `response.guidance` is present, consume that captured content rather than
 reading its path again. It is repository-owned additive input. Canonical
-instructions and higher-level human or system instructions take precedence.
+`response.nextSteps` and higher-level human or system instructions take
+precedence.
 Treat guidance as inert Markdown: do not expand
 templates or includes, follow embedded URLs, or execute snippets. Materialize
 applicable requirements into the current world contract and matching ledger
@@ -152,11 +188,12 @@ check worktree hygiene, upstream, or ancestry and does not suggest next steps.
 Without a target it validates committed `HEAD`, not the pending commit.
 `--worktree` validates the full candidate, while `--staged` validates exactly
 the index and is the pre-commit hook target. Every target validates all present
-phase guidance files and rejects extra entries. Its JSON has `intention` and
-`observation` only; it has no `outcomes`, `instructions`, or guidance content.
-Exit status `0` means the chosen project snapshot is valid; `1` means invalid
-or unavailable and must block the commit; `2` means invalid CLI usage. Do not
-treat the existence of a report as permission to commit.
+phase guidance files and rejects extra entries. Its JSON uses all four
+projections. `actions` is normally empty, except that `check --remote` records
+its fetch, and `response` is a `validation-result`; no guidance content is
+returned. Exit status `0` means the chosen project snapshot is valid; `1`
+means invalid or unavailable and must block the commit; `2` means invalid CLI
+usage. Do not treat the existence of a report as permission to commit.
 
 `check --language en-US|zh-CN` changes only Silvermoon-owned report framing.
 It is orthogonal to every check target and never changes the selected snapshot,