WIP

DOCUMENTATION_GAP_ANALYSIS.md

@@ -0,0 +1,78 @@
+# Documentation Gap Analysis
+
+## Summary Comparison
+
+### ✅ Already Well Covered
+1. **Four-layer architecture** - Covered in `intro/index.md` and `core-concepts/architecture.md`
+2. **Transaction flow** - Detailed sequence diagram in `architecture.md`
+3. **Dual sync strategy** - Explained in `architecture.md` and `nodes.md`
+4. **DAG causal ordering** - Visualized in `architecture.md`
+5. **Node types** - Coordinator/peer explained in `nodes.md`
+6. **Performance characteristics** - Listed in `intro/index.md`
+7. **Component map** - Table in `architecture.md`
+8. **Applications overview** - Comprehensive in `applications.md`
+9. **CRDT collections** - Detailed in `applications.md`
+10. **Where to start** - Table in `intro/index.md`
+
+### ❌ Missing or Incomplete
+
+#### Critical Gaps (Stub Pages)
+1. **`core-concepts/contexts.md`** - Currently just a stub with TODOs
+2. **`core-concepts/identity.md`** - Stub with TODOs
+3. **`core-concepts/index.md`** - Placeholder content
+4. **`getting-started/index.md`** - Placeholder content
+
+#### Missing Information
+1. **Use Cases** - No mention of collaborative editing, decentralized social, P2P gaming, IoT, supply chain, healthcare
+2. **Detailed Component Breakdown** - Runtime, SDK, storage, DAG explanations could be more detailed with "what it does" and "why it matters"
+3. **Project Structure** - The detailed `core/` directory structure with explanations of what each crate does
+4. **What Makes It Unique** - The bullet points exist but could be more prominent and detailed
+5. **Core Principles** - Mentioned but not emphasized enough
+6. **Key Components Deep Dive** - Each major crate needs a "what/why/how" explanation
+
+#### Structural Issues
+1. **Intro page** - Good but could better emphasize unique value props
+2. **Architecture page** - Component map is good but could add "responsibility" column
+3. **No "Core Repository Overview"** - Missing a dedicated page explaining the core repo structure
+
+## Proposed Improvements
+
+### 1. Enhance `intro/index.md`
+- Add prominent "Use Cases" section
+- Expand "What Makes Calimero Unique" with more detail
+- Add "Core Repository Structure" subsection
+- Make "Core Principles" more prominent
+
+### 2. Fill `core-concepts/contexts.md`
+- Explain context isolation model
+- Describe lifecycle (create, invite, join, revoke)
+- Add diagram showing shared state vs private storage
+- Link to merobox workflows
+
+### 3. Fill `core-concepts/identity.md`
+- Explain root vs client keys
+- Describe wallet adapters
+- Cover authentication flows per chain
+- Link to contracts repo
+
+### 4. Enhance `core-concepts/architecture.md`
+- Add "Key Components Deep Dive" section with detailed explanations
+- Expand component map with "Responsibility" column
+- Add "Project Structure" section explaining core/ directory
+
+### 5. Create `core-concepts/core-repository.md` (NEW)
+- Detailed breakdown of core/ directory structure
+- Explanation of each major crate (what/why/how)
+- Component relationships diagram
+- Links to individual crate READMEs
+
+### 6. Fill `core-concepts/index.md`
+- Replace placeholder with actual overview
+- Brief summaries of each concept
+- Navigation guidance
+
+### 7. Fill `getting-started/index.md`
+- Replace placeholder with actual content
+- Clear progression path
+- Links to each getting started page
+

docs/app-directory/index.md

@@ -14,3 +14,12 @@ To get started:
 3. Run it within your Calimero environment to test and customize.
 
 More detailed guides and configuration examples will be added here soon.
+
+## Featured Projects
+
+- `Battleships` — Turn-based multiplayer with private boards and Merobox workflows. [Repo README](https://github.com/calimero-network/battleships#readme)
+- `Shared Todo Backlog` — Collaborative backlog with CRDT sync patterns. [Repo README](https://github.com/calimero-network/shared-todo-backlog#readme)
+- `Split Bills` — Expense sharing with delegation flows and settlement patterns. [Repo README](https://github.com/calimero-network/split-bills#readme)
+- `KV Store` — Minimal read/write example ideal for first integrations. [Repo README](https://github.com/calimero-network/kv-store#readme)
+- `Demo Blob App` — File-style payload handling plus frontend wiring. [Repo README](https://github.com/calimero-network/demo-blob-app#readme)
+- `Calimero Curb Chat` — Rich messaging UI with cross-device workflows. [Repo README](https://github.com/calimero-network/calimero-curb-chat#readme)

docs/builder-directory/index.md

@@ -14,11 +14,11 @@ Before we dive in, here are the tools we'll be using:
 
 - **`mero-devtools-js`** - JavaScript wrappers for Calimero tooling to keep your development workflow simple and consistent. [Source code](https://github.com/calimero-network/mero-devtools-js)
 
-- **`calimero-abi-generator `** - Generates TypeScript clients from your Rust backend, keeping frontend/backend in sync.
+- **`@calimero-network/abi-codegen`** - Generates TypeScript clients from your Rust backend, keeping frontend/backend in sync.
 
 Don't worry about installing these individually - the setup process will handle it.
 
-## Two Paths to Get Started
+## Choose Your Starting Point
 
 Choose your adventure:
 
@@ -60,6 +60,19 @@ After setup, follow the README instructions to build and run the app.
 
 ---
 
+## Minimal Dev Loop
+
+1. `pnpm install` — fetch dependencies for root and generated subdirectories.
+2. `pnpm logic:build` — compile the Rust WASM and regenerate ABI clients.
+3. `pnpm network:bootstrap` — start Merobox, deploy the WASM, capture the **Application ID**.
+4. Update your frontend config with the Application ID and context ID.
+5. `pnpm dev` — run React/Vite with hot reload alongside `logic:watch`.
+6. Open two browser tabs, join the context, and iterate on gameplay or flows.
+
+Keep this loop handy; the walkthrough below explains each step in detail and shows where the commands live.
+
+---
+
 ## The AI-Assisted Path (Walkthrough)
 
 This walkthrough uses **Cursor** (an AI-powered IDE) to build a complete Calimero application. We'll use the [Battleships game](https://github.com/calimero-network/battleships) as our example to show you exactly what happens at each step.
@@ -536,7 +549,7 @@ After the Rust code is written, the AI runs:
 
 ```bash
 cargo build --target wasm32-unknown-unknown --release
-calimero-abi-generator --input logic/res/abi.json --output app/src/api/AbiClient.ts
+npx calimero-abi-codegen -i logic/res/abi.json -o app/src/api/AbiClient.ts
 ```
 
 **What this generates:**
@@ -831,7 +844,7 @@ This is why the first step after `pnpm network:bootstrap` is always to grab the
     "logic:build": "cd logic && cargo build --target wasm32-unknown-unknown --release",
     "logic:watch": "watchexec -w logic/src 'pnpm logic:build && pnpm logic:sync'",
     "logic:sync": "cp logic/target/wasm32-unknown-unknown/release/*.wasm workflows/",
-    "app:generate-client": "calimero-abi-generator --input logic/res/abi.json --output app/src/api/",
+    "app:generate-client": "calimero-abi-codegen -i logic/res/abi.json -o app/src/api/",
     "app:dev": "cd app && pnpm dev",
     "network:bootstrap": "merobox --workflow workflows/local-network.yml",
     "dev": "concurrently 'pnpm logic:watch' 'pnpm app:dev'"
@@ -958,6 +971,9 @@ By following this walkthrough (or just reading it), you now understand:
 
 ### Want to Go Deeper?
 
+- **[SDK Guide](sdk-guide.md)** - Complete guide to building with the Calimero Rust SDK
+- **[JavaScript SDK Guide](js-sdk-guide.md)** - Build Calimero services using TypeScript/JavaScript
+- **[Core Apps Examples](../examples/core-apps-examples.md)** - Reference implementations in `core/apps`
 - **[Introduction](../intro/index.md)** - Understand Calimero's core concepts and architecture
 - **[Privacy, Verifiability & Security](../privacy-verifiability-security/index.md)** - Learn about private contexts and data flow
 - **[App Directory](../app-directory/index.md)** - Discover what's already built on Calimero