Skip to content

README-CODE-REVIEW-DOCUMENTATION.md

Latest commit

 

History

History
472 lines (397 loc) · 59.1 KB

README-CODE-REVIEW-DOCUMENTATION.md

File metadata and controls

472 lines (397 loc) · 59.1 KB

Documentation Review Notes (README Analysis)

See the main Project Code and Documentation Review file for overall context and prompts.

README.md (root)

  • Purpose: Main project overview, executive summary, architecture overview, key innovations, repository structure, getting started.
  • Content Quality: Good high-level overview. Introduces the core components (BackSpace, CraftSpace) and pipeline.
  • Redundancy: Contains a high-level architecture diagram and component description also found in other documentation files (e.g., README-BACKSPACE.md, README-CRAFTSPACE.md). Some overlap with README-PHILOSOPHY.md regarding vision.
  • Suggestions:
    • Keep this as the main entry point and high-level overview.
    • Ensure it links clearly to the more detailed component READMEs (README-BACKSPACE.md, README-CRAFTSPACE.md, README-VISUALIZATION.md, README-IA-INTEGRATION.md).
    • Potentially shorten the architecture overview here and rely more on links to detailed docs.
    • The 'Key Innovations' section overlaps heavily with README-VISUALIZATION.md. Consider summarizing here and linking.
    • 'Future Directions' overlaps with README-TODO.md. Link to README-TODO.md for details.
    • The 'Getting Started' section is good but could link to more detailed setup guides if they exist (e.g., specific setup for BackSpace or CraftSpace development).
  • Location: Correctly placed at the root.

README-SCHEMAS.md (root)

  • Purpose: Describes the schema system (Zod -> JSON Schema -> C#), pipeline, safety rules, key models, best practices, IA metadata handling, extraFields, update workflow.
  • Content Quality: Very detailed and crucial for understanding the cross-platform data modeling. Explains the core pipeline well, including the nuances of WebGL compatibility and the extraFields mechanism.
  • Redundancy: Contains significant overlap with sections in Unity/CraftSpace/README-SCHEMAS.md. The content appears nearly identical in structure and detail, covering the pipeline, base classes, view system, types/converters, directory structure, best practices, and schema evolution.
  • Suggestions:
    • Merge: This file should be the Single Source of Truth (SSOT) for the overall schema system philosophy and pipeline across all platforms (TS, JSON, C#).
    • The content currently duplicated in Unity/CraftSpace/README-SCHEMAS.md should be removed from the Unity version.
    • The Unity-specific README (Unity/CraftSpace/README-SCHEMAS.md) should focus only on Unity-specific implementation details not covered here, like the exact usage of SchemaGeneratedObject, the Brewster registry interaction, specifics of the C# generation tool (SchemaGenerator.cs), and how the manual C# classes (Item.cs, Collection.cs) extend the generated ones. It seems Unity/CraftSpace/README-SCHEMAS.md might be redundant if README-UNITY-CODE.md or README-UNITY-IMPLEMENTATION.md cover the Unity side adequately.
    • Consider renaming this to README-DATA-MODELING.md or README-SCHEMA-SYSTEM.md for clarity if it becomes the main document.
    • Ensure clear links from Unity documentation back to this main schema document.
  • Location: Keep at the root as it describes a system spanning multiple components (BackSpace, Unity, Content).

Unity/CraftSpace/README-UNITY-BRIDGE.md

  • Purpose: Explains the communication bridge between Unity and JavaScript (JS), covering architecture, setup, JSON integration (BridgeJsonConverter), the Interest Query System, Path Expressions, JS API, best practices, and troubleshooting.
  • Content Quality: Detailed explanation of a complex but crucial system. The Interest Query System and Path Expressions sections are particularly valuable.
  • Redundancy: Some overlap with README-UNITY-OVERVIEW.md in terms of the high-level JS-first architecture. The JSON integration section (BridgeJsonConverter) might have some conceptual overlap with the schema system (README-SCHEMAS.md) but focuses specifically on the bridge's converters, which seems distinct enough. README-UNITY-IMPLEMENTATION.md might touch on interaction, but this focuses specifically on the JS bridge.
  • Suggestions:
    • Keep this file focused solely on the JS <-> Unity communication bridge.
    • Ensure README-UNITY-OVERVIEW.md links here for detailed bridge information.
    • Clarify the relationship between BridgeJsonConverter and the main schema serialization/deserialization (SchemaGeneratedObject, Newtonsoft.Json). Are they used together? Does the bridge converter handle types not covered by the schema system?
    • The "Setup Guide" section seems slightly misplaced if it's just about setting up the Bridge component in a scene. Consider merging this setup detail into README-UNITY-IMPLEMENTATION.md or README-UNITY-CODE.md (scene setup section) and keeping this README focused on the concepts and API of the bridge.
  • Location: Should remain within the Unity/CraftSpace/ directory as it's Unity-specific.

Unity/CraftSpace/README-UnITY-BRIDGE-SETUP.md

  • Purpose: Unknown, appears to be a stub or accidental file.
  • Content Quality: Empty (contains only a space).
  • Redundancy: N/A.
  • Suggestions:
    • Delete: This file is empty and serves no purpose. Any relevant setup information should be in README-UNITY-BRIDGE.md or README-UNITY-IMPLEMENTATION.md.
  • Location: N/A (to be deleted).

Unity/CraftSpace/README-UNITY-CINEMACHINE.md

  • Purpose: Describes the Cinemachine camera system implementation, design philosophy, camera types (Overview, Browse, Detail, Magic Carpet), device motion integration, collaborative control, effects, performance, and resolution-aware zoom/projection blending.
  • Content Quality: Very detailed on the camera system's features and philosophy. The sections on resolution-aware zoom, projection blending, and motion-based zoom are particularly innovative and well-explained.
  • Redundancy: Some conceptual overlap with README-UNITY-NAVIGATION.md (camera movement) and potentially README-UNITY-COLLABORATIVE.md (multi-user camera aspects). The core Cinemachine concepts are distinct, but how navigation uses these cameras might overlap.
  • Suggestions:
    • Keep this focused on the camera system itself (Cinemachine setup, virtual cameras, effects, device integration, zoom dynamics).
    • Ensure README-UNITY-NAVIGATION.md focuses on the user control and mechanics of moving through space, explaining how it utilizes the cameras defined here (e.g., switching between Browse and Detail cams based on context).
    • Consolidate the collaborative camera control aspects here or in README-UNITY-COLLABORATIVE.md, but avoid duplicating the explanation. Perhaps this file describes the capability and the collaborative file describes the specific implementation/experience.
    • The resolution-aware zoom and projection blending sections are excellent and seem specific to the camera system, so they belong here.
  • Location: Correctly placed within Unity/CraftSpace/.

Unity/CraftSpace/README-UNITY-COLLABORATIVE.md

  • Purpose: Describes collaborative features: Tandem Magic Carpet navigation, Admiration Marking ("Curination"), financial appreciation, social dynamics, technical implementation, UX, and input mechanics.
  • Content Quality: Good description of unique collaborative concepts, particularly the "Curination" idea and its inspiration. Explains the social and financial aspects well.
  • Redundancy: Significant overlap with README-UNITY-CINEMACHINE.md regarding collaborative camera control/Magic Carpet mechanics (input blending, coordination rewards, feedback). The "Curination" concept seems unique to this file. Financial appreciation details might be better suited for a higher-level project goal document or a dedicated features doc, unless tightly coupled with the collaborative navigation.
  • Suggestions:
    • Merge/Refactor: Decide where the definitive explanation of collaborative navigation lives. Either merge the detailed input mechanics/dynamics into README-UNITY-CINEMACHINE.md (if focusing on camera capabilities) or into README-UNITY-NAVIGATION.md (if focusing on user control). This file could then focus primarily on the social/curation aspects ("Curination", financial support, social dynamics) and simply refer to the collaborative navigation mechanics documented elsewhere.
    • Alternatively, keep this as the main "Collaboration Features" doc, but significantly trim down the navigation mechanics explanation here and link to the Cinemachine/Navigation docs for details.
    • The "Curination" concept is unique and well-explained; keep that part.
    • Consider if the "Financial Appreciation Mechanisms" belong here or in a higher-level design document.
  • Location: Correctly placed within Unity/CraftSpace/.

Unity/CraftSpace/README-UNITY-COLLECTIONLAYOUT-PREFAB.md

  • Purpose: Provides brief instructions on how to create the CollectionLayoutPrefab GameObject in Unity, including required components (CollectionGridLayout) and basic configuration.
  • Content Quality: Very minimal, essentially a short setup note.
  • Redundancy: This information is highly specific to setting up one particular prefab. It partially overlaps with the prefab setup sections described in README-UNITY-IMPLEMENTATION.md and README-UNITY-CODE.md.
  • Suggestions:
    • Merge/Delete: This content should be merged into the prefab setup section of a more comprehensive Unity implementation guide (likely README-UNITY-IMPLEMENTATION.md or README-UNITY-CODE.md). A standalone file for setting up a single prefab is unnecessary.
    • Delete this file after merging its content.
  • Location: N/A (to be deleted/merged).

Unity/CraftSpace/README-UNITY-IMPLEMENTATION.md

  • Purpose: A comprehensive guide to the Unity implementation, covering architecture (Model-View-Renderer), core components (Brewster, CollectionBrowserManager), View System (IModelView, CollectionView, ItemViewsContainer, ItemView, ViewFactory), Layout System (CollectionGridLayout), Control System (CameraController, InputManager, CollectionDisplay), Prefab Setup, and Scene Setup.
  • Content Quality: Very detailed and appears to be a central document explaining how the Unity application is structured and put together. Covers many key classes and their roles.
  • Redundancy: Significant overlap exists with other Unity READMEs:
    • README-UNITY-CODE.md: Both describe core architecture, components (Brewster, Managers, Factory, etc.), prefab setup, and scene setup. README-UNITY-CODE.md seems slightly higher level on architecture but duplicates specific prefab/scene instructions.
    • README-UNITY-COLLECTIONLAYOUT-PREFAB.md: The content of this file is essentially covered in the Prefab Setup section here.
    • README-UNITY-INPUT.md: The InputManager description here overlaps with the purpose of the dedicated Input README.
    • README-UNITY-CINEMACHINE.md / README-UNITY-NAVIGATION.md: The CameraController description here overlaps with these.
    • README-UNITY-VISUALIZATION.md: The descriptions of Views (CollectionView, ItemView, etc.) overlap with the visualization concepts.
  • Suggestions:
    • Consolidate: This file or README-UNITY-CODE.md should become the primary Unity implementation guide.
    • Merge Content: Merge the essential setup instructions from README-UNITY-COLLECTIONLAYOUT-PREFAB.md here.
    • Refactor/Link: Instead of duplicating detailed descriptions of components like InputManager or CameraController, summarize their role within the overall architecture here and link to the dedicated READMEs (README-UNITY-INPUT.md, README-UNITY-CINEMACHINE.md, README-UNITY-NAVIGATION.md) for details.
    • Similarly, summarize the View system's role and link to README-UNITY-VISUALIZATION.md for the deep dive on visualization techniques.
    • Decide whether this file or README-UNITY-CODE.md is the main implementation guide and merge/delete the other, ensuring all essential information (architecture, core component descriptions, prefab/scene setup) is retained in one place.
  • Location: Correctly placed within Unity/CraftSpace/.

Unity/CraftSpace/README-UNITY-INPUT.md

  • Purpose: Describes the multi-platform input system using Unity's New Input System, covering actions, gesture recognition, motion controls, accessibility, multi-user input, WebGL specifics, debugging, and controller/sensor support.
  • Content Quality: Good overview of the input strategy, covering various platforms and features like gestures and motion controls.
  • Redundancy: The InputManager is briefly described in README-UNITY-IMPLEMENTATION.md, creating minor overlap. The multi-user input section overlaps conceptually with README-UNITY-COLLABORATIVE.md and README-UNITY-MULTISCREEN.md.
  • Suggestions:
    • Keep this file focused on the input system implementation (New Input System setup, action maps, gesture recognizers, device sensor integration).
    • Ensure the InputManager description in README-UNITY-IMPLEMENTATION.md is high-level and links here for details.
    • Coordinate with README-UNITY-COLLABORATIVE.md and README-UNITY-MULTISCREEN.md regarding multi-user input. This file should describe the technical foundation for handling multiple inputs, while the other files describe the features/experiences built upon it.
  • Location: Correctly placed within Unity/CraftSpace/.

Unity/CraftSpace/README-UNITY-MULTISCREEN.md

  • Purpose: Describes the architecture for multi-screen installations, including configuration types, implementation approach (ScreenOrchestrator), display roles, content synchronization, user tracking, special interactions, network architecture, and installation guide.
  • Content Quality: Describes a potentially complex feature set for installations. Provides a good overview of the concepts involved.
  • Redundancy: User identification/tracking and potentially some interaction concepts might overlap with README-UNITY-COLLABORATIVE.md and README-UNITY-INPUT.md (multi-user aspects).
  • Suggestions:
    • Keep this file focused on the specifics of multi-screen coordination (synchronization, display roles, spatial awareness between screens, handoff).
    • Ensure multi-user aspects mentioned here (like user identification) are coordinated with README-UNITY-COLLABORATIVE.md and README-UNITY-INPUT.md. This file could describe how users are tracked across screens, while the others focus on collaborative input within a screen or the general input mechanism.
    • Clarify if this is a currently implemented feature or a design document for a future capability.
  • Location: Correctly placed within Unity/CraftSpace/.

Unity/CraftSpace/README-UNITY-NAVIGATION.md

  • Purpose: Describes future enhancements and the specific "Ballistic Link Navigation" (cannon-like) system, including launch mechanics, atlas-optimized flight paths, user control during flight, visual feedback, and integration.
  • Content Quality: Provides a good, focused description of a specific navigation feature ("Ballistic Link"). The atlas optimization aspect is particularly interesting.
  • Redundancy: The "Planned Future Enhancements" section at the top belongs in README-TODO.md. The core concept of navigation overlaps with README-UNITY-CINEMACHINE.md (which describes the cameras used for navigation) and README-UNITY-IMPLEMENTATION.md (which mentions the CameraController).
  • Suggestions:
    • Move Enhancements: Move the list of future enhancements to README-TODO.md.
    • Focus: Keep this file narrowly focused on the user control mechanics and specific navigation features like the Ballistic Link system. It should explain how the user moves the camera/viewpoint.
    • Clarify Role: Clearly distinguish this from README-UNITY-CINEMACHINE.md. Cinemachine describes the cameras (virtual cams, blending, effects, zoom dynamics), while this file describes the control systems that drive those cameras (WASD input, ballistic links, etc.).
    • Ensure the CameraController description in README-UNITY-IMPLEMENTATION.md links here for navigation mechanic details.
  • Location: Correctly placed within Unity/CraftSpace/.

Unity/CraftSpace/README-UNITY-OVERVIEW.md

  • Purpose: Provides a high-level overview of the Unity implementation, focusing on the JS-first architecture, design philosophy (visualization-as-a-service), project structure, application flow, and links to related documentation.
  • Content Quality: Good conceptual overview, explaining the architectural choice of making Unity a rendering layer controlled by JS.
  • Redundancy: The architecture overview, project structure, and application flow concepts are also touched upon in README.md (root), README-CRAFTSPACE.md, README-UNITY-IMPLEMENTATION.md, and README-UNITY-CODE.md. The JS-first philosophy is central but also mentioned elsewhere.
  • Suggestions:
    • Consolidate/Merge: This file's purpose seems very similar to README-CRAFTSPACE.md (which also gives an overview of the Unity client). It also overlaps heavily with the architectural descriptions in README-UNITY-IMPLEMENTATION.md / README-UNITY-CODE.md.
    • Consider merging the essential philosophy (JS-first, visualization-as-a-service) into the main Unity implementation guide (README-UNITY-IMPLEMENTATION.md or README-UNITY-CODE.md).
    • The project structure information should definitely be in the main implementation guide.
    • The application flow description is useful but could also live in the main implementation guide or potentially in README-UNITY-BRIDGE.md (as it describes the JS-Unity interaction flow).
    • This file might be redundant if its key concepts are integrated into other, more comprehensive documents.
  • Location: Currently in Unity/CraftSpace/, but its content might be better merged elsewhere.

Unity/CraftSpace/README-UNITY-PERFORMANCE.md

  • Purpose: Focuses on Unity performance optimization, specifically for WebGL. Covers key metrics, asset optimization (textures, meshes), memory management, rendering optimizations, WebGL specifics, progressive enhancement, loading performance, and testing.
  • Content Quality: Provides specific, actionable advice on optimizing Unity for WebGL. Covers important areas like texture limits, shaders, asset management, and loading.
  • Redundancy: Some overlap with README-VISUALIZATION.md and README-UNITY-VISUALIZATION.md which discuss performance related to specific visualization techniques (LOD, culling, atlasing). README-UNITY-CINEMACHINE.md also mentions performance considerations for cameras.
  • Suggestions:
    • Keep this file focused on general Unity WebGL performance tuning that applies across the board (e.g., Quality Settings, memory management, general rendering pipeline settings, build settings).
    • Ensure that performance advice specific to visualization techniques (like atlas optimization, LOD strategies for rendering) resides primarily in README-VISUALIZATION.md (or its Unity counterpart) and links back here for general platform tuning.
    • Similarly, performance tips specific to the camera system should stay in README-UNITY-CINEMACHINE.md.
    • This serves as a good central place for WebGL-specific performance knowledge.
  • Location: Correctly placed within Unity/CraftSpace/.

Unity/CraftSpace/README-UNITY-PACKAGES.md

  • Purpose: Describes Unity package dependencies, integration philosophy (schema-driven), Bridge extensions, required packages (TextMeshPro, Newtonsoft, Input System, Cinemachine, ProBuilder), JSON.NET integration, NJsonSchema usage, schema examples (Material), and compatibility notes.
  • Content Quality: Good overview of the packages used and the philosophy behind integrating them using schemas. Explains the role of key dependencies.
  • Redundancy: Mentions JSON.NET integration, which is also touched on in the schema documentation (README-SCHEMAS.md and Unity/CraftSpace/README-SCHEMAS.md) and potentially the bridge (README-UNITY-BRIDGE.md). Mentions Input System, Cinemachine, ProBuilder which have their own dedicated or related READMEs (README-UNITY-INPUT.md, README-UNITY-CINEMACHINE.md, README-UNITY-VISUALIZATION.md).
  • Suggestions:
    • Keep this file as the central inventory of Unity package dependencies and their specific integration points/rationale within the CraftSpace project.
    • Minimize the detailed explanation of how packages like Cinemachine or Input System are used here; instead, link to their dedicated READMEs.
    • Focus on the why these packages were chosen and how they fit into the schema-driven architecture.
    • The schema examples (e.g., MaterialSchema) are useful illustrations of the integration philosophy and should likely stay here or be moved to the main schema documentation (README-SCHEMAS.md) if that becomes the SSOT for schema definitions.
    • Clarify the relationship between Bridge and this project's bridge/schema system.
  • Location: Correctly placed within Unity/CraftSpace/.

Unity/CraftSpace/README-UNITY-VISUALIZATION.md

  • Purpose: Describes the Unity visualization system: philosophy, dynamic content generation (ProBuilder, covers, multi-resolution hierarchy, atlasing, map-aware atlasing, region-based metadata), spatial organization models, adaptive LOD, effects, performance, and schema-driven visualization (BookViz schema, ProBuilder pipeline).
  • Content Quality: Extremely detailed and technical explanation of the visualization techniques. The sections on multi-resolution hierarchy, map-aware atlasing, and the ProBuilder pipeline are particularly valuable.
  • Redundancy: Massive overlap with the root README-VISUALIZATION.md. Both cover the philosophy, dynamic generation, multi-res hierarchy, atlasing, spatial models, LOD, effects, performance, and schema aspects in similar detail. Also overlaps with README-UNITY-IMPLEMENTATION.md and README-UNITY-CODE.md regarding view components, and with README-UNITY-PERFORMANCE.md regarding performance.
  • Suggestions:
    • Merge/Eliminate: This file appears almost entirely redundant with the root README-VISUALIZATION.md. The root version should be the SSOT for the overall visualization concepts and techniques.
    • This Unity-specific file should only contain details about the Unity implementation of those concepts not covered elsewhere. For example:
      • Specific shader implementation details.
      • Details on the MaterialPropertyBlock usage for atlases.
      • Concrete C# class names implementing the LOD transitions or spatial layouts (if not covered in README-UNITY-IMPLEMENTATION.md).
      • Specific ProBuilder API usage examples within Unity.
    • Most of the current content (philosophy, multi-res hierarchy, atlas concepts, spatial models concepts) belongs in the root README-VISUALIZATION.md.
    • Performance details should likely live in README-UNITY-PERFORMANCE.md or the root README-VISUALIZATION.md.
    • Strong Candidate for Deletion: If the root README-VISUALIZATION.md is comprehensive and README-UNITY-IMPLEMENTATION.md covers the core Unity classes, this file might be entirely unnecessary.
  • Location: Currently in Unity/CraftSpace/, but most of its content belongs at the root or should be merged/deleted.

README-CICD.md (root)

  • Purpose: Explains the CI/CD setup, focusing on local development (schema regeneration, building), self-hosted Mac runner setup (using run-unity.sh), multi-version Unity support, and log checking.
  • Content Quality: Practical guide for setting up local builds and understanding the CI runner script. Explains the use of the wrapper script well.
  • Redundancy: Overlaps significantly with README-GITHUB.md (which covers GitHub Actions workflows, self-hosted runners, build acceleration) and README-GITHUB-RUNNER-SETUP-MAC.md (which provides detailed Mac runner setup instructions).
  • Suggestions:
    • Merge/Refactor: This file seems largely redundant.
    • The local development build/schema commands (npm run build-*, npm run regenerate-schemas) should be in the main README.md getting started/development section or potentially README-BACKSPACE.md if they primarily operate from there.
    • The CI/CD setup details (self-hosted runner, wrapper script, multi-version support) belong in README-GITHUB.md (for the workflow context) or README-GITHUB-RUNNER-SETUP-MAC.md (for the specific runner setup).
    • The run-unity.sh script explanation is useful and should be incorporated into the main CI/CD documentation (README-GITHUB.md).
    • Delete this file after merging its useful parts elsewhere.
  • Location: Currently at root, but content should be merged into other root READMEs.

README-BACKSPACE.md (root)

  • Purpose: Describes the BackSpace SvelteKit application: responsibilities (content pipeline, web UI, API server, deployment, auth), project structure, data pipeline/deployment/caching strategy (static vs dynamic, storage locations, cache levels), key components, API endpoints, dev setup, building, adding collections, performance, deployment, and troubleshooting.
  • Content Quality: Comprehensive guide to the SvelteKit part of the project. Explains the crucial data pipeline and caching strategy in detail.
  • Redundancy: The data pipeline/caching strategy overlaps significantly with README-DATA-ARCHITECTURE.md and parts of README-IA-INTEGRATION.md. The overview and responsibilities touch on things mentioned in the main README.md. API endpoint descriptions might belong in a dedicated API doc (like the one mentioned in README-DOC-INDEX.md). Development setup and build commands overlap with the main README.md and potentially README-CICD.md.
  • Suggestions:
    • Keep this file focused on the SvelteKit application itself: its structure, key Svelte components, UI aspects, specific server logic, and how it hosts/interacts with the Unity build.
    • Refactor/Link Data Pipeline: Abstract the detailed data pipeline/caching strategy into README-DATA-ARCHITECTURE.md (as the SSOT for data flow) and link to it from here. This file should explain how BackSpace participates in the pipeline (e.g., running processing scripts, serving API endpoints for data) rather than defining the whole strategy.
    • API Docs: Move the detailed API endpoint list to a dedicated API documentation file (e.g., SvelteKit/BackSpace/src/routes/api/README.md if that exists and is suitable) and link from here.
    • Dev Setup: Consolidate common dev setup instructions (like npm install) in the main README.md. Keep BackSpace-specific dev commands (npm run dev, npm run build:scripts, npm run pipeline-*) here.
  • Location: Keep at the root as it's a major top-level component.

README-CRAFTSPACE.md (root)

  • Purpose: Describes the CraftSpace Unity client: overview, features (spatial viz, multi-res, navigation, content integration, WebGL), architecture, core components (Visualization, Navigation, UI, Data Integration), spatial models, performance, multi-device experience, use cases, emulation, dev workflow, customization, BackSpace integration (communication protocol, JS bridge), future directions.
  • Content Quality: Good overview of the Unity client component, its features, and how it fits into the larger project.
  • Redundancy: Significant overlap with other READMEs:
    • README.md (root): General overview and architecture.
    • Unity/CraftSpace/README-UNITY-OVERVIEW.md: Very similar purpose and content (high-level Unity client overview).
    • Unity/CraftSpace/README-UNITY-IMPLEMENTATION.md / README-UNITY-CODE.md: Covers architecture, core components, dev workflow, customization.
    • README-VISUALIZATION.md / Unity/CraftSpace/README-UNITY-VISUALIZATION.md: Covers visualization system, multi-res, spatial models, performance.
    • Unity/CraftSpace/README-UNITY-NAVIGATION.md: Covers navigation.
    • Unity/CraftSpace/README-UNITY-INPUT.md: Covers interaction.
    • Unity/CraftSpace/README-UNITY-MULTISCREEN.md / README-UNITY-COLLABORATIVE.md: Covers multi-device/multi-user aspects.
    • Unity/CraftSpace/README-UNITY-BRIDGE.md: Covers BackSpace integration/JS bridge.
    • README-TODO.md: Covers future directions.
  • Suggestions:
    • Consolidate/Refactor: This file acts as a high-level aggregator for many Unity-specific topics.
    • Consider making this the main entry point for Unity-related documentation within the Unity/CraftSpace/ directory (perhaps rename it to Unity/CraftSpace/README.md).
    • It should provide a concise overview of the CraftSpace client and its capabilities.
    • Heavily use links: Instead of describing visualization, navigation, bridge, implementation details, etc., link to the dedicated READMEs for each of those topics (README-UNITY-VISUALIZATION.md - if kept, README-UNITY-NAVIGATION.md, README-UNITY-BRIDGE.md, README-UNITY-IMPLEMENTATION.md, etc.).
    • The Development Workflow section might belong in the main Unity implementation guide.
    • Future Directions should link to README-TODO.md.
  • Location: Currently at root, but seems like it should be the primary README inside the Unity/CraftSpace/ directory.

README-CURSOR.md (root)

  • Purpose: Explicitly stated as being for AI assistants, reminding them of design philosophy, conventions (TypeScript, Svelte 5, ESM, Zod), cross-platform type safety, data management philosophy (filesystem-first, regenerate), naming conventions (IDs), and schema-driven development approach. Links to related docs.
  • Content Quality: Contains concise bullet points summarizing key architectural decisions and conventions. Useful for onboarding or reminding an AI/developer of the project's standards.
  • Redundancy: Summarizes philosophies and conventions detailed elsewhere (e.g., schema approach in README-SCHEMAS.md, filesystem approach in README-IA-INTEGRATION.md or README-DATA-ARCHITECTURE.md, general philosophy in README-PHILOSOPHY.md).
  • Suggestions:
    • Keep this file as intended - a meta-document for AI/developer conventions. It serves a unique purpose.
    • Ensure it accurately reflects the conventions established in the more detailed documents and is kept up-to-date as decisions evolve.
    • Potentially rename it to README-CONVENTIONS.md or README-DESIGN-PRINCIPLES.md to be clearer for human developers, while still serving the AI assistant reminder purpose.
    • Verify the ID naming conventions described here match the actual implementation and other documentation.
  • Location: Correctly placed at the root as it covers project-wide conventions.

README-DATA-ARCHITECTURE.md (root)

  • Purpose: Outlines the data architecture, content flow from IA, caching strategy (static vs dynamic, storage locations - Raw, Unity Resources, SvelteKit Static, Dynamic Content), cache levels/types, invalidation/versioning, future enhancements (Vector DB, ML, VR, Collaborative), and the content processing pipeline.
  • Content Quality: Provides a structured overview of how data moves through the system and where it's stored. Good explanation of the caching tiers.
  • Redundancy: The caching strategy and storage locations are described in significant detail here and also within README-BACKSPACE.md. The content processing pipeline overview is also touched upon in README-BACKSPACE.md, README-IA-INTEGRATION.md, and README-SCRIPTS.md.
  • Suggestions:
    • Make this file the Single Source of Truth (SSOT) for the overall data flow and caching strategy across the entire project.
    • Remove the detailed caching/storage explanations from README-BACKSPACE.md and have it link here.
    • Keep the description of the processing pipeline high-level here, focusing on the stages data goes through. Link to README-IA-INTEGRATION.md and README-SCRIPTS.md for the implementation details of the pipeline steps.
    • Future enhancements listed here should probably be consolidated into README-TODO.md.
  • Location: Correctly placed at the root as it describes project-wide data architecture.

README-DOC-INDEX.md (root)

  • Purpose: Serves as a central index for all documentation files, providing a brief description of each README and links.
  • Content Quality: Useful meta-document for navigating the documentation. Descriptions seem accurate based on the files reviewed so far.
  • Redundancy: By its nature, it lists files that exist elsewhere. This is expected for an index.
  • Suggestions:
    • Maintain: Keep this file and ensure it stays up-to-date as documentation is merged, deleted, renamed, or added.
    • This will be crucial after the documentation refactoring is complete.
    • Consider grouping the files by category (e.g., Core, BackSpace, Unity, Concepts, Infrastructure) within the index for better organization.
  • Location: Correctly placed at the root.

README-EMOJIS.md (root)

  • Purpose: Describes the emoji logging system conventions, including categories (objects, actions, status, parameters), phrase patterns, Unicode symbols, progress bars, log line structure, implementation details, and visual analysis tips.
  • Content Quality: Very detailed and provides a clear standard for using emojis in logs. Includes useful examples and visual patterns.
  • Redundancy: This is a unique document describing a specific project convention. It might be referenced by README-CURSOR.md (conventions) or potentially a general logging/debugging guide if one existed.
  • Suggestions:
    • Keep this file as the definitive guide to the emoji logging standard.
    • Ensure the implementation location (src/lib/utils/logger.ts) mentioned is correct and the code actually follows these conventions.
    • Consider adding a brief mention of this system in README-CURSOR.md (or README-CONVENTIONS.md).
  • Location: Correctly placed at the root as it's a project-wide convention.

README-ERROR-HANDLING.md (root)

  • Purpose: Describes the exception-based error handling strategy, core principles, custom error types (NotFoundError, ValidationError, etc.), handling examples, logging, and API error responses.
  • Content Quality: Clear and concise explanation of the error handling approach. Provides useful guidelines.
  • Redundancy: Unique focus on error handling strategy. Might be referenced by README-CURSOR.md (conventions).
  • Suggestions:
    • Keep this file as the standard for error handling.
    • Ensure the custom error types listed are actually defined in src/lib/errors.ts as mentioned.
    • Verify that the API error response mapping is consistently applied in the BackSpace API implementation.
    • Could be linked from README-CURSOR.md / README-CONVENTIONS.md.
  • Location: Correctly placed at the root.

README-GITHUB-RUNNER-SETUP-MAC.md (root)

  • Purpose: Detailed step-by-step guide for setting up a macOS self-hosted GitHub Actions runner specifically for Unity builds, including installing Unity, configuring the runner service, setting environment variables, troubleshooting, discussing why self-hosted runners are needed for Unity, and optimizing workflows with persistent workspaces.
  • Content Quality: Very detailed, practical, and specific setup guide. Includes important context about Unity CI/CD challenges (licensing, resources, project size) and solutions (persistent workspaces).
  • Redundancy: Overlaps significantly with README-GITHUB.md (which also discusses self-hosted runners, workflows, build acceleration) and README-CICD.md (which discusses self-hosted Mac setup and the run-unity.sh script).
  • Suggestions:
    • Consolidate: This contains critical setup information that should be part of the main CI/CD documentation.
    • Merge the detailed setup steps, troubleshooting, rationale for self-hosted runners, and persistent workspace optimization strategy into README-GITHUB.md.
    • README-GITHUB.md should become the SSOT for all GitHub Actions, CI/CD, and runner setup information.
    • The information about concurrent Unity instances and batch mode is very important and should be prominently featured in the main CI/CD doc.
    • Delete this file after merging its content into README-GITHUB.md.
  • Location: Currently at root, but its content belongs in the primary CI/CD document (README-GITHUB.md).

README-GITHUB.md (root)

  • Purpose: Describes GitHub integration, CI/CD using Actions, directory structure (.github/), rapid development pipeline philosophy (component independence, iteration speeds), Unity build acceleration, deployment matrix, development workflow, automated workflows (SvelteKit, Unity, Collections), setup instructions (repo secrets, Mac runner - brief), Docker config, deployment (DO), troubleshooting, workflow overview, shared scripts, required secrets, running workflows, adding components, workflow integration, content dev workflow (JS hot-patching), and containerized runners plan.
  • Content Quality: Very comprehensive document covering the entire CI/CD and GitHub workflow strategy. The pipeline philosophy and component iteration strategies are well-articulated. Contains a mix of high-level strategy and specific setup details.
  • Redundancy: Contains sections on self-hosted runner setup that overlap heavily with README-GITHUB-RUNNER-SETUP-MAC.md and README-CICD.md. Discusses build scripts/commands also mentioned in README-CICD.md and README-BACKSPACE.md. Briefly mentions IA integration scripts (README-SCRIPTS.md, README-IA-INTEGRATION.md). Docker config might relate to README-BACKSPACE.md deployment.
  • Suggestions:
    • Make this the Single Source of Truth (SSOT) for all CI/CD, GitHub Actions, and deployment strategies.
    • Merge Content: Merge the detailed Mac runner setup, rationale, and persistent workspace info from README-GITHUB-RUNNER-SETUP-MAC.md into this file.
    • Merge Content: Merge the run-unity.sh script explanation and relevant CI context from README-CICD.md here.
    • Refactor: Streamline the setup instructions here, perhaps linking to external docs for basics (like installing Homebrew) but keeping the project-specific configuration (secrets, runner labels, workflow setup) here.
    • Keep the pipeline philosophy, workflow descriptions, deployment strategy, and JS hot-patching sections as they provide crucial context.
    • Ensure clear links to related component READMEs (e.g., BackSpace, Unity, IA Integration) when discussing their specific build/deploy steps within the workflows.
  • Location: Correctly placed at the root.

README-IA-INTEGRATION.md (root)

  • Purpose: Describes scripts and architecture for integrating with Internet Archive (IA). Covers components (Registry, Downloader, Pipeline, Unity Export), multi-tier architecture (Raw Cache, Deployment Targets, Dynamic Collections), directory structure, collection configuration (targets), discovery (directory scanning), registry usage (npm commands), processing commands, deployment target specs, advanced processing (EPUB), performance optimizations, tile pyramids, atlases, deployment infrastructure (DO Spaces/CDN), and item metadata file conventions (item.json), directory-based management, cache performance (collections-cache.json), runtime exports (index.json).
  • Content Quality: Very detailed and crucial for understanding how content is sourced, processed, and structured. Explains the filesystem-as-database approach well.
  • Redundancy: The multi-tier architecture, deployment targets, caching, and pipeline concepts overlap significantly with README-DATA-ARCHITECTURE.md and README-BACKSPACE.md. Script usage (npm run ia:*) overlaps with README-SCRIPTS.md. Atlas generation overlaps with README-VISUALIZATION.md.
  • Suggestions:
    • Make this file the SSOT for interacting with the Internet Archive specifically and the raw Collections/ directory structure/philosophy.
    • Focus on: IA API interaction details, the downloader, the registry logic, the structure within the Collections/ directory (including item.json convention), advanced content processing logic (like EPUB details), and the npm run ia:* commands for managing collections at the source.
    • Refactor/Link: Move the general data architecture concepts (multi-tier caching, deployment targets, overall pipeline stages) to README-DATA-ARCHITECTURE.md and link from here. This file should explain the IA-specific part of that architecture (the Raw Cache tier and how it's populated).
    • Move the description of the npm run ia:* commands (and other script details) to README-SCRIPTS.md and link from here.
    • Keep the explanation of the directory-based management and item.json/index.json conventions here, as it defines the fundamental structure derived from IA.
    • Atlas/Tile pyramid generation concepts belong in README-VISUALIZATION.md, but this file could mention that the processing pipeline triggers their generation.
  • Location: Correctly placed at the root.

README-PHILOSOPHY.md (root)

  • Purpose: Articulates the core philosophy behind SpaceCraft, covering IA integration mission, filesystem-first design, theoretical frameworks (Engelbart, Constructionism, Simulator Effect, Procedural Rhetoric), single source of truth principle, and technical/ethical implications.
  • Content Quality: High-level, thoughtful explanation of the project's guiding principles and theoretical underpinnings. Connects the project to broader ideas in HCI, learning, and digital archives.
  • Redundancy: Some overlap with the mission/vision parts of the main README.md. The filesystem-first design principle is also covered technically in README-IA-INTEGRATION.md and README-CURSOR.md. Single source of truth is mentioned in README-CURSOR.md and relevant to README-SCHEMAS.md.
  • Suggestions:
    • Keep this file as the high-level philosophical and theoretical foundation document. It provides important context that doesn't fit well in purely technical READMEs.
    • Ensure the main README.md summarizes the core mission and links here for the deeper philosophical background.
    • Ensure technical documents (README-IA-INTEGRATION.md, README-SCHEMAS.md) focus on the implementation of principles like filesystem-first or SSOT, while this file explains the why.
  • Location: Correctly placed at the root.

README-SCRIPTS.md (root)

  • Purpose: Provides an overview of scripts used for content processing, build automation, deployment, and utilities. Covers the TypeScript build system, script categories (IA Integration, Content Processing, Build/Deploy, Utils), NPM script commands, directory structure, common workflows, development guidelines, common implementation patterns, debugging, CI/CD integration, performance considerations, and planned enhancements.
  • Content Quality: Good central guide to the project's scripting infrastructure. Explains the organization and provides usage examples.
  • Redundancy: The NPM script commands (npm run ia:*, npm run build:*) overlap with README-IA-INTEGRATION.md and README-BACKSPACE.md / README-CICD.md. Workflow descriptions touch on processes detailed in README-IA-INTEGRATION.md and README-GITHUB.md. CI/CD integration points to README-GITHUB.md.
  • Suggestions:
    • Keep this file as the central inventory and guide for all automation scripts in the project (primarily those in SvelteKit/BackSpace/scripts/).
    • Focus on the purpose of each script category/script, the TypeScript build system for scripts, development guidelines for scripts, common patterns used within scripts, and debugging scripts.
    • List the main npm run ... commands here as the central reference, but ensure detailed explanations of what those commands do for specific areas (like IA integration) reside in the relevant feature READMEs (e.g., README-IA-INTEGRATION.md) and link back here for the command reference.
    • The common workflows section is useful here, illustrating how scripts are combined.
  • Location: Correctly placed at the root.

README-TODO.md (root)

  • Purpose: Outlines the development roadmap, organizing planned tasks by component area (Core Infra, Web App, Unity Viz, Multi-Device, Emulation, AI, VR/XR, DevOps) and priority level (P1-P6). Includes instructions on how to use and contribute to the roadmap.
  • Content Quality: Provides a clear, structured overview of planned work. Priority levels help guide focus. Seems reasonably detailed.
  • Redundancy: Future plans sections in other READMEs (e.g., README.md, README-DATA-ARCHITECTURE.md, README-CRAFTSPACE.md, README-UNITY-NAVIGATION.md, README-VISUALIZATION.md) are redundant with this file.
  • Suggestions:
    • Keep this file as the Single Source of Truth (SSOT) for all planned features, enhancements, and future work.
    • Remove "Future Directions" / "Planned Enhancements" sections from all other READMEs and ensure they link to this file instead.
    • Maintain this file actively, marking items as completed or adjusting priorities as the project evolves.
    • Consider adding estimated effort levels (e.g., Small, Medium, Large) or linking tasks to specific GitHub Issues for more detailed tracking.
  • Location: Correctly placed at the root.

README-UNITY-CODE.md (root? -> Should be Unity/CraftSpace/)

  • Purpose: Describes Unity code structure: Core Architecture (Brewster, Managers, Factory), Dev Environment Setup (IDE extensions, Cursor, Git LFS), Required Prefabs (CollectionView, ItemView), Scene Setup, Component Relationships, Data Flow, Common Issues, and JSON Handling Best Practices (Newtonsoft vs JsonUtility).
  • Content Quality: Contains practical information about setting up the dev environment and understanding the core Unity class relationships and prefabs/scene structure. The JSON handling best practices section is important.
  • Redundancy: Significant overlap with Unity/CraftSpace/README-UNITY-IMPLEMENTATION.md, covering architecture, components, prefabs, scene setup, relationships, and data flow. Dev Environment setup might be better in a general project setup guide or the main README.md. JSON handling best practices relate to the schema system (README-SCHEMAS.md).
  • Suggestions:
    • Merge/Consolidate: This file duplicates much of README-UNITY-IMPLEMENTATION.md. Decide which one should be the primary Unity implementation guide and merge the content. README-UNITY-IMPLEMENTATION.md seems slightly more comprehensive in its current state.
    • Merge the unique parts of this file (like detailed Dev Environment Setup, JSON Handling Best Practices) into the chosen primary implementation guide or other relevant documents (README.md for general setup, README-SCHEMAS.md for JSON practices if not Unity-specific).
    • The prefab/scene setup details should definitely be consolidated into one place.
    • Delete this file after merging.
  • Location: Currently listed at root, but belongs in Unity/CraftSpace/. However, likely to be deleted after merging.

README-VISUALIZATION.md (root)

  • Purpose: Comprehensive overview of visualization techniques: philosophy, multi-resolution system (hierarchy, ultra-low res techniques, embedded icons), texture atlas system (generation, structure, levels), Unity rendering implementation (mesh, shader, material, LOD, culling, transitions), spatial organization models, visualization pipeline, performance optimization, special features (emulation, SimCity, multi-device gameplay), and future enhancements.
  • Content Quality: Extremely detailed and well-explained document covering the core visualization concepts and implementation strategies. Contains unique and valuable information about the multi-resolution approach, atlasing, and spatial models.
  • Redundancy: Massive overlap with Unity/CraftSpace/README-UNITY-VISUALIZATION.md. Mentions performance (README-UNITY-PERFORMANCE.md), spatial organization (README-CRAFTSPACE.md), emulation (README-CRAFTSPACE.md), future plans (README-TODO.md).
  • Suggestions:
    • Make this the Single Source of Truth (SSOT) for all visualization concepts, techniques, and strategies across the project.
    • Merge/Eliminate: Merge any unique Unity-specific implementation details from Unity/CraftSpace/README-UNITY-VISUALIZATION.md into this document (if appropriate) or into README-UNITY-IMPLEMENTATION.md, then delete the Unity version.
    • Keep the detailed explanations of the multi-resolution system, ultra-low res techniques, atlas system concepts, spatial organization models, and special features like emulation here.
    • Refactor/Link: Summarize performance aspects and link to README-UNITY-PERFORMANCE.md for Unity-specific tuning. Link to README-TODO.md for future enhancements. Ensure README-CRAFTSPACE.md links here for visualization details.
  • Location: Correctly placed at the root as it describes a core, cross-cutting concept.

Unity/CraftSpace/Assets/Scripts/Schemas/Generated/README.md

  • Purpose: Explains the generated C# schema classes: where they come from (JSON schemas via BackSpace TS types), how to generate them (BackSpace script, Unity menu), schema features (converters, Unity Inspector integration), implementation details (extraFields, Model-View pattern), base class (SchemaGeneratedObject), source flow, requirements, namespace, usage guidelines, regeneration steps, and troubleshooting.
  • Content Quality: Very important information explaining how the generated C# classes work and how they are created. The explanation of extraFields and the Model-View pattern in SchemaGeneratedObject is crucial.
  • Redundancy: Significant overlap with README-SCHEMAS.md (root) and Unity/CraftSpace/README-SCHEMAS.md. Both describe the generation pipeline, the extraFields mechanism, the base class, type converters, and usage guidelines.
  • Suggestions:
    • Merge/Refactor: This file describes the result of the schema generation process specifically for the C# side.
    • The pipeline overview (JSON Schemas -> C# Classes) belongs in the main README-SCHEMAS.md (root).
    • The detailed explanation of SchemaGeneratedObject (including extraFields and Model-View) is vital Unity implementation detail. This should be merged into the main Unity implementation guide (README-UNITY-IMPLEMENTATION.md or potentially README-UNITY-CODE.md before it's deleted). Alternatively, if Unity/CraftSpace/README-SCHEMAS.md is kept and refocused on Unity specifics, this content could go there.
    • The instructions on how to trigger the generation (Tools > Import JSON Schema) should be in the main Unity implementation/setup guide.
    • Delete this file after merging its essential content (especially the SchemaGeneratedObject details) into the appropriate Unity documentation.
  • Location: Currently deep within the Unity project structure. Its content needs to be elevated.

Unity/CraftSpace/README-SCHEMAS.md

  • Purpose: Describes the CraftSpace schema system, covering the pipeline overview (TS -> JSON -> Generated C# -> Extended C#), generation process examples (TS, JSON, C#), SchemaGeneratedObject base class (JSON serialization, extraFields, Model-View), View System (IModelView, registration), schema types/converters (Collection, Item, specific converters), directory structure, best practices, and schema evolution.
  • Content Quality: Detailed explanation, particularly strong on the C# implementation aspects like the base class and view system interaction.
  • Redundancy: Massive overlap with README-SCHEMAS.md (root) and Unity/CraftSpace/Assets/Scripts/Schemas/Generated/README.md. Covers the same pipeline, base class features (extraFields, Model-View), converters, best practices, and evolution steps.
  • Suggestions:
    • Merge/Refactor/Delete: This file is largely redundant with the root README-SCHEMAS.md (which should be the SSOT for the overall system) and the Generated schemas README (which covers the base class details).
    • If kept, this file should be drastically trimmed to focus only on Unity-specific schema aspects not covered elsewhere, such as:
      • How the manual extension classes (Item.cs, Collection.cs) interact with the generated *Schema.cs classes and the Brewster registry.
      • Specific Unity editor integration details (if any beyond what the generator README covers).
      • Maybe the specific implementation of the IModelView<T> pattern within Unity views.
    • However, these details might be better placed in the main Unity implementation guide (README-UNITY-IMPLEMENTATION.md).
    • Strong Candidate for Deletion: Given the overlap, it's likely best to merge the essential unique Unity details (like the C# base class explanation from the Generated README) into README-UNITY-IMPLEMENTATION.md and ensure the root README-SCHEMAS.md covers the overall system, then delete this file.
  • Location: Currently in Unity/CraftSpace/, but likely to be deleted/merged.

SvelteKit/BackSpace/README.md

  • Purpose: Serves as the standard developer README for the SvelteKit application (BackSpace). Provides quick start, comprehensive npm command lists (dev, schema, collection, item, content, system mgmt), links to ../../README-BACKSPACE.md, describes local structure (scripts/, src/, static/), and includes SvelteKit boilerplate.
  • Content Quality: Good. Functional and essential for developers working within this sub-project. The categorized npm scripts section is particularly useful.
  • Redundancy: Minimal. Complements the root README-BACKSPACE.md (which covers the 'what' and 'why') by focusing on the 'how' of SvelteKit development. Correctly links to the root README. Does not significantly overlap with root README-SCRIPTS.md.
  • Suggestions:
    • Keep: Necessary for SvelteKit app development.
    • Maintain the link to the root README-BACKSPACE.md.
    • Optional: Add a note clarifying the relationship between these npm scripts and any corresponding scripts in the root /scripts directory (if applicable).
  • Location: Correctly located at SvelteKit/BackSpace/README.md.

Unity/CraftSpace/Assets/Editor/SchemaGenerator/README.md

  • Purpose: Detailed technical documentation for the C# schema generator tool (SchemaGenerator.cs) itself. Covers critical warnings (no reflection, don't edit generated files), workflow, code organization, features, the Zod .describe() metadata hack, string converters, crucial IL2CPP/WebGL constraints (JSON.NET usage), step-by-step usage, CI/CD commands, supported types, limitations, extraFields handling, and TODOs.
  • Content Quality: Excellent, highly technical, and critical for understanding/modifying the generation process. Clear explanation of IL2CPP constraints and the Zod metadata workaround.
  • Redundancy: Moderate overlap with other schema READMEs on the purpose and output of the schemas. Its unique value is documenting the generator tool itself, its constraints, and the metadata pipeline.
  • Suggestions:
    • Keep: Essential documentation for the generator tool.
    • Refactor/Link: Other schema/Unity READMEs should link to this file for detailed generator/constraint/metadata-hack info, avoiding duplication.
    • Consolidate descriptions of the output (e.g., SchemaGeneratedObject features) into other relevant READMEs (like README-UNITY-IMPLEMENTATION.md or the one in Generated/) and link from here to there.
    • Elevate/summarize the critical JSON.NET/IL2CPP warnings to the main README-UNITY-IMPLEMENTATION.md as they apply broadly to Unity C# JSON handling.
  • Location: Correctly located at Unity/CraftSpace/Assets/Editor/SchemaGenerator/README.md.

Unity/CraftSpace/Assets/StreamingAssets/Content/README.md

  • Purpose: Defines the structure, conventions, and philosophy for the Content/ directory (the runtime content SSOT within Unity). Details the "File System First" approach (directory names as IDs), standard filenames (item.json, collection.json), ID consistency checks, example structure, the crucial need for derived *-index.json files (due to StreamingAssets limitations), schema subdirectory origin/metadata, and critical schema/JSON consumption rules (NO REFLECTION for IL2CPP).
  • Content Quality: Excellent. Clearly explains the structure, naming conventions, and the vital *-index.json workaround.
  • Redundancy: Some overlap with README-DATA-ARCHITECTURE.md on general concepts, but provides necessary implementation details. Repeats the critical JSON.NET/IL2CPP warnings found in the SchemaGenerator README (potentially justified for emphasis). Briefly mentions the Zod metadata hack.
  • Suggestions:
    • Keep: Essential for understanding runtime content structure.
    • Consider centralizing the detailed JSON.NET/IL2CPP rules (e.g., in README-UNITY-IMPLEMENTATION.md) and having a summary/link here, OR keep the repetition for safety.
    • Ensure README-DATA-ARCHITECTURE.md links here for specific Unity content implementation.
    • Ensure the schema metadata section links to the SchemaGenerator README for full details.
  • Location: Correctly located at Unity/CraftSpace/Assets/StreamingAssets/Content/README.md.

Unity/CraftSpace/README-CICD.md

  • Purpose: Explains CI/CD setup specifically for the Unity sub-project. Covers prerequisites, local commands (schema regen, builds via UI/npm), self-hosted Mac runner setup details (installations, env vars, git, automation steps), usage of the run-unity.sh wrapper for headless execution, handling multiple Unity versions, log analysis (check-unity-logs), troubleshooting (Unity detection, permissions, licensing), and links to Unity docs.
  • Content Quality: Good. Practical, step-by-step guide for Unity automation, highlighting the run-unity.sh wrapper.
  • Redundancy: Overlaps in topic with root README-CICD.md, but provides crucial Unity-specific details (headless mode, licensing, versions, build commands) likely not covered in the root file.
  • Suggestions:
    • Keep or Merge: Contains essential Unity details. Either keep separate (clearly defining scope and linking to root README-CICD.md) OR merge unique Unity content into the root README-CICD.md under a dedicated section.
    • Clarify Root Link: If kept separate, explicitly state its relationship to the root CI/CD doc.
    • Consolidate Script Info: Ensure consistency and potentially link to script definitions (run-unity.sh, check-unity-logs).
  • Location: Currently Unity/CraftSpace/. Appropriate if kept separate; content moves to root if merged.