@christang/keel 5.73.0 → 5.74.0

package/README.md

@@ -46,22 +46,31 @@ Node.js `>=20.19.0` (the bundled OpenSpec CLI needs it).
 
 ## Install
 
-Two pieces: the `keel` CLI and the `keel` plugin.
-
-**CLI** — one command (also installs the bundled OpenSpec CLI):
+**Claude Code** — the plugin is the whole install. It is the published `@christang/keel`
+package, so it carries the `keel` CLI and the bundled OpenSpec along with the skills and hooks,
+and the agent's `keel` commands run the copy the plugin brought:
 
 ```bash
-npm install -g @christang/keel
-keel --version
+claude plugin marketplace add TanglmChris/keel
+claude plugin install keel@keel-marketplace
 ```
 
-**Plugin** — the execution skills and runtime hooks:
+After an update, `/reload-plugins` applies it in the running session; otherwise it applies at the
+next start.
+
+**Codex, and your own terminal** — install the CLI as well (it also installs the bundled
+OpenSpec CLI):
 
 ```bash
-claude plugin install keel@<marketplace>   # Claude Code
+npm install -g @christang/keel
+keel --version
 codex plugin add keel@<marketplace>        # Codex
 ```
 
+A global `keel` comes first on PATH, ahead of the plugin's copy, so on Claude Code the agent runs
+it instead. Keep it at the plugin's version or remove it (`npm rm -g @christang/keel`); the
+session-start line names it whenever the two disagree.
+
 <details>
 <summary>Install the latest unreleased build from GitHub</summary>
 

package/README.zh-CN.md

@@ -38,22 +38,27 @@ Node.js `>=20.19.0`（内置的 OpenSpec CLI 需要）。
 
 ## 安装
 
-两部分：`keel` CLI 和 `keel` 插件。
-
-**CLI** —— 一条命令（同时装上捆绑的 OpenSpec CLI）：
+**Claude Code** —— 装插件就够了。插件本身就是发布的 `@christang/keel` 包，技能和 hook 之外还带着
+`keel` CLI 和捆绑的 OpenSpec；agent 运行的 `keel` 就是插件带来的这一份：
 
 ```bash
-npm install -g @christang/keel
-keel --version
+claude plugin marketplace add TanglmChris/keel
+claude plugin install keel@keel-marketplace
 ```
 
-**插件** —— 执行技能和运行时 hook：
+更新之后，在当前会话执行 `/reload-plugins` 即可生效；不执行的话，下次启动时生效。
+
+**Codex，以及你自己的终端** —— 另外装一份 CLI（同时装上捆绑的 OpenSpec CLI）：
 
 ```bash
-claude plugin install keel@<marketplace>   # Claude Code
+npm install -g @christang/keel
+keel --version
 codex plugin add keel@<marketplace>        # Codex
 ```
 
+全局装的 `keel` 在 PATH 里排在插件那份前面，所以在 Claude Code 里 agent 会用它。要么让它和插件同版本，
+要么卸掉（`npm rm -g @christang/keel`）；两者版本不一致时，会话启动那一行会指出来。
+
 > 捆绑的 OpenSpec 依赖在安装时会打印一行 opt-in 的 shell 补全提示。如果你的 npm 拦截安装脚本，
 > 这行提示会被跳过，它纯属装饰，keel 照常工作。
 

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.73.0 -->
+<!-- keel:start version=5.74.0 -->
 ## Keel Bootstrap
 
 - Start every session with `keel context`; OpenSpec artifacts and Git are the only durable authority — never native memory, goals, or transcripts.

package/bin/keel

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+"use strict";
+
+// The bare `keel` a Claude plugin's `bin/` puts on the agent's PATH (#164).
+// On Claude the plugin is this published package, and the host adds `bin/`
+// to PATH by file name, so `keel.js` alone would answer to `keel.js`. npm's
+// own `bin` map keeps pointing at `keel.js`; this file only gives the plugin
+// the same name.
+require("./keel.js");

package/bin/keel.js

@@ -769,21 +769,28 @@ function openspecReportedVersion(command) {
 // project that does not depend on OpenSpec directly. A lockfile that exists and
 // cannot be parsed is a read failure. Collapsing them would either warn at
 // everyone or hide a real failure.
+//
+// The lockfile is the one npm installs from: `npm-shrinkwrap.json` when it
+// exists, else `package-lock.json`. A package that publishes itself — Keel
+// does since #164 — carries the shrinkwrap, because npm never publishes a
+// `package-lock.json`.
 function declaredOpenSpecVersion(repo) {
-  const lockPath = path.join(repo, "package-lock.json");
-  if (!fs.existsSync(lockPath)) return { state: "none", version: null };
+  const lockName = ["npm-shrinkwrap.json", "package-lock.json"].find((name) =>
+    fs.existsSync(path.join(repo, name))
+  );
+  if (!lockName) return { state: "none", version: null, lockName: null };
   let lock;
   try {
-    lock = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+    lock = JSON.parse(fs.readFileSync(path.join(repo, lockName), "utf8"));
   } catch {
-    return { state: "unreadable", version: null };
+    return { state: "unreadable", version: null, lockName };
   }
   for (const [name, entry] of Object.entries(lock.packages || {})) {
     if (name.endsWith("@fission-ai/openspec") && entry && entry.version) {
-      return { state: "declared", version: entry.version };
+      return { state: "declared", version: entry.version, lockName };
     }
   }
-  return { state: "none", version: null };
+  return { state: "none", version: null, lockName };
 }
 
 // "Not installed" and "installed and Keel cannot reach it" need different
@@ -1686,7 +1693,7 @@ function runDoctor(options) {
     const declaredText = {
       declared: `repo pins ${declared.version}`,
       none: "repo declares no OpenSpec version",
-      unreadable: "repo package-lock.json unreadable",
+      unreadable: `repo ${declared.lockName} unreadable`,
     }[declared.state];
     const versions = `${resolvedVersion || "version unreadable"}, ${declaredText}`;
     printDoctorLine(