@structured-vibe-coding/core 0.17.1 → 0.18.0

package/dist/index.d.ts

@@ -524,6 +524,16 @@ declare const WorkflowSchema: z.ZodObject<{
 }>;
 declare const ConfigSchema: z.ZodObject<{
     version: z.ZodDefault<z.ZodNumber>;
+    metrics: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        exclude: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        exclude: string[];
+    }, {
+        enabled?: boolean | undefined;
+        exclude?: string[] | undefined;
+    }>>;
     memory_path: z.ZodDefault<z.ZodString>;
     changes_path: z.ZodDefault<z.ZodString>;
     archive_path: z.ZodDefault<z.ZodString>;
@@ -583,6 +593,10 @@ declare const ConfigSchema: z.ZodObject<{
     }>>;
 }, "strip", z.ZodTypeAny, {
     version: number;
+    metrics: {
+        enabled: boolean;
+        exclude: string[];
+    };
     memory_path: string;
     changes_path: string;
     archive_path: string;
@@ -608,6 +622,10 @@ declare const ConfigSchema: z.ZodObject<{
     allowed_workflows?: string[] | undefined;
 }, {
     version?: number | undefined;
+    metrics?: {
+        enabled?: boolean | undefined;
+        exclude?: string[] | undefined;
+    } | undefined;
     memory_path?: string | undefined;
     changes_path?: string | undefined;
     archive_path?: string | undefined;
@@ -641,6 +659,11 @@ declare const ChangeMetaSchema: z.ZodObject<{
     status: z.ZodDefault<z.ZodEnum<["in_progress", "blocked", "completed", "abandoned"]>>;
     stage: z.ZodString;
     branch: z.ZodOptional<z.ZodString>;
+    /** Epic key such as issue-37. Stories in one epic share a dependency graph. */
+    epic: z.ZodOptional<z.ZodString>;
+    /** Story id such as S-001. */
+    story: z.ZodOptional<z.ZodString>;
+    depends: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     domain: z.ZodOptional<z.ZodString>;
     flags: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodBoolean, z.ZodString, z.ZodNumber]>>>;
     overrides: z.ZodDefault<z.ZodObject<{
@@ -913,6 +936,9 @@ declare const ChangeMetaSchema: z.ZodObject<{
     /** Results from `sdd verify` keyed by stage id */
     verify_results: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         ok: z.ZodBoolean;
+        /** pass | fail | not_run (absent in metas written before 0.17.3) */
+        status: z.ZodOptional<z.ZodEnum<["pass", "fail", "not_run"]>>;
+        head_sha: z.ZodOptional<z.ZodString>;
         at: z.ZodString;
         results: z.ZodDefault<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
@@ -931,9 +957,13 @@ declare const ChangeMetaSchema: z.ZodObject<{
             name: string;
             exitCode: number | null;
         }[];
+        status?: "pass" | "fail" | "not_run" | undefined;
+        head_sha?: string | undefined;
     }, {
         at: string;
         ok: boolean;
+        status?: "pass" | "fail" | "not_run" | undefined;
+        head_sha?: string | undefined;
         results?: {
             name: string;
             exitCode: number | null;
@@ -1014,9 +1044,14 @@ declare const ChangeMetaSchema: z.ZodObject<{
             name: string;
             exitCode: number | null;
         }[];
+        status?: "pass" | "fail" | "not_run" | undefined;
+        head_sha?: string | undefined;
     }>;
     updated?: string | undefined;
     branch?: string | undefined;
+    epic?: string | undefined;
+    story?: string | undefined;
+    depends?: string[] | undefined;
     domain?: string | undefined;
     pr?: {
         number?: number | undefined;
@@ -1038,6 +1073,9 @@ declare const ChangeMetaSchema: z.ZodObject<{
     }> | undefined;
     updated?: string | undefined;
     branch?: string | undefined;
+    epic?: string | undefined;
+    story?: string | undefined;
+    depends?: string[] | undefined;
     domain?: string | undefined;
     overrides?: {
         gates?: Record<string, "none" | "soft" | "hard"> | undefined;
@@ -1086,6 +1124,8 @@ declare const ChangeMetaSchema: z.ZodObject<{
     verify_results?: Record<string, {
         at: string;
         ok: boolean;
+        status?: "pass" | "fail" | "not_run" | undefined;
+        head_sha?: string | undefined;
         results?: {
             name: string;
             exitCode: number | null;
@@ -1111,17 +1151,680 @@ declare function configPath(projectRoot: string): string;
 declare function workflowsDir(projectRoot: string): string;
 declare function templatesDir(projectRoot: string): string;
 declare function memoryDir(projectRoot: string, config: Config): string;
+/** Project-relative memory folder, always with a trailing slash stripped. */
+declare function memoryPathRel(config: Pick<Config, "memory_path">): string;
+/** Project-relative changes folder, always with a trailing slash stripped. */
+declare function changesPathRel(config: Pick<Config, "changes_path">): string;
+/** Repo-relative archive directory for a completed change. */
+declare function displayArchivePath(config: Pick<Config, "archive_path">, changeId: string): string;
+/** Repo-relative change directory shown to humans. Never an absolute machine path. */
+declare function displayChangePath(config: Pick<Config, "changes_path">, changeId: string): string;
+/** Paths agents should be told to read, taken from config rather than defaults. */
+declare function guidancePaths(config: Pick<Config, "memory_path" | "changes_path">): {
+    memory: string;
+    changes: string;
+    constitution: string;
+    memoryIndex: string;
+};
 declare function changesDir(projectRoot: string, config: Config): string;
 declare function archiveDir(projectRoot: string, config: Config): string;
 declare function domainsDir(projectRoot: string, config: Config): string;
 declare function changePath(projectRoot: string, config: Config, changeId: string): string;
 declare function changeMetaPath(projectRoot: string, config: Config, changeId: string): string;
 declare function activePointerPath(projectRoot: string, config: Config): string;
+declare function searchConfigPath(projectRoot: string): string;
+declare function indexDbPath(projectRoot: string): string;
 
 declare function isInitialized(projectRoot: string): Promise<boolean>;
 declare function loadConfig(projectRoot: string): Promise<Config>;
 declare function saveConfig(projectRoot: string, config: Config): Promise<void>;
 declare function defaultConfig(): Config;
+/** Merge a user's config over current defaults, then validate and strip unsupported keys. */
+declare function mergeConfigDefaults(existing: unknown): Config;
+
+type GitHeadRunner = (projectRoot: string) => Promise<string>;
+declare function getHeadSha(projectRoot: string, runGit?: GitHeadRunner): Promise<string | null>;
+
+declare const PhaseMetricSchema: z.ZodEffects<z.ZodObject<{
+    phase: z.ZodString;
+    startedAt: z.ZodString;
+    endedAt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    phase: string;
+    startedAt: string;
+    endedAt?: string | undefined;
+}, {
+    phase: string;
+    startedAt: string;
+    endedAt?: string | undefined;
+}>, {
+    phase: string;
+    startedAt: string;
+    endedAt?: string | undefined;
+}, {
+    phase: string;
+    startedAt: string;
+    endedAt?: string | undefined;
+}>;
+declare const TokenUsageMetricSchema: z.ZodObject<{
+    provider: z.ZodEnum<["claude-code", "codex", "grok"]>;
+    model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    requestId: z.ZodString;
+    phase: z.ZodString;
+    startedAt: z.ZodString;
+    inputTokens: z.ZodNullable<z.ZodNumber>;
+    cacheReadTokens: z.ZodNullable<z.ZodNumber>;
+    cacheWriteTokens: z.ZodNullable<z.ZodNumber>;
+    outputTokens: z.ZodNullable<z.ZodNumber>;
+    measured: z.ZodLiteral<true>;
+}, "strip", z.ZodTypeAny, {
+    phase: string;
+    startedAt: string;
+    provider: "claude-code" | "codex" | "grok";
+    requestId: string;
+    inputTokens: number | null;
+    cacheReadTokens: number | null;
+    cacheWriteTokens: number | null;
+    outputTokens: number | null;
+    measured: true;
+    model?: string | null | undefined;
+}, {
+    phase: string;
+    startedAt: string;
+    provider: "claude-code" | "codex" | "grok";
+    requestId: string;
+    inputTokens: number | null;
+    cacheReadTokens: number | null;
+    cacheWriteTokens: number | null;
+    outputTokens: number | null;
+    measured: true;
+    model?: string | null | undefined;
+}>;
+declare const ChangeMetricsSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    phases: z.ZodArray<z.ZodEffects<z.ZodObject<{
+        phase: z.ZodString;
+        startedAt: z.ZodString;
+        endedAt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        phase: string;
+        startedAt: string;
+        endedAt?: string | undefined;
+    }, {
+        phase: string;
+        startedAt: string;
+        endedAt?: string | undefined;
+    }>, {
+        phase: string;
+        startedAt: string;
+        endedAt?: string | undefined;
+    }, {
+        phase: string;
+        startedAt: string;
+        endedAt?: string | undefined;
+    }>, "many">;
+    requests: z.ZodArray<z.ZodObject<{
+        provider: z.ZodEnum<["claude-code", "codex", "grok"]>;
+        model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        requestId: z.ZodString;
+        phase: z.ZodString;
+        startedAt: z.ZodString;
+        inputTokens: z.ZodNullable<z.ZodNumber>;
+        cacheReadTokens: z.ZodNullable<z.ZodNumber>;
+        cacheWriteTokens: z.ZodNullable<z.ZodNumber>;
+        outputTokens: z.ZodNullable<z.ZodNumber>;
+        measured: z.ZodLiteral<true>;
+    }, "strip", z.ZodTypeAny, {
+        phase: string;
+        startedAt: string;
+        provider: "claude-code" | "codex" | "grok";
+        requestId: string;
+        inputTokens: number | null;
+        cacheReadTokens: number | null;
+        cacheWriteTokens: number | null;
+        outputTokens: number | null;
+        measured: true;
+        model?: string | null | undefined;
+    }, {
+        phase: string;
+        startedAt: string;
+        provider: "claude-code" | "codex" | "grok";
+        requestId: string;
+        inputTokens: number | null;
+        cacheReadTokens: number | null;
+        cacheWriteTokens: number | null;
+        outputTokens: number | null;
+        measured: true;
+        model?: string | null | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    version: 1;
+    phases: {
+        phase: string;
+        startedAt: string;
+        endedAt?: string | undefined;
+    }[];
+    requests: {
+        phase: string;
+        startedAt: string;
+        provider: "claude-code" | "codex" | "grok";
+        requestId: string;
+        inputTokens: number | null;
+        cacheReadTokens: number | null;
+        cacheWriteTokens: number | null;
+        outputTokens: number | null;
+        measured: true;
+        model?: string | null | undefined;
+    }[];
+}, {
+    version: 1;
+    phases: {
+        phase: string;
+        startedAt: string;
+        endedAt?: string | undefined;
+    }[];
+    requests: {
+        phase: string;
+        startedAt: string;
+        provider: "claude-code" | "codex" | "grok";
+        requestId: string;
+        inputTokens: number | null;
+        cacheReadTokens: number | null;
+        cacheWriteTokens: number | null;
+        outputTokens: number | null;
+        measured: true;
+        model?: string | null | undefined;
+    }[];
+}>;
+type PhaseMetric = z.infer<typeof PhaseMetricSchema>;
+type TokenUsageMetric = z.infer<typeof TokenUsageMetricSchema>;
+type ChangeMetrics = z.infer<typeof ChangeMetricsSchema>;
+interface MetricsImportResult {
+    imported: number;
+    duplicates: number;
+    ignored: number;
+    unmatched: number;
+    providers: string[];
+    incomplete: boolean;
+}
+declare function emptyChangeMetrics(): ChangeMetrics;
+declare function readChangeMetrics(projectRoot: string, config: Config, changeId: string): Promise<ChangeMetrics>;
+declare function startPhase(projectRoot: string, config: Config, changeId: string, phase: string, startedAt?: string): Promise<void>;
+declare function transitionPhase(projectRoot: string, config: Config, changeId: string, fromPhase: string, toPhase: string | null, at?: string, fromStartedAt?: string): Promise<void>;
+/**
+ * Refuse an in-repo session log under metrics.exclude before the file is opened.
+ * Logs outside the project root are not excluded. Invalid prefixes throw first.
+ */
+declare function assertSessionLogAllowed(projectRoot: string, prefixes: readonly string[], sessionLogPath: string): void;
+declare function importSessionMetrics(projectRoot: string, config: Config, changeId: string, sessionLogPath: string): Promise<MetricsImportResult>;
+
+declare const PriceCardSchema: z.ZodObject<{
+    input_per_million_usd: z.ZodNumber;
+    cache_read_per_million_usd: z.ZodNumber;
+    cache_write_per_million_usd: z.ZodNumber;
+    output_per_million_usd: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    input_per_million_usd: number;
+    cache_read_per_million_usd: number;
+    cache_write_per_million_usd: number;
+    output_per_million_usd: number;
+}, {
+    input_per_million_usd: number;
+    cache_read_per_million_usd: number;
+    cache_write_per_million_usd: number;
+    output_per_million_usd: number;
+}>;
+declare const PricesSchema: z.ZodObject<{
+    usd_to_inr: z.ZodDefault<z.ZodNumber>;
+    models: z.ZodObject<{
+        default: z.ZodObject<{
+            input_per_million_usd: z.ZodNumber;
+            cache_read_per_million_usd: z.ZodNumber;
+            cache_write_per_million_usd: z.ZodNumber;
+            output_per_million_usd: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            input_per_million_usd: number;
+            cache_read_per_million_usd: number;
+            cache_write_per_million_usd: number;
+            output_per_million_usd: number;
+        }, {
+            input_per_million_usd: number;
+            cache_read_per_million_usd: number;
+            cache_write_per_million_usd: number;
+            output_per_million_usd: number;
+        }>;
+    }, "strip", z.ZodObject<{
+        input_per_million_usd: z.ZodNumber;
+        cache_read_per_million_usd: z.ZodNumber;
+        cache_write_per_million_usd: z.ZodNumber;
+        output_per_million_usd: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        input_per_million_usd: number;
+        cache_read_per_million_usd: number;
+        cache_write_per_million_usd: number;
+        output_per_million_usd: number;
+    }, {
+        input_per_million_usd: number;
+        cache_read_per_million_usd: number;
+        cache_write_per_million_usd: number;
+        output_per_million_usd: number;
+    }>, z.objectOutputType<{
+        default: z.ZodObject<{
+            input_per_million_usd: z.ZodNumber;
+            cache_read_per_million_usd: z.ZodNumber;
+            cache_write_per_million_usd: z.ZodNumber;
+            output_per_million_usd: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            input_per_million_usd: number;
+            cache_read_per_million_usd: number;
+            cache_write_per_million_usd: number;
+            output_per_million_usd: number;
+        }, {
+            input_per_million_usd: number;
+            cache_read_per_million_usd: number;
+            cache_write_per_million_usd: number;
+            output_per_million_usd: number;
+        }>;
+    }, z.ZodObject<{
+        input_per_million_usd: z.ZodNumber;
+        cache_read_per_million_usd: z.ZodNumber;
+        cache_write_per_million_usd: z.ZodNumber;
+        output_per_million_usd: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        input_per_million_usd: number;
+        cache_read_per_million_usd: number;
+        cache_write_per_million_usd: number;
+        output_per_million_usd: number;
+    }, {
+        input_per_million_usd: number;
+        cache_read_per_million_usd: number;
+        cache_write_per_million_usd: number;
+        output_per_million_usd: number;
+    }>, "strip">, z.objectInputType<{
+        default: z.ZodObject<{
+            input_per_million_usd: z.ZodNumber;
+            cache_read_per_million_usd: z.ZodNumber;
+            cache_write_per_million_usd: z.ZodNumber;
+            output_per_million_usd: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            input_per_million_usd: number;
+            cache_read_per_million_usd: number;
+            cache_write_per_million_usd: number;
+            output_per_million_usd: number;
+        }, {
+            input_per_million_usd: number;
+            cache_read_per_million_usd: number;
+            cache_write_per_million_usd: number;
+            output_per_million_usd: number;
+        }>;
+    }, z.ZodObject<{
+        input_per_million_usd: z.ZodNumber;
+        cache_read_per_million_usd: z.ZodNumber;
+        cache_write_per_million_usd: z.ZodNumber;
+        output_per_million_usd: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        input_per_million_usd: number;
+        cache_read_per_million_usd: number;
+        cache_write_per_million_usd: number;
+        output_per_million_usd: number;
+    }, {
+        input_per_million_usd: number;
+        cache_read_per_million_usd: number;
+        cache_write_per_million_usd: number;
+        output_per_million_usd: number;
+    }>, "strip">>;
+}, "strip", z.ZodTypeAny, {
+    usd_to_inr: number;
+    models: {
+        default: {
+            input_per_million_usd: number;
+            cache_read_per_million_usd: number;
+            cache_write_per_million_usd: number;
+            output_per_million_usd: number;
+        };
+    } & {
+        [k: string]: {
+            input_per_million_usd: number;
+            cache_read_per_million_usd: number;
+            cache_write_per_million_usd: number;
+            output_per_million_usd: number;
+        };
+    };
+}, {
+    models: {
+        default: {
+            input_per_million_usd: number;
+            cache_read_per_million_usd: number;
+            cache_write_per_million_usd: number;
+            output_per_million_usd: number;
+        };
+    } & {
+        [k: string]: {
+            input_per_million_usd: number;
+            cache_read_per_million_usd: number;
+            cache_write_per_million_usd: number;
+            output_per_million_usd: number;
+        };
+    };
+    usd_to_inr?: number | undefined;
+}>;
+type PriceCard = z.infer<typeof PriceCardSchema>;
+type Prices = z.infer<typeof PricesSchema>;
+interface TokenCounts {
+    input: number | null;
+    cacheRead: number | null;
+    cacheWrite: number | null;
+    output: number | null;
+}
+interface PhaseTimingRow {
+    phase: string;
+    startedAt: string;
+    endedAt?: string;
+    activeMs: number;
+    open: boolean;
+}
+interface PhaseTiming {
+    activeMs: number;
+    waitMs: number;
+    totalMs: number;
+    phases: PhaseTimingRow[];
+}
+interface ChangePhaseOrder {
+    id: string;
+    /** First phase start. Null when a valid file has no phases. Ignored when invalid. */
+    firstStartedAt: string | null;
+    invalid: boolean;
+}
+interface RenderChangeReportInput {
+    changeId: string;
+    metrics: ChangeMetrics;
+    prices: Prices | null;
+    /** Unicode code points in `.sdd/handoff.md`. Null means that file is missing. */
+    handoffCodePoints: number | null;
+    now: Date;
+}
+/** `Hh Mm Ss` from whole seconds. Negative and non-finite inputs are `0h 0m 0s`. */
+declare function formatDuration(ms: number): string;
+/** Active time per stored visit, plus human wait as the gaps between visits. */
+declare function phaseTiming(phases: readonly PhaseMetric[], now: Date): PhaseTiming;
+/**
+ * Sum category USD from numeric token counts only, then round once.
+ * INR multiplies the unrounded USD sum by `usdToInr`, then rounds once.
+ */
+declare function costFor(counts: TokenCounts, card: PriceCard, usdToInr: number): {
+    usd: string;
+    inr: string;
+};
+/** Parsed prices, null when `.sdd/prices.yaml` is missing, or a throw when it is invalid. */
+declare function loadPrices(projectRoot: string): Promise<Prices | null>;
+/** Plain-text one-change report. Does not read or write the filesystem. */
+declare function renderChangeReport(input: RenderChangeReportInput): string;
+/** Valid files with a first start, then empty phases, then invalid files. Tie-break by id. */
+declare function compareChangesByFirstPhase(left: ChangePhaseOrder, right: ChangePhaseOrder): number;
+declare function readHandoffCodePoints(projectRoot: string): Promise<number | null>;
+/** One-change report. Reads metrics and, when unmeasured, the handoff. Writes nothing. */
+declare function reportChange(input: {
+    projectRoot: string;
+    config: Config;
+    changeId: string;
+    prices: Prices | null;
+    now: Date;
+}): Promise<string>;
+/** Every direct child that has metrics.json, or the empty-result sentence. Writes nothing. */
+declare function reportAllChanges(projectRoot: string, config: Config, prices: Prices | null, now: Date): Promise<string>;
+
+declare function countTokens(text: string): number;
+/** FTS5 tokens. A token character is 0-9, A-Z, a-z, `_`, or a code point above 127. */
+declare function ftsTokens(query: string): string[];
+
+declare class SearchConfigError extends Error {
+    constructor();
+}
+declare const SearchConfigSchema: z.ZodObject<{
+    version: z.ZodDefault<z.ZodLiteral<1>>;
+    provider: z.ZodDefault<z.ZodString>;
+    k: z.ZodDefault<z.ZodNumber>;
+    embeddings: z.ZodDefault<z.ZodBoolean>;
+    budgets: z.ZodDefault<z.ZodObject<{
+        default: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodNumber, z.objectOutputType<{
+        default: z.ZodDefault<z.ZodNumber>;
+    }, z.ZodNumber, "strip">, z.objectInputType<{
+        default: z.ZodDefault<z.ZodNumber>;
+    }, z.ZodNumber, "strip">>>;
+    exclude: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    version: 1;
+    exclude: string[];
+    provider: string;
+    k: number;
+    embeddings: boolean;
+    budgets: {
+        default: number;
+    } & {
+        [k: string]: number;
+    };
+}, {
+    version?: 1 | undefined;
+    exclude?: string[] | undefined;
+    provider?: string | undefined;
+    k?: number | undefined;
+    embeddings?: boolean | undefined;
+    budgets?: z.objectInputType<{
+        default: z.ZodDefault<z.ZodNumber>;
+    }, z.ZodNumber, "strip"> | undefined;
+}>;
+type SearchConfig = z.infer<typeof SearchConfigSchema>;
+declare function budgetForStage(config: SearchConfig, stage: string | undefined): number;
+declare function loadSearchConfig(projectRoot: string): Promise<SearchConfig>;
+
+type SearchScope = "code" | "specs" | "memory";
+interface SearchQuery {
+    scope: SearchScope;
+    k: number;
+    budget: number;
+    /** Header text counted against the budget. Empty for context and handoff. */
+    preamble?: string;
+}
+interface SearchHit {
+    scope: SearchScope;
+    path: string;
+    startLine: number;
+    endLine: number;
+    symbol: string;
+    /**
+     * Keyword hits store raw SQLite bm25() (more negative is better).
+     * Hybrid hits store the RRF score (higher is better).
+     */
+    score: number;
+    form: "full" | "signature" | "summary";
+    text: string;
+    signature: string;
+    body: string;
+    language: string;
+}
+interface SearchResult {
+    provider: "builtin";
+    warning?: string;
+    query: string;
+    scope: SearchScope;
+    budget: number;
+    usedTokens: number;
+    hits: SearchHit[];
+    text: string;
+}
+interface IndexStats {
+    provider: "builtin";
+    files: number;
+    chunks: number;
+    lastIndexFilesConsidered: number;
+    lastIndexFilesReindexed: number;
+    lastIndexChunksReindexed: number;
+    lastIndexChunksEmbedded: number;
+    indexedCommit: string | null;
+}
+interface SearchProvider {
+    readonly id: string;
+    index(changed?: readonly string[]): Promise<IndexStats>;
+    search(query: string, options: SearchQuery): Promise<SearchResult>;
+    stats(): Promise<IndexStats>;
+}
+interface RawHit {
+    scope: SearchScope;
+    path: string;
+    startLine: number;
+    endLine: number;
+    symbol: string;
+    score: number;
+    signature: string;
+    body: string;
+    language: string;
+    /** Not printed. Keyword rows are bm25. Fused rows are rrf. */
+    rankedBy?: "bm25" | "rrf";
+    /** Pack-time extract. Absent for code and for the active change. */
+    summary?: string;
+}
+
+declare function searchPreamble(query: string, scope: string, budget: number, hybrid?: boolean): string;
+declare function renderBlock(hit: RawHit, form: "full" | "signature" | "summary"): string;
+declare function packHits(input: {
+    preamble: string;
+    hits: readonly RawHit[];
+    budget: number;
+}): {
+    text: string;
+    usedTokens: number;
+    hits: SearchHit[];
+};
+
+declare function isHardDenied(rel: string): boolean;
+/**
+ * Directories the walker does not open. A directory whose basename merely
+ * contains "secret" (the fixture `secret-nest`) is not pruned: `isSecretPath`
+ * applies to the file itself, and `packages/secret-nest/shown.ts` is allowed.
+ */
+declare function isPrunedDir(rel: string): boolean;
+declare function loadExcluder(projectRoot: string, exclude: readonly string[]): Promise<(rel: string) => boolean>;
+
+interface MarkdownChunk {
+    symbol: string;
+    startLine: number;
+    endLine: number;
+    signature: string;
+    body: string;
+}
+declare function chunkMarkdown(text: string): MarkdownChunk[];
+
+declare const SUMMARY_TOKEN_CAP = 80;
+/** Deterministic extract. Same signature and body always return the same string. */
+declare function extractiveSummary(signature: string, body: string): string;
+
+declare function resolveActiveDirectory(projectRoot: string, config: Config): Promise<string>;
+
+interface CodeChunk {
+    symbol: string;
+    startLine: number;
+    endLine: number;
+    signature: string;
+    body: string;
+    language: string;
+}
+declare function chunkCode(text: string, ext: string): Promise<CodeChunk[] | null>;
+
+declare const EMBEDDING_MODEL = "BAAI/bge-small-en-v1.5";
+declare const EMBEDDINGS_UNAVAILABLE = "Embeddings are unavailable. Using keyword search.";
+interface Embedder {
+    /** One L2-normalized vector per text, same order. Text is the raw chunk body. */
+    embedPassages(texts: readonly string[]): Promise<Float32Array[]>;
+    /** One L2-normalized vector for the raw user query. */
+    embedQuery(text: string): Promise<Float32Array>;
+}
+interface SearchRuntime {
+    embedder?: Embedder;
+    /** Called instead of fastembed. A throw is an embedder failure. */
+    embedderFactory?: () => Promise<Embedder>;
+}
+type EmbedFailure = "none" | "load" | "query";
+interface FastembedModel {
+    passageEmbed(texts: readonly string[], batchSize: number): AsyncIterable<ArrayLike<number>[]>;
+    queryEmbed(text: string): Promise<ArrayLike<number>>;
+}
+type FastembedInit = (options: {
+    model: unknown;
+    executionProviders: unknown[];
+    maxLength: number;
+    showDownloadProgress: boolean;
+    cacheDir: string;
+}) => Promise<FastembedModel>;
+interface FastembedHooks {
+    init?: FastembedInit;
+}
+/** Incremented only when the embeddings-on path evaluates `import("fastembed")`. */
+declare let fastembedImportCount: number;
+/** Fastembed adapter. One successful session per cache directory per process. */
+declare function createFastembedEmbedder(projectRoot: string, hooks?: FastembedHooks): Promise<Embedder>;
+/** Embeddings off returns null and does not import fastembed. */
+declare function resolveEmbedder(projectRoot: string, embeddings: boolean, runtime?: SearchRuntime): Promise<Embedder | null>;
+declare function embedSearchQuery(embedder: Embedder | null, embeddings: boolean, query: string): Promise<{
+    queryVec: Float32Array | null;
+    failure: EmbedFailure;
+}>;
+
+interface RankSession {
+    embeddings: boolean;
+    queryVec: Float32Array | null;
+    failure: EmbedFailure;
+}
+declare function scopeForPath(rel: string, config: Config): SearchScope | null;
+declare function createBuiltinProvider(projectRoot: string, config: Config, runtime?: SearchRuntime): SearchProvider;
+declare function keywordHits(projectRoot: string, query: string, scope: SearchScope, k: number): Promise<RawHit[]>;
+declare function listScopeHits(projectRoot: string, scope: SearchScope): Promise<RawHit[]>;
+declare function rankScope(projectRoot: string, query: string, scope: SearchScope, k: number, session: RankSession): Promise<{
+    hits: RawHit[];
+    warning: boolean;
+    hybrid: boolean;
+}>;
+
+declare const RRF_K = 60;
+declare function rrf(rank: number | undefined): number;
+interface RankInput {
+    id: string;
+    path: string;
+    startLine: number;
+    symbol: string;
+    keywordRank?: number;
+    vectorRank?: number;
+}
+/** Pure fusion. Higher score first, then path, start line, and symbol. */
+declare function fuseByRank(entries: readonly RankInput[]): {
+    id: string;
+    score: number;
+}[];
+/** Union of the two source lists. Does not cut the result to k. */
+declare function fuseHits(keyword: readonly RawHit[], vector: readonly RawHit[]): RawHit[];
+/**
+ * All-bm25 keeps the S1 sort. Any rrf hit is emitted first by RRF descending,
+ * then bm25 hits by BM25 ascending. The two scores are never compared.
+ */
+declare function mergeRankedHits(hits: readonly RawHit[]): RawHit[];
+
+declare function registerSearchProvider(provider: SearchProvider): void;
+declare function clearRegisteredSearchProviders(): void;
+declare function fallbackWarning(name: string): string;
+declare function resolveSearchProvider(projectRoot: string, config: Config, search: SearchConfig, runtime?: SearchRuntime): SearchProvider;
+declare function buildRetrievedInner(projectRoot: string, config: Config, title: string, stage: string | undefined, budget: number | undefined, runtime?: SearchRuntime, activeChange?: string): Promise<string>;
+declare function executeSearch(projectRoot: string, config: Config, query: string, scope: SearchScope, budget: number | undefined): Promise<SearchResult>;
+
+interface SyncChangeResult {
+    changeId: string;
+    headSha: string;
+    updatedResults: number;
+    reportUpdated: boolean;
+    reportPreserved: boolean;
+}
+declare function syncChangeHead(projectRoot: string, config: Config, changeId: string, opts?: {
+    headSha?: string | null;
+}): Promise<SyncChangeResult>;
 
 declare function listWorkflowNames(projectRoot: string): Promise<string[]>;
 declare function loadWorkflow(projectRoot: string, name: string): Promise<Workflow>;
@@ -1154,7 +1857,10 @@ declare function recommendWorkflow(projectRoot: string, title: string, config: C
 
 interface ChangeContext {
     id: string;
+    /** Absolute directory used for file reads and writes. */
     path: string;
+    /** Repo-relative directory for status, handoff, and active-context text. */
+    displayPath: string;
     meta: ChangeMeta;
     workflow: Workflow;
     stages: Stage[];
@@ -1188,13 +1894,13 @@ declare function fallbackIncompleteStageId(ctx: ChangeContext): Promise<string |
 declare function approveGate(projectRoot: string, config: Config, changeId: string, stageId: string | undefined, note?: string, status?: "approved" | "waived" | "failed"): Promise<ChangeContext>;
 
 declare function formatStatus(ctx: ChangeContext): string;
-declare function buildAgentPrompt(ctx: ChangeContext, config: Config, projectRoot: string): Promise<string>;
+declare function buildAgentPrompt(ctx: ChangeContext, config: Config, projectRoot: string, budget?: number, runtime?: SearchRuntime): Promise<string>;
 
 /**
  * Artifact content quality — existence alone is not "stage complete"
  * (templates are materialized on stage entry and would otherwise auto-pass).
  */
-/** Strip comments/headings/empty bullets; require real prose. */
+/** Strip comments/headings/empty bullets/instructional template prose; require real prose. */
 declare function isSubstantiveArtifactContent(content: string): boolean;
 
 interface CreateChangeInput {
@@ -1205,6 +1911,9 @@ interface CreateChangeInput {
     domain?: string;
     flags?: Record<string, boolean | string | number>;
     branch?: string;
+    epic?: string;
+    story?: string;
+    depends?: string[];
 }
 interface AdvanceResult {
     ctx: ChangeContext;
@@ -1226,6 +1935,76 @@ declare function completeChange(projectRoot: string, config: Config, changeId: s
     promoted?: string[];
 }>;
 
+/**
+ * Typed, user-facing errors for sdd core.
+ * CLI maps these to exit codes and optional hints.
+ */
+declare class SddError extends Error {
+    readonly code: string;
+    readonly hint?: string;
+    readonly exitCode: number;
+    constructor(message: string, options?: {
+        code?: string;
+        hint?: string;
+        exitCode?: number;
+        cause?: unknown;
+    });
+}
+declare function isSddError(err: unknown): err is SddError;
+/** Normalize unknown throws into Error for logging. */
+declare function errorMessage(err: unknown): string;
+
+/**
+ * Markers for files sdd generates outside its own state (AGENTS.md, host agent
+ * stubs, protocol). The marker carries a sha256 of the generated body, so sdd
+ * can tell three cases apart:
+ *
+ * - `unmodified`: sdd wrote it and nobody changed it. Safe to regenerate or remove.
+ * - `edited`: sdd wrote it, then someone edited it. Never overwrite or delete.
+ * - `not-generated`: no marker (a user's own file, another tool's, or an old sdd
+ *   version's). Never overwrite or delete.
+ */
+type GeneratedState = "unmodified" | "edited" | "not-generated";
+/** Line endings are normalized (CRLF → LF) so a Windows/autocrlf checkout is not "edited". */
+declare function contentHash(body: string): string;
+/** Insert the marker after YAML front matter (agent hosts parse it) or at the top. */
+declare function markGenerated(body: string): string;
+declare function generatedState(content: string): GeneratedState;
+/**
+ * Why a file was left alone:
+ * - `not-generated` / `edited`: see {@link GeneratedState}
+ * - `symlink`: a symbolic link (or a path through one); sdd never follows, writes
+ *   through, or deletes through links
+ * - `unreadable`: could not be read, so sdd cannot prove it generated it
+ */
+type KeptReason = "not-generated" | "edited" | "symlink" | "unreadable";
+interface KeptFile {
+    /** Project-relative path */
+    path: string;
+    reason: KeptReason;
+}
+declare const GeneratedManifestSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    files: z.ZodRecord<z.ZodString, z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    version: 1;
+    files: Record<string, string>;
+}, {
+    version: 1;
+    files: Record<string, string>;
+}>;
+type GeneratedManifest = z.infer<typeof GeneratedManifestSchema>;
+interface ReconcileGeneratedResult {
+    created: string[];
+    refreshed: string[];
+    kept: KeptFile[];
+    changed: boolean;
+}
+declare function loadGeneratedManifest(path: string): Promise<GeneratedManifest>;
+declare function saveGeneratedManifest(path: string, manifest: GeneratedManifest): Promise<void>;
+declare function reconcileGeneratedTree(projectRoot: string, sourceDir: string, destinationDir: string, destinationRelative: string, manifest: GeneratedManifest, force: boolean): Promise<ReconcileGeneratedResult>;
+declare function describeKept(k: KeptFile): string;
+
 /**
  * AI coding agents (not IDEs).
  * Speckit-style: one integration at a time; public keys: `copilot` | `claude` | `grok` | `ollama` | `kilo`.
@@ -1269,10 +2048,36 @@ declare function optionForTarget(target: AgentTarget): AgentTargetOption;
  * Never includes shared SDD dirs (memory, changes, .sdd) or whole .github (workflows stay).
  */
 declare function agentHostPaths(target: AgentTarget): string[];
+interface RemoveAgentHostsResult {
+    /** Project-relative files and directories sdd removed */
+    removed: string[];
+    /** Files left in place because sdd did not generate them, they were edited, or are links */
+    kept: KeptFile[];
+}
+/** Turn a raw fs error (EACCES, EISDIR, …) into a sentence naming the path. */
+declare function describeFsError(err: unknown, action: string, rel: string): string;
+/** Thrown before anything is written when sdd cannot safely install agent files. */
+declare class AgentInstallPreflightError extends SddError {
+    readonly problems: string[];
+    constructor(problems: string[]);
+}
+/** Files sdd would remove from other hosts' folders, and what it leaves alone. */
+interface RemovalPlan {
+    remove: string[];
+    kept: KeptFile[];
+}
 /**
- * Remove agent files for hosts other than `keep` (and legacy IntelliJ notes).
+ * Remove agent files for hosts other than `keep`, but only files sdd generated
+ * and nobody edited since (marker + content hash). User files, edited files,
+ * symlinks and other tools' files in those folders are kept and reported.
+ * Never follows symlinks. Only folders emptied by this removal are pruned.
  * Does not touch .sdd/, memory/, changes/, or non-agent .github content.
  */
+declare function removeOtherAgentHostsDetailed(projectRoot: string, keep: AgentTarget): Promise<RemoveAgentHostsResult>;
+/**
+ * Remove sdd-generated, unedited agent files for hosts other than `keep`.
+ * Returns the removed paths. See {@link removeOtherAgentHostsDetailed} for kept files.
+ */
 declare function removeOtherAgentHosts(projectRoot: string, keep: AgentTarget): Promise<string[]>;
 /** Parse one Speckit-style integration key. */
 declare function parseIntegration(raw: string): AgentTarget;
@@ -1298,7 +2103,12 @@ interface InstallAgentOptions {
 }
 interface InstallAgentResult {
     created: string[];
+    /** sdd-generated, unedited files that already existed (re-run with force to regenerate) */
     skipped: string[];
+    /** Files never overwritten or deleted: not generated by sdd, or edited since */
+    kept: KeptFile[];
+    /** Other hosts' sdd-generated files that were removed */
+    removed: string[];
     target: AgentTarget;
 }
 /** @deprecated Use InstallAgentOptions / installAgentIntegration. */
@@ -1313,6 +2123,30 @@ type InstallAgentsResult = {
     skipped: string[];
     targets: AgentTarget[];
 };
+/** What installAgentIntegration would do with one generated file. */
+interface PlannedWrite {
+    rel: string;
+    content: string;
+    /** create: new file · overwrite: unmodified sdd file + force · skip: unmodified, no force · keep: never touched */
+    action: "create" | "overwrite" | "skip" | "keep";
+    keptReason?: KeptFile["reason"];
+    /** For symlinks on the path: the link itself */
+    keptPath?: string;
+}
+interface AgentInstallPlan {
+    writes: PlannedWrite[];
+    removal: RemovalPlan;
+    /** Reasons the install cannot proceed safely; empty when it can */
+    problems: string[];
+}
+/**
+ * Work out every write and removal for an agent install without touching the disk,
+ * and collect anything that would make it fail half-way (a directory where a file
+ * goes, unreadable or read-only files, non-writable folders).
+ */
+declare function planAgentIntegration(opts: InstallAgentOptions): Promise<AgentInstallPlan>;
+/** Throw {@link AgentInstallPreflightError} (before any write) if the install cannot finish. */
+declare function assertAgentInstallable(opts: InstallAgentOptions): Promise<void>;
 /**
  * Install thin agents for **one** AI integration (registry-driven).
  * Writes protocol + active-context + role stubs + single `.sdd/agents.json` snapshot.
@@ -1323,8 +2157,8 @@ declare function installAgentIntegration(opts: InstallAgentOptions): Promise<Ins
  * Prefer installAgentIntegration for product flows.
  */
 declare function installAgentIntegrations(opts: InstallAgentsOptions): Promise<InstallAgentsResult>;
-/** Thin agent body shared across hosts (same text). */
-declare function renderThinAgent(role: SddAgentRole): string;
+/** Thin agent body shared across hosts (same text). Paths come from config. */
+declare function renderThinAgent(role: SddAgentRole, config?: Config): string;
 interface InstalledAgentSnapshot {
     /** Public key: copilot | claude | grok | ollama | kilo */
     ai: string;
@@ -1337,7 +2171,7 @@ declare function loadInstalledAgent(projectRoot: string): Promise<InstalledAgent
  * Write `.sdd/handoff.md` for the active (or given) change — full agent brief.
  * Used by `sdd agent` and auto-launch after `sdd new`.
  */
-declare function writeAgentHandoff(projectRoot: string, config: Config, changeId: string): Promise<string>;
+declare function writeAgentHandoff(projectRoot: string, config: Config, changeId: string, budget?: number, runtime?: SearchRuntime): Promise<string>;
 /** Short kickoff line to pass into agent CLIs (full brief is in handoff.md). */
 declare function agentKickoffMessage(opts: {
     title: string;
@@ -1350,34 +2184,60 @@ declare function agentKickoffMessage(opts: {
      * (used by sdd refine and other specialized modes).
      */
     instructions?: string;
+    /** Configured folders; defaults keep existing `memory/` and `changes/` wording. */
+    memoryPath?: string;
+    changesPath?: string;
 }): string;
 /** Write .sdd/active-context.md for the current change. */
 declare function refreshActiveAgentContext(projectRoot: string): Promise<string | null>;
-/** Single playbook — only long agent-facing content we author once. */
-declare const PROTOCOL_MD = "# SDD protocol\n\nThis repo uses **Structured Vibe Coding** (`sdd`). Agents must follow this file plus `.sdd/active-context.md`. Do not invent a parallel process.\n\n## Source of truth\n\n| What | Where |\n|------|--------|\n| Process state | `changes/<id>/meta.yaml` (workflow, stage, gates) |\n| Current task snapshot | `.sdd/active-context.md` |\n| Non-negotiables | `memory/constitution.md` if present |\n| Stable product/tech rules | `memory/*.md` (start at `memory/index.md` if present) |\n| Stage artifacts | files in `changes/<id>/` for the active change |\n\n## Required read order\n\n1. `.sdd/active-context.md`\n2. This file (`.sdd/protocol.md`)\n3. `memory/constitution.md` if present (non-negotiables agents must not violate)\n4. `meta.yaml` + artifacts for the **current stage** (and prior stages if needed)\n5. `memory/index.md` (documentation map) if present, then linked memory pages when architecture or conventions matter\n\n## Stage behavior\n\n| Stage kind | Agent focus |\n|------------|-------------|\n| intent / feature / stories | Clarify scope; write short artifacts |\n| design / lld / db / research / hl_arb | Specs and decisions; minimal product code |\n| tasks | Break work into implementable checklist |\n| implement | Code only for this change; follow tasks/acceptance |\n| local_verify | Check acceptance; fix only; prepare for complete |\n| brainstorm (optional) | Multiple approaches; parallel exploration; no final design yet |\n| clarify_* (optional) | Ask clarifying questions; write Q&A; or tell human to skip |\n\n## Optional stages\n\n- Stages marked **optional** / kind `brainstorm` or `clarify` may be skipped:  \n  `sdd skip <stage_id> -r \"not needed\"`\n- Do **not** invent a skip by jumping stages. `sdd next` blocks on empty required stubs (e.g. design.md).\n- If the tool falls back to an earlier stage, **complete that stage** before advancing again.\n\n## Hard rules\n\n1. **Do not skip hard gates.** If blocked, tell the human to run `sdd gate approve` (or fix the gate).\n2. **Stay in scope** of the active change title/intent. No drive-by refactors or new features.\n3. **Honor constraints** in `arb-decision.md`, design, and memory non-negotiables.\n4. **Local verify** is part of done when the workflow has a verify stage: `sdd verify`.\n5. Prefer small, reviewable diffs.\n6. **Required stage artifacts must be substantive** \u2014 not empty templates. Design cannot be skipped via empty design.md.\n\n## Commands (human / shell)\n\n```bash\nsdd status\nsdd next\nsdd agent              # print handoff\nsdd agents refresh     # refresh active-context.md\nsdd verify\nsdd complete\n```\n\n## Out of scope for agents\n\n- Replacing CI/CD or team process tools\n- Deleting `.sdd` / completed change history\n- Claiming complete without verify when required\n";
+/** Default-path protocol text. Generated files use {@link renderProtocolMd}. */
+declare const PROTOCOL_MD: string;
+/** Single playbook — paths come from project config, not hard-coded defaults. */
+declare function renderProtocolMd(config: Pick<Config, "memory_path" | "changes_path">): string;
+declare function renderAgentsMd(integ: AgentIntegration, config?: Config): string;
 
 interface InitOptions {
     projectRoot: string;
     force?: boolean;
+    /** Place memory, changes, domains, and archive beneath this project-relative root. */
+    layoutRoot?: string;
     /**
      * AI coding agent to install (single, Speckit-style). Not an IDE.
      * - omit / `false` — no agent files
      * - `AgentTarget` — install that integration only
      */
     agents?: false | AgentTarget;
+    /**
+     * Test seam for "is this path tracked?". Return null when git cannot answer.
+     * Production uses `git ls-files`.
+     */
+    indexLookup?: (projectRoot: string, relativePaths: string[]) => Promise<string[] | null>;
 }
 interface InitResult {
     created: string[];
     config: Config;
+    warnings: string[];
+    /** Existing files init left alone: not generated by sdd, or edited since */
+    kept: KeptFile[];
     agents?: {
         created: string[];
         skipped: string[];
+        kept: KeptFile[];
+        removed: string[];
     };
 }
 declare function initProject(opts: InitOptions): Promise<InitResult>;
+/** Append missing required ignore lines. Does not rewrite config, memory, or workflows. */
+declare function repairRequiredIgnores(projectRoot: string): Promise<boolean>;
 
+/** pass: every command ran and exited 0 · fail: a command failed · not_run: nothing was executed */
+type VerifyStatus = "pass" | "fail" | "not_run";
 interface VerifyResult {
     stageId: string;
+    /** Overall outcome; never "pass" unless at least one command ran and all exited 0 */
+    status: VerifyStatus;
+    /** Why the status is not "pass" (human readable) */
+    reason?: string;
     results: {
         name: string;
         command: string;
@@ -1387,13 +2247,21 @@ interface VerifyResult {
     checklist: string[];
     /** Path to evidence dir when configured; null when no evidence_dir is set */
     evidencePath: string | null;
-    /** False if any required command failed or was not run when required */
+    /** local-test-results.md that was written; null when nothing was recorded (wrong stage) */
+    resultsPath: string | null;
+    /** True only when status is "pass" */
     ok: boolean;
 }
 declare function runLocalVerify(projectRoot: string, config: Config, changeId: string, opts?: {
     runCommands?: boolean;
+    headSha?: string | null;
 }): Promise<VerifyResult>;
 
+/**
+ * Lowercase, strip quotes, collapse non-alphanumerics to `-`.
+ * At most 60 characters, cut only on token boundaries.
+ * A trailing `#NNN` is kept whole when it fits, never sliced into a shorter number.
+ */
 declare function slugify(input: string): string;
 declare function todayIsoDate(d?: Date): string;
 declare function nowIso(d?: Date): string;
@@ -1412,6 +2280,8 @@ declare function defaultWorkflowsDir(): string;
 declare function defaultTemplatesDir(): string;
 declare function defaultMemoryDir(): string;
 declare function defaultMcpYamlPath(): string;
+declare function defaultPricesYamlPath(): string;
+declare function defaultSearchYamlPath(): string;
 
 declare function pathExists(path: string): Promise<boolean>;
 declare function ensureDir(path: string): Promise<void>;
@@ -1431,25 +2301,6 @@ declare function copyDirSkipExisting(src: string, dest: string): Promise<void>;
 declare function writeTextIfMissing(path: string, content: string): Promise<boolean>;
 declare function removePath(path: string): Promise<void>;
 
-/**
- * Typed, user-facing errors for sdd core.
- * CLI maps these to exit codes and optional hints.
- */
-declare class SddError extends Error {
-    readonly code: string;
-    readonly hint?: string;
-    readonly exitCode: number;
-    constructor(message: string, options?: {
-        code?: string;
-        hint?: string;
-        exitCode?: number;
-        cause?: unknown;
-    });
-}
-declare function isSddError(err: unknown): err is SddError;
-/** Normalize unknown throws into Error for logging. */
-declare function errorMessage(err: unknown): string;
-
 /**
  * Sanitize env maps for child processes (MCP stdio, verify commands).
  */
@@ -1458,6 +2309,16 @@ declare function toProcessEnv(base: NodeJS.ProcessEnv | Record<string, string |
 
 declare const SDD_CORE_VERSION: string;
 
+/** `.sdd/README.md` body. Paths come from config. */
+declare function renderSddReadme(config: Pick<Config, "memory_path" | "changes_path">): string;
+/** Documentation map. Paths come from config. */
+declare function renderMemoryIndex(config: Pick<Config, "memory_path" | "changes_path">): string;
+/**
+ * Rewrite generated guidance that still names the default folders when config
+ * uses other paths. Edited files are left alone.
+ */
+declare function refreshConfiguredGuidance(projectRoot: string, config: Config): Promise<void>;
+
 /**
  * Public + internal types for the on-demand structure-aware code context pipeline.
  * Contracts: LLD §2.1 / research §6.5.
@@ -1498,7 +2359,7 @@ interface CodeContextRequest {
      */
     writeArtifactTo?: string | null;
 }
-type CodeContextGapCode = "no_focus" | "path_missing" | "path_denied_secret" | "path_ignored" | "unsupported_language" | "parse_error" | "empty_extract" | "cap_truncated" | "no_active_change" | "change_not_found" | "adapter_unavailable";
+type CodeContextGapCode = "no_focus" | "path_missing" | "path_denied_secret" | "path_ignored" | "unsupported_language" | "parse_error" | "empty_extract" | "cap_truncated" | "no_active_change" | "change_not_found" | "adapter_unavailable" | "embeddings_unavailable";
 interface CodeContextGap {
     code: CodeContextGapCode;
     message: string;
@@ -1664,10 +2525,12 @@ declare const fallbackAdapter: LanguageAdapter;
  * Public entry: generateCodeContext
  */
 
-/** Optional deps for tests (inject adapters). */
+/** Optional deps for tests (inject adapters or an embedder). */
 type GenerateCodeContextDeps = {
     adapters?: LanguageAdapter[];
     now?: () => Date;
+    embedder?: SearchRuntime["embedder"];
+    embedderFactory?: SearchRuntime["embedderFactory"];
 };
 /**
  * Main entry: on-demand pipeline. Partial success returns ok:true with gaps.
@@ -1900,11 +2763,11 @@ declare const McpSourceSchema: z.ZodObject<{
         intents: string[];
     };
     priority: number;
+    enabled: boolean;
     args: string[];
     transport: "stdio";
     command: string;
     env: Record<string, string>;
-    enabled: boolean;
     cwd?: string | undefined;
     invoke?: {
         tool: string;
@@ -1922,11 +2785,11 @@ declare const McpSourceSchema: z.ZodObject<{
         intents?: string[] | undefined;
     } | undefined;
     priority?: number | undefined;
+    enabled?: boolean | undefined;
+    cwd?: string | undefined;
     args?: string[] | undefined;
     transport?: "stdio" | undefined;
     env?: Record<string, string> | undefined;
-    cwd?: string | undefined;
-    enabled?: boolean | undefined;
     invoke?: {
         tool: string;
         args?: Record<string, unknown> | undefined;
@@ -2009,11 +2872,11 @@ declare const McpConfigSchema: z.ZodObject<{
             intents: string[];
         };
         priority: number;
+        enabled: boolean;
         args: string[];
         transport: "stdio";
         command: string;
         env: Record<string, string>;
-        enabled: boolean;
         cwd?: string | undefined;
         invoke?: {
             tool: string;
@@ -2031,11 +2894,11 @@ declare const McpConfigSchema: z.ZodObject<{
             intents?: string[] | undefined;
         } | undefined;
         priority?: number | undefined;
+        enabled?: boolean | undefined;
+        cwd?: string | undefined;
         args?: string[] | undefined;
         transport?: "stdio" | undefined;
         env?: Record<string, string> | undefined;
-        cwd?: string | undefined;
-        enabled?: boolean | undefined;
         invoke?: {
             tool: string;
             args?: Record<string, unknown> | undefined;
@@ -2056,11 +2919,11 @@ declare const McpConfigSchema: z.ZodObject<{
             intents: string[];
         };
         priority: number;
+        enabled: boolean;
         args: string[];
         transport: "stdio";
         command: string;
         env: Record<string, string>;
-        enabled: boolean;
         cwd?: string | undefined;
         invoke?: {
             tool: string;
@@ -2083,11 +2946,11 @@ declare const McpConfigSchema: z.ZodObject<{
             intents?: string[] | undefined;
         } | undefined;
         priority?: number | undefined;
+        enabled?: boolean | undefined;
+        cwd?: string | undefined;
         args?: string[] | undefined;
         transport?: "stdio" | undefined;
         env?: Record<string, string> | undefined;
-        cwd?: string | undefined;
-        enabled?: boolean | undefined;
         invoke?: {
             tool: string;
             args?: Record<string, unknown> | undefined;
@@ -2188,4 +3051,135 @@ declare function gatherMcpContextForChange(projectRoot: string, ctx: ChangeConte
 declare function formatMcpContextForHandoff(results: McpFetchResult[]): string;
 declare function listMatchingSourceIds(sources: McpSource[], match: McpMatchContext): string[];
 
-export { AGENT_INTEGRATIONS, AGENT_TARGET_OPTIONS, ALL_AGENT_TARGETS, type AdapterExtractResult, AdapterRegistry, type AdvanceResult, type AgentIntegration, type AgentTarget, type AgentTargetOption, type ArtifactDef, ArtifactDefSchema, type BuildRefinePlanOptions, type CallMcpToolResult, type ChangeContext, type ChangeMeta, ChangeMetaSchema, type CodeContextCaps, type CodeContextGap, type CodeContextGapCode, type CodeContextRequest, type CodeContextResult, type CodeContextSummary, type CodeSlice, type Complexity, type Config, ConfigSchema, type CreateChangeInput, DEFAULT_CODE_CONTEXT_CAPS, DEFAULT_INIT_INTEGRATION, type FocusPlan, type Gate, GateSchema, type GatherMcpOptions, type GenerateCodeContextDeps, type GreenfieldFeature, type InitOptions, type InitResult, type InstallAgentOptions, type InstallAgentResult, type InstallAgentsOptions, type InstallAgentsResult, type InstalledAgentSnapshot, type LanguageAdapter, type McpConfig, McpConfigSchema, type McpFetchResult, type McpInvoke, McpInvokeSchema, type McpMatchContext, type McpSource, McpSourceSchema, type McpWhen, McpWhenSchema, PROTOCOL_MD, type RefineArtifactRef, type RefineMode, type RefinePlan, SDD_AGENT_ROLES, SDD_CORE_VERSION, SDD_DIR, type SddAgentRole, type SddAgentRoleId, SddError, type Stage, StageSchema, type StartFeatureInput, type StartGreenfieldInput, type StartGreenfieldResult, type SymbolInfo, type SymbolKind, VerifyCommandSchema, type VerifyResult, type Workflow, WorkflowSchema, activePointerPath, activeStages, addMcpSource, advanceStage, agentHostPaths, agentKickoffMessage, approveGate, archiveDir, buildAgentPrompt, buildContext, buildRefinePlan, callMcpSourceTool, canLeaveStage, changeDirName, changeMetaPath, changePath, changesDir, classifyPath, clearActiveIf, completeChange, configPath, copyDir, copyDirSkipExisting, createChange, defaultConfig, defaultMcpConfig, defaultMcpYamlPath, defaultMemoryDir, defaultTemplatesDir, defaultWorkflowsDir, defaultsRoot, domainsDir, ensureDir, ensureMcpConfig, errorMessage, explainMatch, fallbackAdapter, fallbackIncompleteStageId, findFeaturesBacklogPath, firstActiveStageId, formatJsonSummary, formatMcpContextForHandoff, formatStatus, gatherMcpContext, gatherMcpContextForChange, generateCodeContext, getActiveChangeId, getIntegration, getStage, incompletePriorStageErrors, inferComplexity, initProject, installAgentIntegration, installAgentIntegrations, integrationKeyFor, interpolate, interpolateArgs, isIgnoredPath, isInitialized, isSddError, isSecretPath, isStageSkipped, isSubstantiveArtifactContent, listBacklogFeatures, listChanges, listDirs, listFiles, listMatchingSourceIds, listMcpSourceTools, listWorkflowNames, loadChangeMeta, loadConfig, loadInstalledAgent, loadMcpConfig, loadWorkflow, matchMcpSources, mcpConfigPath, mcpTimeoutMs, memoryDir, mergeCaps, nextStageId, nowIso, optionForTarget, parseAgentTargets, parseFeaturesBacklog, parseIntegration, pathExists, promoteGreenfieldToMemory, readText, readYaml, recommendWorkflow, refreshActiveAgentContext, removeMcpSource, removeOtherAgentHosts, removePath, renderThinAgent, resolveChangeId, resolveFocus, resolveStages, runLocalVerify, saveChangeMeta, saveConfig, saveMcpConfig, sddRoot, setActiveChange, shouldAutoSkip, skipStage, slugify, startFeatureFromBacklog, startGreenfield, switchWorkflow, templatesDir, toProcessEnv, todayIsoDate, tokenizeKeywords, typescriptAdapter, uniqueChangeDirName, updateFeatureStatus, withMcpSource, workflowsDir, writeAgentHandoff, writeRefineBrief, writeText, writeTextIfMissing, writeYaml };
+interface RoleProfile {
+    name: string;
+    label: string;
+    job: string;
+    description: string;
+    askFirst: boolean;
+    pinned: boolean;
+    hidden: boolean;
+}
+interface RoleModel {
+    complete(input: {
+        roleId: string;
+        prompt: string;
+    }): Promise<string>;
+}
+interface RoleCommandResult {
+    exitCode: number;
+    stdout: string;
+    runId?: string;
+}
+
+declare function setRoleMessaging(root: string, enabled: boolean): Promise<RoleCommandResult>;
+declare function handoffRole(root: string, input: {
+    from: string;
+    to: string;
+    task?: string;
+    change?: string;
+    section?: string;
+    model?: RoleModel;
+    now?: () => Date;
+}): Promise<RoleCommandResult>;
+declare function showRoleGroup(root: string, changeId: string): Promise<RoleCommandResult>;
+declare function planNetwork(root: string, input: {
+    change?: string;
+    section?: string;
+    task?: string;
+    model?: RoleModel;
+    now?: () => Date;
+}): Promise<RoleCommandResult>;
+declare function acceptNetwork(root: string, input: {
+    change?: string;
+    section?: string;
+}): Promise<RoleCommandResult>;
+declare function runNetwork(root: string, input: {
+    change?: string;
+    section?: string;
+    model?: RoleModel;
+    now?: () => Date;
+}): Promise<RoleCommandResult>;
+declare function rebuildNetwork(root: string, input: {
+    change?: string;
+    section?: string;
+    model?: RoleModel;
+    now?: () => Date;
+}): Promise<RoleCommandResult>;
+
+interface RunRoleInput {
+    name: string;
+    task?: string;
+    withRole?: string;
+    kind?: string;
+    section?: string;
+    change?: string;
+    stop?: boolean;
+    model?: RoleModel;
+    now?: () => Date;
+}
+interface AllowRoleInput {
+    runId: string;
+    mode: "once" | "always" | "deny";
+    now?: () => Date;
+}
+declare function runRole(root: string, input: RunRoleInput): Promise<RoleCommandResult>;
+declare function allowRole(root: string, input: AllowRoleInput): Promise<RoleCommandResult>;
+
+declare function createRole(root: string, input: {
+    name: string;
+    label: string;
+    job: string;
+    description?: string;
+    askFirst?: boolean;
+}): Promise<RoleCommandResult>;
+declare function editRole(root: string, nameInput: string, patch: {
+    label?: string;
+    job?: string;
+    description?: string;
+    askFirst?: boolean;
+}): Promise<RoleCommandResult>;
+declare function pinRole(root: string, name: string): Promise<RoleCommandResult>;
+declare function hideRole(root: string, name: string): Promise<RoleCommandResult>;
+declare function showRoles(root: string, opts?: {
+    name?: string;
+    all?: boolean;
+}): Promise<RoleCommandResult>;
+declare function duplicateRole(root: string, nameInput: string): Promise<RoleCommandResult>;
+declare function deleteRole(root: string, nameInput: string): Promise<RoleCommandResult>;
+
+interface StoryNode {
+    changeId: string;
+    title: string;
+    story: string;
+    epic: string;
+    depends: string[];
+    status: string;
+}
+interface StoryDraft {
+    epic?: string;
+    story?: string;
+    depends: string[];
+}
+declare function validBranchName(name: string): boolean;
+declare function parseStoryDraft(input: {
+    epic?: string;
+    story?: string;
+    depends?: string[];
+}): {
+    ok: true;
+    draft: StoryDraft;
+} | {
+    ok: false;
+    stdout: string;
+};
+declare function loadEpicStories(projectRoot: string, config: Config, epic: string): Promise<StoryNode[]>;
+declare function storyIdTaken(projectRoot: string, config: Config, epic: string, story: string): Promise<boolean>;
+declare function formatEpicGraph(nodes: StoryNode[]): {
+    exitCode: number;
+    stdout: string;
+};
+/** Graph errors, then open dependencies. Null means the branch may be created. */
+declare function branchBlock(nodes: StoryNode[], story: string): string | null;
+
+export { AGENT_INTEGRATIONS, AGENT_TARGET_OPTIONS, ALL_AGENT_TARGETS, type AdapterExtractResult, AdapterRegistry, type AdvanceResult, type AgentInstallPlan, AgentInstallPreflightError, type AgentIntegration, type AgentTarget, type AgentTargetOption, type AllowRoleInput, type ArtifactDef, ArtifactDefSchema, type BuildRefinePlanOptions, type CallMcpToolResult, type ChangeContext, type ChangeMeta, ChangeMetaSchema, type ChangeMetrics, ChangeMetricsSchema, type ChangePhaseOrder, type CodeContextCaps, type CodeContextGap, type CodeContextGapCode, type CodeContextRequest, type CodeContextResult, type CodeContextSummary, type CodeSlice, type Complexity, type Config, ConfigSchema, type CreateChangeInput, DEFAULT_CODE_CONTEXT_CAPS, DEFAULT_INIT_INTEGRATION, EMBEDDINGS_UNAVAILABLE, EMBEDDING_MODEL, type Embedder, type FastembedHooks, type FocusPlan, type Gate, GateSchema, type GatherMcpOptions, type GenerateCodeContextDeps, type GeneratedManifest, type GeneratedState, type GitHeadRunner, type GreenfieldFeature, type IndexStats, type InitOptions, type InitResult, type InstallAgentOptions, type InstallAgentResult, type InstallAgentsOptions, type InstallAgentsResult, type InstalledAgentSnapshot, type KeptFile, type KeptReason, type LanguageAdapter, type McpConfig, McpConfigSchema, type McpFetchResult, type McpInvoke, McpInvokeSchema, type McpMatchContext, type McpSource, McpSourceSchema, type McpWhen, McpWhenSchema, type MetricsImportResult, PROTOCOL_MD, type PhaseMetric, PhaseMetricSchema, type PhaseTiming, type PhaseTimingRow, type PlannedWrite, type PriceCard, type Prices, RRF_K, type RawHit, type ReconcileGeneratedResult, type RefineArtifactRef, type RefineMode, type RefinePlan, type RemoveAgentHostsResult, type RenderChangeReportInput, type RoleCommandResult, type RoleModel, type RoleProfile, type RunRoleInput, SDD_AGENT_ROLES, SDD_CORE_VERSION, SDD_DIR, SUMMARY_TOKEN_CAP, type SddAgentRole, type SddAgentRoleId, SddError, type SearchConfig, SearchConfigError, type SearchHit, type SearchProvider, type SearchQuery, type SearchResult, type SearchRuntime, type SearchScope, type Stage, StageSchema, type StartFeatureInput, type StartGreenfieldInput, type StartGreenfieldResult, type StoryDraft, type StoryNode, type SymbolInfo, type SymbolKind, type SyncChangeResult, type TokenCounts, type TokenUsageMetric, TokenUsageMetricSchema, VerifyCommandSchema, type VerifyResult, type VerifyStatus, type Workflow, WorkflowSchema, acceptNetwork, activePointerPath, activeStages, addMcpSource, advanceStage, agentHostPaths, agentKickoffMessage, allowRole, approveGate, archiveDir, assertAgentInstallable, assertSessionLogAllowed, branchBlock, budgetForStage, buildAgentPrompt, buildContext, buildRefinePlan, buildRetrievedInner, callMcpSourceTool, canLeaveStage, changeDirName, changeMetaPath, changePath, changesDir, changesPathRel, chunkCode, chunkMarkdown, classifyPath, clearActiveIf, clearRegisteredSearchProviders, compareChangesByFirstPhase, completeChange, configPath, contentHash, copyDir, copyDirSkipExisting, costFor, countTokens, createBuiltinProvider, createChange, createFastembedEmbedder, createRole, defaultConfig, defaultMcpConfig, defaultMcpYamlPath, defaultMemoryDir, defaultPricesYamlPath, defaultSearchYamlPath, defaultTemplatesDir, defaultWorkflowsDir, defaultsRoot, deleteRole, describeFsError, describeKept, displayArchivePath, displayChangePath, domainsDir, duplicateRole, editRole, embedSearchQuery, emptyChangeMetrics, ensureDir, ensureMcpConfig, errorMessage, executeSearch, explainMatch, extractiveSummary, fallbackAdapter, fallbackIncompleteStageId, fallbackWarning, fastembedImportCount, findFeaturesBacklogPath, firstActiveStageId, formatDuration, formatEpicGraph, formatJsonSummary, formatMcpContextForHandoff, formatStatus, ftsTokens, fuseByRank, fuseHits, gatherMcpContext, gatherMcpContextForChange, generateCodeContext, generatedState, getActiveChangeId, getHeadSha, getIntegration, getStage, guidancePaths, handoffRole, hideRole, importSessionMetrics, incompletePriorStageErrors, indexDbPath, inferComplexity, initProject, installAgentIntegration, installAgentIntegrations, integrationKeyFor, interpolate, interpolateArgs, isHardDenied, isIgnoredPath, isInitialized, isPrunedDir, isSddError, isSecretPath, isStageSkipped, isSubstantiveArtifactContent, keywordHits, listBacklogFeatures, listChanges, listDirs, listFiles, listMatchingSourceIds, listMcpSourceTools, listScopeHits, listWorkflowNames, loadChangeMeta, loadConfig, loadEpicStories, loadExcluder, loadGeneratedManifest, loadInstalledAgent, loadMcpConfig, loadPrices, loadSearchConfig, loadWorkflow, markGenerated, matchMcpSources, mcpConfigPath, mcpTimeoutMs, memoryDir, memoryPathRel, mergeCaps, mergeConfigDefaults, mergeRankedHits, nextStageId, nowIso, optionForTarget, packHits, parseAgentTargets, parseFeaturesBacklog, parseIntegration, parseStoryDraft, pathExists, phaseTiming, pinRole, planAgentIntegration, planNetwork, promoteGreenfieldToMemory, rankScope, readChangeMetrics, readHandoffCodePoints, readText, readYaml, rebuildNetwork, recommendWorkflow, reconcileGeneratedTree, refreshActiveAgentContext, refreshConfiguredGuidance, registerSearchProvider, removeMcpSource, removeOtherAgentHosts, removeOtherAgentHostsDetailed, removePath, renderAgentsMd, renderBlock, renderChangeReport, renderMemoryIndex, renderProtocolMd, renderSddReadme, renderThinAgent, repairRequiredIgnores, reportAllChanges, reportChange, resolveActiveDirectory, resolveChangeId, resolveEmbedder, resolveFocus, resolveSearchProvider, resolveStages, rrf, runLocalVerify, runNetwork, runRole, saveChangeMeta, saveConfig, saveGeneratedManifest, saveMcpConfig, scopeForPath, sddRoot, searchConfigPath, searchPreamble, setActiveChange, setRoleMessaging, shouldAutoSkip, showRoleGroup, showRoles, skipStage, slugify, startFeatureFromBacklog, startGreenfield, startPhase, storyIdTaken, switchWorkflow, syncChangeHead, templatesDir, toProcessEnv, todayIsoDate, tokenizeKeywords, transitionPhase, typescriptAdapter, uniqueChangeDirName, updateFeatureStatus, validBranchName, withMcpSource, workflowsDir, writeAgentHandoff, writeRefineBrief, writeText, writeTextIfMissing, writeYaml };