@entropicwarrior/sdoc 0.2.11 → 0.2.13

package/docs/reference/sdoc-authoring.sdoc

@@ -275,6 +275,66 @@ Content of Section B.
             }
             ```
 
+            # Column Directives @column-directives
+            {
+                An optional directive row after the header controls per-column alignment and number formatting. It is consumed by the parser and not rendered as data.
+
+                # Column Alignment
+                {
+                    Use \`<\` (left), \`>\` (right), or \`=\` (center):
+
+                    ```
+                    {[table]
+                        Programme | Amount | Status
+                        < | > | =
+                        Alpha | $1,000,000 | Active
+                        Beta | $2,500,000 | Pending
+                    }
+                    ```
+
+                    If absent, all columns default to left. Empty cells in the directive row keep the default. Alignment applies to both header and data cells.
+
+                    For headerless tables, the directive row is the first row — it is consumed but no header is rendered:
+
+                    ```
+                    {[table headerless]
+                        < | >
+                        Alice | 100
+                        Bob | 200
+                    }
+                    ```
+                }
+
+                # Column Formatting
+                {
+                    A format token in the directive row formats numeric cells and formula results in that column. Text cells (like bold labels) pass through unchanged. The format is display-only — formulas always use raw numeric values.
+
+                    {[.]
+                        - \`$\` — currency, no decimals: \`$1,000,000\`
+                        - \`$.N\` — currency with N decimals: \`$.2\` → \`$1,234.50\`
+                        - \`,\` — thousands separator: \`1,000,000\`
+                        - \`,.N\` — thousands with N decimals: \`,.2\` → \`1,234,567.89\`
+                        - \`.N\` — fixed N decimals: \`.2\` → \`3.14\`
+                        - \`%\` — percentage (value × 100): \`0.452\` → \`45.2%\`
+                        - \`%.N\` — percentage with N decimals: \`%.1\` → \`45.7%\`
+                    }
+
+                    Alignment and format combine in a single directive cell:
+
+                    ```
+                    {[table]
+                        Item | Amount
+                        < | > $
+                        Widget | 1000000
+                        Gadget | 2500000
+                        **Total** | =SUM(B1:B2)
+                    }
+                    ```
+
+                    The \`Amount\` column is right-aligned and formatted as currency. The formula result and data cells all display as \`$1,000,000\` style. The \`**Total**\` label renders as bold text.
+                }
+            }
+
             # Table Formulas @table-formulas
             {
                 Cells starting with \`=\` are evaluated as formulas. Hover a computed cell in preview to see the original formula.
@@ -282,9 +342,10 @@ Content of Section B.
                 ```
                 {[table]
                     Investor | Shares | Ownership
-                    Seed Fund | 500,000 | 25%
-                    Founder A | 1,000,000 | 50%
-                    Founder B | 500,000 | 25%
+                    < | > , | > %
+                    Seed Fund | 500000 | 0.25
+                    Founder A | 1000000 | 0.50
+                    Founder B | 500000 | 0.25
                     **Total** | =SUM(B1:B3) | =SUM(C1:C3)
                 }
                 ```
@@ -301,6 +362,8 @@ Content of Section B.
                 }
 
                 Errors display in red italic: \`#DIV/0!\` (division by zero), \`#VALUE!\` (bad reference), \`#REF!\` (invalid syntax), \`#NAME!\` (unknown function), \`#CIRCULAR!\` (circular dependency).
+
+                **Tip:** Use numeric values with a column format directive (e.g. \`> $\`) instead of pre-formatted strings like \`$1,000,000\`. Formatted strings are text — formulas cannot reference them.
             }
         }
 
@@ -365,6 +428,39 @@ Content of Section B.
             Do not write \`@setup\` when the target scope is in a different file — it will be flagged as a broken reference.
         }
 
+        # Citations @citations
+        {
+            Use \`[@key]\` in text to cite a source. Define citations in a \`{[citations]\` block. The renderer assigns numbers by order of first appearance and links everything together.
+
+            ```
+            # Findings {
+                Edge AI is growing rapidly [@mm-edge-ai]. The chip market
+                is expected to double by 2031 [@mordor-chips].
+
+                {[citations]
+                    - @mm-edge-ai MarketsandMarkets, "Edge AI Hardware
+                      Market," Report SE 7017, June 2025.
+                    - @mordor-chips Mordor Intelligence, "Edge AI Chips
+                      Market Size & Share Analysis," 2026.
+                }
+            }
+            ```
+
+            {[.]
+                - \`[@key]\` renders as a clickable superscript number (e.g. \`[1]\`) linking to the citation entry
+                - \`[@key1, @key2]\` renders as \`[1, 3]\` with each number individually linked
+                - The same \`[@key]\` used multiple times always renders the same number
+                - Keys follow \`@slug\` conventions: lowercase kebab-case
+                - Citation text is free-form SDOC inline content — links, bold, italics all work
+                - Each citation entry includes a back-link (\`\u21A9\`) to the first place it was cited
+                - Numbering is by order of first \`[@key]\` appearance, not by definition order
+                - Multiple \`{[citations]\` blocks are allowed — numbering is unified across all blocks
+                - A \`[@key]\` with no matching definition is flagged as a broken citation
+                - A defined citation that is never referenced produces a warning
+                - Citation keys are document-local, like \`@slug\` references
+            }
+        }
+
         # Code Blocks @code-blocks
         {
             Fenced with triple backticks. Content inside is raw (no parsing):
@@ -766,5 +862,19 @@ Content of Section B.
 
             **Also right:** \`[See domain-model.sdoc § my-section](./domain-model.sdoc#my-section)\`
         }
+
+        # [@key] vs @key @citation-vs-ref
+        {
+            \`[@key]\` is a **citation reference** — it renders as a numbered superscript linking to a citation entry. \`@key\` is a **section reference** — it renders as a clickable link to a heading with that ID.
+
+            Confusing them will produce errors:
+
+            {[.]
+                - Writing \`@smith2020\` when you mean \`[@smith2020]\` creates a broken section reference (there is no heading with ID \`smith2020\`)
+                - Writing \`[@setup]\` when you mean \`@setup\` creates a broken citation (there is no citation definition for \`setup\`)
+            }
+
+            Rule of thumb: square brackets mean citation, bare \`@\` means section.
+        }
     }
 }

package/lexica/specification.sdoc

@@ -380,6 +380,69 @@ Content of Section B.
                 ```
             }
 
+            # Column Directives @column-directives
+            {
+                An optional directive row immediately after the header row (or as the first row in a headerless table) controls per-column alignment and number formatting. The directive row is consumed by the parser and never rendered as data.
+
+                # Column Alignment @column-alignment
+                {
+                    Alignment characters in the directive row set the text-align for all cells in that column, including the header:
+
+                    {[.]
+                        - `<` — left (default)
+                        - `>` — right (most useful for numbers and currency)
+                        - `=` — center
+                    }
+
+                    ```
+{[table]
+    Programme | Amount | Status
+    < | > | =
+    Alpha | $1,000,000 | Active
+    Beta | $2,500,000 | Pending
+}
+                    ```
+
+                    If the directive row is absent, all columns default to left alignment. Empty cells in the directive row inherit the default (left).
+                }
+
+                # Column Formatting @column-formatting
+                {
+                    A format token in the directive row causes numeric cells and formula results in that column to be formatted for display. Text cells are unaffected. The format is display-only — formulas always operate on raw numeric values.
+
+                    {[.]
+                        - `$` — currency, no decimals: `1000000` → `$1,000,000`
+                        - `$.N` — currency with N decimals: `$.2` → `$1,234.50`
+                        - `,` — thousands separator, no decimals: `1000000` → `1,000,000`
+                        - `,.N` — thousands with N decimals: `,.2` → `1,234,567.89`
+                        - `.N` — fixed N decimals: `.2` → `3.14`
+                        - `%` — percentage (value × 100, auto decimals): `0.452` → `45.2%`
+                        - `%.N` — percentage with N decimals: `%.1` → `45.7%`
+                    }
+
+                    A directive cell may combine alignment and format, separated by whitespace:
+
+                    ```
+{[table]
+    Item | Amount
+    < | > $
+    Widget | 1000000
+    Gadget | 2500000
+    **Total** | =SUM(B1:B2)
+}
+                    ```
+
+                    All numeric values and formula results in the `Amount` column display as currency (`$3,500,000`). The `**Total**` label renders normally as bold text.
+                }
+
+                # Directive Row Detection @directive-detection
+                {
+                    A row is identified as a directive row when every non-empty cell contains only an alignment character (`<`, `>`, `=`), a format token, or both. It must be the first row after the header (or the first row in a headerless table), and at least one cell must contain a directive.
+
+                    For headerless tables, the directive row functions as a virtual header — it is consumed for its directives but no `<thead>` is rendered.
+                }
+            }
+
             # Table Formulas @table-formulas
             {
                 Table cells whose text begins with `=` (but not `==`) are evaluated as formulas. The result replaces the cell text in rendered output; the original formula is preserved as a tooltip.
@@ -474,6 +537,84 @@ Content of Section B.
             }
         }
 
+        # Citations @citations
+        {
+            Citations provide stable, auto-numbered source references. An inline citation reference uses `[@key]`; citation definitions go in a `{[citations]` block.
+
+            # Inline Citation References @citation-refs
+            {
+                ```
+                The market is growing rapidly [@mm-report].
+                Multiple sources agree [@mm-report, @mordor-analysis].
+                ```
+
+                {[.]
+                    - `[@key]` inserts a citation reference that renders as a clickable superscript number (e.g. `[1]`) linking to the corresponding entry in the `{[citations]` block
+                    - `[@key1, @key2]` renders as `[1, 3]` (or whatever the assigned numbers are), with each number individually linked
+                    - Whitespace around commas is optional and ignored
+                    - Keys follow the existing `@slug` convention: lowercase kebab-case
+                    - `[@key]` is visually and semantically distinct from `@slug` — the former is a citation, the latter is a section reference
+                    - The same `[@key]` used multiple times always renders the same number
+                    - Citation keys are document-local, like section references
+                }
+            }
+
+            # Citation Definition Block @citation-block
+            {
+                ```
+{[citations]
+    - @mm-report MarketsandMarkets, "Edge AI Hardware Market,"
+      Report SE 7017, June 2025.
+    - @mordor-analysis Mordor Intelligence, "Edge AI Chips Market
+      Size & Share Analysis," 2026.
+}
+                ```
+
+                {[.]
+                    - `{[citations]` opens a citation definition block (no closing brace on the same line)
+                    - Each citation is a list item with a `- @key` prefix followed by free-form inline content
+                    - Citation text supports full SDOC inline formatting: links, bold, italics, inline code
+                    - There are no structured bibliographic fields — the author formats the citation however they want
+                    - Item text can span multiple continuation lines (same rules as list item continuation)
+                    - The closing `}` must be on its own line
+                    - Works with K&R brace style: `# References {[citations]`
+                }
+            }
+
+            # Numbering @citation-numbering
+            {
+                {[.]
+                    - Numbers are assigned by order of first appearance of `[@key]` in the document text, starting at 1
+                    - The `{[citations]` block renders entries sorted by assigned number, regardless of definition order
+                    - Numbers always increase monotonically as the reader moves through the document
+                    - Defined but unreferenced citations are appended after all referenced entries
+                }
+            }
+
+            # Multiple Blocks @citation-multiple-blocks
+            {
+                Multiple `{[citations]` blocks are allowed in a single document. All blocks share a unified numbering sequence. Each block renders at its own position in the document. This lets authors place citation definitions near the content that references them.
+            }
+
+            # Rendering @citation-rendering
+            {
+                {[.]
+                    - In-text: `[@key]` renders as a superscript bracketed number linking to the entry (e.g. `[1]`)
+                    - Citation list: each entry renders with its assigned number, the citation text, and a back-link (`\u21A9`) to the first location where it was cited
+                    - Only the first occurrence of each `[@key]` in the text receives an anchor ID for the back-link
+                }
+            }
+
+            # Errors and Warnings @citation-errors
+            {
+                {[.]
+                    - `[@key]` with no matching definition in any `{[citations]` block: **warning** (renders with a broken-reference indicator, same as a broken `@slug`)
+                    - Citation defined but never referenced: **warning** (entry is still rendered, but the author is told it is unused)
+                    - Invalid entry inside `{[citations]` (not matching `- @key text`): **parse error**
+                }
+            }
+        }
+
         # Links @links
         {
             Markdown-style links with absolute URLs or relative file paths:
@@ -578,9 +719,13 @@ Content of Section B.
                 - Warning marker: `{!text!}` (orange highlight)
                 - Negative marker: `{-text-}` (red highlight)
                 - Highlight: `{~text~}` (yellow highlight)
+                - Citation reference: `[@key]` (numbered superscript link to citation entry)
+                - Multiple citation references: `[@key1, @key2]` (each individually linked)
             }
 
             Inline math requires non-whitespace immediately after the opening `$` and before the closing `$`. A plain `$` followed by a digit (e.g. `$100`) does not trigger math mode because there is no closing `$`.
+
+            Citation references (`[@key]`) are parsed before link syntax. `[@key]` is always a citation reference even if followed by `(url)`. Use `\[@key]` for a literal `[@key]` in text.
         }
 
         # Escaping @escaping
@@ -949,6 +1094,7 @@ Content of Section A.
             - `}` scope close
             - `{[.]` / `{[#]` list open
             - `{[table]` / `{[table <flags>]` table open
+            - `{[citations]` citations block open
             - `>` blockquote line
             - `---` / `***` / `___` horizontal rule
             - `` ``` `` code fence
@@ -977,18 +1123,19 @@ Content of Section A.
                           ((ws id)? (ws scope_type)? | (ws scope_type)? (ws id)?) ws block_opener ;
         id            = "@" ident ;
         scope_type    = ":" ident ;   (* id and scope_type may appear in either order *)
-        block_opener  = "{" | "{[.]" | "{[#]" | table_open ;
+        block_opener  = "{" | "{[.]" | "{[#]" | table_open | citations_open ;
         block         = "{" ws? block_body "}" ;
         braceless_body = { paragraph | code_block | data_block | blockquote
                          | implicit_list | horizontal_rule | headingless_scope
-                         | list_scope | table_scope | bare_directive
-                         | line_comment | blank } ;
+                         | list_scope | table_scope | citations_scope
+                         | bare_directive | line_comment | blank } ;
 
         bare_directive = "@" ("meta" | "about") (ws block | braceless_body) ;
         block_body    = { blank | line_comment | paragraph | scope
                         | headingless_scope | list_scope | table_scope
-                        | implicit_list | blockquote | horizontal_rule
-                        | code_block | data_block | bare_directive | comma_sep } ;
+                        | citations_scope | implicit_list | blockquote
+                        | horizontal_rule | code_block | data_block
+                        | bare_directive | comma_sep } ;
         headingless_scope = "{" ws? block_body "}" ;
         list_scope    = list_open ws? list_body "}" ;
         list_open     = "{[.]" | "{[#]" ;
@@ -999,8 +1146,19 @@ Content of Section A.
                       | "left" | "center" | "right" ;
         percentage    = digit { digit } [ "." digit { digit } ] "%" ;
         pixels        = digit { digit } "px" ;
-        table_body    = table_row { table_row } ;
+        table_body    = [ directive_row ] table_row { table_row } ;
+        directive_row = directive_cell { "|" directive_cell } ;
+        directive_cell = [ align_char ] [ ws format_spec ] ;
+        align_char    = "<" | ">" | "=" ;
+        format_spec   = "$" [ "." digits ]
+                      | "," [ "." digits ]
+                      | "." digits
+                      | "%" [ "." digits ] ;
         table_row     = cell { "|" cell } ;
+        citations_scope = citations_open ws? citations_body "}" ;
+        citations_open  = "{[citations]" ;
+        citations_body  = { blank | citation_entry } ;
+        citation_entry  = "-" ws "@" ident ws text_line { continuation_line } ;
         list_body     = { blank | comma_sep | scope | list_item_shorthand
                         | anonymous_item } ;
         implicit_list = list_item_shorthand { list_item_shorthand } ;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@entropicwarrior/sdoc",
   "displayName": "SDOC - Docs for Human/Agent Teams",
   "description": "A plain-text documentation format with explicit brace scoping — deterministic parsing, AI-agent efficiency, and 10-50x token savings vs Markdown.",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "publisher": "entropicwarrior-msenfin",
   "license": "MIT",
   "repository": {

package/src/sdoc.js

@@ -11,6 +11,7 @@ const COMMAND_SCOPE_CLOSE = "}";
 const COMMAND_LIST_BULLET = "{[.]";
 const COMMAND_LIST_NUMBER = "{[#]";
 const COMMAND_TABLE = "{[table]";
+const COMMAND_CITATIONS = "{[citations]";
 const COMMAND_CODE_FENCE = "```";
 
 const ESCAPABLE = new Set(["\\", "{", "}", "@", "[", "]", "(", ")", "*", "`", "#", "!", "~", "<", ">", "$", "+", "=", "-", "^", "?", "|"]);
@@ -41,6 +42,10 @@ function isTableCommand(text) {
   return /^\{\[table(?:\s+[^\]]*?)?\]$/.test(text);
 }
 
+function isCitationsCommand(text) {
+  return text === COMMAND_CITATIONS;
+}
+
 function parseTableOptions(text) {
   const match = text.match(/^\{\[table(?:\s+(.*))?\]$/);
   if (!match) return {};
@@ -58,6 +63,105 @@ function parseTableOptions(text) {
   return options;
 }
 
+// ── Column directive row (alignment + format) ──────────────────────────
+
+function isDirectiveRow(cells) {
+  if (cells.length === 0) return false;
+  const pattern = /^([<>=])?\s*(\$(?:\.\d+)?|,(?:\.\d+)?|\.\d+|%(?:\.\d+)?)?$/;
+  let hasDirective = false;
+  for (const cell of cells) {
+    const trimmed = cell.trim();
+    if (trimmed === "") continue;
+    if (!pattern.test(trimmed)) return false;
+    hasDirective = true;
+  }
+  return hasDirective;
+}
+
+function parseFormatSpec(spec) {
+  if (!spec) return null;
+  if (spec.startsWith("$")) {
+    const decimals = spec.includes(".") ? parseInt(spec.slice(spec.indexOf(".") + 1), 10) : 0;
+    return { prefix: "$", thousands: true, decimals, percent: false };
+  }
+  if (spec.startsWith("%")) {
+    const decimals = spec.includes(".") ? parseInt(spec.slice(spec.indexOf(".") + 1), 10) : -1;
+    return { prefix: "", thousands: false, decimals, percent: true };
+  }
+  if (spec.startsWith(",")) {
+    const decimals = spec.includes(".") ? parseInt(spec.slice(spec.indexOf(".") + 1), 10) : 0;
+    return { prefix: "", thousands: true, decimals, percent: false };
+  }
+  if (spec.startsWith(".")) {
+    const decimals = parseInt(spec.slice(1), 10);
+    return { prefix: "", thousands: false, decimals, percent: false };
+  }
+  return null;
+}
+
+function parseDirectiveRow(cells) {
+  const align = [];
+  const format = [];
+  let hasAlign = false;
+  let hasFormat = false;
+  const fmtPattern = /(\$(?:\.\d+)?|,(?:\.\d+)?|\.\d+|%(?:\.\d+)?)$/;
+
+  for (const cell of cells) {
+    const trimmed = cell.trim();
+    const alignMatch = trimmed.match(/^([<>=])/);
+    const fmtMatch = trimmed.match(fmtPattern);
+
+    let a = null;
+    if (alignMatch) {
+      a = alignMatch[1] === "<" ? "left" : alignMatch[1] === ">" ? "right" : "center";
+      hasAlign = true;
+    }
+    align.push(a);
+
+    let f = null;
+    if (fmtMatch) {
+      f = parseFormatSpec(fmtMatch[1]);
+      hasFormat = true;
+    }
+    format.push(f);
+  }
+
+  return {
+    align: hasAlign ? align : null,
+    format: hasFormat ? format : null,
+  };
+}
+
+function formatNumber(value, spec) {
+  if (spec.percent) {
+    const pct = value * 100;
+    if (spec.decimals < 0) {
+      return (Number.isInteger(pct) ? pct.toString() : pct.toFixed(2).replace(/\.?0+$/, "")) + "%";
+    }
+    return pct.toFixed(spec.decimals) + "%";
+  }
+
+  const negative = value < 0;
+  const absVal = Math.abs(value);
+  let result;
+
+  if (spec.decimals > 0) {
+    result = absVal.toFixed(spec.decimals);
+  } else {
+    result = Math.round(absVal).toString();
+  }
+
+  if (spec.thousands) {
+    const parts = result.split(".");
+    parts[0] = parts[0].replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+    result = parts.join(".");
+  }
+
+  return (negative ? "-" : "") + spec.prefix + result;
+}
+
+// ── End column directive row ────────────────────────────────────────────
+
 class LineCursor {
   constructor(lines) {
     this.lines = lines;
@@ -299,6 +403,12 @@ function parseBlock(cursor, kind) {
       continue;
     }
 
+    if (isCitationsCommand(trimmed)) {
+      flushParagraph();
+      nodes.push(parseCitationsBlock(cursor));
+      continue;
+    }
+
     if (trimmed === COMMAND_SCOPE_OPEN) {
       flushParagraph();
       const scopeStartLine = cursor.index + 1;
@@ -340,6 +450,13 @@ function extractTrailingOpener(text) {
       return { text: trimmed.slice(0, pos).trimEnd(), opener: tableMatch[0] };
     }
   }
+  // Check for citations command: {[citations]
+  if (trimmed.endsWith(COMMAND_CITATIONS)) {
+    const pos = trimmed.length - COMMAND_CITATIONS.length;
+    if (!(pos > 0 && trimmed[pos - 1] === "\\")) {
+      return { text: trimmed.slice(0, pos).trimEnd(), opener: COMMAND_CITATIONS };
+    }
+  }
   // Check other openers
   const openers = [COMMAND_LIST_NUMBER, COMMAND_LIST_BULLET, COMMAND_SCOPE_OPEN];
   for (const opener of openers) {
@@ -388,6 +505,8 @@ function parseScope(cursor) {
     } else if (isTableCommand(trailing.opener)) {
       const tableOpts = parseTableOptions(trailing.opener);
       children = [parseTableBody(cursor, scopeStartLine, tableOpts)];
+    } else if (isCitationsCommand(trailing.opener)) {
+      children = [parseCitationsBody(cursor, scopeStartLine)];
     } else {
       children = parseBlock(cursor, "normal");
     }
@@ -545,6 +664,12 @@ function parseBracelessBlock(cursor) {
       continue;
     }
 
+    if (isCitationsCommand(trimmed)) {
+      flushParagraph();
+      nodes.push(parseCitationsBlock(cursor));
+      continue;
+    }
+
     if (!paragraphLines.length) {
       paragraphStartLine = cursor.index + 1;
     }
@@ -594,6 +719,10 @@ function parseScopeBlock(cursor) {
       return { blockType: "normal", children: [parseTableBlock(cursor)] };
     }
 
+    if (isCitationsCommand(trimmed)) {
+      return { blockType: "normal", children: [parseCitationsBlock(cursor)] };
+    }
+
     // No block opener found — braceless scope
     return { blockType: "braceless" };
   }
@@ -689,6 +818,7 @@ function isListContinuationLine(trimmedLeft) {
   if (trimmed === COMMAND_LIST_BULLET) return false;
   if (trimmed === COMMAND_LIST_NUMBER) return false;
   if (isTableCommand(trimmed)) return false;
+  if (isCitationsCommand(trimmed)) return false;
   if (trimmed === ",") return false;
   if (isHeadingLine(trimmedLeft)) return false;
   if (isBlockquoteLine(trimmedLeft)) return false;
@@ -720,6 +850,8 @@ function parseListItemLine(cursor, info, allowContinuation = false) {
     } else if (isTableCommand(trailing.opener)) {
       const tableOpts = parseTableOptions(trailing.opener);
       children = [parseTableBody(cursor, itemStartLine, tableOpts)];
+    } else if (isCitationsCommand(trailing.opener)) {
+      children = [parseCitationsBody(cursor, itemStartLine)];
     } else {
       children = parseBlock(cursor, "normal");
     }
@@ -802,21 +934,91 @@ function parseTableBody(cursor, tableStartLine, options) {
     cursor.next();
   }
 
+  // Detect column directive row (alignment / formatting)
+  // For headerless tables: check rows[0]; for normal tables: check rows[1] (after header)
+  const directiveIndex = options.headerless ? 0 : 1;
+  let columnAlign = null;
+  let columnFormat = null;
+  if (rows.length > directiveIndex && isDirectiveRow(rows[directiveIndex])) {
+    const directives = parseDirectiveRow(rows[directiveIndex]);
+    columnAlign = directives.align;
+    columnFormat = directives.format;
+    rows.splice(directiveIndex, 1);
+  }
+
   const hasOptions = options.borderless || options.headerless || options.width || options.align;
 
+  let tableNode;
   if (options.headerless) {
-    const tableNode = { type: "table", headers: [], rows, lineStart: tableStartLine, lineEnd: cursor.index };
-    if (hasOptions) tableNode.options = options;
-    return tableNode;
+    tableNode = { type: "table", headers: [], rows, lineStart: tableStartLine, lineEnd: cursor.index };
+  } else {
+    const headers = rows.length > 0 ? rows[0] : [];
+    const body = rows.slice(1);
+    tableNode = { type: "table", headers, rows: body, lineStart: tableStartLine, lineEnd: cursor.index };
   }
-
-  const headers = rows.length > 0 ? rows[0] : [];
-  const body = rows.slice(1);
-  const tableNode = { type: "table", headers, rows: body, lineStart: tableStartLine, lineEnd: cursor.index };
   if (hasOptions) tableNode.options = options;
+  if (columnAlign) tableNode.columnAlign = columnAlign;
+  if (columnFormat) tableNode.columnFormat = columnFormat;
   return tableNode;
 }
 
+function parseCitationsBlock(cursor) {
+  const startLine = cursor.index + 1;
+  cursor.next();
+  return parseCitationsBody(cursor, startLine);
+}
+
+function parseCitationsBody(cursor, startLine) {
+  const entries = [];
+
+  while (!cursor.eof()) {
+    const line = cursor.current();
+    const trimmedLeft = line.replace(/^\s+/, "");
+    const trimmed = trimmedLeft.trim();
+
+    if (trimmed === "") {
+      cursor.next();
+      continue;
+    }
+
+    if (trimmed === COMMAND_SCOPE_CLOSE) {
+      cursor.next();
+      break;
+    }
+
+    // Citation items: - @key free-form text
+    const citationMatch = trimmed.match(/^-\s+@([A-Za-z_][A-Za-z0-9_-]*)\s+([\s\S]*)$/);
+    if (citationMatch) {
+      const entryStartLine = cursor.index + 1;
+      const key = citationMatch[1];
+      let text = citationMatch[2].trim();
+      cursor.next();
+
+      // Collect continuation lines (indented text not starting with - @key or })
+      while (!cursor.eof()) {
+        const nextLine = cursor.current();
+        const nextTrimmedLeft = nextLine.replace(/^\s+/, "");
+        const nextTrimmed = nextTrimmedLeft.trim();
+
+        if (nextTrimmed === "") break;
+        if (nextTrimmed === COMMAND_SCOPE_CLOSE) break;
+        if (/^-\s+@[A-Za-z_]/.test(nextTrimmed)) break;
+
+        text += " " + nextTrimmed;
+        cursor.next();
+      }
+
+      entries.push({ key, text, lineStart: entryStartLine, lineEnd: cursor.index });
+      continue;
+    }
+
+    cursor.error("Invalid citation entry (expected '- @key text').");
+    cursor.next();
+  }
+
+  return { type: "citations", entries, lineStart: startLine, lineEnd: cursor.index };
+}
+
 function parseOptionalBlock(cursor) {
   while (!cursor.eof()) {
     const line = cursor.current();
@@ -1123,6 +1325,18 @@ function parseImageWidth(raw) {
   return { src: raw };
 }
 
+function parseCitationKeys(inner) {
+  // Parse "@key1, @key2, ..." — returns array of keys or null if invalid
+  const parts = inner.split(",");
+  const keys = [];
+  for (const part of parts) {
+    const match = part.trim().match(/^@([A-Za-z_][A-Za-z0-9_-]*)$/);
+    if (!match) return null;
+    keys.push(match[1]);
+  }
+  return keys.length > 0 ? keys : null;
+}
+
 function parseInline(text) {
   const nodes = [];
   let buffer = "";
@@ -1252,6 +1466,21 @@ function parseInline(text) {
       }
     }
 
+    // Citation references: [@key] or [@key1, @key2]
+    if (ch === "[" && text[i + 1] === "@") {
+      const endBracket = findUnescaped(text, i + 1, "]");
+      if (endBracket !== -1) {
+        const inner = text.slice(i + 1, endBracket).trim();
+        const keys = parseCitationKeys(inner);
+        if (keys) {
+          flush();
+          nodes.push({ type: "citation_ref", keys });
+          i = endBracket + 1;
+          continue;
+        }
+      }
+    }
+
     if (ch === "[") {
       const endLabel = findUnescaped(text, i + 1, "]");
       if (endLabel !== -1 && text[endLabel + 1] === "(") {
@@ -1371,6 +1600,81 @@ function findUnescaped(text, start, token) {
 
 let _renderOptions = {};
 
+// --- Citation numbering ---
+// Built before rendering; maps citation key → { number, anchorId }
+// anchorId is the id of the first inline citation_ref for back-linking
+let _citationNumbering = new Map();
+let _citationDefinitions = new Map(); // key → { text, lineStart, lineEnd }
+
+function buildCitationNumbering(nodes) {
+  const numbering = new Map();
+  const definitions = new Map();
+  let counter = 0;
+
+  // First pass: collect all citation_ref keys in document order to assign numbers
+  function walkInlineNodes(inlineNodes) {
+    for (const node of inlineNodes) {
+      if (node.type === "citation_ref") {
+        for (const key of node.keys) {
+          if (!numbering.has(key)) {
+            counter += 1;
+            numbering.set(key, { number: counter, anchorId: `citeref-${key}` });
+          }
+        }
+      }
+      if (node.children) walkInlineNodes(node.children);
+    }
+  }
+
+  function walkInlineText(text) {
+    walkInlineNodes(parseInline(text));
+  }
+
+  function walk(nodeList) {
+    for (const node of nodeList) {
+      if (node.type === "paragraph" && node.text) {
+        walkInlineText(node.text);
+      } else if (node.type === "blockquote" && node.paragraphs) {
+        for (const para of node.paragraphs) {
+          walkInlineText(para);
+        }
+      } else if (node.type === "scope") {
+        if (node.title) walkInlineText(node.title);
+        if (node.children) walk(node.children);
+      } else if (node.type === "list" && node.items) {
+        walk(node.items);
+      } else if (node.type === "table") {
+        if (node.headers) {
+          for (const cell of node.headers) walkInlineText(cell);
+        }
+        if (node.rows) {
+          for (const row of node.rows) {
+            for (const cell of row) walkInlineText(cell);
+          }
+        }
+      } else if (node.type === "citations") {
+        // Collect definitions
+        for (const entry of node.entries) {
+          if (!definitions.has(entry.key)) {
+            definitions.set(entry.key, { text: entry.text, lineStart: entry.lineStart, lineEnd: entry.lineEnd });
+          }
+        }
+      }
+    }
+  }
+  walk(nodes);
+
+  // Assign numbers to defined-but-unreferenced citations (appended after referenced ones)
+  for (const [key, def] of definitions) {
+    if (!numbering.has(key)) {
+      counter += 1;
+      numbering.set(key, { number: counter, anchorId: null });
+    }
+  }
+
+  return { numbering, definitions };
+}
+
 function dataLineAttrs(node) {
   if (node.lineStart == null) {
     return "";
@@ -1441,6 +1745,24 @@ function renderInlineNodes(nodes) {
           }
           return `<a class="sdoc-ref" href="${href}">@${escapeHtml(node.id)}</a>`;
         }
+        case "citation_ref": {
+          if (!_renderOptions._citationRefSeen) _renderOptions._citationRefSeen = new Set();
+          const parts = node.keys.map((key) => {
+            const info = _citationNumbering.get(key);
+            const isBroken = !_citationDefinitions.has(key);
+            if (isBroken) {
+              // Undefined citation — render with warning
+              const num = info ? info.number : escapeHtml(key);
+              return `<a class="sdoc-citation-ref sdoc-broken-ref" href="#cite-${escapeAttr(key)}"><span class="sdoc-broken-icon">\u26A0</span>${num}</a>`;
+            }
+            // Only the first occurrence of each key gets the back-link anchor id
+            const isFirst = !_renderOptions._citationRefSeen.has(key);
+            if (isFirst) _renderOptions._citationRefSeen.add(key);
+            const idAttr = isFirst ? ` id="citeref-${escapeAttr(key)}"` : "";
+            return `<a class="sdoc-citation-ref"${idAttr} href="#cite-${escapeAttr(key)}">${info.number}</a>`;
+          });
+          return `<sup class="sdoc-citation-group">[${parts.join(", ")}]</sup>`;
+        }
         case "code":
           return `<code class="sdoc-inline-code">${escapeHtml(node.value)}</code>`;
         case "em":
@@ -1517,6 +1839,33 @@ function renderScope(scope, depth, isTitleScope = false) {
   return `<section class="sdoc-scope${rootClass}${typeClass}"${typeAttr}>${heading}${childrenHtml}</section>`;
 }
 
+function renderCitations(node) {
+  const dl = dataLineAttrs(node);
+
+  // Build entries sorted by assigned citation number
+  const sorted = [];
+  for (const entry of node.entries) {
+    const info = _citationNumbering.get(entry.key);
+    if (info) {
+      sorted.push({ key: entry.key, text: entry.text, number: info.number, anchorId: info.anchorId });
+    } else {
+      // Defined but no number (shouldn't happen if buildCitationNumbering ran, but be safe)
+      sorted.push({ key: entry.key, text: entry.text, number: Infinity, anchorId: null });
+    }
+  }
+  sorted.sort((a, b) => a.number - b.number);
+
+  const items = sorted.map((entry) => {
+    const backLink = entry.anchorId
+      ? ` <a class="sdoc-citation-backlink" href="#${escapeAttr(entry.anchorId)}" title="Back to text">\u21A9</a>`
+      : "";
+    const unreferenced = entry.anchorId === null ? " sdoc-citation-unreferenced" : "";
+    return `<li id="cite-${escapeAttr(entry.key)}" class="sdoc-citation-entry${unreferenced}" value="${entry.number}"><span class="sdoc-citation-text">${renderInline(entry.text)}</span>${backLink}</li>`;
+  }).join("\n");
+
+  return `<ol class="sdoc-citations"${dl}>${items}</ol>`;
+}
+
 function renderList(list, depth) {
   return renderListFromItems(list.listType, list.items, depth, list);
 }
@@ -1885,15 +2234,23 @@ function formatFormulaResult(cell) {
 function renderTable(table) {
   const dl = dataLineAttrs(table);
   const opts = table.options || {};
+  const colAlign = table.columnAlign || [];
+  const colFormat = table.columnFormat || [];
   const classes = ["sdoc-table"];
   if (opts.borderless) classes.push("sdoc-table-borderless");
   if (opts.headerless) classes.push("sdoc-table-headerless");
   const classAttr = classes.join(" ");
 
+  function cellStyle(colIndex) {
+    const align = colAlign[colIndex];
+    if (!align || align === "left") return "";
+    return ` style="text-align:${align}"`;
+  }
+
   let thead = "";
   if (table.headers.length > 0) {
     const headerCells = table.headers
-      .map((cell) => `<th class="sdoc-table-th">${renderInline(cell)}</th>`)
+      .map((cell, c) => `<th class="sdoc-table-th"${cellStyle(c)}>${renderInline(cell)}</th>`)
       .join("");
     thead = `<thead class="sdoc-table-head"><tr>${headerCells}</tr></thead>`;
   }
@@ -1905,16 +2262,33 @@ function renderTable(table) {
     .map((row, r) => {
       const cells = row
         .map((cell, c) => {
+          const style = cellStyle(c);
+          const fmt = colFormat[c] || null;
+
           if (isFormulaCell(cell)) {
             const result = grid[r][c];
-            const display = escapeHtml(formatFormulaResult(result));
+            let display;
+            if (!result.error && fmt) {
+              display = escapeHtml(formatNumber(result.value, fmt));
+            } else {
+              display = escapeHtml(formatFormulaResult(result));
+            }
             const formula = escapeAttr(cell.trim());
             if (result.error) {
-              return `<td class="sdoc-table-td sdoc-formula-error" title="${formula}">${display}</td>`;
+              return `<td class="sdoc-table-td sdoc-formula-error"${style} title="${formula}">${display}</td>`;
+            }
+            return `<td class="sdoc-table-td sdoc-formula-cell"${style} title="${formula}">${display}</td>`;
+          }
+
+          // Apply column format to numeric data cells
+          if (fmt) {
+            const parsed = parseCellValue(cell);
+            if (!isNaN(parsed.value)) {
+              return `<td class="sdoc-table-td"${style}>${escapeHtml(formatNumber(parsed.value, fmt))}</td>`;
             }
-            return `<td class="sdoc-table-td sdoc-formula-cell" title="${formula}">${display}</td>`;
           }
-          return `<td class="sdoc-table-td">${renderInline(cell)}</td>`;
+
+          return `<td class="sdoc-table-td"${style}>${renderInline(cell)}</td>`;
         })
         .join("");
       return `<tr>${cells}</tr>`;
@@ -1955,6 +2329,8 @@ function renderNode(node, depth) {
       const editable = _renderOptions.editable ? ` contenteditable="true"` : "";
       return `<p class="sdoc-paragraph"${dl}${editable}>${renderInline(node.text)}</p>`;
     }
+    case "citations":
+      return renderCitations(node);
     case "code": {
       if (node.lang === "mermaid") {
         return `<pre class="mermaid"${dl}>${escapeHtml(node.text)}</pre>`;
@@ -2392,6 +2768,62 @@ const DEFAULT_STYLE = `
     margin-right: 0.15em;
   }
 
+  .sdoc-citation-group {
+    font-size: 0.8em;
+    line-height: 1;
+    vertical-align: super;
+  }
+
+  .sdoc-citation-ref {
+    color: var(--sdoc-accent);
+    text-decoration: none;
+    cursor: pointer;
+  }
+
+  .sdoc-citation-ref:hover {
+    text-decoration: underline;
+  }
+
+  .sdoc-citations {
+    margin: 1.5rem 0;
+    padding: 1rem 0 0.5rem 0;
+    border-top: 1px solid var(--sdoc-border);
+    list-style: none;
+    counter-reset: none;
+  }
+
+  .sdoc-citation-entry {
+    margin: 0.4rem 0;
+    padding-left: 2.5rem;
+    position: relative;
+    line-height: 1.6;
+    font-size: 0.92em;
+  }
+
+  .sdoc-citation-entry::before {
+    content: "[" attr(value) "]";
+    position: absolute;
+    left: 0;
+    color: var(--sdoc-muted);
+    font-weight: 600;
+    font-size: 0.9em;
+  }
+
+  .sdoc-citation-unreferenced {
+    opacity: 0.6;
+  }
+
+  .sdoc-citation-backlink {
+    color: var(--sdoc-accent);
+    text-decoration: none;
+    margin-left: 0.3em;
+    font-size: 0.85em;
+  }
+
+  .sdoc-citation-backlink:hover {
+    text-decoration: underline;
+  }
+
   .sdoc-image {
     display: inline-block;
     max-width: 100%;
@@ -2592,7 +3024,7 @@ hljs.COMMENT('^\\\\s*//','$'),
   {className:'link',begin:'\\\\(',end:'\\\\)'}
 ]},
 {className:'keyword',begin:'\\\\{[!?+\\\\-=~^]',end:'[!?+\\\\-=~^]\\\\}'},
-{className:'keyword',begin:'\\\\{\\\\[(?:\\\\.|#|\\\\d+|table)\\\\]'},
+{className:'keyword',begin:'\\\\{\\\\[(?:\\\\.|#|\\\\d+|table|citations)\\\\]'},
 {className:'strong',begin:'\\\\*\\\\*',end:'\\\\*\\\\*'},
 {className:'emphasis',begin:'(?<!\\\\*)\\\\*(?!\\\\*)',end:'\\\\*(?!\\\\*)'},
 {className:'deletion',begin:'~~',end:'~~'},
@@ -2648,12 +3080,26 @@ function renderBodyNodes(nodes) {
 function renderHtmlBody(text) {
   const parsed = parseSdoc(text);
   const metaResult = extractMeta(parsed.nodes);
-  return renderBodyNodes(metaResult.nodes);
+  const savedOptions = _renderOptions;
+  _renderOptions = {};
+  const citationData = buildCitationNumbering(metaResult.nodes);
+  _citationNumbering = citationData.numbering;
+  _citationDefinitions = citationData.definitions;
+  const result = renderBodyNodes(metaResult.nodes);
+  _citationNumbering = new Map();
+  _citationDefinitions = new Map();
+  _renderOptions = savedOptions;
+  return result;
 }
 
 function renderHtmlDocumentFromParsed(parsed, title, options = {}) {
   _renderOptions = options.renderOptions ?? {};
+  const citationData = buildCitationNumbering(parsed.nodes);
+  _citationNumbering = citationData.numbering;
+  _citationDefinitions = citationData.definitions;
   const body = renderBodyNodes(parsed.nodes);
+  _citationNumbering = new Map();
+  _citationDefinitions = new Map();
   _renderOptions = {};
   const errorHtml = renderErrors(parsed.errors);
 
@@ -2782,11 +3228,12 @@ function formatSdoc(text, indentStr = "    ") {
       continue;
     }
 
-    // Standalone opener: {, {[.], {[#], {[table]
+    // Standalone opener: {, {[.], {[#], {[table], {[citations]
     if (trimmed === COMMAND_SCOPE_OPEN ||
         trimmed === COMMAND_LIST_BULLET ||
         trimmed === COMMAND_LIST_NUMBER ||
-        isTableCommand(trimmed)) {
+        isTableCommand(trimmed) ||
+        isCitationsCommand(trimmed)) {
       result.push(indentStr.repeat(depth) + trimmed);
       depth++;
       continue;
@@ -3017,6 +3464,7 @@ function collectAllIds(nodes) {
 function collectInlineRefs(nodes) {
   const refs = [];
   const links = [];
+  const citationRefs = [];
 
   function walkInlineNodes(inlineNodes, lineStart, lineEnd) {
     for (const node of inlineNodes) {
@@ -3024,6 +3472,10 @@ function collectInlineRefs(nodes) {
         refs.push({ id: node.id, lineStart, lineEnd });
       } else if (node.type === "link") {
         links.push({ href: node.href, lineStart, lineEnd });
+      } else if (node.type === "citation_ref") {
+        for (const key of node.keys) {
+          citationRefs.push({ key, lineStart, lineEnd });
+        }
       }
       if (node.children) {
         walkInlineNodes(node.children, lineStart, lineEnd);
@@ -3073,7 +3525,24 @@ function collectInlineRefs(nodes) {
     }
   }
   walk(nodes);
-  return { refs, links };
+  return { refs, links, citationRefs };
+}
+
+function collectCitationDefinitions(nodes) {
+  const defs = [];
+  function walk(nodeList) {
+    for (const node of nodeList) {
+      if (node.type === "citations") {
+        for (const entry of node.entries) {
+          defs.push({ key: entry.key, lineStart: entry.lineStart, lineEnd: entry.lineEnd });
+        }
+      }
+      if (node.children) walk(node.children);
+      if (node.type === "list" && node.items) walk(node.items);
+    }
+  }
+  walk(nodes);
+  return defs;
 }
 
 function validateRefs(nodes, options = {}) {
@@ -3117,6 +3586,43 @@ function validateRefs(nodes, options = {}) {
   return warnings;
 }
 
+function validateCitations(nodes) {
+  const { citationRefs } = collectInlineRefs(nodes);
+  const defs = collectCitationDefinitions(nodes);
+  const warnings = [];
+
+  const definedKeys = new Set(defs.map((d) => d.key));
+  const referencedKeys = new Set(citationRefs.map((r) => r.key));
+
+  // Citation referenced but not defined
+  for (const ref of citationRefs) {
+    if (!definedKeys.has(ref.key)) {
+      warnings.push({
+        type: "broken-citation",
+        key: ref.key,
+        message: `Broken citation: [@${ref.key}] is not defined in any {[citations] block`,
+        lineStart: ref.lineStart,
+        lineEnd: ref.lineEnd
+      });
+    }
+  }
+
+  // Citation defined but never referenced
+  for (const def of defs) {
+    if (!referencedKeys.has(def.key)) {
+      warnings.push({
+        type: "unused-citation",
+        key: def.key,
+        message: `Unused citation: @${def.key} is defined but never referenced with [@${def.key}]`,
+        lineStart: def.lineStart,
+        lineEnd: def.lineEnd
+      });
+    }
+  }
+
+  return warnings;
+}
+
 async function resolveIncludes(nodes, resolverFn) {
   for (const node of nodes) {
     if (node.type === "code" && node.src) {
@@ -3167,7 +3673,9 @@ module.exports = {
   // Validation
   collectAllIds,
   collectInlineRefs,
+  collectCitationDefinitions,
   validateRefs,
+  validateCitations,
   // Low-level helpers for custom renderers (e.g. slide-renderer)
   parseInline,
   renderKatex,