@yottagraph-app/aether-instructions 1.1.0 → 1.1.2

package/README.md

@@ -16,6 +16,7 @@ To update to the latest version:
 ```
 
 This Cursor command will:
+
 1. Download the latest version of this package
 2. Replace files in `.cursor/` that are listed in `.cursor/.aether-instructions-manifest`
 3. Extract fresh files from the package
@@ -32,6 +33,7 @@ by the updater.
 ### Customizing Rules/Commands
 
 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 replaced when you run `/update_instructions`
@@ -44,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 to `packages/aether-instructions/` with their original names
 - Bumps the version
 - Publishes to npmjs

package/commands/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/update_instructions.md

@@ -7,6 +7,7 @@ Update Cursor rules, commands, and skills from the `@yottagraph-app/aether-instr
 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 files listed in the existing manifest
 3. Cleans up any legacy `aether_*` prefixed files from older versions
@@ -27,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")
 
 ---
@@ -40,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)
@@ -147,7 +150,9 @@ 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
@@ -172,16 +177,19 @@ git commit -m "Update 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 or command?
 
 If you need to modify a package-provided file:
+
 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/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.1.0",
-  "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.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"
+    }
 }

package/rules/agents.mdc

@@ -53,12 +53,18 @@ Use `broadchurch_auth` for all Elemental API calls. It lives at
 `agents/broadchurch_auth.py` and is automatically bundled into each agent
 directory at deploy time. It handles:
 
-- Reading the API URL from `broadchurch.yaml` (or `ELEMENTAL_API_URL` env var)
-- Minting and caching GCP ID tokens in production
-- Falling back to `ELEMENTAL_API_TOKEN` for local dev
+- Routing through the Broadchurch Portal gateway proxy in production
+  (no direct QS credentials needed — the portal handles Auth0 M2M auth)
+- Authenticating to the proxy with a per-tenant API key from
+  `broadchurch.yaml` (`gateway.qs_api_key`)
+- Falling back to `ELEMENTAL_API_URL` + `ELEMENTAL_API_TOKEN` env vars
+  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 +79,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 +126,16 @@ 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`.
 
+In production, all Elemental API calls go through the Portal Gateway at
+`{gateway_url}/api/qs/{org_id}/...`. The agent sends `X-Api-Key` (from
+`broadchurch.yaml`) and the portal injects its own Auth0 M2M token
+upstream. This keeps QS credentials out of agents entirely and gives the
+platform a per-tenant kill switch.
+
+**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/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

@@ -1,7 +1,5 @@
 ---
-description: Warns users not to modify aether_ prefixed files in .cursor/
-globs:
-  - .cursor/**/aether_*
+description: Warns users not to modify package-managed instruction files in .cursor/
 alwaysApply: false
 ---
 
@@ -9,40 +7,35 @@ alwaysApply: false
 
 **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`.
+Package-managed files are tracked by `.cursor/.aether-instructions-manifest`.
+They will be **overwritten** when you run `/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)
+- Modify files listed in the manifest directly (changes will be lost on update)
 
 ## To Customize
 
-If you need to modify the behavior of an `aether_*` rule or command:
+If you need to modify a package-provided rule or command:
 
-1. **Copy** the file to a new name **without** the `aether_` prefix
+1. **Copy** the file to a new name
 2. Make your changes to the copy
-3. Your copy will not be affected by instruction updates
+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/aether_api.mdc .cursor/rules/api_custom.mdc
+cp .cursor/rules/api.mdc .cursor/rules/api_custom.mdc
 
-# Edit your copy
-# Your customizations in api_custom.mdc are preserved across updates
+# Edit your copy — it won't be affected by instruction updates
 ```
 
-## Why This Matters
+## How It Works
 
-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
+- `.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