VIBECODE-THEORY/tools/README.md

VIBECODE-THEORY Tools Summary

This directory now contains the three structural deliverable sets from CODEX_TASKS.md:

• cross-references/ maps document-to-document relationships across Papers 001-008 and the allegories.
• concept-index/ builds a reusable glossary and concept graph for the series' named frameworks.
• integrator/ consolidates Gemini research into a Paper 009 planning package.

What Exists

cross-references/

• build_cross_references.py regenerates the cross-reference artifacts.
• graph.json contains 16 nodes and 67 edges spanning the eight papers and eight allegories.
• graph.mermaid renders the document-level relationship graph.
• dangling_threads.md lists unresolved questions that remain live after Paper 008.
• concept_flow.md traces major concepts through introduction, revision, challenge, and current standing.

concept-index/

• build_index.py regenerates the concept index artifacts.
• index.json contains 47 curated concepts with origin, definition, revision, challenge, and reference metadata.
• glossary.md is the human-readable glossary.
• concept_map.mermaid is the concept-to-concept relationship graph.

integrator/

• integrate.py regenerates the research synthesis from research/*.md.
• integrated.json is the structured merged research output.
• digest.md contains the scholar frequency table, bibliography, contradiction report, Paper 009 coverage map, and strongest challenges.
• 009_outline_suggestion.md proposes a research-backed sequence for Paper 009.

Strongest Takeaways

• The series has a clear structural arc: social skill -> surplus -> rebuttal -> revision -> feedback loop -> ratchet -> unification / identity.
• The main unresolved Paper 009 questions are already visible in cross-references/dangling_threads.md and are reinforced by integrator/digest.md.
• The research synthesis points most strongly at Q2 (identity) and Q4 (the cheating frame) as the most supported Paper 009 sections, while Q3 (practical individual guidance) and Q5 (timeline) remain weakest and will require more original argument.
• The concept glossary is usable as a reference layer for drafting, navigation, or future tooling.

Recommended Starting Points

• For series structure: read cross-references/concept_flow.md.
• For terminology normalization: read concept-index/glossary.md.
• For Paper 009 planning: read integrator/digest.md and integrator/009_outline_suggestion.md.
• For visualization: render cross-references/graph.mermaid and concept-index/concept_map.mermaid.

Caveats

• These outputs are machine-generated analytical aids, not final prose. They are useful for planning and navigation, but they still deserve human judgment before being quoted as authoritative interpretations.
• concept-index/ is a hybrid approach: source-driven definitions with a curated concept registry. That makes it cleaner than unconstrained extraction, but it is not an ontology inferred fully automatically.
• cross-references/ is good at explicit links and repeated concept propagation, but some edge labels are heuristic.
• integrator/ is only as strong as the current research markdown. If Gemini research files are revised, rerun integrate.py.

Regeneration

Run these from the repo root:

python3 tools/cross-references/build_cross_references.py
python3 tools/concept-index/build_index.py
python3 tools/integrator/integrate.py