Add the FEBio Feature Manual as a third "Features" tab

Absorbs the standalone febiosoftware/febio-feature-manual repo into this
site as a third navigation tab, alongside Theory and Studio.

The feature manual is itself a generated site, not hand-authored Markdown,
so rather than copying static output its source is vendored and its
generator ported into this repo's pipeline:

- source/feature-manual/ - febio_features.json (FEBio's feature database,
  exported from FEBio Studio) plus the 409 hand-authored per-feature
  description fragments in meta/.
- tools/features2md.py - a port of the upstream build.py's content
  generation. Two deliberate differences: it does not write its own
  mkdocs.yml (build.py owns the site nav for all three manuals, so it
  writes a nested nav tree to its stats sidecar instead), and it creates
  output directories with exist_ok=True (upstream gitignores its generated
  docs/modules/*.md, leaving that directory absent in a fresh clone and
  crashing upstream's own build).

build.py's MANUALS entries now carry a "kind" that selects the converter:
"lyx" runs lyx2md.py as before, "features" runs features2md.py. "kind"
also gates the figure-fetch step, since the feature manual's figures are
vendored rather than fetched from upstream. Nav emission gained a
recursive write_nav() for the feature manual's freely nested tree, with
JSON-quoted titles so feature names carrying YAML-significant characters
cannot corrupt mkdocs.yml.

The upstream manual's own top-level tabs (Modules / Features / Output /
febcode) become expandable sidebar sections under the one Features tab.
Its home page is dropped in favor of a Preface matching the Theory and
Studio tabs.

Feature pages are written flat into docs/features/features/ with figs/
alongside them, exactly as upstream laid them out. That is why the path
doubles up. The meta/ fragments contain 44 relative sibling links and 25
figure references that only resolve under that layout, so regrouping it
would break authored prose rather than converter code; noted in both
README.md and CLAUDE.md.

Totals: 660 feature pages across 32 categories, 7 module pages, 262 plot
and 419 log variables. 264 features still have no description fragment
(inherited from upstream, listed in tools/_stats_features.json under
needs_review.pages_without_description).

Verified: build.py exits 0; mkdocs build --strict exits 0 with zero
WARNINGs, so every one of the new pages, cross-page links, and figures
resolves. mkdocs.yml's diff is additions only, with zero deletions, and
nothing under docs/theory/ or docs/studio/ changed - the Theory and
Studio nav is byte-identical.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U96z31ZadrrQ3YtU7br22M

Author: Wesley-Jakob-Gilbert

.gitignore

@@ -1,3 +1,7 @@
 site/
 __pycache__/
 *.pyc
+
+# Local clone of the upstream feature-manual repo. Its source is vendored
+# into source/feature-manual/, so the clone itself is not part of this repo.
+febio-feature-manual/

CLAUDE.md

@@ -4,39 +4,50 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## What this repo is
 
-A MkDocs site that converts FEBio's LyX-authored manuals to Markdown, mirroring the conventions of the
-sibling `febio-feature-manual` repo (Material for MkDocs theme, indigo palette, `pymdownx.arithmatex` +
-MathJax for equations, footnote-based citations). The site has two `navigation.tabs`, each a separately
-converted manual, orchestrated by `build.py`'s `MANUALS` list:
-
-- **Theory** (`source/FEBio_Theory_Manual.lyx` → `docs/theory/`) — all 9 chapters (1–8 plus Appendix A)
-  are converted.
-- **Studio** (`source/FEBioStudio_User_Manual.lyx` → `docs/studio/`) — all 22 chapters (1–20 plus
-  Appendices A and B) are converted.
-
-`source/` is vendored/checked-in for both manuals, so the repo builds standalone from a bare clone.
-
-**`docs/theory/` and `docs/studio/` (except their `index.md` files) are generated output, not
-hand-authored content.** They're regenerated from each manual's `.lyx` source by `tools/lyx2md.py` on
-every build. Do not hand-edit generated chapter/section files expecting them to persist — fix the
-converter (`tools/lyx2md.py`) instead, or edit the relevant `source/*.lyx` file if the manual content
-itself is wrong. `docs/index.md` (site-root landing page, not in `nav:`), `docs/theory/index.md` and
-`docs/studio/index.md` (each manual's Preface), and `docs/js/mathjax_config.js` are hand-authored
-exceptions.
+A MkDocs site that generates all of FEBio's manuals into one site (Material for MkDocs theme, indigo
+palette, `pymdownx.arithmatex` + MathJax for equations, footnote-based citations). The site has three
+`navigation.tabs`, each a separately generated manual, orchestrated by `build.py`'s `MANUALS` list. Each
+entry has a `"kind"` selecting its converter:
+
+- **Theory** (`kind: "lyx"`, `source/FEBio_Theory_Manual.lyx` → `docs/theory/`) — all 9 chapters (1–8
+  plus Appendix A) are converted.
+- **Studio** (`kind: "lyx"`, `source/FEBioStudio_User_Manual.lyx` → `docs/studio/`) — all 22 chapters
+  (1–20 plus Appendices A and B) are converted.
+- **Features** (`kind: "features"`, `source/feature-manual/` → `docs/features/`) — the FEBio Feature
+  Manual, absorbed from the standalone `febio-feature-manual` repo. Generated by `tools/features2md.py`
+  (not `lyx2md.py`) from `febio_features.json` plus per-feature description fragments in `meta/`.
+  660 feature pages, 7 module pages, plot/log variable tables, and the hand-authored febcode page.
+
+`source/` is vendored/checked-in for all three manuals, so the repo builds standalone from a bare clone.
+
+**`docs/theory/`, `docs/studio/`, and `docs/features/` are generated output, not hand-authored
+content.** They're regenerated on every build. Do not hand-edit generated pages expecting them to
+persist — fix the converter instead, or edit the relevant file under `source/` if the manual content
+itself is wrong. For a missing/incorrect *feature description* specifically, the file to edit is
+`source/feature-manual/meta/<page-name>.md` — it is spliced verbatim into that page.
+
+Hand-authored exceptions that survive a rebuild: `docs/index.md` (site-root landing page, not in `nav:`),
+each manual's Preface (`docs/theory/index.md`, `docs/studio/index.md`, `docs/features/index.md`),
+`docs/features/febcode.md` + `febcode.png`, `docs/features/features/figs/`, and
+`docs/js/mathjax_config.js`.
+
+A local clone of the upstream `febio-feature-manual` repo may sit at `febio-feature-manual/` inside the
+working tree; it is gitignored and is *not* the build's source — `source/feature-manual/` is.
 
 ## Commands
 
 ```
 pip install mkdocs mkdocs-material   # prerequisites
 
-python3 build.py                     # runs tools/lyx2md.py once per manual, (re)writes docs/**/*.md and mkdocs.yml
-python3 build.py -v                  # verbose (streams lyx2md.py's own stdout instead of buffering it)
+python3 build.py                     # runs each manual's converter, (re)writes docs/**/*.md and mkdocs.yml
+python3 build.py -v                  # verbose (streams each converter's own stdout instead of buffering it)
 mkdocs serve                         # preview at http://127.0.0.1:8000
 mkdocs build --strict                # validate the full build; must exit 0 with zero WARNINGs
 mkdocs gh-deploy --force             # manually publish site/ to the gh-pages branch (needs push access)
 
-# tools/lyx2md.py is generic across manuals via CLI flags (build.py passes these per MANUALS entry):
+# Both converters are generic via CLI flags (build.py passes these per MANUALS entry):
 python3 tools/lyx2md.py --lyx PATH --bib PATH --docs-root DIR --nav-root PREFIX --stats-out PATH --chapters "1,2|all"
+python3 tools/features2md.py --features-json PATH --meta-dir DIR --docs-root DIR --nav-root PREFIX --stats-out PATH
 ```
 
 There is no test suite. Validation is: `python3 build.py && mkdocs build --strict` exits 0 with no
@@ -47,10 +58,13 @@ below), plus a leftover-artifact grep across both manuals' output:
 grep -rn '\begin_\|\end_inset\|\begin_inset\|SpecialChar\|\lang ' docs/   # must be zero matches
 ```
 
-Each manual's stats sidecar (`tools/_stats.json` for Theory, `tools/_stats_studio.json` for Studio,
-written by `lyx2md.py`) reports per-chapter/per-section formula, citation, and figure counts —
-reconcile these against the source when validating a chapter (see `CONVERSION_NOTES.md` /
-`CONVERSION_NOTES_STUDIO.md` for the established methodology and known small discrepancies).
+Each manual's stats sidecar reports what it produced. `tools/_stats.json` (Theory) and
+`tools/_stats_studio.json` (Studio), written by `lyx2md.py`, report per-chapter/per-section formula,
+citation, and figure counts — reconcile these against the source when validating a chapter (see
+`CONVERSION_NOTES.md` / `CONVERSION_NOTES_STUDIO.md` for the established methodology and known small
+discrepancies). `tools/_stats_features.json`, written by `features2md.py`, instead holds the nav tree,
+totals, and `needs_review.pages_without_description` — the list of features still lacking a `meta/`
+fragment (264 of 660 as of the port; not a build failure, just unwritten prose).
 
 CI (`.github/workflows/deploy.yml`) runs `python3 build.py` then `mkdocs build --strict` on every push
 to `main`, then `mkdocs gh-deploy --force`. **The live site is served from the `gh-pages` branch, not
@@ -61,12 +75,23 @@ triggers the workflow that does.
 
 ### Pipeline
 
-For each manual in `build.py`'s `MANUALS` list: `source/<manual>.lyx` → `tools/lyx2md.py` (invoked as a
-separate subprocess per manual, with `--lyx`/`--bib`/`--docs-root`/`--nav-root`/`--stats-out`/`--chapters`)
-→ `docs/<nav_root>/chapter<N>/<N>.M-slug.md` + that manual's stats JSON → `build.py` reads all manuals'
-stats files and writes one `mkdocs.yml` whose `nav:` has one top-level tab per manual → `mkdocs build`.
-Running each manual as a separate subprocess means `lyx2md.py`'s module-level globals/label-registries
-never cross-contaminate between manuals — no in-process reset logic is needed.
+For each manual in `build.py`'s `MANUALS` list, `build.py` dispatches on `"kind"` to run that manual's
+converter as a separate subprocess, then reads back its stats JSON. Once all manuals are converted it
+writes one `mkdocs.yml` whose `nav:` has one top-level tab per manual → `mkdocs build`. Running each
+manual as a separate subprocess means `lyx2md.py`'s module-level globals/label-registries never
+cross-contaminate between manuals — no in-process reset logic is needed.
+
+- `kind: "lyx"` → `source/<manual>.lyx` → `tools/lyx2md.py` (`--lyx`/`--bib`/`--docs-root`/`--nav-root`/
+  `--stats-out`/`--chapters`) → `docs/<nav_root>/chapter<N>/<N>.M-slug.md` + stats JSON whose `chapters`
+  key drives a fixed chapter → section nav shape.
+- `kind: "features"` → `source/feature-manual/` → `tools/features2md.py` (`--features-json`/`--meta-dir`/
+  `--docs-root`/`--nav-root`/`--stats-out`) → `docs/features/{features,modules}/*.md` +
+  `plotvars.md`/`logvars.md`, plus a stats JSON whose `nav` key is a *freely nested* tree that
+  `build.py`'s `write_nav()` emits recursively. Nav titles are `json.dumps`-quoted so feature names
+  carrying YAML-significant characters can't corrupt `mkdocs.yml`.
+
+`"kind"` also gates the figure-fetching step (step 4): only `"lyx"` manuals fetch missing figures from
+upstream, since the Feature Manual's figures are vendored.
 
 `tools/lyx2md.py` is a **stdlib-only, deterministic** parser for LyX's plain-text format — no LyX,
 Pandoc, or other external tool involved, and the parsing/rendering logic itself is identical regardless
@@ -123,6 +148,13 @@ copies).
 - `mkdocs.yml` is generated by `build.py` — don't hand-edit it; change the write logic in `build.py`
   instead (theme config and the `MANUALS` list live inline as `f.write(...)` calls / a module-level
   list at the top of the file).
+- **Don't rearrange the Feature Manual's output layout.** Its pages are written *flat* into
+  `docs/features/features/` with `figs/` alongside them, exactly as the upstream repo laid them out,
+  which is why the path doubles up (`features/features/...`) and why the "Features" nav section sits
+  inside the "Features" tab. The `meta/` fragments contain 44 relative sibling links
+  (`[x](other_page.md)`) and 25 figure references (`figs/Foo.png`) that only resolve under that layout;
+  flattening or regrouping it would break them, and fixing that would mean rewriting authored prose
+  rather than converter code. (`mkdocs build --strict` does catch it, at least.)
 - Merged table cells (colspan/rowspan) can't be represented in plain Markdown tables; `render_tabular()`
   flags these for manual review rather than guessing — check `CONVERSION_NOTES.md`/`needs_review` before
   assuming a table rendered correctly (occurs in Section 4.1's element-property tables).