silvermoon 0.2.0 → 0.2.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@27700c428509c3152d5eb96e90a8e1a4a150c6cb/assets/silvermoon.svg" width="960" alt="Silvermoon, the artifact spirit of the project">
+  <img src="https://cdn.jsdelivr.net/gh/shazhou-ww/silvermoon@9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/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/27700c428509c3152d5eb96e90a8e1a4a150c6cb/README.zh-CN.md">简体中文</a>
+  English | <a href="https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/README.zh-CN.md">简体中文</a>
 </p>
 
 # Silvermoon
@@ -35,11 +35,15 @@ silvermoon whats-next
 silvermoon list-ideas
 ```
 
-Silvermoon is ecosystem-neutral: the target repository does not need
-`package.json`, a package manager, a Silvermoon dependency, or `node_modules`.
-The first report lists every applicable setup step in order, including the
-exact `npx skills add ... --agent universal` command that registers the
-canonical skill at `.agents/skills/silvermoon`.
+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`:
 
@@ -77,7 +81,7 @@ 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/27700c428509c3152d5eb96e90a8e1a4a150c6cb/docs/getting-started.md) for the complete first workflow.
+[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
@@ -86,7 +90,7 @@ 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/27700c428509c3152d5eb96e90a8e1a4a150c6cb/docs/reference.md) for validation targets and exit
+[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
@@ -105,7 +109,7 @@ 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/27700c428509c3152d5eb96e90a8e1a4a150c6cb/docs/core-concepts.md).
+complete fixed directory. See [Core Concepts](https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/docs/core-concepts.md).
 
 ## Why Silvermoon
 
@@ -135,7 +139,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@27700c428509c3152d5eb96e90a8e1a4a150c6cb/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@9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/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
@@ -183,13 +187,13 @@ the project, not to a fleeting conversation.
 
 ## Further Reading
 
-- [Getting Started](https://github.com/shazhou-ww/silvermoon/blob/27700c428509c3152d5eb96e90a8e1a4a150c6cb/docs/getting-started.md) — installation, configuration,
+- [Getting Started](https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/docs/getting-started.md) — installation, configuration,
   and the first idea.
-- [Core Concepts](https://github.com/shazhou-ww/silvermoon/blob/27700c428509c3152d5eb96e90a8e1a4a150c6cb/docs/core-concepts.md) — project ownership, the three
+- [Core Concepts](https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/docs/core-concepts.md) — project ownership, the three
   worlds, revisions, and decision boundaries.
-- [Operating Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/27700c428509c3152d5eb96e90a8e1a4a150c6cb/docs/operations.md) — navigation, creation,
+- [Operating Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/docs/operations.md) — navigation, creation,
   publication, hygiene, and continuation.
-- [Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/27700c428509c3152d5eb96e90a8e1a4a150c6cb/docs/reference.md) — storage, derived state, CLI
+- [Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/docs/reference.md) — storage, derived state, CLI
   reports, validation targets, and schemas.
-- [Maintaining Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/27700c428509c3152d5eb96e90a8e1a4a150c6cb/docs/maintaining.md) — development checks,
+- [Maintaining Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/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@27700c428509c3152d5eb96e90a8e1a4a150c6cb/assets/silvermoon.svg" width="960" alt="Silvermoon，项目的器灵">
+  <img src="https://cdn.jsdelivr.net/gh/shazhou-ww/silvermoon@9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/assets/silvermoon.svg" width="960" alt="Silvermoon，项目的器灵">
 </p>
 
 <p align="center">
-  <a href="https://github.com/shazhou-ww/silvermoon/blob/27700c428509c3152d5eb96e90a8e1a4a150c6cb/README.md">English</a> | 简体中文
+  <a href="https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/README.md">English</a> | 简体中文
 </p>
 
 # Silvermoon（银月）
@@ -23,10 +23,13 @@ silvermoon whats-next
 silvermoon list-ideas
 ```
 
-Silvermoon 不依赖目标仓库的技术栈：目标项目无需 `package.json`、package manager、
-Silvermoon dependency 或 `node_modules`。首次报告会按顺序列出所有适用的整备步骤，
-其中包括把 canonical skill 注册到 `.agents/skills/silvermoon` 的精确
-`npx skills add ... --agent universal` 命令。
+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`：
 
@@ -60,14 +63,14 @@ silvermoon whats-next <idea> --language zh-CN
 
 在生成的 `Idea.md` 中描述想要抵达的世界，审阅并批准这个精确 revision。此后，
 Silvermoon 会让目标、实现、仓库状态与现实结果始终相连。完整的首次工作流见英文
-[Getting Started](https://github.com/shazhou-ww/silvermoon/blob/27700c428509c3152d5eb96e90a8e1a4a150c6cb/docs/getting-started.md)。
+[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/27700c428509c3152d5eb96e90a8e1a4a150c6cb/docs/reference.md)。
+`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 摘要，
@@ -82,7 +85,7 @@ repository 内的 `*.trace.jsonl` 会被忽略。trace 文件采用缓冲写入
 与 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/27700c428509c3152d5eb96e90a8e1a4a150c6cb/docs/core-concepts.md)。
+[Core Concepts](https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/docs/core-concepts.md)。
 
 ## 为什么需要 Silvermoon
 
@@ -105,7 +108,7 @@ provenance。`create-idea` 可返回 preparing guidance。这些 guidance 只能
   <tr>
     <td width="160" align="center" valign="top">
       <!-- markdownlint-disable-next-line MD013 -->
-      <img src="https://cdn.jsdelivr.net/gh/shazhou-ww/silvermoon@27700c428509c3152d5eb96e90a8e1a4a150c6cb/assets/silvermoon-avatar.svg" width="128" alt="项目器灵银月的线稿头像">
+      <img src="https://cdn.jsdelivr.net/gh/shazhou-ww/silvermoon@9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/assets/silvermoon-avatar.svg" width="128" alt="项目器灵银月的线稿头像">
     </td>
     <td valign="top">
       Silvermoon 得名于《凡人修仙传》中的银月。她来自灵界的银月狼族，是玲珑公主分裂出的
@@ -145,8 +148,8 @@ provenance。`create-idea` 可返回 preparing guidance。这些 guidance 只能
 
 ## 延伸阅读
 
-- [Getting Started](https://github.com/shazhou-ww/silvermoon/blob/27700c428509c3152d5eb96e90a8e1a4a150c6cb/docs/getting-started.md) — 安装、配置与第一个 idea。
-- [Core Concepts](https://github.com/shazhou-ww/silvermoon/blob/27700c428509c3152d5eb96e90a8e1a4a150c6cb/docs/core-concepts.md) — 项目归属、三重世界、revision 与决策边界。
-- [Operating Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/27700c428509c3152d5eb96e90a8e1a4a150c6cb/docs/operations.md) — 导航、创建、发布、仓库卫生与持续推进。
-- [Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/27700c428509c3152d5eb96e90a8e1a4a150c6cb/docs/reference.md) — 存储、派生状态、CLI report、验证 target 与 schema。
-- [Maintaining Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/27700c428509c3152d5eb96e90a8e1a4a150c6cb/docs/maintaining.md) — 开发检查、文档职责与发布指南。
+- [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) — 开发检查、文档职责与发布指南。

package/docs/getting-started.md

@@ -20,18 +20,28 @@ silvermoon whats-next
 # or: npx silvermoon@<version> whats-next
 ```
 
-The setup report gives the exact path for the running installation. Use it to
-register the bundled canonical skill through the universal `skills` target:
+For repositories without a root `package.json`, the setup report gives the
+exact path for the running installation. Use it to register the bundled
+canonical skill through the universal `skills` target:
 
 ```sh
 npx skills add <path-to-running-silvermoon>/skills --skill silvermoon --agent universal --yes --copy
 ```
 
-The registration lives only at `.agents/skills/silvermoon`. Silvermoon checks
-that its content exactly matches the running installation. It does not require
-the target repository to use Node, contain `package.json`, declare a
-Silvermoon dependency, or have `node_modules`, and it never mutates skill
-registration itself.
+If the repository root contains `package.json`, Silvermoon requires valid JSON
+and an exact `devDependencies.silvermoon` value of `^<running-version>`.
+Follow the setup report's package-manager-specific command, then install the
+root dependencies and register the project-local canonical skill:
+
+```sh
+npx skills add ./node_modules/silvermoon/skills --skill silvermoon --agent universal --yes --copy
+```
+
+Only the tracked root manifest is part of readiness; installed dependencies
+and `node_modules` are not required for snapshot checks. Silvermoon checks the
+registration at `.agents/skills/silvermoon` against its running canonical
+skill, and never mutates the manifest, package-manager files, dependencies, or
+skill registration itself. Non-npm repositories remain free of npm setup.
 
 ## Configure The Shared Primary
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "silvermoon",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "The project spirit that checks repository state and answers what's next.",
   "packageManager": "pnpm@11.22.0",
   "type": "module",
@@ -66,7 +66,7 @@
     "mdast-util-to-markdown": "^2.1.2",
     "yaml": "^2.9.1"
   },
-  "gitHead": "27700c428509c3152d5eb96e90a8e1a4a150c6cb",
-  "readme": "<!-- markdownlint-disable-file MD041 -->\n\n<p align=\"center\">\n  <!-- markdownlint-disable-next-line MD013 -->\n  <img src=\"https://cdn.jsdelivr.net/gh/shazhou-ww/silvermoon@27700c428509c3152d5eb96e90a8e1a4a150c6cb/assets/silvermoon.svg\" width=\"960\" alt=\"Silvermoon, the artifact spirit of the project\">\n</p>\n\n<p align=\"center\">\n  <!-- markdownlint-disable-next-line MD013 -->\n  <a href=\"https://npmx.dev/package/silvermoon\"><img src=\"https://img.shields.io/npm/v/silvermoon?style=flat-square\" alt=\"npm version\"></a>\n  <!-- markdownlint-disable-next-line MD013 -->\n  <a href=\"https://npmx.dev/package/silvermoon\"><img src=\"https://img.shields.io/node/v/silvermoon?style=flat-square\" alt=\"Node.js version\"></a>\n  <!-- markdownlint-disable-next-line MD013 -->\n  <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>\n  <!-- markdownlint-disable-next-line MD013 -->\n  <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>\n</p>\n\n<p align=\"center\">\n  English | <a href=\"https://github.com/shazhou-ww/silvermoon/blob/27700c428509c3152d5eb96e90a8e1a4a150c6cb/README.zh-CN.md\">简体中文</a>\n</p>\n\n# Silvermoon\n\n**The artifact spirit of the project.**\n\n## Quick Start\n\nSilvermoon needs Node.js 22 or newer and Git access to the repository's primary\nbranch.\n\n```sh\nnpm install --global silvermoon\nsilvermoon whats-next\nsilvermoon list-ideas\n```\n\nSilvermoon is ecosystem-neutral: the target repository does not need\n`package.json`, a package manager, a Silvermoon dependency, or `node_modules`.\nThe first report lists every applicable setup step in order, including the\nexact `npx skills add ... --agent universal` command that registers the\ncanonical skill at `.agents/skills/silvermoon`.\n\nCreate `.silvermoon/config.yaml`:\n\n```yaml\nversion: 1\nprimaryRepository: https://github.com/example/repository.git\nprimaryBranch: main\npreferredLanguage: en\n```\n\n`preferredLanguage` is optional. A specific idea can override it with\n`language` in `status.yaml`, and `create-idea --language <tag>` can set that\noverride when the idea is created. Otherwise Silvermoon checks\n`~/.config/silvermoon/config.yaml` and finally defaults to `en-US`.\nThese stored values choose the language for project-owned content. To change\nonly one command's built-in output, use `whats-next --language en-US|zh-CN` or\n`check --language en-US|zh-CN`; the temporary override is never persisted.\n\nUse `list-ideas` when you only need the current local inventory. It defaults to\nactive ideas and supports repeatable `--state`, `--all`, literal `--query`,\nRFC 3339 `--created-since` / `--created-before`, `--sort`, and `--limit`.\nUnlike lifecycle navigation, this read-only query uses the valid worktree\nsnapshot without checking branch, upstream, cleanliness, network, or primary\nsynchronization.\n\nThen create an idea and let the registered Silvermoon skill guide one safe\nnext action at a time:\n\n```sh\nsilvermoon create-idea\nsilvermoon whats-next <idea>\nsilvermoon whats-next <idea> --language zh-CN\n```\n\nDescribe the desired world in the generated `Idea.md`, review it, and approve\nthat exact revision. From then on, Silvermoon keeps the goal, implementation,\nrepository state, and real-world result connected. See\n[Getting Started](https://github.com/shazhou-ww/silvermoon/blob/27700c428509c3152d5eb96e90a8e1a4a150c6cb/docs/getting-started.md) for the complete first workflow.\nEvery command processes one ordered, versioned domain-message stream. Add\n`--json` when a programmatic consumer needs its four deterministic projections:\n`intention`, `observation`, `actions`, and `response`. Actions are side effects\nalready attempted; future work belongs only to `response.nextSteps`. Default\nMarkdown renders only the self-contained response instead of exposing the\ninternal projections. For pre-commit validation, run\n`silvermoon check --staged`: unlike the default `check` (committed `HEAD`), it\nchecks the index and exits `0` only when the project snapshot is valid. See the\n[Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/27700c428509c3152d5eb96e90a8e1a4a150c6cb/docs/reference.md) for validation targets and exit\ncodes.\n\nAdd `--trace <file.trace.jsonl>` to any command to write one schema-versioned\nJSONL timeline. Its `domain` channel contains allowlisted message summaries,\nand its `telemetry` channel contains paired performance spans; both share one\ntrace ID and global sequence. Trace output never includes guidance or file\ncontent, Git arguments/output, environment data, or credentials. If the\nargument does not end with the exact lowercase `.trace.jsonl` suffix,\nSilvermoon appends it. Repository-local `*.trace.jsonl` files are ignored.\nTrace files are buffered, created only after command work completes, and never\noverwrite an existing file.\n\nProjects may optionally add `.silvermoon/guidance/preparing.md`,\n`implementing.md`, and `deploying.md`. Silvermoon returns only the current\nactionable phase's snapshot-bound, repository-owned Markdown in\n`response.guidance`; `observation.guidance` carries its provenance without\ncontent. `create-idea` can return preparing guidance. This guidance is\nadditive, never a fourth contract or decision fact, and `check` validates the\ncomplete fixed directory. See [Core Concepts](https://github.com/shazhou-ww/silvermoon/blob/27700c428509c3152d5eb96e90a8e1a4a150c6cb/docs/core-concepts.md).\n\n## Why Silvermoon\n\nLong-running Agent work usually asks people to carry too much invisible state.\nSomeone must remember what was intended, whether the code still matches the\ntask, and which conversation or machine knows the latest truth. Silvermoon\nmakes those concerns part of the project instead.\n\nIt lets people step back from continuous supervision and return at the\ndecisions that belong to them: approving the intended outcome, accepting the\nimplementation, and accepting that the result is true in the outside world.\nBetween those boundaries, an Agent can inspect repository facts and continue\nthe highest-priority safe action.\n\nIt also refuses to let a detached task card declare success. Current artifacts\nand explicit decisions jointly determine state, so a changed goal or\nimplementation naturally invalidates conclusions that depended on the older\nrevision. Because those facts live in Git, work can continue across devices,\nsessions, Agents, and hosting platforms.\n\n## The Project's Artifact Spirit\n\n> Fellow Daoist, you wouldn't want your lifebound project to be without an\n> artifact spirit, would you?\n\n<table>\n  <tr>\n    <td width=\"160\" align=\"center\" valign=\"top\">\n      <!-- markdownlint-disable-next-line MD013 -->\n      <img src=\"https://cdn.jsdelivr.net/gh/shazhou-ww/silvermoon@27700c428509c3152d5eb96e90a8e1a4a150c6cb/assets/silvermoon-avatar.svg\" width=\"128\" alt=\"Line portrait of Silvermoon, the project's artifact spirit\">\n    </td>\n    <td valign=\"top\">\n      Silvermoon is named after a character in <em>A Record of a Mortal's\n      Journey to Immortality</em>. She comes from the Silvermoon Wolf Clan in\n      the Spirit Realm and is one of the split souls of Ling Long. After losing\n      part of her memory in the human realm, she lives as an artifact spirit\n      first in a wolf-headed jade scepter and later in Han Li's Bamboo\n      Cloudswarm Swords.\n      <br><br>\n      That image fits this project: Silvermoon does not belong to one operator\n      or one chat. It lives with the project's artifacts, understands their\n      state, and helps each companion find what comes next. The biography is\n      inspiration, not a prerequisite for using the tool.\n    </td>\n  </tr>\n</table>\n\nWatch *A Record of a Mortal's Journey to Immortality*:\n\n<!-- markdownlint-disable-next-line MD013 -->\n- YouTube: [Episode 150: Overseas Turmoil 26](https://www.youtube.com/watch?v=GJgezoCBIHM \"A Record of a Mortal's Journey to Immortality — Episode 150: Overseas Turmoil 26\")\n<!-- markdownlint-disable-next-line MD013 -->\n- 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\")\n\n## From Ideal To Real\n\nA project is more than a task list or a transcript. It is an ideal becoming\nreal through three nested worlds.\n\n**Ideal World (道心)** names the outcome worth pursuing. **Inner World (内景)**\ngives that intent shape in repository artifacts. **Outer World (现世)** asks\nwhether the shaped work is true where it must actually operate.\n\n> 道心立意，内景成形，现世验真。\n\nThe worlds nest from the inside out. Implementation contains the ideal it\nserves, and deployment contains both. This is an engineering relationship, not\njust a metaphor: when an inner world changes, conclusions from an outer world\nno longer have the same foundation and must be proven again.\n\nHumans own approval and acceptance. Agents own continuation: they read the\ncontracts, the ledger, and Git facts; preserve concurrent work; execute one\nsafe action; and reobserve only after something changes. The context belongs to\nthe project, not to a fleeting conversation.\n\n## Further Reading\n\n- [Getting Started](https://github.com/shazhou-ww/silvermoon/blob/27700c428509c3152d5eb96e90a8e1a4a150c6cb/docs/getting-started.md) — installation, configuration,\n  and the first idea.\n- [Core Concepts](https://github.com/shazhou-ww/silvermoon/blob/27700c428509c3152d5eb96e90a8e1a4a150c6cb/docs/core-concepts.md) — project ownership, the three\n  worlds, revisions, and decision boundaries.\n- [Operating Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/27700c428509c3152d5eb96e90a8e1a4a150c6cb/docs/operations.md) — navigation, creation,\n  publication, hygiene, and continuation.\n- [Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/27700c428509c3152d5eb96e90a8e1a4a150c6cb/docs/reference.md) — storage, derived state, CLI\n  reports, validation targets, and schemas.\n- [Maintaining Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/27700c428509c3152d5eb96e90a8e1a4a150c6cb/docs/maintaining.md) — development checks,\n  documentation ownership, and release guidance.\n",
+  "gitHead": "9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c",
+  "readme": "<!-- markdownlint-disable-file MD041 -->\n\n<p align=\"center\">\n  <!-- markdownlint-disable-next-line MD013 -->\n  <img src=\"https://cdn.jsdelivr.net/gh/shazhou-ww/silvermoon@9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/assets/silvermoon.svg\" width=\"960\" alt=\"Silvermoon, the artifact spirit of the project\">\n</p>\n\n<p align=\"center\">\n  <!-- markdownlint-disable-next-line MD013 -->\n  <a href=\"https://npmx.dev/package/silvermoon\"><img src=\"https://img.shields.io/npm/v/silvermoon?style=flat-square\" alt=\"npm version\"></a>\n  <!-- markdownlint-disable-next-line MD013 -->\n  <a href=\"https://npmx.dev/package/silvermoon\"><img src=\"https://img.shields.io/node/v/silvermoon?style=flat-square\" alt=\"Node.js version\"></a>\n  <!-- markdownlint-disable-next-line MD013 -->\n  <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>\n  <!-- markdownlint-disable-next-line MD013 -->\n  <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>\n</p>\n\n<p align=\"center\">\n  English | <a href=\"https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/README.zh-CN.md\">简体中文</a>\n</p>\n\n# Silvermoon\n\n**The artifact spirit of the project.**\n\n## Quick Start\n\nSilvermoon needs Node.js 22 or newer and Git access to the repository's primary\nbranch.\n\n```sh\nnpm install --global silvermoon\nsilvermoon whats-next\nsilvermoon list-ideas\n```\n\nSilvermoon remains ecosystem-neutral when the repository root has no\n`package.json`: non-npm projects do not need a package manager, a Silvermoon\ndependency, or `node_modules`. If a root `package.json` exists, it must be valid\nJSON and declare `devDependencies.silvermoon` as exactly `^<running-version>`.\nThe report supplies a package-manager-aware repair command. After installing\nthat root dependency, register its canonical skill from\n`./node_modules/silvermoon/skills`; non-npm projects use the skill bundled with\nthe running installation. Readiness checks inspect the selected repository\nsnapshot and do not install dependencies or require `node_modules`.\n\nCreate `.silvermoon/config.yaml`:\n\n```yaml\nversion: 1\nprimaryRepository: https://github.com/example/repository.git\nprimaryBranch: main\npreferredLanguage: en\n```\n\n`preferredLanguage` is optional. A specific idea can override it with\n`language` in `status.yaml`, and `create-idea --language <tag>` can set that\noverride when the idea is created. Otherwise Silvermoon checks\n`~/.config/silvermoon/config.yaml` and finally defaults to `en-US`.\nThese stored values choose the language for project-owned content. To change\nonly one command's built-in output, use `whats-next --language en-US|zh-CN` or\n`check --language en-US|zh-CN`; the temporary override is never persisted.\n\nUse `list-ideas` when you only need the current local inventory. It defaults to\nactive ideas and supports repeatable `--state`, `--all`, literal `--query`,\nRFC 3339 `--created-since` / `--created-before`, `--sort`, and `--limit`.\nUnlike lifecycle navigation, this read-only query uses the valid worktree\nsnapshot without checking branch, upstream, cleanliness, network, or primary\nsynchronization.\n\nThen create an idea and let the registered Silvermoon skill guide one safe\nnext action at a time:\n\n```sh\nsilvermoon create-idea\nsilvermoon whats-next <idea>\nsilvermoon whats-next <idea> --language zh-CN\n```\n\nDescribe the desired world in the generated `Idea.md`, review it, and approve\nthat exact revision. From then on, Silvermoon keeps the goal, implementation,\nrepository state, and real-world result connected. See\n[Getting Started](https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/docs/getting-started.md) for the complete first workflow.\nEvery command processes one ordered, versioned domain-message stream. Add\n`--json` when a programmatic consumer needs its four deterministic projections:\n`intention`, `observation`, `actions`, and `response`. Actions are side effects\nalready attempted; future work belongs only to `response.nextSteps`. Default\nMarkdown renders only the self-contained response instead of exposing the\ninternal projections. For pre-commit validation, run\n`silvermoon check --staged`: unlike the default `check` (committed `HEAD`), it\nchecks the index and exits `0` only when the project snapshot is valid. See the\n[Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/docs/reference.md) for validation targets and exit\ncodes.\n\nAdd `--trace <file.trace.jsonl>` to any command to write one schema-versioned\nJSONL timeline. Its `domain` channel contains allowlisted message summaries,\nand its `telemetry` channel contains paired performance spans; both share one\ntrace ID and global sequence. Trace output never includes guidance or file\ncontent, Git arguments/output, environment data, or credentials. If the\nargument does not end with the exact lowercase `.trace.jsonl` suffix,\nSilvermoon appends it. Repository-local `*.trace.jsonl` files are ignored.\nTrace files are buffered, created only after command work completes, and never\noverwrite an existing file.\n\nProjects may optionally add `.silvermoon/guidance/preparing.md`,\n`implementing.md`, and `deploying.md`. Silvermoon returns only the current\nactionable phase's snapshot-bound, repository-owned Markdown in\n`response.guidance`; `observation.guidance` carries its provenance without\ncontent. `create-idea` can return preparing guidance. This guidance is\nadditive, never a fourth contract or decision fact, and `check` validates the\ncomplete fixed directory. See [Core Concepts](https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/docs/core-concepts.md).\n\n## Why Silvermoon\n\nLong-running Agent work usually asks people to carry too much invisible state.\nSomeone must remember what was intended, whether the code still matches the\ntask, and which conversation or machine knows the latest truth. Silvermoon\nmakes those concerns part of the project instead.\n\nIt lets people step back from continuous supervision and return at the\ndecisions that belong to them: approving the intended outcome, accepting the\nimplementation, and accepting that the result is true in the outside world.\nBetween those boundaries, an Agent can inspect repository facts and continue\nthe highest-priority safe action.\n\nIt also refuses to let a detached task card declare success. Current artifacts\nand explicit decisions jointly determine state, so a changed goal or\nimplementation naturally invalidates conclusions that depended on the older\nrevision. Because those facts live in Git, work can continue across devices,\nsessions, Agents, and hosting platforms.\n\n## The Project's Artifact Spirit\n\n> Fellow Daoist, you wouldn't want your lifebound project to be without an\n> artifact spirit, would you?\n\n<table>\n  <tr>\n    <td width=\"160\" align=\"center\" valign=\"top\">\n      <!-- markdownlint-disable-next-line MD013 -->\n      <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\">\n    </td>\n    <td valign=\"top\">\n      Silvermoon is named after a character in <em>A Record of a Mortal's\n      Journey to Immortality</em>. She comes from the Silvermoon Wolf Clan in\n      the Spirit Realm and is one of the split souls of Ling Long. After losing\n      part of her memory in the human realm, she lives as an artifact spirit\n      first in a wolf-headed jade scepter and later in Han Li's Bamboo\n      Cloudswarm Swords.\n      <br><br>\n      That image fits this project: Silvermoon does not belong to one operator\n      or one chat. It lives with the project's artifacts, understands their\n      state, and helps each companion find what comes next. The biography is\n      inspiration, not a prerequisite for using the tool.\n    </td>\n  </tr>\n</table>\n\nWatch *A Record of a Mortal's Journey to Immortality*:\n\n<!-- markdownlint-disable-next-line MD013 -->\n- YouTube: [Episode 150: Overseas Turmoil 26](https://www.youtube.com/watch?v=GJgezoCBIHM \"A Record of a Mortal's Journey to Immortality — Episode 150: Overseas Turmoil 26\")\n<!-- markdownlint-disable-next-line MD013 -->\n- 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\")\n\n## From Ideal To Real\n\nA project is more than a task list or a transcript. It is an ideal becoming\nreal through three nested worlds.\n\n**Ideal World (道心)** names the outcome worth pursuing. **Inner World (内景)**\ngives that intent shape in repository artifacts. **Outer World (现世)** asks\nwhether the shaped work is true where it must actually operate.\n\n> 道心立意，内景成形，现世验真。\n\nThe worlds nest from the inside out. Implementation contains the ideal it\nserves, and deployment contains both. This is an engineering relationship, not\njust a metaphor: when an inner world changes, conclusions from an outer world\nno longer have the same foundation and must be proven again.\n\nHumans own approval and acceptance. Agents own continuation: they read the\ncontracts, the ledger, and Git facts; preserve concurrent work; execute one\nsafe action; and reobserve only after something changes. The context belongs to\nthe project, not to a fleeting conversation.\n\n## Further Reading\n\n- [Getting Started](https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/docs/getting-started.md) — installation, configuration,\n  and the first idea.\n- [Core Concepts](https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/docs/core-concepts.md) — project ownership, the three\n  worlds, revisions, and decision boundaries.\n- [Operating Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/docs/operations.md) — navigation, creation,\n  publication, hygiene, and continuation.\n- [Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/docs/reference.md) — storage, derived state, CLI\n  reports, validation targets, and schemas.\n- [Maintaining Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/9f6b61b1dfb05a0fb1e5c3eb77ad0a16105ffd0c/docs/maintaining.md) — development checks,\n  documentation ownership, and release guidance.\n",
   "readmeFilename": "README.md"
 }

package/skills/silvermoon/SKILL.md

@@ -45,11 +45,17 @@ override.
 
 `whats-next` may fetch and inspect but never changes files, branches, index, or
 refs. `create-idea` requires the configured primary branch and upstream plus a
-clean worktree; it does not fetch or compare ancestry. The target does not need
-a package manifest, package manager, Silvermoon dependency, or `node_modules`.
-The packaged skill is canonical; register it at `.agents/skills/silvermoon`
-with the supported `npx skills add` universal target. Silvermoon reports setup
-problems but does not repair them.
+clean worktree; it does not fetch or compare ancestry. A repository without a
+root `package.json` needs no package manager, Silvermoon dependency, or
+`node_modules`. When the root manifest exists, it must be valid JSON and declare
+`devDependencies.silvermoon` as exactly `^<running-version>`; follow the
+reported package-manager-specific remediation. Register npm projects' skill
+from `./node_modules/silvermoon/skills` after installing root dependencies.
+Other repositories use the skill bundled with the running installation.
+Snapshot checks do not require installed dependencies, and Silvermoon reports
+setup problems without modifying project files or registering skills. Register
+the canonical skill at `.agents/skills/silvermoon` with the supported
+`npx skills add` universal target.
 
 `check` validates only a project snapshot; it does not navigate ideas or check
 repository synchronization. Default `check` validates committed `HEAD`;

package/skills/silvermoon/references/adoption.md

@@ -15,10 +15,20 @@ when a programmatic consumer needs the complete
 The command may fetch after local readiness passes, but it does not move the
 worktree, index, branches, or named refs.
 
-The target repository may use any language or build ecosystem. It does not
-need `package.json`, a package manager, a Silvermoon dependency, or
-`node_modules`. Use any compatible Silvermoon installation, and register the
-canonical skill bundled with that running installation:
+The target repository may use any language or build ecosystem. If it has no
+root `package.json`, it does not need a package manager, a Silvermoon
+dependency, or `node_modules`. If a root manifest exists, Silvermoon requires
+valid JSON and `devDependencies.silvermoon` exactly equal to
+`^<running-version>`. Follow the reported package-manager-specific command.
+After installing root dependencies, register the canonical skill from the
+project-local package:
+
+```sh
+npx skills add ./node_modules/silvermoon/skills --skill silvermoon --agent universal --yes --copy
+```
+
+Non-npm repositories register the skill bundled with their running Silvermoon
+installation:
 
 ```sh
 npx skills add <path-to-running-silvermoon>/skills --skill silvermoon --agent universal --yes --copy

package/src/adoption.js

@@ -17,6 +17,22 @@ const packageRoot = fileURLToPath(new URL("..", import.meta.url));
 const packageJson = JSON.parse(await readFile(resolve(packageRoot, "package.json"), "utf8"));
 const packagedSkillsRoot = resolve(packageRoot, "skills");
 const packagedSkill = resolve(packagedSkillsRoot, "silvermoon");
+const localSkillsRoot = "./node_modules/silvermoon/skills";
+const dependencySections = [
+  "dependencies",
+  "devDependencies",
+  "peerDependencies",
+  "optionalDependencies",
+];
+const lockfileManagers = new Map([
+  ["package-lock.json", "npm"],
+  ["npm-shrinkwrap.json", "npm"],
+  ["pnpm-lock.yaml", "pnpm"],
+  ["yarn.lock", "yarn"],
+  ["bun.lock", "bun"],
+  ["bun.lockb", "bun"],
+]);
+const semverPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
 const utf8Decoder = new TextDecoder("utf-8", {
   fatal: true,
   ignoreBOM: true,
@@ -24,6 +40,320 @@ const utf8Decoder = new TextDecoder("utf-8", {
 
 export const SILVERMOON_VERSION = packageJson.version;
 export const REPOSITORY_SKILL_PATH = ".agents/skills/silvermoon";
+const expectedDependency = typeof SILVERMOON_VERSION === "string"
+  && semverPattern.test(SILVERMOON_VERSION)
+  ? `^${SILVERMOON_VERSION}`
+  : null;
+
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isSilvermoonSourceCheckout(root, manifest) {
+  const repositoryUrl = manifest.repository?.url;
+  if (
+    resolve(root) !== resolve(packageRoot)
+    || manifest.name !== "silvermoon"
+    || typeof repositoryUrl !== "string"
+  ) {
+    return false;
+  }
+  const normalizedUrl = repositoryUrl
+    .replace(/^git\+/, "")
+    .replace(/\.git$/, "");
+  return normalizedUrl === "https://github.com/shazhou-ww/silvermoon";
+}
+
+function workspaceRoot(manifest) {
+  if (!Object.hasOwn(manifest, "workspaces")) return false;
+  const workspaces = manifest.workspaces;
+  const packages = Array.isArray(workspaces)
+    ? workspaces
+    : isRecord(workspaces)
+      ? workspaces.packages
+      : null;
+  if (!Array.isArray(packages) || !packages.every((item) => typeof item === "string")) {
+    return null;
+  }
+  return packages.length > 0;
+}
+
+function packageManagerDescriptor(manager, workspace, reason = null) {
+  if (reason || !manager || workspace === null) {
+    return {
+      manager: null,
+      reason: reason ?? (workspace === null
+        ? "The root workspaces field is not in a recognized form."
+        : "The package manager could not be determined safely."),
+      workspace,
+    };
+  }
+  return {
+    manager,
+    reason: null,
+    workspace,
+  };
+}
+
+async function detectPackageManager(root, manifest) {
+  const workspace = workspaceRoot(manifest);
+  if (Object.hasOwn(manifest, "packageManager")) {
+    const declaration = manifest.packageManager;
+    const match = typeof declaration === "string"
+      ? /^(npm|pnpm|yarn|bun)@(.+)$/.exec(declaration)
+      : null;
+    if (!match || !semverPattern.test(match[2])) {
+      return packageManagerDescriptor(
+        null,
+        workspace,
+        `The root packageManager value ${JSON.stringify(declaration)} is unknown or invalid.`,
+      );
+    }
+    return packageManagerDescriptor(match[1], workspace);
+  }
+
+  const detected = [];
+  const uncertain = [];
+  for (const [filename, manager] of lockfileManagers) {
+    try {
+      const metadata = await lstat(resolve(root, filename));
+      if (metadata.isFile()) detected.push({ filename, manager });
+      else uncertain.push(filename);
+    } catch (caught) {
+      if (caught.code !== "ENOENT") uncertain.push(filename);
+    }
+  }
+  if (uncertain.length > 0) {
+    return packageManagerDescriptor(
+      null,
+      workspace,
+      `Cannot safely inspect root lockfile path(s): ${uncertain.join(", ")}.`,
+    );
+  }
+  const managers = [...new Set(detected.map(({ manager }) => manager))];
+  if (managers.length > 1) {
+    return packageManagerDescriptor(
+      null,
+      workspace,
+      `Conflicting root lockfiles identify ${managers.join(", ")}.`,
+    );
+  }
+  return packageManagerDescriptor(managers[0] ?? "npm", workspace);
+}
+
+export function dependencyInstallCommand(manager, workspace, version = SILVERMOON_VERSION) {
+  const packageSpecifier = `silvermoon@^${version}`;
+  if (manager === "npm") {
+    return { executable: "npm", args: ["install", "--save-dev", packageSpecifier] };
+  }
+  if (manager === "pnpm") {
+    return {
+      executable: "pnpm",
+      args: [
+        "add",
+        "--save-dev",
+        packageSpecifier,
+        ...(workspace ? ["--workspace-root"] : []),
+      ],
+    };
+  }
+  if (manager === "yarn") {
+    return {
+      executable: "yarn",
+      args: [
+        "add",
+        packageSpecifier,
+        "--dev",
+        ...(workspace ? ["--ignore-workspace-root-check"] : []),
+      ],
+    };
+  }
+  if (manager === "bun") {
+    return { executable: "bun", args: ["add", packageSpecifier, "--dev"] };
+  }
+  return null;
+}
+
+function renderCommand({ executable, args }) {
+  return [executable, ...args]
+    .map((argument) => argument.includes("^") || argument.includes(" ")
+      ? `"${argument.replaceAll('"', '\\"')}"`
+      : argument)
+    .join(" ");
+}
+
+export function renderDependencyCommand(manager, workspace, version = SILVERMOON_VERSION) {
+  const command = dependencyInstallCommand(manager, workspace, version);
+  return command ? renderCommand(command) : null;
+}
+
+function dependencyInstruction(packageManager) {
+  const command = packageManager.manager
+    ? renderDependencyCommand(
+      packageManager.manager,
+      packageManager.workspace,
+      SILVERMOON_VERSION,
+    )
+    : null;
+  if (!expectedDependency) {
+    return `The running Silvermoon version ${JSON.stringify(SILVERMOON_VERSION)} is not a supported SemVer version; repair the package before declaring its dependency.`;
+  }
+  if (!command) {
+    return `Do not guess a package-manager command. ${packageManager.reason} Resolve the root package-manager/workspace configuration, then add silvermoon@${expectedDependency} to the root devDependencies.`;
+  }
+  return `From the repository root, run \`${command}\` to set root devDependencies.silvermoon to ${expectedDependency}.`;
+}
+
+function skillInstruction(skill, packageManager) {
+  const registration = `npx skills add "${skill}" --skill silvermoon --agent universal --yes --copy`;
+  if (skill === packagedSkillsRoot) {
+    return `Run \`${registration}\`.`;
+  }
+  const install = packageManager.manager
+    ? `run \`${packageManager.manager} install\``
+    : "install dependencies with the resolved project package manager";
+  return `After you add the required Silvermoon devDependency and ${install} at the repository root, run \`${registration}\`.`;
+}
+
+export async function inspectNpmProject(
+  snapshotRoot,
+  repositoryRoot,
+  { readManifest = readFile } = {},
+) {
+  const manifestPath = resolve(snapshotRoot, "package.json");
+  let metadata;
+  try {
+    metadata = await lstat(manifestPath);
+  } catch (caught) {
+    if (caught.code === "ENOENT") return { npmProject: false, findings: [] };
+    return {
+      npmProject: true,
+      findings: [{
+        priority: 35,
+        problem: {
+          type: "npm-manifest-unreadable",
+          summary: `Cannot inspect the root package.json: ${caught.message}`,
+        },
+        instruction: "Repair access to the root package.json, then rerun Silvermoon.",
+      }],
+      manifest: null,
+      packageManager: { manager: null, reason: "The root manifest could not be read.", workspace: null },
+    };
+  }
+  if (!metadata.isFile()) {
+    return {
+      npmProject: true,
+      findings: [{
+        priority: 35,
+        problem: {
+          type: "npm-manifest-invalid",
+          summary: "The root package.json must be a regular file.",
+        },
+        instruction: "Replace the root package.json path with a readable regular JSON manifest.",
+      }],
+      manifest: null,
+      packageManager: { manager: null, reason: "The root manifest is not a regular file.", workspace: null },
+    };
+  }
+
+  let manifest;
+  try {
+    manifest = JSON.parse(await readManifest(manifestPath, "utf8"));
+  } catch (caught) {
+    const invalidJson = caught instanceof SyntaxError;
+    return {
+      npmProject: true,
+      findings: [{
+        priority: 35,
+        problem: {
+          type: invalidJson ? "npm-manifest-invalid" : "npm-manifest-unreadable",
+          summary: invalidJson
+            ? `The root package.json is not valid JSON: ${caught.message}`
+            : `Cannot read the root package.json: ${caught.message}`,
+        },
+        instruction: "Repair the root package.json as a readable JSON object, then rerun Silvermoon.",
+      }],
+      manifest: null,
+      packageManager: { manager: null, reason: "The root manifest could not be parsed.", workspace: null },
+    };
+  }
+  if (!isRecord(manifest)) {
+    return {
+      npmProject: true,
+      findings: [{
+        priority: 35,
+        problem: {
+          type: "npm-manifest-invalid",
+          summary: "The root package.json must contain a JSON object.",
+        },
+        instruction: "Replace the root package.json contents with a valid JSON object.",
+      }],
+      manifest: null,
+      packageManager: { manager: null, reason: "The root manifest is not a JSON object.", workspace: null },
+    };
+  }
+
+  const packageManager = await detectPackageManager(snapshotRoot, manifest);
+  const findings = [];
+  const sourceCheckout = isSilvermoonSourceCheckout(repositoryRoot, manifest);
+  if (!expectedDependency) {
+    findings.push({
+      priority: 35,
+      problem: {
+        type: "npm-runtime-version-invalid",
+        summary: `The running Silvermoon version ${JSON.stringify(SILVERMOON_VERSION)} is not a supported SemVer version.`,
+      },
+      instruction: "Use a Silvermoon package with a valid SemVer version before adopting this npm project.",
+    });
+  } else if (!sourceCheckout) {
+    const declarations = dependencySections
+      .filter((section) => isRecord(manifest[section]) && Object.hasOwn(manifest[section], "silvermoon"));
+    const hasDevDependency = declarations.includes("devDependencies");
+    const actual = isRecord(manifest.devDependencies)
+      ? manifest.devDependencies.silvermoon
+      : undefined;
+    if (!hasDevDependency) {
+      findings.push({
+        priority: 35,
+        problem: {
+          type: declarations.length > 0
+            ? "npm-dependency-wrong-section"
+            : "npm-dependency-missing",
+          summary: declarations.length > 0
+            ? "The root Silvermoon dependency must be declared in devDependencies."
+            : `The root devDependencies.silvermoon must be ${expectedDependency}.`,
+        },
+        instruction: dependencyInstruction(packageManager),
+      });
+    } else if (actual !== expectedDependency) {
+      findings.push({
+        priority: 35,
+        problem: {
+          type: "npm-dependency-version-mismatch",
+          summary: `The root devDependencies.silvermoon must be exactly ${expectedDependency}; found ${JSON.stringify(actual)}.`,
+        },
+        instruction: dependencyInstruction(packageManager),
+      });
+    }
+    if (declarations.length > 1) {
+      findings.push({
+        priority: 36,
+        problem: {
+          type: "npm-dependency-duplicate",
+          summary: `Silvermoon is declared in multiple root dependency sections: ${declarations.join(", ")}.`,
+        },
+        instruction: `Remove duplicate Silvermoon declarations and keep only devDependencies.silvermoon at ${expectedDependency}.`,
+      });
+    }
+  }
+  return {
+    npmProject: true,
+    findings,
+    manifest,
+    packageManager,
+    sourceCheckout,
+  };
+}
 
 function canonicalSkillBytes(content) {
   if (content.includes(0)) return content;
@@ -93,9 +423,6 @@ async function inspectSkill(contentRoot) {
         type: "canonical-skill-missing",
         summary: `Missing canonical Silvermoon skill at ${REPOSITORY_SKILL_PATH}.`,
       },
-      instruction:
-        `Run \`npx skills add "${packagedSkillsRoot}" --skill silvermoon `
-        + "--agent universal --yes --copy`.",
     };
   }
   if (!metadata.isDirectory() && !metadata.isSymbolicLink()) {
@@ -137,9 +464,6 @@ async function inspectSkill(contentRoot) {
           `${REPOSITORY_SKILL_PATH} does not match the canonical skill bundled `
           + `with Silvermoon ${SILVERMOON_VERSION}.`,
       },
-      instruction:
-        `Review local skill changes, then run \`npx skills add "${packagedSkillsRoot}" `
-        + "--skill silvermoon --agent universal --yes --copy`.",
     };
   }
   return { ok: true, digest: actualDigest };
@@ -180,16 +504,29 @@ export async function inspectAdoption({
     });
   }
 
+  const npm = await traceAsync(
+    "npm-project.inspect",
+    {},
+    () => inspectNpmProject(snapshotRoot, repositoryRoot),
+  );
+  findings.push(...npm.findings);
+  const skillSource = npm.npmProject && !npm.sourceCheckout
+    ? localSkillsRoot
+    : packagedSkillsRoot;
   const skill = await traceAsync(
     "skill.inspect",
     {},
-    () => inspectSkill(snapshotRoot),
+    () => inspectSkill(snapshotRoot, skillSource),
   );
   if (!skill.ok) {
     findings.push({
       priority: 40,
       problem: skill.problem,
-      instruction: skill.instruction,
+      instruction: skillInstruction(skillSource, npm.packageManager ?? {
+        manager: null,
+        reason: "The root package manager is unknown.",
+        workspace: null,
+      }),
     });
   }
   findings.sort((left, right) => left.priority - right.priority);

package/src/response.js

@@ -297,8 +297,59 @@ function responseTitle(response) {
   return localize(response.language, english, chinese);
 }
 
+function markdownTableCell(value) {
+  return String(value ?? "-")
+    .replaceAll("\\", "\\\\")
+    .replaceAll("|", "\\|")
+    .replaceAll(/\r?\n/g, " ");
+}
+
+function renderIdeaList(response, language) {
+  const headers = [
+    localize(language, "ID", "ID"),
+    localize(language, "Alias", "Alias"),
+    localize(language, "State", "状态"),
+    localize(language, "Created", "创建时间"),
+    localize(language, "Title", "标题"),
+  ];
+  const counts = Object.entries(response.inventory.counts)
+    .map(([state, count]) => `${state}=${count}`)
+    .join(", ");
+  const lines = [
+    `${response.summary} ${localize(language, "Counts", "计数")}: ${counts}.`,
+    "",
+    `| ${headers.join(" | ")} |`,
+    `| ${headers.map(() => "---").join(" | ")} |`,
+  ];
+  for (const idea of response.items) {
+    lines.push(
+      `| ${[
+        idea.id,
+        idea.alias,
+        idea.state,
+        idea.createdAt,
+        idea.title,
+      ].map(markdownTableCell).join(" | ")} |`,
+    );
+  }
+  if (response.items.length === 0) {
+    lines.push(
+      "",
+      localize(language, "No ideas matched.", "没有匹配的 idea。"),
+    );
+  }
+  return lines.join("\n");
+}
+
 export function renderResponse(response) {
   const language = response.language ?? DEFAULT_LANGUAGE;
+  if (response.kind === "idea-list") {
+    return [
+      `## ${responseTitle(response)}`,
+      "",
+      renderIdeaList(response, language),
+    ].join("\n");
+  }
   const lines = [`## ${responseTitle(response)}`, "", response.summary];
 
   if (response.inventory) {