@knotpad/app 0.1.0

package/lib/extract-snippet.test.ts

@@ -0,0 +1,123 @@
+import { describe, it, expect } from "vitest";
+import { extractSnippet } from "./extract-snippet";
+
+describe("extractSnippet", () => {
+  it("extracts snippet from a checkbox task line", () => {
+    const content = [
+      "# Meeting notes",
+      "- [ ] ship docs @alice",
+      "- [ ] review PR",
+      "Some follow-up text",
+    ].join("\n");
+
+    const result = extractSnippet(content, "ship docs");
+    expect(result).toContain("- [ ] ship docs @alice");
+    expect(result).toContain("# Meeting notes");
+    expect(result).toContain("- [ ] review PR");
+  });
+
+  it("extracts snippet from a ((task title)) wikilink in plain text", () => {
+    const content = [
+      "Plan for the week:",
+      "We need to ((ship docs)) before Friday.",
+      "Then we can relax.",
+    ].join("\n");
+
+    const result = extractSnippet(content, "ship docs");
+    expect(result).toContain("We need to ship docs before Friday.");
+    expect(result).not.toContain("((ship docs))");
+    expect(result).toContain("Plan for the week:");
+    expect(result).toContain("Then we can relax.");
+  });
+
+  it("extracts snippet from a ((task title)) wikilink in a bullet list", () => {
+    const content = [
+      "- First item",
+      "- Check ((ship docs)) status",
+      "- Last item",
+    ].join("\n");
+
+    const result = extractSnippet(content, "ship docs");
+    expect(result).toContain("- Check ship docs status");
+    expect(result).not.toContain("((ship docs))");
+  });
+
+  it("finds multiple references in one note", () => {
+    const content = [
+      "Line one",
+      "((ship docs))",
+      "Line three",
+      "Line four",
+      "Line five",
+      "((ship docs)) again",
+      "Line seven",
+    ].join("\n");
+
+    const result = extractSnippet(content, "ship docs");
+    const blocks = result.split("\n---\n");
+    expect(blocks).toHaveLength(2);
+    expect(blocks[0]).toContain("ship docs");
+    expect(blocks[1]).toContain("ship docs");
+  });
+
+  it("returns empty string when there is no match", () => {
+    const content = "Just some random text.\nNothing here.";
+    expect(extractSnippet(content, "nonexistent task")).toBe("");
+  });
+
+  it("does not duplicate when a checkbox line also contains a wikilink", () => {
+    const content = [
+      "- [ ] ((ship docs)) @alice",
+      "Next line",
+    ].join("\n");
+
+    const result = extractSnippet(content, "ship docs");
+    const blocks = result.split("\n---\n").filter(Boolean);
+    expect(blocks).toHaveLength(1);
+  });
+
+  it("strips wikilink syntax even when it spans multiple lines in a block", () => {
+    const content = [
+      "Context line",
+      "See ((ship docs)) for details",
+      "More context",
+    ].join("\n");
+
+    const result = extractSnippet(content, "ship docs");
+    expect(result).not.toContain("((ship docs))");
+    expect(result).toContain("See ship docs for details");
+  });
+
+  it("finds checkbox lines that contain [[note refs]] and dates", () => {
+    const content = [
+      "# Meeting notes",
+      "- [ ] review [[Spec]] ((Task)) @bob <file.md> 2026-06-01..2026-06-05",
+      "- [ ] something else",
+    ].join("\n");
+
+    const result = extractSnippet(content, "review");
+    expect(result).toContain(
+      "- [ ] review [[Spec]] ((Task)) @bob <file.md> 2026-06-01..2026-06-05"
+    );
+  });
+
+  it("finds checkbox lines that contain a single date", () => {
+    const content = [
+      "- [ ] ship docs 2026-05-20",
+      "- [ ] other task",
+    ].join("\n");
+
+    const result = extractSnippet(content, "ship docs");
+    expect(result).toContain("- [ ] ship docs 2026-05-20");
+  });
+
+  it("does not collapse whitespace when matching checkbox titles", () => {
+    const content = [
+      "- [ ] ship   docs",
+      "- [ ] other task",
+    ].join("\n");
+
+    const result = extractSnippet(content, "ship   docs");
+    expect(result).toContain("- [ ] ship   docs");
+  });
+});

package/lib/extract-snippet.ts

@@ -0,0 +1,69 @@
+function escapeRegExp(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+const MENTION_RE = /@[\w-]+/g;
+const FILEREF_RE = /<[^>]+>/g;
+const NOTE_REF_RE = /\[\[[^\]]*\]\]/g;
+const TASK_REF_RE = /\(\([^)]*\)\)/g;
+const STATUS_COMMENT_RE = /\s*<!--task::[A-Z_]+-->/g;
+const DATE_RANGE_RE = /\d{4}-\d{2}-\d{2}\.\.\d{4}-\d{2}-\d{2}/g;
+const DATE_RE = /\d{4}-\d{2}-\d{2}/g;
+
+function cleanTaskTitle(text: string): string {
+  return text
+    .replace(NOTE_REF_RE, "")
+    .replace(TASK_REF_RE, "")
+    .replace(MENTION_RE, "")
+    .replace(FILEREF_RE, "")
+    .replace(DATE_RANGE_RE, "")
+    .replace(DATE_RE, "")
+    .replace(STATUS_COMMENT_RE, "")
+    .trim();
+}
+
+export function extractSnippet(content: string, taskTitle: string): string {
+  const lines = content.split("\n");
+  const usedIndices = new Set<number>();
+  const snippets: string[] = [];
+  const wikilinkPattern = `\\(\\(\\s*${escapeRegExp(taskTitle)}\\s*\\)\\)`;
+  const wikilinkRe = new RegExp(wikilinkPattern);
+
+  for (let i = 0; i < lines.length; i++) {
+    if (usedIndices.has(i)) continue;
+
+    let isMatch = false;
+    let isWikilink = false;
+
+    // Pattern 1: checkbox task line
+    const checkboxPrefix = lines[i].match(/^(\s*)-\s+\[([ x])\]\s*/);
+    if (checkboxPrefix) {
+      const textAfterCheckbox = lines[i].slice(checkboxPrefix[0].length);
+      if (cleanTaskTitle(textAfterCheckbox) === taskTitle) {
+        isMatch = true;
+      }
+    }
+
+    // Pattern 2: wikilink reference ((task title))
+    if (!isMatch && lines[i].match(wikilinkRe)) {
+      isMatch = true;
+      isWikilink = true;
+    }
+
+    if (!isMatch) continue;
+    usedIndices.add(i);
+
+    const start = Math.max(0, i - 2);
+    const end = Math.min(lines.length, i + 3);
+    let block = lines.slice(start, end).join("\n");
+
+    if (isWikilink) {
+      // Strip ((...)) syntax so the snippet reads as natural text
+      block = block.replace(new RegExp(wikilinkPattern, "g"), taskTitle);
+    }
+
+    snippets.push(block);
+  }
+
+  return snippets.join("\n---\n");
+}

package/lib/kanban-status.ts

@@ -0,0 +1,55 @@
+import { prisma } from "@/lib/prisma";
+
+export type KanbanStatusConfig = {
+  key: string;
+  label: string;
+  color: string;
+  order: number;
+  isVisible: boolean;
+};
+
+const DEFAULT_STATUSES: KanbanStatusConfig[] = [
+  { key: "OPEN", label: "Open", color: "border-zinc-700", order: 0, isVisible: true },
+  { key: "CLAIMED", label: "Claimed", color: "border-violet-700", order: 1, isVisible: true },
+  { key: "IN_PROGRESS", label: "In Progress", color: "border-blue-700", order: 2, isVisible: true },
+  { key: "REVIEW", label: "Review", color: "border-amber-700", order: 3, isVisible: true },
+  { key: "DONE", label: "Done", color: "border-emerald-700", order: 4, isVisible: true },
+];
+
+export async function getKanbanStatuses(workspaceId: string): Promise<KanbanStatusConfig[]> {
+  const rows = await prisma.kanbanStatus.findMany({
+    where: { workspaceId },
+    orderBy: { order: "asc" },
+  });
+
+  if (rows.length === 0) {
+    return DEFAULT_STATUSES;
+  }
+
+  return rows.map((r) => ({
+    key: r.key,
+    label: r.label,
+    color: r.color,
+    order: r.order,
+    isVisible: r.isVisible,
+  }));
+}
+
+export async function seedDefaultKanbanStatuses(
+  workspaceId: string,
+  tx?: Parameters<Parameters<typeof prisma.$transaction>[0]>[0]
+) {
+  const client = tx ?? prisma;
+  const existing = await client.kanbanStatus.findFirst({
+    where: { workspaceId },
+  });
+  if (existing) return;
+
+  await client.kanbanStatus.createMany({
+    data: DEFAULT_STATUSES.map((s) => ({ ...s, workspaceId })),
+  });
+}
+
+export function getDefaultKanbanStatuses(): KanbanStatusConfig[] {
+  return DEFAULT_STATUSES.map((s) => ({ ...s }));
+}

package/lib/license.ts

@@ -0,0 +1,21 @@
+// Derive Pro / Cloud entitlement from the canonical license fields rather than
+// the denormalized `isPro` / `isCloud` boolean columns. Those booleans are a
+// cache kept in sync by the admin license route and the Stripe webhook, but they
+// drift when `planType` / `licenseType` are edited directly in the DB. The gating
+// paths should treat this derivation as authoritative.
+//
+// Entitlement rule (mirrors prisma/schema.prisma:73-74):
+//   isPro / isCloud  ===  planType != FREE  ||  licenseType == COMPLIMENTARY
+
+type LicenseFields = {
+  planType: string;
+  licenseType: string;
+};
+
+export function isWorkspacePro(ws: LicenseFields): boolean {
+  return ws.planType !== "FREE" || ws.licenseType === "COMPLIMENTARY";
+}
+
+// Today Cloud access has the same derivation as Pro. Kept as a separate export so
+// call sites read clearly and the two can diverge later without a refactor.
+export const isWorkspaceCloud = isWorkspacePro;

package/lib/limits.ts

@@ -0,0 +1,31 @@
+// Shared guard rails for note size. Kept in lib (not a route) so both route
+// handlers and zod validation schemas can import them without a circular dep.
+export const MAX_CONTENT_LEN = 1_000_000; // ~1 MB of markdown
+export const MAX_TITLE_LEN = 500;
+
+// Calendar feed (read-only .ics import) limits.
+export const MAX_CALENDAR_FEEDS = 5;
+export const MAX_FEED_LABEL_LEN = 60;
+export const ICS_FETCH_TIMEOUT_MS = 10_000;
+export const ICS_MAX_BYTES = 2_000_000; // 2 MB
+export const CALENDAR_FEED_PAST_DAYS = 30;
+export const CALENDAR_FEED_FUTURE_DAYS = 180;
+
+/**
+ * Predefined palette for calendar feed colour chips.  Keys are stored in the DB;
+ * values map to Tailwind bg-* classes used in the calendar view.
+ */
+export const FEED_COLORS = {
+  sky:      { bg: "bg-sky-600",      bgLight: "bg-sky-600/20",      border: "border-sky-500/50",      text: "text-sky-300",      label: "Sky" },
+  violet:   { bg: "bg-violet-600",   bgLight: "bg-violet-600/20",   border: "border-violet-500/50",   text: "text-violet-300",   label: "Violet" },
+  emerald:  { bg: "bg-emerald-600",  bgLight: "bg-emerald-600/20",  border: "border-emerald-500/50",  text: "text-emerald-300",  label: "Emerald" },
+  amber:    { bg: "bg-amber-600",    bgLight: "bg-amber-600/20",    border: "border-amber-500/50",    text: "text-amber-300",    label: "Amber" },
+  rose:     { bg: "bg-rose-600",     bgLight: "bg-rose-600/20",     border: "border-rose-500/50",     text: "text-rose-300",     label: "Rose" },
+  cyan:     { bg: "bg-cyan-600",     bgLight: "bg-cyan-600/20",     border: "border-cyan-500/50",     text: "text-cyan-300",     label: "Cyan" },
+  fuchsia:  { bg: "bg-fuchsia-600",  bgLight: "bg-fuchsia-600/20",  border: "border-fuchsia-500/50",  text: "text-fuchsia-300",  label: "Fuchsia" },
+  orange:   { bg: "bg-orange-600",   bgLight: "bg-orange-600/20",   border: "border-orange-500/50",   text: "text-orange-300",   label: "Orange" },
+} as const;
+
+export type FeedColorKey = keyof typeof FEED_COLORS;
+export const FEED_COLOR_KEYS = Object.keys(FEED_COLORS) as FeedColorKey[];
+export const DEFAULT_FEED_COLOR: FeedColorKey = "sky";

package/lib/mcp-auth.test.ts

@@ -0,0 +1,58 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const findUnique = vi.fn();
+
+vi.mock("@/lib/prisma", () => ({
+  prisma: {
+    mcpToken: {
+      findUnique,
+      update: vi.fn().mockResolvedValue(undefined),
+    },
+  },
+}));
+
+vi.mock("jose", () => ({
+  jwtVerify: vi.fn().mockResolvedValue({
+    payload: { userId: "user-1", workspaceId: "ws-1", tokenId: "tok-1" },
+  }),
+  SignJWT: class {},
+}));
+
+describe("verifyMcpToken", () => {
+  beforeEach(() => {
+    findUnique.mockReset();
+  });
+
+  it("rejects a token if the workspace does not match the JWT payload", async () => {
+    findUnique.mockResolvedValue({
+      id: "tok-1",
+      userId: "user-1",
+      workspaceId: "ws-2",
+      revokedAt: null,
+      alias: "Laptop",
+    });
+
+    const { verifyMcpToken } = await import("@/lib/mcp-auth");
+
+    await expect(verifyMcpToken("secret")).resolves.toBeNull();
+  });
+
+  it("accepts a token when the workspace matches the JWT payload", async () => {
+    findUnique.mockResolvedValue({
+      id: "tok-1",
+      userId: "user-1",
+      workspaceId: "ws-1",
+      revokedAt: null,
+      alias: "Laptop",
+    });
+
+    const { verifyMcpToken } = await import("@/lib/mcp-auth");
+
+    await expect(verifyMcpToken("secret")).resolves.toEqual({
+      userId: "user-1",
+      workspaceId: "ws-1",
+      tokenId: "tok-1",
+      alias: "Laptop",
+    });
+  });
+});

package/lib/mcp-auth.ts

@@ -0,0 +1,65 @@
+import { SignJWT, jwtVerify } from "jose";
+import { prisma } from "@/lib/prisma";
+
+// Throttle lastUsed updates to reduce DB row contention (heartbeat calls ~120/min)
+const THROTTLE_MS = 60_000;
+const lastUsedCache = new Map<string, number>();
+
+const MCP_SECRET = new TextEncoder().encode(
+  process.env.MCP_SECRET ?? "dev-mcp-secret-change-in-production"
+);
+
+export type McpTokenPayload = {
+  userId: string;
+  workspaceId: string;
+  tokenId: string;
+};
+
+export async function signMcpToken(payload: McpTokenPayload): Promise<string> {
+  return new SignJWT({ ...payload })
+    .setProtectedHeader({ alg: "HS256" })
+    .setIssuedAt()
+    .setExpirationTime("1y")
+    .sign(MCP_SECRET);
+}
+
+export async function verifyMcpToken(
+  token: string
+): Promise<(McpTokenPayload & { alias: string | null }) | null> {
+  try {
+    const { payload } = await jwtVerify(token, MCP_SECRET);
+    const { userId, workspaceId, tokenId } = payload as McpTokenPayload;
+
+    // Check DB: not revoked, correct IDs
+    const record = await prisma.mcpToken.findUnique({ where: { id: tokenId } });
+    if (
+      !record ||
+      record.revokedAt ||
+      record.userId !== userId ||
+      record.workspaceId !== workspaceId
+    ) {
+      return null;
+    }
+
+    // Touch lastUsed (throttled to reduce DB row contention)
+    const now = Date.now();
+    const lastUpdate = lastUsedCache.get(tokenId) ?? 0;
+    if (now - lastUpdate > THROTTLE_MS) {
+      lastUsedCache.set(tokenId, now);
+      // Fire-and-forget: don't await so it never blocks auth
+      prisma.mcpToken.update({
+        where: { id: tokenId },
+        data: { lastUsed: new Date() },
+      }).catch(() => {});
+    }
+
+    return { userId, workspaceId, tokenId, alias: record.alias };
+  } catch {
+    return null;
+  }
+}
+
+export function extractBearerToken(authHeader: string | null): string | null {
+  if (!authHeader?.startsWith("Bearer ")) return null;
+  return authHeader.slice(7);
+}

package/lib/mcp-contract.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { SERVER_INSTRUCTIONS, TOOLS } from "@/lib/mcp-contract";
+
+describe("MCP contract", () => {
+  it("documents markdown equivalents for editor shortcuts", () => {
+    expect(SERVER_INSTRUCTIONS).toContain("/todo");
+    expect(SERVER_INSTRUCTIONS).toContain("[[Note Title]]");
+    expect(SERVER_INSTRUCTIONS).toContain("((Task Title))");
+    expect(SERVER_INSTRUCTIONS).toContain("!high");
+  });
+
+  it("teaches create_note how to write agent-friendly markdown", () => {
+    const createNote = TOOLS.find((tool) => tool.name === "create_note");
+
+    expect(createNote?.description).toContain("editor shortcuts");
+    expect(JSON.stringify(createNote?.inputSchema)).toContain("- [ ]");
+  });
+
+  it("teaches append_to_note how to append task-aware markdown", () => {
+    const appendToNote = TOOLS.find((tool) => tool.name === "append_to_note");
+
+    expect(appendToNote?.description).toContain("append markdown");
+    expect(JSON.stringify(appendToNote?.inputSchema)).toContain("!high");
+  });
+});

package/lib/mcp-contract.ts

@@ -0,0 +1,210 @@
+type McpToolSchema = {
+  type: "object";
+  properties: Record<string, unknown>;
+  required: string[];
+};
+
+export type McpTool = {
+  name: string;
+  description: string;
+  inputSchema: McpToolSchema;
+};
+
+export const TOOLS: McpTool[] = [
+  {
+    name: "get_notes",
+    description:
+      "List all notes in the workspace. Returns note IDs, titles, and task counts. " +
+      "Use this first to discover what work is tracked. Note IDs are needed for get_note and append_to_note.",
+    inputSchema: { type: "object", properties: {}, required: [] },
+  },
+  {
+    name: "get_tasks",
+    description:
+      "List unclaimed agent tasks (assigned to @agent, status OPEN, not yet claimed). " +
+      "Returns task IDs, titles, source notes, and age. " +
+      "Use this to find work items you can pick up. Always claim a task before starting work on it.",
+    inputSchema: { type: "object", properties: {}, required: [] },
+  },
+  {
+    name: "get_task_detail",
+    description:
+      "Get full details of a specific task including its audit log history. " +
+      "Use this to understand a task's context, past status changes, and who interacted with it.",
+    inputSchema: {
+      type: "object",
+      properties: { taskId: { type: "string", description: "The task ID (from get_tasks or get_notes)" } },
+      required: ["taskId"],
+    },
+  },
+  {
+    name: "get_linked_files",
+    description:
+      "Get file path references linked to a task (e.g. source files the task relates to). " +
+      "Use this to know which files to look at when working on a task.",
+    inputSchema: {
+      type: "object",
+      properties: { taskId: { type: "string", description: "The task ID" } },
+      required: ["taskId"],
+    },
+  },
+  {
+    name: "claim_tasks",
+    description:
+      "Claim one or more agent tasks to reserve them for yourself. " +
+      "You MUST claim a task before working on it — this prevents other agents from picking it up. " +
+      "After claiming, send periodic heartbeats and update the status as you make progress.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ids: { type: "array", items: { type: "string" }, description: "Task IDs to claim (from get_tasks)" },
+      },
+      required: ["ids"],
+    },
+  },
+  {
+    name: "release_task",
+    description:
+      "Release a task you previously claimed back to the open queue. " +
+      "Use this if you cannot complete the task, it's blocked, or it's no longer relevant. " +
+      "Provide a reason so the workspace owner understands why it was released. " +
+      "This notifies the workspace owner.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "The task ID to release" },
+        reason: { type: "string", description: "Why you are releasing it (optional but recommended)" },
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "update_task",
+    description:
+      "Update the status of a task you have claimed. Status flow: in_progress → review → done. " +
+      "Use 'in_progress' when you start working, 'review' when work is complete and awaiting approval, " +
+      "'done' when fully finished (this also auto-checks the task off in the source note). " +
+      "Each update resets the heartbeat timer.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "The task ID" },
+        status: {
+          type: "string",
+          enum: ["in_progress", "review", "done"],
+          description: "New status: in_progress (working), review (awaiting approval), done (completed)",
+        },
+      },
+      required: ["id", "status"],
+    },
+  },
+  {
+    name: "heartbeat",
+    description:
+      "Send a heartbeat to signal you are still actively working on a claimed task. " +
+      "Send heartbeats regularly (e.g. every few minutes) while working on long tasks " +
+      "so the system knows the task hasn't been abandoned.",
+    inputSchema: {
+      type: "object",
+      properties: { id: { type: "string", description: "The task ID" } },
+      required: ["id"],
+    },
+  },
+  {
+    name: "create_note",
+    description:
+      "Create a new note in the workspace with markdown content. Use markdown, not literal editor shortcuts: " +
+      "/todo becomes '- [ ] Task title', + note becomes '[[Note Title]]', + task becomes '((Task Title))', " +
+      "+ mention becomes '@agent' or '@human(name)', and + priority becomes '!high' or another !priority tag. " +
+      "Checkbox task lines automatically create tasks and parse priority and ISO date metadata.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: { type: "string", description: "Note title (e.g. 'Sprint 24 Tasks')" },
+        content: {
+          type: "string",
+          description:
+            "Markdown content using the parser's real syntax. Example task: '- [ ] Ship MCP docs @agent !high " +
+            "2026-06-14..2026-06-20 <app/mcp/route.tsx>'. Use '- [x]' for completed tasks, '[[Note Title]]' " +
+            "for note links, '((Task Title))' for task references, and @human(name) for human-assigned tasks.",
+        },
+      },
+      required: ["title"],
+    },
+  },
+  {
+    name: "get_note",
+    description:
+      "Get a note's full decrypted markdown content along with all its tasks. " +
+      "Use this to read the complete context of a task or to see all work tracked in a note.",
+    inputSchema: {
+      type: "object",
+      properties: { noteId: { type: "string", description: "The note ID (from get_notes)" } },
+      required: ["noteId"],
+    },
+  },
+  {
+    name: "append_to_note",
+    description:
+      "Append markdown content to an existing note. Use append markdown with the same note-writing syntax as create_note: " +
+      "checkbox tasks, note links, task references, mentions, !priority tags, and ISO dates are all supported. " +
+      "New task lines automatically create tasks without overwriting existing content. Cannot be used on locked notes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        noteId: { type: "string", description: "The note ID (from get_notes)" },
+        content: {
+          type: "string",
+          description:
+            "Markdown to append, such as '- [ ] Review release notes @agent !high 2026-06-14 <docs/release.md>' " +
+            "or 'Linked note [[Release Plan]] with task ref ((Review release notes))'.",
+        },
+      },
+      required: ["noteId", "content"],
+    },
+  },
+];
+
+export const SERVER_INSTRUCTIONS = [
+  "You are connected to Knotpad, a task and note management workspace for dev teams.",
+  "",
+  "## Core Concepts",
+  "- **Notes** contain markdown with embedded task checkboxes.",
+  "- **Tasks** are parsed from notes and can be assigned to @agent (AI) or @human.",
+  "- Agent tasks must be **claimed** before working on them to avoid conflicts.",
+  "- Tasks have a lifecycle: OPEN → CLAIMED → IN_PROGRESS → REVIEW → DONE.",
+  "",
+  "## Recommended Agent Workflow",
+  "1. Call `get_notes` to see all notes and identify work areas.",
+  "2. Call `get_tasks` to see unclaimed agent tasks available to you.",
+  "3. Call `get_task_detail` and `get_linked_files` to understand a task's context and related files.",
+  "4. Call `claim_tasks` to reserve the tasks you want to work on.",
+  "5. Call `update_task` with status 'in_progress' when you start.",
+  "6. Send `heartbeat` periodically while working on long tasks.",
+  "7. When work is done, call `update_task` with status 'review' or 'done'.",
+  "8. Use `create_note` or `append_to_note` to document your work or create new task plans.",
+  "",
+  "## Writing Notes Correctly",
+  "- Prefer valid markdown content over UI-specific wording like 'press /todo'.",
+  "- `/todo` in the editor becomes `- [ ] Task title` in note content.",
+  "- `/bullet` in the editor becomes `- item` in note content.",
+  "- `+ note` becomes `[[Note Title]]`.",
+  "- `+ task` becomes `((Task Title))` for referencing an existing task.",
+  "- `+ mention` becomes `@agent` or `@human(name)`.",
+  "- `+ priority` becomes `!critical`, `!high`, `!medium`, or `!low`.",
+  "- Supported date syntax is `YYYY-MM-DD` or `YYYY-MM-DD..YYYY-MM-DD`.",
+  "",
+  "## Task Syntax in Notes",
+  "- Agent task: `- [ ] Fix login bug @agent <src/auth/login.ts> !high 2026-06-14`",
+  "- Completed task: `- [x] Ship MCP docs @agent !high 2026-06-14..2026-06-20 <app/mcp/route.tsx>`",
+  "- Human task: `- [ ] Review design @human(alice)`",
+  "- Note link: `[[Sprint Plan]]`",
+  "- Task reference: `((Fix login bug))` anywhere in note text.",
+  "",
+  "## Important Rules",
+  "- Always claim a task before starting work on it.",
+  "- Send heartbeats every few minutes for long-running tasks.",
+  "- Release tasks you cannot complete, with a reason.",
+  "- Only update status on tasks you have claimed.",
+  "- When marking a task 'done', the source note checkbox is automatically checked.",
+].join("\n");