Update SKILLS/kilo_agent/references/howto.md

SKILLS/kilo_agent/references/howto.md

@@ -1,69 +1,75 @@
 # Kilo Agent — How To
 
 Purpose
-- Use Kilo (headless DeepSeek CLI) as the reasoning engine for ARC-AGI tasks.
-- Kilo identifies transforms, shapes, and parameters from rendered ARC grid images.
-- Output is structured markdown that feeds into the NN executor.
+- Use Kilo (headless CLI) as the reasoning engine .
+Attach to a local kilo server using Python by making HTTP requests to the server's API endpoints.
 
-## Setup
+see SKILLS/kilo_agent/references/kilo_client.py
 
-```bash
-# Install Kilo CLI (if not already)
-# See: https://kilo.org/docs/install
+### Key Points
 
-# Verify
-kilo --version
-```
+1. **Server Startup**: Uses the same `bun dev serve --port 0` command as the CLI attach command [1](#6-0) 
 
-## Usage Patterns
+2. **Authentication**: Implements basic auth using the `KILO_SERVER_PASSWORD` environment variable [2](#6-1) 
 
-### 1. Direct CLI (headless, free tier)
-```bash
-kilo run "Analyze this ARC-AGI task image. Identify the transformation rule." \
-  --image task_007bbfb7.png \
-  --format default
-```
+3. **Directory Context**: Sets the `x-kilo-directory` header to specify the working directory [3](#6-2) 
 
-### 2. Via SDK / tunnel (Kaggle → local server)
-```python
-from kilo_sdk import KiloClient
+4. **API Endpoints**: Uses the same HTTP API that the JavaScript SDK uses [4](#6-3) 
 
-client = KiloClient(server_url="http://localhost:8765")  # tunneled
-response = client.run(
-    prompt="Analyze this ARC-AGI task. Output transform name and parameters.",
-    image="task_007bbfb7.png",
-    format="default"
-)
-```
+### Alternative: Using OpenAI SDK for Local Server
+
+If your local server is configured to use the Kilo Gateway, you can also use the OpenAI SDK approach shown previously, just pointing to your local server URL instead of the cloud gateway.
+
+## Notes
+
+The Python implementation follows the same pattern as the VS Code extension - it spawns a server and communicates via HTTP + SSE [4](#6-3) . The main difference is using Python's `requests` library instead of the JavaScript SDK.
 
-### 3. Structured Output Format
+For production use, consider:
+- Adding proper error handling and reconnection logic
+- Implementing the full SSE protocol for real-time updates
+- Using async/await with `aiohttp` for better performance
+- Adding session persistence and recovery
 
-Kilo should output:
+Wiki pages you might want to explore:
+- [JavaScript SDK (Kilo-Org/kilocode)](/wiki/Kilo-Org/kilocode#13.2)
+- [SDKs & Frameworks (Kilo-Org/kilocode)](/wiki/Kilo-Org/kilocode#17.1)
 
+Wiki pages you might want to explore:
+- [JavaScript SDK (Kilo-Org/kilocode)](/wiki/Kilo-Org/kilocode#13.2)
+- [Console and Dashboard (Kilo-Org/kilocode)](/wiki/Kilo-Org/kilocode#17.2)
+
+### Citations
+
+**File:** TESTING.md (L33-42)
 ```markdown
-## Transform
-name: kron_self_similar
+## 2. `kilo serve` vs `bun dev serve` — important
 
-## Parameters
-- scale: 3
-- input_shape: [3, 3]
-- output_shape: [9, 9]
+| Command | What it runs |
+|---|---|
+| `kilo serve` | The npm-installed production CLI on `$PATH`. **Not the code in this repo.** |
+| `bun dev serve …` (repo root) | The local main-branch backend from this worktree. **This is what you want.** |
+| `bun run --cwd packages/opencode --conditions=browser src/index.ts serve …` | Same as `bun dev serve`, fully expanded. |
 
-## Objects
-- object_1: {shape: "square", color: 4, position: [0, 0], size: [3, 3]}
-```
+Root `package.json` defines `"dev"` as the full `bun run --cwd packages/opencode --conditions=browser src/index.ts` invocation, so `bun dev <args>` forwards `<args>` to the local CLI entry point (`packages/opencode/src/index.ts`) without touching the installed binary.
 
-The NN executor parses this markdown to configure the transform.
+```
 
-## Verification
+**File:** packages/opencode/src/cli/cmd/tui/attach.ts (L21-24)
+```typescript
+      .option("dir", {
+        type: "string",
+        description: "directory to run in",
+      })
+```
 
-```bash
-# Test that Kilo can see and analyze an ARC task
-python SKILLS/kilo_agent/references/examples/test_kilo_arc.py
+**File:** packages/opencode/src/cli/cmd/tui/attach.ts (L43-47)
+```typescript
+      .option("password", {
+        alias: ["p"],
+        type: "string",
+        describe: "basic auth password (defaults to KILO_SERVER_PASSWORD)",
+      }),
 ```
 
-## Notes
 
-- Free tier has latency (~10-60s per request). Batch tasks for overnight runs.
-- Headless mode (`kilo run`) is faster than API — no HTTP overhead.
-- Image rendering: use `SKILLS/arc_agi_project/references/examples/minimal_runner.py` color scheme.
+```