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, 57 insertions, 0 deletions

diff --git a/doc/ASSET_SYSTEM.md b/doc/ASSET_SYSTEM.md
new file mode 100644
index 0000000..250be07
--- /dev/null
+++ b/doc/ASSET_SYSTEM.md
@@ -0,0 +1,57 @@
+# compact asset system for the 64k demo
+
+This file describe the features of a compact asset system used in the demo.
+
+The idea is the following:
+
+# run-time asset retrieval:
+ All assets are const byte arrays. We need a 'const uint8_t* GetAsset(uint16 asset_id)'
+ The asset ID is defined in a 'assets.h' header, generated during the final
+ compile by our own assembling tool. assets.h needs to be re-generated
+ infrequently.
+
+# assembling the assets:
+
+## description file 'assets.txt'
+ All assets are just files in the assets/final/ directory
+ This directory needs a assets.txt text file to describe the asset files.
+ Each line of the assets.txt file contain, comma-separated:
+   * the name of the asset (that will be used by the #define in assets.h),
+   * the name of the file associated
+   * the compression to use for this asset (default NONE. More options later)
+   * and optionally the type of assets.
+
+## example For instance, a line in assets.txt will read:
+
+SAMPLE_142, sample_142.spec, NONE, "this is a drum kick sample"
+
+This instructs the final assembled file assets.h to have a code line:
+  #define ASSET_SAMPLE_142 6323
+
+(6323 is just an associated id)
+
+(or an enum instead of #define's)
+
+so that we can call
+```
+#include "asset.h"
+const uint8_t* mysample = GetAsset(ASSET_SAMPLE_142);
+...etc
+```
+
+(if we use enums, GetAssert() signature needs to be changed)
+
+### Lazy decompression
+to save memory some assets can be decompressed 'at retrieval time' but kept
+compressed in memory until then.
+This means that we need a 'void DropAsset(uint16 asset_id, const uint8* asset)'
+method to handle memory disallocation depending on the asset type.
+
+### assembling tool
+
+we need a simple tool that:
+  * takes the assets.txt file and parse it
+  * generates the assets.h file with asset enums
+  * generates the assets_data.cc file with all the data
+  * put these in the source tree
+  * this process needs a script for automation