@vortex-os/base 0.2.3 → 0.4.0

package/README.md

@@ -18,7 +18,40 @@ Base entry point for **VortEX** — a Multi-Agent Personal AI Work OS framework.
 npm install @vortex-os/base
 ```
 
-## Usage
+## Quick start — one install, then `init`
+
+`@vortex-os/base` ships a `vortex` CLI, so a working instance is three steps:
+
+```bash
+npm install @vortex-os/base     # install the framework into a new folder
+npx vortex init                 # scaffold the instance (asks for name / role / task)
+# then open your agent (e.g. `claude`) in that folder
+```
+
+`npx vortex init` is non-destructive and creates, in the current folder:
+
+- the five per-agent router files — `AGENT.md`, `CLAUDE.md`, `CODEX.md`, `GEMINI.md`, `.cursorrules` — so any agent host finds VortEX's behavior contract (these are generic templates you personalize over time);
+- the `data/` skeleton (`_memory/`, `worklog/`, `decision-log/`, `runbooks/`, `hubs/`, `inbox/`), your user-profile memory, and today's first worklog;
+- `.claude/settings.json` with the session hooks wired as `npx --no-install -p @vortex-os/base vortex session-start` / `… session-end` (the `--no-install` flag and explicit `-p` package make the auto-firing hook fail closed rather than install or shadow), plus the agent-mediated slash-commands in `.claude/commands/`;
+- `.agent/vortex.json` (auto-record config) and a minimal `package.json` with `"type":"module"` if none exists.
+
+Pass the answers inline to skip the prompts:
+
+```bash
+npx vortex init --name "Alex" --role "engineer" --task "set up my work notes"
+```
+
+Other CLI entry points (all run base-only — `/recall` lights up only when the optional add-on is installed):
+
+```bash
+npx vortex --list           # list available commands
+npx vortex status           # instance state report
+npx vortex session-start    # start-of-session boot report (git pull + counts + catch-up)
+npx vortex session-end      # worklog safety net
+npx vortex doctor           # health diagnosis
+```
+
+## Library usage
 
 ```ts
 import {
@@ -95,6 +128,11 @@ Future capability clusters publish as siblings under the `@vortex-os` scope and
 
 Each add-on installs alongside the base and extends what the agent can do without forcing a base upgrade.
 
+## Privacy & network behavior
+
+- **`vortex init` folder scan.** To suggest content you might want to import, `init` does a read-only scan for common notes-folder names (e.g. an Obsidian vault, a `notes/` directory) under your home directory. It only reads directory listings to count Markdown files and surface a hint — it never copies, modifies, or transmits anything. Import happens only when you explicitly run `vortex import --from <path>`.
+- **No network calls in the base.** Base itself makes no outbound network requests. The optional `@vortex-os/memory-extended` add-on, when installed, may download an embedding model (read-only `GET` from `huggingface.co`, cacheable / offline-able via `HF_HUB_OFFLINE=1`) and feeds transcript excerpts to whatever LLM adapter you wire into its consolidation step. See that package's README for details.
+
 ## Packaging notes
 
 - **Bundled**: all 14 workspaces are bundled into the published artifact via `tsup`. Consumers do not need to install workspace packages individually.

package/bin/vortex.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+// `vortex` — the CLI shipped by @vortex-os/base.
+//
+// `npm i @vortex-os/base` puts this on the instance's path (node_modules/.bin),
+// so `npx vortex init` / `npx vortex session-start` / `npx vortex --list` work
+// without any monorepo checkout. It is a thin wrapper over the canonical
+// dispatch (`runVortexCli`), which is bundled into base from
+// `@vortex-os/session-rituals` — exactly one source of truth for the CLI logic.
+//
+// The dispatch lazily probes the optional `@vortex-os/memory-extended` add-on:
+// when it is installed alongside base, `/recall` lights up; on a lean base-only
+// install the probe is caught and the CLI runs with every other command.
+
+import { sessionRituals } from "../dist/index.js";
+
+const code = await sessionRituals.runVortexCli(process.argv.slice(2));
+process.exitCode = code;

package/dist/catch-up-ZQN7HMMN.js

@@ -0,0 +1,7 @@
+import {
+  catchUpSessions
+} from "./chunk-6SO4DAWJ.js";
+export {
+  catchUpSessions
+};
+//# sourceMappingURL=catch-up-ZQN7HMMN.js.map

package/dist/catch-up-ZQN7HMMN.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/chunk-6SO4DAWJ.js

@@ -0,0 +1,32 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// ../plugins/session-rituals/dist/catch-up.js
+async function catchUpSessions(ctx, opts) {
+  const { sessionArchive } = await import("@vortex-os/memory-extended");
+  const dataDir = ctx.dataDir;
+  const cwd = opts?.cwd ?? ctx.repoRoot;
+  const adapters = opts?.adapters ?? [sessionArchive.claudeCodeAdapter];
+  const ingestResult = await sessionArchive.ingest({ adapters, dataDir, cwd, env: opts?.env });
+  const store = new sessionArchive.SessionArchiveStore(dataDir);
+  let indexedPulled = 0;
+  try {
+    indexedPulled = store.reindexFromNormalized().indexed;
+  } finally {
+    store.close();
+  }
+  return {
+    ingestedLocal: ingestResult.sessionsIngested,
+    indexedPulled,
+    errors: ingestResult.errors.length
+  };
+}
+
+export {
+  __export,
+  catchUpSessions
+};
+//# sourceMappingURL=chunk-6SO4DAWJ.js.map

package/dist/chunk-6SO4DAWJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../plugins/session-rituals/src/catch-up.ts"],"sourcesContent":["import type { ModuleContext } from \"@vortex-os/core\";\n// Type-only — erased at compile time, so importing it does NOT pull the\n// `@vortex-os/memory-extended` add-on (or its native sqlite/level deps) into\n// the module graph of consumers that only need the types. The runtime engine\n// is loaded lazily inside the function body via `await import(...)`.\nimport type { sessionArchive } from \"@vortex-os/memory-extended\";\n\n/**\n * Start-of-session \"catch-up\": fold conversation transcripts into the local\n * search archive without the user ever having to wrap up a session.\n *\n * Two sources, one pass:\n *  - **local (a)** — this machine's own transcripts that are not archived yet,\n *    read from the agent's transcript store and scoped to the current project.\n *  - **pulled (b)** — transcripts created on another machine that arrived as\n *    normalized text via git sync. Their text is present but this machine's\n *    DB (local, derived, gitignored) has never indexed them.\n *\n * Text only — vectorization is deferred to recall/rebuild so session start\n * stays fast. The whole step is gated by `autoRecord.archive` at the call site\n * and is best-effort: callers should treat a thrown archive backend (e.g. the\n * native sqlite module not built) as \"skip\", never as a fatal start error.\n */\nexport interface CatchUpResult {\n  /** Local transcripts newly archived this run (source a). */\n  readonly ingestedLocal: number;\n  /** Normalized transcripts from another machine newly indexed (source b). */\n  readonly indexedPulled: number;\n  /** Per-session ingest errors (source a). */\n  readonly errors: number;\n}\n\nexport interface CatchUpOptions {\n  /** Restrict local ingest to one project's transcripts. Default: `ctx.repoRoot`. */\n  readonly cwd?: string;\n  /**\n   * Transcript adapters for local ingest. Default: Claude Code only. Other\n   * hosts (Codex, Gemini) can be added by a caller; tests inject fakes so the\n   * scan never touches the real home directory.\n   */\n  readonly adapters?: sessionArchive.IngestParams[\"adapters\"];\n  /** Adapter environment override (e.g. a sandbox HOME). Tests use this. */\n  readonly env?: sessionArchive.IngestParams[\"env\"];\n}\n\nexport async function catchUpSessions(\n  ctx: ModuleContext,\n  opts?: CatchUpOptions,\n): Promise<CatchUpResult> {\n  // Lazy-load the optional add-on. Base ships without `memory-extended`; this\n  // import resolves only when the add-on is installed alongside it. The call\n  // site already gates this step on `autoRecord.archive` and treats a thrown\n  // backend as \"skip\", so a missing add-on surfaces as a normal load error\n  // the caller can catch.\n  const { sessionArchive } = await import(\"@vortex-os/memory-extended\");\n\n  const dataDir = ctx.dataDir;\n  const cwd = opts?.cwd ?? ctx.repoRoot;\n  const adapters = opts?.adapters ?? [sessionArchive.claudeCodeAdapter];\n\n  // (a) Ingest this machine's not-yet-archived transcripts for the current\n  // project. Writes the normalized copy into the archive (which git syncs) and\n  // a local DB row. Text only — no vectorization here.\n  const ingestResult = await sessionArchive.ingest({ adapters, dataDir, cwd, env: opts?.env });\n\n  // (b) Index normalized transcripts that arrived from another machine via git\n  // pull — their text is on disk but this machine's DB has no row yet.\n  const store = new sessionArchive.SessionArchiveStore(dataDir);\n  let indexedPulled = 0;\n  try {\n    indexedPulled = store.reindexFromNormalized().indexed;\n  } finally {\n    store.close();\n  }\n\n  return {\n    ingestedLocal: ingestResult.sessionsIngested,\n    indexedPulled,\n    errors: ingestResult.errors.length,\n  };\n}\n"],"mappings":";;;;;;;AA6CA,eAAsB,gBACpB,KACA,MAAqB;AAOrB,QAAM,EAAE,eAAc,IAAK,MAAM,OAAO,4BAA4B;AAEpE,QAAM,UAAU,IAAI;AACpB,QAAM,MAAM,MAAM,OAAO,IAAI;AAC7B,QAAM,WAAW,MAAM,YAAY,CAAC,eAAe,iBAAiB;AAKpE,QAAM,eAAe,MAAM,eAAe,OAAO,EAAE,UAAU,SAAS,KAAK,KAAK,MAAM,IAAG,CAAE;AAI3F,QAAM,QAAQ,IAAI,eAAe,oBAAoB,OAAO;AAC5D,MAAI,gBAAgB;AACpB,MAAI;AACF,oBAAgB,MAAM,sBAAqB,EAAG;EAChD;AACE,UAAM,MAAK;EACb;AAEA,SAAO;IACL,eAAe,aAAa;IAC5B;IACA,QAAQ,aAAa,OAAO;;AAEhC;","names":[]}

package/dist/index.d.ts

@@ -138,7 +138,9 @@ declare function vortexConfigPath(ctx: ModuleContext): string;
 /**
  * Load the instance config, merged over defaults. A missing, unreadable, or
  * invalid file yields defaults (everything on, no environments) rather than
- * throwing — config is opt-in tuning, never a prerequisite.
+ * throwing — config is opt-in tuning, never a prerequisite. Environment rules
+ * are validated individually; malformed ones are dropped so that a partly bad
+ * config still resolves rather than throwing in `resolveEnvironment`.
  */
 declare function loadVortexConfig(ctx: ModuleContext): VortexConfig;
 /**
@@ -153,6 +155,67 @@ declare function resolveEnvironment(config: VortexConfig, signals: {
     readonly pathExists?: (p: string) => boolean;
 }): string | null;
 
+/**
+ * Options for {@link validateDataRelativePath}. Shaped so a future
+ * symlink-aware mode can be added WITHOUT changing any caller: today every
+ * caller passes no options (or `{}`) and gets the lexical check. When the
+ * realpath mode lands it becomes `{ resolveSymlinks: true }` and callers that
+ * want it opt in; the default stays lexical-only.
+ *
+ * The symlink/realpath ancestor check is intentionally DEFERRED for v1 — the
+ * lexical containment check (resolve + `path.relative`) already blocks
+ * traversal, absolute, and drive-qualified paths. A symlink *inside* `data/`
+ * pointing outside it is the remaining gap; closing it needs an async
+ * `realpath` walk, which this synchronous API leaves room for.
+ */
+interface ValidateDataRelativePathOptions {
+    /**
+     * Reserved for the deferred realpath/symlink-ancestor mode. Currently
+     * ignored — accepted now so enabling it later is not a breaking change.
+     */
+    readonly resolveSymlinks?: boolean;
+}
+/**
+ * Validate an untrusted `data/`-relative path and return the vetted absolute
+ * path under `dataDir`, or throw a clear {@link Error}.
+ *
+ * Rejection rules (in order — the cheap lexical checks run before the
+ * resolve so a hostile input never even reaches `path.resolve`):
+ *
+ *  1. Not a non-empty string.
+ *  2. Contains a control character (U+0000–U+001F).
+ *  3. After normalizing `\` → `/`: empty, `.`, drive-qualified (`C:`),
+ *     absolute, or has a leading separator.
+ *  4. Any segment is empty (collapsed `//`), `.`, or `..` (traversal).
+ *  5. The final segment (the filename) is empty.
+ *  6. The first segment is a system/meta dir (worklog, decision-log,
+ *     runbooks, hubs, _memory, _templates, _proactive-curator) or starts
+ *     with `_` (any reserved/meta dir).
+ *
+ * Then it resolves against `dataDir` and confirms containment using
+ * `path.relative` (NOT a string prefix — `data` vs `data-evil` would fool a
+ * prefix check). On Windows the relative check is done case-insensitively.
+ *
+ * @param dataDir Absolute path of the instance's `data/` directory.
+ * @param rel     Untrusted `data/`-relative path (LLM- or agent-supplied).
+ * @returns The validated absolute path, guaranteed under `dataDir`.
+ */
+declare function validateDataRelativePath(dataDir: string, rel: string, _options?: ValidateDataRelativePathOptions): string;
+/**
+ * Create a file exclusively (refusing to overwrite). Writes `body` with the
+ * `wx` flag so an existing target throws `EEXIST`, which is re-thrown as a
+ * clear "refusing to overwrite" error. Use for the create-file action where
+ * clobbering an existing document would be silent data loss.
+ *
+ * The caller is responsible for ensuring the parent directory exists (the
+ * create-file path in the curator does its own `mkdir` after validation).
+ *
+ * @param absPath Absolute target path (already validated by
+ *                {@link validateDataRelativePath}).
+ * @param body    File contents (UTF-8).
+ */
+declare function exclusiveCreateFile(absPath: string, body: string): Promise<void>;
+
 //# sourceMappingURL=index.d.ts.map
 
 type index_d$d_AutoRecordConfig = AutoRecordConfig;
@@ -160,7 +223,9 @@ 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_ValidateDataRelativePathOptions = ValidateDataRelativePathOptions;
 type index_d$d_VortexConfig = VortexConfig;
+declare const index_d$d_exclusiveCreateFile: typeof exclusiveCreateFile;
 declare const index_d$d_isVisibleAt: typeof isVisibleAt;
 declare const index_d$d_loadVortexConfig: typeof loadVortexConfig;
 declare const index_d$d_makeContext: typeof makeContext;
@@ -170,9 +235,10 @@ declare const index_d$d_normalizePrivacy: typeof normalizePrivacy;
 declare const index_d$d_parseFrontmatter: typeof parseFrontmatter;
 declare const index_d$d_resolveEnvironment: typeof resolveEnvironment;
 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_VortexConfig as VortexConfig, 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_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_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 };
 }
 
 /**
@@ -1684,6 +1750,59 @@ type FingerprintInput = {
  */
 declare function computeFingerprint(input: FingerprintInput): string;
 
+/**
+ * Hardened, deterministic write helper for the curate value loop.
+ *
+ * This is the single gate every document write goes through — the
+ * insight-proposer's `onAccept` and the `vortex curate-accept` CLI subcommand
+ * both call {@link writeDocAction}. It does NOT decide *whether* to write
+ * (that is the user's accept) and it does NOT consult an LLM. It takes a
+ * concrete document action and either creates a new file (exclusive — refuses
+ * to overwrite) or appends a section to an EXISTING markdown file.
+ *
+ * Path safety is enforced first, for BOTH actions, via
+ * {@link validateDataRelativePath} from `@vortex-os/core`. A path that escapes
+ * `data/`, is absolute/drive-qualified, or targets a system/meta directory is
+ * rejected before any filesystem access — closing the path-traversal gap that
+ * was previously only guarded by the insight-proposer's system-meta string
+ * check.
+ *
+ * v1 scope (consensus): create-file + append-section only. No update-file
+ * (whole-file replace = data loss) and no create-folder distinct path
+ * (create-file's mkdir covers the new-folder case).
+ */
+/** A document write the user has accepted. Path is `data/`-relative. */
+type DocWriteAction = {
+    readonly kind: "create-file";
+    /** `data/`-relative path of the file to create (validated here). */
+    readonly targetRelPath: string;
+    readonly body: string;
+} | {
+    readonly kind: "append-section";
+    /** `data/`-relative path of an EXISTING file to append to (validated here). */
+    readonly targetRelPath: string;
+    readonly sectionHeader: string;
+    readonly body: string;
+};
+interface WriteDocResult {
+    /** Absolute path written. */
+    readonly writtenPath: string;
+    readonly kind: DocWriteAction["kind"];
+}
+/**
+ * Apply a document write action against `<cwd>/data`, with path validation and
+ * exclusive-create / append-to-existing semantics.
+ *
+ *  - `create-file`: validate the path, `mkdir -p` the parent, then write with
+ *    {@link exclusiveCreateFile} (throws "refusing to overwrite" if it exists).
+ *  - `append-section`: validate the path, REQUIRE the file to already exist
+ *    (append-section never creates), then append a `## <sectionHeader>` block.
+ *
+ * @throws if the path is unsafe, if create-file's target exists, or if
+ *         append-section's target does not exist.
+ */
+declare function writeDocAction(cwd: string, action: DocWriteAction): Promise<WriteDocResult>;
+
 type ProposalKind = "capture-insight" | "create-hub";
 interface DeclinedEntry {
     /** ISO-8601 timestamp of when the user declined. */
@@ -2209,6 +2328,7 @@ declare const index_d$1_CodexLLMJudge: typeof CodexLLMJudge;
 type index_d$1_CodexLLMJudgeError = CodexLLMJudgeError;
 declare const index_d$1_CodexLLMJudgeError: typeof CodexLLMJudgeError;
 type index_d$1_DeclinedEntry = DeclinedEntry;
+type index_d$1_DocWriteAction = DocWriteAction;
 type index_d$1_ExpectedShape = ExpectedShape;
 type index_d$1_FingerprintInput = FingerprintInput;
 type index_d$1_GeminiLLMJudge = GeminiLLMJudge;
@@ -2243,6 +2363,7 @@ type index_d$1_TopicTreeSnapshot = TopicTreeSnapshot;
 type index_d$1_TurnBuffer = TurnBuffer;
 declare const index_d$1_TurnBuffer: typeof TurnBuffer;
 type index_d$1_TurnRecord = TurnRecord;
+type index_d$1_WriteDocResult = WriteDocResult;
 declare const index_d$1_computeFingerprint: typeof computeFingerprint;
 declare const index_d$1_deriveQueryFromTurns: typeof deriveQueryFromTurns;
 declare const index_d$1_frameForJudge: typeof frameForJudge;
@@ -2251,8 +2372,9 @@ declare const index_d$1_parseJudgeResponse: typeof parseJudgeResponse;
 declare const index_d$1_recordAcceptance: typeof recordAcceptance;
 declare const index_d$1_recordDecline: typeof recordDecline;
 declare const index_d$1_resetDeclined: typeof resetDeclined;
+declare const index_d$1_writeDocAction: typeof writeDocAction;
 declare namespace index_d$1 {
-  export { type index_d$1_AcceptResult as AcceptResult, index_d$1_AmbientBackpressure as AmbientBackpressure, type index_d$1_AmbientRecallHit as AmbientRecallHit, type index_d$1_AmbientRecallResult as AmbientRecallResult, index_d$1_AmbientRecaller as AmbientRecaller, type index_d$1_AmbientRecallerOptions as AmbientRecallerOptions, index_d$1_ClaudeCodeLLMJudge as ClaudeCodeLLMJudge, index_d$1_ClaudeCodeLLMJudgeError as ClaudeCodeLLMJudgeError, type index_d$1_ClaudeCodeSubAgentInvoker as ClaudeCodeSubAgentInvoker, type index_d$1_ClaudeDesktopInvoker as ClaudeDesktopInvoker, index_d$1_ClaudeDesktopLLMJudge as ClaudeDesktopLLMJudge, index_d$1_ClaudeDesktopLLMJudgeError as ClaudeDesktopLLMJudgeError, type index_d$1_CodexCompletionInvoker as CodexCompletionInvoker, index_d$1_CodexLLMJudge as CodexLLMJudge, index_d$1_CodexLLMJudgeError as CodexLLMJudgeError, type index_d$1_DeclinedEntry as DeclinedEntry, type index_d$1_ExpectedShape as ExpectedShape, type index_d$1_FingerprintInput as FingerprintInput, index_d$1_GeminiLLMJudge as GeminiLLMJudge, index_d$1_GeminiLLMJudgeError as GeminiLLMJudgeError, type index_d$1_GeminiMcpInvoker as GeminiMcpInvoker, type index_d$1_HubInput as HubInput, type index_d$1_HubProposal as HubProposal, index_d$1_HubProposer as HubProposer, type index_d$1_HubProposerOptions as HubProposerOptions, type index_d$1_InjectedInvoker as InjectedInvoker, index_d$1_InjectedLLMJudge as InjectedLLMJudge, type index_d$1_InsightInput as InsightInput, type index_d$1_InsightProposal as InsightProposal, index_d$1_InsightProposer as InsightProposer, type index_d$1_InsightProposerOptions as InsightProposerOptions, type index_d$1_LLMJudge as LLMJudge, index_d$1_LLMJudgeError as LLMJudgeError, type index_d$1_Proposal as Proposal, type index_d$1_ProposalAction as ProposalAction, type index_d$1_ProposalKind as ProposalKind, type index_d$1_Proposer as Proposer, type index_d$1_ProposerContext as ProposerContext, type index_d$1_RecallFn as RecallFn, type index_d$1_RecallSuggestion as RecallSuggestion, type index_d$1_TopicTreeSnapshot as TopicTreeSnapshot, index_d$1_TurnBuffer as TurnBuffer, type index_d$1_TurnRecord as TurnRecord, index_d$1_computeFingerprint as computeFingerprint, index_d$1_deriveQueryFromTurns as deriveQueryFromTurns, index_d$1_frameForJudge as frameForJudge, index_d$1_loadDeclinedFingerprints as loadDeclinedFingerprints, index_d$1_parseJudgeResponse as parseJudgeResponse, index_d$1_recordAcceptance as recordAcceptance, index_d$1_recordDecline as recordDecline, index_d$1_resetDeclined as resetDeclined };
+  export { type index_d$1_AcceptResult as AcceptResult, index_d$1_AmbientBackpressure as AmbientBackpressure, type index_d$1_AmbientRecallHit as AmbientRecallHit, type index_d$1_AmbientRecallResult as AmbientRecallResult, index_d$1_AmbientRecaller as AmbientRecaller, type index_d$1_AmbientRecallerOptions as AmbientRecallerOptions, index_d$1_ClaudeCodeLLMJudge as ClaudeCodeLLMJudge, index_d$1_ClaudeCodeLLMJudgeError as ClaudeCodeLLMJudgeError, type index_d$1_ClaudeCodeSubAgentInvoker as ClaudeCodeSubAgentInvoker, type index_d$1_ClaudeDesktopInvoker as ClaudeDesktopInvoker, index_d$1_ClaudeDesktopLLMJudge as ClaudeDesktopLLMJudge, index_d$1_ClaudeDesktopLLMJudgeError as ClaudeDesktopLLMJudgeError, type index_d$1_CodexCompletionInvoker as CodexCompletionInvoker, index_d$1_CodexLLMJudge as CodexLLMJudge, index_d$1_CodexLLMJudgeError as CodexLLMJudgeError, type index_d$1_DeclinedEntry as DeclinedEntry, type index_d$1_DocWriteAction as DocWriteAction, type index_d$1_ExpectedShape as ExpectedShape, type index_d$1_FingerprintInput as FingerprintInput, index_d$1_GeminiLLMJudge as GeminiLLMJudge, index_d$1_GeminiLLMJudgeError as GeminiLLMJudgeError, type index_d$1_GeminiMcpInvoker as GeminiMcpInvoker, type index_d$1_HubInput as HubInput, type index_d$1_HubProposal as HubProposal, index_d$1_HubProposer as HubProposer, type index_d$1_HubProposerOptions as HubProposerOptions, type index_d$1_InjectedInvoker as InjectedInvoker, index_d$1_InjectedLLMJudge as InjectedLLMJudge, type index_d$1_InsightInput as InsightInput, type index_d$1_InsightProposal as InsightProposal, index_d$1_InsightProposer as InsightProposer, type index_d$1_InsightProposerOptions as InsightProposerOptions, type index_d$1_LLMJudge as LLMJudge, index_d$1_LLMJudgeError as LLMJudgeError, type index_d$1_Proposal as Proposal, type index_d$1_ProposalAction as ProposalAction, type index_d$1_ProposalKind as ProposalKind, type index_d$1_Proposer as Proposer, type index_d$1_ProposerContext as ProposerContext, type index_d$1_RecallFn as RecallFn, type index_d$1_RecallSuggestion as RecallSuggestion, type index_d$1_TopicTreeSnapshot as TopicTreeSnapshot, index_d$1_TurnBuffer as TurnBuffer, type index_d$1_TurnRecord as TurnRecord, type index_d$1_WriteDocResult as WriteDocResult, index_d$1_computeFingerprint as computeFingerprint, index_d$1_deriveQueryFromTurns as deriveQueryFromTurns, index_d$1_frameForJudge as frameForJudge, index_d$1_loadDeclinedFingerprints as loadDeclinedFingerprints, index_d$1_parseJudgeResponse as parseJudgeResponse, index_d$1_recordAcceptance as recordAcceptance, index_d$1_recordDecline as recordDecline, index_d$1_resetDeclined as resetDeclined, index_d$1_writeDocAction as writeDocAction };
 }
 
 /**
@@ -2369,6 +2491,172 @@ interface RitualRegistryOptions {
  */
 declare function createRitualRegistry(options?: RitualRegistryOptions): CommandRegistry;
 
+interface CliIo {
+    /** Write a chunk to stdout. Default: `process.stdout.write`. */
+    readonly stdout?: (s: string) => void;
+    /** Write a chunk to stderr. Default: `process.stderr.write`. */
+    readonly stderr?: (s: string) => void;
+}
+/**
+ * Build the ritual registry, lighting up `/recall` ONLY when the optional
+ * `@vortex-os/memory-extended` add-on is installed alongside base.
+ *
+ * Base ships without the add-on (it is `external` in the tsup bundle), so this
+ * probe is a real `await import` that throws `ERR_MODULE_NOT_FOUND` on a lean
+ * install — caught here so the CLI runs with base alone and never throws on
+ * startup. When the add-on IS present, its local embedder wires up `/recall`.
+ * `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. */
+declare function resolveRepoRoot(): 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>;
+
+/** The two document actions the v1 value loop supports. */
+type CurateActionKind = "create-file" | "append-section";
+/**
+ * Serializable accepted-proposal payload — the contract between the agent and
+ * the deterministic CLI. The agent builds it (after the user says yes); the
+ * accept/preview path validates and acts on it. Plain data only so it can
+ * round-trip through a CLI argument or a file.
+ *
+ *  - `create-file`: needs `filename` (the new file's basename); `targetRelPath`
+ *    is the `data/`-relative FOLDER it goes in. `sectionHeader` is unused.
+ *  - `append-section`: `targetRelPath` is the `data/`-relative path of the
+ *    EXISTING file; `sectionHeader` is the `## ` heading to add. `filename`
+ *    is unused.
+ *
+ * `fingerprint` is the COARSE decline key (see {@link computeCurateFingerprint})
+ * — the agent may omit it (the CLI recomputes), but if present it must match.
+ */
+interface CuratePayload {
+    readonly action: CurateActionKind;
+    /** Short topic slug (1-3 words). Part of the coarse fingerprint. */
+    readonly topic: string;
+    /**
+     * `data/`-relative path. For create-file this is the destination FOLDER; for
+     * append-section this is the existing FILE. Part of the coarse fingerprint.
+     */
+    readonly targetRelPath: string;
+    /** create-file only: basename of the file to create (e.g. `notes.md`). */
+    readonly filename?: string;
+    /** append-section only: section heading without the leading `## `. */
+    readonly sectionHeader?: string;
+    /** Document body to write (create-file) or section body (append-section). */
+    readonly body: string;
+    /** Optional coarse fingerprint; recomputed + checked if present. */
+    readonly fingerprint?: string;
+}
+interface CuratePayloadValidation {
+    readonly ok: boolean;
+    readonly errors: readonly string[];
+    /** The concrete `data/`-relative file path the action would touch. */
+    readonly effectiveRelPath?: string;
+    /** The recomputed coarse fingerprint. */
+    readonly fingerprint?: string;
+}
+/**
+ * Coarse decline fingerprint — `sha256(topic + "\n" + actionKind + "\n" +
+ * targetRelPath)`, truncated to 16 hex chars. INTENTIONALLY coarse: it does
+ * NOT include the body or the section header, so a re-proposal of the same
+ * topic+action+target is recognized as the same proposal even if the wording
+ * changed. Used identically by accept-record, decline, and the
+ * previously-declined check, so a decline actually suppresses re-proposals.
+ *
+ * `targetRelPath` is normalized to forward slashes so work/home machines agree.
+ */
+declare function computeCurateFingerprint(topic: string, actionKind: CurateActionKind, targetRelPath: string): string;
+/**
+ * Validate a payload at the CLI boundary (shape + light path sanity). Deeper
+ * path safety (traversal/absolute/drive) is enforced authoritatively by
+ * {@link writeDocAction} → `validateDataRelativePath` at write time; this layer
+ * gives the agent a clear, early, write-nothing report and computes the coarse
+ * fingerprint + effective file path.
+ */
+declare function validateCuratePayload(payload: CuratePayload): CuratePayloadValidation;
+interface CurateCandidate {
+    /** `data/`-relative path of an existing document. */
+    readonly relpath: string;
+    /** Frontmatter `topic`, case-folded (lowercased) for matching; or null. */
+    readonly topic: string | null;
+    /** Frontmatter `tags`, case-folded. */
+    readonly tags: readonly string[];
+}
+interface CurateCandidatesResult {
+    readonly subcommand: "curate-candidates";
+    readonly status: "ok";
+    readonly candidates: readonly CurateCandidate[];
+    /** True when the scan was capped by `maxEntries`. */
+    readonly truncated: boolean;
+    readonly nextActions: readonly string[];
+}
+interface CuratePreviewResult {
+    readonly subcommand: "curate-preview";
+    readonly status: "ok" | "invalid";
+    readonly action?: CurateActionKind;
+    readonly effectiveRelPath?: string;
+    readonly fingerprint?: string;
+    /** What would happen if accepted, in plain words. */
+    readonly wouldDo?: string;
+    /** True when this exact proposal was previously declined and not expired. */
+    readonly previouslyDeclined: boolean;
+    /** create-file: does the target already exist (accept would refuse)? */
+    readonly targetExists?: boolean;
+    readonly errors: readonly string[];
+    readonly nextActions: readonly string[];
+}
+interface CurateAcceptResult {
+    readonly subcommand: "curate-accept";
+    readonly status: "written" | "refused" | "invalid";
+    readonly action?: CurateActionKind;
+    readonly writtenPath?: string;
+    readonly fingerprint?: string;
+    readonly errors: readonly string[];
+    readonly nextActions: readonly string[];
+}
+interface CurateDeclineResult {
+    readonly subcommand: "curate-decline";
+    readonly status: "recorded" | "invalid";
+    readonly fingerprint?: string;
+    readonly errors: readonly string[];
+    readonly nextActions: readonly string[];
+}
+/**
+ * List existing user documents under `data/` the agent can choose to append
+ * to (vs creating a new file). Walks `data/`, skipping reserved system/meta
+ * directories and non-document files. Returns relpath + case-folded
+ * frontmatter topic + tags so the agent can match the current work's topic to
+ * an existing home without an LLM call.
+ */
+declare function runCurateCandidates(repoRoot: string, options?: {
+    readonly maxEntries?: number;
+}): Promise<CurateCandidatesResult>;
+/**
+ * Validate a payload and report what WOULD happen — writes nothing. Reports
+ * the previously-declined state (coarse fingerprint, un-expired) so the agent
+ * can suppress a re-proposal, and whether a create-file target already exists
+ * (accept would refuse to overwrite).
+ */
+declare function runCuratePreview(repoRoot: string, payload: CuratePayload, now?: Date): Promise<CuratePreviewResult>;
+/**
+ * Write an accepted proposal through the hardened shared gate, then record the
+ * acceptance in the decline-store audit trail. Requires a valid payload — the
+ * write path is never reachable without an explicit accepted-proposal payload.
+ */
+declare function runCurateAccept(repoRoot: string, payload: CuratePayload, now?: Date): Promise<CurateAcceptResult>;
+/**
+ * Record a decline against the COARSE fingerprint so the same topic+action+
+ * target is suppressed for the expiry window (30 days via decline-store). Body
+ * and sectionHeader are not part of the fingerprint, so a re-worded proposal
+ * of the same capture stays suppressed.
+ */
+declare function runCurateDecline(repoRoot: string, payload: CuratePayload, now?: Date): Promise<CurateDeclineResult>;
+
 /**
  * Bridge the `@vortex-os/memory-extended` recall engine into a
  * `@vortex-os/proactive-curator` {@link AmbientRecaller} — defined in the
@@ -2561,8 +2849,8 @@ declare function catchUpSessions(ctx: ModuleContext, opts?: CatchUpOptions): Pro
  * 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 = "node plugins/session-rituals/scripts/session-start-hook.mjs";
-declare const SESSION_END_COMMAND = "node plugins/session-rituals/scripts/session-end-hook.mjs";
+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;
@@ -2854,6 +3142,8 @@ interface VortexImportResult {
     readonly frontmatterPreserved: number;
     readonly systemDirsCreated: readonly string[];
     readonly skipped: number;
+    readonly collisions: number;
+    readonly collidedFiles: readonly string[];
     readonly links?: {
         readonly filesScanned: number;
         readonly total: number;
@@ -2914,9 +3204,18 @@ type index_d_AmbientRecallFactoryOptions = AmbientRecallFactoryOptions;
 type index_d_CatchUpOptions = CatchUpOptions;
 type index_d_CatchUpResult = CatchUpResult;
 type index_d_ClaudeSettings = ClaudeSettings;
+type index_d_CliIo = CliIo;
 type index_d_CollectAgendaOptions = CollectAgendaOptions;
+type index_d_CurateAcceptResult = CurateAcceptResult;
+type index_d_CurateActionKind = CurateActionKind;
 type index_d_CurateAnyProposal = CurateAnyProposal;
+type index_d_CurateCandidate = CurateCandidate;
+type index_d_CurateCandidatesResult = CurateCandidatesResult;
+type index_d_CurateDeclineResult = CurateDeclineResult;
 type index_d_CurateOptions = CurateOptions;
+type index_d_CuratePayload = CuratePayload;
+type index_d_CuratePayloadValidation = CuratePayloadValidation;
+type index_d_CuratePreviewResult = CuratePreviewResult;
 type index_d_CurateResult = CurateResult;
 type index_d_EnsureHooksResult = EnsureHooksResult;
 type index_d_EnsureWorklogResult = EnsureWorklogResult;
@@ -2942,9 +3241,11 @@ type index_d_VortexSyncStepId = VortexSyncStepId;
 type index_d_VortexSyncStepStatus = VortexSyncStepStatus;
 type index_d_WorklogAppendResult = WorklogAppendResult;
 declare const index_d_agendaCommand: typeof agendaCommand;
+declare const index_d_buildRegistry: typeof buildRegistry;
 declare const index_d_catchUpSessions: typeof catchUpSessions;
 declare const index_d_collectAgenda: typeof collectAgenda;
 declare const index_d_collectSessionStartReport: typeof collectSessionStartReport;
+declare const index_d_computeCurateFingerprint: typeof computeCurateFingerprint;
 declare const index_d_createAmbientRecaller: typeof createAmbientRecaller;
 declare const index_d_createRitualRegistry: typeof createRitualRegistry;
 declare const index_d_curateCommand: typeof curateCommand;
@@ -2960,11 +3261,18 @@ 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_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_runVortexCli: typeof runVortexCli;
 declare const index_d_serializeSettings: typeof serializeSettings;
 declare const index_d_sessionStartCommand: typeof sessionStartCommand;
+declare const index_d_validateCuratePayload: typeof validateCuratePayload;
 declare const index_d_vortexCommand: typeof vortexCommand;
 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_CollectAgendaOptions as CollectAgendaOptions, type index_d_CurateAnyProposal as CurateAnyProposal, type index_d_CurateOptions as CurateOptions, 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_catchUpSessions as catchUpSessions, index_d_collectAgenda as collectAgenda, index_d_collectSessionStartReport as collectSessionStartReport, 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_serializeSettings as serializeSettings, index_d_sessionStartCommand as sessionStartCommand, 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, 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 { 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 };