docs: clarify internal engineering guidance

Author: chenglou

DEVELOPMENT.md

@@ -13,14 +13,14 @@ bun install
 - `bun run check` — typecheck, lint, and dead-code scan (`knip`)
 - `bun test` — small durable invariant suite
 
-### Packaging And Release Confidence
+### Packaging And Release
 
 - `bun run build:package` — emit `dist/` for the published ESM package
 - `bun run package-smoke-test` — pack the tarball and verify temporary JS + TS consumers
 - `bun run site:build` — build the static demo site into `site/`
 - `bun run generate:bidi-data` — refresh the checked-in simplified Unicode bidi ranges
 
-`prepack` also rebuilds `dist/` through plain `tsc`, so keep runtime `.js` specifiers honest in source imports.
+`prepack` also rebuilds `dist/` through plain `tsc`, so source imports need `.js` specifiers that remain valid in the emitted files.
 
 ### Browser Accuracy And Benchmarking
 
@@ -32,15 +32,15 @@ bun install
 - `bun run accuracy-snapshot:firefox`
 - `bun run benchmark-check` — Chrome benchmark snapshot; default is the median of 3 full page runs, use `--runs=1` for a quick local check
 - `bun run benchmark-check:safari`
-- `bun run pre-wrap-check` — compact batched browser oracle for `{ whiteSpace: 'pre-wrap' }`
-- `bun run keep-all-check` — compact batched browser oracle for `{ wordBreak: 'keep-all' }`, including mixed-script no-space canaries
-- `bun run symbol-check` — compact batched Chrome + Safari oracle for no-space symbol runs inside long words
-- `bun run letter-spacing-check` — compact batched Chrome + Safari oracle for `{ letterSpacing }`
-- `bun run letter-spacing-snapshot` — refresh `accuracy/letter-spacing.json` from the Chrome + Safari compact `{ letterSpacing }` oracle
-- `bun run probe-check` — smaller browser probe/diagnostic entrypoint
+- `bun run pre-wrap-check` — small batched browser check for `{ whiteSpace: 'pre-wrap' }`
+- `bun run keep-all-check` — small batched browser check for `{ wordBreak: 'keep-all' }`, including mixed-script text without spaces
+- `bun run symbol-check` — small batched Chrome + Safari check for symbol runs inside long words
+- `bun run letter-spacing-check` — small batched Chrome + Safari check for `{ letterSpacing }`
+- `bun run letter-spacing-snapshot` — refresh `accuracy/letter-spacing.json` from the Chrome + Safari `{ letterSpacing }` check
+- `bun run probe-check` — smaller browser diagnostic
 - `bun run probe-check:safari`
 
-Probe output includes a break trace on first-break mismatches. `sN:gM` is a segment/grapheme position; `[ours]` and `[browser]` mark the competing boundaries. For extractor-sensitive Safari cases, cross-check `--method=span` before changing the engine.
+When a probe finds a first-break mismatch, the report includes a short trace. `sN:gM` identifies a segment and grapheme; `[ours]` and `[browser]` identify the competing break positions. Safari `Range` extraction can be wrong around preserved whitespace and URL queries even when the rendered height is correct, so compare `--method=span` before changing the engine.
 
 ### Corpus Tooling
 
@@ -50,7 +50,7 @@ Probe output includes a break trace on first-break mismatches. `sN:gM` is a segm
 - `bun run corpus-sweep:safari` — maintained Safari `step=10` corpus width sweep
 - `bun run corpus-font-matrix` — same corpus under alternate fonts
 - `bun run corpus-font-matrix:safari`
-- `bun run corpus-taxonomy` — classify a mismatch field into steering buckets
+- `bun run corpus-taxonomy` — group corpus mismatches by likely cause
 - `bun run corpus-status` — rebuild `corpora/dashboard.json`
 - `bun run corpus-status:refresh` — refresh Chrome and Safari `step=10` sweeps, then the corpus dashboard
 
@@ -67,16 +67,16 @@ Probe output includes a break trace on first-break mismatches. `sN:gM` is a segm
 
 ## Current Dashboards And Snapshots
 
-Use these for the current checked-in picture:
+Use these for the current checked-in results:
 
 - [status/dashboard.json](status/dashboard.json) — machine-readable main dashboard
 - [accuracy/chrome.json](accuracy/chrome.json), [accuracy/safari.json](accuracy/safari.json), [accuracy/firefox.json](accuracy/firefox.json) — raw browser accuracy rows
-- [accuracy/letter-spacing.json](accuracy/letter-spacing.json) — compact Chrome + Safari `{ letterSpacing }` oracle snapshot
+- [accuracy/letter-spacing.json](accuracy/letter-spacing.json) — results from the small Chrome + Safari `{ letterSpacing }` check
 - [benchmarks/chrome.json](benchmarks/chrome.json), [benchmarks/safari.json](benchmarks/safari.json) — raw benchmark snapshots
 - [corpora/dashboard.json](corpora/dashboard.json) — machine-readable corpus dashboard
 - [corpora/chrome-step10.json](corpora/chrome-step10.json), [corpora/safari-step10.json](corpora/safari-step10.json) — checked-in browser `step=10` corpus sweep snapshots
 
-[PLATFORM_BUGS.md](PLATFORM_BUGS.md) is the current browser/OS issue and workaround ledger. [RESEARCH.md](RESEARCH.md) keeps durable findings and rejected approaches; it is not a source for current counts or tracker status.
+[PLATFORM_BUGS.md](PLATFORM_BUGS.md) lists current browser and OS issues and their workarounds. [RESEARCH.md](RESEARCH.md) keeps durable findings and rejected approaches; it is not a source for current counts or issue status.
 
 ## Deep Profiling
 
@@ -87,4 +87,4 @@ For one-off performance and memory work, start with `bun start` and an isolated,
 - Use heap sampling for allocation churn.
 - Diff forced-GC heap snapshots for retained memory.
 
-Bun/Node microbenchmarks are useful for cheap hypotheses, but browser behavior needs browser evidence.
+Bun/Node microbenchmarks are useful for quick experiments, but browser behavior needs browser measurements.