repo-visibility-audit

name

repo-visibility-audit

description

Audits the public-facing surface of w7-knowbase — README.md, CLAUDE.md, CHANGELOG.md, the site pages (index.html, architectures/*.html, reference/*.html), and .stitch/DESIGN.md. Detects broken internal links, dead anchors, navigation drift (orphan/dangling pages), README↔site drift, missing bilingual (HU/EN) coverage, broken asset references, and stale pages. Read-only — produces a scannable report. Triggers on "audit the README", "check the docs", "find broken links", "find orphan pages", "/repo-visibility-audit". Do NOT use for code review, design work, or rewriting content.

repo-visibility-audit

Read-only audit of the w7-knowbase public-facing surface — the docs and the static site itself. You print a scannable report. You NEVER edit files.

Scope

Audit ONLY these paths:

• Root: README.md, CLAUDE.md, CHANGELOG.md
• index.html
• architectures/*.html
• reference/*.html
• .stitch/DESIGN.md

Skip everything else — .claude/, .github/, assets/ source, and the git-ignored oldsite/ and .feature/ trees.

Procedure

1. Build the scope list:

   ls README.md CLAUDE.md CHANGELOG.md .stitch/DESIGN.md index.html 2>/dev/null
   find architectures reference -name '*.html' 2>/dev/null
   

2. For each HTML page, extract: href/src attributes, id anchors, and lang="hu" / lang="en" markers.
3. For each markdown file, extract: links ](path), headings, image refs.
4. Run checks 1–7 below.
5. Use git log -1 --format=%cs -- <file> per file for freshness.

Checks

1. Broken internal links / anchors — resolve every relative href, src, and ](path) against the source file. Resolve every #anchor against the target page's id set. Miss = ❌.
2. Navigation integrity — collect the nav link set (from the site nav / the NAV_DATA JS array if present). Every .html in architectures/ and reference/ should appear in the nav → on-disk-but-not-in-nav = ⚠️ ORPHAN; in-nav-but-no-file = ❌ DANGLING.
3. Bilingual coverage — every page must contain both lang="hu" and lang="en" markup. A page missing one language = ❌. Spot-check for bare user-visible strings with no language span = ⚠️.
4. README ↔ site drift — every architecture/reference page named in README.md must exist on disk (missing = ❌); every shipped page should be discoverable from the README (undocumented = ⚠️).
5. Asset references — every src/href into assets/** must resolve to a file that exists. Miss = ❌.
6. Stale pages — now - git-mtime > 180 days → ⚠️ STALE.
7. 30-second pitch — extract README.md's first ~150 words. Subjective ✅ / ⚠️ on whether they answer "what is this site and who is it for?".

Report format

Use .claude/rules/output-formatting.md exactly:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  🔍 Repo-Visibility Audit
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 Internal links & anchors
  ✅ index.html — 18/18 links resolve
  ❌ architectures/graph-rag.html:142 — href to ../reference/missing.html not found

📋 Navigation integrity
  ⚠️ reference/reranking.html — on disk but not in site nav

📋 Bilingual coverage
  ❌ architectures/raptor.html — no lang="en" markup found

📋 README ↔ site drift
  ⚠️ reference/hybrid-search.html shipped but not linked from README.md

📋 Asset references
  ✅ all assets/** references resolve

📋 Stale pages (>180 days)
  ⏭️ none

📋 30-second pitch
  ✅ README opens with a clear value statement

────────────────────────────────────────────
  ❌ Result: NOT CLEAN — 2 errors, 2 warnings
────────────────────────────────────────────

👉 Next steps:
  1. Fix broken href at `architectures/graph-rag.html:142`
  2. Add `reference/reranking.html` to the site nav
  3. Add an `lang="en"` variant to every string in `architectures/raptor.html`

Constraints

• Read-only. If a check needs to write, ABORT with ❌ Tool restriction violated.
• Cap output at 80 lines. If more findings, append (+N more) footer.
• Do NOT call the network — this site has no badges or external probes.
• Do NOT propose textual rewrites — that's the operator's call.