@yottagraph-app/aether-instructions 1.1.44 → 1.1.45

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.
Files changed (12) hide show
  1. package/AGENTS.md +16 -12
  2. package/README.md +13 -8
  3. package/commands/build_my_app.md +9 -9
  4. package/commands/deploy_mcp.md +3 -3
  5. package/commands/update_instructions.md +105 -53
  6. package/package.json +1 -1
  7. package/skills/aether/SKILL.md +1 -1
  8. package/skills/aether/cursor-cloud.md +1 -1
  9. package/skills/aether/data.md +4 -4
  10. package/skills/aether/instructions_warning.md +9 -6
  11. package/skills/aether/mcp-servers.md +1 -1
  12. package/variants/mcp-only/commands/build_my_app.md +5 -5
package/AGENTS.md CHANGED
@@ -1,14 +1,14 @@
1
1
  # Aether
2
2
 
3
- **Read first:** [`.cursor/skills/aether/SKILL.md`](.cursor/skills/aether/SKILL.md) — the Aether skill indexes every topic below and is the canonical entry point for any work in this repo.
3
+ **Read first:** [`.agents/skills/aether/SKILL.md`](.agents/skills/aether/SKILL.md) — the Aether skill indexes every topic below and is the canonical entry point for any work in this repo.
4
4
 
5
5
  **Stack:** Nuxt 3 (SPA), Vue 3 Composition API (`<script setup>`), Vuetify 3, TypeScript (required), Auth0.
6
6
 
7
7
  **Structure:** `pages/` (file-based routing), `components/`, `composables/`, `server/api/`, `agents/` (Python ADK), `mcp-servers/` (Python FastMCP).
8
8
 
9
- **Data:** This app runs on the Lovelace platform -- entities, news, filings, sentiment, relationships, events. See [`data.md`](.cursor/skills/aether/data.md) in the `aether` skill for access patterns and gotchas. Additional skill docs: `skills/data-model/` (entity types, properties, relationships; `SKILL.md` first), `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.
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`](.cursor/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).
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
 
@@ -18,24 +18,28 @@
18
18
 
19
19
  ## Task-specific topics
20
20
 
21
- The `aether` skill (`.cursor/skills/aether/SKILL.md`) covers architecture, data, UI cookbook, agents, MCP servers, deployment, env, storage, troubleshooting, and more. Read `SKILL.md` first; it's a short index that points you to the specific topic file you need.
21
+ The `aether` skill (`.agents/skills/aether/SKILL.md`) covers architecture, data, UI cookbook, agents, MCP servers, deployment, env, storage, troubleshooting, and more. Read `SKILL.md` first; it's a short index that points you to the specific topic file you need.
22
22
 
23
23
  ## Environment
24
24
 
25
25
  Detect your runtime once at startup, then read the matching topic in the `aether` skill:
26
26
 
27
- - **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 `.cursor/environment.json`. → Read [`cursor-cloud.md`](.cursor/skills/aether/cursor-cloud.md).
28
- - **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`](.cursor/skills/aether/local-setup.md).
27
+ - **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`. → Read [`cursor-cloud.md`](.agents/skills/aether/cursor-cloud.md).
28
+ - **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
29
 
30
30
  This check is cheap and only needs to run once per session.
31
31
 
32
- ### Cursor instructions (`.cursor/`)
32
+ ### Agent instructions (`.agents/`)
33
33
 
34
- Cursor commands and skills are installed from the
35
- `@yottagraph-app/aether-instructions` npm package during project init.
36
- `.cursor/skills/aether/` is the main Aether skill.
37
- `.cursor/skills/elemental-api/` contains API skill documentation (endpoint
38
- reference, types, usage patterns). `.cursor/skills/data-model/` contains
34
+ Agent commands and skills are installed from the
35
+ `@yottagraph-app/aether-instructions` npm package during project init, under
36
+ `.agents/`. `.cursor` and `.claude` are symlinks to `.agents/`, and
37
+ `.mcp.json` is a symlink to `.agents/mcp.json`, so Cursor and Claude Code
38
+ both read the same files.
39
+
40
+ `.agents/skills/aether/` is the main Aether skill.
41
+ `.agents/skills/elemental-api/` contains API skill documentation (endpoint
42
+ reference, types, usage patterns). `.agents/skills/data-model/` contains
39
43
  Lovelace data model documentation (entity types, schemas per fetch source).
40
44
  If these directories are missing, run `/update_instructions` to reinstall.
41
45
 
package/README.md CHANGED
@@ -1,6 +1,7 @@
1
1
  # @yottagraph-app/aether-instructions
2
2
 
3
- Cursor commands and skills for Aether development.
3
+ Agent commands and skills for Aether development (used by Cursor and
4
+ Claude Code).
4
5
 
5
6
  The core Aether guidance (architecture, data, UI, agents, MCP servers,
6
7
  deployment, etc.) ships as the **`aether` skill** under `skills/aether/`,
@@ -11,6 +12,10 @@ with a `SKILL.md` entry point that indexes the topic files.
11
12
  This package is automatically downloaded and extracted during Aether project
12
13
  initialization (`init-project.js`). You don't need to install it directly.
13
14
 
15
+ Files install under `.agents/`. `.cursor` and `.claude` are whole-directory
16
+ symlinks to `.agents/`, and `.mcp.json` at the repo root is a symlink to
17
+ `.agents/mcp.json`, so Cursor and Claude Code read the same files.
18
+
14
19
  ### Updating Instructions
15
20
 
16
21
  To update to the latest version:
@@ -19,20 +24,20 @@ To update to the latest version:
19
24
  /update_instructions
20
25
  ```
21
26
 
22
- This Cursor command will:
27
+ This command will:
23
28
 
24
29
  1. Download the latest version of this package
25
- 2. Replace files in `.cursor/` that are listed in `.cursor/.aether-instructions-manifest`
26
- 3. Remove the deprecated `.cursor/rules/` directory if present (rules were replaced by the `aether` skill)
30
+ 2. Replace files in `.agents/` that are listed in `.agents/.aether-instructions-manifest`
31
+ 3. Remove the deprecated `.agents/rules/` directory if present (rules were replaced by the `aether` skill)
27
32
  4. Extract fresh files from the package
28
33
  5. Commit the changes
29
34
 
30
35
  ### File Naming Convention
31
36
 
32
- Package files keep their original names under `.cursor/commands/` and
33
- `.cursor/skills/`. Which paths are owned by the package is recorded in
34
- `.cursor/.aether-instructions-manifest`. Only those paths are overwritten on
35
- update; other files under `.cursor/` are not touched by the updater.
37
+ Package files keep their original names under `.agents/commands/` and
38
+ `.agents/skills/`. Which paths are owned by the package is recorded in
39
+ `.agents/.aether-instructions-manifest`. Only those paths are overwritten on
40
+ update; other files under `.agents/` are not touched by the updater.
36
41
 
37
42
  ### Customizing Commands or Skill Topics
38
43
 
package/commands/build_my_app.md CHANGED
@@ -48,7 +48,7 @@ If design reference images exist (screenshots from Figma or other design tools):
48
48
 
49
49
  1. **Examine each image** -- these are design mockups from the project creator showing what the app should look like.
50
50
  2. Describe what you see in each image: layout structure, navigation patterns, component types, color usage, typography.
51
- 3. Map visual elements to **Vuetify components** (cards = `v-card`, data tables = `v-data-table`, navigation drawers = `v-navigation-drawer`, app bars = `v-app-bar`, etc.). If a `vuetify-figma` skill is available in `.cursor/skills/`, read it for detailed component mapping guidance.
51
+ 3. Map visual elements to **Vuetify components** (cards = `v-card`, data tables = `v-data-table`, navigation drawers = `v-navigation-drawer`, app bars = `v-app-bar`, etc.). If a `vuetify-figma` skill is available in `.agents/skills/`, read it for detailed component mapping guidance.
52
52
  4. Use the design references alongside the Vision text to plan the UX. The images show _what it should look like_; the Vision text explains _what it should do_.
53
53
 
54
54
  If a Figma URL is referenced in DESIGN.md, note it for the user but don't attempt to fetch it -- work from the uploaded screenshots and the text brief.
@@ -64,15 +64,15 @@ tools like `elemental_get_schema`, `elemental_get_entity`, etc.
64
64
  tools (entity search, market data, news, etc.) that you can use during
65
65
  development.
66
66
 
67
- **If MCP tools are NOT available:** Check if `.cursor/mcp.json` exists:
67
+ **If MCP tools are NOT available:** Check if `.agents/mcp.json` exists:
68
68
 
69
69
  ```bash
70
- cat .cursor/mcp.json 2>/dev/null
70
+ cat .agents/mcp.json 2>/dev/null
71
71
  ```
72
72
 
73
73
  If the file exists but tools aren't showing, they may need to be enabled:
74
74
 
75
- > Your project has Lovelace MCP servers configured (`.cursor/mcp.json`),
75
+ > Your project has Lovelace MCP servers configured (`.agents/mcp.json`),
76
76
  > but they don't appear to be active yet. Cursor disables new MCP servers
77
77
  > by default.
78
78
  >
@@ -95,17 +95,17 @@ First, ensure dependencies are installed (types aren't available without this):
95
95
  test -d node_modules || npm install
96
96
  ```
97
97
 
98
- Skills in `.cursor/skills/` are populated during project init (`node init-project.js`).
98
+ Skills in `.agents/skills/` are populated during project init (`node init-project.js`).
99
99
  If that directory is empty after `npm install`, run `node init-project.js` to install them.
100
100
 
101
101
  Then read these files to understand what's available:
102
102
 
103
103
  1. `DESIGN.md` -- project vision and current status
104
104
  2. `broadchurch.yaml` -- project config (name, gateway URL, etc.)
105
- 3. **The `aether` skill's `data.md` topic** (`.cursor/skills/aether/data.md`) — this is critical. It describes the Query Server, the platform's primary data source. Build against platform APIs, not external sources.
106
- 4. **`.cursor/skills/`** — Each subdirectory is one skill. Start with `.cursor/skills/aether/SKILL.md` — it's the index for every Aether topic (architecture, data, UI, agents, MCP, deployment, etc.). Then open each other skill's entry (usually `SKILL.md`) and follow its structure to learn what is documented (APIs, schemas, helpers, etc.).
105
+ 3. **The `aether` skill's `data.md` topic** (`.agents/skills/aether/data.md`) — this is critical. It describes the Query Server, the platform's primary data source. Build against platform APIs, not external sources.
106
+ 4. **`.agents/skills/`** — Each subdirectory is one skill. Start with `.agents/skills/aether/SKILL.md` — it's the index for every Aether topic (architecture, data, UI, agents, MCP, deployment, etc.). Then open each other skill's entry (usually `SKILL.md`) and follow its structure to learn what is documented (APIs, schemas, helpers, etc.).
107
107
 
108
- **Important: Use the platform's data.** This app runs on the Lovelace platform, which provides a Query Server with entities, news, filings, sentiment, relationships, events, and more. Read [`data.md`](../skills/aether/data.md) in the `aether` skill and the other skills under `.cursor/skills/` to understand what data is available. Use `getSchema()` to discover entity types and properties at runtime.
108
+ **Important: Use the platform's data.** This app runs on the Lovelace platform, which provides a Query Server with entities, news, filings, sentiment, relationships, events, and more. Read [`data.md`](../skills/aether/data.md) in the `aether` skill and the other skills under `.agents/skills/` to understand what data is available. Use `getSchema()` to discover entity types and properties at runtime.
109
109
 
110
110
  Key capabilities:
111
111
 
@@ -113,7 +113,7 @@ Key capabilities:
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
115
  - **AI agent chat** -- use the `useAgentChat` composable to build a chat UI for deployed agents
116
- - **MCP servers** -- Lovelace MCP servers may be available (check `.cursor/mcp.json`)
116
+ - **MCP servers** -- Lovelace MCP servers may be available (check `.agents/mcp.json`)
117
117
  - **Components** -- Vuetify 3 component library is available
118
118
 
119
119
  ---
package/commands/deploy_mcp.md CHANGED
@@ -122,9 +122,9 @@ curl -sf -X POST "<GATEWAY_URL>/api/projects/<ORG_ID>/deploy" \
122
122
 
123
123
  ## Step 7: Register in Cursor MCP Config
124
124
 
125
- After deployment completes, add the new server to `.cursor/mcp.json` so Cursor can connect to it through the Portal Gateway proxy.
125
+ After deployment completes, add the new server to `.agents/mcp.json` so Cursor and Claude Code can connect to it through the Portal Gateway proxy.
126
126
 
127
- Read `.cursor/mcp.json`, then add a new entry for the server:
127
+ Read `.agents/mcp.json`, then add a new entry for the server:
128
128
 
129
129
  ```json
130
130
  {
@@ -136,7 +136,7 @@ Read `.cursor/mcp.json`, then add a new entry for the server:
136
136
 
137
137
  Where `<SERVER_NAME>`, `<GATEWAY_URL>`, and `<ORG_ID>` are the values from Steps 1-2.
138
138
 
139
- Write the updated JSON back to `.cursor/mcp.json`.
139
+ Write the updated JSON back to `.agents/mcp.json`.
140
140
 
141
141
  > The MCP server is now registered. Cursor will connect to it through the Portal Gateway proxy — no credentials needed.
142
142
  >
package/commands/update_instructions.md CHANGED
@@ -1,32 +1,73 @@
1
1
  # Update Instructions
2
2
 
3
- Update Cursor commands and skills from the `@yottagraph-app/aether-instructions` npm package.
3
+ Update agent commands and skills from the `@yottagraph-app/aether-instructions` npm package.
4
4
 
5
5
  ## Overview
6
6
 
7
- This command downloads the latest instructions package and extracts it to your `.cursor/` directory. A manifest file (`.cursor/.aether-instructions-manifest`) tracks which files came from the package so updates only replace package-provided files.
7
+ This command downloads the latest instructions package and extracts it to `.agents/`. A manifest file (`.agents/.aether-instructions-manifest`) tracks which files came from the package so updates only replace package-provided files.
8
+
9
+ `.cursor/` and `.claude/` are whole-directory symlinks to `.agents/`, and `.mcp.json` is a symlink to `.agents/mcp.json`. Cursor and Claude Code therefore both read the same files; in the repo itself every reference points at the real `.agents/` path.
8
10
 
9
11
  **What happens:**
10
12
 
11
- 1. Downloads the latest `@yottagraph-app/aether-instructions` package
12
- 2. Deletes files listed in the existing manifest
13
- 3. Removes the deprecated `.cursor/rules/` directory if present (rules were replaced by the `aether` skill)
14
- 4. Extracts fresh files from the package
15
- 5. Writes a new manifest
16
- 6. Commits the changes
13
+ 1. Ensures the `.agents/` layout exists (migrating a legacy `.cursor/` directory and creating the `.cursor`, `.claude`, `.mcp.json` symlinks as needed)
14
+ 2. Downloads the latest `@yottagraph-app/aether-instructions` package
15
+ 3. Deletes files listed in the existing manifest
16
+ 4. Removes the deprecated `.agents/rules/` directory if present (rules were replaced by the `aether` skill)
17
+ 5. Extracts fresh files from the package
18
+ 6. Writes a new manifest
19
+ 7. Commits the changes
17
20
 
18
- **Your files are safe:** Only paths listed in the manifest are removed before reinstall. Other files under `.cursor/` are left alone.
21
+ **Your files are safe:** Only paths listed in the manifest are removed before reinstall. Other files under `.agents/` are left alone.
19
22
 
20
- **Shell compatibility:** Run the bash snippets below with **`bash`**, not bare `zsh`. An **empty line** in the manifest can make `rm -rf ".cursor/$rel"` delete **all of `.cursor/`** — Step 4 skips blank lines to avoid that.
23
+ **Shell compatibility:** Run the bash snippets below with **`bash`**, not bare `zsh`. An **empty line** in the manifest can make `rm -rf ".agents/$rel"` delete **all of `.agents/`** — Step 5 skips blank lines to avoid that.
21
24
 
22
25
  ---
23
26
 
24
- ## Step 1: Check Current Version
27
+ ## Step 1: Ensure `.agents/` Layout
28
+
29
+ Detect and perform any one-time migration from the legacy `.cursor/` directory, then make sure the `.cursor`, `.claude`, and `.mcp.json` symlinks exist.
30
+
31
+ ```bash
32
+ # Case 1: .cursor is already a symlink (previously migrated) — nothing to do here
33
+ if [ -L .cursor ]; then
34
+ :
35
+ # Case 2: Fresh install — create .agents/ and symlinks
36
+ elif [ ! -e .cursor ]; then
37
+ mkdir -p .agents
38
+ # Case 3: Legacy layout — migrate .cursor/ → .agents/
39
+ elif [ -d .cursor ]; then
40
+ # Collision guards
41
+ if [ -e .agents ] && [ ! -L .agents ]; then
42
+ echo "Error: both .cursor/ and .agents/ exist as real paths. Resolve manually, then re-run /update_instructions." >&2
43
+ exit 1
44
+ fi
45
+ if [ -d .claude ] && [ ! -L .claude ] && [ -n "$(ls -A .claude 2>/dev/null)" ]; then
46
+ echo "Error: .claude/ exists as a real directory with contents. Move or remove it, then re-run /update_instructions." >&2
47
+ exit 1
48
+ fi
49
+ mv .cursor .agents
50
+ echo "Migrated .cursor/ → .agents/"
51
+ fi
52
+
53
+ # Create symlinks if absent
54
+ [ -e .cursor ] || ln -s .agents .cursor
55
+ [ -e .claude ] || ln -s .agents .claude
56
+ [ -e .mcp.json ] || ln -s .agents/mcp.json .mcp.json
57
+ ```
58
+
59
+ Report to user:
60
+
61
+ > Layout ready: `.agents/` (canonical), with `.cursor`, `.claude`, and `.mcp.json` symlinks for tool compatibility.
62
+
63
+ ---
64
+
65
+ ## Step 2: Check Current Version
25
66
 
26
67
  Read the current installed version:
27
68
 
28
69
  ```bash
29
- cat .cursor/.aether-instructions-version 2>/dev/null || echo "Not installed"
70
+ cat .agents/.aether-instructions-version 2>/dev/null || echo "Not installed"
30
71
  ```
31
72
 
32
73
  Report to user:
@@ -35,7 +76,7 @@ Report to user:
35
76
 
36
77
  ---
37
78
 
38
- ## Step 2: Check Latest Version
79
+ ## Step 3: Check Latest Version
39
80
 
40
81
  Query npm for the latest version:
41
82
 
@@ -51,7 +92,7 @@ Compare with current:
51
92
 
52
93
  ---
53
94
 
54
- ## Step 3: Download Package
95
+ ## Step 4: Download Package
55
96
 
56
97
  Create a temporary directory and download the package:
57
98
 
@@ -70,12 +111,12 @@ The extracted content is in `$TEMP_DIR/package/`.
70
111
 
71
112
  ---
72
113
 
73
- ## Step 4: Delete Previously Installed Files
114
+ ## Step 5: Delete Previously Installed Files
74
115
 
75
- Read the manifest and delete listed paths. **Skip blank lines** — an empty `rel` would run `rm -rf ".cursor/"` and wipe the whole directory. Entries prefixed with `root/` point at files at the repo root (currently `AGENTS.md` and `CLAUDE.md`); only remove **regular files** there, never directories.
116
+ Read the manifest and delete listed paths. **Skip blank lines** — an empty `rel` would run `rm -rf ".agents/"` and wipe the whole directory. Entries prefixed with `root/` point at files at the repo root (currently `AGENTS.md` and `CLAUDE.md`); only remove **regular files** there, never directories.
76
117
 
77
118
  ```bash
78
- if [ -f .cursor/.aether-instructions-manifest ]; then
119
+ if [ -f .agents/.aether-instructions-manifest ]; then
79
120
  while IFS= read -r rel || [ -n "$rel" ]; do
80
121
  [ -z "$rel" ] && continue
81
122
  case "$rel" in
@@ -85,34 +126,34 @@ if [ -f .cursor/.aether-instructions-manifest ]; then
85
126
  [ -f "$target" ] && rm -f "$target"
86
127
  ;;
87
128
  *)
88
- rm -rf ".cursor/$rel"
129
+ rm -rf ".agents/$rel"
89
130
  ;;
90
131
  esac
91
- done < .cursor/.aether-instructions-manifest
132
+ done < .agents/.aether-instructions-manifest
92
133
  fi
93
134
  ```
94
135
 
95
- Also remove the deprecated `.cursor/rules/` directory (superseded by the `aether` skill in `.cursor/skills/aether/`):
136
+ Also remove the deprecated `.agents/rules/` directory (superseded by the `aether` skill in `.agents/skills/aether/`):
96
137
 
97
138
  ```bash
98
- rm -rf .cursor/rules
139
+ rm -rf .agents/rules
99
140
  ```
100
141
 
101
142
  ---
102
143
 
103
- ## Step 5: Copy New Files
144
+ ## Step 6: Copy New Files
104
145
 
105
146
  Create directories if needed:
106
147
 
107
148
  ```bash
108
- mkdir -p .cursor/commands .cursor/skills
149
+ mkdir -p .agents/commands .agents/skills
109
150
  ```
110
151
 
111
152
  Copy files from the extracted package:
112
153
 
113
154
  ```bash
114
- cp "$TEMP_DIR/package/commands/"* .cursor/commands/ 2>/dev/null || true
115
- cp -r "$TEMP_DIR/package/skills/"* .cursor/skills/ 2>/dev/null || true
155
+ cp "$TEMP_DIR/package/commands/"* .agents/commands/ 2>/dev/null || true
156
+ cp -r "$TEMP_DIR/package/skills/"* .agents/skills/ 2>/dev/null || true
116
157
  ```
117
158
 
118
159
  Copy the root-level AGENTS.md and CLAUDE.md from the package to the tenant repo root, if the package ships them. `CLAUDE.md` is a one-line `@AGENTS.md` pointer so Claude Code imports the same instructions Cursor reads from `AGENTS.md`:
@@ -127,40 +168,40 @@ Copy the root-level AGENTS.md and CLAUDE.md from the package to the tenant repo
127
168
  If this project uses **mcp-only** (or another non-default mode), re-apply the same overlay `init-project.js` uses. Read the saved mode:
128
169
 
129
170
  ```bash
130
- MODE=$(tr -d '\n' < .cursor/.aether-data-mode 2>/dev/null || echo "api-mcp")
171
+ MODE=$(tr -d '\n' < .agents/.aether-data-mode 2>/dev/null || echo "api-mcp")
131
172
  PKG="$TEMP_DIR/package"
132
173
  if [ "$MODE" != "api-mcp" ] && [ -d "$PKG/variants/$MODE/commands" ]; then
133
- cp "$PKG/variants/$MODE/commands/"* .cursor/commands/ 2>/dev/null || true
174
+ cp "$PKG/variants/$MODE/commands/"* .agents/commands/ 2>/dev/null || true
134
175
  fi
135
176
  if [ "$MODE" != "api-mcp" ] && [ -d "$PKG/variants/$MODE/skills" ]; then
136
177
  # Overlay per-file so default skill topics survive
137
178
  for src_dir in "$PKG/variants/$MODE/skills/"*/; do
138
179
  [ -d "$src_dir" ] || continue
139
180
  dir_name=$(basename "$src_dir")
140
- mkdir -p ".cursor/skills/$dir_name"
141
- cp "$src_dir"* ".cursor/skills/$dir_name/" 2>/dev/null || true
181
+ mkdir -p ".agents/skills/$dir_name"
182
+ cp "$src_dir"* ".agents/skills/$dir_name/" 2>/dev/null || true
142
183
  done
143
184
  fi
144
185
  if [ "$MODE" = "mcp-only" ]; then
145
- rm -rf .cursor/skills/elemental-api
186
+ rm -rf .agents/skills/elemental-api
146
187
  fi
147
188
  ```
148
189
 
149
- If `.cursor/.aether-data-mode` is missing, skip the overlay (defaults to **api-mcp**).
190
+ If `.agents/.aether-data-mode` is missing, skip the overlay (defaults to **api-mcp**).
150
191
 
151
192
  ---
152
193
 
153
- ## Step 6: Write Manifest and Version Marker
194
+ ## Step 7: Write Manifest and Version Marker
154
195
 
155
- Build a manifest of all installed files (one relative path per line). **Do not** build a string with a leading `\n` — that writes a blank first line and breaks Step 4. Prefer one `echo` per line:
196
+ Build a manifest of all installed files (one relative path per line). **Do not** build a string with a leading `\n` — that writes a blank first line and breaks Step 5. Prefer one `echo` per line:
156
197
 
157
198
  ```bash
158
199
  {
159
- for f in .cursor/commands/*.md; do [ -f "$f" ] && echo "commands/$(basename "$f")"; done
160
- for d in .cursor/skills/*/; do [ -d "$d" ] && echo "skills/$(basename "$d")"; done
200
+ for f in .agents/commands/*.md; do [ -f "$f" ] && echo "commands/$(basename "$f")"; done
201
+ for d in .agents/skills/*/; do [ -d "$d" ] && echo "skills/$(basename "$d")"; done
161
202
  [ -f "$TEMP_DIR/package/AGENTS.md" ] && [ -f ./AGENTS.md ] && echo "root/AGENTS.md"
162
203
  [ -f "$TEMP_DIR/package/CLAUDE.md" ] && [ -f ./CLAUDE.md ] && echo "root/CLAUDE.md"
163
- } > .cursor/.aether-instructions-manifest
204
+ } > .agents/.aether-instructions-manifest
164
205
  ```
165
206
 
166
207
  If the repo uses **bash** for this loop and a glob might match nothing, run `shopt -s nullglob` first so the loops don't treat `*.md` as a literal filename.
@@ -168,12 +209,12 @@ If the repo uses **bash** for this loop and a glob might match nothing, run `sho
168
209
  Write the version marker:
169
210
 
170
211
  ```bash
171
- grep -o '"version": *"[^"]*"' "$TEMP_DIR/package/package.json" | grep -o '[0-9][^"]*' > .cursor/.aether-instructions-version
212
+ grep -o '"version": *"[^"]*"' "$TEMP_DIR/package/package.json" | grep -o '[0-9][^"]*' > .agents/.aether-instructions-version
172
213
  ```
173
214
 
174
215
  ---
175
216
 
176
- ## Step 7: Cleanup
217
+ ## Step 8: Cleanup
177
218
 
178
219
  Remove the temporary directory:
179
220
 
@@ -183,14 +224,14 @@ rm -rf "$TEMP_DIR"
183
224
 
184
225
  ---
185
226
 
186
- ## Step 8: Report Changes
227
+ ## Step 9: Report Changes
187
228
 
188
229
  Count what was installed:
189
230
 
190
231
  ```bash
191
- wc -l < .cursor/.aether-instructions-manifest
192
- ls .cursor/commands/*.md 2>/dev/null | wc -l
193
- ls -d .cursor/skills/*/ 2>/dev/null | wc -l
232
+ wc -l < .agents/.aether-instructions-manifest
233
+ ls .agents/commands/*.md 2>/dev/null | wc -l
234
+ ls -d .agents/skills/*/ 2>/dev/null | wc -l
194
235
  ```
195
236
 
196
237
  Report to user:
@@ -202,17 +243,24 @@ Report to user:
202
243
 
203
244
  ---
204
245
 
205
- ## Step 9: Commit Changes
246
+ ## Step 10: Commit Changes
206
247
 
207
- Commit the updated instruction files. A root `.gitignore` rule like `skills/` can **ignore** `.cursor/skills/`; if `git add .cursor/skills/` reports ignored paths, force-add:
248
+ Commit the updated instruction files and (on first migration) the new symlinks. A root `.gitignore` rule like `skills/` can **ignore** `.agents/skills/`; if `git add .agents/skills/` reports ignored paths, force-add:
208
249
 
209
250
  ```bash
210
- git add .cursor/commands/ .cursor/.aether-instructions-version .cursor/.aether-instructions-manifest
211
- git add -f .cursor/skills/
251
+ git add .agents/commands/ .agents/.aether-instructions-version .agents/.aether-instructions-manifest
252
+ git add -f .agents/skills/
253
+ # Symlinks (no-ops if they were already tracked)
254
+ [ -L .cursor ] && git add .cursor
255
+ [ -L .claude ] && git add .claude
256
+ [ -L .mcp.json ] && git add .mcp.json
212
257
  [ -f AGENTS.md ] && git add AGENTS.md
213
258
  [ -f CLAUDE.md ] && git add CLAUDE.md
214
259
  # Remove the legacy rules dir from tracking if it was committed in an earlier install
215
- git rm -rf --cached --ignore-unmatch .cursor/rules 2>/dev/null || true
260
+ git rm -rf --cached --ignore-unmatch .agents/rules 2>/dev/null || true
261
+ # If we just migrated, drop the old .cursor/ path from tracking so git records the symlink instead of the directory
262
+ git rm -rf --cached --ignore-unmatch .cursor 2>/dev/null || true
263
+ [ -L .cursor ] && git add .cursor
216
264
  git commit -m "Update instructions to vX.Y.Z"
217
265
  ```
218
266
 
@@ -234,7 +282,7 @@ If `npm pack` fails with a registry error:
234
282
 
235
283
  If you get permission errors:
236
284
 
237
- > Try running with appropriate permissions, or check that `.cursor/` is writable.
285
+ > Try running with appropriate permissions, or check that `.agents/` is writable.
238
286
 
239
287
  ### Want to customize a command, skill topic, or AGENTS.md?
240
288
 
@@ -242,14 +290,18 @@ If you need to modify a package-provided file (including the root `AGENTS.md` or
242
290
 
243
291
  1. Edit it directly — your changes will persist until the next update
244
292
  2. To preserve changes across updates, copy it to a new name first (e.g. `cp AGENTS.md AGENTS.local.md`)
245
- 3. Remove the original's entry from `.cursor/.aether-instructions-manifest` so it won't be deleted on update (for `AGENTS.md`, remove the `root/AGENTS.md` line; for `CLAUDE.md`, remove `root/CLAUDE.md`)
293
+ 3. Remove the original's entry from `.agents/.aether-instructions-manifest` so it won't be deleted on update (for `AGENTS.md`, remove the `root/AGENTS.md` line; for `CLAUDE.md`, remove `root/CLAUDE.md`)
246
294
 
247
295
  `CLAUDE.md` ships as a one-line `@AGENTS.md` pointer — Claude Code imports `AGENTS.md` via that syntax, so in most cases you only need to edit `AGENTS.md`.
248
296
 
249
- ### Blank line in manifest deleted `.cursor/`
297
+ ### Blank line in manifest deleted `.agents/`
298
+
299
+ Regenerate the manifest with Step 7 (echo-per-line form). Ensure Step 5 skips empty lines.
300
+
301
+ ### `git add` says `.agents/skills` is ignored
250
302
 
251
- Regenerate the manifest with Step 6 (echo-per-line form). Ensure Step 4 skips empty lines.
303
+ Use `git add -f .agents/skills/` as in Step 10, or narrow `.gitignore` so `skills/` only ignores the project `skills/` folder (e.g. `/skills/` at repo root) instead of every `skills` path.
252
304
 
253
- ### `git add` says `.cursor/skills` is ignored
305
+ ### Migration aborted (collision)
254
306
 
255
- Use `git add -f .cursor/skills/` as in Step 9, or narrow `.gitignore` so `skills/` only ignores the project `skills/` folder (e.g. `/skills/` at repo root) instead of every `skills` path.
307
+ If Step 1 aborts because `.cursor/` and a real `.agents/` both exist, or `.claude/` has hand-written contents: decide which source is authoritative, back up the other, then re-run.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@yottagraph-app/aether-instructions",
3
- "version": "1.1.44",
3
+ "version": "1.1.45",
4
4
  "description": "Cursor commands and skills for Aether development",
5
5
  "files": [
6
6
  "commands",
package/skills/aether/SKILL.md CHANGED
@@ -54,4 +54,4 @@ topics that apply.
54
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
55
  | [git-support.md](git-support.md) | Git commit workflow and conventions. Read when finishing implementation work, making commits, or troubleshooting git/pre-commit failures. |
56
56
  | [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. |
57
- | [instructions_warning.md](instructions_warning.md) | Warning about editing `.cursor/` files managed by `@yottagraph-app/aether-instructions`. Read before modifying installed instruction files. |
57
+ | [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/cursor-cloud.md CHANGED
@@ -35,7 +35,7 @@ Lovelace MCP servers (`lovelace-elemental`, `lovelace-stocks`, etc.)
35
35
  should be available if configured at the org level. Check your tool list
36
36
  for `elemental_*` tools. If they're not available, use the Elemental API
37
37
  client (`useElementalClient()`) and the skill docs in
38
- `.cursor/skills/elemental-api/` and `.cursor/skills/data-model/` for platform data access instead.
38
+ `.agents/skills/elemental-api/` and `.agents/skills/data-model/` for platform data access instead.
39
39
 
40
40
  ### Technical details
41
41
 
package/skills/aether/data.md CHANGED
@@ -13,14 +13,14 @@ regularly — use the discovery-first pattern to find what's available.
13
13
  ## Skill Documentation
14
14
 
15
15
  For endpoint reference, response shapes, and edge cases, **read the
16
- elemental-api skill** in `.cursor/skills/elemental-api/` (start with `SKILL.md` and
16
+ elemental-api skill** in `.agents/skills/elemental-api/` (start with `SKILL.md` and
17
17
  follow the skill’s own structure). Files are copied from
18
18
  `@yottagraph-app/aether-instructions` (installed during project init). If
19
19
  the directory is missing, run `/update_instructions` to install it.
20
20
 
21
21
  ## Data model skill
22
22
 
23
- For Lovelace **entity types, properties, relationships, and per-source schemas** (EDGAR, FRED, FDIC, etc.), read the **data-model skill** in `.cursor/skills/data-model/`. Start with `SKILL.md`, then `overview.md` and the source-specific folders. Both skills are distributed via `@yottagraph-app/aether-instructions` and installed during project init.
23
+ For Lovelace **entity types, properties, relationships, and per-source schemas** (EDGAR, FRED, FDIC, etc.), read the **data-model skill** in `.agents/skills/data-model/`. Start with `SKILL.md`, then `overview.md` and the source-specific folders. Both skills are distributed via `@yottagraph-app/aether-instructions` and installed during project init.
24
24
 
25
25
  ## Test Before You Build
26
26
 
@@ -494,7 +494,7 @@ if (response.status === 404) {
494
494
 
495
495
  ## Lovelace MCP Servers
496
496
 
497
- Four MCP servers may be configured in `.cursor/mcp.json` for interactive
497
+ Four MCP servers may be configured in `.agents/mcp.json` for interactive
498
498
  data exploration. **Check your tool list** — if tools like
499
499
  `elemental_get_schema` appear, use them as your primary testing and
500
500
  exploration interface before writing code. If they don't appear, the
@@ -526,7 +526,7 @@ building REST-based features with `useElementalClient()`.
526
526
 
527
527
  ### Setup
528
528
 
529
- `.cursor/mcp.json` is auto-generated by `init-project.js`. If it's missing,
529
+ `.agents/mcp.json` is auto-generated by `init-project.js`. If it's missing,
530
530
  run `node init-project.js --local` to regenerate it. For provisioned projects,
531
531
  the servers route through the Portal Gateway proxy (no credentials needed).
532
532
  For local development without a gateway, the servers require an
package/skills/aether/instructions_warning.md CHANGED
@@ -2,13 +2,16 @@
2
2
 
3
3
  **You are editing a file managed by the `@yottagraph-app/aether-instructions` package.**
4
4
 
5
- Package-managed files are tracked by `.cursor/.aether-instructions-manifest`.
5
+ Package-managed files are tracked by `.agents/.aether-instructions-manifest`.
6
6
  They will be **overwritten** when you run `/update_instructions`.
7
7
 
8
- This includes files under `.cursor/commands/`, `.cursor/skills/`, **and the
8
+ This includes files under `.agents/commands/`, `.agents/skills/`, **and the
9
9
  root `AGENTS.md` and `CLAUDE.md`** (tracked as `root/AGENTS.md` and
10
10
  `root/CLAUDE.md` in the manifest).
11
11
 
12
+ `.cursor`, `.claude`, and `.mcp.json` are symlinks into `.agents/`, so any
13
+ path you see under those resolves to the same managed file.
14
+
12
15
  ## Do Not
13
16
 
14
17
  - Modify files listed in the manifest directly (changes will be lost on update)
@@ -19,19 +22,19 @@ If you need to modify a package-provided command, skill topic, or the root `AGEN
19
22
 
20
23
  1. **Copy** the file to a new name
21
24
  2. Make your changes to the copy
22
- 3. Remove the original's entry from `.cursor/.aether-instructions-manifest`
25
+ 3. Remove the original's entry from `.agents/.aether-instructions-manifest`
23
26
  so it won't be replaced on update
24
27
 
25
28
  Examples:
26
29
 
27
30
  ```bash
28
31
  # Customize a skill topic
29
- cp .cursor/skills/aether/data.md .cursor/skills/aether/data_custom.md
32
+ cp .agents/skills/aether/data.md .agents/skills/aether/data_custom.md
30
33
 
31
34
  # Customize AGENTS.md
32
35
  cp AGENTS.md AGENTS.local.md
33
36
  # then remove the `root/AGENTS.md` line from
34
- # .cursor/.aether-instructions-manifest
37
+ # .agents/.aether-instructions-manifest
35
38
 
36
39
  # Customize CLAUDE.md
37
40
  cp CLAUDE.md CLAUDE.local.md
@@ -42,7 +45,7 @@ cp CLAUDE.md CLAUDE.local.md
42
45
 
43
46
  ## How It Works
44
47
 
45
- - `.cursor/.aether-instructions-manifest` lists every file installed by the
48
+ - `.agents/.aether-instructions-manifest` lists every file installed by the
46
49
  package (one relative path per line, e.g. `skills/aether/data.md`). Entries
47
50
  prefixed with `root/` refer to files at the tenant repo root
48
51
  (currently `root/AGENTS.md` and `root/CLAUDE.md`).
package/skills/aether/mcp-servers.md CHANGED
@@ -88,7 +88,7 @@ Deploy with the `/deploy_mcp` Cursor command. This will:
88
88
  2. Deploy to Cloud Run with IAM authentication
89
89
  3. Grant invoker permissions to tenant and Portal service accounts
90
90
  4. Register the server in Firestore (via the Portal API)
91
- 5. Add the server to `.cursor/mcp.json` for Cursor IDE access
91
+ 5. Add the server to `.agents/mcp.json` for agent access (Cursor and Claude Code)
92
92
 
93
93
  ## Connecting MCP Servers to Agents
94
94
 
package/variants/mcp-only/commands/build_my_app.md CHANGED
@@ -55,7 +55,7 @@ If design reference images exist (screenshots from Figma or other design tools):
55
55
 
56
56
  1. **Examine each image** — these are design mockups from the project creator showing what the app should look like.
57
57
  2. Describe what you see in each image: layout structure, navigation patterns, component types, color usage, typography.
58
- 3. Map visual elements to **Vuetify components** (cards = `v-card`, data tables = `v-data-table`, navigation drawers = `v-navigation-drawer`, app bars = `v-app-bar`, etc.). If a `vuetify-figma` skill is available in `.cursor/skills/`, read it for detailed component mapping guidance.
58
+ 3. Map visual elements to **Vuetify components** (cards = `v-card`, data tables = `v-data-table`, navigation drawers = `v-navigation-drawer`, app bars = `v-app-bar`, etc.). If a `vuetify-figma` skill is available in `.agents/skills/`, read it for detailed component mapping guidance.
59
59
  4. Use the design references alongside the Vision text to plan the UX. The images show _what it should look like_; the Vision text explains _what it should do_.
60
60
 
61
61
  If a Figma URL is referenced in DESIGN.md, note it for the user but don't attempt to fetch it — work from the uploaded screenshots and the text brief.
@@ -66,15 +66,15 @@ If a Figma URL is referenced in DESIGN.md, note it for the user but don't attemp
66
66
 
67
67
  Check if Lovelace MCP tools are available (e.g. `elemental_get_schema`, `elemental_get_entity`). Use them while **authoring agents** and validating graph behavior.
68
68
 
69
- **If MCP tools are NOT available**, check `.cursor/mcp.json`:
69
+ **If MCP tools are NOT available**, check `.agents/mcp.json`:
70
70
 
71
71
  ```bash
72
- cat .cursor/mcp.json 2>/dev/null
72
+ cat .agents/mcp.json 2>/dev/null
73
73
  ```
74
74
 
75
75
  If the file exists but tools aren't active yet:
76
76
 
77
- > Your project has Lovelace MCP servers configured (`.cursor/mcp.json`), but they don't appear to be active yet. Cursor disables new MCP servers by default.
77
+ > Your project has Lovelace MCP servers configured (`.agents/mcp.json`), but they don't appear to be active yet. Cursor disables new MCP servers by default.
78
78
  >
79
79
  > Open **Cursor Settings** (Cmd+Shift+J on macOS) → **Tools & MCP** and enable the `lovelace-*` servers listed there. They should show green toggles when active. Let me know when they're enabled (or if you'd like to skip this).
80
80
 
@@ -86,7 +86,7 @@ The **Nuxt** layer may combine **your APIs** (often Postgres-backed), **chat** v
86
86
 
87
87
  ## Step 3: Understand the Environment
88
88
 
89
- Run `npm install` / `node init-project.js` as needed so `.cursor/skills/` includes **`data-model`** (no `elemental-api` skill in this mode).
89
+ Run `npm install` / `node init-project.js` as needed so `.agents/skills/` includes **`data-model`** (no `elemental-api` skill in this mode).
90
90
 
91
91
  Read:
92
92