DOC-3498: tinymceai on-premises documentation (#4142)

* DOC-3498: tinymceai on-prem documentation.

* DOC-3498: Address content gaps identified in source audit

Add missing customer-facing content identified by comparing the
original internal documentation against the current on-premises
AsciiDoc pages: capabilities matrix on the overview page, Podman
production runbook, performance characteristics table, expanded
known limits reference, MySQL 8.4 caveat, Ollama systemd and
Modelfile examples, and getting-started teardown and config update
guidance.

* DOC-3498: Expand acronyms on first prose use across on-premises pages

Expand 18 acronyms (OCI, JWT, LLM, SSE, TLS, CORS, MCP, NTP, HPA,
OTLP, IRSA, ADC, SSR, CSP, SIEM, PII, HA, mTLS) on first prose
occurrence per page for readers unfamiliar with the terms.

* DOC-3498: Clean up architecture overview diagram

Reduce edge clutter by connecting a single representative replica
to downstream services and grouping the data layer into a subgraph.
Fix SVG width to use a fixed pixel value consistent with other
diagrams in the set.

* DOC-3498: Address PR review feedback from metricjs

- Generalize overview page for standalone API use, not just TinyMCE
- Swap complex architecture diagram for simplified overview diagram
- Move detailed enterprise topology to production page (collapsible)
- Fix capabilities table: chat, document review, file attachments, scaling
- Redis: mark Sentinel as not supported
- Remove TinyMCE 8.0+ from prerequisites (not required for API-only)
- Reverse proxy changed from required to recommended
- Fix decision tree cross-references (Section 33 -> guide names)
- Replace troubleshooting flowchart with ordered triage list
- Rename "Framework integration" to "TinyMCE integration" across all refs
- Fix API key reference for on-prem (license key or API key)
- Reorder support section docker commands for logical flow
- Make MCP diagram arrows bidirectional
- LLM providers: clarify native vs OpenAI-compatible providers
- Re-render all mermaid diagrams

* DOC-3498: Update Docker image name to ai-service-tiny

Registry URL confirmed as registry.containers.tiny.cloud/ai-service-tiny.

* DOC-3498: Address review feedback from tiny-ben-tran and ArvinJ-H

- Soften privacy claim to clarify LLM provider data handling
- Reword data flow steps (JWT, prompt phrasing)
- Clarify setup path section and topic guide introduction
- Remove orphan diagrams (troubleshooting-fig-1, complete-guide-fig-9)
- Remove "Must include" from plugins table, fix troubleshooting wording
- Replace MySQL 8.4 references with "the latest MySQL" across all pages
- Add provenance NOTE to performance characteristics
- Consolidate production page diagrams (promote complete-guide-fig-1)
- Improve overview and providers diagram layouts (LR, spacing)
- Move provider examples out of collapsible block for visibility

* DOC-3498: Remove internal testing reference from performance note

* DOC-3498: Remove unverified performance and sizing sections

Remove Performance characteristics and Sizing guide from the
production page until engineering provides verified data.

* DOC-3498: Remove redundant [arabic] list style attributes

* DOC-3498: Address evaluation findings from on-prem setup testing

Fix Redis Sentinel contradiction, add terminationGracePeriodSeconds
and PDB to K8s manifest, add S3 credentials and topology spread,
bootstrap step after Service manifest, HPA I/O-bound caveat, managed
database TLS section, Docker network resolution for Compose v2,
MODELS requirement clarification, and assorted cross-links and
callouts identified during the independent evaluation audit.

* DOC-3498: Apply CockroachDB-benchmark review pass and address PR feedback

- Add Credentials table and OpenAPI capability to Overview
- Expand CORS section with format, wildcards, preflight, common mistakes
- Add production readiness checklist and prerequisite statement
- Document agent-1 default model behavior on Providers page
- Add MODELS and secrets to ECS task definition example
- Document IAM/IRSA limitation across all deployment targets
- Trim rate limiting, distributed logging, PDB, topology to one-liners
- Remove marketing sections from Advanced (guardrails, document pipeline)
- Label install commands in JWT examples for clarity
- Address reviewer feedback on Getting Started clarity and formatting

* DOC-3498: Style fixes, terminology consistency, and external links

- Fix "On-Premise" to "on-premises" in page titles
- Update Advanced description to match trimmed content
- Add external links: K8s Secrets, Ingress, HPA, KEDA, OTLP, nginx
- Replace jargon ("upstream", "definitive") with neutral phrasing
- Normalize xref capitalization to sentence case
- Replace "ensure" with direct imperatives per style guide

* Restructure Advanced scenarios page into focused child pages

Move MCP and web scraping/search content to a dedicated child page
(tinymceai-on-premises-mcp.adoc) under LLM providers. Move
multi-tenant deployment content into the JWT authentication page.
Delete the catch-all Advanced scenarios page and update all
cross-references and nav accordingly.

* Fix audit findings across all on-premises documentation

- Getting Started: add ALLOWED_ORIGINS, fix CORS blocker, mark
  TINYMCE_API_KEY required for CDN demo, fix NOTE inside bash block,
  un-collapse launch script, add prerequisites section
- Production: add missing storage secret keys to K8s Secret, add
  ALLOWED_ORIGINS to K8s and ECS, align HPA minReplicas, add ECS
  startPeriod, label Podman as eval-only storage
- JWT: fix aud description, fix sanity-check port, coerce sub to String
- Frameworks: add React, Vue, Angular minimal examples
- Database: add AI service connection env vars section
- MCP: label Express example as illustrative
- Overview: add MCP to topic guides table

* Add architecture diagram, page intros, and address PR feedback

- Add deployment architecture diagram (overview-fig-2.svg) to Overview
- Add "where this fits" introductory context to Database, Providers,
  JWT, and Frameworks pages linking to overall deployment flow
- Un-nest MCP page to same nav level as other on-prem pages
- Add Step 1/2/3 subheadings to Getting Started verification section
- Remove raw Management API reference from Getting Started
- Restructure Database version pinning into neutral parent section
- Fix "two layers" to "three layers" matching the diagram
- Address metricjs PR feedback: hyphens, TLS note, Redis wording,
  schema note ordering, conditions-first, section explanations

* Improve providers diagram readability

Add theme config with 14px font and wider node spacing, shorten
truncated model names, use uniform arrow weight throughout, and
fix SVG width to 1200px.

* Restructure OpenAI-compatible provider section for clarity

Un-collapse fields table and Ollama networking into visible sections,
remove duplicated LLM_TIMEOUT_MS, consolidate vLLM and LM Studio into
a comparison table, fix Verify to hit the AI service endpoint, and add
a "when to use" introductory sentence.

* Increase overview architecture diagram width to 1200px

* Normalize definition-style lists to colon delimiter

Replace em dashes and double hyphens with colons in label:description
list patterns across all on-premises pages. Normalize bold formatting
to single-asterisk emphasis for consistency.

* Improve on-premises docs structure, flow, and placeholder consistency

- Reorder nav: MCP moved after TinyMCE Integration, marked optional
- Un-collapse token server, K8s manifest, and MySQL compose file
- Add "Next steps" section to Getting Started bridging to production
- Replace dynamic launch script with static docker run + TIP
- Add expected boot log after docker run
- Promote prerequisites to "Before you begin" with verification commands
- Add complete docker run reference to Reference page
- Add numbered steps (1-5) to Production K8s section
- Standardize placeholders to <kebab-case> format across all pages
- Condense agent-1 explanation on Providers page
- Remove raw management API reference from Production page

* Address CK-DOCS-ASKS-HYBRID findings and Tim's diagram feedback

Diagrams:
- overview-fig-2: add LB/proxy, HTTPS/HTTP labels, fix token flow
  direction, split data layer into labeled nodes, fix label positioning
- complete-guide-fig-1: reduce to single replica (+N), add HTTPS labels,
  add read/write labels to data layer connections
- complete-guide-fig-2: remove bare-metal option, rename to
  "Container orchestrator"
- database-setup-fig-1: remove bare-metal, clarify native DB path

Critical fixes (from CK-DOCS-ASKS-HYBRID):
- G6: Fix WEBSEARCH_HEADERS from broken JSON to colon-CSV format
- G1: Add ai:conversations:webSearch to JWT permissions table

High-severity:
- D2: Add Postgres TLS known-issue warning (managed PG + missing SSL)
- B4: Add Bedrock API-key billing trap note
- E1: Document I/O-bound workload shape for HPA guidance
- E2: Add HA primitives section (PDB, anti-affinity, topology spread)
- E3: Add Azure (AKS) and GCP (GKE) cluster bring-up pointers

Medium/Low:
- D3: MySQL role-inherited grants note for Cloud SQL
- E7: License key shared across replicas statement
- G7: host.docker.internal loopback-bind warning
- Network requirements: license.container.tiny.cloud firewall whitelist
- MCP page: web search prominence TIP

* Address PR review comments from Ben, Shiridi, and Benjamin

- Delete unused duplicate diagram (complete-guide-fig-8)
- Frameworks: simplify intro text (remove SSR patterns)
- Overview: simplify step 3, IMPORTANT→NOTE, fix secret wording
- Overview: align LICENSE_KEY note with Ben's suggestion
- Getting Started: apply Shiridi's panel UI wording fixes
- Getting Started: fix dotenv override issue (Benjamin's report)
- Getting Started: align TIP folder name example with mkdir step

* Restructure MCP page: separate web search/scraping, reduce admonitions, fix style

- Split web search and web scraping into independent sections with clear
  enabling steps, trigger mechanisms, and endpoint contracts
- Reduce admonitions from 9 to 2 (WARNING + IMPORTANT only)
- Remove all em-dashes, fix US English, terminology, and Latin terms
- Add Prerequisites section, SSE events section, K8s deployment section
- Document per-message capabilities:{webSearch:{}} requirement
- Document POST /v1/conversations/{id}/web-resources trigger endpoint
- Add tool namespacing and Docker networking subsections
- Replace illustrative MCP example with official SDK-based example
- Add stdio transport limitation note
- Remove forward-looking OAuth statement (per team decision)
- Add production readiness checklist cross-reference
- Replace old diagram with new MCP-specific architecture SVG

* Fix WEBSEARCH_HEADERS description in reference, add web search note to getting-started

- Reference page: correct WEBSEARCH_HEADERS from "JSON object" to
  colon-CSV format with cross-reference to MCP page
- Getting started: add NOTE about enabling web search with link to
  full MCP/web configuration

* Address PR #4142 review comments

- Fix wildcard (*) rendering bug in JWT permissions table
- Clarify ENVIRONMENTS_MANAGEMENT_SECRET_KEY description
- Simplify filesystem storage IMPORTANT admonition
- Un-collapse PostgreSQL compose file for consistency
- Promote MySQL version pinning to WARNING admonition
- Align Redis description with overview diagram label

* Fix wildcard escape to preserve monospace formatting

Use `+*+` instead of pass:[*] so the asterisk renders in
monospace as intended.

* Update diagrams per Tim's feedback

- JWT sequence: label step 2 as tinymceai_token_provider callback
  rather than inventing a specific endpoint
- Overview flowchart: move token endpoint into Application layer,
  route SSE response back through load balancer, simplify LB↔AI
  to bidirectional HTTP/SSE edge

* Align overview prose with updated diagram layout

Token endpoint is now in the Application layer (not client layer),
matching the revised overview-fig-2 diagram structure.

* Apply Ben's suggestions: shorten SQL description, simplify setup intro

- Overview: SQL database bullet shortened to match actual storage scope
- Database: simplify setup path intro sentence per Ben's suggestion

* Re-render SVGs with intrinsic pixel widths

Run the render script to replace width="100%" with actual pixel
widths from viewBox. Fixes diagrams rendering too small in img tags.

* Move permissions example inline into JWT troubleshooting table

Embed the correct-permissions-shape JSON directly in the table cell
(as the last row) instead of an orphaned collapsible block between
sections. Uses a| for AsciiDoc block content in the cell.

* Normalize remaining PASTE_X_HERE placeholders to <kebab-case> format

* Add web-resources endpoint to API reference table

* Add reviews to LM Studio features example

LM Studio natively supports tool calling for the Llama 3.1 8B
Instruct GGUF model shown in the example. The omission of reviews
was overly conservative and inconsistent with the vLLM and Ollama
examples that use the same model family.

* Use {pluginname} and {productname} attributes across on-premises pages

Replace hardcoded TinyMCE AI and TinyMCE references with AsciiDoc
attributes in prose. Add :pluginname:, :description_short:, and
enrich :keywords: on all 10 on-premises pages.

* Replace CDN with NPM self-hosted editor on getting started page

- Fix project folder name: tinymce-ai-onpremise → tinymceai-onpremise
- Replace CDN script tag with locally served tinymce and tinymce-premium
- Rename LICENSE_KEY to AI_LICENCE_KEY in .env and docker run
- Remove TINYMCE_API_KEY (not needed for self-hosted editor)
- Add license_key init option with inline guidance
- Add tinymce and tinymce-premium (^8.4.0) to package.json

* Revert "Replace CDN with NPM self-hosted editor on getting started page"

This reverts commit 8909888.

The NPM self-hosted approach requires using plugin name 'ai' (on-premises)
instead of 'tinymceai' (cloud-only, CDN), and the tinymce-premium NPM
package does not include the tinymceai plugin. Reverting to CDN approach
until the plugin naming and static serving are resolved.

* Rename project folder and license key variable in getting started guide

Update mkdir command to use tinymceai-onpremise and rename
LICENSE_KEY to AI_LICENCE_KEY across .env template, docker run
command, and related notes.

* Add OAuth 2.0 authentication support to MCP docs

Document the new OAuth 2.0 Authorization Code with PKCE flow
for MCP servers, including configuration, Dynamic Client
Registration, authorization flow, REST endpoints, and
troubleshooting. Update reference page with MCP_OAUTH_CALLBACK_URL
env var and corrected authentication notes. Update overview page
feature table to mention OAuth support.

* Document license validation phone-home and data privacy

Add license validation notes to the overview, getting-started,
and production pages clarifying that the AI service contacts
license.containers.tiny.cloud on startup and that no customer
data is transmitted during the check.

* Fix MCP server example and add usability tips

Rewrite MCP server example to use stateless per-request pattern
(fixes crash on second request with SDK v1.29.0). Add package.json
snippet with pinned SDK version and type:module. Add container
name conflict and port 3000 tips to getting-started page.

* Replace CDN with self-hosted TinyMCE and add AI plugin setup

Switch the getting-started demo from CDN-loaded TinyMCE to a
self-hosted bundle served from node_modules. Add license_key
init option, licensekeymanager plugin, and instructions for
copying the tinymceai plugin into the plugins directory.
Also quote .env placeholders, split source/docker-run blocks,
clarify network naming, and update credential notes.

* Add OAuth callback, proxy pattern, and mixed auth examples to MCP docs

Sync validated MCP content: OAuth URL discovery (RFC 9728),
minimal callback page, browser proxy pattern, and mixed
internal/external server config example. Remove Atlassian-
specific examples pending further testing. Fix license
endpoint typo in production page and .env placeholder
inconsistency in getting-started guide.

* Address open PR review comments across on-prem docs

Getting-started: add bold labels and diagnostic guidance to
each verification step for readability. Database: fix double
underscore in table namespace list, add PostgreSQL skip note.
JWT: rename heading to Editor-side configuration. MCP: reorder
config table (oauth after headers), remove redundant OAuth
cross-ref, mention MCP_OAUTH_CALLBACK_URL in config intro,
change "changes" to "steps". Reference: clarify MCP auth
wording, add OAuth endpoints to API table.

* Replace five-minute claim with Quick start in getting-started heading

The original time estimate was unrealistic for first-run setups
that include image pulls and Management Panel configuration.

* Fix readability issue for IMPORTANT admon.

* Refine getting-started: clean up .env placeholders, remove licensekeymanager, expand port tip

Remove angle brackets from remaining .env placeholders, drop
licensekeymanager from plugins list, and convert the port-conflict
tip to a block with a code snippet for easier copy-paste.

Author: kemister85

-scripts/render-mermaid.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+#
+# Re-renders all .mmd Mermaid sources to .svg in the on-premises images folder.
+#
+# Usage (from repo root):
+#   ./-scripts/render-mermaid.sh
+#
+# Requirements:
+#   Node.js (npx downloads @mermaid-js/mermaid-cli automatically)
+#
+set -euo pipefail
+
+DIAGRAM_DIR="modules/ROOT/images/tinymceai-on-premises"
+CONFIG_FILE=$(mktemp)
+
+cat > "$CONFIG_FILE" << 'JSON'
+{
+  "htmlLabels": false,
+  "flowchart": { "htmlLabels": false, "useMaxWidth": true },
+  "sequence": { "useMaxWidth": true },
+  "theme": "default"
+}
+JSON
+
+trap 'rm -f "$CONFIG_FILE"' EXIT
+
+count=0
+for mmd in "$DIAGRAM_DIR"/*.mmd; do
+  [ -f "$mmd" ] || continue
+  svg="${mmd%.mmd}.svg"
+  name=$(basename "$mmd")
+  printf "  Rendering %s\n" "$name"
+  npx -y @mermaid-js/mermaid-cli -i "$mmd" -o "$svg" \
+    -c "$CONFIG_FILE" --backgroundColor white 2>/dev/null
+
+  # Mermaid outputs width="100%" which has no intrinsic size in <img> tags.
+  # Replace with the actual pixel width from the viewBox so browsers can
+  # calculate the correct aspect ratio when the page scales the image.
+  vb_width=$(grep -o 'viewBox="[^"]*"' "$svg" | head -1 | awk -F'[ "]' '{print $4}')
+  if [ -n "$vb_width" ]; then
+    vb_int=$(printf "%.0f" "$vb_width")
+    perl -i -pe "s/width=\"100%\"/width=\"${vb_int}\"/" "$svg"
+  fi
+
+  count=$((count + 1))
+done
+
+printf "\nRendered %d diagrams in %s\n" "$count" "$DIAGRAM_DIR"

modules/ROOT/images/tinymceai-on-premises/advanced-scenarios-fig-2.mmd

@@ -0,0 +1,14 @@
+flowchart LR
+    subgraph Tenants[Your SaaS customers]
+        CA[Customer A users]
+        CB[Customer B users]
+        CC[Customer C users]
+    end
+    subgraph AISvc[Single AI service deployment]
+        EA[Environment A<br>access keys A<br>isolated conversations]
+        EB[Environment B<br>access keys B<br>isolated conversations]
+        EC[Environment C<br>access keys C<br>isolated conversations]
+    end
+    CA --> EA --> OpenAI[OpenAI]
+    CB --> EB --> Anthropic[Anthropic]
+    CC --> EC --> Azure[Azure OpenAI]

modules/ROOT/images/tinymceai-on-premises/advanced-scenarios-fig-2.svg

@@ -0,0 +1,8 @@
+flowchart LR
+    Lawyer[TinyMCE editor<br>used by lawyer] <--> AI[AI Service]
+    AI -->|tools/call| MCP1[MCP: contract-db]
+    AI -->|tools/call| MCP2[MCP: compliance-checker]
+    AI -->|tools/call| MCP3[MCP: precedent-search]
+    MCP1 --> ContractDB[(Contract clause<br>repository)]
+    MCP2 --> ComplianceRules[(Regulatory<br>rule sets)]
+    MCP3 --> PrecedentIdx[(Precedent<br>search index)]

modules/ROOT/images/tinymceai-on-premises/advanced-scenarios-fig-3.mmd

@@ -0,0 +1,26 @@
+flowchart TB
+    Browser["Browser<br>TinyMCE editor + tinymceai plugin"]
+    TokenEP["Your token endpoint<br>signs HS256 JWTs"]
+    Browser -->|"HTTPS"| TokenEP
+    Browser -->|"HTTPS + Bearer JWT"| LB
+
+    subgraph App["Application layer (stateless, +N replicas)"]
+        LB["Reverse proxy / Load balancer<br>nginx · ALB · K8s Ingress<br>TLS termination · SSE pass-through"]
+        AI1["ai-service"]
+        LB -->|"HTTP"| AI1
+    end
+
+    subgraph Data["Shared data layer"]
+        DB[("SQL database<br>MySQL 8.0+ / PostgreSQL 13+")]
+        Cache[("Redis 3.2.6+")]
+        Storage[("File storage<br>S3 · Azure Blob · filesystem")]
+    end
+
+    AI1 <-->|"read/write"| DB
+    AI1 <-->|"read/write"| Cache
+    AI1 <-->|"read/write"| Storage
+
+    AI1 -->|"HTTPS"| LLM["LLM provider<br>OpenAI · Anthropic · Google ·<br>Azure · Bedrock · Vertex ·<br>self-hosted"]
+
+    AI1 -.->|"telemetry"| Obs["OpenTelemetry · Langfuse"]
+    AI1 -.->|"tool calls"| MCP["MCP servers"]

modules/ROOT/images/tinymceai-on-premises/advanced-scenarios-fig-3.svg

@@ -0,0 +1,15 @@
+flowchart TD
+    Start([New deployment]) --> Q1{Evaluating or<br>going to production?}
+    Q1 -->|Evaluating locally| Compose[Docker Compose<br>all services on one host<br>Getting started guide]
+    Q1 -->|Production| Q2{Container orchestrator?}
+    Q2 -->|Kubernetes| K8s[Kubernetes deployment<br>Production guide]
+    Q2 -->|AWS ECS / Fargate| ECS[ECS task definition<br>Production guide]
+    Q2 -->|Docker / Podman on VMs| VMs[Docker or Podman compose<br>Database guide]
+    Compose --> DB{Database?}
+    K8s --> DB
+    ECS --> DB
+    VMs --> DB
+    DB -->|Managed cloud DB| Managed[RDS · Cloud SQL ·<br>Azure Database]
+    DB -->|Self-managed| Self[Containers or native install]
+    Managed --> Done([Continue with<br>LLM providers guide])
+    Self --> Done

modules/ROOT/images/tinymceai-on-premises/complete-guide-fig-1.mmd

@@ -0,0 +1,18 @@
+flowchart TB
+    Internet([Internet]) --> Ingress[Ingress controller<br>nginx-ingress · ALB controller<br>proxy-buffering off]
+    Ingress --> SvcAI[Service: ai-service]
+    SvcAI --> Pod1[Pod: ai-service replica 1]
+    SvcAI --> Pod2[Pod: ai-service replica 2]
+    SvcAI --> PodN[Pod: ai-service replica N]
+    Pod1 --> SvcDB[Service: database<br>or external RDS]
+    Pod2 --> SvcDB
+    PodN --> SvcDB
+    Pod1 --> SvcRedis[Service: redis<br>or external ElastiCache]
+    Pod2 --> SvcRedis
+    PodN --> SvcRedis
+    Pod1 --> S3[(S3 / Azure Blob)]
+    Pod2 --> S3
+    PodN --> S3
+    HPA[HorizontalPodAutoscaler] -. scales .-> Pod1
+    HPA -. scales .-> Pod2
+    HPA -. scales .-> PodN