@entropicwarrior/sdoc 0.2.13 → 0.2.14

package/docs/reference/sdoc-authoring.sdoc

@@ -554,7 +554,7 @@ Content of Section B.
         {
             The reserved \`@meta\` scope configures per-file settings and is not rendered in the document body. Use the bare \`@meta\` form (preferred) or the heading form:
 
-            ```
+            ```sdoc
             @meta {
                 type: doc
 
@@ -604,15 +604,20 @@ Content of Section B.
 
         # About Scope @about-scope
         {
-            The reserved \`@about\` scope provides a discovery summary for the document. It is used by \`list_knowledge\` to describe the file but is not rendered in the document body. Use the bare \`@about\` form (preferred) or the heading form:
+            The reserved \`@about\` scope provides a discovery summary for the document. It is used by \`list_knowledge\` to describe the file and is also rendered in the live preview with a distinct meta-section style so readers can tell it apart from regular body content. Use the bare \`@about\` form (preferred) or the heading form:
 
-            ```
+            ```sdoc
             @about {
-                How to write correct SDOC files. Covers document structure, inline formatting, block types, and common mistakes.
+                How to write correct SDOC files.
+                Covers document structure, inline formatting, block types, and common mistakes.
             }
             ```
 
-            The heading form \`# About @about { }\` also works but the bare form is preferred.
+            The heading form \`# About @about { }\` also works but the bare form is preferred. With the bare form, the renderer synthesizes an \`About\` heading so the meta-section is always labelled. The heading form lets you override that label — \`# Document Discovery @about { }\` renders with `Document Discovery` as the title.
+
+            **Hidden by default in HTML / PDF exports.** Exported files are usually sent to a recipient who has already decided to read the document, so the \`@about\` discovery summary is redundant in that context. To keep it in an export, pass the opt-in flag — \`--include-about\` (see [CLI and Tools Reference](./cli.sdoc)).
+
+            An empty or whitespace-only \`@about\` scope is never rendered, regardless of the include flag.
         }
 
         # Escaping @escaping

package/lexica/specification.sdoc

@@ -982,6 +982,29 @@ Content of Section B.
                 }
             }
         }
+
+        # About Scope @about-scope
+        {
+            A reserved \`@about\` scope holds a short discovery summary for the document — what it covers, who it is for, and when to reach for it. The bare form is preferred:
+
+            ```sdoc
+            @about {
+                How to write correct SDOC files. Covers document structure,
+                inline formatting, block types, and common mistakes.
+            }
+            ```
+
+            The heading form `# Title @about { }` is also accepted; the title given there overrides the default `About` label when the section is rendered.
+
+            {[.]
+                - The `@about` id is reserved and must not be used for normal references
+                - The scope is consumed by discovery tooling (e.g. `list_knowledge` and related agent-facing helpers) to describe a document without loading the full body
+                - In the VS Code live preview, `@about` renders as a meta-section — distinct background, dashed border, subdued typography — so readers can tell it apart from regular body content
+                - **HTML and PDF export hide `@about` by default**, on the principle that an exported file is normally sent to a recipient who has already been asked to read it, so the "should I read this?" framing is redundant. Renderers expose an `includeAbout` opt-in (`--include-about` for the CLI; `{ includeAbout: true }` for the VS Code export commands)
+                - When rendered, a bare `@about { ... }` (no heading line) is given a synthesized `About` heading so the meta-section is always labelled. The heading form preserves any custom title the author wrote
+                - An empty or whitespace-only `@about` scope is never rendered, regardless of the `includeAbout` setting — the meta-section box is suppressed entirely
+            }
+        }
     }
 
     # Interactive Preview @interactive-preview
@@ -1146,9 +1169,12 @@ Content of Section A.
                       | "left" | "center" | "right" ;
         percentage    = digit { digit } [ "." digit { digit } ] "%" ;
         pixels        = digit { digit } "px" ;
-        table_body    = [ directive_row ] table_row { table_row } ;
+        table_body    = table_row [ directive_row ] { table_row }
+                      | directive_row { table_row } ;
+                      (* normal tables: header row then optional directive row;
+                         headerless tables: optional directive row first *)
         directive_row = directive_cell { "|" directive_cell } ;
-        directive_cell = [ align_char ] [ ws format_spec ] ;
+        directive_cell = [ align_char ] [ format_spec ] ;
         align_char    = "<" | ">" | "=" ;
         format_spec   = "$" [ "." digits ]
                       | "," [ "." digits ]

package/package.json

@@ -2,7 +2,7 @@
   "name": "@entropicwarrior/sdoc",
   "displayName": "SDOC - Docs for Human/Agent Teams",
   "description": "A plain-text documentation format with explicit brace scoping — deterministic parsing, AI-agent efficiency, and 10-50x token savings vs Markdown.",
-  "version": "0.2.13",
+  "version": "0.2.14",
   "publisher": "entropicwarrior-msenfin",
   "license": "MIT",
   "repository": {

package/src/notion-renderer.js

@@ -7,7 +7,7 @@
 //   const { nodes, meta } = extractMeta(parsed.nodes);
 //   const blocks = renderNotionBlocks(nodes);
 
-const { parseInline } = require("./sdoc");
+const { parseInline, isAboutEmpty } = require("./sdoc");
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -293,6 +293,11 @@ function renderNode(node, depth, nestLevel) {
 function renderScope(scope, depth, nestLevel) {
   if (scope.scopeType === "comment") return [];
 
+  if (scope.id && scope.id.toLowerCase() === "about") {
+    if (isAboutEmpty(scope)) return [];
+    return renderAboutCallout(scope, depth, nestLevel);
+  }
+
   const level = Math.min(3, Math.max(1, depth));
 
   if (scope.hasHeading === false) {
@@ -310,6 +315,49 @@ function renderScope(scope, depth, nestLevel) {
   return [headingBlock(level, scope.title, null), ...childBlocks];
 }
 
+// Render @about as a Notion callout so readers can tell it apart from body
+// content. Paragraph children fold into the callout's rich_text (separated by
+// newlines); anything else becomes a child block.
+function renderAboutCallout(scope, depth, nestLevel) {
+  // Callout children sit one level deeper in the Notion block tree than the
+  // callout itself. Clamp to MAX_NEST so we never produce blocks past Notion's
+  // nesting limit.
+  const childDepth = depth + 1;
+  const childNestLevel = Math.min(nestLevel + 1, MAX_NEST);
+  const richTexts = [];
+  const childBlocks = [];
+
+  for (const child of scope.children || []) {
+    if (child.type === "paragraph") {
+      if (richTexts.length > 0) {
+        richTexts.push(richText("\n", null, defaultAnnotations()));
+      }
+      const { richText: rt, imageBlocks } = extractImagesFromInline(child.text);
+      richTexts.push(...rt);
+      childBlocks.push(...imageBlocks);
+    } else {
+      childBlocks.push(...renderNode(child, childDepth, childNestLevel));
+    }
+  }
+
+  if (richTexts.length === 0) {
+    richTexts.push(richText("", null, defaultAnnotations()));
+  }
+
+  const callout = {
+    type: "callout",
+    callout: {
+      rich_text: enforceContentLimit(richTexts, RICH_TEXT_LIMIT),
+      icon: { type: "emoji", emoji: "ℹ️" },
+      color: "gray_background"
+    }
+  };
+  if (childBlocks.length > 0) {
+    callout.callout.children = childBlocks;
+  }
+  return [callout];
+}
+
 function renderParagraph(node) {
   const { richText: rt, imageBlocks } = extractImagesFromInline(node.text);
   const blocks = [];

package/src/sdoc.js

@@ -243,7 +243,8 @@ function detectImplicitRoot(cursor) {
     if (nextTrimmed === COMMAND_SCOPE_OPEN ||
         nextTrimmed === COMMAND_LIST_BULLET ||
         nextTrimmed === COMMAND_LIST_NUMBER ||
-        isTableCommand(nextTrimmed)) {
+        isTableCommand(nextTrimmed) ||
+        isCitationsCommand(nextTrimmed)) {
       isImplicit = false;
     } else if (tryParseInlineBlock(nextTrimmed) !== null) {
       isImplicit = false;
@@ -1817,8 +1818,17 @@ function renderInlineNodes(nodes) {
 function renderScope(scope, depth, isTitleScope = false) {
   // :comment scopes are not rendered
   if (scope.scopeType === "comment") return "";
-  // @about is document metadata, not rendered in output
-  if (scope.id && scope.id.toLowerCase() === "about") return "";
+
+  const isAbout = scope.id && scope.id.toLowerCase() === "about";
+  // Skip empty/whitespace-only @about — no point rendering an empty meta box.
+  if (isAbout && isAboutEmpty(scope)) return "";
+
+  // Bare `@about { ... }` (no heading) and heading-form with empty title both
+  // get a default heading of "About" so the meta-section is always labelled.
+  // A custom title (e.g. `# Document Discovery @about`) is preserved.
+  if (isAbout && (!scope.hasHeading || !scope.title || !scope.title.trim())) {
+    scope = { ...scope, hasHeading: true, title: "About" };
+  }
 
   const level = Math.min(6, Math.max(1, depth));
   const children = scope.children.map((child) => renderNode(child, depth + 1)).join("\n");
@@ -1826,9 +1836,10 @@ function renderScope(scope, depth, isTitleScope = false) {
   const dl = dataLineAttrs(scope);
   const typeAttr = scope.scopeType ? ` data-scope-type="${escapeAttr(scope.scopeType)}"` : "";
   const typeClass = scope.scopeType ? ` sdoc-scope-type-${scope.scopeType}` : "";
+  const metaClass = isAbout ? " sdoc-meta-section" : "";
 
   if (scope.hasHeading === false) {
-    return `<section class="sdoc-scope sdoc-scope-noheading${rootClass}${typeClass}"${typeAttr}${dl}>${children}</section>`;
+    return `<section class="sdoc-scope sdoc-scope-noheading${rootClass}${typeClass}${metaClass}"${typeAttr}${dl}>${children}</section>`;
   }
 
   const idAttr = scope.id ? ` id="${escapeAttr(scope.id)}"` : "";
@@ -1836,7 +1847,7 @@ function renderScope(scope, depth, isTitleScope = false) {
   const toggle = hasChildren ? `<span class="sdoc-toggle"></span>` : "";
   const heading = `<h${level}${idAttr} class="sdoc-heading sdoc-depth-${level}"${dl}>${toggle}${renderInline(scope.title)}</h${level}>`;
   const childrenHtml = children ? `\n<div class="sdoc-scope-children">${children}</div>` : "";
-  return `<section class="sdoc-scope${rootClass}${typeClass}"${typeAttr}>${heading}${childrenHtml}</section>`;
+  return `<section class="sdoc-scope${rootClass}${typeClass}${metaClass}"${typeAttr}>${heading}${childrenHtml}</section>`;
 }
 
 function renderCitations(node) {
@@ -2940,6 +2951,43 @@ const DEFAULT_STYLE = `
     display: none;
   }
 
+  /* Meta sections (@about) — rendered with a distinct, subdued style
+     so readers can tell at a glance this is document metadata, not body content. */
+  .sdoc-scope.sdoc-meta-section {
+    position: relative;
+    margin: 1.2rem 3rem 1.6rem 3rem;
+    padding: 0.7rem 1rem 0.7rem 1rem;
+    background: rgba(127, 120, 112, 0.06);
+    border: 1px dashed var(--sdoc-border);
+    border-left: 3px solid var(--sdoc-muted);
+    border-radius: 6px;
+    color: var(--sdoc-muted);
+    font-size: 0.95em;
+  }
+
+  .sdoc-meta-section .sdoc-heading {
+    margin-top: 0.2rem;
+    color: var(--sdoc-muted);
+    font-weight: 600;
+    border-bottom: none;
+  }
+
+  .sdoc-meta-section .sdoc-paragraph {
+    margin: 0.3rem 0;
+    font-style: italic;
+  }
+
+  .sdoc-meta-section .sdoc-scope-children > .sdoc-scope {
+    padding-left: 0;
+  }
+
+  /* Place the collapse toggle in the gutter to the LEFT of the meta
+     box (in the space created by margin-left), not on the colored
+     left border. Default is left: -1.4em which lands on the border. */
+  .sdoc-meta-section > .sdoc-heading > .sdoc-toggle {
+    left: -2.6em;
+  }
+
 `;
 
 const PRINT_STYLE = `
@@ -3077,15 +3125,21 @@ function renderBodyNodes(nodes) {
     .join("\n");
 }
 
-function renderHtmlBody(text) {
+function renderHtmlBody(text, options = {}) {
   const parsed = parseSdoc(text);
   const metaResult = extractMeta(parsed.nodes);
   const savedOptions = _renderOptions;
   _renderOptions = {};
-  const citationData = buildCitationNumbering(metaResult.nodes);
+  // includeAbout defaults to false: HTML output is treated as "export-shape"
+  // by default, hiding the discovery summary. The preview path in
+  // extension.js opts in with `includeAbout: true` to keep the meta-section
+  // visible during authoring.
+  const includeAbout = options.includeAbout === true;
+  const renderNodes = includeAbout ? metaResult.nodes : stripAboutScopes(metaResult.nodes);
+  const citationData = buildCitationNumbering(renderNodes);
   _citationNumbering = citationData.numbering;
   _citationDefinitions = citationData.definitions;
-  const result = renderBodyNodes(metaResult.nodes);
+  const result = renderBodyNodes(renderNodes);
   _citationNumbering = new Map();
   _citationDefinitions = new Map();
   _renderOptions = savedOptions;
@@ -3094,10 +3148,16 @@ function renderHtmlBody(text) {
 
 function renderHtmlDocumentFromParsed(parsed, title, options = {}) {
   _renderOptions = options.renderOptions ?? {};
-  const citationData = buildCitationNumbering(parsed.nodes);
+  // includeAbout defaults to false: HTML/PDF output is hidden-by-default
+  // because exported files are normally sent to a specific recipient who has
+  // already been asked to read the doc, so the "should I read this?" framing
+  // in @about adds noise. The live preview opts in with `includeAbout: true`.
+  const includeAbout = options.includeAbout === true;
+  const renderNodes = includeAbout ? parsed.nodes : stripAboutScopes(parsed.nodes);
+  const citationData = buildCitationNumbering(renderNodes);
   _citationNumbering = citationData.numbering;
   _citationDefinitions = citationData.definitions;
-  const body = renderBodyNodes(parsed.nodes);
+  const body = renderBodyNodes(renderNodes);
   _citationNumbering = new Map();
   _citationDefinitions = new Map();
   _renderOptions = {};
@@ -3125,13 +3185,13 @@ function renderHtmlDocumentFromParsed(parsed, title, options = {}) {
   const mermaidInit = mermaidTheme === "auto"
     ? `var isDark=window.matchMedia("(prefers-color-scheme:dark)").matches;mermaid.initialize({startOnLoad:true,theme:isDark?"dark":"neutral",themeCSS:".node rect, .node polygon, .node circle { rx: 4; ry: 4; }"});`
     : `mermaid.initialize({startOnLoad:true,theme:"${mermaidTheme}",themeCSS:".node rect, .node polygon, .node circle { rx: 4; ry: 4; }"});`;
-  const mermaidScript = hasMermaidBlocks(parsed.nodes)
+  const mermaidScript = hasMermaidBlocks(renderNodes)
     ? `\n<script src="${MERMAID_CDN}"></script>\n<script>${mermaidInit}</script>`
     : "";
   const katexCssTag = body.includes('class="katex"')
     ? `\n<link rel="stylesheet" href="${KATEX_CDN_CSS}" />`
     : "";
-  const hasHljs = hasHighlightableCodeBlocks(parsed.nodes);
+  const hasHljs = hasHighlightableCodeBlocks(renderNodes);
   // Highlight.js CSS is inlined (not a <link>) so it is extracted by parseDocHtml in the web viewer
   // and applied inside shadow DOM. The @media query handles dark mode in browsers.
   const hljsCssInline = hasHljs
@@ -3443,6 +3503,36 @@ function extractAbout(nodes) {
   return null;
 }
 
+// True when an @about scope has no meaningful content. Renderers use this to
+// skip emitting an empty meta-section / callout. Whitespace-only paragraphs
+// count as empty.
+function isAboutEmpty(scope) {
+  if (!scope || !scope.children || scope.children.length === 0) return true;
+  return scope.children.every(
+    (child) => child.type === "paragraph" && (!child.text || child.text.trim() === "")
+  );
+}
+
+// Recursively remove @about scopes from an AST. Used by the HTML/PDF export
+// paths, which hide @about by default: when a doc is exported and sent to a
+// specific recipient, the "should I read this?" framing is moot — the sender
+// already decided the answer is yes. Pass-through for nodes without children.
+function stripAboutScopes(nodes) {
+  if (!Array.isArray(nodes)) return nodes;
+  const result = [];
+  for (const node of nodes) {
+    if (node && node.type === "scope" && node.id && node.id.toLowerCase() === "about") {
+      continue;
+    }
+    if (node && node.type === "scope" && Array.isArray(node.children)) {
+      result.push({ ...node, children: stripAboutScopes(node.children) });
+    } else {
+      result.push(node);
+    }
+  }
+  return result;
+}
+
 function collectAllIds(nodes) {
   const ids = new Set();
   function walk(nodeList) {
@@ -3668,6 +3758,8 @@ module.exports = {
   listSections,
   extractSection,
   extractAbout,
+  isAboutEmpty,
+  stripAboutScopes,
   extractDataBlocks,
   KNOWN_SCOPE_TYPES,
   // Validation

package/tools/build-doc.js

@@ -2,11 +2,12 @@
 // SDOC Document — CLI tool for HTML and PDF export
 //
 // Usage:
-//   node tools/build-doc.js input.sdoc [-o output] [--html]
+//   node tools/build-doc.js input.sdoc [-o output] [--html] [--include-about]
 //
 // Default output is PDF (requires Chrome/Chromium).
 // Use --html for HTML-only output (no Chrome needed).
 // If -o is omitted, writes to input.pdf (or input.html with --html).
+// The @about scope is hidden by default; pass --include-about to keep it.
 
 const fs = require("fs");
 const path = require("path");
@@ -16,7 +17,7 @@ const { parseSdoc, extractMeta, resolveIncludes, renderHtmlDocumentFromParsed }
 const CONFIG_FILENAME = "sdoc.config.json";
 
 function usage() {
-  console.error("Usage: build-doc <input.sdoc> [-o output] [--html]");
+  console.error("Usage: build-doc <input.sdoc> [-o output] [--html] [--include-about]");
   process.exit(1);
 }
 
@@ -98,7 +99,8 @@ function resolveMetaStyles(meta, documentPath) {
   return result;
 }
 
-async function buildHtml(filePath) {
+async function buildHtml(filePath, options = {}) {
+  const includeAbout = options.includeAbout === true;
   const resolvedPath = path.resolve(filePath);
   const text = fs.readFileSync(resolvedPath, "utf8");
   const parsed = parseSdoc(text);
@@ -141,6 +143,7 @@ async function buildHtml(filePath) {
       config,
       cssOverride: cssOverride || undefined,
       cssAppend: cssAppendParts.join("\n") || undefined,
+      includeAbout,
     }
   );
 }
@@ -150,12 +153,15 @@ async function main() {
   let inputPath = null;
   let outputPath = null;
   let htmlMode = false;
+  let includeAbout = false;
 
   for (let i = 0; i < args.length; i++) {
     if (args[i] === "-o" && i + 1 < args.length) {
       outputPath = args[++i];
     } else if (args[i] === "--html") {
       htmlMode = true;
+    } else if (args[i] === "--include-about") {
+      includeAbout = true;
     } else if (args[i] === "--help" || args[i] === "-h") {
       usage();
     } else if (!inputPath) {
@@ -174,7 +180,7 @@ async function main() {
     process.exit(1);
   }
 
-  const html = await buildHtml(resolvedInput);
+  const html = await buildHtml(resolvedInput, { includeAbout });
 
   if (htmlMode) {
     if (!outputPath) {