docs: establish integrated project memory

.project-docs/10-decisions/adr-001-native-android-display.md

@@ -0,0 +1,37 @@
+# ADR-001: Native Android large-screen application
+
+## Status
+
+Accepted
+
+## Date
+
+2026-08-12
+
+## Context
+
+The browser display worked on general computers but remained unreliable on the target Android television hardware because WebView and browser media behavior varied by vendor. The user approved replacing the APK's WebView presentation with native Android pages while retaining the service's public display APIs.
+
+## Decision
+
+The dedicated Android app renders its overview and project screens with Android Views and directly polls the public display API. It does not load the web application. The overview polls every five seconds and cannot create announcement state. A project screen polls its snapshot every three seconds and uses that same response for both UI and announcement detection.
+
+## Rationale
+
+This removes System WebView from the appliance runtime path, makes remote-control focus and lifecycle behavior explicit, and keeps the Go service as the authoritative source without duplicating queue rules in the app.
+
+## Consequences
+
+- Browser and Android presentation code are separate and must both be maintained.
+- The Android app depends on the public overview and snapshot DTOs.
+- Hardware-specific layout, audio routing, orientation, and lifecycle behavior still require target-device acceptance.
+
+## Supersedes
+
+- The previous Android WebView wrapper design.
+
+## Related
+
+- `android/app/src/main/java/cn/nianxx/queue/display/MainActivity.java`
+- `android/app/src/main/java/cn/nianxx/queue/display/DisplayApiClient.java`
+- `.project-docs/50-evidence/topics/20260811-native-display-f2456ea9__public-display-api.md`

.project-docs/10-decisions/adr-002-embedded-audio-announcements.md

@@ -0,0 +1,39 @@
+# ADR-002: Embedded audio announcements
+
+## Status
+
+Accepted
+
+## Date
+
+2026-08-12
+
+## Context
+
+System speech synthesis was absent or inconsistent on the target display devices. A first embedded eSpeak asset set produced unintelligible Mandarin. The repository already contained a prior Mandarin queue-announcement WAV set that the user confirmed was the intended project audio.
+
+## Decision
+
+Package the project’s legacy Mandarin prompt, digit, range, and suffix fragments in the APK. Parse and validate PCM WAV assets, compose the number or range locally, and stream each announcement three times using `AudioTrack` with media usage and transient audio focus. Do not announce the project name. Do not depend on system TTS.
+
+## Rationale
+
+Deterministic bundled PCM avoids browser autoplay and installed-voice dependencies while allowing the server to continue sending ordinary snapshot text and batch data.
+
+## Consequences
+
+- The APK contains and tests exactly 13 WAV resources.
+- The player must own FIFO ordering, cancellation, focus, and native track lifecycle safely.
+- The original generator, speaker, and separate redistribution license for the historical WAVs are not recorded; confirm ownership before distribution outside the project's authorized deployment scope.
+- Audio routing and intelligibility remain target-device acceptance items.
+
+## Supersedes
+
+- Android system TTS announcements.
+- The rejected eSpeak-generated Mandarin assets.
+
+## Related
+
+- `android/app/src/main/java/cn/nianxx/queue/display/QueueAnnouncementPlayer.java`
+- `android/app/src/main/java/cn/nianxx/queue/display/EmbeddedWavComposer.java`
+- `.project-docs/50-evidence/topics/20260811-native-display-f2456ea9__embedded-audio-assets.md`

.project-docs/10-decisions/adr-template.md

@@ -0,0 +1,33 @@
+# ADR-{number}: {decision title}
+
+## Status
+
+Proposed
+
+## Date
+
+{YYYY-MM-DD}
+
+## Context
+
+{context that made the decision necessary}
+
+## Decision
+
+{decision made}
+
+## Rationale
+
+{why this option was chosen}
+
+## Consequences
+
+- {positive or negative consequence}
+
+## Supersedes
+
+- {older ADR or decision, if any}
+
+## Related
+
+- {related doc or source file}

.project-docs/10-decisions/decision-index.md

@@ -0,0 +1,24 @@
+# Decision Index
+
+## Active Decisions
+
+| ID | Decision | Status | Date | Applies To | Detail |
+|---|---|---|---|---|---|
+| ADR-001 | Use native Android Views for the dedicated large-screen app | Accepted | 2026-08-12 | `android/` | [ADR](adr-001-native-android-display.md) |
+| ADR-002 | Compose embedded Mandarin WAV fragments and stream them through `AudioTrack` | Accepted | 2026-08-12 | Android project-screen announcements | [ADR](adr-002-embedded-audio-announcements.md) |
+
+## Superseded Decisions
+
+| ID | Decision | Superseded By | Date |
+|---|---|---|---|
+
+## Decision Criteria
+
+Create or update an ADR when a choice affects:
+
+- project positioning
+- architecture boundaries
+- public behavior
+- data model
+- long-term maintenance
+- user-facing workflow