From 320c1cd6a06af1be81d38b73f9858bfa00bdbc98 Mon Sep 17 00:00:00 2001
From: Cameron <cameron@pfiffer.org>
Date: Tue, 10 Feb 2026 13:25:42 -0800
Subject: [PATCH] docs: add npm run update script and recommend npm ci (#259)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Users running npm install get a dirty lockfile that blocks git pull.
Add an update script that handles the reset+pull+install+build cycle,
and document npm ci as the recommended install method.

Written by Cameron ◯ Letta Code

"Simplicity is the ultimate sophistication." -- Leonardo da Vinci
---
 docs/getting-started.md | 14 +++++++++++++-
 package.json            |  1 +
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/docs/getting-started.md b/docs/getting-started.md
index 24d367e..d60423f 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -16,9 +16,11 @@ Get LettaBot running in 5 minutes.
 ```bash
 git clone https://github.com/letta-ai/lettabot.git
 cd lettabot
-npm install
+npm ci
 ```
 
+> **Note:** Always use `npm ci` (not `npm install`) to avoid modifying the lockfile, which would block future `git pull` updates.
+
 ### 2. Create a Telegram Bot
 
 1. Open Telegram and message [@BotFather](https://t.me/BotFather)
@@ -95,6 +97,16 @@ To limit who can use your bot, set `ALLOWED_USERS`:
 ALLOWED_USERS=123456789,987654321
 ```
 
+## Updating
+
+Pull the latest changes and rebuild:
+
+```bash
+npm run update
+```
+
+This resets the lockfile, pulls from git, installs dependencies, and rebuilds. If you've modified source files locally, stash them first with `git stash`.
+
 ## Next Steps
 
 - [Commands Reference](./commands.md) - Learn all bot commands
diff --git a/package.json b/package.json
index 4cb17e9..2ec6d66 100644
--- a/package.json
+++ b/package.json
@@ -26,6 +26,7 @@
     "skills:status": "tsx src/cli.ts skills status",
     "cron": "tsx src/cron/cli.ts",
     "pairing": "tsx src/cli.ts pairing",
+    "update": "git checkout -- package-lock.json && git pull && npm ci && npm run build",
     "skill:install": "npx clawdhub install --dir ~/.letta/skills",
     "skill:search": "npx clawdhub search",
     "skill:list": "npx clawdhub list --dir ~/.letta/skills",