sdocs-dev 1.6.2 → 1.12.0

package/lib/cells-transclude.js

@@ -0,0 +1,111 @@
+// cells-transclude.js - bake {{path/to/file.csv}} references into ```cells
+// blocks at CLI time.
+//
+// The browser can never read a local file, so a CSV reference only means
+// something while the CLI is involved. On open (and on share), every
+// ```cells block whose body is a bare {{...}} reference is replaced with the
+// file's full contents plus a metadata line the renderer reads:
+//
+//   ```cells                          ```cells
+//   {{data/report.csv}}        ->     sdoc-cells: source=report.csv
+//   ```                               Region,Q1,Q2
+//                                     North,100,150
+//                                     ...
+//                                     ```
+//
+// The whole file is baked in (the user chose "whole CSV always travels"), so
+// the resulting doc is self-contained and a share link never errors. Only the
+// basename is recorded as `source=` - the full local path would leak the
+// author's directory structure into a shared link. A read failure bakes an
+// `error=` directive the renderer surfaces instead.
+
+const fs = require('fs');
+const path = require('path');
+
+// A ```cells fenced block (captures leading boundary + body). Tilde fences and
+// inline-data blocks are left untouched.
+const CELLS_BLOCK = /(^|\n)```cells[ \t]*\n([\s\S]*?)\n```/g;
+const REFERENCE = /^\{\{\s*([^}]+?)\s*\}\}$/;
+// A trailing :range suffix like :B5:J32 or :B5 (a view hint; data is baked in
+// whole regardless, so we just strip it off the path for now).
+const RANGE_SUFFIX = /:([A-Za-z]+\d+(?::[A-Za-z]+\d+)?)$/;
+
+function directiveValue(s) {
+  return /\s|"/.test(s) ? JSON.stringify(s) : s;
+}
+
+function bakeBlock(boundary, ref, baseDir, readFile, preLines) {
+  var range = '';
+  var filePath = ref;
+  var rm = ref.match(RANGE_SUFFIX);
+  if (rm) { range = rm[1]; filePath = ref.slice(0, ref.length - rm[0].length); }
+
+  var base = path.basename(filePath);
+  // Author format: lines (e.g. `format: B=$`) sit before the reference and are
+  // preserved verbatim above the baked data.
+  var head = (preLines && preLines.length ? preLines.join('\n') + '\n' : '');
+  var csv;
+  try {
+    csv = readFile(path.resolve(baseDir, filePath));
+  } catch (e) {
+    return boundary + '```cells\n' + head + 'sdoc-cells: error=' +
+      directiveValue('Could not read ' + base) + '\n```';
+  }
+  csv = String(csv).replace(/\s+$/, '');
+  var directive = 'sdoc-cells: source=' + directiveValue(base) +
+    (range ? ' range=' + range : '');
+  return boundary + '```cells\n' + head + directive + '\n' + csv + '\n```';
+}
+
+// Replace every {{file.csv}} cells block in `content` with the baked data.
+// `readFile` is injectable for tests; defaults to fs.readFileSync(utf-8).
+function transcludeCells(content, baseDir, readFile) {
+  if (typeof content !== 'string' || content.indexOf('```cells') === -1) return content;
+  var read = readFile || function (p) { return fs.readFileSync(p, 'utf-8'); };
+  return content.replace(CELLS_BLOCK, function (whole, boundary, body) {
+    // Peel any leading author `format:` lines, then require a sole {{ref}}.
+    var lines = body.split('\n');
+    var pre = [];
+    var i = 0;
+    while (i < lines.length && /^\s*format:\s*/i.test(lines[i])) { pre.push(lines[i].trim()); i++; }
+    var rest = lines.slice(i).join('\n').trim();
+    var m = rest.match(REFERENCE);
+    if (!m) return whole;                    // inline data - leave alone
+    return bakeBlock(boundary, m[1], baseDir, read, pre);
+  });
+}
+
+// Wrap a standalone .csv file's contents in a ```cells block (so `sdoc x.csv`
+// opens as a sheet, mirroring the .mmd -> mermaid wrapping).
+function wrapCsvFile(csv, filename) {
+  var base = path.basename(filename);
+  return '```cells\nsdoc-cells: source=' + directiveValue(base) + '\n' +
+    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/commands.js

@@ -0,0 +1,291 @@
+// Verb handlers wired into the router.
+//
+// Each handler takes parsed opts and returns a Promise (or void). They
+// share `prepareUrl` for the load-content / apply-defaults / build-URL
+// flow that `open` and `share` both need.
+
+const path = require('path');
+const { execSync } = require('child_process');
+
+const SDocYaml = require('../shared/sdocs-yaml.js');
+
+const { DEFAULT_URL } = require('./constants');
+const { readContent, openBrowser } = require('./io');
+const { loadDefaultStyles, applyDefaultStyles, showDefaults, resetDefaults } = require('./styles');
+const { buildUrl } = require('./url');
+const { buildShortUrl } = require('./short-link');
+const { refreshUpdateCache, maybeUpdateBinary } = require('./update-check');
+const { runSetup, maybeAutoRefresh } = require('./setup');
+
+// Shared "after the command ran" tail used by `open` and `share`.
+async function postCommandHooks() {
+  refreshUpdateCache();
+  await maybeUpdateBinary();
+  await runSetup();
+  await maybeAutoRefresh();
+}
+
+// Load content (file or stdin), apply ~/.sdocs/styles.yaml defaults, inject
+// `file:` into front matter, and build either a hash URL or a short URL.
+// Returns { url, contentPresent }.
+async function prepareUrl(opts) {
+  let content = await readContent(opts.file);
+  const defaults = loadDefaultStyles();
+  if (content && defaults) {
+    content = applyDefaultStyles(content);
+  }
+
+  // Inject `file:` into front matter (basename only — safe to share).
+  // Respects user-set file: if already present.
+  if (content && opts.file) {
+    const parsed = SDocYaml.parseFrontMatter(content);
+    if (!parsed.meta.file) {
+      parsed.meta.file = path.basename(opts.file);
+      content = SDocYaml.serializeFrontMatter(parsed.meta) + '\n' + parsed.body;
+    }
+  }
+
+  // Runtime-only local metadata for the opener's view.
+  // `share` omits it so shared URLs never carry paths.
+  let local = null;
+  if (opts.file && opts.subcommand !== 'share') {
+    const abs = path.resolve(opts.file);
+    const rel = path.relative(process.cwd(), abs);
+    local = { fullPath: abs };
+    if (!rel.startsWith('..') && !path.isAbsolute(rel)) {
+      local.path = './' + rel;
+    }
+  }
+
+  let url;
+  if (opts.shortFlag) {
+    if (opts.subcommand !== 'share') {
+      console.error('sdoc: --short is only valid with the `share` subcommand');
+      process.exit(1);
+    }
+    if (!content) {
+      console.error('sdoc: --short needs content (a file path or piped stdin)');
+      process.exit(1);
+    }
+    try {
+      url = await buildShortUrl(content, {
+        url: opts.url,
+        mode: opts.mode,
+        theme: opts.theme,
+        section: opts.section,
+      });
+    } catch (e) {
+      console.error('sdoc: could not create short link -', e.message);
+      process.exit(1);
+    }
+  } else {
+    url = buildUrl(content, {
+      url: opts.url,
+      mode: opts.mode,
+      theme: opts.theme,
+      defaultStyles: !content ? defaults : null,
+      section: opts.section,
+      local,
+      present: opts.present,
+    });
+  }
+
+  return { url, contentPresent: !!content };
+}
+
+// Default flow: `sdoc <file>` or `sdoc` (no args, or piped stdin).
+//
+// The document travels in the URL hash and renders read-only-by-default in the
+// browser; nothing connects back to disk. This is the everywhere-works path -
+// no local socket, no browser permission prompt. The live, autosaving session
+// (browser <-> file on disk) is opt-in via `sdoc bridge <file>`.
+//
+// The non-blocking, share-by-URL case is `sdoc share <file>`.
+async function openCommand(opts) {
+  const { url } = await prepareUrl(opts);
+  openBrowser(url);
+  console.log(`SDocs → ${url.length > 80 ? url.slice(0, 77) + '...' : url}`);
+  await postCommandHooks();
+}
+
+async function shareCommand(opts) {
+  const { url } = await prepareUrl(opts);
+  try {
+    const clip = process.platform === 'darwin' ? 'pbcopy'
+      : execSync('which xclip 2>/dev/null', { encoding: 'utf-8' }).trim() ? 'xclip -selection clipboard'
+      : 'xsel --clipboard --input';
+    execSync(clip, { input: url, stdio: ['pipe', 'ignore', 'ignore'] });
+    const name = opts.file ? path.basename(opts.file) : 'stdin';
+    const label = opts.shortFlag ? 'Short link' : 'Link';
+    console.log(`✓ ${label} for ${name} copied to clipboard`);
+    if (opts.shortFlag) console.log(`  ${url}`);
+  } catch (_) {
+    process.stdout.write(url + '\n');
+  }
+  await postCommandHooks();
+}
+
+function defaultsCommand(opts) {
+  if (opts.resetFlag) resetDefaults();
+  else showDefaults();
+}
+
+// `sdoc color-analysis <file>` — grade every text-on-background pair in the
+// document's custom palette against WCAG ratios, for both the light and dark
+// themes. Exits 1 if anything is unreadable so an agent (or CI) notices.
+async function colorAnalysisCommand(opts) {
+  const SDocContrast = require('../shared/sdocs-contrast.js');
+  const content = await readContent(opts.file);
+  if (!content) {
+    console.error('sdoc color-analysis: pass a markdown file (or pipe one in)');
+    console.error('  e.g. sdoc color-analysis report.md');
+    process.exit(1);
+  }
+  const meta = SDocYaml.parseFrontMatter(content).meta || {};
+  const styles = meta.styles || null;
+  const name = opts.file ? path.basename(opts.file) : 'stdin';
+
+  if (!styles || !SDocContrast.hasCustomColors(styles)) {
+    console.log(`sdoc color-analysis: ${name}`);
+    console.log('  No custom colours set - the built-in palette is contrast-safe in both themes.');
+    process.exit(0);
+  }
+
+  const a = SDocContrast.analyzeStyles(styles);
+  const pad = (s, n) => (s + ' '.repeat(n)).slice(0, n);
+  const minRatio = SDocContrast.MIN_CONTRAST;
+  function line(p) {
+    const tag = p.ok ? 'ok  ' : 'FAIL';
+    const ratio = p.ratio == null ? '   ?  ' : (p.ratio.toFixed(2) + ':1');
+    return `  ${tag}  ${pad(p.label, 16)} ${pad(p.fg + ' on ' + p.bg, 22)} ${pad(ratio, 9)} ${p.ok ? '' : '(needs ' + minRatio + ':1)'}`;
+  }
+
+  console.log(`sdoc color-analysis: ${name}\n`);
+  console.log('LIGHT THEME');
+  a.light.forEach(p => console.log(line(p)));
+  console.log('\nDARK THEME');
+  a.dark.forEach(p => console.log(line(p)));
+
+  console.log('');
+  if (a.fails.length === 0) {
+    console.log('All text/background pairs meet WCAG AA. ✓');
+    process.exit(0);
+  }
+  console.log(`${a.fails.length} unreadable pair${a.fails.length === 1 ? '' : 's'} (contrast below ${minRatio}:1).`);
+  console.log('Fix the flagged colours, or add a `dark:` override so the dark theme has its own readable values.');
+  console.log('Reminder: top-level colours are the LIGHT theme; dark mode is auto-derived unless you set `dark:`.');
+  process.exit(1);
+}
+
+function newCommand(opts) {
+  const baseUrl = opts.url || process.env.SDOCS_URL || DEFAULT_URL;
+  const url = baseUrl + '/new';
+  openBrowser(url);
+  console.log(`SDocs → ${url}`);
+}
+
+// `sdoc slides` family. Dispatches on the positional after `slides`:
+//   sdoc slides                     -> prints SLIDES_HELP
+//   sdoc slides list                -> built-in template registry
+//   sdoc slides custom-shapes       -> raw-shape reference
+//   sdoc slides icons [query]       -> Lucide icon name listing
+function slidesCommand(opts) {
+  const helpText = require('./help-text');
+  const sub = opts.file;
+  if (sub === 'list')          { printSlideStdlib();           return; }
+  if (sub === 'custom-shapes') { console.log(helpText.SLIDES_CUSTOM_SHAPES_HELP); return; }
+  if (sub === 'icons')         { printIconList(opts.extra);    return; }
+  console.log(helpText.SLIDES_HELP);
+}
+
+// `sdoc present <file>` opens the file straight into fullscreen slide
+// view. Delegates to openCommand with `present: true` set so the URL
+// gets `&present=0` and the browser auto-enters present mode on load.
+function presentCommand(opts) {
+  return openCommand(Object.assign({}, opts, { present: true }));
+}
+
+function printSlideStdlib() {
+  // Require lazily so the browser-side slide stdlib (which uses window
+  // globals) is only loaded when this command actually runs.
+  const SDocSlideStdlib = require('../../public/sdocs-slide-stdlib.js');
+  const names = SDocSlideStdlib.names || Object.keys(SDocSlideStdlib.templates || {});
+  const slots = SDocSlideStdlib.slots || {};
+  console.log('Built-in slide templates');
+  console.log('========================');
+  const pad = 22;
+  for (let i = 0; i < names.length; i++) {
+    const n = names[i];
+    let label = '@extends ' + n;
+    while (label.length < pad) label += ' ';
+    const slotList = (slots[n] || []).join(', ');
+    console.log(label + ' ' + slotList);
+  }
+  console.log('');
+  console.log('`!` marks a required slot (resolver errors when omitted).');
+  console.log('Use a built-in by adding `@extends <name>` to a slide block.');
+  console.log('Define a user @template with the same name to override (you\'ll get a warning).');
+}
+
+function printIconList(query) {
+  let names;
+  try {
+    // The manifest sits next to this file (via cli/bin/). Require by
+    // resolved path so it works whether we're invoked from a globally
+    // installed binary or from a checkout.
+    names = require('../bin/sdocs-icon-names.js');
+  } catch (e) {
+    console.error('sdoc: icon names manifest missing (cli/bin/sdocs-icon-names.js).');
+    console.error('Run `node scripts/build-icons.js` to generate it.');
+    process.exit(1);
+  }
+
+  const q = (query || '').toLowerCase().trim();
+  const matches = q ? names.filter(n => n.indexOf(q) !== -1) : names;
+
+  if (q && matches.length === 0) {
+    console.log('No Lucide icons match "' + query + '".');
+    console.log('Browse the full set at https://lucide.dev/icons/ or run `sdoc slides icons` to list everything.');
+    return;
+  }
+
+  if (q) {
+    console.log('Lucide icons matching "' + query + '" (' + matches.length + ' of ' + names.length + ')');
+  } else {
+    console.log('Lucide icons available to the `icon` shape kind (' + names.length + ' total)');
+  }
+  console.log('Source: https://lucide.dev/icons/  -  use `name=<icon>` in slides');
+  console.log('');
+
+  const longest = matches.reduce((m, n) => n.length > m ? n.length : m, 0);
+  const colWidth = longest + 2;
+  const cols = 4;
+  const rows = Math.ceil(matches.length / cols);
+  for (let r = 0; r < rows; r++) {
+    let line = '';
+    for (let c = 0; c < cols; c++) {
+      const idx = c * rows + r;
+      if (idx >= matches.length) break;
+      let name = matches[idx];
+      while (name.length < colWidth) name += ' ';
+      line += name;
+    }
+    console.log(line.replace(/\s+$/, ''));
+  }
+
+  if (!q) {
+    console.log('');
+    console.log('Tip: filter with `sdoc slides icons <substring>` (e.g. `sdoc slides icons cloud`).');
+  }
+}
+
+module.exports = {
+  prepareUrl,
+  openCommand,
+  shareCommand,
+  defaultsCommand,
+  colorAnalysisCommand,
+  newCommand,
+  slidesCommand,
+  presentCommand,
+};

package/lib/constants.js

@@ -0,0 +1,283 @@
+// Shared constants used across the CLI lib.
+//
+// VERSION resolves to the CLI's own package version (cli/package.json),
+// not the server's root package.json.
+
+const path = require('path');
+const os   = require('os');
+
+exports.DEFAULT_URL       = 'https://smalldocs.org';
+exports.VERSION           = require('../package.json').version;
+exports.UPDATE_CACHE      = path.join(os.homedir(), '.sdocs', 'update-check.json');
+exports.SETUP_CACHE       = path.join(os.homedir(), '.sdocs', 'setup.json');
+exports.ONE_DAY           = 86400000;
+exports.AGENT_CHANGES_URL = 'https://smalldocs.org/agent-changes';
+exports.INSTALL_SH_URL    = exports.DEFAULT_URL + '/install';
+exports.GITHUB_REPO_URL   = 'https://github.com/espressoplease/SDocs';
+
+// Printed by `sdoc feedback` with no args. Goal: an agent can read this
+// once and write valid form blocks afterwards. Short, dense, and every
+// supported field type appears in the example.
+exports.FORM_DSL_REFERENCE = `\
+sdoc feedback — interactive form DSL
+====================================
+
+Ask the user something structured. Write a fenced \`\`\`form block into a
+markdown file, then run:
+
+  sdoc feedback file.md                # opens the file, exits on first submit
+
+That is the simplest, recommended shape: ONE submit button, single
+process invocation. The user clicks, the file gets the answers, the
+process prints one JSON line on stdout, and exits. You just spawn the
+command, wait for it to finish, and read its stdout.
+
+You only need the other modes when you genuinely want multiple submits
+in one session:
+
+  sdoc feedback file.md --keep-open    # bridge stays alive across many
+                                       # submits; you tail stdout to
+                                       # react per click
+  sdoc feedback file.md --keep-open \\
+       --log-file /tmp/sdoc.jsonl      # also mirror events to a file
+                                       # (fallback for harnesses that
+                                       #  can't tail a background process)
+  sdoc feedback file.md --message "Q"  # show "Q" above the document
+
+Strong default: write forms with ONE button. Reach for --keep-open + a
+multi-button form only when "the user submits several things during one
+session" is the actual goal.
+
+A form block has four sections: id, fields, buttons, and (added by the
+bridge on submit) answers + submissions. You author id, fields, buttons.
+
+Full example
+------------
+
+\`\`\`form
+id: q3-review
+fields:
+  - name: ready
+    type: radio
+    label: "Are you ready to ship?"
+    options: [Yes, "Needs more time", Push out]
+    required: true
+    default: Yes
+    help: "All teams have signed off."
+
+  - name: notes
+    type: textarea
+    label: "Detailed thoughts"
+    rows: 5
+    placeholder: "Anything else?"
+    default: |
+      Pre-filled text the user can edit.
+      Spans multiple lines via the | scalar.
+
+  - name: name_field
+    type: text
+    label: "Your name"
+    default: "Jane"          # pre-fills the input; user can edit to "Jane!"
+
+  - name: tags
+    type: checkbox
+    label: "Which areas?"
+    options: [api, web, docs, infra]
+    default: [api, docs]
+
+  - name: tier
+    type: select
+    label: "Pricing tier"
+    options: [free, pro, team, enterprise]
+    default: pro
+
+  - name: head_count
+    type: number
+    label: "How many people?"
+    min: 1
+    max: 500
+    default: 5
+
+  - name: target_date
+    type: date
+    label: "Target ship date"
+    default: "2026-06-01"
+
+buttons:
+  - name: send_decision
+    label: "Send decision"
+    scope: [ready]            # this button only submits the 'ready' field
+    after: ready              # render this button inline, right under the
+                              # 'ready' field, instead of in the footer row
+
+  - name: send_all
+    label: "Submit everything"
+    final: true               # this button always ends the session
+\`\`\`
+
+Field types
+-----------
+
+  text       single-line input. default, placeholder, required, maxlength
+  textarea   multi-line. default (block-scalar OK), rows, placeholder, required, maxlength
+  radio      one of N choices. options[] required. default selects one.
+  checkbox   multi-select. options[] required. default is an array.
+  select     dropdown. options[] required. default selects one.
+  number     numeric input. min, max, step. default is a number.
+  date       date picker (YYYY-MM-DD). min, max. default is the ISO date string.
+
+Per-field keys
+--------------
+
+  name        required, [a-z0-9_-]{1,64}, unique per form
+  label       shown above the control
+  help        small grey description under the control
+  required    true/false
+  default     pre-fill value the user can edit (array for checkbox, number
+              for number, ISO date for date, string otherwise)
+  options     radio / checkbox / select; array of strings
+  placeholder text / textarea / number; greyed-out hint that vanishes on type
+  rows        textarea only
+  min/max     number, date
+  step        number only
+
+Buttons
+-------
+
+  name       required, unique per form
+  label      button text
+  scope      optional list of field names. Defaults to all fields.
+  final      optional bool. true means this submit ends the session even
+             when --keep-open was passed.
+  after      optional field name. Renders the button inline right under
+             that field instead of in the bottom row. Combine with scope
+             for a "submit just this section" pattern.
+  help       optional one-line override for the auto-generated hint
+             (see "Button hints" below). Only set this when your own
+             one-liner is clearly better than the default.
+
+Button hints (automatic, you do not author these)
+-------------------------------------------------
+
+Every button gets a small grey line under it explaining what happens
+when the user clicks. You do not write the hint; it is derived from the
+button's shape:
+
+  final: true            -> "Submitting hands off to the agent and ends
+                             this session."
+  scope: [a, b]          -> "Sends just these answers (a, b). You can
+                             keep editing."
+  no scope (non-final)   -> "Sends all answers. You can keep editing."
+
+After a successful submit, a green italic line also appears under that
+same button: "Saved to <filename> at HH:MM:SS". It updates in place on
+each subsequent click of that button. You do not author this either.
+
+Set the per-button \`help: "..."\` key only when your own copy is
+genuinely more useful than the default (e.g. when the field semantics
+are non-obvious and the auto hint would mislead).
+
+Multi-round flow (with --keep-open)
+-----------------------------------
+
+  1. Write a file with a form block, run \`sdoc feedback file.md --keep-open\`.
+  2. User edits, clicks a non-final submit. Bridge writes the file with
+     answers + a submission entry. The bridge stays alive.
+  3. Read the file. \`submissions[-1]\` has the user's latest answer.
+  4. Rewrite the file with the next question (keep the form id stable to
+     preserve answers + history; change fields or labels as needed).
+  5. The browser refreshes automatically. The user answers the new form.
+  6. Repeat until the user clicks a button with \`final: true\`, or closes
+     the tab.
+
+How to know a submit happened (events)
+--------------------------------------
+
+Every successful submit emits one JSON line to stdout, e.g.
+
+  {"event":"submit","form_id":"q1","by":"send_decision",
+   "at":"2026-05-24T10:01:32.123Z","scope":["ready"],
+   "values":{"ready":"Yes"},"final":false}
+
+Startup chatter is on stderr, so stdout is a clean event channel.
+
+DO NOT fire-and-forget
+----------------------
+
+The submit JSON arrives WHEN the user clicks - which could be seconds
+or minutes after you spawn the command. The whole protocol depends on
+you (or your harness) noticing when the process exits.
+
+Wrong:
+
+  bash -c 'sdoc feedback file.md > log.json 2>&1 &'
+        ^^                                      ^^
+        starts                          shell backgrounding;
+        immediately                     parent NEVER notices exit
+
+That looks like it worked. The user fills out the form, clicks submit,
+the JSON lands in log.json, the process exits 0... and your agent
+never knows. You just sit there.
+
+Right (depends on your harness):
+
+  Claude Code     Bash tool with run_in_background: true
+                  (you get a notification when the process exits)
+  Codex           Codex's background-task primitive, same shape
+  Plain shell     Foreground: sdoc feedback file.md, then wait.
+                  Or:         sdoc feedback file.md & wait \$!
+                              (the wait \$! is what was missing)
+  Make / script   Run it foreground and capture stdout - no '&'
+
+The CLI prints a stderr warning when stdout is not a TTY at startup,
+so you get a hint if you set it up wrong.
+
+Two reading patterns:
+
+  Single-shot   sdoc feedback file.md
+                User clicks once, bridge writes the file, prints one
+                JSON line to stdout, exits 0. Agent runs the command,
+                waits for it to finish, reads stdout. No tailing. Works
+                in every harness that can run a child process.
+
+  Multi-click   sdoc feedback file.md --keep-open
+                Bridge stays alive. Each click prints another JSON
+                line. Agent runs the command in the background and
+                reads new lines as they arrive (Claude Code, Codex,
+                opencode all support this).
+
+  Log fallback  --log-file PATH
+                The same JSON lines, also appended to a file. Use this
+                when your harness can run a backgrounded process but
+                can't stream its stdout (Aider, older Cursor modes).
+                Agent reads the file periodically.
+
+On submit, the form block grows two new sections:
+
+\`\`\`yaml
+answers:
+  ready: Yes
+  notes: |
+    Multi-line answer text the user kept or edited.
+  tags: [api, docs]
+  head_count: 5
+  target_date: "2026-06-01"
+submissions:
+  - by: send_decision
+    at: "2026-05-23T10:01:32Z"
+    scope: [ready]
+    values:
+      ready: Yes
+\`\`\`
+
+Constraints
+-----------
+
+  - 64KB max per form block source.
+  - Field and button names: [a-z0-9_-]{1,64}.
+  - Strings containing triple-backticks are rejected on submit.
+  - Markdown around the form block is preserved byte-for-byte.
+
+End.
+`;
+