[kemister85]

Ticket: TINYDOC-3686

Site: Staging branch

Changes:

• Adds pages for Document Processing, the Usage API, and on-premises guardrails, hooks, and content moderation.
• Updates the on-premises pages to the current ai-service-tiny images (0.1.0 to 1.2.1): version gates use Tiny image numbers, and the pages cover the new provider authentication options, the MCP server admin API, the configuration file, and log levels.
• Corrects published details, moves example models to active models, and points API reference links to /v1/docs.

Main pages changed:

• On-premises hooks
  • New page: hook configuration, request signing, the turn.start request, decisions, and troubleshooting.
• On-premises LLM providers
  • Default model list, Azure, Bedrock, and Vertex AI authentication options, custom agent models, and model availability.
• On-premises content moderation
  • New page: the openai and custom moderation providers, the endpoint contract, and what the editor shows.
• On-premises guardrails
  • New page: operations, options, classification rules, rollout, and rejection behavior.
• Document Processing
  • New page: the request flow and the fragment (ARF) response format.

---

Pre-checks:

• Branch is correctly prefixed:
• modules/ROOT/nav.adoc has been updated (if applicable).
• Files have been included where required (if applicable).
• Build passes without console errors, warnings, or issues.

---

Review:

• Documentation Team Lead has reviewed.

[june-at-tiny]

Hey Karl, Shridi asked me to have a look at these docs after testing the image.

I found the following potential issues, none of them critical.

(Claude helped compare different doc pages and endpoints).

1. mcp resources aren't documented

The mcp section only covers tools, resources aren't mentioned, integrators might expect resources to just work, but they need to be added to the context library.

2. permission list is incomplete

The JWT section says its list is the canonical permission list, but it's missing a lot and doesn't link to the permissions page, which has them all:

• ai:models:* and ai:models:<provider>:*
• ai:actions:custom and ai:reviews:custom
• ai:actions:system:<name> and ai:reviews:system:<name>
• ai:conversations:context:files:<format> and ai:conversations:context:urls
• ai:documents:process
• ai:contexts:<id>

Nothing says auto-applied contexts need ai:contexts:<id>, without it they get skipped silently.

3. the built-in action names on the jwt and overview pages seem wrong

The JWT section says ai:actions:system:* covers rewrite, summarize and expand, and the overview lists them as quick actions, but there's no rewrite or expand, and summarize is a chat action so it needs ai:conversations:*. The actions page has it right, so these two pages just need to match it.

4. metric log format is wrong

The production section's example metric log entry (with ENABLE_METRIC_LOGS=true) has fields that don't exist, so any log parsing or alerts built from it won't match anything.

The docs example:

{"timestamp":"2026-05-19T10:30:00.123Z","method":"POST","path":"/v1/conversations/abc123/messages","statusCode":200,"durationMs":3421}

A real entry from the service for the same request, sending a message to a conversation:

{"level":30,"time":"2026-11-03T03:41:44.879Z","msg":"Request summary","handler":"createMessage","traceId":"5cd27baad742edcce2a780831a7bf505","data":{"duration":2382,"transport":"http","statusCode":200,"environmentId":"<env-id>","status":"success","url":"/v1/conversations/logex-1793677302/messages","method":"POST"},"tags":"metrics"}

5. string permissions cause a 500, and "*" grants nothing

The JWT and troubleshooting sections say a string instead of an array gets rejected with allowed: false, but anything that isn't an array of strings gives a 500 on every endpoint, a string ("ai:conversations:*", "*", "ai:admin"), an object, a number, null, or an array with a non-string in it. An empty array, a missing permissions key or no auth claim gets a clean 403 no-permissions-defined, and ["*"] is accepted but grants nothing.

The docs should say permissions must be an array of strings, and the 500s should really be a 4xx, so that's one for engineering too.

6. Typo: "languages" instead of "frameworks"

on https://pr-4411.tinymce-docs.iad.staging.tiny.cloud/docs/tinymce/latest/tinymceai-on-premises-getting-started/ it says

The token server signs JSON Web Tokens (JWTs) for the editor. The Node.js example below is for the demo only; the JWT authentication guide contains production-ready endpoints in 8 languages (Node, Django, Flask, Laravel, Rails, .NET, Go, Spring Boot).

these are frameworks not languages, and two of them (Django and Flask) use the same language

7. key rotation step says to add the key to the PROVIDERS array

The production security table says "Add the new key to the PROVIDERS array", but PROVIDERS is a JSON object, the key goes in that provider's apiKeys array. Following it literally breaks the config, it should say "add the new key to the provider's apiKeys".

[kemister85]

Thanks @june-at-tiny, all seven points checked out and are fixed in a0479cd and 61b9c10.

• The metric log section now uses your real entry and documents only the fields you saw on the image. I'll add fail for 5xx and the health-check behavior once those are confirmed.
• The docs now state the 500 for non-array permissions. If engineering changes it to a 4xx, I'll update the pages.