docs: comprehensive documentation review with doc-manager#44
Merged
Conversation
- Initialize doc-manager configuration (.doc-manager.yml) - Initialize memory system for documentation tracking (767 files) - Configure docs_path to point to docs/ directory - Test convert one Hugo shortcode link to standard markdown - Verify standard markdown links work in Hugo (without .md extension) Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
- Convert relref shortcodes to standard markdown (without .md extension) - Add Hugo render hook for build-time link validation - Links now work on GitHub and in Hugo site - Render hook validates internal links at build time - Update doc-manager dependencies and conventions Benefits: - GitHub compatibility (links work in repository browser) - Hugo validation (render hook catches broken links) - doc-manager aware (though has limitations with Hugo paths) - Portable across markdown renderers Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
Replace emoji characters with text equivalents: - ✅ → [OK] - ❌ → [ERROR] -⚠️ → [WARNING] - 📦 → [PACKAGE] - ✓ → [PASS] - ✗ → [FAIL] Rationale: - Emojis cause UTF-8 encoding issues in tooling - Text equivalents are more professional - Improves compatibility across different systems and tools - 308 occurrences removed across 16 documentation files Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
- Initialize doc-manager with Hugo/Hextra platform detection - Configure source tracking (cmd/, internal/) and docs path (docs/) - Create baselines: repo checksums, code symbols, dependencies - Set up gitignore integration and Go language detection - Establish documentation mappings for CLI, API, config, dependencies, infrastructure Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Broken Links Fixed (4): - docs/03-reference/command-reference.md:143 - recovery-phrase.md path - docs/03-reference/security-architecture.md:274 - recovery-phrase.md path - docs/04-troubleshooting/vault.md:147 - recovery-phrase.md path - docs/06-development/contributing.md:472 - docs directory link Language Tags Added (62 code blocks): - command-reference.md: 18 blocks (text for output examples) - security-architecture.md: 6 blocks (text for cryptographic pseudocode) - health-checks.md: 12 blocks (text for diagnostic output) - basic-workflows.md: 2 blocks (text for workflow output) - keychain-setup.md: 1 block (text for symptom display) - tui-guide.md: 1 block (text for usage format) - security-operations.md: 2 blocks (text, ini for .gitignore) - branch-workflow.md: 4 blocks (text for CI/CD diagrams) - contributing.md: 1 block (text for project structure) - documentation-lifecycle.md: 4 blocks (text for commit formats) Validation: Error count reduced from 382 to 317 issues Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Configuration Updates: - Update sources to use glob patterns (cmd/**/*.go, internal/**/*.go, *.go) - Fix doc_mappings paths to match numbered directory structure - cli: docs/03-reference/command-reference.md - api: docs/03-reference/security-architecture.md - config: docs/03-reference/configuration.md - dependency: docs/01-getting-started/manual-install.md - infrastructure: docs/06-development/ci-cd.md Baseline Regeneration: - Created symbol-baseline.json (591 symbols tracked) - Updated repo-baseline.json (322 files tracked) - Updated dependencies.json (0 dependencies) This addresses the missing symbol-baseline.json file that should have been created during initial setup. Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Exclusion Updates: - Added specs/* (development specifications) - Added .specify/* (Speckit framework files) - Added .spec-workflow/* (spec workflow data) Baseline Impact: - Files tracked reduced: 322 → 126 (excluded 196 spec files) - Symbol tracking unchanged: 591 symbols - Breakdown: 38 docs, 40 cmd, 30 internal, 9 root files This focuses documentation tracking on actual source code and documentation files, excluding internal development artifacts. Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Link Fix: - contributing.md:472: Changed [docs/](/) to [docs/](../_index.md) - Hugo-compatible relative link to documentation index Doc Conventions Updates: - Changed heading case: sentence_case → title_case - Changed max depth: 3 → 6 - Aligns config with actual documentation style These changes match the existing documentation conventions rather than imposing arbitrary style rules. Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Reverted case: title_case -> sentence_case Analysis showed documentation uses sentence case headings (e.g., "Getting started", "Initialize vault") not title case. Changing to title_case created 127 new validation warnings. Impact: - Validation warnings: 207 -> 153 (eliminated 54 warnings) - Baselines resynced Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Fixed 30 heading case inconsistencies across 10 documentation files: Files modified: - 01-getting-started/manual-install.md - 02-guides/backup-restore.md - 03-reference/command-reference.md (11 headings) - 03-reference/migration.md (Q&A section) - 03-reference/security-architecture.md - 05-operations/health-checks.md - 06-development/branch-workflow.md (10 headings) - 06-development/scoop.md - docs/README.md - docs/_index.md Changes include: - Fixed prepositions: "from" → "From", "with" → "With" - Fixed Q&A headings to Title Case - Fixed compound verbs: "back up" → "Back Up" - Standardized frontmatter titles Validation: 112 → 82 warnings (27% reduction) Remaining: Mostly YAML frontmatter titles on line 2 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
- Add api_coverage section with go-test preset to .doc-manager.yml - Enable include_root_readme for root README validation - Add brand name exceptions (macOS, iOS, GoReleaser, etc.) to doc-conventions.yml - Fix code block language tag in README.md (ASCII art) - Fix heading case "using" -> "Using" in manual-install.md - Update all baselines to current state 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
- Add exclude_symbols for internal data structures (25+ types) - Keep tracking for Config and TerminalConfig only (user-facing) - Excludes: Credential, VaultData, HealthReport, CheckResult, etc. - Update baselines to reflect new focused tracking 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
- migration.md: Remove invalid --config flag references, update version refs from "January 2025" to "v0.3.0", condense unimplemented migrate command documentation - recovery-phrase.md: Fix --config flag usage in test recovery example - command-reference.md: Fix 2 sentence-case headings to Title Case - README.md: Remove duplicate "Getting Help" section - Update doc-manager baselines 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
- Add proper ### doctor section with synopsis, flags, examples, exit codes - Add proper ### tui section with synopsis, features, keyboard shortcuts - Clean up malformed orphaned content after verify-audit section - Add Troubleshooting subsection for doctor/tui FAQs - Update doc-manager baselines 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
- Add missing list flags: --by-project, --location, --recursive - Add missing category field option to get --field - Add missing delete command aliases: rm, remove - Add missing doctor --verbose flag - Fix config reset docs (no --force flag, auto-backup behavior) - Fix version docs (always shows build details, no --verbose flag) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
- Remove "January 2025" references from command-reference, security-architecture, configuration, and security-operations docs - Update migration guide to use v0.3.0 instead of "January 2025 release" - Date-based version references are less maintainable than semantic versions 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
- Symlink docs/README.md -> _index.md (single source of truth) - Move documentation-lifecycle.md to specs/ (internal governance, not user docs) - Remove GitHub Actions version list from ci-cd.md (stale immediately, check workflows for truth) - Remove "Future Enhancements" wishlist from ci-cd.md (belongs in issue tracker) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Updated baselines after plugin upgrade - now correctly tracking 574 dependencies. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Comprehensive documentation review using the doc-manager plugin to identify and fix gaps, inaccuracies, and irrelevant content.
Changes
CLI documentation gaps fixed:
listflags:--by-project,--location,--recursivecategoryfield option toget --fielddeletecommand aliases:rm,removedoctor --verboseflagconfig resetdocs (removed non-existent--forceflag)versiondocs (removed non-existent--verboseflag)Date references replaced with version numbers:
Irrelevant content removed:
docs/README.md→_index.md(single source of truth)documentation-lifecycle.mdtospecs/(internal governance, not user docs)doc-manager baselines updated:
Test plan
🤖 Generated with Claude Code