Clarify documentation around Copilot tasks and verified output

[sbroenne]

Description

The user-facing documentation was confusing about what the framework runs, what tests must verify, and which guidance is historical. This rewrite presents a consistent workflow: configure a Copilot session, run a user task, independently check actual output, and inspect saved JSON evidence.

• Rewrite the README, practical guides, reference, contributor docs, and example READMEs with task-first explanations and clearer examples.
• Reorganize navigation into setup, configuration, comparisons, task guides, reference, explanations, and historical case studies while retaining existing page URLs.
• Clarify session completion versus application correctness, shared A/B outcomes, missing evidence and usage, paid execution, and isolation limits.
• Correct stale guidance and API examples without changing framework code, tests, dependencies, generated evidence, or frozen experiment fixtures.

The GitHub repository description was updated separately through repository settings; it is not a file change in this PR.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update

Checklist

• I ran the deterministic checks required for this change
• I ran the relevant real-Copilot integration file when behavior changed
• I added contract or integration coverage that proves the outcome
• I updated user and contributor documentation where needed
• I did not include credentials or unsanitized private prompts

Testing

uv run --frozen python -X utf8 -m mkdocs build --strict
Passed; documentation built successfully.

git diff --check
Passed; no whitespace errors.

A local audit of the generated site checked 4,098 local links across 45 HTML pages with no missing targets or anchors. Python documentation snippets were syntax-checked during the rewrite.

Real-Copilot integration tests and new contract coverage were not required: this changes documentation and navigation only, not execution behavior. No paid Copilot tasks were run for this rewrite.

Related Issues

N/A

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None