drafted 1.19.16 → 1.19.18

package/cli/drafted.mjs

@@ -16,7 +16,7 @@ import { homedir, tmpdir, platform } from 'os';
 import { fileURLToPath } from 'url';
 import { createHash } from 'node:crypto';
 import { DESIGN_SYSTEM_PROMPT, buildDesignPrompt } from './prompts.mjs';
-import { scanRepoAgents, detectDefaultBranch, detectRemoteUrl, isGitUrl, cloneToTemp } from './repo-scan.mjs';
+import { scanRepoAgents, detectDefaultBranch, detectRemoteUrl, isGitUrl, cloneToTemp, classifySeed } from './repo-scan.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -301,9 +301,14 @@ async function readApiGet(command, apiPath, org) {
     // so a 401/403 here means the credential is genuinely missing/expired — surface
     // an actionable next step instead of the bare server "Unauthenticated" string.
     if (res.status === 401 || res.status === 403) {
+      // Name BOTH paths. `drafted login` is interactive, so an agent that reads
+      // only this line hands its user a shell command instead of a link — which
+      // is what happened. An agent should call the MCP auth tool and surface the
+      // URL it returns; approval writes the shared auth file, fixing the CLI too.
       msg = `Not authenticated for ${serverUrl} — your Drafted session is missing or expired. `
-        + `Run \`drafted login\` to sign in. `
-        + `The CLI and MCP share ${DEFAULT_AUTH_FILE}, so signing in once works for both.`;
+        + `If you are a person at a terminal: run \`drafted login\`. `
+        + `If you are an agent: call the Drafted MCP auth tool with action="get_link" and give the URL to your user — you cannot complete a sign-in yourself. `
+        + `Either way the approval lands in ${DEFAULT_AUTH_FILE}, which the CLI and MCP share.`;
     }
     jsonOut(false, command, msg);
     console.error(`❌ ${msg}`);
@@ -2143,62 +2148,48 @@ minionCmd
 // read-only index for browse/search. `repo add` is idempotent (re-scan on re-add),
 // so content edits in git are reflected with no pin bump. No Drafted token in the
 // daemon — it shells out to this verb.
-const repoCmd = program.command('repo').description('Registered git repos (org index of .agents/ skills/identities)');
+// `repo add` and `repo remove` are gone on purpose. Linking a folder to a repo
+// (and detaching it) moves that folder's wiki + skills into git, makes Drafted
+// read-only for them, and commits someone's knowledge to someone's repository.
+// That is a decision a person makes in the Drafted UI — Settings > Organization
+// > GitHub to connect the account, then the folder menu — not something a script
+// or an agent does in passing. `list`, `lookup` and `rescan` remain.
+const repoCmd = program.command('repo').description('Registered git repos (org index of .agents/ skills/identities and .wiki/ pages)');
 
 repoCmd
-  .command('add <url>')
-  .description('Link a GitHub repo to an org FOLDER — the server fetches it and indexes .agents/ skills/identities (repos are folder-scoped, never org-level). --branch points at a named branch (fails loudly if missing instead of guessing).')
+  .command('list')
+  .description('List the org\'s linked repos with their folder + git index counts (.agents/ skills/identities, .wiki/ pages)')
   .option('--org <org>', 'resolve against this Drafted org (id or name); scopes per-request without switching the session')
-  .option('--folder <name>', 'folder to link the repo into (required)')
-  .option('--slug <slug>', 'repo slug (defaults to the repo name from the URL)')
-  .option('--branch <name>', 'git branch to track (default: the repo default; fails loudly if the branch is missing)')
-  .option('--description <desc>', 'short description')
   .option('--format <fmt>', 'output format: json or text', 'text')
-  .action(async (url, opts) => {
-    requireLogin();
-    const orgHeaders = opts.org ? { 'X-Drafted-Org': opts.org } : {};
-    const server = getServerUrl().replace(/\/$/, '');
-    const fail = (msg) => { if (opts.format === 'json') console.log(JSON.stringify({ ok: false, command: 'repo:add', error: msg })); else console.log(['error', msg].join('\t')); process.exit(1); };
-    const folderName = String(opts.folder || '').trim();
-    if (!folderName) return fail('--folder <name> is required — repos are linked to a folder, never to the org directly');
-    // Resolve folder name -> id in the target org.
-    const foldersRes = await authFetch(`${server}/api/folders`, { headers: orgHeaders });
-    const foldersJson = await foldersRes.json().catch(() => ({}));
-    if (!foldersRes.ok) return fail(foldersJson.error || `HTTP ${foldersRes.status}`);
-    const folders = Array.isArray(foldersJson) ? foldersJson : foldersJson.folders || [];
-    const folder = folders.find((f) => f.name === folderName);
-    if (!folder) return fail(`no folder named "${folderName}" in this org`);
-    // The server fetches + scans; the CLI only resolves the association.
-    const payload = { gitUrl: url, folderId: folder.id, slug: opts.slug, description: opts.description, branch: opts.branch };
-    const res = await authFetch(`${server}/api/repos`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json', ...orgHeaders },
-      body: JSON.stringify(payload),
-    });
-    const data = await res.json().catch(() => ({}));
-    if (!res.ok) return fail(data.error || `HTTP ${res.status}`);
-    const created = res.status === 201;
-    if (opts.format === 'json') {
-      console.log(JSON.stringify({ ok: true, command: 'repo:add', data: { ...data, created } }));
-    } else {
-      console.log([created ? 'added' : 'updated', data.slug || '', data.gitUrl || url, folderName, `branch:${data.branch || '-'}`, `skills:${data.skills ?? 0}`, `identities:${data.identities ?? 0}`].join('\t'));
-    }
+  .action(async (opts) => {
+    const data = await readApiGet('repo:list', '/api/repos', opts.org);
+    const rows = data.repos || [];
+    if (opts.format === 'json') { console.log(JSON.stringify(rows)); return; }
+    for (const r of rows) console.log([r.slug, r.folderName || '-', r.gitUrl, `branch:${r.branch || '-'}`, `skills:${r.skillCount ?? 0}`, `identities:${r.identityCount ?? 0}`, `wiki:${r.wikiCount ?? 0}`].join('\t'));
   });
+
 repoCmd
-  .command('list')
-  .description('List the org\'s linked repos with their folder + .agents/ index counts')
+  .command('entries')
+  .description('Search the git index across the org\'s connected repos — the .agents/ skills and identities and .wiki/ pages each one exposes')
   .option('--org <org>', 'resolve against this Drafted org (id or name); scopes per-request without switching the session')
+  .option('--query <q>', 'match against name, slug and description')
+  .option('--kind <kind>', 'restrict to one of: skill, identity, wiki')
   .option('--format <fmt>', 'output format: json or text', 'text')
   .action(async (opts) => {
-    const data = await readApiGet('repo:list', '/api/repos', opts.org);
-    const rows = data.repos || [];
+    const params = new URLSearchParams();
+    if (opts.query) params.set('q', opts.query);
+    if (opts.kind) params.set('kind', opts.kind);
+    const qs = params.toString();
+    const data = await readApiGet('repo:entries', `/api/repos/entries${qs ? '?' + qs : ''}`, opts.org);
+    const rows = data.entries || [];
     if (opts.format === 'json') { console.log(JSON.stringify(rows)); return; }
-    for (const r of rows) console.log([r.slug, r.folderName || '-', r.gitUrl, `branch:${r.branch || '-'}`, `skills:${r.skillCount ?? 0}`, `identities:${r.identityCount ?? 0}`].join('\t'));
+    if (!rows.length) { console.log('no entries'); return; }
+    for (const e of rows) console.log([e.kind, e.slug || e.name, `repo:${e.repoSlug || '-'}`, e.sourcePath || ''].join('\t'));
   });
 
 repoCmd
   .command('rescan <slugOrId>')
-  .description('Re-fetch the tracked branch and refresh a repo\'s .agents/ index (idempotent; reports staleness via lastScannedAt/Sha)')
+  .description('Re-fetch the tracked branch and refresh a repo\'s git index — .agents/ and .wiki/ (idempotent; reports staleness via lastScannedAt/Sha)')
   .option('--org <org>', 'resolve against this Drafted org (id or name); scopes per-request without switching the session')
   .option('--format <fmt>', 'output format: json or text', 'text')
   .action(async (slugOrId, opts) => {
@@ -2220,34 +2211,7 @@ repoCmd
     const data = await res.json().catch(() => ({}));
     if (!res.ok) { const m = data.error || `HTTP ${res.status}`; if (opts.format === 'json') console.log(JSON.stringify({ ok: false, command: 'repo:rescan', error: m })); else console.log(['error', m].join('\t')); process.exit(1); }
     if (opts.format === 'json') console.log(JSON.stringify({ ok: true, command: 'repo:rescan', data }));
-    else console.log(['rescaned', data.slug || '', data.branch || '-', `skills:${data.skills ?? 0}`, `identities:${data.identities ?? 0}`].join('\t'));
-  });
-
-repoCmd
-  .command('remove <slugOrId>')
-  .description('Remove a registered repo (cascades its index entries)')
-  .option('--org <org>', 'resolve against this Drafted org (id or name); scopes per-request without switching the session')
-  .option('--format <fmt>', 'output format: json or text', 'text')
-  .action(async (slugOrId, opts) => {
-    requireLogin();
-    const orgHeaders = opts.org ? { 'X-Drafted-Org': opts.org } : {};
-    const server = getServerUrl().replace(/\/$/, '');
-    // UUID? DELETE directly. Otherwise resolve slug -> id via the list.
-    const isUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(slugOrId);
-    let id = isUuid ? slugOrId : null;
-    if (!id) {
-      const lookup = await authFetch(`${server}/api/repos`, { headers: orgHeaders });
-      const lj = await lookup.json().catch(() => ({}));
-      if (!lookup.ok) { if (opts.format === 'json') console.log(JSON.stringify({ ok: false, command: 'repo:remove', error: lj.error || `HTTP ${lookup.status}` })); else console.log(['error', lj.error || `HTTP ${lookup.status}`].join('\t')); process.exit(1); }
-      const found = (lj.repos || []).find((r) => r.slug === slugOrId);
-      if (!found) { if (opts.format === 'json') console.log(JSON.stringify({ ok: false, command: 'repo:remove', error: `no repo with slug "${slugOrId}"` })); else console.log(['error', `no repo with slug "${slugOrId}"`].join('\t')); process.exit(1); }
-      id = found.id;
-    }
-    const res = await authFetch(`${server}/api/repos/${encodeURIComponent(id)}`, { method: 'DELETE', headers: orgHeaders });
-    const data = await res.json().catch(() => ({}));
-    if (!res.ok) { if (opts.format === 'json') console.log(JSON.stringify({ ok: false, command: 'repo:remove', error: data.error || `HTTP ${res.status}` })); else console.log(['error', data.error || `HTTP ${res.status}`].join('\t')); process.exit(1); }
-    if (opts.format === 'json') console.log(JSON.stringify({ ok: true, command: 'repo:remove', data: { id } }));
-    else console.log(['removed', id].join('\t'));
+    else console.log(['rescaned', data.slug || '', data.branch || '-', `skills:${data.skills ?? 0}`, `identities:${data.identities ?? 0}`, `wiki:${data.wiki ?? 0}`].join('\t'));
   });
 
 program.parse();

package/cli/repo-scan.mjs

@@ -8,7 +8,7 @@
 // (slug + name). See docs/plans/org-substrate-normalization.md.
 
 import { readFileSync, readdirSync, existsSync, mkdtempSync } from 'fs';
-import { join } from 'path';
+import { join, relative, sep } from 'path';
 import { tmpdir } from 'os';
 import { execSync } from 'child_process';
 import { parse as parseYaml } from 'yaml';
@@ -30,10 +30,12 @@ export function parseFrontmatter(text) {
 // ── Scan ────────────────────────────────────────────────────────────
 
 /**
- * Scan <dir>/.agents/skills/<name>/SKILL.md and <dir>/.agents/identities/<slug>/
- * identity.yaml. Returns { skills, identities } catalog entries (metadata +
- * pointers only — no file content). A skill with no frontmatter still indexes
- * (name falls back to the dir). Identities index {slug, name} from identity.yaml.
+ * Scan <dir>/.agents/skills/<name>/SKILL.md, <dir>/.agents/identities/<slug>/
+ * identity.yaml and <dir>/.wiki/**.md. Returns { skills, identities, wiki }
+ * catalog entries (metadata + pointers only — no file content). A skill with no
+ * frontmatter still indexes (name falls back to the dir). Identities index
+ * {slug, name} from identity.yaml. A wiki page's slug is its `.wiki/`-relative
+ * path with `.md` stripped, which is exactly its Drafted wiki path.
  */
 export function scanRepoAgents(dir) {
   const skills = [];
@@ -84,7 +86,54 @@ export function scanRepoAgents(dir) {
     }
   }
 
-  return { skills, identities };
+  return { skills, identities, wiki: scanRepoWiki(dir) };
+}
+
+/**
+ * Scan <dir>/.wiki/**.md. One entry per page; `index.md` is skipped at every
+ * level because Drafted SYNTHESIZES it on read (a reserved path, never a stored
+ * page) — indexing it would shadow the synthesis with a stale copy.
+ */
+export function scanRepoWiki(dir) {
+  const root = join(dir, '.wiki');
+  if (!existsSync(root)) return [];
+  const pages = [];
+  for (const file of walkMarkdown(root)) {
+    const rel = relative(root, file).split(sep).join('/');
+    if (rel.split('/').pop() === 'index.md') continue;
+    const text = readFileSync(file, 'utf8');
+    const fm = parseFrontmatter(text) || {};
+    const slug = rel.replace(/\.md$/, '');
+    pages.push({
+      kind: 'wiki',
+      name: String(fm.title || firstHeading(text) || slug.split('/').pop()),
+      slug,
+      description: fm.description != null ? String(fm.description) : '',
+      sourcePath: `.wiki/${rel}`,
+    });
+  }
+  return pages.sort((a, b) => a.slug.localeCompare(b.slug));
+}
+
+function firstHeading(text) {
+  const m = text.match(/^#\s+(.+)$/m);
+  return m ? m[1].trim() : null;
+}
+
+/** Recursively yield every `.md` file under dir, skipping dot-entries. */
+function* walkMarkdown(dir) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    if (e.name.startsWith('.')) continue;
+    const full = join(dir, e.name);
+    if (e.isDirectory()) yield* walkMarkdown(full);
+    else if (e.isFile() && e.name.endsWith('.md')) yield full;
+  }
 }
 
 function readdirSafe(dir) {
@@ -95,6 +144,41 @@ function readdirSafe(dir) {
   }
 }
 
+// ── Seed-on-link ────────────────────────────────────────────────────
+
+/**
+ * Classify what seeding a folder's wiki + skills onto a branch would do.
+ *
+ * Linking is a MIGRATION, not a flag flip: the folder's existing content must
+ * land in git BEFORE the folder flips to repo-owned, or every page and skill it
+ * already holds becomes unauthorable and shadowed. So a path already on the
+ * branch is a CONFLICT — refuse the link and list them — unless the content is
+ * identical, which makes it a no-op and keeps `link -> detach -> link` idempotent.
+ *
+ * @param {Map<string,string>|object} existing branch path -> file content
+ * @param {{path:string, content:string}[]} seed what the folder would write
+ * @returns {{creates:string[], identical:string[], conflicts:string[]}}
+ */
+export function classifySeed(existing, seed) {
+  const get = existing instanceof Map ? (p) => existing.get(p) : (p) => existing?.[p];
+  const out = { creates: [], identical: [], conflicts: [] };
+  for (const f of seed || []) {
+    const there = get(f.path);
+    if (there === undefined || there === null) out.creates.push(f.path);
+    else if (sameContent(there, f.content)) out.identical.push(f.path);
+    else out.conflicts.push(f.path);
+  }
+  return out;
+}
+
+// ponytail: byte equality modulo line endings and trailing blank space. Enough
+// to make a re-link a no-op; if a semantic (frontmatter-order) diff ever matters,
+// compare parsed OKF instead.
+function sameContent(a, b) {
+  const norm = (s) => String(s ?? '').replace(/\r\n/g, '\n').replace(/\s+$/, '');
+  return norm(a) === norm(b);
+}
+
 /** Best-effort default branch of a git checkout. 'main' if git is unavailable. */
 export function detectDefaultBranch(dir) {
   try {

package/mcp/server.mjs

@@ -19,6 +19,7 @@ import { z } from 'zod';
 import { registerAppResource, RESOURCE_MIME_TYPE } from '@modelcontextprotocol/ext-apps/server';
 import WebSocket from 'ws';
 import { LAYERS } from '../src/shared/constants.mjs';
+import { liftFolderScope, rootEntries, subfolderEntries } from '../src/shared/folder-path.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, formatProjectIndex, projectPath, PROJECT_CONTEXT_BUDGET_CHARS } from './gates.mjs';
@@ -273,6 +274,8 @@ export function splitOrgScope(raw) {
   return { path: m[2] ? `/${m[2]}` : '/', org: decodeURIComponent(m[1]) };
 }
 
+const ROOT_HINT = '<base>/wiki, <base>/skills, <base>/tasks, <base>/projects';
+
 // Accept a FULL share URL (https://drafted.live/o/...?...) — humans paste links,
 // not paths. The pathname of a Drafted URL IS the fs path (Q2: one canonical link
 // for both consumers), so stripping the origin leaves an addressable path. Falls
@@ -1072,6 +1075,13 @@ function workingOrgId() {
   return session.boundOrgId || session.activeProjectMeta?.orgId || getState().projectMeta?.orgId || null;
 }
 
+// One `ls` level of folders, from the org's folder list. Defined inside the
+// closure because `api` is — it carries this session's auth and org scope.
+async function listSubfolders(base, prefix, orgHeader) {
+  const rows = await api('GET', '/api/folders', undefined, orgHeader).catch(() => []);
+  return subfolderEntries(base, prefix, (Array.isArray(rows) ? rows : []).map((r) => r?.name));
+}
+
 async function api(method, path, body, extraHeaders = {}, _retried = false, _orgHealed = false) {
   await ensureSession();
   const pid = getState().projectId;
@@ -2072,12 +2082,33 @@ async function waitForBootstrapAuth(deadline, staleSid) {
   return null;
 }
 
-if (!isRemote) tool('auth', 'Sign in to Drafted. On a local install the DESKTOP APP is the sign-in surface: both actions open the Drafted app to its sign-in window — no device link is shown. `action=login` opens the app and waits for the in-app sign-in to complete; `action=get_link` opens the app and returns immediately (the next Drafted tool call picks up the captured session). A device-code link is used ONLY as a fallback on platforms without the desktop app (the web MCP uses OAuth2, not this tool).', {
+if (!isRemote) tool('auth', 'Sign in to Drafted.\n\n`action=get_link` ALWAYS returns a sign-in URL. This is the action to use when you are an agent: you cannot complete a sign-in, so put the URL in your reply and stop — the human opens it in their own browser, approves, and your next Drafted call picks up the session. Approval also writes ~/.drafted/auth.json, so the `drafted` CLI is signed in too.\n\n`action=login` signs in and WAITS for it to land, opening the desktop app when one is installed. Use it only when a human is watching this terminal.\n\n(The web MCP uses OAuth2 and does not have this tool.)', {
   action: z.enum(['get_link', 'login']).describe('Operation to perform.'),
 }, async ({ action }) => {
   try {
-    // Local install → open the desktop app's sign-in window (no link). Falls through to the
-    // device-code flow below only when no desktop app is installed on this platform.
+    // get_link's ONE job is to return a URL a human can click. It runs before the
+    // already-authenticated check and before the desktop app on purpose:
+    //   - an agent cannot complete a sign-in, so handing back a link is the only
+    //     safe shape — the human clicks it out of band, in their own browser;
+    //   - "already authenticated" is about THIS MCP's session, which says nothing
+    //     about the CLI's on-disk credential, so short-circuiting on it used to
+    //     make the link unobtainable exactly when it was needed;
+    //   - opening the desktop app returns no link at all, which is useless to an
+    //     agent that must put something in its reply.
+    // Approval writes ~/.drafted/auth.json, so the CLI picks it up too.
+    if (action === 'get_link') {
+      const codeRes = await serverFetch(`${getServerUrl()}/auth/device/code`, { method: 'POST' });
+      if (!codeRes.ok) throw new Error(`Failed to start device authorization (HTTP ${codeRes.status})`);
+      const data = await codeRes.json();
+      persistPendingDeviceCode(data);
+      return ok({
+        signInUrl: data.verificationUrl,
+        instruction: 'Give this URL to the user and stop. They open it in their own browser and approve; you cannot complete this for them. Retry your request afterwards — the next Drafted call picks up the approved session.',
+        expiresInSeconds: data.expiresIn ?? null,
+      });
+    }
+    // `login` waits for the sign-in to land, so the desktop app is the better
+    // surface when one is installed: no code to type.
     {
       const activeSession = getState().sessionId;
       const bootstrapSession = getBootstrapSessionId();
@@ -2098,9 +2129,6 @@ if (!isRemote) tool('auth', 'Sign in to Drafted. On a local install the DESKTOP
       }
       const staleSid = getBootstrapSessionId();
       if (await launchDesktopSignin()) {
-        if (action === 'get_link') {
-          return ok('Opening the Drafted app to sign in — approve in the app window, then retry your request.');
-        }
         const sid = await waitForBootstrapAuth(Date.now() + 180000, staleSid);
         if (!sid) throw new Error('Timed out waiting for sign-in. Complete sign-in in the Drafted app window, then retry.');
         getState().sessionId = null;
@@ -2119,13 +2147,6 @@ if (!isRemote) tool('auth', 'Sign in to Drafted. On a local install the DESKTOP
         return ok({ status: 'logged_in', via: 'desktop-app' });
       }
     }
-    if (action === 'get_link') {
-      const codeRes = await serverFetch(`${getServerUrl()}/auth/device/code`, { method: 'POST' });
-      if (!codeRes.ok) throw new Error(`Failed to start device authorization (HTTP ${codeRes.status})`);
-      const data = await codeRes.json();
-      persistPendingDeviceCode(data);
-      return ok(data.verificationUrl);
-    }
     if (action === 'login') {
       // Prefer the active request session (injected by runWithRequestState on
       // remote, or cloneSession on stdio) over the on-disk bootstrap session, so
@@ -2966,12 +2987,12 @@ server.resource('info', 'drafted://info', {
       text: JSON.stringify({
         version: PACKAGE_VERSION,
         layers: LAYERS,
-        pathFormat: '/o/<org>/<root>/<path> — org first, no org switching',
+        pathFormat: '/o/<org>/<folder…?>/<root>/<path> — org first, no org switching; a folder chain may precede any root',
         roots: {
-          wiki: '/o/<org>/wiki/<path>',
-          skills: '/o/<org>/skills/<slug>',
-          tasks: '/o/<org>/tasks/<lane?>/<file>',
-          projects: '/o/<org>/projects/<folder?>/<project>/<layer>/<lane>/<file>',
+          wiki: '/o/<org>/<folder…?>/wiki/<path>',
+          skills: '/o/<org>/<folder…?>/skills/<slug>',
+          tasks: '/o/<org>/<folder…?>/tasks/<lane?>/<file>',
+          projects: '/o/<org>/<folder…?>/projects/<project>/<layer>/<lane>/<file>',
         },
         tools: ['fs (ls/read/write/edit/mv/rm/mkdir/search)', 'whoami', 'auth', 'session', 'trigger', 'focus', 'tour', 'screenshot', 'minion'],
       }, null, 2),
@@ -2979,9 +3000,9 @@ server.resource('info', 'drafted://info', {
   };
 });
 
-tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder: `fs(ls, path="/")` lists the orgs you can address, then `/o/<org>/<root>/...` addresses one of them — the org is part of the path, there is no org switching:\n\n- `/o/<org>/wiki/<path>` — org knowledge pages (markdown, OKF; free nesting; `index.md` at any level is synthesized and read-only)\n- `/o/<org>/skills/<slug>` — reusable procedures (flat: one dir per skill slug, `SKILL.md` + supporting files inside)\n- `/o/<org>/tasks/<lane?>/<file>` — work items. A task IS a frame: `read` renders its `drafted:status:`/`drafted:assignee:` as front matter and `write`/`edit` parse them back into columns, so they are never stored in the body. The keys are namespaced so an ordinary `status:` in your own front matter is left alone. Valid statuses: open, in_progress, scheduled, needs_review, needs_decision, done, failed (an empty `drafted:status:` clears it). Status is a column, not a location — a task moved out of /tasks stays a task.\n- `/o/<org>/projects/<folder?>/<project>/<layer>/<lane>/<file>` — producible frames (folder optional; then exactly layer → lane → file)\n\n(Bare `/wiki`, `/skills`, `/tasks`, `/projects` roots still resolve via the session\'s working org.)\n\nVerbs: `ls` (list a directory), `read` (file content — hashline-annotated for text so `edit` stays surgical), `write` (create/overwrite; extension + layer classify the type: .html design, .md document, .excalidraw diagram, .xlsx/.docx office, images/videos media, .pdf asset, .google-doc/.google-sheet/.google-slide create native Google Workspace files), `edit` (hashline ops for text, element ops for excalidraw, structured ops for office), `mv` (rename/move, cross-project), `rm` (delete), `search` (frames are searched by label AND content, with the matching line returned as a snippet; `fs(search, path="/")` or `path="/o/<org>"` fans out across wiki + skills + projects in one call), `link` / `unlink` / `links` (relate one frame to another frame, to a project, or to an external url — `links` lists a frame\'s edges plus its backlinks, and on a project path lists the tasks linked to that project; a link is stored by ID, so `mv` never breaks it). `mkdir` creates a project only: use `/projects/<project>` or `/projects/<folder>/<project>`, never a layer path. To create a layer, write its first frame at `/projects/<project>/<new-layer>/<lane>/<file>`.\n\nThe project is resolved from the path itself — no separate "open" step. Guardrails are server-side and unchanged: the org in the path must be the project\'s own org (project paths under /o/<org>/ validate it), the G1 wiki-search gate fires before project mutations, attached-skill gates fire on mutations, anchored frames must be read before editing a layer, `.skillinstall/` is stripped on skill push.', {
+tool('fs', 'Navigate Drafted like a local filesystem. A FOLDER is the single container and the org is the folder at depth 0: `fs(ls, path="/")` lists the orgs you can address, `/o/<org>` is that org, and every folder level — the org included — carries the SAME four roots:\n\n- `<folder>/wiki/<path>` — knowledge pages (markdown, OKF; free nesting; `index.md` at any level is synthesized and read-only)\n- `<folder>/skills/<slug>` — reusable procedures (flat: one dir per skill slug, `SKILL.md` + supporting files inside; slugs stay unique per ORG, so a skill resolves by slug from anywhere)\n- `<folder>/tasks/<lane?>/<file>` — work items. A task IS a frame: `read` renders its `drafted:status:`/`drafted:assignee:` as front matter and `write`/`edit` parse them back into columns, so they are never stored in the body. The keys are namespaced so an ordinary `status:` in your own front matter is left alone. Valid statuses: open, in_progress, scheduled, needs_review, needs_decision, done, failed (an empty `drafted:status:` clears it). Status is a column, not a location — a task moved out of /tasks stays a task.\n- `<folder>/projects/<project>/<layer>/<lane>/<file>` — producible frames (then exactly layer → lane → file)\n\nFolders nest arbitrarily: `/o/<org>/engineering/backend/wiki/deploy`. The ROOT KEYWORD IS THE SEPARATOR — everything before `wiki`/`skills`/`tasks`/`projects` is the folder chain, everything after is the path inside that root, so `/o/<org>/wiki/engineering/foo` (the org wiki, nested page) and `/o/<org>/engineering/wiki/foo` (the engineering folder\'s wiki) are different pages. The four names are therefore RESERVED: a folder cannot be called one. `fs(ls, path="/o/<org>/<folder>")` shows a folder\'s four roots plus the folders inside it; `fs(mkdir, path="/o/<org>/<folder>")` creates one.\n\n(Bare `/wiki`, `/skills`, `/tasks`, `/projects` roots still resolve via the session\'s working org, at that org\'s root.)\n\nVerbs: `ls` (list a directory), `read` (file content — hashline-annotated for text so `edit` stays surgical), `write` (create/overwrite; extension + layer classify the type: .html design, .md document, .excalidraw diagram, .xlsx/.docx office, images/videos media, .pdf asset, .google-doc/.google-sheet/.google-slide create native Google Workspace files), `edit` (hashline ops for text, element ops for excalidraw, structured ops for office), `mv` (rename/move, cross-project), `rm` (delete), `search` (frames are searched by label AND content, with the matching line returned as a snippet; `fs(search, path="/")` or `path="/o/<org>"` fans out across wiki + skills + projects in one call), `link` / `unlink` / `links` (relate one frame to another frame, to a project, or to an external url — `links` lists a frame\'s edges plus its backlinks, and on a project path lists the tasks linked to that project; a link is stored by ID, so `mv` never breaks it). `mkdir` creates a project only: use `/projects/<project>` or `/projects/<folder>/<project>`, never a layer path. To create a layer, write its first frame at `/projects/<project>/<new-layer>/<lane>/<file>`.\n\nThe project is resolved from the path itself — no separate "open" step. Guardrails are server-side and unchanged: the org in the path must be the project\'s own org (project paths under /o/<org>/ validate it), the G1 wiki-search gate fires before project mutations, attached-skill gates fire on mutations, anchored frames must be read before editing a layer, `.skillinstall/` is stripped on skill push.', {
   action: z.enum(['ls', 'read', 'write', 'edit', 'mv', 'rm', 'mkdir', 'search', 'link', 'unlink', 'links']).describe('Filesystem verb.'),
-  path: z.string().describe('Drafted path: /o/<org>/wiki/... | /o/<org>/skills/... | /o/<org>/tasks/... | /o/<org>/projects/... (bare /wiki, /skills, /tasks, /projects also work; for mv: source)'),
+  path: z.string().describe('Drafted path: /o/<org>[/<folder…>]/wiki/... | .../skills/... | .../tasks/... | .../projects/... — a folder chain may precede any root (bare /wiki, /skills, /tasks, /projects also work; for mv: source)'),
   to: z.string().optional().describe('[mv] destination path; [link/unlink] target path — a frame path, or a project path (/o/<org>/projects/<project>) to link a task to a project'),
   url: z.string().optional().describe('[link/unlink] external target URL, instead of `to` (a link is internal-by-id OR external-by-url, never both)'),
   query: z.string().optional().describe('[search] term to match against names/content'),
@@ -3025,7 +3046,24 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
     }
     to = toScoped.path;
   }
-  const orgHeader = org ? { 'X-Drafted-Org': org } : (orgFromPath ? { 'X-Drafted-Org': orgFromPath } : {});
+  // Folder chain (Wave 0): folder is the single recursive container and the org
+  // is that node at depth 0, so EVERY level carries the same four roots. The
+  // root keyword is the separator — everything before wiki/skills/tasks/projects
+  // is the folder chain, everything after is the path within that root. The
+  // folder rides the REQUEST (X-Drafted-Folder); it is never stored, because a
+  // "current folder" would be the retired org cursor rebuilt one level down.
+  const pScope = liftFolderScope(p, to);
+  if (pScope.error) return err(new Error(`${action} ${pScope.error}`));
+  const folder = pScope.folder;
+  to = pScope.to;
+  const orgHeader = {
+    ...(org ? { 'X-Drafted-Org': org } : (orgFromPath ? { 'X-Drafted-Org': orgFromPath } : {})),
+    ...(folder ? { 'X-Drafted-Folder': folder } : {}),
+  };
+  // The folder chain has been lifted into the header — everything below
+  // dispatches on the ROOT, at any depth, with no per-root folder handling.
+  const folderBase = `${orgFromPath ? `/o/${orgFromPath}` : ''}${folder ? '/' + folder : ''}`;
+  if (pScope.rest) p = pScope.rest;
   const gs = getSessionState().gates;
 
   // ── Root listing: / or empty → the orgs this session can address (Shape A) ──
@@ -3060,7 +3098,7 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
 
       section('Wiki', wiki, (v) => {
         const hits = (v?.hits || v?.pages || v?.results || []).slice(0, 10);
-        return hits.length ? hits.map(h => `  ${scope}/wiki/${h.path}${h.title ? `  — ${clip(h.title, 80)}` : ''}`).join('\n') : '';
+        return hits.length ? hits.map(h => `  ${scope}${h.folder ? `/${h.folder}` : ''}/wiki/${h.path}${h.title ? `  — ${clip(h.title, 80)}` : ''}`).join('\n') : '';
       });
       section('Skills', skills, (v) => {
         // Fewer than the other legs on purpose: skills search is fuzzy and its tail
@@ -3091,13 +3129,9 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
     }
     if (action !== 'ls') return err(new Error('read/write/edit/mv/rm require a path under /o/<org>/wiki, /o/<org>/skills, /o/<org>/tasks, or /o/<org>/projects'));
     if (orgFromPath) {
-      // ls /o/<org> → that org's roots
-      return ok([
-        { name: 'wiki', type: 'directory', path: `/o/${orgFromPath}/wiki`, hint: 'org knowledge pages (markdown, OKF)' },
-        { name: 'skills', type: 'directory', path: `/o/${orgFromPath}/skills`, hint: 'reusable procedures (flat: one dir per skill slug)' },
-        { name: 'tasks', type: 'directory', path: `/o/${orgFromPath}/tasks`, hint: 'work items — a task is a frame; status/assignee are front matter on read' },
-        { name: 'projects', type: 'directory', path: `/o/${orgFromPath}/projects`, hint: '<folder?>/<project>/<layer>/<lane>/<file>' },
-      ]);
+      // ls /o/<org> → the org IS the depth-0 folder: its four roots, plus the
+      // folders nested inside it (each carrying the same four).
+      return ok([...rootEntries(`/o/${orgFromPath}`), ...await listSubfolders(`/o/${orgFromPath}`, '', orgHeader)]);
     }
     // ls / → the orgs (id, slug, name) the agent belongs to; org is the top folder
     const orgs = await getOrgList();
@@ -3105,10 +3139,33 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
     return ok(orgs.map(o => ({ name: o.name || o.id, type: 'directory', path: `/o/${o.slug || o.id}`, hint: 'org — fs(ls, path="/o/<org>") shows its wiki/skills/projects' })));
   }
 
+  // ── A path with no root keyword names a FOLDER, at any depth ──────
+  // /o/<org>/engineering, /o/<org>/engineering/backend, … Same shape as the org
+  // itself: four roots plus whatever folders nest inside.
+  if (!pScope.rest && folder) {
+    if (action === 'ls') {
+      return ok([...rootEntries(folderBase), ...await listSubfolders(folderBase, folder, orgHeader)]);
+    }
+    if (action === 'mkdir') {
+      await requireBoundOrgForProjectlessMutation(org || orgFromPath);
+      const created = await api('POST', '/api/folders', { name: folder }, orgHeader);
+      return ok({ created: true, folder: created?.name || folder, id: created?.id, path: folderBase,
+        hint: 'a folder carries its own wiki, skills, tasks and projects' });
+    }
+    if (action === 'rm') {
+      await requireBoundOrgForProjectlessMutation(org || orgFromPath);
+      const rows = await api('GET', '/api/folders', undefined, orgHeader);
+      const row = (Array.isArray(rows) ? rows : []).find((f) => f.name === folder);
+      if (!row) return err(new Error(`no such folder: ${folder}`));
+      return ok(await api('DELETE', `/api/folders/${row.id}`, undefined, orgHeader));
+    }
+    return err(new Error(`${folderBase} is a folder — address one of its roots: ${ROOT_HINT.replace('<base>', folderBase)}`));
+  }
+
   // ── mkdir: create a project (a directory in the /projects root) ──
   if (action === 'mkdir') {
     if (!p.startsWith('/projects')) {
-      return err(new Error('mkdir is only meaningful under /projects (wiki dirs are implicit; skills are flat) — e.g. fs(mkdir, path="/o/<org>/projects/my-project")'));
+      return err(new Error('mkdir creates a project (/o/<org>/projects/<name>) or a folder (/o/<org>/<folder>, which then carries its own four roots) — wiki dirs are implicit and skills are flat, so neither needs one.'));
     }
     // A project create is project-less: it must not guess the org.
     await requireBoundOrgForProjectlessMutation(org || orgFromPath);
@@ -3116,18 +3173,21 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
     if (parts.length === 0 || parts.length > 2) {
       return err(new Error(`mkdir path must be /projects/<name> or /projects/<folder>/<name> — got ${p}`));
     }
-    const folder = parts.length === 2 ? parts[0] : null;
+    // Two spellings reach the same place: the folder chain before the root
+    // (/o/<org>/eng/projects/x) or the legacy segment after it
+    // (/o/<org>/projects/eng/x). The chain wins when both are given.
+    const projectFolder = folder || (parts.length === 2 ? parts[0] : null);
     const projectRef = parts[parts.length - 1];
     const existing = await resolveProjectRef(projectRef).catch(() => null);
     if (existing) return err(new Error(`project already exists: ${projectRef}`));
     const projectName = projectRef.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
     const created = await api('POST', '/api/projects', { name: projectName }, orgHeader);
     if (!created?.id) return err(new Error('project create returned no id'));
-    if (folder) {
-      try { await api('PATCH', `/api/project/${created.id}`, { folder }, orgHeader); } catch { /* folder best-effort */ }
+    if (projectFolder) {
+      try { await api('PATCH', `/api/project/${created.id}`, { folder: projectFolder }, orgHeader); } catch { /* folder best-effort */ }
     }
     projectRefCache.set(projectRef, { id: created.id, slug: created.slug, name: created.name, orgId: created.orgId, orgSlug: created.orgSlug });
-    return ok({ created: true, name: created.name, slug: created.slug, id: created.id, path: `${orgFromPath ? `/o/${orgFromPath}` : ''}/projects${folder ? '/' + folder : ''}/${created.slug}`, projectUrl: `${getServerUrl()}/o/${created.orgId || org || ''}/projects/${created.slug}` });
+    return ok({ created: true, name: created.name, slug: created.slug, id: created.id, path: `${folderBase}/projects/${created.slug}`, projectUrl: `${getServerUrl()}/o/${created.orgId || org || ''}/projects/${created.slug}` });
   }
 
   // ── Root: /wiki/... ────────────────────────────────────────────
@@ -3753,12 +3813,9 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
 // Agents reach the repos table through this tool. Content stays in git;
 // Drafted keeps a read-only index. `add`/`rescan` mutate; `list`/`entries`
 // are read-only and paginated with a compact mode (collection rule).
-tool('repo', 'Registered git repos — the org index of .agents/ skills + identities. A connected repo is the source of truth for its skills (git owns content, Drafted renders + indexes). Dispatch by `action`:\n- `list` — the org\'s linked repos (paginated, compact mode).\n- `add` — link a GitHub repo to a folder; the server fetches + indexes .agents/. `branch` points at a named branch (fails loudly if missing).\n- `rescan` — re-fetch the tracked branch and refresh the index.\n- `entries` — search the index across all the org\'s repos (skills + identities).\n\nAuthoring a Drafted skill whose slug collides with a repo-indexed skill returns 409 repo_owned pointing at the repo — commit to git instead.', {
-  action: z.enum(['list', 'add', 'rescan', 'entries']).describe('list: org repos; add: link a repo; rescan: re-fetch the tracked branch; entries: search the index.'),
-  gitUrl: z.string().optional().describe('[add] GitHub repo URL to link (e.g. https://github.com/owner/repo). Required for add.'),
-  folder: z.string().optional().describe('[add] folder name to link the repo into (required for add; repos are folder-scoped).'),
-  branch: z.string().optional().describe('[add] git branch to track (default: the repo default; fails loudly if the branch is missing).'),
-  slug: z.string().optional().describe('[add] repo slug (defaults to the repo name from the URL); [rescan] the repo slug or UUID.'),
+tool('repo', 'Registered git repos — the org index of .agents/ skills + identities. A connected repo is the source of truth for its skills (git owns content, Drafted renders + indexes). Dispatch by `action`:\n- `list` — the org\'s linked repos (paginated, compact mode).\n- `entries` — search the index across all the org\'s repos (skills + identities).\n- `rescan` — re-fetch the tracked branch and refresh the index.\n\nLINKING AND UNLINKING ARE NOT HERE. A person does them in the Drafted UI (Settings > Organization > GitHub to connect an account, then the folder menu), because linking moves a folder\'s wiki + skills into git and makes Drafted read-only for them. Agents read and rescan; they do not change who owns the content.\n\nAuthoring a Drafted skill whose slug collides with a repo-indexed skill returns 409 repo_owned pointing at the repo — commit to git instead.', {
+  action: z.enum(['list', 'entries', 'rescan']).describe('list: the org\'s connected repos; entries: search the git index across them; rescan: re-fetch a tracked branch and refresh its index.'),
+  slug: z.string().optional().describe('[rescan] the repo slug or UUID.'),
   repoId: z.string().optional().describe('[rescan] repo UUID (alternative to slug).'),
   query: z.string().optional().describe('[entries] search term (matches name/description/slug).'),
   kind: z.enum(['skill', 'identity']).optional().describe('[entries] filter to skill or identity.'),
@@ -3767,7 +3824,7 @@ tool('repo', 'Registered git repos — the org index of .agents/ skills + identi
   compact: z.boolean().optional().describe('list/entries: return only identity fields {slug,name,gitUrl} / {slug,name,kind} (default false).'),
   org: z.string().optional().describe('Org (id or name) to scope this call; defaults to the session\'s working org.'),
 }, async (args) => {
-  const { action, gitUrl, folder, branch, slug, repoId, query, kind, limit, offset, compact, org } = args;
+  const { action, slug, repoId, query, kind, limit, offset, compact, org } = args;
   const orgHeader = org ? { 'X-Drafted-Org': org } : {};
   const cap = Math.min(Math.max(1, Math.floor(Number(limit) || 25)), 100);
   const start = Math.max(0, Math.floor(Number(offset) || 0));
@@ -3783,17 +3840,6 @@ tool('repo', 'Registered git repos — the org index of .agents/ skills + identi
       }))),
     });
   }
-  if (action === 'add') {
-    if (!gitUrl) return err(new Error('add requires gitUrl (e.g. https://github.com/owner/repo)'));
-    if (!folder) return err(new Error('add requires folder (the folder name to link the repo into — repos are folder-scoped)'));
-    // Resolve folder name -> id in the target org.
-    const foldersRes = await api('GET', '/api/folders', undefined, orgHeader);
-    const folders = Array.isArray(foldersRes) ? foldersRes : (foldersRes?.folders || []);
-    const f = folders.find((x) => x.name === folder);
-    if (!f) return err(new Error(`no folder named "${folder}" in this org`));
-    const result = await api('POST', '/api/repos', { gitUrl, folderId: f.id, branch: branch || undefined, slug: slug || undefined }, orgHeader);
-    return ok({ slug: result.slug, gitUrl: result.gitUrl, branch: result.branch, skills: result.skills, identities: result.identities });
-  }
   if (action === 'rescan') {
     const id = repoId || await (async () => {
       if (!slug) return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drafted",
-  "version": "1.19.16",
+  "version": "1.19.18",
   "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/folder-path.mjs

@@ -0,0 +1,160 @@
+/**
+ * Folder is the single recursive container: the org is that node at depth 0, and
+ * EVERY folder level carries the same four roots (wiki, skills, tasks, projects).
+ *
+ *   /o/<org>/                      folder (depth 0)
+ *     wiki/ skills/ tasks/ projects/
+ *     engineering/                 folder
+ *       wiki/ skills/ tasks/ projects/
+ *
+ * The grammar is unambiguous by construction: the ROOT KEYWORD IS THE SEPARATOR.
+ * Everything before the first `wiki`/`skills`/`tasks`/`projects` segment is the
+ * folder chain; everything after is the path within that root. So
+ * `/wiki/engineering/foo` is the org wiki's nested page and
+ * `/engineering/wiki/foo` is the `engineering` folder's — distinct strings, no
+ * collision. The one constraint this imposes: the four names are RESERVED and a
+ * folder may not take one.
+ *
+ * A folder is ADDRESSED, never remembered: the chain travels in the path (and
+ * from there in a request-local `X-Drafted-Folder` header), so no shared row
+ * carries a "current folder". A cursor here would be the retired
+ * `sessions.org_id` mistake rebuilt one level down — see the Drafted wiki page
+ * `engineering/org-addressing-model`.
+ */
+
+export const ROOTS = ['wiki', 'skills', 'tasks', 'projects'];
+const RESERVED = new Set(ROOTS);
+
+export function isReservedFolderName(name) {
+  return RESERVED.has(String(name || '').trim().toLowerCase());
+}
+
+/** '' (org root) or 'a/b' — no leading/trailing slashes, no empty segments. */
+export function normalizeFolder(raw) {
+  return String(raw || '')
+    .split('/')
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .join('/');
+}
+
+/** null when the folder path is usable, else the reason it is not. */
+export function folderPathError(raw) {
+  const segs = String(raw || '').split('/').map((s) => s.trim()).filter(Boolean);
+  if (!segs.length) return 'Folder name is required';
+  for (const s of segs) {
+    if (isReservedFolderName(s)) {
+      return `"${s}" is a reserved name — wiki, skills, tasks and projects are the four roots every folder carries, so a folder cannot be called one`;
+    }
+    if (s.length > 120) return `Folder name too long: "${s.slice(0, 40)}…"`;
+  }
+  return null;
+}
+
+/**
+ * Split a path into its folder chain and the root-relative remainder.
+ *
+ *   /engineering/backend/wiki/foo → { folder: 'engineering/backend', rest: '/wiki/foo' }
+ *   /wiki/engineering/foo         → { folder: '',                    rest: '/wiki/engineering/foo' }
+ *   /engineering                  → { folder: 'engineering',         rest: '' }
+ *   /                             → { folder: '',                    rest: '' }
+ *
+ * `rest` is '' when the path names a folder itself (no root keyword in it).
+ */
+export function splitFolderScope(path) {
+  const segs = String(path || '').split('/').filter(Boolean);
+  const at = segs.findIndex((s) => RESERVED.has(s));
+  if (at === -1) return { folder: segs.join('/'), rest: '' };
+  return { folder: segs.slice(0, at).join('/'), rest: '/' + segs.slice(at).join('/') };
+}
+
+/** Re-join a folder chain and a root-relative path into one addressable path. */
+export function joinFolderScope(folder, rest) {
+  const f = normalizeFolder(folder);
+  const r = String(rest || '').replace(/^\/+/, '');
+  return '/' + [f, r].filter(Boolean).join('/');
+}
+
+/** The four roots as ls entries, for a folder at any depth (base = '/o/<org>[/<folder>]'). */
+export function rootEntries(base) {
+  const b = String(base || '').replace(/\/+$/, '');
+  const hints = {
+    wiki: 'knowledge pages (markdown, OKF)',
+    skills: 'reusable procedures (flat: one dir per skill slug)',
+    tasks: 'work items — a task is a frame; status/assignee are front matter on read',
+    projects: '<project>/<layer>/<lane>/<file>',
+  };
+  return ROOTS.map((name) => ({ name, type: 'directory', path: `${b}/${name}`, hint: hints[name] }));
+}
+
+/**
+ * The folder lift for an fs call: pull the folder chain off the source path (and
+ * off the destination, for mv), leaving root-relative paths the per-root
+ * dispatch can use unchanged at any depth.
+ *
+ * A move stays within one folder — silently re-homing a page across folders on
+ * a rename is the kind of quiet reorganisation that loses work.
+ */
+export function liftFolderScope(path, to) {
+  const src = splitFolderScope(path);
+  const folder = src.folder;
+  if (folder) {
+    const bad = folderPathError(folder);
+    if (bad) return { error: bad };
+  }
+  const out = { folder, path: src.rest || path, rest: src.rest, to };
+  if (to) {
+    const dst = splitFolderScope(to);
+    if (dst.rest) {
+      if (normalizeFolder(dst.folder) !== normalizeFolder(folder)) {
+        return { error: `stays within one folder — source is /${folder || ''} and destination is /${dst.folder || ''}` };
+      }
+      out.to = dst.rest;
+    }
+  }
+  return out;
+}
+
+/**
+ * The folders nested DIRECTLY inside `prefix` ('' = the org itself), given the
+ * org's folder names (each of which is its full path). One segment deeper only —
+ * `ls` shows a level, not a tree.
+ */
+export function subfolderEntries(base, prefix, names) {
+  const depth = prefix ? normalizeFolder(prefix).split('/').length : 0;
+  const kids = new Set();
+  for (const raw of names || []) {
+    const name = normalizeFolder(raw);
+    if (!name) continue;
+    if (prefix && !name.startsWith(normalizeFolder(prefix) + '/')) continue;
+    const segs = name.split('/');
+    if (segs.length > depth) kids.add(segs[depth]);
+  }
+  return [...kids].sort().map((name) => ({
+    name,
+    type: 'directory',
+    path: `${String(base || '').replace(/\/+$/, '')}/${name}`,
+    hint: 'folder — carries its own wiki, skills, tasks and projects',
+  }));
+}
+
+/**
+ * Process surfaces: wiki pages agents WRITE through the tool rather than read.
+ * Promote-to-commons appends to the wiki `log`, and a promotion that
+ * contradicts canon is flagged in `review`.
+ *
+ * They must be excluded from the seed AND exempted from the repo_owned guard,
+ * and those two must agree. Excluded but not exempted, they end up unauthorable
+ * AND unwritten — the tool 409s a page git never received, and promote-to-commons
+ * breaks with no obvious cause. Lives here because the CLI seeder and the server
+ * guard both need it and drift between them is exactly the failure.
+ *
+ * Whole path segments only — `reference/log-shipping` is a normal page.
+ */
+export const PROCESS_SURFACES = new Set(['log', 'review']);
+
+export function isProcessSurface(path) {
+  return String(path || '')
+    .split('/')
+    .some((seg) => PROCESS_SURFACES.has(seg));
+}