@yottagraph-app/aether-instructions 1.1.2 → 1.1.4

package/commands/broadchurch_setup.md

@@ -158,6 +158,5 @@ gcloud projects describe $PROJECT_ID --format="value(projectId)" 2>&1
 >
 > - Create an agent in `agents/` and deploy with `/deploy_agent`
 > - Create an MCP server in `mcp-servers/` and deploy with `/deploy_mcp`
-> - Deploy your UI to Vercel with `/vercel_deploy`
 
 **If it fails:** Help the user troubleshoot the GCP authentication.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@yottagraph-app/aether-instructions",
-    "version": "1.1.2",
+    "version": "1.1.4",
     "description": "Cursor rules, commands, and skills for Aether development",
     "files": [
         "rules",

package/rules/agents.mdc

@@ -168,8 +168,9 @@ Once deployed, the agent is reachable through the Portal Gateway:
 ```
 Chat UI (pages/chat.vue)
   → POST NUXT_PUBLIC_GATEWAY_URL/api/agents/{tenantId}/{agentId}/query
-  → Portal Gateway proxies to Vertex AI Agent Engine
-  → Agent runs, returns response
+  → Portal Gateway proxies to Vertex AI Agent Engine (streamQuery)
+  → Agent runs (may invoke tools, make multiple LLM calls)
+  → Gateway collects the ADK event stream, extracts final text
   → Chat UI displays it
 ```
 
@@ -177,6 +178,126 @@ The gateway URL and tenant ID come from `broadchurch.yaml` (injected as
 `NUXT_PUBLIC_GATEWAY_URL` and `NUXT_PUBLIC_TENANT_ORG_ID`). The chat page
 discovers available agents from the Portal config endpoint.
 
+### Gateway Request
+
+```
+POST {NUXT_PUBLIC_GATEWAY_URL}/api/agents/{tenantId}/{agentId}/query
+Content-Type: application/json
+
+{ "message": "Summarize the latest 8-K filing", "session_id": "optional-session-id" }
+```
+
+Omit `session_id` on the first message — the gateway auto-creates one.
+
+### Gateway Response Format
+
+```json
+{
+  "output": "The agent's final text response",
+  "session_id": "session-abc-123",
+  "events": [ /* raw ADK event stream */ ]
+}
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `output` | `string \| any[]` | Usually the agent's final text. Falls back to the raw `events` array if the gateway couldn't extract text. |
+| `session_id` | `string` | Pass back on subsequent messages to continue the conversation. |
+| `events` | `any[]` | Full ADK event stream. Useful for debugging or building UIs that show intermediate agent steps. |
+
+**Important:** `output` is NOT always a string. When the agent's response
+involves complex tool chains, the gateway's server-side extraction may miss
+the text and return the raw events array instead. Always use
+`extractAgentText()` to parse `output` safely rather than treating it as a
+string directly.
+
+### ADK Event Stream Format
+
+The `events` array contains one object per step the agent took. Each event
+has `content.parts[]` where each part is one of:
+
+```json
+{ "text": "The agent's text response..." }
+{ "functionCall": { "name": "search", "args": { "q": "AAPL" } } }
+{ "functionResponse": { "name": "search", "response": { "results": [...] } } }
+```
+
+A typical stream for an agent that uses a tool:
+
+```json
+[
+  { "content": { "parts": [{ "functionCall": { "name": "search", "args": {"q": "AAPL 8-K"} } }], "role": "model" } },
+  { "content": { "parts": [{ "functionResponse": { "name": "search", "response": {"results": ["..."]} } }], "role": "tool" } },
+  { "content": { "parts": [{ "text": "Here is the summary of the 8-K filing..." }], "role": "model" } }
+]
+```
+
+The final text is the last `text` part that isn't in a `functionCall` or
+`functionResponse` event. Events may also arrive as JSON strings rather
+than objects — always handle both.
+
+### Parsing Agent Responses (Non-Streaming)
+
+For one-shot calls (server routes, background tasks) where streaming isn't
+needed, use the buffered `/query` endpoint with `extractAgentText`:
+
+```typescript
+import { extractAgentText } from '~/composables/useAgentChat';
+
+const response = await $fetch(url, { method: 'POST', body: { message } });
+const text = extractAgentText(response.output);
+```
+
+`extractAgentText` handles: plain strings, ADK event stream arrays (with
+JSON-string or object elements), single event objects, and several legacy
+Agent Engine response shapes. It skips `functionCall` / `functionResponse`
+events and returns the agent's final text.
+
+### Streaming Responses
+
+The gateway also exposes a streaming endpoint that returns Server-Sent
+Events as the agent executes. **The `useAgentChat` composable uses this by
+default** — it tries `/stream` first and falls back to `/query`
+automatically.
+
+```
+POST {NUXT_PUBLIC_GATEWAY_URL}/api/agents/{tenantId}/{agentId}/stream
+Content-Type: application/json
+
+{ "message": "Summarize the latest 8-K filing", "session_id": "optional" }
+```
+
+The response is an SSE stream with these event types:
+
+| Event | Data Shape | Description |
+|---|---|---|
+| `text` | `{ "text": "..." }` | Agent text output (replaces previous text) |
+| `function_call` | `{ "name": "...", "args": {...} }` | Agent is calling a tool |
+| `function_response` | `{ "name": "...", "response": {...} }` | Tool returned a result |
+| `error` | `{ "message": "..." }` | Error during processing |
+| `done` | `{ "session_id": "...", "text": "..." }` | Stream complete with final text |
+
+For custom agent UIs that need streaming, import `readSSE`:
+
+```typescript
+import { readSSE } from '~/composables/useAgentChat';
+
+const res = await fetch(streamUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ message: 'Hello' }),
+});
+
+for await (const { event, data } of readSSE(res)) {
+    if (event === 'text') console.log('Agent says:', data.text);
+    if (event === 'function_call') console.log('Calling:', data.name);
+    if (event === 'done') console.log('Session:', data.session_id);
+}
+```
+
+The `done` event always includes the final extracted text, so you don't
+need to track text deltas yourself.
+
 ## Agent Design Guidelines
 
 - Keep agents focused: one agent per domain or task type

package/rules/api.mdc

@@ -51,6 +51,57 @@ Types are also imported from the client:
 import type { NamedEntityReport, GetNEIDResponse } from '@yottagraph-app/elemental-api/client';
 ```
 
+### Client Method Quick Reference
+
+All methods return data directly and throw on non-2xx responses.
+
+**Entity search and lookup:**
+
+| Method | Signature | Purpose |
+|---|---|---|
+| `getNEID` | `(params: { entityName, maxResults?, includeNames? })` | Lookup entity by name |
+| `findEntities` | `(body: FindEntitiesBody)` | Expression-based search (see `find.md`) |
+| `getNamedEntityReport` | `(neid: string)` | Entity details (name, aliases, type) |
+| `getEntityDetails` | `(neid: string)` | Alias for entity reports |
+
+**Properties and schema:**
+
+| Method | Signature | Purpose |
+|---|---|---|
+| `getSchema` | `()` | All entity types (flavors) and properties (PIDs) |
+| `getPropertyValues` | `(body: { eids: string, pids: string })` | Property values (eids/pids are JSON-stringified arrays!) |
+| `summarizeProperty` | `(pid: number)` | Summary stats for a property |
+
+**Relationships and graph:**
+
+| Method | Signature | Purpose |
+|---|---|---|
+| `getLinkedEntities` | `(neid, params?: { entity_type?, link_type? })` | Linked entities (person/org/location only) |
+| `getLinks` | `(sourceNeid, targetNeid, params?)` | Links between two specific entities |
+| `getLinkCounts` | `(sourceNeid, targetNeid)` | Link counts between entities |
+| `getNeighborhood` | `(centerNeid, params?)` | Neighboring entities |
+| `getGraphLayout` | `(centerNeid, params?)` | Graph layout for visualization |
+
+**News, events, and sentiment:**
+
+| Method | Signature | Purpose |
+|---|---|---|
+| `getArticle` | `(artid: string)` | Article by ID |
+| `getArticleText` | `(artid: string)` | Article full text |
+| `getEvent` | `(eveid: string)` | Event by ID |
+| `getEventsForEntity` | `(params: { neid, startTime?, endTime? })` | Events involving an entity |
+| `getMentions` | `(params: { neid, startTime?, endTime? })` | Mention codes for entities |
+| `getMentionCounts` | `(params: { neid, ... })` | Bucketed mention counts |
+| `getNamedEntitySentiment` | `(neid: string)` | Sentiment for an entity |
+
+**Other:**
+
+| Method | Signature | Purpose |
+|---|---|---|
+| `getHealth` | `()` | Health check |
+| `getStatus` | `()` | Server status and capabilities |
+| `adaMessage` | `(body: AdaMessageBody)` | Ada AI chat |
+
 ## Discovery-First Pattern
 
 The knowledge graph contains many entity types and properties, and new datasets
@@ -81,17 +132,27 @@ knowledge of what's in the graph.
 
 ## API Gotchas
 
-> **WARNING -- `getSchema()` response nesting**: The generated TypeScript types
-> put `flavors` and `properties` at the top level, but the actual API response
-> nests them under a `schema` key. Using `response.properties` directly will
-> crash with `Cannot read properties of undefined`. Always use:
+### `getSchema()` response is nested — WILL crash if you don't handle it
+
+The generated TypeScript types suggest `response.properties` and
+`response.flavors` exist at the top level. **They don't.** The API nests
+them under `response.schema`. This mismatch between types and reality
+causes `Cannot read properties of undefined` every time.
 
 ```typescript
+// WRONG — will crash at runtime despite TypeScript compiling fine:
+const res = await client.getSchema();
+const props = res.properties; // undefined!
+
+// CORRECT — always access through .schema:
 const res = await client.getSchema();
 const properties = res.schema?.properties ?? (res as any).properties ?? [];
 const flavors = res.schema?.flavors ?? (res as any).flavors ?? [];
 ```
 
+The `(res as any).properties` fallback is there in case the API is ever
+fixed to match the types. Use this pattern every time.
+
 > **WARNING -- `getPropertyValues()` takes JSON-stringified arrays**: The `eids`
 > and `pids` parameters must be JSON-encoded strings, NOT native arrays. The
 > TypeScript type is `string`, not `string[]`. Passing a raw array will silently
@@ -139,6 +200,48 @@ See the **cookbook** rule for a full "Get filings for a company" recipe.
   (`POST /elemental/find`). Best for filtered searches (by type, property,
   relationship). See `find.md` for the expression language.
 
+## Common Entity Relationships
+
+The knowledge graph connects entities through relationship properties
+(`data_nindex` PIDs). These are the most common patterns:
+
+| From | PID | To | How to traverse |
+|---|---|---|---|
+| Organization | `filed` | Document (filings) | `getPropertyValues` with the `filed` PID on the org's NEID |
+| Organization | `employs` | Person | `getLinkedEntities` (person is a graph node type) |
+| Person | `employed_by` | Organization | `getLinkedEntities` (organization is a graph node type) |
+| Organization | `headquartered_in` | Location | `getLinkedEntities` (location is a graph node type) |
+| Any entity | `related_to` | Any entity | `getLinkedEntities` for person/org/location; `getPropertyValues` for others |
+
+**Key constraint:** `getLinkedEntities` only works for three target types:
+**person**, **organization**, **location**. For documents, filings,
+articles, financial instruments, and events, use `getPropertyValues` with
+the relationship PID. See the cookbook rule (recipe #7) for a full filings
+example.
+
+**Traversal pattern for non-graph-node types:**
+
+```typescript
+// 1. Get the PID for the relationship
+const schema = await client.getSchema();
+const pids = schema.schema?.properties ?? [];
+const filedPid = pids.find((p: any) => p.name === 'filed')?.pid;
+
+// 2. Get linked entity IDs via getPropertyValues
+const res = await client.getPropertyValues({
+    eids: JSON.stringify([orgNeid]),
+    pids: JSON.stringify([filedPid]),
+});
+
+// 3. Pad IDs to 20 chars to form valid NEIDs
+const docNeids = res.values.map((v: any) => String(v.value).padStart(20, '0'));
+
+// 4. Get details for each linked entity
+const reports = await Promise.all(
+    docNeids.map((neid: string) => client.getNamedEntityReport(neid)),
+);
+```
+
 ## Error Handling
 
 ```typescript

package/rules/architecture.mdc

@@ -133,9 +133,17 @@ Tenant-specific configuration generated during provisioning. Contains GCP projec
 
 ## Built-in Pages
 
-These pages ship with the template and can be kept, modified, or removed based on the app's needs:
-
-- `pages/chat.vue` -- Agent chat UI. Talks to deployed ADK agents through the Portal Gateway. Keep if the app uses AI agents.
-- `pages/mcp.vue` -- MCP Explorer. Browse and test MCP server tools. Keep if the app uses MCP servers.
-- `pages/entity-lookup.vue` -- Entity search tool. Useful for looking up NEIDs. Keep or remove based on the app.
+These pages ship with the template and can be kept, modified, or removed
+based on the app's needs:
+
+- `pages/chat.vue` -- Agent chat UI. Talks to deployed ADK agents through
+  the Portal Gateway with streaming support. Keep if the app uses AI agents.
+- `pages/mcp.vue` -- MCP Explorer. Browse and test MCP server tools. Keep
+  if the app uses MCP servers.
+- `pages/entity-lookup.vue` -- Entity search tool. Useful for looking up
+  NEIDs. Keep or remove based on the app.
+
+If any of these pages are missing from your project, your project may have
+been created from an older template version. Copy them from the latest
+aether-dev source or run `/update_instructions` to check for updates.
 

package/commands/vercel_deploy.md

@@ -1,278 +0,0 @@
-# Vercel Deploy
-
-Deploy the current state of the project to Vercel via Git integration.
-
-## Overview
-
-This command helps the user deploy their code to Vercel. It handles committing changes, choosing production vs. preview (branch) deployment, pushing to the right branch, and confirming the deployment succeeded.
-
-**Prerequisite:** The project must already be set up with Vercel (linked, env vars synced, etc.). If it hasn't been set up yet, redirect the user to `/vercel_setup`.
-
----
-
-## Step 1: Verify Vercel is Set Up
-
-Check that the project is linked to Vercel by checking whether `.vercel/project.json` exists (read the file or check the directory).
-
-**If the file does not exist:** The project hasn't been set up yet. Tell the user:
-
-> This project hasn't been connected to Vercel yet. Let's run the setup first.
-
-Then stop and redirect them to run `/vercel_setup`.
-
-Also verify there's at least one prior deployment:
-
-```bash
-npx vercel ls 2>&1
-```
-
-**If no deployments are listed:** Same as above — redirect to `/vercel_setup`.
-
-**If deployments exist:** Continue.
-
----
-
-## Step 2: Check for Uncommitted Changes
-
-```bash
-git status
-```
-
-**If the working tree is clean** (nothing to commit): Continue to Step 3.
-
-**If there are uncommitted changes:** Show the user what's changed:
-
-```bash
-git status --short
-```
-
-Then ask:
-
-```
-AskQuestion({
-  title: "Uncommitted Changes",
-  questions: [
-    {
-      id: "commit-changes",
-      prompt: "You have uncommitted changes. These need to be committed before deploying.\n\n[paste the git status output here]\n\nWould you like me to commit them now?",
-      options: [
-        { id: "commit", label: "Yes — commit all changes and continue" },
-        { id: "review", label: "Let me review first — I'll commit manually" }
-      ]
-    }
-  ]
-})
-```
-
-If the user selects "commit": Follow the commit workflow in `git-support.mdc` (format, stage, commit). Do not proceed to Step 3 with a failed commit.
-
-If the user selects "review": Stop and wait for them to come back after committing manually.
-
----
-
-## Step 3: Choose Deployment Target
-
-Determine the current branch and the main branch:
-
-```bash
-git branch --show-current
-git remote show origin | grep 'HEAD branch'
-```
-
-Then ask the user where they want to deploy:
-
-```
-AskQuestion({
-  title: "Deployment Target",
-  questions: [
-    {
-      id: "deploy-target",
-      prompt: "Where would you like to deploy?\n\nYou're currently on branch: [current-branch]",
-      options: [
-        { id: "production", label: "Production — deploy to main branch (live site)" },
-        { id: "preview", label: "Preview — deploy to a branch (staging/test URL)" }
-      ]
-    }
-  ]
-})
-```
-
-Then follow the appropriate path below.
-
----
-
-### Path A: Deploy to Production
-
-The user wants to deploy to the main branch.
-
-**If already on main:**
-
-```bash
-git push origin main 2>&1
-```
-
-**If the push is rejected:** Pull the latest changes first with `git pull --rebase origin main`, then try pushing again. If branch protection rules prevent direct pushes to main, the user will need to use the PR path instead.
-
-**If on a feature branch:**
-
-The user's changes need to get to main. Ask how:
-
-```
-AskQuestion({
-  title: "Merge to Main",
-  questions: [
-    {
-      id: "merge-strategy",
-      prompt: "You're on branch [current-branch]. To deploy to production, your changes need to be on main.\n\nHow would you like to proceed?",
-      options: [
-        { id: "merge", label: "Merge [current-branch] into main and push" },
-        { id: "pr", label: "Create a pull request instead (I'll merge it myself)" }
-      ]
-    }
-  ]
-})
-```
-
-If "merge":
-
-```bash
-git checkout main
-git pull origin main
-git merge [feature-branch] --no-edit
-git push origin main
-```
-
-If the merge has conflicts, stop and tell the user:
-
-> There are merge conflicts that need to be resolved manually. After resolving them, commit the merge and run this command again.
-
-**If the push is rejected:** Pull the latest changes with `git pull --rebase origin main` and try pushing again. If branch protection rules prevent direct pushes to main, the user will need to use the PR path instead.
-
-If "pr":
-
-First push the branch if needed:
-
-```bash
-git push -u origin [feature-branch]
-```
-
-Then create a PR:
-
-```bash
-gh pr create --title "Deploy [feature-branch] to production" --body "$(cat <<'EOF'
-[Summarize the actual changes — see below]
-EOF
-)"
-```
-
-Before creating the PR, analyze the commits on the branch (using `git log main..[branch] --oneline`) and draft a meaningful PR description summarizing the changes, rather than using a generic message.
-
-Return the PR URL and tell the user:
-
-> Pull request created: [PR URL]
->
-> Merge it on GitHub to trigger a production deployment. Vercel will auto-deploy when the merge lands on main.
-
-Then stop — the deployment will happen automatically when they merge.
-
----
-
-### Path B: Deploy to Preview (Branch)
-
-The user wants a preview deployment on a branch.
-
-**If already on a feature branch:**
-
-Push the current branch:
-
-```bash
-git push -u origin [current-branch] 2>&1
-```
-
-**If the push is rejected:** Pull the latest changes with `git pull --rebase origin [current-branch]` and try pushing again. If there are rebase conflicts, stop and let the user resolve them.
-
-**If on main:**
-
-The user needs a branch. Ask for a name:
-
-```
-AskQuestion({
-  title: "Branch Name",
-  questions: [
-    {
-      id: "branch-name",
-      prompt: "You're on main. To create a preview deployment, we need a branch.\n\nWhat would you like to call it? (e.g., 'dev', 'staging', 'leah/feature-x')",
-      options: [
-        { id: "dev", label: "dev" },
-        { id: "staging", label: "staging" },
-        { id: "custom", label: "I'll type a custom branch name" }
-      ]
-    }
-  ]
-})
-```
-
-If the user picks "custom", ask them to provide the branch name.
-
-Create and push the branch:
-
-```bash
-git checkout -b [branch-name]
-git push -u origin [branch-name] 2>&1
-```
-
----
-
-## Step 4: Confirm Deployment
-
-After pushing, Vercel's Git integration will automatically start a build. Monitor it:
-
-```bash
-sleep 5
-npx vercel ls 2>&1
-```
-
-Look for the latest deployment matching the push. It may show status as `● Building` initially.
-
-If the deployment is building, wait and poll:
-
-```bash
-sleep 15
-npx vercel ls 2>&1
-```
-
-Keep polling (with increasing intervals: 15s, 30s, 30s) until the status changes to `● Ready` or shows an error. If the build hasn't completed after ~5 minutes of polling, provide the Vercel dashboard link and suggest the user check the build logs there.
-
-**If status is `● Ready`:**
-
-Get the deployment URL from the output. Then verify static assets are served correctly:
-
-```bash
-curl -sI "https://<deployment-url>/_nuxt/<any-chunk>.js" | head -5
-```
-
-Confirm `content-type: application/javascript`.
-
-Present the result to the user:
-
-> Deployment successful!
->
-> **URL:** [deployment URL]
-> **Environment:** [Production / Preview]
-> **Branch:** [branch name]
->
-> [If production and custom domain exists]: Also available at: [custom domain URL]
-
-**If the build failed:**
-
-Check the logs:
-
-```bash
-npx vercel logs <deployment-url> 2>&1 | tail -30
-```
-
-Common failures:
-
-- **E401 npm install:** `NPM_TOKEN` not set for this environment. See `/vercel_setup` Step 1 (NPM Authentication).
-- **Build error:** Show the user the relevant log lines and help them debug.
-- **Missing env vars:** Env vars may not be set for the preview environment. See `/vercel_setup` Step 5 (Sync Environment Variables).

package/commands/vercel_setup.md

@@ -1,528 +0,0 @@
-# Vercel Setup
-
-Set up and sync this Aether project with Vercel for web deployment.
-
-## Overview
-
-This command walks through connecting an Aether project to Vercel and syncing environment variables. It assumes the user has already created a GitHub repository from the Aether template and wants to deploy it to Vercel.
-
-The Vercel connection itself (linking the GitHub repo to a Vercel project) must be done by the user through the Vercel dashboard. Once connected, this command handles everything else via the Vercel CLI.
-
----
-
-## Step 1: Check NPM Authentication for Private Packages
-
-This project depends on private `@lovelace-ai` packages from GitHub Packages. Both local installs and Vercel builds need a valid token. Setting this up first avoids build failures later.
-
-### Check `.npmrc`
-
-Read `.npmrc` in the project root. It should contain:
-
-```
-@lovelace-ai:registry=https://npm.pkg.github.com
-//npm.pkg.github.com/:_authToken=${NPM_TOKEN}
-```
-
-**If `.npmrc` is missing:** Create it with the content above.
-
-**If `.npmrc` has a hardcoded token** (a literal value like `_authToken=ghp_xxxx` instead of `${NPM_TOKEN}`): This shouldn't normally happen since `.npmrc` is committed to git with `${NPM_TOKEN}`. Stop and tell the user:
-
-> Your `.npmrc` has a hardcoded token instead of `${NPM_TOKEN}`. Please move the token value to your `NPM_TOKEN` environment variable, then replace the hardcoded value in `.npmrc` with `${NPM_TOKEN}`.
-
-Wait for the user to confirm before continuing.
-
-**If `.npmrc` already uses `${NPM_TOKEN}`:** Good, continue.
-
-### Ensure `NPM_TOKEN` is a valid PAT
-
-```bash
-echo $NPM_TOKEN
-```
-
-Check the token prefix:
-
-- `ghp_` — Classic PAT. Good, skip to **"Ensure `.npmrc` is committed"**.
-- `github_pat_` — Fine-grained PAT. Good, skip to **"Ensure `.npmrc` is committed"**.
-- `gho_` — **This is an OAuth token, NOT a PAT.** OAuth tokens are tied to a specific device/session and will fail on Vercel's build servers. Tell the user their current token value so they can save it if needed:
-
-    > Your current `NPM_TOKEN` is an OAuth token (`gho_...`), which won't work on Vercel. Here's the value in case you want to save it: `<the full gho_ token>`
-    >
-    > We need to replace it with a classic PAT (`ghp_`).
-
-    Check `~/.npmrc` — it may contain a `ghp_` classic PAT that can be reused. If found, use it as the new `NPM_TOKEN` and persist it (see below). If not, the user needs to create one — use the AskQuestion below.
-
-- **Empty** — The user needs a GitHub Personal Access Token. Check `~/.npmrc` for a usable `ghp_` token first. If found, use it and persist it (see below). If not, use the AskQuestion below.
-
-```
-AskQuestion({
-  title: "GitHub Token Required for Private Packages",
-  questions: [
-    {
-      id: "npm-token",
-      prompt: "This project needs a GitHub Personal Access Token (PAT) to install private @lovelace-ai packages.\n\nNote: OAuth tokens (gho_) won't work on Vercel — you need a classic PAT (ghp_).\n\nDo you already have one, or do you need to create one?",
-      options: [
-        { id: "have-token", label: "I have a classic PAT — I'll set it as NPM_TOKEN" },
-        { id: "need-token", label: "I need to create one" }
-      ]
-    }
-  ]
-})
-```
-
-If the user selects "need-token", guide them:
-
-> To create a GitHub token for npm packages:
->
-> 1. Go to https://github.com/settings/tokens
-> 2. Click **Generate new token** > **Generate new token (classic)**
-> 3. Give it a name like "Aether npm packages"
-> 4. Select the **read:packages** scope (that's all you need)
-> 5. Click **Generate token**
-> 6. Copy the token — you won't see it again
-
-### Persist `NPM_TOKEN` to the shell profile
-
-Once you have a valid PAT (from `~/.npmrc` or from the user), persist it. Detect the user's shell:
-
-```bash
-echo $SHELL
-```
-
-| `$SHELL`    | Profile file |
-| ----------- | ------------ |
-| `/bin/zsh`  | `~/.zshrc`   |
-| `/bin/bash` | `~/.bashrc`  |
-
-If the user's shell is something else (fish, etc.), tell them to set `NPM_TOKEN` as a persistent environment variable themselves and move on.
-
-For **zsh** or **bash**, add or update the export (replacing `<shell_rc>` with the profile filename from the table):
-
-```bash
-sed -i.bak '/^export NPM_TOKEN=/d' ~/.<shell_rc> && rm -f ~/.<shell_rc>.bak
-echo 'export NPM_TOKEN=<the_token>' >> ~/.<shell_rc>
-source ~/.<shell_rc>
-```
-
-Verify it took effect:
-
-```bash
-echo $NPM_TOKEN
-```
-
-### Ensure `.npmrc` is committed
-
-Check that `.npmrc` is NOT in `.gitignore`. Since it uses `${NPM_TOKEN}` (not a hardcoded secret), it's safe to commit and must be present in the repo for Vercel builds to work.
-
-If `.npmrc` appears in `.gitignore`, remove that line and replace it with a comment:
-
-```
-# .npmrc is committed — it uses ${NPM_TOKEN} env var, not a hardcoded token
-```
-
----
-
-## Step 2: Check Vercel CLI & Authentication
-
-The `vercel` package is included as a devDependency, so it should already be available after `npm install` / `npm run init`. Use `npx vercel` to invoke it.
-
-Verify it's available and the user is authenticated:
-
-```bash
-npx vercel whoami
-```
-
-**If the command succeeds** (prints a username): Continue to Step 3.
-
-**If the command fails:** Run the login command in the background so you can read its output:
-
-```bash
-npx vercel login
-```
-
-Run this as a background command (set `block_until_ms: 0`) so you can read its output while it waits. Then read the terminal output to find the one-time device code. The CLI will print a line like:
-
-```
-> Please visit the following URL to log in: https://vercel.com/device
-> Enter code: XXXX-XXXX
-```
-
-**IMPORTANT:** Extract the code from the terminal output and present it to the user in chat, along with the URL. For example:
-
-> Vercel needs you to authorize this device. Please:
->
-> 1. Open **https://vercel.com/device** in your browser (it may have opened automatically)
-> 2. Enter code: **XXXX-XXXX**
-> 3. Verify the location, IP, and request time, then approve
->
-> Let me know once you've approved it.
-
-If the code is not immediately visible in the terminal output, wait a couple of seconds and re-read the terminal file — the CLI may take a moment to contact Vercel's servers.
-
-After the user confirms they've approved, poll the terminal output until the login command completes. Then verify:
-
-```bash
-npx vercel whoami
-```
-
-**Stop here if authentication fails.** The user may need to:
-
-- Check that their browser opened and they completed the authorization
-- Ensure they have a Vercel account (sign up at https://vercel.com/signup)
-- Try running `npx vercel login` again
-
----
-
-## Step 3: Select the Correct Vercel Team
-
-The project should be deployed under the shared **Lovelace** team, not a personal account. Check and switch to the correct team:
-
-```bash
-npx vercel teams ls
-```
-
-Look for `lovelace-web` (team name: Lovelace) in the list. If the checkmark (✔) is not on `lovelace-web`, switch to it:
-
-```bash
-npx vercel teams switch lovelace-web
-```
-
-**If `lovelace-web` is not listed:** The user needs to be invited to the Lovelace team on Vercel. They should ask a team admin to add them at https://vercel.com/lovelace-web/settings/members.
-
-**Stop here if they can't access the team.** All subsequent steps assume the Lovelace team scope.
-
----
-
-## Step 4: Check Vercel Project Link
-
-Check if the project is already linked to Vercel by checking whether `.vercel/project.json` exists (read the file or check the directory).
-
-**If the file exists:** Read it and confirm the project link. Continue to Step 5.
-
-**If the file does not exist:** The project is not linked to Vercel yet. Tell the user:
-
-> Your project needs to be connected to Vercel before we can continue.
->
-> Please complete these steps:
->
-> 1. Go to [vercel.com/new](https://vercel.com/new)
-> 2. Click 'Import Git Repository'
-> 3. Select your GitHub repository (the one created from the Aether template)
-> 4. In the 'Configure Project' screen:
->     - Framework Preset should auto-detect as 'Nuxt.js'
->     - Leave Build Command as default
->     - Leave Output Directory as default
-> 5. Click 'Deploy'
->     - The first deploy may fail (missing env vars) — that's OK, we'll fix it next
->
-> Once the project is imported, come back here.
-
-Use the AskQuestion tool:
-
-```
-AskQuestion({
-  title: "Vercel Project Connection Required",
-  questions: [
-    {
-      id: "vercel-connected",
-      prompt: "Can you confirm that you imported the git repository to Vercel?",
-      options: [
-        { id: "done", label: "Done — I've imported the project to Vercel" },
-        { id: "help", label: "I need help with this step" }
-      ]
-    }
-  ]
-})
-```
-
-If the user selects "help", provide additional guidance:
-
-- They need a Vercel account at https://vercel.com/signup (free tier works fine)
-- They need to install the Vercel GitHub App when prompted during import
-- The repository must be the one they created from the Aether template, not the original template repo
-- If the repository is in their personal github account, they should be able to import it. However, if it is the team github account, or someone else's github account, they will probably need additional permissions.
-
-After the user confirms they've imported the project, link the local project:
-
-```bash
-npx vercel link --yes
-```
-
-This creates the `.vercel/project.json` file that connects the local directory to the Vercel project. If it prompts to select a project, choose the one that matches the repository name.
-
-**Note:** `vercel link` automatically appends `.vercel` to `.gitignore`, even if `.vercel/` is already listed. Check `.gitignore` after linking and remove the duplicate entry if one was added.
-
-Verify the link succeeded by confirming `.vercel/project.json` now exists.
-
-**Stop here if linking fails.** The user may need to re-run `npx vercel link` and select the correct project.
-
----
-
-## Step 5: Sync Environment Variables to Vercel
-
-Now that Vercel is authenticated and the project is linked, sync all required environment variables — starting with `NPM_TOKEN`, then the rest from `.env`.
-
-### Add `NPM_TOKEN` to Vercel
-
-Step 1 ensured `NPM_TOKEN` is valid locally. Now push it to Vercel so builds can use it too.
-
-**IMPORTANT:** Add `NPM_TOKEN` to BOTH the `production` AND `preview` environments. Production deploys come from the main branch; preview deploys come from all other branches. If you only set it for production, branch deploys will fail with E401 during `npm install`.
-
-Check if it already exists on Vercel:
-
-```bash
-npx vercel env ls production
-npx vercel env ls preview
-```
-
-Add it to both environments:
-
-```bash
-printf '%s' "$NPM_TOKEN" | npx vercel env add NPM_TOKEN production --force
-printf '%s' "$NPM_TOKEN" | npx vercel env add NPM_TOKEN preview --force
-```
-
-This uses the local `NPM_TOKEN` value directly. Verify it was added to both:
-
-```bash
-npx vercel env ls production
-npx vercel env ls preview
-```
-
-### Sync `.env` variables
-
-With `NPM_TOKEN` on Vercel, sync the remaining app-level configuration from `.env`.
-
-Read the local `.env` file and parse all non-commented, non-empty lines into KEY=VALUE pairs.
-
-**Variables to sync:** All variables defined in `.env` that are NOT commented out. This typically includes:
-
-- `NUXT_PUBLIC_APP_ID`
-- `NUXT_PUBLIC_APP_NAME`
-- `NUXT_PUBLIC_QUERY_SERVER_ADDRESS`
-- `NUXT_PUBLIC_AUTH0_CLIENT_ID`
-- `NUXT_PUBLIC_AUTH0_CLIENT_SECRET`
-- `NUXT_PUBLIC_USER_NAME`
-
-**Variables to skip:** Do NOT sync these to Vercel:
-
-- Commented-out lines (starting with `#`)
-- Variables with empty values (e.g., `NUXT_PUBLIC_USER_NAME=`, `NUXT_PUBLIC_QUERY_SERVER_ADDRESS=`)
-    > **Why skip empty values?** Nuxt's runtime config defaults them to empty strings already.
-    > The Vercel CLI cannot store truly empty values — it either prompts interactively or
-    > requires a non-empty string. Using a space or placeholder causes bugs. For example,
-    > a space in `NUXT_PUBLIC_USER_NAME` bypasses Auth0 login entirely.
-
-### Sync Process
-
-**IMPORTANT:** Sync env vars to BOTH `production` and `preview` environments. Production is used for main branch deploys; preview is used for all other branch deploys. Missing env vars in preview will cause branch builds to fail or the app to misbehave.
-
-For each variable to sync, push it to Vercel for **both** environments. Use the following pattern to avoid interactive prompts:
-
-```bash
-printf '%s' "VALUE" | npx vercel env add VAR_NAME production --force
-printf '%s' "VALUE" | npx vercel env add VAR_NAME preview --force
-```
-
-**IMPORTANT:** Use `printf '%s'` — NOT `echo`. `echo` appends a trailing newline to the value, which gets stored as part of the env var and causes runtime bugs (e.g., Auth0 rejecting a client ID with `\n` appended).
-
-**Note on `--force`:** This flag overwrites existing values without prompting. This is safe for syncing because we want local values to be the source of truth.
-
-If a variable has a value with spaces or special characters (like `NUXT_PUBLIC_APP_NAME`), the printf/pipe approach handles this correctly.
-
-**IMPORTANT:** Strip surrounding quotes from `.env` values before piping. If `.env` has `NUXT_PUBLIC_APP_NAME="Aether Vercel Demo"`, pipe `Aether Vercel Demo` (without the `"` characters). Vercel stores the value literally — quotes included.
-
-### Sensitive Variables Warning
-
-Before syncing, warn the user about sensitive values:
-
-> **Heads up:** The following sensitive values will be synced to Vercel:
->
-> - `NUXT_PUBLIC_AUTH0_CLIENT_SECRET` — Note: this is in `NUXT_PUBLIC_` which means it's exposed to the browser. Consider moving it to a server-only config in the future.
->
-> Vercel encrypts environment variables at rest and in transit.
-
-### After Syncing
-
-Confirm the sync by listing the variables:
-
-```bash
-npx vercel env ls production
-```
-
-Display the list to the user so they can verify.
-
----
-
-## Step 6: Trigger a Production Deployment
-
-After environment variables are synced, the existing deployment (if any) won't have them yet. Trigger a new production build:
-
-```bash
-npx vercel --prod --yes
-```
-
-This builds and deploys the app using the CLI. Alternatively, if the user prefers to use Git integration for deploys:
-
-> Your environment variables are synced. To trigger a deploy with the new variables, you can either:
->
-> 1. Push a commit to your `main` branch (Vercel will auto-deploy via Git integration)
-> 2. Go to the Vercel dashboard and click "Redeploy" on the latest deployment
-
-**If the deploy fails:** Check `npx vercel logs <deployment-url>` and refer to the Troubleshooting section. The most common cause is missing environment variables — re-run Step 5 if needed.
-
----
-
-## Step 7: Configure Custom Domain
-
-After the first successful deploy, add a custom domain under `.yottagraph.app`.
-
-First, determine the subdomain. Read the repository name from the git remote to use as a suggested default, then ask the user:
-
-```bash
-git remote get-url origin
-```
-
-Extract the repo name (e.g., `aether_vercel_demo` from the URL), convert underscores to hyphens for a cleaner subdomain (e.g., `aether-vercel-demo`), and present it as a suggestion.
-
-Use the AskQuestion tool with a text-like prompt:
-
-```
-AskQuestion({
-  title: "Custom Domain",
-  questions: [
-    {
-      id: "subdomain",
-      prompt: "Choose a subdomain for your app.\n\nYour app will be available at: <subdomain>.yottagraph.app\n\nSuggested based on your repo name: [suggested-name]",
-      options: [
-        { id: "suggested", label: "[suggested-name]" },
-        { id: "other", label: "Other" }
-      ]
-    }
-  ]
-})
-```
-
-If the user selects "other", ask them to type just the subdomain they'd like (not the full domain). Confirm the full URL (`<their-choice>.yottagraph.app`) before proceeding. Always append `.yottagraph.app` to whatever the user provides.
-
-Check what domains are already configured:
-
-```bash
-npx vercel domains ls 2>&1
-```
-
-Add the custom domain:
-
-```bash
-npx vercel domains add <subdomain>.yottagraph.app
-```
-
-**If the domain add succeeds:** Vercel will automatically provision a TLS certificate. The domain should be active within a few minutes.
-
-**If it prompts for DNS configuration:** The `.yottagraph.app` domain must have a wildcard CNAME or individual CNAME record pointing to `cname.vercel-dns.com`. If DNS is already configured for `*.yottagraph.app`, new subdomains should work automatically.
-
-**If it fails with a permission error:** The user may need to verify domain ownership. Domain verification is typically done once per team — if another project in the Lovelace team already uses `.yottagraph.app`, new subdomains should be automatically trusted.
-
-After adding, verify the domain is assigned:
-
-```bash
-npx vercel domains ls 2>&1
-```
-
----
-
-## Step 8: Verify Deployment
-
-After the deploy completes, Vercel will output a production URL (e.g., `https://project-name.vercel.app`). **Do not show this URL to the user.** Always use the custom domain chosen in Step 7 (`<subdomain>.yottagraph.app`) when referring to the deployment.
-
-### Verify static assets are served correctly
-
-Before opening the app, confirm that `_nuxt/` static files are being served with the correct MIME type. Use the custom domain for verification:
-
-```bash
-curl -sI "https://<subdomain>.yottagraph.app/_nuxt/<any-chunk>.js"
-```
-
-Look for `content-type: application/javascript`. If it returns `text/html` instead, the static file routing is broken — the Nuxt serverless function is catching `_nuxt/` requests and serving the SPA template. This usually means `nitro.output.publicDir` is overriding the Vercel preset's output paths. See the troubleshooting section below.
-
-### Verify the app loads
-
-Open `https://<subdomain>.yottagraph.app` and check:
-
-1. The app loads (not a blank page or build error)
-2. The navigation sidebar appears
-3. If Auth0 is configured, the login flow works
-
-**If the app shows a blank page:**
-
-- First check the static asset verification above — a MIME type mismatch is the most common cause
-- Check the Vercel build logs: `npx vercel logs <deployment-url>`
-- Common issue: missing environment variables or build errors
-
-**If Auth0 login fails:**
-Instruct the user:
-
-> Your custom domain needs to be registered as an allowed callback in Auth0.
->
-> 1. Go to https://manage.auth0.com/
-> 2. Navigate to Applications > Your Application > Settings
-> 3. Add your custom domain to these fields:
->     - **Allowed Callback URLs:** `https://<subdomain>.yottagraph.app/api/auth/callback`
->     - **Allowed Logout URLs:** `https://<subdomain>.yottagraph.app`
->     - **Allowed Web Origins:** `https://<subdomain>.yottagraph.app`
-> 4. Save changes
-
----
-
-## Step 9: Summary
-
-After completing all steps, provide the user with a summary:
-
-```
-Vercel Setup Complete!
-
-  Project:    [project name from .vercel/project.json]
-  URL:        https://[subdomain].yottagraph.app
-  Dashboard:  https://vercel.com/[org]/[project]
-
-Environment variables synced:
-  - NPM_TOKEN
-  - NUXT_PUBLIC_APP_ID
-  - NUXT_PUBLIC_APP_NAME
-  - [... list all synced vars]
-
-Next steps:
-  - Push code changes to main branch — Vercel will auto-deploy
-  - If using Auth0: add your custom domain as an allowed callback (see the Verify Deployment step)
-```
-
----
-
-## Troubleshooting
-
-### `vercel link` fails or selects the wrong project
-
-Run `npx vercel link` again interactively (without `--yes`) and manually select the correct project from the list.
-
-### Environment variable sync fails
-
-If `npx vercel env add` fails with a permission error, the user may need to verify they have the correct Vercel team/scope selected:
-
-```bash
-npx vercel whoami
-npx vercel teams ls
-npx vercel link --yes
-```
-
-### Build fails on Vercel
-
-Check build logs:
-
-```bash
-npx vercel logs <deployment-url>
-```
-
-Common causes:
-
-- **Missing npm packages (E401 Unauthorized):** Private `@lovelace-ai` packages need `NPM_TOKEN` configured. See Step 1 — ensure `.npmrc` uses `${NPM_TOKEN}`, the token is set as a Vercel env var, and `.npmrc` is committed (not gitignored).
-- **Orval/API spec errors:** If the build fails during `prebuild` (orval code generation), ensure the API spec file exists or remove the orval dependency if unused.
-- **Memory issues:** The build command includes `--max-old-space-size=8192`. Vercel's free tier may have lower limits. Try removing this from the build command in `package.json` if builds OOM.