@netnodeag/kraftwerk 0.79.0 → 0.80.0

package/dist/core/journal.d.ts

@@ -1,8 +1,8 @@
 /**
  * An agent's journal: agents/<slug>/journal.md, the agent's own memory
  * across sessions. What it learned, decided, promised and finished, one
- * line per entry under a dated heading, newest first (like a project's
- * log.md). The agent writes it through `kraftwerk journal` and reads the
+ * line per entry stamped with its minute, under a dated heading, newest
+ * first (like a project's log.md). Times are the machine's local time. The agent writes it through `kraftwerk journal` and reads the
  * recent part back at the start of every session, so next week it is the
  * same colleague; a human can add a line from the inspector.
  */
@@ -19,7 +19,17 @@ export declare function readJournal(slug: string): Promise<string>;
 export declare function appendJournal(slug: string, entry: string, opts?: {
     kind?: string;
     actor?: string;
+    now?: Date;
 }): Promise<string>;
+/**
+ * One section per day again, its entries newest first by their minute. Two
+ * people adding to a journal on different machines both put a line under
+ * the same day (or both open a new day); once git has kept both sides, the
+ * next entry tidies the file: a day heading that appears twice is merged
+ * into one, and stamped lines are ordered by time, ahead of older unstamped
+ * ones, which keep their order.
+ */
+export declare function mergeDays(raw: string): string;
 /**
  * The recent part of a journal for a session's context: whole days, newest
  * first, until the budget is spent. Older days stay in the file, where the

package/dist/core/journal.js

@@ -4,8 +4,8 @@ import { agentsRoot, getAgent, safeAgentSlug } from "./agents.js";
 /**
  * An agent's journal: agents/<slug>/journal.md, the agent's own memory
  * across sessions. What it learned, decided, promised and finished, one
- * line per entry under a dated heading, newest first (like a project's
- * log.md). The agent writes it through `kraftwerk journal` and reads the
+ * line per entry stamped with its minute, under a dated heading, newest
+ * first (like a project's log.md). Times are the machine's local time. The agent writes it through `kraftwerk journal` and reads the
  * recent part back at the start of every session, so next week it is the
  * same colleague; a human can add a line from the inspector.
  */
@@ -35,11 +35,12 @@ export async function appendJournal(slug, entry, opts = {}) {
         throw new Error(`kind must be one of: ${JOURNAL_KINDS.join(", ")}`);
     const actor = opts.actor?.trim();
     const own = !actor || actor === slug || actor.startsWith(`${slug}/`);
-    const line = `* ${kind === "note" ? "" : `**${kind[0].toUpperCase()}${kind.slice(1)}**: `}${text}${own ? "" : ` (${actor})`}`;
+    const now = opts.now ?? new Date();
+    const line = `* ${clock(now)} ${kind === "note" ? "" : `**${kind[0].toUpperCase()}${kind.slice(1)}**: `}${text}${own ? "" : ` (${actor})`}`;
     const file = await journalPath(slug);
-    const today = new Date().toISOString().slice(0, 10);
+    const today = localDate(now);
     const raw = (await fs.readFile(file, "utf8").catch(() => null)) ?? `# ${def.name}'s journal\n`;
-    const lines = raw.split("\n");
+    const lines = mergeDays(raw).split("\n");
     const todayIdx = lines.findIndex((l) => l.trim() === `## ${today}`);
     if (todayIdx >= 0) {
         lines.splice(todayIdx + 1, 0, line);
@@ -52,6 +53,50 @@ export async function appendJournal(slug, entry, opts = {}) {
     await fs.writeFile(file, out);
     return out;
 }
+const pad = (n) => String(n).padStart(2, "0");
+/** YYYY-MM-DD in local time. */
+const localDate = (d) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+/** HH:MM in local time. */
+const clock = (d) => `${pad(d.getHours())}:${pad(d.getMinutes())}`;
+/**
+ * One section per day again, its entries newest first by their minute. Two
+ * people adding to a journal on different machines both put a line under
+ * the same day (or both open a new day); once git has kept both sides, the
+ * next entry tidies the file: a day heading that appears twice is merged
+ * into one, and stamped lines are ordered by time, ahead of older unstamped
+ * ones, which keep their order.
+ */
+export function mergeDays(raw) {
+    const lines = raw.split("\n");
+    const firstDay = lines.findIndex((l) => /^## /.test(l));
+    if (firstDay < 0)
+        return raw;
+    const head = lines.slice(0, firstDay);
+    const days = new Map();
+    let cur = null;
+    for (const l of lines.slice(firstDay)) {
+        const m = /^## (.+?)\s*$/.exec(l);
+        if (m) {
+            cur = days.get(m[1]) ?? [];
+            days.set(m[1], cur);
+        }
+        else if (cur && l.trim()) {
+            cur.push(l);
+        }
+    }
+    if (days.size === lines.slice(firstDay).filter((l) => /^## /.test(l)).length) {
+        // no day twice: leave the order of a day's lines as written
+        return raw;
+    }
+    const stamp = (l) => /^\* (\d\d:\d\d) /.exec(l)?.[1] ?? "";
+    const order = [...days.keys()].sort((a, b) => b.localeCompare(a));
+    const body = order.map((d) => {
+        const entries = days.get(d).map((l, i) => ({ l, i, t: stamp(l) }));
+        entries.sort((a, b) => (a.t && b.t ? b.t.localeCompare(a.t) : a.t ? -1 : b.t ? 1 : 0) || a.i - b.i);
+        return [`## ${d}`, ...[...new Set(entries.map((e) => e.l))]].join("\n");
+    });
+    return [...head, body.join("\n\n"), ""].join("\n").replace(/\n{3,}/g, "\n\n");
+}
 /**
  * The recent part of a journal for a session's context: whole days, newest
  * first, until the budget is spent. Older days stay in the file, where the

package/dist/core/log.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The daemon's log line, one event per line in a fixed shape:
+ *
+ *   2026-10-15T14:26:47.662Z INFO  relay     connected to https://… as N8I…
+ *   2026-10-15T14:26:47.901Z WARN  cloud     https://… unreachable — no answer (retrying)
+ *   2026-10-15T12:25:33.105Z ERROR server    crashed: Error: listen EADDRINUSE …
+ *
+ * ISO-8601 UTC time, a padded level, a padded component, the message —
+ * stable columns, grep-able, no glyphs, no color. The daemon's stdout IS
+ * ~/.kraftwerk/logs/daemon.log (daemon-control appends the stream), so the
+ * daemon and the long-running pieces it hosts (cloud client, relay,
+ * scheduler) speak this and nothing else. Interactive commands keep their
+ * human output; `kraftwerk daemon status` greps for "crashed:" and
+ * "stopped unexpectedly", which stay literal in the message.
+ */
+export type LogLevel = "info" | "warn" | "error";
+/** INFO to stdout, WARN and ERROR to stderr — the daemon writes both into one file. */
+export declare function log(level: LogLevel, component: string, message: string): void;

package/dist/core/log.js

@@ -0,0 +1,23 @@
+/**
+ * The daemon's log line, one event per line in a fixed shape:
+ *
+ *   2026-10-15T14:26:47.662Z INFO  relay     connected to https://… as N8I…
+ *   2026-10-15T14:26:47.901Z WARN  cloud     https://… unreachable — no answer (retrying)
+ *   2026-10-15T12:25:33.105Z ERROR server    crashed: Error: listen EADDRINUSE …
+ *
+ * ISO-8601 UTC time, a padded level, a padded component, the message —
+ * stable columns, grep-able, no glyphs, no color. The daemon's stdout IS
+ * ~/.kraftwerk/logs/daemon.log (daemon-control appends the stream), so the
+ * daemon and the long-running pieces it hosts (cloud client, relay,
+ * scheduler) speak this and nothing else. Interactive commands keep their
+ * human output; `kraftwerk daemon status` greps for "crashed:" and
+ * "stopped unexpectedly", which stay literal in the message.
+ */
+/** INFO to stdout, WARN and ERROR to stderr — the daemon writes both into one file. */
+export function log(level, component, message) {
+    const line = `${new Date().toISOString()} ${level.toUpperCase().padEnd(5)} ${component.padEnd(9)} ${message}`;
+    if (level === "info")
+        console.log(line);
+    else
+        console.error(line);
+}

package/dist/core/projects.d.ts

@@ -1,5 +1,7 @@
 import { type ResolvedWorkspace } from "../config.js";
 import type { ChatAgentId } from "./chat/types.js";
+import { RECORD_KINDS, recordLine, type SystemOfRecord } from "./records.js";
+import { type LinkState } from "./refs.js";
 /**
  * Projects: a goal with everything the agents need to reach it gathered in
  * one folder — the brief, the systems of record where the truth is managed
@@ -18,33 +20,20 @@ import type { ChatAgentId } from "./chat/types.js";
  *   projects/<slug>/state.md      # current state, rewritten at the end of a session
  *   projects/<slug>/log.md        # append-only: decisions, milestones (newest first, stamped)
  *
- * Links are one-directional lists of slugs; a target that does not exist
- * is reported ("configured but not found"), never an error — the same
- * rule agent knowledge follows. A system of record is context, not a
+ * Links are one-directional lists of slugs, resolved through the reference
+ * registry (refs.ts); a target that does not exist is reported
+ * ("configured but not found"), never an error — the same rule agent
+ * knowledge follows. A system of record (records.ts) is context, not a
  * credential and not a grant: it says where the truth lives and how it is
  * usually reached, and the harness decides what the agent may call.
  */
 export declare const PROJECT_FILE = "project.yml";
 export declare const PROJECT_STATUSES: readonly ["active", "paused", "done", "archived"];
 export type ProjectStatus = (typeof PROJECT_STATUSES)[number];
-/** Where truth is managed outside kraftwerk: a tool, a folder, a board. */
-export interface SystemOfRecord {
-    /** my-netnode | google-drive | github | bitbucket | notion | slack | url | anything else (rendered by name). */
-    kind: string;
-    /** Display name ("Figma board", "Contracts folder"). */
-    title?: string;
-    url?: string;
-    /** For tools with workspaces or boards: the id the agent needs (a my.netnode.ch workspace, a Slack channel). */
-    workspace?: string;
-    /** What lives there and how it is usually reached ("tickets and roadmap, `my` CLI"). */
-    note?: string;
-}
-/** What kraftwerk knows about a record kind: a label and what such a place usually holds. */
-export declare const RECORD_KINDS: Record<string, {
-    label: string;
-    hint: string;
-}>;
-export declare const LINK_KINDS: readonly ["knowledge", "vibeables", "repos", "workflows", "agents"];
+export { RECORD_KINDS, recordLine, type SystemOfRecord };
+export type { LinkState };
+/** What a project links to, in the order project.yml and the UI list them; each is a kind of the reference registry. */
+export declare const LINK_KINDS: readonly ["knowledge", "vibeables", "repos", "workflows", "agents", "contacts", "places", "events"];
 export type LinkKind = (typeof LINK_KINDS)[number];
 export interface ProjectDef {
     slug: string;
@@ -69,6 +58,12 @@ export interface ProjectDef {
     workflows: string[];
     /** Agent slugs. */
     agents: string[];
+    /** Contact slugs (contact:<slug>). */
+    contacts: string[];
+    /** Place slugs. */
+    places: string[];
+    /** Event slugs. */
+    events: string[];
 }
 /** What the ⌘K palette needs of a project: also the shape kept in the workspace registry. */
 export interface ProjectHit {
@@ -86,13 +81,6 @@ export interface ProjectSummary extends ProjectDef {
     /** Set when project.yml exists but is unusable; the rest shows defaults. */
     configError?: string;
 }
-/** One linked slug and whether its target exists right now. */
-export interface LinkState {
-    slug: string;
-    found: boolean;
-    /** Display name of the target when found (an agent's name, a workflow's description). */
-    label?: string;
-}
 export type ProjectLinks = Record<LinkKind, LinkState[]>;
 export interface ProjectDetail extends ProjectSummary {
     brief: string;
@@ -136,12 +124,15 @@ export interface SaveProjectInput {
     repos?: unknown;
     workflows?: unknown;
     agents?: unknown;
+    contacts?: unknown;
+    places?: unknown;
+    events?: unknown;
     brief?: string;
     state?: string;
 }
 export declare function safeProjectSlug(slug: string): string;
 /** Derive a slug from a title: "Relaunch netnode.ch" -> "relaunch-netnode-ch". */
-export declare function projectSlugFromTitle(title: string): string;
+export declare const projectSlugFromTitle: (title: string) => string;
 export declare function openProjects(): Promise<{
     project?: ResolvedWorkspace;
     root?: string;
@@ -154,8 +145,8 @@ export declare function ensureProjectsRoot(): Promise<void>;
 export declare function listProjects(): Promise<ProjectsView>;
 /** Save the sidebar's order (PUT /api/projects); section names must be unique and non-empty. */
 export declare function saveLayout(input: unknown): Promise<ProjectLayout>;
-/** Which of the linked slugs exist right now, with a display label for the ones that do. */
-export declare function resolveLinks(def: ProjectDef): Promise<ProjectLinks>;
+/** Which of the linked slugs exist right now, with a display label for the ones that do (the reference registry decides). */
+export declare const resolveLinks: (def: ProjectDef) => Promise<ProjectLinks>;
 /** One project with its files and link states; null when the folder is not a project. */
 export declare function getProject(slug: string): Promise<ProjectDetail | null>;
 /** The files a fresh project starts with. */
@@ -180,8 +171,6 @@ export declare function linkProject(slug: string, kind: string, target: string,
 export declare function appendProjectLog(slug: string, entry: string, actor: string): Promise<string>;
 /** Move the folder to the trash. */
 export declare function deleteProject(slug: string): Promise<void>;
-/** One line per system of record: what it is, where, and what usually lives there. */
-export declare function recordLine(r: SystemOfRecord): string;
 /**
  * The "## …" blocks a project chat starts with: brief, state, records,
  * every link with how to reach it, and how to keep the project current.

package/dist/core/projects.js

@@ -2,15 +2,16 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { parse, stringify } from "yaml";
 import { projectsRootFor, resolveWorkspace } from "../config.js";
-import { EFFORTS, HARNESSES, listAgents } from "./agents.js";
+import { EFFORTS, HARNESSES } from "./agents.js";
 import { workspaceRoot } from "./context.js";
+import { CONTACTS, entityLine, EVENTS, listEntities, PLACES } from "./entities.js";
 import { syncWorkspaceProjects } from "./instances.js";
-import { knowledgeIndex } from "./knowledge.js";
 import { newestMtime } from "./mtime.js";
+import { cleanRecords, RECORD_KINDS, recordLine } from "./records.js";
+import { resolveRefs } from "./refs.js";
 import { listRepos } from "./repos.js";
+import { SLUG_RE, slugify } from "./slug.js";
 import { moveToTrash } from "./trash.js";
-import { listVibeables } from "./vibeables.js";
-import { listWorkflows } from "./workflows.js";
 import { filesContext } from "./files.js";
 /**
  * Projects: a goal with everything the agents need to reach it gathered in
@@ -30,48 +31,31 @@ import { filesContext } from "./files.js";
  *   projects/<slug>/state.md      # current state, rewritten at the end of a session
  *   projects/<slug>/log.md        # append-only: decisions, milestones (newest first, stamped)
  *
- * Links are one-directional lists of slugs; a target that does not exist
- * is reported ("configured but not found"), never an error — the same
- * rule agent knowledge follows. A system of record is context, not a
+ * Links are one-directional lists of slugs, resolved through the reference
+ * registry (refs.ts); a target that does not exist is reported
+ * ("configured but not found"), never an error — the same rule agent
+ * knowledge follows. A system of record (records.ts) is context, not a
  * credential and not a grant: it says where the truth lives and how it is
  * usually reached, and the harness decides what the agent may call.
  */
 export const PROJECT_FILE = "project.yml";
 export const PROJECT_STATUSES = ["active", "paused", "done", "archived"];
-/** What kraftwerk knows about a record kind: a label and what such a place usually holds. */
-export const RECORD_KINDS = {
-    "my-netnode": { label: "my.netnode.ch", hint: "tickets, roadmap items, meetings and workspace memory" },
-    "google-drive": { label: "Google Drive", hint: "documents and folders" },
-    github: { label: "GitHub", hint: "issues, pull requests and discussions" },
-    bitbucket: { label: "Bitbucket", hint: "pull requests and pipelines" },
-    notion: { label: "Notion", hint: "pages and databases" },
-    slack: { label: "Slack", hint: "conversations and decisions" },
-    url: { label: "Link", hint: "" },
-};
-export const LINK_KINDS = ["knowledge", "vibeables", "repos", "workflows", "agents"];
+export { RECORD_KINDS, recordLine };
+/** What a project links to, in the order project.yml and the UI list them; each is a kind of the reference registry. */
+export const LINK_KINDS = ["knowledge", "vibeables", "repos", "workflows", "agents", "contacts", "places", "events"];
 export const toProjectHit = (p) => ({
     slug: p.slug,
     title: p.title,
     status: p.status,
     ...(p.goal ? { goal: p.goal } : {}),
 });
-const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,48}$/;
 export function safeProjectSlug(slug) {
     if (!SLUG_RE.test(slug))
         throw new Error(`invalid project name "${slug}"`);
     return slug;
 }
 /** Derive a slug from a title: "Relaunch netnode.ch" -> "relaunch-netnode-ch". */
-export function projectSlugFromTitle(title) {
-    return title
-        .normalize("NFKD")
-        .replace(/[̀-ͯ]/g, "")
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "")
-        .slice(0, 48)
-        .replace(/-+$/, "");
-}
+export const projectSlugFromTitle = (title) => slugify(title);
 /* ---------- root ---------- */
 export async function openProjects() {
     let project;
@@ -106,46 +90,6 @@ const strList = (v, field) => {
         throw new Error(`${field} must be a list of names`);
     return [...new Set(v.map((x) => x.trim()).filter(Boolean))];
 };
-const cleanRecords = (v) => {
-    if (v === undefined || v === null)
-        return [];
-    if (!Array.isArray(v))
-        throw new Error("records must be a list");
-    return v.map((r, i) => {
-        if (typeof r !== "object" || r === null || Array.isArray(r))
-            throw new Error(`records[${i}] must be a mapping (kind, title, url, workspace, note)`);
-        const o = r;
-        const kind = typeof o.kind === "string" ? o.kind.trim().toLowerCase() : "";
-        if (!kind)
-            throw new Error(`records[${i}]: kind is required (e.g. my-netnode, google-drive, url)`);
-        const str = (k) => {
-            const x = o[k];
-            if (x === undefined || x === null || x === "")
-                return undefined;
-            if (typeof x === "number")
-                return String(x);
-            if (typeof x !== "string")
-                throw new Error(`records[${i}].${k} must be a string`);
-            return x.trim() || undefined;
-        };
-        const url = str("url");
-        if (url && !/^https?:\/\//.test(url))
-            throw new Error(`records[${i}].url must start with http:// or https://`);
-        const out = { kind };
-        const title = str("title");
-        const workspace = str("workspace");
-        const note = str("note");
-        if (title)
-            out.title = title;
-        if (url)
-            out.url = url;
-        if (workspace)
-            out.workspace = workspace;
-        if (note)
-            out.note = note;
-        return out;
-    });
-};
 const cleanHarness = (v) => {
     if (v === undefined || v === null || v === "")
         return "claude";
@@ -196,13 +140,11 @@ function parseDef(slug, raw) {
         ...(model ? { model } : {}),
         ...(effort ? { effort } : {}),
         records: cleanRecords(d.records),
-        knowledge: strList(d.knowledge, "knowledge"),
-        vibeables: strList(d.vibeables, "vibeables"),
-        repos: strList(d.repos, "repos"),
-        workflows: strList(d.workflows, "workflows"),
-        agents: strList(d.agents, "agents"),
+        ...linkLists((kind) => strList(d[kind], kind)),
     };
 }
+/** The link lists of a definition, one per LINK_KIND, from a function that gives each. */
+const linkLists = (of) => Object.fromEntries(LINK_KINDS.map((kind) => [kind, of(kind)]));
 const emptyDef = (slug) => ({
     slug,
     title: slug,
@@ -210,11 +152,7 @@ const emptyDef = (slug) => ({
     goal: "",
     harness: "claude",
     records: [],
-    knowledge: [],
-    vibeables: [],
-    repos: [],
-    workflows: [],
-    agents: [],
+    ...linkLists(() => []),
 });
 /** project.yml as written: no slug (the folder is the slug), empty lists left out. */
 function defToYaml(def) {
@@ -315,42 +253,8 @@ export async function saveLayout(input) {
     await fs.writeFile(path.join(root, ORDER_FILE), `# The order of the projects in the sidebar, with its sections. Drag them there.\n${stringify(doc)}`);
     return layout;
 }
-/** Which of the linked slugs exist right now, with a display label for the ones that do. */
-export async function resolveLinks(def) {
-    const [knowledge, vibeables, repos, workflows, agents] = await Promise.all([
-        knowledgeIndex().catch(() => ({ bundles: [] })),
-        listVibeables().catch(() => ({ vibeables: [] })),
-        listRepos().catch(() => ({ repos: [] })),
-        listWorkflows().catch(() => ({ workflows: [] })),
-        listAgents().catch(() => []),
-    ]);
-    const state = (slugs, lookup) => slugs.map((slug) => {
-        const label = lookup(slug);
-        return label === undefined ? { slug, found: false } : { slug, found: true, ...(label ? { label } : {}) };
-    });
-    return {
-        knowledge: state(def.knowledge, (s) => {
-            const b = knowledge.bundles.find((x) => x.name === s);
-            return b ? `${b.concepts} concepts` : undefined;
-        }),
-        vibeables: state(def.vibeables, (s) => {
-            const v = vibeables.vibeables.find((x) => x.slug === s);
-            return v ? (v.dev ? "dev" : "static") : undefined;
-        }),
-        repos: state(def.repos, (s) => {
-            const r = repos.repos.find((x) => x.slug === s);
-            return r ? r.branch ?? "" : undefined;
-        }),
-        workflows: state(def.workflows, (s) => {
-            const w = workflows.workflows.find((x) => x.slug === s);
-            return w ? w.description ?? w.name ?? "" : undefined;
-        }),
-        agents: state(def.agents, (s) => {
-            const a = agents.find((x) => x.slug === s && !x.archived);
-            return a ? `${a.emoji} ${a.name}` : undefined;
-        }),
-    };
-}
+/** Which of the linked slugs exist right now, with a display label for the ones that do (the reference registry decides). */
+export const resolveLinks = (def) => resolveRefs(linkLists((kind) => def[kind]));
 /** One project with its files and link states; null when the folder is not a project. */
 export async function getProject(slug) {
     const root = await requireRoot();
@@ -413,11 +317,7 @@ export async function saveProject(slug, input) {
         goal: input.goal !== undefined ? String(input.goal).trim() : current.goal,
         harness: input.harness !== undefined ? cleanHarness(input.harness) : current.harness,
         records: input.records !== undefined ? cleanRecords(input.records) : current.records,
-        knowledge: input.knowledge !== undefined ? strList(input.knowledge, "knowledge") : current.knowledge,
-        vibeables: input.vibeables !== undefined ? strList(input.vibeables, "vibeables") : current.vibeables,
-        repos: input.repos !== undefined ? strList(input.repos, "repos") : current.repos,
-        workflows: input.workflows !== undefined ? strList(input.workflows, "workflows") : current.workflows,
-        agents: input.agents !== undefined ? strList(input.agents, "agents") : current.agents,
+        ...linkLists((kind) => (input[kind] !== undefined ? strList(input[kind], kind) : current[kind])),
     };
     const model = input.model !== undefined ? cleanModel(input.model) : current.model;
     const effort = input.effort !== undefined ? cleanEffort(input.effort) : current.effort;
@@ -488,19 +388,6 @@ export async function deleteProject(slug) {
     await moveToTrash("projects", slug, dir);
 }
 /* ---------- chat context ---------- */
-/** One line per system of record: what it is, where, and what usually lives there. */
-export function recordLine(r) {
-    const known = RECORD_KINDS[r.kind];
-    const label = known?.label ?? r.kind;
-    const head = r.title ? `${label}: ${r.title}` : label;
-    const parts = [
-        r.workspace ? `workspace ${r.workspace}` : "",
-        r.url ?? "",
-        known?.hint ?? "",
-        r.note ?? "",
-    ].filter(Boolean);
-    return `- ${head}${parts.length ? ` — ${parts.join("; ")}` : ""}`;
-}
 /**
  * The "## …" blocks a project chat starts with: brief, state, records,
  * every link with how to reach it, and how to keep the project current.
@@ -517,6 +404,22 @@ export async function projectContext(slug, actor, opts = {}) {
     const repos = await listRepos().catch(() => null);
     const reposRoot = repos?.enabled && repos.root ? repos.root : undefined;
     const vibeables = p.vibeables.length > 0;
+    // Who, where and when: the linked entries as one-liners, each with its reference token.
+    const entityBlock = async (def, slugs, heading, intro) => {
+        if (slugs.length === 0)
+            return "";
+        const view = await listEntities(def).catch(() => ({ items: [] }));
+        const lines = slugs.map((slug) => {
+            const item = view.items.find((x) => x.slug === slug);
+            return item ? entityLine(def, item) : `- ${def.singular}:${slug} (configured but not found in this workspace — tell the user if you need it)`;
+        });
+        return `## ${heading}\n${intro}\n${lines.join("\n")}\n\`npx kraftwerk ${def.kind} show <slug> --json\` has the full entry and notes.`;
+    };
+    const [contactsBlock, placesBlock, eventsBlock] = await Promise.all([
+        entityBlock(CONTACTS, p.contacts, "Contacts", "People and organisations of this project (reference one as contact:<slug>):"),
+        entityBlock(PLACES, p.places, "Places", "Where this project happens (reference one as place:<slug>):"),
+        entityBlock(EVENTS, p.events, "Events", "Dates of this project (reference one as event:<slug>):"),
+    ]);
     const sections = [
         (opts.member
             ? `## Project: ${p.title}\nThis channel works in the project "${p.title}" (status ${p.status}) of this kraftwerk workspace. ` +
@@ -569,6 +472,9 @@ export async function projectContext(slug, actor, opts = {}) {
                 linkLines("agents", (l) => `- ${l.slug}${l.label ? ` — ${l.label}` : ""}`) +
                 `\nThe user talks to them on the Agents screen; you cannot message them yourself. When a request clearly belongs to one of them, say so.`
             : "",
+        contactsBlock,
+        placesBlock,
+        eventsBlock,
         `## Keeping the project current\n` +
             `- brief.md is the user's: propose changes and write them only when they agree.\n` +
             `- state.md is the project's memory between sessions. At the end of a session that changed something, rewrite it so the next session ` +
@@ -576,7 +482,7 @@ export async function projectContext(slug, actor, opts = {}) {
             `- log.md is append-only. Record decisions and milestones with\n` +
             `  npx kraftwerk projects log ${p.slug} "<one line>" --actor ${actor}\n` +
             `  (stamps the date and you as the author; never edit log.md by hand).\n` +
-            `- Links (knowledge, vibeables, repositories, workflows, agents) live in project.yml: \`npx kraftwerk projects link ${p.slug} <kind> <name>\` adds one, \`unlink\` removes it.`,
+            `- Links (knowledge, vibeables, repositories, workflows, agents, contacts, places, events) live in project.yml: \`npx kraftwerk projects link ${p.slug} <kind> <name>\` adds one, \`unlink\` removes it.`,
     ];
     return sections.filter(Boolean).join("\n\n");
 }

package/dist/core/records.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Systems of record: where the truth of something is managed outside
+ * kraftwerk — a tool, a folder, a board. A project points at its ticket
+ * system, a contact at the CRM and the newsletter tool, an event at its
+ * calendar entry, a place at Google Maps. An entry is context, not a
+ * credential and not a grant: it says where the truth lives and how it is
+ * usually reached, and the harness decides what the agent may call.
+ */
+export interface SystemOfRecord {
+    /** my-netnode | google-drive | github | bitbucket | notion | slack | crm | newsletter | calendar | google-maps | url | anything else (rendered by name). */
+    kind: string;
+    /** Display name ("Figma board", "Contracts folder"). */
+    title?: string;
+    url?: string;
+    /** For tools with workspaces or boards: the id the agent needs (a my.netnode.ch workspace, a Slack channel). */
+    workspace?: string;
+    /** What lives there and how it is usually reached ("tickets and roadmap, `my` CLI"). */
+    note?: string;
+}
+/** What kraftwerk knows about a record kind: a label and what such a place usually holds. */
+export declare const RECORD_KINDS: Record<string, {
+    label: string;
+    hint: string;
+}>;
+/** Any input -> a clean list of records; every problem is one error the caller can show. */
+export declare const cleanRecords: (v: unknown) => SystemOfRecord[];
+/** One line per system of record: what it is, where, and what usually lives there. */
+export declare function recordLine(r: SystemOfRecord): string;

package/dist/core/records.js

@@ -0,0 +1,71 @@
+/**
+ * Systems of record: where the truth of something is managed outside
+ * kraftwerk — a tool, a folder, a board. A project points at its ticket
+ * system, a contact at the CRM and the newsletter tool, an event at its
+ * calendar entry, a place at Google Maps. An entry is context, not a
+ * credential and not a grant: it says where the truth lives and how it is
+ * usually reached, and the harness decides what the agent may call.
+ */
+/** What kraftwerk knows about a record kind: a label and what such a place usually holds. */
+export const RECORD_KINDS = {
+    "my-netnode": { label: "my.netnode.ch", hint: "tickets, roadmap items, meetings and workspace memory" },
+    "google-drive": { label: "Google Drive", hint: "documents and folders" },
+    github: { label: "GitHub", hint: "issues, pull requests and discussions" },
+    bitbucket: { label: "Bitbucket", hint: "pull requests and pipelines" },
+    notion: { label: "Notion", hint: "pages and databases" },
+    slack: { label: "Slack", hint: "conversations and decisions" },
+    crm: { label: "CRM", hint: "the contact's record, deals and history" },
+    newsletter: { label: "Newsletter tool", hint: "subscription and mailing lists" },
+    calendar: { label: "Calendar", hint: "the calendar entry, invitees and reminders" },
+    "google-maps": { label: "Google Maps", hint: "the place on the map, opening hours and directions" },
+    url: { label: "Link", hint: "" },
+};
+/** Any input -> a clean list of records; every problem is one error the caller can show. */
+export const cleanRecords = (v) => {
+    if (v === undefined || v === null)
+        return [];
+    if (!Array.isArray(v))
+        throw new Error("records must be a list");
+    return v.map((r, i) => {
+        if (typeof r !== "object" || r === null || Array.isArray(r))
+            throw new Error(`records[${i}] must be a mapping (kind, title, url, workspace, note)`);
+        const o = r;
+        const kind = typeof o.kind === "string" ? o.kind.trim().toLowerCase() : "";
+        if (!kind)
+            throw new Error(`records[${i}]: kind is required (e.g. my-netnode, google-drive, url)`);
+        const str = (k) => {
+            const x = o[k];
+            if (x === undefined || x === null || x === "")
+                return undefined;
+            if (typeof x === "number")
+                return String(x);
+            if (typeof x !== "string")
+                throw new Error(`records[${i}].${k} must be a string`);
+            return x.trim() || undefined;
+        };
+        const url = str("url");
+        if (url && !/^https?:\/\//.test(url))
+            throw new Error(`records[${i}].url must start with http:// or https://`);
+        const out = { kind };
+        const title = str("title");
+        const workspace = str("workspace");
+        const note = str("note");
+        if (title)
+            out.title = title;
+        if (url)
+            out.url = url;
+        if (workspace)
+            out.workspace = workspace;
+        if (note)
+            out.note = note;
+        return out;
+    });
+};
+/** One line per system of record: what it is, where, and what usually lives there. */
+export function recordLine(r) {
+    const known = RECORD_KINDS[r.kind];
+    const label = known?.label ?? r.kind;
+    const head = r.title ? `${label}: ${r.title}` : label;
+    const parts = [r.workspace ? `workspace ${r.workspace}` : "", r.url ?? "", known?.hint ?? "", r.note ?? ""].filter(Boolean);
+    return `- ${head}${parts.length ? ` — ${parts.join("; ")}` : ""}`;
+}