turntax 0.3.0 → 0.5.0

package/README.md

@@ -6,7 +6,9 @@ Coding agents re-send their instruction files with every turn. `turntax` measure
 npx turntax
 ```
 
-Try it in the browser, with nothing uploaded: https://torutdev.github.io/turntax/
+Try it in the browser, with nothing uploaded: https://torutdev.github.io/turntax/ — drop a folder or enter a public GitHub repository. Links like `https://torutdev.github.io/turntax/?repo=owner/name` open straight to that repository's report.
+
+[State of agent instruction files, October 2026](https://torutdev.github.io/turntax/state/): what turntax finds in 100 popular repositories, with pinned commits and the script to reproduce it ([`scripts/state-of.mjs`](scripts/state-of.mjs)).
 
 ## Supported agents
 
@@ -49,7 +51,7 @@ Advice (savings are estimates in o200k tokens per turn)
     3 identical lines are loaded twice every turn by cursor. Keep them in one file.
   HIGH contradiction AGENTS.md, CLAUDE.md [saves ~11 tokens/turn]
     Conflicting package manager: "Always use npm ..." (AGENTS.md:3) vs "Always use pnpm ..." (CLAUDE.md:5).
-  MEDIUM scopable-section CLAUDE.md:11 [saves ~128 tokens/turn]
+  MEDIUM scopable-section CLAUDE.md:12 [saves ~128 tokens/turn]
     Section "API package" is mostly about packages/api/. Move it to packages/api/AGENTS.md ...
 ```
 
@@ -83,6 +85,41 @@ All checks are deterministic. Each one shows an estimated saving in o200k tokens
 - **stale-reference**: referenced files or `npm run` scripts that no longer exist.
 - **non-english**: non-English sections. The token multiplier is measured only against an English version you supply (`--english CLAUDE.md=CLAUDE.en.md`) or, if you opt in, a Claude translation (`--translate`).
 
+## Fixing
+
+```bash
+npx turntax --fix            # print a diff of the safe fixes; nothing is changed
+npx turntax --fix --write    # apply them
+```
+
+`--fix` handles three kinds of advice:
+
+- **duplicate**: removes lines from a file when every agent that reads the file also reads the same lines every turn from another file. Skill, command and subagent files are left whole.
+- **scopable-section**: moves a section into the folder it is about: the same file name there (`packages/api/CLAUDE.md`), a nested `AGENTS.md`, or a Claude Code rule with `paths:`. The folder the section is about must already exist, and sections with `@imports` or relative links stay put. A section moves together with its subsections.
+- **misconfigured**: renames `.md` files in `.cursor/rules` to `.mdc`.
+
+Before a fix is kept, the files are classified again with the change applied: every agent must still read every line it read before, including files reached through `@imports`, and as often as before. The only exception is a moved section, which may load only when the agent works in that folder. Otherwise the fix is skipped and the reason is printed. A moved section can reach agents that did not read it before (a nested `AGENTS.md` is read by more agents than a `CLAUDE.md`); the summary names them. By default that check covers every supported agent, so a section of `AGENTS.md` usually stays where it is, because some agents read only the root file. `--tools codex,claude-code` limits the check to the agents you use.
+
+In preview the diff is on stdout and works with `git apply`, and the summary is on stderr; with `--write` the summary is on stdout. `--write` checks that no file changed since it was read and writes nothing if one did. Symlinked files, their targets and files in symlinked folders are never changed. Contradictions and stale references need a person to decide, so `--fix` leaves them alone.
+
+The web page shows the same fixes for any repository you load, with a downloadable `fix.patch`.
+
+## Config file
+
+Put defaults in `turntax.config.json` in the audited folder (or pass `--config <file>`). Command-line flags override it.
+
+```json
+{
+  "tools": ["claude-code", "codex", "cursor"],
+  "models": ["claude-sonnet-5.5", "gpt-6.1-sol"],
+  "maxTokens": 8000,
+  "maxIncrease": 500,
+  "ignore": ["docs/agents/archive/", "**/*.draft.md"]
+}
+```
+
+Keys: `tools`, `models`, `turns`, `maxTokens`, `maxIncrease` (applies only with `--compare` or `--baseline`), `sectionTokens`, and `ignore`: globs of instruction files to leave out, relative to the audited folder (`*` and `?` within a folder name, `**` across folders, a trailing `/` for a whole folder). Ignored files are also left out of `--compare` and are never changed by `--fix`. Unknown keys and ids are errors.
+
 ## MCP servers
 
 Every MCP server an agent starts adds its tool definitions (names, descriptions, input schemas) to the context. `turntax` reads the agents' MCP configs and lists the servers each agent starts:
@@ -135,7 +172,7 @@ The comparison covers repository instruction files (o200k), per agent and per fi
 
 ## GitHub Action
 
-The repository is also an Action. On pull requests it compares with the base branch, posts one comment (updated on every push) and writes the report to the job summary:
+The repository is also an Action. On pull requests it compares with the base branch, posts one comment (updated on every push), writes the report to the job summary and marks findings on the lines they are about in the pull request's changed files (GitHub shows up to 10 warnings and 10 notices per step):
 
 ```yaml
 name: turntax
@@ -148,14 +185,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: TorutDev/turntax@v0.3.0
+      - uses: TorutDev/turntax@v0.5.0
         with:
           max-increase: 500      # optional: fail when an agent grows by more than 500 tokens per turn
           # max-tokens: 8000     # optional: absolute budget
           # args: --tools claude-code,cursor
+          # annotations: false   # optional: no findings on the changed lines
 ```
 
-The comment opens with a table of the change per agent and per file, and folds the full report below it. Pull requests from forks get a read-only token, so the comment step is skipped there; the job summary still has the report.
+The comment opens with a table of the change per agent and per file. When `--fix` has safe fixes, it says how many and how many tokens they save, with the diff folded; the full report is folded below. A `turntax.config.json` in the repository is read as well. Pull requests from forks get a read-only token, so the comment step is skipped there; the job summary still has the report.
 
 ## Options
 
@@ -165,7 +203,8 @@ turntax [path]
   --models <ids>            see --list-models (default: claude-sonnet-5.5, gpt-6.1-sol, gemini-3.8-flash)
   --turns <n>               cost projection (default 100)
   --json | --md | --badge   output format (default: terminal table)
-  --pr-comment              Markdown for a pull request comment (change first, full report folded)
+  --pr-comment              Markdown for a pull request comment (change first, fixes and full report folded)
+  --annotations             GitHub Actions annotations, one per finding (--path-prefix <dir> for a subfolder)
   --out <file>              write the output to a file
   --max-tokens <n>          exit 1 when any tool loads more than n o200k tokens per turn (CI gate)
   --include-user            add user-level files and MCP servers from your home directory
@@ -180,18 +219,25 @@ turntax [path]
   --translate               opt-in Claude translation for that measurement (needs --claude-api)
   --prices <file.json>      your own price table
   --section-tokens <n>      threshold for oversized sections (default 600)
+  --fix                     print a diff of the safe fixes (--tools limits the agents whose context is kept)
+  --write                   with --fix, apply the changes
+  --config <file>           read defaults from this file (default: turntax.config.json, if any)
 ```
 
+When a selected model's price was checked more than 90 days ago, turntax says so on stderr; check the source or pass `--prices`.
+
 ## Privacy
 
 Offline by default: no network calls, no telemetry. File contents are sent only when you pass `--claude-api`, `--gemini-api` or `--translate`, and only to that vendor's API. Keys are read from environment variables and sent only in request headers.
 
-`--mcp` runs the commands in the MCP configs it finds and connects to the configured HTTP servers, as the agents themselves would. Run it only on repositories whose configs you trust. `turntax` prints each command before starting it. `--include-user` reads files in your home directory and never sends them anywhere.
+`--mcp` runs the commands in the MCP configs it finds and connects to the configured HTTP servers, as the agents themselves would. Run it only on repositories whose configs you trust. `turntax` prints each command before starting it. `--include-user` reads files in your home directory and never sends them anywhere. `--fix --write` is the only option that changes files, and only repository files.
 
 ## Web page
 
 [`web/`](web) is a static page that runs the same engine in the browser with the offline tokenizer only. Drop a repository folder or paste files; nothing is uploaded.
 
+It can also load a public GitHub repository: it lists the files with the GitHub API (`api.github.com`, unauthenticated, 60 requests per hour) and downloads only the instruction files, and files they `@import`, from `raw.githubusercontent.com`. Those are the only network requests the page makes, and only when you load a repository or open a `?repo=` link.
+
 ```bash
 npm run build:web
 ```

package/dist/cli.js

@@ -1,17 +1,21 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { basename, relative, resolve } from 'node:path';
+import { basename, isAbsolute, posix, relative, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 import { hasNonEnglish } from './core/advice.js';
 import { audit } from './core/audit.js';
 import { classify } from './core/classify.js';
 import { asDiffInput, diffReports, maxIncrease } from './core/diff.js';
+import { planFixes, unifiedDiff } from './core/fix.js';
+import { globMatcher } from './core/glob.js';
 import { parseMcpConfigs, serverKey, toolDefinitionsText, toolNamesText } from './core/mcp.js';
 import { DEFAULT_MODEL_IDS, MODELS, validateModels } from './core/prices.js';
-import { badgeMarkdown, headlineTokens, renderMarkdown, renderPrComment, renderText } from './core/render.js';
+import { badgeMarkdown, headlineTokens, renderAnnotations, renderMarkdown, renderPrComment, renderText } from './core/render.js';
 import { countO200k } from './core/tokenize.js';
 import { TOOL_IDS } from './core/tools.js';
-import { discover, discoverMcpConfigs, discoverUser, existsIn, packageScripts } from './node/discover.js';
+import { applyChanges } from './node/apply.js';
+import { CONFIG_FILE, loadConfig } from './node/config.js';
+import { discover, discoverMcpConfigs, discoverUser, existsIn, linkedPaths, packageScripts } from './node/discover.js';
 import { filesAtRef } from './node/git.js';
 import { measureServer } from './node/mcp.js';
 import { anthropicCounter, geminiCounter, translateToEnglish } from './node/remote.js';
@@ -31,6 +35,8 @@ Options:
   --pr-comment            Print a pull request comment: the change first, the full report folded
   --out <file>            Write the report to a file instead of stdout
   --badge                 Print a shields.io badge snippet
+  --annotations           Print GitHub Actions annotations for the advice, shown inline on pull requests
+  --path-prefix <dir>     With --annotations, the audited folder relative to the repository root
   --max-tokens <n>        Exit with code 1 if any tool loads more than n o200k tokens per turn
                           (repository files plus measured project MCP tools)
   --include-user          Also count user-level files and MCP servers in your home directory
@@ -51,9 +57,21 @@ Options:
                           (needs --claude-api; sends those files to api.anthropic.com)
   --prices <file.json>    Use your own price table (same shape as --list-models --json)
   --section-tokens <n>    Flag always-loaded sections at or above n o200k tokens (default: 600)
+  --fix                   Print a diff of the safe fixes: duplicate lines, sections that can load only in
+                          their folder, misnamed Cursor rules. Every agent keeps reading the moved text;
+                          --tools limits the agents whose context is kept
+  --write                 With --fix, apply the changes to the files
+  --config <file>         Read defaults from this file (default: ${CONFIG_FILE} in the audited folder, if any)
   -h, --help              Show help
   -v, --version           Show version
 
+Config file keys (all optional; command-line flags override them):
+  tools, models           Lists of ids, like --tools and --models
+  turns, maxTokens, maxIncrease, sectionTokens
+                          Integers, like the matching flags (maxIncrease applies only when comparing)
+  ignore                  Globs of instruction files to leave out, relative to the audited folder (* and ? within a
+                          folder name, ** across folders, a trailing / for a whole folder)
+
 Without --claude-api, --gemini-api or --mcp nothing leaves your machine.
 `;
 class UsageError extends Error {
@@ -72,7 +90,7 @@ function positiveInt(name, value, fallback) {
         throw new UsageError(`--${name} must be a positive integer`);
     return n;
 }
-export async function main(argv, env = process.env) {
+export async function main(argv, env = process.env, now = new Date()) {
     let parsed;
     try {
         parsed = parseArgs({
@@ -88,6 +106,9 @@ export async function main(argv, env = process.env) {
                 'pr-comment': { type: 'boolean' },
                 out: { type: 'string' },
                 badge: { type: 'boolean' },
+                annotations: { type: 'boolean' },
+                'path-prefix': { type: 'string' },
+                config: { type: 'string' },
                 'max-tokens': { type: 'string' },
                 'claude-api': { type: 'boolean' },
                 'gemini-api': { type: 'boolean' },
@@ -101,6 +122,8 @@ export async function main(argv, env = process.env) {
                 baseline: { type: 'string' },
                 compare: { type: 'string' },
                 'max-increase': { type: 'string' },
+                fix: { type: 'boolean' },
+                write: { type: 'boolean' },
                 help: { type: 'boolean', short: 'h' },
                 version: { type: 'boolean', short: 'v' },
             },
@@ -132,24 +155,56 @@ export async function main(argv, env = process.env) {
             process.stdout.write(o.json ? JSON.stringify(catalog, null, 2) + '\n' : catalog.map(describeModel).join('\n') + '\n');
             return 0;
         }
-        const modelIds = list(o.models) ?? DEFAULT_MODEL_IDS.filter((id) => catalog.some((m) => m.id === id));
+        const root = resolve(positionals[0] ?? '.');
+        let config;
+        try {
+            config = loadConfig(root, o.config, catalog);
+        }
+        catch (e) {
+            throw new UsageError(e.message);
+        }
+        const modelIds = list(o.models) ?? config.models ?? DEFAULT_MODEL_IDS.filter((id) => catalog.some((m) => m.id === id));
         const models = modelIds.map((id) => {
             const m = catalog.find((x) => x.id === id);
             if (!m)
                 throw new UsageError(`Unknown model "${id}". Run --list-models.`);
             return m;
         });
-        const tools = list(o.tools);
+        const tools = list(o.tools) ?? config.tools;
         for (const t of tools ?? [])
             if (!TOOL_IDS.includes(t))
                 throw new UsageError(`Unknown tool "${t}". Use: ${TOOL_IDS.join(', ')}`);
-        const root = resolve(positionals[0] ?? '.');
-        const files = await discover(root);
+        const ignored = globMatcher(config.ignore ?? []);
+        const repoFiles = (files) => files.filter((f) => !ignored(f.path));
+        if (o.write && !o.fix)
+            throw new UsageError('--write needs --fix.');
+        if (o['path-prefix'] !== undefined && !o.annotations)
+            throw new UsageError('--path-prefix needs --annotations.');
+        if (o.annotations) {
+            const other = ['json', 'md', 'pr-comment', 'badge', 'fix'].filter((k) => o[k] !== undefined);
+            if (other.length)
+                throw new UsageError(`--annotations cannot be combined with --${other.join(', --')}.`);
+        }
+        if (o.fix) {
+            const other = ['json', 'md', 'pr-comment', 'badge', 'baseline', 'compare', 'max-tokens', 'max-increase', 'include-user', 'mcp'].filter((k) => o[k] !== undefined);
+            if (o.write && o.out)
+                other.push('out');
+            if (other.length)
+                throw new UsageError(`--fix${o.write ? ' --write' : ''} cannot be combined with --${other.join(', --')}.`);
+            return await fix(root, tools, ignored, Boolean(o.write), o.out);
+        }
+        const discovered = await discover(root);
+        const files = repoFiles(discovered);
+        // Budgets in the config are for report runs; an --annotations run only prints findings.
+        const gates = o.annotations ? {} : config;
+        const label = (flag, key) => o[flag] !== undefined ? `--${flag}` : `${key} in ${o.config ?? CONFIG_FILE}`;
         if (o.baseline && o.compare)
             throw new UsageError('Use --baseline or --compare, not both.');
+        // The config's maxIncrease applies only when a comparison runs, so plain local runs keep working.
         if (o['max-increase'] !== undefined && !o.baseline && !o.compare)
             throw new UsageError('--max-increase needs --baseline or --compare.');
-        const maxIncreaseLimit = o['max-increase'] === undefined ? undefined : nonNegativeInt('max-increase', o['max-increase']);
+        const maxIncreaseLimit = o['max-increase'] === undefined ? gates.maxIncrease : nonNegativeInt('max-increase', o['max-increase']);
+        stalePrices(models, now);
         let userFiles = [];
         let mcpFiles = discoverMcpConfigs(root);
         if (o['include-user']) {
@@ -211,14 +266,14 @@ export async function main(argv, env = process.env) {
             tools,
             models,
             counters,
-            turns: positiveInt('turns', o.turns, 100),
+            turns: positiveInt('turns', o.turns, config.turns ?? 100),
             userFiles,
             mcp: { servers, measured },
             advice: {
                 exists: existsIn(root),
                 packageScripts: packageScripts(root),
                 english,
-                sectionTokens: positiveInt('section-tokens', o['section-tokens'], 600),
+                sectionTokens: positiveInt('section-tokens', o['section-tokens'], config.sectionTokens ?? 600),
             },
         });
         if (o.baseline) {
@@ -235,7 +290,7 @@ export async function main(argv, env = process.env) {
             const base = await filesAtRef(root, o.compare).catch((e) => {
                 throw new UsageError(e.message);
             });
-            const before = await audit(base.files, {
+            const before = await audit(repoFiles(base.files), {
                 tools,
                 models: [],
                 mcp: { servers: parseMcpConfigs(base.mcpConfigs, root).servers },
@@ -245,24 +300,26 @@ export async function main(argv, env = process.env) {
         const output = o.json
             ? JSON.stringify({ root, ...report }, null, 2) + '\n'
             : o['pr-comment']
-                ? renderPrComment(report)
-                : o.md
-                    ? renderMarkdown(report)
-                    : o.badge
-                        ? badgeMarkdown(report) + '\n'
-                        : renderText(report, root) + '\n';
+                ? renderPrComment(report, files.length ? fixPlan(root, discovered, tools, ignored) : undefined, fixCommand(positionals[0], o.config, o.tools))
+                : o.annotations
+                    ? renderAnnotations(report, pathPrefix(o['path-prefix']))
+                    : o.md
+                        ? renderMarkdown(report)
+                        : o.badge
+                            ? badgeMarkdown(report) + '\n'
+                            : renderText(report, root) + '\n';
         if (o.out)
             writeFileSync(o.out, output);
         else
             process.stdout.write(output);
         let code = 0;
-        const max = o['max-tokens'] === undefined ? undefined : positiveInt('max-tokens', o['max-tokens'], 0);
+        const max = o['max-tokens'] === undefined ? gates.maxTokens : positiveInt('max-tokens', o['max-tokens'], 0);
         if (max !== undefined && headlineTokens(report) > max) {
-            process.stderr.write(`turntax: ${headlineTokens(report)} o200k tokens per turn exceeds --max-tokens ${max}\n`);
+            process.stderr.write(`turntax: ${headlineTokens(report)} o200k tokens per turn exceeds ${label('max-tokens', 'maxTokens')} ${max}\n`);
             code = 1;
         }
         if (maxIncreaseLimit !== undefined && report.diff && maxIncrease(report.diff) > maxIncreaseLimit) {
-            process.stderr.write(`turntax: per-turn tokens grew by ${maxIncrease(report.diff)} vs ${report.diff.base}, more than --max-increase ${maxIncreaseLimit}\n`);
+            process.stderr.write(`turntax: per-turn tokens grew by ${maxIncrease(report.diff)} vs ${report.diff.base}, more than ${label('max-increase', 'maxIncrease')} ${maxIncreaseLimit}\n`);
             code = 1;
         }
         return code;
@@ -276,6 +333,75 @@ export async function main(argv, env = process.env) {
         return 1;
     }
 }
+async function fix(root, tools, ignored, write, out) {
+    const discovered = await discover(root);
+    const plan = fixPlan(root, discovered, tools, ignored);
+    const log = (line) => (write ? process.stdout : process.stderr).write(line + '\n');
+    for (const f of plan.fixes)
+        log(`fix: ${f.message}${f.savingTokens ? ` [saves ~${f.savingTokens} tokens/turn]` : ''}`);
+    for (const s of plan.skipped)
+        log(`skipped ${s.kind}: ${s.reason}`);
+    if (!plan.changes.length) {
+        // An empty patch, so an earlier patch in the same file is not applied again.
+        if (out && !write)
+            writeFileSync(out, '');
+        log('Nothing to fix automatically.');
+        return 0;
+    }
+    if (write) {
+        applyChanges(root, plan.changes);
+        log(`Changed ${plan.changes.length} file(s): ${plan.changes.map((c) => c.path).join(', ')}`);
+        return 0;
+    }
+    const diff = unifiedDiff(plan.changes);
+    if (out)
+        writeFileSync(out, diff);
+    else
+        process.stdout.write(diff);
+    log('Preview only. Run again with --write to apply, or save the diff and use git apply.');
+    return 0;
+}
+/**
+ * Safe fixes. The plan sees every repository file, ignored ones included, because the agents still read
+ * them and the safety check must see what they read; symlinks, their targets and ignored files are never
+ * written.
+ */
+function fixPlan(root, discovered, tools, ignored) {
+    const linked = linkedPaths(root, discovered);
+    return planFixes(discovered, {
+        tools,
+        exists: existsIn(root),
+        readOnly: (p) => (ignored(p) ? `${p} is in the config's ignore list; it is left alone.` : linked(p)),
+    });
+}
+/** The --fix command matching the run that made a pull request comment. */
+function fixCommand(path, config, tools) {
+    const arg = (s) => (/^[\w./@:,=-]+$/.test(s) ? s : `"${s}"`);
+    const parts = ['npx turntax'];
+    if (path && path !== '.' && !isAbsolute(path))
+        parts.push(arg(path));
+    if (config)
+        parts.push('--config', arg(config));
+    if (tools)
+        parts.push('--tools', arg(tools));
+    return [...parts, '--fix'].join(' ');
+}
+/** `--path-prefix` as a POSIX folder ending in a slash, or '' for the repository root. */
+function pathPrefix(dir) {
+    if (!dir)
+        return '';
+    const p = posix.normalize(dir.replace(/\\/g, '/') + '/');
+    return p === './' ? '' : p;
+}
+/** One notice when a selected model's price was checked more than 90 days before `now`. */
+function stalePrices(models, now) {
+    const today = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+    const stale = models.filter((m) => today - Date.parse(m.checkedAt) > 90 * 86_400_000);
+    if (!stale.length)
+        return;
+    const dates = [...new Set(stale.map((m) => m.checkedAt))].sort();
+    notice(`prices for ${stale.map((m) => m.label).join(', ')} were checked on ${dates.join(', ')}, over 90 days ago; check the sources or pass --prices.`);
+}
 function nonNegativeInt(name, value) {
     const n = Number(value);
     if (!Number.isInteger(n) || n < 0)

package/dist/core/advice.js

@@ -5,18 +5,57 @@ const DEFAULT_SECTION_TOKENS = 600;
 export function buildAdvice(units, files, opts = {}) {
     // User-level files take part in checks across files; moving sections or checking paths only makes sense in the repository.
     const repo = units.filter((u) => !u.scope);
+    const raw = rawLines(files);
     const advice = [
         ...misconfigured(units),
         ...sizeLimits(units, files),
         ...duplicates(units),
-        ...contradictions(units),
-        ...sections(repo, opts.sectionTokens ?? DEFAULT_SECTION_TOKENS),
-        ...nonEnglish(units, opts.english),
-        ...staleReferences(repo, opts),
+        ...contradictions(units, raw),
+        ...sections(repo, opts.sectionTokens ?? DEFAULT_SECTION_TOKENS, raw, opts.exists),
+        ...nonEnglish(units, raw, opts.english),
+        ...staleReferences(repo, opts, raw),
     ];
     const order = { high: 0, medium: 1, low: 2 };
     return advice.sort((a, b) => order[a.severity] - order[b.severity] || (b.savingTokens ?? 0) - (a.savingTokens ?? 0));
 }
+function rawLines(files) {
+    const byPath = new Map(files.map((f) => [f.path, f.text]));
+    const cache = new Map();
+    return (u, line) => {
+        const key = `${u.path}\0${u.text}`;
+        let map = cache.get(key);
+        if (!map)
+            cache.set(key, (map = alignLines(u.text, byPath.get(u.path))));
+        return map[line - 1];
+    };
+}
+/**
+ * For each line of `text` (what an agent loads: frontmatter, HTML comments or a truncated tail removed),
+ * the 1-based line of `raw` it comes from. Lines are only ever removed, so line i is at raw line i or later.
+ */
+function alignLines(text, raw) {
+    if (raw === undefined)
+        return [];
+    const lines = text.split(/\r?\n/);
+    const rawLines = raw.split(/\r?\n/);
+    // Frontmatter removed: the text is the end of the file.
+    const offset = rawLines.length - lines.length;
+    if (offset >= 0 && rawLines.slice(offset).join('\n') === lines.join('\n'))
+        return lines.map((_, i) => offset + i + 1);
+    const out = [];
+    let next = 0;
+    lines.forEach((line, i) => {
+        const want = line.trim();
+        for (let j = Math.max(next, i); j < rawLines.length; j++) {
+            if (rawLines[j].trim() !== want)
+                continue;
+            out[i] = j + 1;
+            next = j + 1;
+            return;
+        }
+    });
+    return out;
+}
 /** Units that carry real instruction text (not skill descriptions), grouped by path. */
 function contentUnits(units, modes = ['always', 'on-demand']) {
     return units.filter((u) => u.part !== 'description' && modes.includes(u.mode));
@@ -146,6 +185,7 @@ function duplicates(units) {
     }
     return out;
 }
+const at = (d) => (d.line ? `${d.path}:${d.line}` : d.path);
 const DIRECTIVES = [
     {
         topic: 'package manager',
@@ -203,7 +243,7 @@ function conflicts(a, b) {
         return a === `not ${b}` || b === `not ${a}`;
     return true;
 }
-function contradictions(units) {
+function contradictions(units, raw) {
     const found = new Map();
     const tools = [...new Set(units.map((u) => u.tool))];
     for (const tool of tools) {
@@ -213,7 +253,7 @@ function contradictions(units) {
                 if (inFence)
                     return;
                 for (const d of directivesIn(line))
-                    directives.push({ ...d, path: u.path, line: i + 1, text: line.trim() });
+                    directives.push({ ...d, path: u.path, line: raw(u, i + 1), text: line.trim() });
             });
         }
         for (let i = 0; i < directives.length; i++) {
@@ -222,7 +262,7 @@ function contradictions(units) {
                 const b = directives[j];
                 if (a.topic !== b.topic || !conflicts(a.value, b.value))
                     continue;
-                const key = [a.topic, `${a.path}:${a.line}`, `${b.path}:${b.line}`].join('|');
+                const key = [a.topic, at(a), at(b), a.text, b.text].join('|');
                 const prev = found.get(key);
                 if (prev) {
                     prev.tools.push(tool);
@@ -234,7 +274,7 @@ function contradictions(units) {
                     severity: 'high',
                     tools: [tool],
                     paths: [...new Set([a.path, b.path])],
-                    message: `Conflicting ${a.topic}: "${a.text}" (${a.path}:${a.line}) vs "${b.text}" (${b.path}:${b.line}).`,
+                    message: `Conflicting ${a.topic}: "${a.text}" (${at(a)}) vs "${b.text}" (${at(b)}).`,
                     savingTokens: countO200k(shorter),
                     savingNote: 'Removing the outdated line.',
                 });
@@ -259,23 +299,21 @@ export function pathRefs(text) {
         .map((r) => r.replace(/^\.\//, '').replace(/[),.;:]+$/, ''))
         .filter((r) => r.includes('/') && !/^(https?:|~|\/|[A-Za-z]:|@|<)/.test(r) && !/[*?{}<>$]/.test(r));
 }
-function sections(units, threshold) {
+function sections(units, threshold, raw, exists) {
     const out = [];
     for (const u of uniqueByPath(contentUnits(units, ['always']))) {
         const tools = toolsWith(units, u.path, 'always');
         for (const s of splitSections(u.text)) {
             const tokens = countO200k(s.text);
-            const refs = pathRefs(s.text).filter((r) => !r.startsWith('.'));
-            const dirs = refs.map((r) => r.split('/')[0]);
-            const top = mostCommon(dirs);
-            if (tokens >= 100 && top && top.count >= 2 && top.count / dirs.length >= 0.6) {
-                const scope = commonDir(refs.filter((r) => r.startsWith(top.value + '/')));
+            // A folder that does not exist (a URL path, a placeholder) is not a place the section can move to.
+            const scope = sectionScope(s.text);
+            if (scope && (!exists || exists(scope))) {
                 out.push({
                     kind: 'scopable-section',
                     severity: 'medium',
                     tools,
                     paths: [u.path],
-                    line: s.line,
+                    line: raw(u, s.line),
                     message: `Section "${s.heading}" is mostly about ${scope}/. Move it to ${scope}/AGENTS.md (or CLAUDE.md), a path-scoped rule, or an instructions file with applyTo so it loads only when the agent works there.`,
                     savingTokens: tokens,
                     savingNote: 'Saved on turns that do not touch that directory.',
@@ -287,7 +325,7 @@ function sections(units, threshold) {
                     severity: 'medium',
                     tools,
                     paths: [u.path],
-                    line: s.line,
+                    line: raw(u, s.line),
                     message: `Section "${s.heading}" is ${tokens} tokens and loads every turn. If it is a procedure (release, deploy, migration), move it into an on-demand skill or rule and keep a one-line pointer.`,
                     savingTokens: Math.max(0, tokens - 30),
                     savingNote: 'Assumes about 30 tokens remain for the skill description or pointer.',
@@ -297,6 +335,17 @@ function sections(units, threshold) {
     }
     return out;
 }
+/** The directory a section is mostly about (for example `packages/api`), or null when it is not scopable. */
+export function sectionScope(text) {
+    if (countO200k(text) < 100)
+        return null;
+    const refs = pathRefs(text).filter((r) => !r.startsWith('.'));
+    const dirs = refs.map((r) => r.split('/')[0]);
+    const top = mostCommon(dirs);
+    if (!top || top.count < 2 || top.count / dirs.length < 0.6)
+        return null;
+    return commonDir(refs.filter((r) => r.startsWith(top.value + '/')));
+}
 /** Longest directory prefix shared by all refs, e.g. `packages/api` for `packages/api/db.ts` and `packages/api/handlers/`. */
 function commonDir(refs) {
     const dirs = refs.map((r) => (r.endsWith('/') ? r.slice(0, -1) : r.slice(0, r.lastIndexOf('/'))).split('/'));
@@ -349,14 +398,16 @@ export function guessLanguage(text) {
     if (words.length < 15)
         return { nonEnglish: false, script: 'Latin' };
     const stop = words.filter((w) => EN_STOPWORDS.has(w)).length / words.length;
-    const diacritics = letters.filter((c) => /[^\u0000-\u007F]/.test(c)).length / letters.length;
-    return { nonEnglish: stop < 0.12 || (diacritics > 0.03 && stop < 0.2), script: 'Latin' };
+    // Terse English (bullet lists, commands) has few stopwords too, so Latin text also needs words with
+    // accented letters: a few percent of words in German, French, Spanish or Turkish, none in plain English.
+    const accented = words.filter((w) => /[^\u0000-\u007F]/.test(w)).length / words.length;
+    return { nonEnglish: stop < 0.2 && accented >= 0.04, script: 'Latin' };
 }
 /** True when any heading section of the text looks non-English. */
 export function hasNonEnglish(text) {
     return splitSections(text).some((s) => guessLanguage(s.text).nonEnglish);
 }
-function nonEnglish(units, english) {
+function nonEnglish(units, raw, english) {
     const out = [];
     for (const u of uniqueByPath(contentUnits(units, ['always']))) {
         const parts = splitSections(u.text).filter((s) => guessLanguage(s.text).nonEnglish);
@@ -386,7 +437,7 @@ function nonEnglish(units, english) {
                 severity: 'low',
                 tools,
                 paths: [u.path],
-                line: parts[0].line,
+                line: raw(u, parts[0].line),
                 message: `${parts.length} section(s) (${tokens} tokens) in ${script} script look non-English. Pass --english ${u.path}=<english file> or --translate to measure the multiplier.`,
                 savingTokens: null,
                 savingNote: 'Not measured without an English version.',
@@ -400,7 +451,7 @@ function isNested(path) {
     const dir = dirname(path);
     return dir !== '' && !/^\.(claude|github|cursor|windsurf|devin|agents|clinerules|cline|roo|kiro|junie|continue)(\/|$)/.test(dir);
 }
-function staleReferences(units, opts) {
+function staleReferences(units, opts, raw) {
     const out = [];
     for (const u of uniqueByPath(contentUnits(units))) {
         const tools = [...new Set(units.filter((x) => x.path === u.path && x.mode !== 'ignored').map((x) => x.tool))];
@@ -416,18 +467,21 @@ function staleReferences(units, opts) {
                     const first = ref.split('/')[0];
                     if (/^(path|example|foo|your|my)/i.test(first))
                         continue;
+                    // Paths with .. can point outside the repository, where nothing can be checked.
+                    if (ref.split('/').includes('..'))
+                        continue;
                     // Only flag when the top-level folder exists but the file does not: likely moved or deleted.
                     // Paths may be written relative to the repository root or to the instruction file.
                     const local = resolvePath(u.path, ref);
                     if (opts.exists(first) && !opts.exists(ref) && !(local && opts.exists(local)))
-                        missing.push({ ref, line, n: i + 1 });
+                        missing.push({ ref, line, n: raw(u, i + 1) });
                 }
             }
             // Root package.json scripts only apply to root-level instruction files, not nested packages.
             if (opts.packageScripts && !isNested(u.path)) {
                 for (const m of line.matchAll(/\b(?:npm|pnpm|yarn|bun) run (?!-)([\w:.-]+)/g)) {
                     if (!opts.packageScripts.has(m[1]))
-                        missing.push({ ref: `script "${m[1]}"`, line, n: i + 1 });
+                        missing.push({ ref: `script "${m[1]}"`, line, n: raw(u, i + 1) });
                 }
             }
         });
@@ -439,8 +493,8 @@ function staleReferences(units, opts) {
             severity: 'medium',
             tools,
             paths: [u.path],
-            line: missing[0].n,
-            message: `References that no longer exist: ${[...new Set(missing.map((m) => `${m.ref} (line ${m.n})`))].join(', ')}.`,
+            line: missing.find((m) => m.n)?.n,
+            message: `References that no longer exist: ${[...new Set(missing.map((m) => (m.n ? `${m.ref} (line ${m.n})` : m.ref)))].join(', ')}.`,
             savingTokens: countO200k(uniqueLines.join('\n')),
             savingNote: 'If those lines are obsolete; update them instead if they are still relevant.',
         });