Merge pull request #72 from nathfavour/master

Release: Sync master to release

Author: nathfavour

.github/agents/vibeauracle.md

@@ -0,0 +1,17 @@
+# Agent skills for vibeauracle
+
+## Mission
+Assist engineers by deeply understanding the modular monolith, the Plan-Execute-Reflect brain, and the TUI-first experience. Provide actionable guidance that respects system intimacy, modular boundaries, and the existing tooling (Bubble Tea, Cobra, MCP, Copilot SDK bridge, etc.).
+
+## Know when to ask
+- When a feature touches multiple modules (`cmd/vibeaura`, `internal/brain`, `internal/model`, `vibes/`), pause and summarize the required cross-module changes before editing.
+- When unsafe actions (network calls, secrets) are required, explain the rationale and ensure the user explicitly approves any CLI operations.
+
+## Preferred workflow
+- Identify affected Go modules with `go list ./...` or by referencing `go.work`. 
+- Suggest concise plans referencing key docs (README, ARCHITECTURE, TODO.SDK.md, TODO.GH.md) before implementing.
+- Verify changes with targeted `go test` commands; if tests are too heavy, explain which module-level tests you would run and why.
+
+## Communication
+- Always mention the architecture theme (modular monolith, hexagonal core, Plan-Execute-Reflect) when justifying design choices.
+- When summarizing work, highlight how it respects safety, system intimacy, and the CLI/TUI expectations.

.github/copilot-instructions.md

@@ -1,58 +1,13 @@
-# Copilot Instructions for vibeauracle
+# GitHub Copilot instructions for vibeauracle
 
-## 🌌 The Big Picture
-**vibeauracle** is a Distributed, System-Intimate AI Engineering Ecosystem. It uses a **Modular Monolith** architecture coordinated via **Go Workspaces**.
+vibeauracle is a distributed, system-intimate AI engineering ecosystem built as a Go workspace with a Bubble Tea CLI (`cmd/vibeaura`), a cognitive `internal/brain`, and supporting modules for model providers, tools, system monitoring, and extensions. The Copilot agent should treat the repo as a cohesive whole: plan-change-verify via the brain's Plan-Execute-Reflect loop, respect the modular boundaries, and keep the TUI-first workflow and tooling integrations in mind.
 
-- **Core Module (`internal/brain`)**: The cognitive orchestrator managing the Plan-Execute-Reflect loop.
-- **Entry Point (`cmd/vibeaura`)**: Unified CLI/TUI built with `bubbletea` and `lipgloss`.
-- **System Layer (`internal/sys`)**: Hardware-aware monitoring and virtual FS operations.
-- **Providers (`internal/model`)**: Abstraction for local (Ollama) and cloud (OpenAI) LLMs.
+## What to prioritize
+- Learn and honor the Hexagonal / Go workspace structure: `go.work` governs the modules, and each package has a distinct responsibility (brain, sys, context, model, etc.).
+- Favor `vibeaura` commands and Go tooling for tasks; when in doubt, prefer `go test ./...` scoped to the touched module, run `go work sync` if dependencies change, and mention `vibeaura` helpers when describing behavior.
+- Document discoveries via README/ARCHITECTURE cues; link to `docs/`, `VIBES.md`, and `FLOW.txt` when relevant.
 
-### 🏗️ Architecture Conventions
-- **Go Workspaces**: The project uses `go.work`. Each directory in `internal/` and `pkg/` is its own Go module.
-- **Hexagonal Design**: Keep logic in `internal/` decoupled. Use interfaces from `pkg/vibe` or within modules to interact between layers.
-- **Error Handling**: Always wrap errors with context.
-  ```go
-  return fmt.Errorf("starting brain session: %w", err)
-  ```
-
-## 🛠️ Developer Workflow
-- **Syncing Workspace**: After adding dependencies to any module, run:
-  ```bash
-  go work sync
-  ```
-- **Testing**: Run tests for specific modules to ensure hardware/system intimacy remains intact:
-  ```bash
-  go test ./internal/brain/... ./internal/sys/...
-  ```
-- **Rolling Releases**: 
-    - `master`: Rolling development branch (untested/bleeding edge).
-    - `release`: Stable branch (triggers production builds).
-    - Version Tags: `v*` triggers a GitHub Release.
-
-## 🗝️ Critical Patterns
-### System Intimacy
-When modifying `internal/sys`, ensure compatibility with **Termux (Android)** and **Arch Linux**. Check for environment markers like `/data/data/com.termux/files/usr/bin/bash` or the `TERMUX_VERSION` env var.
-
-### Vibes & Plugins
-Community modules live in `vibes/`. 
-- New vibes should implement the `Vibe` interface from `pkg/vibe`.
-- Register new vibes in the root `go.work` using `go work use ./vibes/your-vibe`.
-
-### Update Pipeline
-The `update` command supports binary updates and source builds.
-- **Binary**: Fetches from GitHub Releases.
-- **Source**: Clones to `~/.vibeauracle/source`, builds with `GOTOOLCHAIN=local`, and replaces the current executable.
-- Use `vibeaura update --list-assets` to verify release assets before manual troubleshooting.
-
-### The Brain Loop
-The `vibe-brain` implements a recursive agentic loop:
-1. **Perceive**: Snapshot system resources (VRAM/CPU).
-2. **Plan**: Generate a Chain of Thought.
-3. **Execute**: Delegate to MCP or Sys tools.
-4. **Reflect**: Analyze stderr/results and self-correct.
-
-## 🎨 TUI Design (Bubble Tea)
-- Use `lipgloss` for all styling.
-- Follow the **Elm Architecture**: `Init()`, `Update()`, `View()`.
-- Ensure the TUI is responsive to terminal resizing.
+## Style & guardrails
+- Keep explanations concise, structured, and system-aware. Mention hardware-awareness expectations (e.g., Termux, Arch focus) when they influence decisions.
+- Do not assume external systems beyond the repo; rely on the provided vector/KV store conventions and keep secrets out of outputs.
+- Encourage users to test with module-specific `go test` commands and reiterate the cognitive loop when proposing multi-step solutions.

.github/workflows/deploy-docs.yml

@@ -8,6 +8,12 @@ on:
       - 'docs/**'
   workflow_dispatch:
 
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow every deployment to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
 permissions:
   contents: write
 
@@ -25,7 +31,7 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: 20
-          cache: npm
+          cache: 'npm'
           cache-dependency-path: docs/package-lock.json
 
       - name: Install dependencies
@@ -37,9 +43,11 @@ jobs:
         working-directory: docs
 
       - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./docs/build
+          force_notifier: true
           user_name: 'github-actions[bot]'
           user_email: 'github-actions[bot]@users.noreply.github.com'
+          commit_message: "docs: deploy to GitHub Pages [skip ci]"

COPILOT.md

@@ -0,0 +1,14 @@
+# Copilot guidance for vibeauracle
+
+This file records the GitHub Copilot CLI behavioral guardrails for the project.
+
+## Core themes
+- Treat the repo as a modular monolith governed by `go.work`, with a Bubble Tea CLI entry point (`cmd/vibeaura`) and dedicated modules for brain, model, sys, context, MCP, daemon, vault, and community vibes.
+- Follow the Plan-Execute-Reflect loop, respect the Hexagonal layering, and keep explanations concise, system-aware, and tied back to README/ARCHITECTURE/FLOW when recommending changes.
+- Prefer `vibeaura` and Go tooling (`go test ./...`, `go work sync`) for operations, and mention testing plans when touching multiple modules.
+
+## Agent skill reminders
+- Pause before editing when work spans multiple modules; summarize cross-module impact first.
+- Request explicit approval for risky network, secret, or environment-impacting actions.
+- Highlight the architecture (system intimacy, TUI-first, brain loop) when describing how solutions align with the project.
+- Suggest module-scoped tests, citing specific commands, and link to docs (TODO.SDK.md, TODO.GH.md, docs/) when relevant.

FLOW.txt

@@ -0,0 +1 @@
+

README.md

@@ -4,6 +4,8 @@
   # vibe auracle
   **Distributed, System-Intimate AI Engineering Ecosystem**
 
+  <img src="./assets/shot.png" width="100%" alt="Vibe Auracle TUI Screenshot" />
+
   [![Stable](https://img.shields.io/badge/Stable-ec1de87-10B981?style=for-the-badge&logo=git&logoColor=white)](https://github.com/nathfavour/vibeauracle/tree/release)
   [![Beta](https://img.shields.io/badge/Beta-7ebb650-7C3AED?style=for-the-badge&logo=git&logoColor=white)](https://github.com/nathfavour/vibeauracle/tree/master)
   [![Go Version](https://img.shields.io/badge/Go-1.25+-00ADD8?style=for-the-badge&logo=go&logoColor=white)](https://go.dev)
@@ -15,6 +17,15 @@
 ## 🌌 The Vision
 **vibe auracle** unifies the terminal, the IDE, and the AI assistant into a single, keyboard-centric interface. It's built for engineers who value **system-intimacy**—where the AI isn't just a chatbot, but a co-pilot with deep access to your hardware, configuration, and environment.
 
+## 🤖 Modular Agentic Runtimes
+VibeAuracle is a multi-engine orchestrator. Choose the runtime that fits your task:
+
+- **🎨 Vibe Agent (`/agent /vibe`)**: Our artisan internal loop. Highly transparent, uses custom heuristic loop-detection, and optimized for system-intimate tasks.
+- **🚀 Copilot SDK Agent (`/agent /sdk`)**: Native GitHub Copilot SDK runtime. Delegates multi-step reasoning to the official GitHub agentic engine for deep tool-intimacy and secure, high-stakes engineering.
+- **👤 Custom Agent (`/agent /custom`)**: User-defined agent personas. Register specialized agents with custom system prompts and restricted toolsets to create focused experts for specific workflows.
+
+Use the `/agent` command in the TUI to toggle between engines on the fly.
+
 ## ⚡ Core Features
 - **Keyboard-Centric**: Designed for speed and fluid terminal workflows.
 - **Deep Integration**: Real-time awareness of system stats, files, and Git state.

TODO.GH.md

@@ -0,0 +1,23 @@
+# 🐙 GitHub CLI Leverage Roadmap (TODO.GH.md)
+
+Objective: Transform VibeAuracle into a "Claude Code" competitor by leveraging technical patterns and installed instances of the GitHub CLI.
+
+## 1. Technical Leverage: Infrastructure Resilience
+- [x] **Custom GitHub Transport**: Implement a specialized `http.RoundTripper` in `internal/model` to mirror `gh`'s `capiTransport`.
+    - Inject `Copilot-Integration-Id: copilot-4-cli` and `X-GitHub-Api-Version` headers.
+    - Add user-agent strings matching the official CLI for better API compatibility.
+- [x] **Robust Backoff Strategy**: Port the `cenkalti/backoff` patterns from `gh` into the `vibe-brain` execution loop to handle rate limits and transient network failures during long-running agent tasks.
+
+## 2. Contextual Intelligence: Project-Native Instructions
+- [x] **Agent Instruction Discovery**: Update the prompt system to automatically scan for and ingest `.github/agents/*.md` or `.github/vibeaura/*.md` files.
+    - This allows teams to define project-specific coding standards, architecture rules, and "vibes" that the agent respects by default.
+- [x] **Repository Identity**: Use `gh repo view --json` to populate the agent's initial context with accurate repository metadata (visibility, license, primary language, topics).
+
+## 3. Operational Leverage: Tooling Orchestration
+- [x] **Advanced PR Visibility**: Expand the `gh_pr_manage` tool to fetch PR diffs and conversation history via `gh pr diff` and `gh pr view --json comments`.
+    - This gives VibeAuracle the ability to "read" code reviews and fix requested changes autonomously.
+- [x] **Extension Awareness**: Add a tool to detect and potentially invoke installed `gh` extensions, allowing VibeAuracle to inherit custom organizational workflows.
+
+## 4. Hybrid Workflow: Remote Execution
+- [x] **Cloud Hand-off**: Implement `gh_remote_task` to trigger `gh agent-task create`.
+    - Allows the user to hand off heavy or long-running tasks from the local VibeAuracle session to GitHub's remote agent infrastructure.

TODO.SDK.md

@@ -0,0 +1,108 @@
+# 🤖 Copilot SDK Integration Roadmap (TODO.SDK.md)
+
+Objective: Integrate the official GitHub Copilot SDK to provide native, streaming LLM capabilities with proper session management and tool bridging.
+
+## Prerequisites
+- [x] Analyze `copilot-sdk/go` architecture and types
+- [x] Ensure `copilot` CLI is detectable/installable (graceful fallback if missing)
+
+---
+
+## Phase 1: Foundation (SDK Provider) ✅
+- [x] **Create `internal/copilot/` package**
+    - [x] `provider.go` - Implement `model.Provider` interface wrapping SDK
+    - [x] `bridge.go` - Bridge VibeAuracle `tooling.Tool` → Copilot SDK `Tool`
+    - [x] `events.go` - Handle streaming events (`assistant.message_delta`, etc.)
+    - [x] `mcp.go` - Bridge for Model Context Protocol servers
+
+- [x] **Add SDK dependency**
+    - [x] Add `github.com/github/copilot-sdk/go` to workspace (`internal/copilot-sdk-go`)
+    - [x] Configure local replace directive pointing to `./internal/copilot-sdk-go`
+
+- [x] **Graceful Detection**
+    - [x] Check if `copilot` CLI exists in PATH
+    - [x] Fall back to existing `langchaingo` OpenAI provider if missing
+    - [x] Log clear message about degraded mode
+
+---
+
+## Phase 2: Brain Integration ✅
+- [x] **Wire into Cognitive Loop**
+    - [x] Import copilot package in brain
+    - [x] Auto-select `copilot-sdk` when CLI available and gh auth present
+    - [x] Dual generation path (SDK or standard model)
+    - [x] Graceful shutdown via `Brain.Shutdown()`
+
+- [x] **System Message Customization**
+    - [x] Use `SystemMessageConfig.Mode = "append"` to inject VibeAuracle personality
+    - [x] Preserve SDK guardrails while adding our prompt layers
+
+---
+
+## Phase 3: Tool Bridge ✅
+- [x] **Export VibeAuracle Tools to Copilot**
+    - [x] Convert `tooling.ToolMetadata` → `copilot.Tool`
+    - [x] Auto-generate JSON schema from our `Parameters` field
+    - [x] Implement `ToolHandler` that routes to our `Tool.Execute()`
+    - [x] Register core tools with SDK on startup
+
+- [ ] **Bi-directional Tool Awareness**
+    - [ ] Allow Copilot's native tools (file, bash, etc.) to coexist
+    - [ ] Use `AvailableTools`/`ExcludedTools` for fine-grained control
+
+---
+
+## Phase 4: Streaming & Events ✅
+- [x] **Replace Blocking Generation**
+    - [x] Use `session.On()` event handler for callbacks
+    - [x] Emit `assistant.message_delta` to provider callbacks
+    - [x] Handle `session.idle` to know when response is complete
+
+- [x] **TUI Integration**
+    - [x] Add `streamDeltaMsg` and `streamDoneMsg` message types
+    - [x] Add streaming content state to model struct
+    - [x] Real-time viewport updates with cursor indicator
+
+---
+
+## Phase 5: BYOK (Bring Your Own Key) ✅
+- [x] **Custom Provider Passthrough**
+    - [x] Add `ProviderOptions` struct with BYOK fields
+    - [x] Check vault for `openai_api_key` and `anthropic_api_key`
+    - [x] Configure `sdk.ProviderConfig` with custom credentials
+    - [x] Allow `BaseURL` override for local models (Ollama via OpenAI-compat)
+
+---
+
+## Phase 6: MCP Integration ✅
+- [x] **Model Context Protocol**
+    - [x] Create `MCPBridge` in `internal/copilot/mcp.go`
+    - [x] Support local/stdio and remote HTTP/SSE servers
+    - [x] `RegisterMCPServers()` for SDK session config
+    - [x] Common MCP server presets (filesystem, github, memory)
+
+---
+
+## Implementation Status
+✅ Phase 1 Complete - Foundation SDK provider with streaming and tool bridge
+✅ Phase 2 Complete - Brain integration with dual-path generation
+✅ Phase 3 Complete - Core tools registered with Copilot SDK
+✅ Phase 4 Complete - Streaming events and TUI integration
+✅ Phase 5 Complete - BYOK support for OpenAI/Anthropic/Ollama
+✅ Phase 6 Complete - MCP server bridge
+
+## Build Status
+```
+✅ internal/copilot - builds successfully
+✅ internal/brain - builds successfully
+✅ internal/model - builds successfully  
+✅ cmd/vibeaura - builds successfully
+```
+
+## Files Created/Modified
+- `internal/copilot/provider.go` - Main SDK provider with BYOK
+- `internal/copilot/bridge.go` - VibeAuracle tool → SDK tool bridge
+- `internal/copilot/events.go` - Event routing for streaming
+- `internal/copilot/mcp.go` - MCP server integration
+- `internal/brain/brain.go` - Dual-path generation, tool registration
+- `cmd/vibeaura/chat.go` - TUI streaming support

TODO.md

@@ -0,0 +1,54 @@
+# VibeAuracle Roadmap & Competitive Edge
+
+Objective: To be the most system-intimate, high-performance, and secure AI engineering companion.
+
+## 🚀 Competitive Analysis: VibeAuracle vs. OpenCode
+
+| Feature | VibeAuracle (Edge) | OpenCode (Edge) | Learnings for VibeAuracle |
+|---------|-------------------|-----------------|---------------------------|
+| **Platform** | Go (Native, Fast, Single Binary) | Node.js (Web-Ready, Monorepo) | Maintain native performance while matching UI polish. |
+| **Auth** | Zero-Config (Inherits from `gh` CLI) | Built-in OAuth Device Flow | Add built-in OAuth as fallback if `gh` is missing. |
+| **SDK** | Official Copilot SDK (Stable) | Manual OpenAI-Compat Layer | Leverage SDK for stability but keep header control for betas. |
+| **Context** | Hardware/System Monitor (`sys.Monitor`) | Web/Console Integration | Deepen system intimacy (process tracking, memory usage). |
+| **Enterprise** | Secondary Focus | First-Class GHE Flow | Implement `/auth enterprise` for corporate users. |
+
+---
+
+## 🛠️ Immediate TODOs (Learned from OpenCode)
+
+- [ ] **Native OAuth Fallback**: Implement standalone Device Flow for Copilot auth (using `CLIENT_ID`). *Essential for users without `gh` CLI.*
+- [ ] **Enterprise Support**: Allow custom GitHub Enterprise domains in `/auth login`.
+- [ ] **Vision Support**: Add attachment handling for images in the TUI & SDK bridge.
+- [ ] **LSP Bridge**: Integrate language servers (e.g., `gopls`, `pyright`) to give the agent "Go to Definition" and "Find References" capabilities.
+- [ ] **Safe Shell Execution**: Parse shell commands (potentially using a Go tree-sitter binding) to detect dangerous operations before execution.
+- [ ] **Patch-based Editing**: Implement a `patch` tool for more efficient, token-saving file modifications.
+- [ ] **Dynamic Model Discovery**: Fetch model capabilities from a remote JSON (like `models.dev`) instead of hardcoding.
+- [ ] **Intent Header Control**: Ensure we set `Openai-Intent: conversation-edits` and `X-Initiator` in the Copilot bridge for parity with "Official" behavior.
+- [ ] **Cost & Token Tracking**: Monitor per-session token usage and estimated costs.
+- [ ] **Plugin/Skill Ecosystem**: Expand `/skill` to support external plugins similar to OpenCode's architecture.
+
+---
+
+## 🗺️ Long-Term Roadmap
+
+### 1. 🧠 Deep Project Context (RAG 2.0)
+- [ ] Local vector DB for project-wide semantic search.
+- [ ] Native AST parsing (using tree-sitter) for language-aware code navigation.
+- [ ] Contextual "Project Rules" injection (Auto-detecting `.cursorrules`, `.github/copilot-instructions.md`).
+
+### 2. ⚡ Autonomous Self-Healing
+- [ ] Loop that runs tests and fixes failures automatically.
+- [ ] Real-time error capture from system logs/background processes.
+
+### 3. 🛡️ Hardware-Agentic Security
+- [ ] Secure Enclave integration for secret management (beyond simple vault).
+- [ ] Sandboxed execution for risky shell commands.
+
+### 4. 🌐 MCP Bridge
+- [ ] Native support for connecting to external MCP servers (Model Context Protocol).
+- [ ] Expose VibeAuracle tools *as* an MCP server for other agents.
+
+### 5. 🎨 UI/UX Refinement
+- [ ] Streaming viewport rendering (Incremental TUI updates).
+- [ ] Keybinding customization engine.
+- [ ] Integrated file diff viewer in the TUI.