@netnodeag/kraftwerk 0.47.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
@@ -193,6 +194,16 @@ run-artifact directory (default `output/`), `knowledge:` the OKF bundle root
 `public:` and `tunnel:` expose the inspector through a
 [Cloudflare Tunnel](#inspector-through-a-cloudflare-tunnel).
 
+A `.env` next to kraftwerk.yml (`KEY=value` lines, `#` comments, quotes)
+is loaded into every kraftwerk process at start: `kraftwerk ui` and the
+server it supervises, so a restart from the UI re-reads the file; the chat
+agents, routines and workflow runs the inspector spawns; the tunnel
+(`TUNNEL_TOKEN`); `requires:` checks in `run` and `doctor`. A variable the
+shell already sets wins over the file. A project started from another
+workspace's inspector gets its own `.env`, not the other one's. The file is
+never synced (it is on the workspace git's deny list and in the .gitignore
+`kraftwerk init` writes); `kraftwerk doctor` lists the names it loaded.
+
 `switcher:` links other kraftwerk workspaces from the inspector header. The
 workspace name becomes a dropdown listing them:
 
@@ -207,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
@@ -370,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
@@ -393,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

@@ -5,6 +5,7 @@ import chalk from "chalk";
 import { ignoreEntryFor, isDir, publicHostFor, reposRootFor, resolveProject, tunnelFor } from "../config.js";
 import { discoverWorkflows } from "../discover.js";
 import { missingEnv } from "../yaml.js";
+import { applyDotenv, DOTENV_FILE } from "../dotenv.js";
 const ICONS = {
     ok: chalk.green("✔"),
     warn: chalk.yellow("⚠"),
@@ -87,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"]) {
@@ -106,6 +113,16 @@ export async function runDoctor(cwd) {
             }
         }
     }
+    // .env next to kraftwerk.yml: already applied by the CLI hook; this call
+    // only reports what it holds (names, never values).
+    const dotenv = await applyDotenv(project.root);
+    if (dotenv.file) {
+        const names = [...dotenv.applied, ...dotenv.kept.map((k) => `${k} (shell wins)`)];
+        report("ok", `${DOTENV_FILE}: ${names.length} variable(s) loaded`, names.join(", ") || "empty");
+    }
+    else {
+        report("info", `no ${DOTENV_FILE}`, "variables for agents, workflows and the tunnel can live there — loaded on every start and restart");
+    }
     // Repositories: the clones root must stay out of the workspace git. git
     // itself decides — that covers worktrees (.git is a file), a workspace
     // nested in a larger repo, a .gitignore at the toplevel, global excludes.

package/dist/cli/init.js

@@ -2,6 +2,7 @@ import { appendFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import chalk from "chalk";
 import { CONFIG_SCHEMA_URL, gitignoreHas, SCHEMA_URL } from "../config.js";
+import { DOTENV_FILE } from "../dotenv.js";
 import { initBundle, writeConcept } from "../okf.js";
 /**
  * `kraftwerk init` — make any repository a kraftwerk consumer in one
@@ -25,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
@@ -133,24 +135,24 @@ export async function runInit(cwd) {
         await writeConcept(knowledgeRoot, DEMO_BUNDLE, "playbooks/refunds", DEMO_CONCEPT, "kraftwerk-init");
         created.push(bundleRel);
     }
-    // .gitignore: the output dir and the repos root (clones must never become
-    // gitlinks of the workspace repo). A missing file gets both in one write;
-    // an existing one only the entries it lacks.
+    // .gitignore: the output dir, the repos root (clones must never become
+    // gitlinks of the workspace repo) and .env (secrets). A missing file gets
+    // all in one write; an existing one only the entries it lacks.
     const gitignorePath = path.join(cwd, ".gitignore");
     const gitignore = (await readFile(gitignorePath, "utf8").catch(() => null)) ?? null;
-    const entries = [`${DATA_DIR}/output`, `${DATA_DIR}/repos`];
+    const entries = [`${DATA_DIR}/output/`, `${DATA_DIR}/repos/`, DOTENV_FILE];
     if (gitignore === null) {
-        await writeFile(gitignorePath, entries.map((e) => `${e}/\n`).join(""));
+        await writeFile(gitignorePath, entries.map((e) => `${e}\n`).join(""));
         created.push(".gitignore");
     }
     else {
-        const missing = entries.filter((e) => !gitignoreHas(gitignore, e));
+        const missing = entries.filter((e) => !gitignoreHas(gitignore, e.replace(/\/$/, "")));
         if (missing.length === 0) {
             skipped.push(".gitignore");
         }
         else {
-            await appendFile(gitignorePath, `${gitignore.endsWith("\n") ? "" : "\n"}${missing.map((e) => `${e}/\n`).join("")}`);
-            created.push(`.gitignore (${missing.map((e) => `${e}/`).join(", ")} added)`);
+            await appendFile(gitignorePath, `${gitignore.endsWith("\n") ? "" : "\n"}${missing.map((e) => `${e}\n`).join("")}`);
+            created.push(`.gitignore (${missing.join(", ")} added)`);
         }
     }
     for (const f of created)

package/dist/cli/kraftwerk.js

@@ -13,9 +13,12 @@ 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";
+import { applyDotenv } from "../dotenv.js";
+import { resolveProject } from "../config.js";
 import { registerRoutineCommands } from "./routines.js";
 import { listRuns, showRun } from "./runs.js";
 import { runUi } from "./ui.js";
@@ -29,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
@@ -61,7 +66,15 @@ const pkg = JSON.parse(await readFile(new URL("../../package.json", import.meta.
 const program = new Command()
     .name("kraftwerk")
     .description("kraftwerk — agentic workspace for teams: agents, skills, knowledge, workflows, and the inspector UI")
-    .version(pkg.version);
+    .version(pkg.version)
+    // The project's .env, before any command runs (and so before `kraftwerk
+    // ui` spawns its server, and again in that server on every restart). A
+    // broken kraftwerk.yml is the command's own error to report, not the hook's.
+    .hook("preAction", async () => {
+    const project = await resolveProject(process.cwd()).catch(() => null);
+    if (project)
+        await applyDotenv(project.root);
+});
 const agentLabel = (workflow) => workflow.meta.agents
     .map((a) => {
     const where = [a.harness && a.harness !== "claude" ? a.harness : "", a.protocol === "acp" ? "acp" : ""]
@@ -269,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;