# Decisions log

Newest first. One entry per decision change: the detail and reasoning behind
the short rows in [DECISIONS.md](DECISIONS.md). Agents read it only when they
need *why* or *when* a decision changed: `grep -n "TD-03" docs/DECISIONS_LOG.md`.

```
### YYYY-MM-DD — <ID> <short title>
- **Status:** <old> → <new>
- **Decided by:** <client / project owner / engineering>
- **Decision:** <what was decided>
- **Impact:** <features, docs, code, settings affected>
```

### 2026-11-12 — DEC-14 login identifiers per surface
- **Status:** Open → Partly resolved
- **Decided by:** client
- **Decision:** Admin = email + password. Trainer, trainee, hall provider and training center = phone + password. Initial password generation and delivery channel remain open.
- **Impact:** S1-04, S1-24, S1-30, S1-34, S1-35; center and provider login rows ("username") superseded.

### 2026-11-12 — DEC-23 proceed without early renewal / switching
- **Status:** Open → Partly resolved
- **Decided by:** client
- **Decision:** Build plan CRUD, subscriptions and purchase now; early renewal and model switching deferred.
- **Impact:** S1-16 to S1-18, S1-38, S1-39.

### 2026-11-12 — DEC-06 deferral accepted
- **Status:** Open (unchanged)
- **Decided by:** client
- **Decision:** Keep the fake `PaymentGateway` driver (TD-15); vendor to be supplied later.
- **Impact:** S1-38 and all payment rows.

### 2026-11-15 — TD-21..TD-25 provider and trainer sprint 1
- **Decided by:** engineering, pending client confirmation (TD-21 follows DEC-14).
- **Decision:** phone-or-email login scoped per account type; trainer registration with the password at step 1 and a new `profile_incomplete` → `under_review` transition; trainer text stored once for every language; only accepted / booked requests hold a hall slot; package allowance counts submitted courses.
- **Impact:** `provider/account.md` 1.1.0, `provider/halls.md` 1.1.0, `trainer/auth|profile|subscriptions|course-create|hall-bookings.md`.

### 2026-11-15 — TD-20 hall availability period rules
- **Decided by:** engineering, pending client confirmation.
- **Decision:** same-date periods, no overlap within a hall, future start; creation serialised by a row lock on the hall.
- **Impact:** `provider/halls.md` 1.0.0, `AvailabilityPeriodIsValid`.

### 2026-11-12 — TD-18 / TD-19
- **Decided by:** client (TD-19, admin login by email); engineering (TD-18, hall feature price per slot per BR-HALL-05).

### 2026-11-12 — TD-14 public uuid on every table
- **Status:** — → Accepted
- **Decided by:** project owner
- **Decision:** every table has `id` (BIGINT, used only for foreign keys and joins) and `uuid` (CHAR(36), unique). All CRUD between the Flutter / Vue apps and the API uses the uuid; foreign keys in tables stay integer ids. Resources never return `id`; models bind routes on `uuid`; the app generates an ordered UUID (a MySQL default is only a backstop). Excluded: composite-key pivots, `notifications` (id is already a uuid), `media` (own uuid). Closes the "public id strategy" question in `.kiro/steering/api-surfaces.md`.
- **Built:** `App\Core\Traits\HasUuid` (uuid on create, route binding, `findByUuid`, `idFromUuid`, hides `id`); `AdminResource::publicId()` / `uuidOf()` and `relationSummary()` emit uuids; `tests/Concerns/AssertsPublicIds` + `tests/Feature/PublicUuidTest` (a new resource returning `->id` fails). Pre-TD-14 resources are listed in that test and convert with their model + migration.
- **Impact:** `docs/database/db-schema.sql`, every model (`HasUuid`), resource, route binding and request validation (`exists:…,uuid`); API docs and Postman.

### 2026-11-12 — TD-13 domain ledgers instead of one journal
- **Status:** — → Accepted
- **Decided by:** engineering, approved by the project owner
- **Decision:** The first draft had a generic `ledger_entries` journal. Each money or points table is already an append-only ledger: payments (money in), course_earnings (owed to course owners), hall_commissions (owed by providers), cashback_transactions, points_transactions, and the refund fields on enrollments. Rows are appended and only their status changes; balances are sums; every insert carries a unique idempotency key. A second journal would duplicate them and could drift. A package price is split across its courses in proportion to their list prices, the last course taking the rounding remainder, so commission and refunds work per course.
- **Impact:** `docs/database/db-schema.sql` §6–7; business-logic hard rule 8 satisfied per table.

### 2026-11-12 — TD-12 bilingual notifications
- **Status:** — → Accepted
- **Decided by:** project owner (database design session, 2026-11-12)
- **Decision:** Notifications are stored in Laravel's `notifications` table with `data.title` and `data.body` in both Arabic and English, plus type and related record, so each app shows the language the user currently uses.
- **Impact:** PLT-004, TRN-021, TRR-029, every surface's notification list.

### 2026-11-12 — TD-11 base tables dropped or changed
- **Status:** — → Accepted
- **Decided by:** project owner (database design session, 2026-11-12)
- **Decision:** Dropped for Morvia: wallets, transactions, withdraw_requests (the trainee has no money wallet — cashback and points are ledgers; trainer and center payouts are settled outside by the admin, BR-FIN-04; the BRD has no withdrawal request), governorates and their translations, regions, shipping zones, addresses (the BRD has only cities; addresses are free text, DEC-03). Slider text moves to slider_translations; categories lose parent_id (no sub-categories); country_translations lose slug.
- **Impact:** Base migrations to drop / alter when the owning features are built; `docs/database/db-schema.sql` §1.

### 2026-11-12 — TD-10 live course row and edit requests
- **Status:** — → Accepted
- **Decided by:** project owner (database design session, 2026-11-12)
- **Decision:** Instead of `course_versions`, the `courses` row is the live, approved course. Draft and rejected courses are edited directly. A substantive edit to a published course (D2) is stored as JSON in `course_requests` (type edit) while the live row stays unchanged, and is applied when the admin approves; rejection leaves the course as it was. Course cancellation requests (D5) use the same table (type cancellation). Learning points (TRR-014) are a JSON list per language on `course_translations`; external access and threshold deadlines are columns on `courses`; deadline extensions are audit_logs rows.
- **Impact:** TRR-009..023, ADM-025..032; `docs/database/db-schema.sql` §4; removes course_versions, course_version_translations, course_learning_points (+tr), course_reviews, course_cancellation_requests, course_access, course_threshold_events, course_discounts, offers (+tr), offer_courses.

### 2026-11-12 — SCR-05 course session list
- **Status:** — → Adopted
- **Decided by:** project owner (database design session, 2026-11-12)
- **Decision:** The create / edit course screens have a Sessions step: number of sessions, then a name, date and time per session. Stored in `course_sessions` as information only — no attendance or per-session management (A-p.20). A threshold course's session dates stay empty until the date is set.
- **Impact:** TRR-009, TRR-021, TRN-013 ("next session").

### 2026-11-12 — SCR-04 trainer ratings
- **Status:** — → Adopted
- **Decided by:** project owner (database design session, 2026-11-12)
- **Decision:** The screens let the trainee rate the instructor (1–5 stars and a comment) from a completed course in My Courses and show the reviews on the trainer profile; the BRD has no ratings. Ratings are for the trainer, not the course; a center course without a responsible trainer rates the center. One rating per completed enrollment.
- **Impact:** New table `trainer_ratings`; trainee My Courses, trainer profile, admin (moderation not defined).

### 2026-11-12 — DEC-34 changing a course price
- **Status:** — → Resolved
- **Decided by:** project owner (database design session, 2026-11-12)
- **Decision:** A course's price can be changed only until the course has its first confirmed enrollment; after that the price is locked. The discount (the offer) can still be added or changed and is reviewed with the course (DEC-08). Overrides TRR-021 / BR-CRS-07, which allowed a price change with enrollees applying to new enrollments only.
- **Impact:** TRR-021, ADM-028, BR-CRS-07; BRD guide updated.

### 2026-11-12 — TD-09 country and nationality fields
- **Status:** — → Accepted
- **Decided by:** engineering, delegated by the project owner
- **Decision:** `users.country_id` is the country of residence (address) for every account type (DEC-03). A trainer's nationality is a separate field filled from the Nafath verification: it is verified identity data, while the address country is self-entered; the trainee has no nationality field.
- **Impact:** users, trainer table, TRN-002, TRR-002, `docs/database/`.

### 2026-11-12 — DEC-33 hall commission timing
- **Status:** — → Resolved
- **Decided by:** project owner (design session of the database, 2026-11-12)
- **Decision:** Conflict BR-HALL-14 (due at Accepted) vs BR-ADMIN-HALL-07/08 (Pending at Accepted, Due at Booked). The owner described the flow: provider accepts the request → the parties arrange offline → the provider confirms Booked → only then is it a real booking and the commission counts as income. So the commission is created Pending at Accepted (not income), becomes Due at Booked, and is cancelled by any withdrawal or cancellation; a cancelled booking earns no commission.
- **Impact:** ADM-019, HPV-008, HPV-010, BR-HALL-14 superseded, BR-HALL-18 and BR-ADMIN-HALL-15 widened; BRD guide §11.7, §12.

### 2026-11-12 — DEC-31 what buying a package creates
- **Status:** Open → Resolved
- **Decided by:** project owner (design session of the database, 2026-11-12)
- **Decision:** All or nothing: buying a package creates a confirmed enrollment in every included course in one operation; if any course cannot take the trainee the whole purchase is refused. Each enrollment keeps its share of the package price (needed for commission on the amount actually paid, BR-FIN-02).
- **Impact:** TRN-017, TRR-016, ADM-033; enrollments carry the package purchase.

### 2026-11-12 — DEC-29 seat holding during payment
- **Status:** Open → Resolved
- **Decided by:** project owner (design session of the database, 2026-11-12)
- **Decision:** No seat hold. The seat is taken only when the payment succeeds; confirmation re-checks capacity under a row lock so two payments at the same moment cannot both take the last seat.
- **Impact:** TRN-010, TRN-011; enrollment confirmation.

### 2026-11-12 — DEC-22 hall commission rate setting
- **Status:** Open → Resolved
- **Decided by:** project owner (design session of the database, 2026-11-12)
- **Decision:** One global commission rate (setting), copied onto each booking's commission so later changes never alter it (BR-FIN-03).
- **Impact:** ADM-019, ADM-051.

### 2026-11-12 — DEC-21 package duration
- **Status:** Open → Resolved
- **Decided by:** project owner (design session of the database, 2026-11-12)
- **Decision:** "Duration" = the package's start and end date of sale. The package shows its price against the total of its courses' prices.
- **Impact:** TRR-016, ADM-013, package form.

### 2026-11-12 — DEC-20 center profile change approval
- **Status:** Open → Resolved
- **Decided by:** project owner (design session of the database, 2026-11-12)
- **Decision:** After approval only sensitive fields (licence, IBAN) wait for admin approval; other fields save directly. Same mechanism as DEC-13.
- **Impact:** CTR-015, ADM-012.

### 2026-11-12 — DEC-18 what an offer is
- **Status:** Open → Resolved
- **Decided by:** project owner (design session of the database, 2026-11-12)
- **Decision:** The offer is the trainer's course discount: a percentage with a start and end date, entered from "Add discount" on the create / edit course screen (`docs/app_screens/trainer/indvidual/trainer--courses--04-individual-edit.png`); the app shows the price and the discounted price. No separate offer entity; the trainee's Offers section lists courses whose discount is active.
- **Impact:** TRN-010, TRN-018, TRR-013, ADM-013.

### 2026-11-12 — DEC-17 hall booking to course link
- **Status:** Open → Resolved
- **Decided by:** project owner (design session of the database, 2026-11-12)
- **Decision:** No link between a booking and a course. An in-person course stores the hall name and address as text, a location link and hall photos; the fields are empty for an external course. Provider "courses in my halls", course cards on the hall page and unlink-on-cancel are out of scope.
- **Impact:** TRR-033, HPV-012, HPV-013, ADM-021, TRN-027; BR-HALL-19/20/22, BR-ADMIN-HALL-18/19 marked out of scope.

### 2026-11-12 — DEC-16 center's own halls
- **Status:** Open → Resolved
- **Decided by:** project owner (design session of the database, 2026-11-12)
- **Decision:** Out of scope: halls in the system belong only to hall providers.
- **Impact:** CTR-016, ADM-011.

### 2026-11-12 — DEC-15 center financial model (partly)
- **Status:** Open → Partly resolved
- **Decided by:** project owner (design session of the database, 2026-11-12)
- **Decision:** The center sees, per course and in total, the course revenue, the platform income and the center net income. Where the platform rate comes from (one setting or per center) and how the center is paid out are still open.
- **Impact:** CTR-010, ADM-038.

### 2026-11-12 — DEC-13 trainer profile edits after approval
- **Status:** Open → Resolved
- **Decided by:** project owner (design session of the database, 2026-11-12)
- **Decision:** Only sensitive fields — training licence, IBAN, CV — go back to admin review; the live value changes only on approval. Other fields save directly.
- **Impact:** TRR-028, ADM-006.

### 2026-11-12 — DEC-12 enrollment cancellation and refunds
- **Status:** Open → Resolved
- **Decided by:** project owner (design session of the database, 2026-11-12)
- **Decision:** No trainee cancellation or refund request in the app (also D6). The trainee contacts support; an admin or supervisor removes the trainee from the course in the dashboard and in the same step adjusts the wallet (returns points / cashback used, cancels pending rewards). Cash is refunded outside the system; the system tracks the refund status and never pays the same amount twice.
- **Impact:** TRN-021, ADM-031, ADM-033, TRR-025.

### 2026-11-12 — DEC-09 package approval
- **Status:** Open → Resolved
- **Decided by:** project owner (design session of the database, 2026-11-12)
- **Decision:** Packages are not reviewed before they are visible. The admin can deactivate any package and the owner can stop selling it (C-§16).
- **Impact:** TRR-016, CTR-012, ADM-013.

### 2026-11-12 — DEC-08 course discount controls
- **Status:** Open → Resolved
- **Decided by:** project owner (design session of the database, 2026-11-12)
- **Decision:** No maximum and no separate approval: the trainer decides. The discount is part of the course data the admin reviews; if the admin rejects the course because of it, the trainer edits and resubmits.
- **Impact:** TRR-013, ADM-026.

### 2026-11-12 — DEC-04 one person, several account types
- **Status:** Open → Resolved
- **Decided by:** project owner (design session of the database, 2026-11-12)
- **Decision:** One account per app. Each account has exactly one type (trainee, trainer, center, provider, admin); the same mobile may register on different apps as separate accounts and is unique per account type. Tokens are checked against the account type (TD-08).
- **Impact:** TRN-002, TRR-002, TRR-003, TD-08.

### 2026-11-12 — DEC-03 trainee address
- **Status:** Open → Resolved
- **Decided by:** project owner (design session of the database, 2026-11-12)
- **Decision:** The trainee's address is a country and a city from the lists plus a free-text address.
- **Impact:** TRN-002, TRN-022, ADM-004.

### 2026-11-12 — D9 packages and trainer subscription expiry
- **Status:** — → Resolved (client)
- **Decided by:** client — cancellation and settlement policy PDF (`Morvia_Cancellation_Policy_.docx.pdf`, 10-11-2026; transcription `docs/brd/Morvia-cancellation-policy-ar.md`)
- **Decision:** A package withdrawn from sale stays valid for past buyers, with no refund for that reason; a cancelled course inside a bought package leaves the package running and its share is settled outside the system; the trainee cannot cancel a package or ask for a refund just to cancel. When an independent trainer's subscription ends, published courses stay live and keep selling, the trainer can manage and complete them, but cannot create or publish new courses until renewal (C-§16–20).
- **Overrides:** BRD p.128 (subscription end), A-p.20.
- **Impact:** TRN-017, TRR-016, CTR-012, ADM-013, TRR-030, ADM-037; BR-CNL-10, BR-CNL-11.

### 2026-11-12 — D8 hall booking withdrawal and cancellation
- **Status:** — → Resolved (client)
- **Decided by:** client — cancellation and settlement policy PDF (`Morvia_Cancellation_Policy_.docx.pdf`, 10-11-2026; transcription `docs/brd/Morvia-cancellation-policy-ar.md`)
- **Decision:** The trainer or center withdraws a request until the provider confirms it (Booked), without the provider's approval. A Booked booking is cancelled by the provider: on the booker's cancellation request (approve / reject; paid fees are not refunded and the app warns before sending), or agreed offline and recorded by the provider with a reason (project owner). No in-system refund; a course is never cancelled automatically; a lost hall is replaced by editing the course venue under the normal review (C-§12–15).
- **Overrides:** BR-HALL-16, BR-HALL-17, BR-ADMIN-HALL-12, BR-ADMIN-HALL-13 (admin-only cancellation).
- **Impact:** TRR-032, HPV-011, ADM-020; BR-CNL-08, BR-CNL-09; with DEC-33 no commission on a cancelled booking.

### 2026-11-12 — D7 money effects of a cancelled course
- **Status:** — → Resolved (client)
- **Decided by:** client — cancellation and settlement policy PDF (`Morvia_Cancellation_Policy_.docx.pdf`, 10-11-2026; transcription `docs/brd/Morvia-cancellation-policy-ar.md`)
- **Decision:** Pending trainer / center entitlements are cancelled and never become Available; an exceptional cancellation after the start is settled outside, with no automatic partial calculation. A cancelled course earns no points or cashback, pending rewards are cancelled, points or cashback used to pay return to their original balance, and only the cash actually paid is refunded. The ticket stays visible with its number, marked "Not valid for use"; no certificate for a cancelled course; Completed certificates are unaffected (C-§21–23).
- **Overrides:** BRD p.51, p.133.
- **Impact:** TRN-019, TRN-024, TRN-025, TRR-025, ADM-038; BR-CNL-06, BR-CNL-07.

### 2026-11-12 — D6 trainee enrollments and refunds
- **Status:** — → Resolved (client)
- **Decided by:** client — cancellation and settlement policy PDF (`Morvia_Cancellation_Policy_.docx.pdf`, 10-11-2026; transcription `docs/brd/Morvia-cancellation-policy-ar.md`)
- **Decision:** No self-cancel button or request for the trainee. An enrollment in a cancelled course stays in My courses as Cancelled with its details and refund status; content and ticket are no longer usable. Cash is refunded by contacting platform support outside the system (highlighted by the client); a refund is never recorded as completed before the transfer is confirmed, the admin follows it, and the same amount is never paid twice (C-§08–11). §02's reference to "the two open options above" points to a section the PDF does not contain.
- **Overrides:** BRD p.33, p.51 (refund flow undefined).
- **Impact:** TRN-013, TRN-014, ADM-031, ADM-033, ADM-034; BR-CNL-04, BR-CNL-05; resolves DEC-12 with the owner's answer.

### 2026-11-12 — D5 course cancellation
- **Status:** — → Resolved (client)
- **Decided by:** client — cancellation and settlement policy PDF (`Morvia_Cancellation_Policy_.docx.pdf`, 10-11-2026; transcription `docs/brd/Morvia-cancellation-policy-ar.md`)
- **Decision:** Only an independent trainer (own courses) or a training center (its courses, in its name or linked to an affiliated trainer) requests a cancellation, with a reason; the admin approves or rejects and notifies the requester; the course becomes Cancelled only on approval and sales stop. A started course is cancelled only exceptionally on a reasoned request, with no automatic partial calculation; a Completed course is never cancelled, not even by the admin. At a passed threshold deadline (minimum not reached, or date not set) nothing happens automatically: the admin extends the deadline or cancels. Requester, date, reason and decision are recorded in the admin course details, with no separate log screen (C-§01–07, §24).
- **Overrides:** BRD p.50, A-p.13–14.
- **Impact:** TRR-023, TRR-015, ADM-031, ADM-032, TRN-021; BR-CNL-01..03.

### 2026-11-11 — TD-08 token separation between surfaces
- **Status:** — → Proposed
- **Decided by:** engineering (rule from `.kiro/steering/api-surfaces.md`)
- **Decision:** all five surfaces share the JWT guard `api`; access is decided per app, not per user: a token issued by one surface's login must be refused (403) on every other surface, checked against the account type. Built with the first authentication feature.
- **Impact:** every surface's auth, `config/docs.php` → `surfaces.*.guard`.

### 2026-11-11 — TD-07 API surfaces and consumer apps
- **Status:** — → Accepted
- **Decided by:** project owner
- **Decision:** the BRD's five apps map to five surfaces: `admin` (Vue dashboard, was React), `client` (trainee Flutter app), `trainer` (Flutter app for independent and center-affiliated trainers), `center` (training-center Vue dashboard), `provider` (hall & event provider Vue dashboard). Route files `routes/api/v1/{trainer,center,provider}.php` are mounted empty; endpoints arrive feature by feature. Sign-in per BRD: trainee mobile + password (OTP at registration); independent trainer mobile or email + password (Nafath at registration); affiliated trainer, center, provider and admin username + password.
- **Impact:** `config/docs.php`, `bootstrap/app.php`, `routes/api/v1/*`, `docs/{trainer,center,provider}/README.md`, `docs/admin/README.md`, `PROJECT_BRAIN.md` §2 and §4, `.kiro/steering/api-surfaces.md`, `AGENTS.md`.

### 2026-11-11 — D4 course points set by the admin, earned at completion
- **Status:** — → Resolved (client)
- **Decided by:** client — additional requirements PDF (notes of 18-10-2026 / 22-10-2026)
- **Decision:** Course points are set by the admin during course review (the trainer cannot set them) and are earned when the course is completed (A-p.10–11).
- **Overrides:** BRD p.23, p.30 (points on enrolling), p.131 (points on purchase).
- **Impact:** TRN-008, TRN-012, TRN-019, ADM-026, ADM-041; see the BRD guide §9 (change map).

### 2026-11-11 — D3 training centers create and own courses
- **Status:** — → Resolved (client)
- **Decided by:** client — additional requirements PDF (notes of 18-10-2026 / 22-10-2026)
- **Decision:** Training centers create and own courses: one create screen with "course provider" (center / affiliated trainer); a trainer's course (with proposed price) is reviewed, re-priced and submitted by the center; the center is the financial owner and receives payouts; center packages show under the center's name (A-p.16–18).
- **Overrides:** BRD p.63–65, p.70 (course created by the trainer; center never edits or submits).
- **Impact:** CTR-007, CTR-008, CTR-009, CTR-010, CTR-012; see the BRD guide §9 (change map).

### 2026-11-11 — D2 editing and cancelling a published course
- **Status:** — → Resolved (client)
- **Decided by:** client — additional requirements PDF (notes of 18-10-2026 / 22-10-2026)
- **Decision:** Published-course edits: substantive edits (name, description, price, category, sessions, seats, learning points) are requested and re-reviewed while the approved version stays live; operational edits (session link) apply directly; no type change after confirmed enrollments; seats ≥ confirmed; cancellation only by admin approval of the owner's request (A-p.11–13).
- **Overrides:** BRD p.49–50 (any edit re-reviews; substantive edits made by the admin; no cancel).
- **Impact:** TRR-020, TRR-021, TRR-023, ADM-028, ADM-031; see the BRD guide §9 (change map).

### 2026-11-11 — D1 hall booking separate from course creation
- **Status:** — → Resolved (client)
- **Decided by:** client — additional requirements PDF (notes of 18-10-2026 / 22-10-2026)
- **Decision:** Hall booking is separate from course creation: the trainer books a hall independently and types the venue (hall name, address, map link, notes) into the in-person course; the course form never searches halls or pulls bookings; the admin reviews the venue with the course (A-p.18–19).
- **Overrides:** BRD p.12, p.43 (pick hall from list), p.83 (link Booked request), p.119 (confirmed booking at review).
- **Impact:** TRR-010, TRR-033, HPV-012, HPV-013, ADM-021, ADM-026; see the BRD guide §9 (change map).

### 2026-11-11 — DEC-32 Delivery phasing
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** The BRD has no delivery plan; all features are registered as phase 1 until the client splits them.
- **Impact:** PROJECT_BRAIN §6. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-31 What buying a package creates
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** Does a package purchase create a confirmed enrollment (seat, ticket) in every included course, and what if one is full?
- **Impact:** TRN-017, TRR-016, ADM-033. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-30 Notification channels
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** In-app and email are mentioned (p.37); which events also go by push or SMS?
- **Impact:** PLT-004. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-29 Seat holding during payment
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** "Course full before confirmation stops the operation" (p.25); are seats held while payment is pending, and for how long?
- **Impact:** TRN-010, TRN-011. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-28 Report exports
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** Reports have filters (p.139–140); export formats (Excel, PDF) are not specified.
- **Impact:** ADM-048, CTR-013, ADM-024. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-27 Manual notifications by the admin
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** "Follow and send" operational notifications (p.138); can the admin broadcast manual notifications?
- **Impact:** ADM-047, PLT-004. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-26 Level discount rate vs points conversion
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** Levels carry a discount rate (p.32) while points convert at a fixed rate (p.133); how is the points discount computed and capped?
- **Impact:** TRN-019, ADM-041. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-25 Cashback pending → available
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** Ledger has Pending / Available / Used (p.131) but the trigger is not given (payment? course completion?).
- **Impact:** ADM-040, TRN-019. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-24 Several cashback rules
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** One rule (threshold → value) is described (p.30–31, p.130); can several tiers be active at once?
- **Impact:** ADM-039, TRN-019. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-23 Trainer package renewal vs model switching
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** Renewal any time without carry-over (A-p.20) vs no model switch while one is active (p.128); can a commission trainer buy a package (or back) early?
- **Impact:** TRR-030, ADM-037. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-22 Hall commission rate setting
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** One commission rate for hall bookings (p.81); where it is set and whether it can differ per provider is not stated.
- **Impact:** ADM-019, ADM-051. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-21 Package "duration"
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** Admin trainee-package screen lists a duration (p.134) that the package form lacks (p.45–46).
- **Impact:** TRR-016, ADM-013. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-20 Center profile change approval
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** Center edits need admin approval (p.69); no request / approval screen defined.
- **Impact:** CTR-015, ADM-012. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-19 Provider notification catalogue
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** Provider receives service and booking notifications (p.87); the list is not given.
- **Impact:** HPV-015, PLT-004. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-18 What an "offer" is
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** Offers are listed (p.10, p.20, p.25, p.30: active, validity period, linked to course) but no entity or admin screen defines them.
- **Impact:** TRN-010, TRN-018, ADM-013. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-17 Hall booking ↔ course link after D1
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** With venue typed manually, do Booked requests still link to courses (provider "courses in my halls", hall-page course cards, unlink on cancel)?
- **Impact:** TRR-033, HPV-012, HPV-013, ADM-021. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-16 Center's own halls
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** Scope says centers manage their own halls (p.5, p.100–102) but no screens or rules exist.
- **Impact:** CTR-016, ADM-011. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-15 Center financial model and payouts
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** Platform share from center courses (commission? contract?) and how the center is paid out; no admin screen (A-p.15–18).
- **Impact:** CTR-010, ADM-038. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-14 Credentials for admin- or center-created accounts
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** How usernames / initial passwords are generated and delivered (SMS, email) to affiliated trainers, centers and providers (p.60, p.71, p.100).
- **Impact:** CTR-005, ADM-010, ADM-015. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-13 Trainer profile edits after approval
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** Do edits to professional data (licence, CV, IBAN) after approval need admin re-review? (p.51–52).
- **Impact:** TRR-028, ADM-006. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-12 Enrollment cancellation and refunds
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** Notifications mention cancellation requests (p.33), refunds cancel entitlements (p.51), points return on cancellation (p.133); no trainee flow, policy or refund method exists.
- **Impact:** TRN-021, ADM-031, TRR-025, PLT-002. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-11 Course end time and auto-completion
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** How the end date/time is derived (duration unit, sessions) and whether completion is automatic by default or manual (A-p.20, p.122).
- **Impact:** TRR-022, ADM-030. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-10 Changing date, time or hall of a published course
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** Main BRD: such edits are made by the admin (p.50); notes: controlled change with enrollee notice (A-p.12–13). Who approves and how?
- **Impact:** TRR-021, ADM-028, TRN-024. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-09 Package approval
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** Trainer packages publish directly (p.45–47) but center packages go to review (A-p.17); does every package need admin review?
- **Impact:** TRR-016, CTR-012, ADM-013. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-08 Course discount controls
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** Trainer discount must follow "approved controls" (A-p.10–11): max %, validity period, admin review of the discount?
- **Impact:** TRR-013, ADM-026. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-07 Stacking of offer, discount, cashback and points
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** Only "offers are not combined" is stated (p.25); order and combination of course discount, package, cashback and points undefined.
- **Impact:** TRN-010, TRR-013, TRN-019. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-06 Payment gateway vendor and methods
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** Client contracts the provider (p.6); vendor, methods (mada, Apple Pay…), currency SAR assumed, refund support unknown.
- **Impact:** PLT-002, TRN-011, TRR-006. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-05 Enrolling in a free course
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** Free courses exist (p.42, p.123) but the enrollment flow has no free path: confirm directly, cashback / points / ticket rules?
- **Impact:** TRN-010, TRN-012, TRR-009. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-04 One person, several account types
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** Mobile is unique among trainee accounts only; can the same mobile / person also be a trainer, and does one login serve both apps? (p.18, p.38).
- **Impact:** TRN-002, TRR-002, TRR-003. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-03 Trainee "address" field
- **Status:** — → Open
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** Free text or a city from the cities list? Admin trainee details show "address / city" (p.18, p.94).
- **Impact:** TRN-002, TRN-022, ADM-004. Do not build behaviour that depends on it until answered.

### 2026-11-11 — DEC-02 OTP expiry and resend limits
- **Status:** — → Working assumption
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** BRD leaves them to the technical implementation: keep them in settings; values to be set by engineering (p.18).
- **Impact:** TRN-002, TRN-005, TRN-022. Do not build behaviour that depends on it until answered; keep the values in settings.

### 2026-11-11 — DEC-01 "Live sessions" in NFRs
- **Status:** — → Working assumption
- **Raised at:** BRD ingest (`project-init` step 2)
- **Question / assumption:** No in-platform live sessions: external courses run outside through a link (p.17 vs §5.5).
- **Impact:** PLT-*, TRR-011. Do not build behaviour that depends on it until answered; keep the values in settings.

### 2026-11-11 — SCR-01 enrollment points timing
- **Status:** — → Open
- **Observed:** `client/trainee/client--enrollment--01-trainee-checkout.png` says points are earned by enrolling; additional requirements PDF pages 10–11 award them when the course is completed.
- **Impact:** Do not implement the depicted award timing until confirmed.

### 2026-11-11 — SCR-02 shared academy trainer screen applicability
- **Status:** — → Open
- **Observed:** The user says academy trainer screens missing from the academy set share the individual trainer designs. The academy login export states that the academy instructor only logs in; the BRD describes center-provided credentials. The BRD and additional requirements reserve the independent trainer subscription and personal wallet/financial entitlement for the independent trainer. Confirm which actions and fields of the shared registration, plans and wallet designs apply to academy trainers; do not infer that shared visuals grant access.
- **Impact:** Trainer authentication, subscriptions, wallet and financial permissions; source images remain design references.

### 2026-11-11 — SCR-03 academy course price action
- **Status:** — → Open
- **Observed:** `trainer/academy/trainer--courses--02-academy-details.png` depicts a price edit action. Additional requirements pages 17–18 permit an affiliated trainer to propose a price, while the center reviews it, may change it, and submits the course for administration approval. Confirm how the depicted action interacts with center review, especially for published courses.
- **Impact:** Course price changes, center review and approval; no workflow is decided here.

### 2026-11-11 — TD-06 reusable project base
- **Status:** — → Accepted
- **Decided by:** project owner
- **Decision:** the repo is the base for every new project. The name is set once, in `APP_NAME`; `config/docs.php` derives the slug (`Str::slug`, override `DOCS_PROJECT_SLUG`), the summary (`DOCS_PROJECT_SUMMARY`), the cookie name and the app-team MCP name `{slug}-docs`. Files agents load by fixed path keep neutral names: skills `project-init` / `project-feature` / `project-feature-docs` / `project-decisions` / `project-migrations` / `project-postman`, stdio MCP handle `project-docs` (in `.mcp.json`, `.codex/config.toml`, `opencode.json`, `.agents/mcp_config.json`), `.codex/rules/project.rules`.
- **Impact:** `config/docs.php`, `.env.example`, all skills and agent configs, `AGENTS.md`, docs headers, `project-init` step 0.

### 2026-11-11 — TD-05 token budgets
- **Status:** — → Accepted
- **Decided by:** engineering (requested by the project owner)
- **Decision:** agents read slices, never whole files. `CLAUDE.md` imports only `business-logic.md` and `api-surfaces.md`; the other steering files are read on demand (Claude) or by `fileMatch` (Kiro). The Boost block is written once, to `AGENTS.md` (`config/boost.php`). `php artisan docs:split-brd` writes `docs/brd/features/{ID}.md`; `php artisan docs:brief` / MCP `get-integration-brief` return registry row + Quick reference + BRD section + decisions; `read-doc` has `outline` and `section`; `docs:index-screens` writes a text index of the screens. Limits in `config/docs.php` → `budgets`, enforced by `tests/Feature/DocsBudgetTest.php`. Decision detail moved from `DECISIONS.md` to this log.
- **Impact:** `CLAUDE.md`, `.kiro/steering/*` front matter, `config/{docs,boost}.php`, `app/Services/Shared/Docs/*`, `app/Console/Commands/Docs*`, templates, skills.

### 2026-11-11 — TD-01…TD-04 agent and docs setup
- **Status:** — → Accepted
- **Decided by:** engineering
- **Decision:** `/docs` (viewer), `/tester` (API console: in-process proxy to this API only, Quick Auth demo tokens) and `/mcp/docs` (`project-docs`, read-only) all read `docs/` through `DocsLibrary` behind one gate (`DocsAccess`, `config/docs.php`). Served on every environment except `production`/`prod`, with no token unless `DOCS_TOKEN` is set — set one on any internet-facing staging server. Production answers 404 unless `DOCS_ENABLED=true` and `DOCS_TOKEN` are both set; Quick Auth never runs there. Also: project manifest in `config/docs.php`; web routes registered; steering / skills / MCP layout copied from the reference project.
- **Impact:** `config/docs.php`, `app/Mcp/*`, `app/Services/Shared/Docs/*`, `routes/{web,ai}.php`, `bootstrap/app.php`, `AGENTS.md`, `CLAUDE.md`, `.kiro/steering/*`, `.agents/skills/*`.