@vortex-os/base 0.4.0 → 0.5.0

package/dist/vectorize-PN4Y7XMO.js

@@ -0,0 +1,30 @@
+import "./chunk-PZ5AY32C.js";
+
+// ../plugins/session-rituals/dist/vectorize.js
+import { join } from "path";
+async function vectorizeIndex(ctx, opts) {
+  const { sqlite, vector, sessionArchive } = await import("@vortex-os/memory-extended");
+  const dbPath = opts?.dbPath ?? join(ctx.dataDir, "_indexes", "memory.sqlite");
+  const memoryDir = join(ctx.dataDir, "_memory");
+  const embed = opts?.embed ?? vector.createLocalEmbedder({ localFilesOnly: !opts?.allowDownload });
+  const sqlStore = new sqlite.MemorySqliteStore(dbPath);
+  const vecStore = new vector.MemoryVectorStore({ db: dbPath });
+  const archive = new sessionArchive.SessionArchiveStore(ctx.dataDir);
+  try {
+    try {
+      await sqlite.rebuildFromMemoryDir(sqlStore, memoryDir);
+    } catch {
+    }
+    const mem = await vecStore.rebuild(sqlStore, embed, { onlyMissing: true });
+    const sess = await vecStore.rebuildSessions(archive, embed, { onlyMissing: true });
+    return { memories: mem.indexed, sessionChunks: sess.chunks };
+  } finally {
+    archive.close();
+    vecStore.close();
+    sqlStore.close();
+  }
+}
+export {
+  vectorizeIndex
+};
+//# sourceMappingURL=vectorize-PN4Y7XMO.js.map

package/dist/vectorize-PN4Y7XMO.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../plugins/session-rituals/src/vectorize.ts"],"sourcesContent":["import { join } from \"node:path\";\nimport 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 deps) into the module\n// graph of consumers that only need the types. The runtime engine is loaded\n// lazily inside the function body via `await import(...)`.\nimport type { vector } from \"@vortex-os/memory-extended\";\n\n/**\n * Start-of-session vectorization: fold newly-archived sessions and memories\n * into the semantic-recall index so `/recall` and the ambient \"did we discuss\n * this?\" path stay current without a manual rebuild.\n *\n * The heavy one-time cost (downloading the embedding model + embedding the\n * whole backlog) happens the first time recall is set up — via an explicit\n * `/recall`, or via the `vortex vectorize` setup worker that session start\n * spawns in the background when the add-on is installed and\n * `autoRecord.vectorizeAutoDownload` is on. From then on the model is cached\n * and this runs **incrementally** — memory rows whose hash changed, plus\n * sessions not yet vectorized (`onlyMissing`) — so the per-session-start cost\n * is small.\n *\n * `allowDownload` defaults false, so the automatic inline session-start call is\n * cache-only and never triggers a model download on its own; only the explicit\n * setup paths pass `allowDownload: true`. A throw is treated as \"skip\"\n * (best-effort): a missing model, a rebuild hiccup, or the add-on being absent\n * must never fail session start.\n */\nexport interface VectorizeResult {\n  /** Memory rows (re)embedded this run. */\n  readonly memories: number;\n  /** Session chunks embedded this run (only the not-yet-vectorized ones). */\n  readonly sessionChunks: number;\n}\n\nexport interface VectorizeOptions {\n  /**\n   * Embedding function. Default: the bundled local model\n   * (`vector.createLocalEmbedder()`). Tests inject a deterministic fake so the\n   * run needs no model and no network.\n   */\n  readonly embed?: vector.EmbedFn;\n  /** Override the index DB path. Default `<dataDir>/_indexes/memory.sqlite`. */\n  readonly dbPath?: string;\n  /**\n   * Allow the embedder to DOWNLOAD the model when it is not cached. Default\n   * `false`: the automatic session-start path stays cache-only (a cache miss\n   * throws fast — no ~470 MB download). The explicit `vortex vectorize` setup\n   * worker passes `true` to bring the model into the cache the first time.\n   * Ignored when `embed` is supplied (tests inject their own embedder).\n   */\n  readonly allowDownload?: boolean;\n}\n\nexport async function vectorizeIndex(\n  ctx: ModuleContext,\n  opts?: VectorizeOptions,\n): Promise<VectorizeResult> {\n  // Lazy-load the optional add-on (mirrors catch-up). Resolves only when\n  // `memory-extended` is installed alongside base; a lean install throws here\n  // and the call site treats it as \"skip\".\n  const { sqlite, vector, sessionArchive } = await import(\"@vortex-os/memory-extended\");\n\n  const dbPath = opts?.dbPath ?? join(ctx.dataDir, \"_indexes\", \"memory.sqlite\");\n  const memoryDir = join(ctx.dataDir, \"_memory\");\n  // `localFilesOnly` is the real safety gate for this automatic path: if the\n  // embedding model is not already cached, the first embed throws immediately\n  // (no ~470 MB download) and the caller skips. So session-start vectorization\n  // can never trigger an unprompted download, even if the index db exists for\n  // some other reason. The model is downloaded only by the explicit, consented\n  // `/recall` setup, which uses the default network-enabled embedder.\n  const embed = opts?.embed ?? vector.createLocalEmbedder({ localFilesOnly: !opts?.allowDownload });\n\n  const sqlStore = new sqlite.MemorySqliteStore(dbPath);\n  const vecStore = new vector.MemoryVectorStore({ db: dbPath });\n  const archive = new sessionArchive.SessionArchiveStore(ctx.dataDir);\n  try {\n    // Memory: refresh the sqlite hard-filter index (no model needed) then its\n    // vectors. Best-effort per step — a missing _memory dir must not abort the\n    // session pass.\n    try {\n      await sqlite.rebuildFromMemoryDir(sqlStore, memoryDir);\n    } catch {\n      // no _memory dir yet — nothing to index\n    }\n    // Both incremental (`onlyMissing`): embed only newly-added memories and\n    // not-yet-vectorized sessions, so the per-session-start cost is bounded to\n    // what actually changed — usually nothing or a single new session.\n    const mem = await vecStore.rebuild(sqlStore, embed, { onlyMissing: true });\n    const sess = await vecStore.rebuildSessions(archive, embed, { onlyMissing: true });\n    return { memories: mem.indexed, sessionChunks: sess.chunks };\n  } finally {\n    archive.close();\n    vecStore.close();\n    sqlStore.close();\n  }\n}\n"],"mappings":";;;AAAA,SAAS,YAAY;AAsDrB,eAAsB,eACpB,KACA,MAAuB;AAKvB,QAAM,EAAE,QAAQ,QAAQ,eAAc,IAAK,MAAM,OAAO,4BAA4B;AAEpF,QAAM,SAAS,MAAM,UAAU,KAAK,IAAI,SAAS,YAAY,eAAe;AAC5E,QAAM,YAAY,KAAK,IAAI,SAAS,SAAS;AAO7C,QAAM,QAAQ,MAAM,SAAS,OAAO,oBAAoB,EAAE,gBAAgB,CAAC,MAAM,cAAa,CAAE;AAEhG,QAAM,WAAW,IAAI,OAAO,kBAAkB,MAAM;AACpD,QAAM,WAAW,IAAI,OAAO,kBAAkB,EAAE,IAAI,OAAM,CAAE;AAC5D,QAAM,UAAU,IAAI,eAAe,oBAAoB,IAAI,OAAO;AAClE,MAAI;AAIF,QAAI;AACF,YAAM,OAAO,qBAAqB,UAAU,SAAS;IACvD,QAAQ;IAER;AAIA,UAAM,MAAM,MAAM,SAAS,QAAQ,UAAU,OAAO,EAAE,aAAa,KAAI,CAAE;AACzE,UAAM,OAAO,MAAM,SAAS,gBAAgB,SAAS,OAAO,EAAE,aAAa,KAAI,CAAE;AACjF,WAAO,EAAE,UAAU,IAAI,SAAS,eAAe,KAAK,OAAM;EAC5D;AACE,YAAQ,MAAK;AACb,aAAS,MAAK;AACd,aAAS,MAAK;EAChB;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vortex-os/base",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Base entry point for VortEX — a Multi-Agent Personal AI Work OS framework",
   "license": "MIT",
   "author": "vortex-os-project",
@@ -32,7 +32,7 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "vortex": "./bin/vortex.mjs"
+    "vortex": "bin/vortex.mjs"
   },
   "exports": {
     ".": {

package/templates/commands/recall.md

@@ -1,17 +1,31 @@
----
-description: Semantic search over your memories and past conversations
-argument-hint: <what to recall>
-allowed-tools: Bash(npx vortex:*)
----
-The user wants to recall earlier work: **$ARGUMENTS**
-
-1. From the instance root, run: `npx vortex recall "$ARGUMENTS" --k 5`
-2. Parse the JSON it prints. Each entry in `hits[]` has a name/title, `source`
-   (`memory` or `session-archive`), `score`, a date, and an `excerpt`.
-3. Present the result plainly — never dump raw JSON:
-   - No hits → say nothing matched and suggest rephrasing.
-   - One strong hit → a single sentence ("you did **<name>** on <date> — reuse it?").
-   - Several → a short ranked list (≤5): name — date — one line on why it matches.
-
-Keep it brief; this is a lookup, not a report. The first run may pause while the
-local embedding model loads (one-time download).
+---
+description: Keyword + semantic (hybrid) search over your memories and past conversations
+argument-hint: <what to recall>
+allowed-tools: Bash(npx vortex:*)
+---
+The user wants to recall earlier work: **$ARGUMENTS**
+
+1. Pick the search mode from what the user is after:
+   - exact terms, an error code, a file name, an identifier, or a literal they quoted → `--mode keyword`
+   - a concept, a topic, or "something like X" / "did we discuss …" → `--mode semantic`
+   - unsure, or both apply → omit `--mode` (hybrid is the default — runs both lanes and fuses them)
+   Keyword matching wants a token of **3+ characters**; for a 1–2 character token prefer hybrid so the meaning-based lane can help.
+2. From the instance root, run: `npx vortex recall "$ARGUMENTS" --k 5` (add `--mode keyword` or `--mode semantic` when one clearly fits).
+3. Parse the JSON it prints. Each entry in `hits[]` has a name/title, `source`
+   (`memory` or `session-archive`), `score`, a date, and an `excerpt` — and, on a
+   hybrid or keyword run, `lanes` (which lane matched) and `fusedScore`.
+4. Present the result plainly — never dump raw JSON:
+   - No hits → say nothing matched and suggest rephrasing.
+   - One strong hit → a single sentence ("you did **<name>** on <date> — reuse it?").
+   - Several → a short ranked list (≤5): name — date — one line on why it matches.
+
+Keep it brief; this is a lookup, not a report.
+
+**First-time setup (once per instance).** Recall uses a local search model that
+downloads **once (~470 MB)**. If it has not been set up here yet (no
+`data/_indexes/memory.sqlite`), ask before running — in plain words, no jargon —
+e.g. *"Want me to make your past conversations searchable later? It downloads a
+local search model once (~470 MB), and after that it's automatic."* — and run the command only if the user
+agrees. After that one setup, new conversations are indexed automatically at each
+session start, so later recalls — and the ambient "did we discuss this before?"
+lookups — just work, with no further prompt or download.

package/templates/config/vortex.json

@@ -6,5 +6,8 @@
     "ambientRecall": true,
     "archive": true
   },
+  "updates": {
+    "check": "session"
+  },
   "environments": []
 }

package/templates/manifest.json

@@ -0,0 +1,51 @@
+{
+  "schema": "vortex-template-index/1",
+  "baseVersion": "0.5.0",
+  "files": [
+    {
+      "templateId": "commands/agenda.md",
+      "path": "commands/agenda.md",
+      "sha256": "54b38dd4a66c1495d5fb573fa644539d7fd0444d27be361674c54e8f4e3fe536"
+    },
+    {
+      "templateId": "commands/curate.md",
+      "path": "commands/curate.md",
+      "sha256": "c00f7dc53c802b100a90354b9713191c9d4909e69ef2b57cc14b2c25eeec5c88"
+    },
+    {
+      "templateId": "commands/recall.md",
+      "path": "commands/recall.md",
+      "sha256": "913451c33a6313c923e8433a198846bd5c6616234b1b1b337e15e0d5afe27337"
+    },
+    {
+      "templateId": "config/vortex.json",
+      "path": "config/vortex.json",
+      "sha256": "71d629ce0038534dc3921a1c5e507897ec8754df50a76ad4e9da93327e84b4d6"
+    },
+    {
+      "templateId": "routers/.cursorrules",
+      "path": "routers/.cursorrules",
+      "sha256": "724623db58fca38c386b0c28afd3503a46715a4b5f40ff4eee4daf78d1e4a5db"
+    },
+    {
+      "templateId": "routers/AGENTS.md",
+      "path": "routers/AGENTS.md",
+      "sha256": "422f925b62403c410478401f2fbbe538411b055336d9785c3a2efe7bb2ced72d"
+    },
+    {
+      "templateId": "routers/AI-RULES.md",
+      "path": "routers/AI-RULES.md",
+      "sha256": "4048467df07f6e344ba09ef5e7044fb21492fc63cd4c16e4ba2ffd5c7e15facf"
+    },
+    {
+      "templateId": "routers/CLAUDE.md",
+      "path": "routers/CLAUDE.md",
+      "sha256": "b778d6d322d7436d1391881fe9c9a16d17a99231bbd5fb6955c7bee1a08b5597"
+    },
+    {
+      "templateId": "routers/GEMINI.md",
+      "path": "routers/GEMINI.md",
+      "sha256": "752a3388610fafd649c50e80d0bd6ea471745218937ada71560a34b53783f5de"
+    }
+  ]
+}

package/templates/routers/.cursorrules

@@ -1,13 +1,13 @@
 VortEX Instance — Multi-Agent Personal AI Work OS
 
-When working in this repository, you (Cursor) MUST read AGENT.md first. AGENT.md is the
-single source of truth for how this instance behaves, its data/ layout, conventions, and
-the commands available.
+When working in this repository, you (Cursor) MUST read AI-RULES.md first. AI-RULES.md is the
+single source of truth for shared behavior across all agents: the data/ layout, conventions,
+default behaviors, and the commands available.
 
 Cursor-specific config lives in .cursor/. Shared agent config lives in .agent/.
 
-Per-agent files (CLAUDE.md, CODEX.md, GEMINI.md, .cursorrules) are routers; system-wide
-rules belong in AGENT.md, never duplicated per agent.
+Per-agent entry files (CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules) hold only that agent's
+own supplements; the shared rules live in AI-RULES.md, never duplicated per agent.
 
 This instance was created from the @vortex-os/base framework. The framework code lives in
 node_modules/@vortex-os/; you do not edit it. You work in data/ and use the vortex CLI and

package/templates/routers/AGENTS.md

@@ -1,18 +1,27 @@
-# AGENTS.md
+---
+type: agent-entry
+status: active
+---
 
-This is the file Codex CLI (and other `AGENTS.md`-aware agents) auto-loads when
-working in this VortEX instance.
+# VortEX Instance — Codex CLI entry
 
-## Route to unified entry
+This is the file Codex CLI auto-loads in this VortEX instance. It holds only Codex-specific supplements; the rules shared by **every** agent live in `AI-RULES.md`.
 
-Read [`AGENT.md`](./AGENT.md) first — it is the single source of truth for how
-this instance behaves. This `AGENTS.md` is only the auto-load entry point; the
-full, host-agnostic behavior contract lives in `AGENT.md`.
+## CRITICAL — load the shared rules first
 
-## Working in a VortEX instance (summary)
+The shared rules, default behaviors, `data/` layout, and commands for every agent in this instance are defined in **`AI-RULES.md`**. You MUST read and follow `./AI-RULES.md` **before responding to any request** — it is required reading, not optional.
 
-VortEX rituals are agent-mediated: run the thin `vortex` CLI and present its JSON
-result to the user in plain language — e.g. `npx vortex status`,
-`npx vortex agenda`, `npx vortex recall "<query>"`, `npx vortex log "<update>"`.
-Never hand-write into the reserved system directories under `data/`
-(`worklog`, `decision-log`, `runbooks`, `hubs`, any `_*`) — go through the CLI.
+👉 Read now: `./AI-RULES.md`
+
+> Codex CLI has no auto-import directive, so this instruction *is* the load mechanism — do not skip it. Any other `AGENTS.md`-aware tool that reads this file must do the same: treat `AI-RULES.md` as the shared source of truth.
+
+## Codex-specific supplements
+
+- Dedicated dir: `.codex/`
+- Shared dir: `.agent/`
+
+## Cross-check tool (per `AI-RULES.md` → "Cross-check significant decisions")
+
+For a **cross-model** check, Codex can call Claude Code headless: `claude -p "<prompt>"`. Otherwise use a clean-context Codex sub-task with only the relevant facts. Return only the verdict — you still decide and close by verifying against the code/tests. When you shell out to `claude -p`: close stdin (`< /dev/null`) so it doesn't wait ~3s for input, and set your own timeout.
+
+For the **security-review** lens (per `AI-RULES.md` → "Security-review code changes"), run the same kind of pass but focused on security — path traversal / arbitrary write, command / SQL / template injection, secret leakage, SSRF, unsafe deserialization, missing input validation — via `claude -p` (cross-model) or a clean-context Codex sub-task given only the diff + the threat surface.

package/templates/routers/AI-RULES.md

@@ -0,0 +1,127 @@
+---
+type: agent-entry
+status: active
+---
+
+# VortEX Instance — Shared Agent Rules (AI-RULES)
+
+> A vortex absorbing context, an executable runtime running it through agents.
+
+These are the rules shared by **every** agent working in this instance (Claude Code, Codex CLI, Gemini CLI, Cursor) — the single source of truth for shared behavior. Each agent auto-loads its own entry file (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursorrules`), which holds that agent's specific supplements and loads **this** file for everything shared: Claude and Gemini import it automatically (`@AI-RULES.md`), while Codex and Cursor are instructed to read it first.
+
+This instance was created from the `@vortex-os/base` framework. The framework code lives in `node_modules/@vortex-os/`; you do not edit it. You work in `data/` — your own content — and use the `vortex` CLI and the `/`-commands it installs.
+
+**Framework-owned vs yours — so updates never clobber your rules.** This file (`AI-RULES.md`), the per-agent router files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`), and the installed `/`-command prompts are **framework-owned templates** — a future update may refresh them, so do **not** keep your own rules in them. Put durable personal rules in **`data/_memory/`** (the framework never touches `data/`, so they survive every update). They load in two tiers — see "The `data/` layout" → memory loading. To **override** a framework instruction (not just add a preference), say so explicitly in a memory; precedence is **framework default < your `data/_memory/` rule < your current request**. The split: **framework files update, `data/` is yours.**
+
+## First thing to check
+
+If `data/_memory/user_profile.md` is missing, this instance has not been set up yet. Run:
+
+```
+npx vortex init --name "<your name>" --role "<your role>" --task "<what you're working on>"
+```
+
+`init` creates a user-profile memory, today's first worklog, the agent slash-commands, and wires the session hooks. Everything after that grows as you work.
+
+## How VortEX behaves by default — auto the plumbing, propose the prose
+
+Operating principle: **auto-maintain the operational memory; propose changes to the knowledge base.** You should never have to learn commands to get value — the records that make recall smarter accumulate on their own, while you keep full control over your own topic documentation.
+
+**Auto (no prompt — append-only operational records; *show, don't ask*):**
+- **Session start.** Run the start ritual: if a sync remote is configured, `git pull` (report conflicts, never auto-resolve); detect the environment if one is configured (and if a label resolves with a matching `.agent/env/<label>.md`, read that file as session-specific operating guidance); backfill any worklog missing from prior sessions; **load your `data/_memory/` always-on rules and scan its `_INDEX.md`** (see "The `data/` layout" → memory loading); report status. If the `SessionStart` hook is configured, the **data-side** ritual already ran and its report was **injected into your context — the user has NOT seen it. Start your first reply by relaying the key points: recent work, what's in progress, the time, any update notices, and any warnings.** If no hook ran, perform the ritual yourself first, then report the same status. (Automatic means the records updated on their own — informing the user is still your job.)
+- **Worklog.** As a work unit completes — and at session wind-down ("that's it for today", "wrap up") — ensure today's worklog exists and append the work. The agent is the primary path; the `SessionEnd` hook is the net.
+- **Decisions.** When the user makes a *substantive* decision ("let's go with X"), record it in the Decision Log. Real decisions, not casual asides.
+- **Ambient recall** (read-only). When the user references earlier work, run `/recall <the reference>` and weave a confident hit into one sentence. One nudge, not a list; drop it if waved off. Conversations are vectorized automatically at session start. With the `@vortex-os/memory-extended` add-on installed, the first session also sets recall up on its own — downloading the local search model (~470 MB, once) in the **background** — so recall and these ambient lookups just work with no prompt and no manual step (the session-start report notes the one-time download while it runs; relay that). To keep that download manual instead (metered line, CI), set `autoRecord.vectorizeAutoDownload: false` (or env `VORTEX_VECTORIZE_AUTO_DOWNLOAD=0`) and set it up once with `/recall` or `vortex vectorize`.
+
+These are **append-only and transparent**: do them without a yes/no prompt, but surface a brief, non-blocking note so the user always sees what was recorded. Everything lands in git and is reversible; disable any of them via `.agent/vortex.json` (`autoRecord.*`). `git push` stays **explicit**, never automatic.
+
+**Propose (ask first — the one place friction is intentional):**
+- **Knowledge-base documentation.** Changes to the user's topic documentation (the `data/<topic>/` tree and hubs) are **proposed, never auto-written**: "you've done X, Y, Z on this — update the existing doc, or create a new folder?" The user owns the shape of their knowledge base; the agent never silently restructures it.
+
+The line is technical: **append-only operational logs are safe to auto-write; structural or content changes to the knowledge base are proposed.**
+
+## Before you modify a repo — check it's current
+
+Before you start **substantively modifying files in a git repository** (any folder git tracks — note `.git` may be a *file*, not a directory, inside a worktree or submodule), make sure it isn't stale: run `git fetch`, then `git rev-list --left-right --count HEAD...@{upstream}` (the two numbers are commits-ahead and commits-behind). If you're **behind**, say so and ask whether to `git pull --ff-only` before continuing. If **both** sides moved (diverged), do **not** auto-pull — report it and let the user decide. Do this **once per repo per session**; skip it when the repo has no upstream, or for trivial edits (a one-line fix, a quick note). The instance repo is already pulled at session start — don't re-check that one. Offline or any git error: just proceed, noting you couldn't verify. This prevents building on a stale base or creating a divergent history.
+
+## Framework updates
+
+Session start checks **once per session** whether a newer `@vortex-os/base` is published — this **contacts the npm registry over the network**. Mention that to the user when it first comes up, and note they can turn it off with `.agent/vortex.json` → `"updates": { "check": "off" }`. Two kinds of notice may appear in the start report:
+
+- **"template update(s) ready to apply"** — the installed package already has newer framework templates this instance has not applied. Offer to run `npx vortex update` — it refreshes the routers / command prompts / config, **hash-guarded: your edits are never overwritten** (a framework file you changed is parked alongside as `<file>.new` for you to merge).
+- **"update available: @vortex-os/base X → Y"** — a newer version is published. Tell the user in one sentence and **ask once** whether to update now. On yes, run **the exact command the report printed** — it is tailored to this instance (local vs global; npm/pnpm/yarn), e.g. `npm i @vortex-os/base@latest && npx vortex update` (install the new package, then apply its templates); use the printed command, not this example. Then confirm it landed with `npx vortex check-updates`. On no, drop it for the session. **Never install without asking.**
+
+When the user asks whether there's an update, run `npx vortex check-updates` (read-only — contacts the npm registry and prints the latest version and the exact update command).
+
+## Working style
+
+**Explain simply and briefly — assume the user is not an IT expert.** Default to plain language. Lead with the conclusion. Keep ordinary replies short (a few lines, at most a few bullets); add tables/code only when they earn their place. Unpack any unavoidable technical term in a line or with a plain analogy, and when you must use a technical or non-native term, gloss it in the user's language in parentheses right after it. Write in a **standard written register** — clear and plain, never casual or colloquial speech. Match the user's *level* of detail, not their *voice*: don't echo their slang, tics, or phrasing back (it drifts your tone across the session and the next), unless the current request explicitly asks for a particular style.
+
+**Ask one decision at a time.** When you need the user to decide, ask a single question and wait — do not stack several at once. Only batch when the choices are genuinely independent.
+
+**Match reasoning effort to the task.** Don't over-reason trivial asks — a status check, a one-line edit, a lookup; don't under-reason heavy ones — architecture design, multi-file refactors, large debugging or migration, broad reviews. If the host exposes a tunable reasoning/thinking level and the task ahead clearly needs a different one than the session is set for, recommend the change — but rarely: only at a real boundary (a sizable task's start, a major topic shift, a substantial new directive), one or two times across a long session, never per question.
+
+**Cross-check significant decisions.** For a non-trivial design, implementation, or fix choice, seek an adversarial second opinion before relying on it — a **different model/tool** if one is available, otherwise a **sub-agent given a clean context and only the relevant facts + acceptance criteria**. Agreement is a signal, not proof: the main thread still decides, and closes by verifying against ground truth (usually the code and tests). Scale to the stakes; skip trivial edits. (The per-host file names the concrete tool.)
+
+**Security-review code changes.** A distinct lens from the correctness cross-check above (code can work and still be unsafe). Before relying on a non-trivial code change that touches a security-sensitive surface — file paths/writes, shell/exec, network requests, deserialization, auth/secrets, or any external/untrusted input — run a security-focused adversarial pass. Use the same mechanism: a **different model/tool** if available, otherwise a **clean-context sub-agent given only the diff + the threat surface**. Look for the usual classes — path traversal / arbitrary write, command / SQL / template injection, secret leakage, SSRF, unsafe deserialization, missing input validation. Judge findings on the merits; close by fixing and re-verifying against the code. Scale to the surface; skip pure docs/test/format edits. (The per-host file names the concrete tool.)
+
+**Time a handed-off task.** When the user hands a task off to run while they are away — signals like "do this and ping me", "I'm going to sleep", "back later", or any clearly unattended multi-step task — stamp the **real start time** (via a time command, never a guess) the moment you take it on. When you report completion, include the **elapsed time and the finish time**, both computed from real timestamps (never estimated), and record `started HH:MM → finished HH:MM (N min)` in the worklog — add the date when start and finish fall on different days, and log it under the finish day. Skip this for quick interactive back-and-forth, where timing would just be noise.
+
+**Own routine sequencing.** Decide work order yourself — verify dependencies first (batch edits that touch the same file; finish in-flight work before switching context). Procedure is agent-owned; ask only when the path forks on user intent, on the structure of user-owned content, or on a hard-to-reverse action (commit, push, deploy, delete).
+
+**Protect the main thread's context — delegate heavy, self-contained work.** A long session fills its context window (the reason you end up reopening sessions); offloading keeps the main thread lean *without* losing quality, if done right. When a task is self-contained and clearly specifiable — a broad search, multi-file exploration, a long-output investigation, bulk generation — hand it to a separate agent/subtask with a **precise spec and acceptance criteria**, and bring back only the conclusion. The main thread keeps the plan, the decisions, and the synthesis — it never delegates the *judgment* — and **verifies a delegated result before building on it** (so have the sub-agent report its evidence: what it inspected, the key findings, what's uncertain). **Don't delegate** when the spec is fuzzy, the call is a judgment, the material is sensitive, the work is tightly coupled to the edit you're making, or verifying the result would cost as much as just doing it. Scale the mechanism to the host (the per-host file, e.g. `CLAUDE.md`, names the concrete tools); where a host has no sub-agents, the fallback is a fresh session plus a short handoff note.
+
+## The `data/` layout
+
+Your content lives under `data/`. Each category answers a different question:
+
+| Category | Question it answers |
+|---|---|
+| `worklog/` | "What happened today?" — chronological, one entry per day (`YYYY/MM/YYYY-MM-DD-keyword.md`). |
+| `decision-log/` | "Why did we choose X over Y?" — per-decision record with context + alternatives. |
+| `_memory/` | "What rule or fact must survive every session?" — curated; loads in two tiers (below). |
+| `runbooks/` | "What is the procedure when X breaks?" — repeatable steps with `last_tested` aging. |
+| `hubs/` | "Where do I find everything about topic Z?" — a cross-cut landing page; grows organically once 3+ categories accumulate on the same topic. |
+| `inbox/` | "Where does an unfiled note land before I sort it?" |
+
+A typical day flows from short-lived capture (worklog) into longer-lived artifacts (decision-log, runbook, memory, hub). These are common promotion patterns, not required flows.
+
+**Memory loading (two tiers — so rules are active without wasting context).** Not every memory should sit in context all the time. Load them in two tiers:
+
+1. **Always-on rules** — the few global rules that apply across all your VortEX work (e.g. how you want answers written, tool conventions). Mark a memory `scope: always` in its frontmatter; **load these every session.** Keep the set small and each one short.
+2. **On-demand** — everything else (project facts, situational rules, reference). At session start scan only the one-line **`_INDEX.md`** (name + description per memory) to know what exists; **read a memory's body only when the conversation makes it relevant**, and re-check the index as the topic shifts. `_INDEX.md` is regenerated by `npx vortex reindex`; keep each memory's `description` sharp, since that one line is what decides whether it gets loaded.
+
+So: global rules are always in view; everything else is a cheap index entry until needed.
+
+## Commands you'll use
+
+These slash-commands are installed into `.claude/commands/` by `vortex init` (the agent runs the underlying `vortex` CLI and presents the result):
+
+| Command | What it does |
+|---|---|
+| `/vortex` | Instance operations: `init`, `status`, `import`, `doctor`, `update`, `help`. |
+| `/session-start` | Start-of-session report — recent work, current counts, the time. |
+| `/log <section>` | Append a section to today's worklog (creates it if needed). |
+| `/decision <slug> <title>` | Create a new Decision Log entry from the template. |
+| `/recall <query>` | Keyword + semantic (hybrid) search over your memories and past sessions; the agent picks the mode. *(Only when the optional `@vortex-os/memory-extended` add-on is installed.)* |
+| `/agenda` | "What should I focus on?" — synthesizes open tasks, decisions, recent activity. |
+| `/reindex [dir]` | Regenerate `_INDEX.md` for a category (or all). Idempotent. |
+
+You can also run any of these directly: `npx vortex <command> [args]`.
+
+## Optional add-ons
+
+- **`@vortex-os/memory-extended`** — keyword + semantic (hybrid) recall over memories and past conversation sessions. Install alongside this instance to light up `/recall`; without it, everything else works and `/recall` is simply absent.
+
+## Agent routing
+
+`AI-RULES.md` (this file) is the single source of truth for shared rules. Each agent auto-loads its own entry file, which holds only that agent's supplements and pulls in this file — Claude and Gemini import it automatically (`@AI-RULES.md`); Codex and Cursor are instructed to read it first. Do not duplicate shared rules into the per-agent files.
+
+| Agent | Auto-loads | Reaches shared rules via | Dedicated config |
+|---|---|---|---|
+| Claude Code | `CLAUDE.md` | `@AI-RULES.md` import (automatic) | `.claude/` |
+| Gemini CLI | `GEMINI.md` | `@AI-RULES.md` import (automatic) | `.gemini/` |
+| Codex CLI | `AGENTS.md` | strong directive to read `AI-RULES.md` | `.codex/` |
+| Cursor | `.cursorrules` (and `AGENTS.md`) | directive to read `AI-RULES.md` | `.cursor/` |
+
+All agents share `.agent/`.

package/templates/routers/CLAUDE.md

@@ -2,11 +2,13 @@
 
 This is the first file Claude Code reads when working in this VortEX instance.
 
-## Route to unified entry
+## Shared rules (required — auto-loaded)
 
-Read [`AGENT.md`](./AGENT.md) first — it is the single source of truth for how this instance behaves.
+The rules shared by every agent in this instance live in `AI-RULES.md`, imported here so Claude Code loads it automatically at launch:
 
-This `CLAUDE.md` holds only Claude Code-specific supplements. For everything else, refer to `AGENT.md`.
+@AI-RULES.md
+
+This `CLAUDE.md` holds only Claude Code-specific supplements; everything shared is in `AI-RULES.md` (above).
 
 ## Claude Code-specific config
 
@@ -17,4 +19,21 @@ This `CLAUDE.md` holds only Claude Code-specific supplements. For everything els
 
 ## Reasoning effort
 
-Claude Code exposes a reasoning/effort level you cannot read as a value. When `AGENT.md` → "Working style" calls for an effort change, recommend a *target* ("this looks like high-effort work — raise it if you're below that") rather than asserting the current setting. The user changes it on their side; it takes effect from the next turn, not the current one.
+Claude Code exposes a reasoning/effort level you cannot read as a value. When `AI-RULES.md` → "Working style" calls for an effort change, recommend a *target* ("this looks like high-effort work — raise it if you're below that") rather than asserting the current setting. The user changes it on their side; it takes effect from the next turn, not the current one.
+
+## Delegating to sub-agents (context economy)
+
+This is the Claude Code mechanism behind `AI-RULES.md` → "Working style" → *delegate heavy, self-contained work*. The point is to spend the **sub-agent's** context on the heavy part and return only the conclusion, so the main thread stays lean across a long day.
+
+- **Task / Agent tool — the usual first reach for self-contained work.** Spawn a sub-agent for one scoped, fully-specifiable job; it runs in its own context and only its final answer comes back. Use the **Explore** agent for "search across the repo and tell me the conclusion" (it reads excerpts, not whole files), and a **general-purpose** agent for a multi-step job you can spell out up front. Give it a precise spec + what "done" looks like and have it return its evidence; **verify what it returns** before building on it. (Not for fuzzy, judgment-heavy, or tightly-coupled work — see `AI-RULES.md` → "Working style".)
+- **Several at once.** When jobs are independent, launch them in one message so they run in parallel (e.g. explore three subsystems at once), then synthesize on the main thread.
+- **Custom agents (`.claude/agents/*.md`).** For a delegation you repeat, define a named specialist once and reuse it. Not installed by default — add when a pattern recurs.
+- **Workflows (multi-agent orchestration).** For breadth one context can't hold — a broad review, an audit, a migration across many files. Token-heavy and fan-out-y, so **only when the user explicitly asks** for that scale; otherwise prefer a few Task agents.
+
+Do **not** delegate the judgment — the main thread owns the plan, the decisions, and the final synthesis. Delegate the reading, the searching, the bulk generation; keep the deciding.
+
+## Cross-check tool (per `AI-RULES.md` → "Cross-check significant decisions")
+
+For the adversarial cross-check that `AI-RULES.md` calls for: use a **Task sub-agent with a clean context** (give it only the relevant facts + acceptance criteria) for a same-model check; if the **Codex CLI** is installed, `codex exec -C <repo> -s read-only` is a stronger **cross-model** check. Bring back only the verdict — the main thread still decides and closes by verifying against the code/tests. When you shell out to `codex exec`: close stdin (`< /dev/null`) so it doesn't stall waiting for input, set your own timeout (the host's may not stop a runaway), and keep the reviewer read-only (`-s read-only`).
+
+For the **security-review** lens (per `AI-RULES.md` → "Security-review code changes"): Claude Code ships a `/security-review` command that reviews the pending diff on the current branch — use it for the security pass. For a stronger or independent check, the same `codex exec -C <repo> -s read-only` (cross-model) or a clean-context Task sub-agent (give it only the diff + the threat surface) applies, prompted for the security classes rather than general correctness.

package/templates/routers/GEMINI.md

@@ -2,11 +2,13 @@
 
 This is the first file Gemini CLI reads when working in this VortEX instance.
 
-## Route to unified entry
+## Shared rules (required — auto-loaded)
 
-Read [`AGENT.md`](./AGENT.md) first — it is the single source of truth for how this instance behaves.
+The rules shared by every agent in this instance live in `AI-RULES.md`, imported here so Gemini CLI loads it automatically at launch:
 
-This `GEMINI.md` holds only Gemini-specific supplements. For everything else, refer to `AGENT.md`.
+@AI-RULES.md
+
+This `GEMINI.md` holds only Gemini-specific supplements; everything shared is in `AI-RULES.md` (above).
 
 ## Gemini-specific config
 

package/dist/catch-up-ZQN7HMMN.js

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

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

@@ -1 +0,0 @@
-{"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/templates/routers/AGENT.md

@@ -1,93 +0,0 @@
----
-type: agent-entry
-status: active
----
-
-# VortEX Instance — Multi-Agent Personal AI Work OS
-
-> A vortex absorbing context, an executable runtime running it through agents.
-
-This is the unified entry point for every agent working in this instance (Claude Code, Codex CLI, Gemini CLI, Cursor). The per-agent files (`CLAUDE.md`, `AGENTS.md`, `CODEX.md`, `GEMINI.md`, `.cursorrules`) all route here — this file is the single source of truth.
-
-This instance was created from the `@vortex-os/base` framework. The framework code lives in `node_modules/@vortex-os/`; you do not edit it. You work in `data/` — your own content — and use the `vortex` CLI and the `/`-commands it installs.
-
-## First thing to check
-
-If `data/_memory/user_profile.md` is missing, this instance has not been set up yet. Run:
-
-```
-npx vortex init --name "<your name>" --role "<your role>" --task "<what you're working on>"
-```
-
-`init` creates a user-profile memory, today's first worklog, the agent slash-commands, and wires the session hooks. Everything after that grows as you work.
-
-## How VortEX behaves by default — auto the plumbing, propose the prose
-
-Operating principle: **auto-maintain the operational memory; propose changes to the knowledge base.** You should never have to learn commands to get value — the records that make recall smarter accumulate on their own, while you keep full control over your own topic documentation.
-
-**Auto (no prompt — append-only operational records; *show, don't ask*):**
-- **Session start.** Run the start ritual: if a sync remote is configured, `git pull` (report conflicts, never auto-resolve); detect the environment if one is configured; backfill any worklog missing from prior sessions; report status (recent work, what's in progress, the time). Where the `SessionStart` hook is configured this runs automatically; otherwise perform it as the first action of the session.
-- **Worklog.** As a work unit completes — and at session wind-down ("that's it for today", "wrap up") — ensure today's worklog exists and append the work. The agent is the primary path; the `SessionEnd` hook is the net.
-- **Decisions.** When the user makes a *substantive* decision ("let's go with X"), record it in the Decision Log. Real decisions, not casual asides.
-- **Ambient recall** (read-only). When the user references earlier work, run `/recall <the reference>` and weave a confident hit into one sentence. One nudge, not a list; drop it if waved off.
-
-These are **append-only and transparent**: do them without a yes/no prompt, but surface a brief, non-blocking note so the user always sees what was recorded. Everything lands in git and is reversible; disable any of them via `.agent/vortex.json` (`autoRecord.*`). `git push` stays **explicit**, never automatic.
-
-**Propose (ask first — the one place friction is intentional):**
-- **Knowledge-base documentation.** Changes to the user's topic documentation (the `data/<topic>/` tree and hubs) are **proposed, never auto-written**: "you've done X, Y, Z on this — update the existing doc, or create a new folder?" The user owns the shape of their knowledge base; the agent never silently restructures it.
-
-The line is technical: **append-only operational logs are safe to auto-write; structural or content changes to the knowledge base are proposed.**
-
-## Working style
-
-**Explain simply and briefly — assume the user is not an IT expert.** Default to plain language. Lead with the conclusion. Keep ordinary replies short (a few lines, at most a few bullets); add tables/code only when they earn their place. Unpack any unavoidable technical term in a line or with a plain analogy.
-
-**Ask one decision at a time.** When you need the user to decide, ask a single question and wait — do not stack several at once. Only batch when the choices are genuinely independent.
-
-**Match reasoning effort to the task.** Don't over-reason trivial asks — a status check, a one-line edit, a lookup; don't under-reason heavy ones — architecture design, multi-file refactors, large debugging or migration, broad reviews. If the host exposes a tunable reasoning/thinking level and the task ahead clearly needs a different one than the session is set for, recommend the change — but rarely: only at a real boundary (a sizable task's start, a major topic shift, a substantial new directive), one or two times across a long session, never per question.
-
-## The `data/` layout
-
-Your content lives under `data/`. Each category answers a different question:
-
-| Category | Question it answers |
-|---|---|
-| `worklog/` | "What happened today?" — chronological, one entry per day (`YYYY/MM/YYYY-MM-DD-keyword.md`). |
-| `decision-log/` | "Why did we choose X over Y?" — per-decision record with context + alternatives. |
-| `_memory/` | "What rule or fact must survive every session?" — curated facts reloaded each session start. |
-| `runbooks/` | "What is the procedure when X breaks?" — repeatable steps with `last_tested` aging. |
-| `hubs/` | "Where do I find everything about topic Z?" — a cross-cut landing page; grows organically once 3+ categories accumulate on the same topic. |
-| `inbox/` | "Where does an unfiled note land before I sort it?" |
-
-A typical day flows from short-lived capture (worklog) into longer-lived artifacts (decision-log, runbook, memory, hub). These are common promotion patterns, not required flows.
-
-## Commands you'll use
-
-These slash-commands are installed into `.claude/commands/` by `vortex init` (the agent runs the underlying `vortex` CLI and presents the result):
-
-| Command | What it does |
-|---|---|
-| `/vortex` | Instance operations: `init`, `status`, `import`, `doctor`, `help`. |
-| `/session-start` | Start-of-session report — recent work, current counts, the time. |
-| `/log <section>` | Append a section to today's worklog (creates it if needed). |
-| `/decision <slug> <title>` | Create a new Decision Log entry from the template. |
-| `/recall <query>` | Semantic search over your memories and past sessions. *(Only when the optional `@vortex-os/memory-extended` add-on is installed.)* |
-| `/agenda` | "What should I focus on?" — synthesizes open tasks, decisions, recent activity. |
-| `/reindex [dir]` | Regenerate `_INDEX.md` for a category (or all). Idempotent. |
-
-You can also run any of these directly: `npx vortex <command> [args]`.
-
-## Optional add-ons
-
-- **`@vortex-os/memory-extended`** — semantic recall over memories and past conversation sessions. Install alongside this instance to light up `/recall`; without it, everything else works and `/recall` is simply absent.
-
-## Agent routing
-
-| Agent | Entry | Shared config | Dedicated config |
-|---|---|---|---|
-| Claude Code | `CLAUDE.md` → `AGENT.md` | `.agent/` | `.claude/` |
-| Codex CLI | `AGENTS.md` → `AGENT.md` (Codex auto-loads `AGENTS.md`; `CODEX.md` is legacy/manual) | `.agent/` | `.codex/` |
-| Gemini CLI | `GEMINI.md` → `AGENT.md` | `.agent/` | `.gemini/` |
-| Cursor | `.cursorrules` → `AGENT.md` | `.agent/` | `.cursor/` |
-
-Per-agent files contain only agent-specific supplements. System-wide rules belong in this file.

package/templates/routers/CODEX.md

@@ -1,16 +0,0 @@
-# CODEX.md
-
-NOTE: Codex CLI auto-loads `AGENTS.md`, not this file. The auto-load entry for
-Codex is `AGENTS.md` (which routes to `AGENT.md`). This `CODEX.md` is a manual /
-legacy supplement — read it only when explicitly pointed here.
-
-## Route to unified entry
-
-Read [`AGENT.md`](./AGENT.md) first — it is the single source of truth for how this instance behaves.
-
-This `CODEX.md` holds only Codex-specific supplements. For everything else, refer to `AGENT.md`.
-
-## Codex-specific config
-
-- Dedicated dir: `.codex/`
-- Shared dir: `.agent/`