@azad-73/cli 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,10 @@
+Copyright (c) 2026 et-azad. All rights reserved.
+
+This software and its source code are proprietary and confidential.
+No permission is granted to use, copy, modify, merge, publish, distribute,
+sublicense, or sell any part of this software, except under a separate
+written agreement with the copyright holder.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.

package/README.md

@@ -0,0 +1,70 @@
+# Azad73 (`azad`)
+
+Agentic AI platform built on the [Pi](https://pi.dev) SDK — a branded terminal agent with a curated set of default agents. Local-first and BYO-key: your API key and sessions stay on your machine.
+
+> "Azad" means *free / freedom* — local-first, BYO-key, no lock-in.
+
+## Install
+
+Requires **Node ≥ 22.19**.
+
+```bash
+npm i -g @azad-73/cli
+```
+
+## Authenticate
+
+Launch the TUI and log in (recommended — supports API key or subscription/OAuth):
+
+```bash
+azad
+# then, inside the TUI:
+/login
+```
+
+Credentials are stored locally in `~/.azad/auth.json`. Alternatives:
+
+```bash
+azad auth set                 # paste your Anthropic API key
+# or use an environment variable:
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+## Usage
+
+```bash
+azad                          # launch the branded interactive TUI
+azad agents list              # list available agents
+azad agents show <name>       # show an agent (prompt + tools)
+azad agents new <name>        # scaffold a new agent in ~/.azad/agents
+azad agents edit <name>       # edit an agent ($EDITOR)
+azad auth status|set|remove   # manage the stored credential
+azad version
+```
+
+Default agents include `context-cartographer` (run first on a new repo — maps the
+codebase and writes `AGENTS.md`), `feature-builder`, `feature-mr-reviewer`,
+`bug-reproduction-helper`, `root-cause-investigator`, `bug-fixer`,
+`bugfix-mr-reviewer`, and `ticket-doc-writer`.
+
+## Configuration
+
+Everything lives under `~/.azad/`:
+
+| Path | Contents |
+|------|----------|
+| `~/.azad/auth.json` | provider credentials (chmod 600) |
+| `~/.azad/agents/` | your custom / overridden agents |
+| `~/.azad/sessions/` | session history |
+
+Select the bundled `azad73` theme in-TUI via `/settings`.
+
+## Notes
+
+- Installing pulls one runtime dependency, the Pi SDK (`@earendil-works/pi-coding-agent`).
+  You may see `npm warn deprecated node-domexception@1.0.0` during install — it is a
+  harmless deprecation notice from a deep transitive dependency, not from Azad73.
+
+## License
+
+Proprietary — all rights reserved. See [LICENSE](LICENSE).

package/dist/azad.js

@@ -2,14 +2,15 @@
 
 // src/azad.ts
 import { spawn } from "node:child_process";
-import fs2 from "node:fs";
-import path4 from "node:path";
+import fs4 from "node:fs";
+import path6 from "node:path";
 import readline from "node:readline";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // ../engine/src/index.ts
 import {
-  SessionManager as SessionManager2,
-  createAgentSession
+  SessionManager as SessionManager3,
+  createAgentSession as createAgentSession2
 } from "@earendil-works/pi-coding-agent";
 
 // ../shared/src/index.ts
@@ -84,52 +85,323 @@ import { InteractiveMode } from "@earendil-works/pi-coding-agent";
 // ../engine/src/runtime.ts
 import {
   SessionManager,
+  SettingsManager,
   createAgentSessionFromServices,
   createAgentSessionRuntime,
   createAgentSessionServices
 } from "@earendil-works/pi-coding-agent";
 
+// ../engine/src/approval.ts
+import "@earendil-works/pi-coding-agent";
+var APPROVAL_MODES = [
+  { mode: "ask", short: "ask", label: "Ask \u2014 confirm before mutating tools" },
+  { mode: "auto", short: "auto-pilot", label: "Auto-pilot \u2014 run tools without confirmation" }
+];
+var state = { mode: "ask", allow: /* @__PURE__ */ new Set() };
+function getApprovalMode() {
+  return state.mode;
+}
+function approvalModeLabel(mode = state.mode) {
+  return APPROVAL_MODES.find((m) => m.mode === mode)?.short ?? mode;
+}
+var READ_ONLY = /* @__PURE__ */ new Set(["read", "grep", "find", "ls"]);
+function truncate(s, max) {
+  const clean = s.replace(/\s+/g, " ").trim();
+  return clean.length > max ? `${clean.slice(0, max - 1)}\u2026` : clean;
+}
+function describe(toolName, input) {
+  if (toolName === "bash") return `bash: ${truncate(String(input.command ?? ""), 64)}`;
+  if (toolName === "write") return `write ${String(input.file_path ?? input.path ?? "")}`;
+  if (toolName === "edit") return `edit ${String(input.file_path ?? input.path ?? "")}`;
+  return toolName;
+}
+function bashProgram(command) {
+  const tokens = command.trim().split(/\s+/);
+  for (const tok of tokens) {
+    if (/^[A-Za-z_]\w*=/.test(tok)) continue;
+    return tok;
+  }
+  return tokens[0] ?? "";
+}
+function bashPrograms(command) {
+  if (/\$\(|`|<\(|>\(/.test(command)) return null;
+  const programs = /* @__PURE__ */ new Set();
+  for (const part of command.split(/&&|\|\||[|;\n]/)) {
+    const p = bashProgram(part);
+    if (p) programs.add(p);
+  }
+  return [...programs];
+}
+function createApprovalExtension() {
+  return (pi) => {
+    pi.on("tool_call", async (event, ctx) => {
+      if (state.mode === "auto") return void 0;
+      if (READ_ONLY.has(event.toolName)) return void 0;
+      const input = event.input;
+      const isBash = event.toolName === "bash";
+      const programs = isBash ? bashPrograms(String(input.command ?? "")) : null;
+      if (!isBash) {
+        if (state.allow.has(event.toolName)) return void 0;
+      } else if (programs && programs.length > 0 && programs.every((p) => state.allow.has(`bash:${p}`))) {
+        return void 0;
+      }
+      if (!ctx.hasUI) return { block: true, reason: `Approval required for ${event.toolName} (no UI to confirm)` };
+      const options = ["Yes", "No"];
+      let alwaysLabel;
+      let alwaysKeys = [];
+      if (!isBash) {
+        alwaysLabel = `Always allow ${event.toolName}`;
+        alwaysKeys = [event.toolName];
+      } else if (programs && programs.length > 0) {
+        alwaysKeys = programs.map((p) => `bash:${p}`);
+        alwaysLabel = programs.length === 1 ? `Always allow "${programs.join("")}" commands` : `Always allow: ${programs.join(", ")}`;
+      }
+      if (alwaysLabel) options.push(alwaysLabel);
+      const choice = await ctx.ui.select(`Approve  ${describe(event.toolName, input)}`, options);
+      if (choice === void 0 || choice === "No") return { block: true, reason: "Denied by user" };
+      if (alwaysLabel && choice === alwaysLabel) for (const k of alwaysKeys) state.allow.add(k);
+      return void 0;
+    });
+    const setMode = (ctx, mode) => {
+      state.mode = mode;
+      ctx.ui.notify(`Approval mode: ${approvalModeLabel(mode)}`, mode === "auto" ? "warning" : "info");
+    };
+    const chooseMode = async (ctx) => {
+      const choice = await ctx.ui.select(
+        `Approval mode  (current: ${approvalModeLabel()})`,
+        APPROVAL_MODES.map((m) => m.label)
+      );
+      const picked = APPROVAL_MODES.find((m) => m.label === choice);
+      if (picked) setMode(ctx, picked.mode);
+    };
+    pi.registerCommand("mode", { description: "Choose approval mode", handler: async (_args, ctx) => chooseMode(ctx) });
+    pi.registerCommand("ask", {
+      description: "Approval mode: ask before mutating tools",
+      handler: async (_args, ctx) => setMode(ctx, "ask")
+    });
+    pi.registerCommand("auto", {
+      description: "Approval mode: auto-pilot (run tools without confirmation)",
+      handler: async (_args, ctx) => setMode(ctx, "auto")
+    });
+    pi.registerShortcut("alt+a", { description: "Choose approval mode", handler: (ctx) => chooseMode(ctx) });
+  };
+}
+
+// ../engine/src/branding.ts
+import os2 from "node:os";
+import "@earendil-works/pi-coding-agent";
+
+// ../engine/src/update.ts
+import fs2 from "node:fs";
+import path4 from "node:path";
+var CLI_PACKAGE = "@azad-73/cli";
+var CACHE_FILE = path4.join(AZAD_DIR, ".update-check.json");
+var TTL_MS = 24 * 60 * 60 * 1e3;
+async function getLatestVersion(timeoutMs = 3e3) {
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const res = await fetch(`https://registry.npmjs.org/${CLI_PACKAGE}/latest`, { signal: controller.signal });
+    clearTimeout(timer);
+    if (!res.ok) return null;
+    const data = await res.json();
+    return data.version ?? null;
+  } catch {
+    return null;
+  }
+}
+function isNewerVersion(latest, current) {
+  const a = latest.split(".").map((n) => Number.parseInt(n, 10));
+  const b = current.split(".").map((n) => Number.parseInt(n, 10));
+  for (let i = 0; i < 3; i++) {
+    const x = a[i] ?? 0;
+    const y = b[i] ?? 0;
+    if (x !== y) return x > y;
+  }
+  return false;
+}
+function readCache() {
+  try {
+    return JSON.parse(fs2.readFileSync(CACHE_FILE, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeCache(cache) {
+  try {
+    fs2.mkdirSync(AZAD_DIR, { recursive: true });
+    fs2.writeFileSync(CACHE_FILE, JSON.stringify(cache));
+  } catch {
+  }
+}
+async function checkForUpdate(current) {
+  const cache = readCache();
+  let latest;
+  if (cache && Date.now() - cache.checkedAt < TTL_MS) {
+    latest = cache.latest;
+  } else {
+    latest = await getLatestVersion();
+    writeCache({ checkedAt: Date.now(), latest });
+  }
+  return latest && isNewerVersion(latest, current) ? latest : null;
+}
+function cachedUpdate(current) {
+  const latest = readCache()?.latest;
+  return latest && isNewerVersion(latest, current) ? latest : null;
+}
+
 // ../engine/src/branding.ts
-import { VERSION } from "@earendil-works/pi-coding-agent";
 function coreThemesDir() {
   return resolveCoreDataDir("themes", import.meta.url);
 }
-function brandBanner(theme) {
+var ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+function vlen(s) {
+  return s.replace(ANSI, "").length;
+}
+var LOGO = [
+  "\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2557",
+  "\u255A\u2550\u2550\u2550\u2550\u2588\u2588\u2551\u255A\u2550\u2550\u2550\u2550\u2588\u2588\u2557",
+  "    \u2588\u2588\u2554\u255D \u2588\u2588\u2588\u2588\u2588\u2554\u255D",
+  "   \u2588\u2588\u2554\u255D  \u255A\u2550\u2550\u2550\u2588\u2588\u2557",
+  "   \u2588\u2588\u2551  \u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D",
+  "   \u255A\u2550\u255D  \u255A\u2550\u2550\u2550\u2550\u2550\u255D"
+];
+var LOGO_W = 16;
+var LOGO_GAP = 6;
+var TIP_ITEMS = [
+  { cmd: "/login", desc: "sign in (API key or subscription)" },
+  { cmd: "/model", desc: "switch the active model" },
+  { cmd: "/hotkeys", desc: "show all keyboard shortcuts" }
+];
+var ANIM_STYLE = "wipe";
+var ANIM_MS = 750;
+function animateLogoCell(theme, rowText, progress) {
+  const accent = (s) => theme.fg("accent", s);
+  const glow = (s) => theme.fg("borderAccent", s);
+  const logoFull = rowText.padEnd(LOGO_W);
+  if (progress >= 1) return accent(logoFull);
+  if (ANIM_STYLE === "wipe") {
+    const visible = logoFull.slice(0, Math.round(progress * LOGO_W));
+    const body = visible.slice(0, Math.max(0, visible.length - 1));
+    const edge = visible.slice(Math.max(0, visible.length - 1));
+    return `${accent(body)}${glow(edge)}${" ".repeat(LOGO_W - visible.length)}`;
+  }
+  const band = 2;
+  const sweep = progress * (LOGO_W + 2 * band) - band;
+  const start = Math.max(0, Math.min(LOGO_W, Math.round(sweep - band)));
+  const end = Math.max(0, Math.min(LOGO_W, Math.round(sweep + band) + 1));
+  return `${accent(logoFull.slice(0, start))}${glow(logoFull.slice(start, end))}${accent(logoFull.slice(end))}`;
+}
+function boxedHeader(theme, version, width, progress) {
   const accent = (s) => theme.fg("accent", s);
-  const muted = (s) => theme.fg("muted", s);
   const dim = (s) => theme.fg("dim", s);
-  return [
-    "",
-    `  ${accent("\u2588\u258C")} ${accent("Azad73")}`,
-    `  ${muted("agentic AI \u2014 free to run, yours to own")} ${dim(`\xB7 pi ${VERSION}`)}`,
-    ""
-  ];
+  const muted = (s) => theme.fg("muted", s);
+  const text = (s) => theme.fg("text", s);
+  const inner = Math.max(54, Math.min(width - 2, 72));
+  const verText = `v${version}`;
+  const titlePlain = ` Azad73 ${verText} `;
+  const titleColored = ` ${accent("Azad73")} ${dim(verText)} `;
+  const dashAfter = Math.max(2, inner - 1 - titlePlain.length);
+  const top = `${accent("\u256D\u2500")}${titleColored}${accent("\u2500".repeat(dashAfter))}${accent("\u256E")}`;
+  const bottom = accent(`\u2570${"\u2500".repeat(inner)}\u256F`);
+  const row = (colored, plainLen) => `${accent("\u2502")}${colored}${" ".repeat(Math.max(0, inner - plainLen))}${accent("\u2502")}`;
+  const tipBudget = inner - 2 - LOGO_W - LOGO_GAP;
+  const tips = [{ colored: muted("Tips"), plainLen: 4 }];
+  for (const t of TIP_ITEMS) {
+    const fixed = 2 + t.cmd.length + 1;
+    const desc = fixed + t.desc.length > tipBudget ? t.desc.slice(0, Math.max(0, tipBudget - fixed)) : t.desc;
+    tips.push({ colored: `${dim("\u2022")} ${accent(t.cmd)} ${text(desc)}`, plainLen: fixed + desc.length });
+  }
+  const blank = row("", 0);
+  const lines = [blank];
+  const rowCount = Math.max(LOGO.length, tips.length);
+  for (let i = 0; i < rowCount; i++) {
+    const cell = animateLogoCell(theme, LOGO[i] ?? "", progress);
+    const tip = tips[i] ?? { colored: "", plainLen: 0 };
+    lines.push(row(`  ${cell}${" ".repeat(LOGO_GAP)}${tip.colored}`, 2 + LOGO_W + LOGO_GAP + tip.plainLen));
+  }
+  lines.push(blank);
+  return ["", top, ...lines, bottom, ""];
+}
+function createBrandingExtension(opts) {
+  return (pi) => {
+    pi.on("session_start", async (_event, ctx) => {
+      if (ctx.mode !== "tui") return;
+      ctx.ui.setTitle("Azad73");
+      ctx.ui.setHeader((tui, theme) => {
+        const start = Date.now();
+        let timer;
+        const tick = () => {
+          if (Date.now() - start >= ANIM_MS && timer) {
+            clearInterval(timer);
+            timer = void 0;
+          }
+          tui.requestRender();
+        };
+        timer = setInterval(tick, 33);
+        return {
+          render(width) {
+            const progress = Math.min(1, (Date.now() - start) / ANIM_MS);
+            return boxedHeader(theme, opts.version, width, progress);
+          },
+          invalidate() {
+          },
+          dispose() {
+            if (timer) clearInterval(timer);
+          }
+        };
+      });
+      ctx.ui.setFooter((_tui, theme) => ({
+        render(width) {
+          const home = os2.homedir();
+          const cwd = ctx.cwd.startsWith(home) ? `~${ctx.cwd.slice(home.length)}` : ctx.cwd;
+          let cost = 0;
+          const entries = ctx.sessionManager.getBranch();
+          for (const entry of entries) {
+            if (entry.type === "message" && entry.message?.role === "assistant") {
+              cost += entry.message.usage?.cost?.total ?? 0;
+            }
+          }
+          const model = ctx.model?.id ?? "no model";
+          const level = pi.getThinkingLevel();
+          const mode = getApprovalMode();
+          const modeText = approvalModeLabel(mode);
+          const left = theme.fg("dim", `${cwd}  \xB7  $${cost.toFixed(2)} session`);
+          const modeColored = mode === "auto" ? theme.fg("warning", modeText) : theme.fg("dim", modeText);
+          const right = `${theme.fg("dim", `${model} \xB7 ${level} \xB7 `)}${modeColored}`;
+          if (vlen(left) + vlen(right) + 1 > width) {
+            return [`${theme.fg("dim", `${model} \xB7 ${level} \xB7 `)}${modeColored}`];
+          }
+          const gap = Math.max(1, width - vlen(left) - vlen(right));
+          return [`${left}${" ".repeat(gap)}${right}`];
+        },
+        invalidate() {
+        }
+      }));
+      void checkForUpdate(opts.version).then((latest) => {
+        if (latest) {
+          ctx.ui.notify(`Azad73 update available: ${opts.version} \u2192 ${latest} \xB7 run \`azad update\``, "info");
+        }
+      });
+    });
+  };
 }
-var brandingExtension = (pi) => {
-  pi.on("session_start", async (_event, ctx) => {
-    if (ctx.mode !== "tui") return;
-    ctx.ui.setTitle("Azad73");
-    ctx.ui.setHeader((_tui, theme) => ({
-      render(_width) {
-        return brandBanner(theme);
-      },
-      invalidate() {
-      }
-    }));
-  });
-};
 
 // ../engine/src/runtime.ts
-async function buildRuntime(workspace = defaultWorkspace(), sessionManager = SessionManager.create(workspace.rootDir)) {
+async function buildRuntime(workspace = defaultWorkspace(), sessionManager = SessionManager.create(workspace.rootDir), options = {}) {
   const { authStorage, modelRegistry } = createAuth(workspace);
+  const branding = createBrandingExtension({ version: options.version ?? "0.0.0" });
   const createRuntime = async ({ cwd, sessionManager: sm, sessionStartEvent }) => {
+    const settingsManager = SettingsManager.create(cwd, workspace.agentDir);
+    if (!settingsManager.getQuietStartup()) settingsManager.setQuietStartup(true);
     const services = await createAgentSessionServices({
       cwd,
       agentDir: workspace.agentDir,
       authStorage,
       modelRegistry,
+      settingsManager,
       resourceLoaderOptions: {
-        extensionFactories: [brandingExtension],
+        extensionFactories: [branding, createApprovalExtension()],
         additionalThemePaths: [coreThemesDir()]
       }
     });
@@ -147,24 +419,103 @@ async function buildRuntime(workspace = defaultWorkspace(), sessionManager = Ses
 }
 
 // ../engine/src/tui.ts
-async function runInteractive(workspace = defaultWorkspace()) {
-  const runtime = await buildRuntime(workspace);
+async function runInteractive(options = {}) {
+  const workspace = options.workspace ?? defaultWorkspace();
+  const runtime = await buildRuntime(workspace, void 0, { version: options.version });
   const mode = new InteractiveMode(runtime);
   await mode.run();
 }
 
+// ../engine/src/workflows.ts
+import fs3 from "node:fs";
+import path5 from "node:path";
+import { parseFrontmatter as parseFrontmatter2 } from "@earendil-works/pi-coding-agent";
+function discoverWorkflows(dirs) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const dir of dirs) {
+    if (!fs3.existsSync(dir)) continue;
+    for (const entry of fs3.readdirSync(dir)) {
+      if (!entry.endsWith(".md")) continue;
+      const filePath = path5.join(dir, entry);
+      let content;
+      try {
+        content = fs3.readFileSync(filePath, "utf8");
+      } catch {
+        continue;
+      }
+      const { frontmatter } = parseFrontmatter2(content);
+      const name = frontmatter.name?.trim();
+      if (!name) continue;
+      const steps = (Array.isArray(frontmatter.steps) ? frontmatter.steps : []).map((s) => ({ agent: String(s?.agent ?? "").trim(), task: s?.task })).filter((s) => s.agent.length > 0);
+      byName.set(name, {
+        name,
+        description: frontmatter.description?.trim() ?? "",
+        approval: frontmatter.approval === "off" ? "off" : "between-steps",
+        steps,
+        filePath
+      });
+    }
+  }
+  return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// ../engine/src/workflow-run.ts
+import { DefaultResourceLoader, SessionManager as SessionManager2, createAgentSession } from "@earendil-works/pi-coding-agent";
+async function runAgentStep(agent, input, options = {}) {
+  const workspace = options.workspace ?? defaultWorkspace();
+  const { authStorage, modelRegistry } = createAuth(workspace);
+  const model = options.modelId ? modelRegistry.find("anthropic", options.modelId) ?? void 0 : void 0;
+  const resourceLoader = new DefaultResourceLoader({
+    cwd: workspace.rootDir,
+    agentDir: workspace.agentDir,
+    systemPromptOverride: () => agent.systemPrompt,
+    noExtensions: true
+  });
+  await resourceLoader.reload();
+  const { session } = await createAgentSession({
+    cwd: workspace.rootDir,
+    agentDir: workspace.agentDir,
+    resourceLoader,
+    authStorage,
+    modelRegistry,
+    model,
+    tools: agent.tools,
+    sessionManager: SessionManager2.inMemory(workspace.rootDir)
+  });
+  let output = "";
+  const unsubscribe = session.subscribe((event) => {
+    if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+      output += event.assistantMessageEvent.delta;
+      options.onText?.(event.assistantMessageEvent.delta);
+    }
+  });
+  await session.prompt(input);
+  unsubscribe();
+  session.dispose();
+  return output.trim();
+}
+
 // src/azad.ts
 import { VERSION as PI_VERSION } from "@earendil-works/pi-coding-agent";
 var PROVIDER = "anthropic";
 function coreAgentsDir() {
   return resolveCoreDataDir("agents", import.meta.url);
 }
+function azadVersion() {
+  try {
+    const pkgPath = path6.join(path6.dirname(fileURLToPath2(import.meta.url)), "..", "package.json");
+    const pkg = JSON.parse(fs4.readFileSync(pkgPath, "utf8"));
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
 function agentDirs() {
   const ws = defaultWorkspace();
-  return [coreAgentsDir(), workspaceAgentsDir(), path4.join(ws.rootDir, ".azad", "agents")];
+  return [coreAgentsDir(), workspaceAgentsDir(), path6.join(ws.rootDir, ".azad", "agents")];
 }
 function workspaceAgentsDir() {
-  return path4.join(defaultWorkspace().agentDir, "agents");
+  return path6.join(defaultWorkspace().agentDir, "agents");
 }
 var AGENT_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 function newAgent(name) {
@@ -177,12 +528,12 @@ function newAgent(name) {
     process.exit(1);
   }
   const dir = workspaceAgentsDir();
-  const file = path4.join(dir, `${name}.md`);
-  if (fs2.existsSync(file)) {
+  const file = path6.join(dir, `${name}.md`);
+  if (fs4.existsSync(file)) {
     console.error(`agent already exists: ${file}`);
     process.exit(1);
   }
-  fs2.mkdirSync(dir, { recursive: true });
+  fs4.mkdirSync(dir, { recursive: true });
   const template = [
     "---",
     `name: ${name}`,
@@ -195,7 +546,7 @@ function newAgent(name) {
     "TODO: write the system prompt.",
     ""
   ].join("\n");
-  fs2.writeFileSync(file, template);
+  fs4.writeFileSync(file, template);
   console.log(`created ${file}`);
   console.log(`edit with: azad agents edit ${name}`);
 }
@@ -204,16 +555,20 @@ async function editAgent(name) {
     console.error("usage: azad agents edit <name>");
     process.exit(1);
   }
+  if (!AGENT_NAME_RE.test(name)) {
+    console.error("invalid name: use lowercase letters, digits, and single hyphens (e.g. my-agent)");
+    process.exit(1);
+  }
   const dir = workspaceAgentsDir();
-  const target = path4.join(dir, `${name}.md`);
-  if (!fs2.existsSync(target)) {
+  const target = path6.join(dir, `${name}.md`);
+  if (!fs4.existsSync(target)) {
     const found = discoverAgents(agentDirs()).find((a) => a.name === name);
     if (!found) {
       console.error(`agent not found: ${name}`);
       process.exit(1);
     }
-    fs2.mkdirSync(dir, { recursive: true });
-    fs2.copyFileSync(found.filePath, target);
+    fs4.mkdirSync(dir, { recursive: true });
+    fs4.copyFileSync(found.filePath, target);
     console.log(`copied default '${name}' into the workspace for editing: ${target}`);
   }
   const editor = process.env.EDITOR ?? process.env.VISUAL ?? "vi";
@@ -265,7 +620,7 @@ function promptLine(question) {
 }
 async function authCmd(sub) {
   const ws = defaultWorkspace();
-  const authPath = path4.join(ws.agentDir, "auth.json");
+  const authPath = path6.join(ws.agentDir, "auth.json");
   const { authStorage } = createAuth(ws);
   if (sub === "status" || sub === void 0) {
     const status = authStorage.getAuthStatus(PROVIDER);
@@ -280,7 +635,7 @@ async function authCmd(sub) {
       console.error("no key provided");
       process.exit(1);
     }
-    fs2.mkdirSync(ws.agentDir, { recursive: true });
+    fs4.mkdirSync(ws.agentDir, { recursive: true });
     authStorage.set(PROVIDER, { type: "api_key", key });
     console.log(`stored ${PROVIDER} key in ${authPath}`);
     return;
@@ -293,6 +648,186 @@ async function authCmd(sub) {
   console.error("usage: azad auth [status|set|remove]");
   process.exit(1);
 }
+function workflowDirs() {
+  const ws = defaultWorkspace();
+  return [
+    resolveCoreDataDir("workflows", import.meta.url),
+    path6.join(ws.agentDir, "workflows"),
+    path6.join(ws.rootDir, ".azad", "workflows")
+  ];
+}
+function workspaceWorkflowsDir() {
+  return path6.join(defaultWorkspace().agentDir, "workflows");
+}
+function listWorkflows(workflows) {
+  console.log(`Azad73 workflows (${workflows.length}):
+`);
+  for (const w of workflows) {
+    console.log(`  ${w.name.padEnd(14)} ${ellipsis(w.description, 60)}`);
+    console.log(`  ${" ".repeat(14)} ${w.steps.map((s) => s.agent).join(" \u2192 ")}`);
+  }
+}
+function showWorkflow(workflows, name) {
+  if (!name) {
+    console.error("usage: azad workflow show <name>");
+    process.exit(1);
+  }
+  const workflow = workflows.find((w) => w.name === name);
+  if (!workflow) {
+    console.error(`workflow not found: ${name}`);
+    process.exit(1);
+  }
+  const known = new Set(discoverAgents(agentDirs()).map((a) => a.name));
+  console.log(`# ${workflow.name}`);
+  if (workflow.description) console.log(workflow.description);
+  console.log(`approval: ${workflow.approval}`);
+  console.log(`file:     ${workflow.filePath}
+`);
+  workflow.steps.forEach((step, i) => {
+    const missing = known.has(step.agent) ? "" : "   (agent not found)";
+    console.log(`  ${i + 1}. ${step.agent}${step.task ? ` \u2014 ${step.task}` : ""}${missing}`);
+  });
+}
+function newWorkflow(name) {
+  if (!name) {
+    console.error("usage: azad workflow new <name>");
+    process.exit(1);
+  }
+  if (!AGENT_NAME_RE.test(name)) {
+    console.error("invalid name: use lowercase letters, digits, and single hyphens (e.g. my-flow)");
+    process.exit(1);
+  }
+  const dir = workspaceWorkflowsDir();
+  const file = path6.join(dir, `${name}.md`);
+  if (fs4.existsSync(file)) {
+    console.error(`workflow already exists: ${file}`);
+    process.exit(1);
+  }
+  fs4.mkdirSync(dir, { recursive: true });
+  const template = [
+    "---",
+    `name: ${name}`,
+    "description: TODO \u2014 what this workflow does.",
+    "approval: between-steps",
+    "steps:",
+    "  - agent: context-cartographer",
+    "---",
+    "",
+    "TODO: describe the workflow. Add or remove steps under `steps:` (each is `- agent: <name>`).",
+    ""
+  ].join("\n");
+  fs4.writeFileSync(file, template);
+  console.log(`created ${file}`);
+  console.log(`edit with: azad workflow edit ${name}`);
+}
+async function editWorkflow(name) {
+  if (!name) {
+    console.error("usage: azad workflow edit <name>");
+    process.exit(1);
+  }
+  if (!AGENT_NAME_RE.test(name)) {
+    console.error("invalid name: use lowercase letters, digits, and single hyphens");
+    process.exit(1);
+  }
+  const dir = workspaceWorkflowsDir();
+  const target = path6.join(dir, `${name}.md`);
+  if (!fs4.existsSync(target)) {
+    const found = discoverWorkflows(workflowDirs()).find((w) => w.name === name);
+    if (!found) {
+      console.error(`workflow not found: ${name}`);
+      process.exit(1);
+    }
+    fs4.mkdirSync(dir, { recursive: true });
+    fs4.copyFileSync(found.filePath, target);
+    console.log(`copied default '${name}' into the workspace for editing: ${target}`);
+  }
+  const editor = process.env.EDITOR ?? process.env.VISUAL ?? "vi";
+  await new Promise((resolve, reject) => {
+    const child = spawn(editor, [target], { stdio: "inherit" });
+    child.on("exit", () => resolve());
+    child.on("error", reject);
+  });
+}
+function buildStepInput(step, goal, previous, index) {
+  let task = step.task ?? "";
+  if (task.includes("{previous}")) task = task.replace(/\{previous\}/g, previous);
+  if (index === 0) return task || goal || "Begin.";
+  const parts = [];
+  if (task) parts.push(task);
+  if (goal) parts.push(`Overall goal: ${goal}`);
+  parts.push(`Output from the previous step:
+
+${previous}`);
+  return parts.join("\n\n");
+}
+async function promptYesNo(question) {
+  const answer = (await promptLine(question)).trim().toLowerCase();
+  return answer === "" || answer === "y" || answer === "yes";
+}
+async function runWorkflow(name, goal, modelId) {
+  if (!name) {
+    console.error("usage: azad workflow run <name> [goal] [--model <id>]");
+    process.exit(1);
+  }
+  const workflow = discoverWorkflows(workflowDirs()).find((w) => w.name === name);
+  if (!workflow) {
+    console.error(`workflow not found: ${name}`);
+    process.exit(1);
+  }
+  const agentMap = new Map(discoverAgents(agentDirs()).map((a) => [a.name, a]));
+  const missing = [...new Set(workflow.steps.filter((s) => !agentMap.has(s.agent)).map((s) => s.agent))];
+  if (missing.length > 0) {
+    console.error(`workflow '${name}' references unknown agents: ${missing.join(", ")}`);
+    process.exit(1);
+  }
+  console.log(
+    `
+Workflow: ${workflow.name}  \xB7  ${workflow.steps.length} steps  \xB7  approval: ${workflow.approval}${modelId ? `  \xB7  model: ${modelId}` : ""}
+`
+  );
+  let previous = "";
+  for (let i = 0; i < workflow.steps.length; i++) {
+    const step = workflow.steps[i];
+    const agent = step ? agentMap.get(step.agent) : void 0;
+    if (!step || !agent) continue;
+    if (i > 0 && workflow.approval === "between-steps") {
+      const ok = await promptYesNo(`Proceed to step ${i + 1}/${workflow.steps.length} \xB7 ${step.agent}? [Y/n] `);
+      if (!ok) {
+        console.log("\nWorkflow stopped.");
+        return;
+      }
+    }
+    console.log(`
+\u2500\u2500\u2500 Step ${i + 1}/${workflow.steps.length} \xB7 ${step.agent} \u2500\u2500\u2500
+`);
+    previous = await runAgentStep(agent, buildStepInput(step, goal, previous, i), {
+      modelId,
+      onText: (t) => process.stdout.write(t)
+    });
+    process.stdout.write("\n");
+  }
+  console.log(`
+\u2713 Workflow '${workflow.name}' complete.
+`);
+}
+async function update() {
+  const current = azadVersion();
+  process.stdout.write("Checking npm for the latest version\u2026 ");
+  const latest = await getLatestVersion();
+  if (!latest) {
+    console.log("could not reach the registry.");
+    process.exit(1);
+  }
+  if (!isNewerVersion(latest, current)) {
+    console.log(`already up to date (v${current}).`);
+    return;
+  }
+  console.log(`updating ${current} \u2192 ${latest}`);
+  const child = spawn("npm", ["install", "-g", `${CLI_PACKAGE}@latest`], { stdio: "inherit" });
+  const code = await new Promise((resolve) => child.on("exit", (c) => resolve(c ?? 0)));
+  if (code === 0) console.log(`Updated to v${latest}.`);
+  process.exit(code);
+}
 function printHelp() {
   console.log(
     [
@@ -304,8 +839,14 @@ function printHelp() {
       "  azad agents show <name>    show one agent",
       "  azad agents new <name>     scaffold a new agent in ~/.azad/agents",
       "  azad agents edit <name>    edit an agent ($EDITOR; copies a default into the workspace)",
+      "  azad workflow list         list workflows",
+      "  azad workflow show <name>  show a workflow's steps",
+      "  azad workflow new <name>   scaffold a workflow in ~/.azad/workflows",
+      "  azad workflow edit <name>  edit a workflow (add/remove agents under steps:)",
+      "  azad workflow run <name>   run a workflow (--model <id> to override the model)",
       "  azad auth status|set|remove   manage the Anthropic credential (~/.azad/auth.json)",
-      "  azad version               print version"
+      "  azad version               print version",
+      "  azad update                update to the latest published version"
     ].join("\n")
   );
 }
@@ -313,12 +854,18 @@ async function main() {
   const [cmd, sub, arg] = process.argv.slice(2);
   switch (cmd) {
     case void 0:
-      await runInteractive();
+      await runInteractive({ version: azadVersion() });
       return;
     case "version":
     case "--version":
-    case "-v":
-      console.log(`Azad73 (azad) \u2014 Pi SDK ${PI_VERSION}`);
+    case "-v": {
+      console.log(`Azad73 v${azadVersion()}  (Pi SDK ${PI_VERSION})`);
+      const latest = cachedUpdate(azadVersion());
+      if (latest) console.log(`Update available: ${azadVersion()} \u2192 ${latest} \xB7 run \`azad update\``);
+      return;
+    }
+    case "update":
+      await update();
       return;
     case "help":
     case "--help":
@@ -339,6 +886,37 @@ async function main() {
       else listAgents(agents);
       return;
     }
+    case "workflow":
+    case "workflows": {
+      if (sub === "new") {
+        newWorkflow(arg);
+        return;
+      }
+      if (sub === "edit") {
+        await editWorkflow(arg);
+        return;
+      }
+      if (sub === "run") {
+        const rest = process.argv.slice(5);
+        let modelId;
+        const goalParts = [];
+        for (let i = 0; i < rest.length; i++) {
+          if (rest[i] === "--model") {
+            modelId = rest[i + 1];
+            i++;
+          } else {
+            const part = rest[i];
+            if (part) goalParts.push(part);
+          }
+        }
+        await runWorkflow(arg, goalParts.join(" "), modelId);
+        return;
+      }
+      const workflows = discoverWorkflows(workflowDirs());
+      if (sub === "show") showWorkflow(workflows, arg);
+      else listWorkflows(workflows);
+      return;
+    }
     case "auth":
       await authCmd(sub);
       return;

package/dist/core/workflows/bugfix.md

@@ -0,0 +1,13 @@
+---
+name: bugfix
+description: Bug lifecycle — reproduce, find root cause, fix, review, document.
+approval: between-steps
+steps:
+  - agent: bug-reproduction-helper
+  - agent: root-cause-investigator
+  - agent: bug-fixer
+  - agent: bugfix-mr-reviewer
+  - agent: ticket-doc-writer
+---
+
+Run on a confirmed bug. Each step passes its output to the next.

package/dist/core/workflows/feature.md

@@ -0,0 +1,11 @@
+---
+name: feature
+description: Feature lifecycle — build, review, document.
+approval: between-steps
+steps:
+  - agent: feature-builder
+  - agent: feature-mr-reviewer
+  - agent: ticket-doc-writer
+---
+
+Run from acceptance criteria. Each step passes its output to the next.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@azad-73/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Azad73 — agentic AI platform CLI (branded TUI + agents) built on the Pi SDK",
-  "license": "MIT",
+  "license": "UNLICENSED",
   "type": "module",
   "bin": {
     "azad": "./dist/azad.js"