@vortex-os/base 0.2.3 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vortex-os/base",
-  "version": "0.2.3",
+  "version": "0.4.0",
   "description": "Base entry point for VortEX — a Multi-Agent Personal AI Work OS framework",
   "license": "MIT",
   "author": "vortex-os-project",
@@ -31,6 +31,9 @@
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "vortex": "./bin/vortex.mjs"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -39,11 +42,14 @@
   },
   "files": [
     "dist",
+    "bin",
+    "templates",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup --config tsup.config.ts",
+    "prepare-assets": "node scripts/prepare-assets.mjs",
+    "build": "npm run prepare-assets && tsup --config tsup.config.ts",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {

package/templates/commands/agenda.md

@@ -0,0 +1,15 @@
+---
+description: What should I focus on? Synthesizes open tasks, decisions, and recent activity.
+allowed-tools: Bash(npx vortex:*)
+---
+Show the user what to work on, synthesized from their existing records.
+
+1. From the instance root, run: `npx vortex agenda`
+2. Parse the JSON: `openTasks[]`, `openDecisions[]`, `nextUp[]`, `lastWorklog`,
+   `isEmpty`, `nothingOpen`.
+3. Present plainly — never dump raw JSON:
+   - `isEmpty` → it's a fresh instance; nudge them to just start working (a
+     worklog grows on its own; nothing to set up).
+   - `nothingOpen` → say they're clear, and mention the last activity.
+   - Otherwise → a short "today" view (≤8 lines): open tasks first, then active
+     decisions, then what's queued next (`nextUp`).

package/templates/commands/curate.md

@@ -0,0 +1,48 @@
+---
+description: Propose capturing the current work into a knowledge-base document (you decide, never auto-written)
+allowed-tools: Bash(npx vortex:*)
+---
+Offer to capture the user's accumulated work on the CURRENT topic into a
+document — only when it is genuinely worth keeping, and only with the user's
+explicit yes.
+
+INVARIANTS (never break these):
+- NEVER auto-write. Always ask the user before writing anything.
+- ASK before accept — a write happens only after the user says yes.
+- DOCUMENTS only. No hub files, no `_*` / system directories
+  (worklog, decision-log, runbooks, hubs, _memory, _templates, _proactive-curator).
+- No whole-file replace. Only `create-file` (new file) or `append-section`
+  (add a section to an EXISTING file). Never overwrite an existing file.
+- ALWAYS go through the CLI validate/write path below — never write files yourself.
+
+THROTTLE: propose at a TOPIC BOUNDARY when substantial work on ONE topic has
+accumulated — not every turn. If the user waved off curation earlier this
+session, drop it and stay silent.
+
+Steps:
+1. Decide continuation vs new. From the instance root run:
+   `npx vortex curate-candidates`
+   Parse `candidates[]` (each has `relpath`, `topic`, `tags`). If the current
+   work matches an existing document's topic/tags → propose APPENDING to it
+   (`append-section`). Otherwise → propose a NEW file (`create-file`).
+2. Build the proposal payload (JSON):
+   - create-file:    `{ "action":"create-file", "topic":"<1-3 words>",
+                        "targetRelPath":"<data-relative FOLDER>",
+                        "filename":"<slug>.md", "body":"<full document>" }`
+   - append-section: `{ "action":"append-section", "topic":"<1-3 words>",
+                        "targetRelPath":"<data-relative EXISTING file>",
+                        "sectionHeader":"<heading>", "body":"<section text>" }`
+3. (Optional) Dry-check it — writes nothing:
+   `npx vortex curate-preview --payload '<json>'`
+   If `previouslyDeclined` is true → the user already declined this exact
+   proposal; do NOT re-propose it. Stay silent.
+4. Ask the user ONCE, plainly:
+   "Want me to capture this? **new doc** at `<path>`, or **append** to
+   `<existing>`?" — one question, their call.
+5. On YES:  `npx vortex curate-accept  --payload '<json>'`  (writes via the
+   safe path; refuses to overwrite). Then tell them where it landed.
+   On NO:   `npx vortex curate-decline --payload '<json>'`  (suppresses this
+   proposal for 30 days). Then move on.
+
+Keep it light. This is an offer, not a report — one short proposal, never a wall
+of text, never a second ask if they declined.

package/templates/commands/recall.md

@@ -0,0 +1,17 @@
+---
+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).

package/templates/config/vortex.json

@@ -0,0 +1,10 @@
+{
+  "autoRecord": {
+    "sessionStart": true,
+    "worklog": true,
+    "decision": true,
+    "ambientRecall": true,
+    "archive": true
+  },
+  "environments": []
+}

package/templates/routers/.cursorrules

@@ -0,0 +1,14 @@
+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.
+
+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.
+
+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
+its slash-commands (run `npx vortex --list` to see them).

package/templates/routers/AGENT.md

@@ -0,0 +1,93 @@
+---
+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/AGENTS.md

@@ -0,0 +1,18 @@
+# AGENTS.md
+
+This is the file Codex CLI (and other `AGENTS.md`-aware agents) auto-loads when
+working in this VortEX instance.
+
+## Route to unified entry
+
+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`.
+
+## Working in a VortEX instance (summary)
+
+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.

package/templates/routers/CLAUDE.md

@@ -0,0 +1,20 @@
+# CLAUDE.md
+
+This is the first file Claude Code reads when working in this VortEX instance.
+
+## Route to unified entry
+
+Read [`AGENT.md`](./AGENT.md) first — it is the single source of truth for how this instance behaves.
+
+This `CLAUDE.md` holds only Claude Code-specific supplements. For everything else, refer to `AGENT.md`.
+
+## Claude Code-specific config
+
+- Dedicated dir: `.claude/`
+- Shared dir: `.agent/`
+
+`.claude/settings.json` and `.claude/commands/` are populated by `vortex init` — it wires the SessionStart / SessionEnd hooks (`npx --no-install -p @vortex-os/base vortex session-start` / `… session-end`) and installs the agent-mediated slash-commands.
+
+## 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.

package/templates/routers/CODEX.md

@@ -0,0 +1,16 @@
+# 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/`

package/templates/routers/GEMINI.md

@@ -0,0 +1,14 @@
+# GEMINI.md
+
+This is the first file Gemini CLI reads when working in this VortEX instance.
+
+## Route to unified entry
+
+Read [`AGENT.md`](./AGENT.md) first — it is the single source of truth for how this instance behaves.
+
+This `GEMINI.md` holds only Gemini-specific supplements. For everything else, refer to `AGENT.md`.
+
+## Gemini-specific config
+
+- Dedicated dir: `.gemini/`
+- Shared dir: `.agent/`