Every step, nothing assumed.

1.1Signing in for the first time

1. Open any browser — Chrome, Edge, or Safari.
2. Click the address bar at the top, type the portal address, press Enter.
3. You will see a page split in two: a dark navy panel on the left saying Client Portal — Projects. Decisions. Deliverables. One place., and a white panel on the right saying Sign in.
4. Click the box labelled Email and type the address your invitation was sent to.
5. Click the box labelled Password and type your password.
6. Click the dark button labelled Sign In.
7. You land on your Dashboard. If the email or password is wrong, a red message appears above the form — check your typing and try again. Forgot it entirely? Recipe 1.9.

1.2Reading your Dashboard, top to bottom

1. The greeting — “Good morning / afternoon / evening”, today’s date, and a live Kuala Lumpur clock on the right.
2. The big navy card is your project.
   • The circle gauge shows overall completion — the number counts up to the true percentage.
   • The segmented bar is the phase track. Each segment is one phase: a wide segment is a big share of the contract, a narrow one small. Filled navy = finished, bronze = being worked on now, amber = waiting on you. Rest your mouse on a segment — a small dark box names the phase and its progress.
   • The capital-letter line underneath, e.g. PHASES 3/6 · TARGET 30 SEPT 2026 T−45D · ACTIONS 2, reads: 3 of 6 phases done · target date, 45 days away · 2 things need your action.
   • Click anywhere on the card to open the full project page.
3. ACTION REQUIRED — each card is something only you can do: an information request, an approval, or an unpaid invoice, each with a due pill like in 4 days or a red 5 days overdue. A green tick saying You’re all caught up is the goal state.
4. RECENT ACTIVITY — a timeline of what changed, newest first. Only client-visible events appear; internal engineering chatter never does.

1.3The menu

1. On a computer the menu is on the left: Dashboard · Approvals · Requests · Files · Invoices · Messages. The page you are on is highlighted dark with a small bronze bar.
2. At the bottom: ← Valtrin website (back to this site), your name, and Sign out.
3. On a phone there is no side menu — the same links live behind the top bar.

1.4Approving a deliverable

A deliverable is a piece of finished work — a design, a document, a build — sent to you to accept.

1. Click Approvals in the menu.
2. The section NEEDS YOUR APPROVAL shows a black count badge. Each card is one deliverable.
3. Read the card: the title, the project it belongs to, and the version rail — chips like V1.0 — V2.0. The bronze chip is the version being asked about now. Older versions stay on the rail forever; nothing is ever deleted.
4. Agree with the work? Click Approve V1C. The portal records your name, the exact time, and locks that version as accepted. The card moves into DECISION HISTORY.
5. Want something changed? Click Request changes V1C, type what should change, send. The corrected work returns as the next version — V3.0.

1.5Answering a request

A request is Valtrin asking you for something — a decision, a file, a piece of information.

1. Click Requests.
2. WAITING ON YOU lists the open ones. Each card shows the question, a line beginning Why: explaining what it unblocks, and a due pill.
3. Click Respond V1C, type your answer, send. Until then, simply answer in Messages — staff record it for you.
4. Answered requests move to ANSWERED below — the question and your answer both stay on record.

1.6Finding and downloading files

1. Click Files. Files are grouped by project.
2. Each row shows a file icon with its type (PDF, XLSX…), the name, then folder · version · size · date.
3. The coloured badge tells you what you may do:
   • Downloadable (green) — yours to save. Click the download button at the row’s end V1C.
   • Visible (grey) — view in the portal, not saveable (e.g. work-in-progress previews).
   • Approval required (amber) — a file waiting for your sign-off (recipe 1.4).
4. You will never see Valtrin’s internal working files here — the database itself filters them out; it is not just hiding.

1.7Invoices — checking and paying

1. Click Invoices. The top strip shows OUTSTANDING (total you owe) and OPEN INVOICES (how many).
2. Each open invoice shows its number (like VT-INV-2026-002), what it is for, the amount, a status pill, and a countdown pill.
3. Pay by bank transfer to the account printed on the invoice.
4. Click the invoice, choose Upload receipt V1C, attach the transfer slip, send.
5. Valtrin verifies it within one working day; the invoice moves to SETTLED with a green tick.
6. An invoice past its date turns red Overdue. Something wrong with an invoice? Say so in Messages — never just let it sit.

1.8Messages and decisions

1. Click Messages. There is one conversation per project. Messages from staff carry a small bronze VALTRIN tag.
2. Type in the box at the bottom, press the arrow button to send V1C.
3. A message on a light bronze background with a DECISION chip is a recorded agreement. The thread header counts these, so decisions never get lost in the scroll.
4. A small pin icon marks important reference messages.

1.9Forgot your password

1. On the sign-in page click Forgot password.
2. Type your email, click Send reset link.
3. The page says a link is on its way if that address has an account — it never reveals whether an email exists; that is deliberate.
4. Open the email, click the link, set a new password, sign in again.

1.10Your team’s roles

1.11What you can always trust

1. You can only ever see your own company’s projects, files, and invoices — enforced inside the database on every query, not by hidden buttons.
2. Approved versions are never silently deleted or edited.
3. Every action is written to a permanent log that nobody — including Valtrin — can alter.
4. Valtrin’s internal notes and costs are not visible to any client account by any means.

2.1Getting in

1. Sign in exactly like a client (recipe 1.1).
2. Staff accounts land on the Admin side automatically — dark navy menu, INTERNAL tag under the logo. Clients can never reach this side; the server checks on every page, not the browser.

2.2The morning routine — work the Today screen

1. Click Today. You see a card with today’s date in big numbers, the day name, and the live KL clock.
2. Queue 1 — INVOICES OUTSTANDING: every unpaid invoice, most overdue first, with red/amber pills and amounts. Chase the red ones today.
3. Queue 2 — WAITING ON CLIENTS: open requests with needed-by dates. Anything past its date gets a polite nudge in Messages.
4. Queue 3 — DELIVERABLES NEEDING MOVEMENT: work sitting in Awaiting approval or returned with changes. Remind the client, or start the revision.
5. Queue 4 — MILESTONES DUE WITHIN 7 DAYS (Kuala Lumpur calendar). Confirm each will land, or move its date honestly.
6. Queue 5 — PROJECTS BLOCKED ON CLIENT: whole projects stuck waiting. Click through and unblock.
7. Every queue showing Nothing here. Good. = the day is under control.

2.3Running a project

1. Click Projects → click the project.
2. The header card: gauge, phase track (each phase labelled with its % of contract weight), and the facts row — client, service line, dates, contract value, invoiced / paid.
3. How progress works: each phase has a weight (its share of the contract; all weights add to 100) and a completion. Overall progress = each weight × completion, added up. Update a phase’s completion V1C and the project number moves honestly.
4. Progress override: if the calculation misleads, pin a manual percentage — a reason is required, and the screen shows an amber manual override tag so nobody mistakes it for the calculation.
5. Right column: that project’s WAITING ON CLIENT items and its INVOICES. Bottom: the full activity trail.

2.4Asking the client for something

1. Open the project → create a request V1C: a clear title, a one-sentence why, and a needed-by date.
2. It appears on the client’s dashboard under ACTION REQUIRED, on their Requests page, and in your Today queue until answered.

2.5Sending work for approval

1. Upload the file (recipe 2.7), create a deliverable, attach the file as V1.0 V1C.
2. Send for approval — it appears in the client’s Approvals with the version rail.
3. If changes are requested, upload the revision — it becomes V2.0 automatically. Old versions are never overwritten; that history protects both sides.

2.6Invoicing

1. Click Invoices. The strip: OUTSTANDING (red) · COLLECTED (green) · OPEN (count).
2. New invoices V1C are numbered automatically — VT-INV-2026-NNN, strictly sequential; duplicates are impossible.
3. Lifecycle on the status pills: Draft (invisible to the client) → Issued → Due soon (3 days out) → Overdue — or Paid.
4. When a client uploads a transfer receipt, verify it V1C — the invoice flips to Paid and the verification is logged with your name.

2.7The visibility rule — the most important habit

Everything staff creates starts Internal, invisible to clients. Making something client-visible is always a deliberate choice.

2.8Recording a decision

1. When an agreement is reached in a thread, flag that message as a Decision V1C.
2. It gets the bronze chip, is pinned, and counted in the thread header — so “but we agreed…” is always answerable with a link.

2.9Clients screen & staff roles

1. Clients lists every organisation: member chips with roles, project count, outstanding balance (red if they owe). Invite a member V1C with their role and switches: approve / billing / invite.

3.1Connecting the database — click by click, ~10 minutes

1. Go to supabase.com and sign in.
2. Click New project.
3. Name it valtrin-portal. Region: Southeast Asia (Singapore). Set a strong database password and save it in a password manager. Click Create new project, wait ~2 minutes.
4. Left menu → Project Settings (gear) → API. Keep this tab open. Three values: Project URL, the anon public key, the service_role key.
5. On the PC, open the portal folder of the project.
6. Copy .env.example, paste it in the same folder, rename the copy to exactly .env.local.
7. Open .env.local in Notepad and paste each value after its = sign:
   • NEXT_PUBLIC_SUPABASE_URL= ← Project URL
   • NEXT_PUBLIC_SUPABASE_ANON_KEY= ← anon public
   • SUPABASE_SERVICE_ROLE_KEY= ← service_role
8. Save and close. This file is git-ignored — keys can never end up in the repository.

3.2Creating the database tables

1. In Supabase: SQL Editor → New query.
2. On the PC open portal\supabase\migrations\0001_schema.sql in Notepad. Press Ctrl+A then Ctrl+C.
3. Click into the Supabase query box, Ctrl+V, click Run.
4. Wait for Success. No rows returned.
5. Repeat for 0002_rls.sql, then 0003_storage_functions.sql — in this exact order. 0001 builds the tables, 0002 the security walls, 0003 the file store and helpers.

3.3Creating the first two users

1. Supabase → Authentication → Users → Add user → Create new user.
2. User one: the staff email, set a password, tick Auto Confirm User, create.
3. User two: the client contact’s email, the same way.
4. Each user row shows a long ID (UUID). Copy the staff UUID.
5. Open portal\supabase\migrations\0004_seed.sql in Notepad. Near the top, replace the placeholder after calvin_id with the staff UUID and after client_id with the client’s. Save.
6. Run 0004_seed.sql in the SQL Editor like the others — it loads the live engagement, phases, invoices, and the open request.

3.4Switching onto real data

1. Restart the portal:

   cd portal
   npm run dev

2. Open the portal address. The bronze Preview mode banner is gone — that is how you know it is live.
3. Sign in with the staff account — you land on Admin with real data.
4. Sign out, sign in as the client user — confirm they see only their own project, no INTERNAL items, no margins. Repeat this two-minute check whenever security rules change.

3.5Preview mode, explained

1. With no keys and a dev server, the portal fills itself with labelled sample data and signs you in as Super Admin — the bronze banner is the tell.
2. A deployed build without keys shows a setup card instead. Preview can never leak to the public.
3. You never switch it on or off — it follows the keys automatically.

3.6Day-to-day operations & troubleshooting

1. Start the portal: npm run dev inside the portal folder.
2. Start this website locally: node serve.js website inside the project folder.
3. Portal “down”? 99% of the time the server just isn’t running — run step 1.
4. Page shows the setup card? Keys missing or mistyped in .env.local — recheck 3.1, restart.
5. Can’t sign in? Use Forgot password, or reset the password in Supabase → Authentication.

3.7Going public

1. Push the portal repository to GitHub (private).
2. In Vercel: Add New Project → import the repo.
3. Vercel project → Settings → Environment Variables → add the same three keys from 3.1. This is the only place they live outside the PC.
4. Deploy, then point the DNS record portal.valtrintechnologies.com at Vercel as instructed.
5. Supabase → Authentication → URL Configuration → set the site URL to https://portal.valtrintechnologies.com so password-reset emails link correctly.

3.8The rules that protect the business

1. The audit log is append-only for everyone — including the super admin. Never “fix” history; append a correction. An untouchable log is what wins a dispute.
2. The service-role key is radioactive. If it ever touches a chat, screenshot, or client machine: Supabase → Settings → API → regenerate, then update .env.local and the host.
3. Never run the seed against production once real data exists.
4. No manual database edits in production. Go through the app, or keep the SQL that was run so the change is traceable.
5. Numbering is sacred. Invoice / project / change-order numbers are generated atomically per KL year — never hand-type one.