turntax 0.1.0 → 0.3.0

package/dist/core/render.js

@@ -1,3 +1,4 @@
+import { DEFERRED_NOTE } from './mcp.js';
 export const METHOD_LABEL = {
     'offline-exact': 'exact (offline tokenizer)',
     'offline-proxy': 'estimate (o200k_base proxy)',
@@ -21,9 +22,149 @@ function table(rows, indent = '') {
     const widths = rows[0].map((_, c) => Math.max(...rows.map((r) => (r[c] ?? '').length)));
     return rows.map((r) => indent + r.map((cell, c) => cell.padEnd(widths[c])).join('  ').trimEnd()).join('\n');
 }
-/** Highest always-loaded o200k total across the reported tools. */
+/**
+ * Agents that load exactly the same files with the same results share one row,
+ * so a repository with only AGENTS.md does not print a dozen identical lines.
+ */
+export function groupTools(report) {
+    const groups = new Map();
+    for (const t of report.tools) {
+        const files = report.files
+            .filter((f) => f.tool === t.tool && f.mode !== 'ignored')
+            .map((f) => [f.path, f.part, f.mode, f.o200k])
+            .sort();
+        const key = JSON.stringify([
+            files,
+            t.models.map(({ model, perTurn, method, reason }) => [model, perTurn, method, reason]),
+            report.mcp.filter((m) => m.tool === t.tool).map((m) => [m.configPath, m.name, m.status, m.o200k]),
+        ]);
+        const g = groups.get(key);
+        if (g)
+            g.names.push(t.name);
+        else
+            groups.set(key, { names: [t.name], tool: t });
+    }
+    return [...groups.values()];
+}
+/** File rows that are identical across agents, merged with the list of agents. */
+export function groupFiles(report) {
+    const groups = new Map();
+    for (const f of report.files) {
+        const key = JSON.stringify([f.path, f.part, f.mode, f.trigger, f.o200k, f.importedFrom ?? '']);
+        const g = groups.get(key);
+        if (g)
+            g.tools.push(f.tool);
+        else
+            groups.set(key, { file: f, tools: [f.tool] });
+    }
+    return [...groups.values()];
+}
+/**
+ * Highest per-turn o200k total across the reported tools, for the badge and --max-tokens:
+ * repository files plus measured project MCP tool definitions. User-level files never count here.
+ */
 export function headlineTokens(report) {
-    return Math.max(0, ...report.tools.map((t) => t.perTurnO200k));
+    return Math.max(0, ...report.tools.map((t) => t.perTurnO200k + (t.mcpPerTurnO200k ?? 0)));
+}
+/** MCP cell: measured tokens, a "+" when some servers could not be measured, or how many are unmeasured. */
+export function mcpCell(t) {
+    if (!t.mcpServers)
+        return '-';
+    if (t.mcpMeasured)
+        return fmtTokens(t.mcpPerTurnO200k);
+    return t.mcpPerTurnO200k > 0 ? `${fmtTokens(t.mcpPerTurnO200k)}+` : `${t.mcpServers} not measured`;
+}
+function signed(n) {
+    return n > 0 ? `+${fmtTokens(n)}` : n < 0 ? `-${fmtTokens(-n)}` : '0';
+}
+function fmtMaybe(n) {
+    return n === null ? '-' : fmtTokens(n);
+}
+/** Agents with the same before/after numbers share one line. */
+function groupDeltas(diff) {
+    const groups = new Map();
+    for (const t of diff.tools) {
+        const key = `${t.before}|${t.after}`;
+        const g = groups.get(key);
+        if (g)
+            g.names.push(t.name);
+        else
+            groups.set(key, { names: [t.name], before: t.before, after: t.after, delta: t.delta });
+    }
+    return [...groups.values()].sort((a, b) => b.delta - a.delta);
+}
+export function renderDiffText(diff) {
+    const out = [`Change vs ${diff.base} (o200k tokens per turn, repository files)`];
+    const changed = groupDeltas(diff).filter((g) => g.delta !== 0);
+    if (!changed.length)
+        out.push('  No change in per-turn tokens.');
+    else {
+        const rows = [['before', 'after', 'change', 'agents']];
+        for (const g of changed)
+            rows.push([fmtMaybe(g.before), fmtMaybe(g.after), signed(g.delta), g.names.join(', ')]);
+        out.push(table(rows, '  '));
+    }
+    if (diff.files.length) {
+        out.push('  Files loaded every turn');
+        const rows = [['before', 'after', 'change', 'file']];
+        for (const f of diff.files)
+            rows.push([fmtMaybe(f.before), fmtMaybe(f.after), signed(f.delta), f.part === 'full' ? f.path : `${f.path} (${f.part})`]);
+        out.push(table(rows, '    '));
+    }
+    for (const s of diff.mcp.added)
+        out.push(`  MCP server added: ${s}`);
+    for (const s of diff.mcp.removed)
+        out.push(`  MCP server removed: ${s}`);
+    return out.join('\n');
+}
+export function renderDiffMarkdown(diff) {
+    const out = [`## Change vs \`${diff.base}\``, ''];
+    const changed = groupDeltas(diff).filter((g) => g.delta !== 0);
+    if (!changed.length)
+        out.push('No change in per-turn tokens (o200k, repository files).');
+    else {
+        out.push('o200k tokens added to every turn by repository instruction files.', '');
+        out.push('| Agents | Before | After | Change |', '| --- | ---: | ---: | ---: |');
+        for (const g of changed)
+            out.push(`| ${g.names.join(', ')} | ${fmtMaybe(g.before)} | ${fmtMaybe(g.after)} | **${signed(g.delta)}** |`);
+    }
+    if (diff.files.length) {
+        out.push('', '| File loaded every turn | Before | After | Change |', '| --- | ---: | ---: | ---: |');
+        for (const f of diff.files)
+            out.push(`| \`${f.part === 'full' ? f.path : `${f.path} (${f.part})`}\` | ${fmtMaybe(f.before)} | ${fmtMaybe(f.after)} | ${signed(f.delta)} |`);
+    }
+    if (diff.mcp.added.length || diff.mcp.removed.length) {
+        out.push('');
+        for (const s of diff.mcp.added)
+            out.push(`- MCP server added: ${s}`);
+        for (const s of diff.mcp.removed)
+            out.push(`- MCP server removed: ${s}`);
+    }
+    return out.join('\n');
+}
+/** MCP rows that are identical apart from the agent, merged. */
+function groupMcp(rows) {
+    const groups = new Map();
+    for (const r of rows) {
+        const key = JSON.stringify([r.configPath, r.name, r.status, r.tools, r.o200k, r.error]);
+        const g = groups.get(key);
+        if (g)
+            g.tools.push(r.tool);
+        else
+            groups.set(key, { row: r, tools: [r.tool] });
+    }
+    return [...groups.values()];
+}
+function mcpDetail(r) {
+    if (r.status === 'measured')
+        return r.deferredO200k === undefined
+            ? `${r.tools} tools`
+            : `${r.tools} tools; names only, full definitions (${fmtTokens(r.deferredO200k)}) load when used`;
+    if (r.status === 'disabled')
+        return 'disabled in the config';
+    if (r.status === 'failed')
+        return r.error ?? 'failed';
+    return 'run with --mcp to count its tool definitions';
 }
 export function renderText(report, root) {
     const out = [];
@@ -33,31 +174,55 @@ export function renderText(report, root) {
         out.push('No agent instruction files found.');
         return out.join('\n');
     }
+    if (report.diff) {
+        out.push(renderDiffText(report.diff));
+        out.push('');
+    }
+    const showMcp = report.tools.some((t) => t.mcpServers > 0);
+    const showUser = report.tools.some((t) => t.userAlwaysFiles > 0 || t.userPerTurnO200k > 0);
+    const extra = [...(showMcp ? ['mcp/turn'] : []), ...(showUser ? ['user/turn'] : []), ...(showMcp || showUser ? ['total'] : [])];
     const rows = [
-        ['tool', 'always', 'o200k/turn', 'on-demand', 'model', 'tokens/turn', 'counted by', `${report.turns} turns`, 'cached'],
+        ['always', 'o200k/turn', 'on-demand', ...extra, 'model', 'tokens/turn', 'counted by', `${report.turns} turns`, 'cached', 'agents'],
     ];
-    for (const t of report.tools) {
-        const head = [t.name, String(t.alwaysFiles), fmtTokens(t.perTurnO200k), fmtTokens(t.onDemandO200k)];
+    for (const { names, tool: t } of groupTools(report)) {
+        const head = [
+            String(t.alwaysFiles),
+            fmtTokens(t.perTurnO200k),
+            fmtTokens(t.onDemandO200k),
+            ...(showMcp ? [mcpCell(t)] : []),
+            ...(showUser ? [fmtTokens(t.userPerTurnO200k)] : []),
+            ...(showMcp || showUser ? [fmtTokens(t.totalPerTurnO200k) + (t.mcpMeasured ? '' : '+')] : []),
+        ];
         const blank = head.map(() => '');
+        const agents = names.join(', ');
         if (!t.models.length)
-            rows.push([...head, '(no selected model)', '', '', '', '']);
+            rows.push([...head, '(no selected model)', '', '', '', '', agents]);
         t.models.forEach((m, i) => rows.push([
             ...(i === 0 ? head : blank),
             m.label,
             ...(m.perTurn === null
                 ? ['-', m.reason ?? METHOD_LABEL[m.method], '-', '-']
                 : [fmtTokens(m.perTurn), METHOD_LABEL[m.method], fmtUsd(m.uncached), fmtUsd(m.cached)]),
+            i === 0 ? agents : '',
         ]));
     }
     out.push(table(rows));
     out.push('');
     out.push('Files');
-    const fileRows = [['tool', 'mode', 'file', 'o200k', 'loads']];
-    for (const f of report.files) {
+    const fileRows = [['mode', 'file', 'o200k', 'loads', 'agents']];
+    for (const { file: f, tools } of groupFiles(report)) {
         const name = f.part === 'full' ? f.path : `${f.path} (${f.part})`;
-        fileRows.push([f.tool, f.mode, name + (f.importedFrom ? ` <- @${f.importedFrom}` : ''), fmtTokens(f.o200k), f.trigger]);
+        fileRows.push([f.mode, name + (f.importedFrom ? ` <- @${f.importedFrom}` : ''), fmtTokens(f.o200k), f.trigger, tools.join(', ')]);
     }
     out.push(table(fileRows, '  '));
+    if (report.mcp.length) {
+        out.push('');
+        out.push('MCP servers (tool definitions are sent every turn)');
+        const mcpRows = [['status', 'server', 'config', 'o200k', 'detail', 'agents']];
+        for (const { row: r, tools } of groupMcp(report.mcp))
+            mcpRows.push([r.status, r.name, r.configPath, r.o200k === undefined ? '-' : fmtTokens(r.o200k), mcpDetail(r), tools.join(', ')]);
+        out.push(table(mcpRows, '  '));
+    }
     const notes = [...new Set(report.files.flatMap((f) => f.notes.map((n) => `${f.path}: ${n}`)))];
     if (notes.length) {
         out.push('');
@@ -84,6 +249,10 @@ function footer(report) {
         'o200k = OpenAI o200k_base, counted offline. It is a reference for every file, not a Claude or Gemini count.',
         'Claude and Gemini tokenizers are not public: their counts come only from the vendor APIs (--claude-api, --gemini-api).',
         `Cost = tokens/turn x ${report.turns} turns x input price. "Cached" assumes every turn reads the context from the prompt cache.`,
+        ...(report.mcp.length
+            ? ['MCP tool definitions are counted as JSON with o200k (an estimate of what the agent sends) and are not included in model costs.']
+            : []),
+        ...(report.mcp.some((m) => m.deferredO200k !== undefined) ? [DEFERRED_NOTE] : []),
         'Prices (USD per 1M input tokens):',
     ];
     for (const m of report.models) {
@@ -94,21 +263,35 @@ function footer(report) {
 }
 export function renderMarkdown(report) {
     const out = ['# Agent context tax report', ''];
+    if (report.diff)
+        out.push(renderDiffMarkdown(report.diff), '');
     out.push(`Every agent re-sends its always-loaded instruction files with each turn. Costs are for ${report.turns} turns.`, '');
-    out.push('## Per tool', '');
-    out.push('| Tool | Model | Tokens / turn | Counted by | Uncached | Cached |', '| --- | --- | ---: | --- | ---: | ---: |');
-    for (const t of report.tools) {
+    out.push('## Per agent', '');
+    out.push('| Agents | Model | Tokens / turn | Counted by | Uncached | Cached |', '| --- | --- | ---: | --- | ---: | ---: |');
+    for (const { names, tool: t } of groupTools(report)) {
+        const agents = names.join(', ');
         if (!t.models.length)
-            out.push(`| ${t.name} | - | ${fmtTokens(t.perTurnO200k)} (o200k) | reference | - | - |`);
+            out.push(`| ${agents} | - | ${fmtTokens(t.perTurnO200k)} (o200k) | reference | - | - |`);
         for (const m of t.models)
             out.push(m.perTurn === null
-                ? `| ${t.name} | ${m.label} | - | ${m.reason ?? ''} | - | - |`
-                : `| ${t.name} | ${m.label} | ${fmtTokens(m.perTurn)} | ${METHOD_LABEL[m.method]} | ${fmtUsd(m.uncached)} | ${fmtUsd(m.cached)} |`);
+                ? `| ${agents} | ${m.label} | - | ${m.reason ?? ''} | - | - |`
+                : `| ${agents} | ${m.label} | ${fmtTokens(m.perTurn)} | ${METHOD_LABEL[m.method]} | ${fmtUsd(m.uncached)} | ${fmtUsd(m.cached)} |`);
     }
-    out.push('', '## Files', '', '| Tool | Mode | File | o200k tokens | Loads |', '| --- | --- | --- | ---: | --- |');
-    for (const f of report.files) {
+    if (report.tools.some((t) => t.mcpServers > 0 || t.userAlwaysFiles > 0 || t.userPerTurnO200k > 0)) {
+        out.push('', '### Every turn, by source (o200k)', '');
+        out.push('| Agents | Repository files | MCP tools | User level | Total |', '| --- | ---: | ---: | ---: | ---: |');
+        for (const { names, tool: t } of groupTools(report))
+            out.push(`| ${names.join(', ')} | ${fmtTokens(t.perTurnO200k)} | ${mcpCell(t)} | ${fmtTokens(t.userPerTurnO200k)} | ${fmtTokens(t.totalPerTurnO200k)}${t.mcpMeasured ? '' : '+'} |`);
+    }
+    if (report.mcp.length) {
+        out.push('', '## MCP servers', '', '| Status | Server | Config | o200k tokens | Detail | Agents |', '| --- | --- | --- | ---: | --- | --- |');
+        for (const { row: r, tools } of groupMcp(report.mcp))
+            out.push(`| ${r.status} | ${escapeCell(r.name)} | \`${r.configPath}\` | ${r.o200k === undefined ? '-' : fmtTokens(r.o200k)} | ${escapeCell(mcpDetail(r))} | ${tools.join(', ')} |`);
+    }
+    out.push('', '## Files', '', '| Mode | File | o200k tokens | Loads | Agents |', '| --- | --- | ---: | --- | --- |');
+    for (const { file: f, tools } of groupFiles(report)) {
         const name = f.part === 'full' ? f.path : `${f.path} (${f.part})`;
-        out.push(`| ${f.tool} | ${f.mode} | \`${name}\` | ${fmtTokens(f.o200k)} | ${escapeCell(f.trigger)} |`);
+        out.push(`| ${f.mode} | \`${name}\` | ${fmtTokens(f.o200k)} | ${escapeCell(f.trigger)} | ${tools.join(', ')} |`);
     }
     out.push('', '## Advice', '');
     if (!report.advice.length)
@@ -121,6 +304,10 @@ export function renderMarkdown(report) {
     out.push('- o200k = OpenAI `o200k_base`, counted offline; a reference, not a Claude or Gemini count.');
     out.push('- Claude counts come only from Anthropic `count_tokens`; Gemini counts only from Google `countTokens`.');
     out.push('- "Cached" assumes every turn reads the context from the prompt cache.');
+    if (report.mcp.length)
+        out.push('- MCP tool definitions are counted as JSON with o200k, an estimate of what the agent sends; they are not in the model costs.');
+    if (report.mcp.some((m) => m.deferredO200k !== undefined))
+        out.push(`- ${DEFERRED_NOTE}`);
     for (const m of report.models)
         out.push(`- ${m.label}: $${m.inputPerMTok ?? 'n/a'} input / $${m.cachedInputPerMTok ?? 'n/a'} cached per 1M tokens ([source](${m.source}), checked ${m.checkedAt}).`);
     out.push('', badgeMarkdown(report));
@@ -141,3 +328,17 @@ export function badgeUrl(report) {
 export function badgeMarkdown(report) {
     return `[![context tax (o200k)](${badgeUrl(report)})](https://github.com/TorutDev/turntax)`;
 }
+export const PR_COMMENT_MARKER = '<!-- turntax-report -->';
+const COMMENT_LIMIT = 60_000;
+/**
+ * A pull request comment: the change against the base branch first, the full report folded below.
+ * Starts with a marker so the GitHub Action can update its own comment instead of adding new ones.
+ */
+export function renderPrComment(report) {
+    const top = report.diff ? renderDiffMarkdown(report.diff) : '## Agent context tax';
+    const headline = `Largest per-turn cost: **${fmtTokens(headlineTokens(report))}** o200k tokens (repository files and measured project MCP tools).`;
+    let full = renderMarkdown({ ...report, diff: undefined }).replace(/^# .*\n\n/, '');
+    if (full.length > COMMENT_LIMIT)
+        full = full.slice(0, COMMENT_LIMIT) + '\n\n_Report cut to fit in a comment; the job summary has all of it._\n';
+    return [PR_COMMENT_MARKER, top, '', headline, '', '<details><summary>Full report</summary>', '', full, '</details>', ''].join('\n');
+}

package/dist/core/tools.js

@@ -291,6 +291,256 @@ export const TOOLS = [
         ],
         notes: ['Global rules (~/.codeium/windsurf/memories/global_rules.md) are outside the repository and not counted.'],
     },
+    {
+        id: 'cline',
+        name: 'Cline',
+        families: [],
+        sources: ['https://docs.cline.bot/features/cline-rules'],
+        checkedAt: '2026-10-10',
+        rules: [
+            {
+                kind: 'frontmatter',
+                pattern: /^\.(?:clinerules|cline\/rules)\/.+\.md$/,
+                rootPrefixes: ['.clinerules/', '.cline/rules/'],
+                decide: (fm) => {
+                    if (Array.isArray(fm.paths) && fm.paths.length === 0)
+                        return { mode: 'ignored', trigger: 'paths: [] (never applies)' };
+                    if (has(fm, 'paths'))
+                        return { mode: 'on-demand', trigger: `paths: ${str(fm.paths)}` };
+                    return { mode: 'always', trigger: 'rule without paths' };
+                },
+            },
+        ],
+        limits: [],
+        notes: [
+            'Each rule can be toggled off in Cline; the audit assumes rules are on.',
+            'Cline also detects AGENTS.md, .cursorrules and .windsurfrules; whether they are on by default is not documented, so they are not counted.',
+            'A single .clinerules file (instead of a folder) is not documented and is not counted.',
+        ],
+    },
+    {
+        id: 'roo-code',
+        name: 'Roo Code',
+        families: [],
+        sources: ['https://roocodeinc.github.io/Roo-Code/features/custom-instructions'],
+        checkedAt: '2026-10-10',
+        rules: [
+            {
+                kind: 'precedence',
+                groups: [
+                    { label: '.roo/rules/', patterns: [/^\.roo\/rules\/.+/] },
+                    { label: '.roorules', patterns: [/^\.roorules$/] },
+                    { label: '.clinerules', patterns: [/^\.clinerules$/] },
+                ],
+                note: 'Legacy .roorules and .clinerules are read only when .roo/rules/ has no content; their order between each other is assumed.',
+            },
+            { kind: 'pattern', pattern: /^\.roo\/rules-[\w-]+\/.+/, mode: 'on-demand', trigger: 'only in that Roo mode' },
+            { kind: 'pattern', pattern: /^\.roorules-[\w-]+$/, mode: 'on-demand', trigger: 'only in that Roo mode (legacy)' },
+            {
+                kind: 'hierarchical',
+                names: ['AGENTS.md', 'AGENT.md'],
+                onePerDirectory: true,
+                nested: 'skip',
+                nestedTrigger: '',
+                note: 'Read by default; the roo-cline.useAgentRules setting turns it off.',
+            },
+        ],
+        limits: [],
+        notes: ['Global ~/.roo/rules/ is outside the repository and not counted.'],
+    },
+    {
+        id: 'kiro',
+        name: 'Kiro',
+        families: [],
+        sources: ['https://kiro.dev/docs/steering/'],
+        checkedAt: '2026-10-10',
+        rules: [
+            {
+                kind: 'frontmatter',
+                pattern: /^\.kiro\/steering\/[^/]+\.md$/,
+                rootPrefixes: ['.kiro/steering/'],
+                decide: (fm) => {
+                    switch (str(fm.inclusion).trim()) {
+                        case '':
+                        case 'always':
+                            return { mode: 'always', trigger: 'inclusion: always' };
+                        case 'fileMatch':
+                            return { mode: 'on-demand', trigger: `fileMatch: ${str(fm.fileMatchPattern)}` };
+                        case 'manual':
+                            return { mode: 'manual', trigger: 'inclusion: manual (#name)' };
+                        case 'auto':
+                            return {
+                                mode: 'on-demand',
+                                trigger: 'inclusion: auto (matched on description)',
+                                descriptionOnly: true,
+                                note: 'Description assumed to be in context so Kiro can match it (inferred, not documented).',
+                            };
+                        default:
+                            return { mode: 'always', trigger: `inclusion: ${str(fm.inclusion)} (unknown, treated as always)` };
+                    }
+                },
+            },
+            { kind: 'hierarchical', names: ['AGENTS.md'], nested: 'skip', nestedTrigger: '' },
+        ],
+        limits: [],
+        notes: [
+            'fileMatch and manual modes need Kiro CLI V3; older versions skip those files.',
+            'Global ~/.kiro/steering/ is outside the repository and not counted.',
+        ],
+    },
+    {
+        id: 'junie',
+        name: 'JetBrains Junie',
+        families: [],
+        sources: ['https://junie.jetbrains.com/docs/guidelines-and-memory.html'],
+        checkedAt: '2026-10-10',
+        rules: [
+            {
+                kind: 'precedence',
+                groups: [
+                    { label: '.junie/AGENTS.md', patterns: [/^\.junie\/AGENTS\.md$/] },
+                    { label: 'AGENTS.md', patterns: [/^AGENTS\.md$/, /^\.junie\/playbook\.md$/, /^\.junie\/rules\/[^/]+\.md$/] },
+                    { label: '.junie/guidelines', patterns: [/^\.junie\/guidelines\.md$/, /^\.junie\/guidelines\/[^/]+\.md$/] },
+                ],
+                note: 'Follows the IDE plugin order; a custom guidelines path set in project settings is not modelled.',
+            },
+        ],
+        limits: [],
+        notes: ['Global ~/.junie/AGENTS.md is outside the repository and not counted.'],
+    },
+    {
+        id: 'zed',
+        name: 'Zed',
+        families: [],
+        sources: ['https://zed.dev/docs/ai/instructions'],
+        checkedAt: '2026-10-10',
+        rules: [
+            {
+                kind: 'precedence',
+                groups: [
+                    '.rules',
+                    '.cursorrules',
+                    '.windsurfrules',
+                    '.clinerules',
+                    '.github/copilot-instructions.md',
+                    'AGENT.md',
+                    'AGENTS.md',
+                    'CLAUDE.md',
+                    'GEMINI.md',
+                ].map((path) => ({ label: path, patterns: [new RegExp(`^${path.replace(/\./g, '\\.')}$`)] })),
+                note: 'Zed uses only the first of these files it finds at the project root.',
+            },
+        ],
+        limits: [],
+        notes: ['Personal ~/.config/zed/AGENTS.md is outside the repository and not counted.'],
+    },
+    {
+        id: 'continue',
+        name: 'Continue',
+        families: [],
+        sources: ['https://docs.continue.dev/customize/deep-dives/rules'],
+        checkedAt: '2026-10-10',
+        rules: [
+            {
+                kind: 'frontmatter',
+                pattern: /^\.continue\/rules\/[^/]+\.md$/,
+                rootPrefixes: ['.continue/rules/'],
+                decide: (fm) => {
+                    const always = fm.alwaysApply === true || str(fm.alwaysApply) === 'true';
+                    const never = fm.alwaysApply === false || str(fm.alwaysApply) === 'false';
+                    if (always)
+                        return { mode: 'always', trigger: 'alwaysApply: true' };
+                    if (has(fm, 'globs'))
+                        return { mode: 'on-demand', trigger: `globs: ${str(fm.globs)}` };
+                    if (!never)
+                        return { mode: 'always', trigger: 'no globs' };
+                    if (has(fm, 'description'))
+                        return {
+                            mode: 'on-demand',
+                            trigger: 'agent decides from description',
+                            descriptionOnly: true,
+                            note: 'Description assumed to be in context so the agent can decide (inferred, not documented).',
+                        };
+                    return { mode: 'on-demand', trigger: 'alwaysApply: false (agent decides)' };
+                },
+            },
+        ],
+        limits: [],
+        notes: ['Rules in config.yaml or from the Continue hub are not counted.'],
+    },
+    {
+        id: 'aider',
+        name: 'Aider',
+        families: [],
+        sources: ['https://aider.chat/docs/usage/conventions.html'],
+        checkedAt: '2026-10-10',
+        rules: [
+            { kind: 'config-list', configPath: '.aider.conf.yml', key: 'read', trigger: 'read: in .aider.conf.yml' },
+            { kind: 'pattern', pattern: /^CONVENTIONS\.md$/, mode: 'manual', trigger: 'only with --read, /read or read: in .aider.conf.yml' },
+        ],
+        limits: [],
+        notes: ['Aider loads no instruction file by itself; files given with --read are sent with every request.'],
+    },
+    {
+        id: 'goose',
+        name: 'Goose',
+        families: [],
+        sources: ['https://goose-docs.ai/docs/guides/context-engineering/using-goosehints'],
+        checkedAt: '2026-10-10',
+        rules: [
+            {
+                kind: 'hierarchical',
+                names: ['AGENTS.md', '.goosehints'],
+                nested: 'on-demand',
+                nestedTrigger: 'when goose accesses files in',
+            },
+        ],
+        limits: [],
+        notes: [
+            'Needs the Developer extension; CONTEXT_FILE_NAMES can change which files are read.',
+            'Global ~/.config/goose/.goosehints is outside the repository and not counted.',
+        ],
+    },
+    {
+        id: 'amp',
+        name: 'Amp',
+        families: [],
+        sources: ['https://ampcode.com/docs/customize/agents-md'],
+        checkedAt: '2026-10-10',
+        rules: [
+            {
+                kind: 'hierarchical',
+                names: ['AGENTS.md', 'AGENT.md', 'CLAUDE.md'],
+                onePerDirectory: true,
+                nested: 'on-demand',
+                nestedTrigger: 'when Amp reads a file in',
+                importDepth: 1,
+                importGlobs: true,
+                note: 'AGENT.md and CLAUDE.md are fallbacks for directories without AGENTS.md; their order between each other, and following @-mentions one level deep, are assumptions.',
+            },
+        ],
+        limits: [],
+        notes: ['User and system AGENTS.md files (~/.config/amp, /etc/ampcode) are outside the repository and not counted.'],
+    },
+    {
+        id: 'opencode',
+        name: 'OpenCode',
+        families: [],
+        sources: ['https://opencode.ai/docs/rules/'],
+        checkedAt: '2026-10-10',
+        rules: [
+            {
+                kind: 'hierarchical',
+                names: ['AGENTS.md', 'CLAUDE.md'],
+                onePerDirectory: true,
+                nested: 'skip',
+                nestedTrigger: '',
+                note: 'CLAUDE.md is read only when there is no AGENTS.md.',
+            },
+        ],
+        limits: [],
+        notes: ['Extra files listed under instructions in opencode.json are not counted.'],
+    },
 ];
 export const TOOL_IDS = TOOLS.map((t) => t.id);
 export function getTool(id) {

package/dist/core/user.js

@@ -0,0 +1,80 @@
+/**
+ * User-level instruction files: the ones in the home directory that an agent adds to every project.
+ * Each is classified by the same rules as its project counterpart, through a virtual path
+ * (for example ~/.codex/AGENTS.md is read like a root AGENTS.md, but only by Codex).
+ */
+import { classify } from './classify.js';
+const same = (p) => p;
+export const USER_FILES = [
+    { tool: 'claude-code', pattern: /^\.claude\/CLAUDE\.md$/, as: same, source: 'https://code.claude.com/docs/en/memory' },
+    { tool: 'claude-code', pattern: /^\.claude\/rules\/.+\.md$/, as: same, source: 'https://code.claude.com/docs/en/memory' },
+    { tool: 'claude-code', pattern: /^\.claude\/skills\/[^/]+\/SKILL\.md$/, as: same, source: 'https://code.claude.com/docs/en/skills' },
+    { tool: 'claude-code', pattern: /^\.claude\/commands\/.+\.md$/, as: same, source: 'https://code.claude.com/docs/en/skills' },
+    { tool: 'claude-code', pattern: /^\.claude\/agents\/[^/]+\.md$/, as: same, source: 'https://code.claude.com/docs/en/sub-agents' },
+    { tool: 'codex', pattern: /^\.codex\/AGENTS(\.override)?\.md$/, as: (p) => p.slice('.codex/'.length), source: 'https://learn.chatgpt.com/docs/agent-configuration/agents-md' },
+    { tool: 'codex', pattern: /^\.agents\/skills\/[^/]+\/SKILL\.md$/, as: same, source: 'https://learn.chatgpt.com/docs/build-skills' },
+    { tool: 'gemini-cli', pattern: /^\.gemini\/GEMINI\.md$/, as: () => 'GEMINI.md', source: 'https://geminicli.com/docs/cli/gemini-md/' },
+    { tool: 'windsurf', pattern: /^\.codeium\/windsurf\/memories\/global_rules\.md$/, as: () => '.windsurfrules', source: 'https://docs.devin.ai/desktop/cascade/memories' },
+    { tool: 'cline', pattern: /^(Documents\/Cline\/Rules|Cline\/Rules|\.cline\/rules)\/.+\.md$/, as: (p) => '.clinerules/' + p.replace(/^(Documents\/Cline\/Rules|Cline\/Rules|\.cline\/rules)\//, ''), source: 'https://docs.cline.bot/features/cline-rules' },
+    { tool: 'roo-code', pattern: /^\.roo\/rules(-[\w-]+)?\/.+\.(md|txt)$/, as: same, source: 'https://roocodeinc.github.io/Roo-Code/features/custom-instructions' },
+    { tool: 'kiro', pattern: /^\.kiro\/steering\/[^/]+\.md$/, as: same, source: 'https://kiro.dev/docs/steering/' },
+    { tool: 'goose', pattern: /^\.config\/goose\/\.goosehints$/, as: () => '.goosehints', source: 'https://goose-docs.ai/docs/guides/context-engineering/using-goosehints' },
+    { tool: 'amp', pattern: /^\.config\/(amp\/)?AGENTS\.md$/, as: () => 'AGENTS.md', source: 'https://ampcode.com/docs/customize/agents-md' },
+    { tool: 'opencode', pattern: /^\.config\/opencode\/AGENTS\.md$/, as: () => 'AGENTS.md', source: 'https://opencode.ai/docs/rules/' },
+    // OpenCode falls back to ~/.claude/CLAUDE.md when ~/.config/opencode/AGENTS.md is missing.
+    { tool: 'opencode', pattern: /^\.claude\/CLAUDE\.md$/, as: () => 'CLAUDE.md', source: 'https://opencode.ai/docs/rules/' },
+];
+/** Home-relative folders to search, and how deep. Kept narrow so nothing else in the home directory is read. */
+export const USER_ROOTS = [
+    { dir: '.claude', depth: 4 },
+    { dir: '.codex', depth: 0 },
+    { dir: '.agents/skills', depth: 1 },
+    { dir: '.gemini', depth: 0 },
+    { dir: '.codeium/windsurf/memories', depth: 0 },
+    { dir: 'Documents/Cline/Rules', depth: 3 },
+    { dir: 'Cline/Rules', depth: 3 },
+    { dir: '.cline/rules', depth: 3 },
+    { dir: '.roo', depth: 3 },
+    { dir: '.kiro/steering', depth: 0 },
+    { dir: '.config/goose', depth: 0 },
+    { dir: '.config', depth: 0 },
+    { dir: '.config/amp', depth: 0 },
+    { dir: '.config/opencode', depth: 0 },
+];
+export function isUserInstructionFile(homePath) {
+    return USER_FILES.some((r) => r.pattern.test(homePath));
+}
+/**
+ * Classifies user-level files (paths given as `~/...`). Each tool sees only its own files,
+ * so ~/.codex/AGENTS.md never counts for Claude Code.
+ */
+export function classifyUser(files, toolIds) {
+    const units = [];
+    const tools = [...new Set(USER_FILES.map((r) => r.tool))].filter((t) => !toolIds || toolIds.includes(t));
+    for (const tool of tools) {
+        // Files that map to the same place are all read (Amp loads both ~/.config/amp/AGENTS.md and
+        // ~/.config/AGENTS.md), so each collision is classified in a batch of its own.
+        const batches = [];
+        for (const f of files) {
+            const home = f.path.replace(/^~\//, '');
+            const rule = USER_FILES.find((r) => r.tool === tool && r.pattern.test(home));
+            if (!rule)
+                continue;
+            const as = rule.as(home);
+            let batch = batches.find((b) => !b.virtual.has(as));
+            if (!batch)
+                batches.push((batch = { virtual: new Map(), files: [] }));
+            batch.virtual.set(as, f.path);
+            batch.files.push({ path: as, text: f.text });
+        }
+        for (const batch of batches) {
+            for (const u of classify(batch.files, [tool])) {
+                const real = batch.virtual.get(u.path);
+                if (!real)
+                    continue; // an @import resolved inside the virtual tree; user-level imports are not followed
+                units.push({ ...u, path: real, trigger: `user level, ${u.trigger}`, scope: 'user' });
+            }
+        }
+    }
+    return units;
+}