claude-slim 2.14.2 → 2.15.0

package/README.md

@@ -37,10 +37,11 @@ Where the bloat hides — measured on one real install:
 |--------|:---:|---|
 | Skill listings | ~10,100 tokens | 256 skills × their `name: description` line |
 | Agent catalog | ~2,250 tokens | `~/.claude/agents/`, 12 agents |
-| CLAUDE.md | ~2,000 tokens | plugin instructions |
+| CLAUDE.md | ~2,000 tokens | plugin instructions, plus any `@path` imports |
+| Rules | ~1,200 tokens | `~/.claude/rules/` without `paths:` — path-scoped rules load later |
 | Deferred tools list | ~1,500 tokens | MCP tool schemas |
 | Slash commands | ~80 tokens | `~/.claude/commands/` |
-| Memory files | **0 – 63,500 tokens** | current project only — varies wildly per project |
+| Memory index | **0 – 6,500 tokens** | current project's `MEMORY.md` only, first 200 lines / 25KB — topic files are read on demand |
 
 Skill listings are the part people underestimate: each installed skill contributes one `- name: description` line to the system prompt, and those run anywhere from **30 to 509 tokens each**. Sixty terse skills and sixty verbose ones are not the same bill.
 
@@ -76,8 +77,9 @@ That's slower responses. Hitting your usage cap faster. Paying for context you'r
 | Oversized files | SKILL.md over 10KB |
 | **Unused skills** | **Local skills never invoked in your last N days of sessions (default 60d)** |
 | Agents & commands | `~/.claude/agents/` and `~/.claude/commands/` — measured and reported, never modified |
+| Rules & imports | `~/.claude/rules/` and CLAUDE.md `@path` imports — measured and reported, never modified |
 | **Unused plugins** | **Plugins whose skill/mcp/cmd were never invoked in your last N days of sessions (default 60d). Tier 3, never auto-selected.** |
-| Stale memory | Large memory files loaded every session |
+| Oversized memory index | `MEMORY.md` over 5KB, or cut at the 200-line / 25KB startup cap so its tail never loads |
 | Disabled plugins | Installed but disabled plugins still in cache |
 | Stale projects | Project memory untouched for 90+ days |
 | Temp caches | Failed plugin install remnants (`temp_local_*`) |
@@ -230,8 +232,9 @@ claude-slim scans these locations. No plugin-specific logic — pure filesystem
 ├── plugins/cache/           ← plugin skills, agents, commands, MCP servers
 ├── agents/                  ← user agents (measured, read-only)
 ├── commands/                ← user slash commands (measured, read-only)
-├── CLAUDE.md                ← system instructions (read-only)
-├── projects/*/memory/       ← auto-memory files (current project counts toward startup)
+├── CLAUDE.md                ← system instructions + @imports (read-only)
+├── rules/                   ← user rules (measured, read-only; path-scoped ones listed separately)
+├── projects/*/memory/       ← auto-memory (only the current project's MEMORY.md counts toward startup)
 └── settings.json            ← MCP server count (read-only)
 ```
 
@@ -252,20 +255,20 @@ From a real cleanup session:
 
 ### A note on the numbers
 
-claude-slim reports what a session in **this** directory pays. Memory is per-project — Claude Code loads `~/.claude/projects/<slug>/memory/` for the project you're in, not every project on disk — so running `scan` from two different repos will legitimately give you two different totals.
+claude-slim reports what a session in **this** directory pays. Memory is per-project — Claude Code loads `~/.claude/projects/<slug>/memory/` for the project you're in, not every project on disk — so running `scan` from two different repos will legitimately give you two different totals. Within that project only `MEMORY.md` is loaded at startup, and only its first 200 lines or 25KB; topic files cost nothing until Claude reads one.
 
 Token counts come from [js-tiktoken](https://github.com/nicolo-ribaudo/js-tiktoken) against the actual file contents. The only estimates left are marked with `~`: MCP tool schemas (~8 tokens/tool) and skills whose frontmatter can't be parsed (~30 tokens). Everything else is measured.
 
 ---
 
-## v2.13.1 — What's new
+## v2.15.0 — What's new
 
-- **Fixed: `scan` promised the tool never touches `~/.codex/`, while `clean --auto` deletes from it permanently.** The Codex summary closed with `Reported only — claude-slim never modifies ~/.codex/.` That was true in v2.10 and false from **v2.11** on, when `clean` gained the Codex tiers. Measured here: `clean --dry-run` selects `[Auto] [codex] temp_cache: .tmp (146MB of install leftovers) (permanent)` — Tier 1, which `--auto` applies without prompting and no `restore` undoes.
-- The summary now says what actually happens: `scan` only reads, `clean` acts under the same tiers as `~/.claude/`, moves land in `~/.codex/skills.disabled/` and reverse with `restore`, and Tier 1 install leftovers are deleted permanently.
+- **Fixed: the startup estimate counted every memory file in the project, when Claude Code loads only `MEMORY.md`.** The docs are explicit: the first 200 lines or 25KB of `MEMORY.md` are loaded at session start, and topic files are read on demand. Summing the whole directory put one project with 183 topic files at **~238,000 tokens at session start** when the session actually received about 10,000. The per-file `oversized_memory` warnings on topic files are gone for the same reason — trimming them would have saved no context.
+- **Added: the index truncation warning.** A `MEMORY.md` past the 200-line / 25KB cap is silently cut, so its newest entries never reach a session. `scan` now marks it and reports how many tokens actually arrive.
+- **Added: `~/.claude/rules/`.** Rules without `paths:` frontmatter load at launch with the same priority as CLAUDE.md; path-scoped ones load only when a matching file is read. Both are listed, only the first is summed. Reported only, never moved.
+- **Added: CLAUDE.md `@path` imports.** Files pulled in with `@RTK.md`-style imports are expanded into context at launch, recursively up to four hops. They are now listed under CLAUDE.md and counted.
 
-A test was holding the false claim in place. It asserted the summary *must* say "never modifies", so the line could not be corrected without a test failing — and all 461 tests stayed green across four releases that contradicted it. The assertion is now inverted: the summary must not promise `~/.codex/` is left alone, and must name the permanent deletion and `--auto`.
-
-Tests: 461 → 462.
+Tests: 486 → 529.
 
 For older release notes, see [CHANGELOG.md](CHANGELOG.md).
 

package/dist/cli.js

@@ -320,8 +320,10 @@ program
         'backup_artifact',
     ]);
     const removedSkillEntries = movedEntries.filter((e) => SKILL_TYPES.has(e.type));
+    // Only the current project's memory was ever in `totalTokensBefore`, so
+    // only a stale_project entry for this project restores anything to it.
     const removedMemoryTokens = movedEntries
-        .filter((e) => e.type === 'stale_project')
+        .filter((e) => e.type === 'stale_project' && e.name === result.currentProjectSlug)
         .reduce((sum, e) => sum + (e.tokenCount || 0), 0);
     const totalBefore = result.totalTokensBefore
         + removedSkillEntries.length * SKILL_PROMPT_OVERHEAD_TOKENS

package/dist/codex/index.js

@@ -4,6 +4,7 @@ import { countTokensCached } from '../tokenizer.js';
 import { listingTokens, listingTokensFromContent, parseFrontmatterDescription } from '../scanner/skill-listing.js';
 import { safeReadFile, safeReaddir, isDirectory, isBrokenSymlink } from '../scanner/fs-walk.js';
 import { detectBackupArtifact } from '../scanner/backup-artifacts.js';
+import { sanitizeUntrustedTree } from '../scanner/untrusted.js';
 // Codex support.
 //
 // The Claude Code scanner is deliberately left untouched: it is the
@@ -183,7 +184,11 @@ export async function scanCodex(contents) {
         : 0;
     const skills = [...local, ...plugin];
     const listing = (xs) => xs.reduce((sum, x) => sum + x.listingTokens, 0);
-    return {
+    // ~/.codex labels are authored by whoever wrote those skills and agents, and
+    // the CLI merges this tree into `scan --json` and prints skill names to the
+    // terminal. It never passes through the ~/.claude scanner, so it sanitizes on
+    // its own way out.
+    return sanitizeUntrustedTree({
         root: getCodexDir(),
         skills,
         agents,
@@ -192,7 +197,7 @@ export async function scanCodex(contents) {
         totalTokens: listing(skills) + listing(agents) + instructionsTokens,
         unusedDetectionAvailable: false,
         unusedDetectionReason: UNUSED_DETECTION_REASON,
-    };
+    });
 }
 /** Re-exported so callers can reuse the frontmatter parser without a deep import. */
 export { parseFrontmatterDescription };

package/dist/report.js

@@ -173,7 +173,10 @@ export function formatScanSummary(result) {
     }
     // --- CLAUDE.MD ---
     lines.push('');
-    lines.push(`\x1b[1m  CLAUDE.MD\x1b[0m (${(result.claudeMdBytes / 1024).toFixed(1)}KB, ${result.claudeMdTokens.toLocaleString()} tok)`);
+    const importSuffix = result.claudeMdImportTokens > 0
+        ? ` + ${result.claudeMdImportTokens.toLocaleString()} tok imported`
+        : '';
+    lines.push(`\x1b[1m  CLAUDE.MD\x1b[0m (${(result.claudeMdBytes / 1024).toFixed(1)}KB, ${result.claudeMdTokens.toLocaleString()} tok${importSuffix})`);
     if (result.claudeMdSections && result.claudeMdSections.length > 0) {
         for (const section of result.claudeMdSections) {
             const kb = (section.sizeBytes / 1024).toFixed(1);
@@ -181,6 +184,38 @@ export function formatScanSummary(result) {
             lines.push(`    ${section.name.padEnd(44)} ${kb.padStart(6)}KB  ${tok.padStart(7)} tok`);
         }
     }
+    // `@path` imports are expanded into context at launch beside CLAUDE.md,
+    // recursively — the indent shows which file pulled each one in.
+    for (const imp of result.claudeMdImports ?? []) {
+        const kb = (imp.sizeBytes / 1024).toFixed(1);
+        const tok = imp.tokens.toLocaleString();
+        const label = `${'  '.repeat(imp.depth - 1)}@${imp.spec}`;
+        lines.push(`    ${label.padEnd(44)} ${kb.padStart(6)}KB  ${tok.padStart(7)} tok \x1b[90m(import)\x1b[0m`);
+    }
+    // --- RULES ---
+    // Unconditional rules load at launch like CLAUDE.md; path-scoped ones load
+    // only when Claude reads a matching file, so they are listed but not summed.
+    if (result.userRules && result.userRules.length > 0) {
+        lines.push('');
+        const launched = result.userRules.filter((r) => !r.conditional).length;
+        lines.push(`\x1b[1m  RULES\x1b[0m (${result.userRules.length} files, ${launched} loaded at launch)`);
+        const sortedRules = [...result.userRules].sort((a, b) => Number(a.conditional) - Number(b.conditional) || b.tokens - a.tokens);
+        const importedPaths = new Set((result.claudeMdImports ?? []).map((i) => i.path));
+        for (const rule of sortedRules) {
+            const kb = (rule.sizeBytes / 1024).toFixed(1);
+            const tok = rule.tokens.toLocaleString();
+            const scope = rule.conditional
+                ? ` \x1b[90mpath-scoped: ${rule.paths.join(', ')}\x1b[0m`
+                : importedPaths.has(rule.path)
+                    ? ` \x1b[90malso @imported by CLAUDE.md — counted there\x1b[0m`
+                    : '';
+            lines.push(`    ${rule.name.padEnd(44)} ${kb.padStart(6)}KB  ${tok.padStart(7)} tok${scope}`);
+        }
+        lines.push(`    at launch: ${result.rulesStartupTokens.toLocaleString()} tok  ` +
+            `\x1b[90m(${result.rulesConditionalTokens.toLocaleString()} tok path-scoped, ` +
+            `loaded only when a matching file is read)\x1b[0m`);
+        lines.push(`    \x1b[90mreported only — not touched by clean\x1b[0m`);
+    }
     // --- MEMORY FILES ---
     lines.push('');
     const memTotal = result.memoryFiles.reduce((s, m) => s + m.sizeBytes, 0);
@@ -196,16 +231,21 @@ export function formatScanSummary(result) {
             project = rest ? '~' + rest : '~';
         }
         const label = `${project}/${mem.name}`;
-        // Mark the only project whose memory this session would actually load.
-        const active = mem.project === result.currentProjectSlug ? ' \x1b[32m←\x1b[0m' : '';
-        lines.push(`    ${label.padEnd(52)} ${kb.padStart(6)}KB  ${tok.padStart(7)} tok${active}`);
+        // Mark the one file this session would actually load at startup: the
+        // current project's MEMORY.md. Topic files are read on demand.
+        const isLoaded = mem.isIndex && mem.project === result.currentProjectSlug;
+        const active = isLoaded ? ' \x1b[32m←\x1b[0m' : '';
+        const cut = isLoaded && mem.truncated
+            ? ` \x1b[33m(truncated: only ${mem.startupTokens.toLocaleString()} tok reach the session)\x1b[0m`
+            : '';
+        lines.push(`    ${label.padEnd(52)} ${kb.padStart(6)}KB  ${tok.padStart(7)} tok${active}${cut}`);
     }
     if (result.memoryFiles.length > 0) {
         lines.push('');
-        lines.push(`    \x1b[32m←\x1b[0m loaded in this project: ` +
+        lines.push(`    \x1b[32m←\x1b[0m loaded at startup in this project: ` +
             `${result.currentProjectMemoryTokens.toLocaleString()} tok  ` +
-            `\x1b[90m(${result.allProjectsMemoryTokens.toLocaleString()} tok across all projects, ` +
-            `not a per-session cost)\x1b[0m`);
+            `\x1b[90m(MEMORY.md index only — topic files are read on demand; ` +
+            `${result.allProjectsMemoryTokens.toLocaleString()} tok on disk across all projects)\x1b[0m`);
         // Zero reads as "clean", so name the reason for it. Deliberately does not
         // claim the memory is unattributed: a directory Claude has simply never
         // opened has no memory, and that 0 is correct. What is worth surfacing is

package/dist/scanner/claude-md-imports.d.ts

@@ -0,0 +1,33 @@
+export interface ClaudeMdImport {
+    /** The spec as written after `@`. */
+    spec: string;
+    /** Resolved absolute path. */
+    path: string;
+    /** The file that named it. */
+    from: string;
+    /** 1 for a direct import of CLAUDE.md, up to CLAUDE_MD_IMPORT_MAX_DEPTH. */
+    depth: number;
+    sizeBytes: number;
+    tokens: number;
+}
+/**
+ * Import specs in the order they appear, ignoring fenced code blocks, inline
+ * code spans and HTML comments — the places Claude Code does not read imports
+ * from. Trailing sentence punctuation is dropped so `@docs/x.md.` imports
+ * `docs/x.md`.
+ *
+ * A fence closes only on a run of the same character at least as long as the
+ * one that opened it, so a ``` line inside a ~~~ block, or a ``` inside a
+ * ```` block, stays inside.
+ */
+export declare function extractImportSpecs(content: string): string[];
+/**
+ * Every file `rootPath` transitively imports, in discovery order.
+ *
+ * Targets that do not exist are dropped rather than reported: `@claude` or
+ * `@scope/pkg` in prose match the syntax but Claude Code loads nothing for
+ * them, so listing them would only add noise. A file already visited — the
+ * root included, compared by real path so a symlink and its target are one
+ * file — is not expanded twice, which is what keeps a cycle finite.
+ */
+export declare function resolveClaudeMdImports(rootPath: string, rootContent: string): Promise<ClaudeMdImport[]>;

package/dist/scanner/claude-md-imports.js

@@ -0,0 +1,102 @@
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { countTokensCached } from '../tokenizer.js';
+import { safeReadFile, safeStat, resolveRealPath } from './fs-walk.js';
+import { CLAUDE_MD_IMPORT_MAX_DEPTH } from './constants.js';
+/**
+ * Anything larger is not instructions. Claude Code's own behaviour on a huge
+ * import is not documented; what is certain is that reading and tokenizing a
+ * multi-hundred-megabyte log because prose said `@archive.log` must not hang
+ * a scan that is otherwise sub-second.
+ */
+const MAX_IMPORT_BYTES = 1024 * 1024;
+// `@` at line start or after whitespace / an opening bracket, followed by a
+// path. Preceded by a non-space it is an email or a handle, not an import.
+const IMPORT_PATTERN = /(^|[\s([{])@((?:~\/|\.{1,2}\/|\/)?[A-Za-z0-9_.][A-Za-z0-9_./~-]*)/g;
+const FENCE = /^\s{0,3}(`{3,}|~{3,})/;
+/**
+ * Import specs in the order they appear, ignoring fenced code blocks, inline
+ * code spans and HTML comments — the places Claude Code does not read imports
+ * from. Trailing sentence punctuation is dropped so `@docs/x.md.` imports
+ * `docs/x.md`.
+ *
+ * A fence closes only on a run of the same character at least as long as the
+ * one that opened it, so a ``` line inside a ~~~ block, or a ``` inside a
+ * ```` block, stays inside.
+ */
+export function extractImportSpecs(content) {
+    const specs = [];
+    let fence = null;
+    const body = content.replace(/<!--[\s\S]*?-->/g, ' ');
+    for (const rawLine of body.split('\n')) {
+        const m = FENCE.exec(rawLine);
+        if (m) {
+            const run = m[1];
+            if (fence === null) {
+                fence = run;
+                continue;
+            }
+            if (run[0] === fence[0] && run.length >= fence.length) {
+                fence = null;
+                continue;
+            }
+        }
+        if (fence !== null)
+            continue;
+        const line = rawLine.replace(/`[^`]*`/g, ' ');
+        for (const hit of line.matchAll(IMPORT_PATTERN)) {
+            const spec = hit[2].replace(/[.,:;!?)\]}]+$/, '');
+            if (spec.length > 0)
+                specs.push(spec);
+        }
+    }
+    return specs;
+}
+function resolveSpec(spec, fromFile) {
+    if (spec.startsWith('~/'))
+        return join(homedir(), spec.slice(2));
+    if (isAbsolute(spec))
+        return resolve(spec);
+    return resolve(dirname(fromFile), spec);
+}
+/**
+ * Every file `rootPath` transitively imports, in discovery order.
+ *
+ * Targets that do not exist are dropped rather than reported: `@claude` or
+ * `@scope/pkg` in prose match the syntax but Claude Code loads nothing for
+ * them, so listing them would only add noise. A file already visited — the
+ * root included, compared by real path so a symlink and its target are one
+ * file — is not expanded twice, which is what keeps a cycle finite.
+ */
+export async function resolveClaudeMdImports(rootPath, rootContent) {
+    const out = [];
+    const visited = new Set([await resolveRealPath(resolve(rootPath))]);
+    async function expand(fromFile, content, depth) {
+        if (depth > CLAUDE_MD_IMPORT_MAX_DEPTH)
+            return;
+        for (const spec of extractImportSpecs(content)) {
+            const path = resolveSpec(spec, fromFile);
+            const st = await safeStat(path);
+            if (st === null || !st.isFile() || st.size > MAX_IMPORT_BYTES)
+                continue;
+            const real = await resolveRealPath(path);
+            if (visited.has(real))
+                continue;
+            const body = await safeReadFile(path);
+            if (body === null)
+                continue;
+            visited.add(real);
+            out.push({
+                spec,
+                path,
+                from: fromFile,
+                depth,
+                sizeBytes: Buffer.byteLength(body),
+                tokens: countTokensCached(body, path),
+            });
+            await expand(path, body, depth + 1);
+        }
+    }
+    await expand(resolve(rootPath), rootContent, 1);
+    return out;
+}

package/dist/scanner/constants.d.ts

@@ -5,3 +5,7 @@ export declare const SKILL_PROMPT_OVERHEAD_TOKENS = 30;
 export declare const DEFERRED_TOOL_OVERHEAD_TOKENS = 8;
 export declare const COMMAND_OVERHEAD_TOKENS = 10;
 export declare const MCP_SERVER_TOOLS_AVG = 10;
+export declare const MEMORY_INDEX_FILE = "MEMORY.md";
+export declare const MEMORY_INDEX_MAX_LINES = 200;
+export declare const MEMORY_INDEX_MAX_BYTES: number;
+export declare const CLAUDE_MD_IMPORT_MAX_DEPTH = 4;

package/dist/scanner/constants.js

@@ -10,3 +10,11 @@ export const COMMAND_OVERHEAD_TOKENS = 10;
 // Average tools per MCP server (used when per-server tool count is unknown).
 // Most plugin MCP servers expose 5–15 tools; 10 is a reasonable midpoint.
 export const MCP_SERVER_TOOLS_AVG = 10;
+// Auto-memory: only the index is loaded at session start, and only its first
+// 200 lines or 25KB, whichever comes first. Topic files are read on demand.
+// Source: https://code.claude.com/docs/en/memory.md
+export const MEMORY_INDEX_FILE = 'MEMORY.md';
+export const MEMORY_INDEX_MAX_LINES = 200;
+export const MEMORY_INDEX_MAX_BYTES = 25 * 1024;
+// `@path` imports in CLAUDE.md recurse at most this many hops.
+export const CLAUDE_MD_IMPORT_MAX_DEPTH = 4;

package/dist/scanner/detectors.js

@@ -110,21 +110,28 @@ const tempCacheDetector = {
         }));
     },
 };
+// Only MEMORY.md is loaded at startup, so only MEMORY.md can be "oversized"
+// in the sense this tool cares about. A 40KB topic file costs nothing until
+// Claude decides to read it; flagging it (pre-2.15 behaviour) produced a
+// wall of recommendations whose cleanup would have saved no startup context.
 const oversizedMemoryDetector = {
     name: 'oversized_memory',
     detect({ memoryFiles }) {
         const issues = [];
         for (const mem of memoryFiles) {
-            if (mem.sizeBytes > OVERSIZED_MEMORY_BYTES) {
-                issues.push({
-                    type: 'oversized_memory',
-                    tier: 2,
-                    name: `${mem.project}/${mem.name}`,
-                    detail: `${Math.round(mem.sizeBytes / 1024)}KB`,
-                    tokens: mem.tokens,
-                    path: mem.path,
-                });
-            }
+            if (!mem.isIndex || mem.sizeBytes <= OVERSIZED_MEMORY_BYTES)
+                continue;
+            const size = `${Math.round(mem.sizeBytes / 1024)}KB`;
+            issues.push({
+                type: 'oversized_memory',
+                tier: 2,
+                name: `${mem.project}/${mem.name}`,
+                detail: mem.truncated
+                    ? `${size}, truncated at startup — entries past 200 lines/25KB are never loaded`
+                    : size,
+                tokens: mem.startupTokens,
+                path: mem.path,
+            });
         }
         return issues;
     },
@@ -133,9 +140,11 @@ const staleProjectDetector = {
     name: 'stale_project',
     detect({ staleProjects, memoryFiles }) {
         return staleProjects.map((stale) => {
+            // What a session in that project pays at startup — its index slice —
+            // not the whole directory, which is disk, not context.
             const memTokens = memoryFiles
                 .filter((m) => m.project === stale.project)
-                .reduce((sum, m) => sum + m.tokens, 0);
+                .reduce((sum, m) => sum + m.startupTokens, 0);
             return {
                 type: 'stale_project',
                 tier: 2,

package/dist/scanner/index.d.ts

@@ -26,11 +26,11 @@ export declare function scan(opts?: ScanOptions): Promise<ScanResult>;
  *
  * Memory issues count only when they belong to the current project — the same
  * per-project rule `totalTokensBefore` follows. Deletions that free disk but no
- * context (`broken_symlink`, `temp_cache`) contribute nothing here by design.
+ * context (`broken_symlink`, `temp_cache`) contribute nothing here by design,
+ * and neither does `oversized_memory`, which `clean` never acts on.
  *
- * Three separate overlaps have to be collapsed, since every one of them inflates:
- * the same skill path, the same plugin across cached versions, and a memory file
- * that its own stale project already accounts for.
+ * Two separate overlaps have to be collapsed, since both inflate: the same
+ * skill path, and the same plugin across cached versions.
  */
 export declare function sumRecoverableStartupTokens(issues: Issue[], skills: SkillInfo[], currentProjectSlug: string, 
 /** Plugin name → its skill-listing tokens. See the `unused_plugin` branch. */

package/dist/scanner/index.js

@@ -20,11 +20,13 @@ import { scanPluginSurfaces } from './plugin-surfaces.js';
 import { computePluginBreakdown } from './plugin-breakdown.js';
 import { computePluginCosts } from './plugin-cost.js';
 import { scanUserSurfaces } from './user-surfaces.js';
+import { scanUserRules } from './rules.js';
+import { resolveClaudeMdImports } from './claude-md-imports.js';
 import { sanitizeScanResult } from './untrusted.js';
 const DEFAULT_LOOKBACK_DAYS = 60;
 export async function scan(opts = {}) {
     const lookbackDays = opts.lookbackDays ?? DEFAULT_LOOKBACK_DAYS;
-    const [{ skills: localSkills, brokenSymlinks, contents }, { skills: pluginSkills, plugins, tempCaches }, { memoryFiles, staleProjects }, mcp, disabledPlugins, sessionUsage, userSurfaces,] = await Promise.all([
+    const [{ skills: localSkills, brokenSymlinks, contents }, { skills: pluginSkills, plugins, tempCaches }, { memoryFiles, staleProjects }, mcp, disabledPlugins, sessionUsage, userSurfaces, userRules,] = await Promise.all([
         scanLocalSkills(),
         scanPluginSkills(),
         scanMemoryFiles(),
@@ -32,6 +34,7 @@ export async function scan(opts = {}) {
         getDisabledPlugins(),
         scanSessionUsage(lookbackDays),
         scanUserSurfaces(),
+        scanUserRules(),
     ]);
     const pluginSurfaces = scanPluginSurfaces();
     // Annotate plugin status
@@ -46,13 +49,31 @@ export async function scan(opts = {}) {
     const enabledPlugins = installed
         .filter((p) => p.enabled)
         .map((p) => ({ name: p.name, marketplace: p.marketplace }));
-    // CLAUDE.md
-    const claudeMdContent = await safeReadFile(join(getClaudeDir(), 'CLAUDE.md'));
+    // CLAUDE.md, plus whatever it pulls in with `@path` — those files are
+    // expanded into context at launch right beside it, so they are startup cost.
+    const claudeMdPath = join(getClaudeDir(), 'CLAUDE.md');
+    const claudeMdContent = await safeReadFile(claudeMdPath);
     const claudeMdBytes = claudeMdContent ? Buffer.byteLength(claudeMdContent) : 0;
     const claudeMdTokens = claudeMdContent
-        ? countTokensCached(claudeMdContent, join(getClaudeDir(), 'CLAUDE.md'))
+        ? countTokensCached(claudeMdContent, claudeMdPath)
         : 0;
     const claudeMdSections = claudeMdContent ? parseClaudeMdSections(claudeMdContent) : [];
+    const claudeMdImports = claudeMdContent
+        ? await resolveClaudeMdImports(claudeMdPath, claudeMdContent)
+        : [];
+    const claudeMdImportTokens = claudeMdImports.reduce((sum, i) => sum + i.tokens, 0);
+    // Rules without `paths:` load at launch like CLAUDE.md. Path-scoped ones
+    // load only when a matching file is read, so they are reported, not summed.
+    // A rule CLAUDE.md also `@`-imports is already in `claudeMdImportTokens`;
+    // whether Claude Code loads such a file twice is undocumented, and counting
+    // it once is the error that cannot overstate the total.
+    const importedPaths = new Set(claudeMdImports.map((i) => i.path));
+    const rulesStartupTokens = userRules
+        .filter((r) => !r.conditional && !importedPaths.has(r.path))
+        .reduce((sum, r) => sum + r.tokens, 0);
+    const rulesConditionalTokens = userRules
+        .filter((r) => r.conditional)
+        .reduce((sum, r) => sum + r.tokens, 0);
     // Per-plugin cost map for the unused_plugin detector's savings estimate.
     // Aggregates when multiple surface entries share a pluginName (mirrors the
     // same logic in computePluginBreakdown).
@@ -131,15 +152,22 @@ export async function scan(opts = {}) {
     // disk. Summing all of them (pre-2.8 behaviour) inflated the startup estimate
     // by a factor of however many projects the user had — 100k+ tokens on a busy
     // machine, for a number labelled "tokens at session start".
+    //
+    // And within that project, only MEMORY.md's startup slice is loaded; topic
+    // files are read on demand. Summing every file (pre-2.15 behaviour) put a
+    // project with 183 topic files at ~238,000 startup tokens when the session
+    // actually received ~10,000. `startupTokens` is 0 for anything but the index.
     const currentProjectSlug = getCurrentProjectSlug(opts.projectDir);
     const currentProjectMemoryTokens = memoryFiles
         .filter((m) => m.project === currentProjectSlug)
-        .reduce((sum, m) => sum + m.tokens, 0);
+        .reduce((sum, m) => sum + m.startupTokens, 0);
     const allProjectsMemoryTokens = memoryFiles.reduce((sum, m) => sum + m.tokens, 0);
     const totalTokensBefore = skillListingTokens +
         agentListingTokens +
         commandListingTokens +
         claudeMdTokens +
+        claudeMdImportTokens +
+        rulesStartupTokens +
         currentProjectMemoryTokens;
     const currentProjectKnown = await pathExists(join(getProjectsDir(), currentProjectSlug));
     // Only the skill-listing slice of a plugin's cost is recoverable startup
@@ -162,6 +190,11 @@ export async function scan(opts = {}) {
         claudeMdBytes,
         claudeMdTokens,
         claudeMdSections,
+        claudeMdImports,
+        claudeMdImportTokens,
+        userRules,
+        rulesStartupTokens,
+        rulesConditionalTokens,
         mcpServers: mcp.count,
         mcpServerNames: mcp.names,
         issues,
@@ -205,11 +238,11 @@ const SKILL_MOVE_TYPES = new Set([
  *
  * Memory issues count only when they belong to the current project — the same
  * per-project rule `totalTokensBefore` follows. Deletions that free disk but no
- * context (`broken_symlink`, `temp_cache`) contribute nothing here by design.
+ * context (`broken_symlink`, `temp_cache`) contribute nothing here by design,
+ * and neither does `oversized_memory`, which `clean` never acts on.
  *
- * Three separate overlaps have to be collapsed, since every one of them inflates:
- * the same skill path, the same plugin across cached versions, and a memory file
- * that its own stale project already accounts for.
+ * Two separate overlaps have to be collapsed, since both inflate: the same
+ * skill path, and the same plugin across cached versions.
  */
 export function sumRecoverableStartupTokens(issues, skills, currentProjectSlug, 
 /** Plugin name → its skill-listing tokens. See the `unused_plugin` branch. */
@@ -262,15 +295,11 @@ pluginSkillListingTokens = new Map()) {
             countedPlugins.add(issue.name);
             total += pluginSkillListingTokens.get(issue.name) ?? 0;
         }
-        else if (issue.type === 'oversized_memory') {
-            // Another project's memory never loads here, so trimming it saves this
-            // session nothing.
-            if (!isCurrentProject(issue.name))
-                continue;
-            if (currentProjectIsStale)
-                continue; // already inside the stale-project total
-            total += issue.tokens;
-        }
+        // `oversized_memory` contributes nothing: the cleaner treats it as
+        // report-only, and for a truncated index the advice — trim it under the
+        // cap — frees no startup context, since the tail past the cap was never
+        // loaded. Counting it promised tokens that acting on the issue cannot
+        // return.
     }
     return total;
 }

package/dist/scanner/memory.d.ts

@@ -10,4 +10,14 @@ export interface MemoryScanResult {
     memoryFiles: MemoryFile[];
     staleProjects: StaleProject[];
 }
+/**
+ * The part of MEMORY.md a session actually receives: the first 200 lines or
+ * the first 25KB, whichever ends sooner. Everything past that is on disk but
+ * never in context — which is worth flagging, because an index that has
+ * quietly stopped listing its newest entries defeats its purpose.
+ */
+export declare function memoryIndexStartupSlice(content: string): {
+    text: string;
+    truncated: boolean;
+};
 export declare function scanMemoryFiles(): Promise<MemoryScanResult>;

package/dist/scanner/memory.js

@@ -3,7 +3,35 @@ import { join } from 'node:path';
 import { countTokensCached } from '../tokenizer.js';
 import { getProjectsDir } from '../paths.js';
 import { safeReadFile, safeReaddir } from './fs-walk.js';
-import { STALE_DAYS } from './constants.js';
+import { STALE_DAYS, MEMORY_INDEX_FILE, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, } from './constants.js';
+/**
+ * The part of MEMORY.md a session actually receives: the first 200 lines or
+ * the first 25KB, whichever ends sooner. Everything past that is on disk but
+ * never in context — which is worth flagging, because an index that has
+ * quietly stopped listing its newest entries defeats its purpose.
+ */
+export function memoryIndexStartupSlice(content) {
+    const lines = content.split('\n');
+    // A trailing newline yields an empty final element, not an extra line.
+    const lineCount = content.endsWith('\n') ? lines.length - 1 : lines.length;
+    let text = content;
+    let truncated = false;
+    if (lineCount > MEMORY_INDEX_MAX_LINES) {
+        text = lines.slice(0, MEMORY_INDEX_MAX_LINES).join('\n');
+        truncated = true;
+    }
+    const bytes = Buffer.from(text);
+    if (bytes.length > MEMORY_INDEX_MAX_BYTES) {
+        // Back off to a character boundary so the slice does not end in a torn
+        // multibyte sequence (a U+FFFD that was never in the file).
+        let cut = MEMORY_INDEX_MAX_BYTES;
+        while (cut > 0 && (bytes[cut] & 0xc0) === 0x80)
+            cut--;
+        text = bytes.subarray(0, cut).toString('utf-8');
+        truncated = true;
+    }
+    return { text, truncated };
+}
 export async function scanMemoryFiles() {
     const memoryFiles = [];
     const staleProjects = [];
@@ -21,12 +49,27 @@ export async function scanMemoryFiles() {
             const content = await safeReadFile(filePath);
             if (content !== null) {
                 const sizeBytes = Buffer.byteLength(content);
+                // Case-insensitive: on APFS `memory.md` is the file Claude Code loads.
+                const isIndex = file.toLowerCase() === MEMORY_INDEX_FILE.toLowerCase();
+                const tokens = countTokensCached(content, filePath);
+                let startupTokens = 0;
+                let truncated = false;
+                if (isIndex) {
+                    const slice = memoryIndexStartupSlice(content);
+                    truncated = slice.truncated;
+                    startupTokens = truncated
+                        ? countTokensCached(slice.text, `${filePath}#startup`)
+                        : tokens;
+                }
                 memoryFiles.push({
                     project,
                     name: file,
                     path: filePath,
                     sizeBytes,
-                    tokens: countTokensCached(content, filePath),
+                    tokens,
+                    isIndex,
+                    startupTokens,
+                    truncated,
                 });
                 totalBytes += sizeBytes;
                 try {

package/dist/scanner/rules.d.ts

@@ -0,0 +1,22 @@
+export interface RuleEntry {
+    /** Path relative to the rules directory, e.g. `common/style.md`. */
+    name: string;
+    path: string;
+    sizeBytes: number;
+    tokens: number;
+    /** True when `paths:` frontmatter scopes the rule to matching files. */
+    conditional: boolean;
+    /** The globs from `paths:`; empty for an unconditional rule. */
+    paths: string[];
+}
+/**
+ * The `paths:` list from a rule's frontmatter, or null when absent.
+ *
+ * Handles the YAML shapes seen in the wild — a block list at any indent, an
+ * inline flow list, and a bare scalar — without pulling in a YAML parser for
+ * one key. Comments and blank lines inside a block list are skipped; the list
+ * ends at the next top-level key.
+ */
+export declare function parseFrontmatterPaths(content: string): string[] | null;
+export declare function getUserRulesDir(): string;
+export declare function scanUserRules(): Promise<RuleEntry[]>;

package/dist/scanner/rules.js

@@ -0,0 +1,159 @@
+import { join, relative } from 'node:path';
+import { getClaudeDir } from '../paths.js';
+import { countTokensCached } from '../tokenizer.js';
+import { safeReadFile, safeReaddir, isDirectory, resolveRealPath } from './fs-walk.js';
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---/;
+/** Rules directories rarely nest past two levels; a symlink loop nests forever. */
+const MAX_RULES_DEPTH = 8;
+function unquote(s) {
+    const t = s.trim();
+    if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
+        return t.slice(1, -1);
+    }
+    return t;
+}
+/** Drop an unquoted trailing `# comment` from a YAML scalar. */
+function stripComment(s) {
+    let quote = null;
+    for (let i = 0; i < s.length; i++) {
+        const ch = s[i];
+        if (quote) {
+            if (ch === quote)
+                quote = null;
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+        }
+        else if (ch === '#' && (i === 0 || /\s/.test(s[i - 1]))) {
+            return s.slice(0, i);
+        }
+    }
+    return s;
+}
+/**
+ * Split a YAML flow sequence body on commas that are not inside quotes or
+ * braces — `"src/**\/*.{ts,tsx}"` is one glob, not two.
+ */
+function splitFlowList(inner) {
+    const items = [];
+    let depth = 0;
+    let quote = null;
+    let current = '';
+    for (const ch of inner) {
+        if (quote) {
+            if (ch === quote)
+                quote = null;
+            current += ch;
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+            current += ch;
+        }
+        else if (ch === '{' || ch === '[') {
+            depth++;
+            current += ch;
+        }
+        else if (ch === '}' || ch === ']') {
+            depth--;
+            current += ch;
+        }
+        else if (ch === ',' && depth === 0) {
+            items.push(current);
+            current = '';
+        }
+        else {
+            current += ch;
+        }
+    }
+    items.push(current);
+    return items.map(unquote).filter((s) => s.length > 0);
+}
+/**
+ * The `paths:` list from a rule's frontmatter, or null when absent.
+ *
+ * Handles the YAML shapes seen in the wild — a block list at any indent, an
+ * inline flow list, and a bare scalar — without pulling in a YAML parser for
+ * one key. Comments and blank lines inside a block list are skipped; the list
+ * ends at the next top-level key.
+ */
+export function parseFrontmatterPaths(content) {
+    const fm = FRONTMATTER.exec(content);
+    if (!fm)
+        return null;
+    const lines = fm[1].split(/\r?\n/);
+    const idx = lines.findIndex((l) => /^paths\s*:/.test(l));
+    if (idx === -1)
+        return null;
+    const inline = stripComment(lines[idx].replace(/^paths\s*:/, '')).trim();
+    if (inline.startsWith('[')) {
+        return splitFlowList(inline.replace(/^\[/, '').replace(/\]\s*$/, ''));
+    }
+    if (inline.length > 0)
+        return [unquote(inline)];
+    const items = [];
+    for (let i = idx + 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (/^\s*(#|$)/.test(line))
+            continue; // comment or blank
+        const m = /^\s*-\s*(.*)$/.exec(line);
+        if (!m)
+            break; // next key
+        const value = stripComment(m[1]).trim();
+        if (value)
+            items.push(unquote(value));
+    }
+    return items;
+}
+export function getUserRulesDir() {
+    return join(getClaudeDir(), 'rules');
+}
+/**
+ * Collect `*.md` files below `dir`. Directories are deduplicated by real
+ * path and capped in depth: a symlink pointing back at an ancestor would
+ * otherwise re-emit the same file once per lap until ELOOP, and every copy
+ * would be summed into the startup total.
+ */
+async function walkMarkdown(dir, out, seenDirs, depth) {
+    if (depth > MAX_RULES_DEPTH)
+        return;
+    const real = await resolveRealPath(dir);
+    if (seenDirs.has(real))
+        return;
+    seenDirs.add(real);
+    const entries = await safeReaddir(dir);
+    for (const entry of entries) {
+        const p = join(dir, entry);
+        if (await isDirectory(p)) {
+            await walkMarkdown(p, out, seenDirs, depth + 1);
+        }
+        else if (entry.endsWith('.md')) {
+            out.push(p);
+        }
+    }
+}
+export async function scanUserRules() {
+    const root = getUserRulesDir();
+    const files = [];
+    await walkMarkdown(root, files, new Set(), 0);
+    // Two names for one file (a symlinked rule beside its target) is one rule.
+    const seenFiles = new Set();
+    const entries = await Promise.all(files.map(async (path) => {
+        const real = await resolveRealPath(path);
+        if (seenFiles.has(real))
+            return null;
+        seenFiles.add(real);
+        const content = await safeReadFile(path);
+        if (content === null)
+            return null;
+        const paths = parseFrontmatterPaths(content) ?? [];
+        return {
+            name: relative(root, path).split('\\').join('/'),
+            path,
+            sizeBytes: Buffer.byteLength(content),
+            tokens: countTokensCached(content, path),
+            conditional: paths.length > 0,
+            paths,
+        };
+    }));
+    return entries.filter((e) => e !== null);
+}

package/dist/scanner/untrusted.d.ts

@@ -1,15 +1,22 @@
 import type { ScanResult } from '../types.js';
 /**
- * Names read off disk are written by whoever authored the skill, plugin, or
- * memory file — not by the user running the scan. They flow through the report
- * into the agent's context, which makes them an indirect prompt injection
- * surface: a skill directory or frontmatter `name:` can carry instructions
- * aimed at the model rather than a label aimed at a human.
+ * Names read off disk are written by whoever authored the skill, plugin, agent,
+ * or memory file — not by the person running the scan. They flow through the
+ * report into the agent's context, which makes them an indirect prompt
+ * injection surface: a directory name can carry instructions aimed at the model
+ * rather than a label aimed at a human.
  *
  * Snyk's audit of this skill (W011, medium 0.30) is about exactly this path.
  * The scan never emits file *bodies* — descriptions are measured for token cost
- * and then discarded — so what this module covers is the whole exposed surface,
- * not a sample of it.
+ * and then discarded — so labels are the whole exposed surface.
+ *
+ * v2.14.1 sanitized a hand-written list of fields and claimed that a single
+ * chokepoint could not be forgotten. That was wrong: the chokepoint was one
+ * function, but its contents were an enumeration, and the first version of it
+ * already missed `pluginSkills[].pluginName`, `pluginSkills[].plugin`, and the
+ * entire `codex` subtree — whose skill names are printed to the terminal too.
+ * So this walks the result instead of listing its fields. A field added later
+ * is covered because it exists, not because someone remembered it.
  */
 /** Longest label we render. Real names are far shorter; payloads are not. */
 export declare const MAX_NAME_LENGTH = 120;
@@ -21,10 +28,15 @@ export declare const MAX_NAME_LENGTH = 120;
  */
 export declare function sanitizeUntrusted(value: string, max?: number): string;
 /**
- * Return a copy of the scan with every outsider-authored label flattened.
+ * Return a copy of any scanned tree with every label flattened and bounded.
+ *
+ * Numbers and booleans pass through untouched; the input is not mutated.
  *
- * Applied once at the scanner's exit rather than at each of the dozen sites
- * that read a name off disk: one chokepoint cannot be forgotten by whoever adds
- * the next detector.
+ * Each scanner applies this at its own exit. There is more than one scanner:
+ * `scanCodex()` runs separately and the CLI merges it in at print time
+ * (`src/cli.ts`), so `~/.codex` labels never pass through the `~/.claude`
+ * scanner and have to be sanitized on their own way out.
  */
+export declare function sanitizeUntrustedTree<T>(value: T): T;
+/** The `~/.claude` scanner's exit. */
 export declare function sanitizeScanResult(result: ScanResult): ScanResult;

package/dist/scanner/untrusted.js

@@ -1,14 +1,21 @@
 /**
- * Names read off disk are written by whoever authored the skill, plugin, or
- * memory file — not by the user running the scan. They flow through the report
- * into the agent's context, which makes them an indirect prompt injection
- * surface: a skill directory or frontmatter `name:` can carry instructions
- * aimed at the model rather than a label aimed at a human.
+ * Names read off disk are written by whoever authored the skill, plugin, agent,
+ * or memory file — not by the person running the scan. They flow through the
+ * report into the agent's context, which makes them an indirect prompt
+ * injection surface: a directory name can carry instructions aimed at the model
+ * rather than a label aimed at a human.
  *
  * Snyk's audit of this skill (W011, medium 0.30) is about exactly this path.
  * The scan never emits file *bodies* — descriptions are measured for token cost
- * and then discarded — so what this module covers is the whole exposed surface,
- * not a sample of it.
+ * and then discarded — so labels are the whole exposed surface.
+ *
+ * v2.14.1 sanitized a hand-written list of fields and claimed that a single
+ * chokepoint could not be forgotten. That was wrong: the chokepoint was one
+ * function, but its contents were an enumeration, and the first version of it
+ * already missed `pluginSkills[].pluginName`, `pluginSkills[].plugin`, and the
+ * entire `codex` subtree — whose skill names are printed to the terminal too.
+ * So this walks the result instead of listing its fields. A field added later
+ * is covered because it exists, not because someone remembered it.
  */
 /** Longest label we render. Real names are far shorter; payloads are not. */
 export const MAX_NAME_LENGTH = 120;
@@ -20,82 +27,75 @@ const CONTROL_CHARS = /[\u0000-\u001F\u007F-\u009F]/g;
  */
 const INVISIBLE = /[\u200B-\u200F\u202A-\u202E\u2060-\u2064\u2066-\u2069\uFEFF]/g;
 /**
- * Collapse an untrusted label to a single bounded, printable line.
+ * Keys whose values are truncated only at their peril.
  *
- * Deliberately not an escape or an encoding: the value is a display label, and
- * a reversible transform would relocate a payload rather than remove it.
+ * Paths locate files that cleanup then acts on, so a shortened path is a wrong
+ * path. `currentProjectSlug` is matched against directory names. The two
+ * `*Reason` strings are our own prose and already run past the label bound.
+ * All of them are still flattened — that is the part that blocks injection.
  */
-export function sanitizeUntrusted(value, max = MAX_NAME_LENGTH) {
-    const flattened = value
+const FLATTEN_ONLY_KEYS = new Set([
+    'path',
+    'from',
+    'root',
+    'target',
+    'currentProjectSlug',
+    'unusedDetectionReason',
+]);
+/** Strip anything that could forge a row or hide from a human reader. */
+function flatten(value) {
+    return value
         .replace(CONTROL_CHARS, ' ')
         .replace(INVISIBLE, '')
         .replace(/\s+/g, ' ')
         .trim();
+}
+/**
+ * Collapse an untrusted label to a single bounded, printable line.
+ *
+ * Deliberately not an escape or an encoding: the value is a display label, and
+ * a reversible transform would relocate a payload rather than remove it.
+ */
+export function sanitizeUntrusted(value, max = MAX_NAME_LENGTH) {
+    const flattened = flatten(value);
     if (flattened.length <= max)
         return flattened;
     return `${flattened.slice(0, max)}…`;
 }
 /**
- * Paths are shown to the user and used to locate files for cleanup, so they are
- * flattened but never truncated — a shortened path would be a wrong path.
+ * Walk any scan value, sanitizing every string it contains.
+ *
+ * `key` is the property name the string arrived under; for arrays it is
+ * inherited from the property holding the array, so `mcpServerNames[]` and
+ * `plugins[].skills[]` are treated as the labels they are.
  */
-function sanitizePath(value) {
-    return value.replace(CONTROL_CHARS, ' ').replace(INVISIBLE, '').trim();
+function sanitizeDeep(value, key) {
+    if (typeof value === 'string') {
+        return FLATTEN_ONLY_KEYS.has(key) ? flatten(value) : sanitizeUntrusted(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => sanitizeDeep(entry, key));
+    }
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, sanitizeDeep(v, k)]));
+    }
+    // Numbers, booleans, null, undefined — nothing to sanitize, nothing to copy.
+    return value;
 }
 /**
- * Return a copy of the scan with every outsider-authored label flattened.
+ * Return a copy of any scanned tree with every label flattened and bounded.
  *
- * Applied once at the scanner's exit rather than at each of the dozen sites
- * that read a name off disk: one chokepoint cannot be forgotten by whoever adds
- * the next detector.
+ * Numbers and booleans pass through untouched; the input is not mutated.
+ *
+ * Each scanner applies this at its own exit. There is more than one scanner:
+ * `scanCodex()` runs separately and the CLI merges it in at print time
+ * (`src/cli.ts`), so `~/.codex` labels never pass through the `~/.claude`
+ * scanner and have to be sanitized on their own way out.
  */
+export function sanitizeUntrustedTree(value) {
+    return sanitizeDeep(value, '');
+}
+/** The `~/.claude` scanner's exit. */
 export function sanitizeScanResult(result) {
-    const skill = (s) => ({
-        ...s,
-        name: sanitizeUntrusted(s.name),
-        path: sanitizePath(s.path),
-    });
-    return {
-        ...result,
-        localSkills: result.localSkills.map(skill),
-        pluginSkills: result.pluginSkills.map(skill),
-        plugins: result.plugins.map((p) => ({
-            ...p,
-            name: sanitizeUntrusted(p.name),
-            skills: p.skills.map((s) => sanitizeUntrusted(s)),
-        })),
-        brokenSymlinks: result.brokenSymlinks.map((b) => ({
-            ...b,
-            name: sanitizeUntrusted(b.name),
-            path: sanitizePath(b.path),
-            target: sanitizeUntrusted(b.target),
-        })),
-        memoryFiles: result.memoryFiles.map((m) => ({
-            ...m,
-            project: sanitizeUntrusted(m.project),
-            name: sanitizeUntrusted(m.name),
-            path: sanitizePath(m.path),
-        })),
-        claudeMdSections: result.claudeMdSections.map((s) => ({
-            ...s,
-            name: sanitizeUntrusted(s.name),
-        })),
-        mcpServerNames: result.mcpServerNames.map((n) => sanitizeUntrusted(n)),
-        issues: result.issues.map((i) => ({
-            ...i,
-            name: sanitizeUntrusted(i.name),
-            path: sanitizePath(i.path),
-            ...(i.detail === undefined ? {} : { detail: sanitizeUntrusted(i.detail) }),
-            ...(i.marketplace === undefined
-                ? {}
-                : { marketplace: sanitizeUntrusted(i.marketplace) }),
-        })),
-        pluginBreakdown: result.pluginBreakdown.map((p) => ({
-            ...p,
-            name: sanitizeUntrusted(p.name),
-            marketplace: sanitizeUntrusted(p.marketplace),
-        })),
-        userAgents: result.userAgents.map((a) => ({ ...a, name: sanitizeUntrusted(a.name) })),
-        userCommands: result.userCommands.map((c) => ({ ...c, name: sanitizeUntrusted(c.name) })),
-    };
+    return sanitizeUntrustedTree(result);
 }

package/dist/types.d.ts

@@ -1,6 +1,8 @@
 import type { UserSurfaceEntry } from './scanner/user-surfaces.js';
+import type { RuleEntry } from './scanner/rules.js';
+import type { ClaudeMdImport } from './scanner/claude-md-imports.js';
 import type { AgentId } from './paths.js';
-export type { UserSurfaceEntry, AgentId };
+export type { UserSurfaceEntry, RuleEntry, ClaudeMdImport, AgentId };
 export interface SkillInfo {
     name: string;
     path: string;
@@ -39,7 +41,17 @@ export interface MemoryFile {
     name: string;
     path: string;
     sizeBytes: number;
+    /** Whole-file tokens — what a topic file costs once Claude reads it. */
     tokens: number;
+    /** True for `MEMORY.md`, the only memory file loaded at session start. */
+    isIndex: boolean;
+    /**
+     * Tokens this file adds at startup: the index's first 200 lines / 25KB,
+     * and 0 for every topic file, which Claude reads on demand.
+     */
+    startupTokens: number;
+    /** True when the index exceeds the startup cap and its tail is never loaded. */
+    truncated: boolean;
 }
 export interface PluginInfo {
     name: string;
@@ -83,6 +95,16 @@ export interface ScanResult {
         sizeBytes: number;
         tokens: number;
     }>;
+    /** Files `~/.claude/CLAUDE.md` pulls in via `@path`, transitively. */
+    claudeMdImports: ClaudeMdImport[];
+    /** Sum of `claudeMdImports[].tokens` — paid at startup next to CLAUDE.md. */
+    claudeMdImportTokens: number;
+    /** `~/.claude/rules/**\/*.md`, loaded at launch unless path-scoped. */
+    userRules: RuleEntry[];
+    /** Tokens of rules without `paths:` — in the session from the first turn. */
+    rulesStartupTokens: number;
+    /** Tokens of path-scoped rules — loaded only when a matching file is read. */
+    rulesConditionalTokens: number;
     mcpServers: number;
     mcpServerNames: string[];
     issues: Issue[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-slim",
-  "version": "2.14.2",
+  "version": "2.15.0",
   "description": "Audit and shrink your Claude Code startup context. Measures what every skill, plugin, agent, command, and memory file costs in the system prompt, then reversibly disables the dead weight. Non-destructive scan, tiered proposals, one-command restore — no proxy, no compression.",
   "type": "module",
   "bin": {

package/skills/claude-slim/SKILL.md

@@ -44,10 +44,10 @@ wrapper.
 
 ## Phase 0 — Version gate (run before every scan)
 
-An outdated claude-slim does not merely lack features — it reports **wrong numbers**. Versions before 2.8.0 summed memory across every project on disk and inflated the startup estimate roughly 8×. Presenting those figures as fact is worse than not running at all, so check first:
+An outdated claude-slim does not merely lack features — it reports **wrong numbers**. Versions before 2.8.0 summed memory across every project on disk and inflated the startup estimate roughly 8×; versions before 2.15.0 summed every topic file in the current project, when only `MEMORY.md` loads at startup — a 20× inflation on a memory-heavy project. Presenting those figures as fact is worse than not running at all, so check first:
 
 ```bash
-claude_slim(){ if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "$CLAUDE_PLUGIN_ROOT/dist/cli.js" ]; then node "$CLAUDE_PLUGIN_ROOT/dist/cli.js" "$@"; elif command -v claude-slim >/dev/null 2>&1; then claude-slim "$@"; else npx -y 'claude-slim@^2.14.2' "$@"; fi; }
+claude_slim(){ if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "$CLAUDE_PLUGIN_ROOT/dist/cli.js" ]; then node "$CLAUDE_PLUGIN_ROOT/dist/cli.js" "$@"; elif command -v claude-slim >/dev/null 2>&1; then claude-slim "$@"; else npx -y 'claude-slim@^2.15.0' "$@"; fi; }
 claude_slim check-update --json
 ```
 
@@ -80,7 +80,7 @@ If `"outdated": false`, say nothing and continue to Phase 1.
 Run the CLI to collect environment data:
 
 ```bash
-claude_slim(){ if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "$CLAUDE_PLUGIN_ROOT/dist/cli.js" ]; then node "$CLAUDE_PLUGIN_ROOT/dist/cli.js" "$@"; elif command -v claude-slim >/dev/null 2>&1; then claude-slim "$@"; else npx -y 'claude-slim@^2.14.2' "$@"; fi; }
+claude_slim(){ if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "$CLAUDE_PLUGIN_ROOT/dist/cli.js" ]; then node "$CLAUDE_PLUGIN_ROOT/dist/cli.js" "$@"; elif command -v claude-slim >/dev/null 2>&1; then claude-slim "$@"; else npx -y 'claude-slim@^2.15.0' "$@"; fi; }
 claude_slim scan --json
 ```
 
@@ -135,8 +135,9 @@ Show a summary table:
 |------|-------|--------|
 | Local skills | N (XKB) | X tok |
 | Plugins | N (M skills) | ~X tok |
-| CLAUDE.md | XKB | X tok |
-| Memory files | N (XKB) | ~X tok |
+| CLAUDE.md | XKB | X tok (+ X tok `@path` imports) |
+| Rules | N files | X tok at launch (X tok path-scoped) |
+| Memory index | MEMORY.md XKB | X tok at startup (`currentProjectMemoryTokens`) |
 | **Session startup overhead** | | **~X tok** (`totalTokensBefore`) |
 
 **Check `currentProjectKnown` before presenting memory numbers.** When it is
@@ -200,20 +201,20 @@ If subcommand is `scan`, stop here. Ask a localized equivalent of "Proceed with
 Run the interactive clean command:
 
 ```bash
-claude_slim(){ if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "$CLAUDE_PLUGIN_ROOT/dist/cli.js" ]; then node "$CLAUDE_PLUGIN_ROOT/dist/cli.js" "$@"; elif command -v claude-slim >/dev/null 2>&1; then claude-slim "$@"; else npx -y 'claude-slim@^2.14.2' "$@"; fi; }
+claude_slim(){ if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "$CLAUDE_PLUGIN_ROOT/dist/cli.js" ]; then node "$CLAUDE_PLUGIN_ROOT/dist/cli.js" "$@"; elif command -v claude-slim >/dev/null 2>&1; then claude-slim "$@"; else npx -y 'claude-slim@^2.15.0' "$@"; fi; }
 claude_slim clean
 ```
 
 Or with dry-run:
 ```bash
-claude_slim(){ if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "$CLAUDE_PLUGIN_ROOT/dist/cli.js" ]; then node "$CLAUDE_PLUGIN_ROOT/dist/cli.js" "$@"; elif command -v claude-slim >/dev/null 2>&1; then claude-slim "$@"; else npx -y 'claude-slim@^2.14.2' "$@"; fi; }
+claude_slim(){ if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "$CLAUDE_PLUGIN_ROOT/dist/cli.js" ]; then node "$CLAUDE_PLUGIN_ROOT/dist/cli.js" "$@"; elif command -v claude-slim >/dev/null 2>&1; then claude-slim "$@"; else npx -y 'claude-slim@^2.15.0' "$@"; fi; }
 claude_slim clean --dry-run
 ```
 
 After cleanup, re-run scan to get updated numbers, then show the savings report:
 
 ```bash
-claude_slim(){ if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "$CLAUDE_PLUGIN_ROOT/dist/cli.js" ]; then node "$CLAUDE_PLUGIN_ROOT/dist/cli.js" "$@"; elif command -v claude-slim >/dev/null 2>&1; then claude-slim "$@"; else npx -y 'claude-slim@^2.14.2' "$@"; fi; }
+claude_slim(){ if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "$CLAUDE_PLUGIN_ROOT/dist/cli.js" ]; then node "$CLAUDE_PLUGIN_ROOT/dist/cli.js" "$@"; elif command -v claude-slim >/dev/null 2>&1; then claude-slim "$@"; else npx -y 'claude-slim@^2.15.0' "$@"; fi; }
 claude_slim report
 ```
 
@@ -226,7 +227,7 @@ Present the report box AND the before/after breakdown table to the user.
 When `/claude-slim restore` is invoked:
 
 ```bash
-claude_slim(){ if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "$CLAUDE_PLUGIN_ROOT/dist/cli.js" ]; then node "$CLAUDE_PLUGIN_ROOT/dist/cli.js" "$@"; elif command -v claude-slim >/dev/null 2>&1; then claude-slim "$@"; else npx -y 'claude-slim@^2.14.2' "$@"; fi; }
+claude_slim(){ if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "$CLAUDE_PLUGIN_ROOT/dist/cli.js" ]; then node "$CLAUDE_PLUGIN_ROOT/dist/cli.js" "$@"; elif command -v claude-slim >/dev/null 2>&1; then claude-slim "$@"; else npx -y 'claude-slim@^2.15.0' "$@"; fi; }
 claude_slim restore
 ```
 
@@ -235,7 +236,7 @@ claude_slim restore
 When `/claude-slim doctor` is invoked:
 
 ```bash
-claude_slim(){ if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "$CLAUDE_PLUGIN_ROOT/dist/cli.js" ]; then node "$CLAUDE_PLUGIN_ROOT/dist/cli.js" "$@"; elif command -v claude-slim >/dev/null 2>&1; then claude-slim "$@"; else npx -y 'claude-slim@^2.14.2' "$@"; fi; }
+claude_slim(){ if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "$CLAUDE_PLUGIN_ROOT/dist/cli.js" ]; then node "$CLAUDE_PLUGIN_ROOT/dist/cli.js" "$@"; elif command -v claude-slim >/dev/null 2>&1; then claude-slim "$@"; else npx -y 'claude-slim@^2.15.0' "$@"; fi; }
 claude_slim doctor
 ```