Skip to content

Reorganize and optimize the repo for AI reference - #3

Merged
SeanShaffer88 merged 17 commits into
mainfrom
reorg/ai-reference-optimization
Oct 28, 2026
Merged

SeanShaffer88 merged 17 commits into
mainfrom
reorg/ai-reference-optimization

Conversation

@SeanShaffer88

Copy link
Copy Markdown
Owner

Reorganizes the repository so an AI assistant can use it as a reference without ingesting fake data or the whole 2.3 MB catalog.

  • Archives 1,000 generated placeholder entries (index/master-manifest.json, the seven categories/01–07 manifest.json files, manifests/resources.json) and the incompatible registry schema to archive/legacy-template/, with a README stating they are not real resources and must never be cited or merged. The old AI_INDEX.md (which described a modules/ layout that never existed) is archived there too.
  • Rewrites AI_INDEX.md as an accurate one-page index: 12 domains, counts, and which file to open for each.
  • Removes the template header block from AGENTS.md and gives it a smallest-first reading order.
  • Adds derived AI views generated by the new scripts/generate_ai_views.py: index/resources.compact.json (full catalog, shortlisting fields only, ~38% of the canonical size), 97 per-category shards in index/by-category/, and index/category-groups.json rolling the 97 categories into 12 domains. resources.json remains canonical and is unchanged.
  • README gains a TL;DR pointing AI readers to AI_INDEX.md; llms.txt, index/README.md, and CONTRIBUTING.md updated to match (including the new regeneration step).

Validation: python scripts/validate.py passes (2,202 records, 97 categories), unit tests 5/5, and no placeholder URLs remain outside archive/.

@SeanShaffer88

Copy link
Copy Markdown
Owner Author

Enhancement packs A–C are folded into this PR (4 additional commits):

Pack A — freshness. New scripts/link_check.py (reachability checker, stdlib only) and a monthly link-check workflow (added via the web UI, as workflow files require). Backfill of the 306 records that had no recorded link status: 293 confirmed live and recorded with checked_on 2026-10-28, 0 dead, 2 moved Android documentation URLs updated everywhere they appear, and 11 left untouched because they failed only from the build machine's network (checker-limited, e.g. Page Flows, Behance, Awwwards).

Pack B — alternatives graph. New scripts/generate_related.py derives related-entry links from shared topics/use cases within each category: records with related entries go from 24 to 1,335, links symmetric as the validator requires. Empty topics were filled on 37 records under a strict rule (a topic must be carried by at least 60% of the category); the rest were left blank rather than guessed.

Pack C — thin entries. 100 short purpose lines expanded with a fit/constraint clause, propagated to the category and catalog pages. The remaining 119 obscure entries were left as-is rather than padded with guesses. The 4 cross-listed URLs (Catch2, google/benchmark, Tracy, WAMR) were verified as already grouped by project_id — project-groups.json covers non-GitHub endpoints only, so no change was needed. Adds llms-full.txt (one-file edition, generated by scripts/generate_ai_views.py).

Validation after all packs: python scripts/validate.py passes (2,202 records, 97 categories) and unit tests pass 5/5. The repository homepage has also been set to the Dev Resource Explorer.

@SeanShaffer88
SeanShaffer88 merged commit c97d064 into main Oct 28, 2026
2 checks passed
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