# Get started with Claude Code (/docs/start/claude)

# Get started with Claude Code

Download the Claude Code plugin preview, install it locally and build your first app.

Verified: 16 October 2026

Use Claude Code as your starting point. The Unstoppable Stack plugin brings 19 skills and reference routers into your assistant; the CLI handles app scaffolding.

> Local plugin preview: This download contains skills and references for Claude and Codex. It is a local installation preview, not a public marketplace listing. Native package parsing has been checked; full session activation and end-to-end assistant workflows remain under evaluation.

[Download plugin preview 0.1.2](/downloads/unstoppable-stack-plugins-0.1.2.tar.gz)

[View checksum and content identity](/downloads/plugin-release.json)

1. Check your assistant and install the matching CLI

Start with Claude Code installed and signed in, plus Node.js 22.17 or newer and npm. This plugin requires CLI 0.4.0-beta.1. The matching candidate is not on npm yet; use this pinned source build in a new folder. npm 0.3.0 does not supply the maintained workflow. The commands below use a macOS/Linux shell and a user-writable npm prefix.

```bash
claude --version
claude plugin --help
git clone https://github.com/unstoppable-stack/unstoppable-dev.git unstoppable-cli-source
cd unstoppable-cli-source
git checkout 121cabca1ed2978f98ff1795cc6b87401889be9e
cd packages/cli
npm ci --ignore-scripts
mkdir -p ../../cli-artifacts
npm pack --pack-destination ../../cli-artifacts
npm install --global --prefix "$HOME/.local" ../../cli-artifacts/unstoppable-stack-cli-0.4.0-beta.1.tgz
export PATH="$HOME/.local/bin:$PATH"
cd ~
us --version
```

2. Extract the plugin download

Download the archive above, then run this from your Downloads folder in a macOS or Linux shell. Adjust the folder if your browser saves elsewhere. Keep this terminal open and retain the extracted folder for the local catalog.

```bash
cd ~/Downloads
tar -xzf unstoppable-stack-plugins-0.1.2.tar.gz
PLUGIN_DIR="$(pwd)/unstoppable-stack-plugin"
```

3. Install in Claude Code

Add the extracted catalog and install Unstoppable Stack for your user. This installs guidance; it does not download app dependencies or models.

```bash
claude plugin marketplace add "$PLUGIN_DIR"
claude plugin install unstoppable-stack@unstoppable-stack-dev --scope user
```

4. Start a fresh workspace session

This example creates ~/shop-workspace, then launches Claude there after installation. Choose another directory or name if you prefer, and use a new folder.

```bash
cd ~
mkdir shop-workspace
cd shop-workspace
claude
```

5. Activate the entry skill

Enter this in the Claude chat, then describe your app. The namespaced command should be available in the new session.

```text
/unstoppable-stack:build-with-unstoppable
```

6. Describe the first app

Use a small desktop baseline to check the setup. The assistant should inspect the installed CLI and tell you which generated app folder to run.

```text
Scaffold a Pear Desktop app named shop-starter with local storage and peer networking. Use the installed Unstoppable Stack CLI’s actual catalog, keep storage and networking in the worker, install the app dependencies and tell me which folder to run.
```

## Check the result

Run the generated app from shop-starter, save an entry, close it normally and open it again to confirm persistence. Make one small visible change with your assistant. Local AI can be added after the baseline works; it needs compatible hardware and a model download.

## If the skill does not appear

Confirm both catalog registration and plugin installation completed, then start a fresh session in the intended workspace. Keep the entire extracted folder together. If your project already has CLI-generated guidance, preserve its instructions and inspect overlap before migrating. Use the raw CLI guide while a host installation issue is unresolved.

### Use the raw CLI

Scaffold the same baseline directly from the terminal.

[Read more](/docs/start/cli)

### Packages and integrations

See what is installed, upstream, unpublished or excluded.

[Read more](/docs/packages)

[Claude Code plugin documentation](https://code.claude.com/docs/en/discover-plugins)

---

# Get started with Codex (/docs/start/codex)

# Get started with Codex

Download the Codex plugin preview, install it locally and build your first app.

Verified: 16 October 2026

Use Codex as your starting point. The Unstoppable Stack plugin brings 19 skills and reference routers into your assistant; the CLI handles app scaffolding.

> Local plugin preview: This download contains skills and references for Claude and Codex. It is a local installation preview, not a public marketplace listing. Native package parsing has been checked; full session activation and end-to-end assistant workflows remain under evaluation.

[Download plugin preview 0.1.2](/downloads/unstoppable-stack-plugins-0.1.2.tar.gz)

[View checksum and content identity](/downloads/plugin-release.json)

1. Check your assistant and install the matching CLI

Start with Codex installed and signed in, plus Node.js 22.17 or newer and npm. This plugin requires CLI 0.4.0-beta.1. The matching candidate is not on npm yet; use this pinned source build in a new folder. npm 0.3.0 does not supply the maintained workflow. The commands below use a macOS/Linux shell and a user-writable npm prefix.

```bash
codex --version
codex plugin --help
git clone https://github.com/unstoppable-stack/unstoppable-dev.git unstoppable-cli-source
cd unstoppable-cli-source
git checkout 121cabca1ed2978f98ff1795cc6b87401889be9e
cd packages/cli
npm ci --ignore-scripts
mkdir -p ../../cli-artifacts
npm pack --pack-destination ../../cli-artifacts
npm install --global --prefix "$HOME/.local" ../../cli-artifacts/unstoppable-stack-cli-0.4.0-beta.1.tgz
export PATH="$HOME/.local/bin:$PATH"
cd ~
us --version
```

2. Extract the plugin download

Download the archive above, then run this from your Downloads folder in a macOS or Linux shell. Adjust the folder if your browser saves elsewhere. Keep this terminal open and retain the extracted folder for the local catalog.

```bash
cd ~/Downloads
tar -xzf unstoppable-stack-plugins-0.1.2.tar.gz
PLUGIN_DIR="$(pwd)/unstoppable-stack-plugin"
```

3. Install in Codex

Register the extracted local catalog, then install Unstoppable Stack from it. Registration alone does not activate the plugin. Check codex plugin --help if your version uses a different installation surface.

```bash
codex plugin marketplace add "$PLUGIN_DIR"
codex plugin add unstoppable-stack@unstoppable-stack-dev
```

4. Start a fresh workspace session

This example creates ~/shop-workspace, then launches Codex there after installation. In the Codex desktop app, open that folder and start a new chat instead. Choose a different name if it already exists.

```bash
cd ~
mkdir shop-workspace
cd shop-workspace
codex
```

5. Activate the entry skill

In the new Codex session, select the entry skill by this namespaced name from the available skills. Confirm that it appears before asking it to build.

```text
unstoppable-stack:build-with-unstoppable
```

6. Describe the first app

Use a small desktop baseline to check the setup. The assistant should inspect the installed CLI and tell you which generated app folder to run.

```text
Scaffold a Pear Desktop app named shop-starter with local storage and peer networking. Use the installed Unstoppable Stack CLI’s actual catalog, keep storage and networking in the worker, install the app dependencies and tell me which folder to run.
```

## Check the result

Run the generated app from shop-starter, save an entry, close it normally and open it again to confirm persistence. Make one small visible change with your assistant. Local AI can be added after the baseline works; it needs compatible hardware and a model download.

## If the skill does not appear

Confirm both catalog registration and plugin installation completed, then start a fresh session in the intended workspace. Keep the entire extracted folder together. If your project already has CLI-generated guidance, preserve its instructions and inspect overlap before migrating. Use the raw CLI guide while a host installation issue is unresolved.

### Use the raw CLI

Scaffold the same baseline directly from the terminal.

[Read more](/docs/start/cli)

### Packages and integrations

See what is installed, upstream, unpublished or excluded.

[Read more](/docs/packages)

[Codex plugin documentation](https://developers.openai.com/plugins/build/plugins)

---

# Get started with the raw CLI (/docs/start/cli)

# Get started with the raw CLI

Install the matching CLI and run a local-first desktop app from your terminal.

Verified: 16 October 2026

Use this path for direct control over setup and scaffolding. You can run it without an assistant, or add generated guidance for Claude Code, Codex, Cursor or OpenCode.

1. Check the required tools

Use Node.js 22.17 or newer and npm. The generated desktop project installs its own Electron and Pear runtime dependencies.

```bash
node --version
npm --version
```

2. Install the matching CLI

Use 0.4.0-beta.1 for the maintained workflow. This candidate is not on npm yet. Build the pinned public source in a new folder with a macOS/Linux shell and a user-writable npm prefix; the older published 0.3.0 has a different command surface.

```bash
git clone https://github.com/unstoppable-stack/unstoppable-dev.git unstoppable-cli-source
cd unstoppable-cli-source
git checkout 121cabca1ed2978f98ff1795cc6b87401889be9e
cd packages/cli
npm ci --ignore-scripts
mkdir -p ../../cli-artifacts
npm pack --pack-destination ../../cli-artifacts
npm install --global --prefix "$HOME/.local" ../../cli-artifacts/unstoppable-stack-cli-0.4.0-beta.1.tgz
export PATH="$HOME/.local/bin:$PATH"
cd ~
us --version
```

3. Create a workspace

This creates a workspace, not a runnable app. The command chooses no assistant; use --assistant claude or --assistant codex instead if you want generated project guidance.

```bash
us init shop-workspace --assistant none --no-install
cd shop-workspace
```

4. Scaffold the app

The shop-starter child directory contains a minimal runnable app with peer networking and local Hyperbee storage. It does not include the Local Goods catalog or checkout.

```bash
us scaffold app -p pear-desktop -n shop-starter
```

5. Install and run from the app folder

A desktop window should open. Keep this terminal open while the app is running.

```bash
cd shop-starter
npm install
npm run dev
```

6. Verify persistence

Save an entry, close the app normally and start it again. The entry should remain. Local reads and writes should continue while offline; discovering and syncing with another peer requires connectivity.

> Try the finished ecommerce example: The scaffold above is a minimal starting point. Local Goods adds a searchable catalog, persistent cart, demo checkout and local shopping assistant. Open Examples for its source and run instructions; checkout has no payment or fulfillment integration.

[Explore Local Goods](/showcase)

## If setup fails

If us is not found, check npm prefix -g and ensure its bin directory is on PATH. For runtime problems, run the command below from shop-starter and check the first failed diagnostic. A successful scaffold is separate from a successful app launch.

```bash
us doctor -p pear-desktop
```

### CLI reference

Published commands and the difference from the source candidate.

[Read more](/docs/cli)

### Add local AI

Use QVAC after the desktop baseline works.

[Read more](/docs/local-ai)

### Troubleshooting

Recognize a setup failure and find the next check.

[Read more](/docs/troubleshooting)

### Packages and integrations

One P2P library, upstream SDKs and optional applications.

[Read more](/docs/packages)

---

# Packages and integrations (/docs/packages)

# Packages and integrations

The CLI, one P2P library, assistant plugins and direct upstream SDK integrations.

Verified: 16 October 2026

Start through Claude Code, Codex or the raw CLI. The plugins guide your assistant; the CLI configures workspaces and generates apps. Apps use one Unstoppable P2P library and upstream QVAC or wallet SDKs when needed.

## Packages we maintain

- @unstoppable-stack/cli: workspace setup, scaffolding and environment checks. Version 0.3.0 is published; 0.4.0-beta.1 remains an unpublished source candidate.
- @unstoppable-stack/p2p: identity, pairing, permissions, capability calls and streaming. Replication is the /sync entry of the same package. The consolidated 0.6.0-alpha.1 is unpublished alpha source.
- unstoppable-stack plugins for Claude Code and Codex: two host distributions from shared guidance. Local prototypes exist; public marketplace listings remain pending. Local-install preview downloads are available in the Claude and Codex guides.
- unstoppable-node: optional Personal Node application. Published 0.4.0 has a different API from the reorganized, unpublished 0.6.0-alpha.1 source. It is outside the core preview.

```js
// Proposed alpha imports; publish the P2P package before registry installation.
import { createNode } from '@unstoppable-stack/p2p'
import { syncPack } from '@unstoppable-stack/p2p/sync'
```

## Use upstream SDKs directly

QVAC owns inference. Generated apps use its SDK or inference packages for their runtime, with small private lifecycle helpers for cancellation and shutdown. Personal Node's delegated AI adapter is internal application code. Wallet integration will use WDK directly; current wallet scaffolds are stubs.

## Release boundaries

Memory and Search are excluded from this release. The website, shared agent-pack source and runtime helpers are internal packages. The P2P root does not load replication, but npm installs the storage dependencies with the library. Published releases and unpublished source candidates must use their own version-matched instructions.

### Claude Code — Plugin preview

Add the stack’s workflows to Claude. Describe your app and build with guided P2P, storage and local AI patterns.

[Install Claude plugin](/docs/start/claude)

### Codex — Plugin preview

Give Codex the same stack knowledge. Build, extend and diagnose apps from your chosen workspace.

[Install Codex plugin](/docs/start/codex)

### Raw CLI — Source preview

Work directly in your terminal. Initialize a workspace, scaffold a desktop app and check your environment.

[Install the CLI](/docs/start/cli)

### Choose a setup guide

Install a plugin preview or the published CLI.

[Read more](/getting-started)

### Assistant workflow

Understand how guidance and scaffolding work together.

[Read more](/docs/agent-pack)

### Upgrades

Inspect compatibility differences before migrating an existing app.

[Read more](/docs/upgrades)

---

# Documentation (/docs/)

# Documentation

Task-based guidance for the Unstoppable Stack developer preview.

Verified: 25 September 2026

Unstoppable Stack helps developers create local-first applications with direct peer communication and optional on-device AI. Choose Claude Code, Codex or the raw CLI to build the Pear Desktop baseline. Capabilities outside that baseline carry an explicit maturity label.

### Claude Code — Plugin preview

Add the stack’s workflows to Claude. Describe your app and build with guided P2P, storage and local AI patterns.

[Install Claude plugin](/docs/start/claude)

### Codex — Plugin preview

Give Codex the same stack knowledge. Build, extend and diagnose apps from your chosen workspace.

[Install Codex plugin](/docs/start/codex)

### Raw CLI — Source preview

Work directly in your terminal. Initialize a workspace, scaffold a desktop app and check your environment.

[Install the CLI](/docs/start/cli)

### Packages and integrations

One P2P library, direct upstream SDKs and optional applications.

[Read more](/docs/packages)

### Understand the boundaries

Learn what is local, what needs a reachable peer, and what the project does and does not retain.

[Read more](/docs/support)

### Check compatibility

Use one support table for platforms, features, and combinations instead of relying on promotional copy.

[Read more](/docs/compatibility)

## Preview principles

- Local-first: useful reads and writes should not depend on a central application API.
- Peer availability is optional: show disconnected state and resume cleanly.
- Runtime boundaries matter: renderer UI calls a worker that owns networking, storage, and native AI resources.
- Planned features are not default benefits: wallet payments are not part of the supported preview path.

---

# Choose your starting path (/docs/quickstart)

# Choose your starting path

Install the Claude plugin, the Codex plugin or the raw CLI.

Verified: 16 October 2026

Choose the tool you already use. All three paths lead to the same desktop baseline with local storage and peer networking. Plugin paths include a local preview download; the CLI installs from npm.

### Claude Code — Plugin preview

Add the stack’s workflows to Claude. Describe your app and build with guided P2P, storage and local AI patterns.

[Install Claude plugin](/docs/start/claude)

### Codex — Plugin preview

Give Codex the same stack knowledge. Build, extend and diagnose apps from your chosen workspace.

[Install Codex plugin](/docs/start/codex)

### Raw CLI — Source preview

Work directly in your terminal. Initialize a workspace, scaffold a desktop app and check your environment.

[Install the CLI](/docs/start/cli)

## How the pieces fit

The plugins supply workflows and references. The CLI creates workspaces and apps. The consolidated P2P library owns pairing, permissions and replication; QVAC and wallet features use upstream SDKs directly. The P2P alpha is still unpublished, and wallet scaffolds remain stubs. Memory and Search are excluded from this release.

### Packages and integrations

Purpose, versions and publication status for every layer.

[Read more](/docs/packages)

### Compatibility

Platform and feature maturity before adding capabilities.

[Read more](/docs/compatibility)

---

# Compatibility (/docs/compatibility)

# Compatibility

Current capability maturity and combinations for the developer preview.

Verified: 25 September 2026

This matrix was reviewed 25 September 2026. “Preview” means an implementation and validation path exist; it does not mean production support.

- Pear Desktop scaffold — Preview: Primary documented path; generated with a renderer and worker boundary.
- Local P2P data — Preview: Hyperswarm discovery and local Hyperbee storage are included in base scaffolds.
- Local AI — Being validated: QVAC integration exists; model size, hardware fit, and first-run download vary.
- Personal Node — Deferred alpha: Source exists, but packaging, trust defaults, and replication-status gates exclude it from the core preview.
- Expo Mobile — Deferred: Generated source exists, but native device evidence does not yet support a public claim.
- Wallet payments — Planned: The CLI contains a stub; no production payment path is claimed.

## Known incompatible combination

multi-writer and node-sync cannot be selected together. Multi-writer uses an Autobee writer set, while the current Node registration path handles the single base data core. The CLI rejects the combination instead of generating incomplete protection.

---

# Troubleshooting (/docs/troubleshooting)

# Troubleshooting

Recognizable symptoms, one diagnostic, and one safe recovery action.

Verified: 25 September 2026

### us is not found

Check npm prefix -g, then ensure its bin directory is on PATH or open a new terminal.

### Desktop dependencies are missing

Run npm ls --depth=0 in the generated app, then rerun npm install and address the first meaningful error.

### Install failed

Use the first meaningful npm error to identify network, permission, or native dependency failure; do not start with broad cache deletion.

### Model failed

Check disk space and the first QVAC error. Return to the base scaffold or use a smaller compatible model before retrying.

### Node unavailable

Continue device-only. If Node features are needed, check that it is running, reachable, and has approved the requested capabilities.

---

# Project architecture (/docs/architecture)

# Project architecture

Keep UI, long-lived runtime resources, and optional peers in clear boundaries.

Verified: 25 September 2026

The primary desktop pattern separates the renderer from a worker. This is a runtime requirement, not just code organization.

- Renderer: UI state, user interactions, and narrow bridge calls.
- Worker: Hyperswarm, Corestore, Hyperbee, Hyperdrive, QVAC, and cleanup.
- Bridge: typed messages with timeouts, errors, and visible status.
- Optional Node: a separate peer for replication or delegated inference; local work must survive its absence.

> Shutdown matters: Close swarms, stores, model handles, and worker pipes explicitly. Treat reconnecting and unavailable states as normal.

---

# Assistant workflow (/docs/agent-pack)

# Assistant workflow

How generated project guidance helps an AI coding assistant work inside stack constraints.

Verified: 25 September 2026

Install the Claude or Codex plugin for portable workflows, or use us init for project-local guidance. Both delivery methods share the same maintained agent-pack source. The raw CLI also works without an assistant.

### Claude Code — Plugin preview

Add the stack’s workflows to Claude. Describe your app and build with guided P2P, storage and local AI patterns.

[Install Claude plugin](/docs/start/claude)

### Codex — Plugin preview

Give Codex the same stack knowledge. Build, extend and diagnose apps from your chosen workspace.

[Install Codex plugin](/docs/start/codex)

### Raw CLI — Source preview

Work directly in your terminal. Initialize a workspace, scaffold a desktop app and check your environment.

[Install the CLI](/docs/start/cli)

Plugin installation adds guidance, not the CLI or native dependencies. The entry skill checks the installed CLI catalog before scaffolding. Existing apps keep their recorded runtime and project instructions; updating the plugin does not migrate them.

1. Initialize

Select Claude Code, Cursor, OpenCode, Codex, or none.

```bash
us init my-workspace
```

2. Scaffold first

Create the smallest supported target before asking for feature work.

```bash
us scaffold app -p pear-desktop -n shop-starter
```

3. Request one change

Name the observable result and preserve the worker boundary.

4. Verify

Run the generated project checks and exercise local persistence and disconnect behavior.

---

# Local AI (/docs/local-ai)

# Local AI

Add on-device inference after the base application works.

Verified: 25 September 2026

QVAC-backed inference is optional in the preview. A local model avoids sending prompts to a hosted inference provider, but it still requires compatible hardware, disk space, and an initial model download.

- Keep model initialization in the worker, never the renderer.
- Report download, loading, ready, and error states separately.
- Use mock inference for deterministic UI and protocol tests; label it as mock.
- After a successful model install, test local inference without internet access.
- Do not publish a universal RAM or download-size claim until the chosen model is pinned and measured.

---

# P2P and pairing (/docs/connect)

# P2P and pairing

Peer discovery, invitations, approval, and disconnect behavior.

Verified: 25 September 2026

Hyperswarm provides discovery and encrypted transport. Application trust still needs an explicit identity, invitation, or approval model; discovery alone is not authorization.

- Display searching, approval required, connected, reconnecting, and unavailable states.
- Grant only requested capabilities supported by the peer.
- A desktop Personal Node may require explicit approval; a headless development daemon can be configured differently.
- Remote inference sends the request to the selected trusted device. It is not on-device inference.

---

# Personal Node (/docs/node)

# Personal Node

Deferred alpha architecture for replication and delegated inference.

Verified: 25 September 2026

The Personal Node is not required for a local app and is deferred from the core preview. Its alpha source explores retained replicas, file seeding, and delegated inference, but packaging, trust defaults, and replication-status gates remain open.

- Replication protects observed data; it does not automatically guarantee future writes or a complete backup.
- Settings export does not imply that all replicated application payloads are included.
- Disconnecting pauses Node services but must not erase local data or block local reads and writes.
- Removing or unpairing an app stops replication and revokes access, but already downloaded blocks remain. The alpha has no per-app purge control.

---

# CLI commands (/docs/cli)

# CLI commands

The public command surface and current feature compatibility.

Verified: 25 September 2026

Published CLI 0.3.0 exposes init, scaffold, doctor and node. The source candidate 0.4.0-beta.1 has a narrower minimal release with compatibility checks. Use the reference for your installed version.

```bash
us --version
us --help
us init [project-name] --assistant <claude|codex|cursor|opencode|none>
us scaffold app -p pear-desktop -n <name>
us scaffold list-platforms
us scaffold list-features
us doctor -p pear-desktop
```

## Candidate-only compatibility commands

The unpublished 0.4.0-beta.1 source adds the read-only commands below. They are absent from published 0.3.0. Remote, Research, Search and Memory are not shipped in the minimal release artifact; Personal Node is an optional separate app.

```bash
us compatibility list -o <workspace>
us compatibility check -o <app>
```

## Scaffold facts

- Platforms in source: pear-desktop, expo-mobile, and node-cli. The launch guide defaults to pear-desktop.
- Base Hyperswarm/Corestore networking and Hyperbee storage are always included.
- Feature flags: local-ai, wallet (stub), node-sync, node-host (node-cli only), and multi-writer.
- multi-writer and node-sync are rejected when combined.
- Node CLI is a Node.js command-line target; it is not described as a Bare-only app.

---

# Modules (/docs/modules)

# Modules

The runtime modules used by generated applications.

Verified: 25 September 2026

### Pear and Bare

Application and minimal JavaScript runtimes from Holepunch.

### Hyperswarm

Peer discovery and encrypted connections over the DHT.

### Hypercore and Corestore

Append-only logs and lifecycle management for collections of cores.

### Hyperbee / HyperDB

Local key-value storage and the validated multi-writer collection pattern.

### Hyperdrive

Versioned P2P file storage built on Hypercore.

### QVAC

Optional local model management and inference.

### WDK

Planned wallet integration; not a supported preview capability.

---

# Support and limitations (/docs/support)

# Support and limitations

Data handling, connectivity, exports, logs, and where to ask for help.

Verified: 25 September 2026

This is a developer preview, not a managed application service. Generated apps store and exchange data according to the developer’s code and the peers a user chooses.

## Data paths

- Local storage stays in the generated app’s configured device storage until application code exports, replicates, or deletes it.
- Local inference keeps prompts on the device running the model. Delegated inference sends them to the selected trusted peer.
- P2P sync sends declared data to connected peers; those peers may retain a copy after disconnect.
- A settings export is not necessarily an application-data backup. Inspect what each tool says it includes.
- Coding-assistant data handling is controlled by the assistant and provider the developer selects, not by the generated application runtime.

## Logs and website

The project does not add product analytics in this website source. That statement does not mean the hosting provider keeps no network or request logs. Generated apps may log runtime status and errors; developers should avoid writing prompts, secrets, wallet material, or application records to logs.

## Get help

Use the public GitHub issue tracker linked below. Include the CLI version, platform, exact command, expected result, and first relevant error with private data removed. For a plugin issue, include the assistant version and confirm whether catalog registration, installation or session activation failed.

---

# Upgrades (/docs/upgrades)

# Upgrades

Move between preview releases without hiding compatibility risk.

Verified: 25 September 2026

- Record the current us --version and generated app commit before changing tools.
- Read the release notes for generator, agent-pack, runtime, and storage changes.
- Regenerate into a temporary folder and compare structure instead of overwriting application code blindly.
- Back up irreplaceable local data and test migration on a copy.
- Verify offline reads, writes, reconnect, and shutdown after the upgrade.