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

• The "provable applications" concept is referenced repeatedly in similar wording across files. overview.mdx has a comprehensive section on this, while faq.md also explains provable games in detail. The faq.md content about provable games should be condensed and defer to overview.mdx for the full explanation.

Terminology

• provable games/applications: Used as "provable games" in faq.md, "provable applications" in overview.mdx and installation.mdx. Should consistently use "provable applications" as the broader term.
• onchain games vs onchain applications: faq.md focuses on "onchain games" while overview.mdx uses "onchain applications" as the broader category. Should be consistent about the hierarchy.

Missing Cross-References

• installation.mdx mentions "Dojo configuration" but should link to the framework configuration docs when available
• faq.md discusses Katana, Torii, Sozo, and Cairo but doesn't link to their respective detailed pages in the toolchain section
• overview.mdx mentions "Entity-Component-System" but doesn't link to framework documentation that would explain this in the Dojo context
• brand.mdx has sections on toolchain tools and libraries but the cross-references could be more prominent/consistent

Content Relocations

• The "Known Limitations" section in faq.md (covering Starknet contract size limit and model composition issues) would be better placed in a technical reference or framework documentation rather than general FAQ
• The detailed system requirements section in installation.mdx could have a condensed version, with full details moved to a dedicated system requirements page

Heading Inconsistencies

• installation.mdx uses "Installing Dojo" as main heading while overview.mdx uses "Dojo Overview" - inconsistent capitalization patterns
• brand.mdx uses "Core Dojo Brand" while other sections use just the tool name (e.g., "Katana" not "Katana Tool")
• faq.md section headings mix question format ("What is...") with topic format ("Known Limitations")

---

Section: client

Redundancy

• Content about "dojo.c" being the foundation for all SDKs appears multiple times across /client/sdk/index.md, /client/sdk/c/index.mdx, and /client/sdk/javascript.md. The best comprehensive explanation is in /client/sdk/index.md under "Foundation-First Architecture". The other files should reference this section rather than repeat the architectural explanation.

• Installation instructions for building from source appear in both /client/sdk/c/c-bindings.mdx and /client/sdk/c/wasm-bindings.mdx. The c-bindings page has the better version with clear prerequisites. The wasm-bindings page should reference it.

• Basic Dojo world connection examples are duplicated between /client/sdk/rust.md and /client/sdk/c/wasm-bindings.mdx (Node.js section). The patterns are very similar but in different languages.

Terminology

• "Controller accounts" vs "Session accounts": Used interchangeably in /client/sdk/c/c-bindings.mdx ("Controller accounts provide session-based gameplay") but /client/sdk/godot.md uses "DojoSessionAccount" consistently. Should clarify if these are the same concept or different.

• "Entity queries" vs "Entity operations": /client/sdk/javascript.md uses "Querying Entities" while /client/sdk/c/wasm-bindings.mdx uses "Entity Operations". Prefer "Entity Queries" for consistency.

• "dojo.c" vs "Dojo.c": Mixed capitalization across files. Use lowercase "dojo.c" consistently as shown in /client/sdk/index.md.

Missing Cross-References

• /client/sdk/bevy.md should link to /client/sdk/c when mentioning "built on the dojo.c foundation"
• /client/sdk/javascript.md should link to /client/sdk/c/wasm-bindings when explaining "dojo.c compiled to WebAssembly"
• /client/sdk/unity.md should link to /client/sdk/c/c-bindings when discussing native integration
• /client/sdk/unrealengine.md should link to /client/sdk/c when mentioning the underlying foundation
• /client/sdk/godot.md should link to /client/sdk/c when stating it's "built on the dojo.c foundation"
• /client/sdk/telegram.md should link to /client/sdk/javascript when referencing "JavaScript SDK docs"

Content Relocations

• The "Common Patterns" section in /client/sdk/index.md (lines about core game loop, account management, transaction flow) would be better placed in a general concepts page rather than the architecture overview. This content applies to all SDKs but is buried in the overview.

• The detailed "Prerequisites" and "Installation" sections in individual SDK pages could be consolidated into a single setup guide that each SDK references, particularly the common requirements like Rust toolchain, build tools, etc.

Heading Inconsistencies

• Installation sections use different patterns: "Getting Started" (bevy, godot, javascript), "Installation" (c-bindings), "Setup" (telegram), "Getting Started > Prerequisites" (unity). Prefer "Getting Started" with "Installation" subsection.

• Examples sections use inconsistent naming: "Example Game" (bevy), "Example Project" (godot, unity, unrealengine), "Complete Example" (telegram), "Additional Examples" (javascript), "Discord Bot Example" (rust). Prefer "Examples" or "Example Project".

• Advanced features use different patterns: "Advanced Features" (bevy), "Advanced API" (c-bindings), "Advanced Queries" (javascript). Prefer "Advanced Features" consistently.

---

Section: framework

I'll analyze these 22 documentation pages from the "framework" section for cross-page issues.

Redundancy

• Model API patterns duplicated across multiple files: Both framework/models/api.md and framework/world/api.md contain substantial overlapping content about model operations (read_model, write_model, etc.). The world API page has the more comprehensive version and should be the canonical reference. The models API page should focus on model-specific functionality and defer to world API for storage operations.

• ECS architecture explanations duplicated: The ECS trinity diagram and explanation appears in both framework/index.mdx and framework/systems/index.md. The framework index page has the better foundational explanation and should be the primary reference.

• Permission configuration duplicated: Permission setup is explained in detail in both framework/configuration/index.md and framework/world/permissions.md. The permissions page has more comprehensive coverage and examples. The configuration page should provide basic permission setup syntax and link to the permissions page for detailed usage.

Terminology

• "World contract" vs "World": Used inconsistently across framework/world/index.md (uses "World contract"), framework/configuration/index.md (uses "world"), and framework/systems/index.md (uses "world"). Prefer "World contract" for the smart contract itself, "world" when referring to the conceptual game world or storage instance.

• "Resource selector" vs "selector": Used interchangeably in framework/world/permissions.md and framework/configuration/index.md. Prefer "resource selector" for clarity.

• "System" vs "contract": In framework/systems/index.md and framework/systems/architecture.md, these terms are used somewhat interchangeably when referring to Dojo contracts. Should consistently use "system" for the logical concept and "contract" when referring to the deployed Cairo contract.

Missing Cross-References

• framework/models/index.md should link to framework/models/entities.md when discussing entity relationships and key design
• framework/systems/index.md should link to framework/systems/architecture.md and framework/systems/coordination.md in the "Next Steps" section
• framework/configuration/index.md should link to framework/world/metadata.md when mentioning world metadata
• framework/testing/index.md should link to framework/testing/cheat-codes.md when mentioning "cheat codes reference"
• framework/models/upgrades.md should link to framework/models/introspection.md when discussing IntrospectPacked vs Introspect trade-offs
• framework/world/index.md should link to framework/models/entities.md when explaining entity-component relationships
• framework/systems/libraries.md lacks cross-references entirely - should link to framework/systems/architecture.md for context on system organization

Content Relocations

• Advanced model operations section: The detailed field-level operations (read_member, write_member, etc.) in framework/models/api.md lines 84-150 would be better placed in framework/world/api.md since these are world storage operations, not model-specific functionality.

• ECS implementation details: The detailed ECS pattern explanation in framework/systems/index.md lines 45-120 should be moved to framework/index.mdx to provide foundational concepts before diving into system specifics.

Heading Inconsistencies

• API reference sections: framework/models/api.md uses "Core Model Trait", "Model Storage Operations" while framework/world/api.md uses "Model Operations", "Event System". Should standardize on the pattern used in world API.

• Configuration sections: framework/configuration/index.md uses "Understanding Profiles", "Configuration Files" while other guides use more action-oriented headings like "Managing Permissions", "Writing Models". Should standardize on action-oriented headings.

• Upgrade guide headings: framework/upgrading/dojo-1-0.md and framework/upgrading/dojo-1-7.md use different patterns for version-specific content ("Dojo 1.0.0 Breaking Changes" vs "The DojoStore trait"). Should use consistent patterns for major changes/features.

---

Section: getting-started

Redundancy

• All five files have nearly identical sections explaining the "Terminal X" workflow for starting Katana, Torii, and Sozo. The most comprehensive version is in development-workflow.mdx, which includes helpful scripts and troubleshooting. The other files (your-first-dojo-app.mdx and understanding-the-toolchain.mdx) should reference the development workflow page instead of duplicating this setup process.

Terminology

• "toolchain" vs "tools": Used inconsistently across files. The section is called "toolchain" but individual files sometimes refer to "tools". Prefer "toolchain" for consistency.
• "World" vs "world": Inconsistent capitalization when referring to the Dojo World contract. Should standardize on "World" when referring to the contract/concept.
• "System" vs "system": Inconsistent capitalization for ECS systems. Should use "System" when referring to the ECS concept.

Missing Cross-References

• development-workflow.mdx should link to understanding-the-toolchain.mdx when first mentioning "Katana", "Torii", and "Sozo" to provide readers context about what these tools are
• your-first-dojo-app.mdx should link to development-workflow.mdx when explaining the development environment setup, since the workflow page has more comprehensive information
• understanding-the-toolchain.mdx should link to development-workflow.mdx when discussing "typical development flow"
• next-steps.mdx should link back to understanding-the-toolchain.mdx when mentioning specific tools like Katana and Torii

Content Relocations

• The "Development Best Practices" section in development-workflow.mdx (lines discussing keeping tools running, using profiles, troubleshooting) would be better placed in understanding-the-toolchain.mdx since it's more about understanding how the tools work together rather than the development cycle itself.
• The detailed tool configuration examples in development-workflow.mdx should move to understanding-the-toolchain.mdx where tool configuration is already discussed.

Heading Inconsistencies

• development-workflow.mdx uses "## The Development Cycle" but other workflow sections use "## Step X:" pattern. Should use consistent "## Step X:" format for workflow steps.
• next-steps.mdx uses emoji in headings like "🎮 For Game Developers" while other files don't use emojis in headings. Should standardize on no emojis in headings for consistency across the section.
• understanding-the-toolchain.mdx uses "## How The Toolchain Works Together" but development-workflow.mdx has "## Development Best Practices" - both should follow the same "## [Topic]" pattern without "The" articles.

---

Section: libraries

Redundancy

None found.

Terminology

• Data structures: Alexandria uses "data structures" while Origami uses "primitives" to describe similar foundational building blocks. Both are correct in context, but ensure clarity when discussing complementary functionality.

Missing Cross-References

• libraries/alexandria/index.mdx should link to libraries/origami/index.mdx when discussing game-specific needs. The current reference "While Alexandria provides general utilities, developers should also consider Origami for game-specific primitives" is present and appropriate.
• libraries/origami/index.mdx should link to libraries/alexandria/index.mdx when discussing general utilities. The current reference "While Origami focuses on game-specific primitives, developers should also consider Alexandria for general Cairo utilities" is present and appropriate.

Content Relocations

None found.

Heading Inconsistencies

• Installation sections: Alexandria uses "Installation" while Origami also uses "Installation" - this is consistent.
• Crate organization: Alexandria uses "Key Crates" for main sections followed by "Additional Crates", while Origami uses direct crate names as top-level headings. Consider standardizing to either approach across both libraries.

---

Section: scaling

Redundancy

None found.

Terminology

• Layer 3: used as "Layer 3"s in execution-sharding.md, but this term is not defined or used consistently elsewhere. Consider defining this term or using more descriptive language like "isolated shard environments."

Missing Cross-References

• execution-sharding.md should link to sovereign-rollups.md when discussing the comparison in the overview section. The text mentions "Execution sharding differs from sovereign rollups" but does not provide a link.
• sovereign-rollups.md should link to execution-sharding.md when discussing "alternative scaling approaches that maintain stronger connection to mainnet" in the introduction section.

Content Relocations

None found.

Heading Inconsistencies

• execution-sharding.md uses "Planned Architecture" while sovereign-rollups.md uses "Technical Architecture" for similar sections describing the overall system design. Consider standardizing to either "Architecture" or "Technical Architecture" across both pages.
• execution-sharding.md uses "Proposed [Feature]" pattern (e.g., "Proposed Shard Initialization", "Proposed Concurrency Management") while sovereign-rollups.md does not use this pattern. Since execution sharding is explicitly marked as planned functionality, this difference may be intentional, but consider consistency in how future/proposed features are labeled in headings.

---

Section: toolchain

Redundancy

• File toolchain/sozo/index.md has a table explaining calldata format prefixes that is duplicated from the "Data Format Reference" section in the same file. The table under "Data Format Reference" is more complete and better positioned, so the earlier incomplete mention should be simplified or removed.

Terminology

• [Chain initialization]: used as "Chain Initialization" in toolchain/katana/advanced.md heading and "chain initialization" in lowercase elsewhere. Prefer sentence case for section references.
• [Binding generation]: used as "Bindings Generation" in toolchain/sozo/binding-generation.md title and "binding generation" in lowercase in toolchain/sozo/index.md. Prefer "Binding Generation" for consistency with the dedicated page title.

Missing Cross-References

• toolchain/cainome.mdx should link to toolchain/sozo/binding-generation.md when mentioning "For more binding generation workflows, see the Sozo bindgen documentation"
• toolchain/katana/advanced.md should link to toolchain/torii/index.md when discussing "Torii Integration (Indexer)" and explaining Torii's caching layer
• toolchain/katana/development.md should link to toolchain/katana/reference.md when mentioning the "RPC Reference" for detailed method documentation
• toolchain/sozo/index.md should link to toolchain/cainome.mdx when mentioning "For the architectural details of binding generation, see the Cainome documentation"
• toolchain/torii/index.md should link to toolchain/katana/index.md when mentioning "For local development with Katana sequencer"

Content Relocations

• The detailed explanation of "What are Bindings?" section in toolchain/cainome.mdx (paragraphs explaining language bindings, their purpose, and the before/after code examples) should be moved to toolchain/sozo/binding-generation.md as it's more relevant to the practical binding generation workflow. toolchain/cainome.mdx should keep a brief definition and refer readers to the Sozo documentation for usage details.

Heading Inconsistencies

• Configuration sections use inconsistent patterns: toolchain/katana/configuration.md uses "Configuration Guide" while toolchain/torii/configuration.md uses "Configuration Guide" (these are actually consistent), but subheadings vary between "TOML Configuration" vs "Configuration Examples" vs "Genesis Configuration" - prefer consistent "X Configuration" pattern.

---

Section: tutorials

Looking at these 13 documentation pages from the "tutorials" section, here's my analysis:

Redundancy

• Chess tutorial content: The onchain-chess tutorial is split across 4 separate files (0-setup.md, 1-action.md, 2-move.md, 3-test.md) plus a README.md. This creates artificial separation where a single comprehensive tutorial might be more user-friendly. The README.md in particular duplicates introductory content that appears in 0-setup.md.

• Contract deployment instructions: Both deploy-to-mainnet/main.md and deploy-using-slot/main.md contain similar Torii deployment sections. The deploy-to-mainnet version is more comprehensive and should be the canonical reference, with deploy-using-slot deferring to it for detailed Torii setup.

Terminology

• Development network: Used as "development network" in deploy-using-slot/main.md, "local development network" in katana-starkli-scarb/main.md, and "devnet" elsewhere. Prefer "development network".

• Contract vs System: advanced.mdx consistently uses "contract" while other files mix "system" and "contract" when referring to Dojo systems. The framework uses both terms but should be consistent within tutorials.

Missing Cross-References

• tutorials/dojo-starter.mdx should link to tutorials/react.mdx when discussing client implementation, as both cover building applications with Dojo
• tutorials/advanced.mdx should reference tutorials/deploy-to-mainnet/main.md when discussing "Production Deployment"
• tutorials/katana-starkli-scarb/main.md should link to tutorials/dojo-starter.mdx for users wanting the complete Dojo framework experience
• tutorials/deploy-using-slot/main.md should cross-reference tutorials/deploy-to-mainnet/main.md for more comprehensive deployment patterns
• tutorials/onchain-chess/README.md should link to tutorials/dojo-starter.mdx as a prerequisite

Content Relocations

• The Torii deployment section in tutorials/deploy-using-slot/main.md (starting with "## Torii") should be condensed to a brief overview that refers readers to the comprehensive guide in tutorials/deploy-to-mainnet/main.md
• The "Debug with Walnut" section in tutorials/deploy-to-mainnet/main.md could be moved to a separate debugging/tooling guide, as it's not specifically about mainnet deployment

Heading Inconsistencies

• Main tutorial headings use different patterns: "Dojo 101 Tutorial" vs "Deploying to Sepolia and Mainnet" vs "Deploying with Slot" vs "Deploy your Cairo smart contract using Katana. Advanced Tutorial"
• Chess tutorial files use inconsistent numbering: "0. Setup" vs "1. Actions" vs "2 Move function" vs "3 Test Contract"
• Some use sentence case ("Setting Up an Onchain Chess Game") while others use different patterns

---

Created automatically by the defrag analysis workflow.