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

None found.

Terminology

• provable games vs onchain games: In faq.md, both terms "provable game" and "onchain game" are defined as distinct concepts, but in overview.mdx they appear to be used interchangeably ("provable applications" and "onchain games"). The terminology should be consistent - clarify whether these are the same or different concepts across all documentation.

Missing Cross-References

• installation.mdx mentions Claude Code skills and provides installation instructions, but overview.mdx also mentions AI-Assisted Development with the same skills. These sections should cross-reference each other.
• brand.mdx has "Read more about..." links to various toolchain components that should align with the detailed descriptions in overview.mdx. Consider adding bidirectional references.
• faq.md mentions "Dive deeper into the topic here" for autonomous worlds with a link to /theory/autonomous-worlds, but this cross-reference should also appear in overview.mdx since it discusses the same concepts.
• installation.mdx references Slot with a GitHub link, while overview.mdx also mentions Slot - these should cross-reference each other for consistency.

Content Relocations

• The AI skills installation instructions appear in both installation.mdx (under "Claude Code Skills") and overview.mdx (under "AI-Assisted Development"). The detailed installation steps should live in installation.mdx only, with overview.mdx providing a brief mention and link to the installation guide.

Heading Inconsistencies

• installation.mdx uses "Installing Dojo" as a main heading, while overview.mdx refers to it as "Installation Guide" in the LinkCard. Consider standardizing to one format.
• brand.mdx uses "Brand Assets" as the title but "Core Dojo Brand" as the first major section, which could be simplified to just "Dojo Brand" for consistency with other section naming patterns.

---

Section: client

Redundancy

None found.

Terminology

• Dojo world: Some files use "Dojo world" while others use "world" when referring to the same concept. Files should consistently refer to "Dojo world" when distinguishing from other types of worlds.
• Session accounts: client/sdk/c/c-bindings.mdx uses "session account" while client/sdk/telegram.md uses "session keys" for the same concept. Prefer "session account" for consistency with other files.

Missing Cross-References

• client/sdk/bevy.md should link to client/sdk/c/index.mdx when discussing "built on the dojo.c foundation"
• client/sdk/unity.md should link to client/sdk/c/index.mdx when discussing the dojo.c foundation
• client/sdk/unrealengine.md should link to client/sdk/c/index.mdx when discussing the dojo.c foundation
• client/sdk/rust.md should link to client/sdk/c/index.mdx when mentioning "built on the same dojo.c foundation"
• client/sdk/telegram.md should link to client/sdk/javascript.md when stating "See the JavaScript SDK docs"
• client/sdk/godot.md should reference client/sdk/c/index.mdx when discussing being "built on the dojo.c foundation"

Content Relocations

None found.

Heading Inconsistencies

• client/sdk/c/c-bindings.mdx uses "C Bindings API" as title while client/sdk/c/wasm-bindings.mdx uses "WASM JavaScript API" - these should follow a consistent pattern like "C Bindings API" and "WASM JavaScript API"
• Several files use different heading patterns for "Getting Started" sections - some have numbered steps, others use bullet points, but this appears to be appropriate given the different complexity levels

---

Section: framework

Looking at these 22 documentation pages from the "framework" section, I've analyzed them for cross-page issues. Here's my structured report:

Redundancy

• System coordination patterns: The system architecture page (framework/systems/architecture.md) and system coordination page (framework/systems/coordination.md) have overlapping content around "Coordination Patterns" and "Producer-Consumer Pattern". The coordination page has the better, more detailed version of these patterns - the architecture page should defer to it for coordination-specific patterns.

• ECS explanation: Both the main index (framework/index.mdx) and models index (framework/models/index.md) explain ECS concepts extensively. The main index has the comprehensive ECS explanation and should be the definitive source - the models page should provide a brief summary and link to the main index.

• Permission configuration: Both the configuration page (framework/configuration/index.md) and world permissions page (framework/world/permissions.md) explain permission configuration in detail. The permissions page has the more comprehensive explanation of the permission system - the configuration page should focus on syntax and defer to the permissions page for conceptual understanding.

Terminology

• Entity ID terminology: Used as "entity ID" in framework/models/entities.md but "entity_id" in framework/models/api.md and "entity identifier" in framework/world/events.md. Prefer "entity ID" for consistency.

• World contract reference: Called "World contract" in most files, but "world contract" (lowercase) in framework/world/events.md and "World" in framework/systems/index.md. Prefer "World contract" (capitalized).

• Resource selector: Used as "resource selector" in most places but "Dojo selector" in framework/upgrading/dojo-1-0.md and "selector" generically elsewhere. Prefer "resource selector" for clarity.

Missing Cross-References

• framework/models/index.md should link to framework/models/entities.md when discussing "For more details on entity composition patterns"
• framework/systems/index.md should link to framework/testing/index.md when mentioning "Systems should be designed for testability"
• framework/world/index.md should link to framework/models/index.md when explaining "Components: Your models"
• framework/configuration/index.md should link to framework/world/metadata.md when mentioning "See more information about world metadata here" and "See more information about resource metadata here"
• framework/models/upgrades.md should link to framework/models/introspection.md when discussing IntrospectPacked vs Introspect trade-offs
• framework/world/permissions.md should link to framework/configuration/index.md in the "Migration and Permissions" section for configuration syntax details

Content Relocations

• The "Testing with dojo-cairo-test" section in framework/upgrading/dojo-1-7.md should be moved to framework/testing/index.md as it contains general testing information that applies beyond just the 1.7 upgrade.

• The "Libraries in Dojo" content in framework/systems/libraries.md would be better placed in framework/systems/index.md as a subsection, since libraries are a core concept for system architecture rather than a standalone advanced topic.

Heading Inconsistencies

• API reference pages use inconsistent heading patterns: framework/models/api.md uses "Core Model Trait" while framework/world/api.md uses "Model Operations" as top-level sections. Both should use consistent patterns like "Core Operations" or "Primary Functions".

• The upgrading section uses inconsistent version formatting: framework/upgrading/dojo-1-0.md uses "Dojo 1.0 Overview" while framework/upgrading/dojo-1-7.md uses "Dojo 1.7 Overview" and framework/upgrading/index.md uses "Dojo 1.x" format. Should standardize on "Dojo X.Y Overview" format.

---

Section: getting-started

Cross-Page Issues Analysis

Redundancy

• Development environment setup: your-first-dojo-app.mdx contains detailed setup instructions for starting Katana, Sozo, and Torii across three terminals. development-workflow.mdx repeats similar content in the "Setting Up Your Development Environment" section with slight variations. The workflow page should reference the first app tutorial for basic setup and focus on advanced development patterns.

• Sozo command examples: Both understanding-the-toolchain.mdx and development-workflow.mdx contain substantial sections showing sozo build, migrate, and execute commands. The toolchain page has the more comprehensive coverage of sozo functionality, while the workflow page should focus on how to use these commands in development cycles.

Terminology

• System vs Actions: your-first-dojo-app.mdx refers to "Systems" in the context of ECS but the actual code files are named "actions.cairo". understanding-the-toolchain.mdx and development-workflow.mdx use both terms inconsistently. Prefer "Systems" when discussing ECS architecture, "actions" when referring to specific contract files.

• Component vs Model: your-first-dojo-app.mdx uses "Components" in ECS context but code shows #[dojo::model]. Other pages consistently use "Models". Prefer "Models" as this is Dojo's specific terminology.

• World contract vs World: Most pages use "World" but your-first-dojo-app.mdx uses "world contract" in one place. Prefer "World" for consistency.

Missing Cross-References

• your-first-dojo-app.mdx should link to understanding-the-toolchain.mdx when mentioning Katana, Sozo, and Torii for the first time, not just at the end.

• understanding-the-toolchain.mdx should link back to your-first-dojo-app.mdx when showing practical examples of the tools in use.

• development-workflow.mdx should link to understanding-the-toolchain.mdx when mentioning specific tool features or configurations.

• next-steps.mdx mentions "FAQ" and "reference documentation" but these links lead outside the getting-started section. Should clarify these are in other parts of the documentation.

• index.mdx mentions installation guide and FAQ - should link to these when first referenced.

Content Relocations

• Tool configuration details: understanding-the-toolchain.mdx contains extensive configuration examples for each tool that would be better placed in the individual tool documentation pages it references. Keep high-level configuration concepts but move detailed config examples.

• Advanced project structure: development-workflow.mdx contains detailed project organization patterns that might be better suited for an advanced development guide rather than the getting-started workflow.

• Testing patterns: The comprehensive testing section in development-workflow.mdx could be moved to a dedicated testing guide, keeping only basic testing workflow in the getting-started section.

Heading Inconsistencies

• Step numbering: your-first-dojo-app.mdx uses "Step 1:", "Step 2:" format, while other pages use various heading patterns. Consider standardizing step-based tutorials.

• Tool sections: understanding-the-toolchain.mdx uses "Tool Name: Description" format for headings, while development-workflow.mdx uses varied heading styles when discussing the same tools.

• Subsection depth: development-workflow.mdx uses inconsistent heading levels (some sections go to h4, others stop at h3) making the page hierarchy unclear.

---

Section: libraries

Redundancy

None found.

Terminology

• Cairo: Both files consistently use "Cairo" with bold formatting when referring to the programming language.
• Starknet: Both files consistently use "Starknet" with bold formatting when referring to the blockchain.
• Dojo: Both files consistently use "Dojo" with bold formatting when referring to the game engine.

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 introduction where it mentions "developers should also consider Alexandria for general Cairo utilities"

Note: Both cross-references already exist and are properly implemented.

Content Relocations

None found.

Heading Inconsistencies

• libraries/alexandria/index.mdx uses "## Alexandria" as the main section heading after the title
• libraries/origami/index.mdx uses "## Origami" as the main section heading after the title

Both follow the same pattern of using the library name as the main heading, so this is consistent.

---

Section: scaling

Redundancy

None found.

Terminology

• sovereign rollups: execution-sharding.md uses "sovereign rollups" in comparison (line mentioning they "do not commit state back to Starknet"), while sovereign-rollups.md uses "sovereign rollups" as the primary term. This is consistent usage.
• shard vs rollup: These are appropriately distinguished as different concepts in both files.

Missing Cross-References

• execution-sharding.md should link to sovereign-rollups.md when discussing the comparison: "Execution sharding differs from sovereign rollups" - this link already exists, so this is properly handled.
• sovereign-rollups.md should link to execution-sharding.md when mentioning "For alternative scaling approaches that maintain stronger connection to mainnet, see execution sharding" - this link already exists, so this is properly handled.

Content Relocations

None found.

Heading Inconsistencies

• execution-sharding.md uses "## Overview" while sovereign-rollups.md uses "## Introduction" for the opening conceptual section. Consider standardizing to either "Overview" or "Introduction" across scaling documentation.
• execution-sharding.md uses "## Planned Architecture" while sovereign-rollups.md uses "## Technical Architecture". Both are appropriate for their contexts (one is planned, one is implemented), so no change needed.

---

Section: toolchain

Looking through these 18 documentation pages from the "toolchain" section, I'll analyze them for cross-page issues. Here's my structured report:

Redundancy

• Installation instructions duplicated: All tool pages (katana/index.md, sozo/index.md, torii/index.md) contain nearly identical installation instructions using dojoup, asdf, and building from source. The katana page has the most complete version with additional notes. Consider consolidating these into a shared installation guide and referencing it from each tool page.

• Data format reference duplicated: sozo/index.md contains a detailed "Data Format Reference" section that overlaps with content that should be in sozo/world-interaction.md where actual command usage is demonstrated. The format reference should either be consolidated into the world interaction page or kept only in the overview with a cross-reference.

Terminology

• "Settlement chain" vs "settlement layer": Used inconsistently across katana/advanced.md and saya/persistent.md. katana/advanced.md uses both terms interchangeably. Prefer "settlement layer" for consistency.

• "Namespace" formatting: Sometimes written as "namespace", sometimes as "namespaces". Consistent throughout most pages but sozo/world-interaction.md uses "namespaces" while others use "namespace". Prefer "namespace".

• "Class hash" vs "classHash": katana/configuration.md uses "class_hash", sozo/binding-generation.md uses "classHash", and torii/grpc.md uses both. Prefer "class hash" for prose, "class_hash" for config files, "classHash" for JSON.

Missing Cross-References

• katana/development.md discusses state forking but should link to katana/advanced.md section on "Optimistic Katana" which builds on forking concepts.

• sozo/binding-generation.md should link to cainome.mdx when it mentions "For the architectural details of binding generation, see the Cainome documentation" - this exists but could be more prominent.

• katana/advanced.md discusses cross-layer messaging but should reference saya/persistent.md and saya/sovereign.md which implement actual settlement mechanisms.

• torii/index.md mentions "multiple API interfaces" but should link directly to torii/graphql.md, torii/grpc.md, and torii/sql.md in the overview.

• katana/configuration.md mentions Starkli integration but should link to katana/advanced.md which has the detailed "Starknet Toolchain Integration" section.

• saya/persistent.md and saya/sovereign.md both reference Katana configuration but should link to katana/configuration.md for the detailed setup information.

Content Relocations

• The "Starknet Toolchain Integration" section in katana/advanced.md (substantial content about Starkli setup and usage) should be moved to katana/development.md since it's more of a development workflow feature than an advanced production feature.

• The "Data Format Reference" section in sozo/index.md (multiple paragraphs about prefixes and examples) should be moved to sozo/world-interaction.md where these formats are actually used in commands.

Heading Inconsistencies

• Configuration guides use inconsistent patterns: katana/configuration.md uses "TOML Configuration" and "Command-Line Options" while torii/configuration.md uses "TOML Configuration" and "CLI Usage". Prefer the katana pattern for consistency.

• Some pages use "Getting Started" (sozo/index.md) while others use "Quick Start" (torii/grpc.md, torii/graphql.md). Prefer "Getting Started" for main sections, "Quick Start" for brief setup sections.

• API reference pages use inconsistent heading depth: torii/graphql.md uses "## Core Features" while torii/grpc.md uses "## Core Concepts". Both could use "## Core Features" for consistency.

---

Section: tutorials

Redundancy

• The "Torii" deployment section in tutorials/deploy-using-slot/main.md substantially duplicates content from tutorials/deploy-to-mainnet/main.md. The latter file has a more comprehensive treatment including advanced configuration, service management, and production considerations. The slot tutorial should retain only a basic Torii section with a reference to the mainnet deployment guide for complete coverage.

Terminology

• "world address": consistently used across all files
• "RPC provider/endpoint": used as "RPC Provider", "RPC endpoint", "RPC provider url", and "rpc_url". Prefer "RPC endpoint" for consistency.
• "development network": used as both "development network" and "devnet". Prefer "devnet" for consistency.

Missing Cross-References

• tutorials/deploy-using-slot/main.md should link to tutorials/deploy-to-mainnet/main.md when discussing Torii deployment (already partially present but could be strengthened)
• tutorials/dojo-starter.mdx should link to tutorials/react.mdx in its "Next Steps" section since it mentions building applications
• tutorials/onchain-chess/README.md should link to tutorials/dojo-starter.mdx when it says "If you have not read the Dojo Book yet"
• tutorials/dojo-react.mdx should link to tutorials/dojo-starter.mdx in its prerequisites section

Content Relocations

• The walnut debugging section (Step 1 and Step 2) in tutorials/deploy-to-mainnet/main.md should be moved to a separate debugging guide or the toolchain section, as it's more of a general debugging tool rather than deployment-specific content.
• The client-side notes section in tutorials/deploy-to-mainnet/main.md should be moved to a client configuration guide, as it's not specific to mainnet deployment.

Heading Inconsistencies

• tutorials/deploy-to-mainnet/main.md uses "### Setup" while tutorials/deploy-using-slot/main.md uses no explicit setup heading
• Debug section headings: tutorials/deploy-to-mainnet/main.md uses "### Debug with Walnut" and "#### Step 1:" format, which is inconsistent with other tutorial heading patterns that tend to use numbered sections like "## 1. Actions"
• tutorials/onchain-chess/ files use inconsistent title formats: "# 0. Setup", "# 1. Actions", "# 2 Move function" (missing period), "# 3 Test Contract"

---

Created automatically by the defrag analysis workflow.