@tangle-network/agent-app 0.45.53 → 0.45.55

package/dist/knowledge-loop/index.d.ts

@@ -1,9 +1,3 @@
-import { KnowledgeResearchLoopContext, AddSourceTextInput, SourceAdapter, RunKnowledgeResearchLoopOptions, KnowledgeResearchLoopResult } from '@tangle-network/agent-knowledge';
-import { KnowledgeSourceSpec, AgentKnowledgeConfig } from '../config/index.js';
-import '../knowledge/index.js';
-import '@tangle-network/agent-eval';
-import '../model-CdCDfBA9.js';
-
 /**
  * `@tangle-network/agent-app/knowledge-loop` — wire the declarative
  * `AgentKnowledgeConfig` to a running, source-grounded, eval-gated knowledge
@@ -45,14 +39,15 @@ import '../model-CdCDfBA9.js';
  * bundled. This module imports only TYPES + the loop entry from agent-knowledge
  * and stays substrate-free behind the `decide` / `driver` / `adapters` seams.
  */
-
+import type { AddSourceTextInput, KnowledgeResearchLoopContext, KnowledgeResearchLoopResult, RunKnowledgeResearchLoopOptions, SourceAdapter } from '@tangle-network/agent-knowledge';
+import type { AgentKnowledgeConfig, KnowledgeSourceSpec } from '../config/index';
 /**
  * A research candidate the decider evaluates before the loop applies it. This is
  * the propose-don't-apply unit: notes + the sources discovered this iteration +
  * the proposed write blocks, each carrying a confidence the gate scores against
  * the configured `minConfidence`.
  */
-interface KnowledgeCandidate {
+export interface KnowledgeCandidate {
     /** Human-readable research transcript for this iteration. */
     notes?: string;
     /**
@@ -80,7 +75,7 @@ interface KnowledgeCandidate {
     metadata?: Record<string, unknown>;
 }
 /** The verdict a gate returns for one candidate. */
-interface KnowledgeGateVerdict {
+export interface KnowledgeGateVerdict {
     /** Whether the candidate's proposal is accepted (applied) or gated out. */
     accepted: boolean;
     /** Why — surfaced in the decision metadata for audit. */
@@ -96,11 +91,11 @@ interface KnowledgeGateVerdict {
  * verdict on it. This is the seam an agentic judge or a sandbox run plugs into;
  * the default {@link createReviewerDecider} is a confidence gate.
  */
-interface KnowledgeDecider {
+export interface KnowledgeDecider {
     (input: KnowledgeDeciderInput): Promise<KnowledgeDecision> | KnowledgeDecision;
 }
 /** Define the input parameters required to decide knowledge proposals within an agent-knowledge loop */
-interface KnowledgeDeciderInput {
+export interface KnowledgeDeciderInput {
     /** The agent-knowledge loop context for this iteration. */
     context: KnowledgeResearchLoopContext;
     /** The acquisition goal (from `config.loop.goal` or a deps fallback). */
@@ -115,7 +110,7 @@ interface KnowledgeDeciderInput {
     driver?: KnowledgeLoopDriver;
 }
 /** Define a decision containing a candidate and the gate's verdict on that candidate */
-interface KnowledgeDecision {
+export interface KnowledgeDecision {
     /** The candidate the policy produced (may be empty to end the loop). */
     candidate: KnowledgeCandidate;
     /** The gate's verdict on the candidate's proposal. */
@@ -128,7 +123,7 @@ interface KnowledgeDecision {
  * without this module importing the runtime engine. A deterministic / sandbox
  * decider may omit it.
  */
-interface KnowledgeLoopDriver {
+export interface KnowledgeLoopDriver {
     (opts: {
         systemPrompt: string;
         userMessage: string;
@@ -137,7 +132,7 @@ interface KnowledgeLoopDriver {
     }>;
 }
 /** Define dependencies required to create and run a knowledge processing loop */
-interface CreateKnowledgeLoopDeps {
+export interface CreateKnowledgeLoopDeps {
     /**
      * The knowledge-base root the loop reads/writes (an agent-knowledge layout).
      * Required — agent-knowledge owns disk; agent-app owns only the wiring.
@@ -174,7 +169,7 @@ interface CreateKnowledgeLoopDeps {
     onStep?: RunKnowledgeResearchLoopOptions['onStep'];
 }
 /** The handle `createKnowledgeLoop` returns. */
-interface KnowledgeLoop {
+export interface KnowledgeLoop {
     /** Run the acquisition loop to completion and return the agent-knowledge result. */
     run(): Promise<KnowledgeResearchLoopResult>;
     /** The resolved goal the loop pursues. */
@@ -192,7 +187,7 @@ interface KnowledgeLoop {
  * accepted (nothing to gate). This is the floor policy; swap in an agentic judge
  * or a sandbox-run decider via `deps.decide` for richer review.
  */
-declare function reviewCandidate(candidate: KnowledgeCandidate, minConfidence: number): KnowledgeGateVerdict;
+export declare function reviewCandidate(candidate: KnowledgeCandidate, minConfidence: number): KnowledgeGateVerdict;
 /**
  * Wrap a candidate-producing policy in the default reviewer gate. The policy
  * decides WHAT to propose (notes, sources, proposalText, confidence); the gate
@@ -200,12 +195,10 @@ declare function reviewCandidate(candidate: KnowledgeCandidate, minConfidence: n
  * want the standard confidence gate; pass a full {@link KnowledgeDecider} to
  * `deps.decide` to own the gate too.
  */
-declare function createReviewerDecider(propose: (input: KnowledgeDeciderInput) => Promise<KnowledgeCandidate> | KnowledgeCandidate): KnowledgeDecider;
+export declare function createReviewerDecider(propose: (input: KnowledgeDeciderInput) => Promise<KnowledgeCandidate> | KnowledgeCandidate): KnowledgeDecider;
 /**
  * Build a runnable knowledge-acquisition loop from the product's
  * `AgentKnowledgeConfig` and a small set of seams. Maps config → agent-knowledge
  * `runKnowledgeResearchLoop` options; never reimplements the loop.
  */
-declare function createKnowledgeLoop(knowledge: AgentKnowledgeConfig, deps: CreateKnowledgeLoopDeps): KnowledgeLoop;
-
-export { type CreateKnowledgeLoopDeps, type KnowledgeCandidate, type KnowledgeDecider, type KnowledgeDeciderInput, type KnowledgeDecision, type KnowledgeGateVerdict, type KnowledgeLoop, type KnowledgeLoopDriver, createKnowledgeLoop, createReviewerDecider, reviewCandidate };
+export declare function createKnowledgeLoop(knowledge: AgentKnowledgeConfig, deps: CreateKnowledgeLoopDeps): KnowledgeLoop;

package/dist/legibility/checks/empty-state.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Check 2 — dead-end empty states.
+ *
+ * The defect, measured on one vertical: 21 empty states, 11 of them offering no
+ * next action. A screen that says "No deadlines tracked yet" and nothing else
+ * has told the reader they are in the right place and stranded them there. It
+ * is the cheapest, most repeated legibility failure in the fleet, and it is
+ * mechanically detectable: the empty branch renders no button, no link, no form
+ * control.
+ *
+ * ── How the empty branch is scoped ───────────────────────────────────────────
+ *
+ * The interesting part is not finding the words, it is deciding what subtree
+ * "the empty state" means. Walking up to the page root would find some button
+ * somewhere and never report anything; stopping at the `<p>` would report every
+ * empty state, action or not.
+ *
+ * The lexer records, for each element, the `{` of its enclosing JSX expression
+ * container. Elements sharing a container are one conditional branch — exactly
+ * how empty states are written:
+ *
+ *     {rows.length === 0 && (            ← container
+ *       <div className="empty">          ← branch root, same container
+ *         <p>No deadlines tracked yet</p>
+ *       </div>
+ *     )}
+ *
+ * So the branch root is the outermost ancestor sharing the text's container,
+ * and the subtree searched for an action is exactly that branch. A component
+ * that takes its empty copy as props (`emptyTitle="No sessions yet"`) is its own
+ * root, and its action props are read the same way.
+ *
+ * Recall limit: copy held in a variable or returned from a helper is invisible
+ * to a lexer, and an "action" reached only through a child component's internals
+ * is assumed present when that component takes an action-shaped prop.
+ *
+ * ── A titled section's zero-state is not a dead end ──────────────────────────
+ *
+ * The one measured false-positive class, and the one that decides whether this
+ * check survives contact with a team. A contract detail screen carries four
+ * zero-states — "No parties recorded.", "No open findings.", "No resolved
+ * findings yet.", "No renewal alerts configured." — one under each `<h2>`. None
+ * of them strands anybody: the screen is full, the reader is oriented, and the
+ * line is the honest label for a section that is empty. Reporting all four (and
+ * a table's "No findings." beside its own Run button, and a kanban column's "No
+ * filings") buries the defect this check exists for — the screen whose ENTIRE
+ * body is "No deadlines tracked yet".
+ *
+ * So a branch whose nearest preceding SIBLING is a heading is a section label
+ * and is not reported. Measured over two production verticals: 21 findings → 12,
+ * removing 8 section labels and 1 success state, and keeping every page-level
+ * dead end. The recall cost is a real one — a screen whose whole body is one
+ * titled, actionless section reads as a section here — and `emptyState:
+ * { reportSectionZeroStates: true }` turns it back on.
+ */
+import type { ScannedFile } from '../scan';
+import type { EmptyStateOptions, RawFinding } from '../types';
+/** Run the dead-end empty-state check over one lexed file. */
+export declare function checkEmptyStates(file: ScannedFile, options?: EmptyStateOptions): RawFinding[];

package/dist/legibility/checks/reachability.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Check 5 — a capability with no door.
+ *
+ * Two deterministic engines shipped in this fleet with no way to reach them: a
+ * contract redline that cites statutes, and a court-deadline calculator with 59
+ * golden tests. Both correct, both routed, neither in the navigation and
+ * neither linked from any screen. The only way to open them was to type the URL.
+ * No test failed, because every test was about the engine.
+ *
+ * This check joins two things a product already has — its route table and its
+ * navigation definition — and reports the routes that neither the navigation
+ * nor any link in the source reaches.
+ *
+ * ── Matching, and why it is by STATIC SEGMENTS ───────────────────────────────
+ *
+ * Links are written against a base that is computed at runtime:
+ *
+ *     route('contracts/redline', …)   under   route(':workspaceId', …) under route('app', …)
+ *     <Link to={`${base}/contracts/redline`}>            base = `/app/${workspaceId}`
+ *
+ * Comparing strings finds nothing. So both sides are reduced to their STATIC
+ * segments — parameters and `${…}` holes drop out — and a link reaches a route
+ * when the link's segments are a suffix of the route's:
+ *
+ *     route  app/:workspaceId/contracts/redline  →  [app, contracts, redline]
+ *     link   `${base}/contracts/redline`         →  [contracts, redline]  ✓ suffix
+ *     link   `${base}/contracts`                 →  [contracts]           ✗ (matches the parent, not this)
+ *
+ * The suffix rule is what makes the check usable without resolving `base`, and
+ * the cost is a known blind spot: a detail route (`reviews/:id`) has the same
+ * static segments as its list route, so a link to the list marks the detail
+ * reachable. That is a missed defect, never a false alarm — the deliberate
+ * direction for a gate that only survives if its reports are all real.
+ *
+ * ── Reachable FROM THE NAVIGATION, not merely linked ─────────────────────────
+ *
+ * A link is only a door if the screen holding it can itself be opened. The
+ * shipped defect is an ISLAND: a contract list, a contract detail page and a
+ * statute-citing redline engine, each linking the other two, and no navigation
+ * entry pointing at any of them. Every route in it has an inbound link, so a
+ * check that asks "does a link exist?" reports nothing at all — which is what
+ * happened, and the redline shipped unreachable.
+ *
+ * So doors are resolved transitively from the navigation:
+ *
+ *   - a nav file's path literals are roots;
+ *   - so is a link in a file that is NOT a route module (a shared component, a
+ *     header, an index route) — it could be rendered anywhere, and assuming it
+ *     is always available is the direction that removes findings rather than
+ *     inventing them;
+ *   - a link inside a ROUTE module counts only once that route is itself
+ *     reachable, and the pass repeats to a fixpoint.
+ *
+ * An island therefore reports every route in it, which is right: one nav entry
+ * clears them all, and naming only the entry route would hide how much shipped
+ * behind it.
+ *
+ * ── What is not a screen ─────────────────────────────────────────────────────
+ *
+ * `index()` and `layout()` add no path of their own. A route whose module is
+ * not `.tsx` is a resource endpoint (the react-router convention) and is
+ * skipped by default, as is anything under `ignore` (default `api/*`).
+ */
+import { type ScannedFile } from '../scan';
+import type { RawFinding, ReachabilityOptions } from '../types';
+/** One route as declared, with its composed path. */
+export interface RouteEntry {
+    /** Full path from the root of the route table, no leading slash. */
+    readonly path: string;
+    /** The route module, when the declaration names one. */
+    readonly module: string | null;
+    /** Offset of the path literal in the route config, for file:line. */
+    readonly offset: number;
+    /**
+     * True when the declaration nests children. Such a route renders an Outlet
+     * shell; the destination is its index child, whose path is the same string.
+     * Asking a layout for its own door reports every product's `app` wrapper.
+     */
+    readonly isLayout: boolean;
+}
+/**
+ * Parse a `@react-router/dev/routes` config into composed route paths.
+ *
+ * Nesting is read from offset containment rather than from a grammar: a call
+ * whose parentheses sit inside another call's is that call's child, which is
+ * true of `route(p, m, [ route(…) ])` and needs no array bookkeeping.
+ */
+export declare function parseRouteConfig(file: ScannedFile): RouteEntry[];
+/** The comparable segments of a path: statics only, params and holes dropped. */
+export declare function staticSegments(path: string): string[];
+export interface ReachabilityInput {
+    /** Every scanned product file — the source of in-source links. */
+    readonly files: readonly ScannedFile[];
+    readonly options: ReachabilityOptions;
+}
+export interface ReachabilityResult {
+    readonly findings: readonly RawFinding[];
+    /** The route config, lexed — so the runner can apply its suppressions. */
+    readonly routeFile: ScannedFile | null;
+    readonly routeCount: number;
+}
+/** Run the unreachable-capability check over a whole product. */
+export declare function checkReachability({ files, options }: ReachabilityInput): ReachabilityResult;

package/dist/legibility/checks/silent-failure.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Check 4 — a failure the reader never learns about.
+ *
+ * The shape: a `catch` that clears a loading flag, or returns a fallback, and
+ * tells nobody. The request failed; the screen renders the empty state. The
+ * reader is shown "No documents yet" for a network error, believes the answer,
+ * and acts on it. That is worse than an error message, because it is a
+ * confident wrong answer rather than a visible problem.
+ *
+ * ── What passes ──────────────────────────────────────────────────────────────
+ *
+ * The handler surfaces the failure (an error/notice state setter, a toast, an
+ * injected `onError`), or rethrows / rejects so a boundary above can. Anything
+ * else — an empty body, `setLoading(false)`, `return []`, a lone
+ * `console.error` — is a finding. `console.error` is deliberately NOT a sink:
+ * it writes to a console the reader does not have.
+ *
+ * ── Precision ────────────────────────────────────────────────────────────────
+ *
+ * Only handlers around I/O are read. A `try { JSON.parse(raw) } catch { return
+ * {} }` is a legitimate fallback over a value already in hand, and reporting it
+ * is exactly the noise that gets a gate switched off — so a `try` block with no
+ * `await`, no request call and no `.then` is skipped entirely. A `.catch(…)`
+ * handler is always on a promise, so it needs no such test.
+ *
+ * Three narrowings were MEASURED against two production verticals, where the
+ * unnarrowed check reported 52 handlers of which 14 were real (27%) — a rate
+ * that gets a check deleted, not fixed:
+ *
+ *  1. Only modules that can reach a browser are read ({@link READERLESS_PATHS}).
+ *     31 of the 52 sat in `.server/` service modules and resource routes, where
+ *     the failure IS reported — to the operator's log — and the question of what
+ *     the reader is told belongs to the caller that renders. This is the single
+ *     largest noise class and it is a react-router CONVENTION, not a guess:
+ *     `.server` modules are compiled out of the client bundle.
+ *  2. A handler that RESTORES the prior value has surfaced the failure: the
+ *     control the reader just moved visibly snaps back.
+ *  3. A handler that RETURNS words — `return 'unknown'`, `new Response('Invalid
+ *     JSON', …)` — hands a distinguishable outcome to a caller that renders it.
+ *     Words inside a `console` call do not count, for the reason above.
+ *
+ * The cost is stated rather than hidden: narrowing 1 gives up the real
+ * one-hop defect (a service returning `[]` on a network error, which a screen
+ * then renders as "nothing here"). That is a caller-side finding this check
+ * cannot see from the callee, and a product that wants it back passes
+ * `readerlessPaths: []`.
+ */
+import type { ScannedFile } from '../scan';
+import type { RawFinding, SilentFailureOptions } from '../types';
+/**
+ * Paths whose modules cannot render. `.server` is react-router's server-only
+ * convention (compiled out of the client bundle) and `routes/api.` its resource
+ * -route naming; a `catch` in either reports to an operator, not to a reader.
+ */
+export declare const READERLESS_PATHS: readonly string[];
+/** Run the silent-failure check over one lexed file. */
+export declare function checkSilentFailure(file: ScannedFile, options?: SilentFailureOptions): RawFinding[];

package/dist/legibility/checks/success.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Check 3 — success reported before the response was read.
+ *
+ * The shipped defect: a Settings page that answered "Saved" to a 404. `fetch`
+ * resolves on 404 — it only rejects on a transport failure — so a handler that
+ * awaits it and then celebrates has not checked anything. The reader is told
+ * their change is stored; it is not; nothing in the UI ever says otherwise.
+ *
+ * ── What is required for a pass ──────────────────────────────────────────────
+ *
+ * Somewhere in the same function body, the response is INSPECTED: `res.ok`,
+ * `res.status`, a destructured `{ ok }`, or a guard call the product names in
+ * `success.okGuards`. Reading `await res.json()` is not inspection — a 404 body
+ * parses fine.
+ *
+ * Two failing shapes, reported with different messages because the fixes
+ * differ:
+ *
+ *   1. awaited but unchecked —  `await fetch(url, {…}); toast.success('Saved')`
+ *   2. never awaited —          `fetch(url, {…}); setSaved(true)`
+ *
+ * ── Precision ────────────────────────────────────────────────────────────────
+ *
+ * Scope is the enclosing FUNCTION body, not the file: a component with a fetch
+ * in one handler and a success in another must not report. The trigger is
+ * narrow on both ends — only calls the product declares as HTTP (default:
+ * `fetch`, which is the only one in the standard library that resolves on a
+ * failed request), and only success signals that are unambiguous: `toast.success`,
+ * a `set…Saved/Success/Done/Sent/Submitted(true)` setter, or a status setter
+ * given a success word. A wrapper that throws on a bad status is correct by
+ * construction and is not a default trigger; a wrapper that does NOT throw is
+ * the same bug one level down, so a product wraps `fetch` by adding its wrapper
+ * to `httpCalls`.
+ */
+import type { ScannedFile } from '../scan';
+import type { RawFinding, SuccessOptions } from '../types';
+/** Run the unchecked-success check over one lexed file. */
+export declare function checkUncheckedSuccess(file: ScannedFile, options?: SuccessOptions): RawFinding[];

package/dist/legibility/checks/vocabulary.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Check 1 — engineering vocabulary on screen.
+ *
+ * The defect: a word from the codebase reaches the reader. Shipped instances
+ * include "materialized" inside a user-facing error, a column of `sourceKind`,
+ * and a chip reading `undefined`. Nobody decided to say those words; they leaked
+ * because the label and the field name were the same string.
+ *
+ * ── Precision over recall, deliberately ──────────────────────────────────────
+ *
+ * A vocabulary gate lives or dies on false positives: one bad report and the
+ * check is disabled, after which it guards nothing. `grep -i artifact` over one
+ * product's `apps/web/src` returns 11 hits, all of them imports, prop names or
+ * doc comments — a checker that reports those is deleted in a week.
+ *
+ * So this check only reads positions the lexer PROVES are copy, in two tiers
+ * that are ON by default:
+ *
+ *  1. JSX text — `<p>No artifact yet</p>`. Unambiguous.
+ *  2. A JSX attribute value, when the attribute is in {@link COPY_KEYS}. An
+ *     allowlist, so `className`, `data-*`, `aria-*`, `id`, `href` and every
+ *     other internal attribute are excluded by construction rather than by a
+ *     denylist that goes stale.
+ *  3. The first argument of a call in {@link COPY_CALLS} — `toast.error('…')`,
+ *     `new Error('…')`, `setError('…')`. This is the tier that catches the
+ *     flagship defect: "materialization" reached a reader from a `new Error`
+ *     in a server module, not from a component.
+ *
+ * And ONE tier that is off by default, `includeObjectCopy`:
+ *
+ *  4. A string or template filling an object key named in {@link COPY_KEYS}
+ *     (`emptyTitle: '…'`, `description: '…'`).
+ *
+ * Tier 4 is off because it was MEASURED as the false-positive tier. Over two
+ * production verticals it produced findings on a system prompt (`prompt:` in an
+ * agent profile), an MCP tool description the model reads, and the body of a
+ * legal document template where "Records" is a term of the drafted document —
+ * none of them on any screen. A key named `description` is model-facing about
+ * as often as it is reader-facing, and a checker that cannot tell them apart
+ * must not be the one that fails the build. Products whose data modules really
+ * do hold UI copy turn it on.
+ *
+ * Everything else — a bare string in code, an import specifier, a comment, an
+ * identifier, a test file — is not read at all. The cost is real recall: copy
+ * assembled through a variable (`const msg = base + suffix`) is invisible here,
+ * and no lexer can see it. That is the trade this check makes on purpose.
+ */
+import type { ScannedFile } from '../scan';
+import type { BannedTerm, RawFinding, VocabularyOptions } from '../types';
+/**
+ * The default list. Every entry has shipped to a real screen in this fleet or
+ * its verticals, and every one carries the sentence that replaces it — a gate
+ * that only says "don't" leaves the author to guess.
+ */
+export declare const DEFAULT_BANNED_TERMS: readonly BannedTerm[];
+/**
+ * Attributes and object keys whose string value is copy. An allowlist: an
+ * attribute that is not here is never read, which is how `aria-label`,
+ * `className`, `data-testid` and `href` stay out without being enumerated.
+ */
+export declare const COPY_KEYS: readonly string[];
+/** Calls whose first string argument reaches the reader. */
+export declare const COPY_CALLS: readonly string[];
+/** Run the vocabulary check over one lexed file. */
+export declare function checkVocabulary(file: ScannedFile, options?: VocabularyOptions): RawFinding[];

package/dist/legibility/cli-args.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The bin's argument and config layer, split from `cli.ts` so it can be tested
+ * without executing a `main()` that calls `process.exit`.
+ *
+ * Errors are thrown as {@link LegibilityUsageError} rather than exiting here:
+ * exiting is the bin's job, and a parser that exits cannot be exercised.
+ */
+import { type LegibilityCheckId, type LegibilityConfig } from './types';
+export declare const DEFAULT_CONFIG_FILE = "legibility.config.mjs";
+/** A usage or config problem — exit code 2, never a finding. */
+export declare class LegibilityUsageError extends Error {
+}
+export interface ParsedArgs {
+    srcDirs: string[];
+    navFiles: string[];
+    ignorePaths: string[];
+    skip: LegibilityCheckId[];
+    routes?: string;
+    config?: string;
+    json: boolean;
+    listSuppressions: boolean;
+    help: boolean;
+}
+export declare const USAGE: string;
+export declare function parseArgs(argv: readonly string[]): ParsedArgs;
+/**
+ * Merge a config file with the flags. Flags WIN, so a one-off CI invocation can
+ * narrow a run without editing the committed config.
+ */
+export declare function mergeConfig(fromFile: Partial<LegibilityConfig>, args: ParsedArgs): LegibilityConfig;

package/dist/legibility/cli.d.ts

@@ -1 +1,26 @@
 #!/usr/bin/env node
+/**
+ * `agent-app-legibility-check` — fail a product's CI when a screen leaves its
+ * reader guessing.
+ *
+ * Runs in the PRODUCT's repo, over the product's own source, next to typecheck:
+ *
+ *     "scripts": {
+ *       "legibility": "agent-app-legibility-check --src src --routes src/routes.ts --nav src/components/workspace-sidebar.tsx"
+ *     }
+ *
+ * Flags (repeatable where a list makes sense):
+ *   --src <dir>          source directory to scan (required unless the config supplies it)
+ *   --routes <file>      react-router route config, for the unreachable-capability check
+ *   --nav <file>         a file whose path literals are navigation entries
+ *   --ignore <substr>    skip paths containing this substring
+ *   --skip <check>       turn one check off wholesale (prefer a per-line suppression)
+ *   --config <file>      a legibility.config.mjs default-exporting the config
+ *                        (default: ./legibility.config.mjs when present)
+ *   --json               print the report as JSON instead of text
+ *   --list-suppressions  print every honoured suppression with its reason
+ *
+ * Exit 0 with no findings, 1 with findings, 2 on a usage or config error — the
+ * same contract as `agent-app-preflight` and `agent-app-peer-check`.
+ */
+export {};