From ac2d0b0e43e520889dfb03767062189ba352d351 Mon Sep 17 00:00:00 2001
From: xiuxiuxar <174127740+xiuxiuxar@users.noreply.github.com>
Date: Sun, 2 Mar 2025 12:49:57 -0700
Subject: [PATCH 01/10] Remove unncessary dialogue scaffold

---
 auto_dev/commands/augment.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/auto_dev/commands/augment.py b/auto_dev/commands/augment.py
index 96551c83..e95e2187 100644
--- a/auto_dev/commands/augment.py
+++ b/auto_dev/commands/augment.py
@@ -405,7 +405,6 @@ def customs(ctx, component_type, auto_confirm, use_daos):
     write_to_file(handler_path, handler_code, FileType.PYTHON)
     logger.info(f"Handler code written to {handler_path}")
 
-    scaffolder.create_dialogues()
     if use_daos:
         scaffolder.create_exceptions()
     logger.info("OpenAPI3 scaffolding completed successfully.")

From 49e49496627143a7995eeff86e32009a4e166db3 Mon Sep 17 00:00:00 2001
From: xiuxiuxar <174127740+xiuxiuxar@users.noreply.github.com>
Date: Sun, 2 Mar 2025 12:50:29 -0700
Subject: [PATCH 02/10] Add openapi to test_docs

---
 tests/test_docs.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/test_docs.py b/tests/test_docs.py
index b8ee7285..aa902e2f 100644
--- a/tests/test_docs.py
+++ b/tests/test_docs.py
@@ -34,7 +34,7 @@ def extract_code_blocks(doc):
 
 # we test the documents works.
 
-documentation = ["docs/fsm.md", "docs/dao.md"]
+documentation = ["docs/fsm.md", "docs/dao.md", "docs/openapi.md"]
 logger = getLogger()
 
 

From 8d4d875fb227b0e4fc1a53ffc7982df86ea44177 Mon Sep 17 00:00:00 2001
From: xiuxiuxar <174127740+xiuxiuxar@users.noreply.github.com>
Date: Sun, 2 Mar 2025 12:50:58 -0700
Subject: [PATCH 03/10] Update openapi3 doc

---
 docs/openapi.md | 198 ++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 166 insertions(+), 32 deletions(-)

diff --git a/docs/openapi.md b/docs/openapi.md
index 9ae54414..40d10c11 100644
--- a/docs/openapi.md
+++ b/docs/openapi.md
@@ -1,73 +1,207 @@
-# Scaffolding a new API Handler agent.
+# Augmenting visualisation station with an OpenAPI Handler
 
-The tools within the `handler` subcommand are used to scaffold a new agent.
+The tools within the `openapi` subcommand are used to augment a customs component with handler methods based on an OpenAPI 3 specification. This process automates the creation of endpoints methods. 
 
-We start with a simple openapi;
+## Prerequisites
 
-```bash
+1. An OpenAPI 3 specification file with paths, operationIds, and if augmenting with DAOs, schemas defined.
+2. A `component.yaml` file in the current directory that references the OpenAPI specification using the `api_spec` field.
+3. If augmenting with DAOs, DAOs for each schema in the OpenAPI specification (see dao docs for how to scaffold these).
+
+## Steps to Augment a Handler (without DAOs)
+
+1. Create an OpenAPI3 specification yaml.
+
+```
 cat auto_dev/data/openapi/openapi_specification.yaml
 ```
 
-We now scaffold the agent and cd in.
+Output:
 
-```bash
-aea create new_agent && cd new_agent
+```yaml
+openapi: 3.0.0
+info:
+  title: Test API
+  version: 1.0.0
+  description: A simple API for testing the OpenAPI Handler Generator
+paths:
+  /users:
+    get:
+      summary: List users
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:    
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/User'
+    post:
+      summary: Create a user
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/User'
+      responses:
+        '201':
+          description: Created
+          content:
+            application/json:    
+              schema:
+                $ref: '#/components/schemas/User'
+  /users/{userId}:
+    get:
+      summary: Get a user
+      parameters:
+        - name: userId
+          in: path
+          required: true
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:    
+              schema:
+                $ref: '#/components/schemas/User'
+components:
+  schemas:
+    User:
+      type: object
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: integer
+        name:
+          type: string
+        email:
+          type: string
 ```
 
-This creates a new agent without any real skills.
+2. If not already done, scaffold a repo and a customs component.
 
-Once we have a new agent, we can now use the cli to scaffold the skill using the CORE autonomy libraries and the OpenAPI specification.
+Initialise aea:
 
-This reduces the amount of code we need to write to get a skill up and means that we have no need to write any code to re-implement the wheel.
+```bash
+aea init --remote --author xiuxiuxar --ipfs --reset 
+```
 
-## Scaffolding a new skill
+Create a new repo:
 
-Use the --new-skill flag to scaffold a new skill.
+```bash
+adev repo scaffold --no-install -t autonomy new_station
+```
 
 ```bash
-adev scaffold handler ../auto_dev/data/openapi/openapi_specification.yaml --output my_api_skill --new-skill
+cd new_station
 ```
 
-The skill will be created in the skills directory.  The user will be prompted whether to rename MyModel.py to strategy.py, and whether to remove the dialogues.py file. THe scaffolding step will also install the http protocol, and fingerprint the skill.  At the completion, the user can now run the agent.
+Create a new agent based on the frontend_agent template:
 
 ```bash
-aea run
+adev create xiuxiuxar/agent -t eightballer/frontend_agent --no-clean-up --force
 ```
 
-## Augmenting with an OpenAPI Handler
+```bash
+cd agent
+```
 
-The tools within the `openapi` subcommand are used to augment a customs component with a new handler based on an OpenAPI 3 specification. This process automates the creation of endpoints methods. 
+```bash
+adev eject custom eightballer/simple_html xiuxiuxar/new_handler
+```
 
-## Prerequisites
+```bash
+adev publish xiuxiuxar/agent --force
+```
 
-1. An OpenAPI 3 specification file with paths, operationIds, and if augmenting with DAOs, schemas defined.
-2. A `component.yaml` file in the current directory that references the OpenAPI specification using the `api_spec` field.
-3. If augmenting with DAOs, DAOs for each schema in the OpenAPI specification (see dao docs for how to scaffold these).
+```bash
+cd ..
+```
 
-## Steps to Augment a Handler
 
-1. Ensure you have the OpenAPI 3 specification file. You can view its contents using:
+3. Create or update the `component.yaml` file to reference the OpenAPI specification:
 
 ```bash
-cat auto_dev/data/openapi/openapi_specification.yaml
+cp ../auto_dev/data/openapi/openapi_specification.yaml packages/xiuxiuxar/customs/new_handler/openapi3_spec.yaml
 ```
 
-2. Create or update the `component.yaml` file to reference the OpenAPI specification using the `api_spec` field.
+```bash
+yq e '.api_spec = "openapi3_spec.yaml"' -i packages/xiuxiuxar/customs/new_handler/component.yaml
+```
+
+```bash
+cat packages/xiuxiuxar/customs/new_handler/component.yaml
+```
+
+Output:
 
 ```yaml
-api_spec: <path_to_openapi_specification.yaml>
+version: 0.1.0
+type: custom
+description: Simple HTML frontend to act as a template for the frontend ABCI loader.
+license: Apache-2.0
+aea_version: '>=1.0.0, <2.0.0'
+fingerprint:
+  __init__.py: bafybeidwwtpfuhelmwdkgh2ayk6hls62xpxns33f27qsryzd4vh2kw6hxq
+  behaviours.py: bafybeiadbbujl23thcggr55up7t7jo5nxjk5qty7uqf75xgw57nzrq3dwy
+  build/index.html: bafybeigyjfv75r7fnd7mw63vbidusohzopzyz47c5nmc3tiak5yh22gbfi
+  handlers.py: bafybeibnco7jqjsfwamcek64cvltcr3wvvw73bs74wzbbhwqggy4p4hlsi
+  openapi3_spec.yaml: bafybeibdvlfbr4ghin75dyqjyd3zbusq45uekmuoftmj74k4cvnq2rapci
+  tests/__init__.py: bafybeiayjxaqrjpu7poz56eozqbi4ln7uene4r27bnq5qeely3ambcmggm
+  tests/test_simple_html.py: bafybeiaqu3mw6kq5yq7blk5vjrd5mtw5ej55vs32ftxdf225k3semjyn4u
+fingerprint_ignore_patterns: []
+dependencies: {}
+api_spec: openapi3_spec.yaml
+frontend_dir: build
+behaviours:
+- class_name: LogReadingBehaviour
+  args: {}
+handlers:
+- class_name: HttpHandler
+  args: {}
+```
+
+3. Run the Handler augmenting command:
+
+```bash
+cd packages/xiuxiuxar/customs/new_handler
+```
+
+```bash
+adev augment customs openapi3 --auto-confirm
 ```
 
-3. Run the Handler augmenting command, optionally with the `--use-daos` flag if you are augmenting with DAOs:
+4. Update the component and aea-config.yaml to run the new handler.
 
 ```bash
-adev augment customs openapi3 --use-daos
+cd ../../../..
 ```
 
-The augmenting process creates the following: 
+```bash
+yq e '.handlers[].class_name = "ApiHttpHandler"' -i packages/xiuxiuxar/customs/new_handler/component.yaml
+```
+
+```bash
+yq e '(select(.public_id == "eightballer/trader_abci:0.1.0") | .models.params.args.user_interface.custom_component) = "xiuxiuxar/new_handler"' -i packages/xiuxiuxar/agents/agent/aea-config.yaml
+```
+
+```bash
+autonomy packages lock
+```
+
+5. Run the agent.
+
+```shell
+adev run dev xiuxiuxar/agent --force
+```
 
-1. Handler methods: For each path defined in the OpenAPI specification, a corresponding handler method is generated, along with a general handler and resolver method.
-2. Dialogues.py: A boilerplate dialogues file is generated.
+The augmenting process creates the following handler methods: For each path defined in the OpenAPI specification, a corresponding handler method is generated along with a general handler and resolver method.
 
 ## How It Works
 
@@ -89,4 +223,4 @@ After augmenting your handler:
 
 - Review the generated handler methods in the `handlers.py` file.
 
-Remember to regenerate the Handlers if you make changes to your OpenAPI specification to keep them in sync.
\ No newline at end of file
+Remember to regenerate the Handlers if you make changes to your OpenAPI specification to keep them in sync.

From a5a283ee856c779e0ba47bee67ba574695458210 Mon Sep 17 00:00:00 2001
From: xiuxiuxar <174127740+xiuxiuxar@users.noreply.github.com>
Date: Sun, 2 Mar 2025 12:51:34 -0700
Subject: [PATCH 04/10] Add /api prefix to spec

---
 auto_dev/data/openapi/openapi_specification.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/auto_dev/data/openapi/openapi_specification.yaml b/auto_dev/data/openapi/openapi_specification.yaml
index a2339963..fc05a2a1 100644
--- a/auto_dev/data/openapi/openapi_specification.yaml
+++ b/auto_dev/data/openapi/openapi_specification.yaml
@@ -4,7 +4,7 @@ info:
   version: 1.0.0
   description: A simple API for testing the OpenAPI Handler Generator
 paths:
-  /users:
+  /api/users:
     get:
       summary: List users
       responses:
@@ -31,7 +31,7 @@ paths:
             application/json:    
               schema:
                 $ref: '#/components/schemas/User'
-  /users/{userId}:
+  /api/users/{userId}:
     get:
       summary: Get a user
       parameters:

From a9a719e48d1ac5116d5b99ee2f329a00a83724a3 Mon Sep 17 00:00:00 2001
From: xiuxiuxar <174127740+xiuxiuxar@users.noreply.github.com>
Date: Sun, 2 Mar 2025 12:52:15 -0700
Subject: [PATCH 05/10] Remove indents

---
 docs/dao.md | 238 ++++++++++++++++++++++++++--------------------------
 1 file changed, 119 insertions(+), 119 deletions(-)

diff --git a/docs/dao.md b/docs/dao.md
index dadafd4e..db0257bd 100644
--- a/docs/dao.md
+++ b/docs/dao.md
@@ -11,141 +11,141 @@ The tools within the `dao` subcommand are used to scaffold a new customs compone
 
 1. Ensure you have the OpenAPI 3 specification file. You can view its contents using:
 
-    ```
-    cat auto_dev/data/openapi/openapi_specification.yaml
-    ```
-
-    Output:
-
-    ```yaml
-    openapi: 3.0.0
-    info:
-      title: Test API
-      version: 1.0.0
-      description: A simple API for testing the OpenAPI Handler Generator
-    paths:
-      /users:
-        get:
-          summary: List users
-          responses:
-            '200':
-              description: Successful response
-              content:
-                application/json:    
-                  schema:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/User'
-        post:
-          summary: Create a user
-          requestBody:
-            required: true
-            content:
-              application/json:
-                schema:
+```
+cat auto_dev/data/openapi/openapi_specification.yaml
+```
+
+Output:
+
+```yaml
+openapi: 3.0.0
+info:
+  title: Test API
+  version: 1.0.0
+  description: A simple API for testing the OpenAPI Handler Generator
+paths:
+  /users:
+    get:
+      summary: List users
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:    
+              schema:
+                type: array
+                items:
                   $ref: '#/components/schemas/User'
-          responses:
-            '201':
-              description: Created
-              content:
-                application/json:    
-                  schema:
-                    $ref: '#/components/schemas/User'
-      /users/{userId}:
-        get:
-          summary: Get a user
-          parameters:
-            - name: userId
-              in: path
-              required: true
+    post:
+      summary: Create a user
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/User'
+      responses:
+        '201':
+          description: Created
+          content:
+            application/json:    
+              schema:
+                $ref: '#/components/schemas/User'
+  /users/{userId}:
+    get:
+      summary: Get a user
+      parameters:
+        - name: userId
+          in: path
+          required: true
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:    
               schema:
-                type: integer
-          responses:
-            '200':
-              description: Successful response
-              content:
-                application/json:    
-                  schema:
-                    $ref: '#/components/schemas/User'
-    components:
-      schemas:
-        User:
-          type: object
-          required:
-            - id
-            - name
-          properties:
-            id:
-              type: integer
-            name:
-              type: string
-            email:
-              type: string
-    ```
+                $ref: '#/components/schemas/User'
+components:
+  schemas:
+    User:
+      type: object
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: integer
+        name:
+          type: string
+        email:
+          type: string
+```
 
 2. If not already done, scaffold a repo and a customs component.
 
-    Initialize aea:
-    ```bash
-    aea init --remote --author xiuxiuxar --ipfs --reset 
-    ```
+Initialize aea:
+```bash
+aea init --remote --author xiuxiuxar --ipfs --reset 
+```
 
-    Create a new repo:
-    ```bash
-    adev repo scaffold -t autonomy new_station
-    ```
+Create a new repo:
+```bash
+adev repo scaffold -t autonomy new_station
+```
 
-    ```bash
-    cd new_station
-    ```
+```bash
+cd new_station
+```
 
-    Scaffold a customs component:
-    ```bash
-    aea scaffold -tlr custom simple_dao
-    ```
+Scaffold a customs component:
+```bash
+aea scaffold -tlr custom simple_dao
+```
 
 3. Create or update the `component.yaml` file to reference the OpenAPI specification:
 
-    ```bash
-    cp ../auto_dev/data/openapi/openapi_specification.yaml packages/xiuxiuxar/customs/simple_dao/
-    ```
-
-    ```bash
-    yq e '.api_spec = "openapi_specification.yaml"' -i packages/xiuxiuxar/customs/simple_dao/component.yaml
-    ```
-
-    ```bash
-    cat packages/xiuxiuxar/customs/simple_dao/component.yaml
-    ```
-
-    Output:
-
-    ```yaml
-    name: simple_dao
-    author: xiuxiuxar
-    version: 0.1.0
-    type: custom
-    description: The custom component package.
-    license: Apache-2.0
-    aea_version: '>=1.0.0, <2.0.0'
-    fingerprint:
-      __init__.py: bafybeigjt2jaxismyp3hspvqefjrcp33mmen3pnmnkm4rhesh74io3vikm
-    fingerprint_ignore_patterns: []
-    dependencies: {}
-    api_spec: openapi_specification.yaml
-    ```
+```bash
+cp ../auto_dev/data/openapi/openapi_specification.yaml packages/xiuxiuxar/customs/simple_dao/
+```
+
+```bash
+yq e '.api_spec = "openapi_specification.yaml"' -i packages/xiuxiuxar/customs/simple_dao/component.yaml
+```
+
+```bash
+cat packages/xiuxiuxar/customs/simple_dao/component.yaml
+```
+
+Output:
+
+```yaml
+name: simple_dao
+author: xiuxiuxar
+version: 0.1.0
+type: custom
+description: The custom component package.
+license: Apache-2.0
+aea_version: '>=1.0.0, <2.0.0'
+fingerprint:
+  __init__.py: bafybeigjt2jaxismyp3hspvqefjrcp33mmen3pnmnkm4rhesh74io3vikm
+fingerprint_ignore_patterns: []
+dependencies: {}
+api_spec: openapi_specification.yaml
+```
 
 4. Run the DAO scaffolding command from the customs component directory:
 
-    ```bash
-    cd packages/xiuxiuxar/customs/simple_dao
-    ```
+```bash
+cd packages/xiuxiuxar/customs/simple_dao
+```
 
-    We automatically confirm all actions, though you can omit the `--auto-confirm` flag to see the actions that will be taken.
+We automatically confirm all actions, though you can omit the `--auto-confirm` flag to see the actions that will be taken.
 
-    ```bash
-    adev scaffold dao --auto-confirm
-    ```
+```bash
+adev scaffold dao --auto-confirm
+```
 
 ## Generated Files
 

From f5843c81144b469a706e13c171621ef9e85f58c2 Mon Sep 17 00:00:00 2001
From: xiuxiuxar <174127740+xiuxiuxar@users.noreply.github.com>
Date: Tue, 4 Mar 2025 17:19:33 -0700
Subject: [PATCH 06/10] Cleanup dao doc

---
 docs/dao.md | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/docs/dao.md b/docs/dao.md
index db0257bd..e7b5c724 100644
--- a/docs/dao.md
+++ b/docs/dao.md
@@ -9,7 +9,9 @@ The tools within the `dao` subcommand are used to scaffold a new customs compone
 
 ## Steps to Create a Data Access Object
 
-1. Ensure you have the OpenAPI 3 specification file. You can view its contents using:
+### 1. Define an OpenAPI3 spec
+
+Ensure you have the OpenAPI 3 specification file. You can view its contents using:
 
 ```
 cat auto_dev/data/openapi/openapi_specification.yaml
@@ -83,7 +85,7 @@ components:
           type: string
 ```
 
-2. If not already done, scaffold a repo and a customs component.
+### 2. [Optional] Scaffold a repo and a customs component.
 
 Initialize aea:
 ```bash
@@ -104,7 +106,7 @@ Scaffold a customs component:
 aea scaffold -tlr custom simple_dao
 ```
 
-3. Create or update the `component.yaml` file to reference the OpenAPI specification:
+### 3. Create or update the `component.yaml` file to reference the OpenAPI specification.
 
 ```bash
 cp ../auto_dev/data/openapi/openapi_specification.yaml packages/xiuxiuxar/customs/simple_dao/
@@ -135,7 +137,7 @@ dependencies: {}
 api_spec: openapi_specification.yaml
 ```
 
-4. Run the DAO scaffolding command from the customs component directory:
+### 4. Run the DAO scaffolding command.
 
 ```bash
 cd packages/xiuxiuxar/customs/simple_dao
@@ -155,10 +157,10 @@ The scaffolding process generates the following files in your customs component:
 daos/
 ├── __init__.py
 ├── base_dao.py              # Base Data Access Object class
-├── <model_name_1>_dao.py   # Model-specific Data Access Object
-├── <model_name_2>_dao.py   # Model-specific Data Access Object
+├── <model_name_1>_dao.py    # Model-specific Data Access Object
+├── <model_name_2>_dao.py    # Model-specific Data Access Object
 ├── aggregated_data.json     # Sample data for testing
-└── test_dao.py             # Test script
+└── test_dao.py              # Test script
 ```
 
 ## Implementation Details

From 713e897c4c7212e63d7dc9162cca61a0958b7cd2 Mon Sep 17 00:00:00 2001
From: xiuxiuxar <174127740+xiuxiuxar@users.noreply.github.com>
Date: Tue, 4 Mar 2025 17:20:12 -0700
Subject: [PATCH 07/10] Cleanup openapi doc

---
 docs/openapi.md | 60 ++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 47 insertions(+), 13 deletions(-)

diff --git a/docs/openapi.md b/docs/openapi.md
index 40d10c11..de242ca6 100644
--- a/docs/openapi.md
+++ b/docs/openapi.md
@@ -4,13 +4,13 @@ The tools within the `openapi` subcommand are used to augment a customs componen
 
 ## Prerequisites
 
-1. An OpenAPI 3 specification file with paths, operationIds, and if augmenting with DAOs, schemas defined.
+1. An OpenAPI 3 specification file with paths, operationIds, and if augmenting with data access objects, schemas defined.
 2. A `component.yaml` file in the current directory that references the OpenAPI specification using the `api_spec` field.
 3. If augmenting with DAOs, DAOs for each schema in the OpenAPI specification (see dao docs for how to scaffold these).
 
-## Steps to Augment a Handler (without DAOs)
+## Steps to Augment a Handler (without data access objects)
 
-1. Create an OpenAPI3 specification yaml.
+### 1. Define an OpenAPI3 spec.
 
 ```
 cat auto_dev/data/openapi/openapi_specification.yaml
@@ -25,7 +25,7 @@ info:
   version: 1.0.0
   description: A simple API for testing the OpenAPI Handler Generator
 paths:
-  /users:
+  /api/users:
     get:
       summary: List users
       responses:
@@ -52,7 +52,7 @@ paths:
             application/json:    
               schema:
                 $ref: '#/components/schemas/User'
-  /users/{userId}:
+  /api/users/{userId}:
     get:
       summary: Get a user
       parameters:
@@ -84,7 +84,7 @@ components:
           type: string
 ```
 
-2. If not already done, scaffold a repo and a customs component.
+### 2. [Optional] Scaffold a repo and a customs component.
 
 Initialise aea:
 
@@ -112,10 +112,14 @@ adev create xiuxiuxar/agent -t eightballer/frontend_agent --no-clean-up --force
 cd agent
 ```
 
+Eject a custom component to use as a base handler template:
+
 ```bash
 adev eject custom eightballer/simple_html xiuxiuxar/new_handler
 ```
 
+Push to the local packages directory:
+
 ```bash
 adev publish xiuxiuxar/agent --force
 ```
@@ -125,7 +129,7 @@ cd ..
 ```
 
 
-3. Create or update the `component.yaml` file to reference the OpenAPI specification:
+### 3. Create or update the `component.yaml` file to reference the OpenAPI specification.
 
 ```bash
 cp ../auto_dev/data/openapi/openapi_specification.yaml packages/xiuxiuxar/customs/new_handler/openapi3_spec.yaml
@@ -167,26 +171,32 @@ handlers:
   args: {}
 ```
 
-3. Run the Handler augmenting command:
+### 4. Run the Handler augment command.
 
 ```bash
 cd packages/xiuxiuxar/customs/new_handler
 ```
 
+We automatically confirm all actions, though you can omit the `--auto-confirm` flag to see the actions that will be taken.
+
 ```bash
 adev augment customs openapi3 --auto-confirm
 ```
 
-4. Update the component and aea-config.yaml to run the new handler.
+### 5. Update the component and aea-config.yaml to run the new handler.
 
 ```bash
 cd ../../../..
 ```
 
+We ensure the component yaml references the handler class:
+
 ```bash
 yq e '.handlers[].class_name = "ApiHttpHandler"' -i packages/xiuxiuxar/customs/new_handler/component.yaml
 ```
 
+Modify the agent to load the new custom handler method:
+
 ```bash
 yq e '(select(.public_id == "eightballer/trader_abci:0.1.0") | .models.params.args.user_interface.custom_component) = "xiuxiuxar/new_handler"' -i packages/xiuxiuxar/agents/agent/aea-config.yaml
 ```
@@ -195,7 +205,7 @@ yq e '(select(.public_id == "eightballer/trader_abci:0.1.0") | .models.params.ar
 autonomy packages lock
 ```
 
-5. Run the agent.
+### 6. Run the agent.
 
 ```shell
 adev run dev xiuxiuxar/agent --force
@@ -207,8 +217,8 @@ The augmenting process creates the following handler methods: For each path defi
 
 The augmentation process involves several steps:
 
-1. Loading and validating the OpenAPI specification
-2. Generating Handler methods for each path
+1. Loading and validating the OpenAPI specification.
+2. Generating handler methods for each path.
 
 For more details on the implementation, refer to:
 `auto_dev/handler/scaffolder.py`
@@ -223,4 +233,28 @@ After augmenting your handler:
 
 - Review the generated handler methods in the `handlers.py` file.
 
-Remember to regenerate the Handlers if you make changes to your OpenAPI specification to keep them in sync.
+Remember to regenerate the handlers if you make changes to your OpenAPI specification to keep them in sync.
+
+## Steps to Augment a Handler (with DAOs)
+
+### 1. Perform steps 1-3 above. 
+
+### 2. Run the DAO scaffold command.
+
+[NOTE]
+We automatically confirm all actions, though you can omit the `--auto-confirm` flag to see the actions that will be taken.
+
+
+```shell
+adev scaffold dao --auto-confirm
+```
+
+### 3. Run the handler augment command with DAO flag.  
+
+We automatically confirm all actions, though you can omit the `--auto-confirm` flag to see the actions that will be taken.
+
+```shell
+adev augment customs openapi3 --use-daos --auto-confirm
+```
+
+### 4. Perform 5-6 above.
\ No newline at end of file

From 3014edcf1155f45120ca17f9e2cd05a2095acc0b Mon Sep 17 00:00:00 2001
From: xiuxiuxar <174127740+xiuxiuxar@users.noreply.github.com>
Date: Tue, 4 Mar 2025 17:53:10 -0700
Subject: [PATCH 08/10] Update formatting

---
 docs/openapi.md | 92 ++++++++++++++++++++++++++++---------------------
 1 file changed, 53 insertions(+), 39 deletions(-)

diff --git a/docs/openapi.md b/docs/openapi.md
index de242ca6..82c23068 100644
--- a/docs/openapi.md
+++ b/docs/openapi.md
@@ -1,16 +1,16 @@
-# Augmenting visualisation station with an OpenAPI Handler
+# OpenAPI Handler Integration
 
-The tools within the `openapi` subcommand are used to augment a customs component with handler methods based on an OpenAPI 3 specification. This process automates the creation of endpoints methods. 
+This guide explains how to augment components with handler methods based on an OpenAPI 3.
 
 ## Prerequisites
 
-1. An OpenAPI 3 specification file with paths, operationIds, and if augmenting with data access objects, schemas defined.
-2. A `component.yaml` file in the current directory that references the OpenAPI specification using the `api_spec` field.
-3. If augmenting with DAOs, DAOs for each schema in the OpenAPI specification (see dao docs for how to scaffold these).
+- An OpenAPI 3 specification file with defined paths and operationIds
+- A `component.yaml` file referencing the OpenAPI specification via the `api_spec` field.
+- For DAO integration: Data Access Objects for each schema in the specification. See [Data Access Object](dao.md).
 
-## Steps to Augment a Handler (without data access objects)
+## Basic Handler Augmentation
 
-### 1. Define an OpenAPI3 spec.
+### 1. Define an OpenAPI 3 Specification.
 
 ```
 cat auto_dev/data/openapi/openapi_specification.yaml
@@ -84,7 +84,10 @@ components:
           type: string
 ```
 
-### 2. [Optional] Scaffold a repo and a customs component.
+### 2. Set Up Your Project Structure
+
+!!! note "Optional Step"
+    Skip this if you already have a project structure set up.
 
 Initialise aea:
 
@@ -129,7 +132,9 @@ cd ..
 ```
 
 
-### 3. Create or update the `component.yaml` file to reference the OpenAPI specification.
+### 3. Configure Your Component
+
+Add your OpenAPI specification to the component:
 
 ```bash
 cp ../auto_dev/data/openapi/openapi_specification.yaml packages/xiuxiuxar/customs/new_handler/openapi3_spec.yaml
@@ -171,7 +176,7 @@ handlers:
   args: {}
 ```
 
-### 4. Run the Handler augment command.
+### 4. Run the Augmentation Command
 
 ```bash
 cd packages/xiuxiuxar/customs/new_handler
@@ -183,7 +188,7 @@ We automatically confirm all actions, though you can omit the `--auto-confirm` f
 adev augment customs openapi3 --auto-confirm
 ```
 
-### 5. Update the component and aea-config.yaml to run the new handler.
+### 5. Update Configuration
 
 ```bash
 cd ../../../..
@@ -205,56 +210,65 @@ yq e '(select(.public_id == "eightballer/trader_abci:0.1.0") | .models.params.ar
 autonomy packages lock
 ```
 
-### 6. Run the agent.
+### 6. Run Your Agent
 
 ```shell
 adev run dev xiuxiuxar/agent --force
 ```
 
-The augmenting process creates the following handler methods: For each path defined in the OpenAPI specification, a corresponding handler method is generated along with a general handler and resolver method.
+## Advanced: Integration with Data Access Objects (DAOs)
 
-## How It Works
+### 1. Complete Basic Setup
 
-The augmentation process involves several steps:
+Follow steps 1-3 from the basic handler augmentation.
 
-1. Loading and validating the OpenAPI specification.
-2. Generating handler methods for each path.
+### 2. Scaffold DAOs
 
-For more details on the implementation, refer to:
-`auto_dev/handler/scaffolder.py`
+!!! tip
+    We automatically confirm all actions, though you can omit the `--auto-confirm` flag to see the actions that will be taken.
 
-## Customization
 
-The generated Handler methods use Jinja2 templates for customization. If you need to modify the structure of the generated classes, you can update the templates located in the `JINJA_TEMPLATE_FOLDER`.
+```shell
+adev scaffold dao --auto-confirm
+```
 
-## Next Steps
+### 3. Augment with DAO Integration
 
-After augmenting your handler:
+!!! tip
+    We automatically confirm all actions, though you can omit the `--auto-confirm` flag to see the actions that will be taken.
 
-- Review the generated handler methods in the `handlers.py` file.
+```shell
+adev augment customs openapi3 --use-daos --auto-confirm
+```
 
-Remember to regenerate the handlers if you make changes to your OpenAPI specification to keep them in sync.
+### 4. Complete Configuration
 
-## Steps to Augment a Handler (with DAOs)
+Follow steps 5-6 from the basic handler augmentation.
 
-### 1. Perform steps 1-3 above. 
+## How It Works
 
-### 2. Run the DAO scaffold command.
+The augmentation process:
 
-[NOTE]
-We automatically confirm all actions, though you can omit the `--auto-confirm` flag to see the actions that will be taken.
+1. Loads and validates the OpenAPI specification
+2. Generates handler methods for each defined path
+3. Creates resolver methods to handle requests
+4. When using DAOs, connects endpoints to database operations
 
+!!! tip "Implementation Details"
+    For more details on the implementation, see `auto_dev/handler/scaffolder.py`
 
-```shell
-adev scaffold dao --auto-confirm
-```
+## Customization
 
-### 3. Run the handler augment command with DAO flag.  
+The generated handlers use Jinja2 templates. To customize the structure:
 
-We automatically confirm all actions, though you can omit the `--auto-confirm` flag to see the actions that will be taken.
+1. Locate the templates in the `JINJA_TEMPLATE_FOLDER`
+2. Modify them to suit your specific requirements
+3. Re-run the augmentation command
 
-```shell
-adev augment customs openapi3 --use-daos --auto-confirm
-```
+## Best Practices
+
+!!! warning "Keep in Sync"
+    Always regenerate handlers after modifying your OpenAPI specification to maintain consistency.
 
-### 4. Perform 5-6 above.
\ No newline at end of file
+!!! success "Review Generated Code"
+    After augmentation, review the generated code in `handlers.py` to ensure it meets your requirements.

From a00eb78f73fcb7fe70647ba26eb7d2a43ec57edf Mon Sep 17 00:00:00 2001
From: xiuxiuxar <174127740+xiuxiuxar@users.noreply.github.com>
Date: Tue, 4 Mar 2025 17:59:22 -0700
Subject: [PATCH 09/10] Update formatting

---
 docs/dao.md | 108 ++++++++++++++++++++++++++++++++--------------------
 1 file changed, 67 insertions(+), 41 deletions(-)

diff --git a/docs/dao.md b/docs/dao.md
index e7b5c724..d4d81c59 100644
--- a/docs/dao.md
+++ b/docs/dao.md
@@ -1,17 +1,17 @@
-# Scaffolding a new Data Access Object (DAO)
+# Data Access Object (DAO) Scaffolding
 
-The tools within the `dao` subcommand are used to scaffold a new customs component Data Access Object (DAO) based on an OpenAPI 3 specification. This process automates the creation of Data Access Object classes, dummy data, and test scripts.
+This guide explains how to scaffold Data Access Objects based on an OpenAPI 3 specification, automating the creation of database interaction classes.
 
 ## Prerequisites
 
-1. An OpenAPI 3 specification file with components/schema models defined.
-2. A `component.yaml` file in the current directory that references the OpenAPI specification using the `api_spec` field.
+- An OpenAPI 3 specification file with defined components/schema models
+- A `component.yaml` file referencing the OpenAPI specification via the `api_spec` field
 
-## Steps to Create a Data Access Object
+## Quick Start
 
-### 1. Define an OpenAPI3 spec
+### 1. Define an OpenAPI 3 specification
 
-Ensure you have the OpenAPI 3 specification file. You can view its contents using:
+Your specification should include schema definitions:
 
 ```
 cat auto_dev/data/openapi/openapi_specification.yaml
@@ -26,7 +26,7 @@ info:
   version: 1.0.0
   description: A simple API for testing the OpenAPI Handler Generator
 paths:
-  /users:
+  /api/users:
     get:
       summary: List users
       responses:
@@ -53,7 +53,7 @@ paths:
             application/json:    
               schema:
                 $ref: '#/components/schemas/User'
-  /users/{userId}:
+  /api/users/{userId}:
     get:
       summary: Get a user
       parameters:
@@ -85,7 +85,10 @@ components:
           type: string
 ```
 
-### 2. [Optional] Scaffold a repo and a customs component.
+### 2. Set Up Your Project Structure
+
+!!! note "Optional Step"
+    Skip this if you already have a project structure set up.
 
 Initialize aea:
 ```bash
@@ -106,7 +109,7 @@ Scaffold a customs component:
 aea scaffold -tlr custom simple_dao
 ```
 
-### 3. Create or update the `component.yaml` file to reference the OpenAPI specification.
+### 3. Configure Your Component
 
 ```bash
 cp ../auto_dev/data/openapi/openapi_specification.yaml packages/xiuxiuxar/customs/simple_dao/
@@ -137,21 +140,22 @@ dependencies: {}
 api_spec: openapi_specification.yaml
 ```
 
-### 4. Run the DAO scaffolding command.
+### 4. Generate DAOs
 
 ```bash
 cd packages/xiuxiuxar/customs/simple_dao
 ```
 
-We automatically confirm all actions, though you can omit the `--auto-confirm` flag to see the actions that will be taken.
+!!! tip
+    We automatically confirm all actions, though you can omit the `--auto-confirm` flag to see the actions that will be taken.
 
 ```bash
 adev scaffold dao --auto-confirm
 ```
 
-## Generated Files
+## Generated Structure
 
-The scaffolding process generates the following files in your customs component:
+The scaffolding process creates the following files:
 
 ```
 daos/
@@ -159,48 +163,70 @@ daos/
 ├── base_dao.py              # Base Data Access Object class
 ├── <model_name_1>_dao.py    # Model-specific Data Access Object
 ├── <model_name_2>_dao.py    # Model-specific Data Access Object
-├── aggregated_data.json     # Sample data for testing
+├── aggregated_data.json     # Sample test data
 └── test_dao.py              # Test script
 ```
 
-## Implementation Details
+## Understanding the Generated Code
+
+### Base DAO
+
+The `base_dao.py` file contains:
 
-1. Base Data Access Object Class
-2. Generating Data Access Object classes for each model
-3. Test Script Generation
+- Common CRUD operations (Create, Read, Update, Delete)
+- Transaction handling
+- Error management
 
-## How It Works
+### Model-Specific DAOs
 
-The scaffolding process involves several steps:
+Each model gets its own DAO class with:
 
-1. Loading and validating the OpenAPI specification (checking for required fields, etc.)
-2. Generating DAO classes for each model
-3. Creating dummy data for testing
-4. Generating a test script
+- Model-specific validation
+- Custom query methods
+- Type hints for your schema
 
-For more details on the implementation, refer to:
-`auto_dev/dao/scaffolder.py`
+### Test Data
+
+The `aggregated_data.json` file contains:
+
+- Sample data for each model
+- Valid test cases for CRUD operations
 
 ## Customization
 
-The generated DAO classes use Jinja2 templates for customization. If you need to modify the structure of the generated classes, you can update the templates located in the `auto_dev/data/templates/dao` directory.
+!!! tip "Template Customization"
+    The generated DAOs use Jinja2 templates. To customize:
+    
+    1. Locate templates in `auto_dev/data/templates/dao`
+    2. Modify them to suit your requirements
+    3. Re-run the scaffolding command
+
+## Best Practices
 
-## Error Handling
+### Error Handling
 
 The scaffolding process validates:
-- `component.yaml` exists and has `api_spec` field
-- OpenAPI spec file exits and is valid YAML
-- OpenAPI spec contains components/schemas
-- OpenAPI spec follows OpenAPI 3.0 format
 
-Detailed error messages are logged for troubleshooting.
+- Component configuration
+- OpenAPI specification format
+- Schema definitions
 
-## Next Steps
+!!! warning "Schema Requirements"
+    Ensure your OpenAPI spec includes proper schema definitions with required fields and property types.
 
-After scaffolding your Data Access Objects:
+### Keeping DAOs in Sync
+
+!!! success "Regenerate After Changes"
+    Always regenerate your DAOs after modifying your OpenAPI specification to maintain consistency.
+
+## Testing Your DAOs
+
+Run the generated test script to verify functionality:
+
+```bash
+python -m packages.your_author.customs.simple_dao.daos.test_dao
+```
 
-1. Review the generated Data Access Object classes in the `daos/` directory.
-2. Customize the generated classes as needed.
-3. Run the `test_dao.py` script to ensure the basic functionality of your Data Access Objects.
+## Integration with Handlers
 
-Remember to regenerate the Data Access Objects if you make changes to your OpenAPI specification to keep them in sync.
\ No newline at end of file
+DAOs work seamlessly with OpenAPI handlers. See the [OpenAPI Handler Integration](openapi.md) guide for details on connecting your DAOs to API endpoints.
\ No newline at end of file

From 8383e4e1803711700e7597e01936e4f15ffe9929 Mon Sep 17 00:00:00 2001
From: xiuxiuxar <174127740+xiuxiuxar@users.noreply.github.com>
Date: Tue, 4 Mar 2025 18:05:12 -0700
Subject: [PATCH 10/10] Fix test

---
 docs/dao.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/dao.md b/docs/dao.md
index d4d81c59..edd88f82 100644
--- a/docs/dao.md
+++ b/docs/dao.md
@@ -223,7 +223,7 @@ The scaffolding process validates:
 
 Run the generated test script to verify functionality:
 
-```bash
+```
 python -m packages.your_author.customs.simple_dao.daos.test_dao
 ```