@entropicwarrior/sdoc 0.2.13 → 0.2.15

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/docs/reference/slide-authoring.sdoc

@@ -239,6 +239,84 @@
         }
     }
 
+    # Drilldown Slides @drilldown
+    {
+        A slide deck is normally a 1D spine: Right and Left move along it. A
+        spine slide can also have *vertical detail slides* — extra material
+        you can pull up on demand without cluttering the main flow. Mark a
+        child scope with the `:detail` annotation and it becomes a vertical
+        slide under its parent.
+
+        # Syntax @drilldown-syntax
+        {
+            ```
+            # ETHyR Mechanism @ethyr {
+                Main spine content.
+
+                # PCR primer @pcr :detail {
+                    Detail slide one.
+                }
+
+                # HCR primer @hcr :detail {
+                    Detail slide two.
+                }
+
+                # Notes @notes {
+                    Speaker notes still work alongside details.
+                }
+            }
+            ```
+
+            A detail slide is a regular slide. It can have its own `config:
+            center`, two-column layout, speaker `@notes`, and any other slide
+            content. Drilldowns do not nest further: a `:detail` inside a
+            `:detail` is treated as a plain nested scope.
+        }
+
+        # Navigation @drilldown-navigation
+        {
+            Right — advance one step. From a spine slide, move to the next
+            spine. From a detail slide, advance to the next detail in the
+            same column; at the last detail, return to the parent spine and
+            advance to the next spine (reveal.js convention).
+
+            Left — mirror of Right. From a detail, previous detail or back
+            to parent spine; from spine, previous spine.
+
+            Down — drill into the first detail of the current spine; from
+            within a column, advance to the next detail.
+
+            Up — return from a detail to its parent spine. No-op on a spine.
+
+            Swipe — horizontal swipes mirror Left / Right; vertical swipes
+            mirror Up / Down.
+
+            URL hash — spine slides use `#N`; detail K of spine N uses
+            `#N.K`.
+        }
+
+        # Visual Affordances @drilldown-visual
+        {
+            Spine slides that have detail children get the
+            `slide-has-details` class — the default theme shows a small
+            animated chevron at the bottom of the slide. Themes can replace
+            this rule to fit their own visual language.
+
+            Every slide also gets a `.slide-indicator` element in the
+            bottom-right corner: `5 / 14` on a spine, `5.2 / 14` on detail 2
+            of slide 5. The denominator is always the spine count, so the
+            indicator stays stable as you drill in.
+        }
+
+        # PDF Export @drilldown-pdf
+        {
+            PDF export flattens the deck: spine 1, its details in order,
+            spine 2, its details in order, and so on. This is the same order
+            slides appear in the HTML, so PDF export needs no special case —
+            every slide is just one page.
+        }
+    }
+
     # Theme System @themes
     {
         Themes control the visual appearance of slides. A theme is a directory
@@ -269,17 +347,23 @@
         {
             All themes include these controls by default:
 
-            Arrow right or Space — next slide.
+            Arrow right or Space — next slide (or next detail).
+
+            Arrow left — previous slide (or previous detail).
+
+            Arrow down — drill into details (if any).
 
-            Arrow left — previous slide.
+            Arrow up — return from details to the spine slide.
 
             Home — first slide.
 
-            End — last slide.
+            End — last spine slide.
 
-            Touch swipe left/right on mobile devices.
+            Touch swipe horizontal / vertical on mobile devices.
 
-            Slide counter shown in the bottom-right corner.
+            Slide counter (`.slide-indicator`) shown in the bottom-right
+            corner — `N / TOTAL` on spine slides, `N.K / TOTAL` on detail K
+            of spine N. See [Drilldown Slides](#drilldown) for details.
         }
     }
 

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.15",
   "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/src/slide-renderer.js

@@ -206,18 +206,45 @@ function extractNotes(children) {
   return { notes, contentNodes: rest };
 }
 
+// Separates :detail child scopes (drilldown / vertical slides) from other
+// children. Detail scopes are NOT removed from rendering; they are emitted as
+// sibling slides positioned vertically under the spine slide.
+function extractDetails(children) {
+  const details = [];
+  const rest = [];
+  for (const child of children) {
+    if (child.type === "scope" && child.scopeType === "detail") {
+      details.push(child);
+    } else {
+      rest.push(child);
+    }
+  }
+  return { details, contentNodes: rest };
+}
+
 // ---------------------------------------------------------------------------
 // Slide rendering
 // ---------------------------------------------------------------------------
 
-function renderSlide(scope, slideIndex, overlayHtml) {
-  const { config, contentNodes: afterConfig } = extractSlideConfig(scope.children);
+// position: { spine: 1-based spine index, detail: 0 for spine, 1..N for details,
+//             totalSpines: total number of spine slides, hasDetails: bool (spine only) }
+function renderSlide(scope, slideIndex, overlayHtml, position) {
+  // Pull :detail children out first so they don't appear inline in the spine
+  // slide's content; they're rendered as sibling vertical slides instead.
+  const { contentNodes: afterDetails } = extractDetails(scope.children);
+  const { config, contentNodes: afterConfig } = extractSlideConfig(afterDetails);
   const { notes, contentNodes } = extractNotes(afterConfig);
 
   const classes = ["slide"];
   if (config.layout) {
     classes.push(config.layout);
   }
+  if (position && position.detail === 0 && position.hasDetails) {
+    classes.push("slide-has-details");
+  }
+  if (position && position.detail > 0) {
+    classes.push("slide-detail");
+  }
 
   const title = scope.hasHeading !== false && scope.title
     ? `<h2>${renderInline(scope.title)}</h2>`
@@ -248,9 +275,25 @@ function renderSlide(scope, slideIndex, overlayHtml) {
     : "";
 
   const idAttr = scope.id ? ` id="${escapeAttr(scope.id)}"` : "";
-  const overlay = overlayHtml || "";
 
-  return `<div class="${classes.join(" ")}"${idAttr}>\n${title}\n${bodyHtml}${notesHtml}${overlay}\n</div>`;
+  // Drilldown metadata + slide indicator label (substituted into the footer)
+  let dataAttrs = "";
+  let indicatorLabel = "";
+  if (position) {
+    dataAttrs = ` data-spine="${position.spine}" data-detail="${position.detail}"`;
+    const denom = position.totalSpines;
+    indicatorLabel = position.detail === 0
+      ? `${position.spine} / ${denom}`
+      : `${position.spine}.${position.detail} / ${denom}`;
+  }
+  const overlay = (overlayHtml || "").replace("__SLIDE_INDICATOR__", escapeHtml(indicatorLabel));
+
+  // Wrap title + body in a scale container so PDF export can apply
+  // transform: scale() to fit the content onto a fixed page size.  In
+  // screen mode the wrapper is display:contents (invisible to layout); in
+  // print mode it becomes a real block that the beforeprint handler can
+  // measure and scale.
+  return `<div class="${classes.join(" ")}"${idAttr}${dataAttrs}>\n<div class="slide-content-scale">\n${title}\n${bodyHtml}\n</div>${notesHtml}${overlay}\n</div>`;
 }
 
 // ---------------------------------------------------------------------------
@@ -277,7 +320,11 @@ function renderSlides(nodes, options = {}) {
   // Filter to scope nodes only (skip stray paragraphs and :comment scopes)
   const slides = slideScopes.filter((n) => n.type === "scope" && n.scopeType !== "comment");
 
-  // Build per-slide footer: <  CONFIDENTIAL  ---gap---  Company  >
+  // Build per-slide footer:
+  //   <  CONFIDENTIAL  ---gap---  Company  N/Total  >
+  // The indicator slot is rendered as a literal token here and substituted
+  // per-slide inside renderSlide() so all the right-edge elements share one
+  // flexbox row (avoids the page number stacking on top of the company name).
   const footerParts = [];
   footerParts.push(`<span class="nav-prev">&lsaquo;</span>`);
   if (meta.confidential) {
@@ -292,11 +339,42 @@ function renderSlides(nodes, options = {}) {
   if (meta.company) {
     footerParts.push(`<span class="sdoc-company-footer">${escapeHtml(meta.company)}</span>`);
   }
+  footerParts.push(`<span class="slide-indicator">__SLIDE_INDICATOR__</span>`);
   footerParts.push(`<span class="nav-next">&rsaquo;</span>`);
   const overlayHtml = `\n<div class="slide-footer">${footerParts.join("")}</div>`;
 
-  const slidesHtml = slides
-    .map((scope, index) => renderSlide(scope, index, overlayHtml))
+  // Build a flat emission order: each spine slide, followed immediately by its
+  // :detail children in source order. The flat order matches what we want for
+  // PDF export, so PDF needs no special case.
+  const totalSpines = slides.length;
+  const emitted = [];
+  slides.forEach((scope, i) => {
+    const spineIndex = i + 1; // 1-based
+    const { details } = extractDetails(scope.children);
+    emitted.push({
+      scope,
+      position: {
+        spine: spineIndex,
+        detail: 0,
+        totalSpines,
+        hasDetails: details.length > 0
+      }
+    });
+    details.forEach((detail, j) => {
+      emitted.push({
+        scope: detail,
+        position: {
+          spine: spineIndex,
+          detail: j + 1,
+          totalSpines,
+          hasDetails: false
+        }
+      });
+    });
+  });
+
+  const slidesHtml = emitted
+    .map(({ scope, position }, index) => renderSlide(scope, index, overlayHtml, position))
     .join("\n\n");
 
   const title = meta.properties?.title
@@ -327,19 +405,39 @@ function renderSlides(nodes, options = {}) {
   color: rgba(160, 40, 40, 0.6);
   margin-left: 0.8em;
 }
+.slide-indicator {
+  font-size: 0.7em; color: rgba(0,0,0,0.35);
+  font-variant-numeric: tabular-nums;
+  letter-spacing: 0.04em;
+  pointer-events: none;
+  user-select: none;
+  margin-right: 0.6em;
+}
+/* Scale wrapper: invisible to layout in screen mode so existing slide
+   styles (flex centering, two-column grid, etc.) work as-is.  In print
+   mode it becomes a real block element whose transform is set by the
+   beforeprint handler to shrink overflowing content to fit the page. */
+.slide-content-scale { display: contents; }
+
 @media print {
   @page { size: 13.333in 7.5in; margin: 0; }
   body { overflow: visible; height: auto; }
   .slide {
-    display: flex !important;
+    display: block !important;
     position: relative !important;
     opacity: 1 !important;
     pointer-events: auto !important;
     page-break-after: always; break-after: page;
     width: 100vw; height: 100vh; max-width: none;
+    overflow: hidden;
     page-break-inside: avoid; break-inside: avoid;
   }
   .slide:last-child { page-break-after: auto; break-after: auto; }
+  .slide-content-scale {
+    display: block;
+    width: 100%;
+    transform-origin: top left;
+  }
   .nav-prev, .nav-next { display: none !important; }
   .notes { display: none; }
 }`;
@@ -359,6 +457,7 @@ blockquote p { color: #9d9d9d; }
 .nav-prev, .nav-next { color: rgba(255, 255, 255, 0.7); }
 .sdoc-company-footer { color: rgba(255, 255, 255, 0.35); }
 .sdoc-confidential-notice { color: rgba(235, 120, 120, 0.7); }
+.slide-indicator { color: rgba(255, 255, 255, 0.35); }
 ` : "";
 
   const cssTag = `<style>\n${structuralCss}\n${themeCss}\n${darkCss}</style>`;

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);
@@ -133,7 +135,7 @@ async function buildHtml(filePath) {
 
   const title = path.basename(resolvedPath, ".sdoc");
 
-  return renderHtmlDocumentFromParsed(
+  const html = renderHtmlDocumentFromParsed(
     { nodes: metaResult.nodes, errors: parsed.errors },
     title,
     {
@@ -141,8 +143,44 @@ async function buildHtml(filePath) {
       config,
       cssOverride: cssOverride || undefined,
       cssAppend: cssAppendParts.join("\n") || undefined,
+      includeAbout,
     }
   );
+
+  // Inline local images as data URIs so output is self-contained. PDF export
+  // renders from a temp directory, where relative image paths (e.g.
+  // diagrams/foo.svg) no longer resolve; inlining also makes HTML portable.
+  return inlineLocalImages(html, docDir);
+}
+
+const IMAGE_MIME = {
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+};
+
+function inlineLocalImages(html, docDir) {
+  return html.replace(/(<img\b[^>]*?\bsrc=")([^"]*)(")/gi, (match, pre, src, post) => {
+    // Leave remote URLs and already-inlined data URIs untouched.
+    if (/^(https?:|data:|file:)/i.test(src)) return match;
+    const decoded = src.replace(/&amp;/g, "&");
+    const ext = path.extname(decoded).toLowerCase();
+    const mime = IMAGE_MIME[ext];
+    if (!mime) return match;
+    const abs = path.isAbsolute(decoded) ? decoded : path.join(docDir, decoded);
+    let data;
+    try {
+      data = fs.readFileSync(abs);
+    } catch {
+      console.error(`Warning: could not inline image (not found): ${decoded}`);
+      return match;
+    }
+    const uri = `data:${mime};base64,${data.toString("base64")}`;
+    return `${pre}${uri}${post}`;
+  });
 }
 
 async function main() {
@@ -150,12 +188,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 +215,7 @@ async function main() {
     process.exit(1);
   }
 
-  const html = await buildHtml(resolvedInput);
+  const html = await buildHtml(resolvedInput, { includeAbout });
 
   if (htmlMode) {
     if (!outputPath) {
@@ -191,6 +232,7 @@ async function main() {
       outputPath = resolvedInput.replace(/\.sdoc$/i, "") + ".pdf";
     }
     const resolvedOutput = path.resolve(outputPath);
+    fs.mkdirSync(path.dirname(resolvedOutput), { recursive: true });
 
     // Write HTML to temp file for Chrome
     const tmpHtml = path.join(os.tmpdir(), "sdoc-doc-" + Date.now() + ".html");