1 files changed, 60 insertions, 0 deletions
diff --git a/claude-rules/org-tables.md b/claude-rules/org-tables.md
new file mode 100644
index 0000000..1b70085
--- /dev/null
+++ b/claude-rules/org-tables.md
@@ -0,0 +1,60 @@
+# Org Table Standard
+
+Applies to: `**/*.org`
+
+Every org table in project docs follows one shape. Wide tables overflow the
+page in exported PDF/docx and run off the edge of the org buffer; this is the
+standing fix. Promoted from the work project's local convention 2026-06-11.
+
+## Three requirements
+
+1. **Max width 120 columns — measured at render width.** The whole table
+   line, leading/trailing pipes included, is ≤120 characters as the table
+   *renders* (exported output, or the org buffer). An org link counts as its
+   visible label, not its full `[[target][label]]` source, because export and
+   the live buffer show only the label. This is the one place source width
+   and render width diverge; **never split a link** to chase a source-width
+   number — the render is what overflows the page. Non-link cells have no
+   source/render gap.
+2. **Multi-line cells.** When a cell's text would push the row past 120, wrap
+   it onto continuation rows: repeat the row with the overflow column's text
+   continued and the other columns left blank, as many continuation rows as
+   the content needs. Never truncate content to hit the width; wrap it.
+3. **A rule under the header and under every logical row.** Put a horizontal
+   rule (`|---+---|`) after the header and after every data row, closing rule
+   included. Each logical row then reads as a bordered block, and the rules
+   are what mark where a logical row (with its continuation lines) ends.
+
+Example — the logical row "arch-00" wrapped across two physical rows, rules
+between every row:
+
+    | Document | Doc Status | Notes                            |
+    |----------+------------+----------------------------------|
+    | arch-00  | Current    | Source-of-truth spec; references |
+    |          |            | arch-NN as authority             |
+    |----------+------------+----------------------------------|
+    | arch-01  | Current    | Linear introduction for          |
+    |          |            | first-time readers               |
+    |----------+------------+----------------------------------|
+
+## How to apply
+
+When authoring or editing any table, produce this shape from the start. When
+a table already violates it, reformat in place — preserve every cell's
+content and any links verbatim, only change the layout.
+
+Tooling (in every project's `.ai/scripts/` via the template sync):
+
+- `wrap-org-table.el` reflows tables to the standard mechanically:
+  `emacs --batch -q -l .ai/scripts/wrap-org-table.el [--width=120] FILE.org`.
+  It wraps over-budget cells onto continuation rows, adds the rules, measures
+  links at label width, and never splits a token or a link. Re-running on a
+  conformant table is a no-op.
+- `lint-org.el` flags violating tables as judgment items (checker
+  `org-table-standard`) during its sweep — width overruns, missing rules, or
+  both — and names the helper in the message.
+
+The helper can't fix a table whose single narrowest-possible columns still
+exceed the budget (some token or link label is just too wide). That table
+needs restructuring — merge or drop columns, shorten labels — which is a
+judgment call: the lint item stays until a human reshapes it.