Feat/webui

.github/dependabot.yml

@@ -154,3 +154,19 @@ updates:
         update-types:
           - minor
           - patch
+
+  # Studio (the Node web client) — npm.
+  - package-ecosystem: npm
+    directory: "/studio"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "chore(deps)"
+    labels:
+      - dependencies
+    groups:
+      npm-minor-patch:
+        update-types:
+          - minor
+          - patch

.github/workflows/studio.yml

@@ -0,0 +1,122 @@
+name: Studio
+
+on:
+  pull_request:
+    paths:
+      - "studio/**"
+      - "sdk/typescript/**"
+      - ".github/workflows/studio.yml"
+  push:
+    branches: [main]
+    paths:
+      - "studio/**"
+      - "sdk/typescript/**"
+      - ".github/workflows/studio.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    name: Build, test, lint, typecheck, audit
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      # Studio depends on the TypeScript SDK as `file:../sdk/typescript`; npm
+      # links the checkout without building it, so the SDK is built first with
+      # its own toolchain (pnpm, pinned exactly as ci.yml's SDK job pins it).
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+        with:
+          version: 11.25.0
+          run_install: false
+
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version-file: studio/.nvmrc
+          cache: npm
+          cache-dependency-path: studio/package-lock.json
+
+      - uses: go-task/setup-task@a00fbb05ce67b35648be3c78cbc9fd85354c757e # v2.2.0
+
+      - name: Build the TypeScript SDK
+        run: |
+          task sdk:install
+          task sdk:build
+
+      # No package in the tree needs install scripts (Next/sharp ship prebuilt
+      # binaries), so scripts stay off — supply-chain surface CI never runs.
+      - name: Install
+        working-directory: studio
+        run: npm ci --ignore-scripts
+
+      - name: Lint, typecheck, dead-code
+        working-directory: studio
+        run: |
+          npm run lint
+          npm run typecheck
+          npm run knip
+
+      - name: Unit tests
+        working-directory: studio
+        run: npx vitest run
+
+      - name: Build + hermetic server-tier suite
+        working-directory: studio
+        run: npm run test:server
+
+      - name: Audit
+        working-directory: studio
+        run: npm audit --audit-level=high
+
+      - name: License headers
+        run: |
+          if git grep -l "SPDX-License-Identifier: Proprietary" -- studio/; then
+            echo "Proprietary SPDX headers are not allowed in studio/" >&2
+            exit 1
+          fi
+
+  # Browser smoke over the real proxy tier against the fixture daemon.
+  # Separate job so a browser-infra flake never masks the checks above.
+  e2e:
+    name: Playwright (fixture daemon)
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      # Studio depends on the TypeScript SDK as `file:../sdk/typescript`; npm
+      # links the checkout without building it, so the SDK is built first with
+      # its own toolchain (pnpm, pinned exactly as ci.yml's SDK job pins it).
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+        with:
+          version: 11.25.0
+          run_install: false
+
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version-file: studio/.nvmrc
+          cache: npm
+          cache-dependency-path: studio/package-lock.json
+
+      - uses: go-task/setup-task@a00fbb05ce67b35648be3c78cbc9fd85354c757e # v2.2.0
+
+      - name: Build the TypeScript SDK
+        run: |
+          task sdk:install
+          task sdk:build
+
+      - name: Install
+        working-directory: studio
+        run: |
+          npm ci --ignore-scripts
+          npx playwright install --with-deps chromium
+
+      - name: Build and test
+        working-directory: studio
+        run: npm run test:e2e

.gitignore

@@ -43,3 +43,9 @@ coverage.*
 # Personal, local-only Claude Code instructions and running-state notes
 /CLAUDE.local.md
 /HANDOFF.md
+
+# Studio managed-mode local state (controller-pinned skills/memory dirs).
+/.mecatl/
+
+# Ad-hoc local attachment drops.
+/attachments/

.matlatlignore

@@ -63,6 +63,12 @@ user-docs/
 website/AGENTS.md
 website/CLAUDE.md
 
+# Studio's managed-mode working state (the controller pins the project skills
+# and memory dirs here) and ad-hoc local attachment drops — machine-local
+# state, not documentation. CI checkouts never contain them; ignoring them
+# keeps local `check`/`index` runs byte-identical to CI's.
+/.mecatl/
+/attachments/
 # API Extractor reports are review artifacts, not navigational documentation.
 # Exclude both the committed reports and their ignored comparison copies.
 sdk/typescript/etc/*.api.md

AGENTS.md

@@ -95,6 +95,7 @@ the opt-in `provider/*` submodules (ADR 0093), and the root module all move in l
 - `contracts/proto/mecatl/v1/` — gRPC contract (source of truth); `contracts/proto/mecatl/driver/v1/` — the driver protocol (SessionStoreService/MemoryStoreService stores; SkillSourceService/SoulSourceService/AgentSourceService/CommandSourceService content sources) a remote driver process implements; `contracts/gen/` is generated, **never hand-edit**.
 - `cmd/mecated/` — standalone server (composition root): flags, TLS/auth/rate-limit, HTTP + metrics listeners. `cmd/mecademo/` — the offline demo. `cmd/mecatequi/` — single-shot HEADLESS composition root (peer of mecademo over `app.Build`): one prompt → a git-diff patch + a JSON Summary + an optional JSONL log + an exit code. It is **FORGE-AGNOSTIC** — knows nothing about GitHub; the glue that turns an issue into a PR lives ONLY in `.github/` + shell, NEVER the binary or `engine/`, and keeps a **split-privilege token boundary** (the agent job holds NO GitHub write token; the publish job runs NO agent code, applies the patch as DATA). See `docs/adr/0028-mecatequi.md`. `cmd/mecak8s/` — storage-free k8s-native agent (ADR 0048), a thin peer of mecated that composes `app.Build` with k8s-native defaults (Redis store + k8s lease + drain gate); no PVC, no local state — state is a managed service (Redis + k8s API server). The four real-provider mains share credential/base-URL wiring via `internal/cliconfig`.
 - `cmd/mecatui/` — optional gRPC **client** TUI; by default hosts a `mecated` in-process over a UNIX socket. `ui`/`theme`/`client` import no `engine/...` or `internal/...` and no proto directly — they render from relayed proto `Event`s. See `docs/tui.md`.
+- `studio/` — the web client: a Next.js **Node module**, never a Go module (not in `go.work`, the layering DAG, depguard, or api-compat). A CLIENT like mecatui, consuming the daemon EXCLUSIVELY through the TypeScript SDK (`@stacklok-oss/mecatl-sdk`, `sdk/typescript`, a `file:` dependency built before Studio installs) pointed at Studio's own same-origin `/api/mecatl` proxy, which holds the credential and injects auth ONLY (placement is server-owned, ADR 0291 — no workspace injection); controller calls (`/api/mecatl-control`) stay Studio-owned; daemon-only (an unreachable daemon renders offline, never demo data). Commands run via `task studio:*` (npm underneath). **A breaking HTTP/SSE wire change owes a Studio update in the same PR.** See ADR 0347/0348 + `studio/CLAUDE.md`.
 - `perf/` — the OFFLINE scenario perf harness (perf-tracking Phase 2, `task perf:scenarios`, NOT part of `task test`): `perf/kpi` (stdlib-ONLY KPI capture — `ScenarioResult`/`Capture`/`/proc` RSS sampler; never imports `engine/...` or `internal/...`) + `perf/scenarios` (external-test `testing.B` whole-loop benchmarks over `engine/...` + `engine/adapter/*`, never `internal/...`). The TUI scrollback render bench lives in `cmd/mecatui/ui/scrollback_bench_test.go` (perf/kpi imported in the `_test` file only). `perf/cmd/perfconvert` (Phase 3; stdlib + `perf/kpi` only) reshapes the scenario JSON into the two github-action-benchmark suites the CI gate consumes; `perf/cmd/benchtrend` (stdlib only, tested, FAIL-CLOSED) median-aggregates Go benchmark samples and compacts the commit-keyed dashboard history; and `perf/cmd/allocsgate` (stdlib only, tested, FAIL-CLOSED) is the deterministic allocs/op gate over `task bench` — the gate DECISION (benchstat is the local human A/B tool only, never the CI gate); the gate is `.github/workflows/perf.yml` (split: allocsgate over `task bench` + github-action-benchmark over the scenarios; PR fails-but-never-pushes, main pushes the `gh-pages` trend store). See `docs/adr/0019-perf-tracking.md`.
 
 ## The layering rule (the thing to get right)

Taskfile.yml

@@ -22,6 +22,9 @@ includes:
   site:
     taskfile: website/Taskfile.yml
     dir: website
+  studio:
+    taskfile: studio/Taskfile.yml
+    dir: studio
   sdk:
     taskfile: sdk/typescript/Taskfile.yml
     dir: sdk/typescript

cmd/mecated/helpmeta.go

@@ -201,6 +201,7 @@ var flagMetaByFlag = map[string]flagMeta{
 
 	// ── Storage (both) ───────────────────────────────────────────────────
 	"store-dir":                      {group: groupStorage, common: true, acp: acpInclude},
+	"local-storage-management":       {group: groupStorage, common: false, acp: acpExclude},
 	"memory-dir":                     {group: groupStorage, common: true, acp: acpInclude},
 	"memory-consolidate-interval":    {group: groupStorage, common: false, acp: acpInclude},
 	"child-retention":                {group: groupStorage, common: false, acp: acpInclude},

cmd/mecated/main.go

@@ -368,6 +368,11 @@ type config struct {
 	// deployment where clients drive runs but never answer permission prompts — it
 	// is what makes --subagent-ask-reviewer actually engage.
 	headless bool
+	// localStorageManagement grants the private single-user storage
+	// management surface (health / clean-up) to unauthenticated-principal
+	// callers — the embedded-server grant, for a loopback daemon a trusted
+	// supervisor (Studio's controller) spawns. Refused with OIDC ownership.
+	localStorageManagement bool
 
 	// Skills self-improvement loop (opt-in): when skillsDraftDir is non-empty the
 	// writable SkillDraft tool is registered, writing model-authored candidate
@@ -1322,6 +1327,7 @@ func appConfig(cfg config, sink port.EventSink, recorder port.ToolCallRecorder,
 		// Headless is explicit deployment identity. The posture ladder raises
 		// workspace trust only when this is false.
 		Headless:                         cfg.headless,
+		LocalStorageManagement:           cfg.localStorageManagement,
 		Sink:                             sink,
 		ToolCallRecorder:                 recorder,
 		MetricsRoleScoper:                roleScoper,
@@ -1793,6 +1799,7 @@ func parseFlagsModeOut(mode commandMode, argv []string, out io.Writer) (*flag.Fl
 	fs.IntVar(&cfg.subagentAskReviewerMaxDenies, "subagent-ask-reviewer-max-denies", agent.DefaultAskReviewMaxDenies, "circuit breaker for --subagent-ask-reviewer: after this many CONSECUTIVE non-allow reviewer outcomes (denies/errors/timeouts) in one run, further asks skip the reviewer and fall through to the plain auto-deny; an allow resets the count. <=0 uses the default (3)")
 	fs.StringVar(&cfg.subagentAskReviewerPolicyFile, "subagent-ask-reviewer-policy", "", "path to a TRUSTED policy rubric file for --subagent-ask-reviewer; its CONTENT replaces the built-in read-only/verification rubric the reviewer applies. Empty keeps the built-in rubric. Read once at startup; an unreadable file FAILS STARTUP")
 	fs.BoolVar(&cfg.subagentModelRouter, "subagent-model-router", false, "Semantic model router KILL-SWITCH (ADR 0042, superseding 0031's enable model): the router is ENABLED by configuring a `models.router:` category taxonomy in the OPERATOR-TIER user-global settings.yaml (the guardrails-parity enable model — configure = enable), NOT by this flag. Pass --subagent-model-router=false to force the router OFF despite a taxonomy (the kill-switch; also expressible as models.router.disabled: true in YAML). When ENABLED, a tiny one-turn classifier (on the `router` model slot) reads each plain Subagent delegation's task prompt + the operator taxonomy and picks the child's model BEFORE the child is minted (decide-once, same-provider; only for a plain delegation — no per-call model/agent, no fork/resume). FAIL-SOFT: any classifier failure, unknown category, or the per-run breaker (3 consecutive misses) inherits the default model")
+	fs.BoolVar(&cfg.localStorageManagement, "local-storage-management", false, "grant the storage management surface (GET /v1/storage/health, the clean-up plan/apply routes; advertised as capabilities.storage_health / storage_cleanup) to callers with no OIDC principal — the private single-user grant the embedded mecatui server has, for a LOOPBACK daemon a trusted supervisor spawns (Studio's controller passes it). Refused at startup together with --auth-oidc ownership enforcement; storage_management.principals in settings.yaml is the multi-tenant alternative. DEFAULT off")
 	fs.BoolVar(&cfg.headless, "headless", false, "run NON-interactive: declare that clients drive sessions but never answer permission prompts (autonomous / CI deployments). A child subagent/member/branch permission ask is then NOT surfaced to the client (nobody would answer it — it would park until run-end) but resolved by the auto-deny path / the opt-in --subagent-ask-reviewer. DEFAULT off: a normal mecated serving an interactive client (mecatui, an IDE) surfaces asks for a human. Setting --subagent-ask-reviewer WITHOUT --headless has no effect (asks surface to the client instead) — a startup WARNING says so")
 	fs.BoolVar(&cfg.planModeAutoApprove, "plan-mode-auto-approve", false, "OPT-IN autonomous plan approval (issue #206 Wave 6a): when a plan-mode run ends HEADLESS (no human to review), auto-approve the plan via ApprovePlan(ModeDefault) instead of leaving it parked. This is a deliberate autonomous-approval capability — an operator deployment decision, NEVER load-bearing for safety. It does NOT fire when interactive (a human can approve), NOT in non-plan modes, NOT for non-plan asks. DEFAULT off: a headless plan ask is auto-denied. Requires --headless to engage (an interactive deployment surfaces the plan to the human). A LOUD diagnostic (plan_mode_auto_approve: ON (NO HUMAN REVIEW)) is emitted at startup")
 	fs.StringVar(&cfg.guardrailsModel, "guardrails-model", "", "GUARDRAILS (issue #27): model id or --model-alias of a tool-less checker that inspects OUTBOUND tool-call args (PreToolUse, data exfil) and INBOUND tool results (PostToolUse, prompt injection) and enforces a verdict per the operator-tier `guardrails:` rule list. Configuring a model here OR via a bound `guardrail` model slot (--model-slot guardrail=… / models.slots.guardrail) ENABLES guardrails (configure = enable, the router-parity model of ADR 0042; see ADR 0046) — empty + no slot disables them. A value that does not resolve to a usable model id FAILS STARTUP. A bound `guardrail` slot SUPERSEDES this flag's model when both are set (this flag then supplies only the enable gate). The RULE LIST + cost knobs live in the user-global settings.yaml `guardrails:` subtree (operator-tier ONLY — a project repo cannot configure or weaken a checker); --guardrails-model overrides the YAML model")