feat: Update README files to provide detailed project structure and usage instructions for Wolfenstein 3D workspace

Signed-off-by: Hans Kokx <hans.d.kokx@gmail.com>

packages/wolf_3d_assets/README.md

@@ -0,0 +1,52 @@
+# wolf_3d_assets
+
+Shared asset package that exposes Wolfenstein 3D game-data trees for workspace apps.
+
+## What This Package Is
+
+`wolf_3d_assets` is a content package used by Flutter hosts to bundle known asset directories.
+
+This package does not expose runtime logic APIs; it exists to provide structured asset roots consumed by hosts and tooling.
+
+## Current Asset Layout
+
+Configured asset roots (see `pubspec.yaml`):
+
+- `assets/retail/`
+- `assets/shareware/`
+- `assets/sod/shareware/`
+
+## Setup
+
+From this directory:
+
+```bash
+flutter pub get
+```
+
+## How Hosts Consume It
+
+- Dependent Flutter apps/packages include `wolf_3d_assets` as a workspace dependency.
+- Flutter build tooling includes directories listed in this package `pubspec.yaml`.
+- Runtime data discovery/selection is handled by host and engine packages.
+
+## Maintenance Guidelines
+
+When updating assets:
+
+1. Preserve directory structure conventions by game/version.
+2. Update `pubspec.yaml` asset entries if new top-level roots are introduced.
+3. Validate that host apps still discover and load the updated data sets.
+
+## Verification
+
+Because this is a content package, verification is integration-focused:
+
+- run `apps/wolf_3d_gui` and confirm expected data appears,
+- run `apps/wolf_3d_cli` with explicit `--data-directory` when testing local trees.
+
+## Related Modules
+
+- Core runtime: [`../wolf_3d_dart/README.md`](../wolf_3d_dart/README.md)
+- Flutter integration package: [`../wolf_3d_flutter/README.md`](../wolf_3d_flutter/README.md)
+- Workspace overview: [`../../README.md`](../../README.md)

packages/wolf_3d_dart/README.md

@@ -0,0 +1,70 @@
+# wolf_3d_dart
+
+Core non-Flutter Wolfenstein 3D runtime package used by both CLI and Flutter hosts.
+
+## What This Package Provides
+
+`wolf_3d_dart` contains the platform-neutral simulation/runtime surface:
+
+- engine and session lifecycle,
+- game-data loading and data types,
+- renderer backends and frame-buffer abstractions,
+- menu state/navigation models,
+- input/audio host abstractions,
+- entity and gameplay logic.
+
+## Public Library Surfaces
+
+Primary entry libraries in `lib/`:
+
+- `wolf_3d_engine.dart` — engine exports and runtime contracts.
+- `wolf_3d_data.dart` / `wolf_3d_data_types.dart` — game-data discovery and DTOs.
+- `wolf_3d_renderer.dart` — rendering/backends integration points.
+- `wolf_3d_audio.dart` — audio interfaces and host backends.
+- `wolf_3d_input.dart` — input abstractions.
+- `wolf_3d_menu.dart` — menu models/managers.
+- `wolf_3d_host.dart` — host-level glue contracts.
+
+Implementation details live under `lib/src/`.
+
+## Setup
+
+From this directory:
+
+```bash
+dart pub get
+```
+
+## Development Commands
+
+From this directory:
+
+```bash
+dart analyze
+dart test
+```
+
+## Architecture Notes
+
+- Hosts own platform concerns (windowing, lifecycle, platform input wiring).
+- This package owns deterministic engine/frame progression and shared game logic.
+- Frame-buffer sizing is controlled by hosts through engine APIs.
+- Rendering code is maintained under `lib/src/rendering/`.
+
+## Non-Goals
+
+- Flutter widgets/screens are not part of this package.
+- Bundled app assets are handled by `wolf_3d_assets`.
+
+## Troubleshooting
+
+- **Parity regressions**: run targeted tests under `test/engine/` and `test/entities/`.
+- **Host integration issues**: verify host packages/apps are using exported surfaces from `lib/` rather than private `src/` paths.
+
+## Related Modules
+
+- Flutter integration layer: [`../wolf_3d_flutter/README.md`](../wolf_3d_flutter/README.md)
+- Shared packaged assets: [`../wolf_3d_assets/README.md`](../wolf_3d_assets/README.md)
+- CLI host app: [`../../apps/wolf_3d_cli/README.md`](../../apps/wolf_3d_cli/README.md)
+- GUI host app: [`../../apps/wolf_3d_gui/README.md`](../../apps/wolf_3d_gui/README.md)
+- Workspace overview: [`../../README.md`](../../README.md)

packages/wolf_3d_flutter/README.md

@@ -1,39 +1,82 @@
-<!--
-This README describes the package. If you publish this package to pub.dev,
-this README's contents appear on the landing page for your package.
+# wolf_3d_flutter
 
-For information about how to write a good package README, see the guide for
-[writing package pages](https://dart.dev/tools/pub/writing-package-pages).
+Flutter integration package for the shared Wolfenstein 3D runtime.
 
-For general information about developing packages, see the Dart guide for
-[creating packages](https://dart.dev/guides/libraries/create-packages)
-and the Flutter guide for
-[developing packages and plugins](https://flutter.dev/to/develop-packages).
--->
+## What This Package Provides
 
-TODO: Put a short description of the package here that helps potential users
-know whether this package might be useful for them.
+`wolf_3d_flutter` layers Flutter-specific host concerns on top of `wolf_3d_dart`:
 
-## Features
+- high-level engine facade (`Wolf3dFlutterEngine`),
+- Flutter input adapter,
+- platform audio integration,
+- renderer host widgets and runtime mode helpers,
+- app/session managers and persistence adapters,
+- shader-enabled rendering support.
 
-TODO: List what your package can do. Maybe include images, gifs, or videos.
+Primary entrypoint: `lib/wolf_3d_flutter.dart`
 
-## Getting started
+## Prerequisites
 
-TODO: List prerequisites and provide or point to information on how to
-start using the package.
+- Flutter SDK
+- Dart SDK `^3.11.1`
+- Workspace dependency on `wolf_3d_dart`
+
+## Setup
+
+From this directory:
+
+```bash
+flutter pub get
+```
 
 ## Usage
 
-TODO: Include short and useful examples for package users. Add longer examples
-to `/example` folder.
+Typical host initialization pattern:
 
 ```dart
-const like = 'sample';
+final Wolf3dFlutterEngine engine = await Wolf3dFlutterEngine(
+  debug: kDebugMode,
+).init();
 ```
 
-## Additional information
+`init()` handles platform setup, audio init, and configured game-data discovery.
 
-TODO: Tell users more about the package: where to find more information, how to
-contribute to the package, how to file issues, what response they can expect
-from the package authors, and more.
+For full host wiring examples, see:
+
+- `apps/wolf_3d_gui/lib/main.dart`
+
+## Package Structure
+
+- `lib/wolf_3d_flutter.dart` — exports main host facade and public Flutter APIs.
+- `lib/renderer/` — renderer host widgets.
+- `lib/managers/` — runtime/session/display/persistence managers.
+- `lib/audio/` — platform-aware audio backends.
+- `shaders/wolf_world.frag` — fragment shader included in package configuration.
+
+## Development Commands
+
+From this directory:
+
+```bash
+flutter analyze
+flutter test
+```
+
+## Integration Notes
+
+- Keep UI/platform concerns in this package or app hosts, not in `wolf_3d_dart`.
+- Use exported APIs from `lib/wolf_3d_flutter.dart` rather than importing private internals from `lib/src` in dependencies.
+- Shader path is declared in this package `pubspec.yaml` and must stay synchronized with renderer usage.
+
+## Troubleshooting
+
+- **No discovered game data**: confirm configured/persisted data directory paths are valid.
+- **Desktop behavior mismatch**: verify desktop windowing and audio dependencies are available on the target OS.
+- **Render issues after shader changes**: confirm shader path and package config are still aligned.
+
+## Related Modules
+
+- Core runtime package: [`../wolf_3d_dart/README.md`](../wolf_3d_dart/README.md)
+- GUI host app: [`../../apps/wolf_3d_gui/README.md`](../../apps/wolf_3d_gui/README.md)
+- Shared assets package: [`../wolf_3d_assets/README.md`](../wolf_3d_assets/README.md)
+- Workspace overview: [`../../README.md`](../../README.md)