@vortex-os/base 0.4.0 → 0.6.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 };
 }
 
 /**
@@ -263,12 +303,20 @@ interface CommandArg {
  * - `rest` — the unparsed trailing portion of the input (everything after
  *   the command name), provided as-is for commands that prefer to handle
  *   their own parsing.
+ * - `argv` — pre-split argument tokens (everything after the command name),
+ *   present only when the caller already holds the shell-split argv (e.g. the
+ *   `vortex` CLI). A command that does its own quote-aware tokenization should
+ *   prefer this over re-parsing `rest`: it avoids the lossy
+ *   string-join-then-re-tokenize round-trip, so quotes/spaces/empty values in a
+ *   token can never shift the boundaries of later tokens. Absent for the
+ *   typed-slash path, where the command falls back to tokenizing `rest`.
  * - `context` — resolved repository paths from `@vortex-os/core.makeContext`.
  */
 interface CommandInput {
     readonly raw: string;
     readonly args: Readonly<Record<string, string>>;
     readonly rest: string;
+    readonly argv?: readonly string[];
     readonly context: ModuleContext;
 }
 /**
@@ -320,6 +368,18 @@ declare class CommandNotFoundError extends Error {
  * Returns whatever the command's handler returns (awaited if it is async).
  */
 declare function runSlash(input: string, { registry, context }: RunOptions): Promise<unknown>;
+/**
+ * Dispatch a command by name with pre-split argument tokens, skipping the
+ * whitespace split `runSlash` does on a raw string. Use this when the caller
+ * already holds clean tokens (e.g. the shell-split `vortex` CLI argv): the
+ * tokens reach the handler verbatim via `CommandInput.argv`, so quotes, spaces,
+ * or empty values inside a token can never shift the boundaries of later tokens
+ * (the lossy hazard of joining argv into a string and re-tokenizing it).
+ *
+ * `argv` is the tokens AFTER the command name. `rest`/`args` are still derived
+ * for handlers that read them, but a quote-aware command should prefer `argv`.
+ */
+declare function runSlashArgv(name: string, argv: readonly string[], { registry, context }: RunOptions): Promise<unknown>;
 
 //# sourceMappingURL=index.d.ts.map
 
@@ -332,8 +392,9 @@ type index_d$c_CommandRegistry = CommandRegistry;
 declare const index_d$c_CommandRegistry: typeof CommandRegistry;
 type index_d$c_RunOptions = RunOptions;
 declare const index_d$c_runSlash: typeof runSlash;
+declare const index_d$c_runSlashArgv: typeof runSlashArgv;
 declare namespace index_d$c {
-  export { type index_d$c_Command as Command, type index_d$c_CommandArg as CommandArg, type index_d$c_CommandInput as CommandInput, index_d$c_CommandNotFoundError as CommandNotFoundError, index_d$c_CommandRegistry as CommandRegistry, type index_d$c_RunOptions as RunOptions, index_d$c_runSlash as runSlash };
+  export { type index_d$c_Command as Command, type index_d$c_CommandArg as CommandArg, type index_d$c_CommandInput as CommandInput, index_d$c_CommandNotFoundError as CommandNotFoundError, index_d$c_CommandRegistry as CommandRegistry, type index_d$c_RunOptions as RunOptions, index_d$c_runSlash as runSlash, index_d$c_runSlashArgv as runSlashArgv };
 }
 
 /**
@@ -536,7 +597,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 +621,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 +649,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 +1073,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 +1123,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 +1156,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 +1365,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 +1394,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 +1516,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 +2538,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
@@ -2508,14 +2604,196 @@ interface CliIo {
  * `curate` is intentionally NOT wired here — it is agent-mediated.
  */
 declare function buildRegistry(): Promise<CommandRegistry>;
-/** Resolve the repo root the same way every entry point should: env override, else cwd. */
+/**
+ * Resolve the repo root every entry point should use. Precedence:
+ *   1. `VORTEX_REPO_ROOT` env — explicit override always wins.
+ *   2. cwd, if cwd is itself an initialized instance — running inside an instance
+ *      uses that instance (so multiple instances on one machine still work).
+ *   3. the global pointer (`~/.claude/vortex-global.json`), set by
+ *      `vortex global-setup` — so commands run from any other folder record to
+ *      the one central instance.
+ *   4. cwd — the original fallback.
+ * Until global-setup runs (no pointer), this is identical to the old behavior:
+ * env override, else cwd.
+ */
 declare function resolveRepoRoot(): string;
+/**
+ * Reassemble shell-split argv into the `/`-command string `runSlash` expects,
+ * for every command EXCEPT `/vortex`. Whitespace-containing values are wrapped by
+ * `requote` so they stay visible as a quoted span, and empty tokens are dropped.
+ * `runSlash` then splits this on whitespace only (it is NOT quote-aware), so this
+ * path preserves the long-standing behavior of those commands rather than
+ * guaranteeing perfect token reunification.
+ *
+ * `/vortex` deliberately bypasses this: the CLI threads its tokens straight to
+ * the handler (`runSlashArgv` in runVortexCli), which is what fixes the
+ * quoted/empty-value boundary bug — no lossy join-then-resplit round-trip.
+ */
+declare function argvToSlash(argv: readonly string[]): string;
 /**
  * Run the `vortex` CLI for the given argv (already sliced past `node script`).
  * Returns the process exit code (0 success, 1 on error) instead of calling
  * `process.exit`, so callers/tests stay in control.
  */
 declare function runVortexCli(argv: readonly string[], io?: CliIo): Promise<number>;
+/**
+ * Detect an interrupted git operation — a near-certain crashed-session signal:
+ * a merge / rebase / cherry-pick / revert / bisect left mid-flight, or a stray
+ * index lock. Uses `git rev-parse --git-path` so the marker resolves correctly
+ * even when `.git` is a FILE (a linked worktree or submodule), not a directory.
+ * Returns the FIRST matching marker name, or null when the tree is clean / not a
+ * git repo. Exported for tests. (Tier-1 carryover; decision-log 2026-06-04.)
+ */
+declare function detectInterruptedGitOp(repoRoot: string): string | null;
+/**
+ * Assemble the Tier-1 carryover signal for the session-start report. The
+ * interrupted-op check and the uncommitted count are computed INDEPENDENTLY: a
+ * held/stale `index.lock` can make `git status` fail, and that must NOT suppress
+ * the interrupted-op signal — the very case we most want to surface. Returns
+ * null when there is nothing to report (clean tree / not a git repo). Exported
+ * for tests. (decision-log 2026-06-04-session-recovery-two-tier.)
+ */
+declare function collectCarryover(repoRoot: string): {
+    uncommitted: number;
+    interrupted: string | null;
+} | null;
+
+/**
+ * Hook wiring for `/vortex init`: make sure the instance's
+ * `.claude/settings.json` registers the VortEX SessionStart / SessionEnd hooks,
+ * so the boot report + worklog-net fire automatically without the user knowing
+ * any command. NON-DESTRUCTIVE — like the MCP install merge, this preserves
+ * every other hook and top-level field and only adds our two entries if absent.
+ *
+ * Pure functions here (parse / merge / detect); the command does the actual
+ * file read/write around them. Keeping them pure makes the merge unit-testable
+ * and the "writes only what's missing" guarantee verifiable.
+ */
+declare const SESSION_START_COMMAND = "npx --no-install -p @vortex-os/base vortex session-start || exit 0";
+declare const SESSION_END_COMMAND = "npx --no-install -p @vortex-os/base vortex session-end || exit 0";
+interface HookCommand {
+    readonly type: "command";
+    readonly command: string;
+}
+interface HookGroup {
+    readonly hooks: readonly HookCommand[];
+    readonly matcher?: string;
+}
+interface ClaudeSettings {
+    hooks?: {
+        SessionStart?: HookGroup[];
+        SessionEnd?: HookGroup[];
+        [event: string]: HookGroup[] | undefined;
+    };
+    [key: string]: unknown;
+}
+interface EnsureHooksResult {
+    readonly settings: ClaudeSettings;
+    /**
+     * Hook events that CHANGED — a VortEX entry was added, or a legacy one was
+     * migrated/de-duplicated in place (empty when nothing changed). Callers should
+     * key "did we need to write?" off `alreadyWired`, not the name "added".
+     */
+    readonly added: readonly ("SessionStart" | "SessionEnd")[];
+    /** True when nothing changed — every VortEX hook was already present. */
+    readonly alreadyWired: boolean;
+}
+/**
+ * Parse existing settings.json text. Empty/whitespace → `{}` (fresh). Throws on
+ * malformed JSON so the caller aborts rather than clobbering a hand-edited file.
+ */
+declare function parseSettings(text: string | null | undefined): ClaudeSettings;
+/**
+ * Merge the VortEX hooks into an existing settings object WITHOUT mutating the
+ * input. A hook event is left untouched if it already references our command
+ * (idempotent); otherwise our group is appended alongside any existing groups.
+ */
+declare function ensureVortexHooks(existing: ClaudeSettings | null | undefined): EnsureHooksResult;
+/** Serialize settings the way Claude writes them (2-space, trailing newline). */
+declare function serializeSettings(settings: ClaudeSettings): string;
+
+/**
+ * Global usage setup — make a VortEX instance reachable from ANY folder, not
+ * just the instance directory. The lever is the user's GLOBAL Claude config
+ * (`~/.claude/`), which Claude Code reads in every project:
+ *
+ *   1. `~/.claude/settings.json`     — global SessionStart/SessionEnd hooks, so
+ *      the boot report + worklog-net fire in every folder. SAME command string
+ *      as the per-instance hook, so Claude Code's identical-hook dedup means the
+ *      instance folder never double-fires.
+ *   2. `~/.claude/vortex-global.json` — a small pointer file recording the
+ *      instance path (and a decline marker). `resolveRepoRoot()` reads
+ *      `instanceRoot` so commands run from any folder record to the one instance
+ *      WITHOUT needing an env var baked into the hook command (which would be
+ *      shell-dependent and would break hook dedup).
+ *   3. `~/.claude/CLAUDE.md`         — a small, marker-delimited pointer block
+ *      telling the agent where the instance is and to read its `AI-RULES.md` for
+ *      VortEX work. Regenerated in place; the user's other CLAUDE.md content is
+ *      preserved.
+ *
+ * Every write is merge-safe and idempotent. Pure helpers (block upsert, state
+ * read) are separated from the thin fs wrappers so the merge is unit-testable.
+ * All functions take an explicit `home` (default `os.homedir()`) so tests can
+ * point at a fake home without touching the real `~/.claude`.
+ */
+
+declare function globalSettingsPath(home?: string): string;
+/** The pointer/state file: `{ instanceRoot?, declinedAt? }`. */
+declare function globalStatePath(home?: string): string;
+declare function globalMemoryPath(home?: string): string;
+/**
+ * The instance root recorded by a prior `vortex global-setup`, or null. Read by
+ * `resolveRepoRoot()` so any-folder commands target the central instance.
+ */
+declare function readGlobalInstancePointer(home?: string): string | null;
+/**
+ * Does `dir` look like an initialized VortEX instance? Used by
+ * `resolveRepoRoot()` so that running INSIDE any instance uses that instance,
+ * and only falls back to the global pointer elsewhere.
+ */
+declare function isInstanceRoot(dir: string): boolean;
+/** True if the global settings.json already carries BOTH our session hooks. */
+declare function globalSettingsHasHook(home?: string): boolean;
+/**
+ * State of global usage on this machine. `done` = pointer set AND global hook
+ * wired (and, if `instanceRoot` given, the pointer matches it). `declined` = the
+ * user dismissed the offer. The session-start offer shows only when neither.
+ */
+declare function inspectGlobalSetup(home?: string, instanceRoot?: string): {
+    readonly done: boolean;
+    readonly declined: boolean;
+};
+/** The marker-delimited pointer block written into the global CLAUDE.md. */
+declare function renderGlobalBlock(instanceRoot: string): string;
+/**
+ * Insert or replace the VortEX block in an existing CLAUDE.md, preserving all
+ * other content. Idempotent: a second call with the same instanceRoot returns
+ * identical text.
+ */
+declare function upsertGlobalBlock(existing: string, instanceRoot: string): string;
+interface GlobalSetupWrite {
+    readonly created: readonly string[];
+    readonly modified: readonly string[];
+    readonly skipped: readonly string[];
+}
+/**
+ * Apply global usage setup for `instanceRoot`: merge global hooks, write the
+ * pointer, and upsert the CLAUDE.md block. Non-destructive and idempotent —
+ * re-running with the same instance is a no-op (everything reported `skipped`).
+ */
+declare function applyGlobalSetup(opts: {
+    readonly instanceRoot: string;
+    readonly home?: string;
+}): Promise<GlobalSetupWrite>;
+/**
+ * Record that the user declined the global-usage offer, so the session-start
+ * report stops offering it. Preserves any existing pointer. Returns the path
+ * written.
+ */
+declare function recordGlobalSetupDecline(opts?: {
+    readonly home?: string;
+    readonly now?: Date;
+}): Promise<string>;
 
 /** The two document actions the v1 value loop supports. */
 type CurateActionKind = "create-file" | "append-section";
@@ -2733,16 +3011,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,
@@ -2760,10 +3066,17 @@ declare function collectSessionStartReport(ctx: ModuleContext, opts?: {
  * hook supplies `commitDays` from git; the report supplies the present dates.
  */
 declare function detectWorklogGaps(commitDays: readonly string[], presentDates: readonly string[]): string[];
+/**
+ * Count changed paths in `git status --porcelain` output — one path per
+ * non-empty line. Pure: the hook runs git; this turns its stdout into the
+ * Tier-1 carryover count. (`--porcelain` emits exactly one line per changed
+ * path, including untracked, so a line count is the change count.)
+ */
+declare function countUncommitted(porcelain: string): number;
 /**
  * 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 +3086,57 @@ 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;
+    };
+    /**
+     * One-time offer: this machine has not enabled "VortEX from any folder" and
+     * the user hasn't declined. The agent asks once; on yes → `vortex
+     * global-setup`, on no → `vortex global-setup --decline` (so it stops asking).
+     */
+    readonly globalSetupOffer?: boolean;
+    /**
+     * Tier-1 session-resume signals (cheap, git-only; computed by the hook):
+     * work carried over from a prior session. `interrupted` names an in-progress
+     * git op (MERGE_HEAD / rebase / lock) — a near-certain crash signal, surfaced
+     * as ⚠️. `uncommitted` counts changed paths present at session start — common
+     * in normal WIP, so surfaced as a quiet informational line only. Both point at
+     * `/resume` (Tier 2). See decision-log 2026-06-04-session-recovery-two-tier.
+     */
+    readonly carryover?: {
+        readonly uncommitted: number;
+        readonly interrupted: string | null;
+    };
 }): string;
 
 /**
@@ -2806,7 +3170,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 +3195,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. */
@@ -2838,56 +3208,6 @@ interface CatchUpOptions {
 }
 declare function catchUpSessions(ctx: ModuleContext, opts?: CatchUpOptions): Promise<CatchUpResult>;
 
-/**
- * Hook wiring for `/vortex init`: make sure the instance's
- * `.claude/settings.json` registers the VortEX SessionStart / SessionEnd hooks,
- * so the boot report + worklog-net fire automatically without the user knowing
- * any command. NON-DESTRUCTIVE — like the MCP install merge, this preserves
- * every other hook and top-level field and only adds our two entries if absent.
- *
- * Pure functions here (parse / merge / detect); the command does the actual
- * file read/write around them. Keeping them pure makes the merge unit-testable
- * and the "writes only what's missing" guarantee verifiable.
- */
-declare const SESSION_START_COMMAND = "npx --no-install -p @vortex-os/base vortex session-start";
-declare const SESSION_END_COMMAND = "npx --no-install -p @vortex-os/base vortex session-end";
-interface HookCommand {
-    readonly type: "command";
-    readonly command: string;
-}
-interface HookGroup {
-    readonly hooks: readonly HookCommand[];
-    readonly matcher?: string;
-}
-interface ClaudeSettings {
-    hooks?: {
-        SessionStart?: HookGroup[];
-        SessionEnd?: HookGroup[];
-        [event: string]: HookGroup[] | undefined;
-    };
-    [key: string]: unknown;
-}
-interface EnsureHooksResult {
-    readonly settings: ClaudeSettings;
-    /** Which hook events we added a VortEX entry to (empty if already wired). */
-    readonly added: readonly ("SessionStart" | "SessionEnd")[];
-    /** True when nothing changed — every VortEX hook was already present. */
-    readonly alreadyWired: boolean;
-}
-/**
- * Parse existing settings.json text. Empty/whitespace → `{}` (fresh). Throws on
- * malformed JSON so the caller aborts rather than clobbering a hand-edited file.
- */
-declare function parseSettings(text: string | null | undefined): ClaudeSettings;
-/**
- * Merge the VortEX hooks into an existing settings object WITHOUT mutating the
- * input. A hook event is left untouched if it already references our command
- * (idempotent); otherwise our group is appended alongside any existing groups.
- */
-declare function ensureVortexHooks(existing: ClaudeSettings | null | undefined): EnsureHooksResult;
-/** Serialize settings the way Claude writes them (2-space, trailing newline). */
-declare function serializeSettings(settings: ClaudeSettings): string;
-
 interface ReindexResult {
     readonly dir: string;
     readonly status: "written" | "unchanged" | "missing";
@@ -2970,8 +3290,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 +3321,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 +3358,157 @@ 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" | "adopt" | "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;
+        /** Files force-refreshed to the template via `--adopt` (prior bytes backed up). */
+        readonly adopted: 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;
+    adopt?: ReadonlySet<string>;
+}): Promise<VortexUpdateResult>;
+
 /**
  * `/vortex <sub>` — Root command for VortEX instance operations.
  *
@@ -3140,6 +3612,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,8 +3669,87 @@ interface VortexSyncResult {
     readonly failedAt?: VortexSyncStepId;
     readonly nextActions: readonly string[];
 }
-type VortexResult = VortexInitResult | VortexStatusResult | VortexImportResult | VortexDoctorResult | VortexSyncResult | VortexPlannedResult | VortexHelpResult;
+interface VortexGlobalSetupResult {
+    readonly subcommand: "global-setup";
+    readonly status: "completed" | "declined" | "error";
+    readonly created: readonly string[];
+    readonly modified: readonly string[];
+    readonly skipped: readonly string[];
+    readonly nextActions: readonly string[];
+}
+type VortexResult = VortexInitResult | VortexStatusResult | VortexImportResult | VortexDoctorResult | VortexSyncResult | VortexUpdateResult | VortexGlobalSetupResult | VortexPlannedResult | VortexHelpResult;
 declare const vortexCommand: Command<VortexResult>;
+/**
+ * Parse `--adopt <path>` (repeatable) tokens into the POSIX, repoRoot-relative
+ * dest paths the ownership manifest uses, so a Windows-style argument
+ * (`.claude\commands\recall.md` or a leading `./`) still matches a slot. The
+ * value is the dest path shown in the update report. Exported for tests.
+ */
+declare function parseAdoptArgs(tokens: readonly string[]): Set<string>;
+
+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
 
@@ -3221,8 +3775,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 +3789,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,40 +3800,71 @@ 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_applyGlobalSetup: typeof applyGlobalSetup;
+declare const index_d_argvToSlash: typeof argvToSlash;
+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_collectCarryover: typeof collectCarryover;
 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_countUncommitted: typeof countUncommitted;
 declare const index_d_createAmbientRecaller: typeof createAmbientRecaller;
 declare const index_d_createRitualRegistry: typeof createRitualRegistry;
 declare const index_d_curateCommand: typeof curateCommand;
 declare const index_d_decisionCommand: typeof decisionCommand;
+declare const index_d_detectInterruptedGitOp: typeof detectInterruptedGitOp;
 declare const index_d_detectWorklogGaps: typeof detectWorklogGaps;
 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_globalMemoryPath: typeof globalMemoryPath;
+declare const index_d_globalSettingsHasHook: typeof globalSettingsHasHook;
+declare const index_d_globalSettingsPath: typeof globalSettingsPath;
+declare const index_d_globalStatePath: typeof globalStatePath;
+declare const index_d_inspectGlobalSetup: typeof inspectGlobalSetup;
+declare const index_d_inspectOwnership: typeof inspectOwnership;
+declare const index_d_isInstanceRoot: typeof isInstanceRoot;
+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_parseAdoptArgs: typeof parseAdoptArgs;
 declare const index_d_parseSettings: typeof parseSettings;
+declare const index_d_queryNpmLatest: typeof queryNpmLatest;
+declare const index_d_readGlobalInstancePointer: typeof readGlobalInstancePointer;
+declare const index_d_readInstalledBaseVersion: typeof readInstalledBaseVersion;
 declare const index_d_recallCommand: typeof recallCommand;
+declare const index_d_recordGlobalSetupDecline: typeof recordGlobalSetupDecline;
 declare const index_d_reindexCommand: typeof reindexCommand;
 declare const index_d_renderAgenda: typeof renderAgenda;
+declare const index_d_renderGlobalBlock: typeof renderGlobalBlock;
 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_upsertGlobalBlock: typeof upsertGlobalBlock;
 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_applyGlobalSetup as applyGlobalSetup, index_d_argvToSlash as argvToSlash, 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_collectCarryover as collectCarryover, index_d_collectSessionStartReport as collectSessionStartReport, index_d_compareSemver as compareSemver, index_d_computeCurateFingerprint as computeCurateFingerprint, index_d_countUncommitted as countUncommitted, index_d_createAmbientRecaller as createAmbientRecaller, index_d_createRitualRegistry as createRitualRegistry, index_d_curateCommand as curateCommand, index_d_decisionCommand as decisionCommand, index_d_detectInterruptedGitOp as detectInterruptedGitOp, 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_globalMemoryPath as globalMemoryPath, index_d_globalSettingsHasHook as globalSettingsHasHook, index_d_globalSettingsPath as globalSettingsPath, index_d_globalStatePath as globalStatePath, index_d_inspectGlobalSetup as inspectGlobalSetup, index_d_inspectOwnership as inspectOwnership, index_d_isInstanceRoot as isInstanceRoot, index_d_isNewer as isNewer, index_d_isStableUpdate as isStableUpdate, index_d_logCommand as logCommand, index_d_ownershipManifestPath as ownershipManifestPath, index_d_parseAdoptArgs as parseAdoptArgs, index_d_parseSettings as parseSettings, index_d_queryNpmLatest as queryNpmLatest, index_d_readGlobalInstancePointer as readGlobalInstancePointer, index_d_readInstalledBaseVersion as readInstalledBaseVersion, index_d_recallCommand as recallCommand, index_d_recordGlobalSetupDecline as recordGlobalSetupDecline, index_d_reindexCommand as reindexCommand, index_d_renderAgenda as renderAgenda, index_d_renderGlobalBlock as renderGlobalBlock, 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_upsertGlobalBlock as upsertGlobalBlock, 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 };