@vortex-os/base 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -88,7 +88,7 @@ declare function moduleDir(ctx: ModuleContext, moduleName: string): string;
  * Instance configuration for VortEX, read from `<agentDir>/vortex.json`.
  *
  * The config exists to give the user control over the **auto-maintained**
- * operational behaviors (see `AGENT.md` → "Default behaviors") without
+ * operational behaviors (see `AI-RULES.md` → "Default behaviors") without
  * touching code: toggle any auto-record off, and declare how this machine's
  * environment is detected. A fresh instance has no config file — everything
  * is on, no environment — so the framework works out of the box and the file
@@ -108,6 +108,29 @@ interface AutoRecordConfig {
      * rebuilt.
      */
     readonly archive: boolean;
+    /**
+     * Auto-vectorize: at session start (after catch-up), embed any
+     * newly-archived sessions and memories so semantic recall — including the
+     * ambient "did we discuss this?" path — stays current without a manual
+     * rebuild. **Gated on the recall index already existing** (`_indexes/
+     * memory.sqlite`): until the user has set recall up once (which downloads the
+     * embedding model), this is a silent no-op, so it never triggers a download
+     * on its own. On by default; off → vectors only update on an explicit
+     * `/recall` / rebuild.
+     */
+    readonly vectorize: boolean;
+    /**
+     * Auto-download the embedding model the FIRST time recall is set up. When
+     * `@vortex-os/memory-extended` is installed but the recall index does not
+     * exist yet, session start kicks off a **background** worker that downloads
+     * the model (~470 MB, once) and builds the index — so installing the add-on
+     * is itself the opt-in and search turns on without a manual `/recall`. The
+     * download never blocks session start (it runs detached). On by default; set
+     * `false` — or env `VORTEX_VECTORIZE_AUTO_DOWNLOAD=0` — to keep the first
+     * download manual (metered connections, CI). Independent of `vectorize`: if
+     * `vectorize` is off, nothing runs regardless.
+     */
+    readonly vectorizeAutoDownload: boolean;
 }
 /**
  * One environment label plus the signal that selects it. Rules are evaluated
@@ -129,8 +152,22 @@ interface EnvironmentRule {
         readonly equals?: string;
     };
 }
+/**
+ * Update-awareness behavior. `check` controls the once-per-session check for a
+ * newer published `@vortex-os/base`:
+ *  - `"session"` (default): check the npm registry once at session start and,
+ *    when a newer version exists, surface it (the agent then asks before any
+ *    install — nothing is installed automatically). Offline → silent skip.
+ *  - `"off"`: no automatic check, no network contact for updates.
+ * On either setting the local "templates not yet applied" notice (no network)
+ * and the on-demand `vortex check-updates` still work.
+ */
+interface UpdatesConfig {
+    readonly check: "session" | "off";
+}
 interface VortexConfig {
     readonly autoRecord: AutoRecordConfig;
+    readonly updates: UpdatesConfig;
     readonly environments: readonly EnvironmentRule[];
 }
 /** Path of the instance config file: `<agentDir>/vortex.json`. */
@@ -215,6 +252,7 @@ declare function validateDataRelativePath(dataDir: string, rel: string, _options
  * @param body    File contents (UTF-8).
  */
 declare function exclusiveCreateFile(absPath: string, body: string): Promise<void>;
+declare function atomicWriteFile(absPath: string, body: string): Promise<void>;
 
 //# sourceMappingURL=index.d.ts.map
 
@@ -223,8 +261,10 @@ type index_d$d_EnvironmentRule = EnvironmentRule;
 type index_d$d_FrontmatterDoc<T = Record<string, unknown>> = FrontmatterDoc<T>;
 type index_d$d_ModuleContext = ModuleContext;
 type index_d$d_Privacy = Privacy;
+type index_d$d_UpdatesConfig = UpdatesConfig;
 type index_d$d_ValidateDataRelativePathOptions = ValidateDataRelativePathOptions;
 type index_d$d_VortexConfig = VortexConfig;
+declare const index_d$d_atomicWriteFile: typeof atomicWriteFile;
 declare const index_d$d_exclusiveCreateFile: typeof exclusiveCreateFile;
 declare const index_d$d_isVisibleAt: typeof isVisibleAt;
 declare const index_d$d_loadVortexConfig: typeof loadVortexConfig;
@@ -238,7 +278,7 @@ declare const index_d$d_serializeFrontmatter: typeof serializeFrontmatter;
 declare const index_d$d_validateDataRelativePath: typeof validateDataRelativePath;
 declare const index_d$d_vortexConfigPath: typeof vortexConfigPath;
 declare namespace index_d$d {
-  export { type index_d$d_AutoRecordConfig as AutoRecordConfig, type index_d$d_EnvironmentRule as EnvironmentRule, type index_d$d_FrontmatterDoc as FrontmatterDoc, type index_d$d_ModuleContext as ModuleContext, type index_d$d_Privacy as Privacy, type index_d$d_ValidateDataRelativePathOptions as ValidateDataRelativePathOptions, type index_d$d_VortexConfig as VortexConfig, index_d$d_exclusiveCreateFile as exclusiveCreateFile, index_d$d_isVisibleAt as isVisibleAt, index_d$d_loadVortexConfig as loadVortexConfig, index_d$d_makeContext as makeContext, index_d$d_maxPrivacy as maxPrivacy, index_d$d_moduleDir as moduleDir, index_d$d_normalizePrivacy as normalizePrivacy, index_d$d_parseFrontmatter as parseFrontmatter, index_d$d_resolveEnvironment as resolveEnvironment, index_d$d_serializeFrontmatter as serializeFrontmatter, index_d$d_validateDataRelativePath as validateDataRelativePath, index_d$d_vortexConfigPath as vortexConfigPath };
+  export { type index_d$d_AutoRecordConfig as AutoRecordConfig, type index_d$d_EnvironmentRule as EnvironmentRule, type index_d$d_FrontmatterDoc as FrontmatterDoc, type index_d$d_ModuleContext as ModuleContext, type index_d$d_Privacy as Privacy, type index_d$d_UpdatesConfig as UpdatesConfig, type index_d$d_ValidateDataRelativePathOptions as ValidateDataRelativePathOptions, type index_d$d_VortexConfig as VortexConfig, index_d$d_atomicWriteFile as atomicWriteFile, index_d$d_exclusiveCreateFile as exclusiveCreateFile, index_d$d_isVisibleAt as isVisibleAt, index_d$d_loadVortexConfig as loadVortexConfig, index_d$d_makeContext as makeContext, index_d$d_maxPrivacy as maxPrivacy, index_d$d_moduleDir as moduleDir, index_d$d_normalizePrivacy as normalizePrivacy, index_d$d_parseFrontmatter as parseFrontmatter, index_d$d_resolveEnvironment as resolveEnvironment, index_d$d_serializeFrontmatter as serializeFrontmatter, index_d$d_validateDataRelativePath as validateDataRelativePath, index_d$d_vortexConfigPath as vortexConfigPath };
 }
 
 /**
@@ -536,7 +576,17 @@ declare function privacyValid(): LintRule;
 interface WikiLinkResolvesOptions {
     /** Directory under which valid link targets live. Searched recursively. */
     readonly searchRoot: string;
-    /** Target file extensions. Defaults to `[".md"]`. */
+    /**
+     * Target file extensions. Defaults to `[".md"]`.
+     *
+     * `.md` targets are keyed by basename (extension stripped) — `[[Foo]]`
+     * resolves `Foo.md`. Any non-`.md` extension listed here keeps its
+     * extension in the index, so `[[Foo.pdf]]` resolves `Foo.pdf` while a bare
+     * `[[Foo]]` never silently matches an attachment. Mirrors the resolution
+     * contract in `@vortex-os/link-rewriter` (`resolve.ts`). Pass attachment
+     * extensions here (e.g. `[".md", ".pdf", ".png"]`) so imported binaries are
+     * treated as valid link targets instead of false "unresolved" findings.
+     */
     readonly extensions?: readonly string[];
 }
 /**
@@ -550,6 +600,23 @@ interface WikiLinkResolvesOptions {
  */
 declare function wikiLinkResolves(options: WikiLinkResolvesOptions): LintRule;
 
+/**
+ * Rule for `data/_memory/*.md` entries: the memory `type` must be a TOP-LEVEL
+ * frontmatter field — the index generator and the recall layer read
+ * `frontmatter.type` — never nested under `metadata`, and never the generic
+ * `note` default (which silently misclassifies the memory in type-aware
+ * recall). Scoped to files under a `_memory/` directory; the generated indexes
+ * (`_INDEX.md`, `MEMORY.md`) and `_TEMPLATE*` skeletons are skipped, and files
+ * in any other directory pass untouched.
+ *
+ * It does NOT enforce a closed type vocabulary: instances may extend the set
+ * (e.g. `infra`, `work`), and the built-in `memory-system` accepts any string.
+ * The two things this guards are the observed drift modes — a `metadata.type`
+ * the code never reads, and the `type: note` leak from the harness-memory
+ * format — both of which `require-frontmatter`/`privacy-valid` let through.
+ */
+declare function memoryFrontmatter(): LintRule;
+
 //# sourceMappingURL=index.d.ts.map
 
 type index_d$a_LintFinding = LintFinding;
@@ -561,11 +628,12 @@ type index_d$a_RequireFrontmatterOptions = RequireFrontmatterOptions;
 type index_d$a_Severity = Severity;
 type index_d$a_WikiLinkResolvesOptions = WikiLinkResolvesOptions;
 declare const index_d$a_lintDirectory: typeof lintDirectory;
+declare const index_d$a_memoryFrontmatter: typeof memoryFrontmatter;
 declare const index_d$a_privacyValid: typeof privacyValid;
 declare const index_d$a_requireFrontmatter: typeof requireFrontmatter;
 declare const index_d$a_wikiLinkResolves: typeof wikiLinkResolves;
 declare namespace index_d$a {
-  export { type index_d$a_LintFinding as LintFinding, type index_d$a_LintInput as LintInput, type index_d$a_LintOptions as LintOptions, type index_d$a_LintReport as LintReport, type index_d$a_LintRule as LintRule, type index_d$a_RequireFrontmatterOptions as RequireFrontmatterOptions, type index_d$a_Severity as Severity, type index_d$a_WikiLinkResolvesOptions as WikiLinkResolvesOptions, index_d$a_lintDirectory as lintDirectory, index_d$a_privacyValid as privacyValid, index_d$a_requireFrontmatter as requireFrontmatter, index_d$a_wikiLinkResolves as wikiLinkResolves };
+  export { type index_d$a_LintFinding as LintFinding, type index_d$a_LintInput as LintInput, type index_d$a_LintOptions as LintOptions, type index_d$a_LintReport as LintReport, type index_d$a_LintRule as LintRule, type index_d$a_RequireFrontmatterOptions as RequireFrontmatterOptions, type index_d$a_Severity as Severity, type index_d$a_WikiLinkResolvesOptions as WikiLinkResolvesOptions, index_d$a_lintDirectory as lintDirectory, index_d$a_memoryFrontmatter as memoryFrontmatter, index_d$a_privacyValid as privacyValid, index_d$a_requireFrontmatter as requireFrontmatter, index_d$a_wikiLinkResolves as wikiLinkResolves };
 }
 
 type PitfallSeverity = "info" | "warning" | "error";
@@ -984,6 +1052,13 @@ interface IndexEntry {
     readonly type?: string;
     /** Frontmatter `updated` or `created` value, ISO `YYYY-MM-DD` when parseable. */
     readonly updated?: string;
+    /**
+     * Frontmatter `scope` value, if present. `always` marks a memory the agent
+     * should load every session (the always-on tier); absent means on-demand
+     * (load by relevance from the index). Surfaced as a column in `_INDEX.md`
+     * only when some entry sets it.
+     */
+    readonly scope?: string;
 }
 /**
  * Options controlling {@link scanDirectory}.
@@ -1027,7 +1102,7 @@ interface RenderIndexInput {
     privacy?: "public" | "internal" | "personal" | string;
     /** Extra frontmatter tags besides the default `[index]`. */
     extraTags?: readonly string[];
-    /** Optional "관련" links rendered after the entry list. */
+    /** Optional "Related" links rendered after the entry list. */
     related?: readonly string[];
 }
 
@@ -1060,14 +1135,14 @@ declare function scanDirectory(rootDir: string, opts?: ScanOptions): Promise<rea
  *
  *   > <description>
  *
- *   ## 항목 (<count>)
+ *   ## Items (<count>)
  *
- *   | 파일 | 설명 | 갱신 |
+ *   | File | Description | Updated |
  *   |---|---|---|
  *   | [[<name>]] | <description or title> | <updated> |
  *   ...
  *
- *   ## 관련  (only if `related` is non-empty)
+ *   ## Related  (only if `related` is non-empty)
  *
  *   - [[<related[0]>]]
  *   ...
@@ -1269,7 +1344,7 @@ declare function extractWikiLinks(body: string): readonly WikiLink[];
  *   bare wiki links like `[[Foo]]`, which Obsidian resolves by filename
  *   anywhere in the vault.
  * - `byRelPath` — forward-slash relative path (no `.md`) → absolute path.
- *   Used for path-aware wiki links like `[[Projects/Home/Foo]]` or
+ *   Used for path-aware wiki links like `[[some-topic/Foo]]` or
  *   `[[../Foo]]`, where the operator wrote a path on purpose to
  *   disambiguate.
  *
@@ -1298,7 +1373,7 @@ interface BuildIndexOptions {
      * lookup fails. Useful when the operator's wiki-link convention uses
      * different casing than the on-disk layout (a frequent situation when
      * content is migrated from one vault into another with renamed roots,
-     * e.g. `[[Projects/Home/foo]]` vs `data/projects/home/foo.md`).
+     * e.g. `[[Some-Topic/foo]]` vs `data/some-topic/foo.md`).
      *
      * Default: false. Bare-name lookup is unaffected — Obsidian historically
      * treats bare names case-sensitively, and we keep that.
@@ -1420,9 +1495,9 @@ declare function topBrokenTargets(broken: readonly BrokenLink[], limit?: number)
  *
  * Examples:
  *   { "API-Tokens": "secrets/api-tokens" }
- *     [[API-Tokens]]       → [[secrets/api-tokens]]
- *     [[API-Tokens|토큰]]  → [[secrets/api-tokens|토큰]]
- *     [[API-Tokens#A|토큰]] → [[secrets/api-tokens#A|토큰]]
+ *     [[API-Tokens]]          → [[secrets/api-tokens]]
+ *     [[API-Tokens|alias]]    → [[secrets/api-tokens|alias]]
+ *     [[API-Tokens#A|alias]]  → [[secrets/api-tokens#A|alias]]
  *
  * Use the exact name string the operator wrote — no normalization is
  * applied. If the same broken target appears with different spellings
@@ -2442,7 +2517,7 @@ declare function curateCommand(options: CurateOptions): Command<CurateResult>;
  *
  * Host integration:
  *  1. Supply an embedder. `vector.createLocalEmbedder()` is the bundled
- *     default (local MiniLM, model downloads on first use); pass an
+ *     default (local multilingual e5-small, model downloads on first use); pass an
  *     OpenAI/Voyage adapter to use an API instead.
  *  2. Pass it to `createRitualRegistry({ recall: { embed } })`. The command
  *     is registered only when an embedder is supplied — instances that have
@@ -2733,16 +2808,44 @@ interface GitPullResult {
     readonly conflict: boolean;
 }
 interface SessionStartHookReport {
+    /** ISO timestamp (kept for any internal use). */
     readonly time: string;
+    /** Human-readable LOCAL time for display, e.g. `2026-06-03 (Wed) 15:21 KST`. */
+    readonly localTime: string;
     readonly repoRoot: string;
     readonly dataDir: string;
     readonly counts: Readonly<Record<string, number>>;
     readonly missing: readonly string[];
     readonly recentWorklog: RecentWorklog | null;
+    /**
+     * Up to 3 short "next up" lines lifted from the MOST RECENT worklog's
+     * hand-off section (else its unchecked tasks), each capped — the
+     * "what you were about to do" pointer. Honest-empty when nothing is captured.
+     */
+    readonly nextUp: readonly string[];
     /** Worklog dates (`YYYY-MM-DD`) present within the gap window — for backfill detection. */
     readonly recentWorklogDates: readonly string[];
     /** Resolved environment label (e.g. home/work), or null when none is configured. */
     readonly environment: string | null;
+    /**
+     * The always-on tier: `_memory/` memories marked `scope: always`, **with
+     * their bodies**, so session start actually loads them (not just names them)
+     * — see AI-RULES.md → "data/ layout" → memory loading. Capped for size; the
+     * on-demand rest stays in `_INDEX.md`. Each body is trimmed (and truncated
+     * past a per-rule cap, flagged by `truncated`).
+     */
+    readonly alwaysOnRules: readonly {
+        readonly slug: string;
+        readonly body: string;
+        readonly truncated: boolean;
+    }[];
+    /** Always-on memories dropped because the count exceeded the cap (0 = none). */
+    readonly alwaysOnOverflow: number;
+    /**
+     * The on-demand index looks stale — suggest `reindex`. True when memories
+     * exist but `_INDEX.md` is missing, or a `_memory/*.md` is newer than it.
+     */
+    readonly memoryIndexStale: boolean;
 }
 /**
  * Gather the read-only facts for a start-of-session report: data-dir counts,
@@ -2763,7 +2866,7 @@ declare function detectWorklogGaps(commitDays: readonly string[], presentDates:
 /**
  * Render a session-start report as a compact markdown block for a host hook
  * to inject as session context. A pull conflict and any worklog gaps are
- * surfaced as warnings (the agent acts on the gaps — see AGENT.md).
+ * surfaced as warnings (the agent acts on the gaps — see AI-RULES.md).
  */
 declare function renderSessionStartReport(report: SessionStartHookReport, extras?: {
     readonly git?: GitPullResult | null;
@@ -2773,6 +2876,39 @@ declare function renderSessionStartReport(report: SessionStartHookReport, extras
         readonly indexedPulled: number;
         readonly errors: number;
     };
+    readonly vectorized?: {
+        readonly memories: number;
+        readonly sessionChunks: number;
+    };
+    /**
+     * A first-time recall setup (model download + index build) was just started
+     * in the background (the add-on is installed but the index didn't exist yet).
+     */
+    readonly vectorizeSetup?: boolean;
+    /**
+     * Update lifecycle "signal 1" (local, no network): framework templates that
+     * the installed package has but this instance hasn't applied yet. `pending`
+     * = files that would be cleanly refreshed; `conflicts` = files the user
+     * edited (an update would offer those as `<file>.new`).
+     */
+    readonly templateUpdate?: {
+        readonly pending: number;
+        readonly conflicts: number;
+        readonly toVersion?: string;
+    };
+    /**
+     * Update lifecycle "signal 2" (network): a newer `@vortex-os/base` is
+     * published than the one installed. Shown only when `newer` is true; the
+     * agent then asks before running `command` (nothing installs automatically).
+     */
+    readonly updateCheck?: {
+        readonly package: string;
+        readonly installed: string | null;
+        readonly latest: string | null;
+        readonly newer: boolean;
+        readonly command: string | null;
+        readonly registry: string;
+    };
 }): string;
 
 /**
@@ -2806,7 +2942,10 @@ declare function ensureWorklogEntry(ctx: ModuleContext, opts?: {
  *
  * Two sources, one pass:
  *  - **local (a)** — this machine's own transcripts that are not archived yet,
- *    read from the agent's transcript store and scoped to the current project.
+ *    read from every detected agent host's transcript store (Claude Code,
+ *    Codex, Gemini) and scoped to the current project. Because all hosts are
+ *    swept on every start, a single Claude Code session-start also folds in the
+ *    Codex/Gemini sessions you ran in the same project, into one archive.
  *  - **pulled (b)** — transcripts created on another machine that arrived as
  *    normalized text via git sync. Their text is present but this machine's
  *    DB (local, derived, gitignored) has never indexed them.
@@ -2828,9 +2967,12 @@ interface CatchUpOptions {
     /** Restrict local ingest to one project's transcripts. Default: `ctx.repoRoot`. */
     readonly cwd?: string;
     /**
-     * Transcript adapters for local ingest. Default: Claude Code only. Other
-     * hosts (Codex, Gemini) can be added by a caller; tests inject fakes so the
-     * scan never touches the real home directory.
+     * Transcript adapters for local ingest. Default: all CLI hosts — Claude Code,
+     * Codex, and Gemini. Each adapter's `detect()` returns false when its host is
+     * absent, so registering all three is ~free on a machine that only uses one.
+     * (Claude Desktop is opt-in — it needs the `classic-level` dependency — so it
+     * is not in the default set; a caller can add it.) Tests inject fakes (or a
+     * sandbox `env.home`) so the scan never touches the real home directory.
      */
     readonly adapters?: sessionArchive.IngestParams["adapters"];
     /** Adapter environment override (e.g. a sandbox HOME). Tests use this. */
@@ -2970,8 +3112,8 @@ interface AgendaReport {
     } | null;
     /**
      * "Next up" lines lifted from the most recent worklog's hand-off section
-     * (`## 다음 작업` / `## Next` / a `📋`-marked heading) — the planned-work
-     * pointer, mirroring the vault TIL hand-off block. Empty if none.
+     * (`## Next` / a `📋`-marked heading) — the planned-work pointer, mirroring
+     * a worklog hand-off block. Empty if none.
      */
     readonly nextUp: readonly string[];
     /** Date of the worklog the nextUp lines came from (or null). */
@@ -3001,11 +3143,12 @@ interface CollectAgendaOptions {
  */
 /**
  * Lift the "next up / hand-off" section from a worklog body — the planned-work
- * pointer the agent leaves at wind-down (mirrors the vault's TIL `## 📋 다음
- * 작업` block). Matches a heading whose text contains any of: "다음 작업",
- * "다음 세션", "next", "next up", "todo", "후속", "📋". Returns the section's
- * content lines (bullets de-marked, blanks dropped), capped. Empty if no such
- * section. Stops at the next heading of the same-or-higher level.
+ * pointer the agent leaves at wind-down (mirrors a worklog hand-off block).
+ * Matches a heading whose text contains any of the cue terms (English and
+ * Korean: "next", "next up", "todo", "다음 작업", "다음 세션", "후속", "📋").
+ * Returns the section's content lines (bullets de-marked, blanks dropped),
+ * capped. Empty if no such section. Stops at the next heading of the
+ * same-or-higher level.
  */
 declare function extractNextUp(body: string, max?: number): string[];
 /**
@@ -3037,6 +3180,154 @@ declare function renderAgenda(report: AgendaReport): string;
  */
 declare const agendaCommand: Command<AgendaReport>;
 
+/** Schema tag for the ownership manifest; bump on a breaking shape change. */
+declare const OWNERSHIP_SCHEMA = "vortex-ownership/1";
+/** A single framework-owned file the instance tracks for updates. */
+interface OwnershipEntry {
+    /** Stable id across path moves — currently the template-relative path. */
+    readonly templateId: string;
+    /** Instance destination, repoRoot-relative, forward-slashed (portable). */
+    readonly path: string;
+    /** sha256 of the shipped template when this entry was last reconciled. */
+    readonly sourceSha256: string;
+    /**
+     * When the on-disk file equals the current template, this holds that hash
+     * (the copy is pristine — safe to refresh, since identical content has
+     * nothing to lose, and the first time the user edits it the hash diverges
+     * and it becomes a conflict instead). `null` means the on-disk file diverges
+     * from the template — a foreign / user-owned file we never auto-replace.
+     */
+    readonly installedSha256: string | null;
+}
+interface OwnershipManifest {
+    readonly schema: string;
+    /** The `@vortex-os/base` version whose template index this reconciles to. */
+    readonly baseVersion: string;
+    /** ISO timestamp the manifest was written. */
+    readonly generatedAt: string;
+    readonly files: readonly OwnershipEntry[];
+}
+type UpdateFileActionKind = "replace" | "restore" | "install" | "conflict" | "locally-modified" | "unmanaged" | "removed-upstream" | "unchanged";
+interface UpdateFileAction {
+    readonly path: string;
+    readonly templateId: string;
+    readonly action: UpdateFileActionKind;
+    readonly detail?: string;
+    /** For `replace` (or a backed-up `.new`): where the prior bytes were saved. */
+    readonly backupPath?: string;
+    /** For `conflict`: the `<file>.new` carrying the new template content. */
+    readonly newFilePath?: string;
+    /** Set when applying this file threw — the file was NOT changed destructively. */
+    readonly error?: string;
+}
+interface VortexUpdateResult {
+    readonly subcommand: "update";
+    readonly status: "ok" | "updated" | "conflicts" | "dry-run" | "no-manifest" | "no-templates";
+    readonly mode: "templates-only";
+    readonly dryRun: boolean;
+    /** Instance's recorded base version before the update (manifest baseVersion). */
+    readonly fromVersion?: string;
+    /** Shipped template index's base version (what we reconcile to). */
+    readonly toVersion?: string;
+    readonly actions: readonly UpdateFileAction[];
+    readonly summary: {
+        readonly replaced: number;
+        readonly restored: number;
+        readonly installed: number;
+        readonly conflicts: number;
+        readonly unchanged: number;
+        readonly unmanaged: number;
+        readonly locallyModified: number;
+        readonly removedUpstream: number;
+        /** Files whose apply threw (left unchanged) — surfaces a partial run. */
+        readonly errors: number;
+    };
+    readonly nextActions: readonly string[];
+}
+/** Absolute path of the instance ownership manifest. */
+declare function ownershipManifestPath(ctx: ModuleContext): string;
+/**
+ * Map a template-relative path (as listed in the template index, e.g.
+ * `routers/AGENTS.md`) to the instance destination, repoRoot-relative. The
+ * SINGLE place that knows the init copy layout — `init` (manifest writer) and
+ * `update` both derive destinations here, so they can never drift apart.
+ *
+ * Returns `null` for paths that are not copied into an instance (the index file
+ * itself, or any unrecognized top-level dir) — those are not framework-owned
+ * instance files and are skipped.
+ */
+declare function templateDestRelPath(templateRelPath: string): string | null;
+/**
+ * Reconcile the shipped template index against what is currently on disk and
+ * produce an ownership manifest. For each framework-owned file:
+ *   - `sourceSha256` is the hash of the actual shipped template file (computed
+ *     fresh, not trusted from the index — robust to a stale index);
+ *   - `installedSha256` is `sourceSha256` when the on-disk copy matches the
+ *     template (pristine — whether `init` wrote it or the user already had the
+ *     identical stock content; either way there is nothing to lose), and `null`
+ *     when the slot is missing or holds a divergent foreign file.
+ *
+ * Used by `init` to write the manifest from day one. Pure read — never writes.
+ */
+declare function buildOwnershipManifest(ctx: ModuleContext, templatesDir: string): Promise<OwnershipManifest | null>;
+/**
+ * Build and atomically write the ownership manifest for this instance. Called
+ * by `vortex init` (best-effort — a failure never blocks init). Returns the
+ * written path and file count, or `null` when there is no template index to
+ * reconcile against (a dev tree without a built `templates/manifest.json`).
+ */
+declare function writeOwnershipManifest(ctx: ModuleContext, templatesDir: string | null): Promise<{
+    path: string;
+    fileCount: number;
+} | null>;
+/** Read-only health snapshot of the ownership manifest vs what's on disk. */
+interface OwnershipDiagnosis {
+    /** Whether an ownership manifest exists and parsed. */
+    readonly present: boolean;
+    /** The manifest file exists on disk but could not be parsed/validated. */
+    readonly malformed: boolean;
+    readonly total: number;
+    /** Tracked file on disk still equals the recorded copy (safe to refresh). */
+    readonly pristine: number;
+    /** Tracked file on disk diverges from the recorded copy (user edited it). */
+    readonly modified: number;
+    /** Tracked file is gone from disk (an update would restore it). */
+    readonly missing: number;
+    /** Slot recorded as foreign (installedSha256 === null) — never auto-managed. */
+    readonly unmanaged: number;
+}
+/**
+ * Inspect the ownership manifest against the current instance files — a pure
+ * read used by `vortex doctor` to report whether the instance's framework
+ * files are stock, user-edited, missing, or foreign. No template index needed
+ * (it compares disk to the recorded `installedSha256`, not to a new template).
+ */
+declare function inspectOwnership(ctx: ModuleContext): Promise<OwnershipDiagnosis>;
+/**
+ * Adopt / repair the ownership manifest for an instance that lacks one (e.g.
+ * created before the update lifecycle existed). Conservative by design: it does
+ * NOTHING when a manifest already exists — rewriting could downgrade a tracked-
+ * but-edited file to "foreign" and lose its update path — so a healthy instance
+ * is never disturbed. Only a missing/unreadable manifest is (re)built from the
+ * current on-disk state (diverged files recorded as foreign/null, never falsely
+ * claimed pristine). `vortex update --templates-only` is the way to refresh once
+ * a manifest exists.
+ */
+declare function repairOwnershipManifest(ctx: ModuleContext, templatesDir: string | null): Promise<{
+    status: "created" | "already-present" | "unreadable" | "no-templates";
+    path?: string;
+    fileCount?: number;
+}>;
+/**
+ * `vortex update --templates-only` — refresh framework-owned templates from the
+ * currently-installed package, hash-guarded so user edits are never lost. Two
+ * phases: PLAN (all reads — safe in dry-run) then APPLY (writes, skipped in
+ * dry-run), with the manifest written LAST and always reflecting real disk.
+ */
+declare function runTemplatesUpdate(ctx: ModuleContext, templatesDir: string | null, options?: {
+    dryRun?: boolean;
+}): Promise<VortexUpdateResult>;
+
 /**
  * `/vortex <sub>` — Root command for VortEX instance operations.
  *
@@ -3140,6 +3431,9 @@ interface VortexImportResult {
     };
     readonly frontmatterInjected: number;
     readonly frontmatterPreserved: number;
+    readonly attachmentsCopied: number;
+    readonly skippedSecrets: readonly string[];
+    readonly skippedLarge: readonly string[];
     readonly systemDirsCreated: readonly string[];
     readonly skipped: number;
     readonly collisions: number;
@@ -3194,9 +3488,73 @@ interface VortexSyncResult {
     readonly failedAt?: VortexSyncStepId;
     readonly nextActions: readonly string[];
 }
-type VortexResult = VortexInitResult | VortexStatusResult | VortexImportResult | VortexDoctorResult | VortexSyncResult | VortexPlannedResult | VortexHelpResult;
+type VortexResult = VortexInitResult | VortexStatusResult | VortexImportResult | VortexDoctorResult | VortexSyncResult | VortexUpdateResult | VortexPlannedResult | VortexHelpResult;
 declare const vortexCommand: Command<VortexResult>;
 
+interface UpdateCheckResult {
+    readonly package: string;
+    /** Installed base version (from the shipped template index), or null if unknown. */
+    readonly installed: string | null;
+    /** Latest published version, or null when the check was skipped/failed/offline. */
+    readonly latest: string | null;
+    /** True only when `latest` is a strictly-greater stable version than `installed`. */
+    readonly newer: boolean;
+    /** Exact command to apply the update — present only when `newer`. */
+    readonly command: string | null;
+    /** Disclosed: where the check looked (honest about the network contact). */
+    readonly registry: string;
+}
+/**
+ * Installed base version = the `baseVersion` recorded in the shipped template
+ * index (`templates/manifest.json`). This is signal 1's source of truth too,
+ * and it travels with the running binary, so it can't disagree with the version
+ * actually executing (local or global/npx). Unreadable/invalid → null.
+ */
+declare function readInstalledBaseVersion(templatesDir?: string | null): string | null;
+/**
+ * Query the registry for the latest published `@vortex-os/base` version via
+ * `npm view`. Bounded by `NPM_TIMEOUT_MS`; any failure (offline, no npm,
+ * timeout, non-JSON) returns null so the caller stays silent. Never throws.
+ */
+declare function queryNpmLatest(repoRoot: string): string | null;
+/**
+ * Compare two versions: -1 (a<b), 0 (a==b), 1 (a>b), or null if either is
+ * unparseable. Numeric core left-to-right; on an equal core a RELEASE outranks
+ * a PRERELEASE of the same core. We deliberately do NOT implement full SemVer
+ * §11 prerelease-vs-prerelease ordering — two prereleases of the same core
+ * compare EQUAL here. That is fine because the surfacing policy
+ * ({@link isStableUpdate}) only ever offers a STABLE `latest`, so a
+ * prerelease→prerelease "upgrade" is never surfaced regardless; the §11
+ * tag-ordering is the most bug-prone part, so omitting it removes risk.
+ */
+declare function compareSemver(a: string, b: string): -1 | 0 | 1 | null;
+/** True only when `latest` is a strictly-greater version than `installed`. Null-safe → false. */
+declare function isNewer(latest: string | null, installed: string | null): boolean;
+/**
+ * The SURFACING policy: only offer a STABLE newer release. A prerelease
+ * `latest` (e.g. `2.0.0-beta.1`) is never surfaced — VortEX never nudges users
+ * onto a beta — even when its core is higher. Upgrading FROM a prerelease TO a
+ * stable release of the same-or-higher core IS surfaced (because `latest` is
+ * then stable). Null/unparseable → false. This is what `checkBaseUpdate` uses
+ * to decide `newer`.
+ */
+declare function isStableUpdate(latest: string | null, installed: string | null): boolean;
+/**
+ * The exact, copy-pasteable command to apply the update, detected from the
+ * instance: package manager by lockfile, local vs global by whether base sits
+ * in this folder's node_modules. Always chained with `npx vortex update` so the
+ * new package's templates get applied right after the install. Pure (no
+ * network); the string is surfaced verbatim and the CLI never runs it.
+ */
+declare function buildInstallCommand(repoRoot: string): string;
+/**
+ * Run the once-per-session update check. The CALLER decides whether to call
+ * (session start gates on `updates.check`; `vortex check-updates` forces it).
+ * Never throws — returns a result with `latest: null` / `newer: false` when the
+ * registry can't be reached, so the caller simply shows nothing.
+ */
+declare function checkBaseUpdate(ctx: ModuleContext): UpdateCheckResult;
+
 //# sourceMappingURL=index.d.ts.map
 
 type index_d_AgendaReport = AgendaReport;
@@ -3221,8 +3579,12 @@ type index_d_EnsureHooksResult = EnsureHooksResult;
 type index_d_EnsureWorklogResult = EnsureWorklogResult;
 type index_d_GitPullResult = GitPullResult;
 type index_d_NewDecisionResult = NewDecisionResult;
+declare const index_d_OWNERSHIP_SCHEMA: typeof OWNERSHIP_SCHEMA;
 type index_d_OpenDecision = OpenDecision;
 type index_d_OpenTask = OpenTask;
+type index_d_OwnershipDiagnosis = OwnershipDiagnosis;
+type index_d_OwnershipEntry = OwnershipEntry;
+type index_d_OwnershipManifest = OwnershipManifest;
 type index_d_RecallOptions = RecallOptions;
 type index_d_RecentWorklog = RecentWorklog;
 type index_d_ReindexResult = ReindexResult;
@@ -3231,6 +3593,9 @@ declare const index_d_SESSION_END_COMMAND: typeof SESSION_END_COMMAND;
 declare const index_d_SESSION_START_COMMAND: typeof SESSION_START_COMMAND;
 type index_d_SessionStartHookReport = SessionStartHookReport;
 type index_d_SessionStartReport = SessionStartReport;
+type index_d_UpdateCheckResult = UpdateCheckResult;
+type index_d_UpdateFileAction = UpdateFileAction;
+type index_d_UpdateFileActionKind = UpdateFileActionKind;
 type index_d_VortexHelpResult = VortexHelpResult;
 type index_d_VortexInitResult = VortexInitResult;
 type index_d_VortexPlannedResult = VortexPlannedResult;
@@ -3239,12 +3604,17 @@ type index_d_VortexSyncResult = VortexSyncResult;
 type index_d_VortexSyncStep = VortexSyncStep;
 type index_d_VortexSyncStepId = VortexSyncStepId;
 type index_d_VortexSyncStepStatus = VortexSyncStepStatus;
+type index_d_VortexUpdateResult = VortexUpdateResult;
 type index_d_WorklogAppendResult = WorklogAppendResult;
 declare const index_d_agendaCommand: typeof agendaCommand;
+declare const index_d_buildInstallCommand: typeof buildInstallCommand;
+declare const index_d_buildOwnershipManifest: typeof buildOwnershipManifest;
 declare const index_d_buildRegistry: typeof buildRegistry;
 declare const index_d_catchUpSessions: typeof catchUpSessions;
+declare const index_d_checkBaseUpdate: typeof checkBaseUpdate;
 declare const index_d_collectAgenda: typeof collectAgenda;
 declare const index_d_collectSessionStartReport: typeof collectSessionStartReport;
+declare const index_d_compareSemver: typeof compareSemver;
 declare const index_d_computeCurateFingerprint: typeof computeCurateFingerprint;
 declare const index_d_createAmbientRecaller: typeof createAmbientRecaller;
 declare const index_d_createRitualRegistry: typeof createRitualRegistry;
@@ -3255,24 +3625,34 @@ declare const index_d_ensureVortexHooks: typeof ensureVortexHooks;
 declare const index_d_ensureWorklogEntry: typeof ensureWorklogEntry;
 declare const index_d_extractNextUp: typeof extractNextUp;
 declare const index_d_extractOpenTasks: typeof extractOpenTasks;
+declare const index_d_inspectOwnership: typeof inspectOwnership;
+declare const index_d_isNewer: typeof isNewer;
+declare const index_d_isStableUpdate: typeof isStableUpdate;
 declare const index_d_logCommand: typeof logCommand;
+declare const index_d_ownershipManifestPath: typeof ownershipManifestPath;
 declare const index_d_parseSettings: typeof parseSettings;
+declare const index_d_queryNpmLatest: typeof queryNpmLatest;
+declare const index_d_readInstalledBaseVersion: typeof readInstalledBaseVersion;
 declare const index_d_recallCommand: typeof recallCommand;
 declare const index_d_reindexCommand: typeof reindexCommand;
 declare const index_d_renderAgenda: typeof renderAgenda;
 declare const index_d_renderSessionStartReport: typeof renderSessionStartReport;
+declare const index_d_repairOwnershipManifest: typeof repairOwnershipManifest;
 declare const index_d_resolveRepoRoot: typeof resolveRepoRoot;
 declare const index_d_runCurateAccept: typeof runCurateAccept;
 declare const index_d_runCurateCandidates: typeof runCurateCandidates;
 declare const index_d_runCurateDecline: typeof runCurateDecline;
 declare const index_d_runCuratePreview: typeof runCuratePreview;
+declare const index_d_runTemplatesUpdate: typeof runTemplatesUpdate;
 declare const index_d_runVortexCli: typeof runVortexCli;
 declare const index_d_serializeSettings: typeof serializeSettings;
 declare const index_d_sessionStartCommand: typeof sessionStartCommand;
+declare const index_d_templateDestRelPath: typeof templateDestRelPath;
 declare const index_d_validateCuratePayload: typeof validateCuratePayload;
 declare const index_d_vortexCommand: typeof vortexCommand;
+declare const index_d_writeOwnershipManifest: typeof writeOwnershipManifest;
 declare namespace index_d {
-  export { type index_d_AgendaReport as AgendaReport, type index_d_AmbientRecallFactoryOptions as AmbientRecallFactoryOptions, type index_d_CatchUpOptions as CatchUpOptions, type index_d_CatchUpResult as CatchUpResult, type index_d_ClaudeSettings as ClaudeSettings, type index_d_CliIo as CliIo, type index_d_CollectAgendaOptions as CollectAgendaOptions, type index_d_CurateAcceptResult as CurateAcceptResult, type index_d_CurateActionKind as CurateActionKind, type index_d_CurateAnyProposal as CurateAnyProposal, type index_d_CurateCandidate as CurateCandidate, type index_d_CurateCandidatesResult as CurateCandidatesResult, type index_d_CurateDeclineResult as CurateDeclineResult, type index_d_CurateOptions as CurateOptions, type index_d_CuratePayload as CuratePayload, type index_d_CuratePayloadValidation as CuratePayloadValidation, type index_d_CuratePreviewResult as CuratePreviewResult, type index_d_CurateResult as CurateResult, type index_d_EnsureHooksResult as EnsureHooksResult, type index_d_EnsureWorklogResult as EnsureWorklogResult, type index_d_GitPullResult as GitPullResult, type index_d_NewDecisionResult as NewDecisionResult, type index_d_OpenDecision as OpenDecision, type index_d_OpenTask as OpenTask, type index_d_RecallOptions as RecallOptions, type index_d_RecentWorklog as RecentWorklog, type index_d_ReindexResult as ReindexResult, type index_d_RitualRegistryOptions as RitualRegistryOptions, index_d_SESSION_END_COMMAND as SESSION_END_COMMAND, index_d_SESSION_START_COMMAND as SESSION_START_COMMAND, type index_d_SessionStartHookReport as SessionStartHookReport, type index_d_SessionStartReport as SessionStartReport, type index_d_VortexHelpResult as VortexHelpResult, type index_d_VortexInitResult as VortexInitResult, type index_d_VortexPlannedResult as VortexPlannedResult, type index_d_VortexResult as VortexResult, type index_d_VortexSyncResult as VortexSyncResult, type index_d_VortexSyncStep as VortexSyncStep, type index_d_VortexSyncStepId as VortexSyncStepId, type index_d_VortexSyncStepStatus as VortexSyncStepStatus, type index_d_WorklogAppendResult as WorklogAppendResult, index_d_agendaCommand as agendaCommand, index_d_buildRegistry as buildRegistry, index_d_catchUpSessions as catchUpSessions, index_d_collectAgenda as collectAgenda, index_d_collectSessionStartReport as collectSessionStartReport, index_d_computeCurateFingerprint as computeCurateFingerprint, index_d_createAmbientRecaller as createAmbientRecaller, index_d_createRitualRegistry as createRitualRegistry, index_d_curateCommand as curateCommand, index_d_decisionCommand as decisionCommand, index_d_detectWorklogGaps as detectWorklogGaps, index_d_ensureVortexHooks as ensureVortexHooks, index_d_ensureWorklogEntry as ensureWorklogEntry, index_d_extractNextUp as extractNextUp, index_d_extractOpenTasks as extractOpenTasks, index_d_logCommand as logCommand, index_d_parseSettings as parseSettings, index_d_recallCommand as recallCommand, index_d_reindexCommand as reindexCommand, index_d_renderAgenda as renderAgenda, index_d_renderSessionStartReport as renderSessionStartReport, index_d_resolveRepoRoot as resolveRepoRoot, index_d_runCurateAccept as runCurateAccept, index_d_runCurateCandidates as runCurateCandidates, index_d_runCurateDecline as runCurateDecline, index_d_runCuratePreview as runCuratePreview, index_d_runVortexCli as runVortexCli, index_d_serializeSettings as serializeSettings, index_d_sessionStartCommand as sessionStartCommand, index_d_validateCuratePayload as validateCuratePayload, index_d_vortexCommand as vortexCommand };
+  export { type index_d_AgendaReport as AgendaReport, type index_d_AmbientRecallFactoryOptions as AmbientRecallFactoryOptions, type index_d_CatchUpOptions as CatchUpOptions, type index_d_CatchUpResult as CatchUpResult, type index_d_ClaudeSettings as ClaudeSettings, type index_d_CliIo as CliIo, type index_d_CollectAgendaOptions as CollectAgendaOptions, type index_d_CurateAcceptResult as CurateAcceptResult, type index_d_CurateActionKind as CurateActionKind, type index_d_CurateAnyProposal as CurateAnyProposal, type index_d_CurateCandidate as CurateCandidate, type index_d_CurateCandidatesResult as CurateCandidatesResult, type index_d_CurateDeclineResult as CurateDeclineResult, type index_d_CurateOptions as CurateOptions, type index_d_CuratePayload as CuratePayload, type index_d_CuratePayloadValidation as CuratePayloadValidation, type index_d_CuratePreviewResult as CuratePreviewResult, type index_d_CurateResult as CurateResult, type index_d_EnsureHooksResult as EnsureHooksResult, type index_d_EnsureWorklogResult as EnsureWorklogResult, type index_d_GitPullResult as GitPullResult, type index_d_NewDecisionResult as NewDecisionResult, index_d_OWNERSHIP_SCHEMA as OWNERSHIP_SCHEMA, type index_d_OpenDecision as OpenDecision, type index_d_OpenTask as OpenTask, type index_d_OwnershipDiagnosis as OwnershipDiagnosis, type index_d_OwnershipEntry as OwnershipEntry, type index_d_OwnershipManifest as OwnershipManifest, type index_d_RecallOptions as RecallOptions, type index_d_RecentWorklog as RecentWorklog, type index_d_ReindexResult as ReindexResult, type index_d_RitualRegistryOptions as RitualRegistryOptions, index_d_SESSION_END_COMMAND as SESSION_END_COMMAND, index_d_SESSION_START_COMMAND as SESSION_START_COMMAND, type index_d_SessionStartHookReport as SessionStartHookReport, type index_d_SessionStartReport as SessionStartReport, type index_d_UpdateCheckResult as UpdateCheckResult, type index_d_UpdateFileAction as UpdateFileAction, type index_d_UpdateFileActionKind as UpdateFileActionKind, type index_d_VortexHelpResult as VortexHelpResult, type index_d_VortexInitResult as VortexInitResult, type index_d_VortexPlannedResult as VortexPlannedResult, type index_d_VortexResult as VortexResult, type index_d_VortexSyncResult as VortexSyncResult, type index_d_VortexSyncStep as VortexSyncStep, type index_d_VortexSyncStepId as VortexSyncStepId, type index_d_VortexSyncStepStatus as VortexSyncStepStatus, type index_d_VortexUpdateResult as VortexUpdateResult, type index_d_WorklogAppendResult as WorklogAppendResult, index_d_agendaCommand as agendaCommand, index_d_buildInstallCommand as buildInstallCommand, index_d_buildOwnershipManifest as buildOwnershipManifest, index_d_buildRegistry as buildRegistry, index_d_catchUpSessions as catchUpSessions, index_d_checkBaseUpdate as checkBaseUpdate, index_d_collectAgenda as collectAgenda, index_d_collectSessionStartReport as collectSessionStartReport, index_d_compareSemver as compareSemver, index_d_computeCurateFingerprint as computeCurateFingerprint, index_d_createAmbientRecaller as createAmbientRecaller, index_d_createRitualRegistry as createRitualRegistry, index_d_curateCommand as curateCommand, index_d_decisionCommand as decisionCommand, index_d_detectWorklogGaps as detectWorklogGaps, index_d_ensureVortexHooks as ensureVortexHooks, index_d_ensureWorklogEntry as ensureWorklogEntry, index_d_extractNextUp as extractNextUp, index_d_extractOpenTasks as extractOpenTasks, index_d_inspectOwnership as inspectOwnership, index_d_isNewer as isNewer, index_d_isStableUpdate as isStableUpdate, index_d_logCommand as logCommand, index_d_ownershipManifestPath as ownershipManifestPath, index_d_parseSettings as parseSettings, index_d_queryNpmLatest as queryNpmLatest, index_d_readInstalledBaseVersion as readInstalledBaseVersion, index_d_recallCommand as recallCommand, index_d_reindexCommand as reindexCommand, index_d_renderAgenda as renderAgenda, index_d_renderSessionStartReport as renderSessionStartReport, index_d_repairOwnershipManifest as repairOwnershipManifest, index_d_resolveRepoRoot as resolveRepoRoot, index_d_runCurateAccept as runCurateAccept, index_d_runCurateCandidates as runCurateCandidates, index_d_runCurateDecline as runCurateDecline, index_d_runCuratePreview as runCuratePreview, index_d_runTemplatesUpdate as runTemplatesUpdate, index_d_runVortexCli as runVortexCli, index_d_serializeSettings as serializeSettings, index_d_sessionStartCommand as sessionStartCommand, index_d_templateDestRelPath as templateDestRelPath, index_d_validateCuratePayload as validateCuratePayload, index_d_vortexCommand as vortexCommand, index_d_writeOwnershipManifest as writeOwnershipManifest };
 }
 
 export { index_d$9 as aiCodingPitfalls, index_d$d as core, index_d$a as dataLint, index_d$5 as decisionLog, index_d$4 as indexGenerator, index_d$2 as linkRewriter, index_d$b as memorySystem, index_d$1 as proactiveCurator, index_d$7 as reportGenerator, index_d$3 as runbooks, index_d as sessionRituals, index_d$c as slashCommands, index_d$8 as toolRules, index_d$6 as worklog };