formatting

Author: pavel-kirienko

CLAUDE.md

@@ -0,0 +1,66 @@
+# Cyphal specification — notes for AI agents
+
+Read `README.md` first; it contains the authoritative editing rules, label conventions,
+source-formatting style, and build instructions. This file captures the project-specific
+context that is easy to miss on a cold read.
+
+## Key external sources of truth
+
+These live outside this repository but are the authoritative references for anything
+the spec says about the session layer:
+
+- <https://github.com/OpenCyphal-Garage/cy> -- the C reference implementation, design notes, formal models and proofs.
+- <https://github.com/OpenCyphal/libcanard> -- the Cyphal/CAN transport layer C reference implementation.
+- <https://github.com/OpenCyphal/libudpard> -- the Cyphal/UDP transport layer C reference implementation.
+
+When working on the specification, ensure that these repositories are cloned in the outer directory (`../`);
+if not, clone them and check out the main branch.
+
+Numerical constants (moduli, tag widths, header sizes, etc.) and test vectors in the spec are generated from these
+sources and must reproduce bit-for-bit.
+When adding or revising a test vector, regenerate it from the reference C implementation.
+
+## Repository layout
+
+```
+./
+├── README.md              # authoritative editing guide
+├── CLAUDE.md              # this file
+├── compile.sh             # builds the PDF
+├── clean.sh               # removes build artifacts
+└── specification/
+    ├── Cyphal_Specification.tex   # root document; \input's every chapter
+    ├── cyphaldoc.cls              # custom document class; defines remark, CyphalSimpleTable, etc.
+    ├── introduction/introduction.tex
+    ├── session/                   # main focus of v1.1; composed of several chapter-local files
+    ├── transport/
+    └── appendices/                # proofs, TLA+, formal models, references, ...
+```
+
+A chapter directory contains one main `.tex` file that `\input`s its subordinate files.
+
+## Building
+
+```sh
+./compile.sh
+```
+
+Ensure it builds cleanly and the PDF looks sensible before declaring the work done.
+
+## Style rules that are easy to forget
+
+Most of the house style lives in `README.md`. A few points warrant extra emphasis:
+
+- **Be brief.** v1.0 was too verbose. The spec must be tight: push rationale into `remark` boxes,
+  avoid restating transport-layer definitions, and cross-reference rather than repeat.
+- **No API description.** Describe observable wire behavior and state transitions only.
+  Words like "future" are allowed as conceptual handles when describing asynchronous
+  state transitions, but they are not API promises.
+- **Lowercase shall / should / may.** The document uses lowercase RFC 2119 keywords in prose.
+- **ASCII only inside `minted` bodies.** The `minted` listings use `inputenc` under `pdflatex`,
+  which rejects Unicode characters like `∪`, `≤`, `→`.
+  Use ASCII substitutes (`union`, `<=`, `->`) or TeX math in surrounding prose instead.
+
+Heavy rationale, the CRDT proof, the TLA$^+$ listing, the rapidhash reference
+implementation, the eviction solver, and the gossip analytical models all live under
+`specification/appendices/` and are referenced from the main body.

README.md

@@ -74,6 +74,15 @@ For example, one could refer to a figure contained inside the chapter "Chapter"
 The above rules are crucial to follow to keep cross-references usable.
 Without strict conventions in place, they quickly become unmanageable.
 
+To caption a `CyphalSimpleTable`, put the label inside the caption argument, NOT inside the table body:
+
+```tex
+\begin{CyphalSimpleTable}[wide]{Caption of the table\label{table:chapter_my_table}}{|l l X|}
+    Column A & Column B & Column C \\
+    ...
+\end{CyphalSimpleTable}
+```
+
 ### Source formatting
 
 - One level of nesting shall be indented with 4 spaces. Tabs shall not be used anywhere in the source.

specification/transport/can/can.tex

@@ -185,8 +185,10 @@ \subsection{CAN ID field}
     \caption{CAN ID bit layout}\label{fig:transport_can_id_structure}
 \end{figure}
 
-\begin{CyphalSimpleTable}[wide]{CAN ID bit fields for 16-bit v1.1 message transfers}{|l l l X|}
-    \label{table:transport_can_id_fields_message_transfer_v11}
+\begin{CyphalSimpleTable}[wide]{%
+    CAN ID bit fields for 16-bit v1.1 message transfers%
+    \label{table:transport_can_id_fields_message_transfer_v11}%
+}{|l l l X|}
     Field               & Width & Valid values  & Description \\
 
     Transfer priority   & 3     & $[0, 7]$ (any)    & Section~\ref{sec:transport_transfer_priority}. \\
@@ -204,8 +206,10 @@ \subsection{CAN ID field}
     Source node-ID      & 7     & $[0, 127]$ (any)  & Node-ID of the origin. \\
 \end{CyphalSimpleTable}
 
-\begin{CyphalSimpleTable}[wide]{CAN ID bit fields for 13-bit v1.0 message transfers}{|l l l X|}
-    \label{table:transport_can_id_fields_message_transfer_v10}
+\begin{CyphalSimpleTable}[wide]{%
+    CAN ID bit fields for 13-bit v1.0 message transfers%
+    \label{table:transport_can_id_fields_message_transfer_v10}%
+}{|l l l X|}
     Field               & Width & Valid values  & Description \\
 
     Transfer priority   & 3     & $[0, 7]$ (any)    & Section~\ref{sec:transport_transfer_priority}. \\
@@ -230,8 +234,10 @@ \subsection{CAN ID field}
                                                       section~\ref{sec:transport_can_source_node_pseudo_id}. \\
 \end{CyphalSimpleTable}
 
-\begin{CyphalSimpleTable}[wide]{CAN ID bit fields for service transfers}{|l l l X|}
-    \label{table:transport_can_id_fields_service_transfer}
+\begin{CyphalSimpleTable}[wide]{%
+    CAN ID bit fields for service transfers%
+    \label{table:transport_can_id_fields_service_transfer}%
+}{|l l l X|}
     Field               & Width & Valid values  & Description \\
 
     Transfer priority   & 3     & $[0, 7]$ (any)    & Section~\ref{sec:transport_transfer_priority}. \\
@@ -289,8 +295,10 @@ \subsubsection{Session header reconstruction}\label{sec:transport_can_v10_header
 default values for a best-effort message. The resulting message shall be otherwise indistinguishable from
 an equivalent message originated by a v1.1 node on the same pinned topic.
 
-\begin{CyphalSimpleTable}{Session header field values for reconstructed 13-bit message transfers}{|l X|}
-    \label{table:transport_can_v10_header_reconstruction}
+\begin{CyphalSimpleTable}{%
+    Session header field values for reconstructed 13-bit message transfers%
+    \label{table:transport_can_v10_header_reconstruction}%
+}{|l X|}
     Field               & Value \\
 
     Header type         & Message, best-effort. \\