feat: add LETTABOT_CONFIG env var for config path (#152)

* docs: add TESTING.md guide

Comprehensive testing documentation covering:
- Unit test setup and patterns
- E2E test setup with Letta Cloud
- MockChannelAdapter usage
- CI/CD workflow
- Best practices

Written by Cameron ◯ Letta Code

* feat: add LETTABOT_CONFIG env var for config path

Addresses Discord feedback from fpl9000 who was confused about where
to put the config file after a global npm install.

Changes:
- Add LETTABOT_CONFIG env var that overrides the config search order
- Update error messages to show the env var option
- Document in docs/configuration.md

Now users doing global installs can either:
- Create ~/.lettabot/config.yaml, or
- Set LETTABOT_CONFIG=/path/to/config.yaml

Written by Cameron ◯ Letta Code

"Configuration should be explicit, not magic." - The Twelve-Factor App

docs/configuration.md

@@ -6,10 +6,15 @@ Complete reference for LettaBot configuration options.
 
 LettaBot checks these locations in order:
 
-1. `./lettabot.yaml` - Project-local (recommended)
-2. `./lettabot.yml` - Project-local alternate
-3. `~/.lettabot/config.yaml` - User global
-4. `~/.lettabot/config.yml` - User global alternate
+1. `LETTABOT_CONFIG` env var - Explicit path override
+2. `./lettabot.yaml` - Project-local (recommended)
+3. `./lettabot.yml` - Project-local alternate
+4. `~/.lettabot/config.yaml` - User global
+5. `~/.lettabot/config.yml` - User global alternate
+
+For global installs (`npm install -g`), either:
+- Create `~/.lettabot/config.yaml`, or
+- Set `export LETTABOT_CONFIG=/path/to/your/config.yaml`
 
 ## Example Configuration
 
@@ -203,6 +208,7 @@ Environment variables override config file values:
 
 | Env Variable | Config Equivalent |
 |--------------|-------------------|
+| `LETTABOT_CONFIG` | Path to config file (overrides search order) |
 | `LETTA_API_KEY` | `server.apiKey` |
 | `LETTA_BASE_URL` | `server.baseUrl` |
 | `LETTA_AGENT_ID` | `agent.id` |

src/cli.ts

@@ -105,12 +105,13 @@ async function server() {
   if (!existsSync(configPath)) {
     console.log(`
 No config file found. Searched locations:
-  1. ./lettabot.yaml (project-local - recommended)
-  2. ./lettabot.yml
-  3. ~/.lettabot/config.yaml (user global)
-  4. ~/.lettabot/config.yml
+  1. LETTABOT_CONFIG env var (not set)
+  2. ./lettabot.yaml (project-local - recommended)
+  3. ./lettabot.yml
+  4. ~/.lettabot/config.yaml (user global)
+  5. ~/.lettabot/config.yml
 
-Run "lettabot onboard" to create a config file.
+Run "lettabot onboard" to create a config, or set LETTABOT_CONFIG=/path/to/config.yaml
 `);
     process.exit(1);
   }

src/config/io.ts

@@ -23,8 +23,20 @@ const DEFAULT_CONFIG_PATH = join(homedir(), '.lettabot', 'config.yaml');
 
 /**
  * Find the config file path (first existing, or default)
+ * 
+ * Priority:
+ * 1. LETTABOT_CONFIG env var (explicit override)
+ * 2. ./lettabot.yaml (project-local)
+ * 3. ./lettabot.yml (project-local alt)
+ * 4. ~/.lettabot/config.yaml (user global)
+ * 5. ~/.lettabot/config.yml (user global alt)
  */
 export function resolveConfigPath(): string {
+  // Environment variable takes priority
+  if (process.env.LETTABOT_CONFIG) {
+    return resolve(process.env.LETTABOT_CONFIG);
+  }
+  
   for (const p of CONFIG_PATHS) {
     if (existsSync(p)) {
       return p;

src/main.ts

@@ -131,12 +131,13 @@ const isContainerDeploy = !!(process.env.RAILWAY_ENVIRONMENT || process.env.REND
 if (!existsSync(configPath) && !isContainerDeploy) {
   console.log(`
 No config file found. Searched locations:
-  1. ./lettabot.yaml (project-local - recommended)
-  2. ./lettabot.yml
-  3. ~/.lettabot/config.yaml (user global)
-  4. ~/.lettabot/config.yml
+  1. LETTABOT_CONFIG env var (not set)
+  2. ./lettabot.yaml (project-local - recommended)
+  3. ./lettabot.yml
+  4. ~/.lettabot/config.yaml (user global)
+  5. ~/.lettabot/config.yml
 
-Run "lettabot onboard" to create a config file.
+Run "lettabot onboard" to create a config, or set LETTABOT_CONFIG=/path/to/config.yaml
 `);
   process.exit(1);
 }