Document more customization points across all templates (#30)

teallarson · claude · web-flow · commit f1b0b3487dbc · 2026-03-18T16:10:56.000-07:00
Co-authored-by: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/templates/_shared/agent-playbook.md.hbs b/templates/_shared/agent-playbook.md.hbs
@@ -14,19 +14,29 @@ Look for these markers:
 
 {{#if (eq name "langchain")}}
 1. Edit `app/system-prompt.md` to change agent behavior.
-2. Change model choice in `app/agent.py`.
-3. Extend schema in `app/models.py` if you need app-specific data.
-4. Ensure `ARCADE_GATEWAY_URL` is set and the gateway has the expected tools.
+2. The plan prompt is built inline in `app/routes/plan.py` (`_build_plan_prompt`) — update it to match your system prompt.
+3. Change model choice in `app/agent.py`.
+4. Extend schema in `app/models.py` if you need app-specific data.
+5. Ensure `ARCADE_GATEWAY_URL` is set and the gateway has the expected tools.
+6. If your agent needs write/mutation tools (send, create, reply, post, etc.) during planning, edit the `_MUTATION` regex in `app/routes/plan.py`. By default, all write tools are stripped from the plan endpoint to keep triage read-only.
 {{else if (eq name "mastra")}}
 1. Edit `src/mastra/agents/system-prompt.md` to change agent behavior.
-2. Change model choice in `src/mastra/agents/triage-agent.ts`.
-3. Extend schema in `lib/db/schema.ts` if you need app-specific data.
-4. Ensure `ARCADE_GATEWAY_URL` is set and the gateway has the expected tools.
+2. Edit `src/mastra/agents/plan-prompt.md` to match your updated system prompt — this controls the plan endpoint's behavior.
+3. Change model choice in `src/mastra/agents/triage-agent.ts`.
+4. Extend schema in `lib/db/schema.ts` if you need app-specific data.
+5. Ensure `ARCADE_GATEWAY_URL` is set and the gateway has the expected tools.
+6. If your agent needs write/mutation tools (send, create, reply, post, etc.) during planning, edit the `MUTATION` regex filter in `app/api/plan/route.ts`. By default, all write tools are stripped from the plan endpoint to keep triage read-only.
+7. Update `components/dashboard/empty-state.tsx` to match your agent's purpose — replace "Ready to triage?" heading, the description text, and "Plan my day" button label.
+8. Look for `CUSTOMIZATION POINT` markers in UI files for other safe edit zones.
 {{else}}
 1. Edit `lib/system-prompt.md` to change agent behavior.
-2. Change model choice in `lib/agent.ts`.
-3. Extend schema in `lib/db/schema.ts` if you need app-specific data.
-4. Ensure `ARCADE_GATEWAY_URL` is set and the gateway has the expected tools.
+2. Edit `lib/plan-prompt.md` to match your updated system prompt — this controls the plan endpoint's behavior.
+3. Change model choice in `lib/agent.ts`.
+4. Extend schema in `lib/db/schema.ts` if you need app-specific data.
+5. Ensure `ARCADE_GATEWAY_URL` is set and the gateway has the expected tools.
+6. If your agent needs write/mutation tools (send, create, reply, post, etc.) during planning, edit the `MUTATION` regex filter in `app/api/plan/route.ts`. By default, all write tools are stripped from the plan endpoint to keep triage read-only.
+7. Update `components/dashboard/empty-state.tsx` to match your agent's purpose — replace "Ready to triage?" heading, the description text, and "Plan my day" button label.
+8. Look for `CUSTOMIZATION POINT` markers in UI files for other safe edit zones.
 {{/if}}
 
 ## Gateway Checklist
@@ -39,6 +49,8 @@ Create/configure your gateway at `https://app.arcade.dev/mcp-gateways` and add:
 - GitHub
 - Gmail
 
+If you add tools from services not listed above, also add a source entry in `lib/sources.ts` so they get proper icons and labels in the UI.
+
 ## Verification Commands
 
 {{#if (eq name "langchain")}}
diff --git a/templates/_shared/nextjs-ui/components/dashboard/empty-state.tsx b/templates/_shared/nextjs-ui/components/dashboard/empty-state.tsx
@@ -13,7 +13,9 @@ export function EmptyState({ onPlan, loading }: EmptyStateProps) {
     <div className="flex flex-1 flex-col items-center justify-center gap-6 p-8">
       <Inbox size={48} className="text-muted-foreground/50" />
       <div className="flex flex-col items-center gap-2">
+        {/* CUSTOMIZATION POINT — empty state heading */}
         <h2 className="text-2xl font-semibold">Ready to triage?</h2>
+        {/* CUSTOMIZATION POINT — empty state description */}
         <p className="max-w-md text-center text-muted-foreground">
           Your agent will scan your inbox, calendar, tasks, and PRs, then prioritize everything and
           build your action plan.
@@ -26,6 +28,7 @@ export function EmptyState({ onPlan, loading }: EmptyStateProps) {
             Planning...
           </>
         ) : (
+          /* CUSTOMIZATION POINT — primary action button label */
           "Plan my day"
         )}
       </Button>
diff --git a/templates/_shared/partials/customization.md.hbs b/templates/_shared/partials/customization.md.hbs
@@ -3,11 +3,11 @@
 ### Change the agent's purpose
 
 {{#if (eq name "mastra")}}
-Edit `src/mastra/agents/system-prompt.md` to change what the agent does (PR reviews, calendar management, email drafting, etc.). The agent definition in `src/mastra/agents/triage-agent.ts` has `// --- CUSTOMIZATION POINT ---` markers for model selection and other settings.
+Edit `src/mastra/agents/system-prompt.md` to change what the agent does (PR reviews, calendar management, email drafting, etc.). Also update `src/mastra/agents/plan-prompt.md` in the same directory — this is the system prompt for the plan/triage endpoint and must stay in sync with your main system prompt. The agent definition in `src/mastra/agents/triage-agent.ts` has `// --- CUSTOMIZATION POINT ---` markers for model selection and other settings.
 {{else if (eq name "ai-sdk")}}
-Edit `lib/system-prompt.md` to change what the agent does (PR reviews, calendar management, email drafting, etc.). The agent configuration in `lib/agent.ts` has model selection you can customize.
+Edit `lib/system-prompt.md` to change what the agent does (PR reviews, calendar management, email drafting, etc.). Also update `lib/plan-prompt.md` — this is the system prompt for the plan/triage endpoint and must stay in sync with your main system prompt. The agent configuration in `lib/agent.ts` has model selection you can customize.
 {{else}}
-Edit `app/system-prompt.md` to change what the agent does (PR reviews, calendar management, email drafting, etc.). The agent configuration in `app/agent.py` has `# --- CUSTOMIZATION POINT ---` markers for model selection and other settings.
+Edit `app/system-prompt.md` to change what the agent does (PR reviews, calendar management, email drafting, etc.). The plan prompt is built inline in `app/routes/plan.py` — update `_build_plan_prompt()` to match your system prompt changes. The agent configuration in `app/agent.py` has `# --- CUSTOMIZATION POINT ---` markers for model selection and other settings.
 {{/if}}
 
 ### Add or change Arcade tools
@@ -16,7 +16,7 @@ Edit `app/system-prompt.md` to change what the agent does (PR reviews, calendar
 2. Add tools to your gateway (Gmail, GitHub, Google Calendar, etc.)
 3. Update `ARCADE_GATEWAY_URL` in `.env` if needed
 
-The agent automatically discovers all tools available on your gateway.
+The agent automatically discovers all tools available on your gateway. Write tools (send, create, reply, etc.) may require additional OAuth authorization beyond read tools. The app handles this automatically — when a write tool needs auth, users see an inline prompt to grant access.
 
 ### Switch LLM provider
 
@@ -51,6 +51,16 @@ alembic upgrade head
 ```
 {{/if}}
 
+{{#if (eq language "typescript")}}
+### Customize the UI
+
+The default UI is built for a daily triage workflow. To adapt it for your agent:
+
+1. Edit `components/dashboard/empty-state.tsx` — change the heading, description, and button label
+2. The dashboard layout in `app/dashboard/page.tsx` uses task cards and stats — you can restructure this for your use case
+3. Look for `CUSTOMIZATION POINT` comments in UI files for safe edit zones
+
+{{/if}}
 ### Production considerations
 
 This template uses app-level token storage — all users share the same Arcade Gateway connection via a single `.arcade-auth/` directory. For production deployments:
diff --git a/templates/ai-sdk/CLAUDE.md b/templates/ai-sdk/CLAUDE.md
@@ -29,27 +29,31 @@ bunx drizzle-kit migrate        # Run migrations
 
 ## Key Files
 
-| File                                    | Purpose                                                |
-| --------------------------------------- | ------------------------------------------------------ |
-| `lib/agent.ts`                          | Model selection (Claude/GPT-4o) + system prompt loader |
-| `lib/system-prompt.md`                  | System prompt (customization point)                    |
-| `lib/arcade.ts`                         | MCP OAuth provider + `createMCPClient` factory         |
-| `app/api/chat/route.ts`                 | Streaming chat endpoint (`streamText` + MCP tools)     |
-| `app/api/auth/arcade/connect/route.ts`  | Pre-flight Arcade connection check                     |
-| `app/api/auth/arcade/callback/route.ts` | OAuth callback (code → tokens)                         |
-| `app/api/auth/arcade/verify/route.ts`   | Custom user verifier (COAT protection)                 |
-| `app/dashboard/page.tsx`                | Daily triage dashboard (main UI entry point)           |
-| `lib/auth.ts`                           | Better Auth server config + `getSession()` helper      |
-| `lib/auth-client.ts`                    | Better Auth React client (signIn, signUp, signOut)     |
-| `lib/db/schema.ts`                      | Database schema (Better Auth tables + custom tables)   |
+| File                                    | Purpose                                                                                    |
+| --------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `lib/agent.ts`                          | Model selection (Claude/GPT-4o) + system prompt loader                                     |
+| `lib/system-prompt.md`                  | System prompt (customization point)                                                        |
+| `lib/arcade.ts`                         | MCP OAuth provider + `createMCPClient` factory                                             |
+| `app/api/chat/route.ts`                 | Streaming chat endpoint (`streamText` + MCP tools)                                         |
+| `app/api/auth/arcade/connect/route.ts`  | Pre-flight Arcade connection check                                                         |
+| `app/api/auth/arcade/callback/route.ts` | OAuth callback (code → tokens)                                                             |
+| `app/api/auth/arcade/verify/route.ts`   | Custom user verifier (COAT protection)                                                     |
+| `app/dashboard/page.tsx`                | Daily triage dashboard (main UI entry point)                                               |
+| `lib/auth.ts`                           | Better Auth server config + `getSession()` helper                                          |
+| `lib/auth-client.ts`                    | Better Auth React client (signIn, signUp, signOut)                                         |
+| `lib/db/schema.ts`                      | Database schema (Better Auth tables + custom tables)                                       |
+| `lib/plan-prompt.md`                    | Plan endpoint system prompt (customize alongside system-prompt.md)                         |
+| `app/api/plan/route.ts`                 | Plan/triage streaming endpoint — filters out write tools by default                        |
+| `lib/sources.ts`                        | Tool-to-icon/label mapping — add entries for new services (has CUSTOMIZATION POINT marker) |
+| `components/dashboard/empty-state.tsx`  | Empty state UI — customize heading, description, and button for your agent's purpose       |
 
 ## Auth Architecture
 
 Three layers:
 
 1. **App auth** — email/password via [Better Auth](https://www.better-auth.com), session cookies (7-day), SQLite storage via Drizzle adapter. Configure `BETTER_AUTH_SECRET` and `BETTER_AUTH_URL` in `.env`.
 2. **Arcade Gateway OAuth** — MCP OAuth flow with file-based token persistence in `.arcade-auth/` (discovery → registration → PKCE → token exchange)
-3. **Tool-level OAuth** — Arcade handles per-tool auth (Slack, GitHub, etc.); auth URLs surfaced in chat UI
+3. **Tool-level OAuth** — Arcade handles per-tool auth (Slack, GitHub, etc.); auth URLs surfaced in chat UI. Write tools (send, create, update, etc.) may require additional OAuth scopes beyond read permissions. When a write tool needs authorization, the plan route emits an `auth_required` event with an auth URL, and the UI shows an inline auth prompt. This flow is handled automatically — just ensure your UI renders the `AuthPrompt` component.
 4. **Custom verifier** (optional) — `/api/auth/arcade/verify` confirms user identity for COAT protection. Enabling requires: (a) custom OAuth apps registered with each provider (Slack, GitHub, etc.) in the Arcade dashboard — default shared apps cannot be used, and (b) exposing the local server via ngrok so Arcade can reach the endpoint. When using ngrok: set `NEXT_PUBLIC_APP_URL` to the ngrok URL, delete `.arcade-auth/`, restart the dev server, and **log in via the ngrok URL** (not localhost) — session cookies are scoped to the host that sets them; mismatched host = silent verification failure (`verify_session_required` error). If you get repeated `400 Bad Request` from Arcade's `confirm_user` API, the `flow_id` is stale — delete `.arcade-auth/`, restart, re-authenticate, then retry tool auth from scratch.
 
 ## Constraints
@@ -62,6 +66,7 @@ Three layers:
 ## Customization Points
 
 - `lib/system-prompt.md` — Agent purpose and behavior
+- `lib/plan-prompt.md` — Plan endpoint system prompt (keep in sync with system-prompt.md)
 - `lib/agent.ts` — Model selection
 - `lib/db/schema.ts` — Database schema
 
@@ -70,6 +75,6 @@ Three layers:
 - **Main UI**: `app/dashboard/page.tsx` — layout, plan-run flow, and ChatPanel toggle. This is the primary entry point after login.
 - **Component library**: import UI components from `@arcadeai/design-system`; import brand icons (Slack, GitHub, Gmail, etc.) from `@arcadeai/design-system/components/ui/atoms/icons`.
 - **Startup checks**: add new env-var warnings in `app/api/health/route.ts` — push a new `ConfigWarning` object to the `warnings` array.
-- **Safe to edit**: `lib/system-prompt.md`, `lib/agent.ts` (model choice), `lib/db/schema.ts` (schema extensions).
-- **Edit with care**: anything under `app/api/auth/arcade/` — the OAuth flow is stateful (PKCE verifier, token exchange, `.arcade-auth/` persistence). Read the full flow before making changes.
+- **Safe to edit**: `lib/system-prompt.md`, `lib/plan-prompt.md`, `lib/agent.ts` (model choice), `lib/db/schema.ts` (schema extensions), `lib/sources.ts` (add source entries for new toolkits), `components/dashboard/empty-state.tsx` (heading, description, button label).
+- **Edit with care**: anything under `app/api/auth/arcade/` — the OAuth flow is stateful (PKCE verifier, token exchange, `.arcade-auth/` persistence). Read the full flow before making changes. `app/api/plan/route.ts` — contains a `MUTATION` regex that strips write tools (create, send, reply, etc.) from the plan endpoint. If your agent needs write tools during planning, update or remove this filter.
 - **Do not touch**: `lib/arcade.ts` unless you understand the `OAuthClientProvider` contract expected by `@ai-sdk/mcp`.
diff --git a/templates/langchain/CLAUDE.md b/templates/langchain/CLAUDE.md
@@ -28,26 +28,27 @@ alembic upgrade head                   # Run migrations
 
 ## Key Files
 
-| File                   | Purpose                                                                  |
-| ---------------------- | ------------------------------------------------------------------------ |
-| `app/agent.py`         | Agent definition — model selection                                       |
-| `app/system-prompt.md` | System prompt (customization point)                                      |
-| `app/arcade_oauth.py`  | MCP OAuth flow — discovery, PKCE, token exchange, file-based persistence |
-| `app/routes/chat.py`   | SSE streaming chat endpoint                                              |
-| `app/routes/arcade.py` | OAuth connect/callback + custom user verifier                            |
-| `app/routes/auth.py`   | Login, register, logout                                                  |
-| `app/auth.py`          | `get_current_user()` helper (FastAPI Users JWT-backed)                   |
-| `app/auth_manager.py`  | FastAPI Users setup (UserManager, JWT strategy, cookie transport)        |
-| `app/models.py`        | User model (extends FastAPI Users base)                                  |
-| `app/static/chat.js`   | Chat UI — SSE streaming, tool calls, auth URLs                           |
+| File                   | Purpose                                                                      |
+| ---------------------- | ---------------------------------------------------------------------------- |
+| `app/agent.py`         | Agent definition — model selection                                           |
+| `app/system-prompt.md` | System prompt (customization point)                                          |
+| `app/arcade_oauth.py`  | MCP OAuth flow — discovery, PKCE, token exchange, file-based persistence     |
+| `app/routes/chat.py`   | SSE streaming chat endpoint                                                  |
+| `app/routes/arcade.py` | OAuth connect/callback + custom user verifier                                |
+| `app/routes/auth.py`   | Login, register, logout                                                      |
+| `app/auth.py`          | `get_current_user()` helper (FastAPI Users JWT-backed)                       |
+| `app/auth_manager.py`  | FastAPI Users setup (UserManager, JWT strategy, cookie transport)            |
+| `app/models.py`        | User model (extends FastAPI Users base)                                      |
+| `app/static/chat.js`   | Chat UI — SSE streaming, tool calls, auth URLs                               |
+| `app/routes/plan.py`   | Plan/triage endpoint — filters out write tools + unknown services by default |
 
 ## Auth Architecture
 
 Three layers:
 
 1. **App auth** — email/password via [FastAPI Users](https://fastapi-users.github.io/fastapi-users/), stateless JWT stored in an httpOnly `session_id` cookie, SQLite storage. Configure `APP_SECRET_KEY` in `.env`.
 2. **Arcade Gateway OAuth** — MCP OAuth flow with file-based token persistence in `.arcade-auth/` (discovery → registration → PKCE → token exchange)
-3. **Tool-level OAuth** — Arcade handles per-tool auth (Slack, GitHub, etc.); auth URLs surfaced in chat UI
+3. **Tool-level OAuth** — Arcade handles per-tool auth (Slack, GitHub, etc.); auth URLs surfaced in chat UI. Write tools (send, create, reply, etc.) may require additional OAuth authorization beyond read tools. The app handles this automatically — when a write tool needs auth, users see an inline prompt to grant access.
 4. **Custom verifier** (optional) — `/api/arcade/verify` confirms user identity for COAT protection. Enabling the custom verifier also requires: (a) setting up custom OAuth applications with each auth provider (Slack, GitHub, etc.) in the Arcade dashboard — Arcade's default shared OAuth apps cannot be used with a custom verifier, and (b) exposing the local dev server via ngrok (`ngrok http 8000`) so Arcade can reach the verifier endpoint, then configuring the ngrok URL in the Arcade dashboard
 
 ## Constraints
diff --git a/templates/mastra/CLAUDE.md b/templates/mastra/CLAUDE.md
