> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Monogrid

> Rust CLI tool that checks and auto-fixes ASCII box alignment for CodexMono monospace rendering.

Monogrid ensures every line in a Unicode box drawing has the same visual width — accounting for CJK characters (2 columns), emoji (2 columns), combining marks (0 width), and ASCII (1 column).

The width tables are Q.E.D verified across xterm.js, Alacritty, and Ghostty.

***

## Quick Start

```bash theme={null}
# Check a file
monogrid check docs/guide.md

# Auto-fix alignment issues
monogrid fix docs/guide.md

# Verify at character level
monogrid qed docs/guide.md
```

Monogrid is a single binary (2.2 MB) with no runtime dependencies.

***

## Installation

Included with the Monolex app, or install via:

```bash theme={null}
niia setup

# Verify
monogrid version
```

Monogrid is part of the mono- CLI family:

```
┌──────────────────────────────────────────────────────────────────┐
│  ~/.niia/bin/                                                    │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  monogram    8.4 MB   Code search (trigram + call chain)         │
│  monogrid    2.2 MB   Box alignment (Unicode width + 9 rules)    │
│  monokist    6.9 MB   Git structure (branch/commit cache)        │
│  monomento   6.6 MB   Document search (trigram + ref graph)      │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
```

***

## Commands

### check — Inspect Without Modifying

```bash theme={null}
monogrid check <files...> [-v] [--show-flow]
```

| Flag          | Description                                                |
| ------------- | ---------------------------------------------------------- |
| `-v`          | Verbose — show box details (pattern, nesting, inner boxes) |
| `--show-flow` | Show flow diagram detections (info only)                   |

Implicit check: `monogrid file.md` works without the `check` keyword.

Exit code `0` if no issues, `1` if issues found.

### fix — Auto-Fix with Loop

```bash theme={null}
monogrid fix <files...> [--outer-only] [--max-iter N] [--qed]
```

| Flag           | Description                                  |
| -------------- | -------------------------------------------- |
| `--fix-all`    | Fix outer width + inner │ position (default) |
| `--outer-only` | Fix outer width only                         |
| `--max-iter N` | Max iterations (default: 10)                 |
| `--qed`        | Run Q.E.D verification after fixing          |

Repeats check-fix cycles until 0 issues or max iterations reached.

<Warning>This command modifies files in place.</Warning>

### qed — Q.E.D Deep Verification

```bash theme={null}
monogrid qed <files...>
```

Character-by-character width analysis. For each box:

* Calculates visual width of every line
* Lists every non-ASCII character with its Unicode codepoint and width
* Groups by category (COMBINING, BMP\_WIDE, HIGH\_WIDE, DEFAULT)
* Verifies recalculated width matches expected

Only meaningful after all issues are fixed.

### structure — Structural Analysis

```bash theme={null}
monogrid structure <files...>
```

Detects inner boxes that overflow outer box boundaries. Shows left/right margins for each nested box. Cannot be auto-fixed — requires manual redesign.

### report — Compact File Survey

```bash theme={null}
monogrid report <files...>
```

One-line-per-file summary sorted by issue count. Useful for surveying large documentation sets before batch fixing.

***

## Workflow

```
┌──────────────────────────────────────────────────────────────────┐
│  RECOMMENDED WORKFLOW                                            │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Step 0: monogrid report docs/*.mdx                              │
│          → Survey: which files, how many issues                  │
│                                                                  │
│  Step 1: monogrid fix docs/*.mdx                                 │
│          → Auto-fix outer + inner Rule 6 (~90% resolved)         │
│                                                                  │
│  Step 2: monogrid check docs/problem-file.mdx -v                 │
│          → See remaining issues (manual-only rules)              │
│                                                                  │
│  Step 3: monogrid structure docs/problem-file.mdx                │
│          → Diagnose structural overflows                         │
│                                                                  │
│  Step 4: (manual edit) + monogrid qed docs/file.mdx              │
│          → Character-level proof of correctness                  │
│                                                                  │
│  Step 5: monogrid report docs/*.mdx                              │
│          → Confirm 0 issues across all files                     │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
```

***

## What It Checks

Monogrid enforces 9 alignment rules:

| Rule | Name                              | Auto-Fix  |
| ---- | --------------------------------- | --------- |
| 1    | Outer box width consistency       | Yes       |
| 2    | Missing inner border (closing │)  | No        |
| 3    | Inner ║ position consistency      | No        |
| 4    | Inner border ═ width match        | No        |
| 5    | Flow diagram recognition          | Info only |
| 6    | Single-line box │ position        | Yes       |
| 7    | Missing border (content overflow) | No        |
| 8    | ASCII box detection (+---+)       | No        |
| 9    | Structural overflow analysis      | No        |

Rules 1 and 6 are auto-fixable. All other rules require manual correction because they need semantic understanding of the diagram.

***

## Width Rules

CodexMono renders characters at these widths:

| Category         | Width | Examples                   |
| ---------------- | ----- | -------------------------- |
| ASCII            | 1     | `A-Z`, `0-9`, `!@#`        |
| Box Drawing      | 1     | `┌ ─ ┐ │ └ ┘ ╔ ═ ╗ ║`      |
| CJK Ideographs   | 2     | `漢 字 한 글`                  |
| Hangul Syllables | 2     | `가 나 다`                    |
| Emoji            | 2     | `✅ ❌ ⭐ 💥 🔥`              |
| Fullwidth ASCII  | 2     | `Ａ Ｂ Ｃ`                    |
| Combining Marks  | 0     | Variation Selectors (VS16) |

<Warning>
  **Common mistake:** ⚠ (U+26A0) is width **1**, not 2. But ⚡ (U+26A1) is width **2**.
  These are only 1 codepoint apart but have different widths. Monogrid's tables handle this correctly.
</Warning>

***

## Self-Verification

Monogrid's own `--help` output passes `monogrid check` with 0 issues:

```bash theme={null}
monogrid --help > /tmp/help.txt
monogrid check /tmp/help.txt
# ✅ All boxes aligned correctly (outer + inner)!
# Total issues found: 0
```

***

## Origin

Monogrid is an exact port of `check-boxes.py` v5.7 (Python, 1,984 lines) to Rust (2,719 lines). The Unicode width tables were verified through ASURA 3-Phase Research across three terminal emulators. Both versions produce identical results on all test files.