[ramesh130]

Closes #522

The documents now describe the android/ layout from #521. Each command is spelled the way #525 spelled it, (cd android && ./gradlew …).

What changed

• CLAUDE.md orientation: the table's rows are now android/, android/build-logic/, android/demo/ and android/benchmark/, beside Package.swift + ios/. A new intro sentence says what stays at the root and that Gradle runs from inside android/. The Spotless paragraph now says spotlessApply in android/ reaches demo/, benchmark/ and build-logic/, and that no .kt file lives outside android/. Prose paths are prefixed (goldens, qoe-floors.tsv, benchmark/phase3/, robolectric.properties, the daemon-criteria files, settings.gradle.kts, libs.versions.toml, api/released/). Where the prose meant the Gradle root project, "root build" now reads "library build", because "root" now means two different things.
• Other documents: the root documents, the ten docs/ files, ios/CLAUDE.md, the two iOS READMEs, the three devicelab manuals, android/benchmark/README.md, android/api/released/README.md and third-party/moq/README.md. Code blocks keep their aligned comment columns.
• Links that were wrong: android/api/released/README.md linked ../../docs/…, which after the move resolves to android/docs/; it is now ../../../. android/benchmark/README.md's ../ links are now ../../. A link checker over every tracked .md file now reports only the four links in the committed benchmark reports, which are left as they are; the reason is below.
• Code comments: the Swift ref: comments name android/superplayer-*/…, and the comments in Package.swift, ios/MoQ/Package.swift and DemoApp.swift were changed the same way. So were the "not part of ./gradlew check" comments in ios/check, ios/hunt-leaks and the devicelab scripts, the usage block in android/benchmark/bench, .editorconfig, the fixture tests' KDoc (now matching their UPDATE_COMMAND constants), and BenchmarkMatrixTest's KDoc. Two CI comments that tell a contributor what to type are changed too.

Decisions

• Benchmark report links: I fixed the generator, not the committed reports. ReportWriter now links ../../../PRD.md and ../../../docs/telemetry-schema.md. Both are correct from android/benchmark/out/ and from android/benchmark/phase3/, the only two places bench writes (--out DIR excepted). Before the move the link was one level short. The committed reports, baseline/ (frozen) and phase3/ (the current reference), are generated records of a run at a recorded commit. Editing them by hand would make each one differ from what its generator wrote, so they keep their broken ../PRD.md. The next bench --baseline writes a correct link.
• No ADR addendum: the old paths in ADR-0015, 0017 and 0021 all name files that still exist under the same name inside android/ (gradle/libs.versions.toml, superplayer-abr/src/test/qoe-floors.tsv, demo/build.gradle.kts, ./gradlew updateGoldenTraces, benchmark/phase3/). Each reads correctly from inside the Gradle build, and CLAUDE.md's orientation now says where that build is. None of them points a reader at something that is not there, which is the bar Documents describe the android/ layout #522 sets for an addendum.
• No CHANGELOG.md entry: the changelog is "for someone deciding whether to take a new version", and moving the source tree changes no coordinate, no artifact and no behaviour. The Unreleased section's own paths were corrected; there are no released entries.
• GoldenFile.UPDATE_COMMAND is unchanged, as Move the Android builds under android/ #525 argued.
• Edits are kept minimal and not reflowed: prose lines that grew past the file's usual wrap were left as they are, so the diff stays a path diff.

Remaining grep hits (outside docs/adr/), with the reason each stays

• demo/bbb.hang (docs/testing.md, a devicelab log fixture): a MoQ broadcast name, not a path.
• Paths written relative to android/, inside a context that says so: the PRD.md tree under superplayer/android/, README's and CONTRIBUTING's "the library build in android/ reaches demo/…", the CI and devicelab/lib/common.sh comments next to GRADLE_DIR/GRADLE_ROOT, the CI run: ./gradlew … steps (which run with working-directory: android), and devicelab/lab's and moq-smoke's ./gradlew calls, which run after a cd into the Gradle directory.
• Text read from inside the Gradle build: build scripts, build-logic messages and module KDoc under android/. ./gradlew … is correct where Gradle runs, and ApiSurface's "Run ./gradlew updateApiSurface" is printed to someone already in android/.
• The committed benchmark reports: see Decisions.
• ADR bodies: see Decisions.

Review (two axes, kept separate)

• Standards:
  • One hard finding, fixed: a Package.swift comment line went past 100 columns after a rewrap.
  • Soft findings, fixed: .editorconfig still said "three builds"; "root" was ambiguous; the long ref: line in PlaybackDecision.swift; a redundant "Android android/demo/"; a CI comment that lost the word "copies"; a dangling string fragment in ReportWriter.
  • Soft finding, declined deliberately: prose not reflowed, to keep the edits minimal.
• Spec:
  • No hard findings. Every item in the brief is covered, and no scope creep.
  • Soft findings, fixed: CI comments still advising a root ./gradlew, and "root build" read ambiguously.
  • Soft findings, taken as decisions above: the committed reports, and the ADR addenda.

Tests

• Full check: (cd android && ./gradlew assemble check --max-workers=1) passed: 1238 tests, 0 failures. That includes CompatibilityDocumentTest (28), ModulePhaseRuleTest (16), TelemetrySchemaDocumentTest, DoctorDocumentTest and TransportDocumentTest.
• Re-run after the review fixes: spotlessCheck, verifyLicenseHeader and verifyModulePhaseRule.
• Benchmark build: (cd android/benchmark && ./gradlew spotlessCheck testDebugUnitTest --tests '*ReportHonestyTest') passed.
• Commands run from the root, as the documents now give them:
  • (cd android && ./gradlew --version) prints the Daemon JVM: line.
  • (cd android && ./gradlew help) succeeds.
  • devicelab/test/selftest passes.
  • android/benchmark/bench --help prints the new usage.

Skipped

• ios/check: only Swift comments changed, so the macOS CI job on this PR covers it.
• Emulator: not run, because nothing here touches playback.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MJAhQmFgdRRAKUaMHibQLe