silvermoon 0.2.1 → 0.3.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Silvermoon contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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@9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/assets/silvermoon.svg" width="960" alt="Silvermoon, the artifact spirit of the project">
+  <img src="https://cdn.jsdelivr.net/gh/shazhou-ww/silvermoon@5e116d1fed423bbd1ebed3ec08f2c0b955823022/assets/silvermoon.svg" width="960" alt="Silvermoon, the artifact spirit of the project">
 </p>
 
 <p align="center">
@@ -11,148 +11,122 @@
   <!-- markdownlint-disable-next-line MD013 -->
   <a href="https://npmx.dev/package/silvermoon"><img src="https://img.shields.io/node/v/silvermoon?style=flat-square" alt="Node.js version"></a>
   <!-- markdownlint-disable-next-line MD013 -->
-  <a href="https://npmx.dev/package/silvermoon"><img src="https://img.shields.io/npm/unpacked-size/silvermoon?style=flat-square" alt="npm unpacked size"></a>
+  <a href="https://npmx.dev/package/silvermoon"><img src="https://img.shields.io/npm/dm/silvermoon?style=flat-square" alt="monthly npm downloads"></a>
+  <!-- markdownlint-disable-next-line MD013 -->
+  <a href="https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/LICENSE"><img src="https://img.shields.io/github/license/shazhou-ww/silvermoon?style=flat-square" alt="MIT license"></a>
   <!-- markdownlint-disable-next-line MD013 -->
   <a href="https://github.com/shazhou-ww/silvermoon/actions/workflows/ci.yml?query=branch%3Amain"><img src="https://img.shields.io/github/actions/workflow/status/shazhou-ww/silvermoon/ci.yml?branch=main&style=flat-square&label=CI" alt="CI status"></a>
 </p>
 
 <p align="center">
-  English | <a href="https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/README.zh-CN.md">简体中文</a>
+  English | <a href="https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/README.zh-CN.md">简体中文</a>
 </p>
 
 # Silvermoon
 
-**The artifact spirit of the project.**
+> Fellow cultivator, you wouldn't want your lifebound project to be without an
+> artifact spirit, would you?
 
 ## Quick Start
 
-Silvermoon needs Node.js 22 or newer and Git access to the repository's primary
-branch.
+### Setup
 
-```sh
-npm install --global silvermoon
-silvermoon whats-next
-silvermoon list-ideas
+Silvermoon requires Node.js 22 or later, along with Git access to the
+repository's primary branch.
+
+From the project directory, send this prompt to your coding agent:
+
+```text
+In this project, run:
+`npx silvermoon whats-next --audience agent`
+
+Follow its highest-priority instruction and preserve existing work.
+After each observable change, run it again until it reports: `navigation-ready`
+```
+
+### Talk to Silvermoon
+
+Use the Silvermoon skill in your coding agent:
+
+```text
+/silvermoon
+What should I work on next in this project?
 ```
 
-Silvermoon remains ecosystem-neutral when the repository root has no
-`package.json`: non-npm projects do not need a package manager, a Silvermoon
-dependency, or `node_modules`. If a root `package.json` exists, it must be valid
-JSON and declare `devDependencies.silvermoon` as exactly `^<running-version>`.
-The report supplies a package-manager-aware repair command. After installing
-that root dependency, register its canonical skill from
-`./node_modules/silvermoon/skills`; non-npm projects use the skill bundled with
-the running installation. Readiness checks inspect the selected repository
-snapshot and do not install dependencies or require `node_modules`.
-
-Create `.silvermoon/config.yaml`:
-
-```yaml
-version: 1
-primaryRepository: https://github.com/example/repository.git
-primaryBranch: main
-preferredLanguage: en
+Or continue an idea directly:
+
+```text
+/silvermoon
+Continue working on `<idea-alias>` in this project.
+Follow the `whats-next` guidance.
+Keep going until you need a decision from me.
 ```
 
-`preferredLanguage` is optional. A specific idea can override it with
-`language` in `status.yaml`, and `create-idea --language <tag>` can set that
-override when the idea is created. Otherwise Silvermoon checks
-`~/.config/silvermoon/config.yaml` and finally defaults to `en-US`.
-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.
+Or start a new idea:
 
-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.
+```text
+/silvermoon
+I have an idea:
+Add an optional cultivation-style copy mode,
+independent of the selected language.
+```
 
-Then create an idea and let the registered Silvermoon skill guide one safe
-next action at a time:
+Or run Silvermoon straight from a terminal:
 
 ```sh
-silvermoon create-idea
-silvermoon whats-next <idea>
-silvermoon whats-next <idea> --language zh-CN
+npx silvermoon whats-next
+npx silvermoon whats-next <ULID-or-alias>
+npx silvermoon create-idea
+npx silvermoon list-ideas
 ```
 
-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/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/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/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/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 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 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/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/docs/core-concepts.md).
+> **Note:** We recommend `npx silvermoon` over a global install. It avoids
+> maintaining a separate global version; in Node.js projects, the lockfile keeps
+> the project-installed version consistent.
+
+For workflows, see [Operating Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/docs/operations.md); for command
+details, see the [Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/docs/reference.md).
 
 ## Why Silvermoon
 
-Long-running Agent work usually asks people to carry too much invisible state.
-Someone must remember what was intended, whether the code still matches the
-task, and which conversation or machine knows the latest truth. Silvermoon
-makes those concerns part of the project instead.
+Long-running Agent work tends to make people carry too much invisible state.
+Someone has to remember what was originally intended, whether the code still
+matches the task, and which conversation or machine holds the latest truth.
+Silvermoon moves those concerns into the project itself.
 
-It lets people step back from continuous supervision and return at the
-decisions that belong to them: approving the intended outcome, accepting the
-implementation, and accepting that the result is true in the outside world.
-Between those boundaries, an Agent can inspect repository facts and continue
-the highest-priority safe action.
+It lets people step away from continuous supervision and return only for the
+decisions that are theirs: approving the intended outcome, accepting the
+implementation, and accepting that the result holds in the outside world.
+Between those boundaries, an Agent can inspect repository facts and carry on
+with the highest-priority safe action.
 
-It also refuses to let a detached task card declare success. Current artifacts
-and explicit decisions jointly determine state, so a changed goal or
-implementation naturally invalidates conclusions that depended on the older
-revision. Because those facts live in Git, work can continue across devices,
-sessions, Agents, and hosting platforms.
+It also refuses to let a detached task card declare success. State is derived
+jointly from current artifacts and explicit decisions, so once a goal or an
+implementation changes, conclusions that rested on the older revision are
+invalidated as a matter of course. And because those facts live in Git, work
+continues across devices, sessions, Agents, and hosting platforms.
 
 ## The Project's Artifact Spirit
 
-> Fellow Daoist, you wouldn't want your lifebound project to be without an
-> artifact spirit, would you?
-
 <table>
   <tr>
     <td width="160" align="center" valign="top">
       <!-- markdownlint-disable-next-line MD013 -->
-      <img src="https://cdn.jsdelivr.net/gh/shazhou-ww/silvermoon@9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/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@5e116d1fed423bbd1ebed3ec08f2c0b955823022/assets/silvermoon-mascot.png" width="160" alt="Full-body 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
       Journey to Immortality</em>. She comes from the Silvermoon Wolf Clan in
-      the Spirit Realm and is one of the split souls of Ling Long. After losing
-      part of her memory in the human realm, she lives as an artifact spirit
-      first in a wolf-headed jade scepter and later in Han Li's Bamboo
-      Cloudswarm Swords.
+      the Spirit Realm, and is one of the two souls split from Ling Long.
+      Adrift in the human realm, she became the artifact spirit of a
+      wolf-headed jade scepter — and in that long service lost part of her
+      memory, taking the name Silvermoon. She later became the artifact spirit
+      of Han Li's Bamboo Cloudswarm Swords.
       <br><br>
-      That image fits this project: Silvermoon does not belong to one operator
-      or one chat. It lives with the project's artifacts, understands their
-      state, and helps each companion find what comes next. The biography is
-      inspiration, not a prerequisite for using the tool.
+      That image suits this project: Silvermoon belongs to no single operator
+      and no single chat. It lives alongside the project's artifacts,
+      understands their state, and helps every companion see what comes next.
+      The backstory is inspiration, not a prerequisite for using the tool.
     </td>
   </tr>
 </table>
@@ -164,36 +138,56 @@ Watch *A Record of a Mortal's Journey to Immortality*:
 <!-- markdownlint-disable-next-line MD013 -->
 - Bilibili: [Episode 150: Overseas Turmoil 26](https://www.bilibili.com/bangumi/play/ep1231558 "A Record of a Mortal's Journey to Immortality — Episode 150: Overseas Turmoil 26")
 
-## From Ideal To Real
+## From Ideal to Real
 
 A project is more than a task list or a transcript. It is an ideal becoming
-real through three nested worlds.
+real across three nested worlds.
 
-**Ideal World (道心)** names the outcome worth pursuing. **Inner World (内景)**
-gives that intent shape in repository artifacts. **Outer World (现世)** asks
-whether the shaped work is true where it must actually operate.
+**Ideal World (道心)** is the world of ideals, **Inner World (内景)** the
+subjective world, and **Outer World (现世)** the world of reality.
 
-> 道心立意，内景成形，现世验真。
+> 道心立志，内景化形，现世求真。
 
-The worlds nest from the inside out. Implementation contains the ideal it
-serves, and deployment contains both. This is an engineering relationship, not
-just a metaphor: when an inner world changes, conclusions from an outer world
-no longer have the same foundation and must be proven again.
+The worlds nest from the inside out: the subjective world contains the ideal it
+serves, and is itself part of the real world — just as a person holds ideals yet
+must live in reality.
+
+So the ideal is first argued out in the Ideal World, then given form in the
+Inner World, and finally deployed into the Outer World. That is consciousness
+acting back upon matter.
 
 Humans own approval and acceptance. Agents own continuation: they read the
-contracts, the ledger, and Git facts; preserve concurrent work; execute one
-safe action; and reobserve only after something changes. The context belongs to
-the project, not to a fleeting conversation.
+contracts, the ledger, and the facts in Git; preserve concurrent work; carry
+out one safe action; and re-observe only once something has changed. Context
+belongs to the project, not to a fleeting conversation.
 
 ## Further Reading
 
-- [Getting Started](https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/docs/getting-started.md) — installation, configuration,
+- [Getting Started](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/docs/getting-started.md) — installation, configuration,
   and the first idea.
-- [Core Concepts](https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/docs/core-concepts.md) — project ownership, the three
+- [Core Concepts](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/docs/core-concepts.md) — project ownership, the three
   worlds, revisions, and decision boundaries.
-- [Operating Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/docs/operations.md) — navigation, creation,
+- [Operating Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/docs/operations.md) — navigation, creation,
   publication, hygiene, and continuation.
-- [Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/docs/reference.md) — storage, derived state, CLI
+- [Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/docs/reference.md) — storage, derived state, CLI
   reports, validation targets, and schemas.
-- [Maintaining Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/docs/maintaining.md) — development checks,
+- [Maintaining Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/docs/maintaining.md) — development checks,
   documentation ownership, and release guidance.
+
+## Community
+
+- [Contributing](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/CONTRIBUTING.md)
+- [Code of Conduct](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/CODE_OF_CONDUCT.md)
+- [Security Policy](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/SECURITY.md)
+- [Support](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/SUPPORT.md)
+- [Changelog](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/CHANGELOG.md)
+- [MIT License](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/LICENSE)
+
+## Image Copyright Disclaimer
+
+The Silvermoon character images in this project are AI-generated derivative
+works based on the animated adaptation of *A Record of a Mortal's Journey to
+Immortality*. Rights in the original character and animation belong to their
+respective holders, and these images fall outside this project's
+[MIT License](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/LICENSE). If any rights holder believes an image infringes
+their rights, please contact the author and the image will be replaced.

package/README.zh-CN.md

@@ -2,122 +2,105 @@
 
 <p align="center">
   <!-- markdownlint-disable-next-line MD013 -->
-  <img src="https://cdn.jsdelivr.net/gh/shazhou-ww/silvermoon@9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/assets/silvermoon.svg" width="960" alt="Silvermoon，项目的器灵">
+  <img src="https://cdn.jsdelivr.net/gh/shazhou-ww/silvermoon@5e116d1fed423bbd1ebed3ec08f2c0b955823022/assets/silvermoon.svg" width="960" alt="Silvermoon，项目的器灵">
 </p>
 
 <p align="center">
-  <a href="https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/README.md">English</a> | 简体中文
+  <a href="https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/README.md">English</a> | 简体中文
 </p>
 
 # Silvermoon（银月）
 
-**项目的器灵。**
+> 道友也不想自己的本命项目没有器灵吧？
 
 ## 快速开始
 
-Silvermoon 需要 Node.js 22 或更高版本，并且能够通过 Git 访问仓库的 primary branch。
+### Setup
 
-```sh
-npm install --global silvermoon
-silvermoon whats-next
-silvermoon list-ideas
+Silvermoon 需要 Node.js 22 或更高版本，并且能通过 Git 访问仓库的 primary branch。
+
+在项目目录下，把这段提示词发给你的 coding agent：
+
+```text
+请在本项目中运行：
+`npx silvermoon whats-next --audience agent`
+
+遵循最高优先级指示并保留已有工作。
+每次产生可观察变更后重新运行，直到报告显示：
+`navigation-ready`
 ```
 
-Silvermoon 对非 npm 仓库保持生态中立：当仓库根目录没有 `package.json` 时，无需
-package manager、Silvermoon dependency 或 `node_modules`。如果根目录存在
-`package.json`，它必须是有效 JSON，并在 `devDependencies.silvermoon` 中逐字声明
-`^<当前运行版本>`。首次报告会按项目 package manager 提供修复命令。安装根依赖后，
-从 `./node_modules/silvermoon/skills` 注册 canonical skill；非 npm 项目继续使用当前
-运行实例随附的 skill。整备检查只读取所选 repository snapshot，不会安装依赖，也不要求
-存在 `node_modules`。
-
-创建 `.silvermoon/config.yaml`：
-
-```yaml
-version: 1
-primaryRepository: https://github.com/example/repository.git
-primaryBranch: main
-preferredLanguage: zh-CN
+### Talk to Silvermoon
+
+在 coding agent 中使用 Silvermoon skill：
+
+```text
+/silvermoon
+这个项目接下来应该做什么？
 ```
 
-`preferredLanguage` 可省略。具体 idea 可以通过 `status.yaml` 的 `language`
-覆盖它，创建时也可以使用 `create-idea --language <tag>` 设置该值。否则 Silvermoon 会继续
-读取 `~/.config/silvermoon/config.yaml`，最后稳定回退到 `en-US`。
-这些持久化值决定项目内容所用语言。若只需改变单次命令的内置输出语言，可使用
-`whats-next --language en-US|zh-CN` 或 `check --language en-US|zh-CN`；该临时覆盖
-不会写入任何配置或 idea。
+或者直接继续推进一个 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 同步。
+```text
+/silvermoon
+请继续推进这个项目中的 `<idea-alias>`。
+遵循 `whats-next` 的指引持续工作。
+直到需要我做决定时再停下来。
+```
 
-然后创建一个 idea，让已注册的 Silvermoon skill 每次引导一个安全的下一步行动：
+或者提出一个新想法：
+
+```text
+/silvermoon
+我有个想法：
+增加一个独立于语言选择的修仙风格文案开关。
+```
+
+也可以直接在终端运行 Silvermoon：
 
 ```sh
-silvermoon create-idea
-silvermoon whats-next <idea>
-silvermoon whats-next <idea> --language zh-CN
+npx silvermoon whats-next
+npx silvermoon whats-next <ULID-or-alias>
+npx silvermoon create-idea
+npx silvermoon list-ideas
 ```
 
-在生成的 `Idea.md` 中描述想要抵达的世界，审阅并批准这个精确 revision。此后，
-Silvermoon 会让目标、实现、仓库状态与现实结果始终相连。完整的首次工作流见英文
-[Getting Started](https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/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/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/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 只会在 `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/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/docs/core-concepts.md)。
+> **备注**：建议使用 `npx silvermoon`，而不是全局安装。这样无需单独维护全局版本；
+> 在 Node.js 项目中，lock file 会固定项目使用的版本。
+
+工作流见 [Operating Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/docs/operations.md)，
+命令详情见 [Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/docs/reference.md)。
 
 ## 为什么需要 Silvermoon
 
-长期运行的 Agent 工作往往让人背负太多不可见状态：有人必须记住原本想做什么、代码是否
-仍与任务一致，以及最新事实究竟留在哪次对话或哪台机器上。Silvermoon 把这些问题变成
-项目自身的一部分。
+长期运行的 Agent 工作，往往让人背负太多看不见的状态：总得有人记住最初想做什么、
+代码是否仍与任务一致，以及最新的事实究竟留在哪次对话、哪台机器上。
+Silvermoon 把这些变成项目自身的一部分。
 
-它让人不必持续看守，只在真正属于人的决策点回来：批准目标、验收实现，以及确认结果在
-现世成立。在这些边界之间，Agent 可以检查仓库事实，并继续最高优先级的安全行动。
+它让人不必时刻盯守，只在真正属于人的决策点回来：批准目标、验收实现，
+以及确认结果在现世成立。在这些边界之间，Agent 可以查阅仓库事实，
+推进优先级最高的安全行动。
 
-它也不允许一张脱离代码的任务卡自行宣告成功。当前产物与明确决定共同派生状态，因此目标
-或实现一旦改变，依赖旧 revision 的结论自然失效。事实保存在 Git 中，工作便能跨设备、
-跨 session、跨 Agent、跨托管平台延续。
+它也不允许一张脱离代码的任务卡自行宣告成功。状态由当前产物与明确决定共同派生，
+因此目标或实现一旦改变，依赖旧 revision 的结论自然失效。
+这些事实存在 Git 里，工作便能跨设备、跨 session、跨 Agent、跨托管平台延续下去。
 
 ## 项目的器灵
 
-> 道友也不想自己的本命项目没有器灵吧？
-
 <table>
   <tr>
     <td width="160" align="center" valign="top">
       <!-- markdownlint-disable-next-line MD013 -->
-      <img src="https://cdn.jsdelivr.net/gh/shazhou-ww/silvermoon@9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/assets/silvermoon-avatar.svg" width="128" alt="项目器灵银月的线稿头像">
+      <img src="https://cdn.jsdelivr.net/gh/shazhou-ww/silvermoon@5e116d1fed423bbd1ebed3ec08f2c0b955823022/assets/silvermoon-mascot.png" width="160" alt="项目器灵银月的全身立绘">
     </td>
     <td valign="top">
-      Silvermoon 得名于《凡人修仙传》中的银月。她来自灵界的银月狼族，是玲珑公主分裂出的
-      两道元神之一。她在人界失去部分记忆后成为器灵，先后寄居于狼首玉如意和韩立的
-      青竹蜂云剑。
+      Silvermoon 得名于《凡人修仙传》中的银月。
+      她是灵界银月狼族玲珑公主分裂出的两道元神之一；流落人界后成为狼首玉如意的器灵，
+      又在漫长的岁月里失去部分记忆，从此自称银月，后来才成为韩立青竹蜂云剑的器灵。
       <br><br>
-      这个意象与项目相合：Silvermoon 不属于某位操作者或某次对话。它与项目产物共存，
-      理解它们的状态，并帮助每位同行者判断下一步。人物小传只是灵感来源，不是使用工具的
-      知识门槛。
+      这个意象与本项目相合：Silvermoon 不属于某位操作者，也不属于某次对话。
+      它与项目产物共存，理解它们的状态，并帮每位同行者看清下一步。
+      人物小传只是灵感来源，不是使用这道工具的门槛。
     </td>
   </tr>
 </table>
@@ -131,25 +114,43 @@ provenance。`create-idea` 可返回 preparing guidance。这些 guidance 只能
 
 ## 从理想到现实
 
-项目不只是一张任务列表，也不是一份对话记录。它是理想经过三个嵌套世界逐渐进入现实的
-过程。
+项目不只是一张任务列表，也不是一份对话记录。
+它是理想穿过三个嵌套世界、逐渐落进现实的过程。
+
+**Ideal World（道心）**——理想世界，**Inner World（内景）**——主体世界，
+**Outer World（现世）**——现实世界。
 
-**Ideal World（道心）**确定值得追求的结果，**Inner World（内景）**让意图在仓库产物中
-成形，**Outer World（现世）**则验证这些产物在真正需要运行的地方是否成立。
+> 道心立志，内景化形，现世求真。
 
-> 道心立意，内景成形，现世验真。
+三个世界由内向外层层包含：主体世界包含它所服务的理想世界，又是现实世界的一部分。
+正如人会有理想，却又必须活在现实之中。
 
-三个世界由内向外层层包含：实现包含它所服务的理想，部署又包含二者。这不只是比喻，也是
-工程关系。内层变化时，外层旧结论便失去原有依据，必须重新证明。
+先在理想世界里把理想讨论清楚，再在主体世界中让它成形，
+最后部署到现实世界去——这正是意识反作用于物质的过程。
 
-人负责 approval 与 acceptance，Agent 负责 continuation：读取 contract、ledger 与 Git
-事实，保留并发工作，执行一个安全行动，并只在发生变化后重新观察。上下文属于项目，而不
-属于转瞬即逝的某次对话。
+人负责 approval 与 acceptance，Agent 负责 continuation：
+读取 contract、ledger 与 Git 事实，保留并发工作，执行一个安全行动，
+并且只在发生变化之后重新观察。上下文属于项目，而不属于某次转瞬即逝的对话。
 
 ## 延伸阅读
 
-- [Getting Started](https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/docs/getting-started.md) — 安装、配置与第一个 idea。
-- [Core Concepts](https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/docs/core-concepts.md) — 项目归属、三重世界、revision 与决策边界。
-- [Operating Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/docs/operations.md) — 导航、创建、发布、仓库卫生与持续推进。
-- [Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/docs/reference.md) — 存储、派生状态、CLI report、验证 target 与 schema。
-- [Maintaining Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/docs/maintaining.md) — 开发检查、文档职责与发布指南。
+- [Getting Started](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/docs/getting-started.md) — 安装、配置与第一个 idea。
+- [Core Concepts](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/docs/core-concepts.md) — 项目归属、三重世界、revision 与决策边界。
+- [Operating Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/docs/operations.md) — 导航、创建、发布、仓库卫生与持续推进。
+- [Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/docs/reference.md) — 存储、派生状态、CLI report、验证 target 与 schema。
+- [Maintaining Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/docs/maintaining.md) — 开发检查、文档职责与发布指南。
+
+## 社区
+
+- [贡献指南](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/CONTRIBUTING.md)
+- [行为准则](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/CODE_OF_CONDUCT.md)
+- [安全策略](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/SECURITY.md)
+- [支持说明](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/SUPPORT.md)
+- [变更记录](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/CHANGELOG.md)
+- [MIT License](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/LICENSE)
+
+## 图片版权声明
+
+本项目使用的银月（Silvermoon）形象，均为基于《凡人修仙传》动画二次生成的 AI 图片。
+原角色与动画的相关权利归各自版权方所有，这些图片不在本项目 [MIT License](https://github.com/shazhou-ww/silvermoon/blob/5e116d1fed423bbd1ebed3ec08f2c0b955823022/LICENSE) 的授权范围内。
+若版权方认为其中任何图片构成侵权，请联系作者，作者会替换相关图片。

package/bin/silvermoon.js

@@ -1,5 +1,10 @@
 #!/usr/bin/env node
 
-import { runCli } from "../src/cli.js";
+const bootstrapStartedAt = process.hrtime.bigint();
+const { runCli } = await import("../src/cli.js");
 
-process.exitCode = await runCli(process.argv.slice(2));
+process.exitCode = await runCli(
+  process.argv.slice(2),
+  console,
+  { bootstrapStartedAt },
+);