Merge pull request #15 from leesunghyun/codex/release-readme-polish

Polish README for first-time contributors

Author: leesunghyun

README.md

@@ -4,6 +4,15 @@ A beginner-friendly OSS migration lab that modernizes a 2017 Android AAC ViewMod
 
 This repository is now in the **release readiness phase** of the OSS rebuild.
 
+## Requirements
+
+- Android Studio
+- JDK 17
+- Android SDK
+- Git
+
+If you use Android Studio, the bundled JBR is usually enough.
+
 ## Current status
 
 Completed in this phase:
@@ -45,14 +54,54 @@ The modern version provides:
 ## Quick start
 
 1. Clone the repository
-2. Work in sequence with the migration PRs in this repository
+   ```bash
+   git clone https://github.com/leesunghyun/Android-AAC-ViewModel-Practice.git
+   cd Android-AAC-ViewModel-Practice
+   ```
+
+2. Run tests
+
+macOS / Linux:
+   ```bash
+   ./gradlew test
+   ./gradlew assembleDebug
+   ```
+
+Windows:
+   ```bat
+   gradlew.bat test
+   gradlew.bat assembleDebug
+   ```
+
+3. Open in Android Studio and run the `app` module.
+
+## Demo
+
+The first alpha flow is: `List → Detail/Edit → Save → List` with shared state update.
+
+`v0.1.0-oss-alpha.1` currently uses a placeholder visual in this PR.
+
+Planned path (v0.2): `docs/images/demo.gif`
+
+## Release status
+
+- First OSS alpha release: [v0.1.0-oss-alpha.1](https://github.com/leesunghyun/Android-AAC-ViewModel-Practice/releases/tag/v0.1.0-oss-alpha.1)
+- APK is provided as a sample debug artifact for manual smoke testing (not production release).
+
+For full release details and run verification commands, see:
+- [Release Notes](docs/release-notes-v0.1.0-oss-alpha.1.md)
+- [Release Guide](docs/release-guide-v0.1.0-oss-alpha.1.md)
 
 ## Project structure
 
-- `README.md`: project purpose and progress
-- `docs/`: migration notes and legacy baseline records
-- `legacy-app/`: archived legacy baseline code
-- `.github/`: pull request and issue templates
+```text
+app/        Modern Kotlin + Compose sample app (built in this alpha)
+legacy-app/ Original 2017 Android AAC sample (archive only, reference)
+docs/       Migration documentation and release notes
+```
+
+Only `app/` is built in the first alpha.
+`legacy-app/` is preserved for historical reference only.
 
 ## Migration docs
 
@@ -82,6 +131,14 @@ The modern version provides:
 - [x] Publish migration document bundle
 - [x] Add release notes and changelog section for v0.1.0-oss-alpha.1
 
+## Next milestones (planned, v0.2)
+
+- [ ] Add UI tests for article edit/delete interactions
+- [ ] Add `collectAsStateWithLifecycle` in Compose state collection
+- [ ] Replace demo placeholder with real screen recording (`docs/images/demo.gif`)
+- [ ] Improve Article detail validation UX
+- [ ] Prepare v0.2.0 roadmap and release notes
+
 ## Contributing
 
 Please read [`CONTRIBUTING.md`](CONTRIBUTING.md) and add small, focused changes.