sdocs-dev 1.13.0 → 1.14.0

package/bin/sdocs-bridge.js

@@ -26,7 +26,7 @@ const fs     = require('fs');
 const path   = require('path');
 const crypto = require('crypto');
 const FormBlock = require('../shared/sdocs-form-block.js');
-const { isWrappedFile, wrapForDisplay } = require('../lib/cells-transclude');
+const { isWrappedFile, wrapForDisplay } = require('../lib/file-wrap');
 
 // ── Constants ─────────────────────────────────────────────
 

package/bin/sdocs-dev.js

@@ -54,6 +54,7 @@ function buildRouter() {
     if ((opts.file || '').toLowerCase() === 'verify') return cellsVerify.cellsVerifyCommand(opts);
     console.log(helpText.CELLS_HELP); process.exit(0);
   } });
+  r.register('code',     { handler: () => { console.log(helpText.CODE_HELP);     process.exit(0); } });
   r.register('comments', { handler: () => { console.log(helpText.COMMENTS_HELP); process.exit(0); } });
 
   // Setup / refresh / auto-update.

package/lib/agent-block.js

@@ -18,8 +18,8 @@ const fs   = require('fs');
 const path = require('path');
 const { SETUP_CACHE } = require('./constants');
 
-const AGENT_BLOCK_VERSION = 10;
-const AGENT_BLOCK_REASON  = 'Documents `sdoc bridge file.md`: a live editing session for iterating on a file with the user (browser edits autosave to disk, file edits push to the page). Notes that it parks the terminal so it should run in the background, and that the browser asks for local-process / "Apps on device" permission the user must accept. Reframes plain `sdoc file.md` as the default way to open a file for comfortable reading or quick sharing. Renames the block heading from SDocs to SmallDocs, the project\'s new name and home, and spells out that "sdoc it" / "sdoc me the plan" / "make me a smalldoc" all mean: write the .md and open it with sdoc.';
+const AGENT_BLOCK_VERSION = 12;
+const AGENT_BLOCK_REASON  = 'Adds `sdoc code`: opening a source file (sdoc app.rb) or a ```lang fenced block as a syntax-highlighted listing - a light code viewer for reading code with the user away from the IDE - with source comments given a prominent lane, a fullscreen view that folds by method/class, a comment mode for the user to annotate a line or method, and agent annotations (sdoc app.py 22:"...") that pin markdown callouts to lines so an agent can walk the user through code without editing it. One bullet added after the cells line; the rest of the block is unchanged from v11.';
 
 const AGENT_BLOCK_BODY = `## SmallDocs
 
@@ -48,7 +48,8 @@ Each command below prints its reference when run with no arguments - run it befo
 - \`sdoc charts\` - rendering inline charts (\`\`\`chart blocks)
 - \`sdoc diagrams\` - rendering inline Mermaid diagrams (\`\`\`mermaid blocks; has full-screen mode for zoom). Reach for this when drawing system or architectural diagrams (sequence, flow, component layout) - a diagram often communicates the shape of something faster than the equivalent prose.
 - \`sdoc slides\` - inline slide decks (\`\`\`slide / ~~~slide blocks; has full-screen presentation mode). Slides can be standalone exported as \`.pdf\` or \`.pptx\`. \`sdoc present file.md\` - open file directly in fullscreen presentation mode.
-- \`sdoc cells\` - rendering spreadsheets (\`\`\`cells blocks): CSV rows where plain values and =formulas (SUM, AVERAGE, IF, ROUND...) sit in the same grid and compute live. The reader can sort, select ranges for quick stats, edit a scratch copy fullscreen, and download the sheet as Excel (.xlsx) with the formulas still working. Reach for this when handing the user numbers they will want to check or play with - totals, budgets, projections. \`sdoc report.csv\` opens a CSV file directly as a sheet.
+- \`sdoc cells\` - rendering spreadsheets (\`\`\`cells blocks): CSV rows where plain values and =formulas (SUM, AVERAGE, IF, ROUND...) sit in the same grid and compute live. The reader can sort, select ranges for quick stats, edit a scratch copy fullscreen, and download the sheet as Excel (.xlsx) with the formulas still working. Name a block (\`\`\`cells Expenses) to build a workbook of several tabs whose formulas reference each other across sheets (\`=Expenses!B4\`); run \`sdoc cells verify file.md\` to compute the whole workbook headlessly and read the values back. Reach for this when handing the user numbers they will want to check or play with - totals, budgets, projections. \`sdoc report.csv\` opens a CSV file directly as a sheet.
+- \`sdoc code\` - opening a source file or a fenced code block as a syntax-highlighted listing: a light code viewer for reading code with the user away from the IDE. \`sdoc app.rb\` (or \`.js\`, \`.py\`, \`.go\`, \`.rs\`, \`.ts\`...) opens a file as a highlighted listing; a \`\`\`lang fenced block is highlighted inline. Comments in the source get a prominent lane so the code reads clearly top to bottom. The fullscreen view adds a line-number gutter and language-aware folding (collapse a whole method or class); a comment mode lets the user annotate a line or method with review notes, kept in the browser rather than the file. You can also pin your own explanations to lines as you open a file - \`sdoc app.py 22:"this method has the bug" 25-28:"wrong comparison here"\` - and they render as markdown callouts below those lines, a way to walk the user through code without editing the source. The file rides in the URL like any document; nothing is uploaded. Reach for it when reading or reviewing code with the user, not for prose.
 - \`sdoc schema\` - styling Markdown (fonts, colors, spacing). The default styles are already comfortable to read; reach for this only when they aren't enough - client-facing polish or a bit of fun.
 - \`sdoc feedback\` - rendering interactive elements (\`\`\`form blocks) to receive structured input from the user. Run \`sdoc feedback file.md\` and the user's submission lands as a JSON line on stdout. Good for eliciting complex/subtle feedback. All standard interactive HTML elements with prefilled (but editable) content of your choosing.
 `;

package/lib/bridge-commands.js

@@ -22,6 +22,8 @@ const { startBridge } = require('../bin/sdocs-bridge');
 const { DEFAULT_URL } = require('./constants');
 const { openBrowser } = require('./io');
 const { stripAndCompress } = require('./url');
+const { wrapForDisplay } = require('./file-wrap');
+const { isCodeFile } = require('./code-langs');
 
 function baseUrlFor(opts) {
   return opts.url || process.env.SDOCS_URL || DEFAULT_URL;
@@ -41,7 +43,20 @@ function bridgeSnapshot(file) {
   if (!file) return null;
   if (WRAPPED_EXT.has(path.extname(file).toLowerCase())) return null;
   try {
-    return stripAndCompress(fs.readFileSync(file, 'utf-8'));
+    const raw = fs.readFileSync(file, 'utf-8');
+    // A code file's renderable document is the file wrapped in a fence (the same
+    // transform the live bridge applies). The snapshot must embed THAT, not the
+    // raw source: otherwise the read-only fallback - which is what every page
+    // refresh renders until the socket reconnects - shows the file as markdown
+    // (docstrings as prose, indented bodies as stray code blocks) instead of the
+    // fullscreen code view with its folding and comments. Carry the filename in
+    // front matter so the snapshot is self-contained: the code view names it and
+    // auto-expands without depending on the bridge's `file=` param surviving.
+    if (isCodeFile(file)) {
+      const doc = '---\nfile: ' + path.basename(file) + '\n---\n' + wrapForDisplay(raw, file);
+      return stripAndCompress(doc);
+    }
+    return stripAndCompress(raw);
   } catch (_) {
     return null;
   }
@@ -166,6 +181,7 @@ function feedbackCommand(opts)  { return runBridge(opts, 'feedback', 'Feedback o
 module.exports = {
   runBridgedOpen,
   feedbackCommand,
-  buildBridgeUrl, // for tests
-  timeoutOpts,    // for tests
+  buildBridgeUrl,  // for tests
+  bridgeSnapshot,  // for tests
+  timeoutOpts,     // for tests
 };

package/lib/cells-transclude.js

@@ -86,29 +86,7 @@ function wrapCsvFile(csv, filename) {
     String(csv).replace(/\s+$/, '') + '\n```\n';
 }
 
-// A "wrapped" file is one whose renderable document is DERIVED from the file
-// (its contents inside a fenced block) rather than the file itself. The two
-// open paths (URL snapshot via readContent, live sync via the bridge) both
-// wrap these for display, and the bridge refuses to save the derived view
-// back - that would overwrite the .csv / .mmd with fence markup.
-function isWrappedFile(filePath) {
-  return /\.(csv|mmd|mermaid)$/i.test(String(filePath || ''));
-}
-
-// File contents -> renderable document. Wrapped types get their fence;
-// everything else (markdown) passes through untouched.
-function wrapForDisplay(raw, filePath) {
-  var name = String(filePath || '');
-  if (/\.(mmd|mermaid)$/i.test(name)) {
-    return '```mermaid\n' + String(raw).replace(/\s+$/, '') + '\n```\n';
-  }
-  if (/\.csv$/i.test(name)) return wrapCsvFile(raw, name);
-  return String(raw);
-}
-
 module.exports = {
   transcludeCells: transcludeCells,
   wrapCsvFile: wrapCsvFile,
-  isWrappedFile: isWrappedFile,
-  wrapForDisplay: wrapForDisplay,
 };

package/lib/cells-verify.js

@@ -31,30 +31,44 @@ function scanCellsBlocks(md) {
   var blocks = [];
   var m;
   while ((m = re.exec(md))) {
-    blocks.push({ name: (m[2] || '').trim().replace(/"/g, ''), body: m[3] });
+    blocks.push({ info: (m[2] || '').replace(/"/g, ''), body: m[3] });
   }
   return blocks;
 }
 
-// Parse + name every block into a workbook, mirroring the renderer: a fence
-// name wins, then an explicit `name=` directive, then auto Sheet1/Sheet2... by
-// order among the blocks that became real grids. Non-grid blocks (empty /
-// unresolved) are skipped; a parse error is recorded so the exit code reflects it.
+// Parse + name + group every block into workbooks, mirroring the renderer.
+// Each block's fence info is split into a workbook id and a sheet name (the
+// first "/" separates them); a baked `workbook=` / `name=` directive is the
+// fallback. Blocks bucket by workbook id in first-seen order; within each
+// workbook a fence/directive name wins, else auto Sheet1/Sheet2..., and both
+// the auto counter and duplicate detection reset per workbook. recalcWorkbook
+// later resolves references only within one workbook, so a Sheet!A1 into
+// another workbook reads #REF! - the same isolation the browser enforces.
 function buildWorkbook(md) {
   var blocks = scanCellsBlocks(md);
-  var sheets = [];   // { name, model }
+  var order = [];     // workbook ids, first-seen order
+  var byWb = {};      // id -> [{ name, model }]
   var parseErrors = [];
-  var autoIdx = 0;
   for (var i = 0; i < blocks.length; i++) {
     var model;
     try { model = CELLS.parseCells(blocks[i].body); }
     catch (e) { parseErrors.push((e && e.message) || 'parse error'); continue; }
     if (model.error) { parseErrors.push(model.error); continue; }
     if (model.unresolved || model.empty) continue;
-    var name = blocks[i].name || (model.name && String(model.name).trim()) || ('Sheet' + (++autoIdx));
-    sheets.push({ name: name, model: model });
+    var fence = CELLS.parseFenceInfo(blocks[i].info || '');
+    var wbId = fence.workbook || (model.workbook != null ? String(model.workbook) : '');
+    var explicitName = fence.name || (model.name && String(model.name).trim()) || '';
+    if (!byWb[wbId]) { byWb[wbId] = []; order.push(wbId); }
+    byWb[wbId].push({ name: explicitName, model: model });
   }
-  return { sheets: sheets, parseErrors: parseErrors };
+  var workbooks = order.map(function (id) {
+    var autoIdx = 0;
+    var sheets = byWb[id].map(function (s) {
+      return { name: s.name || ('Sheet' + (++autoIdx)), model: s.model };
+    });
+    return { id: id, sheets: sheets };
+  });
+  return { workbooks: workbooks, parseErrors: parseErrors };
 }
 
 // Render one sheet's computed grid to a 2D array of display strings: a formula
@@ -111,17 +125,24 @@ async function cellsVerifyCommand(opts) {
   }
 
   var wb = buildWorkbook(content);
-  var fxGrids = FX.recalcWorkbook(wb.sheets.map(function (s) {
-    return { name: s.name, model: s.model };
-  }));
 
-  // Build the per-sheet view once; --sheet filters it afterwards.
-  var rendered = wb.sheets.map(function (s, i) {
-    return {
-      name: s.name,
-      values: valuesFor(s.model, fxGrids[i] || []),
-      errors: errorsFor(s.name, s.model, fxGrids[i] || []),
-    };
+  // Recalc each workbook in isolation, then flatten to a per-sheet view that
+  // remembers which workbook each sheet came from. --sheet filters it after.
+  var rendered = [];
+  wb.workbooks.forEach(function (book) {
+    var fxGrids = FX.recalcWorkbook(book.sheets.map(function (s) {
+      return { name: s.name, model: s.model };
+    }));
+    book.sheets.forEach(function (s, i) {
+      var errs = errorsFor(s.name, s.model, fxGrids[i] || []);
+      if (book.id) errs.forEach(function (e) { e.workbook = book.id; });
+      rendered.push({
+        workbook: book.id,
+        name: s.name,
+        values: valuesFor(s.model, fxGrids[i] || []),
+        errors: errs,
+      });
+    });
   });
 
   if (opts.sheetName) {
@@ -141,14 +162,19 @@ async function cellsVerifyCommand(opts) {
   if (opts.jsonFlag) {
     process.stdout.write(JSON.stringify({
       ok: ok,
-      sheets: rendered.map(function (r) { return { name: r.name, values: r.values }; }),
+      sheets: rendered.map(function (r) {
+        var o = { name: r.name, values: r.values };
+        if (r.workbook) o.workbook = r.workbook;
+        return o;
+      }),
       errors: allErrors,
       parseErrors: wb.parseErrors,
     }, null, 2) + '\n');
   } else {
     if (!rendered.length) console.error('sdoc: no cells tabs found in ' + file);
     var chunks = rendered.map(function (r) {
-      return '# sheet: ' + r.name + '\n' + CELLS.serializeCsv(r.values);
+      var banner = r.workbook ? ('# workbook: ' + r.workbook + ' / sheet: ' + r.name) : ('# sheet: ' + r.name);
+      return banner + '\n' + CELLS.serializeCsv(r.values);
     });
     if (chunks.length) process.stdout.write(chunks.join('\n') + '\n');
     wb.parseErrors.forEach(function (e) { console.error('sdoc: cells parse error - ' + e); });

package/lib/code-langs.js

@@ -0,0 +1,85 @@
+// code-langs.js - map a source file's extension to a fenced code block.
+//
+// `sdoc app.rb` should open as a syntax-highlighted Ruby document, the same way
+// `sdoc chart.mmd` opens as a diagram. The CLI can't highlight anything itself;
+// it just wraps the file in a ```<lang> fence and the browser's highlight.js
+// does the colouring. So all this module decides is: which fence label?
+//
+// The label is the highlight.js language name (or one of its aliases), so the
+// fence the CLI writes is the same one a user would type by hand.
+
+var path = require('path');
+
+// Extension (no dot, lowercase) -> fence label. Markdown and plain text are
+// intentionally absent: those open as documents, not as code listings.
+var LANG_BY_EXT = {
+  js: 'javascript', mjs: 'javascript', cjs: 'javascript', jsx: 'javascript',
+  ts: 'typescript', tsx: 'typescript',
+  py: 'python', pyw: 'python',
+  rb: 'ruby', rake: 'ruby',
+  go: 'go',
+  rs: 'rust',
+  java: 'java',
+  kt: 'kotlin', kts: 'kotlin',
+  swift: 'swift',
+  c: 'c', h: 'c',
+  cpp: 'cpp', cc: 'cpp', cxx: 'cpp', hpp: 'cpp', hh: 'cpp',
+  cs: 'csharp',
+  php: 'php',
+  scala: 'scala',
+  ex: 'elixir', exs: 'elixir',
+  erl: 'erlang',
+  clj: 'clojure', cljs: 'clojure',
+  hs: 'haskell',
+  lua: 'lua',
+  pl: 'perl', pm: 'perl',
+  r: 'r',
+  dart: 'dart',
+  sh: 'bash', bash: 'bash', zsh: 'bash',
+  ps1: 'powershell',
+  sql: 'sql',
+  yml: 'yaml', yaml: 'yaml',
+  toml: 'toml',
+  ini: 'ini', cfg: 'ini', conf: 'ini',
+  json: 'json',
+  xml: 'xml', svg: 'xml',
+  html: 'xml', htm: 'xml',
+  css: 'css',
+  scss: 'scss', sass: 'scss',
+  less: 'less',
+  dockerfile: 'dockerfile',
+  diff: 'diff', patch: 'diff',
+  graphql: 'graphql', gql: 'graphql',
+  proto: 'protobuf'
+};
+
+function extOf(filePath) {
+  var name = path.basename(String(filePath || '')).toLowerCase();
+  // Dotfiles named exactly like a known type, e.g. "Dockerfile".
+  if (name === 'dockerfile') return 'dockerfile';
+  var ext = path.extname(name);
+  return ext ? ext.slice(1) : '';
+}
+
+// The highlight.js language for a path, or '' if we don't wrap it as code.
+function langForFile(filePath) {
+  return LANG_BY_EXT[extOf(filePath)] || '';
+}
+
+function isCodeFile(filePath) {
+  return !!langForFile(filePath);
+}
+
+// File contents -> a fenced code document. Trailing whitespace is trimmed so a
+// file's final newline doesn't render as an empty last line in the block.
+function wrapCodeFile(raw, filePath) {
+  var lang = langForFile(filePath);
+  return '```' + lang + '\n' + String(raw).replace(/\s+$/, '') + '\n```\n';
+}
+
+module.exports = {
+  LANG_BY_EXT: LANG_BY_EXT,
+  langForFile: langForFile,
+  isCodeFile: isCodeFile,
+  wrapCodeFile: wrapCodeFile
+};

package/lib/commands.js

@@ -36,11 +36,19 @@ async function prepareUrl(opts) {
   }
 
   // Inject `file:` into front matter (basename only — safe to share).
-  // Respects user-set file: if already present.
+  // Respects user-set file: if already present. Agent annotations
+  // (`sdoc app.py 22:"..."`) ride here too, in `annotations:`, so they travel
+  // with the link and through `sdoc share` (front matter rides in the body,
+  // unlike `local` which share strips).
   if (content && opts.file) {
     const parsed = SDocYaml.parseFrontMatter(content);
-    if (!parsed.meta.file) {
-      parsed.meta.file = path.basename(opts.file);
+    let changed = false;
+    if (!parsed.meta.file) { parsed.meta.file = path.basename(opts.file); changed = true; }
+    if (opts.annotations && opts.annotations.length) {
+      parsed.meta.annotations = opts.annotations;
+      changed = true;
+    }
+    if (changed) {
       content = SDocYaml.serializeFrontMatter(parsed.meta) + '\n' + parsed.body;
     }
   }

package/lib/file-wrap.js

@@ -0,0 +1,39 @@
+// file-wrap.js - turn a file's contents into a renderable document.
+//
+// Some file types don't open as themselves: a .csv opens as a sheet, a .mmd as
+// a diagram, a .rb as a highlighted listing. For those, the document SDocs
+// renders is DERIVED from the file (its contents inside a fenced block) rather
+// than the file itself. This module is the one dispatcher that decides which
+// wrapping applies. Markdown and plain text are not wrapped - they open as-is.
+//
+// Both open paths go through here: readContent (the URL-snapshot path, in
+// io.js) and the bridge (the live-sync path). The bridge also reads
+// isWrappedFile to refuse saving a derived view back over the source file -
+// that would overwrite the .csv / .mmd / .rb with fence markup.
+
+const { wrapCsvFile } = require('./cells-transclude');
+const codeLangs = require('./code-langs');
+
+// A "wrapped" file is one whose renderable document is derived from a fence
+// around its contents, not the raw file.
+function isWrappedFile(filePath) {
+  var name = String(filePath || '');
+  return /\.(csv|mmd|mermaid)$/i.test(name) || codeLangs.isCodeFile(name);
+}
+
+// File contents -> renderable document. Wrapped types get their fence;
+// everything else (markdown) passes through untouched.
+function wrapForDisplay(raw, filePath) {
+  var name = String(filePath || '');
+  if (/\.(mmd|mermaid)$/i.test(name)) {
+    return '```mermaid\n' + String(raw).replace(/\s+$/, '') + '\n```\n';
+  }
+  if (/\.csv$/i.test(name)) return wrapCsvFile(raw, name);
+  if (codeLangs.isCodeFile(name)) return codeLangs.wrapCodeFile(raw, name);
+  return String(raw);
+}
+
+module.exports = {
+  isWrappedFile: isWrappedFile,
+  wrapForDisplay: wrapForDisplay,
+};

package/lib/help-text.js

@@ -1,5 +1,5 @@
 // Long help strings printed by `sdoc help`, `sdoc schema`, `sdoc charts`,
-// `sdoc diagrams`, `sdoc comments`. Kept as plain data with no logic.
+// `sdoc diagrams`, `sdoc code`, `sdoc comments`. Kept as plain data with no logic.
 
 const HELP = `
 SmallDocs CLI
@@ -22,6 +22,8 @@ USAGE
   sdoc charts                      Chart types, options, and styling guide
   sdoc diagrams                    Mermaid diagrams reference (\`\`\`mermaid 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
   sdoc color-analysis <file>       Check custom colours for readable contrast
                                    (both themes). Run after styling a doc.
   sdoc comments                    Comment-format reference (for agents)
@@ -1047,6 +1049,32 @@ MULTIPLE TABS (SHEETS)
       tabs collapse into a single widget (a tab strip + one grid at a time),
       placed where the first tab sat.
 
+WORKBOOK GROUPS (independent tab sets in one document)
+  Name a workbook before the sheet to split a document into separate,
+  independent workbooks. The part before the first "/" is the workbook, the
+  part after is the sheet name:
+
+  \`\`\`cells financials/Model
+  Line,2025,2026
+  Revenue,=Drivers!B2,=Drivers!C2
+  \`\`\`
+
+  \`\`\`cells financials/Drivers
+  Driver,2025,2026
+  Seats,800,2500
+  \`\`\`
+
+  Blocks that share a workbook id form one workbook: their own tab strip (under
+  cells-tabs: tabbed), their own sheet-name namespace, and their own formula
+  scope. Two workbooks on a page render as two separate tab strips. A Sheet!A1
+  reference into another workbook reads #REF! - the isolation is total, so two
+  workbooks may reuse a sheet name without colliding. A block with no "/" stays
+  in the default workbook and behaves exactly as before.
+
+  In the fullscreen view a "Download workbook" button exports the whole
+  workbook as one .xlsx, every sheet and its cross-sheet formulas intact; the
+  per-sheet download on each grid still exports just that one sheet.
+
 VERIFYING (for agents)
   Check the computed values without a browser:
 
@@ -1060,9 +1088,11 @@ VERIFYING (for agents)
   every tab computes cleanly and 1 when any cell errors, so an agent can gate
   on it. Write formulas, run verify, read the values back, fix, repeat.
 
-  The default output banners each tab with "# sheet: <name>". A data row
-  could itself start with that text, so for machine parsing use --json (its
-  per-tab values array is unambiguous).
+  The default output banners each tab with "# sheet: <name>", or "# workbook:
+  <id> / sheet: <name>" when the sheet sits in a named workbook (each workbook
+  is verified in isolation). A data row could itself start with that text, so
+  for machine parsing use --json (its per-tab values array, and each tab's
+  optional workbook field, are unambiguous).
 
 SORTING
   Hover a column letter: an arrow appears on its right showing what a click
@@ -2756,4 +2786,65 @@ COMMON QUESTIONS
      drop a \`.sdocsignore\` into the directory with the pattern.
 `;
 
-module.exports = { HELP, COMMENTS_HELP, SCHEMA, CHARTS_HELP, DIAGRAMS_HELP, CELLS_HELP, SLIDES_HELP, SLIDES_CUSTOM_SHAPES_HELP, LIBRARY_HELP };
+const CODE_HELP = `
+SDocs - Code (syntax highlighting)
+==================================
+Fenced code blocks are syntax-highlighted by language. Tag the fence with a
+language and the block is coloured in the browser; highlight.js is loaded from
+a CDN on first use, so a document with no code blocks pays nothing.
+
+BASIC SYNTAX
+  Tag the opening fence with a language name:
+
+  \`\`\`ruby
+  def greet(name)
+    # comments are styled to stand out, not fade away
+    puts "hello, #{name}"
+  end
+  \`\`\`
+
+  An untagged fence stays plain (no guessing). Blocks claimed by other
+  features - chart, mermaid, cells, form, math, slide - are never treated
+  as code.
+
+OPENING A SOURCE FILE
+  Point sdoc at a source file and it opens as a highlighted listing:
+
+    sdoc app.rb
+    sdoc server.js
+    sdoc main.go
+
+  The file travels in the URL like any document; nothing is uploaded. The
+  fence label is chosen from the extension (.rb -> ruby, .py -> python,
+  .ts -> typescript, and so on). Markdown and plain text open as documents,
+  not as code.
+
+ANNOTATIONS (walk someone through the code)
+  Pin a markdown explanation to a line as you open the file:
+
+    sdoc app.py 22:"this method is where the bug is"
+    sdoc app.py 25-28:"the equality check compares the **wrong** value"
+
+  Each note renders as a callout below its line (a range stripes the lines it
+  covers), with markdown inside - bold, inline code, links. They ride in the
+  link and through \`sdoc share\`, and never touch the source file. This is for
+  an agent explaining code to the reader; the in-browser comment mode
+  (--comment) is the reverse - the reader's own review notes.
+
+COMMENTS
+  Comments are deliberately prominent - italic, full-contrast colour, a faint
+  tint - rather than the usual muted grey, so the human explanation in a
+  listing is the easiest part to read.
+
+STYLING
+  Token colours track the light/dark theme. The block background follows the
+  same control as other code blocks (Blocks / Code in the style panel).
+
+SUPPORTED LANGUAGES
+  The common set ships in the core bundle (javascript, typescript, python,
+  ruby, go, rust, java, c, cpp, csharp, php, bash, sql, yaml, json, xml,
+  css, and more). Less common languages are fetched on demand the first time
+  they appear. An unknown language label renders as plain text.
+`;
+
+module.exports = { HELP, COMMENTS_HELP, SCHEMA, CHARTS_HELP, DIAGRAMS_HELP, CELLS_HELP, CODE_HELP, SLIDES_HELP, SLIDES_CUSTOM_SHAPES_HELP, LIBRARY_HELP };

package/lib/io.js

@@ -3,11 +3,12 @@
 const fs   = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
-const { transcludeCells, isWrappedFile, wrapForDisplay } = require('./cells-transclude');
+const { transcludeCells } = require('./cells-transclude');
+const { isWrappedFile, wrapForDisplay } = require('./file-wrap');
 
 const SUBCOMMANDS = new Set([
   'new', 'share', 'schema', 'defaults', 'help', 'version',
-  'charts', 'diagrams', 'cells', 'comments',
+  'charts', 'diagrams', 'cells', 'code', 'comments',
   'setup', 'safe', 'auto-update', 'refresh', 'upgrade',
   'bridge', 'feedback',
   'slides', 'present',
@@ -20,6 +21,14 @@ const SUBCOMMANDS = new Set([
 // front matter is the only place SDocs stores tags.
 const TAG_ARG = /^\+[A-Za-z][\w-]{0,63}$/;
 
+// Agent annotation arguments: `N:"text"` or `N-M:"text"` (the shell removes the
+// quotes, so the token arrives as `22:this is the bug`). Line numbers are
+// 1-based, matching what the reader sees in the gutter. Collected into an
+// annotations list and written into the opened file's front matter so they
+// travel with the link. The part before the colon must be digits (an optional
+// range), so file paths like `app.py` never match.
+const ANNOTATION_ARG = /^(\d+)(?:-(\d+))?:([\s\S]+)$/;
+
 function parseArgs(argv) {
   const args = argv || process.argv.slice(2);
   let file = null;
@@ -46,6 +55,7 @@ function parseArgs(argv) {
   let dryRunFlag = false;
   let sheetName = null;
   const addTags = [];
+  const annotations = [];
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -108,6 +118,20 @@ function parseArgs(argv) {
     // front matter at open time.
     if (TAG_ARG.test(arg)) { addTags.push(arg.slice(1).toLowerCase()); continue; }
 
+    // Agent annotation: `N:"text"` / `N-M:"text"`. Captured before the file /
+    // extra slots so a `22:...` token is never mistaken for a path.
+    const ann = ANNOTATION_ARG.exec(arg);
+    if (ann) {
+      const start = parseInt(ann[1], 10);
+      const end = ann[2] ? parseInt(ann[2], 10) : start;
+      // Strip one layer of surrounding quotes if a shell preserved them.
+      const text = ann[3].replace(/^"([\s\S]*)"$/, '$1').replace(/^'([\s\S]*)'$/, '$1');
+      if (start >= 1 && end >= start && text.trim()) {
+        annotations.push({ line: start, endLine: end, text });
+      }
+      continue;
+    }
+
     if (!file) { file = arg; continue; }
     // Second positional is captured as `extra` so `sdoc slides icons heart`
     // gets {subcommand: 'slides', file: 'icons', extra: 'heart'}.
@@ -120,7 +144,7 @@ function parseArgs(argv) {
     messageText, connectTimeoutS, idleTimeoutS, reconnectGraceMs,
     keepOpenFlag, logFile,
     tagsFlag, helpFlag, yesFlag, dryRunFlag, sheetName,
-    addTags,
+    addTags, annotations,
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdocs-dev",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "Open, share, and style markdown files from the terminal",
   "main": "bin/sdocs-dev.js",
   "bin": {
@@ -26,7 +26,7 @@
     "agents"
   ],
   "author": "Josh Summers",
-  "license": "MIT",
+  "license": "Elastic-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/espressoplease/smalldocs.git"

package/shared/sdocs-cells.js

@@ -112,6 +112,20 @@
     return meta;
   }
 
+  // Split a fence info string (everything after "cells ") into a workbook id
+  // and a sheet name. The first "/" separates them: "financials/Model" ->
+  // workbook "financials", name "Model". No slash -> default workbook "" and
+  // the whole string is the name. Everything after the first "/" is the name
+  // verbatim, so a sheet name may contain slashes; a workbook id may not. This
+  // is the one place both the browser renderer and the CLI split the fence, so
+  // the two never drift.
+  function parseFenceInfo(rest) {
+    var s = String(rest == null ? '' : rest).trim();
+    var slash = s.indexOf('/');
+    if (slash < 0) return { workbook: '', name: s };
+    return { workbook: s.slice(0, slash).trim(), name: s.slice(slash + 1).trim() };
+  }
+
   // Build the grid model from a ```cells block body.
   // Returns { rows, cols, cells, empty } where cells is row-major, every row
   // padded to `cols` with empty cells so the grid is rectangular. May instead
@@ -130,7 +144,7 @@
     // `name` is the tab name. Authored as the fence info string (```cells
     // Sales); the renderer + CLI normalise that into this directive so the
     // name has one home in the model.
-    var source, range, formats, name;
+    var source, range, formats, name, workbook;
     var lines = trimmed.split('\n');
     var idx = 0;
     var FORMAT_RE = /^format:\s*(.*)$/i;
@@ -141,7 +155,8 @@
         var meta = parseDirectives(dm[1]);
         source = meta.source; range = meta.range;
         if (meta.name != null) name = meta.name;
-        if (meta.error) return { empty: false, error: meta.error, source: source, name: name };
+        if (meta.workbook != null) workbook = meta.workbook;
+        if (meta.error) return { empty: false, error: meta.error, source: source, name: name, workbook: workbook };
         idx++; continue;
       }
       if (fm) { formats = parseFormats(fm[1]); idx++; continue; }
@@ -151,8 +166,8 @@
 
     // Unresolved reference (after directives): the CLI never baked it.
     var ref = body.match(REFERENCE_RE);
-    if (ref) return { empty: false, unresolved: ref[1], formats: formats, name: name };
-    if (body === '') return { rows: 0, cols: 0, cells: [], empty: true, source: source, range: range, formats: formats, name: name };
+    if (ref) return { empty: false, unresolved: ref[1], formats: formats, name: name, workbook: workbook };
+    if (body === '') return { rows: 0, cols: 0, cells: [], empty: true, source: source, range: range, formats: formats, name: name, workbook: workbook };
 
     var raw = parseCsv(body);
     var cols = 0;
@@ -168,7 +183,7 @@
       }
       cells.push(out);
     }
-    return { rows: raw.length, cols: cols, cells: cells, empty: false, source: source, range: range, formats: formats, name: name };
+    return { rows: raw.length, cols: cols, cells: cells, empty: false, source: source, range: range, formats: formats, name: name, workbook: workbook };
   }
 
   // Serialize a 2D array of raw cell strings back to CSV (RFC 4180 quoting:
@@ -378,6 +393,7 @@
   exports.classify = classify;
   exports.parseCsv = parseCsv;
   exports.parseCells = parseCells;
+  exports.parseFenceInfo = parseFenceInfo;
   exports.serializeCsv = serializeCsv;
   exports.selectionStats = selectionStats;
   exports.formatNumber = formatNumber;