@vortex-os/base 0.1.0 → 0.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 dydan77
+Copyright (c) 2026 vortex-os-project
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,77 +1,151 @@
-# @vortex-os/base
-
-Base entry point for **VortEX** — a Multi-Agent Personal AI Work OS framework.
-
-`@vortex-os/base` bundles the framework's 13 internal workspaces (core utilities, slash-command runtime, memory store, daily-log store, decision-log store, runbook store, link-rewriter, index-generator, data-linter, report-generator, two catalog modules, and the session-rituals plugin) into a single installable package. Install once, get the whole framework.
-
-## Install
-
-```bash
-npm install @vortex-os/base
-```
-
-## Usage
-
-```ts
-import {
-  core,
-  slashCommands,
-  memorySystem,
-  til,
-  decisionLog,
-  sessionRituals,
-} from "@vortex-os/base";
-
-// Use the slash-rituals registry against your own data directory
-const registry = sessionRituals.createRitualRegistry();
-const ctx = core.makeContext(process.cwd());
-
-await slashCommands.runSlash("/session-start", { registry, context: ctx });
-```
-
-## Exported namespaces
-
-Each internal workspace is exposed as a top-level namespace on the package:
-
-| Namespace | Source workspace | Role |
-|---|---|---|
-| `core` | `@vortex-os/core` | Frontmatter parser (BOM-safe), three-tier privacy filter, `ModuleContext` path resolver, shared types |
-| `slashCommands` | `@vortex-os/slash-commands` | `Command`, `CommandRegistry`, `runSlash` primitives |
-| `memorySystem` | `@vortex-os/memory-system` | Markdown-frontmatter memory store + `MEMORY.md` index writer + diff helpers |
-| `dataLint` | `@vortex-os/data-lint` | Pluggable linter for markdown directories (frontmatter / privacy / wiki-link checks) |
-| `aiCodingPitfalls` | `@vortex-os/ai-coding-pitfalls` | Typed catalog of AI coding pitfall patterns |
-| `toolRules` | `@vortex-os/tool-rules` | Typed catalog of tool usage rules |
-| `reportGenerator` | `@vortex-os/report-generator` | HTML reports with privacy-marker section filtering |
-| `til` | `@vortex-os/til` | Daily work-log store with year/month layout |
-| `decisionLog` | `@vortex-os/decision-log` | Decision-log store with template-driven entry creation |
-| `indexGenerator` | `@vortex-os/index-generator` | `_INDEX.md` rendering (flat + nested modes) |
-| `runbooks` | `@vortex-os/runbooks` | Runbook store with `last_tested`-based stale detection |
-| `linkRewriter` | `@vortex-os/link-rewriter` | Wiki-link extract / resolve / check / rewrite |
-| `sessionRituals` | `@vortex-os/session-rituals` | Daily session-loop slash commands: `/session-start`, `/reindex`, `/decision`, `/til`, `/vortex` |
-
-## Capability add-ons (Phase 11+)
-
-Future capability clusters publish as siblings under the `@vortex-os` scope and install alongside the base. The base auto-detects installed add-ons at session-start:
-
-- `@vortex-os/memory-extended` (Phase 11) — sqlite + vector + recall for scale and semantic search. Peer-depends on this base. See [memory-extended-design.md](https://github.com/dydan77/vortex/blob/main/docs/memory-extended-design.md).
-- `@vortex-os/dev-toolkit` (Phase 12) — vibe coding + self-QA + CI/CD assistance.
-- `@vortex-os/vision` (Phase 14, under review) — screen context + visual reasoning.
-
-Each add-on installs alongside the base and extends what the agent can do without forcing a base upgrade.
-
-## Packaging notes
-
-- **Bundled**: all 13 workspaces are bundled into the published artifact via `tsup`. Consumers do not need to install workspace packages individually.
-- **External dependency**: `yaml` is left as a runtime dependency (npm resolves it on install).
-- **Format**: ESM only. `"type": "module"` in your consumer is required (or set up `.mjs`).
-- **Types**: a single `dist/index.d.ts` exposes all namespace types.
-
-## Related
-
-- [VortEX framework repository](https://github.com/dydan77/vortex) — source, design docs, integration template for instances
-- [Phase 10 split plan v2](https://github.com/dydan77/vortex/blob/main/docs/phase-10-split-plan.md) — capability-cluster packaging design
-- [Memory-extended design](https://github.com/dydan77/vortex/blob/main/docs/memory-extended-design.md) — Phase 11 (memory-extended add-on) reference
-
-## License
-
-MIT — see [LICENSE](./LICENSE).
+# @vortex-os/base
+
+```
+ __   __       _   _____  __
+ \ \ / ___ _ _| |_| __\ \/ /
+  \ V / _ | '_|  _| _| >  <
+   \_/\___|_|  \__|___/_/\_\
+  Vortex absorbs context · EX executes it
+```
+
+Base entry point for **VortEX** — a Multi-Agent Personal AI Work OS framework.
+
+`@vortex-os/base` bundles the framework's 14 internal workspaces (core utilities, slash-command runtime, memory store, daily-log store, decision-log store, runbook store, link-rewriter, index-generator, data-linter, report-generator, two catalog modules, the proactive-curator proposal engine, and the session-rituals plugin) into a single installable package. Install once, get the whole framework.
+
+## Install
+
+```bash
+npm install @vortex-os/base
+```
+
+## 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 {
+  core,
+  slashCommands,
+  memorySystem,
+  worklog,
+  decisionLog,
+  proactiveCurator,
+  sessionRituals,
+} from "@vortex-os/base";
+
+// Use the slash-rituals registry against your own data directory
+const registry = sessionRituals.createRitualRegistry();
+const ctx = core.makeContext(process.cwd());
+
+await slashCommands.runSlash("/session-start", { registry, context: ctx });
+```
+
+### Opt-in `/curate` surface
+
+The `/curate` command is opt-in because it needs a host-supplied LLM adapter. To enable it on Claude Code, wire a sub-agent invoker:
+
+```ts
+import { proactiveCurator, sessionRituals } from "@vortex-os/base";
+
+const llm = new proactiveCurator.ClaudeCodeLLMJudge(async ({ prompt }) => {
+  // Host-specific sub-agent invocation; return the sub-agent's raw answer.
+  return await invokeMySubAgent(prompt);
+});
+
+const registry = sessionRituals.createRitualRegistry({
+  curate: {
+    llm,
+    // Optional — supply the in-session insight surface with recent turns.
+    insightInputProvider: () => ({
+      recentTurns: myTurnBuffer.recent(20),
+      accumulatedTokens: myTurnBuffer.tokenCount(),
+    }),
+  },
+});
+```
+
+Without an `LLMJudge`, `/curate` is simply absent (graceful degradation); the rest of the rituals work unchanged.
+
+## Exported namespaces
+
+Each internal workspace is exposed as a top-level namespace on the package:
+
+| Namespace | Source workspace | Role |
+|---|---|---|
+| `core` | `@vortex-os/core` | Frontmatter parser (BOM-safe), three-tier privacy filter, `ModuleContext` path resolver, shared types |
+| `slashCommands` | `@vortex-os/slash-commands` | `Command`, `CommandRegistry`, `runSlash` primitives |
+| `memorySystem` | `@vortex-os/memory-system` | Markdown-frontmatter memory store + `MEMORY.md` index writer + diff helpers |
+| `dataLint` | `@vortex-os/data-lint` | Pluggable linter for markdown directories (frontmatter / privacy / wiki-link checks) |
+| `aiCodingPitfalls` | `@vortex-os/ai-coding-pitfalls` | Typed catalog of AI coding pitfall patterns |
+| `toolRules` | `@vortex-os/tool-rules` | Typed catalog of tool usage rules |
+| `reportGenerator` | `@vortex-os/report-generator` | HTML reports with privacy-marker section filtering |
+| `worklog` | `@vortex-os/worklog` | Daily work-log store with year/month layout |
+| `decisionLog` | `@vortex-os/decision-log` | Decision-log store with template-driven entry creation |
+| `indexGenerator` | `@vortex-os/index-generator` | `_INDEX.md` rendering (flat + nested modes) |
+| `runbooks` | `@vortex-os/runbooks` | Runbook store with `last_tested`-based stale detection |
+| `linkRewriter` | `@vortex-os/link-rewriter` | Wiki-link extract / resolve / check / rewrite |
+| `proactiveCurator` | `@vortex-os/proactive-curator` | Topic-aware proposal engine — in-session insight capture + hub auto-curation with 4-action active placement (`create-folder` / `create-file` / `append-section` / `update-file`). Asymmetric LLM gate for hub thresholds (3 weak / 5 strong). Decline durability + Claude Code `LLMJudge` adapter. |
+| `sessionRituals` | `@vortex-os/session-rituals` | Daily session-loop slash commands: `/session-start`, `/reindex`, `/decision`, `/log`, `/vortex`, `/curate`, `/recall` |
+
+## Capability add-ons (Phase 11+)
+
+Future capability clusters publish as siblings under the `@vortex-os` scope and install alongside the base. The base auto-detects installed add-ons at session-start:
+
+- **`@vortex-os/memory-extended@0.5.0` (Phase 11) — shipped** — all five namespaces are live: `sqlite` (structured index + drift detection), `vector` (brute-force cosine backend, local `multilingual-e5-small` embedder), `recall` (two-stage hybrid `/recall` over memories *and* conversation sessions), `sessionArchive` (four first-party host adapters: Claude Code, Codex, Gemini, Claude Desktop), `consolidate` (post-session memory-candidate proposer). Peer-depends on this base. See [memory-extended-design.md](https://github.com/vortex-os-project/vortex/blob/main/docs/memory-extended-design.md).
+- `@vortex-os/dev-toolkit` (Phase 12) — vibe coding + self-QA + CI/CD assistance.
+- `@vortex-os/vision` (Phase 14, under review) — screen context + visual reasoning.
+
+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.
+- **External dependency**: `yaml` is left as a runtime dependency (npm resolves it on install).
+- **Format**: ESM only. `"type": "module"` in your consumer is required (or set up `.mjs`).
+- **Types**: a single `dist/index.d.ts` exposes all namespace types.
+
+## Related
+
+- [VortEX framework repository](https://github.com/vortex-os-project/vortex) — source, design docs, integration template for instances
+- [Phase 10 split plan v2](https://github.com/vortex-os-project/vortex/blob/main/docs/phase-10-split-plan.md) — capability-cluster packaging design
+- [Memory-extended design](https://github.com/vortex-os-project/vortex/blob/main/docs/memory-extended-design.md) — Phase 11 (memory-extended add-on) reference
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

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":[]}