Docs and traction: fill the twelve gaps in packaging, citation, troubleshooting and accuracy docs

Summary

An audit of the docs and packaging surface turned up twelve concrete gaps. Each one is a verified current-state problem, not a stylistic preference. They are grouped here so the dependencies between them stay visible.

Items

Packaging and citation

1. pyproject.toml has no description and no keywords, so the PyPI page shows a bare name with no summary.
2. No CITATION.cff, so GitHub shows no "Cite this repository" button; the README BibTeX is pinned to v2.4.1 (May 2024) while the code is at 3.3.0.

Discoverability of what we already document
3. examples/README.md documents CO2Tracker and @track_co2, neither of which has existed for years, and indexes 6 of ~35 files.
4. docs/how-to/enable-rapl.md — the highest-impact accuracy setting — is filed three levels deep under "Deployment".
5. No troubleshooting page. CodeCarbon degrades silently rather than crashing, so users get worse numbers with no visible cause and nothing to search for.

Claims we make but do not support
6. Zero mentions of carbontracker, eco2AI, or experiment-impact-tracker anywhere in the docs; the "X vs Y" searches go uncontested.
7. The FAQ answers "how accurate?" with a scoping statement and no figure, while the validation notebook that answers it sits unpublished in examples/.
8. A 435-line methodology page whose bibliography has one entry, cites a personal blog, and cites an open GitHub issue as a source.

Contribution and release surface
9. bug_report.md is unedited GitHub boilerplate ("Click on...", OS example "iOS", Python 3.8) and never asks for codecarbon detect output.
10. contributing.md is 580 lines mixing first-contributor, developer and maintainer content, with four headings rendering a stray </a>.
11. No CHANGELOG.md; a scheduled 4.0 breaking change is announced only inside the contributing guide; release-drafter is hardcoded to patch bumps.
12. No Open Graph tags, a single footer link, and an API reference page that renders __init__ but not start() or stop().

Dependencies

• The issue-form config.yml links to the troubleshooting page (5).
• The docs URLs embedded in RAPL warning strings point at anchors defined by the troubleshooting page, so its anchors must land first (5 ↔ 4).
• The comparison page (6) and the RAPL item (4) both make accuracy claims the accuracy page (7) is meant to quantify.
• Items 1 and 2 both edit pyproject.toml and both only take effect on release.

Not covered here

Quantifying per-backend accuracy (NVML, powermetrics, Windows EMI) and validating against a wall-socket wattmeter both need measurement work that no documentation change can substitute for. The accuracy page names these as open gaps rather than filling them with estimates.

Start with the twelve items and dependency notes, then inspect pyproject.toml, examples/README.md, docs/how-to/enable-rapl.md, bug_report.md, contributing.md, config.yml, and the API reference page. Check the existing RAPL warning URLs and validation notebook before changing related documentation. Done means the listed packaging, citation, discoverability, accuracy, contribution, release, metadata, and API gaps are addressed, while the explicitly excluded measurement work remains open.