v1.10.2: README reframed around project memory

Documentation only — no code changes.

The README described AI_README as a style guide, which invited the obvious response: "then I'll just write a CLAUDE.md". Conventions are the least valuable thing these files hold.

Reframed around what a real deployment accumulates: silent-failure traps, deliberate-looking oddities, and post-mortem lessons that are invisible in source. The code shows the fix, never the failure that motivated it.

What changed

• The Problem now opens on session amnesia — the AI starts every session with no memory of the last, which is the root of the other symptoms
• New everyday-cases table before any domain-specific example, so the idea lands without needing the reader to know a particular stack
• Real production entries kept as evidence in a collapsed table, with a plain-language reading for each
• AI_README vs. CLAUDE.md section now contrasts where the knowledge comes from — written up front by a human vs. earned mid-session while debugging — rather than just how each file is maintained
• Documents the reviewed write path: validation, conflict detection, quality scoring, token budget. Conflict detection is what stops an AI "fixing" a workaround back into the bug it was avoiding
• Nesting claims corrected: both formats nest. The difference is when subdirectory rules reach the AI, verified with a small experiment

Full Changelog: v1.10.1...v1.10.2

v1.10.1: Don't assume git in the architecture check

Fix

The ARCHITECTURE CHECK introduced in v1.10.0 told the agent to git mv files unconditionally. Projects that aren't under git — fresh prototypes, downloaded samples, other VCS — would hit a hard failure on a step that has an obvious fallback.

The instruction now reads: git mv if the project is under git (keeps history), a plain move otherwise.

Also removed a redundant git mv aside from the confirm-with-user step; that step is about the change being hard to reverse, not about tooling.

Prompt text only — no behavior or API changes.

v1.10.0: Architecture check for over-budget files

New: a third over-budget mode

Some AI_READMEs are over budget with no dominant section and nothing left to compress — just many mid-sized sections, each one real signal. Rewriting such a file only deletes useful conventions, because the doc shape is a symptom: the directory itself hosts too many parallel features in one flat level.

update_ai_readme and compress_ai_readme now emit an ARCHITECTURE CHECK when a file is over budget with no dominant section and 6+ sections. It deliberately frames the problem as an architecture question rather than a formatting one:

• The question is "should this directory be regrouped into feature subdirectories?" — the AI_README shrinking is a consequence, not the goal.
• The agent must inspect the actual files and judge from the code, not from the AI_README's headings.
• Explicit false-positive exit: if the files really are cohesive (shared logic, one domain), it's told to just rewrite the doc and not touch the directory.
• Moving files requires user confirmation first, and git mv to preserve history.

Existing behavior is unchanged: a file with one dominant section (>= 40%) still gets the targeted SPLIT, which always takes priority over the architecture check.

Fixed: validate no longer mislabels the fix

validate_ai_readmes used to tell you "these files need rewriting, not patching" for every severely over-budget file — wrong advice for a file that actually needs a split, and it pushed agents into deleting real signal. It now labels each file with its likely fix:

🚨 These files are severely over budget — patching won't fix them:
  - AI_README.md (score: 48, tokens: 399) — likely fix: ARCHITECTURE CHECK — 8 sections, none dominant

The split/restructure/rewrite decision is now shared through a single diagnoseOverBudget(), so validate, compress and update can never disagree about the same file.

v1.9.1: Show closest match on replace failure

Improvement

update_ai_readme's `replace` operation fails when `searchText` doesn't match anything in the file — and this happens a lot, because the caller (an LLM) is usually re-typing a remembered version of the content rather than copying it exactly. One changed word, dash, or dropped clause and the operation fails with nothing to go on but the text you sent.

The error now also shows the actual closest-matching lines from the file — same line count as your `searchText`, picked by line-level similarity — so the difference is visible at a glance instead of requiring a re-read of the whole file:

Text not found: - mat-autocomplete: never combine manual string [ngModel] with [displayWith] — displayWith changed the string, not the option object.

Closest match in the file (searchText must match this EXACTLY, including punctuation/whitespace):
- mat-autocomplete: never combine manual string [ngModel] with [displayWith] — displayWith receives the string, not the option object.

If nothing in the file is a close enough match (similarity below 0.3), the hint is omitted rather than showing something misleading.

No API changes.

v1.9.0: Nudge starts at the budget; error tightened to 2×

Behavior changes

Two deliberate tier adjustments. The full ladder (@ default budget 400): 200 / 400 / 600 / 700 / 800 — excellent / budget=nudge / warning / forced rewrite / error.

1. The light nudge now starts at the budget itself (1.25× → 1.0×)

tokenBudget is documented as "a target — files over it get nudged", but the old 1.25× ratio left a silent band: a file at 631 tokens under a 550 budget got no nudge, no warning — nothing. Crossing the budget now triggers the light "drifting — tighten this up" reminder, so the budget number actually means something.

2. Validator error tightened to double the budget (2.5× → 2.0×)

The 2.5× was an artifact of the historical 1000/400 constants, not a design choice. 2× is the natural "double the budget" line. In practice this is rarely the first defense — the 1.75× tier already forces a rewrite/split before a file reaches error.

What you'll notice

• Files between 1.0×–1.25× of budget (400–500 @ default) now get a light nudge where they were previously silent.
• Files between 2.0×–2.5× (800–1000 @ default) are now validation errors instead of warnings.
• compress_ai_readme on a file just over budget now hands off to the LLM rewrite flow instead of reporting "already concise".

No API changes.

v1.8.2: Encourage the LLM to cut when rewriting

Improvement

LLMs skew additive — when asked to shorten, they'll rephrase or add before they delete, and tend to keep an existing line just because it's already there. The over-budget rewrite guidance listed what to drop but never gave the model permission to drop things on its own judgment.

This release adds that permission where it matters:

• Over-budget rewrite prompt: "Be willing to DELETE. When unsure a line earns its place, cut it — don't keep it just because it's already there. A dropped low-value line costs nothing; a kept one costs budget every read."
• Writing guide: "When unsure, CUT."

Both flow through the shared guidance to every over-budget entry point — direct rewrite, update_ai_readme, the compress_ai_readme handoff, and validate_ai_readmes "needs rewriting" tier — i.e. exactly when a file is too long and the model needs to trim it.

Prompt text only; no behavior or API changes.

v1.8.1: Fix README rendering on npm

Fixes

• README not rendering on npm — a stray closing code fence (```) after the update_ai_readme "Note" block left the file with an odd number of fences. npm's markdown renderer mis-parsed everything after it and showed no README. Removed the stray fence.
• Docs: documented the now-required projectRoot parameter on update_ai_readme and compress_ai_readme (required since v1.8.0).

No code changes — v1.8.0 behavior is unchanged.

v1.8.0: Unified config resolution (projectRoot required)

What changed

All six tools now resolve .aireadme.config.json the same way — loadConfig(projectRoot), reading config from the explicit project root. No walking up, no guessing.

compress_ai_readme and update_ai_readme previously lacked a projectRoot and had to infer it from the file path. v1.7.3 made them walk up the directory tree, which fixed nested READMEs but could read a config above the project (e.g. in $HOME) and left them with a different config-lookup path than the other four tools. This release unifies the behavior instead.

• compress_ai_readme / update_ai_readme now require projectRoot and read config exactly like get_context_for_file / discover_ai_readmes / validate_ai_readmes / init_ai_readme.
• Removed the loadConfigNearest / loadConfigFor guessing helpers (and their tests).

⚠️ Breaking

Callers of compress_ai_readme / update_ai_readme must now pass projectRoot. This parameter was never published to npm (the registry is at 1.7.2), so no released public API depended on its absence — hence a minor bump rather than a major one.

v1.7.3: Nearest-config lookup for compress/update

Bug fix

compress_ai_readme and update_ai_readme only receive a readmePath, and were inferring the project root as dirname(dirname(readmePath)) — a fixed two levels up. For an AI_README nested deeper than one level (e.g. apps/backend/AI_README.md), that missed a root-level .aireadme.config.json and silently fell back to the default token budget (400), ignoring a configured tokenBudget, excludePatterns, etc.

New ReadmeValidator.loadConfigNearest() walks up from the file's directory to the first .aireadme.config.json (or the filesystem root), so nested READMEs pick up the project config correctly. compress and update now use it.

Covered by new unit tests (ancestor-config lookup + null when none found).

v1.7.2: Rename config key verbosity → guidanceLevel

What changed

The prompt-size knob added in v1.7.1 is renamed at the config surface:

{ "guidanceLevel": "medium" }

guidanceLevel describes what the setting actually controls — how much guidance (tool descriptions + get_context reminder) the server sends the model — rather than "verbosity", which reads as the chattiness of the output. Values are unchanged: high (default) / medium.

Config key and docs only; behavior is identical to v1.7.1. Since v1.7.1 was never published to npm, there's no verbosity alias to keep.