docs: add contributor & developer documentation#110
Open
rthrash wants to merge 7 commits into
Open
Conversation
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>
- 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>
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>
- 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>
"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>
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>
- 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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds repo-level developer & contributor documentation and modernizes the root README. These are governance/onboarding docs, kept separate from the user-facing documentation site (
docs/).README.md(updated)ARCHITECTURE.md(new)DESIGN_PRINCIPLES.md(new)PROVIDERS.md(new)ROADMAP.md(new)CONTRIBUTING.md(new)Reconciled with the codebase
The drafts were reviewed against
core/components/modai/and corrected so the docs match what actually ships:config.platform; the draft said 8.1+.AIService/AIServiceFactory/AIResponse,ToolInterface,ContextProviderInterface,ConfigBuilder, thesrc/APIexecutor and endpoints, the data models, and themodAIOnServiceRegister/modAIOnToolRegister/modAIOnContextProviderRegisterextension events — plus a codebase map table.composer install,npm install,npm run build/dev/lint/docs:dev, and thephpcs.xmlPHP standard).README link handling
Per request, the new README keeps useful links (verified live):
Notes
DESIGN_PRINCIPLES,ARCHITECTURE,PROVIDERS,ROADMAP,CONTRIBUTING,LICENSE)._build/setup.options.php, fixing the installer's "Learn more" link to the post-reorg docs URL.🤖 Generated with Claude Code