workspace-architect 2.0.4 → 2.1.0

package/README.md

@@ -192,8 +192,10 @@ description: A guide for setting up X.
 ```
 
 **Naming Convention**: Filenames become IDs (extensions are stripped)
-- `assets/instructions/my-guide.md` → `instructions:my-guide`
-- `assets/agents/my-agent.agent.md` → `agents:my-agent`
+- `assets/instructions/my-guide.md` → ID: `instructions:my-guide`
+- `assets/agents/my-agent.agent.md` → ID: `agents:my-agent`
+
+**Note**: The colon format (`type:name`) is used for internal IDs in collections and manifests. When using the CLI, use the space-separated format: `npx wsa download instructions my-guide`
 
 ### Creating Collections
 
@@ -203,17 +205,20 @@ Create a JSON file in `assets/collections/`:
 {
   "name": "My Collection",
   "description": "A collection for X development.",
-  "items": [
-    "instructions:reactjs",
-    "prompts:code-review",
-    "agents:expert-architect"
-  ]
+  "items": {
+    "instructions": ["reactjs"],
+    "prompts": ["code-review"],
+    "agents": ["expert-architect"]
+  }
 }
 ```
 
+**Collection Format**: Collections use a nested object structure where items are grouped by type. Each type key contains an array of asset names (without the type prefix).
+
 ### Useful Scripts
 
 - `npm run generate-manifest` - Generate `assets-manifest.json` (required before PRs)
+- `npm run migrate-collections` - Migrate collections from old flat array format to new nested format
 - `npm run analyze` - Analyze collections with TF-IDF/Cosine Similarity
   - `npm run analyze -- --add` - Auto-add high-confidence matches
   - `npm run analyze -- --remove` - Remove low-confidence items
@@ -256,7 +261,11 @@ workspace-architect/
 
 ## Migration Guide
 
-Migrating from `.chatmode.md` to `.agent.md`? Run:
+### Migrating from `.chatmode.md` to `.agent.md`
+
+**Note:** This guide is for users migrating from the deprecated `.chatmode.md` format to the current `.agent.md` format.
+
+If you have legacy `.chatmode.md` files, run:
 
 ```bash
 mkdir -p assets/agents