> ## 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.

*Published contract: `monogrid 0.2.1`, OpenCLIs build
`2026-05-23-201214`. The executing binary, registry, and public CDN metadata
agree on this release.*

The published dispatcher has **six operational roots**: `check`, `fix`, `qed`,
`structure`, `report`, and `--mcp-schema` (`mcp-schema` alias), plus
help/version aliases and implicit file checking. Current source adds `docs` as
a seventh root, but that source-ahead command is not in the public build above.

***

## 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 standalone native binary with no Python runtime dependency.

***

## Installation

Install the current public payload through OpenCLIs:

```bash theme={null}
openclis install monogrid

# Verify
monogrid --version
monogrid --help
```

***

## Commands

| Command | Purpose | Mutation boundary |
| - | - | - |
| `check <files...>` | Runs all applicable alignment checks. | Read-only; non-zero when issues exist. |
| `fix <files...>` | Iteratively repairs Rule 1 and, by default, Rule 6. | Edits files in place. |
| `qed <files...>` | Recomputes visual widths character by character. | Read-only deep proof after repairs. |
| `structure <files...>` | Detects nested boxes that overflow their outer boundaries. | Read-only; findings require manual redesign. |
| `report <files...>` | Prints one compact, issue-sorted line per file. | Read-only batch survey. |
| `docs [topic]` | Source-main command that lists or serves embedded agent documentation. | Read-only, but not shipped in public build `2026-05-23-201214`; that payload reports `Unknown command: docs`. |
| `--mcp-schema` / `mcp-schema` | Emits typed JSON for `check`, `qed`, `structure`, and `report`. | Read-only discovery; mutating `fix` is deliberately omitted. |
| `help` / `-h` / `--help` | Prints the embedded complete guide. | Read-only. |
| `version` / `-V` / `--version` | Prints the executing payload version. | Read-only. |

Passing files without a command is an implicit `check`.

## Embedded Docs and MCP Boundary

```bash theme={null}
monogrid --mcp-schema      # typed read-only command schema

# Current source builds only; not the published 0.2.1 payload
monogrid docs              # list topics
monogrid docs index        # bundled agent reference
```

The MCP schema contains exactly four commands: `check`, `qed`, `structure`,
and `report`. It excludes `fix`, `docs`, help, and version. Monogrid also has no
native `--json` result mode; typed MCP-to-CLI calls therefore return text. A
schema entry proves argument mapping, not that a file passes alignment checks.
Use `monogrid help` or this page for embedded guidance on the public build;
`monogrid docs` becomes valid only after a later payload includes the current
source dispatcher.

## Published Platforms

| Target | Artifact |
| - | -: |
| macOS Arm64 | Yes |
| macOS x86\_64 | Yes |
| Linux x86\_64 | Yes |
| Linux Arm64 | Yes |
| Windows x86\_64 | Yes |
| Windows Arm64 | No |

All five artifacts expose the same file-oriented command parser. Shell glob
expansion is still owned by the host shell, not by Monogrid itself.

### 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 | Legacy ASCII border detection; convert to `┌───┐` form | 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 began as the native Rust port of `check-boxes.py` v5.7. Its Unicode
width tables were verified through ASURA research across xterm.js, Alacritty,
and Ghostty; current release truth is owned by the Rust payload and its tests,
not by historical source line counts.

## Relationships

| Tool | Ownership |
| - | - |
| [MonoGlyph](/ai-clis/monoglyph) | Converts images/screens into glyph fields; Monogrid verifies textual box geometry |
| [NIIA](/ai-clis/niia) | Orchestrates documentation workflows that can use Monogrid as a quality gate |
| [MonoTerm](/ai-clis/monoterm/overview) | Renders terminal UI; Monogrid checks source diagrams, not live TUI layout |
| [CodexMono](/codexmono/cli) | Defines the intended monospace rendering context; Monogrid owns source-width checks, not font installation |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.