add page cache with read-ahead and dirty writeback, file-backed and anonymous mmap with CoW, VAD-based virtual memory replacing the old user region model, PFN database with eviction and reclaim, file identity for cross-open section sharing, FAT32 path cache and per-file cluster chain cache, serial.sys for COM1 keyboard input, xHCI MSI with INTx and polled fallback, PciEnableMsiAuto, waitable input queue, KeWaitForAnyEvent, per-process thread info syscall, expanded kernel stats (PFN/PTE/VAD/file-cache/disk), pool allocation tags, async I/O user buffer locking, file flush on close, add docs.md.

docs.md

@@ -0,0 +1,93 @@
+# nt-lite development notes
+
+nt-lite is a clean-design hobby kernel. It is not a stable compatibility platform. Prefer the right design over preserving old APIs, shims, or compatibility aliases.
+
+## Principles
+
+- Break old code when the new model is better.
+- Do not keep compatibility paths unless they have a clear purpose.
+- Plan the model before writing the patch.
+- Make one architectural move at a time.
+- Delete stale paths once the real path works.
+- Prefer compile failures over wrappers that hide stale users.
+- Keep the tree internally consistent.
+- Keep one canonical API for each operation.
+- A small patch can still represent the final model.
+- Do not land temporary architecture just to make a feature appear to work.
+- Put policy in the layer that owns it.
+- Shared state should have one clear owner.
+
+## Workflow
+
+- Keep patches reviewable.
+- Boot-test meaningful changes.
+- Add diagnostics before optimizing.
+- Use logs, counters, and assertions instead of guessing.
+- Remove stale comments and dead code as part of the same cleanup.
+- Treat a fallback as either a supported mode or delete it before it becomes permanent.
+- Ask design questions before changing API shape, object lifetime, ownership, cancellation, persistence, or compatibility behavior.
+- Do not add a side path to avoid updating callers.
+- When changing an interface, update every caller in the same patch.
+- When adding a build artifact, update build, packaging, copy, and runtime discovery paths in the same patch.
+- Do not count apply checks or syntax-only checks as a real build.
+- Be precise about what was actually validated.
+- If behavior can be tested cheaply, include a focused runtime test or a visible diagnostic.
+- Prefer counters that prove both success and non-use.
+
+## Breaking changes
+
+Breaking changes are allowed. When making one:
+
+1. Define the new model.
+2. Move every user to it.
+3. Delete the old path.
+4. Bump ABI or version constants when a contract changes.
+5. Let stale users fail to compile.
+
+## Patch expectations for AI agents
+
+- Generate patches from the repository root.
+- Paths must be rooted as `code/...`.
+- `git apply <patch>` should work from the repository root.
+- Do not require `--directory=code`.
+- Keep generated artifacts out of the source tree unless requested.
+- When asked to provide the full tree, also provide the patch.
+- The patch is for review; the full tree is for reproducing the exact baseline.
+- Avoid optimistic claims.
+- Say exactly whether a change was apply-checked, syntax-checked, built, booted, or runtime-tested.
+- Do not introduce compatibility aliases unless they are intentionally supported API.
+
+## Comment style
+
+- Comments explain why, not what the next line already says.
+- Use `//` comments only.
+- Use sentence case.
+- End every sentence with a period.
+- Every owned source file should start with a short file comment.
+- Every function should have a comment, even if it is only a one-line summary.
+- Keep the tone practical and technical.
+- Humor is allowed rarely, but never instead of the real explanation.
+- Debugging history belongs in comments only when it explains a lasting constraint.
+- Document workarounds by saying what looks strange, why it is necessary, and what breaks if it is simplified.
+- Avoid trailing comments except for flags, bitfields, register tables, and packed layouts.
+- Keep real limitations as normal prose.
+
+## Development lessons
+
+- Ask before changing the shape of an API or the ownership model behind it.
+- The right model matters more than minimizing the diff.
+- A patch should be small enough to review, but not so small that it creates a temporary model.
+- If a compatibility path is not meant to stay, do not add it.
+- If the old path is replaced, remove it.
+- Ergonomics matter. A clean API should not make common calls annoying.
+- Debug by evidence, not by the subsystem that changed most recently.
+- Poison values, fault addresses, counters, and reproduction steps are more useful than guesses.
+- Performance fixes need tail-latency checks, not only average throughput.
+- Diagnostics must reach every active output path that developers rely on.
+- Runtime tests should clean up after themselves and say clearly when they use temporary data.
+- A passing test should leave the system in a sane state, not only print `PASS`.
+- Build integration is part of the feature.
+- Packaging mistakes are real bugs, not clerical issues.
+- When a change crosses layers, verify every layer that knows about the new object, file, syscall, or artifact.
+- Prefer finishing the feature the user needs over endlessly polishing the audit around it.
+- Do not hide uncertainty. Say what was checked and what still needs a real build or boot test.