docs: restructure server and web documentation into ADR files and a

routing table
2026-07-17 22:07:55 +08:00
parent f8494a44ca
commit 519aa35f1f
23 changed files with 710 additions and 654 deletions
@@ -0,0 +1,22 @@
+# ADR-0003: Keep Browser Testing Resources Project-Local
+
+Status: Accepted  
+Date: 2026-07-14
+
+## Context
+
+Browser tests and diagnostics run in a headless Debian development container. The toolchain needs repeatable versions and repository-scoped resources.
+
+## Decision
+
+- Use Playwright Test with bundled Chromium for repeatable E2E tests.
+- Keep E2E tests separate from `npm run check` because browser installation is an explicit setup step.
+- Run Chromium headlessly with profile isolation and sandboxing.
+- Store npm and browser caches under `.cache/`.
+- Store traces, screenshots, videos, and CLI output under `.artifacts/`.
+
+## Consequences
+
+- A fresh environment installs npm dependencies, browser libraries, and the pinned Chromium revision before browser work.
+- Browser failures can retain diagnostics without adding generated files to source control.
+- Repository configuration controls browser versions and artifact locations.