docs: complete metadata, citation, troubleshooting and accuracy docs

[davidberenstein1957]

Closes #1301.

Implements all twelve documentation and traction items. uv run task docs builds clean and the internal link check passes (5246 attributes); tests/test_cpu.py, test_emissions_tracker.py and the new link test pass (76 passed, 2 skipped). Ruff error count is unchanged from master.

What is in here

Packaging and citation

• pyproject.toml: description, 15 keywords, 19 classifiers; Changelog URL now points at the docs. bumpver also patterns CITATION.cff.
• New CITATION.cff and a rewritten README citation section using the Zenodo concept DOI 10.5281/zenodo.4658424, which tracks the latest release instead of pinning v2.4.1. docs/index.md citation link updated to the same DOI.

Discoverability

• examples/README.md rewritten as a categorised index. Every filename checked against ls examples/, every symbol against codecarbon/__init__.py — no CO2Tracker, no @track_co2. The duplicated table in docs/how-to/examples.md is gone; that page now points at the canonical index. New tests/test_readme_links.py asserts relative links resolve.
• The RAPL guide moves to a top-level how-to entry, retitled "Get accurate CPU measurements (Linux/RAPL)", with inbound links from the README, docs index, FAQ, installation and the quickstart. File path unchanged, so no redirect needed.
• New docs/how-to/troubleshooting.md, keyed to log lines that were each grepped out of the current source. cpu.py now appends a docs URL to the RAPL-permission and unknown-CPU warnings via one shared constant, so the three call sites cannot drift apart. The two linked anchors are pinned with explicit { #... } ids.

Supporting our claims

• New docs/explanation/alternatives.md and docs/explanation/accuracy.md. The accuracy figures are computed from CSVs already committed in this repo (codecarbon/data/hardware/cpu_load_profiling/) — the TDP estimate deviates from RAPL by up to roughly a factor of two in either direction depending on CPU and load. Per-backend accuracy and wall-socket validation are marked "not yet measured" rather than estimated. Competitor facts (licence, language, archive status) were pulled from the GitHub API; no maintenance judgements, and "peer-reviewed" softened to "accompanying academic paper" where the venue was not verified.
• methodology.md gains a real bibliography (foundational work, hardware measurement, carbon-intensity sources, citing CodeCarbon). The personal blog post is demoted to a supporting walkthrough behind Khan et al. and Weaver; the open GitHub issue is relabelled as a tracked limitation, with Intel's own page cited for the Power Gadget discontinuation.

Contribution and release surface

• Issue forms replace the four .md templates. The bug form requires codecarbon detect output (command verified to exist); config.yml disables blank issues and links Discord, troubleshooting, FAQ and docs.
• contributing.md split into a 95-line contributor page, how-to/development.md, and maintaining.md. Nothing dropped — content moved. The stray </a> in four headings and the hand-maintained TOC markers are gone.
• CHANGELOG.md at the repo root, holding both the user-facing changelog and the deprecations/migrations table; the Changelog project URL points at the GitHub releases page. No changelog or deprecations page in the docs site, and no blog surface — codecarbon.io already has one. Entries are sourced from gh release view bodies and git log; deprecation "since" versions from git log -S plus git tag --contains. release-drafter.yml now resolves the version instead of always bumping the patch.
• Open Graph and Twitter Card tags via a small overrides/main.html (Zensical emits none, and supports custom_dir — no Cairo dependency, no workflow change), five footer links, and start()/stop()/flush()/task-tracking now rendering in the API reference. Two malformed :param: directives in track_task_emissions fixed, since griffe now publishes them.

Worth a maintainer's eye before merge

• CITATION.cff author list. Names come from the existing README BibTeX with unresolved handles dropped, plus a collective "The CodeCarbon contributors" entry. This is a social decision, not a technical one — please confirm.
• Two citations copied from the audit rather than verified against the papers: the Khan et al. RAPL in Action year/venue details, and the Henderson et al. JMLR volume/issue 21(248).
• External links were not fetched — the link checker skips them by default. Worth one scripts/check_docs_links.py site --external run.
• date-released in CITATION.cff still needs a manual touch at release time; bumpver only patterns the version line.
• The release checklist in maintaining.md should gain a "move Unreleased under the new version" step; the changelog page is otherwise a manual artefact.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.77%. Comparing base (3ec31a0) to head (a3148a3).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1302      +/-   ##
==========================================
+ Coverage   91.43%   91.77%   +0.33%     
==========================================
  Files          49       49              
  Lines        5057     5058       +1     
==========================================
+ Hits         4624     4642      +18     
+ Misses        433      416      -17     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.