agentfootprint 6.44.0 → 7.0.0

package/dist/esm/lib/rag/defineRAG.d.ts

@@ -0,0 +1,139 @@
+/**
+ * defineRAG — sugar factory for retrieval-augmented generation.
+ *
+ * RAG is a context-engineering flavor: embed the user's question,
+ * retrieve top-K semantically similar chunks from a vector store,
+ * inject those chunks into the messages slot of the next LLM call.
+ * It's the same plumbing as `defineMemory({ type: SEMANTIC,
+ * strategy: TOP_K })` — the rename is for intent + ergonomics.
+ *
+ *   defineMemory ─┬─► EPISODIC   (raw conversation)
+ *                 ├─► SEMANTIC   (extracted facts / RAG chunks)
+ *                 ├─► NARRATIVE  (beats / summaries)
+ *                 └─► CAUSAL     (footprintjs decision snapshots)
+ *
+ *   defineRAG    ─►  SEMANTIC + TOP_K with RAG-specific defaults
+ *                    (asRole='user', threshold=0.7, no LLM-extract)
+ *
+ * Pattern: Composition over duplication — defineRAG returns a
+ *          MemoryDefinition produced by defineMemory. No new engine
+ *          code, no new slot subflow, no new event type.
+ *
+ * Role:    Layer-3 context-engineering primitive. Lives next to
+ *          defineSkill / defineSteering / defineInstruction / defineFact
+ *          but resolves to a memory subflow rather than an Injection
+ *          (RAG content is computed at runtime via async retrieval —
+ *          can't fit the synchronous Injection.inject shape).
+ *
+ * Emits:   Indirectly — the underlying memory pipeline emits
+ *          `agentfootprint.context.injected` when retrieved chunks
+ *          land in the messages slot.
+ *
+ * @see ./indexDocuments.ts  for the seeding helper
+ * @see ../../memory/define.ts  for the underlying factory
+ *
+ * @example  Basic usage
+ * ```ts
+ * import { *   Agent, defineRAG, indexDocuments, * } from 'agentfootprint'
+import { InMemoryStore, mockEmbedder } from 'agentfootprint/memory'
+import { mock } from 'agentfootprint/llm-providers';
+ *
+ * const embedder = mockEmbedder();
+ * const store = new InMemoryStore();
+ *
+ * // Seed the store once at startup
+ * await indexDocuments(store, embedder, [
+ *   { id: 'doc1', content: 'Refunds are processed within 3 business days.' },
+ *   { id: 'doc2', content: 'Pro plan costs $20/month.' },
+ * ]);
+ *
+ * const docs = defineRAG({
+ *   id: 'product-docs',
+ *   description: 'Retrieve product documentation chunks',
+ *   store,
+ *   embedder,
+ *   topK: 3,
+ *   threshold: 0.6,
+ * });
+ *
+ * const agent = Agent.create({ provider: mock({ reply: 'ok' }), model: 'mock' })
+ *   .rag(docs)
+ *   .build();
+ * ```
+ */
+import type { ContextRole } from '../../events/types.js';
+import type { Embedder } from '../../memory/embedding/index.js';
+import type { MemoryStore } from '../../memory/store/index.js';
+import type { MemoryDefinition } from '../../memory/define.types.js';
+export interface DefineRAGOptions {
+    /** Stable id. Becomes the scope-key suffix and the Lens label. */
+    readonly id: string;
+    /**
+     * Human-readable description. Surfaces in narrative + Lens hover.
+     * Recommend describing the *corpus* (e.g., "Product documentation
+     * chunks indexed weekly from docs.example.com").
+     */
+    readonly description?: string;
+    /**
+     * Vector-capable store containing the indexed corpus. Must implement
+     * `search()`. Use `indexDocuments(store, embedder, docs)` at startup
+     * to populate it. Ships with `InMemoryStore` for dev/tests; swap to
+     * `pgvector` / Pinecone / Qdrant adapters in production.
+     */
+    readonly store: MemoryStore;
+    /**
+     * Embedder used for the read-side query. Pass the SAME embedder
+     * instance (or one with the same `name`) that was used for indexing
+     * — cross-model similarity scores are not comparable.
+     */
+    readonly embedder: Embedder;
+    /**
+     * Stable id of the embedder. Stored on entries during indexing
+     * (via `indexDocuments`) and filtered at search time so a later
+     * embedder swap doesn't pollute results.
+     */
+    readonly embedderId?: string;
+    /**
+     * Top-K chunks to retrieve per turn. Default 3 (balanced —
+     * defends against lost-in-the-middle while giving multiple
+     * perspectives). Increase for richer context, decrease for cost.
+     */
+    readonly topK?: number;
+    /**
+     * Minimum cosine similarity to inject. **Strict** — when no chunk
+     * meets the threshold, NO injection happens (no fallback that would
+     * pollute the prompt with weak matches). Default 0.7.
+     *
+     * Tuning note: 0.7 is a high bar for some embedders. Sentence-BERT
+     * relatives (`all-MiniLM-L6-v2`, etc.) often score 0.4–0.6 even on
+     * relevant chunks. If you see frequent zero-result silent skips,
+     * lower to ~0.5 and observe the `agentfootprint.context.injected`
+     * stream. OpenAI `text-embedding-3-*` and Cohere embed-v3 typically
+     * sit comfortably with 0.7.
+     */
+    readonly threshold?: number;
+    /**
+     * Role to use when injecting retrieved chunks into the messages
+     * slot. Default `'user'`.
+     *
+     * Why `'user'`: in tool-using ReAct loops, retrieved chunks
+     * conceptually "augment what the user asked." Anthropic's tool-use
+     * cookbook and OpenAI's RAG cookbook both show retrieved context
+     * inside user-turn messages.
+     *
+     * Use `'system'` for authoritative reference docs that should
+     * outweigh user instruction (policy / compliance / brand-voice
+     * corpora). Use `'assistant'` only if you've persisted prior agent
+     * turns as context — rare.
+     */
+    readonly asRole?: ContextRole;
+}
+/**
+ * Build a RAG context-engineering definition. The returned
+ * `MemoryDefinition` is registered on the Agent via `.rag(definition)`
+ * (or, equivalently, `.memory(definition)` — same plumbing).
+ *
+ * @throws when `store` does not implement `search()`. RAG requires a
+ *         vector-capable adapter.
+ */
+export declare function defineRAG(opts: DefineRAGOptions): MemoryDefinition;

package/dist/esm/lib/rag/defineRAG.js

@@ -34,9 +34,9 @@
  *
  * @example  Basic usage
  * ```ts
- * import {
- *   Agent, defineRAG, indexDocuments, InMemoryStore, mockEmbedder, mock,
- * } from 'agentfootprint';
+ * import { *   Agent, defineRAG, indexDocuments, * } from 'agentfootprint'
+import { InMemoryStore, mockEmbedder } from 'agentfootprint/memory'
+import { mock } from 'agentfootprint/llm-providers';
  *
  * const embedder = mockEmbedder();
  * const store = new InMemoryStore();

package/dist/esm/lib/rag/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * RAG — retrieval-augmented generation as a context-engineering
+ * flavor. ONE factory + ONE seeding helper. Composes over the memory
+ * subsystem (semantic + top-K + strict threshold).
+ */
+export { defineRAG, type DefineRAGOptions } from './defineRAG.js';
+export { indexDocuments, type IndexDocumentsOptions, type RagDocument } from './indexDocuments.js';

package/dist/esm/lib/rag/indexDocuments.d.ts

@@ -0,0 +1,106 @@
+/**
+ * indexDocuments — seed a vector-capable MemoryStore with documents.
+ *
+ * Embeds each document, builds a `MemoryEntry<{content, metadata?}>`,
+ * batches into `store.putMany()`. Used at application startup to
+ * populate a RAG store before the first agent run.
+ *
+ * Pattern: Bulk-write helper. Not a flowchart stage — it runs once
+ *          at boot, not per-iteration.
+ * Role:    Layer-3 RAG pipeline starter. Pairs with `defineRAG()`
+ *          which only does the read side.
+ * Emits:   N/A — startup-time batch write, not part of the agent run.
+ *
+ * @example
+ * ```ts
+ * import { Agent, indexDocuments, defineRAG } from 'agentfootprint'
+import { InMemoryStore, mockEmbedder } from 'agentfootprint/memory';
+ *
+ * const store = new InMemoryStore();
+ * const embedder = mockEmbedder();
+ *
+ * await indexDocuments(store, embedder, [
+ *   { id: 'doc1', content: 'Refunds processed within 3 business days.' },
+ *   { id: 'doc2', content: 'Pro plan: $20/mo, includes priority support.', metadata: { tier: 'pro' } },
+ *   { id: 'doc3', content: 'Free plan: limited to 100 calls/month.' },
+ * ]);
+ *
+ * const docs = defineRAG({ id: 'product-docs', store, embedder });
+ * const agent = Agent.create({ provider }).rag(docs).build();
+ * ```
+ */
+import type { Embedder } from '../../memory/embedding/index.js';
+import type { MemoryStore } from '../../memory/store/index.js';
+import type { MemoryIdentity } from '../../memory/identity/index.js';
+/** A document to index. `id` must be unique within the store + identity. */
+export interface RagDocument {
+    readonly id: string;
+    readonly content: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface IndexDocumentsOptions {
+    /**
+     * Identity scope to write under. Default: a single shared
+     * `{ conversationId: '_global' }` namespace, suitable for app-wide
+     * corpora.
+     *
+     * **Multi-tenant footgun:** the read side (`agent.run({ identity })`)
+     * queries within whichever identity is passed at request time.
+     * If you index here under `_global` but query under
+     * `{ tenant: 'acme' }`, you'll get ZERO results — silently. Either:
+     *   1. Index every document under each tenant's identity (duplicated
+     *      storage, but isolated), or
+     *   2. Index under `_global` AND query under `_global` (shared
+     *      corpus across tenants — fine for product docs, NOT for
+     *      tenant-private data), or
+     *   3. Use a vector store adapter that supports multi-namespace
+     *      reads at query time (Pinecone, Qdrant — outside this helper's
+     *      scope).
+     */
+    readonly identity?: MemoryIdentity;
+    /**
+     * Stable id of the embedder. Stored on each entry so a future
+     * embedder swap doesn't silently mix similarity scores. Default:
+     * `'default-embedder'` — pass an explicit id when you may rotate
+     * embedders.
+     */
+    readonly embedderId?: string;
+    /**
+     * Optional tier tag to attach to indexed entries (`'hot'` /
+     * `'warm'` / `'cold'`). Useful when read-side `defineRAG` should
+     * filter to a subset of the corpus.
+     */
+    readonly tier?: 'hot' | 'warm' | 'cold';
+    /**
+     * Optional TTL in milliseconds from indexing time. Useful for
+     * compliance retention windows (e.g., re-index quarterly).
+     */
+    readonly ttlMs?: number;
+    /**
+     * Optional abort signal — embedders making network calls thread
+     * this through to abort batch indexing on shutdown / timeout.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * Max number of concurrent embed calls when the embedder doesn't
+     * implement `embedBatch`. Default `8`. Without this cap, a 10K-doc
+     * corpus would fire 10K parallel embed calls and trigger rate limits.
+     * Ignored when `embedBatch` is available (the embedder controls
+     * its own batching).
+     */
+    readonly maxConcurrency?: number;
+}
+/**
+ * Embed + persist documents. Returns the count actually indexed
+ * (skips duplicates if the store rejects them). Throws on embedder
+ * failure or store error — fail loud at startup is desirable.
+ *
+ * **Re-indexing semantics:** entries are written with `version: 1` and
+ * `putMany` (most adapters: last-write-wins). Re-running this helper
+ * after the store has been mutated by other writers may stomp their
+ * versions. For idempotent corpus refresh, either delete-then-index
+ * or use a custom upsert via `store.putIfVersion()` per document. A
+ * first-class `mode: 'upsert' | 'replace'` API is planned for a
+ * future release.
+ */
+export declare function indexDocuments(store: MemoryStore, embedder: Embedder, documents: readonly RagDocument[], options?: IndexDocumentsOptions): Promise<number>;

package/dist/esm/lib/rag/indexDocuments.js

@@ -13,7 +13,8 @@
  *
  * @example
  * ```ts
- * import { Agent, InMemoryStore, mockEmbedder, indexDocuments, defineRAG } from 'agentfootprint';
+ * import { Agent, indexDocuments, defineRAG } from 'agentfootprint'
+import { InMemoryStore, mockEmbedder } from 'agentfootprint/memory';
  *
  * const store = new InMemoryStore();
  * const embedder = mockEmbedder();

package/dist/esm/lib/rag/indexDocuments.js.map

@@ -1 +1 @@
-{"version":3,"file":"indexDocuments.js","sourceRoot":"","sources":["../../../../src/lib/rag/indexDocuments.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"indexDocuments.js","sourceRoot":"","sources":["../../../../src/lib/rag/indexDocuments.ts"],"names":[],"mappings":"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"}

package/dist/esm/lib/tool-lint/analyze.d.ts

@@ -0,0 +1,83 @@
+/**
+ * analyzeToolCatalog — the tool-catalog confusability lint
+ * (RFC-002 block C1, the adoption front door).
+ *
+ * Pattern: policy layer over `pairwiseSimilarity` (influence-core) — the
+ *          geometry is computed there; thresholds, verdicts, hints and
+ *          the structural rule pack live here. Everything is consumer-
+ *          injectable with our defaults (the plug-and-play meta-pattern).
+ * Role:    `src/lib/tool-lint/`. ZERO stack buy-in — plain
+ *          `{ name, description?, inputSchema? }[]` in, report out.
+ *          `catalogFromTools` adapts the library's own `Tool[]`;
+ *          `coerceCatalog` (cli.ts) normalizes OpenAI/Anthropic/MCP
+ *          shapes.
+ *
+ * ## What is embedded (and why)
+ *
+ * `confusabilityText(tool)` = tokenized name + ': ' + description. The
+ * model differentiates tools by name AND description together, so two
+ * tools with near-identical names and overlapping descriptions ARE the
+ * confusability case (`get_fcns_database` vs `influx_get_fcns_database`)
+ * — embedding only the prose would miss the name signal.
+ *
+ * ## Calibration (RFC-002 §3 — read this before trusting verdicts)
+ *
+ * Absolute cosine ranges are PER-EMBEDDER. The default threshold (0.85)
+ * is a starting point for real sentence embedders. The test/demo
+ * `mockEmbedder` (character-frequency) compresses unrelated prose into
+ * ~0.85–0.97 — with it, use `MOCK_EMBEDDER_CALIBRATION` and trust only
+ * the RELATIVE ordering in `report.similarity.ranked` (the acceptance
+ * fixtures assert ordering, never absolute scores).
+ */
+import type { Tool } from '../../core/tools.js';
+import type { AnalyzeToolCatalogOptions, CatalogTool, ToolCatalogReport } from './types.js';
+/** Default `confusabilityThreshold` — a starting point for REAL sentence
+ *  embedders (unrelated tool descriptions typically land 0.3–0.7).
+ *  Calibrate per embedder; meaningless for the mock (see below). */
+export declare const DEFAULT_CONFUSABILITY_THRESHOLD = 0.85;
+/** Default `watchBand` below the threshold. */
+export declare const DEFAULT_WATCH_BAND = 0.05;
+/**
+ * Threshold/band calibrated for the char-frequency `mockEmbedder` on
+ * realistic tool prose (seed corpus: the Neo SAN catalog). The mock
+ * compresses unrelated descriptions into ~0.85–0.97 cosine, so expect
+ * false positives even at 0.94 — with the mock, the RELATIVE ordering
+ * of `report.similarity.ranked` is the trustworthy signal; absolute
+ * verdicts are only honest with a real embedder + per-embedder
+ * calibration.
+ */
+export declare const MOCK_EMBEDDER_CALIBRATION: Readonly<{
+    confusabilityThreshold: 0.94;
+    watchBand: 0.02;
+}>;
+/**
+ * Adapt the library's `Tool[]` (from `defineTool` / `Agent.tool`) to the
+ * lint's plain catalog shape. Trivial on purpose: `Tool.schema` already
+ * IS `{ name, description, inputSchema }`.
+ */
+export declare function catalogFromTools(tools: readonly Tool[]): readonly CatalogTool[];
+/**
+ * The text the confusability analysis embeds for one tool: the name with
+ * `_`/`-`/camelCase boundaries opened into words, then the description.
+ * Exported so consumers can reproduce or replace the construction.
+ */
+export declare function confusabilityText(tool: CatalogTool): string;
+/**
+ * Lint a tool catalog: pairwise confusability over what the model reads
+ * (when an embedder is supplied) + the structural rule pack. Returns a
+ * report whose `ok` is the CI gate.
+ *
+ * Duplicate tool names are themselves reported as structural errors
+ * (rule `duplicate-name`, built-in precondition — a catalog where two
+ * tools share a name is broken before any similarity question); the
+ * duplicates are dropped from the similarity analysis (first one wins).
+ */
+export declare function analyzeToolCatalog(tools: readonly CatalogTool[], options?: AnalyzeToolCatalogOptions): Promise<ToolCatalogReport>;
+/**
+ * Suggest the DIFFERENTIATING AXIS for a flagged pair. Heuristic: when
+ * the names are near-twins (≤2 distinct tokens), the qualifier IS the
+ * axis — the descriptions must say when to choose each variant. When the
+ * names differ, surface the few description terms each tool does NOT
+ * share, as the place to anchor an explicit choice condition.
+ */
+export declare function differentiationHint(a: CatalogTool, b: CatalogTool): string;

package/dist/esm/lib/tool-lint/cli.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Tool-lint CLI core (RFC-002 block C3 — the CI gate).
+ *
+ * Pattern: humble shell — `bin/agentfootprint-lint-tools.mjs` is a
+ *          3-line wrapper; ALL behavior (arg parsing, catalog coercion,
+ *          report, exit code) lives here so it is unit-testable without
+ *          spawning a process.
+ * Role:    `src/lib/tool-lint/`. Reads ONE JSON file of tools, prints a
+ *          report, returns the process exit code:
+ *            0 — report.ok
+ *            1 — findings failed the gate (!ok)
+ *            2 — usage / input error (bad flags, unreadable file,
+ *                unrecognized JSON shape)
+ *
+ * ## Embedder & gating honesty
+ *
+ * The CLI has no way to receive a consumer embedder, so it uses the
+ * built-in deterministic mock (char-frequency, offline, dependency-free)
+ * for the similarity RANKING — and, by default, does NOT gate on it:
+ * without `--threshold`, similarity is report-only (relative ordering +
+ * watch hints) and the exit code reflects structural findings alone.
+ * Pass `--threshold` to make confusable pairs fail the gate — you own
+ * the calibration at that point (start from
+ * `MOCK_EMBEDDER_CALIBRATION.confusabilityThreshold` = 0.94). For real
+ * embedder gating, use `analyzeToolCatalog` from
+ * `agentfootprint/observe` in a small script instead.
+ */
+import type { CatalogTool } from './types.js';
+export interface ToolLintCliIO {
+    readonly stdout: (line: string) => void;
+    readonly stderr: (line: string) => void;
+}
+/**
+ * Normalize any of the recognized tool-list JSON shapes to the lint's
+ * plain catalog. Throws (with a shape description) on unrecognized
+ * input — the CLI maps that to exit code 2.
+ */
+export declare function coerceCatalog(json: unknown): readonly CatalogTool[];
+/**
+ * Run the lint CLI. Returns the exit code (never calls `process.exit` —
+ * the bin wrapper assigns it to `process.exitCode`).
+ */
+export declare function runToolLintCli(argv: readonly string[], io?: ToolLintCliIO): Promise<number>;

package/dist/esm/lib/tool-lint/format.d.ts

@@ -0,0 +1,18 @@
+/**
+ * formatToolCatalogReport — human-readable rendering of a lint report.
+ *
+ * Pattern: pure presenter. One report → one string; used verbatim by the
+ *          CLI (`agentfootprint-lint-tools`) and the examples so output
+ *          stays byte-identical across surfaces.
+ * Role:    `src/lib/tool-lint/` leaf. No I/O.
+ */
+import type { ToolCatalogReport } from './types.js';
+export interface FormatReportOptions {
+    /** How many ranked pairs to show in the relative-ordering section.
+     *  Default 10. 0 hides the section. */
+    readonly topPairs?: number;
+    /** How many WATCH pairs to print before eliding the rest (the report
+     *  object always carries all of them). Default 10. */
+    readonly maxWatch?: number;
+}
+export declare function formatToolCatalogReport(report: ToolCatalogReport, options?: FormatReportOptions): string;

package/dist/esm/lib/tool-lint/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * tool-lint — the tool-catalog confusability lint (RFC-002 tier 1,
+ * blocks C1–C3).
+ *
+ * Build-time, CI-gateable, framework-agnostic: a plain
+ * `{ name, description?, inputSchema? }[]` in (any OpenAI / Anthropic /
+ * LangChain / MCP tool list coerces to it), a report with a CI-gateable
+ * `ok` out. The embedding geometry comes from influence-core
+ * (`pairwiseSimilarity`); this module is the policy layer — thresholds,
+ * verdicts, hints, and the pluggable structural rule pack.
+ *
+ * Surfaces:
+ *   - `analyzeToolCatalog(tools, opts)` — the API (C1)
+ *   - `defaultStructuralRules` + rule factories — the rule pack (C2)
+ *   - `runToolLintCli` / bin `agentfootprint-lint-tools` — the gate (C3)
+ *
+ * Front-door guide: docs/guides/tool-catalog-lint.md
+ */
+export type { AnalyzeToolCatalogOptions, CatalogTool, ConfusablePairFinding, LintRule, LintSeverity, PairVerdict, SimilarityReport, StructuralFinding, ToolCatalogReport, } from './types.js';
+export { analyzeToolCatalog, catalogFromTools, confusabilityText, differentiationHint, DEFAULT_CONFUSABILITY_THRESHOLD, DEFAULT_WATCH_BAND, MOCK_EMBEDDER_CALIBRATION, } from './analyze.js';
+export { defaultStructuralRules, descriptionRule, enumInProseRule, optionalParamRule, saysWhatNotWhenRule, DEFAULT_OMISSION_CUES, DEFAULT_WHEN_CUES, type DescriptionRuleOptions, type OptionalParamRuleOptions, type SaysWhatNotWhenRuleOptions, } from './rules.js';
+export { formatToolCatalogReport, type FormatReportOptions } from './format.js';
+export { coerceCatalog, runToolLintCli, type ToolLintCliIO } from './cli.js';

package/dist/esm/lib/tool-lint/rules.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Structural lint rules (RFC-002 block C2) — the PLUGGABLE RULE PACK.
+ *
+ * Pattern: Strategy list — each rule is a plain `{ id, check }` object;
+ *          `defaultStructuralRules` is OUR pack, and consumers add /
+ *          remove / replace freely via `AnalyzeToolCatalogOptions.rules`.
+ *          Parameterizable rules ship as FACTORIES (`descriptionRule`,
+ *          `saysWhatNotWhenRule`, …) returning a configured `LintRule`.
+ * Role:    `src/lib/tool-lint/` leaf. Pure functions over `CatalogTool`;
+ *          no embedder, no I/O.
+ *
+ * Every rule encodes a FIELD FINDING from real catalogs (the Neo SAN
+ * triage agent's 29-tool catalog was the seed corpus):
+ *
+ *   1. description-missing-or-short — the model can only guess from a name.
+ *   2. says-what-not-when — describes WHAT the tool returns but gives the
+ *      model no cue for WHEN to pick it over a sibling (the #1 cause of
+ *      twin-tool confusion: 'get_fcns_database' vs 'influx_get_fcns_database').
+ *   3. enum-in-prose — string params whose legal values are listed in prose
+ *      ("avg_iops | peak_iops | mbps") instead of a JSON-Schema `enum` the
+ *      model (and validators, see #9 tool-args validation) can act on.
+ *   4. optional-param-undocumented — optional params whose omission has
+ *      meaning (fabric-wide sweep vs one switch) but whose schema never
+ *      says so; the model can't reason about leaving them out.
+ *
+ * Honest claim: these are token/regex HEURISTICS. They flag review
+ * prompts, not certainties — expect (rare) false positives and tune via
+ * the factory options instead of deleting the rule.
+ */
+import type { LintRule } from './types.js';
+export interface DescriptionRuleOptions {
+    /** Descriptions shorter than this (in chars) get a `warn`. Default 40. */
+    readonly minChars?: number;
+}
+/**
+ * Missing description → `error` (the model can only guess from the
+ * name). Present but shorter than `minChars` → `warn` (too short to
+ * differentiate from siblings).
+ */
+export declare function descriptionRule(options?: DescriptionRuleOptions): LintRule;
+/** RFC-002 C2 heuristic cue list — temporal/conditional words whose
+ *  presence suggests the description says WHEN to use the tool. */
+export declare const DEFAULT_WHEN_CUES: readonly string[];
+export interface SaysWhatNotWhenRuleOptions {
+    /** Cue tokens (whole-word, case-insensitive). Default `DEFAULT_WHEN_CUES`. */
+    readonly cueTokens?: readonly string[];
+}
+/**
+ * A description with NO temporal/conditional cue token usually describes
+ * WHAT the tool returns but never WHEN to pick it — the #1 cause of
+ * twin-tool confusion. Heuristic by design: tune `cueTokens` rather than
+ * dropping the rule. Skips tools with no description (rule 1's finding).
+ */
+export declare function saysWhatNotWhenRule(options?: SaysWhatNotWhenRuleOptions): LintRule;
+/**
+ * A string param whose description enumerates its legal values in prose
+ * (pipe-separated literals, or comma lists behind "one of"/"allowed
+ * values") should declare a JSON-Schema `enum` instead — the model picks
+ * reliably from enums, and arg validators (#9) can enforce them. The
+ * field case: Neo's `influx_get_port_ranking.metric` =
+ * `"avg_iops | peak_iops | mbps"`.
+ */
+export declare function enumInProseRule(): LintRule;
+/** Words that signal the description DOES say what omission means. */
+export declare const DEFAULT_OMISSION_CUES: readonly string[];
+export interface OptionalParamRuleOptions {
+    /** Cue tokens that satisfy the rule. Default `DEFAULT_OMISSION_CUES`. */
+    readonly omissionCues?: readonly string[];
+}
+/**
+ * An optional param's omission usually MEANS something (Neo:
+ * `influx_get_interface_counters` without `switch_name` = fabric-wide
+ * sweep) — but the model can only reason about leaving a param out if
+ * the description says so. No description at all, or one with no
+ * omission cue, gets a `warn`.
+ */
+export declare function optionalParamRule(options?: OptionalParamRuleOptions): LintRule;
+/**
+ * OUR rule pack, built with default options. Compose your own:
+ *
+ *   rules: [...defaultStructuralRules, myRule]                 // add
+ *   rules: defaultStructuralRules.filter(r => r.id !== '…')    // remove
+ *   rules: [descriptionRule({ minChars: 80 }), …]              // re-tune
+ */
+export declare const defaultStructuralRules: readonly LintRule[];