@netnodeag/kraftwerk 0.79.0 → 0.81.0

package/README.md

@@ -130,6 +130,9 @@ set up the rest. From there:
   Open one and chat with it; its sessions continue where they ended.
 - **Projects** gather a goal, a brief and links; every chat in a project
   starts with that context.
+- **Contacts, places and events** are the workspace's records of who, where
+  and when — one Markdown file each, referenced anywhere as `contact:<slug>`,
+  `place:<slug>`, `event:<slug>`.
 - **Workflows** are repeatable processes with checked results; run one from
   its page or with `kraftwerk run <workflow> "<request>"`.
 - **Knowledge** is the shared, human-verified context agents read.
@@ -256,6 +259,8 @@ kraftwerk workspaces                    # every workspace on this machine; works
 kraftwerk devices                       # paired devices (a phone, another computer); devices pair|revoke
 kraftwerk remote on|off|pair            # reach this machine from anywhere through the relay, end to end encrypted
 kraftwerk projects                      # goal-scoped project folders; projects create|show|link|log|remove
+kraftwerk contacts|places|events        # who, where and when, one Markdown file each; … show|create|set|remove, events --from/--to
+kraftwerk ref <kind:slug>               # resolve a reference (contact:anna-meier, project:relaunch, …); --file <md> resolves every one in a file
 kraftwerk trash                         # what was deleted; trash restore|purge <id>, trash empty
 kraftwerk journal <agent> ["<entry>"]   # an agent's memory across sessions: print it, add a line (--kind)
 kraftwerk doctor                        # preflight: harness CLIs, docker, workflows, declared env vars, legacy leftovers
@@ -295,7 +300,9 @@ Optional, at the project root, and also the root marker for the walk-up. All
 fields are optional. `workflows:` sets the workflows root, `output:` the
 run-artifact directory (default `output/`), `knowledge:` the OKF bundle root
 (default `knowledge/`), and `agents:` the agent-definition root (default
-`agents/`). `repos:` turns on the [repositories](#repositories) folder.
+`agents/`). `repos:` turns on the [repositories](#repositories) folder,
+`projects:` the [projects](#projects), and `contacts:`, `places:` and
+`events:` each one of the [contacts, places and events](#contacts-places-and-events).
 `cloud: { enabled: false }` leaves the workspace out of this machine's
 record in the [kraftwerk cloud](#this-machine-in-the-kraftwerk-cloud).
 
@@ -337,7 +344,8 @@ projects (all but archived ones) 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 workspace registry under `~/.kraftwerk/workspaces`,
 which every inspector keeps current with its roster, project and channel
-lists.
+lists — and this workspace's contacts, places and events, by title, role,
+organisation, address or date.
 
 ### Triggering from CI, cron, or webhooks
 
@@ -626,6 +634,84 @@ 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.
 
+## Contacts, places and events
+
+Who, where and when, kept by the workspace itself so people and agents can
+point at them reliably. Three features with one shape — turn each on in
+`kraftwerk.yml` (or its checkbox in settings):
+
+```yaml
+contacts:                         # people and organisations
+places:                           # addresses and points of interest
+events:                           # dated one-off entries
+  root: kraftwerk-data/events     # default kraftwerk-data/<kind>; part of the workspace, synced like agents and knowledge
+```
+
+One Markdown file per entry: the typed fields in YAML frontmatter, free
+notes in the body. Readable and editable by hand, by agents and by the UI;
+versioned with the workspace, deleted into the trash.
+
+```
+kraftwerk-data/contacts/anna-meier.md          # title, role, org, email, phone, place, url, tags, records + notes
+kraftwerk-data/places/netnode-office.md        # title, address, lat, lng, url, tags, records + notes
+kraftwerk-data/events/2026-11-03-kickoff.md    # title, start, end, place, contacts, project, url, tags, records + notes
+```
+
+```markdown
+---
+title: Kickoff
+start: 2026-11-03T14:00           # ISO date or date-time; events are one-off (recurrence lives in the calendar entry)
+end: 2026-11-03T16:00
+place: netnode-office             # a place's slug
+contacts: [anna-meier]            # contact slugs
+project: relaunch                 # a project's slug
+records:
+  - kind: calendar
+    url: https://calendar.google.com/event?eid=…
+---
+Agenda: scope, timeline, who does what.
+```
+
+**References.** Fields that point at other entries hold slugs, and anything
+in the workspace is referenced in text as `kind:slug` — `contact:anna-meier`,
+`place:netnode-office`, `event:2026-11-03-kickoff`, and likewise `project:`,
+`agent:`, `workflow:`, `repo:`, `vibeable:`, `knowledge:`. The same resolver
+serves a project's links, an event's place and contacts, a token in notes or
+in a chat reply, the ⌘K palette and the context an agent starts with: a
+target that does not exist is reported ("not found"), never an error, and
+only these tokens match, so `https:` never does. Projects link to contacts,
+places and events like to anything else (`kraftwerk projects link <slug>
+contacts anna-meier`), and a project chat starts with them as one-liners.
+
+**Systems of record.** As on a project: where the truth lives outside
+kraftwerk — a contact's CRM record and newsletter subscription (`crm`,
+`newsletter`), an event's calendar entry (`calendar`), a place on Google
+Maps (`google-maps`). A place without a maps record gets a Google Maps link
+derived from its coordinates or its address.
+
+**Agents** get a "Contacts, places and events" block in every chat: what
+exists, the next events, the token syntax and the CLI — they read and write
+the files through it, never by hand:
+
+```bash
+kraftwerk contacts                                   # list (--json); places, events the same
+kraftwerk contacts create "Anna Meier" --org ACME --email anna@acme.ch --place netnode-office
+kraftwerk contacts show anna-meier                   # fields, records, references with their state, notes
+kraftwerk contacts set anna-meier --role CTO --email ""   # "" clears a field; --notes-file replaces the notes
+kraftwerk places create "NETNODE Office" --address "Zentralstrasse 1, 6003 Luzern" --lat 47.05 --lng 8.3
+kraftwerk places show netnode-office                 # prints the Google Maps link
+kraftwerk events create "Kickoff" --start 2026-11-03T14:00 --place netnode-office --contacts anna-meier --project relaunch
+kraftwerk events --from 2026-11-01 --to 2026-11-30   # the month's events
+kraftwerk ref contact:anna-meier                     # ✔ with its label, or ? not found (exit 1); --file notes.md checks a whole file
+kraftwerk contacts remove anna-meier                 # to the trash
+```
+
+Over the API each kind is its own route family — `contacts.list|get|create|save|delete`,
+`places.*`, `events.*` (`GET /api/events?from=&to=`) — and `refs.resolve`
+resolves tokens or every reference found in a text. In the inspector each
+kind is a page of the workspace (expert mode) with the list beside the open
+entry; a project's context column shows its contacts, places and events.
+
 ## Files
 
 Files are the material of the work, in any format: briefings, contracts,

package/dist/cli/daemon.js

@@ -1,6 +1,7 @@
 import chalk from "chalk";
 import { DAEMON_PORT, daemonState, lastOpenRoots, setDaemonVersion, writeDaemonFile } from "../core/daemon.js";
 import { tildify } from "../core/instances.js";
+import { log } from "../core/log.js";
 import { networkUrls } from "../server/bind.js";
 import { startMachineCloud } from "../server/cloud.js";
 import { startPushWatcher } from "../server/push.js";
@@ -44,31 +45,31 @@ export async function runDaemon(opts) {
             await hub.open(root);
         }
         catch (err) {
-            console.log(`${chalk.yellow("⚠")} not reopened: ${tildify(root)} — ${err.message}`);
+            log("warn", "workspace", `not reopened: ${tildify(root)} — ${err.message}`);
         }
     }
-    console.log(`${chalk.green("✔")} kraftwerk daemon on ${chalk.cyan(`http://localhost:${hub.port}`)} ${chalk.dim(`(pid ${process.pid}, ${new Date().toISOString()})`)}`);
+    log("info", "daemon", `listening on http://localhost:${hub.port} (pid ${process.pid}, v${await getPkgVersion()})`);
     for (const o of hub.list())
-        console.log(`  ${chalk.cyan(o.url)} ${chalk.dim(o.name)}${o.aliasPort ? chalk.dim(` · also :${o.aliasPort}`) : ""}`);
+        log("info", "workspace", `open: ${o.url} (${o.name})${o.aliasPort ? ` · also :${o.aliasPort}` : ""}`);
     if (!hub.list().length)
-        console.log(chalk.dim("  no workspace open yet — `kraftwerk ui` in a workspace folder opens it here"));
+        log("info", "daemon", "no workspace open yet — `kraftwerk ui` in a workspace folder opens it here");
     // The machine in the kraftwerk cloud: registered once, the open workspaces as its children (`kraftwerk cloud`, `kraftwerk login`).
     const cloud = await startMachineCloud({ version: await getPkgVersion(), workspaces: () => hub.list(), owner: hub });
     if (cloud.state === "connected") {
-        console.log(`${chalk.green("✔")} Cloud: ${chalk.cyan(cloud.url)} ${chalk.dim(cloud.account ? `(claimed by ${cloud.account})` : `(unclaimed — \`kraftwerk login\` claims this machine)`)}`);
+        log("info", "cloud", `registered at ${cloud.url} ${cloud.account ? `(claimed by ${cloud.account})` : "(unclaimed — `kraftwerk login` claims this machine)"}`);
     }
     else if (cloud.state === "error") {
-        console.log(`${chalk.yellow("⚠")} Cloud: ${cloud.url} unreachable — ${cloud.error ?? "no answer"} ${chalk.dim("(retrying; nothing else depends on it)")}`);
+        log("warn", "cloud", `${cloud.url} unreachable — ${cloud.error ?? "no answer"} (retrying; nothing else depends on it)`);
     }
     // The relay (`kraftwerk remote on`): devices reach this machine from anywhere, end to end encrypted.
-    const relay = await applyRelay(hub.port, await getPkgVersion(), (line) => console.log(chalk.dim(line)));
+    const relay = await applyRelay(hub.port, await getPkgVersion(), (level, line) => log(level, "relay", line));
     // What needs you, pushed to the phones that asked (through the relay, sealed per device).
     startPushWatcher(hub, relayPush);
     if (relay.state !== "off")
-        console.log(`${chalk.green("✔")} Reachable from anywhere through ${chalk.cyan(relay.url ?? "")} ${chalk.dim("(`kraftwerk remote pair` pairs a device)")}`);
+        log("info", "relay", `reachable from anywhere through ${relay.url ?? ""} (\`kraftwerk remote pair\` pairs a device)`);
     const lan = networkUrls(hub.port);
     if (lan.length)
-        console.log(`${chalk.green("✔")} On your network: ${lan.map((u) => chalk.cyan(u)).join(", ")} ${chalk.dim("(add /w/<slug>/; devices pair first)")}`);
+        log("info", "daemon", `on your network: ${lan.join(", ")} (add /w/<slug>/; devices pair first)`);
 }
 export function registerDaemonCommand(program) {
     const daemon = program

package/dist/cli/doctor.js

@@ -95,7 +95,7 @@ export async function runDoctor(cwd, opts = {}) {
     else {
         const cfg = project.config;
         const keys = Object.keys(cfg);
-        // Blocks (git, repos, vibeables, projects, cloud) print as their keys, not [object Object].
+        // Blocks (git, repos, vibeables, projects, contacts, places, events, cloud) print as their keys, not [object Object].
         const show = (v) => typeof v === "object" && v !== null
             ? Array.isArray(v)
                 ? `[${v.length}]`

package/dist/cli/entities.d.ts

@@ -0,0 +1,8 @@
+import type { Command } from "commander";
+import { type EntityKindDef } from "../core/entities.js";
+export declare function registerEntityCommands(program: Command, def: EntityKindDef<any>): void;
+export declare const registerContactCommands: (program: Command) => void;
+export declare const registerPlaceCommands: (program: Command) => void;
+export declare const registerEventCommands: (program: Command) => void;
+/** `kraftwerk ref` — resolve one reference, or every reference in a file. */
+export declare function registerRefCommand(program: Command): void;

package/dist/cli/entities.js

@@ -0,0 +1,222 @@
+import chalk from "chalk";
+import Table from "cli-table3";
+import { readFile } from "node:fs/promises";
+import { CONTACTS, createEntity, deleteEntity, EVENTS, getEntity, listEntities, PLACES, saveEntity } from "../core/entities.js";
+import { recordLine } from "../core/records.js";
+import { findRefs, resolveRef, resolveTokens } from "../core/refs.js";
+import { initContext as prepare } from "./routines.js";
+import { fmtAgo } from "./workspaces.js";
+/**
+ * `kraftwerk contacts|places|events` — the workspace's records of who,
+ * where and when, one Markdown file each (core/entities.ts). One command
+ * group per kind, built from the kind's definition so the options are its
+ * fields; the same module the inspector uses, so an entry created here
+ * shows up in the UI at once, and an agent uses these to keep them current:
+ *
+ *   kraftwerk contacts                                   list (--json)
+ *   kraftwerk contacts show <slug>                       fields, records, links (found / missing), notes
+ *   kraftwerk contacts create <title> [--org ..] [--email ..] [--place <slug>] [--tags a,b] [--notes ..]
+ *   kraftwerk contacts set <slug> [--role ..] [--notes-file <md>]   change fields; "" clears one
+ *   kraftwerk contacts remove <slug>                     move the file to the trash
+ *   kraftwerk places ...                                 --address, --lat, --lng, --url; show prints the Google Maps link
+ *   kraftwerk events [--from <date>] [--to <date>]       --start (required), --end, --place, --contacts a,b, --project
+ *   kraftwerk ref <kind:slug> | --file <md>              resolve references (exit 1 when a target is missing)
+ */
+const die = (msg) => {
+    console.error(chalk.red(msg));
+    process.exit(1);
+};
+const mark = (found) => (found ? chalk.green("✔") : chalk.yellow("?"));
+function printDetail(def, e) {
+    const rec = e;
+    console.log(`${chalk.bold(e.title)} ${chalk.dim(`(${def.singular}:${e.slug})`)}`);
+    console.log(chalk.dim(e.path));
+    if (e.configError)
+        console.log(chalk.red(`frontmatter: ${e.configError}`));
+    for (const f of def.fields) {
+        const v = rec[f.name];
+        if (v === undefined || (Array.isArray(v) && v.length === 0))
+            continue;
+        const links = e.links[f.name];
+        const shown = links ? links.map((l) => `${mark(l.found)} ${l.slug}${l.label ? chalk.dim(`  ${l.label}`) : l.found ? "" : chalk.dim(" (not found)")}`).join(", ") : Array.isArray(v) ? v.join(", ") : String(v);
+        console.log(`${chalk.dim(f.label.padEnd(12))} ${shown}`);
+    }
+    if (def.kind === "places" && rec.mapsUrl)
+        console.log(`${chalk.dim("map".padEnd(12))} ${rec.mapsUrl}`);
+    if (e.tags.length)
+        console.log(`${chalk.dim("tags".padEnd(12))} ${e.tags.join(", ")}`);
+    for (const [k, v] of Object.entries(e.extra ?? {}))
+        console.log(`${chalk.dim(k.padEnd(12))} ${typeof v === "string" ? v : JSON.stringify(v)}`);
+    if (e.records.length) {
+        console.log(`\n${chalk.bold("systems of record")}`);
+        for (const r of e.records)
+            console.log(recordLine(r));
+    }
+    if (e.notes.trim())
+        console.log(`\n${chalk.bold("notes")}\n${e.notes.trim()}`);
+}
+/** The fields given on the command line, as the store takes them (comma lists split there; "" clears). */
+function fieldsOf(def, opts) {
+    const out = {};
+    for (const f of def.fields)
+        if (opts[f.name] !== undefined)
+            out[f.name] = opts[f.name];
+    if (opts.tags !== undefined)
+        out.tags = opts.tags;
+    if (opts.title !== undefined)
+        out.title = opts.title;
+    return out;
+}
+export function registerEntityCommands(program, def) {
+    const what = { contacts: "people and organisations", places: "addresses and points of interest", events: "dated one-off entries" }[def.kind];
+    const group = program.command(def.kind).description(`${def.kind[0].toUpperCase()}${def.kind.slice(1)}: ${what}, one Markdown file each — list, show, create, set, remove`);
+    const withFields = (cmd) => {
+        for (const f of def.fields)
+            cmd.option(`--${f.name} <value>`, `${f.hint}${f.required ? " (required)" : ""}`);
+        cmd.option("--tags <list>", "Tags, comma-separated");
+        return cmd;
+    };
+    const list = group
+        .command("list", { isDefault: true })
+        .description(`List the ${def.kind} under the ${def.kind} root`)
+        .option("--json", "Machine-readable output");
+    if (def.span)
+        list.option("--from <date>", "Only entries still running on or after this date (ISO)").option("--to <date>", "Only entries that have started by this date (ISO)");
+    list.action(async (opts) => {
+        await prepare();
+        const view = await listEntities(def, { from: opts.from, to: opts.to });
+        if (opts.json) {
+            console.log(JSON.stringify(view, null, 2));
+            return;
+        }
+        if (!view.enabled)
+            die(view.error ?? `${def.kind} are off`);
+        if (view.items.length === 0) {
+            console.log(chalk.dim(`No ${def.kind} under ${view.root} yet — \`kraftwerk ${def.kind} create "<title>"\` adds one.`));
+            return;
+        }
+        const table = new Table({ head: [def.singular, "details", "changed"].map((h) => chalk.bold(h)), wordWrap: true, colWidths: [30, 56, 14] });
+        for (const e of view.items) {
+            table.push([`${chalk.cyan(e.title)}\n${chalk.dim(e.slug)}`, e.configError ? chalk.red(e.configError) : def.detail(e) || chalk.dim("—"), chalk.dim(fmtAgo(e.updatedAt))]);
+        }
+        console.log(table.toString());
+        console.log(chalk.dim(view.root ?? ""));
+    });
+    group
+        .command("show")
+        .description(`Show one ${def.singular}: fields, records, links with their state, notes`)
+        .argument("<slug>", "File name under the root, without .md")
+        .option("--json", "Machine-readable output")
+        .action(async (slug, opts) => {
+        await prepare();
+        try {
+            const e = await getEntity(def, slug);
+            if (!e)
+                die(`no ${def.singular} "${slug}"`);
+            if (opts.json)
+                console.log(JSON.stringify(e, null, 2));
+            else
+                printDetail(def, e);
+        }
+        catch (err) {
+            die(err.message);
+        }
+    });
+    withFields(group
+        .command("create")
+        .description(`Create a ${def.singular} file from its title and fields`)
+        .argument("<title>", "Display title; the file name derives from it unless --slug is given")
+        .option("--slug <slug>", "File name under the root (lowercase, digits, dashes)")
+        .option("--notes <text>", "The Markdown body")
+        .option("--notes-file <path>", "Read the body from a file")
+        .option("--json", `Print the new ${def.singular} as JSON`)).action(async (title, opts) => {
+        await prepare();
+        try {
+            const notes = opts.notesFile ? await readFile(opts.notesFile, "utf8") : opts.notes;
+            const e = await createEntity(def, { ...fieldsOf(def, opts), title, slug: opts.slug, ...(notes !== undefined ? { notes } : {}) });
+            if (opts.json)
+                console.log(JSON.stringify(e, null, 2));
+            else {
+                const missing = Object.values(e.links).flat().filter((l) => !l.found);
+                console.log(`${chalk.green("✔")} ${chalk.cyan(`${def.singular}:${e.slug}`)} → ${e.path}${missing.length ? chalk.yellow(` (not found in this workspace yet: ${missing.map((l) => l.slug).join(", ")})`) : ""}`);
+            }
+        }
+        catch (err) {
+            die(err.message);
+        }
+    });
+    withFields(group
+        .command("set")
+        .description(`Change a ${def.singular}'s fields ("" clears one) or notes`)
+        .argument("<slug>", "File name under the root")
+        .option("--title <text>", "New title")
+        .option("--notes <text>", "Replace the Markdown body")
+        .option("--notes-file <path>", "Replace the body with a file's content")
+        .option("--json", `Print the ${def.singular} as JSON`)).action(async (slug, opts) => {
+        await prepare();
+        try {
+            const notes = opts.notesFile ? await readFile(opts.notesFile, "utf8") : opts.notes;
+            const input = { ...fieldsOf(def, opts), ...(notes !== undefined ? { notes } : {}) };
+            if (Object.keys(input).length === 0)
+                die(`nothing to set — pass --${def.fields.map((f) => f.name).join(", --")}, --tags, --title or --notes`);
+            const e = await saveEntity(def, slug, input);
+            if (opts.json)
+                console.log(JSON.stringify(e, null, 2));
+            else
+                console.log(`${chalk.green("✔")} ${chalk.cyan(`${def.singular}:${e.slug}`)} — ${def.describe(e)}`);
+        }
+        catch (err) {
+            die(err.message);
+        }
+    });
+    group
+        .command("remove")
+        .description(`Move a ${def.singular} file to the trash (\`kraftwerk trash\` puts it back)`)
+        .argument("<slug>", "File name under the root")
+        .action(async (slug) => {
+        await prepare();
+        try {
+            await deleteEntity(def, slug);
+            console.log(`${chalk.green("✔")} moved ${chalk.cyan(`${def.singular}:${slug}`)} to the trash`);
+        }
+        catch (err) {
+            die(err.message);
+        }
+    });
+}
+export const registerContactCommands = (program) => registerEntityCommands(program, CONTACTS);
+export const registerPlaceCommands = (program) => registerEntityCommands(program, PLACES);
+export const registerEventCommands = (program) => registerEntityCommands(program, EVENTS);
+const refLine = (r) => `${mark(r.found)} ${r.token}${r.label ? chalk.dim(`  ${r.label}`) : r.found ? "" : chalk.dim("  (not found)")}`;
+/** `kraftwerk ref` — resolve one reference, or every reference in a file. */
+export function registerRefCommand(program) {
+    program
+        .command("ref")
+        .description("Resolve a reference (contact:anna-meier, place:…, event:…, project:…, agent:…, workflow:…, repo:…, vibeable:…, knowledge:…) or every one in a file")
+        .argument("[ref]", "The reference, <kind>:<slug>")
+        .option("--file <path>", "Resolve every reference found in this file")
+        .option("--json", "Machine-readable output")
+        .action(async (ref, opts) => {
+        await prepare();
+        let refs;
+        if (opts.file)
+            refs = await resolveTokens(findRefs(await readFile(opts.file, "utf8").catch((e) => die(e.message))));
+        else if (ref) {
+            const r = await resolveRef(ref);
+            if (!r)
+                die(`not a reference: "${ref}" (expected <kind>:<slug>, e.g. contact:anna-meier)`);
+            refs = [r];
+        }
+        else
+            die("pass a reference like contact:anna-meier, or --file <path>");
+        if (opts.json)
+            console.log(JSON.stringify({ refs: refs }, null, 2));
+        else if (refs.length === 0)
+            console.log(chalk.dim("no references found"));
+        else
+            for (const r of refs)
+                console.log(refLine(r));
+        if (refs.some((r) => !r.found))
+            process.exit(1);
+    });
+}

package/dist/cli/init.js

@@ -31,6 +31,9 @@ skills: ${DATA_DIR}/skills         # workspace skills (shared instruction packag
 #   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)
+# contacts:                       # people and organisations, one Markdown file each under ${DATA_DIR}/contacts — referenced as contact:<slug> (uncomment to enable)
+# places:                         # addresses and points of interest, one Markdown file each under ${DATA_DIR}/places — referenced as place:<slug> (uncomment to enable)
+# events:                         # dated one-off entries with place, contacts and project, one Markdown file each under ${DATA_DIR}/events — referenced as event:<slug> (uncomment to enable)
 # cloud:                          # the daemon registers this MACHINE with the kraftwerk cloud and lists this workspace (\`kraftwerk login\` claims the machine)
 #   enabled: false                # uncomment both lines to leave this workspace out (\`kraftwerk cloud off\` turns the cloud off for the whole machine)
 `;
@@ -136,11 +139,12 @@ export async function runInit(cwd) {
         created.push(bundleRel);
     }
     // .gitignore: the output dir, the repos root (clones must never become
-    // gitlinks of the workspace repo) and .env (secrets). A missing file gets
+    // gitlinks of the workspace repo), the temp root (session scratch, which
+    // also carries a .gitignore of its own) 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/`, DOTENV_FILE];
+    const entries = [`${DATA_DIR}/output/`, `${DATA_DIR}/repos/`, `${DATA_DIR}/temp/`, DOTENV_FILE];
     if (gitignore === null) {
         await writeFile(gitignorePath, entries.map((e) => `${e}\n`).join(""));
         created.push(".gitignore");

package/dist/cli/kraftwerk.js

@@ -13,10 +13,12 @@ import { runDoctor } from "./doctor.js";
 import { runInit } from "./init.js";
 import { registerKnowledgeCommands } from "./knowledge.js";
 import { registerProjectCommands } from "./projects.js";
+import { registerContactCommands, registerEventCommands, registerPlaceCommands, registerRefCommand } from "./entities.js";
 import { registerWorkspaceCommands } from "./workspaces.js";
 import { registerRepoCommands } from "./repos.js";
 import { registerVibeableCommands } from "./vibeables.js";
 import { registerTrashCommands } from "./trash.js";
+import { registerTempCommands } from "./temp.js";
 import { registerDevicesCommands } from "./devices.js";
 import { registerDaemonCommand } from "./daemon.js";
 import { registerRemoteCommand } from "./remote.js";
@@ -42,10 +44,13 @@ import { runUi } from "./ui.js";
  *   kraftwerk ui                      start the inspector web UI (localhost:1981)
  *   kraftwerk workspaces ...          known workspaces on this machine (list/start/stop/forget)
  *   kraftwerk projects ...            goal-scoped project folders (list/create/show/link/log/remove)
+ *   kraftwerk contacts|places|events  who, where and when: one Markdown file each (list/show/create/set/remove)
+ *   kraftwerk ref <kind:slug>         resolve a reference (contact:anna-meier) or every one in a file
  *   kraftwerk vibeables ...           small apps built live in a chat (list/create/remove)
  *   kraftwerk repos ...               repositories the agents work on (list/add/update/remove)
  *   kraftwerk journal <agent> [entry] an agent's memory across sessions: print it, add a line
  *   kraftwerk trash ...               what was deleted: list, restore, purge, empty
+ *   kraftwerk temp [clean]            the sessions' scratch folders (TMPDIR of every agent): list, clean
  *   kraftwerk devices ...             paired devices: list, pair one, revoke one
  *   kraftwerk daemon                  the machine's kraftwerk: every open workspace at <slug>.localhost
  *   kraftwerk cloud [on|off|status]   this machine in the kraftwerk cloud (the daemon registers it)
@@ -299,9 +304,14 @@ registerKnowledgeCommands(program);
 registerRoutineCommands(program);
 registerWorkspaceCommands(program);
 registerProjectCommands(program);
+registerContactCommands(program);
+registerPlaceCommands(program);
+registerEventCommands(program);
+registerRefCommand(program);
 registerRepoCommands(program);
 registerVibeableCommands(program);
 registerTrashCommands(program);
+registerTempCommands(program);
 registerDevicesCommands(program);
 registerDaemonCommand(program);
 registerRemoteCommand(program);

package/dist/cli/temp.d.ts

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

package/dist/cli/temp.js

@@ -0,0 +1,62 @@
+import chalk from "chalk";
+import Table from "cli-table3";
+import { cleanTemp, listTemp, SWEEP_AFTER_MS } from "../core/temp.js";
+import { fmtAgo } from "./workspaces.js";
+import { initContext as prepare } from "./routines.js";
+/**
+ * `kraftwerk temp` — the sessions' scratch folders under kraftwerk-data/temp
+ * (one per chat session; TMPDIR of the agent process). Nothing in there is
+ * a deliverable: a clean deletes for good, no trash.
+ *
+ *   kraftwerk temp                          list: session, files, size, last change
+ *   kraftwerk temp clean                    remove folders idle for a week
+ *   kraftwerk temp clean --older-than <d>   … idle for <d> days
+ *   kraftwerk temp clean --all              remove every folder
+ */
+const fmtBytes = (n) => n < 1024 ? `${n} B` : n < 1024 * 1024 ? `${(n / 1024).toFixed(1)} KB` : n < 1024 ** 3 ? `${(n / 1024 ** 2).toFixed(1)} MB` : `${(n / 1024 ** 3).toFixed(2)} GB`;
+export function registerTempCommands(program) {
+    const temp = program.command("temp").description("The sessions' scratch folders: list, clean");
+    temp
+        .command("list", { isDefault: true })
+        .description("List the scratch folders, newest first")
+        .option("--json", "Machine-readable output")
+        .action(async (opts) => {
+        await prepare();
+        const view = await listTemp();
+        if (opts.json) {
+            console.log(JSON.stringify(view, null, 2));
+            return;
+        }
+        if (view.entries.length === 0) {
+            console.log(chalk.dim("No scratch folders."));
+            console.log(chalk.dim(view.root));
+            return;
+        }
+        const table = new Table({ head: ["session", "files", "size", "last change"].map((h) => chalk.bold(h)) });
+        for (const e of view.entries)
+            table.push([chalk.cyan(e.id), String(e.files), fmtBytes(e.bytes), chalk.dim(fmtAgo(e.modifiedAt))]);
+        console.log(table.toString());
+        console.log(chalk.dim(`${view.root} — ${fmtBytes(view.bytes)} in ${view.entries.length} folder${view.entries.length === 1 ? "" : "s"}`));
+    });
+    temp
+        .command("clean")
+        .description(`Remove scratch folders idle for ${SWEEP_AFTER_MS / 86_400_000} days (for good — nothing there is a deliverable)`)
+        .option("--older-than <days>", "Remove folders idle for this many days instead")
+        .option("--all", "Remove every folder, whatever its age")
+        .option("--json", "Machine-readable output")
+        .action(async (opts) => {
+        await prepare();
+        const days = opts.olderThan === undefined ? undefined : Number(opts.olderThan);
+        if (days !== undefined && (!Number.isFinite(days) || days < 0)) {
+            console.error(chalk.red(`--older-than wants a number of days, not "${opts.olderThan}"`));
+            process.exit(2);
+        }
+        const gone = await cleanTemp({ all: opts.all, ...(days === undefined ? {} : { olderThanMs: days * 86_400_000 }) });
+        const bytes = gone.reduce((n, e) => n + e.bytes, 0);
+        if (opts.json) {
+            console.log(JSON.stringify({ removed: gone.map((e) => e.id), bytes }, null, 2));
+            return;
+        }
+        console.log(`${chalk.green("✔")} removed ${gone.length} folder${gone.length === 1 ? "" : "s"} (${fmtBytes(bytes)})`);
+    });
+}

package/dist/cli/ui.js

@@ -1,4 +1,5 @@
 import { existsSync } from "node:fs";
+import { log } from "../core/log.js";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -144,7 +145,7 @@ export async function supervise(argv, what) {
             if (ran > 120_000)
                 backoff = 1000;
             const how = result.signal ? `signal ${result.signal}` : `exit ${result.code}`;
-            console.error(chalk.yellow(`↻ ${new Date().toISOString()} ${what} stopped unexpectedly (${how}) — starting it again in ${backoff / 1000}s`));
+            log("warn", "supervise", `${what} stopped unexpectedly (${how}) — starting it again in ${backoff / 1000}s`);
             await new Promise((r) => setTimeout(r, backoff));
             backoff = Math.min(backoff * 2, 60_000);
             continue;

package/dist/client/routes.d.ts

@@ -50,6 +50,11 @@ export declare const ROUTES: {
     readonly "cloud.status": readonly ["GET", "/api/cloud"];
     readonly "cloud.sync": readonly ["POST", "/api/cloud/sync"];
     readonly "cloud.unlink": readonly ["POST", "/api/cloud/unlink"];
+    readonly "contacts.create": readonly ["POST", "/api/contacts"];
+    readonly "contacts.delete": readonly ["DELETE", "/api/contacts/:slug"];
+    readonly "contacts.get": readonly ["GET", "/api/contacts/:slug"];
+    readonly "contacts.list": readonly ["GET", "/api/contacts"];
+    readonly "contacts.save": readonly ["PUT", "/api/contacts/:slug"];
     readonly "devices.code": readonly ["POST", "/api/devices/code"];
     readonly "devices.dropPush": readonly ["DELETE", "/api/devices/push"];
     readonly "devices.list": readonly ["GET", "/api/devices"];
@@ -59,6 +64,11 @@ export declare const ROUTES: {
     readonly "devices.self": readonly ["GET", "/api/devices/self"];
     readonly "devices.setPush": readonly ["POST", "/api/devices/push"];
     readonly "devices.setRelay": readonly ["POST", "/api/devices/relay"];
+    readonly "events.create": readonly ["POST", "/api/events"];
+    readonly "events.delete": readonly ["DELETE", "/api/events/:slug"];
+    readonly "events.get": readonly ["GET", "/api/events/:slug"];
+    readonly "events.list": readonly ["GET", "/api/events"];
+    readonly "events.save": readonly ["PUT", "/api/events/:slug"];
     readonly "files.delete": readonly ["DELETE", "/api/files"];
     readonly "files.list": readonly ["GET", "/api/files/list"];
     readonly "files.mkdir": readonly ["POST", "/api/files/folder"];
@@ -89,6 +99,11 @@ export declare const ROUTES: {
     readonly "notifications.diagnose": readonly ["POST", "/api/notifications/:id/diagnose"];
     readonly "notifications.list": readonly ["GET", "/api/notifications"];
     readonly "notifications.read": readonly ["POST", "/api/notifications/read"];
+    readonly "places.create": readonly ["POST", "/api/places"];
+    readonly "places.delete": readonly ["DELETE", "/api/places/:slug"];
+    readonly "places.get": readonly ["GET", "/api/places/:slug"];
+    readonly "places.list": readonly ["GET", "/api/places"];
+    readonly "places.save": readonly ["PUT", "/api/places/:slug"];
     readonly "projects.create": readonly ["POST", "/api/projects"];
     readonly "projects.delete": readonly ["DELETE", "/api/projects/:slug"];
     readonly "projects.get": readonly ["GET", "/api/projects/:slug"];
@@ -98,6 +113,7 @@ export declare const ROUTES: {
     readonly "projects.save": readonly ["PUT", "/api/projects/:slug"];
     readonly "projects.saveLayout": readonly ["PUT", "/api/projects"];
     readonly "protocol.get": readonly ["GET", "/api/protocol"];
+    readonly "refs.resolve": readonly ["POST", "/api/refs/resolve"];
     readonly "repos.add": readonly ["POST", "/api/repos"];
     readonly "repos.commit": readonly ["GET", "/api/repos/:slug/commits/:hash"];
     readonly "repos.diff": readonly ["GET", "/api/repos/:slug/diff"];
@@ -120,6 +136,8 @@ export declare const ROUTES: {
     readonly "settings.save": readonly ["PUT", "/api/settings"];
     readonly "skills.get": readonly ["GET", "/api/skills/:name"];
     readonly "skills.list": readonly ["GET", "/api/skills"];
+    readonly "temp.clean": readonly ["DELETE", "/api/temp"];
+    readonly "temp.list": readonly ["GET", "/api/temp"];
     readonly "trash.empty": readonly ["DELETE", "/api/trash"];
     readonly "trash.list": readonly ["GET", "/api/trash"];
     readonly "trash.purge": readonly ["POST", "/api/trash/purge"];