@netnodeag/kraftwerk 0.79.0 → 0.81.0

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"],
@@ -121,6 +137,8 @@ export const ROUTES = {
     "settings.save": ["PUT", "/api/settings"],
     "skills.get": ["GET", "/api/skills/:name"],
     "skills.list": ["GET", "/api/skills"],
+    "temp.clean": ["DELETE", "/api/temp"],
+    "temp.list": ["GET", "/api/temp"],
     "trash.empty": ["DELETE", "/api/trash"],
     "trash.list": ["GET", "/api/trash"],
     "trash.purge": ["POST", "/api/trash/purge"],

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);

package/dist/core/chat/acp.js

@@ -3,6 +3,7 @@ import { promises as fs } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { RequestError, } from "@agentclientprotocol/sdk";
 import { adapterEnv, airMeta, connectAcp, EXT_METHODS, EXT_NOTIFICATIONS, fileChangeReportMeta, openSession, withAdapter, } from "../../acp.js";
+import { tempEnv } from "../temp.js";
 import { unattendedMode } from "./permissions.js";
 /**
  * ACP-backed chat: spawn an adapter (claude-agent-acp / codex-acp) as a
@@ -389,7 +390,7 @@ export async function startAcpBackend(agent, cwd, hooks, tuning = {}) {
     };
     const { child, conn } = await connectAcp(agent, {
         cwd,
-        env: adapterEnv(agent, tuning),
+        env: { ...adapterEnv(agent, tuning), ...(tuning.temp ? tempEnv(tuning.temp) : {}) },
         client,
         clientName: "kraftwerk-inspector",
         elicitation: true,

package/dist/core/chat/backend.d.ts

@@ -37,6 +37,8 @@ export interface BackendTuning {
     skillDirs?: string[];
     /** claude: extra directories the session may work in (e.g. project root for run chats). */
     addDirs?: string[];
+    /** The session's scratch folder (core/temp.ts): handed to the process as TMPDIR and KRAFTWERK_TEMP. */
+    temp?: string;
     /**
      * Nobody is watching this session live (routine runs). The backend selects
      * the harness's own hands-off permission mode — the harness keeps deciding

package/dist/core/chat/context.js

@@ -7,10 +7,12 @@ import { getAgent, listAgents } from "../agents.js";
 import { listRepos } from "../repos.js";
 import { listVibeables, vibeableStatus, VIBEABLE_CONFIG_FILE } from "../vibeables.js";
 import { projectContext } from "../projects.js";
+import { entitiesContext } from "../entities.js";
 import { unattendedTimeoutLabel } from "./permissions.js";
 import { getChannel } from "../channels.js";
 import { JOURNAL_FILE, journalExcerpt, readJournal } from "../journal.js";
 import { filesSummary } from "../files.js";
+import { sessionTemp, tempContext } from "../temp.js";
 /**
  * What an agent is told about where it works: the skills it may use and
  * the scope's context block (the workspace, a run, a project, a channel,
@@ -84,8 +86,8 @@ async function agentKnowledgeContext(def) {
         `part of your job. Consult them before answering questions in their domain, and keep them current ` +
         `when you learn something durable:\n${lines}\n\n` +
         `Read with \`npx kraftwerk knowledge list <bundle>\`, \`get <bundle>/<path>\`, \`search <text>\`. ` +
-        `Write ONLY through \`npx kraftwerk knowledge put <bundle>/<path> --file <tmp.md> --actor ${def.slug}/${def.harness}\` ` +
-        `(write the markdown to a temp file first; the CLI stamps provenance and maintains index.md/log.md). ` +
+        `Write ONLY through \`npx kraftwerk knowledge put <bundle>/<path> --file $KRAFTWERK_TEMP/<name>.md --actor ${def.slug}/${def.harness}\` ` +
+        `(write the markdown into your temp folder first; the CLI stamps provenance and maintains index.md/log.md). ` +
         `Never hand-edit index.md or log.md, and never add \`verified\` yourself — verification is the human's ` +
         `click in the UI.\n\n`);
 }
@@ -131,7 +133,8 @@ export async function agentFilesContext(def) {
     return (`## Files\nThe workspace's shared files (any format: brand assets, templates, contracts, …) are in ${ws.root}/ (${ws.count} file${ws.count === 1 ? "" : "s"}). ` +
         (linked ? `The folders that are part of your job:\n${linked}\n` : "") +
         `Work you do for a project belongs in that project's files folder, not here. What you produce in a direct session goes to ${ws.root}/inbox/. ` +
-        `Delete nothing there unless asked.\n\n`);
+        `Only finished work and the user's own material belong in these folders — scratch, intermediate and downloaded files go to your ` +
+        `temp folder (below), never here. Delete nothing there unless asked.\n\n`);
 }
 /**
  * "## Your vibeables" block: the apps an agent builds and maintains, linked
@@ -309,7 +312,7 @@ async function baseScopeContext(scope, agent) {
             `- Favor structural markdown (headings, tables, lists) over prose.\n\n` +
             `ALWAYS write through the kraftwerk CLI so provenance is stamped and the bundle log/index stay maintained:\n` +
             `- \`npx kraftwerk knowledge init <bundle>\` — new bundle\n` +
-            `- \`npx kraftwerk knowledge put <bundle>/<path> --file <tmp.md> --actor kraftwerk-chat/${agent}\` — create/update a concept ` +
+            `- \`npx kraftwerk knowledge put <bundle>/<path> --file $KRAFTWERK_TEMP/<name>.md --actor kraftwerk-chat/${agent}\` — create/update a concept ` +
             `(write the markdown to a temp file first; the CLI stamps generated.by/at, appends log.md, regenerates index.md)\n` +
             `- \`npx kraftwerk knowledge list [bundle]\`, \`get <bundle>/<path>\`, \`search <text>\`, \`validate\`\n` +
             `Do not hand-edit index.md or log.md (derived/maintained), and do not add \`verified\` yourself — ` +
@@ -348,7 +351,7 @@ async function baseScopeContext(scope, agent) {
             `## Recent runs\n${runLines || "(none)"}\n\n` +
             `## Knowledge\nOKF bundles in this project:\n${bundleLines || "(none)"}\n` +
             `Read with \`npx kraftwerk knowledge list [bundle]\`, \`get <bundle>/<path>\`, \`search <text>\`. ` +
-            `Write ONLY through \`npx kraftwerk knowledge put <bundle>/<path> --file <tmp.md> --actor kraftwerk-chat/${agent}\` ` +
+            `Write ONLY through \`npx kraftwerk knowledge put <bundle>/<path> --file $KRAFTWERK_TEMP/<name>.md --actor kraftwerk-chat/${agent}\` ` +
             `(stamps provenance, maintains index.md/log.md — never hand-edit those).\n\n` +
             `## Agents\n${agentLines || "(none)"}\n` +
             `These are persistent agents (defined under agents/); the user talks to them on the ` +
@@ -391,7 +394,7 @@ export async function scopeContext(meta, seat) {
     const agent = seat.harness;
     // The repositories block reads every clone from git, so it runs alongside
     // the rest instead of adding its spawns to the first prompt's latency.
-    const [base, repos, vibe, skills, channel, project] = await Promise.all([
+    const [base, repos, vibe, skills, channel, project, entities] = await Promise.all([
         baseScopeContext(scope, agent),
         scope.kind === "agent" || scope.kind === "kraftwerk" ? reposContext() : Promise.resolve(""),
         meta.vibeable ? vibeableContext(meta.vibeable, meta.cwd) : Promise.resolve(""),
@@ -399,8 +402,13 @@ export async function scopeContext(meta, seat) {
         meta.scope.kind === "channel" ? channelContext(meta.scope.slug, seat.key) : Promise.resolve(""),
         // A channel that works in a project: every member reads the project too, as a member, not as its assistant.
         meta.scope.kind === "channel" && meta.project ? projectContext(meta.project, `${seat.key}/${agent}`, { member: true }) : Promise.resolve(""),
+        // Who, where and when: the workspace's contacts, places and events, wherever the chat works (a run discusses its own artifacts only).
+        scope.kind === "run" ? Promise.resolve("") : entitiesContext().catch(() => ""),
     ]);
-    return [base, channel, project, repos, vibe, RENDERING_BLOCK, skillsBlock(skills)].filter(Boolean).join("\n\n");
+    // Every session has a scratch folder of its own (core/temp.ts), named by its absolute path: a run chat or a
+    // vibeable session works in another folder than the workspace root. The block comes after the files blocks it refers to.
+    const temp = await sessionTemp(meta.id).catch(() => null);
+    return [base, channel, project, repos, entities, vibe, temp ? tempContext(temp.abs) : "", RENDERING_BLOCK, skillsBlock(skills)].filter(Boolean).join("\n\n");
 }
 /** The channel block a member agent gets once per process: who is here, how turns work, how to hand over. */
 async function channelContext(slug, self) {

package/dist/core/chat/pi.js

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { workspaceEnv } from "../env.js";
+import { tempEnv } from "../temp.js";
 const clip = (raw) => {
     const oneLine = String(raw ?? "").replace(/\s+/g, " ").trim();
     return oneLine.length > 120 ? `${oneLine.slice(0, 120)}…` : oneLine;
@@ -24,7 +25,7 @@ export function startPiBackend(cwd, hooks, tuning = {}) {
                 const proc = spawn("pi", ["-p", "--mode", "json", "--session-id", sessionId, ...tuningArgs], {
                     cwd,
                     stdio: ["pipe", "pipe", "pipe"],
-                    env: workspaceEnv(),
+                    env: { ...workspaceEnv(), ...(tuning.temp ? tempEnv(tuning.temp) : {}) },
                 });
                 child = proc;
                 proc.stdin.write(text);

package/dist/core/chat/seats.js

@@ -9,6 +9,7 @@ import { chatHref, dismissKey, pushNotification } from "../notifications.js";
 import { writeMeta } from "./store.js";
 import { availableSkills } from "./context.js";
 import { effectiveCwd } from "./sessions.js";
+import { sessionTemp } from "../temp.js";
 import { emit, isUnattended, ownerLabel, seatAuthor } from "./state.js";
 /**
  * Starting an agent process for a seat: its harness, tuning (model,
@@ -57,6 +58,8 @@ async function backendTuning(meta, seat) {
         if (skills.length > 0)
             tuning.skillDirs = skills.map((s) => s.dir);
     }
+    // Every seat gets the chat's scratch folder as its temp dir (core/temp.ts), so nothing temporary lands in files/ or /tmp.
+    tuning.temp = (await sessionTemp(meta.id)).abs;
     return tuning;
 }
 export async function ensureBackend(state, seat) {

package/dist/core/chat/sessions.js

@@ -7,6 +7,7 @@ import { deleteAgentSession, listAgentSessions } from "./acp.js";
 import { chatHref, pushNotification } from "../notifications.js";
 import { readIdentity } from "../identity.js";
 import { moveToTrash } from "../trash.js";
+import { removeSessionTemp } from "../temp.js";
 import { attachmentPath, copyChatFiles, listChatMetas, newChatId, readMetaAt, safeChatDir, writeMeta } from "./store.js";
 import { postChannelMessage } from "./channel-turns.js";
 import { expandSkillInvocation, scopeContext } from "./context.js";
@@ -526,6 +527,8 @@ export async function deleteChat(id) {
     dropBackend(state);
     chatStates().delete(id);
     await moveToTrash("chats", id, safeChatDir(id));
+    // Scratch, not a deliverable: gone for good with the chat.
+    await removeSessionTemp(id).catch(() => { });
     return {};
 }
 /** The agents' own transcripts of a chat folder (one in the trash), deleted for good. Best effort. */

package/dist/core/entities.d.ts

@@ -0,0 +1,171 @@
+import { type EntityKind, type ResolvedWorkspace } from "../config.js";
+import { recordLine, type SystemOfRecord } from "./records.js";
+import { type LinkState, type RefKind } from "./refs.js";
+/**
+ * Contacts, places and events: the workspace's own records of who, where
+ * and when. One Markdown file per entry under the kind's root (`contacts:`,
+ * `places:`, `events:` in kraftwerk.yml, default kraftwerk-data/<kind>/):
+ * the typed fields in YAML frontmatter, free notes in the body. Readable
+ * and editable by people and agents, versioned by the workspace git,
+ * deleted into the trash.
+ *
+ *   contacts/anna-meier.md            title, role, org, email, phone, place, url, tags, records + notes
+ *   places/netnode-office.md          title, address, lat, lng, url, tags, records + notes
+ *   events/2026-11-03-kickoff.md      title, start, end, place, contacts, project, url, tags, records + notes
+ *
+ * The three kinds share this store; each is a small definition (its
+ * fields, how its slug derives, how it sorts, how it reads in one line).
+ * Fields that point at other things (a contact's place, an event's place,
+ * contacts and project) hold slugs and are resolved through the reference
+ * registry (refs.ts), so a missing target is reported, never an error.
+ * Systems of record say where the truth lives outside kraftwerk (CRM,
+ * newsletter tool, calendar, Google Maps); a place without one gets a
+ * Google Maps link derived from its coordinates or address.
+ */
+export interface EntityBase {
+    slug: string;
+    title: string;
+    tags: string[];
+    records: SystemOfRecord[];
+    /** Frontmatter keys this kind does not define; kept verbatim across saves. */
+    extra?: Record<string, unknown>;
+}
+export interface ContactDef extends EntityBase {
+    role?: string;
+    org?: string;
+    email?: string;
+    phone?: string;
+    /** A place's slug (place:<slug>). */
+    place?: string;
+    url?: string;
+}
+export interface PlaceDef extends EntityBase {
+    address?: string;
+    lat?: number;
+    lng?: number;
+    url?: string;
+    /** Derived, never written: the google-maps record's URL, else one from lat/lng or the address. */
+    mapsUrl?: string;
+}
+export interface EventDef extends EntityBase {
+    /** ISO date (2026-11-03) or date-time (2026-11-03T14:00, optionally with seconds and a zone). */
+    start: string;
+    end?: string;
+    /** A place's slug. */
+    place?: string;
+    /** Contact slugs. */
+    contacts: string[];
+    /** A project's slug. */
+    project?: string;
+    url?: string;
+}
+export type FieldType = "text" | "email" | "url" | "number" | "date" | "list" | "ref" | "refs";
+/** One typed frontmatter field beyond the shared ones (title, tags, records); drives validation, the CLI options and the web form. */
+export interface FieldSpec {
+    name: string;
+    label: string;
+    type: FieldType;
+    /** For ref/refs: what the slugs point at. */
+    refKind?: RefKind;
+    required?: boolean;
+    /** One line for the CLI option and the form's placeholder. */
+    hint: string;
+}
+export interface EntityKindDef<D extends EntityBase = EntityBase, K extends EntityKind = EntityKind> {
+    /** The literal kind, so a factory built on the definition yields `contacts.list` and `/api/contacts/:slug` as types. */
+    kind: K;
+    /** The token in references: contact in contact:anna-meier. */
+    singular: string;
+    /** Material icon name the UI shows for the kind. */
+    icon: string;
+    fields: FieldSpec[];
+    /** The default slug of a new entry. */
+    slugFor(def: D): string;
+    /** List order. */
+    sort(a: D, b: D): number;
+    /** What says more than the title (role and org, address, date); "" when there is nothing. */
+    detail(def: D): string;
+    /** One line that stands for the entry in lists, link labels and agent context: the title with its detail. */
+    describe(def: D): string;
+    /** Checks across fields (an event's end after its start); throws the one error to show. */
+    validate?(def: D): void;
+    /** Fields computed on read and never written (a place's maps URL); every derived key is present, undefined when there is no value. */
+    derive?(def: D): Partial<D>;
+    /** The days an entry covers, for a `from`/`to` filter on the list: an entry counts while it is still running. */
+    span?(def: D): {
+        start: string;
+        end: string;
+    };
+}
+export type EntitySummary<D extends EntityBase> = D & {
+    /** Absolute file path. */
+    path: string;
+    updatedAt?: string;
+    /** Set when the file's frontmatter is unusable; the rest shows defaults. */
+    configError?: string;
+};
+export type EntityDetail<D extends EntityBase> = EntitySummary<D> & {
+    /** The Markdown body. */
+    notes: string;
+    /** Per ref field (place, contacts, project): the referenced slugs and whether each exists. */
+    links: Record<string, LinkState[]>;
+};
+export interface EntitiesView<D extends EntityBase> {
+    enabled: boolean;
+    root?: string;
+    items: EntitySummary<D>[];
+    /** Set when the feature is off or the root cannot be read. */
+    error?: string;
+}
+/** Fields of a create or save: shared ones, the kind's, plus notes; every one optional. */
+export type EntityInput = Record<string, unknown> & {
+    title?: string;
+    notes?: string;
+    slug?: string;
+};
+export declare const CONTACTS: EntityKindDef<ContactDef, "contacts">;
+export declare const PLACES: EntityKindDef<PlaceDef, "places">;
+/** The Google Maps link of a place: its google-maps record, else its coordinates, else its address; undefined with none of them. */
+export declare function mapsUrl(p: PlaceDef): string | undefined;
+export declare const EVENTS: EntityKindDef<EventDef, "events">;
+/**
+ * When an event's ISO value happens, as a timestamp: a plain day is local
+ * midnight (its end, when asked, the last moment of that day), a date-time
+ * is what Date reads (local without a zone, else the zone it names) — so
+ * values with different offsets order by the instant, not by their text.
+ */
+export declare function eventTime(iso: string, endOfDay?: boolean): number;
+export declare const ENTITY_DEFS: {
+    [K in EntityKind]: EntityKindDef<any>;
+};
+export declare const entityDef: (kind: string) => EntityKindDef | undefined;
+export declare function openEntities(kind: EntityKind): Promise<{
+    project?: ResolvedWorkspace;
+    root?: string;
+    off?: boolean;
+    error?: string;
+}>;
+/** Make sure the root exists; runs when the feature is switched on. */
+export declare function ensureEntitiesRoot(kind: EntityKind): Promise<void>;
+export declare function safeEntitySlug(def: EntityKindDef<any>, slug: string): string;
+/** Every entry under the kind's root in the kind's order; `from`/`to` narrow kinds with a date (events) by it. */
+export declare function listEntities<D extends EntityBase>(def: EntityKindDef<D>, range?: {
+    from?: string;
+    to?: string;
+}): Promise<EntitiesView<D>>;
+/** One entry with its notes and link states; null when there is no such file. */
+export declare function getEntity<D extends EntityBase>(def: EntityKindDef<D>, slug: string): Promise<EntityDetail<D> | null>;
+export declare function createEntity<D extends EntityBase>(def: EntityKindDef<D>, input: EntityInput): Promise<EntityDetail<D>>;
+/** Merge the given fields into the frontmatter (and the notes when given); lists replace wholesale, "" clears a field. */
+export declare function saveEntity<D extends EntityBase>(def: EntityKindDef<D>, slug: string, input: EntityInput): Promise<EntityDetail<D>>;
+/** Move the file to the trash. */
+export declare function deleteEntity(def: EntityKindDef<any>, slug: string): Promise<void>;
+/** One line for an entry in a context block: its token, how it reads, its records. */
+export declare function entityLine<D extends EntityBase>(def: EntityKindDef<D>, d: D): string;
+/**
+ * The "## Contacts, places and events" block every chat starts with when at
+ * least one of the kinds is on: what exists (counts, the next events), how
+ * to reference an entry, and the CLI that reads and writes them.
+ */
+export declare function entitiesContext(): Promise<string>;
+export { recordLine };