# Reader Data Contract

This reference exists so the static page code can be reused for every paper-code analysis without rewriting page logic.

## Directory Layout

Every analysis directory must contain:

```text
analysis_dir/
  analysis_bundle.json
  paper_reading_report.md
  paper_questions_for_code.md
  paper_code_crosswalk.md
  experiment_joint_reading.md
  implementation_omissions.md
  diagrams.md
  modify_method_guide.md
  validation_report.md
  site/
```

The `site/` directory must be generated by:

```bash
python scripts/build_static_reader.py <analysis_dir> --force
```

When full local KaTeX typography is required and network access is available, generate the site with fonts installed:

```bash
python scripts/build_static_reader.py <analysis_dir> --force --install-katex-fonts
```

Do not put KaTeX `.ttf`, `.woff`, or `.woff2` files in the ClawHub skill package. The font install flag writes WOFF2 files only into generated `site/vendor/katex/fonts/` output directories.

Do not hand-write a paper-specific site. If the reader needs a new generic display feature, patch `assets/reader-template/` and rebuild.

For modest artifacts, keep one fixed Markdown file. For very large artifacts or outputs blocked by tool/OS transport limits, use `_parts/` as an intermediate build area, then merge into the fixed final filename. The reader should still consume the final stable filename.

## JSON Contract

`analysis_bundle.json` is the machine-readable source for structured sections.

Required stable keys:

- `schema_version`
- `intake`
- `paper_questions`
- `domain_critical_execution`
- `mechanisms`
- `experiments`
- `implementation_omissions`
- `diagrams`
- `modify_guide`
- `validation`

The reader assumes these names. Do not rename them for one paper.

## Markdown Contract

The reader fetches fixed filenames. Do not rename them:

- `paper_reading_report.md`: full paper-only deep-reading report.
- `paper_questions_for_code.md`: questions raised by the deep-reading report plus code-evidence answers.
- `paper_code_crosswalk.md`: detailed paper-step/formula-to-code mapping.
- `experiment_joint_reading.md`: every paper experiment mapped to code.
- `implementation_omissions.md`: paper omissions revealed by code.
- `diagrams.md`: Mermaid diagram source blocks.
- `modify_method_guide.md`: how to change the proposed method.
- `validation_report.md`: checks and remaining risks.

## Full Report Requirement

`paper_reading_report.md` must be complete enough to stand alone. It is not a short abstract, dashboard summary, or table-only report.

For a normal computer-science paper, target at least 12,000 characters and cover:

- problem and assumptions;
- title interpretation and related-work gap;
- symbols and entities;
- formulas and losses;
- method components;
- algorithm/control flow;
- figures, tables, and charts;
- experiments and ablations;
- ambiguities visible from the paper alone;
- reviewer/defense lens;
- teaching summary.

The report should follow the local module `modules/deep-reading-gate1.md`: explain central ideas in the sequence intuition -> formula/algorithm -> concrete example -> limitation -> paper-only open question. Do not include repository paths, source-code line numbers, or code-disclosed facts in this report. Do not call `paper-toon-deep-reader`, and do not import cartoon generation gates into this reader.

If a report is below the threshold because source material is genuinely limited, document that in `validation_report.md`.

`paper_questions_for_code.md` must stand between PDF reading and repository reading. It should list what the PDF leaves unclear, why the question matters for implementation or reproduction, what paper evidence raised the question, what code evidence answers it, and whether the question is answered, partly answered, contradicted, inferred, or unresolved.

`modify_method_guide.md` should explain the compact edit surface for proposing a new model or algorithm within the paper's framework. It should not be a hyperparameter tuning checklist.

If one model/tool call cannot safely write the full report, create section chunks and merge them. If the full report is below the active model/API practical limit and can be read from disk, do not chunk just for the sake of chunking.

```bash
python scripts/merge_markdown_parts.py analysis_dir/_parts/paper_reading_report analysis_dir/paper_reading_report.md
```

## Formula Display Requirement

Markdown may store formulas in fenced `math` blocks and JSON may store formula source in `formula.math`, but the reader must display formulas as typeset math via KaTeX.

Normal rendered pages must not expose raw LaTeX commands such as `\frac`, `\lambda`, `\theta`, `\mathcal`, or `\tilde` inside visible formula blocks. Raw source can appear only as fallback when rendering fails.

## Encoding Requirement

All visible reader UI labels, generated Markdown reports, and JSON text fields should be valid UTF-8. Before final delivery, run `scripts/check_outputs.py` and `scripts/check_reader.py`; fix and rebuild if they report mojibake markers or replacement characters.
