Mecatl Studio: bring the web UI into the repository as apps/ and release its image #1736

Summary

Bring the Mecatl Studio web UI into this repository as apps/, and release it as a container image the same way the Slack bot example is released.

Status: initial Studio delivery landed; design alignment is active. The whole gh stack series (stack #1766) merged into main on 2026-09-23, and all six Studio acceptance plans are landed.

Decisions taken in the design interview (2026-09-21)

• apps/server depends on the published @stacklok-oss/mecatl-sdk from npm only; sdk/typescript is untouched.
• Self-contained pnpm workspace at apps/ (apps/web, apps/server, apps/contracts), included in the root Taskfile as studio:*.
• Bootstrap is a skeleton: health/runtime routes, auth service and routes, workspace shell, auth gate, generate pipeline. Features port one PR each afterwards as Bounded work with their own acceptance plans.
• Runtime modes spawn / mock / external all kept; the product path is external against a mecak8s deployment.
• Encrypted-cookie stateless sessions; Vercel entrypoint and preview relay dropped; single callback STUDIO_PUBLIC_URL/api/v1/auth/callback.
• One image, one origin, multi-stage; Chainguard node runtime pinned by digest; ghcr.io/stacklok/mecatl/studio.
• publish-studio release job cloned from publish-slack-bot; live from the first tag. Helm/Ingress is a follow-up.
• CI job with install, lint, typecheck, test, generated-drift check, and a no-push image build.
• MECATL_* for target settings, STUDIO_* for Studio-owned settings.
• Studio-owned apps/docker/mecated.Dockerfile for the local compose.
• Full security hardening in the bootstrap (public-URL-derived cookie flags, CSP, same-origin check, rate limiting, CSRF token, login audit log).
• In-repo docs plus ADR 0351.

Two of these changed during delivery:

• The image is labelled org.stacklok.mecatl.studio.stability=early-access rather than experimental, and the label stays for as long as Studio may change without notice between versions.
• The user-docs/ deployment page landed as the top layer of the stack rather than with the chat feature.

Steps

• Studio bootstrap: apps/ workspace, BFF, shell, image, CI, release #1746 bootstrap: apps/ workspace, BFF, shell, image, CI, release (plan + ADR 0351) — docs(plan): Mecatl Studio bootstrap acceptance plan and ADR 0351 #1753, feat(studio): bootstrap the Mecatl Studio web UI as apps/ #1754
• Studio chat: sessions, streamed runs, controls, chat workspace #1747 chat — docs(plan): Mecatl Studio chat acceptance plan #1755, feat(studio): chat — sessions, streamed runs, controls, and the chat workspace #1756
• Studio schedules: capability-gated inventory, spec mapping, actions, fires #1748 schedules — docs(plan): Mecatl Studio schedules acceptance plan #1757, feat(studio): schedules — capability-gated inventory, spec mapping, actions, fires #1758
• Studio knowledge: skills, learned skills, learning review, memory consolidation #1749 knowledge — docs(plan): Mecatl Studio knowledge acceptance plan #1759, feat(studio): knowledge — skills, learned skills, learning review, memory consolidation #1760
• Studio settings: runtime inventory, storage health, settings workspace #1750 settings — docs(plan): Mecatl Studio settings acceptance plan #1761, feat(studio): settings — runtime inventory, storage health, settings workspace #1762
• Studio global search palette and keyboard-shortcuts reference #1751 global search and keyboard shortcuts — docs(plan): Mecatl Studio global search and keyboard shortcuts acceptance plan #1763, feat(studio): global search palette and keyboard-shortcuts reference #1764
• Studio user documentation: deployment page #1752 user documentation — docs(user-docs): Mecatl Studio web UI deployment page #1765

An integration suite that drives the BFF over the real SDK against a spawned mecated --mock landed as #1767, and runs in the studio CI job.

Where it lives

• Code: apps/ (README for local development).
• Decision record: ADR 0351.
• Acceptance plans: docs/acceptance/studio-{bootstrap,chat,schedules,knowledge,settings,search-shortcuts}.md.
• User documentation: Mecatl Studio web UI.
• Image: ghcr.io/stacklok/mecatl/studio, published from the next v* release tag.

Follow-ups

Not part of this delivery:

• Helm chart / Ingress wiring for Studio next to mecak8s.
• Register STUDIO_PUBLIC_URL/api/v1/auth/callback with each deployment's OIDC client. The staging Okta client currently accepts only the mecatui loopback callback, so the image works against staging only in local-development callback mode.
• Settings: providerEndpoint is always empty; filling it needs a per-provider server-info call and a contract change.
• Auth: the refresh grace window is per replica, so replicas without session affinity can still race a rotating refresh token; cookies do not use the __Host- prefix.
• CI: the studio job has no always-run aggregator gate, and the image is built but never started in CI (it runs Node 26 while tests run on Node 24).
• Chat web: Enter during an IME composition sends the composer's prompt; queue and multi-tab edge cases; the CSP blocks the PDF preview; Android notifications; whole-transcript re-render on every token.
• Knowledge: learned skills past the first 100 are unreachable; the detail page shows a stale state briefly after an action.

Design alignment follow-up (2026-09-24)

The first Studio port is complete. These linked sub-issues bring the current app to the
agreed design baseline; their descriptions are the implementation scope. #1779 coordinates
maintainer visual and interaction review. #1777 owns any mechanical structure move,
#1775 owns agent conventions, and #1776 owns browser-test infrastructure, so those tracks
are not duplicated here.

• Studio appearance: design tokens, palettes, typography, and shared controls #1843 — appearance, palettes, typography, and shared controls
• Studio shell: navigation, search, error pages, and installable app assets #1844 — shell, navigation, search, error pages, installable assets
• Studio sign-in and recovery: OIDC popup, public status, and banners #1845 — popup sign-in, minimal public status, recovery banners
• Studio settings and About: section routes, provider detail, and shortcuts #1846 — settings routes, provider detail, About, shortcuts
• Studio chat: transcript, composer, and live-session layout #1847 — chat transcript, composer, and live-session layout
• Studio chat: inline approvals, plan review, and Escape behavior #1848 — inline approvals, plan review, and Escape behavior
• Studio chat: live subagent, parallel, and team activity #1849 — subagent, parallel, and team activity
• Studio chat: minimap, side panels, and session inspection #1850 — chat minimap, side panels, and session inspection
• Studio chat: browse MCP inventory and insert into a draft #1851 — MCP inventory and composer insertion
• Studio schedules: list, editor dialogs, detail, and run history #1852 — schedules list, dialogs, detail, and run history
• Studio skills: inventory, detail pages, and learned-skill review #1853 — skills inventory, detail, and learned-skill review
• Studio memory: stores, facts, detail, and consolidation #1854 — memory stores, facts, detail, and consolidation
• Studio learning: proposal queue, evidence, and chat reflection #1855 — learning proposals, evidence, and reflection
• Studio Labs: local demo chat and mock Projects tour #1856 — local Labs demo tour and mock Projects (later; does not block real chat)

Each behavior-changing issue follows the repository's acceptance-plan process. The local
Studio/BFF boundary and published-SDK rule from ADR 0351 remain in force. Maintainers
review desktop/mobile screenshots and the key interaction flow for each surface; new
tests build on #1776.

Implementation delivery for design alignment

Use independent implementation PRs targeting main, rather than a stacked series or an
aggregate preview PR. Each Bounded or Architectural issue gets its Plan / Interface PR
reviewed and merged before implementation, following docs/development-process.md.
Plans can advance in parallel; implementation PRs merge after their dependencies and
individual maintainer review. #1779 holds the final end-to-end design review on main
after the core sub-issues land, with any gaps fixed before that review closes. The local
Labs demo (#1856) remains a later, non-blocking item.