capman 0.5.4 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,52 @@ All notable changes to capman are documented here.
 
 ---
 
+## [0.5.5] — 2026-05-03
+### Fixed
+
+**Critical:**
+- LLM rate-limit slot now refunded on failure — `recordLLMFailure()` decrements `llmCallsThisMinute`. Previously burned slot was never returned, causing premature rate exhaustion under sustained errors and silent degradation to keyword-only matching
+- `maxLLMCallsPerMinute: 0` now returns a clear `'LLM disabled'` message instead of arithmetic confusion
+- Anthropic/OpenAI/OpenRouter error responses now read via `res.text()` before `res.ok` check — `res.json()` on a non-200 with malformed body was masking the real API error with a parse exception
+- Empty string API keys (`""`) now correctly rejected — `??` operator passed empty strings through as truthy; replaced with `.trim() ||` across all three provider env vars
+
+**High:**
+- Privacy trace step now correctly shows `'fail'` when auth would block — previously always pushed `status: 'pass'` regardless of auth state, making the trace misleading for unauthenticated requests
+- `preBoostMatchResult` is now an explicit shallow copy (`{ ...matchResult, candidates: matchResult.candidates.slice() }`) instead of a reference alias — prevents accidental mutation corrupting the pre-boost snapshot
+- `'manage'` keyword no longer causes false admin classification in OpenAPI parser — replaced substring check with word-boundary regex `\b(admin|administrator|backoffice|back-office|internal|superuser)\b`. Operations like `manageWishlist`, `fileManager` are no longer misclassified as admin
+- `'context'` and `'static'` param sources removed from schema and types — were schema-valid but silently dropped at runtime, injecting `null` into URLs with no error. Schema now only accepts `'user_query'` and `'session'`. Parser updated to map Swagger 2.x body/formData params to `'user_query'`
+- Swagger 2.0 `scheme` no longer hardcoded to `https` — respects declared `schemes` array, prefers `https` over `http` when both present
+- `process.exit()` removed from library signal handlers — `FileLearningStore` SIGTERM/SIGINT handlers were calling `process.exit(0)`, hijacking application shutdown sequence. Handlers now flush only. Handler references stored as module-level variables and cleaned up via `unregisterExitHandlers()` when `activeStores` is empty after `destroy()`
+- LLM `extracted_params` validated against declared capability params — previously cast directly to `Record<string, string | null>`. Nested objects now produce `null` instead of `"[object Object]"` in URLs. Unknown keys dropped. Numbers and booleans coerced to string
+
+**Medium:**
+- `ENOENT` vs corruption now distinguished in `FileCache` and `FileLearningStore` load — bare `catch {}` replaced with code check; only non-ENOENT errors emit a warning
+- `loadPromise` now resets on rejection — previously a failed load cached the rejected promise permanently, causing all subsequent calls to fail forever
+- `validateNavParam` allowlist aligned with `validateApiPathParam` — dots, colons, `@` now permitted. Allows deep links (`myapp://path`), domain-qualified values (`auth.tokens`), versioned routes (`v1:resource`)
+- `manifest.app` sanitized before LLM prompt injection — strips newlines, tabs, and control characters that could break prompt structure
+- `buildCacheKey` now used on cache write — engine stores results under both `normalizeQuery` key (exact phrasing) and `buildCacheKey` (capability + params semantic key). Differently-phrased queries resolving to the same capability share cache entries
+- Description scoring normalized against `Math.min(descWords.length, 10)` — previously `overlap / totalWords` penalized rich documentation. Long descriptions no longer score lower than short ones for the same keyword overlap
+- Silent `baseUrl` placeholder in parser now emits a `logger.warn` — generated configs with no server URL were silently broken at runtime
+- `writeManifest` now validates output path stays within working directory — public API had no guard, only the CLI wrapper did
+- `scoreCapability` converted from O(n²) to O(n) — `qWords.includes(w)` inside loops replaced with a `Set` built once per `match()` call. At 500 capabilities × 30 query words: ~300,000 ops → ~15,000 ops
+
+**Low / Cosmetic:**
+- `export class CapmanEngine` indentation fixed — extra leading 2-space indent removed
+- Trailing whitespace artifact removed from `matcher.ts` line 89
+- Rate-limiter call sites in `_runMatch()` now have comment noting shared quota between `ask()` and `explain()`
+- Learning boost skips high-confidence LLM matches — `applyBoostToMatchResult()` now accepts `resolvedVia` and returns early when `resolvedVia === 'llm' && confidence > 80`. Avoids learning signal incorrectly overriding strong LLM decisions
+- `matchWithLLM()` sanitizes capability `description` and `examples` fields via `sanitizeForPrompt()` before LLM prompt injection — strips newlines, delimiters, leading braces. Defence-in-depth on top of caller-side sanitization
+- `resolveApi` JSDoc updated — documents that partial failure scenario does not surface which endpoints succeeded, and notes planned `partialSuccess` field in future version
+- `extractParams` JSDoc updated — documents fallback word extraction limitation and future `pattern` field plan
+- `matchWithLLM` security JSDoc updated — notes current single-string prompt limitation for system/user message separation
+
+### Tests
+- 99 tests passing (up from 97)
+- Added: `'manage'` false admin classification test
+- Added: nav params with dots/colons allowed test
+  
+---
+
 ## [0.5.4] — 2026-04-29
 ### Added
 - `engine.loadManifest(manifest)` — hot-reloads the manifest without creating a new engine instance. Preserves cache, learning history, and rate limiter state. Clears cache automatically since cached results from the old manifest are no longer valid

package/CODEBASE.md

@@ -28,6 +28,7 @@ All TypeScript types and interfaces. No logic — pure declarations.
 
 Key exports:
 - `Capability`, `CapabilityParam`, `Manifest`, `CapmanConfig` — core data shapes
+- `CapabilityParam.source` — `'user_query' | 'session'` only. `context` and `static` removed in v0.5.5 — were schema-valid but silently dropped at runtime
 - `MatchResult` — what `match()` returns, including `candidates: MatchCandidate[]`
 - `MatchCandidate` — `{ capabilityId, score, matched }` — all scored candidates
 - `ResolveResult`, `ApiCallResult` — what `resolve()` returns, with `status` and `data`
@@ -48,8 +49,12 @@ Key exports:
 
 Notable rules:
 - `id` must match `/^[a-z0-9_]+$/` — snake_case only
-- `description` minimum 10 characters
+- `description` minimum 10 characters, maximum 500 characters
+- `examples` each entry maximum 200 characters
+- `source` only accepts `'user_query'` or `'session'`
 - Capability IDs must be unique within a manifest
+- `baseUrl` required when any capability uses `api` or `hybrid` resolver
+- `CapmanConfig` refined — `baseUrl` must be present when any API/hybrid capability exists
 
 ---
 
@@ -59,13 +64,13 @@ Manifest lifecycle — create, read, write, validate.
 Key exports:
 - `generate(config)` → `Manifest` — converts config to manifest, deep-copies capabilities
 - `loadConfig(path?)` → `CapmanConfig` — loads `capman.config.js` via `require()`
-- `writeManifest(manifest, path?)` — writes `manifest.json`
+- `writeManifest(manifest, path?)` — writes `manifest.json`. Output path validated against working directory — throws on path traversal
 - `readManifest(path?)` → `Manifest` — reads and Zod-validates `manifest.json`
 - `validate(manifest)` → `ValidationResult`
 - `generateStarterConfig()` → `string`
 - `VERSION` — current version string, auto-generated by `scripts/version.js`
 
-Note: `loadConfig()` uses `require()` internally — CJS config files only. ESM config files (`.mjs` or `"type": "module"`) are not supported. Full ESM config support is planned for v0.6.
+Note: `loadConfig()` uses `require()` internally — CJS config files only. ESM config files (`.mjs` or `"type": "module"`) produce a clear error with migration instructions. Full ESM config support is planned for v0.6.
 
 ---
 
@@ -73,28 +78,38 @@ Note: `loadConfig()` uses `require()` internally — CJS config files only. ESM
 Intent matching — keyword scoring and LLM-based matching.
 
 Key exports:
-- `match(query, manifest)` → `MatchResult` — scores all capabilities, returns winner + all candidates
+- `match(query, manifest, options?)` → `MatchResult` — scores all capabilities, returns winner + all candidates
+  - `options.fuzzyMatch` — enable Fuse.js fuzzy matching (default: false)
+  - `options.fuzzyThreshold` — Fuse.js threshold 0.0–1.0 (default: 0.4)
 - `matchWithLLM(query, manifest, { llm })` → `MatchResult` — LLM-based matching
   - Query passed as `JSON.stringify({ user_query })` with system instructions before user data
   - `USER_QUERY_START/END` delimiters separate instructions from user-controlled content
-  - Parse failures throw `LLM_PARSE_ERROR:` prefixed errors — not counted as network failures
+  - Capability `description` and `examples` sanitized via `sanitizeForPrompt()` before injection
+  - `manifest.app` sanitized — strips newlines/control chars, capped at 100 chars
+  - LLM `extracted_params` validated against declared capability params — nested objects → null, numbers/booleans → string, unknown keys dropped
+  - Parse failures throw `LLMParseError` — not counted toward circuit breaker
   - Errors propagate to caller — no internal try/catch
 - `extractParams(query, capability)` → `Record<string, string | null>` — direct param extraction
 - `resolverToIntent(capability)` → intent string — converts resolver type to intent
 - `STOPWORDS` — set of words filtered from scoring and learning index
+- `LLMParseError` — typed error class for LLM parse failures
+- `MatchOptions` — `{ fuzzyMatch?, fuzzyThreshold? }`
 
-Scoring algorithm (weights):
-- Examples: `Math.max` across all examples (best single match, up to 60 points),
-- Description match: up to 30 points
-- Name match: up to 10 points
-- When `fuzzyMatch` enabled, Fuse.js flat corpus scores merged via `Math.max` with keyword scores.
+Scoring algorithm:
+- Examples: `Math.max` across all examples — best single match up to 60 points. Quality beats quantity — a capability with 10 weak examples no longer beats one with a single precise example
+- Description: `Math.min(overlap / Math.min(descWords.length, 10), 1) * 30` — normalized against a cap of 10 words to avoid penalizing rich documentation
+- Name: up to 10 points
+- Fuzzy (optional): Fuse.js flat corpus — one entry per example/description/name, one index per `match()` call, results grouped by capability, best hit merged via `Math.max` with keyword score
+
+Performance: `qWordSet` built once as `Set<string>` per `match()` call — O(1) `.has()` lookups replace O(n) `Array.includes` in all scoring loops.
 
 Param extraction:
 - `isIdParam` — single token (e.g. `order_id=1234`)
 - `isNavParam` — single token after nav keywords (`to`, `open`, `show`)
 - Multi-word — joined with `-` (e.g. `product=blue-jacket`)
-- Required param fallback — only accepts identifier-shaped last word (rejects generic nouns)
+- Required param fallback — only accepts identifier-shaped last word (rejects generic nouns and category words)
 - Optional params stay `null` if no keyword match found
+- Session params return `null` — injected by resolver from auth context, not extracted from query
 
 ---
 
@@ -104,16 +119,19 @@ Capability execution — API calls, navigation, hybrid.
 Key exports:
 - `resolve(matchResult, params, options)` → `ResolveResult`
   - Enforces privacy before executing
-  - Injects `auth.userId` into session params (skipped if empty string or undefined)
+  - Injects `auth.userId` into session params per-endpoint — only where `{param}` placeholder exists in that specific endpoint's path
   - Supports `dryRun: true` — returns call plan without executing
-  - Retries with `AbortController` timeout on failure
+  - Retries with `AbortController` timeout on failure — safe methods (GET/HEAD/OPTIONS) only by default
+  - `retryAllMethods: true` opt-in for retrying write operations
   - Returns `status` and parsed `data` from API response
   - `null` and `undefined` params never written into URLs
-  - Nav param values URL-encoded via `encodeURIComponent`
-  - Nav params validated against `[a-zA-Z0-9_-]` allowlist — rejects path separators
+  - Both API and nav param values URL-encoded via `encodeURIComponent`
+  - API path params validated against `[a-zA-Z0-9_\-.:@]+` allowlist — prevents path traversal
+  - Nav params validated against same allowlist — rejects `/` and shell metacharacters
+- `checkPrivacy(capability, auth)` → `string | null` — exported. Used by engine to populate privacy trace step accurately
 
 `ResolveOptions`:
-- `baseUrl`, `auth`, `dryRun`, `retries`, `timeoutMs`, `headers`, `fetch`
+- `baseUrl`, `auth`, `dryRun`, `retries`, `timeoutMs`, `retryAllMethods`, `headers`, `fetch`
 
 Privacy enforcement:
 - `public` — always allowed
@@ -122,51 +140,61 @@ Privacy enforcement:
 
 Debug logging: param values and `auth.userId` are redacted as `[REDACTED]` — never logged in plaintext.
 
+⚠️ Parallel execution: multi-endpoint capabilities fire all endpoints simultaneously via `Promise.all()`. If one fails, side effects from successful endpoints cannot be rolled back. Use single-endpoint capabilities for operations requiring ordering or rollback.
+
 ---
 
 ### `src/cache.ts`
 Pluggable cache backends.
 
 Key exports:
-- `CacheStore` interface — `get(key)`, `set(key, result)`, `clear()`, `size()`
-- `MemoryCache` — in-memory Map, 512-entry cap with oldest-first eviction
-- `FileCache` — async `fs.promises` read/write, 2048-entry cap with oldest-first eviction
+- `CacheStore` interface — `get(key, ttlMs?)`, `set(key, result)`, `clear()`, `size()`
+- `MemoryCache` — in-memory Map, 512-entry LRU cap
+- `FileCache` — async `fs.promises` read/write, 2048-entry LRU cap. Atomic writes via `.tmp` + rename. Concurrent load serialized via `loadPromise`
 - `ComboCache` — memory-first with file fallback
-- `normalizeQuery(query)` — lowercase + trim + collapse whitespace → cache key
-- `buildCacheKey(query, capabilityId, params)` — exported for future post-match cache layer (not currently used by engine)
+- `normalizeQuery(query)` — lowercase + trim + strip punctuation + collapse whitespace → cache key. Punctuation stripped so `"show orders!"` and `"show orders"` share the same key
+- `buildCacheKey(query, capabilityId, params)` — semantic key using capability + params. Engine writes under both `normalizeQuery` and `buildCacheKey` — differently-phrased queries resolving to the same capability share cache entries
 
-Security: Only `public` capabilities are cached. Non-public (`user_owned`, `admin`) are never cached — prevents auth bypass where one user's cached match is served to another.
+Security: Only `public` capabilities are cached. Non-public (`user_owned`, `admin`) are never cached — prevents auth bypass where one user's cached match is served to another. Cache written only after successful resolution — failed resolutions do not poison the cache.
 
 Notes:
 - `FileCache` and `ComboCache` are single-instance only — concurrent writers will corrupt
+- `loadPromise` resets on rejection — failed loads allow retry rather than caching the rejection permanently
 - For multi-instance deployments, use a Redis adapter (planned v0.6)
 
 ---
 
 ### `src/learning.ts`
-Usage analytics and keyword index — now incremental.
+Usage analytics and keyword index — incremental, PII-safe.
 
 Key exports:
-- `LearningStore` interface — `record(entry)`, `getStats()`, `getTopCapabilities(limit)`, `getIndex()`
-- `FileLearningStore` — persists to `.capman/learning.json`, caps at 10,000 entries. Saves are debounced (5s) with synchronous flush on process exit
+- `LearningStore` interface — `record(entry)`, `getStats()`, `getTopCapabilities(limit)`, `getIndex()`, `destroy()`
+- `FileLearningStore` — persists to `.capman/learning.json`, caps at 10,000 entries. Saves debounced (5s) with synchronous flush on process exit via `flushSync()`
 - `MemoryLearningStore` — in-memory only, used in tests
 - `LearningIndex` — internal class shared by both stores. Maintains keyword index and stats counters incrementally. Eliminates ~80 lines of duplication
 
 `LearningEntry`:
-- `query`, `capabilityId`, `confidence`, `intent`, `extractedParams`
+- `query` — stored as tokenized keywords only, never raw text. PII (emails, names, IDs) stripped before persistence
+- `capabilityId`, `confidence`, `intent`, `extractedParams`
 - `resolvedVia: 'keyword' | 'llm' | 'cache'`
 - `timestamp`
 
 `KeywordStats` (from `getStats()`):
-- `index` — `{ word → { capabilityId → hitCount } }` — used by engine for learning boost
+- `index` — `{ word → { capabilityId → hitCount } }` — used by engine for learning boost. Returns `structuredClone` — callers cannot corrupt internal state
 - `totalQueries`, `llmQueries`, `cacheHits`, `outOfScope`
 
 Performance:
-- Index is maintained incrementally in `record()` — O(w) per entry where w = meaningful words
+- Index maintained incrementally in `record()` — O(w) per entry
 - `getStats()` returns cached counters — O(1), no rebuild
-- `getIndex()` returns live index — O(1)
-- Full rebuild only on pruning (when entries exceed 10,000 cap)
-- Stopwords filtered from index — same `STOPWORDS` set as `matcher.ts`
+- Prune uses `subtractFromIndex()` — O(pruned × w), not full rebuild
+
+Exit handling:
+- Process exit handlers registered once via module-level `registerExitHandlers()`
+- Handler references stored as `exitHandler`, `sigTermHandler`, `sigIntHandler`
+- Removed via `unregisterExitHandlers()` when `activeStores` is empty after `destroy()`
+- Does NOT call `process.exit()` — library must not hijack application shutdown
+
+`destroy()` — async, awaits final flush before removing from registry. On the `LearningStore` interface — callable through the interface type.
 
 ---
 
@@ -176,36 +204,40 @@ The recommended API — orchestrates matching, caching, learning, and tracing.
 Key exports:
 - `CapmanEngine` class
 - `EngineOptions` — all constructor options
-- `fuzzyMatch` — enable Fuse.js fuzzy matching (default: false)
-- `fuzzyThreshold` — Fuse.js threshold 0.0–1.0 (default: 0.4)
 - `EngineResult` — `{ match, resolution, resolvedVia, durationMs, trace }`
 
 ⚠️ **Concurrency:** `CapmanEngine` is not safe for sharing across concurrent async request handlers. The LLM rate limiter, circuit breaker, and learning index cache are instance-level mutable state. Create one engine per request in server deployments, or use `cheap` mode for shared instances.
 
 `CapmanEngine` methods:
 - `ask(query, overrides?)` → `EngineResult` — full pipeline: cache → match → boost → resolve → learn
-- `explain(query)` → `ExplainResult` — match + boost only, no execution, no cache/learning write
+- `explain(query)` → `ExplainResult` — match + boost only, no execution, no cache/learning write. Shares LLM quota with `ask()` — explain() counts against rate limit
+- `loadManifest(manifest)` — hot-reloads manifest without losing learning history, rate limiter state, or cache. Cache is cleared automatically. Rate limiter state intentionally preserved — LLM provider unchanged
 - `getStats()` → `KeywordStats | null`
 - `getTopCapabilities(limit?)` → `Array<{ id, hits }>`
 - `clearCache()`
-- `loadManifest(manifest)` — hot-reloads manifest, clears cache, preserves learning and rate limiter state
+
+`EngineOptions` highlights:
+- `fuzzyMatch` — enable Fuse.js fuzzy matching (default: false)
+- `fuzzyThreshold` — Fuse.js threshold 0.0–1.0 (default: 0.4)
+- `cacheTtlMs` — optional TTL for cache entries in ms (default: no expiry)
+- `maxLLMCallsPerMinute` — rate limit (default: 60). Set to 0 to disable LLM entirely
+- `llmCooldownMs`, `llmCircuitBreakerThreshold`, `llmCircuitBreakerResetMs`
 
 Matching pipeline in `ask()`:
-1. Cache check — return immediately on hit (public capabilities only)
-2. Match — `cheap` / `balanced` / `accurate` mode
-3. Privacy check — recorded in trace
-4. Learning boost — up to +15 points for historically matched capabilities (skipped in `cheap` mode, skipped if all candidates score 0)
-5. Cache set — stores post-boost result under normalized query key (public only)
+1. Cache check — return immediately on hit (public capabilities only). Re-extracts params fresh from current query
+2. Match — `cheap` / `balanced` / `accurate` mode dispatch via `_runMatch()`
+3. Privacy check — uses `checkPrivacy()` from `resolver.ts`. Correctly shows `'fail'` for blocked requests
+4. Learning boost — up to +15 points. Skipped in `cheap` mode, skipped if all candidates score 0 (no keyword signal), skipped if `resolvedVia === 'llm'` and `confidence > 80`
+5. Cache set — writes under both `normalizeQuery` and `buildCacheKey` (public only, after successful resolution only)
 6. Resolve — actual API call or nav
 7. Reasoning build — human-readable array
 8. Learning record — pre-boost result recorded to prevent feedback loop
 
-LLM rate limiting (all modes respect these):
-- `maxLLMCallsPerMinute` — sliding window (default: 60)
-- `llmCooldownMs` — minimum gap between calls (default: 0)
-- `llmCircuitBreakerThreshold` — failures before circuit opens (default: 3)
-- `llmCircuitBreakerResetMs` — circuit reset time (default: 60,000ms)
-- Parse failures (`LLM_PARSE_ERROR`) do NOT count toward circuit breaker — only network failures do
+LLM rate limiting:
+- `maxLLMCallsPerMinute` — slot reserved in `checkLLMAllowed()`, refunded in `recordLLMFailure()`
+- `maxLLMCallsPerMinute: 0` returns `'LLM disabled'` message immediately
+- Parse failures (`LLMParseError`) do NOT count toward circuit breaker — only network failures do
+- Rate-limiter state shared between `ask()` and `explain()`
 
 ---
 
@@ -214,13 +246,18 @@ OpenAPI/Swagger → capman config converter.
 
 Key exports:
 - `parseOpenAPI(specPathOrUrl)` → `ParseResult`
-  - Accepts local file path or HTTP URL
-  - Parses JSON natively; YAML requires `js-yaml` installed
+  - Accepts local file path or HTTP URL (10s timeout via `AbortController`)
+  - Parses JSON natively; YAML requires `js-yaml` (distinguished via `err.code === 'MODULE_NOT_FOUND'`)
   - Converts every path+method into a `Capability`
   - Infers privacy from security schemes and tags
-  - Extracts path/query/body params
+  - Extracts path/query/body params — all mapped to `'user_query'` source
   - Generates examples from operation summaries
 
+Privacy inference:
+- Admin classification uses word-boundary regex `\b(admin|administrator|backoffice|back-office|internal|superuser)\b` — `'manage'` alone no longer triggers admin. Operations like `manageWishlist`, `fileManager` correctly classified as non-admin
+- Swagger 2.x `schemes` array respected — prefers `https` over `http` when both declared
+- Missing server URL emits `logger.warn` instead of silently using placeholder
+
 `ParseResult`: `{ config, stats: { total, skipped, warnings } }`
 
 Supported: OpenAPI 3.x, Swagger 2.x (JSON or YAML)
@@ -234,7 +271,7 @@ Key exports:
 - `logger` — singleton with `debug()`, `info()`, `warn()`, `error()`
 - `setLogLevel(level)` — `'silent' | 'error' | 'warn' | 'info' | 'debug'`
 
-Note: The manifest version compatibility warning uses `console.warn` directly (not `logger.warn`) so it is always visible regardless of log level.
+Note: The manifest version compatibility warning uses `console.warn` directly (not `logger.warn`) so it is always visible regardless of log level. Raw query text never appears at info level — only query length logged at info, full query at debug.
 
 ---
 
@@ -245,7 +282,7 @@ Notable:
 - `ask(query, manifest, options?)` — convenience function, delegates to `CapmanEngine`
   - Marked `@deprecated` — use `CapmanEngine` directly for full features
 - `MatchMode` — `'cheap' | 'balanced' | 'accurate'`
-- `extractParams`, `resolverToIntent`, `STOPWORDS` — exported for advanced use cases
+- `extractParams`, `resolverToIntent`, `STOPWORDS`, `LLMParseError` — exported for advanced use cases
 
 ---
 
@@ -255,22 +292,24 @@ Notable:
 Entry point only (~20 lines). Routes `command` to the correct module.
 
 ### `bin/lib/shared.js`
-Exports: `args`, `command`, `flags`, `getFlag`, `c`, `log`, `header`, `posArgs`, `requireSrc`
+Exports: `args`, `command`, `flags`, `posArgs`, `getFlag`, `c`, `log`, `header`, `requireSrc`
 
-`getFlag(name)` — exits with error if flag is present but has no value (e.g. `--from` with no path).
-`posArgs` — positional arguments after POSIX `--` sentinel. Allows queries starting with `--` to be passed without flag interpretation
+- `getFlag(name)` — exits with error if flag is present but has no value
+- `posArgs` — positional arguments after POSIX `--` sentinel. Allows queries starting with `--` to be passed without flag interpretation (e.g. `capman run -- "--help me find orders"`)
 
 ### `bin/lib/cmd-generate.js`
 Three generation paths: `--from` (OpenAPI), `--ai` (LLM-assisted), manual.
 Output paths validated via `safeOutputPath()` — rejects traversal outside working directory.
 Contains `buildAIPrompt()` and `callLLM()`.
+- All three providers (Anthropic, OpenAI, OpenRouter) read response via `res.text()` before `res.ok` check — prevents JSON parse errors masking real API errors
+- Empty string API keys rejected — `.trim() ||` used instead of `??`
 
 ### `bin/lib/cmd-init.js` — creates `capman.config.js`
 ### `bin/lib/cmd-validate.js` — validates `manifest.json`
 ### `bin/lib/cmd-inspect.js` — prints all capabilities
 ### `bin/lib/cmd-demo.js` — live demo with hardcoded e-commerce manifest
-### `bin/lib/cmd-run.js` — runs a query, `--debug` shows all candidates
-### `bin/lib/cmd-explain.js` — runs `engine.explain()` and prints full breakdown
+### `bin/lib/cmd-run.js` — runs a query, `--debug` shows all candidates. Supports `--` sentinel via `posArgs`
+### `bin/lib/cmd-explain.js` — runs `engine.explain()` and prints full breakdown. Supports `--` sentinel via `posArgs`
 ### `bin/lib/cmd-help.js` — usage and command list
 
 ---
@@ -278,16 +317,16 @@ Contains `buildAIPrompt()` and `callLLM()`.
 ## tests/
 
 ### `tests/matcher.test.ts` — 17 tests
-Keyword scoring, OOS detection, param extraction, LLM edge cases (hallucinated ID, undefined reasoning), example scoring quality-over-quantity (Math.max)
+Keyword scoring, OOS detection, param extraction, LLM edge cases (hallucinated ID, undefined reasoning), example quality-over-quantity (Math.max)
 
 ### `tests/resolver.test.ts` — 27 tests
-API/nav/hybrid resolvers, privacy enforcement, session injection, null params, nav open redirect, API path param traversal rejection, multi-endpoint session param isolation, LRU cache eviction
+API/nav/hybrid resolvers, privacy enforcement, session injection, null params, nav open redirect, API path traversal rejection, multi-endpoint session param isolation, LRU eviction, nav params with dots/colons allowed
 
 ### `tests/engine.test.ts` — 44 tests
 `ask()`, `explain()`, caching, learning, matching modes, trace, rate limiting, manifest version check, learning boost, query validation (TypeError/RangeError guards), LRU eviction, fuzzy matching (typos, cheap mode bypass, default disabled, strict threshold), `loadManifest()` hot-reload (cache cleared, learning preserved)
 
-### `tests/parser.test.ts` — 9 tests
-OpenAPI capability extraction, privacy inference, param extraction, base URL, error handling
+### `tests/parser.test.ts` — 11 tests
+OpenAPI capability extraction, privacy inference, param extraction, base URL, error handling, manage/admin false-positive regression
 
 ---
 
@@ -306,9 +345,9 @@ Prebuild script. Reads `version` from `package.json` and writes `src/version.ts`
 | `tsconfig.esm.json` | ESM build → `dist/esm/` with `.d.ts` |
 | `package.json` | Version, exports map, scripts, dependencies |
 | `.github/workflows/ci.yml` | Build + test + verify both dist outputs on every push |
+| `.gitignore` | Includes `.capman/` — cache and learning files must never be committed |
 | `CHANGELOG.md` | All notable changes per version |
 | `CODEBASE.md` | This file |
-| `ROADMAP_v0.5.0.md` | Prioritized fix and feature roadmap |
 
 ---
 
@@ -319,19 +358,25 @@ Developer writes capman.config.js
          ↓
   capman generate
          ↓
-  generator.ts → manifest.json
+  generator.ts → manifest.json (path-guarded write)
          ↓
   CapmanEngine.ask("user query")
          ↓
-  cache.ts       → cache hit? return immediately (public only)
+  cache.ts       → cache hit? re-extract params fresh → return
+         ↓
+  matcher.ts     → score all capabilities (Set-based O(n))
+                 → optional Fuse.js fuzzy pass (single index)
+                 → pick winner
+         ↓
+  checkPrivacy() → privacy trace step (pass or fail)
          ↓
-  matcher.ts     → score all capabilities → pick winner
+  learning.ts    → apply boost (+0 to +15) — skipped for high-confidence LLM
          ↓
-  learning.ts    → apply boost (+0 to +15) based on keyword history
+  cache.ts       → write under normalizeQuery + buildCacheKey (public, on success only)
          ↓
   resolver.ts    → enforce privacy → call API or navigate
          ↓
-  learning.ts    → record pre-boost match result
+  learning.ts    → record pre-boost match result (tokenized, PII-stripped)
          ↓
   EngineResult   → { match, resolution, trace, resolvedVia }
 ```

package/README.md

@@ -227,6 +227,25 @@ const engine = new CapmanEngine({
 })
 ```
 
+### Fuzzy Matching
+
+Enable opt-in fuzzy matching to catch typos and slight paraphrases:
+
+```typescript
+const engine = new CapmanEngine({
+  manifest,
+  mode: 'balanced',
+  fuzzyMatch: true,       // enable Fuse.js fuzzy matching
+  fuzzyThreshold: 0.4,   // 0.0 = exact only, 1.0 = match anything (default: 0.4)
+})
+
+// Now catches typos: "Shwo me artciles" → matches "Show me articles"
+// Also catches near-matches Fuse.js considers similar
+```
+
+Fuzzy matching never runs in `cheap` mode. It is additive — fuzzy can only
+help a capability reach the confidence threshold, never hurt it.
+
 ---
 
 ## Caching + Learning
@@ -249,6 +268,28 @@ const top = await engine.getTopCapabilities(3)
 
 ---
 
+### Hot-reloading manifests
+
+Swap the manifest without creating a new engine instance — preserves cache,
+learning history, and rate limiter state:
+
+```typescript
+const newManifest = generate(updatedConfig)
+await engine.loadManifest(newManifest)
+// Cache is cleared automatically — stale entries from old manifest are gone
+```
+
+### Cleaning up
+
+Call `destroy()` on file-backed stores when done to flush pending data and
+deregister process exit handlers:
+
+```typescript
+await engine.learning?.destroy()
+```
+
+---
+
 ## Privacy + Auth
 
 Privacy scope is enforced **per capability**, before resolution happens:
@@ -320,8 +361,6 @@ const result = await engine.ask('show my orders', {
 |---|---|
 | `user_query` | Extracted from the user's query |
 | `session` | Injected from `auth.userId` automatically |
-| `context` | Provided by the caller |
-| `static` | Fixed value, never changes |
 
 ---
 
@@ -337,8 +376,10 @@ const result = await engine.ask('show my orders', {
 **Current limits:**
 - Real-time infra status (is the server down?)
 - UI-only state with no API backing
-- Very ambiguous queries — use `mode: 'accurate'` with an LLM
-- Multi-instance deployments need Redis adapter (planned for v0.5)
+- Very ambiguous queries with no keyword signal — use `mode: 'accurate'` with an LLM, or enable `fuzzyMatch: true`
+- Multi-instance deployments: `FileCache` and `FileLearningStore` are single-instance only — concurrent writers will corrupt the file. Use separate instances per process or a shared Redis adapter
+- `FileLearningStore` saves are debounced — up to 5s of learning data could be lost on `SIGKILL` (not SIGTERM/SIGINT which are handled)
+- Parallel multi-endpoint capabilities: if one endpoint fails, side effects from successful endpoints cannot be rolled back. Use single-endpoint capabilities for operations requiring ordering or rollback
 
 ---