# Portal - Current State

Verified against the local Portal repo after the dashboard/nav cleanup pass, fresh API and Agent repo review, server status/host lifecycle/IDE UX pass, public marketing/SEO refresh, mobile responsiveness pass, and server create/delete/status follow-up fixes.

This file records what is implemented now.

## Runtime / tooling baseline
- Portal is now aligned to the Node 24 runtime line used by the API repo.
- `.nvmrc`, `package.json` engines, and `package-lock.json` are synchronized on the current Node 24 baseline.
- Lint no longer relies on removed `next lint`; the repo uses `eslint .` with the Next 16 flat-config path.
- The lint configuration has been adjusted so current project patterns lint cleanly without forcing a broad React-compiler-style refactor.
- `npm run lint` passes with only existing React hook dependency warnings.
- `npm run build` reportedly passes on Next 16.2.4 with Turbopack.
- npm audit is reported clean at moderate-or-higher severity.

## Repo cleanup already done
- Confirmed-unused HUD wrapper components have been removed.
- Stale `src/styles.old/*` legacy CSS has been removed.
- Unused `js-cookie` type shim has been removed.
- Unused dependencies and Tailwind plugins have reportedly been pruned from the Portal repo.
- The Portal cleanup pass reports net line-count reduction rather than growth.

## Public marketing / SEO site
- Public marketing now follows a hybrid SaaS structure:
  - homepage acts as the conversion flow
  - separate pages support deeper product/SEO intent
- Homepage now includes:
  - hero with platform-neutral copy: `Code, test, and run servers from your browser.`
  - browser/dev + managed server subheadline
  - product-style visual panel
  - Build / Test / Ship workflow
  - differentiators
  - use cases
  - SEO topic links
  - pricing preview
  - FAQ preview
  - final CTA
- Root metadata has been updated from the old game-hosting-only description to browser dev environments + managed server hosting positioning.
- Pricing has been repositioned from `Vanilla / Modded / Heavy` to workload tiers:
  - Starter
  - Pro
  - Performance
- Pricing copy now states that every plan includes a browser-based dev environment and managed server hosting.
- Public feature copy now presents the platform as build/test/run rather than Minecraft-only hosting.
- LXC/system-container differentiator is represented carefully as avoiding Docker-style game-server overhead without unsupported benchmark claims.
- The fake `zlh build --target server` hero command was removed and replaced with a real/plausible `$ npm run build` line.
- Public SEO/intent pages have been added:
  - `/minecraft-server-hosting`
  - `/modded-minecraft-hosting`
  - `/browser-dev-environment`
- Metadata has been added or refreshed for Home, Features, Pricing, FAQ, About, Support, and the three SEO landing pages.
- FAQ has been expanded around platform positioning, dev environments, Minecraft, mods, datapacks, local install expectations, backups/restores, and plan limits.
- Build and lint reportedly pass after the marketing/SEO changes with the same existing unrelated warnings.

## Current mobile status
- A targeted mobile responsiveness pass has been applied across public marketing, SEO landing pages, auth pages, server list, server create, and basic console/file/backup surfaces.
- Public nav now uses a working mobile menu and hides the desktop nav until the larger breakpoint.
- CTA groups, pricing cards, auth forms, server cards, and dashboard shell spacing have been adjusted with responsive Tailwind utilities.
- Complex console/file/backup panels are considered basic-mobile-usable rather than full mobile-native experiences.
- Remaining mobile work should be validation/polish only unless new breakage is observed.

## Readiness / operation UI
- Portal consumes API-normalized state.
- Portal understands:
  - `ready`
  - `operationInProgress`
  - `operationType`
  - `maintenance`
  - `operationStartedAt`
  - `operationMessage`
- targeted `409` and `503` UX messaging exists for operation conflicts and not-ready states.
- server card and game console readiness labels now share explicit mapping for ready, stopped, starting, stopping, restarting, maintenance, provisioning/network-pending, plan-limit, and true error states.
- `connectable === false` no longer automatically maps to `Needs attention`; expected non-connectable states such as stopped servers, host lifecycle actions, backup/restore maintenance, and provisioning use specific user-facing labels.
- game server readiness and dev container readiness are separated in the server list so DEV cards use host/agent/IDE state instead of game `connectable` semantics.
- host/container lifecycle status is surfaced from the LXC host layer, including `Online`, `Offline`, `Starting`, `Stopping`, and `Restarting`, plus active host-operation polling.
- server list refresh waits for per-server status enrichment before committing the merged state, preventing transient IDE/readiness badge flips during polling or page remount.
- server creation now records a pending setup marker and returns the user to `/servers` immediately after submit while the create request completes in the background.
- setup progress can be matched by pending name/type before the API returns a VMID, then by VMID once creation finishes.
- setup-step labels are state-aware; stopping or stopped hosts no longer appear as `installing`/`creating` simply because the host is offline.
- the previous maximum-update-depth loop in server-list creation progress hydration has been fixed by removing state values that were being changed from the polling effect dependency path.

## Metrics UI
- server console metrics continue to poll the API metrics summary route for both DEV and GAME servers.
- Portal normalizes multiple CPU, memory, disk, and network field shapes so API casing/name drift does not leave CPU or network stuck at zero.
- metrics polling sends no-cache headers and a cache-busting query value to avoid stale summary responses.
- if CPU/network still do not move for running servers, the remaining likely cause is API/agent metrics collection or rate calculation rather than Portal rendering.

## Backup UI
- game backup UI exists for:
  - list
  - create
  - restore
  - delete
- Portal uses API routes, not direct agent calls.
- backup metadata is normalized and displayed when the API includes metadata fields.
- backup/restore actions now provide user feedback and progress/elapsed time during active operations.

## Console / action gating
- console command transport uses POST JSON through API.
- previous blanket `ready === false` gating bug for game actions was fixed.
- Start is not blocked merely because a stopped server is not ready.
- backup actions are not blocked purely by `ready === false`; backend validity decides.

## Billing / auth / onboarding
- billing UI alignment exists with the newer billing state model.
- billing plan-limit gating has been observed in Portal create flow.
- forgot/reset password flow exists.
- logged-in change-password flow exists.
- first-login onboarding flow exists.
- Next 16 / current TypeScript cleanup included fixes around nullable normalization and search-param/Suspense usage in affected pages/components.

## Hosted IDE
- console and server-list `Open IDE` actions request `/api/dev/{serverId}/ide-token`.
- Portal opens the hosted URL returned by the API, falling back to the configured API base for relative URLs.
- DEV server console and server-list rows show compact IDE indicators and inline `Open`, `Start`, `Restart`, and `Stop` controls instead of large stacked action blocks.
- code-server service actions call `/api/dev/{serverId}/codeserver/start`, `/api/dev/{serverId}/codeserver/restart`, and `/api/dev/{serverId}/codeserver/stop`.
- Portal preserves last-known IDE state when a polling response omits code-server fields, avoiding UI blips between list and status responses.
- API owns the IDE bootstrap, hosted proxy, and tunnel flow. Portal is not expected to proxy IDE traffic itself.

## API client layer
- Portal uses API-mediated transport rather than direct agent calls.
- the old Portal-internal `/api/agent/{serverId}/{action}` bridge has been removed from the frontend repo.
- server deletion has been migrated from `DELETE /api/containers/{vmid}` to `DELETE /api/servers/{id}` through the normal user JWT API client.
- Portal does not add or expose `INTERNAL_API_TOKEN` in browser code.
- delete UX maps API responses explicitly: `202` as already in progress, `401` as login required, `404` as not owned/missing, `409` as `Stop host before deleting`, and `500` as teardown failure.
- Project cleanup has reportedly removed dead weight around unused wrappers/dependencies, but API-client/status-polling consolidation is not yet considered fully complete.

## Dashboard / IA
- the dashboard spotlight server card now uses API-backed server data instead of placeholder entries.
- the spotlight card no longer links to a non-existent `/servers/{id}` route; it routes users back into the supported `/servers` surface.
- the spotlight card now recognizes DEV containers across API field aliases and mirrors server-list badges, including the IDE indicator, readiness badge, and host status.
- hub navigation now includes Billing and Profile so onboarding tour targets match the actual menu.
- the hub shell now covers authenticated account/control-surface pages including billing, profile, and support instead of only dashboard/servers.

## Still true
- Portal should track API auth / JWT behavior closely because API-side token hardening can require Portal compatibility verification.
- Portal cleanup should remain behavior-preserving; build/lint green status is part of the current baseline.
- Mobile responsiveness is no longer a from-zero open item, but it still needs periodic device/browser validation as UI surfaces change.