# docs/formal/CLAUDE.md — Authoring Conventions for the Formal Documentation Tier > **Draft** — generated 2026-06-16, starter for Bob's review. > Override any rule below with explicit instruction. --- ## Purpose `docs/formal/` is the press-ready LaTeX documentation set for StarshipOS / StarForth / LithosAnanke. Audience: patent counsel, SSRN reviewers, potential licensees, paying customers, hobbyist hackers with hardware in hand. Nothing goes here until it is ready to be cited. The set is ten publications in three groups, all built from the shared `common/preamble.tex` and `common/starship.bib` and assembled from `scraps/`: | Group | Publications | |-------|--------------| | Research volumes | `vol1-vm-physics`, `vol2-kernel`, `vol3-research` | | Practitioner books | `dev-guide`, `user-guide`, `cookbook` | | Standalone reports | `experiments`, `proofs`, `ssrn`, `patent` | The four standalone reports wrap material that lives elsewhere and may build independently: `experiments` links R-generated figures from `docs/working/experiments/`; `proofs` mirrors the Isabelle/HOL corpus in `proof/`; `ssrn` includes the Math Companion and references the published PDF; `patent` wraps the legal-hold source in `docs/patent/` (no claim language is drafted here — see "What NOT to do"). --- ## Scraps System `docs/formal/scraps/` contains press-ready LaTeX fragments converted from every document in `docs/working/`. Each scrap is a self-contained `.tex` fragment — no `\documentclass`, no `\begin{document}` — ready to `\input{}` into any publication. ### Scrap file naming Mirror the source path under `scraps/`: ``` docs/working/architecture/build-and-tooling/BUILD_OPTIONS.adoc → docs/formal/scraps/architecture/build-and-tooling/BUILD_OPTIONS.tex ``` ### Scrap header (required on every file) ```latex %% SCRAP: architecture/build-and-tooling/BUILD_OPTIONS %% SOURCE: docs/working/architecture/build-and-tooling/BUILD_OPTIONS.adoc %% STATUS: working-triage (CURRENT|WORKING|HISTORICAL|SUPERSEDED|OBSOLETE) %% FITS: dev-guide/ch-build, cookbook/appendix-flags %% EDITORIAL: lifted — prose rewritten to press voice ``` `FITS:` lists candidate `\input{}` locations across the three publications. Use `none` if the scrap is archive/historical material kept for completeness. ### Scrap prose conventions (editorial lift) - Rewrite passive and wordy constructions to active, tight prose. - Strip filler phrases ("it is important to note that", "as mentioned above"). - Convert bullet lists to `\begin{itemize}` or prose where a list is lazy. - Code blocks → `\begin{lstlisting}[language=bash]` or `[language=C]`. - Tables → `\begin{tabular}` with `booktabs` rules. - All claims checked against `ANTI_CLAIMS.md`; hedged language preserved. - `%% TODO(bob):` for anything that requires dictation or verification. - `%% PATENT:` flag on any section touching patent-adjacent claims. ### The practitioner books Scraps feed primarily the three practitioner books, each of which has its own `main.tex` that `\input{}`s scraps in chapter order: | Directory | Title | Audience | |-----------|-------|----------| | `dev-guide/` | StarForth Developer Guide | Contributors, embedders, kernel hackers | | `user-guide/` | StarForth User Guide | End users running StarForth interactively | | `cookbook/` | The StarForth Cookbook | FORTH programmers wanting patterns and recipes | A `FITS:` target may also name a research volume (`vol1`–`vol3`) or a standalone report (`experiments`, `proofs`, `ssrn`, `patent`) when a scrap suits one of those. A scrap can be `\input{}` into more than one publication. | Volume | Scope | |--------|-------| | **Vol I — StarForth VM and Physics Runtime** | FORTH-79 interpreter, physics-driven adaptive runtime (7 feedback loops), Isabelle/HOL formal verification, 90-run experimental results. | | **Vol II — LithosAnanke Kernel and Capsule System** | Bare-metal UEFI kernel (M0–M7), capsule birth protocol, word-level ACL, platform support, L8 Jacquard Mode Selector. | | **Vol III — Research Reference** | SSRN paper transcript, Mathematical Companion, formal claim tables, reproducibility protocol, roadmap. | --- ## Voice and Tone - **Technical precision over enthusiasm.** Never write "cutting-edge," "revolutionary," or "state-of-the-art." Let results speak. - **Third person throughout.** Not "we did X" — "the system does X" or "the implementation uses X." - **Calibrated claims only.** If a claim appears in `ANTI_CLAIMS.md` as out-of-bounds, it does not appear here. See `docs/working/papers/ANTI_CLAIMS.md`. - **Thermodynamic metaphors are modeling tools, not physics claims.** Always introduce the domain of use: "using execution frequency as a proxy for thermal energy, …" See `ONTOLOGY.md` for canonical term definitions. - **Proper nouns are proper.** Never rename: James Law, SSM (Steady-State Machine), Jacquard Selector, Uberkernel, Hades. These are registered terms. --- ## LaTeX Conventions ### Preamble All volumes `\input{../common/preamble}` and `\bibliography{../common/starship}`. Do not duplicate preamble content across volumes. ### Source and TODO markers Every chapter stub must carry at the top: ```latex %% SOURCE: %% TODO(bob): [description of what's needed — dictate or write] ``` Do not remove `%% SOURCE:` comments when a chapter is filled in — they serve as provenance for later reviewers. ### Fonts and formatting - Body text: Computer Modern (default), 11pt, `a4paper`, `twoside`. - Code listings: `listings` package, `basicstyle=\ttfamily\small`. - Math: `amsmath`, `amssymb`. Q48.16 fixed-point notation: `\mathbb{Q}_{48.16}`. - Figures: `\includegraphics[width=\linewidth]{...}`. All figures in `common/figures/` or in the volume directory's `figures/` subfolder. - Tables: `booktabs` package. `\toprule` / `\midrule` / `\bottomrule` — no vertical rules. ### Cross-volume references Use `\label{vol:N:chap:slug}` convention, e.g. `\label{vol1:chap:physics}`. Do not reference across volumes via `\ref` in production builds; link by title instead. ### Citations All citations go through `common/starship.bib`. Use BibTeX keys in format: - `james:2025:ssrn` — published paper - `james:2025:patent` — patent application - `james:2025:proof:loop1` — Isabelle/HOL theory file --- ## Promotion Criteria A section of `docs/working/` is ready for formal inclusion when: 1. The underlying code or claim is confirmed in `.claude/CLAUDE.md` or the running codebase. 2. It has been reviewed against `ANTI_CLAIMS.md` and `ACADEMIC_WORDING_GUIDELINES.md`. 3. There is a `%% SOURCE:` pointer to the working/ document it came from. 4. It compiles without errors and warnings. A stub with `%% TODO(bob):` markers **does satisfy #4** — compilable stubs are the goal of Phase 3, not finished chapters. --- ## What NOT to do - **Never invent results.** If a number isn't in a source doc or the published paper, stub it: `%% TODO(bob): cite figure here`. - **Never invent proofs.** If a theorem isn't in `proof/*.thy`, mark it TODO. - **Never draft patent-adjacent text** (independent/dependent claims, claim mapping) without Bob's explicit dictation. Leave those sections as `%% TODO(bob): PATENT — do not draft`. - **Never copy-paste from `COMPUTATIONAL_PHYSICS_FRAMEWORK.md`.** That doc is HISTORICAL and contains out-of-scope claims that contradict `ANTI_CLAIMS.md`.