# Stage 2 — Users, user types, and schools

Date: 2026-10-23.

Status: implemented locally on 2026-10-23 following the user's instruction to proceed. The specification below records the scope; implementation defaults and verification are listed at the end.

## Goal

Give the super admin a clear place to manage staff accounts, user types, schools, and assignments. Build these screens in the Laravel backend administration area, following the existing Masar style.

## Confirmed decisions

- Main modules: users, user types/roles, and schools.
- The super admin is a separate central role with platform-wide administration.
- The backend login portal is exclusively for active `super_admin` accounts. Directorate heads, supervisors, and counselors cannot log in through this portal, including seeded staff accounts. Enforce this on the server, not through a role selector or hidden UI.
- Business staff types: directorate head, supervisor, and school counselor.
- Students are not users. They must have a separate `students` table, no login account, and no password.
- Public registration stays disabled. Accounts are provisioned through administration; the protected main administrator remains CLI-created.
- Use MySQL and follow [the backend instructions](BACKEND_INSTRUCTIONS.md).
- Support Arabic and English, RTL/LTR, light/dark appearance, and responsive layouts as required by [the project instructions](PROJECT_INSTRUCTIONS.md) and [responsive requirements](RESPONSIVE_REQUIREMENTS.md).

## User types and responsibilities

The following permission boundaries are proposed for this stage. Titles can be refined without changing stored role codes.

| Type                                                    | Stored code        | Responsibility                                                                    |
| ------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------- |
| Super admin — مدير النظام                               | `super_admin`      | Manage all users, schools, directorates, and assignments.                         |
| Directorate head — رئيس قسم الإرشاد التربوي في المديرية | `directorate_head` | Manage schools, supervisors, and counselors within their assigned directorate. |
| Supervisor — المشرف المتابع للمرشدين التربويين          | `supervisor`       | Future follow-up of assigned counselors.                                          |
| Counselor — المرشد التربوي                              | `counselor`        | Future counseling work in assigned schools.                                       |

The original Stage 2 backend management screens are super-admin-only. The subsequent directorate-head frontend workspace is documented below; it grants management only within the head's directorate. Counseling workflows remain later work.

The user-types screen lists these fixed types and their descriptions. The super admin assigns a type to a user; creating arbitrary roles or editing individual permissions is outside this stage. Additional super-admin creation through the web interface is also outside this stage.

## Users module

Provide a paginated user list, search by name/email, filters by type/status/directorate/school, a details page, creation/editing, and activation/deactivation.

### Common user fields

These are the implemented form requirements.

| Field              | Required?           | Rule                                                                                                                    |
| ------------------ | ------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Full name          | Yes                 | Preserve the name as entered; a second translated name is not required.                                                 |
| Email              | Yes                 | Unique login identifier; normalize consistently.                                                                        |
| User type          | Yes                 | Select one permitted fixed staff type.                                                                                  |
| Status             | Yes                 | Active or inactive. Inactive users cannot authenticate or continue protected activity.                                  |
| Initial password   | On creation         | Hash on the server; never display or log the saved password. Editing an account must not require changing its password. |
| Mobile number      | Optional            | Store as text to preserve country prefixes and leading zeros.                                                           |
| Employee number    | Optional            | Unique when supplied; store as text.                                                                                    |
| Preferred language | Yes, default Arabic | `ar` or `en`; users can change their interface preference.                                                              |

### Data required by user type

| Type             | Additional data                                                                                                  |
| ---------------- | ---------------------------------------------------------------------------------------------------------------- |
| Super admin      | No school/directorate restriction. Preserve the existing main-admin CLI and protection rules.                    |
| Directorate head | Assigned directorate.                                                                                            |
| Supervisor       | Assigned directorate; counselors they follow are managed through assignments.                                    |
| Counselor        | Assigned directorate and at least one school before activation. A supervisor assignment can be added separately. |

Recommended defaults: one business type per user and one directorate per business user. Do not expose role/status changes through ordinary profile editing. Preserve historical links when a user changes assignment or becomes inactive.

## Schools module

Provide a paginated school list, search by name/code, filters by directorate/status/category/stage, a details page, creation/editing, and activation/deactivation. Show assigned counselors on school details.

The HTML prototype has school names inside counselor examples and a supervisor school list. It has no school-creation form or validated required-field list. The following fields are the Stage 2 application design, not an extracted prototype form.

| School field           | Required?   | Rule                                                                                          |
| ---------------------- | ----------- | --------------------------------------------------------------------------------------------- |
| Arabic school name     | Yes         | Official display name. Names alone do not identify a school uniquely.                         |
| English school name    | Optional    | Use the Arabic name as fallback until supplied; do not invent an automatic translation.       |
| Internal school code   | Yes         | Unique stable code, separate from the display name; store as text.                            |
| Official ministry code | Optional    | Unique when supplied; preserve leading zeros.                                                 |
| Directorate — المديرية | Yes         | Select an existing directorate.                                                               |
| Gender category        | Yes         | Boys, girls, or mixed; store stable codes and translate labels.                               |
| Educational stage(s)   | Yes         | Select one or more stages. Confirm the stage list before implementation.                      |
| Status                 | Yes         | Active or inactive.                                                                           |
| Area / address         | Optional    | Location details.                                                                             |
| School phone           | Optional    | Text value.                                                                                   |
| School email           | Optional    | Validate when supplied.                                                                       |
| Manager name           | Conditional | Required when a manager phone or email is supplied; up to 255 characters.                     |
| Manager phone          | Optional    | Text, up to 30 characters; preserve country prefixes and leading zeros.                       |
| Manager email          | Optional    | Valid email, up to 255 characters.                                                            |
| Shift — الفترة         | Optional    | Confirm whether morning/evening shifts need separate school identities or a school attribute. |

Do not store counselor names or activity totals as school fields. Counselors come from assignments; future record totals are calculated from records.

## Directorates and assignments

Directorates are a small supporting module to avoid entering their names differently on each school/user. Fields: unique code, Arabic name, optional English name, and active/inactive status.

Implemented relationships, using the defaults recorded below:

- Each school belongs to one directorate.
- Each directorate head and supervisor is assigned to one directorate.
- Each counselor belongs to one directorate and may serve multiple schools within it.
- A school may have multiple counselors. Use explicit school assignments rather than one `school_id` on the user.
- A supervisor may follow multiple counselors. Initially allow one current supervisor per counselor; retain previous assignments with start/end dates.
- Assignment forms must allow only users of the correct type and compatible directorates. Prevent duplicate active assignments and invalid dates.
- Transfers close the previous assignment and create a new one. They must not reassign ownership of historical counseling records implicitly.

## Students

Students must remain separate from `users`; do not create a student role or fake email/password for them. A future student record will link to a school, with academic placement handled separately as needed.

Student management screens, the final student field list, and the `students` table are deferred. School details reserve a Students section for future work. Counseling, family, health, and case-study information must not be added to staff account forms.

## Data and access rules

- Keep existing `super_admin` and `counselor` codes stable. If introducing a roles table, seed the fixed codes and migrate existing users safely; do not break the current login or main-admin database protections.
- Preserve the protected main administrator. Web actions must not delete, demote, deactivate, or remove its protection.
- Prefer deactivation to deletion for users and schools. Do not cascade-delete related students, assignments, or counseling history. Allow changes only through authorized server-side actions.
- Recheck account status and permissions on protected requests; deactivation must affect existing sessions, not only the next login attempt.
- Enforce uniqueness and relationships in MySQL, validate input, and use transactions for related account/assignment changes.
- Keep lists bounded, select needed fields, eager-load displayed relationships, and index measured search/filter/join patterns. Follow existing query-performance requirements.
- Record the actor, action, target, and time for administrative changes without logging passwords or sensitive counseling content.

## Delivery order and acceptance

1. Confirm the proposed fields, directorate scope, and assignment rules below.
2. Add reviewed MySQL migrations and fixed user-type definitions without changing existing main-admin credentials.
3. Build directorate and school management.
4. Build user management and school/supervisor assignments.
5. Verify permissions, inactive accounts, duplicate prevention, assignment consistency, and main-admin protection using the isolated MySQL test database.
6. Check Arabic/English, RTL/LTR, both themes, mobile layouts, and language persistence. Record checks actually run; do not claim production capacity without load testing.

Done means the super admin can manage these records and assignments, while ordinary users cannot reach management actions by changing URLs or request payloads. No public signup, counseling registers, case editing, review workflows, reporting, or operational staff dashboards are included.

## Implementation defaults

- One business type and one directorate per staff user. The central super administrator has no directorate restriction.
- Multiple schools per counselor and multiple counselors per school, within the same directorate.
- One current supervisor per counselor, within the same directorate. School and supervision histories retain start/end timestamps.
- Stages: kindergarten, basic, and secondary, with multiple selections allowed. Shift is an optional school attribute: morning, evening, or full day. Official ministry code is optional and unique when supplied.
- Fixed types are defined in `App/Support/StaffTypes.php` and enforced by validation and a MySQL role constraint. No editable permission builder or separate role records are needed for these four fixed types.
- Student management and the student-table migration are deferred. Students will remain separate from users, with no login account.

## Local implementation and verification

- Delivered Laravel admin navigation, module counts, list/filter/search/detail/create/edit screens, activation/deactivation through edit forms, fixed user-type descriptions, and school/supervisor assignment controls.
- Only active super administrators can access management. Other staff accounts are provisioned for future workflows and cannot sign in to this admin area. Public signup remains unavailable.
- School and supervisor selectors search server-side, return at most 100 results, and restrict choices to the selected directorate. Lists paginate at 25 records. Name/code searches use prefixes; growing lists never load all records into the browser.
- Saves run in transactions with ordered directorate locks and record-version checks. Duplicate current school/supervision assignments are constrained in MySQL. Scope changes close historical assignments rather than overwriting them.
- Schools with current assignments cannot be moved/deactivated until assignments end. Supervisors following counselors cannot change role/directorate or deactivate until those counselors are reassigned. Directorates cannot deactivate while active schools/users remain. Counselor deactivation closes current assignments.
- Administrative audit rows store actor, target, action, timestamp, and changed field names, without passwords or password hashes.
- Backend translation files live in `backend/lang/ar/admin.php` and `backend/lang/en/admin.php`. An encrypted language cookie works before login and survives logout; signed-in language changes also update the user's preference. The language switch retains unsaved form values in memory, including assignment selections, without storing passwords or drafts in browser storage.
- All backend layouts use the root theme configuration; English font tokens are defined there too. The React frontend remains Stage 1 and is not translated by this stage.
- A private SQL backup was created under ignored `backend/storage/app/private/backups/` before migrating the local `masar` database. Main-admin identity, password hash, role, and protection were compared before/after and remained unchanged. Restoration has not been tested.
- Backend tests run against `masar_auth_test`; a target guard runs before any test-table reset. Browser mutations used disposable records on that test database, not application data.
- Browser checks covered login, directorate/school/supervisor/counselor creation, assignments, and language switching with an unsaved counselor form. User edit, school creation, and school list had no page-wide overflow at 320, 375, 640, 768, 1024, and 1440px in both languages and both themes (72 combinations).
- The React production build and its existing 3 theme checks plus 4 component tests passed after the shared theme-token additions.

Initial Stage 2 backend result: **45 tests passed, 247 assertions**, including authentication, CLI protections, management saves, authorization, deactivation, assignment history, stale-save conflicts, lookup limits/scope, stable list query counts, and localization. PHP formatting and Blade compilation passed.

## Administration UX update — 2026-10-23

The user requested a standard administration layout and modal workflows after reviewing the initial UI. The required behavior is now documented in [the project administration UI contract](PROJECT_INSTRUCTIONS.md#administration-ui-and-ux).

- Desktop sidebar, navbar, avatar/account menu, settings menu, and a mobile navigation drawer replace the horizontal admin navigation.
- Settings use immediate Arabic/English toggle buttons and a labeled Light/Dark/Auto icon toggle. Sun, moon, and monitor icons communicate each appearance mode; Auto follows device appearance, and the selected preference survives reloads. Arabic/English switching retains the existing draft-preservation behavior.
- Dashboard overview cards and recent-record tables use actual stored data. User, school, and directorate modules retain paginated/filterable tables and gain modal Create/Edit actions. Fixed user types are shown in a read-only table linked to filtered user lists.
- Modal forms reuse the existing validation, authorization, transactions, and version-conflict handling. They support inline errors, disabled controls during saving, draft-preserving language changes, keyboard focus containment, and confirmation before discarding changes. Header/footer controls remain visible while the editor body scrolls.
- Saves refresh the same list/detail page, preserving its URL, filters, and pagination. Normal module actions use modals; existing standalone form routes remain available as fallbacks.
- User names, assigned schools, directorates, supervisors, and related counts link to their respective detail/list routes. School details show information, manager contacts, counselor assignment history, and the reserved Students section.
- School manager fields: `manager_name` (optional unless manager phone/email is provided), `manager_phone` (optional text, up to 30 characters), and `manager_email` (optional validated email). Names/emails accept up to 255 characters. A manager is not a user and receives no credentials or permissions.
- The user explicitly chose to reserve Students for now. No student table, records, counts, or login accounts were added by this update.
- The nullable manager columns were added through an additive migration after creating a private local SQL backup. Main-administrator identity, credentials, status, and protection were verified unchanged.

UX verification: **53 backend tests passed, 330 assertions**. Coverage includes modal authorization, validation and saves, related links, manager contacts without user accounts, and existing authentication/assignment protections. JavaScript syntax, shared CSS token references, PHP formatting, Blade compilation, the React production build, and its existing 7 checks passed.

Browser verification covered dashboard, user list, and school details across both languages, both themes, and six widths from 320 to 1440px (72 combinations), plus school editor modals across the same settings (24 combinations). Checks included an 812×375 landscape viewport, visible modal save controls, keyboard focus containment/restoration, unsaved-change confirmation, validation errors, draft-preserving language switching, related links, and saving while retaining list filters. No page-wide overflow was found in these checks.

Real-device/on-screen keyboard behavior, 200% zoom, printing, comprehensive accessibility/contrast review, backup restoration, production verification, and capacity/load testing remain outside the completed checks.

## Prototype demo seeders

- `DemoManagementData` snapshots the root HTML's 11 counselor names and their school names; `DemoManagementSeeder` also uses its supervisor, أ. ماجد العبيدات, and the Irbid Qasaba directorate. The source HTML remains unchanged.
- Additional data is explicitly fictional: directorate head, school manager contacts, `.test` emails, internal demo codes, area text, and unspecified school attributes. Gender follows the prototype flags; secondary stages follow explicit school names, otherwise basic is a demo default. Shift defaults to morning. Missing English school names use the existing Arabic fallback.
- Seed 1 directorate, 11 schools, 11 counselors, 1 supervisor, and 1 directorate head. Each counselor has their prototype school and the prototype supervisor. School managers are contact fields only. Students and counseling activity/case records remain deferred.
- Use `php artisan masar:seed-demo` from `backend/` for a read-only preview; `php artisan masar:seed-demo --apply` inserts missing records. See [README commands](../README.md#demo-seed-data). `DatabaseSeeder` calls the demo seeder instead of creating an unrelated factory user.
- Require the existing protected main administrator, local/testing environment, and MySQL. Show the resolved target before applying. Reuse administration save services, audit changes, and wrap the full seed in a transaction. Never replace existing accounts or reset passwords, edits, or assignments. Demo passwords are random hashes; no shared login password is introduced.
- Applied locally to the verified `masar` database after creating a private SQL backup. The main administrator's entire stored row was compared before/after and remained unchanged. Backup restoration remains untested.
- Seeder tests cover source-name parity, preview/no writes, prerequisites, correct relationships, manager/student separation, preserving the main administrator and later edits, repeat runs, collision rollback, and production refusal.
- Verification: 7 seeder tests passed (154 assertions); the full backend suite passed with 60 tests and 484 assertions. Scoped Pint formatting passed. A second local preview reported zero missing records.

## Public landing page and separate staff login — 2026-10-23

- The React `/` route now shows a public landing page explaining the system and its roles. Separate pages list news/articles and show full publication details. Public navigation, Arabic/English, RTL/LTR, Light/Dark/Auto, localized dates, and remembered preferences are implemented. The earlier Stage 1 preview remains at `/dashboard`; operational staff modules remain deferred.
- Added the `publications` table, read-only public list/detail APIs, and `PublicationSeeder`: three bilingual news items and three articles, all marked as samples. Pagination is bounded at six, drafts/future entries are excluded, and bodies are detail-only/plain text. Seed reruns preserve edits; publishing/authoring administration is not part of this update.
- Frontend `/login` is a separate staff portal for active directorate heads, supervisors, and counselors. It uses Laravel's `staff` guard, cookie sessions, CSRF, login throttling, generic failure messages, session regeneration, and role/status rechecks. `/portal` confirms the authenticated name/role and provides logout; operational screens are later work. Super admins remain exclusive to the backend portal. Public signup remains disabled.
- The new publications migration and sample seed were applied to verified local MySQL `masar` after a private backup. All existing user rows, including credentials and main-admin protection, were compared before/after and stayed unchanged. Existing demo staff passwords were not reset; administrators can set them through Users/Edit.
- Verified: **69 backend tests, 595 assertions**, **7 frontend component tests**, **3 theme checks**, production frontend build, scoped Pint, and Blade compilation. Lint reports two Fast Refresh export warnings in the existing theme-provider pattern and the matching locale-provider pattern, without errors.
- Browser checks covered real news/article navigation, full article text, About-anchor navigation, language/theme persistence, failed staff login, successful counselor sign-in, reload persistence, and logout. Authentication mutations used disposable `masar_auth_test` fixtures, then the guarded full suite cleaned them. Landing, login, and article details passed 72 language/theme/viewport combinations from 320 through 1440px without page-wide overflow. Browser console checks returned no warnings/errors.
- Set frontend `VITE_BACKEND_URL` to the Laravel base URL and backend `CORS_ALLOWED_ORIGINS` to the exact frontend origin. API and staff-auth requests support credentialed cross-origin sessions with CSRF; configure HTTPS/SameSite cookies as described in deployment instructions. The frontend still requires SPA fallback. Frontend and backend display preferences remain independent. Real devices/keyboards, 200% zoom, full accessibility/contrast auditing, backup restoration, production deployment, and load testing remain unverified.

Future changes to these defaults must preserve existing identities, credentials, canonical role codes, and assignment history.

Public motion update: added brief hero settling, one-time section reveals through one IntersectionObserver, smooth anchors, and small hover/press responses. Shared motion settings live in the root theme configuration; no animation dependency or continuous effect was added. Hero text stays visible immediately. Reduced-motion, keyboard-focus, missing-observer, and print paths preserve readable content. Production build and 10 frontend component tests plus 3 theme checks passed; browser checks confirmed desktop scroll reveals, keyboard access, and 320px anchor navigation without horizontal overflow. Real-device frame-rate and print-output checks were not performed.

## Directorate-head management workspace — 2026-10-24

- Delivered `/portal/directorate` with a sidebar, navbar, avatar/account menu, actual scoped counts, and Arabic/English display controls. `/portal` redirects heads here; other staff retain their placeholder. The head must be active and assigned to an active directorate.
- Schools: paginated list, prefix search, status/category/stage filters, details, Create/Edit dialogs, activation/deactivation, and school manager contacts without manager accounts. School details link assigned counselors and retain the reserved Students section.
- Users: manage supervisors/counselors within the same directorate, with lists, search/status/type filters, details, Create/Edit dialogs, optional password changes, activation/deactivation, school assignments, and supervisor assignments. Related school/supervisor names open scoped details; supervisor details list assigned counselors. No deletion, head/super-admin management, directorate transfers, student records, counseling registers, or reports are included.
- APIs under `/api/v1/directorate` use web sessions/CSRF, staff/head middleware, a head-access policy, explicit resources, inherited server-side directorate IDs, scoped lookup/related filters, 25-row pagination, and 100-result lookups. Save services recheck head status/scope inside the transaction and retain existing stale-version, duplicate, audit, and assignment-history rules. Cross-scope records return 404; supplied directorates and privileged roles are rejected. Frontend caches include the staff ID/directorate and are cleared on logout.
- Modal saves preserve the list URL and filters. Field errors retain drafts. Language changes preserve unsaved values. Native dialogs support focus containment, discard confirmation, focus restoration, background scroll locking, and visible footer actions. Shared theme/display components are reused; no dependencies or schema migrations were added.
- Browser mutations used only disposable `masar_auth_test` records. Verified school creation/editing, duplicate validation, supervisor/counselor creation and assignments, linked school/supervisor details, filtered saves, language-preserved drafts, discard/keep-editing, deactivation updating current assignments, keyboard wrapping/restoration, mirrored mobile drawers, and sign-out. The guarded full test run cleaned QA fixtures afterward. Existing application accounts/passwords were not reset.
- Verification: **78 backend tests passed, 684 assertions**; **12 frontend component tests and 3 theme checks passed**. Production frontend build, frontend formatting, and scoped Pint passed. Lint retains only the two existing Fast Refresh provider export warnings. Page layouts passed 72 language/theme/viewport combinations and school/counselor dialogs passed 48, from 320–1440px, with no page-wide overflow and visible modal footers. One 812×375 landscape editor check passed; the browser console reported no warnings/errors.
- Real-device/on-screen keyboard checks, 200% zoom, full accessibility/contrast auditing, print output, production deployment, and capacity/load tests remain outside this local verification.


### Separate staff pages — 2026-10-24

- The directorate-head workspace now has separate `/portal/directorate/counselors` and `/portal/directorate/supervisors` pages and sidebar links, with matching details routes. Overview cards link to these pages.
- Both pages reuse the existing scoped users API and shared table/editor components. Each page fixes its role filter and Create/Edit user type; search, status filters, pagination, dialogs, assignments, and Arabic/English support remain available.
- School/counselor/supervisor relationships link to the appropriate details page. Old users list URLs remain supported; old user details URLs redirect to the matching role page. No database changes are needed.


### Frontend selection and dialog UX — 2026-10-24

- Replaced always-expanded assignment lists in the directorate workspace with compact search pickers: selected count, removable chips, checkbox/radio rows, Clear selections, and Done. Selection survives filtering and closing. Options are fetched only when open; existing scoped APIs and limits remain unchanged. Small fixed school-stage choices use checkbox pills.
- Long Create/Edit dialogs retain their visible header/actions while the body scrolls, with themed thin scrollbars, stable scrollbar space, and a hint when fields remain below. Results and selected chips have bounded heights. Shared dimensions remain in the root theme configuration; no package or schema changes.
- Verification: 15 frontend tests and 3 theme checks passed; production build and formatting passed. Lint retains the two existing Fast Refresh provider warnings. Browser checks covered Arabic/dark desktop, 375×667 and 320×568, plus English/light 812×375. Form bodies had no horizontal overflow and Save/Cancel stayed visible. Checked multiple selections, retained chips after language changes, Done, picker Escape, and discard; no records were saved. No browser warning/error logs were reported. Real-device keyboards and a full accessibility audit were not performed.


### Supervisor read-only workspace — 2026-10-24

- Delivered `/portal/supervisor` with automatic staff-login routing, scoped counts, sidebar/navbar/avatar, Schools/Counselors tabs, filters, pagination, and linked read-only details. School details offer Information, Counselors, and reserved Students tabs with keyboard navigation.
- Added five GET endpoints under `/api/v1/supervisor`. An active supervisor in an active directorate sees only currently supervised counselors and their currently assigned schools in the same directorate. Shared-school counselors, unrelated schools, ended assignments, and cross-directorate relationships are hidden. School counselor counts include only visible counselors. School visibility derives from counselor assignments; no separate supervisor-school mapping was introduced.
- No create/edit/delete or evaluation workflows were added. Direct management/admin access remains denied. Student records remain deferred. Existing head management, admin login, credentials, and application data were preserved; no migrations or dependencies were added. Shared UI components accept an explicit read-only mode and separate API/cache scope.
- Verification: full backend suite passed **83 tests / 749 assertions**, including five supervisor access/assignment/read-only/pagination/query-count tests. Frontend suite passed **17 tests plus 3 theme checks**. Browser QA used only disposable `masar_auth_test` fixtures and covered supervisor login/redirect, scoped overview/school/counselor details, a hidden counselor at a visible shared school, 404 for direct hidden school/counselor URLs, Students reservation, Arabic/light at 320px, English/dark at 375px, and desktop 1440px. Mobile checks had no page-wide horizontal overflow. Test servers were stopped and QA fixtures removed through the guarded backend test workflow. Real-device keyboards, full accessibility audit, load testing, and production verification remain pending.


### Counselor self-service workspace — 2026-10-24

- Added a separate `/portal/counselor` workspace with automatic login routing, shared sidebar/navbar/avatar and display settings, My account and information (`/profile`), and My supervisor (`/supervisor`). Pages are read-only and show the counselor's own account/directorate and their current supervisor's contact details. Missing or invalid current assignments produce a translated empty state.
- Added GET `/api/v1/counselor/profile`, counselor middleware/policy, and an explicit response resource. Identity comes only from the staff session. Supplied identity/scope IDs are rejected; other-user routes, writes, supervisor/directorate management, and backend administration remain inaccessible. Ended, inactive, cross-directorate, or wrong-role supervisors are hidden. No account passwords, database schema, dependencies, student records, or counseling/evaluation workflows were changed.
- Verification: **88 backend tests / 818 assertions** passed, including four counselor access/profile tests and the earlier supervisor school-preview regression. **20 frontend tests plus 3 theme checks** passed. Production build, formatting, and Pint passed; lint retains two existing provider Fast Refresh warnings. Browser checks used disposable `masar_auth_test` fixtures and covered login redirect, own profile/supervisor pages, Arabic/light at 320px, English/dark at 375px, desktop layout, mobile drawer navigation, redirect from a wrong-role workspace, and sign-out. No page-wide overflow was observed. QA servers were stopped and fixtures cleared through guarded tests; application credentials and records were preserved. Real-device keyboards, full accessibility auditing, load tests, and production verification remain pending.


### Counselor students and Excel import — 2026-10-24

- Added a separate `students` table/model, with no user account or login. Required data: student number, full name, grade, section. Optional: birth date, gender, guardian name and phone (guardian name required when phone is supplied). Student numbers and phones are text; numbers are unique per school. Added foreign keys, current-school query indexes, a factory, explicit resources, a policy, and transactional creation with audit counts.
- The counselor Students page selects an active assigned school and provides a paginated table, prefix search, grade/section filters, linked student details, an Add Student modal, Download Excel template, and Import Excel modal. Account/supervisor pages stay read-only. Student editing/deletion, transfers, student login, evaluations and other roles' student tabs remain outside this increment.
- Installed the user-approved `openspout/openspout` **4.32.0** for PHP 8.3. Templates have a frozen bilingual header, 1,000 empty text-formatted input rows, and an Instructions sheet. Arabic/English/canonical headers and Excel date cells are accepted. The first sheet is imported. Preview displays the first 10 rows and total count; an explicit Import action re-submits/revalidates the selected file. No uploaded student files are permanently stored.
- Imports allow **1,000 students / 2 MB**, with bounded ZIP entries/expanded size, formula rejection, row-numbered errors, and duplicate detection. No partial import or overwrite occurs on an invalid row or duplicate. Writes recheck the counselor's active role, directorate, school and current assignment under transaction locks, then insert bounded chunks. Student APIs and template access cannot expose another school by changing an ID.
- Applied only the additive student migration to verified local MySQL database `masar`; its new student table is empty and existing application data/passwords were preserved. QA used disposable `masar_auth_test` fixtures; test servers stopped, fixtures reset through guarded tests, and temporary upload workbooks removed.
- Verification: **95 backend tests / 900 assertions**, **22 frontend tests plus 3 theme checks**, production frontend build, formatting, and Pint passed. Lint retains only the two existing provider Fast Refresh warnings. Backend tests cover real XLSX preview/import, Arabic, leading zeros, dates, missing/invalid headings, formulas, duplicate/invalid rows, size/ZIP/row limits, assignment removal, denied access, and bounded list queries. Browser checks covered assigned-school selection, manual creation, linked details, duplicate rejection with retained drafts, keep/discard/focus restoration, actual template download and workbook read-back, Arabic/light at 320px, and English/dark at 375px without page-wide overflow and with visible modal actions.
- Automated browser file selection was blocked by the ChatGPT Chrome extension's disabled “Allow access to file URLs” permission. Therefore browser-driven upload/preview/confirmation remains unverified; actual XLSX imports passed through API tests and preview/confirmation passed component tests. Native Excel visual review, real-device keyboards, full accessibility review, concurrent load tests, and production verification remain pending.


### Fictional student seeding — 2026-10-24

- Added `DemoStudentSeeder` and `masar:seed-demo-students` (preview by default, explicit `--apply` to write). It is an opt-in seeder and does not change the standard database seeder.
- Targets only known prototype demo schools in the active `DEMO-IRBID` directorate. Inactive schools or schools without a current active counselor are skipped and counted. It creates ten fictional students per eligible school, with stable `DEMO-cN-NNN` identifiers, demo-labeled Arabic names and guardian details, non-dialable phone placeholders, birth dates, gender matching the school category, grades and sections. Writes use existing scoped transactional student creation and audits.
- Preserves existing records and manual edits, creates no user accounts, and refuses production/non-MySQL environments. Four isolated MySQL tests cover preview safety, repeat execution/edit preservation, valid sample data, non-demo school exclusion, skipped schools, and production refusal; **4 tests / 362 assertions passed**. Pint passed.
- Verified local target `mysql / 127.0.0.1 / masar`, previewed 110 missing students, applied the seeder, and applied it again. Final read-only verification found **110 students / 11 schools / 10 per school**, zero remaining sample numbers to insert, and ten students visible to sample counselor `c1@demo.masar.test`. Existing account passwords and school/supervisor assignments were preserved.


### Counselor interviews and consultations — 2026-10-24

- Implemented the first counseling form at `/portal/counselor/interviews`, linked from the counselor sidebar. Assigned-school selection, paginated student search, automatic grade/section display, all prototype interview fields, Create/Edit dialogs, related student/details links, confirmed soft deletion, and student/month/type/follow-up table filters are included.
- Records are private to their creator and require a current assignment to the active same-directorate school. Server writes recheck actor/school/assignment under locks. A student from another school cannot be selected by forged IDs. Other counselors sharing a school cannot see the notes. Supervisor review, printing, the remaining six registers, and case-study editing remain deferred; there is no fake pending/approved state.
- Dates/student are required, selects have valid defaults, and each optional narrative is bounded to 5,000 characters. Dates use the MySQL DATE range. Durable saves include a unique request UUID/payload hash for retry protection and version checks for edits/deletes. Audits contain action/field names, not counseling values. Student records remain intact on interview deletion.
- Fixed the workspace shell unmounting its active editor while localized overview/profile data reloads. Previous shell data is used only within the same role/user/directorate scope. The dialog retains the version its draft originally opened from, including through background detail refetches.
- Verified the local MySQL `masar` target, saved an ignored database backup, and applied only the additive interviews migration. Browser QA used one clearly labeled temporary interview on a fictional seeded student: create/save, linked details, follow-up edit/save, language changes retaining student/notes, modal keep/discard protection, English/light at 320px, and Arabic/dark at 375px. No page-wide overflow was observed; fixed dialog actions remained visible. The temporary interview was soft-deleted through the scoped service after QA; all 110 existing students remain.
- Verification: full backend suite **105 tests / 1,350 assertions** passed, including six interview tests covering date boundaries, scope, validation, retries, conflicts, deletion and bounded queries. Frontend **26 tests plus 3 theme checks** passed, including create retry/validation, edit conflicts, explicit delete confirmation, and shell draft retention during language reload. Production build and Pint passed. Lint retains only the two existing provider Fast Refresh warnings. Load tests, a full accessibility audit, real-device input, and production deployment checks remain pending.


### Supervisor interview review — 2026-10-24

- Added the supervisor **Counselor forms / نماذج المرشدين** sidebar item and workspace tab at `/portal/supervisor/interviews`. It lists the currently implemented interview form with student prefix search, month/status filters, pagination, and scoped counselor/school/detail hyperlinks. Supervisor details show answers read-only and open a separate review modal.
- Review decisions are **Reviewed / تم الاطلاع** and **Approved / معتمد**, with an optional note up to 5,000 characters. New records are Pending review. Counselors see status in the table and the latest note/reviewer/date on details and Edit. Viewing alone never changes status. No return/reject status, bulk approval, inbox, notification, other form type, or supervisor student-management permission is added.
- SQL scope requires an active currently supervised counselor, their current assignment to the record's active same-directorate school, valid student-school membership and a non-deleted interview. Shared schools cannot expose an unrelated counselor's notes. Writes recheck role, active directorate, scope and assignments under locks. Supervisors can save only review fields, not edit answers or delete forms.
- Shared version checks prevent stale content/review saves. Actual answer changes increment a separate content version and reset the review to Pending; saving unchanged answers preserves approval. Earlier decisions/notes are retained in dedicated history rows tied to content version. The UI displays the latest review, clearly labeled when it predates the current answers. General audits omit note values. Eloquent stamps review creation in application UTC; responses use ISO timestamps for localized display.
- Saved an ignored backup of verified local MySQL `masar`, then applied the additive review migration. Browser QA used one clearly labeled temporary interview on a fictional demo student and a separate 127.0.0.1 supervisor session, preserving the user's localhost counselor session. Verified Reviewed + note, Approved + updated note, counselor feedback visibility, and Pending reset/previous-note warning after a counselor edit. Arabic/light at 375px and English/dark at 320px had no page-wide overflow; note/status survived language switching and modal actions remained visible. Restored temporary preferences/viewport and closed QA tabs. The temporary interview was soft-deleted through the scoped service; its two test review decisions remain in history, and all 110 students were preserved.
- Verification: **112 backend tests / 1,424 assertions**, including seven supervisor-review tests; **30 frontend tests plus 3 theme checks**; production build, formatting and Pint passed. Coverage includes scope/role/status boundaries, same-school leaks, stale/repeated reviews, content reset/no-op behavior, note validation/tampering, eager-loading query bounds, review draft retention, and UTC timestamps. Lint retains the same two existing provider Fast Refresh warnings. Full accessibility auditing, real-device input, load/capacity testing and production checks remain pending.


### Fictional interview seeding — 2026-10-24

- Added `DemoInterviewSeeder` and opt-in `masar:seed-demo-interviews` with read-only preview and explicit `--apply`. `DatabaseSeeder` remains unchanged. Six example slots per canonical demo school/counselor use existing sample students, labeled Arabic narratives, varied type/referral/follow-up selections, September/October dates, and two examples per Pending/Reviewed/Approved status. Reviewed/Approved slots include a fictional note from the currently assigned active demo supervisor.
- Enforces local/testing MySQL, known demo codes/emails/student numbers, active schools/counselors and current assignments; skips missing student/review prerequisites. Uses the normal scoped transactional services and stable UUIDs. Reruns skip existing and soft-deleted slots, preserving manual edits, approvals, notes and deletion choices without changing users/passwords/students/assignments.
- Five isolated MySQL tests / **391 assertions** passed for read-only preview, prerequisite failure, data/status/review validity, counselor/supervisor API visibility, rerun preservation, missing/inactive/ended assignments, non-demo exclusion and production refusal. Pint and whitespace checks passed. No frontend code or schema changed in this increment.
- Verified local `mysql / 127.0.0.1 / masar`, saved an ignored backup, previewed 66 records, applied and applied again. Final read-only verification: **66 active demo interviews / 11 schools / 44 sample reviews**, **22 Pending + 22 Reviewed + 22 Approved**, sample counselor visible count **6**, supervisor visible count **66**, zero remaining missing slots, and **110 students preserved**.


### Parent meetings register — 2026-10-24

- Implemented **مقابلات أولياء الأمور / Parent meetings** at `/portal/counselor/parent-meetings`, with its own typed records/review tables and eight scoped session/CSRF API routes. Uses assigned-school/student selection, automatic class display, required date/student, In person/Phone call/School invitation types, follow-up and optional reason/action (5,000 characters each). No guardian user account or interview-only fields are created.
- Includes paginated search/filter tables, Create/Edit/confirmed soft-delete dialogs, related detail links, Arabic/English and RTL/LTR, retained drafts on validation/locale/conflict, duplicate-create UUID protection and stale-edit versions. Reuses workspace dialogs, scrolling, school/student APIs, theme styles and the shared review presentation.
- Supervisors open the Parent meetings tab to read authorized counselors' forms and save Reviewed/Approved notes, without editing answers or gaining student-management access. Actual answer changes reset review to Pending, preserve earlier reviews and mark old-version feedback. Role/directorate/current-supervision/current-school-assignment checks apply to every record and review write, including same-school ownership boundaries.
- Verified and backed up local MySQL `masar`, then applied the additive parent meetings migration. Browser QA created a clearly labeled temporary phone meeting, verified saved table/details, student/notes retained during Arabic→English switching, narrow 320px English/light form with visible footer and no page-wide overflow, supervisor approval/note, and counselor feedback visibility. Temporary record soft-deleted via the scoped service after QA; existing students and interview demo data were preserved. No parent-meeting demo seeder was added.
- Verification: **130 backend tests / 1,988 assertions** passed, including 13 parent meeting/review tests for access, tampering, replay, stale edits/reviews, review reset/no-op, dates, soft deletion, review UTC and bounded eager-loaded query counts. **37 frontend tests plus 3 theme checks** passed, with parent dialog/review tests covering validation, draft preservation, review decisions and conflicts. Build and Pint passed; lint retains the two existing provider Fast Refresh warnings. Full accessibility auditing, device keyboards, load testing and production verification remain pending.

### Vocational guidance register — 2026-10-25

- Implemented سجل التوجيه المهني for counselors and supervisors at their respective `/portal/{role}/vocational-guidance` routes. Uses the HTML prototype's topic, class, date, session/beneficiary counts, activity narrative and evaluation. This is a school/class activity and works without student records. Topic/date are required; class fields and bounded whole-number counts/narratives are optional, preserving null versus zero.
- Added separate typed record/review tables, eight scoped session/CSRF routes, owner/current-assignment policies and transactional save/review services. Create retries use stable UUIDs; stale edits/reviews/deletes return conflicts. Actual answer changes reset review to Pending while preserving prior review history. Shared schools cannot expose another counselor's activities. Supervisor decisions remain Reviewed/Approved with optional notes and read-only answers.
- Added bilingual responsive table/detail/dialog screens, topic/month/status filters, related school/counselor links and navigation in both workspaces. Reuses the existing workspace shell, dialogs, draft protection, theme styles and review panel. No dependency, student model change or demo seeder was added.
- Verified local MySQL `127.0.0.1 / masar` and saved an ignored SQL backup before applying only `2026_10_25_064232_create_vocational_guidance_records_table`. Existing seeded users, students and other forms remain intact. No vocational-guidance records were inserted into the application database during automated tests.
- Verification: **152 backend tests / 2,262 assertions**, including 12 vocational save/review tests; **46 frontend tests plus 3 theme checks**, including seven vocational draft/retry/conflict/review tests. Production build, Pint and frontend formatting passed. Lint retains the two existing provider Fast Refresh warnings. Live browser inspection could not proceed because the computer-use tool could not establish the current browser URL for its policy check; visual/mobile/theme checks for this increment remain pending. Production and load/capacity verification remain pending.

### Bulletins register — 2026-10-25

- Implemented سجل النشرات at `/portal/counselor/bulletins` and `/portal/supervisor/bulletins`, following the prototype's name/date/target audience/copies/objectives fields. Names/dates/audiences are required; the UI defaults to All students. Optional copies accept whole numbers 0–100,000, preserving null versus zero; objectives are bounded to 5,000 characters. All five audience labels are available in Arabic and English.
- Added separate typed bulletin/review tables, eight scoped session/CSRF routes, transactional save/review services, owner/current-school/exact-supervisor policies, stable create UUIDs, stale-write protection, soft deletion and review history. Answer edits reset review to Pending; unchanged answers retain approval. Private bulletin records do not create public news/articles or individual student links.
- Both workspaces include tables, name/month/audience/status filters, record details and related school/counselor links. Shared dialogs preserve drafts on language changes, validation failures and conflicts. Counselors have create/edit/confirmed deletion; supervisors read answers and save notes with Reviewed/Approved. Existing theme, dialog scrolling and mobile layout rules are reused. No dependency or bulletin demo seeder was added.
- Confirmed local MySQL `127.0.0.1 / masar`, saved an ignored SQL backup and applied only `2026_10_25_065723_create_counselor_bulletins_table`. Existing users, credentials, students, sample publications and other forms are preserved. Automated tests use the separate guarded MySQL test database; no bulletin sample records were inserted into the application database.
- Verification: **166 backend tests / 2,492 assertions**, including 14 bulletin/review tests; **54 frontend tests plus 3 theme checks**, including eight bulletin dialog/review tests. Checks cover all audiences, null/zero copies, field limits, private/public separation, scope, retry/conflict/deletion behavior, review history/reset/no-op, UTC dates, bounded queries and bilingual draft preservation. Production build, Pint and formatting passed. Lint retains the two existing provider Fast Refresh warnings. Live browser/mobile visual checks remain pending due to the previously encountered browser-tool limitation; no visual pass is claimed. Production deployment, device input and load/capacity checks remain pending.

### Studies register — 2026-10-25

- Implemented سجل الدراسات at `/portal/counselor/studies` and `/portal/supervisor/studies`, following the prototype's title/date/sample/purpose/results fields. Title/date are required; optional sample is bounded to 255 characters and each narrative to 5,000. Empty/omitted optional text stores null. School-level records do not require students or publish public articles.
- Added separate typed study/review tables and eight scoped session/CSRF routes with current-school/exact-supervisor access policies and transactional save/review services. Reuses stable create UUIDs, optimistic versions, soft deletion, privacy-preserving audits and versioned supervisor history. Actual answer edits reset Pending; no-op saves preserve approval. Shared schools cannot expose another counselor's records.
- Added bilingual table/detail/dialog screens, title/month/status filters and related school/counselor links. Counselor CRUD and supervisor Reviewed/Approved notes retain drafts across language changes, validation failures and conflicts. Reuses the existing shell, modal scrolling, theme and responsive rules. No dependency or study demo seeder was added.
- Confirmed local MySQL `127.0.0.1 / masar`, saved an ignored SQL backup and applied only `2026_10_25_071703_create_counselor_studies_table`. Read-only comparison verified every pre-existing application table row was unchanged. New study tables are empty; automated tests run on the separate guarded MySQL test database.
- Verification: **180 backend tests / 2,680 assertions**, including 14 study/save/review tests; **62 frontend tests plus 3 theme checks**, including eight study draft/retry/conflict/optional-field/review tests. Production build, Pint and formatting passed. Lint retains the two existing provider Fast Refresh warnings. Live browser/mobile visual checks remain pending due to the previously encountered browser-tool limitation; no visual pass is claimed. Production, real-device input and load/capacity checks remain pending.

### Counseling committee register — 2026-10-25

- Implemented ملف اللجنة الإرشادية for counselor and supervisor workspaces at their `/portal/{role}/committee-activities` routes. Required activity/date and valid counselor evaluation (Excellent/Very good/Good/Acceptable), optional committee/external/teacher counts and objectives follow the HTML prototype. Counts preserve blank/null versus zero and accept whole numbers 0–100,000. Evaluation remains separate from supervisor review; no participant overlap rules or teacher accounts are invented.
- Added separate typed record/review tables, eight scoped session/CSRF routes, owner/current-school/exact-supervisor policies and transactional save/review services. Shared UUID retry protection, optimistic versions, soft deletion, private audits and versioned review history retain the established behavior. Answer edits reset Pending; unchanged answers preserve approval. Shared schools cannot expose another counselor's records.
- Added bilingual table/detail/dialog screens, activity/month/evaluation/status filters, related links and workspace navigation. Shared modal scrolling, theme and responsive rules are reused, with draft retention through locale changes, failed validation and conflicts. No dependency or committee demo seeder was added.
- Verified local MySQL `127.0.0.1 / masar`, saved an ignored SQL backup and applied only `2026_10_25_073811_create_committee_activities_table`. Read-only comparison verified all pre-existing application rows were unchanged. New committee tables are empty; tests use the separate guarded MySQL database.
- Verification: **194 backend tests / 2,905 assertions**, including 14 committee/review tests; **70 frontend tests plus 3 theme checks**, including eight committee draft/retry/count/evaluation/conflict/review tests. Production build and Pint passed. Lint retains the same two provider Fast Refresh warnings. Live browser/mobile visual checks remain pending because the browser automation URL-verification limitation has not been resolved; no visual pass is claimed. Production, device input and load/capacity checks remain pending.

### Home visits register — 2026-10-25

- Implemented ملف الزيارات المنزلية at `/portal/counselor/home-visits` and `/portal/supervisor/home-visits`, completing the seventh ordinary register. Uses assigned-school student selection, current grade/section display, date, Preventive/Remedial/Absence follow-up types, follow-up status and one combined visit/action narrative (optional, max 5,000). Case-study editing remains deferred.
- Added separate typed record/review tables, eight scoped session/CSRF routes, owner/current-school/exact-supervisor policies and transactional save/review services. Current student-school membership is required. Parent-meeting reason/action and unrelated interview fields are rejected. Shared UUID retry protection, versions, soft deletion, private audits and content-version review history preserve established behavior. Answer changes reset Pending; unchanged answers retain approval.
- Added bilingual tables, details and dialogs, student/month/type/follow-up/status filters, scoped hyperlinks and workspace navigation. Counselors manage their own records; supervisors read answers and save notes/Reviewed/Approved without student-detail access. Shared dialogs retain drafts through language changes, validation and conflicts. Existing theme/responsive/scrolling rules are reused. No dependency or home-visit demo seeder was added.
- Confirmed local MySQL `127.0.0.1 / masar`, saved an ignored SQL backup and applied only `2026_10_25_074331_create_home_visits_table`. Read-only verification confirmed every pre-existing application row was unchanged. New home-visit tables are empty; automated tests use the separate guarded MySQL database.
- Verification: **208 backend tests / 3,114 assertions**, including 14 home-visit/review tests; **77 frontend tests plus 3 theme checks**, including seven home-visit draft/retry/conflict/delete/review tests. Checks cover all visit types, optional notes, cross-school students, scope, version history/reset/no-op, bounded queries, UTC review dates and bilingual draft retention. Production build and Pint passed. Lint retains the same two provider Fast Refresh warnings. Live browser/mobile visual checks remain pending due to the unresolved browser automation URL-verification limitation; no visual pass is claimed. Production, device input and load/capacity checks remain pending.

### Twelve-section case-study form — 2026-10-25

- Implemented دراسة الحالة at `/portal/counselor/case-studies` and `/portal/supervisor/case-studies`, completing the eight-form inventory. The editor covers general/family/academic/adjustment/health/interests/economic/registration/problem/plan/sessions/closing sections. Goals and sessions have ordered add/remove rows. Name/class come from the current student record; student identity is immutable after creation. Minimal required student/date/canonical defaults allow gradual completion of optional sections.
- Added typed case columns, ordered relational goal/session tables and separate review history, with eight scoped session/CSRF routes. Existing creator/current active school/exact current supervisor policies, transaction locks, UUID request hashes and optimistic versions apply. Case and child changes commit/roll back together. Short fields are bounded to 255, narratives to 5,000, goals to 50 and sessions to 100. Date ordering, family size and working hours are validated. Lists select summary columns and omit private narratives/child collections. Student details remain denied to supervisors outside the case's deliberate selected fields.
- Counselor CRUD uses paginated student/month/type/progress/status tables and a bilingual sectioned modal with shared scrolling/fixed actions. First creation is explicit; reopened cases autosave after 900 ms, serialize requests and queue edits made in flight. Lost creation responses retry the original UUID/payload before saving newer drafts. Saved is displayed only after acknowledgement. Failures/conflicts stop automatic retries and retain drafts, and opening fetches a fresh version before pinning the editor baseline. Language changes/refetches preserve ongoing edits. Sensitive unsaved drafts remain in memory and are guarded on close/refresh; they are not stored in browser local storage.
- Case progress (New/In follow-up/Closed) is derived from sessions/closing date, separate from Pending/Reviewed/Approved review. Supervisors read all 12 sections and save notes/decisions without editing answers/children. Scalar/child/order edits reset Pending and preserve prior review versions; no-op saves preserve approval. Soft deletion retains children/reviews and the student. There is no formal submit/return inbox, attachment upload, digital signature, print/export or case demo seeder.
- Confirmed local MySQL `127.0.0.1 / masar`, saved an ignored SQL backup and applied only `2026_10_25_074748_create_case_studies_table`. Read-only comparison confirmed every pre-existing application row was unchanged. New case tables are empty; automated tests use the guarded isolated MySQL test database.
- Backend verification: **224 tests / 3,341 assertions**, including 16 case/save/review tests covering all scalar fields, child order/transactions/retention, partial drafts, status derivation, immutable/cross-school students, validation, privacy, versions, supervisor scope and bounded list queries. Frontend verification includes ten case editor/review tests for serialized autosave, in-flight edits, lost creation acknowledgements, fresh editor baselines, optional sections, bilingual child drafts, conflicts, unsaved-close protection, explicit deletion and supervisor decisions. **87 frontend tests plus 3 theme checks**, production build, frontend formatting and Pint passed. Lint retains only the two existing provider Fast Refresh warnings. Live browser/mobile visual acceptance remains pending because no usable browser automation surface is available for this increment; automated checks do not constitute a visual or production pass. Device input and load/capacity verification remain pending.

### Demo data for all newer forms — 2026-10-25

- Added opt-in `masar:seed-demo-forms` (preview, explicit `--apply`, optional `--form`) for parent meetings, vocational guidance, bulletins, studies, committee activities, home visits and case studies. Requires existing canonical demo management/students/current assignments and local/testing MySQL; staging/production are refused. Existing interview command and `DatabaseSeeder` remain unchanged. No dependencies or migrations added.
- Backed up local `127.0.0.1 / masar` under ignored `backups/masar-before-demo-forms-20261025/` before applying. Inserted **462 records**, six per school per form (**66 per form**), **308 reviews**, **132 case goals** and **66 case sessions**. Each form has 22 Pending, 22 Reviewed and 22 Approved examples. Case progress has 22 New, 22 In follow-up and 22 Closed examples.
- Full pre-existing row comparison confirmed accounts/passwords, students, assignments, publications, interviews/reviews and previous audits were preserved. An additional complete seeder rerun changed no database rows. Stable UUID slots also preserve edited and soft-deleted samples; missing prerequisites are skipped/countable. All data is fictional and written through existing typed save/review services.
- Validation: **231 backend tests / 5,313 assertions passed**, including seven new seeder tests with 1,972 assertions. These cover request-rule validity for every variant, read-only preview, rollback, scopes, prerequisites, environment restrictions, API visibility and exact preservation of edits/reviews/deletions/case children/passwords. Pint passed. Live authenticated HTTP checks through the local frontend proxy confirmed six records per form for c1 and 66 per form for the demo supervisor; both sessions were logged out. No browser visual, staging or production validation is claimed.


### Directorate-head form viewing — 2026-10-25

- Added read-only lists/details for all eight forms under `/portal/directorate/{form}` and `/api/v1/directorate/{form}`. Shared tables retain filters/pagination/statuses and head-workspace school/counselor links. Details show answers and the latest supervisor note, reviewer/date and changed-content indication; case details include all sections/goals/sessions. Arabic/English copy identifies read-only access, with no edit/review dialogs or mutation actions.
- `DirectorateFormPolicy` constrains school and counselor to the active head's own active directorate in SQL. Historic forms remain visible after assignments end, while inaccessible/deleted records return 404. All review writes retain the original supervisor policy/service. No form write routes are registered for heads; existing school/staff management and student permissions remain unchanged. No migration, dependency, reseeding or local data reset was needed.
- Verification: **233 backend tests / 5,524 assertions passed**, including two new tests with 211 assertions covering all eight forms, statuses/notes, case children/list privacy, read-only routes, cross-directorate schools/counselors, invalid filters, other roles, inactive actors/directorates, soft deletion and ended assignments. **89 frontend tests plus 3 theme checks passed**; an additional list/filter test was then added and all **7 focused bulletin review/view tests** passed. Head details are checked in Arabic/English for notes and absence of write actions. Production frontend build, Pint and formatting passed. Lint has only the two pre-existing provider Fast Refresh warnings.
- Live authenticated local HTTP checks through the frontend proxy confirmed all eight approved lists (22 demo records each), record details and supervisor notes using the head account; the session was logged out. Browser visual/mobile and staging/production acceptance remain pending.


### Multiple records per student and counselor — 2026-10-25

- Confirmed existing typed tables allow many records per student/counselor/type/date; UUID uniqueness protects request retries only. Added validated SQL `student_id` filters to the four student-linked counselor list endpoints without widening ownership or current-school authorization. No schema, dependency, seeding or local data changes required.
- Student details now show type-specific history for interviews, parent meetings, home visits and case studies, with review-status filter, bounded table/pagination and individual detail links. Create reuses each existing dialog, fixes the current student and starts a fresh record/UUID on each opening. All eight registers support multiple entries; the other four remain school/class-level forms. Existing per-record reviews, revisions, draft/conflict handling and case autosave remain intact.
- Verification: **234 backend tests / 5,636 assertions passed**, including a new 112-assertion test creating two same-type/same-date records per register, same-student records across types, retry replay, exact student filtering, invalid input and denied cross-school/counselor access. **95 frontend tests plus 3 theme checks passed**, including five new history/type-switch/preselected-student tests covering all four dialogs. Production build, Pint, formatting and diff checks passed. Lint retains only the two existing provider Fast Refresh warnings. Browser visual/mobile and staging/production checks remain pending.


### Private supporting attachments — 2026-10-25

- Added optional files for studies, bulletins, vocational guidance and committee activities. These are a new extension: the sample HTML has no upload field. Student-linked interviews, parent meetings, home visits and case studies remain unchanged. Saved form details show a shared drop zone with keyboard/touch file chooser, selected filenames, sequential uploads, retained failed selections and authenticated downloads for opening/previewing files. Create/edit dialogs explain the save-first flow. Supported formats: PDF, DOCX, XLSX, JPG/JPEG and PNG; maximum 10 MB per file and five active/pending files per record.
- Added typed attachment metadata with explicit parent FKs and a one-parent CHECK, private storage, role/parent authorization, optimistic versions and upload UUID/hash replay protection. Reservation state stays pending until bytes and the authorized/versioned finalization succeed. Content/extension checks include bounded Office-package inspection. Upload/removal advances content/lock versions and resets Pending; earlier reviews remain intact. Download forces binary attachment/no-store/nosniff. Soft removal retains bytes privately and denies download; parent deletion also denies file access. Pending failure cleanup and a preview/`--apply` cleanup command handle abandoned uploads older than 24 hours without deleting ready/retained files.
- Backed up local MySQL `127.0.0.1 / masar` under ignored `backups/masar-before-form-attachments-20261025/`, applied only `2026_10_25_120104_create_form_attachments_table`, and compared all previous application rows: unchanged. The new attachment table is empty; no demo binary files were seeded and no dependency added. Current CLI PHP upload/post limits exceed application limits; deployment documentation specifies the serving SAPI/web-server requirements separately.
- Verification: full backend suite **241 tests / 5,831 assertions** and frontend **100 tests plus 3 theme checks** passed. After adding the final locked-cleanup failure test, all **8 focused attachment tests / 199 assertions** passed. Covers all four forms, real PDF/image/Office content, extension spoofing, size/count limits, replay/stale writes, supervisor/head/counselor scope, cross-parent/file access, deleted records, version/review invalidation, storage failure/conflict cleanup and retained metadata when cleanup fails. Five frontend tests cover drop/select, sequential versioned uploads, retry UUID/selection preservation, read-only roles and binary downloads/removal. Production frontend build, Pint, formatting and diff checks passed; lint retains only the two existing provider Fast Refresh warnings. Browser visual/mobile and staging/production acceptance remain pending.
- Updated project/backend instructions with the reusable drop-zone contract and deployment instructions with private storage persistence/backups, server limits, migration and cleanup procedures. There is no inline viewer or malware scanning service.
