hyochan · hyochan · Aug 7, 2026 · Aug 6, 2026 · Aug 6, 2026 · Aug 6, 2026
diff --git a/.claude/commands/audit-code.md b/.claude/commands/audit-code.md
@@ -0,0 +1,57 @@
+# Audit Code
+
+Audit the selected react-native-nitro-sound surface against its public API,
+Nitro contract, platform implementations, tests, examples, docs, and current
+toolchain requirements.
+
+## Usage
+
+```text
+/audit-code [path|api|ios|android|web|all]
+```
+
+An audit is read-only unless the user also asks for fixes.
+
+## Evidence Order
+
+1. Read `AGENTS.md` and `.codex/skills/nitro-sound-workflows/SKILL.md`.
+2. Resolve the requested paths and inspect their history when intent is unclear.
+3. Read `src/specs/*.nitro.ts`, `src/index.tsx`, Web implementation, hooks,
+   Swift, Kotlin, tests, example screens, README, FAQ, package metadata, and CI
+   that apply.
+4. For latest Nitro, React Native, Xcode, Android, or browser requirements,
+   verify official primary documentation rather than relying on memory.
+
+## Audit Lenses
+
+- Public exports, types, defaults, units, errors, and backward compatibility
+- Spec-to-generated-to-Swift/Kotlin wiring and codegen freshness
+- Promise settlement, listener add/remove behavior, cleanup, idempotency, and
+  rapid start/stop concurrency
+- Recorder/player state machines, seek, speed, volume, and playback completion
+- iOS permission, AVAudioSession, interruption, route, and lifecycle behavior
+- Android permission, MediaRecorder/MediaPlayer, audio focus, lifecycle, and ABI
+  build behavior
+- Web MediaRecorder support, object URL cleanup, timers, and browser fallbacks
+- Hooks cleanup and React lifecycle behavior
+- Unit tests, example coverage, device evidence, docs, migration notes, and CI
+- Generated-file policy, release safety, secret handling, and workflow permissions
+
+## Validate Findings
+
+Every finding must identify the affected path, concrete failure mode, evidence,
+severity, and smallest safe remediation. Confirm the finding against current
+code and reject speculative or cosmetic observations. Distinguish:
+
+- confirmed defect;
+- coverage or verification gap;
+- documentation drift;
+- current external compatibility risk;
+- blocked runtime claim requiring a device.
+
+## Output
+
+List findings in severity order, then verification gaps and a concise clean-area
+summary. If there are no actionable findings, say so and state which platforms
+or runtime lanes were not exercised. Do not modify code unless the user asked
+for implementation.
diff --git a/.claude/commands/commit.md b/.claude/commands/commit.md
@@ -12,7 +12,7 @@ Complete workflow: branch → commit → push → PR, for `hyochan/react-native-
 
 - `--push` / `-p`: Push to remote after commit
 - `--pr`: Create PR after push
-- `--all` / `-a`: Commit all changes at once
+- `--all` / `-a`: Commit all in-scope changes at once
 - `<path>`: Commit only specific path (e.g., `ios/`, `android/`, `src/`)
 
 ## Examples
@@ -53,6 +53,10 @@ git status
 git diff --name-only
 ```
 
+Preserve pre-existing user changes. Record staged, unstaged, and untracked
+files before staging, and never include unrelated files merely because they are
+present.
+
 ### 3. Stage Changes
 
 **Specific path:**
@@ -61,12 +65,14 @@ git diff --name-only
 git add <path>
 ```
 
-**All:**
+**All files owned by the requested change:**
 
 ```bash
-git add .
+git add <explicit-paths>
 ```
 
+Do not sweep-stage with `git add .` when unrelated user changes exist.
+
 ### 4. Review Staged Changes
 
 ```bash
@@ -83,24 +89,23 @@ git commit -m "$(cat <<'EOF'
 
 <body — what changed and why>
 
-🤖 Autogenerated by Claude (AI-native maintenance).
-Co-Authored-By: Claude <noreply@anthropic.com>
+🤖 AI-assisted maintenance.
 EOF
 )"
 ```
 
 **Types:**
 
-| Type       | Description                  |
-| ---------- | ---------------------------- |
-| `feat`     | New feature                  |
-| `fix`      | Bug fix                      |
-| `docs`     | Documentation                |
-| `refactor` | Code refactor                |
-| `chore`    | Maintenance / deps           |
-| `test`     | Tests                        |
-| `ci`       | CI / GitHub Actions          |
-| `perf`     | Performance                  |
+| Type       | Description         |
+| ---------- | ------------------- |
+| `feat`     | New feature         |
+| `fix`      | Bug fix             |
+| `docs`     | Documentation       |
+| `refactor` | Code refactor       |
+| `chore`    | Maintenance / deps  |
+| `test`     | Tests               |
+| `ci`       | CI / GitHub Actions |
+| `perf`     | Performance         |
 
 **Scopes:**
 
@@ -111,7 +116,7 @@ EOF
 - `example` — `example/`
 - `deps` — dependency bumps
 - `ci` — `.github/`
-- `skills` — `.claude/commands/`
+- `skills` — `.claude/`, `.codex/`, `AGENTS.md`, or AI context
 
 ### 6. Push to Remote
 
@@ -136,7 +141,7 @@ gh pr create --title "<type>(<scope>): <description>" --body "$(cat <<'EOF'
 - [ ] iOS example builds
 - [ ] Android example builds
 
-🤖 Autogenerated by Claude (AI-native maintenance).
+🤖 AI-assisted maintenance.
 EOF
 )"
 ```
@@ -167,16 +172,20 @@ gh pr edit <PR_NUMBER> --add-label "<label1>,<label2>"
 
 When touching multiple layers, commit in this order so reviewers can follow:
 
-| Order | Path                  | Description                                    |
-| ----- | --------------------- | ---------------------------------------------- |
-| 1     | `src/specs/*.nitro.ts`| Nitro spec changes (API surface)               |
-| 2     | `nitrogen/generated/` | Regenerated nitrogen code                      |
-| 3     | `ios/`                | iOS implementation                             |
-| 4     | `android/`            | Android implementation                         |
-| 5     | `src/` (non-spec)     | JS / TS wrapper                                |
-| 6     | `example/`            | Example app updates                            |
-| 7     | `docs/` / `README.md` | Documentation                                  |
-| 8     | `.claude/commands/`   | Skill updates                                  |
+| Order | Path                   | Description                      |
+| ----- | ---------------------- | -------------------------------- |
+| 1     | `src/specs/*.nitro.ts` | Nitro spec changes (API surface) |
+| 2     | `nitrogen/generated/`  | Regenerated nitrogen code        |
+| 3     | `ios/`                 | iOS implementation               |
+| 4     | `android/`             | Android implementation           |
+| 5     | `src/` (non-spec)      | JS / TS wrapper                  |
+| 6     | `example/`             | Example app updates              |
+| 7     | `docs/` / `README.md`  | Documentation                    |
+| 8     | `.claude/` / `.codex/` | AI workflow and skill updates    |
+
+Internal workflow-only changes under `.claude/`, `.codex/`, `AGENTS.md`, or
+`knowledge/_claude-context/` stay local unless the user explicitly asks to
+commit, push, or open a PR.
 
 ---
 
@@ -190,8 +199,7 @@ feat(nitro): add segmented recording API
 - Add RecordingSegmentConfig to Sound.nitro.ts
 - Introduce startRecorderSegmented() method
 
-🤖 Autogenerated by Claude (AI-native maintenance).
-Co-Authored-By: Claude <noreply@anthropic.com>
+🤖 AI-assisted maintenance.
 ```
 
 **iOS fix:**
@@ -204,17 +212,15 @@ coerces via a safe NaN/inf check before Int conversion.
 
 Closes #774
 
-🤖 Autogenerated by Claude (AI-native maintenance).
-Co-Authored-By: Claude <noreply@anthropic.com>
+🤖 AI-assisted maintenance.
 ```
 
 **Dep bump:**
 
 ```
-chore(deps): bump react-native-nitro-modules to 0.35.4
+chore(deps): bump react-native-nitro-modules to 0.36.5
 
 Minor patch release. No API changes.
 
-🤖 Autogenerated by Claude (AI-native maintenance).
-Co-Authored-By: Claude <noreply@anthropic.com>
+🤖 AI-assisted maintenance.
 ```
diff --git a/.claude/commands/compile-knowledge.md b/.claude/commands/compile-knowledge.md
@@ -1,16 +1,18 @@
 # Compile Knowledge Base
 
-Regenerate AI context files for `react-native-nitro-sound` so Claude (and other AI assistants) have an up-to-date, compact reference when working on this repo.
+Regenerate AI context files for `react-native-nitro-sound` so repository-aware
+assistants have an up-to-date, compact reference when working on this repo.
 
-> This repo is AI-native: Claude maintains it. That means the knowledge base IS the contract. Keep it fresh.
+> This repo is AI-native. The knowledge base is a compact operational contract
+> shared by Claude, Codex, and other assistants; keep it grounded in source.
 
 ## Output Files
 
-| Output           | Location                     | Purpose                                       |
-| ---------------- | ---------------------------- | --------------------------------------------- |
-| `context.md`     | `knowledge/_claude-context/` | Claude Code context for this repo             |
-| `llms.txt`       | `docs/public/` (if site)     | AI assistant quick reference                  |
-| `llms-full.txt`  | `docs/public/` (if site)     | AI assistant full reference                   |
+| Output          | Location                     | Purpose                           |
+| --------------- | ---------------------------- | --------------------------------- |
+| `context.md`    | `knowledge/_claude-context/` | Claude Code context for this repo |
+| `llms.txt`      | `docs/public/` (if site)     | AI assistant quick reference      |
+| `llms-full.txt` | `docs/public/` (if site)     | AI assistant full reference       |
 
 If there is no docs site yet, only `knowledge/_claude-context/context.md` is required.
 
@@ -30,7 +32,7 @@ Read, in this order:
 
 1. `README.md` — user-facing API overview
 2. `src/specs/*.nitro.ts` — the Nitro spec (source of truth for the native API)
-3. `src/index.ts` and `src/*.ts` — TypeScript wrapper
+3. `src/index.tsx`, `src/index.web.tsx`, and `src/*.ts` — TypeScript/Web wrappers
 4. `ios/*.swift` — iOS implementation notes
 5. `android/src/main/java/**/*.kt` — Android implementation notes
 6. `package.json` — current versions (nitro-modules, RN peer range)
@@ -46,48 +48,61 @@ Write to `knowledge/_claude-context/context.md` with these sections:
 > Autogenerated. Do not edit by hand. Run `/compile-knowledge`.
 
 ## Repo Purpose
+
 <1-paragraph summary>
 
 ## Architecture
+
 - Built on `react-native-nitro-modules` (Nitro)
 - iOS: AVAudioRecorder + AVAudioPlayer under Swift
 - Android: MediaRecorder + MediaPlayer under Kotlin
 - Spec-first: `src/specs/*.nitro.ts` → nitrogen → native bindings
 
 ## Current Versions
+
 - Library: <x.y.z>
 - Peer: react-native-nitro-modules >= <x.y.z>
 - React Native tested against: <x.y>
 - Nitrogen: <x.y.z>
 
 ## Public API
+
 <Enumerate from src/index.ts — one line per export>
 
 ## Nitro Spec Surface
-<Methods / properties from *.nitro.ts — signature only>
+
+<Methods / properties from \*.nitro.ts — signature only>
 
 ## Platform Notes
+
 ### iOS
+
 <Key behaviors, known pitfalls (e.g. Release build codec handling, std::optional<double> coercion)>
 
 ### Android
+
 <Key behaviors, foreground service, ndkVersion requirement, 16KB page size status>
 
 ## Known Issue Classes
+
 - Legacy bugs from `react-native-audio-recorder-player` (pre-Nitro) → label `🗑 stale-legacy`
 - Build failures on RN 0.81+ → track nitro-modules compatibility
 - iOS Release-only codec issues → check AudioSet patch history
 
 ## Release / Maintenance
-- Autogenerated commits & PRs by Claude (AI-native)
+
+- AI-assisted maintenance with explicit human direction and final authority
 - Hyo triages direction; mobile triggers via `/ai triage` on an issue → dispatches workflow
 
 ## Key Files
+
 - `src/specs/Sound.nitro.ts`
-- `src/index.ts`
-- `ios/HybridSound.swift`
-- `android/src/main/java/com/margelo/nitro/sound/HybridSound.kt`
+- `src/index.tsx`
+- `src/index.web.tsx`
+- `ios/Sound.swift`
+- `android/src/main/java/com/margelo/nitro/audiorecorderplayer/Sound.kt`
 - `.claude/commands/*.md` — AI-native workflow skills
+- `.codex/skills/*/SKILL.md` — canonical cross-agent skills
 ```
 
 ### 3. (Optional) Generate `llms.txt` / `llms-full.txt`
@@ -97,16 +112,18 @@ Only if a docs site is present under `docs/`.
 - `llms.txt` — 1 page: project summary, install command, peer deps, top-level API with 1-line descriptions
 - `llms-full.txt` — full concatenation of public docs + API signatures
 
-### 4. Commit
+### 4. Commit Only When Requested
+
+Keep generated context changes local unless the user explicitly requests a
+commit. When commit authority is present:
 
 ```bash
 git add knowledge/_claude-context/context.md
 # if generated:
 git add docs/public/llms.txt docs/public/llms-full.txt
 git commit -m "docs: recompile knowledge base
 
-🤖 Autogenerated by Claude (AI-native maintenance).
-Co-Authored-By: Claude <noreply@anthropic.com>"
+🤖 AI-assisted maintenance."
 ```
 
 ## SST (Single Source of Truth)