# 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:

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