@netnodeag/kraftwerk 0.48.0 → 0.50.0

package/dist/inspector/git.js

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { realpathSync } from "node:fs";
 import path from "node:path";
-import { reposRootFor, resolveProject, vibeablesRootFor, isSafeGitName } from "../config.js";
+import { projectsRootFor, reposRootFor, resolveProject, vibeablesRootFor, isSafeGitName } from "../config.js";
 import { ENV_FILE } from "../runner/docker.js";
 import { getOutputDir, getProjectRoot } from "./context.js";
 /**
@@ -32,7 +32,8 @@ import { getOutputDir, getProjectRoot } from "./context.js";
  * terminal nobody is watching.
  */
 /** Files that must never be staged, whatever the scope says. */
-const DENY = [
+/** Paths whose content is never shown or synced, whichever repo they sit in. */
+export const DENY = [
     /(^|\/)\.env($|\.)/,
     /(^|\/)\.envrc$/,
     new RegExp(`(^|/)${ENV_FILE.replace(/\./g, "\\.")}$`),
@@ -147,7 +148,7 @@ function netArgs(cmd, ...names) {
  * Pathspecs are globs by default, so a file called `note[1].md` would not
  * match itself. `:(literal)` turns the pattern off.
  */
-const literal = (p) => `:(literal)${p}`;
+export const literal = (p) => `:(literal)${p}`;
 /** Repo root for a directory, or null when it is not inside a git repo. */
 export async function repoRootFor(dir) {
     const r = await git(["rev-parse", "--show-toplevel"], dir);
@@ -203,7 +204,7 @@ async function checkedOut(repo) {
 }
 /**
  * The roots that may be committed, as repo-relative paths: the workflows,
- * knowledge, agents, skills, channels and vibeables roots this project
+ * knowledge, agents, skills, channels, vibeables and projects roots this project
  * declares, plus kraftwerk.yml and the project README. The output directory
  * is excluded even when it lives inside one of them.
  */
@@ -234,6 +235,8 @@ function scopeFor({ project, repoRoot }) {
         path.resolve(project.root, "channels"),
         // Vibeables are the workspace's own apps: versioned with it, unlike clones.
         vibeablesRootFor(project),
+        // Projects too: briefs, state and logs are the workspace's own record.
+        projectsRootFor(project),
         project.configPath,
         path.resolve(project.root, "README.md"),
     ];
@@ -284,7 +287,7 @@ async function hasLocalChanges(repoRoot) {
     return !(await git(["diff", "--cached", "--quiet"], repoRoot)).ok;
 }
 /** Label for a porcelain code, using whichever half is set. */
-function label(code) {
+export function label(code) {
     if (code === "??")
         return "untracked";
     const c = code.replace(/ /g, "");
@@ -305,7 +308,7 @@ function label(code) {
     return c || "changed";
 }
 /** Parse `git status --porcelain=v1 -z`, which NUL-separates and doubles up on renames and copies. */
-function parseStatus(out) {
+export function parseStatus(out) {
     const parts = out.split("\0").filter((p) => p.length > 0);
     const files = [];
     for (let i = 0; i < parts.length; i++) {
@@ -411,7 +414,7 @@ export async function gitStatus(fresh = false) {
     const blocked = all.filter((f) => !f.syncable).sort(byPath);
     const blockedHidden = Math.max(0, blocked.length - MAX_BLOCKED);
     const scopeError = scope.wholeRepo
-        ? "A configured root points at the repository root, which would put the whole repo in scope. Narrow workflows/knowledge/agents/skills/vibeables in kraftwerk.yml."
+        ? "A configured root points at the repository root, which would put the whole repo in scope. Narrow workflows/knowledge/agents/skills/vibeables/projects in kraftwerk.yml."
         : undefined;
     const value = {
         ...base,
@@ -448,11 +451,18 @@ export async function gitDiff(file) {
         return { diff: "", error: "not shown: not a changed file under the workspace paths" };
     if (!entry.syncable)
         return { diff: "", error: `not shown: ${entry.reason}` };
-    const { repoRoot } = st;
-    // A repo without commits yet has nothing for `diff HEAD` to compare with;
-    // there, as for an untracked file, the whole file is the change.
+    return diffAgainstHead(st.repoRoot, file, entry.code);
+}
+/**
+ * Unified diff of one path in a repo against HEAD, capped. The caller has
+ * checked that the path is a listed, showable change. A repo without
+ * commits yet has nothing for `diff HEAD` to compare with; there, as for an
+ * untracked file, the whole file is the change. Shared by the workspace
+ * diff and the repositories screen so the two never drift.
+ */
+export async function diffAgainstHead(repoRoot, file, code) {
     const hasHead = (await git(["rev-parse", "--verify", "-q", "HEAD"], repoRoot)).ok;
-    if (entry.code === "??" || !hasHead) {
+    if (code === "??" || !hasHead) {
         // --no-index exits 1 when the files differ, which is the normal case here.
         const r = await git(["diff", "--no-index", "--", "/dev/null", file], repoRoot);
         return r.stdout ? capDiff(r.stdout) : { diff: "", error: r.stderr || "no diff available" };
@@ -460,7 +470,7 @@ export async function gitDiff(file) {
     const r = await git(["diff", "HEAD", "--", literal(file)], repoRoot);
     return r.ok ? capDiff(r.stdout) : { diff: "", error: r.stderr || "diff failed" };
 }
-function capDiff(diff) {
+export function capDiff(diff) {
     if (diff.length <= MAX_DIFF)
         return { diff };
     const cut = diff.lastIndexOf("\n", MAX_DIFF);

package/dist/inspector/instances.d.ts

@@ -1,7 +1,7 @@
 import type { AgentSummary } from "./agents.js";
 import type { ChannelSummary } from "./channels.js";
 /** Durable per-project record. The root is the key; everything else derives from it. */
-export interface ProjectRecord {
+export interface WorkspaceRecord {
     root: string;
     firstSeen: string;
     lastStarted: string;
@@ -29,7 +29,7 @@ export interface DiscoveredInstance {
 }
 /**
  * One workspace as the switcher shows it: a known project (running or
- * not) or a running instance the projects registry doesn't know yet.
+ * not) or a running instance the workspace registry doesn't know yet.
  */
 export interface WorkspaceEntry {
     name: string;
@@ -49,6 +49,8 @@ export interface WorkspaceEntry {
     lastStarted?: string;
     lastStopped?: string;
 }
+/** File name of a root's record: a hash of the absolute root, the same under the old and the new directory. */
+export declare const workspaceRecordName: (root: string) => string;
 /** ~/… for display. */
 export declare const tildify: (p: string) => string;
 /** Write this instance's registry file (call once the server listens). */
@@ -60,15 +62,15 @@ export declare function unregisterInstance(): void;
 /** All other running instances, verified live. Cached briefly — /api/meta is polled. */
 export declare function discoverInstances(): Promise<DiscoveredInstance[]>;
 /** Upsert the project record for a root (call on every inspector start). */
-export declare function registerProject(root: string): Promise<void>;
-export declare const syncProjectAgents: (root: string, agents: AgentSummary[]) => Promise<void>;
-export declare const syncProjectChannels: (root: string, channels: ChannelSummary[]) => Promise<void>;
+export declare function registerWorkspace(root: string): Promise<void>;
+export declare const syncWorkspaceAgents: (root: string, agents: AgentSummary[]) => Promise<void>;
+export declare const syncWorkspaceChannels: (root: string, channels: ChannelSummary[]) => Promise<void>;
 /** Stamp lastStopped on clean shutdown. Sync so exit handlers can call it. */
-export declare function markProjectStopped(): void;
-/** All known projects, most recently started first. */
-export declare function listProjects(): Promise<ProjectRecord[]>;
-/** Drop a project record (the root itself is untouched). */
-export declare function forgetProject(root: string): Promise<boolean>;
+export declare function markWorkspaceStopped(): void;
+/** All known workspaces, most recently started first. */
+export declare function listWorkspaceRecords(): Promise<WorkspaceRecord[]>;
+/** Drop a workspace record (the root itself is untouched) — from the legacy directory too, see migrateRegistry. */
+export declare function forgetWorkspace(root: string): Promise<boolean>;
 /**
  * The switcher's view: every known project joined with the live instances,
  * plus running instances with no project record yet. The calling instance
@@ -118,14 +120,14 @@ export interface StartResult {
  * Waits up to ~5s for the new inspector to answer so callers can link
  * straight to it.
  */
-export declare function startProject(root: string): Promise<StartResult>;
+export declare function startWorkspace(root: string): Promise<StartResult>;
 /**
  * Stop a running workspace: SIGTERM to its server process, which
  * unregisters, stamps lastStopped and exits; the `kraftwerk ui` supervisor
  * follows. Matched by root, or by url for instances from older versions
  * that registered no root. Waits up to ~5s for the port to go quiet.
  */
-export declare function stopProject(target: {
+export declare function stopWorkspace(target: {
     root?: string;
     url?: string;
 }): Promise<{

package/dist/inspector/instances.js

@@ -14,25 +14,28 @@ import { selfCommand } from "./self-command.js";
  * Registered ports are verified by probing /api/meta on read; entries
  * that stop answering are pruned, so crashes leave no ghosts.
  *
- * projects/<hash(root)>.json — durable. One record per project root that
+ * workspaces/<hash(root)>.json — durable. One record per workspace root that
  * ever ran the inspector on this machine, keyed by the root and never
  * pruned automatically. Everything else (name, icon, port) is derived from
  * the root's kraftwerk.yml at read time, so it is always current. A
  * project that is not running can be started again from the switcher or
- * `kraftwerk projects start` — that is what makes a killed UI findable.
+ * `kraftwerk workspaces start` — that is what makes a killed UI findable.
  * The record also carries the project's agent roster (written whenever the
  * instance reads it), so the ⌘K palette can list every workspace's agents
  * from a handful of small files without probing anything.
  */
 const HOME = path.join(os.homedir(), ".kraftwerk");
 const INSTANCES_DIR = path.join(HOME, "instances");
-const PROJECTS_DIR = path.join(HOME, "projects");
+const WORKSPACES_DIR = path.join(HOME, "workspaces");
+/** Where the records lived before 0.49 (`kraftwerk projects`); moved over once, see migrateRegistry. */
+const LEGACY_WORKSPACES_DIR = path.join(HOME, "projects");
 const LOGS_DIR = path.join(HOME, "logs");
 const selfFile = () => path.join(INSTANCES_DIR, `${process.pid}.json`);
 let selfPort = null;
 let selfRoot = null;
-const projectKey = (root) => createHash("sha1").update(absolutePath(root)).digest("hex").slice(0, 16);
-const projectFile = (root) => path.join(PROJECTS_DIR, `${projectKey(root)}.json`);
+/** File name of a root's record: a hash of the absolute root, the same under the old and the new directory. */
+export const workspaceRecordName = (root) => `${createHash("sha1").update(absolutePath(root)).digest("hex").slice(0, 16)}.json`;
+const recordFile = (root) => path.join(WORKSPACES_DIR, workspaceRecordName(root));
 /** ~/… for display. */
 export const tildify = (p) => {
     const home = os.homedir();
@@ -132,8 +135,38 @@ export async function discoverInstances() {
     cache = { at: Date.now(), entries };
     return entries;
 }
-/* ---------- projects (durable) ---------- */
-async function readProject(file) {
+/* ---------- workspaces (durable) ---------- */
+let migrated = null;
+/**
+ * Records were written under ~/.kraftwerk/projects until 0.48. Copy them
+ * into the new directory once per process, never overwriting a record
+ * that is already there, so a machine that upgrades keeps every workspace
+ * it knew. The old directory stays: an inspector of an older version may
+ * still be running and reading it. forgetWorkspace drops a record from
+ * both, so a forgotten workspace does not come back on the next start.
+ * Best-effort like everything else in this registry.
+ */
+function migrateRegistry() {
+    return (migrated ??= (async () => {
+        let legacy;
+        try {
+            legacy = await fs.readdir(LEGACY_WORKSPACES_DIR);
+        }
+        catch {
+            return;
+        }
+        try {
+            await fs.mkdir(WORKSPACES_DIR, { recursive: true });
+            for (const f of legacy) {
+                if (!f.endsWith(".json"))
+                    continue;
+                await fs.copyFile(path.join(LEGACY_WORKSPACES_DIR, f), path.join(WORKSPACES_DIR, f), fsSync.constants.COPYFILE_EXCL).catch(() => { });
+            }
+        }
+        catch { }
+    })());
+}
+async function readRecord(file) {
     try {
         const rec = JSON.parse(await fs.readFile(file, "utf8"));
         if (typeof rec.root !== "string")
@@ -153,12 +186,13 @@ async function readProject(file) {
     }
 }
 /** Upsert the project record for a root (call on every inspector start). */
-export async function registerProject(root) {
+export async function registerWorkspace(root) {
+    await migrateRegistry();
     const abs = absolutePath(root);
     const now = new Date().toISOString();
     try {
-        await fs.mkdir(PROJECTS_DIR, { recursive: true });
-        const prev = await readProject(projectFile(abs));
+        await fs.mkdir(WORKSPACES_DIR, { recursive: true });
+        const prev = await readRecord(recordFile(abs));
         const rec = {
             root: abs,
             firstSeen: prev?.firstSeen || now,
@@ -167,7 +201,7 @@ export async function registerProject(root) {
             ...(prev?.agents ? { agents: prev.agents } : {}),
             ...(prev?.channels ? { channels: prev.channels } : {}),
         };
-        await fs.writeFile(projectFile(abs), JSON.stringify(rec, null, 2));
+        await fs.writeFile(recordFile(abs), JSON.stringify(rec, null, 2));
     }
     catch { } // best-effort, like the instance file
 }
@@ -178,13 +212,14 @@ const synced = new Map();
  * changes when the list did. Roots with no record (a CLI run in a project
  * that never started the inspector) are left alone.
  */
-async function syncProjectList(root, key, list) {
+async function syncWorkspaceList(root, key, list) {
+    await migrateRegistry();
     const stamp = `${root}\n${JSON.stringify(list)}`;
     if (synced.get(key) === stamp)
         return;
     try {
-        const file = projectFile(root);
-        const rec = await readProject(file);
+        const file = recordFile(root);
+        const rec = await readRecord(file);
         if (!rec)
             return;
         await fs.writeFile(file, JSON.stringify({ ...rec, [key]: list }, null, 2));
@@ -192,41 +227,46 @@ async function syncProjectList(root, key, list) {
     }
     catch { }
 }
-export const syncProjectAgents = (root, agents) => syncProjectList(root, "agents", agents);
-export const syncProjectChannels = (root, channels) => syncProjectList(root, "channels", channels);
+export const syncWorkspaceAgents = (root, agents) => syncWorkspaceList(root, "agents", agents);
+export const syncWorkspaceChannels = (root, channels) => syncWorkspaceList(root, "channels", channels);
 /** Stamp lastStopped on clean shutdown. Sync so exit handlers can call it. */
-export function markProjectStopped() {
+export function markWorkspaceStopped() {
     if (!selfRoot)
         return;
     try {
-        const file = projectFile(selfRoot);
+        const file = recordFile(selfRoot);
         const rec = JSON.parse(fsSync.readFileSync(file, "utf8"));
         rec.lastStopped = new Date().toISOString();
         fsSync.writeFileSync(file, JSON.stringify(rec, null, 2));
     }
     catch { }
 }
-/** All known projects, most recently started first. */
-export async function listProjects() {
+/** All known workspaces, most recently started first. */
+export async function listWorkspaceRecords() {
+    await migrateRegistry();
     let files;
     try {
-        files = await fs.readdir(PROJECTS_DIR);
+        files = await fs.readdir(WORKSPACES_DIR);
     }
     catch {
         return [];
     }
-    const recs = await Promise.all(files.filter((f) => f.endsWith(".json")).map((f) => readProject(path.join(PROJECTS_DIR, f))));
+    const recs = await Promise.all(files.filter((f) => f.endsWith(".json")).map((f) => readRecord(path.join(WORKSPACES_DIR, f))));
     return recs
         .filter((r) => r != null)
         .sort((a, b) => b.lastStarted.localeCompare(a.lastStarted));
 }
-/** Drop a project record (the root itself is untouched). */
-export async function forgetProject(root) {
+/** Drop a workspace record (the root itself is untouched) — from the legacy directory too, see migrateRegistry. */
+export async function forgetWorkspace(root) {
+    await migrateRegistry();
+    const legacy = fs.unlink(path.join(LEGACY_WORKSPACES_DIR, workspaceRecordName(root))).catch(() => { });
     try {
-        await fs.unlink(projectFile(root));
+        await fs.unlink(recordFile(root));
+        await legacy;
         return true;
     }
     catch {
+        await legacy;
         return false;
     }
 }
@@ -268,7 +308,7 @@ let wsCache = null;
 export async function discoverWorkspaces() {
     if (wsCache && Date.now() - wsCache.at < 5_000)
         return wsCache.entries;
-    const [projects, live] = await Promise.all([listProjects(), discoverInstances()]);
+    const [projects, live] = await Promise.all([listWorkspaceRecords(), discoverInstances()]);
     const liveByRoot = new Map(live.filter((i) => i.root).map((i) => [i.root, i]));
     const consumed = new Set();
     const entries = (await Promise.all(projects
@@ -353,7 +393,7 @@ export async function listWorkspacesDetailed() {
     const all = [...others];
     if (selfRoot && selfPort) {
         const d = await describeRoot(selfRoot);
-        const rec = await readProject(projectFile(selfRoot));
+        const rec = await readRecord(recordFile(selfRoot));
         all.unshift({
             name: d.name,
             icon: d.icon,
@@ -373,7 +413,7 @@ export async function listWorkspacesDetailed() {
         const base = { ...e, current, state: e.live ? "running" : "stopped" };
         if (!e.root)
             return base;
-        const rec = await readProject(projectFile(e.root));
+        const rec = await readRecord(recordFile(e.root));
         base.firstSeen = rec?.firstSeen;
         base.startCount = rec?.startCount;
         // "missing" = the folder is gone; "orphaned" = it is still there but
@@ -418,7 +458,7 @@ export async function listWorkspacesDetailed() {
  * Waits up to ~5s for the new inspector to answer so callers can link
  * straight to it.
  */
-export async function startProject(root) {
+export async function startWorkspace(root) {
     const abs = absolutePath(root);
     const { name, port, exists } = await describeRoot(abs);
     if (!exists)
@@ -441,7 +481,7 @@ export async function startProject(root) {
     let stdio = ["ignore", "ignore", "ignore"];
     try {
         await fs.mkdir(LOGS_DIR, { recursive: true });
-        log = path.join(LOGS_DIR, `${projectKey(abs)}.log`);
+        log = path.join(LOGS_DIR, workspaceRecordName(abs).replace(/\.json$/, ".log"));
         const fd = fsSync.openSync(log, "a");
         fsSync.writeSync(fd, `\n--- ${new Date().toISOString()} start ${name} (${abs}) ---\n`);
         stdio = ["ignore", fd, fd];
@@ -487,7 +527,7 @@ export async function startProject(root) {
  * follows. Matched by root, or by url for instances from older versions
  * that registered no root. Waits up to ~5s for the port to go quiet.
  */
-export async function stopProject(target) {
+export async function stopWorkspace(target) {
     if (target.root && absolutePath(target.root) === selfRoot) {
         return { ok: false, error: "that is this workspace — stop it from its own terminal or pid" };
     }

package/dist/inspector/notifications.js

@@ -43,6 +43,8 @@ export function clipBody(text) {
 export function chatHref(meta) {
     if (meta.scope.kind === "channel")
         return `/channels/${meta.scope.slug}`;
+    if (meta.scope.kind === "project")
+        return `/projects/${meta.scope.slug}/chat/${meta.id}`;
     return meta.scope.kind === "agent" ? `/agents/${meta.scope.slug}/chat/${meta.id}` : `/agents/chats/${meta.id}`;
 }
 export async function pushNotification(input) {

package/dist/inspector/projects.d.ts

@@ -0,0 +1,167 @@
+import { type Project } from "../config.js";
+import type { ChatAgentId } from "./chat/types.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
+ * outside kraftwerk, and links to the workspace's knowledge, vibeables,
+ * repositories, workflows and agents. Working in a project is chat: a
+ * session scoped to it carries all of this as context (sessions.ts).
+ *
+ * One folder per project under the projects root (`projects.root` in
+ * kraftwerk.yml, default kraftwerk-data/projects/). Like agents and
+ * knowledge it is part of the workspace: versioned by the workspace git,
+ * no repository of its own. The folder is the registry — whatever
+ * directory under the root holds a project.yml is a project.
+ *
+ *   projects/<slug>/project.yml   # title, status, goal, harness/model/effort, records, links (slug lists)
+ *   projects/<slug>/brief.md      # the goal in full: what done looks like, constraints, stakeholders
+ *   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
+ * 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 type LinkKind = (typeof LINK_KINDS)[number];
+export interface ProjectDef {
+    slug: string;
+    title: string;
+    status: ProjectStatus;
+    /** One line: what the project is for. brief.md holds the long form. */
+    goal: string;
+    /** Harness every chat in the project runs on, like an agent's. Default: claude. */
+    harness: ChatAgentId;
+    /** Model for that harness; absent = the harness default. */
+    model?: string;
+    /** Reasoning effort (low … max); absent = the harness default. */
+    effort?: string;
+    records: SystemOfRecord[];
+    /** OKF bundle names. */
+    knowledge: string[];
+    /** Folder names under the vibeables root. */
+    vibeables: string[];
+    /** Folder names under the repos root. */
+    repos: string[];
+    /** Workflow slugs. */
+    workflows: string[];
+    /** Agent slugs. */
+    agents: string[];
+}
+export interface ProjectSummary extends ProjectDef {
+    /** Absolute folder path. */
+    path: string;
+    /** Newest change inside the folder. */
+    updatedAt?: string;
+    /** 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;
+    state: string;
+    log: string;
+    links: ProjectLinks;
+}
+export interface ProjectsView {
+    enabled: boolean;
+    root?: string;
+    projects: ProjectSummary[];
+    /** Set when the feature is off or the root cannot be read. */
+    error?: string;
+}
+/** Every field optional: omitted = untouched. */
+export interface SaveProjectInput {
+    title?: string;
+    status?: string;
+    goal?: string;
+    harness?: string;
+    model?: string;
+    effort?: string;
+    records?: unknown;
+    knowledge?: unknown;
+    vibeables?: unknown;
+    repos?: unknown;
+    workflows?: unknown;
+    agents?: 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 function openProjects(): Promise<{
+    project?: Project;
+    root?: string;
+    off?: boolean;
+    error?: string;
+}>;
+/** Make sure the root exists; runs when the feature is switched on. */
+export declare function ensureProjectsRoot(): Promise<void>;
+/** Every project under the root: active ones first, then by title. */
+export declare function listProjects(): Promise<ProjectsView>;
+/** 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>;
+/** 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. */
+export declare function projectStarter(def: ProjectDef): Record<string, string>;
+export declare function createProject(input: {
+    title: string;
+    goal?: string;
+    slug?: string;
+    harness?: string;
+    model?: string;
+    effort?: string;
+}): Promise<ProjectDetail>;
+/** Merge the given fields into project.yml (and brief/state when given); lists replace wholesale. */
+export declare function saveProject(slug: string, input: SaveProjectInput): Promise<ProjectDetail>;
+/** Add or remove one slug in a link list. */
+export declare function linkProject(slug: string, kind: string, target: string, remove?: boolean): Promise<ProjectDetail>;
+/**
+ * Prepend an entry under today's heading in log.md (newest first, like a
+ * knowledge bundle's log). The actor is stamped so a line written by an
+ * agent reads as such next to a human's.
+ */
+export declare function appendProjectLog(slug: string, entry: string, actor: string): Promise<string>;
+/** Remove the folder; its history stays in the workspace git. */
+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.
+ * `actor` is stamped on log entries the agent writes.
+ */
+export declare function projectContext(slug: string, actor: string, opts?: {
+    member?: boolean;
+}): Promise<string>;