sdocs-dev 1.15.0 → 1.19.2

package/lib/help-text.js

@@ -12,16 +12,23 @@ 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)
   sdoc share <file>                Copy shareable link to clipboard
   sdoc share <file> --section "X"  Link with section anchor
   sdoc share <file> --short        Encrypted /s/<id> short link (see SHORT LINKS)
+  sdoc share <file> --short --source email-launch
+                                   Short link attributed to a named source
+  sdoc share <file> --short --source x --placement launch-reply-01
+                                   Social link attributed to one placement
   sdoc schema                      Print the full styles schema
   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 +42,27 @@ 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 setup --cloud --yes         Enable Cloud-first opens and install the Cloud skill
+  sdoc setup --cloud --account ID  Use one Cloud account for automatic creates
+  sdoc setup --standard --yes      Return to local-first behavior
+  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 +90,12 @@ 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).
+  --source <name>       Attribute short-link visits to a source or campaign.
+  --placement <id>      Attribute a social short link to one publishing
+                        placement. Use 4-32 letters, numbers, underscores,
+                        or hyphens with --source x, yt, or youtube.
+  --json                Machine-readable output for safe and Cloud commands.
+  --no-open             Do not launch the browser after a normal file open.
   --audit               Also print GitHub links to server-side source
                         files (safe subcommand only).
   --keep-open           feedback subcommand: keep the bridge alive across
@@ -86,6 +109,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 +185,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.
 
@@ -176,6 +214,21 @@ SHORT LINKS (sdoc share --short)
 
   \`--short\` produces a shorter, encrypted form: \`https://smalldocs.org/s/<id>#k=<key>\`.
 
+  Add any source name when publishing a link, for example
+  \`--source email-launch\`, \`--source product-hunt\`, or \`--source x\`.
+  This produces a URL such as
+  \`https://smalldocs.org/s/<id>?src=email-launch#k=<key>\`. The source appears
+  automatically at \`/analytics/sources\`; the visit still counts in the
+  ordinary visit and short-link totals.
+
+  Add \`--placement launch-reply-01\` to an X or YouTube source link
+  when the same document is published in more than one place. This produces
+  \`https://smalldocs.org/s/<id>?src=x&pid=launch-reply-01#k=<key>\`.
+  The placement id is public and identifies the post, reply, or comment where
+  the link was used. It does not identify a visitor. Only links with a valid
+  placement id appear in the targeted-placement table at
+  \`/analytics/sources?type=short\`.
+
   How it works:
     1. The CLI brotli-compresses the content, generates a 256-bit AES-GCM
        key + 96-bit nonce locally, and encrypts the compressed bytes.
@@ -192,6 +245,8 @@ SHORT LINKS (sdoc share --short)
   What the server can see:
     - That a ciphertext blob was uploaded under id <id>.
     - When it was fetched and from which IP (standard server logs).
+    - For an opted-in placement link, its source, public placement id, and
+      short-link id when a visit is counted.
   What the server cannot see:
     - The plaintext document. It does not have the key.
     - The key. The key never leaves the URL fragment.
@@ -978,6 +1033,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 +1208,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 +1490,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 +1503,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 +1535,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,18 +1547,12 @@ navigate.
   template), keep these in mind - they're the difference between a
   deck that lands and one that doesn't.
 
-  Templates for scratch, custom layout for anything seen. The
-  built-in templates are the fast path: legible, consistent, and
-  well suited to fast information transfer - an internal review, a
-  working draft, a deck you will talk over. They are not built for
-  an audience that cares about feel, so a deck made only from them
-  reads as functional rather than designed. For anything
-  external-facing - a client, a conference, a launch, anything with
-  your name on it that you will not be in the room to narrate -
-  compose the deck from raw shapes instead. If you are not sure which
-  setting you are in, ask your user, explaining the trade-off:
-  templates are faster and uniform, raw shapes take longer but let
-  the deck carry a designed look. See \`sdoc slides custom-shapes\`
+  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
@@ -1360,9 +1585,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.
@@ -1380,17 +1609,19 @@ navigate.
   A bulleted paragraph is hiding the fact that you haven't decided
   what you're claiming.
 
-  When the deck is internal or you only need it to read clearly,
-  \`@extends\` a built-in template instead of composing from raw
-  shapes - run \`sdoc slides list\` to see the registry. Reach for
-  raw shapes when the deck will be seen by an audience and the
-  default beat is not enough; the guidelines above are what keep
-  that hand-built deck on the professional side of the line. 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.
+  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
@@ -1645,7 +1876,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
@@ -1668,17 +1900,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
@@ -1955,7 +2190,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
@@ -1969,10 +2205,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
@@ -2286,7 +2522,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),
@@ -2465,6 +2702,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
@@ -2715,14 +2954,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
@@ -2755,9 +2988,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, ...)
@@ -2931,8 +3162,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.
 
@@ -3035,4 +3266,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 };