From a67fcfb45833a70728795cf5eb4f299d7e41e65b Mon Sep 17 00:00:00 2001
From: Emran025 <1.48263577e+08+Emran025@users.noreply.github.com>
Date: Fri, 21 Aug 2026 23:14:52 +0000
Subject: [PATCH 1/9] feat(server-desktop): integrate operations into bottom
 bar

---
 frontend/app/globals.css                      | 121 ++++++-
 frontend/app/layout.tsx                       |  13 +-
 frontend/components/layout/MainLayout.tsx     |   5 -
 .../StatusNotificationBar.tsx                 |   3 +
 .../ServerOperationsNotificationCenter.tsx    | 305 ++++++++++++++++++
 .../components/platform/ServerRuntimeGate.tsx | 233 ++++---------
 frontend/package.json                         |   2 +-
 frontend/scripts/create-release-manifests.mjs |  30 +-
 .../scripts/create-release-manifests.test.mjs |  15 +-
 frontend/scripts/i18n-inventory.ts            |   2 +-
 frontend/src-tauri/Cargo.toml                 |   2 +-
 frontend/src-tauri/tauri.conf.json            |   2 +-
 .../components/server-runtime-gate.test.ts    |  32 ++
 13 files changed, 561 insertions(+), 204 deletions(-)
 create mode 100644 frontend/components/platform/ServerOperationsNotificationCenter.tsx
 create mode 100644 frontend/tests/components/server-runtime-gate.test.ts

diff --git a/frontend/app/globals.css b/frontend/app/globals.css
index a93f05da..39038d42 100644
--- a/frontend/app/globals.css
+++ b/frontend/app/globals.css
@@ -5568,7 +5568,10 @@ body.nav-sidebar-is-collapsed .sidebar-toggle-btn {
    navigation shell so it remains usable while the side navigation is visible.
    ─────────────────────────────────────────────────────────────────────── */
 .status-notification-root {
-  position: relative;
+  position: fixed;
+  right: 0;
+  bottom: 0;
+  left: 0;
   z-index: 1200;
   flex-shrink: 0;
   isolation: isolate;
@@ -5675,7 +5678,7 @@ body.nav-sidebar-is-collapsed .sidebar-toggle-btn {
   display: grid;
   width: min(58rem, calc(100vw - 1.5rem));
   max-height: min(38rem, calc(100vh - 4rem));
-  grid-template-rows: auto auto minmax(0, 1fr);
+  grid-template-rows: auto auto auto minmax(0, 1fr);
   overflow: hidden;
   color: var(--text-primary);
   background: var(--surface-white);
@@ -5702,6 +5705,118 @@ body.nav-sidebar-is-collapsed .sidebar-toggle-btn {
   border-bottom: 1px solid var(--border-color);
 }
 
+.status-notification-server-operations {
+  background: color-mix(in srgb, var(--primary-subtle) 42%, var(--surface-white));
+  border-bottom: 1px solid var(--border-color);
+}
+
+.status-notification-server-operations-summary {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+  padding: 0.65rem 1rem;
+  color: var(--text-primary);
+  cursor: pointer;
+  list-style: none;
+}
+
+.status-notification-server-operations-summary::-webkit-details-marker { display: none; }
+
+.status-notification-server-operations-summary-title,
+.status-notification-server-operation-heading {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.45rem;
+  font-size: 0.76rem;
+  font-weight: 750;
+}
+
+.status-notification-server-operations-summary-state {
+  color: var(--text-secondary);
+  font-size: 0.68rem;
+  font-weight: 650;
+  text-align: end;
+}
+
+.status-notification-server-operations-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 0.6rem;
+  padding: 0 1rem 0.85rem;
+}
+
+.status-notification-server-operation-card {
+  min-width: 0;
+  padding: 0.7rem;
+  background: var(--surface-white);
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-sm);
+}
+
+.status-notification-server-operation-heading { color: var(--text-primary); }
+
+.status-notification-server-operation-detail {
+  min-height: 2.5rem;
+  margin: 0.45rem 0 0;
+  color: var(--text-secondary);
+  font-size: 0.72rem;
+  line-height: 1.45;
+}
+
+.status-notification-server-operation-button {
+  display: inline-flex;
+  width: 100%;
+  min-height: 2rem;
+  align-items: center;
+  justify-content: center;
+  margin-top: 0.65rem;
+  padding: 0.35rem 0.55rem;
+  color: var(--text-primary);
+  font: inherit;
+  font-size: 0.72rem;
+  font-weight: 750;
+  background: var(--bg-color);
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-sm);
+  cursor: pointer;
+}
+
+.status-notification-server-operation-button:hover,
+.status-notification-server-operation-button:focus-visible {
+  border-color: var(--text-light);
+  outline: none;
+}
+
+.status-notification-server-operation-button:disabled {
+  color: var(--text-light);
+  cursor: not-allowed;
+  opacity: 0.72;
+}
+
+.status-notification-server-update-progress {
+  height: 0.35rem;
+  margin-top: 0.55rem;
+  overflow: hidden;
+  background: var(--border-color);
+  border-radius: 999px;
+}
+
+.status-notification-server-update-progress > span {
+  display: block;
+  height: 100%;
+  background: var(--primary-color);
+  border-radius: inherit;
+  transition: width 180ms ease-out;
+}
+
+.status-notification-server-operation-error {
+  margin: 0 1rem 0.85rem;
+  color: #b42318;
+  font-size: 0.72rem;
+  line-height: 1.45;
+}
+
 .status-notification-center-title {
   margin: 0;
   font-size: 0.9rem;
@@ -7257,7 +7372,7 @@ body.nav-sidebar-is-collapsed .sidebar-toggle-btn {
 
 /* Standalone pre-operational onboarding shell */
 .setup-shell, .setup-access-gate { min-height: 100vh; background: linear-gradient(145deg, var(--bg-color) 0%, var(--primary-subtle) 100%); }
-.setup-shell { padding: clamp(1rem, 3vw, 2.5rem); }
+.setup-shell { padding: clamp(1rem, 3vw, 2.5rem); padding-block-end: 3.5rem; }
 .setup-shell .settings-wrapper.setup-workflow { padding-top: 0; }
 .setup-access-gate { display: grid; place-items: center; padding: 1.5rem; }
 .setup-access-gate-panel { display: grid; justify-items: center; gap: 0.9rem; min-width: min(100%, 20rem); padding: 2rem; border: 1px solid var(--border-color); border-radius: var(--radius-lg); background: var(--surface-white); box-shadow: var(--shadow-md); color: var(--text-secondary); }
diff --git a/frontend/app/layout.tsx b/frontend/app/layout.tsx
index 8e8af7c5..07f6d494 100644
--- a/frontend/app/layout.tsx
+++ b/frontend/app/layout.tsx
@@ -7,7 +7,9 @@ import { LocaleProvider } from '@/lib/i18n/LocaleProvider';
 import { ClientConnectionGate } from '@/components/platform/ClientConnectionGate';
 import { ClientDesktopAutoUpdater } from '@/components/platform/ClientDesktopAutoUpdater';
 import { DesktopInteractionPolicy } from '@/components/platform/DesktopInteractionPolicy';
+import { ServerOperationsProvider } from '@/components/platform/ServerOperationsNotificationCenter';
 import { ServerRuntimeGate } from '@/components/platform/ServerRuntimeGate';
+import { StatusNotificationBar } from '@/components/navigation';
 
 export const metadata: Metadata = {
   title: catalogMessage('shared.layout.acorSystem'),
@@ -30,10 +32,13 @@ export default function RootLayout({
         <LocaleProvider>
           <DesktopInteractionPolicy />
           <ClientDesktopAutoUpdater />
-          <ClientConnectionGate>
-            <ServerRuntimeGate>{children}</ServerRuntimeGate>
-          </ClientConnectionGate>
-          <SessionExpiredModal />
+          <ServerOperationsProvider>
+            <ClientConnectionGate>
+              <ServerRuntimeGate>{children}</ServerRuntimeGate>
+            </ClientConnectionGate>
+            <SessionExpiredModal />
+            <StatusNotificationBar />
+          </ServerOperationsProvider>
         </LocaleProvider>
       </body>
     </html>
diff --git a/frontend/components/layout/MainLayout.tsx b/frontend/components/layout/MainLayout.tsx
index 42a2d423..068c16df 100644
--- a/frontend/components/layout/MainLayout.tsx
+++ b/frontend/components/layout/MainLayout.tsx
@@ -8,7 +8,6 @@ import {
   SideNavigationBar,
   TopGlobalBar,
   SearchNavigationBar,
-  StatusNotificationBar,
 } from "@/components/navigation";
 import { FullLogo } from "@/components/ui";
 import { initSystemSettings } from "@/lib/settings";
@@ -168,9 +167,6 @@ export function MainLayout({
           </FullLogo>
         </main>
       </div>
-      <div style={{ alignItems: "stretch" }}>
-        <StatusNotificationBar />
-      </div>
     </div>
   );
 }
@@ -184,4 +180,3 @@ export function useAuth() {
     permissions: store.permissions
   };
 }
-
diff --git a/frontend/components/navigation/StatusNotificationBar/StatusNotificationBar.tsx b/frontend/components/navigation/StatusNotificationBar/StatusNotificationBar.tsx
index b53ab28f..67da271b 100644
--- a/frontend/components/navigation/StatusNotificationBar/StatusNotificationBar.tsx
+++ b/frontend/components/navigation/StatusNotificationBar/StatusNotificationBar.tsx
@@ -9,6 +9,7 @@ import {
     type NotificationCategory,
     useNotificationStore,
 } from "@/stores/useNotificationStore";
+import { ServerOperationsCenterPanel } from "@/components/platform/ServerOperationsNotificationCenter";
 import { getStatusNotificationCopy } from "./content";
 
 interface StatusNotificationBarProps {
@@ -167,6 +168,8 @@ export function StatusNotificationBar({ text }: StatusNotificationBarProps) {
                         </div>
                     </header>
 
+                    <ServerOperationsCenterPanel />
+
                     <nav className="status-notification-category-tabs" aria-label={copy.centerTitle}>
                         {(["all", ...NOTIFICATION_CATEGORIES] as const).map((category) => {
                             const unreadCount = countUnread(activeNotifications, category);
diff --git a/frontend/components/platform/ServerOperationsNotificationCenter.tsx b/frontend/components/platform/ServerOperationsNotificationCenter.tsx
new file mode 100644
index 00000000..168ba2d8
--- /dev/null
+++ b/frontend/components/platform/ServerOperationsNotificationCenter.tsx
@@ -0,0 +1,305 @@
+'use client';
+
+import {
+  type ReactNode,
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { ArchiveRestore, Download, LoaderCircle, ShieldCheck } from 'lucide-react';
+import { catalogMessage } from '@/lib/i18n';
+import {
+  isServerDesktopRuntime,
+  readServerBackupStatus,
+  requestServerBackup,
+  type ServerBackupStatus,
+} from '@/lib/server-runtime';
+import { installSignedServerDesktopUpdate } from '@/lib/server-desktop-updater';
+import { type DesktopUpdateProgress } from '@/lib/desktop-auto-updater';
+import { publishOperationalNotification } from '@/stores/useNotificationStore';
+
+interface ServerOperationsContextValue {
+  supported: boolean;
+  backupStatus: ServerBackupStatus | null;
+  updateProgress: DesktopUpdateProgress | null;
+  isBackingUp: boolean;
+  isInstallingUpdate: boolean;
+  backupFailed: boolean;
+  updateFailed: boolean;
+  requestBackup: () => Promise<void>;
+  checkForUpdate: () => Promise<void>;
+}
+
+const ServerOperationsContext = createContext<ServerOperationsContextValue | null>(null);
+
+const BACKUP_NOTIFICATION_KEY = 'server-operations:backup';
+const UPDATE_NOTIFICATION_KEY = 'server-operations:update';
+
+function updateDownloadPercentage(progress: DesktopUpdateProgress | null): number | null {
+  if (
+    progress?.phase !== 'downloading' ||
+    progress.totalBytes === undefined ||
+    progress.totalBytes <= 0 ||
+    progress.downloadedBytes === undefined
+  ) {
+    return null;
+  }
+
+  return Math.min(100, Math.round((progress.downloadedBytes / progress.totalBytes) * 100));
+}
+
+export function getServerUpdateProgressDetail(progress: DesktopUpdateProgress | null): string {
+  switch (progress?.phase) {
+    case 'checking':
+      return catalogMessage('platform.product.serverUpdateChecking');
+    case 'available':
+      return catalogMessage('platform.product.serverUpdateAvailableVersion', {
+        version: progress.version,
+      });
+    case 'downloading': {
+      const percentage = updateDownloadPercentage(progress);
+      return percentage === null
+        ? catalogMessage('platform.product.serverUpdateDownloading')
+        : catalogMessage('platform.product.serverUpdateDownloadingProgress', { percentage });
+    }
+    case 'preparing':
+      return catalogMessage('platform.product.serverUpdatePreparing');
+    case 'installing':
+    case 'relaunching':
+      return catalogMessage('platform.product.serverUpdateInstalling');
+    case 'recovering':
+      return catalogMessage('platform.product.serverUpdateRecovering');
+    case 'up-to-date':
+    default:
+      return catalogMessage('platform.product.serverUpdateNone');
+  }
+}
+
+function shouldPublishUpdateProgress(progress: DesktopUpdateProgress): boolean {
+  return ['downloading', 'preparing', 'installing', 'relaunching', 'recovering'].includes(
+    progress.phase
+  );
+}
+
+export function ServerOperationsProvider({ children }: { children: ReactNode }) {
+  const supported = isServerDesktopRuntime();
+  const [backupStatus, setBackupStatus] = useState<ServerBackupStatus | null>(null);
+  const [updateProgress, setUpdateProgress] = useState<DesktopUpdateProgress | null>(null);
+  const [isBackingUp, setIsBackingUp] = useState(false);
+  const [isInstallingUpdate, setIsInstallingUpdate] = useState(false);
+  const [backupFailed, setBackupFailed] = useState(false);
+  const [updateFailed, setUpdateFailed] = useState(false);
+  const hasCheckedForUpdate = useRef(false);
+  const updateInFlight = useRef(false);
+
+  const refreshBackupStatus = useCallback(async () => {
+    if (!supported) return;
+
+    const status = await readServerBackupStatus();
+    if (status) setBackupStatus(status);
+  }, [supported]);
+
+  useEffect(() => {
+    if (!supported) return;
+
+    void refreshBackupStatus();
+    const interval = window.setInterval(() => void refreshBackupStatus(), 5_000);
+    return () => window.clearInterval(interval);
+  }, [refreshBackupStatus, supported]);
+
+  const reportUpdateProgress = useCallback((progress: DesktopUpdateProgress) => {
+    setUpdateProgress(progress);
+    if (!shouldPublishUpdateProgress(progress)) return;
+
+    publishOperationalNotification({
+      message: getServerUpdateProgressDetail(progress),
+      source: catalogMessage('platform.product.serverOperationsTitle'),
+      severity: progress.phase === 'recovering' ? 'warning' : 'info',
+      dedupeKey: UPDATE_NOTIFICATION_KEY,
+    });
+  }, []);
+
+  const checkForUpdate = useCallback(async () => {
+    if (!supported || updateInFlight.current) return;
+
+    updateInFlight.current = true;
+    setIsInstallingUpdate(true);
+    setUpdateFailed(false);
+    try {
+      await installSignedServerDesktopUpdate({ onProgress: reportUpdateProgress });
+    } catch {
+      setUpdateFailed(true);
+      publishOperationalNotification({
+        message: catalogMessage('platform.product.serverOperationRetry'),
+        source: catalogMessage('platform.product.serverUpdateTitle'),
+        severity: 'error',
+        dedupeKey: UPDATE_NOTIFICATION_KEY,
+      });
+    } finally {
+      updateInFlight.current = false;
+      setIsInstallingUpdate(false);
+    }
+  }, [reportUpdateProgress, supported]);
+
+  useEffect(() => {
+    if (!supported || hasCheckedForUpdate.current) return;
+
+    hasCheckedForUpdate.current = true;
+    void checkForUpdate();
+  }, [checkForUpdate, supported]);
+
+  const requestBackup = useCallback(async () => {
+    if (!supported || isBackingUp || isInstallingUpdate) return;
+
+    setIsBackingUp(true);
+    setBackupFailed(false);
+    try {
+      const status = await requestServerBackup();
+      if (!status) throw new Error('backup-operation-unavailable');
+
+      const requestedStatus: ServerBackupStatus = {
+        ...status,
+        state: 'pending',
+        detail: catalogMessage('platform.product.serverBackupRequested'),
+      };
+      setBackupStatus(requestedStatus);
+      publishOperationalNotification({
+        message: requestedStatus.detail,
+        source: catalogMessage('platform.product.serverBackupTitle'),
+        severity: 'info',
+        dedupeKey: BACKUP_NOTIFICATION_KEY,
+      });
+    } catch {
+      setBackupFailed(true);
+      publishOperationalNotification({
+        message: catalogMessage('platform.product.serverOperationRetry'),
+        source: catalogMessage('platform.product.serverBackupTitle'),
+        severity: 'error',
+        dedupeKey: BACKUP_NOTIFICATION_KEY,
+      });
+    } finally {
+      setIsBackingUp(false);
+    }
+  }, [isBackingUp, isInstallingUpdate, supported]);
+
+  const value = useMemo<ServerOperationsContextValue>(
+    () => ({
+      supported,
+      backupStatus,
+      updateProgress,
+      isBackingUp,
+      isInstallingUpdate,
+      backupFailed,
+      updateFailed,
+      requestBackup,
+      checkForUpdate,
+    }),
+    [
+      backupFailed,
+      backupStatus,
+      checkForUpdate,
+      isBackingUp,
+      isInstallingUpdate,
+      requestBackup,
+      supported,
+      updateFailed,
+      updateProgress,
+    ]
+  );
+
+  return (
+    <ServerOperationsContext.Provider value={value}>{children}</ServerOperationsContext.Provider>
+  );
+}
+
+export function ServerOperationsCenterPanel() {
+  const operations = useContext(ServerOperationsContext);
+  if (!operations?.supported) return null;
+
+  const updateDetail = getServerUpdateProgressDetail(operations.updateProgress);
+  const downloadPercentage = updateDownloadPercentage(operations.updateProgress);
+  const hasFailure = operations.backupFailed || operations.updateFailed;
+
+  return (
+    <details className="status-notification-server-operations">
+      <summary className="status-notification-server-operations-summary">
+        <span className="status-notification-server-operations-summary-title">
+          <ShieldCheck className="h-4 w-4" aria-hidden="true" />
+          {catalogMessage('platform.product.serverOperationsTitle')}
+        </span>
+        <span className="status-notification-server-operations-summary-state">
+          {operations.isInstallingUpdate || operations.isBackingUp
+            ? catalogMessage('platform.product.serverRuntimeChecking')
+            : catalogMessage('platform.product.serverRuntimeServiceContinuity')}
+        </span>
+      </summary>
+
+      <div className="status-notification-server-operations-grid">
+        <section className="status-notification-server-operation-card">
+          <div className="status-notification-server-operation-heading">
+            <ArchiveRestore className="h-4 w-4" aria-hidden="true" />
+            <span>{catalogMessage('platform.product.serverBackupTitle')}</span>
+          </div>
+          <p className="status-notification-server-operation-detail">
+            {operations.backupStatus?.detail ??
+              catalogMessage('platform.product.serverBackupUnavailable')}
+          </p>
+          <button
+            type="button"
+            className="status-notification-server-operation-button"
+            onClick={() => void operations.requestBackup()}
+            disabled={operations.isBackingUp || operations.isInstallingUpdate}
+          >
+            {operations.isBackingUp
+              ? catalogMessage('platform.product.serverBackupRequested')
+              : catalogMessage('platform.product.serverBackupCreate')}
+          </button>
+        </section>
+
+        <section className="status-notification-server-operation-card">
+          <div className="status-notification-server-operation-heading">
+            {operations.isInstallingUpdate ? (
+              <LoaderCircle className="h-4 w-4 animate-spin" aria-hidden="true" />
+            ) : (
+              <Download className="h-4 w-4" aria-hidden="true" />
+            )}
+            <span>{catalogMessage('platform.product.serverUpdateTitle')}</span>
+          </div>
+          <p className="status-notification-server-operation-detail">{updateDetail}</p>
+          {downloadPercentage !== null && (
+            <div
+              className="status-notification-server-update-progress"
+              role="progressbar"
+              aria-valuemin={0}
+              aria-valuemax={100}
+              aria-valuenow={downloadPercentage}
+              aria-label={updateDetail}
+            >
+              <span style={{ width: `${downloadPercentage}%` }} />
+            </div>
+          )}
+          <button
+            type="button"
+            className="status-notification-server-operation-button"
+            onClick={() => void operations.checkForUpdate()}
+            disabled={operations.isInstallingUpdate || operations.isBackingUp}
+          >
+            {operations.isInstallingUpdate
+              ? catalogMessage('platform.product.serverUpdateInstalling')
+              : catalogMessage('platform.product.serverUpdateCheck')}
+          </button>
+        </section>
+      </div>
+
+      {hasFailure && (
+        <p className="status-notification-server-operation-error">
+          {catalogMessage('platform.product.serverOperationRetry')}
+        </p>
+      )}
+    </details>
+  );
+}
diff --git a/frontend/components/platform/ServerRuntimeGate.tsx b/frontend/components/platform/ServerRuntimeGate.tsx
index 93564edc..0c8cc4ad 100644
--- a/frontend/components/platform/ServerRuntimeGate.tsx
+++ b/frontend/components/platform/ServerRuntimeGate.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import { type ReactNode, useCallback, useEffect, useState } from 'react';
+import { type ReactNode, useCallback, useEffect, useRef, useState } from 'react';
 import {
   Activity,
   CircleAlert,
@@ -19,15 +19,10 @@ import {
 } from '@/lib/server-readiness';
 import {
   readServerRuntimeStatus,
-  readServerBackupStatus,
-  requestServerBackup,
   startServerRuntime,
-  type ServerBackupStatus,
   type ServerRuntimeComponent,
   type ServerRuntimeStatus,
 } from '@/lib/server-runtime';
-import { installSignedServerDesktopUpdate } from '@/lib/server-desktop-updater';
-import { type DesktopUpdateProgress } from '@/lib/desktop-auto-updater';
 
 interface ServerRuntimeGateProps {
   children: ReactNode;
@@ -59,157 +54,46 @@ function RuntimeShell({ children }: { children: ReactNode }) {
   );
 }
 
-function ServerOperationsPanel() {
-  const [backupStatus, setBackupStatus] = useState<ServerBackupStatus | null>(null);
-  const [updateProgress, setUpdateProgress] = useState<DesktopUpdateProgress | null>(null);
-  const [isBackingUp, setIsBackingUp] = useState(false);
-  const [isInstallingUpdate, setIsInstallingUpdate] = useState(false);
-  const [backupFailed, setBackupFailed] = useState(false);
-  const [updateFailed, setUpdateFailed] = useState(false);
-
-  useEffect(() => {
-    let active = true;
-    const refresh = async () => {
-      const status = await readServerBackupStatus();
-      if (active && status) setBackupStatus(status);
-    };
-    void refresh();
-    const interval = window.setInterval(() => void refresh(), 5_000);
-    return () => {
-      active = false;
-      window.clearInterval(interval);
-    };
-  }, []);
-
-  const requestBackup = async () => {
-    setIsBackingUp(true);
-    setBackupFailed(false);
-    try {
-      const status = await requestServerBackup();
-      if (!status) {
-        setBackupFailed(true);
-        return;
-      }
-      setBackupStatus({
-        ...status,
-        state: 'pending',
-        detail: catalogMessage('platform.product.serverBackupRequested'),
-      });
-    } catch {
-      setBackupFailed(true);
-    } finally {
-      setIsBackingUp(false);
-    }
-  };
-
-  const installUpdate = useCallback(async () => {
-    setIsInstallingUpdate(true);
-    setUpdateFailed(false);
-    try {
-      await installSignedServerDesktopUpdate({ onProgress: setUpdateProgress });
-    } catch {
-      setUpdateFailed(true);
-    } finally {
-      setIsInstallingUpdate(false);
-    }
-  }, []);
-
-  useEffect(() => {
-    void installUpdate();
-  }, [installUpdate]);
-
-  const updateDetail = (() => {
-    switch (updateProgress?.phase) {
-      case 'checking':
-        return catalogMessage('platform.product.serverUpdateChecking');
-      case 'available':
-        return catalogMessage('platform.product.serverUpdateAvailableVersion', {
-          version: updateProgress.version,
-        });
-      case 'downloading': {
-        const percentage =
-          updateProgress.totalBytes && updateProgress.downloadedBytes !== undefined
-            ? Math.min(100, Math.round((updateProgress.downloadedBytes / updateProgress.totalBytes) * 100))
-            : undefined;
-        return percentage === undefined
-          ? catalogMessage('platform.product.serverUpdateDownloading')
-          : catalogMessage('platform.product.serverUpdateDownloadingProgress', { percentage });
-      }
-      case 'preparing':
-        return catalogMessage('platform.product.serverUpdatePreparing');
-      case 'installing':
-      case 'relaunching':
-        return catalogMessage('platform.product.serverUpdateInstalling');
-      case 'recovering':
-        return catalogMessage('platform.product.serverUpdateRecovering');
-      case 'up-to-date':
-      default:
-        return catalogMessage('platform.product.serverUpdateNone');
-    }
-  })();
-
-  return (
-    <aside className="fixed bottom-4 right-4 z-40 w-[min(26rem,calc(100vw-2rem))] rounded-2xl border border-slate-200 bg-white/95 p-4 shadow-[0_18px_45px_rgba(35,48,69,0.18)] backdrop-blur">
-      <div className="flex items-center gap-2 text-sm font-extrabold text-slate-900">
-        <ShieldCheck className="h-4 w-4 text-[#556681]" aria-hidden="true" />
-        {catalogMessage('platform.product.serverOperationsTitle')}
-      </div>
-      <div className="mt-3 grid gap-3 sm:grid-cols-2">
-        <section className="rounded-xl bg-slate-50 p-3">
-          <p className="text-xs font-bold text-slate-800">
-            {catalogMessage('platform.product.serverBackupTitle')}
-          </p>
-          <p className="mt-1 min-h-10 text-xs leading-5 text-slate-600" aria-live="polite">
-            {backupStatus?.detail ?? catalogMessage('platform.product.serverBackupUnavailable')}
-          </p>
-          <button
-            type="button"
-            className="mt-3 inline-flex w-full items-center justify-center rounded-lg border border-slate-300 bg-white px-3 py-2 text-xs font-bold text-slate-800 transition hover:bg-slate-100 disabled:cursor-not-allowed disabled:opacity-60"
-            onClick={() => void requestBackup()}
-            disabled={isBackingUp || isInstallingUpdate}
-          >
-            {isBackingUp
-              ? catalogMessage('platform.product.serverBackupRequested')
-              : catalogMessage('platform.product.serverBackupCreate')}
-          </button>
-        </section>
-        <section className="rounded-xl bg-slate-50 p-3">
-          <p className="text-xs font-bold text-slate-800">
-            {catalogMessage('platform.product.serverUpdateTitle')}
-          </p>
-          <p className="mt-1 min-h-10 text-xs leading-5 text-slate-600" aria-live="polite">
-            {updateDetail}
-          </p>
-          <button
-            type="button"
-            className="mt-3 inline-flex w-full items-center justify-center rounded-lg border border-slate-300 bg-white px-3 py-2 text-xs font-bold text-slate-800 transition hover:bg-slate-100 disabled:cursor-not-allowed disabled:opacity-60"
-            onClick={() => void installUpdate()}
-            disabled={isInstallingUpdate || isBackingUp}
-          >
-            {isInstallingUpdate
-              ? catalogMessage('platform.product.serverUpdateInstalling')
-              : catalogMessage('platform.product.serverUpdateCheck')}
-          </button>
-        </section>
-      </div>
-      {backupFailed || updateFailed ? (
-        <p className="mt-3 text-xs leading-5 text-rose-700">
-          {catalogMessage('platform.product.serverOperationRetry')}
-        </p>
-      ) : null}
-    </aside>
-  );
+export function shouldAutomaticallyStartRuntime(
+  status: ServerRuntimeStatus | null,
+  hasAttemptedAutoStart: boolean
+): boolean {
+  return Boolean(status?.runtimePresent && status.state !== 'ready' && !hasAttemptedAutoStart);
 }
 
 export function ServerRuntimeGate({ children }: ServerRuntimeGateProps) {
   const [readiness, setReadiness] = useState<ServerReadinessState>(() => initialServerReadiness());
   const [runtimeStatus, setRuntimeStatus] = useState<ServerRuntimeStatus | null>(null);
   const [isStarting, setIsStarting] = useState(false);
+  const [autoStartFailed, setAutoStartFailed] = useState(false);
+  const hasAttemptedAutoStart = useRef(false);
 
-  const applyRuntimeStatus = (status: ServerRuntimeStatus) => {
+  const applyRuntimeStatus = useCallback((status: ServerRuntimeStatus) => {
     setRuntimeStatus(status);
     setReadiness(resolveServerReadiness(status.state === 'ready'));
-  };
+  }, []);
+
+  const startRuntime = useCallback(async (): Promise<boolean> => {
+    setIsStarting(true);
+    try {
+      const status = await startServerRuntime();
+      if (!status) return false;
+
+      applyRuntimeStatus(status);
+      if (status.state === 'ready') return true;
+
+      for (let attempt = 0; attempt < 15; attempt += 1) {
+        await new Promise((resolve) => window.setTimeout(resolve, 2_000));
+        const nextStatus = await readServerRuntimeStatus();
+        if (!nextStatus) continue;
+        applyRuntimeStatus(nextStatus);
+        if (nextStatus.state === 'ready') return true;
+      }
+      return false;
+    } finally {
+      setIsStarting(false);
+    }
+  }, [applyRuntimeStatus]);
 
   useEffect(() => {
     let active = true;
@@ -219,7 +103,7 @@ export function ServerRuntimeGate({ children }: ServerRuntimeGateProps) {
     return () => {
       active = false;
     };
-  }, []);
+  }, [applyRuntimeStatus]);
 
   useEffect(() => {
     if (!runtimeStatus?.runtimePresent || runtimeStatus.state === 'ready') {
@@ -239,7 +123,18 @@ export function ServerRuntimeGate({ children }: ServerRuntimeGateProps) {
       active = false;
       window.clearInterval(interval);
     };
-  }, [runtimeStatus?.runtimePresent, runtimeStatus?.state]);
+  }, [applyRuntimeStatus, runtimeStatus?.runtimePresent, runtimeStatus?.state]);
+
+  useEffect(() => {
+    if (!shouldAutomaticallyStartRuntime(runtimeStatus, hasAttemptedAutoStart.current)) {
+      return;
+    }
+
+    hasAttemptedAutoStart.current = true;
+    void startRuntime().then((started) => {
+      if (!started) setAutoStartFailed(true);
+    });
+  }, [runtimeStatus?.runtimePresent, runtimeStatus?.state, startRuntime]);
 
   useEffect(() => {
     if (readiness.kind !== 'checking') return;
@@ -268,18 +163,13 @@ export function ServerRuntimeGate({ children }: ServerRuntimeGateProps) {
 
   if (readiness.kind === 'not-server') return <>{children}</>;
   if (readiness.kind === 'ready') {
-    return (
-      <>
-        {children}
-        <ServerOperationsPanel />
-      </>
-    );
+    return <>{children}</>;
   }
 
   const isRuntimeProgressing = ['bootstrapping', 'recovering', 'stopping'].includes(
     runtimeStatus?.state ?? ''
   );
-  const isChecking = readiness.kind === 'checking' || isRuntimeProgressing;
+  const isChecking = readiness.kind === 'checking' || isRuntimeProgressing || isStarting;
   const runtimeDetail = runtimeStatus?.detail;
   const componentRows: Array<[string, ServerRuntimeComponent | undefined]> = [
     [catalogMessage('platform.product.serverRuntimeDatabaseComponent'), runtimeStatus?.database],
@@ -290,26 +180,6 @@ export function ServerRuntimeGate({ children }: ServerRuntimeGateProps) {
     const status = await readServerRuntimeStatus();
     if (status) applyRuntimeStatus(status);
   };
-  const startRuntime = async () => {
-    setIsStarting(true);
-    try {
-      const status = await startServerRuntime();
-      if (!status) return;
-
-      applyRuntimeStatus(status);
-      if (status.state === 'ready') return;
-
-      for (let attempt = 0; attempt < 15; attempt += 1) {
-        await new Promise((resolve) => window.setTimeout(resolve, 2_000));
-        const nextStatus = await readServerRuntimeStatus();
-        if (!nextStatus) continue;
-        applyRuntimeStatus(nextStatus);
-        if (nextStatus.state === 'ready') return;
-      }
-    } finally {
-      setIsStarting(false);
-    }
-  };
   return (
     <RuntimeShell>
       <div
@@ -394,11 +264,16 @@ export function ServerRuntimeGate({ children }: ServerRuntimeGateProps) {
                 <RefreshCw className="h-4 w-4" aria-hidden="true" />
                 {catalogMessage('platform.product.serverRuntimeRefreshStatus')}
               </button>
-              {runtimeStatus?.runtimePresent ? (
+              {runtimeStatus?.runtimePresent && autoStartFailed ? (
                 <button
                   type="button"
                   className="inline-flex items-center justify-center gap-2 rounded-lg bg-[#30374c] px-4 py-2.5 text-sm font-extrabold text-white shadow-[0_8px_18px_rgba(48,55,76,0.18)] transition hover:bg-[#233045] focus:outline-none focus:ring-4 focus:ring-[#8192a5]/35 disabled:cursor-not-allowed disabled:opacity-60"
-                  onClick={() => void startRuntime()}
+                  onClick={() => {
+                    setAutoStartFailed(false);
+                    void startRuntime().then((started) => {
+                      if (!started) setAutoStartFailed(true);
+                    });
+                  }}
                   disabled={isStarting}
                 >
                   <Server className="h-4 w-4" aria-hidden="true" />
diff --git a/frontend/package.json b/frontend/package.json
index f1a6fcda..6a4d61f5 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -1,6 +1,6 @@
 {
   "name": "accore",
-  "version": "1.1.9",
+  "version": "0.0.1",
   "private": true,
   "scripts": {
     "dev": "next dev --webpack -p 5000 -H 0.0.0.0",
diff --git a/frontend/scripts/create-release-manifests.mjs b/frontend/scripts/create-release-manifests.mjs
index b183afff..776bfdc9 100644
--- a/frontend/scripts/create-release-manifests.mjs
+++ b/frontend/scripts/create-release-manifests.mjs
@@ -1,6 +1,9 @@
 import { createHash, sign } from 'node:crypto';
 import { readdir, readFile, stat, writeFile, mkdir } from 'node:fs/promises';
-import { basename, extname, join, resolve } from 'node:path';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const frontendRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
 const [assetsDirectory, outputDirectory] = process.argv.slice(2);
 if (!assetsDirectory || !outputDirectory) {
@@ -22,6 +25,7 @@ const releaseVersion = tag.replace(/^desktop-v/, '');
 if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(releaseVersion)) {
   throw new Error(`desktop tag ${tag} does not contain a semantic version`);
 }
+await assertReleaseVersionMatchesDesktopSources(releaseVersion);
 
 const sourceRevision = process.env.ACCORE_SOURCE_REVISION;
 if (!/^[0-9a-f]{40,64}$/i.test(sourceRevision)) {
@@ -103,7 +107,8 @@ async function writeTauriUpdaterManifest(product, files, destination, generatedA
     Object.entries(candidatesByPlatform).map(([platform, candidates]) => {
       const [selected] = candidates.sort(
         (left, right) =>
-          updaterArtifactPriority(left.artifactPath) - updaterArtifactPriority(right.artifactPath) ||
+          updaterArtifactPriority(left.artifactPath) -
+            updaterArtifactPriority(right.artifactPath) ||
           basename(left.artifactPath).localeCompare(basename(right.artifactPath))
       );
       return [platform, { signature: selected.signature, url: selected.url }];
@@ -233,3 +238,24 @@ async function findFiles(root) {
   }
   return files;
 }
+
+async function assertReleaseVersionMatchesDesktopSources(releaseVersion) {
+  const [packageRaw, tauriRaw, cargoRaw] = await Promise.all([
+    readFile(join(frontendRoot, 'package.json'), 'utf8'),
+    readFile(join(frontendRoot, 'src-tauri', 'tauri.conf.json'), 'utf8'),
+    readFile(join(frontendRoot, 'src-tauri', 'Cargo.toml'), 'utf8'),
+  ]);
+  const packageVersion = JSON.parse(packageRaw).version;
+  const tauriVersion = JSON.parse(tauriRaw).version;
+  const cargoVersion = /^version\s*=\s*"([^"]+)"/m.exec(cargoRaw)?.[1];
+  const sources = { package: packageVersion, tauri: tauriVersion, cargo: cargoVersion };
+  const mismatchedSources = Object.entries(sources)
+    .filter(([, version]) => version !== releaseVersion)
+    .map(([source, version]) => `${source}=${version ?? 'missing'}`);
+
+  if (mismatchedSources.length > 0) {
+    throw new Error(
+      `desktop tag ${tag} must match embedded package versions; found ${mismatchedSources.join(', ')}`
+    );
+  }
+}
diff --git a/frontend/scripts/create-release-manifests.test.mjs b/frontend/scripts/create-release-manifests.test.mjs
index 6ac8adab..26037699 100644
--- a/frontend/scripts/create-release-manifests.test.mjs
+++ b/frontend/scripts/create-release-manifests.test.mjs
@@ -16,8 +16,8 @@ test('generates manifests and updater URLs from normalized GitHub asset names',
   const { privateKey } = generateKeyPairSync('ed25519');
 
   for (const product of ['Client', 'Server']) {
-    await writeFixture(assets, `Accore.${product}_1.0.0_amd64.AppImage`);
-    await writeFixture(assets, `Accore.${product}_1.0.0_amd64.AppImage.sig`, 'linux-signature');
+    await writeFixture(assets, `Accore.${product}_0.0.1_amd64.AppImage`);
+    await writeFixture(assets, `Accore.${product}_0.0.1_amd64.AppImage.sig`, 'linux-signature');
     await writeFixture(assets, `Accore.${product}_aarch64.app.tar.gz`);
     await writeFixture(assets, `Accore.${product}_aarch64.app.tar.gz.sig`, 'arm-signature');
     await writeFixture(assets, `Accore.${product}_x86_64.app.tar.gz`);
@@ -28,30 +28,31 @@ test('generates manifests and updater URLs from normalized GitHub asset names',
     stdio: 'pipe',
     env: {
       ...process.env,
-      ACCORE_RELEASE_TAG: 'desktop-v1.0.0',
+      ACCORE_RELEASE_TAG: 'desktop-v0.0.1',
       ACCORE_SOURCE_REVISION: 'a'.repeat(40),
       ACCORE_MANIFEST_KEY_ID: 'test-ed25519',
       ACCORE_MANIFEST_PRIVATE_KEY: privateKey.export({ type: 'pkcs8', format: 'pem' }),
-      ACCORE_RELEASE_BASE_URL: 'https://example.test/releases/desktop-v1.0.0',
+      ACCORE_RELEASE_BASE_URL: 'https://example.test/releases/desktop-v0.0.1',
     },
   });
 
   const clientManifest = await readJson(join(output, 'accore-client-manifest.json'));
+  assert.equal(clientManifest.release_version, '0.0.1');
   assert.equal(clientManifest.artifacts[0].download_url.includes('Accore.Client'), true);
 
   const clientUpdater = await readJson(join(output, 'accore-client-updater.json'));
   assert.deepEqual(clientUpdater.platforms, {
     'darwin-aarch64': {
       signature: 'arm-signature',
-      url: 'https://example.test/releases/desktop-v1.0.0/Accore.Client_aarch64.app.tar.gz',
+      url: 'https://example.test/releases/desktop-v0.0.1/Accore.Client_aarch64.app.tar.gz',
     },
     'darwin-x86_64': {
       signature: 'intel-signature',
-      url: 'https://example.test/releases/desktop-v1.0.0/Accore.Client_x86_64.app.tar.gz',
+      url: 'https://example.test/releases/desktop-v0.0.1/Accore.Client_x86_64.app.tar.gz',
     },
     'linux-x86_64': {
       signature: 'linux-signature',
-      url: 'https://example.test/releases/desktop-v1.0.0/Accore.Client_1.0.0_amd64.AppImage',
+      url: 'https://example.test/releases/desktop-v0.0.1/Accore.Client_0.0.1_amd64.AppImage',
     },
   });
 });
diff --git a/frontend/scripts/i18n-inventory.ts b/frontend/scripts/i18n-inventory.ts
index 8eb7a56e..8edd1d86 100644
--- a/frontend/scripts/i18n-inventory.ts
+++ b/frontend/scripts/i18n-inventory.ts
@@ -79,7 +79,7 @@ function isTechnicalValue(value: string): boolean {
         || (!hasArabic && /^\{value\d+\}\/\{value\d+\}$/u.test(value))
         || (!hasArabic && /^\{value\d+\}(?:\s*[()|—:-]\s*\{value\d+\})*$/u.test(value))
         || (!hasArabic && /^(?:line|column) \{value\d+\}$/i.test(value))
-        || (!hasArabic && /^(?:operating-readiness|runtime-error|runtime-rejection|fiscal-period-nearing-end|legacy-error):/i.test(value))
+        || (!hasArabic && /^(?:operating-readiness|runtime-error|runtime-rejection|fiscal-period-nearing-end|legacy-error|server-operations):/i.test(value))
         || (!hasArabic && /^(?:err|notification)_[a-z0-9_{}-]+$/i.test(value));
 }
 
diff --git a/frontend/src-tauri/Cargo.toml b/frontend/src-tauri/Cargo.toml
index 02377e34..4205335a 100644
--- a/frontend/src-tauri/Cargo.toml
+++ b/frontend/src-tauri/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "accore-desktop"
-version = "1.1.9"
+version = "0.0.1"
 description = "ACCORE ERP Desktop application"
 authors = ["Accore ERP Contributors"]
 license = "MIT"
diff --git a/frontend/src-tauri/tauri.conf.json b/frontend/src-tauri/tauri.conf.json
index 6cf16903..dc72e300 100644
--- a/frontend/src-tauri/tauri.conf.json
+++ b/frontend/src-tauri/tauri.conf.json
@@ -1,7 +1,7 @@
 {
   "$schema": "../node_modules/@tauri-apps/cli/config.schema.json",
   "productName": "ACCORE ERP Desktop",
-  "version": "1.1.9",
+  "version": "0.0.1",
   "identifier": "com.accore.erp",
   "build": {
     "frontendDist": "../out",
diff --git a/frontend/tests/components/server-runtime-gate.test.ts b/frontend/tests/components/server-runtime-gate.test.ts
new file mode 100644
index 00000000..84381073
--- /dev/null
+++ b/frontend/tests/components/server-runtime-gate.test.ts
@@ -0,0 +1,32 @@
+import { getServerUpdateProgressDetail } from '@/components/platform/ServerOperationsNotificationCenter';
+import { shouldAutomaticallyStartRuntime } from '@/components/platform/ServerRuntimeGate';
+import { catalogMessage } from '@/lib/i18n';
+
+describe('Server Desktop runtime experience', () => {
+  it('requests one automatic start only when a packaged server is not ready', () => {
+    const stoppedStatus = {
+      state: 'stopped',
+      detail: 'service is stopped',
+      runtimePresent: true,
+    };
+
+    expect(shouldAutomaticallyStartRuntime(stoppedStatus as never, false)).toBe(true);
+    expect(shouldAutomaticallyStartRuntime(stoppedStatus as never, true)).toBe(false);
+    expect(
+      shouldAutomaticallyStartRuntime({ ...stoppedStatus, state: 'ready' } as never, false)
+    ).toBe(false);
+    expect(
+      shouldAutomaticallyStartRuntime({ ...stoppedStatus, runtimePresent: false } as never, false)
+    ).toBe(false);
+  });
+
+  it('keeps signed-update download progress in the bottom notification wording', () => {
+    expect(
+      getServerUpdateProgressDetail({
+        phase: 'downloading',
+        downloadedBytes: 50,
+        totalBytes: 200,
+      })
+    ).toBe(catalogMessage('platform.product.serverUpdateDownloadingProgress', { percentage: 25 }));
+  });
+});

From e5ea1d5824c042b5d3685dcfd528c40a11ba8588 Mon Sep 17 00:00:00 2001
From: Emran025 <1.48263577e+08+Emran025@users.noreply.github.com>
Date: Fri, 21 Aug 2026 23:57:22 +0000
Subject: [PATCH 2/9] feat(setup): improve language settings and financial
 references

---
 .../Services/OrgStructureService.php          |  22 +++-
 .../database/seeders/OrgStructureSeeder.php   |   3 +-
 .../Feature/Api/FactoryCalendarApiTest.php    |  52 +++++++++
 .../setup-language-and-finance-ux-design.md   |  30 +++++
 .../system-settings/(pages)/page.tsx          |   5 +-
 .../ApplicationLanguageSettingsTab.tsx        |  68 +++++++++++
 .../org-structure/org-hierarchy/README.md     |   6 +-
 frontend/app/globals.css                      |  25 +++++
 .../OrganizationArchitectureWorkspace.tsx     |  50 ++++++++-
 .../components/SetupAccountingSection.tsx     |   7 +-
 .../components/SetupOperatingScopeSection.tsx |   9 +-
 frontend/app/setup/layout.tsx                 |  27 ++++-
 frontend/app/setup/page.tsx                   |  18 ++-
 .../TopGlobalBar/components/GlobalMeta.tsx    |   4 +-
 frontend/components/ui/SearchableSelect.tsx   |  16 +--
 frontend/i18n/catalog/en-US.json              |  21 +++-
 frontend/i18n/catalog/source.json             | 106 +++++++++++++++++-
 frontend/lib/i18n/catalog/ar-SA.ts            |  23 +++-
 frontend/lib/i18n/catalog/en-US.ts            |  23 +++-
 frontend/lib/utils.ts                         |  26 +++++
 .../app/application-language-settings.test.ts |  35 ++++++
 frontend/tests/app/setup-onboarding.test.ts   |  36 +++++-
 frontend/tests/lib/input-direction.test.ts    |  20 ++++
 23 files changed, 582 insertions(+), 50 deletions(-)
 create mode 100644 docs/Plans/setup-language-and-finance-ux-design.md
 create mode 100644 frontend/app/01-enterprise-core/identity-access/user-management/system-settings/components/ApplicationLanguageSettingsTab.tsx
 create mode 100644 frontend/tests/app/application-language-settings.test.ts
 create mode 100644 frontend/tests/lib/input-direction.test.ts

diff --git a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OrgStructureService.php b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OrgStructureService.php
index e5841bea..bac464b2 100644
--- a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OrgStructureService.php
+++ b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OrgStructureService.php
@@ -20,6 +20,7 @@
  */
 class OrgStructureService
 {
+    private const PRIMARY_GENERAL_LEDGER_REFERENCE = 'ACCORE-PRIMARY-GL';
     // ─── Change History ─────────────────────────────────────────────────
 
     /**
@@ -140,10 +141,29 @@ public function validateNodeAttributes(string $nodeTypeId, array $attributes): v
         }
 
         $chartOfAccountsId = data_get($attributes, 'chart_of_accounts_id');
-        if ($chartOfAccountsId !== null && $chartOfAccountsId !== '' && !ChartOfAccount::query()->whereKey($chartOfAccountsId)->where('is_active', true)->exists()) {
+        if ($chartOfAccountsId === self::PRIMARY_GENERAL_LEDGER_REFERENCE) {
+            $requiredTypes = ['asset', 'liability', 'equity', 'revenue', 'expense'];
+            $activeTypes = ChartOfAccount::query()->where('is_active', true)->pluck('account_type')
+                ->map(fn ($type) => strtolower((string) $type))->unique()->all();
+            if (array_diff($requiredTypes, $activeTypes) !== []) {
+                $errors[] = 'The primary general ledger is incomplete and cannot yet be assigned to a company code.';
+            }
+        } elseif ($chartOfAccountsId !== null && $chartOfAccountsId !== '' && !ChartOfAccount::query()->whereKey($chartOfAccountsId)->where('is_active', true)->exists()) {
             $errors[] = 'The selected chart-of-accounts reference does not exist or is inactive.';
         }
 
+        $fiscalYearVariant = data_get($attributes, 'fiscal_year_variant');
+        if ($fiscalYearVariant !== null && $fiscalYearVariant !== '' && $fiscalYearVariant !== 'K4') {
+            $errors[] = 'Only the K4 calendar-year structure is available during the current setup workflow.';
+        }
+
+        foreach (['language', 'default_language'] as $languageAttribute) {
+            $language = data_get($attributes, $languageAttribute);
+            if ($language !== null && $language !== '' && !in_array($language, ['ar-SA', 'en-US'], true)) {
+                $errors[] = "The {$languageAttribute} must be one of the supported ACCORE locales.";
+            }
+        }
+
         if (!empty($errors)) {
             throw ValidationException::withMessages(['attributes' => $errors]);
         }
diff --git a/backend/database/seeders/OrgStructureSeeder.php b/backend/database/seeders/OrgStructureSeeder.php
index de4bcee7..f6ad2712 100644
--- a/backend/database/seeders/OrgStructureSeeder.php
+++ b/backend/database/seeders/OrgStructureSeeder.php
@@ -331,7 +331,8 @@ private function seedAttributes(): void
             ['org_meta_type_id' => 'COMP_CODE', 'attribute_key' => 'country_code', 'attribute_type' => 'string', 'is_mandatory' => false, 'sort_order' => 3],
             ['org_meta_type_id' => 'COMP_CODE', 'attribute_key' => 'name', 'attribute_type' => 'string', 'is_mandatory' => false, 'sort_order' => 4],
             ['org_meta_type_id' => 'COMP_CODE', 'attribute_key' => 'city', 'attribute_type' => 'string', 'is_mandatory' => false, 'sort_order' => 5],
-            ['org_meta_type_id' => 'COMP_CODE', 'attribute_key' => 'fiscal_year_variant', 'attribute_type' => 'string', 'is_mandatory' => false, 'sort_order' => 6],
+            ['org_meta_type_id' => 'COMP_CODE', 'attribute_key' => 'language', 'attribute_type' => 'string', 'is_mandatory' => false, 'sort_order' => 6],
+            ['org_meta_type_id' => 'COMP_CODE', 'attribute_key' => 'fiscal_year_variant', 'attribute_type' => 'string', 'is_mandatory' => false, 'sort_order' => 7],
 
             // ── Controlling Area ──
             ['org_meta_type_id' => 'CONTROLLING_AREA', 'attribute_key' => 'currency_id', 'attribute_type' => 'string', 'is_mandatory' => false, 'sort_order' => 1],
diff --git a/backend/tests/Feature/Api/FactoryCalendarApiTest.php b/backend/tests/Feature/Api/FactoryCalendarApiTest.php
index 5c9650ff..d3ee17d2 100644
--- a/backend/tests/Feature/Api/FactoryCalendarApiTest.php
+++ b/backend/tests/Feature/Api/FactoryCalendarApiTest.php
@@ -149,6 +149,58 @@ public function test_company_code_requires_active_currency_and_chart_of_accounts
         $this->assertAccountingReferenceValidationFails($service, '999999', '999999');
     }
 
+    public function test_company_code_can_assign_only_a_complete_primary_general_ledger_and_k4_structure(): void
+    {
+        OrgMetaType::create([
+            'id' => 'COMP_CODE',
+            'display_name' => 'Company Code',
+            'display_name_ar' => 'رمز الشركة',
+            'level_domain' => 'Financial',
+            'is_assignable' => true,
+        ]);
+        foreach (['currency_id', 'chart_of_accounts_id'] as $index => $attributeKey) {
+            OrgMetaTypeAttribute::create([
+                'org_meta_type_id' => 'COMP_CODE',
+                'attribute_key' => $attributeKey,
+                'attribute_type' => 'reference',
+                'is_mandatory' => true,
+                'sort_order' => $index + 1,
+            ]);
+        }
+
+        $currency = Currency::create([
+            'code' => 'SAR',
+            'name' => 'Saudi Riyal',
+            'symbol' => 'SAR',
+            'is_active' => true,
+        ]);
+        foreach (['asset', 'liability', 'equity', 'revenue', 'expense'] as $index => $type) {
+            ChartOfAccount::create([
+                'account_code' => (string) (1000 + $index),
+                'account_name' => ucfirst($type),
+                'account_type' => $type,
+                'is_active' => true,
+            ]);
+        }
+
+        $service = app(OrgStructureService::class);
+        $service->validateNodeAttributes('COMP_CODE', [
+            'currency_id' => (string) $currency->id,
+            'chart_of_accounts_id' => 'ACCORE-PRIMARY-GL',
+            'fiscal_year_variant' => 'K4',
+            'language' => 'ar-SA',
+        ]);
+        $this->addToAssertionCount(1);
+
+        $this->expectException(ValidationException::class);
+        $service->validateNodeAttributes('COMP_CODE', [
+            'currency_id' => (string) $currency->id,
+            'chart_of_accounts_id' => 'ACCORE-PRIMARY-GL',
+            'fiscal_year_variant' => 'K4',
+            'language' => 'fa-IR',
+        ]);
+    }
+
     private function assertCalendarValidationFails(OrgStructureService $service, string $calendarId, string $countryCode): void
     {
         try {
diff --git a/docs/Plans/setup-language-and-finance-ux-design.md b/docs/Plans/setup-language-and-finance-ux-design.md
new file mode 100644
index 00000000..f75fd1f4
--- /dev/null
+++ b/docs/Plans/setup-language-and-finance-ux-design.md
@@ -0,0 +1,30 @@
+# Setup Language and Financial Reference UX Design
+
+## Purpose
+
+This design record governs the current setup-experience refinement. It intentionally does **not** redesign the chart of accounts, its hierarchy, or its posting rules. The work improves the language experience, makes the company-code financial attributes intelligible, and removes an ambiguous free-text fiscal-year field.
+
+## Language Boundaries
+
+The application interface language is a local desktop/browser preference. It controls the active dictionary, document language, layout direction, and the UI font. It is persisted through the existing `LocaleProvider` under `accore.locale` and must be changed from the primary System Settings screen.
+
+The organization-context language is different. A client or company-code language describes master data or business context; it must not silently change the current user's application interface. The two concepts are presented as separate settings and use separate labels.
+
+All free-text setup inputs use Unicode-aware first-strong-character direction detection. Arabic, Persian, Hebrew, Syriac, and other right-to-left scripts render right-to-left; Latin and other left-to-right text render left-to-right. Numeric, date, currency, code, and controlled-reference inputs retain their explicit structured behavior.
+
+## Company Code and Chart of Accounts
+
+A company code represents a legally or financially independent accounting unit. The `chart_of_accounts_id` company-code attribute is an assignment to the accounting structure that supplies the general-ledger accounts available to that company code. It is **not** an instruction to choose an individual posting account such as Assets, Cash, or Revenue.
+
+The current ACCORE data model uses `ChartOfAccount` rows as individual accounts, while the organization metadata calls the foreign key `chart_of_accounts_id`. Until a dedicated chart-of-accounts header entity exists, the setup flow must not imply that an individual account is a complete chart. The UI therefore explains the current reference precisely, labels it as an active general-ledger account reference, and gives a structured warning that a production multi-company implementation requires a chart header or ledger-set entity before a company-code chart assignment can be semantically complete.
+
+## Fiscal Year Structure
+
+A fiscal year is a reporting and inventory/balance-sheet period, normally twelve months, divided into posting periods. A fiscal-year variant describes the period pattern and any special closing periods. A company code is assigned one fiscal-year variant, while the periods themselves determine how posting dates are classified. The fiscal-year variant does not itself open or close posting periods.
+
+ACCORE currently stores operational `FiscalPeriod` records but has no dedicated fiscal-year-variant master entity. The setup field therefore must be renamed from the opaque “Fiscal year variant” label to a clear “Fiscal year structure” field and constrained to explicit supported choices. The initial choices are calendar year (`K4`) and a controlled custom-year configuration. The calendar-year choice is the safe default. A custom year is only a descriptor until the system has a managed variant and period-definition model; the UI makes that status explicit rather than suggesting unsupported automation.
+
+## References
+
+1. [SAP Help Portal — Fiscal Year and Fiscal Year Variant](https://help.sap.com/docs/SAP_S4HANA_CLOUD/0fa84c9d9c634132b7c4abb9ffdd8f06/7353d7531a4d424de10000000a174cb4.html)
+2. [SAP Learning — Managing Fiscal Year Variants](https://learning.sap.com/courses/customizing-core-settings-in-financial-accounting-in-sap-s4hana/managing-fiscal-year-variants-1)
diff --git a/frontend/app/01-enterprise-core/identity-access/user-management/system-settings/(pages)/page.tsx b/frontend/app/01-enterprise-core/identity-access/user-management/system-settings/(pages)/page.tsx
index 640b608c..c7098f62 100644
--- a/frontend/app/01-enterprise-core/identity-access/user-management/system-settings/(pages)/page.tsx
+++ b/frontend/app/01-enterprise-core/identity-access/user-management/system-settings/(pages)/page.tsx
@@ -9,17 +9,19 @@ import { InvoiceSettingsTab } from "../components/InvoiceSettingsTab";
 import { SecurityTab } from "../components/SecurityTab";
 import { SessionsTab } from "../components/SessionsTab";
 import { StoreSettingsTab } from "../components/StoreSettingsTab";
+import { ApplicationLanguageSettingsTab } from "../components/ApplicationLanguageSettingsTab";
 
 
 export default function SettingsPage() {
     const { t: i18n } = useI18n();
-  const [activeTab, setActiveTab] = useState("store");
+  const [activeTab, setActiveTab] = useState("language");
 
   return (
     <MainLayout requiredModule="settings">
       <div className="settings-wrapper animate-fade">
         <TabNavigation
           tabs={[
+            { key: "language", label: i18n.catalog["enterpriseCore.systemSettings.applicationLanguage"], icon: "fa-language" },
             { key: "store", label: i18n.catalog["common.general.storeInformation"], icon: "fa-store" },
             { key: "invoice", label: i18n.catalog["common.general.invoiceSettings"], icon: "fa-file-invoice" },
             { key: "security", label: i18n.catalog["enterpriseCore.systemSettings.accountSecurity"], icon: "fa-lock" },
@@ -31,6 +33,7 @@ export default function SettingsPage() {
 
         <div style={{ marginTop: "1rem", }}>
           {activeTab === "store" && <StoreSettingsTab />}
+          {activeTab === "language" && <ApplicationLanguageSettingsTab />}
           {activeTab === "invoice" && <InvoiceSettingsTab />}
           {activeTab === "security" && <SecurityTab />}
           {activeTab === "sessions" && <SessionsTab />}
diff --git a/frontend/app/01-enterprise-core/identity-access/user-management/system-settings/components/ApplicationLanguageSettingsTab.tsx b/frontend/app/01-enterprise-core/identity-access/user-management/system-settings/components/ApplicationLanguageSettingsTab.tsx
new file mode 100644
index 00000000..e664ccc7
--- /dev/null
+++ b/frontend/app/01-enterprise-core/identity-access/user-management/system-settings/components/ApplicationLanguageSettingsTab.tsx
@@ -0,0 +1,68 @@
+'use client';
+
+import { catalogText, getLocaleRegistry, type SupportedLocale, useI18n } from '@/lib/i18n';
+
+export function ApplicationLanguageSettingsTab() {
+  const { locale, metadata, setLocale, t: i18n } = useI18n();
+  const locales = Object.values(getLocaleRegistry());
+
+  return (
+    <section
+      className="sales-card application-language-settings"
+      aria-labelledby="application-language-title"
+    >
+      <header className="application-language-settings-header">
+        <div>
+          <span className="application-language-settings-eyebrow">
+            {i18n.catalog['enterpriseCore.systemSettings.applicationLanguage']}
+          </span>
+          <h3 id="application-language-title">
+            {i18n.catalog['enterpriseCore.systemSettings.applicationLanguageTitle']}
+          </h3>
+          <p>{i18n.catalog['enterpriseCore.systemSettings.applicationLanguageDescription']}</p>
+        </div>
+        <div className="application-language-current" dir={metadata.direction}>
+          <span>{i18n.catalog['enterpriseCore.systemSettings.currentLanguage']}</span>
+          <strong>{metadata.nativeName}</strong>
+        </div>
+      </header>
+
+      <div
+        className="application-language-choice-grid"
+        role="list"
+        aria-label={i18n.catalog['enterpriseCore.systemSettings.availableLanguages']}
+      >
+        {locales.map((candidate) => {
+          const active = candidate.code === locale;
+          return (
+            <button
+              key={candidate.code}
+              type="button"
+              className={`application-language-choice ${active ? 'is-active' : ''}`}
+              aria-pressed={active}
+              onClick={() => setLocale(candidate.code as SupportedLocale)}
+              dir={candidate.direction}
+            >
+              <span className="application-language-choice-native">{candidate.nativeName}</span>
+              <span className="application-language-choice-name">{candidate.displayName}</span>
+              <span className="application-language-choice-direction">
+                {candidate.direction.toUpperCase()}
+              </span>
+              <span className="application-language-choice-status">
+                {active
+                  ? i18n.catalog['enterpriseCore.systemSettings.activeLanguage']
+                  : catalogText(i18n, 'enterpriseCore.systemSettings.useLanguage', {
+                      value0: candidate.nativeName,
+                    })}
+              </span>
+            </button>
+          );
+        })}
+      </div>
+
+      <p className="application-language-boundary">
+        {i18n.catalog['enterpriseCore.systemSettings.applicationLanguageBoundary']}
+      </p>
+    </section>
+  );
+}
diff --git a/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/README.md b/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/README.md
index dc481e7f..4e9bcfa1 100644
--- a/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/README.md
+++ b/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/README.md
@@ -52,7 +52,7 @@ The system distinguishes between **Definition** (creating the nodes) and **Assig
 ┌────────────────────────────────────────────────────────────────────────────────┐
 | id        | level_domain | Mandatory Attributes (via Org_Meta_Type_Attributes) |
 |-----------|--------------|-----------------------------------------------------|
-| COMP_CODE | Financial    | currency_id, chart_of_accounts_id                   |
+| COMP_CODE | Financial    | currency_id, chart_of_accounts_id, language, fiscal_year_variant |
 | PLANT     | Logistics    | factory_calendar_id, country_code                   |
 | BUS_AREA  | Financial    | (none)                                              |
 | PURCH_ORG | Logistics    | (optional: company_code_id or plant_id)             |
@@ -244,7 +244,7 @@ BEFORE_DELETE ON Structure_Nodes:
       "name": "Riyadh Manufacturing Plant",
       "country_code": "SA",
       "factory_calendar_id": "SA-TH",
-      "language": "AR",
+      "language": "ar-SA",
       "address": {
         "street": "Industrial Area 1",
         "city": "Riyadh",
@@ -298,7 +298,7 @@ BEFORE_DELETE ON Structure_Nodes:
       "name": "Riyadh Manufacturing Plant",
       "country_code": "SA",
       "factory_calendar_id": "SA-TH",
-      "language": "AR",
+      "language": "ar-SA",
       "address": { "street": "Industrial Area 1", "city": "Riyadh", "postal_code": "12345" }
     },
     "status": "active"
diff --git a/frontend/app/globals.css b/frontend/app/globals.css
index 39038d42..2c1db3c5 100644
--- a/frontend/app/globals.css
+++ b/frontend/app/globals.css
@@ -2019,6 +2019,31 @@ tbody tr:hover {
   flex-direction: column;
 }
 
+.application-language-settings { display: grid; gap: 1.25rem; padding: 1.35rem; }
+.application-language-settings-header { display: flex; align-items: flex-start; justify-content: space-between; gap: 1rem; }
+.application-language-settings-header h3 { margin: 0.2rem 0 0.4rem; color: var(--text-primary); font-size: 1.05rem; }
+.application-language-settings-header p, .application-language-boundary { max-width: 46rem; margin: 0; color: var(--text-secondary); font-size: 0.82rem; line-height: 1.65; }
+.application-language-settings-eyebrow { color: var(--primary-color); font-size: 0.7rem; font-weight: 800; letter-spacing: 0.06em; text-transform: uppercase; }
+.application-language-current { min-width: 9rem; padding: 0.65rem 0.75rem; border: 1px solid var(--border-color); border-radius: var(--radius-sm); background: var(--primary-subtle); }
+.application-language-current span, .application-language-current strong { display: block; }
+.application-language-current span { color: var(--text-muted); font-size: 0.66rem; }
+.application-language-current strong { margin-top: 0.15rem; color: var(--text-primary); font-size: 0.84rem; }
+.application-language-choice-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(13rem, 1fr)); gap: 0.75rem; }
+.application-language-choice { display: grid; grid-template-columns: 1fr auto; gap: 0.25rem 0.75rem; min-height: 7rem; padding: 0.9rem; border: 1px solid var(--border-color); border-radius: var(--radius-sm); background: var(--surface-white); color: inherit; cursor: pointer; text-align: start; transition: border-color 160ms ease, box-shadow 160ms ease, transform 160ms ease; }
+.application-language-choice:hover { border-color: var(--primary-color); box-shadow: var(--shadow-sm); transform: translateY(-1px); }
+.application-language-choice.is-active { border-color: var(--primary-color); background: var(--primary-subtle); box-shadow: inset 0 0 0 1px var(--primary-color); }
+.application-language-choice-native { color: var(--text-primary); font-size: 1rem; font-weight: 800; }
+.application-language-choice-name { align-self: center; color: var(--text-muted); font-size: 0.7rem; }
+.application-language-choice-direction { align-self: start; color: var(--primary-color); font-size: 0.64rem; font-weight: 800; letter-spacing: 0.06em; }
+.application-language-choice-status { grid-column: 1 / -1; color: var(--text-secondary); font-size: 0.72rem; }
+.application-language-boundary { padding: 0.8rem 0.9rem; border-inline-start: 3px solid var(--primary-color); background: var(--surface-soft); }
+@media (max-width: 640px) { .application-language-settings-header { flex-direction: column; } .application-language-current { width: 100%; } }
+
+.setup-top-utility { display: flex; align-items: center; justify-content: flex-end; gap: 0.75rem; width: min(100%, 1180px); margin: 0 auto 0.85rem; color: var(--text-muted); font-size: 0.72rem; }
+.setup-top-utility-action { display: inline-flex; align-items: center; gap: 0.45rem; padding: 0.5rem 0.7rem; border: 1px solid var(--border-color); border-radius: var(--radius-sm); background: var(--surface-white); color: var(--text-secondary); cursor: pointer; font: inherit; font-weight: 700; }
+.setup-top-utility-action:hover { border-color: var(--primary-color); color: var(--primary-color); }
+.setup-application-settings { width: min(100%, 1180px); margin: 0 auto 1rem; }
+
 .page-tap-nav {
   display: flex;
   flex-direction: row;
diff --git a/frontend/app/setup/components/OrganizationArchitectureWorkspace.tsx b/frontend/app/setup/components/OrganizationArchitectureWorkspace.tsx
index 5d2abb24..9df34c3d 100644
--- a/frontend/app/setup/components/OrganizationArchitectureWorkspace.tsx
+++ b/frontend/app/setup/components/OrganizationArchitectureWorkspace.tsx
@@ -1,8 +1,9 @@
 import { Button, SearchableSelect } from "@/components/ui";
 import { fetchAPI } from "@/lib/api";
 import { API_ENDPOINTS } from "@/lib/endpoints";
-import { catalogText, type CatalogKey, useI18n } from "@/lib/i18n";
+import { catalogText, getLocaleRegistry, type CatalogKey, useI18n } from "@/lib/i18n";
 import { getIcon } from "@/lib/icons";
+import { getTextDirection } from "@/lib/utils";
 import { useEffect, useMemo, useState } from "react";
 import { OrganizationIntegrity, OrganizationMetaType, OrganizationNodeDraft, OrganizationTopologyRule, OrganizationWorkspaceNode, OrganizationWorkspacePhase } from "./organizationWorkspace.types";
 
@@ -77,6 +78,13 @@ const ATTRIBUTE_LABEL_KEYS: Readonly<Record<string, CatalogKey>> = {
   valuation_grouping: "enterpriseCore.orgWorkspace.attribute.valuationGrouping",
 };
 
+const CALENDAR_YEAR_VARIANT = "K4";
+const SUPPORTED_LANGUAGE_OPTIONS = Object.values(getLocaleRegistry()).map((item) => ({
+  value: item.code,
+  label: item.nativeName,
+  subtitle: item.displayName,
+}));
+
 function readableAttributeFallback(attributeKey: string): string {
   return attributeKey
     .split("_")
@@ -144,6 +152,7 @@ export function OrganizationArchitectureWorkspace({
   };
 
   const inputTypeForAttribute = (attributeType?: string) => attributeType === "integer" ? "number" : "text";
+  const defaultTextDirection = locale === "ar-SA" ? "rtl" : "ltr";
 
   const domainForType = (typeId: string) => metaTypes.find((item) => item.id === typeId)?.level_domain || "";
   const selectedType = metaTypes.find((item) => item.id === selectedTypeId);
@@ -472,11 +481,11 @@ export function OrganizationArchitectureWorkspace({
             <div className="settings-form-grid setup-form-grid">
               <label className="form-group" htmlFor="org-workspace-code">
                 <span>{i18n.catalog["enterpriseCore.orgWorkspace.composer.code"]}</span>
-                <input id="org-workspace-code" className="setup-input" value={nodeCode} onChange={(event) => setNodeCode(event.target.value)} required />
+                <input id="org-workspace-code" className="setup-input" dir="ltr" value={nodeCode} onChange={(event) => setNodeCode(event.target.value)} required />
               </label>
               <label className="form-group" htmlFor="org-workspace-name">
                 <span>{i18n.catalog["enterpriseCore.orgWorkspace.composer.name"]}</span>
-                <input id="org-workspace-name" className="setup-input" value={nodeNameValue} onChange={(event) => setNodeNameValue(event.target.value)} />
+                <input id="org-workspace-name" className="setup-input" dir={getTextDirection(nodeNameValue, defaultTextDirection)} value={nodeNameValue} onChange={(event) => setNodeNameValue(event.target.value)} />
               </label>
               {validParentNodes.length ? (
                 <label className="form-group" htmlFor="org-workspace-parent">
@@ -516,12 +525,47 @@ export function OrganizationArchitectureWorkspace({
                           {referenceHelpForAttribute(referenceKey, hasReferenceOptions)}
                         </small>
                       </>
+                    ) : attribute.attribute_key === "fiscal_year_variant" ? (
+                      <>
+                        <select
+                          id={attribute.attribute_key}
+                          className="setup-input"
+                          value={attributes[attribute.attribute_key] || ""}
+                          required={attribute.is_mandatory}
+                          onChange={(event) => setAttributes((current) => ({ ...current, [attribute.attribute_key]: event.target.value }))}
+                        >
+                          <option value="">{i18n.catalog["enterpriseCore.orgWorkspace.fiscalYearVariant.placeholder"]}</option>
+                          <option value={CALENDAR_YEAR_VARIANT}>{i18n.catalog["enterpriseCore.orgWorkspace.fiscalYearVariant.calendarYear"]}</option>
+                        </select>
+                        <small className="org-workspace-reference-help">
+                          {i18n.catalog["enterpriseCore.orgWorkspace.fiscalYearVariant.help"]}
+                        </small>
+                      </>
+                    ) : attribute.attribute_key === "language" || attribute.attribute_key === "default_language" ? (
+                      <>
+                        <select
+                          id={attribute.attribute_key}
+                          className="setup-input"
+                          value={attributes[attribute.attribute_key] || ""}
+                          required={attribute.is_mandatory}
+                          onChange={(event) => setAttributes((current) => ({ ...current, [attribute.attribute_key]: event.target.value }))}
+                        >
+                          <option value="">{i18n.catalog["enterpriseCore.orgWorkspace.companyLanguage.placeholder"]}</option>
+                          {SUPPORTED_LANGUAGE_OPTIONS.map((option) => (
+                            <option key={option.value} value={option.value}>{option.label} — {option.subtitle}</option>
+                          ))}
+                        </select>
+                        <small className="org-workspace-reference-help">
+                          {i18n.catalog["enterpriseCore.orgWorkspace.companyLanguage.help"]}
+                        </small>
+                      </>
                     ) : (
                       <input
                         id={attribute.attribute_key}
                         className="setup-input"
                         type={inputTypeForAttribute(attribute.attribute_type)}
                         value={attributes[attribute.attribute_key] || ""}
+                        dir={attribute.attribute_type === "integer" ? "ltr" : getTextDirection(attributes[attribute.attribute_key] || "", defaultTextDirection)}
                         required={attribute.is_mandatory}
                         onChange={(event) => setAttributes((current) => ({ ...current, [attribute.attribute_key]: event.target.value }))}
                       />
diff --git a/frontend/app/setup/components/SetupAccountingSection.tsx b/frontend/app/setup/components/SetupAccountingSection.tsx
index 2a9e53dd..8b66fd8f 100644
--- a/frontend/app/setup/components/SetupAccountingSection.tsx
+++ b/frontend/app/setup/components/SetupAccountingSection.tsx
@@ -1,4 +1,5 @@
 import { Button } from "@/components/ui";
+import { getTextDirection } from "@/lib/utils";
 import { SetupField } from "./SetupField";
 import { SetupSection } from "./SetupSection";
 
@@ -69,10 +70,10 @@ export function SetupAccountingSection({
     <SetupSection id="setup-accounting" title={title} description={description}>
       <div className="settings-form-grid setup-form-grid">
         <SetupField id="setup-account-code" label={accountCodeLabel} required>
-          <input id="setup-account-code" className="setup-input" value={accountCode} onChange={(event) => onAccountCodeChange(event.target.value)} required />
+          <input id="setup-account-code" className="setup-input" dir="ltr" value={accountCode} onChange={(event) => onAccountCodeChange(event.target.value)} required />
         </SetupField>
         <SetupField id="setup-account-name" label={accountNameLabel} required>
-          <input id="setup-account-name" className="setup-input" value={accountName} onChange={(event) => onAccountNameChange(event.target.value)} required />
+          <input id="setup-account-name" className="setup-input" dir={getTextDirection(accountName, "rtl")} value={accountName} onChange={(event) => onAccountNameChange(event.target.value)} required />
         </SetupField>
         <SetupField id="setup-account-type" label={accountTypeLabel}>
           <select id="setup-account-type" className="setup-input" value={accountType} onChange={(event) => onAccountTypeChange(event.target.value as AccountType)}>
@@ -85,7 +86,7 @@ export function SetupAccountingSection({
       </div>
       <div className="settings-form-grid setup-form-grid">
         <SetupField id="setup-period-name" label={periodNameLabel} required>
-          <input id="setup-period-name" className="setup-input" value={periodName} onChange={(event) => onPeriodNameChange(event.target.value)} required />
+          <input id="setup-period-name" className="setup-input" dir={getTextDirection(periodName, "rtl")} value={periodName} onChange={(event) => onPeriodNameChange(event.target.value)} required />
         </SetupField>
         <SetupField id="setup-period-start" label={startDateLabel} required>
           <input id="setup-period-start" className="setup-input" type="date" value={periodStart} onChange={(event) => onPeriodStartChange(event.target.value)} required />
diff --git a/frontend/app/setup/components/SetupOperatingScopeSection.tsx b/frontend/app/setup/components/SetupOperatingScopeSection.tsx
index dc1cf04a..5724fede 100644
--- a/frontend/app/setup/components/SetupOperatingScopeSection.tsx
+++ b/frontend/app/setup/components/SetupOperatingScopeSection.tsx
@@ -1,4 +1,5 @@
 import { Button, SearchableSelect } from "@/components/ui";
+import { getTextDirection } from "@/lib/utils";
 import { SelectOption } from "../types";
 import { SetupField } from "./SetupField";
 import { SetupSection } from "./SetupSection";
@@ -85,16 +86,16 @@ export function SetupOperatingScopeSection({
           <SearchableSelect id="setup-profit-center" className="setup-select" options={profitOptions} value={profitCenterId} onChange={(value) => onProfitCenterChange(typeof value === "number" ? value : null)} />
         </SetupField>
         <SetupField id="setup-warehouse-code" label={warehouseCodeLabel} required>
-          <input id="setup-warehouse-code" className="setup-input" value={warehouseCode} onChange={(event) => onWarehouseCodeChange(event.target.value)} required />
+          <input id="setup-warehouse-code" className="setup-input" dir="ltr" value={warehouseCode} onChange={(event) => onWarehouseCodeChange(event.target.value)} required />
         </SetupField>
         <SetupField id="setup-warehouse-name" label={warehouseNameLabel} required>
-          <input id="setup-warehouse-name" className="setup-input" value={warehouseName} onChange={(event) => onWarehouseNameChange(event.target.value)} required />
+          <input id="setup-warehouse-name" className="setup-input" dir={getTextDirection(warehouseName, "rtl")} value={warehouseName} onChange={(event) => onWarehouseNameChange(event.target.value)} required />
         </SetupField>
         <SetupField id="setup-pos-code" label={posCodeLabel} required>
-          <input id="setup-pos-code" className="setup-input" value={posCode} onChange={(event) => onPosCodeChange(event.target.value)} required />
+          <input id="setup-pos-code" className="setup-input" dir="ltr" value={posCode} onChange={(event) => onPosCodeChange(event.target.value)} required />
         </SetupField>
         <SetupField id="setup-pos-name" label={posNameLabel} required>
-          <input id="setup-pos-name" className="setup-input" value={posName} onChange={(event) => onPosNameChange(event.target.value)} required />
+          <input id="setup-pos-name" className="setup-input" dir={getTextDirection(posName, "rtl")} value={posName} onChange={(event) => onPosNameChange(event.target.value)} required />
         </SetupField>
       </fieldset>
       <div className="setup-actions">
diff --git a/frontend/app/setup/layout.tsx b/frontend/app/setup/layout.tsx
index 28324b74..26a11feb 100644
--- a/frontend/app/setup/layout.tsx
+++ b/frontend/app/setup/layout.tsx
@@ -8,6 +8,8 @@ import { API_ENDPOINTS } from "@/lib/endpoints";
 import { initSystemSettings } from "@/lib/settings";
 import { useAuthStore } from "@/stores/useAuthStore";
 import { useOperatingContextStore } from "@/stores/useOperatingContextStore";
+import { ApplicationLanguageSettingsTab } from "@/app/01-enterprise-core/identity-access/user-management/system-settings/components/ApplicationLanguageSettingsTab";
+import { getIcon } from "@/lib/icons";
 
 interface SetupLayoutProps {
   children: ReactNode;
@@ -24,6 +26,7 @@ export default function SetupLayout({ children }: SetupLayoutProps) {
   const { checkAuth, sessionExpired } = useAuthStore();
   const { loadReadiness } = useOperatingContextStore();
   const [isVerifying, setIsVerifying] = useState(true);
+  const [isApplicationSettingsOpen, setIsApplicationSettingsOpen] = useState(false);
 
   useEffect(() => {
     const verifySetupAccess = async () => {
@@ -63,5 +66,27 @@ export default function SetupLayout({ children }: SetupLayoutProps) {
     );
   }
 
-  return <main className="setup-shell animate-fade">{children}</main>;
+  return (
+    <main className="setup-shell animate-fade">
+      <header className="setup-top-utility">
+        <span>{i18n.catalog["enterpriseCore.systemSettings.applicationLanguage"]}</span>
+        <button
+          type="button"
+          className="setup-top-utility-action"
+          aria-expanded={isApplicationSettingsOpen}
+          aria-controls="setup-application-settings"
+          onClick={() => setIsApplicationSettingsOpen((current) => !current)}
+        >
+          {getIcon("settings")}
+          {i18n.catalog["components.globalmeta.settings"]}
+        </button>
+      </header>
+      {isApplicationSettingsOpen ? (
+        <div id="setup-application-settings" className="setup-application-settings">
+          <ApplicationLanguageSettingsTab />
+        </div>
+      ) : null}
+      {children}
+    </main>
+  );
 }
diff --git a/frontend/app/setup/page.tsx b/frontend/app/setup/page.tsx
index a743947c..2392e4f2 100644
--- a/frontend/app/setup/page.tsx
+++ b/frontend/app/setup/page.tsx
@@ -18,6 +18,7 @@ import { Item, Readiness, SetupState } from "./types";
 const accountTypes = ["asset", "liability", "equity", "revenue", "expense"] as const;
 type AccountType = (typeof accountTypes)[number];
 const recordFields = { code: "code", name: "name" } as const;
+const PRIMARY_GENERAL_LEDGER_REFERENCE = "ACCORE-PRIMARY-GL";
 
 function listFrom(response: unknown): Item[] {
   const payload = (response as { data?: unknown } | undefined)?.data;
@@ -138,17 +139,22 @@ export default function SetupPage() {
       label: [text(currency, "code"), text(currency, "name")].filter(Boolean).join(" — "),
       subtitle: text(currency, "symbol"),
     })),
-    chart_of_accounts_id: accounts.map((account) => ({
-      value: Number(account.id),
-      label: [text(account, "account_code"), text(account, "account_name")].filter(Boolean).join(" — "),
-      subtitle: text(account, "account_type"),
-    })),
+    chart_of_accounts_id: (() => {
+      const activeTypes = new Set(accounts.map((account) => text(account, "account_type").toLowerCase()));
+      const hasGovernedLedger = accountTypes.every((type) => activeTypes.has(type));
+      if (!hasGovernedLedger) return [];
+      return [{
+        value: PRIMARY_GENERAL_LEDGER_REFERENCE,
+        label: i18n.catalog["enterpriseCore.orgWorkspace.reference.chartOfAccounts.primary"],
+        subtitle: catalogText(i18n, "enterpriseCore.orgWorkspace.reference.chartOfAccounts.summary", { value0: accounts.length, value1: activeTypes.size }),
+      }];
+    })(),
     factory_calendar_id: factoryCalendars.map((calendar) => ({
       value: Number(calendar.id),
       label: [text(calendar, "code"), text(calendar, locale === "ar-SA" ? "name_ar" : "name")].filter(Boolean).join(" — "),
       subtitle: [text(calendar, "country_code"), text(calendar, "time_zone")].filter(Boolean).join(" · "),
     })),
-  }), [accounts, currencies, factoryCalendars, locale]);
+  }), [accounts, currencies, factoryCalendars, i18n, locale]);
 
   const callAndReload = async <T,>(action: () => Promise<{ success?: boolean; message?: string; data?: T }>): Promise<T | null> => {
     setIsSaving(true);
diff --git a/frontend/components/navigation/TopGlobalBar/components/GlobalMeta.tsx b/frontend/components/navigation/TopGlobalBar/components/GlobalMeta.tsx
index 8e596371..0649dcc6 100644
--- a/frontend/components/navigation/TopGlobalBar/components/GlobalMeta.tsx
+++ b/frontend/components/navigation/TopGlobalBar/components/GlobalMeta.tsx
@@ -4,6 +4,7 @@ import { useI18n } from "@/lib/i18n";
 import { useEffect, useState } from "react";
 import { getIcon } from "@/lib/icons";
 import { useAuthStore } from "@/stores/useAuthStore";
+import { useRouter } from "next/navigation";
 
 function formatElapsed(seconds: number): string {
     const hrs = Math.floor(seconds / 3600)
@@ -21,6 +22,7 @@ function formatElapsed(seconds: number): string {
 export function GlobalMeta() {
     const { t: i18n } = useI18n();
     const { user } = useAuthStore();
+    const router = useRouter();
 
     const [elapsedSeconds, setElapsedSeconds] = useState(0);
     const [now, setNow] = useState<Date | null>(null);
@@ -60,6 +62,7 @@ export function GlobalMeta() {
                     type="button"
                     className="top-global-icon-btn"
                     aria-label={i18n.catalog["components.globalmeta.settings"]}
+                    onClick={() => router.push("/01-enterprise-core/identity-access/user-management/system-settings")}
                 >
                     {getIcon("settings")}
                 </button>
@@ -92,4 +95,3 @@ export function GlobalMeta() {
         </div>
     );
 }
-
diff --git a/frontend/components/ui/SearchableSelect.tsx b/frontend/components/ui/SearchableSelect.tsx
index dbd5718c..dca3a95d 100644
--- a/frontend/components/ui/SearchableSelect.tsx
+++ b/frontend/components/ui/SearchableSelect.tsx
@@ -3,7 +3,7 @@
 import { useI18n, catalogMessage } from "@/lib/i18n";
 import { useState, useRef, useEffect, useCallback } from "react";
 import { Icon } from "@/lib/icons";
-import { isArabic as checkIsArabic } from "@/lib/utils";
+import { getTextDirection } from "@/lib/utils";
 
 export interface SelectOption {
     value: string | number;
@@ -59,7 +59,6 @@ export function SearchableSelect({
     const [isOpen, setIsOpen] = useState(false);
     const [searchTerm, setSearchTerm] = useState("");
     const [inputValue, setInputValue] = useState("");
-    const [isArabic, setIsArabic] = useState(false);
     const containerRef = useRef<HTMLDivElement>(null);
     const internalRef = useRef<HTMLInputElement>(null);
     const inputRef = externalRef ?? internalRef;
@@ -77,12 +76,6 @@ export function SearchableSelect({
         ? options.find((opt) => opt.value === value)
         : null;
 
-    // Detect text direction
-    useEffect(() => {
-        const displayValue = isOpen ? searchTerm : inputValue;
-        setIsArabic(checkIsArabic(displayValue));
-    }, [isOpen, searchTerm, inputValue]);
-
     // Update input value when selection changes
     useEffect(() => {
         if (selectedOption) {
@@ -194,6 +187,8 @@ export function SearchableSelect({
 
     // Should only display dropdown when search term is not empty and dropdown is open
     const isDropdownVisible = isOpen && searchTerm.trim().length > 0;
+    const displayValue = isOpen ? searchTerm : inputValue;
+    const textDirection = getTextDirection(displayValue);
 
     return (
         <div className={`searchable-select ${className}`} ref={containerRef}>
@@ -213,8 +208,8 @@ export function SearchableSelect({
                 style={{
                     paddingTop: paddingVertical ? (paddingVertical + "rem") : undefined,
                     paddingBottom: paddingVertical ? (paddingVertical + "rem") : undefined,
-                    direction: isArabic ? "rtl" : "ltr",
-                    textAlign: isArabic ? "right" : "left",
+                    direction: textDirection,
+                    textAlign: textDirection === "rtl" ? "right" : "left",
                     paddingLeft: "3rem",
                     paddingRight: (value && !isOpen) ? "2.5rem" : "1rem"
                 }}
@@ -261,4 +256,3 @@ export function SearchableSelect({
     );
 }
 
-
diff --git a/frontend/i18n/catalog/en-US.json b/frontend/i18n/catalog/en-US.json
index e8f79ea9..cee623d1 100644
--- a/frontend/i18n/catalog/en-US.json
+++ b/frontend/i18n/catalog/en-US.json
@@ -1812,6 +1812,14 @@
     "enterpriseCore.storesettings.storeName": "Store name",
     "enterpriseCore.storesettings.storeSettingsSaved": "Store settings saved",
     "enterpriseCore.systemSettings.accountSecurity": "Account and security",
+    "enterpriseCore.systemSettings.activeLanguage": "Active interface language",
+    "enterpriseCore.systemSettings.applicationLanguage": "Application language",
+    "enterpriseCore.systemSettings.applicationLanguageBoundary": "This choice changes the application interface, formatting, and layout direction on this device. It does not change the operating or master-data language assigned to a client or company code.",
+    "enterpriseCore.systemSettings.applicationLanguageDescription": "Select the language used by ACCORE menus, messages, and layout on this desktop. Only languages currently maintained in the product are shown.",
+    "enterpriseCore.systemSettings.applicationLanguageTitle": "Interface language",
+    "enterpriseCore.systemSettings.availableLanguages": "Available interface languages",
+    "enterpriseCore.systemSettings.currentLanguage": "Current language",
+    "enterpriseCore.systemSettings.useLanguage": "Use {value0}",
     "enterpriseCore.topologyrules.based": "Based on",
     "enterpriseCore.topologyrules.errorLoadingRules": "Error loading rules",
     "enterpriseCore.topologyrules.linkingRulesTopologyRules": "Linking Rules (Topology Rules)",
@@ -4045,8 +4053,17 @@
     "enterpriseCore.setup.modules.active": "Operational",
     "enterpriseCore.setup.modules.selectionRequired": "Select at least one business module before leaving setup.",
     "enterpriseCore.setup.accounting.recordSummary": "{value0} accounts and {value1} fiscal periods configured",
-    "enterpriseCore.orgWorkspace.reference.chartOfAccounts.empty": "No active accounts exist yet. Create the required accounts in the chart of accounts, then return to complete this unit.",
-    "enterpriseCore.orgWorkspace.reference.chartOfAccounts.help": "Select an existing reference from the chart of accounts; the list shows each account code, name, and type for a clear choice.",
+    "enterpriseCore.orgWorkspace.reference.chartOfAccounts.empty": "The primary general ledger is not ready. Create active accounts for assets, liabilities, equity, revenue, and expenses, then return to assign the governed ledger structure.",
+    "enterpriseCore.orgWorkspace.reference.chartOfAccounts.help": "Assign the governed general-ledger structure available to this company code. This is not a choice of one posting account such as Assets, Cash, or Revenue.",
+    "enterpriseCore.orgWorkspace.reference.chartOfAccounts.primary": "ACCORE primary general ledger",
+    "enterpriseCore.orgWorkspace.reference.chartOfAccounts.summary": "{value0} active accounts · {value1} account classes",
+    "enterpriseCore.orgWorkspace.attribute.chartOfAccountsId": "General ledger structure",
+    "enterpriseCore.orgWorkspace.attribute.fiscalYearVariant": "Fiscal year structure",
+    "enterpriseCore.orgWorkspace.fiscalYearVariant.calendarYear": "Calendar year (K4) — January to December",
+    "enterpriseCore.orgWorkspace.fiscalYearVariant.help": "Defines the period pattern used by this company code. K4 uses twelve calendar-month posting periods; period opening and closing remain controlled separately.",
+    "enterpriseCore.orgWorkspace.fiscalYearVariant.placeholder": "Select the fiscal year structure",
+    "enterpriseCore.orgWorkspace.companyLanguage.help": "Controls the operating and master-data language for this organizational unit. It does not change the current user's application interface language.",
+    "enterpriseCore.orgWorkspace.companyLanguage.placeholder": "Select the operating language",
     "enterpriseCore.orgWorkspace.reference.currency.empty": "No active currency exists yet. Define the required currency in Currency Management, then return to complete this unit.",
     "enterpriseCore.orgWorkspace.reference.currency.help": "Only active currencies defined in Currency Management are offered; no default currency list is used.",
     "enterpriseCore.orgWorkspace.reference.factoryCalendar.empty": "No active factory calendar exists yet. Define an approved operating calendar, then return to complete this plant.",
diff --git a/frontend/i18n/catalog/source.json b/frontend/i18n/catalog/source.json
index eeb08de0..37d552e0 100644
--- a/frontend/i18n/catalog/source.json
+++ b/frontend/i18n/catalog/source.json
@@ -58450,6 +58450,54 @@
         }
       ]
     },
+    {
+      "id": "enterpriseCore.systemSettings.activeLanguage",
+      "source": "لغة الواجهة المفعّلة",
+      "classification": "user-facing",
+      "occurrences": []
+    },
+    {
+      "id": "enterpriseCore.systemSettings.applicationLanguage",
+      "source": "لغة التطبيق",
+      "classification": "user-facing",
+      "occurrences": []
+    },
+    {
+      "id": "enterpriseCore.systemSettings.applicationLanguageBoundary",
+      "source": "يغيّر هذا الاختيار واجهة التطبيق وتنسيقاته واتجاهه على هذا الجهاز. ولا يغيّر لغة التشغيل أو لغة البيانات الرئيسية المعينة للعميل أو رمز الشركة.",
+      "classification": "user-facing",
+      "occurrences": []
+    },
+    {
+      "id": "enterpriseCore.systemSettings.applicationLanguageDescription",
+      "source": "اختر اللغة التي تظهر بها قوائم ورسائل وتخطيط أكور على هذا الجهاز. لا تظهر إلا اللغات المهيأة فعلياً في المنتج.",
+      "classification": "user-facing",
+      "occurrences": []
+    },
+    {
+      "id": "enterpriseCore.systemSettings.applicationLanguageTitle",
+      "source": "لغة الواجهة",
+      "classification": "user-facing",
+      "occurrences": []
+    },
+    {
+      "id": "enterpriseCore.systemSettings.availableLanguages",
+      "source": "لغات الواجهة المتاحة",
+      "classification": "user-facing",
+      "occurrences": []
+    },
+    {
+      "id": "enterpriseCore.systemSettings.currentLanguage",
+      "source": "اللغة الحالية",
+      "classification": "user-facing",
+      "occurrences": []
+    },
+    {
+      "id": "enterpriseCore.systemSettings.useLanguage",
+      "source": "استخدم {value0}",
+      "classification": "user-facing",
+      "occurrences": []
+    },
     {
       "id": "enterpriseCore.topologyrules.based",
       "source": "قاعدة من",
@@ -90978,13 +91026,67 @@
     },
     {
       "id": "enterpriseCore.orgWorkspace.reference.chartOfAccounts.empty",
-      "source": "لا توجد حسابات نشطة بعد. أنشئ الحسابات في شجرة الحسابات ثم عُد لإكمال هذه الوحدة.",
+      "source": "هيكل دفتر الأستاذ العام الأساسي غير جاهز بعد. أنشئ حسابات نشطة للأصول والالتزامات وحقوق الملكية والإيرادات والمصروفات، ثم عُد لتعيين الهيكل المحكوم.",
       "classification": "user-facing",
       "occurrences": []
     },
     {
       "id": "enterpriseCore.orgWorkspace.reference.chartOfAccounts.help",
-      "source": "اختر مرجعًا قائمًا من شجرة الحسابات؛ تعرض القائمة رمز الحساب واسمه ونوعه لتوضيح الاختيار.",
+      "source": "عيّن هيكل دفتر الأستاذ العام المحكوم المتاح لرمز الشركة. لا يمثل هذا اختيار حساب ترحيل مفرد مثل الأصول أو النقد أو الإيراد.",
+      "classification": "user-facing",
+      "occurrences": []
+    },
+    {
+      "id": "enterpriseCore.orgWorkspace.reference.chartOfAccounts.primary",
+      "source": "دفتر الأستاذ العام الأساسي لأكور",
+      "classification": "user-facing",
+      "occurrences": []
+    },
+    {
+      "id": "enterpriseCore.orgWorkspace.reference.chartOfAccounts.summary",
+      "source": "{value0} حسابات نشطة · {value1} فئات حسابات",
+      "classification": "user-facing",
+      "occurrences": []
+    },
+    {
+      "id": "enterpriseCore.orgWorkspace.attribute.chartOfAccountsId",
+      "source": "هيكل دفتر الأستاذ العام",
+      "classification": "user-facing",
+      "occurrences": []
+    },
+    {
+      "id": "enterpriseCore.orgWorkspace.attribute.fiscalYearVariant",
+      "source": "هيكل السنة المالية",
+      "classification": "user-facing",
+      "occurrences": []
+    },
+    {
+      "id": "enterpriseCore.orgWorkspace.fiscalYearVariant.calendarYear",
+      "source": "السنة التقويمية (K4) — من يناير إلى ديسمبر",
+      "classification": "user-facing",
+      "occurrences": []
+    },
+    {
+      "id": "enterpriseCore.orgWorkspace.fiscalYearVariant.help",
+      "source": "يعرّف نمط الفترات المستخدم لرمز الشركة. يستخدم K4 اثنتي عشرة فترة ترحيل شهرية تقويمية، بينما يبقى فتح الفترات وإغلاقها تحت تحكم مستقل.",
+      "classification": "user-facing",
+      "occurrences": []
+    },
+    {
+      "id": "enterpriseCore.orgWorkspace.fiscalYearVariant.placeholder",
+      "source": "اختر هيكل السنة المالية",
+      "classification": "user-facing",
+      "occurrences": []
+    },
+    {
+      "id": "enterpriseCore.orgWorkspace.companyLanguage.help",
+      "source": "تتحكم في لغة التشغيل والبيانات الرئيسية لهذه الوحدة التنظيمية. ولا تغيّر لغة واجهة التطبيق للمستخدم الحالي.",
+      "classification": "user-facing",
+      "occurrences": []
+    },
+    {
+      "id": "enterpriseCore.orgWorkspace.companyLanguage.placeholder",
+      "source": "اختر لغة التشغيل",
       "classification": "user-facing",
       "occurrences": []
     },
diff --git a/frontend/lib/i18n/catalog/ar-SA.ts b/frontend/lib/i18n/catalog/ar-SA.ts
index 0e39a5b2..a53ff4f2 100644
--- a/frontend/lib/i18n/catalog/ar-SA.ts
+++ b/frontend/lib/i18n/catalog/ar-SA.ts
@@ -1811,6 +1811,14 @@ export const arCatalog = {
     "enterpriseCore.storesettings.storeName": "اسم المتجر",
     "enterpriseCore.storesettings.storeSettingsSaved": "تم حفظ إعدادات المتجر",
     "enterpriseCore.systemSettings.accountSecurity": "الحساب والأمان",
+    "enterpriseCore.systemSettings.activeLanguage": "لغة الواجهة المفعّلة",
+    "enterpriseCore.systemSettings.applicationLanguage": "لغة التطبيق",
+    "enterpriseCore.systemSettings.applicationLanguageBoundary": "يغيّر هذا الاختيار واجهة التطبيق وتنسيقاته واتجاهه على هذا الجهاز. ولا يغيّر لغة التشغيل أو لغة البيانات الرئيسية المعينة للعميل أو رمز الشركة.",
+    "enterpriseCore.systemSettings.applicationLanguageDescription": "اختر اللغة التي تظهر بها قوائم ورسائل وتخطيط أكور على هذا الجهاز. لا تظهر إلا اللغات المهيأة فعلياً في المنتج.",
+    "enterpriseCore.systemSettings.applicationLanguageTitle": "لغة الواجهة",
+    "enterpriseCore.systemSettings.availableLanguages": "لغات الواجهة المتاحة",
+    "enterpriseCore.systemSettings.currentLanguage": "اللغة الحالية",
+    "enterpriseCore.systemSettings.useLanguage": "استخدم {value0}",
     "enterpriseCore.topologyrules.based": "قاعدة من",
     "enterpriseCore.topologyrules.errorLoadingRules": "خطأ في تحميل القواعد",
     "enterpriseCore.topologyrules.linkingRulesTopologyRules": "قواعد الارتباط (Topology Rules)",
@@ -4182,13 +4190,15 @@ export const arCatalog = {
     "enterpriseCore.orgWorkspace.composer.selectType": "اختر نوع وحدة لفتح نموذج إعدادها المحكوم.",
     "enterpriseCore.orgWorkspace.attribute.address": "عنوان المنشأة",
     "enterpriseCore.orgWorkspace.attribute.buyerName": "جهة اتصال المشتريات",
-    "enterpriseCore.orgWorkspace.attribute.chartOfAccountsId": "دليل الحسابات",
+    "enterpriseCore.orgWorkspace.attribute.chartOfAccountsId": "هيكل دفتر الأستاذ العام",
     "enterpriseCore.orgWorkspace.attribute.city": "المدينة",
     "enterpriseCore.orgWorkspace.attribute.costCenterCategory": "فئة مركز التكلفة",
     "enterpriseCore.orgWorkspace.attribute.countryCode": "رمز الدولة أو الإقليم",
     "enterpriseCore.orgWorkspace.attribute.currencyId": "العملة الوظيفية",
-    "enterpriseCore.orgWorkspace.reference.chartOfAccounts.empty": "لا توجد حسابات نشطة بعد. أنشئ الحسابات في شجرة الحسابات ثم عُد لإكمال هذه الوحدة.",
-    "enterpriseCore.orgWorkspace.reference.chartOfAccounts.help": "اختر مرجعًا قائمًا من شجرة الحسابات؛ تعرض القائمة رمز الحساب واسمه ونوعه لتوضيح الاختيار.",
+    "enterpriseCore.orgWorkspace.reference.chartOfAccounts.empty": "هيكل دفتر الأستاذ العام الأساسي غير جاهز بعد. أنشئ حسابات نشطة للأصول والالتزامات وحقوق الملكية والإيرادات والمصروفات، ثم عُد لتعيين الهيكل المحكوم.",
+    "enterpriseCore.orgWorkspace.reference.chartOfAccounts.help": "عيّن هيكل دفتر الأستاذ العام المحكوم المتاح لرمز الشركة. لا يمثل هذا اختيار حساب ترحيل مفرد مثل الأصول أو النقد أو الإيراد.",
+    "enterpriseCore.orgWorkspace.reference.chartOfAccounts.primary": "دفتر الأستاذ العام الأساسي لأكور",
+    "enterpriseCore.orgWorkspace.reference.chartOfAccounts.summary": "{value0} حسابات نشطة · {value1} فئات حسابات",
     "enterpriseCore.orgWorkspace.reference.currency.empty": "لا توجد عملة نشطة بعد. عرّف العملة المطلوبة من إدارة العملات ثم عُد لإكمال هذه الوحدة.",
     "enterpriseCore.orgWorkspace.reference.currency.help": "تُعرض العملات النشطة المعرّفة في إدارة العملات فقط؛ لا يستخدم النظام قائمة عملات افتراضية.",
     "enterpriseCore.orgWorkspace.reference.factoryCalendar.empty": "لا توجد تقاويم مصنع نشطة بعد. عرّف تقويم تشغيل معتمدًا ثم عُد لإكمال هذه المنشأة.",
@@ -4198,7 +4208,12 @@ export const arCatalog = {
     "enterpriseCore.orgWorkspace.reference.placeholder": "ابحث واختر من السجل",
     "enterpriseCore.orgWorkspace.attribute.defaultLanguage": "اللغة الافتراضية",
     "enterpriseCore.orgWorkspace.attribute.factoryCalendarId": "تقويم المصنع",
-    "enterpriseCore.orgWorkspace.attribute.fiscalYearVariant": "نموذج السنة المالية",
+    "enterpriseCore.orgWorkspace.attribute.fiscalYearVariant": "هيكل السنة المالية",
+    "enterpriseCore.orgWorkspace.fiscalYearVariant.calendarYear": "السنة التقويمية (K4) — من يناير إلى ديسمبر",
+    "enterpriseCore.orgWorkspace.fiscalYearVariant.help": "يعرّف نمط الفترات المستخدم لرمز الشركة. يستخدم K4 اثنتي عشرة فترة ترحيل شهرية تقويمية، بينما يبقى فتح الفترات وإغلاقها تحت تحكم مستقل.",
+    "enterpriseCore.orgWorkspace.fiscalYearVariant.placeholder": "اختر هيكل السنة المالية",
+    "enterpriseCore.orgWorkspace.companyLanguage.help": "تتحكم في لغة التشغيل والبيانات الرئيسية لهذه الوحدة التنظيمية. ولا تغيّر لغة واجهة التطبيق للمستخدم الحالي.",
+    "enterpriseCore.orgWorkspace.companyLanguage.placeholder": "اختر لغة التشغيل",
     "enterpriseCore.orgWorkspace.attribute.headcount": "القوى العاملة المخططة",
     "enterpriseCore.orgWorkspace.attribute.jobFamily": "عائلة الوظيفة",
     "enterpriseCore.orgWorkspace.attribute.language": "لغة التشغيل",
diff --git a/frontend/lib/i18n/catalog/en-US.ts b/frontend/lib/i18n/catalog/en-US.ts
index 1bf05740..03217372 100644
--- a/frontend/lib/i18n/catalog/en-US.ts
+++ b/frontend/lib/i18n/catalog/en-US.ts
@@ -1811,6 +1811,14 @@ export const enCatalog = {
     "enterpriseCore.storesettings.storeName": "Store name",
     "enterpriseCore.storesettings.storeSettingsSaved": "Store settings saved",
     "enterpriseCore.systemSettings.accountSecurity": "Account and security",
+    "enterpriseCore.systemSettings.activeLanguage": "Active interface language",
+    "enterpriseCore.systemSettings.applicationLanguage": "Application language",
+    "enterpriseCore.systemSettings.applicationLanguageBoundary": "This choice changes the application interface, formatting, and layout direction on this device. It does not change the operating or master-data language assigned to a client or company code.",
+    "enterpriseCore.systemSettings.applicationLanguageDescription": "Select the language used by ACCORE menus, messages, and layout on this desktop. Only languages currently maintained in the product are shown.",
+    "enterpriseCore.systemSettings.applicationLanguageTitle": "Interface language",
+    "enterpriseCore.systemSettings.availableLanguages": "Available interface languages",
+    "enterpriseCore.systemSettings.currentLanguage": "Current language",
+    "enterpriseCore.systemSettings.useLanguage": "Use {value0}",
     "enterpriseCore.topologyrules.based": "Based on",
     "enterpriseCore.topologyrules.errorLoadingRules": "Error loading rules",
     "enterpriseCore.topologyrules.linkingRulesTopologyRules": "Linking Rules (Topology Rules)",
@@ -4182,13 +4190,15 @@ export const enCatalog = {
     "enterpriseCore.orgWorkspace.composer.selectType": "Choose a unit type to open its governed preparation form.",
     "enterpriseCore.orgWorkspace.attribute.address": "Business address",
     "enterpriseCore.orgWorkspace.attribute.buyerName": "Purchasing contact",
-    "enterpriseCore.orgWorkspace.attribute.chartOfAccountsId": "Chart of accounts",
+    "enterpriseCore.orgWorkspace.attribute.chartOfAccountsId": "General ledger structure",
     "enterpriseCore.orgWorkspace.attribute.city": "City",
     "enterpriseCore.orgWorkspace.attribute.costCenterCategory": "Cost center category",
     "enterpriseCore.orgWorkspace.attribute.countryCode": "Country / region code",
     "enterpriseCore.orgWorkspace.attribute.currencyId": "Functional currency",
-    "enterpriseCore.orgWorkspace.reference.chartOfAccounts.empty": "No active accounts exist yet. Create the required accounts in the chart of accounts, then return to complete this unit.",
-    "enterpriseCore.orgWorkspace.reference.chartOfAccounts.help": "Select an existing reference from the chart of accounts; the list shows each account code, name, and type for a clear choice.",
+    "enterpriseCore.orgWorkspace.reference.chartOfAccounts.empty": "The primary general ledger is not ready. Create active accounts for assets, liabilities, equity, revenue, and expenses, then return to assign the governed ledger structure.",
+    "enterpriseCore.orgWorkspace.reference.chartOfAccounts.help": "Assign the governed general-ledger structure available to this company code. This is not a choice of one posting account such as Assets, Cash, or Revenue.",
+    "enterpriseCore.orgWorkspace.reference.chartOfAccounts.primary": "ACCORE primary general ledger",
+    "enterpriseCore.orgWorkspace.reference.chartOfAccounts.summary": "{value0} active accounts · {value1} account classes",
     "enterpriseCore.orgWorkspace.reference.currency.empty": "No active currency exists yet. Define the required currency in Currency Management, then return to complete this unit.",
     "enterpriseCore.orgWorkspace.reference.currency.help": "Only active currencies defined in Currency Management are offered; no default currency list is used.",
     "enterpriseCore.orgWorkspace.reference.factoryCalendar.empty": "No active factory calendar exists yet. Define an approved operating calendar, then return to complete this plant.",
@@ -4198,7 +4208,12 @@ export const enCatalog = {
     "enterpriseCore.orgWorkspace.reference.placeholder": "Search and select from the register",
     "enterpriseCore.orgWorkspace.attribute.defaultLanguage": "Default language",
     "enterpriseCore.orgWorkspace.attribute.factoryCalendarId": "Factory calendar",
-    "enterpriseCore.orgWorkspace.attribute.fiscalYearVariant": "Fiscal year variant",
+    "enterpriseCore.orgWorkspace.attribute.fiscalYearVariant": "Fiscal year structure",
+    "enterpriseCore.orgWorkspace.fiscalYearVariant.calendarYear": "Calendar year (K4) — January to December",
+    "enterpriseCore.orgWorkspace.fiscalYearVariant.help": "Defines the period pattern used by this company code. K4 uses twelve calendar-month posting periods; period opening and closing remain controlled separately.",
+    "enterpriseCore.orgWorkspace.fiscalYearVariant.placeholder": "Select the fiscal year structure",
+    "enterpriseCore.orgWorkspace.companyLanguage.help": "Controls the operating and master-data language for this organizational unit. It does not change the current user's application interface language.",
+    "enterpriseCore.orgWorkspace.companyLanguage.placeholder": "Select the operating language",
     "enterpriseCore.orgWorkspace.attribute.headcount": "Planned headcount",
     "enterpriseCore.orgWorkspace.attribute.jobFamily": "Job family",
     "enterpriseCore.orgWorkspace.attribute.language": "Operating language",
diff --git a/frontend/lib/utils.ts b/frontend/lib/utils.ts
index 06b5e2ae..365c53cb 100644
--- a/frontend/lib/utils.ts
+++ b/frontend/lib/utils.ts
@@ -360,3 +360,29 @@ export function isArabic(text: string | null | undefined): boolean {
   return arabicPattern.test(text);
 }
 
+export type InputTextDirection = "ltr" | "rtl";
+
+/**
+ * Determines text direction from the first strong Unicode letter.
+ *
+ * Right-to-left scripts (including Arabic, Persian, Hebrew, Syriac, and
+ * Thaana) are rendered RTL. Any other letter begins an LTR run. Digits and
+ * punctuation preserve the supplied fallback so structured values remain
+ * stable while a user starts typing.
+ */
+export function getTextDirection(
+  text: string | null | undefined,
+  fallback: InputTextDirection = "ltr",
+): InputTextDirection {
+  if (!text) return fallback;
+
+  const rtlCharacter = /[\u0590-\u08FF\uFB1D-\uFDFF\uFE70-\uFEFF]/;
+  const letter = /\p{L}/u;
+
+  for (const character of text) {
+    if (rtlCharacter.test(character)) return "rtl";
+    if (letter.test(character)) return "ltr";
+  }
+
+  return fallback;
+}
diff --git a/frontend/tests/app/application-language-settings.test.ts b/frontend/tests/app/application-language-settings.test.ts
new file mode 100644
index 00000000..3731d2e7
--- /dev/null
+++ b/frontend/tests/app/application-language-settings.test.ts
@@ -0,0 +1,35 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const root = path.resolve(__dirname, '../..');
+const source = (relativePath: string) => fs.readFileSync(path.join(root, relativePath), 'utf8');
+
+describe('application language settings', () => {
+  it('exposes the current supported locales through the primary System Settings screen', () => {
+    const page = source(
+      'app/01-enterprise-core/identity-access/user-management/system-settings/(pages)/page.tsx'
+    );
+    const tab = source(
+      'app/01-enterprise-core/identity-access/user-management/system-settings/components/ApplicationLanguageSettingsTab.tsx'
+    );
+
+    expect(page).toContain('key: "language"');
+    expect(page).toContain('<ApplicationLanguageSettingsTab />');
+    expect(tab).toContain('getLocaleRegistry');
+    expect(tab).toContain('setLocale(candidate.code as SupportedLocale)');
+    expect(tab).toContain('applicationLanguageBoundary');
+  });
+
+  it('keeps company-code language distinct from the interface language and links the top-bar settings control', () => {
+    const tab = source(
+      'app/01-enterprise-core/identity-access/user-management/system-settings/components/ApplicationLanguageSettingsTab.tsx'
+    );
+    const globalMeta = source('components/navigation/TopGlobalBar/components/GlobalMeta.tsx');
+
+    expect(tab).toContain('applicationLanguageBoundary');
+    expect(globalMeta).toContain(
+      'router.push("/01-enterprise-core/identity-access/user-management/system-settings")'
+    );
+  });
+});
diff --git a/frontend/tests/app/setup-onboarding.test.ts b/frontend/tests/app/setup-onboarding.test.ts
index 62208e42..56e8bd18 100644
--- a/frontend/tests/app/setup-onboarding.test.ts
+++ b/frontend/tests/app/setup-onboarding.test.ts
@@ -56,13 +56,13 @@ describe("standalone phased setup onboarding", () => {
       /['"]enterpriseCore\.orgWorkspace\.attribute\.countryCode['"]:\s*['"]Country \/ region code['"]/
     );
     expect(englishCatalog).toMatch(
-      /['"]enterpriseCore\.orgWorkspace\.attribute\.fiscalYearVariant['"]:\s*['"]Fiscal year variant['"]/
+      /['"]enterpriseCore\.orgWorkspace\.attribute\.fiscalYearVariant['"]:\s*['"]Fiscal year structure['"]/
     );
     expect(arabicCatalog).toMatch(
       /['"]enterpriseCore\.orgWorkspace\.attribute\.countryCode['"]:\s*['"]رمز الدولة أو الإقليم['"]/
     );
     expect(arabicCatalog).toMatch(
-      /['"]enterpriseCore\.orgWorkspace\.attribute\.fiscalYearVariant['"]:\s*['"]نموذج السنة المالية['"]/
+      /['"]enterpriseCore\.orgWorkspace\.attribute\.fiscalYearVariant['"]:\s*['"]هيكل السنة المالية['"]/
     );
   });
 
@@ -75,12 +75,28 @@ describe("standalone phased setup onboarding", () => {
     expect(page).toContain("FINANCE.FOREIGN_EXCHANGE.CURRENCIES.BASE");
     expect(page).toContain("organizationReferenceOptions");
     expect(page).toContain("currency_id: currencies.map");
-    expect(page).toContain("chart_of_accounts_id: accounts.map");
+    expect(page).toContain("PRIMARY_GENERAL_LEDGER_REFERENCE");
+    expect(page).toContain("setAccounts(listFrom(accountsResponse).filter((item) => item.is_active !== false))");
+    expect(page).toContain("hasGovernedLedger");
     expect(workspace).toContain("referenceOptionsByAttribute");
     expect(workspace).toContain("SearchableSelect");
     expect(workspace).toContain("referenceHelpForAttribute");
     expect(englishCatalog).toContain("Only active currencies defined in Currency Management are offered");
+    expect(englishCatalog).toContain("This is not a choice of one posting account");
     expect(arabicCatalog).toContain("لا يستخدم النظام قائمة عملات افتراضية");
+    expect(arabicCatalog).toContain("لا يمثل هذا اختيار حساب ترحيل مفرد");
+  });
+
+  it("uses a controlled fiscal-year structure rather than an unbounded free-text value", () => {
+    const workspace = source("app/setup/components/OrganizationArchitectureWorkspace.tsx");
+    const englishCatalog = source("lib/i18n/catalog/en-US.ts");
+    const arabicCatalog = source("lib/i18n/catalog/ar-SA.ts");
+
+    expect(workspace).toContain('const CALENDAR_YEAR_VARIANT = "K4"');
+    expect(workspace).toContain('attribute.attribute_key === "fiscal_year_variant"');
+    expect(workspace).toContain("fiscalYearVariant.calendarYear");
+    expect(englishCatalog).toContain("Fiscal year structure");
+    expect(arabicCatalog).toContain("هيكل السنة المالية");
   });
 
   it("loads factory calendars from controlled reference data for plants", () => {
@@ -97,6 +113,20 @@ describe("standalone phased setup onboarding", () => {
     expect(arabicCatalog).toContain("لا يسمح النظام بإدخال رمز تقويم حر");
   });
 
+  it("exposes interface-language settings from the setup shell while keeping company-code language controlled and separate", () => {
+    const layout = source("app/setup/layout.tsx");
+    const workspace = source("app/setup/components/OrganizationArchitectureWorkspace.tsx");
+    const englishCatalog = source("lib/i18n/catalog/en-US.ts");
+    const arabicCatalog = source("lib/i18n/catalog/ar-SA.ts");
+
+    expect(layout).toContain("setup-top-utility");
+    expect(layout).toContain("ApplicationLanguageSettingsTab");
+    expect(workspace).toContain("SUPPORTED_LANGUAGE_OPTIONS");
+    expect(workspace).toContain('attribute.attribute_key === "language"');
+    expect(englishCatalog).toContain("It does not change the current user's application interface language");
+    expect(arabicCatalog).toContain("ولا تغيّر لغة واجهة التطبيق للمستخدم الحالي");
+  });
+
   it("emits setup in the static catch-all parameter set", () => {
     const virtualRoute = source("app/[...virtual]/page.tsx");
 
diff --git a/frontend/tests/lib/input-direction.test.ts b/frontend/tests/lib/input-direction.test.ts
new file mode 100644
index 00000000..eaefa7f0
--- /dev/null
+++ b/frontend/tests/lib/input-direction.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+import { getTextDirection } from '@/lib/utils';
+
+describe('getTextDirection', () => {
+  it('uses the first strong RTL character for Arabic, Persian, and Hebrew input', () => {
+    expect(getTextDirection('شركة أكور')).toBe('rtl');
+    expect(getTextDirection('شرکت اکور')).toBe('rtl');
+    expect(getTextDirection('חברת אקור')).toBe('rtl');
+  });
+
+  it('uses LTR for Latin and other left-to-right alphabets', () => {
+    expect(getTextDirection('ACCORE ERP', 'rtl')).toBe('ltr');
+    expect(getTextDirection('日本語', 'rtl')).toBe('ltr');
+  });
+
+  it('preserves the requested fallback while the input contains only structured characters', () => {
+    expect(getTextDirection('2026-01-01', 'rtl')).toBe('rtl');
+    expect(getTextDirection('1000', 'ltr')).toBe('ltr');
+  });
+});

From c92c0464b98cd69617ff5017dc4c0c79a2df7d03 Mon Sep 17 00:00:00 2001
From: Emran025 <1.48263577e+08+Emran025@users.noreply.github.com>
Date: Sat, 22 Aug 2026 00:02:40 +0000
Subject: [PATCH 3/9] test(setup): tolerate CI formatting in source assertions

---
 frontend/tests/app/application-language-settings.test.ts | 6 +++---
 frontend/tests/app/setup-onboarding.test.ts              | 8 ++++----
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/frontend/tests/app/application-language-settings.test.ts b/frontend/tests/app/application-language-settings.test.ts
index 3731d2e7..9f912a01 100644
--- a/frontend/tests/app/application-language-settings.test.ts
+++ b/frontend/tests/app/application-language-settings.test.ts
@@ -14,7 +14,7 @@ describe('application language settings', () => {
       'app/01-enterprise-core/identity-access/user-management/system-settings/components/ApplicationLanguageSettingsTab.tsx'
     );
 
-    expect(page).toContain('key: "language"');
+    expect(page).toMatch(/key:\s*['"]language['"]/);
     expect(page).toContain('<ApplicationLanguageSettingsTab />');
     expect(tab).toContain('getLocaleRegistry');
     expect(tab).toContain('setLocale(candidate.code as SupportedLocale)');
@@ -28,8 +28,8 @@ describe('application language settings', () => {
     const globalMeta = source('components/navigation/TopGlobalBar/components/GlobalMeta.tsx');
 
     expect(tab).toContain('applicationLanguageBoundary');
-    expect(globalMeta).toContain(
-      'router.push("/01-enterprise-core/identity-access/user-management/system-settings")'
+    expect(globalMeta).toMatch(
+      /router\.push\(['"]\/01-enterprise-core\/identity-access\/user-management\/system-settings['"]\)/
     );
   });
 });
diff --git a/frontend/tests/app/setup-onboarding.test.ts b/frontend/tests/app/setup-onboarding.test.ts
index 56e8bd18..22ada260 100644
--- a/frontend/tests/app/setup-onboarding.test.ts
+++ b/frontend/tests/app/setup-onboarding.test.ts
@@ -76,7 +76,7 @@ describe("standalone phased setup onboarding", () => {
     expect(page).toContain("organizationReferenceOptions");
     expect(page).toContain("currency_id: currencies.map");
     expect(page).toContain("PRIMARY_GENERAL_LEDGER_REFERENCE");
-    expect(page).toContain("setAccounts(listFrom(accountsResponse).filter((item) => item.is_active !== false))");
+    expect(page).toMatch(/setAccounts\(listFrom\(accountsResponse\)\.filter\(\(item\) => item\.is_active !== false\)\)/);
     expect(page).toContain("hasGovernedLedger");
     expect(workspace).toContain("referenceOptionsByAttribute");
     expect(workspace).toContain("SearchableSelect");
@@ -92,8 +92,8 @@ describe("standalone phased setup onboarding", () => {
     const englishCatalog = source("lib/i18n/catalog/en-US.ts");
     const arabicCatalog = source("lib/i18n/catalog/ar-SA.ts");
 
-    expect(workspace).toContain('const CALENDAR_YEAR_VARIANT = "K4"');
-    expect(workspace).toContain('attribute.attribute_key === "fiscal_year_variant"');
+    expect(workspace).toMatch(/const CALENDAR_YEAR_VARIANT = ['"]K4['"]/);
+    expect(workspace).toMatch(/attribute\.attribute_key === ['"]fiscal_year_variant['"]/);
     expect(workspace).toContain("fiscalYearVariant.calendarYear");
     expect(englishCatalog).toContain("Fiscal year structure");
     expect(arabicCatalog).toContain("هيكل السنة المالية");
@@ -122,7 +122,7 @@ describe("standalone phased setup onboarding", () => {
     expect(layout).toContain("setup-top-utility");
     expect(layout).toContain("ApplicationLanguageSettingsTab");
     expect(workspace).toContain("SUPPORTED_LANGUAGE_OPTIONS");
-    expect(workspace).toContain('attribute.attribute_key === "language"');
+    expect(workspace).toMatch(/attribute\.attribute_key === ['"]language['"]/);
     expect(englishCatalog).toContain("It does not change the current user's application interface language");
     expect(arabicCatalog).toContain("ولا تغيّر لغة واجهة التطبيق للمستخدم الحالي");
   });

From 767fbcecd5cd4990cb14367fb8c8af8700d7b129 Mon Sep 17 00:00:00 2001
From: Emran025 <1.48263577e+08+Emran025@users.noreply.github.com>
Date: Sat, 22 Aug 2026 00:21:29 +0000
Subject: [PATCH 4/9] feat(setup): guide onboarding and simplify operating
 links

---
 .../Services/ModuleReadinessService.php       |   2 +-
 .../Services/ModuleSelectionService.php       |  15 +-
 .../Services/OperatingContextService.php      |  84 ++++++----
 .../ConfigureOperatingContextRequest.php      |  20 +--
 .../Feature/Api/OperatingContextApiTest.php   |  13 ++
 .../setup-language-and-finance-ux-design.md   |  10 ++
 .../org-hierarchy/(pages)/page.tsx            | 108 +++----------
 frontend/app/globals.css                      |  15 +-
 .../components/SetupAccountingSection.tsx     |  12 ++
 .../setup/components/SetupJourneyStepper.tsx  |  62 ++++++++
 .../setup/components/SetupModuleSelection.tsx |   7 +-
 .../components/SetupOperatingScopeSection.tsx |  83 +++++-----
 frontend/app/setup/page.tsx                   | 145 ++++++++++++------
 frontend/app/setup/types.ts                   |   5 +
 frontend/i18n/catalog/en-US.json              |   9 +-
 frontend/i18n/catalog/source.json             |  30 ++++
 frontend/lib/i18n/catalog/ar-SA.ts            |   9 +-
 frontend/lib/i18n/catalog/en-US.ts            |   9 +-
 frontend/tests/app/setup-onboarding.test.ts   |  29 +++-
 19 files changed, 412 insertions(+), 255 deletions(-)
 create mode 100644 frontend/app/setup/components/SetupJourneyStepper.tsx

diff --git a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/ModuleReadinessService.php b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/ModuleReadinessService.php
index 7aaa1300..910aaf17 100644
--- a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/ModuleReadinessService.php
+++ b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/ModuleReadinessService.php
@@ -227,7 +227,7 @@ public function validateOperatingStructure(?OperatingContext $context, ?array $i
 
         $context->loadMissing(['warehouse', 'posTerminal', 'costCenter', 'profitCenter']);
 
-        foreach (['costCenter' => 'COST_CENTER', 'profitCenter' => 'PROFIT_CENTER'] as $relation => $expectedType) {
+        foreach (['costCenter' => 'COST_CENTER'] as $relation => $expectedType) {
             $businessRecord = $context->{$relation};
             $nodeUuid = $businessRecord?->structure_node_uuid;
             $node = $nodeUuid ? StructureNode::find($nodeUuid) : null;
diff --git a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/ModuleSelectionService.php b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/ModuleSelectionService.php
index cfe74f78..7a61b508 100644
--- a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/ModuleSelectionService.php
+++ b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/ModuleSelectionService.php
@@ -104,7 +104,6 @@ public function activateSelected(?int $userId): array
         $evaluation = collect($readiness['modules'])->keyBy('module_key');
         $baselineReady = (bool) data_get($readiness, 'onboarding.baseline_ready', false);
         $selected = $this->selectedModuleKeys();
-        $missingStarterModules = array_values(array_diff(self::CORE_STARTER_MODULES, $selected));
         $activated = [];
         $pending = [];
 
@@ -116,14 +115,6 @@ public function activateSelected(?int $userId): array
             return compact('activated', 'pending');
         }
 
-        if ($missingStarterModules !== []) {
-            foreach ($selected as $moduleKey) {
-                $pending[$moduleKey] = ['mandatory_core_module_selection_incomplete'];
-            }
-
-            return compact('activated', 'pending');
-        }
-
         foreach ($selected as $moduleKey) {
             $module = Module::query()->where('module_key', $moduleKey)->first();
             $status = $evaluation->get($moduleKey);
@@ -192,14 +183,12 @@ public function state(?int $userId = null): array
         $activeBusiness = $selectedBusiness->where('is_operational', true)->values();
         $pendingBusiness = $selectedBusiness->where('is_operational', false)->values();
         $baselineReady = (bool) data_get($readiness, 'onboarding.baseline_ready', false);
-        $missingStarterModules = array_values(array_diff(self::CORE_STARTER_MODULES, $selected));
+        $missingStarterModules = [];
         $activeStarterModules = $activeBusiness
             ->whereIn('module_key', self::CORE_STARTER_MODULES)
             ->pluck('module_key')
             ->all();
-        $starterBundleActive = $baselineReady
-            && $missingStarterModules === []
-            && array_values(array_diff(self::CORE_STARTER_MODULES, $activeStarterModules)) === [];
+        $starterBundleActive = $baselineReady;
 
         return [
             // Core access is only granted after the mandated foundational,
diff --git a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OperatingContextService.php b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OperatingContextService.php
index 316498d6..3e1d8c41 100644
--- a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OperatingContextService.php
+++ b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OperatingContextService.php
@@ -43,7 +43,6 @@ public function readiness(?int $userId): array
             $this->check('working_unit', $workingUnitReadiness['ready']),
             $this->check('warehouse', $warehouse !== null && $warehouse->is_active && $warehouse->status === 'active'),
             $this->check('cost_center', $costCenter !== null && $costCenter->is_active),
-            $this->check('profit_center', $profitCenter !== null && $profitCenter->is_active),
             $this->check('pos_terminal', $terminal !== null && $terminal->is_active && $terminal->status === 'active'),
             $this->check('organizational_structure', $structuralReadiness['ready']),
             $this->check('open_fiscal_period', $accountingReadiness['open_fiscal_period']['ready']),
@@ -69,37 +68,58 @@ public function readiness(?int $userId): array
     public function configure(array $data, ?int $userId): OperatingContext
     {
         return DB::transaction(function () use ($data, $userId) {
-            $warehouseData = Arr::get($data, 'warehouse', []);
-            $warehouse = Warehouse::query()->updateOrCreate(
-                ['code' => $warehouseData['code']],
-                [
-                    'name' => $warehouseData['name'],
-                    'name_en' => $warehouseData['name_en'] ?? null,
-                    'org_node_uuid' => $data['org_node_uuid'] ?? null,
-                    'cost_center_id' => $data['cost_center_id'] ?? null,
-                    'profit_center_id' => $data['profit_center_id'] ?? null,
-                    'status' => 'active',
-                    'is_active' => true,
-                    'description' => $warehouseData['description'] ?? null,
-                    'created_by' => $userId,
-                ]
-            );
-
-            $terminalData = Arr::get($data, 'pos_terminal', []);
-            $terminal = PosTerminal::query()->updateOrCreate(
-                ['code' => $terminalData['code']],
-                [
-                    'name' => $terminalData['name'],
-                    'name_en' => $terminalData['name_en'] ?? null,
+            $terminal = isset($data['pos_terminal_id'])
+                ? PosTerminal::query()
+                    ->whereKey($data['pos_terminal_id'])
+                    ->where('is_active', true)
+                    ->where('status', 'active')
+                    ->firstOrFail()
+                : null;
+            $warehouse = $terminal?->warehouse;
+
+            if (!$terminal) {
+                $warehouseData = Arr::get($data, 'warehouse', []);
+                $warehouse = Warehouse::query()->updateOrCreate(
+                    ['code' => $warehouseData['code']],
+                    [
+                        'name' => $warehouseData['name'],
+                        'name_en' => $warehouseData['name_en'] ?? null,
+                        'org_node_uuid' => $data['org_node_uuid'] ?? null,
+                        'cost_center_id' => $data['cost_center_id'] ?? null,
+                        'profit_center_id' => $data['profit_center_id'] ?? null,
+                        'status' => 'active',
+                        'is_active' => true,
+                        'description' => $warehouseData['description'] ?? null,
+                        'created_by' => $userId,
+                    ]
+                );
+                $terminalData = Arr::get($data, 'pos_terminal', []);
+                $terminal = PosTerminal::query()->updateOrCreate(
+                    ['code' => $terminalData['code']],
+                    [
+                        'name' => $terminalData['name'],
+                        'name_en' => $terminalData['name_en'] ?? null,
+                        'org_node_uuid' => $data['org_node_uuid'] ?? null,
+                        'warehouse_id' => $warehouse->id,
+                        'cost_center_id' => $data['cost_center_id'] ?? null,
+                        'profit_center_id' => $data['profit_center_id'] ?? null,
+                        'status' => 'active',
+                        'is_active' => true,
+                        'created_by' => $userId,
+                    ]
+                );
+            }
+
+            $terminal->update([
+                'org_node_uuid' => $data['org_node_uuid'] ?? null,
+                'cost_center_id' => $data['cost_center_id'] ?? null,
+            ]);
+            if ($warehouse) {
+                $warehouse->update([
                     'org_node_uuid' => $data['org_node_uuid'] ?? null,
-                    'warehouse_id' => $warehouse->id,
                     'cost_center_id' => $data['cost_center_id'] ?? null,
-                    'profit_center_id' => $data['profit_center_id'] ?? null,
-                    'status' => 'active',
-                    'is_active' => true,
-                    'created_by' => $userId,
-                ]
-            );
+                ]);
+            }
 
             OperatingContext::query()
                 ->where('user_id', $userId)
@@ -110,9 +130,9 @@ public function configure(array $data, ?int $userId): OperatingContext
                 ['user_id' => $userId, 'pos_terminal_id' => $terminal->id],
                 [
                     'org_node_uuid' => $data['org_node_uuid'] ?? null,
-                    'warehouse_id' => $warehouse->id,
+                    'warehouse_id' => $warehouse?->id,
                     'cost_center_id' => $data['cost_center_id'] ?? null,
-                    'profit_center_id' => $data['profit_center_id'] ?? null,
+                    'profit_center_id' => $data['profit_center_id'] ?? $terminal->profit_center_id,
                     // Status is recalculated from the authoritative readiness
                     // contract below; configuration submission is never proof of readiness.
                     'status' => 'draft',
diff --git a/backend/app/Http/Requests/EnterpriseCore/OrganizationGovernance/ConfigureOperatingContextRequest.php b/backend/app/Http/Requests/EnterpriseCore/OrganizationGovernance/ConfigureOperatingContextRequest.php
index b6bf60a2..cec96fee 100644
--- a/backend/app/Http/Requests/EnterpriseCore/OrganizationGovernance/ConfigureOperatingContextRequest.php
+++ b/backend/app/Http/Requests/EnterpriseCore/OrganizationGovernance/ConfigureOperatingContextRequest.php
@@ -16,15 +16,16 @@ public function rules(): array
         return [
             'org_node_uuid' => 'required|exists:structure_nodes,node_uuid',
             'cost_center_id' => 'required|exists:cost_centers,id',
-            'profit_center_id' => 'required|exists:profit_centers,id',
-            'warehouse' => 'required|array',
-            'warehouse.code' => 'required|string|max:30',
-            'warehouse.name' => 'required|string|max:255',
+            'pos_terminal_id' => 'required_without:pos_terminal|nullable|exists:pos_terminals,id',
+            'profit_center_id' => 'nullable|exists:profit_centers,id',
+            'warehouse' => 'required_with:pos_terminal|array',
+            'warehouse.code' => 'required_with:pos_terminal|string|max:30',
+            'warehouse.name' => 'required_with:pos_terminal|string|max:255',
             'warehouse.name_en' => 'nullable|string|max:255',
             'warehouse.description' => 'nullable|string',
-            'pos_terminal' => 'required|array',
-            'pos_terminal.code' => 'required|string|max:30',
-            'pos_terminal.name' => 'required|string|max:255',
+            'pos_terminal' => 'required_without:pos_terminal_id|array',
+            'pos_terminal.code' => 'required_without:pos_terminal_id|string|max:30',
+            'pos_terminal.name' => 'required_without:pos_terminal_id|string|max:255',
             'pos_terminal.name_en' => 'nullable|string|max:255',
         ];
     }
@@ -34,9 +35,8 @@ public function messages(): array
         return [
             'org_node_uuid.required' => 'An organizational unit must be selected before configuring the operating context.',
             'cost_center_id.required' => 'An active cost center must be selected.',
-            'profit_center_id.required' => 'An active profit center must be selected.',
-            'warehouse.required' => 'Warehouse configuration is required.',
-            'pos_terminal.required' => 'POS terminal configuration is required.',
+            'pos_terminal_id.required_without' => 'Select an existing active POS terminal or provide a new terminal configuration.',
+            'pos_terminal.required_without' => 'Select an existing active POS terminal or provide a new terminal configuration.',
         ];
     }
 }
diff --git a/backend/tests/Feature/Api/OperatingContextApiTest.php b/backend/tests/Feature/Api/OperatingContextApiTest.php
index 477c1b83..8c64d6d3 100644
--- a/backend/tests/Feature/Api/OperatingContextApiTest.php
+++ b/backend/tests/Feature/Api/OperatingContextApiTest.php
@@ -128,5 +128,18 @@ public function test_can_configure_a_ready_operating_context_only_after_structur
         $context = OperatingContext::query()->firstOrFail();
         $this->assertTrue((bool) $context->is_default);
         $this->assertSame('ready', $context->status);
+
+        $existingLinkResponse = $this->authPost(route('v2.operating_context.configure'), [
+            'org_node_uuid' => $company->node_uuid,
+            'cost_center_id' => $costCenter->id,
+            'pos_terminal_id' => $context->pos_terminal_id,
+        ]);
+
+        $this->assertSuccessResponse($existingLinkResponse, 201);
+        $existingLinkResponse->assertJsonPath('data.pos_terminal.code', 'POS-STORE')
+            ->assertJsonPath('data.cost_center.id', $costCenter->id);
+        $this->assertDatabaseCount('warehouses', 1);
+        $this->assertDatabaseCount('pos_terminals', 1);
+        $this->assertDatabaseCount('operating_contexts', 1);
     }
 }
diff --git a/docs/Plans/setup-language-and-finance-ux-design.md b/docs/Plans/setup-language-and-finance-ux-design.md
index f75fd1f4..b59c4694 100644
--- a/docs/Plans/setup-language-and-finance-ux-design.md
+++ b/docs/Plans/setup-language-and-finance-ux-design.md
@@ -24,6 +24,16 @@ A fiscal year is a reporting and inventory/balance-sheet period, normally twelve
 
 ACCORE currently stores operational `FiscalPeriod` records but has no dedicated fiscal-year-variant master entity. The setup field therefore must be renamed from the opaque “Fiscal year variant” label to a clear “Fiscal year structure” field and constrained to explicit supported choices. The initial choices are calendar year (`K4`) and a controlled custom-year configuration. The calendar-year choice is the safe default. A custom year is only a descriptor until the system has a managed variant and period-definition model; the UI makes that status explicit rather than suggesting unsupported automation.
 
+## Guided Setup Journey
+
+The setup page is a gated, sequential journey rather than a vertical collection of unrelated forms. It presents one actionable step at a time: **Foundation**, **Operating links**, and **Optional capabilities**. The user moves with explicit Back and Next controls. A step can advance only when its applicable readiness condition is satisfied; completed steps remain available for review and correction without forcing the user through inactive forms.
+
+Every successful save reloads the readiness, setup state, organizational tree, integrity result, and applicable reference data before the user sees the next action. The summary badges, current-phase card, step availability, and editable controls therefore derive from the same refreshed server response rather than stale local assumptions.
+
+Foundation retains only the legal, accounting, and organizational data required to form the initial operating network. Where an embedded baseline already provides a usable general-ledger structure or another delivered capability, setup shows it as available context rather than requiring the user to recreate it. Additional business modules remain an explicit later choice.
+
+The operating-links step does not recreate a working unit, a profit center, a warehouse, or a point of sale that is already represented in the organizational structure. Instead, it selects an existing active operating unit and lets the administrator maintain the specific cost-center-to-point-of-sale relationship needed for the default context. Profit-center ownership stays with its organizational-unit configuration and is displayed as context, not demanded again as a duplicate entry.
+
 ## References
 
 1. [SAP Help Portal — Fiscal Year and Fiscal Year Variant](https://help.sap.com/docs/SAP_S4HANA_CLOUD/0fa84c9d9c634132b7c4abb9ffdd8f06/7353d7531a4d424de10000000a174cb4.html)
diff --git a/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/(pages)/page.tsx b/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/(pages)/page.tsx
index f212d731..d09cf857 100644
--- a/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/(pages)/page.tsx
+++ b/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/(pages)/page.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import { useI18n, catalogText, catalogMessage } from "@/lib/i18n";
+import { useI18n, catalogText } from "@/lib/i18n";
 import { MainLayout } from '@/components/layout';
 import {
   Button,
@@ -30,21 +30,13 @@ type OrgTab =
 type SetupForm = {
   org_node_uuid: string | null;
   cost_center_id: number | null;
-  profit_center_id: number | null;
-  warehouse_code: string;
-  warehouse_name: string;
-  pos_code: string;
-  pos_name: string;
+  pos_terminal_id: number | null;
 };
 
 const initialSetupForm: SetupForm = {
   org_node_uuid: null,
   cost_center_id: null,
-  profit_center_id: null,
-  warehouse_code: 'WH-MAIN',
-  warehouse_name: catalogMessage("enterpriseCore.orgHierarchy.mainWarehouse"),
-  pos_code: 'POS-MAIN',
-  pos_name: catalogMessage("enterpriseCore.orgHierarchy.mainPos"),
+  pos_terminal_id: null,
 };
 
 function listFromResponse(response: any): any[] {
@@ -62,19 +54,17 @@ export default function OrganizationalStructurePage() {
   const [setupForm, setSetupForm] = useState<SetupForm>(initialSetupForm);
   const [nodes, setNodes] = useState<any[]>([]);
   const [costCenters, setCostCenters] = useState<any[]>([]);
-  const [profitCenters, setProfitCenters] = useState<any[]>([]);
+  const [posTerminals, setPosTerminals] = useState<any[]>([]);
   const { readiness, loadReadiness } = useOperatingContextStore();
   const readinessLabels: Record<string, string> = {
     warehouse: i18n.catalog["enterpriseCore.orgHierarchy.readinessWarehouse"],
     cost_center: i18n.catalog["enterpriseCore.orgHierarchy.readinessCostCenter"],
-    profit_center: i18n.catalog["enterpriseCore.orgHierarchy.readinessProfitCenter"],
     pos_terminal: i18n.catalog["enterpriseCore.orgHierarchy.readinessPosTerminal"],
     organizational_structure: i18n.catalog["enterpriseCore.orgHierarchy.readinessOrganizationalStructure"],
   };
   const readinessActions: Record<string, string> = {
     warehouse: i18n.catalog["enterpriseCore.orgHierarchy.readinessActionWarehouse"],
     cost_center: i18n.catalog["enterpriseCore.orgHierarchy.readinessActionCostCenter"],
-    profit_center: i18n.catalog["enterpriseCore.orgHierarchy.readinessActionProfitCenter"],
     pos_terminal: i18n.catalog["enterpriseCore.orgHierarchy.readinessActionPosTerminal"],
     organizational_structure: i18n.catalog["enterpriseCore.orgHierarchy.readinessActionOrganizationalStructure"],
   };
@@ -90,16 +80,14 @@ export default function OrganizationalStructurePage() {
 
   useEffect(() => {
     const loadSetupData = async () => {
-      const [nodeResponse, costResponse, profitResponse] = await Promise.all([
+      const [nodeResponse, costResponse, posResponse] = await Promise.all([
         fetchAPI(API_ENDPOINTS.ENTERPRISE_CORE.ORG.NODES),
         fetchAPI(API_ENDPOINTS.FINANCE.COST_CENTERS.BASE),
-        fetchAPI(API_ENDPOINTS.FINANCE.PROFIT_CENTERS.BASE),
+        fetchAPI(API_ENDPOINTS.ENTERPRISE_CORE.OPERATING_CONTEXT.POS_TERMINALS),
       ]);
       setNodes(listFromResponse(nodeResponse));
       setCostCenters(listFromResponse(costResponse).filter((center) => center.is_active !== false));
-      setProfitCenters(
-        listFromResponse(profitResponse).filter((center) => center.is_active !== false)
-      );
+      setPosTerminals(listFromResponse(posResponse).filter((terminal) => terminal.is_active !== false));
       await loadReadiness();
     };
     loadSetupData();
@@ -107,7 +95,7 @@ export default function OrganizationalStructurePage() {
 
   const nodeOptions = useMemo<SelectOption[]>(
     () =>
-      nodes.map((node) => ({
+      nodes.filter((node) => node.node_type_id === 'COMP_CODE').map((node) => ({
         value: node.node_uuid,
         label: node.code || node.node_uuid,
         subtitle: node.status,
@@ -123,14 +111,14 @@ export default function OrganizationalStructurePage() {
       })),
     [costCenters]
   );
-  const profitCenterOptions = useMemo<SelectOption[]>(
+  const posTerminalOptions = useMemo<SelectOption[]>(
     () =>
-      profitCenters.map((center) => ({
-        value: center.id,
-        label: catalogText(i18n, "common.general.notAvailable.alternative10", { value0: center.code, value1: center.name }),
-        subtitle: center.name_en || '',
+      posTerminals.map((terminal) => ({
+        value: terminal.id,
+        label: catalogText(i18n, "common.general.notAvailable.alternative10", { value0: terminal.code, value1: terminal.name }),
+        subtitle: terminal.name_en || '',
       })),
-    [profitCenters]
+    [posTerminals]
   );
 
   const updateSetupField = <K extends keyof SetupForm>(key: K, value: SetupForm[K]) => {
@@ -141,11 +129,7 @@ export default function OrganizationalStructurePage() {
     if (
       !setupForm.org_node_uuid ||
       !setupForm.cost_center_id ||
-      !setupForm.profit_center_id ||
-      !setupForm.warehouse_code ||
-      !setupForm.warehouse_name ||
-      !setupForm.pos_code ||
-      !setupForm.pos_name
+      !setupForm.pos_terminal_id
     ) {
       showAlert(
         'operating-context-alert',
@@ -162,15 +146,7 @@ export default function OrganizationalStructurePage() {
         body: JSON.stringify({
           org_node_uuid: setupForm.org_node_uuid,
           cost_center_id: setupForm.cost_center_id,
-          profit_center_id: setupForm.profit_center_id,
-          warehouse: {
-            code: setupForm.warehouse_code,
-            name: setupForm.warehouse_name,
-          },
-          pos_terminal: {
-            code: setupForm.pos_code,
-            name: setupForm.pos_name,
-          },
+          pos_terminal_id: setupForm.pos_terminal_id,
         }),
       });
       if (!response.success) {
@@ -295,58 +271,16 @@ export default function OrganizationalStructurePage() {
             />
           </div>
           <div className="form-group">
-            <label>{i18n.catalog["enterpriseCore.orgHierarchy.profitCenter"]}</label>
+            <label>{i18n.catalog["enterpriseCore.setup.scope.pointOfSale"]}</label>
             <SearchableSelect
-              options={profitCenterOptions}
-              value={setupForm.profit_center_id}
-              onChange={(value) =>
-                updateSetupField('profit_center_id', typeof value === 'number' ? value : null)
-              }
-              placeholder={i18n.catalog["enterpriseCore.orgHierarchy.selectActiveProfitCenter"]}
+              options={posTerminalOptions}
+              value={setupForm.pos_terminal_id}
+              onChange={(value) => updateSetupField('pos_terminal_id', typeof value === 'number' ? value : null)}
+              placeholder={i18n.catalog["enterpriseCore.orgHierarchy.selectOperatingUnitOptional"]}
               required
             />
           </div>
         </div>
-        <div className="form-row">
-          <div className="form-group">
-            <label htmlFor="warehouse-code">{i18n.catalog["enterpriseCore.orgHierarchy.warehouseCode"]}</label>
-            <input
-              id="warehouse-code"
-              className="form-control"
-              value={setupForm.warehouse_code}
-              onChange={(event) => updateSetupField('warehouse_code', event.target.value)}
-            />
-          </div>
-          <div className="form-group">
-            <label htmlFor="warehouse-name">{i18n.catalog["enterpriseCore.orgHierarchy.warehouseName"]}</label>
-            <input
-              id="warehouse-name"
-              className="form-control"
-              value={setupForm.warehouse_name}
-              onChange={(event) => updateSetupField('warehouse_name', event.target.value)}
-            />
-          </div>
-        </div>
-        <div className="form-row">
-          <div className="form-group">
-            <label htmlFor="pos-code">{i18n.catalog["enterpriseCore.orgHierarchy.posTerminalCode"]}</label>
-            <input
-              id="pos-code"
-              className="form-control"
-              value={setupForm.pos_code}
-              onChange={(event) => updateSetupField('pos_code', event.target.value)}
-            />
-          </div>
-          <div className="form-group">
-            <label htmlFor="pos-name">{i18n.catalog["enterpriseCore.orgHierarchy.posTerminalName"]}</label>
-            <input
-              id="pos-name"
-              className="form-control"
-              value={setupForm.pos_name}
-              onChange={(event) => updateSetupField('pos_name', event.target.value)}
-            />
-          </div>
-        </div>
       </Dialog>
     </MainLayout>
   );
diff --git a/frontend/app/globals.css b/frontend/app/globals.css
index 2c1db3c5..f4ff18db 100644
--- a/frontend/app/globals.css
+++ b/frontend/app/globals.css
@@ -7410,6 +7410,19 @@ body.nav-sidebar-is-collapsed .sidebar-toggle-btn {
 .setup-phase-progress-item.is-ready { border-color: rgba(16, 185, 129, 0.42); background: rgba(16, 185, 129, 0.06); }
 .setup-phase-progress-item.is-current { border-color: rgba(37, 99, 235, 0.45); box-shadow: 0 0 0 3px var(--primary-subtle); }
 .setup-phase-progress-item.is-locked { opacity: 0.72; }
+.setup-journey { display: grid; gap: 0.85rem; padding: 0.9rem; border: 1px solid var(--border-color); border-radius: var(--radius-md); background: var(--surface-white); box-shadow: var(--shadow-xs); }
+.setup-journey-progress { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 0.65rem; }
+.setup-journey-step { display: grid; grid-template-columns: auto minmax(0, 1fr); gap: 0.6rem; align-items: start; min-height: 4.5rem; padding: 0.7rem; border: 1px solid transparent; border-radius: var(--radius-sm); color: var(--text-muted); }
+.setup-journey-step-index { display: grid; place-items: center; width: 1.6rem; height: 1.6rem; border: 1px solid currentColor; border-radius: 50%; font-size: 0.72rem; font-weight: 800; }
+.setup-journey-step strong, .setup-journey-step small { display: block; }
+.setup-journey-step strong { color: var(--text-primary); font-size: 0.82rem; line-height: 1.35; }
+.setup-journey-step small { margin-top: 0.2rem; font-size: 0.74rem; line-height: 1.4; }
+.setup-journey-step.is-current { border-color: var(--primary-color); background: var(--primary-subtle); color: var(--primary-color); }
+.setup-journey-step.is-complete { color: var(--success-color); }
+.setup-journey-step.is-locked { opacity: 0.52; }
+.setup-journey-actions { display: flex; justify-content: flex-end; gap: 0.65rem; padding-top: 0.2rem; }
+.readiness-notice.success { border-color: rgba(16, 185, 129, 0.42); background: rgba(16, 185, 129, 0.07); color: #047857; }
+.setup-module-group-included { padding: 0.85rem; border-inline-start: 3px solid var(--success-color); border-radius: var(--radius-sm); background: rgba(16, 185, 129, 0.05); }
 .setup-module-groups { display: grid; gap: 1rem; }
 .setup-module-group { display: grid; gap: 0.65rem; }
 .setup-module-group-title { margin: 0; color: var(--text-primary); font-size: 0.9rem; }
@@ -7418,7 +7431,7 @@ body.nav-sidebar-is-collapsed .sidebar-toggle-btn {
 .setup-module-card.is-disabled { cursor: not-allowed; opacity: 0.62; }
 .setup-module-card.is-disabled:hover { border-color: var(--border-color); box-shadow: none; }
 @keyframes setup-spin { to { transform: rotate(360deg); } }
-@media (max-width: 768px) { .setup-shell { padding: 0.75rem; } .setup-phase-progress { grid-template-columns: 1fr; } }
+@media (max-width: 768px) { .setup-shell { padding: 0.75rem; } .setup-phase-progress, .setup-journey-progress { grid-template-columns: 1fr; } .setup-journey-actions .btn { flex: 1 1 auto; } }
 @media (prefers-reduced-motion: reduce) { .setup-access-gate-spinner { animation: none; } }
 
 /* Organizational architecture workspace */
diff --git a/frontend/app/setup/components/SetupAccountingSection.tsx b/frontend/app/setup/components/SetupAccountingSection.tsx
index 8b66fd8f..f8913c56 100644
--- a/frontend/app/setup/components/SetupAccountingSection.tsx
+++ b/frontend/app/setup/components/SetupAccountingSection.tsx
@@ -25,6 +25,9 @@ interface SetupAccountingSectionProps {
   periodStart: string;
   periodEnd: string;
   recordSummary: string;
+  chartReady: boolean;
+  periodReady: boolean;
+  completeLabel: string;
   isSaving: boolean;
   onAccountCodeChange: (value: string) => void;
   onAccountNameChange: (value: string) => void;
@@ -56,6 +59,9 @@ export function SetupAccountingSection({
   periodStart,
   periodEnd,
   recordSummary,
+  chartReady,
+  periodReady,
+  completeLabel,
   isSaving,
   onAccountCodeChange,
   onAccountNameChange,
@@ -68,6 +74,8 @@ export function SetupAccountingSection({
 }: SetupAccountingSectionProps) {
   return (
     <SetupSection id="setup-accounting" title={title} description={description}>
+      {chartReady ? <p className="readiness-notice success">{accountNameLabel}: {completeLabel}</p> : null}
+      {!chartReady ? <>
       <div className="settings-form-grid setup-form-grid">
         <SetupField id="setup-account-code" label={accountCodeLabel} required>
           <input id="setup-account-code" className="setup-input" dir="ltr" value={accountCode} onChange={(event) => onAccountCodeChange(event.target.value)} required />
@@ -84,6 +92,9 @@ export function SetupAccountingSection({
       <div className="setup-actions">
         <Button type="button" onClick={onCreateAccount} isLoading={isSaving}>{createAccountLabel}</Button>
       </div>
+      </> : null}
+      {periodReady ? <p className="readiness-notice success">{periodNameLabel}: {completeLabel}</p> : null}
+      {!periodReady ? <>
       <div className="settings-form-grid setup-form-grid">
         <SetupField id="setup-period-name" label={periodNameLabel} required>
           <input id="setup-period-name" className="setup-input" dir={getTextDirection(periodName, "rtl")} value={periodName} onChange={(event) => onPeriodNameChange(event.target.value)} required />
@@ -98,6 +109,7 @@ export function SetupAccountingSection({
       <div className="setup-actions">
         <Button type="button" onClick={onCreatePeriod} isLoading={isSaving}>{createPeriodLabel}</Button>
       </div>
+      </> : null}
       <p className="setup-context-summary">{recordSummary}</p>
     </SetupSection>
   );
diff --git a/frontend/app/setup/components/SetupJourneyStepper.tsx b/frontend/app/setup/components/SetupJourneyStepper.tsx
new file mode 100644
index 00000000..81457e5c
--- /dev/null
+++ b/frontend/app/setup/components/SetupJourneyStepper.tsx
@@ -0,0 +1,62 @@
+import { Button } from "@/components/ui";
+
+export type SetupJourneyStepId = "foundation" | "operating_links" | "optional_capabilities";
+
+type SetupJourneyStep = {
+  id: SetupJourneyStepId;
+  title: string;
+  description: string;
+  complete: boolean;
+  enabled: boolean;
+};
+
+interface SetupJourneyStepperProps {
+  steps: SetupJourneyStep[];
+  activeStep: SetupJourneyStepId;
+  previousLabel: string;
+  nextLabel: string;
+  completeLabel: string;
+  onPrevious: () => void;
+  onNext: () => void;
+}
+
+export function SetupJourneyStepper({
+  steps,
+  activeStep,
+  previousLabel,
+  nextLabel,
+  completeLabel,
+  onPrevious,
+  onNext,
+}: SetupJourneyStepperProps) {
+  const activeIndex = steps.findIndex((step) => step.id === activeStep);
+  const active = steps[activeIndex];
+  const isFinalStep = activeIndex === steps.length - 1;
+
+  return (
+    <section className="setup-journey" aria-label={active?.title}>
+      <div className="setup-journey-progress" aria-label={active?.title}>
+        {steps.map((step, index) => (
+          <div
+            key={step.id}
+            className={`setup-journey-step ${step.id === activeStep ? "is-current" : ""} ${step.complete ? "is-complete" : ""} ${!step.enabled ? "is-locked" : ""}`}
+          >
+            <span className="setup-journey-step-index">{index + 1}</span>
+            <span>
+              <strong>{step.title}</strong>
+              <small>{step.complete ? completeLabel : step.description}</small>
+            </span>
+          </div>
+        ))}
+      </div>
+      <div className="setup-journey-actions">
+        <Button type="button" variant="secondary" disabled={activeIndex === 0} onClick={onPrevious}>
+          {previousLabel}
+        </Button>
+        <Button type="button" disabled={!active?.complete || isFinalStep} onClick={onNext}>
+          {nextLabel}
+        </Button>
+      </div>
+    </section>
+  );
+}
diff --git a/frontend/app/setup/components/SetupModuleSelection.tsx b/frontend/app/setup/components/SetupModuleSelection.tsx
index d351eb9a..040388b7 100644
--- a/frontend/app/setup/components/SetupModuleSelection.tsx
+++ b/frontend/app/setup/components/SetupModuleSelection.tsx
@@ -55,10 +55,9 @@ export function SetupModuleSelection({
   onActivate,
 }: SetupModuleSelectionProps) {
   const businessModules = modules.filter((module) => !module.is_configuration_module);
-  const coreModules = businessModules.filter((module) => coreModuleKeys.includes(module.module_key));
   const optionalModules = businessModules.filter((module) => !coreModuleKeys.includes(module.module_key));
 
-  const moduleLabel = (module: SetupModule) => locale === "ar-SA"
+  const moduleLabel = (module: Pick<SetupModule, "module_key" | "module_name_ar" | "module_name_en">) => locale === "ar-SA"
     ? module.module_name_ar || module.module_name_en || module.module_key
     : module.module_name_en || module.module_name_ar || module.module_key;
 
@@ -104,10 +103,10 @@ export function SetupModuleSelection({
     <SetupSection id="setup-modules" title={title} description={description}>
       {!canActivate ? <p className="readiness-notice warning">{baselineRequiredLabel}</p> : null}
       <div className="setup-module-groups">
-        <div className="setup-module-group">
+        <div className="setup-module-group setup-module-group-included">
           <h4 className="setup-module-group-title">{coreTitle}</h4>
           <p className="setup-module-group-description">{coreDescription}</p>
-          {renderGroup(coreModules, true)}
+          <p className="setup-context-summary">{coreModuleKeys.map((key) => moduleLabel(businessModules.find((module) => module.module_key === key) ?? { module_key: key })).join(" · ")}</p>
         </div>
         <div className="setup-module-group">
           <h4 className="setup-module-group-title">{optionalTitle}</h4>
diff --git a/frontend/app/setup/components/SetupOperatingScopeSection.tsx b/frontend/app/setup/components/SetupOperatingScopeSection.tsx
index 5724fede..52e7c5d0 100644
--- a/frontend/app/setup/components/SetupOperatingScopeSection.tsx
+++ b/frontend/app/setup/components/SetupOperatingScopeSection.tsx
@@ -1,5 +1,4 @@
 import { Button, SearchableSelect } from "@/components/ui";
-import { getTextDirection } from "@/lib/utils";
 import { SelectOption } from "../types";
 import { SetupField } from "./SetupField";
 import { SetupSection } from "./SetupSection";
@@ -10,31 +9,28 @@ interface SetupOperatingScopeSectionProps {
   foundationComplete: boolean;
   foundationRequiredLabel: string;
   workingUnitLabel: string;
+  workingUnitCodeLabel: string;
+  workingUnitNameLabel: string;
+  saveWorkingUnitLabel: string;
   costCenterLabel: string;
-  profitCenterLabel: string;
-  warehouseCodeLabel: string;
-  warehouseNameLabel: string;
-  posCodeLabel: string;
-  posNameLabel: string;
+  pointOfSaleLabel: string;
+  contextHelper: string;
   saveLabel: string;
   workingUnit: string;
+  workingUnitCode: string;
+  workingUnitName: string;
   costCenterId: number | null;
-  profitCenterId: number | null;
-  warehouseCode: string;
-  warehouseName: string;
-  posCode: string;
-  posName: string;
+  posTerminalId: number | null;
   nodeOptions: SelectOption[];
   costOptions: SelectOption[];
-  profitOptions: SelectOption[];
+  posOptions: SelectOption[];
   isSaving: boolean;
   onWorkingUnitChange: (value: string) => void;
+  onWorkingUnitCodeChange: (value: string) => void;
+  onWorkingUnitNameChange: (value: string) => void;
+  onSaveWorkingUnit: () => void;
   onCostCenterChange: (value: number | null) => void;
-  onProfitCenterChange: (value: number | null) => void;
-  onWarehouseCodeChange: (value: string) => void;
-  onWarehouseNameChange: (value: string) => void;
-  onPosCodeChange: (value: string) => void;
-  onPosNameChange: (value: string) => void;
+  onPosTerminalChange: (value: number | null) => void;
   onSave: () => void;
 }
 
@@ -44,61 +40,54 @@ export function SetupOperatingScopeSection({
   foundationComplete,
   foundationRequiredLabel,
   workingUnitLabel,
+  workingUnitCodeLabel,
+  workingUnitNameLabel,
+  saveWorkingUnitLabel,
   costCenterLabel,
-  profitCenterLabel,
-  warehouseCodeLabel,
-  warehouseNameLabel,
-  posCodeLabel,
-  posNameLabel,
+  pointOfSaleLabel,
+  contextHelper,
   saveLabel,
   workingUnit,
+  workingUnitCode,
+  workingUnitName,
   costCenterId,
-  profitCenterId,
-  warehouseCode,
-  warehouseName,
-  posCode,
-  posName,
+  posTerminalId,
   nodeOptions,
   costOptions,
-  profitOptions,
+  posOptions,
   isSaving,
   onWorkingUnitChange,
+  onWorkingUnitCodeChange,
+  onWorkingUnitNameChange,
+  onSaveWorkingUnit,
   onCostCenterChange,
-  onProfitCenterChange,
-  onWarehouseCodeChange,
-  onWarehouseNameChange,
-  onPosCodeChange,
-  onPosNameChange,
+  onPosTerminalChange,
   onSave,
 }: SetupOperatingScopeSectionProps) {
   return (
     <SetupSection id="setup-operating-scope" title={title} description={description}>
       {!foundationComplete ? <p className="readiness-notice warning">{foundationRequiredLabel}</p> : null}
+      <p className="setup-context-summary">{contextHelper}</p>
       <fieldset className="settings-form-grid setup-form-grid" disabled={!foundationComplete}>
         <legend className="sr-only">{title}</legend>
         <SetupField id="setup-working-unit" label={workingUnitLabel} required>
           <SearchableSelect id="setup-working-unit" className="setup-select" options={nodeOptions} value={workingUnit} onChange={(value) => onWorkingUnitChange(String(value || ""))} />
         </SetupField>
-        <SetupField id="setup-cost-center" label={costCenterLabel} required>
-          <SearchableSelect id="setup-cost-center" className="setup-select" options={costOptions} value={costCenterId} onChange={(value) => onCostCenterChange(typeof value === "number" ? value : null)} />
-        </SetupField>
-        <SetupField id="setup-profit-center" label={profitCenterLabel} required>
-          <SearchableSelect id="setup-profit-center" className="setup-select" options={profitOptions} value={profitCenterId} onChange={(value) => onProfitCenterChange(typeof value === "number" ? value : null)} />
+        <SetupField id="setup-working-unit-code" label={workingUnitCodeLabel} required>
+          <input id="setup-working-unit-code" className="setup-input" dir="ltr" value={workingUnitCode} onChange={(event) => onWorkingUnitCodeChange(event.target.value)} required />
         </SetupField>
-        <SetupField id="setup-warehouse-code" label={warehouseCodeLabel} required>
-          <input id="setup-warehouse-code" className="setup-input" dir="ltr" value={warehouseCode} onChange={(event) => onWarehouseCodeChange(event.target.value)} required />
+        <SetupField id="setup-working-unit-name" label={workingUnitNameLabel}>
+          <input id="setup-working-unit-name" className="setup-input" value={workingUnitName} onChange={(event) => onWorkingUnitNameChange(event.target.value)} />
         </SetupField>
-        <SetupField id="setup-warehouse-name" label={warehouseNameLabel} required>
-          <input id="setup-warehouse-name" className="setup-input" dir={getTextDirection(warehouseName, "rtl")} value={warehouseName} onChange={(event) => onWarehouseNameChange(event.target.value)} required />
-        </SetupField>
-        <SetupField id="setup-pos-code" label={posCodeLabel} required>
-          <input id="setup-pos-code" className="setup-input" dir="ltr" value={posCode} onChange={(event) => onPosCodeChange(event.target.value)} required />
+        <SetupField id="setup-cost-center" label={costCenterLabel} required>
+          <SearchableSelect id="setup-cost-center" className="setup-select" options={costOptions} value={costCenterId} onChange={(value) => onCostCenterChange(typeof value === "number" ? value : null)} />
         </SetupField>
-        <SetupField id="setup-pos-name" label={posNameLabel} required>
-          <input id="setup-pos-name" className="setup-input" dir={getTextDirection(posName, "rtl")} value={posName} onChange={(event) => onPosNameChange(event.target.value)} required />
+        <SetupField id="setup-pos-terminal" label={pointOfSaleLabel} required>
+          <SearchableSelect id="setup-pos-terminal" className="setup-select" options={posOptions} value={posTerminalId} onChange={(value) => onPosTerminalChange(typeof value === "number" ? value : null)} />
         </SetupField>
       </fieldset>
       <div className="setup-actions">
+        <Button type="button" variant="secondary" onClick={onSaveWorkingUnit} isLoading={isSaving} disabled={!foundationComplete || !workingUnit || !workingUnitCode.trim()}>{saveWorkingUnitLabel}</Button>
         <Button type="button" onClick={onSave} isLoading={isSaving} disabled={!foundationComplete}>{saveLabel}</Button>
       </div>
     </SetupSection>
diff --git a/frontend/app/setup/page.tsx b/frontend/app/setup/page.tsx
index 2392e4f2..adda8ca3 100644
--- a/frontend/app/setup/page.tsx
+++ b/frontend/app/setup/page.tsx
@@ -7,11 +7,11 @@ import { fetchAPI } from "@/lib/api";
 import { API_ENDPOINTS } from "@/lib/endpoints";
 import { catalogText, useI18n } from "@/lib/i18n";
 import { SetupAccountingSection } from "./components/SetupAccountingSection";
+import { SetupJourneyStepper, type SetupJourneyStepId } from "./components/SetupJourneyStepper";
 import { SetupModuleSelection } from "./components/SetupModuleSelection";
 import { SetupOperatingScopeSection } from "./components/SetupOperatingScopeSection";
 import { OrganizationArchitectureWorkspace } from "./components/OrganizationArchitectureWorkspace";
 import { OrganizationIntegrity, OrganizationMetaType, OrganizationNodeDraft, OrganizationTopologyRule, OrganizationWorkspaceNode } from "./components/organizationWorkspace.types";
-import { SetupPhaseProgress } from "./components/SetupPhaseProgress";
 import { SetupReadinessSummary } from "./components/SetupReadinessSummary";
 import { Item, Readiness, SetupState } from "./types";
 
@@ -46,12 +46,13 @@ export default function SetupPage() {
   const [topologyRules, setTopologyRules] = useState<OrganizationTopologyRule[]>([]);
   const [organizationIntegrity, setOrganizationIntegrity] = useState<OrganizationIntegrity | null>(null);
   const [costCenters, setCostCenters] = useState<Item[]>([]);
-  const [profitCenters, setProfitCenters] = useState<Item[]>([]);
   const [currencies, setCurrencies] = useState<Item[]>([]);
   const [factoryCalendars, setFactoryCalendars] = useState<Item[]>([]);
   const [accounts, setAccounts] = useState<Item[]>([]);
   const [periods, setPeriods] = useState<Item[]>([]);
+  const [posTerminals, setPosTerminals] = useState<Item[]>([]);
   const [selectedModuleKeys, setSelectedModuleKeys] = useState<string[]>([]);
+  const [journeyStep, setJourneyStep] = useState<SetupJourneyStepId>("foundation");
 
   const [accountCode, setAccountCode] = useState("");
   const [accountName, setAccountName] = useState("");
@@ -61,17 +62,15 @@ export default function SetupPage() {
   const [periodEnd, setPeriodEnd] = useState("");
 
   const [workingUnit, setWorkingUnit] = useState("");
+  const [workingUnitCode, setWorkingUnitCode] = useState("");
+  const [workingUnitName, setWorkingUnitName] = useState("");
   const [costCenterId, setCostCenterId] = useState<number | null>(null);
-  const [profitCenterId, setProfitCenterId] = useState<number | null>(null);
-  const [warehouseCode, setWarehouseCode] = useState("WH-MAIN");
-  const [warehouseName, setWarehouseName] = useState("");
-  const [posCode, setPosCode] = useState("POS-MAIN");
-  const [posName, setPosName] = useState("");
+  const [posTerminalId, setPosTerminalId] = useState<number | null>(null);
 
   const load = useCallback(async () => {
     setIsLoading(true);
     try {
-      const [readinessResponse, setupResponse, nodesResponse, typesResponse, topologyResponse, integrityResponse, costsResponse, profitsResponse, currenciesResponse, factoryCalendarsResponse, accountsResponse, periodsResponse] = await Promise.all([
+      const [readinessResponse, setupResponse, nodesResponse, typesResponse, topologyResponse, integrityResponse, costsResponse, currenciesResponse, factoryCalendarsResponse, accountsResponse, periodsResponse, posTerminalsResponse] = await Promise.all([
         fetchAPI<Readiness>(API_ENDPOINTS.ENTERPRISE_CORE.OPERATING_CONTEXT.READINESS),
         fetchAPI<SetupState>(API_ENDPOINTS.ENTERPRISE_CORE.SETUP.STATE),
         fetchAPI(API_ENDPOINTS.ENTERPRISE_CORE.ORG.NODES),
@@ -79,11 +78,11 @@ export default function SetupPage() {
         fetchAPI<OrganizationTopologyRule[]>(API_ENDPOINTS.ENTERPRISE_CORE.ORG.TOPOLOGY_RULES),
         fetchAPI<OrganizationIntegrity>(API_ENDPOINTS.ENTERPRISE_CORE.ORG.INTEGRITY_CHECK),
         fetchAPI(`${API_ENDPOINTS.FINANCE.COST_CENTERS.BASE}?limit=500`),
-        fetchAPI(`${API_ENDPOINTS.FINANCE.PROFIT_CENTERS.BASE}?limit=500`),
         fetchAPI(API_ENDPOINTS.FINANCE.FOREIGN_EXCHANGE.CURRENCIES.BASE),
         fetchAPI(API_ENDPOINTS.ENTERPRISE_CORE.ORG.FACTORY_CALENDARS),
         fetchAPI(`${API_ENDPOINTS.FINANCE.ACCOUNTS.BASE}?limit=500`),
         fetchAPI(`${API_ENDPOINTS.FINANCE.FISCAL_PERIODS.BASE}?limit=500`),
+        fetchAPI(API_ENDPOINTS.ENTERPRISE_CORE.OPERATING_CONTEXT.POS_TERMINALS),
       ]);
 
       setReadiness(readinessResponse.success ? readinessResponse.data ?? null : null);
@@ -95,11 +94,15 @@ export default function SetupPage() {
       setTopologyRules(listFrom(topologyResponse) as OrganizationTopologyRule[]);
       setOrganizationIntegrity(integrityResponse.success ? integrityResponse.data ?? null : null);
       setCostCenters(listFrom(costsResponse).filter((item) => item.is_active !== false));
-      setProfitCenters(listFrom(profitsResponse).filter((item) => item.is_active !== false));
       setCurrencies(listFrom(currenciesResponse).filter((item) => item.is_active !== false));
       setFactoryCalendars(listFrom(factoryCalendarsResponse).filter((item) => item.is_active !== false));
       setAccounts(listFrom(accountsResponse).filter((item) => item.is_active !== false));
       setPeriods(listFrom(periodsResponse));
+      setPosTerminals(listFrom(posTerminalsResponse).filter((item) => item.is_active !== false));
+      const context = (readinessResponse.success ? readinessResponse.data?.context : null) as Item | null;
+      setWorkingUnit(text(context ?? {}, "org_node_uuid"));
+      setCostCenterId(Number(context?.cost_center_id) || null);
+      setPosTerminalId(Number(context?.pos_terminal_id) || null);
     } catch {
       showToast(i18n.catalog["enterpriseCore.setup.failedToLoad"], "error");
     } finally {
@@ -119,6 +122,15 @@ export default function SetupPage() {
         value1: node.meta_type?.display_name_ar || node.meta_type?.display_name || node.node_type_id,
       }),
     })), [activeNodes, i18n]);
+  const selectedWorkingUnitNode = useMemo(
+    () => nodes.find((node) => node.node_uuid === workingUnit) ?? null,
+    [nodes, workingUnit],
+  );
+  useEffect(() => {
+    if (!selectedWorkingUnitNode) return;
+    setWorkingUnitCode(selectedWorkingUnitNode.code);
+    setWorkingUnitName(typeof selectedWorkingUnitNode.attributes_json?.name === "string" ? selectedWorkingUnitNode.attributes_json.name : "");
+  }, [selectedWorkingUnitNode]);
   const costOptions = useMemo(() => costCenters.map((center) => ({
     value: Number(center.id),
     label: catalogText(i18n, "enterpriseCore.setup.centerSummary", {
@@ -126,13 +138,10 @@ export default function SetupPage() {
       value1: text(center, recordFields.name),
     }),
   })), [costCenters, i18n]);
-  const profitOptions = useMemo(() => profitCenters.map((center) => ({
-    value: Number(center.id),
-    label: catalogText(i18n, "enterpriseCore.setup.centerSummary", {
-      value0: text(center, recordFields.code),
-      value1: text(center, recordFields.name),
-    }),
-  })), [profitCenters, i18n]);
+  const posOptions = useMemo(() => posTerminals.map((terminal) => ({
+    value: Number(terminal.id),
+    label: [text(terminal, "code"), text(terminal, "name")].filter(Boolean).join(" — "),
+  })), [posTerminals]);
   const organizationReferenceOptions = useMemo(() => ({
     currency_id: currencies.map((currency) => ({
       value: Number(currency.id),
@@ -214,7 +223,7 @@ export default function SetupPage() {
   };
 
   const saveContext = async () => {
-    if (!workingUnit || !costCenterId || !profitCenterId || !warehouseCode.trim() || !warehouseName.trim() || !posCode.trim() || !posName.trim()) {
+    if (!workingUnit || !costCenterId || !posTerminalId) {
       showToast(i18n.catalog["enterpriseCore.setup.failedToSave"], "error");
       return;
     }
@@ -223,9 +232,31 @@ export default function SetupPage() {
       body: JSON.stringify({
         org_node_uuid: workingUnit,
         cost_center_id: costCenterId,
-        profit_center_id: profitCenterId,
-        warehouse: { code: warehouseCode.trim(), name: warehouseName.trim() },
-        pos_terminal: { code: posCode.trim(), name: posName.trim() },
+        pos_terminal_id: posTerminalId,
+      }),
+    }));
+  };
+
+  const selectWorkingUnit = (nodeUuid: string) => {
+    setWorkingUnit(nodeUuid);
+    const node = nodes.find((candidate) => candidate.node_uuid === nodeUuid);
+    setWorkingUnitCode(node?.code ?? "");
+    setWorkingUnitName(typeof node?.attributes_json?.name === "string" ? node.attributes_json.name : "");
+  };
+
+  const saveWorkingUnit = async () => {
+    if (!selectedWorkingUnitNode || !workingUnitCode.trim()) {
+      showToast(i18n.catalog["enterpriseCore.setup.failedToSave"], "error");
+      return;
+    }
+    await callAndReload(() => fetchAPI(API_ENDPOINTS.ENTERPRISE_CORE.ORG.NODE(selectedWorkingUnitNode.node_uuid), {
+      method: "PUT",
+      body: JSON.stringify({
+        code: workingUnitCode.trim(),
+        attributes: {
+          ...selectedWorkingUnitNode.attributes_json,
+          ...(workingUnitName.trim() ? { name: workingUnitName.trim() } : {}),
+        },
       }),
     }));
   };
@@ -248,7 +279,14 @@ export default function SetupPage() {
   };
 
   const onboarding = setupState?.onboarding ?? readiness?.onboarding;
-  const canConfigureModules = onboarding?.baseline_ready === true;
+  const canConfigureModules = onboarding?.phases.core_operations.ready === true;
+  const foundationComplete = onboarding?.phases.foundation.ready === true;
+  const operatingLinksComplete = onboarding?.phases.core_operations.ready === true;
+
+  useEffect(() => {
+    if (journeyStep === "operating_links" && !foundationComplete) setJourneyStep("foundation");
+    if (journeyStep === "optional_capabilities" && !operatingLinksComplete) setJourneyStep(foundationComplete ? "operating_links" : "foundation");
+  }, [foundationComplete, journeyStep, operatingLinksComplete]);
 
   const accountTypeLabels: Record<AccountType, string> = {
     asset: i18n.catalog["enterpriseCore.setup.accountType.asset"],
@@ -284,18 +322,20 @@ export default function SetupPage() {
         onRefresh={() => void load()}
         onOpenDashboard={() => router.push("/01-enterprise-core/system-overview/dashboard/global-dashboard")}
       />
-      <SetupPhaseProgress
-        onboarding={onboarding}
-        foundationTitle={i18n.catalog["enterpriseCore.setup.phase.foundation"]}
-        foundationDescription={i18n.catalog["enterpriseCore.setup.phase.foundationDescription"]}
-        coreOperationsTitle={i18n.catalog["enterpriseCore.setup.phase.coreOperations"]}
-        coreOperationsDescription={i18n.catalog["enterpriseCore.setup.phase.coreOperationsDescription"]}
-        moduleActivationTitle={i18n.catalog["enterpriseCore.setup.phase.moduleActivation"]}
-        moduleActivationDescription={i18n.catalog["enterpriseCore.setup.phase.moduleActivationDescription"]}
-        currentLabel={i18n.catalog["enterpriseCore.setup.phase.current"]}
-        lockedLabel={i18n.catalog["enterpriseCore.setup.phase.locked"]}
+      <SetupJourneyStepper
+        activeStep={journeyStep}
+        previousLabel={i18n.catalog["common.general.previous"]}
+        nextLabel={i18n.catalog["common.general.next"]}
         completeLabel={i18n.catalog["enterpriseCore.setup.complete"]}
+        steps={[
+          { id: "foundation", title: i18n.catalog["enterpriseCore.setup.phase.foundation"], description: i18n.catalog["enterpriseCore.setup.phase.foundationDescription"], complete: foundationComplete, enabled: true },
+          { id: "operating_links", title: i18n.catalog["enterpriseCore.setup.phase.coreOperations"], description: i18n.catalog["enterpriseCore.setup.phase.coreOperationsDescription"], complete: operatingLinksComplete, enabled: foundationComplete },
+          { id: "optional_capabilities", title: i18n.catalog["enterpriseCore.setup.phase.moduleActivation"], description: i18n.catalog["enterpriseCore.setup.phase.moduleActivationDescription"], complete: onboarding?.starter_bundle_active === true, enabled: operatingLinksComplete },
+        ]}
+        onPrevious={() => setJourneyStep((current) => current === "optional_capabilities" ? "operating_links" : "foundation")}
+        onNext={() => setJourneyStep((current) => current === "foundation" ? "operating_links" : "optional_capabilities")}
       />
+      {journeyStep === "foundation" ? <>
       <OrganizationArchitectureWorkspace
         nodes={nodes}
         metaTypes={metaTypes}
@@ -328,6 +368,9 @@ export default function SetupPage() {
         periodStart={periodStart}
         periodEnd={periodEnd}
         recordSummary={catalogText(i18n, "enterpriseCore.setup.accounting.recordSummary", { value0: accounts.length, value1: periods.length })}
+        chartReady={readiness?.accounting_readiness?.chart_of_accounts.ready === true}
+        periodReady={readiness?.accounting_readiness?.open_fiscal_period.ready === true}
+        completeLabel={i18n.catalog["enterpriseCore.setup.complete"]}
         isSaving={isSaving}
         onAccountCodeChange={setAccountCode}
         onAccountNameChange={setAccountName}
@@ -338,39 +381,40 @@ export default function SetupPage() {
         onCreateAccount={() => void createAccount()}
         onCreatePeriod={() => void createPeriod()}
       />
+      </> : null}
+      {journeyStep === "operating_links" ? (
       <SetupOperatingScopeSection
         title={i18n.catalog["enterpriseCore.setup.scope.title"]}
         description={i18n.catalog["enterpriseCore.setup.scope.description"]}
-        foundationComplete={onboarding?.phases.foundation.ready === true}
+        foundationComplete={foundationComplete}
         foundationRequiredLabel={i18n.catalog["enterpriseCore.setup.scope.foundationRequired"]}
         workingUnitLabel={i18n.catalog["enterpriseCore.setup.scope.workingUnit"]}
+        workingUnitCodeLabel={i18n.catalog["enterpriseCore.setup.scope.workingUnitCode"]}
+        workingUnitNameLabel={i18n.catalog["enterpriseCore.setup.scope.workingUnitName"]}
+        saveWorkingUnitLabel={i18n.catalog["enterpriseCore.setup.scope.saveWorkingUnit"]}
         costCenterLabel={i18n.catalog["enterpriseCore.setup.scope.costCenter"]}
-        profitCenterLabel={i18n.catalog["enterpriseCore.setup.scope.profitCenter"]}
-        warehouseCodeLabel={i18n.catalog["enterpriseCore.setup.scope.warehouseCode"]}
-        warehouseNameLabel={i18n.catalog["enterpriseCore.setup.scope.warehouseName"]}
-        posCodeLabel={i18n.catalog["enterpriseCore.setup.scope.posCode"]}
-        posNameLabel={i18n.catalog["enterpriseCore.setup.scope.posName"]}
+        pointOfSaleLabel={i18n.catalog["enterpriseCore.setup.scope.pointOfSale"]}
+        contextHelper={i18n.catalog["enterpriseCore.setup.scope.contextHelper"]}
         saveLabel={i18n.catalog["enterpriseCore.setup.scope.save"]}
         workingUnit={workingUnit}
+        workingUnitCode={workingUnitCode}
+        workingUnitName={workingUnitName}
         costCenterId={costCenterId}
-        profitCenterId={profitCenterId}
-        warehouseCode={warehouseCode}
-        warehouseName={warehouseName}
-        posCode={posCode}
-        posName={posName}
+        posTerminalId={posTerminalId}
         nodeOptions={workingUnitOptions}
         costOptions={costOptions}
-        profitOptions={profitOptions}
+        posOptions={posOptions}
         isSaving={isSaving}
-        onWorkingUnitChange={setWorkingUnit}
+        onWorkingUnitChange={selectWorkingUnit}
+        onWorkingUnitCodeChange={setWorkingUnitCode}
+        onWorkingUnitNameChange={setWorkingUnitName}
+        onSaveWorkingUnit={() => void saveWorkingUnit()}
         onCostCenterChange={setCostCenterId}
-        onProfitCenterChange={setProfitCenterId}
-        onWarehouseCodeChange={setWarehouseCode}
-        onWarehouseNameChange={setWarehouseName}
-        onPosCodeChange={setPosCode}
-        onPosNameChange={setPosName}
+        onPosTerminalChange={setPosTerminalId}
         onSave={() => void saveContext()}
       />
+      ) : null}
+      {journeyStep === "optional_capabilities" ? (
       <SetupModuleSelection
         locale={locale}
         modules={setupState?.modules ?? []}
@@ -396,6 +440,7 @@ export default function SetupPage() {
         onSave={() => void saveModuleSelection()}
         onActivate={() => void activateSelectedModules()}
       />
+      ) : null}
     </div>
   );
 }
diff --git a/frontend/app/setup/types.ts b/frontend/app/setup/types.ts
index 2d9d040a..4ed3c0b7 100644
--- a/frontend/app/setup/types.ts
+++ b/frontend/app/setup/types.ts
@@ -31,6 +31,11 @@ export type Onboarding = {
 
 export type Readiness = {
   ready: boolean;
+  context?: {
+    org_node_uuid?: string | null;
+    cost_center_id?: number | null;
+    pos_terminal_id?: number | null;
+  } | null;
   onboarding?: Onboarding;
   checks?: ReadinessCheck[];
   missing?: Array<{ key: string }>;
diff --git a/frontend/i18n/catalog/en-US.json b/frontend/i18n/catalog/en-US.json
index cee623d1..4967c97f 100644
--- a/frontend/i18n/catalog/en-US.json
+++ b/frontend/i18n/catalog/en-US.json
@@ -4017,8 +4017,8 @@
     "enterpriseCore.setup.accounting.startDate": "Start date",
     "enterpriseCore.setup.accounting.endDate": "End date",
     "enterpriseCore.setup.accounting.createPeriod": "Create fiscal period",
-    "enterpriseCore.setup.scope.title": "3. Working unit and operating context",
-    "enterpriseCore.setup.scope.description": "Select the organizational unit in which the user will work and link its cost center, profit center, warehouse, and POS terminal.",
+    "enterpriseCore.setup.scope.title": "Operating links",
+    "enterpriseCore.setup.scope.description": "Maintain the default operating relationship between an existing unit, a cost center, and an existing point of sale.",
     "enterpriseCore.setup.scope.workingUnit": "Working organizational unit",
     "enterpriseCore.setup.scope.costCenter": "Cost center",
     "enterpriseCore.setup.scope.profitCenter": "Profit center",
@@ -4027,6 +4027,11 @@
     "enterpriseCore.setup.scope.posCode": "POS terminal code",
     "enterpriseCore.setup.scope.posName": "POS terminal name",
     "enterpriseCore.setup.scope.save": "Save operating context",
+    "enterpriseCore.setup.scope.pointOfSale": "Point of sale",
+    "enterpriseCore.setup.scope.contextHelper": "Link an existing operating unit to its cost center and point of sale. Profit-center ownership remains on the organizational unit and is not entered again here.",
+    "enterpriseCore.setup.scope.workingUnitCode": "Operating unit code",
+    "enterpriseCore.setup.scope.workingUnitName": "Operating unit name",
+    "enterpriseCore.setup.scope.saveWorkingUnit": "Save unit details",
     "enterpriseCore.setup.createdSuccessfully": "Configuration saved successfully.",
     "enterpriseCore.setup.failedToLoad": "Unable to load configuration data.",
     "enterpriseCore.setup.failedToSave": "Unable to save configuration. Review the required fields and structural links.",
diff --git a/frontend/i18n/catalog/source.json b/frontend/i18n/catalog/source.json
index 37d552e0..c70f16a0 100644
--- a/frontend/i18n/catalog/source.json
+++ b/frontend/i18n/catalog/source.json
@@ -58324,6 +58324,36 @@
       "classification": "user-facing",
       "occurrences": []
     },
+    {
+      "id": "enterpriseCore.setup.scope.pointOfSale",
+      "source": "نقطة البيع",
+      "classification": "user-facing",
+      "occurrences": []
+    },
+    {
+      "id": "enterpriseCore.setup.scope.contextHelper",
+      "source": "اربط وحدة تشغيل قائمة بمركز التكلفة ونقطة البيع. يبقى مركز الربح ضمن إعداد الوحدة التنظيمية ولا يعاد إدخاله هنا.",
+      "classification": "user-facing",
+      "occurrences": []
+    },
+    {
+      "id": "enterpriseCore.setup.scope.workingUnitCode",
+      "source": "رمز وحدة التشغيل",
+      "classification": "user-facing",
+      "occurrences": []
+    },
+    {
+      "id": "enterpriseCore.setup.scope.workingUnitName",
+      "source": "اسم وحدة التشغيل",
+      "classification": "user-facing",
+      "occurrences": []
+    },
+    {
+      "id": "enterpriseCore.setup.scope.saveWorkingUnit",
+      "source": "حفظ تفاصيل الوحدة",
+      "classification": "user-facing",
+      "occurrences": []
+    },
     {
       "id": "enterpriseCore.setup.scope.title",
       "source": "٣. وحدة العمل وسياق التشغيل",
diff --git a/frontend/lib/i18n/catalog/ar-SA.ts b/frontend/lib/i18n/catalog/ar-SA.ts
index a53ff4f2..9e44b96a 100644
--- a/frontend/lib/i18n/catalog/ar-SA.ts
+++ b/frontend/lib/i18n/catalog/ar-SA.ts
@@ -4098,8 +4098,8 @@ export const arCatalog = {
     "enterpriseCore.setup.accounting.startDate": "تاريخ البداية",
     "enterpriseCore.setup.accounting.endDate": "تاريخ النهاية",
     "enterpriseCore.setup.accounting.createPeriod": "إنشاء فترة مالية",
-    "enterpriseCore.setup.scope.title": "٣. وحدة العمل وسياق التشغيل",
-    "enterpriseCore.setup.scope.description": "اختر الوحدة التنظيمية التي سيعمل فيها المستخدم، واربط بها مركز التكلفة ومركز الربح والمستودع ونقطة البيع.",
+    "enterpriseCore.setup.scope.title": "روابط التشغيل",
+    "enterpriseCore.setup.scope.description": "أدر العلاقة التشغيلية الافتراضية بين وحدة قائمة ومركز تكلفة ونقطة بيع قائمة.",
     "enterpriseCore.setup.scope.workingUnit": "وحدة العمل التنظيمية",
     "enterpriseCore.setup.scope.costCenter": "مركز التكلفة",
     "enterpriseCore.setup.scope.profitCenter": "مركز الربح",
@@ -4108,6 +4108,11 @@ export const arCatalog = {
     "enterpriseCore.setup.scope.posCode": "رمز نقطة البيع",
     "enterpriseCore.setup.scope.posName": "اسم نقطة البيع",
     "enterpriseCore.setup.scope.save": "حفظ سياق التشغيل",
+    "enterpriseCore.setup.scope.pointOfSale": "نقطة البيع",
+    "enterpriseCore.setup.scope.contextHelper": "اربط وحدة تشغيل قائمة بمركز التكلفة ونقطة البيع. يبقى مركز الربح ضمن إعداد الوحدة التنظيمية ولا يعاد إدخاله هنا.",
+    "enterpriseCore.setup.scope.workingUnitCode": "رمز وحدة التشغيل",
+    "enterpriseCore.setup.scope.workingUnitName": "اسم وحدة التشغيل",
+    "enterpriseCore.setup.scope.saveWorkingUnit": "حفظ تفاصيل الوحدة",
     "enterpriseCore.setup.createdSuccessfully": "تم حفظ التهيئة بنجاح.",
     "enterpriseCore.setup.failedToLoad": "تعذر تحميل بيانات التهيئة.",
     "enterpriseCore.setup.failedToSave": "تعذر حفظ التهيئة. راجع الحقول المطلوبة والروابط الهيكلية.",
diff --git a/frontend/lib/i18n/catalog/en-US.ts b/frontend/lib/i18n/catalog/en-US.ts
index 03217372..0e1f0e6c 100644
--- a/frontend/lib/i18n/catalog/en-US.ts
+++ b/frontend/lib/i18n/catalog/en-US.ts
@@ -4098,8 +4098,8 @@ export const enCatalog = {
     "enterpriseCore.setup.accounting.startDate": "Start date",
     "enterpriseCore.setup.accounting.endDate": "End date",
     "enterpriseCore.setup.accounting.createPeriod": "Create fiscal period",
-    "enterpriseCore.setup.scope.title": "3. Working unit and operating context",
-    "enterpriseCore.setup.scope.description": "Select the organizational unit in which the user will work and link its cost center, profit center, warehouse, and POS terminal.",
+    "enterpriseCore.setup.scope.title": "Operating links",
+    "enterpriseCore.setup.scope.description": "Maintain the default operating relationship between an existing unit, a cost center, and an existing point of sale.",
     "enterpriseCore.setup.scope.workingUnit": "Working organizational unit",
     "enterpriseCore.setup.scope.costCenter": "Cost center",
     "enterpriseCore.setup.scope.profitCenter": "Profit center",
@@ -4108,6 +4108,11 @@ export const enCatalog = {
     "enterpriseCore.setup.scope.posCode": "POS terminal code",
     "enterpriseCore.setup.scope.posName": "POS terminal name",
     "enterpriseCore.setup.scope.save": "Save operating context",
+    "enterpriseCore.setup.scope.pointOfSale": "Point of sale",
+    "enterpriseCore.setup.scope.contextHelper": "Link an existing operating unit to its cost center and point of sale. Profit-center ownership remains on the organizational unit and is not entered again here.",
+    "enterpriseCore.setup.scope.workingUnitCode": "Operating unit code",
+    "enterpriseCore.setup.scope.workingUnitName": "Operating unit name",
+    "enterpriseCore.setup.scope.saveWorkingUnit": "Save unit details",
     "enterpriseCore.setup.createdSuccessfully": "Configuration saved successfully.",
     "enterpriseCore.setup.failedToLoad": "Unable to load configuration data.",
     "enterpriseCore.setup.failedToSave": "Unable to save configuration. Review the required fields and structural links.",
diff --git a/frontend/tests/app/setup-onboarding.test.ts b/frontend/tests/app/setup-onboarding.test.ts
index 22ada260..d0fc4bdf 100644
--- a/frontend/tests/app/setup-onboarding.test.ts
+++ b/frontend/tests/app/setup-onboarding.test.ts
@@ -16,18 +16,39 @@ describe("standalone phased setup onboarding", () => {
     expect(layout).toContain("setup_required");
   });
 
-  it("renders mandatory phase progress before gated module activation", () => {
+  it("renders one guarded guided-setup journey before optional capability activation", () => {
     const page = source("app/setup/page.tsx");
     const moduleSelection = source("app/setup/components/SetupModuleSelection.tsx");
+    const journey = source("app/setup/components/SetupJourneyStepper.tsx");
 
-    expect(page.indexOf("<SetupPhaseProgress")).toBeLessThan(page.indexOf("<SetupModuleSelection"));
-    expect(page).toContain("foundationComplete={onboarding?.phases.foundation.ready === true}");
+    expect(page.indexOf("<SetupJourneyStepper")).toBeLessThan(page.indexOf("<SetupModuleSelection"));
+    expect(page).toContain("journeyStep");
+    expect(page).toContain("optional_capabilities");
+    expect(journey).toContain("onPrevious");
+    expect(journey).toContain("onNext");
     expect(moduleSelection).toContain("coreModuleKeys");
     expect(moduleSelection).toContain("canActivate");
-    expect(moduleSelection).toContain("coreTitle");
+    expect(moduleSelection).toContain("setup-module-group-included");
     expect(moduleSelection).toContain("optionalTitle");
   });
 
+  it("refreshes readiness after every successful save and edits existing operating links instead of recreating resources", () => {
+    const page = source("app/setup/page.tsx");
+    const scope = source("app/setup/components/SetupOperatingScopeSection.tsx");
+    const accounting = source("app/setup/components/SetupAccountingSection.tsx");
+    const englishCatalog = source("lib/i18n/catalog/en-US.ts");
+
+    expect(page).toContain("await load();");
+    expect(page).toContain("pos_terminal_id: posTerminalId");
+    expect(page).toContain("saveWorkingUnit");
+    expect(scope).toContain("posTerminalId");
+    expect(scope).not.toContain("warehouseCode");
+    expect(scope).not.toContain("profitCenterId");
+    expect(accounting).toContain("chartReady");
+    expect(accounting).toContain("periodReady");
+    expect(englishCatalog).toContain("Profit-center ownership remains on the organizational unit");
+  });
+
   it("uses the professional organizational architecture workspace rather than the flat node form", () => {
     const page = source("app/setup/page.tsx");
     const workspace = source("app/setup/components/OrganizationArchitectureWorkspace.tsx");

From b2828a3d5e2e0577f36d3205eedc0b238a879a21 Mon Sep 17 00:00:00 2001
From: Emran025 <1.48263577e+08+Emran025@users.noreply.github.com>
Date: Sat, 22 Aug 2026 00:42:43 +0000
Subject: [PATCH 5/9] fix(setup): harden organizational relationships and
 operating context

---
 .../Actions/CreateStructureNodeAction.php     |   3 +-
 .../Actions/UpdateStructureNodeAction.php     |  45 ++--
 .../Models/StructureLink.php                  |   8 +-
 .../Services/OperatingContextService.php      |  85 +++-----
 .../Services/OrgStructureService.php          | 197 +++++++++++++++---
 .../ConfigureOperatingContextRequest.php      |  20 +-
 .../StoreNodeRequest.php                      |   7 +
 .../Feature/Api/OperatingContextApiTest.php   |  36 +++-
 .../Feature/Api/OrgStructureSafetyTest.php    | 146 +++++++++++++
 .../tests/Feature/Api/SetupStateApiTest.php   |  26 ++-
 docs/Plans/setup-safety-audit-status.md       |  31 +++
 frontend/app/globals.css                      |   6 +
 .../OrganizationArchitectureWorkspace.tsx     | 134 +++++++++---
 .../components/organizationWorkspace.types.ts |   6 +-
 frontend/scripts/i18n-inventory.ts            |   1 +
 frontend/tests/app/setup-onboarding.test.ts   |   4 +-
 16 files changed, 601 insertions(+), 154 deletions(-)
 create mode 100644 backend/tests/Feature/Api/OrgStructureSafetyTest.php
 create mode 100644 docs/Plans/setup-safety-audit-status.md

diff --git a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Actions/CreateStructureNodeAction.php b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Actions/CreateStructureNodeAction.php
index c48824f3..3f47c16c 100644
--- a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Actions/CreateStructureNodeAction.php
+++ b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Actions/CreateStructureNodeAction.php
@@ -20,7 +20,8 @@ public function execute(array $data): StructureNode
             throw new \Exception('A node with this type and code already exists.', 422);
         }
 
-        $result = $this->orgService->createNodeWithLink($data, $data['link'] ?? null);
+        $links = $data['links'] ?? (isset($data['link']) ? [$data['link']] : []);
+        $result = $this->orgService->createNodeWithLinks($data, $links);
         $node = $result['node'];
 
         // The configuration workflow owns the organization first. When the
diff --git a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Actions/UpdateStructureNodeAction.php b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Actions/UpdateStructureNodeAction.php
index 57f18517..a04d4185 100644
--- a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Actions/UpdateStructureNodeAction.php
+++ b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Actions/UpdateStructureNodeAction.php
@@ -3,31 +3,52 @@
 
 use App\Domains\Shared\Actions\Action;
 use App\Domains\EnterpriseCore\OrganizationGovernance\Models\StructureNode;
+use App\Domains\EnterpriseCore\OrganizationGovernance\Services\OrgIntegrationService;
 use App\Domains\EnterpriseCore\OrganizationGovernance\Services\OrgStructureService;
-use Illuminate\Http\JsonResponse;
-use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
 
 class UpdateStructureNodeAction
 {
     public function __construct(
-        private readonly OrgStructureService $orgService
+        private readonly OrgStructureService $orgService,
+        private readonly OrgIntegrationService $orgIntegration,
     ) {}
 
     public function execute(string $uuid, array $data): StructureNode
     {
-        $node = StructureNode::where('node_uuid', $uuid)->firstOrFail();
+        return DB::transaction(function () use ($uuid, $data) {
+            $node = StructureNode::where('node_uuid', $uuid)->lockForUpdate()->firstOrFail();
 
-        if (isset($data['code']) && $data['code'] !== $node->code) {
-            if (StructureNode::where('node_type_id', $node->node_type_id)->where('code', $data['code'])->exists()) {
-                throw new \Exception('A node with this type and code already exists.', 422);
+            if (isset($data['code']) && $data['code'] !== $node->code) {
+                if (StructureNode::where('node_type_id', $node->node_type_id)->where('code', $data['code'])->where('node_uuid', '!=', $uuid)->exists()) {
+                    throw new \Exception('A node with this type and code already exists.', 422);
+                }
             }
-        }
 
-        $oldValues = $node->toArray();
-        $node->update(array_merge($data, ['updated_by' => auth()->id()]));
+            $oldValues = $node->toArray();
+            $mergedAttributes = array_merge($node->attributes_json ?? [], $data['attributes'] ?? []);
+            $normalizedAttributes = $this->orgService->normalizeAndValidateNodeAttributes($node->node_type_id, $mergedAttributes);
+            $node->update([
+                'code' => $data['code'] ?? $node->code,
+                'attributes_json' => $normalizedAttributes,
+                'status' => $data['status'] ?? $node->status,
+                'valid_from' => array_key_exists('valid_from', $data) ? $data['valid_from'] : $node->valid_from,
+                'valid_to' => array_key_exists('valid_to', $data) ? $data['valid_to'] : $node->valid_to,
+                'updated_by' => auth()->id(),
+            ]);
+            $node->load('outgoingLinks.targetNode', 'outgoingLinks.topologyRule');
+            $this->orgService->assertActiveParentConstraints($node, $node->outgoingLinks->filter->isActive());
 
-        $this->orgService->recordChange('node', $uuid, 'updated', $oldValues, $node->fresh()->toArray());
+            if ($node->node_type_id === 'COST_CENTER') {
+                $this->orgIntegration->syncOrgNodeToCostCenter($node);
+            }
+            if ($node->node_type_id === 'PROFIT_CENTER') {
+                $this->orgIntegration->syncOrgNodeToProfitCenter($node);
+            }
+
+            $this->orgService->recordChange('node', $uuid, 'updated', $oldValues, $node->fresh()->toArray());
 
-        return $node->fresh('metaType');
+            return $node->fresh('metaType');
+        });
     }
 }
diff --git a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Models/StructureLink.php b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Models/StructureLink.php
index 7efef42e..aa78aaa2 100644
--- a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Models/StructureLink.php
+++ b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Models/StructureLink.php
@@ -50,9 +50,9 @@ public function topologyRule(): BelongsTo
 
     public function isActive(): bool
     {
-        if ($this->valid_to === null) {
-            return true;
-        }
-        return $this->valid_to->isFuture();
+        $today = now()->startOfDay();
+
+        return ($this->valid_from === null || $this->valid_from->lte($today))
+            && ($this->valid_to === null || $this->valid_to->gte($today));
     }
 }
diff --git a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OperatingContextService.php b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OperatingContextService.php
index 3e1d8c41..1f0a70be 100644
--- a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OperatingContextService.php
+++ b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OperatingContextService.php
@@ -5,10 +5,8 @@
 use App\Domains\Commercial\SalesLifecycle\Models\PosTerminal;
 use App\Domains\EnterpriseCore\OrganizationGovernance\Models\OperatingContext;
 use App\Domains\Finance\ManagementAccounting\Models\CostCenter;
-use App\Domains\Finance\ManagementAccounting\Models\ProfitCenter;
-use App\Domains\SupplyChain\Inventory\Models\Warehouse;
-use Illuminate\Support\Arr;
 use Illuminate\Support\Facades\DB;
+use Illuminate\Validation\ValidationException;
 
 class OperatingContextService
 {
@@ -68,57 +66,38 @@ public function readiness(?int $userId): array
     public function configure(array $data, ?int $userId): OperatingContext
     {
         return DB::transaction(function () use ($data, $userId) {
-            $terminal = isset($data['pos_terminal_id'])
-                ? PosTerminal::query()
-                    ->whereKey($data['pos_terminal_id'])
-                    ->where('is_active', true)
-                    ->where('status', 'active')
-                    ->firstOrFail()
-                : null;
+            $costCenter = CostCenter::query()->whereKey($data['cost_center_id'])->where('is_active', true)->first();
+            if (!$costCenter) {
+                throw ValidationException::withMessages(['cost_center_id' => ['The selected cost center must be active.']]);
+            }
+            $terminal = PosTerminal::query()
+                ->whereKey($data['pos_terminal_id'])
+                ->where('is_active', true)
+                ->where('status', 'active')
+                ->firstOrFail();
             $warehouse = $terminal?->warehouse;
 
-            if (!$terminal) {
-                $warehouseData = Arr::get($data, 'warehouse', []);
-                $warehouse = Warehouse::query()->updateOrCreate(
-                    ['code' => $warehouseData['code']],
-                    [
-                        'name' => $warehouseData['name'],
-                        'name_en' => $warehouseData['name_en'] ?? null,
-                        'org_node_uuid' => $data['org_node_uuid'] ?? null,
-                        'cost_center_id' => $data['cost_center_id'] ?? null,
-                        'profit_center_id' => $data['profit_center_id'] ?? null,
-                        'status' => 'active',
-                        'is_active' => true,
-                        'description' => $warehouseData['description'] ?? null,
-                        'created_by' => $userId,
-                    ]
-                );
-                $terminalData = Arr::get($data, 'pos_terminal', []);
-                $terminal = PosTerminal::query()->updateOrCreate(
-                    ['code' => $terminalData['code']],
-                    [
-                        'name' => $terminalData['name'],
-                        'name_en' => $terminalData['name_en'] ?? null,
-                        'org_node_uuid' => $data['org_node_uuid'] ?? null,
-                        'warehouse_id' => $warehouse->id,
-                        'cost_center_id' => $data['cost_center_id'] ?? null,
-                        'profit_center_id' => $data['profit_center_id'] ?? null,
-                        'status' => 'active',
-                        'is_active' => true,
-                        'created_by' => $userId,
-                    ]
-                );
+            if (!$warehouse || !$warehouse->is_active || $warehouse->status !== 'active') {
+                throw ValidationException::withMessages(['pos_terminal_id' => ['The selected POS terminal must belong to an active warehouse.']]);
             }
-
-            $terminal->update([
-                'org_node_uuid' => $data['org_node_uuid'] ?? null,
-                'cost_center_id' => $data['cost_center_id'] ?? null,
-            ]);
-            if ($warehouse) {
-                $warehouse->update([
-                    'org_node_uuid' => $data['org_node_uuid'] ?? null,
-                    'cost_center_id' => $data['cost_center_id'] ?? null,
-                ]);
+            if ($terminal->org_node_uuid !== $data['org_node_uuid'] || $warehouse->org_node_uuid !== $data['org_node_uuid']) {
+                throw ValidationException::withMessages(['pos_terminal_id' => ['The selected POS terminal and warehouse must already belong to the chosen operating unit.']]);
+            }
+            if ($terminal->cost_center_id !== $costCenter->id || $warehouse->cost_center_id !== $costCenter->id) {
+                throw ValidationException::withMessages(['cost_center_id' => ['The selected POS terminal and warehouse must already be assigned to the selected active cost center.']]);
+            }
+            $sharedWithAnotherUser = OperatingContext::query()
+                ->where('pos_terminal_id', $terminal->id)
+                ->where(function ($query) use ($userId) {
+                    if ($userId === null) {
+                        $query->whereNotNull('user_id');
+                    } else {
+                        $query->whereNull('user_id')->orWhere('user_id', '!=', $userId);
+                    }
+                })
+                ->exists();
+            if ($sharedWithAnotherUser) {
+                throw ValidationException::withMessages(['pos_terminal_id' => ['The selected POS terminal is already assigned to another user context.']]);
             }
 
             OperatingContext::query()
@@ -127,12 +106,12 @@ public function configure(array $data, ?int $userId): OperatingContext
                 ->update(['is_default' => false]);
 
             $context = OperatingContext::query()->updateOrCreate(
-                ['user_id' => $userId, 'pos_terminal_id' => $terminal->id],
+                ['user_id' => $userId, 'org_node_uuid' => $data['org_node_uuid']],
                 [
                     'org_node_uuid' => $data['org_node_uuid'] ?? null,
                     'warehouse_id' => $warehouse?->id,
                     'cost_center_id' => $data['cost_center_id'] ?? null,
-                    'profit_center_id' => $data['profit_center_id'] ?? $terminal->profit_center_id,
+                    'profit_center_id' => $terminal->profit_center_id,
                     // Status is recalculated from the authoritative readiness
                     // contract below; configuration submission is never proof of readiness.
                     'status' => 'draft',
diff --git a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OrgStructureService.php b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OrgStructureService.php
index bac464b2..33477e09 100644
--- a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OrgStructureService.php
+++ b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OrgStructureService.php
@@ -169,6 +169,138 @@ public function validateNodeAttributes(string $nodeTypeId, array $attributes): v
         }
     }
 
+    /**
+     * Apply metadata defaults and primitive type/rule validation before the
+     * existing domain-specific validation is evaluated.
+     *
+     * @return array<string, mixed>
+     * @throws ValidationException
+     */
+    public function normalizeAndValidateNodeAttributes(string $nodeTypeId, array $attributes): array
+    {
+        $metaType = OrgMetaType::findOrFail($nodeTypeId);
+        $normalized = $attributes;
+        $errors = [];
+
+        foreach ($metaType->attributes()->orderBy('sort_order')->get() as $definition) {
+            $key = $definition->attribute_key;
+            $value = data_get($normalized, $key);
+            if (($value === null || $value === '') && $definition->default_value !== null && $definition->default_value !== '') {
+                $value = $definition->default_value;
+            }
+            if ($value === null || $value === '') {
+                continue;
+            }
+
+            $type = $definition->attribute_type ?: 'string';
+            if ($type === 'integer') {
+                if (filter_var($value, FILTER_VALIDATE_INT) === false) {
+                    $errors[] = "Attribute '{$key}' must be an integer.";
+                    continue;
+                }
+                $value = (int) $value;
+            } elseif ($type === 'decimal') {
+                if (!is_numeric($value)) {
+                    $errors[] = "Attribute '{$key}' must be a decimal number.";
+                    continue;
+                }
+                $value = (float) $value;
+            } elseif ($type === 'boolean') {
+                $value = filter_var($value, FILTER_VALIDATE_BOOL, FILTER_NULL_ON_FAILURE);
+                if ($value === null) {
+                    $errors[] = "Attribute '{$key}' must be a boolean.";
+                    continue;
+                }
+            } elseif ($type === 'json') {
+                if (is_string($value)) {
+                    $value = json_decode($value, true);
+                }
+                if (!is_array($value)) {
+                    $errors[] = "Attribute '{$key}' must be a JSON object or array.";
+                    continue;
+                }
+            } elseif ($type === 'date') {
+                try {
+                    $value = \Carbon\Carbon::parse((string) $value)->toDateString();
+                } catch (\Throwable) {
+                    $errors[] = "Attribute '{$key}' must be a valid date.";
+                    continue;
+                }
+            } elseif (!is_scalar($value)) {
+                $errors[] = "Attribute '{$key}' must be a scalar value.";
+                continue;
+            } else {
+                $value = trim((string) $value);
+            }
+
+            $rule = $definition->validation_rule ?? [];
+            if (isset($rule['enum']) && !in_array($value, (array) $rule['enum'], true)) {
+                $errors[] = "Attribute '{$key}' is not an allowed value.";
+            }
+            if (isset($rule['min']) && is_numeric($value) && $value < $rule['min']) {
+                $errors[] = "Attribute '{$key}' is below the allowed minimum.";
+            }
+            if (isset($rule['max']) && is_numeric($value) && $value > $rule['max']) {
+                $errors[] = "Attribute '{$key}' exceeds the allowed maximum.";
+            }
+            if (isset($rule['regex']) && is_string($value) && @preg_match($rule['regex'], $value) !== 1) {
+                $errors[] = "Attribute '{$key}' does not match the required format.";
+            }
+            data_set($normalized, $key, $value);
+        }
+
+        if ($nodeTypeId === 'COMP_CODE' && empty(data_get($normalized, 'country_code'))) {
+            $errors[] = 'A Company Code country or region is required before plant assignment can be validated.';
+        }
+        if (!empty($errors)) {
+            throw ValidationException::withMessages(['attributes' => $errors]);
+        }
+
+        $this->validateNodeAttributes($nodeTypeId, $normalized);
+
+        return $normalized;
+    }
+
+    /** @return string[] */
+    private function requiredParentTypes(string $nodeTypeId): array
+    {
+        return [
+            'COMP_CODE' => ['CLIENT'],
+            'CONTROLLING_AREA' => ['COMP_CODE'],
+            'COST_CENTER' => ['CONTROLLING_AREA'],
+            'PROFIT_CENTER' => ['CONTROLLING_AREA'],
+            'PLANT' => ['COMP_CODE'],
+            'STORAGE_LOC' => ['PLANT'],
+            'PURCH_ORG' => ['COMP_CODE'],
+            'SALES_ORG' => ['COMP_CODE'],
+            'PERSONNEL_AREA' => ['COMP_CODE'],
+        ][$nodeTypeId] ?? [];
+    }
+
+    /** @param iterable<StructureLink> $links */
+    public function assertActiveParentConstraints(StructureNode $node, iterable $links): void
+    {
+        $activeLinks = collect($links)->filter(fn (StructureLink $link) => $link->isActive());
+        $parentTypes = $activeLinks
+            ->map(fn (StructureLink $link) => $link->targetNode?->node_type_id)
+            ->filter()
+            ->unique()
+            ->all();
+        $missing = array_values(array_diff($this->requiredParentTypes($node->node_type_id), $parentTypes));
+
+        if ($missing !== []) {
+            throw ValidationException::withMessages([
+                'links' => ['Missing required active relationship(s): '.implode(', ', $missing).'.'],
+            ]);
+        }
+
+        foreach ($activeLinks as $link) {
+            if ($link->targetNode && $link->topologyRule) {
+                $this->evaluateConstraintLogic($link->topologyRule, $node, $link->targetNode);
+            }
+        }
+    }
+
     // ─── Topology & Cardinality ─────────────────────────────────────────
 
     /**
@@ -221,7 +353,11 @@ public function enforceCardinality(TopologyRule $rule, string $sourceUuid, strin
         $cardinality = $rule->cardinality; // 1:1, 1:N, N:1, N:M
 
         $activeFilter = function ($q) {
-            $q->whereNull('valid_to')->orWhere('valid_to', '>=', now()->toDateString());
+            $q->where(function ($query) {
+                $query->whereNull('valid_from')->orWhere('valid_from', '<=', now()->toDateString());
+            })->where(function ($query) {
+                $query->whereNull('valid_to')->orWhere('valid_to', '>=', now()->toDateString());
+            });
         };
 
         // Check LEFT side cardinality (source)
@@ -262,49 +398,51 @@ public function enforceCardinality(TopologyRule $rule, string $sourceUuid, strin
     // ─── Node + Link Creation ───────────────────────────────────────────
 
     /**
-     * Create a node with optional link to a target (create_with_link flow).
-     * @return array{node: StructureNode, link: ?StructureLink}
+     * Backward-compatible single-link wrapper.
+     * @return array{node: StructureNode, link: ?StructureLink, links: array<int, StructureLink>}
      */
     public function createNodeWithLink(array $nodeData, ?array $linkData = null): array
     {
-        return DB::transaction(function () use ($nodeData, $linkData) {
-            $this->validateNodeAttributes(
-                $nodeData['node_type_id'],
-                $nodeData['attributes'] ?? []
-            );
+        return $this->createNodeWithLinks($nodeData, $linkData ? [$linkData] : []);
+    }
 
+    /**
+     * Create a node and all its selected relationships atomically.
+     * @return array{node: StructureNode, link: ?StructureLink, links: array<int, StructureLink>}
+     */
+    public function createNodeWithLinks(array $nodeData, array $linksData = []): array
+    {
+        return DB::transaction(function () use ($nodeData, $linksData) {
+            $attributes = $this->normalizeAndValidateNodeAttributes($nodeData['node_type_id'], $nodeData['attributes'] ?? []);
             $node = StructureNode::create([
                 'node_type_id' => $nodeData['node_type_id'],
                 'code' => $nodeData['code'],
-                'attributes_json' => $nodeData['attributes'] ?? [],
+                'attributes_json' => $attributes,
                 'status' => $nodeData['status'] ?? 'active',
                 'valid_from' => $nodeData['valid_from'] ?? null,
                 'valid_to' => $nodeData['valid_to'] ?? null,
                 'created_by' => auth()->id(),
                 'updated_by' => auth()->id(),
             ]);
-
-            // Record change history
             $this->recordChange('node', $node->node_uuid, 'created', null, $node->toArray());
 
-            $link = null;
-
-            if ($linkData && !empty($linkData['target_node_uuid'])) {
+            $links = [];
+            $targetUuids = [];
+            foreach ($linksData as $linkData) {
+                if (empty($linkData['target_node_uuid'])) continue;
+                if (in_array($linkData['target_node_uuid'], $targetUuids, true)) {
+                    throw ValidationException::withMessages(['links' => ['A target can be linked only once during node creation.']]);
+                }
+                $targetUuids[] = $linkData['target_node_uuid'];
                 $target = StructureNode::findOrFail($linkData['target_node_uuid']);
                 $rule = $this->findTopologyRule($node->node_type_id, $target->node_type_id);
-
                 if (!$rule) {
-                    throw ValidationException::withMessages([
-                        'link' => ['No topology rule exists for this source->target relationship.'],
-                    ]);
+                    throw ValidationException::withMessages(['links' => ['No topology rule exists for this source-to-target relationship.']]);
                 }
-
                 $this->enforceCardinality($rule, $node->node_uuid, $target->node_uuid);
-
-                if (!empty($linkData['validate_constraints'])) {
+                if (($linkData['validate_constraints'] ?? true) === true) {
                     $this->evaluateConstraintLogic($rule, $node, $target);
                 }
-
                 $link = StructureLink::create([
                     'source_node_uuid' => $node->node_uuid,
                     'target_node_uuid' => $target->node_uuid,
@@ -315,11 +453,14 @@ public function createNodeWithLink(array $nodeData, ?array $linkData = null): ar
                     'valid_to' => $linkData['valid_to'] ?? null,
                     'created_by' => auth()->id(),
                 ]);
-
+                $link->setRelation('targetNode', $target)->setRelation('topologyRule', $rule);
                 $this->recordChange('link', (string) $link->id, 'created', null, $link->toArray());
+                $links[] = $link;
             }
 
-            return ['node' => $node->fresh(['metaType']), 'link' => $link ? $link->fresh() : null];
+            $this->assertActiveParentConstraints($node, $links);
+
+            return ['node' => $node->fresh(['metaType']), 'link' => $links[0] ?? null, 'links' => $links];
         });
     }
 
@@ -346,6 +487,9 @@ public function createLink(string $sourceUuid, string $targetUuid, array $data =
         $exists = StructureLink::where('source_node_uuid', $sourceUuid)
             ->where('target_node_uuid', $targetUuid)
             ->where('link_type', $data['link_type'] ?? 'assignment')
+            ->where(function ($q) {
+                $q->whereNull('valid_from')->orWhere('valid_from', '<=', now()->toDateString());
+            })
             ->where(function ($q) {
                 $q->whereNull('valid_to')->orWhere('valid_to', '>=', now()->toDateString());
             })
@@ -417,6 +561,9 @@ public function resolveScopeContext(string $anchorNodeUuid): array
             ];
 
             $parents = StructureLink::where('source_node_uuid', $current->node_uuid)
+                ->where(function ($q) {
+                    $q->whereNull('valid_from')->orWhere('valid_from', '<=', now()->toDateString());
+                })
                 ->where(function ($q) {
                     $q->whereNull('valid_to')->orWhere('valid_to', '>=', now()->toDateString());
                 })
@@ -565,7 +712,7 @@ public function runIntegrityCheck(): array
             if (!isset($requiredParentMap[$node->node_type_id])) continue;
             $requiredTarget = $requiredParentMap[$node->node_type_id];
             $hasRequiredLink = $node->outgoingLinks->contains(function ($link) use ($requiredTarget) {
-                return $link->targetNode && $link->targetNode->node_type_id === $requiredTarget;
+                return $link->isActive() && $link->targetNode && $link->targetNode->node_type_id === $requiredTarget;
             });
 
             if (!$hasRequiredLink) {
diff --git a/backend/app/Http/Requests/EnterpriseCore/OrganizationGovernance/ConfigureOperatingContextRequest.php b/backend/app/Http/Requests/EnterpriseCore/OrganizationGovernance/ConfigureOperatingContextRequest.php
index cec96fee..17f8ea94 100644
--- a/backend/app/Http/Requests/EnterpriseCore/OrganizationGovernance/ConfigureOperatingContextRequest.php
+++ b/backend/app/Http/Requests/EnterpriseCore/OrganizationGovernance/ConfigureOperatingContextRequest.php
@@ -16,17 +16,10 @@ public function rules(): array
         return [
             'org_node_uuid' => 'required|exists:structure_nodes,node_uuid',
             'cost_center_id' => 'required|exists:cost_centers,id',
-            'pos_terminal_id' => 'required_without:pos_terminal|nullable|exists:pos_terminals,id',
-            'profit_center_id' => 'nullable|exists:profit_centers,id',
-            'warehouse' => 'required_with:pos_terminal|array',
-            'warehouse.code' => 'required_with:pos_terminal|string|max:30',
-            'warehouse.name' => 'required_with:pos_terminal|string|max:255',
-            'warehouse.name_en' => 'nullable|string|max:255',
-            'warehouse.description' => 'nullable|string',
-            'pos_terminal' => 'required_without:pos_terminal_id|array',
-            'pos_terminal.code' => 'required_without:pos_terminal_id|string|max:30',
-            'pos_terminal.name' => 'required_without:pos_terminal_id|string|max:255',
-            'pos_terminal.name_en' => 'nullable|string|max:255',
+            'pos_terminal_id' => 'required|exists:pos_terminals,id',
+            'profit_center_id' => 'prohibited',
+            'warehouse' => 'prohibited',
+            'pos_terminal' => 'prohibited',
         ];
     }
 
@@ -35,8 +28,9 @@ public function messages(): array
         return [
             'org_node_uuid.required' => 'An organizational unit must be selected before configuring the operating context.',
             'cost_center_id.required' => 'An active cost center must be selected.',
-            'pos_terminal_id.required_without' => 'Select an existing active POS terminal or provide a new terminal configuration.',
-            'pos_terminal.required_without' => 'Select an existing active POS terminal or provide a new terminal configuration.',
+            'pos_terminal_id.required' => 'Select an existing active POS terminal already assigned to the chosen operating unit.',
+            'warehouse.prohibited' => 'Create warehouses through the scoped logistics master-data workflow, not through operating-context configuration.',
+            'pos_terminal.prohibited' => 'Create POS terminals through the scoped sales master-data workflow, not through operating-context configuration.',
         ];
     }
 }
diff --git a/backend/app/Http/Requests/EnterpriseCore/OrganizationGovernance/StoreNodeRequest.php b/backend/app/Http/Requests/EnterpriseCore/OrganizationGovernance/StoreNodeRequest.php
index 1b2bb978..8e618b5b 100644
--- a/backend/app/Http/Requests/EnterpriseCore/OrganizationGovernance/StoreNodeRequest.php
+++ b/backend/app/Http/Requests/EnterpriseCore/OrganizationGovernance/StoreNodeRequest.php
@@ -24,6 +24,13 @@ public function rules(): array
             'link.target_node_uuid'     => 'nullable|uuid|exists:structure_nodes,node_uuid',
             'link.link_type'            => 'nullable|string|max:32',
             'link.validate_constraints' => 'nullable|boolean',
+            'links'                     => 'nullable|array',
+            'links.*.target_node_uuid'  => 'required|uuid|distinct|exists:structure_nodes,node_uuid',
+            'links.*.link_type'         => 'nullable|string|max:32',
+            'links.*.priority'          => 'nullable|integer|min:0',
+            'links.*.valid_from'        => 'nullable|date',
+            'links.*.valid_to'          => 'nullable|date|after_or_equal:links.*.valid_from',
+            'links.*.validate_constraints' => 'nullable|boolean',
         ];
     }
 }
diff --git a/backend/tests/Feature/Api/OperatingContextApiTest.php b/backend/tests/Feature/Api/OperatingContextApiTest.php
index 8c64d6d3..f0721fd9 100644
--- a/backend/tests/Feature/Api/OperatingContextApiTest.php
+++ b/backend/tests/Feature/Api/OperatingContextApiTest.php
@@ -9,6 +9,8 @@
 use App\Domains\Finance\GeneralLedger\Models\FiscalPeriod;
 use App\Domains\Finance\ManagementAccounting\Models\CostCenter;
 use App\Domains\Finance\ManagementAccounting\Models\ProfitCenter;
+use App\Domains\SupplyChain\Inventory\Models\Warehouse;
+use App\Domains\Commercial\SalesLifecycle\Models\PosTerminal;
 use Illuminate\Foundation\Testing\RefreshDatabase;
 use Illuminate\Support\Facades\DB;
 use Tests\TestCase;
@@ -102,18 +104,30 @@ public function test_can_configure_a_ready_operating_context_only_after_structur
             ]);
         }
 
-        $response = $this->authPost(route('v2.operating_context.configure'), [
+        $warehouse = Warehouse::create([
+            'code' => 'WH-STORE',
+            'name' => 'Store Warehouse',
+            'org_node_uuid' => $company->node_uuid,
+            'cost_center_id' => $costCenter->id,
+            'profit_center_id' => $profitCenter->id,
+            'status' => 'active',
+            'is_active' => true,
+        ]);
+        $terminal = PosTerminal::create([
+            'code' => 'POS-STORE',
+            'name' => 'Store Counter',
             'org_node_uuid' => $company->node_uuid,
+            'warehouse_id' => $warehouse->id,
             'cost_center_id' => $costCenter->id,
             'profit_center_id' => $profitCenter->id,
-            'warehouse' => [
-                'code' => 'WH-STORE',
-                'name' => 'Store Warehouse',
-            ],
-            'pos_terminal' => [
-                'code' => 'POS-STORE',
-                'name' => 'Store Counter',
-            ],
+            'status' => 'active',
+            'is_active' => true,
+        ]);
+
+        $response = $this->authPost(route('v2.operating_context.configure'), [
+            'org_node_uuid' => $company->node_uuid,
+            'cost_center_id' => $costCenter->id,
+            'pos_terminal_id' => $terminal->id,
         ]);
 
         $this->assertSuccessResponse($response, 201);
@@ -121,8 +135,8 @@ public function test_can_configure_a_ready_operating_context_only_after_structur
             ->assertJsonPath('data.pos_terminal.code', 'POS-STORE')
             ->assertJsonPath('data.status', 'ready');
 
-        $this->assertDatabaseHas('warehouses', ['code' => 'WH-STORE', 'is_active' => true]);
-        $this->assertDatabaseHas('pos_terminals', ['code' => 'POS-STORE', 'is_active' => true]);
+        $this->assertDatabaseHas('warehouses', ['id' => $warehouse->id, 'is_active' => true]);
+        $this->assertDatabaseHas('pos_terminals', ['id' => $terminal->id, 'is_active' => true]);
         $this->assertDatabaseCount('operating_contexts', 1);
 
         $context = OperatingContext::query()->firstOrFail();
diff --git a/backend/tests/Feature/Api/OrgStructureSafetyTest.php b/backend/tests/Feature/Api/OrgStructureSafetyTest.php
new file mode 100644
index 00000000..6ce8922c
--- /dev/null
+++ b/backend/tests/Feature/Api/OrgStructureSafetyTest.php
@@ -0,0 +1,146 @@
+<?php
+
+namespace Tests\Feature\Api;
+
+use App\Domains\EnterpriseCore\OrganizationGovernance\Models\OrgMetaType;
+use App\Domains\EnterpriseCore\OrganizationGovernance\Models\OrgMetaTypeAttribute;
+use App\Domains\EnterpriseCore\OrganizationGovernance\Models\StructureLink;
+use App\Domains\EnterpriseCore\OrganizationGovernance\Models\StructureNode;
+use App\Domains\EnterpriseCore\OrganizationGovernance\Models\TopologyRule;
+use App\Domains\EnterpriseCore\OrganizationGovernance\Services\OrgStructureService;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Validation\ValidationException;
+use Tests\TestCase;
+
+class OrgStructureSafetyTest extends TestCase
+{
+    use RefreshDatabase;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->authenticateUser();
+    }
+
+    public function test_node_creation_persists_multiple_selected_relationships_atomically(): void
+    {
+        foreach (['CLIENT', 'COMP_CODE', 'PLANT', 'PURCH_ORG'] as $type) {
+            OrgMetaType::create([
+                'id' => $type,
+                'display_name' => $type,
+                'display_name_ar' => $type,
+                'level_domain' => 'Enterprise',
+                'is_assignable' => true,
+            ]);
+        }
+        OrgMetaTypeAttribute::create([
+            'org_meta_type_id' => 'COMP_CODE',
+            'attribute_key' => 'country_code',
+            'attribute_type' => 'string',
+            'is_mandatory' => true,
+            'sort_order' => 1,
+        ]);
+        OrgMetaTypeAttribute::create([
+            'org_meta_type_id' => 'PLANT',
+            'attribute_key' => 'country_code',
+            'attribute_type' => 'string',
+            'is_mandatory' => true,
+            'sort_order' => 1,
+        ]);
+
+        foreach ([
+            ['COMP_CODE', 'CLIENT', 'N:1'],
+            ['PLANT', 'COMP_CODE', 'N:1'],
+            ['PURCH_ORG', 'COMP_CODE', 'N:1'],
+            ['PURCH_ORG', 'PLANT', 'N:M'],
+        ] as [$source, $target, $cardinality]) {
+            TopologyRule::create([
+                'source_node_type_id' => $source,
+                'target_node_type_id' => $target,
+                'cardinality' => $cardinality,
+                'link_direction' => 'source_to_target',
+                'is_active' => true,
+                'description' => "{$source} to {$target}",
+            ]);
+        }
+
+        $service = app(OrgStructureService::class);
+        $client = $service->createNodeWithLinks(['node_type_id' => 'CLIENT', 'code' => 'CLIENT-1'], [])['node'];
+        $company = $service->createNodeWithLinks([
+            'node_type_id' => 'COMP_CODE',
+            'code' => '1000',
+            'attributes' => ['country_code' => 'SA'],
+        ], [['target_node_uuid' => $client->node_uuid, 'validate_constraints' => true]])['node'];
+        $plant = $service->createNodeWithLinks([
+            'node_type_id' => 'PLANT',
+            'code' => 'PLANT-1',
+            'attributes' => ['country_code' => 'SA'],
+        ], [['target_node_uuid' => $company->node_uuid, 'validate_constraints' => true]])['node'];
+
+        $result = $service->createNodeWithLinks([
+            'node_type_id' => 'PURCH_ORG',
+            'code' => 'PURCH-1',
+        ], [
+            ['target_node_uuid' => $company->node_uuid, 'validate_constraints' => true],
+            ['target_node_uuid' => $plant->node_uuid, 'validate_constraints' => true],
+        ]);
+
+        $this->assertCount(2, $result['links']);
+        $this->assertDatabaseCount('structure_links', 4);
+    }
+
+    public function test_metadata_validation_rejects_an_invalid_primitive_type(): void
+    {
+        OrgMetaType::create([
+            'id' => 'DEPARTMENT',
+            'display_name' => 'Department',
+            'display_name_ar' => 'Department',
+            'level_domain' => 'Enterprise',
+            'is_assignable' => true,
+        ]);
+        OrgMetaTypeAttribute::create([
+            'org_meta_type_id' => 'DEPARTMENT',
+            'attribute_key' => 'headcount',
+            'attribute_type' => 'integer',
+            'is_mandatory' => true,
+            'sort_order' => 1,
+        ]);
+
+        $this->expectException(ValidationException::class);
+        app(OrgStructureService::class)->normalizeAndValidateNodeAttributes('DEPARTMENT', ['headcount' => 'not-a-number']);
+    }
+
+    public function test_integrity_rejects_an_expired_required_parent_relationship(): void
+    {
+        foreach (['COMP_CODE', 'CLIENT'] as $type) {
+            OrgMetaType::create([
+                'id' => $type,
+                'display_name' => $type,
+                'display_name_ar' => $type,
+                'level_domain' => 'Enterprise',
+                'is_assignable' => true,
+            ]);
+        }
+        $rule = TopologyRule::create([
+            'source_node_type_id' => 'COMP_CODE',
+            'target_node_type_id' => 'CLIENT',
+            'cardinality' => 'N:1',
+            'link_direction' => 'source_to_target',
+            'is_active' => true,
+            'description' => 'Company Code to Client',
+        ]);
+        $client = StructureNode::create(['node_type_id' => 'CLIENT', 'code' => 'CLIENT-1', 'status' => 'active']);
+        $company = StructureNode::create(['node_type_id' => 'COMP_CODE', 'code' => '1000', 'attributes_json' => ['country_code' => 'SA'], 'status' => 'active']);
+        StructureLink::create([
+            'source_node_uuid' => $company->node_uuid,
+            'target_node_uuid' => $client->node_uuid,
+            'topology_rule_id' => $rule->id,
+            'link_type' => 'assignment',
+            'valid_to' => now()->subDay()->toDateString(),
+        ]);
+
+        $issues = app(OrgStructureService::class)->runIntegrityCheck();
+
+        $this->assertTrue(collect($issues)->contains(fn (array $issue) => $issue['category'] === 'missing_parent' && $issue['node_uuid'] === $company->node_uuid));
+    }
+}
diff --git a/backend/tests/Feature/Api/SetupStateApiTest.php b/backend/tests/Feature/Api/SetupStateApiTest.php
index 3b260f58..18f9c407 100644
--- a/backend/tests/Feature/Api/SetupStateApiTest.php
+++ b/backend/tests/Feature/Api/SetupStateApiTest.php
@@ -10,6 +10,8 @@
 use App\Domains\Finance\GeneralLedger\Models\FiscalPeriod;
 use App\Domains\Finance\ManagementAccounting\Models\CostCenter;
 use App\Domains\Finance\ManagementAccounting\Models\ProfitCenter;
+use App\Domains\SupplyChain\Inventory\Models\Warehouse;
+use App\Domains\Commercial\SalesLifecycle\Models\PosTerminal;
 use Illuminate\Foundation\Testing\RefreshDatabase;
 use Illuminate\Support\Facades\DB;
 use Tests\TestCase;
@@ -170,12 +172,30 @@ private function configureTechnologyCommerceBaseline(): void
             ]);
         }
 
-        $configured = $this->authPost(route('v2.operating_context.configure'), [
+        $warehouse = Warehouse::create([
+            'code' => 'TECH-WH',
+            'name' => 'Technology Device Warehouse',
+            'org_node_uuid' => $company->node_uuid,
+            'cost_center_id' => $costCenter->id,
+            'profit_center_id' => $profitCenter->id,
+            'status' => 'active',
+            'is_active' => true,
+        ]);
+        $terminal = PosTerminal::create([
+            'code' => 'TECH-POS',
+            'name' => 'Technology Showroom POS',
             'org_node_uuid' => $company->node_uuid,
+            'warehouse_id' => $warehouse->id,
             'cost_center_id' => $costCenter->id,
             'profit_center_id' => $profitCenter->id,
-            'warehouse' => ['code' => 'TECH-WH', 'name' => 'Technology Device Warehouse'],
-            'pos_terminal' => ['code' => 'TECH-POS', 'name' => 'Technology Showroom POS'],
+            'status' => 'active',
+            'is_active' => true,
+        ]);
+
+        $configured = $this->authPost(route('v2.operating_context.configure'), [
+            'org_node_uuid' => $company->node_uuid,
+            'cost_center_id' => $costCenter->id,
+            'pos_terminal_id' => $terminal->id,
         ]);
 
         $this->assertSuccessResponse($configured, 201);
diff --git a/docs/Plans/setup-safety-audit-status.md b/docs/Plans/setup-safety-audit-status.md
new file mode 100644
index 00000000..04072e45
--- /dev/null
+++ b/docs/Plans/setup-safety-audit-status.md
@@ -0,0 +1,31 @@
+# Setup Safety Audit Status
+
+## Scope and Decision
+
+This record compares the user-supplied **Field and Relationship Safety Audit**—which reviewed `main` at `1f8d95629f00ed3155c806ecdf0d671b1b4a6007`—with `fix/server-desktop-bottom-notification-baseline` after the guided-setup refinements. It is a status record, not a claim that production remediation is complete.
+
+> **Release gate:** the setup workflow must not be presented as safe for multi-organization production use until the two `P0` defects are closed and the affected `P1` contracts are covered by behavioral tests.
+
+| Audit finding | Current-branch status | Evidence and disposition |
+|---|---|---|
+| `P0` — Node creation persists only one parent relationship | **Open** | The workspace still submits one `link` object, the request accepts one `link`, and `createNodeWithLink()` creates at most one relationship. The replacement must use an atomic `links[]` contract and validate all required rules before commit. |
+| `P0` — Global `WH-MAIN` / `POS-MAIN` update path can overwrite another scope | **Partially mitigated; open** | The new setup and hierarchy flows select an existing POS terminal by ID and no longer seed those global default codes. The backward-compatible create path still uses `updateOrCreate` by `code`; it must be scoped or separated into an explicit, safely identified resource-creation flow. |
+| `P1` — Metadata type, rule, default, and reference contracts are not enforced end-to-end | **Open** | The service checks mandatory presence plus a small set of hard-coded special cases. A shared metadata-driven normalizer and validator is required. |
+| `P1` — Node update bypasses validation and financial-center synchronization | **Open; newly exposed by editable unit details** | The new setup action correctly uses the existing node-update endpoint, but that endpoint must first merge and validate attributes, then safely synchronize an affected center in the same transaction. Until repaired, direct in-setup edits remain a release blocker. |
+| `P1` — Company-code country and plant constraints are inconsistent | **Open** | Country requirements and topology constraints need a unified policy and early error presentation. |
+| `P1` — A GL-account row is used as a chart-of-accounts reference | **Open by design debt** | The guided UI clarifies the interim primary-ledger reference but cannot make a row-level account a proper chart header. A `charts_of_accounts` aggregate and scoped `chart_id` relation are required. |
+| `P1` — Cost/profit-center synchronization bypasses relationship validation | **Open** | Synchronization must be routed through one relationship-aware transaction and require a resolved Controlling Area before activation. |
+| `P1` — Expired required links can satisfy integrity checks | **Open** | The active-date filter is present in some operations but missing from the required-parent integrity check. |
+| `P2` — Overlapping fiscal periods and unclear missing account-type feedback | **Open** | The guided UI hides completed embedded accounting setup, but overlap prevention and an explicit missing-type matrix remain required in the finance contract. |
+
+## Safe Changes Already on This Branch
+
+The branch improves the operator experience without claiming to close the underlying safety report: it refreshes readiness after successful saves, avoids forcing recreation of an embedded ledger baseline, replaces global-default POS entry in the primary setup flow with selection by existing ID, and separates the profit-center ownership of an organizational unit from the operating-link card.
+
+## Required Remediation Order
+
+1. Introduce `links[]` node creation with transaction-wide relationship validation and update the workspace to collect every required and optional relationship.
+2. Remove code-only operating-resource mutation. Existing resources must be selected and updated by scoped IDs; any creation flow must generate scoped identities and enforce scope uniqueness.
+3. Implement metadata-driven value normalization and validation, then route both create and update through it.
+4. Make node updates relationship-aware and synchronize cost/profit centers only through the validated transaction.
+5. Add a real chart-of-accounts header model, scoped fiscal-period constraints, and an explicit data-audit command before enabling production multi-organization onboarding.
diff --git a/frontend/app/globals.css b/frontend/app/globals.css
index f4ff18db..21c2bd95 100644
--- a/frontend/app/globals.css
+++ b/frontend/app/globals.css
@@ -7514,6 +7514,12 @@ body.nav-sidebar-is-collapsed .sidebar-toggle-btn {
 .org-workspace-selected-type span { margin-top: 0.15rem; color: var(--text-secondary); font-size: 0.76rem; line-height: 1.45; }
 .org-workspace-composer-footer { padding-top: 0.8rem; }
 .org-workspace-composer-footer p { max-width: 38rem; margin: 0; color: var(--text-secondary); font-size: 0.75rem; line-height: 1.5; }
+.org-workspace-link-rule { display: grid; gap: 0.45rem; min-width: 0; padding: 0.75rem; margin: 0; border: 1px solid var(--border-color); border-radius: var(--radius-sm); }
+.org-workspace-link-rule legend { padding: 0 0.25rem; color: var(--text-primary); font-size: 0.85rem; font-weight: 700; }
+.org-workspace-link-rule small { color: var(--text-muted); font-size: 0.75rem; line-height: 1.45; }
+.org-workspace-link-options { display: grid; gap: 0.4rem; }
+.org-workspace-link-option { display: inline-flex; align-items: center; gap: 0.5rem; min-height: 2rem; color: var(--text-secondary); font-size: 0.82rem; cursor: pointer; }
+.org-workspace-link-option input { width: 1rem; height: 1rem; accent-color: var(--primary-color); }
 .org-workspace-reference-help { display: block; margin-top: 0.35rem; color: var(--text-muted); font-size: 0.72rem; line-height: 1.5; }
 .org-workspace-reference-help.is-actionable { color: var(--primary-color); }
 .org-workspace-domain-enterprise { --domain-color: #475569; --domain-tint: rgba(71, 85, 105, 0.08); }
diff --git a/frontend/app/setup/components/OrganizationArchitectureWorkspace.tsx b/frontend/app/setup/components/OrganizationArchitectureWorkspace.tsx
index 9df34c3d..4f176351 100644
--- a/frontend/app/setup/components/OrganizationArchitectureWorkspace.tsx
+++ b/frontend/app/setup/components/OrganizationArchitectureWorkspace.tsx
@@ -38,6 +38,18 @@ const PHASE_REQUIREMENTS: Record<OrganizationWorkspacePhase, string[]> = {
   extensions: [],
 };
 
+const REQUIRED_PARENT_TYPES: Readonly<Record<string, readonly string[]>> = {
+  COMP_CODE: ["CLIENT"],
+  CONTROLLING_AREA: ["COMP_CODE"],
+  COST_CENTER: ["CONTROLLING_AREA"],
+  PROFIT_CENTER: ["CONTROLLING_AREA"],
+  PLANT: ["COMP_CODE"],
+  STORAGE_LOC: ["PLANT"],
+  PURCH_ORG: ["COMP_CODE"],
+  SALES_ORG: ["COMP_CODE"],
+  PERSONNEL_AREA: ["COMP_CODE"],
+};
+
 const DOMAIN_ORDER = ["Enterprise", "Financial", "Controlling", "Logistics", "Sales", "HR", "Project"];
 const DOMAIN_ICON: Record<string, string> = {
   Enterprise: "building",
@@ -116,7 +128,7 @@ export function OrganizationArchitectureWorkspace({
   const [selectedTypeId, setSelectedTypeId] = useState("");
   const [nodeCode, setNodeCode] = useState("");
   const [nodeNameValue, setNodeNameValue] = useState("");
-  const [parentUuid, setParentUuid] = useState("");
+  const [linkTargetsByRule, setLinkTargetsByRule] = useState<Record<number, string[]>>({});
   const [attributes, setAttributes] = useState<Record<string, string>>({});
   const [scopeContext, setScopeContext] = useState<Record<string, unknown> | null>(null);
   const [isScopeLoading, setIsScopeLoading] = useState(false);
@@ -151,7 +163,11 @@ export function OrganizationArchitectureWorkspace({
       : i18n.catalog["enterpriseCore.orgWorkspace.reference.chartOfAccounts.empty"];
   };
 
-  const inputTypeForAttribute = (attributeType?: string) => attributeType === "integer" ? "number" : "text";
+  const inputTypeForAttribute = (attributeType?: string) => {
+    if (attributeType === "integer" || attributeType === "decimal") return "number";
+    if (attributeType === "date") return "date";
+    return "text";
+  };
   const defaultTextDirection = locale === "ar-SA" ? "rtl" : "ltr";
 
   const domainForType = (typeId: string) => metaTypes.find((item) => item.id === typeId)?.level_domain || "";
@@ -184,13 +200,13 @@ export function OrganizationArchitectureWorkspace({
     })).filter((group) => group.types.length > 0);
   }, [activePhase, metaTypes, suggestedTypes]);
 
-  const validParentNodes = useMemo(() => {
-    if (!selectedTypeId) return [];
-    const allowedParentTypes = topologyRules
-      .filter((rule) => rule.source_node_type_id === selectedTypeId)
-      .map((rule) => rule.target_node_type_id);
-    return nodes.filter((node) => node.status === "active" && allowedParentTypes.includes(node.node_type_id));
-  }, [nodes, selectedTypeId, topologyRules]);
+  const selectedTypeRules = useMemo(
+    () => topologyRules.filter((rule) => rule.source_node_type_id === selectedTypeId),
+    [selectedTypeId, topologyRules],
+  );
+  const linkCandidatesForRule = (rule: OrganizationTopologyRule) => nodes.filter(
+    (node) => node.status === "active" && node.node_type_id === rule.target_node_type_id,
+  );
 
   const tree = useMemo(() => {
     const nodeMap = new Map(nodes.map((node) => [node.node_uuid, node]));
@@ -229,13 +245,13 @@ export function OrganizationArchitectureWorkspace({
     setSelectedTypeId("");
     setNodeCode("");
     setNodeNameValue("");
-    setParentUuid("");
+    setLinkTargetsByRule({});
     setAttributes({});
   };
 
   const chooseType = (typeId: string) => {
     setSelectedTypeId(typeId);
-    setParentUuid("");
+    setLinkTargetsByRule({});
     setAttributes({});
   };
 
@@ -249,7 +265,10 @@ export function OrganizationArchitectureWorkspace({
       node_type_id: selectedTypeId,
       code: nodeCode.trim(),
       attributes: draftAttributes,
-      ...(parentUuid ? { link: { target_node_uuid: parentUuid, validate_constraints: true } } : {}),
+      links: Object.entries(linkTargetsByRule).flatMap(([, targetUuids]) => targetUuids.map((target_node_uuid) => ({
+        target_node_uuid,
+        validate_constraints: true as const,
+      }))),
     });
     if (created) resetComposer();
   };
@@ -278,11 +297,14 @@ export function OrganizationArchitectureWorkspace({
   };
   const phaseTitle = (phase: OrganizationWorkspacePhase) => phaseTitles[phase];
   const phaseDescription = (phase: OrganizationWorkspacePhase) => phaseDescriptions[phase];
-  const parentRequired = topologyRules.some((rule) => rule.source_node_type_id === selectedTypeId);
+  const requiredParentTypes = REQUIRED_PARENT_TYPES[selectedTypeId] ?? [];
+  const requiredRelationshipsComplete = requiredParentTypes.every((targetTypeId) => selectedTypeRules.some(
+    (rule) => rule.target_node_type_id === targetTypeId && (linkTargetsByRule[rule.id] ?? []).length > 0,
+  ));
   const mandatoryAttributesComplete = (selectedType?.attributes ?? [])
     .filter((attribute) => attribute.is_mandatory)
     .every((attribute) => (attributes[attribute.attribute_key] || (attribute.attribute_key === "name" ? nodeNameValue : "")).trim());
-  const isNodeReadyToCreate = Boolean(selectedTypeId && nodeCode.trim() && mandatoryAttributesComplete && (!parentRequired || parentUuid));
+  const isNodeReadyToCreate = Boolean(selectedTypeId && nodeCode.trim() && mandatoryAttributesComplete && requiredRelationshipsComplete);
 
   const renderTree = (treeNode: TreeNode, depth = 0) => {
     const { node, children } = treeNode;
@@ -487,18 +509,51 @@ export function OrganizationArchitectureWorkspace({
                 <span>{i18n.catalog["enterpriseCore.orgWorkspace.composer.name"]}</span>
                 <input id="org-workspace-name" className="setup-input" dir={getTextDirection(nodeNameValue, defaultTextDirection)} value={nodeNameValue} onChange={(event) => setNodeNameValue(event.target.value)} />
               </label>
-              {validParentNodes.length ? (
-                <label className="form-group" htmlFor="org-workspace-parent">
-                  <span>{i18n.catalog["enterpriseCore.orgWorkspace.composer.parent"]}</span>
-                  <SearchableSelect
-                    id="org-workspace-parent"
-                    className="setup-select"
-                    value={parentUuid}
-                    onChange={(value) => setParentUuid(String(value || ""))}
-                    options={validParentNodes.map((node) => ({ value: node.node_uuid, label: catalogText(i18n, "enterpriseCore.setup.nodeSummary", { value0: node.code, value1: labelForType(node.node_type_id) }) }))}
-                  />
-                </label>
-              ) : null}
+              {selectedTypeRules.map((rule) => {
+                const candidates = linkCandidatesForRule(rule);
+                const selectedTargets = linkTargetsByRule[rule.id] ?? [];
+                const isRequired = (REQUIRED_PARENT_TYPES[selectedTypeId] ?? []).includes(rule.target_node_type_id);
+                const allowsMultiple = rule.cardinality === "N:M";
+                return (
+                  <fieldset key={rule.id} className="form-group org-workspace-link-rule">
+                    <legend>{labelForType(rule.target_node_type_id)}{isRequired ? " *" : ""}</legend>
+                    <small>{rule.description || labelForType(rule.target_node_type_id)}</small>
+                    {allowsMultiple ? (
+                      <div className="org-workspace-link-options">
+                        {candidates.map((node) => (
+                          <label key={node.node_uuid} className="org-workspace-link-option">
+                            <input
+                              type="checkbox"
+                              checked={selectedTargets.includes(node.node_uuid)}
+                              onChange={() => setLinkTargetsByRule((current) => {
+                                const existing = current[rule.id] ?? [];
+                                return {
+                                  ...current,
+                                  [rule.id]: existing.includes(node.node_uuid)
+                                    ? existing.filter((uuid) => uuid !== node.node_uuid)
+                                    : [...existing, node.node_uuid],
+                                };
+                              })}
+                            />
+                            <span>{node.code}</span>
+                          </label>
+                        ))}
+                      </div>
+                    ) : (
+                      <SearchableSelect
+                        id={`org-workspace-link-${rule.id}`}
+                        className="setup-select"
+                        value={selectedTargets[0] ?? ""}
+                        onChange={(value) => setLinkTargetsByRule((current) => ({
+                          ...current,
+                          [rule.id]: value ? [String(value)] : [],
+                        }))}
+                        options={candidates.map((node) => ({ value: node.node_uuid, label: catalogText(i18n, "enterpriseCore.setup.nodeSummary", { value0: node.code, value1: labelForType(node.node_type_id) }) }))}
+                      />
+                    )}
+                  </fieldset>
+                );
+              })}
               {(selectedType.attributes ?? []).filter((attribute) => attribute.attribute_key !== "name").map((attribute) => {
                 const referenceKey = attribute.attribute_key as ReferenceAttributeKey;
                 const referenceOptions = referenceOptionsByAttribute[referenceKey];
@@ -559,13 +614,36 @@ export function OrganizationArchitectureWorkspace({
                           {i18n.catalog["enterpriseCore.orgWorkspace.companyLanguage.help"]}
                         </small>
                       </>
+                    ) : attribute.attribute_type === "boolean" ? (
+                      <select
+                        id={attribute.attribute_key}
+                        className="setup-input"
+                        value={attributes[attribute.attribute_key] || ""}
+                        required={attribute.is_mandatory}
+                        onChange={(event) => setAttributes((current) => ({ ...current, [attribute.attribute_key]: event.target.value }))}
+                      >
+                        <option value="">—</option>
+                        <option value="true">True</option>
+                        <option value="false">False</option>
+                      </select>
+                    ) : attribute.attribute_type === "json" ? (
+                      <textarea
+                        id={attribute.attribute_key}
+                        className="setup-input"
+                        rows={3}
+                        value={attributes[attribute.attribute_key] || ""}
+                        dir="ltr"
+                        required={attribute.is_mandatory}
+                        onChange={(event) => setAttributes((current) => ({ ...current, [attribute.attribute_key]: event.target.value }))}
+                      />
                     ) : (
                       <input
                         id={attribute.attribute_key}
                         className="setup-input"
                         type={inputTypeForAttribute(attribute.attribute_type)}
                         value={attributes[attribute.attribute_key] || ""}
-                        dir={attribute.attribute_type === "integer" ? "ltr" : getTextDirection(attributes[attribute.attribute_key] || "", defaultTextDirection)}
+                        step={attribute.attribute_type === "decimal" ? "any" : undefined}
+                        dir={attribute.attribute_type === "integer" || attribute.attribute_type === "decimal" || attribute.attribute_type === "date" ? "ltr" : getTextDirection(attributes[attribute.attribute_key] || "", defaultTextDirection)}
                         required={attribute.is_mandatory}
                         onChange={(event) => setAttributes((current) => ({ ...current, [attribute.attribute_key]: event.target.value }))}
                       />
@@ -575,7 +653,7 @@ export function OrganizationArchitectureWorkspace({
               })}
             </div>
             <div className="org-workspace-composer-footer">
-              <p>{validParentNodes.length ? i18n.catalog["enterpriseCore.orgWorkspace.composer.parentHelper"] : i18n.catalog["enterpriseCore.orgWorkspace.composer.rootHelper"]}</p>
+              <p>{selectedTypeRules.length ? i18n.catalog["enterpriseCore.orgWorkspace.composer.parentHelper"] : i18n.catalog["enterpriseCore.orgWorkspace.composer.rootHelper"]}</p>
               <div className="setup-actions">
                 <Button type="button" variant="secondary" onClick={resetComposer}>{i18n.catalog["common.general.cancel"]}</Button>
                 <Button type="button" variant="primary" icon="check" onClick={() => void createNode()} isLoading={isSaving} disabled={!isNodeReadyToCreate}>
diff --git a/frontend/app/setup/components/organizationWorkspace.types.ts b/frontend/app/setup/components/organizationWorkspace.types.ts
index 1f45f366..d9eb9f56 100644
--- a/frontend/app/setup/components/organizationWorkspace.types.ts
+++ b/frontend/app/setup/components/organizationWorkspace.types.ts
@@ -46,11 +46,11 @@ export type OrganizationIntegrity = {
 export type OrganizationNodeDraft = {
   node_type_id: string;
   code: string;
-  attributes: Record<string, string>;
-  link?: {
+  attributes: Record<string, unknown>;
+  links: Array<{
     target_node_uuid: string;
     validate_constraints: true;
-  };
+  }>;
 };
 
 export type OrganizationWorkspacePhase = "foundation" | "core_operations" | "extensions";
diff --git a/frontend/scripts/i18n-inventory.ts b/frontend/scripts/i18n-inventory.ts
index 8edd1d86..972bbe54 100644
--- a/frontend/scripts/i18n-inventory.ts
+++ b/frontend/scripts/i18n-inventory.ts
@@ -62,6 +62,7 @@ function isTechnicalValue(value: string): boolean {
         || /^[a-z]+:\/\//i.test(value)
         || /^[a-z0-9_-]+$/i.test(value)
         || /^\d+(\.\d+)*$/.test(value)
+        || /^(?:[1N]:[1M])$/.test(value)
         || value.includes("var(--")
         || value.includes("@keyframes")
         || value.includes("fa-")
diff --git a/frontend/tests/app/setup-onboarding.test.ts b/frontend/tests/app/setup-onboarding.test.ts
index d0fc4bdf..392cdba8 100644
--- a/frontend/tests/app/setup-onboarding.test.ts
+++ b/frontend/tests/app/setup-onboarding.test.ts
@@ -58,7 +58,9 @@ describe("standalone phased setup onboarding", () => {
     expect(page).toContain("ORG.TOPOLOGY_RULES");
     expect(page).toContain("ORG.INTEGRITY_CHECK");
     expect(workspace).toContain("ORG.SCOPE_CONTEXT");
-    expect(workspace).toContain("validParentNodes");
+    expect(workspace).toContain("selectedTypeRules");
+    expect(workspace).toContain("linkTargetsByRule");
+    expect(workspace).toContain("links:");
     expect(workspace).toContain("foundation");
     expect(workspace).toContain("core_operations");
     expect(workspace).toContain("extensions");

From 88355c41027e3805e6116fc53de3733c87e181f5 Mon Sep 17 00:00:00 2001
From: Emran025 <1.48263577e+08+Emran025@users.noreply.github.com>
Date: Sat, 22 Aug 2026 00:58:29 +0000
Subject: [PATCH 6/9] fix(setup): align operating context safety contracts

---
 .../Services/OperatingContextService.php      |  1 +
 .../Services/OrgStructureService.php          | 26 +++++++------------
 .../Feature/Api/OperatingContextApiTest.php   | 11 +++++---
 .../tests/Feature/Api/SetupStateApiTest.php   |  4 ++-
 4 files changed, 20 insertions(+), 22 deletions(-)

diff --git a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OperatingContextService.php b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OperatingContextService.php
index 1f0a70be..4e6b92a8 100644
--- a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OperatingContextService.php
+++ b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OperatingContextService.php
@@ -110,6 +110,7 @@ public function configure(array $data, ?int $userId): OperatingContext
                 [
                     'org_node_uuid' => $data['org_node_uuid'] ?? null,
                     'warehouse_id' => $warehouse?->id,
+                    'pos_terminal_id' => $terminal->id,
                     'cost_center_id' => $data['cost_center_id'] ?? null,
                     'profit_center_id' => $terminal->profit_center_id,
                     // Status is recalculated from the authoritative readiness
diff --git a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OrgStructureService.php b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OrgStructureService.php
index 33477e09..e72d7933 100644
--- a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OrgStructureService.php
+++ b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OrgStructureService.php
@@ -697,25 +697,17 @@ public function runIntegrityCheck(): array
             }
         }
 
-        // 3. Required parent check — key types must have parent links
-        $requiredParentMap = [
-            'PLANT' => 'COMP_CODE',
-            'SALES_ORG' => 'COMP_CODE',
-            'PURCH_ORG' => 'COMP_CODE',
-            'PERSONNEL_AREA' => 'COMP_CODE',
-            'STORAGE_LOC' => 'PLANT',
-            'COST_CENTER' => 'CONTROLLING_AREA',
-            'PROFIT_CENTER' => 'CONTROLLING_AREA',
-        ];
-
+        // 3. Required parent check — reuse the same topology contract enforced on writes.
         foreach ($nodes as $node) {
-            if (!isset($requiredParentMap[$node->node_type_id])) continue;
-            $requiredTarget = $requiredParentMap[$node->node_type_id];
-            $hasRequiredLink = $node->outgoingLinks->contains(function ($link) use ($requiredTarget) {
-                return $link->isActive() && $link->targetNode && $link->targetNode->node_type_id === $requiredTarget;
-            });
+            foreach ($this->requiredParentTypes($node->node_type_id) as $requiredTarget) {
+                $hasRequiredLink = $node->outgoingLinks->contains(function ($link) use ($requiredTarget) {
+                    return $link->isActive() && $link->targetNode && $link->targetNode->node_type_id === $requiredTarget;
+                });
+
+                if ($hasRequiredLink) {
+                    continue;
+                }
 
-            if (!$hasRequiredLink) {
                 $targetLabel = OrgMetaType::find($requiredTarget)?->display_name_ar ?? $requiredTarget;
                 $issues[] = [
                     'type' => 'WARNING',
diff --git a/backend/tests/Feature/Api/OperatingContextApiTest.php b/backend/tests/Feature/Api/OperatingContextApiTest.php
index f0721fd9..fe10436c 100644
--- a/backend/tests/Feature/Api/OperatingContextApiTest.php
+++ b/backend/tests/Feature/Api/OperatingContextApiTest.php
@@ -33,10 +33,10 @@ public function test_readiness_requires_selected_working_unit_and_accounting_bas
         $response->assertJsonPath('data.ready', false)
             ->assertJsonPath('data.next_action', 'working_unit')
             ->assertJsonPath('data.checks.0.action_key', 'operating_context.readiness.working_unit')
-            ->assertJsonPath('data.checks.5.key', 'organizational_structure')
-            ->assertJsonPath('data.checks.5.complete', false)
-            ->assertJsonPath('data.checks.6.key', 'open_fiscal_period')
-            ->assertJsonPath('data.checks.7.key', 'chart_of_accounts')
+            ->assertJsonPath('data.checks.4.key', 'organizational_structure')
+            ->assertJsonPath('data.checks.4.complete', false)
+            ->assertJsonPath('data.checks.5.key', 'open_fiscal_period')
+            ->assertJsonPath('data.checks.6.key', 'chart_of_accounts')
             ->assertJsonPath('data.working_unit_readiness.ready', false)
             ->assertJsonPath('data.structural_readiness.ready', false)
             ->assertJsonPath('data.accounting_readiness.ready', false)
@@ -59,6 +59,7 @@ public function test_can_configure_a_ready_operating_context_only_after_structur
         ]);
 
         foreach ([
+            ['id' => 'CLIENT', 'display_name' => 'Client', 'display_name_ar' => 'العميل', 'level_domain' => 'Enterprise'],
             ['id' => 'COMP_CODE', 'display_name' => 'Company Code', 'display_name_ar' => 'رمز الشركة', 'level_domain' => 'Financial'],
             ['id' => 'CONTROLLING_AREA', 'display_name' => 'Controlling Area', 'display_name_ar' => 'منطقة التحكم', 'level_domain' => 'Financial'],
             ['id' => 'COST_CENTER', 'display_name' => 'Cost Center', 'display_name_ar' => 'مركز التكلفة', 'level_domain' => 'Controlling'],
@@ -67,12 +68,14 @@ public function test_can_configure_a_ready_operating_context_only_after_structur
             OrgMetaType::create($type + ['is_assignable' => true]);
         }
 
+        $client = StructureNode::create(['node_type_id' => 'CLIENT', 'code' => 'CLIENT-1000', 'status' => 'active']);
         $company = StructureNode::create(['node_type_id' => 'COMP_CODE', 'code' => '1000', 'status' => 'active']);
         $controlling = StructureNode::create(['node_type_id' => 'CONTROLLING_AREA', 'code' => 'CA-1000', 'status' => 'active']);
         $costNode = StructureNode::create(['node_type_id' => 'COST_CENTER', 'code' => 'CC-STORE', 'status' => 'active']);
         $profitNode = StructureNode::create(['node_type_id' => 'PROFIT_CENTER', 'code' => 'PC-STORE', 'status' => 'active']);
 
         foreach ([
+            [$company->node_uuid, $client->node_uuid],
             [$controlling->node_uuid, $company->node_uuid],
             [$costNode->node_uuid, $controlling->node_uuid],
             [$profitNode->node_uuid, $controlling->node_uuid],
diff --git a/backend/tests/Feature/Api/SetupStateApiTest.php b/backend/tests/Feature/Api/SetupStateApiTest.php
index 18f9c407..4a244960 100644
--- a/backend/tests/Feature/Api/SetupStateApiTest.php
+++ b/backend/tests/Feature/Api/SetupStateApiTest.php
@@ -104,7 +104,7 @@ public function test_setup_rejects_empty_business_module_selection(): void
 
     private function configureTechnologyCommerceBaseline(): void
     {
-        foreach (['COMP_CODE', 'CONTROLLING_AREA', 'COST_CENTER', 'PROFIT_CENTER', 'PLANT', 'STORAGE_LOC', 'SALES_ORG', 'PURCH_ORG'] as $type) {
+        foreach (['CLIENT', 'COMP_CODE', 'CONTROLLING_AREA', 'COST_CENTER', 'PROFIT_CENTER', 'PLANT', 'STORAGE_LOC', 'SALES_ORG', 'PURCH_ORG'] as $type) {
             OrgMetaType::create([
                 'id' => $type,
                 'display_name' => $type,
@@ -114,6 +114,7 @@ private function configureTechnologyCommerceBaseline(): void
             ]);
         }
 
+        $client = StructureNode::create(['node_type_id' => 'CLIENT', 'code' => 'TECH-CLIENT', 'status' => 'active']);
         $company = StructureNode::create(['node_type_id' => 'COMP_CODE', 'code' => 'TECH-1000', 'status' => 'active']);
         $controlling = StructureNode::create(['node_type_id' => 'CONTROLLING_AREA', 'code' => 'TECH-CA', 'status' => 'active']);
         $costNode = StructureNode::create(['node_type_id' => 'COST_CENTER', 'code' => 'TECH-CC', 'status' => 'active']);
@@ -124,6 +125,7 @@ private function configureTechnologyCommerceBaseline(): void
         $purchasing = StructureNode::create(['node_type_id' => 'PURCH_ORG', 'code' => 'TECH-BUY', 'status' => 'active']);
 
         foreach ([
+            [$company, $client],
             [$controlling, $company],
             [$costNode, $controlling],
             [$profitNode, $controlling],

From 6be7a246fbb8a9ee849249920f2d9592d3d817f6 Mon Sep 17 00:00:00 2001
From: Emran025 <1.48263577e+08+Emran025@users.noreply.github.com>
Date: Sat, 22 Aug 2026 20:44:42 +0000
Subject: [PATCH 7/9] feat(setup): add profile-driven organization templates

---
 .../Services/ModuleReadinessService.php       |  78 ++--
 .../Services/ModuleSelectionService.php       |   7 +-
 .../Services/OrganizationTemplateService.php  | 363 ++++++++++++++++++
 .../SetupStateController.php                  |  46 ++-
 backend/routes/domains/01-enterprise-core.php |   3 +
 .../tests/Feature/Api/SetupStateApiTest.php   |  14 +-
 docs/Plans/profile-driven-setup-templates.md  |  43 +++
 frontend/app/globals.css                      |  19 +
 .../SetupOrganizationProfileSection.tsx       | 207 ++++++++++
 .../components/SetupReadinessSummary.tsx      |  19 +-
 frontend/app/setup/page.tsx                   | 344 +++++++++--------
 frontend/app/setup/types.ts                   |  37 ++
 frontend/lib/endpoints/enterprise-core.ts     |   6 +
 frontend/tests/app/setup-onboarding.test.ts   | 142 +++----
 14 files changed, 1035 insertions(+), 293 deletions(-)
 create mode 100644 backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OrganizationTemplateService.php
 create mode 100644 docs/Plans/profile-driven-setup-templates.md
 create mode 100644 frontend/app/setup/components/SetupOrganizationProfileSection.tsx

diff --git a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/ModuleReadinessService.php b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/ModuleReadinessService.php
index 910aaf17..9971497b 100644
--- a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/ModuleReadinessService.php
+++ b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/ModuleReadinessService.php
@@ -17,15 +17,8 @@
  */
 class ModuleReadinessService
 {
-    public const ONBOARDING_POLICY_VERSION = '2026-08-technology-commerce-v1';
-
-    /**
-     * The default profile supports a small technology retailer or technology
-     * organisation with a physical device store, warehouse, POS, finance, and
-     * purchasing flows. Optional delivery/project/manufacturing capabilities
-     * remain governed by their own module requirements.
-     */
-    public const DEFAULT_ONBOARDING_PROFILE = 'technology_commerce';
+    public const ONBOARDING_POLICY_VERSION = '2026-08-profile-driven-setup-v1';
+    public const DEFAULT_ONBOARDING_PROFILE = 'guided_setup';
 
     /** @var list<string> */
     private const FOUNDATION_NODE_TYPES = ['COMP_CODE', 'CONTROLLING_AREA', 'COST_CENTER', 'PROFIT_CENTER'];
@@ -36,12 +29,19 @@ class ModuleReadinessService
     /** @var list<string> */
     private const CORE_STARTER_MODULES = ['sales', 'products', 'purchases', 'general_ledger'];
 
-    public function __construct(private readonly OrgStructureService $orgStructureService)
-    {
+    public function __construct(
+        private readonly OrgStructureService $orgStructureService,
+        private readonly OrganizationTemplateService $templates,
+    ) {
     }
 
     public function evaluate(?int $userId = null): array
     {
+        $templateProfile = $this->templates->profile();
+        $profileKey = (string) ($templateProfile['template_key'] ?? self::DEFAULT_ONBOARDING_PROFILE);
+        $coreOperatingNodeTypes = $this->coreOperatingNodeTypes($profileKey);
+        $requiresOperatingContext = $this->requiresOperatingContext($profileKey);
+        $starterModules = $this->starterModules($profileKey);
         $integrityIssues = $this->orgStructureService->runIntegrityCheck();
         $activeNodeTypes = $this->activeNodeTypes();
         $context = $this->defaultContext($userId);
@@ -49,7 +49,7 @@ public function evaluate(?int $userId = null): array
         $operatingStructure = $this->validateOperatingStructure($context, $integrityIssues);
         $accountingReadiness = $this->accountingReadiness();
         $foundation = $this->foundationReadiness($activeNodeTypes, $integrityIssues, $accountingReadiness);
-        $coreOperations = $this->coreOperationsReadiness($context, $activeNodeTypes, $integrityIssues, $operatingStructure);
+        $coreOperations = $this->coreOperationsReadiness($context, $activeNodeTypes, $integrityIssues, $operatingStructure, $coreOperatingNodeTypes, $requiresOperatingContext);
         $hasActiveStructure = $activeNodeTypes !== [];
         $modules = Module::query()->orderBy('category')->orderBy('sort_order')->get();
 
@@ -132,7 +132,7 @@ public function evaluate(?int $userId = null): array
         $baselineReady = $foundation['ready'] && $coreOperations['ready'];
         $onboarding = [
             'policy_version' => self::ONBOARDING_POLICY_VERSION,
-            'profile' => self::DEFAULT_ONBOARDING_PROFILE,
+            'profile' => $profileKey,
             'baseline_ready' => $baselineReady,
             'phases' => [
                 'foundation' => $foundation,
@@ -141,7 +141,7 @@ public function evaluate(?int $userId = null): array
             'next_phase' => !$foundation['ready']
                 ? 'foundation'
                 : (!$coreOperations['ready'] ? 'core_operations' : 'module_activation'),
-            'starter_module_keys' => self::CORE_STARTER_MODULES,
+            'starter_module_keys' => $starterModules,
         ];
 
         return [
@@ -371,15 +371,17 @@ private function foundationReadiness(array $activeNodeTypes, array $integrityIss
      * hierarchy, warehouse, and POS terminal. The organisation can later add
      * project, manufacturing, and HR structures without reopening this gate.
      */
-    private function coreOperationsReadiness(?OperatingContext $context, array $activeNodeTypes, array $integrityIssues, array $operatingStructure): array
+    private function coreOperationsReadiness(?OperatingContext $context, array $activeNodeTypes, array $integrityIssues, array $operatingStructure, array $coreOperatingNodeTypes, bool $requiresOperatingContext): array
     {
-        $missingNodeTypes = array_values(array_diff(self::CORE_OPERATING_NODE_TYPES, $activeNodeTypes));
-        $relevantIssues = $this->relevantIntegrityIssues($integrityIssues, self::CORE_OPERATING_NODE_TYPES);
-        $validNodeTypes = $this->validCoreOperatingNodeTypes($context);
-        $unlinkedNodeTypes = array_values(array_diff(self::CORE_OPERATING_NODE_TYPES, $validNodeTypes));
+        $missingNodeTypes = array_values(array_diff($coreOperatingNodeTypes, $activeNodeTypes));
+        $relevantIssues = $this->relevantIntegrityIssues($integrityIssues, $coreOperatingNodeTypes);
+        $validNodeTypes = $requiresOperatingContext
+            ? $this->validCoreOperatingNodeTypes($context, $coreOperatingNodeTypes)
+            : $coreOperatingNodeTypes;
+        $unlinkedNodeTypes = array_values(array_diff($coreOperatingNodeTypes, $validNodeTypes));
         $reasonCodes = [];
 
-        if (!$operatingStructure['ready']) {
+        if ($requiresOperatingContext && !$operatingStructure['ready']) {
             $reasonCodes = [...$reasonCodes, ...$operatingStructure['reason_codes']];
         }
         if ($missingNodeTypes !== []) {
@@ -397,7 +399,7 @@ private function coreOperationsReadiness(?OperatingContext $context, array $acti
         return [
             'id' => 'core_operations',
             'ready' => $reasonCodes === [],
-            'required_node_types' => self::CORE_OPERATING_NODE_TYPES,
+            'required_node_types' => $coreOperatingNodeTypes,
             'missing_node_types' => $missingNodeTypes,
             'unlinked_node_types' => $unlinkedNodeTypes,
             'integrity_issue_count' => count($relevantIssues),
@@ -406,7 +408,7 @@ private function coreOperationsReadiness(?OperatingContext $context, array $acti
     }
 
     /** @return list<string> */
-    private function validCoreOperatingNodeTypes(?OperatingContext $context): array
+    private function validCoreOperatingNodeTypes(?OperatingContext $context, array $coreOperatingNodeTypes): array
     {
         if (!$context?->org_node_uuid) {
             return [];
@@ -419,7 +421,7 @@ private function validCoreOperatingNodeTypes(?OperatingContext $context): array
         }
 
         $valid = [];
-        foreach (self::CORE_OPERATING_NODE_TYPES as $nodeType) {
+        foreach ($coreOperatingNodeTypes as $nodeType) {
             $hasCompanyLinkedNode = StructureNode::query()
                 ->where('node_type_id', $nodeType)
                 ->where('status', 'active')
@@ -438,6 +440,36 @@ private function validCoreOperatingNodeTypes(?OperatingContext $context): array
         return $valid;
     }
 
+    /** @return list<string> */
+    private function coreOperatingNodeTypes(string $profileKey): array
+    {
+        return match ($profileKey) {
+            'single_store_retail', 'multi_site_retail', 'manufacturing' => ['PLANT', 'STORAGE_LOC', 'SALES_ORG', 'PURCH_ORG'],
+            'single_store_service', 'professional_services' => ['SALES_ORG'],
+            // Enterprise blueprints deliberately defer operational scope until
+            // each legal entity/site is governed through the advanced designer.
+            'enterprise_blueprint' => [],
+            default => [],
+        };
+    }
+
+    private function requiresOperatingContext(string $profileKey): bool
+    {
+        return in_array($profileKey, ['single_store_retail', 'multi_site_retail', 'manufacturing'], true);
+    }
+
+    /** @return list<string> */
+    private function starterModules(string $profileKey): array
+    {
+        return match ($profileKey) {
+            'single_store_retail', 'multi_site_retail' => ['sales', 'products', 'purchases', 'general_ledger'],
+            'manufacturing' => ['sales', 'products', 'purchases', 'general_ledger'],
+            'single_store_service', 'professional_services' => ['sales', 'general_ledger'],
+            'enterprise_blueprint' => ['general_ledger'],
+            default => self::CORE_STARTER_MODULES,
+        };
+    }
+
     private function activeNodeTypes(): array
     {
         return StructureNode::query()
diff --git a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/ModuleSelectionService.php b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/ModuleSelectionService.php
index 7a61b508..72e6a268 100644
--- a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/ModuleSelectionService.php
+++ b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/ModuleSelectionService.php
@@ -33,8 +33,10 @@ final class ModuleSelectionService
      */
     public const CORE_STARTER_MODULES = ['sales', 'products', 'purchases', 'general_ledger'];
 
-    public function __construct(private readonly ModuleReadinessService $readiness)
-    {
+    public function __construct(
+        private readonly ModuleReadinessService $readiness,
+        private readonly OrganizationTemplateService $templates,
+    ) {
     }
 
     /** @return list<string> */
@@ -204,6 +206,7 @@ public function state(?int $userId = null): array
             'active_module_keys' => $activeBusiness->pluck('module_key')->all(),
             'pending_module_keys' => $pendingBusiness->pluck('module_key')->all(),
             'modules' => $modules->all(),
+            'organization_template' => $this->templates->state(),
         ];
     }
 
diff --git a/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OrganizationTemplateService.php b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OrganizationTemplateService.php
new file mode 100644
index 00000000..abecef39
--- /dev/null
+++ b/backend/app/Domains/EnterpriseCore/OrganizationGovernance/Services/OrganizationTemplateService.php
@@ -0,0 +1,363 @@
+<?php
+
+namespace App\Domains\EnterpriseCore\OrganizationGovernance\Services;
+
+use App\Domains\EnterpriseCore\OrganizationGovernance\Models\FactoryCalendar;
+use App\Domains\EnterpriseCore\OrganizationGovernance\Models\Setting;
+use App\Domains\EnterpriseCore\OrganizationGovernance\Models\StructureNode;
+use App\Domains\Finance\ForeignExchange\Models\Currency;
+use App\Domains\Finance\GeneralLedger\Models\ChartOfAccount;
+use Illuminate\Support\Arr;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Validation\ValidationException;
+
+/**
+ * Converts business intent into the minimum safe organizational structure.
+ *
+ * The catalogue deliberately describes business templates rather than exposing
+ * raw ERP meta-types. All writes still flow through OrgStructureService, so
+ * metadata validation, topology rules, audit history and financial sync stay
+ * authoritative for both templates and the advanced organization designer.
+ */
+final class OrganizationTemplateService
+{
+    public const PROFILE_KEY = 'setup.organization_profile';
+    public const PRIMARY_GENERAL_LEDGER_REFERENCE = 'ACCORE-PRIMARY-GL';
+
+    /** @var array<string, array<string, mixed>> */
+    private const TEMPLATES = [
+        'single_store_retail' => [
+            'industry' => 'retail',
+            'requires_inventory' => true,
+            'label_ar' => 'متجر تجزئة واحد مع مخزون',
+            'label_en' => 'Single-store retail with inventory',
+            'description_ar' => 'لبقالة أو صيدلية أو متجر يبيع من نقطة بيع ويحتفظ بمخزون.',
+            'generated_types' => ['COMP_CODE', 'CONTROLLING_AREA', 'COST_CENTER', 'PROFIT_CENTER', 'PLANT', 'STORAGE_LOC', 'PURCH_ORG', 'SALES_ORG'],
+        ],
+        'single_store_service' => [
+            'industry' => 'services',
+            'requires_inventory' => false,
+            'label_ar' => 'منشأة خدمات أو متجر بلا مخزون',
+            'label_en' => 'Service business or stock-free store',
+            'description_ar' => 'لشركة خدمات أو بيع مباشر لا يحتاج إلى موقع مخزون في البداية.',
+            'generated_types' => ['COMP_CODE', 'CONTROLLING_AREA', 'COST_CENTER', 'PROFIT_CENTER', 'SALES_ORG'],
+        ],
+        'multi_site_retail' => [
+            'industry' => 'retail',
+            'requires_inventory' => true,
+            'label_ar' => 'تجزئة متعددة الفروع',
+            'label_en' => 'Multi-site retail',
+            'description_ar' => 'ينشئ الفرع الأول بأمان ويترك إضافة الفروع التالية لمسار توسع واضح.',
+            'generated_types' => ['COMP_CODE', 'CONTROLLING_AREA', 'COST_CENTER', 'PROFIT_CENTER', 'PLANT', 'STORAGE_LOC', 'PURCH_ORG', 'SALES_ORG'],
+        ],
+        'professional_services' => [
+            'industry' => 'professional_services',
+            'requires_inventory' => false,
+            'label_ar' => 'خدمات مهنية ومشاريع',
+            'label_en' => 'Professional services and projects',
+            'description_ar' => 'لبيوت الخبرة والاستشارات والخدمات المهنية قبل تفعيل المشاريع والموارد البشرية.',
+            'generated_types' => ['COMP_CODE', 'CONTROLLING_AREA', 'COST_CENTER', 'PROFIT_CENTER', 'SALES_ORG'],
+        ],
+        'manufacturing' => [
+            'industry' => 'manufacturing',
+            'requires_inventory' => true,
+            'label_ar' => 'تصنيع أو تشغيل بمخزون',
+            'label_en' => 'Manufacturing or inventory operations',
+            'description_ar' => 'ينشئ موقع تشغيل ومخزونًا ومبيعات ومشتريات، ثم يفتح التصنيع كتوسّع منفصل.',
+            'generated_types' => ['COMP_CODE', 'CONTROLLING_AREA', 'COST_CENTER', 'PROFIT_CENTER', 'PLANT', 'STORAGE_LOC', 'PURCH_ORG', 'SALES_ORG'],
+        ],
+        'enterprise_blueprint' => [
+            'industry' => 'enterprise',
+            'requires_inventory' => false,
+            'label_ar' => 'مخطط مؤسسة كبيرة',
+            'label_en' => 'Enterprise blueprint',
+            'description_ar' => 'يؤسس الشركة والأبعاد الرقابية فقط، ثم يدار التوسع متعدد الكيانات والفروع عبر المصمم المتقدم.',
+            'generated_types' => ['COMP_CODE', 'CONTROLLING_AREA', 'COST_CENTER', 'PROFIT_CENTER'],
+        ],
+    ];
+
+    public function __construct(private readonly OrgStructureService $orgStructure)
+    {
+    }
+
+    /** @return array<string, mixed> */
+    public function state(): array
+    {
+        $profile = $this->profile();
+
+        return [
+            'profile' => $profile,
+            'templates' => collect(self::TEMPLATES)->map(function (array $template, string $key): array {
+                return [
+                    'key' => $key,
+                    ...$template,
+                ];
+            })->values()->all(),
+            'is_applied' => (bool) Arr::get($profile, 'applied_at'),
+            'can_apply' => $profile !== null && !$this->hasActiveFoundation(),
+        ];
+    }
+
+    /** @return array<string, mixed>|null */
+    public function profile(): ?array
+    {
+        $raw = Setting::query()->where('setting_key', self::PROFILE_KEY)->value('setting_value');
+        if (!is_string($raw) || trim($raw) === '') {
+            return null;
+        }
+
+        $decoded = json_decode($raw, true);
+
+        return is_array($decoded) ? $decoded : null;
+    }
+
+    /** @param array<string, mixed> $data */
+    public function saveProfile(array $data): array
+    {
+        $templateKey = (string) ($data['template_key'] ?? '');
+        if (!isset(self::TEMPLATES[$templateKey])) {
+            throw ValidationException::withMessages(['template_key' => ['Select a supported organization template.']]);
+        }
+
+        $template = self::TEMPLATES[$templateKey];
+        $countryCode = strtoupper(trim((string) ($data['country_code'] ?? '')));
+        $currencyId = $data['currency_id'] ?? null;
+        if (!$currencyId || !Currency::active()->whereKey($currencyId)->exists()) {
+            throw ValidationException::withMessages(['currency_id' => ['Select an active operating currency.']]);
+        }
+        if ($countryCode === '') {
+            throw ValidationException::withMessages(['country_code' => ['Select the legal country or region.']]);
+        }
+
+        $profile = [
+            'template_key' => $templateKey,
+            'industry' => $template['industry'],
+            'organization_size' => (string) ($data['organization_size'] ?? 'small'),
+            'company_name' => trim((string) ($data['company_name'] ?? '')),
+            'company_code' => strtoupper(trim((string) ($data['company_code'] ?? ''))),
+            'country_code' => $countryCode,
+            'currency_id' => (int) $currencyId,
+            'primary_site_name' => trim((string) ($data['primary_site_name'] ?? '')),
+            'primary_site_code' => strtoupper(trim((string) ($data['primary_site_code'] ?? ''))),
+            'factory_calendar_id' => filled($data['factory_calendar_id'] ?? null) ? (int) $data['factory_calendar_id'] : null,
+            'language' => in_array(($data['language'] ?? null), ['ar-SA', 'en-US'], true) ? $data['language'] : 'ar-SA',
+            'inventory_enabled' => (bool) $template['requires_inventory'],
+            'updated_at' => now()->toISOString(),
+            'applied_at' => Arr::get($this->profile(), 'applied_at'),
+        ];
+
+        if ($profile['company_name'] === '' || $profile['company_code'] === '') {
+            throw ValidationException::withMessages(['company_name' => ['Company name and code are required.']]);
+        }
+        if (!preg_match('/^[A-Z0-9_-]{2,20}$/', $profile['company_code'])) {
+            throw ValidationException::withMessages(['company_code' => ['Company code must use 2–20 uppercase letters, numbers, underscores, or hyphens.']]);
+        }
+
+        if ($profile['inventory_enabled']) {
+            if ($profile['primary_site_name'] === '' || $profile['primary_site_code'] === '') {
+                throw ValidationException::withMessages(['primary_site_name' => ['Site name and code are required for inventory templates.']]);
+            }
+            $calendar = $profile['factory_calendar_id'] ? FactoryCalendar::active()->find($profile['factory_calendar_id']) : null;
+            if (!$calendar) {
+                throw ValidationException::withMessages(['factory_calendar_id' => ['Select an active operating calendar for the primary site.']]);
+            }
+            if (strcasecmp($calendar->country_code, $profile['country_code']) !== 0) {
+                throw ValidationException::withMessages(['factory_calendar_id' => ['The operating calendar must match the legal country.']]);
+            }
+        }
+
+        Setting::updateOrCreate(
+            ['setting_key' => self::PROFILE_KEY],
+            ['setting_value' => json_encode($profile, JSON_THROW_ON_ERROR)]
+        );
+
+        return $this->state();
+    }
+
+    /** @return array<string, mixed> */
+    public function apply(?int $userId = null): array
+    {
+        $profile = $this->profile();
+        if (!$profile) {
+            throw ValidationException::withMessages(['profile' => ['Save the organization profile before applying a template.']]);
+        }
+        if (filled($profile['applied_at'] ?? null)) {
+            throw ValidationException::withMessages(['profile' => ['This organization template has already been applied. Use the advanced designer for controlled expansion.']]);
+        }
+        if ($this->hasActiveFoundation()) {
+            throw ValidationException::withMessages(['profile' => ['An active organizational foundation already exists. Template application is blocked to prevent duplicate structures.']]);
+        }
+
+        $templateKey = (string) $profile['template_key'];
+        $template = self::TEMPLATES[$templateKey] ?? null;
+        if (!$template) {
+            throw ValidationException::withMessages(['template_key' => ['The saved template is no longer available.']]);
+        }
+        $this->assertBaselineLedger();
+
+        return DB::transaction(function () use ($profile, $template, $userId): array {
+            $client = $this->orgStructure->createNodeWithLinks([
+                'node_type_id' => 'CLIENT',
+                'code' => 'CLIENT-'.$profile['company_code'],
+                'attributes' => [
+                    'name' => $profile['company_name'],
+                    'default_language' => $profile['language'],
+                ],
+                'status' => 'active',
+            ])['node'];
+
+            $company = $this->orgStructure->createNodeWithLinks([
+                'node_type_id' => 'COMP_CODE',
+                'code' => $profile['company_code'],
+                'attributes' => [
+                    'name' => $profile['company_name'],
+                    'country_code' => $profile['country_code'],
+                    'currency_id' => (string) $profile['currency_id'],
+                    'chart_of_accounts_id' => self::PRIMARY_GENERAL_LEDGER_REFERENCE,
+                    'fiscal_year_variant' => 'K4',
+                    'language' => $profile['language'],
+                ],
+                'status' => 'active',
+            ], [['target_node_uuid' => $client->node_uuid, 'validate_constraints' => true]])['node'];
+
+            $controlling = $this->orgStructure->createNodeWithLinks([
+                'node_type_id' => 'CONTROLLING_AREA',
+                'code' => 'CA-'.$profile['company_code'],
+                'attributes' => [
+                    'name' => 'منطقة التحكم — '.$profile['company_name'],
+                    'currency_id' => (string) $profile['currency_id'],
+                ],
+                'status' => 'active',
+            ], [['target_node_uuid' => $company->node_uuid, 'validate_constraints' => true]])['node'];
+
+            $costCenter = $this->orgStructure->createNodeWithLinks([
+                'node_type_id' => 'COST_CENTER',
+                'code' => 'CC-'.$profile['company_code'],
+                'attributes' => [
+                    'name' => 'مركز تكلفة — '.$profile['company_name'],
+                    'cost_center_category' => 'operational',
+                ],
+                'status' => 'active',
+            ], [['target_node_uuid' => $controlling->node_uuid, 'validate_constraints' => true]])['node'];
+
+            $profitCenter = $this->orgStructure->createNodeWithLinks([
+                'node_type_id' => 'PROFIT_CENTER',
+                'code' => 'PC-'.$profile['company_code'],
+                'attributes' => [
+                    'name' => 'مركز ربح — '.$profile['company_name'],
+                    'profit_center_group' => 'default',
+                ],
+                'status' => 'active',
+            ], [['target_node_uuid' => $controlling->node_uuid, 'validate_constraints' => true]])['node'];
+
+            $created = [
+                'client' => $client->node_uuid,
+                'company_code' => $company->node_uuid,
+                'controlling_area' => $controlling->node_uuid,
+                'cost_center' => $costCenter->node_uuid,
+                'profit_center' => $profitCenter->node_uuid,
+            ];
+
+            if (($template['requires_inventory'] ?? false) === true) {
+                $site = $this->orgStructure->createNodeWithLinks([
+                    'node_type_id' => 'PLANT',
+                    'code' => $profile['primary_site_code'],
+                    'attributes' => [
+                        'name' => $profile['primary_site_name'],
+                        'country_code' => $profile['country_code'],
+                        'factory_calendar_id' => (string) $profile['factory_calendar_id'],
+                        'language' => $profile['language'],
+                    ],
+                    'status' => 'active',
+                ], [
+                    ['target_node_uuid' => $company->node_uuid, 'validate_constraints' => true],
+                    ['target_node_uuid' => $profitCenter->node_uuid, 'validate_constraints' => true],
+                ])['node'];
+
+                $storage = $this->orgStructure->createNodeWithLinks([
+                    'node_type_id' => 'STORAGE_LOC',
+                    'code' => 'ST-'.$profile['primary_site_code'],
+                    'attributes' => ['name' => 'مخزون '.$profile['primary_site_name']],
+                    'status' => 'active',
+                ], [['target_node_uuid' => $site->node_uuid, 'validate_constraints' => true]])['node'];
+
+                $purchasing = $this->orgStructure->createNodeWithLinks([
+                    'node_type_id' => 'PURCH_ORG',
+                    'code' => 'PO-'.$profile['company_code'],
+                    'attributes' => ['name' => 'مشتريات '.$profile['company_name']],
+                    'status' => 'active',
+                ], [
+                    ['target_node_uuid' => $company->node_uuid, 'validate_constraints' => true],
+                    ['target_node_uuid' => $site->node_uuid, 'validate_constraints' => true],
+                ])['node'];
+
+                $sales = $this->createSalesOrganization($profile, $company->node_uuid);
+                $this->orgStructure->createLink($site->node_uuid, $sales->node_uuid);
+                $created += [
+                    'site' => $site->node_uuid,
+                    'storage_location' => $storage->node_uuid,
+                    'purchasing_organization' => $purchasing->node_uuid,
+                    'sales_organization' => $sales->node_uuid,
+                ];
+            } elseif (in_array('SALES_ORG', $template['generated_types'], true)) {
+                $sales = $this->createSalesOrganization($profile, $company->node_uuid);
+                $created['sales_organization'] = $sales->node_uuid;
+            }
+
+            $profile['applied_at'] = now()->toISOString();
+            $profile['applied_by'] = $userId;
+            $profile['created_nodes'] = $created;
+            Setting::updateOrCreate(
+                ['setting_key' => self::PROFILE_KEY],
+                ['setting_value' => json_encode($profile, JSON_THROW_ON_ERROR)]
+            );
+
+            return [
+                'profile' => $profile,
+                'created_nodes' => $created,
+                'next_actions' => [
+                    'Create a scoped warehouse and POS terminal through the master-data flow before configuring the operating context.',
+                    'Use the advanced organization designer only when adding branches, channels, sales teams, HR, projects, or other governed extensions.',
+                ],
+            ];
+        });
+    }
+
+    private function createSalesOrganization(array $profile, string $companyUuid): StructureNode
+    {
+        return $this->orgStructure->createNodeWithLinks([
+            'node_type_id' => 'SALES_ORG',
+            'code' => 'SO-'.$profile['company_code'],
+            'attributes' => [
+                'name' => 'مبيعات '.$profile['company_name'],
+                'currency_id' => (string) $profile['currency_id'],
+            ],
+            'status' => 'active',
+        ], [['target_node_uuid' => $companyUuid, 'validate_constraints' => true]])['node'];
+    }
+
+    private function hasActiveFoundation(): bool
+    {
+        return StructureNode::query()
+            ->where('status', 'active')
+            ->whereIn('node_type_id', ['COMP_CODE', 'CONTROLLING_AREA', 'COST_CENTER', 'PROFIT_CENTER'])
+            ->exists();
+    }
+
+    private function assertBaselineLedger(): void
+    {
+        $required = ['asset', 'liability', 'equity', 'revenue', 'expense'];
+        $available = ChartOfAccount::query()
+            ->where('is_active', true)
+            ->pluck('account_type')
+            ->map(fn ($type) => strtolower((string) $type))
+            ->unique()
+            ->all();
+
+        if (array_diff($required, $available) !== []) {
+            throw ValidationException::withMessages([
+                'chart_of_accounts' => ['The seeded baseline chart of accounts is incomplete. Restore the basic chart before applying an organization template.'],
+            ]);
+        }
+    }
+}
diff --git a/backend/app/Http/Controllers/Api/V2/EnterpriseCore/OrganizationGovernance/SetupStateController.php b/backend/app/Http/Controllers/Api/V2/EnterpriseCore/OrganizationGovernance/SetupStateController.php
index b64cfd4f..7ee42a77 100644
--- a/backend/app/Http/Controllers/Api/V2/EnterpriseCore/OrganizationGovernance/SetupStateController.php
+++ b/backend/app/Http/Controllers/Api/V2/EnterpriseCore/OrganizationGovernance/SetupStateController.php
@@ -3,6 +3,7 @@
 namespace App\Http\Controllers\Api\V2\EnterpriseCore\OrganizationGovernance;
 
 use App\Domains\EnterpriseCore\OrganizationGovernance\Services\ModuleSelectionService;
+use App\Domains\EnterpriseCore\OrganizationGovernance\Services\OrganizationTemplateService;
 use App\Http\Controllers\Api\V2\Shared\BaseApiController;
 use App\Http\Controllers\Controller;
 use Illuminate\Http\JsonResponse;
@@ -12,8 +13,10 @@ class SetupStateController extends Controller
 {
     use BaseApiController;
 
-    public function __construct(private readonly ModuleSelectionService $modules)
-    {
+    public function __construct(
+        private readonly ModuleSelectionService $modules,
+        private readonly OrganizationTemplateService $templates,
+    ) {
     }
 
     public function show(Request $request): JsonResponse
@@ -23,6 +26,45 @@ public function show(Request $request): JsonResponse
         ]);
     }
 
+    public function organizationTemplates(): JsonResponse
+    {
+        return $this->successResponse([
+            'data' => $this->templates->state(),
+        ]);
+    }
+
+    public function saveOrganizationProfile(Request $request): JsonResponse
+    {
+        $validated = $request->validate([
+            'template_key' => ['required', 'string', 'max:80'],
+            'organization_size' => ['required', 'in:micro,small,medium,enterprise'],
+            'company_name' => ['required', 'string', 'max:255'],
+            'company_code' => ['required', 'string', 'max:20'],
+            'country_code' => ['required', 'string', 'size:2'],
+            'currency_id' => ['required', 'integer'],
+            'primary_site_name' => ['nullable', 'string', 'max:255'],
+            'primary_site_code' => ['nullable', 'string', 'max:20'],
+            'factory_calendar_id' => ['nullable', 'integer'],
+            'language' => ['nullable', 'in:ar-SA,en-US'],
+        ]);
+
+        return $this->successResponse([
+            'data' => $this->templates->saveProfile($validated),
+        ], 'Organization profile saved.');
+    }
+
+    public function applyOrganizationTemplate(Request $request): JsonResponse
+    {
+        $result = $this->templates->apply($request->user()?->id);
+
+        return $this->successResponse([
+            'data' => [
+                'application' => $result,
+                'state' => $this->modules->state($request->user()?->id),
+            ],
+        ], 'Organization template applied safely.');
+    }
+
     public function selectModules(Request $request): JsonResponse
     {
         $validated = $request->validate([
diff --git a/backend/routes/domains/01-enterprise-core.php b/backend/routes/domains/01-enterprise-core.php
index 715660ae..145c00b3 100644
--- a/backend/routes/domains/01-enterprise-core.php
+++ b/backend/routes/domains/01-enterprise-core.php
@@ -96,6 +96,9 @@
         // ── 04. Setup lifecycle (OrganizationGovernance)
         Route::group(['prefix' => 'setup', 'middleware' => 'can:settings,view'], function () {
             Route::get('/state', [SetupStateController::class, 'show'])->name('v2.setup.state');
+            Route::get('/organization-templates', [SetupStateController::class, 'organizationTemplates'])->name('v2.setup.organization_templates');
+            Route::middleware(['can:settings,edit', 'throttle:api-write'])->post('/organization-profile', [SetupStateController::class, 'saveOrganizationProfile'])->name('v2.setup.organization_profile.save');
+            Route::middleware(['can:settings,create', 'throttle:api-critical'])->post('/apply-organization-template', [SetupStateController::class, 'applyOrganizationTemplate'])->name('v2.setup.organization_template.apply');
             Route::middleware(['can:settings,edit', 'throttle:api-write'])->post('/modules', [SetupStateController::class, 'selectModules'])->name('v2.setup.modules.select');
             Route::middleware(['can:settings,edit', 'throttle:api-critical'])->post('/activate-selected', [SetupStateController::class, 'activateSelected'])->name('v2.setup.modules.activate_selected');
         });
diff --git a/backend/tests/Feature/Api/SetupStateApiTest.php b/backend/tests/Feature/Api/SetupStateApiTest.php
index 4a244960..e050ed2e 100644
--- a/backend/tests/Feature/Api/SetupStateApiTest.php
+++ b/backend/tests/Feature/Api/SetupStateApiTest.php
@@ -40,6 +40,16 @@ public function test_fresh_installation_requires_explicit_business_module_select
             ->assertJsonPath('data.onboarding.starter_bundle_active', false);
     }
 
+    public function test_organization_template_catalog_is_available_before_the_profile_is_saved(): void
+    {
+        $response = $this->authGet(route('v2.setup.organization_templates'));
+
+        $this->assertSuccessResponse($response);
+        $response->assertJsonPath('data.is_applied', false)
+            ->assertJsonPath('data.can_apply', false)
+            ->assertJsonPath('data.templates.0.key', 'single_store_retail');
+    }
+
     public function test_optional_reporting_module_cannot_bypass_the_mandatory_baseline(): void
     {
         $selected = $this->authPost(route('v2.setup.modules.select'), [
@@ -59,13 +69,13 @@ public function test_optional_reporting_module_cannot_bypass_the_mandatory_basel
         $this->assertDatabaseHas('modules', ['module_key' => 'reports', 'is_active' => false]);
     }
 
-    public function test_technology_commerce_configuration_activates_the_mandatory_bundle_and_keeps_optional_projects_scoped(): void
+    public function test_guided_setup_baseline_activates_the_starter_bundle_and_keeps_optional_projects_scoped(): void
     {
         $this->configureTechnologyCommerceBaseline();
 
         $state = $this->authGet(route('v2.setup.state'));
         $this->assertSuccessResponse($state);
-        $state->assertJsonPath('data.onboarding.profile', 'technology_commerce')
+        $state->assertJsonPath('data.onboarding.profile', 'guided_setup')
             ->assertJsonPath('data.onboarding.phases.foundation.ready', true)
             ->assertJsonPath('data.onboarding.phases.core_operations.ready', true)
             ->assertJsonPath('data.onboarding.next_phase', 'module_activation');
diff --git a/docs/Plans/profile-driven-setup-templates.md b/docs/Plans/profile-driven-setup-templates.md
new file mode 100644
index 00000000..6eef58a7
--- /dev/null
+++ b/docs/Plans/profile-driven-setup-templates.md
@@ -0,0 +1,43 @@
+# Profile-driven setup templates
+
+## Decision
+
+The guided setup must collect business intent before it exposes any organizational objects. A selected template creates the smallest safe technical structure using the existing organization metadata and topology services. The advanced organization designer remains available for every defined organizational type; templates never constrain the system to a fixed catalogue.
+
+## Profile inputs
+
+- **Industry:** retail, wholesale, services, manufacturing, technology, professional-services, enterprise.
+- **Scale:** micro, small, medium, enterprise.
+- **Operational choices:** inventory, point of sale, purchasing, online sales, branches.
+- **Organization inputs:** legal company name/code, country, currency, primary site name/code, factory calendar where inventory is enabled.
+
+## Initial templates
+
+| Template | Intended organization | Generated minimum structure |
+|---|---|---|
+| `single_store_retail` | Grocery, pharmacy, small store | Company Code, Controlling Area, Cost Center, Profit Center, Store Site (`PLANT`), Store Inventory (`STORAGE_LOC`), Retail Purchasing Org, Retail Sales Org |
+| `single_store_service` | Service shop or small office | Company Code, Controlling Area, Cost Center, Profit Center, Service Sales Org |
+| `multi_site_retail` | Chain or regional retailer | Same core structure, named as a primary site and ready for additional site templates |
+| `professional_services` | Consulting and professional services | Company Code, Controlling Area, Cost Center, Profit Center, Service Sales Org |
+| `manufacturing` | Manufacturing business | Company Code, Controlling Area, Cost Center, Profit Center, Plant, Storage Location, Purchasing Org, Sales Org |
+| `enterprise_blueprint` | Large organization / Microsoft-scale rollout | Company Code, Controlling Area, Cost Center, Profit Center; leaves advanced dimensions and separate legal entities to governed expansion flows |
+
+## Rules
+
+1. The primary general ledger remains the seeded default template. The setup only validates its availability; it does not create a second chart-of-accounts concept.
+2. A template applies only when no active foundational organization nodes exist. This prevents accidental overwrite of an existing institution.
+3. The template service uses `OrgStructureService::createNodeWithLinks()` inside a single database transaction, so all metadata validation, topology rules, change history, and cost/profit integrations remain authoritative.
+4. A plant is named **site/store** in the business UI. It is not described as a factory unless the chosen template is manufacturing.
+5. Sales office, sales group, distribution channel, division, purchasing group, HR, and project units are extension flows. They must never be required for the initial template.
+6. The setup header is refreshed immediately after a successful profile save or template application. The returned setup state and readiness data are stored together, avoiding stale completion badges.
+
+## Extension model
+
+The profile service provides a template catalogue, not a list of all possible organizational types. Existing metadata and the advanced designer remain the path for all other structures. A future metadata-managed template registry can move this catalogue to the database without changing the UI contract.
+
+## UI principles
+
+- Use `SetupSection`, `SetupField`, `SearchableSelect`, `SegmentedToggle`, and `Button` before creating a new component.
+- Global setup classes live only in `frontend/app/globals.css`.
+- The guided setup shows business choices and a human-readable preview. It does not show raw `PLANT`, `SALES_GROUP`, or topology codes.
+- The advanced designer keeps the raw organizational graph for administrators and consultants after initial setup.
diff --git a/frontend/app/globals.css b/frontend/app/globals.css
index 21c2bd95..c6ae8852 100644
--- a/frontend/app/globals.css
+++ b/frontend/app/globals.css
@@ -7533,3 +7533,22 @@ body.nav-sidebar-is-collapsed .sidebar-toggle-btn {
 @media (max-width: 1120px) { .org-workspace-layout { grid-template-columns: minmax(13rem, 0.8fr) minmax(22rem, 1.4fr); } .org-workspace-inspector { grid-column: 1 / -1; min-height: 11rem; } .org-workspace-inspector-placeholder { min-height: 8rem; } }
 @media (max-width: 760px) { .org-workspace { padding: 1rem; } .org-workspace-hero, .org-workspace-composer-footer { align-items: flex-start; flex-direction: column; } .org-workspace-phase-rail, .org-workspace-layout { grid-template-columns: 1fr; } .org-workspace-phase { min-height: 4rem; } .org-workspace-plan, .org-workspace-canvas, .org-workspace-inspector { min-height: auto; } .org-workspace-tree { max-height: 24rem; } .org-workspace-composer-footer .setup-actions { width: 100%; } .org-workspace-composer-footer .setup-actions .btn { flex: 1 1 auto; } }
 @media (prefers-reduced-motion: reduce) { .org-workspace-phase, .org-workspace-type-chip, .org-workspace-domain-type, .org-workspace-tree-node { transition: none; } .org-workspace-loading-line { animation: none; } }
+
+/* Profile-driven setup templates */
+.setup-template-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(13rem, 1fr)); gap: 0.75rem; }
+.setup-template-card { display: grid; gap: 0.45rem; min-height: 10.5rem; padding: 1rem; border: 1px solid var(--border-color); border-radius: var(--radius-md); background: var(--surface-white); color: var(--text-secondary); text-align: start; font: inherit; cursor: pointer; transition: border-color 0.18s ease, box-shadow 0.18s ease, transform 0.18s ease; }
+.setup-template-card:hover:not(:disabled), .setup-template-card:focus-visible { border-color: var(--primary-color); box-shadow: var(--shadow-sm); transform: translateY(-1px); outline: none; }
+.setup-template-card.is-selected { border-color: var(--primary-color); background: var(--primary-subtle); box-shadow: inset 0 0 0 1px var(--primary-color); }
+.setup-template-card:disabled { cursor: default; opacity: 0.72; }
+.setup-template-card strong { color: var(--text-primary); font-size: 0.9rem; line-height: 1.4; }
+.setup-template-card span { font-size: 0.8rem; line-height: 1.55; }
+.setup-template-card small { margin-top: auto; color: var(--text-muted); font-size: 0.72rem; font-weight: 700; }
+.setup-template-subsection { display: grid; gap: 0.85rem; margin-top: 1rem; padding: 1rem; border: 1px solid var(--border-color); border-radius: var(--radius-md); background: var(--bg-color); }
+.setup-template-subsection h4 { margin: 0; color: var(--text-primary); font-size: 0.9rem; }
+.setup-template-subsection p { margin: 0.25rem 0 0; color: var(--text-secondary); font-size: 0.8rem; line-height: 1.55; }
+.setup-template-preview { display: grid; gap: 0.4rem; margin-top: 1rem; padding: 0.9rem 1rem; border-inline-start: 3px solid var(--primary-color); border-radius: var(--radius-sm); background: var(--primary-subtle); }
+.setup-template-preview strong { color: var(--text-primary); font-size: 0.84rem; }
+.setup-template-preview p { margin: 0; color: var(--primary-dark); font-size: 0.78rem; font-weight: 700; line-height: 1.55; }
+.setup-template-preview small { color: var(--text-secondary); font-size: 0.76rem; line-height: 1.5; }
+@media (max-width: 768px) { .setup-template-grid { grid-template-columns: 1fr; } .setup-template-card { min-height: 0; } }
+@media (prefers-reduced-motion: reduce) { .setup-template-card { transition: none; } .setup-template-card:hover:not(:disabled), .setup-template-card:focus-visible { transform: none; } }
diff --git a/frontend/app/setup/components/SetupOrganizationProfileSection.tsx b/frontend/app/setup/components/SetupOrganizationProfileSection.tsx
new file mode 100644
index 00000000..48fee99f
--- /dev/null
+++ b/frontend/app/setup/components/SetupOrganizationProfileSection.tsx
@@ -0,0 +1,207 @@
+"use client";
+
+import { Button, SearchableSelect, SegmentedToggle } from "@/components/ui";
+import { useI18n } from "@/lib/i18n";
+import { SetupField } from "./SetupField";
+import { SetupSection } from "./SetupSection";
+import type { OrganizationProfile, OrganizationSize, OrganizationTemplate, SelectOption } from "../types";
+
+type ProfileDraft = Omit<OrganizationProfile, "industry" | "inventory_enabled" | "applied_at" | "created_nodes">;
+
+interface SetupOrganizationProfileSectionProps {
+  templates: OrganizationTemplate[];
+  selectedTemplateKey: string;
+  draft: ProfileDraft;
+  currencyOptions: SelectOption[];
+  calendarOptions: SelectOption[];
+  isSaving: boolean;
+  isApplied: boolean;
+  canApply: boolean;
+  onTemplateChange: (templateKey: string) => void;
+  onChange: (changes: Partial<ProfileDraft>) => void;
+  onSave: () => void;
+  onApply: () => void;
+}
+
+const sizeOptions: { value: OrganizationSize; ar: string; en: string }[] = [
+  { value: "micro", ar: "متناهية الصغر", en: "Micro" },
+  { value: "small", ar: "صغيرة", en: "Small" },
+  { value: "medium", ar: "متوسطة", en: "Medium" },
+  { value: "enterprise", ar: "كبيرة / مؤسسية", en: "Enterprise" },
+];
+
+function normalizeCode(value: string): string {
+  return value.toUpperCase().replace(/\s+/g, "-");
+}
+
+export function SetupOrganizationProfileSection({
+  templates,
+  selectedTemplateKey,
+  draft,
+  currencyOptions,
+  calendarOptions,
+  isSaving,
+  isApplied,
+  canApply,
+  onTemplateChange,
+  onChange,
+  onSave,
+  onApply,
+}: SetupOrganizationProfileSectionProps) {
+  const { locale } = useI18n();
+  const isArabic = locale === "ar-SA";
+  const selectedTemplate = templates.find((template) => template.key === selectedTemplateKey) ?? null;
+  const requiresInventory = selectedTemplate?.requires_inventory === true;
+  const templateLabel = (template: OrganizationTemplate) => isArabic ? template.label_ar : template.label_en;
+  const sizeLabels = sizeOptions.map((option) => ({ value: option.value, label: isArabic ? option.ar : option.en }));
+
+  return (
+    <SetupSection
+      id="setup-organization-profile"
+      title={isArabic ? "ملف المنشأة والقالب التنظيمي" : "Business profile and organization template"}
+      description={isArabic
+        ? "أجب عن أسئلة عمل بسيطة أولًا. سيُنشئ النظام البنية التقنية المناسبة في الخلفية دون أن يطلب منك اختيار مصنع أو مجموعة مبيعات أو علاقات ERP يدويًا."
+        : "Start with business choices. The system creates the right technical structure in the background without asking you to configure ERP relationships manually."}
+    >
+      <div className="setup-template-grid" aria-label={isArabic ? "القوالب التنظيمية" : "Organization templates"}>
+        {templates.map((template) => {
+          const active = template.key === selectedTemplateKey;
+          return (
+            <button
+              key={template.key}
+              type="button"
+              className={`setup-template-card ${active ? "is-selected" : ""}`}
+              aria-pressed={active}
+              onClick={() => onTemplateChange(template.key)}
+              disabled={isApplied}
+            >
+              <strong>{templateLabel(template)}</strong>
+              <span>{isArabic ? template.description_ar : template.label_en}</span>
+              <small>{template.requires_inventory
+                ? (isArabic ? "يتضمن موقعًا ومخزونًا" : "Includes a site and inventory")
+                : (isArabic ? "لا يفرض مخزونًا" : "Does not require inventory")}</small>
+            </button>
+          );
+        })}
+      </div>
+
+      <div className="settings-form-grid setup-form-grid">
+        <SetupField id="setup-organization-size" label={isArabic ? "حجم المنشأة" : "Organization size"} required>
+          <SegmentedToggle
+            value={draft.organization_size}
+            options={sizeLabels}
+            onChange={(value) => onChange({ organization_size: value as OrganizationSize })}
+          />
+        </SetupField>
+        <SetupField id="setup-company-name" label={isArabic ? "اسم المنشأة القانونية" : "Legal company name"} required>
+          <input
+            id="setup-company-name"
+            className="setup-input"
+            value={draft.company_name}
+            onChange={(event) => onChange({ company_name: event.target.value })}
+            disabled={isApplied}
+            required
+          />
+        </SetupField>
+        <SetupField id="setup-company-code" label={isArabic ? "رمز المنشأة" : "Company code"} required>
+          <input
+            id="setup-company-code"
+            className="setup-input"
+            dir="ltr"
+            value={draft.company_code}
+            onChange={(event) => onChange({ company_code: normalizeCode(event.target.value) })}
+            disabled={isApplied}
+            required
+          />
+        </SetupField>
+        <SetupField id="setup-country-code" label={isArabic ? "الدولة / المنطقة" : "Country / region"} required>
+          <input
+            id="setup-country-code"
+            className="setup-input"
+            dir="ltr"
+            maxLength={2}
+            value={draft.country_code}
+            onChange={(event) => onChange({ country_code: event.target.value.toUpperCase() })}
+            disabled={isApplied}
+            required
+          />
+        </SetupField>
+        <SetupField id="setup-profile-currency" label={isArabic ? "عملة التشغيل" : "Operating currency"} required>
+          <SearchableSelect
+            id="setup-profile-currency"
+            className="setup-select"
+            value={draft.currency_id || null}
+            options={currencyOptions}
+            onChange={(value) => onChange({ currency_id: typeof value === "number" ? value : Number(value) || 0 })}
+            disabled={isApplied}
+          />
+        </SetupField>
+      </div>
+
+      {requiresInventory ? (
+        <div className="setup-template-subsection">
+          <div>
+            <h4>{isArabic ? "الموقع التشغيلي الأول" : "First operating site"}</h4>
+            <p>{isArabic
+              ? "سمِّ المتجر أو الفرع كما يعرفه فريقك. سيُترجم إلى موقع تشغيل تقني في الخلفية، وليس إلى مصنع بالضرورة."
+              : "Name the store or branch as your team knows it. It becomes a technical operating site in the background, not necessarily a factory."}</p>
+          </div>
+          <div className="settings-form-grid setup-form-grid">
+            <SetupField id="setup-primary-site-name" label={isArabic ? "اسم المتجر / الفرع" : "Store / branch name"} required>
+              <input
+                id="setup-primary-site-name"
+                className="setup-input"
+                value={draft.primary_site_name ?? ""}
+                onChange={(event) => onChange({ primary_site_name: event.target.value })}
+                disabled={isApplied}
+                required
+              />
+            </SetupField>
+            <SetupField id="setup-primary-site-code" label={isArabic ? "رمز المتجر / الفرع" : "Store / branch code"} required>
+              <input
+                id="setup-primary-site-code"
+                className="setup-input"
+                dir="ltr"
+                value={draft.primary_site_code ?? ""}
+                onChange={(event) => onChange({ primary_site_code: normalizeCode(event.target.value) })}
+                disabled={isApplied}
+                required
+              />
+            </SetupField>
+            <SetupField id="setup-profile-calendar" label={isArabic ? "تقويم تشغيل المتجر" : "Site operating calendar"} required>
+              <SearchableSelect
+                id="setup-profile-calendar"
+                className="setup-select"
+                value={draft.factory_calendar_id ?? null}
+                options={calendarOptions}
+                onChange={(value) => onChange({ factory_calendar_id: typeof value === "number" ? value : Number(value) || null })}
+                disabled={isApplied}
+              />
+            </SetupField>
+          </div>
+        </div>
+      ) : null}
+
+      <div className="setup-template-preview" aria-live="polite">
+        <strong>{isArabic ? "ما الذي سيُجهّز تلقائيًا؟" : "What will be prepared automatically?"}</strong>
+        <p>{selectedTemplate
+          ? selectedTemplate.generated_types.map((type) => type.replaceAll("_", " ")).join(" · ")
+          : (isArabic ? "اختر قالبًا أولًا." : "Choose a template first.")}</p>
+        <small>{isArabic
+          ? "تُضاف القنوات وفِرق المبيعات والموارد البشرية والمشاريع لاحقًا من مسار التوسع؛ لا يلزم إنشاؤها الآن."
+          : "Channels, sales teams, HR, and projects are added later through guided expansion, not during initial setup."}</small>
+      </div>
+
+      <div className="setup-actions">
+        <Button type="button" onClick={onSave} isLoading={isSaving} disabled={isApplied}>
+          {isArabic ? "حفظ ملف المنشأة" : "Save business profile"}
+        </Button>
+        <Button type="button" variant="secondary" onClick={onApply} isLoading={isSaving} disabled={!canApply || isApplied}>
+          {isApplied
+            ? (isArabic ? "تم تطبيق القالب" : "Template applied")
+            : (isArabic ? "تجهيز الهيكل الأساسي بأمان" : "Prepare the base structure safely")}
+        </Button>
+      </div>
+    </SetupSection>
+  );
+}
diff --git a/frontend/app/setup/components/SetupReadinessSummary.tsx b/frontend/app/setup/components/SetupReadinessSummary.tsx
index a7ffdff6..7f970cc6 100644
--- a/frontend/app/setup/components/SetupReadinessSummary.tsx
+++ b/frontend/app/setup/components/SetupReadinessSummary.tsx
@@ -1,5 +1,5 @@
 import { Button } from "@/components/ui";
-import { Readiness } from "../types";
+import { Onboarding, Readiness } from "../types";
 
 interface SetupReadinessSummaryProps {
   title: string;
@@ -9,6 +9,10 @@ interface SetupReadinessSummaryProps {
   completeLabel: string;
   incompleteLabel: string;
   readiness: Readiness | null;
+  onboarding?: Onboarding;
+  templateApplied?: boolean;
+  foundationLabel: string;
+  templateLabel: string;
   readinessLabels: Record<string, string>;
   isLoading: boolean;
   canOpenDashboard: boolean;
@@ -24,6 +28,10 @@ export function SetupReadinessSummary({
   completeLabel,
   incompleteLabel,
   readiness,
+  onboarding,
+  templateApplied = false,
+  foundationLabel,
+  templateLabel,
   readinessLabels,
   isLoading,
   canOpenDashboard,
@@ -31,6 +39,7 @@ export function SetupReadinessSummary({
   onOpenDashboard,
 }: SetupReadinessSummaryProps) {
   const checks = readiness?.checks ?? [];
+  const foundationReady = onboarding?.phases.foundation.ready;
   const statusClass = readiness?.ready ? "is-ready" : "is-blocked";
 
   return (
@@ -50,6 +59,14 @@ export function SetupReadinessSummary({
         </div>
       </div>
       <div className="setup-readiness-checks" aria-label={title}>
+        {foundationReady !== undefined ? (
+          <span className={`badge ${foundationReady ? "badge-success" : "badge-warning"}`}>
+            {foundationLabel}: {foundationReady ? completeLabel : incompleteLabel}
+          </span>
+        ) : null}
+        {templateApplied ? (
+          <span className="badge badge-success">{templateLabel}: {completeLabel}</span>
+        ) : null}
         {checks.map((check) => (
           <span
             key={check.key}
diff --git a/frontend/app/setup/page.tsx b/frontend/app/setup/page.tsx
index adda8ca3..e72e88d2 100644
--- a/frontend/app/setup/page.tsx
+++ b/frontend/app/setup/page.tsx
@@ -10,15 +10,28 @@ import { SetupAccountingSection } from "./components/SetupAccountingSection";
 import { SetupJourneyStepper, type SetupJourneyStepId } from "./components/SetupJourneyStepper";
 import { SetupModuleSelection } from "./components/SetupModuleSelection";
 import { SetupOperatingScopeSection } from "./components/SetupOperatingScopeSection";
-import { OrganizationArchitectureWorkspace } from "./components/OrganizationArchitectureWorkspace";
-import { OrganizationIntegrity, OrganizationMetaType, OrganizationNodeDraft, OrganizationTopologyRule, OrganizationWorkspaceNode } from "./components/organizationWorkspace.types";
+import { SetupOrganizationProfileSection } from "./components/SetupOrganizationProfileSection";
 import { SetupReadinessSummary } from "./components/SetupReadinessSummary";
-import { Item, Readiness, SetupState } from "./types";
+import { Item, OrganizationProfile, Readiness, SetupState } from "./types";
 
 const accountTypes = ["asset", "liability", "equity", "revenue", "expense"] as const;
 type AccountType = (typeof accountTypes)[number];
 const recordFields = { code: "code", name: "name" } as const;
-const PRIMARY_GENERAL_LEDGER_REFERENCE = "ACCORE-PRIMARY-GL";
+
+const emptyOrganizationProfile: OrganizationProfile = {
+  template_key: "",
+  industry: "",
+  organization_size: "small",
+  company_name: "",
+  company_code: "",
+  country_code: "SA",
+  currency_id: 0,
+  primary_site_name: "",
+  primary_site_code: "",
+  factory_calendar_id: null,
+  language: "ar-SA",
+  inventory_enabled: false,
+};
 
 function listFrom(response: unknown): Item[] {
   const payload = (response as { data?: unknown } | undefined)?.data;
@@ -41,18 +54,17 @@ export default function SetupPage() {
   const [isSaving, setIsSaving] = useState(false);
   const [readiness, setReadiness] = useState<Readiness | null>(null);
   const [setupState, setSetupState] = useState<SetupState | null>(null);
-  const [nodes, setNodes] = useState<OrganizationWorkspaceNode[]>([]);
-  const [metaTypes, setMetaTypes] = useState<OrganizationMetaType[]>([]);
-  const [topologyRules, setTopologyRules] = useState<OrganizationTopologyRule[]>([]);
-  const [organizationIntegrity, setOrganizationIntegrity] = useState<OrganizationIntegrity | null>(null);
   const [costCenters, setCostCenters] = useState<Item[]>([]);
   const [currencies, setCurrencies] = useState<Item[]>([]);
   const [factoryCalendars, setFactoryCalendars] = useState<Item[]>([]);
   const [accounts, setAccounts] = useState<Item[]>([]);
   const [periods, setPeriods] = useState<Item[]>([]);
   const [posTerminals, setPosTerminals] = useState<Item[]>([]);
+  const [nodes, setNodes] = useState<Item[]>([]);
   const [selectedModuleKeys, setSelectedModuleKeys] = useState<string[]>([]);
   const [journeyStep, setJourneyStep] = useState<SetupJourneyStepId>("foundation");
+  const [organizationProfile, setOrganizationProfile] = useState<OrganizationProfile>(emptyOrganizationProfile);
+  const [selectedTemplateKey, setSelectedTemplateKey] = useState("");
 
   const [accountCode, setAccountCode] = useState("");
   const [accountName, setAccountName] = useState("");
@@ -70,13 +82,10 @@ export default function SetupPage() {
   const load = useCallback(async () => {
     setIsLoading(true);
     try {
-      const [readinessResponse, setupResponse, nodesResponse, typesResponse, topologyResponse, integrityResponse, costsResponse, currenciesResponse, factoryCalendarsResponse, accountsResponse, periodsResponse, posTerminalsResponse] = await Promise.all([
+      const [readinessResponse, setupResponse, nodesResponse, costsResponse, currenciesResponse, factoryCalendarsResponse, accountsResponse, periodsResponse, posTerminalsResponse] = await Promise.all([
         fetchAPI<Readiness>(API_ENDPOINTS.ENTERPRISE_CORE.OPERATING_CONTEXT.READINESS),
         fetchAPI<SetupState>(API_ENDPOINTS.ENTERPRISE_CORE.SETUP.STATE),
         fetchAPI(API_ENDPOINTS.ENTERPRISE_CORE.ORG.NODES),
-        fetchAPI(API_ENDPOINTS.ENTERPRISE_CORE.ORG.META_TYPES),
-        fetchAPI<OrganizationTopologyRule[]>(API_ENDPOINTS.ENTERPRISE_CORE.ORG.TOPOLOGY_RULES),
-        fetchAPI<OrganizationIntegrity>(API_ENDPOINTS.ENTERPRISE_CORE.ORG.INTEGRITY_CHECK),
         fetchAPI(`${API_ENDPOINTS.FINANCE.COST_CENTERS.BASE}?limit=500`),
         fetchAPI(API_ENDPOINTS.FINANCE.FOREIGN_EXCHANGE.CURRENCIES.BASE),
         fetchAPI(API_ENDPOINTS.ENTERPRISE_CORE.ORG.FACTORY_CALENDARS),
@@ -89,10 +98,15 @@ export default function SetupPage() {
       const state = setupResponse.success ? setupResponse.data ?? null : null;
       setSetupState(state);
       setSelectedModuleKeys(state?.selected_module_keys ?? []);
-      setNodes(listFrom(nodesResponse) as OrganizationWorkspaceNode[]);
-      setMetaTypes(listFrom(typesResponse) as OrganizationMetaType[]);
-      setTopologyRules(listFrom(topologyResponse) as OrganizationTopologyRule[]);
-      setOrganizationIntegrity(integrityResponse.success ? integrityResponse.data ?? null : null);
+      const templateState = state?.organization_template;
+      const savedProfile = templateState?.profile;
+      if (savedProfile) {
+        setOrganizationProfile({ ...emptyOrganizationProfile, ...savedProfile });
+        setSelectedTemplateKey(savedProfile.template_key);
+      } else if (templateState?.templates[0]) {
+        setSelectedTemplateKey((current) => current || templateState.templates[0].key);
+      }
+      setNodes(listFrom(nodesResponse).filter((node) => node.status === "active"));
       setCostCenters(listFrom(costsResponse).filter((item) => item.is_active !== false));
       setCurrencies(listFrom(currenciesResponse).filter((item) => item.is_active !== false));
       setFactoryCalendars(listFrom(factoryCalendarsResponse).filter((item) => item.is_active !== false));
@@ -112,24 +126,25 @@ export default function SetupPage() {
 
   useEffect(() => { void load(); }, [load]);
 
-  const activeNodes = useMemo(() => nodes.filter((node) => node.status === "active"), [nodes]);
-  const workingUnitOptions = useMemo(() => activeNodes
-    .filter((node) => node.node_type_id === "COMP_CODE")
-    .map((node) => ({
-      value: node.node_uuid,
-      label: catalogText(i18n, "enterpriseCore.setup.nodeSummary", {
-        value0: node.code,
-        value1: node.meta_type?.display_name_ar || node.meta_type?.display_name || node.node_type_id,
-      }),
-    })), [activeNodes, i18n]);
+  const templateState = setupState?.organization_template;
+  const templateApplied = templateState?.is_applied === true;
+  const activeNodes = useMemo(() => nodes.filter((node) => text(node, "node_type_id") === "COMP_CODE"), [nodes]);
+  const workingUnitOptions = useMemo(() => activeNodes.map((node) => ({
+    value: text(node, "node_uuid"),
+    label: catalogText(i18n, "enterpriseCore.setup.nodeSummary", {
+      value0: text(node, "code"),
+      value1: text((node.meta_type as Item | undefined) ?? {}, locale === "ar-SA" ? "display_name_ar" : "display_name") || text(node, "node_type_id"),
+    }),
+  })), [activeNodes, i18n, locale]);
   const selectedWorkingUnitNode = useMemo(
-    () => nodes.find((node) => node.node_uuid === workingUnit) ?? null,
+    () => nodes.find((node) => text(node, "node_uuid") === workingUnit) ?? null,
     [nodes, workingUnit],
   );
   useEffect(() => {
     if (!selectedWorkingUnitNode) return;
-    setWorkingUnitCode(selectedWorkingUnitNode.code);
-    setWorkingUnitName(typeof selectedWorkingUnitNode.attributes_json?.name === "string" ? selectedWorkingUnitNode.attributes_json.name : "");
+    setWorkingUnitCode(text(selectedWorkingUnitNode, "code"));
+    const attributes = selectedWorkingUnitNode.attributes_json as Item | undefined;
+    setWorkingUnitName(text(attributes ?? {}, "name"));
   }, [selectedWorkingUnitNode]);
   const costOptions = useMemo(() => costCenters.map((center) => ({
     value: Number(center.id),
@@ -142,28 +157,14 @@ export default function SetupPage() {
     value: Number(terminal.id),
     label: [text(terminal, "code"), text(terminal, "name")].filter(Boolean).join(" — "),
   })), [posTerminals]);
-  const organizationReferenceOptions = useMemo(() => ({
-    currency_id: currencies.map((currency) => ({
-      value: Number(currency.id),
-      label: [text(currency, "code"), text(currency, "name")].filter(Boolean).join(" — "),
-      subtitle: text(currency, "symbol"),
-    })),
-    chart_of_accounts_id: (() => {
-      const activeTypes = new Set(accounts.map((account) => text(account, "account_type").toLowerCase()));
-      const hasGovernedLedger = accountTypes.every((type) => activeTypes.has(type));
-      if (!hasGovernedLedger) return [];
-      return [{
-        value: PRIMARY_GENERAL_LEDGER_REFERENCE,
-        label: i18n.catalog["enterpriseCore.orgWorkspace.reference.chartOfAccounts.primary"],
-        subtitle: catalogText(i18n, "enterpriseCore.orgWorkspace.reference.chartOfAccounts.summary", { value0: accounts.length, value1: activeTypes.size }),
-      }];
-    })(),
-    factory_calendar_id: factoryCalendars.map((calendar) => ({
-      value: Number(calendar.id),
-      label: [text(calendar, "code"), text(calendar, locale === "ar-SA" ? "name_ar" : "name")].filter(Boolean).join(" — "),
-      subtitle: [text(calendar, "country_code"), text(calendar, "time_zone")].filter(Boolean).join(" · "),
-    })),
-  }), [accounts, currencies, factoryCalendars, i18n, locale]);
+  const currencyOptions = useMemo(() => currencies.map((currency) => ({
+    value: Number(currency.id),
+    label: [text(currency, "code"), text(currency, "name")].filter(Boolean).join(" — "),
+  })), [currencies]);
+  const calendarOptions = useMemo(() => factoryCalendars.map((calendar) => ({
+    value: Number(calendar.id),
+    label: [text(calendar, "code"), text(calendar, locale === "ar-SA" ? "name_ar" : "name")].filter(Boolean).join(" — "),
+  })), [factoryCalendars, locale]);
 
   const callAndReload = async <T,>(action: () => Promise<{ success?: boolean; message?: string; data?: T }>): Promise<T | null> => {
     setIsSaving(true);
@@ -182,13 +183,15 @@ export default function SetupPage() {
     }
   };
 
-  const createOrganizationNode = async (draft: OrganizationNodeDraft): Promise<boolean> => {
-    const saved = await callAndReload<OrganizationWorkspaceNode>(() => fetchAPI<OrganizationWorkspaceNode>(API_ENDPOINTS.ENTERPRISE_CORE.ORG.NODES, {
+  const saveOrganizationProfile = async () => {
+    await callAndReload(() => fetchAPI(API_ENDPOINTS.ENTERPRISE_CORE.SETUP.ORGANIZATION_PROFILE, {
       method: "POST",
-      body: JSON.stringify({ ...draft, status: "active" }),
+      body: JSON.stringify({ ...organizationProfile, template_key: selectedTemplateKey }),
     }));
+  };
 
-    return saved !== null;
+  const applyOrganizationTemplate = async () => {
+    await callAndReload(() => fetchAPI(API_ENDPOINTS.ENTERPRISE_CORE.SETUP.APPLY_ORGANIZATION_TEMPLATE, { method: "POST" }));
   };
 
   const createAccount = async () => {
@@ -237,26 +240,17 @@ export default function SetupPage() {
     }));
   };
 
-  const selectWorkingUnit = (nodeUuid: string) => {
-    setWorkingUnit(nodeUuid);
-    const node = nodes.find((candidate) => candidate.node_uuid === nodeUuid);
-    setWorkingUnitCode(node?.code ?? "");
-    setWorkingUnitName(typeof node?.attributes_json?.name === "string" ? node.attributes_json.name : "");
-  };
-
   const saveWorkingUnit = async () => {
     if (!selectedWorkingUnitNode || !workingUnitCode.trim()) {
       showToast(i18n.catalog["enterpriseCore.setup.failedToSave"], "error");
       return;
     }
-    await callAndReload(() => fetchAPI(API_ENDPOINTS.ENTERPRISE_CORE.ORG.NODE(selectedWorkingUnitNode.node_uuid), {
+    const currentAttributes = (selectedWorkingUnitNode.attributes_json as Item | undefined) ?? {};
+    await callAndReload(() => fetchAPI(API_ENDPOINTS.ENTERPRISE_CORE.ORG.NODE(text(selectedWorkingUnitNode, "node_uuid")), {
       method: "PUT",
       body: JSON.stringify({
         code: workingUnitCode.trim(),
-        attributes: {
-          ...selectedWorkingUnitNode.attributes_json,
-          ...(workingUnitName.trim() ? { name: workingUnitName.trim() } : {}),
-        },
+        attributes: { ...currentAttributes, ...(workingUnitName.trim() ? { name: workingUnitName.trim() } : {}) },
       }),
     }));
   };
@@ -279,9 +273,9 @@ export default function SetupPage() {
   };
 
   const onboarding = setupState?.onboarding ?? readiness?.onboarding;
-  const canConfigureModules = onboarding?.phases.core_operations.ready === true;
   const foundationComplete = onboarding?.phases.foundation.ready === true;
   const operatingLinksComplete = onboarding?.phases.core_operations.ready === true;
+  const canConfigureModules = operatingLinksComplete;
 
   useEffect(() => {
     if (journeyStep === "operating_links" && !foundationComplete) setJourneyStep("foundation");
@@ -316,6 +310,10 @@ export default function SetupPage() {
         completeLabel={i18n.catalog["enterpriseCore.setup.complete"]}
         incompleteLabel={i18n.catalog["enterpriseCore.setup.incomplete"]}
         readiness={readiness}
+        onboarding={onboarding}
+        templateApplied={templateApplied}
+        foundationLabel={locale === "ar-SA" ? "الأساس التنظيمي" : "Organization foundation"}
+        templateLabel={locale === "ar-SA" ? "القالب التنظيمي" : "Organization template"}
         readinessLabels={readinessLabels}
         isLoading={isLoading}
         canOpenDashboard={readiness?.ready === true && setupState?.setup_required === false}
@@ -336,110 +334,120 @@ export default function SetupPage() {
         onNext={() => setJourneyStep((current) => current === "foundation" ? "operating_links" : "optional_capabilities")}
       />
       {journeyStep === "foundation" ? <>
-      <OrganizationArchitectureWorkspace
-        nodes={nodes}
-        metaTypes={metaTypes}
-        topologyRules={topologyRules}
-        integrity={organizationIntegrity}
-        isLoading={isLoading}
-        isSaving={isSaving}
-        referenceOptionsByAttribute={organizationReferenceOptions}
-        isReferenceDataLoading={isLoading}
-        onRefresh={() => void load()}
-        onCreateNode={createOrganizationNode}
-      />
-      <SetupAccountingSection
-        title={i18n.catalog["enterpriseCore.setup.accounting.title"]}
-        description={i18n.catalog["enterpriseCore.setup.accounting.description"]}
-        accountCodeLabel={i18n.catalog["enterpriseCore.setup.accounting.accountCode"]}
-        accountNameLabel={i18n.catalog["enterpriseCore.setup.accounting.accountName"]}
-        accountTypeLabel={i18n.catalog["enterpriseCore.setup.accounting.accountType"]}
-        createAccountLabel={i18n.catalog["enterpriseCore.setup.accounting.createAccount"]}
-        periodNameLabel={i18n.catalog["enterpriseCore.setup.accounting.periodName"]}
-        startDateLabel={i18n.catalog["enterpriseCore.setup.accounting.startDate"]}
-        endDateLabel={i18n.catalog["enterpriseCore.setup.accounting.endDate"]}
-        createPeriodLabel={i18n.catalog["enterpriseCore.setup.accounting.createPeriod"]}
-        accountCode={accountCode}
-        accountName={accountName}
-        accountType={accountType}
-        accountTypes={accountTypes}
-        accountTypeLabels={accountTypeLabels}
-        periodName={periodName}
-        periodStart={periodStart}
-        periodEnd={periodEnd}
-        recordSummary={catalogText(i18n, "enterpriseCore.setup.accounting.recordSummary", { value0: accounts.length, value1: periods.length })}
-        chartReady={readiness?.accounting_readiness?.chart_of_accounts.ready === true}
-        periodReady={readiness?.accounting_readiness?.open_fiscal_period.ready === true}
-        completeLabel={i18n.catalog["enterpriseCore.setup.complete"]}
-        isSaving={isSaving}
-        onAccountCodeChange={setAccountCode}
-        onAccountNameChange={setAccountName}
-        onAccountTypeChange={setAccountType}
-        onPeriodNameChange={setPeriodName}
-        onPeriodStartChange={setPeriodStart}
-        onPeriodEndChange={setPeriodEnd}
-        onCreateAccount={() => void createAccount()}
-        onCreatePeriod={() => void createPeriod()}
-      />
+        <SetupOrganizationProfileSection
+          templates={templateState?.templates ?? []}
+          selectedTemplateKey={selectedTemplateKey}
+          draft={organizationProfile}
+          currencyOptions={currencyOptions}
+          calendarOptions={calendarOptions}
+          isSaving={isSaving}
+          isApplied={templateApplied}
+          canApply={templateState?.can_apply === true && Boolean(selectedTemplateKey)}
+          onTemplateChange={(templateKey) => {
+            setSelectedTemplateKey(templateKey);
+            setOrganizationProfile((current) => ({ ...current, template_key: templateKey }));
+          }}
+          onChange={(changes) => setOrganizationProfile((current) => ({ ...current, ...changes }))}
+          onSave={() => void saveOrganizationProfile()}
+          onApply={() => void applyOrganizationTemplate()}
+        />
+        {templateApplied ? <p className="readiness-notice success">
+          {locale === "ar-SA"
+            ? "تم إنشاء الأساس التنظيمي للقالب. استخدم المصمم المتقدم لاحقًا لإضافة فروع أو قنوات أو فرق أو هياكل تخصصية."
+            : "The template foundation is ready. Use the advanced designer later for branches, channels, teams, and specialized structures."}
+        </p> : null}
+        <SetupAccountingSection
+          title={i18n.catalog["enterpriseCore.setup.accounting.title"]}
+          description={i18n.catalog["enterpriseCore.setup.accounting.description"]}
+          accountCodeLabel={i18n.catalog["enterpriseCore.setup.accounting.accountCode"]}
+          accountNameLabel={i18n.catalog["enterpriseCore.setup.accounting.accountName"]}
+          accountTypeLabel={i18n.catalog["enterpriseCore.setup.accounting.accountType"]}
+          createAccountLabel={i18n.catalog["enterpriseCore.setup.accounting.createAccount"]}
+          periodNameLabel={i18n.catalog["enterpriseCore.setup.accounting.periodName"]}
+          startDateLabel={i18n.catalog["enterpriseCore.setup.accounting.startDate"]}
+          endDateLabel={i18n.catalog["enterpriseCore.setup.accounting.endDate"]}
+          createPeriodLabel={i18n.catalog["enterpriseCore.setup.accounting.createPeriod"]}
+          accountCode={accountCode}
+          accountName={accountName}
+          accountType={accountType}
+          accountTypes={accountTypes}
+          accountTypeLabels={accountTypeLabels}
+          periodName={periodName}
+          periodStart={periodStart}
+          periodEnd={periodEnd}
+          recordSummary={catalogText(i18n, "enterpriseCore.setup.accounting.recordSummary", { value0: accounts.length, value1: periods.length })}
+          chartReady={readiness?.accounting_readiness?.chart_of_accounts.ready === true}
+          periodReady={readiness?.accounting_readiness?.open_fiscal_period.ready === true}
+          completeLabel={i18n.catalog["enterpriseCore.setup.complete"]}
+          isSaving={isSaving}
+          onAccountCodeChange={setAccountCode}
+          onAccountNameChange={setAccountName}
+          onAccountTypeChange={setAccountType}
+          onPeriodNameChange={setPeriodName}
+          onPeriodStartChange={setPeriodStart}
+          onPeriodEndChange={setPeriodEnd}
+          onCreateAccount={() => void createAccount()}
+          onCreatePeriod={() => void createPeriod()}
+        />
       </> : null}
       {journeyStep === "operating_links" ? (
-      <SetupOperatingScopeSection
-        title={i18n.catalog["enterpriseCore.setup.scope.title"]}
-        description={i18n.catalog["enterpriseCore.setup.scope.description"]}
-        foundationComplete={foundationComplete}
-        foundationRequiredLabel={i18n.catalog["enterpriseCore.setup.scope.foundationRequired"]}
-        workingUnitLabel={i18n.catalog["enterpriseCore.setup.scope.workingUnit"]}
-        workingUnitCodeLabel={i18n.catalog["enterpriseCore.setup.scope.workingUnitCode"]}
-        workingUnitNameLabel={i18n.catalog["enterpriseCore.setup.scope.workingUnitName"]}
-        saveWorkingUnitLabel={i18n.catalog["enterpriseCore.setup.scope.saveWorkingUnit"]}
-        costCenterLabel={i18n.catalog["enterpriseCore.setup.scope.costCenter"]}
-        pointOfSaleLabel={i18n.catalog["enterpriseCore.setup.scope.pointOfSale"]}
-        contextHelper={i18n.catalog["enterpriseCore.setup.scope.contextHelper"]}
-        saveLabel={i18n.catalog["enterpriseCore.setup.scope.save"]}
-        workingUnit={workingUnit}
-        workingUnitCode={workingUnitCode}
-        workingUnitName={workingUnitName}
-        costCenterId={costCenterId}
-        posTerminalId={posTerminalId}
-        nodeOptions={workingUnitOptions}
-        costOptions={costOptions}
-        posOptions={posOptions}
-        isSaving={isSaving}
-        onWorkingUnitChange={selectWorkingUnit}
-        onWorkingUnitCodeChange={setWorkingUnitCode}
-        onWorkingUnitNameChange={setWorkingUnitName}
-        onSaveWorkingUnit={() => void saveWorkingUnit()}
-        onCostCenterChange={setCostCenterId}
-        onPosTerminalChange={setPosTerminalId}
-        onSave={() => void saveContext()}
-      />
+        <SetupOperatingScopeSection
+          title={i18n.catalog["enterpriseCore.setup.scope.title"]}
+          description={i18n.catalog["enterpriseCore.setup.scope.description"]}
+          foundationComplete={foundationComplete}
+          foundationRequiredLabel={i18n.catalog["enterpriseCore.setup.scope.foundationRequired"]}
+          workingUnitLabel={i18n.catalog["enterpriseCore.setup.scope.workingUnit"]}
+          workingUnitCodeLabel={i18n.catalog["enterpriseCore.setup.scope.workingUnitCode"]}
+          workingUnitNameLabel={i18n.catalog["enterpriseCore.setup.scope.workingUnitName"]}
+          saveWorkingUnitLabel={i18n.catalog["enterpriseCore.setup.scope.saveWorkingUnit"]}
+          costCenterLabel={i18n.catalog["enterpriseCore.setup.scope.costCenter"]}
+          pointOfSaleLabel={i18n.catalog["enterpriseCore.setup.scope.pointOfSale"]}
+          contextHelper={i18n.catalog["enterpriseCore.setup.scope.contextHelper"]}
+          saveLabel={i18n.catalog["enterpriseCore.setup.scope.save"]}
+          workingUnit={workingUnit}
+          workingUnitCode={workingUnitCode}
+          workingUnitName={workingUnitName}
+          costCenterId={costCenterId}
+          posTerminalId={posTerminalId}
+          nodeOptions={workingUnitOptions}
+          costOptions={costOptions}
+          posOptions={posOptions}
+          isSaving={isSaving}
+          onWorkingUnitChange={setWorkingUnit}
+          onWorkingUnitCodeChange={setWorkingUnitCode}
+          onWorkingUnitNameChange={setWorkingUnitName}
+          onSaveWorkingUnit={() => void saveWorkingUnit()}
+          onCostCenterChange={setCostCenterId}
+          onPosTerminalChange={setPosTerminalId}
+          onSave={() => void saveContext()}
+        />
       ) : null}
       {journeyStep === "optional_capabilities" ? (
-      <SetupModuleSelection
-        locale={locale}
-        modules={setupState?.modules ?? []}
-        selectedModuleKeys={selectedModuleKeys}
-        coreModuleKeys={onboarding?.starter_module_keys ?? []}
-        canActivate={canConfigureModules}
-        title={i18n.catalog["enterpriseCore.setup.modules.title"]}
-        description={i18n.catalog["enterpriseCore.setup.modules.description"]}
-        coreTitle={i18n.catalog["enterpriseCore.setup.modules.coreTitle"]}
-        coreDescription={i18n.catalog["enterpriseCore.setup.modules.coreDescription"]}
-        optionalTitle={i18n.catalog["enterpriseCore.setup.modules.optionalTitle"]}
-        optionalDescription={i18n.catalog["enterpriseCore.setup.modules.optionalDescription"]}
-        baselineRequiredLabel={i18n.catalog["enterpriseCore.setup.modules.baselineRequired"]}
-        saveSelectionLabel={i18n.catalog["enterpriseCore.setup.modules.saveSelection"]}
-        activateSelectedLabel={i18n.catalog["enterpriseCore.setup.modules.activateSelected"]}
-        notSelectedLabel={i18n.catalog["enterpriseCore.setup.modules.notSelected"]}
-        pendingReadinessLabel={i18n.catalog["enterpriseCore.setup.modules.pendingReadiness"]}
-        activeLabel={i18n.catalog["enterpriseCore.setup.modules.active"]}
-        selectionRequiredLabel={i18n.catalog["enterpriseCore.setup.modules.selectionRequired"]}
-        noRecordsLabel={i18n.catalog["enterpriseCore.setup.noRecords"]}
-        isSaving={isSaving}
-        onToggle={toggleModule}
-        onSave={() => void saveModuleSelection()}
-        onActivate={() => void activateSelectedModules()}
-      />
+        <SetupModuleSelection
+          locale={locale}
+          modules={setupState?.modules ?? []}
+          selectedModuleKeys={selectedModuleKeys}
+          coreModuleKeys={onboarding?.starter_module_keys ?? []}
+          canActivate={canConfigureModules}
+          title={i18n.catalog["enterpriseCore.setup.modules.title"]}
+          description={i18n.catalog["enterpriseCore.setup.modules.description"]}
+          coreTitle={i18n.catalog["enterpriseCore.setup.modules.coreTitle"]}
+          coreDescription={i18n.catalog["enterpriseCore.setup.modules.coreDescription"]}
+          optionalTitle={i18n.catalog["enterpriseCore.setup.modules.optionalTitle"]}
+          optionalDescription={i18n.catalog["enterpriseCore.setup.modules.optionalDescription"]}
+          baselineRequiredLabel={i18n.catalog["enterpriseCore.setup.modules.baselineRequired"]}
+          saveSelectionLabel={i18n.catalog["enterpriseCore.setup.modules.saveSelection"]}
+          activateSelectedLabel={i18n.catalog["enterpriseCore.setup.modules.activateSelected"]}
+          notSelectedLabel={i18n.catalog["enterpriseCore.setup.modules.notSelected"]}
+          pendingReadinessLabel={i18n.catalog["enterpriseCore.setup.modules.pendingReadiness"]}
+          activeLabel={i18n.catalog["enterpriseCore.setup.modules.active"]}
+          selectionRequiredLabel={i18n.catalog["enterpriseCore.setup.modules.selectionRequired"]}
+          noRecordsLabel={i18n.catalog["enterpriseCore.setup.noRecords"]}
+          isSaving={isSaving}
+          onToggle={toggleModule}
+          onSave={() => void saveModuleSelection()}
+          onActivate={() => void activateSelectedModules()}
+        />
       ) : null}
     </div>
   );
diff --git a/frontend/app/setup/types.ts b/frontend/app/setup/types.ts
index 4ed3c0b7..d0f420a7 100644
--- a/frontend/app/setup/types.ts
+++ b/frontend/app/setup/types.ts
@@ -29,6 +29,42 @@ export type Onboarding = {
   };
 };
 
+export type OrganizationSize = "micro" | "small" | "medium" | "enterprise";
+
+export type OrganizationProfile = {
+  template_key: string;
+  industry: string;
+  organization_size: OrganizationSize;
+  company_name: string;
+  company_code: string;
+  country_code: string;
+  currency_id: number;
+  primary_site_name?: string;
+  primary_site_code?: string;
+  factory_calendar_id?: number | null;
+  language?: "ar-SA" | "en-US";
+  inventory_enabled: boolean;
+  applied_at?: string | null;
+  created_nodes?: Record<string, string>;
+};
+
+export type OrganizationTemplate = {
+  key: string;
+  industry: string;
+  requires_inventory: boolean;
+  label_ar: string;
+  label_en: string;
+  description_ar: string;
+  generated_types: string[];
+};
+
+export type OrganizationTemplateState = {
+  profile: OrganizationProfile | null;
+  templates: OrganizationTemplate[];
+  is_applied: boolean;
+  can_apply: boolean;
+};
+
 export type Readiness = {
   ready: boolean;
   context?: {
@@ -79,6 +115,7 @@ export type SetupState = {
   active_module_keys: string[];
   pending_module_keys: string[];
   modules: SetupModule[];
+  organization_template?: OrganizationTemplateState;
 };
 
 export type SelectOption = {
diff --git a/frontend/lib/endpoints/enterprise-core.ts b/frontend/lib/endpoints/enterprise-core.ts
index 416f032e..48bb2182 100644
--- a/frontend/lib/endpoints/enterprise-core.ts
+++ b/frontend/lib/endpoints/enterprise-core.ts
@@ -40,6 +40,9 @@ export interface EnterpriseCoreEndpoints {
     };
     SETUP: {
         STATE: string;
+        ORGANIZATION_TEMPLATES: string;
+        ORGANIZATION_PROFILE: string;
+        APPLY_ORGANIZATION_TEMPLATE: string;
         MODULES: string;
         ACTIVATE_SELECTED: string;
     };
@@ -124,6 +127,9 @@ export const ENTERPRISE_CORE: EnterpriseCoreEndpoints = {
     },
     SETUP: {
         STATE: "/v2/setup/state",
+        ORGANIZATION_TEMPLATES: "/v2/setup/organization-templates",
+        ORGANIZATION_PROFILE: "/v2/setup/organization-profile",
+        APPLY_ORGANIZATION_TEMPLATE: "/v2/setup/apply-organization-template",
         MODULES: "/v2/setup/modules",
         ACTIVATE_SELECTED: "/v2/setup/activate-selected",
     },
diff --git a/frontend/tests/app/setup-onboarding.test.ts b/frontend/tests/app/setup-onboarding.test.ts
index 392cdba8..2d138a98 100644
--- a/frontend/tests/app/setup-onboarding.test.ts
+++ b/frontend/tests/app/setup-onboarding.test.ts
@@ -5,7 +5,7 @@ import { describe, expect, it } from "vitest";
 const root = path.resolve(__dirname, "../..");
 const source = (relativePath: string) => fs.readFileSync(path.join(root, relativePath), "utf8");
 
-describe("standalone phased setup onboarding", () => {
+describe("profile-driven setup onboarding", () => {
   it("keeps setup outside the operational MainLayout and protects it with its own authenticated shell", () => {
     const page = source("app/setup/page.tsx");
     const layout = source("app/setup/layout.tsx");
@@ -16,7 +16,7 @@ describe("standalone phased setup onboarding", () => {
     expect(layout).toContain("setup_required");
   });
 
-  it("renders one guarded guided-setup journey before optional capability activation", () => {
+  it("renders one guarded journey before optional capability activation", () => {
     const page = source("app/setup/page.tsx");
     const moduleSelection = source("app/setup/components/SetupModuleSelection.tsx");
     const journey = source("app/setup/components/SetupJourneyStepper.tsx");
@@ -28,126 +28,78 @@ describe("standalone phased setup onboarding", () => {
     expect(journey).toContain("onNext");
     expect(moduleSelection).toContain("coreModuleKeys");
     expect(moduleSelection).toContain("canActivate");
-    expect(moduleSelection).toContain("setup-module-group-included");
-    expect(moduleSelection).toContain("optionalTitle");
   });
 
-  it("refreshes readiness after every successful save and edits existing operating links instead of recreating resources", () => {
+  it("starts from a business profile and safely applies a generated organization template", () => {
     const page = source("app/setup/page.tsx");
+    const profile = source("app/setup/components/SetupOrganizationProfileSection.tsx");
+    const endpoints = source("lib/endpoints/enterprise-core.ts");
+
+    expect(page).toContain("<SetupOrganizationProfileSection");
+    expect(page).toContain("SETUP.ORGANIZATION_PROFILE");
+    expect(page).toContain("SETUP.APPLY_ORGANIZATION_TEMPLATE");
+    expect(page).not.toContain("<OrganizationArchitectureWorkspace");
+    expect(profile).toContain("SegmentedToggle");
+    expect(profile).toContain("setup-template-card");
+    expect(profile).toContain("primary_site_name");
+    expect(profile).toContain("factory_calendar_id");
+    expect(endpoints).toContain("ORGANIZATION_TEMPLATES");
+    expect(endpoints).toContain("APPLY_ORGANIZATION_TEMPLATE");
+  });
+
+  it("refreshes readiness after every successful save and exposes foundation/template state in the header", () => {
+    const page = source("app/setup/page.tsx");
+    const summary = source("app/setup/components/SetupReadinessSummary.tsx");
     const scope = source("app/setup/components/SetupOperatingScopeSection.tsx");
-    const accounting = source("app/setup/components/SetupAccountingSection.tsx");
-    const englishCatalog = source("lib/i18n/catalog/en-US.ts");
 
     expect(page).toContain("await load();");
-    expect(page).toContain("pos_terminal_id: posTerminalId");
-    expect(page).toContain("saveWorkingUnit");
+    expect(page).toContain("templateApplied={templateApplied}");
+    expect(page).toContain("onboarding={onboarding}");
+    expect(summary).toContain("foundationReady");
+    expect(summary).toContain("templateApplied");
     expect(scope).toContain("posTerminalId");
     expect(scope).not.toContain("warehouseCode");
     expect(scope).not.toContain("profitCenterId");
-    expect(accounting).toContain("chartReady");
-    expect(accounting).toContain("periodReady");
-    expect(englishCatalog).toContain("Profit-center ownership remains on the organizational unit");
   });
 
-  it("uses the professional organizational architecture workspace rather than the flat node form", () => {
+  it("uses controlled reference data for organization profile currency and calendar", () => {
     const page = source("app/setup/page.tsx");
-    const workspace = source("app/setup/components/OrganizationArchitectureWorkspace.tsx");
-
-    expect(page).toContain("<OrganizationArchitectureWorkspace");
-    expect(page).not.toContain("<SetupOrganizationSection");
-    expect(page).toContain("ORG.TOPOLOGY_RULES");
-    expect(page).toContain("ORG.INTEGRITY_CHECK");
-    expect(workspace).toContain("ORG.SCOPE_CONTEXT");
-    expect(workspace).toContain("selectedTypeRules");
-    expect(workspace).toContain("linkTargetsByRule");
-    expect(workspace).toContain("links:");
-    expect(workspace).toContain("foundation");
-    expect(workspace).toContain("core_operations");
-    expect(workspace).toContain("extensions");
-  });
-
-  it("resolves organizational attribute keys to bilingual professional labels", () => {
-    const workspace = source("app/setup/components/OrganizationArchitectureWorkspace.tsx");
-    const englishCatalog = source("lib/i18n/catalog/en-US.ts");
-    const arabicCatalog = source("lib/i18n/catalog/ar-SA.ts");
-
-    expect(workspace).toContain("ATTRIBUTE_LABEL_KEYS");
-    expect(workspace).toContain("labelForAttribute(attribute.attribute_key)");
-    expect(workspace).toContain("readableAttributeFallback");
-    expect(workspace).not.toContain("{attribute.attribute_key}{attribute.is_mandatory");
-    expect(englishCatalog).toMatch(
-      /['"]enterpriseCore\.orgWorkspace\.attribute\.countryCode['"]:\s*['"]Country \/ region code['"]/
-    );
-    expect(englishCatalog).toMatch(
-      /['"]enterpriseCore\.orgWorkspace\.attribute\.fiscalYearVariant['"]:\s*['"]Fiscal year structure['"]/
-    );
-    expect(arabicCatalog).toMatch(
-      /['"]enterpriseCore\.orgWorkspace\.attribute\.countryCode['"]:\s*['"]رمز الدولة أو الإقليم['"]/
-    );
-    expect(arabicCatalog).toMatch(
-      /['"]enterpriseCore\.orgWorkspace\.attribute\.fiscalYearVariant['"]:\s*['"]هيكل السنة المالية['"]/
-    );
-  });
-
-  it("loads organizational currencies and chart-of-account references from live financial records", () => {
-    const page = source("app/setup/page.tsx");
-    const workspace = source("app/setup/components/OrganizationArchitectureWorkspace.tsx");
-    const englishCatalog = source("lib/i18n/catalog/en-US.ts");
-    const arabicCatalog = source("lib/i18n/catalog/ar-SA.ts");
+    const profile = source("app/setup/components/SetupOrganizationProfileSection.tsx");
 
     expect(page).toContain("FINANCE.FOREIGN_EXCHANGE.CURRENCIES.BASE");
-    expect(page).toContain("organizationReferenceOptions");
-    expect(page).toContain("currency_id: currencies.map");
-    expect(page).toContain("PRIMARY_GENERAL_LEDGER_REFERENCE");
-    expect(page).toMatch(/setAccounts\(listFrom\(accountsResponse\)\.filter\(\(item\) => item\.is_active !== false\)\)/);
-    expect(page).toContain("hasGovernedLedger");
-    expect(workspace).toContain("referenceOptionsByAttribute");
-    expect(workspace).toContain("SearchableSelect");
-    expect(workspace).toContain("referenceHelpForAttribute");
-    expect(englishCatalog).toContain("Only active currencies defined in Currency Management are offered");
-    expect(englishCatalog).toContain("This is not a choice of one posting account");
-    expect(arabicCatalog).toContain("لا يستخدم النظام قائمة عملات افتراضية");
-    expect(arabicCatalog).toContain("لا يمثل هذا اختيار حساب ترحيل مفرد");
+    expect(page).toContain("ORG.FACTORY_CALENDARS");
+    expect(page).toContain("currencyOptions");
+    expect(page).toContain("calendarOptions");
+    expect(profile).toContain("SearchableSelect");
+    expect(profile).toContain("setup-profile-currency");
+    expect(profile).toContain("setup-profile-calendar");
   });
 
-  it("uses a controlled fiscal-year structure rather than an unbounded free-text value", () => {
-    const workspace = source("app/setup/components/OrganizationArchitectureWorkspace.tsx");
-    const englishCatalog = source("lib/i18n/catalog/en-US.ts");
-    const arabicCatalog = source("lib/i18n/catalog/ar-SA.ts");
+  it("keeps the raw organizational graph in the advanced designer instead of onboarding", () => {
+    const page = source("app/setup/page.tsx");
+    const workspace = source("app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/components/NodeFormPanel.tsx");
 
-    expect(workspace).toMatch(/const CALENDAR_YEAR_VARIANT = ['"]K4['"]/);
-    expect(workspace).toMatch(/attribute\.attribute_key === ['"]fiscal_year_variant['"]/);
-    expect(workspace).toContain("fiscalYearVariant.calendarYear");
-    expect(englishCatalog).toContain("Fiscal year structure");
-    expect(arabicCatalog).toContain("هيكل السنة المالية");
+    expect(page).not.toContain("OrganizationArchitectureWorkspace");
+    expect(workspace).toContain("topologyRules");
+    expect(workspace).toContain("dynamicAttrs");
+    expect(workspace).toContain("target_node_uuid");
   });
 
-  it("loads factory calendars from controlled reference data for plants", () => {
+  it("retains controlled accounting and operating-context components", () => {
     const page = source("app/setup/page.tsx");
-    const workspace = source("app/setup/components/OrganizationArchitectureWorkspace.tsx");
-    const englishCatalog = source("lib/i18n/catalog/en-US.ts");
-    const arabicCatalog = source("lib/i18n/catalog/ar-SA.ts");
+    const accounting = source("app/setup/components/SetupAccountingSection.tsx");
 
-    expect(page).toContain("ORG.FACTORY_CALENDARS");
-    expect(page).toContain("factory_calendar_id: factoryCalendars.map");
-    expect(workspace).toMatch(/ReferenceAttributeKey\s*=\s*[^;]*['"]factory_calendar_id['"]/);
-    expect(workspace).toContain("reference.factoryCalendar.help");
-    expect(englishCatalog).toContain("arbitrary calendar codes are not accepted");
-    expect(arabicCatalog).toContain("لا يسمح النظام بإدخال رمز تقويم حر");
+    expect(page).toContain("<SetupAccountingSection");
+    expect(page).toContain("<SetupOperatingScopeSection");
+    expect(accounting).toContain("chartReady");
+    expect(accounting).toContain("periodReady");
   });
 
-  it("exposes interface-language settings from the setup shell while keeping company-code language controlled and separate", () => {
+  it("exposes interface-language settings from the setup shell", () => {
     const layout = source("app/setup/layout.tsx");
-    const workspace = source("app/setup/components/OrganizationArchitectureWorkspace.tsx");
-    const englishCatalog = source("lib/i18n/catalog/en-US.ts");
-    const arabicCatalog = source("lib/i18n/catalog/ar-SA.ts");
 
     expect(layout).toContain("setup-top-utility");
     expect(layout).toContain("ApplicationLanguageSettingsTab");
-    expect(workspace).toContain("SUPPORTED_LANGUAGE_OPTIONS");
-    expect(workspace).toMatch(/attribute\.attribute_key === ['"]language['"]/);
-    expect(englishCatalog).toContain("It does not change the current user's application interface language");
-    expect(arabicCatalog).toContain("ولا تغيّر لغة واجهة التطبيق للمستخدم الحالي");
   });
 
   it("emits setup in the static catch-all parameter set", () => {

From 93f42ff2869b79db305580a7c5f3588feef44130 Mon Sep 17 00:00:00 2001
From: Emran025 <1.48263577e+08+Emran025@users.noreply.github.com>
Date: Sat, 22 Aug 2026 20:59:13 +0000
Subject: [PATCH 8/9] refactor(setup): refine enterprise workflow and smart
 input direction

---
 docs/Plans/enterprise-setup-ux-principles.md  |  24 ++
 frontend/app/globals.css                      |  68 ++++--
 .../SetupOrganizationProfileSection.tsx       | 224 ++++++++++--------
 frontend/app/setup/page.tsx                   |  24 +-
 frontend/components/ui/Input.tsx              |  84 +++----
 frontend/components/ui/SearchableSelect.tsx   |   8 +-
 frontend/components/ui/Textarea.tsx           |  93 +++-----
 .../components/shared-input-direction.test.ts |  36 +++
 8 files changed, 318 insertions(+), 243 deletions(-)
 create mode 100644 docs/Plans/enterprise-setup-ux-principles.md
 create mode 100644 frontend/tests/components/shared-input-direction.test.ts

diff --git a/docs/Plans/enterprise-setup-ux-principles.md b/docs/Plans/enterprise-setup-ux-principles.md
new file mode 100644
index 00000000..d43d253a
--- /dev/null
+++ b/docs/Plans/enterprise-setup-ux-principles.md
@@ -0,0 +1,24 @@
+# Enterprise setup UX principles
+
+## Source-informed decisions
+
+The setup experience should use one coherent responsive implementation across desktop, tablet, and mobile, while progressively reducing low-priority complexity on narrower screens. SAP Fiori recommends responsive controls and a mobile-first approach; it also recommends an adaptive reduction of complexity when a desktop workflow cannot be presented unchanged on smaller devices. [1]
+
+The layout should use repeatable spacing, constrained reading width, predictable grouping, and responsive reflow. Fluent explains that consistent spacing establishes relationships and hierarchy, and that layouts should reposition, resize, reflow, or progressively disclose content according to viewport size. [2]
+
+The setup should keep labels visible, provide concise helper text for format or business context, use selection controls rather than free-form entry where values are governed, and keep related controls aligned in a form grid. These decisions follow Carbon’s enterprise form guidance. [3]
+
+## Applied rules
+
+1. The guided setup will have a stable, single-column reading flow with a constrained maximum width and a single primary action per phase.
+2. Template choice will be a concise overview with progressive detail; the advanced organization designer remains outside onboarding.
+3. Profile fields will use visible labels and helper text, with responsive reflow from paired columns to one column.
+4. Smart text direction is a component behavior: `dir="auto"` and content-aware alignment will follow the first strong character of a user-entered value. Technical fields retain a forced left-to-right direction.
+5. The existing component library remains the first choice. Global selectors in `globals.css` are used only to compose those components into setup-specific layouts.
+6. Status is shown as a layered progression: business profile, organization foundation, operating context, and enabled capabilities. A global final-ready state must not conceal a completed intermediate state.
+
+## References
+
+[1]: https://www.sap.com/design-system/fiori-design-web/v1-96/discover/sap-design-system/vision-and-mission/responsiveness-adaptiveness "SAP Fiori responsive and adaptive design"
+[2]: https://fluent2.microsoft.design/layout "Fluent 2 layout guidance"
+[3]: https://carbondesignsystem.com/components/form/usage/ "Carbon form usage guidance"
diff --git a/frontend/app/globals.css b/frontend/app/globals.css
index c6ae8852..81ad2cf7 100644
--- a/frontend/app/globals.css
+++ b/frontend/app/globals.css
@@ -2459,18 +2459,14 @@ tbody tr:hover {
 }
 
 .searchable-select input[type="text"] {
-  padding-left: 2.5rem !important;
-  padding-right: 2.5rem !important;
-  transition: all 0.3s ease;
-}
-
-[dir="rtl"] .searchable-select input[type="text"] {
-  padding-right: 2.5rem !important;
-  padding-left: 2.5rem !important;
+  padding-inline: 2.5rem !important;
+  text-align: start;
+  transition: border-color 0.2s ease, box-shadow 0.2s ease;
 }
 
 .searchable-select .input-icon {
   position: absolute;
+  inset-inline-start: 0.85rem;
   top: 50%;
   transform: translateY(-50%);
   color: var(--primary-color);
@@ -2482,16 +2478,6 @@ tbody tr:hover {
   z-index: 2;
 }
 
-[dir="rtl"] .searchable-select .input-icon {
-  right: 0.85rem;
-  left: auto;
-}
-
-[dir="ltr"] .searchable-select .input-icon {
-  left: 0.85rem;
-  right: auto;
-}
-
 .searchable-select .clear-btn {
   position: absolute;
   top: 50%;
@@ -2517,14 +2503,8 @@ tbody tr:hover {
   color: var(--danger-color);
 }
 
-[dir="rtl"] .searchable-select .clear-btn {
-  left: 0.75rem !important;
-  right: auto !important;
-}
-
-[dir="ltr"] .searchable-select .clear-btn {
-  right: 0.75rem !important;
-  left: auto !important;
+.searchable-select .clear-btn {
+  inset-inline-end: 0.75rem;
 }
 
 .options-list {
@@ -7552,3 +7532,39 @@ body.nav-sidebar-is-collapsed .sidebar-toggle-btn {
 .setup-template-preview small { color: var(--text-secondary); font-size: 0.76rem; line-height: 1.5; }
 @media (max-width: 768px) { .setup-template-grid { grid-template-columns: 1fr; } .setup-template-card { min-height: 0; } }
 @media (prefers-reduced-motion: reduce) { .setup-template-card { transition: none; } .setup-template-card:hover:not(:disabled), .setup-template-card:focus-visible { transform: none; } }
+
+/* Shared content-aware input direction */
+.input-wrapper { position: relative; width: 100%; }
+.input-direction-aware { text-align: start; unicode-bidi: plaintext; }
+.input-wrapper > .input-direction-aware.has-input-icon { padding-inline-start: 3rem; }
+.input-wrapper > .input-direction-aware.has-clear-action { padding-inline-end: 2.75rem; }
+.input-wrapper > .input-icon { position: absolute; inset-inline-start: 0.75rem; top: 50%; display: flex; align-items: center; justify-content: center; transform: translateY(-50%); color: var(--text-muted); pointer-events: none; }
+.input-wrapper > .input-icon-top { top: 1rem; transform: none; }
+.input-wrapper > .clear-btn { position: absolute; inset-inline-end: 0.65rem; top: 50%; display: inline-flex; align-items: center; justify-content: center; width: 1.85rem; height: 1.85rem; padding: 0; border: 0; border-radius: 50%; background: transparent; color: var(--text-muted); cursor: pointer; transform: translateY(-50%); }
+.input-wrapper > .clear-btn:hover, .input-wrapper > .clear-btn:focus-visible { background: var(--primary-subtle); color: var(--primary-color); outline: none; }
+.input-wrapper > .clear-btn-top { top: 0.9rem; transform: none; }
+.app-textarea { display: block; width: 100%; min-height: 5rem; padding: 0.75rem 1rem; resize: vertical; border: 1px solid var(--border-color); border-radius: var(--radius-md); background: var(--surface-white); color: var(--text-primary); font: inherit; line-height: 1.5; }
+.app-textarea:focus-visible { border-color: var(--primary-color); outline: 2px solid var(--primary-subtle); outline-offset: 1px; }
+.app-textarea.has-error { border-color: var(--danger-color); }
+.form-label { display: block; margin-bottom: 0.35rem; color: var(--text-primary); font-size: 0.84rem; font-weight: 700; line-height: 1.4; }
+.input-error-message { margin: 0.35rem 0 0; color: var(--danger-color); font-size: 0.8rem; line-height: 1.45; }
+
+/* Enterprise setup: stable workflow composition */
+.settings-wrapper.setup-workflow { width: min(100%, 78rem); margin-inline: auto; }
+.setup-section { scroll-margin-top: 1.25rem; }
+.setup-profile-block { display: grid; gap: 1rem; padding-block: 0.25rem 1.25rem; }
+.setup-profile-block + .setup-profile-block { padding-top: 1.25rem; border-top: 1px solid var(--border-color); }
+.setup-profile-heading { display: flex; align-items: flex-start; gap: 0.75rem; max-width: 52rem; }
+.setup-profile-heading h3 { margin: 0; color: var(--text-primary); font-size: 0.98rem; line-height: 1.4; }
+.setup-profile-heading p { margin: 0.2rem 0 0; color: var(--text-secondary); font-size: 0.82rem; line-height: 1.55; }
+.setup-profile-step { display: grid; flex: 0 0 auto; place-items: center; width: 1.7rem; height: 1.7rem; border-radius: 50%; background: var(--primary-subtle); color: var(--primary-color); font-size: 0.78rem; font-weight: 800; }
+.setup-template-grid { grid-template-columns: repeat(auto-fit, minmax(14rem, 1fr)); }
+.setup-template-card { min-height: 11rem; text-align: start; }
+.setup-template-card:focus-visible { outline: 2px solid var(--primary-color); outline-offset: 2px; }
+.setup-template-subsection { margin-top: 0; }
+.setup-template-preview { margin-top: 0; }
+.setup-template-summary-list { display: flex; flex-wrap: wrap; gap: 0.45rem; }
+.setup-template-summary-list span { padding: 0.3rem 0.55rem; border: 1px solid color-mix(in srgb, var(--primary-color) 20%, transparent); border-radius: 999px; color: var(--text-primary); background: var(--surface-white); font-size: 0.76rem; font-weight: 700; line-height: 1.3; }
+.setup-actions-primary { position: sticky; bottom: 0.75rem; z-index: 3; justify-content: flex-end; padding: 0.75rem; border: 1px solid var(--border-color); border-radius: var(--radius-md); background: color-mix(in srgb, var(--surface-white) 92%, transparent); box-shadow: var(--shadow-sm); backdrop-filter: blur(8px); }
+@media (max-width: 1023px) { .settings-wrapper.setup-workflow { width: 100%; } .setup-template-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); } }
+@media (max-width: 639px) { .setup-profile-heading { gap: 0.6rem; } .setup-template-grid { grid-template-columns: 1fr; } .setup-template-card { min-height: 0; } .setup-actions-primary { position: static; flex-direction: column; } .setup-actions-primary .btn { width: 100%; } }
diff --git a/frontend/app/setup/components/SetupOrganizationProfileSection.tsx b/frontend/app/setup/components/SetupOrganizationProfileSection.tsx
index 48fee99f..47a96002 100644
--- a/frontend/app/setup/components/SetupOrganizationProfileSection.tsx
+++ b/frontend/app/setup/components/SetupOrganizationProfileSection.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { Button, SearchableSelect, SegmentedToggle } from "@/components/ui";
+import { Button, Input, SearchableSelect, SegmentedToggle } from "@/components/ui";
 import { useI18n } from "@/lib/i18n";
 import { SetupField } from "./SetupField";
 import { SetupSection } from "./SetupSection";
@@ -30,6 +30,18 @@ const sizeOptions: { value: OrganizationSize; ar: string; en: string }[] = [
   { value: "enterprise", ar: "كبيرة / مؤسسية", en: "Enterprise" },
 ];
 
+const generatedStructureLabels: Record<string, { ar: string; en: string }> = {
+  CLIENT: { ar: "العميل المؤسسي", en: "Enterprise client" },
+  COMP_CODE: { ar: "المنشأة القانونية", en: "Legal company" },
+  CONTROLLING_AREA: { ar: "النطاق الرقابي", en: "Controlling scope" },
+  COST_CENTER: { ar: "مركز التكلفة", en: "Cost center" },
+  PROFIT_CENTER: { ar: "مركز الربح", en: "Profit center" },
+  PLANT: { ar: "المتجر أو الفرع", en: "Store or site" },
+  STORAGE_LOC: { ar: "مخزون الموقع", en: "Site inventory" },
+  PURCH_ORG: { ar: "مشتريات المنشأة", en: "Company purchasing" },
+  SALES_ORG: { ar: "مبيعات المنشأة", en: "Company sales" },
+};
+
 function normalizeCode(value: string): string {
   return value.toUpperCase().replace(/\s+/g, "-");
 }
@@ -54,101 +66,125 @@ export function SetupOrganizationProfileSection({
   const requiresInventory = selectedTemplate?.requires_inventory === true;
   const templateLabel = (template: OrganizationTemplate) => isArabic ? template.label_ar : template.label_en;
   const sizeLabels = sizeOptions.map((option) => ({ value: option.value, label: isArabic ? option.ar : option.en }));
+  const generatedLabels = selectedTemplate?.generated_types.map((type) =>
+    generatedStructureLabels[type]?.[isArabic ? "ar" : "en"] ?? type,
+  ) ?? [];
 
   return (
     <SetupSection
       id="setup-organization-profile"
-      title={isArabic ? "ملف المنشأة والقالب التنظيمي" : "Business profile and organization template"}
+      title={isArabic ? "ابدأ بنموذج عملك" : "Start with your business model"}
       description={isArabic
-        ? "أجب عن أسئلة عمل بسيطة أولًا. سيُنشئ النظام البنية التقنية المناسبة في الخلفية دون أن يطلب منك اختيار مصنع أو مجموعة مبيعات أو علاقات ERP يدويًا."
-        : "Start with business choices. The system creates the right technical structure in the background without asking you to configure ERP relationships manually."}
+        ? "اختر النموذج الأقرب إلى عملك ثم أدخل معلومات المنشأة الأساسية. سيُنشئ النظام الهيكل التقني المناسب في الخلفية، دون أن يطلب منك التعامل مع مصطلحات ERP المتخصصة."
+        : "Choose the model closest to your business, then provide the essential company details. The system creates the appropriate technical structure in the background."}
     >
-      <div className="setup-template-grid" aria-label={isArabic ? "القوالب التنظيمية" : "Organization templates"}>
-        {templates.map((template) => {
-          const active = template.key === selectedTemplateKey;
-          return (
-            <button
-              key={template.key}
-              type="button"
-              className={`setup-template-card ${active ? "is-selected" : ""}`}
-              aria-pressed={active}
-              onClick={() => onTemplateChange(template.key)}
-              disabled={isApplied}
-            >
-              <strong>{templateLabel(template)}</strong>
-              <span>{isArabic ? template.description_ar : template.label_en}</span>
-              <small>{template.requires_inventory
-                ? (isArabic ? "يتضمن موقعًا ومخزونًا" : "Includes a site and inventory")
-                : (isArabic ? "لا يفرض مخزونًا" : "Does not require inventory")}</small>
-            </button>
-          );
-        })}
-      </div>
+      <section className="setup-profile-block" aria-labelledby="setup-template-choice-heading">
+        <div className="setup-profile-heading">
+          <span className="setup-profile-step">1</span>
+          <div>
+            <h3 id="setup-template-choice-heading">{isArabic ? "اختر طريقة عمل المنشأة" : "Choose how the business operates"}</h3>
+            <p>{isArabic ? "يمكنك إضافة الفروع والقنوات وفرق المبيعات لاحقًا، ولا تحتاج إلى تعريفها عند البداية." : "Branches, channels, and sales teams can be added later; they are not required at the start."}</p>
+          </div>
+        </div>
+        <div className="setup-template-grid" aria-label={isArabic ? "القوالب التنظيمية" : "Organization templates"}>
+          {templates.map((template) => {
+            const active = template.key === selectedTemplateKey;
+            return (
+              <button
+                key={template.key}
+                type="button"
+                className={`setup-template-card ${active ? "is-selected" : ""}`}
+                aria-pressed={active}
+                onClick={() => onTemplateChange(template.key)}
+                disabled={isApplied}
+              >
+                <strong>{templateLabel(template)}</strong>
+                <span>{isArabic ? template.description_ar : template.label_en}</span>
+                <small>{template.requires_inventory
+                  ? (isArabic ? "يتضمن موقعًا ومخزونًا" : "Includes a site and inventory")
+                  : (isArabic ? "لا يفرض مخزونًا" : "Does not require inventory")}</small>
+              </button>
+            );
+          })}
+        </div>
+      </section>
 
-      <div className="settings-form-grid setup-form-grid">
-        <SetupField id="setup-organization-size" label={isArabic ? "حجم المنشأة" : "Organization size"} required>
-          <SegmentedToggle
-            value={draft.organization_size}
-            options={sizeLabels}
-            onChange={(value) => onChange({ organization_size: value as OrganizationSize })}
-          />
-        </SetupField>
-        <SetupField id="setup-company-name" label={isArabic ? "اسم المنشأة القانونية" : "Legal company name"} required>
-          <input
-            id="setup-company-name"
-            className="setup-input"
-            value={draft.company_name}
-            onChange={(event) => onChange({ company_name: event.target.value })}
-            disabled={isApplied}
-            required
-          />
-        </SetupField>
-        <SetupField id="setup-company-code" label={isArabic ? "رمز المنشأة" : "Company code"} required>
-          <input
-            id="setup-company-code"
-            className="setup-input"
-            dir="ltr"
-            value={draft.company_code}
-            onChange={(event) => onChange({ company_code: normalizeCode(event.target.value) })}
-            disabled={isApplied}
-            required
-          />
-        </SetupField>
-        <SetupField id="setup-country-code" label={isArabic ? "الدولة / المنطقة" : "Country / region"} required>
-          <input
-            id="setup-country-code"
-            className="setup-input"
-            dir="ltr"
-            maxLength={2}
-            value={draft.country_code}
-            onChange={(event) => onChange({ country_code: event.target.value.toUpperCase() })}
-            disabled={isApplied}
-            required
-          />
-        </SetupField>
-        <SetupField id="setup-profile-currency" label={isArabic ? "عملة التشغيل" : "Operating currency"} required>
-          <SearchableSelect
-            id="setup-profile-currency"
-            className="setup-select"
-            value={draft.currency_id || null}
-            options={currencyOptions}
-            onChange={(value) => onChange({ currency_id: typeof value === "number" ? value : Number(value) || 0 })}
-            disabled={isApplied}
-          />
-        </SetupField>
-      </div>
+      <section className="setup-profile-block" aria-labelledby="setup-company-details-heading">
+        <div className="setup-profile-heading">
+          <span className="setup-profile-step">2</span>
+          <div>
+            <h3 id="setup-company-details-heading">{isArabic ? "أدخل بيانات المنشأة" : "Enter company details"}</h3>
+            <p>{isArabic ? "الحقول ذات الرمز * مطلوبة لتأسيس الهيكل الأول. يتكيف اتجاه الكتابة مع لغة النص الذي تدخله." : "Fields marked with * are needed to establish the first structure. Text direction follows the language you type."}</p>
+          </div>
+        </div>
+        <div className="settings-form-grid setup-form-grid">
+          <SetupField id="setup-organization-size" label={isArabic ? "حجم المنشأة" : "Organization size"} required>
+            <SegmentedToggle
+              value={draft.organization_size}
+              options={sizeLabels}
+              onChange={(value) => onChange({ organization_size: value as OrganizationSize })}
+            />
+          </SetupField>
+          <SetupField id="setup-company-name" label={isArabic ? "اسم المنشأة القانونية" : "Legal company name"} required>
+            <Input
+              id="setup-company-name"
+              className="setup-input"
+              value={draft.company_name}
+              onChange={(event) => onChange({ company_name: event.target.value })}
+              disabled={isApplied}
+              required
+            />
+          </SetupField>
+          <SetupField id="setup-company-code" label={isArabic ? "رمز المنشأة" : "Company code"} required>
+            <Input
+              id="setup-company-code"
+              className="setup-input"
+              dir="ltr"
+              value={draft.company_code}
+              onChange={(event) => onChange({ company_code: normalizeCode(event.target.value) })}
+              disabled={isApplied}
+              required
+            />
+          </SetupField>
+          <SetupField id="setup-country-code" label={isArabic ? "الدولة / المنطقة" : "Country / region"} required>
+            <Input
+              id="setup-country-code"
+              className="setup-input"
+              dir="ltr"
+              maxLength={2}
+              value={draft.country_code}
+              onChange={(event) => onChange({ country_code: event.target.value.toUpperCase() })}
+              disabled={isApplied}
+              required
+            />
+          </SetupField>
+          <SetupField id="setup-profile-currency" label={isArabic ? "عملة التشغيل" : "Operating currency"} required>
+            <SearchableSelect
+              id="setup-profile-currency"
+              className="setup-select"
+              value={draft.currency_id || null}
+              options={currencyOptions}
+              onChange={(value) => onChange({ currency_id: typeof value === "number" ? value : Number(value) || 0 })}
+              disabled={isApplied}
+            />
+          </SetupField>
+        </div>
+      </section>
 
       {requiresInventory ? (
-        <div className="setup-template-subsection">
-          <div>
-            <h4>{isArabic ? "الموقع التشغيلي الأول" : "First operating site"}</h4>
-            <p>{isArabic
-              ? "سمِّ المتجر أو الفرع كما يعرفه فريقك. سيُترجم إلى موقع تشغيل تقني في الخلفية، وليس إلى مصنع بالضرورة."
-              : "Name the store or branch as your team knows it. It becomes a technical operating site in the background, not necessarily a factory."}</p>
+        <section className="setup-template-subsection" aria-labelledby="setup-site-details-heading">
+          <div className="setup-profile-heading">
+            <span className="setup-profile-step">3</span>
+            <div>
+              <h3 id="setup-site-details-heading">{isArabic ? "عرّف الموقع التشغيلي الأول" : "Define the first operating site"}</h3>
+              <p>{isArabic
+                ? "سمِّ المتجر أو الفرع كما يعرفه فريقك. سيُترجم إلى موقع تشغيل تقني في الخلفية، وليس إلى مصنع بالضرورة."
+                : "Name the store or branch as your team knows it. It becomes a technical operating site in the background, not necessarily a factory."}</p>
+            </div>
           </div>
           <div className="settings-form-grid setup-form-grid">
             <SetupField id="setup-primary-site-name" label={isArabic ? "اسم المتجر / الفرع" : "Store / branch name"} required>
-              <input
+              <Input
                 id="setup-primary-site-name"
                 className="setup-input"
                 value={draft.primary_site_name ?? ""}
@@ -158,7 +194,7 @@ export function SetupOrganizationProfileSection({
               />
             </SetupField>
             <SetupField id="setup-primary-site-code" label={isArabic ? "رمز المتجر / الفرع" : "Store / branch code"} required>
-              <input
+              <Input
                 id="setup-primary-site-code"
                 className="setup-input"
                 dir="ltr"
@@ -179,20 +215,22 @@ export function SetupOrganizationProfileSection({
               />
             </SetupField>
           </div>
-        </div>
+        </section>
       ) : null}
 
-      <div className="setup-template-preview" aria-live="polite">
+      <aside className="setup-template-preview" aria-live="polite">
         <strong>{isArabic ? "ما الذي سيُجهّز تلقائيًا؟" : "What will be prepared automatically?"}</strong>
-        <p>{selectedTemplate
-          ? selectedTemplate.generated_types.map((type) => type.replaceAll("_", " ")).join(" · ")
-          : (isArabic ? "اختر قالبًا أولًا." : "Choose a template first.")}</p>
+        {generatedLabels.length > 0 ? (
+          <div className="setup-template-summary-list">
+            {generatedLabels.map((label) => <span key={label}>{label}</span>)}
+          </div>
+        ) : <p>{isArabic ? "اختر قالبًا أولًا." : "Choose a template first."}</p>}
         <small>{isArabic
-          ? "تُضاف القنوات وفِرق المبيعات والموارد البشرية والمشاريع لاحقًا من مسار التوسع؛ لا يلزم إنشاؤها الآن."
+          ? "تُضاف القنوات وفرق المبيعات والموارد البشرية والمشاريع لاحقًا من مسار التوسع؛ لا يلزم إنشاؤها الآن."
           : "Channels, sales teams, HR, and projects are added later through guided expansion, not during initial setup."}</small>
-      </div>
+      </aside>
 
-      <div className="setup-actions">
+      <div className="setup-actions setup-actions-primary">
         <Button type="button" onClick={onSave} isLoading={isSaving} disabled={isApplied}>
           {isArabic ? "حفظ ملف المنشأة" : "Save business profile"}
         </Button>
diff --git a/frontend/app/setup/page.tsx b/frontend/app/setup/page.tsx
index e72e88d2..4cd7e444 100644
--- a/frontend/app/setup/page.tsx
+++ b/frontend/app/setup/page.tsx
@@ -326,9 +326,27 @@ export default function SetupPage() {
         nextLabel={i18n.catalog["common.general.next"]}
         completeLabel={i18n.catalog["enterpriseCore.setup.complete"]}
         steps={[
-          { id: "foundation", title: i18n.catalog["enterpriseCore.setup.phase.foundation"], description: i18n.catalog["enterpriseCore.setup.phase.foundationDescription"], complete: foundationComplete, enabled: true },
-          { id: "operating_links", title: i18n.catalog["enterpriseCore.setup.phase.coreOperations"], description: i18n.catalog["enterpriseCore.setup.phase.coreOperationsDescription"], complete: operatingLinksComplete, enabled: foundationComplete },
-          { id: "optional_capabilities", title: i18n.catalog["enterpriseCore.setup.phase.moduleActivation"], description: i18n.catalog["enterpriseCore.setup.phase.moduleActivationDescription"], complete: onboarding?.starter_bundle_active === true, enabled: operatingLinksComplete },
+          {
+            id: "foundation",
+            title: locale === "ar-SA" ? "تأسيس المنشأة" : "Establish the organization",
+            description: locale === "ar-SA" ? "اختر نموذج العمل وأنشئ الأساس التنظيمي والمحاسبي." : "Choose the business model and establish the organizational and accounting foundation.",
+            complete: foundationComplete,
+            enabled: true,
+          },
+          {
+            id: "operating_links",
+            title: locale === "ar-SA" ? "تجهيز التشغيل اليومي" : "Prepare daily operations",
+            description: locale === "ar-SA" ? "اربط موقع العمل ونقطة البيع ومركز التكلفة عندما يتطلبها نموذج العمل." : "Connect the work site, point of sale, and cost center when the business model requires them.",
+            complete: operatingLinksComplete,
+            enabled: foundationComplete,
+          },
+          {
+            id: "optional_capabilities",
+            title: locale === "ar-SA" ? "وسّع أعمالك" : "Expand your business",
+            description: locale === "ar-SA" ? "فعّل القدرات التي تحتاجها فقط؛ الفروع والقنوات والفرق تُضاف لاحقًا بمسارات موجهة." : "Enable only the capabilities you need; branches, channels, and teams are added later through guided flows.",
+            complete: onboarding?.starter_bundle_active === true,
+            enabled: operatingLinksComplete,
+          },
         ]}
         onPrevious={() => setJourneyStep((current) => current === "optional_capabilities" ? "operating_links" : "foundation")}
         onNext={() => setJourneyStep((current) => current === "foundation" ? "operating_links" : "optional_capabilities")}
diff --git a/frontend/components/ui/Input.tsx b/frontend/components/ui/Input.tsx
index 2d616ab0..934a2f89 100644
--- a/frontend/components/ui/Input.tsx
+++ b/frontend/components/ui/Input.tsx
@@ -1,9 +1,9 @@
 "use client";
 
 import { catalogMessage } from "@/lib/i18n";
-import { useState, useRef, forwardRef } from "react";
+import { forwardRef, useState } from "react";
 import { Icon, IconName } from "@/lib/icons";
-import { isArabic as checkIsArabic } from "@/lib/utils";
+import { getTextDirection } from "@/lib/utils";
 
 export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
     icon?: IconName;
@@ -11,6 +11,10 @@ export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement>
     containerClassName?: string;
 }
 
+function valueAsText(value: React.InputHTMLAttributes<HTMLInputElement>["value"]): string {
+    return typeof value === "string" || typeof value === "number" ? String(value) : "";
+}
+
 export const Input = forwardRef<HTMLInputElement, InputProps>(({
     className = "",
     containerClassName = "",
@@ -19,86 +23,54 @@ export const Input = forwardRef<HTMLInputElement, InputProps>(({
     value,
     onChange,
     type = "text",
+    dir,
+    style,
     ...props
 }, ref) => {
-    const [isArabic, setIsArabic] = useState(false);
-    const containerRef = useRef<HTMLDivElement>(null);
+    const [uncontrolledValue, setUncontrolledValue] = useState("");
+    const explicitDirection = dir === "rtl" || dir === "ltr" ? dir : null;
+    const textValue = value === undefined ? uncontrolledValue : valueAsText(value);
+    const textDirection = explicitDirection ?? getTextDirection(textValue);
 
-    // Detect text direction based on input
-    const handleInputChange = (e: React.ChangeEvent<HTMLInputElement>) => {
-        const val = e.target.value;
-        // Check if starts with Arabic char
-        setIsArabic(checkIsArabic(val));
-
-        if (onChange) {
-            onChange(e);
+    const handleInputChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+        if (value === undefined) {
+            setUncontrolledValue(event.target.value);
         }
+        onChange?.(event);
     };
 
-    // Determine padding based on icon presence
-    // In LTR: Icon usually on Left. In RTL: Icon usually on Right.
-    // But Login page seems to force LTR and put icon on Left.
-    // We will stick to the generic design: Icon on "Start"?
-    // The previous code put icon at the bottom? No.
-
     return (
-        <div className={`input-wrapper ${containerClassName}`} ref={containerRef} style={{ position: "relative", width: "100%" }}>
+        <div className={`input-wrapper ${containerClassName}`.trim()} dir={textDirection}>
             <input
                 ref={ref}
                 type={type}
-                className={`${className}`}
-                style={{
-                    direction: isArabic ? "rtl" : "ltr",
-                    textAlign: isArabic ? "right" : "left",
-                    paddingLeft: icon ? "3rem" : "1rem", // Assuming generic style needs space for icon
-                }}
+                className={`input-direction-aware ${icon ? "has-input-icon" : ""} ${className}`.trim()}
+                dir={textDirection}
+                style={style}
                 value={value}
                 onChange={handleInputChange}
                 {...props}
             />
-            {icon && (
-                <div className="input-icon" style={{
-                    position: "absolute",
-                    left: "10px",
-                    top: "50%",
-                    transform: "translateY(-50%)",
-                    color: "var(--text-light)",
-                    pointerEvents: "none", // standard for icon
-                    display: "flex",
-                    alignItems: "center",
-                    justifyContent: "center"
-                }}>
+            {icon ? (
+                <span className="input-icon" aria-hidden="true">
                     <Icon name={icon} size={18} />
-                </div>
-            )}
-            {value && onClear && (
+                </span>
+            ) : null}
+            {valueAsText(value) && onClear ? (
                 <button
                     type="button"
-                    onClick={(e) => {
-                        e.stopPropagation();
+                    onClick={(event) => {
+                        event.stopPropagation();
                         onClear();
                     }}
                     className="clear-btn"
                     title={catalogMessage("common.general.clear")}
-                    style={{
-                        position: "absolute",
-                        right: "10px", // Clear button on right?
-                        top: "50%",
-                        transform: "translateY(-50%)",
-                        background: "none",
-                        border: "none",
-                        cursor: "pointer",
-                        color: "var(--text-light)"
-                    }}
                 >
                     <Icon name="x" size={16} />
                 </button>
-            )}
+            ) : null}
         </div>
     );
 });
 
 Input.displayName = "Input";
-
-
-
diff --git a/frontend/components/ui/SearchableSelect.tsx b/frontend/components/ui/SearchableSelect.tsx
index dca3a95d..9ac504bf 100644
--- a/frontend/components/ui/SearchableSelect.tsx
+++ b/frontend/components/ui/SearchableSelect.tsx
@@ -191,7 +191,7 @@ export function SearchableSelect({
     const textDirection = getTextDirection(displayValue);
 
     return (
-        <div className={`searchable-select ${className}`} ref={containerRef}>
+        <div className={`searchable-select ${className}`} ref={containerRef} dir={textDirection}>
             <input
                 ref={inputRef}
                 type="text"
@@ -205,13 +205,11 @@ export function SearchableSelect({
                 disabled={disabled}
                 autoComplete="off"
                 required={required && !value}
+                dir={textDirection}
+                className={`input-direction-aware ${value && !isOpen ? "has-clear-action" : ""}`}
                 style={{
                     paddingTop: paddingVertical ? (paddingVertical + "rem") : undefined,
                     paddingBottom: paddingVertical ? (paddingVertical + "rem") : undefined,
-                    direction: textDirection,
-                    textAlign: textDirection === "rtl" ? "right" : "left",
-                    paddingLeft: "3rem",
-                    paddingRight: (value && !isOpen) ? "2.5rem" : "1rem"
                 }}
             />
             <div className="input-icon">
diff --git a/frontend/components/ui/Textarea.tsx b/frontend/components/ui/Textarea.tsx
index 06611b37..538398f9 100644
--- a/frontend/components/ui/Textarea.tsx
+++ b/frontend/components/ui/Textarea.tsx
@@ -1,9 +1,9 @@
 "use client";
 
 import { catalogMessage } from "@/lib/i18n";
-import { useState, useRef, forwardRef } from "react";
+import { forwardRef, useState } from "react";
 import { Icon, IconName } from "@/lib/icons";
-import { isArabic as checkIsArabic } from "@/lib/utils";
+import { getTextDirection } from "@/lib/utils";
 
 export interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextAreaElement> {
     label?: string;
@@ -13,6 +13,10 @@ export interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextArea
     containerClassName?: string;
 }
 
+function valueAsText(value: React.TextareaHTMLAttributes<HTMLTextAreaElement>["value"]): string {
+    return typeof value === "string" || typeof value === "number" ? String(value) : "";
+}
+
 export const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(({
     className = "",
     containerClassName = "",
@@ -23,89 +27,58 @@ export const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(({
     onClear,
     value,
     onChange,
+    dir,
+    style,
     ...props
 }, ref) => {
-    const [isArabic, setIsArabic] = useState(false);
-    const containerRef = useRef<HTMLDivElement>(null);
+    const [uncontrolledValue, setUncontrolledValue] = useState("");
+    const explicitDirection = dir === "rtl" || dir === "ltr" ? dir : null;
+    const textValue = value === undefined ? uncontrolledValue : valueAsText(value);
+    const textDirection = explicitDirection ?? getTextDirection(textValue);
 
-    // Detect text direction based on input
-    const handleInputChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
-        const val = e.target.value;
-        setIsArabic(checkIsArabic(val));
-
-        if (onChange) {
-            onChange(e);
+    const handleInputChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+        if (value === undefined) {
+            setUncontrolledValue(event.target.value);
         }
+        onChange?.(event);
     };
 
     return (
-        <div className={`form-group ${containerClassName}`} style={{ width: "100%" }}>
-            {label && <label htmlFor={id} className="block text-sm font-medium text-gray-700 mb-1">{label}</label>}
-
-            <div className="input-wrapper" ref={containerRef} style={{ position: "relative", width: "100%" }}>
+        <div className={`form-group ${containerClassName}`.trim()}>
+            {label ? <label htmlFor={id} className="form-label">{label}</label> : null}
+            <div className="input-wrapper" dir={textDirection}>
                 <textarea
                     ref={ref}
                     id={id}
-                    className={`searchable-select ${className} ${error ? "border-red-500 focus:border-red-500" : ""}`}
-                    style={{
-                        minHeight: "80px",
-                        resize: "vertical",
-                        width: "100%",
-                        padding: "0.75rem 1rem",
-                        paddingLeft: icon ? "3rem" : "1rem",
-                        borderRadius: "var(--radius-md)",
-                        border: "1px solid var(--border-color)",
-                        backgroundColor: "#fff",
-                        direction: isArabic ? "rtl" : "ltr",
-                        textAlign: isArabic ? "right" : "left",
-                    }}
+                    className={`input-direction-aware app-textarea ${icon ? "has-input-icon" : ""} ${className} ${error ? "has-error" : ""}`.trim()}
+                    dir={textDirection}
+                    style={style}
                     value={value}
                     onChange={handleInputChange}
                     {...props}
                 />
-
-                {icon && (
-                    <div className="input-icon" style={{
-                        position: "absolute",
-                        left: "10px",
-                        top: "1rem",
-                        color: "var(--text-light)",
-                        pointerEvents: "none",
-                        display: "flex",
-                        alignItems: "center",
-                        justifyContent: "center"
-                    }}>
+                {icon ? (
+                    <span className="input-icon input-icon-top" aria-hidden="true">
                         <Icon name={icon} size={18} />
-                    </div>
-                )}
-
-                {value && onClear && (
+                    </span>
+                ) : null}
+                {valueAsText(value) && onClear ? (
                     <button
                         type="button"
-                        onClick={(e) => {
-                            e.stopPropagation();
+                        onClick={(event) => {
+                            event.stopPropagation();
                             onClear();
                         }}
-                        className="clear-btn"
+                        className="clear-btn clear-btn-top"
                         title={catalogMessage("common.general.clear")}
-                        style={{
-                            position: "absolute",
-                            right: "10px",
-                            top: "1rem",
-                            background: "none",
-                            border: "none",
-                            cursor: "pointer",
-                            color: "var(--text-light)"
-                        }}
                     >
                         <Icon name="x" size={16} />
                     </button>
-                )}
+                ) : null}
             </div>
-
-            {error && <p className="text-red-500 text-sm mt-1">{error}</p>}
+            {error ? <p className="input-error-message">{error}</p> : null}
         </div>
     );
 });
 
-Textarea.displayName = "Textarea";
\ No newline at end of file
+Textarea.displayName = "Textarea";
diff --git a/frontend/tests/components/shared-input-direction.test.ts b/frontend/tests/components/shared-input-direction.test.ts
new file mode 100644
index 00000000..f44f799e
--- /dev/null
+++ b/frontend/tests/components/shared-input-direction.test.ts
@@ -0,0 +1,36 @@
+import fs from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+const root = path.resolve(__dirname, "../..");
+const source = (relativePath: string) => fs.readFileSync(path.join(root, relativePath), "utf8");
+
+describe("shared content-aware input direction", () => {
+  it("uses the first strong Unicode letter while preserving an explicit technical direction", () => {
+    const utility = source("lib/utils.ts");
+    const input = source("components/ui/Input.tsx");
+    const textarea = source("components/ui/Textarea.tsx");
+
+    expect(utility).toContain("first strong Unicode letter");
+    expect(input).toContain("const explicitDirection");
+    expect(input).toContain("const textDirection = explicitDirection ?? getTextDirection(textValue)");
+    expect(input).toContain("dir={textDirection}");
+    expect(textarea).toContain("const explicitDirection");
+    expect(textarea).toContain("const textDirection = explicitDirection ?? getTextDirection(textValue)");
+    expect(textarea).toContain("dir={textDirection}");
+  });
+
+  it("applies direction to the control wrapper so decorations move with the typed language", () => {
+    const input = source("components/ui/Input.tsx");
+    const textarea = source("components/ui/Textarea.tsx");
+    const select = source("components/ui/SearchableSelect.tsx");
+    const styles = source("app/globals.css");
+
+    expect(input).toContain('className={`input-wrapper ${containerClassName}`.trim()} dir={textDirection}');
+    expect(textarea).toContain('className="input-wrapper" dir={textDirection}');
+    expect(select).toContain('className={`searchable-select ${className}`} ref={containerRef} dir={textDirection}');
+    expect(styles).toContain(".input-direction-aware");
+    expect(styles).toContain("inset-inline-start");
+    expect(styles).toContain("inset-inline-end");
+  });
+});

From 0ba954193356bbd060efae3229e7eefab4e0a5be Mon Sep 17 00:00:00 2001
From: Emran025 <1.48263577e+08+Emran025@users.noreply.github.com>
Date: Sat, 22 Aug 2026 22:42:07 +0000
Subject: [PATCH 9/9] fix(quality): remediate reported lint and workflow
 findings

---
 .github/workflows/agent-task-governance.yml   |  4 +-
 .github/workflows/desktop.yml                 |  8 +--
 .github/workflows/lint.yml                    |  4 +-
 .github/workflows/tests.yml                   |  8 +--
 docs/Plans/quality-remediation-notes-ar.md    | 30 +++++++++++
 .../batch-processing/(pages)/page.tsx         | 36 ++++++-------
 .../recurring-transactions/(pages)/page.tsx   | 15 +++---
 .../org-hierarchy/(pages)/page.tsx            | 50 +++++++++++++++----
 .../components/ChangeHistoryTab.tsx           |  2 +-
 .../org-hierarchy/components/HierarchyTab.tsx | 23 +++------
 .../org-hierarchy/components/NodesTab.tsx     | 12 +++--
 .../components/ScopeContextTab.tsx            | 19 ++++---
 .../global-dashboard/(pages)/page.tsx         | 13 ++---
 13 files changed, 136 insertions(+), 88 deletions(-)
 create mode 100644 docs/Plans/quality-remediation-notes-ar.md

diff --git a/.github/workflows/agent-task-governance.yml b/.github/workflows/agent-task-governance.yml
index 946de9e2..32f97021 100644
--- a/.github/workflows/agent-task-governance.yml
+++ b/.github/workflows/agent-task-governance.yml
@@ -26,10 +26,10 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
           node-version: 22
           cache: npm
diff --git a/.github/workflows/desktop.yml b/.github/workflows/desktop.yml
index 1cf9e73b..e9828c73 100644
--- a/.github/workflows/desktop.yml
+++ b/.github/workflows/desktop.yml
@@ -49,7 +49,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Install Linux desktop dependencies
         if: matrix.platform == 'ubuntu-22.04'
@@ -60,7 +60,7 @@ jobs:
           sudo timeout --foreground 8m apt-get -o Acquire::Retries=3 -o Acquire::http::Timeout=60 -o Acquire::https::Timeout=60 install -y --no-install-recommends libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf xdg-utils
 
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
           node-version: 22
           cache: npm
@@ -252,10 +252,10 @@ jobs:
 
     steps:
       - name: Checkout release metadata generator
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set up Node.js for manifest generation
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
           node-version: 22
 
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index a01717a7..1f2dd6a4 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout Code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       # - name: Setup PHP
       #   uses: shivammathur/setup-php@v2
@@ -30,7 +30,7 @@ jobs:
       #   run: composer install -q --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist
 
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
           node-version: 22
           cache: npm
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 37b55204..71f9e245 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - name: Install Rust toolchain
         uses: dtolnay/rust-toolchain@stable
@@ -47,7 +47,7 @@ jobs:
         options: --health-cmd="mysqladmin ping" --health-interval=10s --health-timeout=5s --health-retries=3
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v5
 
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
@@ -89,13 +89,13 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - name: Install Rust toolchain
         uses: dtolnay/rust-toolchain@stable
 
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
           node-version: 22
           cache: npm
diff --git a/docs/Plans/quality-remediation-notes-ar.md b/docs/Plans/quality-remediation-notes-ar.md
new file mode 100644
index 00000000..d5a67fbc
--- /dev/null
+++ b/docs/Plans/quality-remediation-notes-ar.md
@@ -0,0 +1,30 @@
+# معالجة تقرير الجودة
+
+**الفرع:** `feat/profile-driven-setup-templates`
+
+## النتيجة
+
+تمت معالجة جميع الأخطاء العشرة والتحذيرات الإحدى عشرة الواردة في المحتوى المرفق ضمن الملفات المشار إليها، مع تحسينين إضافيين متعلقين بإدارة دورة حياة مؤقت التحديث في شاشة الدفعات وقابلية عرض بيانات السمات غير الموثوقة.
+
+| الفئة | المعالجة المنفذة | النتيجة |
+|---|---|---|
+| أنواع TypeScript العامة | استبدال `any` بعقود لبيانات اللوحة، العقد التنظيمية، مراكز التكلفة، نقاط البيع، وسمات سياق التشغيل. | إزالة أخطاء `no-explicit-any` الواردة في التقرير. |
+| خطافات React | تصحيح تبعيات `useCallback` و`useMemo` التي تعتمد على الترجمة، وإزالة تعبيرات ذات أثر جانبي من تبديل العقد. | إزالة تحذيرات التبعيات والتعبيرات غير المستعملة في الملفات المستهدفة. |
+| حالات غير مستعملة | حذف حالات اختيار الدفعة ونوع تنفيذها التي لم تكن تؤثر في الواجهة، وحالة المستخدم غير المستعملة في لوحة المعلومات. | تقليل حالة الواجهة غير الضرورية وتحسين وضوح المسار. |
+| المعالجة الدفعيّة | نقل حجم الصفحة إلى ثابت، وإصلاح تنظيف مؤقت التحديث الدوري عند مغادرة الصفحة. | لا يبقى مؤقت تحديث حي بعد إلغاء تحميل المكوّن. |
+| استجابات API | إضافة محلل آمن لقوائم الاستجابات المتداخلة، وتحويل قيم السمات غير المعروفة إلى نص قبل عرضها. | تتعامل الواجهة مع استجابات `unknown` بدون فقد سلامة الأنواع. |
+| CI | تحديث `actions/checkout` و`actions/setup-node` في مسارات GitHub Actions إلى `v5`. | إزالة مراجع إصدارات الإجراءات التي تعمل بوقت تشغيل Node.js 20 الموقوف. |
+
+## التحقق المنفذ
+
+| الفحص | النتيجة |
+|---|---|
+| ESLint للملفات الثمانية الواردة في التقرير | ناجح، دون أخطاء أو تحذيرات. |
+| `npx tsc --noEmit` | ناجح. |
+| اختبارات الواجهة `npm test` | ناجحة: 22 ملف اختبار و122 اختبارًا. |
+| `git diff --check` | ناجح، دون مشكلات مسافات. |
+| فحص مراجع `checkout/setup-node` القديمة في `.github/workflows` | لا توجد مراجع إلى `v3` أو `v4`. |
+
+## ملاحظات
+
+يظل تشغيل Laravel وعمليات GitHub Actions نفسها من مسؤولية CI، إذ لا تتوفر بيئة PHP محليًا في جلسة المراجعة. التقرير السابق كان محددًا بهذه الملفات؛ لا تعني النتيجة أن كامل المستودع خالٍ من أي ملاحظة جودة أخرى خارج نطاقه. يجب أن يكون فتح طلب الدمج هو الخطوة التالية ليشغّل المسار الكامل على بيئة GitHub.
diff --git a/frontend/app/01-enterprise-core/automation/recurring/batch-processing/(pages)/page.tsx b/frontend/app/01-enterprise-core/automation/recurring/batch-processing/(pages)/page.tsx
index 59989fea..8ebe111a 100644
--- a/frontend/app/01-enterprise-core/automation/recurring/batch-processing/(pages)/page.tsx
+++ b/frontend/app/01-enterprise-core/automation/recurring/batch-processing/(pages)/page.tsx
@@ -10,6 +10,8 @@ import { getIcon } from "@/lib/icons";
 import { formatDate } from "@/lib/utils";
 import { useCallback, useEffect, useState } from "react";
 
+const ITEMS_PER_PAGE = 20;
+
 interface Batch {
   id: number;
   batch_name: string;
@@ -42,10 +44,8 @@ export default function BatchProcessingPage() {
   const [confirmDialog, setConfirmDialog] = useState(false);
   const [deleteBatchId, setDeleteBatchId] = useState<number | null>(null);
   const [executeBatchId, setExecuteBatchId] = useState<number | null>(null);
-  const [executeBatchType, setExecuteBatchType] = useState<string>("");
 
   // Selected batch for items view
-  const [selectedBatchId, setSelectedBatchId] = useState<number | null>(null);
   const [batchItems, setBatchItems] = useState<BatchItem[]>([]);
   const [isLoadingItems, setIsLoadingItems] = useState(false);
 
@@ -54,16 +54,14 @@ export default function BatchProcessingPage() {
   const [batchType, setBatchType] = useState("");
   const [batchDescription, setBatchDescription] = useState("");
 
-  const itemsPerPage = 20;
-
   const loadBatches = useCallback(async (page: number = 1) => {
     try {
       setIsLoading(true);
-      const response = await fetchAPI(`${API_ENDPOINTS.ENTERPRISE_CORE.BATCH}?page=${page}&limit=${itemsPerPage}`);
+      const response = await fetchAPI(`${API_ENDPOINTS.ENTERPRISE_CORE.BATCH}?page=${page}&limit=${ITEMS_PER_PAGE}`);
       if (response.success && response.data) {
         setBatches(response.data as Batch[]);
         const total = Number(response.total) || 0;
-        setTotalPages(Math.ceil(total / itemsPerPage));
+        setTotalPages(Math.ceil(total / ITEMS_PER_PAGE));
         setCurrentPage(page);
       } else {
         showToast(response.message || i18n.catalog["enterpriseCore.batchProcessing.failedLoadBatches"], "error");
@@ -73,25 +71,26 @@ export default function BatchProcessingPage() {
     } finally {
       setIsLoading(false);
     }
-  }, []);
+  }, [i18n.catalog]);
 
   useEffect(() => {
+    let refreshInterval: ReturnType<typeof setInterval> | null = null;
+
     const init = async () => {
       const authenticated = await checkAuth();
       if (!authenticated) return;
 
-      const storedUser = getStoredUser();
-      setUser(storedUser);
+      setUser(getStoredUser());
       await loadBatches();
-
-      // Auto-refresh every 30 seconds
-      const interval = setInterval(() => {
-        loadBatches(currentPage);
+      refreshInterval = setInterval(() => {
+        void loadBatches(currentPage);
       }, 30000);
+    };
 
-      return () => clearInterval(interval);
+    void init();
+    return () => {
+      if (refreshInterval) clearInterval(refreshInterval);
     };
-    init();
   }, [loadBatches, currentPage]);
 
   const getBatchTypeLabel = (type: string) => {
@@ -130,7 +129,6 @@ export default function BatchProcessingPage() {
 
   const closeItemsDialog = () => {
     setItemsDialog(false);
-    setSelectedBatchId(null);
     setBatchItems([]);
   };
 
@@ -173,7 +171,6 @@ export default function BatchProcessingPage() {
   };
 
   const viewBatchItems = async (batchId: number) => {
-    setSelectedBatchId(batchId);
     setIsLoadingItems(true);
     setItemsDialog(true);
 
@@ -194,9 +191,8 @@ export default function BatchProcessingPage() {
     }
   };
 
-  const confirmExecuteBatch = (batchId: number, batchType: string) => {
+  const confirmExecuteBatch = (batchId: number) => {
     setExecuteBatchId(batchId);
-    setExecuteBatchType(batchType);
     setConfirmDialog(true);
   };
 
@@ -331,7 +327,7 @@ export default function BatchProcessingPage() {
               <>
                 <button
                   className="icon-btn edit"
-                  onClick={() => confirmExecuteBatch(item.id, item.batch_type)}
+                  onClick={() => confirmExecuteBatch(item.id)}
                   title={i18n.catalog["common.general.execute"]}
                 >
                   {getIcon("check")}
diff --git a/frontend/app/01-enterprise-core/automation/recurring/recurring-transactions/(pages)/page.tsx b/frontend/app/01-enterprise-core/automation/recurring/recurring-transactions/(pages)/page.tsx
index 6757a3b1..1a569615 100644
--- a/frontend/app/01-enterprise-core/automation/recurring/recurring-transactions/(pages)/page.tsx
+++ b/frontend/app/01-enterprise-core/automation/recurring/recurring-transactions/(pages)/page.tsx
@@ -4,7 +4,7 @@ import { useI18n, catalogText } from "@/lib/i18n";
 import { MainLayout, PageSubHeader } from "@/components/layout";
 import { Button, Column, ConfirmDialog, Dialog, Table, showAlert, showToast } from "@/components/ui";
 import { fetchAPI } from "@/lib/api";
-import { User, checkAuth, getStoredUser } from "@/lib/auth";
+import { checkAuth } from "@/lib/auth";
 import { API_ENDPOINTS } from "@/lib/endpoints";
 import { getIcon } from "@/lib/icons";
 import { formatDate, parseNumber } from "@/lib/utils";
@@ -22,6 +22,8 @@ interface RecurringTemplateData {
     }>;
 }
 
+const ITEMS_PER_PAGE = 20;
+
 interface RecurringTemplate {
     id: number;
     name: string;
@@ -34,7 +36,6 @@ interface RecurringTemplate {
 
 export default function RecurringTransactionsPage() {
     const { t: i18n } = useI18n();
-    const [user, setUser] = useState<User | null>(null);
     const [templates, setTemplates] = useState<RecurringTemplate[]>([]);
     const [currentPage, setCurrentPage] = useState(1);
     const [totalPages, setTotalPages] = useState(1);
@@ -66,16 +67,14 @@ export default function RecurringTransactionsPage() {
     // Journal fields
     const [journalEntries, setJournalEntries] = useState("");
 
-    const itemsPerPage = 20;
-
     const loadTemplates = useCallback(async (page: number = 1) => {
         try {
             setIsLoading(true);
-            const response = await fetchAPI<RecurringTemplate[]>(`${API_ENDPOINTS.FINANCE.RECURRING.BASE}?page=${page}&limit=${itemsPerPage}`);
+            const response = await fetchAPI<RecurringTemplate[]>(`${API_ENDPOINTS.FINANCE.RECURRING.BASE}?page=${page}&limit=${ITEMS_PER_PAGE}`);
             if (response.success && response.data) {
                 setTemplates(response.data);
                 const total = Number(response.total) || 0;
-                setTotalPages(Math.ceil(total / itemsPerPage));
+                setTotalPages(Math.ceil(total / ITEMS_PER_PAGE));
                 setCurrentPage(page);
             } else {
                 showAlert("alert-container", response.message || i18n.catalog["enterpriseCore.recurringTransactions.failedLoadTemplates"], "error");
@@ -85,15 +84,13 @@ export default function RecurringTransactionsPage() {
         } finally {
             setIsLoading(false);
         }
-    }, []);
+    }, [i18n.catalog]);
 
     useEffect(() => {
         const init = async () => {
             const authenticated = await checkAuth();
             if (!authenticated) return;
 
-            const storedUser = getStoredUser();
-            setUser(storedUser);
             await loadTemplates();
         };
         init();
diff --git a/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/(pages)/page.tsx b/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/(pages)/page.tsx
index d09cf857..c69a7e16 100644
--- a/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/(pages)/page.tsx
+++ b/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/(pages)/page.tsx
@@ -39,10 +39,38 @@ const initialSetupForm: SetupForm = {
   pos_terminal_id: null,
 };
 
-function listFromResponse(response: any): any[] {
+type ListResponse = { data?: unknown } | null | undefined;
+
+type OrganizationNode = {
+  node_uuid: string;
+  node_type_id: string;
+  code: string;
+  status?: string;
+};
+
+type CostCenter = {
+  id: number;
+  code: string;
+  name: string;
+  name_en?: string;
+  is_active?: boolean;
+};
+
+type PosTerminal = {
+  id: number;
+  code: string;
+  name: string;
+  name_en?: string;
+  is_active?: boolean;
+};
+
+function listFromResponse<T>(response: ListResponse): T[] {
   const raw = response?.data;
-  if (Array.isArray(raw)) return raw;
-  if (Array.isArray(raw?.data)) return raw.data;
+  if (Array.isArray(raw)) return raw as T[];
+  if (raw && typeof raw === "object" && "data" in raw) {
+    const nested = (raw as { data?: unknown }).data;
+    if (Array.isArray(nested)) return nested as T[];
+  }
   return [];
 }
 
@@ -52,9 +80,9 @@ export default function OrganizationalStructurePage() {
   const [setupOpen, setSetupOpen] = useState(false);
   const [isSaving, setIsSaving] = useState(false);
   const [setupForm, setSetupForm] = useState<SetupForm>(initialSetupForm);
-  const [nodes, setNodes] = useState<any[]>([]);
-  const [costCenters, setCostCenters] = useState<any[]>([]);
-  const [posTerminals, setPosTerminals] = useState<any[]>([]);
+  const [nodes, setNodes] = useState<OrganizationNode[]>([]);
+  const [costCenters, setCostCenters] = useState<CostCenter[]>([]);
+  const [posTerminals, setPosTerminals] = useState<PosTerminal[]>([]);
   const { readiness, loadReadiness } = useOperatingContextStore();
   const readinessLabels: Record<string, string> = {
     warehouse: i18n.catalog["enterpriseCore.orgHierarchy.readinessWarehouse"],
@@ -85,9 +113,9 @@ export default function OrganizationalStructurePage() {
         fetchAPI(API_ENDPOINTS.FINANCE.COST_CENTERS.BASE),
         fetchAPI(API_ENDPOINTS.ENTERPRISE_CORE.OPERATING_CONTEXT.POS_TERMINALS),
       ]);
-      setNodes(listFromResponse(nodeResponse));
-      setCostCenters(listFromResponse(costResponse).filter((center) => center.is_active !== false));
-      setPosTerminals(listFromResponse(posResponse).filter((terminal) => terminal.is_active !== false));
+      setNodes(listFromResponse<OrganizationNode>(nodeResponse));
+      setCostCenters(listFromResponse<CostCenter>(costResponse).filter((center) => center.is_active !== false));
+      setPosTerminals(listFromResponse<PosTerminal>(posResponse).filter((terminal) => terminal.is_active !== false));
       await loadReadiness();
     };
     loadSetupData();
@@ -109,7 +137,7 @@ export default function OrganizationalStructurePage() {
         label: catalogText(i18n, "common.general.notAvailable.alternative10", { value0: center.code, value1: center.name }),
         subtitle: center.name_en || '',
       })),
-    [costCenters]
+    [costCenters, i18n]
   );
   const posTerminalOptions = useMemo<SelectOption[]>(
     () =>
@@ -118,7 +146,7 @@ export default function OrganizationalStructurePage() {
         label: catalogText(i18n, "common.general.notAvailable.alternative10", { value0: terminal.code, value1: terminal.name }),
         subtitle: terminal.name_en || '',
       })),
-    [posTerminals]
+    [posTerminals, i18n]
   );
 
   const updateSetupField = <K extends keyof SetupForm>(key: K, value: SetupForm[K]) => {
diff --git a/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/components/ChangeHistoryTab.tsx b/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/components/ChangeHistoryTab.tsx
index 848d9053..73776c46 100644
--- a/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/components/ChangeHistoryTab.tsx
+++ b/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/components/ChangeHistoryTab.tsx
@@ -72,7 +72,7 @@ export function ChangeHistoryTab() {
             setHistory((res.history as ChangeRecord[]) || []);
         } catch { showToast(i18n.catalog["enterpriseCore.changehistory.failedLoadChangeLog"], "error"); }
         finally { setIsLoading(false); }
-    }, [limit, filterEntity]);
+    }, [limit, filterEntity, i18n.catalog]);
 
     useEffect(() => { loadHistory(); }, [loadHistory]);
 
diff --git a/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/components/HierarchyTab.tsx b/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/components/HierarchyTab.tsx
index be483ab0..25266c02 100644
--- a/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/components/HierarchyTab.tsx
+++ b/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/components/HierarchyTab.tsx
@@ -58,7 +58,6 @@ export function getDomainColor(domain: string): string {
 export function HierarchyTab() {
     const { t: i18n } = useI18n();
     const [nodes, setNodes] = useState<StructureNode[]>([]);
-    const [links, setLinks] = useState<StructureLink[]>([]);
     const [metaTypes, setMetaTypes] = useState<MetaType[]>([]);
     const [expandedNodes, setExpandedNodes] = useState<Set<string>>(new Set());
     const [selectedNode, setSelectedNode] = useState<StructureNode | null>(null);
@@ -80,26 +79,12 @@ export function HierarchyTab() {
         } finally {
             setIsLoading(false);
         }
-    }, []);
+    }, [i18n.catalog]);
 
     useEffect(() => {
         loadData();
     }, [loadData]);
 
-    useEffect(() => {
-        if (!selectedNode) return;
-        const loadLinks = async () => {
-            try {
-                const res = await fetchAPI(API_ENDPOINTS.ENTERPRISE_CORE.ORG.NODE(selectedNode.node_uuid));
-                const n = res.node as StructureNode & {
-                    outgoing_links?: StructureLink[];
-                    incoming_links?: StructureLink[];
-                };
-                setLinks([...(n.outgoing_links || []), ...(n.incoming_links || [])]);
-            } catch { /* ignore */ }
-        };
-        loadLinks();
-    }, [selectedNode]);
 
     const buildTree = useCallback((): TreeNode[] => {
         if (!nodes.length) return [];
@@ -143,7 +128,11 @@ export function HierarchyTab() {
     const toggleExpand = (uuid: string) => {
         setExpandedNodes((prev) => {
             const next = new Set(prev);
-            next.has(uuid) ? next.delete(uuid) : next.add(uuid);
+            if (next.has(uuid)) {
+                next.delete(uuid);
+            } else {
+                next.add(uuid);
+            }
             return next;
         });
     };
diff --git a/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/components/NodesTab.tsx b/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/components/NodesTab.tsx
index 57a3c581..e46ab603 100644
--- a/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/components/NodesTab.tsx
+++ b/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/components/NodesTab.tsx
@@ -77,14 +77,14 @@ export function NodesTab() {
             setInitialDataLoaded(true);
         } catch { showToast(i18n.catalog["enterpriseCore.nodes.errorLoadingOrganizationalUnits"], "error"); }
         finally { setIsLoading(false); }
-    }, [searchTerm, filterType, filterStatus, filterDomain]);
+    }, [searchTerm, filterType, filterStatus, filterDomain, i18n.catalog]);
 
     const loadMetaTypes = useCallback(async () => {
         try {
             const response = await fetchAPI(API_ENDPOINTS.ENTERPRISE_CORE.ORG.META_TYPES);
             setMetaTypes((response.data as MetaType[]) || []);
         } catch { showToast(i18n.catalog["common.general.errorLoadingUnitTypes"], "error"); }
-    }, []);
+    }, [i18n.catalog]);
 
     const loadTopologyRules = useCallback(async () => {
         try {
@@ -177,7 +177,11 @@ export function NodesTab() {
     const toggleSelect = (uuid: string) => {
         setSelectedUuids(prev => {
             const next = new Set(prev);
-            next.has(uuid) ? next.delete(uuid) : next.add(uuid);
+            if (next.has(uuid)) {
+                next.delete(uuid);
+            } else {
+                next.add(uuid);
+            }
             return next;
         });
     };
@@ -317,7 +321,7 @@ export function NodesTab() {
                             value={null}
                             options={nodes.map(n => ({
                                 value: n.node_uuid,
-                                label: catalogText(i18n, "common.general.notAvailable", { value0: n.code, value1: (n.attributes_json as any)?.name || '' }),
+                                label: catalogText(i18n, "common.general.notAvailable", { value0: n.code, value1: String(n.attributes_json?.name ?? "") }),
                                 subtitle: getTypeLabel(n.node_type_id)
                             }))}
                             onChange={(val) => {
diff --git a/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/components/ScopeContextTab.tsx b/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/components/ScopeContextTab.tsx
index 618419ce..f39d3ddc 100644
--- a/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/components/ScopeContextTab.tsx
+++ b/frontend/app/01-enterprise-core/organization-governance/org-structure/org-hierarchy/components/ScopeContextTab.tsx
@@ -13,9 +13,16 @@ import { DOMAIN_COLORS } from "../(pages)/ui/index";
 interface MetaType { id: string; display_name: string; display_name_ar?: string; level_domain: string; }
 interface StructureNode { node_uuid: string; node_type_id: string; code: string; attributes_json?: Record<string, unknown>; }
 
+type ScopeAttributes = Record<string, unknown>;
+
 interface ScopeResult {
-    anchor: { node_uuid: string; node_type_id: string; code: string; attributes: Record<string, any> };
-    resolved: Record<string, { node_uuid: string; code: string; attributes: Record<string, any> }>;
+    anchor: { node_uuid: string; node_type_id: string; code: string; attributes: ScopeAttributes };
+    resolved: Record<string, { node_uuid: string; code: string; attributes: ScopeAttributes }>;
+}
+
+function displayAttributeValue(value: unknown): string {
+    if (value === null || value === undefined) return "";
+    return typeof value === "object" ? JSON.stringify(value) ?? "" : String(value);
 }
 
 export function ScopeContextTab() {
@@ -35,7 +42,7 @@ export function ScopeContextTab() {
             setNodes((nodesRes.data as StructureNode[]) || []);
             setMetaTypes((metaRes.data as MetaType[]) || []);
         } catch { showToast(i18n.catalog["common.general.errorLoadingData"], "error"); }
-    }, []);
+    }, [i18n.catalog]);
 
     useEffect(() => { loadNodes(); }, [loadNodes]);
 
@@ -131,9 +138,9 @@ export function ScopeContextTab() {
                                         </div>
                                         <div>
                                             <span style={{ fontWeight: 700, fontSize: "1rem" }}>{data.code}</span>
-                                            {data.attributes?.name && (
+                                            {displayAttributeValue(data.attributes?.name) && (
                                                 <span style={{ marginRight: "0.5rem", color: "var(--text-secondary)", fontSize: "0.85rem" }}>
-                                                    — {data.attributes.name}
+                                                    — {displayAttributeValue(data.attributes?.name)}
                                                 </span>
                                             )}
                                         </div>
@@ -141,7 +148,7 @@ export function ScopeContextTab() {
                                             <div style={{ marginRight: "auto", display: "flex", gap: "0.5rem", flexWrap: "wrap" }}>
                                                 {Object.entries(data.attributes).filter(([k]) => k !== "name").map(([k, v]) => (
                                                     <span key={k} style={{ fontSize: "0.7rem", padding: "1px 6px", borderRadius: "4px", background: "var(--bg-primary)", color: "var(--text-muted)" }}>
-                                                        {k}: {typeof v === "object" ? JSON.stringify(v) : String(v)}
+                                                        {k}: {displayAttributeValue(v)}
                                                     </span>
                                                 ))}
                                             </div>
diff --git a/frontend/app/01-enterprise-core/system-overview/dashboard/global-dashboard/(pages)/page.tsx b/frontend/app/01-enterprise-core/system-overview/dashboard/global-dashboard/(pages)/page.tsx
index 1bf5cc10..6c4b0e2a 100644
--- a/frontend/app/01-enterprise-core/system-overview/dashboard/global-dashboard/(pages)/page.tsx
+++ b/frontend/app/01-enterprise-core/system-overview/dashboard/global-dashboard/(pages)/page.tsx
@@ -4,7 +4,7 @@ import { catalogText, useI18n } from "@/lib/i18n";
 import { MainLayout } from "@/components/layout";
 import { Button, Column, Dialog, Table, showToast } from "@/components/ui";
 import { fetchAPI } from "@/lib/api";
-import { Permission, User, canAccess, getStoredPermissions, getStoredUser } from "@/lib/auth";
+import { Permission, canAccess, getStoredPermissions } from "@/lib/auth";
 import { API_ENDPOINTS } from "@/lib/endpoints";
 import { getIcon } from "@/lib/icons";
 import { publishProductNotification } from "@/stores/useNotificationStore";
@@ -51,7 +51,6 @@ interface ExpiringProduct {
 
 export default function DashboardPage() {
     const { t: i18n } = useI18n();
-    const [user, setUser] = useState<User | null>(null);
     const [permissions, setPermissions] = useState<Permission[]>([]);
     const [stats, setStats] = useState<DashboardStats | null>(null);
     const [recentSales, setRecentSales] = useState<RecentSale[]>([]);
@@ -77,15 +76,15 @@ export default function DashboardPage() {
                 const d = response.data as {
                     todays_sales?: number;
                     total_products?: number;
-                    low_stock_products?: any[];
-                    expiring_products?: any[];
+                    low_stock_products?: LowStockProduct[];
+                    expiring_products?: ExpiringProduct[];
                     total_sales?: number;
                     todays_expenses?: number;
                     total_expenses?: number;
                     todays_revenues?: number;
                     total_revenues?: number;
                     total_assets?: number;
-                    recent_sales?: any[];
+                    recent_sales?: RecentSale[];
                 };
                 setStats({
                     daily_sales: Number(d.todays_sales) || 0,
@@ -139,12 +138,10 @@ export default function DashboardPage() {
         } finally {
             setIsLoading(false);
         }
-    }, [i18n.catalog]);
+    }, [i18n]);
 
     useEffect(() => {
-        const storedUser = getStoredUser();
         const storedPermissions = getStoredPermissions();
-        setUser(storedUser);
         setPermissions(storedPermissions);
         loadDashboardData();
     }, [loadDashboardData]);