docs(repo): align doc examples with integrations

Signed-off-by: Vatche Isahagian <vatchei@ibm.com>

Author: visahak

.secrets.baseline

@@ -3,7 +3,7 @@
     "files": "^.secrets.baseline$|package-lock\\.json$",
     "lines": null
   },
-  "generated_at": "2026-02-26T16:00:29Z",
+  "generated_at": "2026-04-02T15:14:08Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"
@@ -77,35 +77,35 @@
     }
   ],
   "results": {
-    "CONFIGURATION.md": [
+    "README.md": [
       {
         "hashed_secret": "ec3810e10fb78db55ce38b9c18d1c3eb1db739e0",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 9,
+        "line_number": 44,
         "type": "Secret Keyword",
         "verified_result": null
-      },
+      }
+    ],
+    "docs/guides/configuration.md": [
       {
-        "hashed_secret": "11fa7c37d697f30e6aee828b4426a10f83ab2380",
+        "hashed_secret": "ec3810e10fb78db55ce38b9c18d1c3eb1db739e0",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 18,
+        "line_number": 9,
         "type": "Secret Keyword",
         "verified_result": null
-      }
-    ],
-    "README.md": [
+      },
       {
-        "hashed_secret": "ec3810e10fb78db55ce38b9c18d1c3eb1db739e0",
+        "hashed_secret": "11fa7c37d697f30e6aee828b4426a10f83ab2380",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 36,
+        "line_number": 18,
         "type": "Secret Keyword",
         "verified_result": null
       }
     ],
-    "README_extract_trajectories.md": [
+    "docs/guides/extract-trajectories.md": [
       {
         "hashed_secret": "48ae8db8c64fbf47ec3f8eec6f31f3a5b88594d2",
         "is_secret": false,
@@ -123,7 +123,7 @@
         "verified_result": null
       }
     ],
-    "README_phoenix_sync.md": [
+    "docs/guides/phoenix-sync.md": [
       {
         "hashed_secret": "ec3810e10fb78db55ce38b9c18d1c3eb1db739e0",
         "is_secret": false,

docs/examples/hello_world/index.md

@@ -42,4 +42,4 @@ At this point, Bob will correct itself and eventually run `uv sync` and correctl
 Bob should then run some Evolve Lite skills to save the learned correction into memory.
 If it does not, the `/evolve:learn` command can be used to manually run the skill.
 
-In the future, Bob should remember via Evolve-Lite skills that `uv` is used for this project and not make the same mistake. This can be tested in this toy project by deleting the `.venv` and `uv.lock` folder and trying the same utterance again.
+In the future, Bob should remember via Evolve-Lite skills that `uv` is used for this project and not make the same mistake. This can be tested in this toy project by deleting the `.venv` directory and the `uv.lock` file and trying the same utterance again.

docs/installation/index.md

@@ -15,13 +15,14 @@ curl -fsSL https://raw.githubusercontent.com/AgentToolkit/altk-evolve/v1.0.5/pla
 ```
 ### Install Script Usage
 ```bash
-./install.sh install --platform {bob,claude,all} --mode {lite,full} [--dry-run]
+./install.sh install --platform {bob,roo,claude,all} --mode {lite,full} [--dry-run]
 ```
 
 | Platform | Description |
 |-----------|-------------|
 | `all` | Install all platforms |
 | `bob` | IBM Bob |
+| `roo` | Roo Code |
 | `claude` | Claude Code |
 
 | Mode | Description |

docs/integrations/evolve-lite.md

@@ -1,6 +1,6 @@
 # Evolve Lite
 
-Evolve Lite is a lightweight mode that runs as a Claude Code plugin — no vector store, no MCP servers, no API keys required. It stores entities as plain JSON in your project directory and uses Claude Code's built-in hooks to inject them automatically.
+Evolve Lite is a lightweight mode that runs as a Claude Code plugin — no vector store, no MCP servers, no API keys required. It stores entities as Markdown files with YAML frontmatter under `.evolve/entities/` in your project directory and uses Claude Code's built-in hooks to inject them automatically.
 
 ## Prerequisites
 
@@ -31,11 +31,11 @@ claude plugin list
 
 Evolve Lite has two halves:
 
-1. **Learn** — You invoke `/evolve:learn` at the end of a conversation. The plugin analyzes what happened and extracts reusable entities (preferences, strategies, recovery patterns) into `.evolve/entities.json`.
+1. **Learn** — You invoke `/evolve:learn` at the end of a conversation. The plugin analyzes what happened, produces an entity JSON payload, and saves each entity as a Markdown file under `.evolve/entities/`.
 
 2. **Recall** — On every subsequent prompt, a `UserPromptSubmit` hook automatically loads stored entities and injects them into the conversation context. Claude applies whichever entities are relevant to the current task.
 
-No external services are involved. The entire loop is a JSON file and two Python scripts.
+No external services are involved. The entire loop is a directory of entity files and two Python scripts.
 
 ## Example Walkthrough
 
@@ -79,7 +79,7 @@ Claude: I've extracted the following entities from this conversation:
         }
 
         Added 1 new entity(ies). Total: 1
-        Entities stored in: /path/to/project/.evolve/entities.json
+        Entities stored in: /path/to/project/.evolve/entities
 ```
 
 ### Session 2 — Preference is applied automatically
@@ -117,7 +117,7 @@ Then run a task to extract metadata from an image:
 just trace=true learn=true sandbox-prompt 'where was the photo @sample.jpg taken. use exif metadata'
 ```
 
-When you run the above, you will see that the agent hits some dead ends (exiftool not found, Pillow not installed), and that it learns guidelines to avoid them in the future (see `demo/workspace/.evolve/entities.json`).
+When you run the above, you will see that the agent hits some dead ends (exiftool not found, Pillow not installed), and that it learns guidelines to avoid them in the future (see `demo/workspace/.evolve/entities/`).
 
 Run the same task again in a new session:
 
@@ -197,7 +197,7 @@ Claude: I've extracted the following entities from this conversation:
         }
 
         Added 2 new entity(ies). Total: 2
-        Entities stored in: /workspace/.evolve/entities.json
+        Entities stored in: /workspace/.evolve/entities
 ```
 
 ### Session 2 — No more dead ends
@@ -232,22 +232,30 @@ The agent skipped both `exiftool` and `Pillow` entirely — it went straight to
 
 ## Entities Storage
 
-Entities live in `.evolve/entities.json` in the project root:
-
-```json
-{
-  "entities": [
-    {
-      "content": "Use Python stdlib (struct module) to manually parse JPEG EXIF/GPS metadata when no external tools are available",
-      "rationale": "In sandboxed environments, neither system tools (exiftool) nor third-party libraries (PIL/Pillow) may be installed. Python stdlib is always available.",
-      "category": "strategy",
-      "trigger": "When extracting EXIF or GPS metadata from images in containerized or sandboxed environments"
-    }
-  ]
-}
+Entities live in `.evolve/entities/` in the project root, organized into type-based subdirectories:
+
+```text
+.evolve/entities/
+  strategy/
+    use-python-stdlib-struct-module-to-manually-parse-jpeg-exif-gps.md
+```
+
+Each entity file uses Markdown with YAML frontmatter:
+
+```markdown
+---
+type: strategy
+trigger: When extracting EXIF or GPS metadata from images in containerized or sandboxed environments
+---
+
+Use Python stdlib (struct module) to manually parse JPEG EXIF/GPS metadata when no external tools are available
+
+## Rationale
+
+In sandboxed environments, neither system tools (exiftool) nor third-party libraries (PIL/Pillow) may be installed. Python stdlib is always available.
 ```
 
-Override the storage location with the `EVOLVE_ENTITIES_FILE` environment variable.
+Override the storage location with the `EVOLVE_ENTITIES_DIR` environment variable.
 
 ## Tradeoffs
 
@@ -267,7 +275,7 @@ But it has a number of limitations:
 
 | Capability | Evolve Lite | Full Evolve |
 |------------|-------------|-------------|
-| Entity storage | JSON file | Milvus vector store |
+| Entity storage | Markdown files in `.evolve/entities/` | Milvus vector store |
 | Retrieval | All entities injected via hooks | Semantic search via MCP |
 | Conflict resolution | Append-only | LLM-based merging + garbage collection |
 | Trajectory analysis | Current session only (`/evolve:learn`) | Multi-session, automatic via MCP |

platform-integrations/claude/plugins/evolve-lite/README.md

@@ -54,7 +54,7 @@ See the [Evolve Lite guide](../../../../docs/integrations/evolve-lite.md#example
 Manually invoke to extract entities from the current conversation:
 - Analyzes task, steps taken, successes and failures
 - Generates proactive entities (what to do, not what to avoid)
-- Outputs JSON for storage
+- Outputs JSON that the save script persists as entity files
 
 ### `/evolve:recall`