From 04927b2ef80a95d11f3532068c5fe94befb22c94 Mon Sep 17 00:00:00 2001
From: Diego Madero Islas <sigilabcodex@gmail.com>
Date: Mon, 18 May 2026 21:41:35 -0600
Subject: [PATCH] Refine admin/setup repository contracts

---
 app/admin/modules/page.tsx                  | 20 ++---
 app/admin/page.tsx                          | 18 ++---
 app/admin/setup/page.tsx                    | 22 ++----
 app/customers/page.tsx                      |  5 +-
 app/entry/page.tsx                          |  5 +-
 app/login/page.tsx                          |  7 +-
 app/page.tsx                                | 23 +++---
 app/setup/page.tsx                          |  3 +-
 components/app-shell.tsx                    | 15 ++--
 components/primary-nav.tsx                  | 41 +++-------
 components/setup/onboarding-quick-start.tsx |  3 +-
 lib/application-planes.ts                   | 74 +++++++++++++++++
 lib/server/actions/admin-core.ts            | 70 ++++++++--------
 lib/server/actions/entry-bootstrap.ts       | 88 ++++++++-------------
 lib/server/application-access.ts            | 17 ++++
 lib/server/demo-data.ts                     |  7 +-
 lib/server/persistence/context.ts           | 48 ++++++++++-
 lib/server/persistence/contracts.ts         |  7 ++
 18 files changed, 280 insertions(+), 193 deletions(-)
 create mode 100644 lib/application-planes.ts
 create mode 100644 lib/server/application-access.ts

diff --git a/app/admin/modules/page.tsx b/app/admin/modules/page.tsx
index d4c0122..f9b3951 100644
--- a/app/admin/modules/page.tsx
+++ b/app/admin/modules/page.tsx
@@ -1,19 +1,13 @@
-import { redirect } from 'next/navigation';
+import { skossCoreRoutes } from '@/lib/application-planes';
 import { moduleRegistry } from '@/lib/modules';
-import { getCurrentUserContext } from '@/lib/server/auth';
-import { readAppData } from '@/lib/server/persistence';
+import { requireAdminPlaneAccess } from '@/lib/server/application-access';
+import { readPersistence } from '@/lib/server/persistence';
 import { updateModuleRegistryAction } from '@/lib/server/actions';
 
 export default async function AdminModulesPage({ searchParams }: { searchParams?: Promise<{ saved?: string }> }) {
-  const [userContext, data, params] = await Promise.all([getCurrentUserContext(), readAppData(), searchParams]);
-
-  if (!userContext.currentUser) {
-    redirect('/login?redirectTo=/admin/modules');
-  }
-
-  if (!userContext.canManageSettings) {
-    redirect('/');
-  }
+  await requireAdminPlaneAccess(skossCoreRoutes.adminModules);
+  const [persistence, params] = await Promise.all([readPersistence(), searchParams]);
+  const moduleStates = persistence.instance.getInstanceState().moduleStates ?? {};
 
   return (
     <div className="page-stack">
@@ -25,7 +19,7 @@ export default async function AdminModulesPage({ searchParams }: { searchParams?
       {params?.saved === 'modules' ? <p className="inline-success">Module settings updated.</p> : null}
       <form action={updateModuleRegistryAction} className="panel page-stack">
         {moduleRegistry.map((module) => {
-          const enabled = module.required || data.instance.moduleStates?.[module.id] !== false;
+          const enabled = module.required || moduleStates[module.id] !== false;
           return (
             <label key={module.id} className="checkbox-row">
               <input
diff --git a/app/admin/page.tsx b/app/admin/page.tsx
index 00228a5..ba4f21d 100644
--- a/app/admin/page.tsx
+++ b/app/admin/page.tsx
@@ -1,17 +1,9 @@
 import Link from 'next/link';
-import { redirect } from 'next/navigation';
-import { getCurrentUserContext } from '@/lib/server/auth';
+import { skossCoreRoutes } from '@/lib/application-planes';
+import { requireAdminPlaneAccess } from '@/lib/server/application-access';
 
 export default async function AdminHomePage() {
-  const userContext = await getCurrentUserContext();
-
-  if (!userContext.currentUser) {
-    redirect('/login?redirectTo=/admin');
-  }
-
-  if (!userContext.canManageSettings) {
-    redirect('/');
-  }
+  await requireAdminPlaneAccess(skossCoreRoutes.admin);
 
   return (
     <div className="page-stack">
@@ -21,11 +13,11 @@ export default async function AdminHomePage() {
         <p className="lede">Structural setup, module control, imports, and system configuration stay on the admin plane.</p>
       </section>
       <section className="grid-cards">
-        <Link href="/admin/setup" className="panel-link">
+        <Link href={skossCoreRoutes.adminSetup} className="panel-link">
           <h2>Structural setup</h2>
           <p>Users, suppliers, materials, recipes, imports, and business fine tuning.</p>
         </Link>
-        <Link href="/admin/modules" className="panel-link">
+        <Link href={skossCoreRoutes.adminModules} className="panel-link">
           <h2>Module control</h2>
           <p>Core-required and optional module defaults for this instance.</p>
         </Link>
diff --git a/app/admin/setup/page.tsx b/app/admin/setup/page.tsx
index e7d1217..eb643d1 100644
--- a/app/admin/setup/page.tsx
+++ b/app/admin/setup/page.tsx
@@ -1,5 +1,5 @@
 import Link from 'next/link';
-import { redirect } from 'next/navigation';
+import { skossBootstrapRoutes, skossCoreRoutes } from '@/lib/application-planes';
 import {
   formatCurrency,
   formatDateLabel,
@@ -19,8 +19,8 @@ import {
   updateUserAction,
   resetDemoWorkspaceAction,
 } from '@/lib/server/actions';
+import { requireAdminPlaneAccess } from '@/lib/server/application-access';
 import { getSetupWorkspace } from '@/lib/server/demo-data';
-import { getCurrentUserContext } from '@/lib/server/auth';
 import { getServerTranslator } from '@/lib/i18n/server';
 import { getVisibleWorkspacesForRole } from '@/lib/workspaces';
 import { ThemeSwitcher } from '@/components/theme-switcher';
@@ -70,7 +70,7 @@ type SetupSearchParams = {
 
 function buildSetupHref(params: Record<string, string | undefined>) {
   return {
-    pathname: '/admin/setup',
+    pathname: skossCoreRoutes.adminSetup,
     query: Object.fromEntries(
       Object.entries(params).filter(([, value]) => Boolean(value)),
     ),
@@ -168,24 +168,16 @@ export default async function SetupPage({
 }: {
   searchParams?: Promise<SetupSearchParams>;
 }) {
-  const [data, params, { t, locale, term }, userContext] = await Promise.all([
+  const userContext = await requireAdminPlaneAccess(skossCoreRoutes.adminSetup);
+  const [data, params, { t, locale, term }] = await Promise.all([
     getSetupWorkspace(),
     searchParams,
     getServerTranslator(),
-    getCurrentUserContext(),
   ]);
   const today = new Date().toISOString().slice(0, 10);
   const runtimeMode = getRuntimeMode();
   const canResetDemoWorkspace = isNonProductionMode();
 
-  if (!userContext.currentUser) {
-    redirect('/login?redirectTo=/admin/setup');
-  }
-
-  if (!userContext.canManageSettings) {
-    redirect('/');
-  }
-
   const editingSupplier = params?.supplier
     ? (data.suppliers.find((supplier) => supplier.id === params.supplier) ??
       null)
@@ -353,7 +345,7 @@ export default async function SetupPage({
     { key: 'price-history', label: t('setup.sections.priceHistory') },
   ];
   const buildSectionLink = (section: (typeof sectionNavItems)[number]['key']) => ({
-    pathname: '/admin/setup',
+    pathname: skossCoreRoutes.adminSetup,
     query: { section },
     hash: section,
   });
@@ -455,7 +447,7 @@ export default async function SetupPage({
           ))}
         </ul>
         <div className="inline-action-row">
-          <Link href="/bootstrap?step=1" className="button-secondary compact-button">
+          <Link href={skossBootstrapRoutes.bootstrapStart} className="button-secondary compact-button">
             Resume guided activation
           </Link>
           <a href="#suppliers" className="button-secondary compact-button">
diff --git a/app/customers/page.tsx b/app/customers/page.tsx
index a454ba9..b9f3aac 100644
--- a/app/customers/page.tsx
+++ b/app/customers/page.tsx
@@ -1,4 +1,5 @@
 import Link from 'next/link';
+import { skossCoreRoutes, skossinaRoutes } from '@/lib/application-planes';
 import { formatDateLabel, formatStatusLabel } from '@/lib/domain/formatters';
 import { createCustomerAction, updateCustomerAction } from '@/lib/server/actions';
 import { getCustomersWorkspace } from '@/lib/server/demo-data';
@@ -42,10 +43,10 @@ export default async function CustomersPage({
           <p>{t('customers.description')}</p>
         </div>
         <div className="inline-action-row">
-          <Link href="/admin/setup#imports" className="button-secondary">
+          <Link href={skossCoreRoutes.adminSetupImports} className="button-secondary">
             <span>{t('customers.actions.importCsv')}</span>
           </Link>
-          <Link href="/orders" className="button-secondary">
+          <Link href={skossinaRoutes.orders} className="button-secondary">
             <ArrowRightIcon className="button-icon button-icon-reverse" />
             <span>{t('common.backToOrders')}</span>
           </Link>
diff --git a/app/entry/page.tsx b/app/entry/page.tsx
index f463310..38ff781 100644
--- a/app/entry/page.tsx
+++ b/app/entry/page.tsx
@@ -1,6 +1,7 @@
 import Link from 'next/link';
 import { redirect } from 'next/navigation';
 import { LanguageSwitcher } from '@/components/language-switcher';
+import { skossBootstrapRoutes, skossinaRoutes } from '@/lib/application-planes';
 import {
   launchDemoModeAction,
   recoverLocalAdminAccessAction,
@@ -81,7 +82,7 @@ export default async function EntryGatewayPage({
   const state = await detectInstanceGatewayState(data);
 
   if (currentUser && state.hasAdminUser && state.hasInstance && !state.onboardingIncomplete) {
-    redirect('/');
+    redirect(skossinaRoutes.home);
   }
   const copy = getEntryCopy(locale);
   const runtimeMode = getRuntimeMode();
@@ -126,7 +127,7 @@ export default async function EntryGatewayPage({
           <h2>{copy.newTitle}</h2>
           <p>{copy.newBody}</p>
           {state.canRunBootstrap ? (
-            <Link className="button-primary" href="/bootstrap?step=1">
+            <Link className="button-primary" href={skossBootstrapRoutes.bootstrapStart}>
               {copy.newAction}
             </Link>
           ) : (
diff --git a/app/login/page.tsx b/app/login/page.tsx
index 1fe33db..3bfaeb9 100644
--- a/app/login/page.tsx
+++ b/app/login/page.tsx
@@ -1,8 +1,9 @@
+import Link from 'next/link';
+import { skossBootstrapRoutes } from '@/lib/application-planes';
 import { loginAction } from '@/lib/server/actions';
 import { getServerTranslator } from '@/lib/i18n/server';
 import { readAppData } from '@/lib/server/persistence';
 import { detectInstanceGatewayState } from '@/lib/server/instance-entry';
-import Link from 'next/link';
 
 export default async function LoginPage({
   searchParams,
@@ -52,11 +53,11 @@ export default async function LoginPage({
         </datalist>
         <button type="submit" className="button-primary">{t('login.submit')}</button>
         <p className="helper-text no-margin">
-          Need a different path? <Link href="/entry" className="inline-link">Back to entry gateway</Link> for new setup, restore, or demo mode.
+          Need a different path? <Link href={skossBootstrapRoutes.entry} className="inline-link">Back to entry gateway</Link> for new setup, restore, or demo mode.
         </p>
         {gatewayState.canRunBootstrap ? (
           <p className="helper-text no-margin">
-            Need to initialize this instance first? <Link href="/bootstrap?step=1" className="inline-link">Run first-use wizard</Link>
+            Need to initialize this instance first? <Link href={skossBootstrapRoutes.bootstrapStart} className="inline-link">Run first-use wizard</Link>
           </p>
         ) : null}
       </form>
diff --git a/app/page.tsx b/app/page.tsx
index 4b69c3d..11e50e0 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -3,27 +3,28 @@ import { redirect } from 'next/navigation';
 import { ActivityFeed } from '@/components/activity-feed';
 import { formatDateLabel } from '@/lib/domain/formatters';
 import { getPresetExperience, type WorkspaceLinkKey } from '@/lib/business-presets';
-import { getWorkspaceSummary } from '@/lib/server/demo-data';
+import { buildWorkspaceSummary } from '@/lib/server/demo-data';
 import { getCurrentUserContext } from '@/lib/server/auth';
 import { detectInstanceGatewayState, shouldRouteToEntryGateway } from '@/lib/server/instance-entry';
 import { getServerTranslator } from '@/lib/i18n/server';
 import { readAppData } from '@/lib/server/persistence';
+import { skossBootstrapRoutes, skossCoreRoutes, skossinaRoutes, type AppPlaneRoute } from '@/lib/application-planes';
 import { ArrowRightIcon, CustomersIcon, HandoffIcon, OrdersIcon, ProductionIcon, SetupIcon, SparklesIcon, TimelineIcon } from '@/components/ui-icons';
 
 type QuickLink = {
-  href: Parameters<typeof Link>[0]['href'];
+  href: AppPlaneRoute;
   title: string;
   description: string;
   icon: typeof OrdersIcon;
 };
 
 export default async function HomePage() {
-  const [summary, { t, locale, preset }, data, userContext] = await Promise.all([
-    getWorkspaceSummary(),
+  const [{ t, locale, preset }, data, userContext] = await Promise.all([
     getServerTranslator(),
     readAppData(),
     getCurrentUserContext(),
   ]);
+  const summary = buildWorkspaceSummary(data);
   const { currentUser, visibleWorkspaces, homeWorkspace } = userContext;
   const gatewayState = await detectInstanceGatewayState(data);
 
@@ -39,37 +40,37 @@ export default async function HomePage() {
 
   const quickLinkMap: Record<WorkspaceLinkKey, QuickLink> = {
     timeline: {
-      href: '/timeline',
+      href: skossinaRoutes.timeline,
       title: t('home.quickLinks.timeline.title'),
       description: t('home.quickLinks.timeline.description'),
       icon: TimelineIcon,
     },
     orders: {
-      href: '/orders',
+      href: skossinaRoutes.orders,
       title: t('home.quickLinks.orders.title'),
       description: t('home.quickLinks.orders.description'),
       icon: OrdersIcon,
     },
     customers: {
-      href: '/customers',
+      href: skossinaRoutes.customers,
       title: t('home.quickLinks.customers.title'),
       description: t('home.quickLinks.customers.description'),
       icon: CustomersIcon,
     },
     production: {
-      href: '/production',
+      href: skossinaRoutes.production,
       title: t('home.quickLinks.production.title'),
       description: t('home.quickLinks.production.description'),
       icon: ProductionIcon,
     },
     handoff: {
-      href: '/handoff',
+      href: skossinaRoutes.handoff,
       title: t('home.quickLinks.handoff.title'),
       description: t('home.quickLinks.handoff.description'),
       icon: HandoffIcon,
     },
     admin: {
-      href: '/admin/setup',
+      href: skossCoreRoutes.adminSetup,
       title: t('home.quickLinks.setup.title'),
       description: t('home.quickLinks.setup.description'),
       icon: SetupIcon,
@@ -84,7 +85,7 @@ export default async function HomePage() {
   const orderedQuickLinks = orderedQuickLinkKeys.map((key) => quickLinkMap[key]);
 
   if (!summary.preferences.onboardingCompleted) {
-    redirect('/bootstrap?step=1');
+    redirect(skossBootstrapRoutes.bootstrapStart);
   }
 
   return (
diff --git a/app/setup/page.tsx b/app/setup/page.tsx
index 13aaf87..6899c38 100644
--- a/app/setup/page.tsx
+++ b/app/setup/page.tsx
@@ -1,5 +1,6 @@
 import { redirect } from 'next/navigation';
+import { skossCoreRoutes } from '@/lib/application-planes';
 
 export default function LegacySetupRedirectPage() {
-  redirect('/admin/setup');
+  redirect(skossCoreRoutes.adminSetup);
 }
diff --git a/components/app-shell.tsx b/components/app-shell.tsx
index 478d1d6..3ea757c 100644
--- a/components/app-shell.tsx
+++ b/components/app-shell.tsx
@@ -3,13 +3,16 @@ import type { ReactNode } from 'react';
 import { headers } from 'next/headers';
 import { PrimaryNav } from '@/components/primary-nav';
 import { UserMenu } from '@/components/user-menu';
+import { getApplicationPlane, skossinaRoutes } from '@/lib/application-planes';
 import { getServerTranslator } from '@/lib/i18n/server';
-import { readAppData } from '@/lib/server/persistence';
+import { readPersistence } from '@/lib/server/persistence';
 import { getCurrentUserContext } from '@/lib/server/auth';
 import { getRuntimeModeLabel, isNonProductionMode } from '@/lib/server/runtime-mode';
 
 export async function AppShell({ children }: { children?: ReactNode }) {
-  const [{ t }, data] = await Promise.all([getServerTranslator(), readAppData()]);
+  const [{ t }, persistence] = await Promise.all([getServerTranslator(), readPersistence()]);
+  const data = persistence.raw;
+  const workspace = persistence.instance.getWorkspace();
   const { currentUser, visibleWorkspaces } = await getCurrentUserContext(data);
   const showNonProductionBanner = isNonProductionMode();
   const runtimeModeLabel = getRuntimeModeLabel();
@@ -19,9 +22,9 @@ export async function AppShell({ children }: { children?: ReactNode }) {
     ?? headerStore.get('x-invoke-path')
     ?? headerStore.get('x-matched-path')
     ?? '';
-  const isBootstrapRoute = requestPath.startsWith('/bootstrap');
+  const plane = getApplicationPlane(requestPath);
 
-  if (isBootstrapRoute) {
+  if (plane === 'bootstrap') {
     return (
       <div className="shell onboarding-shell">
         {showNonProductionBanner ? (
@@ -42,9 +45,9 @@ export async function AppShell({ children }: { children?: ReactNode }) {
         </div>
       ) : null}
       <header className="shell-header">
-        <Link href="/" className="brand-block" aria-label={t('shell.homeAria')}>
+        <Link href={skossinaRoutes.home} className="brand-block" aria-label={t('shell.homeAria')}>
           <span className="brand-kicker">SKOSS</span>
-          <strong>{data.workspace.name}</strong>
+          <strong>{workspace.name}</strong>
           <span className="brand-subtitle">{t('shell.brandTitle')}</span>
         </Link>
         <div className="shell-controls">
diff --git a/components/primary-nav.tsx b/components/primary-nav.tsx
index 407375f..591f8c8 100644
--- a/components/primary-nav.tsx
+++ b/components/primary-nav.tsx
@@ -4,6 +4,7 @@ import Link from 'next/link';
 import type { ReactNode } from 'react';
 import { usePathname } from 'next/navigation';
 import { useI18n } from '@/components/i18n-provider';
+import { adminPlaneNavItems, operatorWorkspaceRoutes, type AppPlaneRoute, type OperatorWorkspaceSurface } from '@/lib/application-planes';
 import {
   CustomersIcon,
   HandoffIcon,
@@ -14,28 +15,14 @@ import {
 } from '@/components/ui-icons';
 import type { WorkspaceSurface } from '@/lib/domain/types';
 
-type NavHref =
-  | '/'
-  | '/timeline'
-  | '/orders'
-  | '/customers'
-  | '/production'
-  | '/handoff';
-
 type NavItem = {
-  key: Exclude<WorkspaceSurface, 'admin' | 'preferences'>;
-  href: NavHref;
+  key: OperatorWorkspaceSurface;
+  href: AppPlaneRoute;
   labelKey: string;
   icon: typeof HomeIcon;
   active: (pathname: string) => boolean;
 };
 
-type DesktopAdminItem = {
-  href: '/admin' | '/admin/setup' | '/admin/modules';
-  labelKey: string;
-  active: (pathname: string) => boolean;
-};
-
 function NavLink({
   href,
   label,
@@ -43,7 +30,7 @@ function NavLink({
   children,
   compact = false,
 }: {
-  href: NavHref | '/admin' | '/admin/setup' | '/admin/modules';
+  href: AppPlaneRoute;
   label: string;
   active: boolean;
   children?: ReactNode;
@@ -64,54 +51,48 @@ function NavLink({
 const navItems: NavItem[] = [
   {
     key: 'home',
-    href: '/',
+    href: operatorWorkspaceRoutes.home,
     labelKey: 'nav.home',
     icon: HomeIcon,
     active: (pathname) => pathname === '/',
   },
   {
     key: 'timeline',
-    href: '/timeline',
+    href: operatorWorkspaceRoutes.timeline,
     labelKey: 'nav.timeline',
     icon: TimelineIcon,
     active: (pathname) => pathname.startsWith('/timeline'),
   },
   {
     key: 'orders',
-    href: '/orders',
+    href: operatorWorkspaceRoutes.orders,
     labelKey: 'nav.orders',
     icon: OrdersIcon,
     active: (pathname) => pathname.startsWith('/orders'),
   },
   {
     key: 'customers',
-    href: '/customers',
+    href: operatorWorkspaceRoutes.customers,
     labelKey: 'nav.customers',
     icon: CustomersIcon,
     active: (pathname) => pathname.startsWith('/customers'),
   },
   {
     key: 'production',
-    href: '/production',
+    href: operatorWorkspaceRoutes.production,
     labelKey: 'nav.production',
     icon: ProductionIcon,
     active: (pathname) => pathname.startsWith('/production'),
   },
   {
     key: 'handoff',
-    href: '/handoff',
+    href: operatorWorkspaceRoutes.handoff,
     labelKey: 'nav.handoff',
     icon: HandoffIcon,
     active: (pathname) => pathname.startsWith('/handoff'),
   },
 ];
 
-const desktopAdminItems: DesktopAdminItem[] = [
-  { href: '/admin', labelKey: 'nav.setup', active: (pathname) => pathname === '/admin' },
-  { href: '/admin/setup', labelKey: 'setup.sections.businessSetup', active: (pathname) => pathname.startsWith('/admin/setup') },
-  { href: '/admin/modules', labelKey: 'setup.sections.preferencesSystem', active: (pathname) => pathname.startsWith('/admin/modules') },
-];
-
 export function PrimaryNav({
   visibleWorkspaces,
   mode = 'mobile',
@@ -157,7 +138,7 @@ export function PrimaryNav({
       {showAdminSection ? (
         <nav className="shell-nav shell-nav-desktop shell-nav-admin" aria-label={t('shell.sections.admin')}>
           <p className="shell-nav-section-label">{t('shell.sections.admin')}</p>
-          {desktopAdminItems.map((item) => (
+          {adminPlaneNavItems.map((item) => (
             <NavLink
               key={`${item.href}-${item.labelKey}`}
               href={item.href}
diff --git a/components/setup/onboarding-quick-start.tsx b/components/setup/onboarding-quick-start.tsx
index b8987ff..87e2cbe 100644
--- a/components/setup/onboarding-quick-start.tsx
+++ b/components/setup/onboarding-quick-start.tsx
@@ -5,6 +5,7 @@ import {
   createSupplierAction,
   createUserAction,
 } from '@/lib/server/actions';
+import { skossCoreRoutes } from '@/lib/application-planes';
 import { getServerTranslator } from '@/lib/i18n/server';
 
 type OnboardingQuickStartProps = {
@@ -119,7 +120,7 @@ export async function OnboardingQuickStart({ redirectTo, compact = false }: Onbo
       </div>
 
       <p className="helper-text no-margin">
-        {t('setupAssistant.quickStart.skipHelp')} <Link href="/admin/setup" className="inline-link">{t('setup.title')}</Link>
+        {t('setupAssistant.quickStart.skipHelp')} <Link href={skossCoreRoutes.adminSetup} className="inline-link">{t('setup.title')}</Link>
       </p>
     </section>
   );
diff --git a/lib/application-planes.ts b/lib/application-planes.ts
new file mode 100644
index 0000000..75e62a3
--- /dev/null
+++ b/lib/application-planes.ts
@@ -0,0 +1,74 @@
+import type { Route } from 'next';
+import type { WorkspaceSurface } from '@/lib/domain/types';
+
+export const skossCoreRoutes = {
+  admin: '/admin',
+  adminSetup: '/admin/setup',
+  adminSetupImports: '/admin/setup#imports',
+  adminModules: '/admin/modules',
+} as const satisfies Record<string, Route>;
+
+export const skossBootstrapRoutes = {
+  entry: '/entry',
+  bootstrap: '/bootstrap',
+  bootstrapStart: '/bootstrap?step=1',
+  login: '/login',
+} as const satisfies Record<string, Route>;
+
+export const skossinaRoutes = {
+  home: '/',
+  timeline: '/timeline',
+  orders: '/orders',
+  customers: '/customers',
+  production: '/production',
+  handoff: '/handoff',
+  preferences: '/preferences',
+} as const satisfies Record<string, Route>;
+
+export type SkossCoreRoute = (typeof skossCoreRoutes)[keyof typeof skossCoreRoutes];
+export type SkossBootstrapRoute = (typeof skossBootstrapRoutes)[keyof typeof skossBootstrapRoutes];
+export type SkossinaRoute = (typeof skossinaRoutes)[keyof typeof skossinaRoutes];
+export type AppPlaneRoute = SkossCoreRoute | SkossBootstrapRoute | SkossinaRoute;
+
+export type OperatorWorkspaceSurface = Exclude<WorkspaceSurface, 'admin' | 'preferences'>;
+
+export const operatorWorkspaceRoutes = {
+  home: skossinaRoutes.home,
+  timeline: skossinaRoutes.timeline,
+  orders: skossinaRoutes.orders,
+  customers: skossinaRoutes.customers,
+  production: skossinaRoutes.production,
+  handoff: skossinaRoutes.handoff,
+} as const satisfies Record<OperatorWorkspaceSurface, SkossinaRoute>;
+
+export const adminPlaneNavItems = [
+  {
+    href: skossCoreRoutes.admin,
+    labelKey: 'nav.setup',
+    active: (pathname: string) => pathname === skossCoreRoutes.admin,
+  },
+  {
+    href: skossCoreRoutes.adminSetup,
+    labelKey: 'setup.sections.businessSetup',
+    active: (pathname: string) => pathname.startsWith(skossCoreRoutes.adminSetup),
+  },
+  {
+    href: skossCoreRoutes.adminModules,
+    labelKey: 'setup.sections.preferencesSystem',
+    active: (pathname: string) => pathname.startsWith(skossCoreRoutes.adminModules),
+  },
+] as const;
+
+export type ApplicationPlane = 'bootstrap' | 'admin' | 'operator';
+
+export function getApplicationPlane(pathname: string): ApplicationPlane {
+  if (pathname.startsWith(skossBootstrapRoutes.entry) || pathname.startsWith(skossBootstrapRoutes.bootstrap)) {
+    return 'bootstrap';
+  }
+
+  if (pathname === skossCoreRoutes.admin || pathname.startsWith(`${skossCoreRoutes.admin}/`)) {
+    return 'admin';
+  }
+
+  return 'operator';
+}
diff --git a/lib/server/actions/admin-core.ts b/lib/server/actions/admin-core.ts
index f53d192..a2d8519 100644
--- a/lib/server/actions/admin-core.ts
+++ b/lib/server/actions/admin-core.ts
@@ -20,7 +20,7 @@ import {
   validateSupplierPriceEntryForm,
   validateUserForm,
 } from '@/lib/server/demo-data';
-import { getPersistenceGateway, readAppData, mutateAppData, reseedRuntimeAppData } from '@/lib/server/persistence';
+import { getPersistenceGateway, readAppData, readPersistence, mutateAppData, reseedRuntimeAppData } from '@/lib/server/persistence';
 import { appendActivity } from '@/lib/server/activity';
 import { hashPassword } from '@/lib/server/passwords';
 import {
@@ -36,10 +36,6 @@ import { getCurrentUserContext } from '@/lib/server/auth';
 import { isNonProductionMode } from '@/lib/server/runtime-mode';
 import type { AppData } from '@/lib/domain/types';
 
-function sortUsers(left: { displayName: string }, right: { displayName: string }) {
-  return left.displayName.localeCompare(right.displayName);
-}
-
 function quoteLabel(label: string) {
   return `"${label}"`;
 }
@@ -83,7 +79,6 @@ export async function resetDemoWorkspaceAction() {
 }
 
 export async function updateModuleRegistryAction(formData: FormData) {
-  const data = await readAppData();
   const nextStates: Record<string, boolean> = {};
 
   for (const manifest of moduleRegistry) {
@@ -96,20 +91,15 @@ export async function updateModuleRegistryAction(formData: FormData) {
   }
 
   await persistence.write(({ instance }) => {
-    instance.updateInstanceState({
-      ...data.instance,
-      moduleStates: {
-        ...(data.instance.moduleStates ?? {}),
-        ...nextStates,
-      },
-    });
+    instance.updateModuleStates(nextStates);
   });
   revalidatePath('/admin/modules');
   redirect('/admin/modules?saved=modules');
 }
 
 export async function createUserAction(formData: FormData) {
-  const data = await readAppData();
+  const context = await readPersistence();
+  const data = context.raw;
   const actorUserId = await getActorUserId(data);
   const redirectTo = resolveRedirectTo(formData, '/admin/setup');
   const allowEmpty = shouldAllowEmpty(formData);
@@ -127,19 +117,7 @@ export async function createUserAction(formData: FormData) {
   user.passwordHash = hashPassword(values.password?.trim() || 'skoss-demo');
   user.passwordUpdatedAt = new Date().toISOString();
   user.mustChangePassword = !values.password?.trim();
-  const nextUsers = [...data.users, user].sort(sortUsers);
-  if (user.roles.includes('owner_admin') || user.role === 'owner_admin') {
-    data.instance = {
-      ...data.instance,
-      initialized: true,
-      onboardingProgress: {
-        ...data.instance.onboardingProgress,
-        adminAccount: true,
-        roles: true,
-        users: true,
-      },
-    };
-  }
+  const createdOwnerAdmin = user.roles.includes('owner_admin') || user.role === 'owner_admin';
   appendActivity(data, {
     entityType: 'user',
     entityId: user.id,
@@ -148,8 +126,15 @@ export async function createUserAction(formData: FormData) {
     summary: `User ${quoteLabel(user.displayName)} created.`,
   });
   await persistence.write(({ raw, instance, users }) => {
-    users.replaceAll(nextUsers);
-    instance.updateInstanceState(data.instance);
+    users.upsert(user);
+    if (createdOwnerAdmin) {
+      instance.setInitialized(true);
+      instance.updateOnboardingProgress({
+        adminAccount: true,
+        roles: true,
+        users: true,
+      });
+    }
     raw.activities = data.activities;
   });
   revalidateAllWorkspaces();
@@ -157,8 +142,9 @@ export async function createUserAction(formData: FormData) {
 }
 
 export async function updateUserAction(userId: string, formData: FormData) {
-  const data = await readAppData();
-  const existing = data.users.find((entry) => entry.id === userId);
+  const context = await readPersistence();
+  const data = context.raw;
+  const existing = context.users.getById(userId);
 
   if (!existing) {
     redirect('/admin/setup?error=missing-user');
@@ -177,7 +163,6 @@ export async function updateUserAction(userId: string, formData: FormData) {
     user.passwordUpdatedAt = new Date().toISOString();
     user.mustChangePassword = !values.password?.trim();
   }
-  const nextUsers = data.users.map((entry) => (entry.id === userId ? user : entry)).sort(sortUsers);
   appendActivity(data, {
     entityType: 'user',
     entityId: user.id,
@@ -188,13 +173,18 @@ export async function updateUserAction(userId: string, formData: FormData) {
       : `User ${quoteLabel(user.displayName)} updated.`,
   });
 
-  if (!user.active && data.session.currentUserId === userId) {
-    data.session.currentUserId = nextUsers.find((entry) => entry.active && entry.id !== userId)?.id;
+  const wasSessionUser = data.session.currentUserId === userId;
+  const nextSessionUserId = data.users.find((entry) => entry.active && entry.id !== userId)?.id;
+
+  if (!user.active && wasSessionUser) {
+    data.session.currentUserId = nextSessionUserId;
   }
 
   await persistence.write(({ raw, instance, users }) => {
-    users.replaceAll(nextUsers);
-    instance.updateSessionState(data.session);
+    users.upsert(user);
+    if (!user.active && wasSessionUser) {
+      instance.setSessionUser(nextSessionUserId, data.session.lastLoginAt);
+    }
     raw.activities = data.activities;
   });
   revalidateAllWorkspaces();
@@ -297,7 +287,8 @@ export async function createRawMaterialAction(formData: FormData) {
 }
 
 export async function importCsvEntitiesAction(formData: FormData) {
-  const data = await readAppData();
+  const context = await readPersistence();
+  const data = context.raw;
   const redirectTo = resolveRedirectTo(formData, '/admin/setup');
   const entity = String(formData.get('entity') ?? '') as CsvEntity;
   const csvContent = String(formData.get('csvContent') ?? '');
@@ -316,6 +307,7 @@ export async function importCsvEntitiesAction(formData: FormData) {
   const actorUserId = await getActorUserId(data);
   let imported = 0;
   let skipped = 0;
+  let importedCustomers: AppData['customers'] = [];
 
   if (entity === 'customers') {
     const payload = buildCustomerImportPayload(parsed.headers, parsed.rows, mapping);
@@ -329,7 +321,7 @@ export async function importCsvEntitiesAction(formData: FormData) {
       return [buildCustomerRecord(entry, actorUserId)];
     });
 
-    data.customers = [...data.customers, ...importedRecords].sort((left, right) => left.displayName.localeCompare(right.displayName));
+    importedCustomers = importedRecords;
   }
 
   if (entity === 'suppliers') {
@@ -363,7 +355,7 @@ export async function importCsvEntitiesAction(formData: FormData) {
   }
 
   await persistence.write(({ raw, customers }) => {
-    customers.replaceAll(data.customers);
+    customers.upsertMany(importedCustomers);
     raw.suppliers = data.suppliers;
     raw.rawMaterials = data.rawMaterials;
   });
diff --git a/lib/server/actions/entry-bootstrap.ts b/lib/server/actions/entry-bootstrap.ts
index 229acfc..1ab54f8 100644
--- a/lib/server/actions/entry-bootstrap.ts
+++ b/lib/server/actions/entry-bootstrap.ts
@@ -4,7 +4,7 @@ import { revalidatePath } from 'next/cache';
 import { cookies } from 'next/headers';
 import { redirect } from 'next/navigation';
 import { getCurrentUserContext, loggedOutSessionValue, sessionUserCookieName } from '@/lib/server/auth';
-import { getPersistenceGateway, readSeedAppData, readAppData, reseedRuntimeAppData, mutateAppData } from '@/lib/server/persistence';
+import { getPersistenceGateway, readSeedAppData, readAppData, readPersistence, reseedRuntimeAppData, mutateAppData } from '@/lib/server/persistence';
 import { hashPassword, verifyPassword } from '@/lib/server/passwords';
 import { isSupportedLocale, isSupportedPreset, localeCookieName, supportedLocales, presetCookieName, supportedPresets } from '@/lib/i18n/config';
 import { themeCookieName } from '@/lib/theme';
@@ -103,41 +103,29 @@ export async function recoverLocalAdminAccessAction() {
     redirect('/entry?error=' + encodeURIComponent('Local recovery is disabled in production mode.'));
   }
 
-  const data = await readAppData();
+  const context = await readPersistence();
+  const data = context.raw;
   const now = new Date().toISOString();
-  const adminUser = data.users.find((user) => user.role === 'owner_admin' || user.roles?.includes('owner_admin'));
+  const adminUser = context.users.list().find((user) => user.role === 'owner_admin' || user.roles?.includes('owner_admin'));
 
   if (!adminUser) {
     redirect('/entry?error=' + encodeURIComponent('No admin account found. Use restore or guided activation.'));
   }
 
   const temporaryPassword = 'skoss-local-admin';
-  const nextUsers = data.users.map((user) => user.id === adminUser.id
-    ? {
-        ...user,
-        passwordHash: hashPassword(temporaryPassword),
-        passwordUpdatedAt: now,
-        mustChangePassword: true,
-        active: true,
-        updatedAt: now,
-      }
-    : user);
+  const recoveredAdmin = {
+    ...adminUser,
+    passwordHash: hashPassword(temporaryPassword),
+    passwordUpdatedAt: now,
+    mustChangePassword: true,
+    active: true,
+    updatedAt: now,
+  };
   await persistence.write(({ users, instance }) => {
-    users.replaceAll(nextUsers);
-    instance.updateInstanceState({
-      ...data.instance,
-      initialized: true,
-      onboardingProgress: {
-        ...data.instance.onboardingProgress,
-        adminAccount: true,
-      },
-      onboardingStatus: data.preferences.onboardingCompleted ? 'completed' : 'in_progress',
-    });
-    instance.updateSessionState({
-      ...data.session,
-      currentUserId: undefined,
-      lastLoginAt: undefined,
-    });
+    users.upsert(recoveredAdmin);
+    instance.setInitialized(true, data.preferences.onboardingCompleted ? 'completed' : 'in_progress');
+    instance.updateOnboardingProgress({ adminAccount: true });
+    instance.setSessionUser(undefined);
   });
 
   const cookieStore = await cookies();
@@ -264,7 +252,8 @@ export async function saveOnboardingPreferencesAction(formData: FormData) {
   await persistence.write(({ instance }) => {
     instance.updateWorkspace(nextWorkspace);
     instance.updatePreferences(nextPreferences);
-    instance.updateInstanceState(nextInstance);
+    instance.setInitialized(nextInstance.initialized, nextInstance.onboardingStatus);
+    instance.updateOnboardingProgress(nextInstance.onboardingProgress);
   });
 
   const cookieStore = await cookies();
@@ -529,7 +518,8 @@ export async function saveBootstrapStepAction(formData: FormData) {
 }
 
 export async function saveUserPreferencesAction(formData: FormData) {
-  const data = await readAppData();
+  const context = await readPersistence();
+  const data = context.raw;
   const { currentUser } = await getCurrentUserContext(data);
 
   if (!currentUser) {
@@ -561,22 +551,20 @@ export async function saveUserPreferencesAction(formData: FormData) {
   const defaultWorkspace = defaultWorkspaceValue ? requestedWorkspace : fallbackWorkspace;
   const nextUpdatedAt = new Date().toISOString();
 
-  const nextUsers = data.users.map((user) => user.id === currentUser.id
-    ? {
-        ...user,
-        defaultWorkspace,
-        preferences: {
-          ...user.preferences,
-          locale,
-          theme: theme as (typeof supportedThemes)[number],
-          defaultWorkspace,
-        },
-        updatedAt: nextUpdatedAt,
-      }
-    : user);
+  const nextUser = {
+    ...currentUser,
+    defaultWorkspace,
+    preferences: {
+      ...currentUser.preferences,
+      locale,
+      theme: theme as (typeof supportedThemes)[number],
+      defaultWorkspace,
+    },
+    updatedAt: nextUpdatedAt,
+  };
 
   await persistence.write(({ users }) => {
-    users.replaceAll(nextUsers);
+    users.upsert(nextUser);
   });
 
   const cookieStore = await cookies();
@@ -604,11 +592,7 @@ export async function loginAction(formData: FormData) {
 
   const now = new Date().toISOString();
   await persistence.write(({ instance }) => {
-    instance.updateSessionState({
-      ...data.session,
-      currentUserId: user.id,
-      lastLoginAt: now,
-    });
+    instance.setSessionUser(user.id, now);
   });
 
   const cookieStore = await cookies();
@@ -636,12 +620,8 @@ export async function loginAction(formData: FormData) {
 }
 
 export async function logoutAction() {
-  const data = await readAppData();
   await persistence.write(({ instance }) => {
-    instance.updateSessionState({
-      ...data.session,
-      currentUserId: undefined,
-    });
+    instance.setSessionUser(undefined);
   });
 
   const cookieStore = await cookies();
diff --git a/lib/server/application-access.ts b/lib/server/application-access.ts
new file mode 100644
index 0000000..4725e9d
--- /dev/null
+++ b/lib/server/application-access.ts
@@ -0,0 +1,17 @@
+import { redirect } from 'next/navigation';
+import { skossinaRoutes, type SkossCoreRoute } from '@/lib/application-planes';
+import { getCurrentUserContext } from '@/lib/server/auth';
+
+export async function requireAdminPlaneAccess(redirectTo: SkossCoreRoute) {
+  const userContext = await getCurrentUserContext();
+
+  if (!userContext.currentUser) {
+    redirect(`/login?redirectTo=${redirectTo}`);
+  }
+
+  if (!userContext.canManageSettings) {
+    redirect(skossinaRoutes.home);
+  }
+
+  return userContext;
+}
diff --git a/lib/server/demo-data.ts b/lib/server/demo-data.ts
index 0d1d6be..968d36d 100644
--- a/lib/server/demo-data.ts
+++ b/lib/server/demo-data.ts
@@ -407,8 +407,7 @@ export function buildUserRecord(
   };
 }
 
-export async function getWorkspaceSummary() {
-  const data = await readAppData();
+export function buildWorkspaceSummary(data: AppData) {
   const focusDate = getFocusDate(data);
   const ordersToday = data.orders.filter((order) => order.productionDate === focusDate);
   const activePriceEntries = data.supplierPriceEntries.filter((entry) => entry.priceDate <= focusDate);
@@ -439,6 +438,10 @@ export async function getWorkspaceSummary() {
   };
 }
 
+export async function getWorkspaceSummary() {
+  return buildWorkspaceSummary(await readAppData());
+}
+
 export async function getOrdersWorkspace() {
   const data = await readAppData();
   const dates = getAllProductionDates(data);
diff --git a/lib/server/persistence/context.ts b/lib/server/persistence/context.ts
index 7468e6f..5b8598e 100644
--- a/lib/server/persistence/context.ts
+++ b/lib/server/persistence/context.ts
@@ -1,4 +1,4 @@
-import type { AppData, Destination, Product } from '@/lib/domain/types';
+import type { AppData, Customer, Destination, Product, User } from '@/lib/domain/types';
 import type {
   ActivityRepository,
   CatalogRepository,
@@ -21,19 +21,65 @@ class InMemoryInstanceRepository implements InstanceRepository {
   updatePreferences(next: AppData['preferences']) { this.data.preferences = next; }
   getInstanceState() { return this.data.instance; }
   updateInstanceState(next: AppData['instance']) { this.data.instance = next; }
+  updateOnboardingProgress(next: Partial<AppData['instance']['onboardingProgress']>) {
+    this.data.instance.onboardingProgress = {
+      ...this.data.instance.onboardingProgress,
+      ...next,
+    };
+  }
+  updateModuleStates(next: Record<string, boolean>) {
+    this.data.instance.moduleStates = {
+      ...(this.data.instance.moduleStates ?? {}),
+      ...next,
+    };
+  }
+  setInitialized(initialized: boolean, onboardingStatus?: AppData['instance']['onboardingStatus']) {
+    this.data.instance.initialized = initialized;
+    if (onboardingStatus) {
+      this.data.instance.onboardingStatus = onboardingStatus;
+    }
+  }
   getSessionState() { return this.data.session; }
   updateSessionState(next: AppData['session']) { this.data.session = next; }
+  setSessionUser(userId: string | undefined, lastLoginAt?: string) {
+    this.data.session.currentUserId = userId;
+    this.data.session.lastLoginAt = lastLoginAt;
+  }
 }
 
 class InMemoryUsersRepository implements UsersRepository {
   constructor(private readonly data: AppData) {}
   list() { return this.data.users; }
+  getById(userId: string) { return this.data.users.find((user) => user.id === userId); }
+  upsert(user: User) {
+    const existingIndex = this.data.users.findIndex((entry) => entry.id === user.id);
+    if (existingIndex >= 0) {
+      this.data.users[existingIndex] = user;
+    } else {
+      this.data.users.push(user);
+    }
+    this.data.users.sort((left, right) => left.displayName.localeCompare(right.displayName));
+  }
   replaceAll(next: AppData['users']) { this.data.users = next; }
 }
 
 class InMemoryCustomersRepository implements CustomersRepository {
   constructor(private readonly data: AppData) {}
   list() { return this.data.customers; }
+  private upsert(customer: Customer) {
+    const existingIndex = this.data.customers.findIndex((entry) => entry.id === customer.id);
+    if (existingIndex >= 0) {
+      this.data.customers[existingIndex] = customer;
+    } else {
+      this.data.customers.push(customer);
+    }
+    this.data.customers.sort((left, right) => left.displayName.localeCompare(right.displayName));
+  }
+  upsertMany(customers: Customer[]) {
+    for (const customer of customers) {
+      this.upsert(customer);
+    }
+  }
   replaceAll(next: AppData['customers']) { this.data.customers = next; }
 }
 
diff --git a/lib/server/persistence/contracts.ts b/lib/server/persistence/contracts.ts
index e2a18a5..bd03d80 100644
--- a/lib/server/persistence/contracts.ts
+++ b/lib/server/persistence/contracts.ts
@@ -26,17 +26,24 @@ export interface InstanceRepository {
   updatePreferences(next: WorkspacePreferences): void;
   getInstanceState(): InstanceState;
   updateInstanceState(next: InstanceState): void;
+  updateOnboardingProgress(next: Partial<InstanceState['onboardingProgress']>): void;
+  updateModuleStates(next: Record<string, boolean>): void;
+  setInitialized(initialized: boolean, onboardingStatus?: InstanceState['onboardingStatus']): void;
   getSessionState(): SessionState;
   updateSessionState(next: SessionState): void;
+  setSessionUser(userId: string | undefined, lastLoginAt?: string): void;
 }
 
 export interface UsersRepository {
   list(): User[];
+  getById(userId: string): User | undefined;
+  upsert(user: User): void;
   replaceAll(next: User[]): void;
 }
 
 export interface CustomersRepository {
   list(): Customer[];
+  upsertMany(customers: Customer[]): void;
   replaceAll(next: Customer[]): void;
 }