Merge pull request #252 from pipecat-ai/jpt/phonellm-readme-step-order

Author: markbackman

phonellm/.claude/skills/setup/SKILL.md

@@ -32,10 +32,35 @@ must log in themselves — it's a browser flow. Ask them to run:
 
 There is no `modal login`; `modal setup` is the auth command.
 
-## 3. PhoneLLM endpoint
+## 3. Proxy token
+
+The bot authenticates with a workspace proxy token rather than local Modal credentials,
+and this has to come **before** creating the endpoint: an authenticated endpoint requires
+a proxy token to already exist in the workspace, so `modal endpoint create` fails without
+one.
+
+If `MODAL_API_KEY` is already in `server/.env`, keep it. Otherwise create one:
+
+```bash
+modal workspace proxy-tokens create --json
+```
+
+Combine as `<token-id>.<token-secret>` (`wk-....ws-...`) and write it to `server/.env`
+without echoing the secret (create that file with `cp server/.env.example server/.env`
+first if it doesn't exist yet). The secret is shown once and cannot be retrieved later.
+
+On RBAC workspaces the new token has no environment access and the endpoint will
+return `401 "Webhook token not found"`. Authorize it (the endpoint lives in `main`
+unless created elsewhere):
+
+```bash
+modal workspace proxy-tokens allow <token-id> main
+```
+
+## 4. PhoneLLM endpoint
 
 Check for an existing endpoint: `modal endpoint list --json`, looking for a live
-`phonellm-alpha-1`. If present, skip to step 4.
+`phonellm-alpha-1`. If present, skip to step 5.
 
 If absent, **ask the user before creating** (it provisions GPU infrastructure —
 takes ~20–30 minutes and bills their workspace):
@@ -48,40 +73,21 @@ modal endpoint create --model pipecat-ai/phonellm-alpha-1
 retrieve it later (`modal endpoint list` shows status only). Then poll
 `modal endpoint list --json` every ~30s (in the background) until status is `live`.
 
-## 4. Endpoint URL
+## 5. Endpoint URL
 
 If `MODAL_ENDPOINT_URL` is already in `server/.env`, keep it. If you just ran
 `endpoint create`, use the URL from its output. Otherwise **ask the user to paste it**
 from their create-output scrollback or the endpoint's page in the Modal dashboard
 (`modal dashboard`). Do not guess hostnames — the URL's label is not derivable from
 the endpoint name.
 
-## 5. Proxy token
-
-If `MODAL_API_KEY` is already in `server/.env`, keep it. Otherwise create one:
-
-```bash
-modal workspace proxy-tokens create --json
-```
-
-Combine as `<token-id>.<token-secret>` (`wk-....ws-...`) and write it to `server/.env`
-without echoing the secret. The secret is shown once and cannot be retrieved later.
-
-On RBAC workspaces the new token has no environment access and the endpoint will
-return `401 "Webhook token not found"`. Authorize it (the endpoint lives in `main`
-unless created elsewhere):
-
-```bash
-modal workspace proxy-tokens allow <token-id> main
-```
-
 ## 6. Configure .env
 
 If `server/.env` doesn't exist, `cp server/.env.example server/.env`. Ensure it has:
 
 - `DEEPGRAM_API_KEY` — **ask the user for it** if missing; never invent keys.
-- `MODAL_ENDPOINT_URL` — from step 4.
-- `MODAL_API_KEY` — from step 5.
+- `MODAL_ENDPOINT_URL` — from step 5.
+- `MODAL_API_KEY` — from step 3.
 
 ## 7. Health-check the endpoint
 
@@ -97,7 +103,7 @@ Interpret the result:
   Retry every ~30s (in the background). A 30B model can take several minutes. An
   *instant* 503 that persists well past 10 minutes suggests a wrong URL — re-verify
   with the user rather than retrying forever.
-- **401 "Webhook token not found"** — the RBAC `allow` step (5) is missing.
+- **401 "Webhook token not found"** — the RBAC `allow` step (3) is missing.
 
 Optionally verify the exact request path the bot uses:
 

phonellm/README.md

@@ -28,7 +28,23 @@ modal setup
 
 This opens your browser to authenticate and writes your API credentials to a local Modal profile.
 
-### 2. Create the endpoint
+### 2. Create a proxy token
+
+The bot authenticates with a workspace proxy token rather than your local credentials. Create it before the endpoint — an authenticated endpoint requires a proxy token to already exist in the workspace, and `modal endpoint create` fails without one:
+
+```bash
+modal workspace proxy-tokens create
+```
+
+This prints a token ID (`wk-...`) and secret (`ws-...`). Save the secret now — it can't be retrieved later. Combined as `<token-id>.<token-secret>`, they form the API key the bot sends as a Bearer token.
+
+On workspaces with RBAC enabled, new tokens start with no environment access, and the endpoint rejects them with `401 "Webhook token not found"`. Allow the token into the environment the endpoint will live in (`main` unless you create it elsewhere):
+
+```bash
+modal workspace proxy-tokens allow <token-id> main
+```
+
+### 3. Create the endpoint
 
 ```bash
 modal endpoint create --model pipecat-ai/phonellm-alpha-1
@@ -38,7 +54,9 @@ Modal provisions an [Auto Endpoint](https://modal.com/docs/guide/endpoints) —
 
 > **Note:** The CLI can't retrieve the endpoint URL after the fact — `modal endpoint list` shows status but not the URL. If you lose it, find it on the endpoint's page in the [Modal dashboard](https://modal.com/) (`modal dashboard` opens it).
 
-### 3. Check that it's running
+> **Note:** `modal endpoint create --unauthenticated` skips the token requirement, but leaves the endpoint open to anyone on the internet. The rest of this guide assumes the authenticated endpoint above.
+
+### 4. Check that it's running
 
 List your endpoints and their status (`provisioning` → `live`):
 
@@ -56,22 +74,6 @@ A JSON response listing `pipecat-ai/phonellm-alpha-1` means the endpoint is heal
 
 > **Note:** Endpoints scale to zero when idle. The first request after creation (or after a quiet period) returns 503 while the model spins up — this can take several minutes for a 30B model, and the container logs (`modal app logs`) may go quiet during kernel compilation. Keep retrying.
 
-### 4. Create a proxy token
-
-The bot authenticates with a workspace proxy token rather than your local credentials:
-
-```bash
-modal workspace proxy-tokens create
-```
-
-This prints a token ID (`wk-...`) and secret (`ws-...`). Save the secret now — it can't be retrieved later. Combined as `<token-id>.<token-secret>`, they form the API key the bot sends as a Bearer token.
-
-On workspaces with RBAC enabled, new tokens start with no environment access, and the endpoint rejects them with `401 "Webhook token not found"`. Allow the token into the environment the endpoint lives in (`main` unless you created it elsewhere):
-
-```bash
-modal workspace proxy-tokens allow <token-id> main
-```
-
 ### 5. Verify end to end (optional)
 
 Test the exact request path the bot will use — proxy-token auth against the chat completions API: