feat(admin): apix-admin UI at admin.api-index.org

Internal maintainer dashboard: global stats, sandbox list with tier-filter and pagination, sandbox drill-down with D3 world map, tier-promotion form. API-key auth via HttpOnly cookie. Port 8084, rolling a/b deploy alongside the existing service pairs. - apix-common: AdminSandboxSummary, AdminSandboxListResponse, AdminStatsResponse DTOs - apix-registry: AdminResource (4 endpoints), SandboxService.listAllSandboxes + getGlobalStats - apix-registry: SandboxResource GET /{uuid}/dashboard endpoint (was missing — fixes portal 500) - apix-portal: RegistryClient path corrected to /dashboard - apix-admin: new Quarkus module — auth filter, registry REST client, 3 resources, 6 Qute templates, admin.js - infra: Dockerfile.admin, docker-compose admin-a/b services, Caddyfile admin.api-index.org block - scripts: deploy-bluegreen.sh extended for admin-a/b Co-Authored-By: Mira Rehfeld <noreply@anthropic.com>
fix(sandbox): two sandbox bugs blocking Peter Steinberger beta test
2026-05-16 21:18:48 +02:00 · 2026-05-16 13:20:37 +02:00 · 2026-05-15 20:11:18 +02:00
44 changed files with 1527 additions and 124 deletions
@@ -35,3 +35,9 @@ REGISTRY_BASE_URL=http://localhost:8180
 # ── Logging ───────────────────────────────────────────────────────────────────
 # DEBUG in dev; INFO in prod
 LOG_LEVEL=DEBUG
+
+# ── Observability ─────────────────────────────────────────────────────────────
+# Grafana admin password. Change in any non-local environment.
+GRAFANA_ADMIN_PASSWORD=admin
+# Set to your public domain in production, e.g. https://grafana.api-index.org
+GRAFANA_ROOT_URL=http://localhost:3000
@@ -7,6 +7,9 @@ logs/
 # Local environment — never commit real credentials
 .env

+# Bunny.net pull zone ID written by setup-bunnynet.sh
+.bunnynet-pull-zone-id
+
 # Maven build output
 target/
 **/target/
@@ -22,3 +25,4 @@ sanctions-cache/
 # OS
 .DS_Store
 Thumbs.db
+/.allure/
@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+                             https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>org.botstandards</groupId>
+        <artifactId>apix-parent</artifactId>
+        <version>${revision}</version>
+    </parent>
+
+    <artifactId>apix-admin</artifactId>
+    <name>APIX :: Admin</name>
+    <description>Internal maintainer UI at admin.api-index.org. API-key auth, no username/password. Port 8084.</description>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.botstandards</groupId>
+            <artifactId>apix-common</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-rest</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-rest-qute</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-rest-client</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-rest-client-jackson</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-smallrye-health</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-junit5</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>${quarkus.platform.group-id}</groupId>
+                <artifactId>quarkus-maven-plugin</artifactId>
+                <extensions>true</extensions>
+                <executions>
+                    <execution>
+                        <goals>
+                            <goal>build</goal>
+                            <goal>generate-code</goal>
+                            <goal>generate-code-tests</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+</project>
@@ -0,0 +1,46 @@
+package org.botstandards.apix.admin.client;
+
+import jakarta.ws.rs.*;
+import jakarta.ws.rs.core.MediaType;
+import org.botstandards.apix.common.*;
+import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
+
+import java.util.Map;
+
+@RegisterRestClient(configKey = "registry")
+@Produces(MediaType.APPLICATION_JSON)
+@Consumes(MediaType.APPLICATION_JSON)
+public interface AdminRegistryClient {
+
+    @GET
+    @Path("/admin/sandboxes")
+    AdminSandboxListResponse listSandboxes(
+            @HeaderParam("X-Admin-Key") String adminKey,
+            @QueryParam("page") int page,
+            @QueryParam("size") int size,
+            @QueryParam("tier") String tier);
+
+    @GET
+    @Path("/admin/stats")
+    AdminStatsResponse stats(@HeaderParam("X-Admin-Key") String adminKey);
+
+    @GET
+    @Path("/admin/sandboxes/{uuid}")
+    SandboxDashboardResponse sandboxDetail(
+            @HeaderParam("X-Admin-Key") String adminKey,
+            @PathParam("uuid") String uuid);
+
+    @PATCH
+    @Path("/admin/sandboxes/{uuid}/tier")
+    Map<String, Object> promoteTier(
+            @HeaderParam("X-Admin-Key") String adminKey,
+            @PathParam("uuid") String uuid,
+            Map<String, String> body);
+
+    @PATCH
+    @Path("/sandbox/admin/{uuid}/tier")
+    Map<String, Object> promoteTierLegacy(
+            @HeaderParam("X-Admin-Key") String adminKey,
+            @PathParam("uuid") String uuid,
+            Map<String, String> body);
+}
@@ -0,0 +1,41 @@
+package org.botstandards.apix.admin.filter;
+
+import jakarta.ws.rs.container.ContainerRequestContext;
+import jakarta.ws.rs.container.ContainerRequestFilter;
+import jakarta.ws.rs.core.Cookie;
+import jakarta.ws.rs.core.Response;
+import jakarta.ws.rs.core.UriInfo;
+import jakarta.ws.rs.ext.Provider;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+
+import java.io.IOException;
+import java.net.URI;
+
+@Provider
+public class AdminAuthFilter implements ContainerRequestFilter {
+
+    @ConfigProperty(name = "apix.admin.key")
+    String adminKey;
+
+    @ConfigProperty(name = "apix.admin.cookie-name")
+    String cookieName;
+
+    private static final java.util.Set<String> PUBLIC_PATHS = java.util.Set.of(
+            "/login", "/q/health", "/q/health/live", "/q/health/ready"
+    );
+
+    @Override
+    public void filter(ContainerRequestContext ctx) throws IOException {
+        UriInfo uri = ctx.getUriInfo();
+        String path = "/" + uri.getPath();
+
+        for (String pub : PUBLIC_PATHS) {
+            if (path.startsWith(pub)) return;
+        }
+
+        Cookie session = ctx.getCookies().get(cookieName);
+        if (session != null && adminKey.equals(session.getValue())) return;
+
+        ctx.abortWith(Response.seeOther(URI.create("/login")).build());
+    }
+}
@@ -0,0 +1,62 @@
+package org.botstandards.apix.admin.resource;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.quarkus.qute.CheckedTemplate;
+import io.quarkus.qute.TemplateInstance;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.*;
+import jakarta.ws.rs.core.*;
+import org.botstandards.apix.common.AdminStatsResponse;
+import org.botstandards.apix.common.SandboxDashboardResponse;
+import org.botstandards.apix.admin.client.AdminRegistryClient;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.eclipse.microprofile.rest.client.inject.RestClient;
+import org.jboss.logging.Logger;
+
+@Path("/")
+@Produces(MediaType.TEXT_HTML)
+public class DashboardResource {
+
+    private static final Logger LOG = Logger.getLogger(DashboardResource.class);
+
+    @Inject @RestClient
+    AdminRegistryClient registry;
+
+    @Inject
+    ObjectMapper mapper;
+
+    @ConfigProperty(name = "apix.admin.key")
+    String adminKey;
+
+    @CheckedTemplate
+    static class Templates {
+        static native TemplateInstance global(AdminStatsResponse stats, String statsJson);
+        static native TemplateInstance sandbox(SandboxDashboardResponse dashboard, String dataJson);
+        static native TemplateInstance error(String message);
+    }
+
+    @GET
+    public TemplateInstance globalDashboard() {
+        try {
+            AdminStatsResponse stats = registry.stats(adminKey);
+            String json = mapper.writeValueAsString(stats).replace("</", "<\\/");
+            return Templates.global(stats, json);
+        } catch (Exception e) {
+            LOG.errorf(e, "Failed to load global stats");
+            return Templates.error("Could not load stats from registry");
+        }
+    }
+
+    @GET
+    @Path("/sandbox/{uuid}")
+    public TemplateInstance sandboxDashboard(@PathParam("uuid") String uuid) {
+        try {
+            SandboxDashboardResponse dashboard = registry.sandboxDetail(adminKey, uuid);
+            String json = mapper.writeValueAsString(dashboard).replace("</", "<\\/");
+            return Templates.sandbox(dashboard, json);
+        } catch (Exception e) {
+            LOG.errorf(e, "Failed to load sandbox %s", uuid);
+            return Templates.error("Could not load sandbox " + uuid);
+        }
+    }
+}
@@ -0,0 +1,59 @@
+package org.botstandards.apix.admin.resource;
+
+import io.quarkus.qute.CheckedTemplate;
+import io.quarkus.qute.TemplateInstance;
+import jakarta.ws.rs.*;
+import jakarta.ws.rs.core.*;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+
+import java.net.URI;
+
+@Path("/login")
+public class LoginResource {
+
+    @ConfigProperty(name = "apix.admin.key")
+    String adminKey;
+
+    @ConfigProperty(name = "apix.admin.cookie-name")
+    String cookieName;
+
+    @CheckedTemplate
+    static class Templates {
+        static native TemplateInstance login(boolean invalid);
+    }
+
+    @GET
+    @Produces(MediaType.TEXT_HTML)
+    public TemplateInstance loginPage() {
+        return Templates.login(false);
+    }
+
+    @POST
+    @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
+    public Response authenticate(@FormParam("key") String key) {
+        if (key == null || !adminKey.equals(key.strip())) {
+            return Response.ok(Templates.login(true).render())
+                    .type(MediaType.TEXT_HTML)
+                    .build();
+        }
+        NewCookie session = new NewCookie.Builder(cookieName)
+                .value(adminKey)
+                .path("/")
+                .httpOnly(true)
+                .sameSite(NewCookie.SameSite.STRICT)
+                .maxAge(28800) // 8 hours
+                .build();
+        return Response.seeOther(URI.create("/")).cookie(session).build();
+    }
+
+    @GET
+    @Path("/logout")
+    public Response logout() {
+        NewCookie expired = new NewCookie.Builder(cookieName)
+                .value("")
+                .path("/")
+                .maxAge(0)
+                .build();
+        return Response.seeOther(URI.create("/login")).cookie(expired).build();
+    }
+}
@@ -0,0 +1,61 @@
+package org.botstandards.apix.admin.resource;
+
+import io.quarkus.qute.CheckedTemplate;
+import io.quarkus.qute.TemplateInstance;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.*;
+import jakarta.ws.rs.core.*;
+import org.botstandards.apix.common.AdminSandboxListResponse;
+import org.botstandards.apix.admin.client.AdminRegistryClient;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.eclipse.microprofile.rest.client.inject.RestClient;
+import org.jboss.logging.Logger;
+
+import java.net.URI;
+import java.util.Map;
+
+@Path("/sandboxes")
+@Produces(MediaType.TEXT_HTML)
+public class SandboxListResource {
+
+    private static final Logger LOG = Logger.getLogger(SandboxListResource.class);
+
+    @Inject @RestClient
+    AdminRegistryClient registry;
+
+    @ConfigProperty(name = "apix.admin.key")
+    String adminKey;
+
+    @CheckedTemplate
+    static class Templates {
+        static native TemplateInstance list(AdminSandboxListResponse result, int page, int size, String tier);
+        static native TemplateInstance error(String message);
+    }
+
+    @GET
+    public TemplateInstance list(
+            @QueryParam("page") @DefaultValue("0") int page,
+            @QueryParam("size") @DefaultValue("50") int size,
+            @QueryParam("tier") @DefaultValue("") String tier) {
+        try {
+            String tierParam = tier.isBlank() ? null : tier;
+            AdminSandboxListResponse result = registry.listSandboxes(adminKey, page, size, tierParam);
+            return Templates.list(result, page, size, tier);
+        } catch (Exception e) {
+            LOG.errorf(e, "Failed to load sandbox list");
+            return Templates.error("Could not load sandbox list");
+        }
+    }
+
+    @POST
+    @Path("/{uuid}/promote")
+    @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
+    public Response promote(@PathParam("uuid") String uuid, @FormParam("tier") String tier) {
+        try {
+            registry.promoteTier(adminKey, uuid, Map.of("tier", tier.toUpperCase()));
+        } catch (Exception e) {
+            LOG.errorf(e, "Failed to promote sandbox %s to %s", uuid, tier);
+        }
+        return Response.seeOther(URI.create("/sandbox/" + uuid)).build();
+    }
+}
@@ -0,0 +1,128 @@
+/* admin.js — shared between global dashboard and sandbox drill-down */
+(function () {
+  // ── Relative expiry display ─────────────────────────────────────────────────
+  const expiresRaw = document.getElementById('expires-raw');
+  const expiresVal = document.getElementById('expires-val');
+  if (expiresRaw && expiresVal) {
+    const d = new Date(expiresRaw.textContent.trim());
+    const days = Math.round((d - Date.now()) / 86400000);
+    expiresVal.textContent = days < 0 ? `expired ${-days}d ago` : `${days}d left`;
+    expiresVal.style.color = days < 7 ? '#f85149' : days < 30 ? '#e3b341' : '#3fb950';
+  }
+
+  // ── Request count formatting ────────────────────────────────────────────────
+  const reqFmt = document.getElementById('req-fmt');
+  if (reqFmt && window.__D) {
+    const n = __D.totalRequests || 0;
+    reqFmt.textContent = n >= 1e6 ? (n / 1e6).toFixed(1) + 'M'
+                        : n >= 1e3 ? (n / 1e3).toFixed(1) + 'k'
+                        : n.toString();
+  }
+
+  // ── Timestamp ───────────────────────────────────────────────────────────────
+  const ts = document.getElementById('refresh-ts');
+  if (ts) ts.textContent = 'loaded ' + new Date().toLocaleTimeString();
+
+  // ── D3 world map ────────────────────────────────────────────────────────────
+  const mapEl = document.getElementById('world-map');
+  if (!mapEl || typeof d3 === 'undefined') return;
+
+  const W = mapEl.parentElement.clientWidth || 960;
+  const H = Math.round(W * 0.42);
+  mapEl.setAttribute('viewBox', `0 0 ${W} ${H}`);
+  mapEl.style.height = H + 'px';
+
+  const projection = d3.geoNaturalEarth1()
+      .scale(W / 6.3)
+      .translate([W / 2, H / 2]);
+  const path = d3.geoPath().projection(projection);
+  const svg = d3.select(mapEl);
+
+  const TIER_COLORS = {
+    FREE: '#484f58', STANDARD: '#388bfd', PROFESSIONAL: '#a371f7',
+    COMMUNITY: '#3fb950', FOUNDER: '#e3b341', DEMO: '#58a6ff'
+  };
+
+  fetch('https://cdn.jsdelivr.net/npm/world-atlas@2/countries-110m.json')
+    .then(r => r.json())
+    .then(world => {
+      svg.append('g').selectAll('path')
+          .data(topojson.feature(world, world.objects.countries).features)
+          .join('path')
+          .attr('d', path)
+          .attr('fill', '#0d2033')
+          .attr('stroke', '#1c2d3f')
+          .attr('stroke-width', 0.4);
+
+      // Points: from stats (global) or sandbox (drill-down)
+      let points = [];
+      if (window.__D) {
+        if (__D.registrarPoints) {
+          // global dashboard
+          points = __D.registrarPoints.map(p => ({
+            lat: p.lat, lon: p.lon, label: p.name, tier: p.tier, type: 'registrar'
+          }));
+        } else if (__D.registrarLat != null) {
+          // sandbox drill-down — registrar star
+          points.push({ lat: __D.registrarLat, lon: __D.registrarLon, label: __D.name, tier: __D.tier, type: 'registrar' });
+          // agent visits
+          (__D.recentVisits || []).forEach(v => {
+            points.push({ lat: v.lat, lon: v.lon, type: 'agent' });
+          });
+        }
+      }
+
+      // Agent blinks
+      svg.append('g').selectAll('circle.agent')
+          .data(points.filter(p => p.type === 'agent'))
+          .join('circle')
+          .attr('class', 'agent-blink')
+          .attr('cx', p => projection([p.lon, p.lat])?.[0])
+          .attr('cy', p => projection([p.lon, p.lat])?.[1])
+          .attr('r', 3)
+          .style('animation-delay', (_, i) => `${(i * 0.4) % 2.8}s`);
+
+      // Registrar stars
+      svg.append('g').selectAll('text.star')
+          .data(points.filter(p => p.type === 'registrar'))
+          .join('text')
+          .attr('class', 'registrar-star')
+          .attr('x', p => projection([p.lon, p.lat])?.[0])
+          .attr('y', p => projection([p.lon, p.lat])?.[1])
+          .attr('fill', p => TIER_COLORS[p.tier] || '#ffd700')
+          .text('★')
+          .append('title').text(p => `${p.label} (${p.tier})`);
+    });
+
+  // ── Tier donut (global dashboard only) ─────────────────────────────────────
+  const donutEl = document.getElementById('donut');
+  const legendEl = document.getElementById('tier-legend');
+  if (donutEl && window.__D && __D.byTier) {
+    const data = Object.entries(__D.byTier).map(([tier, count]) => ({ tier, count }));
+    const total = data.reduce((s, d) => s + d.count, 0);
+    const cx = 60, cy = 60, r = 46, ri = 28;
+    const svgD = d3.select(donutEl);
+    const pie = d3.pie().value(d => d.count).sort(null);
+    const arc = d3.arc().innerRadius(ri).outerRadius(r);
+
+    svgD.append('g').attr('transform', `translate(${cx},${cy})`)
+        .selectAll('path').data(pie(data)).join('path')
+        .attr('d', arc)
+        .attr('fill', d => TIER_COLORS[d.data.tier] || '#484f58')
+        .attr('stroke', '#0d1117').attr('stroke-width', 1.5)
+        .append('title').text(d => `${d.data.tier}: ${d.data.count}`);
+
+    svgD.append('text').attr('x', cx).attr('y', cy + 5)
+        .attr('text-anchor', 'middle').attr('dominant-baseline', 'middle')
+        .attr('fill', '#e6edf3').attr('font-size', '18').attr('font-weight', '700')
+        .text(total);
+
+    data.forEach(d => {
+      const li = document.createElement('li');
+      li.innerHTML = `<span class="tier-dot" style="background:${TIER_COLORS[d.tier] || '#484f58'}"></span>
+        <span style="color:#8b949e">${d.tier}</span>
+        <span style="margin-left:auto;color:#e6edf3">${d.count}</span>`;
+      legendEl.appendChild(li);
+    });
+  }
+})();
@@ -0,0 +1,14 @@
+quarkus.http.port=8084
+quarkus.smallrye-health.root-path=/q/health
+quarkus.log.level=${LOG_LEVEL:INFO}
+
+# Registry REST client — all admin API calls go through here
+quarkus.rest-client.registry.url=${APIX_REGISTRY_URL:http://registry:8180}
+quarkus.rest-client.registry.connect-timeout=5000
+quarkus.rest-client.registry.read-timeout=15000
+
+# Admin API key — must match APIX_API_KEY on the registry
+apix.admin.key=${APIX_API_KEY:dev-insecure-key-change-in-prod}
+
+# Session cookie name
+apix.admin.cookie-name=apix_admin_session
@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>APIX Admin — Error</title>
+<style>
+* { box-sizing: border-box; margin: 0; padding: 0; }
+body { background: #0d1117; color: #c9d1d9; font-family: 'SF Mono','Consolas',monospace; display: flex; align-items: center; justify-content: center; min-height: 100vh; }
+.card { text-align: center; }
+.label { font-size: 0.75rem; color: #f85149; letter-spacing: 0.1em; margin-bottom: 0.5rem; }
+.msg { color: #8b949e; font-size: 0.9rem; margin-bottom: 1.5rem; }
+a { color: #58a6ff; }
+</style>
+</head>
+<body>
+<div class="card">
+  <div class="label">ERROR</div>
+  <div class="msg">{message}</div>
+  <a href="/">← Back to dashboard</a>
+</div>
+</body>
+</html>
@@ -0,0 +1,111 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>APIX Admin — Dashboard</title>
+<style>
+* { box-sizing: border-box; margin: 0; padding: 0; }
+body { background: #0d1117; color: #c9d1d9; font-family: 'SF Mono','Consolas','Fira Code',monospace; font-size: 14px; }
+a { color: #58a6ff; text-decoration: none; }
+a:hover { text-decoration: underline; }
+nav {
+  display: flex; align-items: center; gap: 1.5rem;
+  padding: 0.75rem 1.5rem; border-bottom: 1px solid #21262d;
+  background: #161b22;
+}
+.nav-logo { color: #8b949e; font-size: 0.75rem; }
+.nav-logo span { color: #e6edf3; font-weight: 600; font-size: 0.9rem; }
+.nav-link { font-size: 0.8rem; color: #8b949e; }
+.nav-link.active, .nav-link:hover { color: #e6edf3; }
+.nav-right { margin-left: auto; }
+
+.stats-grid {
+  display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+  gap: 1px; background: #21262d; border-bottom: 1px solid #21262d;
+}
+.stat { background: #0d1117; padding: 1.2rem 1.5rem; }
+.stat-label { font-size: 0.65rem; color: #484f58; text-transform: uppercase; letter-spacing: 0.06em; margin-bottom: 0.3rem; }
+.stat-value { font-size: 1.8rem; color: #e6edf3; font-weight: 700; }
+.stat-sub { font-size: 0.7rem; color: #484f58; margin-top: 0.2rem; }
+
+.layout { display: grid; grid-template-columns: 1fr 320px; gap: 1px; background: #21262d; }
+.panel { background: #0d1117; padding: 1.5rem; }
+.panel-title { font-size: 0.7rem; color: #484f58; text-transform: uppercase; letter-spacing: 0.06em; margin-bottom: 1rem; }
+
+#map-wrap { background: #060d18; border-bottom: 1px solid #21262d; }
+#world-map { display: block; width: 100%; }
+
+.donut-wrap { display: flex; align-items: center; gap: 1.5rem; }
+#donut { width: 120px; height: 120px; flex-shrink: 0; }
+.tier-list { list-style: none; }
+.tier-list li { display: flex; align-items: center; gap: 0.5rem; font-size: 0.8rem; margin-bottom: 0.4rem; }
+.tier-dot { width: 10px; height: 10px; border-radius: 50%; flex-shrink: 0; }
+
+.footer { padding: 0.75rem 1.5rem; border-top: 1px solid #21262d; font-size: 0.7rem; color: #484f58; display: flex; justify-content: space-between; }
+
+@keyframes star-glow {
+  0%,100% { filter: drop-shadow(0 0 3px #ffd700) drop-shadow(0 0 6px #ffd70066); }
+  50% { filter: drop-shadow(0 0 8px #ffd700) drop-shadow(0 0 18px #ffd700aa); }
+}
+.registrar-star { font-size: 12px; fill: #ffd700; dominant-baseline: central; text-anchor: middle; animation: star-glow 2.4s ease-in-out infinite; cursor: default; }
+</style>
+</head>
+<body>
+<nav>
+  <div class="nav-logo">APIX · <span>Admin</span></div>
+  <a class="nav-link active" href="/">Dashboard</a>
+  <a class="nav-link" href="/sandboxes">Sandboxes</a>
+  <div class="nav-right"><a class="nav-link" href="/login/logout">Sign out</a></div>
+</nav>
+
+<div class="stats-grid">
+  <div class="stat">
+    <div class="stat-label">Total Sandboxes</div>
+    <div class="stat-value">{stats.totalSandboxes}</div>
+    <div class="stat-sub">{stats.activeSandboxes} active · {stats.expiredSandboxes} expired</div>
+  </div>
+  <div class="stat">
+    <div class="stat-label">Services registered</div>
+    <div class="stat-value">{stats.totalServices}</div>
+    <div class="stat-sub">across all sandboxes</div>
+  </div>
+  <div class="stat">
+    <div class="stat-label">Total Requests</div>
+    <div class="stat-value" id="req-fmt">—</div>
+    <div class="stat-sub">cumulative</div>
+  </div>
+</div>
+
+<div id="map-wrap"><svg id="world-map"></svg></div>
+
+<div class="layout">
+  <div class="panel">
+    <div class="panel-title">Tier distribution</div>
+    <div class="donut-wrap">
+      <svg id="donut" viewBox="0 0 120 120"></svg>
+      <ul class="tier-list" id="tier-legend"></ul>
+    </div>
+  </div>
+  <div class="panel">
+    <div class="panel-title">Quick links</div>
+    <p style="font-size:0.8rem;color:#8b949e;line-height:1.8">
+      <a href="/sandboxes">All sandboxes →</a><br>
+      <a href="/sandboxes?tier=COMMUNITY">COMMUNITY tier →</a><br>
+      <a href="/sandboxes?tier=FREE">FREE tier →</a><br>
+      <a href="/sandboxes?tier=FOUNDER">FOUNDER tier →</a>
+    </p>
+  </div>
+</div>
+
+<div class="footer">
+  <span>APIX Admin · internal</span>
+  <span id="refresh-ts"></span>
+</div>
+
+<script>var __D = {statsJson.raw};</script>
+<script src="https://cdn.jsdelivr.net/npm/d3@7/dist/d3.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/topojson-client@3/dist/topojson-client.min.js"></script>
+<script src="/admin.js"></script>
+</body>
+</html>
@@ -0,0 +1,136 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{dashboard.name} · APIX Admin</title>
+<style>
+* { box-sizing: border-box; margin: 0; padding: 0; }
+body { background: #0d1117; color: #c9d1d9; font-family: 'SF Mono','Consolas','Fira Code',monospace; font-size: 14px; }
+a { color: #58a6ff; text-decoration: none; }
+a:hover { text-decoration: underline; }
+nav {
+  display: flex; align-items: center; gap: 1.5rem;
+  padding: 0.75rem 1.5rem; border-bottom: 1px solid #21262d; background: #161b22;
+}
+.nav-logo { color: #8b949e; font-size: 0.75rem; }
+.nav-logo span { color: #e6edf3; font-weight: 600; font-size: 0.9rem; }
+.nav-link { font-size: 0.8rem; color: #8b949e; }
+.nav-link:hover { color: #e6edf3; }
+.nav-right { margin-left: auto; }
+
+.header { padding: 1rem 1.5rem; border-bottom: 1px solid #21262d; display: flex; align-items: center; gap: 1rem; }
+.sb-name { font-size: 1rem; color: #e6edf3; font-weight: 600; }
+.tier-badge {
+  background: #161b22; border: 1px solid #30363d;
+  color: #8b949e; padding: 0.1rem 0.5rem; border-radius: 12px;
+  font-size: 0.7rem; letter-spacing: 0.05em;
+}
+.sb-id { font-size: 0.75rem; color: #484f58; }
+
+.stats-grid {
+  display: grid; grid-template-columns: repeat(auto-fit, minmax(200px,1fr));
+  gap: 1px; background: #21262d; border-bottom: 1px solid #21262d;
+}
+.stat { background: #0d1117; padding: 1rem 1.5rem; }
+.stat-label { font-size: 0.65rem; color: #484f58; text-transform: uppercase; letter-spacing: 0.06em; margin-bottom: 0.3rem; }
+.stat-value { font-size: 1.4rem; color: #e6edf3; font-weight: 600; }
+.stat-sub { font-size: 0.7rem; color: #484f58; margin-top: 0.2rem; }
+
+#map-wrap { background: #060d18; }
+#world-map { display: block; width: 100%; }
+
+.actions { padding: 1.5rem; border-top: 1px solid #21262d; display: flex; gap: 1rem; flex-wrap: wrap; }
+.actions-title { width: 100%; font-size: 0.7rem; color: #484f58; text-transform: uppercase; letter-spacing: 0.06em; margin-bottom: 0.5rem; }
+form { display: flex; gap: 0.5rem; align-items: center; }
+select, button {
+  background: #161b22; border: 1px solid #30363d; color: #c9d1d9;
+  font-family: inherit; font-size: 0.8rem;
+  border-radius: 4px; padding: 0.4rem 0.7rem; cursor: pointer;
+}
+select:focus, button:focus { outline: none; border-color: #58a6ff; }
+button.promote { background: #238636; border-color: #238636; color: #fff; font-weight: 600; }
+button.promote:hover { background: #2ea043; }
+
+.footer { padding: 0.75rem 1.5rem; border-top: 1px solid #21262d; font-size: 0.7rem; color: #484f58; }
+
+@keyframes star-glow {
+  0%,100% { filter: drop-shadow(0 0 3px #ffd700) drop-shadow(0 0 6px #ffd70066); }
+  50% { filter: drop-shadow(0 0 8px #ffd700) drop-shadow(0 0 18px #ffd700aa); }
+}
+.registrar-star { font-size: 14px; fill: #ffd700; dominant-baseline: central; text-anchor: middle; animation: star-glow 2.4s ease-in-out infinite; }
+@keyframes blink-pulse {
+  0% { opacity:0; r:2; } 25% { opacity:0.9; r:5; } 65% { opacity:0.4; r:4; } 100% { opacity:0; r:2; }
+}
+.agent-blink { fill: #3d8bfd; opacity:0; animation: blink-pulse 2.8s ease-in-out infinite; }
+</style>
+</head>
+<body>
+<nav>
+  <div class="nav-logo">APIX · <span>Admin</span></div>
+  <a class="nav-link" href="/">Dashboard</a>
+  <a class="nav-link" href="/sandboxes">Sandboxes</a>
+  <div class="nav-right"><a class="nav-link" href="/login/logout">Sign out</a></div>
+</nav>
+
+<div class="header">
+  <span class="sb-name">{dashboard.name}</span>
+  <span class="tier-badge">{dashboard.tier}</span>
+  <span class="sb-id">{dashboard.sandboxId}</span>
+</div>
+
+<div class="stats-grid">
+  <div class="stat">
+    <div class="stat-label">Services</div>
+    <div class="stat-value">{#if dashboard.usage.get('SERVICE_REGISTERED') != null}{dashboard.usage.get('SERVICE_REGISTERED')}{#else}0{/if}</div>
+    <div class="stat-sub">of {#if dashboard.maxServices != null}{dashboard.maxServices}{#else}∞{/if} allowed</div>
+  </div>
+  <div class="stat">
+    <div class="stat-label">Searches</div>
+    <div class="stat-value">{#if dashboard.usage.get('SERVICE_SEARCHED') != null}{dashboard.usage.get('SERVICE_SEARCHED')}{#else}0{/if}</div>
+    <div class="stat-sub">capability discovery calls</div>
+  </div>
+  <div class="stat">
+    <div class="stat-label">Rate limit</div>
+    <div class="stat-value">{dashboard.ratePerMinute}</div>
+    <div class="stat-sub">req / min</div>
+  </div>
+  <div class="stat">
+    <div class="stat-label">Expires</div>
+    <div class="stat-value" id="expires-val">—</div>
+    <div class="stat-sub" id="expires-raw">{dashboard.expiresAt}</div>
+  </div>
+  {#if dashboard.registrarLocation != null}
+  <div class="stat">
+    <div class="stat-label">Location</div>
+    <div class="stat-value" style="font-size:1rem">{dashboard.registrarLocation}</div>
+    <div class="stat-sub">owner-declared</div>
+  </div>
+  {/if}
+</div>
+
+<div id="map-wrap"><svg id="world-map"></svg></div>
+
+<div class="actions">
+  <div class="actions-title">Admin actions</div>
+  <form method="POST" action="/sandboxes/{dashboard.sandboxId}/promote">
+    <select name="tier">
+      <option value="FREE">FREE</option>
+      <option value="STANDARD">STANDARD</option>
+      <option value="PROFESSIONAL">PROFESSIONAL</option>
+      <option value="COMMUNITY">COMMUNITY</option>
+      <option value="FOUNDER">FOUNDER</option>
+      <option value="DEMO">DEMO</option>
+    </select>
+    <button type="submit" class="promote">Promote tier</button>
+  </form>
+</div>
+
+<div class="footer">sandbox id: {dashboard.sandboxId} · created {dashboard.createdAt}</div>
+
+<script>var __D = {dataJson.raw};</script>
+<script src="https://cdn.jsdelivr.net/npm/d3@7/dist/d3.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/topojson-client@3/dist/topojson-client.min.js"></script>
+<script src="/admin.js"></script>
+</body>
+</html>
@@ -0,0 +1,60 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>APIX Admin — Login</title>
+<style>
+* { box-sizing: border-box; margin: 0; padding: 0; }
+body {
+  background: #0d1117; color: #c9d1d9;
+  font-family: 'SF Mono', 'Consolas', 'Fira Code', monospace;
+  display: flex; align-items: center; justify-content: center;
+  min-height: 100vh;
+}
+.card {
+  width: 380px;
+  background: #161b22;
+  border: 1px solid #30363d;
+  border-radius: 6px;
+  padding: 2rem;
+}
+.logo { color: #8b949e; font-size: 0.75rem; letter-spacing: 0.1em; margin-bottom: 1.5rem; }
+.logo span { color: #e6edf3; font-size: 1rem; font-weight: 600; }
+label { display: block; font-size: 0.75rem; color: #8b949e; margin-bottom: 0.4rem; letter-spacing: 0.04em; }
+input[type=password] {
+  width: 100%; padding: 0.6rem 0.8rem;
+  background: #0d1117; border: 1px solid #30363d;
+  border-radius: 4px; color: #e6edf3;
+  font-family: inherit; font-size: 0.9rem;
+  outline: none; margin-bottom: 1rem;
+}
+input[type=password]:focus { border-color: #58a6ff; }
+button {
+  width: 100%; padding: 0.65rem;
+  background: #238636; border: none;
+  border-radius: 4px; color: #fff;
+  font-family: inherit; font-size: 0.9rem;
+  cursor: pointer; font-weight: 600;
+}
+button:hover { background: #2ea043; }
+.error {
+  background: #2d1b1b; border: 1px solid #f85149;
+  color: #f85149; border-radius: 4px;
+  padding: 0.5rem 0.8rem; font-size: 0.8rem;
+  margin-bottom: 1rem;
+}
+</style>
+</head>
+<body>
+<div class="card">
+  <div class="logo">APIX · <span>Admin</span></div>
+  {#if invalid}<div class="error">Invalid admin key. Try again.</div>{/if}
+  <form method="POST" action="/login">
+    <label>Admin API Key</label>
+    <input type="password" name="key" autofocus autocomplete="current-password" placeholder="apix_...">
+    <button type="submit">Sign in</button>
+  </form>
+</div>
+</body>
+</html>
@@ -0,0 +1,7 @@
+<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="UTF-8"><title>Error · APIX Admin</title>
+<style>* { box-sizing:border-box;margin:0;padding:0; } body { background:#0d1117;color:#c9d1d9;font-family:monospace;display:flex;align-items:center;justify-content:center;min-height:100vh; } .card { text-align:center; } .label { color:#f85149;font-size:.75rem;margin-bottom:.5rem; } .msg { color:#8b949e;margin-bottom:1.5rem; } a { color:#58a6ff; }</style>
+</head>
+<body><div class="card"><div class="label">ERROR</div><div class="msg">{message}</div><a href="/sandboxes">← Back to list</a></div></body>
+</html>
@@ -0,0 +1,124 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Sandboxes · APIX Admin</title>
+<style>
+* { box-sizing: border-box; margin: 0; padding: 0; }
+body { background: #0d1117; color: #c9d1d9; font-family: 'SF Mono','Consolas','Fira Code',monospace; font-size: 13px; }
+a { color: #58a6ff; text-decoration: none; }
+a:hover { text-decoration: underline; }
+nav {
+  display: flex; align-items: center; gap: 1.5rem;
+  padding: 0.75rem 1.5rem; border-bottom: 1px solid #21262d; background: #161b22;
+}
+.nav-logo { color: #8b949e; font-size: 0.75rem; }
+.nav-logo span { color: #e6edf3; font-weight: 600; font-size: 0.9rem; }
+.nav-link { font-size: 0.8rem; color: #8b949e; }
+.nav-link.active, .nav-link:hover { color: #e6edf3; }
+.nav-right { margin-left: auto; }
+
+.toolbar {
+  padding: 0.75rem 1.5rem; border-bottom: 1px solid #21262d;
+  display: flex; gap: 0.75rem; align-items: center; flex-wrap: wrap;
+}
+.toolbar-label { font-size: 0.7rem; color: #484f58; }
+.filter-link {
+  font-size: 0.75rem; color: #8b949e;
+  padding: 0.2rem 0.6rem; border: 1px solid #30363d; border-radius: 12px;
+}
+.filter-link:hover, .filter-link.active { color: #e6edf3; border-color: #58a6ff; }
+.count { margin-left: auto; font-size: 0.75rem; color: #484f58; }
+
+table { width: 100%; border-collapse: collapse; }
+th {
+  text-align: left; padding: 0.6rem 1.5rem;
+  font-size: 0.65rem; color: #484f58; text-transform: uppercase; letter-spacing: 0.06em;
+  border-bottom: 1px solid #21262d; background: #161b22;
+}
+td { padding: 0.55rem 1.5rem; border-bottom: 1px solid #161b22; vertical-align: middle; }
+tr:hover td { background: #161b22; }
+
+.tier-badge {
+  background: #0d1117; border: 1px solid #30363d;
+  color: #8b949e; padding: 0.1rem 0.4rem; border-radius: 10px;
+  font-size: 0.65rem; letter-spacing: 0.04em;
+}
+.tier-COMMUNITY { border-color: #1f6feb; color: #58a6ff; }
+.tier-FOUNDER   { border-color: #9e6a03; color: #e3b341; }
+.tier-DEMO      { border-color: #388bfd; color: #79c0ff; }
+
+.expired { color: #f85149; }
+.ok { color: #3fb950; }
+
+.pagination { padding: 1rem 1.5rem; display: flex; gap: 1rem; align-items: center; border-top: 1px solid #21262d; }
+.page-link { font-size: 0.8rem; color: #58a6ff; }
+.page-info { font-size: 0.75rem; color: #484f58; }
+</style>
+</head>
+<body>
+<nav>
+  <div class="nav-logo">APIX · <span>Admin</span></div>
+  <a class="nav-link" href="/">Dashboard</a>
+  <a class="nav-link active" href="/sandboxes">Sandboxes</a>
+  <div class="nav-right"><a class="nav-link" href="/login/logout">Sign out</a></div>
+</nav>
+
+<div class="toolbar">
+  <span class="toolbar-label">Filter:</span>
+  <a class="filter-link {#if tier == ''}active{/if}" href="/sandboxes">All</a>
+  <a class="filter-link {#if tier == 'FREE'}active{/if}" href="/sandboxes?tier=FREE">FREE</a>
+  <a class="filter-link {#if tier == 'COMMUNITY'}active{/if}" href="/sandboxes?tier=COMMUNITY">COMMUNITY</a>
+  <a class="filter-link {#if tier == 'FOUNDER'}active{/if}" href="/sandboxes?tier=FOUNDER">FOUNDER</a>
+  <a class="filter-link {#if tier == 'DEMO'}active{/if}" href="/sandboxes?tier=DEMO">DEMO</a>
+  <span class="count">{result.total} total</span>
+</div>
+
+<table>
+  <thead>
+    <tr>
+      <th>Name</th>
+      <th>Tier</th>
+      <th>Services</th>
+      <th>Requests</th>
+      <th>Location</th>
+      <th>Expires</th>
+    </tr>
+  </thead>
+  <tbody>
+  {#for sb in result.sandboxes}
+    <tr>
+      <td><a href="/sandbox/{sb.sandboxId}">{sb.name}</a>
+        <div style="font-size:0.65rem;color:#484f58;margin-top:2px">{sb.sandboxId}</div>
+      </td>
+      <td><span class="tier-badge tier-{sb.tier}">{sb.tier}</span></td>
+      <td>{sb.serviceCount}</td>
+      <td>{sb.totalRequests}</td>
+      <td>{#if sb.location != null}{sb.location}{#else}<span style="color:#484f58">—</span>{/if}</td>
+      <td class="{#if sb.expired}expired{#else}ok{/if}" data-expires="{sb.expiresAt}">{sb.expiresAt}</td>
+    </tr>
+  {/for}
+  </tbody>
+</table>
+
+<div class="pagination">
+  {#if page > 0}
+    <a class="page-link" href="/sandboxes?page={page - 1}&size={size}&tier={tier}">← Previous</a>
+  {/if}
+  <span class="page-info">Page {page + 1} · {result.sandboxes.size} of {result.total}</span>
+  {#if (page + 1) * size < result.total}
+    <a class="page-link" href="/sandboxes?page={page + 1}&size={size}&tier={tier}">Next →</a>
+  {/if}
+</div>
+
+<script>
+document.querySelectorAll('[data-expires]').forEach(td => {
+  const d = new Date(td.dataset.expires);
+  const now = new Date();
+  const days = Math.round((d - now) / 86400000);
+  td.textContent = days < 0 ? `expired ${-days}d ago` : `in ${days}d`;
+});
+</script>
+</body>
+</html>
@@ -0,0 +1,10 @@
+package org.botstandards.apix.common;
+
+import java.util.List;
+
+public record AdminSandboxListResponse(
+        long total,
+        int page,
+        int size,
+        List<AdminSandboxSummary> sandboxes
+) {}
@@ -0,0 +1,21 @@
+package org.botstandards.apix.common;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import java.time.Instant;
+
+/** Per-sandbox row in the admin list and stats endpoints. */
+public record AdminSandboxSummary(
+        String sandboxId,
+        String name,
+        String tier,
+        int ratePerMinute,
+        @JsonInclude(JsonInclude.Include.ALWAYS) Integer maxServices,
+        Instant createdAt,
+        Instant expiresAt,
+        boolean expired,
+        @JsonInclude(JsonInclude.Include.NON_NULL) String location,
+        @JsonInclude(JsonInclude.Include.NON_NULL) Double lat,
+        @JsonInclude(JsonInclude.Include.NON_NULL) Double lon,
+        long serviceCount,
+        long totalRequests
+) {}
@@ -0,0 +1,17 @@
+package org.botstandards.apix.common;
+
+import java.util.List;
+import java.util.Map;
+
+public record AdminStatsResponse(
+        long totalSandboxes,
+        long activeSandboxes,
+        long expiredSandboxes,
+        Map<String, Long> byTier,
+        long totalServices,
+        long totalRequests,
+        /** Geo-points for the world map: one point per sandbox that provided a location. */
+        List<GeoPoint> registrarPoints
+) {
+    public record GeoPoint(double lat, double lon, String name, String tier) {}
+}
@@ -14,6 +14,6 @@ import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
 public interface RegistryClient {

    @GET
-    @Path("/{uuid}")
+    @Path("/{uuid}/dashboard")
    SandboxDashboardResponse getDashboard(@PathParam("uuid") String uuid);
 }
@@ -453,6 +453,13 @@ public class IotTransitionSteps {
        lastResponse = given().get("/services/" + currentServiceId + "/history");
    }

+    // ── Then — HTTP status assertion ──────────────────────────────────────────
+
+    @Then("the response is HTTP {int}")
+    public void theResponseIsHttp(int status) {
+        lastResponse.then().statusCode(status);
+    }
+
    // ── Then — lifecycle state assertions ────────────────────────────────────

    @Then("the service stage is {string}")
@@ -511,13 +518,6 @@ public class IotTransitionSteps {
            .body("find { it.type == 'LOCK_RELEASED' }.previousValue", equalTo("true"));
    }

-    // ── Then — HTTP response assertions ──────────────────────────────────────
-
-    @Then("the response is HTTP {int}")
-    public void theResponseIsHttp(int statusCode) {
-        lastResponse.then().statusCode(statusCode);
-    }
-
    @Then("the error message contains {string}")
    public void theErrorMessageContains(String message) {
        lastResponse.then().body("message", containsString(message));
@@ -861,8 +861,9 @@ public class IotTransitionSteps {
    @When("^GET /services/\\{smartHubCloudId\\}/replacements\\?iotReady=true is called with no (?:authentication|Authorization) header$")
    public void getReplacementsIotReady() {
        actionPhase = true;
-        lastResponse = given().get(
-            "/services/" + serviceIds.get("SmartHub Cloud") + "/replacements?iotReady=true");
+        lastResponse = given()
+            .queryParam("iotReady", "true")
+            .get("/services/" + serviceIds.get("SmartHub Cloud") + "/replacements");
    }

    @When("^GET /services/\\{smartHubCloudId\\}/replacements\\?deviceClass=([^ ]+) is called with no (?:authentication|Authorization) header$")
@@ -33,7 +33,9 @@ public class SandboxSteps {
    /** Name of the most recently created sandbox. */
    private String currentSandboxName;
    /** Keys indexed by sandbox name for multi-sandbox scenarios. */
-    private final Map<String, String> sandboxKeys = new HashMap<>();
+    private final Map<String, String> sandboxKeys  = new HashMap<>();
+    /** UUIDs indexed by sandbox name — used for resource routing (name is display-only). */
+    private final Map<String, String> sandboxUuids = new HashMap<>();

    // ── Given — sandbox creation ──────────────────────────────────────────────

@@ -45,6 +47,7 @@ public class SandboxSteps {
    @Given("a production service {string} with endpoint {string} is registered")
    public void aProductionServiceIsRegistered(String serviceName, String endpoint) {
        Map<String, Object> payload = buildServicePayload(serviceName, endpoint, "device.telemetry");
+        payload.put("serviceStage", "PRODUCTION");
        given()
            .contentType(JSON)
            .header(ADMIN_API_KEY_HEADER, ADMIN_API_KEY)
@@ -57,14 +60,15 @@ public class SandboxSteps {

    @Given("a sandbox service with endpoint {string} and capability {string} is registered in {string}")
    public void aSandboxServiceIsRegistered(String endpoint, String capability, String sandboxName) {
-        String key = resolveKey(sandboxName);
+        String key  = resolveKey(sandboxName);
+        String uuid = resolveUuid(sandboxName);
        Map<String, Object> payload = buildServicePayload("SandboxService-" + endpoint.hashCode(), endpoint, capability);
        given()
            .contentType(JSON)
            .header(SANDBOX_API_KEY_HEADER, key)
            .body(payload)
        .when()
-            .post("/sandbox/" + sandboxName + "/services")
+            .post("/sandbox/" + uuid + "/services")
        .then()
            .statusCode(201);
    }
@@ -72,7 +76,8 @@ public class SandboxSteps {
    @Given("a sandbox service with endpoint {string} capability {string} and extension {string} is registered in {string}")
    public void aSandboxServiceWithExtensionIsRegistered(String endpoint, String capability,
                                                          String extension, String sandboxName) {
-        String key = resolveKey(sandboxName);
+        String key  = resolveKey(sandboxName);
+        String uuid = resolveUuid(sandboxName);
        int colon = extension.indexOf(':');
        Map<String, Object> extensions = colon > 0
                ? Map.of(extension.substring(0, colon), extension.substring(colon + 1))
@@ -84,19 +89,19 @@ public class SandboxSteps {
            .header(SANDBOX_API_KEY_HEADER, key)
            .body(payload)
        .when()
-            .post("/sandbox/" + sandboxName + "/services")
+            .post("/sandbox/" + uuid + "/services")
        .then()
            .statusCode(201);
    }

    @Given("the sandbox root for {string} has been viewed once")
    public void sandboxRootHasBeenViewedOnce(String sandboxName) {
-        given().get("/sandbox/" + sandboxName).then().statusCode(200);
+        given().get("/sandbox/" + resolveUuid(sandboxName)).then().statusCode(200);
    }

    @Given("the sandbox service list for {string} has been requested once")
    public void sandboxServiceListHasBeenRequestedOnce(String sandboxName) {
-        given().get("/sandbox/" + sandboxName + "/services").then().statusCode(200);
+        given().get("/sandbox/" + resolveUuid(sandboxName) + "/services").then().statusCode(200);
    }

    @Given("feedback has been submitted to {string} with scores {word}={int} {word}={int}")
@@ -111,7 +116,8 @@ public class SandboxSteps {

    @Given("{int} services have been registered in sandbox {string}")
    public void nServicesRegisteredInSandbox(int count, String sandboxName) {
-        String key = resolveKey(sandboxName);
+        String key  = resolveKey(sandboxName);
+        String uuid = resolveUuid(sandboxName);
        for (int i = 0; i < count; i++) {
            Map<String, Object> payload = buildServicePayload(
                "CapService-" + i, "https://cap-" + i + ".example.com", "cap.test");
@@ -120,7 +126,7 @@ public class SandboxSteps {
                .header(SANDBOX_API_KEY_HEADER, key)
                .body(payload)
            .when()
-                .post("/sandbox/" + sandboxName + "/services")
+                .post("/sandbox/" + uuid + "/services")
            .then()
                .statusCode(201);
        }
@@ -141,6 +147,7 @@ public class SandboxSteps {
            currentSandboxKey  = lastResponse.jsonPath().getString("apiKey");
            currentSandboxName = name;
            sandboxKeys.put(name, currentSandboxKey);
+            sandboxUuids.put(name, lastResponse.jsonPath().getString("sandboxId"));
        }
    }

@@ -172,19 +179,29 @@ public class SandboxSteps {

    @When("the sandbox root for {string} is requested")
    public void sandboxRootRequested(String sandboxName) {
-        lastResponse = given().get("/sandbox/" + sandboxName).andReturn();
+        lastResponse = given().get("/sandbox/" + resolveUuid(sandboxName)).andReturn();
+    }
+
+    @When("the sandbox root for UUID {string} is requested")
+    public void sandboxRootRequestedByUuid(String uuid) {
+        lastResponse = given().get("/sandbox/" + uuid).andReturn();
    }

    // ── When — service operations ─────────────────────────────────────────────

-    @When("GET /services is called without authentication")
+    @When("GET \\/services is called without authentication")
    public void getServicesWithoutAuth() {
        lastResponse = given().get("/services").andReturn();
    }

+    @When("GET \\/services is called with capability {string} without authentication")
+    public void getServicesWithCapabilityWithoutAuth(String capability) {
+        lastResponse = given().get("/services?capability=" + capability).andReturn();
+    }
+
    @When("the sandbox service list for {string} is requested")
    public void sandboxServiceListRequested(String sandboxName) {
-        lastResponse = given().get("/sandbox/" + sandboxName + "/services").andReturn();
+        lastResponse = given().get("/sandbox/" + resolveUuid(sandboxName) + "/services").andReturn();
    }

    @When("a service is registered in sandbox {string} without an API key")
@@ -194,7 +211,7 @@ public class SandboxSteps {
            .contentType(JSON)
            .body(payload)
        .when()
-            .post("/sandbox/" + sandboxName + "/services")
+            .post("/sandbox/" + resolveUuid(sandboxName) + "/services")
        .andReturn();
    }

@@ -206,7 +223,7 @@ public class SandboxSteps {
            .header(SANDBOX_API_KEY_HEADER, key)
            .body(payload)
        .when()
-            .post("/sandbox/" + sandboxName + "/services")
+            .post("/sandbox/" + resolveUuid(sandboxName) + "/services")
        .andReturn();
    }

@@ -219,21 +236,38 @@ public class SandboxSteps {
            .header(SANDBOX_API_KEY_HEADER, key)
            .body(payload)
        .when()
-            .post("/sandbox/" + sandboxName + "/services")
+            .post("/sandbox/" + resolveUuid(sandboxName) + "/services")
        .andReturn();
    }

    @When("sandbox {string} services are searched by capability {string}")
    public void sandboxServiceSearchCalled(String sandboxName, String capability) {
        lastResponse = given()
-            .get("/sandbox/" + sandboxName + "/services?capability=" + capability)
+            .get("/sandbox/" + resolveUuid(sandboxName) + "/services?capability=" + capability)
        .andReturn();
    }

    @When("sandbox {string} services are searched by capability {string} and property {string}")
    public void sandboxServiceSearchCalledWithProperty(String sandboxName, String capability, String property) {
        lastResponse = given()
-            .get("/sandbox/" + sandboxName + "/services?capability=" + capability + "&property=" + property)
+            .get("/sandbox/" + resolveUuid(sandboxName) + "/services?capability=" + capability + "&property=" + property)
+        .andReturn();
+    }
+
+    @When("GET \\/services is called with capability {string} and the sandbox key for {string}")
+    public void getServicesWithCapabilityAndSandboxKey(String capability, String sandboxName) {
+        String key = resolveKey(sandboxName);
+        lastResponse = given()
+            .header(SANDBOX_API_KEY_HEADER, key)
+            .get("/services?capability=" + capability)
+        .andReturn();
+    }
+
+    @When("GET \\/services is called with capability {string} and API key {string}")
+    public void getServicesWithCapabilityAndLiteralKey(String capability, String apiKey) {
+        lastResponse = given()
+            .header(SANDBOX_API_KEY_HEADER, apiKey)
+            .get("/services?capability=" + capability)
        .andReturn();
    }

@@ -241,17 +275,18 @@ public class SandboxSteps {

    @When("the telemetry for {string} is requested with the sandbox API key")
    public void telemetryRequestedWithKey(String sandboxName) {
-        String key = resolveKey(sandboxName);
+        String key  = resolveKey(sandboxName);
+        String uuid = resolveUuid(sandboxName);
        lastResponse = given()
            .header(SANDBOX_API_KEY_HEADER, key)
        .when()
-            .get("/sandbox/" + sandboxName + "/telemetry")
+            .get("/sandbox/" + uuid + "/telemetry")
        .andReturn();
    }

    @When("the telemetry for {string} is requested without an API key")
    public void telemetryRequestedWithoutKey(String sandboxName) {
-        lastResponse = given().get("/sandbox/" + sandboxName + "/telemetry").andReturn();
+        lastResponse = given().get("/sandbox/" + resolveUuid(sandboxName) + "/telemetry").andReturn();
    }

    @When("the telemetry for {string} is requested with API key {string}")
@@ -259,13 +294,13 @@ public class SandboxSteps {
        lastResponse = given()
            .header(SANDBOX_API_KEY_HEADER, key)
        .when()
-            .get("/sandbox/" + sandboxName + "/telemetry")
+            .get("/sandbox/" + resolveUuid(sandboxName) + "/telemetry")
        .andReturn();
    }

    // ── When — feedback ───────────────────────────────────────────────────────

-    @When("GET /sandbox/feedback-schema is called without authentication")
+    @When("GET \\/sandbox\\/feedback-schema is called without authentication")
    public void getFeedbackSchema() {
        lastResponse = given().get("/sandbox/feedback-schema").andReturn();
    }
@@ -291,23 +326,24 @@ public class SandboxSteps {
            .contentType(JSON)
            .body(Map.of("scores", Map.of()))
        .when()
-            .post("/sandbox/" + sandboxName + "/feedback")
+            .post("/sandbox/" + resolveUuid(sandboxName) + "/feedback")
        .andReturn();
    }

    @When("the feedback aggregate for {string} is requested with the sandbox API key")
    public void feedbackAggregateWithKey(String sandboxName) {
-        String key = resolveKey(sandboxName);
+        String key  = resolveKey(sandboxName);
+        String uuid = resolveUuid(sandboxName);
        lastResponse = given()
            .header(SANDBOX_API_KEY_HEADER, key)
        .when()
-            .get("/sandbox/" + sandboxName + "/feedback")
+            .get("/sandbox/" + uuid + "/feedback")
        .andReturn();
    }

    @When("the feedback aggregate for {string} is requested without an API key")
    public void feedbackAggregateWithoutKey(String sandboxName) {
-        lastResponse = given().get("/sandbox/" + sandboxName + "/feedback").andReturn();
+        lastResponse = given().get("/sandbox/" + resolveUuid(sandboxName) + "/feedback").andReturn();
    }

    // ── Then — HTTP status ────────────────────────────────────────────────────
@@ -339,6 +375,11 @@ public class SandboxSteps {
        assertThat(lastResponse.jsonPath().getString("expiresAt")).isNotBlank();
    }

+    @Then("the response contains _links.self")
+    public void responseContainsLinksSelf() {
+        assertThat(lastResponse.jsonPath().getString("_links.self.href")).as("_links.self.href").isNotBlank();
+    }
+
    @Then("the response contains _links.self ending with {string}")
    public void responseContainsLinksSelfEndingWith(String suffix) {
        String href = lastResponse.jsonPath().getString("_links.self.href");
@@ -510,8 +551,10 @@ public class SandboxSteps {
        .andReturn();

        assertThat(r.statusCode()).as("sandbox creation for '%s' must return 201", name).isEqualTo(201);
-        String key = r.jsonPath().getString("apiKey");
+        String key  = r.jsonPath().getString("apiKey");
+        String uuid = r.jsonPath().getString("sandboxId");
        sandboxKeys.put(name, key);
+        sandboxUuids.put(name, uuid);
        currentSandboxKey  = key;
        currentSandboxName = name;
    }
@@ -522,6 +565,12 @@ public class SandboxSteps {
        return key;
    }

+    private String resolveUuid(String sandboxName) {
+        String uuid = sandboxUuids.get(sandboxName);
+        assertThat(uuid).as("sandbox UUID for '%s' must be known — call createSandbox first", sandboxName).isNotNull();
+        return uuid;
+    }
+
    private void submitFeedback(String sandboxName, Map<String, Integer> scores, String model, String provider) {
        submitFeedbackResponse(sandboxName, scores, model, provider);
    }
@@ -536,7 +585,7 @@ public class SandboxSteps {
            .contentType(JSON)
            .body(body)
        .when()
-            .post("/sandbox/" + sandboxName + "/feedback")
+            .post("/sandbox/" + resolveUuid(sandboxName) + "/feedback")
        .andReturn();
    }

@@ -1,4 +1,4 @@
-package org.botstandards.apix.registry.bdd.device;
+package org.botstandards.apix.registry.devicebdd;

 import io.cucumber.core.cli.Main;
 import io.quarkus.test.junit.QuarkusTest;
@@ -9,8 +9,9 @@ import static org.junit.jupiter.api.Assertions.assertEquals;
 /**
 * Runs all device navigation BDD scenarios inside the Quarkus test context.
 *
- * Uses its own glue package so step definitions do not conflict with
- * IotTransitionSteps or OrgOnboardingSteps.
+ * Uses two glue packages: bdd (for TestSetup/truncateTables) and devicebdd
+ * (for DeviceNavigationSteps). The separation prevents DeviceNavigationSteps
+ * from being picked up by non-device CucumberITs that only scan --glue bdd.
 */
@QuarkusTest
 public class DeviceCucumberIT {
@@ -18,7 +19,7 @@ public class DeviceCucumberIT {
    @Test
    public void run() {
        byte exitCode = Main.run(
-            "--glue", "org.botstandards.apix.registry.bdd.device",
+            "--glue", "org.botstandards.apix.registry.devicebdd",
            "--plugin", "pretty",
            "--plugin", "json:target/cucumber-report-devices.json",
            "--plugin", "io.qameta.allure.cucumber7jvm.AllureCucumber7Jvm",
@@ -1,4 +1,4 @@
-package org.botstandards.apix.registry.bdd.device;
+package org.botstandards.apix.registry.devicebdd;

 import io.cucumber.java.en.And;
 import io.cucumber.java.en.Given;
@@ -16,7 +16,8 @@ import static org.hamcrest.Matchers.*;

 /**
 * Self-contained step definitions for the /devices top-level resource.
- * Uses its own glue package so it does not conflict with IotTransitionSteps.
+ * Lives in a sibling package (devicebdd) to avoid recursive inclusion by
+ * non-device CucumberITs that use --glue bdd only.
 * Cucumber creates a fresh instance per scenario — instance fields are scenario-scoped.
 */
 public class DeviceNavigationSteps {
@@ -97,27 +98,27 @@ public class DeviceNavigationSteps {

    // ── When ──────────────────────────────────────────────────────────────────

-    @When("GET /devices is called with no query params")
+    @When("GET \\/devices is called with no query params")
    public void getDevicesRoot() {
        lastResponse = given().get("/devices");
    }

-    @When("GET / is called")
+    @When("GET \\/ is called")
    public void getRoot() {
        lastResponse = given().get("/");
    }

-    @When("GET /devices?capability={string} is called")
+    @When("^GET /devices\\?capability=(.+) is called$")
    public void getDevicesByCapability(String capability) {
        lastResponse = given().get("/devices?capability=" + capability);
    }

-    @When("GET /devices?deviceClass={string} is called")
+    @When("^GET /devices\\?deviceClass=(.+) is called$")
    public void getDevicesByDeviceClass(String deviceClass) {
        lastResponse = given().get("/devices?deviceClass=" + deviceClass);
    }

-    @When("GET /devices?protocol={string} is called")
+    @When("^GET /devices\\?protocol=(.+) is called$")
    public void getDevicesByProtocol(String protocol) {
        lastResponse = given().get("/devices?protocol=" + protocol);
    }
@@ -0,0 +1,36 @@
+package org.botstandards.apix.registry.devicebdd;
+
+import io.cucumber.java.After;
+import io.cucumber.java.Before;
+import io.quarkus.arc.Arc;
+import io.restassured.RestAssured;
+import org.botstandards.apix.registry.service.ClockService;
+
+import java.sql.DriverManager;
+import java.time.Instant;
+
+public class TestSetup {
+
+    private static final Instant REFERENCE_INSTANT = Instant.parse("2025-01-01T00:00:00Z");
+
+    @Before(order = 0)
+    public void configureRestAssured() {
+        RestAssured.port = 8181;
+        RestAssured.enableLoggingOfRequestAndResponseIfValidationFails();
+        Arc.container().instance(ClockService.class).get().advance(REFERENCE_INSTANT);
+    }
+
+    @Before(order = 1)
+    public void truncateTables() throws Exception {
+        try (var conn = DriverManager.getConnection(
+                "jdbc:postgresql://localhost:5432/apix", "apix", "apix");
+             var stmt = conn.createStatement()) {
+            stmt.execute("TRUNCATE TABLE service_replacements, service_versions, services, org_verification_events, organizations, sandbox_feedback, sandbox_usage_stats, sandboxes CASCADE");
+        }
+    }
+
+    @After
+    public void resetClock() {
+        Arc.container().instance(ClockService.class).get().reset();
+    }
+}
@@ -13,7 +13,7 @@ Feature: HATEOAS navigation and root key resolution
  Scenario: Root resource with valid sandbox API key includes _links.sandbox
    When the root resource is requested with the sandbox API key for "nav-demo"
    Then the response code is 200
-    And the response contains _links.sandbox ending with "/sandbox/nav-demo"
+    And the response contains _links.sandbox

  Scenario: Root resource with unknown API key omits _links.sandbox
    When the root resource is requested with API key "apix_sb_unknownkey"
@@ -28,6 +28,6 @@ Feature: HATEOAS navigation and root key resolution
    And the response contains _links.submitFeedback
    And the response contains _links.feedbackSchema

-  Scenario: Sandbox root for unknown name returns 404
-    When the sandbox root for "does-not-exist" is requested
+  Scenario: Sandbox root for unknown UUID returns 404
+    When the sandbox root for UUID "00000000-0000-0000-0000-000000000000" is requested
    Then the response code is 404
@@ -7,7 +7,7 @@ Feature: Sandbox registration
    And the response contains an API key with prefix "apix_sb_"
    And the response contains tier "FREE"
    And the response contains a non-null expiresAt
-    And the response contains _links.self ending with "/sandbox/peter-demo"
+    And the response contains _links.self
    And the response contains _links.services

  Scenario: Registration fails when name contains uppercase letters
@@ -26,7 +26,7 @@ Feature: Sandbox registration
    When an agent registers a sandbox named "valid-name" with email "not-an-email"
    Then the response code is 400

-  Scenario: Duplicate name is rejected with 409
+  Scenario: Duplicate name is allowed since names are display-only labels
    Given a sandbox named "duplicate-test" exists
    When an agent registers a sandbox named "duplicate-test" with email "other@example.com"
-    Then the response code is 409
+    Then the response code is 201
@@ -6,7 +6,7 @@ Feature: Sandbox service isolation from production

  Scenario: Service registered in sandbox does not appear in production list
    Given a sandbox service with endpoint "https://sandbox.example.com" and capability "test.cap" is registered in "isolation-test"
-    When GET /services is called without authentication
+    When GET /services is called with capability "test.cap" without authentication
    Then the response code is 200
    And "https://sandbox.example.com" is not in the endpoint list

@@ -43,3 +43,19 @@ Feature: Sandbox service isolation from production
    Then the response code is 200
    And "https://ext-eu.example.com" is in the endpoint list
    And "https://ext-us.example.com" is not in the endpoint list
+
+  Scenario: GET /services with sandbox key scopes results to sandbox only
+    Given a sandbox service with endpoint "https://keyed-sb.example.com" and capability "keyed.cap" is registered in "isolation-test"
+    When GET /services is called with capability "keyed.cap" and the sandbox key for "isolation-test"
+    Then the response code is 200
+    And "https://keyed-sb.example.com" is in the endpoint list
+
+  Scenario: GET /services with sandbox key does not return production services
+    When GET /services is called with capability "device.telemetry" and the sandbox key for "isolation-test"
+    Then the response code is 200
+    And "https://prod.example.com" is not in the endpoint list
+
+  Scenario: GET /services with invalid sandbox key falls back to production
+    When GET /services is called with capability "device.telemetry" and API key "apix_sb_000invalid"
+    Then the response code is 200
+    And "https://prod.example.com" is in the endpoint list
@@ -61,11 +61,16 @@ public class QueryNormalisationService {
    public String canonicalForReplacements(MultivaluedMap<String, String> raw) {
        Map<String, String> out = new TreeMap<>();
        put(out, "deviceClass", normaliseLower(raw.getFirst("deviceClass")));
+        put(out, "iotReady",    normaliseIotReady(raw.getFirst("iotReady")));
        put(out, "minOLevel",   normaliseEnum(raw.getFirst("minOLevel")));
        put(out, "protocol",    normaliseEnum(raw.getFirst("protocol")));
        return render(out);
    }

+    String normaliseIotReady(String v) {
+        return "true".equalsIgnoreCase(v) ? "true" : null;
+    }
+
    // ── Individual value normalisers — package-private for unit tests ──────────

    String normaliseCapability(String v) {
@@ -0,0 +1,97 @@
+package org.botstandards.apix.registry.resource;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.*;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import org.botstandards.apix.common.AdminSandboxListResponse;
+import org.botstandards.apix.common.AdminStatsResponse;
+import org.botstandards.apix.common.SandboxDashboardResponse;
+import org.botstandards.apix.registry.service.SandboxService;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+
+import java.util.Map;
+import java.util.UUID;
+
+@Path("/admin")
+@Produces(MediaType.APPLICATION_JSON)
+@Consumes(MediaType.APPLICATION_JSON)
+public class AdminResource {
+
+    @Inject
+    SandboxService sandboxService;
+
+    @ConfigProperty(name = "apix.api-key", defaultValue = "")
+    String adminApiKey;
+
+    @GET
+    @Path("/sandboxes")
+    @Operation(summary = "List all sandboxes (admin)", description = "Requires X-Admin-Key.")
+    public AdminSandboxListResponse listSandboxes(
+            @HeaderParam("X-Admin-Key") String adminKey,
+            @QueryParam("page") @DefaultValue("0") int page,
+            @QueryParam("size") @DefaultValue("50") int size,
+            @QueryParam("tier") String tier) {
+        requireAdmin(adminKey);
+        if (size > 200) size = 200;
+        return sandboxService.listAllSandboxes(page, size, tier);
+    }
+
+    @GET
+    @Path("/stats")
+    @Operation(summary = "Global registry statistics (admin)", description = "Requires X-Admin-Key.")
+    public AdminStatsResponse stats(@HeaderParam("X-Admin-Key") String adminKey) {
+        requireAdmin(adminKey);
+        return sandboxService.getGlobalStats();
+    }
+
+    @GET
+    @Path("/sandboxes/{uuid}")
+    @Operation(summary = "Full dashboard view of any sandbox (admin)", description = "Requires X-Admin-Key.")
+    public SandboxDashboardResponse sandboxDetail(
+            @HeaderParam("X-Admin-Key") String adminKey,
+            @PathParam("uuid") String uuidStr) {
+        requireAdmin(adminKey);
+        UUID id;
+        try { id = UUID.fromString(uuidStr); }
+        catch (IllegalArgumentException e) {
+            throw new WebApplicationException(
+                    Response.status(404).entity(Map.of("message", "Sandbox not found")).build());
+        }
+        return sandboxService.getDashboard(id);
+    }
+
+    @PATCH
+    @Path("/sandboxes/{uuid}/tier")
+    @Operation(summary = "Promote sandbox tier (admin)", description = "Requires X-Admin-Key.")
+    public Response promoteTier(
+            @HeaderParam("X-Admin-Key") String adminKey,
+            @PathParam("uuid") String uuidStr,
+            Map<String, String> body) {
+        requireAdmin(adminKey);
+        String newTier = body == null ? null : body.get("tier");
+        if (newTier == null || newTier.isBlank())
+            return Response.status(400).entity(Map.of("message", "Body must contain 'tier'")).build();
+        UUID id;
+        try { id = UUID.fromString(uuidStr); }
+        catch (IllegalArgumentException e) {
+            throw new WebApplicationException(
+                    Response.status(404).entity(Map.of("message", "Sandbox not found")).build());
+        }
+        var sb = sandboxService.requireById(id);
+        sandboxService.promoteTier(sb, newTier.toUpperCase());
+        return Response.ok(Map.of(
+                "sandboxId", sb.id.toString(),
+                "tier", sb.tier,
+                "ratePerMinute", sb.ratePerMinute,
+                "expiresAt", sb.expiresAt.toString())).build();
+    }
+
+    private void requireAdmin(String key) {
+        if (adminApiKey.isBlank() || !adminApiKey.equals(key)) {
+            throw new WebApplicationException(
+                    Response.status(401).entity(Map.of("message", "Invalid or missing admin key")).build());
+        }
+    }
+}
@@ -47,7 +47,7 @@ public class IndexResource {
        if (apiKey != null && !apiKey.isBlank()) {
            SandboxEntity sandbox = sandboxService.findByKey(apiKey);
            if (sandbox != null) {
-                sandboxLink = new LinkRef(baseUrl + "/sandbox/" + sandbox.name);
+                sandboxLink = new LinkRef(baseUrl + "/sandbox/" + sandbox.id);
            }
        }

@@ -69,16 +69,31 @@ public class SandboxResource {
    @GET
    @Path("/{uuid}")
    @Operation(
-        summary = "Sandbox root — HATEOAS navigation and dashboard data",
-        description = "Returns sandbox metadata, navigation links, usage stats, and agent visit data. " +
+        summary = "Sandbox root — HATEOAS navigation",
+        description = "Returns sandbox metadata and navigation links. " +
            "No authentication required. The UUID is the permanent resource identifier."
    )
-    public SandboxDashboardResponse index(@PathParam("uuid") String uuidStr) {
+    public SandboxIndexResponse index(@PathParam("uuid") String uuidStr) {
        UUID id = parseUuid(uuidStr);
-        SandboxDashboardResponse dashboard = sandboxService.getDashboard(id);
+        var sb = sandboxService.requireById(id);
        sandboxService.recordUsage(id.toString(), SandboxService.EVENT_SANDBOX_VIEWED);
        meters.counter("apix.sandbox.views", "sandbox", id.toString()).increment();
-        return dashboard;
+        String base = baseUrl + "/sandbox/" + id;
+        return new SandboxIndexResponse(sb.id.toString(), sb.name, sb.tier, sb.ratePerMinute,
+                sb.expiresAt, sandboxService.sandboxLinks(base, id.toString()));
+    }
+
+    @GET
+    @Path("/{uuid}/dashboard")
+    @Operation(
+        summary = "Full sandbox dashboard — for the portal",
+        description = "Returns the complete sandbox view: tier caps, usage counters, " +
+            "recent agent visits with geo-resolved coordinates. " +
+            "Intended for the portal UI; no authentication required."
+    )
+    public SandboxDashboardResponse dashboard(@PathParam("uuid") String uuidStr) {
+        UUID id = parseUuid(uuidStr);
+        return sandboxService.getDashboard(id);
    }

    @POST
@@ -11,12 +11,15 @@ import org.botstandards.apix.registry.dto.ReplacementsResponse;
 import org.botstandards.apix.registry.dto.ServicePatchRequest;
 import org.botstandards.apix.registry.dto.ServiceResponse;
 import org.botstandards.apix.registry.dto.VersionHistoryEntry;
+import org.botstandards.apix.registry.entity.SandboxEntity;
 import org.botstandards.apix.registry.service.RegistryService;
+import org.botstandards.apix.registry.service.SandboxService;
 import org.eclipse.microprofile.config.inject.ConfigProperty;
 import org.eclipse.microprofile.openapi.annotations.Operation;
 import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
 import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;

+import jakarta.ws.rs.core.UriInfo;
 import java.net.URI;
 import java.util.List;
 import java.util.Map;
@@ -30,6 +33,9 @@ public class ServiceResource {
    @Inject
    RegistryService registryService;

+    @Inject
+    SandboxService sandboxService;
+
    @Inject
    MeterRegistry meters;

@@ -83,6 +89,8 @@ public class ServiceResource {
        summary = "Search services by capability and optional extension properties",
        description = "Returns services matching the given capability keyword. " +
            "Omitting ?stage= defaults to PRODUCTION only — this is the standard agent query. " +
+            "When a valid sandbox API key is provided via X-Api-Key, results are scoped to that sandbox " +
+            "and stage defaults to DEVELOPMENT. " +
            "Use ?stage=DEVELOPMENT or ?stage=BETA to discover pre-production services. " +
            "Capability values are lowercase kebab-case strings defined by the registrant (e.g. nlp, translation, speech-to-text). " +
            "The search matches exact capability tokens, not substrings. " +
@@ -90,17 +98,20 @@ public class ServiceResource {
            "Multiple ?property= parameters are ANDed together. " +
            "Example: ?capability=translation&property=region:eu&property=dataResidency:DE"
    )
-    public List<ServiceResponse> search(
+    public Response search(
            @Parameter(description = "Capability keyword to search for (e.g. nlp, translation, speech-to-text). Required.", example = "nlp")
            @QueryParam("capability") String capability,
            @Parameter(description = "Lifecycle stage filter. Defaults to PRODUCTION if omitted. Valid values: DEVELOPMENT, BETA, PRODUCTION, DEPRECATED.", example = "PRODUCTION")
            @QueryParam("stage") String stage,
            @Parameter(description = "Extension property filter in key:value format. Matches against the service's extensions object. Repeatable for AND logic.", example = "region:eu")
-            @QueryParam("property") List<String> properties) {
+            @QueryParam("property") List<String> properties,
+            @HeaderParam("X-Api-Key") String incomingKey) {
        if (capability == null || capability.isBlank()) {
            throw new BadRequestException("capability query parameter is required");
        }
-        var results = registryService.search(capability, stage, properties).stream()
+        SandboxEntity sandbox = sandboxService.findByKey(incomingKey);
+        String sandboxId = sandbox != null ? sandbox.id.toString() : null;
+        var results = registryService.search(capability, stage, properties, sandboxId).stream()
                .map(ServiceResponse::from)
                .toList();

@@ -114,7 +125,12 @@ public class ServiceResource {
                "capability", tv(capability))
                .record(results.size());

-        return results;
+        Response.ResponseBuilder rb = Response.ok(results);
+        // Sandbox responses are scoped to a specific API key — must not be cached by the CDN.
+        if (sandboxId != null) {
+            rb.header("Cache-Control", "private, no-store");
+        }
+        return rb.build();
    }

    @PATCH
@@ -143,14 +159,15 @@ public class ServiceResource {
            "Optionally filter by minimum O-level, IoT readiness, device class, or protocol."
    )
    public Response getReplacements(@PathParam("id") UUID id,
+                                    @Context UriInfo uriInfo,
                                    @Parameter(description = "Minimum O-level of replacement candidates.", example = "IDENTITY_VERIFIED")
                                    @QueryParam("minOLevel") String minOLevel,
-                                    @Parameter(description = "If true, only return services with an IoT profile.")
-                                    @QueryParam("iotReady") Boolean iotReady,
                                    @Parameter(description = "Filter by IoT device class (e.g. sensor, actuator, gateway).")
                                    @QueryParam("deviceClass") String deviceClass,
                                    @Parameter(description = "Filter by IoT protocol (e.g. MQTT, AMQP, HTTP).")
                                    @QueryParam("protocol") String protocol) {
+        String iotReadyStr = uriInfo.getQueryParameters().getFirst("iotReady");
+        boolean iotReady = "true".equalsIgnoreCase(iotReadyStr);
        ReplacementsResponse body = registryService.getReplacements(id, minOLevel, iotReady, deviceClass, protocol);
        return Response.ok(body)
                .header("Cache-Control", "public, max-age=60")
@@ -127,18 +127,22 @@ public class RegistryService {
    }

    @SuppressWarnings("unchecked")
-    public List<ServiceEntity> search(String capability, String stage, List<String> properties) {
+    public List<ServiceEntity> search(String capability, String stage, List<String> properties,
+                                      String sandboxId) {
        ServiceStage targetStage = stage != null
                ? ServiceStage.valueOf(stage.toUpperCase())
-                : ServiceStage.PRODUCTION;
+                : sandboxId != null ? ServiceStage.DEVELOPMENT : ServiceStage.PRODUCTION;

        List<String[]> props = parsePropertyFilters(properties);
+        String scopeClause = sandboxId != null
+                ? "AND s.sandbox_id = :sid"
+                : "AND s.sandbox_id IS NULL";
        StringBuilder sql = new StringBuilder(
                "SELECT s.* FROM services s " +
                "WHERE s.bsm_payload @> jsonb_build_object('capabilities', jsonb_build_array(:cap)) " +
                "AND s.registry_status = 'ACTIVE' " +
                "AND s.service_stage = :stage " +
-                "AND s.sandbox_id IS NULL");
+                scopeClause);
        for (int i = 0; i < props.size(); i++) {
            sql.append(" AND s.bsm_payload -> 'extensions' ->> :propKey").append(i)
               .append(" = :propValue").append(i);
@@ -147,6 +151,7 @@ public class RegistryService {
        Query q = em.createNativeQuery(sql.toString(), ServiceEntity.class)
                .setParameter("cap", capability)
                .setParameter("stage", targetStage.name());
+        if (sandboxId != null) q.setParameter("sid", sandboxId);
        for (int i = 0; i < props.size(); i++) {
            q.setParameter("propKey" + i, props.get(i)[0]);
            q.setParameter("propValue" + i, props.get(i)[1]);
@@ -167,7 +172,7 @@ public class RegistryService {

    @SuppressWarnings("unchecked")
    public ReplacementsResponse getReplacements(UUID deprecatedId, String minOLevelStr,
-                                                 Boolean iotReady, String deviceClass, String protocol) {
+                                                 boolean iotReady, String deviceClass, String protocol) {
        ServiceEntity deprecated = requireById(deprecatedId);

        // Locked services that are not yet DECOMMISSIONED block replacement discovery
@@ -175,36 +180,39 @@ public class RegistryService {
            return new ReplacementsResponse(deprecated.locked, deprecated.sunsetAt, List.of());
        }

-        List<ServiceEntity> candidates = em.createNativeQuery(
+        // INNER JOIN iot_profiles when IoT filters are active — explicit join guarantees
+        // row existence without relying on Hibernate EAGER proxy null-checks.
+        boolean needsIotJoin = iotReady
+                || (deviceClass != null && !deviceClass.isBlank())
+                || (protocol   != null && !protocol.isBlank());
+
+        StringBuilder sql = new StringBuilder(
                "SELECT s.* FROM services s " +
-                "INNER JOIN service_replacements sr ON sr.replacement_service_id = s.id " +
-                "WHERE sr.deprecated_service_id = :depId AND s.registry_status = 'ACTIVE'",
-                ServiceEntity.class)
-                .setParameter("depId", deprecatedId)
-                .getResultList();
-
-        OLevel minOLevel = minOLevelStr != null ? OLevel.valueOf(minOLevelStr) : null;
-
-        Stream<ServiceEntity> stream = candidates.stream()
-                .filter(c -> minOLevel == null || c.olevel.ordinal() >= minOLevel.ordinal());
-        if (Boolean.TRUE.equals(iotReady)) {
-            stream = stream.filter(c -> c.iotProfile != null);
+                "INNER JOIN service_replacements sr ON sr.replacement_service_id = s.id ");
+        if (needsIotJoin) {
+            sql.append("INNER JOIN iot_profiles ip ON ip.service_id = s.id ");
        }
+        sql.append("WHERE sr.deprecated_service_id = :depId AND s.registry_status = 'ACTIVE'");
        if (deviceClass != null && !deviceClass.isBlank()) {
-            stream = stream.filter(c -> c.iotProfile != null
-                    && c.iotProfile.deviceClasses != null
-                    && c.iotProfile.deviceClasses.contains(deviceClass));
+            sql.append(" AND ip.device_classes @> jsonb_build_array(:deviceClass)");
        }
        if (protocol != null && !protocol.isBlank()) {
-            stream = stream.filter(c -> c.iotProfile != null
-                    && c.iotProfile.protocols != null
-                    && c.iotProfile.protocols.contains(protocol));
+            sql.append(" AND ip.protocols @> jsonb_build_array(:protocol)");
        }

+        Query q = em.createNativeQuery(sql.toString(), ServiceEntity.class)
+                .setParameter("depId", deprecatedId);
+        if (deviceClass != null && !deviceClass.isBlank()) q.setParameter("deviceClass", deviceClass);
+        if (protocol   != null && !protocol.isBlank())     q.setParameter("protocol", protocol);
+
+        List<ServiceEntity> candidates = q.getResultList();
+        OLevel minOLevel = minOLevelStr != null ? OLevel.valueOf(minOLevelStr) : null;
+
        return new ReplacementsResponse(
                deprecated.locked,
                deprecated.sunsetAt,
-                stream
+                candidates.stream()
+                        .filter(c -> minOLevel == null || c.olevel.ordinal() >= minOLevel.ordinal())
                        .sorted(Comparator.comparingInt((ServiceEntity c) -> c.olevel.ordinal()).reversed())
                        .map(c -> new ReplacementsResponse.Candidate(
                                c.id, c.bsmPayload.name(), c.endpointUrl, c.olevel, c.serviceStage,
@@ -377,7 +377,7 @@ public class SandboxService {
            em.createNativeQuery(
                    "INSERT INTO sandbox_feedback " +
                    "(sandbox_id, scores, agent_identifier, comment, model_identifier, model_provider) " +
-                    "VALUES (:sid, :scores::jsonb, :agent, :comment, :modelId, :modelProvider)")
+                    "VALUES (:sid, CAST(:scores AS jsonb), :agent, :comment, :modelId, :modelProvider)")
                    .setParameter("sid", sandboxId)
                    .setParameter("scores", scoresJson)
                    .setParameter("agent", req.agentIdentifier())
@@ -454,6 +454,87 @@ public class SandboxService {
                schemaLinks);
    }

+    @SuppressWarnings("unchecked")
+    public AdminSandboxListResponse listAllSandboxes(int page, int size, String tierFilter) {
+        String tierClause = (tierFilter != null && !tierFilter.isBlank()) ? " AND s.tier = :tier" : "";
+
+        String countSql = "SELECT COUNT(*) FROM sandboxes s WHERE 1=1" + tierClause;
+        String listSql =
+                "SELECT s.id, s.name, s.tier, s.rate_per_minute, s.max_services, " +
+                "s.created_at, s.expires_at, s.registrar_location, s.registrar_lat, s.registrar_lon, " +
+                "COALESCE((SELECT COUNT(*) FROM services sv WHERE sv.sandbox_id = s.id::text), 0), " +
+                "COALESCE((SELECT SUM(request_count) FROM sandbox_usage_stats u WHERE u.sandbox_id = s.id::text), 0) " +
+                "FROM sandboxes s WHERE 1=1" + tierClause +
+                " ORDER BY s.created_at DESC LIMIT :lim OFFSET :off";
+
+        var countQ = em.createNativeQuery(countSql);
+        var listQ  = em.createNativeQuery(listSql);
+        if (!tierClause.isBlank()) {
+            countQ.setParameter("tier", tierFilter.toUpperCase());
+            listQ.setParameter("tier", tierFilter.toUpperCase());
+        }
+        listQ.setParameter("lim", size).setParameter("off", page * size);
+
+        long total = ((Number) countQ.getSingleResult()).longValue();
+        Instant now = Instant.now();
+
+        List<AdminSandboxSummary> rows = ((List<Object[]>) listQ.getResultList()).stream()
+                .map(r -> new AdminSandboxSummary(
+                        r[0].toString(),
+                        (String) r[1],
+                        (String) r[2],
+                        ((Number) r[3]).intValue(),
+                        r[4] != null ? ((Number) r[4]).intValue() : null,
+                        r[5] instanceof java.sql.Timestamp t ? t.toInstant() : null,
+                        r[6] instanceof java.sql.Timestamp t ? t.toInstant() : null,
+                        r[6] instanceof java.sql.Timestamp t && now.isAfter(t.toInstant()),
+                        (String) r[7],
+                        r[8] != null ? ((Number) r[8]).doubleValue() : null,
+                        r[9] != null ? ((Number) r[9]).doubleValue() : null,
+                        ((Number) r[10]).longValue(),
+                        ((Number) r[11]).longValue()))
+                .toList();
+
+        return new AdminSandboxListResponse(total, page, size, rows);
+    }
+
+    @SuppressWarnings("unchecked")
+    public AdminStatsResponse getGlobalStats() {
+        Instant now = Instant.now();
+
+        long total   = ((Number) em.createNativeQuery("SELECT COUNT(*) FROM sandboxes").getSingleResult()).longValue();
+        long active  = ((Number) em.createNativeQuery("SELECT COUNT(*) FROM sandboxes WHERE expires_at > now()").getSingleResult()).longValue();
+        long expired = total - active;
+
+        List<Object[]> tierRows = em.createNativeQuery(
+                "SELECT tier, COUNT(*) FROM sandboxes GROUP BY tier ORDER BY tier")
+                .getResultList();
+        Map<String, Long> byTier = new LinkedHashMap<>();
+        for (Object[] r : tierRows) byTier.put((String) r[0], ((Number) r[1]).longValue());
+
+        long totalServices = ((Number) em.createNativeQuery(
+                "SELECT COUNT(*) FROM services").getSingleResult()).longValue();
+
+        long totalRequests = 0;
+        Object reqResult = em.createNativeQuery(
+                "SELECT COALESCE(SUM(request_count), 0) FROM sandbox_usage_stats").getSingleResult();
+        if (reqResult != null) totalRequests = ((Number) reqResult).longValue();
+
+        List<Object[]> geoRows = em.createNativeQuery(
+                "SELECT registrar_lat, registrar_lon, name, tier FROM sandboxes " +
+                "WHERE registrar_lat IS NOT NULL AND registrar_lon IS NOT NULL")
+                .getResultList();
+        List<AdminStatsResponse.GeoPoint> points = geoRows.stream()
+                .map(r -> new AdminStatsResponse.GeoPoint(
+                        ((Number) r[0]).doubleValue(),
+                        ((Number) r[1]).doubleValue(),
+                        (String) r[2],
+                        (String) r[3]))
+                .toList();
+
+        return new AdminStatsResponse(total, active, expired, byTier, totalServices, totalRequests, points);
+    }
+
    public SandboxLinks sandboxLinks(String base) {
        return sandboxLinks(base, null);
    }
@@ -41,6 +41,20 @@ demo.api-index.org {
 	header -Server
 }

+admin.api-index.org {
+	reverse_proxy admin-a:8084 admin-b:8084 {
+		lb_policy       first
+		health_uri      /q/health/live
+		health_interval 5s
+		fail_duration   30s
+	}
+	header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
+	header X-Content-Type-Options "nosniff"
+	header X-Frame-Options "DENY"
+	header Referrer-Policy "strict-origin"
+	header -Server
+}
+
 git.api-index.org {
 	reverse_proxy gitea:3001
 	header Strict-Transport-Security "max-age=31536000; includeSubDomains"
@@ -0,0 +1,8 @@
+FROM eclipse-temurin:21-jre-alpine
+RUN addgroup -S apix && adduser -S apix -G apix
+WORKDIR /app
+COPY apix-admin/target/quarkus-app/ quarkus-app/
+RUN chown -R apix:apix /app
+USER apix
+EXPOSE 8084
+ENTRYPOINT ["java", "-jar", "quarkus-app/quarkus-run.jar"]
@@ -173,6 +173,38 @@ services:
      retries: 3
    restart: unless-stopped

+  # ── Admin UI (a/b) ────────────────────────────────────────────────────────
+
+  admin-a:
+    image: apix-admin:latest
+    environment:
+      APIX_REGISTRY_URL: http://registry-a:8180
+      APIX_API_KEY: ${APIX_API_KEY}
+      LOG_LEVEL: ${LOG_LEVEL:-INFO}
+    depends_on:
+      - registry-a
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://localhost:8084/q/health/live || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+    restart: unless-stopped
+
+  admin-b:
+    image: apix-admin:latest
+    environment:
+      APIX_REGISTRY_URL: http://registry-b:8180
+      APIX_API_KEY: ${APIX_API_KEY}
+      LOG_LEVEL: ${LOG_LEVEL:-INFO}
+    depends_on:
+      - registry-b
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://localhost:8084/q/health/live || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+    restart: unless-stopped
+
  # ── Edge proxy ────────────────────────────────────────────────────────────

  caddy:
@@ -18,6 +18,7 @@
        <module>apix-spider</module>
        <module>apix-portal</module>
        <module>apix-demo</module>
+        <module>apix-admin</module>
    </modules>

    <properties>
@@ -59,24 +59,27 @@ docker build -f infra/Dockerfile.registry -t apix-registry:latest . -q
 docker build -f infra/Dockerfile.portal   -t apix-portal:latest   . -q
 docker build -f infra/Dockerfile.demo     -t apix-demo:latest     . -q
 docker build -f infra/Dockerfile.spider   -t apix-spider:latest   . -q
+docker build -f infra/Dockerfile.admin    -t apix-admin:latest    . -q

 # ── 4. Rolling restart: a-stack (registry-a → portal-a + demo-a) ─────────────
 log "Rolling restart: a-stack..."
 $COMPOSE up -d --no-deps --force-recreate registry-a
 wait_healthy "registry-a"

-$COMPOSE up -d --no-deps --force-recreate portal-a demo-a
+$COMPOSE up -d --no-deps --force-recreate portal-a demo-a admin-a
 wait_healthy "portal-a"
 wait_healthy "demo-a"
+wait_healthy "admin-a"

 # ── 5. Rolling restart: b-stack ───────────────────────────────────────────────
 log "Rolling restart: b-stack..."
 $COMPOSE up -d --no-deps --force-recreate registry-b
 wait_healthy "registry-b"

-$COMPOSE up -d --no-deps --force-recreate portal-b demo-b
+$COMPOSE up -d --no-deps --force-recreate portal-b demo-b admin-b
 wait_healthy "portal-b"
 wait_healthy "demo-b"
+wait_healthy "admin-b"

 # ── 6. Spider (cron job — restart acceptable) ─────────────────────────────────
 log "Restarting spider..."
@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# promote-sandbox.sh — Promote a sandbox tier + fetch demo ecosystem UUID
+# Run on the server: bash promote-sandbox.sh
+set -euo pipefail
+
+ENV_FILE="/opt/apix/.env"
+REGISTRY="https://api-index.org"
+
+# ── Adjust these ───────────────────────────────────────────────────────────────
+SANDBOX_ID="25321050-4707-4e85-bd9f-877ab04e4a55"
+NEW_TIER="COMMUNITY"
+# ──────────────────────────────────────────────────────────────────────────────
+
+ADMIN_KEY=$(grep -oP '(?<=APIX_API_KEY=).+' "$ENV_FILE" | tr -d '[:space:]')
+
+if [[ -z "$ADMIN_KEY" ]]; then
+  echo "ERROR: APIX_API_KEY not found in $ENV_FILE" >&2
+  exit 1
+fi
+
+echo "==> Promoting sandbox $SANDBOX_ID to $NEW_TIER ..."
+curl -s -X PATCH "$REGISTRY/sandbox/admin/$SANDBOX_ID/tier" \
+  -H "X-Admin-Key: $ADMIN_KEY" \
+  -H "Content-Type: application/json" \
+  -d "{\"tier\":\"$NEW_TIER\"}" | python3 -m json.tool
+
+echo ""
+echo "==> Demo ecosystem sandbox UUID ..."
+docker exec "$(docker ps -qf name=demo-a)" \
+  psql -U apix -d apix -t -A \
+  -c "SELECT value FROM demo_config WHERE key='sandbox.id';"
@@ -11,6 +11,12 @@ info() { echo -e "${GREEN}[apix]${NC} $*"; }
 warn() { echo -e "${YELLOW}[warn]${NC} $*"; }
 die()  { echo -e "${RED}[fail]${NC} $*" >&2; exit 1; }

+_on_exit() {
+  echo ""
+  read -rp "Press Enter to close…" _
+}
+trap _on_exit EXIT
+
 warn "This will DROP and recreate the local 'apix' database."
 read -rp "Continue? [y/N] " confirm
 [[ "${confirm,,}" == "y" ]] || { echo "Aborted."; exit 0; }
@@ -58,12 +64,5 @@ for i in $(seq 1 30); do
  sleep 1
 done

-info "Running Liquibase migrations"
-mvn -q liquibase:update -pl apix-registry \
-  -Dliquibase.url="jdbc:postgresql://localhost:${DB_PORT}/${DB_NAME}" \
-  -Dliquibase.username="$DB_USER" \
-  -Dliquibase.password="$DB_PASS"
-info "Migrations applied"
-
-info "Reset complete — starting dev servers"
-"$SCRIPT_DIR/dev.sh"
+info "Reset complete — starting dev servers (Quarkus applies migrations at startup)"
+exec "$SCRIPT_DIR/dev.sh"
@@ -13,6 +13,9 @@ TARGET="${1:-all}"
 GREEN='\033[0;32m'; NC='\033[0m'
 info() { echo -e "${GREEN}[apix]${NC} $*"; }

+_on_exit() { echo ""; read -rp "Press Enter to close…" _; }
+trap _on_exit EXIT
+
 # ── tmux mode ────────────────────────────────────────────────────────────────
 if command -v tmux &>/dev/null && tmux has-session -t apix-dev 2>/dev/null; then
  _restart_window() {
@@ -116,27 +116,13 @@ for i in $(seq 1 30); do
  sleep 1
 done

-# ── 6. Liquibase migrations ───────────────────────────────────────────────────
+# ── 6. Note on migrations ─────────────────────────────────────────────────────
 step "Database migrations"
-JDBC_URL="jdbc:postgresql://localhost:${DB_PORT}/${DB_NAME}"
-
-if [[ ! -f "$PROJECT_ROOT/pom.xml" ]]; then
-  warn "No pom.xml found — Maven project not scaffolded yet (WORKLOG Block 1 / C-00)."
-  warn "Skipping Liquibase migrations. Run this script again after completing Block 1."
-else
-  # apix-registry depends on apix-common and apix-verification; install them
-  # to the local repository first so Maven can resolve them during the
-  # liquibase:update goal (no source files yet — this completes in seconds).
-  info "Installing shared modules to local repository…"
-  mvn -q install -pl apix-common,apix-verification -DskipTests
-
-  info "Running Liquibase migrations on $JDBC_URL"
-  mvn -q liquibase:update -pl apix-registry \
-    -Dliquibase.url="$JDBC_URL" \
-    -Dliquibase.username="$DB_USER" \
-    -Dliquibase.password="$DB_PASS"
-  info "Migrations applied"
-fi
+# Migrations are applied automatically by Quarkus at startup via
+# quarkus.liquibase.migrate-at-start=true. Running them separately via the
+# Maven Liquibase plugin records a different classpath prefix in DATABASECHANGELOG
+# than Quarkus uses, causing a "relation already exists" conflict on next start.
+info "Migrations will run automatically when Quarkus starts (migrate-at-start=true)."

 # ── Done ──────────────────────────────────────────────────────────────────────
 echo ""