fix: monorepo fix for subdirectory projects + impact + readme

.agents/skills/architecture/references/code-map.md

@@ -3,20 +3,20 @@
 ## Key Files
 
 **Hub files (most depended-on):**
-- `src/lib/runner.js` - 8 dependents
+- `src/lib/runner.js` - 9 dependents
+- `src/lib/target.js` - 9 dependents
+- `src/lib/scanner.js` - 8 dependents
 - `src/lib/errors.js` - 7 dependents
-- `src/lib/scanner.js` - 7 dependents
-- `src/lib/target.js` - 7 dependents
-- `src/lib/skill-writer.js` - 6 dependents
+- `src/lib/skill-writer.js` - 7 dependents
 
 **Domain clusters:**
 
 | Domain | Files | Top entries |
 |--------|-------|-------------|
-| src | 37 | `src/lib/runner.js`, `src/commands/doc-init.js`, `src/commands/doc-sync.js` |
+| src | 44 | `src/commands/doc-init.js`, `src/lib/runner.js`, `src/lib/target.js` |
 
 **High-churn hotspots:**
-- `src/commands/doc-init.js` - 27 changes
-- `src/commands/doc-sync.js` - 19 changes
+- `src/commands/doc-init.js` - 32 changes
+- `src/commands/doc-sync.js` - 20 changes
 - `src/lib/runner.js` - 16 changes
 

.agents/skills/base/SKILL.md

@@ -9,7 +9,7 @@ This is a **base skill** that always loads when working in this repository.
 
 ---
 
-You are working in **aspens** — a CLI tool that generates and maintains AI-ready documentation (skill files + AGENTS.md) for any codebase. Supports multiple output targets (Claude Code, Codex CLI).
+You are working in **aspens** — a CLI that keeps coding-agent context accurate as your codebase changes. Scans repos, generates project-specific instructions and skills for Claude Code and Codex CLI, and keeps them fresh.
 
 ## Tech Stack
 Node.js (ESM) | Commander | Vitest | es-module-lexer | @clack/prompts | picocolors
@@ -18,11 +18,13 @@ Node.js (ESM) | Commander | Vitest | es-module-lexer | @clack/prompts | picocolo
 - `npm test` — Run vitest suite
 - `npm start` / `node bin/cli.js` — Run CLI
 - `aspens scan [path]` — Deterministic repo analysis (no LLM)
-- `aspens doc init [path]` — Generate skills + hooks + AGENTS.md (supports `--target claude|codex|all`, `--backend claude|codex`)
+- `aspens doc init [path]` — Generate skills + hooks + AGENTS.md (`--target claude|codex|all`, `--recommended` for full recommended setup)
+- `aspens doc impact [path]` — Show freshness, coverage, and drift of generated context (`--apply` for auto-repair, `--backend`/`--model`/`--timeout`/`--verbose` for LLM interpretation)
 - `aspens doc sync [path]` — Incremental skill updates from git diffs
 - `aspens doc graph [path]` — Rebuild import graph cache (`.claude/graph.json`)
 - `aspens add <type> [name]` — Install templates (agents, commands, hooks)
 - `aspens customize agents` — Inject project context into installed agents
+- `aspens save-tokens [path]` — Install token-saving session settings (`--recommended` for no-prompt install, `--remove` to uninstall)
 
 ## Architecture
 CLI entry (`bin/cli.js`) → command handlers (`src/commands/`) → lib modules (`src/lib/`)
@@ -35,15 +37,17 @@ CLI entry (`bin/cli.js`) → command handlers (`src/commands/`) → lib modules
 - `src/lib/skill-writer.js` — Writes skill files and directory-scoped files, generates skill-rules.json, merges settings
 - `src/lib/skill-reader.js` — Parses skill files, frontmatter, activation patterns, keywords
 - `src/lib/diff-helpers.js` — Targeted file diffs and prioritized diff truncation for doc-sync
-- `src/lib/git-helpers.js` — Git repo detection, diff retrieval, log formatting
-- `src/lib/git-hook.js` — Post-commit git hook installation/removal for auto doc-sync
+- `src/lib/git-helpers.js` — Git repo detection, git root resolution, diff retrieval, log formatting
+- `src/lib/git-hook.js` — Post-commit git hook installation/removal for auto doc-sync (monorepo-aware)
+- `src/lib/impact.js` — Context health analysis: domain coverage, hub surfacing, drift detection, hook health, save-tokens health, usefulness summary, value comparison, opportunities
+- `src/lib/save-tokens.js` — Save-tokens config defaults, settings builders, gitignore/readme generators
 - `src/lib/timeout.js` — Timeout resolution (`--timeout` flag > `ASPENS_TIMEOUT` env > default)
 - `src/lib/errors.js` — `CliError` class (structured errors caught by CLI top-level handler)
-- `src/lib/target.js` — Target definitions (claude/codex), config persistence (`.aspens.json`)
+- `src/lib/target.js` — Target definitions (claude/codex), config persistence (`.aspens.json`) with `saveTokens` feature config
 - `src/lib/target-transform.js` — Transforms Claude-format output to other target formats
 - `src/lib/backend.js` — Backend detection and resolution (which CLI generates content)
 - `src/prompts/` — Prompt templates with `{{partial}}` and `{{variable}}` substitution
-- `src/templates/` — Bundled agents, commands, hooks, and settings for `aspens add` / `doc init`
+- `src/templates/` — Bundled agents, commands, hooks, and settings for `aspens add` / `doc init` / `save-tokens`
 
 ## Critical Conventions
 - **Pure ESM** — `"type": "module"` throughout; use `import`/`export`, never `require()`
@@ -55,14 +59,15 @@ CLI entry (`bin/cli.js`) → command handlers (`src/commands/`) → lib modules
 - **Target/Backend distinction** — Target = output format/location; Backend = which LLM CLI generates content. Config persisted in `.aspens.json`
 - **Scanner is deterministic** — no LLM calls; pure filesystem analysis
 - **CliError pattern** — command handlers throw `CliError` instead of calling `process.exit()`; caught at top level in `bin/cli.js`
+- **Monorepo support** — `getGitRoot()` resolves the actual git root; hooks, sync, and impact scope to the subdirectory project path
 
 ## Structure
 - `bin/` — CLI entry point (commander setup, CliError handler)
-- `src/commands/` — Command handlers (scan, doc-init, doc-sync, doc-graph, add, customize)
+- `src/commands/` — Command handlers (scan, doc-init, doc-impact, doc-sync, doc-graph, add, customize, save-tokens)
 - `src/lib/` — Core library modules
 - `src/prompts/` — Prompt templates + partials
 - `src/templates/` — Installable agents, commands, hooks, settings
 - `tests/` — Vitest test files
 
 ---
-**Last Updated:** 2026-04-02
+**Last Updated:** 2026-04-09

.agents/skills/claude-runner/SKILL.md

@@ -35,7 +35,7 @@ You are working on the **CLI execution layer** — the bridge between assembled
 - **Validation:** `validateSkillFiles()` checks for truncation (XML tag collisions), missing frontmatter, missing sections, bad file path references.
 - **Skill rules generation:** `extractRulesFromSkills()` reads all skills via `skill-reader.js`, produces `skill-rules.json` (v2.0) with file patterns, keywords, and intent patterns.
 - **Domain patterns:** `generateDomainPatterns()` converts file patterns to bash `detect_skill_domain()` function using `BEGIN/END` markers.
-- **Settings merge:** `mergeSettings()` merges aspens hook config into existing `settings.json`, detecting aspens-managed hooks by `ASPENS_HOOK_MARKERS` (`skill-activation-prompt`, `post-tool-use-tracker`).
+- **Settings merge:** `mergeSettings()` merges aspens hook config into existing `settings.json`. Detects aspens-managed hooks by `ASPENS_HOOK_MARKERS` (`skill-activation-prompt`, `graph-context-prompt`, `post-tool-use-tracker`, `save-tokens-statusline`, `save-tokens-prompt-guard`, `save-tokens-precompact`). Also handles `statusLine` merging — replaces existing statusLine only if the current one is aspens-managed (detected by `isAspensHook`), preserving user-custom statusLine configs. After merging hooks, `dedupeAspensHookEntries()` removes duplicate aspens-managed entries per event type.
 - **Directory-scoped writes:** `writeTransformedFiles()` handles files outside `.claude/` (e.g., `src/billing/AGENTS.md`) with explicit path allowlist — only `AGENTS.md`, `AGENTS.md` exact files and `.claude/`, `.agents/`, `.codex/` prefixes are permitted.
 - **`findSkillFiles` matching:** Only matches the exact `skillFilename` (e.g., `skill.md` or `SKILL.md`), not arbitrary `.md` files in the skills directory.
 
@@ -46,8 +46,8 @@ You are working on the **CLI execution layer** — the bridge between assembled
 - **Path sanitization is non-negotiable** — `sanitizePath()` blocks `..` traversal, absolute paths, and any path not in the allowed set.
 - **Prompt partials resolve before variables** — `{{skill-format}}` resolves to `partials/skill-format.md` first. If no file, falls through to variable substitution.
 - **Timeout resolution:** `resolveTimeout(flagValue, fallbackSeconds)` — `--timeout` flag wins, then `ASPENS_TIMEOUT` env, then caller-provided fallback. Size-based defaults (small: 120s, medium: 300s, large: 600s, very-large: 900s) are set by command handlers, not runner.
-- **`mergeSettings` preserves non-aspens hooks** — identifies aspens hooks by `ASPENS_HOOK_MARKERS`, replaces matching entries, preserves everything else.
+- **`mergeSettings` preserves non-aspens hooks and statusLine** — identifies aspens hooks by `ASPENS_HOOK_MARKERS` (now includes save-tokens markers), replaces matching entries, preserves everything else. StatusLine only replaced if current one is aspens-managed. Post-merge deduplication ensures no duplicate aspens entries accumulate.
 - **Debug mode:** Set `ASPENS_DEBUG=1` to dump raw stream-json to `$TMPDIR/aspens-debug-stream.json` (Claude) or `$TMPDIR/aspens-debug-codex-stream.json` (Codex). Codex also logs exit code and output length to stderr.
 
 ---
-**Last Updated:** 2026-04-07
+**Last Updated:** 2026-04-09

.agents/skills/codex-support/SKILL.md

@@ -20,8 +20,8 @@ Keywords: codex, target, backend, AGENTS.md, directory-scoped, transform, multi-
 You are working on **multi-target output support** — the system that lets aspens generate documentation for Claude Code, Codex CLI, or both simultaneously.
 
 ## Key Files
-- `src/lib/target.js` — Target definitions (`TARGETS`), `getAllowedPaths()`, path helpers, config persistence (`.aspens.json`)
-- `src/lib/target-transform.js` — Transforms Claude-format output to other target formats; `projectCodexDomainDocs()`, `validateTransformedFiles()`, content sanitization
+- `src/lib/target.js` — Target definitions (`TARGETS`), `getAllowedPaths()`, `mergeConfiguredTargets()`, path helpers, config persistence (`.aspens.json`) with feature config support (`saveTokens`)
+- `src/lib/target-transform.js` — Transforms Claude-format output to other target formats; `projectCodexDomainDocs()`, `validateTransformedFiles()`, `ensureRootKeyFilesSection()`, content sanitization
 - `src/lib/backend.js` — Backend detection (`detectAvailableBackends`) and resolution (`resolveBackend`) with fallback logic
 
 ## Key Concepts
@@ -30,23 +30,27 @@ You are working on **multi-target output support** — the system that lets aspe
 - **Canonical generation:** Generation always produces Claude-canonical format first. Prompts always receive `CANONICAL_VARS` (hardcoded Claude paths from `doc-init.js`). Transforms run **after** generation to produce other target formats.
 - **Content transform:** `transformForTarget()` remaps paths and content. For Codex: base skill → root `AGENTS.md`, domain skills → both `.agents/skills/{domain}/SKILL.md` and source directory `AGENTS.md`. `generateCodexSkillReferences()` creates `.agents/skills/architecture/` with code-map data.
 - **Content sanitization:** `sanitizeCodexInstructions()` and `sanitizeCodexSkill()` strip Claude-specific references (hooks, skill-rules.json, Claude Code mentions) from Codex output.
-- **`getAllowedPaths(targets)`** — Returns `{ dirPrefixes, exactFiles }` union across all active targets. Dir prefixes use **full** target paths (e.g., `.agents/skills/`, not `.agents/`), providing tighter path validation.
+- **`ensureRootKeyFilesSection(content, graphSerialized)`** — Post-processes root instructions file to guarantee a `## Key Files` section with top hub files from the graph.
+- **`mergeConfiguredTargets(existing, next)`** — Merges target arrays to avoid dropping previously configured targets during narrower runs. Validates against `TARGETS` keys, deduplicates.
+- **`getAllowedPaths(targets)`** — Returns `{ dirPrefixes, exactFiles }` union across all active targets.
 - **Backend detection:** `detectAvailableBackends()` checks if `claude` and `codex` CLIs are installed. `resolveBackend()` picks best match: explicit flag > target match > fallback.
-- **Config persistence:** `.aspens.json` at repo root stores `{ targets, backend, version }`. `readConfig()` returns `null` if missing **or if the config is structurally invalid** — callers default to `'claude'` target. Validation via internal `isValidConfig()` ensures `targets` is a non-empty array of known target keys, `backend` (if present) is a known target key, and `version` (if present) is a string.
-- **Multi-target publish:** `doc-sync` uses `publishFilesForTargets()` to generate output for all configured targets from a single LLM run — source target files kept as-is, other targets get transforms applied.
-- **Codex inference tightened:** `inferConfig()` only adds `'codex'` to inferred targets when `.codex/` config dir or `.agents/skills/` dir exists — a standalone `AGENTS.md` without either is not sufficient.
-- **Conditional architecture ref:** Codex `buildCodexSkillRefs()` only includes the architecture skill reference when a graph was actually serialized (`hasGraph` parameter).
+- **Config persistence:** `.aspens.json` at repo root stores `{ targets, backend, version, saveTokens? }`. `readConfig()` returns `null` if missing **or if the config is structurally invalid**. `isValidConfig()` validates targets, backend, version, and `saveTokens` (via `isValidSaveTokensConfig()`).
+- **Feature config (`saveTokens`):** Optional object in `.aspens.json` validated by `isValidSaveTokensConfig()` — checks `enabled` (boolean), `warnAtTokens`/`compactAtTokens` (positive integers, compact > warn unless either is `MAX_SAFE_INTEGER`), `saveHandoff`/`sessionRotation` (booleans), optional `claude`/`codex` sub-objects with `enabled` and `mode`.
+- **`writeConfig` preserves feature config:** `writeConfig()` reads existing config and merges — `saveTokens` preserved unless explicitly set to `null` (intentional removal) or `undefined` (keep existing). Targets and backend also merge with existing.
+- **Multi-target publish:** `doc-sync` uses `publishFilesForTargets()` to generate output for all configured targets from a single LLM run.
+- **Codex inference tightened:** `inferConfig()` only adds `'codex'` to inferred targets when `.codex/` config dir or `.agents/skills/` dir exists.
+- **Conditional architecture ref:** Codex `buildCodexSkillRefs()` only includes the architecture skill reference when a graph was actually serialized.
 
 ## Critical Rules
 - **Generation always targets Claude canonical format first** — transforms run after, never during. Prompts always receive `CANONICAL_VARS`.
-- **Split write logic:** `writeSkillFiles()` handles direct-write files (`.claude/`, `.agents/`, `AGENTS.md`, root `AGENTS.md`). `writeTransformedFiles()` handles directory-scoped `AGENTS.md` (e.g., `src/billing/AGENTS.md`) with an explicit path allowlist and warn-and-skip policy.
-- **Path safety:** `validateTransformedFiles()` in `target-transform.js` rejects absolute paths, traversal, and unexpected filenames. `writeTransformedFiles()` enforces the same checks plus an allowlist (`AGENTS.md`/`AGENTS.md` exact, `.claude/`/`.agents/`/`.codex/` prefixes).
+- **Split write logic:** `writeSkillFiles()` handles direct-write files. `writeTransformedFiles()` handles directory-scoped `AGENTS.md` with an explicit path allowlist and warn-and-skip policy.
+- **Path safety:** `validateTransformedFiles()` rejects absolute paths, traversal, and unexpected filenames. `writeTransformedFiles()` enforces the same checks.
 - **Codex-only restrictions:** `add agent/command/hook` and `customize agents` throw `CliError` for Codex-only repos. `add skill` works for both targets.
 - **Graph/hooks are Claude-only** — `persistGraphArtifacts()` returns data without writing files when `target.supportsGraph === false`. Hook installation skipped when `supportsHooks === false`.
-- **Config validation is defensive** — `readConfig()` treats malformed but parseable JSON (e.g., wrong types for `targets`/`backend`/`version`) as invalid and returns `null`, same as missing config.
+- **Config validation is defensive** — `readConfig()` treats malformed but parseable JSON (e.g., wrong types for `targets`/`backend`/`version`/`saveTokens`) as invalid and returns `null`, same as missing config.
 
 ## References
 - **Patterns:** See `src/lib/target.js` for all target property definitions
 
 ---
-**Last Updated:** 2026-04-07
+**Last Updated:** 2026-04-09