docs(repo): reorganize documentation structure (#131)

* docs(repo): reorganize documentation structure

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

* docs(repo): align doc examples with integrations

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

---------

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,

CONTRIBUTING.md

@@ -1,6 +1,6 @@
-## How to contribute to ALTK‑Evolve
+## How to Contribute to Evolve
 
-ALTK‑Evolve welcomes external contributions of all kinds. Whether you are fixing bugs, improving existing functionality, or adding new evolution-focused capabilities, we’re glad to work with you.
+Evolve welcomes external contributions of all kinds. Whether you are fixing bugs, improving existing functionality, or adding new evolution-focused capabilities, we’re glad to work with you.
 
 ### Did you find a bug?
 
@@ -9,7 +9,7 @@ ALTK‑Evolve welcomes external contributions of all kinds. Whether you are fixi
 ### Types of contributions
 
 * Fixing bugs
-* Improving existing ALTK‑Evolve components
+* Improving existing Evolve components
 * Adding new components or evolution strategies
 * Improving documentation, examples, or tests
 
@@ -54,9 +54,9 @@ Or:
 pre-commit run --all-files
 ```
 
-### Adding new components to ALTK‑Evolve
+### Adding new components to Evolve
 
-ALTK‑Evolve builds on Agent Lifecycle Toolkit concepts with a focus on agent evolution, adaptation, and improvement over time.
+Evolve builds on Agent Lifecycle Toolkit concepts with a focus on agent evolution, adaptation, and improvement over time.
 
 1. Identify the evolution purpose of your component.
 2. Add a new package under the appropriate module.

README.md

@@ -32,7 +32,7 @@ Prerequisites:
 
 ```bash
 git clone <repository_url>
-cd evolve
+cd altk-evolve
 uv venv --python=3.12 && source .venv/bin/activate
 uv sync
 ```
@@ -44,7 +44,7 @@ For direct OpenAI usage:
 export OPENAI_API_KEY=sk-...
 ```
 
-For LiteLLM proxy usage and model selection (including global fallback via `EVOLVE_MODEL_NAME`), see [CONFIGURATION.md](CONFIGURATION.md).
+For LiteLLM proxy usage and model selection (including global fallback via `EVOLVE_MODEL_NAME`), see [the configuration guide](docs/guides/configuration.md).
 
 ### Running the MCP Server & UI
 
@@ -102,7 +102,7 @@ Evolve automatically tracks the origin of every guideline it generates or stores
 - `creation_mode`: Identifies how the tip was created (`auto-phoenix` via trace observability, `auto-mcp` via trajectory saving tools, or `manual`).
 - `source_task_id`: The ID of the original trace or task that inspired the tip, providing full audibility.
 
-See the [Low-Code Tracing Guide](docs/LOW_CODE_TRACING.md#6-understanding-tip-provenance-metadata) for more details.
+See the [Low-Code Tracing Guide](docs/guides/low-code-tracing.md#6-understanding-tip-provenance-metadata) for more details.
 
 
 ## Community & Feedback
@@ -115,11 +115,13 @@ If you’re experimenting with Evolve or exploring on‑the‑job learning for a
 
 ## Documentation
 
-- [EVOLVE_LITE.md](EVOLVE_LITE.md) - Lightweight mode via Claude Code plugin (no infra required)
-- [CONFIGURATION.md](CONFIGURATION.md) - Detailed configuration options
-- [POLICIES.md](docs/POLICIES.md) - Policy support and schema
-- [CLI.md](CLI.md) - Command-line interface documentation
-- [CLAUDE_CODE_DEMO.md](CLAUDE_CODE_DEMO.md) - Claude Code demo walkthrough
+- [Documentation Home](docs/index.md) - Overview of guides, reference docs, and tutorials
+- [Installation](docs/installation/index.md) - Setup instructions for supported platforms
+- [Configuration](docs/guides/configuration.md) - Environment variables and backend options
+- [CLI Reference](docs/reference/cli.md) - Command-line interface documentation
+- [Evolve Lite](docs/integrations/evolve-lite.md) - Lightweight Claude Code plugin mode
+- [Claude Code Demo](docs/tutorials/claude-code-demo.md) - End-to-end demo walkthrough
+- [Policies](docs/reference/policies.md) - Policy support and schema
 
 ## Development
 
@@ -150,7 +152,7 @@ The test suite is organized into 4 cleanly isolated tiers depending on infrastru
    ```bash
    uv run pytest -m e2e --run-e2e
    ```
-   *(See [docs/LOW_CODE_TRACING.md](docs/LOW_CODE_TRACING.md#end-to-end-verification) for more details).*
+   *(See [the Low-Code Tracing Guide](docs/guides/low-code-tracing.md#end-to-end-verification) for more details).*
 
 5. **LLM Evaluation Tests**
    Tests needing active LLM inference to test resolution pipelines (requires LLM API keys).

SAVE_SKILL_DESIGN.md …/archive/save-session-as-skill-design.mdSAVE_SKILL_DESIGN.md renamed to docs/archive/save-session-as-skill-design.md SAVE_SKILL_DESIGN.md renamed to docs/archive/save-session-as-skill-design.md

@@ -279,7 +279,7 @@ When the skill is invoked, the session history is already available in the conte
 - **Agent responses**: All assistant messages and outputs
 
 **No External Fetching Required**:
-- No need to call Phoenix or extract_trajectories.py
+- No need to call Phoenix or `scripts/extract_trajectories.py`
 - No need to check environment variables
 - Context is provided automatically when skill is invoked
 
@@ -816,4 +816,4 @@ if __name__ == "__main__":
 1. ✅ Design approved by user
 2. ✅ Trajectory access method confirmed (use session context)
 3. Create the actual save-session-as-skill SKILL.md
-4. Test the skill with the current session as an example
+4. Test the skill with the current session as an example

docs/examples/hello_world/index.md

@@ -14,9 +14,9 @@ uv init
 ```
 
 ## Step 2: Install Evolve
-Install Evolve by following the [installation instructions](../../installation), or run:
+Install Evolve by following the [installation instructions](../../installation/index.md), or run:
 ```bash
-curl -fsSL https://raw.githubusercontent.com/AgentToolkit/evolve/main/platform-integrations/install.sh | bash -s -- install --platform bob --mode lite
+curl -fsSL https://raw.githubusercontent.com/AgentToolkit/altk-evolve/main/platform-integrations/install.sh | bash -s -- install --platform bob --mode lite
 ```
 ## Step 3: Project Setup
 Open the project directory in IBM Bob IDE, and switch Bob's mode to `Evolve Lite`
@@ -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.

CONFIGURATION.md docs/guides/configuration.mdCONFIGURATION.md renamed to docs/guides/configuration.md

@@ -1,6 +1,6 @@
 # Extract Trajectories from Arize Phoenix
 
-A Python tool to extract agent trajectories from Arize Phoenix traces and convert them to OpenAI chat completion message format.
+A Python utility at `scripts/extract_trajectories.py` for extracting agent trajectories from Arize Phoenix traces and converting them to OpenAI chat completion message format.
 
 ## Features
 
@@ -23,25 +23,25 @@ A Python tool to extract agent trajectories from Arize Phoenix traces and conver
 
 ```bash
 # Get recent trajectories as JSON (pretty-printed)
-python3 extract_trajectories.py --limit 100 --pretty
+python3 scripts/extract_trajectories.py --limit 100 --pretty
 
 # Get a specific trace by ID
-python3 extract_trajectories.py --trace-id a67264f4375a60a1ac26ef3061c7352d --pretty
+python3 scripts/extract_trajectories.py --trace-id a67264f4375a60a1ac26ef3061c7352d --pretty
 
 # Human-readable text format
-python3 extract_trajectories.py --text --trace-id a67264f4375a60a1ac26ef3061c7352d
+python3 scripts/extract_trajectories.py --text --trace-id a67264f4375a60a1ac26ef3061c7352d
 
 # Include failed/error spans
-python3 extract_trajectories.py --include-errors --pretty
+python3 scripts/extract_trajectories.py --include-errors --pretty
 
 # Keep system reminders (don't clean)
-python3 extract_trajectories.py --no-clean --pretty
+python3 scripts/extract_trajectories.py --no-clean --pretty
 
 # Save to file
-python3 extract_trajectories.py --limit 100 -o trajectories.json --pretty
+python3 scripts/extract_trajectories.py --limit 100 -o trajectories.json --pretty
 
 # Custom Phoenix URL
-python3 extract_trajectories.py --url http://localhost:8080 --pretty
+python3 scripts/extract_trajectories.py --url http://localhost:8080 --pretty
 ```
 
 ### CLI Options
@@ -60,7 +60,7 @@ python3 extract_trajectories.py --url http://localhost:8080 --pretty
 ### As a Library
 
 ```python
-from extract_trajectories import (
+from scripts.extract_trajectories import (
     get_trajectories,
     get_trajectory_by_trace_id,
     format_trajectory_as_text

README_extract_trajectories.md docs/guides/extract-trajectories.mdREADME_extract_trajectories.md renamed to docs/guides/extract-trajectories.md

@@ -145,7 +145,7 @@ Two entity types are stored:
 
 ```bash
 # Sync every hour
-0 * * * * cd /path/to/evolve && uv run evolve sync phoenix --limit 100
+0 * * * * cd /path/to/altk-evolve && uv run evolve sync phoenix --limit 100
 ```
 
 ### Systemd Timer
@@ -157,7 +157,7 @@ Description=Evolve Phoenix Sync
 
 [Service]
 Type=oneshot
-WorkingDirectory=/path/to/evolve
+WorkingDirectory=/path/to/altk-evolve
 ExecStart=/path/to/uv run evolve sync phoenix
 Environment=PHOENIX_URL=http://localhost:6006
 Environment=EVOLVE_NAMESPACE_ID=production

docs/LOW_CODE_TRACING.md docs/guides/low-code-tracing.mddocs/LOW_CODE_TRACING.md renamed to docs/guides/low-code-tracing.md

@@ -10,5 +10,27 @@ Evolve is a system designed to help agents improve over time by learning from th
 - **Trajectory Analysis**: Automatically analyzes agent trajectories to generate guidelines and best practices.
 - **Milvus Integration**: Uses Milvus (or Milvus Lite) for efficient vector storage and retrieval.
 
+## Start Here
+
+- [Installation](installation/index.md): Set up Evolve on Bob or Claude Code.
+- [Configuration](guides/configuration.md): Configure models, backends, and environment variables.
+- [CLI Reference](reference/cli.md): Manage namespaces, entities, and sync jobs from the command line.
+
+## Guides
+
+- [Low-Code Tracing](guides/low-code-tracing.md): Instrument agents with Phoenix and verify end-to-end tracing.
+- [Phoenix Sync](guides/phoenix-sync.md): Pull trajectories from Phoenix and generate stored guidelines.
+- [Extract Trajectories](guides/extract-trajectories.md): Export Phoenix traces into an OpenAI-style message format.
+
+## Integrations and Tutorials
+
+- [Evolve Lite](integrations/evolve-lite.md): Lightweight Claude Code integration with local entity storage.
+- [Claude Code Demo](tutorials/claude-code-demo.md): Run the filesystem demo with Claude Code and the Evolve MCP server.
+- [Hello World with IBM Bob](examples/hello_world/index.md): A simple Bob walkthrough that shows how memory gets learned.
+
+## Reference
+
+- [Policies](reference/policies.md): Structured policy entities and how to retrieve them with MCP tools.
+
 ## Architecture
-![Screenshot](assets/architecture.png)
+![Architecture](assets/architecture.png)