diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
new file mode 100644
index 0000000..5e135f7
--- /dev/null
+++ b/ARCHITECTURE.md
@@ -0,0 +1,160 @@
+# Architecture
+
+modAI is the native AI framework for MODX Revolution.
+
+It provides a common structure for AI capabilities, provider integrations, Manager workflows, agents and tools, and retrieval across MODX.
+
+## Architecture overview
+
+```text
+Manager UI (_build/js)
+    |
+    v
+API / executor (src/API)
+    |
+    |-- Prompt endpoints: Text, Vision, Image, Chat
+    |-- Chat history: load, store, pin, search, share
+    |-- Tools/Run, Context/Get, Download
+    |
+    v
+Capability layer
+    |
+    |-- Chat / text generation
+    |-- Image generation
+    |-- Vision analysis
+    |-- Agents, tools, function calling
+    |-- Context providers (RAG)
+    |
+    v
+Provider layer (src/Services)
+    |
+    |-- OpenAI
+    |-- Anthropic Claude
+    |-- Google Gemini
+    |-- OpenRouter
+    |-- Custom (OpenAI-compatible)
+    |
+    v
+External AI services
+```
+
+## Core idea
+
+modAI separates user-facing capabilities from provider-specific implementations.
+
+The Manager should not need to know which provider is generating text, analyzing an image, or returning a chat response. It calls a capability; the provider layer handles the provider-specific request and response details.
+
+Providers build a request description (an `AIResponse`) rather than calling the HTTP API directly — modAI's executor performs the actual request. This keeps the user experience consistent while allowing providers and models to change over time.
+
+## Codebase map
+
+All PHP lives under `core/components/modai/src/`. Front-end code lives under `_build/js/src/`.
+
+| Area | Location | Key types |
+| --- | --- | --- |
+| Provider layer | `src/Services/` | `AIService` (interface), `AIServiceFactory`, `Response/AIResponse`, `ApiKey` (trait), `Config/{CompletionsConfig,VisionConfig,ImageConfig}`, and the providers `OpenAI` / `Anthropic` / `Google` / `OpenRouter` / `CustomOpenAI` |
+| Request executor | `src/API/API.php` | Executes an `AIResponse`; honors `modai.api.*.execute_on_server` |
+| API endpoints | `src/API/` | `Prompt/{Text,Vision,Image,Chat,ChatTitle,AdditionalOptions}`, `Chat/*` (history), `Tools/Run`, `Context/Get`, `Download/*` |
+| Tools | `src/Tools/` | `ToolInterface` + built-in tools (resources, templates, chunks, categories) |
+| Context providers | `src/ContextProviders/` | `ContextProviderInterface`, built-in `Pinecone` |
+| Admin config forms | `src/Config/` | `ConfigBuilder`, `FieldBuilder` (shared by tools and context providers) |
+| Data models | `src/Model/` | `Agent`, `Tool`, `AgentTool`, `ContextProvider`, `AgentContextProvider`, `PromptLibraryCategory`, `PromptLibraryPrompt`, `Chat`, `Message` |
+| Manager UI | `_build/js/src/` | Chat modal, global button, media-browser integration, executor, provider response handlers |
+| Settings | `src/Settings.php`, `_build/gpm.yaml` | Namespaced `modai.*` system settings |
+
+## Extension points
+
+modAI is extended through MODX plugin events. A plugin returns one or more class names from the relevant event:
+
+- **`modAIOnServiceRegister`** — register a custom AI service (implements `AIService`).
+- **`modAIOnToolRegister`** — register a custom tool (implements `ToolInterface`).
+- **`modAIOnContextProviderRegister`** — register a custom context provider (implements `ContextProviderInterface`).
+
+This keeps provider-, tool-, and retrieval-specific code in its own Extra without modifying modAI core.
+
+## Major components
+
+### Manager UI
+
+The Manager UI handles user-facing interactions.
+
+Examples:
+
+- Chat panel (global button and media browser)
+- Prompt dialogs and field actions
+- Image generation and vision actions
+- Tool, agent, context provider, and prompt-library administration
+- Provider configuration screens
+
+The UI calls shared API endpoints instead of talking to provider APIs directly.
+
+### Capability layer
+
+The capability layer defines what modAI can do in provider-neutral terms.
+
+Current capabilities include:
+
+- Chat
+- Text generation
+- Image generation
+- Vision analysis
+- Function calling (tools)
+- Vector search and retrieval (context providers)
+
+### Provider layer
+
+The provider layer handles communication with external AI services. Provider implementations are responsible for:
+
+- Authentication
+- Request formatting
+- Response parsing
+- Model selection
+- Provider-specific errors and limits
+
+Provider-specific code stays out of Manager UI code.
+
+### Configuration layer
+
+Configuration handles provider credentials, model settings, feature toggles, and user choices. It should be clear enough for site builders and safe enough for production. Sensitive credentials are stored and handled according to MODX security expectations, and can optionally execute server-side (`modai.api.*.execute_on_server`) to avoid exposing keys to the browser.
+
+### Agents, tools, and prompts
+
+Agents bundle a model, a system prompt, model parameters, tools, and context providers into a reusable assistant. Tools are server-side capabilities an agent can call (function calling); context providers supply grounded, site-specific context. The Prompt Library stores reusable prompts. These are configured in the Manager and stored in the data models listed above.
+
+## Provider and capability relationship
+
+A provider may support some capabilities and not others. For example, Anthropic supports chat and vision but not image generation. The Manager exposes only the features available for the configured provider and model. See [PROVIDERS.md](PROVIDERS.md) for the capability matrix.
+
+## Shipped advanced capabilities
+
+These are implemented today and are areas of active improvement:
+
+### Function calling (tools)
+
+Agents can call server-side tools through the model. Tool access is explicit and scoped: each tool declares its parameters (as JSON Schema), a prompt, and a permission check, and a tool runs only when it is marked default or attached to the selected agent.
+
+### Vector search and RAG
+
+Context providers ground responses in site-specific content. The built-in Pinecone provider performs retrieval with reranking and can automatically index MODX resources, chunks, snippets, and templates as they change.
+
+## Future architecture areas
+
+### Site-aware assistants
+
+Future assistants may help users work with a specific MODX site — finding related content, suggesting internal links, drafting page updates, or explaining site structure. These should respect permissions and avoid changing content without user approval.
+
+### Workflow automation
+
+Automation should grow from explicit tools and user-approved actions — repetitive content cleanup, metadata generation, draft creation, content review, media description, and translation support. Automation should be inspectable and reversible where possible.
+
+## Contributor guidance
+
+When adding a feature, ask:
+
+1. Is this a capability, a provider implementation, or a Manager workflow?
+2. Can another provider support this later?
+3. Does this belong in shared code or provider-specific code?
+4. Does the user remain in control?
+5. Does this fit the design principles?
+
+Read [DESIGN_PRINCIPLES.md](DESIGN_PRINCIPLES.md) before making architecture changes.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..a2cff2e
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,156 @@
+# Contributing to modAI
+
+Thank you for your interest in contributing to modAI.
+
+modAI is the native AI framework for MODX Revolution. The goal is to build a shared foundation for AI-powered workflows throughout the MODX ecosystem.
+
+Contributions of all sizes are welcome.
+
+Useful contributions include:
+
+- Bug fixes
+- Documentation improvements
+- Provider integrations
+- Manager UI improvements
+- Testing and QA
+- Performance work
+- Vision and image workflows
+- Tools and agents (function calling)
+- Vector search and retrieval
+
+## Before you start
+
+Please review:
+
+- Open issues
+- Existing pull requests
+- Project discussions
+- [DESIGN_PRINCIPLES.md](DESIGN_PRINCIPLES.md)
+- [ARCHITECTURE.md](ARCHITECTURE.md)
+
+For larger changes, open an issue or discussion before writing a full implementation.
+
+That helps avoid duplicated work and keeps the change aligned with the project direction.
+
+## Development workflow
+
+1. Fork the repository.
+2. Create a feature branch.
+3. Make your changes.
+4. Add or update tests when practical.
+5. Update documentation when behavior changes.
+6. Submit a pull request.
+
+Use clear branch names.
+
+Examples:
+
+```text
+fix/provider-error-handling
+feature/gemini-vision-support
+docs/provider-setup
+```
+
+## Local setup and tooling
+
+Install dependencies:
+
+```bash
+composer install
+npm install
+```
+
+Common commands:
+
+```bash
+npm run build      # build the Manager assets (esbuild)
+npm run dev        # rebuild on change while developing
+npm run lint       # lint JavaScript/TypeScript with ESLint
+npm run docs:dev   # run the documentation site locally
+```
+
+PHP code follows the coding standard defined in `phpcs.xml` (PHP CodeSniffer). The project targets **PHP 8.2+** and **MODX Revolution 3.x**.
+
+The user-facing documentation site lives in `_build/docs` (Docusaurus) and renders the Markdown in the top-level `docs/` directory.
+
+## Pull requests
+
+A good pull request should include:
+
+- A clear description of the problem
+- A clear description of the change
+- Screenshots for UI changes
+- Test notes or manual verification steps
+- Links to related issues or discussions
+
+Keep pull requests focused when possible.
+
+A small, clear PR is easier to review than a large PR that mixes unrelated changes.
+
+## Coding standards
+
+Follow existing project patterns.
+
+Contributions should:
+
+- Avoid unnecessary dependencies
+- Keep provider-specific logic in provider code
+- Keep Manager UI code provider-neutral where practical
+- Preserve backwards compatibility when practical
+- Handle provider errors clearly
+- Avoid exposing credentials or sensitive data
+
+## Documentation
+
+Update documentation when a change affects:
+
+- Installation
+- Configuration
+- Supported providers
+- Supported capabilities
+- Developer APIs
+- Manager behavior
+- User-facing workflows
+
+Documentation should be written for experienced MODX developers.
+
+Use plain language. Avoid hype.
+
+## Provider changes
+
+Provider contributions should update [PROVIDERS.md](PROVIDERS.md).
+
+Include:
+
+- Supported capabilities
+- Required credentials
+- Model requirements
+- Known limits
+- Manual test notes
+
+## UI changes
+
+UI changes should include screenshots or screen recordings when practical.
+
+Please check:
+
+- Empty states
+- Error states
+- Loading states
+- Long responses
+- Small screens
+- Permission-related behavior
+
+## Security
+
+Do not include API keys, secrets, access tokens, or real customer data in commits, issues, screenshots, or pull requests.
+
+If you believe you have found a security issue, do not open a public issue. Contact the MODX team through the appropriate security channel.
+
+## Questions
+
+Use GitHub Discussions for architecture questions, provider ideas, and larger proposals.
+
+Use GitHub Issues for bugs and clearly scoped tasks.
+
+We appreciate your help building modAI.
diff --git a/DESIGN_PRINCIPLES.md b/DESIGN_PRINCIPLES.md
new file mode 100644
index 0000000..08a837d
--- /dev/null
+++ b/DESIGN_PRINCIPLES.md
@@ -0,0 +1,80 @@
+# Design principles
+
+These principles guide product and architecture decisions for modAI.
+
+## Native MODX experience
+
+AI features should feel like part of MODX.
+
+Users should be able to use AI where they already work: resources, fields, media, SEO tools, and Manager workflows.
+
+Context switching should be rare. Configuration should be clear. The user experience should respect how MODX developers and editors already build sites.
+
+## Provider agnostic
+
+modAI should avoid hard dependence on any single AI vendor.
+
+Providers change quickly. Models change even faster. Users have different budgets, policies, and data requirements.
+
+The architecture should allow new providers and models to be added without rewriting the Manager experience.
+
+## Capability driven
+
+modAI should be organized around capabilities.
+
+Examples:
+
+- Chat
+- Text generation
+- Image generation
+- Vision analysis
+- Embeddings
+- Vector search
+- Function calling
+
+Providers implement capabilities. Capabilities shape the user experience.
+
+## Built for extension
+
+Developers should be able to add providers, tools, capabilities, and integrations through clear extension points.
+
+Special cases should be rare.
+
+Core code should stay focused on shared behavior. Provider-specific code should live with the provider.
+
+## Practical AI
+
+modAI exists to help people get real work done.
+
+Good features should reduce repetitive work, improve content quality, support accessibility, or make MODX workflows easier to manage.
+
+AI novelty is not enough.
+
+## Context matters
+
+AI gets more useful when it has access to the right context.
+
+Future work should help modAI understand the site it is assisting with. That may include:
+
+- Resource discovery
+- Site knowledge
+- Embeddings
+- Vector databases
+- Retrieval-augmented generation
+- Function calling
+
+The user should stay in control of what context is available and how it is used.
+
+## Progressive adoption
+
+Users should be able to adopt modAI one workflow at a time.
+
+A site may start with image alt text, then add SEO assistance, then content generation, then deeper assistant workflows.
+
+The architecture should support that path without forcing a full rewrite of existing MODX processes.
+
+## Shared foundation
+
+modAI should provide common AI building blocks for the MODX ecosystem.
+
+The long-term goal is to reduce duplicated work across future Extras, integrations, and Manager features.
diff --git a/PROVIDERS.md b/PROVIDERS.md
new file mode 100644
index 0000000..af7881b
--- /dev/null
+++ b/PROVIDERS.md
@@ -0,0 +1,138 @@
+# Providers
+
+modAI supports multiple AI providers through a shared provider layer.
+
+The provider layer allows the Manager to use AI capabilities without hard-coding provider-specific API behavior into user-facing workflows.
+
+## Supported providers
+
+Current provider support includes:
+
+- OpenAI
+- Anthropic Claude
+- Google Gemini
+- OpenRouter
+- Custom / OpenAI-compatible endpoints
+
+Provider support may vary by capability and model.
+
+## Capability matrix
+
+| Capability | OpenAI | Anthropic Claude | Google Gemini | OpenRouter | Custom (OpenAI-compatible) |
+| --- | --- | --- | --- | --- | --- |
+| Chat / text generation | Yes | Yes | Yes | Yes | Yes |
+| Streaming responses | Yes | Yes | Yes | Yes | Yes |
+| Vision analysis | Yes | Yes | Yes | Yes | Yes |
+| Image generation | Yes | No | Yes | Yes | Yes |
+| Function calling (tools) | Yes | Yes | Yes | Yes¹ | Yes¹ |
+| Text to audio (TTS) | Planned | — | Planned | Planned¹ | Planned¹ |
+| Voice input (STT) | Planned | — | Planned | Planned¹ | Planned¹ |
+
+**Legend:** Yes = supported today · Planned = on the [roadmap](ROADMAP.md), not yet implemented · — = not offered by the provider.
+
+¹ Model-dependent. OpenRouter and custom endpoints route to many underlying models; vision, image, audio, and tool support depend on the selected model.
+
+This matrix should be updated as provider support changes.
+
+> **Embeddings, vector search, and RAG** are provided through [Context Providers](https://modxcms.github.io/modAI/Admin/Context-Providers), not through a provider-level embeddings capability. The built-in Pinecone provider relies on the vector database's own integrated embeddings rather than computing embeddings through an AI provider.
+
+## How providers work
+
+A provider is a PHP class implementing `\modAI\Services\AIService`. The key pieces:
+
+- **`getServiceName()`** returns a short identifier (e.g. `openai`) used to look up the `modai.api.{service}.key` setting.
+- **`isMyModel(string $model)`** claims a model prefix (e.g. `openai/`, `anthropic/`, `custom/`). `AIServiceFactory` resolves a `service/model` string by asking each registered service whether it owns that prefix.
+- **`getCompletions()` / `getVision()` / `generateImage()`** build and return an `\modAI\Services\Response\AIResponse` describing the request (URL, headers, body, parser, streaming). modAI executes the request — the service does not call the HTTP API itself.
+
+The five built-in services live in `core/components/modai/src/Services/`.
+
+## Provider responsibilities
+
+Each provider implementation should handle:
+
+- Authentication (the `ApiKey` trait reads `modai.api.{service}.key`)
+- Request formatting
+- Response parsing (via the appropriate `AIResponse` parser)
+- Model selection (the prefix claimed by `isMyModel()`)
+- Capability support (text, vision, image)
+- Provider-specific limits
+- Provider-specific error handling
+
+Provider-specific behavior should be documented.
+
+## Adding a provider
+
+A new provider should:
+
+1. Implement `\modAI\Services\AIService` (use an existing service such as `OpenRouter` as a reference).
+2. Claim a unique model prefix in `isMyModel()` that does not collide with the built-ins (`openai/`, `google/`, `anthropic/`, `openrouter/`, `custom/`).
+3. Register the class by returning it from a plugin on the `modAIOnServiceRegister` event.
+4. Add configuration fields for credentials and model settings.
+5. Document supported models and known limits.
+6. Include basic tests or manual test steps.
+7. Avoid changes to Manager UI unless the provider needs a new shared capability.
+
+See the [Supported Services](https://modxcms.github.io/modAI/Configuration/Supported-Services) docs for the contributor-facing details and a minimal service skeleton.
+
+## Adding a capability to an existing provider
+
+When adding a capability to an existing provider:
+
+1. Confirm that the provider supports the capability in the target models.
+2. Add support inside the provider implementation.
+3. Update the capability matrix.
+4. Add configuration notes if the feature requires a specific model or setting.
+5. Add tests or documented manual test steps.
+
+## Provider-specific behavior
+
+Provider APIs differ.
+
+Common differences include:
+
+- Model names
+- Token limits
+- File and image formats
+- Streaming formats
+- Rate limits
+- Safety filtering
+- Error payloads
+- Tool calling syntax
+- Pricing models
+
+Keep those differences inside the provider layer when possible.
+
+## Credentials
+
+Provider credentials should be handled with care.
+
+Do not commit API keys or test credentials.
+
+Documentation and examples should use placeholders.
+
+Example:
+
+```text
+YOUR_PROVIDER_API_KEY
+```
+
+## Local testing
+
+When testing provider changes:
+
+1. Test with valid credentials.
+2. Test missing credentials.
+3. Test invalid credentials.
+4. Test provider rate limit or error responses where practical.
+5. Test unsupported model or capability combinations.
+6. Confirm the Manager shows a useful error.
+
+## Documentation updates
+
+Provider changes should update this file when they change:
+
+- Supported providers
+- Supported capabilities
+- Configuration requirements
+- Model requirements
+- Known limitations
diff --git a/README.md b/README.md
index 91cf079..90c27f5 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,209 @@
-# 🚀 modAI for MODX Revolution 3.0+
+# modAI
 
-A **generative AI Extra** for MODX Revolution that helps you **create content faster** and **optimize SEO effortlessly**.
+The native AI framework for MODX Revolution.
 
-## ✨ What modAI Can Do
-📝 **Generate Content** – Quickly craft page content, blog posts, and marketing copy.  
-🔍 **SEO Optimization** – Improve **meta titles, descriptions, and summaries** for better ranking.  
-🖼️ **Image Assistance** – Create and enhance images, **generate meaninful alt tags**, and improve accessibility.  
-💬 **Chat-Based Prompts** – Use **zero-shot or iterative chat** to refine your outputs dynamically.  
+modAI brings AI tools into the MODX Manager for content generation, image generation, image analysis, chat, agents and tools, provider integrations, and AI-assisted workflows across the MODX ecosystem.
 
-## ⚡ Powerful Features
-🌎 **Multi-Vendor Support** – Choose from **different AI providers** for flexibility.  
-🧠 **Multiple Model Types** – Use **text models, image models, vision models, and hybrid AI** for various tasks.  
-🔄 **Iterative Refinements** – Fine-tune AI-generated content through **chat-based enhancements**.  
-🔗 **Seamless Integration** – Attach to **any text or image field** in MODX and works with **SEO Suite** and **Image+**.  
+The project is built by the MODX team and is intended to grow with MODX itself.
 
-Perfect for **MODX users, content creators, and SEO specialists** who want to streamline their workflow! 🚀
+## Why modAI exists
 
-_For additional information, read the [documentation](https://modxcms.github.io/modAI/), view the [latest announcment](https://modx.com/blog/generative-ai-content-for-modx-revolution-with-modai), or ask a question in an issue here._
+Many CMS AI integrations wrap a single API and expose a few prompt buttons.
+
+modAI takes a different path. It gives MODX a shared AI foundation that supports multiple providers, multiple model types, agents and tools, retrieval, and deeper Manager workflows.
+
+The goal is practical: help MODX users create, refine, review, and manage content with AI assistance inside the tools they already use.
+
+## Project philosophy
+
+modAI is more than an AI content generator.
+
+The long-term goal is a shared AI layer for the MODX ecosystem. That includes content generation, image workflows, contextual assistance, automation, and future AI-powered experiences built on a common architecture.
+
+Read [DESIGN_PRINCIPLES.md](DESIGN_PRINCIPLES.md) before proposing large changes.
+
+## Project status
+
+modAI is actively developed and maintained.
+
+Current capabilities include:
+
+- AI chat and assistant workflows
+- Text generation
+- Image generation
+- Vision analysis
+- Multi-provider support
+- Streaming responses
+- Agents, tools, and function calling
+- Vector search and RAG via Context Providers
+
+Community feedback, testing, bug reports, and contributions are welcome.
+
+## Features
+
+### AI chat
+
+Use AI models directly within the MODX Manager through a streaming chat interface, with persistent history and optional shared chats.
+
+### Text generation
+
+Generate, rewrite, summarize, and improve content without leaving MODX.
+
+### Image generation
+
+Create original images with supported AI providers and add them to your content workflow, including directly from the Media browser.
+
+### Vision analysis
+
+Analyze images and generate alt text, captions, summaries, and descriptions.
+
+### SEO assistance
+
+Generate titles, meta descriptions, summaries, and other SEO-focused content.
+
+### Agents, tools, and function calling
+
+Configure agents that bundle a model, a system prompt, tools, and context providers. modAI ships with built-in tools for working with MODX resources, templates, chunks, and categories, and you can register your own.
+
+### Vector search and RAG
+
+Ground responses in your own content through Context Providers. A built-in Pinecone provider supports retrieval and can automatically index MODX content.
+
+### Multi-provider architecture
+
+Use the AI models that fit your workflow, requirements, and budget.
+
+Supported providers currently include:
+
+- OpenAI
+- Anthropic Claude
+- Google Gemini
+- OpenRouter
+- Custom / OpenAI-compatible endpoints
+
+More providers can be added through the provider layer.
+
+### Works with other MODX Extras
+
+modAI complements tools you may already use:
+
+- **[image+](https://extras.modx.com/package/imageplustvinput)** — generate and manage images for image+ TVs, such as hero images and Open Graph previews.
+- **[SEO Suite](https://extras.modx.com/package/seosuite)** — generate the meta titles, descriptions, and summaries SEO Suite manages.
+
+## Documentation
+
+User and configuration documentation lives on the documentation site:
+
+- **Docs site:** https://modxcms.github.io/modAI/
+- **Extras package:** https://extras.modx.com/package/modai
+
+Developer and contributor documentation:
+
+| Document | Purpose |
+| --- | --- |
+| [DESIGN_PRINCIPLES.md](DESIGN_PRINCIPLES.md) | Product and architecture principles |
+| [ARCHITECTURE.md](ARCHITECTURE.md) | System architecture and component design |
+| [PROVIDERS.md](PROVIDERS.md) | Provider support and provider integration guidance |
+| [ROADMAP.md](ROADMAP.md) | Current priorities and future direction |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Contribution guidelines and development workflow |
+
+If you want to contribute, start with the design principles and architecture docs.
+
+## Requirements
+
+- MODX Revolution 3.x
+- PHP 8.2+
+- Credentials for at least one supported AI provider
+
+Provider-specific features may have their own requirements.
+
+## Installation
+
+Install modAI through the MODX Extras installer ([package page](https://extras.modx.com/package/modai)). The installer prompts you for provider API keys as part of setup.
+
+### Getting provider API keys
+
+You need **at least one** provider key to use modAI. The installer prompts you for keys during setup, and you can add or change them later in the system settings (`modai.api.{service}.key`).
+
+Create a key with the provider(s) you want to use:
+
+| Provider | Get a key | Notes |
+| --- | --- | --- |
+| **OpenAI** (ChatGPT, image generation) | [platform.openai.com/api-keys](https://platform.openai.com/api-keys) | Requires a billing method / prepaid credits. The API is billed separately from any ChatGPT subscription. |
+| **Anthropic** (Claude) | [platform.claude.com/settings/keys](https://platform.claude.com/settings/keys) | Created in the Claude Console; requires account credits/billing. Runs server-side only — enable `modai.api.anthropic.execute_on_server`. |
+| **Google Gemini** | [aistudio.google.com/apikey](https://aistudio.google.com/apikey) | Created in Google AI Studio; free tier available with limits (higher usage and image generation may require billing). |
+| **OpenRouter** (multi-vendor gateway) | [openrouter.ai/settings/keys](https://openrouter.ai/settings/keys) | One key for many models and providers; requires account credits. |
+
+Custom / OpenAI-compatible endpoints are configured directly in the system settings. Treat API keys like passwords — never commit or share them.
+
+See [PROVIDERS.md](PROVIDERS.md) for provider setup notes.
+
+### After installation
+
+1. Enable the features you want to use.
+2. Start using AI features inside the MODX Manager.
+
+## Development setup
+
+Clone the repository:
+
+```bash
+git clone https://github.com/modxcms/modAI.git
+cd modAI
+```
+
+Install dependencies:
+
+```bash
+composer install
+npm install
+```
+
+Build assets:
+
+```bash
+npm run build
+```
+
+Start development mode (watch/rebuild):
+
+```bash
+npm run dev
+```
+
+modAI runs inside the MODX Manager, so building the assets alone does not produce a running instance. To exercise your changes you need a local MODX Revolution 3.x site with modAI set up for development.
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for implementation notes and [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow.
+
+## Contributing
+
+We welcome contributions of all sizes.
+
+Useful areas include:
+
+- Provider integrations
+- Manager UI improvements
+- Documentation
+- Testing and QA
+- Performance work
+- Vision workflows
+- Tools and agents
+- Vector search and retrieval
+
+Before starting a larger change, review:
+
+- [DESIGN_PRINCIPLES.md](DESIGN_PRINCIPLES.md)
+- [ARCHITECTURE.md](ARCHITECTURE.md)
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+
+For significant changes, open an issue or discussion first.
+
+## Community
+
+- Report bugs through GitHub Issues
+- Discuss ideas through GitHub Discussions
+- Share feedback with the MODX community
+
+## License
+
+modAI is open source software released under the terms of the included [license](LICENSE.md) (GNU AGPL v3.0).
diff --git a/ROADMAP.md b/ROADMAP.md
new file mode 100644
index 0000000..43b0b9d
--- /dev/null
+++ b/ROADMAP.md
@@ -0,0 +1,105 @@
+# Roadmap
+
+This roadmap describes current areas of work and likely future direction.
+
+Many capabilities already ship today — including chat, text and image generation, vision, agents and tools (function calling), and retrieval via context providers. This roadmap focuses on deepening and expanding them.
+
+Priorities may change as AI models, provider APIs, and MODX needs change.
+
+## Foundation
+
+Keep the core stable and easier to build on.
+
+Examples:
+
+- Provider improvements
+- Better streaming support
+- Clearer developer APIs
+- Better configuration handling
+- Better test coverage
+- Clearer error handling
+
+## Context-aware AI
+
+Help modAI understand the site it is assisting with. Initial retrieval support ships today via context providers (including the built-in Pinecone provider); the goal is to broaden it.
+
+Examples:
+
+- More context provider integrations
+- Improved embeddings and indexing
+- Retrieval-augmented generation improvements
+- Site-aware assistants
+- Resource discovery
+- Content relationship discovery
+
+## Actions and automation
+
+Allow AI to help perform approved work inside MODX. Function calling through agents and tools ships today; the goal is to expand the available actions and safeguards.
+
+Examples:
+
+- More built-in tools
+- Resource draft creation
+- Content update suggestions
+- Metadata generation
+- Approved external service integrations
+
+AI-generated changes should be reviewable before they are applied.
+
+## Content and media
+
+Improve creative and editorial workflows.
+
+A near-term focus is an **audio capability**, which improves accessibility and enables hands-free workflows:
+
+- Text to audio — for example, reading an article aloud
+- Voice input through speech to text — for example, dictating a prompt
+
+Examples:
+
+- Audio: text to audio and voice input (speech to text)
+- Image generation improvements
+- Vision analysis
+- Alt text generation
+- Caption generation
+- Content refinement
+- SEO metadata assistance
+- Rich media workflows
+
+## Provider ecosystem
+
+Make it easier to add and maintain providers.
+
+Examples:
+
+- Shared provider interfaces
+- Capability registration
+- Provider test fixtures
+- Provider documentation
+- Community provider integrations
+
+## Manager experience
+
+Improve how AI appears inside MODX.
+
+Examples:
+
+- Better field-level actions
+- Better chat workflows
+- Clear model selection
+- Clear error messages
+- Better permission handling
+- More useful defaults
+
+## Longer-term direction
+
+Potential long-term areas include:
+
+- Skills: reusable, packaged units that bundle a prompt, tools, context, and instructions — an evolution of agents and the prompt library
+- Sharing and installing skills across sites and the MODX community
+- Site-aware assistants
+- Agent-style workflows
+- Retrieval tools
+- Workflow automation
+- Shared AI APIs for future Extras
+- Deeper Manager integrations
diff --git a/_build/setup.options.php b/_build/setup.options.php
index 8a1e5c8..130da12 100644
--- a/_build/setup.options.php
+++ b/_build/setup.options.php
@@ -130,7 +130,7 @@
 <div class="modai-setup">
 <h2>API Keys</h2>
 <p>Add the API keys for the services you wish to use.</p>
-<p>You can add these later in the system settings, but you will need at least one to use modAI. Click the vendor labels below to open instructions for each one. <a href="https://modxcms.github.io/modAI/supported-services.html" target="_blank">Learn more about API keys in modAI</a>.</p>
+<p>You can add these later in the system settings, but you will need at least one to use modAI. Click the vendor labels below to open instructions for each one. <a href="https://modxcms.github.io/modAI/Configuration/Supported-Services" target="_blank">Learn more about API keys in modAI</a>.</p>
 <div class="modai-setup-fields">';
 
 foreach ($settings as $setting) {