What is JKO Audit Solutions?

1.1 In one paragraph

JKO Audit Solutions is an end-to-end audit working-paper platform that ships as a single self-contained HTML file and runs in any modern browser. It is built for Ghana SME audit firms — the kind that audit limited liability companies, NGOs, schools, churches, MFIs, rural banks and small listed entities under ICAG oversight — and it walks a team through every stage of an ISA-aligned audit, from the first client-acceptance interview to the final signed financial statements, without ever leaving the browser. An optional Cloudflare-hosted backend layers on multi-device sync, a server-held AI key, tamper-evident audit logging, e-mailed welcome packs, and SaaS subscription billing through Paystack.

1.2 Who it's for

JKO is opinionated about its audience. It is designed for:

• Audit firms registered with ICAG — sole-practitioner setups all the way up to firms with several partners and dozens of staff. The pricing model (one base fee, a per-extra-user uplift) is sized for that range.
• Engagements that follow the ISA / IFRS / IFRS for SMEs framework, with optional add-ons for Ghana Tax (GRA-style audits), Bank of Ghana / Basel III work, and US SOX / ICFR engagements.
• Mixed-experience teams, where a partner reviews and signs off, managers oversee, seniors prepare working papers, and juniors run targeted fieldwork. Each role sees a different version of the app — the same file, four different views.

It is not intended for: very large international firms with bespoke engagement-management systems, audits performed under non-ISA frameworks (e.g. PCAOB-only) without enabling the SOX module, or pure bookkeeping work — JKO Books is a separate product for that.

1.3 How it ships

JKO ships in two layers, and you choose how much of the second layer you want.

Cloud-mode and local-mode are not mutually exclusive — if connectivity drops, the app silently falls back to local mode and re-syncs when the backend comes back. You never lose work because of a flaky connection.

1.4 The audit lifecycle, in JKO's own words

The sidebar is the canonical map of what JKO covers. Reading it top-to-bottom is the lifecycle:

1. Engagement — Client Progress View, Audit Workflow, Dashboard, Client Acceptance (Sections A–G with DD, AML, board appointment, EQR), Engagement Setup (Optional Modules, Team Assignment, Materiality, Trial Balance, Chart of Accounts).
2. Planning — Risk Assessment (IR × CR matrix, ABCOTD scoping, fraud flags), Analytical Procedures (ISA 520), Statistical Sampling (ISA 530), Ghana Tax Audit (when enabled), Banking Audit (when enabled), SOX / ICFR Audit (when enabled).
3. Fieldwork — Working Papers (risk-linked, sign-off controls), File Assignments & Review Monitor, Exceptions Log, Disclosure Checklist (26 frameworks).
4. Completion — Completion (misstatement schedule, EQR gate, going concern, subsequent events), Management Letter, Audit Report (with Final Signed AFS upload).
5. Administration — Time & Fees Tracker, Billing Centre (cross-engagement WIP, fee notes, invoicing, AR aging), Project Finance & P&L.
6. File Management — Archive, Permanent Audit File (survives engagement switches), Temp Working Folder (cleared on New Engagement).
7. Team — Admin Panel (Partner only), Team Profiles & CPD, Pending Submissions queue.
8. Quality Management — ISQM 1 / ISQM 2 / ISA 220 compliance review (66 quality objectives, annual SoQM sign-off).
9. Audit Procedures — Risk Identification, Audit Procedures, Journal Entry Testing (ISA 240), Lease Analysis (IFRS 16).

Each sidebar entry has a status dot that lights up as you complete that page. The topbar shows an overall progress bar for the active engagement.

1.5 What's in scope, what isn't

In scope — everything you need to take an engagement from acceptance to a signed audit report:

• Client acceptance & continuance (DD, AML, integrity, EQR appointment)
• Engagement letter generation
• Materiality calculation (four bases) and trial-balance management
• Risk assessment with COSO / ABCOTD scoping
• Analytical procedures with industry benchmarks for major Ghana sectors
• Statistical sampling (MUS or random)
• Working papers per assessed risk area, with preparer / reviewer sign-offs
• Disclosure checklist across 26 frameworks (IFRS, IFRS for SMEs, Ghana Companies Act, Ghana Tax, IESBA, AML, GDPR and more)
• Misstatement schedule, management letter, audit report, AFS upload
• ISQM 1 / 2 / ISA 220 quality reviews with annual SoQM attestation
• Project finance & cross-engagement P&L
• Time tracking, billing centre, AR aging
• AI-assisted lease extraction, risk commentary, ISQM commentary, audit-report polishing

Not in scope — JKO is a working-paper platform, not a general-ledger system. It does not:

• Replace your client's accounting software (you import their TB; you don't post journals on their behalf).
• File returns with GRA, RGD, or any regulator. The Ghana Tax Audit module documents the audit; it does not submit anything.
• Provide tax-computation advisory beyond the Tax Position Letter (AI-assisted draft).
• Maintain a CRM of prospects — the client list is engagements you are auditing, not leads.
• Replace ICAG's CPD portal, though Team Profiles & CPD records what your staff have logged.

1.6 What success looks like, by role

Read this section as "how do I know JKO is being used properly in my role?"

If your day-to-day looks like the row for your role, JKO is doing its job.

Getting started

This section is a click-by-click first-run walkthrough. Everything you see on screen is named here exactly as it appears in the app.

2.1 Opening the file for the first time

1. Save JKO_Audit_Solutions.html (or whichever versioned filename your firm distributes — e.g. JKO_Audit_Solutions_GH_v4_3.html) into a stable location on your device. Documents/JKO/ is the convention. Do not keep it on the desktop or in Downloads — those folders get cleared more often than people remember.
2. Double-click the file. It opens in your default browser.
3. Use Google Chrome or Microsoft Edge. Firefox works but is not the primary test target. Internet Explorer is not supported. Safari is untested and will likely have minor styling quirks.
4. Do not open the file in an Incognito / Private / InPrivate window. Browser storage is wiped when those windows close, which means every account you create and every working paper you save will be lost the moment the tab shuts. The app shows a yellow "⚠️ Browser storage is blocked" warning when this happens — heed it.
5. The app boots into the JKO Audit Solutions auth screen. The diagnostic line at the bottom of the auth card briefly says "Checking storage…" and then disappears once the app verifies it can write to localStorage.

2.2 The auth screen, in detail

The first screen has three switchable forms. Which one you see first depends on whether any account exists on this device.

a. Sign In (default when one or more accounts exist) - Username — the username you chose at signup, lowercased (the app forces lowercase silently). - Password — the password you set. - Sign In → button. Pressing Enter in either field is equivalent. - If the device already has accounts, a faint "Accounts on this device:" line appears below the button listing every username on file — handy when several team members share a workstation. - Two links sit at the bottom: ➕ Create new account (switches to the Create Account form) and 🔑 Forgot / Reset account (opens the Reset form).

b. Create Account (shown automatically on a fresh device, or when you click "Create new account")

This is where the Partner is born. The first account on a device is always a Partner — JKO has no separate "register as Manager" path; managers and below are added later by the Partner from the Admin Panel.

Click Create Account →. If anything fails validation, a red banner appears at the top of the card with a specific reason ("Password must contain at least one letter", "Username … already exists", etc.) — fix it and retry.

Note on the placeholder text — the input placeholder says "At least 6 characters" but the validator is stricter. If your password meets the actual rules above, you're fine; if you only type 6 characters you'll be rejected.

c. Reset Account (the 🔑 link)

This is the nuclear option. It deletes every account record on this device so a Partner can re-create the firm from scratch — useful when a junior has left and you want to wipe their saved login, or when a workstation is being handed to a new owner. You must type RESET (capitals) into the confirmation box before the red "Delete All Accounts & Start Fresh →" button will fire.

Important: Reset deletes login credentials, not audit data. Engagement state, working papers, the Permanent Audit File and the Temp Working Folder all stay intact in localStorage. After reset you'll create a new Partner and your existing engagements will reappear under that account.

2.3 The first sign-in — what you actually see

After you click Create Account → (or sign in for the first time), the auth card is replaced by the full app. You land on the Client Acceptance page (not "Engagement Setup" — that comes second). Take 30 seconds to orient before doing anything.

The sidebar (left edge) — top to bottom:

• 📊 JKO Audit Solutions brand block with the strap "ISA-Aligned · IFRS for SMEs · Ghana Practice" and the version label.
• User badge — your initials in a coloured circle, your name, your role ("Partner"), a 🔑 (change password) button and a ⏏ (sign out) button.
• Active Client box — currently shows "—" because you haven't created an engagement yet. Once you do, the client name and a status badge ("Acceptance", "Fieldwork", "Completion"…) appear here.
• Section headers and nav items — Engagement, Planning, Fieldwork, Completion, Administration, File Management, Team, Quality Management, Audit Procedures. Each nav item has an emoji icon, a label, and a status dot on the right.
• Footer — 🤖 AI Assistant button, "Auto-saves · Last: —" indicator, three sync badges (💾 Supabase, 💾 Firebase, 🔐 Backend) which are dim until configured, an active-engagement indicator, and the ＋ New Engagement button.

The topbar (top of the main pane) shows the page title ("Client Acceptance"), a subtitle, a Progress bar with a percentage, a 🤖 AI Help button, 📧 Share Progress, 📤 Export Excel and a 🖨 print button.

The main pane itself currently shows the seven Client Acceptance sub-sections (A through G). You will fill these in for your first client once you've created an engagement record — which is the next step.

2.4 Creating your first engagement

JKO does not auto-create an engagement on signup. You make the first one manually.

1. Click the ＋ New Engagement button in the sidebar footer. (As a Partner, this routes through newEngagementFromPartner, which prompts you for a client name and creates the engagement record. As a Manager / Senior / Junior, it asks for confirmation that you want to wipe the current Temp Working Folder and clear the in-memory engagement.)
2. Enter the Client Name in the prompt — e.g. "Asda Seashore Limited". The current calendar year becomes the engagement year by default; you can change the year-end on the Acceptance page.
3. JKO saves whatever you had loaded before (so nothing is lost), creates a new engagement record, and switches to it. The Active Client box in the sidebar now shows the new client's name with a status of "Not Started".
4. The app keeps you on the page you were already on (most likely Client Acceptance). To begin engagement-level setup, click 📁 Engagement Setup in the sidebar.

2.5 Client Acceptance — the gate before materiality

Client Acceptance must be completed before you compute materiality or design any audit procedures. It is the integrity gate: if the client fails any of the gatekeeper checks (illegal independence position, failed AML, partner refuses to approve), the engagement should be declined and no further fieldwork happens. The default sidebar landing page right after sign-up is Client Acceptance for exactly this reason.

The page is laid out as seven cards, A through G, plus an Engagement Letter card at the bottom that unlocks only after Section G is signed YES.

Section A — Client Profile (red GATEKEEPER chip)

The client's identity. Legal name, registration number, TIN, registered office, year-end, principal activities, ownership chain (UBO disclosure), prior auditor (predecessor enquiry), and any regulatory registrations (BoG, NIC, SEC, GRA Large Taxpayer Office, etc.). Two of these — Client Legal Name and Registration Number — are mandatory and feed the unlock-checklist for Section G.

Section B — Independence Checklist (red Auto-Blocking chip)

Five independence factors per ISA 200 / IESBA Code: financial interest, family / personal relationships, recent employment with the client, fee dependence, advocacy / management threats. Each one is YES (independent) / NO (breach). The engagement auto-blocks if 3 or more breaches exist — JKO will refuse to let you sign Section G in that state.

Section C — AML / KYC (red All Must Be YES chip)

Four mandatory items: source-of-funds verified, sanctions screening completed, PEP check performed, identification documents on file. All four must be YES before Section G unlocks. This implements the firm's obligations under Ghana's AML Act.

Section D — Key Personnel Due Diligence

A roster of every director, ultimate beneficial owner and key management person, each with: name, role, ID type & number, date of birth, nationality, internet / media search summary, and a per-person risk rating (Low / Medium / High / Critical). At least one person must be added and screened, and no person may be rated Critical for the section to clear. The internet-search field is mandatory per person — leaving it blank counts as "unscreened" and blocks Section G.

Section E — Board of Directors Appointment

Records the board resolution that appointed your firm as auditor: resolution reference number, date, and a Partner Sighted toggle. The Partner must tick "Sighted" once they have personally seen the resolution document. Both a resolution reference and the Partner Sighted confirmation are required.

Section F — Risk Scoring

Six weighted risk factors (Integrity 0–100, Competence 0–100, Financial Stability 0–100, Regulatory 0–100, Industry 0–100, plus a Due Diligence sub-score that auto-populates from Section D). Note the scale: 0 is highest risk, 100 is lowest — this is deliberately the inverse of the IR×CR matrix you'll meet later in Risk Assessment, because Section F is asking "how trustworthy is this client?" not "how risky is the audit?".

The card computes a weighted total and a verdict band (Low / Moderate / High / Decline-recommended).

Section G — Partner Sign-Off

The ultimate gate. The card shows a live unlock checklist:

• ⬜ Client Legal Name entered (Section A)
• ⬜ Registration Number entered (Section A)
• ⬜ All 4 KYC/AML items set to YES (Section C)
• ⬜ Fewer than 3 independence breaches (Section B)
• ⬜ Key personnel added & due diligence completed — no Critical ratings (Section D)
• ⬜ Board resolution referenced and sighted by partner (Section E)
• ⬜ Partner Approval set to YES (Section G)

Each box ticks green as the underlying condition is met. When all seven are green, you can switch the Partner Approval dropdown to YES and the engagement is officially accepted. The Engagement Letter card unlocks immediately and an auto-generated draft (using captured Section A data) appears for the partner to review, edit and finalise.

The Save & Continue rail at the bottom of the page offers Save & Continue → Engagement Setup. You should only click this once Section G is YES — moving on without acceptance means you would compute materiality and design procedures for a client you haven't formally agreed to audit. The app does not strictly block this navigation (the lock that previously enforced it was removed), but every downstream page assumes acceptance is complete.

2.6 The Engagement Setup page, card by card

The Engagement Setup page is a stack of cards. You don't have to fill them top-to-bottom, but that is the order that makes sense.

Card 1 — Optional Modules (purple left border)

Three checkboxes, each one toggling a specialised module on or off for this engagement only. Toggling a checkbox immediately adds or removes the matching sidebar entry and includes/excludes that module from progress tracking and exports.

• 🏛️ Ghana Tax Audit Module — opt in only when the engagement is subject to a GRA tax audit under the Income Tax Act 2015 / VAT Act.
• 🏦 Banking Audit (Bank of Ghana / Basel III) — for licensed financial institutions. Adds CAR / NPL / LCR / NSFR calculators, single-obligor and insider-lending tracker, IFRS 9 ECL staging, AML transaction sampling.
• 🇺🇸 SOX / ICFR Audit Module — for US-listed entities and accelerated filers. Adds Section 302 / 404 attestation tracker, COSO 2013 five-component assessment, ICFR walkthrough log, material-weakness register, audit-committee independence checklist.

For a typical Ghana SME audit you leave all three off.

Card 2 — Engagement Team Assignment (navy left border)

Lists your team roster (drawn from getUsers() — i.e. accounts in the Admin Panel) and lets you assign team members to specific audit areas. Junior and Senior staff only see the audit areas they are assigned to here.

• A status badge in the top-right shows ⏳ Awaiting Partner Approval until the Partner clicks ✅ Partner Approve Team, after which it turns green.
• 🔄 Refresh Team re-pulls from the user list (use after adding a new team member from the Admin Panel).
• 👤 Manage Users jumps to the Admin Panel.
• 📥 Import Handoff Package lets you ingest a .json file produced by another team member's "handoff" export — useful when a senior is taking over an area mid-engagement.

Card 3 — Materiality Calculator (with an "Auto-Calc" green chip)

Five inputs, four basis options, three computed outputs.

Three boxes update live as you type: - Planning Materiality — basis × percentage. - Performance Materiality — 75% of planning materiality. - Clearly Trivial — 5% of planning materiality (the threshold below which misstatements are not posted to the Misstatement Schedule).

Every keystroke triggers an autosave (800 ms after you stop typing).

Card 4 — Trial Balance

A blue info banner at the top reminds you: Use Tab to move between cells. Debits and Credits must balance before proceeding.

The card has two sub-areas:

• Chart of Accounts (COA) panel — collapsible. Click the header bar to expand. You can drag-drop or click-upload an .xlsx, .xls or .csv with columns Code, Name, Type (Asset / Liability / Equity / Income / Expense) and optionally Lead Area. After import, three buttons appear: 🔗 Auto-Map Lead Areas to TB (assigns Lead Area to each TB row by code lookup), 🔍 Appraise TB vs COA (flags TB lines whose code is missing from the COA, and COA lines that don't appear in the TB), ✕ Clear COA.
• Trial Balance entry — drag-drop or click to upload an Excel/CSV with columns Code, Name, Debit, Credit, or click + Add Row to enter rows manually. Each row also captures Prior Year (GHS), the auto-computed Net, and a Lead Area dropdown. Tab moves between cells.

Three buttons sit above the table: - + Add Row — appends an empty row. - 🔍 Check Balance — runs the totals. A green "Trial Balance is BALANCED" banner appears below the table when totals match; a red "NOT BALANCED. Difference: GHS …" banner when they don't. - 📥 Download Setup Excel — exports the current TB plus materiality inputs.

The footer of the table shows live TOTALS (Debit / Credit / Difference). The difference number is green when zero and red otherwise.

2.7 Save & Continue rail

At the bottom of every workflow page is a thin sticky bar with a 💾 Save Progress button on the left and a Save & Continue → [next page] button on the right (and ← [previous page] when there's a previous step). On Engagement Setup the next-step button is Save & Continue → Risk Assessment.

You don't have to use these — every change autosaves anyway — but the explicit click also pushes you forward in the workflow, which is the path of least resistance for new users.

2.8 Switching between engagements

Once you have more than one engagement, the Active Client box in the sidebar is the entry point.

1. Click the client name in the Active Client box. The Engagement Manager modal opens, listing every engagement in the firm sorted by recency.
2. Each row shows the client name, year, current status (Acceptance / Setup / Fieldwork / etc.), progress %, partner / manager initials, risk level and any exception count.
3. Click 🔄 Switch To on the engagement you want. JKO pops a confirmation ("Switch to … ? Your current work is automatically saved — no data will be lost.") — confirm and the app flushes pending saves synchronously, verifies the save was written, then loads the target engagement's full state.
4. To create another engagement from the modal, use the ＋ New Engagement button at the top of the list (Partners) or close the modal and use the sidebar footer's button.

If you want to start a fresh engagement without going through the modal, click ＋ New Engagement in the sidebar footer directly. Non-Partner staff get a confirmation dialog warning them that the current Temp Working Folder will be cleared (the Permanent Audit File is preserved). Partners go straight to the client-name prompt.

2.9 What to do next

You now have: - A signed-in Partner account on the device. - A first engagement record with a client name and year. - A completed Client Acceptance file (Sections A–G with Partner Approval = YES) and an unlocked Engagement Letter. - (Optionally) any specialised modules toggled on for this engagement. - (Optionally) a team assigned and partner-approved. - A planning materiality figure (and performance materiality at 75%, clearly trivial at 5%). - A balanced trial balance, optionally COA-mapped.

The natural next step is Risk Assessment — click the Save & Continue → Risk Assessment button at the bottom of Engagement Setup, or ⚠️ Risk Assessment in the sidebar's Planning section. From there, the workflow is linear: Risk → Analytical → Sampling → Fieldwork → Completion → Reporting. Each subsequent section of this manual takes one of those stages and breaks it down with the same depth as §2 broke down getting started.

Subscription & billing

JKO is a yearly subscription. Payment is taken through Paystack, which means clients can pay by card, Ghana Mobile Money (MTN, Vodafone, AirtelTigo), or bank transfer through the same checkout. The subscription is per-firm, not per-engagement — once a firm is paid, every active user signs in against the same licence.

This section is laid out so you can find the answer to the three questions a Partner actually asks: what does it cost?, how do I pay it?, and what happens if I don't?.

3.1 The pricing model in plain English

JKO billing has three components. The first is fixed for your firm; the other two are billed separately based on usage and scope.

A user is counted as "active" if their account in the Admin Panel has the Active checkbox ticked. Deactivating a user (un-tick the box) immediately removes them from the next quote — they no longer count toward the headcount.

For the firm's actual annual licence figure at any time, open the Subscription card in the Admin Panel — the live quote always reflects your current Active-user count.

3.2 Where the Subscription card lives

The card lives in the Admin Panel (Partner only — sidebar entry ⚙️ Admin Panel) under the heading 💳 Subscription & Billing, with a green left-border. The strap line reads "Annual subscription · Paystack · Renew before period end to avoid read-only grace". A 🔄 Refresh button sits in the top-right of the card; click it any time you've made a payment in another tab and want to pull the latest status.

If you have not yet connected the cloud backend, the card shows an amber "⚠️ Sign in via the backend first." panel and no other content. The subscription engine lives on the backend — it is not available in pure local mode.

3.3 Reading the status banner

Once the card has fetched your subscription, the top of the card shows a coloured banner. The colour is the tell.

Below the banner the card shows the firm's name and firm ID (the latter is the key you quote when contacting JKO support).

3.4 The free trial

Every new firm gets 30 days free with full features, no card required. The trial is created automatically the first time a Partner registers the firm with the backend — there is no separate "start trial" button.

The Subscription card's banner is the canonical countdown. The number in brackets ("X days remaining") refreshes each time you load the page or click 🔄 Refresh. There is no email warning when the trial nears expiry — keep an eye on the card if you're approaching day 25.

3.5 The live quote, line by line

Below the banner the card renders a small 📋 Annual Licence Quote table that always reflects the firm's current Active-user count. It has four rows:

• Base licence — the flat fee that covers the included headcount.
• Active users in firm — your current Active-checkbox count.
• Extra users — count beyond the included base × per-extra-user uplift, if any.
• Total payable now — the figure that will appear on the Paystack confirmation in the next step.

The yellow callout under the table reminds you what is excluded: Anthropic API consumption (passed through at cost) and servicing / on-call support charges. Those are the AI API and Installation & Support components from §3.1 — not part of the licence fee.

3.6 Activating or renewing

The action button 💳 Pay / Renew Annual Licence appears under the quote when you are signed in as a Partner or Manager. Senior and Junior accounts do not see this button — they can read the status banner but cannot initiate payment. Either Partner or Manager can pay the renewal — useful when the Partner is unreachable around expiry.

1. Click 💳 Pay / Renew Annual Licence. A confirmation dialog appears with the exact figure for your firm: "Confirm payment of [amount] for the annual licence ([N] active users — base covers [included headcount], extras: [k])? You will be redirected to Paystack to complete payment." The bracketed values are filled in live from the quote on the Subscription card.
2. Confirm. A toast says "Redirecting… Opening Paystack checkout."
3. You're handed off to Paystack. Choose card / MoMo / bank transfer. Complete the payment.
4. Paystack returns you to the app at the same URL you started from. The Subscription card auto-refreshes within ~30 seconds; if it doesn't, click 🔄 Refresh.
5. The banner turns green with the new period end (365 days from payment).

3.7 Renewal extends, it does not reset

If you renew before your current period ends, the new period is added to the existing one — you don't lose the days you already had. You can renew at any point from the same Subscription card; the quote will simply add another 365 days to your current expiry.

If you renew after the grace period (already in red Expired state), the new period starts on the day you pay — you lose whatever calendar gap you let elapse.

3.8 What happens if you don't renew

The lifecycle from the day a paid subscription ends:

• Day 0 (expiry day): the banner turns amber and the subscription enters a 14-day grace period. The app is read-only — you can sign in, view every working paper, export Excel — but new saves and AI calls are blocked at the backend.
• After 14 days: full lockout. The banner turns red ("Expired"). Sign-in still works, but every authenticated backend call returns HTTP 402 Payment Required until a Partner renews.
• Local-mode is unaffected. If you previously used the HTML in pure offline mode (no backend connected), you're not subject to the subscription gate at all — but you also don't get cloud sync, server-side AI, the tamper-evident audit log, or the team-collaboration features. Most firms outgrow local mode within a month.

3.9 How the licence quote scales

The annual licence amount scales linearly: the base fee covers the included headcount, and each Active user beyond the base adds the per-extra-user uplift. There is no banding, no discount tier, and no minimum commitment beyond one year.

The Subscription card always shows your actual quote based on your real Active-user count — there is no need to compute it by hand. For a firm-specific quote outside the app (e.g. before signup), contact JKO Audit Solutions support.

3.10 What's included vs what's separately billed

Included for every active user:

• Unlimited engagements per firm
• Cloud sync (R2-backed multi-device)
• Server-stamped, hash-chained tamper-evident audit log
• AI: lease extraction, risk commentary, ISQM commentary, audit-report enhancement, free-form Assistant
• Multi-framework disclosure checklist (26 frameworks)
• Project finance & cross-engagement P&L
• Billing Centre (cross-engagement WIP, fee notes, invoicing, AR aging)
• ISQM 1 / 2 / ISA 220 quality reviews
• Ghana Tax Audit module (optional toggle)
• Banking Audit / SOX modules (optional toggles)
• Email-delivered welcome packs (when Resend is configured)
• Firm-wide data export (regulator inspection / portability)

Billed separately:

• Anthropic API consumption — passed through at the prevailing Anthropic rate. Varies by usage.
• Servicing & on-call support — quoted per firm based on engagement volume and SLA expectations.
• Custom integration / on-site training — quoted on request.

3.11 Common payment mistakes

• "Why does my quote show 11 users when I only have 10 staff?" — your own Partner account is also a user. The 10-user base covers everyone, including the Partner.
• "I deactivated a leaver, but the next quote still includes them." — the quote uses Active accounts at the moment the Pay button is pressed. If your card is showing a stale figure, click 🔄 Refresh and recompute.
• "I paid but the banner didn't turn green." — give it 30 seconds (the backend reconciles the Paystack webhook asynchronously) then click 🔄 Refresh. If it's still amber/red after a minute, contact JKO support with your firm ID.
• "I'm a Manager and I can't see the Pay button." — Managers can now see and click Pay / Renew Annual Licence. If the button is missing for a Manager, the cause is almost always one of: (a) you're signed in via local mode rather than the cloud backend (the subscription engine lives on the backend); or (b) the subscription card is in "No subscription found" / loading state. Refresh the card with 🔄.

Account roles & permissions

JKO has four roles, hard-coded in the Add Team Member dropdown. You cannot invent custom roles, and there is no per-page permission editor — the role chosen at account creation is the access boundary, full stop. This keeps the security model boring on purpose: a Partner reading the manual can predict exactly what every team member can and can't see.

4.1 The four roles, side by side

The dropdown in the Add Team Member modal shows: Partner, Manager, Senior Auditor (stored as Senior), Junior Auditor (stored as Junior). The default selection for a new account is Senior Auditor.

A few practical implications:

• Either a Partner or a Manager can save your firm from a 402 lockout. Both roles can hit Pay / Renew Annual Licence; Senior and Junior cannot. If only Junior staff are on duty when the subscription lapses, the firm is read-only until a Partner or Manager signs in.
• Senior and Junior look identical to a casual observer. The difference is mostly UI strictness around non-fieldwork pages: Junior sees fewer sidebar entries. Both are scoped to assigned audit areas.
• Manager is the "operationally trusted, not legally responsible" tier. They can do everything you'd expect a senior reviewer to do, but they don't sign anything that carries Partner risk (acceptance, opinion, ISQM).

4.2 Adding a team member — the click-by-click

This entire flow is Partner-only.

1. Sidebar → ⚙️ Admin Panel. The panel scrolls through several cards; you want the Team Members section.
2. Click ＋ Add Team Member. A modal titled Add Team Member opens.
3. Fill in the modal:

4. Click 💾 Save Member. Validation runs. If the password is too weak the toast says "Weak Password" with a specific reason. If the username is taken the toast says "Username already taken." Otherwise the user record is created with mustChangePassword = true and an entry is written to the audit log (USER_CREATE).

5. The Welcome Pack modal opens automatically. This is the new team member's onboarding kit. (Detail in §4.3.)

4.3 The Welcome Pack modal

A dark-blue header titled 📧 Welcome Pack — [Member Name] with the strap "Email a copy of the audit software + login details". The body of the modal has three blocks:

Block 1 — LOGIN DETAILS (light-blue panel, monospaced):

Username:            aowusu
Temporary password:  Q7rk9!nXp2
Role:                Senior
Email:               aowusu@firm.com
🔑 The user will be forced to change this password on first login.

This is the only time the temporary password is shown in plaintext — write it down or copy it now.

Block 2 — How to share access (yellow callout):

1. Click ⬇ Download Audit Software below — saves the app as an HTML file.
2. Click 📧 Compose Email — opens your email client with the welcome message
   pre-filled.
3. Attach the downloaded HTML file to that email and send.
4. The team member opens the file in Chrome and logs in.

Block 3 — three action buttons:

There is also a Close button. The modal does not auto-dismiss — close it only after you've successfully shared access, because once it's gone the temporary password will not be shown again.

If your firm has the Resend integration configured on the backend, the welcome email is sent automatically to the address in the Email field, with login credentials and the "must change password on first login" notice already embedded. The Welcome Pack modal still appears as a backup / for manual sharing.

📧 Welcome Pack — Ama Owusu

Email a copy of the audit software + login details

Username: aowusu

Temporary password: Q7rk9!nXp2

Role: Senior

Email: aowusu@firm.com

🔑 The user will be forced to change this password on first login.

How to share access:
1. Click ⬇ Download Audit Software — saves the app as an HTML file.
2. Click 📧 Compose Email — opens your email client with the welcome message pre-filled.
3. Attach the downloaded HTML file to that email and send.
4. The team member opens the file in Chrome and logs in.

⬇ Download Audit Software 📧 Compose Email 📋 Copy Welcome Message Close

Figure 4.3 — The Welcome Pack modal that opens automatically after Save Member. The temporary password is shown only here in plaintext — copy it before closing. With Resend wired to the backend, the email is also auto-sent.

4.4 Forced password change on first login

When a user with mustChangePassword = true signs in, the Change Password modal appears immediately and cannot be dismissed without setting a new password. The fields are:

• Current password — the temporary password the Partner gave them.
• New password — must satisfy the same validator (8+ chars, letter, digit, no whitespace, not common, and different from the current password).
• Confirm new password — must match.

On success the flag is cleared, an audit-log entry is written (PASSWORD_CHANGE), the toast says "✅ Password Updated · Your new password is now active.", and the user lands on whichever page their role would normally land on.

The same forced-change behaviour fires after a Partner-initiated password reset (see §4.6).

4.5 Self-service password change

Any signed-in user can change their own password without going through a Partner.

1. Sidebar user badge → 🔑 icon (next to the ⏏ sign-out button, top of the sidebar).
2. The Change Password modal opens.
3. Enter the current password and the new password (twice).
4. Click Change Password.

In backend mode the change is sent to the backend, which revokes every refresh token belonging to the user — so every other device they're signed in on is bounced to the login screen on its next request. The current device is also signed out and reloaded after a 1.5-second toast. This is deliberate: changing your password should kick out anyone with a stale session.

In local mode only the local user record is updated and the current session is refreshed in place; other devices (if any) keep their existing session until it naturally expires.

4.6 Partner-initiated password reset

When a team member forgets their password, the Partner does this from the Admin Panel.

1. Admin Panel → Team Members table → row for the user → 🔑 Reset Password action.
2. A confirmation dialog explains exactly what's about to happen: Reset password for "aowusu"? This will: • Generate a new temporary password • Sign the user out of every device • Force a password change on next login You will see the new temp password ONCE — copy it then.
3. Confirm. A modal appears showing the one-time temporary password in monospace. Copy it now — the modal stresses that this is the only time it will be displayed.
4. Communicate the temporary password to the user through a trusted channel (in person, phone call, separate-channel message — not the same email thread you might be CCing colleagues on).
5. On their next login, the user is forced into the Change Password flow described in §4.4.

The reset writes an audit-log entry (USER_UPDATE … "password reset") so there is a permanent record of who reset whose password.

4.7 Deactivating, removing, demoting

Three different ways to take someone out of the firm, with different consequences.

Safety rails the app enforces:

• You cannot deactivate yourself. The Active checkbox is greyed out on your own row, with the tooltip "Cannot deactivate yourself".
• A Partner cannot demote themselves. The Role dropdown is greyed on your own row when you're a Partner, with the tooltip "Cannot demote yourself". To step down, promote another user to Partner first, then have them demote you.
• You cannot remove your own account. A toast fires: "You cannot remove your own account."

These rails prevent the classic "last admin locked themselves out" failure mode.

4.8 Audit-log trail

Every account-management action goes into the hash-chained audit log:

The audit log is append-only and tamper-evident — verifyAuditLogIntegrity() will detect if someone has rewritten history. ICAG inspectors can ask for the full log via the firm-wide data export.

Working with engagements

An "engagement" in JKO is a self-contained record of one client's audit for one financial year. Every page in the app — from Acceptance through to AFS upload — operates on the currently-active engagement, identified by an internal ID like eng_1714299034812 (a millisecond timestamp prefixed with eng_). The Active Client box at the top of the sidebar tells you which engagement is loaded right now.

This section covers the lifecycle, the auto-save model, the multi-engagement registry, and the two file-folder types.

5.1 The lifecycle as a state machine

The audit lifecycle has eleven sidebar pages between acceptance and final sign-off. The flow:

Client Acceptance → Engagement Setup → Risk Assessment → Analytical Procedures →
Statistical Sampling → Working Papers → Exceptions Log → Disclosure Checklist →
Completion → Management Letter → Audit Report → (AFS upload)

Specialised modules (Ghana Tax, Banking, SOX) appear in the Planning band when toggled on; they sit alongside the standard pages, not in the linear chain.

Stages are navigationally free but logically sequenced. You can click any sidebar entry at any time — there is no hard lock between pages — but each downstream page assumes the upstream pages have been done. Visiting Risk Assessment before completing Engagement Setup, for example, will show a "Complete Engagement Setup first" placeholder where the lock screen used to be in earlier versions.

Status dot beside each sidebar entry lights up as that page reaches completion: ⭕ grey for not started, 🟡 amber for in progress, 🟢 green for complete. The topbar Progress bar in the active engagement is the average of these dots.

The engagement record itself carries a status field on the registry entry — acceptance / setup / fieldwork / completion / signed — which is what the Engagement Manager modal sorts by. This is the same status badge that appears next to the client name in the Active Client sidebar box.

5.2 Auto-save in detail

Every change to a JKO field triggers a debounced save 800 milliseconds after you stop typing or interacting. The mechanism:

1. The change handler calls autoSave().
2. autoSave() clears any in-flight save timer and starts a new 800 ms timer.
3. If you keep typing, the timer keeps resetting — no save fires until you've been idle for 800 ms.
4. When the timer fires, JKO captures every field on the current page plus the in-memory engagement state (TB rows, risk rows, exceptions, misstatements, sample points, materiality figures, all 26 disclosure-framework tables, working-paper status and content, COA rows, COSO scores, control-environment scores, and more).
5. The complete snapshot is serialised to JSON and written to two localStorage keys: - sme_audit_v2 — the "current engagement" pointer (always overwritten with the live state) - do_audit_eng_<engagementId> — the per-engagement archive (so switching back later restores exactly what you had)
6. The "Last saved" indicator updates in two places: the bottom of the sidebar footer (HH:MM:SS) and the top of any page that has the secondary indicator.

Side effects that fire after auto-save:

• Engagement registry sync at 1.5 s — syncEngagementMeta() updates the engagement record (last-updated timestamp, progress %, exceptions count, partner name, etc.) so the Engagement Manager modal stays current.
• Local folder save at 1.5 s — if you have set up a save folder via the File System Access API and the auto-save toggle is on, a .json backup is dropped into that folder.
• Backend push at 2 s — if the cloud backend is connected and active, the engagement blob is PATCHed up to R2.
• Firebase / Supabase push if those sync destinations are configured.

What this means in practice: you almost never have to think about saving. The 💾 Save Progress buttons on each Save & Continue rail are convenience — the underlying autosave has already fired. They show a toast ("Saved · Progress saved.") so you have visible confirmation before navigating away.

What is not auto-saved:

• Files in the Temp Working Folder and Permanent Audit File — these go straight to localStorage as they're uploaded, not via autoSave.
• Anything in the AI panel transcript — chat history is session-only.
• Field changes made to other engagements — JKO only saves the currently loaded engagement; switching is what flushes the old state to its archive key.

5.3 The multi-engagement model

A single device, a single firm, but as many engagements as you need. JKO maintains an engagement registry (a list of all engagement records with metadata) and per-engagement state archives. There is no upper limit — firms with dozens of concurrent engagements run them all out of the same HTML file.

Active Client box (top of the sidebar) shows:

• The currently-loaded client name (e.g. "Asda Seashore Limited")
• A status pill: "Not Started", "Acceptance", "Fieldwork", "Completion", "Signed"

Clicking the client name opens the Engagement Manager modal (see §2.7) with the full list, sorted by recency, with a 🔄 Switch To button on each row.

Switching is atomic:

1. JKO calls saveCurrentEngagementNow() to flush every pending debounced timer synchronously.
2. It verifies the save was written by reading the per-engagement key back.
3. If the verify fails, a toast fires ("Save Error · Could not verify save. Please try again.") and the switch is aborted — no data loss.
4. Otherwise the new engagement's state is loaded from its do_audit_eng_<id> archive into sme_audit_v2, the current-engagement pointer is updated, and the page reloads.

Concurrent editing of the same engagement on two devices is detected on the backend by version numbers; the loser sees a "Version conflict" message and is bounced into the Pending Submissions queue (§16.10).

Footer engagement indicator — a tiny 📁 [client name] line near the bottom of the sidebar reaffirms which engagement is loaded. If your sidebar is ever ambiguous (because two clients happen to have similar names), this is the second confirmation.

5.4 Permanent vs Temporary file folders

JKO ships two distinct file folders with very different lifecycles. Pick the right one or you will lose work.

The Temp Working Folder shows a yellow alert at the top: "Files in this folder will be permanently deleted when you click 'New Engagement'. Download anything you want to keep before starting a new engagement."

If you accidentally clear the Temp folder by clicking ＋ New Engagement: there is no undo, but if you've configured a local-folder save destination (see §13.4) the JSON backup written before the clear contains your files in base64.

5.5 Renaming, archiving, and deleting an engagement

• Rename — change the client name on the Client Acceptance → Section A → Client Legal Name field. The Active Client box and the Engagement Manager modal pick up the new name on the next autosave.
• Archive — once the engagement is signed-off and Final AFS is uploaded, use File Management → Archive to capture a complete snapshot. Archives are permanent and survive ＋ New Engagement actions; they are read-only by design.
• Delete — there is no built-in "delete engagement" button in the standard UI (deliberate: audit records are append-only). To truly purge an engagement, a Partner uses the firm-wide data export to extract everything, then clears the per-engagement localStorage key from the Admin Panel maintenance card.

5.6 Engagement-switch quick reference

Planning section

The Planning band of the sidebar covers everything you do before fieldwork: who is this client (Acceptance), what are we auditing and against what (Engagement Setup), where is the risk (Risk Assessment), what does the data say at a 30,000-foot level (Analytical Procedures), and what should we test in detail (Statistical Sampling).

The first-run walkthrough for §6.1 and §6.2 lives in §2.5 and §2.6 respectively — this chapter assumes you've completed that and goes deeper into the parts that come up after the first engagement: the Engagement Letter, advanced setup flows, and the three pages this chapter introduces for the first time (Risk Assessment, Analytical Procedures, Statistical Sampling).

6.1 Client Acceptance — beyond the first pass

The seven Acceptance sections (A through G) and the unlock checklist are documented click-by-click in §2.5. This subsection covers what comes next.

6.1.1 The Engagement Letter card

Once Section G's Partner Approval flips to YES and all seven unlock-checklist boxes are green, an Engagement Letter card appears at the bottom of the Acceptance page. It is auto-generated from the data you captured upstream:

• Firm name and address (from Admin Panel → firm profile)
• Client legal name, registration number, year-end (from Section A)
• Engagement scope (statutory audit / GRA tax audit / combined — driven by the Optional Modules in Engagement Setup)
• Materiality basis (from Engagement Setup, if already populated)
• Fees and out-of-pocket reimbursements (from Project Finance & P&L, if populated)
• ISA 210 standard wording for partner / client responsibilities, going-concern, and management representations
• Signature blocks for the audit partner and the client director

The card has four actions:

• 👁 Preview — opens the letter in a print-friendly modal so you can read the full draft.
• ✏️ Edit — opens an inline rich-text editor; whatever you save here overrides the auto-generated paragraphs but the substitution placeholders (firm name, year-end, etc.) stay live.
• 🤖 AI Polish — sends the current draft through Claude with an "audit firm engagement letter" prompt and returns a tightened version. The diff is shown for accept/reject before it replaces the live text.
• 📥 Download — exports a .docx for the client to review and sign.

6.1.2 What if you re-open Acceptance after sign-off?

You can. Acceptance is not write-locked once signed. But:

• Editing any field in Sections A–F automatically clears Section G's Partner Approval back to "Pending" — the Engagement Letter card relocks, and the engagement returns to "acceptance" status in the registry.
• The audit log captures every revoke (USER_UPDATE event with subject acceptance:G).
• If fieldwork has already started, the Working Papers page does not clear — but the topbar progress bar drops back to reflect the lost approval.

This is deliberate: if a Partner spots a problem with acceptance halfway through fieldwork, JKO forces a fresh re-approval rather than letting the engagement quietly proceed on a stale gate.

6.1.3 EQR appointment

Section E captures the board appointment of the firm. The EQR (Engagement Quality Reviewer) appointment is a separate concept — captured during Engagement Setup → Team Assignment, where one team member is flagged as the EQR. The EQR cannot be on the engagement team for the same engagement (ISQM 2 independence). JKO does not enforce this in code; it shows a yellow warning if the same person is selected for both roles.

6.2 Engagement Setup — beyond the first pass

The four Engagement Setup cards (Optional Modules, Team Assignment, Materiality Calculator, Trial Balance) are walked through field-by-field in §2.6. This subsection covers the advanced flows.

6.2.1 The handoff package import

Click 📥 Import Handoff Package on the Team Assignment card to ingest a .json produced by another team member's "handoff" export. Use case: a senior is taking over an audit area mid-engagement and needs to absorb the previous senior's working papers, exceptions, and notes without re-keying.

The file format is a flat object with arrays for each carry-forward category: workingPapers, exceptions, samplePoints, assignmentNotes, plus a metadata header (fromUser, area, exportedAt). On import:

1. JKO validates the schema; rejects the file if fromUser is not on the current team or if area is not in the engagement's risk matrix.
2. A preview modal shows what will be merged, item by item, with checkboxes so you can deselect any line.
3. On confirm, items are appended (not replaced) to the live engagement state; an audit-log entry HANDOFF_IMPORT records the source, target, and item count.

6.2.2 Revoking partner approval of the team

Once the Partner ticks ✅ Partner Approve Team, the badge turns green and Junior / Senior staff begin to see only their assigned areas. To change the team after this point, the Partner clicks ↩ Revoke Approval (visible only to Partners, only after approval has been given).

Revoke does not clear the assignments themselves — it just lifts the gate. The badge returns to amber ⏳ Awaiting Partner Approval. Junior / Senior staff are immediately blocked from non-fieldwork pages again until re-approval.

The audit log captures both events (TEAM_APPROVE and TEAM_REVOKE) with the Partner's username.

6.2.3 COA appraisal — what the appraisal output actually says

After uploading a Chart of Accounts and clicking 🔍 Appraise TB vs COA, the COA panel below the table renders a results panel with three lists:

• TB lines with no COA match — accounts in your trial balance whose code does not appear in the uploaded COA. Most often this is a typo, an account split that hasn't been propagated, or a non-standard sub-ledger code. Each line shows the offending code, name, balance, and a 🔍 button that scrolls the COA panel to show what's nearest alphabetically.
• COA accounts with no TB activity — accounts in your COA that the TB doesn't touch. Often legitimate (dormant accounts, contra accounts) but worth confirming with the client that no transactions are missing.
• Lead-area mismatches — TB lines where the auto-mapped lead area conflicts with whatever was set manually before the COA upload. Each mismatch shows both values and a "Use COA value / Keep manual" toggle.

The appraisal is non-destructive — it does not change your TB until you click 🔗 Auto-Map Lead Areas to TB.

6.2.4 The Trial Balance "NOT BALANCED" state

The TB card refuses to gate downstream pages on imbalance — you can navigate to Risk Assessment with an unbalanced TB — but every dependent page renders a red banner reminding you. Materiality Calculator inputs (Revenue, PBT, Total Assets, Equity) can be entered manually if you don't yet have a balanced TB, but the analytical procedures page will refuse to compute ratios until the imbalance is resolved.

6.2.5 Materiality basis selection notes

The four bases are conventional under ISA 320:

• 5% of PBT — default; used for profit-driven entities. Switch off when PBT is volatile or near zero.
• 1% of Revenue — for entities where PBT is unstable but revenue is steady (early-stage companies, public benefit organisations).
• 1% of Total Assets — for asset-heavy entities (real estate, infrastructure, financial institutions where the Banking Audit module is enabled).
• 2% of Equity — for not-for-profits and public-benefit entities where the right scale is balance-sheet based.

The card always computes Performance Materiality at 75% of Planning and Clearly Trivial at 5% of Planning. These percentages are not configurable in the UI — they are ISA 320 conventions hard-coded into calcMat().

6.3 Risk Assessment

The Risk Assessment page is the single most important page of the planning phase: it tells JKO which audit areas to scope into Fieldwork, at what depth, with what kind of procedures. It is structured as six numbered tabs that flow left to right, each one feeding the next.

6.3.1 The six tabs

Each tab has a Next: [name] → button at the bottom that moves you forward without losing scroll position; you can also click any tab header to jump.

6.3.2 The Risk Matrix table — column by column

The matrix lives on tab 6 and is one row per audit area (Cash & Bank, Receivables, Inventory, PPE, Payables, Revenue, Expenses, Equity & Loans, Payroll, Related Parties, Tax, Other — twelve standard areas; you can add custom areas with the + Add Area button).

6.3.3 The three action buttons

Below the matrix:

• 🗺 Update Heat Map — recomputes Overall Score, Risk Level, and Audit Response for every row. Updates the topbar progress bar. Fires a toast: "Heat Map Updated · N HIGH risk area(s) identified." (warn-level if any HIGHs exist, success-level if not).

Warning toast for unscoped assessed areas: if any row has IR or CR > 0 but no ABCOTD chip ticked, an additional yellow toast fires — "Scope Warning: 'Receivables' is assessed (Risk Level: HIGH) but has no ABCOTD scope. It will not appear in Working Papers." This is JKO's safety net against forgetting to tick the chips on a high-risk area.

• 🤖 AI Commentary — sends the matrix to Claude with an "ISA 315 risk profile" prompt. Returns a per-area narrative explaining the inherent factors, the control deficiencies, and a short justification for the audit response. The output is appended to the matrix as collapsible per-area drawers.

• 📥 Download Risk Excel — exports the matrix plus the upstream tabs' notes to a five-sheet workbook (one sheet per tab + a summary).

6.3.4 Sample workflow — first-time risk assessment

1. Tab 1 (Business Environment) — capture the client's industry, key revenue streams, going-concern factors. 5–10 minutes of typing.
2. Tab 2 (COSO Framework) — score each of the 17 principles. About 15 minutes.
3. Tab 3 (Industry Benchmarks) — review the auto-loaded benchmarks; note any material deviation. 5 minutes.
4. Tab 4 (Control Environment) — score tone-at-the-top factors. 5 minutes.
5. Tab 5 (Control Review) — assess process-level controls for each audit area. 20 minutes for a typical SME. Click ⚡ Apply to Risk Matrix when done.
6. Tab 6 (Risk Matrix) — adjust Inherent Risk for each area (Control Risk is now pre-filled). Tick ABCOTD chips. Click 🗺 Update Heat Map. Click 🤖 AI Commentary if you want narrative support.

Save & Continue → Analytical Procedures.

6.4 Analytical Procedures (ISA 520)

This page implements ISA 520 preliminary analytical procedures. Two cards: Trial Balance Data Source (where the figures come from) and Analytical Procedures — Ratio Analysis (where they're crunched).

6.4.1 The Trial Balance Data Source card

A status badge in the top-right shows the import state: ⏳ Not imported (amber) → ✅ Imported (green).

• First Year toggle — a "This is a first-year audit" checkbox at the top. Tick it to grey out the prior-year column entirely (no PY data, no comparatives). Otherwise both years are required.
• Current Year section (purple panel) — three options to populate CY figures:
• 📥 Import from Existing TB (Engagement Setup) — pulls the trial balance you already entered in §2.6 into the analytical figures grid. Fastest path.
• Upload CY Trial Balance — drag-drop or click an Excel/CSV with the same column expectations as the Engagement Setup TB upload.
• Manual entry — type figures directly into the ratio-analysis grid below.
• Prior Year section (green panel) — same three options for PY figures.

6.4.2 The Ratio Analysis grid

Two side-by-side columns (Current Year / Prior Year). Each captures fourteen line items:

Three fields auto-recalculate as you type: Gross Profit (Revenue − Cost of Sales), Net Profit (Gross Profit − Operating Expenses), and the inverse — typing GP back-fills CoS if Revenue is set.

Two buttons under the grid: 📊 Compute Ratios and 🗑 Clear Figures.

6.4.3 The Computed Ratios & Flags card

Hidden until you click Compute Ratios. Shows a grid of about twelve ratios, each colour-coded against industry-typical bands:

• 🟢 Normal — within the green band for the client's industry
• 🟡 Borderline — outside the green band but inside the amber tolerance
• 🔴 Flag for investigation — outside the amber tolerance; a finding worth raising in the management letter

Below the grid: a Year-on-Year Movement Analysis table comparing every line item CY vs PY with absolute change, % change, and a flag for material movements (configurable threshold; defaults to 10%).

Three actions:

• 🤖 AI Interpret — Claude reads the ratios, the flags, and the YoY movements, and writes a planning-stage analytical commentary suitable for the working-paper file.
• ✅ Mark Complete — ticks the analytical-procedures status dot in the sidebar.
• 📥 Download Excel — three-sheet export: figures, ratios, movement analysis.

6.5 Statistical Sampling (ISA 530)

Sampling lives on a four-tab workspace (header tabs left to right): ⚙️ Parameters → 📂 Upload Ledger → 🎯 Sample Selection → 📋 Results & Projection.

6.5.1 Tab 1 — Parameters

The Monetary Unit Sampling parameters card. Every field:

Click 🔢 Calculate Sample Size. A results panel appears below with five rows:

• Calculated Sample Size (the n)
• Sampling Interval (GHS) — for MUS, the cumulative-value step between selections
• Random Start (GHS) — the first selection point
• Method — full text of the selected method
• Generated — timestamp

A toast confirms: "Sample Size Calculated · n = N · Upload ledger to auto-extract items." Auto-save fires.

6.5.2 Tab 2 — Upload Ledger

A drop-zone for the full transaction listing for the audit area. Expected columns: Reference, Date, Description, Debit, Credit (or a single Amount column). Optional: Balance, Narrative.

The ledger upload pipeline:

1. Drop or click to upload .xlsx, .xls, or .csv.
2. JKO renders a column mapper (your column → JKO column) so you can correct any mis-detection.
3. On confirm, JKO computes Population Value and Population Size and pushes them back to tab 1.
4. The ledger badge turns green: "Loaded · N transactions · GHS X total."
5. A preview button (👁 Preview Ledger) shows the first 50 rows; ✕ Clear Ledger removes the upload.

6.5.3 Tab 3 — Sample Selection

Click 🎯 Extract Samples and JKO runs the sampling engine with the parameters from tab 1 against the ledger from tab 2. The output is a table of selected items showing Reference, Date, Description, Amount, and a per-row Disposition column with five states:

• ⏳ Pending (default after extraction)
• 🔍 In Testing
• ✅ No Exception
• ⚠️ Minor Exception (under tolerable misstatement)
• ❌ Material Exception (over tolerable misstatement)

Each row also has a free-text Note field for the working-paper narrative. Select-all / mark-all-pending bulk actions are at the top.

6.5.4 Tab 4 — Results & Projection

Once dispositions are set, this tab shows:

• Items tested (N), of which exceptions (count, amount)
• Projected misstatement — exception rate × population value (or the MUS projection formula for monetary-unit samples)
• A traffic light: 🟢 Projected misstatement < Tolerable, 🔴 Projected ≥ Tolerable
• A recommendation: "No action required" / "Extend sample by N items" / "Refer to Misstatement Schedule"
• 📥 Download Sampling Excel — exports parameters + selected items + dispositions + projection in a four-sheet workbook for the working-paper file.

The 🔴 outcome on this tab is the trigger for raising an audit exception in §7.3 and a misstatement on the §8.1 schedule.

Fieldwork section

Fieldwork is where planning meets evidence. The Risk Assessment from §6.3 told JKO which areas you're testing and how; this chapter is where you actually do the testing, log the findings, and confirm the financial-statement disclosures. Four sidebar entries make up the Fieldwork band: 📂 Working Papers, 🗂️ File Assignments, 📋 Exceptions Log, ✅ Disclosure Checklist.

7.1 Working Papers

The page is titled Fieldwork Working Papers — Risk-Linked, with the strap "Each identified risk is linked to its ABCOTD audit programme section with working paper templates, sign-off controls and training resources" and an ISA 330 Aligned chip in the header. The page is generated entirely from the Risk Assessment matrix — there is no manual "create new working paper" path; if a row doesn't appear, it's because the risk assessment didn't tick the relevant ABCOTD chip.

7.1.1 The ABCOTD legend

A horizontal band of six pill-shaped chips at the top of the page acts as the legend:

These letters match the chips on the Risk Matrix's ABCOTD Scope column (§6.3.2). Tick a letter on the matrix and a working-paper section with that badge appears here.

7.1.2 The summary bar

Across the top of the page, just below the legend:

Total WPs: N    ✅ Complete: X    ⏳ In Progress: Y    ⭕ Not Started: Z    🔴 HIGH Risks: H

A quick health-check on fieldwork progress. The HIGH-risk count is the number of Risk-Matrix areas with Risk Level = HIGH that don't yet have all their ABCOTD working papers at ✅ Complete — i.e. where the Partner should be paying the most attention.

7.1.3 Risk-linked working-paper cards

The body of the page is a vertical stack of cards, one per assessed audit area (Cash & Bank, Receivables, Inventory, etc.). Each area card has:

• Header row — area name, current Risk Level pill (HIGH / MEDIUM / LOW), and a roll-up status chip
• ABCOTD badge strip — only the letters that were ticked in §6.3 appear here. If you scoped Receivables as "A · T · D" only, the card shows three sub-sections, not six.
• One sub-section per ticked ABCOTD letter, each containing:
• The audit-procedure template for that section (Excel and Word style — Excel for tabulated procedures like a vouching schedule, Word style for narrative sections like a process walk-through)
• Status chip that cycles ⭕ Not Started → 🔄 In Progress → ✅ Complete
• Preparer Initials field (free text — three letters by convention) and Date Prepared
• Reviewer Initials field and Date Reviewed
• Open button — launches the workpaper workspace, a focussed pane with: Objective (pre-filled from the procedure template), Procedures (the template body, editable), Conclusion (free text), Attached Evidence (drop-zone for vouchers, confirmations, screenshots), Narrative notes
• Training links — an inline list of ICAG / IAASB / industry resources relevant to the procedure (auto-loaded by area)

7.1.4 Role-restricted view

Senior and Junior staff only see working-paper cards for the audit areas they are assigned to in §2.6's Team Assignment. Other areas are hidden entirely (not greyed out — gone from their view). This is JKO's "least privilege" default for staff; if a senior needs visibility into a colleague's area they ask the manager to expand their assignment.

7.1.5 Page-footer actions

Below all the area cards:

• 🔄 Refresh from Risk Assessment — re-reads the Risk Matrix and rebuilds the working-paper structure. Useful if you've added or re-scoped an area on §6.3 and want it reflected here without a full reload.
• 📥 Export WP Index (Excel) — exports a flat list of every working paper across every area, with status, preparer, reviewer, and dates. The index, not the contents.
• 🖨 Print All — print-formatted view of the entire fieldwork section.

7.2 File Assignments & Review Monitor

The page is titled File Assignments & Review Monitor, with a purple left-border, the strap "Engagement-wide view of who is assigned what, preparation status, reviewer sign-off and close-out — ISA 220 / ISA 230", and two header buttons (🔄 Refresh and 📥 Export (Excel)).

This is the manager / partner oversight page for fieldwork. Junior and Senior staff see a stripped-down "My Fieldwork" view (their own assignments only); Manager and Partner see everything.

7.2.1 The six-up stats row

Six pill cards across the top of the page give an at-a-glance read on fieldwork completeness:

7.2.2 The filter bar

A row of filter dropdowns just under the stats:

• All team members — narrow the view to one person
• All audit areas — narrow to one area
• All statuses — Pending / In Progress / Complete / Reviewed
• All risk levels — HIGH / MEDIUM / LOW

Filters are AND-combined and persist for the session.

7.2.3 Three pivots — By Team Member, By Audit Area, Awaiting Review

The body of the page renders three tables in sequence:

• By Team Member — one row per assigned staff. Columns: Member · Role · Areas assigned · Total papers · ✅ Done · ⏳ In Progress · ⭕ Not Started · % Complete · Last activity. The "% Complete" cell is a small horizontal progress bar.
• By Audit Area — one row per assessed area. Columns: Area · Risk Level · Assignees (avatar pills) · WP count · Reviewer · Reviewer status. Useful for spotting the area where one team member is stuck.
• ⏳ Awaiting Review — flat list of every working paper marked ✅ Complete by the preparer but with empty Reviewer Initials. Each row links straight back to the working paper for the reviewer to action.

A separate red-banner card surfaces ⚠️ Unassigned Assessed Areas — risk areas in §6.3 with IR or CR > 0 but no team member. These are the "we haven't decided who's testing this" gaps that, left alone, become a Section G accountability problem.

7.3 Exceptions Log

Title: Audit Exceptions & Findings Log with the strap "All findings auto-populate the Management Letter". Two header buttons: 🤖 AI Draft (Claude drafts a finding from a brief description you provide) and ＋ Add Finding.

7.3.1 The columns

The exceptions table has nine working columns plus an action column:

The unspoken carry-forward / carry-to-report behaviour: by default, every finding flows into the Management Letter (§8.2 reads from this table). Findings with Priority = HIGH AND Impact > Performance Materiality also flow into the Audit Report's basis-for-modification section if Cleared = NO at the time of opinion generation (§8.3.2).

7.3.2 The summary bar

Below the table:

Total: N    🔴 High: H    🟡 Medium: M    🟢 Low: L

Useful as a sanity check before Management Letter generation — if you have zero findings you probably haven't done your job; if you have 200 you probably need to consolidate.

7.3.3 The 🤖 AI Draft button

Click it and a small modal asks two questions: "Briefly describe what you found" and "Which audit area?". Claude returns a structured draft with Observation / Risk Implication / Recommendation / Priority pre-filled, which you can accept-as-is, edit inline, or discard. The drafts come from a prompt that references ISA 240 / 265 framing and the firm's house style (the latter is configurable in the Admin Panel).

7.4 Disclosure Checklist

Title: Compliance & Disclosure Framework Checklist with the strap "Multi-jurisdiction · Select applicable frameworks for this engagement" and an ISA-Aligned blue chip. This is JKO's most extensive single page — twenty-six framework tabs covering most of the ISA-relevant disclosure regimes worldwide.

7.4.1 The framework selector

At the top of the page, a panel titled ACTIVE FRAMEWORKS FOR THIS ENGAGEMENT with a grid of toggle cards. Tick which frameworks apply to your client. Most Ghana SME audits will tick:

• 📊 IFRS for SMEs (or Full IFRS for a larger entity)
• 🇬🇭 Ghana Companies Act 2019
• 🇬🇭 Ghana Tax (ITA 2015 / VAT Act)
• ⚖️ IESBA Ethics
• 🔐 AML / KYC

A bank audit adds 🏦 Bank of Ghana. A US-listed entity adds 🇺🇸 SOX, 🇺🇸 PCAOB, 📋 SEC Reporting. A multinational adds 🇪🇺 EU CSRD, 🌱 ESG / ISSB, 🌡 TCFD.

Inactive frameworks have their tab hidden from the strip below — you don't waste screen space on rules that don't apply.

7.4.2 The compliance summary bar

A horizontal stat strip just below the selector:

Total Items: N   ✅ Compliant: X   ❌ Deficient: D   N/A: U   Compliance Rate: P%

The Compliance Rate is Compliant / (Compliant + Deficient) — N/A items are excluded from the denominator.

7.4.3 The 26 framework tabs

A wrapping row of tab buttons. Click any tab to switch the body of the page to that framework's checklist. The full set:

7.4.4 The per-tab requirement table

Each tab is a structured table with the same column set:

Each row also has a 📎 N paperclip button (where N is the count of attached evidence items). Clicking it opens the evidence modal.

7.4.5 The per-item evidence modal

A blue modal titled 📎 Evidence with the requirement text as the subtitle. Inside:

• A blue dashed drop-zone — "Upload Evidence · Click or drag & drop · PDF / DOCX / XLSX / CSV / image · Max 10MB each"
• Accepts: .pdf, .docx, .doc, .xlsx, .xls, .csv, .png, .jpg, .jpeg, .txt
• Multiple files at once
• Below the drop-zone, a list of already-attached items, each with file name, size, uploader name, upload date, an inline note field, a 👁 Preview button (where the file type supports it), and a 🗑 delete button

This is the per-requirement evidence trail that ICAG inspectors look for. The paperclip count badge updates live so you can sweep the disclosure tab visually for items missing evidence.

7.4.6 Page-footer actions

Below the tab content:

• 📥 Export Full Checklist (Excel) — every framework's checklist, every requirement, every comment, in one workbook (one sheet per framework).
• 📄 Export Compliance Report — a print-formatted summary suitable for inclusion in the working-paper file.
• 🤖 AI Compliance Review — Claude reads the entire checklist and returns a written compliance commentary highlighting deficient items, rationale, and recommended remediation. The output appears in a side-panel for review and is saved to the engagement state.

Completion section

Completion is where the engagement converges on an opinion. Three sidebar entries — 📊 Completion, ✉️ Management Letter, 📄 Audit Report — cover, in order: aggregating the misstatements, communicating findings to management, and forming and issuing the audit opinion. The path is linear and gated: the audit report cannot be Final until the EQR closure gate is satisfied.

8.1 Completion

The Completion page (sidebar entry 📊 Completion) is the single most important sanity check before issuing an opinion. It has three cards.

8.1.1 The Misstatement Summary card

A flat table that captures every uncorrected and corrected misstatement found during fieldwork. Columns:

Footer: a ＋ Add Misstatement button to append a row. Each row is editable inline.

A summary box below the table aggregates the figures live:

Total Unadjusted Misstatements        GHS X
Planning Materiality                  GHS Y    (from §2.6)
Unadjusted as % of Materiality        Z%
Suggested Audit Opinion               [opinion + colour pill]

The Suggested Audit Opinion is auto-derived from the unadjusted total against materiality and the going-concern flag (set in the next card):

This is the suggested opinion — the Audit Report page (§8.3) lets the partner override it.

8.1.2 The EQR Closure Gate card

A purple-bordered card titled Engagement Quality Reviewer (EQR) — Closure Gate with the strap "Audit cannot be archived / closed until EQR approval is confirmed on the Client Acceptance page." A status badge on the right shows the current state:

• ⏳ EQR Pending (purple) — the EQR has been appointed but has not signed off
• ✅ EQR Approved (green) — the EQR has signed off; the engagement can proceed to archive
• ❌ EQR Rejected (red) — the EQR has flagged a concern that must be resolved before sign-off

Below the badge, a details panel shows the EQR's name, appointment date, sign-off date (if any), and any objection notes.

A 📋 Go to EQR Sign-Off button jumps you back to the Acceptance page and smooth-scrolls to the EQR sign-off card. This is also where the EQR records their concurrence (or refusal) per ISQM 2.

The closure gate is enforced at archive time, not at navigation time — you can finish writing the audit report without an EQR sign-off, but you cannot move the engagement to File Management → Archive with EQR Pending.

8.1.3 The Going Concern & Subsequent Events card

Two YES/NO dropdowns and two textareas:

A 📥 Download Completion Excel button at the bottom exports the misstatement schedule, the EQR status, and both notes as a three-sheet workbook for the working-paper file.

Written Representations are not on this page — they live in the Permanent Audit File (§5.4) as the signed-by-management ISA 580 letter. JKO does not template the rep letter itself; partners use their firm's standard.

8.2 Management Letter

The Management Letter page (sidebar entry ✉️ Management Letter) takes the contents of the Exceptions Log (§7.3) and turns them into a client-ready letter.

8.2.1 The Management Letter Generator card

Title bar: Management Letter Generator with an Auto-Draft from Exceptions Log green chip.

A small stat strip in the action row shows the live exception count:

🔴 High: H    🟡 Med: M    🟢 Low: L

Four action buttons:

• ✉️ Generate Letter — pulls every row from the Exceptions Log into a structured letter: 1. Header — addressed to the Board, with the firm's letterhead placeholders 2. Introduction — context: "We have audited the financial statements of [client] for the year ended [year-end]" 3. Section A — High Priority Findings (HIGH-priority exceptions) 4. Section B — Medium Priority Findings (MEDIUM) 5. Section C — Low Priority Findings (LOW) 6. Each finding is rendered as: Observation · Risk Implication · Recommendation · Management Response (if filled) 7. Closing — partner signature block
• 🤖 AI Enhance — sends the generated letter to Claude with a "polish for clarity, tone, and consistency" prompt. The diff is shown for accept/reject before replacing the live text.
• 📥 Download Excel — exports the letter (rich text) and the underlying findings table as a two-sheet workbook.
• 🖨 Print — prints the rendered letter.

Below the action row, a large textarea (the rich-text editor) holds the letter content. It autosaves on every keystroke (800 ms debounce, §5.2). You can edit freely — your edits are preserved when you click Generate again only if you accept the diff. Click Generate without saving your edits and they are overwritten.

8.2.2 What feeds in, and how

• Source of findings — the Exceptions Log (§7.3). Every row, regardless of "Cleared?" status. Findings marked Cleared = YES are still listed but appear in italics with a "(resolved)" tag.
• Source of management responses — the Mgmt Response column on the same exceptions table. After the exit meeting, fill in the responses there and click Generate again to refresh the letter.
• Cross-references — each finding's Ref (EXC-001, EXC-002…) appears in both the management letter and, if it carries to the audit report, in the basis-for-modification paragraph.

8.3 Audit Report

The Audit Report page (sidebar entry 📄 Audit Report) is where the opinion is formed, the report is generated, and the signed AFS is uploaded.

8.3.1 The Audit Report Generator card

Title: Audit Report Generator with an ISA 700–705 blue chip. Four input fields above the generator:

Below the form, the Opinion Banner updates live as you change inputs — a coloured pill showing the currently-selected opinion (green / amber / red), the basis (auto vs override), and a one-line justification ("Total unadjusted misstatement is below performance materiality with no going-concern issues" / "EQR has flagged a scope limitation" / etc.).

8.3.2 Generating the report

Click 📄 Generate Audit Report. The standard ISA 700-format report is rendered into the textarea below, with placeholders filled:

1. Title — "INDEPENDENT AUDITOR'S REPORT to the Members of [client]"
2. Opinion — the selected opinion type with the standard ISA 700 wording
3. Basis for Opinion — references ISA standards, independence, ethical requirements; for Modified opinions, references the basis paragraph that follows
4. Basis for [Modification] (only for Qualified / Adverse / Disclaimer) — describes the issue, references the misstatement schedule and the management-letter findings that carry to the report
5. Material Uncertainty Related to Going Concern (only when §8.1 going-concern flag is YES)
6. Other Information — typical SME wording; references the management letter if §8.3.1 toggle is YES
7. Responsibilities of Management and Those Charged with Governance
8. Auditor's Responsibilities for the Audit of the Financial Statements
9. Report on Other Legal and Regulatory Requirements — Ghana Companies Act 2019 §137 wording
10. Signature block — firm name, partner name and ICAG number, address, date

Three additional buttons:

• 🤖 AI Enhance — Claude reviews the generated report for clarity, ISA 700 wording fidelity, and consistency with the misstatement schedule. The diff is shown for accept/reject.
• 📥 Download Excel — exports the report text and the underlying inputs as a two-sheet workbook.
• 📤 Export ALL Working Papers — bundles every section of the engagement (Acceptance, Setup, Risk, Analytical, Sampling, Working Papers, Exceptions, Disclosure, Completion, Management Letter, Audit Report) into a single multi-sheet Excel workbook. This is the canonical "give the regulator everything" export.
• 🖨 Print — prints the rendered report.

8.3.3 The Final & Signed AFS upload card

A green-bordered card titled Final & Signed AFS with the strap "Upload the signed Audited Financial Statements (PDF preferred) after Partner + client signature · ISA 230 retention". A "0 uploaded" badge in the top-right reflects the current count.

A green dashed drop-zone below the header: "Upload Signed AFS · Click or drag & drop · PDF / DOCX / image · Max 10MB per file". The accepted MIME types are .pdf, .docx, .doc, .png, .jpg, .jpeg.

After upload, each file appears in a list below the drop-zone with:

• File name and size
• Uploader name and timestamp
• A Final toggle — tick this when the document is the final signed version (not a draft, not a markup)
• Signing date — the date the partner and client director signed
• Uploaded by — auto-captured (current user's name)
• 👁 Preview button (PDFs and images render inline; .docx downloads)
• 🗑 Delete button (Partner only)

Once any AFS file is marked Final, the engagement's Audit Report sidebar dot turns green and the engagement's status in the registry advances to "signed". The engagement is now ready for archival — provided the EQR closure gate (§8.1.2) has cleared.

8.3.4 Why the AFS upload matters

Three reasons the signed AFS belongs inside the engagement record, not on a shared drive somewhere:

• ISA 230 retention — the audit working-paper file should include the audited document the opinion was given on.
• ICAG inspection — when the regulator asks for the engagement, they expect to receive the signed AFS as part of the bundle. The firm-wide data export (§15.4) zips this in automatically.
• Tamper-evident anchoring — the file's hash is recorded in the audit log, so the firm can later prove that the AFS in storage is byte-identical to what was signed.

8.4 ICAGH external quality review (post-archive)

After the engagement has been archived (Sidebar → 📦 Archive → archive card created), the Partner has a one-time decision: hold the file internally, or push it to an ICAGH Quality Reviewer for external regulatory review. JKO's review-push flow generates a self-contained HTML "review package" — a single file the reviewer opens in any modern browser — and walks the Partner through emailing it to the designated reviewer.

8.4.1 The Hold / Push choice

By default every freshly archived engagement is 🔒 Held internally — the chip on the archive card says so. No action is required if you are simply retaining the file in your own records. Only the Partner can change this state; Manager / Senior / Junior do not see the push button.

When the Partner clicks 🏛 Push to ICAGH on an archive row, a modal asks for:

• Reviewer name — printed on the package header and pre-filled in the email
• Reviewer email — used as both the mailto: recipient and (in Phase 2) the auto-send address
• ICAG registration # — optional but recommended (printed on findings for traceability)
• Token expiry (days) — default 60, range 7–180; bounds when findings are still accepted
• Cover note — pre-populated text that becomes the email body

On submit, JKO generates a 32-character random token (the link between the package and this archive — the firm refuses to import findings whose token does not match), builds a self-contained ICAGH_Review_<client>_<year>.html file, downloads it, and opens your default mail client with subject and body pre-filled. Attach the just-downloaded HTML file before sending — the email is what carries the package to the reviewer.

The archive card chip flips from 🔒 Held internally to 📤 Pushed to ICAGH · [reviewer]. Two new buttons appear: 📥 Import Findings (used when the reviewer returns the JSON), and ↩ Recall (sets the archive back to Held; existing review packages still open for the reviewer but findings imports will be refused once the token is rotated).

8.4.2 What's inside the review package

The package is an offline single-file HTML — no internet required to use it. It contains:

• A purple-banded header: firm name · client · FY · reviewer name · token expiry
• Engagement snapshot card: opinion, score, materiality, exceptions count, archive metadata, the review token (so the reviewer can confirm provenance)
• The full risk matrix (read-only) — IR, CR, fraud, overall risk per area
• The exceptions log (read-only) — each exception with priority and clearance status
• The Working Paper Compliance Tracker — every WP from WP_AREA_DATA listed and grouped by area, each row showing:
  • WP name, phase (B/C/T/A/D), ISA reference
  • The fieldwork status the engagement team recorded (Complete / In progress / Pending)
  • A compliance dropdown the reviewer fills in: ✅ Compliant · 🟡 Partial · ❌ Deficient · ➖ N/A
  • An ISQM objectives multi-select: pick from the firm's 66 quality objectives (ISQM 1, ISQM 2, ISA 220) which the WP touches; the picker has a search box and shows the standard, component, and reference for each item
  • A free-text notes box per WP
• The Reviewer's Overall Conclusion card: free-text conclusion, recommendation dropdown (Accepted / Accepted with observations / Remediation required / Re-perform / Escalate), signed-by name and date

The package auto-saves drafts to the reviewer's browser localStorage (keyed by token), so partial reviews persist if they close the tab. There is also a 💾 Save draft to file button for portability.

8.4.3 Submitting findings (reviewer side)

When the reviewer clicks 📤 Submit Findings, the package validates that the conclusion text, recommendation, and signed-by name are filled in (and warns if WPs remain unreviewed). It then downloads ICAGH_Findings_<client>_<year>.json. This JSON contains the token, reviewer details, the full WP list, every per-WP review (status / ISQM tags / notes), and the overall conclusion — but not the original audit data. The reviewer emails that JSON back to the firm.

8.4.4 Importing findings (firm side)

The Partner clicks 📥 Import Findings on the archive's pushed row → file picker opens → the Partner selects the returned JSON. JKO validates:

• The file's kind is jko-icag-findings
• The token matches the archive's saved token (mismatched tokens are rejected with a toast)

On success the archive flips to ✅ ICAGH findings received, the chip turns green, and a 📋 View Findings button appears. Click it to see:

• A 5-card summary: counts of Compliant / Partial / Deficient / N/A / Not reviewed
• The reviewer's identity, ICAG number, and submission timestamp
• The full per-WP table — each WP with the reviewer's compliance badge, the ISQM objectives they tagged, and their notes
• The reviewer's overall conclusion, recommendation, and signature

Print, share, or use as input to the firm's ISQM monitoring (§10.7) and remediation pipeline.

8.4.5 Why this is a one-way push

The package is a permanent snapshot at the moment of push — it does not "live-update" if the firm later edits the archive (which they shouldn't anyway; archives are append-only by design). Re-pushing creates a fresh token; the prior package's findings can no longer be imported. The recall button is the explicit way to invalidate.

Specialised modules

JKO ships five optional modules that sit alongside the standard ISA audit but are not part of it. Three are industry-specific opt-ins toggled in Engagement Setup → Optional Modules (§2.6); two more — IFRS 16 Lease Analysis and Journal Entry Testing — are available on every engagement under the Audit Procedures sidebar band.

The opt-in pattern matters: when an industry module is enabled the corresponding sidebar entry appears (e.g. 🏦 Banking Audit (BoG) under Planning) and the module's progress is included in the engagement's overall progress bar. Toggle it off and the entry vanishes from the sidebar and from progress tracking. Switching off does not delete the data — re-enabling it restores everything.

9.0 Banking Audit — Bank of Ghana / Basel III

The 🏦 Banking Audit (BoG) sidebar entry. For licensed financial institutions audited under the Banking Act 2016 and BoG Directives. The page is a stack of six cards, each handling one prudential or AML dimension.

9.0.1 The header strip and live stats

A teal-bordered header card titled 🏦 Banking Audit — Bank of Ghana & Basel III with the strap "Prudential ratio calculators · IFRS 9 ECL staging · Single obligor · AML transaction sampling — Banking Act 2016 & BoG Directives" and two header buttons (🔄 Refresh, 📥 Export (Excel)).

Below the header: a five-up live stats strip showing the current state of every key prudential metric — CAR · NPL · LCR · Single-obligor breaches · AML escalations. Each stat is a coloured pill: green when the metric is within tolerance, red when it has breached the regulatory threshold.

9.0.2 Capital Adequacy Ratio (CAR)

A blue-bordered card titled 💼 Capital Adequacy Ratio (CAR) with the strap "Basel III · BoG Capital Directive 2018 · Minimum 13%". Three input fields (all in GHS '000):

A result panel below renders three computed numbers: Total Capital (Tier 1 + Tier 2), CAR % (Total Capital ÷ RWA), Tier 1 Ratio (Tier 1 ÷ RWA). Each is shown with a traffic light: green if CAR ≥ 13% and Tier 1 ≥ 8.5%, red otherwise, with the breach amount displayed in cedis.

9.0.3 NPL & ECL Staging

An amber-bordered card titled 📉 Non-Performing Loans & ECL Staging with the strap "IFRS 9 stages · BoG Provisioning Directive · NPL ratio". A five-row table — one per IFRS 9 stage — with hard-coded provisioning rates per BoG:

Stages 3a / 3b / 3c are shaded pink — these are the NPL bucket. You enter a Gross Exposure for each row; JKO computes the provision live (Gross × Min ECL %) and rolls up:

• Total Gross Loans (sum of all stages)
• Total NPL (sum of Stage 3a–3c)
• NPL Ratio = NPL / Total Gross Loans, with traffic-light against the BoG <10% threshold
• Total Provision = sum of provisions
• NPL Coverage Ratio = Provision / NPL

9.0.4 Liquidity Coverage & Net Stable Funding

A green-bordered card titled 💧 Liquidity Coverage & Net Stable Funding with the strap "LCR ≥ 100% · NSFR ≥ 100% — BoG Liquidity Directive". Four inputs in a two-column grid:

The result panel renders LCR % and NSFR % each with a 100% threshold pill — green if ≥ 100%, red below.

9.0.5 Single Obligor & Insider Lending

A red-bordered card titled ⚠️ Single Obligor & Insider Lending with the strap "Single obligor limit 25% of net own funds · Insider lending limits per Banking Act s.72". Two parts:

• Net Own Funds (GHS '000) input — the denominator for the single-obligor calculation.
• Counterparty exposure table — one row per significant counterparty, with Counterparty · Type · Exposure · % of NOF · Status. The Status column auto-flags any row above the 25% limit.

A ＋ Add Counterparty button appends rows. Type is a dropdown (Single Borrower / Connected Group / Insider — Director / Insider — Officer / Insider — Related Party). The Banking Act limits are enforced in the Status pill: 25% for single counterparty, lower thresholds for insider categories.

9.0.6 AML Transaction Sample

A purple-bordered card titled 🔐 AML Transaction Sample with the strap "Suspicious-pattern testing — AML Act 2020 · FATF · BoG AML Guidelines". An info banner at the top reminds you: "Sample at least 25 high-value or pattern-flagged transactions. Test customer due diligence (CDD), source-of-funds documentation, sanctions screening, and STR/CTR filing."

The sample table has eight columns:

A ＋ Add Transaction button appends rows.

9.0.7 SOX / ICFR Audit Module

The 🇺🇸 SOX / ICFR Audit sidebar entry. For US-listed entities and accelerated filers subject to Sarbanes-Oxley. The page has six stacked cards plus a five-up stats strip.

Header card — title 🇺🇸 SOX / ICFR Audit Module with the strap "Sarbanes-Oxley Act 2002 · §302 attestation · §404 ICFR opinion · COSO 2013 framework · PCAOB AS 2201". Buttons: 🔄 Refresh, 📥 Export (Excel).

Stats strip: COSO principles effective · Walkthroughs logged · Material weaknesses · Significant deficiencies · Current opinion.

Card 1 — §302 Certifications (blue border). Quarterly and annual certifications of disclosure-control design and accuracy. Fields:

• CEO Name, CEO Certification Date
• CFO Name, CFO Certification Date
• Significant changes to internal controls disclosed? — NO (no changes) / YES (disclosed in MD&A)

Card 2 — COSO 2013 Five-Component Assessment (purple border). Strap: "17 principles across 5 components · used as the §404 ICFR framework". An expandable grid with one row per component (Control Environment, Risk Assessment, Control Activities, Information & Communication, Monitoring), each containing the relevant principles. Per principle:

• Status: Effective / Partial / Ineffective / N/A
• Evidence reference (free text)
• Reviewer initials and date

Card 3 — ICFR Walkthrough Log (green border). Strap: "One walkthrough per significant process — origination → approval → recording → reporting". A ＋ Add Walkthrough button. Columns:

Card 4 — Control Deficiency Register (amber border). Strap: "Material weakness · Significant deficiency · Control deficiency — PCAOB AS 2201". A ＋ Add Deficiency button. Columns:

Card 5 — Audit Committee Independence (§301) (green border). Strap: "All members independent · Financial expert disclosed · Auditor oversight". Fields:

• Number of AC members
• All members independent (NYSE / Nasdaq def)? — YES / NO
• Financial Expert designated — name + qualification (free text)
• AC pre-approves audit & non-audit services? — YES / NO

Card 6 — §404(b) ICFR Opinion (red border). Strap: "Auditor's attestation on management's assessment". Two fields:

• ICFR Opinion dropdown: Unqualified (effective in all material respects) / Adverse (material weakness(es) exist) / Disclaimer (scope limitation).
• Basis for opinion / supporting narrative — free-text textarea.

9.1 Ghana Tax Audit

The 🏛️ Ghana Tax Audit sidebar entry. A comprehensive GRA-style tax audit module modelled on the Ghana Revenue Authority's official audit forms (the AF series).

9.1.1 Page structure

The Ghana Tax Audit page is rendered dynamically into a single root container — content scrolls vertically through the form set in canonical AF order. Each form is a card with the same status pattern: ⭕ Not Started → 🔄 In Progress → ✅ Complete, plus preparer / reviewer initials and date.

9.1.2 The forms

9.1.3 Cross-form behaviour

• AF100 timestamps every action — useful for the GRA file inspection trail.
• AF101B risk ratings drive which AF300-series forms appear by default. A LOW VAT risk hides AF304 by default (you can manually enable it).
• AF400 aggregates totals from the AF300 series — change a number in AF300 (CIT) and AF400 picks it up on its next render.
• The Tax Position Letter pulls every adjustment from AF400 and the rationale from each AF300-series form to compose the draft.

9.1.4 Export

A 📥 Download Tax Audit Excel button at the foot of the page exports a workbook with one sheet per form plus a consolidated summary. This is the bundle you submit to GRA.

9.2 IFRS 16 Lease Analysis

The 🏢 Lease Analysis (IFRS 16) sidebar entry, under the Audit Procedures band — available on every engagement, no toggle required.

9.2.1 The page header

Title: Lease Analysis — IFRS 16 with the strap "Upload a lease contract → AI extracts the IFRS 16 inputs → auto-compute lease liability, right-of-use asset, depreciation & amortisation schedule". A status badge in the top-right shows "📂 N leases analysed".

9.2.2 Upload a contract

A teal dashed drop-zone: "Upload a Lease Contract (PDF) · Click or drag & drop · Max 10MB · Anthropic Claude reads the PDF and extracts IFRS 16 terms". Only PDF is accepted (the AI extraction relies on text-layer reading).

After upload, the page shows a small staging panel with the file name, size, and two buttons: 🤖 Extract IFRS 16 Inputs with AI and ↺ Cancel.

9.2.3 The AI extraction

Click 🤖 Extract IFRS 16 Inputs with AI. JKO sends the PDF to Claude with an "extract IFRS 16 terms" prompt. Status banner: "⏳ Calling AI…". After 5–15 seconds the form below the panel pre-fills with extracted values.

9.2.4 The lease form

A three-column grid of fifteen fields. Always verify each field against the contract — Claude is good but contracts are tricky.

9.2.5 Compute and save

Click ⚙️ Compute IFRS 16 Numbers. The output panel shows:

• Initial Lease Liability (PV of payments at IBR)
• Initial Right-of-Use Asset (Liability + Initial Direct Costs + Restoration − Incentives)
• Monthly straight-line ROU depreciation
• Full amortisation schedule (period × opening liability × interest × payment × closing liability) — collapsed by default; click to expand to the full table

Click 💾 Save Lease Analysis to add the lease to the engagement's lease register (shown in a list at the bottom of the page).

9.3 Journal Entry Testing (ISA 240)

The 📓 Journal Entry Testing sidebar entry, under Audit Procedures — available on every engagement.

9.3.1 Why this exists

ISA 240 §32(c) requires the auditor to test journal entries for characteristics indicative of fraud or unusual activity. Doing this manually against a 50,000-row GL is a fool's errand — JET runs nine pattern-detection tests in parallel against the full population.

9.3.2 The upload pipeline

A red dashed drop-zone: "Upload General Ledger / Journal Entries · .xlsx / .xls / .csv · Expected columns: Date, Account, Description, Debit, Credit (others auto-detect)". Drop the full posting / journal listing for the engagement period — SheetJS reads all sheets and uses the first by default.

After upload, a column mapper appears: JKO's auto-detection guesses which columns are which; you confirm or correct the mapping (Date → Date column, Debit → Debit column, etc.).

9.3.3 Test parameters

After mapping, a Test Parameters card appears with seven configurable inputs:

9.3.4 The nine tests

Click ⚙️ Run All Tests. JKO runs nine tests in parallel:

A flagged entry can hit multiple tests; the system tracks which flags applied to which entry. Only flagged entries are persisted (not the whole population — keeps the engagement state lean).

9.3.5 Stats and results

After running, a five-up stats strip appears: total entries · total flagged · % flagged · highest-priority test · last run timestamp. Below that, the results section renders a card per test with the count, the description, and an expandable list of flagged entries.

9.3.6 Disposition each flagged entry

Each flagged entry has a free-text Note field and a Disposition:

• ⏳ Pending (default)
• ✅ Explained — auditor has reviewed and is satisfied
• ❌ Exception — auditor has reviewed and considers it a finding (carries to the Exceptions Log §7.3)

Four buttons at the bottom of the page:

• ⚙️ Run All Tests — re-runs the nine tests against the latest parameters.
• ↺ Reset Upload — clears the ledger and parameters; useful if you uploaded the wrong file.
• 📥 Export Results (Excel) — exports flagged entries by test, with dispositions and notes, as the JET working paper.
• 🤖 AI Commentary — Claude reviews the flagged set and writes a planning-stage narrative on the patterns observed and the risk implications.

Quality management (ISQM)

The 🛡️ ISQM Compliance Review sidebar entry (under Quality Management) is JKO's implementation of the IAASB's quality-management standards: ISQM 1 (firm-level System of Quality Management), ISQM 2 (Engagement Quality Reviewer), and ISA 220 (Revised) (engagement-level quality). All three apply to every audit engagement and the firm has to be able to evidence them annually.

Sixty-six quality objectives are pre-loaded across the three standards. The page is a structured review tool — work through it once a year for the firm-level SoQM and per engagement for the engagement-level review.

10.1 The engagement context banner

A green banner at the top of the page makes it explicit which engagement this review attaches to:

📁  ENGAGEMENT-SPECIFIC ISQM REVIEW
    [Client name]
    [year-end · engagement status · partner]

    This ISQM review attaches to this engagement file only.
    Each engagement maintains its own evaluation, sign-off and evidence trail.

    [📋 Copy from another engagement]

This is deliberate — without the banner, a Partner reviewing six engagements in succession can lose track of which one they're commenting on. The banner re-grounds them every time.

10.2 The header card

A dark-teal-bordered card titled ISQM Compliance Review with the strap "Firm-level & engagement-level quality management — ISQM 1 (Firm SoQM) · ISQM 2 (EQR) · ISA 220 (Revised, Engagement)". Three header buttons: 🔄 Refresh, 📥 Export (Excel), 🤖 AI Commentary.

A five-up stats strip below the header: Total objectives · Compliant · Partially compliant · Deficient · Not started. Updates live as you fill in the review.

A filter bar lets you narrow the view by status — Not started, Compliant, Partially compliant, Deficient, N/A — useful for finding the deficiencies fast in a large review. The filter has an inline reminder: "Documented under ISQM 1 §57 — review & sign-off retained for 5 years (or as required by jurisdiction)."

10.3 The 66 quality objectives, by standard

Below the header, the page renders three collapsible sections:

10.3.1 ISQM 1 — Firm SoQM (eight components)

ISQM 1 is structured around eight components. Each component has multiple objectives:

Each component header is a clickable bar. Click to expand and see the per-objective rows.

10.3.2 ISQM 2 — Engagement Quality Reviewer

Objectives covering: appointment of the EQR (criteria, independence, competence), conduct of the review (timing, depth, documentation), the EQR's concurrence (or refusal) and how it is recorded.

10.3.3 ISA 220 (Revised) — Engagement-level quality

Objectives covering: engagement partner's responsibilities, ethical requirements at engagement level, engagement resources, direction-supervision-review, consultation, EQR engagement-level co-ordination, monitoring inputs from ISQM 1.

10.4 The per-objective row

Every one of the 66 objectives is a row with the following fields:

Below each component, a mini-summary panel rolls up the component's status: e.g. "Component 5 — 7 objectives · 5 Compliant · 1 Partial · 1 Deficient".

10.5 The Annual SoQM Sign-Off card

A purple-bordered card at the bottom of the page titled Annual SoQM Evaluation & Sign-Off with the strap "Managing Partner attestation that the firm's System of Quality Management is operating effectively — ISQM 1 §53". A status badge in the top-right shows ⏳ Pending (amber) until confirmed, then ✅ Confirmed (green).

Five fields:

Two buttons:

• ✅ Confirm Annual Sign-Off — flips the badge to ✅ Confirmed and writes an audit-log entry (ISQM_SIGNOFF) with the Managing Partner's name, conclusion, and timestamp.
• ↩ Revoke Sign-Off — reverts the badge to ⏳ Pending. Used when you need to amend the conclusion or add a deficiency that came to light after sign-off.

10.5.1 Auto-revoke on edit

A subtle but important behaviour: editing any of the five sign-off fields after a confirmation auto-revokes the sign-off. This prevents the situation where a Partner confirms the SoQM, someone changes the deficiency narrative, and the audit log retains a confirmation that no longer matches the live document. The audit log captures the revoke (ISQM_SIGNOFF_REVOKE).

10.6 Copy from another engagement

The 📋 Copy from another engagement button (top-right of the engagement banner) opens a modal titled Copy ISQM Review from Another Engagement with the strap "Pre-fills statuses, responses, evidence and sign-off fields. You can edit anything afterwards. The copied sign-off is not automatically confirmed."

The modal has four section toggles at the top:

• ☑ ISQM 1 (firm-level) — usually safe to copy; ISQM 1 reflects firm-wide controls that don't change by engagement.
• ☐ ISQM 2 (EQR) — copy only if the EQR profile is similar.
• ☐ ISA 220 (engagement) — copy only if the engagement profile is similar.
• ☐ Sign-off fields — usually leave unticked; sign-off should be deliberately re-confirmed.

A reminder banner: "💡 ISQM 1 reflects firm-level controls — usually safe to copy. ISQM 2 / ISA 220 are engagement-specific — copy only if the engagement profile is similar."

Below the toggles, a list of every other engagement in the firm (sorted by recency) with a Copy from this engagement button on each. Selecting one and confirming pre-fills the ticked sections in the current engagement's review. The copied sign-off remains unconfirmed regardless of source — you have to confirm afresh.

10.7 Workflow for the annual SoQM cycle

A typical annual cadence for a Ghana SME firm:

1. Q1 — Managing Partner kicks off the SoQM evaluation. Updates ISQM 1 firm-level objectives based on the past year's monitoring inputs (inspection findings, complaints, regulatory feedback).
2. Each engagement (throughout the year) — Engagement partner completes ISQM 2 + ISA 220 sections on the engagement's ISQM page. Where appropriate, uses 📋 Copy from another engagement to seed the form, then edits.
3. End of FY — Managing Partner reviews monitoring outputs, compiles the firm's SoQM conclusion, and completes the Annual SoQM Sign-Off card on a representative engagement (or on a dedicated firm-level "SoQM holding" engagement). The conclusion + deficiencies + remediation plan is the formal ISQM 1 §53 attestation.
4. 5-year retention — JKO keeps the review and sign-off forever; ISQM 1 §57 mandates a minimum of 5 years.

10.8 Footer actions

• 🔄 Refresh — re-renders the objective list (useful after copying from another engagement).
• 📥 Export (Excel) — exports the entire ISQM review (all 66 objectives + sign-off) as a multi-sheet workbook for the firm's quality file.
• 🤖 AI Commentary — Claude reads the review and writes a structured commentary identifying patterns of partial/deficient ratings, suggested root causes, and a recommended remediation plan. Suitable for inclusion in the firm's monitoring report.

Project finance & P&L

The 💰 Project Finance & P&L sidebar entry (under Administration) is JKO's engagement-economics workbench. It answers two questions: is this engagement profitable? and which engagements in the firm are pulling their weight?. The first is per-engagement; the second is firm-wide.

This is distinct from the 💼 Billing Centre (sibling sidebar entry, covered in §11.4) which handles the actual invoicing and AR flow. Project Finance is about cost vs revenue — Billing Centre is about cash collection.

11.1 The Engagement Profitability summary card

A green-bordered card at the top of the page titled Engagement Profitability with the strap "Live P&L for this engagement — fee revenue vs personnel + admin + reimbursable costs". A margin badge in the top-right is colour-coded:

• Green — Margin ≥ 25%
• Amber — Margin 0–25%
• Red — Margin negative (the engagement is losing money)

Below the badge, a six-up grid of summary stats updates live as you fill in the cards below:

A progress band below the stats compares current Total Cost against budget (if a budget has been set in the Time & Fees Tracker).

11.2 The four input cards

11.2.1 Fee & Revenue Setup

A six-field form:

Every field auto-saves on input.

11.2.2 Personnel Cost Rates

A flexible card titled 👥 Personnel Cost Rates with the strap "Define each team member's cost — hourly rate × hours, OR a fixed allocation per person". A header button ↺ Pull Team Members populates the table with rows for every team member assigned to this engagement (from §2.6's Team Assignment).

Per row:

• Member — name (auto-pulled)
• Cost Mode — Hourly / Fixed
• Hourly Rate (GHS) — only used in Hourly mode
• Hours — only used in Hourly mode
• Fixed Allocation (GHS) — only used in Fixed mode
• Computed Cost — Hourly × Hours, or the Fixed value
• A 🗑 delete button on each row

Junior staff are usually Hourly; Partners are often Fixed. The choice doesn't affect billing — it only changes how internal cost is computed.

11.2.3 Other Direct & Reimbursable Costs

A categorised expense table titled 📋 Other Direct & Reimbursable Costs with the strap "Travel, accommodation, printing, software, training — set 'Billable' if recoverable from the client". A ＋ Add Expense button.

Per expense row:

Net cost to the firm = Cost − Recovered. The "Total Direct + Reimbursable Cost" stat on the summary card aggregates these net costs, not the gross.

11.3 The Cross-Engagement P&L Dashboard card

A purple-bordered card at the bottom of the page titled 📊 Cross-Engagement P&L Dashboard with the strap "All engagements at a glance — revenue, cost, margin, recovery rate". Two header buttons: 🔄 Refresh and 📥 Export (Excel).

A five-up stats strip shows firm-wide totals: Engagements · Revenue · Cost · Net Profit · Average Margin %. Below that, a sortable table with one row per engagement:

Sortable by any column — sort by Margin descending to find your most profitable engagements; sort by Recovery Rate ascending to find the ones with collection problems.

11.4 How this differs from the Billing Centre

Two pages, two purposes — the line is worth knowing.

Both pages share the engagement registry — they're two views on the same data. Updating fees in one is reflected in the other on the next refresh.

11.5 The Excel export

Click 📥 Export (Excel) on the Cross-Engagement Dashboard for a three-sheet workbook:

• Sheet 1 — Cross-Engagement P&L — one row per engagement with the same columns as the dashboard table.
• Sheet 2 — Personnel Detail — every personnel cost row across every engagement, useful for capacity-utilisation analysis (who's billable on which engagement, at what rate, how many hours).
• Sheet 3 — Expenses Detail — every direct/reimbursable expense across every engagement, useful for partner-level expense governance.

This is the workbook to produce ahead of any partner-meeting review of firm economics.

Administration

The Administration band of the sidebar covers four distinct utilities — one for time-tracking, one for managing staff change-requests, one for the engagement timeline visualisation, and one for the client-facing executive view. Each is a separate page, none of them gate the audit workflow, and all four can be touched in any order.

12.1 Time & Fees Tracker

The ⏱ Time & Fees Tracker sidebar entry. Title: Engagement Time & Fees Tracker with the strap "Log hours by section and team member". A header button ＋ Log Time appends a new entry row.

12.1.1 The three configuration fields

A three-column form across the top of the card:

12.1.2 The time-entry table

Per row:

A 🗑 icon on each row deletes it.

12.1.3 The fee summary box

Hidden until at least one entry exists. Three boxes:

Total Hours Logged       N
Total Fees Earned        GHS X
Budget Remaining         B (Budget Hours − Total Hours Logged), with a colour pill

The Budget Remaining pill is green when ≥ 20% of budget remains, amber when 0–20%, red when over budget.

12.1.4 Export

A 📥 Download Time Sheet button at the foot of the card exports a single-sheet workbook with the time entries plus the budget-vs-actual summary.

12.1.5 Why this isn't the same as Project Finance

The Time & Fees Tracker captures time entries (a journal). Project Finance & P&L (§11.2.2) captures personnel cost rates (a structure). The two coexist:

• A small firm with mostly fixed-fee engagements may use the Time Tracker for internal capacity tracking only and leave P&L's personnel rates as Fixed allocations.
• A T&M-heavy firm may use the Time Tracker as the source of truth for billable hours and feed Hours from this page into the personnel cost rows on §11.2.2.

There is no automatic sync between the two — by design, so partners can apply judgement (write-offs, rate adjustments) in P&L without distorting the time journal.

12.2 Pending Submissions

The 📨 Pending Submissions sidebar entry. Title: Pending Submissions & Review with the strap "Team members' saves that conflict with live data are queued here for Partner/Manager review — ISA 220". A purple-bordered card with a 🔄 Refresh header button.

12.2.1 Why submissions exist

When two team members edit the same engagement on different devices, the version-conflict detection (§5.3) catches the conflict on save. The first edit through wins; the second is queued here as a "submission" for a Partner or Manager to triage.

This is also the queue for Junior / Senior staff edits to fields that require sign-off (e.g. a Junior populating a working paper that needs a Manager's review-initials). The Junior's edit waits as a submission until the Manager Accepts.

12.2.2 The role gate

Junior and Senior staff see a red 🔒 banner: "Only Partners and Managers can review and accept/reject submissions." They can see their own submissions in flight (so they know what's pending review) but cannot Accept or Reject anything. Partner and Manager see every submission in the firm.

12.2.3 Each submission card

Per submission, a card showing:

• Submitter — name, role, timestamp
• Engagement — which engagement the submission belongs to
• Section — which page the change was made on
• Summary diff — a brief "X changed: [old] → [new]" preview with up to three field changes
• 🔍 Full Diff button — opens the diff viewer modal
• ✕ Reject button — declines the submission; the submitter sees a notification with an optional Partner/Manager note
• ✅ Accept & Apply button — applies the submission to the live engagement state and closes the queue item

12.2.4 The Full Diff modal

Click 🔍 Full Diff to open a side-by-side viewer with field-level before/after rendering:

• Header: 🔍 Full Diff with the engagement name and submission timestamp
• Body: a scrollable side-by-side table — left column is the live state, right column is the submitter's proposed state, with changed fields highlighted in green (additions), red (deletions), and yellow (modifications)
• Footer: Cancel / ✕ Reject Submission / ✅ Accept & Apply

This is the canonical view for resolving a substantive disagreement — a manager can see exactly what the senior changed, in what section, before deciding.

12.3 Audit Workflow

The 🔀 Audit Workflow sidebar entry. A timeline visualisation of the audit lifecycle, rendered into a single root container.

12.3.1 The three scopes

The page can render the workflow in one of three scope variants — the variant that appears depends on which Optional Modules are toggled on for the engagement (§2.6):

If only the Statutory module is active, only the Statutory timeline renders. The page is forgiving — toggling modules on or off after the fact will reshape the timeline on the next render.

12.3.2 What the timeline shows

Each step on the timeline is a clickable pill that:

• Shows the step name and an icon (matching the sidebar entries)
• Has a status colour: ⭕ grey (not started), 🟡 amber (in progress), 🟢 green (complete), 🔴 red (blocked / has open exceptions)
• Shows an arrow connector to the next step
• Click navigates straight to that page

This is the "where are we?" visualisation a Partner uses in a 30-second status check before walking into a client meeting.

12.4 Client Progress View

The 📊 Client Progress View sidebar entry. An executive dashboard rendered into a single root container — the page you screen-share with a client when they ask for a status update.

12.4.1 The dashboard sections

• Header — client name, year-end, current engagement phase (Acceptance / Setup / Fieldwork / Completion / Signed), overall progress %.
• Phase completion bars — one horizontal bar per audit phase (Planning / Fieldwork / Completion / Reporting), each with a percentage and a coloured fill.
• KPI tiles — key engagement metrics: working papers complete vs total, exceptions logged, days since planning materiality was set, projected completion date.
• Milestone deadlines — upcoming dates: planned audit completion, EQR review window, signing date, AFS submission to RGD, statutory filing deadlines (where the Optional Modules add tax dates).
• Recent activity feed — last N events from the audit log, in plain language ("Senior K. Mensah completed Receivables Tests of Details on 14 March", "Partner approved the engagement team on 12 March").

12.4.2 Sharing with the client

The 📧 Share Progress button in the topbar (§2.3) is the canonical way to send this view to the client. It composes an email with the dashboard's headline metrics in plain text, ready for the partner to send. The full Client Progress View itself is not shared — it stays inside the firm; only the digest goes out.

Backend cloud sync (optional but recommended)

JKO is functional as a single offline HTML file. The optional cloud backend — a Cloudflare Workers + R2 + D1 deployment — turns it into a SaaS platform with the features that local mode cannot offer:

• SaaS subscription billing through Paystack (§3 doesn't work without it)
• Multi-device collaboration — partners on a laptop, seniors on tablets in the field, all working on the same engagement
• Server-side AI key — your firm's Anthropic key lives on the backend, not in user browsers (so a junior leaving with a downloaded copy of the HTML can't keep using your AI quota)
• Server-stamped, hash-chained audit log — tamper-evident in a way that pure-local mode cannot be
• Email-delivered welcome packs and password resets through the optional Resend integration
• Firm-wide data export — Partner can download every user, engagement, ACL row and audit-log entry in a single JSON archive

The backend is opt-in. Most firms run on it from day one, but you don't have to — JKO works without it and the path to migrate later (§13.2) is well-trodden.

13.1 Connecting to the backend

The connection is done once, by a Partner, from the Admin Panel.

13.1.1 The Admin Panel card

Sidebar → ⚙️ Admin Panel → scroll to the teal-bordered card titled 🔐 Backend API Connection & Migration with the strap "Connect to the cloud backend (closes browser-only security gaps) and migrate existing users + assignments". A status badge in the top-right shows the current state — ⏳ Not connected (amber) by default, ✅ Connected (green) after a successful Test Connection.

13.1.2 The five-step connection flow

1. Get the backend URL. Provided by your firm's administrator or by JKO support. Format: https://do-audit-api.YOUR-ACCOUNT.workers.dev (or your firm's custom domain).
2. Paste it into the Backend API URL field at the top of the card.
3. Click 🛜 Test Connection. The button shows a spinner; on success, the status badge flips to ✅ Connected (green) and a toast confirms "Backend reachable." On failure (wrong URL, backend down, your firewall blocks Cloudflare, etc.) you get a red error toast with the specific cause.
4. Sign out, then sign in again. This is the moment the app switches into backend mode — your browser exchanges credentials with the Cloudflare Worker rather than checking against the local user table. The welcome toast on a successful sign-in says "🔐 backend" instead of the local-mode "👋 welcome".
5. The 🔐 badge in the sidebar footer turns bright (it was dim before). This is the visual confirmation that you are now operating against the backend.

If anything goes wrong, the ↺ Clear button next to Test Connection resets the URL field; you can try a different URL, or contact JKO support with the firm ID.

13.1.3 What happens to local data

Connecting does not by itself delete local data. Your existing localStorage engagement state stays in place. The backend simply takes over as the source of truth for user authentication, audit log, and (if you migrate, see §13.2) engagement state.

If you want to clean out localStorage after a successful migration, the Admin Panel has a maintenance card with a "Clear local engagement archives" button. Use it deliberately — once cleared, the only copy of your historical engagements is on the backend.

13.2 Migrating local data to the backend

A one-time operation. If you've been using JKO offline for a while and now want to move onto the SaaS, this is how the existing data comes with you.

13.2.1 Prerequisites

A yellow callout in the card spells these out:

One-time migration: imports your existing local users and engagement assignments into the backend. Existing passwords are preserved (silently upgraded to bcrypt on each user's next login). Your engagement data stays where it is. Run this after the backend has been deployed and you have admin credentials.

So before you start: backend deployed (Cloudflare URL works), Test Connection succeeds, and you have the bootstrap admin credentials that your firm was issued at signup.

13.2.2 The migration form

Two fields in a sub-card:

• Backend admin username — the bootstrap partner username (provided at signup).
• Backend admin password — the bootstrap password (provided at signup; should be rotated immediately after first migration).

Two buttons:

• 👁 Preview What Will Be Sent — opens a modal showing every user record and engagement assignment that will be uploaded, with the password fields masked. Use this to sanity-check before you commit.
• 📤 Migrate Local Data → Backend — performs the migration.

13.2.3 What gets migrated

• Every user record from the local users table (name, username, role, email, ICAG, active flag)
• Every engagement-team assignment (member × engagement × area)
• Existing password hashes are sent up as-is. The backend stores them in their legacy form and silently upgrades each user's hash to bcrypt on their next successful login. This means users do not need to reset their password to migrate — their existing one continues to work.

What does not get migrated by this button:

• Engagement state (working papers, TB rows, exception logs, ISQM reviews) — these are pulled per-engagement via §13.3 below
• The audit log — the local audit log stays local; the backend starts a fresh hash chain

13.2.4 After migration

A green panel below the buttons shows the result: "N users migrated · M assignments migrated · K skipped". If anything was skipped, the reason is listed (typically because a user with the same username already existed on the backend). The audit log captures the migration as a MIGRATION_RUN event.

13.3 Pulling engagements on a new device

When a team member opens JKO on a fresh laptop and signs in via the backend, their localStorage is empty — no engagements, no working papers. The Pull flow is how they fetch the engagements they're assigned to.

13.3.1 The Pull card

A green-bordered card titled 📥 Pull Engagements from Backend with the strap "Fetch the latest engagement state from R2 — useful on a fresh device or after a long offline period". A 🔄 Refresh List button is in the top-right of the card.

13.3.2 The four-step pull flow

1. Set the backend URL in the card above (§13.1).
2. Sign in.
3. Click 🔄 Refresh List. The card body lists every engagement on the backend that this user has access to (Partner sees all engagements in the firm; Manager / Senior / Junior see only those they're assigned to).
4. Click 📥 Pull on each engagement you want locally. JKO fetches the engagement blob from R2, decrypts and hydrates it into local state, and the engagement appears in the Engagement Manager modal (§2.7).

The user then signs in normally — their assignments populate, the working papers they own appear under their fieldwork view, and they can resume work.

13.3.3 Conflict handling

If you Pull an engagement that already has a local copy with newer changes (e.g. you worked offline for a week), JKO does not automatically overwrite. It shows a Pull confirmation dialog: "Local copy is newer (last modified [date]). Overwrite with backend version?" — choose carefully. The Pull always replaces the local copy; if you want to merge, push your local changes first, then pull.

13.4 Working offline

JKO is offline-tolerant by design. If you start a session in backend mode and your internet drops mid-edit, the app silently falls back to local mode:

• Auto-save continues to write to localStorage (and Firebase / Supabase if configured).
• The 🔐 badge in the sidebar footer dims.
• The next backend-only operation you attempt (e.g. clicking the AI Assistant button if your Anthropic key lives on the backend) shows a "Backend Unreachable" toast with the suggestion to keep working and try again when connectivity returns.

When connectivity is restored:

• The next autosave that fires (within 800 ms of your next edit) automatically resumes pushing to the backend.
• Any engagement state you wrote during the outage is reconciled with the backend's last-known version. The newest write wins — so if no one else edited the same engagement during your outage, your offline changes go up cleanly. If someone did, the loser is queued in the Pending Submissions queue (§12.2) for a Partner / Manager to merge.

This is JKO's offline-first contract: never lose work because of connectivity, and never silently overwrite someone else's changes.

13.5 Backend user management — Partner-only

A red-bordered card in the Admin Panel titled 👥 Backend User Management with the strap "Edit roles, reset passwords, deactivate accounts on the backend — Partner-only". A 🔄 Refresh button in the top-right.

The card body lists every backend user with inline controls:

• Role dropdown (Partner / Manager / Senior / Junior)
• Active checkbox
• 🔑 Reset Password button (the same one-time-display flow as §4.6)

The same safety rails apply: a Partner cannot demote themselves, cannot deactivate themselves, cannot remove their own account.

This card is the backend-mode equivalent of the local Admin Panel user table. When a firm is in backend mode, this is the source of truth for user records — local-mode user editing should be avoided, otherwise the two tables drift.

13.6 Firm-wide data export — Partner-only

A purple-bordered card in the Admin Panel titled 📦 Firm-Wide Data Export with the strap "Download every user, engagement, ACL row and audit-log entry for this firm in a single JSON archive — for regulator inspection, periodic backups or platform migration". A ⬇ Export Firm Data button.

Click the button: the backend assembles a single JSON archive containing:

• Every user record (with bcrypt password hashes)
• Every engagement record + complete state
• Every ACL row (member × engagement × area)
• The complete audit log (with hash chain intact)
• The firm's subscription history
• Welcome-pack send history
• Any uploaded AFS files (base64-encoded with original filenames)

Download time depends on size — a small firm with a handful of engagements is a few hundred KB; a large firm with years of history can be tens of MB. A status line at the foot of the card shows progress and the final filename.

This is the bundle to hand the regulator on inspection, the backup to take before a major upgrade, and the artefact that lets you migrate to a different JKO deployment if you ever need to.

AI features

JKO embeds Anthropic Claude at every point in the audit workflow where a structured language model genuinely speeds up the work — not for novelty, but to compress the parts of the job (commentary, drafting, extraction) that are normally hours-long manual labour. The same AI panel powers ten different features, ten 🤖 buttons scattered across the app.

JKO's AI is also provider-agnostic: while Anthropic is the default, the panel lets you switch to Google Gemini, OpenAI, Groq, or OpenRouter — useful when a client requires a specific provider or when you want to test outputs across models.

14.1 The AI panel

The AI panel is launched from the 🤖 AI Assistant (Claude) button at the bottom of the sidebar footer, or from any 🤖 AI Help button in the topbar. It slides in from the right.

14.1.1 Header

• 🤖 icon, "AI Audit Assistant" title, "Powered by Claude · Ghana Practice" strap, ✕ close button.

14.1.2 The provider dropdown

A field labelled AI Provider at the top of the panel. Five options:

The label below the dropdown updates with the provider's required key format: "Claude API Key (stored locally)" / "Gemini API Key" / etc.

14.1.3 The API key field

A password-style input with a Save Key button next to it. The key is stored in browser localStorage in local mode — never sent anywhere except to the chosen provider's API. In backend mode, the firm's key is held server-side and this field is hidden.

A help line below the key field links to console.anthropic.com to get an Anthropic key.

14.1.4 The five quick-prompt chips

Below the key, five one-tap chips that pre-fill the textarea with a focused prompt:

• ⚠️ Risk Commentary — "Analyse the current Risk Matrix and write a planning-stage narrative…"
• ✉️ Draft Mgmt Letter — "Draft a management letter from the Exceptions Log…"
• 📄 Suggest Opinion — "Based on the Misstatement Schedule and going-concern flag, recommend an audit opinion with supporting rationale…"
• 📊 Explain Ratios — "Interpret the analytical-procedures ratios for this engagement…"
• 📚 ISA Guidance — "Explain the relevant ISA standards for this audit area…"

Each chip is a starting point — you can edit the prompt before sending.

14.1.5 The chat transcript and textarea

A scrolling message area renders user / assistant turns with avatars. The textarea at the bottom is where you type free-form questions; Enter sends, Shift+Enter newline.

A Send ↑ button is visible to the right of the textarea.

14.2 The ten AI features, in context

Every 🤖 button in the app uses the same AI panel under the hood, but with a feature-specific system prompt. Here's the full inventory:

14.3 Where the AI key lives

A diff in security: backend mode means the AI key never crosses your firewall to a user device. Local mode means trust is distributed — fine for solo practitioners, less ideal for a firm with five Juniors who shouldn't be trusted with a five-figure-monthly Anthropic key.

14.4 AI-call quotas (backend mode)

When the firm is on the cloud backend, AI calls are rate-limited to prevent runaway bills:

• Standard plan — 30 AI calls per user per hour. Server-side enforcement; the 31st call in the hour gets a 429 toast: "Rate limit hit (30 calls/hr). Try again in N minutes."
• Pro plan — unlimited. Available on request; typically applied to firms doing high-volume tax audits or ISQM rollouts.

Calls counted: every Generate / Draft / Enhance / Extract / Commentary button. Free-form chat messages also count, one call per message.

In local mode there are no JKO-imposed quotas — the user is rate-limited only by Anthropic's account-level limits.

14.5 What Claude is and isn't told

JKO sends Claude only the data it needs for the requested task:

• The task-specific prompt describing what to do (e.g. "Generate ISA 315 risk commentary…")
• The relevant slice of engagement state — for risk commentary, the Risk Matrix; for analytical commentary, the ratios and movements; for lease extraction, the PDF text.
• Firm-style hints if your firm has configured a house-style preamble in the Admin Panel.

Claude is not told:

• The client's TIN, phone numbers, addresses, or other PII unless the user has typed them into a relevant field
• The audit log
• Other engagements you have on the device
• The firm's user list

This is a deliberate "minimum necessary" posture. You can verify what's being sent by using the 👁 Preview option that appears in some AI flows (e.g. lease extraction, AI Enhance). For the chat panel, the message bubbles are exactly what's sent.

14.6 The cost — and how to control it

AI consumption is billed separately from your subscription (§3.1) — it's the AI API key component, passed through at the prevailing Anthropic rate. Spend scales with usage: light engagements use very little; heavy AI users — firms running every JET, every lease, every ISQM through Claude — can spend an order of magnitude more.

To control spend:

• Use AI sparingly on routine engagements. A small audit doesn't need AI commentary on every page; reserve it for the planning narratives and the final report polish.
• Prefer Claude Haiku for simple tasks — JKO's default model is cost-tuned. The Admin Panel exposes a model override if your firm wants to lock to a specific model for cost control.
• Cache where possible. The "AI Polish" buttons cache their output on the engagement; click again only when the underlying content has changed.
• Watch the Subscription card — the live quote callout reminds you that Anthropic consumption is excluded from the licence fee.

Data security & retention

JKO is built to satisfy three audiences at once: the partner (who needs the data to be safe), the regulator (who needs it to be inspectable), and the IT-savvy client (who wants to understand exactly where their financial information sits). This chapter is the answer to "what happens to our data?".

15.1 Where data lives

The location depends on whether you're in local mode or backend mode (§13).

15.1.1 Local mode

The single point of risk in local mode is the device itself. JKO recommends device-level disk encryption (BitLocker on Windows, FileVault on macOS) for any device that holds engagement data — this is the standard ICAG good-practice baseline.

15.1.2 Backend mode

In backend mode, the user's browser localStorage continues to mirror the engagement state for offline tolerance (§13.4) — but the source of truth is the backend. Clearing browser data on a backend-mode device only logs the user out; the engagement is still safely on R2.

15.2 The audit log — what it is and how to read it

JKO maintains a hash-chained, append-only audit log of every high-stakes mutation. The log lives engagement-scoped (one log per engagement, plus a firm-level log on the backend) and is always growing — there is no "delete log entry" path in the UI.

15.2.1 What gets logged

Every event that has audit / regulatory significance:

Each entry captures: timestamp, user (username + role), action (the code from the table above), target (the affected entity — user:aowusu, engagement:eng_xxx, etc.), summary (free text), and two hash fields.

15.2.2 The hash chain

Each entry's hash is computed as:

hash = sha256(prevHash + ts + user + action + target + summary)

The first entry in the chain has prevHash = "". Every subsequent entry's prevHash points at the previous entry's hash. Mutating any entry invalidates that entry's hash; the next entry's prevHash no longer matches the upstream hash; and every downstream entry breaks the chain.

15.2.3 Verifying integrity

A diagnostic function verifyAuditLogIntegrity() walks the chain, recomputes each hash, and compares against the stored value. The Admin Panel exposes a "🔍 Verify Audit Log Integrity" button (Partner only) that calls this function and shows the result:

• ✅ Chain intact — N entries verified
• ❌ Chain broken at entry N (timestamp X) — manual investigation required

A broken chain is rare and serious. Typical causes:

• Direct localStorage manipulation (a developer reading the JSON, editing, and saving back)
• Disk corruption
• A bug in the writer (open a support ticket)

In backend mode the verification also walks the server-side log; a broken backend chain points to a security incident and should be reported immediately.

15.3 Retention policy

You can override these defaults at the firm level — e.g. set audit log to be exportable and trimmed annually — by configuring the firm's policy in the Admin Panel maintenance card. The defaults are designed to satisfy ICAG inspection without requiring tuning.

15.4 Compliance posture

JKO's defaults map to common audit-firm regulatory expectations:

• ISA 230 (Audit Documentation) — retention: at least the assembly-period retention required by your jurisdiction. JKO's default is unlimited; configurable per firm if you want to set a hard floor.
• Ghana Companies Act 2019: companies must retain financial records for 6 years after the end of the financial year (per §131(3)). JKO recommends a 7-year retention practical minimum to give a one-year buffer.
• ICAG (Institute of Chartered Accountants Ghana) inspection: ICAG can request the full audit file at any time. The Admin Panel → 📦 Firm-Wide Data Export (§13.6) produces the canonical inspection bundle in a single JSON file.
• GDPR / Ghana Data Protection Act 2012: client PII (director names, dates of birth, ID numbers from §6.1's Section D) is processed under "legitimate interest" for audit purposes. The JKO Privacy Notice (Admin Panel → firm profile → Privacy Notice) is the firm's standing notification to engagement clients.
• AML Act 2020: Section C of acceptance plus the AML transaction-sample card on the Banking module (§9.0.6) cover the firm's testing obligations. STR / CTR filings happen outside JKO with the FIC (Financial Intelligence Centre); JKO records that the filings were made.

15.5 Watermarking and source traceability

When a Partner downloads a copy of the audit software for a team member (the ⬇ Download Audit Software button in the Welcome Pack modal, §4.3), the downloaded HTML is stamped with a unique signed token baked into the file. The token encodes:

• The firm ID
• The recipient user ID
• The download timestamp
• A signature using the firm's signing key (held server-side; not derivable from the HTML itself)

If a downloaded copy ever appears in the wild — leaked online, found on a competitor's machine, distributed without authorisation — the token can be read by JKO support and traced back to the firm and the specific download event.

Practical implications:

• The token is verified by the backend on each authenticated request. A revoked token (e.g. when a team member leaves and the Partner deactivates them) refuses sign-in.
• Stripping the token from the HTML breaks sign-in entirely — the file becomes a useless local-mode app with no sync, no AI key, no subscription.
• The token is invisible to the user — it lives in a metadata block at the top of the file and is not displayed in the UI.

This is the firm's protection against unauthorised distribution. In a regulated industry where the audit working papers contain the client's most sensitive financial information, that protection matters.

15.6 What to do if you suspect a breach

A pragmatic playbook:

1. Immediately rotate the Anthropic API key (backend mode: Admin Panel → AI; local mode: each user replaces their key).
2. Force-revoke all refresh tokens by changing the backend's signing key (a Cloudflare Worker secret rotation). Every session is logged out.
3. Run 🔍 Verify Audit Log Integrity on every engagement on the device. Log any breaks for the incident report.
4. Pull the Firm-Wide Data Export as a pre-incident snapshot.
5. Notify ICAG if the breach involved client data — Ghana data-protection law has a 72-hour notification window.
6. Open a JKO support ticket with the firm ID, the suspected window of exposure, and the audit-log verification report.

JKO's role in a breach is to give you the forensic tools (the hash chain, the watermarks, the firm-wide export); the regulatory response is yours to lead.

Troubleshooting

Each entry: the message you see, why it's happening, how to fix it.

16.1 "Browser storage is blocked"

Symptom. Yellow banner at the top of the auth screen: "⚠️ Browser storage is blocked. Your account cannot be saved."

Cause. Your browser is in incognito / private / InPrivate mode, or has localStorage disabled at the browser-policy level (common on locked-down corporate machines).

Fix. 1. Close the incognito window. 2. Open the JKO HTML file in a normal Chrome or Edge window. 3. If the warning persists in a normal window, your browser has explicitly blocked storage — go to Settings → Privacy and security → Cookies and site data → Allow all (or whitelist your local file). 4. If you're on a corporate-managed laptop, ask IT to whitelist localStorage for file:// URLs. Many firms block this by default.

16.2 "Subscription required (402)"

Symptom. Toast or banner: "Subscription required (402)". Saves and AI calls fail.

Cause. Your firm's trial or paid subscription has expired. The backend returns HTTP 402 Payment Required for every authenticated write.

Fix. Sidebar → ⚙️ Admin Panel → 💳 Subscription & Billing. Click 🔄 Refresh to confirm the current state, then 💳 Pay / Renew Annual Licence (Partner or Manager). After Paystack returns, click 🔄 Refresh and the banner should turn green.

If you're a Senior or Junior, you cannot fix this yourself — escalate to a Partner or Manager immediately.

16.3 "Backend Unreachable"

Symptom. Toast: "Backend Unreachable". The 🔐 sidebar badge dims.

Cause. Your internet has dropped, the Cloudflare Worker is down, or your firm's firewall blocks Cloudflare traffic.

Fix. Keep working — JKO has fallen back to local mode (§13.4) and your edits are still saving to localStorage. When connectivity returns, sync resumes automatically. If the message persists for more than 15 minutes when your internet is otherwise working:

1. Try a different network (tether to your phone briefly).
2. Check your firewall allows traffic to *.workers.dev.
3. If still blocked, contact JKO support with your firm ID — there may be a backend incident.

16.4 "Too many failed attempts — account locked for 15 minutes"

Symptom. Sign-in is refused even with the correct password.

Cause. Five wrong passwords in a row triggered a 15-minute lockout on this user account.

Fix. 1. Wait 15 minutes — the lockout clears automatically. 2. Or: have a Partner reset your password (Admin Panel → Team Members → 🔑 Reset Password).

The lockout window is hard-coded; it cannot be shortened in the UI.

16.5 "Session expired due to inactivity"

Symptom. "Signed out due to inactivity" toast. You're bounced to the auth screen mid-task.

Cause. 30 minutes of no keystroke / mouse activity in JKO. The session is server-side-revoked for security.

Fix. Sign in again. Your work is auto-saved (§5.2) so nothing is lost. The 30-minute window is a global setting; it is not configurable per user.

If you regularly hit this during long client meetings where you're reading the manual aloud rather than typing, keep a finger on the screen — any input resets the timer.

16.6 "Cannot deactivate your own account"

Symptom. Toast on toggling your own Active checkbox: "You cannot deactivate yourself."

Cause. A safety rail to prevent the last Partner locking themselves out (§4.7).

Fix. Have another Partner deactivate your account. If you're the only Partner, promote a Manager to Partner first.

16.7 "A Partner cannot demote themselves"

Symptom. The Role dropdown on your own row is greyed out.

Cause. Same safety rail. JKO refuses to let the last Partner self-demote.

Fix. Promote another user to Partner first; have them demote you.

16.8 The AI button does nothing

Symptom. Click 🤖 AI Help / 🤖 Generate / etc., nothing happens, no toast.

Causes (check in order):

1. Local mode + no API key configured. Sidebar → 🤖 AI Assistant → enter the API key for your provider, click Save Key.
2. Backend mode + subscription expired. Renew (§16.2).
3. Backend mode + rate limit hit. Wait for the next hour boundary (§14.4 — 30 calls/user/hour on Standard plan). The 31st call shows a 429 toast: "Rate limit hit (30 calls/hr). Try again in N minutes."
4. Backend mode + Anthropic upstream is down. Rare; the toast will say "AI provider unreachable". Wait and retry.
5. Wrong provider for the prompt. Some flows (e.g. lease extraction §9.2) require Anthropic Claude specifically and may not work with Groq's free tier. Check the AI panel's Provider dropdown.

16.9 Data lost after refresh

Symptom. You opened a fresh tab and your engagement is empty.

Causes:

• Incognito mode — localStorage is wiped when the window closes (§16.1).
• You cleared browsing data — including localStorage, in your browser's Settings → Clear browsing data.
• A different browser profile — your data is in the profile you originally signed in on.
• A different device — local-mode data does not roam.

Fix.

• If you're in backend mode, your engagements are safe on R2 — Pull them again (§13.3).
• If you're in local mode with a configured save folder (§5.2), the JSON backup in the folder is your last-write copy — re-import it via the Admin Panel maintenance card.
• If neither, the data is gone. This is the "always configure backend or local-folder save" lesson, learnt the hard way.

16.10 "Version conflict" on save

Symptom. Save fails with a "Version conflict" toast.

Cause. Two users edited the same engagement simultaneously on different devices. The first save through wins; yours arrives stale.

Fix. 1. Pull the latest version from the backend (§13.3) to get the current state. 2. Your in-flight edit is queued in the Pending Submissions queue (§12.2) for a Partner / Manager to review. 3. They open the Full Diff modal, see what you changed vs what's now live, and Accept or Reject. 4. If Accepted, your changes are merged. If Rejected, you'll see a notification with the reviewer's note explaining why.

This is JKO's deliberate "no silent overwrites" model.

16.11 The print layout looks wrong

Symptom. Print preview shows truncated tables, missing sidebar, or weirdly-spaced cards.

Cause. JKO's print stylesheet hides interactive controls (sidebar, action buttons, edit boxes) and re-flows tables for portrait A4. Large tables (e.g. the full Disclosure Checklist) are wider than A4 and will be split.

Fix. 1. For a section export, prefer 📥 Export Excel over Print — Excel handles wide tables natively. 2. For a printed audit file, the 🖨 Print button on each section is intended for in-section printing. Print one section at a time rather than the whole engagement. 3. For a single PDF of the full engagement, use Chrome's print → Save as PDF, set paper size to A3 for wide tables.

16.12 Drag-drop file upload doesn't trigger

Symptom. Dragging an Excel/PDF over a drop-zone doesn't change the zone's colour or upload the file.

Cause. The browser's drag-and-drop handler is being intercepted by an extension (most often a tab manager or screenshot tool), or you're on a browser where drag-drop is disabled (older Firefox).

Fix. Click the drop-zone instead of dragging — the file picker opens, and selecting a file uploads it the same way. If you must use drag-drop, disable browser extensions one at a time to find the culprit.

16.13 Excel export downloads an empty file

Symptom. A click on 📥 Download Excel produces a 0-byte file.

Cause. Either (a) the section has no data yet (e.g. exporting a Risk Matrix before any rows are populated), or (b) browser is blocking the download.

Fix. Confirm there is data on the section. If yes, check your browser's download settings — some configurations block automated downloads from file:// URLs. Allow downloads, then retry.

16.14 The Engagement Manager modal is empty

Symptom. Clicking the Active Client name opens an empty modal.

Cause. No engagements have been created on this device yet, OR you're signed in as a Junior / Senior with no team assignments.

Fix. - Partner / Manager: click ＋ New Engagement in the sidebar footer to create the first one. - Junior / Senior: ask your Partner to assign you to an engagement (Engagement Setup → Team Assignment, §2.6 / §6.2).

16.15 The PDF lease extraction returns gibberish

Symptom. §9.2's AI Extract IFRS 16 Inputs button returns nonsense — wrong dates, empty fields, made-up numbers.

Cause. The PDF is a scanned image with no text layer, or the text layer is corrupt. Claude can read text-layer PDFs but does not OCR.

Fix. Run the PDF through an OCR tool (Adobe Acrobat's Recognise Text, or ocrmypdf if you're technical) to add a text layer, then re-upload to JKO and re-extract.

Glossary

Audit firms work with a dense vocabulary. This glossary covers every abbreviation, term, and JKO-specific concept that appears in this manual, in alphabetical order.

Support & contact

• In-app: AI Assistant (sidebar) for general audit queries.
• Email: support@jko-audit.local (replace with your actual support address)
• Documentation updates: This manual is versioned with the software. Always check the version number at the top.

JKO Audit Solutions — built for Ghana SME audit firms · ISA-aligned · ICAG-compatible.