@iamu-dev/iamu 0.7.0-beta.0 → 0.8.0-beta.1

package/dist/commands/browse-actions.d.ts

@@ -28,6 +28,7 @@ export interface IndexedElement {
     name: string;
     type?: string;
     disabled?: boolean;
+    checked?: boolean;
 }
 export declare const INDEXED_SELECTOR: string;
 export declare function markAndQueryIndexedElements(page: Page): Promise<IndexedElement[]>;

package/dist/commands/browse-driver.d.ts

@@ -43,7 +43,7 @@ export interface BrowserDriver {
     /** The full command line of `pid`, or null when it is gone or cannot be read. */
     commandLine(pid: number): Promise<string | null>;
     /** Send SIGTERM to `pid`. Never throws. */
-    kill(pid: number): void;
+    kill(pid: number, signal?: NodeJS.Signals | number): void;
 }
 /** How long a CDP liveness probe may take before the port counts as dead. */
 export declare const CDP_PROBE_TIMEOUT_MS = 1000;
@@ -65,10 +65,9 @@ export declare const CDP_PROBE_TIMEOUT_MS = 1000;
  */
 export declare function probeCdp(port: number, timeoutMs?: number): Promise<boolean>;
 /**
- * The command line of a running process, read without a shell:
- * `/proc/<pid>/cmdline` on Linux, else `ps -ww -o args= -p <pid>`.
- * Windows has no equivalent we trust, so it answers null there — and
- * callers then leave the process alone.
+ * The command line of a running process:
+ * `/proc/<pid>/cmdline` on Linux, PowerShell CIM query on Windows,
+ * else `ps -ww -o args= -p <pid>`.
  *
  * @param pid - Process ID to inspect.
  * @param platform - Defaults to `process.platform`.
@@ -82,6 +81,12 @@ export declare function probeCdp(port: number, timeoutMs?: number): Promise<bool
  * @public
  */
 export declare function readProcessCommandLine(pid: number, platform?: NodeJS.Platform): Promise<string | null>;
+/**
+ * Supported browser executable names in process command lines.
+ *
+ * @public
+ */
+export declare const BROWSER_NAME_RE: RegExp;
 /**
  * Was this command line launched with exactly this `--user-data-dir`?
  * The profile directory is ours alone, so a match means the PID is the
@@ -117,5 +122,20 @@ export declare function isOurBrowser(commandLine: string | null, profileDir: str
  * @public
  */
 export declare function reapBrowser(pid: number, profileDir: string, driver: Pick<BrowserDriver, "commandLine" | "kill">): Promise<boolean>;
+/**
+ * Select the target page to act on from all open pages in the context.
+ * Filters out devtools and browser internal/extension pages unless only internal pages exist.
+ * Respects pageIndex when valid; otherwise prefers the last active non-blank page.
+ *
+ * @param rawPages - All pages returned by the browser context.
+ * @param pageIndex - Optional explicit zero-based index into the filtered pages array.
+ * @returns The selected Page and the list of user/available pages.
+ *
+ * @public
+ */
+export declare function selectTargetPage(rawPages: Page[], pageIndex?: number): {
+    page: Page | undefined;
+    pages: Page[];
+};
 /** The real driver: spawns Chrome and speaks CDP through playwright-core. */
 export declare const cdpDriver: BrowserDriver;

package/dist/commands/browse.d.ts

@@ -19,9 +19,15 @@ export interface BrowseOptions {
     surface?: string;
     maxSteps?: string | number;
     stepFile?: string;
+    /** Chained page actions executed sequentially in a single browse step before screenshot. */
+    then?: string[];
+    /** Include post-action indexed snapshot in browse step output (default: true). */
+    snapshot?: boolean;
     json?: boolean;
     /** Annotate snapshot with 1-based index numbers [#N] for click-index / fill-index */
     indexed?: boolean;
+    /** `clear-storage`: the origin to clear (default: the run's target URL). */
+    origin?: string;
 }
 interface BrowseState {
     port: number;
@@ -175,7 +181,39 @@ export declare function detectAntiBotChallenge(page: Page, allowEvaluate?: boole
  */
 export declare function withPage(opts: BrowseOptions, driver: BrowserDriver, fn: (page: Page) => Promise<void>, 
 /** What the action looks for, named for the error message. */
-target?: string): Promise<PageResult | null>;
+target?: string, 
+/** Optional post-screenshot hook executed before detaching from CDP. */
+onPostShot?: (page: Page) => Promise<void>): Promise<PageResult | null>;
+/**
+ * Obtain an ARIA accessibility snapshot with fallback from body to :root,
+ * handling empty or about:blank pages gracefully.
+ *
+ * @public
+ */
+export declare function resilientAriaSnapshot(page: Page): Promise<string>;
+/** What {@link clearOriginStorage} removed. */
+export interface ClearedStorage {
+    origin: string;
+    local_storage_keys: string[];
+    cookies: string[];
+}
+/**
+ * Leave the page for `about:blank` (so the app cannot write its state
+ * back on unload), then clear cookies, localStorage, IndexedDB and
+ * caches for `origin`. Returns what was there, or an error message.
+ */
+export declare function clearOriginStorage(origin: string, driver?: BrowserDriver, 
+/** Page to open after clearing (the run's start URL); else about:blank. */
+returnTo?: string): Promise<ClearedStorage | {
+    error: string;
+}>;
+/**
+ * Split a chained action string (e.g. `fill-index 22 "2026-11-20"`) into tokens,
+ * respecting single and double quotes.
+ *
+ * @public
+ */
+export declare function parseActionCommand(raw: string): string[];
 /**
  * `iamu browse <command> [args…]` — dispatch one browse subcommand.
  * Failures print to stderr and set exit code 1.

package/dist/commands/doctor-design.d.ts

@@ -0,0 +1,9 @@
+import type { DoctorCheck } from "./doctor.js";
+/**
+ * The design docs the project recorded: files that are gone, references
+ * inside them to paths, components and tokens that no longer exist, an
+ * unmigrated legacy doc, stale proposals and an outdated agent block.
+ * No recorded docs is not a fault: the designer then reviews by general
+ * craft, so it is reported as ok with a hint.
+ */
+export declare function checkDesignDocs(projectRoot: string): Promise<DoctorCheck[]>;

package/dist/commands/doctor.d.ts

@@ -1,5 +1,5 @@
 export interface DoctorCheck {
-    category: "runtime" | "browser" | "project" | "agent" | "cloud" | "target";
+    category: "runtime" | "browser" | "project" | "design" | "agent" | "cloud" | "target";
     name: string;
     status: "ok" | "warn" | "error";
     message: string;

package/dist/commands/edit-entity.d.ts

@@ -2,7 +2,7 @@ export interface EditEntityOptions {
     json?: boolean;
 }
 /**
- * Open an entity in the user's $EDITOR or $VISUAL, and validate its frontmatter
- * against the entity schema on exit.
+ * Open an entity or project configuration file in the user's $EDITOR or $VISUAL,
+ * and validate its frontmatter against the schema on exit.
  */
-export declare function editEntity(type: string, slug: string, opts?: EditEntityOptions): Promise<void>;
+export declare function editEntity(type: string, slug?: string, opts?: EditEntityOptions): Promise<void>;

package/dist/commands/finding-stability.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Spike (fast-critic-loop D6): how stable each finding has been across
+ * its scenario's runs, computed on read from local run history. No new
+ * stored field; the harden phase moves this into the match stage.
+ *
+ * A data point per non-blocked completed run of the scenario, oldest
+ * first, from the finding's first observation on:
+ * - `1` the run recorded it: a finding file of that run carries its
+ *   `canonical_id`, or the run's verification says it persists;
+ * - `0` the run re-checked it and saw it working: `verification.resolved`
+ *   or the matcher's `rechecked_fixed` (step-backed, not absence);
+ * - no point at all when the run said nothing about it (`not_observed`,
+ *   `uncertain`, or it was not part of the comparison). A walk that took
+ *   another path is not evidence of a flicker, the same rule as
+ *   `fix-state.ts` ("never from absence").
+ *
+ * `unstable` when the points since the last fix (a finding with that
+ * canonical id triaged `addressed`/`fixed`) change value two or more
+ * times; `first_seen` when it was observed once; otherwise `stable`.
+ */
+import { type RunEvidence } from "@iamu-dev/local-store";
+/** How far a builder can trust a finding to be real and lasting. */
+export type FindingStability = "stable" | "unstable" | "first_seen";
+/** One run's word on a finding: observed (1) or re-checked fixed (0). */
+export interface StabilityPoint {
+    observed: boolean;
+    /** Run start, epoch ms; null when unknown. */
+    at: number | null;
+}
+/**
+ * The D6 rule on one finding's chronological points.
+ *
+ * @param points - Oldest first; runs with no word on the finding left out.
+ * @param fixedAt - Epoch ms of the latest recorded fix, or null.
+ * @returns `first_seen`, `unstable` or `stable`.
+ *
+ * @example
+ * ```ts
+ * stabilityOf([{ observed: true, at: 1 }, { observed: false, at: 2 }, { observed: true, at: 3 }], null);
+ * // "unstable"
+ * ```
+ */
+export declare function stabilityOf(points: readonly StabilityPoint[], fixedAt: number | null): FindingStability;
+interface HistoryFinding {
+    run?: string;
+    scenario?: string;
+    canonical_id?: string;
+    triage_status?: string;
+    updated_at?: string;
+    created_at?: string;
+    source?: string;
+    lens?: string;
+}
+/** What the stability read needs from disk; load once per report. */
+export interface StabilityHistory {
+    runs: RunEvidence[];
+    findings: HistoryFinding[];
+}
+/** Read the run evidence and finding files once. Never throws. */
+export declare function loadStabilityHistory(projectRoot: string): Promise<StabilityHistory>;
+/**
+ * Stability of every canonical finding of `scenario`, as of `runId`
+ * (later runs are not its past).
+ *
+ * @param history - From {@link loadStabilityHistory}.
+ * @param scenario - Scenario slug.
+ * @param runId - The run being reported; runs after it are ignored.
+ * @returns canonical id → stability.
+ */
+export declare function scenarioStability(history: StabilityHistory, scenario: string, runId: string): Map<string, FindingStability>;
+export {};

package/dist/commands/fix-brief.d.ts

@@ -1,9 +1,13 @@
 import { type DesignerFixBrief, type FixBrief } from "@iamu-dev/local-store";
-export declare function fixBrief(ref: string, opts: {
+export declare function fixBrief(ref: string | undefined, opts: {
+    wave?: boolean;
     json?: boolean;
 }): Promise<void>;
 /**
  * A loop step as a person reads it: each backticked field name becomes
  * the section above that holds it, or its value.
  */
-export declare function readable(step: string, b: Pick<FixBrief | DesignerFixBrief, "rerun" | "closing_check">): string;
+export declare function readable(step: string, b: Pick<FixBrief | DesignerFixBrief, "closing_check"> & {
+    rerun?: string | string[];
+    scenarios_to_rerun?: string[];
+}): string;

package/dist/commands/init.d.ts

@@ -8,18 +8,18 @@ export declare function setupCommand(projectRoot: string, hosts: HostAdapter[]):
  * Detect the target port for local dev execution.
  * Checks, in order:
  * 1. process.env.PORT
- * 2. .env files (.env.local, .env.development, .env) for PORT, VITE_PORT, APP_URL, NEXT_PUBLIC_APP_URL
- * 3. package.json scripts for `-p <port>` or `--port <port>` flags
- * 4. package.json dependencies and framework config files (vite -> 5173, astro -> 4321)
+ * 2. Root .env files, vite/astro config `port:`, package.json scripts/deps
+ * 3. Monorepo workspace subdirectories (apps/*, packages/*, web, frontend, client)
  */
 export declare function detectTargetPort(projectRoot: string): number | undefined;
 export declare function detectTargetUrl(projectRoot: string): string;
-export declare function createDraftTestabilityContent(targetUrl?: string): string;
+export declare function createDraftTestabilityContent(targetUrl?: string, status?: "draft" | "verified"): string;
 export interface InitOptions {
     name?: string;
     yes?: boolean;
     json?: boolean;
     cloud?: boolean;
+    target?: string;
 }
 /**
  * Scaffold `iamu/` and install skills for the detected hosts.

package/dist/commands/instructions-walk.d.ts

@@ -1,5 +1,11 @@
 import { type GuidanceRule, type RevisitPlace } from "@iamu-dev/local-store";
 import { type RunViewport, type ScenarioState } from "@iamu-dev/protocol";
+/**
+ * How to invoke this very CLI from a subagent's shell. Aliases and
+ * shell functions do not exist there, so name the executable that is
+ * running now.
+ */
+export declare function selfCommand(execPath?: string, scriptPath?: string): string;
 /** "The browser is sized as a phone screen, 390×844." */
 export declare function viewportLine(v: RunViewport): string;
 interface WalkerPromptParts {

package/dist/commands/live-run-client.d.ts

@@ -20,6 +20,7 @@ export interface RegisterLiveRunParams {
     targetUrl: string;
     startedAt?: string;
     lenses?: string[];
+    json?: boolean;
     fetchFn?: typeof fetch;
 }
 export interface RegisterLiveRunResult {

package/dist/commands/preflight.d.ts

@@ -10,14 +10,16 @@ export interface PreflightCheckResult {
     reason?: string;
 }
 /**
- * Detect the fast compile/typecheck/lint command for a target project.
+ * Detect the fast compile/typecheck command for a target project.
+ * Deliberately excludes lint scripts (`check`, `eslint`, `biome check`) so
+ * lint rules never block walkthrough execution.
  */
 export declare function detectPreflightCommand(targetDir: string): Promise<{
     command: string;
     args: string[];
 } | null>;
 /**
- * Executes a fast preflight type/lint check.
+ * Executes a fast preflight typecheck.
  */
 export declare function runPreflightCheck(targetDir: string): Promise<PreflightCheckResult>;
 /**

package/dist/commands/report-data.d.ts

@@ -1,5 +1,6 @@
 import type { CanonicalWalkthrough } from "@iamu-dev/protocol";
 import { type OverviewView, type RunView, type VerdictLabel } from "../ui/report-view.js";
+import { type StabilityHistory } from "./finding-stability.js";
 export interface CompletedRun {
     runId: string;
     manifest: Record<string, unknown>;
@@ -12,5 +13,5 @@ export declare function readCompletedRuns(projectRoot: string, runIds: string[],
 export declare function verdictLabel(c: CanonicalWalkthrough | null): VerdictLabel;
 /** "/request · step 8" from a page URL and a step id. */
 export declare function whereOf(pageUrl: unknown, stepId: unknown): string | null;
-export declare function buildRunView(projectRoot: string, run: CompletedRun): Promise<RunView>;
+export declare function buildRunView(projectRoot: string, run: CompletedRun, history?: StabilityHistory): Promise<RunView>;
 export declare function buildOverview(projectRoot: string, runs: CompletedRun[]): Promise<OverviewView>;

package/dist/commands/set-entity.d.ts

@@ -1,3 +1,4 @@
+import { type ContextFrontmatter } from "@iamu-dev/protocol";
 /**
  * Options for `iamu set`. Every field is staging: where a walk starts,
  * what the world holds, which account a persona uses, which routes an
@@ -52,6 +53,12 @@ export interface SetEntityOptions {
     description?: string | false;
     /** Project name (context). */
     name?: string | false;
+    /** Governing documents/standards (context patch). */
+    governedBy?: ContextFrontmatter["governed_by"] | false;
+    /** Domain actors (context patch). */
+    actors?: ContextFrontmatter["actors"] | false;
+    /** Domain glossary (context patch). */
+    glossary?: ContextFrontmatter["glossary"] | false;
     /** Markdown body narrative (testability, context). */
     body?: string;
     /** JSON patch file (or - for stdin) containing staging fields. */

package/dist/commands/step.d.ts

@@ -25,6 +25,8 @@ export interface RecordStepInput {
     note?: string | null;
     /** Path of an existing screenshot to copy in; a missing file is an error. */
     shot?: string | null;
+    /** When true, move `shot` into `screenshots/step-N.png` via rename instead of copying. */
+    moveShot?: boolean;
     url?: string | null;
     surface?: string | null;
     grounding?: string | null;

package/dist/commands/timings.d.ts

@@ -0,0 +1,19 @@
+/** A bracket around a pipeline stage: `start` when a command begins, `end` when it has written its output. */
+export type TimingEvent = "start" | "end";
+/**
+ * Spike (fast-critic-loop D0): append one rough timing line to
+ * `<runDir>/timings.jsonl`. Never creates the run directory and never
+ * throws — a timing that cannot be written is simply lost, so a command
+ * never fails because of it. No lock: concurrent appends of one short
+ * line are fine for a rough read.
+ *
+ * @param runDirPath - Absolute path of the run directory (`iamu/.runs/<id>`).
+ * @param stage - The command name, e.g. `match-record`.
+ * @param event - `start` or `end`.
+ *
+ * @example
+ * ```ts
+ * await logTiming(runDirPath, "match", "end");
+ * ```
+ */
+export declare function logTiming(runDirPath: string | null | undefined, stage: string, event: TimingEvent): Promise<void>;

package/dist/commands/triage.d.ts

@@ -10,6 +10,12 @@ export interface TriageOptions {
     scope?: string;
     /** `false` (`--no-guidance`): dismiss without writing a guidance rule. */
     guidance?: boolean;
+    /**
+     * Project-wide sweep ("we never want X"): dismiss all matching open
+     * persona and designer findings across the project and record a
+     * project-wide guidance rule.
+     */
+    sweep?: boolean | string;
     json?: boolean;
 }
 /**