From 287a9367ac3d9bf0e17e0f728077a8f4d06cff3e Mon Sep 17 00:00:00 2001
From: Ryan Thrash <ryan@thrash.me>
Date: Fri, 5 Jun 2026 18:10:51 -0500
Subject: [PATCH 1/7] docs: add contributor & developer documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds repo-level docs aimed at developers and contributors, and expands
the root README. Content was reconciled against the codebase so the
docs match what actually ships.

- README.md: rewrite as a developer-facing overview; list all five
  providers (OpenAI, Anthropic, Google, OpenRouter, Custom), present
  agents/tools/function-calling and RAG as shipped capabilities, pin
  PHP 8.2+, and link the docs site and Extras package page.
- ARCHITECTURE.md (new): system design grounded in the real codebase —
  AIService/AIServiceFactory/AIResponse, ToolInterface,
  ContextProviderInterface, ConfigBuilder, the API executor, data
  models, and the modAIOnServiceRegister/ToolRegister/ContextProviderRegister
  extension events. Function calling and RAG are documented as shipped.
- PROVIDERS.md (new): accurate five-provider capability matrix
  (corrected image-generation and function-calling rows), how the
  provider layer works, and how to add a provider via AIService +
  modAIOnServiceRegister. Clarifies RAG is via Context Providers, not a
  provider embeddings capability.
- ROADMAP.md (new): reframed so already-shipped capabilities read as
  "expand" rather than "introduce".
- CONTRIBUTING.md (new): workflow plus a real local-setup/tooling
  section (build/dev/lint, phpcs.xml, docs:dev).
- DESIGN_PRINCIPLES.md (new): product/architecture principles.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 ARCHITECTURE.md      | 160 +++++++++++++++++++++++++++++++++++
 CONTRIBUTING.md      | 156 ++++++++++++++++++++++++++++++++++
 DESIGN_PRINCIPLES.md |  80 ++++++++++++++++++
 PROVIDERS.md         | 134 +++++++++++++++++++++++++++++
 README.md            | 195 +++++++++++++++++++++++++++++++++++++++----
 ROADMAP.md           |  97 +++++++++++++++++++++
 6 files changed, 808 insertions(+), 14 deletions(-)
 create mode 100644 ARCHITECTURE.md
 create mode 100644 CONTRIBUTING.md
 create mode 100644 DESIGN_PRINCIPLES.md
 create mode 100644 PROVIDERS.md
 create mode 100644 ROADMAP.md

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..cbf726b
--- /dev/null
+++ b/PROVIDERS.md
@@ -0,0 +1,134 @@
+# 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¹ |
+
+¹ Model-dependent. OpenRouter and custom endpoints route to many underlying models; vision, image, 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..016d77c 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,186 @@
-# 🚀 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 used in production.
+
+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.
+
+## 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)).
+
+After installation:
+
+1. Configure at least one AI provider.
+2. Enable the features you want to use.
+3. Start using AI features inside the MODX Manager.
+
+See [PROVIDERS.md](PROVIDERS.md) for provider setup notes.
+
+## 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
+```
+
+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..8d553fa
--- /dev/null
+++ b/ROADMAP.md
@@ -0,0 +1,97 @@
+# 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.
+
+Examples:
+
+- 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:
+
+- Site-aware assistants
+- Agent-style workflows
+- Retrieval tools
+- Workflow automation
+- Shared AI APIs for future Extras
+- Deeper Manager integrations

From 6943308de8b3e8b7ed20044819749dde989dbf3b Mon Sep 17 00:00:00 2001
From: Ryan Thrash <ryan@thrash.me>
Date: Fri, 5 Jun 2026 18:15:55 -0500
Subject: [PATCH 2/7] docs: add audio capability and skills to the roadmap
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Content and media (near-term): add an audio capability — text to audio
  (read an article aloud) and voice input via speech to text — framed
  around accessibility and hands-free workflows.
- Longer-term direction: add skills — reusable, packaged units that
  bundle a prompt, tools, context, and instructions (an evolution of
  agents and the prompt library), plus sharing/installing skills across
  sites and the MODX community.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 ROADMAP.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/ROADMAP.md b/ROADMAP.md
index 8d553fa..43b0b9d 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -50,8 +50,14 @@ AI-generated changes should be reviewable before they are applied.
 
 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
@@ -89,6 +95,8 @@ Examples:
 
 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

From 5ae81fb702f2893ad9c8e0dea28cc42f0253090d Mon Sep 17 00:00:00 2001
From: Ryan Thrash <ryan@thrash.me>
Date: Fri, 5 Jun 2026 18:23:06 -0500
Subject: [PATCH 3/7] docs: add planned audio capability to the provider matrix
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Foreshadow the near-term audio capability in PROVIDERS.md with Text to
audio (TTS) and Voice input (STT) rows marked Planned, and add a legend
(Yes / Planned / —). Anthropic is marked — (no audio API); OpenRouter
and custom endpoints are model/endpoint-dependent.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 PROVIDERS.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/PROVIDERS.md b/PROVIDERS.md
index cbf726b..af7881b 100644
--- a/PROVIDERS.md
+++ b/PROVIDERS.md
@@ -25,8 +25,12 @@ Provider support may vary by capability and model.
 | 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¹ |
 
-¹ Model-dependent. OpenRouter and custom endpoints route to many underlying models; vision, image, and tool support depend on the selected model.
+**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.
 

From 1c9178df92a648d7018d728c91542810eb778021 Mon Sep 17 00:00:00 2001
From: Ryan Thrash <ryan@thrash.me>
Date: Fri, 5 Jun 2026 18:55:28 -0500
Subject: [PATCH 4/7] docs: add provider API key sources; fix installer docs
 link

- README: add a "Getting provider API keys" subsection to Installation
  with where-to-get-a-key links for OpenAI, Anthropic, Google Gemini,
  and OpenRouter (matching the keys the installer prompts for), plus
  billing/free-tier notes.
- setup.options.php: fix the installer's "Learn more" link, which
  pointed at the pre-reorg URL (.../supported-services.html, now a 404),
  to .../Configuration/Supported-Services.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 README.md                | 15 +++++++++++++++
 _build/setup.options.php |  2 +-
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 016d77c..7c05918 100644
--- a/README.md
+++ b/README.md
@@ -120,6 +120,21 @@ After installation:
 2. Enable the features you want to use.
 3. Start using AI features inside the MODX Manager.
 
+### Getting provider API keys
+
+The installer prompts you for provider API keys during setup. You need **at least one** to use modAI, and you can add or change keys 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. |
+| **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.
 
 ## Development setup
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) {

From a69fa20119046252b523ea2b64aae7c856de7b9c Mon Sep 17 00:00:00 2001
From: Ryan Thrash <ryan@thrash.me>
Date: Fri, 5 Jun 2026 19:03:29 -0500
Subject: [PATCH 5/7] =?UTF-8?q?docs:=20fix=20Installation=20steps=20?=
 =?UTF-8?q?=E2=80=94=20keys=20are=20entered=20during=20setup?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

"Configure at least one AI provider" was listed under "After
installation", but the installer prompts for provider API keys during
setup. Move that into the install line and leave the post-install steps
as enabling features and using modAI.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 README.md | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 7c05918..de1088a 100644
--- a/README.md
+++ b/README.md
@@ -112,13 +112,12 @@ Provider-specific features may have their own requirements.
 
 ## Installation
 
-Install modAI through the MODX Extras installer ([package page](https://extras.modx.com/package/modai)).
+Install modAI through the MODX Extras installer ([package page](https://extras.modx.com/package/modai)). During setup you'll be prompted to add at least one provider API key (you can also add or change keys later in the system settings).
 
 After installation:
 
-1. Configure at least one AI provider.
-2. Enable the features you want to use.
-3. Start using AI features inside the MODX Manager.
+1. Enable the features you want to use.
+2. Start using AI features inside the MODX Manager.
 
 ### Getting provider API keys
 

From c79aa94d229df4a46a56f3dc0ed4decc358497d9 Mon Sep 17 00:00:00 2001
From: Ryan Thrash <ryan@thrash.me>
Date: Fri, 5 Jun 2026 19:08:38 -0500
Subject: [PATCH 6/7] =?UTF-8?q?docs:=20reorder=20Installation=20=E2=80=94?=
 =?UTF-8?q?=20keys=20before=20post-install=20steps?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Move the "After installation" steps below the "Getting provider API
keys" section so the flow reads install -> add keys -> enable and use.
Trim the duplicated "you'll be prompted / add later" wording between the
install line and the keys section.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 README.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index de1088a..470dd22 100644
--- a/README.md
+++ b/README.md
@@ -112,16 +112,11 @@ Provider-specific features may have their own requirements.
 
 ## Installation
 
-Install modAI through the MODX Extras installer ([package page](https://extras.modx.com/package/modai)). During setup you'll be prompted to add at least one provider API key (you can also add or change keys later in the system settings).
-
-After installation:
-
-1. Enable the features you want to use.
-2. Start using AI features inside the MODX Manager.
+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
 
-The installer prompts you for provider API keys during setup. You need **at least one** to use modAI, and you can add or change keys later in the system settings (`modai.api.{service}.key`).
+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:
 
@@ -136,6 +131,11 @@ Custom / OpenAI-compatible endpoints are configured directly in the system setti
 
 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:

From 6cb1a81bfa99997d18d76269f56efc229b150622 Mon Sep 17 00:00:00 2001
From: Ryan Thrash <ryan@thrash.me>
Date: Fri, 5 Jun 2026 19:12:55 -0500
Subject: [PATCH 7/7] docs: clarify Anthropic server-side, Extra compatibility,
 dev caveats
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Note that Anthropic/Claude runs server-side only and requires enabling
  modai.api.anthropic.execute_on_server (added to the API key table).
- Add a "Works with other MODX Extras" section covering image+ and
  SEO Suite, restoring the compatibility note from the prior README.
- Soften "used in production" to "actively developed and maintained"
  (unverifiable claim).
- Note in Development setup that modAI runs inside the Manager, so a
  local MODX Revolution 3.x install is needed to exercise changes —
  building assets alone is not enough.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 README.md | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 470dd22..90c27f5 100644
--- a/README.md
+++ b/README.md
@@ -24,7 +24,7 @@ Read [DESIGN_PRINCIPLES.md](DESIGN_PRINCIPLES.md) before proposing large changes
 
 ## Project status
 
-modAI is actively developed and used in production.
+modAI is actively developed and maintained.
 
 Current capabilities include:
 
@@ -83,6 +83,13 @@ Supported providers currently include:
 
 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:
@@ -123,7 +130,7 @@ 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. |
+| **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. |
 
@@ -164,6 +171,8 @@ Start development mode (watch/rebuild):
 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