refactor(build): Centralize generated files and clean up project layout

- Task A: Centralized all generated code (assets, timeline) into a single  directory to create a single source of truth.
- Task A: Isolated test asset generation into a temporary build directory, preventing pollution of the main source tree.
- Task B: Vertically compacted all C/C++ source files by removing superfluous newlines.
- Task C: Created a top-level README.md with project overview and file descriptions.
- Task D: Moved non-essential documentation into a  directory to reduce root-level clutter.

1 files changed, 189 insertions, 0 deletions

diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md
new file mode 100644
index 0000000..7ae2e52
--- /dev/null
+++ b/doc/CONTRIBUTING.md
@@ -0,0 +1,189 @@
+# Contributing Guidelines
+
+This document outlines the conventions to follow when contributing to this project.
+
+## Commit Policy
+
+### Verify Build and Tests Before Committing
+
+Before preparing or proposing a commit, you **must** perform the following verifications to prevent regressions:
+
+1.  **MacOS / Linux (Native)**:
+    *   Build the project (debug or release).
+    *   Run the entire test suite (`ctest`).
+    *   Ensure all tests pass.
+
+2.  **Windows (Cross-Compilation)**:
+    *   If `mingw-w64` is installed on your system, you **must** also verify the Windows build.
+    *   Run `./scripts/build_win.sh`.
+    *   Ensure the build succeeds and produces the `demo64k_packed.exe` binary.
+    *   Check the size report to ensure no unexpected bloat.
+
+Refer to the "Testing" and "Windows Cross-Compilation" sections in `HOWTO.md` for detailed instructions.
+
+### Format Code Before Committing
+
+All code **must** be formatted using `clang-format` before committing. This ensures a consistent coding style across the entire codebase.
+
+To format your code, run the following command from the project root:
+```bash
+clang-format -i $(git ls-files | grep -E '\.(h|cc)$' | grep -vE '^(assets|archive|third_party)/')
+```
+
+Refer to the `.clang-format` file in the project root for the specific style rules.
+
+### Ensure Newline at End of File
+
+All source files (`.h`, `.cc`, `.cpp`, etc.) must end with a newline character. This prevents "No newline at end of file" errors from linters and ensures consistent file handling.
+
+### Source File Headers
+
+Every source file (`.h`, `.cc`) must begin with a concise 3-line comment header describing its purpose.
+
+Example:
+```cpp
+// This file is part of the 64k demo project.
+// It implements the core audio synthesis engine.
+// This is not a user-facing header, but an internal one.
+```
+
+### Function and method comments
+
+Functions and methods, especially if they are internal non user-facing,
+should at least have a 1-line comment describing what they do or their
+how/when they should be called. Except if they are just 1-line function
+or very very short, obvious ones.
+
+### '#endif' directive
+
+The closing #endif directive must recall the corresponding opening #ifdef
+clause they are closing
+
+Example:
+```cpp
+#ifdef MY_TAG
+...some code
+#endif /* MY TAG */
+```
+
+We must also prefer '#if defined(MY_QUITE_LONG_TAG)' over '#ifdef MY_QUITE_LONG_TAG'
+especially if there's a risk of having later something like:
+```cpp
+#if defined(MY_TAG_1) && !defined(MY_TAG_2)
+```
+
+### use and abuse 'const' directives
+
+Especially for local variable, use 'const' qualification as much as
+possible.
+
+As an example, don't use:
+```cpp
+StructA variable_name = StructA(...);
+```
+
+but prefer instead:
+```cpp
+const StructA variable_name = StructA(...);
+```
+
+if variable_name is not mutated afterward.
+
+Also: pass parameter as "const ref" as much as possible
+(```const Struct& param``` instead of pointers or non-const refs)
+
+### put spaces around code and operators (cosmetics)
+
+Don't compact the code to much horizontally, and prefer adding extra
+spaces around code and operators.
+
+Example:
+```cpp
+const bool v = my_variable && (my_function() / 3. > (1. / x));
+const y = function_call(3, x, 2.);
+for (int x = 0; x < 24; ++x) { ... }
+```
+
+instead of
+```cpp
+const bool v=my_variable&&my_function()/3.>(1./x);
+const y = function_call(3,x,2);
+for(int x=0;x<24;++x){ ... }
+```
+
+### prefer prefixed incrementation over suffixed
+
+Use pre-incrementation:
+```cpp
+++x
+```
+
+instead of post-incrementation:
+
+```cpp
+x++
+```
+
+### use extra () for boolean operations
+
+Even if they are not strictly needed due to operator precedence rules,
+prefer adding extra ()'s around tests for clarity, with parcimony.
+
+### c++ cast
+
+don't use reinterpret_cast<>, static_cast<> or const_cast<>.
+
+### pointer declaration
+
+prefer ```const T* name``` to ```const T *name```.
+
+### 'auto' type
+
+Don't use 'auto' as type, unless for complex iterators or very complex
+types.
+
+### don't use trailing whitespaces
+
+don't.
+
+### no missing \newline at the end of file
+
+make sure each file has a final \n newline.
+
+### c++ keyword indentation:
+
+The keyword 'public', 'protected', 'private' should be intended 1 character
+less than the methods.
+
+Example:
+```cpp
+ private:
+  int field_;
+```
+
+instead of:
+```cpp
+private:
+  int field_;
+```
+
+### vertical space
+
+keep the code compact vertically. That includes shader code, too.
+Use only one statement per line.
+
+### finally
+
+Make sure everything is reflected in clang-format.
+
+## Development Protocols
+
+### Adding a New Visual Effect
+
+1.  **Implement**: Create or update a class in `src/gpu/demo_effects.cc` (and declare in `demo_effects.h`) that inherits from `Effect`.
+    -   Implement `init()` for one-time resource setup (e.g., using the asset system).
+    -   Implement `compute()` if you need GPU-side physics or state updates.
+    -   Implement `render()` to record WebGPU draw commands.
+2.  **Register**: Add an `EFFECT` entry to `assets/demo.seq` specifying the class name, start/end times, and any constructor arguments.
+3.  **Verify**: Build with `DEMO_ALL_OPTIONS=ON` and use `--seek` to test your effect at its specific timestamp.
+