@yottagraph-app/aether-instructions 1.0.1 → 1.1.0

package/README.md

@@ -12,32 +12,29 @@ 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 +44,6 @@ 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_update_instructions.md → update_instructions.md}

@@ -1,19 +1,20 @@
-# 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.
 
 ---
 
@@ -64,18 +65,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 +105,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,10 +140,10 @@ 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:
@@ -149,11 +159,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.
 
 ---
 
@@ -169,15 +179,9 @@ If `npm pack` fails with a registry error:
 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
-
-Example:
-```bash
-cp .cursor/rules/aether_api.mdc .cursor/rules/api_custom.mdc
-# Edit api_custom.mdc as needed
-```
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottagraph-app/aether-instructions",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Cursor rules, commands, and skills for Aether development",
   "files": [
     "rules",