drafted 1.12.8 → 1.13.0

package/README.md

@@ -0,0 +1,26 @@
+# Drafted
+
+Multi-tenant shared surface for AI-human collaboration. Drafted organizes agent-produced work into **projects** (frames on a zoomable real-time surface), **skills** (reusable operating procedures agents load), and a **wiki** (durable org knowledge) — with MCP tools for agents and a browser UI for humans.
+
+- Product vision and positioning: [PRODUCT.md](PRODUCT.md)
+- Architecture, development, and operations: [AGENTS.md](AGENTS.md)
+- Live: [drafted.live](https://drafted.live)
+
+## OKF-native
+
+Drafted is a native producer and consumer of the **Open Knowledge Format (OKF) v0.1** ([GoogleCloudPlatform/knowledge-catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog)):
+
+- **The org wiki is an OKF v0.1 bundle.** Every page carries conformant YAML frontmatter (required `type`, one-line `description`, `tags`, synthesized `timestamp`; unknown keys preserved). `index.md` at every level is synthesized, `log.md` keeps the date-grouped change history, links resolve with or without `.md`, and broken links are legal. The wiki UI shows a live OKF conformance badge.
+- **Bundle exchange everywhere.** Export/import the wiki (`GET /api/wiki/export.tar.gz`, `POST /api/wiki/import`), the skill library (`skills/<slug>/SKILL.md` layout), and whole projects (`<layer>/<lane>/<file>.md` concepts; markdown links round-trip as connectors) — via HTTP or the MCP `wiki`, `skill`, and `project` tools, with dry-run reports.
+
+## Quick start
+
+```bash
+npm install && npm run dev   # Docker services + schema + server with hot reload
+```
+
+- App: http://localhost:3477
+- Email inbox (magic links): http://localhost:8025
+- MinIO console: http://localhost:9001
+
+Sign in with any email and grab the magic link from Mailpit.

package/cli/drafted.mjs

@@ -1440,6 +1440,18 @@ function synthesizeSkillMd(skill) {
     lines.push('setup:');
     for (const s of setup) lines.push(`  - ${JSON.stringify(s)}`);
   }
+  // OKF v0.1 concept keys — byte-identical to the server authority
+  // (server/lib/skill-hash.mjs synthesizeSkillMd); keep in lockstep so a
+  // locally materialized bundle matches the server-side hash input.
+  lines.push('type: Skill');
+  lines.push(`title: ${JSON.stringify(skill.name || skill.slug || '')}`);
+  const skillTags = Array.isArray(skill.tags) ? skill.tags.filter(Boolean) : [];
+  if (skillTags.length) {
+    lines.push('tags:');
+    for (const t of skillTags) lines.push(`  - ${JSON.stringify(t)}`);
+  }
+  const ts = skill.updatedAt ? new Date(skill.updatedAt) : null;
+  if (ts && !Number.isNaN(ts.getTime())) lines.push(`timestamp: ${JSON.stringify(ts.toISOString())}`);
   lines.push('---', '');
   return lines.join('\n') + (skill.content || '');
 }

package/mcp/server.mjs

@@ -20,6 +20,7 @@ import { registerAppResource, RESOURCE_MIME_TYPE } from '@modelcontextprotocol/e
 import WebSocket from 'ws';
 import { LAYERS } from '../src/shared/constants.mjs';
 import { emptyExcalidrawScene, stringifyExcalidrawScene } from '../src/shared/excalidraw.mjs';
+import { formatOkfLogEntry, appendOkfLogEntry } from '../src/shared/okf-log.mjs';
 import { createGateState, markSearched, g1Block, g2Block, g3Block, selectWithinBudget, wouldExceedBudget, budgetError, formatWikiIndex, PROJECT_CONTEXT_BUDGET_CHARS } from './gates.mjs';
 import { loadPersistedProject, savePersistedProject } from './active-project-store.mjs';
 
@@ -1619,9 +1620,9 @@ tool('whoami', 'Return THIS agent session\'s identity: its server-assigned human
 
 // ── Project management tools (direct HTTP) ────────────────────────
 
-tool('project', 'START HERE for project management. Dispatch by `action`: list (lists all projects across all orgs — always call first), open (bind this agent session to a project; required before reading/writing frames — the org derives from the project), create (new project; org= names where it is born), update (change name/folder/description/layers), move (transfer to another org). There is no org switching: for project-less work (wiki/skills) pass org=... on the call. **Skill gate:** projects with attached skills will REJECT all mutations (write, edit, mv, rm, shape, group, connector, layout, layer, asset upload) until you have loaded each attached skill via skill(action="load"). Skills tell you HOW to do the work — they\'re not optional. Open returns the attached skill list and auto-inlines content for projects with ≤3 skills.', {
-  action: z.enum(['list', 'open', 'create', 'update', 'move']).describe('Operation to perform.'),
-  projectId: z.string().optional().describe('[open|update|move] project ID. Get IDs from action=list.'),
+tool('project', 'START HERE for project management. Dispatch by `action`: list (lists all projects across all orgs — always call first), open (bind this agent session to a project; required before reading/writing frames — the org derives from the project), create (new project; org= names where it is born), update (change name/folder/description/layers), move (transfer to another org), export (the project as an OKF v0.1 bundle — <layer>/<lane>/<file>.md concepts, index.md/log.md synthesized), import (ingest an OKF bundle: concepts become markdown document frames, links between them become connectors; dryRun supported). There is no org switching: for project-less work (wiki/skills) pass org=... on the call. **Skill gate:** projects with attached skills will REJECT all mutations (write, edit, mv, rm, shape, group, connector, layout, layer, asset upload) until you have loaded each attached skill via skill(action="load"). Skills tell you HOW to do the work — they\'re not optional. Open returns the attached skill list and auto-inlines content for projects with ≤3 skills.', {
+  action: z.enum(['list', 'open', 'create', 'update', 'move', 'export', 'import']).describe('Operation to perform.'),
+  projectId: z.string().optional().describe('[open|update|move|export|import] project ID. Get IDs from action=list. For export/import: defaults to the bound project.'),
   name: z.string().optional().describe('[create|update] project name'),
   description: z.string().nullable().optional().describe('[create|update] project description'),
   templateSlug: z.string().optional().describe('[create] template slug (e.g. "web-design", "mobile-app", "landing-page")'),
@@ -1630,6 +1631,16 @@ tool('project', 'START HERE for project management. Dispatch by `action`: list (
   layers: z.array(z.object({}).passthrough()).optional().describe('[update] full layers array replacement. Use ls / to read current layers first.'),
   targetOrgId: z.string().optional().describe('[move] destination organization ID. Get org IDs from action=list (each project has an orgId field) or get_org. Both source and target org must include the current user.'),
   skipBrowser: z.boolean().optional().describe('[open] skip opening/navigating a browser tab (use when the user already has the project open, e.g. from an invite snippet)'),
+  format: z.string().optional().describe('[export] "files" returns {files:[{path,content}]} paginated via limit/offset (compact=true for paths only) instead of writing a local dir (stdio) or returning a download URL (remote).'),
+  limit: z.number().optional().describe('[export] max files per page for format="files" (default 100, max 500)'),
+  offset: z.number().optional().describe('[export] pagination offset for format="files"'),
+  compact: z.boolean().optional().describe('[export] with format="files": return file paths only (no content)'),
+  files: z.array(z.object({
+    path: z.string().describe('Bundle-relative file path, e.g. "research/default/notes.md"'),
+    content: z.string().describe('File content (markdown, optional YAML frontmatter)'),
+  })).optional().describe('[import] OKF bundle files inline. index.md/log.md are skipped (synthesized). Caps: 500 files, 512KB/file, 5MB total.'),
+  dryRun: z.boolean().optional().describe('[import] preview the {creates, updates, skips, warnings} report without writing'),
+  ...(isRemote ? {} : { dir: z.string().optional().describe('[export|import] local directory. export: write the bundle files here (default ./okf-project-<slug>). import: recursively read .md files from here (alternative to files[]).') }),
 }, async (args) => {
   try {
     const { action } = args;
@@ -1774,6 +1785,80 @@ tool('project', 'START HERE for project management. Dispatch by `action`: list (
         if (!projectId || !targetOrgId) throw new Error('projectId and targetOrgId required for action=move');
         return ok(await api('POST', `/api/project/${projectId}/move`, { targetOrgId }));
       }
+
+      // ── export ──────────────────────────────────────────────────
+      // The project as an OKF v0.1 bundle. Mirrors wiki export: format="files"
+      // pages the bundle inline; otherwise stdio writes a local dir, remote
+      // returns the authenticated tar.gz download URL.
+      case 'export': {
+        const projectId = args.projectId || getState().projectId;
+        if (!projectId) throw new Error('projectId required for action=export (or open a project first)');
+        if (args.format === 'files') {
+          const qp = new URLSearchParams({ limit: String(Math.min(Math.max(1, args.limit || 100), 500)) });
+          if (args.offset) qp.set('offset', String(args.offset));
+          if (args.compact) qp.set('compact', 'true');
+          return ok(await api('GET', `/api/projects/${projectId}/export?${qp.toString()}`));
+        }
+        if (isRemote) {
+          return ok({
+            downloadUrl: `${getServerUrl()}/api/projects/${projectId}/export.tar.gz`,
+            note: 'Open the URL in a signed-in browser to download the OKF v0.1 project bundle, or call export with format="files" to page the bundle contents inline.',
+          });
+        }
+        // stdio: write every bundle file under a local directory.
+        const meta = getCurrentProjectContext();
+        const projSlug = String((meta && meta.id === projectId && (meta.slug || meta.name)) || projectId)
+          .toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'project';
+        const exportDir = resolve(args.dir || `./okf-project-${projSlug}`);
+        let expOffset = 0;
+        let written = 0;
+        for (;;) {
+          const batch = await api('GET', `/api/projects/${projectId}/export?limit=200&offset=${expOffset}`);
+          const batchFiles = batch.files || [];
+          for (const f of batchFiles) {
+            const dest = resolve(exportDir, f.path);
+            if (dest !== exportDir && !dest.startsWith(exportDir + '/') && !dest.startsWith(exportDir + '\\')) continue; // traversal guard
+            mkdirSync(dirname(dest), { recursive: true });
+            writeFileSync(dest, f.content, 'utf8');
+            written++;
+          }
+          expOffset += batchFiles.length;
+          if (!batch.truncated || batchFiles.length === 0) break;
+        }
+        return ok({ exported: written, dir: exportDir, note: 'OKF v0.1 project bundle written (<layer>/<lane>/<file>.md concepts; index.md and log.md are synthesized).' });
+      }
+
+      // ── import ──────────────────────────────────────────────────
+      // Ingest an OKF bundle into the project: inline files[] or (stdio) a
+      // local dir walked for .md files. Concepts become markdown document
+      // frames; markdown links between them become connectors.
+      case 'import': {
+        const projectId = args.projectId || getState().projectId;
+        if (!projectId) throw new Error('projectId required for action=import (or open a project first)');
+        let importFiles = args.files;
+        if (!importFiles && args.dir) {
+          const root = resolve(args.dir);
+          if (!existsSync(root)) throw new Error(`dir not found: ${args.dir}`);
+          importFiles = [];
+          const walk = (d) => {
+            for (const ent of readdirSync(d, { withFileTypes: true })) {
+              if (ent.name.startsWith('.')) continue;
+              const p = join(d, ent.name);
+              if (ent.isDirectory()) walk(p);
+              else if (/\.md$/i.test(ent.name)) {
+                if (importFiles.length >= 500) throw new Error('import capped at 500 files — split the bundle');
+                importFiles.push({ path: p.slice(root.length + 1).replace(/\\/g, '/'), content: readFileSync(p, 'utf8') });
+              }
+            }
+          };
+          walk(root);
+        }
+        if (!Array.isArray(importFiles) || importFiles.length === 0) {
+          throw new Error('import requires files[] (or dir on stdio) with at least one .md file');
+        }
+        return ok(await api('POST', `/api/projects/${projectId}/import`, { files: importFiles, dryRun: !!args.dryRun }));
+      }
+
       default:
         throw new Error(`Unknown project action: ${action}`);
     }
@@ -3113,7 +3198,7 @@ function ensureSkillInstallIgnored(dir) {
   } catch { return false; }
 }
 
-tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/guidelines agents can load and follow. When you build a reusable skill, author it HERE — add for prose, push to ingest a local source tree — so its method and setup: recipe live in Drafted and any machine or agent can reuse it; keep only machine-specific build output local in .skillinstall/ (always stripped on push). Dispatch by `action`: search/load/list for discovery; history for a skill\'s version git-log; add/update/remove for org skills; fork/push for source-only skills; attach/detach for project binding; favorite/unfavorite for personal pins; read_file/update_file for supporting files inside a skill directory.', {
+tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/guidelines agents can load and follow. When you build a reusable skill, author it HERE — add for prose, push to ingest a local source tree — so its method and setup: recipe live in Drafted and any machine or agent can reuse it; keep only machine-specific build output local in .skillinstall/ (always stripped on push). Dispatch by `action`: search/load/list for discovery; history for a skill\'s version git-log; add/update/remove for org skills; fork/push for source-only skills; attach/detach for project binding; favorite/unfavorite for personal pins; read_file/update_file for supporting files inside a skill directory; export/import to exchange the library as an OKF v0.1 bundle (skills/<slug>/SKILL.md layout).', {
   action: z.enum([
     'search', 'load', 'list', 'history',
     'add', 'update', 'remove',
@@ -3121,12 +3206,13 @@ tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/gui
     'attach', 'detach',
     'favorite', 'unfavorite',
     'read_file', 'update_file',
-  ]).describe('Operation to perform.'),
+    'export', 'import',
+  ]).describe('Operation to perform. export: the skill library as an OKF v0.1 bundle (local dir on stdio, download URL on remote, or format="files" for paged inline files). import: ingest the SKILL.md-shaped concepts of an OKF bundle as org skills (files[] or local dir; dryRun supported).'),
   query: z.string().optional().describe('[search] term to match against name/description/content'),
   tags: z.array(z.string()).optional().describe('[search] filter by tags; [add|update] tag list'),
   scope: z.enum(['all', 'org', 'global']).optional().describe('[search|list] library scope (default: all for search; when provided to list, lists the library instead of project/org attachments)'),
-  limit: z.number().optional().describe('[search|list] max results per page (default 25, max 100)'),
-  compact: z.boolean().optional().describe('[search|list] return only {slug,name,tags} per skill instead of full summaries — for browsing large catalogs within token budget'),
+  limit: z.number().optional().describe('[search|list] max results per page (default 25, max 100); [export] files per page for format="files" (default 100, max 500)'),
+  compact: z.boolean().optional().describe('[search|list] return only {slug,name,tags} per skill instead of full summaries — for browsing large catalogs within token budget; [export] with format="files": file paths only (no content)'),
   skill: z.string().optional().describe('[load|history] skill ID (UUID) or slug'),
   version: z.number().optional().describe('[history] fetch this version number\'s full snapshot (content included); omit for the reverse-chron version list'),
   skillId: z.string().optional().describe('[update|remove|attach|detach|favorite|unfavorite|read_file|update_file] skill ID'),
@@ -3136,13 +3222,16 @@ tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/gui
   content: z.string().optional().describe('[add|update] root SKILL.md content; [update_file] file content'),
   triggerPatterns: z.array(z.string()).optional().describe('[add|update] patterns that suggest this skill'),
   path: z.string().optional().describe('[read_file|update_file] relative path inside skill directory (e.g. "examples/react.md")'),
-  offset: z.number().optional().describe('[search|list] skip N results for pagination; [read_file] start reading at this byte offset (default 0) — for large files (e.g. a >90KB app-frame bundle) read in chunks using the returned nextOffset until truncated=false'),
+  offset: z.number().optional().describe('[search|list|export] skip N results for pagination; [read_file] start reading at this byte offset (default 0) — for large files (e.g. a >90KB app-frame bundle) read in chunks using the returned nextOffset until truncated=false'),
   maxBytes: z.number().optional().describe('[read_file] return at most this many bytes from offset (default: whole remaining file). Response reports totalSize/offset/truncated/nextOffset.'),
-  org: z.string().optional().describe('[add] org (id or name) the skill is born in — defaults to the open project\'s org; [list|search|load] scope to this org; [fork|push|update] resolve/fork into this org. Per-request only — nothing is switched.'),
+  org: z.string().optional().describe('[add] org (id or name) the skill is born in — defaults to the open project\'s org; [list|search|load] scope to this org; [fork|push|update|export|import] resolve/fork into this org. Per-request only — nothing is switched.'),
   setup: z.array(z.string()).optional().describe('[add|update] setup command(s) (in order) run on materialize to build a source-only skill, e.g. ["npm ci","npm run build"]'),
-  files: z.array(z.object({ path: z.string(), content: z.string() })).optional().describe('[push] source files to push (path + UTF-8 content); server strips artifacts + enforces caps'),
-  dir: z.string().optional().describe('[push] local directory to push instead of files[]; walked locally (heavy dirs, .skillinstall/, and .skillignore pre-filtered), server re-enforces. On push the dir\'s .gitignore is auto-updated to exclude .skillinstall/ (the rebuildable bundle).'),
+  files: z.array(z.object({ path: z.string(), content: z.string() })).optional().describe('[push] source files to push (path + UTF-8 content); server strips artifacts + enforces caps. [import] OKF bundle files inline — skills/<slug>/SKILL.md dirs and Skill/Playbook/SOP/Procedure-typed .md with name + description frontmatter become org skills. Caps: 500 files, 512KB/file, 5MB total.'),
+  dir: z.string().optional().describe('[push|export|import] local directory. push: source tree to push instead of files[]; walked locally (heavy dirs, .skillinstall/, and .skillignore pre-filtered), server re-enforces; the dir\'s .gitignore is auto-updated to exclude .skillinstall/ (the rebuildable bundle). export: write the OKF bundle files here (default ./okf-skills-<org>). import: read the bundle from here (alternative to files[]).'),
   deleteMissing: z.boolean().optional().describe('[push] remove stored files not present in the pushed set'),
+  format: z.string().optional().describe('[export] "files" returns {files:[{path,content}]} paginated via limit/offset (compact=true for paths only) instead of writing a local dir (stdio) or returning a download URL (remote).'),
+  includeGlobal: z.boolean().optional().describe('[export] include global built-in skills in the bundle (default: org skills only)'),
+  dryRun: z.boolean().optional().describe('[import] report {created, updated, skips, warnings} without writing'),
 }, async (args) => {
   try {
     const { action } = args;
@@ -3150,7 +3239,7 @@ tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/gui
     // bound org (or explicit org=) when the user is multi-org. (DRAFT-36 Phase 4.)
     // UUID-first exception: update/remove addressed by a skillId derive their org
     // from the skill row server-side, so the bound-org gate is unnecessary.
-    if (['add', 'update', 'remove', 'push', 'fork'].includes(action)) {
+    if (['add', 'update', 'remove', 'push', 'fork', 'import'].includes(action)) {
       const byId = (action === 'update' || action === 'remove') && /^[a-f0-9-]{36}$/.test(args.skillId || '');
       if (!byId) await requireBoundOrgForProjectlessMutation(args.org);
     }
@@ -3349,6 +3438,64 @@ tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/gui
         if (!skillId || !path || content == null) throw new Error('skillId, path, content required for action=update_file');
         return ok(await api('PUT', `/api/skills/${skillId}/files/${path}`, { content }));
       }
+
+      // ── export ──────────────────────────────────────────────────
+      // The skill library as an OKF v0.1 bundle (skills/<slug>/SKILL.md +
+      // supporting files + synthesized log.md/index.md). Mirrors wiki export:
+      // format="files" pages the bundle inline; otherwise stdio writes a local
+      // dir, remote returns the authenticated tar.gz download URL.
+      case 'export': {
+        const extra = args.org ? { 'X-Drafted-Org': args.org } : {};
+        const inc = args.includeGlobal ? '&includeGlobal=1' : '';
+        if (args.format === 'files') {
+          const qp = new URLSearchParams({ limit: String(Math.min(Math.max(1, args.limit || 100), 500)) });
+          if (args.offset) qp.set('offset', String(args.offset));
+          if (args.compact) qp.set('compact', 'true');
+          return ok(await api('GET', `/api/skills/export?${qp.toString()}${inc}`, undefined, extra));
+        }
+        if (isRemote) {
+          return ok({
+            downloadUrl: `${getServerUrl()}/api/skills/export.tar.gz${args.includeGlobal ? '?includeGlobal=1' : ''}`,
+            note: 'Open the URL in a signed-in browser to download the OKF v0.1 skill bundle, or call export with format="files" to page the bundle contents inline.',
+          });
+        }
+        // stdio: write every bundle file under a local directory.
+        const skOrgCtx = await getCurrentOrgContext();
+        const skOrgSlug = String(skOrgCtx?.name || skOrgCtx?.id || 'org').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'org';
+        const exportDir = resolve(args.dir || `./okf-skills-${skOrgSlug}`);
+        let expOffset = 0;
+        let written = 0;
+        for (;;) {
+          const batch = await api('GET', `/api/skills/export?limit=200&offset=${expOffset}${inc}`, undefined, extra);
+          const batchFiles = batch.files || [];
+          for (const f of batchFiles) {
+            const dest = resolve(exportDir, f.path);
+            if (dest !== exportDir && !dest.startsWith(exportDir + '/') && !dest.startsWith(exportDir + '\\')) continue; // traversal guard
+            mkdirSync(dirname(dest), { recursive: true });
+            writeFileSync(dest, f.content, 'utf8');
+            written++;
+          }
+          expOffset += batchFiles.length;
+          if (!batch.truncated || batchFiles.length === 0) break;
+        }
+        return ok({ exported: written, dir: exportDir, note: 'OKF v0.1 skill bundle written (skills/<slug>/SKILL.md layout; index.md and log.md are synthesized).' });
+      }
+
+      // ── import ──────────────────────────────────────────────────
+      // Ingest the SKILL.md-shaped concepts of an OKF bundle as org skills:
+      // inline files[] or (stdio) a local dir walked with the push filters.
+      // Use wiki(action="import") for a mixed knowledge bundle — it routes
+      // skill concepts here and everything else into the wiki.
+      case 'import': {
+        const extra = args.org ? { 'X-Drafted-Org': args.org } : {};
+        let importFiles = args.files;
+        if (!importFiles && args.dir) importFiles = collectSkillTreeForPush(args.dir);
+        if (!Array.isArray(importFiles) || importFiles.length === 0) {
+          throw new Error('import requires files[] (or dir on stdio) with at least one file');
+        }
+        return ok(await api('POST', '/api/skills/import', { files: importFiles, dryRun: !!args.dryRun }, extra));
+      }
+
       default:
         throw new Error(`Unknown skill action: ${action}`);
     }
@@ -3359,20 +3506,32 @@ tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/gui
 // All 11 actions dispatch from one tool. Read-only actions skip the
 // skill gate; mutations require org-level wiki-maintainer skills loaded.
 
-tool('wiki', 'Per-org wiki. Markdown pages with paths as hierarchy. You and other agents/humans share maintenance — every edit broadcasts live, and edits from others appear in `recent` and on `read`.\n\n**Addressing:** a `pageId` (UUID) self-derives its org — no org arg needed. Path-based and listing actions scope to the open project\'s org by default; pass `org=...` to target another org (there is no org switching). `search` spans ALL your orgs by default — don\'t assume "no hits" means the content doesn\'t exist.\n\nBefore mutating: check `recent` and `search` for relevant existing pages. Before mv/rm: check `links` (or pass `dryRun=true`). After completing a logical session of work, append a `log` entry.\n\nThe tool handles bookkeeping you\'d otherwise forget: `mv` rewrites inbound references via the link index, `read` shows who edited last and when. Use `health` to find unlinked pages and broken links.\n\n**Skill gate:** the org may attach a `wiki-maintainer` skill that you MUST load before mutations. If you get a skill-gate error, run skill(action="load", skill="wiki-maintainer") then retry.', {
-  action: z.enum(['ls', 'recent', 'read', 'search', 'links', 'log', 'health', 'write', 'edit', 'mv', 'rm', 'source-register', 'source-list', 'source-get', 'bulk-write']).describe('Operation to perform.'),
-  path: z.string().optional().describe('[ls|read|links] wiki path. For ls: default / (root). For read: required. For links: required.'),
+tool('wiki', 'Per-org wiki. Markdown pages with paths as hierarchy. You and other agents/humans share maintenance — every edit broadcasts live, and edits from others appear in `recent` and on `read`.\n\n**Addressing:** a `pageId` (UUID) self-derives its org — no org arg needed. Path-based and listing actions scope to the open project\'s org by default; pass `org=...` to target another org (there is no org switching). `search` spans ALL your orgs by default — don\'t assume "no hits" means the content doesn\'t exist.\n\nBefore mutating: check `recent` and `search` for relevant existing pages. Before mv/rm: check `links` (or pass `dryRun=true`). After completing a logical session of work, append a `log` entry. Reference sources with `cite` (appends a numbered entry to the page\'s `# Citations` section).\n\nThe wiki is an OKF v0.1 bundle (Open Knowledge Format): every page carries frontmatter with a `type` (default "Page"), a one-line `description` is recommended, links may use `/a/b.md` or extensionless `a/b` form, and `index.md` at any level is synthesized — read it for a directory listing, never write it. Exchange whole bundles with `export` (conformant tar.gz / local dir / paged files) and `import` (files[] or local dir, dryRun supported).\n\nThe tool handles bookkeeping you\'d otherwise forget: `mv` rewrites inbound references via the link index, `read` shows who edited last and when. Use `health` to find unlinked pages and broken links.\n\n**Skill gate:** the org may attach a `wiki-maintainer` skill that you MUST load before mutations. If you get a skill-gate error, run skill(action="load", skill="wiki-maintainer") then retry.', {
+  action: z.enum(['ls', 'recent', 'read', 'search', 'links', 'log', 'health', 'write', 'edit', 'mv', 'rm', 'cite', 'source-register', 'source-list', 'source-get', 'bulk-write', 'export', 'import']).describe('Operation to perform. export: the whole wiki as an OKF v0.1 bundle (local dir on stdio, download URL on remote, or format="files" for paged inline files). import: ingest an OKF bundle (files[] or local dir; dryRun supported).'),
+  path: z.string().optional().describe('[ls|read|links|cite] wiki path. For ls: default / (root). For read: required. For links/cite: required unless pageId given. Reading `index.md` (any level) returns the SYNTHESIZED OKF directory listing.'),
   pageId: z.string().optional().describe('[read|edit|mv|rm|links] page UUID (from read/search). UUID-first: addresses the page directly, org auto-derives — no org needed and no path lookup. Preferred over path for an existing page.'),
   org: z.string().optional().describe('Org slug or id to scope this call to (per-request only — nothing is switched). [write] the org the page is created in — required when you belong to several orgs and no project is open. [search] restrict to this org (default: ALL your orgs). [ls|recent|read|links|log|health|edit|mv|rm|bulk-write] target this org\'s wiki instead of the open project\'s org. Ignored when a pageId is given (the page self-derives its org).'),
   recursive: z.boolean().optional().describe('[ls] list recursively with depth indicators'),
-  limit: z.number().optional().describe('[recent|search] max results (recent default 10, search default 25)'),
+  limit: z.number().optional().describe('[recent|search|export] max results (recent default 10, search default 25, export files default 100)'),
+  offset: z.number().optional().describe('[export] pagination offset for format="files"'),
+  compact: z.boolean().optional().describe('[export] with format="files": return file paths only (no content)'),
+  format: z.string().optional().describe('[export] "files" returns {files:[{path,content}]} paginated via limit/offset (compact=true for paths only) instead of writing a local dir (stdio) or returning a download URL (remote).'),
+  files: z.array(z.object({
+    path: z.string().describe('Bundle-relative file path, e.g. "concepts/frames.md"'),
+    content: z.string().describe('File content (markdown, optional YAML frontmatter)'),
+  })).optional().describe('[import] OKF bundle files inline. index.md files are skipped (synthesized), bundle-root log.md merges into the wiki log page. Caps: 500 files, 512KB/file, 5MB total.'),
+  ...(isRemote ? {} : { dir: z.string().optional().describe('[export|import] local directory. export: write the bundle files here (default ./okf-export-<org>). import: recursively read .md files from here (alternative to files[]).') }),
   query: z.string().optional().describe('[search] term to search in title, path, and content'),
   lines: z.string().optional().describe('[read] line range (e.g. "1-50"). Omit to read all.'),
-  message: z.string().optional().describe('[log] message to append to log.md page'),
+  message: z.string().optional().describe('[log] message to append to the log page (OKF date-grouped format)'),
+  verb: z.string().optional().describe('[log] leading bold verb for the entry: Update (default), Creation, Deprecation, or Initialization.'),
   title: z.string().optional().describe('[write] page title (required for write)'),
   content: z.string().optional().describe('[write|edit] page content (write: full content; edit: hashline content not used — use operations)'),
-  type: z.string().optional().describe('[write] page type (default "page")'),
-  frontmatter: z.any().optional().describe('[write] frontmatter object'),
+  type: z.string().optional().describe('[write] OKF concept type — free-form string, e.g. "Page", "Reference", "Playbook", "Decision", "Metric". Defaults to "Page" on create; must stay non-empty on update (OKF v0.1 requires a type on every page).'),
+  raw: z.boolean().optional().describe('[read] return content bytes-as-stored (skip the synthesized OKF frontmatter block). Do NOT build edit operations from a raw read — hashline anchors for edit must come from a normal (non-raw) read.'),
+  url: z.string().optional().describe('[cite] citation URL (required for cite)'),
+  label: z.string().optional().describe('[cite] link label for the citation (defaults to the URL)'),
+  frontmatter: z.any().optional().describe('[write] frontmatter object. Recommended OKF keys: a one-line "description" (index listings and consumers read it), "tags" (list), "resource" (canonical URI of the underlying asset). Unknown keys are preserved; never set "timestamp" (synthesized from the last update).'),
   operations: z.array(z.object({
     type: z.enum(['replace', 'delete', 'insertAfter', 'insertBefore']).describe('Edit type'),
     lineHash: z.string().describe('The full line anchor copied verbatim from read output — line number + 3-char hash, e.g. "182vix" (the token left of the "|"). NOT the bare hash.'),
@@ -3380,10 +3539,10 @@ tool('wiki', 'Per-org wiki. Markdown pages with paths as hierarchy. You and othe
   })).optional().describe('[edit] hashline edit operations — same shape as frame.edit'),
   from: z.string().optional().describe('[mv] source path'),
   to: z.string().optional().describe('[mv] destination path'),
-  dryRun: z.boolean().optional().describe('[mv|rm] preview impact without applying changes'),
+  dryRun: z.boolean().optional().describe('[mv|rm|import] preview impact without applying changes (import: returns the {creates, updates, skips, warnings} report without writing)'),
   file_path: z.string().optional().describe('[source-register] absolute path to a local file. Server hashes it and registers the source. stdio MCP only.'),
-  contentHash: z.string().optional().describe('[source-register|source-list] hex-encoded SHA-256 (64 chars). Use when the client already hashed the bytes (HTTP MCP).'),
-  filename: z.string().optional().describe('[source-register] original filename for the source (informational)'),
+  contentHash: z.string().optional().describe('[source-register|source-list|cite] hex-encoded SHA-256 (64 chars). Use when the client already hashed the bytes (HTTP MCP). For cite: also registers the cited source.'),
+  filename: z.string().optional().describe('[source-register|cite] original filename for the source (informational)'),
   contentType: z.string().optional().describe('[source-register] MIME type (informational)'),
   size: z.number().optional().describe('[source-register] byte size (informational)'),
   sourceId: z.string().optional().describe('[source-get] source ID returned from source-register'),
@@ -3398,7 +3557,7 @@ tool('wiki', 'Per-org wiki. Markdown pages with paths as hierarchy. You and othe
     // Otherwise (path-addressed, multi-org, nothing bound) the gate still
     // refuses to guess the org so a write never silently lands in the wrong one.
     const orgHeader = args.org ? { 'X-Drafted-Org': args.org } : {};
-    if (['write', 'edit', 'mv', 'rm', 'bulk-write'].includes(action)) {
+    if (['write', 'edit', 'mv', 'rm', 'bulk-write', 'cite', 'import'].includes(action)) {
       if (!args.pageId) await requireBoundOrgForProjectlessMutation(args.org);
     }
 
@@ -3427,7 +3586,7 @@ tool('wiki', 'Per-org wiki. Markdown pages with paths as hierarchy. You and othe
     // Ensure the wiki-maintainer skill is attached to this org BEFORE the
     // gate check, so the gate fires reliably on the very first wiki call —
     // not just after the org has visited /wiki in a browser. Idempotent.
-    const MUTATING = new Set(['write', 'edit', 'mv', 'rm', 'log', 'source-register', 'bulk-write']);
+    const MUTATING = new Set(['write', 'edit', 'mv', 'rm', 'log', 'cite', 'source-register', 'bulk-write', 'import']);
     if (MUTATING.has(action)) {
       try { await api('POST', '/api/wiki/_ensure-skill'); } catch { /* non-fatal */ }
       const skillErr = await checkOrgSkills(orgId, action);
@@ -3510,19 +3669,21 @@ tool('wiki', 'Per-org wiki. Markdown pages with paths as hierarchy. You and othe
       // Returns content in hashline format (`LINE+ID|content`) so the
       // agent can produce hashline edit operations. Mirrors frame.read.
       case 'read': {
-        const { path: readPath, pageId: readPageId, lines: readLines } = args;
+        const { path: readPath, pageId: readPageId, lines: readLines, raw: readRaw } = args;
         if (readLines && !/^\d+-\d+$/.test(readLines)) throw new Error(`lines must be "N-M" (e.g. "10-50"), got: ${readLines}`);
         let page;
         if (readPageId) {
           // UUID-first: address the page directly, org auto-derives server-side.
           const params = new URLSearchParams({ format: 'hashline' });
           if (readLines) params.set('lines', readLines);
+          if (readRaw) params.set('raw', 'true');
           page = await api('GET', `/api/wiki/pages/${readPageId}?${params.toString()}`);
         } else {
           if (!readPath) throw new Error('path or pageId required for action=read');
           const normalized = normalizeWikiPath(readPath);
           const params = new URLSearchParams({ path: normalized, format: 'hashline' });
           if (readLines) params.set('lines', readLines);
+          if (readRaw) params.set('raw', 'true');
           page = await api('GET', `/api/wiki/page?${params.toString()}`, undefined, orgHeader);
         }
         // Get backlink count via search (approximate)
@@ -3582,41 +3743,156 @@ tool('wiki', 'Per-org wiki. Markdown pages with paths as hierarchy. You and othe
       }
 
       // ── log ─────────────────────────────────────────────────────
+      // OKF log.md format: newest-first `## YYYY-MM-DD` date headings (UTC),
+      // each with `* **Verb**: message (agent, HH:MM UTC)` bullets. Legacy
+      // `## <ISO datetime> ...` headings on existing log pages are left as-is.
       case 'log': {
-        const { message: logMessage } = args;
+        const { message: logMessage, verb: logVerb } = args;
         if (!logMessage) throw new Error('message required for action=log');
         const agentName = process.env.DRAFTED_AGENT_NAME || 'mcp';
-        const dateStr = new Date().toISOString().replace('T', ' ').slice(0, 19) + 'Z';
-        const entry = `## ${dateStr} note by ${agentName} | ${logMessage}`;
+        const now = new Date();
+        const entry = formatOkfLogEntry(logVerb, logMessage, agentName, now);
+        const logTitle = (orgCtx?.name ? orgCtx.name + ' ' : '') + 'Log';
 
-        // Try to read existing log page
-        let existingContent = '';
-        let existingId = null;
+        // Try to read existing log page (raw: bytes-as-stored, no synthesis)
+        let logPage = null;
         try {
-          const logPage = await api('GET', '/api/wiki/page?path=log', undefined, orgHeader);
-          existingContent = logPage.content || '';
-          existingId = logPage.id;
+          logPage = await api('GET', '/api/wiki/page?path=log&raw=true', undefined, orgHeader);
         } catch {
           // Create new log page
           const created = await api('POST', '/api/wiki/pages', {
             path: 'log',
             title: 'Log',
-            content: entry + '\n',
+            type: 'Log',
+            content: appendOkfLogEntry('', entry, now, logTitle),
           }, orgHeader);
           return ok(withOrg({ appended: true, created: true, pageId: created.id, path: 'log', url: wikiBrowserUrl('log') }));
         }
 
-        // Append to existing log
-        const updatedContent = (existingContent.endsWith('\n') ? existingContent : existingContent + '\n') + entry + '\n';
-        await api('PATCH', `/api/wiki/pages/${existingId}`, { content: updatedContent });
+        // Append under today's date heading (created at the top if missing)
+        const updatedContent = appendOkfLogEntry(logPage.content || '', entry, now, logTitle);
+        await api('PATCH', `/api/wiki/pages/${logPage.id}`, { content: updatedContent }, orgHeader);
         return ok(withOrg({ appended: true, path: 'log', url: wikiBrowserUrl('log') }));
       }
 
+      // ── cite ────────────────────────────────────────────────────
+      // Append a numbered citation to a page's `# Citations` section
+      // (creating the section if missing), OKF style: `[n] [label](url)`.
+      // Optionally registers a wiki source when contentHash is given.
+      case 'cite': {
+        const { path: citePath, pageId: citePageId, url: citeUrl, label: citeLabel, contentHash: citeHash, filename: citeFilename } = args;
+        if (!citeUrl) throw new Error('url required for action=cite');
+        let page;
+        if (citePageId) {
+          page = await api('GET', `/api/wiki/pages/${citePageId}?raw=true`);
+        } else {
+          if (!citePath) throw new Error('path or pageId required for action=cite');
+          page = await api('GET', `/api/wiki/page?path=${encodeURIComponent(normalizeWikiPath(citePath))}&raw=true`, undefined, orgHeader);
+        }
+        const lines = (page.content || '').split('\n');
+        let maxN = 0;
+        for (const l of lines) {
+          const m = l.match(/^\[(\d+)\]\s/);
+          if (m) maxN = Math.max(maxN, parseInt(m[1], 10));
+        }
+        const n = maxN + 1;
+        const entry = `[${n}] [${citeLabel || citeUrl}](${citeUrl})`;
+        let content;
+        const hIdx = lines.findIndex((l) => /^#{1,3}\s+Citations\s*$/.test(l));
+        if (hIdx < 0) {
+          const base = (page.content || '').replace(/\s+$/, '');
+          content = (base ? base + '\n\n' : '') + '# Citations\n\n' + entry + '\n';
+        } else {
+          let end = hIdx + 1;
+          while (end < lines.length && !/^#{1,6}\s/.test(lines[end])) end++;
+          let insertAt = end;
+          while (insertAt > hIdx + 1 && lines[insertAt - 1].trim() === '') insertAt--;
+          lines.splice(insertAt, 0, entry);
+          content = lines.join('\n');
+        }
+        await api('PATCH', `/api/wiki/pages/${page.id}`, { content });
+        let source = null;
+        if (citeHash) {
+          try {
+            source = await api('POST', '/api/wiki/sources', { contentHash: citeHash, filename: citeFilename }, orgHeader);
+          } catch { /* source registration is best-effort */ }
+        }
+        return ok(withOrg({ cited: true, n, entry, path: page.path, id: page.id, sourceId: source?.id, url: wikiBrowserUrl(page.path) }));
+      }
+
       // ── health ──────────────────────────────────────────────────
       case 'health': {
         return ok(await api('GET', '/api/wiki/health', undefined, orgHeader));
       }
 
+      // ── export ──────────────────────────────────────────────────
+      // The whole wiki as an OKF v0.1 bundle. format="files" pages the bundle
+      // inline; otherwise stdio writes a local dir, remote returns the
+      // authenticated tar.gz download URL.
+      case 'export': {
+        if (args.format === 'files') {
+          const qp = new URLSearchParams({ limit: String(Math.min(Math.max(1, args.limit || 100), 500)) });
+          if (args.offset) qp.set('offset', String(args.offset));
+          if (args.compact) qp.set('compact', 'true');
+          return ok(withOrg(await api('GET', `/api/wiki/export?${qp.toString()}`, undefined, orgHeader)));
+        }
+        if (isRemote) {
+          return ok(withOrg({
+            downloadUrl: `${getServerUrl()}/api/wiki/export.tar.gz`,
+            note: 'Open the URL in a signed-in browser to download the OKF v0.1 bundle, or call export with format="files" to page the bundle contents inline.',
+          }));
+        }
+        // stdio: write every bundle file under a local directory.
+        const orgSlug = String(orgCtx?.name || orgId || 'org').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'org';
+        const exportDir = resolve(args.dir || `./okf-export-${orgSlug}`);
+        let expOffset = 0;
+        let written = 0;
+        for (;;) {
+          const batch = await api('GET', `/api/wiki/export?limit=200&offset=${expOffset}`, undefined, orgHeader);
+          const batchFiles = batch.files || [];
+          for (const f of batchFiles) {
+            const dest = resolve(exportDir, f.path);
+            if (dest !== exportDir && !dest.startsWith(exportDir + '/') && !dest.startsWith(exportDir + '\\')) continue; // traversal guard
+            mkdirSync(dirname(dest), { recursive: true });
+            writeFileSync(dest, f.content, 'utf8');
+            written++;
+          }
+          expOffset += batchFiles.length;
+          if (!batch.truncated || batchFiles.length === 0) break;
+        }
+        return ok(withOrg({ exported: written, dir: exportDir, note: 'OKF v0.1 bundle written. Pages carry synthesized frontmatter; index.md files are synthesized directory listings.' }));
+      }
+
+      // ── import ──────────────────────────────────────────────────
+      // Ingest an OKF bundle: inline files[] or (stdio) a local dir walked
+      // for .md files. index.md skipped, bundle-root log.md merged into the
+      // wiki log page, frontmatter lifted with unknown keys preserved.
+      case 'import': {
+        let importFiles = args.files;
+        if (!importFiles && args.dir) {
+          const root = resolve(args.dir);
+          if (!existsSync(root)) throw new Error(`dir not found: ${args.dir}`);
+          importFiles = [];
+          const walk = (d) => {
+            for (const ent of readdirSync(d, { withFileTypes: true })) {
+              if (ent.name.startsWith('.')) continue;
+              const p = join(d, ent.name);
+              if (ent.isDirectory()) walk(p);
+              else if (/\.md$/i.test(ent.name)) {
+                if (importFiles.length >= 500) throw new Error('import capped at 500 files — split the bundle');
+                importFiles.push({ path: p.slice(root.length + 1).replace(/\\/g, '/'), content: readFileSync(p, 'utf8') });
+              }
+            }
+          };
+          walk(root);
+        }
+        if (!Array.isArray(importFiles) || importFiles.length === 0) {
+          throw new Error('import requires files[] (or dir on stdio) with at least one .md file');
+        }
+        const result = await api('POST', '/api/wiki/import', { files: importFiles, dryRun: !!args.dryRun }, orgHeader);
+        return ok(withOrg(result));
+      }
+
       // ── write ───────────────────────────────────────────────────
       case 'write': {
         const { path: writePath, title: writeTitle, content: writeContent, type: writeType, frontmatter } = args;
@@ -3628,15 +3904,21 @@ tool('wiki', 'Per-org wiki. Markdown pages with paths as hierarchy. You and othe
         if (writeType) body.type = writeType;
         if (frontmatter !== undefined) body.frontmatter = frontmatter;
 
+        // Writing the reserved log page directly is allowed (it IS an editable
+        // page) but the `log` action keeps the OKF date-grouped format for you.
+        const logNote = normalized === 'log'
+          ? 'Note: prefer wiki(action="log") for log entries — it maintains the OKF date-grouped format (## YYYY-MM-DD headings, newest first).'
+          : undefined;
+
         // Check if page exists — if so, update; otherwise create. `orgHeader`
         // (the `org` arg) targets a specific org without switching the active org.
         try {
           const existing = await api('GET', `/api/wiki/page?path=${encodeURIComponent(normalized)}`, undefined, orgHeader);
           const result = await api('PATCH', `/api/wiki/pages/${existing.id}`, body, orgHeader);
-          return ok(withOrg({ path: result.path, title: result.title, id: result.id, updated: true, url: wikiBrowserUrl(result.path) }));
+          return ok(withOrg({ path: result.path, title: result.title, id: result.id, updated: true, url: wikiBrowserUrl(result.path), note: logNote }));
         } catch {
           const result = await api('POST', '/api/wiki/pages', body, orgHeader);
-          return ok(withOrg({ path: result.path, title: result.title, id: result.id, created: true, url: wikiBrowserUrl(result.path) }));
+          return ok(withOrg({ path: result.path, title: result.title, id: result.id, created: true, url: wikiBrowserUrl(result.path), note: logNote }));
         }
       }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drafted",
-  "version": "1.12.8",
+  "version": "1.13.0",
   "description": "Drafted — visual thinking surface for humans and AI agents. Renders HTML, markdown, images, and code as frames on a zoomable canvas, with MCP tools for AI agents and real-time sync for humans.",
   "type": "module",
   "files": [

package/src/shared/okf-log.mjs

@@ -0,0 +1,62 @@
+/**
+ * OKF v0.1 log.md formatting (knowledge-catalog okf/SPEC.md, reserved files):
+ * a `# ... Log` title, then newest-first `## YYYY-MM-DD` date headings (ISO
+ * date ONLY), each with `* **Verb**: message` bullets.
+ *
+ * Lives in src/shared (shipped in the npm package) because both the server
+ * (server/lib/okf.mjs) and the stdio MCP wiki `log` action need it —
+ * server/lib is NOT shipped to npm installs.
+ */
+
+const OKF_LOG_VERBS = ['Update', 'Creation', 'Deprecation', 'Initialization'];
+
+/** Normalize a verb: capitalized, defaulting to 'Update'. Unknown verbs pass
+ * through capitalized — the leading bold word is an OKF convention, not an
+ * enforced enum. */
+export function okfLogVerb(verb) {
+  const v = typeof verb === 'string' ? verb.trim() : '';
+  if (!v) return 'Update';
+  return v[0].toUpperCase() + v.slice(1);
+}
+
+/** One OKF log bullet: `* **Verb**: message (agent, HH:MM UTC)` */
+export function formatOkfLogEntry(verb, message, agent, when = new Date()) {
+  const hh = String(when.getUTCHours()).padStart(2, '0');
+  const mm = String(when.getUTCMinutes()).padStart(2, '0');
+  return `* **${okfLogVerb(verb)}**: ${message} (${agent}, ${hh}:${mm} UTC)`;
+}
+
+/**
+ * Insert `entryLine` under the `## YYYY-MM-DD` heading for `when` (UTC),
+ * creating the heading (newest-first, after the `# ... Log` title when one
+ * exists) if missing. Legacy `## <ISO datetime> ...` headings are left
+ * untouched — permissive, no destructive rewrite.
+ */
+export function appendOkfLogEntry(content, entryLine, when = new Date(), title = 'Log') {
+  const dateHeading = '## ' + when.toISOString().slice(0, 10);
+  const text = content || '';
+  if (!text.trim()) {
+    return ['# ' + title, '', dateHeading, '', entryLine, ''].join('\n');
+  }
+  const lines = text.split('\n');
+  const idx = lines.findIndex((l) => l.trim() === dateHeading);
+  if (idx >= 0) {
+    // Append at the end of today's section (before the next heading),
+    // skipping past trailing blank lines inside the section.
+    let end = idx + 1;
+    while (end < lines.length && !/^#{1,6}\s/.test(lines[end])) end++;
+    let insertAt = end;
+    while (insertAt > idx + 1 && lines[insertAt - 1].trim() === '') insertAt--;
+    lines.splice(insertAt, 0, entryLine);
+    return lines.join('\n');
+  }
+  // New date section goes at the top (newest first), after a leading
+  // `# ...` document title when present.
+  let at = 0;
+  if (/^#\s/.test(lines[0])) {
+    at = 1;
+    while (at < lines.length && lines[at].trim() === '') at++;
+  }
+  lines.splice(at, 0, dateHeading, '', entryLine, '');
+  return lines.join('\n');
+}