@yottagraph-app/aether-instructions 1.0.1

package/commands/aether_deploy_mcp.md

@@ -0,0 +1,163 @@
+# Deploy MCP Server
+
+Deploy a custom MCP server from the `mcp-servers/` directory to Google Cloud Run via the Broadchurch Portal.
+
+## Overview
+
+This command deploys a Python MCP server (typically built with FastMCP) by triggering a GitHub Actions workflow through the Portal API. No local GCP credentials are needed -- the workflow authenticates via Workload Identity Federation, builds a container with Cloud Build, and deploys to Cloud Run.
+
+The server must live in `mcp-servers/<name>/` with at minimum `server.py` and `requirements.txt`. A `Dockerfile` is auto-generated if not provided.
+
+**Prerequisite:** The project must have a valid `broadchurch.yaml` (created during provisioning).
+
+---
+
+## Step 1: Read Configuration
+
+Read `broadchurch.yaml` from the project root.
+
+```bash
+cat broadchurch.yaml
+```
+
+**If the file does not exist:**
+
+> This project hasn't been provisioned yet. Create it in the Broadchurch Portal first.
+
+Stop here.
+
+Extract these values:
+
+- `tenant.org_id` (tenant org ID)
+- `gateway.url` (Portal Gateway URL)
+
+---
+
+## Step 2: Discover MCP Servers
+
+List the directories under `mcp-servers/`:
+
+```bash
+ls -d mcp-servers/*/
+```
+
+**If no directories exist:**
+
+> No MCP servers found. Create one by making a directory under `mcp-servers/` with:
+>
+> ```
+> mcp-servers/my-server/
+> ├── server.py         # FastMCP server definition
+> └── requirements.txt  # Must include 'fastmcp'
+> ```
+
+Stop here.
+
+**If multiple servers exist:** Ask which one to deploy.
+
+**If only one exists:** Confirm with the user.
+
+---
+
+## Step 3: Validate Server Structure
+
+Verify required files:
+
+```bash
+ls mcp-servers/<name>/server.py mcp-servers/<name>/requirements.txt
+```
+
+**If missing:** Tell the user what's needed.
+
+---
+
+## Step 4: Ensure Code is Pushed
+
+The deployment workflow runs on the code in the GitHub repo. Make sure the server code is committed and pushed:
+
+```bash
+git status
+```
+
+**If there are uncommitted changes in `mcp-servers/<name>/`:**
+
+> Your server code has local changes that aren't pushed yet. The deployment will use the version on GitHub. Would you like me to commit and push first?
+
+If yes, commit and push. If no, warn them and continue.
+
+---
+
+## Step 5: Trigger Deployment
+
+Call the Portal API to trigger the deploy workflow:
+
+```bash
+curl -sf -X POST "<GATEWAY_URL>/api/projects/<ORG_ID>/deploy" \
+  -H "Content-Type: application/json" \
+  -d '{"type": "mcp", "name": "<SERVER_NAME>"}'
+```
+
+**If this fails with 404:** The server directory may not exist on GitHub yet. Push your code first.
+
+**If this succeeds:** The Portal has triggered the `deploy-mcp.yml` GitHub Actions workflow.
+
+---
+
+## Step 6: Monitor Progress
+
+> Deployment triggered! The MCP server is being deployed via GitHub Actions.
+>
+> - **Server:** <name>
+> - **Workflow:** deploy-mcp.yml
+>
+> This typically takes 2-5 minutes (container build + Cloud Run deploy).
+> You can monitor progress:
+>
+> - In the Broadchurch Portal under your project's Deployment Status section
+> - On GitHub: `https://github.com/<REPO>/actions`
+>
+> Once complete, the Cloud Run service URL will be available.
+
+---
+
+## 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.
+
+Read `.cursor/mcp.json`, then add a new entry for the server:
+
+```json
+{
+    "<SERVER_NAME>": {
+        "url": "<GATEWAY_URL>/api/mcp/<ORG_ID>/<SERVER_NAME>/mcp"
+    }
+}
+```
+
+Where `<SERVER_NAME>`, `<GATEWAY_URL>`, and `<ORG_ID>` are the values from Steps 1-2.
+
+Write the updated JSON back to `.cursor/mcp.json`.
+
+> The MCP server is now registered. Cursor will connect to it through the Portal Gateway proxy — no credentials needed.
+>
+> You may need to reload Cursor (Cmd+Shift+P → "Developer: Reload Window") for the new MCP server to appear in your tool list.
+
+---
+
+## Troubleshooting
+
+### Build fails
+
+Check the GitHub Actions logs for the `Deploy MCP Server` workflow. Common issues:
+
+- **"requirements.txt" errors**: Make sure `fastmcp` and all dependencies are listed.
+- **Dockerfile issues**: If you have a custom Dockerfile, ensure it exposes port 8080.
+- **WIF auth failure**: The Broadchurch admin needs to run the WIF setup script.
+
+### "Permission denied" when agents call the server
+
+The Cloud Run service is deployed with `--no-allow-unauthenticated`. Only the tenant's service account can invoke it. The deployment workflow grants this automatically.
+
+### Need to update an existing server
+
+Just run `/deploy_mcp` again. It will rebuild and redeploy to the same Cloud Run service.

package/commands/aether_update_branding.md

@@ -0,0 +1,123 @@
+# Update Branding
+
+Refresh the Lovelace Brand R2 files from the canonical source repository.
+
+## Overview
+
+Aether's branding files are wholesale copies from the `moongoose/ui/news-ui` directory of the Lovelace repo. This command copies the latest versions and checks for new dependencies.
+
+**Do not hardcode any local paths.** Always ask the user for the Lovelace repo location.
+
+---
+
+## Step 1: Ask for the Lovelace Repo Path
+
+```
+AskQuestion({
+  title: "Lovelace Repository Path",
+  questions: [
+    {
+      id: "repo-path",
+      prompt: "Where is your local clone of the Lovelace repository?",
+      options: [
+        { id: "home-lovelace", label: "~/lovelace" },
+        { id: "custom", label: "Other location (I'll specify)" }
+      ]
+    }
+  ]
+})
+```
+
+If the user selects "Other location", ask them to provide the full path.
+
+Expand `~` to the user's home directory. Store the result as `{repo}`.
+
+---
+
+## Step 2: Validate the Source Path
+
+Confirm the branding source directory exists:
+
+```bash
+ls {repo}/moongoose/ui/news-ui/BRANDING.md
+```
+
+**If the file does not exist:** Tell the user the path doesn't contain the expected branding files and ask them to double-check. Stop.
+
+Also verify the other expected source files exist:
+
+```bash
+ls {repo}/moongoose/ui/news-ui/composables/useNewsTheme.ts
+ls {repo}/moongoose/ui/news-ui/composables/useThemeClasses.ts
+ls {repo}/moongoose/ui/news-ui/assets/theme-styles.css
+ls {repo}/moongoose/ui/news-ui/assets/fonts.css
+ls {repo}/moongoose/ui/news-ui/public/fonts/README.md
+ls {repo}/moongoose/ui/news-ui/public/LL-logo-full-wht.svg
+```
+
+Report any missing files. If critical files are missing (BRANDING.md, useNewsTheme.ts, theme-styles.css), stop. If optional files are missing (logo, fonts README), warn but continue.
+
+---
+
+## Step 3: Copy the Branding Files
+
+The base source path is `{repo}/moongoose/ui/news-ui`.
+
+Copy these files to their Aether destinations:
+
+| Source (relative to base)        | Destination (relative to Aether root) |
+| -------------------------------- | ------------------------------------- |
+| `BRANDING.md`                    | `branding/BRANDING.md`                |
+| `composables/useNewsTheme.ts`    | `composables/useNewsTheme.ts`         |
+| `composables/useThemeClasses.ts` | `composables/useThemeClasses.ts`      |
+| `assets/theme-styles.css`        | `assets/theme-styles.css`             |
+| `assets/fonts.css`               | `assets/fonts.css`                    |
+| `public/fonts/README.md`         | `public/fonts/README.md`              |
+| `public/LL-logo-full-wht.svg`    | `public/LL-logo-full-wht.svg`         |
+
+For `app.vue`, extract only the `<style>` block contents (not the `<style>` tags themselves) and write them to `assets/brand-globals.css`. Read the source `app.vue`, find the content between `<style>` and `</style>`, and overwrite `assets/brand-globals.css` with that content.
+
+---
+
+## Step 4: Dependency Audit
+
+After copying, read through each copied file and check for new references that weren't present before:
+
+1. **TypeScript imports**: Check `useNewsTheme.ts` and `useThemeClasses.ts` for any new `import` statements referencing files that don't exist in Aether.
+
+2. **CSS references**: Check `theme-styles.css`, `fonts.css`, and `brand-globals.css` for:
+    - `url()` paths pointing to files not in `public/`
+    - `@import` statements referencing files not in `assets/`
+
+3. **Documentation references**: Check `BRANDING.md` for references to new files (logos, assets, CSS files) that should be copied.
+
+**If new dependencies are found:**
+
+- Static assets (images, SVGs, fonts) -> copy to `public/` in the equivalent subdirectory
+- CSS files -> copy to `assets/`
+- TypeScript/JS files -> copy to `composables/` or the equivalent directory
+- Report what was copied to the user
+
+---
+
+## Step 5: Verify Integration
+
+Check that the adapter (`composables/useCustomTheme.ts`) is still compatible:
+
+1. Read `composables/useNewsTheme.ts` and check what it exports.
+2. Read `composables/useCustomTheme.ts` and confirm it re-exports the expected interface.
+3. If `useNewsTheme.ts` has added new named exports that aren't re-exported by the adapter, tell the user:
+
+> `useNewsTheme.ts` has new exports that aren't exposed through `useCustomTheme.ts`: [list them]. You may want to add these to the adapter if components need them.
+
+4. Check that `nuxt.config.ts` still includes the three CSS files:
+
+```typescript
+css: ['~/assets/fonts.css', '~/assets/brand-globals.css', '~/assets/theme-styles.css'],
+```
+
+---
+
+## Step 6: Commit
+
+Follow the `git-support.mdc` workflow to commit the change.

package/commands/aether_update_instructions.md

@@ -0,0 +1,183 @@
+# Update Aether 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.
+
+**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/`
+4. Extracts fresh files from the package
+5. 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.
+
+---
+
+## Step 1: Check Current Version
+
+Read the current installed version:
+
+```bash
+cat .cursor/.aether-instructions-version 2>/dev/null || echo "Not installed"
+```
+
+Report to user:
+> Current version: X.Y.Z (or "Not installed")
+
+---
+
+## Step 2: Check Latest Version
+
+Query npm for the latest version:
+
+```bash
+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)
+
+---
+
+## Step 3: Download Package
+
+Create a temporary directory and download the package:
+
+```bash
+TEMP_DIR=$(mktemp -d)
+npm pack @yottagraph-app/aether-instructions@latest --pack-destination "$TEMP_DIR"
+```
+
+Extract the tarball:
+
+```bash
+tar -xzf "$TEMP_DIR"/*.tgz -C "$TEMP_DIR"
+```
+
+The extracted content is in `$TEMP_DIR/package/`.
+
+---
+
+## Step 4: Delete Existing aether_* Files
+
+Remove all `aether_*` files from `.cursor/rules/` and `.cursor/commands/`:
+
+```bash
+rm -f .cursor/rules/aether_*.mdc
+rm -f .cursor/commands/aether_*.md
+```
+
+Remove all `aether_*/` directories from `.cursor/skills/`:
+
+```bash
+rm -rf .cursor/skills/aether_*/
+```
+
+---
+
+## Step 5: Copy New Files
+
+Create directories if needed:
+
+```bash
+mkdir -p .cursor/rules .cursor/commands .cursor/skills
+```
+
+Copy files from the extracted package:
+
+```bash
+cp "$TEMP_DIR/package/rules/"* .cursor/rules/ 2>/dev/null || true
+cp "$TEMP_DIR/package/commands/"* .cursor/commands/ 2>/dev/null || true
+cp -r "$TEMP_DIR/package/skills/"* .cursor/skills/ 2>/dev/null || true
+```
+
+---
+
+## Step 6: Update Version Marker
+
+Read the new version from the package:
+
+```bash
+grep '"version"' "$TEMP_DIR/package/package.json"
+```
+
+Write the version marker:
+
+```bash
+echo "X.Y.Z" > .cursor/.aether-instructions-version
+```
+
+---
+
+## Step 7: Cleanup
+
+Remove the temporary directory:
+
+```bash
+rm -rf "$TEMP_DIR"
+```
+
+---
+
+## Step 8: Report Changes
+
+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
+```
+
+Report to user:
+> Updated to @yottagraph-app/aether-instructions@X.Y.Z
+> - Rules: N files
+> - Commands: N files
+> - Skills: N directories
+
+---
+
+## Step 9: Commit Changes
+
+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"
+```
+
+> Changes committed. Your Aether instructions are now up to date.
+
+---
+
+## Troubleshooting
+
+### 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?
+
+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
+
+Example:
+```bash
+cp .cursor/rules/aether_api.mdc .cursor/rules/api_custom.mdc
+# Edit api_custom.mdc as needed
+```