collabmd 0.1.51 → 0.1.52

package/src/client/styles/surfaces/landing-page.css

@@ -0,0 +1,260 @@
+/* Standalone landing page. Loaded only by landing/styles.css. */
+:root {
+  --landing-font: 'Avenir Next', 'Segoe UI', system-ui, sans-serif;
+  --landing-mono: ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace;
+}
+
+*, *::before, *::after { box-sizing: border-box; }
+* { margin: 0; }
+html { scroll-behavior: smooth; scroll-padding-top: 96px; }
+body { background: var(--color-bg); color: var(--color-text); font: 16px/1.65 var(--landing-font); -webkit-font-smoothing: antialiased; }
+a { color: inherit; text-decoration: none; }
+button { font: inherit; cursor: pointer; }
+img, video { display: block; width: 100%; height: auto; }
+svg { display: block; }
+button, a { -webkit-tap-highlight-color: transparent; }
+:focus-visible { outline: 3px solid var(--color-primary); outline-offset: 5px; }
+::selection { background: var(--color-primary-highlight); }
+[hidden] { display: none !important; }
+.wrap { width: min(1320px, 100% - 96px); margin-inline: auto; }
+.skip-link { position: fixed; top: 12px; left: 16px; padding: 10px 16px; background: var(--color-text); color: var(--color-text-inverse); z-index: 200; transform: translateY(-180%); }
+.skip-link:focus { transform: none; }
+.eyebrow, .feature-index, .preview-label { font: 11px/1.5 var(--landing-mono); letter-spacing: .075em; text-transform: uppercase; }
+.eyebrow { color: var(--color-primary); margin-bottom: 20px; }
+h1, h2, h3 { line-height: 1.1; letter-spacing: -.045em; font-weight: 650; text-wrap: balance; }
+h2 { font-size: clamp(30px, 3.1vw, 46px); }
+h3 { font-size: 23px; }
+p { text-wrap: pretty; }
+.section { padding-block: 104px; }
+.section-head { margin-bottom: 44px; }
+.section-head > p:not(.eyebrow) { max-width: 43ch; margin-top: 24px; color: var(--color-text-muted); }
+.text-link { display: inline-flex; align-items: center; gap: 12px; font-size: 14px; font-weight: 600; }
+.text-link > span { transition: transform .2s; }
+.text-link:hover { color: var(--color-primary); }
+.text-link:hover > span { transform: translateX(4px); }
+.landing-button { display: inline-flex; align-items: center; justify-content: center; gap: 20px; min-height: 48px; padding: 12px 22px; border: 1px solid transparent; border-radius: 5px; font-size: 14px; font-weight: 600; transition: background .2s, transform .2s; }
+.landing-button:hover { transform: translateY(-2px); }
+.landing-button-primary { background: var(--color-primary); color: var(--color-primary-contrast); }
+.landing-button-primary:hover { background: var(--color-primary-hover); }
+.landing-button-secondary { background: var(--color-surface); border-color: var(--color-border); color: var(--color-text); }
+.landing-button-secondary:hover { background: var(--color-surface-offset); }
+
+/* Navigation */
+.nav { position: sticky; top: 0; z-index: 100; background: var(--surface-overlay-raised); backdrop-filter: blur(16px); border-bottom: 1px solid var(--color-divider); }
+.nav-inner { display: flex; align-items: center; gap: 26px; height: 80px; }
+.nav-brand { display: inline-flex; align-items: center; gap: 9px; font-size: 22px; font-weight: 750; letter-spacing: -.055em; }
+.nav-mark { width: 30px; height: 30px; color: var(--color-primary); }
+.nav-links { display: flex; gap: 26px; margin-left: auto; }
+.nav-links a, .nav-github { padding-block: 12px; font-size: 13px; font-weight: 550; color: var(--color-text-muted); }
+.nav-links a:hover, .nav-links .is-active, .nav-github:hover { color: var(--color-primary); }
+.nav-links .is-active { box-shadow: inset 0 -2px var(--color-primary); }
+.nav-github { margin-left: 20px; }
+.nav-demo { min-height: 42px; padding: 9px 16px; font-size: 13px; }
+.nav-menu-toggle { display: none; align-items: center; justify-content: center; width: 44px; height: 44px; padding: 0; border: 1px solid var(--color-border); border-radius: 5px; background: var(--color-surface); color: var(--color-text); font-size: 22px; }
+
+/* One visual plane: the promise and the actual workspace. */
+.hero { overflow: clip; background: var(--surface-accent-subtle); border-bottom: 1px solid var(--color-divider); }
+.hero-inner { display: grid; grid-template-columns: minmax(0, .9fr) minmax(0, 1.1fr); gap: 44px; align-items: center; min-height: min(740px, calc(100svh - 80px)); padding-block: 48px; }
+.hero-title { font-size: clamp(66px, 7.2vw, 108px); letter-spacing: -.075em; margin-left: -.045em; }
+.hero-promise { margin-top: 26px; font-size: clamp(34px, 3.4vw, 49px); font-weight: 550; line-height: 1.12; letter-spacing: -.05em; }
+.hero-promise em { font-style: normal; color: var(--color-primary); }
+.hero-sub { max-width: 38ch; margin-top: 24px; color: var(--color-text-muted); font-size: 16px; }
+.hero-actions { display: flex; align-items: center; gap: 24px; margin-top: 32px; }
+.hero-note { font-size: 12px; margin-top: 22px; color: var(--color-text-muted); }
+.hero-shot { width: 125%; margin-top: 26px; }
+.preview-label { display: flex; justify-content: space-between; padding-bottom: 16px; color: var(--color-text-muted); }
+.hero-shot img { border: 1px solid var(--color-border); border-radius: 7px; box-shadow: var(--shadow-media-stage); }
+figcaption { margin-top: 20px; font-size: 11px; color: var(--color-text-muted); }
+.hero-shot figcaption { max-width: 70%; }
+
+/* Outcomes and the supported workflow. */
+.benefits { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 40px; }
+.benefit { padding-top: 24px; border-top: 1px solid var(--color-border); }
+.feature-index { display: block; color: var(--color-text-muted); margin-bottom: 26px; }
+.benefit p { margin-top: 18px; color: var(--color-text-muted); font-size: 14px; }
+.benefit .benefit-detail { font-size: 12px; }
+.benefit .text-link { margin-top: 22px; color: var(--color-primary); }
+.workflow-detail { margin-top: 76px; padding: 40px; display: grid; grid-template-columns: 1fr 1.3fr; gap: 60px; background: var(--color-surface-offset-2); }
+.workflow-detail h3 { font-size: 33px; }
+.workflow-detail p:not(.eyebrow) { max-width: 36ch; color: var(--color-text-muted); font-size: 14px; margin-top: 18px; }
+.format-list { align-self: center; }
+.format-list > div { display: grid; grid-template-columns: 150px 1fr; gap: 22px; padding-block: 20px; }
+.format-list > div + div { border-top: 1px solid var(--color-border); }
+.format-list dt { font-size: 14px; font-weight: 600; }
+.format-list dd { font-size: 13px; color: var(--color-text-muted); }
+.capability-rail { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 40px; margin-top: 48px; }
+.capability .eyebrow { margin-bottom: 16px; }
+.capability h3 { font-size: 20px; }
+.capability > p:last-child { margin-top: 14px; color: var(--color-text-muted); font-size: 13px; }
+
+/* The existing recording provides product proof. */
+.demo-section { background: var(--color-surface); border-block: 1px solid var(--color-divider); }
+.demo-layout { display: grid; grid-template-columns: .7fr 1.3fr; gap: 64px; align-items: center; }
+.demo-copy > p:not(.eyebrow) { margin-top: 24px; color: var(--color-text-muted); max-width: 36ch; font-size: 15px; }
+.demo-copy .landing-button { margin-top: 28px; }
+.demo-copy .demo-note { font-size: 12px; }
+.demo-note a { text-decoration: underline; text-underline-offset: 3px; }
+.demo-frame video { border-radius: 7px; border: 1px solid var(--color-border); background: var(--color-surface-ink); aspect-ratio: 16 / 10; }
+
+/* Setup: reuse the existing keyboard-accessible install tabs. */
+.install-layout, .docs-layout { display: grid; grid-template-columns: minmax(0, .85fr) minmax(0, 1.15fr); gap: 80px; }
+.install-layout .section-head, .docs-layout .section-head { margin: 0; }
+.section-head .install-requirements { font-size: 12px; margin-top: 20px; }
+.install-layout .text-link { margin-top: 24px; color: var(--color-primary); }
+.install { border: 1px solid var(--color-border); border-radius: 7px; background: var(--color-surface); overflow: hidden; }
+.install-tabs { display: flex; gap: 24px; padding-inline: 24px; border-bottom: 1px solid var(--color-divider); }
+.install-tab { min-height: 56px; padding: 12px 0; border: 0; background: transparent; color: var(--color-text-muted); font-size: 13px; }
+.install-tab.is-active { color: var(--color-primary); box-shadow: inset 0 -2px var(--color-primary); }
+.install-panel { padding: 26px; min-height: 184px; }
+.install-code { display: flex; flex-wrap: wrap; align-items: flex-start; justify-content: space-between; gap: 22px; }
+.install-code pre { min-width: 0; max-width: 100%; overflow-x: auto; font: 12px/1.9 var(--landing-mono); }
+code { font-family: var(--landing-mono); font-size: .9em; }
+.install-code pre code { font-size: inherit; }
+.copy-btn { min-height: 36px; padding: 7px 12px; font-size: 12px; gap: 6px; }
+.icon { width: 14px; height: 14px; }
+.install-note, .share-note { margin-top: 22px; font-size: 12px; color: var(--color-text-muted); }
+.share-note a { text-decoration: underline; text-underline-offset: 3px; }
+.clipboard-fallback { position: fixed; left: -9999px; opacity: 0; }
+html:not(.copy-ready) .copy-btn, html:not(.tabs-ready) .install-tabs { display: none; }
+html:not(.tabs-ready) .install-panel[hidden] { display: block !important; }
+html:not(.tabs-ready) .install-panel + .install-panel { border-top: 1px solid var(--color-divider); }
+
+/* Docs are routes to maintained guides, not duplicated reference content. */
+.docs-section { padding-top: 72px; border-top: 1px solid var(--color-divider); }
+.docs-layout .section-head { align-self: start; position: sticky; top: 128px; }
+.docs-source { display: inline-block; font-size: 11px; color: var(--color-text-muted); margin-top: 28px; }
+.docs-list { border-top: 1px solid var(--color-border); }
+.docs-list a { display: flex; align-items: center; justify-content: space-between; gap: 24px; padding: 20px 0; border-bottom: 1px solid var(--color-border); transition: color .2s; }
+.docs-list a:hover { color: var(--color-primary); }
+.docs-list strong { font-size: 17px; font-weight: 600; letter-spacing: -.02em; }
+.docs-list small { display: block; color: var(--color-text-muted); font-size: 12px; margin-top: 3px; }
+.docs-list a > span:last-child { color: var(--color-primary); font-size: 22px; }
+.closing { padding-block: 76px; background: var(--surface-accent-subtle); border-top: 1px solid var(--color-divider); }
+.closing-inner { display: flex; justify-content: space-between; align-items: center; gap: 40px; }
+.closing h2 { font-size: clamp(38px, 4.5vw, 64px); }
+.closing-actions { display: flex; flex-direction: column; align-items: flex-start; gap: 24px; }
+.footer { padding-block: 34px; border-top: 1px solid var(--color-divider); }
+.footer-inner { display: flex; align-items: center; gap: 24px; }
+.footer p { font-size: 11px; color: var(--color-text-muted); }
+.footer nav { display: flex; gap: 24px; margin-left: auto; font-size: 12px; }
+.footer nav a:hover { color: var(--color-primary); }
+
+/* Progressive enhancement: content is visible until observers are ready. */
+.reveal-ready .reveal { opacity: 0; transform: translateY(16px); transition: opacity .65s ease, transform .65s ease; }
+.reveal-ready .reveal.is-visible { opacity: 1; transform: none; }
+
+/* A single arrival: the pages meet, then the workspace comes into view. */
+@media (prefers-reduced-motion: no-preference) {
+  .nav-mark { overflow: visible; }
+  .nav-mark > * { transform-origin: center; animation: landing-page-front .8s cubic-bezier(.16, 1, .3, 1) backwards; }
+  .nav-mark > :first-child { animation-name: landing-page-back; }
+  .hero-enter { animation: landing-enter .7s cubic-bezier(.16, 1, .3, 1) backwards; }
+  .hero-copy > :nth-child(2) { animation-delay: .08s; }
+  .hero-copy > :nth-child(3) { animation-delay: .16s; }
+  .hero-copy > :nth-child(4) { animation-delay: .24s; }
+  .hero-copy > :nth-child(5) { animation-delay: .32s; }
+  .hero-copy > :nth-child(6) { animation-delay: .4s; }
+  .hero-shot { animation-name: landing-preview-enter; animation-duration: .9s; animation-delay: .28s; }
+  .hero-enter:focus-within { animation: none; }
+}
+@keyframes landing-page-back {
+  from { transform: translateX(-6px) rotate(-12deg); }
+  to { transform: none; }
+}
+@keyframes landing-page-front {
+  from { transform: translateX(6px) rotate(12deg); }
+  to { transform: none; }
+}
+@keyframes landing-enter {
+  from { opacity: 0; transform: translateY(14px); }
+  to { opacity: 1; transform: none; }
+}
+@keyframes landing-preview-enter {
+  from { opacity: 0; transform: translate(24px, 12px) scale(.985); }
+  to { opacity: 1; transform: none; }
+}
+
+@media (min-width: 1600px) {
+  .hero-shot { width: 112%; }
+}
+@media (min-width: 901px) and (max-height: 800px) {
+  .hero-inner { padding-block: 24px; }
+}
+@media (max-width: 1100px) {
+  .wrap { width: calc(100% - 64px); }
+  .nav-inner { gap: 20px; }
+  .nav-links { gap: 20px; }
+  .nav-github { display: none; }
+  .hero-inner { gap: 24px; }
+  .hero-title { font-size: 76px; }
+  .hero-promise { font-size: 37px; }
+  .hero-actions { gap: 18px; }
+  .benefits, .capability-rail { gap: 26px; }
+  .demo-layout, .install-layout, .docs-layout { gap: 40px; }
+  .workflow-detail { gap: 32px; padding: 32px; }
+  .format-list > div { grid-template-columns: 120px 1fr; gap: 16px; }
+}
+@media (max-width: 900px) {
+  .hero-inner { grid-template-columns: 1fr; min-height: auto; padding-block: 48px; }
+  .hero-copy { max-width: 600px; }
+  .hero-title { font-size: clamp(66px, 12vw, 100px); }
+  .hero-promise { font-size: 38px; }
+  .hero-sub { max-width: 44ch; }
+  .hero-shot { width: 100%; margin-top: 18px; }
+  .hero-shot figcaption { max-width: none; }
+  .benefits { grid-template-columns: 1fr; gap: 32px; }
+  .feature-index { margin-bottom: 16px; }
+  .benefit p { max-width: 64ch; }
+  .workflow-detail { grid-template-columns: 1fr; }
+  .format-list > div { grid-template-columns: 150px 1fr; }
+  .capability-rail { grid-template-columns: 1fr; gap: 32px; }
+  .capability { border-bottom: 1px solid var(--color-divider); padding-bottom: 24px; }
+  .demo-layout, .install-layout, .docs-layout { grid-template-columns: minmax(0, 1fr); gap: 36px; }
+  .docs-layout .section-head { position: static; }
+  .demo-copy > p:not(.eyebrow) { max-width: 52ch; }
+  .footer-inner { flex-wrap: wrap; }
+  .footer nav { width: 100%; margin: 0; }
+}
+@media (max-width: 700px) {
+  .wrap { width: calc(100% - 40px); }
+  .nav-inner { height: 68px; gap: 12px; }
+  .nav-brand { font-size: 20px; }
+  .nav-mark { width: 25px; height: 25px; }
+  .nav-demo { margin-left: auto; font-size: 11px; gap: 8px; padding-inline: 12px; }
+  .nav-menu-toggle { display: flex; }
+  .nav-links { display: none; }
+  .nav.is-menu-open .nav-links { position: absolute; display: grid; gap: 0; inset: 100% 0 auto; padding: 12px 20px; background: var(--color-surface); border-bottom: 1px solid var(--color-border); box-shadow: var(--shadow-md); }
+  .nav-links a { padding: 13px 8px; }
+  .section { padding-block: 64px; }
+  .section-head { margin-bottom: 32px; }
+  .hero-inner { padding-block: 36px; gap: 24px; }
+  .hero-copy .eyebrow { font-size: 10px; margin-bottom: 18px; }
+  .hero-title { font-size: clamp(56px, 14.5vw, 86px); }
+  .hero-promise { margin-top: 18px; font-size: 34px; }
+  .hero-sub { font-size: 14px; margin-top: 18px; }
+  .hero-actions { margin-top: 24px; gap: 20px; flex-wrap: wrap; }
+  .hero-actions .landing-button { padding-inline: 18px; }
+  .hero-actions .text-link { font-size: 13px; }
+  .hero-note { font-size: 10px; margin-top: 16px; }
+  .hero-shot { margin-top: 0; }
+  .preview-label { font-size: 9px; padding-bottom: 10px; }
+  figcaption { font-size: 10px; margin-top: 14px; }
+  .hero-shot img { box-shadow: var(--shadow-lg); }
+  .workflow-detail { padding: 24px; margin-top: 40px; gap: 16px; }
+  .workflow-detail h3 { font-size: 29px; }
+  .format-list > div { grid-template-columns: 1fr; gap: 5px; padding-block: 16px; }
+  .install-tabs { padding-inline: 18px; }
+  .install-panel { padding: 22px 18px; }
+  .install-code pre { font-size: 11px; }
+  .closing { padding-block: 56px; }
+  .closing-inner { flex-direction: column; align-items: flex-start; }
+  .closing-actions { gap: 20px; }
+  .footer-inner { gap: 16px; }
+  .footer p { font-size: 10px; }
+  .footer nav { gap: 22px; }
+}
+@media (prefers-reduced-motion: reduce) {
+  html { scroll-behavior: auto; }
+  *, *::before, *::after { transition: none !important; animation: none !important; }
+  .reveal-ready .reveal { opacity: 1; transform: none; }
+}

package/src/domain/agent-tool-definitions.js

@@ -49,6 +49,15 @@ const VALIDATION_ISSUE_SCHEMA = objectSchema({
   target: { type: 'string' },
 });
 
+const MARKDOWN_VALIDATION_SCHEMA = objectSchema({
+  issues: { items: VALIDATION_ISSUE_SCHEMA, type: 'array' },
+  valid: { type: 'boolean' },
+});
+const VALIDATE_MARKDOWN_INPUT = {
+  description: 'Return reference validation for the exact saved revision. Markdown only; validation issues do not roll back the save.',
+  type: 'boolean',
+};
+
 const DIAGRAM_RENDER_OUTPUT_PROPERTIES = {
   endLine: { minimum: 1, type: 'integer' },
   format: { enum: ['png', 'svg'], type: 'string' },
@@ -382,16 +391,18 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
 
   {
     annotations: { idempotentHint: true, readOnlyHint: true },
-    description: 'Search current Vault text with one fixed case-insensitive term. Returns path and line evidence.',
+    description: 'Search current Vault text with one literal case-insensitive phrase, not a natural-language question. Defaults to 10 files and 2 snippets each. Read relevant ranges before answering and cite path:line evidence. Narrow prefix or query when truncated; no matches do not prove a topic is absent.',
     inputSchema: objectSchema({
       limit: {
-        description: 'Maximum matching documents to return.',
+        default: 10,
+        description: 'Maximum matching documents to return (default 10).',
         maximum: 50,
         minimum: 1,
         type: 'integer',
       },
       maxSnippetsPerFile: {
-        description: 'Maximum matching snippets returned per document.',
+        default: 2,
+        description: 'Maximum matching snippets returned per document (default 2).',
         maximum: 10,
         minimum: 1,
         type: 'integer',
@@ -437,7 +448,7 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
         required: ['available', 'backend', 'minQueryLength', 'unavailableReason', 'version'],
         type: 'object',
       },
-      truncated: { type: 'boolean' },
+      truncated: { description: 'True when documents or snippets were omitted, or the search was incomplete. Counts cover observed matches, not necessarily all Vault matches.', type: 'boolean' },
     }),
     scope: 'vault:read',
     untrustedContentHint: true,
@@ -445,14 +456,21 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
   },
   {
     annotations: { idempotentHint: true, readOnlyHint: true },
-    description: 'Read a current CollabMD document range and return full-document revision for citations and edits.',
+    description: 'Read current text (default 80 lines) or a compact Markdown outline with full-document revision. Follow nextStartLine for more. Read content immediately before exact edits; on revision conflict reread and recompute. Maximum source size is 1000000 characters; a single content line over 100000 characters fails explicitly.',
     inputSchema: objectSchema({
       lineCount: {
-        description: 'Maximum number of lines to return.',
+        default: 80,
+        description: 'Maximum content lines or outline headings to return (default 80).',
         maximum: 500,
         minimum: 1,
         type: 'integer',
       },
+      mode: {
+        default: 'content',
+        description: 'Outline returns top-level ATX and single-line Setext headings, excluding fenced code and frontmatter. Heading text is capped at 200 characters.',
+        enum: ['content', 'outline'],
+        type: 'string',
+      },
       path: {
         description: 'Vault-relative document path.',
         maxLength: 1024,
@@ -470,13 +488,23 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
     outputSchema: objectSchema({
       content: { type: 'string' },
       endLine: { minimum: 1, type: 'integer' },
+      headings: {
+        items: objectSchema({
+          level: { minimum: 1, maximum: 6, type: 'integer' },
+          line: { minimum: 1, type: 'integer' },
+          text: { type: 'string' },
+          truncated: { type: 'boolean' },
+        }),
+        type: 'array',
+      },
+      nextStartLine: { type: ['integer', 'null'], minimum: 1 },
       kind: { type: 'string' },
       path: { type: 'string' },
       revision: REVISION_SCHEMA,
       startLine: { minimum: 1, type: 'integer' },
       totalLines: { minimum: 1, type: 'integer' },
       truncated: { type: 'boolean' },
-    }),
+    }, ['content', 'endLine', 'kind', 'nextStartLine', 'path', 'revision', 'startLine', 'totalLines', 'truncated']),
     scope: 'vault:read',
     untrustedContentHint: true,
     webMcp: true,
@@ -676,7 +704,7 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
   },
   {
     annotations: { destructiveHint: false, idempotentHint: true, readOnlyHint: false },
-    description: 'Create a valid editable .excalidraw scene from basic Excalidraw elements, with optional same-revision verification.',
+    description: 'Create an editable .excalidraw scene. Before the first diagram in a task, call get_collabmd_syntax with kind="excalidraw" for design guidance and valid examples. Request inline inspection/rendering and examine the image before finishing.',
     inputSchema: objectSchema({
       elements: {
         description: 'One to 200 basic Excalidraw elements in back-to-front order. Text may bind to a container with containerId; groupIds define atomic movement groups. Arrows may bind with startElementId and endElementId. beforeElementId or afterElementId sets explicit placement.',
@@ -707,7 +735,7 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
   },
   {
     annotations: { destructiveHint: false, idempotentHint: false, readOnlyHint: false },
-    description: 'Create, update, replace, translate, reorder, or delete elements in an existing .excalidraw scene when its revision still matches. Bound text whose font, size, line height, or content changes reflows automatically.',
+    description: 'Edit an existing .excalidraw scene only when its revision matches. Before the first diagram edit in a task, consult get_collabmd_syntax with kind="excalidraw". Inspect first, preserve existing style and unrelated elements, then verify the result. Supports create, update, replace, translate, reorder, and delete; bound-text metric edits reflow automatically.',
     inputSchema: objectSchema({
       create: {
         items: EXCALIDRAW_ELEMENT_INPUT_SCHEMA,
@@ -782,7 +810,7 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
   },
   {
     annotations: { destructiveHint: false, idempotentHint: false, readOnlyHint: false },
-    description: 'Apply bounded exact replacements to a document only when its revision still matches.',
+    description: 'Apply up to 20 unique, non-overlapping exact replacements against the revision from a fresh content read. Combined old/new text is limited to 50000 characters. On conflict reread; on ambiguous matches include more surrounding text. Optional Markdown validation checks the saved revision.',
     inputSchema: objectSchema({
       path: {
         description: 'Vault-relative path returned by read_document.',
@@ -813,6 +841,7 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
         type: 'array',
       },
       revision: REVISION_SCHEMA,
+      validate: VALIDATE_MARKDOWN_INPUT,
     }, ['path', 'revision', 'replacements']),
     method: 'applyTextEdits',
     name: 'apply_text_edits',
@@ -820,13 +849,14 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
       path: { type: 'string' },
       replacementCount: { minimum: 1, type: 'integer' },
       revision: REVISION_SCHEMA,
-    }),
+      validation: MARKDOWN_VALIDATION_SCHEMA,
+    }, ['path', 'replacementCount', 'revision']),
     scope: 'vault:edit',
     webMcp: true,
   },
   {
     annotations: { destructiveHint: false, idempotentHint: true, readOnlyHint: false },
-    description: 'Create a new supported CollabMD text document. An identical retry succeeds; different content at an existing path fails.',
+    description: 'Create a new supported text document (up to 200000 characters). Inspect nearby naming/style and consult get_collabmd_syntax for unfamiliar kinds. Identical retries succeed; different content at an existing path fails. Optional Markdown validation checks the saved revision.',
     inputSchema: objectSchema({
       content: {
         description: 'Initial document text, normalized to LF line endings.',
@@ -839,6 +869,7 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
         minLength: 1,
         type: 'string',
       },
+      validate: VALIDATE_MARKDOWN_INPUT,
     }, ['path', 'content']),
     method: 'createDocument',
     name: 'create_document',
@@ -846,7 +877,8 @@ export const AGENT_TOOL_DEFINITIONS = Object.freeze([
       kind: { type: 'string' },
       path: { type: 'string' },
       revision: REVISION_SCHEMA,
-    }),
+      validation: MARKDOWN_VALIDATION_SCHEMA,
+    }, ['kind', 'path', 'revision']),
     scope: 'vault:edit',
     webMcp: true,
   },

package/src/domain/collabmd-content-capabilities.js

@@ -13,6 +13,56 @@ import {
   supportsCommentsForFilePath,
 } from './file-kind.js';
 
+const EXCALIDRAW_DESIGN_GUIDE = [
+  'Plan: State the question the diagram answers, its audience, the essential entities, and what each connection means. Choose a flowchart for steps/decisions or a layered layout for responsibilities/dependencies. Keep one main idea per diagram; split dense detail into another diagram. Do not invent relationships to fill space.',
+  'Layout: Choose left-to-right or top-to-bottom reading order. Place containers before labels and connectors. Align related nodes and use consistent sizes and gaps. As starting points, use 200 x 88 nodes, 80-120 units between columns, and 60-80 between rows; enlarge these for the actual text. Reserve clear connector lanes. Route arrows around unrelated shapes, minimize crossings, and make direction unambiguous. These are defaults, not constraints on an existing design.',
+  'Labels and bindings: Prefer short entity names and verb phrases for relationships. Start around 20-unit body text and 28-unit titles, with one font family. Enlarge the container or add deliberate line breaks instead of shrinking text to fit. Create labels as separate text elements using containerId; creation still requires explicit x/y and correctly sized bounds. Bind connectors with startElementId/endElementId and set points relative to the arrow x/y, near the appropriate shape edges. Binding identifies the relationship; it does not plan the route. Allow padding around labels and keep relationship labels away from arrowheads.',
+  'Visual hierarchy: Use a clear title, restrained strokes, and at most two or three semantic fill colors with readable dark labels on light fills. Use shape, position, or text as well as color to distinguish roles. Reuse colors for the same meaning. Give related elements groupIds when they should move together. Keep text above its container in paint order. Avoid decorative elements that compete with the information.',
+  'Existing diagrams: In WebMCP, get active context first. Inspect the existing scene and preserve its style, IDs, layout, and unrelated elements. Use edit_excalidraw with the returned revision. Prefer translate for moving containers/groups and their related text; inspect attached connector routes after movement. Use reorder for paint order and same-ID replace for a type change. Bound-text placement normalization re-centers labels; use it only when that is intended. On a revision conflict, inspect again and reconsider the edit.',
+  'Verify and refine: Create or edit with verify: { render: true } to receive inspection and an image for that exact revision. Check diagnostics for clipping, unintended overlaps, occlusion, text placement, and connectors crossing components. Examine the image for reading order, legibility, correct relationships, and clear arrow direction; structural validity alone does not establish visual quality. Fix concrete problems with revision-guarded edits and verify again. Use verify: { render: false } for intermediate create/edit checks when an image would add no information; use verify_excalidraw with render: true for the final image. Stop when the requested meaning is clear and no material layout issue remains; do not redraw solely to chase cosmetic variation.',
+  'Rendering limits: Remote collabmd-basic-svg previews approximate Excalidraw and report preview-not-pixel-identical; WebMCP uses the official browser renderer. If an image is unavailable, report that visual quality was not checked instead of claiming it was verified.',
+  'Examples below are complete MCP tools/call payloads using this server\'s schema. Choose a new Vault-relative path and adapt labels, geometry, and relationships. For WebMCP, call the corresponding collabmd_ tool with the arguments object. Reuse this guide during the task; fetching it before every edit is unnecessary.',
+].join('\n\n');
+
+const EXCALIDRAW_CREATION_EXAMPLES = [
+  {
+    name: 'create_excalidraw',
+    arguments: {
+      path: 'diagrams/request-flow.excalidraw',
+      elements: [
+        { id: 'title', type: 'text', x: 40, y: 32, text: 'Request review', fontSize: 28 },
+        { id: 'request', type: 'rectangle', x: 40, y: 96, width: 200, height: 88, backgroundColor: '#e7f5ff' },
+        { id: 'review', type: 'rectangle', x: 360, y: 96, width: 200, height: 88, backgroundColor: '#e7f5ff' },
+        { id: 'respond', type: 'rectangle', x: 680, y: 96, width: 200, height: 88, backgroundColor: '#e7f5ff' },
+        { id: 'request-label', type: 'text', x: 98, y: 127.5, text: 'Request', containerId: 'request' },
+        { id: 'review-label', type: 'text', x: 424, y: 127.5, text: 'Review', containerId: 'review' },
+        { id: 'respond-label', type: 'text', x: 738, y: 127.5, text: 'Respond', containerId: 'respond' },
+        { id: 'request-review', type: 'arrow', x: 244, y: 140, points: [[0, 0], [112, 0]], startElementId: 'request', endElementId: 'review' },
+        { id: 'review-respond', type: 'arrow', x: 564, y: 140, points: [[0, 0], [112, 0]], startElementId: 'review', endElementId: 'respond' },
+      ],
+      verify: { render: true },
+    },
+  },
+  {
+    name: 'create_excalidraw',
+    arguments: {
+      path: 'diagrams/service-layers.excalidraw',
+      elements: [
+        { id: 'title', type: 'text', x: 40, y: 32, text: 'Service layers', fontSize: 28 },
+        { id: 'presentation', type: 'rectangle', x: 40, y: 96, width: 360, height: 96, backgroundColor: '#e7f5ff' },
+        { id: 'application', type: 'rectangle', x: 40, y: 256, width: 360, height: 96, backgroundColor: '#e7f5ff' },
+        { id: 'storage', type: 'rectangle', x: 40, y: 416, width: 360, height: 96, backgroundColor: '#e7f5ff' },
+        { id: 'presentation-label', type: 'text', x: 148, y: 131.5, text: 'Presentation', containerId: 'presentation' },
+        { id: 'application-label', type: 'text', x: 154, y: 291.5, text: 'Application', containerId: 'application' },
+        { id: 'storage-label', type: 'text', x: 178, y: 451.5, text: 'Storage', containerId: 'storage' },
+        { id: 'presentation-application', type: 'arrow', x: 220, y: 196, points: [[0, 0], [0, 56]], startElementId: 'presentation', endElementId: 'application' },
+        { id: 'application-storage', type: 'arrow', x: 220, y: 356, points: [[0, 0], [0, 56]], startElementId: 'application', endElementId: 'storage' },
+      ],
+      verify: { render: true },
+    },
+  },
+].map((example) => JSON.stringify(example));
+
 const CAPABILITIES = Object.freeze({
   base: {
     agentCreatable: true,
@@ -35,7 +85,7 @@ const CAPABILITIES = Object.freeze({
     agentEditable: true,
     editable: true,
     extensions: [EXCALIDRAW_FILE_EXTENSION],
-    guide: 'Excalidraw scene JSON managed by the canvas editor. Use create_excalidraw and edit_excalidraw rather than raw text edits. Element order is back-to-front; create supports beforeElementId and afterElementId, while edit supports relationship-aware translation, reorder, same-ID verification, and bound-text placement normalization. Container or group translation also moves bound text and grouped members. Standalone auto-resizing text recalculates its bounds when text metrics change; bound text whose font, size, line height, or content changes is re-centered and remeasured vertically. Line, arrow, and freedraw dimensions are derived from points. Creation and editing support inline inspection and optional rendering; verify_excalidraw can return compact layout diagnostics without an image. Remote fallback renders report preview-not-pixel-identical. Supported agent element types: rectangle, ellipse, diamond, text, arrow, line, and freedraw. Embed with ![[drawing.excalidraw]].',
+    guide: 'Excalidraw scene JSON managed by the canvas editor. Use create_excalidraw and edit_excalidraw rather than raw text edits. Element order is back-to-front; create supports beforeElementId and afterElementId, while edit supports relationship-aware translation, reorder, same-ID replacement, and bound-text placement normalization. Container or group translation also moves bound text and grouped members. Standalone auto-resizing text recalculates its bounds when text metrics change; bound text whose font, size, line height, or content changes is re-centered and remeasured vertically. Line, arrow, and freedraw dimensions are derived from points. Creation and editing support inline inspection and optional rendering; verify_excalidraw can return compact layout diagnostics without an image. Remote fallback renders report preview-not-pixel-identical. Supported agent element types: rectangle, ellipse, diamond, text, arrow, line, and freedraw. Embed with ![[drawing.excalidraw]].',
     examples: ['![[drawing.excalidraw]]'],
   },
   html: {
@@ -59,12 +109,13 @@ const CAPABILITIES = Object.freeze({
     agentEditable: true,
     editable: true,
     extensions: [...MARKDOWN_FILE_EXTENSIONS],
-    guide: 'Markdown-it syntax with YAML frontmatter, headings, tables, task lists, fenced code, linkified URLs, [[wiki-links]], aliases, and embeds. Use ![[file.ext]] for Base, draw.io, Excalidraw, Mermaid, or PlantUML Vault embeds. Use ![Label](https://...) for public video embeds: valid YouTube URLs or direct public HTTPS URLs ending in .mp4, .webm, or .ogg. Use relative Markdown image paths for Vault image attachments. Raw HTML is disabled.',
+    guide: 'Markdown-it syntax with YAML frontmatter, headings, tables, task lists, fenced code, linkified URLs, [[wiki-links]], aliases, and embeds. Use $...$ for inline math and $$...$$ on its own lines for display math (KaTeX). Use ![[file.ext]] for Base, draw.io, Excalidraw, Mermaid, or PlantUML Vault embeds. Use ![Label](https://...) for public video embeds: valid YouTube URLs or direct public HTTPS URLs ending in .mp4, .webm, or .ogg. Use relative Markdown image paths for Vault image attachments. Raw HTML is disabled.',
     examples: [
       '---\ntags: [docs]\n---\n# Title\n\n- [ ] Task\n\n[[Other Note|Alias]]',
       '![[diagram.mmd]]\n![[diagram.puml]]\n![[drawing.excalidraw]]\n![[architecture.drawio]]\n![[query.base]]',
       '![Demo](https://www.youtube.com/watch?v=dQw4w9WgXcQ)\n![Demo](https://cdn.example.com/demo.webm)\n![Diagram](assets/diagram.png)',
       '```mermaid\nflowchart LR\n  A --> B\n```\n\n```plantuml\n@startuml\nAlice -> Bob\n@enduml\n```',
+      'Inline math $E = mc^2$ and display math:\n\n$$\n\\frac{a}{b}\n$$',
     ],
   },
   mermaid: {
@@ -127,9 +178,13 @@ export function listCollabMdContentCapabilities() {
 export function getCollabMdSyntaxGuide(kind) {
   const capability = getCollabMdContentCapability(kind);
   return capability ? {
-    examples: capability.examples,
+    examples: capability.kind === 'excalidraw'
+      ? [...EXCALIDRAW_CREATION_EXAMPLES, ...capability.examples]
+      : capability.examples,
     extensions: capability.extensions,
-    guide: capability.guide,
+    guide: capability.kind === 'excalidraw'
+      ? `${capability.guide}\n\n${EXCALIDRAW_DESIGN_GUIDE}`
+      : capability.guide,
     kind: capability.kind,
   } : null;
 }

package/src/domain/collaboration-protocol.js

@@ -1,2 +1,4 @@
+export const MSG_SYNC = 0;
+export const MSG_AWARENESS = 1;
 export const MSG_AGENT_FLUSH = 4;
 export const MSG_AGENT_FLUSH_ACK = 5;

package/src/domain/markdown-outline.js

@@ -0,0 +1,35 @@
+import { extractYamlFrontmatter } from './yaml-frontmatter.js';
+
+// ponytail: top-level ATX and single-line Setext headings only; use a shared full parser if nested outlines are needed.
+export function collectMarkdownOutline(content) {
+  const lines = (extractYamlFrontmatter(content)?.bodyMarkdown ?? content).split(/\r?\n/u);
+  const headings = [];
+  let fence = null;
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    const marker = line.match(/^ {0,3}(`{3,}|~{3,})(.*)$/u);
+    if (fence) {
+      if (marker && marker[1][0] === fence[0] && marker[1].length >= fence.length && !marker[2].trim()) {
+        fence = null;
+      }
+      continue;
+    }
+    if (marker && (marker[1][0] !== '`' || !marker[2].includes('`'))) {
+      fence = marker[1];
+      continue;
+    }
+    const atx = line.match(/^ {0,3}(#{1,6})(?:[\t ]+(.*)|$)/u);
+    const setext = !atx && /^ {0,3}\S/u.test(line) && !/^ {0,3}(?:>|[-+*]\s|\d+[.)]\s)/u.test(line)
+      && lines[index + 1]?.match(/^ {0,3}(=+|-+)[\t ]*$/u);
+    if (!atx && !setext) continue;
+    const text = atx ? (atx[2] ?? '').replace(/(?:^|[\t ]+)#+[\t ]*$/u, '').trim() : line.trim();
+    headings.push({
+      level: atx ? atx[1].length : setext[1][0] === '=' ? 1 : 2,
+      line: index + 1,
+      text: text.slice(0, 200),
+      truncated: text.length > 200,
+    });
+    if (setext) index += 1;
+  }
+  return headings;
+}

package/src/server/application/agent-connection-service.js

@@ -158,12 +158,16 @@ export class AgentConnectionService {
       throw createAccessError('AGENT_TOKEN_INVALID', 'Agent Connection token is invalid or expired', 401);
     }
 
+    if (this.hostedWorkspaceService?.enabled && connection.subjectType !== 'hosted_membership') {
+      throw createAccessError('AGENT_MEMBERSHIP_REQUIRED', 'Create a new Agent Connection for this Team Membership', 403);
+    }
+
     let collaborator = connection.subjectEmail
       ? { email: connection.subjectEmail, name: connection.subjectEmail }
       : null;
     if (connection.subjectType === 'hosted_membership') {
-      const access = await this.hostedWorkspaceService.authorizeWorkspaceAccess({ user: collaborator });
-      if (!access.ok || access.membership.id !== connection.subjectId) {
+      const access = await this.hostedWorkspaceService?.authorizeWorkspaceAccess({ user: collaborator });
+      if (!access?.ok || access.membership?.id !== connection.subjectId) {
         throw createAccessError('AGENT_MEMBERSHIP_REQUIRED', 'Team Membership is no longer active', 403);
       }
       collaborator = access.membership;