@yottagraph-app/aether-instructions 1.1.46 → 1.1.48
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 -1
- package/package.json +1 -1
- package/skills/aether/SKILL.md +24 -23
- package/skills/aether/claude-code-cloud.md +75 -0
package/AGENTS.md
CHANGED
|
@@ -24,7 +24,8 @@ The `aether` skill (`.agents/skills/aether/SKILL.md`) covers architecture, data,
|
|
|
24
24
|
|
|
25
25
|
Detect your runtime once at startup, then read the matching topic in the `aether` skill:
|
|
26
26
|
|
|
27
|
-
- **
|
|
27
|
+
- **Claude Code (claude.ai/code)** if you are Claude Code running in a cloud session (Linux container, `$HOME` starts with `/root` or `/home/ubuntu`, and you were invoked via claude.ai/code rather than a local CLI). → Read [`claude-code-cloud.md`](.agents/skills/aether/claude-code-cloud.md). Sessions are ephemeral — commit and push changes regularly.
|
|
28
|
+
- **Cursor Cloud** if `$HOME` starts with `/root` or `/home/ubuntu`, OR `uname -s` reports `Linux` in a container-shaped path, OR a "Dev Server" terminal was auto-started from `.agents/environment.json`, AND you are running inside Cursor. → Read [`cursor-cloud.md`](.agents/skills/aether/cursor-cloud.md).
|
|
28
29
|
- **Local dev** if `$HOME` is under `/Users/…` (macOS) or a normal Linux/Windows user home, and no "Dev Server" terminal is auto-running. → If `.env` and `node_modules/` are present, you're set up; otherwise read [`local-setup.md`](.agents/skills/aether/local-setup.md).
|
|
29
30
|
|
|
30
31
|
This check is cheap and only needs to run once per session.
|
package/package.json
CHANGED
package/skills/aether/SKILL.md
CHANGED
|
@@ -32,26 +32,27 @@ 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
|
-
| [agents.md](agents.md) | Conventions for developing ADK agents in `agents/**`. Read when writing or editing agent code.
|
|
49
|
-
| [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/**`).
|
|
50
|
-
| [mcp-servers.md](mcp-servers.md) | Conventions for developing MCP servers in `mcp-servers/**`. Read when writing or editing FastMCP servers.
|
|
51
|
-
| [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.
|
|
52
|
-
| [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.
|
|
53
|
-
| [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.
|
|
54
|
-
| [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.
|
|
55
|
-
| [
|
|
56
|
-
| [
|
|
57
|
-
| [
|
|
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
|
+
| [agents.md](agents.md) | Conventions for developing ADK agents in `agents/**`. Read when writing or editing agent code. |
|
|
49
|
+
| [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/**`). |
|
|
50
|
+
| [mcp-servers.md](mcp-servers.md) | Conventions for developing MCP servers in `mcp-servers/**`. Read when writing or editing FastMCP servers. |
|
|
51
|
+
| [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. |
|
|
52
|
+
| [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. |
|
|
53
|
+
| [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. |
|
|
54
|
+
| [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. |
|
|
55
|
+
| [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`. |
|
|
56
|
+
| [git-support.md](git-support.md) | Git commit workflow and conventions. Read when finishing implementation work, making commits, or troubleshooting git/pre-commit failures. |
|
|
57
|
+
| [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. |
|
|
58
|
+
| [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,75 @@
|
|
|
1
|
+
If you are in a claude.ai/code cloud session, the `environment.json` install
|
|
2
|
+
step runs `init-project.js` and `npm install` automatically, and starts a dev
|
|
3
|
+
server on port 3000.
|
|
4
|
+
|
|
5
|
+
**Verify before starting:** check that `.env` exists and `node_modules/` is
|
|
6
|
+
present. If either is missing, run: `node init-project.js && npm install`
|
|
7
|
+
|
|
8
|
+
**Do NOT** manually run `nvm install` or `nvm use` — Node version is managed
|
|
9
|
+
by the environment.
|
|
10
|
+
|
|
11
|
+
### Sessions are ephemeral
|
|
12
|
+
|
|
13
|
+
Each claude.ai/code session clones a fresh copy of the repo. Uncommitted
|
|
14
|
+
changes are lost when the session ends. Commit and push work regularly.
|
|
15
|
+
|
|
16
|
+
### GitHub connection required
|
|
17
|
+
|
|
18
|
+
The repo must be hosted on GitHub. On first use, you will be prompted to
|
|
19
|
+
install the Claude GitHub App on the repository. Alternatively, run
|
|
20
|
+
`/web-setup` in Claude Code to sync a local `gh` CLI token to your account.
|
|
21
|
+
Both public and private repos are supported.
|
|
22
|
+
|
|
23
|
+
### Initial environment setup only
|
|
24
|
+
|
|
25
|
+
This subsection applies ONLY when first asked to "set up the development
|
|
26
|
+
environment" or "demonstrate that the environment is working." It does
|
|
27
|
+
**NOT** apply to ongoing development — once the app is built, use the
|
|
28
|
+
browser normally to test and verify UI changes.
|
|
29
|
+
|
|
30
|
+
**During initial setup**, skip browser/UI testing. The starter UI is a
|
|
31
|
+
placeholder template that will be replaced by `/build_my_app`. Do not
|
|
32
|
+
launch a browser, record videos, or take screenshots at this stage.
|
|
33
|
+
Verifying `npm run build` passes is sufficient.
|
|
34
|
+
|
|
35
|
+
1. Check the "Dev Server" terminal output for a line containing
|
|
36
|
+
`Listening on` or `Local: http://localhost:3000`. If present, the
|
|
37
|
+
environment is working.
|
|
38
|
+
2. If the dev server is NOT running, start it with `npm run dev` and wait
|
|
39
|
+
for the "Listening on" line.
|
|
40
|
+
3. Run `npm run build` to verify the project compiles.
|
|
41
|
+
4. Once confirmed, tell the user the environment is ready, then
|
|
42
|
+
immediately run the `/build_my_app` command.
|
|
43
|
+
|
|
44
|
+
### MCP tools
|
|
45
|
+
|
|
46
|
+
Lovelace MCP servers (`lovelace-elemental`, `lovelace-stocks`, etc.) are
|
|
47
|
+
available after running `/broadchurch_setup`, which writes `.agents/mcp.json`
|
|
48
|
+
with the tenant's portal proxy URLs. Check your tool list for `elemental_*`
|
|
49
|
+
tools. If they're not available, use the Elemental API client
|
|
50
|
+
(`useElementalClient()`) and the skill docs in `.agents/skills/elemental-api/`
|
|
51
|
+
and `.agents/skills/data-model/` for platform data access instead.
|
|
52
|
+
|
|
53
|
+
### Technical details
|
|
54
|
+
|
|
55
|
+
Node 20 is the baseline (`.nvmrc`). The `environment.json` install step
|
|
56
|
+
handles this via `nvm install 20 && nvm alias default 20`. Newer Node
|
|
57
|
+
versions (22, 25) generally work but may produce `EBADENGINE` warnings
|
|
58
|
+
during install — safe to ignore.
|
|
59
|
+
|
|
60
|
+
The install step runs `node init-project.js --local` (creates `.env` if
|
|
61
|
+
absent) then `npm install` (triggers `postinstall` → `nuxt prepare`).
|
|
62
|
+
Auth0 is bypassed via `NUXT_PUBLIC_USER_NAME=dev-user`
|
|
63
|
+
in the generated `.env`.
|
|
64
|
+
|
|
65
|
+
**No automated test suite.** Verification is `npm run build` (compile
|
|
66
|
+
check) and `npm run format:check` (Prettier). See Verification Commands.
|
|
67
|
+
|
|
68
|
+
**Before committing:** always run `npm run format` — the husky pre-commit
|
|
69
|
+
hook runs `lint-staged` with `prettier --check` and will reject
|
|
70
|
+
unformatted files.
|
|
71
|
+
|
|
72
|
+
### Availability
|
|
73
|
+
|
|
74
|
+
claude.ai/code is available on Pro, Max, Team, and Enterprise plans
|
|
75
|
+
(Research Preview). Sessions are billed against your plan's usage.
|