Public release: Room Riddle brand, showcase README, community files and CI

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,34 @@
+name: Bug report
+description: Something doesn't work as expected
+labels: [bug]
+body:
+  - type: dropdown
+    id: area
+    attributes:
+      label: Where
+      options: [TV app (Vega), Phone app, Server, AI suspects / voices, A case's content, Docs]
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      placeholder: "1. Create a room on the TV\n2. Join from a phone\n3. …"
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected vs actual
+    validations:
+      required: true
+  - type: input
+    id: env
+    attributes:
+      label: Environment
+      placeholder: "Fire TV Stick 4K Max / Vega Virtual Device; phone browser; commit"
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs or screenshots
+      description: Please remove any API keys.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security issue
+    url: https://github.com/perhaps-aksh/RoomRiddle/security/advisories/new
+    about: Please report vulnerabilities privately.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,18 @@
+name: Feature or case idea
+description: Suggest a feature, an improvement or a new mystery
+labels: [enhancement]
+body:
+  - type: textarea
+    id: idea
+    attributes:
+      label: The idea
+    validations:
+      required: true
+  - type: textarea
+    id: why
+    attributes:
+      label: Who it helps and why
+  - type: textarea
+    id: notes
+    attributes:
+      label: Anything else (sketches, references)

.github/pull_request_template.md

@@ -0,0 +1,15 @@
+## What
+<!-- One or two sentences: what changes and why. Link the issue: Closes #123 -->
+
+## How
+<!-- Key decisions, files touched, anything a reviewer should look at first. -->
+
+## Checks
+- [ ] `npm run check` passes
+- [ ] TV changes: `apps/tv/scripts/wsl-check.sh` passes (and checked on the Vega Virtual Device if it changes what's on screen)
+- [ ] No case-specific logic in the engine or UI; content stays in `packages/mystery-data`
+- [ ] No secrets, keys or `.env` files
+- [ ] Docs updated (README, `docs/`, friction log) where relevant
+
+## Screenshots
+<!-- TV or phone before/after, if the change is visible. -->

.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: Typecheck and test (engine, content, server, phone)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run check
+        env:
+          AI_DISABLED: "1"
+          VOICES_DISABLED: "1"

CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes, newest first. The project follows [Conventional Commits](https://www.conventionalcommits.org/); see `git log` for every commit.
+
+## [Unreleased]: public release prep
+- **Brand:** the app is now "Room Riddle", with a launcher icon on the TV and a favicon and web manifest on the phone.
+- **Docs:** showcase README with screenshots; technical reference moved to `docs/system-design.md`; contributing guide, code of conduct, security policy, credits, `.env.example`, CI and issue/PR templates.
+
+## 2026-10-12: Voices on the TV
+- AI suspect voices play on Vega: the server converts clips to fragmented-MP4 AAC and the TV streams them through Media Source (Vega refuses plain `http://` media; FL-014).
+- The speech bubble sits above the footer.
+
+## 2026-10-10: AI suspects and five cases
+- **AI questioning (server):** prompts built only from unlocked truth-table facts, a reply guard for spoilers, answers and character breaks, authored fallbacks, a question budget, cooldowns and caching. Groq first.
+- **Voices:** free Edge neural voices, with Groq Orpheus as a second provider; one voice per character.
+- **Phone Question tab:** pick a suspect, ask in your own words, show found evidence.
+- **TV speech bubble:** "is thinking…", then the reply with voice and subtitles.
+- **Content:** truth tables; *The Hollow Manor*, *Signal Lost*, *The Forgotten Temple* and *The Yaksha's Three Questions* are playable; the library fits five cases.
+- Technical README and market research.
+
+## 2026-10-06 to 10-09: Audio and polish (Phase 7)
+- Data-driven audio: music states, ambience layers, cues and voice ducking; pooled effect players; saved settings.
+- Audio diagnostics; the emulator crackle was traced to the emulator itself (FL-013).
+- World fixes: real clock faces, focus tags, remote focus that follows the layout; Play Again in a room.
+
+## 2026-09-29 to 10-05: Design system and 2.5D world (Phases 5 and 6)
+- Design tokens shared by TV and phone; redesigned TV and phone screens; connection overlays; reduced motion.
+- 2.5D world: asset registry, camera and parallax, director and timelines, rain, fog, steam, lightning, the train and the detective.
+- Vega WebSocket messages that arrive in pieces are reassembled (FL-011).
+
+## 2026-09-27 to 09-29: Foundation (Phases 0 to 4)
+- Monorepo, development rules, Vega app generated and running on the Vega Virtual Device.
+- TV shell with D-pad navigation.
+- Deterministic game engine and *The Last Train*, playable end to end.
+- Authoritative WebSocket server: rooms, QR join, reconnection, host pause. Phone web app and a shared protocol client.

CODE_OF_CONDUCT.md

@@ -0,0 +1,7 @@
+# Code of Conduct
+
+Room Riddle follows the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+In short: be welcoming and respectful, assume good intent, give and accept constructive feedback gracefully, and keep discussions about the work. Harassment, insults, and personal or political attacks are not accepted.
+
+To report unacceptable behaviour, open a private [security advisory](https://github.com/perhaps-aksh/RoomRiddle/security/advisories/new) or contact the maintainer through their GitHub profile. Reports are handled confidentially.

CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing to Room Riddle
+
+Thanks for your interest. Room Riddle started as a hackathon project and welcomes issues, fixes and new cases.
+
+## Ground rules
+Read [AGENTS.md](AGENTS.md) first: it is the rulebook for humans and coding agents alike. The short version:
+
+- **The server is authoritative.** Clients send intents ("my answer is 1147"), never results.
+- **The engine is pure and mystery-agnostic.** No I/O, no `Date.now()`, no case ids in engine or UI code.
+- **Content is data.** Everything about a case lives in `packages/mystery-data`.
+- **The TV works with a remote only.** Every focusable element has a visible focus state; Back never destroys progress without asking.
+- **AI is optional and guarded.** It may only voice facts the room has unlocked, and the game must play without it.
+- **No secrets in git.** Keys go in `apps/server/.env` (see `.env.example`).
+
+## Setup
+```bash
+npm install
+npm run check      # must pass before every commit
+npm run serve      # server + phone app on :4000
+```
+TV app setup (Vega SDK, WSL2 on Windows): [docs/development.md](docs/development.md).
+
+## Workflow
+1. Open an issue describing the bug or idea (templates are provided).
+2. Branch from `main`: `feat/…`, `fix/…`, `docs/…`.
+3. Keep changes small and tested. Add tests next to the code (`*.test.ts`, or `apps/tv/test/*.spec.tsx`).
+4. Run `npm run check` (and `apps/tv/scripts/wsl-check.sh` for TV changes).
+5. Commit with [Conventional Commits](https://www.conventionalcommits.org/): `feat(tv): …`, `fix(server): …`, `docs: …`.
+6. Open a pull request and fill in the template. CI must be green.
+
+## Writing a new case
+1. Copy an existing case folder in `packages/mystery-data/src/` (for example `the-forgotten-temple/`).
+2. Fill in the `MysteryDefinition`: summary and audience, intro, scenes, clues, puzzles (each with accepted answers and exactly three hints), endings, scoring.
+3. Add the **truth table**: each character's persona, public claims and secrets with `unlockedBy`, plus guarded spoiler terms.
+4. Register it in `packages/mystery-data/src/index.ts`.
+5. Run `npm run check`. The catalog tests validate every reference and **play the case to the end automatically**; they fail if a clue can't be found or a spoiler can never unlock.
+
+Cultural or religious source material must be original, respectful, and never presented as scripture; worship is never a puzzle.
+
+## Reporting Vega / Fire TV friction
+Real problems with the Vega SDK, the emulator or tooling go in [docs/friction-log.md](docs/friction-log.md), with steps, expected and actual results, and the workaround. Only verified facts.
+
+## Code of conduct
+This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md).

CREDITS.md

@@ -0,0 +1,24 @@
+# Credits
+
+**Design, code and story:** Chitraksh Kumar ([@perhaps-aksh](https://github.com/perhaps-aksh)).
+
+## Art
+- App icon, banner and concept art: AI-assisted illustration, art-directed and edited by the author. Released with the project under the MIT licence.
+- TV scenes in the current build use code-drawn placeholder shapes; painted plates and character art are being added through the asset system.
+- Screenshots in `docs/images` were captured from the Vega Virtual Device and a phone browser.
+
+## Audio
+- Current music, ambience and effects are **placeholders synthesized for development** (`apps/tv/scripts/gen-placeholder-audio.py`). They will be replaced by licensed or CC0 recordings, which will be listed here with their sources.
+- Detective narration lines: Microsoft Edge neural voice `en-GB-RyanNeural`, generated for development.
+- Live suspect voices are generated at runtime by Microsoft Edge neural TTS (via [`msedge-tts`](https://www.npmjs.com/package/msedge-tts)) and Groq-hosted [Orpheus](https://console.groq.com/docs/text-to-speech) by Canopy Labs.
+
+## Services and libraries
+- [Amazon Vega SDK](https://developer.amazon.com/docs/vega/) and React Native for Vega.
+- [Groq](https://groq.com/) free tier: `openai/gpt-oss-120b` (OpenAI open-weight model) for suspect dialogue.
+- [`ws`](https://github.com/websockets/ws), [esbuild](https://esbuild.github.io/), [tsx](https://github.com/privatenumber/tsx), [ffmpeg](https://ffmpeg.org/) and the React Native Testing Library.
+
+## Fonts
+The TV uses Vega's built-in system fonts (Bookerly, Amazon Ember, Amazon Ember Mono); none are bundled.
+
+## Inspiration
+*The Yaksha's Three Questions* is inspired by the *Yaksha Prashna* episode of the Mahabharata. The case is an original story and puzzles, not a retelling of scripture.