Skip to content

docs: breadcrumbs, validation block, and mkdocs config improvements#482

Merged
Data-Wise merged 19 commits into
mainfrom
dev
Jun 30, 2026
Merged

docs: breadcrumbs, validation block, and mkdocs config improvements#482
Data-Wise merged 19 commits into
mainfrom
dev

Conversation

@Data-Wise

Copy link
Copy Markdown
Owner

Summary

  • Breadcrumbs + instant prefetch (navigation.path, navigation.instant.prefetch) added to mkdocs.yml
  • Validation block (validation.nav.omitted_files: warn, validation.links.anchors: warn) now surfaces silent build issues
  • not_in_nav block marks ATLAS-CONTRACT.md and adhd template files as intentionally out of nav (accessible via links, not in sidebar)
  • Glob bug fix: internal/*.md narrowed to the specific file — Python fnmatch treats * as matching path separators, silently excluding public pages under internal/conventions/
  • Broken link fix in EMAIL-DISPATCHER-GUIDE.md: removed reference to an excluded file
  • Contributing docs updated: fix incorrect mkdocs gh-deploy --force instruction; add not_in_nav guidance
  • Style guide updated: add MkDocs Configuration section (validation, not_in_nav vs exclude, fnmatch footgun, breadcrumbs)
  • Also includes tok mint feature (GitHub App installation tokens, PR feat: tok mint — generate GitHub App installation tokens locally #480 already merged to dev)

Also includes (from dev)

Commit Summary
feat: tok mint Generate short-lived ghs_ GitHub App tokens locally
chore(zshrc) Remove duplicate PATH, comment out antigravity hooks

Test plan

  • mkdocs build — no warnings output
  • mkdocs serve — breadcrumbs visible above page titles in docs
  • Links to ATLAS-CONTRACT.md and adhd templates still resolve (not_in_nav keeps them in site)
  • CI (ZSH Plugin Tests + Full Test Suite) passes

🤖 Generated with Claude Code

Test User and others added 19 commits June 19, 2026 11:24
Adds SPEC-flow-claude-v2.md covering:
- C4 two-tier threshold (warn >100, error >180)
- C7: per-project CLAUDE.md line count + version drift
- C8: orphaned ~/.claude/projects/ memory dirs
- C9: unreferenced rules in ~/.claude/rules/
- C10: hooks in settings.json pointing to missing scripts
- C11: plugin dirs missing valid plugin.json
- flow claude watch: 30-min background daemon, terminal-notifier on
  WARN/ERROR state change, --stop/--status subcommands

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* chore: add ORCHESTRATE plan for flow claude v2

C4 two-tier fix + C7-C11 new checks + flow claude watch daemon.
5-wave implementation plan with test list and verification steps.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(claude): C4 two-tier + C7-C11 checks + watch daemon

Extends `flow claude check` with:
- C4 two-tier threshold: >100 lines → WARN, >180 → ERROR
- C7 per-project CLAUDE.md audit (line count + version drift)
- C8 orphaned memory dir detection (slug decode)
- C9 rules drift (unreferenced rules in CLAUDE.md)
- C10 missing hook file detection from settings.json
- C11 plugin.json health check
- `flow claude watch [--interval N] [--stop] [--status]`
  background daemon with desktop notifications on state change

Tests: 39 passed, 6 skipped (tool-absent), 0 failed

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(claude): Wave 5 — CHANGELOG, test counts, completions for v7.13.0

- CHANGELOG.md + docs/CHANGELOG.md: [Unreleased] section documenting
  C4 two-tier, C7-C11 checks, and flow claude watch daemon
- CLAUDE.md: 218→219 test files, 66/66→67/67 suites
- docs/guides/TESTING.md: 218→219 test files (table + footer)
- completions/_flow: watch subcommand + options (--interval, --stop, --status)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Test User <test@example.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
…h daemon

Add C7-C11 rows to the checks table (per-project CLAUDE.md, orphaned
memory dirs, rules drift, missing hook files, plugin health), update C4
to show the two-tier threshold (>100 WARN, >180 ERROR), and add Watch
Daemon section covering flow claude watch --interval/--stop/--status.
Mirror all changes in tutorial 49. Bump both to v7.13.0.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Fixes MD040 markdownlint errors introduced by the C7-C11/watch daemon
doc update — 14 output blocks in tutorial 49 and 1 in the commands
page were missing the text language specifier. Also fixes MD049
underscore emphasis → asterisk.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- flow.plugin.zsh, package.json, CLAUDE.md, man pages → 7.13.0
- CHANGELOG.md + docs/CHANGELOG.md: 7.13.0 date stamped (2026-06-19)
- docs/CHANGELOG.md: inserted missing 7.12.0 entry
- MASTER-DISPATCHER-GUIDE.md: version footer → v7.13.0
- .STATUS: phase → Release Pending (v7.13.0)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
IM6 is deprecated (EOL, disabled 2029-04-01) and nothing in the
environment calls `convert` with image flags. Uninstalled the formula;
`convert` now resolves to IM7.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds tok mint subcommand to generate short-lived ghs_ tokens from a
GitHub App stored in Keychain. Includes:

- _tok_mint(): main function with --org, --dry-run, --verbose flags
- _tok_mint_jwt(): RS256 JWT signing via openssl dgst -sha256 -sign
- _tok_mint_setup(): interactive wizard for Keychain credential storage
- Help text, man page, completions, and full documentation
- All 14 existing tok tests continue to pass

Closes #479
feat: tok mint — generate GitHub App installation tokens locally
CLAUDE_CODE_MAX_OUTPUT_TOKENS moved to settings.json (already set there).
Duplicate /opt/homebrew/bin PATH entry (Qwen installer artifact) removed.
Antigravity workflow hooks commented out pending decision on whether to keep.
…o mkdocs

- Add navigation.instant.prefetch for hover-prefetch
- Add navigation.path for breadcrumb trail in deep nav
- Add validation.nav.omitted_files and validation.links.anchors warnings

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Replace overly-broad 'internal/*.md' glob with specific file exclusions
  (Python fnmatch '*' matches '/' so it was excluding adhd/ subdirs too)
- Add not_in_nav for ATLAS-CONTRACT.md (linked by 6 docs, just not in nav)
  and adhd template files (reachable via Documentation Templates page)
- Remove broken link to excluded EM-V2-ARCHITECTURE.md from email guide

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…n contributing guides

- CONTRIBUTING.md: fix incorrect mkdocs gh-deploy step (auto-deploy via CI, not manual); add not_in_nav guidance linking to style guide; add warning about blocking manual gh-deploy
- DOCUMENTATION-STYLE-GUIDE.md: add MkDocs Configuration section covering validation block, not_in_nav vs exclude, fnmatch footgun, and breadcrumbs; update --strict reference to mkdocs build
- CHANGELOG (root + docs): add Unreleased entries for breadcrumbs, prefetch, validation block, not_in_nav, and bug fixes applied in prior commits

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@Data-Wise Data-Wise merged commit 2623e77 into main Jun 30, 2026
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.

1 participant