keystone/docs/ui-review.md

Keystone UI Gap Review

A full audit of the current Vue/Inertia UI in resources/js/pages/ against docs/implementation-spec.md. Findings are grouped by spec section/feature. Each gap lists what is missing, where the relevant code lives today, and a suggested resolution.

Conventions:

• Missing — feature has no UI surface at all.
• Partial — surface exists but does not cover the spec.
• Broken — surface exists but has a bug or dead code path.

---

1. Global Navigation & Information Architecture

• Partial — sidebar only exposes Dashboard + Servers. resources/js/components/AppSidebar.vue:19-37 builds a mainNavItems array with only Dashboard and Servers. There are no entries for Applications, Operations, Onboarding, or organisation Settings. The spec frames environments as the primary surface (§20 Phase 6: "Present environments as the primary application surface"). Add at minimum Applications and Operations items, plus a context switcher / link to onboarding while incomplete.
• Missing — no organisation switcher. Multiple organisations are modeled (Organisation::members() on app/Models/Organisation.php), and the dashboard already supports multiple orgs (resources/js/pages/Dashboard.vue:8-13). After picking an org there is no way to switch without going back to /dashboard. Add a switcher in the sidebar header.
• Missing — no Operations index. Operations are the spec's audit/execution backbone (§3) but the UI only surfaces them inline on environments/Show.vue and servers/Show.vue. There is no organisation-wide operations feed for triage. Add an operations.index view with filters (kind, status, target).
• Missing — no global empty/help state. A fresh org with no servers/apps has no "Get started" CTA in the sidebar; user must guess to visit /onboarding. Promote the onboarding link until all onboarding steps are complete.

2. Onboarding (Spec §19)

• Partial — onboarding page exists but is unreachable from primary nav. resources/js/pages/onboarding/Show.vue is only reachable via the URL /organisations/{id}/onboarding. There is no link from Dashboard, AppSidebar, or organisations/Show.vue. Surface a persistent banner or sidebar entry while nextStep is non-terminal.
• Partial — onboarding "Provider" step routes to organisation show. app/Http/Controllers/OnboardingController.php:25 sets the Provider step href to organisations.show, but the Server Providers list there (resources/js/pages/organisations/Show.vue:202-220) has no Add button. There is no providers.create route or page. Either add a ProviderController@create + Vue page or make the step open an inline dialog.
• Missing — registry/source/server-create steps don't enforce a single org-level "default" once configured. Spec §19 says registry is required for multi-server. The UI never blocks deployment on this — see Deployment Flow gap below.
• Missing — onboarding doesn't reflect deploy-key install step (§5). The spec lists "Deploy key installation and verification" as a discrete step; onboarding shows none. Add a step gated on applications.deploy_key_installed_at.

3. Organisation & Provider Management

• Missing — server-provider UI is read-only. resources/js/pages/organisations/Show.vue:202-220 lists providers but offers no add/edit/delete. There is no ProviderController registered (see routes/web.php). The Hetzner provider must currently be seeded outside the UI.
• Missing — registry/source-provider lists have no edit/delete. Only create and store are wired (routes/web.php:33-41). Users can produce duplicate registries with bad credentials and never repair them.
• Missing — no organisation member management. organisations/Show.vue:111-122 shows a members count with no roster, invite flow, role editor, or removal. The members() BelongsToMany on Organisation is unused by the UI.
• Partial — registry credentials cannot be rotated. No edit page; the only fix is delete-and-recreate, but delete is also missing. Add registries.edit + registries.update.

4. Source Providers & Repository Access (Spec §5)

• Partial — deploy-key card disappears once installed. resources/js/pages/applications/Show.vue:46-75 only shows the deploy-key card when application.deploy_key_public && !application.deploy_key_installed_at. After install there is no way to view or rotate the key. Show key + deploy_key_fingerprint and a "Rotate" action permanently in an Application Settings tab.
• Missing — no fingerprint display. The model stores deploy_key_fingerprint (app/Models/Application.php), but the UI never renders it. Surface beside the public key for verification.
• Missing — no way to re-run git ls-remote verification after install. Verify button is gated by the same conditional in applications/Show.vue:46. Move it to an always-available action; spec §5 implies verification can be re-run.
• Missing — application creation does not pick a source provider. resources/js/pages/applications/Create.vue collects repository_url as a free string. Source providers exist (§5: Gitea/GitHub/generic Git) but the form never references them — users have no guidance for which provider corresponds to the URL, and application.source_provider_id is not captured.
• Missing — repository type selector. Spec lists repository_type (§2 Application). UI hardcodes RepositoryType::GIT (app/Http/Controllers/ApplicationController.php:39). Even if Git is the only v1 type, the form should display the resolved type.

5. Applications & Environments (Spec §2, §6, §17)

Applications

• Missing — no Application edit/delete. Only index/show/create/store are routed (routes/web.php:62-66). Renaming or removing an app requires DB intervention.
• Missing — environment creation UI. The initial environment is auto-created in ApplicationController@store (CreateLaravelEnvironment). There is no "Add environment" affordance on applications/Show.vue, despite the spec describing multiple environments (production/staging/dev) as the primary deployment unit (§2).
• Broken — Applications/Index uses wrong key + has no empty state. resources/js/pages/applications/Index.vue:46 writes :key=\application{$applications.id}`(literal$applications). Replace with :key="application.id"and render an empty card whenapplications.length === 0`.
• Partial — Application Show has no overview. No "last deployed at", no current commit, no current image digest. Spec §6 stores current_image_digest on Service and BuildArtifact per environment but neither is rendered.

Environments

• Missing — environment-level edit page. Cannot change branch, name, status, scheduler_enabled, scheduler_target_service_id, scheduler_mode, or build_config (spec §2). All are dead fields in the DB from the UI's perspective.
• Missing — branch change / redeploy with a specific commit. Deploy is a fire-and-forget POST (environments/Show.vue:63-76 and applications/Show.vue:139-153). The spec resolves a "target commit" (§17 step 1) — there is no commit picker or branch switcher in the UI.
• Missing — build artifact view per environment. BuildArtifact exists with status/digest/registry_ref but is not rendered on environments/Show.vue. Add a "Builds" section showing recent artifacts and their status.
• Missing — scheduler controls (Spec §8). No UI for scheduler_enabled, scheduler_target_service_id, or scheduler_mode. The spec explicitly says scheduler is a role/capability and that v1 should expose it. Add to environment settings tab and surface "Scheduler runs on: " on the environment overview.
• Missing — migration policy controls (Spec §18). migration_mode, migration_timing, migration_command are spec fields on a service. The UI has only a one-off Migrate button (environments/Show.vue:77-91); there is no form to inspect/change defaults per service.
• Partial — environment header buttons are crowded. resources/js/pages/applications/Show.vue:123-211 packs Open / Deploy / Migrate / Env / Worker / Attach into a single card row. On md screens this overflows. Move secondary actions into a dropdown.
• Missing — environment delete. Spec implies environments are mutable units (§2); UI has no delete.

6. Services (Spec §2 Service, §7, §9, §11)

Service list / show

• Missing — no service-by-environment scoping. services/Show.vue does not show its parent environment (only server + service). Reaching a service from an environment requires service.server_id to be set (environments/Show.vue:138-153); environments where the service is server-less (replicas only) cannot be opened. Show environment breadcrumb when present.
• Missing — replica detail view. services/Show.vue:62-79 lists replicas but they are inert. Spec §2 ServiceReplica has cpu_limit, memory_limit_mb, container_id, internal_host, internal_port, public_port, image_digest, health_status. Tap-through to a replica detail with logs/restart action is missing.
• Missing — start/stop/restart actions on replicas. Status badges show status and health_status (services/Show.vue:73-77) but no buttons.
• Missing — endpoint listing. app/Models/ServiceEndpoint.php exists and Spec §14 defines an endpoint model (scope: docker_network/private_network/public, hostname/ip/port/priority). UI never renders endpoints. Add an "Endpoints" card on services/Show.vue.
• Missing — compose preview / generated artifact view. Spec §16 establishes generated Compose under /home/keystone/services/<service-id>/compose.yml. There is no UI to inspect/render it. Add a "Compose" tab on services/Show.vue (read-only, syntax-highlighted).
• Missing — process_roles editor. Service has process_roles JSON (spec §2). Used by scheduler role attachment (§8). No UI exposes it.

Service edit (services/Edit.vue)

• Partial — only name, desired_replicas, default_cpu_limit, default_memory_limit_mb editable. Missing: deploy_policy, version_track, available_image_digest (acknowledge available update), config overrides (migration_mode/timing/command per §18), scheduler flags for app services.
• Missing — health-check / health-path override. Spec §7 defaults health path to /up. No UI surfaces or overrides.

Service create

• Missing — builder service category in practice. ServiceCategory::BUILDER exists and Spec §6 says "A dedicated builder is represented as a Service with category builder". The Create flow shows the BUILDER radio (it loops over the enum) but services/Create.vue:111-122 only lists services[form.category] from config('keystone.services') — there is no entry for builder there, so selecting builder shows an empty type list with no message. Either remove BUILDER from the radio set or wire builder driver options.
• Missing — selecting category doesn't surface deploy_policy defaults. Spec §2 defines deploy_policy defaults per category. The form does not show or let the user accept them.

Stateful service updates (Spec §11)

• Partial — update form exists but exposes raw digest. resources/js/pages/services/updates/Create.vue:74-82 requires the user to paste an image digest. The available digest is pre-filled from service.available_image_digest, but Postgres/Valkey users will not know how to obtain a different digest. Replace with a "latest minor" resolver and a manual override (spec §9: "resolving image tags to digests"; §11 implies guided update).
• Partial — backup checkbox visible only when backup_enabled config flag is set. Spec §11 step 3 says "Optional backup checkbox appears only if backup capability exists" — current code matches the letter, but the UI never lets the user enable backups in the first place, so the checkbox is unreachable.
• Missing — downtime acknowledgement. Spec §11 step 2 says "Keystone warns about downtime and data risk." Current warning is generic. Show a hard confirmation step ("type the service name to confirm").

7. Slices & Attachments (Spec §12, §13)

• Missing — slice index per service. services/Show.vue:81-95 lists slices with name + type only — no operations, no credentials view, no detail page, no create from service-detail (spec §12: "Advanced users can select existing slices or create slices manually from service detail pages").
• Missing — slice create UI. No slices.create route or page. Spec §12 explicitly requires this for advanced users.
• Missing — slice operations are not independent in the UI. Spec §12: "Slice operations should be independent from service container deployments." Backend distinguishes slice_provision/slice_configure operations (§3), but UI only shows them mixed into the service's operations list (services/Show.vue:97-117).
• Missing — env-var preview for attachments. Spec §13 enumerates DB_* / REDIS_* exports. The attachment form (environment-attachments/Create.vue) shows only "Generated " with no preview of what variables will be written. Add a preview block.
• Missing — attachment edit/detach. environments/Show.vue:184-204 lists attachments inertly — no detach button, no edit. Recovering from a wrong attachment requires DB intervention.
• Partial — attachment form's role/service compatibility is hardcoded in JS. environment-attachments/Create.vue:37-48 keeps role-to-service-type mapping client-side. If the backend adds queue support via Postgres listen/notify or storage via Caddy, this map drifts. Push the compatibility matrix from the controller.
• Missing — is_primary semantics aren't explained. A checkbox labeled "Primary attachment" with no helper text; users don't know when to uncheck.

8. Environment Variables (Spec §13)

• Partial — variables UI is add-only. environment-variables/Create.vue only POSTs. There is no edit, no delete, no value reveal, no bulk import (.env paste). Managed values show as badges (environments/Show.vue:206-235) but cannot be inspected or overridden.
• Missing — overridable toggle. Spec §2 EnvironmentVariable has overridable. The UI never surfaces it; all user-created variables silently become overridable: true (EnvironmentVariableController::store).
• Missing — source/slice provenance display. Managed/system variables should "show their source and whether they are overridable" per spec §13. Currently rendered as <source> text only; no link back to the slice/attachment that generated them.
• Missing — secret vs. plain value distinction. No marker, no masking, no copy button.

9. Servers (Spec §4)

• Broken — <template> block has dangling fallback. resources/js/pages/servers/Show.vue:217 reads <template> Something else </template> outside any v-if/v-else-if chain. This is a stray Vue <template> rendered literally for any status that isn't active or provisioning — clean up or convert to <template v-else>.
• Partial — provisioning UI is decorative. servers/Show.vue:27-39 cycles through fake messages on an interval. No actual progress, no association to the running server_provision operation (spec §3 OperationKind). Tie the cycling messages to real operation_steps events.
• Missing — server delete / decommission. Not wired anywhere; only index/show/create/store routes registered (routes/web.php:43-47).
• Missing — firewall-rule UI. app/Models/FirewallRule.php and Server::firewallRules() exist. Spec §4 step 8 says UFW with SSH open, but additional rules (e.g. for Caddy 80/443, private network) are not surfaced. Add a Firewall tab on servers/Show.vue.
• Missing — credential persistence/regen. "WILL NOT BE SHOWN AGAIN" (servers/Show.vue:219-224) appears via flash only; if the user navigates away without copying, the only credential they have is the SSH key Keystone manages. Acceptable, but should explicitly say "Keystone uses an SSH key for all subsequent operations; this password is informational."
• Missing — re-provision/heal action. If provisioning fails there is no retry button on the show page.
• Missing — service add gated on server active status. servers/Show.vue:75-94 only renders the Add button when status is active, but during provisioning there is no informative message about why services can't be added (the cycling messages run but the section disappears entirely). Show a disabled "Add" with tooltip.
• Missing — operations list does not show parent-child structure. servers/Show.vue:138-196 shows steps under each operation but flat. Spec §3 emphasises parent-child (environment_deploy → service_deploy → replica_deploy). Render as a tree.

10. Operations & Logs (Spec §3)

• Partial — step log dialog only on server show. servers/Show.vue:226-245 is the only place a user can read full step logs. Service Show and Environment Show both list operations without log expansion. Promote the log dialog to a shared component and use it everywhere operations appear.
• Missing — operation detail page. Spec §3 implies operations are first-class. There is no operations.show page. Cannot view secrets used, parent op, retry, cancel, or download logs.
• Missing — retry / abort actions. Failed operations are terminal in the UI; spec doesn't forbid retry. Add at least a "Re-run operation" button on the operation detail page.
• Missing — operation hash / kind / target column. Operation::hash is generated but never displayed; useful for support and correlation with server-side /home/keystone/operations/<operation-hash>/ directories (spec §16).
• Missing — live progress. Operations require a refresh to update. Inertia v2 WhenVisible + polling exists in this app (used in organisations/Show.vue:126); apply to operations.

11. Build Artifacts & Registry (Spec §6)

• Missing — no build artifact UI. BuildArtifact model + PlanBuildArtifact/BuildApplicationArtifact actions exist, but there is no listing per environment or per registry. Users cannot see whether a build is pending, building, available, or failed.
• Missing — registry usage indicator. Spec §19: "If an environment spans more than one server and no registry exists, deployment should be blocked with a registry setup prompt." UI does not surface this precondition anywhere — deploy button is always live on applications/Show.vue:139-153. Add a pre-deploy check.
• Missing — build strategy selector. Spec §6: target_server / dedicated_builder / external_registry. There is no UI to choose. Currently the strategy lives in BuildArtifact.metadata['build_strategy'] only.
• Missing — registry detail page. No way to see which artifacts have been pushed where.

12. Gateway / Caddy (Spec §15)

• Missing — domain / route configuration UI. Caddy attachment is supported (environment-attachments/Create.vue:39-48) but the form does not collect a domain, TLS preference, or path prefix. Spec §15 requires explicit gateway routes; spec §12 says "Caddy/domain attachment: Create route slice. Wire gateway route to environment web service." There is no domain input anywhere in the UI.
• Missing — TLS / certificate status view. No surface to see whether Caddy has issued a cert.
• Missing — Caddyfile preview. Similar to compose preview — spec §16 places it at /home/keystone/gateway/Caddyfile. Should be viewable.
• Missing — cutover visualisation. Spec §15 lays out the cutover sequence (render → health → upstream add → reload → drain → stop). UI has no visualisation; users get a generic deploy progress only.

13. Networking (Spec §14)

• Missing — endpoint surface entirely. Spec defines an endpoint model with scope/hostname/ip_address/port/priority/health_status. The model class exists (app/Models/ServiceEndpoint.php) but is never rendered.
• Missing — private-network membership view. Network model and Server::network() exist; spec §14 prefers same-provider private IPs. UI never shows which servers share which networks.

14. Dashboard & Welcome

• Partial — Dashboard is a single card. Dashboard.vue:27-44 lists organisations only. Once an org is picked, no summary of pending operations, recent deploys, or failing services on the main dashboard. Add "Recent operations" + "Unhealthy services" panels.
• Missing — no aggregated health. Organisation Show (organisations/Show.vue:65-123) shows counts but not health (provisioning servers, failed last deploy, locked attachments).

15. Visual & UX Polish

• Inconsistent — script tags mix <script setup lang="ts"> and <script setup>. E.g. pages/environments/Show.vue:1 is plain JS while pages/applications/Show.vue:1 is TypeScript. Pick a default and apply.
• Inconsistent — typed props. Several Show pages declare defineProps({ application: { type: Object, required: true }, ... }) with no TS interfaces. New pages should use defineProps<{...}>() shapes.
• Inconsistent — breadcrumb depth. Service Show breadcrumb (services/Show.vue:18-33) goes Servers → server → service, but an environment-scoped service should also show the environment in the trail.
• Accessibility — radio button groups in Create flows. servers/Create.vue and services/Create.vue use RadioButton but render via v-for with no :key on the radios. Visual-only impact today, but a11y-wise the labelling could be tightened (associate description text with aria-describedby).
• Accessibility — colour-only status. ServiceCard.vue:38-58 uses small dots + colour classes for status with no text alternative beyond the status string. Verify contrast in light mode.
• Empty states — Applications/Servers indexes have none. A new organisation hits a blank grid. Render an illustration + CTA pointing to onboarding.

16. Routes & Controllers Backing the UI

These backend gaps directly produce the UI gaps listed above. Filling the UI will require new routes/controllers (or destroy actions on existing ones):

• providers.create/store/destroy (organisation provider mgmt)
• registries.index/edit/update/destroy
• source-providers.index/edit/update/destroy
• applications.edit/update/destroy
• environments.create/store/edit/update/destroy
• environments.scheduler (settings sub-resource)
• services.destroy and service-level slice mgmt (services/{service}/slices.*)
• service-replicas.show/restart
• environment-variables.update/destroy/index
• environment-attachments.destroy/update
• operations.index/show/retry
• build-artifacts.index/show
• servers.destroy, servers.firewall-rules.*
• domains.* / gateway.routes.* for Caddy

---

17. Suggested Priorities

To bring the UI in line with spec without inflating scope:

1. Make environments the primary surface (spec §20 Phase 6). Sidebar entry, environment overview tab, environment edit page covering branch + scheduler + build config + migration policy.
2. Fix the deploy preconditions and visibility loop. Block deploy when no registry + multi-server (§19). Show build artifact + commit + image digest after deploy.
3. Promote operations to first-class. operations.index, operations.show, log dialog reused across pages, parent-child tree, retry.
4. Round out CRUD for org-level resources (providers, registries, source providers, members). Currently all "configured once via DB" surfaces.
5. Slice + attachment maintenance. Edit/detach/preview env-var exports.
6. Gateway/domain UX. Domain input on Caddy attachment, route slice view, Caddyfile preview.
7. Polish: fix servers/Show.vue dangling <template>, fix applications/Index.vue :key, add empty states, unify script lang.