hermes - ✅(Solved) Fix [Bug]: generate-skill-docs.py produces ASCII-guard-failing output for 2 bundled skills (blocks all website PRs) [1 pull requests, 1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
NousResearch/hermes-agent#15305Fetched 2026-04-25 06:23:02
View on GitHub
Comments
1
Participants
2
Timeline
6
Reactions
0
Author
Timeline (top)
labeled ×4commented ×1cross-referenced ×1

Fix Action

Fixed

PR fix notes

PR #15260: fix(docs): add ┴ junctions to two outer-box bottom borders to satisfy ascii-guard

Description (problem / solution / changelog)

What does this PR do?

Fixes 6 pre-existing ascii-guard 2.3.0 warnings that currently block the `docs-site-checks` CI on every PR touching `website/**`.

  • `website/docs/developer-guide/architecture.md` — 3 warnings on the bottom border of the outer AIAgent box (line 38)
  • `website/docs/developer-guide/gateway-internals.md` — 3 warnings on the bottom border of the outer GatewayRunner box (line 49)

Both diagrams have a two-row nested-box pattern where the first inner-box row's bottom uses `┬` to connect downward to a second inner-box row. ascii-guard's `validate_box()` routine looks for `┬`/`┼` characters anywhere in the outer box's content lines (not just in its top border) via `get_column_positions()` and concludes those are table-column boundaries belonging to the outer box. It then expects a matching `┴` in the outer box's bottom border — and warns when it finds `─` instead. That interpretation is wrong for this geometry (the `┬` is a purely internal inner-box-to-inner-box connection), but the linter rule is what it is, and the fix is trivial: add `┴` at the three flagged columns of each outer bottom border.

After the fix, the `┴` reads visually as "the column space continues past this box," which matches the arrows already sitting below each outer box. No readability regression.

Related Issue

No existing issue — noticed while filing #15214 (docs cookbook). Verified the warnings are pre-existing on `main` (`architecture.md` last touched in #11373, `gateway-internals.md` much older).

Fixes #

Type of Change

  • 🐛 Bug fix (non-breaking change that fixes an issue) — unblocks `docs-site-checks` CI
  • ✨ New feature
  • 🔒 Security fix
  • 📝 Documentation update
  • ✅ Tests
  • ♻️ Refactor
  • 🎯 New skill

Changes Made

  • `website/docs/developer-guide/architecture.md` line 38: positions 11, 29, 47 (1-indexed) on the outer bottom border changed from `─` to `┴`. Those positions line up with the `┬` junctions on line 30 that connect the "Prompt Builder / Provider Resolution / Tool Dispatch" row to the "Compression / 3 API Modes / Tool Registry" row below.
  • `website/docs/developer-guide/gateway-internals.md` line 49: positions 9, 23, 37 (1-indexed) on the outer bottom border changed from `─` to `┴`. Those positions line up with the `┬` junctions on line 35 that connect the "Telegram / Discord / Slack Adapter" row to the `_handle_message()` merge below.

Diff: 2 files changed, 2 insertions(+), 2 deletions(-) — every changed character is a single Unicode swap.

How to Test

Validated locally against ascii-guard 2.3.0 (same version the CI workflow installs via `python -m pip install ascii-guard==2.3.0`).

Before (on clean `upstream/main`): ``` $ ascii-guard lint website/docs/developer-guide/architecture.md Checking .../architecture.md... Found 10 ASCII box(es) ⚠ Line 39, Col 12: Bottom border missing junction point at column 11 (expected ┴, got '─') ⚠ Line 39, Col 30: Bottom border missing junction point at column 29 (expected ┴, got '─') ⚠ Line 39, Col 48: Bottom border missing junction point at column 47 (expected ┴, got '─')

$ ascii-guard lint website/docs/developer-guide/gateway-internals.md Checking .../gateway-internals.md... Found 4 ASCII box(es) ⚠ Line 50, Col 10: Bottom border missing junction point at column 9 (expected ┴, got '─') ⚠ Line 50, Col 24: Bottom border missing junction point at column 23 (expected ┴, got '─') ⚠ Line 50, Col 38: Bottom border missing junction point at column 37 (expected ┴, got '─') ```

After (on this branch): ``` $ ascii-guard lint website/docs/developer-guide/architecture.md Checking .../architecture.md... Found 10 ASCII box(es) ✓ No issues found ✓ Errors: 0

$ ascii-guard lint website/docs/developer-guide/gateway-internals.md Checking .../gateway-internals.md... Found 4 ASCII box(es) ✓ No issues found ✓ Errors: 0 ```

No other files changed. Other pre-existing ascii-guard findings on committed-but-regenerated-in-CI skill-docs (`skills/bundled/research/research-research-paper-writing.md`, `skills/bundled/mlops/mlops-models-segment-anything.md`) are out of scope for this PR — CI runs `generate-skill-docs.py` before the lint step, which overwrites those files with clean output, so they don't actually fail CI.

Checklist

Code

  • I've read the Contributing Guide
  • My commit messages follow Conventional Commits (`fix(docs): …`)
  • I searched for existing PRs — nothing duplicative
  • My PR contains only changes related to this fix (2 `─` → `┴` swaps on 2 lines)
  • I've run `pytest tests/ -q` — N/A for a docs-only change to 2 markdown files; the Python test suite does not exercise these files
  • I've added tests — N/A, existing CI `docs-site-checks` workflow is the regression guard
  • I've tested on my platform: macOS 15 / darwin-arm64, ascii-guard 2.3.0

Documentation & Housekeeping

  • Documentation (README, `docs/`, docstrings) — this PR IS a docs fix
  • `cli-config.yaml.example` — N/A
  • `CONTRIBUTING.md` or `AGENTS.md` — N/A
  • Cross-platform impact considered — ASCII art renders identically on all platforms
  • Tool descriptions/schemas — N/A

For New Skills

N/A.

Screenshots / Logs

The 3 `┴` characters on `architecture.md` line 38 now align with the `┬` connectors on line 30 (same columns: 11, 29, 47). Same pattern for `gateway-internals.md`.

Unblocks #15214 (and every other open PR touching `website/**`) from the same CI failure.

Changed files

  • website/docs/developer-guide/architecture.md (modified, +1/-1)
  • website/docs/developer-guide/gateway-internals.md (modified, +1/-1)

Code Example

git clone https://github.com/NousResearch/hermes-agent
cd hermes-agent
python3 website/scripts/extract-skills.py
python3 website/scripts/generate-skill-docs.py
pip install ascii-guard==2.3.0
cd website && ascii-guard lint docs

---

Line 46, Col 63: Right border missing: line too short
Line 54, Col 63: Right border missing: line too short
Line 157, Col 20: Line has extra characters after right border (length 67, expected 19)
Line 157, Col 44: Line has extra characters after right border (length 67, expected 43)
Errors: 4

Summary:
  Files checked: 262
  Boxes found: 29
exit 1

---

{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
RAW_BUFFERClick to expand / collapse

Bug Description

`website/scripts/generate-skill-docs.py` — the CI step that regenerates per-skill docs pages from `skills//SKILL.md` before the ascii-guard lint runs — produces output that fails ascii-guard validation for two bundled skills. This causes every PR touching `website/` to fail the `docs-site-checks` workflow with 4 errors, independent of what the PR actually changes.

First observed today (2026-04-24) on my PRs #15214 and #15260. Same failure reproduces on a clean `main` checkout locally.

Steps to Reproduce

git clone https://github.com/NousResearch/hermes-agent
cd hermes-agent
python3 website/scripts/extract-skills.py
python3 website/scripts/generate-skill-docs.py
pip install ascii-guard==2.3.0
cd website && ascii-guard lint docs

Expected Behavior

ascii-guard lint docs exits 0 on a clean main checkout.

Actual Behavior

✗ Line 46, Col 63: Right border missing: line too short
✗ Line 54, Col 63: Right border missing: line too short
✗ Line 157, Col 20: Line has extra characters after right border (length 67, expected 19)
✗ Line 157, Col 44: Line has extra characters after right border (length 67, expected 43)
✗ Errors: 4

Summary:
  Files checked: 262
  Boxes found: 29
exit 1

The failing files:

  • website/docs/user-guide/skills/bundled/research/research-research-paper-writing.md — 2 errors at lines 46 and 54 (box right-border truncation)
  • website/docs/user-guide/skills/bundled/mlops/mlops-models-segment-anything.md — 2 errors at line 157 (extra chars after right border)

Both files start with the auto-generated header:

{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}

So the fix needs to live in either:

  1. generate-skill-docs.py — the rendering logic that's producing the malformed ASCII boxes (box width computed from a different field than what it emits into the output?)
  2. The source SKILL.md filesskills/research/research-paper-writing/SKILL.md and skills/mlops/models/segment-anything/SKILL.md — if they contain ASCII art with wrong dimensions that the generator copies verbatim.

Skimmed the source files; neither contains ASCII boxes at line 46/54/157 matching the errors. That points at (1) — the generator is synthesizing boxes from metadata and getting the dimensions wrong.

Affected Component

  • Documentation / website tooling (generate-skill-docs.py)
  • CI (Docs Site Checks workflow)

Messaging Platform

N/A (CI only).

Environment

  • GitHub-hosted ubuntu-latest runners (CI) and locally (macOS 15 arm64, Python 3.11, ascii-guard 2.3.0) — both reproduce.

Debug Report Links

N/A — build-side issue.

Suggested Remediation

  • Regenerate both files locally (python3 website/scripts/generate-skill-docs.py), inspect the generated ASCII at the cited line/col positions, and identify which code path in the generator is emitting a mis-dimensioned box.
  • Likely candidates: the box-width computation for a tool/command/option summary, or a template that emits a fixed-width header without truncating long labels.
  • Once the generator fix is in, the CI's existing regenerate-then-lint sequence will clean the output without needing the committed files in the repo to change.

Impact / Urgency

Every PR touching `website/**` currently fails `docs-site-checks` with `Errors: 4`, regardless of what it changes. Observed at filing on #15214 (my docs cookbook) and #15260 (my ascii-guard fix for architecture.md / gateway-internals.md warnings — those warnings are now cleared but the generator-side errors remain, so the check still fails).

Related

  • #15272 — `Nix CI broken on main` (separate master regression blocking the same set of PRs from a different angle)
  • #15260 — my PR that cleared the 6 unrelated ascii-guard warnings on `architecture.md` and `gateway-internals.md`
  • #15214 — my docs cookbook, blocked by this + #15272

extent analysis

TL;DR

The most likely fix involves modifying the generate-skill-docs.py script to correctly compute and emit ASCII box dimensions.

Guidance

  • Inspect the generated ASCII art at the cited line and column positions in the affected files to identify the mis-dimensioned boxes.
  • Review the generate-skill-docs.py script, focusing on box-width computation for tool/command/option summaries and templates that emit fixed-width headers.
  • Verify that the script correctly truncates long labels to prevent extra characters after the right border.
  • Test the modified script by regenerating the affected files and running ascii-guard lint docs to ensure the errors are resolved.

Example

No code snippet is provided as the issue does not contain sufficient information to create a specific example.

Notes

The fix may require adjustments to the generate-skill-docs.py script, and it is essential to test the changes thoroughly to ensure the ASCII art is generated correctly.

Recommendation

Apply a workaround by modifying the generate-skill-docs.py script to correctly compute and emit ASCII box dimensions, as this is the most likely cause of the issue.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

hermes - ✅(Solved) Fix [Bug]: generate-skill-docs.py produces ASCII-guard-failing output for 2 bundled skills (blocks all website PRs) [1 pull requests, 1 comments, 2 participants]