@netnodeag/kraftwerk 0.79.0 → 0.81.0

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. ` +
@@ -538,7 +441,7 @@ export async function projectContext(slug, actor, opts = {}) {
             ? `## Knowledge\nOKF bundles linked to this project (markdown + YAML frontmatter under the knowledge root):\n` +
                 linkLines("knowledge", (l) => `- ${l.slug}${l.label ? ` (${l.label})` : ""}`) +
                 `\nRead with \`npx kraftwerk knowledge list <bundle>\`, \`get <bundle>/<path>\`, \`search <text>\`. ` +
-                `Write ONLY through \`npx kraftwerk knowledge put <bundle>/<path> --file <tmp.md> --actor ${actor}\` ` +
+                `Write ONLY through \`npx kraftwerk knowledge put <bundle>/<path> --file $KRAFTWERK_TEMP/<name>.md --actor ${actor}\` ` +
                 `(stamps provenance, maintains index.md/log.md — never hand-edit those).`
             : "",
         p.repos.length > 0
@@ -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("; ")}` : ""}`;
+}

package/dist/core/refs.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The reference registry: everything in a workspace that can be pointed
+ * at by name — knowledge bundles, vibeables, repositories, workflows,
+ * agents, projects, contacts, places and events. Each kind registers only
+ * a lookup (its storage and routes stay where they are); one resolver then
+ * serves every place a reference appears: a project's link lists, an
+ * event's place and contacts, a `contact:anna-meier` token in text, the
+ * ⌘K palette and the context an agent starts with.
+ *
+ * A reference is `<token>:<slug>` — the kind's singular token (contact,
+ * place, event, project, agent, workflow, repo, vibeable, knowledge) and
+ * the target's slug. Only registered tokens match, so `https:` and the
+ * like never do. A target that does not exist is reported (found: false),
+ * never an error — the same rule project links have always followed.
+ */
+export declare const REF_KIND_NAMES: readonly ["knowledge", "vibeables", "repos", "workflows", "agents", "projects", "contacts", "places", "events"];
+/** The kind's plural: the link-list name in project.yml and the folder/route name. */
+export type RefKind = (typeof REF_KIND_NAMES)[number];
+/** One existing target. */
+export interface RefTarget {
+    slug: string;
+    /** Display text next to the slug (an agent's name, a bundle's size); "" when there is nothing to add. */
+    label: string;
+    /** Where the web UI opens it (a hash route). */
+    href: string;
+}
+export interface RefKindDef {
+    kind: RefKind;
+    /** The token in text: contact in contact:anna-meier. */
+    token: string;
+    /** How the kind reads in a sentence ("knowledge bundle", "contact"). */
+    noun: string;
+    /** Every target that exists right now; [] when the feature is off. */
+    list(): Promise<RefTarget[]>;
+}
+/** One referenced 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;
+}
+/** A `kind:slug` token, resolved. */
+export interface ResolvedRef extends LinkState {
+    kind: RefKind;
+    token: string;
+    href: string;
+}
+export declare const REF_KINDS: readonly RefKindDef[];
+/** The kind registered under a plural name or a token; undefined for anything else. */
+export declare const refKind: (name: string) => RefKindDef | undefined;
+/** Which of the slugs exist right now, per kind. Kinds without slugs are not listed at all. */
+export declare function resolveRefs<K extends RefKind>(byKind: Record<K, string[]>): Promise<Record<K, LinkState[]>>;
+/** A `token:slug` reference in text: a registered token, a colon, a slug — not inside a word, a path or a URL. */
+export declare const REF_TOKEN_RE: RegExp;
+/** Every distinct reference in a text, in order of appearance. */
+export declare function findRefs(text: string): Array<{
+    token: string;
+    kind: RefKind;
+    slug: string;
+}>;
+/** Parse one reference ("contact:anna-meier"); null when it is not one. */
+export declare function parseRef(text: string): {
+    token: string;
+    kind: RefKind;
+    slug: string;
+} | null;
+/** Resolve references: each with whether its target exists and where it opens. */
+export declare function resolveTokens(refs: Array<{
+    kind: RefKind;
+    slug: string;
+}>): Promise<ResolvedRef[]>;
+/** Resolve one reference written as text; null when the text is not a reference. */
+export declare function resolveRef(text: string): Promise<ResolvedRef | null>;