# Documentation Guidance
Documentation, changelog, citation, and scientific-notation rules for this
repository.
---
## Contents
- [Documentation Ownership](#documentation-ownership)
- [Academic Paper Authorship](#academic-paper-authorship)
- [Scientific Notation](#scientific-notation)
- [References](#references)
- [Changelog Maintenance](#changelog-maintenance)
- [Crates.io Documentation](#cratesio-documentation)
---
## Documentation Ownership
- `AGENTS.md` is the coding-agent entry point.
- `docs/dev/README.md` indexes development workflow guidance.
- `docs/dev/notebooks.md` owns notebook cell identity, execution, and artifact
policy.
- `docs/code_organization.md` is the required-reading architecture hub.
- `docs/architecture/README.md` indexes focused architecture references.
- `REFERENCES.md` owns literature references.
- `CITATION.cff` owns citation metadata.
- `papers/*.tex` owns publication-facing mathematical exposition. The matching
`papers/*.bib` files own paper-local BibTeX references. The matching
`papers/*.pdf` files are tracked reviewer copies, built from TeX in
`target/papers/` with Tectonic and refreshed by `just papers` or
`just paper-refresh`.
- `docs/assets/validation/*.png` owns stable validation figures generated by
notebooks and reused by both documentation and papers. Regenerate them with
`just validation-doc-figures`; ordinary notebook checks write only under
`target/notebooks/`.
- `README.md`'s first Introduction paragraph and `CITATION.cff`'s `abstract`
field intentionally mirror each other. When one changes, update the other in
the same patch. `scripts/tests/test_readme_citation_mirror.py` checks the
normalized text after Markdown links are stripped from the README prose.
Semgrep also rejects stale public validation-hierarchy wording.
- `docs/archive/` stores historical plans, completed changelog series, and old
design notes. Do not update archived docs as active guidance unless an
explicit archive-maintenance task asks for it.
## Academic Paper Authorship
Paper prose under `papers/` is author-owned. Agents must not add substantive
publication prose there. They may maintain outlines, TODO scaffolds, TeX/build
tooling, figures, citations, and review comments.
Keep paper drafts visibly marked as outlines or TODO scaffolds until the
maintainer supplies prose. Treat formal AI-use disclosure as a separate
venue/submission matter, not as a repository guidance claim.
## Scientific Notation
Unicode math is welcome in doc comments and active documentation when it makes
scientific meaning clearer. Examples include:
```text
×, ≤, ≥, ∈, Σ, ², 2^-50, χ(S^d) = 1 + (−1)^d
```
Prefer mathematical invariants where possible instead of prose-only
descriptions.
Use topological-space notation when naming a fixed manifold. Write `T^2`,
`T^3`, `S^2`, or `S^3` in prose and doc comments; Unicode superscripts such as
`T²` and `S²` are equivalent. Rust identifiers use `t2`, `t3`, `s2`, and `s3`.
Keep labels such as `2D` and `3D` for algorithm, coordinate, ambient, or
simplicial-complex dimensions. For example, describe a cone over `T^2` as a 3D
simplicial complex rather than calling its torus link "2D" or "3D."
## References
Algorithms should cite their sources in `REFERENCES.md` and document relevant
conditioning behavior. Typical references include Shewchuk, Bowyer-Watson,
Edelsbrunner, and Preparata-Shamos.
Use numbered `REFERENCES.md` citations in API docs and active design docs when
describing algorithms, numerical robustness, or topology guarantees.
## Changelog Maintenance
- Never edit `CHANGELOG.md` or `docs/archive/changelog/*.md` manually.
- Run `just changelog` to regenerate the root changelog and archive files from
commits.
- The root `CHANGELOG.md` contains only `Unreleased` plus the active minor
series.
- Completed minor series are archived in `docs/archive/changelog/X.Y.md`.
Commit-message rules that affect generated changelog text live in
[`git.md`](git.md).
## Crates.io Documentation
Publish documentation changes before bumping the crates.io version. crates.io
does not allow re-publishing documentation without a version bump.