# Lab Journal

The HAHACS invention log for the `pwr-hybrid-3-demo` preliminary
example. Each dated session gets an entry. The goal: a reader in 2030
should be able to rebuild the thesis work from this journal alone.

## Structure

```
journal/
  preamble.tex         shared LaTeX setup (fonts, listings, callouts, macros)
  journal.tex          top-level aggregator (builds all entries into one PDF)
  entries/             dated session entries, one file per session
    YYYY-MM-DD-{topic-slug}.tex
  figures/             journal-specific figures (referenced from entries)
  README.md            this file
```

## Conventions

### Filename

`entries/YYYY-MM-DD-{topic-slug}.tex`. One file per session. If a day has multiple distinct sessions, use time-of-day in the slug (e.g., `2026-04-20-morning-predicates.tex` and `2026-04-20-evening-mega-session.tex`).

### Entry skeleton

```tex
\session{2026-04-17}{duration}{one-line summary}

\section{Session: ... (YYYY-MM-DD)}
\label{sec:YYYYMMDD}

\subsection*{Goal}
What I set out to do and why.

\subsection*{What landed}
...

\subsection*{Key decisions}
...

\subsection*{Dead ends}
...

\subsection*{Derivations}
...

\subsection*{Results}
...

\subsection*{Limitations recorded}
...

\subsection*{Open at close}
...
```

Entries compile standalone (each starts with `\input{../preamble.tex}` wrapped in a conditional so it only pulls preamble when not already loaded by `journal.tex`), or together via `journal.tex`.

### Two entry styles

- **A-style (deep / invention-log)**: full derivations, code commentary, dead-ends, embedded figures, terminal output where useful. Used for retroactive entries and sessions that land meaningful artifacts.
- **B-style (narrative + pointers)**: end-of-session notes. Uses `\apass{...}` callouts to flag spots that need a later A-pass.

### Callout boxes

From `preamble.tex`:

| Environment | Use |
|---|---|
| `derivation` | Math derivations |
| `decision` | Design choices with rationale + alternatives |
| `deadend` | Paths that didn't work |
| `limitation` | Soundness gaps, known-approximate behavior |

Plus the inline `\apass{text}` marker for A-pass TODOs.

### Code inclusion

- `\juliafile[options]{path/to/file.jl}` — includes a Julia source file as a numbered listing.
- `\matlabfile[...]{...}` — for MATLAB sources.
- Or inline with `lstlisting` environment and `language=Julia` for snippets.

Always include the path as the listing caption so readers can find the file.

### Figures

Figures live in `../docs/figures/` (shared with the thesis) or `figures/` (journal-only). The preamble sets `\graphicspath` to check both.

Always include:
1. A descriptive caption (what's on axes, what's being shown).
2. A discussion in the surrounding prose — *what the figure proves or illustrates*. Figures without discussion are noise.

### Terminal output

For a numerical result or an error that drove a decision, include the actual terminal text in a `lstlisting` block with `style=terminal`:

```tex
\begin{lstlisting}[style=terminal]
TMJets: 10583 reach-sets
T_c envelope: [274.45, 295.0] C
FAILED: AssertionError: radius must be nonnegative
\end{lstlisting}
```

Don't include full logs — only the lines that changed what you did next.

## Build

```bash
cd journal
latexmk -pdf journal.tex            # whole journal as one PDF
latexmk -pdf entries/2026-04-17-controllers-linear-reach.tex  # one entry
```

Requires TeX Live with `tcolorbox`, `listings`, `inconsolata`, `siunitx`, `cleveref`, `hyperref`, `fancyhdr`. All in the standard distribution.

## Not a replacement for

- `claude_memory/` — short AI-context notes, Markdown, different audience.
- `reachability/WALKTHROUGH.md` — standalone doc summarizing current state of reach analysis.
- Git commit messages — per-commit rationale for code changes.

The journal is the *chronological narrative* of the work. The others are snapshots, summaries, or pointers. They're all legitimate; they do different things.