# Kualifi — locked decisions

Product: **Kualifi** (AI4Good) — multi-tenant SaaS preparing Malaysian companies
for SIRIM 55:2023 ESG certification. Built as "ESGReady", **rebranded to Kualifi
on 29 Jul 2026**. Commercial productization of the ESG module originally built
inside Dale Carnegie Malaysia's VoC portal; **the DC portal is not touched by
this project.**

Decisions below were asked and answered explicitly on 28–29 Jul 2026 (none
assumed). Change them deliberately, in this file, not by drive-by code edits.

## Platform & hosting
- Plain **PHP 8 + PDO + MySQL** on cPanel-style shared hosting. No framework, no
  Composer — same constraints and idioms as the DC portal it derives from.
- **Domain: `kualifi.com`** (decided 29 Jul 2026), hosted as an **addon domain
  on an existing cPanel account**.
- English-only UI for v1.

## Brand (29–30 Jul 2026)
- Product name **Kualifi** everywhere (app, emails, padmin). `APP_COMPANY`
  stays **AI4Good** — Kualifi is the product, not the company.
- **Brand package v1.3 adopted 30 Jul 2026** (`KualifiBrand/Corrected-Assets/`
  is the authority): navy/cobalt/lime/teal on warm canvas, Plus Jakarta Sans +
  Inter, pill actions, navy+lime focus ring. Landing page uses the approved
  website copy verbatim; About section carries the approved Purpose, Promise,
  Positioning statement, five-year direction and message pillars.
- Tagline: **"Making ESG readiness achievable."**
- **INTERIM RULE (in force, user decision: applies EVERYWHERE)** — no
  user-visible copy, email, or AI-generated document names SIRIM or
  SIRIM 55:2023; say "Malaysia's national ESG standard". Internal identifiers
  (standards.code `SIRIM55`, seed filename, SQL comments, negative prompt
  instructions) are exempt. Lift only when SIRIM's written permission lands
  (named-reference register is parked in the brand guidelines §8).
- Readiness never blurs into certification: "Certification Pack" renamed
  **"Assessment Pack"**; approved interim disclaimer on the landing page,
  public footer and Assessment Pack.
- **Four-tier readiness (user decision: full migration, not display-only)**:
  Foundation < 35 ≤ Building < 60 ≤ Progressing < 80 ≤ Assessment-ready
  (padmin-editable boundaries on `standards`). Enum values
  `foundation/building/progressing/assessment_ready`; live DB migrates via
  `sql/migrate_01_four_tier.sql`. Every outcome renders with
  "Kualifi methodology v1 · assessed <date>" (brand rule).
- British English, no Oxford comma, unspaced em dashes — policy for all copy.
- **Approved deviation from the brand nav spec**: the landing navigation omits
  "Resources" and "Pricing" until those pages exist; "Assessment preparation"
  is an on-page section. Revisit when pricing launches.
- **Reviewer-feedback additions (30 Jul 2026), approved extensions to the
  website copy**: three pain cards under the problem section; a metrics strip
  in About (true product facts only — no customers to cite yet; replace with
  testimonials when real ones exist); "About 5 minutes · instant result ·
  free" microcopy under assessment CTAs; public assessment asks the questions
  FIRST and contact details after (no-JS falls back to one screen); question
  pillar labels appear only in the result breakdown. Tagline feedback
  ("available" vs "achievable") noted and NOT adopted — the approved brand
  asset stands; revisit at the next brand review.
- Leads inbox: `mahmud.hisham@ai4good.com` (config).

## Tenancy
- **Single database**; every tenant-owned table carries `company_id`; every
  query filters on it via `Tenant::id()`. No page accepts a company_id from
  user input.
- **Template-copy pattern**: standard content lives in global `std_*` seed
  tables; activating a standard copies rows into the company's own editable
  tables (`Tenant::activateStandardContent()`).
- **Multi-standard schema** (`standard_id` on standards content) with only
  SIRIM 55 shipped in v1.

## Accounts & access
- **Self-registration** with email verification (single-use hashed tokens,
  48h TTL). First registrant creates the company and becomes **Owner**;
  Owners invite **Members** by email. Two roles only in v1.
- **Platform admins are a separate auth surface** (`platform_admins`, /padmin)
  that never mixes with tenant users. Support access is by **impersonation**,
  entered/exited with `audit_log` rows and a visible banner.
- Suspending a company takes effect on the next request, not next login.

## Holidays & working week (30 Jul 2026, superseding same-day national-only note)
- **Per-state model**: `companies.state` (chosen at registration, Owner-editable
  in Team; 3-letter codes, `''` = unspecified) selects which holidays apply —
  national `''` rows plus that state's rows in `holidays.state` — AND the
  weekend pattern: Kedah/Kelantan/Terengganu run Friday–Saturday
  (`EsgSchedule::FRI_SAT_STATES`), everyone else Saturday–Sunday.
- Seed (`sql/seed_holidays_my.sql`) carries the national set; state-specific
  holidays are added via padmin → Holidays as customers need them.
- Date changes never retro-shift already-generated periods (same rule as
  holiday edits); state changes affect future generations only.

## AI
- Platform-owned Anthropic key (key file outside webroot); document generation
  uses **`claude-opus-5`** (decided 29 Jul 2026 — same price as the previously
  chosen `claude-opus-4-8`, current-generation Opus; `max_tokens` 8000 with
  effort `medium` because Opus 5 thinks by default within the token cap).
- **Per-tenant monthly AI quota** (`companies.ai_quota_month`, default 20,
  padmin-adjustable), consumed and audited via `ai_usage` before each call.

## Email
- All sending through **`Mailer::send()`** — PHP `mail()` today (confirmed for
  launch, 29 Jul 2026); the wrapper is the single swap point for SMTP/provider
  later. **SPF + DKIM must be configured on kualifi.com** — see
  `docs/DEPLOY.md` step 7.

## Funnel
- Public **Readiness Assessment**: weighted No/Partially/Yes questions per
  pillar (E/S/G/MS), outcome Poor/Intermediate/Ready with padmin-editable
  thresholds on the standard; guest attempts claimable after signup;
  retakeable in-portal with trend. Support-interest → `leads` queue in padmin,
  notified to `LEADS_EMAIL`.

## Billing
- **Dormant skeleton only**: `plans` / `subscriptions` / `payments` tables
  exist, every company sits on a seeded `free` plan, **no gateway chosen** —
  deliberately deferred until payments actually launch.

## Legal / IP
- SIRIM 55:2023 is a licensed document. Reusing its clause summaries and
  guidance content in a commercial product is an IP question the user has
  **explicitly deferred** — revisit before public launch.

## Deferred / open (do not resolve silently)
- Payment gateway choice + pricing (billing skeleton stays dormant).
- **SIRIM content licensing for commercial use — gates PUBLIC launch.** A
  private pilot is fine; resolve before charging customers or marketing
  publicly.