Replit UI Workbench

Purpose

Use the Replit UI Workbench when a designer or product manager needs to edit UI code, run the Admin UI, widget, or docs locally, and test against the deployed testing environment.

Replit should use testing APIs through APIM. Do not copy the main backend .env into Replit, and do not weaken App Service network rules for Replit access.

Canonical repo artifacts:

Artifact	Purpose
.replit	Replit run button, workflows, ports, and non-secret APIM defaults.
replit.md	Short Replit agent/operator guide for import-time setup.
docs/internal/documentation-revival/replit-handoff-guide.md	Full setup, secrets, commands, ports, screenshots, and escalation rules.
docs/internal/documentation-revival/replit.env.example	Non-secret environment template for Replit Secrets and variables.
docs/internal/documentation-revival/endpoint-catalog.yaml	Machine-readable endpoint catalog with Replit-safe routes and mutation classes.
docs/internal/documentation-revival/source-route-inventory.json	Machine-readable source-derived route inventory for literal routes and route mounts.
docs/internal/documentation-revival/source-symbol-inventory.json	Machine-readable source-derived symbol inventory for exported and internal helpers.
docs/internal/documentation-revival/mcp-inventory.json	Machine-readable MCP server, tool registry, and docs-chat scope inventory.
docs/internal/documentation-revival/replit-mcp-client-config.json	Machine-readable local docs MCP and token-gated diagnostics MCP client snippets.
docs/internal/documentation-revival/replit-live-gate-checklist.md	User-run checklist for the remaining live APIM/Replit gates.
docs/internal/documentation-revival/safe-test-data.yaml	Safe testing data, approved-workflow policy, and routes to avoid.
docs/internal/documentation-revival/readiness-matrix.yaml	Current readiness state and live-gated checks.

Default Mode

Run UI surfaces locally in Replit:

• apps/admin-ui
• apps/widget
• docusaurus-docs

Call deployed testing APIs through:

https://test-aitools-llfc-apim.azure-api.net

Do not run the full Mastra runtime, ingestion worker, SQL, storage, AI Search, Document Intelligence, Azure OpenAI, provider stack, or diagnostics stack in a shared Replit workspace.

Minimum Secrets

Secret	Required?	Notes
APIM_SUBSCRIPTION_KEY	Yes	Primary testing APIM key.
MASTRA_APIM_SUBSCRIPTION_KEY	Yes for Admin UI live mode	Can use the same value as APIM_SUBSCRIPTION_KEY; the APIM smoke also accepts it as a fallback.
DOCS_CHAT_API_KEY	Optional	Can use the same value as APIM_SUBSCRIPTION_KEY for external scopes only.
INTERNAL_DOCS_CHAT_API_KEY	No by default	Requires explicit maintainer approval.

Keep these out of shared Replit by default:

• Azure OpenAI keys
• AI Search keys
• SQL connection strings
• storage connection strings
• Document Intelligence keys
• OAuth client secrets
• Key Vault credentials
• production APIM keys
• diagnostics gateway tokens

Live APIM Mode

Use live mode when the UI depends on deployed feature flags, service health, prompt workbench data, widget token/session flows, docs chat, or real testing API behavior.

APIM_SUBSCRIPTION_KEY=<testing APIM subscription key>
MASTRA_APIM_SUBSCRIPTION_KEY=<same testing APIM subscription key>
APIM_GATEWAY_URL=https://test-aitools-llfc-apim.azure-api.net
DASHBOARD_URL=https://test-aitools-llfc-apim.azure-api.net/dashboard/admin/
MASTRA_RUNTIME_URL=https://test-aitools-llfc-apim.azure-api.net/dashboard/admin-api
VITE_MOCK_API=false
BASE_PATH=/admin/
PORT=8787
npm --prefix apps/admin-ui run dev

Docs chat should use external scopes in shared Replit:

DOCS_CHAT_API_BASE_URL=https://test-aitools-llfc-apim.azure-api.net
# Optional for local Docusaurus docs chat external scopes:
# DOCS_CHAT_API_KEY=<same testing APIM subscription key>
DOCS_CHAT_SCOPE=sdac-external

Mock Mode

Use mock mode for layout-only iteration:

VITE_MOCK_API=true
BASE_PATH=/admin/
PORT=8787
npm --prefix apps/admin-ui run dev

Mock mode is useful for visual work, but final workflow checks should use live APIM mode.

Bootstrap

npm ci
npm --prefix apps/admin-ui ci --legacy-peer-deps
npm --prefix apps/widget ci
npm --prefix docusaurus-docs ci

Replit Workflows

The root .replit file exposes these workflows:

Workflow	Purpose
Admin UI	Run button; starts the Admin UI at /admin/.
Start Widget	Starts the local widget service.
Start Internal Docs	Starts the internal Docusaurus docs.
Bootstrap All UI Surfaces	Installs root, Admin UI, widget, and docs dependencies.
Dry Run APIM Smoke	Prints the APIM smoke plan without live calls or writes.
Validate Documentation Handoff	Runs docs:revival:check and smokes every local docs MCP server.

Smoke Checks

Dry-run the live APIM plan without secrets:

npm run replit:smoke:apim -- --dry-run
npm run replit:smoke:apim -- --dry-run --require-mcp-transport

Run live smoke only after the testing APIM key is available:

APIM_SUBSCRIPTION_KEY=<testing APIM subscription key> npm run replit:smoke:apim
APIM_SUBSCRIPTION_KEY=<testing APIM subscription key> npm run replit:smoke:apim -- --allow-widget-session

--allow-widget-session adds the dashboard widget-token flow and Widget Testing session route to the live smoke. The script reports status metadata and does not print the token or launch URL.

Widget upload smoke is stateful and explicitly write-gated:

npm run replit:fixture:sdac-workbook
APIM_SUBSCRIPTION_KEY=<testing APIM subscription key> \
  npm run replit:smoke:apim -- \
  --allow-widget-upload \
  --widget-upload-file temp/replit-sdac-smoke/Q2-2025-Replit_Test_District-sdac-costs.xlsx

Only run widget upload smoke after the fixture and reset policy are approved for shared testing.

Use docs/internal/documentation-revival/replit-live-gate-checklist.md as the single checklist for the remaining user-run live gates.

Permissions

Use branch or PR workflow. Do not allow direct pushes to main from Replit.

Replit can edit UI code, docs, and mock fixtures. Route backend/API shape, infra, database, ingestion-worker, provider/model, or production secret changes back to engineering.