Skip to content

fix(guide): stop sync-html-content duplicating the Rust prerequisite row - #49

Merged
ihmaws merged 2 commits into
mainfrom
dev/ihmaws/guide-rust-row-idempotency
Oct 20, 2026
Merged

ihmaws merged 2 commits into
mainfrom
dev/ihmaws/guide-rust-row-idempotency

Conversation

@ihmaws

@ihmaws ihmaws commented Oct 14, 2026 •

Copy link
Copy Markdown
Member

Description

Docs tooling (tools/build-user-guide/):

  • html_sop_edits.py: the "essentials gains a Rust row" append now inserts the final "Built from a clone of the repository…" text. This makes it the only edit that owns the row.
  • sync-html-content.py: removed the "qs prereq row: release framing" substitution. It rewrote the text the append had just inserted, so the append's already-applied check never matched and every --apply added another row.
  • sync-html-content.py: --apply now refuses to write a result that a second pass would change, and names the edits still firing. This catches any pair of edits that undo each other, not just this one.
  • sync-html-content.py, html_sop_edits.py: renamed claude-sonnet-5 to claude-sonnet-5.5 in the edit tables. chore(agents): move every agent to claude-sonnet-5.5 #50 moved the HTML to the new model but not these edits, so 17 targets stopped matching and make guide-html refused to write.

Docs:

  • docs/index.html and docs/site/user-guide.html: two sentences chore(agents): move every agent to claude-sonnet-5.5 #50 missed ("Every agent runs claude-sonnet-5…") now say claude-sonnet-5.5, matching agents.md and reference.md. Also removed the 4 extra "A Rust toolchain" rows (5 → 1). The decoded page diff against main only removes lines.

Fixes #48

Type of Change

  • Documentation
  • Other: user-guide build tooling (tools/build-user-guide/)

Testing

  • sync-html-content.py --apply run 3 times in a row: the first run inserted the single row, and the next two report "no change" for both bundles, which stay byte-identical.
  • The new guard, run against main's bundle with the old edit table, refuses to write and names qs prereq row: release framing.
  • After rebasing onto chore(agents): move every agent to claude-sonnet-5.5 #50, the full sync-html-content.py --apply runs clean on both bundles, and a second run reports "no change".
  • No claude-sonnet-5 (without .5) is left in either bundle, and they stay byte-identical.
  • Rendered docs/index.html locally: Prerequisites → The essentials shows one "A Rust toolchain" row above "A terminal".

Checklist

  • My code follows the style guidelines of this project (see AGENTS.md's Code Style & Conventions)
  • I have performed a self-review of my own changes
  • I have commented my code where necessary

Notes for Reviewers

  • These existing failures are also on origin/main and are left out of scope:
    • build-user-guide.sh --check fails because feat: publish Konductor as a Claude Code plugin marketplace #28 changed docs/user-guide/**/*.md without regenerating the HTML. This PR leaves the manifest unchanged.
    • make guide-check reports one failure: "config is listed as withdrawn… but cli/README.md no longer declares it".
  • Follow-up: the prerequisites row and quick start step 1 still say to build from a clone, but releases are published (v1.0.0–v1.0.3) and the README offers a binary install. Rewording that across the Markdown and HTML is a separate change.

@ihmaws
ihmaws marked this pull request as ready for review October 14, 2026 15:16
knihit
knihit previously approved these changes Oct 15, 2026

@knihit knihit left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

A substitution rewrote the text that the Rust-row append inserts, so the
append's already-applied check never matched and every --apply added
another row (5 on main). The append now inserts the final text and the
substitution is gone; the committed bundles are cleaned to one row.

--apply now refuses to write a result that a second pass would change,
naming the edits still firing.

Fixes #48
@ihmaws
ihmaws force-pushed the dev/ihmaws/guide-rust-row-idempotency branch from 5440011 to ff44ad4 Compare October 16, 2026 11:58
#50 moved the HTML to claude-sonnet-5.5 but not the edit tables, so 17
targets stopped matching and --apply refused to write. Two sentences #50
missed in the bundles still named claude-sonnet-5; they now match the
Markdown.
@ihmaws
ihmaws requested a review from knihit October 16, 2026 17:46

@knihit knihit left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@ihmaws
ihmaws merged commit ae2098a into main Oct 20, 2026
7 checks passed
@ihmaws
ihmaws deleted the dev/ihmaws/guide-rust-row-idempotency branch October 20, 2026 17:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

User doc builder duplicating rust toolchain entry

3 participants