@netnodeag/kraftwerk 0.78.1 → 0.80.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
@@ -626,6 +631,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)
 `;

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 { registerContactCommands, registerEventCommands, registerPlaceCommands, registerRefCommand } from "./entities.js";
 import { registerWorkspaceCommands } from "./workspaces.js";
 import { registerRepoCommands } from "./repos.js";
 import { registerVibeableCommands } from "./vibeables.js";
@@ -42,6 +43,8 @@ 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
@@ -299,6 +302,10 @@ registerKnowledgeCommands(program);
 registerRoutineCommands(program);
 registerWorkspaceCommands(program);
 registerProjectCommands(program);
+registerContactCommands(program);
+registerPlaceCommands(program);
+registerEventCommands(program);
+registerRefCommand(program);
 registerRepoCommands(program);
 registerVibeableCommands(program);
 registerTrashCommands(program);

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"];

package/dist/client/routes.js

@@ -51,6 +51,11 @@ export const ROUTES = {
     "cloud.status": ["GET", "/api/cloud"],
     "cloud.sync": ["POST", "/api/cloud/sync"],
     "cloud.unlink": ["POST", "/api/cloud/unlink"],
+    "contacts.create": ["POST", "/api/contacts"],
+    "contacts.delete": ["DELETE", "/api/contacts/:slug"],
+    "contacts.get": ["GET", "/api/contacts/:slug"],
+    "contacts.list": ["GET", "/api/contacts"],
+    "contacts.save": ["PUT", "/api/contacts/:slug"],
     "devices.code": ["POST", "/api/devices/code"],
     "devices.dropPush": ["DELETE", "/api/devices/push"],
     "devices.list": ["GET", "/api/devices"],
@@ -60,6 +65,11 @@ export const ROUTES = {
     "devices.self": ["GET", "/api/devices/self"],
     "devices.setPush": ["POST", "/api/devices/push"],
     "devices.setRelay": ["POST", "/api/devices/relay"],
+    "events.create": ["POST", "/api/events"],
+    "events.delete": ["DELETE", "/api/events/:slug"],
+    "events.get": ["GET", "/api/events/:slug"],
+    "events.list": ["GET", "/api/events"],
+    "events.save": ["PUT", "/api/events/:slug"],
     "files.delete": ["DELETE", "/api/files"],
     "files.list": ["GET", "/api/files/list"],
     "files.mkdir": ["POST", "/api/files/folder"],
@@ -90,6 +100,11 @@ export const ROUTES = {
     "notifications.diagnose": ["POST", "/api/notifications/:id/diagnose"],
     "notifications.list": ["GET", "/api/notifications"],
     "notifications.read": ["POST", "/api/notifications/read"],
+    "places.create": ["POST", "/api/places"],
+    "places.delete": ["DELETE", "/api/places/:slug"],
+    "places.get": ["GET", "/api/places/:slug"],
+    "places.list": ["GET", "/api/places"],
+    "places.save": ["PUT", "/api/places/:slug"],
     "projects.create": ["POST", "/api/projects"],
     "projects.delete": ["DELETE", "/api/projects/:slug"],
     "projects.get": ["GET", "/api/projects/:slug"],
@@ -99,6 +114,7 @@ export const ROUTES = {
     "projects.save": ["PUT", "/api/projects/:slug"],
     "projects.saveLayout": ["PUT", "/api/projects"],
     "protocol.get": ["GET", "/api/protocol"],
+    "refs.resolve": ["POST", "/api/refs/resolve"],
     "repos.add": ["POST", "/api/repos"],
     "repos.commit": ["GET", "/api/repos/:slug/commits/:hash"],
     "repos.diff": ["GET", "/api/repos/:slug/diff"],

package/dist/config.d.ts

@@ -121,6 +121,25 @@ export interface ProjectsConfig {
 export declare const PROJECTS_DEFAULT_ROOT = "kraftwerk-data/projects";
 /** Absolute projects root when the feature is on, undefined otherwise. */
 export declare function projectsRootFor(project: ResolvedWorkspace): string | undefined;
+/**
+ * Contacts, places and events: the workspace's own records of who, where
+ * and when — one Markdown file with YAML frontmatter per entry under the
+ * kind's root, so humans, agents and projects can reference them reliably
+ * (`contact:anna-meier`). Three features with one shape, each switched on
+ * by its own block; part of the workspace and synced by the workspace git.
+ */
+export interface EntitiesConfig {
+    /** false keeps the block but turns the feature off. Default: true. */
+    enabled?: boolean;
+    /** Where the files live, relative to the project root. Default: kraftwerk-data/<kind> */
+    root?: string;
+}
+export declare const ENTITY_KINDS: readonly ["contacts", "places", "events"];
+export type EntityKind = (typeof ENTITY_KINDS)[number];
+/** Where a kind's files live when its `root` is not set. */
+export declare const entityDefaultRoot: (kind: EntityKind) => string;
+/** Absolute root of a kind when its feature is on, undefined otherwise. */
+export declare function entitiesRootFor(project: ResolvedWorkspace, kind: EntityKind): string | undefined;
 /**
  * kraftwerk.yml `cloud:` — since the cloud knows machines (core/cloud.ts,
  * server/cloud.ts), this block only vetoes: `enabled: false` leaves the
@@ -193,6 +212,12 @@ export interface WorkspaceConfig {
     vibeables?: VibeablesConfig;
     /** Projects: goal-scoped folders the chats work in. Absent = off. */
     projects?: ProjectsConfig;
+    /** Contacts: people and organisations, one Markdown file each. Absent = off. */
+    contacts?: EntitiesConfig;
+    /** Places: addresses and points of interest, one Markdown file each. Absent = off. */
+    places?: EntitiesConfig;
+    /** Events: dated entries (one-off), one Markdown file each. Absent = off. */
+    events?: EntitiesConfig;
     /** The machine's cloud record lists this workspace. Absent = listed; `enabled: false` leaves it out. */
     cloud?: CloudConfig;
 }

package/dist/config.js

@@ -96,6 +96,16 @@ export function projectsRootFor(project) {
         return undefined;
     return path.resolve(project.root, p.root ?? PROJECTS_DEFAULT_ROOT);
 }
+export const ENTITY_KINDS = ["contacts", "places", "events"];
+/** Where a kind's files live when its `root` is not set. */
+export const entityDefaultRoot = (kind) => `kraftwerk-data/${kind}`;
+/** Absolute root of a kind when its feature is on, undefined otherwise. */
+export function entitiesRootFor(project, kind) {
+    const e = project.config[kind];
+    if (!e || e.enabled === false)
+        return undefined;
+    return path.resolve(project.root, e.root ?? entityDefaultRoot(kind));
+}
 export const CLOUD_DEFAULT_URL = "https://srv.kraftwerk-cloud.netnode.cloud";
 /** A directory as a .gitignore entry: relative, forward slashes, no trailing slash; undefined outside the root. */
 export function ignoreEntryFor(projectRoot, dir) {
@@ -231,7 +241,7 @@ export async function addWorkspaceId(configPath) {
     await writeFile(configPath, out);
     return id;
 }
-const KNOWN_KEYS = ["id", "name", "slug", "icon", "color", "port", "workflows", "output", "knowledge", "agents", "skills", "switcher", "git", "repos", "vibeables", "projects", "cloud"];
+const KNOWN_KEYS = ["id", "name", "slug", "icon", "color", "port", "workflows", "output", "knowledge", "agents", "skills", "switcher", "git", "repos", "vibeables", "projects", "contacts", "places", "events", "cloud"];
 /**
  * Keys an older kraftwerk understood and this one ignores, so the files
  * that still carry them keep loading: `public:` and `tunnel:` (the
@@ -298,10 +308,10 @@ async function loadConfig(configPath) {
                 config[key] = {};
             validateRootBlock(configPath, "vibeables", config[key]);
         }
-        else if (key === "projects") {
+        else if (key === "projects" || key === "contacts" || key === "places" || key === "events") {
             if (config[key] === null)
                 config[key] = {};
-            validateRootBlock(configPath, "projects", config[key]);
+            validateRootBlock(configPath, key, config[key]);
         }
         else if (key === "cloud") {
             if (config[key] === null)
@@ -403,9 +413,10 @@ function validateGit(configPath, value) {
     }
 }
 /**
- * `repos`, `vibeables` and `projects` share one shape: { enabled?, root? }. The root
- * must never be the project itself or anything outside it — it is what
- * remove/delete operate under, and what the workspace git may stage.
+ * `repos`, `vibeables`, `projects`, `contacts`, `places` and `events` share one
+ * shape: { enabled?, root? }. The root must never be the project itself or
+ * anything outside it — it is what remove/delete operate under, and what
+ * the workspace git may stage.
  */
 function validateRootBlock(configPath, block, value) {
     const file = path.basename(configPath);