forge Documentation Site Implementation Plan¶

For agentic workers: REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Set up a Doxide + MkDocs Material documentation site for forge that replaces the old hdoc-based docs.

Architecture: Doxide parses C++ source via Tree-sitter and outputs Markdown into docs/api/. MkDocs with the Material theme builds a static site from hand-authored pages (getting-started/, guides/) plus the Doxide-generated API reference. A custom hero landing page uses Material's override system.

Tech Stack: Doxide, MkDocs, Material for MkDocs, Python (pip)

Spec: docs/superpowers/specs/2026-03-16-documentation-site-design.md

Chunk 1: Scaffolding and Configuration¶

Task 1: Install dependencies and verify toolchain¶

Files: - Create: docs/requirements.txt

[ ] Step 1: Install Doxide via Homebrew

Run: brew install doxide Expected: Doxide binary available at doxide --version

[ ] Step 2: Create Python requirements file

Create docs/requirements.txt:

mkdocs>=1.6
mkdocs-material>=9.5

[ ] Step 3: Install Python dependencies

Run: pip install -r docs/requirements.txt Expected: mkdocs --version outputs version >= 1.6

[ ] Step 4: Commit

git add docs/requirements.txt
git commit -m "docs: add Python requirements for MkDocs Material"

Task 2: Create Doxide configuration¶

Files: - Create: doxide.yaml

[ ] Step 1: Create doxide.yaml at repo root

title: forge
description: Fast, Optimized Reconstruction via Gridding Engine
output: docs/api

files:
  - "forge/**/*.hpp"
  - "forge/**/*.h"
  - "forge/**/*.cpp"

exclude:
  - "forge/Tests/"
  - "forge/Tutorials/"
  - "forge/Microbenchmarks/"
  - "Support/"

[ ] Step 2: Run Doxide to verify it parses the codebase

Run: doxide build Expected: Markdown files generated in docs/api/. Check that docs/api/index.md exists and contains namespace/class listings.

[ ] Step 3: Verify Doxide output looks reasonable

Run: ls docs/api/ Expected: Multiple .md files corresponding to forge's namespaces and classes.

If the files or exclude glob syntax doesn't work with the installed Doxide version, adjust the patterns. Doxide expects paths relative to the config file location.

[ ] Step 4: Commit

git add doxide.yaml
git commit -m "docs: add Doxide configuration for C++ API reference generation"

Task 3: Create MkDocs configuration¶

Files: - Create: mkdocs.yml

[ ] Step 1: Create mkdocs.yml at repo root

site_name: forge
site_url: https://mechneurolab.github.io/forge/
repo_name: mechneurolab/forge
repo_url: https://github.com/mechneurolab/forge

theme:
  name: material
  custom_dir: docs/overrides
  logo: assets/logo.svg
  favicon: assets/logo.svg
  icon:
    repo: fontawesome/brands/square-github
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.top
    - content.code.copy
    - content.code.annotate
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: fontawesome/solid/sun
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: fontawesome/solid/moon
        name: Switch to light mode

nav:
  - Home: index.md
  - Getting Started:
    - Installation: getting-started/installation.md
    - Building from Source: getting-started/building.md
    - Your First Reconstruction: getting-started/first-reconstruction.md
  - Guides:
    - Operators & Solvers: guides/operators-and-solvers.md
    - forge Types (forgeCol/forgeMat): guides/forge-types.md
    - Metal GPU Backend: guides/metal-backend.md
    - forgeview TUI: guides/forgeview.md
    - MPI Distributed Reconstruction: guides/mpi.md
  - API Reference: api/

markdown_extensions:
  - toc:
      permalink: true
  - admonition
  - pymdownx.details
  - pymdownx.highlight
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.inlinehilite
  - attr_list
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

extra_css:
  - stylesheets/extra.css

plugins:
  - search

[ ] Step 2: Create required directory structure

Run:

mkdir -p docs/overrides docs/stylesheets docs/assets docs/getting-started docs/guides

[ ] Step 3: Create placeholder files so MkDocs can build

Create minimal placeholder docs/index.md:

---
hide:
  - navigation
  - toc
---

# forge

Placeholder — hero page coming soon.

Create placeholder files for every page in the nav (one line each — # Page Title):

docs/getting-started/installation.md
docs/getting-started/building.md
docs/getting-started/first-reconstruction.md
docs/guides/operators-and-solvers.md
docs/guides/forge-types.md
docs/guides/metal-backend.md
docs/guides/forgeview.md
docs/guides/mpi.md

Create a fallback docs/api/index.md (will be overwritten by Doxide but ensures MkDocs builds even without running Doxide first):

# API Reference

Run `doxide build` to generate API documentation from the C++ source.

Create empty docs/stylesheets/extra.css (will be filled in Task 5).

Create empty docs/overrides/.gitkeep (overrides dir needs to exist for Material).

[ ] Step 4: Run doxide build && mkdocs build to verify the full pipeline

Run: doxide build && mkdocs build Expected: Site built successfully in site/ directory with no errors.

[ ] Step 5: Run mkdocs serve and verify in browser

Run: mkdocs serve Expected: Dev server at http://127.0.0.1:8000/. Verify: - Four tabs visible: Home, Getting Started, Guides, API Reference - Dark/light toggle works - API Reference tab shows Doxide-generated content - Stop the server with Ctrl+C

[ ] Step 6: Commit

git add mkdocs.yml docs/index.md docs/getting-started/ docs/guides/ docs/stylesheets/extra.css docs/overrides/.gitkeep
git add -f docs/api/index.md
git commit -m "docs: add MkDocs Material configuration with placeholder pages"

Task 4: Copy logo and update .gitignore¶

Files: - Create: docs/assets/logo.svg - Modify: .gitignore

[ ] Step 1: Copy the logo SVG from forge-studio

Run: cp /Users/acerjanic/Developer/forge-studio/resources/logo.svg docs/assets/logo.svg

[ ] Step 2: Add .gitignore entries

Add to .gitignore:

# MkDocs build output
site/

Note: docs/api/ is already in .gitignore (line 46). The hand-authored fallback docs/api/index.md was already force-added in Task 3.

[ ] Step 3: Commit

git add docs/assets/logo.svg .gitignore
git add -f docs/api/index.md
git commit -m "docs: add forge logo and gitignore entries for build artifacts"

Task 5: Custom color scheme CSS¶

Files: - Modify: docs/stylesheets/extra.css

[ ] Step 1: Write the custom CSS

Write docs/stylesheets/extra.css:

/* forge color overrides — derived from forge-studio logo */
/* Blue #3B82F6 primary, Gold #D4A843 accent */

/* Light mode */
[data-md-color-scheme="default"] {
  --md-primary-fg-color: #3B82F6;
  --md-primary-fg-color--light: #60a5fa;
  --md-primary-fg-color--dark: #2563eb;
  --md-accent-fg-color: #D4A843;
  --md-accent-fg-color--transparent: rgba(212, 168, 67, 0.1);
}

/* Dark mode */
[data-md-color-scheme="slate"] {
  --md-primary-fg-color: #60a5fa;
  --md-primary-fg-color--light: #93c5fd;
  --md-primary-fg-color--dark: #3B82F6;
  --md-accent-fg-color: #e8c05a;
  --md-accent-fg-color--transparent: rgba(232, 192, 90, 0.1);
}

/* Gradient accent bar under the header */
.md-header {
  border-bottom: 3px solid transparent;
  border-image: linear-gradient(90deg, #3B82F6, #D4A843) 1;
}

[data-md-color-scheme="slate"] .md-header {
  border-image: linear-gradient(90deg, #60a5fa, #e8c05a) 1;
}

[ ] Step 2: Rebuild and verify colors

Run: mkdocs serve Expected: Header uses blue, gradient bar visible under the header, links are blue. Toggle dark mode — colors shift to lighter blue, gold accent brightens. Stop with Ctrl+C.

[ ] Step 3: Commit

git add docs/stylesheets/extra.css
git commit -m "docs: add custom color scheme with forge-studio blue/gold palette"

Chunk 2: Hero Landing Page¶

Task 6: Create custom hero landing page¶

Files: - Create: docs/overrides/home.html - Modify: docs/index.md

[ ] Step 1: Update docs/index.md with hero front-matter

---
template: home.html
hide:
  - navigation
  - toc
---

No body content — the template handles everything.

[ ] Step 2: Create docs/overrides/home.html

This extends Material's main.html and overrides the content block:

{% extends "main.html" %}

{% block content %}
<style>
  /* Hide the default page title */
  .md-content__inner h1 { display: none; }

  .forge-hero {
    text-align: center;
    padding: 4rem 1rem 2rem;
  }

  .forge-hero__logo {
    width: 96px;
    height: 96px;
    margin-bottom: 1.5rem;
  }

  .forge-hero__title {
    font-size: 2.5rem;
    font-weight: 700;
    margin: 0 0 0.5rem;
    color: var(--md-default-fg-color);
  }

  .forge-hero__tagline {
    font-size: 1.2rem;
    color: var(--md-default-fg-color--light);
    margin: 0 0 2rem;
  }

  .forge-hero__actions {
    display: flex;
    gap: 1rem;
    justify-content: center;
    flex-wrap: wrap;
    margin-bottom: 3rem;
  }

  .forge-hero__actions a {
    padding: 0.75rem 1.5rem;
    border-radius: 6px;
    text-decoration: none;
    font-weight: 600;
    font-size: 0.95rem;
  }

  .forge-hero__actions a.primary {
    background: var(--md-primary-fg-color);
    color: #fff;
  }

  .forge-hero__actions a.secondary {
    border: 2px solid var(--md-primary-fg-color);
    color: var(--md-primary-fg-color);
  }

  .forge-features {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
    gap: 1.5rem;
    max-width: 960px;
    margin: 0 auto 3rem;
    padding: 0 1rem;
  }

  .forge-feature {
    padding: 1.5rem;
    border-radius: 8px;
    background: var(--md-code-bg-color);
  }

  .forge-feature h3 {
    margin: 0 0 0.5rem;
    font-size: 1.05rem;
    color: var(--md-default-fg-color);
  }

  .forge-feature p {
    margin: 0;
    font-size: 0.9rem;
    color: var(--md-default-fg-color--light);
  }

  .forge-install {
    max-width: 640px;
    margin: 0 auto 2rem;
    padding: 0 1rem;
  }

  .forge-install h2 {
    text-align: center;
    font-size: 1.3rem;
    margin-bottom: 1rem;
  }

  .forge-install pre {
    border-radius: 8px;
  }
</style>

<section class="forge-hero">
  <img src="assets/logo.svg" alt="forge logo" class="forge-hero__logo">
  <h1 class="forge-hero__title">forge</h1>
  <p class="forge-hero__tagline">Fast, Optimized Reconstruction via Gridding Engine</p>

  <div class="forge-hero__actions">
    <a href="getting-started/installation/" class="primary">Get Started</a>
    <a href="https://github.com/mechneurolab/forge" class="secondary">GitHub</a>
  </div>
</section>

<section class="forge-features">
  <div class="forge-feature">
    <h3>NUFFT Gridding</h3>
    <p>Kaiser-Bessel gridding with look-up table acceleration. CPU and GPU backends.</p>
  </div>
  <div class="forge-feature">
    <h3>Metal & CUDA GPU</h3>
    <p>Full GPU pipeline on Apple Silicon via Metal. NVIDIA acceleration via OpenACC/CUDA.</p>
  </div>
  <div class="forge-feature">
    <h3>SENSE / pcSENSE</h3>
    <p>Multi-coil sensitivity encoding with per-shot phase correction and time segmentation.</p>
  </div>
  <div class="forge-feature">
    <h3>forgeview TUI</h3>
    <p>Live reconstruction monitor with progress bars, convergence sparklines, and image preview.</p>
  </div>
</section>

<section class="forge-install">
  <h2>Quick Start</h2>

  <div class="highlight">
    <pre><code>cmake -B build -DMETAL_COMPUTE=ON
cmake --build build -j$(sysctl -n hw.logicalcpu)

forgeSense -i data.h5 -o output/ -F NUFFT -n 20 2>&1 | forgeview</code></pre>
  </div>
</section>
{% endblock %}

[ ] Step 3: Rebuild and verify hero page

Run: doxide build && mkdocs serve Expected: Homepage shows logo, tagline, "Get Started" / "GitHub" buttons, four feature cards, quick start code block. Navigation tabs still work to navigate to other sections. Stop with Ctrl+C.

[ ] Step 4: Commit

git add docs/overrides/home.html docs/index.md
git commit -m "docs: add custom hero landing page with feature cards and quick start"

Chunk 3: Content Migration — Getting Started¶

Task 7: Write installation page¶

Files: - Modify: docs/getting-started/installation.md

Source: README.md lines 33-44 (requirements table)

[ ] Step 1: Write docs/getting-started/installation.md

# Installation

## Requirements

| Dependency | Version | Notes |
|------------|---------|-------|
| CMake | >= 3.17 | |
| C++ compiler | C++17 | Apple clang (macOS), GCC or nvc++ (Linux) |
| [Armadillo](http://arma.sourceforge.net) | >= 9.2 | Linear algebra |
| [ISMRMRD](https://ismrmrd.github.io) | >= 1.4 | MRI data format |
| [FFTW3](http://www.fftw.org) | | CPU FFT |
| [Boost](https://www.boost.org) | >= 1.43 | Program options, MPI bindings |
| HDF5 | | Data I/O |
| [SuperLU 5](https://github.com/xiaoyeli/superlu) | 5.x | Sparse decompositions |

## Platform-Specific Notes

### macOS (Apple Silicon)

Install dependencies via Homebrew:

    brew install cmake armadillo fftw hdf5 boost superlu ismrmrd

### Linux (Ubuntu/Debian)

    sudo apt install cmake libarmadillo-dev libfftw3-dev libhdf5-dev \
        libboost-all-dev libsuperlu-dev

For NVIDIA GPU support, install the [NVIDIA HPC SDK](https://developer.nvidia.com/hpc-sdk).

[ ] Step 2: Commit

git add docs/getting-started/installation.md
git commit -m "docs: add installation page with requirements and platform notes"

Task 8: Write building page¶

Files: - Modify: docs/getting-started/building.md

Source: README.md lines 46-100 (build commands, CMake options, Docker)

[ ] Step 1: Write docs/getting-started/building.md

# Building from Source

## macOS (Apple Silicon — recommended for development)

```shell
cmake -B build \
    -DMETAL_COMPUTE=ON \
    -DBUILD_FORGEVIEW=ON \
    -DMPISupport=OFF
cmake --build build -j$(sysctl -n hw.logicalcpu)

Linux (NVIDIA GPU via NVIDIA HPC SDK)¶

cmake -B build \
    -DCMAKE_CXX_COMPILER=nvc++ \
    -DOPENACC_GPU=ON \
    -DMPISupport=ON
cmake --build build -j$(nproc)

Linux (CPU only)¶

cmake -B build -DOPENACC_GPU=OFF -DMPISupport=OFF
cmake --build build -j$(nproc)

CMake Options¶

Option	Default	Effect
`-DMETAL_COMPUTE=ON`	OFF	Apple Metal GPU backend
`-DOPENACC_GPU=ON`	OFF	NVIDIA CUDA/OpenACC GPU backend
`-DMPISupport=ON`	ON	MPI-distributed executables
`-DBUILD_FORGEVIEW=ON`	ON	forgeview TUI monitor
`-DENABLE_DOUBLE_PRECISION=ON`	OFF	Double precision throughout

Docker (Linux GPU)¶

docker pull mechneurolab/forge
docker run --gpus all -it mechneurolab/forge

Build Your Own Image¶

# Base image (NVIDIA HPC SDK + dependencies)
docker build -t forge-hpcsdk docker/forge-hpcsdk/

# Runtime image (clones and builds forge)
docker build -t forge docker/forge/

Testing¶

# CPU tests
./build/cpu_tests

# Metal GPU tests (macOS)
./build/metal_tests

- [ ] **Step 2: Commit**

```bash
git add docs/getting-started/building.md
git commit -m "docs: add building page with platform commands, CMake options, Docker"

Task 9: Write first reconstruction page¶

Files: - Modify: docs/getting-started/first-reconstruction.md

Source: README.md lines 104-174 (CLI usage, forgeview, NIfTI)

[ ] Step 1: Write docs/getting-started/first-reconstruction.md

# Your First Reconstruction

## SENSE / NUFFT

```shell
forgeSense \
    -i data.h5 \
    -o output/ \
    -F NUFFT \
    -t 4 \        # time segments for field correction
    -n 20 \       # CG iterations
    -B 0.001      # regularization weight

pcSENSE (phase-corrected, multi-shot)¶

forgePcSense \
    -i data.h5 \
    -o output/ \
    -s 4 \        # number of shots
    -n 20 \
    -B 0.001

Monitoring with forgeview¶

Pipe reconstruction output to forgeview for real-time progress bars, convergence sparklines, and inline image preview:

forgeSense [args] 2>&1 | forgeview

For FORGE Studio integration (JSONL without spawning forgeview):

forgeSense [args] --no-tui

To redirect JSONL to a file or stdout:

forgeSense [args] --jsonl-output /path/to/output.jsonl
forgeSense [args] --jsonl-output stdout

For classic text output (no JSONL):

forgeSense [args] --no-jsonl

NIfTI Orientation Metadata¶

Output NIfTI files automatically include spatial orientation from the ISMRMRD acquisition headers (direction cosines, voxel sizes, position offsets). The ISMRMRD LPS coordinate system is converted to the NIfTI RAS convention, and both qform and sform are populated with NIFTI_XFORM_SCANNER_ANAT.

Override computed voxel sizes:

forgeSense [args] --voxel-size 1.5,1.5,3.0

Suppress orientation metadata (legacy identity behavior):

forgeSense [args] --no-orient

- [ ] **Step 2: Commit**

```bash
git add docs/getting-started/first-reconstruction.md
git commit -m "docs: add first reconstruction page with CLI usage and NIfTI metadata"

[ ] Step 3: Verify Getting Started pages build

Run: doxide build && mkdocs build Expected: No errors. All three Getting Started pages render without broken tables or unclosed code fences.

Chunk 4: Content Migration — Guides¶

Task 10: Write operators and solvers guide¶

Files: - Modify: docs/guides/operators-and-solvers.md

Source: docs/pages/index.md + CLAUDE.md operator tables. The existing docs/pages/index.md is missing pcSENSE and pcSenseTimeSeg — use CLAUDE.md as the authoritative operator list.

[ ] Step 1: Write docs/guides/operators-and-solvers.md

# Operators & Solvers

## Operator Convention

All encoding operators in forge follow a unified interface:

| Expression | Meaning |
|------------|---------|
| `G * x`    | Forward transform: image -> k-space |
| `G / y`    | Adjoint transform: k-space -> image |

Both operators accept and return `arma::Col<std::complex<T1>>` vectors at the
Armadillo interface boundary. Internally, hot paths use `forgeCol`/`forgeMat`
for GPU dispatch (see [forge Types](forge-types.md)).

## Encoding Operators

| Class | Header | Description |
|-------|--------|-------------|
| `Gdft<T1>` | `Operators/Gdft.h` | Direct non-uniform DFT with optional off-resonance correction |
| `GdftR2<T1>` | `Operators/GdftR2.h` | Gdft extended with R2* field map gradient support |
| `Gnufft<T1>` | `Operators/Gnufft.h` | Fast NUFFT via Kaiser-Bessel gridding (CPU + GPU) |
| `Gfft<T1>` | `Operators/Gfft.h` | Uniform Cartesian FFT (wraps FFTW / cuFFT) |
| `SENSE<T1, Tobj>` | `Operators/SENSE.h` | Multi-coil sensitivity encoding wrapping any encoding operator |
| `pcSENSE<T1>` | `Operators/pcSENSE.h` | Phase-corrected SENSE with per-shot phase maps |
| `pcSenseTimeSeg<T1>` | `Operators/pcSenseTimeSeg.h` | pcSENSE combined with time-segmented field correction |
| `TimeSegmentation<T1, Tobj>` | `Gridding/TimeSegmentation.h` | Off-resonance correction via time-segmented interpolation |

## Regularization

All regularization operators inherit from `Robject<T1>`:

| Class | Header | Description |
|-------|--------|-------------|
| `Robject<T1>` | `Penalties/Robject.h` | Abstract base class for penalty functions |
| `QuadPenalty<T1>` | `Penalties/QuadPenalty.h` | Quadratic (Tikhonov) penalty |
| `TVPenalty<T1>` | `Penalties/TVPenalty.h` | Approximate total-variation penalty |

## Solvers

| Function | Header | Description |
|----------|--------|-------------|
| `solve_pwls_pcg` | `Solvers/solve_pwls_pcg.hpp` | Preconditioned weighted least-squares via conjugate gradient (Polak-Ribiere-Polyak beta) |
| `solve_grad_desc` | `Solvers/solve_grad_desc.hpp` | Gradient descent solver |
| `reconSolve` | `Solvers/reconSolve.h` | High-level reconstruction entry point |

## Quick Example

```cpp
#include "forge/Operators/Gdft.h"
#include "forge/Penalties/QuadPenalty.h"
#include "forge/Solvers/solve_pwls_pcg.hpp"
using namespace arma;

// Build a Cartesian Gdft operator (8x8 image, 64 k-space samples)
uword Nx = 8, Ny = 8, n1 = Nx*Ny, n2 = Nx*Ny;
Col<float> kx(n2), ky(n2), kz(n2, fill::zeros);
Col<float> ix(n1), iy(n1), iz(n1, fill::zeros);
// ... fill kx/ky with Cartesian grid, ix/iy with pixel positions ...
Col<float> FM(n1, fill::zeros), t(n2, fill::zeros);
Gdft<float> G(n1, n2, kx, ky, kz, ix, iy, iz, FM, t);

// Forward transform
Col<cx_float> image(n1, fill::ones);
Col<cx_float> kspace = G * image;

// Adjoint transform
Col<cx_float> back = G / kspace;

// Iterative reconstruction via PCG
Col<float> W(n2, fill::ones);
QuadPenalty<float> R(Nx, Ny, 1, 0.01f);
Col<cx_float> x0(n1, fill::zeros);
Col<cx_float> xhat = solve_pwls_pcg<float>(x0, G, W, kspace, R, 50);

- [ ] **Step 2: Commit**

```bash
git add docs/guides/operators-and-solvers.md
git commit -m "docs: add operators and solvers guide with complete operator table"

Task 11: Migrate forge types guide¶

Files: - Modify: docs/guides/forge-types.md

Source: docs/pgcol-pgmat-guide.md (copy content, adjust for MkDocs formatting)

[ ] Step 1: Copy and adapt docs/pgcol-pgmat-guide.md to docs/guides/forge-types.md

Copy the full content of docs/pgcol-pgmat-guide.md into docs/guides/forge-types.md. No structural changes needed — the existing content is already well-organized Markdown. Just verify that code blocks use triple-backtick fencing (they do) and tables render correctly.

[ ] Step 2: Commit

git add docs/guides/forge-types.md
git commit -m "docs: migrate forgeCol/forgeMat developer guide"

Task 12: Migrate Metal backend guide¶

Files: - Modify: docs/guides/metal-backend.md

Source: docs/metal-backend.md. Update stale references: build_native -> build, remove the ghcr.io/acerjanic/powergrid-hpcsdk Docker reference (use current build commands from README).

[ ] Step 1: Copy docs/metal-backend.md to docs/guides/metal-backend.md

Copy the full content. Then fix these stale references:

Replace build_native with build in all build/test commands (lines 64-94)
Replace the Docker command on line 76-79 (references powergrid-hpcsdk) with the current Docker build from README:

docker build -t forge-hpcsdk docker/forge-hpcsdk/
docker build -t forge docker/forge/

[ ] Step 2: Commit

git add docs/guides/metal-backend.md
git commit -m "docs: migrate Metal backend guide with updated build commands"

Task 13: Write forgeview guide¶

Files: - Modify: docs/guides/forgeview.md

Source: README.md lines 129-155 (forgeview piping, CLI flags) + CLAUDE.md JSONL protocol section

[ ] Step 1: Write docs/guides/forgeview.md

# forgeview TUI

forgeview is a live terminal UI for monitoring forge reconstructions. It reads
structured JSONL on stdin and displays progress bars, convergence sparklines,
and log messages.

## Usage

Pipe any forge reconstruction executable to forgeview:

```shell
forgeSense [args] 2>&1 | forgeview

Output Modes¶

Default: JSONL + forgeview auto-spawn¶

Reconstruction executables output structured JSONL by default and attempt to spawn forgeview automatically.

FORGE Studio integration¶

Output JSONL without spawning forgeview (for programmatic consumption):

forgeSense [args] --no-tui

Redirect JSONL to file¶

forgeSense [args] --jsonl-output /path/to/output.jsonl
forgeSense [args] --jsonl-output stdout

Classic text output¶

Disable JSONL entirely for traditional spdlog+indicators output:

forgeSense [args] --no-jsonl

JSONL Protocol¶

JSONL messages are single-line JSON objects on stderr with a "type" field:

Type	Description
`log`	Log message with timestamp, level, file, line, message
`progress`	Progress bar add/tick/done with label, max, current count
`metrics`	Per-iteration error norm and penalty values (PCG solver)
`start`	Reconstruction lifecycle start event
`exit`	Reconstruction lifecycle exit event

forgeview Features¶

Scrolling log area with color-coded severity levels
Progress bars with percentage, ETA (time remaining), and wall clock completion time

Sparkline convergence plots (error norm + roughness penalty) using Unicode block characters

- [ ] **Step 2: Commit**

```bash
git add docs/guides/forgeview.md
git commit -m "docs: add forgeview TUI guide with JSONL protocol reference"

Task 14: Write MPI guide¶

Files: - Modify: docs/guides/mpi.md

Source: README.md lines 176-187 (MPI distributed reconstruction)

[ ] Step 1: Write docs/guides/mpi.md

# MPI Distributed Reconstruction

forge supports distributed-memory parallel reconstruction via MPI. Build with
`-DMPISupport=ON` to produce MPI-enabled executables (`forgeSenseMPI`,
`forgePcSenseMPI`).

## Building with MPI

```shell
cmake -B build \
    -DCMAKE_CXX_COMPILER=nvc++ \
    -DOPENACC_GPU=ON \
    -DMPISupport=ON
cmake --build build -j$(nproc)

Running¶

mpirun -np 4 forgeSenseMPI \
    --device auto \
    --no-tui \
    -i data.h5 \
    -o output/ \
    -F NUFFT \
    -I minmax \
    -t 6

Options¶

Flag	Description
`--device auto`	Assigns GPU `rank % num_gpus` to each MPI process
`--device N`	Explicitly assign GPU N to this process
`--mpi-log-all`	Enable log output from all ranks (default: rank 0 only)
`--no-tui`	Required for MPI — disables forgeview auto-spawn
- [ ] Step 2: Commit ```bash git add docs/guides/mpi.md git commit -m "docs: add MPI distributed reconstruction guide"

[ ] Step 3: Verify all Guides pages build

Run: doxide build && mkdocs build Expected: No errors. All five Guides pages render correctly.

Chunk 5: Cleanup and Final Verification¶

Task 15: Remove old hdoc infrastructure¶

Files: - Remove: .hdoc.toml - Remove: scripts/generate-docs.sh - Remove: docker/forge-hdoc/Dockerfile

[ ] Step 1: Remove old files

Run:

git rm .hdoc.toml
git rm scripts/generate-docs.sh
git rm docker/forge-hdoc/Dockerfile

If docker/forge-hdoc/ directory is now empty, remove it too:

rmdir docker/forge-hdoc 2>/dev/null && git add docker/forge-hdoc

[ ] Step 2: Update README.md API Documentation section

Replace the "API Documentation" section (lines 191-206) in README.md with:

## API Documentation

forge uses [Doxide](https://doxide.org) + [MkDocs Material](https://squidfunk.github.io/mkdocs-material/)
for documentation. Build locally:

```shell
pip install -r docs/requirements.txt
brew install doxide  # macOS
doxide build && mkdocs serve

View at http://127.0.0.1:8000/.

- [ ] **Step 3: Commit**

```bash
git add -A
git commit -m "docs: remove hdoc infrastructure, update README with Doxide instructions"

Task 16: Full build verification¶

[ ] Step 1: Clean rebuild

Run:

rm -rf docs/api/*.md site/
doxide build && mkdocs build

Expected: No errors. site/ directory contains the built static site.

[ ] Step 2: Verify all pages render

Run: mkdocs serve

Check each page in the browser:

[ ] Home — hero page with logo, feature cards, quick start
[ ] Getting Started > Installation — requirements table
[ ] Getting Started > Building — platform build commands, Docker
[ ] Getting Started > First Reconstruction — CLI examples, NIfTI metadata
[ ] Guides > Operators & Solvers — full operator table with pcSENSE
[ ] Guides > forge Types — forgeCol/forgeMat guide
[ ] Guides > Metal GPU Backend — architecture, dispatch chain
[ ] Guides > forgeview TUI — JSONL protocol, features
[ ] Guides > MPI — build and run instructions
[ ] API Reference — Doxide-generated class/namespace pages
[ ] Dark/light toggle works across all pages
[ ] Gradient accent bar visible under header
[ ] Navigation tabs work correctly
[ ] Search returns results

Stop with Ctrl+C.

[ ] Step 3: Final commit if any fixes were needed

git add -A
git commit -m "docs: fix issues found during final verification"