update-docs

# Update Wiki Docs Read markdown files in the `wiki/` folder, fix markdown syntax issues, and improve readability without changing technical intent. ## When To Use - The user asks to clean, polish, or normalize markdown docs in `wiki/` - Headings/lists/code fences/tables render incorrectly - Documentation is hard to scan due to long paragraphs or inconsistent structure - A doc needs editorial cleanup before sharing or release ## Scope Primary scope: - Files under `wiki/**/*.md`, but can be used on any markdown file in the repo if specified by the user - Skip any files starting with `_` (e.g. `_footer.md`) or non-markdown files (e.g. `LICENSE.txt`) to avoid unintended edits to non-doc files or templates. Baseline actions: - Correct markdown syntax - Correct general readability issues - Run link integrity pass for obvious broken links and anchors - Normalize heading hierarchy and section flow - Add or correct code block language tags when known Expanded actions (when user allows full pass): - Improve list/table/code-block consistency - Standardize terminology and naming across the document - Flag stale or unverifiable claims for follow-up ## Style Rules - Write in concise technical style that remains approachable to non-expert users - Prefer short to medium sentences; avoid unnecessary long sentences - Explain terms briefly when first used if they may be unfamiliar - Avoid unexplained jargon and acronym-heavy phrasing - Keep wording direct, specific, and neutral ## Safety Rules - Preserve technical meaning and factual content - Do not invent commands, API behavior, or version claims - Keep edits narrow and reversible - Preserve existing project-specific terminology unless clearly inconsistent - If uncertainty is high, prefer adding a short clarification request over guessing ## Procedure ## Validation Tool Use the repo-local validation script before and after doc edits when possible: - `test/check-docs` to validate all wiki markdown files - `test/check-docs wiki/File.md` to validate one or more specific files - `test/check-docs --fix wiki/File.md` only when a safe markdownlint auto-fix is appropriate ### 1. Confirm Target Extract from user prompt: - target markdown file(s) in `wiki/` - constraints (tone, audience, preserve wording, max rewrite level) If targets are missing, ask for paths before editing. ### 2. Confirm Depth Extract from user prompt: - desired depth mode: - syntax-only: fix markdown syntax/rendering issues only; do not rewrite wording or structure beyond what syntax requires - readability: include syntax fixes plus clarity and scanability edits without broad restructuring - full pass: include syntax, readability, structure normalization, terminology consistency, and broader doc cleanup If depth is missing, default to readability and state that assumption. ### 3. Read And Diagnose For each target file: - If the scope is broad or unclear, run `test/check-docs` first to establish the current markdown baseline. - Scan for syntax/rendering issues - Identify readability pain points (dense blocks, weak headings, mixed terminology) - Note risky sections where edits may alter meaning ### 4. Normalize Heading Hierarchy Apply heading structure rules before deep rewrites: - keep one logical top-level heading per file where appropriate - avoid skipped levels (`##` directly to `####`) unless source constraints require it - ensure sibling sections use consistent levels - rename headings only when it improves clarity without changing meaning ### 5. Apply Syntax Fixes First Fix rendering/correctness issues first, such as: - broken heading levels - malformed lists - unclosed/misfenced code blocks - malformed links/images - inconsistent table delimiter rows - accidental HTML/markdown mixing that breaks rendering ### 6. Apply Readability Improvements Make editorial improvements while preserving meaning: - split long paragraphs - convert prose enumerations into lists when clearer - improve section titles for scanability - remove repetition and tighten wording - align terminology within the same document Apply tone constraints during edits: - concise technical phrasing - approachable wording for normal users - no unexplained technical babble ### 7. Run Link Integrity Pass Check and fix obvious link issues: - malformed inline/reference links - anchors that no longer match heading text after edits - obvious relative-path mistakes in wiki cross-links If link targets cannot be verified from repo context, keep the original target and flag it in the report. ### 8. Add Code Block Language Tags For fenced code blocks: - add language tags when confidently inferable (`bash`, `python`, `json`, `yaml`, etc.) - correct clearly wrong tags - leave tag blank only when language cannot be inferred safely ### 9. Run Completion Checks Validate each edited file against this checklist: - `test/check-docs` or `test/check-docs <file...>` passes for the affected scope - markdown renders correctly - heading hierarchy is logical - code fences include language where known - links/anchors are internally consistent and obviously valid - no factual changes introduced - tone is concise, technical, and approachable ### 10. Report Results Return: - files edited - categories of changes made (syntax/readability/structure) - any unresolved ambiguity or potential factual follow-ups ## Branching Guidance - If the user asks minimal edits, still run heading normalization, link integrity checks, and code-block language tagging with minimal wording changes. - If the user asks broad cleanup, run full pass including structure and terminology normalization. - If a section appears technically outdated but cannot be verified from repo context, do not rewrite claims; flag it in the report. ## Pass Criteria A successful pass means: - requested wiki markdown files were edited - syntax/rendering issues were corrected - heading hierarchy was normalized - link integrity pass was completed - code block language tagging was applied where known - readability clearly improved without changing intent - output report summarizes edits and open follow-ups