@1agents/session-reader 0.6.1 → 0.6.2

package/README.md

@@ -71,6 +71,21 @@ npx @1agents/session-reader list      # 不安装直接用
 其他开关：`--agent claude,codex`（只装指定的几家，即使该智能体尚未安装也会建目录，
 方便先装 skill 后装智能体）、`--dry-run`（只说会做什么）、`--force`（覆盖同名条目）。
 
+**别用 `npx` 跑 `skill install`。** 默认的链接模式会指回包所在目录，而 npx 装的那份在
+`~/.npm/_npx/<hash>/` 的缓存里，npm 自己会清。清掉那天五家的 skill 一起静悄悄消失。
+先 `npm i -g` 再 `skill install`；实在要从 npx 引导就加 `--copy`，把字节交给各家自己拿着。
+
+传播给别人时，两行就够——第二行是大家会忘的那行：只装 CLI 的人得自己记着它存在，
+两行都跑了的人是智能体替他记着。
+
+```bash
+npm i -g @1agents/session-reader
+1session skill install
+```
+
+skill 自己也带着这套安装说明（`skills/1session/references/install.md`）：即便对方只拿到
+一份 SKILL.md、机器上没有 CLI，它也会先用 `npx` 把问题回答掉，再回头提一次永久安装。
+
 ## CLI
 
 ```bash
@@ -538,6 +553,21 @@ base_url  http://scott-mac.tailfb4720.ts.net:7777/v1   ← MagicDNS，跨机可
 > 而共用同一份定义才谈得上「公共语言」。**schema 是唯一事实源，改类型先去改那个包。**
 > `/manifest` 的 `metadata.protocol_version` 报告本服务遵循的协议版本。
 
+### SQLite 的 TEXT 列会在 NUL 处截断
+
+存进去 `A<NUL>B`，读出来只剩 `A`——**不报错**，安静地丢掉后面全部内容。
+实测一个 antigravity 会话里 `wsl -l -v` 的 UTF-16 输出被当 UTF-8 读，产生交错
+的 NUL，502 字符的 `tool_result` 存完只剩 342，后面 160 个字符凭空消失。
+
+改存 BLOB 能保真，但 `text` / `tool_result` 上有 SQL 搜索（`LIKE` 对 BLOB 不
+工作），所以走**写入转义、读取还原**（`src/store/nul.ts`）。引导符用 U+FFFF：
+Unicode 明确规定的 noncharacter，不会出现在有效文本里；万一真出现也会被双写，
+还原无歧义。绝大多数内容两个字符都不含，直接原样返回，常态零开销。
+
+这类 bug 的可怕之处在于**没有任何报错**——只有 round-trip 测试
+（`readSession(db,row)` 深度等于 `adapter.parse(candidate)`）能抓到它。
+那条断言就是整个索引层的安全网：一旦索引在改写事实而不是缓存事实，它就会红。
+
 ## 测试
 
 ```bash

package/dist/src/serve/http.js

@@ -172,7 +172,19 @@ export function createServer(options = {}) {
 export async function serve(options = {}) {
     const host = options.host ?? '127.0.0.1';
     const server = createServer(options);
-    await new Promise((resolve) => server.listen(options.port ?? DEFAULT_PORT, host, resolve));
+    // 请求的端口。实际绑定到哪个从 server.address() 读——传 0 时它是随机的。
+    const wanted = options.port ?? DEFAULT_PORT;
+    // 端口占用是最常见的启动失败，默认会抛一整屏 Node 栈——对着栈猜"是不是
+    // 已经起了一个"没意义，直接说清楚怎么办。
+    await new Promise((resolve, reject) => {
+        server.once('error', (error) => {
+            reject(error.code === 'EADDRINUSE'
+                ? new Error(`端口 ${wanted} 已被占用。换一个：--port <n>；或先停掉占用它的进程：` +
+                    `lsof -nP -iTCP:${wanted} -sTCP:LISTEN`)
+                : error);
+        });
+        server.listen(wanted, host, resolve);
+    });
     const { port } = server.address();
     const identity = await nodeIdentity();
     // 只听回环的服务，外部发现得了却连不上——如实说，别让调用方白跑一趟。

package/dist/src/store/nul.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 写进 SQLite 的 TEXT 列之前调用。
+ *
+ * 绝大多数内容两个字符都不含，直接原样返回——所以常态是零拷贝。
+ */
+export declare function encodeText(value: string): string;
+export declare function encodeText(value: string | null | undefined): string | null;
+/** 从 SQLite 的 TEXT 列读出来之后调用。 */
+export declare function decodeText(value: string): string;
+export declare function decodeText(value: string | null | undefined): string | null;
+/** 测试与诊断用：这段文本经过 SQLite 的 TEXT 列会不会被截断。 */
+export declare function wouldTruncate(value: string): boolean;

package/dist/src/store/nul.js

@@ -0,0 +1,52 @@
+/**
+ * SQLite 的 TEXT 列在第一个 NUL 处截断——不报错，安静地丢掉后面全部内容。
+ *
+ * 实测：一个 antigravity 会话里 `wsl -l -v` 的 UTF-16 输出被当 UTF-8 读，产生
+ * 交错的 NUL；502 字符的 tool_result 存进索引再读出来只剩 342，后面 160 个
+ * 字符凭空消失。round-trip 测试因此长期飘红，而失败信息指向的是内容本身，
+ * 很难看出是存储层干的。
+ *
+ * 改存 BLOB 能保真，但 `text` / `tool_result` 上有 SQL 搜索（`LIKE` 对 BLOB
+ * 不工作），所以改成**写入时转义、读取时还原**。
+ *
+ * 引导符用 U+FFFF：Unicode 明确规定的 noncharacter，不会出现在有效文本里；
+ * 万一真出现也会被双写，所以还原无歧义。
+ *
+ * 两个常量用 `String.fromCharCode` 而不是字面量，免得源文件里真带上这些
+ * 字符——它们在编辑器、diff、终端里都是隐形的。
+ */
+const NUL = String.fromCharCode(0x00);
+const LEAD = String.fromCharCode(0xffff);
+const ESCAPED_NUL = `${LEAD}0`;
+const ESCAPED_LEAD = `${LEAD}${LEAD}`;
+export function encodeText(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (!value.includes(NUL) && !value.includes(LEAD))
+        return value;
+    // 顺序要紧：先把引导符自己双写，再拿它去转义 NUL。反过来会把刚写出的
+    // 转义序列又转义一遍。
+    return value.split(LEAD).join(ESCAPED_LEAD).split(NUL).join(ESCAPED_NUL);
+}
+export function decodeText(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (!value.includes(LEAD))
+        return value;
+    let out = '';
+    for (let i = 0; i < value.length; i++) {
+        if (value[i] !== LEAD) {
+            out += value[i];
+            continue;
+        }
+        const next = value[++i];
+        // 双写还原成引导符本身；LEAD+'0' 还原成 NUL；落单的引导符原样留着，
+        // 宁可多留一个字符，也不要把不认识的序列吞掉。
+        out += next === LEAD ? LEAD : next === '0' ? NUL : LEAD + (next ?? '');
+    }
+    return out;
+}
+/** 测试与诊断用：这段文本经过 SQLite 的 TEXT 列会不会被截断。 */
+export function wouldTruncate(value) {
+    return value.includes(NUL);
+}

package/dist/src/store/read.js

@@ -1,3 +1,4 @@
+import { decodeText } from './nul.js';
 import { turnStartsFrom } from '../turns.js';
 import { emptyProviderStats, } from '../types.js';
 export function sessionRow(db, id) {
@@ -70,7 +71,7 @@ export function refOf(row) {
         id: row.native_id,
         provider: row.provider,
         path: row.source_path,
-        ...(row.title === null ? {} : { title: row.title }),
+        ...(row.title === null ? {} : { title: decodeText(row.title) }),
         ...(row.workspace === null ? {} : { workspace: row.workspace }),
         ...(row.started_at === null ? {} : { createdAt: row.started_at }),
         ...(row.ended_at === null ? {} : { updatedAt: row.ended_at }),
@@ -89,12 +90,12 @@ function eventsOf(db, id, nativeId) {
         id: `${nativeId}#${row.idx}`,
         index: row.idx,
         kind: row.kind,
-        ...(row.text === null ? {} : { text: row.text }),
+        ...(row.text === null ? {} : { text: decodeText(row.text) }),
         ...(row.tool_name === null ? {} : { toolName: row.tool_name }),
         ...(row.tool_args_json === null
             ? {}
             : { toolArgs: JSON.parse(row.tool_args_json) }),
-        ...(row.tool_result === null ? {} : { toolResult: row.tool_result }),
+        ...(row.tool_result === null ? {} : { toolResult: decodeText(row.tool_result) }),
         ...(row.is_error === null ? {} : { isError: row.is_error === 1 }),
         ...(row.ts === null ? {} : { timestamp: row.ts }),
         ...(row.source_index === null ? {} : { sourceIndex: row.source_index }),

package/dist/src/store/schema.d.ts

@@ -7,7 +7,7 @@
  * the behaviour — never derive them from a git hash, `dist` ships without git.
  */
 /** DDL layout. A bump drops and rebuilds the whole database. */
-export declare const SCHEMA_VERSION = 1;
+export declare const SCHEMA_VERSION = 2;
 /** L1 semantics — anything in `parsers/` that changes normalized events. */
 export declare const PARSER_VERSION = 3;
 /** L2 rules — `writes.ts` / `ledger.ts`. Re-derives facts from stored events. */

package/dist/src/store/schema.js

@@ -7,7 +7,7 @@
  * the behaviour — never derive them from a git hash, `dist` ships without git.
  */
 /** DDL layout. A bump drops and rebuilds the whole database. */
-export const SCHEMA_VERSION = 1;
+export const SCHEMA_VERSION = 2;
 /** L1 semantics — anything in `parsers/` that changes normalized events. */
 export const PARSER_VERSION = 3;
 /** L2 rules — `writes.ts` / `ledger.ts`. Re-derives facts from stored events. */

package/dist/src/store/write.js

@@ -1,3 +1,4 @@
+import { encodeText } from './nul.js';
 import fs from 'node:fs';
 import crypto from 'node:crypto';
 import { PARSER_VERSION } from './schema.js';
@@ -51,7 +52,7 @@ export function writeSession(db, session, fingerprint, turnCount) {
          id, provider, native_id, source_path, workspace, title, started_at, ended_at,
          event_count, turn_count, source_size, source_mtime_ms, head_hash, aux_fingerprint,
          parser_version, extractor_version, edge_version, indexed_at, artifacts_json, stats_json
-       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0, 0, ?, ?, ?)`).run(id, session.ref.provider, session.ref.id, session.ref.path, session.ref.workspace ?? null, session.ref.title ?? null, session.ref.createdAt ?? null, session.ref.updatedAt ?? null, session.turns.length, turnCount, fingerprint.sourceSize, fingerprint.sourceMtimeMs, fingerprint.headHash, fingerprint.auxFingerprint ?? null, PARSER_VERSION, new Date().toISOString(), JSON.stringify(session.artifacts), JSON.stringify(session.stats));
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0, 0, ?, ?, ?)`).run(id, session.ref.provider, session.ref.id, session.ref.path, session.ref.workspace ?? null, encodeText(session.ref.title), session.ref.createdAt ?? null, session.ref.updatedAt ?? null, session.turns.length, turnCount, fingerprint.sourceSize, fingerprint.sourceMtimeMs, fingerprint.headHash, fingerprint.auxFingerprint ?? null, PARSER_VERSION, new Date().toISOString(), JSON.stringify(session.artifacts), JSON.stringify(session.stats));
         const insert = db.prepare(`INSERT INTO events (
          session_id, idx, kind, text, tool_name, tool_args_json, tool_result, is_error,
          ts, source_index, exit_code, pid, duration_ms, provider_truncated
@@ -60,7 +61,7 @@ export function writeSession(db, session, fingerprint, turnCount) {
         // 0.08% and silently dropped search hits from long build logs — exactly
         // the kind of "looks complete, isn't" answer this store exists to remove.
         for (const event of session.turns) {
-            insert.run(id, event.index, event.kind, event.text ?? null, event.toolName ?? null, event.toolArgs ? JSON.stringify(event.toolArgs) : null, event.toolResult ?? null, event.isError === undefined ? null : event.isError ? 1 : 0, event.timestamp ?? null, event.sourceIndex ?? null, event.exitCode ?? null, event.processId ?? null, event.durationMs ?? null, event.truncated === undefined ? null : event.truncated ? 1 : 0);
+            insert.run(id, event.index, event.kind, encodeText(event.text), event.toolName ?? null, event.toolArgs ? JSON.stringify(event.toolArgs) : null, encodeText(event.toolResult), event.isError === undefined ? null : event.isError ? 1 : 0, event.timestamp ?? null, event.sourceIndex ?? null, event.exitCode ?? null, event.processId ?? null, event.durationMs ?? null, event.truncated === undefined ? null : event.truncated ? 1 : 0);
         }
         db.exec('COMMIT');
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1agents/session-reader",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Read Plane: cross-agent session discovery, turn inspection, workspace aggregation and distillation from raw local session files.",
   "keywords": [
     "claude-code",
@@ -60,6 +60,6 @@
   },
   "dependencies": {
     "@1agents/dreammate-network": "^0.3.0",
-    "@1agents/dreammate-node": "^0.3.0"
+    "@1agents/dreammate-node": "^0.4.0"
   }
 }

package/skills/1session/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: 1session
-description: Search and read the user's past AI coding sessions across Claude Code, Codex, Antigravity, Grok and DeepSeek Harness (dsh) from their raw local session files, using the `1session` CLI. Use this whenever the user refers to work they did in an earlier session rather than in this conversation — "上次/之前/昨天我们改了什么", "那个报错后来怎么解决的", "我在哪个会话里提过 X", "这个功能是哪一轮加的", "codex 那边做到哪了", "grok/dsh 那边呢", "跨项目找一下", "整理一下最近几天的会话/写个周报". Also reach for it proactively, before asking the user to re-explain context they have obviously already established with some agent on this machine — the answer is usually already on disk. Read-only: it never modifies or resumes a session.
+description: Search and read the user's past AI coding sessions across Claude Code, Codex, Antigravity, Grok and DeepSeek Harness (dsh) from their raw local session files, using the `1session` CLI. Use this whenever the user refers to work they did in an earlier session rather than in this conversation — "上次/之前/昨天我们改了什么", "那个报错后来怎么解决的", "我在哪个会话里提过 X", "这个功能是哪一轮加的", "codex 那边做到哪了", "grok/dsh 那边呢", "跨项目找一下", "整理一下最近几天的会话/写个周报". Also reach for it proactively, before asking the user to re-explain context they have obviously already established with some agent on this machine — the answer is usually already on disk. Read-only: it never modifies or resumes a session. This skill also covers getting itself running and spreading to other agents: when the `1session` CLI is missing it falls back to `npx` on the spot, and it knows how to install the package globally and push the skill into all five agents at once — so use it too when the user asks to install, upgrade, uninstall, share or distribute 1session / session-reader, or reports that the `1session` command is not found.
 ---
 
 # 1session — the cross-agent Read Plane
@@ -19,15 +19,52 @@ normalizes all of them and answers questions about what actually happened.
 Everything is derived from the raw files at read time. Nothing is written back to
 them, no daemon is involved, and no session is ever resumed or modified.
 
-## Before the first call
+## Bootstrap: get the CLI, then answer the question
 
-Run `1session help`. If the command is missing, fall back to
-`npx -y @1agents/session-reader` in place of `1session` everywhere below, and
-mention the one-time fix once: `npm i -g @1agents/session-reader`.
+This skill travels on its own. Someone may have dropped `SKILL.md` into an agent
+on a machine where the `1session` CLI does not exist, so the first call is a
+probe rather than an assumption:
 
-The first run on a machine parses every session (~10s for a few hundred); after
-that an index makes each call sub-second. If a call feels slow, it is that first
-build, not a hang.
+```bash
+1session help
+```
+
+If that fails, **do not stop to install before answering.** `npx` runs the same
+CLI with nothing installed:
+
+```bash
+npx -y @1agents/session-reader@latest list --global --limit 10
+```
+
+Substitute `npx -y @1agents/session-reader@latest` for `1session` everywhere
+below, answer the question the user actually asked, and offer the permanent
+install once, afterwards. Someone asking where last week's bug got fixed wants
+the bug, not a setup errand.
+
+The permanent install, when they want it:
+
+```bash
+npm i -g @1agents/session-reader   # requires Node >= 22.15
+1session skill install             # put this skill into every agent on the machine
+```
+
+Node below 22.15 is a hard stop rather than a warning — the reader needs
+`node:sqlite` for the index and `node:zlib`'s zstd to read dsh's compressed
+sessions, and `npx` does not rescue an old runtime either. Check `node -v`, say
+plainly that Node needs upgrading, and don't improvise around it.
+
+That second command is what makes this spread: one run installs the skill into
+Claude Code, Codex, Antigravity, Grok and dsh at once, so whichever agent the
+user opens next already knows their history is readable. Run it after a global
+install, **not** through `npx` — npx installs the package into a cache directory
+that npm later garbage-collects, and the skill links would dangle with it.
+
+`references/install.md` has the rest: PATH and permission failures, link vs copy,
+upgrading, uninstalling, and what to hand someone who wants this on their own
+machine. Read it when an install misbehaves or the user asks how to share this.
+
+The first real run parses every session (~10s for a few hundred); an index makes
+each call after that sub-second. A slow first call is that build, not a hang.
 
 ## Pick the command from the question
 

package/skills/1session/evals/evals.json

@@ -42,6 +42,48 @@
         "Gives a drill-down handle — a turn/event number or an exact command the user can run to see the evidence",
         "Reports how it was verified (tests green / the commit) rather than only describing the change"
       ]
+    },
+    {
+      "id": 3,
+      "name": "missing-cli-still-answers",
+      "prompt": "上周我在这台机器上调一个超时的问题，后来是怎么解决的？（顺便说一句，我这台机器上好像没装过什么 1session，`1session` 这个命令敲下去是 command not found）",
+      "expected_output": "Recognizes the CLI is absent, immediately falls back to `npx -y @1agents/session-reader@latest ...` to actually answer the timeout question, and only then mentions the permanent install as a one-time follow-up — rather than stopping to install first or declaring it cannot help.",
+      "files": [],
+      "assertions": [
+        "Falls back to npx (`npx -y @1agents/session-reader@latest ...`) instead of stopping at the missing command",
+        "Actually attempts to answer the user's timeout question rather than turning the turn into a setup errand",
+        "Mentions the permanent install (`npm i -g @1agents/session-reader`) as an optional follow-up, not as a precondition",
+        "Does not run a global npm install without the user agreeing to it first",
+        "Does not claim the question is unanswerable because the CLI is missing"
+      ]
+    },
+    {
+      "id": 4,
+      "name": "distribute-to-a-colleague",
+      "prompt": "同事看我能翻出以前会话的记录，也想在他 mac 上用。我要发给他什么？他那边只装了 claude code 和 codex，另外他 node 好像还是 20。",
+      "expected_output": "Gives the two-line install (npm i -g, then `1session skill install`), explains that the second line is what puts the skill into Claude Code and Codex, and flags that Node 20 is below the 22.15 floor so he must upgrade Node first — npx will not work around it either.",
+      "files": [],
+      "assertions": [
+        "Gives `npm i -g @1agents/session-reader` as the install command",
+        "Includes `1session skill install` and explains it is what puts the skill into the colleague's agents, not just the CLI",
+        "Flags Node 20 as below the >= 22.15 requirement and says it must be upgraded",
+        "Does not suggest npx as a way around the old Node version (it runs on the same runtime and fails identically)",
+        "Does not invent an install path that does not exist (no curl|sh script, no brew formula, no manual git clone as the primary route)"
+      ]
+    },
+    {
+      "id": 5,
+      "name": "npx-skill-install-trap",
+      "prompt": "我不想全局装东西，能不能直接用 npx 把这个 skill 装到我的 claude 和 codex 里就好？",
+      "expected_output": "Warns that `skill install` in its default link mode would point at the npx cache directory, which npm garbage-collects — the skill would silently vanish later. Offers `--copy` as the npx-compatible route, or a global install as the robust one.",
+      "files": [],
+      "assertions": [
+        "Warns that a link-mode install via npx points into the npx cache (~/.npm/_npx/...) which npm later prunes",
+        "Names the consequence concretely: the skill silently disappears from the agents afterwards",
+        "Offers `--copy` as the way to make an npx-based install survive, and/or a global install as the robust alternative",
+        "Mentions `--agent claude,codex` or otherwise respects that the user only wants those two",
+        "Does not simply tell the user to run `npx ... skill install` with no caveat"
+      ]
     }
   ]
-}
+}

package/skills/1session/references/install.md

@@ -0,0 +1,195 @@
+# Installing and spreading 1session
+
+Read this when the probe in SKILL.md fails in a way the two-line fallback does
+not cover, or when the user asks how to get this onto another machine or into
+another agent.
+
+- [What it needs](#what-it-needs)
+- [Three ways to run it](#three-ways-to-run-it)
+- [Spreading the skill to every agent](#spreading-the-skill-to-every-agent)
+- [Upgrading](#upgrading)
+- [Uninstalling](#uninstalling)
+- [Handing it to someone else](#handing-it-to-someone-else)
+- [Troubleshooting](#troubleshooting)
+
+## What it needs
+
+**Node.js >= 22.15**, and nothing else. The version floor is real, not
+defensive: the index is `node:sqlite` and dsh's sessions are zstd-compressed,
+which only landed in `node:zlib` in 22.15. On an older runtime the package
+installs and then fails at the first call, so check first:
+
+```bash
+node -v
+```
+
+If it is below 22.15, say so and stop. `npx` runs the same code on the same
+runtime and will fail identically — there is no way around it except upgrading
+Node (`nvm install 22`, `brew upgrade node`, or whatever that machine uses).
+
+Everything else is already on the machine. The only runtime dependency is
+`@1agents/dreammate-network` (12 kB, zero dependencies of its own), which npm
+pulls in automatically. There is no daemon, no service to start, no config file,
+and no account. The reader opens session files the agents already wrote and
+never writes back to them.
+
+macOS, Linux and WSL all work. On native Windows the paths it reads
+(`~/.claude`, `~/.codex`, …) resolve through `os.homedir()`, but it is the least
+exercised platform — if something looks wrong there, check that the agent in
+question actually stores sessions under the Windows home directory before
+assuming the reader is broken.
+
+## Three ways to run it
+
+**Zero install (`npx`).** Correct for a one-off answer, for a machine you are
+only visiting, and for the first call before anyone has agreed to install
+anything:
+
+```bash
+npx -y @1agents/session-reader@latest list --global --limit 10
+```
+
+Every command in SKILL.md works with this prefix substituted for `1session`.
+The cost is a few seconds of download per invocation and a cache directory npm
+cleans up on its own schedule — fine for answering, wrong as a permanent setup
+(see the warning under [spreading](#spreading-the-skill-to-every-agent)).
+
+**Global install.** The normal choice for a machine the user works on daily:
+
+```bash
+npm i -g @1agents/session-reader
+1session help          # verify: prints the command list
+```
+
+**As a library.** The parsers and ledgers are exported, so a script can consume
+sessions without shelling out:
+
+```bash
+npm i @1agents/session-reader
+```
+
+```js
+import { listSessions } from '@1agents/session-reader';
+```
+
+Reach for this only when the user is building something on top of session data.
+For answering questions about the past, the CLI is both cheaper and denser.
+
+## Spreading the skill to every agent
+
+The package ships this skill inside it, and the CLI installs it into every
+agent's skills directory in one call:
+
+```bash
+1session skill install     # all agents found on this machine
+1session skill status      # what is installed where, and whether it is current
+1session skill uninstall   # remove it again
+```
+
+| Agent | Where it lands |
+| --- | --- |
+| claude | `~/.claude/skills/1session` |
+| codex | `~/.codex/skills/1session` |
+| antigravity | `~/.gemini/antigravity/skills/1session` (**not** `~/.gemini/skills`, which is gemini-cli's) |
+| grok | `~/.grok/skills/1session` |
+| dsh | `~/.dsh/skills/1session` |
+
+All five load `<dir>/<name>/SKILL.md` with the same YAML frontmatter, so it is
+genuinely one file serving five agents, not five ports of it.
+
+**Do not run `skill install` through `npx`.** In link mode — the default — the
+installed entry is a symlink back to wherever the package lives, and under npx
+that is a cache directory like `~/.npm/_npx/<hash>/node_modules/…` which npm
+garbage-collects. The skill works right up until the day the cache is pruned and
+then silently disappears from all five agents. Install the package globally
+first and then run `skill install`; if you truly must bootstrap through npx, use
+`--copy` so the bytes are owned by the agent rather than borrowed from a cache.
+
+Link mode is otherwise the better default: after `npm i -g …@latest`, every
+agent is already looking at the new skill with nothing to re-run. Use `--copy`
+when an agent's loader does not follow symlinks — the symptom is `skill status`
+reporting a healthy link while the agent itself never mentions the skill. The
+cost of a copy is that upgrades no longer propagate; `skill status` marks a copy
+that has drifted from the installed package, so the drift is visible rather than
+silent.
+
+Other flags:
+
+| Flag | Why |
+| --- | --- |
+| `--agent claude,codex` | Only these. Named agents get their skills directory created even if the agent is not installed yet, which is how you set a machine up before installing the agent. |
+| `--copy` | Copy instead of symlink. |
+| `--force` | Overwrite a same-named entry that this installer did not create, or convert an existing copy into a link. Without it, both cases are refused rather than clobbered. |
+| `--dry-run` | Print the plan and touch nothing. Worth doing first on someone else's machine. |
+| `--json` | Machine-readable result. |
+
+Agents that are not installed are skipped rather than failed, so a machine with
+only Claude Code reports three skips and one install, and that is success.
+
+## Upgrading
+
+```bash
+npm i -g @1agents/session-reader@latest
+```
+
+Linked skills are current the moment that finishes. Copied ones need
+`1session skill install --copy --force` afterwards; `1session skill status` is
+what tells you which case you are in.
+
+The index rebuilds itself when the parser version moves, so an upgrade that
+changes how sessions are read costs one slower call and needs no manual
+clearing. To force it: `1session index --all --global`.
+
+## Uninstalling
+
+```bash
+1session skill uninstall         # remove the skill from the agents
+npm rm -g @1agents/session-reader
+rm -rf ~/.1agents/session-reader # the index; sessions themselves are untouched
+```
+
+`skill uninstall` only removes entries it could have created (its own links and
+copies); anything else needs `--force`, which exists so a hand-written skill of
+the same name is never deleted by accident. Nothing here touches the agents'
+session files — the reader has never written to them.
+
+## Handing it to someone else
+
+The whole thing is one npm package, so the shortest correct instruction is two
+lines:
+
+```bash
+npm i -g @1agents/session-reader
+1session skill install
+```
+
+That is the version to paste into a chat or a README. It gets them the CLI and
+puts the skill into every agent they have, which is the part people forget: a
+colleague who installs only the CLI has to remember it exists, while one who ran
+both lines has their agent remember for them.
+
+If they cannot install globally (locked-down machine, shared box), the npx form
+plus `skill install --copy` gets them to the same place with the package living
+in a cache instead of `/usr/local`.
+
+If they want to read the source or file a bug:
+<https://github.com/scottzx/session-reader>.
+
+When you are the one setting this up on a user's machine, prefer offering these
+commands over running them unasked — a global npm install changes their system.
+Running the read-only CLI to answer a question is not the same kind of act as
+installing software, and the difference is worth respecting.
+
+## Troubleshooting
+
+| Symptom | What is actually wrong |
+| --- | --- |
+| `1session: command not found` right after `npm i -g` | npm's global bin directory is not on `PATH`. It is `$(npm prefix -g)/bin` — `npm bin -g` was removed in npm 9, so use the prefix form — and it goes in the shell profile. Meanwhile `npx -y @1agents/session-reader@latest …` works unchanged. |
+| `EACCES` / permission denied during `npm i -g` | The global prefix is root-owned. Do not reach for `sudo npm` — repoint the prefix (`npm config set prefix ~/.npm-global`, then put `~/.npm-global/bin` on `PATH`) or use a Node version manager, both of which leave the system directories alone. |
+| Installs fine, then throws on the first real command | Almost always Node < 22.15 — `node:sqlite` or zstd missing. Check `node -v`. |
+| `skill status` shows a healthy link, but the agent never uses the skill | That agent's loader does not follow symlinks. `1session skill install --copy --force`. |
+| The skill vanished from every agent at once | It was installed in link mode from an npx cache that npm has since pruned. Install the package globally, then `1session skill install --force`. |
+| `skill install` reports `blocked` | Something else already owns that name — a hand-written skill, or a copy where a link is wanted. Look at it before passing `--force`. |
+| The first call takes ~10s | That is the initial index build over every session on the machine, not a hang. Subsequent calls are sub-second. |
+| Results look stale or wrong | `1session index --all --global` rebuilds, and `--no-index` on any command reads the raw files directly — if those two disagree, that is a real bug worth reporting. |
+| `list` returns nothing in a directory that definitely had sessions | Scope, not installation. `list` defaults to the pwd subtree; add `--global`. |