Add agent name to outbound emails, update /docs with missing endpoints

- Outbound invite and RSVP reply emails now use agent name as From
  display name when set (e.g. "My Agent" <cal-xxx@invite.caldave.ai>)
- /docs page now documents GET /agents/me, PATCH /agents, agent
  name/description on POST /agents, GET /changelog, and POST /man
- Added IMPORTANT note to CLAUDE.md requiring all five doc surfaces
  to be updated when adding public API endpoints

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: plc

CHANGELOG.md

@@ -11,6 +11,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - **API changelog endpoint** — `GET /changelog` returns a structured list of API changes with dates and docs links. With optional Bearer auth, highlights changes introduced since the agent was created. Designed for agents to poll ~weekly.
 - **Agent metadata** — `POST /agents` now accepts optional `name` and `description` fields to identify agents. New `GET /agents/me` returns the agent's profile. New `PATCH /agents` updates metadata without changing the API key. Agent name and description are surfaced in `POST /man` context.
 - **Outbound calendar invites** — when an event is created or updated with attendees, CalDave sends METHOD:REQUEST iCal invite emails via Postmark. Invites include `.ics` attachments that work with Google Calendar, Outlook, and Apple Calendar. From address is the calendar's email so replies route back through the inbound webhook.
+- **Agent name in outbound emails** — when an agent has a name set (via `PATCH /agents`), outbound invite and RSVP reply emails use `"Agent Name" <calendar-email>` as the From address, so recipients see a friendly display name instead of just the calendar email.
 - **Outbound RSVP replies** — when an agent responds to an inbound invite via `POST /respond`, CalDave sends a METHOD:REPLY iCal email back to the organiser with the agent's acceptance, decline, or tentative status.
 - **Graceful degradation** — if `POSTMARK_SERVER_TOKEN` is not set, outbound emails are silently skipped. All API endpoints continue to work normally.
 - **Outbound email tracking** — new `invite_sent`, `reply_sent`, and `ical_sequence` columns on events prevent duplicate sends and support proper iCal update semantics.
@@ -23,6 +24,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - **Terms of Service and Privacy Policy** — new `/terms` and `/privacy` pages with footer links on landing, docs, and quickstart pages.
 
 ### Fixed
+- **API docs updated** — `/docs` page now documents `GET /agents/me`, `PATCH /agents`, agent `name`/`description` fields on `POST /agents`, `GET /changelog`, and `POST /man`. Table of contents updated with Agents and Discovery sections.
 - **JSON 404 catch-all** — unmatched routes now return `{"error": "Not found. Try POST /man for the API reference."}` instead of Express's default HTML page.
 - **Guide mode discoverability** — `POST /man?guide` now includes a `discover_more` object pointing to the full API reference, changelog, and agent update endpoint so agents don't have to guess at available endpoints.
 - **Welcome event in /man recommendation** — `POST /man` recommendation logic now accounts for the auto-created welcome event (same fix as changelog recommendations).

CLAUDE.md

@@ -70,6 +70,15 @@ fly deploy
 | **README.md** | When user-facing details change |
 | **GOTCHAS.md** | When you encounter problems |
 
+**IMPORTANT: When adding or changing public API endpoints, you MUST update ALL of these:**
+1. **`src/routes/docs.js`** — the HTML docs page at `/docs` (endpoint card + table of contents)
+2. **`src/routes/changelog.js`** — the structured `CHANGELOG` array served by `GET /changelog`
+3. **`src/routes/man.js`** — the `getEndpoints()` array served by `POST /man`
+4. **`CHANGELOG.md`** — the human-readable changelog
+5. **`CALDAVE_SPEC.md`** — the full API spec
+
+These are all separate and must be kept in sync. Missing any one means agents or humans won't discover the new endpoint.
+
 ## Git Workflow
 
 - **Update CHANGELOG.md before committing** — include it in the same commit as your changes

src/lib/outbound.js

@@ -138,9 +138,11 @@ function generateReplyIcs(event, calendar, response) {
  * @param {Object} event            — event row from DB
  * @param {Object} calendar         — calendar row from DB
  * @param {string[]} recipientEmails — email addresses to send to
+ * @param {Object} [options]         — optional settings
+ * @param {string} [options.agentName] — agent display name for From header
  * @returns {Promise<{ sent: boolean, reason?: string, icalUid?: string }>}
  */
-async function sendInviteEmail(event, calendar, recipientEmails) {
+async function sendInviteEmail(event, calendar, recipientEmails, options = {}) {
   const client = getPostmarkClient();
   if (!client) {
     console.log('[outbound] Skipping invite (no POSTMARK_SERVER_TOKEN): event=%s', event.id);
@@ -155,11 +157,12 @@ async function sendInviteEmail(event, calendar, recipientEmails) {
   const { icsString, icalUid } = generateInviteIcs(event, calendar);
 
   const to = recipientEmails.join(',');
-  console.log('[outbound] Sending invite: event=%s from=%s to=%s title="%s"', event.id, calendar.email, to, event.title);
+  const from = options.agentName ? '"' + options.agentName + '" <' + calendar.email + '>' : calendar.email;
+  console.log('[outbound] Sending invite: event=%s from=%s to=%s title="%s"', event.id, from, to, event.title);
 
   try {
     const pmResponse = await client.sendEmail({
-      From: calendar.email,
+      From: from,
       To: to,
       Subject: 'Invitation: ' + event.title,
       TextBody: [
@@ -193,9 +196,11 @@ async function sendInviteEmail(event, calendar, recipientEmails) {
  * @param {Object} event    — event row from DB (must have organiser_email and ical_uid)
  * @param {Object} calendar — calendar row from DB
  * @param {string} response — 'accepted' | 'declined' | 'tentative'
+ * @param {Object} [options]         — optional settings
+ * @param {string} [options.agentName] — agent display name for From header
  * @returns {Promise<{ sent: boolean, reason?: string }>}
  */
-async function sendReplyEmail(event, calendar, response) {
+async function sendReplyEmail(event, calendar, response, options = {}) {
   const client = getPostmarkClient();
   if (!client) {
     console.log('[outbound] Skipping reply (no POSTMARK_SERVER_TOKEN): event=%s', event.id);
@@ -215,11 +220,12 @@ async function sendReplyEmail(event, calendar, response) {
   const icsString = generateReplyIcs(event, calendar, response);
   const statusLabel = response.charAt(0).toUpperCase() + response.slice(1);
 
-  console.log('[outbound] Sending %s reply: event=%s from=%s to=%s title="%s"', response, event.id, calendar.email, event.organiser_email, event.title);
+  const from = options.agentName ? '"' + options.agentName + '" <' + calendar.email + '>' : calendar.email;
+  console.log('[outbound] Sending %s reply: event=%s from=%s to=%s title="%s"', response, event.id, from, event.organiser_email, event.title);
 
   try {
     const pmResponse = await client.sendEmail({
-      From: calendar.email,
+      From: from,
       To: event.organiser_email,
       Subject: statusLabel + ': ' + event.title,
       TextBody: calendar.name + ' has ' + response + ' the invitation: ' + event.title,

src/routes/changelog.js

@@ -128,6 +128,13 @@ const CHANGELOG = [
         endpoints: ['POST /agents', 'GET /agents/me', 'PATCH /agents'],
         docs: BASE + '/docs#agents',
       },
+      {
+        type: 'feature',
+        title: 'Agent name in outbound emails',
+        description: 'When your agent has a name set, outbound invite and RSVP reply emails show the agent name as the From display name (e.g. "My Agent" <cal-xxx@invite.caldave.ai>).',
+        endpoints: ['POST /calendars/:id/events', 'PATCH /calendars/:id/events/:event_id', 'POST /calendars/:id/events/:event_id/respond'],
+        docs: BASE + '/docs#agents',
+      },
       {
         type: 'feature',
         title: 'Personalized recommendations in changelog',

src/routes/docs.js

@@ -76,9 +76,11 @@ router.get('/', (req, res) => {
 
     <div class="toc">
       <h2>Endpoints</h2>
-      <div class="section">Auth</div>
+      <div class="section">Agents</div>
       <ul>
         <li><a href="#post-agents">POST /agents</a> — Create agent</li>
+        <li><a href="#get-agents-me">GET /agents/me</a> — Get agent profile</li>
+        <li><a href="#patch-agents">PATCH /agents</a> — Update agent</li>
       </ul>
       <div class="section">Calendars</div>
       <ul>
@@ -104,6 +106,11 @@ router.get('/', (req, res) => {
         <li><a href="#get-feed">GET /feeds/:id.ics</a> — iCal feed</li>
         <li><a href="#post-inbound">POST /inbound/:token</a> — Inbound email webhook</li>
       </ul>
+      <div class="section">Discovery</div>
+      <ul>
+        <li><a href="#get-changelog">GET /changelog</a> — API changelog</li>
+        <li><a href="#post-man">POST /man</a> — Machine-readable API manual</li>
+      </ul>
     </div>
 
     <!-- ============================================================ -->
@@ -113,7 +120,7 @@ router.get('/', (req, res) => {
     <p>Exceptions: <code class="inline-code">POST /agents</code> (no auth), <code class="inline-code">GET /feeds</code> (token in query param), and <code class="inline-code">POST /inbound</code> (token in URL path).</p>
 
     <!-- ============================================================ -->
-    <h2>Agent Provisioning</h2>
+    <h2>Agents</h2>
 
     <div class="endpoint" id="post-agents">
       <div class="method-path">
@@ -122,16 +129,71 @@ router.get('/', (req, res) => {
         <span class="auth-badge">No auth</span>
       </div>
       <p class="desc">Create a new agent identity. Returns credentials you must save — the API key is shown once.</p>
+      <div class="label">Body parameters</div>
+      <div class="params">
+        <div class="param"><span class="param-name">name <span class="param-opt">optional</span></span><span class="param-desc">Display name for the agent (max 255 chars). Shown in outbound email From headers.</span></div>
+        <div class="param"><span class="param-name">description <span class="param-opt">optional</span></span><span class="param-desc">What the agent does (max 1000 chars). Surfaced in POST /man context.</span></div>
+      </div>
       <div class="label">Example</div>
-      <pre><code>curl -s -X POST https://${DOMAIN}/agents</code></pre>
+      <pre><code>curl -s -X POST https://${DOMAIN}/agents \\
+  -H "Content-Type: application/json" \\
+  -d '{"name": "Meeting Scheduler", "description": "Books rooms and sends reminders"}'</code></pre>
       <div class="label">Response</div>
       <pre><code>{
   "agent_id": "agt_x7y8z9AbCd",
   "api_key": "sk_live_abc123...",
+  "name": "Meeting Scheduler",
+  "description": "Books rooms and sends reminders",
   "message": "Store these credentials securely. The API key will not be shown again."
 }</code></pre>
     </div>
 
+    <div class="endpoint" id="get-agents-me">
+      <div class="method-path">
+        <span class="method get">GET</span>
+        <span class="path">/agents/me</span>
+        <span class="auth-badge required">Bearer token</span>
+      </div>
+      <p class="desc">Get the authenticated agent's profile.</p>
+      <div class="label">Example</div>
+      <pre><code>curl -s https://${DOMAIN}/agents/me \\
+  -H "Authorization: Bearer YOUR_API_KEY"</code></pre>
+      <div class="label">Response</div>
+      <pre><code>{
+  "agent_id": "agt_x7y8z9AbCd",
+  "name": "Meeting Scheduler",
+  "description": "Books rooms and sends reminders",
+  "created_at": "2026-02-14T10:30:00.000Z"
+}</code></pre>
+    </div>
+
+    <div class="endpoint" id="patch-agents">
+      <div class="method-path">
+        <span class="method patch">PATCH</span>
+        <span class="path">/agents</span>
+        <span class="auth-badge required">Bearer token</span>
+      </div>
+      <p class="desc">Update agent metadata. Does not change the API key. Set a field to <code class="inline-code">null</code> to clear it.</p>
+      <div class="label">Body parameters</div>
+      <div class="params">
+        <div class="param"><span class="param-name">name</span><span class="param-desc">Display name (max 255 chars)</span></div>
+        <div class="param"><span class="param-name">description</span><span class="param-desc">What the agent does (max 1000 chars)</span></div>
+      </div>
+      <div class="label">Example</div>
+      <pre><code>curl -s -X PATCH https://${DOMAIN}/agents \\
+  -H "Content-Type: application/json" \\
+  -H "Authorization: Bearer YOUR_API_KEY" \\
+  -d '{"name": "Updated Name"}'</code></pre>
+      <div class="label">Response</div>
+      <pre><code>{
+  "agent_id": "agt_x7y8z9AbCd",
+  "name": "Updated Name",
+  "description": "Books rooms and sends reminders",
+  "created_at": "2026-02-14T10:30:00.000Z"
+}</code></pre>
+      <div class="note">When an agent has a name, outbound invite and RSVP reply emails use it as the From display name (e.g. "Meeting Scheduler" &lt;cal-xxx@${EMAIL_DOMAIN}&gt;).</div>
+    </div>
+
     <!-- ============================================================ -->
     <h2>Calendars</h2>
 
@@ -463,6 +525,49 @@ Daily standup  2026-02-13 16:00:00Z  ...
 { "status": "ignored", "reason": "..." }</code></pre>
     </div>
 
+    <!-- ============================================================ -->
+    <h2>Discovery</h2>
+
+    <div class="endpoint" id="get-changelog">
+      <div class="method-path">
+        <span class="method get">GET</span>
+        <span class="path">/changelog</span>
+        <span class="auth-badge">No auth (optional Bearer)</span>
+      </div>
+      <p class="desc">Structured list of API changes with dates and docs links. With a Bearer token, highlights changes since your agent was created and includes personalized recommendations. Poll ~weekly to discover new features.</p>
+      <div class="label">Example</div>
+      <pre><code>curl -s https://${DOMAIN}/changelog \\
+  -H "Authorization: Bearer YOUR_API_KEY"</code></pre>
+      <div class="label">Response (authenticated)</div>
+      <pre><code>{
+  "description": "CalDave API changelog...",
+  "your_agent": { "agent_id": "agt_...", "created_at": "..." },
+  "changes_since_signup": [{ "date": "2026-02-14", "changes": [...] }],
+  "changes_since_signup_count": 2,
+  "changelog": [{ "date": "2026-02-08", "changes": [...] }],
+  "recommendations": [
+    { "action": "Name your agent", "why": "...", "how": "PATCH /agents ...", "docs": "..." }
+  ]
+}</code></pre>
+      <div class="note">The <code class="inline-code">recommendations</code> array includes actionable suggestions based on your agent state (e.g. name your agent, create a calendar, create an event). Only present when authenticated and there are suggestions.</div>
+    </div>
+
+    <div class="endpoint" id="post-man">
+      <div class="method-path">
+        <span class="method post">POST</span>
+        <span class="path">/man</span>
+        <span class="auth-badge">No auth (optional Bearer)</span>
+      </div>
+      <p class="desc">Machine-readable API manual. Returns all endpoints with curl examples and parameters. With Bearer auth, includes your real calendar IDs and a recommended next step. Use <code class="inline-code">?guide</code> for a compact onboarding overview.</p>
+      <div class="label">Example — full reference</div>
+      <pre><code>curl -s -X POST https://${DOMAIN}/man \\
+  -H "Authorization: Bearer YOUR_API_KEY"</code></pre>
+      <div class="label">Example — guided onboarding</div>
+      <pre><code>curl -s -X POST "https://${DOMAIN}/man?guide" \\
+  -H "Authorization: Bearer YOUR_API_KEY"</code></pre>
+      <div class="note">The <code class="inline-code">?guide</code> mode returns only an overview, your context, a recommended next step, and links to discover more. Ideal for first-time agent onboarding.</div>
+    </div>
+
     <!-- ============================================================ -->
     <h2>Quick Start</h2>
     <div class="endpoint">