many changes

scripts/README.md

@@ -60,6 +60,42 @@ View Android logcat filtered for the app.
 ./scripts/logcat.sh
 ```
 
+## Traceability & Documentation
+
+### `extract-traces.ts`
+Extract requirement IDs (TRACES) from source code and generate a traceability matrix mapping requirements to implementation locations.
+
+```bash
+bun run traces                    # Generate markdown report
+bun run traces:json              # Generate JSON report
+bun run traces:markdown           # Save to docs/TRACEABILITY.md
+```
+
+The script scans all TypeScript, Svelte, and Rust files looking for `TRACES:` comments and generates a comprehensive mapping of:
+- Which code files implement which requirements
+- Line numbers and code context
+- Coverage summary by requirement type (UR, IR, DR, JA)
+
+Example TRACES comment in code:
+```typescript
+// TRACES: UR-005, UR-026 | DR-029
+function handlePlayback() { ... }
+```
+
+See [docs/TRACEABILITY.md](../docs/TRACEABILITY.md) for the latest generated mapping.
+
+### CI/CD Validation
+
+The traceability system is integrated with Gitea Actions CI/CD:
+- Automatically validates TRACES on every push and pull request
+- Enforces minimum 50% coverage threshold
+- Warns if new code lacks TRACES comments
+- Generates traceability reports automatically
+
+For details, see:
+- [Traceability CI Guide](../docs/TRACEABILITY_CI.md) - Full CI/CD documentation
+- [TRACES Quick Reference](../TRACES_QUICK_REF.md) - Quick guide for adding TRACES
+
 ## Utility Scripts
 
 ### `clean.sh`