sdocs-dev 1.14.1 → 1.18.0

package/lib/help-text.js

@@ -12,6 +12,8 @@ USAGE
   sdoc <file> --style              Open with style panel
   sdoc <file> --raw                Open raw markdown source
   sdoc <file> --comment            Open in comment mode (review/annotate)
+  sdoc <file> 12:"note" 24-28:"note"
+                                   Open a guided document walkthrough
   sdoc bridge <file>               Live editing session: edits autosave to disk,
                                    external changes push to the page (see LIVE BRIDGE)
   sdoc new                         New blank document (write mode)
@@ -22,6 +24,7 @@ USAGE
   sdoc charts                      Chart types, options, and styling guide
   sdoc diagrams                    Mermaid diagrams reference (\`\`\`mermaid blocks)
   sdoc videos                      YouTube embed reference (\`\`\`video blocks)
+  sdoc apps                        Runnable HTML reference (\`\`\`sdoc-app blocks)
   sdoc cells                       Inline spreadsheet reference (\`\`\`cells blocks)
   sdoc code                        Syntax highlighting + code-viewer reference
   sdoc app.rb / server.js / ...    Open a source file as a highlighted listing
@@ -35,16 +38,24 @@ USAGE
   sdoc slides list                 Built-in slide template registry + slot names
   sdoc slides icons [query]        Lucide icon names available to the \`icon\` shape kind
   sdoc slides custom-shapes        Raw-shape primitives + design principles reference
+  sdoc slides verify <file>        Validate slide syntax and geometry without a browser
+  sdoc slides verify <file> --json Machine-readable validation output for agents
   sdoc present <file>              Open <file> and jump straight into fullscreen slides
   sdoc library                     Open the personal markdown library at smalldocs.org/library
   sdoc library ls                  List markdown indexed in this project (walks up to .git)
   sdoc library ls --tags           Tag bag (tag - count) for this project
   sdoc library --help              Full library reference - commands, tagging, rescue, autostart
+  sdoc cloud login                 Sign this CLI into SmallDocs Cloud once
+  sdoc cloud status --json         Check the connected Cloud account
+  sdoc cloud ls                    List Cloud documents
+  sdoc cloud search "query"        Search Cloud documents
+  sdoc cloud create file.md        Add a document to Cloud
+  sdoc cloud --help                Full Cloud command reference
   sdoc <file> +tag1 +tag2          Inject tags into the file's front matter at open time
   sdoc defaults                    Show ~/.sdocs/styles.yaml
   sdoc defaults --reset            Remove default styles
-  sdoc setup                       Wire SmallDocs into your coding agents
-  sdoc refresh                     Update the SmallDocs section in agent files to the current version
+  sdoc setup                       Install the SmallDocs skill for your coding agents
+  sdoc refresh                     Refresh the SmallDocs skill to the current version
   sdoc auto-update [on|off]        Toggle auto-install of sdoc updates
   sdoc upgrade                     Upgrade sdoc to the latest version now
   sdoc safe                        Verify the SmallDocs server is running the published code
@@ -72,7 +83,7 @@ OPTIONS
   --mode <m>            Alias for --read / --write / --style / --raw / --comment
   --short               Use the encrypted /s/<id> short-URL form (share
                         subcommand only). See SHORT LINKS below.
-  --json                Machine-readable output (safe subcommand only).
+  --json                Machine-readable output for safe and Cloud commands.
   --audit               Also print GitHub links to server-side source
                         files (safe subcommand only).
   --keep-open           feedback subcommand: keep the bridge alive across
@@ -86,6 +97,22 @@ OPTIONS
 ENVIRONMENT
   SDOCS_URL   Fallback base URL if --url is not passed.
 
+DOCUMENT WALKTHROUGHS
+  Add notes after a Markdown filename to guide a reader through the
+  rendered document:
+
+    sdoc report.md 12:"Start with the result" 24-28:"Compare these figures"
+
+  Each source line or range becomes a highlighted target followed by a
+  markdown note with Prev / Next controls. Steps follow command argument
+  order, not source order. A prose line highlights its matching rendered
+  text. A line inside an ordinary code fence highlights that code line
+  and places the note beneath it. A chart, diagram, sheet, slide, form,
+  math block, or video is highlighted as one complete rendered element.
+
+  The annotations ride in the URL and through sdoc share. The source file
+  is unchanged.
+
 INTERACTIVE FEEDBACK (sdoc feedback)
   An agent writes a fenced \`\`\`form block into a markdown file and runs
   \`sdoc feedback file.md\`. The browser renders real form controls
@@ -146,7 +173,6 @@ LIBRARY (personal, on-machine index)
     sdoc library                Open the search UI.
     sdoc library ls             List indexed files in this project.
     sdoc library ls --tags      Tag bag (tag - count) for this project.
-    sdoc library rebuild        Walk \$HOME and refresh every entry.
     sdoc library status         Show enabled/disabled + entry count.
     sdoc library autostart      Manage the macOS LaunchAgent.
 
@@ -978,6 +1004,141 @@ SECURITY
 `;
 
 
+const APPS_HELP = `
+SmallDocs - Runnable HTML
+========================
+Run a self-contained HTML document inside Markdown using a \`\`\`sdoc-app
+fenced code block. The component appears inline and can expand to fill the
+browser window. Use this for interactive models, calculators, simulations,
+and other agent-authored browser tools.
+
+BASIC SYNTAX
+  \`\`\`sdoc-app
+  <!doctype html>
+  <html>
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Counter</title>
+  </head>
+  <body>
+    <button id="count">Count: 0</button>
+    <script>
+      let value = 0;
+      const button = document.getElementById('count');
+      button.onclick = () => button.textContent = 'Count: ' + (++value);
+    </script>
+  </body>
+  </html>
+  \`\`\`
+
+AUTHORING
+  - Put one complete HTML document in each block.
+  - Use <title> to name the component in its toolbar and fullscreen view.
+  - CSS, inline JavaScript, canvas, SVG, forms, and browser-native controls work.
+  - Package required data and code in the document when the component should
+    keep working without an external service.
+  - An ordinary \`\`\`html fence remains a highlighted source listing.
+
+INHERITED DESIGN
+  Bare semantic HTML starts with the SmallDocs document's current typography,
+  text and heading colours, background, accent, border, surface, spacing, and
+  corner radius. Native controls receive the same font and a restrained base
+  treatment. These values update when the document theme or styles change.
+
+  The defaults live in a low-priority CSS layer. Ordinary component CSS wins.
+  Override individual values through these custom properties:
+
+    --sdoc-app-background          --sdoc-app-surface
+    --sdoc-app-color               --sdoc-app-heading-color
+    --sdoc-app-muted-color         --sdoc-app-accent-color
+    --sdoc-app-border-color        --sdoc-app-font-family
+    --sdoc-app-heading-font-family --sdoc-app-code-font-family
+    --sdoc-app-font-size           --sdoc-app-line-height
+    --sdoc-app-heading-scale
+    --sdoc-app-h1-size             --sdoc-app-h2-size
+    --sdoc-app-h3-size             --sdoc-app-h1-weight
+    --sdoc-app-h2-weight           --sdoc-app-h3-weight
+    --sdoc-app-radius              --sdoc-app-block-spacing
+    --sdoc-app-padding             --sdoc-app-color-scheme
+
+  Example override:
+
+    :root { --sdoc-app-background: #101827; --sdoc-app-color: #f8fafc; }
+    body { padding: 12px; }
+
+  Do not repeat a body reset, font stack, or page background when the inherited
+  design is appropriate. Add CSS for the component's layout and intentional
+  visual differences. The bundled Inter faces load inside the component.
+  Load other webfonts inside the component when their exact face is required.
+
+VISUAL DIRECTION
+  Let the tool's purpose determine its layout. Start with semantic HTML and the
+  inherited design, then add treatment where it clarifies hierarchy, grouping,
+  state, or interaction.
+
+  - Try a clear page, list, table, or form before turning every region into a
+    dashboard card. Use a canvas or stage when the interaction is spatial.
+    Whitespace and dividers are often enough to structure repeated rows.
+    For repeated records, try one list with border-bottom separators before
+    wrapping every record in its own card.
+  - Reserve a bordered or raised surface for content that needs to read as a
+    separate group, selection, or interaction. Avoid stacking several levels
+    of rounded containers only to create hierarchy.
+  - Keep a consistent shape language and begin with the inherited radius.
+    Pills suit compact statuses and category choices; ordinary actions and
+    metrics do not need to become pills.
+  - For an ordinary document tool, leave the inherited design tokens unchanged
+    unless the brief calls for a distinct visual direction. Add semantic colour
+    when it carries meaning. Gradients, glows, and shadows should support the
+    subject or interaction rather than decorate empty space.
+  - Accent rails, badges, uppercase eyebrows, and wide letter spacing are
+    conspicuous patterns. Use them when they communicate something specific,
+    not as automatic decoration. A title does not also need an eyebrow unless
+    that label adds context the title does not contain.
+  - Match density to the task. Repeated controls should read as efficient rows;
+    the primary result or working area should receive the strongest emphasis.
+    A few totals can often share one summary line or bar instead of separate
+    metric cards.
+
+SIZING AND RESPONSIVE LAYOUT
+  The component owns its inline height. SmallDocs measures the complete
+  document and follows that height without imposing a minimum or maximum. The
+  frame width follows the SmallDocs reading column. Fullscreen uses the
+  available browser viewport.
+
+  - Include a viewport meta tag in every component.
+  - Let normal document flow determine height when content can grow.
+  - Use the component's own CSS min-height, height, or aspect-ratio when an
+    interactive canvas or stage needs a deliberate working area.
+  - Avoid fixed page widths. Use fluid widths, grid or flex wrapping, media or
+    container queries, and controls that remain usable at narrow widths.
+  - Resize canvas and other measured graphics from their rendered container.
+    ResizeObserver and the normal window resize event are available.
+  - Check the component inline and fullscreen at both narrow and wide widths.
+
+  A concise inline height keeps the surrounding document easy to navigate.
+  Dense tools can use more space or rely on the expand control. These are
+  authoring choices rather than renderer limits.
+
+VIEWING
+  Expand opens the same running frame fullscreen, so its current inputs and
+  JavaScript state remain in place. When a document has several components,
+  Previous and Next move between them.
+
+BROWSER BOUNDARY
+  Component code runs in a sandboxed frame. It cannot read the SmallDocs page,
+  browser storage for smalldocs.org, or account controls. Scripts can use forms,
+  modals, downloads, and popups. Network requests still leave the browser and
+  are subject to the destination's CORS rules, so a document can communicate
+  with services that allow it.
+
+FAILURE BEHAVIOUR
+  If the runner cannot start or does not respond within 15 seconds, SmallDocs
+  leaves the component source readable in an error panel. Re-rendering or
+  destroying an SDK instance removes its frames and event listeners.
+`;
+
+
 const CELLS_HELP = `
 SmallDocs - Cells (sheets)
 ======================
@@ -1018,27 +1179,40 @@ WRAPPING
   text - markup never renders.
 
 FORMATTING
-  Numbers display with thousands separators and negatives in red by default.
-  An optional first line sets per-column formats by column letter:
+  Numbers display with thousands separators and up to two decimal places by
+  default. Negatives are red. One or more leading format: lines can control a
+  sheet, column, row, or individual cell:
 
   \`\`\`cells
-  format: A=plain B=$ C=%
+  format: A=plain B=$ C=% C4=%.1
   Year,Revenue,Margin
   2024,12000,0.23
   \`\`\`
 
   Renders 2024 (plain - no comma), $12,000.00, 23%.
 
-  Format tokens (keyed by column letter):
+  Targets use familiar sheet addresses:
+    *              whole sheet
+    A              column A
+    4              row 4
+    C4             cell C4
+
+  A cell overrides its row, a row overrides its column, and a column overrides
+  the whole sheet. This makes \`format: B=$ B4=%\` a currency column with one
+  percentage cell.
+
+  Format tokens:
     $ / usd        currency, e.g. $12,000.00   (also £ / gbp, € / eur)
     %              percent - multiplies by 100, e.g. 0.23 -> 23%
-    , / number     thousands separators (the default)
+    , / number     thousands separators
     plain / text   no number formatting (good for years, ids, codes)
-    .N suffix      fixed decimals, e.g. $.0 (no cents), %.1, .2
+    .N suffix      fixed decimals, attached directly: $.0, %.1, .2
 
-  Formatting is display only - copy and export always emit the original
-  values. This is what makes a cells block more than a CSV: the author
-  chooses how each column reads.
+  Each target accepts one format token. Use C=%.2, not C=%,.2. Unknown or
+  malformed rules are ignored without changing the sheet's data.
+
+  Formatting changes appearance, not the underlying values. Copy preserves
+  the source values; Excel export preserves both the values and number formats.
 
 FORMULAS
   A cell whose value starts with = is a formula, evaluated in the browser.
@@ -1287,7 +1461,8 @@ EXPORT
   formulas and recalculate when the file opens; the format: directive's
   currency / percent / comma columns carry over as Excel number formats.
   The export uses the document's row order (plus any fullscreen edits),
-  never the sorted view, so formula references stay correct.
+  never the sorted view, so formula references stay correct. Sheet, column,
+  row, and cell number formats carry over to Excel.
 `;
 
 const SLIDES_HELP = `
@@ -1299,6 +1474,31 @@ present-mode icon in the slide's top-right corner to enter fullscreen.
 Text inside a slide thumbnail is selectable. Esc to exit, arrows to
 navigate.
 
+\u2500\u2500 START HERE \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  Use \`@extends\` for covers, section breaks, quotations, simple
+  text, and layouts that repeat. Fill named slots and the template
+  handles layout, spacing, and alignment for you:
+
+    ~~~slide
+    @extends title-body
+    #title: What is SmallDocs?
+    #body:
+    - Markdown in, styled docs out
+    - No server, hash-only state
+    ~~~
+
+  Run \`sdoc slides list\` for the template + slot names (cover,
+  title-body, two-column, three-column, exhibit, quote, metric,
+  section, closing).
+
+  Use custom shapes when geometry explains the idea: a process,
+  architecture, hierarchy, comparison, feedback loop, market
+  structure, or causal model. This applies to internal presentations
+  too. An internal audience should be able to see the model instead
+  of reconstructing it from title-and-bullet slides. Mix templates
+  and custom slides in the same deck. Read DESIGN GUIDELINES and
+  \`sdoc slides custom-shapes\` before hand-placing shapes.
+
 \u2500\u2500 COMMANDS \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
   sdoc present <file>              Open file directly in fullscreen slide view
   sdoc <file>                      Open normally (click a slide's present icon)
@@ -1306,9 +1506,11 @@ navigate.
   sdoc slides list                 List built-in templates + slot names
   sdoc slides icons [query]        List the Lucide icons available to the
                                    \`icon\` shape kind. Optional substring filter.
-  sdoc slides custom-shapes        Long-tail notes for raw-shape custom slides
-                                   (polygon text, composite patterns, layering).
-                                   Most decks use \`@extends\` and never need this.
+  sdoc slides custom-shapes        Shape syntax and design guidance for visual
+                                   explanations, diagrams, and custom layouts.
+  sdoc slides verify <file>        Validate every slide headlessly. Exit 0 when
+                                   clean, 1 for diagnostics, or 2 for bad usage.
+  sdoc slides verify <file> --json Return the same result as structured JSON.
 
 ── DESIGN GUIDELINES ────────────────────────────────────
   The built-in templates encode a few rules that separate professional
@@ -1316,6 +1518,14 @@ navigate.
   template), keep these in mind - they're the difference between a
   deck that lands and one that doesn't.
 
+  Match the layout to the information. Templates are the fast path
+  for covers, section breaks, simple text, and repeated structures.
+  Raw shapes are the explanatory path when position, direction,
+  grouping, size, or sequence carries meaning. Audience type does
+  not decide this: internal architecture and process decks often
+  benefit most from a visual model. See \`sdoc slides custom-shapes\`
+  for the shape vocabulary and the design principles that go with it.
+
   Margins. Keep all content inside a 1-unit safe area on every side
   of a 16x9 grid (so x ∈ [1, 15], y ∈ [0.5, 8.5]). Nothing touches
   the slide edge except a deliberate full-bleed background (\`section\`
@@ -1346,9 +1556,13 @@ navigate.
   Caption renders as ~3px in a 240px-wide thumbnail - never put
   load-bearing content in caption role.
 
-  Default \`valign=center\`. \`valign=top\` reads right only when the
-  body shape is sized to its content. On an oversized body shape
-  top-anchoring leaves dead space underneath; centering balances it.
+  Use \`valign=top\` for body copy - bullets, paragraphs, columns.
+  Text has a reading order and a top edge readers expect just under
+  the title, so anchor it there and let it grow down. \`valign=center\`
+  is for a single short block that balances its box or a neighbouring
+  visual (a takeaway beside a chart, a caption, a lead line) - not for
+  a list. If a top-anchored body leaves dead space below, shrink the
+  shape rather than re-centering the text.
 
   Content fills 55-65% of the safe area, no more. Empty space is a
   feature: it's what makes a deck feel confident rather than crowded.
@@ -1366,9 +1580,56 @@ navigate.
   A bulleted paragraph is hiding the fact that you haven't decided
   what you're claiming.
 
-  When in doubt, \`@extends\` a built-in template instead of
-  composing from raw shapes. Run \`sdoc slides list\` to see the
-  registry.
+  Do not default an internal deck to title-and-bullet templates.
+  If the slide explains relationships, stages, or movement, compose
+  those relationships with shapes. If a custom layout repeats across
+  slides, define it once as your own \`@template\` and \`@extends\` it -
+  the consistency of a template with a look you designed.
+
+\u2500\u2500 VERIFYING A DECK (OPTIONAL, BUT IT IS WHAT SEPARATES CLEAN FROM BROKEN) \u2500\u2500
+  Run \`sdoc slides verify <file> --json\` after authoring. It uses the
+  same parser, template resolver, reference resolver, and bounds check
+  as the browser. Fix every reported problem or acknowledge intentional
+  off-canvas decoration on that shape with \`bleed=allow\`, then run it
+  again. The command exits 0 only when the deck is clean.
+
+  You are authoring slides you cannot see. You place coordinates and
+  trust them, and the renderer does not warn you when a shape covers
+  text, when a label wraps to a line you did not intend, when text sits
+  on a fill it cannot be read against, or when an arrow lands in empty
+  space. Templates mostly avoid this; hand-placed raw shapes do not.
+  The single most effective check is to look at the rendered result and
+  fix what you see.
+
+  If you have a way to render a page to an image - a headless browser
+  you can drive (Playwright or Puppeteer in headless mode, a headless
+  system Chrome), or any screenshot tool in your environment - use it.
+  Open the deck, capture the slides, look, fix the DSL, and render
+  again. Two or three passes turns a deck with hidden text and clipped
+  labels into one that reads cleanly. When you render, check each slide
+  for:
+    - text covered by a shape drawn after it (source order is paint order)
+    - text with poor contrast against whatever is actually painted under it
+    - labels that wrap or overflow their box
+    - connectors (l / a) that float short of, or pierce, what they join
+    - a composition that sits low, high, or lopsided in the frame
+
+  The CLI does not bundle a browser - it has no runtime dependencies on
+  purpose - so this check is something you bring from your environment,
+  not something sdoc installs. If you do not have a headless browser and
+  you judge that rendering would catch real problems, you can ask your
+  user to install one (for example \`npx playwright install chromium\`, or
+  to point you at a browser already on the machine) and explain why: a
+  render check catches the text-overlap, contrast, and wrapping faults
+  that are invisible in the markdown source. Leave the decision to them;
+  it is their machine, and the subtleties of what is available are yours
+  to work out in context.
+
+  \`sdoc present <file>\` opens the deck fullscreen for a human to review,
+  which is the right check when a person is in the loop. If you cannot
+  render at all, keep each slide simple enough to verify by arithmetic -
+  list every text shape's box and confirm no later shape's fill overlaps
+  it - and prefer templates for anything you will not be able to see.
 
 \u2500\u2500 FENCE SYNTAX \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
   Wrap shape DSL in a ~~~slide fenced block:
@@ -1586,7 +1847,8 @@ navigate.
   Everything after \`|\` is standard markdown. Multi-line uses
   indentation under the shape line - continuation lines MUST be
   indented at least 2 spaces, or the parser treats them as fresh
-  top-level shape lines (and fails).
+  top-level shape lines (and fails). In short inline labels, \`\\n\`
+  inserts a visible line break; \`\\\\n\` keeps the literal text \`\\n\`.
 
     r 5 20 90 60 align=left |
       ## Heading
@@ -1609,17 +1871,20 @@ navigate.
     - Title shapes (one heading or phrase)
     - Subheaders, section labels
     - Standalone caption text
+    - A single short block balancing a box or a neighbouring visual
 
-  Switch to \`align=left\` when the shape holds body copy - paragraphs,
-  bullet lists, numbered lists, blockquotes. Left-aligned reads better
-  once you have multiple lines. Keep \`valign=center\` (the default) so
-  the block floats in the middle of the shape; switch to \`valign=top\`
-  only when the shape is sized exactly to the content and you want it
-  anchored to the top.
+  Switch to \`align=left valign=top\` when the shape holds body copy -
+  paragraphs, bullet lists, numbered lists, blockquotes. Left-aligned
+  reads better once you have multiple lines, and top-anchoring puts the
+  first line just under the title where the reader looks first.
+  Centering a list in an oversized box floats it toward the middle, so
+  the gap under the title reads as a mistake. If top-anchoring leaves
+  dead space below, shrink the shape - don't re-center the text.
 
   Rule of thumb:
-    ONE short phrase  \u2192  leave centered
-    MULTIPLE lines    \u2192  align=left, keep valign=center
+    ONE short phrase / balancing block   \u2192  center both axes
+    MULTIPLE lines / bullets / columns   \u2192  align=left valign=top
+    Footer / attribution label           \u2192  valign=bottom
 
 \u2500\u2500 PULLING FROM DOC STYLES \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
   Slides pick up the host document's styles so a deck feels visually
@@ -1896,7 +2161,8 @@ navigate.
 
   Common errors:
     - "shape extends outside grid WxH"   bbox past an edge by >10% of the
-                                         grid (a little bleed is allowed)
+                                         grid. Add \`bleed=allow\` only when
+                                         that individual shape is intentional
     - \`unknown id "@name"\`               @-ref before the shape is declared
     - \`duplicate id "#name"\`             two shapes share an id
     - \`invalid attribute key\`            key must start with a letter
@@ -1910,10 +2176,10 @@ navigate.
 const SLIDES_CUSTOM_SHAPES_HELP = `
 SmallDocs — Slides (raw shapes)
 ===========================
-Reference + design notes for slides built from raw shapes rather than
-the stdlib templates. Most decks won't need any of this - if you can
-express the slide via \`@extends\` on a built-in (cover, title-body,
-two-column, exhibit, etc.), do that.
+Reference + design notes for slides built from raw shapes. Use templates
+for simple or repeated layouts. Use these shapes when geometry explains
+a process, architecture, hierarchy, comparison, or causal model, including
+in internal presentations.
 
 Read DESIGN PRINCIPLES first. The syntax reference below assumes you've
 made the visual choices the principles describe. Without them, raw
@@ -2051,6 +2317,18 @@ rather than as designed.
     overlay text on a single patch of colour (or very closely
     related colours) to keep it straightforwardly legible.
 
+  Attempt to verify what you cannot see.
+    The principles above guide the layout, but a hand-placed shape
+    can still cover text, a label can wrap, or an arrow can miss its
+    target, and none of it shows in the source. If you can drive a
+    headless browser or any screenshot tool in your environment,
+    render the deck and fix what you see before trusting it. If you
+    cannot, it is worth raising with your user - for example, "I
+    would like to use Playwright to verify the slides render
+    correctly, is that okay?" - since a quick render check catches
+    problems the markdown cannot show. See the VERIFYING A DECK
+    section of \`sdoc slides\` for what to look for.
+
 ── SHAPE KINDS ───────────────────────────────────────
   r x y w h            rectangle  (x,y = top-left; w,h = size)
   i x y w h            image rect (sugar for \`r\` with \`image=\`; see IMAGES)
@@ -2215,7 +2493,8 @@ rather than as designed.
   All shapes EXCEPT \`l\` and \`a\` can hold markdown after \`|\` - full
   markdown (headings, lists, bold/italic, code, blockquote, tables).
   Non-rectangle shapes use their bounding box as the text area (see
-  the TEXT INSIDE NON-RECT SHAPES section).
+  the TEXT INSIDE NON-RECT SHAPES section). In a short inline label,
+  \`\\n\` inserts a visible line break.
 
   No \`fill=\` on a shape -> transparent (slide background shows through).
   Color values accept any CSS colour: hex (#1e40af), named (tomato),
@@ -2394,6 +2673,8 @@ rather than as designed.
                         backdrops, ghosted "previous state" shapes,
                         overlapping highlights. Out-of-range values
                         clamp.
+    bleed=allow         Acknowledge intentional off-canvas overflow for
+                        this shape. Other shapes are still checked.
 
   Numeric attributes (strokeWidth, radius) are in grid units - pick
   values relative to your grid size, no prescribed defaults. On a
@@ -2644,14 +2925,8 @@ COMMANDS
                                           bag (tag - count, sorted by
                                           frequency). Run before tagging
                                           a new file to stay consistent.
-    sdoc library status                   Print enabled/disabled, entry
-                                          count, last scan time.
-
-  Refresh
-    sdoc library rebuild                  Walk \$HOME again from scratch
-                                          and refresh every entry. Use
-                                          after moving files around or
-                                          when an entry seems stale.
+    sdoc library status                   Print enabled/disabled and the
+                                          current entry count.
 
   On/off
     sdoc library enable                   Re-enable indexing-on-open if
@@ -2684,9 +2959,7 @@ COMMANDS
     sdoc library help                     Same.
 
 WHAT GETS INDEXED
-  Every file you open with \`sdoc <file>\` is recorded at open time.
-  \`sdoc library rebuild\` additionally walks \$HOME looking for
-  markdown that fits these rules:
+  Every file you open with \`sdoc <file>\` is recorded at open time when:
     - extension is .md, .mdx, or .markdown
     - size is at most 1 MB
     - not under a hidden directory (.git, .venv, .cache, ...)
@@ -2860,8 +3133,8 @@ PRIVACY MODEL
 
 COMMON QUESTIONS
   Q: I opened a file but I don't see it in the library.
-  A: Check \`sdoc library status\` (is it enabled?), then
-     \`sdoc library rebuild\`. If the file is in front matter
+  A: Check \`sdoc library status\` (is it enabled?), then open the file
+     again with \`sdoc <file>\`. If the file is in front matter
      \`sdocs-library: false\`, that's the opt-out. Also check for a
      .sdocsignore in the file's directory or any ancestor.
 
@@ -2931,6 +3204,23 @@ ANNOTATIONS (walk someone through the code)
   an agent explaining code to the reader; the in-browser comment mode
   (--comment) is the reverse - the reader's own review notes.
 
+  Annotations render as a WALKTHROUGH: the file opens in the fullscreen viewer
+  with each note carrying a Prev / Next stepper, so the reader is guided from
+  one note to the next (arrow keys work too; a restart button returns to the
+  start). The steps follow the ORDER YOU PASS THEM, not line order:
+
+    sdoc app.py 10:"start here" 5:"then jump back up here"
+
+  walks to line 10 first, then line 5.
+
+  Pass several files to narrate across them - each becomes a tab, and a step
+  in another file switches to its tab as you walk (a small "-> file" marker
+  shows when a step crosses files):
+
+    sdoc app.py 5:"entry point" util.py 12:"it calls into here" app.py 9:"back"
+
+  Naming a file twice gives one tab; the walk still hops between them in order.
+
 COMMENTS
   Comments are deliberately prominent - italic, full-contrast colour, a faint
   tint - rather than the usual muted grey, so the human explanation in a
@@ -2947,4 +3237,4 @@ SUPPORTED LANGUAGES
   they appear. An unknown language label renders as plain text.
 `;
 
-module.exports = { HELP, COMMENTS_HELP, SCHEMA, CHARTS_HELP, DIAGRAMS_HELP, VIDEOS_HELP, CELLS_HELP, CODE_HELP, SLIDES_HELP, SLIDES_CUSTOM_SHAPES_HELP, LIBRARY_HELP };
+module.exports = { HELP, COMMENTS_HELP, SCHEMA, CHARTS_HELP, DIAGRAMS_HELP, VIDEOS_HELP, APPS_HELP, CELLS_HELP, CODE_HELP, SLIDES_HELP, SLIDES_CUSTOM_SHAPES_HELP, LIBRARY_HELP };