@entropicwarrior/sdoc 0.2.12 → 0.2.14

package/docs/reference/sdoc-authoring.sdoc

@@ -275,6 +275,66 @@ Content of Section B.
             }
             ```
 
+            # Column Directives @column-directives
+            {
+                An optional directive row after the header controls per-column alignment and number formatting. It is consumed by the parser and not rendered as data.
+
+                # Column Alignment
+                {
+                    Use \`<\` (left), \`>\` (right), or \`=\` (center):
+
+                    ```
+                    {[table]
+                        Programme | Amount | Status
+                        < | > | =
+                        Alpha | $1,000,000 | Active
+                        Beta | $2,500,000 | Pending
+                    }
+                    ```
+
+                    If absent, all columns default to left. Empty cells in the directive row keep the default. Alignment applies to both header and data cells.
+
+                    For headerless tables, the directive row is the first row — it is consumed but no header is rendered:
+
+                    ```
+                    {[table headerless]
+                        < | >
+                        Alice | 100
+                        Bob | 200
+                    }
+                    ```
+                }
+
+                # Column Formatting
+                {
+                    A format token in the directive row formats numeric cells and formula results in that column. Text cells (like bold labels) pass through unchanged. The format is display-only — formulas always use raw numeric values.
+
+                    {[.]
+                        - \`$\` — currency, no decimals: \`$1,000,000\`
+                        - \`$.N\` — currency with N decimals: \`$.2\` → \`$1,234.50\`
+                        - \`,\` — thousands separator: \`1,000,000\`
+                        - \`,.N\` — thousands with N decimals: \`,.2\` → \`1,234,567.89\`
+                        - \`.N\` — fixed N decimals: \`.2\` → \`3.14\`
+                        - \`%\` — percentage (value × 100): \`0.452\` → \`45.2%\`
+                        - \`%.N\` — percentage with N decimals: \`%.1\` → \`45.7%\`
+                    }
+
+                    Alignment and format combine in a single directive cell:
+
+                    ```
+                    {[table]
+                        Item | Amount
+                        < | > $
+                        Widget | 1000000
+                        Gadget | 2500000
+                        **Total** | =SUM(B1:B2)
+                    }
+                    ```
+
+                    The \`Amount\` column is right-aligned and formatted as currency. The formula result and data cells all display as \`$1,000,000\` style. The \`**Total**\` label renders as bold text.
+                }
+            }
+
             # Table Formulas @table-formulas
             {
                 Cells starting with \`=\` are evaluated as formulas. Hover a computed cell in preview to see the original formula.
@@ -282,9 +342,10 @@ Content of Section B.
                 ```
                 {[table]
                     Investor | Shares | Ownership
-                    Seed Fund | 500,000 | 25%
-                    Founder A | 1,000,000 | 50%
-                    Founder B | 500,000 | 25%
+                    < | > , | > %
+                    Seed Fund | 500000 | 0.25
+                    Founder A | 1000000 | 0.50
+                    Founder B | 500000 | 0.25
                     **Total** | =SUM(B1:B3) | =SUM(C1:C3)
                 }
                 ```
@@ -301,6 +362,8 @@ Content of Section B.
                 }
 
                 Errors display in red italic: \`#DIV/0!\` (division by zero), \`#VALUE!\` (bad reference), \`#REF!\` (invalid syntax), \`#NAME!\` (unknown function), \`#CIRCULAR!\` (circular dependency).
+
+                **Tip:** Use numeric values with a column format directive (e.g. \`> $\`) instead of pre-formatted strings like \`$1,000,000\`. Formatted strings are text — formulas cannot reference them.
             }
         }
 
@@ -491,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
 
@@ -541,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

@@ -380,6 +380,69 @@ Content of Section B.
                 ```
             }
 
+            # Column Directives @column-directives
+            {
+                An optional directive row immediately after the header row (or as the first row in a headerless table) controls per-column alignment and number formatting. The directive row is consumed by the parser and never rendered as data.
+
+                # Column Alignment @column-alignment
+                {
+                    Alignment characters in the directive row set the text-align for all cells in that column, including the header:
+
+                    {[.]
+                        - `<` — left (default)
+                        - `>` — right (most useful for numbers and currency)
+                        - `=` — center
+                    }
+
+                    ```
+{[table]
+    Programme | Amount | Status
+    < | > | =
+    Alpha | $1,000,000 | Active
+    Beta | $2,500,000 | Pending
+}
+                    ```
+
+                    If the directive row is absent, all columns default to left alignment. Empty cells in the directive row inherit the default (left).
+                }
+
+                # Column Formatting @column-formatting
+                {
+                    A format token in the directive row causes numeric cells and formula results in that column to be formatted for display. Text cells are unaffected. The format is display-only — formulas always operate on raw numeric values.
+
+                    {[.]
+                        - `$` — currency, no decimals: `1000000` → `$1,000,000`
+                        - `$.N` — currency with N decimals: `$.2` → `$1,234.50`
+                        - `,` — thousands separator, no decimals: `1000000` → `1,000,000`
+                        - `,.N` — thousands with N decimals: `,.2` → `1,234,567.89`
+                        - `.N` — fixed N decimals: `.2` → `3.14`
+                        - `%` — percentage (value × 100, auto decimals): `0.452` → `45.2%`
+                        - `%.N` — percentage with N decimals: `%.1` → `45.7%`
+                    }
+
+                    A directive cell may combine alignment and format, separated by whitespace:
+
+                    ```
+{[table]
+    Item | Amount
+    < | > $
+    Widget | 1000000
+    Gadget | 2500000
+    **Total** | =SUM(B1:B2)
+}
+                    ```
+
+                    All numeric values and formula results in the `Amount` column display as currency (`$3,500,000`). The `**Total**` label renders normally as bold text.
+                }
+
+                # Directive Row Detection @directive-detection
+                {
+                    A row is identified as a directive row when every non-empty cell contains only an alignment character (`<`, `>`, `=`), a format token, or both. It must be the first row after the header (or the first row in a headerless table), and at least one cell must contain a directive.
+
+                    For headerless tables, the directive row functions as a virtual header — it is consumed for its directives but no `<thead>` is rendered.
+                }
+            }
+
             # Table Formulas @table-formulas
             {
                 Table cells whose text begins with `=` (but not `==`) are evaluated as formulas. The result replaces the cell text in rendered output; the original formula is preserved as a tooltip.
@@ -919,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
@@ -1083,7 +1169,17 @@ Content of Section A.
                       | "left" | "center" | "right" ;
         percentage    = digit { digit } [ "." digit { digit } ] "%" ;
         pixels        = digit { digit } "px" ;
-        table_body    = 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 ] [ format_spec ] ;
+        align_char    = "<" | ">" | "=" ;
+        format_spec   = "$" [ "." digits ]
+                      | "," [ "." digits ]
+                      | "." digits
+                      | "%" [ "." digits ] ;
         table_row     = cell { "|" cell } ;
         citations_scope = citations_open ws? citations_body "}" ;
         citations_open  = "{[citations]" ;

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.12",
+  "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

@@ -63,6 +63,105 @@ function parseTableOptions(text) {
   return options;
 }
 
+// ── Column directive row (alignment + format) ──────────────────────────
+
+function isDirectiveRow(cells) {
+  if (cells.length === 0) return false;
+  const pattern = /^([<>=])?\s*(\$(?:\.\d+)?|,(?:\.\d+)?|\.\d+|%(?:\.\d+)?)?$/;
+  let hasDirective = false;
+  for (const cell of cells) {
+    const trimmed = cell.trim();
+    if (trimmed === "") continue;
+    if (!pattern.test(trimmed)) return false;
+    hasDirective = true;
+  }
+  return hasDirective;
+}
+
+function parseFormatSpec(spec) {
+  if (!spec) return null;
+  if (spec.startsWith("$")) {
+    const decimals = spec.includes(".") ? parseInt(spec.slice(spec.indexOf(".") + 1), 10) : 0;
+    return { prefix: "$", thousands: true, decimals, percent: false };
+  }
+  if (spec.startsWith("%")) {
+    const decimals = spec.includes(".") ? parseInt(spec.slice(spec.indexOf(".") + 1), 10) : -1;
+    return { prefix: "", thousands: false, decimals, percent: true };
+  }
+  if (spec.startsWith(",")) {
+    const decimals = spec.includes(".") ? parseInt(spec.slice(spec.indexOf(".") + 1), 10) : 0;
+    return { prefix: "", thousands: true, decimals, percent: false };
+  }
+  if (spec.startsWith(".")) {
+    const decimals = parseInt(spec.slice(1), 10);
+    return { prefix: "", thousands: false, decimals, percent: false };
+  }
+  return null;
+}
+
+function parseDirectiveRow(cells) {
+  const align = [];
+  const format = [];
+  let hasAlign = false;
+  let hasFormat = false;
+  const fmtPattern = /(\$(?:\.\d+)?|,(?:\.\d+)?|\.\d+|%(?:\.\d+)?)$/;
+
+  for (const cell of cells) {
+    const trimmed = cell.trim();
+    const alignMatch = trimmed.match(/^([<>=])/);
+    const fmtMatch = trimmed.match(fmtPattern);
+
+    let a = null;
+    if (alignMatch) {
+      a = alignMatch[1] === "<" ? "left" : alignMatch[1] === ">" ? "right" : "center";
+      hasAlign = true;
+    }
+    align.push(a);
+
+    let f = null;
+    if (fmtMatch) {
+      f = parseFormatSpec(fmtMatch[1]);
+      hasFormat = true;
+    }
+    format.push(f);
+  }
+
+  return {
+    align: hasAlign ? align : null,
+    format: hasFormat ? format : null,
+  };
+}
+
+function formatNumber(value, spec) {
+  if (spec.percent) {
+    const pct = value * 100;
+    if (spec.decimals < 0) {
+      return (Number.isInteger(pct) ? pct.toString() : pct.toFixed(2).replace(/\.?0+$/, "")) + "%";
+    }
+    return pct.toFixed(spec.decimals) + "%";
+  }
+
+  const negative = value < 0;
+  const absVal = Math.abs(value);
+  let result;
+
+  if (spec.decimals > 0) {
+    result = absVal.toFixed(spec.decimals);
+  } else {
+    result = Math.round(absVal).toString();
+  }
+
+  if (spec.thousands) {
+    const parts = result.split(".");
+    parts[0] = parts[0].replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+    result = parts.join(".");
+  }
+
+  return (negative ? "-" : "") + spec.prefix + result;
+}
+
+// ── End column directive row ────────────────────────────────────────────
+
 class LineCursor {
   constructor(lines) {
     this.lines = lines;
@@ -144,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;
@@ -835,18 +935,31 @@ function parseTableBody(cursor, tableStartLine, options) {
     cursor.next();
   }
 
+  // Detect column directive row (alignment / formatting)
+  // For headerless tables: check rows[0]; for normal tables: check rows[1] (after header)
+  const directiveIndex = options.headerless ? 0 : 1;
+  let columnAlign = null;
+  let columnFormat = null;
+  if (rows.length > directiveIndex && isDirectiveRow(rows[directiveIndex])) {
+    const directives = parseDirectiveRow(rows[directiveIndex]);
+    columnAlign = directives.align;
+    columnFormat = directives.format;
+    rows.splice(directiveIndex, 1);
+  }
+
   const hasOptions = options.borderless || options.headerless || options.width || options.align;
 
+  let tableNode;
   if (options.headerless) {
-    const tableNode = { type: "table", headers: [], rows, lineStart: tableStartLine, lineEnd: cursor.index };
-    if (hasOptions) tableNode.options = options;
-    return tableNode;
+    tableNode = { type: "table", headers: [], rows, lineStart: tableStartLine, lineEnd: cursor.index };
+  } else {
+    const headers = rows.length > 0 ? rows[0] : [];
+    const body = rows.slice(1);
+    tableNode = { type: "table", headers, rows: body, lineStart: tableStartLine, lineEnd: cursor.index };
   }
-
-  const headers = rows.length > 0 ? rows[0] : [];
-  const body = rows.slice(1);
-  const tableNode = { type: "table", headers, rows: body, lineStart: tableStartLine, lineEnd: cursor.index };
   if (hasOptions) tableNode.options = options;
+  if (columnAlign) tableNode.columnAlign = columnAlign;
+  if (columnFormat) tableNode.columnFormat = columnFormat;
   return tableNode;
 }
 
@@ -1705,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");
@@ -1714,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)}"` : "";
@@ -1724,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) {
@@ -2122,15 +2245,23 @@ function formatFormulaResult(cell) {
 function renderTable(table) {
   const dl = dataLineAttrs(table);
   const opts = table.options || {};
+  const colAlign = table.columnAlign || [];
+  const colFormat = table.columnFormat || [];
   const classes = ["sdoc-table"];
   if (opts.borderless) classes.push("sdoc-table-borderless");
   if (opts.headerless) classes.push("sdoc-table-headerless");
   const classAttr = classes.join(" ");
 
+  function cellStyle(colIndex) {
+    const align = colAlign[colIndex];
+    if (!align || align === "left") return "";
+    return ` style="text-align:${align}"`;
+  }
+
   let thead = "";
   if (table.headers.length > 0) {
     const headerCells = table.headers
-      .map((cell) => `<th class="sdoc-table-th">${renderInline(cell)}</th>`)
+      .map((cell, c) => `<th class="sdoc-table-th"${cellStyle(c)}>${renderInline(cell)}</th>`)
       .join("");
     thead = `<thead class="sdoc-table-head"><tr>${headerCells}</tr></thead>`;
   }
@@ -2142,16 +2273,33 @@ function renderTable(table) {
     .map((row, r) => {
       const cells = row
         .map((cell, c) => {
+          const style = cellStyle(c);
+          const fmt = colFormat[c] || null;
+
           if (isFormulaCell(cell)) {
             const result = grid[r][c];
-            const display = escapeHtml(formatFormulaResult(result));
+            let display;
+            if (!result.error && fmt) {
+              display = escapeHtml(formatNumber(result.value, fmt));
+            } else {
+              display = escapeHtml(formatFormulaResult(result));
+            }
             const formula = escapeAttr(cell.trim());
             if (result.error) {
-              return `<td class="sdoc-table-td sdoc-formula-error" title="${formula}">${display}</td>`;
+              return `<td class="sdoc-table-td sdoc-formula-error"${style} title="${formula}">${display}</td>`;
+            }
+            return `<td class="sdoc-table-td sdoc-formula-cell"${style} title="${formula}">${display}</td>`;
+          }
+
+          // Apply column format to numeric data cells
+          if (fmt) {
+            const parsed = parseCellValue(cell);
+            if (!isNaN(parsed.value)) {
+              return `<td class="sdoc-table-td"${style}>${escapeHtml(formatNumber(parsed.value, fmt))}</td>`;
             }
-            return `<td class="sdoc-table-td sdoc-formula-cell" title="${formula}">${display}</td>`;
           }
-          return `<td class="sdoc-table-td">${renderInline(cell)}</td>`;
+
+          return `<td class="sdoc-table-td"${style}>${renderInline(cell)}</td>`;
         })
         .join("");
       return `<tr>${cells}</tr>`;
@@ -2803,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 = `
@@ -2940,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;
@@ -2957,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 = {};
@@ -2988,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
@@ -3306,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) {
@@ -3531,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) {