diff --git a/docs/wiki.md b/docs/wiki.md
new file mode 100644
index 0000000..9d865a5
--- /dev/null
+++ b/docs/wiki.md
@@ -0,0 +1,34 @@
+# Project Overview
+
+**PapiAI Core** is a framework-agnostic, type-safe PHP (8.2+) library designed for building robust AI agents. It serves as a foundational layer that abstracts the complexities of interacting with various LLM providers while offering powerful features like:
+
+*   **Multi-Provider Support:** Seamless integration with Anthropic (Claude) and Google (Gemini), with more on the way.
+*   **Tool Calling:** flexible definition of tools using closures or class-based attributes.
+*   **Structured Output:** Strong validation of LLM responses using a Zod-like schema builder.
+*   **Event-Driven Streaming:** First-class support for streaming responses and events.
+*   **Observability:** Built-in hooks for logging, metrics, and error handling.
+
+It is designed to be lightweight and easily embeddable into any PHP project, whether it's a standalone script, a Laravel application, or a Symfony service.
+
+# Roadmap
+
+## Phase 1: Foundation (Completed)
+*   [x] Core Agent and Provider architecture
+*   [x] Anthropic and Google provider implementations
+*   [x] Tool calling and execution logic
+*   [x] Structured output parsing and validation
+*   [x] Basic event-driven streaming
+
+## Phase 2: Capabilities & Resilience (Short-term)
+*   [ ] **OpenAI Integration:** Add support for GPT-4 and other OpenAI models.
+*   [ ] **Memory Management:** Implement flexible memory stores (Redis, Database) to maintain conversation context.
+*   [ ] **Resilience:** Add built-in retry mechanisms, rate-limiting handling, and circuit breakers.
+
+## Phase 3: Expansion (Mid-term)
+*   [ ] **Middleware Pipeline:** Allow intercepting and modifying requests/responses globally.
+*   [ ] **RAG Integration:** Native support for Vector Stores to enable Retrieval-Augmented Generation.
+*   [ ] **CLI Tooling:** A dedicated CLI for scaffolding agents and testing prompts.
+
+## Phase 4: Advanced Orchestration (Long-term)
+*   [ ] **Multi-Agent Systems:** Patterns and tools for coordinating multiple agents working together.
+*   [ ] **Async Runtime:** Better support for asynchronous execution environments (e.g., Swoole, Amphp).
diff --git a/papi-core/docs/WIKI.md b/papi-core/docs/WIKI.md
new file mode 100644
index 0000000..4d1927b
--- /dev/null
+++ b/papi-core/docs/WIKI.md
@@ -0,0 +1,63 @@
+# PapiAI Project Wiki
+
+## 1. Project Overview
+
+**PapiAI** is a modern, framework-agnostic PHP library designed for building robust AI agents. It provides a unified interface to interact with various Large Language Models (LLMs) like Anthropic Claude and Google Gemini, making it easy to integrate AI capabilities into any PHP application (Laravel, Symfony, or standalone).
+
+### Key Philosophy
+- **Simplicity**: Clean, intuitive API for creating agents.
+- **Type Safety**: Built on PHP 8.2+ with strict typing.
+- **Modularity**: Core logic is separated from specific provider implementations.
+
+## 2. Architecture
+
+The project is structured around a few key abstractions:
+
+### Core Components (`papi-ai/papi-core`)
+- **Agent**: The main entry point. It orchestrates interactions between the user, the LLM provider, and available tools.
+- **ProviderInterface**: The contract that all LLM providers must implement. It standardizes:
+  - `chat()`: Standard request/response.
+  - `stream()`: Real-time streaming responses.
+  - Capabilities: `supportsTool()`, `supportsVision()`, `supportsStructuredOutput()`.
+- **Tool**: encapsulations of functions or class methods that the AI can "call" to perform actions (e.g., fetching weather, querying a database).
+- **Schema**: A fluent builder (Zod-like) for defining structured output requirements, ensuring the AI returns data in a predictable format.
+
+### Providers
+Specific implementations are handled in separate packages to keep the core lightweight:
+- `papi-ai/anthropic`: Adapter for Anthropic's Claude models.
+- `papi-ai/google`: Adapter for Google's Gemini models.
+- `papi-ai/openai`: (Planned/In-progress) Adapter for OpenAI.
+
+## 3. Getting Started
+
+### Installation
+Install the core package and your desired provider:
+
+```bash
+composer require papi-ai/core
+composer require papi-ai/anthropic
+```
+
+### Basic Usage
+Here is how to create a simple agent using Claude:
+
+```php
+use PapiAI\Core\Agent;
+use PapiAI\Anthropic\AnthropicProvider;
+
+$agent = new Agent(
+    provider: new AnthropicProvider(apiKey: $_ENV['ANTHROPIC_API_KEY']),
+    model: 'claude-3-5-sonnet-20240620',
+    instructions: 'You are a helpful coding assistant.'
+);
+
+$response = $agent->run('Refactor this class for me...');
+echo $response->text;
+```
+
+## 4. Advanced Features
+
+- **Tool Calling**: Define PHP functions or class methods as tools. The Agent handles the LLM's request to execute them.
+- **Structured Output**: Enforce JSON schemas on responses for reliable data extraction.
+- **Streaming**: Subscribe to event streams for real-time UI updates.
+- **Observability**: Hooks available for logging and monitoring agent performance.