From 211c3839483c8bbb7ede1a030ceb43e0f0874576 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Thu, 16 Jul 2026 08:30:39 +0000
Subject: [PATCH] Update Quick Start instructions to use setup.sh and clarify
 .env location

Updated the README.md to use `./setup.sh` instead of `npm ci` for the Quick Start command, preventing onboarding friction due to missing system dependencies. Also clarified the location of the `.env` file to prevent startup crashes. Logged these changes in the Showcase journal.
---
 .jules/showcase.md |  1 +
 README.md          | 10 +++++-----
 2 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/.jules/showcase.md b/.jules/showcase.md
index cd4d6d35..4338c145 100644
--- a/.jules/showcase.md
+++ b/.jules/showcase.md
@@ -4,6 +4,7 @@
 - **[2024-05-22]** Initial audit revealed `README.md` was functional but lacked "Curb Appeal". It missed critical link arrays, visual hooks, and a clear documentation map. Refactoring to follow the "Golden Template".
 - **[2024-05-24]** Standardized "Quick Start" on `npm ci` rather than `npm install` for the TS monorepo. This prevents unintended local `package-lock.json` mutations, reducing onboarding friction and unexpected local state issues.
 - **[2026-04-09]** Added `DISCORD_APPLICATION_ID` to Quick Start instructions. Users were encountering a startup crash when trying to run the bot with just `BOT_TOKEN` due to missing required application ID context, causing immediate abandonment.
+- **[2026-04-10]** Updated Quick Start to use `./setup.sh` instead of `npm ci` because users were missing system dependencies (`ffmpeg`, `libnacl-dev`). Also clarified that the `.env` file must be placed in `packages/bot/.env`, not the monorepo root, to prevent startup crashes when running the bot locally via npm workspaces.
 
 ## Showcase's Philosophy
 - The README is not documentation; it is a Landing Page.
diff --git a/README.md b/README.md
index 36dba630..e27c9fdf 100644
--- a/README.md
+++ b/README.md
@@ -31,16 +31,16 @@ Get up and running in less than 5 minutes.
     ```
 
 2.  **Install Dependencies**
-    This project uses `npm` workspaces.
+    This project uses `npm` workspaces and requires system dependencies.
     ```bash
-    npm ci
+    ./setup.sh
     ```
 
 3.  **Configure Environment**
-    Create a `.env` file in the `packages/bot` directory (or the root directory):
+    Create a `.env` file in the `packages/bot` directory (it MUST be placed here, not the monorepo root, for `dotenv` to work):
     ```bash
-    echo "BOT_TOKEN=your_token_here" > .env
-    echo "DISCORD_APPLICATION_ID=your_app_id" >> .env
+    echo "BOT_TOKEN=your_token_here" > packages/bot/.env
+    echo "DISCORD_APPLICATION_ID=your_app_id" >> packages/bot/.env
     ```
 
 4.  **Run the Bot**