invoket 0.1.9 → 0.2.0

package/CLAUDE.md

@@ -0,0 +1,77 @@
+# CLAUDE.md
+
+Add reusable commands to `tasks.ts`. invoket gives them typed args, `--help`, and error handling.
+
+Use invoket when a command will be reused. Write a raw script for throwaway one-offs.
+
+## Task skeleton
+
+```typescript
+import { Context } from "invoket/context";
+
+export class Tasks {
+  /** Description (required — no JSDoc = not discovered) */
+  async taskName(c: Context, required: string, optional: number = 1) {}
+}
+```
+
+`async` + JSDoc + `c: Context` first param. `_prefix` = private.
+
+## Types → CLI
+
+`string` as-is, `number` rejects NaN, `boolean` accepts `true/false/1/0/--flag/--no-flag`, `"a" | "b"` validates against the listed choices, `Interface` and `Record` expect JSON string, `type[]` expects JSON array, `...args: string[]` collects remaining, `= default` and `| null` make optional.
+
+## Flags
+
+Auto: `--paramName`. For short flags add `@flag` in JSDoc:
+
+```typescript
+/** @flag env -e --environment */
+async deploy(c: Context, env: string) {}
+```
+
+Unknown flags and extra positional args are errors. Negative numbers work as flag values (`--count -3`). Use `--` to pass remaining args literally (including `-h`).
+
+## Namespaces
+
+```typescript
+class Db {
+  /** Migrate */
+  async migrate(c: Context, direction: string = "up") {}
+}
+export class Tasks {
+  db = new Db();  // invt db:migrate up
+}
+```
+
+## Context
+
+```typescript
+await c.run(cmd);                        // throw on failure
+await c.run(cmd, { warn: true });        // don't throw
+const { stdout } = await c.run(cmd, { hide: true }); // capture
+await c.run(cmd, { stream: true });      // real-time output
+await c.run(cmd, { echo: true });        // print command first
+await c.sudo(cmd);                       // sudo prefix
+for await (const _ of c.cd(dir)) { }    // temp cd
+```
+
+Result: `{ stdout, stderr, code, ok, failed }`. Failure throws `CommandError` with `.result`; the command's output is printed before the throw (with `hide`, stderr is folded into the error message).
+
+Commands run via `sh -c` and interpolations are not escaped — single-quote values that may contain spaces or shell characters: `` c.run(`git commit -m '${msg.replace(/'/g, `'\\''`)}'`) ``.
+
+`invt` finds `tasks.ts` in the current directory or any parent, and runs commands relative to where `tasks.ts` lives.
+
+## Agent batteries
+
+```typescript
+import { Ctx, Session } from "invoket/agent";
+export class Tasks {
+  ctx = new Ctx();        // invt ctx:set/get/search/decide/decisions/dump — project memory
+  session = new Session(); // invt session:start — SessionStart hook body (skills sync + memory inject)
+}
+```
+
+`.ctx.jsonl` is committed truth; `.ctx.db` is a rebuildable cache (gitignore it). Record facts (`ctx:set key value...`) and decisions (`ctx:decide subject decision rationale...`) as you work.
+
+Memory is for **application projects only**. Library and tool repos stay atomic — their agent interface is the skills they ship, not a memory store. Don't retrofit `Ctx`/`Session` hooks into a library repo.

package/README.md

@@ -25,16 +25,32 @@ You could. But then you write arg parsing, help text, and error handling every t
 
 One script solves one problem. A `tasks.ts` file is a project's command centre.
 
+## Do you need invoket?
+
+Maybe not. invoket's pitch — write a method, get arg parsing, help, and error handling for free — amortizes *authoring* effort. If an AI agent writes your commands, authoring is already free, and a bespoke `cli.ts` beside the code it operates on works just as well.
+
+What every project still needs is an **inventory**: one well-known place where commands live, so the next session — human or agent — finds the existing command instead of writing a duplicate. invoket provides that, but so does a cheaper convention: `package.json` scripts, a justfile, or a paragraph in CLAUDE.md saying "commands live as `cli.ts` beside the code they operate on; check for an existing one before writing a new one".
+
+invoket earns its keep when a human runs operational commands often enough to want one consistent grammar (`invt db:migrate up`) and a single `--help` that lists everything. If that's not you, a documented convention is enough.
+
 ## Installation
 
 ```bash
-bun add -d invoket    # Add to project
-bun link invoket      # Or link globally for development
+bun add -d invoket     # Add to project (use bunx invt to run)
+bun add -g invoket     # Or install globally (invt available on PATH)
 ```
 
+Then scaffold your project:
+
+```bash
+bunx invt --init       # Creates tasks.ts and CLAUDE.md
+```
+
+`--init` creates a starter `tasks.ts` and copies the `CLAUDE.md` reference card into your project so AI agents know how to write tasks.
+
 ## Quick Start
 
-Create `tasks.ts`:
+Edit `tasks.ts`:
 
 ```typescript
 import { Context } from "invoket/context";
@@ -117,6 +133,7 @@ invt db.seed          # dot separator also works
 | `name: string = "default"` | `[name]` (optional) | `hello` |
 | `count: number` | `<count>` | `42` |
 | `force: boolean` | `<force>` | `true`, `1`, `false`, `0` |
+| `env: "dev" \| "prod"` | `<env>` (validated choice) | `dev` |
 | `params: SomeInterface` | `<params>` | `'{"key": "value"}'` |
 | `items: string[]` | `<items>` | `'["a", "b"]'` |
 | `...args: string[]` | `[args...]` (variadic) | `a b c` |
@@ -145,6 +162,8 @@ invt install -- --not-a-flag           # -- stops flag parsing
 
 Flags and positional args can be freely mixed in any order.
 
+Arguments are strict: an unknown flag or an extra positional argument is an error, not silently ignored — a typo'd `--cuont 3` fails loudly instead of running with the wrong count. Negative numbers are treated as values, so `--count -3` works.
+
 ### CLI Flags
 
 | Flag | Description |
@@ -153,6 +172,11 @@ Flags and positional args can be freely mixed in any order.
 | `<task> -h` | Help for a specific task |
 | `-l`, `--list` | List tasks |
 | `--version` | Show version |
+| `--init` | Scaffold `tasks.ts` and `CLAUDE.md` |
+
+## Finding tasks.ts
+
+`invt` looks for `tasks.ts` in the current directory, then walks up parent directories until it finds one (like `make` or `just`). Commands run relative to the directory containing `tasks.ts`, so `invt build` behaves the same from anywhere in the project.
 
 ## Context API
 
@@ -197,6 +221,15 @@ interface RunResult {
 }
 ```
 
+### Quoting
+
+Commands run via `sh -c`, and interpolated values are **not** escaped. Wrap values that may contain spaces or shell characters in single quotes, escaping any embedded single quotes:
+
+```typescript
+const safe = message.replace(/'/g, `'\\''`);
+await c.run(`git commit -m '${safe}'`);
+```
+
 ### Error Handling
 
 Failed commands throw `CommandError`:
@@ -216,6 +249,8 @@ try {
 
 Use `{ warn: true }` to suppress throws and inspect the result instead.
 
+A failing command's output is always printed before the throw, so errors are never silent. With `{ hide: true }` the captured stderr is folded into the `CommandError` message instead.
+
 ## Private Methods
 
 Prefix with `_` to hide from CLI:
@@ -253,7 +288,8 @@ async setup(c: Context) {
 async ship(c: Context, message: string) {
   const { stdout } = await c.run("git branch --show-current", { hide: true });
   await c.run("git add -A");
-  await c.run(`git commit -m "${message}"`);
+  const safe = message.replace(/'/g, `'\\''`);
+  await c.run(`git commit -m '${safe}'`);
   await c.run(`git push -u origin ${stdout.trim()}`);
 }
 ```
@@ -304,6 +340,47 @@ AI agents like Claude Code have built-in tools for searching files, reading code
 
 invoket lets you build a **structured, queryable project knowledge base** that agents can read and write through the same CLI interface humans use. Bun's built-in SQLite makes this trivial — no external database, no setup, just a `.ctx.db` file that travels with the project.
 
+### Batteries included — `invoket/agent`
+
+The pattern below ships ready-made. Two lines in `tasks.ts`:
+
+```typescript
+import { Ctx, Session } from "invoket/agent";
+
+export class Tasks {
+  ctx = new Ctx();        // invt ctx:set / get / search / decide / decisions / dump
+  session = new Session(); // invt session:start / skills
+}
+```
+
+`Ctx` stores facts and decisions in `.ctx.db` (a rebuildable cache — gitignore it) and `.ctx.jsonl` (the committed source of truth — diffable, merge-friendly; a fresh clone or a pulled change is replayed automatically). `Session.start` is built to be a Claude Code **SessionStart hook** body: it syncs `.claude/skills/` from any dependency that ships skills, rebuilds the cache, and prints a bounded context payload to stdout — which the hook injects into the model's context on startup, resume, `/clear`, and compaction:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.sh" }]
+      }
+    ]
+  }
+}
+```
+
+```sh
+#!/bin/sh
+cd "${CLAUDE_PROJECT_DIR:-$(dirname "$0")/../..}" || exit 0
+[ -d node_modules ] || bun install >/dev/null 2>&1 || true
+exec bun node_modules/invoket/src/cli.ts session:start
+```
+
+`bunx create-blueshed my-app` scaffolds a Bun project with all of this wired — delta + railroad + invoket, skills sync, hook, seeded memory (see `packages/create-blueshed`).
+
+**Scope: memory belongs to applications.** Library packages stay atomic — their agent interface is the skills they ship, versioned with the code. Tools carry their own process (their feedback loop *is* the memory). Only an application accumulates project-specific facts and decisions worth a store; that's where `Ctx` and the SessionStart hook go.
+
+Prefer your own schema? The hand-rolled version of the same pattern:
+
 ### Project context — a SQLite-backed knowledge base
 
 ```typescript

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "invoket",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "type": "module",
   "description": "TypeScript task runner for Bun - uses type annotations to parse CLI arguments",
   "bin": {
     "invt": "./src/cli.ts"
   },
   "exports": {
-    "./context": "./src/context.ts"
+    "./context": "./src/context.ts",
+    "./agent": "./src/agent.ts"
   },
   "files": [
-    "src"
+    "src",
+    "CLAUDE.md"
   ],
   "keywords": [
     "task-runner",

package/src/agent.ts

@@ -0,0 +1,444 @@
+/**
+ * invoket/agent — batteries for agent-assisted projects.
+ *
+ * Two namespace classes for a project's tasks.ts:
+ *
+ *   import { Ctx, Session } from "invoket/agent";
+ *   export class Tasks {
+ *     ctx = new Ctx();        // invt ctx:set / get / search / decide / decisions / dump / inject
+ *     session = new Session(); // invt session:start / skills
+ *   }
+ *
+ * Ctx is a SQLite-backed project knowledge base (the pattern from the README,
+ * productionized). Facts and decisions live in `.ctx.db` (a rebuildable cache,
+ * gitignore it) and `.ctx.jsonl` (the committed source of truth — diffable,
+ * merge-friendly). Every mutation rewrites the JSONL; opening the database
+ * replays the JSONL whenever its content hash differs from the one recorded
+ * at the last sync, so a fresh clone or a pulled change is picked up
+ * automatically.
+ *
+ * Session wires a project for agent sessions. `session:start` is built to be
+ * a Claude Code SessionStart hook body: it syncs `.claude/skills/` from any
+ * dependency that ships skills, rebuilds the context cache, and prints a
+ * bounded context payload to stdout (a SessionStart hook's stdout becomes
+ * model context; the harness caps it at 10k characters, so the payload
+ * targets well under that).
+ *
+ * All paths resolve from `c.cwd`, which the CLI anchors to the directory
+ * containing tasks.ts.
+ */
+import { Database } from "bun:sqlite";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "fs";
+import { join } from "path";
+import { Context } from "./context";
+
+/** Project knowledge base — facts and decisions agents query and append to */
+export class Ctx {
+  /** Store a key-value fact about the project */
+  async set(c: Context, key: string, ...value: string[]) {
+    ctxSet(c.cwd, key, value.join(" "));
+    console.log(`Set: ${key}`);
+  }
+
+  /** Retrieve a fact by key */
+  async get(c: Context, key: string) {
+    const fact = ctxGet(c.cwd, key);
+    if (!fact) {
+      console.error(`Not found: ${key}`);
+      process.exitCode = 1;
+      return;
+    }
+    console.log(`${fact.value}  (${fact.updated_at})`);
+  }
+
+  /** Search facts and decisions by keyword */
+  async search(c: Context, ...terms: string[]) {
+    const hits = ctxSearch(c.cwd, terms.join(" "));
+    for (const h of hits) console.log(h);
+    if (hits.length === 0) console.log("No matches.");
+  }
+
+  /** Record a decision with its rationale */
+  async decide(c: Context, subject: string, decision: string, ...rationale: string[]) {
+    const id = ctxDecide(c.cwd, subject, decision, rationale.join(" "));
+    console.log(`Recorded decision #${id}: ${subject}`);
+  }
+
+  /** List active decisions, newest first */
+  async decisions(c: Context) {
+    const rows = ctxDecisions(c.cwd);
+    for (const r of rows) {
+      console.log(`#${r.id} ${r.subject}: ${r.decision}`);
+      if (r.rationale) console.log(`   ${r.rationale}`);
+    }
+    if (rows.length === 0) console.log("No decisions recorded.");
+  }
+
+  /** Dump all facts and active decisions as JSON */
+  async dump(c: Context) {
+    console.log(JSON.stringify(ctxDump(c.cwd), null, 2));
+  }
+
+  /** Print the bounded context block used by session:start */
+  async inject(c: Context, budget: number = 6000) {
+    console.log(buildMemoryBlock(c.cwd, budget));
+  }
+}
+
+/** Session bring-up for agent-assisted projects */
+export class Session {
+  /** Sync skills, rebuild context, print the session payload (SessionStart hook body) */
+  async start(c: Context) {
+    console.log(buildSessionPayload(c.cwd));
+  }
+
+  /** Sync .claude/skills/ from dependencies that ship skills */
+  async skills(c: Context) {
+    const synced = syncSkills(c.cwd);
+    if (synced.length === 0) {
+      console.log("No dependency skills found (is node_modules installed?)");
+      return;
+    }
+    for (const s of synced) console.log(`Synced ${s.name} (from ${s.from})`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Storage: SQLite cache (.ctx.db) + committed JSONL source of truth (.ctx.jsonl)
+// ---------------------------------------------------------------------------
+
+export interface Fact {
+  key: string;
+  value: string;
+  updated_at: string;
+}
+
+export interface Decision {
+  id: number;
+  subject: string;
+  decision: string;
+  rationale: string;
+  status: string;
+  created_at: string;
+}
+
+const DB_FILE = ".ctx.db";
+const JSONL_FILE = ".ctx.jsonl";
+
+function openDb(dir: string): Database {
+  const db = new Database(join(dir, DB_FILE), { create: true });
+  db.run(`CREATE TABLE IF NOT EXISTS context (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL,
+    updated_at TEXT DEFAULT (datetime('now'))
+  )`);
+  db.run(`CREATE TABLE IF NOT EXISTS decisions (
+    id INTEGER PRIMARY KEY,
+    subject TEXT NOT NULL,
+    decision TEXT NOT NULL,
+    rationale TEXT,
+    status TEXT DEFAULT 'active',
+    created_at TEXT DEFAULT (datetime('now'))
+  )`);
+  db.run(`CREATE TABLE IF NOT EXISTS ctx_meta (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+  )`);
+  replayJsonlIfChanged(dir, db);
+  return db;
+}
+
+// The JSONL is the source of truth: replay it into the cache whenever its
+// content differs from what the cache last saw (fresh clone, pulled change,
+// hand edit). Hash comparison, not mtime — mtimes lie across clones.
+function replayJsonlIfChanged(dir: string, db: Database): void {
+  const jsonlPath = join(dir, JSONL_FILE);
+  if (!existsSync(jsonlPath)) return;
+  const text = readFileSync(jsonlPath, "utf8");
+  const hash = String(Bun.hash(text));
+  const seen = db
+    .query("SELECT value FROM ctx_meta WHERE key = 'jsonl_hash'")
+    .get() as { value: string } | null;
+  if (seen?.value === hash) return;
+
+  db.run("DELETE FROM context");
+  db.run("DELETE FROM decisions");
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    let rec: any;
+    try {
+      rec = JSON.parse(line);
+    } catch {
+      continue; // a corrupt line shouldn't take the whole store down
+    }
+    if (rec.t === "fact" && rec.key) {
+      db.run(
+        "INSERT OR REPLACE INTO context (key, value, updated_at) VALUES (?, ?, ?)",
+        [rec.key, rec.value ?? "", rec.updated_at ?? new Date().toISOString()],
+      );
+    } else if (rec.t === "decision" && rec.subject) {
+      db.run(
+        "INSERT INTO decisions (id, subject, decision, rationale, status, created_at) VALUES (?, ?, ?, ?, ?, ?)",
+        [
+          rec.id ?? null,
+          rec.subject,
+          rec.decision ?? "",
+          rec.rationale ?? "",
+          rec.status ?? "active",
+          rec.created_at ?? new Date().toISOString(),
+        ],
+      );
+    }
+  }
+  db.run(
+    "INSERT OR REPLACE INTO ctx_meta (key, value) VALUES ('jsonl_hash', ?)",
+    [hash],
+  );
+}
+
+// Mutations rewrite the whole JSONL — it stays small, ordering stays
+// deterministic (facts by key, then decisions by id), diffs stay readable.
+function saveJsonl(dir: string, db: Database): void {
+  const facts = db
+    .query("SELECT key, value, updated_at FROM context ORDER BY key")
+    .all() as Fact[];
+  const decisions = db
+    .query(
+      "SELECT id, subject, decision, rationale, status, created_at FROM decisions ORDER BY id",
+    )
+    .all() as Decision[];
+  const lines: string[] = [];
+  for (const f of facts) lines.push(JSON.stringify({ t: "fact", ...f }));
+  for (const d of decisions) lines.push(JSON.stringify({ t: "decision", ...d }));
+  const text = lines.join("\n") + (lines.length ? "\n" : "");
+  writeFileSync(join(dir, JSONL_FILE), text);
+  db.run(
+    "INSERT OR REPLACE INTO ctx_meta (key, value) VALUES ('jsonl_hash', ?)",
+    [String(Bun.hash(text))],
+  );
+}
+
+export function ctxSet(dir: string, key: string, value: string): void {
+  const db = openDb(dir);
+  db.run(
+    "INSERT OR REPLACE INTO context (key, value, updated_at) VALUES (?, ?, datetime('now'))",
+    [key, value],
+  );
+  saveJsonl(dir, db);
+  db.close();
+}
+
+export function ctxGet(dir: string, key: string): Fact | null {
+  const db = openDb(dir);
+  const row = db
+    .query("SELECT key, value, updated_at FROM context WHERE key = ?")
+    .get(key) as Fact | null;
+  db.close();
+  return row;
+}
+
+export function ctxSearch(dir: string, term: string): string[] {
+  const db = openDb(dir);
+  const pattern = `%${term}%`;
+  const facts = db
+    .query("SELECT key, value FROM context WHERE key LIKE ? OR value LIKE ? ORDER BY key")
+    .all(pattern, pattern) as Fact[];
+  const decisions = db
+    .query(
+      "SELECT id, subject, decision, rationale FROM decisions WHERE status = 'active' AND (subject LIKE ? OR decision LIKE ? OR rationale LIKE ?) ORDER BY id",
+    )
+    .all(pattern, pattern, pattern) as Decision[];
+  db.close();
+  return [
+    ...facts.map((f) => `${f.key}: ${f.value}`),
+    ...decisions.map((d) => `#${d.id} ${d.subject}: ${d.decision}`),
+  ];
+}
+
+export function ctxDecide(
+  dir: string,
+  subject: string,
+  decision: string,
+  rationale: string,
+): number {
+  const db = openDb(dir);
+  db.run(
+    "INSERT INTO decisions (subject, decision, rationale) VALUES (?, ?, ?)",
+    [subject, decision, rationale],
+  );
+  const id = (
+    db.query("SELECT last_insert_rowid() AS id").get() as { id: number }
+  ).id;
+  saveJsonl(dir, db);
+  db.close();
+  return id;
+}
+
+export function ctxDecisions(dir: string): Decision[] {
+  const db = openDb(dir);
+  const rows = db
+    .query(
+      "SELECT id, subject, decision, rationale, status, created_at FROM decisions WHERE status = 'active' ORDER BY id DESC",
+    )
+    .all() as Decision[];
+  db.close();
+  return rows;
+}
+
+export function ctxDump(dir: string): { facts: Fact[]; decisions: Decision[] } {
+  const db = openDb(dir);
+  const facts = db
+    .query("SELECT key, value, updated_at FROM context ORDER BY key")
+    .all() as Fact[];
+  const decisions = db
+    .query(
+      "SELECT id, subject, decision, rationale, status, created_at FROM decisions WHERE status = 'active' ORDER BY id DESC",
+    )
+    .all() as Decision[];
+  db.close();
+  return { facts, decisions };
+}
+
+// ---------------------------------------------------------------------------
+// Skills sync — copy .claude/skills/* from any dependency that ships them
+// ---------------------------------------------------------------------------
+
+export interface SyncedSkill {
+  name: string;
+  from: string;
+}
+
+export function syncSkills(dir: string): SyncedSkill[] {
+  const pkgPath = join(dir, "package.json");
+  if (!existsSync(pkgPath)) return [];
+  let pkg: any;
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  } catch {
+    return [];
+  }
+  const deps = Object.keys({
+    ...pkg.dependencies,
+    ...pkg.devDependencies,
+  });
+  const synced: SyncedSkill[] = [];
+  for (const dep of deps) {
+    const skillsDir = join(dir, "node_modules", dep, ".claude", "skills");
+    if (!existsSync(skillsDir)) continue;
+    for (const name of readdirSync(skillsDir)) {
+      const src = join(skillsDir, name);
+      const dest = join(dir, ".claude", "skills", name);
+      mkdirSync(join(dir, ".claude", "skills"), { recursive: true });
+      rmSync(dest, { recursive: true, force: true });
+      cpSync(src, dest, { recursive: true });
+      synced.push({ name, from: dep });
+    }
+  }
+  return synced;
+}
+
+// ---------------------------------------------------------------------------
+// Session payload — what a SessionStart hook prints into model context
+// ---------------------------------------------------------------------------
+
+const PAYLOAD_BUDGET = 9000; // the harness caps hook stdout at 10k chars
+const FACT_VALUE_CAP = 300;
+
+export function buildMemoryBlock(dir: string, budget: number = 6000): string {
+  const { facts, decisions } = ctxDump(dir);
+  const lines: string[] = ["## Project memory"];
+  lines.push(
+    "Record what you learn as you work: `invt ctx:set <key> <value...>` for facts,",
+    "`invt ctx:decide <subject> <decision> <rationale...>` for decisions.",
+    "Query with `invt ctx:get|search|decisions|dump`.",
+    "",
+  );
+  if (facts.length === 0 && decisions.length === 0) {
+    lines.push("(empty — this project has no recorded memory yet)");
+    return lines.join("\n");
+  }
+  if (facts.length > 0) {
+    lines.push("### Facts");
+    for (const f of facts) {
+      const v =
+        f.value.length > FACT_VALUE_CAP
+          ? f.value.slice(0, FACT_VALUE_CAP) + "…"
+          : f.value;
+      lines.push(`- ${f.key}: ${v}`);
+    }
+    lines.push("");
+  }
+  if (decisions.length > 0) {
+    lines.push("### Decisions (newest first)");
+    let used = lines.join("\n").length;
+    let dropped = 0;
+    for (const d of decisions) {
+      const line = `- #${d.id} ${d.subject}: ${d.decision}${d.rationale ? ` — ${d.rationale}` : ""} (${d.created_at})`;
+      if (used + line.length > budget) {
+        dropped = decisions.length - decisions.indexOf(d);
+        break;
+      }
+      lines.push(line);
+      used += line.length + 1;
+    }
+    if (dropped > 0) {
+      lines.push(`…and ${dropped} older decision(s) — \`invt ctx:decisions\` for all.`);
+    }
+  }
+  return lines.join("\n");
+}
+
+export function buildSessionPayload(dir: string): string {
+  const lines: string[] = ["# Session context (generated by `invt session:start`)", ""];
+
+  // Stack: the project's dependencies with installed versions
+  const pkgPath = join(dir, "package.json");
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+      const deps = Object.keys({ ...pkg.dependencies, ...pkg.devDependencies });
+      const stack: string[] = [];
+      for (const dep of deps) {
+        const depPkgPath = join(dir, "node_modules", dep, "package.json");
+        if (!existsSync(depPkgPath)) continue;
+        try {
+          const depPkg = JSON.parse(readFileSync(depPkgPath, "utf8"));
+          stack.push(`${dep}@${depPkg.version}`);
+        } catch {
+          stack.push(dep);
+        }
+      }
+      if (pkg.name) lines[0] = `# Session context — ${pkg.name} (generated by \`invt session:start\`)`;
+      if (stack.length > 0) lines.push(`Stack: ${stack.join(", ")}`, "");
+    } catch {
+      // unreadable package.json — payload still useful without the stack line
+    }
+  }
+
+  const synced = syncSkills(dir);
+  if (synced.length > 0) {
+    const names = synced.map((s) => `${s.name} (${s.from})`).join(", ");
+    lines.push(
+      `Skills synced into .claude/skills: ${names}.`,
+      "Read the matching skill before writing code against that package — it overrides trained habits.",
+      "",
+    );
+  }
+
+  lines.push(buildMemoryBlock(dir));
+  let payload = lines.join("\n");
+  if (payload.length > PAYLOAD_BUDGET) {
+    payload =
+      payload.slice(0, PAYLOAD_BUDGET) +
+      "\n…(truncated — `invt ctx:dump` for the full store)";
+  }
+  return payload;
+}

package/src/cli.ts

@@ -1,6 +1,8 @@
 #!/usr/bin/env bun
-import { Context } from "./context";
-import { dirname } from "path";
+import { Context, CommandError } from "./context";
+import { dirname, join } from "path";
+import { existsSync } from "fs";
+import { fileURLToPath } from "url";
 import {
   discoverAllTasks,
   discoverRuntimeNamespaces,
@@ -15,25 +17,41 @@ import {
   showTaskHelp,
 } from "./parser";
 
+// Walk up from startDir looking for tasks.ts (like make/just find their files)
+function findTasksFile(startDir: string): string | null {
+  let dir = startDir;
+  while (true) {
+    const candidate = join(dir, "tasks.ts");
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
 // Main CLI entry point
 async function main() {
   const args = Bun.argv.slice(2);
 
   // --version flag
   if (args[0] === "--version") {
-    const pkgPath = new URL("../package.json", import.meta.url).pathname;
+    const pkgPath = fileURLToPath(new URL("../package.json", import.meta.url));
     const pkg = await Bun.file(pkgPath).json();
     console.log(pkg.version);
     return;
   }
 
-  // Find tasks.ts
-  let tasksPath: string;
-  try {
-    tasksPath = Bun.resolveSync("./tasks.ts", process.cwd());
-  } catch {
-    console.log("No tasks.ts found. Create one to get started:\n");
-    console.log(`import { Context } from "invoket/context";
+  // --init flag: scaffold tasks.ts and CLAUDE.md
+  if (args[0] === "--init") {
+    const cwd = process.cwd();
+
+    const tasksFile = `${cwd}/tasks.ts`;
+    if (existsSync(tasksFile)) {
+      console.log("tasks.ts already exists, skipping.");
+    } else {
+      await Bun.write(
+        tasksFile,
+        `import { Context } from "invoket/context";
 
 export class Tasks {
   /** Say hello */
@@ -41,7 +59,42 @@ export class Tasks {
     console.log("Hello, World!");
   }
 }
-`);
+`,
+      );
+      console.log("Created tasks.ts");
+    }
+
+    const claudeFile = `${cwd}/CLAUDE.md`;
+    const claudeMdPath = fileURLToPath(new URL("../CLAUDE.md", import.meta.url));
+    const claudeMd = await Bun.file(claudeMdPath).text();
+    // First substantive line of the shipped guide doubles as the "already
+    // installed" marker — a mere mention of invoket shouldn't skip the append
+    const marker = claudeMd
+      .split("\n")
+      .map((line) => line.trim())
+      .find((line) => line && !line.startsWith("#"));
+    if (existsSync(claudeFile)) {
+      const existing = await Bun.file(claudeFile).text();
+      if (marker && existing.includes(marker)) {
+        console.log("CLAUDE.md already has invoket section, skipping.");
+      } else {
+        await Bun.write(claudeFile, existing.trimEnd() + "\n\n" + claudeMd);
+        console.log("Appended invoket guide to CLAUDE.md");
+      }
+    } else {
+      await Bun.write(claudeFile, claudeMd);
+      console.log("Created CLAUDE.md");
+    }
+
+    return;
+  }
+
+  // Find tasks.ts in cwd or any parent directory
+  const tasksPath = findTasksFile(process.cwd());
+  if (!tasksPath) {
+    console.error(
+      "No tasks.ts found in this directory or any parent. Run 'invt --init' to get started.",
+    );
     process.exit(1);
   }
 
@@ -51,6 +104,8 @@ export class Tasks {
   const { Tasks } = await import(tasksPath);
   const instance = new Tasks();
   const context = new Context();
+  // Tasks run relative to tasks.ts, wherever invt was invoked from
+  context.cwd = dirname(tasksPath);
 
   // Discover all tasks including namespaced
   const discovered = discoverAllTasks(source);
@@ -105,7 +160,10 @@ export class Tasks {
   const taskArgs = args.slice(1);
 
   // Check if asking for task-specific help: invt hello -h
-  const wantsTaskHelp = taskArgs.includes("-h") || taskArgs.includes("--help");
+  // Anything after -- is a literal task argument, never a help flag
+  const ddIdx = taskArgs.indexOf("--");
+  const beforeDD = ddIdx === -1 ? taskArgs : taskArgs.slice(0, ddIdx);
+  const wantsTaskHelp = beforeDD.includes("-h") || beforeDD.includes("--help");
 
   const { namespace, method: methodName } = parseCommand(command);
 
@@ -156,7 +214,7 @@ export class Tasks {
     // If method exists at runtime but not in source (inherited), allow it
     if (!meta && typeof method === "function") {
       // Inherited method - no type info, treat all args as strings
-      meta = { description: "", params: [] };
+      meta = { description: "", params: [], untyped: true };
     } else if (!meta) {
       console.error(`Unknown task: ${command}`);
       const allTasks = [...discovered.root.keys()];
@@ -181,8 +239,12 @@ export class Tasks {
     return;
   }
 
-  // Filter out help flags from taskArgs before parsing
-  const argsWithoutHelp = taskArgs.filter((a) => a !== "-h" && a !== "--help");
+  // Filter out help flags from taskArgs before parsing (only before --)
+  const notHelp = (a: string) => a !== "-h" && a !== "--help";
+  const argsWithoutHelp =
+    ddIdx === -1
+      ? taskArgs.filter(notHelp)
+      : [...beforeDD.filter(notHelp), ...taskArgs.slice(ddIdx)];
 
   // Parse CLI args into flags and positional
   const parsed = parseCliArgs(argsWithoutHelp);
@@ -190,8 +252,8 @@ export class Tasks {
   // Validate and coerce arguments
   let coercedArgs: unknown[];
 
-  // If no param info (imported namespace), pass all args as strings
-  if (meta.params.length === 0 && argsWithoutHelp.length > 0) {
+  // If no signature info (runtime-discovered method), pass all args as strings
+  if (meta.untyped && argsWithoutHelp.length > 0) {
     coercedArgs = [...parsed.positional];
   } else {
     try {
@@ -208,7 +270,17 @@ export class Tasks {
   try {
     await method.call(thisArg, context, ...coercedArgs);
   } catch (e) {
-    console.error(`Error running "${command}": ${(e as Error).message}`);
+    if (e instanceof CommandError) {
+      // Command output was already written (or is in the message when hidden)
+      console.error(`Error running "${command}": ${e.message}`);
+    } else if (e instanceof Error) {
+      console.error(`Error running "${command}": ${e.message}`);
+      // A bug in the task itself — show where it happened
+      const frames = e.stack?.split("\n").slice(1).join("\n");
+      if (frames) console.error(frames);
+    } else {
+      console.error(`Error running "${command}": ${String(e)}`);
+    }
     process.exit(1);
   }
 }

package/src/context.ts

@@ -79,19 +79,22 @@ export class Context {
       failed: result.exitCode !== 0,
     };
 
-    if (!opts.warn && runResult.failed) {
-      throw new CommandError(
-        `Command failed with exit code ${runResult.code}: ${command}`,
-        runResult,
-      );
-    }
-
-    // When streaming, output already went to terminal; otherwise write captured output
+    // When streaming, output already went to terminal; otherwise write captured
+    // output — before any throw, so a failing command's stderr is never silent
     if (!opts.stream && !opts.hide) {
       if (runResult.stdout) process.stdout.write(runResult.stdout);
       if (runResult.stderr) process.stderr.write(runResult.stderr);
     }
 
+    if (!opts.warn && runResult.failed) {
+      let message = `Command failed with exit code ${runResult.code}: ${command}`;
+      // With hide the output wasn't printed, so surface stderr in the error
+      if (opts.hide && runResult.stderr.trim()) {
+        message += `\n${runResult.stderr.trim()}`;
+      }
+      throw new CommandError(message, runResult);
+    }
+
     return runResult;
   }
 

package/src/parser.ts

@@ -15,11 +15,13 @@ export interface ParamMeta {
   required: boolean;
   isRest: boolean;
   flag?: FlagMeta;
+  choices?: string[]; // from string-literal union types, e.g. "dev" | "prod"
 }
 
 export interface TaskMeta {
   description: string;
   params: ParamMeta[];
+  untyped?: boolean; // discovered at runtime only — no signature info available
 }
 
 // Parsed CLI arguments
@@ -176,9 +178,10 @@ export function parseParams(
     return params;
   }
 
-  // Updated regex to handle union types with null (e.g., string | null)
+  // Handles union types with null (e.g., string | null) and string-literal
+  // unions (e.g., "dev" | "prod"), which become validated string choices
   const paramPattern =
-    /(\w+)\s*:\s*(\w+\[\]|Record<[^>]+>|\{[^}]*\}|string|number|boolean|\w+)(?:\s*\|\s*null)?(?:\s*=\s*[^,)]+)?/g;
+    /(\w+)\s*:\s*((?:"[^"]*"|'[^']*')(?:\s*\|\s*(?:"[^"]*"|'[^']*'))*|\w+\[\]|Record<[^>]+>|\{[^}]*\}|string|number|boolean|\w+)(?:\s*\|\s*null)?(?:\s*=\s*[^,)]+)?/g;
   let paramMatch;
 
   while ((paramMatch = paramPattern.exec(paramsStr)) !== null) {
@@ -187,7 +190,13 @@ export function parseParams(
     const isNullable = fullMatch.includes("| null");
 
     let type: ParamType;
-    if (rawType === "string") {
+    let choices: string[] | undefined;
+    if (rawType.startsWith('"') || rawType.startsWith("'")) {
+      type = "string";
+      choices = [...rawType.matchAll(/"([^"]*)"|'([^']*)'/g)].map(
+        (m) => m[1] ?? m[2],
+      );
+    } else if (rawType === "string") {
       type = "string";
     } else if (rawType === "number") {
       type = "number";
@@ -213,6 +222,7 @@ export function parseParams(
       required: !hasDefault && !isNullable,
       isRest: false,
       flag,
+      choices,
     });
   }
 
@@ -315,7 +325,7 @@ export function discoverRuntimeNamespaces(
 
         // No type info for imported methods - treat args as strings
         if (!methods.has(methodName)) {
-          methods.set(methodName, { description: "", params: [] });
+          methods.set(methodName, { description: "", params: [], untyped: true });
         }
       }
       proto = Object.getPrototypeOf(proto);
@@ -375,6 +385,11 @@ export function coerceArg(value: string, type: ParamType): unknown {
   }
 }
 
+// Negative numbers (-3, -0.5) are values, not flags
+function isNegativeNumber(arg: string): boolean {
+  return /^-(\d+(\.\d+)?|\.\d+)$/.test(arg);
+}
+
 // Parse CLI arguments into flags and positional args
 export function parseCliArgs(args: string[]): ParsedArgs {
   const positional: string[] = [];
@@ -416,7 +431,10 @@ export function parseCliArgs(args: string[]): ParsedArgs {
       const nextArg = args[i + 1];
 
       // If next arg exists and doesn't look like a flag, use it as value
-      if (nextArg !== undefined && !nextArg.startsWith("-")) {
+      if (
+        nextArg !== undefined &&
+        (!nextArg.startsWith("-") || isNegativeNumber(nextArg))
+      ) {
         flags.set(name, nextArg);
         i++; // Skip next arg
       } else {
@@ -425,6 +443,12 @@ export function parseCliArgs(args: string[]): ParsedArgs {
       continue;
     }
 
+    // Bare negative number is a positional value, not a short flag
+    if (isNegativeNumber(arg)) {
+      positional.push(arg);
+      continue;
+    }
+
     // -f=value (short with equals, single char only)
     if (arg.startsWith("-") && !arg.startsWith("--") && arg.includes("=")) {
       const eqIdx = arg.indexOf("=");
@@ -441,7 +465,10 @@ export function parseCliArgs(args: string[]): ParsedArgs {
       const name = arg.slice(1);
       const nextArg = args[i + 1];
 
-      if (nextArg !== undefined && !nextArg.startsWith("-")) {
+      if (
+        nextArg !== undefined &&
+        (!nextArg.startsWith("-") || isNegativeNumber(nextArg))
+      ) {
         flags.set(name, nextArg);
         i++;
       } else {
@@ -459,12 +486,42 @@ export function parseCliArgs(args: string[]): ParsedArgs {
 
 // Resolve arguments from parsed CLI args using param metadata
 export function resolveArgs(params: ParamMeta[], parsed: ParsedArgs): unknown[] {
+  // Reject unknown flags first — a typo'd flag silently changing behavior is
+  // worse than an error, and this diagnostic beats "missing required argument"
+  const validFlagNames = new Set<string>();
+  for (const param of params) {
+    if (!param.flag) continue;
+    validFlagNames.add(param.flag.long.slice(2));
+    if (param.flag.short) validFlagNames.add(param.flag.short.slice(1));
+    for (const alias of param.flag.aliases ?? []) {
+      validFlagNames.add(alias.slice(2));
+    }
+  }
+  const unknownFlags = [...parsed.flags.keys()].filter(
+    (name) => !validFlagNames.has(name),
+  );
+  if (unknownFlags.length > 0) {
+    const display = unknownFlags
+      .map((name) => (name.length === 1 ? `-${name}` : `--${name}`))
+      .join(", ");
+    const valid = params
+      .filter((p) => p.flag)
+      .map((p) => p.flag!.long)
+      .join(", ");
+    throw new Error(
+      `Unknown flag${unknownFlags.length > 1 ? "s" : ""}: ${display}` +
+        (valid ? `. Valid flags: ${valid}` : ""),
+    );
+  }
+
   const result: unknown[] = [];
   const usedPositional = new Set<number>();
+  let hasRest = false;
 
   for (const param of params) {
     // Handle rest parameters - collect all remaining positional args
     if (param.isRest) {
+      hasRest = true;
       const remaining = parsed.positional.filter(
         (_, i) => !usedPositional.has(i),
       );
@@ -474,28 +531,17 @@ export function resolveArgs(params: ParamMeta[], parsed: ParsedArgs): unknown[]
 
     let value: string | boolean | undefined;
 
-    // Try to get value from flags first
+    // Try to get value from flags first; long flag wins over short and aliases
     if (param.flag) {
-      // Check long flag (without --)
-      const longName = param.flag.long.slice(2);
-      if (parsed.flags.has(longName)) {
-        value = parsed.flags.get(longName);
-      }
-      // Check short flag (without -)
-      else if (param.flag.short) {
-        const shortName = param.flag.short.slice(1);
-        if (parsed.flags.has(shortName)) {
-          value = parsed.flags.get(shortName);
-        }
+      const flagNames = [param.flag.long.slice(2)];
+      if (param.flag.short) flagNames.push(param.flag.short.slice(1));
+      if (param.flag.aliases) {
+        flagNames.push(...param.flag.aliases.map((a) => a.slice(2)));
       }
-      // Check aliases
-      if (value === undefined && param.flag.aliases) {
-        for (const alias of param.flag.aliases) {
-          const aliasName = alias.slice(2);
-          if (parsed.flags.has(aliasName)) {
-            value = parsed.flags.get(aliasName);
-            break;
-          }
+      for (const flagName of flagNames) {
+        if (parsed.flags.has(flagName)) {
+          value = parsed.flags.get(flagName);
+          break;
         }
       }
     }
@@ -524,10 +570,29 @@ export function resolveArgs(params: ParamMeta[], parsed: ParsedArgs): unknown[]
 
     // Coerce and add to result
     // Boolean flags that are already boolean don't need coercion
+    let coerced: unknown;
     if (typeof value === "boolean" && param.type === "boolean") {
-      result.push(value);
+      coerced = value;
     } else {
-      result.push(coerceArg(String(value), param.type));
+      coerced = coerceArg(String(value), param.type);
+    }
+
+    if (param.choices && !param.choices.includes(String(coerced))) {
+      throw new Error(
+        `Invalid value for <${param.name}>: "${coerced}" (expected one of: ${param.choices.join(", ")})`,
+      );
+    }
+
+    result.push(coerced);
+  }
+
+  // Positional args left unclaimed by any parameter are an error too
+  if (!hasRest) {
+    const extra = parsed.positional.filter((_, i) => !usedPositional.has(i));
+    if (extra.length > 0) {
+      throw new Error(
+        `Unexpected argument${extra.length > 1 ? "s" : ""}: ${extra.join(" ")}`,
+      );
     }
   }
 
@@ -558,20 +623,35 @@ export function formatFlagInfo(param: ParamMeta): string {
 
 // Display task listing (used by both help and --list)
 export function printTaskList(discovered: DiscoveredTasks): void {
-  for (const [name, meta] of discovered.root) {
+  const signatureFor = (prefix: string, name: string, meta: TaskMeta) => {
     const paramStr = meta.params.map(formatParam).join(" ");
-    const signature = paramStr ? `${name} ${paramStr}` : name;
-    console.log(`  ${signature}`);
+    const full = prefix ? `${prefix}:${name}` : name;
+    return paramStr ? `${full} ${paramStr}` : full;
+  };
+
+  // Collect every row first so descriptions align across the whole listing
+  const rootRows: Array<[string, string]> = [];
+  for (const [name, meta] of discovered.root) {
+    rootRows.push([signatureFor("", name, meta), meta.description]);
   }
+  const nsRows = new Map<string, Array<[string, string]>>();
   for (const [ns, methods] of discovered.namespaced) {
-    console.log(`\n${ns}:`);
+    const rows: Array<[string, string]> = [];
     for (const [name, meta] of methods) {
-      const paramStr = meta.params.map(formatParam).join(" ");
-      const signature = paramStr
-        ? `${ns}:${name} ${paramStr}`
-        : `${ns}:${name}`;
-      console.log(`  ${signature}`);
+      rows.push([signatureFor(ns, name, meta), meta.description]);
     }
+    nsRows.set(ns, rows);
+  }
+
+  const allRows = [...rootRows, ...[...nsRows.values()].flat()];
+  const width = Math.max(0, ...allRows.map(([sig]) => sig.length));
+  const printRow = ([sig, desc]: [string, string]) =>
+    console.log(desc ? `  ${sig.padEnd(width)}  ${desc}` : `  ${sig}`);
+
+  rootRows.forEach(printRow);
+  for (const [ns, rows] of nsRows) {
+    console.log(`\n${ns}:`);
+    rows.forEach(printRow);
   }
 }
 
@@ -590,7 +670,11 @@ export function showTaskHelp(command: string, meta: TaskMeta): void {
     console.log("Arguments:");
     for (const param of meta.params) {
       const reqStr = param.required ? "(required)" : "(optional)";
-      const typeStr = param.isRest ? `${param.type}...` : param.type;
+      const typeStr = param.isRest
+        ? `${param.type}...`
+        : param.choices
+          ? param.choices.join("|")
+          : param.type;
       const flagStr = formatFlagInfo(param);
       const flagDisplay = flagStr ? `  ${flagStr}` : "";
       console.log(