@netnodeag/kraftwerk 0.4.1 → 0.7.0

package/README.md

@@ -56,6 +56,7 @@ kraftwerk list                          # table: workflows, steps, agents (with
 kraftwerk run tagline "https://..."     # run; --yes, --verbose
 kraftwerk run                           # interactive: pick workflow, type the request
 kraftwerk runs                          # past runs from output/*/trace.jsonl; runs show <id> for detail
+kraftwerk knowledge                     # Context & Knowledge: OKF bundles (list/get/put/verify/search/...)
 kraftwerk ui                            # inspector web UI on http://localhost:1981; --port, --output
 kraftwerk doctor                        # preflight: harness CLIs, docker, workflows, declared env vars
 kraftwerk validate                      # all discovered — schema + semantics + files, exit 1 on failure
@@ -69,8 +70,10 @@ kraftwerk runner ps / stop <run-id>     # see / stop running sandbox containers
 ### Project config — kraftwerk.yml
 
 Optional, at the project root (also the root marker for the walk-up); all
-fields optional: `workflows:` (workflows root) and `output:` (run-artifact
-directory, default `output/`).
+fields optional: `workflows:` (workflows root), `output:` (run-artifact
+directory, default `output/`), `knowledge:` (OKF knowledge-bundle root,
+default `knowledge/`), and `agents:` (team agent-definition root, default
+`agents/`).
 
 ### Triggering from CI / cron / webhooks
 
@@ -116,6 +119,165 @@ agent (Claude Code, Codex): it prints a self-contained brief — schema
 example, gates, harness rules, verify ladder — that the agent follows to
 author the workflow folder and validate/smoke it with this CLI.
 
+### Inspector on a server — deploy starter
+
+The repo root ships [`deploy-starter/`](../deploy-starter/): copy it
+into your consumer repo as `deploy/` and it builds a small image (this
+package from npm + the claude/codex/pi CLIs) that serves `kraftwerk ui`
+for that repo, bind-mounted at `/work`. `compose.yml` is localhost-only
+(SSH tunnel); `compose.traefik.yml` layers traefik routing + mandatory
+basic-auth on top — the UI has no authentication of its own and its chat
+runs coding agents against the mounted repo. Agent logins made inside
+the container persist in the `agent-home` volume. This is a different
+image from the `kraftwerk-runner` sandbox (`runner/Dockerfile`) used by
+`run --sandbox`.
+
+## Team — persistent agents
+
+The inspector's "team" screen turns chat agents into persistent teammates.
+A team member is one folder under the project's `agents/` root:
+
+```
+agents/max/
+  agent.yml     # name, emoji, description, harness, model, effort, workflows
+  system.md     # the member's system prompt (its role)
+```
+
+```yaml
+# agents/max/agent.yml
+name: Max
+emoji: 🛠️
+description: Runs and explains this project's workflows
+harness: claude        # claude | codex | pi — which chat backend runs it
+model: sonnet          # optional; harness default when omitted
+effort: medium         # optional: low | medium | high | xhigh | max
+workflows: [tagline, website-check]
+knowledge: [customer-support]   # OKF bundles the member consults & maintains
+skills: [report-html]           # optional allowlist; omit = all skills, [] = none
+```
+
+Sessions with a member are ordinary chats scoped `{ kind: "team", member }`,
+listed per member in a second sidebar. On the first message the member gets
+its role plus its connected workflows and knowledge bundles injected as
+context — including how to run workflows
+(`KRAFTWERK_YES=1 npx kraftwerk run <workflow> "<request>"`) and how to read
+and write knowledge through `kraftwerk knowledge` (writes stamped with the
+member's own actor, `<slug>/<harness>`), so it triggers its own workflows
+when a request matches and keeps its bundles current. Model/effort ride on
+backend-specific channels: the claude adapter takes the model via ACP session
+options and the thinking budget via `MAX_THINKING_TOKENS`; codex gets a
+`CODEX_CONFIG` env override (`model`, `model_reasoning_effort`); pi gets
+`--model`/`--thinking` flags. Members are created and edited in the UI (or by
+editing the files — the definition is read fresh for each new session).
+
+### Skills in chat
+
+Chats — general ones and team sessions — can use skills: Claude-style
+instruction packages, one folder per skill with a `SKILL.md` (YAML
+frontmatter `name` + `description`, then the instructions). Two roots are
+discovered, with a project skill shadowing a same-named user skill:
+
+```
+<project>/.claude/skills/<name>/SKILL.md   # git-tracked, per project
+~/.claude/skills/<name>/SKILL.md           # personal, per user
+```
+
+Every chat lists its visible skills as context ("## Your skills"), so the
+agent reaches for one when the request matches. Typing `/` in the composer
+opens an autocomplete over them; sending `/<name> <args>` expands the
+skill's SKILL.md into the prompt — which is why this works identically on
+claude, codex, and pi. Natively on top of that, claude discovers
+`.claude/skills` itself (a team member's `skills:` allowlist narrows that
+via ACP session options) and pi loads each visible skill folder via
+`--skill`. Team members take an optional `skills:` list in `agent.yml`:
+omitted means all discovered skills, an empty list means none, otherwise
+it's the allowlist. `GET /api/skills` returns what's discovered.
+
+### Routines — scheduled prompts
+
+A member can have routines: cron-scheduled prompts, like standing orders for
+an employee. Definitions live next to the member in
+`agents/<slug>/routines.yml` (git-tracked); run state (last run, last
+session, errors) lives in `<output>/routines-state.json`.
+
+```yaml
+# agents/max/routines.yml
+- id: morning-check
+  name: Morning check
+  schedule: "0 9 * * 1-5"   # 5-field cron (server local time) or @hourly/@daily/@weekly/@monthly
+  prompt: |
+    Run the website-check workflow for https://example.com and summarize
+    anything that regressed since the last run.
+  enabled: true
+```
+
+The inspector server runs the scheduler in-process (no external cron): every
+due routine opens a fresh session for the member, posts the prompt, and the
+run shows up in the sessions sidebar titled "⏰ <name>". Routine sessions run
+unattended, so tool-permission requests are auto-approved (the
+request/approval pair stays in the thread as an audit trail) — treat routine
+prompts with the same trust as `KRAFTWERK_YES=1` workflow runs. Manage
+routines on the member page: create/edit/delete, toggle enabled, "run now",
+and jump to the last run's session. Missed schedules while the server is
+down are skipped, not replayed.
+
+## Context & Knowledge — OKF bundles
+
+Alongside runs and chats, a project can keep curated knowledge as
+[OKF v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+bundles (Open Knowledge Format): directories of markdown files with YAML
+frontmatter under `knowledge/`, one concept per file. Human-readable,
+agent-parseable, diffable in git — and self-describing: frontmatter
+carries provenance (`sources`, `generated`), trust (`verified`), and
+lifecycle (`status`, `stale_after`).
+
+```
+knowledge/
+  customer-support/        # one bundle per subdirectory
+    index.md               # derived directory listing (regenerated on every write)
+    log.md                 # chronological update history (appended on every write)
+    playbooks/refunds.md   # a concept: YAML frontmatter + markdown body
+```
+
+The `kraftwerk knowledge` CLI is the enforced write path — `put` stamps
+`generated: { by, at }` with the writing actor, appends the bundle log,
+and regenerates the derived `index.md`, so an agent-maintained corpus
+stays trustable:
+
+```bash
+kraftwerk knowledge init customer-support               # new bundle
+kraftwerk knowledge put customer-support/playbooks/refunds \
+  --file refunds.md --actor helpdesk-agent/claude-sonnet-5
+kraftwerk knowledge list customer-support               # concepts + trust tier
+kraftwerk knowledge get customer-support/playbooks/refunds   # raw markdown; --json parsed
+kraftwerk knowledge search "refund"                     # full-text across bundles
+kraftwerk knowledge verify customer-support/playbooks/refunds --by human:user
+kraftwerk knowledge validate                            # OKF conformance + warnings
+kraftwerk knowledge fsck --fix                          # heal out-of-band edits (reindex)
+```
+
+Actors follow the OKF convention: `<producer>/<version>` for agents,
+`human:<id>` for people, `process:<id>` for automation. Consumers derive
+a **trust tier** per concept: no `verified` ⇒ unverified, verified by
+non-human actors ⇒ machine-confirmed, verified by a `human:` actor ⇒
+human-reviewed. The inspector's **Context & Knowledge** screen shows
+bundles, concepts with trust/status/staleness badges, sources, and the
+bundle log — the ✓ verify button records a `human:user` verification, and
+"curate in chat" opens a knowledge-scoped chat whose agent knows the OKF
+essentials and writes through the CLI.
+
+Workflows read and write knowledge through the same CLI via a
+[CLI grant](#cli-grants) — the trust model stays intact because every
+agent write is stamped with its actor:
+
+```yaml
+clis:
+  npx kraftwerk knowledge: "OKF knowledge base. Read: `list`, `get <bundle>/<path>`, `search <text>`. Write: `put <bundle>/<path> --file <tmp.md> --actor triager/gpt-5.6`. Frontmatter needs `type:`; never edit index.md/log.md by hand."
+agents:
+  triager:
+    clis: [npx kraftwerk knowledge]
+```
+
 ## The agent — four axes
 
 ```ts
@@ -241,11 +403,35 @@ npm start -- validate <path>                   # runCli consumers (TS registry)
 ```
 
 Gates: `file_non_empty: <file>`, `slots_filled: <file>`,
-`contains: {file, text, label?}`. Living examples:
+`contains: {file, text, label?}`, and `check: <script>` (or
+`check: {run, label?}`) — a bash validation script executed in the run
+directory; exit 0 passes, non-zero fails and everything the script printed
+becomes the failure message, verbatim in the correction prompt. Single-line
+values reference a file inside the workflow folder, like `run:`.
+
+Steps take an optional `if:` — deterministic preconditions in the same
+forms as gates, evaluated against the run directory just before the step.
+Any unmet precondition SKIPS the step (traced as `phase_skipped`, run
+continues) — the way to avoid spawning an agent when a previous script
+found nothing to do:
+
+```yaml
+  - name: triage tickets
+    agent: triager
+    if:
+      - file_non_empty: todo.json    # written by the fetch step only when work exists
+    prompt: prompts/triage.md
+    gates:
+      - check: scripts/validate-triage.sh
+```
+
+Living examples:
 [`../agent-playground/src/workflows/tagline/`](../agent-playground/src/workflows/tagline/)
-and [`../agent-playground/src/workflows/pitch/`](../agent-playground/src/workflows/pitch/).
-v1 is deliberately linear — approval loops, AGENTS.md-style context files
-and skills stay on the roadmap; anything non-linear is a TS workflow.
+and [`../agent-playground/src/workflows/pitch/`](../agent-playground/src/workflows/pitch/);
+`check`/`if` in [`../agent-playground/src/workflows/helpdesk-check/`](../agent-playground/src/workflows/helpdesk-check/).
+v1 is deliberately linear — approval loops and AGENTS.md-style context files
+stay on the roadmap (skills exist in chat, not in workflow runs); anything
+non-linear is a TS workflow.
 
 ### MCP servers alongside the workflow
 

package/dist/cli/doctor.js

@@ -1,4 +1,5 @@
 import { spawnSync } from "node:child_process";
+import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import chalk from "chalk";
 import { resolveProject } from "../config.js";
@@ -13,6 +14,31 @@ const ICONS = {
 function report(level, label, detail) {
     console.log(`${ICONS[level]} ${label}${detail ? chalk.dim(` — ${detail}`) : ""}`);
 }
+/** True if a < b for plain x.y.z versions (prerelease tags ignored). */
+function semverLt(a, b) {
+    const pa = a.split("-")[0].split(".").map(Number);
+    const pb = b.split("-")[0].split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        if ((pa[i] ?? 0) !== (pb[i] ?? 0))
+            return (pa[i] ?? 0) < (pb[i] ?? 0);
+    }
+    return false;
+}
+/** Latest published version from the npm registry, or undefined if unreachable. */
+async function latestNpmVersion(name) {
+    try {
+        const res = await fetch(`https://registry.npmjs.org/${name}/latest`, {
+            signal: AbortSignal.timeout(5_000),
+        });
+        if (!res.ok)
+            return undefined;
+        const data = (await res.json());
+        return data.version;
+    }
+    catch {
+        return undefined;
+    }
+}
 function cliVersion(command) {
     const r = spawnSync(command, ["--version"], { encoding: "utf8", timeout: 10_000 });
     if (r.status !== 0)
@@ -29,9 +55,58 @@ export async function runDoctor(cwd) {
         report("fail", `node ${process.versions.node}`, "kraftwerk needs node >= 20");
         failures++;
     }
-    // Project.
-    const project = await resolveProject(cwd);
+    // kraftwerk version vs npm.
+    const pkg = JSON.parse(await readFile(new URL("../../package.json", import.meta.url), "utf8"));
+    const latest = await latestNpmVersion(pkg.name);
+    if (!latest) {
+        report("info", `kraftwerk ${pkg.version}`, "could not reach npm registry to check for updates");
+    }
+    else if (semverLt(pkg.version, latest)) {
+        report("warn", `kraftwerk ${pkg.version}`, `${latest} available — npm i -g ${pkg.name}@latest`);
+    }
+    else {
+        report("ok", `kraftwerk ${pkg.version}`, latest === pkg.version ? "latest on npm" : `ahead of npm (latest: ${latest})`);
+    }
+    // Project. resolveProject throws on a malformed kraftwerk.yml (bad YAML,
+    // non-mapping, unknown keys, non-string values) — surface that as a check.
+    let project;
+    try {
+        project = await resolveProject(cwd);
+    }
+    catch (err) {
+        report("fail", "kraftwerk.yml invalid", err.message.split("\n")[0]);
+        console.log(chalk.red("\n1 problem(s) found."));
+        process.exit(1);
+    }
     report("info", `Project root: ${project.root}`, project.configPath ? path.basename(project.configPath) : "no kraftwerk.yml (fallback: workflows folder or .git)");
+    // Project config: well-formed (guaranteed by the parse above) and the
+    // configured paths actually exist.
+    if (!project.configPath) {
+        report("warn", "no kraftwerk.yml", "recommended as project root marker — `kraftwerk init` scaffolds one");
+    }
+    else {
+        const cfg = project.config;
+        const keys = Object.keys(cfg);
+        report("ok", `${path.basename(project.configPath)} well-formed`, keys.length ? keys.map((k) => `${k}: ${cfg[k]}`).join(", ") : "empty — defaults apply");
+        if (!cfg.name)
+            report("info", "name not set in kraftwerk.yml", "inspector header falls back to the folder name");
+        const isDir = async (p) => (await stat(p).catch(() => null))?.isDirectory() ?? false;
+        for (const key of ["workflows", "knowledge", "agents", "output"]) {
+            const value = cfg[key];
+            if (!value)
+                continue;
+            const abs = path.resolve(project.root, value);
+            if (await isDir(abs))
+                continue;
+            if (key === "output") {
+                report("info", `output: ${value}`, "directory not created yet — appears on first run");
+            }
+            else {
+                report("fail", `${key}: ${value}`, "configured directory does not exist");
+                failures++;
+            }
+        }
+    }
     const found = project.workflowsRoot ? await discoverWorkflows(cwd) : [];
     if (!project.workflowsRoot) {
         report("warn", "no workflows root", "expected src/workflows/ or workflows/ — `kraftwerk init` scaffolds one");

package/dist/cli/init.js

@@ -2,16 +2,22 @@ import { appendFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import chalk from "chalk";
 import { SCHEMA_URL } from "../config.js";
+import { initBundle, writeConcept } from "../okf.js";
 /**
  * `kraftwerk init` — make any repository a kraftwerk consumer in one
- * command: kraftwerk.yml (root marker + config), workflows/ with a runnable
- * example, and an output/ ignore entry. Everything is idempotent: existing
- * files are left untouched and reported.
+ * command: kraftwerk.yml (root marker + config), a kraftwerk-data/ tree with
+ * a runnable example workflow, a starter team agent ("max"), a demo
+ * knowledge bundle, and an output ignore entry. Everything is idempotent:
+ * existing files are left untouched and reported.
  */
-const CONFIG_TEMPLATE = `# kraftwerk project config — also marks the project root for the CLI.
+const DATA_DIR = "kraftwerk-data";
+const configTemplate = (name) => `# kraftwerk project config — also marks the project root for the CLI.
 # All fields optional. Docs: https://github.com/NETNODEAG/kraftwerk
-workflows: workflows   # where workflows live
-output: output         # where run artifacts land (git-ignored)
+name: ${JSON.stringify(name)}   # display name, shown in the inspector header
+workflows: ${DATA_DIR}/workflows   # where workflows live
+output: ${DATA_DIR}/output         # where run artifacts land (git-ignored)
+knowledge: ${DATA_DIR}/knowledge   # OKF knowledge bundles
+agents: ${DATA_DIR}/agents         # team agent definitions
 `;
 const WORKFLOW_TEMPLATE = `# yaml-language-server: $schema=${SCHEMA_URL}
 name: hello
@@ -38,6 +44,34 @@ const PROMPT_TEMPLATE = `Request: \${{ request }}
 Answer the request and write the answer to answer.md
 (Markdown, with a short heading).
 `;
+const AGENT_YML_TEMPLATE = `name: Max - Workflow Runner
+emoji: 🛠️
+description: Runs and explains this project's workflows
+harness: claude
+model: sonnet
+effort: medium
+workflows:
+  - hello
+knowledge:
+  - demo-customer-support
+`;
+const AGENT_SYSTEM_TEMPLATE = `You are Max, this project's workflow runner. You run and explain the
+project's kraftwerk workflows, and you consult the knowledge bundles you
+have access to before answering questions they cover.
+`;
+const DEMO_BUNDLE = "demo-customer-support";
+const DEMO_CONCEPT = `---
+type: Playbook
+title: Refund handling
+description: How support handles refund requests.
+tags: [ support, refunds ]
+---
+
+# Steps
+
+1. Check the order in the shop backend.
+2. Refunds under CHF 50 are approved directly.
+`;
 export async function runInit(cwd) {
     const exists = async (p) => !!(await stat(p).catch(() => null));
     const created = [];
@@ -52,20 +86,36 @@ export async function runInit(cwd) {
         await writeFile(abs, content);
         created.push(rel);
     };
-    await put("kraftwerk.yml", CONFIG_TEMPLATE);
-    await put("workflows/hello/workflow.yml", WORKFLOW_TEMPLATE);
-    await put("workflows/hello/prompts/assistant.md", PERSONA_TEMPLATE);
-    await put("workflows/hello/prompts/answer.md", PROMPT_TEMPLATE);
-    // .gitignore: append output/ if it's not covered yet.
+    await put("kraftwerk.yml", configTemplate(path.basename(path.resolve(cwd))));
+    await put(`${DATA_DIR}/workflows/hello/workflow.yml`, WORKFLOW_TEMPLATE);
+    await put(`${DATA_DIR}/workflows/hello/prompts/assistant.md`, PERSONA_TEMPLATE);
+    await put(`${DATA_DIR}/workflows/hello/prompts/answer.md`, PROMPT_TEMPLATE);
+    // Team agent "max".
+    await put(`${DATA_DIR}/agents/max/agent.yml`, AGENT_YML_TEMPLATE);
+    await put(`${DATA_DIR}/agents/max/system.md`, AGENT_SYSTEM_TEMPLATE);
+    // Demo knowledge bundle, through the canonical OKF write path so
+    // index.md and log.md come out consistent.
+    const knowledgeRoot = path.join(cwd, DATA_DIR, "knowledge");
+    const bundleRel = `${DATA_DIR}/knowledge/${DEMO_BUNDLE}/`;
+    if (await exists(path.join(knowledgeRoot, DEMO_BUNDLE))) {
+        skipped.push(bundleRel);
+    }
+    else {
+        await initBundle(knowledgeRoot, DEMO_BUNDLE);
+        await writeConcept(knowledgeRoot, DEMO_BUNDLE, "playbooks/refunds", DEMO_CONCEPT, "kraftwerk-init");
+        created.push(bundleRel);
+    }
+    // .gitignore: append the output dir if it's not covered yet.
+    const outputEntry = `${DATA_DIR}/output`;
     const gitignorePath = path.join(cwd, ".gitignore");
     const gitignore = (await readFile(gitignorePath, "utf8").catch(() => null)) ?? null;
     if (gitignore === null) {
-        await writeFile(gitignorePath, "output/\n");
+        await writeFile(gitignorePath, `${outputEntry}/\n`);
         created.push(".gitignore");
     }
-    else if (!gitignore.split("\n").some((l) => l.trim().replace(/\/$/, "") === "output")) {
-        await appendFile(gitignorePath, `${gitignore.endsWith("\n") ? "" : "\n"}output/\n`);
-        created.push(".gitignore (output/ added)");
+    else if (!gitignore.split("\n").some((l) => l.trim().replace(/\/$/, "") === outputEntry)) {
+        await appendFile(gitignorePath, `${gitignore.endsWith("\n") ? "" : "\n"}${outputEntry}/\n`);
+        created.push(`.gitignore (${outputEntry}/ added)`);
     }
     else {
         skipped.push(".gitignore");

package/dist/cli/knowledge.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerKnowledgeCommands(program: Command): void;

package/dist/cli/knowledge.js

@@ -0,0 +1,213 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import chalk from "chalk";
+import { resolveProject } from "../config.js";
+import { fsck, getConcept, initBundle, knowledgeRoot, listBundles, listConcepts, searchKnowledge, validateBundle, verifyConcept, writeConcept, } from "../okf.js";
+/**
+ * `kraftwerk knowledge` — the CLI surface over OKF bundles (Context &
+ * Knowledge). This is the enforced write path: `put` stamps provenance
+ * (`generated: { by, at }`), appends the bundle log, and regenerates
+ * index.md; direct file edits are healed by `fsck --fix`.
+ *
+ * Agents identify via --actor (or KRAFTWERK_ACTOR); the OKF convention is
+ * `<producer>/<version>` for agents, `human:<id>` for people,
+ * `process:<id>` for automation. Humans default to `human:user`.
+ */
+const DEFAULT_ACTOR = "human:user";
+const actorOf = (opts) => opts.actor?.trim() || process.env.KRAFTWERK_ACTOR?.trim() || DEFAULT_ACTOR;
+async function root() {
+    const project = await resolveProject(process.cwd());
+    return knowledgeRoot(project.root, project.config.knowledge);
+}
+/** Split "bundle/path/to/concept" into its bundle and concept id. */
+function splitRef(ref) {
+    const clean = ref.replace(/^\/+/, "");
+    const slash = clean.indexOf("/");
+    if (slash <= 0 || slash === clean.length - 1) {
+        throw new Error(`expected <bundle>/<concept-path>, got "${ref}"`);
+    }
+    return { bundle: clean.slice(0, slash), id: clean.slice(slash + 1) };
+}
+const tierColor = (tier) => tier === "human-reviewed"
+    ? chalk.green(tier)
+    : tier === "machine-confirmed"
+        ? chalk.cyan(tier)
+        : chalk.dim(tier);
+function conceptLine(c) {
+    const flags = [
+        c.status !== "stable" ? chalk.yellow(c.status) : "",
+        c.stale ? chalk.red("stale") : "",
+        c.error ? chalk.red("invalid") : "",
+    ]
+        .filter(Boolean)
+        .join(" ");
+    return (`  ${chalk.cyan(c.id.padEnd(32))} ${(c.type ?? "?").padEnd(22)} ` +
+        `${tierColor(c.trustTier).padEnd(18)} ${flags}`);
+}
+function printIssues(issues) {
+    for (const i of issues) {
+        const mark = i.level === "error" ? chalk.red("✖") : chalk.yellow("⚠");
+        console.log(`${mark} ${i.bundle}/${i.file}: ${i.message}`);
+    }
+}
+async function readStdin() {
+    let data = "";
+    for await (const chunk of process.stdin)
+        data += chunk;
+    return data;
+}
+export function registerKnowledgeCommands(program) {
+    const knowledge = program
+        .command("knowledge")
+        .description("Context & Knowledge: OKF bundles under knowledge/ (read, write, verify)");
+    knowledge
+        .command("list", { isDefault: true })
+        .description("List bundles, or the concepts of one bundle")
+        .argument("[bundle]", "Bundle name (a directory under knowledge/)")
+        .option("--json", "Machine-readable output")
+        .action(async (bundle, opts) => {
+        const kroot = await root();
+        if (!bundle) {
+            const bundles = await listBundles(kroot);
+            if (opts.json)
+                return void console.log(JSON.stringify({ root: kroot, bundles }, null, 2));
+            if (bundles.length === 0) {
+                console.log(chalk.yellow(`No knowledge bundles in ${kroot} — create one with \`kraftwerk knowledge init <name>\`.`));
+                return;
+            }
+            for (const b of bundles) {
+                console.log(`${chalk.cyan(b.name.padEnd(24))} ${String(b.concepts).padStart(3)} concepts` +
+                    chalk.dim(`${b.okfVersion ? `  okf ${b.okfVersion}` : ""}${b.updatedAt ? `  updated ${b.updatedAt.slice(0, 10)}` : ""}`));
+            }
+            return;
+        }
+        const concepts = await listConcepts(kroot, bundle);
+        if (opts.json)
+            return void console.log(JSON.stringify({ bundle, concepts }, null, 2));
+        if (concepts.length === 0) {
+            console.log(chalk.yellow(`Bundle "${bundle}" has no concepts.`));
+            return;
+        }
+        console.log(chalk.bold(`  ${"concept".padEnd(32)} ${"type".padEnd(22)} trust`));
+        for (const c of concepts)
+            console.log(conceptLine(c));
+    });
+    knowledge
+        .command("get")
+        .description("Print one concept (raw markdown; --json adds parsed frontmatter + trust)")
+        .argument("<ref>", "<bundle>/<concept-path>, e.g. finance/metrics/revenue")
+        .option("--json", "Machine-readable output")
+        .action(async (ref, opts) => {
+        const { bundle, id } = splitRef(ref);
+        const concept = await getConcept(await root(), bundle, id);
+        if (!concept) {
+            console.error(chalk.red(`Concept ${ref} not found.`));
+            process.exit(2);
+        }
+        if (opts.json) {
+            const { raw, ...rest } = concept;
+            console.log(JSON.stringify(rest, null, 2));
+        }
+        else {
+            process.stdout.write(concept.raw);
+        }
+    });
+    knowledge
+        .command("put")
+        .description("Write a concept from stdin or --file (stamps generated.by/at, logs, reindexes)")
+        .argument("<ref>", "<bundle>/<concept-path>")
+        .option("--file <path>", "Read the concept markdown from a file instead of stdin")
+        .option("--actor <actor>", `Who writes: <producer>/<version>, human:<id>, process:<id> (default: ${DEFAULT_ACTOR})`)
+        .action(async (ref, opts) => {
+        const { bundle, id } = splitRef(ref);
+        const content = opts.file ? await readFile(path.resolve(opts.file), "utf8") : await readStdin();
+        if (!content.trim()) {
+            console.error(chalk.red("No content (pipe markdown on stdin or pass --file)."));
+            process.exit(2);
+        }
+        try {
+            const result = await writeConcept(await root(), bundle, id, content, actorOf(opts));
+            console.log(`${chalk.green("✔")} ${result.created ? "created" : "updated"} ${chalk.cyan(`${bundle}/${result.concept.id}`)} ` +
+                chalk.dim(`(${result.concept.type}, by ${actorOf(opts)})`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(2);
+        }
+    });
+    knowledge
+        .command("verify")
+        .description("Record a verification event on a concept (raises its trust tier)")
+        .argument("<ref>", "<bundle>/<concept-path>")
+        .option("--by <actor>", `Verifier actor (default: ${DEFAULT_ACTOR})`)
+        .action(async (ref, opts) => {
+        const { bundle, id } = splitRef(ref);
+        const actor = opts.by?.trim() || process.env.KRAFTWERK_ACTOR?.trim() || DEFAULT_ACTOR;
+        try {
+            const concept = await verifyConcept(await root(), bundle, id, actor);
+            console.log(`${chalk.green("✔")} ${ref} verified by ${actor} → ${tierColor(concept.trustTier)}`);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(2);
+        }
+    });
+    knowledge
+        .command("search")
+        .description("Full-text search across bundles")
+        .argument("<query>", "Search text (case-insensitive substring)")
+        .option("--bundle <name>", "Restrict to one bundle")
+        .option("--json", "Machine-readable output")
+        .action(async (query, opts) => {
+        const hits = await searchKnowledge(await root(), query, opts.bundle);
+        if (opts.json)
+            return void console.log(JSON.stringify({ query, hits }, null, 2));
+        if (hits.length === 0)
+            return void console.log(chalk.dim("No matches."));
+        for (const h of hits) {
+            console.log(`${chalk.cyan(`${h.bundle}/${h.id}`)} ${chalk.dim(`(${h.type ?? "?"})`)}\n  ${h.snippet}`);
+        }
+    });
+    knowledge
+        .command("init")
+        .description("Create an empty bundle (index.md + log.md)")
+        .argument("<bundle>", "Bundle name")
+        .action(async (bundle) => {
+        try {
+            const dir = await initBundle(await root(), bundle);
+            console.log(`${chalk.green("✔")} bundle ${chalk.cyan(bundle)} created at ${dir}`);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(2);
+        }
+    });
+    knowledge
+        .command("validate")
+        .description("OKF conformance check (errors) + provenance/staleness warnings")
+        .argument("[bundle]", "Bundle name; without it: all bundles")
+        .action(async (bundle) => {
+        const kroot = await root();
+        const bundles = bundle ? [bundle] : (await listBundles(kroot)).map((b) => b.name);
+        let errors = 0;
+        for (const b of bundles) {
+            const issues = await validateBundle(kroot, b);
+            printIssues(issues);
+            errors += issues.filter((i) => i.level === "error").length;
+        }
+        if (errors === 0)
+            console.log(chalk.green(`✔ ${bundles.length} bundle(s) conformant`));
+        process.exit(errors > 0 ? 1 : 0);
+    });
+    knowledge
+        .command("fsck")
+        .description("Validate all bundles; --fix regenerates every derived index.md")
+        .option("--fix", "Regenerate index.md files (heals out-of-band writes)")
+        .action(async (opts) => {
+        const issues = await fsck(await root(), !!opts.fix);
+        printIssues(issues);
+        if (opts.fix)
+            console.log(chalk.green("✔ indexes regenerated"));
+        process.exit(issues.some((i) => i.level === "error") ? 1 : 0);
+    });
+}