docs: update documentation structure and build scripts for clarity

README.md

@@ -357,27 +357,27 @@ This allows you to:
 
 ### Documentation
 - **[README.md](README.md)** - Main documentation (you are here)
-- **[DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md)** - Quick reference for developers
-- **[CHANGELOG.md](CHANGELOG.md)** - Version history and changes
-- **[OVERTE_AUTH.md](OVERTE_AUTH.md)** - OAuth implementation details
-- **[OVERTE_ASSIGNMENT_CLIENT_TASK.md](OVERTE_ASSIGNMENT_CLIENT_TASK.md)** - Protocol implementation
-- **[ENTITY_RENDERING_ENHANCEMENTS.md](ENTITY_RENDERING_ENHANCEMENTS.md)** - Rendering implementation
-- **[MODELCACHE_IMPLEMENTATION.md](MODELCACHE_IMPLEMENTATION.md)** - Asset pipeline details
-- **[CI_SETUP_SUMMARY.md](CI_SETUP_SUMMARY.md)** - Continuous integration setup
+- **[docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md)** - Quick reference for developers
+- **[docs/CHANGELOG.md](docs/CHANGELOG.md)** - Version history and changes
+- **[docs/OVERTE_AUTH.md](docs/OVERTE_AUTH.md)** - OAuth implementation details
+- **[docs/OVERTE_ASSIGNMENT_CLIENT_TASK.md](docs/OVERTE_ASSIGNMENT_CLIENT_TASK.md)** - Protocol implementation
+- **[docs/ENTITY_RENDERING_ENHANCEMENTS.md](docs/ENTITY_RENDERING_ENHANCEMENTS.md)** - Rendering implementation
+- **[docs/MODELCACHE_IMPLEMENTATION.md](docs/MODELCACHE_IMPLEMENTATION.md)** - Asset pipeline details
+- **[docs/CI_SETUP_SUMMARY.md](docs/CI_SETUP_SUMMARY.md)** - Continuous integration setup
 
 ### Getting Started
-1. Read [DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md) for build/run commands
-2. Check [CHANGELOG.md](CHANGELOG.md) for recent changes
-3. Review protocol details in [OVERTE_ASSIGNMENT_CLIENT_TASK.md](OVERTE_ASSIGNMENT_CLIENT_TASK.md)
+1. Read [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md) for build/run commands
+2. Check [docs/CHANGELOG.md](docs/CHANGELOG.md) for recent changes
+3. Review protocol details in [docs/OVERTE_ASSIGNMENT_CLIENT_TASK.md](docs/OVERTE_ASSIGNMENT_CLIENT_TASK.md)
 
 ### Development Workflow
 1. Create feature branch: `git checkout -b feature/my-feature`
-2. Make changes and test locally: `./ci-test.sh`
+2. Make changes and test locally: `./scripts/ci-test.sh`
 3. Commit with clear messages
 4. Push and create PR in Gitea
 5. CI will run automated tests
 
-See [CI_SETUP_SUMMARY.md](CI_SETUP_SUMMARY.md) for details on the CI pipeline.
+See [docs/CI_SETUP_SUMMARY.md](docs/CI_SETUP_SUMMARY.md) for details on the CI pipeline.
 
 ## License
 

build_and_test.sh

@@ -0,0 +1,62 @@
+#!/bin/bash#!/bin/bash
+
+# Backwards compatibility wrapper - scripts have moved to scripts/# Quick build and test script for Starworld
+
+exec "$(dirname "$0")/scripts/build_and_test.sh" "$@"
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+echo "=== Starworld Build & Test Script ==="
+echo
+
+# 1. Build the Rust bridge
+echo "[1/3] Building Rust bridge..."
+cd "$SCRIPT_DIR/bridge"
+cargo build --release
+echo "✓ Rust bridge built successfully"
+echo
+
+# 2. Build the C++ client
+echo "[2/3] Building C++ client..."
+cd "$SCRIPT_DIR"
+mkdir -p build
+cd build
+cmake .. -DCMAKE_BUILD_TYPE=Release
+make -j$(nproc)
+echo "✓ C++ client built successfully"
+echo
+
+# 3. Verify the bridge library exists
+echo "[3/3] Verifying build artifacts..."
+BRIDGE_PATH="$SCRIPT_DIR/bridge/target/release/libstardust_bridge.so"
+if [ -f "$BRIDGE_PATH" ]; then
+    echo "✓ Bridge library found: $BRIDGE_PATH"
+    ls -lh "$BRIDGE_PATH"
+else
+    echo "✗ Bridge library not found at: $BRIDGE_PATH"
+    exit 1
+fi
+
+CLIENT_PATH="$SCRIPT_DIR/build/starworld"
+if [ -f "$CLIENT_PATH" ]; then
+    echo "✓ Client executable found: $CLIENT_PATH"
+    ls -lh "$CLIENT_PATH"
+else
+    echo "✗ Client executable not found at: $CLIENT_PATH"
+    exit 1
+fi
+
+echo
+echo "=== Build Complete! ==="
+echo
+echo "To test with simulation mode:"
+echo "  export STARWORLD_SIMULATE=1"
+echo "  export STARWORLD_BRIDGE_PATH=$SCRIPT_DIR/bridge/target/release"
+echo "  $SCRIPT_DIR/build/starworld"
+echo
+echo "To connect to an Overte server:"
+echo "  export STARWORLD_BRIDGE_PATH=$SCRIPT_DIR/bridge/target/release"
+echo "  $SCRIPT_DIR/build/starworld ws://domain.example.com:40102"
+echo

docs/DEVELOPER_GUIDE.md

@@ -4,7 +4,7 @@
 
 ```bash
 # Full clean build
-./build_and_test.sh
+./scripts/build_and_test.sh
 
 # Build Rust bridge only
 cd bridge && cargo build --release
@@ -42,7 +42,7 @@ RUST_LOG=debug ./build/starworld
 
 ```bash
 # Run all tests
-./ci-test.sh
+./scripts/ci-test.sh
 
 # Run C++ tests only
 ./build/starworld-tests

docs/README.md

@@ -0,0 +1,75 @@
+# Starworld Documentation
+
+This directory contains all project documentation organized by topic.
+
+## Documentation Index
+
+### Getting Started
+- **[../README.md](../README.md)** - Main project README with quick start guide
+- **[DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md)** - Developer quick reference with commands and tips
+
+### Project Information
+- **[CHANGELOG.md](CHANGELOG.md)** - Version history and changes
+- **[CI_SETUP_SUMMARY.md](CI_SETUP_SUMMARY.md)** - Continuous integration setup and workflow
+
+### Implementation Guides
+- **[OVERTE_ASSIGNMENT_CLIENT_TASK.md](OVERTE_ASSIGNMENT_CLIENT_TASK.md)** - Overte protocol implementation details
+- **[OVERTE_AUTH.md](OVERTE_AUTH.md)** - OAuth 2.0 authentication implementation guide
+- **[ENTITY_RENDERING_ENHANCEMENTS.md](ENTITY_RENDERING_ENHANCEMENTS.md)** - Entity rendering system
+- **[MODELCACHE_IMPLEMENTATION.md](MODELCACHE_IMPLEMENTATION.md)** - Asset download and caching
+
+### Planning Documents
+- **[CODE_CLEANUP_PLAN.md](CODE_CLEANUP_PLAN.md)** - Code organization and cleanup plans
+
+## Quick Links
+
+### For New Developers
+1. Start with [../README.md](../README.md) for project overview
+2. Read [DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md) for build/run commands
+3. Check [CHANGELOG.md](CHANGELOG.md) to understand recent changes
+
+### For Contributors
+1. Review [CI_SETUP_SUMMARY.md](CI_SETUP_SUMMARY.md) for testing workflow
+2. Read relevant implementation guides for the area you're working on
+3. Follow conventions described in [CODE_CLEANUP_PLAN.md](CODE_CLEANUP_PLAN.md)
+
+### For Protocol Work
+1. Study [OVERTE_ASSIGNMENT_CLIENT_TASK.md](OVERTE_ASSIGNMENT_CLIENT_TASK.md) for protocol details
+2. Review [OVERTE_AUTH.md](OVERTE_AUTH.md) if working on authentication
+3. Check Overte source code references in each document
+
+### For Rendering Work
+1. Read [ENTITY_RENDERING_ENHANCEMENTS.md](ENTITY_RENDERING_ENHANCEMENTS.md) for rendering pipeline
+2. Review [MODELCACHE_IMPLEMENTATION.md](MODELCACHE_IMPLEMENTATION.md) for asset loading
+3. Check the Rust bridge code in `../bridge/src/lib.rs`
+
+## External Resources
+
+### StardustXR
+- Website: https://stardustxr.org
+- Documentation: https://stardustxr.org/docs
+- GitHub: https://github.com/StardustXR
+
+### Overte
+- Website: https://overte.org
+- Documentation: https://docs.overte.org
+- GitHub: https://github.com/overte-org/overte
+- Discord: https://discord.gg/overte
+
+## Contributing to Documentation
+
+When adding or updating documentation:
+1. Keep documents focused on a single topic
+2. Use clear, descriptive filenames
+3. Include code examples where helpful
+4. Update this README.md index
+5. Link between related documents
+6. Keep the main README.md up to date with links
+
+### Documentation Style
+- Use Markdown format (`.md`)
+- Include a clear title and overview
+- Use code blocks with language tags
+- Add links to external resources
+- Keep line length reasonable for readability
+- Use relative links for internal references