@netnodeag/kraftwerk 0.48.0 → 0.49.0

package/README.md

@@ -94,7 +94,7 @@ newer version is on disk, right after "update now" or after a manual install.
 
 ```bash
 npm install -g @netnodeag/kraftwerk@latest
-kraftwerk projects                 # every workspace on this machine, running or not
+kraftwerk workspaces               # every workspace on this machine, running or not
 ```
 
 ## Consume
@@ -156,7 +156,8 @@ kraftwerk run                           # interactive: pick workflow, type the r
 kraftwerk runs                          # past runs from output/*/trace.jsonl; runs show <id> for detail
 kraftwerk knowledge                     # Knowledge: OKF bundles (list/get/put/verify/search/...)
 kraftwerk ui                            # inspector web UI on http://localhost:1981; --port, --output
-kraftwerk projects                      # every workspace on this machine; projects start|stop|forget <ref>
+kraftwerk workspaces                    # every workspace on this machine; workspaces start|stop|forget <ref>
+kraftwerk projects                      # goal-scoped project folders; projects create|show|link|log|remove
 kraftwerk doctor                        # preflight: harness CLIs, docker, workflows, declared env vars
 kraftwerk validate                      # all discovered: schema + semantics + files, exit 1 on failure
 kraftwerk validate src/workflows/pitch  # specific paths
@@ -217,8 +218,8 @@ switcher:
 letters of an agent's or channel's name, description or workspace and hit
 enter to jump to it. It lists the active agents and the channels of every
 workspace on this machine, grouped by workspace and running or not (a
-stopped one is started on the way), read from the project registry under
-`~/.kraftwerk/projects`, which every inspector keeps current with its
+stopped one is started on the way), read from the workspace registry under
+`~/.kraftwerk/workspaces`, which every inspector keeps current with its
 roster and channel list.
 
 ### Triggering from CI, cron, or webhooks
@@ -380,7 +381,7 @@ working without a login. `kraftwerk doctor` reports the tunnel, the Access
 block and whether cloudflared is installed.
 
 **Variants.** `kraftwerk tunnel` runs the configured tunnel alone, for an
-inspector that already runs elsewhere (started by `kraftwerk projects
+inspector that already runs elsewhere (started by `kraftwerk workspaces
 start`, or in a container). For a tunnel created in the Zero Trust
 dashboard instead (Networks → Tunnels), leave `name` out, route the
 hostname to `http://localhost:<port>` there and export its token as
@@ -403,6 +404,96 @@ Quick tunnels (`trycloudflare.com`) are deliberately not supported: Access
 cannot be attached to them, which would leave the UI open to anyone with
 the URL.
 
+## Projects
+
+Turn on `projects:` in `kraftwerk.yml` (or the checkbox in settings) and
+the workspace gets one folder per project — a goal with everything the
+agents need to reach it:
+
+```yaml
+projects:
+  root: kraftwerk-data/projects   # default; part of the workspace, synced like agents and knowledge
+```
+
+```
+kraftwerk-data/projects/<slug>/
+  project.yml   # title, status, goal, records, links
+  brief.md      # the goal in full: what done looks like, constraints, stakeholders
+  state.md      # current state, rewritten at the end of a session
+  log.md        # append-only, newest first: decisions and milestones, dated and attributed
+```
+
+`project.yml` holds the one-line goal, a status (`active`, `paused`, `done`,
+`archived`), the harness, model and effort its chats run on (the same three
+fields an agent has; the harness decides, not the caller), the **systems of
+record** and the **links**:
+
+```yaml
+title: Relaunch netnode.ch
+status: active
+goal: Ship the new site on NodeHive by 2026-11-30
+harness: claude                 # claude | codex | pi — every chat in the project runs on it
+model: sonnet                   # optional, like an agent's
+effort: high                    # optional: low | medium | high | xhigh | max
+records:
+  - kind: my-netnode            # my-netnode | google-drive | github | bitbucket | notion | slack | url | anything
+    workspace: 22
+    url: https://my.netnode.ch/workspace/22
+    note: tickets, roadmap and meetings
+  - kind: google-drive
+    title: Contracts and briefs
+    url: https://drive.google.com/drive/folders/…
+knowledge: [netnode-helpdesk]          # OKF bundle names
+vibeables: [launch-tracker]            # folders under the vibeables root
+repos: [netnode-frontend]              # folders under the repos root
+workflows: [website-check]             # workflow slugs
+agents: [max]                          # agent slugs
+```
+
+A system of record says where the truth of the project is managed outside
+kraftwerk and what usually lives there. It is context, not a credential and
+not a grant: the agent reaches it through the tools its harness already has
+(a CLI, an MCP server, the browser), and the harness decides what it may
+call. Kraftwerk knows a few kinds only to label them and phrase the context
+better; any other kind passes through as a link with a note.
+
+Links are one-directional lists of slugs. A target that does not exist is
+shown as "not found" on the project page and told to the agent, never an
+error — the same rule an agent's knowledge list follows.
+
+**Working in a project is chat.** The Projects screen lists the projects,
+the chats of the selected one, and the thread; opening a project opens its
+latest chat. A session scoped to a project starts with the brief, the
+current state, the records, every link with how to reach it, and the rule
+for keeping the project current: `state.md` is rewritten at the end of a
+session that changed something, so the next session (by anyone) continues
+without the transcript; `log.md` is appended through
+`kraftwerk projects log <slug> "<line>" --actor <who>` so every line is
+dated and attributed; `brief.md` belongs to the user. The working
+directory stays the workspace root, so linked repositories and knowledge
+are reachable by path; opening a vibeable moves it into the app folder as
+in any chat.
+
+**Coworkers.** "Add coworker" on a project chat works as on an agent
+session: the chat becomes a channel whose members are the agents you pick,
+with everything said so far and the project's brief, state, records and
+links as context for every member (`project:` in `channel.yml`). The
+channel lives on the channels screen and stays listed under the project.
+The first agent picked answers messages that mention nobody.
+
+```bash
+kraftwerk projects                                   # list: title, status, goal, links
+kraftwerk projects create "Relaunch netnode.ch" --goal "Ship by November"
+kraftwerk projects show relaunch-netnode-ch          # definition, records, link states, state, log
+kraftwerk projects set relaunch-netnode-ch --harness codex --model gpt-5.6-sol --effort high
+kraftwerk projects link relaunch-netnode-ch workflows website-check
+kraftwerk projects log relaunch-netnode-ch "Decided on NodeHive." --actor human:lukas
+kraftwerk projects remove relaunch-netnode-ch
+```
+
+The registry of workspaces on this machine, which answered to
+`kraftwerk projects` until 0.48, is `kraftwerk workspaces` now.
+
 ## Persistent agents
 
 The inspector's "agents" screen turns chat agents into persistent teammates. An

package/dist/cli/doctor.js

@@ -88,7 +88,13 @@ export async function runDoctor(cwd) {
     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");
+        // Blocks (git, repos, vibeables, projects, tunnel) print as their keys, not [object Object].
+        const show = (v) => typeof v === "object" && v !== null
+            ? Array.isArray(v)
+                ? `[${v.length}]`
+                : `{${Object.entries(v).map(([k, x]) => `${k}: ${show(x)}`).join(", ") || " "}}`
+            : String(v);
+        report("ok", `${path.basename(project.configPath)} well-formed`, keys.length ? keys.map((k) => `${k}: ${show(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");
         for (const key of ["workflows", "knowledge", "agents", "output"]) {

package/dist/cli/init.js

@@ -26,6 +26,7 @@ skills: ${DATA_DIR}/skills         # workspace skills (shared instruction packag
 # repos:                          # git repositories the agents work on (uncomment both lines to enable)
 #   root: ${DATA_DIR}/repos       # clones land here (git-ignored); a bare \`repos:\` uses repos/ instead
 # vibeables:                      # small apps built live in a chat with a preview pane (uncomment to enable; one folder per app under ${DATA_DIR}/vibeables, versioned with the workspace)
+# projects:                       # goal-scoped folders — brief, systems of record, links to knowledge/vibeables/repos/workflows/agents — that chats work in (uncomment to enable; one folder per project under ${DATA_DIR}/projects)
 # public: https://kw.example.com  # hostname the inspector is reached at through a tunnel or reverse proxy
 # tunnel:                         # Cloudflare Tunnel run by \`kraftwerk ui\` (needs public:; put a Cloudflare Access policy on the hostname — the UI has no login of its own)
 #   name: kraftwerk               # locally-managed tunnel (cloudflared tunnel create/route dns); omit and export TUNNEL_TOKEN for a dashboard-managed one

package/dist/cli/kraftwerk.js

@@ -13,6 +13,7 @@ import { runDoctor } from "./doctor.js";
 import { runInit } from "./init.js";
 import { registerKnowledgeCommands } from "./knowledge.js";
 import { registerProjectCommands } from "./projects.js";
+import { registerWorkspaceCommands } from "./workspaces.js";
 import { registerRepoCommands } from "./repos.js";
 import { registerVibeableCommands } from "./vibeables.js";
 import { registerTunnelCommands } from "./tunnel.js";
@@ -31,7 +32,9 @@ import { runUi } from "./ui.js";
  *   kraftwerk knowledge ...           Knowledge: OKF bundles (list/get/put/verify/...)
  *   kraftwerk routines ...            per-agent scheduled prompts (list/add/remove/enable/run)
  *   kraftwerk ui                      start the inspector web UI (localhost:1981)
- *   kraftwerk projects ...            known projects on this machine (list/start/forget)
+ *   kraftwerk workspaces ...          known workspaces on this machine (list/start/stop/forget)
+ *   kraftwerk projects ...            goal-scoped project folders (list/create/show/link/log/remove)
+ *   kraftwerk vibeables ...           small apps built live in a chat (list/create/remove)
  *   kraftwerk repos ...               repositories the agents work on (list/add/update/remove)
  *   kraftwerk tunnel [setup <host>]   Cloudflare Tunnel to the inspector: run it alone, or set one up
  *   kraftwerk doctor                  preflight: harness CLIs, docker, workflows, env
@@ -279,6 +282,7 @@ runs
 });
 registerKnowledgeCommands(program);
 registerRoutineCommands(program);
+registerWorkspaceCommands(program);
 registerProjectCommands(program);
 registerRepoCommands(program);
 registerVibeableCommands(program);

package/dist/cli/projects.d.ts

@@ -1,16 +1,2 @@
 import type { Command } from "commander";
-/**
- * `kraftwerk projects` — every project that ever ran the inspector on this
- * machine (~/.kraftwerk/projects), joined with what is running right now.
- * The answer to "where did I start that UI, and how do I get it back":
- *
- *   kraftwerk projects                 list: name, root, running/stopped
- *   kraftwerk projects start <ref>     relaunch `kraftwerk ui` in that root, detached
- *   kraftwerk projects stop <ref>      SIGTERM a running UI (also ones started in a terminal)
- *   kraftwerk projects forget <ref>    drop the record (the folder stays)
- *
- * <ref> is a project name, the root's folder name, the root path, or a
- * port / localhost:port for running instances that recorded no root.
- */
-export declare const fmtAgo: (iso?: string) => string;
 export declare function registerProjectCommands(program: Command): void;

package/dist/cli/projects.js

@@ -1,149 +1,223 @@
-import path from "node:path";
 import chalk from "chalk";
-import { absolutePath } from "../config.js";
 import Table from "cli-table3";
-import { discoverWorkspaces, forgetProject, startProject, stopProject, tildify, } from "../inspector/instances.js";
+import { readFile } from "node:fs/promises";
+import { appendProjectLog, createProject, deleteProject, getProject, linkProject, listProjects, LINK_KINDS, recordLine, saveProject, } from "../inspector/projects.js";
+import { initContext as prepare } from "./routines.js";
+import { fmtAgo } from "./workspaces.js";
 /**
- * `kraftwerk projects` — every project that ever ran the inspector on this
- * machine (~/.kraftwerk/projects), joined with what is running right now.
- * The answer to "where did I start that UI, and how do I get it back":
+ * `kraftwerk projects` — the goal-scoped folders under the projects root
+ * (`projects.root` in kraftwerk.yml): a brief, the systems of record, and
+ * links to knowledge, vibeables, repositories, workflows and agents. The
+ * same module the inspector uses, so a project created here shows up in
+ * the UI at once, and an agent in a project chat uses `log` and `link`
+ * to keep the project current:
  *
- *   kraftwerk projects                 list: name, root, running/stopped
- *   kraftwerk projects start <ref>     relaunch `kraftwerk ui` in that root, detached
- *   kraftwerk projects stop <ref>      SIGTERM a running UI (also ones started in a terminal)
- *   kraftwerk projects forget <ref>    drop the record (the folder stays)
+ *   kraftwerk projects                              list: title, status, goal, links
+ *   kraftwerk projects create <title> [--goal ..]   new folder from the starter (project.yml, brief, state, log); --harness/--model/--effort
+ *   kraftwerk projects set <slug> [--harness ..]    change harness, model, effort, status or goal
+ *   kraftwerk projects show <slug>                  definition, links (found / missing), records, state, log
+ *   kraftwerk projects link <slug> <kind> <name>    add a knowledge|vibeables|repos|workflows|agents link
+ *   kraftwerk projects unlink <slug> <kind> <name>  remove one
+ *   kraftwerk projects log <slug> "<entry>"         append a stamped line to log.md (--actor)
+ *   kraftwerk projects remove <slug>                delete the folder (its history stays in the workspace git)
  *
- * <ref> is a project name, the root's folder name, the root path, or a
- * port / localhost:port for running instances that recorded no root.
+ * The workspace registry answered to this name until 0.48; it is
+ * `kraftwerk workspaces` now (workspaces.ts).
  */
-export const fmtAgo = (iso) => {
-    if (!iso)
-        return "—";
-    const s = Math.max(0, (Date.now() - Date.parse(iso)) / 1000);
-    if (s < 90)
-        return "just now";
-    if (s < 5400)
-        return `${Math.round(s / 60)} min ago`;
-    if (s < 129600)
-        return `${Math.round(s / 3600)} h ago`;
-    return `${Math.round(s / 86400)} d ago`;
+const die = (msg) => {
+    console.error(chalk.red(msg));
+    process.exit(1);
 };
-/**
- * Running → its url. Not running: "stopped" after a clean shutdown, "died"
- * when the last start has no matching stop (killed, crashed, terminal
- * closed) — the case this command exists for.
- */
-const status = (e) => {
-    if (e.live)
-        return chalk.green(`● ${e.url.replace(/^https?:\/\//, "")}`);
-    if (e.exists === false)
-        return chalk.red("path missing");
-    const clean = !!e.lastStopped && !!e.lastStarted && e.lastStopped >= e.lastStarted;
-    return clean ? chalk.dim("stopped") : chalk.yellow("died");
-};
-/** Match a ref against known workspaces; `needRoot` excludes rootless live instances (start/forget need a root). */
-async function resolveRef(ref, needRoot = true) {
-    const all = (await discoverWorkspaces()).filter((e) => e.root || !needRoot);
-    const abs = absolutePath(ref);
-    const port = /^\d+$/.test(ref) ? `http://localhost:${ref}` : `http://${ref.replace(/^https?:\/\//, "")}`;
-    const hits = all.filter((e) => e.root === abs ||
-        e.root === ref ||
-        e.name === ref ||
-        (e.root && path.basename(e.root) === ref) ||
-        e.url === port);
-    if (hits.length === 1)
-        return hits[0];
-    if (hits.length === 0) {
-        console.error(chalk.red(`No known project "${ref}". See \`kraftwerk projects\`.`));
-        process.exit(2);
+const linkSummary = (p) => LINK_KINDS.map((k) => (p[k].length ? `${p[k].length} ${k}` : ""))
+    .filter(Boolean)
+    .join(", ");
+function printDetail(p) {
+    console.log(`${chalk.bold(p.title)} ${chalk.dim(`(${p.slug}, ${p.status})`)}`);
+    console.log(p.goal ? p.goal : chalk.dim("(no goal yet)"));
+    console.log(chalk.dim(`runs on ${p.harness}${p.model ? ` · ${p.model}` : ""}${p.effort ? ` · effort ${p.effort}` : ""}`));
+    console.log(chalk.dim(p.path));
+    if (p.configError)
+        console.log(chalk.red(`project.yml: ${p.configError}`));
+    if (p.records.length) {
+        console.log(`\n${chalk.bold("systems of record")}`);
+        for (const r of p.records)
+            console.log(recordLine(r));
+    }
+    for (const kind of LINK_KINDS) {
+        if (!p.links[kind].length)
+            continue;
+        console.log(`\n${chalk.bold(kind)}`);
+        for (const l of p.links[kind]) {
+            console.log(l.found ? `  ${chalk.green("✔")} ${l.slug}${l.label ? chalk.dim(`  ${l.label}`) : ""}` : `  ${chalk.yellow("?")} ${l.slug} ${chalk.dim("(not found)")}`);
+        }
     }
-    console.error(chalk.red(`"${ref}" is ambiguous — use the root path or port:`));
-    for (const h of hits)
-        console.error(`  ${h.root ?? h.url}`);
-    process.exit(2);
+    if (p.state.trim())
+        console.log(`\n${chalk.bold("state.md")}\n${p.state.trim()}`);
+    if (p.log.trim())
+        console.log(`\n${chalk.bold("log.md")}\n${p.log.trim()}`);
 }
 export function registerProjectCommands(program) {
     const projects = program
         .command("projects")
-        .description("Known kraftwerk projects on this machine: list, start a stopped UI, stop a running one, forget");
+        .description("Projects: a goal with its brief, systems of record and links, worked on in chat — list, create, link, log");
     projects
         .command("list", { isDefault: true })
-        .description("List known projects with their root and whether the UI is running")
+        .description("List the projects under the projects root")
         .option("--json", "Machine-readable output")
         .action(async (opts) => {
-        const entries = await discoverWorkspaces();
+        await prepare();
+        const view = await listProjects();
         if (opts.json) {
-            console.log(JSON.stringify(entries, null, 2));
+            console.log(JSON.stringify(view, null, 2));
             return;
         }
-        if (entries.length === 0) {
-            console.log(chalk.dim("No projects known yet — `kraftwerk ui` registers the current one."));
+        if (!view.enabled)
+            die(view.error ?? "projects are off");
+        if (view.projects.length === 0) {
+            console.log(chalk.dim(`No projects under ${view.root} yet — \`kraftwerk projects create "<title>"\` starts one.`));
             return;
         }
         const table = new Table({
-            head: ["project", "root", "status", "last started"].map((h) => chalk.bold(h)),
+            head: ["project", "status", "goal", "links", "changed"].map((h) => chalk.bold(h)),
             wordWrap: true,
-            colWidths: [22, 48, 24, 14],
+            colWidths: [26, 10, 40, 24, 14],
         });
-        for (const e of entries) {
+        for (const p of view.projects) {
             table.push([
-                `${e.icon ? e.icon + " " : ""}${chalk.cyan(e.name)}`,
-                e.rootLabel ?? chalk.dim("(no root recorded)"),
-                status(e),
-                fmtAgo(e.lastStarted),
+                `${chalk.cyan(p.title)}\n${chalk.dim(p.slug)}`,
+                p.status === "active" ? chalk.green(p.status) : chalk.dim(p.status),
+                p.configError ? chalk.red(p.configError) : p.goal || chalk.dim("—"),
+                chalk.dim(linkSummary(p) || "—"),
+                chalk.dim(fmtAgo(p.updatedAt)),
             ]);
         }
         console.log(table.toString());
+        console.log(chalk.dim(view.root ?? ""));
     });
     projects
-        .command("start")
-        .description("Relaunch the UI of a stopped project (detached; logs in ~/.kraftwerk/logs)")
-        .argument("<ref>", "Project name, folder name, or root path")
-        .action(async (ref) => {
-        const entry = await resolveRef(ref);
-        if (entry.live) {
-            console.log(`${chalk.green("✔")} ${entry.name} already running: ${chalk.cyan(entry.url)}`);
-            return;
+        .command("create")
+        .description("Create a project folder from the starter (project.yml, brief.md, state.md, log.md)")
+        .argument("<title>", "Display title; the folder name is derived from it unless --slug is given")
+        .option("--goal <text>", "One-line goal")
+        .option("--slug <slug>", "Folder name under the root (lowercase, digits, dashes)")
+        .option("--harness <harness>", "Harness every chat in the project runs on: claude | codex | pi (default: claude)")
+        .option("--model <model>", "Model for that harness (default: the harness default)")
+        .option("--effort <effort>", "Reasoning effort: low | medium | high | xhigh | max")
+        .option("--json", "Print the new project as JSON")
+        .action(async (title, opts) => {
+        await prepare();
+        try {
+            const p = await createProject({ title, goal: opts.goal, slug: opts.slug, harness: opts.harness, model: opts.model, effort: opts.effort });
+            if (opts.json)
+                console.log(JSON.stringify(p, null, 2));
+            else
+                console.log(`${chalk.green("✔")} ${chalk.cyan(p.slug)} → ${p.path} ${chalk.dim("(open it on the Projects screen, or `kraftwerk projects show " + p.slug + "`)")}`);
         }
-        const r = await startProject(entry.root);
-        if (!r.ok) {
-            console.error(chalk.red(`Could not start ${entry.name}: ${r.error}`));
-            if (r.log)
-                console.error(chalk.dim(`log: ${tildify(r.log)}`));
-            process.exit(1);
+        catch (err) {
+            die(err.message);
         }
-        console.log(`${chalk.green("✔")} ${entry.name} ${r.live ? "running" : "starting"}: ${chalk.cyan(r.url)}` +
-            chalk.dim(` (pid ${r.pid}${r.log ? `, log ${tildify(r.log)}` : ""})`));
     });
     projects
-        .command("stop")
-        .description("Stop a running UI (SIGTERM to its server; works for terminal-started ones too)")
-        .argument("<ref>", "Project name, folder name, root path, or port")
-        .action(async (ref) => {
-        const entry = await resolveRef(ref, false);
-        if (!entry.live) {
-            console.log(chalk.dim(`${entry.name} is not running.`));
-            return;
+        .command("show")
+        .description("Show one project: definition, records, links with their state, state.md and log.md")
+        .argument("<slug>", "Folder name under the root")
+        .option("--json", "Machine-readable output")
+        .action(async (slug, opts) => {
+        await prepare();
+        try {
+            const p = await getProject(slug);
+            if (!p)
+                die(`no project "${slug}"`);
+            if (opts.json)
+                console.log(JSON.stringify(p, null, 2));
+            else
+                printDetail(p);
+        }
+        catch (err) {
+            die(err.message);
+        }
+    });
+    projects
+        .command("set")
+        .description("Change the project's harness, model, effort, status or goal (like an agent's settings)")
+        .argument("<slug>", "Project folder name")
+        .option("--harness <harness>", "claude | codex | pi")
+        .option("--model <model>", 'Model for the harness; "" for the default')
+        .option("--effort <effort>", 'low | medium | high | xhigh | max; "" for the default')
+        .option("--status <status>", "active | paused | done | archived")
+        .option("--goal <text>", "One-line goal")
+        .option("--json", "Print the project as JSON")
+        .action(async (slug, opts) => {
+        await prepare();
+        const { json: asJson, ...fields } = opts;
+        if (Object.values(fields).every((v) => v === undefined))
+            die("nothing to set — pass --harness, --model, --effort, --status or --goal");
+        try {
+            const p = await saveProject(slug, fields);
+            if (asJson)
+                console.log(JSON.stringify(p, null, 2));
+            else
+                console.log(`${chalk.green("✔")} ${chalk.cyan(p.slug)} runs on ${p.harness}${p.model ? ` · ${p.model}` : ""}${p.effort ? ` · effort ${p.effort}` : ""} ${chalk.dim(`(${p.status})`)}`);
+        }
+        catch (err) {
+            die(err.message);
+        }
+    });
+    for (const verb of ["link", "unlink"]) {
+        projects
+            .command(verb)
+            .description(verb === "link" ? "Add a linked knowledge bundle, vibeable, repository, workflow or agent" : "Remove a link")
+            .argument("<slug>", "Project folder name")
+            .argument("<kind>", `One of ${LINK_KINDS.join(", ")}`)
+            .argument("<name>", "The target's name (bundle, folder, workflow or agent slug)")
+            .option("--json", "Print the project as JSON")
+            .action(async (slug, kind, name, opts) => {
+            await prepare();
+            try {
+                const p = await linkProject(slug, kind, name, verb === "unlink");
+                if (opts.json)
+                    console.log(JSON.stringify(p, null, 2));
+                else {
+                    const state = p.links[kind]?.find((l) => l.slug === name);
+                    const note = verb === "link" && state && !state.found ? chalk.yellow(" (not found in this workspace yet)") : "";
+                    console.log(`${chalk.green("✔")} ${verb === "link" ? "linked" : "unlinked"} ${kind} ${chalk.cyan(name)} ${verb === "link" ? "to" : "from"} ${p.slug}${note}`);
+                }
+            }
+            catch (err) {
+                die(err.message);
+            }
+        });
+    }
+    projects
+        .command("log")
+        .description("Append a dated, attributed line to the project's log.md (newest first)")
+        .argument("<slug>", "Project folder name")
+        .argument("[entry]", "The line to record; omit with --file")
+        .option("--file <path>", "Read the entry from a file")
+        .option("--actor <actor>", "Who writes: human:<id>, <agent>/<harness>, process:<id>", "human:user")
+        .action(async (slug, entry, opts) => {
+        await prepare();
+        try {
+            const text = opts.file ? await readFile(opts.file, "utf8") : entry ?? "";
+            await appendProjectLog(slug, text, opts.actor);
+            console.log(`${chalk.green("✔")} logged to ${chalk.cyan(slug)} ${chalk.dim(`(${opts.actor})`)}`);
         }
-        const r = await stopProject({ root: entry.root, url: entry.url });
-        if (!r.ok) {
-            console.error(chalk.red(`Could not stop ${entry.name}: ${r.error}`));
-            process.exit(1);
+        catch (err) {
+            die(err.message);
         }
-        console.log(`${chalk.green("✔")} ${entry.name} stopped ${chalk.dim(`(${entry.url.replace(/^https?:\/\//, "")})`)}`);
     });
     projects
-        .command("forget")
-        .description("Remove a project from the registry (its folder is untouched)")
-        .argument("<ref>", "Project name, folder name, or root path")
-        .action(async (ref) => {
-        const entry = await resolveRef(ref);
-        if (await forgetProject(entry.root)) {
-            console.log(`${chalk.green("✔")} forgot ${entry.name} (${entry.rootLabel})`);
+        .command("remove")
+        .description("Delete a project folder; its history stays in the workspace git")
+        .argument("<slug>", "Folder name under the root")
+        .action(async (slug) => {
+        await prepare();
+        try {
+            await deleteProject(slug);
+            console.log(`${chalk.green("✔")} removed ${chalk.cyan(slug)}`);
         }
-        else {
-            console.error(chalk.red(`No record for ${entry.root}`));
-            process.exit(1);
+        catch (err) {
+            die(err.message);
         }
     });
 }

package/dist/cli/repos.js

@@ -1,7 +1,7 @@
 import chalk from "chalk";
 import Table from "cli-table3";
 import { addRepo, listRepos, removeRepo, updateRepo } from "../inspector/repos.js";
-import { fmtAgo } from "./projects.js";
+import { fmtAgo } from "./workspaces.js";
 import { initContext as prepare } from "./routines.js";
 /**
  * `kraftwerk repos` — the git repositories the agents work on, kept under

package/dist/cli/ui.js

@@ -69,7 +69,7 @@ export async function runUi(cwd, opts) {
  * local node_modules, npx, and a file: dev checkout. Any exit other than
  * RESTART_EXIT_CODE ends the loop. A SIGTERM/SIGINT to the supervisor is
  * forwarded to the server, so `kill <supervisor pid>` (what `kraftwerk
- * projects start` reports) takes the whole UI down; Ctrl-C signals the
+ * workspaces start` reports) takes the whole UI down; Ctrl-C signals the
  * foreground group and reaches both anyway.
  */
 async function superviseUi(cwd, opts) {

package/dist/cli/vibeables.js

@@ -1,7 +1,7 @@
 import chalk from "chalk";
 import Table from "cli-table3";
 import { createVibeable, deleteVibeable, listVibeables } from "../inspector/vibeables.js";
-import { fmtAgo } from "./projects.js";
+import { fmtAgo } from "./workspaces.js";
 import { initContext as prepare } from "./routines.js";
 /**
  * `kraftwerk vibeables` — the small apps built live in a chat, one folder

package/dist/cli/workspaces.d.ts

@@ -0,0 +1,16 @@
+import type { Command } from "commander";
+/**
+ * `kraftwerk workspaces` — every workspace that ever ran the inspector on this
+ * machine (~/.kraftwerk/workspaces), joined with what is running right now.
+ * The answer to "where did I start that UI, and how do I get it back":
+ *
+ *   kraftwerk workspaces                 list: name, root, running/stopped
+ *   kraftwerk workspaces start <ref>     relaunch `kraftwerk ui` in that root, detached
+ *   kraftwerk workspaces stop <ref>      SIGTERM a running UI (also ones started in a terminal)
+ *   kraftwerk workspaces forget <ref>    drop the record (the folder stays)
+ *
+ * <ref> is a workspace name, the root's folder name, the root path, or a
+ * port / localhost:port for running instances that recorded no root.
+ */
+export declare const fmtAgo: (iso?: string) => string;
+export declare function registerWorkspaceCommands(program: Command): void;