zam-core 0.3.3 → 0.3.5

package/dist/index.d.ts

@@ -1,163 +1,299 @@
 import { Database } from 'libsql';
 
+/**
+ * Learning Analytics
+ *
+ * Progress statistics, competence tracking, and session summaries.
+ * Ported from PoC's `stats` command with additions for FSRS and symbiosis modes.
+ */
+
+interface UserStats {
+    userId: string;
+    totalTokens: number;
+    cardsInDeck: number;
+    dueToday: number;
+    blocked: number;
+    mature: number;
+    avgStability: number | null;
+    totalSessions: number;
+    lastSession: string | null;
+}
+interface DomainCompetence {
+    domain: string;
+    totalCards: number;
+    matureCards: number;
+    avgStability: number;
+    retentionRate: number;
+    suggestedMode: "shadowing" | "copilot" | "autonomy";
+}
+/**
+ * Get overall learning stats for a user (ported from PoC's `stats` command).
+ */
+declare function getUserStats(db: Database, userId: string): UserStats;
+/**
+ * Get competence per domain for a user.
+ * Used to suggest symbiosis mode transitions.
+ */
+declare function getDomainCompetence(db: Database, userId: string): DomainCompetence[];
+
+/**
+ * Azure DevOps connector — fetches work items from ADO boards.
+ */
+interface ADOConfig {
+    orgUrl: string;
+    project: string;
+    pat: string;
+}
+interface WorkItem {
+    id: number;
+    title: string;
+    state: string;
+    type: string;
+    assignedTo: string;
+}
+/** Load ADO config from credentials file. Returns null if not configured. */
+declare function loadADOConfig(): ADOConfig | null;
+/**
+ * Fetch active work items assigned to the current user.
+ * Uses WIQL to query, then batch-fetches work item details.
+ */
+declare function fetchActiveWorkItems(config: ADOConfig): Promise<WorkItem[]>;
+
+/**
+ * Credential store — reads/writes ~/.zam/credentials.json
+ *
+ * Connector secrets (Turso URL/token, ADO PAT, etc.) live here instead of
+ * inside the SQLite database. This ensures credentials survive db deletion,
+ * which is required when migrating from plain SQLite to a libsql embedded
+ * replica (Turso cloud sync).
+ */
+interface TursoCredentials {
+    url: string;
+    token: string;
+}
+interface ADOCredentials {
+    org_url: string;
+    project: string;
+    pat: string;
+}
+interface Credentials {
+    turso?: Partial<TursoCredentials>;
+    ado?: Partial<ADOCredentials>;
+}
+/** Load credentials from ~/.zam/credentials.json. Returns empty object if missing. */
+declare function loadCredentials(path?: string): Credentials;
+/** Save credentials to ~/.zam/credentials.json. */
+declare function saveCredentials(creds: Credentials, path?: string): void;
+/** Get complete Turso credentials, or null if incomplete. */
+declare function getTursoCredentials(path?: string): TursoCredentials | null;
+/** Set Turso credentials. */
+declare function setTursoCredentials(url: string, token: string, path?: string): void;
+/** Clear Turso credentials. */
+declare function clearTursoCredentials(path?: string): void;
+/** Get complete ADO credentials, or null if incomplete. */
+declare function getADOCredentials(path?: string): ADOCredentials | null;
+/** Set ADO credentials. */
+declare function setADOCredentials(orgUrl: string, project: string, pat: string, path?: string): void;
+/** Clear ADO credentials. */
+declare function clearADOCredentials(path?: string): void;
+
 interface ConnectionOptions {
     /** Path to the SQLite database file. Defaults to ~/.zam/zam.db */
     dbPath?: string;
     /** If true, create the directory and run schema migrations on open */
     initialize?: boolean;
-    /** Turso sync URL for cloud replication (e.g. libsql://db-name.turso.io) */
+    /** Turso sync URL for embedded replica mode (e.g. libsql://db-name.turso.io) */
     syncUrl?: string;
-    /** Turso auth token for cloud replication */
+    /** Turso auth token for direct remote or embedded replica access */
     authToken?: string;
+    /** If false, ignore ~/.zam/credentials.json and force the local/default database. */
+    useConfiguredCloud?: boolean;
 }
 /**
  * Open (or create) the ZAM database.
- * Uses WAL mode for concurrent access from AI CLI and user CLI.
- * When syncUrl is provided, enables embedded replica sync with Turso.
+ * Uses configured Turso credentials for the default database when present.
+ * Falls back to local SQLite and WAL mode when no cloud credentials exist.
+ * When syncUrl is provided explicitly, enables embedded replica sync with Turso.
  */
 declare function openDatabase(options?: ConnectionOptions): Database;
 /**
- * Open the database with Turso cloud sync auto-detected from stored settings.
- * Reads turso.url and turso.token from user_config. If present, reopens
- * the database with embedded replica sync enabled.
+ * Open the database with Turso cloud credentials auto-detected.
+ * Credentials live in ~/.zam/credentials.json (NOT in the db), so a fresh
+ * machine only has to collect missing secrets instead of bootstrapping local
+ * state first.
  */
 declare function openDatabaseWithSync(options?: Omit<ConnectionOptions, "syncUrl" | "authToken">): Database;
 /** Get the default database path */
 declare function getDefaultDbPath(): string;
 
 /**
- * Token repository — typed wrappers around the tokens table.
+ * Goal file parser — reads markdown files with YAML-style frontmatter.
  *
- * Tokens are atomic knowledge concepts with Bloom taxonomy levels
- * and optional symbiosis modes (shadowing / copilot / autonomy).
+ * Goals are persisted as markdown files in the personal repo.
+ * Each file has simple key: value frontmatter (no nested structures)
+ * and a markdown body with description, tasks, and token references.
  */
-
-type BloomLevel$1 = 1 | 2 | 3 | 4 | 5;
-type SymbiosisMode = "shadowing" | "copilot" | "autonomy";
-interface Token {
-    id: string;
-    slug: string;
-    concept: string;
-    domain: string;
-    bloom_level: BloomLevel$1;
-    context: string;
-    symbiosis_mode: SymbiosisMode | null;
-    created_at: string;
-    updated_at: string;
-    deprecated_at: string | null;
-}
-interface CreateTokenInput {
+type GoalStatus = "active" | "completed" | "paused" | "abandoned";
+interface Goal {
     slug: string;
-    concept: string;
-    domain?: string;
-    bloom_level?: BloomLevel$1;
-    context?: string;
-    symbiosis_mode?: SymbiosisMode | null;
-}
-interface ListTokensOptions {
-    domain?: string;
+    title: string;
+    status: GoalStatus;
+    parent: string | null;
+    created: string;
+    updated: string;
+    body: string;
+    filePath: string;
 }
-interface ScoredToken extends Token {
-    score: number;
+interface GoalFrontmatter {
+    title?: string;
+    status?: string;
+    parent?: string;
+    created?: string;
+    updated?: string;
 }
 /**
- * Create a new knowledge token.
- * Throws if a token with the same slug already exists.
- */
-declare function createToken(db: Database, input: CreateTokenInput): Token;
-/**
- * Look up a token by its unique slug.
- * Returns undefined if not found.
- */
-declare function getTokenBySlug(db: Database, slug: string): Token | undefined;
-/**
- * Look up a token by its ULID.
- * Returns undefined if not found.
+ * Parse a goal markdown file into a Goal object.
+ *
+ * Expected format:
+ * ```
+ * ---
+ * title: Learn Rust fundamentals
+ * status: active
+ * parent: become-systems-programmer
+ * created: 2026-03-28
+ * updated: 2026-03-28
+ * ---
+ *
+ * ## Description
+ * ...
+ * ```
+ *
+ * @param content - Raw file content
+ * @param slug - Goal slug (derived from filename by caller)
+ * @param filePath - Absolute path to the file
  */
-declare function getTokenById(db: Database, id: string): Token | undefined;
+declare function parseGoalFile(content: string, slug: string, filePath: string): Goal;
 /**
- * Mark a token as deprecated. Deprecated tokens are excluded from review queues
- * and search results but are not deleted — they can still be consulted.
- *
- * Throws if the token does not exist or is already deprecated.
+ * Serialize a Goal back to markdown with frontmatter.
  */
-declare function deprecateToken(db: Database, slug: string): Token;
+declare function serializeGoal(goal: Goal): string;
 /**
- * Fuzzy search for tokens by keyword query.
- *
- * Ported from the PoC's find-token command: splits the query into word
- * tokens, scores each database token by word overlap plus a substring
- * bonus on the concept field, and returns all matches sorted by score
- * descending.
+ * Extract tasks (checklist items) from goal body.
+ * Returns items like { text: "Complete Rustlings", done: false }.
  */
-declare function findTokens(db: Database, query: string): ScoredToken[];
+declare function extractTasks(body: string): Array<{
+    text: string;
+    done: boolean;
+}>;
 /**
- * List all tokens, optionally filtered by domain.
- * Results are ordered by bloom_level then slug.
+ * Extract token references from goal body.
+ * Looks for lines like `- token/slug` under a "## Tokens" section.
  */
-declare function listTokens(db: Database, options?: ListTokensOptions): Token[];
+declare function extractTokenRefs(body: string): string[];
 
 /**
- * Prerequisite repository — typed wrappers around the prerequisites table.
+ * Goal Engine — manages goal lifecycle via markdown files.
  *
- * Models the dependency graph: "to learn token A, first know token B."
+ * Goals live as markdown files in a directory (typically the personal repo's
+ * goals/ folder). The engine reads, creates, and updates these files.
+ * It does not depend on the database — goals are git-tracked, not DB-tracked.
  */
 
-interface Prerequisite {
-    token_id: string;
-    requires_id: string;
+interface GoalSummary {
+    slug: string;
+    title: string;
+    status: GoalStatus;
+    parent: string | null;
+    taskCount: number;
+    tasksDone: number;
+    tokenCount: number;
 }
-/** A prerequisite row joined with the token it points to. */
-interface PrerequisiteWithToken extends Prerequisite {
+interface CreateGoalInput {
     slug: string;
-    concept: string;
-    domain: string;
-    bloom_level: number;
+    title: string;
+    status?: GoalStatus;
+    parent?: string;
+    description?: string;
 }
 /**
- * Add a prerequisite edge: tokenId requires requiresId.
- *
- * Idempotent — silently ignores duplicate edges.
- * Throws if either token ID does not exist (FK constraint).
- * Throws if a token is declared as its own prerequisite.
+ * List all goals in the goals directory.
+ * Returns summaries sorted by status (active first) then title.
  */
-declare function addPrerequisite(db: Database, tokenId: string, requiresId: string): void;
+declare function listGoals(goalsDir: string): GoalSummary[];
 /**
- * Get the direct prerequisites of a token — "what does token X require?"
- *
- * Returns prerequisite rows joined with the required token's details.
+ * Get a single goal by slug (filename without .md).
+ * Returns undefined if the file doesn't exist.
  */
-declare function getPrerequisites(db: Database, tokenId: string): PrerequisiteWithToken[];
+declare function getGoal(goalsDir: string, slug: string): Goal | undefined;
 /**
- * Get the direct dependents of a token — "what depends on token X?"
- *
- * Returns prerequisite rows joined with the dependent token's details.
+ * Create a new goal file. Throws if a goal with this slug already exists.
  */
-declare function getDependents(db: Database, tokenId: string): PrerequisiteWithToken[];
+declare function createGoal(goalsDir: string, input: CreateGoalInput): Goal;
+/**
+ * Update a goal's status. Writes the updated file back to disk.
+ */
+declare function updateGoalStatus(goalsDir: string, slug: string, status: GoalStatus): Goal;
+/**
+ * Get the goal tree — goals organized by parent relationships.
+ * Returns root goals (no parent) with nested children.
+ */
+declare function getGoalTree(goalsDir: string): Array<GoalSummary & {
+    children: GoalSummary[];
+}>;
 
 /**
- * Card repository — typed wrappers around the cards table.
+ * Agent skills: task recipes the agent learns from user guidance.
  *
- * Each card tracks one user's scheduling state for one token,
- * using FSRS fields (stability, difficulty, elapsed_days, etc.).
+ * When the agent cannot execute a step, it admits it, asks for guidance,
+ * and saves the successful approach here. Skills are linked to tokens so
+ * FSRS decay naturally resurfaces them for review — automation ≠ retention.
  */
 
-type CardState$1 = "new" | "learning" | "review" | "relearning";
-interface Card {
+type SkillSource = "learned" | "builtin";
+interface AgentSkill {
     id: string;
-    token_id: string;
-    user_id: string;
-    stability: number;
-    difficulty: number;
-    elapsed_days: number;
-    scheduled_days: number;
-    reps: number;
-    lapses: number;
-    state: CardState$1;
-    due_at: string;
-    last_review_at: string | null;
-    blocked: number;
-}
+    slug: string;
+    description: string;
+    steps: string[];
+    token_slugs: string[];
+    source: SkillSource;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateAgentSkillInput {
+    slug: string;
+    description: string;
+    steps: string[];
+    token_slugs?: string[];
+    source?: SkillSource;
+}
+declare function createAgentSkill(db: Database, input: CreateAgentSkillInput): AgentSkill;
+declare function getAgentSkill(db: Database, slug: string): AgentSkill | undefined;
+declare function listAgentSkills(db: Database): AgentSkill[];
+
+/**
+ * Card repository — typed wrappers around the cards table.
+ *
+ * Each card tracks one user's scheduling state for one token,
+ * using FSRS fields (stability, difficulty, elapsed_days, etc.).
+ */
+
+type CardState$1 = "new" | "learning" | "review" | "relearning";
+interface Card {
+    id: string;
+    token_id: string;
+    user_id: string;
+    stability: number;
+    difficulty: number;
+    elapsed_days: number;
+    scheduled_days: number;
+    reps: number;
+    lapses: number;
+    state: CardState$1;
+    due_at: string;
+    last_review_at: string | null;
+    blocked: number;
+}
 interface UpdateCardInput {
     stability?: number;
     difficulty?: number;
@@ -170,6 +306,13 @@ interface UpdateCardInput {
     last_review_at?: string | null;
     blocked?: number;
 }
+interface CardDeletionImpact {
+    review_logs: number;
+}
+interface DeleteCardResult {
+    card: Card;
+    impact: CardDeletionImpact;
+}
 /** A due card joined with its token details. */
 interface DueCard extends Card {
     slug: string;
@@ -197,6 +340,10 @@ declare function ensureCard(db: Database, tokenId: string, userId: string): Card
  * Get a card by token+user. Returns undefined if no card exists.
  */
 declare function getCard(db: Database, tokenId: string, userId: string): Card | undefined;
+/**
+ * Get a card by its ULID.
+ */
+declare function getCardById(db: Database, cardId: string): Card | undefined;
 /**
  * Update a card's scheduling fields.
  *
@@ -204,6 +351,14 @@ declare function getCard(db: Database, tokenId: string, userId: string): Card |
  * does not exist.
  */
 declare function updateCard(db: Database, cardId: string, updates: UpdateCardInput): Card;
+/**
+ * Preview the review-log rows that will be removed when deleting a user's card.
+ */
+declare function getCardDeletionImpact(db: Database, tokenId: string, userId: string): CardDeletionImpact;
+/**
+ * Delete one user's card for a token. Review logs cascade via FK.
+ */
+declare function deleteCardForUser(db: Database, tokenId: string, userId: string): DeleteCardResult;
 /**
  * Get all cards that are due for review.
  *
@@ -222,6 +377,44 @@ declare function getDueCards(db: Database, userId: string, now?: string): DueCar
  */
 declare function getBlockedCards(db: Database, userId: string): BlockedCard[];
 
+/**
+ * Prerequisite repository — typed wrappers around the prerequisites table.
+ *
+ * Models the dependency graph: "to learn token A, first know token B."
+ */
+
+interface Prerequisite {
+    token_id: string;
+    requires_id: string;
+}
+/** A prerequisite row joined with the token it points to. */
+interface PrerequisiteWithToken extends Prerequisite {
+    slug: string;
+    concept: string;
+    domain: string;
+    bloom_level: number;
+}
+/**
+ * Add a prerequisite edge: tokenId requires requiresId.
+ *
+ * Idempotent — silently ignores duplicate edges.
+ * Throws if either token ID does not exist (FK constraint).
+ * Throws if a token is declared as its own prerequisite.
+ */
+declare function addPrerequisite(db: Database, tokenId: string, requiresId: string): void;
+/**
+ * Get the direct prerequisites of a token — "what does token X require?"
+ *
+ * Returns prerequisite rows joined with the required token's details.
+ */
+declare function getPrerequisites(db: Database, tokenId: string): PrerequisiteWithToken[];
+/**
+ * Get the direct dependents of a token — "what depends on token X?"
+ *
+ * Returns prerequisite rows joined with the dependent token's details.
+ */
+declare function getDependents(db: Database, tokenId: string): PrerequisiteWithToken[];
+
 /**
  * Review log repository — typed wrappers around the review_logs table.
  *
@@ -356,36 +549,6 @@ declare function logStep(db: Database, input: LogStepInput): SessionStep;
  */
 declare function getSessionSummary(db: Database, sessionId: string): SessionSummary;
 
-/**
- * Agent skills: task recipes the agent learns from user guidance.
- *
- * When the agent cannot execute a step, it admits it, asks for guidance,
- * and saves the successful approach here. Skills are linked to tokens so
- * FSRS decay naturally resurfaces them for review — automation ≠ retention.
- */
-
-type SkillSource = "learned" | "builtin";
-interface AgentSkill {
-    id: string;
-    slug: string;
-    description: string;
-    steps: string[];
-    token_slugs: string[];
-    source: SkillSource;
-    created_at: string;
-    updated_at: string;
-}
-interface CreateAgentSkillInput {
-    slug: string;
-    description: string;
-    steps: string[];
-    token_slugs?: string[];
-    source?: SkillSource;
-}
-declare function createAgentSkill(db: Database, input: CreateAgentSkillInput): AgentSkill;
-declare function getAgentSkill(db: Database, slug: string): AgentSkill | undefined;
-declare function listAgentSkills(db: Database): AgentSkill[];
-
 /**
  * User settings — key/value store backed by the user_config table.
  */
@@ -407,56 +570,299 @@ declare function setSetting(db: Database, key: string, value: string): void;
 declare function deleteSetting(db: Database, key: string): boolean;
 
 /**
- * FSRS-5 — Free Spaced Repetition Scheduler (v5)
+ * Token repository — typed wrappers around the tokens table.
  *
- * Pure-function implementation of the FSRS algorithm that replaces
- * the PoC's SM-2 scheduler. This is the mathematical heart of ZAM's
- * spaced-repetition engine.
+ * Tokens are atomic knowledge concepts with Bloom taxonomy levels
+ * and optional symbiosis modes (shadowing / copilot / autonomy).
+ */
+
+type BloomLevel$1 = 1 | 2 | 3 | 4 | 5;
+type SymbiosisMode = "shadowing" | "copilot" | "autonomy";
+interface Token {
+    id: string;
+    slug: string;
+    concept: string;
+    domain: string;
+    bloom_level: BloomLevel$1;
+    context: string;
+    symbiosis_mode: SymbiosisMode | null;
+    source_link: string | null;
+    question: string | null;
+    created_at: string;
+    updated_at: string;
+    deprecated_at: string | null;
+}
+interface CreateTokenInput {
+    slug: string;
+    concept: string;
+    domain?: string;
+    bloom_level?: BloomLevel$1;
+    context?: string;
+    symbiosis_mode?: SymbiosisMode | null;
+    source_link?: string | null;
+    question?: string | null;
+}
+interface UpdateTokenInput {
+    concept?: string;
+    domain?: string;
+    bloom_level?: BloomLevel$1;
+    context?: string;
+    symbiosis_mode?: SymbiosisMode | null;
+    source_link?: string | null;
+    question?: string | null;
+}
+interface ListTokensOptions {
+    domain?: string;
+}
+interface TokenDeleteImpact {
+    cards: number;
+    review_logs: number;
+    prerequisite_edges_from_token: number;
+    prerequisite_edges_to_token: number;
+    session_steps: number;
+    sessions_touched: number;
+    agent_skills: number;
+}
+interface DeleteTokenResult {
+    token: Token;
+    impact: TokenDeleteImpact;
+}
+interface ScoredToken extends Token {
+    score: number;
+}
+/**
+ * Create a new knowledge token.
+ * Throws if a token with the same slug already exists.
+ */
+declare function createToken(db: Database, input: CreateTokenInput): Token;
+/**
+ * Look up a token by its unique slug.
+ * Returns undefined if not found.
+ */
+declare function getTokenBySlug(db: Database, slug: string): Token | undefined;
+/**
+ * Look up a token by its ULID.
+ * Returns undefined if not found.
+ */
+declare function getTokenById(db: Database, id: string): Token | undefined;
+/**
+ * Update mutable fields on a token.
  *
- * Reference: https://github.com/open-spaced-repetition/fsrs4anki/wiki/The-Algorithm
+ * Slug is intentionally immutable in v1 because it is referenced by other
+ * parts of the system (for example agent skill metadata).
  */
-/** 1 = Again (forgot), 2 = Hard, 3 = Good, 4 = Easy */
-type Rating = 1 | 2 | 3 | 4;
-type CardState = "new" | "learning" | "review" | "relearning";
-interface SchedulingCard {
-    /** Memory stability in days — expected half-life of recall probability. */
-    stability: number;
-    /** Intrinsic difficulty on a 1–10 scale. */
-    difficulty: number;
-    /** Days elapsed since the last review. */
-    elapsedDays: number;
-    /** Currently scheduled interval in days. */
-    scheduledDays: number;
-    /** Count of successful consecutive reviews. */
-    reps: number;
-    /** Times the card was forgotten (rated Again). */
-    lapses: number;
-    /** Current learning state. */
-    state: CardState;
-    /** When the card is next due. */
-    dueAt: Date;
-    /** When the card was last reviewed (null for new cards). */
-    lastReviewAt: Date | null;
+declare function updateToken(db: Database, slug: string, updates: UpdateTokenInput): Token;
+/**
+ * Mark a token as deprecated. Deprecated tokens are excluded from review queues
+ * and search results but are not deleted — they can still be consulted.
+ *
+ * Throws if the token does not exist or is already deprecated.
+ */
+declare function deprecateToken(db: Database, slug: string): Token;
+/**
+ * Preview the rows that will be removed or updated when deleting a token.
+ */
+declare function getTokenDeleteImpact(db: Database, slug: string): TokenDeleteImpact;
+/**
+ * Hard-delete a token and clean up non-FK references that point at its slug.
+ */
+declare function deleteToken(db: Database, slug: string): DeleteTokenResult;
+/**
+ * Fuzzy search for tokens by keyword query.
+ *
+ * Ported from the PoC's find-token command: splits the query into word
+ * tokens, scores each database token by word overlap plus a substring
+ * bonus on the concept field, and returns all matches sorted by score
+ * descending.
+ */
+declare function findTokens(db: Database, query: string): ScoredToken[];
+/**
+ * List all tokens, optionally filtered by domain.
+ * Results are ordered by bloom_level then slug.
+ */
+declare function listTokens(db: Database, options?: ListTokensOptions): Token[];
+
+/**
+ * Monitor log analyzer — maps observed shell commands to token ratings.
+ *
+ * Pure functions, no DB or filesystem access. Takes parsed command records
+ * and a token-to-pattern mapping, returns ratings with evidence.
+ */
+interface MonitorEvent {
+    type: "command_start" | "command_end" | "monitor_meta";
+    ts: string;
+    seq?: number;
+    pid?: number;
+    command?: string;
+    cwd?: string;
+    exit_code?: number;
+    event?: "start" | "stop";
+    session_id?: string;
+    shell?: string;
 }
-interface FSRSParameters {
-    /** 19 optimised weight parameters (w0 – w18). */
-    w: number[];
-    /** Target retention rate, e.g. 0.9 means we aim for 90% recall. */
-    requestRetention: number;
+interface CommandRecord {
+    seq: number;
+    pid: number;
+    command: string;
+    cwd: string;
+    startedAt: string;
+    endedAt: string | null;
+    durationMs: number | null;
+    exitCode: number | null;
 }
-interface FSRS {
-    /** Return a fully updated card after applying a rating. Pure function. */
-    schedule(card: SchedulingCard, rating: Rating, now?: Date): SchedulingCard;
-    /** The parameters baked into this instance. */
-    readonly params: Readonly<FSRSParameters>;
+interface TokenPattern {
+    slug: string;
+    patterns: string[];
+}
+interface ObservationRating {
+    tokenSlug: string;
+    rating: 1 | 2 | 3 | 4 | null;
+    confidence: "high" | "medium" | "low";
+    evidence: {
+        matchedCommands: number;
+        helpSeeking: boolean;
+        errorCount: number;
+        selfCorrections: number;
+        medianGapMs: number | null;
+        thinkingGapMs: number | null;
+    };
+    matchedCommandTexts: string[];
+}
+interface AnalysisResult {
+    ratings: ObservationRating[];
+    unmatchedCommands: string[];
+    timeSpan: {
+        start: string;
+        end: string;
+        durationMs: number;
+    } | null;
+}
+/**
+ * Parse a JSONL string into MonitorEvent objects.
+ * Skips malformed lines silently.
+ */
+declare function parseMonitorLog(jsonl: string): MonitorEvent[];
+/**
+ * Pair command_start and command_end events by (pid, seq) into CommandRecords.
+ */
+declare function pairCommands(events: MonitorEvent[]): CommandRecord[];
+/**
+ * Analyze observed commands against token patterns and produce ratings.
+ */
+declare function analyzeObservation(commands: CommandRecord[], tokenPatterns: TokenPattern[]): AnalysisResult;
+
+/**
+ * Monitor I/O — read/write JSONL files for shell observation.
+ *
+ * Monitor logs live at ~/.zam/monitor/<session-id>.jsonl.
+ * Separated from analyzer.ts so the analyzer remains pure-function testable.
+ */
+
+/** Get the monitor directory path. */
+declare function getMonitorDir(): string;
+/** Get the JSONL file path for a session. */
+declare function getMonitorPath(sessionId: string): string;
+/** Ensure the monitor directory exists (mode 0700 for privacy). */
+declare function ensureMonitorDir(): void;
+/** Append a single event to the session's JSONL file. */
+declare function writeMonitorEvent(sessionId: string, event: MonitorEvent): void;
+/** Read and parse all events from a session's monitor log. */
+declare function readMonitorLog(sessionId: string): MonitorEvent[];
+/** Check if a monitor log exists for a session. */
+declare function monitorLogExists(sessionId: string): boolean;
+/** Get basic stats about a monitor log without full parsing. */
+declare function getMonitorLogStats(sessionId: string): {
+    exists: boolean;
+    sizeBytes: number;
+    lineCount: number;
+};
+
+/**
+ * Shell hook code generation for zsh, bash, and PowerShell.
+ *
+ * Pure functions that return shell code strings. The CLI command
+ * `zam monitor start/stop` calls these and prints to stdout.
+ */
+/**
+ * Generate zsh hooks that capture commands to a JSONL file.
+ * Uses $EPOCHREALTIME for sub-second timestamp precision.
+ */
+declare function generateZshHooks(monitorFile: string, sessionId: string): string;
+/**
+ * Generate bash hooks that capture commands to a JSONL file.
+ * Uses DEBUG trap for preexec, PROMPT_COMMAND for precmd.
+ */
+declare function generateBashHooks(monitorFile: string, sessionId: string): string;
+/**
+ * Generate PowerShell hooks that capture completed commands to a JSONL file.
+ * PowerShell has no zsh-style preexec hook, so this records the most recent
+ * history item from the prompt function after each command completes.
+ */
+declare function generatePowerShellHooks(monitorFile: string, sessionId: string): string;
+/** Generate zsh code to remove monitor hooks. */
+declare function generateZshUnhooks(): string;
+/** Generate bash code to remove monitor hooks. */
+declare function generateBashUnhooks(): string;
+/** Generate PowerShell code to remove monitor hooks. */
+declare function generatePowerShellUnhooks(): string;
+
+/**
+ * Skill Discovery — identifies recurring non-standard command patterns
+ * across multiple sessions and proposes them as minimal reusable skills.
+ *
+ * The key insight from Increment 2: "The human's demonstrated competence
+ * is the gate for automation — not the other way around." A pattern must
+ * appear consistently across sessions before being proposed as a skill.
+ *
+ * Pure functions — no DB access. Callers provide command records and
+ * existing skills; this module returns proposed skills.
+ */
+
+interface CommandSequence {
+    /** The ordered command prefixes forming the pattern (e.g., ["git checkout", "npm install", "npm run build"]) */
+    steps: string[];
+    /** How many sessions contained this sequence */
+    sessionCount: number;
+    /** Total occurrences across all sessions */
+    totalOccurrences: number;
+    /** Example full commands from the most recent occurrence */
+    examples: string[];
+}
+interface SkillProposal {
+    /** Suggested slug for the skill */
+    slug: string;
+    /** Human-readable description of what the pattern does */
+    description: string;
+    /** The command steps forming the skill */
+    steps: string[];
+    /** How many sessions demonstrated this pattern */
+    sessionCount: number;
+    /** Confidence that this is a real, repeatable skill */
+    confidence: "high" | "medium" | "low";
+    /** Example commands from actual usage */
+    examples: string[];
+}
+interface DiscoveryOptions {
+    /** Minimum number of sessions a pattern must appear in (default: 2) */
+    minSessions?: number;
+    /** Minimum sequence length to consider (default: 2) */
+    minSequenceLength?: number;
+    /** Maximum sequence length to consider (default: 5) */
+    maxSequenceLength?: number;
+    /** Existing skill slugs to exclude from proposals */
+    existingSkillSlugs?: string[];
 }
 /**
- * Create an FSRS scheduler instance.
+ * Discover recurring command patterns across multiple sessions.
  *
- * All scheduling is done through pure functions — no side effects,
- * no database access, no mutation of the input card.
+ * Takes a map of session ID → command records, finds command sequences
+ * that appear in multiple sessions, and proposes them as skills.
+ *
+ * @param sessionCommands - Map of session ID to that session's commands
+ * @param options - Discovery configuration
+ * @returns Array of skill proposals, sorted by confidence then session count
  */
-declare function createFSRS(params?: Partial<FSRSParameters>): FSRS;
+declare function discoverSkills(sessionCommands: Map<string, CommandRecord[]>, options?: DiscoveryOptions): SkillProposal[];
 
 /**
  * Cascade Block & Unblock — prerequisite-aware blocking logic.
@@ -513,104 +919,56 @@ declare function cascadeBlock(db: Database, userId: string, tokenSlug: string):
 declare function unblockReady(db: Database, userId: string): UnblockResult;
 
 /**
- * Reorder items so no domain appears more than `maxConsecutive` times in a row.
- *
- * Algorithm: group items by domain, then round-robin across domain groups.
- * Each round picks one item from each non-exhausted domain. Within a domain,
- * the original order is preserved (so urgency sorting survives).
- *
- * If a domain has more items than others, its extras will appear after all
- * other domains are exhausted — but the `maxConsecutive` cap is still
- * respected by inserting items from the largest remaining domains first.
+ * FSRS-5 — Free Spaced Repetition Scheduler (v5)
  *
- * @param items - Array of items to interleave. Not mutated.
- * @param maxConsecutive - Max consecutive items from the same domain. Defaults to 2.
- * @returns A new array with the same items in interleaved order.
- */
-declare function interleave<T extends {
-    domain: string;
-}>(items: T[], maxConsecutive?: number): T[];
-
-/**
- * Review Queue Builder — assembles a session's review queue.
+ * Pure-function implementation of the FSRS algorithm that replaces
+ * the PoC's SM-2 scheduler. This is the mathematical heart of ZAM's
+ * spaced-repetition engine.
  *
- * Combines due-card fetching, new-card selection, urgency sorting,
- * and cross-domain interleaving into a single ready-to-review queue.
+ * Reference: https://github.com/open-spaced-repetition/fsrs4anki/wiki/The-Algorithm
  */
-
-interface ReviewQueueOptions {
-    userId: string;
-    maxNew?: number;
-    maxReviews?: number;
-    now?: Date;
+/** 1 = Again (forgot), 2 = Hard, 3 = Good, 4 = Easy */
+type Rating = 1 | 2 | 3 | 4;
+type CardState = "new" | "learning" | "review" | "relearning";
+interface SchedulingCard {
+    /** Memory stability in days — expected half-life of recall probability. */
+    stability: number;
+    /** Intrinsic difficulty on a 1–10 scale. */
+    difficulty: number;
+    /** Days elapsed since the last review. */
+    elapsedDays: number;
+    /** Currently scheduled interval in days. */
+    scheduledDays: number;
+    /** Count of successful consecutive reviews. */
+    reps: number;
+    /** Times the card was forgotten (rated Again). */
+    lapses: number;
+    /** Current learning state. */
+    state: CardState;
+    /** When the card is next due. */
+    dueAt: Date;
+    /** When the card was last reviewed (null for new cards). */
+    lastReviewAt: Date | null;
 }
-interface ReviewQueueItem {
-    cardId: string;
-    tokenId: string;
-    slug: string;
-    concept: string;
-    domain: string;
-    bloomLevel: number;
-    state: string;
-    dueAt: string;
+interface FSRSParameters {
+    /** 19 optimised weight parameters (w0 – w18). */
+    w: number[];
+    /** Target retention rate, e.g. 0.9 means we aim for 90% recall. */
+    requestRetention: number;
 }
-interface ReviewQueue {
-    items: ReviewQueueItem[];
-    newCount: number;
-    reviewCount: number;
-    relearnCount: number;
-    totalDomains: string[];
+interface FSRS {
+    /** Return a fully updated card after applying a rating. Pure function. */
+    schedule(card: SchedulingCard, rating: Rating, now?: Date): SchedulingCard;
+    /** The parameters baked into this instance. */
+    readonly params: Readonly<FSRSParameters>;
 }
 /**
- * Build a review queue for a user's study session.
- *
- * The queue is assembled in stages:
- * 1. Fetch all due cards (not blocked, due_at <= now, state in review/relearning/learning)
- * 2. Fetch new cards (state = 'new', not blocked) up to maxNew
- * 3. Sort overdue cards by urgency — most overdue first
- * 4. Apply cross-domain interleaving to prevent same-domain streaks
- * 5. Intersperse new cards at regular intervals (every 5th position)
- * 6. Cap total at maxReviews
- *
- * @param db - Database connection
- * @param options - Queue building options
- * @returns The assembled review queue with metadata
- */
-declare function buildReviewQueue(db: Database, options: ReviewQueueOptions): ReviewQueue;
-
-/**
- * Active Recall Prompt Generation
+ * Create an FSRS scheduler instance.
  *
- * Generates review prompts from tokens, adapting the question style
- * to the token's Bloom taxonomy level. This is NOT an LLM call —
- * it's template-based prompt assembly for the CLI and bridge.
- */
-type BloomLevel = 1 | 2 | 3 | 4 | 5;
-interface RecallPrompt {
-    cardId: string;
-    tokenId: string;
-    slug: string;
-    question: string;
-    concept: string;
-    domain: string;
-    bloomLevel: BloomLevel;
-    bloomVerb: string;
-    hints: string[];
-}
-interface PromptInput {
-    cardId: string;
-    tokenId: string;
-    slug: string;
-    concept: string;
-    domain: string;
-    bloomLevel: BloomLevel;
-}
-/**
- * Generate a recall prompt for a token at its Bloom level.
- * When called from the CLI, the prompt is rendered in the terminal.
- * When called from the AI bridge, the JSON is returned for the AI to present conversationally.
+ * All scheduling is done through pure functions — no side effects,
+ * no database access, no mutation of the input card.
  */
-declare function generatePrompt(input: PromptInput): RecallPrompt;
+declare function createFSRS(params?: Partial<FSRSParameters>): FSRS;
 
 /**
  * Rating Evaluator
@@ -645,354 +1003,272 @@ interface EvaluateResult {
  */
 declare function evaluateRating(db: Database, input: EvaluateInput): EvaluateResult;
 
-/**
- * Learning Analytics
- *
- * Progress statistics, competence tracking, and session summaries.
- * Ported from PoC's `stats` command with additions for FSRS and symbiosis modes.
- */
-
-interface UserStats {
+type ReviewActionType = "rate" | "skip" | "edit-token" | "deprecate-token" | "delete-token" | "delete-card" | "stop";
+interface ExecuteReviewActionInput {
+    cardId: string;
     userId: string;
-    totalTokens: number;
-    cardsInDeck: number;
-    dueToday: number;
-    blocked: number;
-    mature: number;
-    avgStability: number | null;
-    totalSessions: number;
-    lastSession: string | null;
+    action: ReviewActionType;
+    rating?: Rating;
+    tokenUpdates?: UpdateTokenInput;
 }
-interface DomainCompetence {
-    domain: string;
-    totalCards: number;
-    matureCards: number;
-    avgStability: number;
-    retentionRate: number;
-    suggestedMode: "shadowing" | "copilot" | "autonomy";
+interface ReviewActionResult {
+    action: ReviewActionType;
+    token: Token;
+    evaluation?: EvaluateResult;
+    blocked?: CascadeBlockResult;
+    updatedToken?: Token;
+    deletedToken?: DeleteTokenResult;
+    deletedCard?: DeleteCardResult;
+    skipped?: boolean;
+    stopped?: boolean;
 }
-/**
- * Get overall learning stats for a user (ported from PoC's `stats` command).
- */
-declare function getUserStats(db: Database, userId: string): UserStats;
-/**
- * Get competence per domain for a user.
- * Used to suggest symbiosis mode transitions.
- */
-declare function getDomainCompetence(db: Database, userId: string): DomainCompetence[];
+declare function executeReviewAction(db: Database, input: ExecuteReviewActionInput): ReviewActionResult;
 
 /**
- * Monitor log analyzer — maps observed shell commands to token ratings.
+ * Active Recall Prompt Generation
  *
- * Pure functions, no DB or filesystem access. Takes parsed command records
- * and a token-to-pattern mapping, returns ratings with evidence.
+ * Generates review prompts from tokens, adapting the question style
+ * to the token's Bloom taxonomy level. This is NOT an LLM call —
+ * it's template-based prompt assembly for the CLI and bridge.
  */
-interface MonitorEvent {
-    type: "command_start" | "command_end" | "monitor_meta";
-    ts: string;
-    seq?: number;
-    pid?: number;
-    command?: string;
-    cwd?: string;
-    exit_code?: number;
-    event?: "start" | "stop";
-    session_id?: string;
-    shell?: string;
-}
-interface CommandRecord {
-    seq: number;
-    pid: number;
-    command: string;
-    cwd: string;
-    startedAt: string;
-    endedAt: string | null;
-    durationMs: number | null;
-    exitCode: number | null;
-}
-interface TokenPattern {
+type BloomLevel = 1 | 2 | 3 | 4 | 5;
+interface RecallPrompt {
+    cardId: string;
+    tokenId: string;
     slug: string;
-    patterns: string[];
-}
-interface ObservationRating {
-    tokenSlug: string;
-    rating: 1 | 2 | 3 | 4 | null;
-    confidence: "high" | "medium" | "low";
-    evidence: {
-        matchedCommands: number;
-        helpSeeking: boolean;
-        errorCount: number;
-        selfCorrections: number;
-        medianGapMs: number | null;
-        thinkingGapMs: number | null;
-    };
-    matchedCommandTexts: string[];
+    question: string;
+    concept: string;
+    domain: string;
+    bloomLevel: BloomLevel;
+    bloomVerb: string;
+    hints: string[];
+    sourceLink?: string | null;
 }
-interface AnalysisResult {
-    ratings: ObservationRating[];
-    unmatchedCommands: string[];
-    timeSpan: {
-        start: string;
-        end: string;
-        durationMs: number;
-    } | null;
+interface PromptInput {
+    cardId: string;
+    tokenId: string;
+    slug: string;
+    concept: string;
+    domain: string;
+    bloomLevel: BloomLevel;
+    sourceLink?: string | null;
+    question?: string | null;
 }
 /**
- * Parse a JSONL string into MonitorEvent objects.
- * Skips malformed lines silently.
+ * Generate a template-based concept-free recall cue using the slug and domain.
  */
-declare function parseMonitorLog(jsonl: string): MonitorEvent[];
+declare function generateConceptFreeCue(bloomLevel: BloomLevel, slug: string, _domain: string): string;
 /**
- * Pair command_start and command_end events by (pid, seq) into CommandRecords.
+ * Generate a recall prompt for a token at its Bloom level.
+ * When called from the CLI, the prompt is rendered in the terminal.
+ * When called from the AI bridge, the JSON is returned for the AI to present conversationally.
  */
-declare function pairCommands(events: MonitorEvent[]): CommandRecord[];
+declare function generatePrompt(input: PromptInput): RecallPrompt;
+
+interface ResolvedReference {
+    sourceType: "local" | "remote_web" | "dynamic_search";
+    content: string;
+    filePath?: string;
+    url?: string;
+}
 /**
- * Analyze observed commands against token patterns and produce ratings.
+ * A source reference resolved and bounded for inclusion in a review payload.
+ * Same shape as ResolvedReference plus the originating link and a truncation flag.
  */
-declare function analyzeObservation(commands: CommandRecord[], tokenPatterns: TokenPattern[]): AnalysisResult;
-
+interface ReviewContext {
+    sourceLink: string;
+    sourceType: ResolvedReference["sourceType"];
+    content: string;
+    filePath?: string;
+    url?: string;
+    truncated: boolean;
+}
+/** Default cap on resolved content length, so bridge JSON / terminal output stays bounded. */
+declare const DEFAULT_REVIEW_CONTEXT_MAX_CHARS = 6000;
 /**
- * Monitor I/O — read/write JSONL files for shell observation.
- *
- * Monitor logs live at ~/.zam/monitor/<session-id>.jsonl.
- * Separated from analyzer.ts so the analyzer remains pure-function testable.
+ * Resolves a given token's source_link into readable textual content.
  */
-
-/** Get the monitor directory path. */
-declare function getMonitorDir(): string;
-/** Get the JSONL file path for a session. */
-declare function getMonitorPath(sessionId: string): string;
-/** Ensure the monitor directory exists (mode 0700 for privacy). */
-declare function ensureMonitorDir(): void;
-/** Append a single event to the session's JSONL file. */
-declare function writeMonitorEvent(sessionId: string, event: MonitorEvent): void;
-/** Read and parse all events from a session's monitor log. */
-declare function readMonitorLog(sessionId: string): MonitorEvent[];
-/** Check if a monitor log exists for a session. */
-declare function monitorLogExists(sessionId: string): boolean;
-/** Get basic stats about a monitor log without full parsing. */
-declare function getMonitorLogStats(sessionId: string): {
-    exists: boolean;
-    sizeBytes: number;
-    lineCount: number;
-};
-
+declare function resolveReference(sourceLink: string): Promise<ResolvedReference>;
 /**
- * Shell hook code generation for zsh and bash.
+ * Resolve a token's source_link into bounded, review-ready context.
  *
- * Pure functions that return shell code strings. The CLI command
- * `zam monitor start/stop` calls these and prints to stdout.
- * The user wraps with `eval "$(zam monitor start ...)"`.
+ * Wraps {@link resolveReference} for the review/bridge flow: returns `null`
+ * for empty links and caps content length so the surrounding payload (bridge
+ * JSON or terminal output) stays manageable, flagging when truncation occurred.
  */
+declare function resolveReviewContext(sourceLink: string | null | undefined, opts?: {
+    maxChars?: number;
+}): Promise<ReviewContext | null>;
 /**
- * Generate zsh hooks that capture commands to a JSONL file.
- * Uses $EPOCHREALTIME for sub-second timestamp precision.
+ * Normalizes a path, stripping anchors and converting separators.
  */
-declare function generateZshHooks(monitorFile: string, sessionId: string): string;
+declare function normalizePath(p: string): string;
 /**
- * Generate bash hooks that capture commands to a JSONL file.
- * Uses DEBUG trap for preexec, PROMPT_COMMAND for precmd.
+ * Checks if a token's source_link references a changed file.
  */
-declare function generateBashHooks(monitorFile: string, sessionId: string): string;
-/** Generate zsh code to remove monitor hooks. */
-declare function generateZshUnhooks(): string;
-/** Generate bash code to remove monitor hooks. */
-declare function generateBashUnhooks(): string;
+declare function matchesFilePath(sourceLink: string | null, changedFile: string): boolean;
 
 /**
- * Skill Discovery — identifies recurring non-standard command patterns
- * across multiple sessions and proposes them as minimal reusable skills.
- *
- * The key insight from Increment 2: "The human's demonstrated competence
- * is the gate for automation — not the other way around." A pattern must
- * appear consistently across sessions before being proposed as a skill.
+ * Reorder items so no domain appears more than `maxConsecutive` times in a row.
  *
- * Pure functions — no DB access. Callers provide command records and
- * existing skills; this module returns proposed skills.
- */
-
-interface CommandSequence {
-    /** The ordered command prefixes forming the pattern (e.g., ["git checkout", "npm install", "npm run build"]) */
-    steps: string[];
-    /** How many sessions contained this sequence */
-    sessionCount: number;
-    /** Total occurrences across all sessions */
-    totalOccurrences: number;
-    /** Example full commands from the most recent occurrence */
-    examples: string[];
-}
-interface SkillProposal {
-    /** Suggested slug for the skill */
-    slug: string;
-    /** Human-readable description of what the pattern does */
-    description: string;
-    /** The command steps forming the skill */
-    steps: string[];
-    /** How many sessions demonstrated this pattern */
-    sessionCount: number;
-    /** Confidence that this is a real, repeatable skill */
-    confidence: "high" | "medium" | "low";
-    /** Example commands from actual usage */
-    examples: string[];
-}
-interface DiscoveryOptions {
-    /** Minimum number of sessions a pattern must appear in (default: 2) */
-    minSessions?: number;
-    /** Minimum sequence length to consider (default: 2) */
-    minSequenceLength?: number;
-    /** Maximum sequence length to consider (default: 5) */
-    maxSequenceLength?: number;
-    /** Existing skill slugs to exclude from proposals */
-    existingSkillSlugs?: string[];
-}
-/**
- * Discover recurring command patterns across multiple sessions.
+ * Algorithm: group items by domain, then round-robin across domain groups.
+ * Each round picks one item from each non-exhausted domain. Within a domain,
+ * the original order is preserved (so urgency sorting survives).
  *
- * Takes a map of session ID → command records, finds command sequences
- * that appear in multiple sessions, and proposes them as skills.
+ * If a domain has more items than others, its extras will appear after all
+ * other domains are exhausted — but the `maxConsecutive` cap is still
+ * respected by inserting items from the largest remaining domains first.
  *
- * @param sessionCommands - Map of session ID to that session's commands
- * @param options - Discovery configuration
- * @returns Array of skill proposals, sorted by confidence then session count
+ * @param items - Array of items to interleave. Not mutated.
+ * @param maxConsecutive - Max consecutive items from the same domain. Defaults to 2.
+ * @returns A new array with the same items in interleaved order.
  */
-declare function discoverSkills(sessionCommands: Map<string, CommandRecord[]>, options?: DiscoveryOptions): SkillProposal[];
+declare function interleave<T extends {
+    domain: string;
+}>(items: T[], maxConsecutive?: number): T[];
 
 /**
- * Goal file parser — reads markdown files with YAML-style frontmatter.
+ * Review Queue Builder — assembles a session's review queue.
  *
- * Goals are persisted as markdown files in the personal repo.
- * Each file has simple key: value frontmatter (no nested structures)
- * and a markdown body with description, tasks, and token references.
+ * Combines due-card fetching, new-card selection, urgency sorting,
+ * and cross-domain interleaving into a single ready-to-review queue.
  */
-type GoalStatus = "active" | "completed" | "paused" | "abandoned";
-interface Goal {
+
+interface ReviewQueueOptions {
+    userId: string;
+    maxNew?: number;
+    maxReviews?: number;
+    now?: Date;
+}
+interface ReviewQueueItem {
+    cardId: string;
+    tokenId: string;
     slug: string;
-    title: string;
-    status: GoalStatus;
-    parent: string | null;
-    created: string;
-    updated: string;
-    body: string;
-    filePath: string;
+    concept: string;
+    domain: string;
+    bloomLevel: number;
+    state: string;
+    dueAt: string;
+    sourceLink: string | null;
+    question: string | null;
 }
-interface GoalFrontmatter {
-    title?: string;
-    status?: string;
-    parent?: string;
-    created?: string;
-    updated?: string;
+interface ReviewQueue {
+    items: ReviewQueueItem[];
+    newCount: number;
+    reviewCount: number;
+    relearnCount: number;
+    totalDomains: string[];
 }
 /**
- * Parse a goal markdown file into a Goal object.
- *
- * Expected format:
- * ```
- * ---
- * title: Learn Rust fundamentals
- * status: active
- * parent: become-systems-programmer
- * created: 2026-03-28
- * updated: 2026-03-28
- * ---
+ * Build a review queue for a user's study session.
  *
- * ## Description
- * ...
- * ```
+ * The queue is assembled in stages:
+ * 1. Fetch all due cards (not blocked, due_at <= now, state in review/relearning/learning)
+ * 2. Fetch new cards (state = 'new', not blocked) up to maxNew
+ * 3. Sort overdue cards by urgency — most overdue first
+ * 4. Apply cross-domain interleaving to prevent same-domain streaks
+ * 5. Intersperse new cards at regular intervals (every 5th position)
+ * 6. Cap total at maxReviews
  *
- * @param content - Raw file content
- * @param slug - Goal slug (derived from filename by caller)
- * @param filePath - Absolute path to the file
+ * @param db - Database connection
+ * @param options - Queue building options
+ * @returns The assembled review queue with metadata
  */
-declare function parseGoalFile(content: string, slug: string, filePath: string): Goal;
+declare function buildReviewQueue(db: Database, options: ReviewQueueOptions): ReviewQueue;
+
 /**
- * Serialize a Goal back to markdown with frontmatter.
+ * Get the path to ZAM's internal package SKILL.md.
  */
-declare function serializeGoal(goal: Goal): string;
+declare function getPackageSkillPath(agent?: "default" | "claude" | "codex"): string;
 /**
- * Extract tasks (checklist items) from goal body.
- * Returns items like { text: "Complete Rustlings", done: false }.
+ * Distribute the ZAM active-recall training skill globally.
+ * Copies SKILL.md into global directories for supported coding agents.
  */
-declare function extractTasks(body: string): Array<{
-    text: string;
-    done: boolean;
+declare function distributeGlobalSkills(home?: string): Array<{
+    name: string;
+    path: string;
+    success: boolean;
 }>;
 /**
- * Extract token references from goal body.
- * Looks for lines like `- token/slug` under a "## Tokens" section.
+ * Inject the ZAM shell observation hook into user profile scripts so monitoring
+ * is automatically initialized on startup.
  */
-declare function extractTokenRefs(body: string): string[];
+declare function injectShellHooks(): Array<{
+    shell: string;
+    file: string;
+    success: boolean;
+    alreadyHooked: boolean;
+}>;
 
+type SupportedLocale = "en" | "de" | "es" | "fr" | "pt" | "zh" | "ja";
 /**
- * Goal Engine — manages goal lifecycle via markdown files.
- *
- * Goals live as markdown files in a directory (typically the personal repo's
- * goals/ folder). The engine reads, creates, and updates these files.
- * It does not depend on the database — goals are git-tracked, not DB-tracked.
+ * Clean and map raw locale string (e.g., "de_DE.UTF-8" or "en-US") to SupportedLocale.
  */
-
-interface GoalSummary {
-    slug: string;
-    title: string;
-    status: GoalStatus;
-    parent: string | null;
-    taskCount: number;
-    tasksDone: number;
-    tokenCount: number;
-}
-interface CreateGoalInput {
-    slug: string;
-    title: string;
-    status?: GoalStatus;
-    parent?: string;
-    description?: string;
-}
+declare function normalizeLocale(raw: string): SupportedLocale;
 /**
- * List all goals in the goals directory.
- * Returns summaries sorted by status (active first) then title.
+ * Detect the operating system's active language code dynamically.
  */
-declare function listGoals(goalsDir: string): GoalSummary[];
+declare function detectSystemLocale(): SupportedLocale;
+
+type TranslationKey = "welcome" | "new_review_relearn" | "domains" | "instruction" | "quit_hint" | "offline_warning" | "offline_instruction" | "nothing_due" | "evaluating" | "generating_question" | "translating" | "prompt_answer" | "session_ended" | "session_complete" | "cards_rated" | "avg_rating" | "forgot" | "feedback_title" | "answer_title" | "keep_waiting" | "local_ai_working" | "wait_warning" | "wait_info" | "keep_waiting_llm" | "proceeding_offline" | "eval_skipped";
 /**
- * Get a single goal by slug (filename without .md).
- * Returns undefined if the file doesn't exist.
+ * Format and interpolate a translation string with key-value params.
  */
-declare function getGoal(goalsDir: string, slug: string): Goal | undefined;
+declare function t(locale: SupportedLocale, key: TranslationKey, params?: Record<string, string | number>): string;
+
+interface InstallResult {
+    success: boolean;
+    message: string;
+}
 /**
- * Create a new goal file. Throws if a goal with this slug already exists.
+ * Check if a command is executable on the system.
  */
-declare function createGoal(goalsDir: string, input: CreateGoalInput): Goal;
+declare function hasCommand(cmd: string): boolean;
 /**
- * Update a goal's status. Writes the updated file back to disk.
+ * Install FastFlowLM via winget on Windows.
  */
-declare function updateGoalStatus(goalsDir: string, slug: string, status: GoalStatus): Goal;
+declare function installFastFlowLM(): InstallResult;
 /**
- * Get the goal tree — goals organized by parent relationships.
- * Returns root goals (no parent) with nested children.
+ * Install Ollama via Homebrew on macOS.
  */
-declare function getGoalTree(goalsDir: string): Array<GoalSummary & {
-    children: GoalSummary[];
-}>;
+declare function installOllama(): InstallResult;
 
+interface SystemProfile {
+    os: "windows" | "macos" | "linux" | "unknown";
+    arch: "x64" | "arm64" | "unknown";
+    hasRyzenNPU: boolean;
+    hasAppleSilicon: boolean;
+    recommendedRunner: "fastflowlm" | "ollama" | "generic";
+    recommendedModel: string;
+}
 /**
- * Azure DevOps connector — fetches work items from ADO boards.
+ * Profile the active system hardware and software capabilities.
  */
+declare function getSystemProfile(): SystemProfile;
 
-interface ADOConfig {
-    orgUrl: string;
-    project: string;
-    pat: string;
+interface RepoPaths {
+    personal: string | null;
+    team: string | null;
+    org: string | null;
 }
-interface WorkItem {
-    id: number;
-    title: string;
-    state: string;
-    type: string;
-    assignedTo: string;
-}
-/** Load ADO config from user settings. Returns null if not configured. */
-declare function loadADOConfig(db: Database): ADOConfig | null;
 /**
- * Fetch active work items assigned to the current user.
- * Uses WIQL to query, then batch-fetches work item details.
+ * Resolve absolute paths for personal, team, and organization repositories.
+ * Personal falls back to personal.workspace_dir if repo.personal is not set.
  */
-declare function fetchActiveWorkItems(config: ADOConfig): Promise<WorkItem[]>;
+declare function getRepoPaths(db: Database): RepoPaths;
+/**
+ * Resolve a specific repo's path, or null if not configured.
+ */
+declare function resolveRepoPath(db: Database, type: "personal" | "team" | "org"): string | null;
+/**
+ * Resolve paths to all existing "/beliefs" directories in the hierarchy,
+ * sorted from most specific (personal) to most general (org).
+ */
+declare function resolveAllBeliefPaths(db: Database): string[];
+/**
+ * Resolve paths to all existing "/goals" directories in the hierarchy,
+ * sorted from most specific (personal) to most general (org).
+ */
+declare function resolveAllGoalPaths(db: Database): string[];
 
-export { type ADOConfig, type AgentSkill, type AnalysisResult, type BloomLevel$1 as BloomLevel, type Card, type CardState$1 as CardState, type CascadeBlockResult, type CommandRecord, type CommandSequence, type CreateAgentSkillInput, type CreateGoalInput, type CreateReviewInput, type CreateSessionInput, type CreateTokenInput, type DiscoveryOptions, type DomainCompetence, type EvaluateInput, type EvaluateResult, type ExecutionContext, type FSRSParameters, type Goal, type GoalFrontmatter, type GoalStatus, type GoalSummary, type LogStepInput, type MonitorEvent, type ObservationRating, type Prerequisite, type PrerequisiteWithToken, type PromptInput, type Rating, type RecallPrompt, type ReviewLog, type ReviewQueue, type ReviewQueueItem, type ReviewQueueOptions, type SchedulingCard, type Session, type SessionStep, type SessionSummary, type SkillProposal, type SkillSource, type SymbiosisMode, type Token, type TokenPattern, type UnblockResult, type UpdateCardInput, type UserSetting, type UserStats, type WorkItem, addPrerequisite, analyzeObservation, buildReviewQueue, cascadeBlock, createAgentSkill, createFSRS, createGoal, createToken, deleteSetting, deprecateToken, discoverSkills, endSession, ensureCard, ensureMonitorDir, evaluateRating, extractTasks, extractTokenRefs, fetchActiveWorkItems, findTokens, generateBashHooks, generateBashUnhooks, generatePrompt, generateZshHooks, generateZshUnhooks, getAgentSkill, getAllSettings, getAllSettingsDetailed, getBlockedCards, getCard, getDefaultDbPath, getDependents, getDomainCompetence, getDueCards, getGoal, getGoalTree, getMonitorDir, getMonitorLogStats, getMonitorPath, getPrerequisites, getReviewsForCard, getReviewsForUser, getSessionSummary, getSetting, getTokenById, getTokenBySlug, getUserStats, interleave, listAgentSkills, listGoals, listTokens, loadADOConfig, logReview, logStep, monitorLogExists, openDatabase, openDatabaseWithSync, pairCommands, parseGoalFile, parseMonitorLog, readMonitorLog, serializeGoal, setSetting, startSession, unblockReady, updateCard, updateGoalStatus, writeMonitorEvent };
+export { type ADOConfig, type ADOCredentials, type AgentSkill, type AnalysisResult, type BloomLevel$1 as BloomLevel, type Card, type CardDeletionImpact, type CardState$1 as CardState, type CascadeBlockResult, type CommandRecord, type CommandSequence, type CreateAgentSkillInput, type CreateGoalInput, type CreateReviewInput, type CreateSessionInput, type CreateTokenInput, type Credentials, DEFAULT_REVIEW_CONTEXT_MAX_CHARS, type DeleteCardResult, type DeleteTokenResult, type DiscoveryOptions, type DomainCompetence, type EvaluateInput, type EvaluateResult, type ExecuteReviewActionInput, type ExecutionContext, type FSRSParameters, type Goal, type GoalFrontmatter, type GoalStatus, type GoalSummary, type InstallResult, type LogStepInput, type MonitorEvent, type ObservationRating, type Prerequisite, type PrerequisiteWithToken, type PromptInput, type Rating, type RecallPrompt, type RepoPaths, type ResolvedReference, type ReviewActionResult, type ReviewActionType, type ReviewContext, type ReviewLog, type ReviewQueue, type ReviewQueueItem, type ReviewQueueOptions, type SchedulingCard, type Session, type SessionStep, type SessionSummary, type SkillProposal, type SkillSource, type SupportedLocale, type SymbiosisMode, type SystemProfile, type Token, type TokenDeleteImpact, type TokenPattern, type TranslationKey, type TursoCredentials, type UnblockResult, type UpdateCardInput, type UpdateTokenInput, type UserSetting, type UserStats, type WorkItem, addPrerequisite, analyzeObservation, buildReviewQueue, cascadeBlock, clearADOCredentials, clearTursoCredentials, createAgentSkill, createFSRS, createGoal, createToken, deleteCardForUser, deleteSetting, deleteToken, deprecateToken, detectSystemLocale, discoverSkills, distributeGlobalSkills, endSession, ensureCard, ensureMonitorDir, evaluateRating, executeReviewAction, extractTasks, extractTokenRefs, fetchActiveWorkItems, findTokens, generateBashHooks, generateBashUnhooks, generateConceptFreeCue, generatePowerShellHooks, generatePowerShellUnhooks, generatePrompt, generateZshHooks, generateZshUnhooks, getADOCredentials, getAgentSkill, getAllSettings, getAllSettingsDetailed, getBlockedCards, getCard, getCardById, getCardDeletionImpact, getDefaultDbPath, getDependents, getDomainCompetence, getDueCards, getGoal, getGoalTree, getMonitorDir, getMonitorLogStats, getMonitorPath, getPackageSkillPath, getPrerequisites, getRepoPaths, getReviewsForCard, getReviewsForUser, getSessionSummary, getSetting, getSystemProfile, getTokenById, getTokenBySlug, getTokenDeleteImpact, getTursoCredentials, getUserStats, hasCommand, injectShellHooks, installFastFlowLM, installOllama, interleave, listAgentSkills, listGoals, listTokens, loadADOConfig, loadCredentials, logReview, logStep, matchesFilePath, monitorLogExists, normalizeLocale, normalizePath, openDatabase, openDatabaseWithSync, pairCommands, parseGoalFile, parseMonitorLog, readMonitorLog, resolveAllBeliefPaths, resolveAllGoalPaths, resolveReference, resolveRepoPath, resolveReviewContext, saveCredentials, serializeGoal, setADOCredentials, setSetting, setTursoCredentials, startSession, t, unblockReady, updateCard, updateGoalStatus, updateToken, writeMonitorEvent };