docs: reorganize sidebar into a task-based reading order

[rthrash]

Overview

A documentation overhaul for the docs/ site (Docusaurus). Three focused commits: a structural reorganization, a grammar/correctness pass, and a large content expansion that closes gaps between the docs and the actual codebase. All new content was verified against core/components/modai/ source.

Commits

1. Reorganize the sidebar into a task-based reading order (ecc8e3c)

The sidebar was autogenerated with no explicit ordering, so pages sorted alphabetically — advanced admin internals showed up second and Usage landed at the bottom.

• Added sidebar_position frontmatter to every page and a _category_.json (label + position + landing page) to each folder.
• New order: About → Usage → Configuration → Agents, Tools & Prompts → Glossary → Developer API.
• Moved Cost into Configuration and the internal History Module reference into a new Developer API group.
• Added a new Agents page (Agents were referenced throughout but never documented).

2. Fix typos, grammar, and incorrect setting names (29f0ae0)

Copy-edit pass plus three correctness fixes verified against the PHP source:

• Context Providers implement \modAI\ContextProviders\ContextProviderInterface, not \modAI\Tools\ToolInterface.
• Anthropic's per-service server-execution setting is modai.api.anthropic.execute_on_server (claude is not a valid service token — Anthropic::getServiceName() returns anthropic).
• The "enable only for ChatGPT" example used the anthropic key; ChatGPT's service name is openai. Also removed a stray } from the setting format.
• Typo/grammar fixes across the docs (valide→valid, tokes→tokens, controles→controls, subject-verb agreement, etc.).

3. Document chat, built-in tools, Pinecone, custom services & more (2e85527)

Researched the implementation and wrote up the major undocumented surface area:

• Chat (rewritten): the global chat assistant — opening it, text/image modes, DB-persisted history, pinning, public chats (clarified: visible to other Manager users, not anonymous links), search, clone, auto-titles + settings, agents/tools/context-providers in chat, media-browser integration, and the permission model.
• Tools: a Built-in Tools reference (all 13 seeded tools), the clear_cache config, the ToolInterface signature, and an Availability note (enabled vs. default vs. agent-attached).
• Context Providers: the built-in Pinecone provider — config reference, setup, integrated embedding + reranking retrieval, and auto-indexing via the modai.contexts.* settings; plus the correct ContextProviderInterface.
• Supported Services: a "Registering Custom Services" section (modAIOnServiceRegister, the AIService interface, model-prefix resolution, the AIResponse builder); fixed the custom-service compatibility setting key; noted the OpenAI custom service supports text/vision/image/edit.
• Overview: corrected stale default models/sizes/quality (gpt-5.5, gpt-5-nano, gpt-image-2, 1024x1024, auto), added base_output/context_prompt and the image media_source/path/download_domains settings, documented init.global_chat/init.media_browser/cache.lit, and added ImageCropper TV support.
• Prompt Library: documented the seeded Text/Image categories and the library's permissions.

Verification

• npm run build (production) passes with no broken links or anchor warnings.
• Dev server (npm start) compiled cleanly throughout.
• Content-only PR — no application code changes.

---

⚠️ Code bugs found while documenting (out of scope — tracked separately)

Reading the built-in Tool classes to document them surfaced three genuine bugs. They are not addressed in this docs PR (and the docs intentionally describe correct/intended behavior, not the buggy behavior). Filing here for visibility; they should be fixed in a separate code PR.

Bug 1 — name filter searches by the wrong argument (get_chunks, get_templates)

In the name branch, the WHERE clause is built from $arguments['query'] instead of $arguments['name'].

• core/components/modai/src/Tools/GetChunks.php:86 → ['name' => $arguments['query']]
• core/components/modai/src/Tools/GetTemplates.php:86 → ['templatename' => $arguments['query']]

Repro: invoke get_chunks with {"name": "myChunk"} and no query. The if (!empty($arguments['name'])) branch fires, but the filter value is $arguments['query'] — which is unset (null) — so it searches for a chunk literally named null and returns nothing. Even if both are supplied, the name value is ignored and the query value is used. Fix: use $arguments['name'] in that branch.

Bug 2 — create_resource JSON-Schema required list doesn't match its properties

core/components/modai/src/Tools/CreateResource.php:53 declares "required" => ["name", "description", "content"], but the item properties (lines 36–48) are pagetitle, template, parent, content. So the schema marks two non-existent properties (name, description) as required, while omitting template and parent — which the tool body does enforce at runtime (CreateResource.php:102–107 returns "parent is required" / "template is required").

Repro: have an agent call create_resource. The advertised schema tells the model name/description are required (they're ignored) and lets it legally omit template/parent. When the model omits them, runTool rejects the call with a runtime "required" error — a contradiction the schema should have prevented. Fix: set "required" => ["pagetitle", "template", "parent", "content"] (or whichever subset is truly mandatory). Note: CreateChunk and CreateTemplate are correct — their properties genuinely are name/description/content.

Bug 3 — edit_chunk cache refresh is unreachable on success

core/components/modai/src/Tools/EditChunk.php:96–104:

if ($chunk->save()) {
    return json_encode(['success' => true, ...]);  // returns here on success
}

if ($this->clearCache) {                            // only reachable if save() failed
    $this->modx->cacheManager->refresh();
}

return json_encode(['success' => false, 'message' => 'Could not save chunk.']);

On a successful save the method returns before the clearCache block, so the cache is never refreshed after a chunk edit (even though clear_cache defaults to on); the refresh is only reachable on the failed-save path, where it does nothing useful.

Repro: with clear_cache enabled (default), edit a cached chunk via the tool — the rendered output keeps serving the stale cached version until the cache is cleared another way. Fix: move the clearCache refresh before the success return (mirroring EditTemplate, which has the correct order: it returns early only on failure, then refreshes, then returns success — so EditTemplate is not affected).

🤖 Generated with Claude Code