skills-viewer 0.8.0 → 0.9.0

package/README.md

@@ -1,8 +1,8 @@
 # skills-viewer
 
-Browse, search and manage your [Claude Code](https://code.claude.com) skills, commands, agents, hooks and auto memory in the browser.
+Read, search and diagnose your [Claude Code](https://code.claude.com) skills, commands, agents, hooks, auto memory and CLAUDE.md in the browser.
 
-Scans every project registered in `~/.claude.json` (plus user scope, plugins and built-ins), and serves a local web UI to explore them — with usage stats, AI-generated summaries, full SKILL.md rendering, same-name diffs, and copy/delete management.
+Scans every project registered in `~/.claude.json` (plus user scope, plugins and built-ins), and serves a local web UI to explore them — with usage stats, AI-generated summaries, full SKILL.md rendering and same-name diffs. It reads and explains; changes are handed to Claude Code (as a paste-ready instruction) or to your editor.
 
 ```bash
 npx skills-viewer
@@ -12,31 +12,43 @@ npx skills-viewer
 
 <!-- 相対パス参照: private リポジトリでも GitHub 上で表示でき、npmjs.com は repository フィールドを元に raw URL へ書き換えるため public 化後は npm でも表示される -->
 
-![Skills Viewer — grid view with per-scope grouping, usage stats and AI summaries](docs/screenshot.png)
+![Skills Viewer — home: what changed since you last looked, and everything installed across projects](assets/home.png)
+
+<!-- 3 枚は横並びのサムネイル(クリックで原寸)。縦に並べると README が画面 4 枚分伸びるため -->
+<p>
+  <a href="assets/skill.png"><img src="assets/skill.png" width="32%" alt="Skill page — summary, facts strip, how it triggers and what it touches"></a>
+  <a href="assets/flow.png"><img src="assets/flow.png" width="32%" alt="Flow diagram extracted from the skill body — steps, branches, delegations and a human gate"></a>
+  <a href="assets/memory.png"><img src="assets/memory.png" width="32%" alt="Memory page — index line, freshness and triage verdict, then the body"></a>
+</p>
+<sub>Skill page · flow diagram · memory page (click to enlarge). Ledger theme; Console is the dark one.</sub>
 
 ## Features
 
-- **All scopes in one view** — user (`~/.claude/skills`), every project's `.claude/skills` / `.claude/commands`, installed plugins, and Claude Code built-ins, grouped by source
-- **Purpose grouping (AI)** — one haiku call classifies everything installed by _when you use it_ into 4–8 groups generated for your environment (planning / building / review / release / … as a role-agnostic guide — a designer's or PM's skills get their own groups). Switch the list between by-source, by-purpose and flat views; a frontmatter `category:` pins an item to a manual group that takes precedence
+- **Home answers three questions** — what changed since you last looked, what this session actually loads, and what is available in it. The list is no longer the first thing you see
+- **What's loaded, and what it costs** — the _session context_ block adds up everything Claude Code reads at the start of a session in the current project: the CLAUDE.md files, the `MEMORY.md` index (against the official 200-line / 25 KB limit) and every name + description (against the skill-listing budget — Claude Code truncates the listing at about 2 % of the context window; the viewer estimates it and defers to `/doctor` for the actual cut). System prompt, MCP tools and hook output are not visible to the viewer and are excluded
+- **CLAUDE.md, all seven layers** — managed policy, `~/.claude/CLAUDE.md`, `CLAUDE.md`, `.claude/CLAUDE.md`, `CLAUDE.local.md`, `.claude/rules/*.md` and ancestor files up to the git root, listed in load order with per-heading token cost and `@import` expanded in place. Layers that do not exist stay on the list as _none_, because what is **not** read is information too
+- **Two themes** — Console (dark, monospace labels, dense rows) and Ledger (light, rows and tables). Follows your OS setting by default and can be pinned in settings; the layout is fluid down to a 900 px minimum
+- **All scopes in one view** — user (`~/.claude/skills`), every project's `.claude/skills` / `.claude/commands`, installed plugins, and Claude Code built-ins. The current project opens first and the rest stay collapsed, so "what is in this repo" is not buried in what applies everywhere
+- **Worktrees** — the project switcher lists main checkouts only, with a worktree count; open a project and pick a worktree from the selector at the top of the page to see what a session started there would load (skills from the worktree itself, memory shared with the main checkout)
+- **Purpose grouping (AI)** — one haiku call classifies everything installed by _when you use it_ into 4–8 groups generated for your environment (planning / building / review / release / … as a role-agnostic guide — a designer's or PM's skills get their own groups). Pick between by-source, by-purpose and single-list orderings in the _all projects_ view; a frontmatter `category:` pins an item to a manual group that takes precedence
 - **Search / sort** — incremental search over name + description + usage; sort by name, usage count, last used, updated date, or token cost
-- **Diagnostics** — a _no recent use_ badge (no recorded use within the transcript retention window) with an all / recent use / no recent use filter, plus static description lint: missing / too-short / too-long descriptions, missing trigger conditions ("use when …") that make auto-invocation unlikely, and name-echo descriptions
+- **Diagnostics** — a _no recent use_ badge (no recorded use within the transcript retention window) with an all / recent use / no recent use filter, plus static description lint: missing / too-short / too-long descriptions, missing trigger conditions ("use when …") that make auto-invocation unlikely, name-echo descriptions, and descriptions that exceed the 1,536-character cap Claude Code applies to the skill listing (the rest is cut, so the trigger should come first)
 - **Token cost** — since every name + description is injected into each session, the estimated token overhead is shown per item, per scope, and as a per-session total for the current project
-- **AI trigger diagnosis** — one click asks the model whether the description is likely to trigger auto-invocation, lists concrete issues, and proposes an improved description you can apply with one click (cached by content hash)
+- **AI trigger diagnosis** — one click asks the model whether the description is likely to trigger auto-invocation, lists concrete issues, and proposes an improved description (cached by content hash). The result comes with a paste-ready instruction for Claude Code — the target path, what to change (or what to keep if you change it), and the "check first, ask when unsure, execute after approval" steps — so the edit happens where you can review it
 - **AI flow diagram** — extract the processing flow of orchestration-style skills (steps, branches, delegations, human gates) from the definition body and render it as a step diagram; delegated skills are clickable
 - **AI model choice** — pick the model behind all AI features (haiku default / sonnet / opus) in settings; aliases are resolved by your claude CLI
-- **Memory triage** — a _Memory_ view lists Claude Code's auto memory (`~/.claude/projects/<project>/memory/`) per project with its context cost split into the always-on part (the `MEMORY.md` index line injected into every session) and the pay-per-use part (the body, read on demand), plus Read / Write counts from transcripts, `[[link]]` resolution and backlinks. **AI triage** reads every memory of a project with the claude CLI (one call, split into a few for very large projects) and proposes a destination per memory — keep / shrink / move to CLAUDE.md / move to docs / move to a skill / delete / wrong project — with the reasoning and a paste-ready instruction for Claude Code (it is asked to always cover removing the `MEMORY.md` index line and re-pointing `[[link]]`s). Each memory is first judged for freshness (current / outdated / historical / obsolete) from mechanical signals — dates in the body, missing paths, merged or deleted branches, references to another project — and a _rewrite the body_ verdict covers memories whose gist still holds; the triage also flags when the `MEMORY.md` index line disagrees with the body. For feedback memories the instruction is built from a fixed template, so it reads the same on every model. The viewer never writes to memory: you paste the instruction into Claude Code, which inspects, asks when unsure, and executes after your approval
-- **Edit in the browser** — inline editor for SKILL.md / commands / agents (project & user scopes) with mtime conflict detection and a one-generation backup in `~/.cache/skills-viewer/backups/`
-- **What's changed** — a banner shows items added / updated / removed since your last launch (baseline advances only when you dismiss it); the CLI prints a one-line summary at startup too
+- **Memory triage** — a _Memory_ view lists Claude Code's auto memory (`~/.claude/projects/<project>/memory/`, or the directory set by `autoMemoryDirectory`) per project with its context cost split into the always-on part (the `MEMORY.md` index line injected into every session) and the pay-per-use part (the body, read on demand), plus Read / Write counts from transcripts, `[[link]]` resolution and backlinks. **AI triage** reads every memory of a project with the claude CLI (one call, split into a few for very large projects) and proposes a destination per memory — keep / shrink / move to CLAUDE.md / move to your user CLAUDE.md / move to docs / move to a skill / delete / wrong project — with the reasoning and a paste-ready instruction for Claude Code (it is asked to always cover removing the `MEMORY.md` index line and re-pointing `[[link]]`s). Each memory is first judged for freshness (current / outdated / historical / obsolete) from mechanical signals — dates in the body, missing paths, merged or deleted branches, references to another project — and a _rewrite the body_ verdict covers memories whose gist still holds; the triage also flags when the `MEMORY.md` index line disagrees with the body. For feedback memories the instruction is built from a fixed template, so it reads the same on every model. The viewer never writes to memory: you paste the instruction into Claude Code, which inspects, asks when unsure, and executes after your approval
+- **What's changed** — the first block on the home screen lists what was added / updated / removed since you last marked it read, in GitHub's diff grammar (`+` / `~` / `−`). Skills, commands, agents, **auto memory and CLAUDE.md** are all tracked, and for files under git the author and date come from `git log` (looked up for the first 40 changed files, within a short time budget; the rest show the date only); the CLI prints a one-line summary at startup too
 - **Usage sparkline** — the detail pane charts the last 30 days of per-day usage
 - **Usage stats** — invocation counts and last-used dates aggregated from Claude Code session transcripts (`~/.claude/projects/`), covering both user-typed `/skill` calls and model-invoked Skill tool calls
 - **AI summaries** — one-click summarization of each SKILL.md via `claude -p --model haiku`, cached by content hash in `~/.cache/skills-viewer/` so unchanged skills are never re-summarized
-- **Detail pane** — master/detail layout with an Overview tab (description, usage, bundled files) and a rendered SKILL.md tab
-- **Agents & hooks too** — `.claude/agents/*.md` and `hooks` entries from `settings.json` / `settings.local.json` are listed alongside skills with kind badges (hooks are read-only)
-- **Manage** — copy a skill/command/agent to another project or to user scope (`-copy` suffix on name conflicts), or delete it — deletions go to the OS trash, not `rm`. Plugin and built-in entries are read-only
+- **One page per item** — a single column, read top to bottom: summary, then a strip of facts (usage, when it was added and by whom, same-name definitions, bundled files), then how it triggers, what it touches (delegates and `allowed-tools`, so writes and outbound calls are known without asking the model), then the flow, then the full text. Hooks get a short page of their own (event, matcher, command, and the other hooks in the session)
+- **Agents & hooks too** — `.claude/agents/*.md` and `hooks` entries from `settings.json` / `settings.local.json` are listed alongside skills with kind badges (a hook is a `settings.json` entry, not a file of its own)
+- **Read-only by design** — the viewer never edits, copies or deletes your definitions. It diagnoses and explains, then hands the change over: a paste-ready instruction for Claude Code, or _Open in editor_ for any file it is allowed to read
 - **Same-name diff** — when the same skill name exists in multiple scopes, the detail page lists the other definitions and shows a line diff between them
-- **Open in editor** — via URL scheme (VS Code / Cursor / Zed / Windsurf / custom, configurable in the ⚙ settings modal), or the OS default opener
+- **Open in editor** — via URL scheme (VS Code / Cursor / Zed / Windsurf / custom, configurable in the ⚙ settings modal), or the OS default opener; offered for every file inside the paths the viewer may read, including `settings.json` and not only `.md`
 - **English / 日本語** — UI language auto-detected from the browser and switchable in settings; AI summaries are generated in the selected language (CLI messages follow `LANG`)
-- **URL routing** — `/skills/:id?tab=md`, `/memory/:id`, `/memory/triage/:project`, search/sort/grouping in query params; links are shareable across reloads
+- **URL routing** — `/skills/:id`, `/claude-md/:id`, `/memory`, `/memory/:id`, with `?project=<id>|all`, search, sort and filters in query params; the project id is derived from its path, so links are shareable across reloads
 
 ## Usage
 
@@ -52,7 +64,12 @@ Run it from a project directory to have that project marked as “current” and
 
 - Binds to `127.0.0.1` only
 - Mutating APIs require a per-run token that other origins cannot read (same-origin policy), and requests with a non-localhost `Origin` are rejected
-- Copy/delete are restricted to `.claude/skills/` / `.claude/commands/` / `.claude/agents/` paths; plugin directories are never written to; deletions go to the OS trash
+- **The viewer never modifies your definitions.** It writes only its own state (the "what's changed" baseline and the AI result cache under `~/.cache/skills-viewer/`); the other mutating APIs just start a `claude` CLI call or hand a path to your editor
+- Reads stay inside `~/.claude`, the per-project `.claude` directories, the `autoMemoryDirectory` configured for the current directory or the project you selected (its `.claude/settings.json` / `settings.local.json` are read the same way Claude Code reads them there), and **the CLAUDE.md files Claude Code itself loads for those same two projects** — `CLAUDE.md`, `CLAUDE.local.md`, `.claude/rules/*.md` and ancestor `CLAUDE.md` files up to the git root. That last group sits outside `.claude`, so it is allowed by exact path: only the files the scanner enumerated at those fixed names and places, never an arbitrary `.md`. (Change tracking additionally hashes the CLAUDE.md group of every registered project and its worktrees so the _Changed_ block can list them; those files are read to compute a hash and are never returned to the page or sent anywhere.) The `autoMemoryDirectory` and CLAUDE.md parts follow your selection and nothing else — the `.claude` rule itself is fixed and does not depend on what you select: a project you have registered but are not looking at cannot widen those two, since `autoMemoryDirectory` is read from a committed `.claude/settings.json` that arrives with a cloned repository. Selecting a project is what grants it: the viewer has no separate trust prompt, so its `.claude/settings.json` is read the same way Claude Code reads it once you trust the folder. The project is picked by id from the list the viewer itself enumerated (the registry, the worktrees linked from it, and the main checkouts those worktrees belong to), never by a path sent from the page. A symlinked `CLAUDE.md` is followed, since Claude Code follows it too (`ln -s AGENTS.md CLAUDE.md` is a documented setup). An `autoMemoryDirectory` that resolves to a filesystem root, your home directory or an ancestor of it is ignored. _Open in editor_ is limited to the same paths
+- `@import` inside a CLAUDE.md is followed only within the project or `~/.claude`, up to 4 levels (the official limit) and 4 MiB per file (the size at which Claude Code itself skips a file). A CLAUDE.md arrives with a cloned repository, so `@/etc/hosts` is reported as out of scope and never opened — not even to check whether it exists. Dot-prefixed names and anything under `.git` stay out of reach even inside the project (`.claude` itself is the exception, since it is the boundary), and the boundary is re-checked after symlinks resolve. At most 200 references per file and 500 per scan are followed; when either limit is reached, the home and CLAUDE.md screens say so, since the token totals they show are then short of the rest. A file larger than 4 MiB is listed but shown as not loaded, since Claude Code skips it too
+- Only the bodies under `~/.claude`, the per-project `.claude` directories and the `autoMemoryDirectory` of the current or selected project are ever sent to the `claude` CLI. The CLAUDE.md group sits outside those, so its bodies are displayed but never sent — `CLAUDE.local.md` in particular is usually gitignored and private. The one exception is deliberate and small: memory triage sends the **headings** (never the bodies) of `~/.claude/CLAUDE.md` and of the triaged project's `CLAUDE.md` / `.claude/CLAUDE.md`, so it can spot duplicates and promotion targets (see Notes)
+- On startup the viewer deletes `~/.cache/skills-viewer/backups/`, the one-generation copies the v0.8 in-browser editor used to make. Nothing writes there any more, and it prints a line when it removes them
+- Reading the previous version of a file (for the diff) runs local `git show` inside the same allowed paths, and `git log` supplies the author for changed files. Both are invoked as argument arrays with a timeout, never through a shell, and no network access is involved
 
 ## Development
 
@@ -69,7 +86,7 @@ Layout:
 ```
 src/
 ├─ cli.ts         # bin entry
-├─ server/        # zero-dep Node API (scan / usage / summary / manage) — TypeScript
+├─ server/        # zero-dep Node API (scan / usage / summary / read-access) — TypeScript
 └─ shared/        # types shared between server and web (single source)
 web/              # React + TypeScript + Vite (devDependencies only — bundled into dist/)
 build/            # compiled server JS shipped in the npm package (generated by prepack)
@@ -81,9 +98,11 @@ dist/             # prebuilt UI shipped in the npm package (generated by prepack
 - Usage stats only cover the transcript retention window of Claude Code (`cleanupPeriodDays`, default 30 days) — the _no recent use_ badge and memory Read counts have the same limitation (projects without transcripts show no usage columns at all)
 - Token costs are heuristic estimates (≈4 chars/token for ASCII, ≈1.5 for CJK), not exact tokenizer counts
 - Usage is attributed per calling project (worktrees roll up to their parent project by encoded-path prefix). When scopes share a name, the resolution order project > user > plugin > built-in is assumed
-- The built-in skill list is hardcoded in `server/scan.js` (they live inside the Claude Code binary); check `/skills` inside Claude Code for the authoritative list
-- AI summaries require a logged-in `claude` CLI
+- The built-in skill list is hardcoded in `src/server/scan.ts` (they live inside the Claude Code binary); check `/skills` inside Claude Code for the authoritative list
+- The skill-listing budget shown on the home screen is an estimate: Claude Code caps the listing by characters at about 2 % of the context window, and the viewer compares its token estimate against 2 % of a 200k window (4,000 tokens). It says _likely truncated_, not _truncated_ — run `/doctor` inside Claude Code to see what was actually cut
+- AI features require a logged-in `claude` CLI. Its presence is checked once at startup (`claude --version`); if it is missing, the AI buttons are disabled with a note — install it and restart the viewer to enable them
 - Memory triage sends each memory's body to the claude CLI, together with the project's `MEMORY.md` index, the **headings** of `CLAUDE.md` / `.claude/CLAUDE.md` / `~/.claude/CLAUDE.md` and the names + descriptions of the skills available to that project (never their bodies) so it can spot duplicates and promotion targets. Branch status for the freshness signals comes from local `git` (no network). Results are cached per memory by content hash (plus the index line); memory files themselves are never modified
+- The Memory view resolves `autoMemoryDirectory` from your user settings and the project you selected (any project registered in `~/.claude.json`, or a linked worktree of one; its `.claude/settings.json` / `settings.local.json` are read the same way Claude Code reads them there). Only the current directory and the selected project are resolved this way — the settings of the other registered projects are not read, so they cannot widen what the viewer may read
 
 ## License
 

package/build/server/claude-md.js

@@ -0,0 +1,512 @@
+"use strict";
+/*
+ * CLAUDE.md 群の走査。Claude Code が「毎セッションの最初に読むもの」を注入順に列挙し、
+ * 常時コスト(トークン)と本文を返す。ホームの「セッションの文脈」と CLAUDE.md 画面の土台。
+ *
+ * 公式の読み込み順(https://code.claude.com/docs/en/memory.md、2026-09-08 確認):
+ *   1. 管理ポリシー(OS 固定パス)
+ *   2. ~/.claude/CLAUDE.md
+ *   3. <project>/CLAUDE.md
+ *   4. <project>/.claude/CLAUDE.md
+ *   5. <project>/CLAUDE.local.md
+ *   6. <project>/.claude/rules/*.md(frontmatter に paths: が無いものだけが起動時。有りは遅延)
+ *   7. 親ディレクトリの CLAUDE.md(git root まで遡る)
+ * サブディレクトリの CLAUDE.md は「そのディレクトリのファイルを読むとき」の遅延ロードなので
+ * 常時コストには含めない(この走査の対象外)。
+ *
+ * HOME/.claude の参照はこのファイルに集約する(計画 11 の claudeDir() へ差し替えやすくするため)。
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.userClaudeDir = void 0;
+exports.claudeMdLayers = claudeMdLayers;
+exports.claudeMdPaths = claudeMdPaths;
+exports.claudeMdRefs = claudeMdRefs;
+exports.claudeMdRefsOf = claudeMdRefsOf;
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const lint_1 = require("./lint");
+const scan_1 = require("./scan");
+const memory_1 = require("./memory");
+const import_refs_1 = require("../shared/import-refs");
+/*
+ * user scope の設定ディレクトリ。HOME/.claude の参照はこのファイルに集約する
+ * (計画 11 の CLAUDE_CONFIG_DIR 対応で claudeDir() に差し替える箇所を 1 つに保つため)。
+ */
+const userClaudeDir = (home = os.homedir()) => path.join(home, '.claude');
+exports.userClaudeDir = userClaudeDir;
+/* @import の展開上限(公式仕様: maximum depth of four hops) */
+const MAX_IMPORT_DEPTH = 4;
+/*
+ * 1 ファイルの読み取り上限。公式が「Claude Code loads a CLAUDE.md file of up to 4 MiB in full
+ * and skips a larger file」と定めているので同じ線に揃える。ここを公式より狭くすると、
+ * Claude Code は読んでいるのに viewer は「未読」と出すことになり、常時コストを過少に出す。
+ * 7 段の本体にも @import 先にも同じ上限を掛ける(本体だけ無制限だと概算のループが効かない)。
+ */
+const MAX_FILE_BYTES = 4 * 1024 * 1024;
+/*
+ * 1 ファイルから拾う参照の件数と、1 回の走査(7 段ぜんぶ)で作る @import 行の総数。
+ * 参照 1 件ごとに realpath + stat が走るので、扇形に広い CLAUDE.md で毎リクエスト数千回の
+ * fs 呼び出しと数 MB の JSON が出るのを防ぐ(git author に 40 件の予算を置いたのと同じ趣旨)。
+ *
+ * 総数はファイル単位ではなく**走査全体で共有する**。rules 段は .claude/rules/*.md を
+ * 件数の制限なく回すので、ファイル単位の上限だけだと「200 本 × 200 件」で元の木阿弥になる。
+ */
+const MAX_IMPORT_REFS_PER_FILE = 200;
+const MAX_IMPORT_ENTRIES = 500;
+function importScopeOf(root, home) {
+    const dirs = [(0, exports.userClaudeDir)(home), root].filter((d) => !!d);
+    // realDir は memory.ts の写像(realpath が取れなければ resolve で代用)。
+    // 許可の判定はこの 1 本に揃える — 場所ごとに実パスで見るかが変わると許可と判定がずれる
+    return {
+        roots: [...new Set(dirs.flatMap((d) => [d, (0, memory_1.realDir)(d)]))],
+        budget: { left: MAX_IMPORT_ENTRIES, truncated: false },
+    };
+}
+/* 管理ポリシーの置き場(OS ごとの固定パス)。本文は返さず存在と概算だけ扱う */
+function managedPolicyPath() {
+    if (process.platform === 'darwin')
+        return '/Library/Application Support/ClaudeCode/CLAUDE.md';
+    if (process.platform === 'win32')
+        return 'C:\\Program Files\\ClaudeCode\\CLAUDE.md';
+    return '/etc/claude-code/CLAUDE.md';
+}
+/*
+ * 本文の読み取り。'too-large' と null(読めない)を言い分ける:
+ * 大きすぎるファイルは「存在するが読まれない」ので、段から消すと差分追跡が
+ * 「消えた」と誤って出す(claudeMdRefs は段の files から現在のキーを作る)。
+ */
+function readText(fp) {
+    try {
+        // 公式も 4 MiB 超の CLAUDE.md は読まない(loads … up to 4 MiB in full and skips a larger file)。
+        // 読む前に大きさで落とす(毎リクエストの全読みと概算の文字単位ループが効かないように)
+        if (fs.statSync(fp).size > MAX_FILE_BYTES)
+            return 'too-large';
+        return fs.readFileSync(fp, 'utf8');
+    }
+    catch {
+        return null; // 権限エラー等で読めない段は「無い」扱いにして一覧全体を落とさない
+    }
+}
+function mtime(fp) {
+    try {
+        return fs.statSync(fp).mtime.toISOString();
+    }
+    catch {
+        return '';
+    }
+}
+/*
+ * 見出しごとの概算。見出し行から次の見出し行の直前までを 1 節として数えるので、
+ * 節の合計は本文全体の概算とほぼ一致する(どの節が重いかを出すための内訳)。
+ */
+function headingsOf(body) {
+    const lines = body.split(/\r?\n/);
+    const out = [];
+    let cur = null;
+    for (const line of lines) {
+        const h = line.match(/^(#{1,6})\s+(.*)$/);
+        if (h) {
+            if (cur)
+                out.push({ text: cur.text, tokens: (0, lint_1.estimateTokens)(cur.buf.join('\n')) });
+            cur = { text: h[2].trim(), buf: [line] };
+        }
+        else if (cur) {
+            cur.buf.push(line);
+        }
+    }
+    if (cur)
+        out.push({ text: cur.text, tokens: (0, lint_1.estimateTokens)(cur.buf.join('\n')) });
+    return out;
+}
+function resolveImport(ref, fromDir, home) {
+    if (ref.startsWith('~/'))
+        return path.join(home, ref.slice(2));
+    if (path.isAbsolute(ref))
+        return ref;
+    return path.resolve(fromDir, ref);
+}
+/*
+ * @import を深さ優先で展開する。
+ * - stack は展開の経路(自分の先祖)。ここに居れば本当の循環
+ * - seen は 1 ファイルの走査で数えた実パス。経路が違うのに再登場したのはダイヤモンド参照で、
+ *   二重計上を避けるために展開しないが循環ではない(表示の文言を分ける)
+ */
+function expandImports(body, fromDir, home, depth, seen, stack, scope, out) {
+    const found = (0, import_refs_1.importRefs)(body, MAX_IMPORT_REFS_PER_FILE);
+    // 1 ファイル単位で切った分も「数えていない」ことに変わりはないので同じ印を立てる
+    if (found.truncated)
+        scope.budget.truncated = true;
+    for (const ref of found.refs) {
+        if (scope.budget.left <= 0) {
+            scope.budget.truncated = true;
+            return;
+        }
+        scope.budget.left--;
+        const abs = resolveImport(ref, fromDir, home);
+        /*
+         * 読み取りの境界の外は realpath も stat もしない。CLAUDE.md は clone したリポジトリから
+         * 来るファイルなので、@/etc/hosts や @~/.ssh/config を素直に解決すると、本文を読まなくても
+         * 「存在するか」「symlink の先はどこか」をブラウザへ返してしまう(覗く材料になる)。
+         * 字句で先に落とし、返すのも要求されたパスのまま(解決後のフルパスは出さない)。
+         */
+        if (!openableImport(abs, scope)) {
+            out.push({ ref, path: abs, exists: false, depth, tokens: 0, skipped: 'out-of-scope' });
+            continue;
+        }
+        let real = abs;
+        let size = 0;
+        let exists;
+        try {
+            real = fs.realpathSync(abs);
+            const st = fs.statSync(real);
+            exists = st.isFile();
+            size = st.size;
+        }
+        catch {
+            exists = false;
+        }
+        if (!exists) {
+            out.push({ ref, path: abs, exists: false, depth, tokens: 0 });
+            continue;
+        }
+        // symlink で境界の外へ出ていないか、解決後にもう一度見る
+        if (!openableImport(real, scope)) {
+            out.push({ ref, path: abs, exists: false, depth, tokens: 0, skipped: 'out-of-scope' });
+            continue;
+        }
+        if (stack.has(real)) {
+            out.push({ ref, path: real, exists: true, depth, tokens: 0, skipped: 'cycle' });
+            continue;
+        }
+        if (seen.has(real)) {
+            out.push({ ref, path: real, exists: true, depth, tokens: 0, skipped: 'duplicate' });
+            continue;
+        }
+        if (depth > MAX_IMPORT_DEPTH) {
+            out.push({ ref, path: real, exists: true, depth, tokens: 0, skipped: 'depth' });
+            continue;
+        }
+        if (size > MAX_FILE_BYTES) {
+            out.push({ ref, path: real, exists: true, depth, tokens: 0, skipped: 'too-large' });
+            continue;
+        }
+        seen.add(real);
+        const raw = readText(real);
+        if (raw === null) {
+            out.push({ ref, path: real, exists: false, depth, tokens: 0 });
+            continue;
+        }
+        if (raw === 'too-large') {
+            out.push({ ref, path: real, exists: true, depth, tokens: 0, skipped: 'too-large' });
+            continue;
+        }
+        out.push({ ref, path: real, exists: true, depth, tokens: (0, lint_1.estimateTokens)(raw) });
+        stack.add(real);
+        expandImports(raw, path.dirname(real), home, depth + 1, seen, stack, scope, out);
+        stack.delete(real);
+    }
+}
+/*
+ * @import 先として開いてよい範囲。Claude Code 自身が読むのはプロジェクト配下のファイル
+ * (@README など)と user scope の設定なので、その 2 つに限る。
+ */
+const inImportScope = (p, scope) => scope.roots.some((r) => (0, memory_1.isUnder)(p, r));
+/*
+ * 境界の中でも開かないもの。公式の @import は拡張子を問わない(@package.json も読む)ので
+ * .md には絞らないが、秘密が入る場所は外す。判定は**パスの全区切り**を見る:
+ * 名前だけを見ると `<project>/.aws/credentials` や `<project>/.ssh/id_rsa` が素通りする。
+ *
+ * 例外は `.claude` そのもの。境界の定義に使っているディレクトリで、`~/.claude/rules/x.md`
+ * のような正当な参照がここを通る。その配下でも `.` で始まるもの(`.credentials.json`)は外す。
+ *
+ * 本文は返さないので漏れるのは「存在するか」と概算サイズだけだが、`.env` を外した理由
+ * (参照されただけで大きさを渡したくない)は `.aws` `.ssh` にそのまま当てはまる。
+ */
+function openableImport(p, scope) {
+    if (!inImportScope(p, scope))
+        return false;
+    return !p
+        .split(path.sep)
+        .some((seg) => seg.startsWith('.') && seg !== '.claude' && seg !== '.' && seg !== '..');
+}
+/* 1 ファイル分の読み取り。本文を返さない段(管理ポリシー)は withhold で切り替える */
+function readFile(fp, home, scope, opts = {}) {
+    const raw = readText(fp);
+    if (raw === null)
+        return null;
+    // 大きすぎて読まなかった段。存在は残し、コストは 0(Claude Code も読み飛ばす)
+    if (raw === 'too-large')
+        return {
+            path: fp,
+            ownTokens: 0,
+            tokens: 0,
+            updatedAt: mtime(fp),
+            headings: [],
+            imports: [],
+            tooLarge: true,
+        };
+    const ownTokens = (0, lint_1.estimateTokens)(raw);
+    const imports = [];
+    const seen = new Set();
+    const stack = new Set();
+    try {
+        const self = fs.realpathSync(fp);
+        seen.add(self);
+        stack.add(self);
+    }
+    catch {
+        seen.add(fp);
+        stack.add(fp);
+    }
+    /*
+     * 参照は frontmatter を外した本文から拾う。web は frontmatter を別枠で描くので印を置けず、
+     * server だけが数えると出現順の突き合わせが 1 つずれる
+     * (.claude/rules/*.md の `description: applies to @types/node` のような値で実際に起きる)。
+     */
+    expandImports((0, import_refs_1.bodyWithoutFrontmatter)(raw), path.dirname(fp), home, 1, seen, stack, scope, imports);
+    const importTokens = imports.reduce((n, im) => n + im.tokens, 0);
+    return {
+        path: fp,
+        ownTokens,
+        tokens: ownTokens + importTokens,
+        updatedAt: mtime(fp),
+        headings: opts.withhold ? [] : headingsOf(raw),
+        imports,
+        ...(opts.withhold ? { bodyWithheld: true } : {}),
+    };
+}
+/* 単一ファイルの段。無くても「どこを見たか」を残すため files: [] で返す */
+function singleLayer(kind, fp, home, scope, opts = {}) {
+    const f = fs.existsSync(fp) ? readFile(fp, home, scope, opts) : null;
+    return { kind, label: fp, files: f ? [f] : [], tokens: f ? f.tokens : 0 };
+}
+/*
+ * .claude/rules/*.md。frontmatter に paths: があるものは「そのパスのファイルを読むとき」の
+ * 遅延ロードなので常時コストに含めない(件数だけ lazy で残す)。
+ * paths: の値は YAML リストで、既存の parseFrontmatter では中身を取れない。
+ * ここで要るのは有無だけなので、キーの存在で判定する(真偽値で見ると空文字列に負ける)。
+ */
+function rulesLayer(root, home, scope) {
+    const dir = path.join(root, '.claude', 'rules');
+    const layer = {
+        kind: 'rules',
+        label: path.join(dir, '*.md'),
+        files: [],
+        tokens: 0,
+    };
+    let names;
+    try {
+        names = fs
+            .readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isFile() && e.name.endsWith('.md'))
+            .map((e) => e.name)
+            .sort();
+    }
+    catch {
+        return layer;
+    }
+    for (const name of names) {
+        const fp = path.join(dir, name);
+        const raw = readText(fp);
+        if (raw === null)
+            continue;
+        const f = readFile(fp, home, scope);
+        if (!f)
+            continue;
+        const lazy = 'paths' in (0, scan_1.parseFrontmatter)(raw).meta;
+        layer.files.push(lazy ? { ...f, lazy: true } : f);
+        if (!lazy)
+            layer.tokens += f.tokens;
+    }
+    return layer;
+}
+/*
+ * 親ディレクトリの探索範囲。git root まで遡り、ホームとその祖先・ファイルシステムのルートには出ない。
+ * git 管理外なら 1 つ上だけ(どこまでも遡ると無関係な親の CLAUDE.md を拾う)。
+ * 本文の読み取り(parentLayer)とパスの列挙(claudeMdPaths)で同じ範囲を使う。
+ */
+function parentDirs(root, home) {
+    const gitRoot = (0, memory_1.worktreeRootOf)(root);
+    const dirs = [];
+    let cur = path.dirname(path.resolve(root));
+    for (;;) {
+        if (cur === path.dirname(cur))
+            break; // ファイルシステムのルート
+        if (cur === home || (0, memory_1.isUnder)(home, cur))
+            break; // ホームとその祖先には出ない
+        if (!gitRoot) {
+            dirs.push(cur); // git 管理外は 1 つ上だけ
+            break;
+        }
+        // git 配下は境界の判定を先に置く。root 自身が git root(普通のリポジトリを開いた場合)なら
+        // 親は範囲外なので 1 件も拾わない
+        if (!(0, memory_1.isUnder)(cur, gitRoot))
+            break;
+        dirs.push(cur);
+        if (cur === gitRoot)
+            break;
+        cur = path.dirname(cur);
+    }
+    return dirs;
+}
+/*
+ * 親ディレクトリの CLAUDE.md。git root まで遡り、ホームやファイルシステムのルートには出ない。
+ * git 管理外なら 1 つ上だけ見る(どこまでも遡ると無関係な親の CLAUDE.md を拾う)。
+ */
+function parentLayer(root, home, scope) {
+    const layer = {
+        kind: 'parent',
+        label: path.join(path.dirname(root), 'CLAUDE.md'),
+        files: [],
+        tokens: 0,
+    };
+    for (const dir of parentDirs(root, home)) {
+        const fp = path.join(dir, 'CLAUDE.md');
+        if (!fs.existsSync(fp))
+            continue;
+        const f = readFile(fp, home, scope);
+        if (!f)
+            continue;
+        layer.files.push(f);
+        layer.tokens += f.tokens;
+    }
+    return layer;
+}
+/*
+ * 注入順に 7 段を並べる。無い段も files: [] で残す(「何が読まれていないか」も情報なので、
+ * 画面側で「なし」の行として出せるようにする)。
+ * root / home はテストから差し替えられるよう引数で受ける。
+ */
+function claudeMdLayers(opts = {}) {
+    const home = opts.home ?? os.homedir();
+    const root = opts.root ? path.resolve(opts.root) : null;
+    const scope = importScopeOf(root, home);
+    const layers = [
+        singleLayer('managed', opts.managedPath ?? managedPolicyPath(), home, scope, {
+            withhold: true,
+        }),
+        singleLayer('user', path.join((0, exports.userClaudeDir)(home), 'CLAUDE.md'), home, scope),
+    ];
+    if (root) {
+        layers.push(singleLayer('project', path.join(root, 'CLAUDE.md'), home, scope), singleLayer('project-dot', path.join(root, '.claude', 'CLAUDE.md'), home, scope), singleLayer('local', path.join(root, 'CLAUDE.local.md'), home, scope), rulesLayer(root, home, scope), parentLayer(root, home, scope));
+    }
+    return {
+        layers,
+        tokens: layers.reduce((n, l) => n + l.tokens, 0),
+        // 予算切れで打ち切ったなら上限の件数を添える。合計 tok が小さく出た理由を画面が言えるように
+        // (件数は画面の文面にも出すので、定数を web 側へ写さずここから渡す)
+        // 上限(1 ファイル 200 件 / 走査全体 500 件)のどちらかで切ったら立てる。
+        // どちらの上限かは利用者の行動(参照を減らす)を変えないので、値は分けない
+        ...(scope.budget.truncated ? { importsTruncated: true } : {}),
+    };
+}
+/*
+ * 走査が見るファイルのパスだけを列挙する(本文を読まず、トークンも数えない)。
+ * 読み取り・エディタ起動の許可判定(read-access.ts)は「このパスか」だけを知りたいので、
+ * claudeMdLayers を呼ぶと 1 リクエストごとに全文の読み取りと @import の展開が走ってしまう。
+ * 管理ポリシーは本文を返さない段なので含めない(許可の対象外)。
+ */
+function claudeMdPaths(opts = {}) {
+    const home = opts.home ?? os.homedir();
+    const root = opts.root ? path.resolve(opts.root) : null;
+    const out = [path.join((0, exports.userClaudeDir)(home), 'CLAUDE.md')];
+    if (root) {
+        out.push(path.join(root, 'CLAUDE.md'), path.join(root, '.claude', 'CLAUDE.md'), path.join(root, 'CLAUDE.local.md'));
+        const rulesDir = path.join(root, '.claude', 'rules');
+        try {
+            for (const e of fs.readdirSync(rulesDir, { withFileTypes: true }))
+                if (e.isFile() && e.name.endsWith('.md'))
+                    out.push(path.join(rulesDir, e.name));
+        }
+        catch {
+            /* rules ディレクトリが無い環境 */
+        }
+        for (const dir of parentDirs(root, home))
+            out.push(path.join(dir, 'CLAUDE.md'));
+    }
+    return out.filter((fp) => fs.existsSync(fp));
+}
+/* 差分追跡(snapshot)へ渡す参照。遅延ロードの rules も「変わったら知りたい」ので含める */
+function claudeMdRefs(scan, home = os.homedir()) {
+    const userDir = (0, exports.userClaudeDir)(home);
+    const out = [];
+    for (const layer of scan.layers) {
+        // 管理ポリシーは OS が配るもので、利用者の変更対象ではないので追跡しない
+        if (layer.kind === 'managed')
+            continue;
+        for (const f of layer.files) {
+            out.push({
+                path: f.path,
+                exists: true,
+                name: path.basename(f.path),
+                source: (0, memory_1.isUnder)(f.path, userDir) ? 'user' : 'project',
+            });
+        }
+    }
+    return out;
+}
+/*
+ * 差分追跡(snapshot)へ渡す参照。計画 16 Phase D: CLAUDE.md の変化追跡を cwd だけでなく
+ * 登録済み全プロジェクトへ広げるための入口。claudeMdRefs(claudeMdLayers(...))と違い、
+ * 本文を読んで @import を展開する重い走査(claudeMdLayers)は使わず、パスの存在だけを見る
+ * claudeMdPaths を各プロジェクトに回す ── 38 プロジェクトでも existsSync と小さいファイルの
+ * hash(呼び出し元の computeChanges が contentHash で取る)で済む軽さを保つため。
+ *
+ * `~/.claude/CLAUDE.md` は全プロジェクトで共通に列挙され、親ディレクトリの CLAUDE.md も
+ * サブディレクトリ登録で重複しうるので、パスで重複を除いてから返す(snapshot のキーは
+ * パス由来なので、重複したままだと同じキーへの上書きが起きるだけで実害は無いが、
+ * 呼び出し側の件数集計をわかりやすくするために先に潰す)。
+ */
+function claudeMdRefsOf(paths, home = os.homedir()) {
+    const userDir = (0, exports.userClaudeDir)(home);
+    const seen = new Set();
+    const out = [];
+    for (const root of paths) {
+        for (const fp of claudeMdPaths({ root, home })) {
+            if (seen.has(fp))
+                continue;
+            seen.add(fp);
+            out.push({
+                path: fp,
+                exists: true,
+                name: path.basename(fp),
+                source: (0, memory_1.isUnder)(fp, userDir) ? 'user' : 'project',
+            });
+        }
+    }
+    return out;
+}