diff --git a/scaffold/pm-api/sql/009-doc-versioning.sql b/scaffold/pm-api/sql/009-doc-versioning.sql
new file mode 100644
index 00000000..f7503de4
--- /dev/null
+++ b/scaffold/pm-api/sql/009-doc-versioning.sql
@@ -0,0 +1,6 @@
+-- Migration 009: Add version column to docs for optimistic locking
+-- Prevents silent data loss when multiple users edit the same document simultaneously.
+-- Strategy: version-based (integer increment), not CRDT.
+-- On save: WHERE version = ? + increment. If 0 rows updated → 409 Conflict.
+
+ALTER TABLE docs ADD COLUMN version INTEGER NOT NULL DEFAULT 1;
diff --git a/scaffold/pm-api/src/routes/v2-docs.ts b/scaffold/pm-api/src/routes/v2-docs.ts
index d7b6bf25..338d138f 100644
--- a/scaffold/pm-api/src/routes/v2-docs.ts
+++ b/scaffold/pm-api/src/routes/v2-docs.ts
@@ -10,7 +10,7 @@ app.get('/', async (c) => {
   return c.json({ docs: rows })
 })
 
-// GET /:id - document detail
+// GET /:id - document detail (includes version for optimistic locking)
 app.get('/:id', async (c) => {
   const id = c.req.param('id')
   const { rows } = await queryOrThrow('SELECT * FROM docs WHERE id = ?', [id])
@@ -18,17 +18,51 @@ app.get('/:id', async (c) => {
   return c.json({ doc: rows[0] })
 })
 
-// PUT /:id - create/update document
+// PUT /:id - create/update document with optimistic locking
+// Body: { title, content, version? }
+// - New doc (INSERT): version is ignored; server sets version = 1
+// - Existing doc (UPDATE): must supply version matching current row
+//   → 409 Conflict if version mismatch (someone else saved in between)
 app.put('/:id', async (c) => {
   const id = c.req.param('id')
-  const body = await c.req.json<{ title: string; content: string }>()
+  const body = await c.req.json<{ title: string; content: string; version?: number }>()
   const createdBy = c.get('userName') || 'unknown'
-  await executeOrThrow(
-    `INSERT INTO docs (id, title, content, created_by) VALUES (?, ?, ?, ?)
-     ON CONFLICT(id) DO UPDATE SET title = excluded.title, content = excluded.content, updated_at = CURRENT_TIMESTAMP`,
-    [id, body.title, body.content, createdBy],
+
+  // Check if doc already exists
+  const { rows } = await queryOrThrow('SELECT version FROM docs WHERE id = ?', [id])
+
+  if (rows.length === 0) {
+    // New document — INSERT with version = 1
+    await executeOrThrow(
+      `INSERT INTO docs (id, title, content, created_by, version) VALUES (?, ?, ?, ?, 1)`,
+      [id, body.title, body.content, createdBy],
+    )
+    return c.json({ ok: true, version: 1 })
+  }
+
+  // Existing document — optimistic locking
+  const currentVersion = (rows[0] as { version: number }).version ?? 1
+  const clientVersion = body.version
+
+  if (clientVersion === undefined || clientVersion === null) {
+    return c.json({ error: 'version required for optimistic locking' }, 400)
+  }
+
+  // Versioned save: only update if version matches
+  const result = await executeOrThrow(
+    `UPDATE docs SET title = ?, content = ?, updated_at = CURRENT_TIMESTAMP, version = version + 1
+     WHERE id = ? AND version = ?`,
+    [body.title, body.content, id, clientVersion],
   )
-  return c.json({ ok: true })
+
+  if (result.rowsAffected === 0) {
+    return c.json(
+      { error: 'conflict', message: 'Document was modified by another user', currentVersion },
+      409,
+    )
+  }
+
+  return c.json({ ok: true, version: currentVersion + 1 })
 })
 
 export default app
diff --git a/scaffold/spec-site/src/App.vue b/scaffold/spec-site/src/App.vue
index 5b4a4484..9714a348 100644
--- a/scaffold/spec-site/src/App.vue
+++ b/scaffold/spec-site/src/App.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import AppHeader from './components/AppHeader.vue'
 import MemoSidebar from './components/MemoSidebar.vue'
+import ConfirmDialog from './components/ConfirmDialog.vue'
 </script>
 
 <template>
@@ -10,6 +11,7 @@ import MemoSidebar from './components/MemoSidebar.vue'
       <router-view />
     </main>
     <MemoSidebar />
+    <ConfirmDialog />
   </div>
 </template>
 
diff --git a/scaffold/spec-site/src/api/client.ts b/scaffold/spec-site/src/api/client.ts
index 091ff3de..0569aac3 100644
--- a/scaffold/spec-site/src/api/client.ts
+++ b/scaffold/spec-site/src/api/client.ts
@@ -113,9 +113,10 @@ async function apiMutate<T>(
       signal: AbortSignal.timeout(5000),
     })
     if (!resp.ok) {
-      const text = await resp.text().catch(() => '')
       if (resp.status !== 401 && resp.status !== 403 && _reachable === null) _reachable = false
-      return { error: `HTTP ${resp.status}: ${text}` }
+      // Try to parse structured error body (e.g. 409 conflict payloads)
+      const errorData = await resp.json().catch(() => null)
+      return { error: `HTTP ${resp.status}`, data: errorData ?? undefined }
     }
     _reachable = true
     const data = await resp.json()
diff --git a/scaffold/spec-site/src/components/ConfirmDialog.vue b/scaffold/spec-site/src/components/ConfirmDialog.vue
new file mode 100644
index 00000000..0a37af0f
--- /dev/null
+++ b/scaffold/spec-site/src/components/ConfirmDialog.vue
@@ -0,0 +1,99 @@
+<script setup lang="ts">
+import { useConfirm } from '@/composables/useConfirm'
+
+const { visible, title, message, confirmText, cancelText, isAlertMode, onConfirm, onCancel } = useConfirm()
+</script>
+
+<template>
+  <Teleport to="body">
+    <Transition name="modal-fade">
+      <div v-if="visible" class="modal-overlay" @click.self="isAlertMode ? onConfirm() : onCancel()">
+        <div class="modal-card" role="dialog" :aria-modal="true" aria-labelledby="confirm-dialog-title">
+          <p v-if="title" id="confirm-dialog-title" class="modal-title">{{ title }}</p>
+          <p class="modal-message">{{ message }}</p>
+          <div class="modal-actions">
+            <button v-if="!isAlertMode" class="btn-cancel" @click="onCancel">{{ cancelText }}</button>
+            <button class="btn-confirm" @click="onConfirm">{{ confirmText }}</button>
+          </div>
+        </div>
+      </div>
+    </Transition>
+  </Teleport>
+</template>
+
+<style scoped>
+.modal-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.45);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 9999;
+}
+
+.modal-card {
+  background: var(--card-bg);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  box-shadow: var(--shadow-md);
+  padding: 24px;
+  min-width: 320px;
+  max-width: 480px;
+  width: 90%;
+}
+
+.modal-title {
+  font-weight: 600;
+  font-size: 1rem;
+  color: var(--text-primary);
+  margin: 0 0 8px 0;
+}
+
+.modal-message {
+  font-size: 0.9rem;
+  color: var(--text-secondary);
+  margin: 0 0 20px 0;
+  line-height: 1.5;
+}
+
+.modal-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 8px;
+}
+
+.btn-cancel {
+  padding: 7px 16px;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  background: transparent;
+  color: var(--text-secondary);
+  font-size: 0.875rem;
+  cursor: pointer;
+  transition: background 0.15s;
+}
+.btn-cancel:hover { background: var(--border-light); }
+
+.btn-confirm {
+  padding: 7px 16px;
+  border: none;
+  border-radius: var(--radius-sm);
+  background: var(--primary);
+  color: #fff;
+  font-size: 0.875rem;
+  cursor: pointer;
+  transition: background 0.15s;
+}
+.btn-confirm:hover { background: var(--primary-dark); }
+
+/* Transition */
+.modal-fade-enter-active,
+.modal-fade-leave-active {
+  transition: opacity 0.15s ease;
+}
+.modal-fade-enter-from,
+.modal-fade-leave-to {
+  opacity: 0;
+}
+</style>
diff --git a/scaffold/spec-site/src/components/DocComments.vue b/scaffold/spec-site/src/components/DocComments.vue
index 68fa6845..43bbf3fb 100644
--- a/scaffold/spec-site/src/components/DocComments.vue
+++ b/scaffold/spec-site/src/components/DocComments.vue
@@ -1,6 +1,9 @@
 <script setup lang="ts">
 import { ref, onMounted } from 'vue'
 import { apiGet, apiPost, apiPatch, apiDelete } from '@/composables/useTurso'
+import { useConfirm } from '@/composables/useConfirm'
+
+const { showConfirm } = useConfirm()
 
 interface Comment {
   id: number; doc_id: string; parent_id: number | null; author: string; content: string; created_at: string; updated_at: string
@@ -49,7 +52,7 @@ async function saveEdit() {
 }
 
 async function remove(id: number) {
-  if (!confirm('Delete this comment?')) return
+  if (!await showConfirm('Delete this comment?')) return
   await apiDelete(`/api/v2/docs/comments/${id}`)
   await load()
 }
diff --git a/scaffold/spec-site/src/components/DocsSidebar.vue b/scaffold/spec-site/src/components/DocsSidebar.vue
index 1a4db99a..57b5e0b4 100644
--- a/scaffold/spec-site/src/components/DocsSidebar.vue
+++ b/scaffold/spec-site/src/components/DocsSidebar.vue
@@ -2,6 +2,9 @@
 import { ref, computed, onMounted, onUnmounted } from 'vue'
 import { useRouter } from 'vue-router'
 import { apiGet, apiPut, apiPatch } from '@/composables/useTurso'
+import { useConfirm } from '@/composables/useConfirm'
+
+const { showConfirm, showAlert } = useConfirm()
 import TreeNode from './TreeNode.vue'
 import Icon from './Icon.vue'
 
@@ -93,12 +96,12 @@ async function bulkUploadMd(e: Event) {
   input.value = ''
   const failed = fileArr.length - count
   uploadProgress.value = { current: 0, total: 0 }
-  alert(`${count} uploaded successfully${failed ? `, ${failed} failed` : ''}`)
+  await showAlert(`${count} uploaded successfully${failed ? `, ${failed} failed` : ''}`)
   await loadTree()
 }
 
 async function ctxDelete() {
-  if (!ctxMenu.value || !confirm('Delete this document?')) return
+  if (!ctxMenu.value || !await showConfirm('Delete this document?')) return
   await apiPatch(`/api/v2/docs/${ctxMenu.value.node.id}`, { archived: 1 })
   closeCtxMenu(); await loadTree()
 }
diff --git a/scaffold/spec-site/src/components/MemoRelations.vue b/scaffold/spec-site/src/components/MemoRelations.vue
index 60f888d5..c767100b 100644
--- a/scaffold/spec-site/src/components/MemoRelations.vue
+++ b/scaffold/spec-site/src/components/MemoRelations.vue
@@ -2,6 +2,9 @@
 import { ref, onMounted } from 'vue'
 import { useRouter } from 'vue-router'
 import { apiGet, apiPost, apiDelete } from '@/composables/useTurso'
+import { useConfirm } from '@/composables/useConfirm'
+
+const { showConfirm } = useConfirm()
 
 interface Relation { id: number; source_memo_id: number; target_memo_id: number; relation_type: string; created_by: string }
 
@@ -36,7 +39,7 @@ async function addRelation(targetId: number) {
 }
 
 async function removeRelation(relId: number) {
-  if (!confirm('Delete this relation?')) return
+  if (!await showConfirm('Delete this relation?')) return
   await apiDelete(`/api/v2/memos/relations/${relId}`)
   await loadRelations()
 }
diff --git a/scaffold/spec-site/src/composables/useConfirm.ts b/scaffold/spec-site/src/composables/useConfirm.ts
new file mode 100644
index 00000000..8ac76898
--- /dev/null
+++ b/scaffold/spec-site/src/composables/useConfirm.ts
@@ -0,0 +1,79 @@
+/**
+ * useConfirm — programmatic confirm/alert dialog
+ *
+ * Singleton pattern: module-level state, shared across all consumers.
+ * Works both inside Vue components and in plain TS modules (e.g. TipTap extensions).
+ *
+ * Usage:
+ *   const { showConfirm, showAlert } = useConfirm()
+ *   const ok = await showConfirm('Delete this item?')
+ *   if (!ok) return
+ *   await showAlert('Done!')
+ */
+
+import { ref } from 'vue'
+
+// Module-level singletons
+const visible = ref(false)
+const title = ref('')
+const message = ref('')
+const confirmText = ref('OK')
+const cancelText = ref('Cancel')
+const isAlertMode = ref(false)
+
+let _resolve: (val: boolean) => void = () => {}
+
+export interface ConfirmOptions {
+  title?: string
+  confirmText?: string
+  cancelText?: string
+}
+
+export function useConfirm() {
+  function showConfirm(msg: string, opts: ConfirmOptions = {}): Promise<boolean> {
+    return new Promise<boolean>(resolve => {
+      title.value = opts.title ?? ''
+      message.value = msg
+      confirmText.value = opts.confirmText ?? 'Confirm'
+      cancelText.value = opts.cancelText ?? 'Cancel'
+      isAlertMode.value = false
+      visible.value = true
+      _resolve = resolve
+    })
+  }
+
+  function showAlert(msg: string, opts: ConfirmOptions = {}): Promise<void> {
+    return new Promise<void>(resolve => {
+      title.value = opts.title ?? ''
+      message.value = msg
+      confirmText.value = opts.confirmText ?? 'OK'
+      cancelText.value = ''
+      isAlertMode.value = true
+      visible.value = true
+      _resolve = () => resolve()
+    })
+  }
+
+  function onConfirm() {
+    visible.value = false
+    _resolve(true)
+  }
+
+  function onCancel() {
+    visible.value = false
+    _resolve(false)
+  }
+
+  return {
+    visible,
+    title,
+    message,
+    confirmText,
+    cancelText,
+    isAlertMode,
+    showConfirm,
+    showAlert,
+    onConfirm,
+    onCancel,
+  }
+}
diff --git a/scaffold/spec-site/src/pages/DocsEditor.vue b/scaffold/spec-site/src/pages/DocsEditor.vue
index 3860caa4..3a666fdf 100644
--- a/scaffold/spec-site/src/pages/DocsEditor.vue
+++ b/scaffold/spec-site/src/pages/DocsEditor.vue
@@ -12,13 +12,16 @@ const isNew = computed(() => !docId.value)
 const title = ref('')
 const content = ref('')
 const saving = ref(false)
+const docVersion = ref<number | undefined>(undefined)
+const conflictError = ref('')
 
 onMounted(async () => {
   if (docId.value) {
-    const { data } = await apiGet<{ doc: { title: string; content: string } }>(`/api/v2/docs/${docId.value}`)
+    const { data } = await apiGet<{ doc: { title: string; content: string; version?: number } }>(`/api/v2/docs/${docId.value}`)
     if (data?.doc) {
       title.value = data.doc.title
       content.value = data.doc.content
+      docVersion.value = data.doc.version
     }
   }
 })
@@ -30,14 +33,28 @@ function generateId(title: string): string {
 async function save() {
   if (!title.value.trim()) { alert('Please enter a title'); return }
   saving.value = true
+  conflictError.value = ''
   const id = docId.value || generateId(title.value)
-  const { error } = await apiPut(`/api/v2/docs/${id}`, { title: title.value, content: content.value })
+  const { data, error } = await apiPut<{ ok: boolean; version?: number }>(`/api/v2/docs/${id}`, {
+    title: title.value,
+    content: content.value,
+    version: docVersion.value,
+  })
   saving.value = false
+
+  if ((data as any)?.error === 'conflict' || error?.includes('HTTP 409')) {
+    conflictError.value = 'Someone else edited this document while you were working. Please refresh the page to get the latest version, then re-apply your changes.'
+    return
+  }
   if (error) { alert(error); return }
+
+  // Update local version from server response
+  if (data?.version !== undefined) {
+    docVersion.value = data.version
+  }
+
   router.push(`/docs/${id}`)
 }
-
-// renderMarkdown imported from @/utils/markdown
 </script>
 
 <template>
@@ -52,6 +69,10 @@ async function save() {
       </div>
     </div>
 
+    <div v-if="conflictError" class="conflict-banner">
+      ⚠️ {{ conflictError }}
+    </div>
+
     <input
       v-model="title"
       class="editor-title"
@@ -81,6 +102,12 @@ async function save() {
 .editor-header h1 { font-size: 20px; font-weight: 700; }
 .editor-actions { display: flex; gap: 8px; }
 
+.conflict-banner {
+  background: #fef3c7; border: 1px solid #f59e0b; border-radius: 8px;
+  padding: 12px 16px; margin-bottom: 16px; font-size: 14px; color: #92400e;
+  line-height: 1.5;
+}
+
 .editor-title {
   width: 100%; padding: 12px 16px; font-size: 18px; font-weight: 600;
   border: 1px solid rgba(0,0,0,0.1); border-radius: 12px; margin-bottom: 16px;