@yottagraph-app/aether-instructions 1.0.2 → 1.1.1

package/README.md

@@ -12,32 +12,31 @@ initialization (`init-project.js`). You don't need to install it directly.
 To update to the latest version:
 
 ```
-/aether_update_instructions
+/update_instructions
 ```
 
 This Cursor command will:
+
 1. Download the latest version of this package
-2. Delete existing `aether_*` files in `.cursor/`
+2. Replace files in `.cursor/` that are listed in `.cursor/.aether-instructions-manifest`
 3. Extract fresh files from the package
 4. Commit the changes
 
 ### File Naming Convention
 
-All files from this package are prefixed with `aether_`:
-- Rules: `.cursor/rules/aether_*.mdc`
-- Commands: `.cursor/commands/aether_*.md`
-- Skills: `.cursor/skills/aether_*/`
-
-This separates package-provided files from your own custom files. Files with
-the `aether_` prefix will be overwritten on update; your non-prefixed files
-are untouched.
+Package files keep their original names under `.cursor/rules/`,
+`.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.
 
 ### Customizing Rules/Commands
 
-To customize a package file:
-1. Copy it to a new name without the `aether_` prefix
+To customize something that ships with the package:
+
+1. Copy it to a new filename (a path not listed in the manifest)
 2. Make your changes to the copy
-3. Your copy won't be affected by instruction updates
+3. Your copy won't be replaced when you run `/update_instructions`
 
 ## For Maintainers
 
@@ -47,6 +46,7 @@ This package is built from `aether-dev` sources. To publish:
 2. Run `/publish_instructions --bump patch --publish`
 
 The publish command:
-- Copies source files with `aether_` prefix to `packages/aether-instructions/`
+
+- Copies source files to `packages/aether-instructions/` with their original names
 - Bumps the version
 - Publishes to npmjs

package/commands/{aether_configure_query_server.md → configure_query_server.md}

@@ -59,7 +59,7 @@ Replace the `query_server.url` value in `broadchurch.yaml` with the new URL. The
 
 ```yaml
 query_server:
-  url: "<NEW_URL>"
+    url: '<NEW_URL>'
 ```
 
 Preserve all other content in the file.

package/commands/{aether_update_instructions.md → update_instructions.md}

@@ -1,19 +1,21 @@
-# Update Aether Instructions
+# Update Instructions
 
 Update Cursor rules, commands, and skills from the `@yottagraph-app/aether-instructions` npm package.
 
 ## Overview
 
-This command downloads the latest version of the Aether instructions package and extracts it to your `.cursor/` directory. All package files are prefixed with `aether_` to distinguish them from your own custom files.
+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.
 
 **What happens:**
+
 1. Downloads the latest `@yottagraph-app/aether-instructions` package
-2. Deletes all existing `aether_*` files in `.cursor/rules/` and `.cursor/commands/`
-3. Deletes all existing `aether_*/` directories in `.cursor/skills/`
+2. Deletes files listed in the existing manifest
+3. Cleans up any legacy `aether_*` prefixed files from older versions
 4. Extracts fresh files from the package
-5. Commits the changes
+5. Writes a new manifest
+6. Commits the changes
 
-**Your files are safe:** Only files with the `aether_` prefix are touched. Your custom rules, commands, and skills (without the prefix) are never modified.
+**Your files are safe:** Only files listed in the manifest are touched during updates. If you've created your own rules or commands, they won't be modified.
 
 ---
 
@@ -26,6 +28,7 @@ cat .cursor/.aether-instructions-version 2>/dev/null || echo "Not installed"
 ```
 
 Report to user:
+
 > Current version: X.Y.Z (or "Not installed")
 
 ---
@@ -39,6 +42,7 @@ npm view @yottagraph-app/aether-instructions version
 ```
 
 Compare with current:
+
 - If same version: Ask user if they want to reinstall anyway
 - If newer version: Proceed with update
 - If current is newer: Warn user (they may have a pre-release)
@@ -64,18 +68,23 @@ The extracted content is in `$TEMP_DIR/package/`.
 
 ---
 
-## Step 4: Delete Existing aether_* Files
+## Step 4: Delete Previously Installed Files
 
-Remove all `aether_*` files from `.cursor/rules/` and `.cursor/commands/`:
+Read the manifest and delete listed files:
 
 ```bash
-rm -f .cursor/rules/aether_*.mdc
-rm -f .cursor/commands/aether_*.md
+if [ -f .cursor/.aether-instructions-manifest ]; then
+  while IFS= read -r rel; do
+    rm -rf ".cursor/$rel"
+  done < .cursor/.aether-instructions-manifest
+fi
 ```
 
-Remove all `aether_*/` directories from `.cursor/skills/`:
+Also clean up legacy `aether_*` files from older package versions:
 
 ```bash
+rm -f .cursor/rules/aether_*.mdc
+rm -f .cursor/commands/aether_*.md
 rm -rf .cursor/skills/aether_*/
 ```
 
@@ -99,18 +108,22 @@ cp -r "$TEMP_DIR/package/skills/"* .cursor/skills/ 2>/dev/null || true
 
 ---
 
-## Step 6: Update Version Marker
+## Step 6: Write Manifest and Version Marker
 
-Read the new version from the package:
+Build a manifest of all installed files (one relative path per line):
 
 ```bash
-grep '"version"' "$TEMP_DIR/package/package.json"
+MANIFEST=""
+for f in .cursor/rules/*.mdc; do [ -f "$f" ] && MANIFEST="$MANIFEST\nrules/$(basename "$f")"; done
+for f in .cursor/commands/*.md; do [ -f "$f" ] && MANIFEST="$MANIFEST\ncommands/$(basename "$f")"; done
+for d in .cursor/skills/*/; do [ -d "$d" ] && MANIFEST="$MANIFEST\nskills/$(basename "$d")"; done
+echo -e "$MANIFEST" > .cursor/.aether-instructions-manifest
 ```
 
 Write the version marker:
 
 ```bash
-echo "X.Y.Z" > .cursor/.aether-instructions-version
+grep -o '"version": *"[^"]*"' "$TEMP_DIR/package/package.json" | grep -o '[0-9][^"]*' > .cursor/.aether-instructions-version
 ```
 
 ---
@@ -130,14 +143,16 @@ rm -rf "$TEMP_DIR"
 Count what was installed:
 
 ```bash
-echo "=== Installed ==="
-ls .cursor/rules/aether_*.mdc 2>/dev/null | wc -l
-ls .cursor/commands/aether_*.md 2>/dev/null | wc -l
-ls -d .cursor/skills/aether_*/ 2>/dev/null | wc -l
+wc -l < .cursor/.aether-instructions-manifest
+ls .cursor/rules/*.mdc 2>/dev/null | wc -l
+ls .cursor/commands/*.md 2>/dev/null | wc -l
+ls -d .cursor/skills/*/ 2>/dev/null | wc -l
 ```
 
 Report to user:
+
 > Updated to @yottagraph-app/aether-instructions@X.Y.Z
+>
 > - Rules: N files
 > - Commands: N files
 > - Skills: N directories
@@ -149,11 +164,11 @@ Report to user:
 Commit the updated instruction files:
 
 ```bash
-git add .cursor/rules/aether_* .cursor/commands/aether_* .cursor/skills/aether_* .cursor/.aether-instructions-version
-git commit -m "Update Aether instructions to vX.Y.Z"
+git add .cursor/rules/ .cursor/commands/ .cursor/skills/ .cursor/.aether-instructions-version .cursor/.aether-instructions-manifest
+git commit -m "Update instructions to vX.Y.Z"
 ```
 
-> Changes committed. Your Aether instructions are now up to date.
+> Changes committed. Your instructions are now up to date.
 
 ---
 
@@ -162,22 +177,19 @@ git commit -m "Update Aether instructions to vX.Y.Z"
 ### npm pack fails
 
 If `npm pack` fails with a registry error:
+
 > Make sure you have network access to npmjs.com. If you're behind a proxy, configure npm: `npm config set proxy <url>`
 
 ### Permission denied
 
 If you get permission errors:
+
 > Try running with appropriate permissions, or check that `.cursor/` is writable.
 
-### Want to customize a rule/command?
+### Want to customize a rule or command?
 
-If you need to modify one of the `aether_*` files:
-1. Copy it to a new name without the `aether_` prefix
-2. Make your changes to the copy
-3. Your copy won't be affected by future updates
+If you need to modify a package-provided file:
 
-Example:
-```bash
-cp .cursor/rules/aether_api.mdc .cursor/rules/api_custom.mdc
-# Edit api_custom.mdc as needed
-```
+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
+3. Remove the original's entry from `.cursor/.aether-instructions-manifest` so it won't be deleted on update

package/commands/{aether_vercel_setup.md → vercel_setup.md}

@@ -307,10 +307,10 @@ Read the local `.env` file and parse all non-commented, non-empty lines into KEY
 
 - Commented-out lines (starting with `#`)
 - Variables with empty values (e.g., `NUXT_PUBLIC_USER_NAME=`, `NUXT_PUBLIC_QUERY_SERVER_ADDRESS=`)
-> **Why skip empty values?** Nuxt's runtime config defaults them to empty strings already.
-> The Vercel CLI cannot store truly empty values — it either prompts interactively or
-> requires a non-empty string. Using a space or placeholder causes bugs. For example,
-> a space in `NUXT_PUBLIC_USER_NAME` bypasses Auth0 login entirely.
+    > **Why skip empty values?** Nuxt's runtime config defaults them to empty strings already.
+    > The Vercel CLI cannot store truly empty values — it either prompts interactively or
+    > requires a non-empty string. Using a space or placeholder causes bugs. For example,
+    > a space in `NUXT_PUBLIC_USER_NAME` bypasses Auth0 login entirely.
 
 ### Sync Process
 

package/package.json

@@ -1,26 +1,26 @@
 {
-  "name": "@yottagraph-app/aether-instructions",
-  "version": "1.0.2",
-  "description": "Cursor rules, commands, and skills for Aether development",
-  "files": [
-    "rules",
-    "commands",
-    "skills"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Lovelace-AI/aether-dev.git",
-    "directory": "packages/aether-instructions"
-  },
-  "keywords": [
-    "cursor",
-    "aether",
-    "rules",
-    "commands",
-    "skills"
-  ],
-  "license": "UNLICENSED",
-  "publishConfig": {
-    "access": "public"
-  }
+    "name": "@yottagraph-app/aether-instructions",
+    "version": "1.1.1",
+    "description": "Cursor rules, commands, and skills for Aether development",
+    "files": [
+        "rules",
+        "commands",
+        "skills"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/Lovelace-AI/aether-dev.git",
+        "directory": "packages/aether-instructions"
+    },
+    "keywords": [
+        "cursor",
+        "aether",
+        "rules",
+        "commands",
+        "skills"
+    ],
+    "license": "UNLICENSED",
+    "publishConfig": {
+        "access": "public"
+    }
 }

package/rules/{aether_agents.mdc → agents.mdc}

@@ -58,7 +58,10 @@ directory at deploy time. It handles:
 - Falling back to `ELEMENTAL_API_TOKEN` for local dev
 
 ```python
-from broadchurch_auth import elemental_client
+try:
+    from broadchurch_auth import elemental_client
+except ImportError:
+    from .broadchurch_auth import elemental_client
 
 def get_schema() -> dict:
     """Get the yottagraph schema."""
@@ -73,6 +76,10 @@ def find_entities(expression: str, limit: int = 10) -> dict:
     return resp.json()
 ```
 
+The try/except is required because the import path differs between local
+dev (`agents/` on sys.path → absolute import) and Agent Engine runtime
+(code packaged inside an ADK module → relative import).
+
 **Do NOT** hardcode URLs or manually handle auth tokens. Do NOT read
 `broadchurch.yaml` directly — `broadchurch_auth` handles all of this.
 
@@ -116,6 +123,10 @@ Select your agent from the dropdown in the web UI. You can also run a single age
 during local dev (agents/ is the CWD → on sys.path). At deploy time, the
 workflow copies it into the agent directory alongside `broadchurch.yaml`.
 
+**Important:** Always use the try/except import pattern shown above. ADK
+wraps agent code in a package at deploy time, so absolute imports fail at
+runtime in Agent Engine — the relative import fallback is required.
+
 ## Deployment
 
 Two ways to deploy:

package/rules/{aether_api.mdc → api.mdc}

@@ -135,8 +135,8 @@ See the **cookbook** rule for a full "Get filings for a company" recipe.
 
 - **`client.getNEID()`** -- simple single-entity lookup by name
   (`GET /entities/lookup`). Best for resolving one company/person name.
-- **`client.findEntities()`** -- expression-based batch search
-  (`POST /entities/search`). Best for filtered searches (by type, property,
+- **`client.findEntities()`** -- expression-based search
+  (`POST /elemental/find`). Best for filtered searches (by type, property,
   relationship). See `find.md` for the expression language.
 
 ## Error Handling

package/rules/instructions_warning.mdc

@@ -0,0 +1,41 @@
+---
+description: Warns users not to modify package-managed instruction files in .cursor/
+alwaysApply: false
+---
+
+# Aether Instructions Warning
+
+**You are editing a file managed by the `@yottagraph-app/aether-instructions` package.**
+
+Package-managed files are tracked by `.cursor/.aether-instructions-manifest`.
+They will be **overwritten** when you run `/update_instructions`.
+
+## Do Not
+
+- Modify files listed in the manifest directly (changes will be lost on update)
+
+## To Customize
+
+If you need to modify a package-provided rule or command:
+
+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`
+   so it won't be replaced on update
+
+Example:
+
+```bash
+# Copy the rule you want to customize
+cp .cursor/rules/api.mdc .cursor/rules/api_custom.mdc
+
+# Edit your copy — it won't be affected by instruction updates
+```
+
+## How It Works
+
+- `.cursor/.aether-instructions-manifest` lists every file installed by the
+  package (one relative path per line, e.g. `rules/api.mdc`)
+- `/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/rules/aether_instructions_warning.mdc

@@ -1,48 +0,0 @@
----
-description: Warns users not to modify aether_ prefixed files in .cursor/
-globs:
-  - .cursor/**/aether_*
-alwaysApply: false
----
-
-# Aether Instructions Warning
-
-**You are editing a file managed by the `@yottagraph-app/aether-instructions` package.**
-
-Files prefixed with `aether_` are automatically installed and updated by the
-Aether instructions system. They will be **overwritten** when you run
-`/aether_update_instructions`.
-
-## Do Not
-
-- Modify existing `aether_*` files directly (changes will be lost on update)
-- Create new files with the `aether_` prefix (they will be deleted on update)
-
-## To Customize
-
-If you need to modify the behavior of an `aether_*` rule or command:
-
-1. **Copy** the file to a new name **without** the `aether_` prefix
-2. Make your changes to the copy
-3. Your copy will not be affected by instruction updates
-
-Example:
-
-```bash
-# Copy the rule you want to customize
-cp .cursor/rules/aether_api.mdc .cursor/rules/api_custom.mdc
-
-# Edit your copy
-# Your customizations in api_custom.mdc are preserved across updates
-```
-
-## Why This Matters
-
-The `aether_` prefix creates a clear namespace:
-- **`aether_*` files** = Package-managed, updated automatically
-- **Other files** = Your custom rules/commands, never touched
-
-This allows you to:
-- Receive rule updates without losing your customizations
-- Know at a glance which files are yours vs. package-provided
-- Safely extend the system without conflicts