@yottagraph-app/aether-instructions 1.1.48 → 1.1.50

package/AGENTS.md

@@ -8,11 +8,11 @@
 
 **Data:** This app runs on the Lovelace platform -- entities, news, filings, sentiment, relationships, events. See [`data.md`](.agents/skills/aether/data.md) in the `aether` skill for access patterns and gotchas. Additional skill docs: `.agents/skills/data-model/` (entity types, properties, relationships; `SKILL.md` first), `.agents/skills/elemental-mcp-patterns/` (MCP response shapes, property type handling, Python patterns for agent tools). Do NOT call external APIs for data the platform provides.
 
-**Storage:** KV (Upstash Redis) for preferences and lightweight state via `Pref<T>` from `usePrefsStore()`. Neon Postgres for relational data if connected (see [`storage.md`](.agents/skills/aether/storage.md) in the `aether` skill).
+**Storage:** KV (Upstash Redis) for preferences and lightweight state via `Pref<T>` from `usePrefsStore()`. Neon Postgres for relational data if connected (see [`storage.md`](.agents/skills/aether/storage.md) in the `aether` skill). BigQuery for analytical/warehouse data when configured — go through `server/utils/bigquery.ts` (which proxies the Broadchurch Portal gateway), never `@google-cloud/bigquery` or a pasted service-account key. See [`bigquery.md`](.agents/skills/aether/bigquery.md) in the `aether` skill.
 
 **Source of truth:** `DESIGN.md` -- read before starting work, update when changing features. The starter UI is placeholder -- replace freely. Feature docs in `design/` for implementation planning.
 
-**Git:** Commit meaningful units of work. Run `npm run format` before commit. Message format: `[Agent commit] {summary}`. Push directly to main — do NOT create PRs or feature branches.
+**Git:** Commit meaningful units of work. Run `npm run format` before commit. Message format: `[Agent commit] {summary}`. Push directly to `main` with `git push origin main` — do NOT create PRs, do NOT run `gh pr create`, and do NOT use feature branches. Tenant `main` is not protected; Vercel auto-deploys on push to `main`, and that's how the app gets live. (This is the opposite of the `aether-dev` repo, which IS PR-only — do not import that habit.)
 
 **First action for a new project:** Run `/build_my_app`.
 

package/commands/build_my_app.md

@@ -112,6 +112,7 @@ Key capabilities:
 - **Query Server / Elemental API** -- the primary data source. Use `useElementalClient()` from `@yottagraph-app/elemental-api/client`. See [`data.md`](../skills/aether/data.md) in the `aether` skill.
 - **KV storage** -- always available for preferences and lightweight data (see [`pref.md`](../skills/aether/pref.md) in the `aether` skill)
 - **Neon Postgres** -- may be available for relational data; see [`storage.md`](../skills/aether/storage.md) in the `aether` skill for how to check and how to use it
+- **BigQuery** -- may be available for analytical / warehouse data via the portal gateway. **If the brief mentions BigQuery, analytics, a warehouse, dashboards over event data, or anything in that family, read [`bigquery.md`](../skills/aether/bigquery.md) in the `aether` skill BEFORE writing any code.** A pre-built `server/utils/bigquery.ts` helper is already scaffolded — do NOT add `@google-cloud/bigquery` to `package.json` and do NOT ask the user to paste a service-account key. The build will fail if you try (a prebuild guard catches it).
 - **AI agent chat** -- use the `useAgentChat` composable to build a chat UI for deployed agents
 - **MCP servers** -- Lovelace MCP servers may be available (check `.agents/mcp.json`)
 - **Components** -- Vuetify 3 component library is available
@@ -228,16 +229,24 @@ git add -A
 git commit -m "[Agent commit] Initial app build from project brief"
 ```
 
-**Push directly to main.** Vercel auto-deploys on push to main, so this
-gets the app live immediately. Do NOT try to create a pull request via
-`gh pr create` — in Cursor Cloud environments, the GitHub integration
-token lacks PR permissions (known Cursor issue). Pushing to main is the
-correct workflow.
+**Push directly to main. Do NOT create a pull request or a feature branch.**
+
+Vercel auto-deploys on push to `main`, which is how this project gets
+live. Creating a PR blocks that auto-deploy and breaks the smooth
+first-run experience the user is expecting from the wizard. The `main`
+branch on tenant repos is **not** protected — `git push origin main`
+will succeed. Tenant repos follow a different policy than the upstream
+`aether-dev` template (which IS PR-only) — do not import that habit.
 
 ```bash
 git push origin main
 ```
 
+Specifically: do NOT run `gh pr create`, do NOT create a feature
+branch, and do NOT push to anything other than `main`. If a push to
+`main` fails because of a real permission issue (not branch
+protection), report the exact error rather than falling back to a PR.
+
 If running locally (not in Cursor Cloud), the user may prefer a PR-based
 workflow — ask before pushing directly to main in that case.
 

package/commands/deploy_job.md

@@ -0,0 +1,227 @@
+# Deploy Compute Job
+
+Deploy a Cloud Run Job from the `jobs/` directory via the Broadchurch Portal.
+
+## Overview
+
+A "compute job" is a containerized Python (or any-language) entrypoint
+that runs on Google Cloud Run Jobs. Use it for:
+
+- **Cron jobs** (set `schedule:` in `job.yaml` — Cloud Scheduler is wired up automatically)
+- **Event-triggered batch work** (HTTP-triggered from your Vercel app or an Agent Engine tool)
+- **Heavy compute** (entity enrichment, scoring, ETL, exports, aggregations)
+- **Workflow steps** (called from a Cloud Workflow definition under `workflows/`)
+
+This command triggers a Cloud Build → Cloud Run Job deploy through
+the Portal. No local GCP credentials needed.
+
+The job must live in `jobs/<name>/` with at minimum:
+
+```
+jobs/<name>/
+├── main.py             # Entrypoint (or any executable; see Dockerfile)
+├── requirements.txt    # Python deps (only required if no custom Dockerfile)
+├── job.yaml            # Manifest: resources, schedule, env
+└── Dockerfile          # Optional — auto-generated if missing
+```
+
+**Prerequisite:** The project must have a valid `broadchurch.yaml`
+(created during provisioning).
+
+---
+
+## Step 1: Read Configuration
+
+Read `broadchurch.yaml` from the project root.
+
+```bash
+cat broadchurch.yaml
+```
+
+**If the file does not exist:**
+
+> This project hasn't been provisioned yet. Create it in the Broadchurch Portal first.
+
+Stop here.
+
+Extract these values:
+
+- `tenant.org_id` (tenant org ID)
+- `gateway.url` (Portal Gateway URL)
+
+---
+
+## Step 2: Discover Jobs
+
+List the directories under `jobs/`:
+
+```bash
+ls -d jobs/*/
+```
+
+**If no directories exist:**
+
+> No jobs found. Create one by making a directory under `jobs/` with the structure above.
+> See `docs/COMPUTE_JOBS.md` for guidance, or copy `jobs/example_job/` as a starting point.
+
+Stop here.
+
+**Skip `example_job`** — this is a template placeholder and should
+never be deployed. Filter it out before proceeding.
+
+**If multiple jobs remain:** Deploy all of them. If called interactively
+(not from `/build_my_app`), ask the user which one to deploy.
+
+**If only one job remains:** Proceed with it — no confirmation needed.
+
+**Important:** Job directory names should use underscores; the deploy
+workflow translates them to Cloud Run-friendly hyphens automatically.
+
+---
+
+## Step 3: Validate Job Structure
+
+For the selected job directory, verify the required files exist:
+
+```bash
+ls jobs/<name>/main.py jobs/<name>/job.yaml
+```
+
+If `Dockerfile` exists, the deploy uses it as-is. If not, the deploy
+auto-generates a Python 3.12 Dockerfile that runs `python main.py`.
+
+If using the auto-Dockerfile, `requirements.txt` must also exist:
+
+```bash
+ls jobs/<name>/requirements.txt 2>/dev/null
+```
+
+Validate the manifest is well-formed:
+
+```bash
+yq -e '.name // ""' jobs/<name>/job.yaml >/dev/null
+```
+
+---
+
+## Step 4: Ensure Code is Pushed
+
+The deployment workflow runs on the code in the GitHub repo, not the
+local working directory:
+
+```bash
+git status
+```
+
+**If there are uncommitted changes in `jobs/<name>/`:**
+
+> Your job code has local changes that aren't pushed yet. The
+> deployment will use the version on GitHub. Would you like me to
+> commit and push first?
+
+If yes, commit and push. If no, warn them and continue.
+
+---
+
+## Step 5: Trigger Deployment
+
+Call the Portal API to trigger the deploy workflow:
+
+```bash
+curl -sf -X POST "<GATEWAY_URL>/api/projects/<ORG_ID>/deploy" \
+  -H "Content-Type: application/json" \
+  -d '{"type": "job", "name": "<JOB_NAME>"}'
+```
+
+**If this fails with 404:** The job directory may not exist on GitHub
+yet. Push your code first.
+
+**If this succeeds:** The Portal has triggered the `deploy-job.yml`
+GitHub Actions workflow.
+
+---
+
+## Step 6: Monitor Progress
+
+> Deployment triggered! The compute job is being deployed via GitHub Actions.
+>
+> - **Job:** <name>
+> - **Workflow:** deploy-job.yml
+>
+> This typically takes 2-5 minutes (container build + Cloud Run Job create/update).
+> You can monitor progress:
+>
+> - In the Broadchurch Portal under your project's "Jobs" tab
+> - On GitHub: `https://github.com/<REPO>/actions`
+>
+> Once complete:
+>
+> - The job is callable via the Portal "Run now" button
+> - If `schedule:` is set in `job.yaml`, Cloud Scheduler will trigger it automatically
+> - Run history is visible in the Portal's "Jobs" tab
+
+---
+
+## Step 7: (Optional) Trigger a Test Run
+
+After deployment, trigger an ad-hoc run to verify the job works:
+
+```bash
+curl -sf -X POST "<GATEWAY_URL>/api/projects/<ORG_ID>/jobs/<JOB_NAME>/run" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+Then poll for results:
+
+```bash
+curl -sf "<GATEWAY_URL>/api/projects/<ORG_ID>/jobs/<JOB_NAME>/runs" | jq '.runs[0]'
+```
+
+Each run has a `status` field. Terminal statuses are: `Succeeded`,
+`Failed`, `Cancelled`.
+
+---
+
+## Troubleshooting
+
+### Build fails
+
+Check the GitHub Actions logs for the `Deploy Compute Job` workflow.
+Common issues:
+
+- **"requirements.txt" errors**: list every Python dep your `main.py` imports.
+- **Custom Dockerfile**: ensure the `CMD` actually runs your entrypoint.
+- **Memory/CPU mismatch**: Cloud Run Jobs require 1 vCPU per 4 GiB memory minimum (see Google Cloud docs).
+
+### Job times out
+
+Increase `task_timeout` in `job.yaml`. Cloud Run Jobs supports up to 24
+hours per task. For longer-running work, split into shards
+(`task_count: N` + `parallelism: N`) or escalate to GCP Batch.
+
+### Schedule doesn't fire
+
+Cloud Scheduler entries are named `job-<name>`. Check in the Cloud
+Console (Cloud Scheduler → us-central1) and verify:
+
+- The cron expression is valid
+- The OAuth service account email matches the tenant SA
+- The target URL points at the Cloud Run Job's `:run` endpoint
+
+### Need to update an existing job
+
+Just run `/deploy_job` again. It will rebuild the container, update
+the Cloud Run Job in place, and reconcile the Cloud Scheduler entry
+to match the current `job.yaml`.
+
+### Want to delete a job
+
+Delete via the Portal "Jobs" tab, or:
+
+```bash
+curl -sf -X DELETE "<GATEWAY_URL>/api/projects/<ORG_ID>/jobs/<JOB_NAME>"
+```
+
+This removes the Cloud Run Job, its Cloud Scheduler entry, and the
+Portal's job registration.

package/commands/deploy_workflow.md

@@ -0,0 +1,189 @@
+# Deploy Cloud Workflow
+
+Deploy a Cloud Workflow definition from the `workflows/` directory via
+the Broadchurch Portal.
+
+## Overview
+
+A Cloud Workflow orchestrates one or more compute jobs. It's the
+declarative DAG layer on top of the job runtime — useful for:
+
+- **Multi-step pipelines** ("for each entity: enrich, score, write")
+- **Fan-out / fan-in** patterns (parallel jobs that converge)
+- **Retry / error-branch logic** managed by the workflow runner, not the jobs
+- **Scheduled multi-step orchestration** (set `schedule:` in `manifest.yaml`)
+
+Cloud Workflows handles state, retries, fan-out, and observability.
+Your jobs stay stateless and idempotent — that's the design point.
+
+The workflow must live in `workflows/<name>/` with:
+
+```
+workflows/<name>/
+├── workflow.yaml       # Cloud Workflows DSL — the DAG itself
+└── manifest.yaml       # Name, schedule, log level, schedule input
+```
+
+**Prerequisite:** The project must have a valid `broadchurch.yaml`,
+and any jobs the workflow references must already be deployed via
+`/deploy_job`.
+
+---
+
+## Step 1: Read Configuration
+
+```bash
+cat broadchurch.yaml
+```
+
+**If the file does not exist:** Stop and tell the user the project
+isn't provisioned yet.
+
+Extract:
+
+- `tenant.org_id`
+- `gateway.url`
+
+---
+
+## Step 2: Discover Workflows
+
+```bash
+ls -d workflows/*/
+```
+
+**If no directories exist:** Suggest copying `workflows/example_workflow/`
+or creating a new one matching the structure above. Stop here.
+
+**Skip `example_workflow`** — it's a template placeholder. Filter it out.
+
+**If multiple remain:** Ask which to deploy.
+**If one remains:** Proceed without confirmation.
+
+---
+
+## Step 3: Validate Workflow Structure
+
+```bash
+ls workflows/<name>/workflow.yaml workflows/<name>/manifest.yaml
+```
+
+Validate `workflow.yaml` is syntactically valid:
+
+```bash
+yq -e '.main.steps' workflows/<name>/workflow.yaml >/dev/null
+```
+
+Validate `manifest.yaml` has a name:
+
+```bash
+yq -e '.name' workflows/<name>/manifest.yaml >/dev/null
+```
+
+---
+
+## Step 4: Ensure Referenced Jobs Are Deployed
+
+Cloud Workflows can't deploy referenced jobs for you. Check the
+workflow definition for any `googleapis.run.v1.namespaces.jobs.run`
+calls and verify those jobs exist:
+
+```bash
+grep -oP 'jobs/\K[a-z0-9-]+' workflows/<name>/workflow.yaml | sort -u
+```
+
+For each job name found, confirm it appears in the Portal:
+
+```bash
+curl -sf "<GATEWAY_URL>/api/projects/<ORG_ID>/jobs" | jq '.jobs[].job_name'
+```
+
+If a referenced job isn't deployed yet:
+
+> The workflow `<name>` references job `<job>` which isn't deployed.
+> Deploy it first with `/deploy_job <job>`.
+
+---
+
+## Step 5: Ensure Code is Pushed
+
+```bash
+git status
+```
+
+If there are uncommitted changes in `workflows/<name>/`, prompt to
+commit and push.
+
+---
+
+## Step 6: Trigger Deployment
+
+```bash
+curl -sf -X POST "<GATEWAY_URL>/api/projects/<ORG_ID>/deploy" \
+  -H "Content-Type: application/json" \
+  -d '{"type": "workflow", "name": "<WORKFLOW_NAME>"}'
+```
+
+**If 404:** The directory may not exist on GitHub yet. Push first.
+
+**If success:** The Portal has triggered the `deploy-workflow.yml`
+GitHub Actions workflow.
+
+---
+
+## Step 7: Monitor Progress
+
+> Workflow deployment triggered.
+>
+> - **Workflow:** <name>
+> - **GitHub Action:** deploy-workflow.yml
+>
+> Typically completes in under a minute (workflow definitions are tiny).
+>
+> Once deployed:
+>
+> - The workflow is executable via the Portal "Run now" button on the Workflows tab
+> - If `schedule:` is set, Cloud Scheduler invokes it automatically
+> - Execution history is in the Portal Workflows tab
+
+---
+
+## Step 8: (Optional) Trigger a Test Execution
+
+```bash
+curl -sf -X POST "<GATEWAY_URL>/api/projects/<ORG_ID>/workflows/<WORKFLOW_NAME>/run" \
+  -H "Content-Type: application/json" \
+  -d '{"input": {"limit": 10}}'
+```
+
+Then poll for the result:
+
+```bash
+curl -sf "<GATEWAY_URL>/api/projects/<ORG_ID>/workflows/<WORKFLOW_NAME>/executions" | jq '.executions[0]'
+```
+
+---
+
+## Troubleshooting
+
+### Workflow rejected with parsing errors
+
+Cloud Workflows YAML has strict syntax. Common gotchas:
+
+- Indentation must use spaces (no tabs)
+- `${...}` expressions must be quoted strings in YAML
+- `parallel for` requires `value` and `range` (or `in`) under `for:`
+- `args:` for `googleapis.run.v1.*` must include `name: namespaces/<project>/jobs/<job>`
+
+Reference: https://cloud.google.com/workflows/docs/reference/syntax
+
+### Workflow times out
+
+Cloud Workflows has a 1-year max duration but each step has its own
+limits. Long-running step calls (`googleapis.run.v1.namespaces.jobs.run`)
+should use `connector_params: {timeout: <seconds>}` to bound them.
+
+### Schedule doesn't fire
+
+Cloud Scheduler entries are named `workflow-<name>`. Verify in the
+Cloud Console.

package/package.json

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

package/skills/aether/SKILL.md

@@ -32,27 +32,28 @@ topics that apply.
 
 ## Files
 
-| File                                               | When to read                                                                                                                                                                                                                                                    |
-| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [architecture.md](architecture.md)                 | Project structure, navigation, server routes, agents, MCP. Read when adding pages, navigation, or server-side functionality.                                                                                                                                    |
-| [data.md](data.md)                                 | How this app reads platform data (clients, schema discovery, entity/news/filings access, common gotchas). Read when building any feature that fetches or displays platform data.                                                                                |
-| [cookbook.md](cookbook.md)                         | Copy-paste UI patterns for common pages: data table, form, chart, dialog, master-detail. For data-fetching recipes see `cookbook-data.md`.                                                                                                                      |
-| [cookbook-data.md](cookbook-data.md)               | Data-fetching UI recipes: entity search, news feed, filings, and related helpers. Read with `data.md` when building pages that display platform data.                                                                                                           |
-| [design.md](design.md)                             | `DESIGN.md` workflow, feature docs, starter-app-is-placeholder guidance. Read when starting work, planning features, or updating project design.                                                                                                                |
-| [ui.md](ui.md)                                     | Vue/Vuetify page templates, layouts, scrollable content, data tables, loading states. Applies when creating or editing page templates (`pages/**`, `components/**`).                                                                                            |
-| [pref.md](pref.md)                                 | User preferences and KV storage: `usePrefsStore`, `Pref<T>`, app namespacing (`NUXT_PUBLIC_APP_ID`). Read when working on settings persistence.                                                                                                                 |
-| [branding.md](branding.md)                         | Visual styling, colors, typography, theming, branding, UI appearance. Read when updating brand assets or theme code.                                                                                                                                            |
-| [server.md](server.md)                             | Nitro server-side API routes (`server/**`): file-based routing, event handlers, image proxy. Read when adding server routes. For storage backends see `storage.md`; for platform-data proxying see `server-data.md`.                                            |
-| [server-data.md](server-data.md)                   | Reading platform data from Nitro server routes (`server/**`). Read when a server route needs to fetch platform data on behalf of the app.                                                                                                                       |
-| [storage.md](storage.md)                           | Storage backends: KV (always on) vs Neon Postgres (if provisioned). Read when choosing persistence, wiring `getRedis()`/`getDb()`, creating tables, or handling missing credentials gracefully.                                                                 |
-| [agents.md](agents.md)                             | Conventions for developing ADK agents in `agents/**`. Read when writing or editing agent code.                                                                                                                                                                  |
-| [agents-data.md](agents-data.md)                   | How ADK agents access platform data (authentication, local testing env vars, mode-specific wiring). Read when an agent needs platform data (`agents/**`).                                                                                                       |
-| [mcp-servers.md](mcp-servers.md)                   | Conventions for developing MCP servers in `mcp-servers/**`. Read when writing or editing FastMCP servers.                                                                                                                                                       |
-| [deployment.md](deployment.md)                     | App, agent, and MCP server deployment targets (Vercel, Vertex AI Agent Engine, Cloud Run). Read when pushing to main, running `/deploy_agent` or `/deploy_mcp`, or explaining how code reaches production.                                                      |
-| [env.md](env.md)                                   | `.env` variable reference (`APP_ID`, `USER_NAME`, `QUERY_SERVER_ADDRESS`, etc.). Read when adding env vars, configuring Auth0 bypass, or inspecting runtime config.                                                                                             |
-| [local-setup.md](local-setup.md)                   | Manual local dev setup (`npm run init -- --local`, `npm run dev`). Read when running the app locally outside Cursor Cloud.                                                                                                                                      |
-| [cursor-cloud.md](cursor-cloud.md)                 | Cursor Cloud environment quirks (Node managed by env, dev server auto-started, skip browser testing during initial setup). Read when `$HOME` is under `/root` or `/home/ubuntu`, or when a dev-server terminal was auto-started.                                |
-| [claude-code-cloud.md](claude-code-cloud.md)       | Claude Code (claude.ai/code) cloud session quirks (ephemeral sessions, Claude GitHub App, env auto-runs init + dev server, skip browser testing during initial setup). Read when running in claude.ai/code, especially `$HOME` under `/root` or `/home/ubuntu`. |
-| [git-support.md](git-support.md)                   | Git commit workflow and conventions. Read when finishing implementation work, making commits, or troubleshooting git/pre-commit failures.                                                                                                                       |
-| [something-broke.md](something-broke.md)           | Error recovery and build failure troubleshooting. Read when something broke, build failed, `npm run build` errors, or the user wants to restore previous behavior.                                                                                              |
-| [instructions_warning.md](instructions_warning.md) | Warning about editing `.agents/` files managed by `@yottagraph-app/aether-instructions`. Read before modifying installed instruction files.                                                                                                                     |
+| File                                               | When to read                                                                                                                                                                                                                                                        |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [architecture.md](architecture.md)                 | Project structure, navigation, server routes, agents, MCP. Read when adding pages, navigation, or server-side functionality.                                                                                                                                        |
+| [data.md](data.md)                                 | How this app reads platform data (clients, schema discovery, entity/news/filings access, common gotchas). Read when building any feature that fetches or displays platform data.                                                                                    |
+| [cookbook.md](cookbook.md)                         | Copy-paste UI patterns for common pages: data table, form, chart, dialog, master-detail. For data-fetching recipes see `cookbook-data.md`.                                                                                                                          |
+| [cookbook-data.md](cookbook-data.md)               | Data-fetching UI recipes: entity search, news feed, filings, and related helpers. Read with `data.md` when building pages that display platform data.                                                                                                               |
+| [design.md](design.md)                             | `DESIGN.md` workflow, feature docs, starter-app-is-placeholder guidance. Read when starting work, planning features, or updating project design.                                                                                                                    |
+| [ui.md](ui.md)                                     | Vue/Vuetify page templates, layouts, scrollable content, data tables, loading states. Applies when creating or editing page templates (`pages/**`, `components/**`).                                                                                                |
+| [pref.md](pref.md)                                 | User preferences and KV storage: `usePrefsStore`, `Pref<T>`, app namespacing (`NUXT_PUBLIC_APP_ID`). Read when working on settings persistence.                                                                                                                     |
+| [branding.md](branding.md)                         | Visual styling, colors, typography, theming, branding, UI appearance. Read when updating brand assets or theme code.                                                                                                                                                |
+| [server.md](server.md)                             | Nitro server-side API routes (`server/**`): file-based routing, event handlers, image proxy. Read when adding server routes. For storage backends see `storage.md`; for platform-data proxying see `server-data.md`.                                                |
+| [server-data.md](server-data.md)                   | Reading platform data from Nitro server routes (`server/**`). Read when a server route needs to fetch platform data on behalf of the app.                                                                                                                           |
+| [storage.md](storage.md)                           | Storage backends: KV (always on) vs Neon Postgres (if provisioned). Read when choosing persistence, wiring `getRedis()`/`getDb()`, creating tables, or handling missing credentials gracefully.                                                                     |
+| [bigquery.md](bigquery.md)                         | Analytical reads via the portal gateway: `isBigQueryConfigured()`, `listDatasets()`, `listTables()`, `runQuery()`. Read whenever the task touches BigQuery — and DO NOT add `@google-cloud/bigquery` or paste service-account keys (BC 1.0 pattern, not supported). |
+| [agents.md](agents.md)                             | Conventions for developing ADK agents in `agents/**`. Read when writing or editing agent code.                                                                                                                                                                      |
+| [agents-data.md](agents-data.md)                   | How ADK agents access platform data (authentication, local testing env vars, mode-specific wiring). Read when an agent needs platform data (`agents/**`).                                                                                                           |
+| [mcp-servers.md](mcp-servers.md)                   | Conventions for developing MCP servers in `mcp-servers/**`. Read when writing or editing FastMCP servers.                                                                                                                                                           |
+| [deployment.md](deployment.md)                     | App, agent, and MCP server deployment targets (Vercel, Vertex AI Agent Engine, Cloud Run). Read when pushing to main, running `/deploy_agent` or `/deploy_mcp`, or explaining how code reaches production.                                                          |
+| [env.md](env.md)                                   | `.env` variable reference (`APP_ID`, `USER_NAME`, `QUERY_SERVER_ADDRESS`, etc.). Read when adding env vars, configuring Auth0 bypass, or inspecting runtime config.                                                                                                 |
+| [local-setup.md](local-setup.md)                   | Manual local dev setup (`npm run init -- --local`, `npm run dev`). Read when running the app locally outside Cursor Cloud.                                                                                                                                          |
+| [cursor-cloud.md](cursor-cloud.md)                 | Cursor Cloud environment quirks (Node managed by env, dev server auto-started, skip browser testing during initial setup). Read when `$HOME` is under `/root` or `/home/ubuntu`, or when a dev-server terminal was auto-started.                                    |
+| [claude-code-cloud.md](claude-code-cloud.md)       | Claude Code (claude.ai/code) cloud session quirks (ephemeral sessions, Claude GitHub App, env auto-runs init + dev server, skip browser testing during initial setup). Read when running in claude.ai/code, especially `$HOME` under `/root` or `/home/ubuntu`.     |
+| [git-support.md](git-support.md)                   | Git commit workflow and conventions. Read when finishing implementation work, making commits, or troubleshooting git/pre-commit failures.                                                                                                                           |
+| [something-broke.md](something-broke.md)           | Error recovery and build failure troubleshooting. Read when something broke, build failed, `npm run build` errors, or the user wants to restore previous behavior.                                                                                                  |
+| [instructions_warning.md](instructions_warning.md) | Warning about editing `.agents/` files managed by `@yottagraph-app/aether-instructions`. Read before modifying installed instruction files.                                                                                                                         |

package/skills/aether/bigquery.md

@@ -0,0 +1,200 @@
+# BigQuery
+
+The tenant app reads BigQuery through the **Broadchurch Portal gateway**.
+The Vercel-hosted Aether app NEVER holds GCP credentials directly — the
+portal runs queries in the tenant's per-tenant GCP project on the app's
+behalf, using its own service account.
+
+| Capability                | How to check                                                      | Env var                                                                                               | Utility file                                |
+| ------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------- |
+| **BigQuery (analytical)** | `process.env.NUXT_PUBLIC_BIGQUERY_ENABLED === 'true'`             | `NUXT_PUBLIC_BIGQUERY_ENABLED`                                                                        | `server/utils/bigquery.ts` (pre-scaffolded) |
+|                           | OR `curl <gateway.url>/api/tenants/<org_id>` → `gcp.bigquery` set | `NUXT_PUBLIC_BIGQUERY_DATASET_ID`, `NUXT_PUBLIC_BIGQUERY_PROJECT_ID`, `NUXT_PUBLIC_BIGQUERY_LOCATION` |                                             |
+
+Only available if the tenant was provisioned with BigQuery enabled (or
+had it enabled later via the portal's "Enable BigQuery" action). Check
+`isBigQueryConfigured()` before calling any of the helpers.
+
+For transactional / relational data see [storage.md](storage.md)
+(Postgres + KV); BigQuery is the analytical store, optimized for
+append-only / large columnar scans.
+
+## Critical: never do these
+
+The agent reflexively reaches for `@google-cloud/bigquery` and a
+service-account-key env var when asked to talk to BigQuery — that's the
+**BC 1.0 pattern** and it is not supported here. If you find yourself
+about to write any of these, **stop**, re-read this file, and use
+`server/utils/bigquery.ts` instead:
+
+- DO NOT add `@google-cloud/bigquery` to `package.json`. It only ships
+  with the Broadchurch Portal where the SA actually exists; in the
+  tenant app it would fail at runtime with "could not load default
+  credentials".
+- DO NOT paste a JSON service-account key into Vercel env (as
+  `GCP_SERVICE_ACCOUNT_KEY` or any other name). There is no key for the
+  app to use — the portal is what holds credentials. The Vercel env is
+  also not a secure place to put long-lived GCP keys.
+- DO NOT add `GOOGLE_APPLICATION_CREDENTIALS`. That env var points at a
+  key file on disk; Vercel has no such file and no way to obtain one.
+- DO NOT call the BigQuery REST API directly from `<script setup>` or
+  any client-side code. Always go through a Nitro server route
+  (`server/api/**`).
+
+## Where credentials come from
+
+There is no credential on the tenant side. The portal gateway resolves
+the tenant's GCP project from `org_id` (passed in the URL) and runs
+jobs with the portal SA's ADC. Inside `bc-{slug}` the portal SA has:
+
+- `roles/bigquery.jobUser` + `roles/bigquery.metadataViewer` at the
+  project level (list datasets/tables, run SELECT jobs).
+- `roles/bigquery.dataEditor` on `bc_{slug}_analytics` (read row data).
+
+That last binding scopes read access: the picker can list every dataset
+the agent or tenant has created in the project, but `runQuery()` will
+fail on datasets the portal hasn't been ACL'd into. The intended
+analytical write target is `bc_{slug}_analytics`.
+
+## `isBigQueryConfigured()` — feature gating
+
+The provisioner injects `NUXT_PUBLIC_BIGQUERY_ENABLED=true` into the
+Vercel env when BQ is on. Use it to gate UI:
+
+```vue
+<script setup lang="ts">
+    const bqEnabled = useRuntimeConfig().public.bigqueryEnabled === 'true';
+</script>
+
+<template>
+    <v-card v-if="bqEnabled">…analytics UI…</v-card>
+    <v-card v-else>
+        <v-card-title>BigQuery is not configured</v-card-title>
+        <v-card-text> Ask the platform operator to enable BigQuery for this app. </v-card-text>
+    </v-card>
+</template>
+```
+
+For server routes, use `isBigQueryConfigured()` from
+`server/utils/bigquery.ts` and return a 503-style message when it's
+false (don't throw — the page should still render).
+
+## Server-route pattern
+
+All BQ access lives in `server/api/**`. Helpers exposed by
+`server/utils/bigquery.ts`:
+
+| Helper                            | Returns                                  |
+| --------------------------------- | ---------------------------------------- |
+| `isBigQueryConfigured()`          | `boolean`                                |
+| `getDefaultDataset()`             | `string \| null` — `bc_{slug}_analytics` |
+| `getBigQueryProjectId()`          | `string \| null` — `bc-{slug}`           |
+| `getBigQueryLocation()`           | `string \| null` — e.g. `us-central1`    |
+| `listDatasets()`                  | `BqDataset[]`                            |
+| `listTables(datasetId, options?)` | `BqTable[]`                              |
+| `runQuery(sql, options?)`         | `BqQueryResult`                          |
+| `toRowObjects(result)`            | `Record<string, unknown>[]`              |
+
+### Example: list datasets
+
+```typescript
+// server/api/bq/datasets.get.ts
+import { isBigQueryConfigured, listDatasets } from '~/server/utils/bigquery';
+
+export default defineEventHandler(async () => {
+    if (!isBigQueryConfigured()) {
+        throw createError({ statusCode: 503, statusMessage: 'BigQuery not configured' });
+    }
+    return await listDatasets();
+});
+```
+
+### Example: list tables in a dataset
+
+```typescript
+// server/api/bq/tables/[dataset].get.ts
+import { isBigQueryConfigured, listTables } from '~/server/utils/bigquery';
+
+export default defineEventHandler(async (event) => {
+    if (!isBigQueryConfigured()) {
+        throw createError({ statusCode: 503, statusMessage: 'BigQuery not configured' });
+    }
+    const dataset = getRouterParam(event, 'dataset');
+    if (!dataset) {
+        throw createError({ statusCode: 400, statusMessage: 'dataset is required' });
+    }
+    return await listTables(dataset);
+});
+```
+
+### Example: run a parameterized SELECT
+
+```typescript
+// server/api/bq/events.get.ts
+import { isBigQueryConfigured, runQuery, toRowObjects } from '~/server/utils/bigquery';
+
+export default defineEventHandler(async (event) => {
+    if (!isBigQueryConfigured()) {
+        throw createError({ statusCode: 503, statusMessage: 'BigQuery not configured' });
+    }
+    const { date, limit } = getQuery(event);
+    const result = await runQuery(
+        `SELECT * FROM events WHERE event_date = @date ORDER BY ts DESC LIMIT @limit`,
+        {
+            params: [
+                { name: 'date', type: 'DATE', value: String(date ?? '2026-01-01') },
+                { name: 'limit', type: 'INT64', value: Number(limit ?? 100) },
+            ],
+        }
+    );
+    return {
+        schema: result.schema,
+        rows: toRowObjects(result),
+        truncated: result.truncated,
+    };
+});
+```
+
+`defaultDataset` is set automatically to `bc_{slug}_analytics` for
+unqualified table refs. Pass `options.defaultDataset` to override.
+
+## Guardrails the gateway enforces
+
+The portal will reject:
+
+- DML / DDL (`INSERT`, `DELETE`, `UPDATE`, `CREATE`, `DROP`, `MERGE`,
+  `TRUNCATE`, etc.). Only `SELECT` / `WITH` / `CALL` (for TVFs) are
+  allowed. If you need to write to BigQuery, do it from a Cloud Run
+  Job in the tenant project — that's the documented append path.
+- Queries that would scan more than 10 GB (default cap 1 GB). The
+  gateway sets BigQuery's `maximumBytesBilled` server-side; over-scope
+  queries fail with a clear error from BQ before any cost is incurred.
+- More than 10,000 rows returned in one call (default 1,000). Paginate
+  with `LIMIT … OFFSET` in SQL if you need more.
+- 30s wall-clock. The response sets `truncated: true` if BQ ran out of
+  time producing the first page.
+
+## Local dev
+
+`NUXT_PUBLIC_BIGQUERY_*` are intentionally unset in local `.env`.
+`isBigQueryConfigured()` returns false, helpers throw with a clear
+message ("BigQuery is not configured for this tenant…"). Test BQ
+features on the deployed preview/production URL where the env vars
+are injected.
+
+## Where the data goes
+
+Cloud Run Jobs and Workflows in the tenant project write to
+`bc_{slug}_analytics` (see [`deployment.md`](deployment.md) and the
+portal's compute-jobs docs). The tenant app reads from that dataset
+through this gateway. Round-trip:
+
+```
+Cloud Run Job → BigQuery (bc_{slug}_analytics) → Portal gateway → Aether app
+                                                       ↑
+                                                  portal SA's ADC
+```
+
+If you see "Permission denied on resource project" in the gateway
+response, the dataset's IAM was likely created in a previous tenant
+version and is missing the portal SA. Re-run "Enable BigQuery" in the
+portal cockpit to reconcile.

package/skills/aether/data.md

@@ -5,6 +5,12 @@ primary data source — use it first for any data needs (entities, news,
 filings, sentiment, relationships, events). Do NOT call external APIs
 (e.g. sec.gov, Wikipedia) for data that the platform already provides.
 
+Tenant-owned analytical data (event streams, derived tables, time-series
+features that Cloud Run Jobs write into the tenant project) lives in
+BigQuery, not the Elemental API. For that see [`bigquery.md`](bigquery.md)
+— and importantly, do NOT add `@google-cloud/bigquery` or any GCP
+credentials to this app. Queries go through the portal gateway.
+
 The Elemental API provides access to the Lovelace Knowledge Graph through
 the Query Server. Use it to search for entities, retrieve properties,
 explore relationships, and analyze sentiment. New data sources are added
@@ -236,6 +242,7 @@ types or property names. Instead, discover them at runtime:
    and properties (PIDs) available in the system. See `schema.md`.
 
     The schema response contains:
+
     - **Flavors** (entity types): Company, Person, GovernmentOrg, etc.
       Each flavor has a numeric ID and a human-readable name.
     - **PIDs** (properties): name, country, industry, lei_code, etc.

package/skills/aether/git-support.md

@@ -40,17 +40,27 @@ If a user asks about this error, explain the `npm run format` requirement.
 
 ## Pushing
 
-**Push directly to main.** Vercel auto-deploys on push to main, so this
-gets the app live immediately.
+**Push directly to main.** Vercel auto-deploys on push to `main`, which
+is how this project gets live. Creating a PR breaks that auto-deploy
+flow and disrupts the smooth first-run experience the wizard sets up.
 
-**Do NOT create pull requests** — do not run `gh pr create` or create
-feature branches. In Cursor Cloud environments, the GitHub integration
-token lacks PR permissions (known Cursor issue). Pushing to main is the
-correct workflow.
+**Do NOT create pull requests** — do not run `gh pr create`, do not
+create a feature branch, and do not push to anything other than `main`.
+The `main` branch on tenant repos is **not** protected; `git push
+origin main` will succeed.
+
+> Note: tenant repos follow a different policy than the upstream
+> `aether-dev` template. `aether-dev` is PR-only because its `main` is
+> protected; tenant projects deliberately are not. Do not import the
+> `aether-dev` habit when working in a tenant repo.
 
 ```bash
 git push origin main
 ```
 
+If a push to `main` fails because of an actual permission issue (not
+branch protection), report the exact error to the user — do not fall
+back to a PR as a workaround.
+
 If running locally (not in Cursor Cloud), the user may prefer a PR-based
 workflow — ask before pushing directly to main in that case.

package/skills/aether/storage.md

@@ -1,5 +1,12 @@
 # Storage
 
+This skill covers **transactional / state** storage — KV (always on) and
+Neon Postgres (if provisioned). For **analytical / append-only** reads
+from large datasets (anything you'd reach for a data warehouse for), see
+[`bigquery.md`](bigquery.md) instead — BigQuery is provisioned per-tenant
+in the GCP tenant project and read through the portal gateway, NOT via
+direct GCP credentials.
+
 Two storage services are available. KV is always connected; Neon Postgres
 is only present if the tenant was provisioned with it. Each store has its
 own way of checking availability — see the **How to check** column below:

package/variants/mcp-only/commands/build_my_app.md

@@ -170,16 +170,24 @@ git add -A
 git commit -m "[Agent commit] Initial app build from project brief"
 ```
 
-**Push directly to main.** Vercel auto-deploys on push to main, so this
-gets the app live immediately. Do NOT try to create a pull request via
-`gh pr create` — in Cursor Cloud environments, the GitHub integration
-token lacks PR permissions (known Cursor issue). Pushing to main is the
-correct workflow.
+**Push directly to main. Do NOT create a pull request or a feature branch.**
+
+Vercel auto-deploys on push to `main`, which is how this project gets
+live. Creating a PR blocks that auto-deploy and breaks the smooth
+first-run experience the user is expecting from the wizard. The `main`
+branch on tenant repos is **not** protected — `git push origin main`
+will succeed. Tenant repos follow a different policy than the upstream
+`aether-dev` template (which IS PR-only) — do not import that habit.
 
 ```bash
 git push origin main
 ```
 
+Specifically: do NOT run `gh pr create`, do NOT create a feature
+branch, and do NOT push to anything other than `main`. If a push to
+`main` fails because of a real permission issue (not branch
+protection), report the exact error rather than falling back to a PR.
+
 If running locally (not in Cursor Cloud), the user may prefer a PR-based
 workflow — ask before pushing directly to main in that case.