@aragon-agent/cli 0.6.28 → 0.6.31

package/dist/ui/use-startup-notices.js

@@ -14,7 +14,7 @@
 import { useEffect, useRef } from 'react';
 import { MODE_TOGGLE_KEYS } from '../agent/agent-mode.js';
 import { readConfigFile } from '../config/store.js';
-import { getMouseNoticeVersion, getVtInputNoticeVersion } from '../config/ui-state.js';
+import { getMouseNoticeVersion, getScrollModeNoticeVersion, getVtInputNoticeVersion, } from '../config/ui-state.js';
 import { getLogger } from '../logging/logger.js';
 /**
  * The revision of the mouse notice a user must have seen for it to stay quiet
@@ -93,7 +93,17 @@ export function vtInputDeadNotice(nodeVersion) {
         `as a PLAIN TAB - ${cost}${toggle}, and Shift+Up / Shift+Down to scroll. ` +
         'Node 22.17.0+ (or 24.2.0+) restores both.');
 }
-export function useStartupNotices(dispatch, mouseNotice, retainNotice, vtInputNotice) {
+/**
+ * The revision of the native-scroll notice a user must have seen for it to stay
+ * quiet (`state.json::scrollModeNoticeVersion`). BUMP IT WHENEVER THE ADVICE
+ * CHANGES, never for a rewording (tui-native-terminal-scroll D12).
+ */
+export const SCROLL_MODE_NOTICE_VERSION = 1;
+export function scrollModeNoticeText() {
+    return ('Scrolling now uses your terminal: wheel, scrollbar, selection and search all work as ' +
+        'usual. Prefer the old full-screen view? Run: aragon config set scrollMode app');
+}
+export function useStartupNotices(dispatch, mouseNotice, retainNotice, vtInputNotice, scrollModeNotice) {
     // The sink gives up after repeated write failures (a read-only log directory,
     // a full disk). Silently logging nothing is exactly the state a user must not
     // discover later, from an empty file, while trying to explain a bug.
@@ -167,6 +177,22 @@ export function useStartupNotices(dispatch, mouseNotice, retainNotice, vtInputNo
         });
         vtNoticeRef.current?.onSeen();
     }, [vtNodeVersion, dispatch]);
+    // The one-shot native-scroll notice (D12): a default-behaviour change has to be
+    // discoverable and reversible. `>=`, like the notices above: a state file written
+    // by a newer build has already told this user.
+    const scrollNoticeRef = useRef(scrollModeNotice);
+    scrollNoticeRef.current = scrollModeNotice;
+    const scrollNoticeWanted = scrollModeNotice !== undefined;
+    const scrollNoticeShown = useRef(false);
+    useEffect(() => {
+        if (!scrollNoticeWanted || scrollNoticeShown.current)
+            return;
+        if (getScrollModeNoticeVersion() >= SCROLL_MODE_NOTICE_VERSION)
+            return;
+        scrollNoticeShown.current = true;
+        dispatch({ type: 'notice', level: 'info', text: scrollModeNoticeText() });
+        scrollNoticeRef.current?.onSeen();
+    }, [scrollNoticeWanted, dispatch]);
     // A `warn` notice rather than a toast: it is about a value the user typed, so
     // it belongs in the transcript where it can be scrolled back to, not in a row
     // that expires. DEPENDS ON THE TWO SCALARS, never on the options object —

package/dist/ui/use-wheel-routing.d.ts

@@ -22,13 +22,6 @@
 import type { Overlay } from '../agent/reducer.js';
 import type { MouseSource } from '../input/stdin-filter.js';
 import type { ScrollIntent } from './layout/scroll.js';
-/**
- * Rows a PgUp/PgDn — and a Shift+wheel notch — moves inside a controlled
- * overlay. Declared here rather than in `App.tsx` because both the keyboard
- * branch and the wheel branch need it and `App` imports this module; the other
- * direction would be a cycle.
- */
-export declare const OVERLAY_PAGE = 8;
 export interface WheelRoutingOptions {
     isPointerCaptured?: () => boolean;
     isActive?: () => boolean;
@@ -39,6 +32,16 @@ export interface WheelRoutingOptions {
     onScroll: (kind: ScrollIntent, repeat: number) => void;
     /** Signed row delta; the caller clamps at 0 the way the keyboard branch does. */
     onOverlayScroll: (delta: number) => void;
+    /**
+     * Rows one Shift+wheel notch turns inside a controlled overlay (defect 11).
+     *
+     * A GETTER, read at event time for the same reason `getOverlay` is: the window
+     * height changes with the terminal, with `statusExpanded` and with the rail, and
+     * a value captured when the subscription was built is the value that goes stale.
+     * `App` answers with `overlayPageSize(...)`, the same function its keyboard
+     * branch uses, so the wheel and `PgDn` can never disagree.
+     */
+    getOverlayPage?: () => number;
 }
 export interface WheelRouting {
     /**

package/dist/ui/use-wheel-routing.js

@@ -21,12 +21,15 @@
  */
 import { useCallback, useEffect, useRef } from 'react';
 /**
- * Rows a PgUp/PgDn — and a Shift+wheel notch — moves inside a controlled
- * overlay. Declared here rather than in `App.tsx` because both the keyboard
- * branch and the wheel branch need it and `App` imports this module; the other
- * direction would be a cycle.
+ * Page rows used ONLY when the host supplies no `getOverlayPage`.
+ *
+ * `App` always supplies one (defect 11): the step is the overlay's visible window
+ * minus two rows of context, so `PgDn` in `/help` turns a page instead of 42% of
+ * one. This fallback exists so a host that owns no overlay window - this module's
+ * own routing tests are the only such host - still gets a page rather than
+ * silently degrading a Shift+wheel to a three-row notch.
  */
-export const OVERLAY_PAGE = 8;
+const FALLBACK_OVERLAY_PAGE = 8;
 /** Transcript rows per notch. The terminal's own convention. */
 const CONTENT_LINES_PER_NOTCH = 3;
 /** Overlay rows per notch. Overlay content is short; a page needs Shift. */
@@ -113,7 +116,9 @@ export function useWheelRouting(options) {
             // D-3: the row is not consulted here either. Behind an overlay the
             // composer is inactive and the overlay is the only scrollable thing on
             // screen, so a notch anywhere scrolls it.
-            const step = event.shift ? OVERLAY_PAGE : OVERLAY_LINES_PER_NOTCH;
+            const step = event.shift
+                ? current.getOverlayPage?.() ?? FALLBACK_OVERLAY_PAGE
+                : OVERLAY_LINES_PER_NOTCH;
             current.onOverlayScroll(event.dir === 'up' ? -step : step);
             return;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aragon-agent/cli",
-  "version": "0.6.28",
+  "version": "0.6.31",
   "description": "AragonAgent CLI — a Claude-Code / Codex-style interactive terminal UI (TUI) on top of the @aragon-agent/core engine. Installable and runnable via npm / npx.",
   "license": "MIT",
   "author": "AragonAgent contributors",
@@ -56,7 +56,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@aragon-agent/core": "^0.2.40",
+    "@aragon-agent/core": "^0.2.43",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.0.0",
     "commander": "^12.1.0",

package/skills/project-indexer/SKILL.md

@@ -1,163 +1,163 @@
----
-name: project-indexer
-description: Generate and use a project index for quick codebase understanding in new sessions. Scans the workspace, extracts exported symbols, writes .claude-index/index.md plus config, and injects a Google-style Clean Code Guidelines section into CLAUDE.md. Use when the user says "explore the project", "generate index", "regenerate index", "更新索引", "生成索引", or presses Ctrl+I.
-version: 1.1.0
-license: MIT
-keywords: [productivity, codebase, indexing, navigation, cleancode]
-# The read-only tools (read_file, list_dir, glob, grep, ask_user, todo_write)
-# are always available inside a skill frame via the tool floor; this ceiling
-# adds exactly the two writers the generated files need.
-allowed-tools:
-  - write_file
-  - edit_file
----
-
-# Project Indexer
-
-Generate a structured index of any codebase so a new session understands the
-project with minimal context usage. The index is a **navigation map**, not a
-code copy: enough to see the project globally (type, stack, architecture),
-navigate on demand (feature map, file index), and know which symbols exist
-without reading every file.
-
-## Current request
-
-$ARGUMENTS
-
-## Step 1: Check for an existing index
-
-- If `.claude-index/index.md` exists and has the key sections (Project
-  Overview, Feature Map, File Index), go to "Using an existing index".
-- If it exists but is empty or malformed, tell the user and regenerate
-  (first-time flow), preserving `config.md` if intact.
-- Otherwise run the first-time flow.
-
-## Using an existing index
-
-1. Read `.claude-index/index.md` and `CLAUDE.md` (if present).
-2. Summarize in 3-5 bullets: structure, stack, feature areas, key entry
-   points. Offer to help.
-3. For later questions, navigate via the Feature Map / File Index and read
-   real source only when detail is needed.
-
-## First-time flow
-
-### Step 2: Gather configuration (ask_user)
-
-Ask with `ask_user`, defaults offered in every question:
-
-1. **Exclusions** - A) defaults (node_modules, .git, dist, build,
-   __pycache__, .venv, vendor, coverage, .next, .nuxt, .cache, target, bin,
-   obj, .idea, .vscode) B) add more C) custom list.
-2. **Priority directories** - A) auto-detect (recommended) B) specify C) all
-   equally.
-3. **Tech stack** - auto-detect unless the user names one.
-4. **Clean Code Guidelines** (injected into CLAUDE.md) - A) Google strict
-   (method 60, file 1000 - recommended) B) Google relaxed (method 600)
-   C) custom D) skip.
-
-If C: ask **one `ask_user` call per limit** showing default and range -
-MAX_FILE_LINES 1000 (200-5000), MAX_METHOD_LINES 60 (20-600),
-MAX_FUNCTION_PARAMS 5 (2-10), MAX_CYCLOMATIC 10 (5-25); fall back to the
-default on an out-of-range answer and say so in the summary.
-MAX_LINE_LENGTH (default 100, Python 80) and MAX_NESTING_DEPTH (4) are never
-asked. If the user skips every question, use all defaults.
-
-Treat the answer as `CleanCodeConfig.preset`: strict | relaxed | custom |
-disabled. D (`disabled`) skips the Clean Code composition below, never adds
-markers, and persists `Enabled: No`.
-
-### Step 3: Scan and analyze
-
-1. Traverse the tree with the exclusion rules (`glob`, never one giant read).
-2. Detect project type (frontend/backend/fullstack/library/CLI/monorepo),
-   languages with percentages, frameworks, entry points.
-3. Group files by feature/domain and extract exported symbols - full support
-   for JS/TS (.js/.jsx/.ts/.tsx/.mjs) and Python; best-effort for Java,
-   Kotlin, Go, Rust, C/C++, C#, Ruby, PHP; unknown types are listed without
-   symbols.
-4. Analyze module-level dependencies (import graph).
-
-Adaptive sizing: <50 files -> full detail; 50-200 -> full coverage with
-concise descriptions; 200+ -> detail the priority directories, summarize the
-rest, group similar utilities. Over 1000 files after exclusions: warn and
-suggest more exclusions before continuing; sample representative files with
-glob/grep rather than reading everything. Keep language/framework findings in
-working memory - do NOT write an intermediate JSON file.
-
-### Step 4: Write `.claude-index/`
-
-1. `config.md` - exclusions, priorities, tech stack, plus an Index Settings
-   block (Generated date, Project Root, Index Version) and a Clean Code
-   Settings block (Enabled / Preset / the six limits; when the user picked
-   skip, write `Enabled: No`, `Preset: disabled` and the strict numbers so a
-   later "enable cleancode" can flip it back).
-2. `index.md` - follow `templates/index-template.md` in this skill's
-   directory: Project Overview, Feature Map (per area: entry file, one-line
-   description, key exports with signatures), Module Dependencies, File Index
-   (per-directory tables, one line per file).
-
-### Step 5: Compose the Clean Code Guidelines (skip when disabled)
-
-Read `templates/cleancode-template.md` and `templates/cleancode-overrides.md`
-from this skill's directory, then:
-
-1. Primary languages = every language with >= 10% of post-exclusion source
-   files; if none clears 10%, use the `Other` row.
-2. Take the **minimum** across all matching rows for each numeric column.
-3. Apply the user preset: strict/relaxed values intersect with the language
-   minimum (never looser than the baseline); custom numbers are honoured
-   verbatim with divergence noted.
-4. Substitute every placeholder: `{{MAX_FILE_LINES}}`, `{{MAX_METHOD_LINES}}`,
-   `{{MAX_FUNCTION_PARAMS}}`, `{{MAX_CYCLOMATIC}}`, `{{MAX_LINE_LENGTH}}`,
-   `{{MAX_NESTING_DEPTH}}`, `{{PRIMARY_LANGUAGES}}` (comma-joined languages)
-   and `{{LANGUAGE_HINTS}}` (one `- Language: note` bullet per matching row,
-   deduped by exact string).
-5. Verify no `{{...}}` placeholder remains. Do not count characters at
-   runtime.
-
-### Step 6: Update CLAUDE.md
-
-- `## Project Index` section: upsert (replace when present, else append at
-  end; create the file when missing). Contents: Location
-  `.claude-index/index.md`, Last Updated (YYYY-MM-DD), Contents line, a
-  Usage line, and "Regenerate: say 'regenerate index' / '更新索引'".
-- `## Clean Code Guidelines` section (unless disabled): wrap the rendered
-  body in `<!-- project-indexer:cleancode:begin v1.1.0 -->` and
-  `<!-- project-indexer:cleancode:end -->`. Locate an existing block with
-  the version-agnostic regex `<!-- project-indexer:cleancode:begin
-  v\d+\.\d+\.\d+ -->` (NEVER a literal-version match) plus the literal end
-  marker; fallback: the region from a `## Clean Code Guidelines` heading to
-  the next `## ` heading or EOF. Replace the found block; if none, insert
-  after the Project Index section (first-insert only; when both sections
-  already exist preserve the user's ordering and everything between them).
-  Write UTF-8; add a trailing newline when missing.
-
-### Step 7: Report
-
-List what was created/updated, the feature-area count, files indexed and
-symbols extracted. Offer to start work.
-
-## Regeneration ("regenerate index" / "更新索引")
-
-1. Read `config.md` and preserve exclusions, priorities, stack.
-2. Clean Code handling: if CLAUDE.md has markers or the heading, ask
-   A) refresh B) keep C) remove; honour `Enabled: No` from config.md by
-   skipping silently with one reminder line. When no block exists and
-   Enabled is Yes/absent, compose and inject (announce before writing).
-3. Confirm the plan (exclusions, priorities, cleancode decision) with the
-   user, then re-run Steps 3-7.
-
-Special triggers: "disable cleancode" removes the block and sets
-`Enabled: No`; "enable cleancode" re-composes it and sets `Enabled: Yes` -
-both without a full rescan.
-
-## Edge cases
-
-- Inaccessible directories: list them under a "Skipped Directories" note and
-  continue; never fail the whole run for one unreadable path.
-- No recognizable source files: generate a minimal index (overview + file
-  listing) and say so.
-- The user pressed Ctrl+I: they already confirmed once - do not re-ask the
-  global "proceed?" question, but still ask the configuration questions
-  above (or reuse `.claude-index/config.md` when it exists).
+---
+name: project-indexer
+description: Generate and use a project index for quick codebase understanding in new sessions. Scans the workspace, extracts exported symbols, writes .claude-index/index.md plus config, and injects a Google-style Clean Code Guidelines section into CLAUDE.md. Use when the user says "explore the project", "generate index", "regenerate index", "更新索引", "生成索引", or presses Ctrl+I.
+version: 1.1.0
+license: MIT
+keywords: [productivity, codebase, indexing, navigation, cleancode]
+# The read-only tools (read_file, list_dir, glob, grep, ask_user, todo_write)
+# are always available inside a skill frame via the tool floor; this ceiling
+# adds exactly the two writers the generated files need.
+allowed-tools:
+  - write_file
+  - edit_file
+---
+
+# Project Indexer
+
+Generate a structured index of any codebase so a new session understands the
+project with minimal context usage. The index is a **navigation map**, not a
+code copy: enough to see the project globally (type, stack, architecture),
+navigate on demand (feature map, file index), and know which symbols exist
+without reading every file.
+
+## Current request
+
+$ARGUMENTS
+
+## Step 1: Check for an existing index
+
+- If `.claude-index/index.md` exists and has the key sections (Project
+  Overview, Feature Map, File Index), go to "Using an existing index".
+- If it exists but is empty or malformed, tell the user and regenerate
+  (first-time flow), preserving `config.md` if intact.
+- Otherwise run the first-time flow.
+
+## Using an existing index
+
+1. Read `.claude-index/index.md` and `CLAUDE.md` (if present).
+2. Summarize in 3-5 bullets: structure, stack, feature areas, key entry
+   points. Offer to help.
+3. For later questions, navigate via the Feature Map / File Index and read
+   real source only when detail is needed.
+
+## First-time flow
+
+### Step 2: Gather configuration (ask_user)
+
+Ask with `ask_user`, defaults offered in every question:
+
+1. **Exclusions** - A) defaults (node_modules, .git, dist, build,
+   __pycache__, .venv, vendor, coverage, .next, .nuxt, .cache, target, bin,
+   obj, .idea, .vscode) B) add more C) custom list.
+2. **Priority directories** - A) auto-detect (recommended) B) specify C) all
+   equally.
+3. **Tech stack** - auto-detect unless the user names one.
+4. **Clean Code Guidelines** (injected into CLAUDE.md) - A) Google strict
+   (method 60, file 1000 - recommended) B) Google relaxed (method 600)
+   C) custom D) skip.
+
+If C: ask **one `ask_user` call per limit** showing default and range -
+MAX_FILE_LINES 1000 (200-5000), MAX_METHOD_LINES 60 (20-600),
+MAX_FUNCTION_PARAMS 5 (2-10), MAX_CYCLOMATIC 10 (5-25); fall back to the
+default on an out-of-range answer and say so in the summary.
+MAX_LINE_LENGTH (default 100, Python 80) and MAX_NESTING_DEPTH (4) are never
+asked. If the user skips every question, use all defaults.
+
+Treat the answer as `CleanCodeConfig.preset`: strict | relaxed | custom |
+disabled. D (`disabled`) skips the Clean Code composition below, never adds
+markers, and persists `Enabled: No`.
+
+### Step 3: Scan and analyze
+
+1. Traverse the tree with the exclusion rules (`glob`, never one giant read).
+2. Detect project type (frontend/backend/fullstack/library/CLI/monorepo),
+   languages with percentages, frameworks, entry points.
+3. Group files by feature/domain and extract exported symbols - full support
+   for JS/TS (.js/.jsx/.ts/.tsx/.mjs) and Python; best-effort for Java,
+   Kotlin, Go, Rust, C/C++, C#, Ruby, PHP; unknown types are listed without
+   symbols.
+4. Analyze module-level dependencies (import graph).
+
+Adaptive sizing: <50 files -> full detail; 50-200 -> full coverage with
+concise descriptions; 200+ -> detail the priority directories, summarize the
+rest, group similar utilities. Over 1000 files after exclusions: warn and
+suggest more exclusions before continuing; sample representative files with
+glob/grep rather than reading everything. Keep language/framework findings in
+working memory - do NOT write an intermediate JSON file.
+
+### Step 4: Write `.claude-index/`
+
+1. `config.md` - exclusions, priorities, tech stack, plus an Index Settings
+   block (Generated date, Project Root, Index Version) and a Clean Code
+   Settings block (Enabled / Preset / the six limits; when the user picked
+   skip, write `Enabled: No`, `Preset: disabled` and the strict numbers so a
+   later "enable cleancode" can flip it back).
+2. `index.md` - follow `templates/index-template.md` in this skill's
+   directory: Project Overview, Feature Map (per area: entry file, one-line
+   description, key exports with signatures), Module Dependencies, File Index
+   (per-directory tables, one line per file).
+
+### Step 5: Compose the Clean Code Guidelines (skip when disabled)
+
+Read `templates/cleancode-template.md` and `templates/cleancode-overrides.md`
+from this skill's directory, then:
+
+1. Primary languages = every language with >= 10% of post-exclusion source
+   files; if none clears 10%, use the `Other` row.
+2. Take the **minimum** across all matching rows for each numeric column.
+3. Apply the user preset: strict/relaxed values intersect with the language
+   minimum (never looser than the baseline); custom numbers are honoured
+   verbatim with divergence noted.
+4. Substitute every placeholder: `{{MAX_FILE_LINES}}`, `{{MAX_METHOD_LINES}}`,
+   `{{MAX_FUNCTION_PARAMS}}`, `{{MAX_CYCLOMATIC}}`, `{{MAX_LINE_LENGTH}}`,
+   `{{MAX_NESTING_DEPTH}}`, `{{PRIMARY_LANGUAGES}}` (comma-joined languages)
+   and `{{LANGUAGE_HINTS}}` (one `- Language: note` bullet per matching row,
+   deduped by exact string).
+5. Verify no `{{...}}` placeholder remains. Do not count characters at
+   runtime.
+
+### Step 6: Update CLAUDE.md
+
+- `## Project Index` section: upsert (replace when present, else append at
+  end; create the file when missing). Contents: Location
+  `.claude-index/index.md`, Last Updated (YYYY-MM-DD), Contents line, a
+  Usage line, and "Regenerate: say 'regenerate index' / '更新索引'".
+- `## Clean Code Guidelines` section (unless disabled): wrap the rendered
+  body in `<!-- project-indexer:cleancode:begin v1.1.0 -->` and
+  `<!-- project-indexer:cleancode:end -->`. Locate an existing block with
+  the version-agnostic regex `<!-- project-indexer:cleancode:begin
+  v\d+\.\d+\.\d+ -->` (NEVER a literal-version match) plus the literal end
+  marker; fallback: the region from a `## Clean Code Guidelines` heading to
+  the next `## ` heading or EOF. Replace the found block; if none, insert
+  after the Project Index section (first-insert only; when both sections
+  already exist preserve the user's ordering and everything between them).
+  Write UTF-8; add a trailing newline when missing.
+
+### Step 7: Report
+
+List what was created/updated, the feature-area count, files indexed and
+symbols extracted. Offer to start work.
+
+## Regeneration ("regenerate index" / "更新索引")
+
+1. Read `config.md` and preserve exclusions, priorities, stack.
+2. Clean Code handling: if CLAUDE.md has markers or the heading, ask
+   A) refresh B) keep C) remove; honour `Enabled: No` from config.md by
+   skipping silently with one reminder line. When no block exists and
+   Enabled is Yes/absent, compose and inject (announce before writing).
+3. Confirm the plan (exclusions, priorities, cleancode decision) with the
+   user, then re-run Steps 3-7.
+
+Special triggers: "disable cleancode" removes the block and sets
+`Enabled: No`; "enable cleancode" re-composes it and sets `Enabled: Yes` -
+both without a full rescan.
+
+## Edge cases
+
+- Inaccessible directories: list them under a "Skipped Directories" note and
+  continue; never fail the whole run for one unreadable path.
+- No recognizable source files: generate a minimal index (overview + file
+  listing) and say so.
+- The user pressed Ctrl+I: they already confirmed once - do not re-ask the
+  global "proceed?" question, but still ask the configuration questions
+  above (or reuse `.claude-index/config.md` when it exists).

package/skills/project-indexer/templates/cleancode-overrides.md

@@ -1,46 +1,46 @@
-# Clean Code — Language Override Table
-
-> Read by `project-indexer` at Step 5. The skill intersects the rows below
-> with the **primary languages** detected during the scan (any language whose
-> source files account for >= 10% of the post-exclusion total).
->
-> When two or more rows apply, the skill **takes the minimum** for every
-> numeric column. Notes from each matching row are concatenated and rendered
-> as bullets in the `{{LANGUAGE_HINTS}}` placeholder of
-> `cleancode-template.md`.
->
-> Defaults (used when no row matches, i.e. the `Other` row) live in the last
-> row. Numeric units: `MAX_FILE_LINES` and `MAX_METHOD_LINES` are physical
-> lines of source. `MAX_LINE_LENGTH` is columns. `MAX_FUNCTION_PARAMS` is the
-> count of positional + keyword parameters in a single signature.
-
-| Language    | MAX_FILE_LINES | MAX_METHOD_LINES | MAX_LINE_LENGTH | MAX_FUNCTION_PARAMS | Notes |
-|-------------|----------------|------------------|-----------------|---------------------|-------|
-| TypeScript  | 1000           | 60               | 100             | 5                   | Prefer `interface` over `type` for public APIs. |
-| JavaScript  | 1000           | 60               | 100             | 5                   | Avoid `any`; use JSDoc when no TS. |
-| Python      | 800            | 50               | 80              | 5                   | PEP 8 + Google docstrings. |
-| Go          | 800            | 60               | 120             | 4                   | Errors as values; no panic in library code. |
-| Java        | 1500           | 40               | 100             | 5                   | Google Java Style. |
-| Kotlin      | 1500           | 40               | 100             | 5                   | KtLint defaults. |
-| Rust        | 1000           | 60               | 100             | 5                   | `clippy::pedantic` recommended. |
-| C / C++     | 1000           | 50               | 100             | 5                   | Google C++ Style. |
-| Other       | 1000           | 60               | 100             | 5                   | Generic fallback. |
-
-## Merge Rules
-
-1. **Detection threshold** — only languages with >= 10% of source files (after
-   exclusions) contribute. If no language clears 10%, use the `Other` row.
-2. **Numeric merge** — `min()` across every matching row, per column.
-3. **Note merge** — collect each matching row's `Notes` cell, dedupe by exact
-   string match, render as a bullet list. Example for TypeScript + Python:
-   - `- TypeScript: Prefer interface over type for public APIs.`
-   - `- Python: PEP 8 + Google docstrings.`
-4. **Fixed defaults (not in the table, applied unconditionally)** —
-   `MAX_CYCLOMATIC = 10`, `MAX_NESTING_DEPTH = 4`. These can still be
-   overridden by the user via the Custom preset.
-
-## Adding a Language
-
-When extending this table, keep the column order identical and use the
-strictest reasonable value for each cell so the `min()` merge stays
-meaningful for polyglot repos.
+# Clean Code — Language Override Table
+
+> Read by `project-indexer` at Step 5. The skill intersects the rows below
+> with the **primary languages** detected during the scan (any language whose
+> source files account for >= 10% of the post-exclusion total).
+>
+> When two or more rows apply, the skill **takes the minimum** for every
+> numeric column. Notes from each matching row are concatenated and rendered
+> as bullets in the `{{LANGUAGE_HINTS}}` placeholder of
+> `cleancode-template.md`.
+>
+> Defaults (used when no row matches, i.e. the `Other` row) live in the last
+> row. Numeric units: `MAX_FILE_LINES` and `MAX_METHOD_LINES` are physical
+> lines of source. `MAX_LINE_LENGTH` is columns. `MAX_FUNCTION_PARAMS` is the
+> count of positional + keyword parameters in a single signature.
+
+| Language    | MAX_FILE_LINES | MAX_METHOD_LINES | MAX_LINE_LENGTH | MAX_FUNCTION_PARAMS | Notes |
+|-------------|----------------|------------------|-----------------|---------------------|-------|
+| TypeScript  | 1000           | 60               | 100             | 5                   | Prefer `interface` over `type` for public APIs. |
+| JavaScript  | 1000           | 60               | 100             | 5                   | Avoid `any`; use JSDoc when no TS. |
+| Python      | 800            | 50               | 80              | 5                   | PEP 8 + Google docstrings. |
+| Go          | 800            | 60               | 120             | 4                   | Errors as values; no panic in library code. |
+| Java        | 1500           | 40               | 100             | 5                   | Google Java Style. |
+| Kotlin      | 1500           | 40               | 100             | 5                   | KtLint defaults. |
+| Rust        | 1000           | 60               | 100             | 5                   | `clippy::pedantic` recommended. |
+| C / C++     | 1000           | 50               | 100             | 5                   | Google C++ Style. |
+| Other       | 1000           | 60               | 100             | 5                   | Generic fallback. |
+
+## Merge Rules
+
+1. **Detection threshold** — only languages with >= 10% of source files (after
+   exclusions) contribute. If no language clears 10%, use the `Other` row.
+2. **Numeric merge** — `min()` across every matching row, per column.
+3. **Note merge** — collect each matching row's `Notes` cell, dedupe by exact
+   string match, render as a bullet list. Example for TypeScript + Python:
+   - `- TypeScript: Prefer interface over type for public APIs.`
+   - `- Python: PEP 8 + Google docstrings.`
+4. **Fixed defaults (not in the table, applied unconditionally)** —
+   `MAX_CYCLOMATIC = 10`, `MAX_NESTING_DEPTH = 4`. These can still be
+   overridden by the user via the Custom preset.
+
+## Adding a Language
+
+When extending this table, keep the column order identical and use the
+strictest reasonable value for each cell so the `min()` merge stays
+meaningful for polyglot repos.