From 1eadbb66316c4acb5d19f88d985e0d7786685933 Mon Sep 17 00:00:00 2001
From: Vibn Agent Runner <agent@vibnai.com>
Date: Thu, 26 Feb 2026 23:04:01 +0000
Subject: [PATCH] feat: Add PROJECT.md documentation for vibn-agent-runner

---
 PROJECT.md | 103 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 103 insertions(+)
 create mode 100644 PROJECT.md

diff --git a/PROJECT.md b/PROJECT.md
new file mode 100644
index 0000000..4db8743
--- /dev/null
+++ b/PROJECT.md
@@ -0,0 +1,103 @@
+# vibn-agent-runner Project Documentation
+
+## What it does
+
+The `vibn-agent-runner` is a service responsible for executing tasks or "agents" within the Vibn ecosystem. It likely receives requests to run specific agents, manages their execution, and reports back their status or results. This service acts as a crucial component for extending Vibn's capabilities through custom or predefined agents.
+
+## API Endpoints
+
+(Note: These are example endpoints. Please refer to the source code or API documentation for exact details.)
+
+### `POST /run-agent`
+
+Initiates the execution of an agent.
+
+- **Method:** `POST`
+- **URL:** `/run-agent`
+- **Request Body Example:**
+  ```json
+  {
+    "agentId": "your-agent-id",
+    "payload": {
+      "param1": "value1",
+      "param2": "value2"
+    }
+  }
+  ```
+- **Response Body Example (Success):**
+  ```json
+  {
+    "status": "success",
+    "runId": "unique-run-id",
+    "message": "Agent execution started."
+  }
+  ```
+- **Response Body Example (Error):**
+  ```json
+  {
+    "status": "error",
+    "message": "Failed to start agent execution.",
+    "details": "Error message details"
+  }
+  ```
+
+### `GET /agent-status/{runId}`
+
+Retrieves the status of a running or completed agent.
+
+- **Method:** `GET`
+- **URL:** `/agent-status/{runId}`
+- **Response Body Example:**
+  ```json
+  {
+    "runId": "unique-run-id",
+    "status": "running", // or "completed", "failed"
+    "progress": "50%",
+    "results": {} // or actual results if completed
+  }
+  ```
+
+## How to run locally
+
+To run the `vibn-agent-runner` locally, follow these steps:
+
+1.  **Clone the repository:**
+    ```bash
+    git clone <repository-url>
+    cd vibn-agent-runner
+    ```
+
+2.  **Install dependencies:**
+    ```bash
+    npm install
+    ```
+    or
+    ```bash
+    yarn install
+    ```
+
+3.  **Configure environment variables:**
+    Copy the `.env.example` file to `.env` and update the values as needed.
+    ```bash
+    cp .env.example .env
+    ```
+
+4.  **Build the project (if TypeScript):**
+    ```bash
+    npm run build
+    ```
+    or
+    ```bash
+    yarn build
+    ```
+
+5.  **Start the application:**
+    ```bash
+    npm start
+    ```
+    or
+    ```bash
+    yarn start
+    ```
+
+The application should now be running, typically accessible at `http://localhost:3000` (or another port specified in your environment configuration).
\ No newline at end of file