added known-bugs.ml

doc/known-bugs.md

@@ -0,0 +1,26 @@
+# Known bugs
+
+This document tracks currently known issues and limitations.
+
+## Open issues
+
+- **Prompt execution time is inaccurate in Windows Terminal (WSL)**
+	- **Status:** open, likely not fully fixable with the current Bash prompt model.
+	- **Symptoms:** in Windows Terminal, the displayed duration includes idle time
+		and typing time, and is consistently higher than real command execution time.
+		Behavior differs across terminal environments:
+		- In a native Linux terminal (including Linux shells launched through WSL),
+			timing starts when Enter is pressed and stops when the prompt is shown again.
+		- In Windows Terminal, timing appears to start/stop on prompt display events.
+	- **Technical context:** execution time is measured from a `DEBUG` trap plus
+		`PROMPT_COMMAND`, using `date +%s%N` deltas. In WSL + Windows Terminal,
+		timer precision and scheduling behavior can introduce jitter that does not
+		match wall-clock perception.
+	- **Likely cause:** Windows Terminal does not handle Bash timing-related events
+		in the same way as native Linux terminals.
+	- **Impact:** cosmetic/observability issue only. Commands are executed normally.
+	- **Workarounds:**
+		- Use a native Linux terminal under WSL (for example QTerminal, Terminator,
+			Konsole, etc.) to recover the expected Enter→prompt timing behavior.
+		- Use `/usr/bin/time -p <command>` (or `time <command>`) when accurate timing is needed.
+		- Treat prompt timing as an approximate indicator in this environment.