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