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_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)