@yottagraph-app/aether-instructions 1.1.49 → 1.1.51
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +2 -2
- package/commands/build_my_app.md +13 -5
- package/package.json +1 -1
- package/skills/aether/SKILL.md +25 -24
- package/skills/aether/bigquery.md +200 -0
- package/skills/aether/data.md +7 -0
- package/skills/aether/git-support.md +11 -6
- package/skills/aether/storage.md +7 -0
- package/variants/mcp-only/commands/build_my_app.md +12 -5
package/AGENTS.md
CHANGED
|
@@ -8,11 +8,11 @@
|
|
|
8
8
|
|
|
9
9
|
**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.
|
|
10
10
|
|
|
11
|
-
**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).
|
|
11
|
+
**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.
|
|
12
12
|
|
|
13
13
|
**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.
|
|
14
14
|
|
|
15
|
-
**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
|
|
15
|
+
**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. This project's `main` is not protected; Vercel auto-deploys on push to `main`, and that's how the app gets live. A PR blocks the auto-deploy and breaks the smooth first-run flow.
|
|
16
16
|
|
|
17
17
|
**First action for a new project:** Run `/build_my_app`.
|
|
18
18
|
|
package/commands/build_my_app.md
CHANGED
|
@@ -112,6 +112,7 @@ Key capabilities:
|
|
|
112
112
|
- **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.
|
|
113
113
|
- **KV storage** -- always available for preferences and lightweight data (see [`pref.md`](../skills/aether/pref.md) in the `aether` skill)
|
|
114
114
|
- **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
|
|
115
|
+
- **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).
|
|
115
116
|
- **AI agent chat** -- use the `useAgentChat` composable to build a chat UI for deployed agents
|
|
116
117
|
- **MCP servers** -- Lovelace MCP servers may be available (check `.agents/mcp.json`)
|
|
117
118
|
- **Components** -- Vuetify 3 component library is available
|
|
@@ -228,16 +229,23 @@ git add -A
|
|
|
228
229
|
git commit -m "[Agent commit] Initial app build from project brief"
|
|
229
230
|
```
|
|
230
231
|
|
|
231
|
-
**Push directly to main
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
232
|
+
**Push directly to main. Do NOT create a pull request or a feature branch.**
|
|
233
|
+
|
|
234
|
+
Vercel auto-deploys on push to `main`, which is how this project gets
|
|
235
|
+
live. Creating a PR blocks that auto-deploy and breaks the smooth
|
|
236
|
+
first-run experience the user is expecting from the wizard. This
|
|
237
|
+
project's `main` is **not** protected — `git push origin main` will
|
|
238
|
+
succeed.
|
|
236
239
|
|
|
237
240
|
```bash
|
|
238
241
|
git push origin main
|
|
239
242
|
```
|
|
240
243
|
|
|
244
|
+
Specifically: do NOT run `gh pr create`, do NOT create a feature
|
|
245
|
+
branch, and do NOT push to anything other than `main`. If a push to
|
|
246
|
+
`main` fails because of a real permission issue (not branch
|
|
247
|
+
protection), report the exact error rather than falling back to a PR.
|
|
248
|
+
|
|
241
249
|
If running locally (not in Cursor Cloud), the user may prefer a PR-based
|
|
242
250
|
workflow — ask before pushing directly to main in that case.
|
|
243
251
|
|
package/package.json
CHANGED
package/skills/aether/SKILL.md
CHANGED
|
@@ -32,27 +32,28 @@ topics that apply.
|
|
|
32
32
|
|
|
33
33
|
## Files
|
|
34
34
|
|
|
35
|
-
| File | When to read
|
|
36
|
-
| -------------------------------------------------- |
|
|
37
|
-
| [architecture.md](architecture.md) | Project structure, navigation, server routes, agents, MCP. Read when adding pages, navigation, or server-side functionality.
|
|
38
|
-
| [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.
|
|
39
|
-
| [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`.
|
|
40
|
-
| [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.
|
|
41
|
-
| [design.md](design.md) | `DESIGN.md` workflow, feature docs, starter-app-is-placeholder guidance. Read when starting work, planning features, or updating project design.
|
|
42
|
-
| [ui.md](ui.md) | Vue/Vuetify page templates, layouts, scrollable content, data tables, loading states. Applies when creating or editing page templates (`pages/**`, `components/**`).
|
|
43
|
-
| [pref.md](pref.md) | User preferences and KV storage: `usePrefsStore`, `Pref<T>`, app namespacing (`NUXT_PUBLIC_APP_ID`). Read when working on settings persistence.
|
|
44
|
-
| [branding.md](branding.md) | Visual styling, colors, typography, theming, branding, UI appearance. Read when updating brand assets or theme code.
|
|
45
|
-
| [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`.
|
|
46
|
-
| [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.
|
|
47
|
-
| [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.
|
|
48
|
-
| [
|
|
49
|
-
| [agents
|
|
50
|
-
| [
|
|
51
|
-
| [
|
|
52
|
-
| [
|
|
53
|
-
| [
|
|
54
|
-
| [
|
|
55
|
-
| [
|
|
56
|
-
| [
|
|
57
|
-
| [
|
|
58
|
-
| [
|
|
35
|
+
| File | When to read |
|
|
36
|
+
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
37
|
+
| [architecture.md](architecture.md) | Project structure, navigation, server routes, agents, MCP. Read when adding pages, navigation, or server-side functionality. |
|
|
38
|
+
| [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. |
|
|
39
|
+
| [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`. |
|
|
40
|
+
| [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. |
|
|
41
|
+
| [design.md](design.md) | `DESIGN.md` workflow, feature docs, starter-app-is-placeholder guidance. Read when starting work, planning features, or updating project design. |
|
|
42
|
+
| [ui.md](ui.md) | Vue/Vuetify page templates, layouts, scrollable content, data tables, loading states. Applies when creating or editing page templates (`pages/**`, `components/**`). |
|
|
43
|
+
| [pref.md](pref.md) | User preferences and KV storage: `usePrefsStore`, `Pref<T>`, app namespacing (`NUXT_PUBLIC_APP_ID`). Read when working on settings persistence. |
|
|
44
|
+
| [branding.md](branding.md) | Visual styling, colors, typography, theming, branding, UI appearance. Read when updating brand assets or theme code. |
|
|
45
|
+
| [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`. |
|
|
46
|
+
| [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. |
|
|
47
|
+
| [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. |
|
|
48
|
+
| [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). |
|
|
49
|
+
| [agents.md](agents.md) | Conventions for developing ADK agents in `agents/**`. Read when writing or editing agent code. |
|
|
50
|
+
| [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/**`). |
|
|
51
|
+
| [mcp-servers.md](mcp-servers.md) | Conventions for developing MCP servers in `mcp-servers/**`. Read when writing or editing FastMCP servers. |
|
|
52
|
+
| [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. |
|
|
53
|
+
| [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. |
|
|
54
|
+
| [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. |
|
|
55
|
+
| [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. |
|
|
56
|
+
| [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`. |
|
|
57
|
+
| [git-support.md](git-support.md) | Git commit workflow and conventions. Read when finishing implementation work, making commits, or troubleshooting git/pre-commit failures. |
|
|
58
|
+
| [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. |
|
|
59
|
+
| [instructions_warning.md](instructions_warning.md) | Warning about editing `.agents/` files managed by `@yottagraph-app/aether-instructions`. Read before modifying installed instruction files. |
|
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
# BigQuery
|
|
2
|
+
|
|
3
|
+
The tenant app reads BigQuery through the **Broadchurch Portal gateway**.
|
|
4
|
+
The Vercel-hosted Aether app NEVER holds GCP credentials directly — the
|
|
5
|
+
portal runs queries in the tenant's per-tenant GCP project on the app's
|
|
6
|
+
behalf, using its own service account.
|
|
7
|
+
|
|
8
|
+
| Capability | How to check | Env var | Utility file |
|
|
9
|
+
| ------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------- |
|
|
10
|
+
| **BigQuery (analytical)** | `process.env.NUXT_PUBLIC_BIGQUERY_ENABLED === 'true'` | `NUXT_PUBLIC_BIGQUERY_ENABLED` | `server/utils/bigquery.ts` (pre-scaffolded) |
|
|
11
|
+
| | 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` | |
|
|
12
|
+
|
|
13
|
+
Only available if the tenant was provisioned with BigQuery enabled (or
|
|
14
|
+
had it enabled later via the portal's "Enable BigQuery" action). Check
|
|
15
|
+
`isBigQueryConfigured()` before calling any of the helpers.
|
|
16
|
+
|
|
17
|
+
For transactional / relational data see [storage.md](storage.md)
|
|
18
|
+
(Postgres + KV); BigQuery is the analytical store, optimized for
|
|
19
|
+
append-only / large columnar scans.
|
|
20
|
+
|
|
21
|
+
## Critical: never do these
|
|
22
|
+
|
|
23
|
+
The agent reflexively reaches for `@google-cloud/bigquery` and a
|
|
24
|
+
service-account-key env var when asked to talk to BigQuery — that's the
|
|
25
|
+
**BC 1.0 pattern** and it is not supported here. If you find yourself
|
|
26
|
+
about to write any of these, **stop**, re-read this file, and use
|
|
27
|
+
`server/utils/bigquery.ts` instead:
|
|
28
|
+
|
|
29
|
+
- DO NOT add `@google-cloud/bigquery` to `package.json`. It only ships
|
|
30
|
+
with the Broadchurch Portal where the SA actually exists; in the
|
|
31
|
+
tenant app it would fail at runtime with "could not load default
|
|
32
|
+
credentials".
|
|
33
|
+
- DO NOT paste a JSON service-account key into Vercel env (as
|
|
34
|
+
`GCP_SERVICE_ACCOUNT_KEY` or any other name). There is no key for the
|
|
35
|
+
app to use — the portal is what holds credentials. The Vercel env is
|
|
36
|
+
also not a secure place to put long-lived GCP keys.
|
|
37
|
+
- DO NOT add `GOOGLE_APPLICATION_CREDENTIALS`. That env var points at a
|
|
38
|
+
key file on disk; Vercel has no such file and no way to obtain one.
|
|
39
|
+
- DO NOT call the BigQuery REST API directly from `<script setup>` or
|
|
40
|
+
any client-side code. Always go through a Nitro server route
|
|
41
|
+
(`server/api/**`).
|
|
42
|
+
|
|
43
|
+
## Where credentials come from
|
|
44
|
+
|
|
45
|
+
There is no credential on the tenant side. The portal gateway resolves
|
|
46
|
+
the tenant's GCP project from `org_id` (passed in the URL) and runs
|
|
47
|
+
jobs with the portal SA's ADC. Inside `bc-{slug}` the portal SA has:
|
|
48
|
+
|
|
49
|
+
- `roles/bigquery.jobUser` + `roles/bigquery.metadataViewer` at the
|
|
50
|
+
project level (list datasets/tables, run SELECT jobs).
|
|
51
|
+
- `roles/bigquery.dataEditor` on `bc_{slug}_analytics` (read row data).
|
|
52
|
+
|
|
53
|
+
That last binding scopes read access: the picker can list every dataset
|
|
54
|
+
the agent or tenant has created in the project, but `runQuery()` will
|
|
55
|
+
fail on datasets the portal hasn't been ACL'd into. The intended
|
|
56
|
+
analytical write target is `bc_{slug}_analytics`.
|
|
57
|
+
|
|
58
|
+
## `isBigQueryConfigured()` — feature gating
|
|
59
|
+
|
|
60
|
+
The provisioner injects `NUXT_PUBLIC_BIGQUERY_ENABLED=true` into the
|
|
61
|
+
Vercel env when BQ is on. Use it to gate UI:
|
|
62
|
+
|
|
63
|
+
```vue
|
|
64
|
+
<script setup lang="ts">
|
|
65
|
+
const bqEnabled = useRuntimeConfig().public.bigqueryEnabled === 'true';
|
|
66
|
+
</script>
|
|
67
|
+
|
|
68
|
+
<template>
|
|
69
|
+
<v-card v-if="bqEnabled">…analytics UI…</v-card>
|
|
70
|
+
<v-card v-else>
|
|
71
|
+
<v-card-title>BigQuery is not configured</v-card-title>
|
|
72
|
+
<v-card-text> Ask the platform operator to enable BigQuery for this app. </v-card-text>
|
|
73
|
+
</v-card>
|
|
74
|
+
</template>
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
For server routes, use `isBigQueryConfigured()` from
|
|
78
|
+
`server/utils/bigquery.ts` and return a 503-style message when it's
|
|
79
|
+
false (don't throw — the page should still render).
|
|
80
|
+
|
|
81
|
+
## Server-route pattern
|
|
82
|
+
|
|
83
|
+
All BQ access lives in `server/api/**`. Helpers exposed by
|
|
84
|
+
`server/utils/bigquery.ts`:
|
|
85
|
+
|
|
86
|
+
| Helper | Returns |
|
|
87
|
+
| --------------------------------- | ---------------------------------------- |
|
|
88
|
+
| `isBigQueryConfigured()` | `boolean` |
|
|
89
|
+
| `getDefaultDataset()` | `string \| null` — `bc_{slug}_analytics` |
|
|
90
|
+
| `getBigQueryProjectId()` | `string \| null` — `bc-{slug}` |
|
|
91
|
+
| `getBigQueryLocation()` | `string \| null` — e.g. `us-central1` |
|
|
92
|
+
| `listDatasets()` | `BqDataset[]` |
|
|
93
|
+
| `listTables(datasetId, options?)` | `BqTable[]` |
|
|
94
|
+
| `runQuery(sql, options?)` | `BqQueryResult` |
|
|
95
|
+
| `toRowObjects(result)` | `Record<string, unknown>[]` |
|
|
96
|
+
|
|
97
|
+
### Example: list datasets
|
|
98
|
+
|
|
99
|
+
```typescript
|
|
100
|
+
// server/api/bq/datasets.get.ts
|
|
101
|
+
import { isBigQueryConfigured, listDatasets } from '~/server/utils/bigquery';
|
|
102
|
+
|
|
103
|
+
export default defineEventHandler(async () => {
|
|
104
|
+
if (!isBigQueryConfigured()) {
|
|
105
|
+
throw createError({ statusCode: 503, statusMessage: 'BigQuery not configured' });
|
|
106
|
+
}
|
|
107
|
+
return await listDatasets();
|
|
108
|
+
});
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### Example: list tables in a dataset
|
|
112
|
+
|
|
113
|
+
```typescript
|
|
114
|
+
// server/api/bq/tables/[dataset].get.ts
|
|
115
|
+
import { isBigQueryConfigured, listTables } from '~/server/utils/bigquery';
|
|
116
|
+
|
|
117
|
+
export default defineEventHandler(async (event) => {
|
|
118
|
+
if (!isBigQueryConfigured()) {
|
|
119
|
+
throw createError({ statusCode: 503, statusMessage: 'BigQuery not configured' });
|
|
120
|
+
}
|
|
121
|
+
const dataset = getRouterParam(event, 'dataset');
|
|
122
|
+
if (!dataset) {
|
|
123
|
+
throw createError({ statusCode: 400, statusMessage: 'dataset is required' });
|
|
124
|
+
}
|
|
125
|
+
return await listTables(dataset);
|
|
126
|
+
});
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
### Example: run a parameterized SELECT
|
|
130
|
+
|
|
131
|
+
```typescript
|
|
132
|
+
// server/api/bq/events.get.ts
|
|
133
|
+
import { isBigQueryConfigured, runQuery, toRowObjects } from '~/server/utils/bigquery';
|
|
134
|
+
|
|
135
|
+
export default defineEventHandler(async (event) => {
|
|
136
|
+
if (!isBigQueryConfigured()) {
|
|
137
|
+
throw createError({ statusCode: 503, statusMessage: 'BigQuery not configured' });
|
|
138
|
+
}
|
|
139
|
+
const { date, limit } = getQuery(event);
|
|
140
|
+
const result = await runQuery(
|
|
141
|
+
`SELECT * FROM events WHERE event_date = @date ORDER BY ts DESC LIMIT @limit`,
|
|
142
|
+
{
|
|
143
|
+
params: [
|
|
144
|
+
{ name: 'date', type: 'DATE', value: String(date ?? '2026-01-01') },
|
|
145
|
+
{ name: 'limit', type: 'INT64', value: Number(limit ?? 100) },
|
|
146
|
+
],
|
|
147
|
+
}
|
|
148
|
+
);
|
|
149
|
+
return {
|
|
150
|
+
schema: result.schema,
|
|
151
|
+
rows: toRowObjects(result),
|
|
152
|
+
truncated: result.truncated,
|
|
153
|
+
};
|
|
154
|
+
});
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
`defaultDataset` is set automatically to `bc_{slug}_analytics` for
|
|
158
|
+
unqualified table refs. Pass `options.defaultDataset` to override.
|
|
159
|
+
|
|
160
|
+
## Guardrails the gateway enforces
|
|
161
|
+
|
|
162
|
+
The portal will reject:
|
|
163
|
+
|
|
164
|
+
- DML / DDL (`INSERT`, `DELETE`, `UPDATE`, `CREATE`, `DROP`, `MERGE`,
|
|
165
|
+
`TRUNCATE`, etc.). Only `SELECT` / `WITH` / `CALL` (for TVFs) are
|
|
166
|
+
allowed. If you need to write to BigQuery, do it from a Cloud Run
|
|
167
|
+
Job in the tenant project — that's the documented append path.
|
|
168
|
+
- Queries that would scan more than 10 GB (default cap 1 GB). The
|
|
169
|
+
gateway sets BigQuery's `maximumBytesBilled` server-side; over-scope
|
|
170
|
+
queries fail with a clear error from BQ before any cost is incurred.
|
|
171
|
+
- More than 10,000 rows returned in one call (default 1,000). Paginate
|
|
172
|
+
with `LIMIT … OFFSET` in SQL if you need more.
|
|
173
|
+
- 30s wall-clock. The response sets `truncated: true` if BQ ran out of
|
|
174
|
+
time producing the first page.
|
|
175
|
+
|
|
176
|
+
## Local dev
|
|
177
|
+
|
|
178
|
+
`NUXT_PUBLIC_BIGQUERY_*` are intentionally unset in local `.env`.
|
|
179
|
+
`isBigQueryConfigured()` returns false, helpers throw with a clear
|
|
180
|
+
message ("BigQuery is not configured for this tenant…"). Test BQ
|
|
181
|
+
features on the deployed preview/production URL where the env vars
|
|
182
|
+
are injected.
|
|
183
|
+
|
|
184
|
+
## Where the data goes
|
|
185
|
+
|
|
186
|
+
Cloud Run Jobs and Workflows in the tenant project write to
|
|
187
|
+
`bc_{slug}_analytics` (see [`deployment.md`](deployment.md) and the
|
|
188
|
+
portal's compute-jobs docs). The tenant app reads from that dataset
|
|
189
|
+
through this gateway. Round-trip:
|
|
190
|
+
|
|
191
|
+
```
|
|
192
|
+
Cloud Run Job → BigQuery (bc_{slug}_analytics) → Portal gateway → Aether app
|
|
193
|
+
↑
|
|
194
|
+
portal SA's ADC
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
If you see "Permission denied on resource project" in the gateway
|
|
198
|
+
response, the dataset's IAM was likely created in a previous tenant
|
|
199
|
+
version and is missing the portal SA. Re-run "Enable BigQuery" in the
|
|
200
|
+
portal cockpit to reconcile.
|
package/skills/aether/data.md
CHANGED
|
@@ -5,6 +5,12 @@ primary data source — use it first for any data needs (entities, news,
|
|
|
5
5
|
filings, sentiment, relationships, events). Do NOT call external APIs
|
|
6
6
|
(e.g. sec.gov, Wikipedia) for data that the platform already provides.
|
|
7
7
|
|
|
8
|
+
Tenant-owned analytical data (event streams, derived tables, time-series
|
|
9
|
+
features that Cloud Run Jobs write into the tenant project) lives in
|
|
10
|
+
BigQuery, not the Elemental API. For that see [`bigquery.md`](bigquery.md)
|
|
11
|
+
— and importantly, do NOT add `@google-cloud/bigquery` or any GCP
|
|
12
|
+
credentials to this app. Queries go through the portal gateway.
|
|
13
|
+
|
|
8
14
|
The Elemental API provides access to the Lovelace Knowledge Graph through
|
|
9
15
|
the Query Server. Use it to search for entities, retrieve properties,
|
|
10
16
|
explore relationships, and analyze sentiment. New data sources are added
|
|
@@ -236,6 +242,7 @@ types or property names. Instead, discover them at runtime:
|
|
|
236
242
|
and properties (PIDs) available in the system. See `schema.md`.
|
|
237
243
|
|
|
238
244
|
The schema response contains:
|
|
245
|
+
|
|
239
246
|
- **Flavors** (entity types): Company, Person, GovernmentOrg, etc.
|
|
240
247
|
Each flavor has a numeric ID and a human-readable name.
|
|
241
248
|
- **PIDs** (properties): name, country, industry, lei_code, etc.
|
|
@@ -40,17 +40,22 @@ If a user asks about this error, explain the `npm run format` requirement.
|
|
|
40
40
|
|
|
41
41
|
## Pushing
|
|
42
42
|
|
|
43
|
-
**Push directly to main.** Vercel auto-deploys on push to main
|
|
44
|
-
|
|
43
|
+
**Push directly to main.** Vercel auto-deploys on push to `main`, which
|
|
44
|
+
is how this project gets live. Creating a PR blocks that auto-deploy
|
|
45
|
+
and disrupts the smooth first-run experience.
|
|
45
46
|
|
|
46
|
-
**Do NOT create pull requests** — do not run `gh pr create
|
|
47
|
-
feature
|
|
48
|
-
|
|
49
|
-
|
|
47
|
+
**Do NOT create pull requests** — do not run `gh pr create`, do not
|
|
48
|
+
create a feature branch, and do not push to anything other than `main`.
|
|
49
|
+
This project's `main` is **not** protected; `git push origin main`
|
|
50
|
+
will succeed.
|
|
50
51
|
|
|
51
52
|
```bash
|
|
52
53
|
git push origin main
|
|
53
54
|
```
|
|
54
55
|
|
|
56
|
+
If a push to `main` fails because of an actual permission issue (not
|
|
57
|
+
branch protection), report the exact error to the user — do not fall
|
|
58
|
+
back to a PR as a workaround.
|
|
59
|
+
|
|
55
60
|
If running locally (not in Cursor Cloud), the user may prefer a PR-based
|
|
56
61
|
workflow — ask before pushing directly to main in that case.
|
package/skills/aether/storage.md
CHANGED
|
@@ -1,5 +1,12 @@
|
|
|
1
1
|
# Storage
|
|
2
2
|
|
|
3
|
+
This skill covers **transactional / state** storage — KV (always on) and
|
|
4
|
+
Neon Postgres (if provisioned). For **analytical / append-only** reads
|
|
5
|
+
from large datasets (anything you'd reach for a data warehouse for), see
|
|
6
|
+
[`bigquery.md`](bigquery.md) instead — BigQuery is provisioned per-tenant
|
|
7
|
+
in the GCP tenant project and read through the portal gateway, NOT via
|
|
8
|
+
direct GCP credentials.
|
|
9
|
+
|
|
3
10
|
Two storage services are available. KV is always connected; Neon Postgres
|
|
4
11
|
is only present if the tenant was provisioned with it. Each store has its
|
|
5
12
|
own way of checking availability — see the **How to check** column below:
|
|
@@ -170,16 +170,23 @@ git add -A
|
|
|
170
170
|
git commit -m "[Agent commit] Initial app build from project brief"
|
|
171
171
|
```
|
|
172
172
|
|
|
173
|
-
**Push directly to main
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
173
|
+
**Push directly to main. Do NOT create a pull request or a feature branch.**
|
|
174
|
+
|
|
175
|
+
Vercel auto-deploys on push to `main`, which is how this project gets
|
|
176
|
+
live. Creating a PR blocks that auto-deploy and breaks the smooth
|
|
177
|
+
first-run experience the user is expecting from the wizard. This
|
|
178
|
+
project's `main` is **not** protected — `git push origin main` will
|
|
179
|
+
succeed.
|
|
178
180
|
|
|
179
181
|
```bash
|
|
180
182
|
git push origin main
|
|
181
183
|
```
|
|
182
184
|
|
|
185
|
+
Specifically: do NOT run `gh pr create`, do NOT create a feature
|
|
186
|
+
branch, and do NOT push to anything other than `main`. If a push to
|
|
187
|
+
`main` fails because of a real permission issue (not branch
|
|
188
|
+
protection), report the exact error rather than falling back to a PR.
|
|
189
|
+
|
|
183
190
|
If running locally (not in Cursor Cloud), the user may prefer a PR-based
|
|
184
191
|
workflow — ask before pushing directly to main in that case.
|
|
185
192
|
|