Add agent docs and update forward-call README

forward-call/.github/copilot-instructions.md

@@ -0,0 +1 @@
+Refer to [AGENTS.md](../AGENTS.md) for all repo instructions.

forward-call/AGENTS.md

@@ -0,0 +1,75 @@
+# Forward Call
+
+Demonstrates how to forward an incoming call to a specified phone number using Twilio Serverless Functions and TwiML.
+
+## Environment Variables
+
+`.env` is included with placeholder values. Update it before running. Never commit `.env`.
+
+| Variable | Where to find | Format |
+| -------- | ------------- | ------ |
+| `MY_PHONE_NUMBER` | Phone number you control — the destination for forwarded calls | E.164 format: `+15551234567` |
+| `TWILIO_VOICE_WEBHOOK_URL` | Pre-set to `/forward-call` — do not change | `/forward-call` |
+
+## Commands
+
+```bash
+# Install Twilio CLI serverless plugin (once)
+twilio plugins:install @twilio-labs/plugin-serverless
+
+# Initialize a new project from this template
+# --skip-credentials skips the credential prompt (Serverless injects them at runtime)
+twilio serverless:init example --template=forward-call --skip-credentials && cd example
+# Edit .env — replace placeholder MY_PHONE_NUMBER with your real E.164 number
+
+# Start the server
+twilio serverless:start
+
+# Expose locally via ngrok (run separately — install and authenticate at https://ngrok.com)
+ngrok http 3000
+
+# Configure the voice webhook on your Twilio number
+# Find your phone number SID:
+twilio api:core:incoming-phone-numbers:list
+# Set the webhook (replace URL with your ngrok URL or deployed URL):
+twilio api:core:incoming-phone-numbers:update \
+  --sid <your-phone-number-sid> \
+  --voice-url https://<your-ngrok-id>.ngrok.app/forward-call \
+  --voice-method POST
+
+# Deploy
+twilio serverless:deploy --service-name forward-call
+```
+
+## Project Structure
+
+- `functions/forward-call.protected.js` — main handler; dials `MY_PHONE_NUMBER` via TwiML
+- `tests/forward-call.test.js` — Jest unit tests (run from the monorepo root, not this directory)
+- `.env` — environment variables (never commit)
+
+## Agent Boundaries
+
+**Always:**
+
+- Confirm `.env` is configured before running any command
+- Use the Environment Variables section to guide the user to each credential — don't ask them to find values without direction
+- Confirm the app is running before asking the user to test it
+- Always use `--template=forward-call` when initializing a new project
+
+**Never:**
+
+- Run the app with missing or placeholder credentials
+- Hardcode credentials or phone numbers in source files
+- Run with placeholder values still in `.env`
+
+## Verify It's Working
+
+1. Call your Twilio phone number
+2. The call should ring through to the number set in `MY_PHONE_NUMBER`
+
+## Twilio Resources
+
+- [Twilio Console](https://console.twilio.com) — credentials, phone numbers, webhook configuration
+- [Twilio Serverless Toolkit](https://www.twilio.com/docs/labs/serverless-toolkit) — deploy and manage Serverless Functions
+- [TwiML for Voice](https://www.twilio.com/docs/voice/twiml) — reference for the VoiceResponse used in this template
+- [Programmable Voice](https://www.twilio.com/docs/voice) — Voice API reference

forward-call/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

forward-call/README.md

@@ -1,15 +1,82 @@
 # Forward Call
 
-This Function in `forward-call.js` will return the [TwiML](https://www.twilio.com/docs/voice/twiml) required to forward an incoming call to a number that is set in the environment variables.
+This application forwards an incoming call to a number set in the environment variables.
+
+## Pre-requisites
+
+- A [Twilio account](https://www.twilio.com/try-twilio) with an active phone number that can receive calls
 
 ### Environment variables
 
-This Function expects one environment variable to be set.
+`.env` is included with placeholder values. Update `MY_PHONE_NUMBER` before running. Never commit `.env`.
+
+| Variable | Description | Required |
+| :- | :- | :- |
+| `MY_PHONE_NUMBER` | The number to forward incoming calls to [in E.164 format](https://support.twilio.com/hc/en-us/articles/223183008-Formatting-International-Phone-Numbers) | Yes |
+| `TWILIO_VOICE_WEBHOOK_URL` | The webhook path — pre-set to `/forward-call`, do not change | Yes |
+
+## Running the project
+
+1. Install the [Twilio CLI](https://www.twilio.com/docs/twilio-cli/quickstart#install-twilio-cli)
+1. Install the [serverless toolkit](https://www.twilio.com/docs/labs/serverless-toolkit/getting-started)
+
+```shell
+twilio plugins:install @twilio-labs/plugin-serverless
+```
+
+1. Initialize the project from the template
+
+```shell
+twilio serverless:init example --template=forward-call --skip-credentials && cd example
+```
+
+1. Edit `.env` and replace the placeholder `MY_PHONE_NUMBER` with your real E.164 number
+
+1. Start the server
+
+```shell
+twilio serverless:start
+```
+
+Check the developer console and terminal for any errors, and make sure you've set your environment variables.
+
+### Configuring your Twilio phone number
+
+You can configure the webhook via the Twilio CLI (recommended) or the Console.
+
+**Via CLI:**
+
+Find your phone number SID:
+
+```shell
+twilio api:core:incoming-phone-numbers:list
+```
+
+Then update the voice webhook:
+
+```shell
+twilio api:core:incoming-phone-numbers:update \
+  --sid <your-phone-number-sid> \
+  --voice-url https://<your-ngrok-id>.ngrok.app/forward-call \
+  --voice-method POST
+```
+
+**Via Console:**
+
+1. Go to your [Twilio Console Phone Numbers](https://console.twilio.com/us1/develop/phone-numbers/manage/incoming)
+2. Select the phone number you want to use
+3. Under "Voice Configuration":
+   - Set "A Call Comes In" to **Webhook**
+   - Enter your URL: `https://<your-ngrok-id>.ngrok.app/forward-call` (or your deployed URL)
+   - Set HTTP method to **POST**
+4. Click **Save**
+
+## Deploying
 
-| Variable          | Meaning                                                                                                                                                              |
-| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `MY_PHONE_NUMBER` | The number you want to forward incoming calls to [in E.164 format](https://help.twilio.com/articles/223183008-Formatting-International-Phone-Numbers) |
+Deploy your functions and assets with the following command. Note: you must run these commands from inside your project folder. [More information about the serverless toolkit in the docs.](https://www.twilio.com/docs/labs/serverless-toolkit)
 
-### Parameters
+With the [Twilio CLI](https://www.twilio.com/docs/twilio-cli/quickstart):
 
-This Function expects the incoming request to be a messaging webhook. The parameters that will be used are `From` and `Body`.
+```shell
+twilio serverless:deploy --service-name forward-call
+```