@phren/cli 0.0.57 → 0.0.58

package/dist/project-topics.d.ts

@@ -0,0 +1,122 @@
+export interface ProjectTopic {
+    slug: string;
+    label: string;
+    description: string;
+    keywords: string[];
+}
+export interface BuiltinTopic {
+    name: string;
+    description: string;
+    keywords: string[];
+}
+export type ProjectTopicSource = "default" | "custom";
+export interface ProjectTopicDocInfo {
+    slug: string;
+    label: string;
+    file: string;
+    path: string;
+    exists: boolean;
+    autoManaged: boolean;
+    entryCount: number;
+    lastModified: string;
+}
+export interface ProjectReferenceDocInfo {
+    file: string;
+    path: string;
+    title: string;
+    autoManaged: boolean;
+    entryCount: number;
+    lastModified: string;
+}
+export interface LegacyTopicDocInfo extends ProjectReferenceDocInfo {
+    slug: string;
+    eligible: boolean;
+    reason?: string;
+}
+export interface ProjectTopicSuggestion {
+    slug: string;
+    label: string;
+    description: string;
+    keywords: string[];
+    source: "builtin" | "heuristic" | "pinned";
+    reason: string;
+    confidence: number;
+}
+export interface ProjectTopicsResponse {
+    source: ProjectTopicSource;
+    topics: ProjectTopic[];
+    suggestions: ProjectTopicSuggestion[];
+    pinnedTopics: ProjectTopic[];
+    legacyDocs: LegacyTopicDocInfo[];
+    topicDocs: ProjectTopicDocInfo[];
+}
+export interface ReferenceListResponse {
+    topicDocs: ProjectTopicDocInfo[];
+    otherDocs: ProjectReferenceDocInfo[];
+}
+export interface ReclassifyTopicsResult {
+    movedFiles: number;
+    movedEntries: number;
+    skipped: Array<{
+        file: string;
+        reason: string;
+    }>;
+}
+declare const DOMAIN_TOPICS: Record<string, ProjectTopic[]>;
+export declare function topicReferencePath(phrenPath: string, project: string, slug: string): string | null;
+export declare function normalizeBuiltinTopicDomain(domain?: string): keyof typeof DOMAIN_TOPICS;
+export declare function getBuiltinTopicConfig(domain?: string): BuiltinTopic[];
+export declare function getBuiltinTopics(phrenPath?: string, project?: string): ProjectTopic[];
+export declare function readProjectTopics(phrenPath: string, project: string): {
+    source: ProjectTopicSource;
+    topics: ProjectTopic[];
+    domain?: string;
+};
+export declare function pinProjectTopicSuggestion(phrenPath: string, project: string, topic: ProjectTopic): {
+    ok: true;
+    pinnedTopics: ProjectTopic[];
+} | {
+    ok: false;
+    error: string;
+};
+export declare function unpinProjectTopicSuggestion(phrenPath: string, project: string, slug: string): {
+    ok: true;
+    pinnedTopics: ProjectTopic[];
+} | {
+    ok: false;
+    error: string;
+};
+export declare function writeProjectTopics(phrenPath: string, project: string, topics: ProjectTopic[]): {
+    ok: true;
+    topics: ProjectTopic[];
+} | {
+    ok: false;
+    error: string;
+};
+export declare function classifyTopicForText(text: string, topics: ProjectTopic[]): ProjectTopic;
+export declare function appendArchivedEntriesToTopicDoc(filePath: string, project: string, topic: ProjectTopic, entries: Array<{
+    date: string;
+    bullet: string;
+    citation?: string;
+}>): void;
+export declare function ensureTopicReferenceDoc(phrenPath: string, project: string, topic: ProjectTopic): {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function listProjectReferenceDocs(phrenPath: string, project: string, topics?: ProjectTopic[]): ReferenceListResponse;
+export declare function suggestTopics(phrenPath: string, project: string, topics?: ProjectTopic[]): ProjectTopicSuggestion[];
+/** @internal Exported for tests. */
+export declare const suggestProjectTopics: typeof suggestTopics;
+export declare function getProjectTopicsResponse(phrenPath: string, project: string): ProjectTopicsResponse;
+export declare function readReferenceContent(phrenPath: string, project: string, file: string): {
+    ok: true;
+    content: string;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function reclassifyLegacyTopicDocs(phrenPath: string, project: string): ReclassifyTopicsResult;
+export {};

package/dist/provider-adapters.d.ts

@@ -0,0 +1,34 @@
+export type HookToolName = "claude" | "copilot" | "cursor" | "codex";
+export declare const HOOK_TOOL_NAMES: readonly ["claude", "copilot", "cursor", "codex"];
+export type McpRootKey = "mcpServers" | "servers";
+type CommandExistsFn = (cmd: string) => boolean;
+export declare function hookConfigPath(tool: HookToolName, phrenPath?: string | undefined): string;
+export declare function hookConfigPaths(phrenPath: string): Record<HookToolName, string>;
+export declare function hookConfigRoots(phrenPath: string): string[];
+export declare function vscodeMcpCandidates(env?: NodeJS.ProcessEnv): string[];
+export declare function probeVsCodeConfig(commandExists: CommandExistsFn, env?: NodeJS.ProcessEnv): {
+    targetDir: string | null;
+    installed: boolean;
+};
+export declare function cursorMcpCandidates(env?: NodeJS.ProcessEnv): string[];
+export declare function resolveCursorMcpConfig(commandExists: CommandExistsFn, env?: NodeJS.ProcessEnv): {
+    installed: boolean;
+    existing: string | null;
+    target: string;
+};
+export declare function copilotMcpCandidates(env?: NodeJS.ProcessEnv): string[];
+export declare function resolveCopilotMcpConfig(commandExists: CommandExistsFn, env?: NodeJS.ProcessEnv): {
+    installed: boolean;
+    existing: string | null;
+    cliConfig: string;
+    hasCliDir: boolean;
+};
+export declare function codexJsonCandidates(phrenPath: string, env?: NodeJS.ProcessEnv): string[];
+export declare function resolveCodexMcpConfig(phrenPath: string, commandExists: CommandExistsFn, env?: NodeJS.ProcessEnv): {
+    installed: boolean;
+    tomlPath: string;
+    existingJson: string | null;
+    preferToml: boolean;
+    jsonCandidates: string[];
+};
+export {};

package/dist/query-correlation.d.ts

@@ -0,0 +1,31 @@
+import type { SelectedSnippet } from "./shared/retrieval.js";
+export interface CorrelationEntry {
+    timestamp: string;
+    keywords: string;
+    project: string;
+    filename: string;
+    sessionId?: string;
+    helpful?: boolean;
+}
+/**
+ * Check if query correlation feature is enabled via env var.
+ */
+export declare function isQueryCorrelationEnabled(): boolean;
+/**
+ * Log query-to-finding correlations after snippet selection.
+ * Called from handleHookPrompt after selectSnippets.
+ */
+export declare function logCorrelations(phrenPath: string, keywords: string, selected: SelectedSnippet[], sessionId?: string): void;
+/**
+ * Mark correlations from a session as "helpful" when positive feedback is received.
+ * This retroactively stamps entries so that future correlation lookups weight them higher.
+ */
+export declare function markCorrelationsHelpful(phrenPath: string, sessionId: string, docKey: string): void;
+/**
+ * Find documents that historically correlate with the given query keywords.
+ * Returns doc keys (project/filename) sorted by correlation strength.
+ *
+ * Only looks at the last RECENT_WINDOW entries for performance.
+ * Entries marked "helpful" get a 2x weight boost.
+ */
+export declare function getCorrelatedDocs(phrenPath: string, keywords: string, limit?: number): string[];

package/dist/runtime-profile.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Resolve the effective runtime profile for user-facing entrypoints.
+ * Explicit env selection is strict. Implicit selection is best-effort via
+ * machines.yaml / profiles and falls back to an unscoped view during early setup.
+ */
+export declare function resolveRuntimeProfile(phrenPath: string, requestedProfile?: string | undefined): string;

package/dist/session/checkpoints.d.ts

@@ -0,0 +1,25 @@
+export interface TaskCheckpoint {
+    project: string;
+    taskId: string;
+    taskText?: string;
+    taskLine: string;
+    sessionId?: string;
+    createdAt: string;
+    resumptionHint: {
+        lastAttempt: string;
+        nextStep: string;
+    };
+    gitStatus: string;
+    editedFiles: string[];
+    failingTests: string[];
+}
+export declare function checkpointPath(phrenPath: string, project: string, taskId: string): string;
+export declare function writeTaskCheckpoint(phrenPath: string, checkpoint: TaskCheckpoint): void;
+export declare function listTaskCheckpoints(phrenPath: string, project?: string): TaskCheckpoint[];
+export declare function clearTaskCheckpoint(phrenPath: string, args: {
+    project: string;
+    taskId?: string;
+    stableId?: string;
+    positionalId?: string;
+    taskLine?: string;
+}): number;

package/dist/session/utils.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Write JSON to a file atomically using temp-file + rename.
+ * Ensures the parent directory exists before writing.
+ */
+export declare function atomicWriteJson(filePath: string, data: unknown): void;
+export interface SessionState {
+    sessionId: string;
+    project?: string;
+    agentScope?: string;
+    startedAt: string;
+    endedAt?: string;
+    summary?: string;
+    findingsAdded: number;
+    tasksCompleted: number;
+    /** When true, this session was created by a lifecycle hook, not an explicit MCP call. */
+    hookCreated?: boolean;
+}
+export declare function sessionsDir(phrenPath: string): string;
+export declare function sessionFileForId(phrenPath: string, sessionId: string): string;
+export declare function readSessionStateFile(file: string): SessionState | null;
+export declare function writeSessionStateFile(file: string, state: SessionState): void;
+/**
+ * Log an error to stderr when PHREN_DEBUG is enabled.
+ * Centralises the repeated `if (PHREN_DEBUG) stderr.write(...)` pattern.
+ */
+export declare function debugError(scope: string, err: unknown): void;
+interface SessionFileEntry<T> {
+    fullPath: string;
+    data: T;
+    mtimeMs: number;
+}
+/**
+ * Enumerate all `session-*.json` files under `dir`, parse each one via `parse`,
+ * and keep entries where `filter` returns true.
+ *
+ * Returns an array of `{ fullPath, data, mtimeMs }` sorted newest-mtime-first.
+ * `includeMtime` controls whether `fs.statSync` is called (some callers don't need it).
+ */
+export declare function scanSessionFiles<T>(dir: string, parse: (filePath: string) => T | null, filter: (data: T, fullPath: string) => boolean, opts?: {
+    includeMtime?: boolean;
+    errorScope?: string;
+}): SessionFileEntry<T>[];
+export {};

package/dist/shared/content.d.ts

@@ -0,0 +1,7 @@
+export { type ConsolidationNeeded, type ConsolidationStatus, checkConsolidationNeeded, validateFindingsFormat, stripTaskDoneSection, validateTaskFormat, extractConflictVersions, mergeFindings, mergeTask, autoMergeConflicts, } from "../content/validate.js";
+export { filterTrustedFindings, filterTrustedFindingsDetailed, } from "../content/citation.js";
+export { scanForSecrets, resolveCoref, isDuplicateFinding, detectConflicts, extractDynamicEntities, checkSemanticDedup, checkSemanticConflicts, } from "../content/dedup.js";
+export { countActiveFindings, autoArchiveToReference, } from "../content/archive.js";
+export { upsertCanonical, addFindingToFile, addFindingsToFile, autoDetectFindingType, type AddFindingResult, } from "../content/learning.js";
+export { FINDING_LIFECYCLE_STATUSES, FINDING_TYPE_DECAY, extractFindingType, parseFindingLifecycle, buildLifecycleComments, isInactiveFindingLine, type FindingLifecycleStatus, type FindingLifecycleMetadata, } from "../finding/lifecycle.js";
+export { METADATA_REGEX, parseStatus, parseStatusField, parseSupersession, parseSupersedesRef, parseContradiction, parseAllContradictions, parseFindingId, parseCreatedDate, isCitationLine, isArchiveStart, isArchiveEnd, stripLifecycleMetadata, stripRelationMetadata, stripAllMetadata, stripComments, addMetadata, } from "../content/metadata.js";

package/dist/shared/data-utils.d.ts

@@ -0,0 +1,8 @@
+import { type PhrenResult } from "../shared.js";
+export declare function withSafeLock<T>(filePath: string, fn: () => PhrenResult<T>): PhrenResult<T>;
+/**
+ * Recursively walk a directory and return paths of files matching an optional filter.
+ * Defaults to `.md` files only. Uses an iterative stack to avoid recursion limits.
+ */
+export declare function walkDirectory(root: string, filter?: (name: string) => boolean): string[];
+export declare function ensureProject(phrenPath: string, project: string): PhrenResult<string>;

package/dist/shared/embedding-cache.d.ts

@@ -0,0 +1,30 @@
+export interface EmbeddingCoverage {
+    total: number;
+    embedded: number;
+    missing: number;
+    pct: number;
+    missingPct: number;
+    state: "empty" | "cold" | "warming" | "warm";
+}
+export declare class EmbeddingCache {
+    private phrenPath;
+    private cache;
+    private dirty;
+    private dirtyUpserts;
+    private dirtyDeletes;
+    constructor(phrenPath: string);
+    load(): Promise<void>;
+    get(docPath: string, model: string): number[] | null;
+    set(docPath: string, model: string, vec: number[]): void;
+    delete(docPath: string): void;
+    flush(): Promise<void>;
+    getAllEntries(): Array<{
+        path: string;
+        vec: number[];
+        model: string;
+    }>;
+    size(): number;
+    coverage(allPaths: string[]): EmbeddingCoverage;
+}
+export declare function formatEmbeddingCoverage(coverage: EmbeddingCoverage): string;
+export declare function getEmbeddingCache(phrenPath: string): EmbeddingCache;

package/dist/shared/fragment-graph.d.ts

@@ -0,0 +1,60 @@
+import type { SqlJsDatabase } from "./index.js";
+/** @internal Exported for tests. */
+export declare function escapeRegex(s: string): string;
+/** Escape SQL LIKE wildcard characters so user input is treated literally.
+ * @internal Exported for tests. */
+export declare function escapeLike(s: string): string;
+/**
+ * Log fragment resolution misses to .runtime/fragment-misses.jsonl.
+ *
+ * Judgment criteria — what's worth capturing vs noise:
+ * - Worth capturing: repeated lookups for the same fragment name (indicates a gap
+ *   in the fragment graph that the user keeps hitting), fragment names that look like
+ *   real library/tool names (not random query fragments).
+ * - Noise: single one-off lookups for short generic terms, lookups that fail
+ *   because the query was malformed. We filter these by requiring name.length > 2.
+ *
+ * Gated by PHREN_DEBUG (or PHREN_DEBUG for compat) to avoid disk writes for
+ * regular users. The miss log is append-only JSONL so downstream tooling can
+ * detect repeated patterns (e.g. "fragment X was looked up 5 times but never
+ * found" -> suggest adding it).
+ */
+export declare function logFragmentMiss(phrenPath: string, name: string, context: string, project?: string): void;
+/**
+ * Lightweight synchronous fragment extraction from text — regex only, no DB writes.
+ * Used by add_finding to surface detected fragments in the MCP response without
+ * requiring a DB reference in the write path. Full DB linking happens on the next
+ * index rebuild, which is triggered automatically after every add_finding call via
+ * updateFileInIndex -> extractAndLinkFragments.
+ */
+export declare function extractFragmentNames(content: string): string[];
+/**
+ * Ensure the global_entities cross-project index table exists.
+ * Called during buildIndex to enable cross-project fragment queries.
+ */
+export declare function ensureGlobalEntitiesTable(db: SqlJsDatabase): void;
+/**
+ * Prime CLAUDE.md fragments per project for a single build pass.
+ * During an active build, extractAndLinkFragments resolves user fragments from this
+ * in-memory map and avoids per-file sync stat/read calls.
+ */
+export declare function beginUserFragmentBuildCache(phrenPath: string, projects: Iterable<string>): void;
+/** End a build-scoped cache created by beginUserFragmentBuildCache(). */
+export declare function endUserFragmentBuildCache(phrenPath: string): void;
+export declare function extractAndLinkFragments(db: SqlJsDatabase, content: string, sourceDoc: string, phrenPath?: string): void;
+/**
+ * Query related fragments for a given name.
+ */
+export declare function queryFragmentLinks(db: SqlJsDatabase, name: string): {
+    related: string[];
+};
+/**
+ * Query cross-project fragment relationships.
+ * Returns projects and docs that share fragments with the given query.
+ */
+export declare function queryCrossProjectFragments(db: SqlJsDatabase, fragmentName: string, excludeProject?: string): Array<{
+    fragment: string;
+    project: string;
+    docKey: string;
+}>;
+export declare function getFragmentBoostDocs(db: SqlJsDatabase, query: string): Set<string>;

package/dist/shared/governance.d.ts

@@ -0,0 +1,4 @@
+export * from '../governance/policy.js';
+export * from '../governance/scores.js';
+export * from '../governance/audit.js';
+export { withFileLock, isFiniteNumber, hasValidSchemaVersion } from '../governance/locks.js';

package/dist/shared/index.d.ts

@@ -0,0 +1,29 @@
+import { type SqlJsDatabase } from "../index-query.js";
+export { porterStem } from "./stemmer.js";
+export { cosineFallback } from "./search-fallback.js";
+export { queryFragmentLinks, getFragmentBoostDocs, ensureGlobalEntitiesTable, queryCrossProjectFragments, logFragmentMiss, extractFragmentNames, } from "./fragment-graph.js";
+export { buildSourceDocKey, decodeFiniteNumber, decodeStringRow, extractSnippet, getDocSourceKey, normalizeMemoryId, queryDocBySourceKey, queryDocRows, queryRows, rowToDoc, rowToDocWithRowid, } from "../index-query.js";
+export type { SqlValue, DbRow, DocRow, SqlJsDatabase } from "../index-query.js";
+export declare function classifyFile(filename: string, relPath: string): string;
+/**
+ * Resolve `@import shared/file.md` directives in document content.
+ * The import path is resolved relative to the phren root (e.g. `shared/foo.md` -> `~/.phren/global/shared/foo.md`).
+ * Circular imports are detected and skipped. Depth is capped to prevent runaway recursion.
+ */
+/** @internal Exported for tests. */
+export declare function resolveImports(content: string, phrenPath: string): string;
+export declare function listIndexedDocumentPaths(phrenPath: string, profile?: string): string[];
+export declare function normalizeIndexedContent(content: string, type: string, phrenPath: string, maxChars?: number): string;
+/**
+ * Incrementally update a single file in the FTS index.
+ * Deletes the old record for the file, re-reads and re-inserts it.
+ * Touches the sentinel file to invalidate caches.
+ */
+export declare function updateFileInIndex(db: SqlJsDatabase, filePath: string, phrenPath: string): void;
+export declare function buildIndex(phrenPath: string, profile?: string): Promise<SqlJsDatabase>;
+/** Find the FTS cache file for a specific phrenPath+profile. Returns exists + size. */
+export declare function findFtsCacheForPath(phrenPath: string, profile?: string): {
+    exists: boolean;
+    sizeBytes?: number;
+};
+export declare function detectProject(phrenPath: string, cwd: string, profile?: string): string | null;

package/dist/shared/ollama.d.ts

@@ -0,0 +1,28 @@
+/** @internal Exported for tests. */
+export declare function prepareEmbeddingInput(text: string): string;
+/**
+ * Cloud embedding API support (Item 6).
+ * Set PHREN_EMBEDDING_API_URL to an OpenAI-compatible /embeddings endpoint.
+ * Set PHREN_EMBEDDING_API_KEY for the Authorization: Bearer header.
+ * When set, cloud embedding takes priority over Ollama.
+ *
+ * Example (OpenAI):
+ *   PHREN_EMBEDDING_API_URL=https://api.openai.com/v1
+ *   PHREN_EMBEDDING_API_KEY=sk-...
+ *   PHREN_EMBEDDING_MODEL=text-embedding-3-small
+ */
+export declare function getCloudEmbeddingUrl(): string | null;
+export declare function getOllamaUrl(): string | null;
+export declare function getEmbeddingModel(): string;
+export declare function getExtractModel(): string;
+export declare function checkOllamaAvailable(url?: string): Promise<boolean>;
+export declare function checkModelAvailable(model?: string, url?: string): Promise<boolean>;
+export declare function embedText(text: string, model?: string, url?: string): Promise<number[] | null>;
+export declare function generateText(prompt: string, model?: string, url?: string): Promise<string | null>;
+export type OllamaStatus = "ready" | "no_model" | "not_running" | "disabled";
+/**
+ * Probe Ollama availability and model readiness in one call.
+ * Returns a status enum so callers can branch on it without repeating the check logic.
+ */
+export declare function checkOllamaStatus(): Promise<OllamaStatus>;
+export { cosineSimilarity } from "../embedding.js";

package/dist/shared/process.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared process helpers for spawning detached child processes.
+ */
+import { type ChildProcess } from "child_process";
+export interface SpawnDetachedChildOptions {
+    phrenPath: string;
+    logFd?: number;
+    cwd?: string;
+    extraEnv?: Record<string, string>;
+}
+/**
+ * Spawn a detached child process with the standard phren environment.
+ * When logFd is provided, stdout/stderr are redirected to that fd.
+ * When omitted, all stdio is ignored.
+ * Returns the ChildProcess so callers can attach `.unref()` or `.on("exit", ...)`.
+ */
+export declare function spawnDetachedChild(args: string[], opts: SpawnDetachedChildOptions): ChildProcess;

package/dist/shared/retrieval.d.ts

@@ -0,0 +1,84 @@
+import { type RetentionPolicy } from "./governance.js";
+import { type DocRow, type SqlJsDatabase } from "./index.js";
+import type { GitContext } from "../cli/hooks-session.js";
+export type { GitContext } from "../cli/hooks-session.js";
+export declare function detectTaskIntent(prompt: string): "debug" | "review" | "build" | "docs" | "skill" | "general";
+export declare function fileRelevanceBoost(filePath: string, changedFiles: Set<string>): number;
+export declare function branchMatchBoost(content: string, branch: string | undefined): number;
+/**
+ * Item 4: Reciprocal Rank Fusion — merges ranked result lists from multiple search tiers.
+ * Documents appearing in multiple tiers get a higher combined score.
+ * Formula: score(d) = Σ 1/(k + rank_i) for each tier i containing d, where k=60 (standard).
+ */
+/** @internal Exported for tests. */
+export declare function rrfMerge(tiers: DocRow[][], k?: number): DocRow[];
+/** @internal Exported for tests. */
+export declare function shouldRunVectorExpansion(rows: DocRow[] | null, prompt: string, desiredResults?: number): boolean;
+declare function approximateTokens(text: string): number;
+export declare function filterTaskByPriority(items: string[], allowedPriorities?: string[]): string[];
+export declare function searchDocuments(db: SqlJsDatabase, safeQuery: string, prompt: string, keywords: string, detectedProject: string | null, searchAllProjects?: boolean, phrenPath?: string): DocRow[] | null;
+/**
+ * Async variant of searchDocuments that also runs real vector search (Tier 3)
+ * when cloud embeddings (PHREN_EMBEDDING_API_URL) or Ollama are available.
+ * Falls back to the sync result if vector search is unavailable or fails.
+ */
+export declare function searchDocumentsAsync(db: SqlJsDatabase, safeQuery: string, prompt: string, keywords: string, detectedProject: string | null, searchAllProjects?: boolean, phrenPath?: string): Promise<DocRow[] | null>;
+export interface SearchKnowledgeRowsOptions {
+    query: string;
+    maxResults: number;
+    fetchLimit?: number;
+    filterProject?: string | null;
+    filterType?: string | null;
+    phrenPath: string;
+}
+export interface SearchKnowledgeRowsResult {
+    safeQuery: string;
+    rows: DocRow[] | null;
+    usedFallback: boolean;
+}
+export declare function searchKnowledgeRows(db: SqlJsDatabase, options: SearchKnowledgeRowsOptions): Promise<SearchKnowledgeRowsResult>;
+export interface FederatedDocRow extends DocRow {
+    /** The phren store path this result came from (undefined = local store). */
+    federationSource?: string;
+    /** Human-readable store name from the registry. */
+    storeName?: string;
+    /** Immutable store ID from the registry. */
+    storeId?: string;
+}
+/**
+ * Search additional phren stores defined in the store registry (or PHREN_FEDERATION_PATHS).
+ * Returns an array of results tagged with their source store. Read-only — no mutations.
+ */
+export declare function searchFederatedStores(localPhrenPath: string, options: Omit<SearchKnowledgeRowsOptions, "phrenPath">): Promise<FederatedDocRow[]>;
+export type TrustFilterQueueItem = {
+    project: string;
+    section: "Stale" | "Conflicts";
+    items: string[];
+};
+export type TrustFilterResult = {
+    rows: DocRow[];
+    queueItems: TrustFilterQueueItem[];
+    auditEntries: string[];
+};
+/** Apply trust filter to rows. Returns filtered rows plus any queue/audit items to be written
+ * by the caller — retrieval itself should remain side-effect-free. */
+export declare function applyTrustFilter(rows: DocRow[], ttlDays: number, minConfidence: number, decay: Partial<RetentionPolicy["decay"]>, phrenPath?: string): TrustFilterResult;
+/** Item 3: Recency boost for findings. Recent findings rank higher. Accepts pre-computed date string. */
+export declare function recencyBoost(docType: string, latestDate: string): number;
+export declare function rankResults(rows: DocRow[], intent: string, gitCtx: GitContext | null, detectedProject: string | null, phrenPathLocal: string, db: SqlJsDatabase, cwd?: string, query?: string, opts?: {
+    filterType?: string | null;
+    skipTaskFilter?: boolean;
+}): DocRow[];
+export interface SelectedSnippet {
+    doc: DocRow;
+    snippet: string;
+    key: string;
+}
+/** Mark snippet lines with stale citations (cited file missing or line content changed).
+ * @internal Exported for tests. */
+export declare function markStaleCitations(snippet: string): string;
+export declare function selectSnippets(rows: DocRow[], keywords: string, tokenBudget: number, lineBudget: number, charBudget: number): {
+    selected: SelectedSnippet[];
+    usedTokens: number;
+};
+export { approximateTokens };

package/dist/shared/search-fallback.d.ts

@@ -0,0 +1,23 @@
+import type { SqlJsDatabase, DocRow } from "./index.js";
+/** @internal Exported for tests. */
+export declare function deriveVectorDocIdentity(phrenPath: string, fullPath: string): {
+    project: string;
+    filename: string;
+    relFile: string;
+};
+/** Invalidate the DF cache. Call after a full index rebuild. */
+export declare function invalidateDfCache(): void;
+export declare function deterministicSeed(text: string): number;
+/**
+ * Cosine fallback search: when FTS5 returns fewer than COSINE_FALLBACK_THRESHOLD results,
+ * load all docs and rank by TF-IDF cosine similarity.
+ * Only activated when PHREN_FEATURE_HYBRID_SEARCH=1 and corpus size <= COSINE_MAX_CORPUS.
+ * Returns DocRow[] ranked by similarity (threshold > COSINE_SIMILARITY_MIN), excluding already-found rowids.
+ */
+export declare function cosineFallback(db: SqlJsDatabase, query: string, excludeRowids: Set<number>, limit: number): DocRow[];
+/**
+ * Vector-based semantic search fallback using pre-computed Ollama embeddings.
+ * Only runs when Ollama is configured (PHREN_OLLAMA_URL is set or defaults).
+ * Returns DocRow[] sorted by cosine similarity, above 0.5 threshold.
+ */
+export declare function vectorFallback(phrenPath: string, query: string, excludePaths: Set<string>, limit: number, project?: string | null): Promise<DocRow[]>;

package/dist/shared/sqljs.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Bootstrap sql.js-fts5: find the WASM binary and initialise the library.
+ * Shared across shared-index.ts and embedding.ts to avoid duplication.
+ */
+export declare function bootstrapSqlJs(): Promise<unknown>;

package/dist/shared/stemmer.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Porter stemmer implementation for English words.
+ * Based on the Porter (1980) algorithm.
+ */
+export declare function porterStem(word: string): string;

package/dist/shared/vector-index.d.ts

@@ -0,0 +1,18 @@
+interface EmbeddingEntryLike {
+    path: string;
+    model: string;
+    vec: number[];
+}
+declare class PersistentVectorIndex {
+    private phrenPath;
+    private loaded;
+    private source;
+    private models;
+    constructor(phrenPath: string);
+    private loadFromDisk;
+    private saveToDisk;
+    ensure(entries: EmbeddingEntryLike[]): void;
+    query(model: string, queryVec: number[], limit: number, eligiblePaths?: Set<string>): string[];
+}
+export declare function getPersistentVectorIndex(phrenPath: string): PersistentVectorIndex;
+export {};

package/dist/shared.d.ts

@@ -0,0 +1,9 @@
+export type { HookToolName } from "./provider-adapters.js";
+export { HOOK_TOOL_NAMES, hookConfigPath } from "./provider-adapters.js";
+export { EXEC_TIMEOUT_MS, EXEC_TIMEOUT_QUICK_MS, PhrenError, type PhrenErrorCode, type PhrenResult, phrenOk, phrenErr, forwardErr, parsePhrenErrorCode, isRecord, withDefaults, FINDING_TYPES, type FindingType, FINDING_TAGS, type FindingTag, KNOWN_OBSERVATION_TAGS, DOC_TYPES, type DocType, capCache, RESERVED_PROJECT_DIR_NAMES, } from "./phren-core.js";
+export { ROOT_MANIFEST_FILENAME, type InstallMode, type SyncMode, type PhrenRootManifest, type InstallContext, homeDir, homePath, expandHomePath, defaultPhrenPath, rootManifestPath, readRootManifest, writeRootManifest, resolveInstallContext, findNearestPhrenPath, isProjectLocalMode, runtimeDir, tryUnlink, sessionsDir, runtimeFile, installPreferencesFile, runtimeHealthFile, shellStateFile, sessionMetricsFile, memoryScoresFile, memoryUsageLogFile, sessionMarker, debugLog, appendIndexEvent, resolveFindingsPath, findPhrenPath, ensurePhrenPath, findPhrenPathWithArg, normalizeProjectNameForCreate, findProjectNameCaseInsensitive, findArchivedProjectNameCaseInsensitive, getProjectDirs, collectNativeMemoryFiles, computePhrenLiveStateToken, getPhrenPath, qualityMarkers, atomicWriteText, } from "./phren-paths.js";
+export { PROACTIVITY_LEVELS, type ProactivityLevel, getProactivityLevel, getProactivityLevelForFindings, getProactivityLevelForTask, hasExplicitFindingSignal, hasExplicitTaskSignal, hasExecutionIntent, hasDiscoveryIntent, shouldAutoCaptureFindingsForLevel, shouldAutoCaptureTaskForLevel, } from "./proactivity.js";
+export declare function normalizeMemoryScope(scope?: string | null): string | undefined;
+export declare function isMemoryScopeVisible(itemScope: string | undefined, activeScope?: string): boolean;
+export declare function impactLogFile(phrenPath: string): string;
+export declare function appendAuditLog(phrenPath: string, event: string, details: string): void;

package/dist/shell/entry.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shell entry point: wires PhrenShell to stdin/stdout.
+ * Extracted from shell.ts to keep the orchestrator under 300 lines.
+ */
+interface LiveStateHost {
+    invalidateSubsectionsCache(): void;
+    setMessage(message: string): void;
+}
+interface StartupIntroPlan {
+    mode: "always" | "once-per-version" | "off";
+    variant: "full" | "final-frame" | "skip";
+    holdForKeypress: boolean;
+    dwellMs: number;
+    markSeen: boolean;
+}
+export declare function resolveStartupIntroPlan(phrenPath: string, version?: string): StartupIntroPlan;
+export declare function startLiveStatePoller({ phrenPath, shell, repaint, isExiting, intervalMs, computeToken, }: {
+    phrenPath: string;
+    shell: LiveStateHost;
+    repaint: () => Promise<void>;
+    isExiting?: () => boolean;
+    intervalMs?: number;
+    computeToken?: (phrenPath: string) => string;
+}): () => void;
+export declare function startShell(phrenPath: string, profile: string): Promise<void>;
+export {};