docs: add developer, testing and performance guides; record M0 resultsv0.1.0

- DEVELOPER_GUIDE: workflow, how the tooling works (verified simulator
  behaviour), conventions and how to add devices.
- TESTING and PERFORMANCE: test layers, M0 results and measured numbers.
- FEASIBILITY: what M0 verified (watchdog 120k/240k, 10 MB storage in
  device profiles, unreliable monkeydo exit code, icon sizes).
- README status, new make targets and layout; CHANGELOG 0.1.0.
- Author/Summary headers on every document, including the original brief.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 39 insertions, 0 deletions

diff --git a/docs/PERFORMANCE.md b/docs/PERFORMANCE.md
new file mode 100644
index 0000000..2e668c2
--- /dev/null
+++ b/docs/PERFORMANCE.md
@@ -0,0 +1,39 @@
+<!--
+  Author:  cirakg & claude ai
+  Summary: Performance and memory budgets, how they are measured, and the measured numbers per milestone.
+-->
+# Performance
+
+The targets are in [README section 18](../README.md#18-performance-budgets). This document records how each number is measured, what it does and doesn't tell you, and the results.
+
+## How it is measured
+
+- **In-app start-up** (`startup_ms`): debug builds take `System.getTimer()` when the app object is created and again after the first complete frame, and print the difference (`source/util/Diag.mc`). It doesn't include the time the watch needs to load the program before the app object exists.
+- **Launch to first frame** (`first_frame_wall_ms`): `docker/scripts/app-diag.sh` measures the wall-clock time from launching `monkeydo` until the app's first-frame line appears. This includes the Java start of `monkeydo`, sending the program to the simulator and loading it, so it is mostly tool overhead; it's only useful to catch large regressions.
+- **Memory** (`mem_used_fraction`): `System.getSystemStats()` after the first frame: used memory divided by the memory the device gives watch apps.
+- **On the watch**: the numbers that matter are measured on your Forerunner 70 with a sideloaded debug build that shows them on screen. That arrives with M4; the simulator runs on your PC's CPU and says nothing about watch speed.
+
+`make perf` and `make memtest` fail when a value exceeds `tools/budgets.json`.
+
+## Budgets in force
+
+| Value | Budget | Why |
+| --- | --- | --- |
+| `startup_ms` | 3000 ms | Placeholder until M4 sets about 2× the measured baseline |
+| `first_frame_wall_ms` | 15000 ms | Regression guard only (tool overhead dominates) |
+| `mem_used_fraction` | 70 % | Hard limit, leaves room for spikes on the 512 KB watches |
+
+## Results
+
+### M0, 2026-10-18 (version 0.1.0, placeholder app)
+
+Simulator in Docker on your PC (12 cores), debug builds:
+
+| Device | Watch-app memory | In-app start-up | Launch to first frame | Memory used |
+| --- | --- | --- | --- | --- |
+| Forerunner 255S | 512 KB | 1 ms | 6.4 s | 1.3 % |
+| Venu Sq 2 | 768 KB | 3 ms | 6.5 s | 0.9 % |
+| Forerunner 70 | 768 KB | 0 ms | 6.7 s | 0.9 % |
+| Forerunner 965 | 768 KB | 6 ms | 6.8 s | 0.9 % |
+
+The placeholder app draws two lines of text, so these numbers only prove the measuring works. The first meaningful baseline comes with M4 (the real list and code screens). The signed package is 488 KB for all 72 products; a release build for one device is 7 to 15 KB.