From 9f8f29d61478384d56ac530cc1ab6325a4157782 Mon Sep 17 00:00:00 2001
From: mihretue <mihretuendeshaw84@gmail.com>
Date: Mon, 24 Aug 2026 11:30:56 +0000
Subject: [PATCH 01/14] fix(exam): stop hiding non-CHOICE questions from
 OFFLINE assignment picker

eligibleQuestions filtered by q.form === exam.form, which matched the
backend's own restriction (assertUsable) only for ONLINE exams. Once
exam.form gained the "BOTH" value for OFFLINE mixed papers, no question
ever has form "BOTH", so the picker silently emptied out or, for a
plain CHOICE-form exam, looked CHOICE-only regardless of administration
method. Now mirrors the backend: CHOICE-only gate applies only when
administrationMethod is ONLINE.
---
 .../src/app/features/exam/pages/ExamDetailPage.tsx  | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/apps/backoffice/src/app/features/exam/pages/ExamDetailPage.tsx b/apps/backoffice/src/app/features/exam/pages/ExamDetailPage.tsx
index 8e9037840..5ce7a4ab5 100644
--- a/apps/backoffice/src/app/features/exam/pages/ExamDetailPage.tsx
+++ b/apps/backoffice/src/app/features/exam/pages/ExamDetailPage.tsx
@@ -121,18 +121,25 @@ export function ExamDetailPage() {
 
   // Only approved bank items may go on a paper (US-EXAM-003), so the picker
   // must not offer drafts or retired questions either.
+  //
+  // Form restriction mirrors the backend's assertUsable: ONLINE exams are
+  // CHOICE-only (auto-grading needs it), OFFLINE exams have no form
+  // restriction at all — mixing ESSAY and CHOICE by hand (exam.form
+  // "BOTH") is the sanctioned, only way to build a mixed paper. Matching
+  // `q.form === exam.form` here used to hide every question once "BOTH"
+  // became a real exam.form value, since no question itself is "BOTH".
   const eligibleQuestions = useMemo(() => {
     if (!exam) return [];
     return allQuestions
       .filter(
         (q) =>
           q.certificationId === exam.certificationId &&
-          q.form === exam.form &&
-          q.status === 'APPROVED',
+          q.status === 'APPROVED' &&
+          (exam.administrationMethod !== 'ONLINE' || q.form === 'CHOICE'),
       )
       .map((q) => ({ id: q.id, title: q.title, form: q.form, points: q.points }));
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [allQuestions, exam?.certificationId, exam?.form]);
+  }, [allQuestions, exam?.certificationId, exam?.administrationMethod]);
 
   if (isLoading)
     return <PageLoader label="Loading Exam Details…" height={400} />;

From 35961ec8099a9712254545a2cbbc56ea92581023 Mon Sep 17 00:00:00 2001
From: mihretue <mihretuendeshaw84@gmail.com>
Date: Mon, 24 Aug 2026 12:57:37 +0000
Subject: [PATCH 02/14] feat(exam): let ONLINE exams take ESSAY/BOTH form, add
 grading-sheet API
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Frontend half of the backend change: ExamPage no longer disables the
form Select or force-resets it to CHOICE when administrationMethod is
ONLINE (backend's assertOnlineIsChoiceOnly is gone, matching gate
removed here). Also wires up GET .../grading-sheet as
useGetGradingSheetQuery — RecordResultModal wiring (show candidate
answers, prefill auto-computed CHOICE scores) is next.
---
 .../src/app/features/exam/api/exam-api.ts      | 11 +++++++++++
 .../app/features/exam/pages/ExamPage/index.tsx | 15 +--------------
 .../src/app/features/exam/types/exam.ts        | 18 ++++++++++++++++++
 apps/backoffice/src/app/i18n/locales/am.ts     |  1 -
 apps/backoffice/src/app/i18n/locales/en.ts     |  1 -
 5 files changed, 30 insertions(+), 16 deletions(-)

diff --git a/apps/backoffice/src/app/features/exam/api/exam-api.ts b/apps/backoffice/src/app/features/exam/api/exam-api.ts
index d313a38ac..4dbe8f713 100644
--- a/apps/backoffice/src/app/features/exam/api/exam-api.ts
+++ b/apps/backoffice/src/app/features/exam/api/exam-api.ts
@@ -12,6 +12,7 @@ import type {
   CreateIncidentPayload,
   ResolveIncidentPayload,
   RegradeOutcome,
+  GradingSheet,
 } from '../types/exam';
 
 const examApi = baseApi.injectEndpoints({
@@ -101,6 +102,15 @@ const examApi = baseApi.injectEndpoints({
       }),
       invalidatesTags: ['Api'],
     }),
+    /** The candidate's answers plus auto-computable CHOICE scores, for RecordResultModal. */
+    getGradingSheet: builder.query<
+      GradingSheet,
+      { examId: string; profileId: string }
+    >({
+      query: ({ examId, profileId }) =>
+        `/exam-attempts/exam/${examId}/candidate/${profileId}/grading-sheet`,
+      providesTags: ['Api'],
+    }),
   }),
   overrideExisting: false,
 });
@@ -119,4 +129,5 @@ export const {
   useRecordIncidentMutation,
   useResolveIncidentMutation,
   useRegradeAttemptMutation,
+  useGetGradingSheetQuery,
 } = examApi;
diff --git a/apps/backoffice/src/app/features/exam/pages/ExamPage/index.tsx b/apps/backoffice/src/app/features/exam/pages/ExamPage/index.tsx
index 034d203ae..34039328c 100644
--- a/apps/backoffice/src/app/features/exam/pages/ExamPage/index.tsx
+++ b/apps/backoffice/src/app/features/exam/pages/ExamPage/index.tsx
@@ -255,12 +255,6 @@ function ExamForm({
                   onChange={setForm}
                   size="sm"
                   required
-                  disabled={adminMethod === "ONLINE"}
-                  description={
-                    adminMethod === "ONLINE"
-                      ? t("exam.form.onlineChoiceOnlyHint")
-                      : undefined
-                  }
                 />
                 <Select
                   label={t("exam.detail.administration")}
@@ -270,14 +264,7 @@ function ExamForm({
                     { value: "ONLINE", label: t("exam.form.online") },
                   ]}
                   value={adminMethod}
-                  onChange={(value) => {
-                    setAdminMethod(value);
-                    // Online exams are graded automatically, and that only
-                    // has an answer model for CHOICE — matches the backend
-                    // rule (online_exam_requires_choice_form), not just a
-                    // UI nicety.
-                    if (value === "ONLINE") setForm("CHOICE");
-                  }}
+                  onChange={setAdminMethod}
                   size="sm"
                   required
                 />
diff --git a/apps/backoffice/src/app/features/exam/types/exam.ts b/apps/backoffice/src/app/features/exam/types/exam.ts
index 28752ae64..9ca4676d4 100644
--- a/apps/backoffice/src/app/features/exam/types/exam.ts
+++ b/apps/backoffice/src/app/features/exam/types/exam.ts
@@ -136,6 +136,24 @@ export type RegradeOutcome =
   | { graded: true; resultId: string }
   | { graded: false; reason: string };
 
+/** One question's row on the staff grading sheet — the candidate's own
+ * answer plus the auto-computable score, where one exists. */
+export interface GradingSheetQuestion {
+  questionId: string;
+  form: QuestionForm;
+  points: number;
+  answerText: string | null;
+  selectedOptionId: string | null;
+  selectedOptionText: { en?: string; am?: string } | null;
+  /** null means "no auto-score" — examiner enters one by hand. */
+  autoScore: number | null;
+}
+
+export interface GradingSheet {
+  attemptStatus: 'IN_PROGRESS' | 'SUBMITTED' | 'EXPIRED';
+  questions: GradingSheetQuestion[];
+}
+
 export interface RecordAttendancePayload {
   registrationId: string;
   status: AttendanceStatus;
diff --git a/apps/backoffice/src/app/i18n/locales/am.ts b/apps/backoffice/src/app/i18n/locales/am.ts
index 458b638e6..1e75f20eb 100644
--- a/apps/backoffice/src/app/i18n/locales/am.ts
+++ b/apps/backoffice/src/app/i18n/locales/am.ts
@@ -260,7 +260,6 @@ export const am: Translations = {
       both: "ሁለቱም",
       offline: "ከመስመር ውጪ",
       online: "በመስመር",
-      onlineChoiceOnlyHint: "የመስመር ላይ ፈተናዎች በራስ-ሰር ይመዘገባሉ፣ ይህም ለምርጫ ጥያቄዎች ብቻ ይሰራል።",
       sum: "ድምር",
       average: "አማካይ",
       percentage: "መቶኛ",
diff --git a/apps/backoffice/src/app/i18n/locales/en.ts b/apps/backoffice/src/app/i18n/locales/en.ts
index 73a9d96d7..3af7597f0 100644
--- a/apps/backoffice/src/app/i18n/locales/en.ts
+++ b/apps/backoffice/src/app/i18n/locales/en.ts
@@ -259,7 +259,6 @@ export const en = {
       both: 'Both',
       offline: 'Offline',
       online: 'Online',
-      onlineChoiceOnlyHint: 'Online exams are graded automatically, which only works for multiple choice.',
       sum: 'Sum',
       average: 'Average',
       percentage: 'Percentage',

From 34208ed0d663bc3be6895ef4f61184ed591f660e Mon Sep 17 00:00:00 2001
From: mihretue <mihretuendeshaw84@gmail.com>
Date: Mon, 24 Aug 2026 13:02:08 +0000
Subject: [PATCH 03/14] feat(exam): show candidate answers + prefill
 auto-scores in RecordResultModal
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Wires useGetGradingSheetQuery into the grading modal: a new 'Candidate's
Answer' column shows the selected option or essay text per question, and
whichever CHOICE scores auto-grading could already compute get prefilled
into the score inputs (tagged 'Auto-graded', still editable — the examiner
can override). Grading a mixed or ESSAY paper no longer means guessing at
what was answered or re-deriving the CHOICE portion by eye.

Degrades to blank inputs exactly as before for an OFFLINE candidate or one
who hasn't sat an online attempt (gradingSheet returns empty answers for
those, not an error).
---
 .../components/RecordResultModal/columns.tsx  | 51 ++++++++++++++-----
 .../components/RecordResultModal/index.tsx    | 32 +++++++++++-
 apps/backoffice/src/app/i18n/locales/am.ts    |  3 ++
 apps/backoffice/src/app/i18n/locales/en.ts    |  3 ++
 4 files changed, 75 insertions(+), 14 deletions(-)

diff --git a/apps/backoffice/src/app/features/result/components/RecordResultModal/columns.tsx b/apps/backoffice/src/app/features/result/components/RecordResultModal/columns.tsx
index f224aa828..9503b1120 100644
--- a/apps/backoffice/src/app/features/result/components/RecordResultModal/columns.tsx
+++ b/apps/backoffice/src/app/features/result/components/RecordResultModal/columns.tsx
@@ -1,7 +1,7 @@
-import { NumberInput, Text, TextInput } from '@mantine/core';
+import { Badge, Group, NumberInput, Text, TextInput } from '@mantine/core';
 import type { TFunction } from 'i18next';
 import type { AdvancedColumn } from '@ema-platform/ui';
-import type { QuestionBrief } from '../../../exam/types/exam';
+import type { GradingSheetQuestion, QuestionBrief } from '../../../exam/types/exam';
 
 export function recordResultColumns(
   t: TFunction,
@@ -11,6 +11,9 @@ export function recordResultColumns(
     questionRemarks: Record<string, string>;
     onScoreChange: (questionId: string, value: number) => void;
     onRemarkChange: (questionId: string, value: string) => void;
+    /** The candidate's own answer + auto-score, when available (empty for
+     *  an OFFLINE candidate or one who hasn't sat an online attempt). */
+    answersByQuestion: Map<string, GradingSheetQuestion>;
   },
 ): AdvancedColumn<QuestionBrief>[] {
   return [
@@ -22,6 +25,20 @@ export function recordResultColumns(
         </Text>
       ),
     },
+    {
+      header: t('result.recordModal.candidateAnswer'),
+      cell: ({ row }) => {
+        const answer = handlers.answersByQuestion.get(row.original.id);
+        if (!answer || (!answer.answerText && !answer.selectedOptionText)) {
+          return <Text fz="xs" c="dimmed">{t('result.recordModal.noAnswer')}</Text>;
+        }
+        return (
+          <Text fz="sm" maw={220} lineClamp={3}>
+            {answer.selectedOptionText?.[locale] ?? answer.answerText}
+          </Text>
+        );
+      },
+    },
     {
       header: t('result.recordModal.maxPoints'),
       cell: ({ row }) => (
@@ -32,16 +49,26 @@ export function recordResultColumns(
     },
     {
       header: t('result.recordModal.score'),
-      cell: ({ row }) => (
-        <NumberInput
-          value={handlers.scores[row.original.id] ?? 0}
-          onChange={(v) => handlers.onScoreChange(row.original.id, Number(v))}
-          min={0}
-          max={row.original.points}
-          size="xs"
-          style={{ width: 80 }}
-        />
-      ),
+      cell: ({ row }) => {
+        const autoGraded = handlers.answersByQuestion.get(row.original.id)?.autoScore != null;
+        return (
+          <Group gap={4} wrap="nowrap">
+            <NumberInput
+              value={handlers.scores[row.original.id] ?? 0}
+              onChange={(v) => handlers.onScoreChange(row.original.id, Number(v))}
+              min={0}
+              max={row.original.points}
+              size="xs"
+              style={{ width: 80 }}
+            />
+            {autoGraded && (
+              <Badge size="xs" variant="light" color="teal">
+                {t('result.recordModal.autoGraded')}
+              </Badge>
+            )}
+          </Group>
+        );
+      },
     },
     {
       header: t('result.recordModal.remark'),
diff --git a/apps/backoffice/src/app/features/result/components/RecordResultModal/index.tsx b/apps/backoffice/src/app/features/result/components/RecordResultModal/index.tsx
index 15ed50335..b073b1ca1 100644
--- a/apps/backoffice/src/app/features/result/components/RecordResultModal/index.tsx
+++ b/apps/backoffice/src/app/features/result/components/RecordResultModal/index.tsx
@@ -1,4 +1,4 @@
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import {
   Modal,
@@ -20,7 +20,7 @@ import { extractErrorMessage } from '@ema-platform/api';
 import { LICENSE_PERMISSIONS, RequirePermission } from '@ema-platform/auth';
 import { recordResultColumns } from './columns';
 import { useCreateResultMutation } from '../../api/result-api';
-import { useGetExamRegistrationsQuery } from '../../../exam/api/exam-api';
+import { useGetExamRegistrationsQuery, useGetGradingSheetQuery } from '../../../exam/api/exam-api';
 import type { Exam } from '../../../exam/types/exam';
 
 function InfoRow({ label, value }: { label: string; value: string }) {
@@ -55,12 +55,39 @@ export function RecordResultModal({
   const { data: registrations } = useGetExamRegistrationsQuery(exam.id, {
     skip: !opened,
   });
+  // The candidate's own answers plus whatever score auto-grading could
+  // already compute for the CHOICE portion — degrades to "no data" for an
+  // OFFLINE candidate or one who never sat an online attempt, same as
+  // before this existed.
+  const { data: gradingSheet } = useGetGradingSheetQuery(
+    { examId: exam.id, profileId: selectedSeafarerId ?? '' },
+    { skip: !opened || !selectedSeafarerId },
+  );
+  const answersByQuestion = new Map(
+    (gradingSheet?.questions ?? []).map((q) => [q.questionId, q]),
+  );
   const [createResult, { isLoading: isSaving }] = useCreateResultMutation();
   const table = useServerTable();
 
   const questions = exam.questions ?? [];
   const pagedQuestions = table.paginate(questions);
 
+  // Prefill (never override) the CHOICE questions auto-grading already
+  // scored — the examiner only has to key in the ESSAY marks. A fresh
+  // seafarer selection always starts from an empty scores map, so this
+  // only ever fills in blanks, never stomps a manual edit already made.
+  useEffect(() => {
+    if (!gradingSheet) return;
+    const autoScores: Record<string, number> = {};
+    for (const q of gradingSheet.questions) {
+      if (q.autoScore !== null) autoScores[q.questionId] = q.autoScore;
+    }
+    if (Object.keys(autoScores).length) {
+      setScores((prev) => ({ ...autoScores, ...prev }));
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [gradingSheet]);
+
   const seafarerOptions = (registrations ?? [])
     .filter((registration) =>
       ['PRESENT', 'LATE'].includes(registration.attendanceStatus),
@@ -175,6 +202,7 @@ export function RecordResultModal({
                 questionRemarks,
                 onScoreChange: handleScoreChange,
                 onRemarkChange: handleQuestionRemarkChange,
+                answersByQuestion,
               })}
               data={pagedQuestions.rows}
               itemCount={pagedQuestions.itemCount}
diff --git a/apps/backoffice/src/app/i18n/locales/am.ts b/apps/backoffice/src/app/i18n/locales/am.ts
index 1e75f20eb..292a374ae 100644
--- a/apps/backoffice/src/app/i18n/locales/am.ts
+++ b/apps/backoffice/src/app/i18n/locales/am.ts
@@ -657,6 +657,9 @@ export const am: Translations = {
       seafarerPlaceholder: "መርከበኛ ይፈልጉ እና ይምረጡ",
       scorePerQuestion: "በጥያቄ ውጤት",
       question: "ጥያቄ",
+      candidateAnswer: "የተፈታኙ መልስ",
+      noAnswer: "የተመዘገበ መልስ የለም",
+      autoGraded: "በራስ-ሰር የተመዘነ",
       maxPoints: "ከፍተኛ ውጤት",
       score: "ውጤት",
       remark: "ማስታወሻ",
diff --git a/apps/backoffice/src/app/i18n/locales/en.ts b/apps/backoffice/src/app/i18n/locales/en.ts
index 3af7597f0..8c0ff66ff 100644
--- a/apps/backoffice/src/app/i18n/locales/en.ts
+++ b/apps/backoffice/src/app/i18n/locales/en.ts
@@ -657,6 +657,9 @@ export const en = {
       seafarerPlaceholder: 'Search and select a seafarer',
       scorePerQuestion: 'Score per Question',
       question: 'Question',
+      candidateAnswer: "Candidate's Answer",
+      noAnswer: 'No answer on file',
+      autoGraded: 'Auto-graded',
       maxPoints: 'Max Points',
       score: 'Score',
       remark: 'Remark',

From b49de1c1a8580e7a9b89b56355ec375689576bad Mon Sep 17 00:00:00 2001
From: mihretue <mihretuendeshaw84@gmail.com>
Date: Mon, 24 Aug 2026 14:04:24 +0000
Subject: [PATCH 04/14] fix(exam): guard question assignment once the paper is
 locked
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The detail page fired assign/draw requests blind and surfaced the raw
backend key to the user — a locked paper showed up as the literal string
"paper_locked_after_registration" in a toast.

Manage Questions is now disabled once any candidate has registered, with a
tooltip and badge explaining why; both the manual assign and the random draw
live behind that modal, so one guard covers the same ground the backend's
assertPaperEditable does. The empty-paper alert now explains the deadlock
instead of telling the user to click a button that will fail, and both
error handlers translate paper_locked_after_registration in case someone
registers while the modal is open.

Registrations come from the query ExamCandidatesPanel already runs on this
page, so RTK Query serves it from cache rather than issuing a second request.
---
 .../features/exam/pages/ExamDetailPage.tsx    | 62 +++++++++++++++----
 apps/backoffice/src/app/i18n/locales/am.ts    |  3 +
 apps/backoffice/src/app/i18n/locales/en.ts    |  3 +
 3 files changed, 56 insertions(+), 12 deletions(-)

diff --git a/apps/backoffice/src/app/features/exam/pages/ExamDetailPage.tsx b/apps/backoffice/src/app/features/exam/pages/ExamDetailPage.tsx
index 4abe06117..ff8759458 100644
--- a/apps/backoffice/src/app/features/exam/pages/ExamDetailPage.tsx
+++ b/apps/backoffice/src/app/features/exam/pages/ExamDetailPage.tsx
@@ -22,6 +22,7 @@ import {
   TextInput,
   ThemeIcon,
   Box,
+  Tooltip,
   rem,
 } from "@mantine/core";
 import { useDisclosure } from "@mantine/hooks";
@@ -48,6 +49,7 @@ import {
   useUpdateExamMutation,
   useAssignQuestionsMutation,
   useSelectRandomQuestionsMutation,
+  useGetExamRegistrationsQuery,
 } from '../api/exam-api';
 import { useGetQuestionsQuery } from '../../question/api/question-api';
 import { useGetCertificationsQuery } from '../../certification/api/certification-api';
@@ -114,6 +116,12 @@ export function ExamDetailPage() {
   const [selectRandom, { isLoading: isDrawing }] = useSelectRandomQuestionsMutation();
 
   const { data: exam, isLoading, isError } = useGetExamQuery(id ?? '', { skip: !id });
+  // The backend locks the paper the moment the first candidate registers
+  // (ExamService.assertPaperEditable) — every candidate must sit the same
+  // paper. Same query ExamCandidatesPanel already runs, so RTK Query serves
+  // it from cache rather than issuing a second request.
+  const { data: registrations } = useGetExamRegistrationsQuery(id ?? '', { skip: !id });
+  const paperLocked = (registrations?.length ?? 0) > 0;
   const { data: qRes } = useGetQuestionsQuery();
   const { data: certRes } = useGetCertificationsQuery();
   const allQuestions = qRes?.items ?? [];
@@ -183,7 +191,9 @@ export function ExamDetailPage() {
     } catch (error) {
       const key = extractErrorMessage(error, t('exam.randomError'));
       notify.error(
-        key.startsWith('insufficient_approved_questions')
+        key === 'paper_locked_after_registration'
+          ? t('exam.paperLockedHint', { count: registrations?.length ?? 0 })
+          : key.startsWith('insufficient_approved_questions')
           ? `${t('exam.notEnoughApproved')} (${key.split(':')[1] ?? ''})`
           : key.startsWith('paper_cannot_reach_cutting_point')
             ? t('exam.cannotReachCuttingPoint', {
@@ -204,7 +214,9 @@ export function ExamDetailPage() {
     } catch (error) {
       const key = extractErrorMessage(error, 'Failed to assign questions');
       notify.error(
-        key.startsWith('question_not_approved')
+        key === 'paper_locked_after_registration'
+          ? t('exam.paperLockedHint', { count: registrations?.length ?? 0 })
+          : key.startsWith('question_not_approved')
           ? t('question.qc.onlyApprovedUsable')
           : key.startsWith('paper_cannot_reach_cutting_point')
             ? t('exam.cannotReachCuttingPoint', {
@@ -456,19 +468,45 @@ export function ExamDetailPage() {
             {t("exam.detail.questionsSection", { pts: totalPoints })}
           </Title>
           <RequirePermission anyOf={[LICENSE_PERMISSIONS.MANAGE_EXAMS]} hideOnly>
-            <Button
-              variant="light"
-              size="xs"
-              leftSection={<IconPlus size={14} />}
-              onClick={openAssignModal}
-            >
-              {t("exam.manageQuestions")}
-            </Button>
+            <Group gap="xs">
+              {paperLocked && (
+                <Badge size="sm" variant="light" color="gray">
+                  {t("exam.paperLocked")}
+                </Badge>
+              )}
+              <Tooltip
+                label={t("exam.paperLockedHint", {
+                  count: registrations?.length ?? 0,
+                })}
+                disabled={!paperLocked}
+                multiline
+                w={280}
+              >
+                {/* Wrapped: a disabled Mantine Button fires no pointer events,
+                    so the tooltip needs an enabled element to hang off. */}
+                <Box>
+                  <Button
+                    variant="light"
+                    size="xs"
+                    leftSection={<IconPlus size={14} />}
+                    onClick={openAssignModal}
+                    disabled={paperLocked}
+                  >
+                    {t("exam.manageQuestions")}
+                  </Button>
+                </Box>
+              </Tooltip>
+            </Group>
           </RequirePermission>
         </Group>
         {(exam.questions ?? []).length === 0 ? (
-          <Alert color="gray" icon={<IconInfoCircle size={16} />}>
-            {t("exam.noQuestionsAssigned")}
+          <Alert
+            color={paperLocked ? "red" : "gray"}
+            icon={<IconInfoCircle size={16} />}
+          >
+            {paperLocked
+              ? t("exam.paperLockedHint", { count: registrations?.length ?? 0 })
+              : t("exam.noQuestionsAssigned")}
           </Alert>
         ) : (
           <Stack gap="md">
diff --git a/apps/backoffice/src/app/i18n/locales/am.ts b/apps/backoffice/src/app/i18n/locales/am.ts
index 292a374ae..c8e51193d 100644
--- a/apps/backoffice/src/app/i18n/locales/am.ts
+++ b/apps/backoffice/src/app/i18n/locales/am.ts
@@ -387,6 +387,9 @@ export const am: Translations = {
     notEnoughApproved: "ለዚህ ትምህርት በቂ የጸደቁ ጥያቄዎች የሉም።",
     cannotReachCuttingPoint:
       "ይህ ወረቀት የማለፊያ ነጥቡን ሊደርስ አይችልም (ከፍተኛ {{max}}፣ የማለፊያ ነጥብ {{cuttingPoint}})። ተጨማሪ ወይም ከፍ ያለ ነጥብ ያላቸው ጥያቄዎችን ጨምር፣ ወይም የማለፊያ ነጥቡን ቀንስ።",
+    paperLocked: "ወረቀቱ ተቆልፏል",
+    paperLockedHint:
+      "ለዚህ ፈተና {{count}} ተፈታኝ(ዎች) ተመዝግበዋል። ሁሉም ተፈታኞች አንድ ዓይነት ወረቀት መፈተን ስላለባቸው ጥያቄዎቹ ከዚህ በኋላ አይቀየሩም።",
   },
 
   country: {
diff --git a/apps/backoffice/src/app/i18n/locales/en.ts b/apps/backoffice/src/app/i18n/locales/en.ts
index 8c0ff66ff..7152067ce 100644
--- a/apps/backoffice/src/app/i18n/locales/en.ts
+++ b/apps/backoffice/src/app/i18n/locales/en.ts
@@ -386,6 +386,9 @@ export const en = {
       'Not enough approved questions in the bank for this subject.',
     cannotReachCuttingPoint:
       'This paper cannot reach the passing mark (max {{max}}, pass mark {{cuttingPoint}}). Add more/higher-point questions, or lower the cutting point.',
+    paperLocked: 'Paper locked',
+    paperLockedHint:
+      '{{count}} candidate(s) have registered for this session. Every candidate must sit the same paper, so questions can no longer be changed.',
   },
 
   country: {

From 933ba41476635ee8e8adb04ae5722dde97cd9a08 Mon Sep 17 00:00:00 2001
From: mihretue <muluhome@gmail.com>
Date: Tue, 25 Aug 2026 12:30:57 +0000
Subject: [PATCH 05/14] feat(signup): verify identity with Fayda and prefill
 the form
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds "Continue with Fayda" to the existing signup page. It is an alternative
way to fill the form, not a second signup: the applicant still submits to
/auth/signup-with-pwd through the same schema, the same validation and the same
redirect to OTP verification, and signing up without Fayda is unchanged.

The page asks the API for an authorization URL, keeps the returned handle and
state in sessionStorage for the round trip, and FaydaCallbackPage hands the
code back to /auth/fayda/callback. No Fayda protocol logic lives here — the
PKCE verifier, the client key and the token exchange stay on the server. Once
the account exists the page posts the verification token to /auth/fayda/link so
the identity is recorded against it; that call is best-effort, since the
account is already usable without it.

Prefilled fields carry a "From Fayda" badge and stay editable, and a value
that already belongs to another account is badged as such so the applicant can
see which one to change rather than reading a single opaque signup error.
Cancellation, an expired session, a mismatched state and an incomplete callback
each get their own message.

Amharic strings are a first pass and want a native speaker's review.
---
 apps/portal/src/app/i18n/locales/am.ts        |  22 +++
 apps/portal/src/app/i18n/locales/en.ts        |  22 +++
 apps/portal/src/app/router.tsx                |   6 +
 libs/auth/src/index.ts                        |   1 +
 libs/auth/src/lib/pages/FaydaCallbackPage.tsx | 119 +++++++++++++
 libs/auth/src/lib/pages/SignupPage.tsx        | 159 +++++++++++++++++-
 libs/auth/src/lib/utils/fayda-session.ts      |  81 +++++++++
 7 files changed, 407 insertions(+), 3 deletions(-)
 create mode 100644 libs/auth/src/lib/pages/FaydaCallbackPage.tsx
 create mode 100644 libs/auth/src/lib/utils/fayda-session.ts

diff --git a/apps/portal/src/app/i18n/locales/am.ts b/apps/portal/src/app/i18n/locales/am.ts
index 0ecee5cda..98673b6b7 100644
--- a/apps/portal/src/app/i18n/locales/am.ts
+++ b/apps/portal/src/app/i18n/locales/am.ts
@@ -602,6 +602,28 @@ export const am: Translations = {
     createOne: "አንድ ይፍጠሩ",
   },
 
+  fayda: {
+    continueWith: "በፋይዳ ይቀጥሉ",
+    orFillManually: "ወይም መረጃዎን ራስዎ ይሙሉ",
+    verifiedTitle: "በፋይዳ ተረጋግጧል",
+    verifiedBody: "ፋይዳ ያረጋገጣቸውን መረጃዎች ሞልተናል። እባክዎ የቀሩትን መስኮች ያሟሉ።",
+    discard: "እነዚህን መረጃዎች አጥፍቼ ቅጹን ራሴ እሞላለሁ",
+    fieldVerified: "ከፋይዳ",
+    fieldConflict: "በሌላ መለያ ተይዟል",
+    conflictBody:
+      "አንዳንድ የተረጋገጡ መረጃዎች አስቀድሞ የሌላ መለያ ናቸው። የተመለከቱትን መስኮች ይቀይሩ ወይም ይግቡ።",
+    brandTitle: "በፋይዳ በማረጋገጥ ላይ",
+    brandSubtitle: "ማንነትዎን እስክናረጋግጥ ድረስ አንድ አፍታ።",
+    verifying: "የፋይዳ ማንነትዎን በማረጋገጥ ላይ…",
+    failedTitle: "ማረጋገጡ አልተጠናቀቀም",
+    backToSignup: "ወደ ምዝገባ ተመለስ",
+    cancelled: "የፋይዳ ማረጋገጫው ተሰርዟል። አሁንም በእጅ መመዝገብ ይችላሉ።",
+    rejected: "ፋይዳ ማንነትዎን ማረጋገጥ አልቻለም። እባክዎ እንደገና ይሞክሩ።",
+    invalidCallback: "ይህ የማረጋገጫ ሊንክ አልተሟላም። እባክዎ እንደገና ይጀምሩ።",
+    sessionLost: "የማረጋገጫ ክፍለ ጊዜዎ አልፏል። እባክዎ እንደገና ይጀምሩ።",
+    stateMismatch: "ይህ ማረጋገጫ ሊታመን አልቻለም። እባክዎ እንደገና ይጀምሩ።",
+  },
+
   signup: {
     usernameMinLength: "የተጠቃሚ ስም ቢያንስ 3 ቁምፊዎች ሊኖረው ይገባል",
     nameEnRequired: "ስም (እንግሊዝኛ) ያስፈልጋል",
diff --git a/apps/portal/src/app/i18n/locales/en.ts b/apps/portal/src/app/i18n/locales/en.ts
index 57fe394f3..d6d578b06 100644
--- a/apps/portal/src/app/i18n/locales/en.ts
+++ b/apps/portal/src/app/i18n/locales/en.ts
@@ -602,6 +602,28 @@ export const en = {
     createOne: 'Create one',
   },
 
+  fayda: {
+    continueWith: 'Continue with Fayda',
+    orFillManually: 'or fill in your details',
+    verifiedTitle: 'Verified with Fayda',
+    verifiedBody: 'We filled in the details Fayda confirmed. Please complete the remaining fields.',
+    discard: 'Clear these details and fill the form myself',
+    fieldVerified: 'From Fayda',
+    fieldConflict: 'Already used by another account',
+    conflictBody:
+      'Some verified details already belong to another account. Change the highlighted fields, or sign in instead.',
+    brandTitle: 'Verifying with Fayda',
+    brandSubtitle: 'One moment while we confirm your identity.',
+    verifying: 'Verifying your Fayda identity\u2026',
+    failedTitle: 'Verification incomplete',
+    backToSignup: 'Back to sign up',
+    cancelled: 'Fayda verification was cancelled. You can still sign up manually.',
+    rejected: 'Fayda could not verify your identity. Please try again.',
+    invalidCallback: 'This verification link is incomplete. Please start again.',
+    sessionLost: 'Your verification session has expired. Please start again.',
+    stateMismatch: 'This verification could not be trusted. Please start again.',
+  },
+
   signup: {
     usernameMinLength: 'Username must be at least 3 characters',
     nameEnRequired: 'Name (English) is required',
diff --git a/apps/portal/src/app/router.tsx b/apps/portal/src/app/router.tsx
index a8c20ea4f..348b98685 100644
--- a/apps/portal/src/app/router.tsx
+++ b/apps/portal/src/app/router.tsx
@@ -8,6 +8,7 @@ import { LandingRoute } from "./components/LandingRoute";
 import {
   LoginPage,
   SignupPage,
+  FaydaCallbackPage,
   OTPVerificationPage,
   ForgotPasswordPage,
   SetPasswordPage,
@@ -67,6 +68,11 @@ export const router = createBrowserRouter([
   { path: "/login", element: <LoginPage /> },
   { path: "/signup", element: <SignupPage /> },
 
+  // Where Fayda returns the applicant. Public by necessity — they have no
+  // account yet. It redeems the code and hands control back to /signup; the
+  // path must match the API's REDIRECT_URI, which is registered with Fayda.
+  { path: "/signup/fayda/callback", element: <FaydaCallbackPage /> },
+
   // Completes the forgot-password flow; the reset message links here. The
   // IAM package generates `/reset-password` links, `/set-password` is the
   // first-time-credential variant — one page serves both.
diff --git a/libs/auth/src/index.ts b/libs/auth/src/index.ts
index 7d8be994b..16ad04c39 100644
--- a/libs/auth/src/index.ts
+++ b/libs/auth/src/index.ts
@@ -6,6 +6,7 @@ export { AuthBootstrap } from "./lib/components/AuthBootstrap";
 export { useIdleTimer } from "./lib/hooks/useIdleTimer";
 export { LoginPage } from "./lib/pages/LoginPage";
 export { SignupPage } from "./lib/pages/SignupPage";
+export { FaydaCallbackPage } from "./lib/pages/FaydaCallbackPage";
 export { ForgotPasswordPage } from "./lib/pages/ForgotPasswordPage";
 export { SetPasswordPage } from "./lib/pages/SetPasswordPage";
 export { OTPVerificationPage } from "./lib/pages/OTPVerificationPage";
diff --git a/libs/auth/src/lib/pages/FaydaCallbackPage.tsx b/libs/auth/src/lib/pages/FaydaCallbackPage.tsx
new file mode 100644
index 000000000..d3f9ac1d1
--- /dev/null
+++ b/libs/auth/src/lib/pages/FaydaCallbackPage.tsx
@@ -0,0 +1,119 @@
+import { useEffect, useRef, useState } from 'react';
+import { Alert, Button, Group, Loader, Stack, Text, Title } from '@mantine/core';
+import { IconAlertTriangle, IconArrowLeft } from '@tabler/icons-react';
+import { useNavigate, useSearchParams } from 'react-router-dom';
+import { useTranslation } from 'react-i18next';
+import { useApiMutation } from '@ema-platform/api';
+import { useErrorHandler } from '@ema-platform/ui';
+import { AuthShell } from '../components/AuthShell';
+import { faydaSession, type FaydaResult } from '../utils/fayda-session';
+
+/**
+ * Where Fayda returns the applicant.
+ *
+ * It creates no account and holds no credentials — it hands the authorization
+ * code to the API, stashes the normalised result, and sends the applicant back
+ * to the signup form they started on.
+ */
+export function FaydaCallbackPage() {
+  const navigate = useNavigate();
+  const { t } = useTranslation();
+  const [params] = useSearchParams();
+  const { handleError } = useErrorHandler();
+  const [error, setError] = useState<string | null>(null);
+  const [callbackTrigger] = useApiMutation<FaydaResult>();
+
+  // React 18 mounts effects twice in development, and the authorization code is
+  // single-use — the second redemption would fail and show a spurious error.
+  const redeemed = useRef(false);
+
+  useEffect(() => {
+    if (redeemed.current) return;
+    redeemed.current = true;
+
+    const code = params.get('code');
+    const state = params.get('state');
+    const providerError = params.get('error');
+    const request = faydaSession.takeRequest();
+
+    if (providerError) {
+      setError(
+        providerError === 'access_denied'
+          ? t('fayda.cancelled', 'Fayda verification was cancelled. You can still sign up manually.')
+          : t('fayda.rejected', 'Fayda could not verify your identity. Please try again.'),
+      );
+      return;
+    }
+
+    if (!code || !state) {
+      setError(t('fayda.invalidCallback', 'This verification link is incomplete. Please start again.'));
+      return;
+    }
+
+    if (!request) {
+      setError(
+        t('fayda.sessionLost', 'Your verification session has expired. Please start again.'),
+      );
+      return;
+    }
+
+    if (request.state !== state) {
+      setError(t('fayda.stateMismatch', 'This verification could not be trusted. Please start again.'));
+      return;
+    }
+
+    callbackTrigger({
+      url: '/auth/fayda/callback',
+      method: 'POST',
+      body: { code, state, transactionToken: request.transactionToken },
+    })
+      .unwrap()
+      .then((result) => {
+        faydaSession.saveResult(result);
+        // replace: the callback URL carries a spent code, so it must not come
+        // back on Back.
+        navigate('/signup', { replace: true });
+      })
+      .catch((err: unknown) => setError(handleError(err)));
+    // Runs once on mount; the guard above makes that explicit.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return (
+    <AuthShell
+      brandTitle={t('fayda.brandTitle', 'Verifying with Fayda')}
+      brandSubtitle={t('fayda.brandSubtitle', 'One moment while we confirm your identity.')}
+    >
+      <Stack gap="lg">
+        {error ? (
+          <>
+            <Title order={2} fz={26}>
+              {t('fayda.failedTitle', 'Verification incomplete')}
+            </Title>
+            <Alert
+              variant="light"
+              color="orange"
+              icon={<IconAlertTriangle size={18} />}
+            >
+              {error}
+            </Alert>
+            <Group>
+              <Button
+                variant="light"
+                leftSection={<IconArrowLeft size={18} />}
+                onClick={() => navigate('/signup', { replace: true })}
+              >
+                {t('fayda.backToSignup', 'Back to sign up')}
+              </Button>
+            </Group>
+          </>
+        ) : (
+          <Group gap="sm">
+            <Loader size="sm" />
+            <Text c="dimmed">{t('fayda.verifying', 'Verifying your Fayda identity…')}</Text>
+          </Group>
+        )}
+      </Stack>
+    </AuthShell>
+  );
+}
diff --git a/libs/auth/src/lib/pages/SignupPage.tsx b/libs/auth/src/lib/pages/SignupPage.tsx
index 13b7bb132..7045d9777 100644
--- a/libs/auth/src/lib/pages/SignupPage.tsx
+++ b/libs/auth/src/lib/pages/SignupPage.tsx
@@ -1,10 +1,11 @@
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
 import {
   Alert,
   Anchor,
+  Badge,
   Button,
   Checkbox,
-  Group,
+  Divider,
   PasswordInput,
   SimpleGrid,
   Stack,
@@ -14,11 +15,14 @@ import {
   UnstyledButton,
 } from '@mantine/core';
 import {
+  IconAlertTriangle,
   IconArrowLeft,
   IconArrowRight,
   IconAt,
+  IconId,
   IconLock,
   IconMail,
+  IconRosetteDiscountCheck,
   IconUser,
 } from '@tabler/icons-react';
 import { useForm } from 'react-hook-form';
@@ -27,12 +31,13 @@ import { z } from 'zod';
 import { useNavigate, Link } from 'react-router-dom';
 import { useDispatch } from 'react-redux';
 import { useTranslation } from 'react-i18next';
-import { useApiMutation } from '@ema-platform/api';
+import { useApiLazyQuery, useApiMutation } from '@ema-platform/api';
 import { useErrorHandler, passwordSchema, PasswordRequirements, phoneNumber, PhoneInput } from '@ema-platform/ui';
 import { AuthShell } from '../components/AuthShell';
 import { loginSuccess, setUser } from '../store/auth.slice';
 import type { AuthUser } from '../types/auth.types';
 import { useAuthConfig } from '../AuthConfig';
+import { faydaSession, type FaydaResult } from '../utils/fayda-session';
 
 interface SignupPayload {
   email: string;
@@ -62,6 +67,53 @@ export function SignupPage() {
   }>();
   const [meTrigger] = useApiMutation<AuthUser>();
 
+  // Fayda is optional: the form below works exactly as before without it.
+  const [fayda, setFayda] = useState<FaydaResult | null>(() => faydaSession.peekResult());
+  const [faydaStarting, setFaydaStarting] = useState(false);
+  const [authorizeTrigger] = useApiLazyQuery<{
+    authorizationUrl: string;
+    state: string;
+    transactionToken: string;
+    expiresIn: number;
+  }>();
+  const [linkTrigger] = useApiMutation<void>();
+
+  const verified = (field: string) => fayda?.verifiedFields.includes(field) ?? false;
+  const conflicted = (field: string) => fayda?.conflicts.includes(field) ?? false;
+
+  /**
+   * Per-field provenance, so it is obvious which values came from Fayda and
+   * which are still the applicant's to supply. Verified fields stay editable —
+   * a conflicting email has to be changeable for the form to be completable at
+   * all.
+   */
+  const faydaMark = (field: string): { description?: React.ReactNode } => {
+    if (conflicted(field)) {
+      return {
+        description: (
+          <Badge size="xs" variant="light" color="orange">
+            {t('fayda.fieldConflict', 'Already used by another account')}
+          </Badge>
+        ),
+      };
+    }
+    if (verified(field)) {
+      return {
+        description: (
+          <Badge
+            size="xs"
+            variant="light"
+            color="teal"
+            leftSection={<IconRosetteDiscountCheck size={11} />}
+          >
+            {t('fayda.fieldVerified', 'From Fayda')}
+          </Badge>
+        ),
+      };
+    }
+    return {};
+  };
+
   const handleBack = () => {
     if (window.history.length > 1) {
       navigate(-1);
@@ -118,6 +170,38 @@ export function SignupPage() {
     defaultValues: { userType: 'individual' },
   });
 
+  // Fills what Fayda vouched for and leaves the rest — username and password
+  // are always the applicant's to choose, and Fayda supplies neither.
+  useEffect(() => {
+    if (!fayda) return;
+    const { email, phoneNumber: phone, nameEn, nameAm } = fayda.prefill;
+    if (email) setValue('email', email);
+    if (phone) setValue('phoneNumber', phone);
+    if (nameEn) setValue('nameEn', nameEn);
+    if (nameAm) setValue('nameAm', nameAm);
+  }, [fayda, setValue]);
+
+  const startFayda = async () => {
+    setServerError(null);
+    setFaydaStarting(true);
+    try {
+      const { authorizationUrl, transactionToken, state } = await authorizeTrigger({
+        url: '/auth/fayda/authorize',
+      }).unwrap();
+
+      faydaSession.saveRequest({ transactionToken, state });
+      window.location.assign(authorizationUrl);
+    } catch (err: unknown) {
+      setFaydaStarting(false);
+      setServerError(handleError(err));
+    }
+  };
+
+  const clearFayda = () => {
+    faydaSession.clearResult();
+    setFayda(null);
+  };
+
   const onSubmit = async (values: FormValues) => {
     try {
       const payload: SignupPayload = {
@@ -147,6 +231,24 @@ export function SignupPage() {
       const me = await meTrigger({ url: '/auth/me', method: 'GET' }).unwrap();
       dispatch(setUser(me));
 
+      // Records the Fayda identity on the account that was just created. The
+      // registration endpoint is shared platform code and drops fields it does
+      // not know, so the link has to be a separate call. It is best-effort: the
+      // account is already usable, and the worst case is that it is not marked
+      // as Fayda-verified.
+      if (fayda) {
+        try {
+          await linkTrigger({
+            url: '/auth/fayda/link',
+            method: 'POST',
+            body: { verificationToken: fayda.verificationToken },
+          }).unwrap();
+        } catch {
+          /* deliberately ignored — signup already succeeded */
+        }
+        faydaSession.clearResult();
+      }
+
       if (data.isPhoneNumberVerified) {
         navigate(loginRedirectPath);
       } else {
@@ -212,6 +314,53 @@ export function SignupPage() {
           </Alert>
         )}
 
+        {fayda ? (
+          <Alert
+            variant="light"
+            color="teal"
+            icon={<IconRosetteDiscountCheck size={18} />}
+            title={t('fayda.verifiedTitle', 'Verified with Fayda')}
+          >
+            <Stack gap="xs">
+              <Text size="sm">
+                {t(
+                  'fayda.verifiedBody',
+                  'We filled in the details Fayda confirmed. Please complete the remaining fields.',
+                )}
+              </Text>
+              <Anchor size="sm" component="button" type="button" onClick={clearFayda}>
+                {t('fayda.discard', 'Clear these details and fill the form myself')}
+              </Anchor>
+            </Stack>
+          </Alert>
+        ) : (
+          <>
+            <Button
+              variant="default"
+              size="md"
+              fullWidth
+              loading={faydaStarting}
+              leftSection={<IconId size={18} />}
+              onClick={startFayda}
+            >
+              {t('fayda.continueWith', 'Continue with Fayda')}
+            </Button>
+            <Divider
+              label={t('fayda.orFillManually', 'or fill in your details')}
+              labelPosition="center"
+            />
+          </>
+        )}
+
+        {fayda && fayda.conflicts.length > 0 && (
+          <Alert variant="light" color="orange" icon={<IconAlertTriangle size={18} />}>
+            {t(
+              'fayda.conflictBody',
+              'Some verified details already belong to another account. Change the highlighted fields, or sign in instead.',
+            )}
+          </Alert>
+        )}
+
         <form onSubmit={handleSubmit(onSubmit)}>
           <Stack gap="md">
             <SimpleGrid cols={{ base: 1, xs: 2 }} spacing="md">
@@ -220,6 +369,7 @@ export function SignupPage() {
                 placeholder={t('signup.nameEnPlaceholder', 'Abebe Bekele')}
                 leftSection={<IconUser size={18} />}
                 error={errors.nameEn?.message}
+                {...faydaMark('nameEn')}
                 {...register('nameEn')}
               />
               <TextInput
@@ -227,6 +377,7 @@ export function SignupPage() {
                 placeholder={t('signup.nameAmPlaceholder', 'ስም')}
                 leftSection={<IconUser size={18} />}
                 error={errors.nameAm?.message}
+                {...faydaMark('nameAm')}
                 {...register('nameAm')}
               />
             </SimpleGrid>
@@ -237,6 +388,7 @@ export function SignupPage() {
                 placeholder={t('signup.emailPlaceholder', 'you@example.com')}
                 leftSection={<IconMail size={18} />}
                 error={errors.email?.message}
+                {...faydaMark('email')}
                 {...register('email')}
               />
               <TextInput
@@ -255,6 +407,7 @@ export function SignupPage() {
               onChange={(val) => setValue('phoneNumber', val, { shouldValidate: !!errors.phoneNumber })}
               onBlur={() => trigger('phoneNumber')}
               error={errors.phoneNumber?.message}
+              {...faydaMark('phoneNumber')}
             />
 
             <SimpleGrid cols={{ base: 1, xs: 2 }} spacing="md">
diff --git a/libs/auth/src/lib/utils/fayda-session.ts b/libs/auth/src/lib/utils/fayda-session.ts
new file mode 100644
index 000000000..2319e67fc
--- /dev/null
+++ b/libs/auth/src/lib/utils/fayda-session.ts
@@ -0,0 +1,81 @@
+/**
+ * The Fayda round trip leaves the app entirely, so the little state that has to
+ * survive it lives in sessionStorage: same tab, same origin, gone when the tab
+ * closes.
+ *
+ * Nothing secret is kept here. `transactionToken` and `verificationToken` are
+ * signed by the API and are useless without it — the PKCE verifier and the
+ * client secret never leave the backend.
+ */
+
+const REQUEST_KEY = 'fayda:request';
+const RESULT_KEY = 'fayda:result';
+
+export interface FaydaRequest {
+  transactionToken: string;
+  state: string;
+}
+
+export interface FaydaPrefill {
+  email?: string;
+  phoneNumber?: string;
+  nameEn?: string;
+  nameAm?: string;
+  /** Shown for context only — the signup form has no field for these. */
+  gender?: string;
+  address?: string;
+}
+
+export interface FaydaResult {
+  prefill: FaydaPrefill;
+  /** Always true when the API returned a result at all. */
+  faydaVerified: boolean;
+  /** Signup fields Fayda vouched for. */
+  verifiedFields: string[];
+  /** Prefilled fields already taken by another account. */
+  conflicts: string[];
+  /** Posted to /auth/fayda/link once the account exists. */
+  verificationToken: string;
+}
+
+// Private browsing and locked-down browsers can throw on access, and a failure
+// here should degrade to "no Fayda prefill", never break the signup page.
+function read<T>(key: string): T | null {
+  try {
+    const raw = sessionStorage.getItem(key);
+    return raw ? (JSON.parse(raw) as T) : null;
+  } catch {
+    return null;
+  }
+}
+
+function write(key: string, value: unknown): void {
+  try {
+    sessionStorage.setItem(key, JSON.stringify(value));
+  } catch {
+    /* nothing to do — the flow reports a generic failure instead */
+  }
+}
+
+function clear(key: string): void {
+  try {
+    sessionStorage.removeItem(key);
+  } catch {
+    /* ignore */
+  }
+}
+
+export const faydaSession = {
+  saveRequest: (request: FaydaRequest) => write(REQUEST_KEY, request),
+  takeRequest: (): FaydaRequest | null => {
+    const request = read<FaydaRequest>(REQUEST_KEY);
+    // Single use: a stale token would otherwise be replayed against a fresh
+    // callback and fail with a confusing "session expired".
+    clear(REQUEST_KEY);
+    return request;
+  },
+
+  saveResult: (result: FaydaResult) => write(RESULT_KEY, result),
+  peekResult: (): FaydaResult | null => read<FaydaResult>(RESULT_KEY),
+  clearResult: () => clear(RESULT_KEY),
+};

From c4c84abc660876a9425fd795574fbeb12633f57e Mon Sep 17 00:00:00 2001
From: mihretue <muluhome@gmail.com>
Date: Tue, 25 Aug 2026 13:01:40 +0000
Subject: [PATCH 06/14] refactor(signup): drive Fayda through
 register-with-fayda

Follows the API back to a single endpoint. The page posts { action: 'start' }
to open the attempt, the callback page posts { action: 'verify', ... } to get
the verified identity, and the existing signup submission is unchanged.

Drops the post-signup link call: there is no longer a link endpoint, and the
account is created by the signup endpoint that already owns user creation.
---
 libs/auth/src/lib/pages/FaydaCallbackPage.tsx |  6 ++--
 libs/auth/src/lib/pages/SignupPage.tsx        | 33 ++++++-------------
 libs/auth/src/lib/utils/fayda-session.ts      | 12 +++----
 3 files changed, 19 insertions(+), 32 deletions(-)

diff --git a/libs/auth/src/lib/pages/FaydaCallbackPage.tsx b/libs/auth/src/lib/pages/FaydaCallbackPage.tsx
index d3f9ac1d1..81314beb2 100644
--- a/libs/auth/src/lib/pages/FaydaCallbackPage.tsx
+++ b/libs/auth/src/lib/pages/FaydaCallbackPage.tsx
@@ -63,9 +63,11 @@ export function FaydaCallbackPage() {
     }
 
     callbackTrigger({
-      url: '/auth/fayda/callback',
+      url: '/auth/register-with-fayda',
       method: 'POST',
-      body: { code, state, transactionToken: request.transactionToken },
+      // `verify` returns the identity without creating an account — the
+      // existing signup endpoint still does that.
+      body: { action: 'verify', code, state, transactionToken: request.transactionToken },
     })
       .unwrap()
       .then((result) => {
diff --git a/libs/auth/src/lib/pages/SignupPage.tsx b/libs/auth/src/lib/pages/SignupPage.tsx
index 7045d9777..29b03e6c8 100644
--- a/libs/auth/src/lib/pages/SignupPage.tsx
+++ b/libs/auth/src/lib/pages/SignupPage.tsx
@@ -31,7 +31,7 @@ import { z } from 'zod';
 import { useNavigate, Link } from 'react-router-dom';
 import { useDispatch } from 'react-redux';
 import { useTranslation } from 'react-i18next';
-import { useApiLazyQuery, useApiMutation } from '@ema-platform/api';
+import { useApiMutation } from '@ema-platform/api';
 import { useErrorHandler, passwordSchema, PasswordRequirements, phoneNumber, PhoneInput } from '@ema-platform/ui';
 import { AuthShell } from '../components/AuthShell';
 import { loginSuccess, setUser } from '../store/auth.slice';
@@ -70,13 +70,12 @@ export function SignupPage() {
   // Fayda is optional: the form below works exactly as before without it.
   const [fayda, setFayda] = useState<FaydaResult | null>(() => faydaSession.peekResult());
   const [faydaStarting, setFaydaStarting] = useState(false);
-  const [authorizeTrigger] = useApiLazyQuery<{
+  const [startTrigger] = useApiMutation<{
     authorizationUrl: string;
     state: string;
     transactionToken: string;
     expiresIn: number;
   }>();
-  const [linkTrigger] = useApiMutation<void>();
 
   const verified = (field: string) => fayda?.verifiedFields.includes(field) ?? false;
   const conflicted = (field: string) => fayda?.conflicts.includes(field) ?? false;
@@ -174,7 +173,7 @@ export function SignupPage() {
   // are always the applicant's to choose, and Fayda supplies neither.
   useEffect(() => {
     if (!fayda) return;
-    const { email, phoneNumber: phone, nameEn, nameAm } = fayda.prefill;
+    const { email, phoneNumber: phone, nameEn, nameAm } = fayda.identity;
     if (email) setValue('email', email);
     if (phone) setValue('phoneNumber', phone);
     if (nameEn) setValue('nameEn', nameEn);
@@ -185,8 +184,12 @@ export function SignupPage() {
     setServerError(null);
     setFaydaStarting(true);
     try {
-      const { authorizationUrl, transactionToken, state } = await authorizeTrigger({
-        url: '/auth/fayda/authorize',
+      // Same endpoint the registration itself uses; `start` only opens the
+      // attempt and hands back where to send the user.
+      const { authorizationUrl, transactionToken, state } = await startTrigger({
+        url: '/auth/register-with-fayda',
+        method: 'POST',
+        body: { action: 'start' },
       }).unwrap();
 
       faydaSession.saveRequest({ transactionToken, state });
@@ -231,23 +234,7 @@ export function SignupPage() {
       const me = await meTrigger({ url: '/auth/me', method: 'GET' }).unwrap();
       dispatch(setUser(me));
 
-      // Records the Fayda identity on the account that was just created. The
-      // registration endpoint is shared platform code and drops fields it does
-      // not know, so the link has to be a separate call. It is best-effort: the
-      // account is already usable, and the worst case is that it is not marked
-      // as Fayda-verified.
-      if (fayda) {
-        try {
-          await linkTrigger({
-            url: '/auth/fayda/link',
-            method: 'POST',
-            body: { verificationToken: fayda.verificationToken },
-          }).unwrap();
-        } catch {
-          /* deliberately ignored — signup already succeeded */
-        }
-        faydaSession.clearResult();
-      }
+      faydaSession.clearResult();
 
       if (data.isPhoneNumberVerified) {
         navigate(loginRedirectPath);
diff --git a/libs/auth/src/lib/utils/fayda-session.ts b/libs/auth/src/lib/utils/fayda-session.ts
index 2319e67fc..d61db63c1 100644
--- a/libs/auth/src/lib/utils/fayda-session.ts
+++ b/libs/auth/src/lib/utils/fayda-session.ts
@@ -3,9 +3,9 @@
  * survive it lives in sessionStorage: same tab, same origin, gone when the tab
  * closes.
  *
- * Nothing secret is kept here. `transactionToken` and `verificationToken` are
- * signed by the API and are useless without it — the PKCE verifier and the
- * client secret never leave the backend.
+ * Nothing secret is kept here. The `transactionToken` is signed by the API and
+ * useless without it — the PKCE verifier, the nonce and the client key never
+ * leave the backend.
  */
 
 const REQUEST_KEY = 'fayda:request';
@@ -26,16 +26,14 @@ export interface FaydaPrefill {
   address?: string;
 }
 
+/** Shape of `POST /auth/register-with-fayda` with `action: "verify"`. */
 export interface FaydaResult {
-  prefill: FaydaPrefill;
-  /** Always true when the API returned a result at all. */
+  identity: FaydaPrefill;
   faydaVerified: boolean;
   /** Signup fields Fayda vouched for. */
   verifiedFields: string[];
   /** Prefilled fields already taken by another account. */
   conflicts: string[];
-  /** Posted to /auth/fayda/link once the account exists. */
-  verificationToken: string;
 }
 
 // Private browsing and locked-down browsers can throw on access, and a failure

From 0582c311c9845708055bb19f12579b7db585eda8 Mon Sep 17 00:00:00 2001
From: mihretue <muluhome@gmail.com>
Date: Tue, 25 Aug 2026 13:24:29 +0000
Subject: [PATCH 07/14] feat(signup): serve the Fayda callback at /callback too

Fayda matches the registered redirect URI exactly, and the value being
registered first is a bare /callback. The descriptive path stays so the route
still reads as part of signup once that can be changed.
---
 apps/portal/src/app/router.tsx | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/apps/portal/src/app/router.tsx b/apps/portal/src/app/router.tsx
index 348b98685..5e2c539c5 100644
--- a/apps/portal/src/app/router.tsx
+++ b/apps/portal/src/app/router.tsx
@@ -69,9 +69,14 @@ export const router = createBrowserRouter([
   { path: "/signup", element: <SignupPage /> },
 
   // Where Fayda returns the applicant. Public by necessity — they have no
-  // account yet. It redeems the code and hands control back to /signup; the
-  // path must match the API's REDIRECT_URI, which is registered with Fayda.
+  // account yet. It redeems the code and hands control back to /signup.
+  //
+  // Two paths for one page: whichever is registered with Fayda has to match the
+  // API's FAYDA_REDIRECT_URI exactly, and the value being registered first is a
+  // bare /callback. The descriptive path is kept so the route still reads as
+  // part of signup once that can be changed.
   { path: "/signup/fayda/callback", element: <FaydaCallbackPage /> },
+  { path: "/callback", element: <FaydaCallbackPage /> },
 
   // Completes the forgot-password flow; the reset message links here. The
   // IAM package generates `/reset-password` links, `/set-password` is the

From 16a5dec734375d3c5a246adf4f551afb1ab7c0c0 Mon Sep 17 00:00:00 2001
From: mihretue <muluhome@gmail.com>
Date: Tue, 25 Aug 2026 18:18:02 +0000
Subject: [PATCH 08/14] docs(env): add the .env.example the README already told
 people to copy
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

README.md line 72 says `cp .env.example .env`, but no such file existed and
.gitignore's `.env.*` rule would have swallowed it — hence the explicit
negation alongside it.

Documents the two variables the code actually reads, VITE_BASE_API_URL and
VITE_USE_MOCKS, rather than the longer list in the README, none of which is
referenced anywhere in apps/ or libs/. Notes that Vite resolves this from the
workspace root via envDir, and that Fayda needs nothing here beyond the callback
path matching the API's FAYDA_REDIRECT_URI.
---
 .env.example | 38 ++++++++++++++++++++++++++++++++++++++
 .gitignore   |  2 ++
 2 files changed, 40 insertions(+)
 create mode 100644 .env.example

diff --git a/.env.example b/.env.example
new file mode 100644
index 000000000..abf8c4034
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,38 @@
+# emaui environment
+#
+# Vite reads this from the workspace root, not from the app directory:
+# apps/portal/vite.config.mts and apps/backoffice/vite.config.mts both set
+# `envDir: '../../'`. So copy this file to ./.env here, at the repo root.
+#
+#   cp .env.example .env
+#
+# Only VITE_-prefixed values reach the browser, and everything that does is
+# public — it ships inside the built bundle. Never put a secret here. The Fayda
+# client id, private key and endpoints live in the API's environment only; the
+# frontend never speaks to Fayda directly.
+
+# Base URL of the emaapi backend, including the /api prefix.
+# Defaults to http://localhost:3000/api when unset.
+VITE_BASE_API_URL=http://localhost:3000/api
+
+# Serve fixture data instead of calling the API. Any value other than "true"
+# uses the real backend.
+VITE_USE_MOCKS=false
+
+# --- Docker Compose only -----------------------------------------------------
+# Host ports published by docker-compose.yml. It also expects per-app env files
+# at apps/portal/.env and apps/backoffice/.env, which can each be a copy of this
+# file. Ignored when running the Vite dev servers, which serve the portal on
+# 4200 and the backoffice on 4201.
+# EMA_PORTAL_PORT=8021
+# EMA_BACKOFFICE_PORT=8022
+
+# --- Fayda note --------------------------------------------------------------
+# There is nothing to configure here for Fayda. The portal serves the callback
+# page at /callback and /signup/fayda/callback, and whichever path is registered
+# with Fayda must match the API's FAYDA_REDIRECT_URI exactly.
+#
+# The value being registered first is http://localhost:3000/callback, which is
+# also emaapi's default port — so when testing that redirect, serve the portal
+# on 3000 (`npx nx serve portal --port 3000`) and move the API elsewhere, or
+# register a URI that points at the port the portal actually runs on.
diff --git a/.gitignore b/.gitignore
index 4b15bf545..8b70b3e9d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,6 +13,8 @@ coverage/
 # env
 .env
 .env.*
+# ...but the checked-in template must survive that rule.
+!.env.example
 
 # logs
 *.log

From baea9f2b577c208bd42680027748637f9f00ba09 Mon Sep 17 00:00:00 2001
From: mihretue <muluhome@gmail.com>
Date: Tue, 25 Aug 2026 19:04:27 +0000
Subject: [PATCH 09/14] chore(dev): serve the portal on 3000 for the Fayda
 redirect
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Fayda redirect URI registered for local testing is
http://localhost:3000/callback, matched exactly by the provider, so the portal
has to be the thing listening there. Its dev and preview servers move from 4200
to 3000 and the API moves to 3001.

Every hardcoded fallback to http://localhost:3000/api follows — six copies of
the same default across libs/api, libs/auth, the portal and the backoffice —
otherwise a developer without a .env would have had the app calling itself.

e2e is unaffected: it binds its own ports (3011/4302/4303) explicitly.
---
 .env.example                                      | 15 ++++++++-------
 .../certificate-designer/config/designer.ts       |  2 +-
 apps/backoffice/vite.config.mts                   |  2 +-
 apps/e2e/README.md                                |  2 +-
 .../certificates/pages/CertificatesPage.tsx       |  2 +-
 apps/portal/vite.config.mts                       |  9 ++++++---
 .../src/lib/base-api/base-query-with-reauth.ts    |  2 +-
 .../lib/features/licensing/licensing.helpers.ts   |  2 +-
 libs/api/src/lib/session/index.ts                 |  2 +-
 libs/auth/src/lib/components/AuthBootstrap.tsx    |  2 +-
 libs/auth/src/lib/utils/refresh-token.ts          |  2 +-
 11 files changed, 23 insertions(+), 19 deletions(-)

diff --git a/.env.example b/.env.example
index abf8c4034..05b61e286 100644
--- a/.env.example
+++ b/.env.example
@@ -12,8 +12,10 @@
 # frontend never speaks to Fayda directly.
 
 # Base URL of the emaapi backend, including the /api prefix.
-# Defaults to http://localhost:3000/api when unset.
-VITE_BASE_API_URL=http://localhost:3000/api
+# 3001, not 3000: the portal itself takes 3000 in development, because that is
+# the port in the Fayda redirect URI registered for local testing. Set PORT=3001
+# in emaapi's .env to match.
+VITE_BASE_API_URL=http://localhost:3001/api
 
 # Serve fixture data instead of calling the API. Any value other than "true"
 # uses the real backend.
@@ -23,7 +25,7 @@ VITE_USE_MOCKS=false
 # Host ports published by docker-compose.yml. It also expects per-app env files
 # at apps/portal/.env and apps/backoffice/.env, which can each be a copy of this
 # file. Ignored when running the Vite dev servers, which serve the portal on
-# 4200 and the backoffice on 4201.
+# 3000 and the backoffice on 4201.
 # EMA_PORTAL_PORT=8021
 # EMA_BACKOFFICE_PORT=8022
 
@@ -32,7 +34,6 @@ VITE_USE_MOCKS=false
 # page at /callback and /signup/fayda/callback, and whichever path is registered
 # with Fayda must match the API's FAYDA_REDIRECT_URI exactly.
 #
-# The value being registered first is http://localhost:3000/callback, which is
-# also emaapi's default port — so when testing that redirect, serve the portal
-# on 3000 (`npx nx serve portal --port 3000`) and move the API elsewhere, or
-# register a URI that points at the port the portal actually runs on.
+# The value being registered first is http://localhost:3000/callback, so the
+# portal's dev server now listens on 3000 and emaapi moves to 3001. Nothing
+# extra to run — `nx serve portal` already binds the right port.
diff --git a/apps/backoffice/src/app/features/certificate-designer/config/designer.ts b/apps/backoffice/src/app/features/certificate-designer/config/designer.ts
index f6fd5abae..07d22cd74 100644
--- a/apps/backoffice/src/app/features/certificate-designer/config/designer.ts
+++ b/apps/backoffice/src/app/features/certificate-designer/config/designer.ts
@@ -3,7 +3,7 @@ import type { Bilingual, LicenseCategory, LicenseTemplate, LicenseType } from '@
 /** Same resolution — and same fallback — the shared RTK Query baseQuery uses. */
 export const API_BASE_URL =
   (import.meta as { env?: Record<string, string> }).env?.['VITE_BASE_API_URL'] ??
-  'http://localhost:3000/api';
+  'http://localhost:3001/api';
 
 export const STATUS_COLOR: Record<LicenseTemplate['status'], string> = {
   DRAFT: 'gray',
diff --git a/apps/backoffice/vite.config.mts b/apps/backoffice/vite.config.mts
index 97ed5cae3..be6f4eef9 100644
--- a/apps/backoffice/vite.config.mts
+++ b/apps/backoffice/vite.config.mts
@@ -17,7 +17,7 @@ export default defineConfig({
 //   port: 4201,
 //   proxy: {
 //     '/api': {
-//       target: 'http://localhost:3000', // change from 'https://ema-api-dev.triaplc.com'
+//       target: 'http://localhost:3001', // change from 'https://ema-api-dev.triaplc.com'
 //       changeOrigin: true,
 //     },
 //   },
diff --git a/apps/e2e/README.md b/apps/e2e/README.md
index cfec73a58..86c75a6da 100644
--- a/apps/e2e/README.md
+++ b/apps/e2e/README.md
@@ -22,7 +22,7 @@ own ports, against its own database:
 | Backoffice | 4303 | same |
 | Database | — | `ema_e2e` |
 
-This is deliberate. A developer's stack is usually already up on 3000/4200/4201,
+This is deliberate. A developer's stack is usually already up on 3000/3001/4201,
 and `dev/start.sh` **rewrites** `emaapi/apps/server/emaapi/.env` and the apps'
 `.env.local` on every run — a suite that read those files would point at
 whichever stack was started last. The API is launched with `DATABASE_NAME`,
diff --git a/apps/portal/src/app/features/certificates/pages/CertificatesPage.tsx b/apps/portal/src/app/features/certificates/pages/CertificatesPage.tsx
index c15fa983b..edbe6f516 100644
--- a/apps/portal/src/app/features/certificates/pages/CertificatesPage.tsx
+++ b/apps/portal/src/app/features/certificates/pages/CertificatesPage.tsx
@@ -122,7 +122,7 @@ function formatDate(value: string | null | undefined): string {
 
 const API_BASE =
   (import.meta as { env?: Record<string, string> }).env?.['VITE_BASE_API_URL'] ??
-  'http://localhost:3000/api';
+  'http://localhost:3001/api';
 
 async function generateCertificate(profileId: string): Promise<Blob> {
   const token = authStorage.getToken();
diff --git a/apps/portal/vite.config.mts b/apps/portal/vite.config.mts
index 4e08b10fe..6487e7752 100644
--- a/apps/portal/vite.config.mts
+++ b/apps/portal/vite.config.mts
@@ -9,17 +9,20 @@ export default defineConfig({
   // built-in default.
   envDir: '../../',
   cacheDir: '../../node_modules/.vite/apps/portal',
-  server: { port: 4200, host: 'localhost' },
+  // 3000, not the usual 4200: the Fayda redirect URI registered for local
+  // testing is http://localhost:3000/callback, and the provider matches it
+  // exactly. The API moves to 3001 to make room.
+  server: { port: 3000, host: 'localhost' },
 //   server: {
 //   port: 4200,
 //   proxy: {
 //     '/api': {
-//       target: 'http://localhost:3000', // change from 'https://ema-api-dev.triaplc.com'
+//       target: 'http://localhost:3001', // change from 'https://ema-api-dev.triaplc.com'
 //       changeOrigin: true,
 //     },
 //   },
 // },
-  preview: { port: 4200, host: 'localhost' },
+  preview: { port: 3000, host: 'localhost' },
   plugins: [react(), nxViteTsPaths()],
   resolve: {
     dedupe: ['react', 'react-dom', 'react-router-dom', '@tanstack/react-query'],
diff --git a/libs/api/src/lib/base-api/base-query-with-reauth.ts b/libs/api/src/lib/base-api/base-query-with-reauth.ts
index c47336cd8..6f27c1b4f 100644
--- a/libs/api/src/lib/base-api/base-query-with-reauth.ts
+++ b/libs/api/src/lib/base-api/base-query-with-reauth.ts
@@ -5,7 +5,7 @@ import { resolveSessionContext } from "../session";
 export const BASE_API_URL =
   (import.meta as { env?: Record<string, string> }).env?.[
     "VITE_BASE_API_URL"
-  ] ?? "http://localhost:3000/api";
+  ] ?? "http://localhost:3001/api";
 
 let _onTokenExpired: (() => Promise<string>) | null = null;
 let _onAuthFailure: (() => void) | null = null;
diff --git a/libs/api/src/lib/features/licensing/licensing.helpers.ts b/libs/api/src/lib/features/licensing/licensing.helpers.ts
index ecb0218d4..c74eabbc6 100644
--- a/libs/api/src/lib/features/licensing/licensing.helpers.ts
+++ b/libs/api/src/lib/features/licensing/licensing.helpers.ts
@@ -12,7 +12,7 @@ import type {
 
 const BASE_API_URL =
   (import.meta as { env?: Record<string, string> }).env?.['VITE_BASE_API_URL'] ??
-  'http://localhost:3000/api';
+  'http://localhost:3001/api';
 
 /**
  * Uploads a document straight to the API.
diff --git a/libs/api/src/lib/session/index.ts b/libs/api/src/lib/session/index.ts
index 69277fd91..f907697ab 100644
--- a/libs/api/src/lib/session/index.ts
+++ b/libs/api/src/lib/session/index.ts
@@ -11,7 +11,7 @@ export const SESSION_HEADER_KEYS = {
  * Which app this bundle is, so it reads its own session and no one else's.
  *
  * Set by each app's store via `configureSessionScope`. Cookies ignore the
- * port, so `localhost:4200` and `localhost:4201` share one jar: without a
+ * port, so `localhost:3000` and `localhost:4201` share one jar: without a
  * scope the backoffice would happily authenticate as whoever last signed into
  * the portal, and render a staff console with an applicant's permissions.
  */
diff --git a/libs/auth/src/lib/components/AuthBootstrap.tsx b/libs/auth/src/lib/components/AuthBootstrap.tsx
index 251db18c0..afabc2988 100644
--- a/libs/auth/src/lib/components/AuthBootstrap.tsx
+++ b/libs/auth/src/lib/components/AuthBootstrap.tsx
@@ -8,7 +8,7 @@ import type { AuthUser } from '../types/auth.types';
 
 const BASE_API_URL =
   (import.meta as { env?: Record<string, string> }).env?.['VITE_BASE_API_URL'] ??
-  'http://localhost:3000/api';
+  'http://localhost:3001/api';
 
 /**
  * Restores the signed-in session before the router renders.
diff --git a/libs/auth/src/lib/utils/refresh-token.ts b/libs/auth/src/lib/utils/refresh-token.ts
index 4b6997f8a..1d5312593 100644
--- a/libs/auth/src/lib/utils/refresh-token.ts
+++ b/libs/auth/src/lib/utils/refresh-token.ts
@@ -3,7 +3,7 @@ import { authStorage } from "./auth-storage";
 const BASE_API_URL =
   (import.meta as { env?: Record<string, string> }).env?.[
     "VITE_BASE_API_URL"
-  ] ?? "http://localhost:3000/api";
+  ] ?? "http://localhost:3001/api";
 
 interface RefreshResponse {
   token: string;

From 5ad43ba7609e6c29b8e19b4c9961cbf9186b6350 Mon Sep 17 00:00:00 2001
From: mihretue <mihretuendeshaw84@gmail.com>
Date: Wed, 26 Aug 2026 06:23:06 +0000
Subject: [PATCH 10/14] fix(exam): step the exam form instead of validating
 hidden tabs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Submitting from Basic Info complained that required fields on the Settings
tab were empty — a correct error the user could not act on, since Settings
had not been shown yet.

The primary action now reads "Next" while Basic Info is open and validates
only that tab before moving on; Create/Update appears on Settings, the final
step, alongside a Back button. Submit still checks both tabs, since the tab
headers stay clickable and a user can reach Settings without going through
Next.
---
 .../features/exam/pages/ExamPage/index.tsx    | 66 +++++++++++++++----
 apps/backoffice/src/app/i18n/locales/am.ts    |  2 +
 apps/backoffice/src/app/i18n/locales/en.ts    |  2 +
 3 files changed, 57 insertions(+), 13 deletions(-)

diff --git a/apps/backoffice/src/app/features/exam/pages/ExamPage/index.tsx b/apps/backoffice/src/app/features/exam/pages/ExamPage/index.tsx
index 34039328c..1bdf2c247 100644
--- a/apps/backoffice/src/app/features/exam/pages/ExamPage/index.tsx
+++ b/apps/backoffice/src/app/features/exam/pages/ExamPage/index.tsx
@@ -79,21 +79,44 @@ function ExamForm({
   const [status, setStatus] = useState<string | null>(editing?.status ?? null);
   const [activeTab, setActiveTab] = useState<string | null>("basic");
 
-  const handleSubmit = (e: React.FormEvent) => {
-    e.preventDefault();
+  /**
+   * Split per tab so "Next" can check just the tab in front of the user.
+   * Submitting from Basic Info used to complain about Settings fields the
+   * user had not been shown yet — the error was correct and unactionable at
+   * the same time. Each returns the message key for what is missing, or null.
+   */
+  const validateBasic = (): string | null => {
     if (!certificationId || !titleEn || !titleAm || !date || !venue) {
-      setActiveTab("basic");
-      notify.error(t("exam.form.fillRequiredBasic"));
-      return;
+      return "exam.form.fillRequiredBasic";
     }
     if ((directionEn || directionAm) && !(directionEn && directionAm)) {
-      setActiveTab("basic");
-      notify.error(t("exam.form.directionBothLanguages"));
+      return "exam.form.directionBothLanguages";
+    }
+    return null;
+  };
+
+  const validateSettings = (): string | null =>
+    !type || !form || !adminMethod || !evalMethod || !cuttingPoint
+      ? "exam.form.fillRequiredSettings"
+      : null;
+
+  const goNext = () => {
+    const error = validateBasic();
+    if (error) {
+      notify.error(t(error));
       return;
     }
-    if (!type || !form || !adminMethod || !evalMethod || !cuttingPoint) {
-      setActiveTab("settings");
-      notify.error(t("exam.form.fillRequiredSettings"));
+    setActiveTab("settings");
+  };
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    // Still checks both: the tabs are clickable, so a user can reach Settings
+    // without going through Next.
+    const error = validateBasic() ?? validateSettings();
+    if (error) {
+      setActiveTab(error === "exam.form.fillRequiredSettings" ? "settings" : "basic");
+      notify.error(t(error));
       return;
     }
     onSubmit(
@@ -337,9 +360,26 @@ function ExamForm({
           <Button variant="default" onClick={onCancel} size="sm">
             {t("exam.cancel")}
           </Button>
-          <Button type="submit" size="sm" loading={isSubmitting}>
-            {editing ? t("exam.update") : t("exam.create")}
-          </Button>
+          {activeTab === "basic" ? (
+            /* Not type="submit": Basic Info is not the last step, so the
+               primary action advances rather than saves. */
+            <Button size="sm" onClick={goNext}>
+              {t("exam.form.next")}
+            </Button>
+          ) : (
+            <>
+              <Button
+                variant="default"
+                size="sm"
+                onClick={() => setActiveTab("basic")}
+              >
+                {t("exam.form.back")}
+              </Button>
+              <Button type="submit" size="sm" loading={isSubmitting}>
+                {editing ? t("exam.update") : t("exam.create")}
+              </Button>
+            </>
+          )}
         </ModalFooter>
       </form>
     </Modal>
diff --git a/apps/backoffice/src/app/i18n/locales/am.ts b/apps/backoffice/src/app/i18n/locales/am.ts
index c8e51193d..9bdb4e114 100644
--- a/apps/backoffice/src/app/i18n/locales/am.ts
+++ b/apps/backoffice/src/app/i18n/locales/am.ts
@@ -271,6 +271,8 @@ export const am: Translations = {
       cuttingPointPercentageHint: "የመቶኛ ግምገማ — ከ100 አይበልጥም።",
       fillRequiredBasic: "በመሠረታዊ መረጃ ውስጥ ያሉ አስፈላጊ መስኮችን ይሙሉ።",
       fillRequiredSettings: "በቅንብሮች ውስጥ ያሉ አስፈላጊ መስኮችን ይሙሉ — ዓይነት፣ ቅጽ፣ የአስተዳደር ዘዴ፣ የግምገማ ዘዴ እና የማለፊያ ነጥብ።",
+      next: "ቀጣይ",
+      back: "ተመለስ",
       directionBothLanguages: "መመሪያ በሁለቱም እንግሊዝኛ እና አማርኛ ጽሑፍ ያስፈልገዋል፣ ወይም ሁለቱንም ባዶ ይተዉ።",
       status: "ሁኔታ",
       statusPlaceholder: "የፈተና ሁኔታ",
diff --git a/apps/backoffice/src/app/i18n/locales/en.ts b/apps/backoffice/src/app/i18n/locales/en.ts
index 7152067ce..ceb6e6c38 100644
--- a/apps/backoffice/src/app/i18n/locales/en.ts
+++ b/apps/backoffice/src/app/i18n/locales/en.ts
@@ -271,6 +271,8 @@ export const en = {
       fillRequiredBasic: 'Please fill all required fields in Basic Info.',
       fillRequiredSettings: 'Please fill all required fields in Settings — type, form, administration method, evaluation method, and cutting point.',
       directionBothLanguages: 'Direction needs text in both English and Amharic, or leave both empty.',
+      next: 'Next',
+      back: 'Back',
       status: 'Status',
       statusPlaceholder: 'Exam status',
       pending: 'Pending',

From c753009ed99bd40c37feaa5432d9a1fe67c8dcc8 Mon Sep 17 00:00:00 2001
From: mihretue <muluhome@gmail.com>
Date: Wed, 26 Aug 2026 09:09:25 +0000
Subject: [PATCH 11/14] refactor(api): resolve the backend URL in one place
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

VITE_BASE_API_URL with a localhost:3001/api fallback was re-derived in six
files across libs/api, libs/auth, the portal and the backoffice — and a seventh
site (UserManagementPage) read the env raw with no fallback at all, handing the
IAM user-management app an undefined apiUrl whenever no .env was present.

BASE_API_URL in base-query-with-reauth.ts is now the single definition,
exported from @ema-platform/api; every other site imports it. Trims the env
value and treats blank as unset, matching how the backend reads its own keys.
---
 .../app/features/certificate-designer/config/designer.ts   | 6 +++---
 .../app/features/user-management/UserManagementPage.tsx    | 3 ++-
 .../app/features/certificates/pages/CertificatesPage.tsx   | 4 +---
 libs/api/src/index.ts                                      | 2 +-
 libs/api/src/lib/base-api/base-query-with-reauth.ts        | 7 ++++++-
 libs/api/src/lib/features/licensing/licensing.helpers.ts   | 4 +---
 libs/auth/src/lib/components/AuthBootstrap.tsx             | 4 +---
 libs/auth/src/lib/utils/refresh-token.ts                   | 5 +----
 8 files changed, 16 insertions(+), 19 deletions(-)

diff --git a/apps/backoffice/src/app/features/certificate-designer/config/designer.ts b/apps/backoffice/src/app/features/certificate-designer/config/designer.ts
index 07d22cd74..056d2a739 100644
--- a/apps/backoffice/src/app/features/certificate-designer/config/designer.ts
+++ b/apps/backoffice/src/app/features/certificate-designer/config/designer.ts
@@ -1,9 +1,9 @@
 import type { Bilingual, LicenseCategory, LicenseTemplate, LicenseType } from '@ema-platform/api';
 
+import { BASE_API_URL } from '@ema-platform/api';
+
 /** Same resolution — and same fallback — the shared RTK Query baseQuery uses. */
-export const API_BASE_URL =
-  (import.meta as { env?: Record<string, string> }).env?.['VITE_BASE_API_URL'] ??
-  'http://localhost:3001/api';
+export const API_BASE_URL = BASE_API_URL;
 
 export const STATUS_COLOR: Record<LicenseTemplate['status'], string> = {
   DRAFT: 'gray',
diff --git a/apps/backoffice/src/app/features/user-management/UserManagementPage.tsx b/apps/backoffice/src/app/features/user-management/UserManagementPage.tsx
index 6a96bba84..20d277399 100644
--- a/apps/backoffice/src/app/features/user-management/UserManagementPage.tsx
+++ b/apps/backoffice/src/app/features/user-management/UserManagementPage.tsx
@@ -3,6 +3,7 @@ import { useCallback, useEffect, useRef } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 import { useNavigate } from 'react-router-dom';
 import { UserManagementApp } from '@tria-plc/iamui';
+import { BASE_API_URL } from '@ema-platform/api';
 import type { DesignConfig, UserManagementSessionOptions } from '@tria-plc/iamui';
 import '@tria-plc/iamui/style.css';
 
@@ -99,7 +100,7 @@ const UM_CONFIG: DesignConfig = {
 
 const UM_RUNTIME = {
   basename: '/um',
-  apiUrl: import.meta.env.VITE_BASE_API_URL,
+  apiUrl: BASE_API_URL,
 };
 
 const buttonStyle: React.CSSProperties = {
diff --git a/apps/portal/src/app/features/certificates/pages/CertificatesPage.tsx b/apps/portal/src/app/features/certificates/pages/CertificatesPage.tsx
index edbe6f516..f7cf52743 100644
--- a/apps/portal/src/app/features/certificates/pages/CertificatesPage.tsx
+++ b/apps/portal/src/app/features/certificates/pages/CertificatesPage.tsx
@@ -120,9 +120,7 @@ function formatDate(value: string | null | undefined): string {
   });
 }
 
-const API_BASE =
-  (import.meta as { env?: Record<string, string> }).env?.['VITE_BASE_API_URL'] ??
-  'http://localhost:3001/api';
+import { BASE_API_URL as API_BASE } from '@ema-platform/api';
 
 async function generateCertificate(profileId: string): Promise<Blob> {
   const token = authStorage.getToken();
diff --git a/libs/api/src/index.ts b/libs/api/src/index.ts
index 903012532..e01bec7dd 100644
--- a/libs/api/src/index.ts
+++ b/libs/api/src/index.ts
@@ -7,5 +7,5 @@ export * from './lib/features/seafarer';
 export * from './lib/features/seafarer-registration';
 export * from './lib/features/seafarer-document';
 export * from './lib/features/vessel';
-export { baseQueryWithReauth, configureTokenRefresh } from './lib/base-api/base-query-with-reauth';
+export { BASE_API_URL, baseQueryWithReauth, configureTokenRefresh } from './lib/base-api/base-query-with-reauth';
 export { openAuthedDocument, downloadAuthedFile } from './lib/base-api/download';
diff --git a/libs/api/src/lib/base-api/base-query-with-reauth.ts b/libs/api/src/lib/base-api/base-query-with-reauth.ts
index 6f27c1b4f..8b9feb2cb 100644
--- a/libs/api/src/lib/base-api/base-query-with-reauth.ts
+++ b/libs/api/src/lib/base-api/base-query-with-reauth.ts
@@ -2,10 +2,15 @@ import { fetchBaseQuery, type BaseQueryFn } from "@reduxjs/toolkit/query/react";
 import type { FetchArgs, FetchBaseQueryError } from "@reduxjs/toolkit/query";
 import { resolveSessionContext } from "../session";
 
+/**
+ * The one place the backend URL is resolved: VITE_BASE_API_URL from the env,
+ * falling back to the local dev API (3001 — the portal itself owns 3000 for
+ * the Fayda redirect). Import this; do not re-derive it.
+ */
 export const BASE_API_URL =
   (import.meta as { env?: Record<string, string> }).env?.[
     "VITE_BASE_API_URL"
-  ] ?? "http://localhost:3001/api";
+  ]?.trim() || "http://localhost:3001/api";
 
 let _onTokenExpired: (() => Promise<string>) | null = null;
 let _onAuthFailure: (() => void) | null = null;
diff --git a/libs/api/src/lib/features/licensing/licensing.helpers.ts b/libs/api/src/lib/features/licensing/licensing.helpers.ts
index c74eabbc6..e5833387d 100644
--- a/libs/api/src/lib/features/licensing/licensing.helpers.ts
+++ b/libs/api/src/lib/features/licensing/licensing.helpers.ts
@@ -10,9 +10,7 @@ import type {
   ValidationIssue,
 } from './licensing.types';
 
-const BASE_API_URL =
-  (import.meta as { env?: Record<string, string> }).env?.['VITE_BASE_API_URL'] ??
-  'http://localhost:3001/api';
+import { BASE_API_URL } from '../../base-api/base-query-with-reauth';
 
 /**
  * Uploads a document straight to the API.
diff --git a/libs/auth/src/lib/components/AuthBootstrap.tsx b/libs/auth/src/lib/components/AuthBootstrap.tsx
index afabc2988..264738c00 100644
--- a/libs/auth/src/lib/components/AuthBootstrap.tsx
+++ b/libs/auth/src/lib/components/AuthBootstrap.tsx
@@ -6,9 +6,7 @@ import { hydrateAuth, logout, setToken, setUser } from '../store/auth.slice';
 import { refreshAccessToken } from '../utils/refresh-token';
 import type { AuthUser } from '../types/auth.types';
 
-const BASE_API_URL =
-  (import.meta as { env?: Record<string, string> }).env?.['VITE_BASE_API_URL'] ??
-  'http://localhost:3001/api';
+import { BASE_API_URL } from '@ema-platform/api';
 
 /**
  * Restores the signed-in session before the router renders.
diff --git a/libs/auth/src/lib/utils/refresh-token.ts b/libs/auth/src/lib/utils/refresh-token.ts
index 1d5312593..6ceb275cf 100644
--- a/libs/auth/src/lib/utils/refresh-token.ts
+++ b/libs/auth/src/lib/utils/refresh-token.ts
@@ -1,9 +1,6 @@
 import { authStorage } from "./auth-storage";
 
-const BASE_API_URL =
-  (import.meta as { env?: Record<string, string> }).env?.[
-    "VITE_BASE_API_URL"
-  ] ?? "http://localhost:3001/api";
+import { BASE_API_URL } from "@ema-platform/api";
 
 interface RefreshResponse {
   token: string;

From 12ffa72cb254d437e114abe3d0fae88002cd8ea4 Mon Sep 17 00:00:00 2001
From: mihretue <mihretuendeshaw84@gmail.com>
Date: Thu, 27 Aug 2026 13:10:46 +0000
Subject: [PATCH 12/14] fix(exam): gate Take Exam on confirmed attendance
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The registrations table mirrored the server's old attendance deny-list —
ABSENT/WITHDRAWN/DISQUALIFIED — so the default REGISTERED fell through and
"Take exam" appeared before any invigilator had confirmed the candidate was
there. It is an allow-list now, PRESENT and LATE only, matching
ExamAttemptService.MAY_SIT.

A blocked candidate gets a reason rather than an empty cell: "Awaiting
attendance" with a tooltip while nobody has called the register, "Not sitting"
once attendance was taken and they are not. useExamAttempt does the same for
the direct-link path, and translates attendance_not_confirmed /
candidate_not_present instead of showing a raw error key on a Start button
that cannot work. The server refuses either way — this only makes the refusal
legible.

ScheduleExamModal no longer promises an admission number: scheduling makes a
sitting available, and the candidate registers for it themselves.
---
 .../components/ScheduleExamModal.tsx          |  7 ++--
 .../exam-attempt/hooks/useExamAttempt.ts      | 25 +++++++++++++-
 .../exams/pages/ExamsPage/columns.tsx         | 34 ++++++++++++++++---
 apps/portal/src/app/i18n/locales/am.ts        |  4 +++
 apps/portal/src/app/i18n/locales/en.ts        |  4 +++
 5 files changed, 66 insertions(+), 8 deletions(-)

diff --git a/apps/backoffice/src/app/features/license-review/components/ScheduleExamModal.tsx b/apps/backoffice/src/app/features/license-review/components/ScheduleExamModal.tsx
index 641ffc864..320f5a6e2 100644
--- a/apps/backoffice/src/app/features/license-review/components/ScheduleExamModal.tsx
+++ b/apps/backoffice/src/app/features/license-review/components/ScheduleExamModal.tsx
@@ -22,6 +22,9 @@ interface Props {
  * of a per-candidate appointment. Scoped to sittings whose certification
  * matches this application's rank, so a Chief Mate candidate cannot be seated
  * into an OOW Deck sitting by accident.
+ *
+ * Scheduling makes the sitting available; it does not register the candidate.
+ * That is their own act, from the portal's Register button.
  */
 export function ScheduleExamModal({
   opened,
@@ -61,7 +64,7 @@ export function ScheduleExamModal({
         <Text size="sm" c="dimmed">
           {t('review.scheduleExam.intro', {
             defaultValue:
-              'Assign {{applicant}} to a scheduled sitting. They will be notified with the date and their admission number.',
+              'Make a sitting available to {{applicant}}. They register for it themselves from the portal.',
             applicant: applicantName,
           })}
         </Text>
@@ -89,7 +92,7 @@ export function ScheduleExamModal({
         <Text size="xs" c="dimmed">
           {t(
             'review.scheduleExam.admissionHint',
-            'An admission number is issued automatically when the candidate is seated.',
+            'Scheduling does not seat the candidate. They must register for the sitting from the portal, and the admission number is issued then.',
           )}
         </Text>
 
diff --git a/apps/portal/src/app/features/exam-attempt/hooks/useExamAttempt.ts b/apps/portal/src/app/features/exam-attempt/hooks/useExamAttempt.ts
index e671dba76..baa445600 100644
--- a/apps/portal/src/app/features/exam-attempt/hooks/useExamAttempt.ts
+++ b/apps/portal/src/app/features/exam-attempt/hooks/useExamAttempt.ts
@@ -9,6 +9,9 @@ import type {
   SaveState,
 } from '../types/exam-attempt';
 
+/** Mirrors the server's allow-list (ExamAttemptService.MAY_SIT). */
+const MAY_SIT = ['PRESENT', 'LATE'];
+
 const ESSAY_DEBOUNCE_MS = 1500;
 
 type ViewState = 'loading' | 'not-started' | 'taking' | 'completed' | 'error';
@@ -83,6 +86,19 @@ export function useExamAttempt(examId: string | undefined) {
       setErrorMessage('You are not registered for this examination.');
       return;
     }
+    // Attendance gates the sitting, and the exam list already hides "Take
+    // exam" for these — this is the direct-link path. The server refuses
+    // either way (ExamAttemptService.MAY_SIT); this only makes the refusal
+    // legible instead of a raw error key on a Start button that never works.
+    if (!MAY_SIT.includes(registration.attendanceStatus)) {
+      setViewState('error');
+      setErrorMessage(
+        registration.attendanceStatus === 'REGISTERED'
+          ? 'An invigilator must confirm you are present before this exam opens.'
+          : 'Your attendance record does not permit sitting this examination.',
+      );
+      return;
+    }
     if (mineData) {
       seedFrom(mineData);
       return;
@@ -200,7 +216,14 @@ export function useExamAttempt(examId: string | undefined) {
       }).unwrap();
       seedFrom(result);
     } catch (error) {
-      notify.error(extractErrorMessage(error, 'Could not start the exam.'));
+      const key = extractErrorMessage(error, 'Could not start the exam.');
+      notify.error(
+        key === 'attendance_not_confirmed'
+          ? 'An invigilator must confirm you are present before this exam opens.'
+          : key === 'candidate_not_present'
+            ? 'Your attendance record does not permit sitting this examination.'
+            : key,
+      );
     }
   }, [examId, startTrigger, seedFrom]);
 
diff --git a/apps/portal/src/app/features/exams/pages/ExamsPage/columns.tsx b/apps/portal/src/app/features/exams/pages/ExamsPage/columns.tsx
index 06cf8a4f6..652e72fc3 100644
--- a/apps/portal/src/app/features/exams/pages/ExamsPage/columns.tsx
+++ b/apps/portal/src/app/features/exams/pages/ExamsPage/columns.tsx
@@ -1,4 +1,4 @@
-import { Badge, Button, Text } from '@mantine/core';
+import { Badge, Button, Text, Tooltip } from '@mantine/core';
 import { IconFileText, IconGavel, IconPlayerPlay } from '@tabler/icons-react';
 import type { TFunction } from 'i18next';
 import type { AdvancedColumn } from '@ema-platform/ui';
@@ -20,7 +20,14 @@ const ATTENDANCE_COLOR: Record<AttendanceStatus, string> = {
   DISQUALIFIED: 'red',
 };
 
-const NOT_SITTING: AttendanceStatus[] = ['ABSENT', 'WITHDRAWN', 'DISQUALIFIED'];
+/**
+ * Attendance rulings that permit sitting the paper — an allow-list mirroring
+ * the server's (ExamAttemptService.MAY_SIT). The deny-list this replaced named
+ * only ABSENT/WITHDRAWN/DISQUALIFIED, so the default REGISTERED fell through
+ * and "Take exam" appeared before any invigilator had confirmed the candidate
+ * was there. LATE counts: a late arrival is present, just not on time.
+ */
+const MAY_SIT: AttendanceStatus[] = ['PRESENT', 'LATE'];
 
 export function registrationColumns(
   t: TFunction,
@@ -115,9 +122,26 @@ export function registrationColumns(
             </Badge>
           );
         }
-        const eligible =
-          exam?.status === 'ACTIVE' && !NOT_SITTING.includes(row.original.attendanceStatus);
-        if (!eligible || !deps.can([PORTAL_PERMISSIONS.APPLY_EXAM])) return null;
+        if (!deps.can([PORTAL_PERMISSIONS.APPLY_EXAM])) return null;
+        // Say why the exam is shut rather than rendering an empty cell: the
+        // candidate is waiting on an invigilator, and silence reads as a bug.
+        if (row.original.attendanceStatus === 'REGISTERED') {
+          return (
+            <Tooltip label={t('exams.columns.awaitingAttendanceHint')} multiline w={240}>
+              <Badge size="sm" variant="light" color="gray">
+                {t('exams.columns.awaitingAttendance')}
+              </Badge>
+            </Tooltip>
+          );
+        }
+        if (!MAY_SIT.includes(row.original.attendanceStatus)) {
+          return (
+            <Badge size="sm" variant="light" color="orange">
+              {t('exams.columns.notSitting')}
+            </Badge>
+          );
+        }
+        if (exam?.status !== 'ACTIVE') return null;
         return (
           <Button
             size="compact-xs"
diff --git a/apps/portal/src/app/i18n/locales/am.ts b/apps/portal/src/app/i18n/locales/am.ts
index 0ecee5cda..fabde4809 100644
--- a/apps/portal/src/app/i18n/locales/am.ts
+++ b/apps/portal/src/app/i18n/locales/am.ts
@@ -978,6 +978,10 @@ export const am: Translations = {
       timeExpired: 'ጊዜው አልቋል',
       resumeExam: 'ፈተና ይቀጥሉ',
       takeExam: 'ፈተና ይውሰዱ',
+      awaitingAttendance: 'መገኘት በመጠባበቅ ላይ',
+      awaitingAttendanceHint:
+        'ፈተናው ከመከፈቱ በፊት ተቆጣጣሪ መገኘትዎን ማረጋገጥ አለበት።',
+      notSitting: 'አይፈተኑም',
       attendanceStatus: {
         REGISTERED: 'አልተጠራም',
         PRESENT: 'ተገኝቷል',
diff --git a/apps/portal/src/app/i18n/locales/en.ts b/apps/portal/src/app/i18n/locales/en.ts
index 57fe394f3..77c72eb88 100644
--- a/apps/portal/src/app/i18n/locales/en.ts
+++ b/apps/portal/src/app/i18n/locales/en.ts
@@ -980,6 +980,10 @@ export const en = {
       timeExpired: 'Time expired',
       resumeExam: 'Resume exam',
       takeExam: 'Take exam',
+      awaitingAttendance: 'Awaiting attendance',
+      awaitingAttendanceHint:
+        'An invigilator must confirm you are present before the exam opens.',
+      notSitting: 'Not sitting',
       attendanceStatus: {
         REGISTERED: 'Not called',
         PRESENT: 'Present',

From 8992d924940999e399d735188a638a61476a1d01 Mon Sep 17 00:00:00 2001
From: mihretue <muluhome@gmail.com>
Date: Thu, 27 Aug 2026 13:42:18 +0000
Subject: [PATCH 13/14] feat(signup): present the Fayda proof after signup and
 skip the second OTP
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The verify step now returns an encrypted verificationToken alongside the
readable identity. After the existing signup succeeds, the page posts it to
POST /profiles/me/fayda, which marks the phone verified when it is the one
Fayda vouched for and fills the still-empty profile fields. Best-effort: the
account already works if the call fails, and the token can be presented again.

When the server confirms the phone, the page goes straight to the portal
instead of /otp-verify — Fayda already verified that exact number with its own
OTP, and asking for a second one on the same number is theatre. An applicant
who edited the prefilled number still gets the normal OTP step.
---
 libs/auth/src/lib/pages/SignupPage.tsx   | 27 ++++++++++++++++++++++--
 libs/auth/src/lib/utils/fayda-session.ts |  8 +++++++
 2 files changed, 33 insertions(+), 2 deletions(-)

diff --git a/libs/auth/src/lib/pages/SignupPage.tsx b/libs/auth/src/lib/pages/SignupPage.tsx
index 29b03e6c8..3b41c45de 100644
--- a/libs/auth/src/lib/pages/SignupPage.tsx
+++ b/libs/auth/src/lib/pages/SignupPage.tsx
@@ -76,6 +76,7 @@ export function SignupPage() {
     transactionToken: string;
     expiresIn: number;
   }>();
+  const [linkTrigger] = useApiMutation<{ phoneNumberVerified?: boolean }>();
 
   const verified = (field: string) => fayda?.verifiedFields.includes(field) ?? false;
   const conflicted = (field: string) => fayda?.conflicts.includes(field) ?? false;
@@ -89,8 +90,10 @@ export function SignupPage() {
   const faydaMark = (field: string): { description?: React.ReactNode } => {
     if (conflicted(field)) {
       return {
+        // component="span" on these badges: the description slot renders
+        // inside a <p>, where Badge's default <div> is invalid HTML.
         description: (
-          <Badge size="xs" variant="light" color="orange">
+          <Badge component="span" size="xs" variant="light" color="orange">
             {t('fayda.fieldConflict', 'Already used by another account')}
           </Badge>
         ),
@@ -100,6 +103,7 @@ export function SignupPage() {
       return {
         description: (
           <Badge
+            component="span"
             size="xs"
             variant="light"
             color="teal"
@@ -234,9 +238,28 @@ export function SignupPage() {
       const me = await meTrigger({ url: '/auth/me', method: 'GET' }).unwrap();
       dispatch(setUser(me));
 
+      // Records the Fayda-verified identity on the new account: marks the
+      // phone verified when it is the one Fayda vouched for, and fills the
+      // still-empty profile fields. Best-effort — the account already works,
+      // and the token can be presented again on a retry.
+      let faydaPhoneVerified = false;
+      if (fayda?.verificationToken) {
+        try {
+          const applied = await linkTrigger({
+            url: '/profiles/me/fayda',
+            method: 'POST',
+            body: { verificationToken: fayda.verificationToken },
+          }).unwrap();
+          faydaPhoneVerified = Boolean(applied?.phoneNumberVerified);
+        } catch {
+          /* deliberately ignored — signup already succeeded */
+        }
+      }
       faydaSession.clearResult();
 
-      if (data.isPhoneNumberVerified) {
+      // Fayda already verified this exact number via its own OTP; asking for
+      // a second OTP on the same number is theatre.
+      if (data.isPhoneNumberVerified || faydaPhoneVerified) {
         navigate(loginRedirectPath);
       } else {
         navigate('/otp-verify', {
diff --git a/libs/auth/src/lib/utils/fayda-session.ts b/libs/auth/src/lib/utils/fayda-session.ts
index d61db63c1..0dda61b00 100644
--- a/libs/auth/src/lib/utils/fayda-session.ts
+++ b/libs/auth/src/lib/utils/fayda-session.ts
@@ -24,6 +24,9 @@ export interface FaydaPrefill {
   /** Shown for context only — the signup form has no field for these. */
   gender?: string;
   address?: string;
+  birthdate?: string;
+  nationality?: string;
+  faydaNumber?: string;
 }
 
 /** Shape of `POST /auth/register-with-fayda` with `action: "verify"`. */
@@ -34,6 +37,11 @@ export interface FaydaResult {
   verifiedFields: string[];
   /** Prefilled fields already taken by another account. */
   conflicts: string[];
+  /**
+   * Encrypted proof of the verification, presented to POST /profiles/me/fayda
+   * after signup so the account and profile record what Fayda vouched for.
+   */
+  verificationToken: string;
 }
 
 // Private browsing and locked-down browsers can throw on access, and a failure

From a66eef352cf7ed54e2fe02a97069d8696a5c008c Mon Sep 17 00:00:00 2001
From: nati14575 <natinigussie7@gmail.com>
Date: Fri, 28 Aug 2026 14:38:56 +0300
Subject: [PATCH 14/14] feat(i18n): add biometric-related translations and
 update navigation permissions

---
 apps/backoffice/src/app/i18n/locales/am.ts    | 2 ++
 apps/backoffice/src/app/i18n/locales/en.ts    | 2 ++
 apps/backoffice/src/app/layouts/nav-config.ts | 8 +++++++-
 apps/backoffice/src/app/router/index.tsx      | 8 +++++++-
 apps/portal/src/app/i18n/locales/am.ts        | 1 +
 apps/portal/src/app/i18n/locales/en.ts        | 1 +
 6 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/apps/backoffice/src/app/i18n/locales/am.ts b/apps/backoffice/src/app/i18n/locales/am.ts
index e83e9929a..64af78746 100644
--- a/apps/backoffice/src/app/i18n/locales/am.ts
+++ b/apps/backoffice/src/app/i18n/locales/am.ts
@@ -88,6 +88,8 @@ export const am: Translations = {
     btcQueue: "የBTC ወረፋ",
     cocQueue: "የCoC ወረፋ",
     copQueue: "የCoP ወረፋ",
+    endorsementCocQueue: "የCoC እውቅና ወረፋ",
+    endorsementGocQueue: "የGOC እውቅና ወረፋ",
     endorsementQueue: "የማስተያየት ወረፋ",
     vesselRegistrations: "የመርከብ ምዝገባ",
     // vesselRegistrationReport: 'የምዝገባ ሪፖርት',
diff --git a/apps/backoffice/src/app/i18n/locales/en.ts b/apps/backoffice/src/app/i18n/locales/en.ts
index ff4fc4f15..e299655ec 100644
--- a/apps/backoffice/src/app/i18n/locales/en.ts
+++ b/apps/backoffice/src/app/i18n/locales/en.ts
@@ -88,6 +88,8 @@ export const en = {
     postWaiverQueue: 'Post-Waiver Queue',
     cocQueue: 'CoC Queue',
     copQueue: 'CoP Queue',
+    endorsementCocQueue: 'CoC Endorsement Queue',
+    endorsementGocQueue: 'GOC Endorsement Queue',
     endorsementQueue: 'Endorsement Queue',
     vesselRegistrations: 'Vessel Registration',
     vesselTransfers: 'Vessel Ownership Transfer',
diff --git a/apps/backoffice/src/app/layouts/nav-config.ts b/apps/backoffice/src/app/layouts/nav-config.ts
index 1f4a7eb02..9ed42fd62 100644
--- a/apps/backoffice/src/app/layouts/nav-config.ts
+++ b/apps/backoffice/src/app/layouts/nav-config.ts
@@ -42,6 +42,12 @@ const APPLICATION_QUEUE = [P.VIEW_APPLICATION_QUEUE, P.VIEW_APPLICATIONS];
  */
 const SEAFARER_QUEUE = [P.VIEW_SEAFARER_REGISTRY, ...APPLICATION_QUEUE];
 
+const BIOMETRIC_ENROLLMENT = [
+  P.ENROLL_BIOMETRICS,
+  P.VIEW_BIOMETRICS,
+  P.VIEW_SEAFARER_REGISTRY,
+];
+
 /**
  * The backoffice information architecture.
  *
@@ -149,7 +155,7 @@ export const NAV_SECTIONS: NavSection[] = [
         to: "/biometric-enrollment",
         label: "nav.biometricEnrollment",
         icon: IconFingerprint,
-        permissions: [P.ENROLL_BIOMETRICS, P.VIEW_BIOMETRICS],
+        permissions: BIOMETRIC_ENROLLMENT,
       },
       {
         to: "/seafarer-registrations",
diff --git a/apps/backoffice/src/app/router/index.tsx b/apps/backoffice/src/app/router/index.tsx
index 46f0879f0..12a801650 100644
--- a/apps/backoffice/src/app/router/index.tsx
+++ b/apps/backoffice/src/app/router/index.tsx
@@ -53,6 +53,12 @@ import { BiometricEnrollmentPage } from '../features/biometric-enrollment/pages/
 /** Any-of gate shared by every licence-type queue and its review workspace. */
 const APPLICATION_QUEUE = [P.VIEW_APPLICATION_QUEUE, P.VIEW_APPLICATIONS];
 
+const BIOMETRIC_ENROLLMENT = [
+  P.ENROLL_BIOMETRICS,
+  P.VIEW_BIOMETRICS,
+  P.VIEW_SEAFARER_REGISTRY,
+];
+
 /** Route gate: same keys as the route's nav item in nav-config.ts. */
 const guard = (anyOf: string[], element: ReactNode) => (
   <RequirePermission anyOf={anyOf}>{element}</RequirePermission>
@@ -101,7 +107,7 @@ const router = createBrowserRouter([
           { path: 'sea-service-verification', element: guard([P.VERIFY_SEAFARER_RECORDS], <SeaServiceVerificationPage />) },
           { path: 'payment-config', element: guard([P.VIEW_PAYMENTS], <PaymentConfigPage />) },
           { path: 'seafarer-registry', element: guard([P.VIEW_SEAFARER_REGISTRY], <SeafarerRegistryPage />) },
-          { path: 'biometric-enrollment', element: guard([P.ENROLL_BIOMETRICS, P.VIEW_BIOMETRICS], <BiometricEnrollmentPage />) },
+          { path: 'biometric-enrollment', element: guard(BIOMETRIC_ENROLLMENT, <BiometricEnrollmentPage />) },
           // Seafarer registration is not a licence: own queue, own review.
           { path: 'seafarer-registrations', element: guard(APPLICATION_QUEUE, <SeafarerRegistrationQueuePage />) },
           { path: 'seafarer-registrations/:id', element: guard(APPLICATION_QUEUE, <SeafarerRegistrationReviewPage />) },
diff --git a/apps/portal/src/app/i18n/locales/am.ts b/apps/portal/src/app/i18n/locales/am.ts
index 5f921d909..d5c14c190 100644
--- a/apps/portal/src/app/i18n/locales/am.ts
+++ b/apps/portal/src/app/i18n/locales/am.ts
@@ -59,6 +59,7 @@ export const am: Translations = {
     seaRecords: 'የባህር መዝገቦቼ',
     seaService: 'የባህር አገልግሎት',
     medical: 'የሕክምና የምስክር ወረቀት',
+    biometrics: 'ባዮሜትሪክ',
     myApplication: 'ማመልከቻዬ',
     certificates: 'የምስክር ወረቀቶች',
     seamanBook: 'የመርከበኛ መጽሐፍ እና BTC',
diff --git a/apps/portal/src/app/i18n/locales/en.ts b/apps/portal/src/app/i18n/locales/en.ts
index f3e0d4d83..e946849b1 100644
--- a/apps/portal/src/app/i18n/locales/en.ts
+++ b/apps/portal/src/app/i18n/locales/en.ts
@@ -49,6 +49,7 @@ export const en = {
     seaRecords: 'My Sea Records',
     seaService: 'Sea Service',
     medical: 'Medical Certificate',
+    biometrics: 'Biometrics',
     myApplication: 'My Application',
     vesselRegistration: 'Vessel Registration',
     vesselRegistrationDashboard: 'Vessel Registration Dashboard',