@yottagraph-app/aether-instructions 1.1.43 → 1.1.45

package/AGENTS.md

@@ -1,14 +1,14 @@
 # Aether
 
-**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.
+**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.
 
 **Stack:** Nuxt 3 (SPA), Vue 3 Composition API (`<script setup>`), Vuetify 3, TypeScript (required), Auth0.
 
 **Structure:** `pages/` (file-based routing), `components/`, `composables/`, `server/api/`, `agents/` (Python ADK), `mcp-servers/` (Python FastMCP).
 
-**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.
+**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`](.cursor/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).
 
 **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.
 
@@ -18,24 +18,28 @@
 
 ## Task-specific topics
 
-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.
+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.
 
 ## Environment
 
 Detect your runtime once at startup, then read the matching topic in the `aether` skill:
 
-- **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).
-- **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).
+- **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).
+- **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).
 
 This check is cheap and only needs to run once per session.
 
-### Cursor instructions (`.cursor/`)
+### Agent instructions (`.agents/`)
 
-Cursor commands and skills are installed from the
-`@yottagraph-app/aether-instructions` npm package during project init.
-`.cursor/skills/aether/` is the main Aether skill.
-`.cursor/skills/elemental-api/` contains API skill documentation (endpoint
-reference, types, usage patterns). `.cursor/skills/data-model/` contains
+Agent commands and skills are installed from the
+`@yottagraph-app/aether-instructions` npm package during project init, under
+`.agents/`. `.cursor` and `.claude` are symlinks to `.agents/`, and
+`.mcp.json` is a symlink to `.agents/mcp.json`, so Cursor and Claude Code
+both read the same files.
+
+`.agents/skills/aether/` is the main Aether skill.
+`.agents/skills/elemental-api/` contains API skill documentation (endpoint
+reference, types, usage patterns). `.agents/skills/data-model/` contains
 Lovelace data model documentation (entity types, schemas per fetch source).
 If these directories are missing, run `/update_instructions` to reinstall.
 

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/README.md

@@ -1,6 +1,7 @@
 # @yottagraph-app/aether-instructions
 
-Cursor commands and skills for Aether development.
+Agent commands and skills for Aether development (used by Cursor and
+Claude Code).
 
 The core Aether guidance (architecture, data, UI, agents, MCP servers,
 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.
 This package is automatically downloaded and extracted during Aether project
 initialization (`init-project.js`). You don't need to install it directly.
 
+Files install under `.agents/`. `.cursor` and `.claude` are whole-directory
+symlinks to `.agents/`, and `.mcp.json` at the repo root is a symlink to
+`.agents/mcp.json`, so Cursor and Claude Code read the same files.
+
 ### Updating Instructions
 
 To update to the latest version:
@@ -19,20 +24,20 @@ To update to the latest version:
 /update_instructions
 ```
 
-This Cursor command will:
+This command will:
 
 1. Download the latest version of this package
-2. Replace files in `.cursor/` that are listed in `.cursor/.aether-instructions-manifest`
-3. Remove the deprecated `.cursor/rules/` directory if present (rules were replaced by the `aether` skill)
+2. Replace files in `.agents/` that are listed in `.agents/.aether-instructions-manifest`
+3. Remove the deprecated `.agents/rules/` directory if present (rules were replaced by the `aether` skill)
 4. Extract fresh files from the package
 5. Commit the changes
 
 ### File Naming Convention
 
-Package files keep their original names under `.cursor/commands/` and
-`.cursor/skills/`. Which paths are owned by the package is recorded in
-`.cursor/.aether-instructions-manifest`. Only those paths are overwritten on
-update; other files under `.cursor/` are not touched by the updater.
+Package files keep their original names under `.agents/commands/` and
+`.agents/skills/`. Which paths are owned by the package is recorded in
+`.agents/.aether-instructions-manifest`. Only those paths are overwritten on
+update; other files under `.agents/` are not touched by the updater.
 
 ### Customizing Commands or Skill Topics
 

package/commands/build_my_app.md

@@ -48,7 +48,7 @@ If design reference images exist (screenshots from Figma or other design tools):
 
 1. **Examine each image** -- these are design mockups from the project creator showing what the app should look like.
 2. Describe what you see in each image: layout structure, navigation patterns, component types, color usage, typography.
-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.
+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.
 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_.
 
 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.
 tools (entity search, market data, news, etc.) that you can use during
 development.
 
-**If MCP tools are NOT available:** Check if `.cursor/mcp.json` exists:
+**If MCP tools are NOT available:** Check if `.agents/mcp.json` exists:
 
 ```bash
-cat .cursor/mcp.json 2>/dev/null
+cat .agents/mcp.json 2>/dev/null
 ```
 
 If the file exists but tools aren't showing, they may need to be enabled:
 
-> Your project has Lovelace MCP servers configured (`.cursor/mcp.json`),
+> 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.
 >
@@ -95,17 +95,17 @@ First, ensure dependencies are installed (types aren't available without this):
 test -d node_modules || npm install
 ```
 
-Skills in `.cursor/skills/` are populated during project init (`node init-project.js`).
+Skills in `.agents/skills/` are populated during project init (`node init-project.js`).
 If that directory is empty after `npm install`, run `node init-project.js` to install them.
 
 Then read these files to understand what's available:
 
 1. `DESIGN.md` -- project vision and current status
 2. `broadchurch.yaml` -- project config (name, gateway URL, etc.)
-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.
-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.).
+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.
+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.).
 
-**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.
+**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.
 
 Key capabilities:
 
@@ -113,7 +113,7 @@ Key capabilities:
 - **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
 - **AI agent chat** -- use the `useAgentChat` composable to build a chat UI for deployed agents
-- **MCP servers** -- Lovelace MCP servers may be available (check `.cursor/mcp.json`)
+- **MCP servers** -- Lovelace MCP servers may be available (check `.agents/mcp.json`)
 - **Components** -- Vuetify 3 component library is available
 
 ---

package/commands/deploy_mcp.md

@@ -122,9 +122,9 @@ curl -sf -X POST "<GATEWAY_URL>/api/projects/<ORG_ID>/deploy" \
 
 ## Step 7: Register in Cursor MCP Config
 
-After deployment completes, add the new server to `.cursor/mcp.json` so Cursor can connect to it through the Portal Gateway proxy.
+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.
 
-Read `.cursor/mcp.json`, then add a new entry for the server:
+Read `.agents/mcp.json`, then add a new entry for the server:
 
 ```json
 {
@@ -136,7 +136,7 @@ Read `.cursor/mcp.json`, then add a new entry for the server:
 
 Where `<SERVER_NAME>`, `<GATEWAY_URL>`, and `<ORG_ID>` are the values from Steps 1-2.
 
-Write the updated JSON back to `.cursor/mcp.json`.
+Write the updated JSON back to `.agents/mcp.json`.
 
 > The MCP server is now registered. Cursor will connect to it through the Portal Gateway proxy — no credentials needed.
 >

package/commands/update_instructions.md

@@ -1,32 +1,73 @@
 # Update Instructions
 
-Update Cursor commands and skills from the `@yottagraph-app/aether-instructions` npm package.
+Update agent commands and skills from the `@yottagraph-app/aether-instructions` npm package.
 
 ## Overview
 
-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.
+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.
+
+`.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.
 
 **What happens:**
 
-1. Downloads the latest `@yottagraph-app/aether-instructions` package
-2. Deletes files listed in the existing manifest
-3. Removes the deprecated `.cursor/rules/` directory if present (rules were replaced by the `aether` skill)
-4. Extracts fresh files from the package
-5. Writes a new manifest
-6. Commits the changes
+1. Ensures the `.agents/` layout exists (migrating a legacy `.cursor/` directory and creating the `.cursor`, `.claude`, `.mcp.json` symlinks as needed)
+2. Downloads the latest `@yottagraph-app/aether-instructions` package
+3. Deletes files listed in the existing manifest
+4. Removes the deprecated `.agents/rules/` directory if present (rules were replaced by the `aether` skill)
+5. Extracts fresh files from the package
+6. Writes a new manifest
+7. Commits the changes
+
+**Your files are safe:** Only paths listed in the manifest are removed before reinstall. Other files under `.agents/` are left alone.
+
+**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.
+
+---
+
+## Step 1: Ensure `.agents/` Layout
+
+Detect and perform any one-time migration from the legacy `.cursor/` directory, then make sure the `.cursor`, `.claude`, and `.mcp.json` symlinks exist.
+
+```bash
+# Case 1: .cursor is already a symlink (previously migrated) — nothing to do here
+if [ -L .cursor ]; then
+  :
+# Case 2: Fresh install — create .agents/ and symlinks
+elif [ ! -e .cursor ]; then
+  mkdir -p .agents
+# Case 3: Legacy layout — migrate .cursor/ → .agents/
+elif [ -d .cursor ]; then
+  # Collision guards
+  if [ -e .agents ] && [ ! -L .agents ]; then
+    echo "Error: both .cursor/ and .agents/ exist as real paths. Resolve manually, then re-run /update_instructions." >&2
+    exit 1
+  fi
+  if [ -d .claude ] && [ ! -L .claude ] && [ -n "$(ls -A .claude 2>/dev/null)" ]; then
+    echo "Error: .claude/ exists as a real directory with contents. Move or remove it, then re-run /update_instructions." >&2
+    exit 1
+  fi
+  mv .cursor .agents
+  echo "Migrated .cursor/ → .agents/"
+fi
+
+# Create symlinks if absent
+[ -e .cursor ]   || ln -s .agents .cursor
+[ -e .claude ]   || ln -s .agents .claude
+[ -e .mcp.json ] || ln -s .agents/mcp.json .mcp.json
+```
 
-**Your files are safe:** Only paths listed in the manifest are removed before reinstall. Other files under `.cursor/` are left alone.
+Report to user:
 
-**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.
+> Layout ready: `.agents/` (canonical), with `.cursor`, `.claude`, and `.mcp.json` symlinks for tool compatibility.
 
 ---
 
-## Step 1: Check Current Version
+## Step 2: Check Current Version
 
 Read the current installed version:
 
 ```bash
-cat .cursor/.aether-instructions-version 2>/dev/null || echo "Not installed"
+cat .agents/.aether-instructions-version 2>/dev/null || echo "Not installed"
 ```
 
 Report to user:
@@ -35,7 +76,7 @@ Report to user:
 
 ---
 
-## Step 2: Check Latest Version
+## Step 3: Check Latest Version
 
 Query npm for the latest version:
 
@@ -51,7 +92,7 @@ Compare with current:
 
 ---
 
-## Step 3: Download Package
+## Step 4: Download Package
 
 Create a temporary directory and download the package:
 
@@ -70,12 +111,12 @@ The extracted content is in `$TEMP_DIR/package/`.
 
 ---
 
-## Step 4: Delete Previously Installed Files
+## Step 5: Delete Previously Installed Files
 
-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 just `AGENTS.md`); only remove **regular files** there, never directories.
+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.
 
 ```bash
-if [ -f .cursor/.aether-instructions-manifest ]; then
+if [ -f .agents/.aether-instructions-manifest ]; then
   while IFS= read -r rel || [ -n "$rel" ]; do
     [ -z "$rel" ] && continue
     case "$rel" in
@@ -85,40 +126,41 @@ if [ -f .cursor/.aether-instructions-manifest ]; then
         [ -f "$target" ] && rm -f "$target"
         ;;
       *)
-        rm -rf ".cursor/$rel"
+        rm -rf ".agents/$rel"
         ;;
     esac
-  done < .cursor/.aether-instructions-manifest
+  done < .agents/.aether-instructions-manifest
 fi
 ```
 
-Also remove the deprecated `.cursor/rules/` directory (superseded by the `aether` skill in `.cursor/skills/aether/`):
+Also remove the deprecated `.agents/rules/` directory (superseded by the `aether` skill in `.agents/skills/aether/`):
 
 ```bash
-rm -rf .cursor/rules
+rm -rf .agents/rules
 ```
 
 ---
 
-## Step 5: Copy New Files
+## Step 6: Copy New Files
 
 Create directories if needed:
 
 ```bash
-mkdir -p .cursor/commands .cursor/skills
+mkdir -p .agents/commands .agents/skills
 ```
 
 Copy files from the extracted package:
 
 ```bash
-cp "$TEMP_DIR/package/commands/"* .cursor/commands/ 2>/dev/null || true
-cp -r "$TEMP_DIR/package/skills/"* .cursor/skills/ 2>/dev/null || true
+cp "$TEMP_DIR/package/commands/"* .agents/commands/ 2>/dev/null || true
+cp -r "$TEMP_DIR/package/skills/"* .agents/skills/ 2>/dev/null || true
 ```
 
-Copy the root-level AGENTS.md from the package to the tenant repo root, if the package ships one:
+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`:
 
 ```bash
 [ -f "$TEMP_DIR/package/AGENTS.md" ] && cp "$TEMP_DIR/package/AGENTS.md" ./AGENTS.md
+[ -f "$TEMP_DIR/package/CLAUDE.md" ] && cp "$TEMP_DIR/package/CLAUDE.md" ./CLAUDE.md
 ```
 
 ### Data-mode variant overlay
@@ -126,39 +168,40 @@ Copy the root-level AGENTS.md from the package to the tenant repo root, if the p
 If this project uses **mcp-only** (or another non-default mode), re-apply the same overlay `init-project.js` uses. Read the saved mode:
 
 ```bash
-MODE=$(tr -d '\n' < .cursor/.aether-data-mode 2>/dev/null || echo "api-mcp")
+MODE=$(tr -d '\n' < .agents/.aether-data-mode 2>/dev/null || echo "api-mcp")
 PKG="$TEMP_DIR/package"
 if [ "$MODE" != "api-mcp" ] && [ -d "$PKG/variants/$MODE/commands" ]; then
-  cp "$PKG/variants/$MODE/commands/"* .cursor/commands/ 2>/dev/null || true
+  cp "$PKG/variants/$MODE/commands/"* .agents/commands/ 2>/dev/null || true
 fi
 if [ "$MODE" != "api-mcp" ] && [ -d "$PKG/variants/$MODE/skills" ]; then
   # Overlay per-file so default skill topics survive
   for src_dir in "$PKG/variants/$MODE/skills/"*/; do
     [ -d "$src_dir" ] || continue
     dir_name=$(basename "$src_dir")
-    mkdir -p ".cursor/skills/$dir_name"
-    cp "$src_dir"* ".cursor/skills/$dir_name/" 2>/dev/null || true
+    mkdir -p ".agents/skills/$dir_name"
+    cp "$src_dir"* ".agents/skills/$dir_name/" 2>/dev/null || true
   done
 fi
 if [ "$MODE" = "mcp-only" ]; then
-  rm -rf .cursor/skills/elemental-api
+  rm -rf .agents/skills/elemental-api
 fi
 ```
 
-If `.cursor/.aether-data-mode` is missing, skip the overlay (defaults to **api-mcp**).
+If `.agents/.aether-data-mode` is missing, skip the overlay (defaults to **api-mcp**).
 
 ---
 
-## Step 6: Write Manifest and Version Marker
+## Step 7: Write Manifest and Version Marker
 
-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:
+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:
 
 ```bash
 {
-  for f in .cursor/commands/*.md; do [ -f "$f" ] && echo "commands/$(basename "$f")"; done
-  for d in .cursor/skills/*/; do [ -d "$d" ] && echo "skills/$(basename "$d")"; done
+  for f in .agents/commands/*.md; do [ -f "$f" ] && echo "commands/$(basename "$f")"; done
+  for d in .agents/skills/*/; do [ -d "$d" ] && echo "skills/$(basename "$d")"; done
   [ -f "$TEMP_DIR/package/AGENTS.md" ] && [ -f ./AGENTS.md ] && echo "root/AGENTS.md"
-} > .cursor/.aether-instructions-manifest
+  [ -f "$TEMP_DIR/package/CLAUDE.md" ] && [ -f ./CLAUDE.md ] && echo "root/CLAUDE.md"
+} > .agents/.aether-instructions-manifest
 ```
 
 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.
@@ -166,12 +209,12 @@ If the repo uses **bash** for this loop and a glob might match nothing, run `sho
 Write the version marker:
 
 ```bash
-grep -o '"version": *"[^"]*"' "$TEMP_DIR/package/package.json" | grep -o '[0-9][^"]*' > .cursor/.aether-instructions-version
+grep -o '"version": *"[^"]*"' "$TEMP_DIR/package/package.json" | grep -o '[0-9][^"]*' > .agents/.aether-instructions-version
 ```
 
 ---
 
-## Step 7: Cleanup
+## Step 8: Cleanup
 
 Remove the temporary directory:
 
@@ -181,14 +224,14 @@ rm -rf "$TEMP_DIR"
 
 ---
 
-## Step 8: Report Changes
+## Step 9: Report Changes
 
 Count what was installed:
 
 ```bash
-wc -l < .cursor/.aether-instructions-manifest
-ls .cursor/commands/*.md 2>/dev/null | wc -l
-ls -d .cursor/skills/*/ 2>/dev/null | wc -l
+wc -l < .agents/.aether-instructions-manifest
+ls .agents/commands/*.md 2>/dev/null | wc -l
+ls -d .agents/skills/*/ 2>/dev/null | wc -l
 ```
 
 Report to user:
@@ -200,16 +243,24 @@ Report to user:
 
 ---
 
-## Step 9: Commit Changes
+## Step 10: Commit Changes
 
-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:
+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:
 
 ```bash
-git add .cursor/commands/ .cursor/.aether-instructions-version .cursor/.aether-instructions-manifest
-git add -f .cursor/skills/
+git add .agents/commands/ .agents/.aether-instructions-version .agents/.aether-instructions-manifest
+git add -f .agents/skills/
+# Symlinks (no-ops if they were already tracked)
+[ -L .cursor ]   && git add .cursor
+[ -L .claude ]   && git add .claude
+[ -L .mcp.json ] && git add .mcp.json
 [ -f AGENTS.md ] && git add AGENTS.md
+[ -f CLAUDE.md ] && git add CLAUDE.md
 # Remove the legacy rules dir from tracking if it was committed in an earlier install
-git rm -rf --cached --ignore-unmatch .cursor/rules 2>/dev/null || true
+git rm -rf --cached --ignore-unmatch .agents/rules 2>/dev/null || true
+# If we just migrated, drop the old .cursor/ path from tracking so git records the symlink instead of the directory
+git rm -rf --cached --ignore-unmatch .cursor 2>/dev/null || true
+[ -L .cursor ] && git add .cursor
 git commit -m "Update instructions to vX.Y.Z"
 ```
 
@@ -231,20 +282,26 @@ If `npm pack` fails with a registry error:
 
 If you get permission errors:
 
-> Try running with appropriate permissions, or check that `.cursor/` is writable.
+> Try running with appropriate permissions, or check that `.agents/` is writable.
 
 ### Want to customize a command, skill topic, or AGENTS.md?
 
-If you need to modify a package-provided file (including the root `AGENTS.md`):
+If you need to modify a package-provided file (including the root `AGENTS.md` or `CLAUDE.md`):
 
 1. Edit it directly — your changes will persist until the next update
 2. To preserve changes across updates, copy it to a new name first (e.g. `cp AGENTS.md AGENTS.local.md`)
-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)
+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`)
+
+`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`.
+
+### Blank line in manifest deleted `.agents/`
+
+Regenerate the manifest with Step 7 (echo-per-line form). Ensure Step 5 skips empty lines.
 
-### Blank line in manifest deleted `.cursor/`
+### `git add` says `.agents/skills` is ignored
 
-Regenerate the manifest with Step 6 (echo-per-line form). Ensure Step 4 skips empty lines.
+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.
 
-### `git add` says `.cursor/skills` is ignored
+### Migration aborted (collision)
 
-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.
+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

@@ -1,12 +1,13 @@
 {
     "name": "@yottagraph-app/aether-instructions",
-    "version": "1.1.43",
+    "version": "1.1.45",
     "description": "Cursor commands and skills for Aether development",
     "files": [
         "commands",
         "skills",
         "variants",
-        "AGENTS.md"
+        "AGENTS.md",
+        "CLAUDE.md"
     ],
     "repository": {
         "type": "git",

package/skills/aether/SKILL.md

@@ -54,4 +54,4 @@ topics that apply.
 | [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. |
 | [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 `.cursor/` files managed by `@yottagraph-app/aether-instructions`. Read before modifying installed instruction files.                                                                                      |
+| [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

@@ -35,7 +35,7 @@ Lovelace MCP servers (`lovelace-elemental`, `lovelace-stocks`, etc.)
 should be available if configured at the org level. Check your tool list
 for `elemental_*` tools. If they're not available, use the Elemental API
 client (`useElementalClient()`) and the skill docs in
-`.cursor/skills/elemental-api/` and `.cursor/skills/data-model/` for platform data access instead.
+`.agents/skills/elemental-api/` and `.agents/skills/data-model/` for platform data access instead.
 
 ### Technical details
 

package/skills/aether/data.md

@@ -13,14 +13,14 @@ regularly — use the discovery-first pattern to find what's available.
 ## Skill Documentation
 
 For endpoint reference, response shapes, and edge cases, **read the
-elemental-api skill** in `.cursor/skills/elemental-api/` (start with `SKILL.md` and
+elemental-api skill** in `.agents/skills/elemental-api/` (start with `SKILL.md` and
 follow the skill’s own structure). Files are copied from
 `@yottagraph-app/aether-instructions` (installed during project init). If
 the directory is missing, run `/update_instructions` to install it.
 
 ## Data model skill
 
-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.
+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.
 
 ## Test Before You Build
 
@@ -494,7 +494,7 @@ if (response.status === 404) {
 
 ## Lovelace MCP Servers
 
-Four MCP servers may be configured in `.cursor/mcp.json` for interactive
+Four MCP servers may be configured in `.agents/mcp.json` for interactive
 data exploration. **Check your tool list** — if tools like
 `elemental_get_schema` appear, use them as your primary testing and
 exploration interface before writing code. If they don't appear, the
@@ -526,7 +526,7 @@ building REST-based features with `useElementalClient()`.
 
 ### Setup
 
-`.cursor/mcp.json` is auto-generated by `init-project.js`. If it's missing,
+`.agents/mcp.json` is auto-generated by `init-project.js`. If it's missing,
 run `node init-project.js --local` to regenerate it. For provisioned projects,
 the servers route through the Portal Gateway proxy (no credentials needed).
 For local development without a gateway, the servers require an

package/skills/aether/instructions_warning.md

@@ -2,11 +2,15 @@
 
 **You are editing a file managed by the `@yottagraph-app/aether-instructions` package.**
 
-Package-managed files are tracked by `.cursor/.aether-instructions-manifest`.
+Package-managed files are tracked by `.agents/.aether-instructions-manifest`.
 They will be **overwritten** when you run `/update_instructions`.
 
-This includes files under `.cursor/commands/`, `.cursor/skills/`, **and the
-root `AGENTS.md`** (tracked as `root/AGENTS.md` in the manifest).
+This includes files under `.agents/commands/`, `.agents/skills/`, **and the
+root `AGENTS.md` and `CLAUDE.md`** (tracked as `root/AGENTS.md` and
+`root/CLAUDE.md` in the manifest).
+
+`.cursor`, `.claude`, and `.mcp.json` are symlinks into `.agents/`, so any
+path you see under those resolves to the same managed file.
 
 ## Do Not
 
@@ -14,33 +18,37 @@ root `AGENTS.md`** (tracked as `root/AGENTS.md` in the manifest).
 
 ## To Customize
 
-If you need to modify a package-provided command, skill topic, or the root `AGENTS.md`:
+If you need to modify a package-provided command, skill topic, or the root `AGENTS.md` / `CLAUDE.md`:
 
 1. **Copy** the file to a new name
 2. Make your changes to the copy
-3. Remove the original's entry from `.cursor/.aether-instructions-manifest`
+3. Remove the original's entry from `.agents/.aether-instructions-manifest`
    so it won't be replaced on update
 
 Examples:
 
 ```bash
 # Customize a skill topic
-cp .cursor/skills/aether/data.md .cursor/skills/aether/data_custom.md
+cp .agents/skills/aether/data.md .agents/skills/aether/data_custom.md
 
 # Customize AGENTS.md
 cp AGENTS.md AGENTS.local.md
 # then remove the `root/AGENTS.md` line from
-# .cursor/.aether-instructions-manifest
+# .agents/.aether-instructions-manifest
+
+# Customize CLAUDE.md
+cp CLAUDE.md CLAUDE.local.md
+# then remove the `root/CLAUDE.md` line from the manifest
 
 # Edit your copy — it won't be affected by instruction updates
 ```
 
 ## How It Works
 
-- `.cursor/.aether-instructions-manifest` lists every file installed by the
+- `.agents/.aether-instructions-manifest` lists every file installed by the
   package (one relative path per line, e.g. `skills/aether/data.md`). Entries
   prefixed with `root/` refer to files at the tenant repo root
-  (currently only `root/AGENTS.md`).
+  (currently `root/AGENTS.md` and `root/CLAUDE.md`).
 - `/update_instructions` deletes manifest entries, extracts fresh files from
   the latest package, and writes a new manifest
 - Files not in the manifest are never touched

package/skills/aether/mcp-servers.md

@@ -88,7 +88,7 @@ Deploy with the `/deploy_mcp` Cursor command. This will:
 2. Deploy to Cloud Run with IAM authentication
 3. Grant invoker permissions to tenant and Portal service accounts
 4. Register the server in Firestore (via the Portal API)
-5. Add the server to `.cursor/mcp.json` for Cursor IDE access
+5. Add the server to `.agents/mcp.json` for agent access (Cursor and Claude Code)
 
 ## Connecting MCP Servers to Agents
 

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

@@ -55,7 +55,7 @@ If design reference images exist (screenshots from Figma or other design tools):
 
 1. **Examine each image** — these are design mockups from the project creator showing what the app should look like.
 2. Describe what you see in each image: layout structure, navigation patterns, component types, color usage, typography.
-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.
+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.
 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_.
 
 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
 
 Check if Lovelace MCP tools are available (e.g. `elemental_get_schema`, `elemental_get_entity`). Use them while **authoring agents** and validating graph behavior.
 
-**If MCP tools are NOT available**, check `.cursor/mcp.json`:
+**If MCP tools are NOT available**, check `.agents/mcp.json`:
 
 ```bash
-cat .cursor/mcp.json 2>/dev/null
+cat .agents/mcp.json 2>/dev/null
 ```
 
 If the file exists but tools aren't active yet:
 
-> 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.
+> 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.
 >
 > 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).
 
@@ -86,7 +86,7 @@ The **Nuxt** layer may combine **your APIs** (often Postgres-backed), **chat** v
 
 ## Step 3: Understand the Environment
 
-Run `npm install` / `node init-project.js` as needed so `.cursor/skills/` includes **`data-model`** (no `elemental-api` skill in this mode).
+Run `npm install` / `node init-project.js` as needed so `.agents/skills/` includes **`data-model`** (no `elemental-api` skill in this mode).
 
 Read: