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

Author: kemister85

modules/ROOT/nav.adoc

@@ -274,10 +274,10 @@
 ***** xref:tinymceai-on-premises-getting-started.adoc[Getting started]
 ***** xref:tinymceai-on-premises-database.adoc[Database, Redis, and storage]
 ***** xref:tinymceai-on-premises-providers.adoc[LLM providers]
-***** xref:tinymceai-on-premises-mcp.adoc[MCP and web integrations]
 ***** xref:tinymceai-on-premises-jwt.adoc[JWT authentication]
 ***** xref:tinymceai-on-premises-frameworks.adoc[TinyMCE integration]
 ***** xref:tinymceai-on-premises-production.adoc[Production deployment]
+***** xref:tinymceai-on-premises-mcp.adoc[MCP and web integrations (optional)]
 ***** xref:tinymceai-on-premises-troubleshooting.adoc[Troubleshooting]
 ***** xref:tinymceai-on-premises-reference.adoc[Reference]
 **** xref:ai.adoc[AI Assistant (legacy)]

modules/ROOT/pages/tinymceai-on-premises-database.adoc

@@ -37,21 +37,11 @@ The AI service supports both MySQL and PostgreSQL equally. Pick whichever the op
 
 == Choosing a setup path
 
+Use Docker Compose for evaluation, managed cloud services (Amazon RDS, Cloud SQL, Azure Database) for production. All paths produce the same end state: a running database the AI service can connect to. Both MySQL and PostgreSQL are supported in every configuration.
+
 [.text-center]
 image::tinymceai-on-premises/database-setup-fig-1.svg[Database setup decision tree: local Docker Compose vs managed cloud database for evaluation and production,width=100%]
 
-All paths produce the same end state: a running database the AI service can connect to.
-
-[cols="1,1,1",options="header"]
-|===
-|Path |MySQL |PostgreSQL
-
-|Docker / Podman |Yes |Yes
-|Docker Compose |Yes |Yes
-|Native (macOS / Linux) |Yes |Yes
-|Managed cloud (RDS, Cloud SQL, Azure) |Yes |Yes
-|===
-
 
 
 [[postgresql-schema-prerequisite]]
@@ -117,7 +107,7 @@ The database user needs enough privilege to create, alter, and operate on these
 
 [source,sql]
 ----
-CREATE USER 'ai_service'@'%' IDENTIFIED BY 'STRONG_PASSWORD';
+CREATE USER 'ai_service'@'%' IDENTIFIED BY '<strong-password>';
 GRANT SELECT, INSERT, UPDATE, DELETE,
       ALTER, CREATE, DROP, INDEX,
       TRIGGER, LOCK TABLES, REFERENCES
@@ -145,7 +135,7 @@ If `DATABASE_SCHEMA=public` was chosen (see <<postgresql-schema-prerequisite>>),
 
 [source,sql]
 ----
-CREATE USER ai_service WITH PASSWORD 'STRONG_PASSWORD';
+CREATE USER ai_service WITH PASSWORD '<strong-password>';
 CREATE DATABASE ai_service OWNER ai_service;
 \c ai_service
 CREATE SCHEMA "cs-on-premises" AUTHORIZATION ai_service;
@@ -175,19 +165,17 @@ The sections below provide ready-to-use configuration for each database engine.
 
 === Docker Compose (recommended for evaluation)
 
-.MySQL compose file
-[%collapsible]
-====
 [source,yaml]
+.MySQL compose file
 ----
 services:
   mysql:
     image: mysql:8.0
     environment:
-      MYSQL_ROOT_PASSWORD: ROOT_PASSWORD
+      MYSQL_ROOT_PASSWORD: <root-password>
       MYSQL_DATABASE: ai_service
       MYSQL_USER: ai_service
-      MYSQL_PASSWORD: STRONG_PASSWORD
+      MYSQL_PASSWORD: <strong-password>
     ports:
       - "3306:3306"
     volumes:
@@ -211,7 +199,6 @@ services:
 volumes:
   mysql_data:
 ----
-====
 
 .PostgreSQL compose file
 [%collapsible]
@@ -224,7 +211,7 @@ services:
     environment:
       POSTGRES_DB: ai_service
       POSTGRES_USER: ai_service
-      POSTGRES_PASSWORD: STRONG_PASSWORD
+      POSTGRES_PASSWORD: <strong-password>
     ports:
       - "5432:5432"
     volumes:
@@ -269,10 +256,10 @@ Use these `docker run` commands when Docker Compose is not available or when int
 ----
 docker run -d \
   --name ai-mysql \
-  -e MYSQL_ROOT_PASSWORD=ROOT_PASSWORD \
+  -e MYSQL_ROOT_PASSWORD=<root-password> \
   -e MYSQL_DATABASE=ai_service \
   -e MYSQL_USER=ai_service \
-  -e MYSQL_PASSWORD=STRONG_PASSWORD \
+  -e MYSQL_PASSWORD=<strong-password> \
   -p 3306:3306 \
   -v ai_mysql_data:/var/lib/mysql \
   mysql:8.0
@@ -288,7 +275,7 @@ docker run -d \
   --name ai-postgres \
   -e POSTGRES_DB=ai_service \
   -e POSTGRES_USER=ai_service \
-  -e POSTGRES_PASSWORD=STRONG_PASSWORD \
+  -e POSTGRES_PASSWORD=<strong-password> \
   -p 5432:5432 \
   -v ai_pg_data:/var/lib/postgresql/data \
   postgres:16
@@ -319,7 +306,7 @@ brew services start mysql
 mysql_secure_installation
 mysql -u root -p <<'SQL'
 CREATE DATABASE ai_service;
-CREATE USER 'ai_service'@'%' IDENTIFIED BY 'STRONG_PASSWORD';
+CREATE USER 'ai_service'@'%' IDENTIFIED BY '<strong-password>';
 GRANT SELECT, INSERT, UPDATE, DELETE, ALTER, CREATE, DROP,
       INDEX, TRIGGER, LOCK TABLES, REFERENCES
   ON ai_service.* TO 'ai_service'@'%';
@@ -361,7 +348,7 @@ sudo systemctl enable --now mysql
 sudo mysql_secure_installation
 sudo mysql <<'SQL'
 CREATE DATABASE ai_service;
-CREATE USER 'ai_service'@'%' IDENTIFIED BY 'STRONG_PASSWORD';
+CREATE USER 'ai_service'@'%' IDENTIFIED BY '<strong-password>';
 GRANT SELECT, INSERT, UPDATE, DELETE, ALTER, CREATE, DROP,
       INDEX, TRIGGER, LOCK TABLES, REFERENCES
   ON ai_service.* TO 'ai_service'@'%';
@@ -379,7 +366,7 @@ sudo apt update
 sudo apt install -y postgresql postgresql-contrib
 sudo systemctl enable --now postgresql
 sudo -u postgres psql <<'SQL'
-CREATE USER ai_service WITH PASSWORD 'STRONG_PASSWORD';
+CREATE USER ai_service WITH PASSWORD '<strong-password>';
 CREATE DATABASE ai_service OWNER ai_service;
 SQL
 sudo -u postgres psql -d ai_service \
@@ -653,7 +640,7 @@ After provisioning the database and Redis, pass the connection details to the AI
 -e DATABASE_HOST='mysql' \
 -e DATABASE_PORT='3306' \
 -e DATABASE_USER='ai_service' \
--e DATABASE_PASSWORD='STRONG_PASSWORD' \
+-e DATABASE_PASSWORD='<strong-password>' \
 -e DATABASE_DATABASE='ai_service' \
 -e REDIS_HOST='redis' \
 -e REDIS_PORT='6379'
@@ -667,7 +654,7 @@ After provisioning the database and Redis, pass the connection details to the AI
 -e DATABASE_HOST='postgres' \
 -e DATABASE_PORT='5432' \
 -e DATABASE_USER='ai_service' \
--e DATABASE_PASSWORD='STRONG_PASSWORD' \
+-e DATABASE_PASSWORD='<strong-password>' \
 -e DATABASE_DATABASE='ai_service' \
 -e DATABASE_SCHEMA='cs-on-premises' \
 -e REDIS_HOST='redis' \
@@ -714,7 +701,7 @@ For a complete `docker run` command including all env vars, see the xref:tinymce
 
 [source,bash]
 ----
-mysql --host=DB_HOST --user=ai_service --password=STRONG_PASSWORD \
+mysql --host=DB_HOST --user=ai_service --password=<strong-password> \
   ai_service --port=3306 -e "SELECT 1"
 ----
 

modules/ROOT/pages/tinymceai-on-premises-getting-started.adoc

@@ -13,10 +13,19 @@ This guide sets up a fully working local stack in roughly five minutes on any ma
 
 The quick start is designed to validate the stack components before moving to a production deployment. Production engineers can review this section to understand the conceptual flow before continuing to xref:tinymceai-on-premises-production.adoc[Production deployment].
 
-=== Prerequisites
+== Before you begin
+
+Verify the following are installed and accessible:
+
+[source,bash]
+----
+docker --version   # 20.10+ required (or podman --version for Podman 4+)
+node --version     # 18+ required
+npm --version
+----
+
+Additionally, have the following credentials ready:
 
-* Docker 20.10{plus} (or Podman 4{plus})
-* Node.js 18{plus} and npm (for the demo token server)
 * A TinyMCE license key and container registry credentials (from the Tiny account representative)
 * At least one LLM provider API key (OpenAI, Anthropic, or Google)
 
@@ -37,18 +46,18 @@ For Docker:
 
 [source,bash]
 ----
-docker login -u 'TINY_REGISTRY_USERNAME' https://registry.containers.tiny.cloud
+docker login -u '<registry-username>' https://registry.containers.tiny.cloud
 # Docker prompts for the password; this avoids leaking it in shell history.
 ----
 
 For Podman:
 
 [source,bash]
 ----
-podman login -u 'TINY_REGISTRY_USERNAME' registry.containers.tiny.cloud
+podman login -u '<registry-username>' registry.containers.tiny.cloud
 ----
 
-Replace `TINY_REGISTRY_USERNAME` with the username supplied by the Tiny account representative. If credentials have not been received, contact `support@tiny.cloud`.
+Replace `<registry-username>` with the username supplied by the Tiny account representative. If credentials have not been received, contact `support@tiny.cloud`.
 
 === Pull the AI service image
 
@@ -155,35 +164,21 @@ Both data layer containers (MySQL and Redis) should report `healthy` in the STAT
 
 The AI service runs as a standalone container outside of the Docker Compose stack. This separation allows upgrading or reconfiguring the AI service without restarting the database and Redis.
 
-Run from the same folder as the `.env` file:
+First, find the Docker Compose network name (Docker creates it from the folder name):
 
 [source,bash]
 ----
-set -a && source .env && set +a
+docker network ls --format '{{.Name}}' | grep default
+----
 
-PROVIDERS='{'
-if [ -n "$OPENAI_API_KEY" ]; then
-  PROVIDERS+='"openai":{"type":"openai","apiKeys":["'"$OPENAI_API_KEY"'"]}'
-fi
-if [ -n "$ANTHROPIC_API_KEY" ]; then
-  [ "$PROVIDERS" != '{' ] && PROVIDERS+=','
-  PROVIDERS+='"anthropic":{"type":"anthropic","apiKeys":["'"$ANTHROPIC_API_KEY"'"]}'
-fi
-if [ -n "$GOOGLE_API_KEY" ]; then
-  [ "$PROVIDERS" != '{' ] && PROVIDERS+=','
-  PROVIDERS+='"google":{"type":"google","apiKeys":["'"$GOOGLE_API_KEY"'"]}'
-fi
-PROVIDERS+='}'
-
-# Resolve the compose network name (varies across Docker versions and folder names)
-NETWORK=$(docker network ls --format '{{.Name}}' | grep -E "^$(basename "$PWD" | tr '[:upper:]' '[:lower:]')[_-]default$" | head -1)
-if [ -z "$NETWORK" ]; then
-  echo "ERROR: Could not find the Docker Compose network. Run 'docker network ls' and pass the network name with --network=<name>."
-  exit 1
-fi
+Use the matching network name in `--network` below. Then run from the same folder as the `.env` file:
+
+[source,bash]
+----
+set -a && source .env && set +a
 
 docker run --init -d -p 8000:8000 \
-  --network "$NETWORK" \
+  --network <compose-network-name>_default \
   --name ai-service \
   -e LICENSE_KEY="$LICENSE_KEY" \
   -e ENVIRONMENTS_MANAGEMENT_SECRET_KEY="$MANAGEMENT_SECRET" \
@@ -193,13 +188,15 @@ docker run --init -d -p 8000:8000 \
   -e DATABASE_PASSWORD="$DB_PASSWORD" \
   -e DATABASE_DATABASE='ai_service' \
   -e REDIS_HOST='redis' \
-  -e PROVIDERS="$PROVIDERS" \
+  -e PROVIDERS='{"openai":{"type":"openai","apiKeys":["'"$OPENAI_API_KEY"'"]}}' \
   -e STORAGE_DRIVER='database' \
   -e ALLOWED_ORIGINS='http://localhost:3000' \
   -e ENABLE_METRIC_LOGS='true' \
   registry.containers.tiny.cloud/ai-service-tiny:latest
 ----
 
+TIP: The network name is typically `<foldername>_default` (e.g., `tinymce-ai-onpremise_default`). Run `docker network ls` to confirm. For multiple LLM providers, extend the `PROVIDERS` JSON: `{"openai":{...},"anthropic":{...}}`.
+
 For Podman, replace `docker run` with `podman run` and use a Podman pod instead of a compose network. See xref:tinymceai-on-premises-production.adoc[Production deployment] for Podman-specific guidance. See xref:tinymceai-on-premises-production.adoc#_podman_deployment[Podman deployment] for a full example.
 
 For native databases (the database runs on the host or in a managed service rather than in Docker), drop the `--network` flag and set `DATABASE_HOST=host.docker.internal` (Docker Desktop and Podman 4{plus}). On native Linux Docker, additionally pass `--add-host=host.docker.internal:host-gateway`.
@@ -218,6 +215,17 @@ Expected response:
 {"serviceName":"on-premises-http","uptime":5.123}
 ----
 
+.Successful boot log (`docker logs ai-service`)
+[source,text]
+----
+Connecting to database (driver=mysql host=mysql)
+Running migrations...
+Migrations complete: 32 tables ready
+Connecting to Redis (host=redis:6379)
+Redis connected
+Server is listening on port 8000.
+----
+
 [WARNING]
 --
 If the container exits immediately, run `docker logs ai-service`. The most common causes are documented in the xref:tinymceai-on-premises-troubleshooting.adoc[Troubleshooting] guide. The top three are: malformed `LICENSE_KEY` (line breaks from word wrap), missing PostgreSQL schema, and JSON syntax error in `PROVIDERS`.
@@ -271,10 +279,8 @@ Create `package.json`:
 
 Create `token-server.js`:
 
-.Full token-server.js listing
-[%collapsible]
-====
 [source,javascript]
+.token-server.js
 ----
 require('dotenv').config();
 const express = require('express');
@@ -350,7 +356,6 @@ app.listen(PORT, () => {
   console.log('AI Service: ' + AI_SERVICE_URL);
 });
 ----
-====
 
 === Install and run
 
@@ -493,3 +498,13 @@ For Kubernetes, scale the deployment to zero or delete it. Persistent volumes fo
 ----
 kubectl delete deployment ai-service -n tinymce-ai
 ----
+
+== Next steps
+
+The quick start validates the stack end-to-end on a single machine. To deploy for production, work through each guide in order:
+
+. xref:tinymceai-on-premises-database.adoc[Database, Redis, and storage]: provision managed databases, configure TLS, and set up production-grade file storage.
+. xref:tinymceai-on-premises-providers.adoc[LLM providers]: configure explicit model catalogs and multi-provider routing.
+. xref:tinymceai-on-premises-jwt.adoc[JWT authentication]: build the production token endpoint with proper permissions and multi-tenant isolation.
+. xref:tinymceai-on-premises-frameworks.adoc[TinyMCE integration]: wire the editor to the production AI service with CORS and CSP.
+. xref:tinymceai-on-premises-production.adoc[Production deployment]: deploy to Kubernetes or ECS with TLS, scaling, and observability.