openwriter 0.40.2 → 0.40.3

package/dist/server/marks.js

@@ -0,0 +1,182 @@
+/**
+ * Agent Marks: sidecar JSON storage for inline user feedback.
+ * Each document gets a sidecar file at DATA_DIR/_marks/{filename}.json.
+ */
+import { join } from 'path';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, unlinkSync, renameSync } from 'fs';
+import { randomUUID } from 'crypto';
+import { getDataDir, ensureDataDir } from './helpers.js';
+function getMarksDir() { return join(getDataDir(), '_marks'); }
+function ensureMarksDir() {
+    ensureDataDir();
+    if (!existsSync(getMarksDir()))
+        mkdirSync(getMarksDir(), { recursive: true });
+}
+function markFilePath(filename) {
+    // Sanitize: replace path separators to avoid nested paths
+    const safe = filename.replace(/[/\\]/g, '_');
+    return join(getMarksDir(), `${safe}.json`);
+}
+function readMarkFile(filename) {
+    const path = markFilePath(filename);
+    if (!existsSync(path))
+        return { marks: [] };
+    try {
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return { marks: [] };
+    }
+}
+function writeMarkFile(filename, data) {
+    ensureMarksDir();
+    const path = markFilePath(filename);
+    if (data.marks.length === 0) {
+        // Clean up empty sidecar files
+        if (existsSync(path))
+            unlinkSync(path);
+        return;
+    }
+    writeFileSync(path, JSON.stringify(data, null, 2));
+}
+export function addMark(filename, text, note, nodeId, nodeIds) {
+    const data = readMarkFile(filename);
+    const mark = {
+        id: randomUUID().slice(0, 8),
+        text,
+        note,
+        nodeId,
+        ...(nodeIds && nodeIds.length > 1 ? { nodeIds } : {}),
+        createdAt: new Date().toISOString(),
+    };
+    data.marks.push(mark);
+    writeMarkFile(filename, data);
+    return mark;
+}
+export function getMarks(filename) {
+    if (filename) {
+        const data = readMarkFile(filename);
+        if (data.marks.length === 0)
+            return {};
+        return { [filename]: data.marks };
+    }
+    // All docs: scan _marks directory
+    ensureMarksDir();
+    const result = {};
+    try {
+        const files = readdirSync(getMarksDir());
+        for (const file of files) {
+            if (!file.endsWith('.json'))
+                continue;
+            const docFilename = file.replace(/\.json$/, '').replace(/_/g, ' ');
+            // Read raw to avoid filename roundtrip issues
+            const path = join(getMarksDir(), file);
+            try {
+                const data = JSON.parse(readFileSync(path, 'utf-8'));
+                if (data.marks.length > 0)
+                    result[docFilename] = data.marks;
+            }
+            catch { /* skip corrupt files */ }
+        }
+    }
+    catch { /* dir doesn't exist yet */ }
+    return result;
+}
+export function getMarkCount(filename) {
+    return readMarkFile(filename).marks.length;
+}
+/** Count marks across all documents, optionally excluding one filename. */
+export function getGlobalMarkSummary(excludeFilename) {
+    ensureMarksDir();
+    let totalMarks = 0;
+    let docCount = 0;
+    try {
+        const files = readdirSync(getMarksDir());
+        for (const file of files) {
+            if (!file.endsWith('.json'))
+                continue;
+            if (excludeFilename) {
+                const safe = excludeFilename.replace(/[/\\]/g, '_');
+                if (file === `${safe}.json`)
+                    continue;
+            }
+            const path = join(getMarksDir(), file);
+            try {
+                const data = JSON.parse(readFileSync(path, 'utf-8'));
+                if (data.marks.length > 0) {
+                    totalMarks += data.marks.length;
+                    docCount++;
+                }
+            }
+            catch { /* skip */ }
+        }
+    }
+    catch { /* dir doesn't exist */ }
+    return { totalMarks, docCount };
+}
+export function editMark(filename, id, note) {
+    const data = readMarkFile(filename);
+    const mark = data.marks.find((m) => m.id === id);
+    if (!mark)
+        return null;
+    mark.note = note;
+    writeMarkFile(filename, data);
+    return mark;
+}
+export function resolveMarks(ids) {
+    const idSet = new Set(ids);
+    const resolved = [];
+    ensureMarksDir();
+    try {
+        const files = readdirSync(getMarksDir());
+        for (const file of files) {
+            if (!file.endsWith('.json'))
+                continue;
+            const filePath = join(getMarksDir(), file);
+            try {
+                const data = JSON.parse(readFileSync(filePath, 'utf-8'));
+                const before = data.marks.length;
+                data.marks = data.marks.filter((m) => {
+                    if (idSet.has(m.id)) {
+                        resolved.push(m.id);
+                        return false;
+                    }
+                    return true;
+                });
+                if (data.marks.length !== before) {
+                    const docFilename = file.replace(/\.json$/, '').replace(/_/g, ' ');
+                    writeMarkFile(docFilename, data);
+                }
+            }
+            catch { /* skip */ }
+        }
+    }
+    catch { /* dir doesn't exist */ }
+    return resolved;
+}
+export function pruneStaleMarks(filename, validNodeIds) {
+    const data = readMarkFile(filename);
+    if (data.marks.length === 0)
+        return 0;
+    const validSet = new Set(validNodeIds);
+    const before = data.marks.length;
+    data.marks = data.marks.filter((m) => {
+        // Multi-node mark: keep if ANY nodeId is still valid
+        if (m.nodeIds && m.nodeIds.length > 0) {
+            return m.nodeIds.some((id) => validSet.has(id));
+        }
+        return validSet.has(m.nodeId);
+    });
+    const pruned = before - data.marks.length;
+    if (pruned > 0)
+        writeMarkFile(filename, data);
+    return pruned;
+}
+/** Rename a mark sidecar file when a document is renamed. */
+export function renameMark(oldFilename, newFilename) {
+    const oldPath = markFilePath(oldFilename);
+    if (!existsSync(oldPath))
+        return;
+    const newPath = markFilePath(newFilename);
+    renameSync(oldPath, newPath);
+}

package/dist/server/mcp.js

@@ -23,7 +23,7 @@ import { readFrontmatter, writeFrontmatter, computeBacklinksFor, invalidateBackl
 import { logger, generateRequestId, withRequestId } from './logger.js';
 import { broadcastDocumentSwitched, broadcastDocumentsChanged, broadcastWorkspacesChanged, broadcastTitleChanged, broadcastMetadataChanged, broadcastPendingDocsChanged, broadcastPendingMetadataChanged, broadcastWritingStarted, broadcastWritingFinished, broadcastCommentsChanged, broadcastActivityEvent } from './ws.js';
 import { listWorkspaces, getWorkspace, getDocTitle, getItemContext, addDoc, updateWorkspaceContext, createWorkspace, deleteWorkspace, addContainerToWorkspace, findOrCreateWorkspace, findOrCreateContainer, moveDoc, moveContainer, reorderWorkspaceAfter, removeContainer, renameWorkspace, renameContainer, removeDocFromAllWorkspaces, findWorkspacesContainingDoc, collectFilesInWorkspace } from './workspaces.js';
-import { findDocNode } from './workspace-tree.js';
+import { findDocNode, findContainer } from './workspace-tree.js';
 import { importGoogleDoc } from './gdoc-import.js';
 import { toCompactFormat, compactNodes, parseMarkdownContent } from './compact.js';
 import matter from 'gray-matter';
@@ -484,12 +484,14 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'create_document',
-        description: 'Create a new document. content_type is REQUIRED — use "document" for plain docs, or "tweet"/"reply"/"quote"/"article"/"linkedin"/"newsletter"/"blog" for typed docs. Always provide a title. By default shows a sidebar spinner — call populate_document next to deliver content and clear it. This two-step flow is REQUIRED for all content documents: create_document → populate_document. Use empty=true ONLY for typed docs (tweets, articles) that start blank and get written to incrementally via write_to_pad. If workspace is provided, the doc is automatically added to it (workspace is created if it doesn\'t exist). If container is also provided, the doc is placed inside that container (created if it doesn\'t exist).',
+        description: 'Create a new document. content_type is REQUIRED — use "document" for plain docs, or "tweet"/"reply"/"quote"/"article"/"linkedin"/"newsletter"/"blog" for typed docs. Always provide a title. By default shows a sidebar spinner — call populate_document next to deliver content and clear it. This two-step flow is REQUIRED for all content documents: create_document → populate_document. Use empty=true ONLY for typed docs (tweets, articles) that start blank and get written to incrementally via write_to_pad. Placement accepts EITHER convention: name-based auto-create (workspace title + container name, created if absent) OR id-based targeting of existing items (workspaceFile + containerId, the same ids move_item/get_workspace_structure use). A placement param that cannot be honored (unknown workspaceFile/containerId, or a container with no workspace) is a hard error — the doc is never silently created unplaced. The result always states where the doc landed, or "UNFILED".',
         schema: {
             title: z.string().optional().describe('Title for the new document. Defaults to "Untitled".'),
             path: z.string().optional().describe('Absolute file path to create the document at (e.g. "C:/projects/doc.md"). If omitted, creates in ~/.openwriter/.'),
             workspace: z.string().optional().describe('Workspace title to add this doc to. Creates the workspace if it doesn\'t exist.'),
             container: z.string().optional().describe('Container name within the workspace (e.g. "Chapters", "Notes", "References"). Creates the container if it doesn\'t exist. Requires workspace.'),
+            workspaceFile: z.string().optional().describe('Existing workspace by manifest filename (the *.json id used by move_item / get_workspace_structure). Id-based alternative to "workspace" (title). Must already exist — errors if not found. Use when you already hold the workspaceFile from another tool.'),
+            containerId: z.string().optional().describe('Existing container by id (8-char hex, as used by move_item / get_workspace_structure). Id-based alternative to "container" (name). Must already exist in the resolved workspace — errors if not found. Requires a workspace (workspaceFile or workspace).'),
             empty: z.boolean().optional().describe('ONLY for content_type template docs (tweets, articles) that start blank. Skips the spinner and switches immediately. Do NOT set this for content documents — use the two-step flow (create_document → populate_document) instead.'),
             content_type: z.enum(['document', 'tweet', 'reply', 'quote', 'article', 'linkedin', 'newsletter', 'blog', 'manuscript']).describe('Required. Use "document" for plain documents. Tweet/reply/quote/article/linkedin/newsletter/blog set type-specific metadata automatically. "manuscript" = a binding doc whose body is an ordered list of [text](doc:ID) pointers under ## chapter headings; populate it with the manifest, then it compiles to EPUB/DOCX via the manuscript routes.'),
             url: z.string().optional().describe('Tweet URL — REQUIRED for content_type "reply" or "quote" (e.g. "https://x.com/user/status/123"). Sets tweetContext.url automatically. Ignored for other content types.'),
@@ -498,7 +500,7 @@ export const TOOL_REGISTRY = [
             masterDocId: z.string().optional().describe('Make this doc a VARIANT of another doc. Pass the master doc\'s docId (8-char hex). The variant nests under its master in the sidebar (expandable tree). Use when creating a derivative — e.g. a tweet thread from a blog post. Pair with variantType. See docs/variants.md.'),
             variantType: z.string().optional().describe('Label for what kind of variant this is (e.g. "tweet", "blog", "linkedin"). Shows as a badge in the sidebar. Only meaningful alongside masterDocId.'),
         },
-        handler: async ({ title, path, workspace, container, empty, content_type, url, afterId, status, masterDocId, variantType }) => {
+        handler: async ({ title, path, workspace, container, workspaceFile, containerId, empty, content_type, url, afterId, status, masterDocId, variantType }) => {
             // Require url for reply/quote
             if ((content_type === 'reply' || content_type === 'quote') && !url) {
                 return { content: [{ type: 'text', text: `Error: content_type "${content_type}" requires a url parameter (e.g. "https://x.com/user/status/123").` }] };
@@ -511,17 +513,69 @@ export const TOOL_REGISTRY = [
                 };
                 title = typeDefaults[content_type];
             }
-            // Resolve workspace/container up front so spinner renders in the right place
+            // Resolve placement up front so the spinner renders in the right place.
+            // Accept BOTH addressing conventions: the id-based one used across the rest
+            // of the API (workspaceFile + containerId, targeting EXISTING items) and the
+            // name-based auto-create one (workspace title + container name). Whichever is
+            // given is resolved; a placement param that cannot be honored is a HARD ERROR
+            // rather than a silent drop that orphans the doc.
+            // adr: adr/create-document-placement-contract.md
             let wsTarget;
-            if (workspace) {
-                const ws = findOrCreateWorkspace(workspace);
-                let containerId = null;
-                if (container) {
-                    const c = findOrCreateContainer(ws.filename, container);
-                    containerId = c.containerId;
+            if (workspace || workspaceFile || container || containerId) {
+                // 1. Resolve the workspace. Prefer the explicit id (workspaceFile).
+                let wsFilenameResolved = null;
+                if (workspaceFile) {
+                    try {
+                        getWorkspace(workspaceFile);
+                    }
+                    catch {
+                        return { content: [{ type: 'text', text: `Error: create_document workspaceFile "${workspaceFile}" not found. Pass an existing workspace .json filename, or use "workspace" (title) to create one by name.` }] };
+                    }
+                    wsFilenameResolved = workspaceFile;
+                }
+                else if (workspace) {
+                    wsFilenameResolved = findOrCreateWorkspace(workspace).filename;
+                }
+                // 2. A container was requested but the workspace couldn't be resolved.
+                //    Previously silently dropped — now a hard error.
+                if ((container || containerId) && !wsFilenameResolved) {
+                    return { content: [{ type: 'text', text: `Error: create_document was given a container but no workspace. Pass "workspaceFile" (existing) or "workspace" (title, auto-created) alongside the container.` }] };
+                }
+                // 3. Resolve the container within that workspace.
+                let resolvedContainerId = null;
+                if (wsFilenameResolved) {
+                    if (containerId) {
+                        const wsObj = getWorkspace(wsFilenameResolved);
+                        if (!findContainer(wsObj.root, containerId)) {
+                            return { content: [{ type: 'text', text: `Error: create_document containerId "${containerId}" not found in workspace ${wsFilenameResolved}. Pass an existing containerId, or use "container" (name) to create one.` }] };
+                        }
+                        resolvedContainerId = containerId;
+                    }
+                    else if (container) {
+                        resolvedContainerId = findOrCreateContainer(wsFilenameResolved, container).containerId;
+                    }
+                    wsTarget = { wsFilename: wsFilenameResolved, containerId: resolvedContainerId };
+                    broadcastWorkspacesChanged(); // Browser sees container structure before spinner
+                }
+            }
+            // Always state the final placement in the result, so a doc that lands in no
+            // workspace says so loudly (UNFILED) — an unplaced doc can never read as a
+            // bland success again. adr: brief 2026-07-09-create-document-placement-contract.
+            let placement = ' (UNFILED — not added to any workspace; lives at ~/.openwriter)';
+            if (wsTarget) {
+                let wsLabel = wsTarget.wsFilename;
+                let cLabel = '';
+                try {
+                    const wsObj = getWorkspace(wsTarget.wsFilename);
+                    wsLabel = wsObj.title || wsTarget.wsFilename;
+                    if (wsTarget.containerId) {
+                        const found = findContainer(wsObj.root, wsTarget.containerId);
+                        if (found)
+                            cLabel = ` / ${found.node.name}`;
+                    }
                 }
-                wsTarget = { wsFilename: ws.filename, containerId };
-                broadcastWorkspacesChanged(); // Browser sees container structure before spinner
+                catch { /* keep filename */ }
+                placement = ` → workspace "${wsLabel}"${cLabel}`;
             }
             // Track the spinner key so catch can clear exactly this entry
             // (not siblings from a concurrent declare_writes).
@@ -552,13 +606,11 @@ export const TOOL_REGISTRY = [
                             Object.assign(initMeta, typeMeta);
                     }
                     setMetadata(initMeta);
-                    let wsInfo = '';
                     if (wsTarget) {
                         // Resolve afterId: it may be a docId (8-char hex) or containerId.
                         // filenameByDocId resolves docId→filename; if null, treat as containerId.
                         const afterRef = afterId ? (filenameByDocId(afterId) ?? afterId) : null;
                         addDoc(wsTarget.wsFilename, wsTarget.containerId, result.filename, result.title, afterRef);
-                        wsInfo = ` → workspace "${workspace}"${container ? ` / ${container}` : ''}`;
                     }
                     const newDocId = getDocId();
                     save('agent');
@@ -576,7 +628,7 @@ export const TOOL_REGISTRY = [
                     return {
                         content: [{
                                 type: 'text',
-                                text: `Created "${result.title}" [${newDocId}]${wsInfo}${content_type ? ` (${content_type})` : ''} — ready.`,
+                                text: `Created "${result.title}" [${newDocId}]${placement}${content_type ? ` (${content_type})` : ''} — ready.`,
                             }],
                     };
                 }
@@ -587,11 +639,9 @@ export const TOOL_REGISTRY = [
                 const typeMeta = content_type ? resolveTypeMeta(content_type, url) : undefined;
                 const initialMeta = { ...statusMeta, ...variantMeta, ...(typeMeta || {}) };
                 const result = createDocumentFile(title, path, initialMeta);
-                let wsInfo = '';
                 if (wsTarget) {
                     const afterRef = afterId ? (filenameByDocId(afterId) ?? afterId) : null;
                     addDoc(wsTarget.wsFilename, wsTarget.containerId, result.filename, result.title, afterRef);
-                    wsInfo = ` → workspace "${workspace}"${container ? ` / ${container}` : ''}`;
                 }
                 // Broadcast spinner keyed by filename so populate_document can clear exactly
                 // this entry. Fires after the file exists, so documents-changed arrives with
@@ -610,7 +660,7 @@ export const TOOL_REGISTRY = [
                 return {
                     content: [{
                             type: 'text',
-                            text: `Created "${result.title}" [${result.docId}]${wsInfo} — empty. Call populate_document with docId "${result.docId}" to add content.`,
+                            text: `Created "${result.title}" [${result.docId}]${placement} — empty. Call populate_document with docId "${result.docId}" to add content.`,
                         }],
                 };
             }

package/dist/server/sync-routes.js

@@ -0,0 +1,75 @@
+/**
+ * Express routes for GitHub sync.
+ * Mounted in index.ts — follows version-routes.ts pattern.
+ */
+import { Router } from 'express';
+import { getSyncStatus, getCapabilities, getPendingFiles, setupWithGh, setupWithPat, connectExisting, pushSync, } from './git-sync.js';
+export function createSyncRouter(broadcastSyncStatus) {
+    const router = Router();
+    router.get('/api/sync/status', async (_req, res) => {
+        try {
+            res.json(await getSyncStatus());
+        }
+        catch (err) {
+            res.status(500).json({ state: 'error', error: err.message });
+        }
+    });
+    router.get('/api/sync/capabilities', async (_req, res) => {
+        try {
+            res.json(await getCapabilities());
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+    router.get('/api/sync/pending', async (_req, res) => {
+        try {
+            res.json(await getPendingFiles());
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+    router.post('/api/sync/setup', async (req, res) => {
+        try {
+            const { method, repoName, remoteUrl, pat, isPrivate } = req.body;
+            if (method === 'gh') {
+                await setupWithGh(repoName || 'openwriter-docs', isPrivate !== false);
+            }
+            else if (method === 'pat') {
+                if (!pat) {
+                    res.status(400).json({ error: 'PAT is required' });
+                    return;
+                }
+                await setupWithPat(pat, repoName || 'openwriter-docs', isPrivate !== false);
+            }
+            else if (method === 'connect') {
+                if (!remoteUrl) {
+                    res.status(400).json({ error: 'Remote URL is required' });
+                    return;
+                }
+                await connectExisting(remoteUrl, pat);
+            }
+            else {
+                res.status(400).json({ error: 'Invalid method. Use: gh, pat, or connect' });
+                return;
+            }
+            const status = await getSyncStatus();
+            broadcastSyncStatus(status);
+            res.json({ success: true, status });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+    router.post('/api/sync/push', async (_req, res) => {
+        try {
+            const result = await pushSync(broadcastSyncStatus);
+            res.json(result);
+        }
+        catch (err) {
+            res.status(500).json({ state: 'error', error: err.message });
+        }
+    });
+    return router;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openwriter",
-  "version": "0.40.2",
+  "version": "0.40.3",
   "description": "The open-source writing surface for AI agents. Markdown-native editor with pending change review — your agent writes, you accept or reject.",
   "type": "module",
   "license": "MIT",

package/skill/SKILL.md

@@ -16,7 +16,7 @@ description: |
   Requires: OpenWriter MCP server configured. Browser UI at localhost:5050.
 metadata:
   author: travsteward
-  version: "0.18.0"
+  version: "0.19.0"
   repository: https://github.com/travsteward/openwriter
 license: MIT
 ---
@@ -201,7 +201,7 @@ Every document has an immutable **docId** (8-char hex, e.g. `a1b2c3d4`) in its Y
 | `delete_container` | Delete a container from a workspace (doc files stay on disk) |
 | `tag_doc` | Add a tag to a document by docId (stored in doc frontmatter) |
 | `untag_doc` | Remove a tag from a document by docId |
-| `move_item` | Move or reorder a doc, container, or workspace (type: doc/container/workspace) |
+| `move_item` | Move or reorder a doc, container, or workspace (type: doc/container/workspace). To nest a doc into a container: `move_item({ type: 'doc', workspaceFile, itemId: <docId>, targetContainerId: <containerId>, afterId? })`. The target param is **`targetContainerId`** — passing `containerId`/`container` instead is silently ignored and the doc lands at workspace root. |
 | `rename_item` | Rename a workspace, container, or document (type: workspace/container/document) |
 
 ### Enrichment (three-field schema — v0.19.0)
@@ -328,21 +328,29 @@ The user can turn on **auto-accept** on a per-doc basis (right-click the doc in
 
 ### Workspace-Integrated Creation
 
-`create_document` accepts optional `workspace` and `container` parameters for direct workspace placement:
+`create_document` takes placement in **either** convention (unified 2026-07-09):
 
 ```
 create_document({
   title: "Opening Chapter",
   content_type: "document",          ← REQUIRED: "document" for plain, or "tweet"/"article"/etc.
-  workspace: "The Immortal",        ← creates workspace if it doesn't exist
-  container: "Chapters"             ← creates container if it doesn't exist
+  workspace: "The Immortal",        ← name-based: creates workspace if it doesn't exist
+  container: "Chapters"             ← name-based: creates container if it doesn't exist
 })
 ```
 
+**Name-based (auto-create):**
 - **`workspace`** (string) — workspace title to add the doc to. Auto-creates if not found (case-insensitive match).
 - **`container`** (string) — container name within the workspace (e.g. "Chapters", "Notes", "References"). Auto-creates if not found. Requires `workspace`.
-- **`afterId`** (string, optional) — docId (8-char hex) or containerId to place the new doc immediately after. Omit and the doc lands at the **bottom** of its parent (the default since 0.18.0, matching the ascending-order convention: oldest at top, newest at bottom). Use `afterId` when you need surgical placement — e.g. inserting a new chapter doc immediately after the chapter's Beats doc.
-- All three are optional — omit `workspace` for standalone docs outside any workspace.
+
+**Id-based (target existing items — the same ids `move_item`/`get_workspace_structure` use):**
+- **`workspaceFile`** (string) — existing workspace manifest filename (`*.json`). Must already exist. Alternative to `workspace`.
+- **`containerId`** (string) — existing container id (8-char hex). Must already exist in the resolved workspace. Alternative to `container`. Requires a workspace param.
+
+**Both conventions:**
+- **`afterId`** (string, optional) — docId (8-char hex) or containerId to place the new doc immediately after. Omit and the doc lands at the **bottom** of its parent (the default since 0.18.0, matching the ascending-order convention: oldest at top, newest at bottom). `afterId` alone does NOT set a workspace — pass a workspace param too.
+- Omit all placement params for a standalone doc — the result then says **UNFILED** (a doc created in no workspace announces it, rather than reading as a bland success).
+- A placement that can't be honored (unknown `workspaceFile`/`containerId`, or a container with no workspace) is a **hard error** — the doc is never silently created unplaced. The result always states where it landed.
 
 This eliminates the need for separate `create_workspace`, `create_container`, and `move_item` calls when building up a workspace. The default-bottom landing also eliminates the need for a follow-up `move_item` pass to fix sidebar order after every create — the doc lands in convention position the first time.