defrag: cross-page analysis findings

[github-actions]

The monthly defrag analysis identified the following cross-page issues.
Each finding should be reviewed and resolved interactively.

Section: .

Redundancy

• brand.mdx duplicates basic Dojo introduction content that exists in overview.mdx. The brand.mdx page states "The Dojo logo represents the complete framework and toolchain for building provable games and applications. For an overview of how the tools work together, see the Dojo Overview." The overview.mdx has the comprehensive explanation of what Dojo is and should be the primary source.

• Both brand.mdx and overview.mdx describe the same toolchain components (Katana, Torii, Sozo, Saya/Slot) with similar explanations. The overview.mdx versions are more comprehensive and should be the canonical source.

Terminology

• "provable games" vs "provable applications": faq.md uses "provable games" while overview.mdx and brand.mdx use "provable applications". Prefer "provable applications" as it's more inclusive.

• "onchain games" vs "onchain applications": faq.md focuses on "onchain games" while other files use "onchain applications". The broader term "onchain applications" should be preferred for consistency.

• "Autonomous Worlds" vs "autonomous worlds": inconsistent capitalization across files. Standardize on "Autonomous Worlds" (capitalized) when referring to the concept.

Missing Cross-References

• installation.mdx mentions Cairo and Scarb requirements but should link to the Cairo explanation in faq.md ("What is Cairo?")

• faq.md discusses "What is an autonomous world?" but doesn't link to the more detailed coverage in overview.mdx

• installation.mdx mentions troubleshooting and GitHub issues but should cross-reference the FAQ section for common questions

Content Relocations

• The toolchain descriptions in brand.mdx (Katana, Torii, Sozo, Saya sections) should be removed since they duplicate content that's better covered in overview.mdx and the individual toolchain pages. Keep only the brand assets and logos.

• The "What is Cairo?" explanation in faq.md should be moved to overview.mdx as it's foundational information about Dojo's dependencies, not a frequently asked question.

Heading Inconsistencies

• brand.mdx uses "## Core Dojo Brand" while other sections use "## Toolchain", "## Ecosystem Libraries" - the "Core" prefix is unnecessary and inconsistent with other headings

• installation.mdx uses both "### System Requirements" and "#### Install asdf" - inconsistent heading levels within the same logical grouping

• faq.md mixes "###" and "###" for question headings under the same topic sections

---

Section: client

Redundancy

• Redundant SDK introduction patterns: Multiple files (bevy.md, godot.md, unity.md, unrealengine.md) have nearly identical opening paragraphs describing their respective engines. Each follows the pattern "X is a [description of engine]... Dojo.X is the official X SDK..." Consider creating a shared template or cross-referencing pattern.
• Installation instructions duplicated: Several files repeat similar "Prerequisites" and "Getting Started" sections with cargo/package manager commands. The JavaScript SDK and Unity SDK both have detailed dependency installation steps that could reference a common setup guide.

Terminology

• "SDK" vs "bindings": Used inconsistently across files. JavaScript file calls it "dojo.js SDK", C files refer to "C Bindings API", Unity calls it "Dojo.Unity SDK". Should standardize on either "SDK" or clarify the distinction.
• "Torii client" vs "ToriiClient": Mixed usage of capitalized class name vs descriptive term across files.
• "Contract bindings" vs "binding generation" vs "bindings": Used interchangeably without clear distinction.

Missing Cross-References

• client/sdk/c/index.mdx discusses the foundation architecture but doesn't link to the individual binding pages (c-bindings.mdx, wasm-bindings.mdx) that it mentions.
• client/sdk/index.md mentions "Complete C API Reference" and "Complete JavaScript API Reference" but these are not the actual file names (should link to c-bindings and wasm-bindings).
• client/sdk/javascript.md should link to client/sdk/c/wasm-bindings.mdx when mentioning it's "a wrapper around dojo.c".
• client/sdk/bevy.md, unity.md, unrealengine.md mention being built on dojo.c but don't link to client/sdk/c/index.mdx.
• client/sdk/telegram.md references JavaScript SDK but doesn't link to client/sdk/javascript.md.

Content Relocations

• The section "Foundation-First Architecture" in client/sdk/index.md contains detailed technical information about Cainome and dojo.c that would be better placed in client/sdk/c/index.mdx, with a summary remaining in the overview.
• The "Common Patterns" section in client/sdk/index.md duplicates some content that appears in individual SDK files and could be consolidated.

Heading Inconsistencies

• Inconsistent capitalization: "Getting Started" vs "Getting started" vs "Getting Started"
• Section naming patterns vary: some files use "Core Concepts" while others use "Key Features" or "Core Components" for similar introductory content
• Installation sections inconsistently named: "Installation", "Download", "Prerequisites", "Setup"

---

Section: framework

Cross-Page Analysis Report

Redundancy

• Model API and introspection content: framework/models/api.md extensively covers model operations and storage, while framework/models/introspection.md covers the Introspect trait. There's some overlap in discussing model serialization and the DojoStore trait. The content in api.md appears more comprehensive for the API reference, while introspection.md should focus purely on the Introspect trait implementation details.

• System architecture patterns: framework/systems/architecture.md and framework/systems/coordination.md have some overlap in discussing how systems work together. architecture.md covers structural patterns while coordination.md focuses on interaction patterns, but both discuss system composition and collaboration. The division is appropriate, but there's minor redundancy in explaining basic system interaction concepts.

• Configuration examples across files: framework/configuration/index.md contains extensive configuration examples that are referenced in multiple other files (world/permissions.md, upgrading guides). The configuration file should be the authoritative source, with other files linking to it rather than duplicating examples.

• Permission concepts: framework/world/permissions.md and framework/world/index.md both explain permission basics. The world/index.md should provide a brief overview and refer to the detailed permissions guide, rather than duplicating permission type explanations.

Terminology

• "Resource" vs "Component": Used inconsistently across files. framework/models/entities.md uses "components" in ECS context, while world-related files use "resources." Prefer "components" for ECS architecture discussions and "resources" for world contract interactions.

• "System" vs "Contract": framework/systems/index.md sometimes refers to systems as contracts and sometimes as functions within contracts. Prefer "system" for the logical unit and "contract" for the deployment unit.

• "Entity ID" vs "Entity identifier": Used interchangeably across model files. Prefer "entity ID" for consistency.

• "Namespace" vs "namespace hash": Sometimes written as "namespace" (string) and sometimes as "namespace hash" (felt252). Be consistent about when referring to the string vs the hash.

• "Tag" vs "Selector": framework/world files sometimes conflate these terms. A "tag" is the human-readable "namespace-resource" format, while a "selector" is the felt252 hash. Use consistently.

Missing Cross-References

• framework/models/index.md should link to framework/models/entities.md when discussing ECS composition patterns

• framework/systems/index.md should link to framework/models/entities.md when explaining the ECS trinity

• framework/world/index.md should link to framework/world/permissions.md when first mentioning permissions

• framework/configuration/index.md should link to framework/world/metadata.md when discussing world metadata configuration

• framework/testing/index.md should link to framework/models/api.md and framework/systems/index.md for testing specific components

• framework/upgrading/dojo-1-7.md should link to framework/models/introspection.md when discussing the DojoStore trait changes

• framework/systems/libraries.md should link to framework/configuration/index.md for library configuration details

• framework/models/upgrades.md should link to framework/models/introspection.md when discussing IntrospectPacked vs Introspect trade-offs

Content Relocations

• Model API examples: framework/models/index.md contains some basic API usage examples that duplicate content in framework/models/api.md. Move the detailed API examples to api.md and keep only conceptual examples in index.md.

• Permission configuration examples: framework/world/permissions.md contains detailed configuration examples that belong in framework/configuration/index.md. Move the configuration syntax to the configuration guide and reference it from permissions.md.

• Testing setup examples: framework/upgrading/dojo-1-7.md contains detailed testing setup information that should be in framework/testing/index.md. Move the testing API changes to the testing guide.

• ECS architecture explanation: framework/index.mdx contains a detailed ECS explanation that overlaps with framework/systems/index.md. Consolidate the ECS explanation in one place (preferably index.mdx as the overview) and reference it from other files.

Heading Inconsistencies

• Configuration sections: framework/configuration/index.md uses "Profile Configuration" while other files refer to "Dojo Configuration" or "Project Configuration". Standardize on "Profile Configuration" for profile-specific files.

• API reference sections: Some files use "API Reference" while others use "API" or "Reference". Standardize on "API Reference" for comprehensive API documentation.

• Best Practices sections: Some files use "Best Practices" while others use "Tips" or "Guidelines". Standardize on "Best Practices" for actionable recommendations.

• Example sections: Inconsistent use of "Examples", "Usage Examples", "Common Patterns", and "Practical Examples". Standardize on "Examples" for basic usage and "Common Patterns" for architectural patterns.

• Troubleshooting sections: framework/upgrading/dojo-1-7.md uses "Troubleshooting" while framework/testing/cheat-codes.md uses "Common Issues". Standardize on "Troubleshooting" for problem-solving guidance.

---

Section: getting-started

Cross-Page Documentation Analysis: Getting Started Section

Redundancy

• Development Commands: The "Quick Reference: Development Commands" section in development-workflow.mdx substantially duplicates basic command patterns already covered in understanding-the-toolchain.mdx. The toolchain file has better explanations of what each command does, while the workflow file just lists commands. Consider consolidating these into a single reference section in the toolchain file and having the workflow file reference it.

Terminology

• "World" capitalization: Used as "World" (capitalized) in your-first-dojo-app.mdx and development-workflow.mdx, but as "world" (lowercase) in understanding-the-toolchain.mdx when referring to the deployed instance. Prefer consistent capitalization - "World" when referring to the concept/contract, "world" when referring to a specific instance.
• "Profile" vs "Environment": understanding-the-toolchain.mdx uses "profiles" and "environments" somewhat interchangeably when discussing deployment targets. Prefer "profile" consistently as this matches the Sozo terminology.

Missing Cross-References

• your-first-dojo-app.mdx should link to understanding-the-toolchain.mdx when mentioning Katana, Torii, and Sozo tools in Step 3, rather than just briefly describing them
• development-workflow.mdx should link to understanding-the-toolchain.mdx in the "Setting Up Your Development Environment" section where it references tool concepts
• understanding-the-toolchain.mdx should link to development-workflow.mdx in the "How The Toolchain Works Together" section when describing the typical flow
• next-steps.mdx should link to specific framework documentation sections (like /toolchain/katana/) when mentioning advanced configurations

Content Relocations

• The "Katana Configuration", "Torii Configuration", and "Sozo Profiles" sections in understanding-the-toolchain.mdx contain substantial configuration details that would be better placed in the individual tool reference pages (/toolchain/katana/, /toolchain/torii/, /toolchain/sozo/). The getting-started section should focus on basic usage, with detailed configuration referenced elsewhere.
• The "Troubleshooting Common Issues" section in understanding-the-toolchain.mdx should be moved to development-workflow.mdx where debugging is a core topic.

Heading Inconsistencies

• development-workflow.mdx uses "## Quick Reference: Development Commands" while other files use simple "##" headings without colons
• understanding-the-toolchain.mdx uses "### Development vs Production" while development-workflow.mdx uses "### Local to Testnet Progression" for similar deployment-related content - consider standardizing the progression terminology
• next-steps.mdx uses emoji in headings like "### 🎮 For Game Developers" while other files use plain text headings

---

Section: libraries

Redundancy

None found.

Terminology

• cross-references to other library: Alexandria refers to Origami as "game-specific primitives", while Origami refers to Alexandria as "general Cairo utilities" - these are consistent and complementary descriptions.

Missing Cross-References

• libraries/alexandria/index.mdx should link to libraries/origami/index.mdx in the final paragraph where it mentions "developers should also consider Origami for game-specific primitives"
• libraries/origami/index.mdx should link to libraries/alexandria/index.mdx in the final paragraph where it mentions "developers should also consider Alexandria for general Cairo utilities"

Content Relocations

None found.

Heading Inconsistencies

• Crate section organization: Alexandria uses "Key Crates" for major crates followed by "Additional Crates" for others, while Origami uses individual top-level headings for each crate (## Algebra, ## Map, etc.). This creates an inconsistent navigation structure within the libraries section. Consider standardizing to either approach across both pages.

---

Section: scaling

Redundancy

None found.

Terminology

• sovereign rollup vs sovereign chain: "sovereign rollups" used throughout sovereign-rollups.md, while execution-sharding.md refers to "sovereign chains" when contrasting with execution sharding. Prefer "sovereign rollups" for consistency.

Missing Cross-References

• execution-sharding.md mentions sovereign rollups in contrast but should link to /scaling/sovereign-rollups when stating "Execution sharding differs from sovereign rollups"
• sovereign-rollups.md should link to /scaling/execution-sharding when stating "For alternative scaling approaches that maintain stronger connection to mainnet, see execution sharding"

Content Relocations

None found.

Heading Inconsistencies

• execution-sharding.md uses "Planned Architecture" vs "Proposed Shard Initialization" vs "Planned Execution Flow" - mixing "Planned" and "Proposed" terms. Should consistently use "Planned" throughout since this describes planned functionality under development.

---

Section: toolchain

Looking at these 18 documentation pages from the "toolchain" section, I'll analyze them for cross-page issues:

Redundancy

• Binding generation content: The core concept of what bindings are and basic usage patterns is explained in both /toolchain/cainome.mdx and /toolchain/sozo/binding-generation.md. The Cainome page has a more comprehensive explanation of what bindings are conceptually, while Sozo focuses on the practical workflow. The Cainome explanation should be the canonical reference, with Sozo referencing it.

• Installation instructions: Multiple files contain nearly identical installation instructions using dojoup, asdf, and building from source (katana/index.md, sozo/index.md, torii/index.md). These should be consolidated or reference a central installation guide.

Terminology

• "World introspection": used as "world introspection" in sozo/index.md and torii/index.md, but "World introspection" (capitalized) in sozo/index.md header. Prefer lowercase "world introspection".

• Profile terminology: sozo files use both "profile" and "environment" to refer to the same concept (dev, staging, prod configurations). Prefer "profile" consistently.

• Block production vs mining: katana files use both "block production" and "mining" for the same concept. The development.md file uses "Block Production Modes" as a heading but then refers to "Interval Mining" and "On-demand Mining". Prefer "block production" as the primary term with "mining" as a secondary reference.

Missing Cross-References

• katana/index.md should link to sozo when discussing "Unlike validators who verify blocks in consensus" - should reference Sozo for deployment workflows
• sozo/binding-generation.md should link to cainome.mdx when mentioning "For the architectural details of binding generation, see the Cainome documentation" (this link already exists and is correct)
• katana/development.md mentions "See the complete RPC Reference" but should link to katana/reference.md
• Multiple files mention Starkli integration but should cross-reference each other for consistent account management approaches
• saya files should cross-reference katana's advanced features section when discussing settlement and proving

Content Relocations

• The detailed explanation of "What are Bindings?" in /toolchain/cainome.mdx (multiple paragraphs with code examples) would be better placed in a shared concepts section, as it's referenced by both Cainome and Sozo documentation.

• The installation sections in katana/index.md, sozo/index.md, and torii/index.md are nearly identical and should be moved to a central installation guide that all tools reference.

• The "Data Format Reference" section in sozo/index.md (the table with prefixes like u256, str, arr) should be moved to sozo/world-interaction.md where data formatting is more contextually relevant during system execution.

Heading Inconsistencies

• Configuration files use inconsistent heading patterns: katana/configuration.md uses "TOML Configuration" while torii/configuration.md uses "TOML Configuration" but katana uses "Complete Configuration Reference" vs torii's "Basic Configuration"

• API reference sections: torii/graphql.md uses "Quick Start" while torii/grpc.md uses "Quick Start" (consistent), but katana/reference.md uses "RPC Method Namespaces" for similar organizational content

• Installation sections: katana/index.md uses "Installation" as top-level, sozo/index.md uses "Installation", torii/index.md uses "Installation" - these are consistent

• Getting started sections: inconsistent between "Getting Started", "Quick Start", and "Getting Started" + "Quick Start" as separate sections across different tools

---

Section: tutorials

Redundancy

• Significant overlap between deploy-to-mainnet/main.md and deploy-using-slot/main.md in the Torii deployment section. Both cover creating Torii configuration files and deployment commands. The mainnet deployment guide has the more comprehensive Torii section that includes advanced configuration and management details. The slot deployment guide should defer to the mainnet guide for detailed Torii setup and focus only on basic slot-specific configuration.

Terminology

• "development network" vs "devnet": used as "development network" in deploy-using-slot/main.md, "devnet" in katana-starkli-scarb/main.md. Prefer "devnet".
• "smart contracts" vs "contracts": used as "smart contracts" in katana-starkli-scarb/main.md title, but "contracts" throughout all other files. Prefer "contracts".

Missing Cross-References

• advanced.mdx should link to dojo-starter.mdx in the Prerequisites section when mentioning "foundational concepts"
• deploy-using-slot/main.md should link to deploy-to-mainnet/main.md when mentioning "comprehensive Torii indexer deployment including advanced configuration options"
• katana-starkli-scarb/main.md should link to dojo-starter.mdx when mentioning users wanting to work with the complete Dojo framework
• onchain-chess/0-setup.md should link to dojo-starter.mdx when referencing the "hello-dojo" chapter
• react.mdx should link to dojo-starter.mdx in the Next Steps section when mentioning "foundational Dojo tutorial"

Content Relocations

• The Torii deployment section in deploy-using-slot/main.md (from "## Torii" onwards) should be condensed to a brief overview that references the comprehensive guide in deploy-to-mainnet/main.md. The detailed Torii configuration, service management, and troubleshooting content belongs in the mainnet deployment guide.

Heading Inconsistencies

• deploy-to-mainnet/main.md uses "Sepolia / Mainnet Deployment" while deploy-using-slot/main.md uses "Deploy your game using Slot" - inconsistent title patterns for deployment tutorials.
• onchain-chess/ files use numbered prefixes in titles ("0. Setup", "1. Actions") while other tutorial files use descriptive titles only.

---

Created automatically by the defrag analysis workflow.