**: Functional error handling
-- **Interface Segregation**: Every component has an interface
-
-### Layer Structure
-
-**1. Domain Layer** (`domain/`)
-- `base/` - BaseModel, BaseRepository
-- `model/` - Entities (ARObject, ARScene, PlacedObject)
- - `valueobjects/` - ModelUri, ObjectName
-- `repository/` - Repository interfaces
-- `exception/` - Domain exceptions
-
-**2. Application Layer** (`application/`)
-- `base/` - BaseUseCase
-- `dto/` - Use case Input/Output DTOs
-- `usecase/` - Business workflows
-
-**3. Infrastructure Layer** (`infrastructure/persistence/`)
-- `dto/` - Persistence DTOs
-- `mapper/` - DTO ↔ Model mappers
-- `repository/` - Repository implementations
-- `local/` - Data source interfaces
-- `BaseMapper.kt` - Mapper base class
-
-**4. Presentation Layer** (`presentation/`)
-- `viewmodel/` - State management
-- `ui/` - Compose screens and components
-
-📚 **[Read more about architecture →](./docs/architecture/TECHNICAL_ANALYSIS.md)**
-
----
-
-## 👥 Multi-Agent Development System
-
-This project uses a multi-agent approach for development:
-
-| Agent | Role |
-|-------|------|
-| **Design & Analysis** | Research and architecture design |
-| **Android Expert** | ARCore implementation |
-| **iOS Expert** | ARKit implementation |
-| **Main Developer** | Core feature development |
-| **Test Developer** | Unit test creation |
-| **Code Reviewer** | Quality control |
-| **Bug Fixer** | Debugging and fixes |
-
-📚 **[Learn about agents →](./.claude/agents/README.md)**
-
----
-
-## 🛠️ Build & Test Commands
-
-**Android:**
-```bash
-./gradlew :composeApp:assembleDebug
-```
-
-**iOS:**
-```bash
-open iosApp/iosApp.xcodeproj # Then run from Xcode
-```
-
-**Run tests:**
-```bash
-./gradlew :composeApp:testDebugUnitTest
-```
-
-📚 **[More commands in CLAUDE.md →](./CLAUDE.md)**
-
----
-
-## 📱 Platform Support
-
-- **Android**: ARCore + SceneView library
-- **iOS**: ARKit + RealityKit
-- **Models**: GLB (primary), USDZ (iOS)
-- **Storage**: DataStore (Android), UserDefaults (iOS)
-
----
-
-## 📊 Project Status
-
-| Category | Status |
-|----------|--------|
-| Core Architecture | ✅ Complete |
-| Android Implementation | ✅ Complete |
-| iOS Implementation | ✅ Complete |
-| Unit Tests | ✅ Complete |
-| Documentation | ✅ Complete |
-
-📚 **[View detailed reports →](./docs/reports/)**
-
----
-
-## 📚 Documentation Categories
-
-### By Topic
-
-- **🏗️ Architecture**: [Technical Analysis](./docs/architecture/technical-analysis.md)
-- **🎨 Design**: [UI/UX Design System](./docs/design/)
-- **👥 Development**: [Agents System](./docs/agents/README.md)
-- **📱 iOS**: [iOS Documentation](./docs/ios/)
-- **📖 Guides**: [Implementation Guides](./docs/guides/)
-- **📊 Reports**: [Status Reports](./docs/reports/)
-
-### By Role
-
-- **For Developers**: [Main Developer Agent](./.claude/agents/main-developer-agent.md)
-- **For Testers**: [Test Implementation Guide](./docs/guides/test-implementation-guide.md)
-- **For Reviewers**: [Code Review Checklist](./docs/guides/code-review-checklist.md)
-- **For iOS Devs**: [iOS Quick Reference](./docs/ios/ios-quick-reference.md)
-- **For Android Devs**: [Android Expert Agent](./.claude/agents/android-expert-agent.md)
-
----
-
-## 🔗 External Resources
-
-- [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html)
-- [ARCore Developer Guide](https://developers.google.com/ar)
-- [ARKit Documentation](https://developer.apple.com/documentation/arkit)
-- [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
-- [Domain-Driven Design](https://www.domainlanguage.com/ddd/reference/)
-
----
-
-## 📝 Recent Updates
-
-- **2026-03-30**: Added comprehensive [UI/UX Design System](./docs/design/) with Material 3 + iOS guidelines
-- **2026-03-30**: Added [AR Competitor Analysis](./docs/design/AR_COMPETITOR_ANALYSIS.md) research
-- **2026-03-30**: Added [Design Tokens](./docs/design/DESIGN_TOKENS.md) quick reference
-- **2026-03-30**: Added [Drag-and-Drop Design Document](./docs/DRAG_DROP_DESIGN.md)
-- **2026-03-31**: Documentation reorganized into `docs/` structure
-- **2026-03-31**: Agents updated with Flutter-inspired DDD patterns
-- **2026-03-31**: Added Value Objects, DTO/Mapper patterns
-- **2026-03-30**: Initial implementation completed
-
----
-
-## 📄 License
-
-This project is private and not published.
-
----
-
-
- 📖 For comprehensive documentation, visit **[docs/INDEX.md](./docs/INDEX.md)**
-
diff --git a/docs/BUG-001-AR-PLACEMENT-FIX.md b/docs/bugs/bug-001-ar-placement-fix.md
similarity index 100%
rename from docs/BUG-001-AR-PLACEMENT-FIX.md
rename to docs/bugs/bug-001-ar-placement-fix.md
diff --git a/docs/BUG-001-VERIFICATION.md b/docs/bugs/bug-001-verification.md
similarity index 100%
rename from docs/BUG-001-VERIFICATION.md
rename to docs/bugs/bug-001-verification.md
diff --git a/docs/design/app-icon/INDEX.md b/docs/design/app-icon/INDEX.md
deleted file mode 100644
index 5c79c1e..0000000
--- a/docs/design/app-icon/INDEX.md
+++ /dev/null
@@ -1,100 +0,0 @@
-# App Icon Design - Quick Index
-
-**Status:** ✅ Ready for Integration
-**Version:** 1.0
-**Date:** 2026-03-30
-
----
-
-## 📋 Quick Links
-
-| Document | Description | Size |
-|----------|-------------|------|
-| **[SUMMARY.md](SUMMARY.md)** | **📌 START HERE** - Complete overview and quick start | 11 KB |
-| [README.md](README.md) | Comprehensive design documentation | 8.9 KB |
-| [preview.html](preview.html) | 🎨 Visual preview gallery (open in browser) | 16 KB |
-
----
-
-## 🎨 Design Files
-
-| File | Purpose |
-|------|---------|
-| [icon-master.svg](icon-master.svg) | Master design (1024x1024) - All platforms |
-| [android-foreground.svg](android-foreground.svg) | Android adaptive icon foreground layer |
-| [android-background.svg](android-background.svg) | Android adaptive icon background layer |
-
----
-
-## 📚 Documentation
-
-| Guide | Platform | Size |
-|-------|----------|------|
-| [android-adaptive-guide.md](android-adaptive-guide.md) | 🤖 Android 8.0+ | 10 KB |
-| [ios-integration-guide.md](ios-integration-guide.md) | 🍎 iOS 13+ | 12 KB |
-| [color-palette.md](color-palette.md) | All platforms | 6.1 KB |
-
----
-
-## 🛠️ Scripts
-
-| Script | Purpose | Status |
-|--------|---------|--------|
-| [export-script.sh](export-script.sh) | Export all iOS + Android sizes | ✅ Executable |
-| [copy-ios-icons.sh](copy-ios-icons.sh) | Copy iOS icons to asset catalog | ✅ Executable |
-
----
-
-## 🚀 Quick Start
-
-### 1. Export All Sizes
-
-```bash
-./export-script.sh
-```
-
-### 2. Copy to iOS Project
-
-```bash
-./copy-ios-icons.sh
-```
-
-### 3. Android Integration
-
-See [android-adaptive-guide.md](android-adaptive-guide.md) for adaptive icon setup.
-
----
-
-## 📁 Export Folders
-
-After running export scripts:
-
-- `ios/` - 11 PNG files for iOS asset catalog
-- `android/` - 5 legacy icons + 5 adaptive foreground layers
-
----
-
-## 🎯 Use Cases
-
-| Task | Document |
-|------|----------|
-| First time setup | [SUMMARY.md](SUMMARY.md) |
-| Visual preview | [preview.html](preview.html) |
-| Android integration | [android-adaptive-guide.md](android-adaptive-guide.md) |
-| iOS integration | [ios-integration-guide.md](ios-integration-guide.md) |
-| Color reference | [color-palette.md](color-palette.md) |
-| Complete documentation | [README.md](README.md) |
-
----
-
-## 📊 Design Stats
-
-- **Theme:** AR-powered 3D placement
-- **Primary Element:** Isometric cube
-- **Colors:** Purple-indigo gradient + white cube
-- **Formats:** SVG (source), PNG (exports)
-- **Platform Support:** iOS 13+, Android 8.0+
-
----
-
-**📖 For comprehensive documentation, see [SUMMARY.md](SUMMARY.md)**
diff --git a/docs/DRAG_DROP_DESIGN.md b/docs/design/drag-drop-design.md
similarity index 100%
rename from docs/DRAG_DROP_DESIGN.md
rename to docs/design/drag-drop-design.md
diff --git a/docs/documentation-organization-complete.md b/docs/documentation-organization-complete.md
deleted file mode 100644
index b576d48..0000000
--- a/docs/documentation-organization-complete.md
+++ /dev/null
@@ -1,269 +0,0 @@
-# Documentation Organization Complete ✅
-
-**Date:** 2026-03-31
-**Status:** Complete
-
----
-
-## 📊 Summary
-
-All markdown documentation has been successfully organized into a structured folder hierarchy.
-
-### Statistics
-
-| Metric | Count |
-|--------|-------|
-| Total MD Files | 27 |
-| Files in `docs/` | 24 |
-| Root MD Files | 3 |
-| Categories | 5 |
-
----
-
-## 📂 New Structure
-
-```
-ARSample/
-├── INDEX.md # Master hub (NEW)
-├── README.md # Project overview
-├── CLAUDE.md # AI assistant config (UPDATED)
-├── .github/
-│ └── copilot-instructions.md # GitHub Copilot (UPDATED)
-│
-└── docs/ # Documentation folder (NEW)
- ├── INDEX.md # Complete doc index (NEW)
- ├── README.md # Docs quick start (NEW)
- │
- ├── architecture/ # Architecture docs
- │ └── TECHNICAL_ANALYSIS.md
- │
- ├── agents/ # Multi-agent system (UPDATED)
- │ ├── README.md
- │ ├── design-analysis-agent.md ⭐ UPDATED
- │ ├── android-expert-agent.md
- │ ├── ios-expert-agent.md
- │ ├── main-developer-agent.md ⭐ UPDATED
- │ ├── bug-fixer-agent.md
- │ ├── test-developer-agent.md ⭐ UPDATED
- │ └── code-reviewer-agent.md ⭐ UPDATED
- │
- ├── ios/ # iOS-specific docs
- │ ├── ios-expert-report.md
- │ ├── ios-expert-summary.md
- │ ├── ios-implementation-checklist.md
- │ ├── ios-implementation-code-examples.md
- │ └── ios-quick-reference.md
- │
- ├── guides/ # How-to guides
- │ ├── CODE_REVIEW_CHECKLIST.md
- │ └── TEST_IMPLEMENTATION_GUIDE.md
- │
- └── reports/ # Status reports
- ├── CODE_FIXES_INDEX.md
- ├── IMPLEMENTATION_COMPLETE.md
- ├── CHANGES_REFERENCE.md
- ├── CODE_FIXES_SUMMARY.md
- ├── TEST_COVERAGE_REPORT.md
- └── TEST_FILES_SUMMARY.md
-```
-
----
-
-## 🎯 Key Improvements
-
-### 1. Clear Entry Points
-- **INDEX.md** (root) - Main documentation hub
-- **docs/INDEX.md** - Detailed documentation index
-- **docs/README.md** - Quick navigation guide
-
-### 2. Organized by Category
-- **architecture/** - System design and technical analysis
-- **agents/** - Multi-agent development system
-- **ios/** - iOS-specific documentation
-- **guides/** - Step-by-step guides
-- **reports/** - Status and progress reports
-
-### 3. Updated Content
-- ✅ Agent files updated with Flutter-inspired DDD patterns
-- ✅ CLAUDE.md updated with key patterns
-- ✅ GitHub Copilot instructions enhanced
-- ✅ Cross-references maintained
-
----
-
-## 📚 Documentation Index
-
-### Root Level (Quick Access)
-| File | Purpose |
-|------|---------|
-| `INDEX.md` | Master documentation hub with quick links |
-| `README.md` | Project overview, setup, and build commands |
-| `CLAUDE.md` | AI assistant config, architecture, key patterns |
-
-### docs/ Level (Organized Content)
-| Folder | File Count | Content |
-|--------|------------|---------|
-| `architecture/` | 1 | Technical analysis and design decisions |
-| `agents/` | 8 | Multi-agent development system |
-| `ios/` | 5 | iOS ARKit implementation docs |
-| `guides/` | 2 | How-to guides and checklists |
-| `reports/` | 6 | Status reports and summaries |
-
----
-
-## 🔍 Navigation Patterns
-
-### By Role
-- **Developers** → `docs/agents/main-developer-agent.md`
-- **Testers** → `docs/guides/TEST_IMPLEMENTATION_GUIDE.md`
-- **Reviewers** → `docs/guides/CODE_REVIEW_CHECKLIST.md`
-- **iOS Devs** → `docs/ios/ios-quick-reference.md`
-- **Android Devs** → `docs/agents/android-expert-agent.md`
-
-### By Topic
-- **Architecture** → `docs/architecture/TECHNICAL_ANALYSIS.md`
-- **Agents System** → `docs/agents/README.md`
-- **iOS Docs** → `docs/ios/`
-- **Testing** → `docs/guides/TEST_IMPLEMENTATION_GUIDE.md`
-- **Status** → `docs/reports/`
-
-### By Task
-- **Getting Started** → `README.md` → `CLAUDE.md` → `docs/INDEX.md`
-- **Understanding Architecture** → `docs/architecture/` → `CLAUDE.md`
-- **Learning Workflow** → `docs/agents/README.md` → agent files
-- **Platform Implementation** → `docs/ios/` or `docs/agents/android-expert-agent.md`
-
----
-
-## ✨ New Features
-
-### 1. Master Documentation Hub (INDEX.md)
-- Beautiful badges and visual hierarchy
-- Quick start section
-- Architecture overview
-- Multi-agent system summary
-- Build commands
-- Status dashboard
-- Documentation categories by topic and role
-
-### 2. Documentation Index (docs/INDEX.md)
-- Complete file listing with descriptions
-- Organized by category
-- Navigation by topic
-- Document status tracker
-- External references
-
-### 3. Quick Start Guide (docs/README.md)
-- Fast navigation for specific roles
-- Links to most relevant docs
-- Clear folder structure
-
----
-
-## 🔗 Cross-References
-
-All documents maintain proper cross-references:
-- ✅ Root INDEX.md → docs/INDEX.md
-- ✅ docs/INDEX.md → All category files
-- ✅ Agent files → Each other and domain docs
-- ✅ Guides → Reports and agents
-- ✅ Reports → Implementation files
-
----
-
-## 📈 Before vs After
-
-### Before
-```
-ARSample/
-├── (26 .md files scattered in root)
-├── .claude/agents/ (7 agent files)
-└── .github/copilot-instructions.md
-```
-**Problem:** Hard to find, no organization, cluttered root
-
-### After
-```
-ARSample/
-├── INDEX.md (hub)
-├── README.md
-├── CLAUDE.md
-├── .github/copilot-instructions.md
-└── docs/ (organized structure)
- ├── INDEX.md
- ├── README.md
- ├── architecture/ (1)
- ├── agents/ (8)
- ├── ios/ (5)
- ├── guides/ (2)
- └── reports/ (6)
-```
-**Solution:** Clean, organized, easy navigation
-
----
-
-## 🎉 Benefits
-
-### For Developers
-- ✅ Easy to find relevant documentation
-- ✅ Clear navigation paths
-- ✅ Role-based organization
-- ✅ Quick reference guides
-
-### For AI Assistants
-- ✅ CLAUDE.md with key patterns
-- ✅ Copilot instructions enhanced
-- ✅ Agent system documented
-- ✅ Architecture clearly defined
-
-### For Maintenance
-- ✅ Single source of truth (docs/)
-- ✅ Clear categories
-- ✅ Easy to update
-- ✅ Scalable structure
-
----
-
-## ✅ Verification Checklist
-
-- [x] All .md files categorized
-- [x] Master INDEX.md created
-- [x] docs/INDEX.md created
-- [x] docs/README.md created
-- [x] Cross-references working
-- [x] Agent files in docs/agents/
-- [x] Original .claude/agents/ preserved
-- [x] No broken links
-- [x] Clear navigation paths
-- [x] Beautiful formatting
-
----
-
-## 🚀 Next Steps
-
-### Immediate
-- ✅ Documentation organized
-- ✅ Navigation guides created
-- ✅ Cross-references verified
-
-### Optional Enhancements
-- [ ] Add diagrams to architecture docs
-- [ ] Create video tutorials
-- [ ] Add code snippets to guides
-- [ ] Generate PDF versions
-
----
-
-## 📝 Notes
-
-1. **Original files preserved**: `.claude/agents/` still contains original agent files
-2. **Copies in docs**: `docs/agents/` contains copies for easy access
-3. **No code changes**: Only documentation organization
-4. **All links work**: Verified cross-references
-5. **Git-ready**: Ready to commit
-
----
-
-**Status:** ✅ Complete and ready to use!
-**Last Updated:** 2026-03-31
-**Version:** 1.0
diff --git a/docs/arcore-best-practices-cheatsheet.md b/docs/guides/arcore-best-practices.md
similarity index 100%
rename from docs/arcore-best-practices-cheatsheet.md
rename to docs/guides/arcore-best-practices.md
diff --git a/docs/ARCORE_QUICK_REFERENCE.md b/docs/guides/arcore-quick-reference.md
similarity index 100%
rename from docs/ARCORE_QUICK_REFERENCE.md
rename to docs/guides/arcore-quick-reference.md
diff --git a/docs/DEPLOYMENT_GUIDE.md b/docs/guides/deployment-guide.md
similarity index 100%
rename from docs/DEPLOYMENT_GUIDE.md
rename to docs/guides/deployment-guide.md
diff --git a/.github/workflows/QUICK_REFERENCE.md b/docs/guides/ios-ci-quick-reference.md
similarity index 100%
rename from .github/workflows/QUICK_REFERENCE.md
rename to docs/guides/ios-ci-quick-reference.md
diff --git a/docs/IOS_ISSUES_ANALYSIS.md b/docs/ios/ios-issues-analysis.md
similarity index 100%
rename from docs/IOS_ISSUES_ANALYSIS.md
rename to docs/ios/ios-issues-analysis.md
diff --git a/.github/workflows/IOS_WORKFLOW_README.md b/docs/ios/ios-workflow-readme.md
similarity index 100%
rename from .github/workflows/IOS_WORKFLOW_README.md
rename to docs/ios/ios-workflow-readme.md
diff --git a/docs/ANDROID_ARCORE_STATE_SYNC_FIX.md b/docs/reports/android-arcore-state-sync-fix.md
similarity index 100%
rename from docs/ANDROID_ARCORE_STATE_SYNC_FIX.md
rename to docs/reports/android-arcore-state-sync-fix.md
diff --git a/docs/android-arcore-summary.md b/docs/reports/android-arcore-summary.md
similarity index 100%
rename from docs/android-arcore-summary.md
rename to docs/reports/android-arcore-summary.md
diff --git a/docs/ANDROID_EXPERT_SESSION_SUMMARY.md b/docs/reports/android-expert-session-summary.md
similarity index 100%
rename from docs/ANDROID_EXPERT_SESSION_SUMMARY.md
rename to docs/reports/android-expert-session-summary.md
diff --git a/docs/ANDROID_FIX_COMPLETE.md b/docs/reports/android-fix-complete.md
similarity index 100%
rename from docs/ANDROID_FIX_COMPLETE.md
rename to docs/reports/android-fix-complete.md
diff --git a/docs/reports/documentation-cleanup-report.md b/docs/reports/documentation-cleanup-report.md
deleted file mode 100644
index 7345ef8..0000000
--- a/docs/reports/documentation-cleanup-report.md
+++ /dev/null
@@ -1,322 +0,0 @@
-# Markdown Documentation Cleanup Report
-
-**Date**: 2026-04-01
-**Status**: ✅ Complete
-**Duration**: ~30 minutes
-
----
-
-## 📋 Executive Summary
-
-Successfully reorganized and improved the markdown documentation structure across the ARSample project. Eliminated duplications, standardized naming conventions, and created a more maintainable documentation hierarchy.
-
-### Key Achievements
-- ✅ Removed 7 duplicate agent files
-- ✅ Consolidated 4 hit testing documents into organized structure
-- ✅ Standardized 12 file names to kebab-case
-- ✅ Updated 50+ broken links across 6 files
-- ✅ Reduced total markdown files from 44 to 37
-
----
-
-## 🔧 Changes Made
-
-### 1. Agent Duplication Removal ✅
-
-**Problem**: Agent documentation existed in two locations
-- `.claude/agents/` (7 files) ← **Kept as source**
-- `docs/agents/` (7 files) ← **Deleted**
-
-**Actions**:
-- Deleted entire `docs/agents/` directory
-- Updated all references in `docs/INDEX.md` and `INDEX.md` to point to `.claude/agents/`
-
-**Files Deleted**:
-```
-docs/agents/README.md
-docs/agents/design-analysis-agent.md
-docs/agents/android-expert-agent.md
-docs/agents/ios-expert-agent.md
-docs/agents/main-developer-agent.md
-docs/agents/test-developer-agent.md
-docs/agents/code-reviewer-agent.md
-docs/agents/bug-fixer-agent.md
-```
-
-**Files Saved**: 7 files (0 bytes wasted on duplicates)
-
----
-
-### 2. Hit Testing Documentation Consolidation ✅
-
-**Problem**: 4 separate hit testing files scattered in `docs/` root
-
-**Before**:
-```
-docs/
-├── HIT_TESTING_DESIGN.md
-├── HIT_TESTING_IMPLEMENTATION.md
-├── HIT_TESTING_QUICKREF.md
-└── ANDROID_ARCORE_HIT_TEST_ANALYSIS.md
-```
-
-**After**:
-```
-docs/guides/hit-testing/
-├── README.md # Navigation hub (NEW)
-├── design.md # Renamed from HIT_TESTING_DESIGN.md
-├── implementation.md # Renamed from HIT_TESTING_IMPLEMENTATION.md
-├── quick-reference.md # Renamed from HIT_TESTING_QUICKREF.md
-└── android-arcore-analysis.md # Renamed from ANDROID_ARCORE_HIT_TEST_ANALYSIS.md
-```
-
-**Benefits**:
-- Centralized hit testing documentation
-- Clear navigation with README.md
-- Platform-specific docs grouped together
-- Easier to maintain and extend
-
----
-
-### 3. File Naming Standardization ✅
-
-**Problem**: Inconsistent naming (UPPERCASE vs lowercase vs kebab-case)
-
-**Convention Adopted**: `lowercase-with-hyphens.md` (kebab-case)
-
-**Files Renamed** (12 files):
-
-| Before (UPPERCASE_SNAKE_CASE) | After (kebab-case) |
-|-------------------------------|-------------------|
-| `DOCUMENTATION_ORGANIZATION_COMPLETE.md` | `documentation-organization-complete.md` |
-| `architecture/TECHNICAL_ANALYSIS.md` | `architecture/technical-analysis.md` |
-| `guides/CODE_REVIEW_CHECKLIST.md` | `guides/code-review-checklist.md` |
-| `guides/TEST_IMPLEMENTATION_GUIDE.md` | `guides/test-implementation-guide.md` |
-| `reports/TEST_COVERAGE_REPORT.md` | `reports/test-coverage-report.md` |
-| `reports/TEST_FILES_SUMMARY.md` | `reports/test-files-summary.md` |
-| `reports/CODE_FIXES_INDEX.md` | `reports/code-fixes-index.md` |
-| `reports/CODE_FIXES_SUMMARY.md` | `reports/code-fixes-summary.md` |
-| `reports/CHANGES_REFERENCE.md` | `reports/changes-reference.md` |
-| `reports/IMPLEMENTATION_COMPLETE.md` | `reports/implementation-complete.md` |
-| `ios/IOS_ARKIT_QUICK_FIX_GUIDE.md` | `ios/ios-arkit-quick-fix-guide.md` |
-| `ios/IOS_ARKIT_HIT_TESTING_IMPLEMENTATION_REPORT.md` | `ios/ios-arkit-hit-testing-report.md` |
-
-**Benefits**:
-- Consistent visual appearance
-- Easier to type and remember
-- Better URL compatibility
-- Industry standard (GitHub, Jekyll, etc.)
-
----
-
-### 4. Link References Updated ✅
-
-**Problem**: 50+ broken links after file moves and renames
-
-**Files Updated** (6 files):
-1. `INDEX.md` - Root documentation hub
-2. `docs/INDEX.md` - Master documentation index
-3. `docs/README.md` - Docs folder README
-4. `docs/guides/hit-testing/README.md` - Hit testing hub
-5. `docs/android-arcore-summary.md` - Android summary
-6. `docs/ios/README.md` - iOS documentation index
-
-**Link Categories Fixed**:
-- Agent references: `./docs/agents/` → `../.claude/agents/`
-- Hit testing: `./HIT_TESTING_*.md` → `./guides/hit-testing/*.md`
-- Uppercase files: `TECHNICAL_ANALYSIS.md` → `technical-analysis.md`
-- iOS files: `IOS_ARKIT_*.md` → `ios-arkit-*.md`
-
-**Verification**: All internal links now valid
-
----
-
-## 📊 Before & After Comparison
-
-### File Count
-
-| Category | Before | After | Change |
-|----------|--------|-------|--------|
-| **Total Files** | 44 | 37 | -7 |
-| Agent Files | 14 | 7 | -7 (removed duplicates) |
-| Hit Testing | 4 scattered | 5 organized | +1 (added README) |
-| Naming Consistency | ~60% | 100% | +40% |
-
-### Directory Structure
-
-**Before**:
-```
-docs/
-├── UPPERCASE_FILES.md (scattered)
-├── lowercase-files.md (scattered)
-├── agents/ (duplicate)
-├── HIT_TESTING_*.md (4 files at root)
-└── ...
-```
-
-**After**:
-```
-docs/
-├── lowercase-files.md (consistent)
-├── guides/
-│ ├── hit-testing/ (organized)
-│ │ ├── README.md
-│ │ ├── design.md
-│ │ ├── implementation.md
-│ │ ├── quick-reference.md
-│ │ └── android-arcore-analysis.md
-│ ├── code-review-checklist.md
-│ └── test-implementation-guide.md
-└── ...
-```
-
----
-
-## ✅ Quality Improvements
-
-### 1. Discoverability
-- ✅ Hit testing docs now have a dedicated hub (README.md)
-- ✅ Clear categorization (guides, architecture, reports, platform)
-- ✅ Consistent naming makes files easier to find
-
-### 2. Maintainability
-- ✅ Single source of truth for agent docs (`.claude/agents/`)
-- ✅ No duplicate content to keep in sync
-- ✅ Organized structure reduces cognitive load
-
-### 3. Navigation
-- ✅ All broken links fixed
-- ✅ Hub files (README.md) provide clear entry points
-- ✅ Breadcrumb-style organization (guides/hit-testing/design.md)
-
-### 4. Consistency
-- ✅ 100% kebab-case naming convention
-- ✅ Standardized directory structure
-- ✅ Predictable file locations
-
----
-
-## 🎯 Impact Assessment
-
-### Developer Experience
-- **Search**: Easier to find files with consistent naming
-- **Navigation**: Logical grouping reduces confusion
-- **Maintenance**: Single source for agents eliminates sync issues
-- **Onboarding**: Clear structure helps new developers
-
-### Documentation Health
-- **Accuracy**: All links verified and working
-- **Organization**: Topic-based grouping (hit-testing/)
-- **Scalability**: Easy to add new docs in established structure
-- **Standards**: Industry-standard kebab-case naming
-
----
-
-## 📁 Final Structure
-
-```
-ARSample/
-├── CLAUDE.md (kept)
-├── INDEX.md (updated)
-├── README.md (kept)
-├── .claude/
-│ └── agents/ (7 files - source of truth)
-├── .github/
-│ └── copilot-instructions.md (kept)
-└── docs/
- ├── INDEX.md (updated - master index)
- ├── README.md (updated)
- ├── android-arcore-summary.md
- ├── arcore-best-practices-cheatsheet.md
- ├── documentation-organization-complete.md ✓ renamed
- ├── architecture/
- │ └── technical-analysis.md ✓ renamed
- ├── guides/
- │ ├── code-review-checklist.md ✓ renamed
- │ ├── test-implementation-guide.md ✓ renamed
- │ └── hit-testing/ ✓ NEW organized structure
- │ ├── README.md ✓ NEW
- │ ├── design.md ✓ moved & renamed
- │ ├── implementation.md ✓ moved & renamed
- │ ├── quick-reference.md ✓ moved & renamed
- │ └── android-arcore-analysis.md ✓ moved & renamed
- ├── ios/
- │ ├── README.md (updated)
- │ ├── ios-arkit-hit-testing-report.md ✓ renamed
- │ ├── ios-arkit-quick-fix-guide.md ✓ renamed
- │ ├── ios-expert-report.md
- │ ├── ios-expert-summary.md
- │ ├── ios-implementation-checklist.md
- │ ├── ios-implementation-code-examples.md
- │ └── ios-quick-reference.md
- └── reports/
- ├── changes-reference.md ✓ renamed
- ├── code-fixes-index.md ✓ renamed
- ├── code-fixes-summary.md ✓ renamed
- ├── implementation-complete.md ✓ renamed
- ├── test-coverage-report.md ✓ renamed
- └── test-files-summary.md ✓ renamed
-```
-
----
-
-## 🚀 Next Steps (Recommendations)
-
-### Optional Future Improvements
-1. **Add `.markdownlint.json`** - Enforce markdown standards
-2. **Link checker CI/CD** - Automated broken link detection
-3. **Doc versioning** - Track major doc changes
-4. **Navigation breadcrumbs** - Add "< Back to INDEX" links
-
-### Maintenance Guidelines
-1. **New Files**: Always use `kebab-case-naming.md`
-2. **New Categories**: Create subdirectories (e.g., `docs/guides/testing/`)
-3. **Agent Docs**: Only update `.claude/agents/`, never duplicate
-4. **Links**: Use relative paths (`./`, `../`)
-
----
-
-## 📈 Metrics
-
-| Metric | Value |
-|--------|-------|
-| **Files Deleted** | 7 |
-| **Files Renamed** | 12 |
-| **Files Moved** | 4 |
-| **Links Fixed** | 50+ |
-| **New Files Created** | 1 (hit-testing/README.md) |
-| **Time Saved** | ~2 hours (no manual cleanup needed) |
-| **Disk Space Saved** | ~50KB (duplicate removal) |
-| **Consistency Score** | 100% (was 60%) |
-
----
-
-## ✅ Verification Checklist
-
-- [x] No duplicate files exist
-- [x] All files use kebab-case naming
-- [x] Hit testing docs organized in `guides/hit-testing/`
-- [x] Agent docs reference `.claude/agents/`
-- [x] All internal links verified
-- [x] Hub files (INDEX.md, README.md) updated
-- [x] Navigation structure logical
-- [x] Plan.md documented in session folder
-
----
-
-## 🏆 Summary
-
-**Mission Accomplished!** The markdown documentation is now:
-- ✅ **Organized** - Clear hierarchy with topic-based grouping
-- ✅ **Consistent** - 100% kebab-case naming convention
-- ✅ **Accurate** - All links verified and working
-- ✅ **Maintainable** - Single source of truth, no duplicates
-- ✅ **Scalable** - Easy to extend with new documentation
-
-**Developer Impact**: Improved discoverability, faster navigation, and reduced maintenance overhead.
-
----
-
-**Report Generated**: 2026-04-01 15:35 UTC
-**Executed By**: GitHub Copilot CLI
-**Session ID**: b841847c-0f40-4880-b695-6c19f1b56d2e
diff --git a/docs/FIX-DRAG-DELETE.md b/docs/reports/fix-drag-delete.md
similarity index 100%
rename from docs/FIX-DRAG-DELETE.md
rename to docs/reports/fix-drag-delete.md
diff --git a/.github/workflows/IMPLEMENTATION_SUMMARY.md b/docs/reports/ios-workflow-implementation-summary.md
similarity index 100%
rename from .github/workflows/IMPLEMENTATION_SUMMARY.md
rename to docs/reports/ios-workflow-implementation-summary.md
diff --git a/docs/reports/project-restructuring-report.md b/docs/reports/project-restructuring-report.md
deleted file mode 100644
index 4fd1189..0000000
--- a/docs/reports/project-restructuring-report.md
+++ /dev/null
@@ -1,118 +0,0 @@
-# ARSample Project Restructuring Report
-
-**Date:** 2026-04-01
-**Task:** Align project structure with documentation (CLAUDE.md, COPILOT.md)
-
-## Summary
-
-Başarıyla tamamlandı! Projeye **DDD + Clean Architecture** yapısı için gerekli temel bileşenler eklendi.
-
-## Changes Made
-
-### 1. ✅ Base Classes Created (`domain/base/`)
-
-Tüm domain katmanı için temel interface'ler oluşturuldu:
-
-| File | Purpose | Lines |
-|------|---------|-------|
-| `BaseModel.kt` | Marker interface for domain models | 6 |
-| `BaseUseCase.kt` | Typed use case pattern (Input → Output) | 11 |
-| `BaseRepository.kt` | Marker interface for repositories | 6 |
-| `BaseMapper.kt` | DTO ↔ Model transformation | 15 |
-
-**Pattern:** Halleder Flutter projelerinden alınan Clean Architecture pattern'i.
-
-### 2. ✅ Exception Hierarchy (`domain/exception/`)
-
-Domain-level exception hierarchy oluşturuldu:
-
-```kotlin
-DomainException (sealed base)
- ├── ValidationException - Input validation failures
- ├── EntityNotFoundException - Entity not found
- ├── StorageException - Data persistence errors
- └── BusinessRuleException - Business logic violations
-```
-
-**File:** `DomainException.kt` (47 lines)
-
-### 3. ✅ Value Objects (`domain/model/valueobjects/`)
-
-Domain validation için immutable value objects:
-
-| Value Object | Validates | Rules |
-|--------------|-----------|-------|
-| `ModelUri` | 3D model file paths | .glb, .usdz, .fbx, .obj extensions |
-| `ObjectName` | Object names | 1-50 chars, non-blank |
-
-**Pattern:**
-- Sealed class with private constructor
-- `create()` factory returns `Result`
-- Prevents invalid state creation
-
-Example:
-```kotlin
-val nameResult = ObjectName.create("Modern Chair")
-nameResult.fold(
- onSuccess = { name -> use(name.value) },
- onFailure = { error -> handleError(error) }
-)
-```
-
-## Architecture Impact
-
-### Before
-```
-domain/
-├── model/ (basic entities)
-├── repository/ (interfaces)
-└── usecase/ (implementations)
-```
-
-### After
-```
-domain/
-├── base/ ← NEW: Foundation layer
-├── exception/ ← NEW: Domain exceptions
-├── model/
-│ └── valueobjects/ ← NEW: Validation layer
-├── repository/
-└── usecase/
-```
-
-## Benefits
-
-1. **Type Safety:** Value Objects prevent invalid data at compile time
-2. **Validation:** Business rules enforced in domain layer
-3. **Consistency:** Base classes standardize patterns across codebase
-4. **Error Handling:** Typed exceptions with Result pattern
-5. **Testability:** Clear separation of concerns
-
-## Next Steps (Future)
-
-1. **DTO Layer:** Create `data/dto/` with serializable DTOs
-2. **Refactor Existing:** Update current models to use Value Objects
-3. **Use Case Inputs:** Add Input/Output models to use cases
-4. **Mappers:** Implement BaseMapper for existing entities
-5. **Tests:** Add unit tests for Value Objects and exceptions
-
-## Files Summary
-
-| Category | Files Added | Total Lines |
-|----------|-------------|-------------|
-| Base Classes | 4 | 38 |
-| Exceptions | 1 | 47 |
-| Value Objects | 2 | 80 |
-| **Total** | **7** | **165** |
-
-## Compliance
-
-✅ Follows CLAUDE.md patterns
-✅ Implements Halleder-inspired DDD
-✅ Uses sealed class + Result pattern
-✅ Zero breaking changes to existing code
-✅ Documentation-first approach
-
----
-
-**Conclusion:** Proje artık dokümantasyonda tanımlanan Clean Architecture yapısına sahip. Mevcut kodlar bozulmadı, yeni pattern'ler eklenmeye hazır.
diff --git a/TEST_SUMMARY.md b/docs/reports/test-summary.md
similarity index 100%
rename from TEST_SUMMARY.md
rename to docs/reports/test-summary.md
From 75c36e5da2c327a8b3ad8906d7abf54a99f975c8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Recep=20Tayyip=20Ek=C5=9Fi?=
<100341383+recepteksi@users.noreply.github.com>
Date: Wed, 8 Apr 2026 13:57:55 +0300
Subject: [PATCH 24/24] docs: update INDEX.md and README.md with new file
structure
Co-Authored-By: Claude Sonnet 4.6
---
docs/INDEX.md | 214 ++++++++++++++++++-------------------------------
docs/README.md | 40 +++++----
2 files changed, 94 insertions(+), 160 deletions(-)
diff --git a/docs/INDEX.md b/docs/INDEX.md
index 3773e74..f7cf1ea 100644
--- a/docs/INDEX.md
+++ b/docs/INDEX.md
@@ -2,201 +2,139 @@
> **AR Sample Application** - Kotlin Multiplatform app for importing and placing 3D objects in AR scenes (Android ARCore + iOS ARKit)
-## 📋 Quick Links
+## Quick Links
| Document | Description |
|----------|-------------|
| [README.md](../README.md) | Project overview and getting started |
| [CLAUDE.md](../CLAUDE.md) | AI assistant instructions and architecture |
-| [.github/copilot-instructions.md](../.github/copilot-instructions.md) | GitHub Copilot instructions |
+| [CHANGELOG.md](../CHANGELOG.md) | Version history |
---
-## 📂 Documentation Structure
+## Documentation Structure
-### 🎨 UI/UX Design
-Complete design system and guidelines for ARSample application.
+### Architecture
| File | Description |
|------|-------------|
-| [design/README.md](./design/README.md) | **📚 START HERE** - Design documentation overview |
-| [design/UI_UX_DESIGN_GUIDE.md](./design/UI_UX_DESIGN_GUIDE.md) | **📖 Complete Guide** - Material 3 + iOS HIG design system (1000+ lines) |
-| [design/AR_COMPETITOR_ANALYSIS.md](./design/AR_COMPETITOR_ANALYSIS.md) | **🔍 Research** - Industry analysis (IKEA, Amazon, Houzz, Pokemon GO) |
-| [design/DESIGN_TOKENS.md](./design/DESIGN_TOKENS.md) | **⚡ Quick Ref** - Colors, typography, spacing, icons |
+| [architecture/technical-analysis.md](./architecture/technical-analysis.md) | Technical architecture analysis and decisions |
---
-### 🏗️ Architecture
-Documentation about system design and architecture.
+### Design (UI/UX)
| File | Description |
|------|-------------|
-| [technical-analysis.md](./architecture/technical-analysis.md) | Technical architecture analysis and decisions |
-| **[DRAG_DROP_DESIGN.md](./DRAG_DROP_DESIGN.md)** | **🆕 NEW** - Drag-to-move and drag-to-delete feature design |
+| [design/README.md](./design/README.md) | Design documentation overview |
+| [design/UI_UX_DESIGN_GUIDE.md](./design/UI_UX_DESIGN_GUIDE.md) | Material 3 + iOS HIG design system |
+| [design/AR_COMPETITOR_ANALYSIS.md](./design/AR_COMPETITOR_ANALYSIS.md) | Industry analysis (IKEA, Amazon, Houzz) |
+| [design/DESIGN_TOKENS.md](./design/DESIGN_TOKENS.md) | Colors, typography, spacing, icons |
+| [design/drag-drop-design.md](./design/drag-drop-design.md) | Drag-to-move and drag-to-delete feature design |
+| [design/app-icon/README.md](./design/app-icon/README.md) | App icon design documentation |
+| [design/app-icon/SUMMARY.md](./design/app-icon/SUMMARY.md) | App icon package summary |
+| [design/app-icon/color-palette.md](./design/app-icon/color-palette.md) | App icon color palette |
+| [design/app-icon/android-adaptive-guide.md](./design/app-icon/android-adaptive-guide.md) | Android adaptive icon guide |
+| [design/app-icon/ios-integration-guide.md](./design/app-icon/ios-integration-guide.md) | iOS icon integration guide |
+| [design/splash/README.md](./design/splash/README.md) | Splash screen documentation |
+| [design/splash/SPLASH_SCREEN_DESIGN_SPEC.md](./design/splash/SPLASH_SCREEN_DESIGN_SPEC.md) | Splash screen design spec |
---
-### 👥 Agents
-Multi-agent system documentation for development workflow.
+### Android (ARCore)
| File | Description |
|------|-------------|
-| [../.claude/agents/README.md](../.claude/agents/README.md) | Agent system overview and workflow |
-| [../.claude/agents/design-analysis-agent.md](../.claude/agents/design-analysis-agent.md) | Research and architecture design agent |
-| [../.claude/agents/android-expert-agent.md](../.claude/agents/android-expert-agent.md) | ARCore implementation expert |
-| [../.claude/agents/ios-expert-agent.md](../.claude/agents/ios-expert-agent.md) | ARKit implementation expert |
-| [../.claude/agents/main-developer-agent.md](../.claude/agents/main-developer-agent.md) | Core development agent (Domain/Data/Presentation) |
-| [../.claude/agents/bug-fixer-agent.md](../.claude/agents/bug-fixer-agent.md) | Debugging and bug fixing agent |
-| [../.claude/agents/test-developer-agent.md](../.claude/agents/test-developer-agent.md) | Unit testing agent |
-| [../.claude/agents/code-reviewer-agent.md](../.claude/agents/code-reviewer-agent.md) | Code quality control agent |
+| [guides/arcore-quick-reference.md](./guides/arcore-quick-reference.md) | ARCore patterns and gotchas quick reference |
+| [guides/arcore-best-practices.md](./guides/arcore-best-practices.md) | ARCore best practices cheatsheet |
+| [guides/hit-testing/README.md](./guides/hit-testing/README.md) | Hit testing documentation hub |
+| [guides/hit-testing/android-arcore-analysis.md](./guides/hit-testing/android-arcore-analysis.md) | ARCore hit testing analysis and fixes |
+| [guides/hit-testing/implementation.md](./guides/hit-testing/implementation.md) | Hit testing implementation guide |
+| [guides/hit-testing/quick-reference.md](./guides/hit-testing/quick-reference.md) | Hit testing quick reference |
+| [guides/hit-testing/design.md](./guides/hit-testing/design.md) | Hit testing design document |
+| [reports/android-arcore-summary.md](./reports/android-arcore-summary.md) | Executive summary of Android implementation |
+| [reports/android-arcore-state-sync-fix.md](./reports/android-arcore-state-sync-fix.md) | AndroidView stale closure fix |
+| [reports/android-expert-session-summary.md](./reports/android-expert-session-summary.md) | Android expert session documentation |
+| [reports/android-fix-complete.md](./reports/android-fix-complete.md) | Android fix completion report |
---
-### 📱 Platform Specific
-
-#### Android (ARCore)
-Android platform-specific documentation (ARCore, SceneView, Kotlin).
+### iOS (ARKit)
| File | Description |
|------|-------------|
-| **[ANDROID_ARCORE_STATE_SYNC_FIX.md](./ANDROID_ARCORE_STATE_SYNC_FIX.md)** | **🔴 FIXED** - AndroidView stale closure fix with rememberUpdatedState |
-| [ARCORE_QUICK_REFERENCE.md](./ARCORE_QUICK_REFERENCE.md) | **📚 Quick Reference** - Patterns, templates, gotchas for AR development |
-| [DEPLOYMENT_GUIDE.md](./DEPLOYMENT_GUIDE.md) | **🚀 Deployment** - Build, test, and deployment instructions |
-| [ANDROID_EXPERT_SESSION_SUMMARY.md](./ANDROID_EXPERT_SESSION_SUMMARY.md) | **📋 Session Summary** - Complete analysis and solution documentation |
-| [android-arcore-analysis.md](./guides/hit-testing/android-arcore-analysis.md) | ARCore hit testing analysis and fixes |
-| [android-arcore-summary.md](./android-arcore-summary.md) | Executive summary of Android implementation issues |
-| [arcore-best-practices-cheatsheet.md](./arcore-best-practices-cheatsheet.md) | Quick reference for ARCore best practices |
-
-#### iOS (ARKit)
-iOS platform-specific documentation (ARKit, RealityKit, Swift).
-
-| File | Description |
-|------|-------------|
-| [ios/ios-arkit-quick-fix-guide.md](./ios/ios-arkit-quick-fix-guide.md) | **🔥 START HERE** - 3-4 saat içinde critical issues düzelt |
-| [ios/ios-arkit-hit-testing-report.md](./ios/ios-arkit-hit-testing-report.md) | **📚 COMPREHENSIVE** - iOS ARKit hit testing kapsamlı implementation raporu (1000+ satır) |
+| [ios/ios-arkit-quick-fix-guide.md](./ios/ios-arkit-quick-fix-guide.md) | Critical iOS issues quick fix guide |
+| [ios/ios-arkit-hit-testing-report.md](./ios/ios-arkit-hit-testing-report.md) | iOS ARKit hit testing comprehensive report |
| [ios/ios-expert-report.md](./ios/ios-expert-report.md) | Comprehensive iOS ARKit implementation report |
| [ios/ios-expert-summary.md](./ios/ios-expert-summary.md) | iOS implementation summary |
| [ios/ios-implementation-checklist.md](./ios/ios-implementation-checklist.md) | iOS implementation checklist |
| [ios/ios-implementation-code-examples.md](./ios/ios-implementation-code-examples.md) | iOS code examples and snippets |
| [ios/ios-quick-reference.md](./ios/ios-quick-reference.md) | Quick reference for iOS implementation |
+| [ios/ios-issues-analysis.md](./ios/ios-issues-analysis.md) | iOS issues analysis |
+| [ios/ios-workflow-readme.md](./ios/ios-workflow-readme.md) | iOS CI/CD workflow documentation |
---
-### 📖 Guides
-Step-by-step guides and checklists.
+### Guides
| File | Description |
|------|-------------|
-| [guides/test-implementation-guide.md](./guides/test-implementation-guide.md) | Guide for implementing unit tests |
+| [guides/test-implementation-guide.md](./guides/test-implementation-guide.md) | Unit test implementation guide |
| [guides/code-review-checklist.md](./guides/code-review-checklist.md) | Code review checklist and standards |
-| **[guides/hit-testing/README.md](./guides/hit-testing/README.md)** | **📘 NEW** - Comprehensive hit testing documentation hub |
+| [guides/deployment-guide.md](./guides/deployment-guide.md) | Build, test, and deployment instructions |
+| [guides/ios-ci-quick-reference.md](./guides/ios-ci-quick-reference.md) | iOS CI/CD quick reference |
---
-### 📊 Reports
-Development reports, summaries, and status updates.
+### Bugs
| File | Description |
|------|-------------|
-| [reports/code-fixes-index.md](./reports/code-fixes-index.md) | Complete code fixes index and verification |
-| [reports/implementation-complete.md](./reports/implementation-complete.md) | Implementation completion report |
-| [reports/changes-reference.md](./reports/changes-reference.md) | Reference of all code changes made |
-| [reports/code-fixes-summary.md](./reports/code-fixes-summary.md) | Summary of bug fixes and improvements |
-| [reports/test-coverage-report.md](./reports/test-coverage-report.md) | Test coverage metrics and analysis |
-| [reports/test-files-summary.md](./reports/test-files-summary.md) | Summary of all test files |
-
----
-
-## 🗺️ Navigation by Topic
-
-### Getting Started
-1. [README.md](../README.md) - Start here
-2. [CLAUDE.md](../CLAUDE.md) - Understand the architecture
-3. [../.claude/agents/README.md](../.claude/agents/README.md) - Learn about the development workflow
-
-### Architecture & Design
-1. [architecture/technical-analysis.md](./architecture/technical-analysis.md)
-2. [../.claude/agents/design-analysis-agent.md](../.claude/agents/design-analysis-agent.md)
-3. [CLAUDE.md](../CLAUDE.md) - Key patterns section
-
-### Platform Implementation
-
-**Android (ARCore):**
-- 🔴 **[guides/hit-testing/android-arcore-analysis.md](./guides/hit-testing/android-arcore-analysis.md)** - Critical implementation issues
-- [android-arcore-summary.md](./android-arcore-summary.md) - Executive summary
-- [arcore-best-practices-cheatsheet.md](./arcore-best-practices-cheatsheet.md) - Quick reference
-- [../.claude/agents/android-expert-agent.md](../.claude/agents/android-expert-agent.md) - Agent documentation
-
-**iOS (ARKit):**
-- [ios/ios-arkit-hit-testing-report.md](./ios/ios-arkit-hit-testing-report.md) - Hit testing implementation
-- [ios/ios-expert-report.md](./ios/ios-expert-report.md) - Comprehensive report
-- [ios/ios-implementation-code-examples.md](./ios/ios-implementation-code-examples.md) - Code examples
-- [ios/ios-quick-reference.md](./ios/ios-quick-reference.md) - Quick reference
-
-### Development Workflow
-1. [../.claude/agents/main-developer-agent.md](../.claude/agents/main-developer-agent.md) - Core development
-2. [../.claude/agents/test-developer-agent.md](../.claude/agents/test-developer-agent.md) - Testing
-3. [../.claude/agents/code-reviewer-agent.md](../.claude/agents/code-reviewer-agent.md) - Code review
-4. [../.claude/agents/bug-fixer-agent.md](../.claude/agents/bug-fixer-agent.md) - Bug fixing
-
-### Testing
-1. [guides/TEST_IMPLEMENTATION_GUIDE.md](./guides/TEST_IMPLEMENTATION_GUIDE.md)
-2. [reports/TEST_COVERAGE_REPORT.md](./reports/TEST_COVERAGE_REPORT.md)
-3. [reports/TEST_FILES_SUMMARY.md](./reports/TEST_FILES_SUMMARY.md)
-
-### Quality Assurance
-1. [guides/CODE_REVIEW_CHECKLIST.md](./guides/CODE_REVIEW_CHECKLIST.md)
-2. [agents/code-reviewer-agent.md](./agents/code-reviewer-agent.md)
-3. [reports/CODE_FIXES_SUMMARY.md](./reports/CODE_FIXES_SUMMARY.md)
+| [bugs/BUG-001-import-feature-not-working.md](./bugs/BUG-001-import-feature-not-working.md) | BUG-001 import feature analysis |
+| [bugs/bug-001-ar-placement-fix.md](./bugs/bug-001-ar-placement-fix.md) | BUG-001 AR placement fix |
+| [bugs/bug-001-verification.md](./bugs/bug-001-verification.md) | BUG-001 fix verification |
---
-## 📝 Document Status
+### Reports
-| Category | File Count | Status |
-|----------|------------|--------|
-| Architecture | 1 | ✅ Complete |
-| Agents | 8 | ✅ Complete |
-| Android Docs | 7 | ✅ State Sync Fixed |
-| iOS Docs | 6 | ✅ Complete |
-| Guides | 4 | ✅ Complete |
-| Reports | 6 | ✅ Complete |
-| **Total** | **32** | 🟢 Android Fix Deployed |
+| File | Description |
+|------|-------------|
+| [reports/implementation-complete.md](./reports/implementation-complete.md) | Implementation completion report |
+| [reports/changes-reference.md](./reports/changes-reference.md) | Reference of all code changes |
+| [reports/code-fixes-summary.md](./reports/code-fixes-summary.md) | Bug fixes and improvements summary |
+| [reports/code-fixes-index.md](./reports/code-fixes-index.md) | Complete code fixes index |
+| [reports/test-coverage-report.md](./reports/test-coverage-report.md) | Test coverage metrics |
+| [reports/test-files-summary.md](./reports/test-files-summary.md) | Summary of all test files |
+| [reports/test-summary.md](./reports/test-summary.md) | ModelUri bug fix test suite summary |
+| [reports/fix-drag-delete.md](./reports/fix-drag-delete.md) | Drag-delete fix report |
+| [reports/DDD_STRUCTURE_UPDATE.md](./reports/DDD_STRUCTURE_UPDATE.md) | DDD structure update report |
+| [reports/DDD_STRUCTURE_COMPARISON.md](./reports/DDD_STRUCTURE_COMPARISON.md) | DDD structure comparison |
+| [reports/ANDROID_SPLASH_IMPLEMENTATION_REPORT.md](./reports/ANDROID_SPLASH_IMPLEMENTATION_REPORT.md) | Android splash screen implementation report |
+| [reports/ios-workflow-implementation-summary.md](./reports/ios-workflow-implementation-summary.md) | iOS workflow implementation summary |
+| [reports/i18n-implementation-report.md](./reports/i18n-implementation-report.md) | i18n implementation report |
+| [reports/i18n-build-fix-report.md](./reports/i18n-build-fix-report.md) | i18n build fix report |
---
-## 🔄 Recent Updates
-
-- **2026-03-30**: 🆕 **[Drag-and-Drop Design Document](./DRAG_DROP_DESIGN.md)** - Complete UX/Architecture design for drag-to-move and drag-to-delete
-- **2024-04-02**: ✅ **Android State Sync Bug FIXED** - rememberUpdatedState solution implemented
-- **2024-04-02**: Added 4 new Android documentation files (fix analysis, quick reference, deployment guide, session summary)
-- **2024-03-30**: 🔴 **Android ARCore critical analysis completed** - 5 major issues found in hit testing
-- **2024-03-30**: Added Android ARCore implementation documentation (3 new files)
-- **2024-03-31**: Documentation reorganized into `docs/` folder structure
-- **2024-03-31**: Agents updated with Flutter-inspired DDD patterns
-- **2024-03-31**: Added Value Objects, DTO/Mapper patterns, Base Classes
-- **2024-03-30**: Initial agent system created
-
-## ⚠️ Action Required
-
-### 🔴 Android Critical Issues
-The Android ARCore implementation has **5 critical issues** that must be fixed before production:
+### Reviews
-1. **Missing Anchor usage** - Models not anchored properly
-2. **No hit result filtering** - Distance/confidence checks missing
-3. **No plane tracking state checks** - Can place on invalid planes
-4. **No pose polygon validation** - Models can float in air
-5. **DepthPoint not prioritized** - Missing most accurate placement
-
-**Estimated fix time:** 5 hours (Sprint 1)
-**See:** [ANDROID_ARCORE_HIT_TEST_ANALYSIS.md](./ANDROID_ARCORE_HIT_TEST_ANALYSIS.md) for detailed fixes
+| File | Description |
+|------|-------------|
+| [reviews/README.md](./reviews/README.md) | Reviews overview |
+| [reviews/DESIGN_REVIEW_SUMMARY.md](./reviews/DESIGN_REVIEW_SUMMARY.md) | Design review summary |
+| [reviews/DESIGN_DOCS_REVIEW_2026-04-05.md](./reviews/DESIGN_DOCS_REVIEW_2026-04-05.md) | Design docs review |
+| [reviews/APP_ICON_INTEGRATION_REVIEW_2026-04-05.md](./reviews/APP_ICON_INTEGRATION_REVIEW_2026-04-05.md) | App icon integration review |
+| [reviews/SPLASH_REVIEW_SUMMARY.md](./reviews/SPLASH_REVIEW_SUMMARY.md) | Splash screen review summary |
+| [reviews/SPLASH_SCREENS_REVIEW_2026-04-05.md](./reviews/SPLASH_SCREENS_REVIEW_2026-04-05.md) | Splash screens review |
+| [reviews/ACTION_ITEMS_DESIGN_ANALYSIS_AGENT.md](./reviews/ACTION_ITEMS_DESIGN_ANALYSIS_AGENT.md) | Design analysis agent action items |
---
-## 📚 External References
+## Navigation by Role
-- [Kotlin Multiplatform Documentation](https://kotlinlang.org/docs/multiplatform.html)
-- [ARCore Developer Guide](https://developers.google.com/ar)
-- [ARKit Documentation](https://developer.apple.com/documentation/arkit)
-- [Clean Architecture by Uncle Bob](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
-- [Domain-Driven Design Reference](https://www.domainlanguage.com/ddd/reference/)
+- **Developers**: [CLAUDE.md](../CLAUDE.md) → [architecture/technical-analysis.md](./architecture/technical-analysis.md) → [guides/](./guides/)
+- **Android Devs**: [guides/arcore-quick-reference.md](./guides/arcore-quick-reference.md) → [guides/hit-testing/](./guides/hit-testing/)
+- **iOS Devs**: [ios/ios-quick-reference.md](./ios/ios-quick-reference.md) → [ios/ios-arkit-hit-testing-report.md](./ios/ios-arkit-hit-testing-report.md)
+- **Testers**: [guides/test-implementation-guide.md](./guides/test-implementation-guide.md) → [reports/test-coverage-report.md](./reports/test-coverage-report.md)
+- **Reviewers**: [guides/code-review-checklist.md](./guides/code-review-checklist.md)
diff --git a/docs/README.md b/docs/README.md
index a8e7974..7061e1c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,44 +2,40 @@
All ARSample project documentation is organized here.
-## 📂 Folder Structure
+## Folder Structure
```
docs/
├── INDEX.md # Master documentation index (start here!)
├── architecture/ # System design and technical analysis
-├── agents/ # Multi-agent development system
-├── ios/ # iOS-specific documentation
-├── guides/ # How-to guides and checklists
-└── reports/ # Status reports and summaries
+├── bugs/ # Bug reports and fixes
+├── design/ # UI/UX design system and guidelines
+├── guides/ # How-to guides and checklists
+├── ios/ # iOS-specific documentation
+├── reports/ # Status reports and summaries
+└── reviews/ # Code and design review reports
```
-## 🚀 Getting Started
-
-**New to the project?** Start here:
+## Getting Started
1. **[INDEX.md](./INDEX.md)** - Complete documentation index
-2. **[../CLAUDE.md](../CLAUDE.md)** - Architecture overview
-3. **[agents/README.md](./agents/README.md)** - Development workflow
+2. **[../CLAUDE.md](../CLAUDE.md)** - Architecture overview and key patterns
+3. **[../.claude/agents/README.md](../.claude/agents/README.md)** - Development workflow
-## 📚 Quick Links
+## Quick Links
### For Developers
-- [Main Developer Agent](./agents/main-developer-agent.md)
-- [Architecture Guide](./architecture/TECHNICAL_ANALYSIS.md)
+- [Architecture Guide](./architecture/technical-analysis.md)
+- [ARCore Quick Reference](./guides/arcore-quick-reference.md)
+- [Deployment Guide](./guides/deployment-guide.md)
### For Testers
-- [Test Implementation Guide](./guides/TEST_IMPLEMENTATION_GUIDE.md)
-- [Test Coverage Report](./reports/TEST_COVERAGE_REPORT.md)
+- [Test Implementation Guide](./guides/test-implementation-guide.md)
+- [Test Coverage Report](./reports/test-coverage-report.md)
### For Reviewers
-- [Code Review Checklist](./guides/CODE_REVIEW_CHECKLIST.md)
-- [Code Reviewer Agent](./agents/code-reviewer-agent.md)
+- [Code Review Checklist](./guides/code-review-checklist.md)
### Platform-Specific
- [iOS Documentation](./ios/)
-- [Android Expert Agent](./agents/android-expert-agent.md)
-
----
-
-**📖 For the complete navigation guide, see [INDEX.md](./INDEX.md)**
+- [Android Hit Testing](./guides/hit-testing/)