Add case studies doc with agent attribution

[cmeans]

Summary

• New docs/case-studies.md with 7 real-world case studies in collapsible <details> blocks — visitors see all titles at a glance, expand what interests them
• Each case study attributed to the platform involved using "Platform:" / "Discovered with:" / "Implemented with:" framing (not "Discovered by" — agents are tools, not actors)
• Intro explicitly states: "every step was human-directed: the user asked the questions, made the decisions, reviewed the output, and approved the results"
• Condensed README "How it's built" from 4 detailed paragraphs to a summary with link to case studies
• Added case studies to Design docs list in README
• Added copyright footer to all 5 docs that were missing it (collation-layer, data-dictionary, from-metrics-to-mental-models, memory-prompts, case-studies)
• Fixed human-in-the-loop framing across README:
  • Practice scenario: "you drafted", "you refined", "you moved to" (not agents acting autonomously)
  • "maintained itself" → "you and your agents maintain it together"
  • "self-resolve without user intervention" → "your agent surfacing recommendations and you deciding what to act on"
  • "accumulated as a side effect" → "you asked your AI to remember important details"

Case studies included

1. Patterns over events — OS update analysis (Claude on claude.ai)
2. Feature discovery through friction — logical_key upsert (Claude Desktop → Claude Code)
3. Prompt tuning through data audit — 53/56 entries misclassified (Claude on claude.ai)
4. Cross-platform planning — commute plan flow (Claude Android → Desktop → Code)
5. Agent-driven code review — tool surface feedback (Claude Desktop)
6. Query discipline — 356K-char blowout (Claude Code, PR Add query discipline to server instructions #54)
7. Aspirational README audit — catching overpromises (Claude Code Dev + QA roles, PR Fix aspirational claims in README #53)

QA

Prerequisites

• No code changes — docs and README only

Manual tests

1. • Verify case-studies.md renders correctly on GitHub
     Review case-studies.md on branch — confirm all 7 case studies render as collapsible blocks with proper attribution, formatting, and links
2. • Verify README link works
     Review README on branch — confirm "How it's built" section links to case studies, Design docs list includes case studies entry
3. • Verify no content lost
     All 4 original "How it's built" examples (logical_key, data audit, cross-platform planning, code review) are present in case-studies.md with expanded detail
4. • Verify human-in-the-loop framing
     Check README practice scenario, estate section, goals section, and "How it's built" summary — all should credit the user directing the work, not agents acting autonomously
5. • Verify copyright footers
     All 7 docs in docs/ should end with the Apache 2.0 copyright footer
6. • Verify collapsible blocks
     Each case study should be folded by default with title + platform visible in the summary line

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cmeans]

QA Review — PR #55

Changes: 3 files, +148/−10 — docs/case-studies.md (new), README.md, CHANGELOG.md

Findings

No blockers or substantive issues.

1. (observation) The condensed "How it's built" README section works well — one paragraph hitting all four original examples by name, then a link to the full case studies. Reads as a teaser, not a loss.
2. (observation) Case studies #6 (query discipline) and #7 (aspirational README) reference PRs #54 and #53 with working links — good provenance.
3. (observation) Case study #1 (patterns over events) is the strongest new addition — it demonstrates a non-obvious design decision (what NOT to store) with clear reasoning.
4. (nit) CHANGELOG has two entries: Added for the case studies doc, Changed for the README condensation — correct categories per Keep a Changelog.

Automated Tests

• No code changes — tests N/A

Manual Tests

1. Verify case-studies.md renders correctly on GitHub

$ curl -s ".../case-studies-doc/docs/case-studies.md" | grep -c "^## "
7

$ curl -s ".../case-studies-doc/docs/case-studies.md" | grep "Discovered by:\|Performed by:\|Drafted by:"
**Discovered by:** Claude on claude.ai
**Discovered by:** Claude Desktop
**Discovered by:** Claude on claude.ai
**Drafted by:** Claude on Android (claude.ai mobile)
**Performed by:** Claude Desktop
**Discovered by:** Claude Code
**Discovered by:** Claude Code (Dev role)

✅ All 7 case studies render with proper headings, attribution, formatting, and PR links — confirmed.

2. Verify README link works

$ curl -s ".../case-studies-doc/README.md" | grep "Case Studies"
- [Case Studies](docs/case-studies.md) — real-world examples of awareness in practice, with agent attribution
Each interaction generated a case study. Read them all: **[Case Studies — Awareness in Practice](docs/case-studies.md)**

✅ Case studies linked in both Design docs list and "How it's built" section — confirmed.

3. Verify no content lost
Searched case-studies.md for key phrases from all 4 original README examples:

logical_key: 2 matches
53 out of 56: 1 match
commute: 2 matches
token cost: 1 match

✅ All 4 original examples (logical_key upsert, data audit, cross-platform planning, agent-driven code review) present in case-studies.md with expanded detail — confirmed.

Verdict

All 3 manual tests pass. Clean extraction from README to standalone doc, no content lost, 3 valuable new case studies added. Ready to merge.

[cmeans]

QA Re-review — PR #55 (Expanded Scope)

Changes: 7 files, +208/−15 — docs/case-studies.md (new), README.md, CHANGELOG.md, plus copyright footers on 4 existing docs

New commits since last review

1. Collapsible details blocks — case studies wrapped in <details>/<summary> for scannable overview
2. Copyright footers — 5 docs that were missing the Apache 2.0 footer now have it (collation-layer, data-dictionary, from-metrics-to-mental-models, memory-prompts, case-studies). Consistent with deployment-guide and vision which already had them.
3. Human-directed reframing — all case studies reframed: "Discovered by" → "Platform" / "Discovered with", agents as tools not actors, user directs every decision. Intro paragraph updated.
4. README grounding — fixed "maintained itself", "self-resolve without intervention", passive accumulation language, and agent-as-actor framing throughout.

Findings

No blockers or substantive issues.

1. (observation) Human-directed reframing is thorough and consistent. Every case study now attributes the decision-making to the user. The intro paragraph sets the frame explicitly: "the user asked the questions, made the decisions, reviewed the output, and approved the results."
2. (observation) Collapsible blocks work well — summary lines include title + platform attribution, so all 7 are visible at a glance.
3. (observation) Copyright footer is now consistent across all 7 docs — good hygiene.
4. (observation) README "How it's built" reframing is clean: "The agents are tools; the human directs every decision." and "the user directed the fix" — consistent with case studies.
5. (observation) Vision section edits ("you and your agents maintain it together", "your agent evaluates", "with your agent surfacing recommendations and you deciding what to act on") — all grounded.

Automated Tests

• No code changes — tests N/A

Manual Tests

1. Verify case-studies.md renders correctly on GitHub

$ curl -s ".../case-studies-doc/docs/case-studies.md" | grep -c "<details>"
7

$ curl -s ".../case-studies-doc/docs/case-studies.md" | grep "<summary>"
<summary><strong>Patterns over events</strong> — OS update analysis (Claude on claude.ai)</summary>
<summary><strong>Feature discovery through friction</strong> — logical_key upsert (Claude Desktop → Claude Code)</summary>
<summary><strong>Prompt tuning through data audit</strong> — 53/56 entries misclassified (Claude on claude.ai)</summary>
<summary><strong>Cross-platform planning</strong> — commute to deployment (Claude Android → Desktop → Code)</summary>
<summary><strong>Agent-driven code review</strong> — tool surface feedback (Claude Desktop)</summary>
<summary><strong>Query discipline</strong> — the 356K blowout (Claude Code)</summary>
<summary><strong>Aspirational README audit</strong> — catching our own overpromises (Claude Code Dev + QA roles)</summary>

✅ 7 collapsible case studies with proper attribution in summary lines — confirmed.

2. Verify README link works

$ curl -s ".../case-studies-doc/README.md" | sed -n '/## How it.s built/,/## License/p'
## How it's built
This project is built using the thing it builds. The developer works across multiple
AI platforms ... The agents are tools; the human directs every decision.
...
Each interaction generated a case study. Read them all: **[Case Studies — Awareness in Practice](docs/case-studies.md)**
## License

✅ Condensed section with human-directed framing and link — confirmed.

3. Verify no content lost

$ curl -s ".../case-studies-doc/docs/case-studies.md" | grep -c "logical_key\|53 out of 56\|commute\|token cost"
8

✅ All 4 original examples present with expanded detail — confirmed.

Additional verification: copyright footers

$ tail -3 docs/{collation-layer,data-dictionary,from-metrics-to-mental-models,memory-prompts}.md
*[mcp-awareness](...) is open source under the Apache 2.0 License. Copyright (c) 2026 Chris Means.*
(all 4 match)

✅ Consistent with existing deployment-guide.md and vision.md footers — confirmed.

Verdict

All manual tests pass. Expanded scope is clean: collapsible blocks improve scannability, human-directed framing is consistent throughout, copyright footers now cover all docs. Ready to merge.