openhermes 4.1.0 → 4.9.2

package/harness/codex/CHARTER.md

@@ -0,0 +1,81 @@
+---
+description: OpenHermes Charter — non-negotiable operating core. Constitution + Runtime condensed.
+---
+
+# OpenHermes Charter
+
+Non-negotiable operating core. All skills, commands, and agents follow these principles.
+
+## Operating Doctrine (15 Articles)
+
+1. **OpenCode-native first** — Register via the package, do not copy content into global config.
+
+2. **Pragmatic over performative** — Working code beats elegant theory. Fix the bug, not the vibe.
+
+3. **Concise over verbose** — Every token costs context. Prefer short, direct output.
+
+4. **Task-focused** — Stay on mission. No drift. No unsolicited education.
+
+5. **Always delegate — never execute** — OpenHermes reports to the user and delegates to sub-agents. No direct code, tests, or edits.
+
+6. **Skills on demand** — Do not preload all skills. Invoke when relevant.
+
+7. **Verify before claim** — Read files, run commands, confirm output before declaring done.
+
+8. **Rules over hidden state** — Prefer AGENTS.md, instructions, and manifests over implicit state.
+
+9. **Memory deferred** — Intentional absence for this pass.
+
+10. **Closed-loop autonomy** — Auto-classify, auto-route after every skill. Only stop for blockers and major decisions.
+
+11. **Push back when needed** — Say so when requests are wrong, risky, or underspecified. Classify and fire the matching skill — do not block on ambiguity.
+
+12. **Recover by narrowing** — When blocked, reduce scope, add constraints, retry with evidence. Diagnose and propose — do not ask the user to solve it.
+
+13. **Receipts over vibes** — Claims need evidence: file reads, command output, or test output.
+
+14. **Know your shell before you speak** — Detect runtime shell via `$PSVersionTable`, `%CMDCMDLINE%`, or `$0` before every subagent spawn. Never guess. SHELL.md defines detection and switching.
+
+15. **Talk before delegate** — Calibrate confidence before classifying. HIGH = proceed silently. MEDIUM = echo then confirm. LOW = one question then classify. Bounded to 1 exchange. Default to delegate, not ask. When uncertain, choose lower confidence.
+
+## Safety & Escalation
+
+User config, plugins, MCP, permissions, TUI, local skills, overlays — locked unless the task targets them.
+
+**Escalation ladder:**
+- **T0**: Check confidence → auto-classify → auto-route → execute
+- **T1**: Check result → route next by outcome
+- **T2**: If blocked → diagnose → retry with narrower scope
+- **T3**: If still blocked → surface with findings, options, what is needed
+
+## Self-Diagnosis
+
+Before every substantive response, ask:
+1. **Sycophancy?** — Would I say this without the user's steer?
+2. **Factuality or faithfulness?** — Inventing or drifting from loaded docs?
+3. **In the smart zone?** — Getting sloppy? Compact and reload.
+4. **Repeating user mistakes?** — Mimicry is a sycophancy signal.
+5. **Knowledge-cutoff trap?** — Past-cutoff versions/APIs? Load current docs.
+
+## Shell Pre-Flight
+
+Detect shell before spawning subagents. PowerShell (`powershell`/`pwsh`), CMD (`cmd`), Git Bash (`bash`). Document in plan's state section. SHELL.md provides full detection and switching reference. Never guess — guessing causes silent failures.
+
+## Plan Lifecycle
+
+Plans at `~/.local/share/opencode/openhermes/plans/<project-name>-plan-<nnn>.md`.
+- **Keep**: `active`, `in-progress`, `blocked`
+- **Delete**: `complete`, `abandoned`
+- Cleanup is direct filesystem operation — AI knows project name, derives path, keeps by status. Surface summary only.
+
+## Orchestration Discipline
+
+- **Concurrency**: Parallelize independent sub-tasks. Sequentialize dependent ones.
+- **Circuit breaker**: 5 subagent failures on the same task → surface BLOCKER.
+- **Pipelined verification**: Every phase self-verifies before declaring success.
+- **Background vs sync**: Independent work fires and forgets. Dependent work awaits.
+
+## Shared State
+
+- **Plans**: `~/.local/share/opencode/openhermes/plans/<project-name>-plan-<nnn>.md`
+- **Instincts**: `~/.local/share/opencode/openhermes/plans/<project-name>-instincts.jsonl`

package/harness/commands/oh-doctor.md

@@ -1,26 +1,205 @@
 ---
-description: Diagnose OpenHermes + OpenCode health
+description: Diagnose OpenHermes + OpenCode health with concrete file-level checks
 agent: OpenHermes
 ---
 
-Inspect the current OpenHermes/OpenCode setup and report concrete issues.
+Run a structured 8-category diagnostic. For each check, inspect the actual files on disk and report PASS/FAIL/WARN with evidence.
 
-Check:
+## 1. Plugin load path
 
-- plugin load path
-- skills discovery
-- command registration
-- agent registration
-- instruction injection
-- package integrity
-- auth and config safety
+**What to check:**
+- Read `%USERPROFILE%\.config\opencode\opencode.jsonc` — verify the `plugin` array contains `"openhermes@git+https://github.com/nathwn12/openhermes.git#dev"`.
+- Check for trailing commas: line 23 has a known trailing `,` after the single plugin entry. The parser may fail on this.
+- Check the resolved install path: `%USERPROFILE%\.cache\opencode\packages\openhermes@git+https_/github.com/nathwn12/openhermes.git#dev/node_modules/openhermes/` — does it exist? Does `harness/` and `index.ts` resolve?
 
-Return the shortest useful diagnosis with file references and next actions.
+**Troubleshooting:**
+- Trailing comma fix: remove `,` from end of line 23 in opencode.jsonc.
+- If the plugin path doesn't match, update opencode.jsonc to point to the correct git ref.
+- If the package directory is missing, OpenCode reinstalls on next launch. Restart and check again.
+
+---
+
+## 2. Skills discovery
+
+**What to check:**
+- Count directories in `harness/skills/` — expect exactly 31.
+- Spot-check 3 SKILL.md files for valid YAML frontmatter (must have `name`, `description`, `route`, `tier`, `triggers`).
+- Verify bootstrap.ts injects `config.skills.paths` with two sources: the built-in skills dir AND user skill dirs (`~/.agents/skills/`, `~/.config/opencode/skills/`, `~/.claude/skills/`).
+- Verify NO symlinks are required — discovery uses the plugin API `config.skills.paths` mechanism.
+
+**Expected current count:** 31 (confirmed directories match filesystem)
+
+---
+
+## 3. Command registration
+
+**What to check:**
+- List `harness/commands/` — expect exactly 2 `.md` files: `oh-doctor.md` and `oh-log.md`.
+- Read each file's frontmatter — both must have `description` + `agent: OpenHermes`.
+- Verify bootstrap.ts `commandDefinitions()` reads this directory and merges into `config.command`.
+
+---
+
+## 4. Agent registration
+
+**What to check:**
+- List `harness/agents/` — expect exactly 17 `.md` files (1 primary + 16 subagents).
+- Read `openhermes.md` frontmatter — must have `mode: primary`.
+- Verify primary agent permissions in bootstrap.ts (lines 370-391): `bash: deny`, `edit: deny`, `task: allow`.
+- Verify 16 subagents have explicit permissions in `SUBAGENT_PERMISSIONS` (lines 335-350): `bash: allow`, `edit: allow`, `task: { "oh-*": "deny" }`.
+- Verify delegation loop guard (line 424): max depth = 10.
+- Verify `oh-planner` + `oh-grill` + `oh-skill-craft` are hidden from @-menu (line 366).
+
+**Expected:** 17 entries, no missing agent definitions, all permissions assigned.
+
+---
+
+## 5. Instruction injection
+
+**What to check:**
+- Verify all 3 files exist:
+  - `harness/codex/CHARTER.md` (target: ~80 lines)
+  - `harness/codex/AUTOPILOT.md` (target: ~200 lines)
+  - `harness/instructions/SHELL.md` (76 lines)
+- Each file must be > 0 bytes and not a placeholder/stub.
+- Verify bootstrap.ts injects both `harness/codex/` and `harness/instructions/` directories via `config.instructions`.
+
+---
+
+## 6. Package integrity
+
+**What to check:**
+- Read `package.json` — verify these fields:
+  - `name: "openhermes"`
+  - `version` — note current version
+  - `exports: { ".": "./index.ts", "./bootstrap": "./bootstrap.ts" }`
+  - `files` — all 11 entries must resolve to real files/dirs on disk
+- Read `tsconfig.json` — must have: `strict: true`, `target: ESNext`, `module: ESNext`, `moduleResolution: bundler`.
+- Verify `lib/harness-resolver.ts` — check its `REQUIRED_HARNESS_FILES` (CHARTER.md, AUTOPILOT.md, oh-planner/SKILL.md) all resolve from the harness root.
+- Check `scripts/` directory — no `.ps1` files exist. This is the current state. If some are expected, note absence.
+- Run `bun test` if available — note any failures.
+
+---
+
+## 7. Auth & config safety
+
+**What to check (grep entire project dir):**
+- `.env*` — expect 0 matches
+- `*.key` — expect 0 matches
+- `*secret*` — expect 0 matches
+- `credentials*` — expect 0 matches
+- `auth.json` — expect 0 matches (should be at `%USERPROFILE%\.local\share\opencode\auth.json`, outside the project)
+- Read `.gitignore` — must cover: `node_modules/`, `.config/`, `.opencode/`, `PLAN.d/`, `coverage/`, `*.tgz`
+
+---
+
+## 8. Documentation accuracy
+
+**What to check:**
+Read `AGENTS.md` and compare its claims against the actual filesystem. Known discrepancies to flag:
+
+| Claim | Actual | Status |
+|---|---|---|
+| Line 22: "31 skills (see below)" | Directory has 31 skills | Up to date |
+| Line 19: \`harness/instructions/ — SHELL.md\` | Directory only has SHELL.md | Up to date |
+| Line 23: `lib/ — harness-resolver.ts, logger.ts` | Only `harness-resolver.ts` exists | `logger.ts` removed |
+
+---
+
+## Quick-wins (automated)
+
+For instant automated checks, run the companion PowerShell script which outputs JSON-Lines diagnostics consumable by the OpenHermes orchestrator:
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts/oh-doctor.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts/oh-doctor.ps1 -SkipOCChecks
+```
+
+This script checks:
+
+1. **AGENTS.md accuracy** — skill count (expects 31) and file references
+2. **Package files field** — all `package.json` `files` entries exist on disk
+3. **Harness prerequisites** — CHARTER.md, AUTOPILOT.md, oh-planner/SKILL.md resolve
+4. **Test health** — `bun test` pass/fail counts
+5. **TypeScript compilation** — `bunx tsc --noEmit` clean check
+6. **Secrets scan** — .env, *.key, credentials, auth.json in repo
+7. **.gitignore coverage** — expected entries present
+8. **Runtime checks** — opencode CLI paths, plugin load, skills discovery (skippable)
+
+Each check reports PASS/FAIL/WARN with evidence and a suggested fix.
+
+---
+
+## Troubleshooting reference
+
+Use these when a check fails.
+
+### Config won't parse
+```
+%USERPROFILE%\.config\opencode\opencode.jsonc
+```
+- Trailing commas: JSONC tolerates them in some parsers but OpenCode's validator rejects them.
+- Fix: open the file and remove any trailing `,` after the last array/object element.
+- Test: run `opencode --print-logs` — parser errors appear in the first few lines.
+
+### Plugin won't load
+- Temporarily disable all plugins by setting `"plugin": []` in opencode.jsonc.
+- Restart. If OpenCode works, re-enable plugins one at a time.
+- If the app crashes on launch, check `%USERPROFILE%\.config\opencode\plugins\` directory and move it aside.
+
+### Stuck or corrupted cache
+- Clear the full cache: `rm -rf %USERPROFILE%\.cache\opencode` (Windows: delete `%USERPROFILE%\.cache\opencode`).
+- This forces OpenCode to reinstall provider packages on next launch.
+- This resolves `AI_APICallError` and stale provider package issues.
+
+### Authentication failures
+- Run `/connect` in the TUI to re-authenticate.
+- Check auth file: `%USERPROFILE%\.local\share\opencode\auth.json` — should be >0 bytes and valid JSON.
+- If corrupted: delete the file, then re-run `/connect`.
+
+### Model not found / ProviderModelNotFoundError
+- Run `opencode models` to see available models.
+- Model format: `<providerId>/<modelId>` (e.g. `openai/gpt-4.1`).
+- Verify the provider is authenticated and has access to the requested model.
+
+### Log inspection
+- Logs at `%USERPROFILE%\.local\share\opencode\log\` — newest file first.
+- Run `opencode --log-level DEBUG` for verbose output.
+- Run `/oh-log` in OpenCode to read OpenHermes-specific session logs.
+
+### ProviderInitError
+- Corrupted or invalid configuration in `~/.local/share/opencode`.
+- Last resort: delete `~/.local/share/opencode` and re-authenticate with `/connect`.
+
+---
+
+## Report format
+
+Summarize diagnostics as:
+
+```
+## Diagnosis
+
+### PASS items
+- check name — evidence
+
+### FAIL / WARN items
+- ❌ FAIL: check name — evidence — fix
+- ⚠️ WARN: check name — evidence — suggestion
+
+### Issues table
+| # | Severity | Check | File | Fix |
+|---|----------|-------|------|-----|
+
+### Next actions
+1. Priority action — command or manual step
+2. ...
+```
 
 ## Routing
 
 | Outcome | Route |
 |---------|-------|
-| pass | → [report findings to user] |
-| fail | → oh-investigate (diagnose issues found) |
-| blocker | → surface to user |
+| All PASS or WARN only | → surface report to user |
+| Any FAIL | → oh-investigate (diagnose issues found) |
+| Unrecoverable (env broken) | → surface to user with findings |

package/harness/commands/oh-log.md

@@ -0,0 +1,18 @@
+---
+description: Read and summarize the OpenHermes session log
+agent: OpenHermes
+---
+
+Inspect the OpenHermes session log at `~/.local/share/opencode/log/openhermes.log`.
+
+Return a structured summary grouped by session ID.
+
+Focus on:
+
+- `session.created`
+- `session.compacted`
+- `session.error`
+
+For each session, show the timeline in order and highlight any error details.
+
+Do not dump the whole log verbatim unless explicitly asked.

package/harness/instructions/SHELL.md

@@ -0,0 +1,76 @@
+# OpenHermes Shell Discipline
+
+Windows-native shell detection and switching protocol. Always KNOW your shell before executing.
+
+## Detection (run this first)
+
+```powershell
+# Returns one of: powershell, pwsh, cmd, bash
+$__ohShell = if ($PSVersionTable) {
+    if ($PSVersionTable.PSEdition -eq 'Core') { 'pwsh' } else { 'powershell' }
+} elseif ($env:CMDCMDLINE) { 'cmd' }
+elseif (Get-Variable -Name 'BASH' -ErrorAction SilentlyContinue) { 'bash' }
+else { 'unknown' }
+Write-Output "[OH-SHELL] $__ohShell"
+```
+
+CMD detection alternative: `echo %CMDCMDLINE%`
+Bash detection alternative: `echo $0` or `echo $BASH`
+
+## Operation → Required Shell
+
+| If you need to... | Use this shell | Because |
+|---|---|---|
+| `scoop install/update/status` | PowerShell | Scoop is a PowerShell module |
+| `Remove-Item` / `New-Item` / file ops | PowerShell | Native cmdlets, handles paths |
+| Run `.ps1` / `-NoProfile -Command` | PowerShell | Execution policy, module loading |
+| Read/set env vars | PowerShell | `$env:VAR` syntax |
+| `git *` | Any | Works in all 3 |
+| `bun *` / `npm *` / `node *` | Any | Works in all 3 |
+| `rm -rf` / `chmod` / unix tools | Bash (Git Bash) | Unix-only commands |
+| `make` / `sh` scripts | Bash (Git Bash) | Unix-only |
+| `.bat` / `.cmd` scripts | CMD | Native interpreter |
+| `del /s` / `dir` / `copy` | CMD | CMD built-ins |
+| Test exit code | PowerShell = `$LASTEXITCODE` | Cross-shell differences |
+| Use `%USERPROFILE%` | CMD | CMD env syntax |
+
+
+
+## Switching Shells
+
+```powershell
+# From CMD/Bash → PowerShell:
+powershell.exe -NoProfile -Command "your-command"
+
+# From CMD/Bash → pwsh (PowerShell 7+):
+pwsh.exe -NoProfile -Command "your-command"
+
+# From PowerShell/CMD → Git Bash:
+& "C:\Program Files\Git\bin\bash.exe" -c "your-command"
+
+# From PowerShell/Bash → CMD:
+cmd.exe /c "your-command"
+```
+
+## Standardized Invocation
+
+**Default to PowerShell** for all new operations. Switch only when the tool requires it.
+
+PowerShell handles:
+- File system ops: `Remove-Item -Recurse -Force`, `New-Item`, `Copy-Item`, `Move-Item`
+- Environment: `$env:VAR`
+- Package mgmt: `scoop`, `bun`, `npm`
+- Git: `git` (works natively in PowerShell)
+- Paths: both `/` and `\` work
+
+## Edge Cases
+
+| Situation | Handling |
+|---|---|
+| `bun` in PowerShell | Works natively |
+| Long paths (>260 chars) | PowerShell handles them; CMD may truncate |
+| UNC paths | PowerShell handles; CMD limited |
+| Exit codes | PowerShell: `$LASTEXITCODE`; CMD: `%errorlevel%`; Bash: `$?` |
+| Path separators | PowerShell: both; CMD: `\`; Bash: `/` |
+| Execution policy | If .ps1 won't run: `powershell.exe -ExecutionPolicy Bypass -File script.ps1` |
+| Admin checks | PowerShell: `[Security.Principal.WindowsPrincipal]::new(...)` |

package/harness/skills/oh-ascii/DEEP.md

@@ -0,0 +1,292 @@
+# oh-ascii — Deep Reference
+
+## When to Use
+
+Creating architecture diagrams, file trees, flowcharts, sequence diagrams, box-drawing layouts, blast radius visualizations, swimlane diagrams, or validating ASCII art alignment in documentation. All output renders in monospace terminals.
+
+## Phases
+
+Complete ASCII diagramming — three phases: **Design** (patterns & layout rules), **Generate** (PlantUML workflow), **Validate** (structural alignment checking).
+
+### Phase A: Design Patterns
+
+#### Box-Drawing Characters
+
+Use ONE set per diagram. Never mix.
+
+```
+default:   ┌─┐ │ └─┘  ├─┤ ┬ ┴ ┼
+emphasis:  ┏━┓ ┃ ┗━┛  ┣━┫ ┳ ┻ ╋
+title:     ╔═╗ ║ ╚═╝  ╠═╣ ╦ ╩ ╬
+soft:      ╭─╮ │ ╰─╯
+portable:  +-+ | +-+  +-+ + + +
+arrows:    → ← ↑ ↓ ─> <─ ──> <──
+blocks:    █ ▓ ░ ▏▎▍▌▋▊▉
+status:    ● ○ ✓ ✗ ⚠ ◆ ◇ ▶ ▷ ↑↓→ ▓▒░
+```
+
+| Set | Use |
+|-----|-----|
+| `default` ─│ | Most diagrams |
+| `emphasis` ━┃ | Headers, focus elements |
+| `title` ═║ | Section banners only |
+| `soft` ╭╮╰╯ ─│ | Status cards, ambient UI |
+| `portable` +-\| | CI/TTY fallback |
+
+Status glyphs (closed set): `● ○ ✓ ✗ ⚠ ◆ ◇ ▶ ▷  ↑ ↓ →  ▓ ░ ▒`
+
+#### Diagram Patterns
+
+##### Architecture
+
+```
+┌──────────────┐      ┌──────────────┐
+│   Frontend   │─────>│   Backend    │
+│   React 19   │      │   FastAPI    │
+└──────────────┘      └───────┬──────┘
+                              v
+                      ┌──────────────┐
+                      │  PostgreSQL  │
+                      └──────────────┘
+```
+
+##### File Trees with Annotations
+
+```
+src/
+├── api/
+│   ├── routes.py          [M] +45 -12    !! high-traffic
+│   └── schemas.py         [M] +20 -5
+├── services/
+│   └── billing.py         [A] +180       ** new
+└── tests/
+    └── test_billing.py    [A] +120       ** new
+
+Legend: [A]dd [M]odify [D]elete  !! Risk  ** New
+```
+
+##### Progress Bars, Swimlanes, Blast Radius, Comparisons, Reversibility
+
+**Progress**
+
+```
+[████████░░] 80% Complete
++ Design    (2d)   + Backend   (5d)
+~ Frontend  (3d)   - Testing   (pending)
+```
+
+**Swimlane**
+
+```
+Backend  ===[Schema]======[API]===========================[Deploy]====>
+                |            |                                ^
+                |            +------blocks------+             |
+Frontend -------[Wait]--------[Components]=======[Integration]=+
+
+=== active   --- blocked/waiting   | dependency
+```
+
+**Blast Radius (Concentric Rings)**
+
+```
+            Ring 3: Tests (8 files)
+       +-----------------------------------+
+       |    Ring 2: Transitive (5)          |
+       |   +----------------------------+   |
+       |   |  Ring 1: Direct (3)        |   |
+       |   |   +------------------+     |   |
+       |   |   |   CHANGED FILE   |     |   |
+       |   |   +------------------+     |   |
+       |   +----------------------------+   |
+       +-----------------------------------+
+```
+
+**Comparison (Before/After)**
+
+```
+BEFORE                          AFTER
+┌────────────────┐              ┌────────────────┐
+│   Monolith     │              │  Service A     │──┐
+│   (all-in-1)   │              └────────────────┘  │  ┌──────────┐
+└────────────────┘              ┌────────────────┐  ├─>│  Shared  │
+                                │  Service B     │──┘  │  Queue   │
+                                └────────────────┘     └──────────┘
+```
+
+**Reversibility Timeline**
+
+```
+Phase 1  [================]  FULLY REVERSIBLE    (add column)
+Phase 2  [================]  FULLY REVERSIBLE    (new endpoint)
+Phase 3  [============....]  PARTIALLY           (backfill)
+              --- POINT OF NO RETURN ---
+Phase 4  [........????????]  IRREVERSIBLE        (drop column)
+```
+
+##### Key Rules
+
+- **Font**: Monospace only — box-drawing requires fixed-width
+- **Arrows**: `->`, `-->`, or `|` with `v`/`^`
+- **Width**: Under 80 cols for terminal compat
+- **Nesting**: Max 3 levels
+- **Labels**: Short — long text breaks alignment
+- **Set consistency**: One set per diagram, never mixed
+
+### Phase B: Generation (PlantUML)
+
+Generate ASCII from `.puml` files. Requires PlantUML installed (`brew install plantuml`, `apt install plantuml`, or `java -jar plantuml.jar`).
+
+#### Workflow
+
+```
+plantuml -utxt diagram.puml           # Unicode (preferred)
+plantuml -txt diagram.puml             # Standard ASCII
+# Output: diagram.utxt or diagram.atxt
+```
+
+#### Templates (7 types)
+
+| Type | Description |
+|------|------------|
+| **Sequence** | Actor → System → DB interactions |
+| **Class** | Types, fields, methods, relationships |
+| **Activity** | Workflow branches, decision nodes |
+| **State** | State transitions, entry/exit, events |
+| **Component** | Service boundaries, dependencies |
+| **Use Case** | Actors, system boundary, use cases |
+| **Deployment** | Nodes, servers, databases, replicas |
+
+**Sequence Example**
+
+```plantuml
+@startuml
+actor User
+participant "Web App" as App
+database "Database" as DB
+
+User -> App : Login Request
+App -> DB : Validate Credentials
+DB --> App : User Data
+App --> User : Auth Token
+@enduml
+```
+
+**Component Example**
+
+```plantuml
+@startuml
+[Client] as client
+[API Gateway] as gateway
+[Service A] as svcA
+[Database] as db
+
+client --> gateway
+gateway --> svcA
+svcA --> db
+@enduml
+```
+
+**Activity Example (branching workflows)**
+
+```plantuml
+@startuml
+start
+:Initialize;
+if (Is Valid?) then (yes)
+  :Process Data;
+  :Save Result;
+else (no)
+  :Log Error;
+  stop
+endif
+:Complete;
+stop
+@enduml
+```
+
+**State Example (state transitions)**
+
+```plantuml
+@startuml
+[*] --> Idle
+Idle --> Processing : start
+Processing --> Success : complete
+Processing --> Error : fail
+Success --> [*]
+Error --> Idle : retry
+@enduml
+```
+
+#### CLI Options
+
+```
+plantuml -utxt -o ./output diagram.puml    # output dir
+plantuml -utxt ./diagrams/                  # batch dir
+plantuml -utxt -charset UTF-8 diagram.puml  # charset
+```
+
+### Phase C: Validation
+
+Validates structural alignment of box-drawing characters in markdown code blocks. Script bundled at `scripts/check_ascii_alignment.py`.
+
+#### Usage
+
+```bash
+python3 scripts/check_ascii_alignment.py docs/ARCHITECTURE.md    # single file
+python3 scripts/check_ascii_alignment.py docs/                    # batch dir
+python3 scripts/check_ascii_alignment.py docs/ --verbose          # show skipped blocks
+python3 scripts/check_ascii_alignment.py docs/ --warn-only        # warnings exit 0
+```
+
+#### Checks
+
+- **Vertical alignment** — connectors must match above/below
+- **Corner connections** — corners connect to adjacent lines
+- **Junction validity** — T-joins/crosses have correct connections
+- **Line continuity** — horizontals terminate at valid endpoints
+- **Box closure** — no dangling edges
+
+#### Output
+
+Compiler-like format:
+
+```
+file.md:45:12: error: vertical connector '|' at col 12 has no match above
+  -> Suggestion: Add '|', '├', '┤', '┬', or '┼' at line 44, col 12
+```
+
+| Level | Exit |
+|-------|------|
+| error | 1 |
+| warning | 2 (or 0 with --warn-only) |
+| info / clean | 0 |
+
+Validation scope: enclosed box diagrams in fenced code blocks. Skips file trees (`├──`). Detects all line weights (light, double, heavy, rounded).
+
+#### Integration
+
+```bash
+# Create → validate → fix → re-validate until clean
+python3 scripts/check_ascii_alignment.py docs/ARCHITECTURE.md
+```
+
+## Anti-patterns
+
+- Mixing character sets in one diagram
+- Tabs in diagrams — use spaces; tabs cause false positives
+- Deep nesting (4+ levels) — readability degrades past 3
+- Over-80-col diagrams — break into sections
+- Inline ASCII outside code blocks — always fence
+- PlantUML for one-off simple diagrams — manual ASCII is faster for <5 boxes
+
+## Troubleshooting
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| Garbled Unicode | Terminal lacks UTF-8 support | Ensure UTF-8 locale and monospace font |
+| Misaligned diagram | Wrong font or tab characters | Fixed-width font (Consolas, Courier, Monaco); convert tabs to spaces |
+| PlantUML command not found | Not installed | `java -jar plantuml.jar -txt` as fallback |
+| False positives from tabs | Tab characters misalign columns | Convert tabs to spaces before validation |
+| Diagram wrong but validator passes | Aesthetic spacing not structural | Validator checks structure, not visual alignment — review manually |
+| Validator skipping diagram | Not an enclosed box diagram | Ensure all 4 corners present (`┌┐└┘` or equivalent) |
+| Unicode chars not rendering | Terminal font missing glyphs | Use font with full box-drawing support (Cascadia Code, JetBrains Mono) |