polish Vix internals documentation

Author: GaspardKirira

internals/architecture.md

@@ -1,6 +1,14 @@
 # Architecture
 
-Vix is not only an HTTP framework. Internally, it is composed of several layers: developer workflow, runtime core, application APIs, module system, diagnostics, build pipeline, and production runtime.
+Vix is not only an HTTP framework.
+Internally, it is composed of several layers:
+- developer workflow,
+- runtime core,
+- application APIs,
+- module system,
+- diagnostics,
+- build pipeline,
+- and production runtime.
 
 ```txt
 CLI → project detection → build/run pipeline → runtime modules → application
@@ -51,11 +59,11 @@ Application code
 
 ## Execution modes
 
-| Mode | Used when | Build strategy |
-|------|-----------|---------------|
-| Script mode | `vix run main.cpp` — one .cpp file | Direct compile |
-| Project mode | CMakeLists.txt, vix.json, src/ present | CMake / project build |
-| Manifest mode | `app.vix` manifest present | Manifest-described build |
+| Mode          | Used when                              | Build strategy                    |
+|---------------|---------------------------------------- |-----------------------------------|
+| Script mode   | Running one `.cpp` file with `vix run`. | Uses direct compilation.          |
+| Project mode  | `CMakeLists.txt`, `vix.json`, or `src/` is present. | Uses the project build system. |
+| Manifest mode | An `app.vix` manifest is present.      | Uses the manifest-defined build.  |
 
 ## Public API layer
 
@@ -167,17 +175,19 @@ HTTP may use JSON. JSON should not depend on HTTP. Avoid circular dependencies.
 
 ## Design principles
 
-1. **Application-first** — start from what you want to build, not from build config
-2. **Explicit C++** — ownership, lifetimes, types, and errors remain understandable
-3. **Fast path for simple cases** — one file should be fast to run
-4. **Modules are focused** — each module solves a clear problem
-5. **Reliability matters** — safe errors, durable operations, retries, health checks
-6. **No unnecessary magic** — the system should remain debuggable
+1. **Application-first:** start from what you want to build, not from build configuration.
+2. **Explicit C++:** ownership, lifetimes, types, and errors remain understandable.
+3. **Fast path for simple cases:** a single file should run quickly.
+4. **Modules are focused:** each module solves a clear, well-defined problem.
+5. **Reliability matters:** handle errors safely with durable operations, retries, and health checks.
+6. **No unnecessary magic:** the system should remain transparent and debuggable.
 
 ## What you should remember
 
-The main layers are: CLI workflow → public APIs → runtime modules → core foundation → system layer.
+The main layers are:
+CLI workflow → public APIs → runtime modules → core foundation → system layer.
 
-The core idea: **make C++ applications easier to build without hiding C++.**
+The core idea:
+**make C++ applications easier to build without hiding C++.**
 
 Next: [Runtime Model](/internals/runtime-model)

internals/cache-system.md

@@ -22,12 +22,12 @@ Goal: **do not repeat expensive work when the inputs did not change.**
 
 ## Main cache areas
 
-| Area | Path | Purpose |
-|------|------|---------|
-| Registry index | `~/.vix/registry/index` | Package metadata |
-| Store cache | `~/.vix/store/git` | Downloaded packages and commits |
-| Global packages | `~/.vix/global` | Globally installed packages |
-| Artifact cache | `~/.vix/cache/build` | Build artifacts |
+| Area            | Path                    | Purpose                                 |
+|-----------------|-------------------------|-----------------------------------------|
+| Registry index  | `~/.vix/registry/index` | Stores package metadata.                |
+| Store cache     | `~/.vix/store/git`      | Stores downloaded packages and commits. |
+| Global packages | `~/.vix/global`         | Stores globally installed packages.     |
+| Artifact cache  | `~/.vix/cache/build`    | Stores build artifacts.                 |
 
 ## vix info
 
@@ -169,11 +169,11 @@ Cache accelerates repeated work. Source code, manifests, lock files, and package
 
 ## Design principles
 
-1. **Invisible when healthy** — developers shouldn't think about cache during normal work
-2. **Visible when debugging** — `vix info` exposes cache state clearly
-3. **Safe** — never reuse if inputs don't match
-4. **Rebuildable** — artifact cache can always be regenerated
-5. **Correctness over speed** — a fast but wrong cache is worse than no cache
+1. **Invisible when healthy:** developers should not think about cache during normal work.
+2. **Visible when debugging:** `vix info` exposes cache state clearly.
+3. **Safe:** never reuse cached data when inputs do not match.
+4. **Rebuildable:** artifact cache can always be regenerated.
+5. **Correctness over speed:** a fast but wrong cache is worse than no cache.
 
 ## What you should remember
 
@@ -184,7 +184,8 @@ Cache accelerates repeated work. Source code, manifests, lock files, and package
 ~/.vix/cache/build     → build artifacts
 ```
 
-Use `vix info` to inspect cache state. Use `vix --version` and the failing command for bug reports.
+Use `vix info` to inspect cache state.
+Use `vix --version` and the failing command for bug reports.
 
 The core idea: **cache makes Vix faster, but correctness always comes first.**
 

internals/design-decisions.md

@@ -8,22 +8,22 @@ C++ should feel direct for application development without losing its power.
 
 ## Summary of key decisions
 
-| Decision | Reason |
-|----------|--------|
-| Runtime, not new language | Keep C++ power and improve workflow |
-| Direct compile | Make single-file C++ fast and simple |
-| CMake support | Keep real project builds correct |
-| Explicit APIs | Avoid hidden behavior |
-| Public module headers | Keep docs stable and learnable |
-| Middleware | Keep shared logic out of routes |
-| Config via .env | Change runtime behavior without recompiling |
-| Prepared statements | Safer database access |
-| Cache is temporary | Avoid treating cache as durable state |
-| Sync persists first | Prevent lost operations |
-| P2P as transport | Keep connection logic separate from delivery logic |
-| Diagnostics | Make C++ errors easier to act on |
-| Benchmark mode | Measure performance with less noise |
-| Native deployment | Run as a normal Linux service |
+| Decision                  | Reason                                           |
+|---------------------------|--------------------------------------------------|
+| Runtime, not new language | Keeps the power of C++ while improving workflow. |
+| Direct compile            | Makes single-file C++ fast and simple.           |
+| CMake support             | Keeps real project builds correct and portable.  |
+| Explicit APIs             | Avoids hidden behavior and unexpected magic.     |
+| Public module headers     | Keeps documentation stable and learnable.        |
+| Middleware                | Keeps shared logic out of route handlers.        |
+| Config via `.env`         | Changes runtime behavior without recompiling.    |
+| Prepared statements       | Provides safer database access.                  |
+| Cache is temporary        | Avoids treating cache as durable state.          |
+| Sync persists first       | Prevents local operations from being lost.       |
+| P2P as transport          | Separates connection logic from delivery logic.  |
+| Diagnostics               | Makes C++ errors easier to understand and fix.   |
+| Benchmark mode            | Measures performance with less runtime noise.    |
+| Native deployment         | Runs applications as normal Linux services.      |
 
 ## 1. Vix is a runtime, not a new language
 
@@ -32,6 +32,7 @@ Vix keeps C++, improves the workflow around it:
 ```cpp
 #include <vix.hpp>
 using namespace vix;
+
 int main()
 {
   App app;
@@ -274,9 +275,22 @@ Production readiness is part of normal app design.
 
 ## 26. Logs must be safe
 
-Good logs: startup, request method/path, error code, duration, sync failure, P2P stats.
+Good logs include:
+
+- Startup events
+- Request method and path
+- Error codes
+- Request duration
+- Sync failures
+- P2P statistics
+
+Never log:
 
-Never log: passwords, tokens, cookies, private keys, authorization headers.
+- Passwords
+- Tokens
+- Cookies
+- Private keys
+- Authorization headers
 
 ## 27. One-file docs are intentional
 
@@ -308,7 +322,8 @@ Vix is designed around a balance:
 simple workflow + explicit C++ + production reliability
 ```
 
-The core design idea: **make C++ application development feel direct without hiding how the system works.**
+The core design idea:
+**make C++ application development feel direct without hiding how the system works.**
 
 Vix helps developers move from:
 

internals/direct-compile.md

@@ -1,14 +1,16 @@
 # Direct Compile
 
-Direct compile is the fast path behind `vix run main.cpp`. It allows a single C++ file to be compiled and run immediately.
+Direct compile is the fast path behind `vix run main.cpp`.
+It allows a single C++ file to be compiled and run immediately.
 
 ```txt
 main.cpp → detect script mode → compile directly → cache binary → run
 ```
 
 ## The problem direct compile solves
 
-Traditional C++ requires build setup even for small files. Direct compile removes this friction:
+Traditional C++ requires build setup even for small files.
+Direct compile removes this friction:
 
 ```bash
 mkdir -p ~/tmp/vix-demo
@@ -27,10 +29,10 @@ read CLI arguments → detect that main.cpp is a file → enter script mode
 
 ## Script mode vs project mode
 
-| Mode | Best for | Build strategy |
-|------|----------|---------------|
-| Direct compile | One .cpp file | Compile file directly |
-| Project build | Real app/project | Use project config and build system |
+| Mode           | Best for                   | Build strategy                         |
+|----------------|----------------------------|----------------------------------------|
+| Direct compile | A single `.cpp` file.      | Compiles the file directly.            |
+| Project build  | A real application project.| Uses project config and build system.  |
 
 Direct compile answers: "Can I quickly compile and run this one file?"
 
@@ -120,7 +122,8 @@ Docs examples should use public headers, not internal repository paths.
 
 ## Working directory
 
-The program runs from the current working directory. Relative paths depend on where you run the command:
+The program runs from the current working directory.
+Relative paths depend on where you run the command:
 
 ```cpp
 res.file("public/index.html");  // looks for ./public/index.html
@@ -204,11 +207,11 @@ cd ~/my-app && vix run main.cpp
 
 ## Design principles
 
-1. **Fast simple path** — `vix run main.cpp` should just work
-2. **Keep C++ explicit** — Vix makes the workflow smoother, not invisible
-3. **Cache safely** — never reuse stale binaries incorrectly
-4. **Fall back when needed** — project mode exists for complex cases
-5. **Good diagnostics** — when compilation fails, explain what to try next
+1. **Fast simple path:** `vix run main.cpp` should just work.
+2. **Keep C++ explicit:** Vix makes the workflow smoother, not invisible.
+3. **Cache safely:** never reuse stale binaries incorrectly.
+4. **Fall back when needed:** project mode exists for complex cases.
+5. **Good diagnostics:** when compilation fails, explain what to try next.
 
 ## What you should remember
 

internals/error-diagnostics.md

@@ -15,11 +15,20 @@ undefined reference to ...
 terminate called without an active exception
 ```
 
-and not know what to do. Vix diagnostics answer three questions: **what happened, where, and what to try next.**
+and not know what to do. Vix diagnostics answer three questions:
+**what happened, where, and what to try next.**
 
 ## Diagnostic layers
 
-Vix handles: compile errors, link errors, build system errors, runtime crashes, sanitizer reports, known C++ mistakes, unclassified failures.
+Vix handles:
+
+- Compile errors
+- Link errors
+- Build system errors
+- Runtime crashes
+- Sanitizer reports
+- Known C++ mistakes
+- Unclassified failures
 
 ## Build error flow
 
@@ -46,6 +55,7 @@ main.cpp:8:3
 ```txt
 error: expected ';'
 hint: missing ';' (often the previous line)
+
 error: use of undeclared identifier 'std'
 hint: std is not visible here (include the required standard header)
 ```
@@ -129,8 +139,10 @@ hint: index out of bounds (check vector/string indexing)
 ```txt
 runtime error: heap-buffer-overflow
 hint: heap out-of-bounds (check vector/string indexing and sizes)
+
 runtime error: heap-use-after-free
 hint: you used memory after it was freed (dangling pointer/reference)
+
 runtime error: double free
 hint: the same allocation was freed twice (double owner or duplicate delete/free)
 ```
@@ -221,21 +233,26 @@ parsed compiler errors → try specialized rules → if handled: print friendly
 
 ## Design principles
 
-1. First error matters most — show it clearly
-2. Show source context — code frames over long logs
-3. Hide repeated noise — deduplicate
-4. Prefer specific explanations — "division by zero" beats "runtime error"
-5. Give next action — include a practical hint
-6. Keep fallback honest — show raw log if unknown
-7. Do not hide C++ — explain errors, don't remove the need to understand them
+1. **First error matters most:** show the first meaningful error clearly.
+2. **Show source context:** prefer code frames over long raw logs.
+3. **Hide repeated noise:** deduplicate repeated diagnostics.
+4. **Prefer specific explanations:** `division by zero` is better than `runtime error`.
+5. **Give the next action:** include a practical hint when possible.
+6. **Keep fallback honest:** show the raw log when the error is unknown.
+7. **Do not hide C++:** explain errors without removing the need to understand them.
 
 ## What you should remember
 
 ```txt
 raw log → parse → classify → deduplicate → code frame → hint
 ```
 
-Vix handles: compiler errors, linker errors, runtime crashes, sanitizer reports, common C++ mistakes.
+Vix handles:
+- compiler errors,
+- linker errors,
+- runtime crashes,
+- sanitizer reports,
+- common C++ mistakes.
 
 The core idea: **a good error message should teach the next step.**