Search: rename plan docs (remove date prefix), slim down api-design, add roadmap

Author: gibrown

projects/packages/search/docs/plans/2026-04-21-search-ai-answers-api-design.md

@@ -6,23 +6,23 @@ A checklist to verify your local environment can run tests and test the AI Answe
 
 ## 1. Prerequisites
 
-- [ ] Docker Desktop is installed and running (`docker info` returns no error)
-- [ ] `jetpack` CLI is installed and on PATH:
+- [x ] Docker Desktop is installed and running (`docker info` returns no error)
+- [x ] `jetpack` CLI is installed and on PATH:
   ```bash
   jetpack --version
   # If missing: npm install -g @automattic/jetpack-cli  (or pnpm add -g)
   ```
-- [ ] Node and pnpm are available:
+- [x ] Node and pnpm are available:
   ```bash
   node --version   # 20+
   pnpm --version   # 9+
   ```
-- [ ] PHP and Composer are available:
+- [x ] PHP and Composer are available:
   ```bash
   php --version    # 8.0+
   composer --version
   ```
-- [ ] You're on the right branch:
+- [x ] You're on the right branch:
   ```bash
   git branch       # should be jps3-answers-plan
   ```
@@ -31,7 +31,7 @@ A checklist to verify your local environment can run tests and test the AI Answe
 
 ## 2. Install Monorepo Dependencies
 
-- [ ] Install all JS and PHP dependencies from the monorepo root:
+- [x ] Install all JS and PHP dependencies from the monorepo root:
   ```bash
   pnpm install
   composer install
@@ -44,19 +44,19 @@ A checklist to verify your local environment can run tests and test the AI Answe
 
 The PHP unit tests for the Search and Sync packages use WorDBless (no WordPress needed) and run locally without Docker.
 
-- [ ] Run Search package PHP tests:
+- [x ] Run Search package PHP tests:
   ```bash
   jetpack test php packages/search -v
   ```
   Expected: all tests pass (including `AI_Answers_Test` once Task 1 is implemented).
 
-- [ ] Run Sync package PHP tests:
+- [x ] Run Sync package PHP tests:
   ```bash
   jetpack test php packages/sync -v
   ```
   Expected: all tests pass (including the CPT sync tests once Task 2 is implemented).
 
-- [ ] Run Search package JS tests:
+- [x ] Run Search package JS tests:
   ```bash
   cd projects/packages/search
   pnpm test-scripts
@@ -69,7 +69,7 @@ The PHP unit tests for the Search and Sync packages use WorDBless (no WordPress
 
 Build is required before the Docker site can serve the updated JS bundle.
 
-- [ ] Build all Search JS bundles:
+- [x ] Build all Search JS bundles:
   ```bash
   cd projects/packages/search
   pnpm build
@@ -86,26 +86,26 @@ Build is required before the Docker site can serve the updated JS bundle.
 
 ## 5. Start Docker WordPress Environment
 
-- [ ] Start containers (first time or after `jetpack docker clean`):
+- [x ] Start containers (first time or after `jetpack docker clean`):
   ```bash
   jetpack docker up -d
   jetpack docker install
   ```
   WordPress is now at [http://localhost](http://localhost).  
   Default credentials: `jp_docker_acct` / `jp_docker_pass`
 
-- [ ] If containers were already installed previously, just start them:
+- [x ] If containers were already installed previously, just start them:
   ```bash
   jetpack docker up -d
   ```
 
-- [ ] Verify WordPress is reachable:
+- [x ] Verify WordPress is reachable:
   ```bash
   open http://localhost/wp-admin
   ```
   You should see the WP login page.
 
-- [ ] Verify Jetpack plugin is active (it's auto-linked from the monorepo):
+- [x ] Verify Jetpack plugin is active (it's auto-linked from the monorepo):
   ```bash
   jetpack docker wp plugin list | grep jetpack
   ```

…/plans/2026-04-21-local-testing-setup.md …search/docs/plans/local-testing-setup.mdprojects/packages/search/docs/plans/2026-04-21-local-testing-setup.md renamed to projects/packages/search/docs/plans/local-testing-setup.md projects/packages/search/docs/plans/2026-04-21-local-testing-setup.md renamed to projects/packages/search/docs/plans/local-testing-setup.md

@@ -0,0 +1,70 @@
+# Jetpack Search AI Answers — wpcom API
+
+## Endpoint
+
+```
+POST /wpcom/v2/ai/agent/jetpack-search-answers
+Authorization: Bearer {jwt-or-hmac-token}
+Accept: text/event-stream
+Content-Type: application/json
+```
+
+## Authentication
+
+Two auth paths:
+
+**Anonymous site visitors**: A site-level hourly HMAC token generated server-side in PHP and embedded in `JetpackInstantSearchOptions.aiAnswersToken`:
+
+```
+hash_hmac('sha256', 'search-answers:' . $site_id . ':' . floor(time()/3600), $blog_token_secret)
+```
+
+Rotates hourly; wpcom accepts both the current and previous hour's token to handle clock skew.
+
+**Logged-in users**: Standard Jetpack AI JWT from `/jetpack/v4/jetpack-ai-jwt`.
+
+## Request Format
+
+JSON-RPC 2.0 with `message/stream` method. The search query goes in the `text` part; site context (site ID, active filters, locale) goes in the `data` part:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "req-1",
+  "method": "message/stream",
+  "params": {
+    "message": {
+      "role": "user",
+      "parts": [
+        { "type": "text", "text": "how do I reset my password" },
+        {
+          "type": "data",
+          "data": {
+            "clientContext": {
+              "selectedSiteId": 12345,
+              "filters": { "post_type": ["post", "page"], "category": [] },
+              "locale": "en"
+            }
+          },
+          "metadata": {}
+        }
+      ],
+      "kind": "message",
+      "messageId": "msg-1"
+    }
+  },
+  "tokenStreaming": true
+}
+```
+
+## SSE Response Events
+
+| Event   | Payload | Description |
+|---------|---------|-------------|
+| `chunk` | `{"type":"chunk","text":"…"}` | Answer tokens, appended as they arrive |
+| `done`  | `{"type":"done","citations":[{"title":"…","url":"…","excerpt":"…"}]}` | Stream complete; citations as structured list |
+| `error` | `{"type":"error","code":"quota_exceeded","message":"…"}` | Terminal error; overlay hides AI panel |
+
+## Quota
+
+500 requests per calendar month per site (all plans). Returns `error` with `code: quota_exceeded` when exceeded; overlay falls back to standard search results.

projects/packages/search/docs/plans/search-ai-answers-api-design.md

@@ -7,7 +7,7 @@
 
 The WordPress plugin side of Jetpack Search AI Answers adds two custom post types for site-owner customization, syncs them to wpcom, embeds the auth token for anonymous visitors in the search overlay options, connects the overlay to the wpcom streaming endpoint, and provides an admin UI for managing search behavior and topics.
 
-The companion spec for the wpcom API side is `2026-04-21-search-ai-answers-api-design.md`.
+The companion spec for the wpcom API side is `search-ai-answers-api-design.md`.
 
 ## Custom Post Types