sdocs-dev 1.15.0 → 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
+
+  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 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.
+  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,18 +1518,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 +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.
@@ -1380,17 +1580,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 +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
@@ -1668,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
@@ -1955,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
@@ -1969,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
@@ -2286,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),
@@ -2465,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
@@ -2715,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
@@ -2755,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, ...)
@@ -2931,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.
 
@@ -3035,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 };

package/lib/io.js

@@ -9,11 +9,12 @@ const codeLangs = require('./code-langs');
 
 const SUBCOMMANDS = new Set([
   'new', 'share', 'schema', 'defaults', 'help', 'version',
-  'charts', 'diagrams', 'videos', 'video', 'cells', 'code', 'comments',
+  'charts', 'diagrams', 'videos', 'video', 'apps', 'app', 'cells', 'code', 'comments',
   'setup', 'safe', 'auto-update', 'refresh', 'upgrade',
   'bridge', 'feedback',
   'slides', 'present',
   'library',
+  'cloud',
   'color-analysis',
 ]);
 
@@ -55,6 +56,23 @@ function parseArgs(argv) {
   let yesFlag = false;
   let dryRunFlag = false;
   let sheetName = null;
+  let projectFlag = null;
+  let accountFlag = null;
+  let outputPath = null;
+  let revisionFlag = null;
+  let documentFlag = null;
+  let baseRevisionFlag = null;
+  let limitFlag = null;
+  let noOpenFlag = false;
+  let noBindFlag = false;
+  let forceFlag = false;
+  let everyoneFlag = false;
+  let onlyYouFlag = false;
+  let sharedWithMeFlag = false;
+  let noteText = null;
+  const memberFlags = [];
+  const documentFlags = [];
+  const tagFilters = [];
   const addTags = [];
   const annotations = [];
   // Multi-file code walkthrough: every source-code positional is collected
@@ -115,6 +133,26 @@ function parseArgs(argv) {
     if (arg === '--yes' || arg === '-y')             { yesFlag          = true; continue; }
     if (arg === '--dry-run')                         { dryRunFlag       = true; continue; }
     if (arg === '--sheet')                           { sheetName        = args[++i]; continue; }
+    if (arg === '--project')                         { projectFlag      = args[++i]; continue; }
+    if (arg === '--account')                         { accountFlag      = args[++i]; continue; }
+    if (arg === '--member')                          { memberFlags.push(args[++i]); continue; }
+    if (arg === '--everyone')                        { everyoneFlag     = true; continue; }
+    if (arg === '--only-you')                        { onlyYouFlag      = true; continue; }
+    if (arg === '--shared-with-me')                  { sharedWithMeFlag = true; continue; }
+    if (arg === '--note')                            { noteText = args[++i]; continue; }
+    if (arg === '--output' || arg === '-o')          { outputPath       = args[++i]; continue; }
+    if (arg === '--revision')                        { revisionFlag     = args[++i]; continue; }
+    if (arg === '--document') {
+      documentFlag = args[++i];
+      documentFlags.push(documentFlag);
+      continue;
+    }
+    if (arg === '--base-revision')                   { baseRevisionFlag = args[++i]; continue; }
+    if (arg === '--limit')                           { limitFlag        = Number(args[++i]); continue; }
+    if (arg === '--tag')                             { tagFilters.push(args[++i]); continue; }
+    if (arg === '--no-open')                         { noOpenFlag       = true; continue; }
+    if (arg === '--no-bind')                         { noBindFlag       = true; continue; }
+    if (arg === '--force')                           { forceFlag        = true; continue; }
 
     if (!subcommand && SUBCOMMANDS.has(arg)) {
       subcommand = arg;
@@ -165,6 +203,9 @@ function parseArgs(argv) {
     messageText, connectTimeoutS, idleTimeoutS, reconnectGraceMs,
     keepOpenFlag, logFile,
     tagsFlag, helpFlag, yesFlag, dryRunFlag, sheetName,
+    projectFlag, accountFlag, outputPath, revisionFlag, documentFlag, baseRevisionFlag,
+    limitFlag, noOpenFlag, noBindFlag, forceFlag, tagFilters,
+    everyoneFlag, onlyYouFlag, sharedWithMeFlag, noteText, memberFlags, documentFlags,
     addTags, annotations, files,
   };
 }
@@ -236,13 +277,13 @@ function readCodewalkContent(files) {
   return { body: parts.join('\n'), files: tabs };
 }
 
-function openBrowser(url) {
+function openBrowser(url, fallback) {
   try {
     if (process.platform === 'darwin')      execFileSync('open', [url]);
     else if (process.platform === 'win32')  execFileSync('cmd', ['/c', 'start', '', url]);
     else                                    execFileSync('xdg-open', [url]);
   } catch {
-    console.log(`Open in browser: ${url}`);
+    (fallback || console.log)(`Open in browser: ${url}`);
   }
 }