Refresh narrative docs for Pear v2.4+ and module KB links

- Holepunch-For-Dummies: PROGRESS.md, fix README; phase-5/quick-reference use pear dev; cross-links in phases 2/4/8; glossary pointer
- Glossary: index date and platform terms; rewrite Pear commands; README/troubleshooting/api-reference updates
- existing-projects: module map and KB links; keet build defers upstream; pear dev in example
- core-concepts: rewrite pear-runtime concept doc; README §10.2 CLI vs pear-runtime mermaid
- building-tools/architecture: Pear workflow, cmake-android/java, distribution layer, bare-network pointers
- dev-diary/scripts: checklist + test-projects glob typo; fix rocksdb-native canonical link

Made-with: Cursor

Glossary/README.md

@@ -2,6 +2,8 @@
 
 A comprehensive glossary of terms, concepts, and technologies in the Holepunch peer-to-peer ecosystem.
 
+**Per-package documentation:** each mirrored repository has a dedicated article under [`../modules/`](../modules/) (see also [`../scripts/module-inventory.json`](../scripts/module-inventory.json)).
+
 ---
 
 ## Table of Contents
@@ -257,10 +259,14 @@ A minimal, cross-platform JavaScript runtime designed for embedding and P2P appl
 ### Pear
 The flagship application runtime for building and distributing P2P applications. Pear extends Bare with application lifecycle management, IPC, sidecar services, and automatic updates.
 
-**Components:**
+**CLI vs embeddable runtime:** the **`pear`** binary is the developer and operator CLI. The **`pear-runtime`** npm packages split out the embeddable runtime and updater used for OTA-capable apps. The legacy **`pear run`** *CLI* subcommand is **deprecated** from Pear **v2.4+**; prefer **`pear dev`** locally and **`pear-runtime`** when embedding ([Pear KB article](../modules/utilities/pear.md), [changelog](https://github.com/holepunchto/pear/blob/main/CHANGELOG.md)).
-- pear: Main platform (CLI, sidecar, subsystems)
+
+**Components (see `modules/pear/`):**
+- pear: Main platform (CLI, sidecar, subsystems) — [repo module](../modules/utilities/pear.md)
+- pear-runtime / pear-runtime-updater / pear-runtime-legacy-storage — [runtime](../modules/pear/pear-runtime.md), [updater](../modules/pear/pear-runtime-updater.md)
+- bundlebee / bundlebee-cli — [multi-arch bundles](../modules/pear/bundlebee.md)
 - pear-api: Runtime API interface
-- pear-cli: Command-line interface
+- pear-cli: Command-line interface — [pear-cmd](../modules/pear/pear-cmd.md)
 - pear-sidecar: Background service
 - pear-bridge: IPC bridge
 - pear-desktop: Desktop UI runtime

Glossary/api-reference.md

@@ -2,6 +2,10 @@
 
 Quick reference for key APIs and methods in the Holepunch ecosystem.
 
+**Note:** In current `hypercore` releases, most I/O methods return **Promises** (`await core.append(...)`, `await core.get(...)`). Treat snippets below as patterns—verify against the version pinned in your app and the [Hypercore module doc](../modules/hyper/hypercore.md).
+
+**Pear CLI:** see [commands.md](commands.md) and [Pear (KB)](../modules/utilities/pear.md) (`pear dev`, `pear build`, staging, **`pear-runtime`** vs deprecated **`pear run`**).
+
 ---
 
 ## Hypercore API

Glossary/commands.md

@@ -6,49 +6,46 @@ Quick reference for CLI commands in the Holepunch ecosystem.
 
 ## Pear Commands
 
+Commands evolve with the `pear` CLI. This table reflects **Pear v2.4–v2.6** themes from the upstream [CHANGELOG](https://github.com/holepunchto/pear/blob/main/CHANGELOG.md). Run **`pear --help`** and **`pear <cmd> --help`** for the exact surface on your install.
+
 ### Installation
 ```bash
-# Install Pear
+npm install -g pear   # or: npx pear
-npm install -g pear
-
-# Check version
 pear --version
 ```
 
-### Application Management
+### Development
 ```bash
-# Create new app
 pear init my-app
 cd my-app
+pear dev             # local dev / hot reload (preferred)
+# pear run (CLI) — DEPRECATED v2.4+; use pear dev + pear-runtime for embeddable OTA runtimes
+```
 
-# Run app locally
+### Build, stage, seed, release
-pear run
+```bash
+pear build           # v2.5+: multi-architecture deployment folder from build sources
+pear stage           # upload tree to pear drive (configure pear.stage.ignore — v2.4+ defaults changed)
+pear seed            # seed a link; supports --json, stats flags (see changelog)
+pear release         # when your workflow uses it
+pear touch           # v2.5+: links — package.json name no longer defines pear link
+pear multisig      # v2.5–2.6: production signing; uses root pear.json
+pear data            # optional link arg (v2.4+)
+```
 
-# Build for platform
+### Deprecated / historical (do not teach as default)
-pear build ios
+- **`pear run`** (CLI) — deprecated **v2.4+** in favor of **`pear-runtime`** embedding.
-pear build android
+- **`pear package`** / per-platform **`pear build ios|android|...`** — if your template still uses npm scripts, prefer those; the first-party CLI emphasizes **`pear build`** for deployment folders (see changelog **v2.5.0**).
-pear build macos
-pear build linux
-pear build windows
 
-# Package app
+### Other project commands (when installed)
-pear package
+```bash
-
+pear install         # if your pear version exposes it
-# Update Pear
+pear list
+pear uninstall <app-name>
 pear update
 ```
 
-### Project Commands
+**KB deep dives:** [Pear](../modules/utilities/pear.md), [`pear-runtime`](../modules/pear/pear-runtime.md), [`pear-stage`](../modules/pear/pear-stage.md), [`pear-build`](../modules/pear/pear-build.md), [`bundlebee`](../modules/pear/bundlebee.md).
-```bash
-# Install dependencies
-pear install
-
-# List installed apps
-pear list
-
-# Uninstall app
-pear uninstall <app-name>
-```
 
 ---
 

Glossary/index.md

@@ -16,12 +16,20 @@ Comprehensive glossary and reference documentation for the Holepunch/Hypercore e
 ## Quick Links
 
 ### Core Terms
-- **Hypercore**: Append-only log, the foundation of the ecosystem
+- **Hypercore**: Append-only log, the foundation of the ecosystem — [module](../modules/hyper/hypercore.md)
-- **Hyperbee**: Key-value database built on Hypercore
+- **Hyperbee**: Key-value database built on Hypercore — [module](../modules/hyper/hyperbee.md)
-- **Hyperdrive**: Distributed filesystem
+- **Hyperdrive**: Distributed filesystem — [module](../modules/hyper/hyperdrive.md)
-- **Autobase**: Multi-writer data structure
+- **Autobase**: Multi-writer data structure — [module](../modules/utilities/autobase.md)
-- **Hyperswarm**: P2P networking stack
+- **Hyperswarm**: P2P networking stack — [module](../modules/hyper/hyperswarm.md)
-- **HyperDHT**: Distributed Hash Table for peer discovery
+- **HyperDHT**: Distributed Hash Table for peer discovery — [module](../modules/hyper/hyperdht.md)
+
+### Platform (Pear v2.4+)
+- **`pear-runtime`**: Embeddable runtime with P2P OTA updates — [module](../modules/pear/pear-runtime.md)
+- **`pear touch`**: Create or manage pear links (replaces relying on `package.json` name for links)
+- **`pear.stage.ignore`**: Explicit ignore list for `pear stage` (defaults no longer skip `.git` / `.github` / `.DS_Store` / `node_modules/.package-lock.json`)
+- **`bundlebee` / `bundlebee-cli`**: Multi-architecture deployment bundles — [bundlebee](../modules/pear/bundlebee.md), [CLI](../modules/pear/bundlebee-cli.md)
+- **`distributed-drive`**: Shared drive utilities — [module](../modules/storage/distributed-drive.md)
+- **Deprecated CLI `pear run`**: use **`pear dev`** for local development and **`pear-runtime`** when embedding; see [Pear (KB)](../modules/utilities/pear.md)
 
 ### Key Concepts
 - **Append-only log**: Data structure that can only be appended to
@@ -44,7 +52,8 @@ Comprehensive glossary and reference documentation for the Holepunch/Hypercore e
 - [Architecture](../architecture/) - System architecture
 - [Interconnections](../interconnections/) - How components compose
 - [Building Tools](../building-tools/) - Development tools
+- [Module documentation](../modules/) - One article per upstream repository (`holepunchto_repos` mirror)
 
 ---
 
-*Last Updated: 2026-02-19*
+*Last Updated: 2026-04-20*

Glossary/troubleshooting.md

@@ -4,6 +4,26 @@ Common issues and solutions in the Holepunch/Hypercore ecosystem.
 
 ---
 
+## Pear CLI and staging
+
+### `pear stage` uploads huge trees (includes `.git`, lockfiles)
+
+**Cause (Pear v2.4+):** default ignore patterns for **`pear stage`** were removed. `.git`, `.github`, `.DS_Store`, and `node_modules/.package-lock.json` are **no longer** auto-excluded.
+
+**Fix:** add explicit globs under **`pear.stage.ignore`** in your Pear manifest. See [`pear-stage`](../modules/pear/pear-stage.md) and the [Pear changelog](https://github.com/holepunchto/pear/blob/main/CHANGELOG.md) (v2.4.0).
+
+### Confusion between `pear run`, `pear dev`, and `pear-runtime`
+
+- Use **`pear dev`** for normal local development.
+- The **`pear run`** *shell command* is **deprecated** (v2.4+); for shipping an app with P2P OTA updates, integrate **`pear-runtime`** ([module](../modules/pear/pear-runtime.md)).
+- The npm package **`pear-run`** (with a hyphen) is a **separate** Node API for spawning pear apps—do not mix it up with the deprecated CLI subcommand ([`pear-run` doc](../modules/pear/pear-run.md)).
+
+### Broken or wrong pear links after upgrade
+
+From Pear **v2.5+**, **`package.json` `name` does not define** the pear link. Use **`pear touch`** to create or refresh links ([changelog](https://github.com/holepunchto/pear/blob/main/CHANGELOG.md)).
+
+---
+
 ## Connection Issues
 
 ### Can't Find Peers

Holepunch-For-Dummies/PROGRESS.md

@@ -0,0 +1,16 @@
+# Guide progress
+
+Use this file to track which phases you have finished.
+
+| Phase | Topic | Done |
+|-------|-------|------|
+| 1 | [P2P Basics](phase-1-p2p-basics.md) | ☐ |
+| 2 | [Core Concepts](phase-2-core-concepts.md) | ☐ |
+| 3 | [Networking](phase-3-networking.md) | ☐ |
+| 4 | [Data Structures](phase-4-data-structures.md) | ☐ |
+| 5 | [Platform](phase-5-platform.md) | ☐ |
+| 6 | [Real Examples](phase-6-real-examples.md) | ☐ |
+| 7 | [Building](phase-7-building.md) | ☐ |
+| 8 | [Advanced Topics](phase-8-advanced-topics.md) | ☐ |
+
+For deeper technical detail after this guide, see the [main KB](../README.md), [Glossary](../Glossary/README.md), and [module docs](../modules/).

Holepunch-For-Dummies/README.md

@@ -27,8 +27,7 @@ Start here if you're new!
 |------|---------------|
 | [glossary.md](glossary.md) | Plain English terms A-Z |
 | [quick-reference.md](quick-reference.md) | Key commands & patterns |
-| [PROGRESS.md](PROGRESS.md) | What we've covered |
+| [PROGRESS.md](PROGRESS.md) | Checklist of phases you have completed |
-| [PROGRESS.md](PROGRESS.md) | What we've covered |
 
 ---
 

Holepunch-For-Dummies/glossary.md

@@ -1,5 +1,7 @@
 # Glossary: Plain English
 
+> **Expanded glossary and APIs:** see the main KB [Glossary](../Glossary/README.md), [API reference](../Glossary/api-reference.md), and [module documentation](../modules/) (one article per upstream repo).
+
 ## A–Z of Holepunch Terms
 
 ---

Holepunch-For-Dummies/phase-2-core-concepts.md

@@ -238,6 +238,11 @@ Here's how everything we've learned fits together:
 
 ---
 
+## Further reading (KB)
+
+- [Core concepts (technical)](../core-concepts/README.md)
+- [Hypercore](../modules/hyper/hypercore.md), [replication overview](../core-concepts/replication.md)
+
 ## What's Next?
 
 Now that you understand the core concepts:

Holepunch-For-Dummies/phase-4-data-structures.md

@@ -414,6 +414,10 @@ drive.get('/messages').append(message)
 
 ---
 
+## Further reading (KB)
+
+- [Hyperdrive](../modules/hyper/hyperdrive.md), [Hyperbee](../modules/hyper/hyperbee.md), [Autobase](../modules/utilities/autobase.md), [Corestore](../modules/storage/corestore.md)
+
 ## What's Next?
 
 Now you understand the data structures:

Holepunch-For-Dummies/phase-5-platform.md

@@ -156,45 +156,59 @@ This is like the app store, but:
 
 ## Using Pear
 
+> **Pear CLI vs `pear-runtime`:** The `pear` command-line tool handles init, dev, staging, seeding, releases, and more. For **embeddable** runtimes with P2P OTA updates inside your own binary, use the **`pear-runtime`** family of packages. The legacy **`pear run`** *CLI* command is **deprecated** from Pear **v2.4+** ([changelog](https://github.com/holepunchto/pear/blob/main/CHANGELOG.md)). Deep dive: [Pear (KB)](../modules/utilities/pear.md), [`pear-runtime`](../modules/pear/pear-runtime.md).
+
 ### Installing Pear
 
 ```bash
-# Install Pear CLI
+# Install Pear CLI (or use: npx pear)
 npm install -g pear
 
 # Check version
 pear --version
 ```
 
-### Creating an App
+### Creating an app
 
 ```bash
-# Create new project
 pear init my-chat-app
-
 cd my-chat-app
 
-# Run locally during development
+# Development (preferred)
-pear run
+pear dev
 
-# Build for distribution
+# Multi-architecture deployment folder (Pear v2.5+)
 pear build
+
+# Typical release path (see official docs for your template)
+pear stage
+pear seed
+# pear release — when you are ready to publish
 ```
 
-### The Package.json
+Use **`pear touch`** to create or manage **pear links**; **`package.json` `name` is not used** to derive the link (Pear v2.5+). If **`pear stage`** uploads too much (for example `.git` or lockfiles), set explicit patterns under **`pear.stage.ignore`** in your Pear manifest—defaults no longer skip those paths automatically (Pear v2.4+). Details: [`pear-stage`](../modules/pear/pear-stage.md).
+
+### Manifest snippet (`package.json`)
+
+Real apps use a `pear` block (fields vary by template). Treat the following as illustrative only—always start from **`pear init`** and [docs.pears.com](https://docs.pears.com):
 
 ```json
 {
   "name": "my-chat-app",
   "pear": {
-    "id": "my-chat",
-    "version": "1.0.0",
     "title": "My P2P Chat",
     "description": "Chat with friends directly!"
   }
 }
 ```
 
+For **multisig releases**, Pear v2.6+ coordinates signing via **`pear multisig`** and a root **`pear.json`** file. See upstream release notes when you need production signing.
+
+### Further reading (KB)
+
+- [Pear overview](../modules/utilities/pear.md)
+- [`pear-runtime`](../modules/pear/pear-runtime.md), [`pear-build`](../modules/pear/pear-build.md), [`bundlebee`](../modules/pear/bundlebee.md) (multi-arch bundles)
+
 ---
 
 ## Node.js Compatibility

Holepunch-For-Dummies/phase-8-advanced-topics.md

@@ -339,6 +339,10 @@ The tools are in your hands. Go build! 🚀
 
 ---
 
+## Further reading (KB)
+
+- [Architecture](../architecture/README.md), [interconnections](../interconnections/README.md), [building tools](../building-tools/README.md)
+
 ## Continue Your Journey
 
 If you want to revisit or explore other parts of the guide:

Holepunch-For-Dummies/quick-reference.md

@@ -12,13 +12,15 @@ npm install -g pear
 npm install -g hypershell hyperbeam
 ```
 
-### Start a Project
+### Start a Pear project
 ```bash
 pear init my-app
 cd my-app
-pear run
+pear dev
 ```
 
+The **`pear dev`** command runs your app during development (hot reload where supported). The old **`pear run`** *CLI* subcommand is **deprecated** from Pear **v2.4+**; for shipping an embeddable runtime with OTA updates, use the **`pear-runtime`** npm package (see [Pear (KB)](../modules/utilities/pear.md) and [core-concepts/pear-runtime](../core-concepts/pear-runtime.md)). Do not confuse that with the separate **`pear-run`** npm library for spawning child apps from Node.
+
 ---
 
 ## Key Patterns

architecture/README.md

@@ -766,6 +766,7 @@ flowchart TB
 
 ## See Also
 
+- [Module inventory](../scripts/module-inventory.json) - clone-to-doc map for the `holepunchto_repos` mirror
 - [Core Concepts](../core-concepts/) - Detailed concept explanations
 - [Building Tools](../building-tools/) - Build and development tools
 - [Interconnections](../interconnections/) - How components compose

architecture/bare-network-stack.md

@@ -116,6 +116,8 @@ client.on('open', () => {
 
 ## P2P Networking with Hyperswarm
 
+Adjacent ecosystem packages extend discovery and routing (for example **`hyperdht-address`** for address records and **`blind-peer-router`** for blind-peer topologies). See the KB under [`../modules/network/hyperdht-address.md`](../modules/network/hyperdht-address.md) and [`../modules/utilities/blind-peer-router.md`](../modules/utilities/blind-peer-router.md) when you need those specifics.
+
 ### Integration with Bare
 
 ```javascript

architecture/hyper-stack-overview.md

@@ -54,6 +54,10 @@ graph TB
     BARE --> DHT
 ```
 
+## Distribution and platform updates
+
+Pear adds a **distribution layer** on top of this stack: the **`pear`** CLI (`pear dev`, `pear build`, `pear stage`, `pear seed`, …), **embeddable** **`pear-runtime`** packages for OTA-capable apps, and helpers such as **`bundlebee`** for multi-architecture deployment output. These tools do not replace Hypercore replication; they control **how binaries and manifests reach peers**. See [Interconnections](../interconnections/README.md) (section on distribution), [`pear-runtime`](../modules/pear/pear-runtime.md), and [`bundlebee`](../modules/pear/bundlebee.md).
+
 ## Layer-by-Layer Breakdown
 
 ### Layer 1: JavaScript Runtime (Bare)

building-tools/README.md

@@ -56,8 +56,11 @@ The CMake toolchain provides cross-platform building for native dependencies acr
 | `cmake-macos` | macOS | macOS builds |
 | `cmake-windows` | Windows | Windows builds |
 | `cmake-android` | Android | Android builds |
+| `cmake-java` | JVM / JNI | Java-side native integration |
 | `cmake-linux` | Linux | Linux builds |
 
+KB articles: [`cmake-android`](../modules/tooling/cmake-android.md), [`cmake-java`](../modules/tooling/cmake-java.md); other `cmake-*` modules are listed under [`../modules/tooling/`](../modules/tooling/).
+
 ### 1.4 Package Management
 
 | Module | Purpose |
@@ -241,20 +244,28 @@ bare-prebuild --upload
 
 Pear provides the complete application lifecycle from initialization to distribution.
 
-### 3.2 Pear CLI Commands
+### 3.2 Pear CLI commands (Pear v2.4+)
 
 | Command | Purpose | Example |
 |---------|---------|---------|
 | `pear init` | Initialize project | `pear init my-app` |
-| `pear run` | Run application | `pear run` |
+| `pear dev` | Local development / hot reload | `pear dev` |
-| `pear build` | Build application | `pear build` |
+| `pear build` | Multi-architecture deployment folder (v2.5+) | `pear build` |
-| `pear stage` | Stage release | `pear stage` |
+| `pear stage` | Stage files to pear drive (set `pear.stage.ignore`) | `pear stage` |
-| `pear release` | Create release | `pear release` |
+| `pear seed` | Seed a link | `pear seed` |
-| `pear seed` | Seed application | `pear seed` |
+| `pear touch` | Create or refresh pear links | `pear touch` |
+| `pear multisig` | Production signing (`pear.json`) | `pear multisig` |
+| `pear release` | Release step when used in your workflow | `pear release` |
 | `pear inspect` | Debug app | `pear inspect` |
 | `pear doctor` | Diagnostics | `pear doctor` |
 | `pear info` | App information | `pear info` |
 
+**Deprecated:** CLI **`pear run`** (v2.4+) — use **`pear dev`** and embed **`pear-runtime`** for OTA-capable binaries. **KB:** [Pear](../modules/utilities/pear.md), [commands](../Glossary/commands.md), [core-concepts/pear-runtime](../core-concepts/pear-runtime.md).
+
+### 3.2a Distribution bundles
+
+For multi-architecture app folders and related tooling, see **[`bundlebee`](../modules/pear/bundlebee.md)** and **[`bundlebee-cli`](../modules/pear/bundlebee-cli.md)**.
+
 ### 3.3 Pear Build Tools
 
 | Tool | Purpose |
@@ -286,7 +297,7 @@ Pear provides the complete application lifecycle from initialization to distribu
 
 ```mermaid
 flowchart TB
-    INIT["pear init"] --> DEV["pear run dev"]
+    INIT["pear init"] --> DEV["pear dev"]
     DEV --> BUILD["pear build"]
     BUILD --> STAGE["pear stage"]
     STAGE --> RELEASE["pear release"]
@@ -301,20 +312,16 @@ flowchart TB
 pear init my-app --template desktop
 cd my-app
 
-# Development
+# Development (Pear v2.4+: prefer pear dev; CLI pear run is deprecated)
-pear run --dev
+pear dev
 
-# Build for production
+# Build for production (see pear --help for flags valid on your version)
 pear build
 
-# Stage release
+# Stage / seed / release — exact flags depend on template; consult docs.pears.com
-pear stage --channel beta
+pear stage
-
+pear seed
-# Release to production
+pear release
-pear release --channel production
-
-# Seed for distribution
-pear seed --persistent
 ```
 
 ### 3.7 Pear Configuration
@@ -526,7 +533,7 @@ bare-build --platform win32 --arch x64
 ### 10.1 Development Workflow
 
 1. **Initialize**: Use `pear init` with appropriate template
-2. **Develop**: Use `pear run --dev` for hot reload
+2. **Develop**: Use **`pear dev`** for hot reload (CLI **`pear run`** is deprecated v2.4+)
 3. **Test**: Write tests with `brittle`
 4. **Build**: Use `pear build` for production
 5. **Release**: Stage with `pear stage`, release with `pear release`
@@ -558,7 +565,7 @@ pear init my-app
 cd my-app
 
 # Development
-pear run --dev
+pear dev
 
 # Build
 pear build

building-tools/cmake-addon.md

@@ -6,6 +6,8 @@ This guide covers creating native addons for the Bare runtime using CMake.
 
 Bare addons are native libraries (C/C++) that provide performance-critical functionality. The CMake build system automates compilation, linking, and prebuild generation.
 
+**Related KB:** platform-specific toolchains include [`cmake-android`](../modules/tooling/cmake-android.md) and [`cmake-java`](../modules/tooling/cmake-java.md); see [`../modules/tooling/`](../modules/tooling/) for the full `cmake-*` set.
+
 ## Project Structure
 
 ```

core-concepts/README.md

@@ -669,29 +669,27 @@ flowchart TB
 
 **Pear** extends Bare with application lifecycle management.
 
+**CLI vs embeddable packages:** the **`pear`** binary is the **command-line interface** for init, dev, staging, seeding, releases, and more. The **`pear-runtime`**, **`pear-runtime-updater`**, and related **npm** packages are what you **embed** when you need a runtime inside your own shipped binary with P2P OTA-style updates. The legacy **`pear run`** *CLI* subcommand is **deprecated** from Pear **v2.4+**; prefer **`pear dev`** locally and the **`pear-runtime`** family when embedding ([upstream CHANGELOG](https://github.com/holepunchto/pear/blob/main/CHANGELOG.md)). Concept guide: [Pear platform and runtime](pear-runtime.md). Module articles: [`pear-runtime`](../modules/pear/pear-runtime.md), [Pear (KB)](../modules/utilities/pear.md). Composition overview: [Interconnections §0](../interconnections/README.md).
+
 ```mermaid
 flowchart TB
-    subgraph "Pear Platform"
+    subgraph pearPlatform [PearPlatform]
-        APP["Application"]
+        APP[Application]
-        
+        subgraph pearServices [PearServices]
-        subgraph "Pear Services"
+            IPC[IPC_Bridge]
-            IPC["IPC/Bridge"]
+            SIDE[Sidecar]
-            SIDE["Sidecar"]
+            PACK[Bundle_Pack]
-            PACK["Bundle/Pack"]
+            UPD[Updater]
-            UPD["Updater"]
         end
-        
+        subgraph uiLayer [UI]
-        subgraph "UI"
+            DESK[Desktop]
-            DESK["Desktop"]
+            TERM[Terminal]
-            TERM["Terminal"]
+            ELEC[Electron]
-            ELEC["Electron"]
         end
     end
-    
+    subgraph bareRuntime [BareRuntime]
-    subgraph "Bare Runtime"
+        BARE[BareJS]
-        BARE["Bare JS"]
     end
-    
     APP --> IPC
     IPC --> SIDE
     SIDE --> PACK
@@ -733,6 +731,7 @@ flowchart TB
 
 ## See Also
 
+- [Pear platform and runtime (concept)](pear-runtime.md) - CLI vs `pear-runtime` npm, Pear v2.4+ notes
 - [Architecture](../architecture/) - System architecture
 - [Interconnections](../interconnections/) - Component composition
 - [Building Tools](../building-tools/) - Development tools

core-concepts/pear-runtime.md

@@ -1,239 +1,87 @@
-# Pear Runtime
+# Pear platform and runtime (concept)
 
-Pear is Holepunch's comprehensive P2P runtime, development, and deployment platform. It enables building, sharing, and running peer-to-peer applications across desktop, mobile, and terminal platforms. Built on the Bare JavaScript runtime.
+**Last reviewed with upstream:** Pear CLI themes **v2.4–v2.6** ([`pear/CHANGELOG.md`](https://github.com/holepunchto/pear/blob/main/CHANGELOG.md)). Always confirm behavior with **`pear --help`** on your machine and [docs.pears.com](https://docs.pears.com).
 
-## Overview
+Pear is Holepunch’s **distribution and tooling layer** on top of **Bare**: scaffolding apps, staging bytes to pear drives, seeding links, multi-arch **build** output, and (when you embed it) **P2P over-the-air updates**. It is *not* the same thing as the **`pear-runtime`** npm package family—see below.
 
-Pear provides a complete toolkit for P2P application development:
+---
 
-- **Runtime**: Execute P2P applications without traditional servers
+## Two different “runtimes”
-- **Development**: CLI tools for scaffolding, building, and testing
-- **Distribution**: Share applications directly via Hyperswarm
-- **Deployment**: Install and run apps from `pear://` links
 
-## Recent Updates (Feb 2026)
+| Idea | What it is | When to use it |
+|------|------------|----------------|
+| **`pear` CLI** | Developer/operator binary (`pear init`, `pear dev`, `pear stage`, …) | Day-to-day development and releases |
+| **`pear-runtime` (+ updater) npm packages** | Libraries used to **embed** a Pear-capable runtime inside **your** shipped binary, with OTA-style updates | Shipping desktop/mobile/terminal apps that update like Keet-era Pear apps |
 
-- **Externalized HyperDB**: Moved to `pear-hyperdb` for better modularity
+The legacy **`pear run`** *shell subcommand* is **deprecated from Pear v2.4+** in favor of **`pear dev`** for local work and **`pear-runtime`** when you need an embeddable updater stack ([CHANGELOG](https://github.com/holepunchto/pear/blob/main/CHANGELOG.md) v2.4.0).
-- **Removed Channel Support**: Simplified architecture
-- **Seeded Links Fixes**: Improved reliability for deterministic links
-- **Info Race Fixes**: Resolved race conditions in peer discovery
 
-## Installation
+> **Do not confuse** with the npm package **`pear-run`** (hyphenated), which is a **Node API** for spawning a child Pear app and returning an IPC pipe—see [`pear-run`](../modules/pear/pear-run.md).
+
+---
+
+## CLI surface (high level)
+
+**Install:** `npm install -g pear` or `npx pear` (ensure `pear` is on your `PATH`).
+
+**Development**
 
 ```bash
-# Install Pear globally via npx
+pear init my-app
-npx pear
+cd my-app
-
+pear dev          # preferred local dev / hot reload where supported
-# Or install as a dev dependency
-npm install pear --save-dev
 ```
 
-After installation, ensure Pear is in your PATH:
+**Build & release (v2.5+ highlights)**
 
 ```bash
-# Add to PATH (output from npx pear)
+pear build        # multi-architecture deployment folder from build sources
-export PATH="$PATH:$HOME/.pear/bin"
+pear stage        # sync tree into pear drive
+pear seed         # seed a link (see --json / stats flags in changelog)
+pear release      # when your workflow uses it
+pear touch        # create/manage pear links (package.json name no longer defines links — v2.5+)
+pear multisig     # production signing; uses root pear.json (v2.6+)
 ```
 
-## Core Commands
+**Staging ignores (v2.4+):** `.git`, `.github`, `.DS_Store`, and `node_modules/.package-lock.json` are **not** auto-ignored by `pear stage`. Set **`pear.stage.ignore`** in your manifest. Details: [`pear-stage`](../modules/pear/pear-stage.md).
 
-### Development
+---
 
-```bash
+## Application shape
-# Initialize new project
-pear init --template desktop my-app
-pear init --template terminal my-terminal-app
 
-# Start development server with hot reload
+Templates vary. A common layout includes `package.json`, a `pear` configuration block, entry JavaScript, and optional UI folders. Treat any JSON snippet in older KB articles as **illustrative**—generate a fresh app with **`pear init`** and follow upstream templates.
-pear dev
 
-# Run application
+---
-pear run
-```
 
-### Building & Distribution
+## How Pear sits on the Hyper stack
 
-```bash
+Pear apps routinely use the same libraries as any P2P Node/Bare app:
-# Package for current platform
-pear package my-app
 
-# Package for specific platforms
+- **Hyperswarm / HyperDHT** for connectivity
-pear package my-app --win      # Windows
+- **Hypercore / Corestore / Hyperdrive / Hyperbee** for data
-pear package my-app --mac     # macOS  
-pear package my-app --linux   # Linux
 
-# Create installer
+Module deep dives: [`../modules/`](../modules/) (for example [`hyperswarm`](../modules/hyper/hyperswarm.md), [`hypercore`](../modules/hyper/hypercore.md)).
-pear release my-app
-```
 
-### Sharing
+---
 
-```bash
+## Distribution helpers
-# Share application via P2P
-pear share my-app
 
-# Generate installation link
+- **`bundlebee` / `bundlebee-cli`**: multi-architecture bundles — [`bundlebee`](../modules/pear/bundlebee.md)
-pear link my-app
+- **`distributed-drive`**: shared drive utilities — [`distributed-drive`](../modules/storage/distributed-drive.md)
-```
 
-## Application Structure
+See also [Interconnections §0](../interconnections/README.md) for how these compose with the rest of the stack.
 
-A Pear application typically includes:
+---
 
-```
+## Further reading (KB)
-my-app/
-├── index.js           # Main entry point
-├── pear.json         # Application configuration
-├── package.json
-├── renderer/         # UI code (for desktop apps)
-│   ├── index.html
-│   └── index.js
-└── assets/           # Static assets
-```
 
-### pear.json Configuration
+- [Pear overview](../modules/utilities/pear.md)
+- [`pear-runtime`](../modules/pear/pear-runtime.md), [`pear-runtime-updater`](../modules/pear/pear-runtime-updater.md), [`pear-build`](../modules/pear/pear-build.md)
+- [Architecture: stack overview](../architecture/hyper-stack-overview.md)
+- [Glossary: commands](../Glossary/commands.md)
 
-```json
+---
-{
-  "name": "my-app",
-  "version": "1.0.0",
-  "description": "My P2P Application",
-  "main": "index.js",
-  "permissions": {
-    "network": true,
-    "storage": true,
-    "camera": false,
-    "microphone": false
-  },
-  "ui": {
-    "type": "desktop",
-    "width": 800,
-    "height": 600
-  }
-}
-```
 
-## Runtime Architecture
+## Official resources
 
-### Components
+- [docs.pears.com](https://docs.pears.com/)
-
+- [github.com/holepunchto/pear](https://github.com/holepunchto/pear)
-1. **Bare Runtime**: Minimal JS engine for cross-platform execution
-2. **Hyperswarm**: P2P networking and peer discovery
-3. **Hypercore Stack**: Distributed data storage
-4. **Pear Protocol**: Application loading and updates
-
-### Execution Flow
-
-```
-User clicks pear://link
-    |
-    v
-Pear runtime resolves link
-    |
-    v
-Downloads app metadata from DHT
-    |
-    v
-Connects to seed peers
-    |
-    v
-Fetches application code
-    |
-    v
-Executes in sandboxed environment
-```
-
-## Pear Links
-
-Pear uses custom URL scheme for application links:
-
-```bash
-# Standard link format
-pear://<public-key>/<app-name>
-
-# Seeded deterministic links
-pear://<seed>/<app-name>
-```
-
-### Link Resolution
-
-1. Parse public key from link
-2. Query DHT for application metadata
-3. Connect to available peers
-4. Download and verify application
-5. Execute in Pear runtime
-
-## Integration with Hypercore Stack
-
-Pear applications have access to the full Holepunch ecosystem:
-
-```javascript
-const hyperswarm = require('hyperswarm')
-const hypercore = require('hypercore')
-const hyperdrive = require('hyperdrive')
-const hyperbee = require('hyperbee')
-
-// Create P2P connections
-const swarm = hyperswarm()
-
-// Store distributed data
-const feed = hypercore(corestore)
-
-// File system
-const drive = hyperdrive(corestore)
-
-// Database
-const db = hyperbee(corestore)
-```
-
-## Desktop Applications
-
-Pear Desktop provides Electron-based runtime:
-
-```bash
-# Create desktop app
-pear init --template desktop chat-app
-cd chat-app
-pear dev
-```
-
-Features:
-- Native window management
-- System tray integration
-- Desktop notifications
-- File system access
-- Hardware acceleration
-
-## Terminal Applications
-
-Lightweight CLI applications:
-
-```bash
-# Create terminal app
-pear init --template terminal my-tool
-cd my-tool
-pear dev
-```
-
-## Mobile Support
-
-Pear supports mobile via Bare Kit:
-
-- **iOS**: React Native integration
-- **Android**: Native bindings in progress
-
-## Documentation & Resources
-
-- [Official Docs](https://docs.pears.com/)
-- [Getting Started Guide](https://docs.pears.com/guides/getting-started)
-- [API Reference](https://docs.pears.com/reference)
-- [Templates](https://docs.pears.com/templates)
-- [Building Blocks](https://docs.pears.com/building-blocks/)
-
-## Related Projects
-
-- [pear-cli](https://github.com/holepunchto/pear) - CLI tool
-- [pear-electron](https://github.com/holepunchto/pear-electron) - Electron integration
-- [pear-updater](https://github.com/holepunchto/pear-updater) - P2P updates
-- [Bare Runtime](/architecture/bare-runtime) - JS runtime
-- [Pear Desktop](/existing-projects/pear-desktop) - Desktop shell

dev-diary.md

@@ -22,5 +22,6 @@ After pulling upstream mirrors (about monthly):
 3. `node scripts/sync-title-semver.mjs` — refreshes `vsemver` in the first line of docs under `storage/`, `native/`, `utilities/`, and `tooling/` when it diverges from `package.json`.
 4. Re-read **Tier A** changelogs (`hypercore`, `hyperdrive`, `autobase`, `hyperswarm`, `hyperdht`, `corestore`, `protomux`, …) for API or security notes.
 5. **Pear**: diff `holepunchto_repos/pear/CHANGELOG.md` against `modules/utilities/pear.md` and `modules/pear/` for CLI vs `pear-runtime` wording.
-6. `test-projects/`*: run `npm install`, commit lockfiles; keep `node_modules` untracked (root `.gitignore`).
+6. `test-projects/*`: run `npm install`, commit lockfiles; keep `node_modules` untracked (root `.gitignore`).
+7. When Pear CLI has a semver **minor** release, skim **Holepunch-For-Dummies**, **Glossary/commands**, **building-tools/README**, **core-concepts/pear-runtime**, and **existing-projects** for deprecated-command wording (`pear run`, staging defaults, link generation).
 

existing-projects/README.md

@@ -15,6 +15,14 @@ These are the officially featured applications from the Holepunch showcase:
 
 The Holepunch ecosystem powers production applications ranging from messaging and file sharing to password management and remote access. These projects demonstrate the practical application of P2P technologies.
 
+### KB module map (selected)
+
+| Area | Module articles |
+|------|-----------------|
+| Data | [Hypercore](../modules/hyper/hypercore.md), [Hyperbee](../modules/hyper/hyperbee.md), [Hyperdrive](../modules/hyper/hyperdrive.md), [Autobase](../modules/utilities/autobase.md) |
+| Network | [Hyperswarm](../modules/hyper/hyperswarm.md), [HyperDHT](../modules/hyper/hyperdht.md), [Protomux](../modules/protomux/protomux.md) |
+| Platform | [Pear](../modules/utilities/pear.md), [`pear-runtime`](../modules/pear/pear-runtime.md), [Corestore](../modules/storage/corestore.md) |
+
 ```mermaid
 flowchart TB
     subgraph "Production Applications"
@@ -567,9 +575,9 @@ cd filesharing-app-example
 # Install dependencies
 npm install
 
-# Run
+# Run (see upstream README — Pear v2.4+ deprecates CLI `pear run`; prefer `pear dev` or project npm scripts)
 cd app
-pear run
+pear dev
 ```
 
 ### 11.2 Build from Source
@@ -619,6 +627,7 @@ npm run dev
 
 ## See Also
 
+- [Module documentation](../modules/) - Per-repo KB articles
 - [Architecture](../architecture/) - System architecture
 - [Core Concepts](../core-concepts/) - Key concepts
 - [Building Tools](../building-tools/) - Development tools

existing-projects/autopass.md

@@ -11,6 +11,10 @@ Autopass provides:
 - **Secure sharing** - Share credentials with trusted contacts
 - **Mobile apps** - iOS and Android support
 
+**Branding:** the product is also marketed as **PearPass** ([pass.pears.com](https://pass.pears.com)); **Autopass** is the upstream project name.
+
+**KB modules:** [Hyperdrive](../modules/hyper/hyperdrive.md), [Hyperswarm](../modules/hyper/hyperswarm.md), [Hyperbee](../modules/hyper/hyperbee.md).
+
 ## Technology Stack
 
 | Layer | Technology |

existing-projects/gitea.md

@@ -6,6 +6,8 @@ Gitea Integration: https://github.com/holepunchto/gitea-skill
 
 The Gitea integration enables running a complete Git hosting platform over Hyperswarm, allowing P2P git repositories with web interface, SSH access, and collaborative features - all without centralized infrastructure.
 
+**KB modules:** [Hyperswarm](../modules/hyper/hyperswarm.md); see also [git-remote-punch-transport](../modules/utilities/git-remote-punch-transport.md) if documented.
+
 ## Architecture
 
 The integration consists of several components:

existing-projects/hyperbeam.md

@@ -11,6 +11,8 @@ Hyperbeam provides:
 - **Resume support** - Continue interrupted transfers
 - **Large files** - No size limits
 
+**KB modules:** [Hyperswarm](../modules/hyper/hyperswarm.md), [HyperDHT](../modules/hyper/hyperdht.md).
+
 ## Architecture
 
 ```mermaid

existing-projects/hyperdb.md

@@ -10,6 +10,8 @@ HyperDB provides:
 - **CRDT-like** behavior
 - **Nested** hierarchies
 
+**KB modules:** [HyperDB](../modules/hyper/hyperdb.md), [Hyperbee](../modules/hyper/hyperbee.md), [Hypercore](../modules/hyper/hypercore.md).
+
 ## Status
 
 > **Note**: HyperDB has been largely superseded by **Hyperbee** for new projects. Hyperbee offers better performance, simpler API, and active development.

existing-projects/hypershell.md

@@ -12,6 +12,8 @@ Hypershell enables:
 - **File transfer** capabilities
 - **Port forwarding** tunnels
 
+**KB modules:** [Hyperswarm](../modules/hyper/hyperswarm.md), [HyperDHT](../modules/hyper/hyperdht.md), [Protomux](../modules/protomux/protomux.md).
+
 ## Architecture
 
 ```mermaid

existing-projects/hyperssh.md

@@ -10,6 +10,8 @@ Hyperssh provides:
 - **Proxy command** - Drop-in SSH replacement
 - **Remote forwarding** - Tunnel support
 
+**KB modules:** [Hyperswarm](../modules/hyper/hyperswarm.md), [HyperDHT](../modules/hyper/hyperdht.md).
+
 ## Architecture
 
 ```mermaid

existing-projects/keet.md

@@ -160,20 +160,18 @@ Keet uses:
 
 ### Building
 
+Keet’s mobile and desktop pipelines live in **`keet-appling`** and related repos; commands change with Pear releases. Always follow the **README** in [github.com/holepunchto/keet-appling](https://github.com/holepunchto/keet-appling) and [docs.pears.com](https://docs.pears.com).
+
 ```bash
-# Clone repo
 git clone https://github.com/holepunchto/keet-appling
-
+cd keet-appling
-# Install dependencies
 npm install
-
+# Typical local dev today uses `pear dev` (Pear CLI v2.4+ deprecates `pear run`).
-# Run on iOS
+# iOS/Android simulators/devices: use the npm/yarn scripts documented upstream, not hard-coded `pear run ios|android`.
-pear run ios
-
-# Run on Android
-pear run android
 ```
 
+**KB:** [Pear](../modules/utilities/pear.md), [`pear-runtime`](../modules/pear/pear-runtime.md).
+
 ## Privacy & Security
 
 ### Encryption Layers

existing-projects/libudx.md

@@ -11,6 +11,8 @@ libudx provides:
 - **Multiplexing** - Multiple streams per socket
 - **Zero-copy** - Minimal memory copies
 
+**KB modules:** [udx-native](../modules/native/udx-native.md) (JS bindings), [libudx](../modules/lib/libudx.md).
+
 ## Architecture
 
 ```mermaid

existing-projects/lightning.md

@@ -10,6 +10,8 @@ Lightning provides:
 - **Privacy** - Payment channels
 - **Micropayments** - Enable new business models
 
+**KB modules:** [Lightning](../modules/utilities/lightning.md), [grpc-lnd](../modules/protocol/grpc-lnd.md), [simple-lnd](../modules/utilities/simple-lnd.md).
+
 ## Architecture
 
 ```mermaid

existing-projects/pear-desktop.md

@@ -6,6 +6,8 @@ pear-desktop repo: https://github.com/holepunchto/pear-desktop
 
 Pear Desktop is an Electron-based shell application that provides the desktop runtime environment for Pear applications. It enables P2P applications to run natively on Windows, macOS, and Linux with full system integration.
 
+**KB modules:** [Pear](../modules/utilities/pear.md), [`pear-desktop`](../modules/pear/pear-desktop.md), [`pear-electron`](../modules/pear/pear-electron.md), [`pear-runtime`](../modules/pear/pear-runtime.md).
+
 ## Architecture
 
 Pear Desktop serves as the "container" for Pear applications, providing:

existing-projects/planb-school.md

@@ -6,6 +6,8 @@ planb-summer-school repo: https://github.com/holepunchto/planb-summer-school
 
 PlanB Summer School was an intensive two-week program held in Lugano, Switzerland (July 2-15, 2023) focused on Bitcoin and Peer-to-Peer technologies. The Holepunch team contributed the **Pear Track** - a technical track teaching developers how to build P2P applications using the Hypercore ecosystem.
 
+**KB:** [Hyperswarm](../modules/hyper/hyperswarm.md), [Hypercore](../modules/hyper/hypercore.md), [Pear](../modules/utilities/pear.md).
+
 ## Workshop Content
 
 The Pear Track covered three days of progressively advanced P2P development:

modules/native/rocksdb-native.md

@@ -1,6 +1,6 @@
 # rocksdb-native - RocksDB Bindings for JavaScript
 
-**Canonical KB article** for the `[holepunchto/rocksdb-native](https://github.com/holepunchto/rocksdb-native)` package. (A legacy duplicate stub under `modules/storage/rocksdb.md` was removed; use this file.)
+**Canonical KB article** for the [holepunchto/rocksdb-native](https://github.com/holepunchto/rocksdb-native) package. (A legacy duplicate stub under `modules/storage/rocksdb.md` was removed; use this file.)
 
 ## Overview
 

scripts/README.md

@@ -13,4 +13,4 @@
 1. Pull latest `holepunchto_repos` mirrors.
 2. Run `node scripts/build-module-inventory.mjs` and fix any `undocumentedClones`.
 3. Run `node scripts/sync-title-semver.mjs`; refresh Tier A/B module pages after semver majors.
-4. Re-run `npm install` (or `npm ci`) in each `test-projects/`* sample and commit lockfile updates.
+4. Re-run `npm install` (or `npm ci`) in each `test-projects/*` sample and commit lockfile updates.