Nuqsaf Methodology

This document is the full methodology for Nuqsaf v2. All 13 numbered sections are included below. Sections 1–5 and 11–13 supersede the corresponding sections in v0.2; sections 6–10 are new.

1. Scope

1.1 What this methodology covers

Nuqsaf is a halal financial operating system for Muslim households. It reads a user's bank and brokerage data (via Plaid, read-only), applies Islamic finance rules, and produces artefacts the user can act on: purification reports, zakat estimates, values reports, investment screens, inheritance distributions, and scholar-cited answers to fiqh questions.

This document is the single source of truth for the rules Nuqsaf applies. It answers five questions:

1. What counts as riba, and how much of a user's income should be purified?
2. How is zakat calculated from a user's assets, and when is it due?
3. Which holdings in a brokerage account are Sharia-compliant, and how are their dividends purified?
4. Which merchants surface as values conflicts, and at what strictness?
5. How is an estate distributed under classical Mirāth rules?

It also describes two engineering surfaces that touch fiqh: the AI assistant (Ask Nuqsaf) and auto-purification (Stripe Connect to partner charities).

1.2 Product surfaces in scope

• Annual Riba Purification Report — the wedge. A 12-month identification of interest income and dividend income, with a single dollar amount to discharge as sadaqah.
• Nuqsaf Monthly subscription — real-time purification, monthly mini-PDFs, zakat engine, unlimited household members.
• Zakat engine — nisab detection, hawl tracking, asset-class calculation, discharge ledger.
• Values layer — merchant-level classification for alcohol-, pork-, gambling-, and tobacco-adjacent spending.
• Investment screening — AAOIFI-style screens on brokerage holdings, with dividend purification.
• Auto-purification — optional Stripe Connect flow that discharges flagged interest to partner charities.
• Ask Nuqsaf — scoped AI assistant grounded on the rulings library and the user's own transactions.
• Mirāth assistant — classical Sunni (with Ja'fari option) inheritance distribution engine.

1.3 What remains outside scope

The following are explicitly outside scope even in v2:

• Real-time chat with a human scholar. Ask Nuqsaf is an AI assistant with strict refusal rules (§10). For live fiqh counsel, Nuqsaf links users to Ask-a-Scholar, which is an async, paid, human-reviewed service — not part of this methodology.
• Zakat on non-financial assets Nuqsaf cannot see. Gold, silver, physical cash, jewellery, business inventory, agricultural produce, livestock, and debts owed to the user are not covered by the automatic zakat engine. Users must add these manually or consult a scholar.
• Crypto halal screening beyond Bitcoin. Only Bitcoin has a ruling in the v1 library. Altcoins, stablecoins, and DeFi activity are not screened.
• Riba al-fadl in currency exchange, commodity trades, or derivatives. Nuqsaf does not analyse the mechanics of FX or derivative instruments. Users with such activity should consult a specialist.
• Mortgage and loan structure permissibility. Nuqsaf identifies interest paid and received as they appear in transaction data. It does not classify specific loan products (including those marketed as “Islamic”) as permissible or impermissible.
• Business income and corporate zakat. Users who receive business income through personal accounts should consult a scholar. Nuqsaf treats all transactions in a linked account as personal transactions.
• Non-US financial institutions. Plaid coverage is primarily US. UK and other regions will be addressed in a later version.

1.4 Why scope expanded (but not to everything)

v0.2 was deliberately narrow because v1 sold a single artefact: the annual riba purification PDF. v2 sells an ongoing relationship: monthly subscriptions, widgets, auto-purification, weekly summaries, inheritance help. That relationship requires more of a user's financial life to be in the model.

The expansion follows one rule: add a surface only if the core rule is either universally agreed upon or has a conservative default that no reasonable scholar would reject. That means:

• Zakat is in, because the fact of zakat and its 2.5% rate is ijma across all madhhabs. Disagreements at the margin (nisab standard, asset-class treatment) are handled via conservative defaults and user override.
• Investment screening is in, because AAOIFI Standard 21 is the closest thing to a global Sharia benchmark and every major Muslim index provider uses a variant of it.
• Values layer is in with strictness toggles, because scholarly opinion on incidental exposure at mixed-use merchants varies. The user picks their own strictness (§8).
• Mirāth is in because the classical rules are deterministic given inputs, and the engine is reviewed by a named scholar before launch.
• The AI assistant is in because refusing to answer is cheap and well-bounded — it cites a ruling or it declines.

2. Definition of riba

2.1 Riba in the Quran

The prohibition of riba is one of the strongest and most repeated financial rulings in the Quran. The following verses are the primary sources cited in every classical and modern treatment of riba:

Al-Baqarah 2:275

“Those who consume interest cannot stand [on the Day of Resurrection] except as one stands who is being beaten by Satan into insanity. That is because they say, ‘Trade is [just] like interest.’ But Allah has permitted trade and has forbidden interest.”

Al-Baqarah 2:276

“Allah destroys interest and gives increase for charities. And Allah does not like every sinning disbeliever.”

Al-Baqarah 2:278–279

“O you who have believed, fear Allah and give up what remains [due to you] of interest, if you should be believers. And if you do not, then be informed of a war [against you] from Allah and His Messenger. But if you repent, you may have your principal — [thus] you do no wrong, nor are you wronged.”

Al-Imran 3:130

“O you who have believed, do not consume usury, doubled and multiplied, but fear Allah that you may be successful.”

An-Nisa 4:161

“And [for] their taking of usury while they had been forbidden from it, and their consuming of the people's wealth unjustly. And we have prepared for the disbelievers among them a painful punishment.”

Al-Rum 30:39

“And whatever you give for interest to increase within the wealth of people will not increase with Allah. But what you give in zakat, desiring the countenance of Allah — those are the multipliers.”

The Quranic position is unambiguous: riba is forbidden. The language in Al-Baqarah 2:279 (“war from Allah and His Messenger”) is the most severe framing used for any financial prohibition in Islamic scripture.

2.2 Riba in the hadith literature

The Prophetic tradition further clarifies and extends the Quranic prohibition. The following hadiths are widely cited in classical and modern works and are considered sahih (authentic) by the major hadith scholars:

• The Prophet (peace be upon him) cursed the one who consumes riba, the one who gives it, the one who records it, and the two witnesses to it, saying: “They are all alike [in sin].” — narrated in Sahih Muslim, the Book of Transactions.
• “Riba has seventy-three chapters, the least of which is like a man committing incest with his own mother.” — narrated in Sunan Ibn Majah and other collections.
• The “six commodities” hadith, in which the Prophet (peace be upon him) said: “Gold for gold, silver for silver, wheat for wheat, barley for barley, dates for dates, and salt for salt — like for like, hand to hand. Whoever gives more or takes more has engaged in riba.” — narrated in Sahih al-Bukhari and Sahih Muslim.

2.3 Two categories of riba

Classical Islamic jurisprudence distinguishes two categories of riba:

Riba al-nasi'ah (“riba of delay”) is the predetermined increase on a loan as compensation for time. This includes interest on savings, checking, money market, CDs, bonds, sweep accounts, credit card balances, and peer-to-peer lending returns.

Riba al-fadl (“riba of excess”) is the exchange of certain commodities for the same commodity in unequal quantities, based on the six-commodities hadith. Modern scholars extend this by analogy (qiyas) to currency exchanges, gold and silver trades, and some derivative instruments.

2.4 What Nuqsaf identifies as riba

Nuqsaf identifies riba al-nasi'ah — predetermined interest income earned on money held in conventional financial institutions.

Specifically included:

1. Interest income on savings, checking, and money market accounts.
2. Interest income on certificates of deposit (CDs) — periodic or maturity-date.
3. Interest income on brokerage cash balances and conventional money-market fund distributions.
4. Dividend income from conventional (non-screened) brokerage holdings, purified per §6.

Nuqsaf does NOT treat the following as purification-eligible income:

• Interest paid by the user on loans and credit cards. This is tracked separately for awareness; the appropriate response is tawba and faster repayment, not purification.
• Riba al-fadl in FX, commodity trades, or derivatives.
• Business interest income received through a business the user owns.
• Inflation adjustments, stock buybacks, return of capital, and principal repayments.

2.5 Summary of the position

Conventional bank interest (riba al-nasi'ah) is unambiguously prohibited by the Quran, the Sunnah, and the ijma of the Sunni madhhabs. A Muslim who holds money in a conventional bank account and receives interest income is under an obligation to identify that income and discharge it as sadaqah with no expectation of personal reward.

3. How transactions are identified as interest

3.1 Data source

Nuqsaf connects to US financial institutions via Plaid (a regulated bank data aggregator). Plaid provides transaction history, metadata (name, merchant, amount, date, category), and account information. Nuqsaf has read-only access — it cannot initiate transactions or move money. The auto-purification flow (§12.2) uses a separate, user-consented Stripe payment rail, not Plaid.

3.2 Interest RECEIVED detection (the purification pipeline)

Interest received is detected using a three-tier pipeline:

Tier 1: Heuristic pre-filter. Every transaction is checked against rules that do not require AI: Plaid's personal finance category (INCOME_INTEREST_EARNED, INCOME_DIVIDENDS), name pattern matching (interest, dividend, APY, yield), and account context. Transactions that pass none of these checks are classified as “Clear” at 99% confidence. This eliminates ~90% of transactions from AI processing.

Tier 2: AI verification. Transactions passing the pre-filter are sent to a language model (Claude Sonnet, Anthropic) in batches of up to 20. The model classifies each as clear, needs purification, or needs review, with confidence scores and reasoning. The AI does not make the final decision.

Tier 3: User review and override. Every flagged transaction is presented to the user. For each, the user sees the merchant name, amount, AI reasoning, and two buttons: Confirm (include in purification total) or Exclude. The user's decision is final and is written to an audit log.

3.3 Real-time (subscription) pipeline

For Nuqsaf Monthly subscribers, Plaid webhooks stream new transactions as institutions post them. Each new transaction runs the same three-tier pipeline nightly; anything flagged queues for review or, if auto-purification is enabled (§12.2), for charitable discharge at month-end.

3.4 Interest PAID detection

Interest the user pays on credit cards and loans is tracked separately. Detection uses name pattern matching (interest charge, finance charge, intrst chrg). Results are grouped by account and month. This is for awareness — you cannot purify money you paid to someone else. The correct response is tawba, faster debt payoff, and a scholar consultation on restructuring.

3.5 Validation

The classification pipeline is validated against a hand-labeled ground-truth dataset: ≥95% precision (of all flagged transactions, ≥95% are actually interest) and ≥90% recall (of all actual interest transactions, ≥90% are caught). This runs in CI on every code change. The initial fixture is 200 transactions; the plan is to grow it to 2,000 by month 6 via opt-in user contributions.

4. Treatment of dividends

When a user holds conventional stocks or mutual funds and receives dividends, should those dividends require purification? Three scholarly positions exist:

• Position A (AAOIFI): Dividends from conventional stocks require purification in proportion to the issuing company's non-permissible income. A formula is applied (see §6.4).
• Position B (some Hanafi scholars): Only dividends from clearly haram companies require purification; others are tolerable incidental impurity.
• Position C (strictest): The entire investment in a conventional stock is impermissible; dividends are merely one symptom.

Nuqsaf's default: Position A (AAOIFI). When a user has connected a brokerage account and enabled investment screening (§6), Nuqsaf computes a purification amount per holding per dividend. When screening has not been enabled, Nuqsaf falls back to a conservative blanket rule: all dividends from non-screened conventional holdings are treated as 100% purification-eligible. Users can Exclude individual dividends during review if they have independently verified Sharia compliance of a specific holding.

5. Madhhab choice and scholarly consensus

5.1 Areas of universal agreement

All four Sunni madhhabs (Hanafi, Maliki, Shafi'i, Hanbali), the Ja'fari school, AAOIFI, and the OIC Islamic Fiqh Academy agree: riba al-nasi'ah is categorically prohibited, conventional bank interest is riba, interest income must be disposed of via sadaqah, and zakat is due annually at 2.5% on wealth above nisab held for one hawl.

5.2 Areas of minor disagreement

Disposal method: Majority says give to the poor as charity (no reward). Minority (some Hanafi scholars) allows use for public infrastructure (roads, sanitation). Nuqsaf's discharge guidance follows the majority (§12).

Dividend purification: See §4. Positions range from “all require purification” to “only clearly haram companies.” Nuqsaf defaults to Position A.

Nisab standard for zakat: Silver (~612g) vs gold (~87g). Nuqsaf defaults to silver (more conservative — lower threshold → more qualifying wealth → more zakat owed). Users can override (§7.1).

Mirāth: Sunni and Ja'fari schools differ structurally (§9). Nuqsaf defaults to the Sunni (majoritarian) engine, with Ja'fari available as an explicit choice for users who identify it.

5.3 Nuqsaf's approach

Nuqsaf does not follow a single madhhab. Instead: (1) core identification follows the ijma position all madhhabs share, (2) conservative defaults are applied wherever positions diverge, (3) user override is available for every classification and every setting where diversity exists, (4) the rationale for every default is written down in this document. This approach works for Hanafi, Shafi'i, Hanbali, Maliki, and Ja'fari users alike — and fails loudly for users with a position Nuqsaf has not yet documented, rather than silently producing wrong output.

6. Halal investment screening (AAOIFI Standard 21)

6.1 The benchmark

Nuqsaf screens brokerage holdings against AAOIFI Shariah Standard No. 21 (Financial Paper — Shares and Bonds). AAOIFI is the Accounting and Auditing Organization for Islamic Financial Institutions; its standards are the closest thing to a global benchmark in Islamic finance and are adopted by regulators in Bahrain, Oman, Qatar, Sudan, Syria, the UAE, and by every major Sharia index provider in a variant form.

6.2 Business activity screen

A company is excluded outright if its primary business activity is impermissible. Primary-haram industries include: conventional banks, insurance (non-takaful), alcohol production and distribution, pork processing, tobacco, adult entertainment, gambling and casinos, and conventional defence contractors whose revenue is materially tied to indiscriminate weapons.

6.3 Financial ratio screens

A company whose primary activity is permissible must also pass three financial ratios. All ratios are computed against the trailing 24-month average market capitalisation (the AAOIFI denominator), not total assets.

A company that fails any one ratio is non-compliant for the screening period and is excluded from halal-pass status. Thresholds are AAOIFI's; some other index providers (Dow Jones Islamic, S&P Shariah, MSCI Islamic) use 33⅓% for the debt and liquidity ratios and variants of the income ratio. Nuqsaf uses the stricter AAOIFI figure as its default and flags any holding that is non-compliant by AAOIFI but compliant by 33⅓% provider rules, so the user can make an informed override.

6.4 Dividend purification formula

For holdings that pass the screen but have non-zero non-permissible income, the dividend must be partially purified. Nuqsaf uses the AAOIFI-style formula:

NPI% = Interest Income ÷ (Operating Profit + Interest Income)

Purification amount = NPI% × dividend received

Where Interest Income and Operating Profit are taken from the issuer's most recent audited annual filing (10-K for US-listed companies). The purification amount is added to the user's purification total for that period. The remaining dividend after purification is the user's lawful earnings.

6.5 Data sources and limitations

Nuqsaf reads brokerage holdings via Plaid Investments. For each US-listed ticker it caches: the primary industry classification (excluded or not), the three AAOIFI ratios from the latest 10-K, and the NPI% for dividend purification. Data is refreshed quarterly or on earnings. Mutual funds and ETFs are screened at the fund level where an AAOIFI-compliant equivalent exists; where they are not (e.g., a conventional S&P 500 ETF), Nuqsaf treats the holding as non-compliant and flags dividends for 100% purification on the conservative default.

Limitations:

• Private equity, hedge funds, and non-traded securities are not screened.
• Non-US listed equities are screened where data is available; gaps are marked unscreened, not compliant.
• The engine cannot see intra-quarter changes to a company's balance sheet.
• Sukuk and Islamic funds are assumed compliant on trust; users are shown the issuer's declared Sharia board and can override.

7. Zakat methodology

7.1 Nisab

Zakat is due only on wealth above the nisab — the minimum threshold set by the Prophet (peace be upon him). Two standards exist:

• Silver nisab: 612.36 grams of silver (equivalent to 200 dirhams at the time of the Prophet). At April 2026 spot prices, approximately $1,500–1,700 USD depending on the day.
• Gold nisab: 87.48 grams of gold (equivalent to 20 dinars). At April 2026 spot prices, approximately $13,000–14,000 USD.

Nuqsaf defaults to the silver nisab. Rationale: silver yields the lower threshold, so more users qualify, more zakat is owed, and more ends up with the poor. This is the majoritarian contemporary position (cited by Islamic Relief, Zakat Foundation of America, Muslim Aid, and the National Zakat Foundation). Users who follow the gold standard (sometimes argued on the grounds that silver's real purchasing power has collapsed since the Prophetic era) can switch in Settings; the choice is written to users.nisab_preference and used for every subsequent calculation.

Nisab values are pulled live from goldapi.io (with a static silver fallback) each time a user's zakat is computed. The exact spot price used is stamped on the resulting report.

7.2 Hawl

Zakat is due once per lunar year (hawl — 354 days) provided the user's qualifying wealth has remained above nisab for the whole year. Nuqsaf tracks the hawl in two steps:

1. Nisab crossing: the first day the user's zakatable wealth crosses nisab is written to zakat_assets.nisab_crossed_at. The hawl countdown starts from that date.
2. Hawl completion: 354 days after nisab crossing, zakat is due. If wealth drops below nisab during the year, Nuqsaf flags the user for manual review — opinions differ on whether the hawl resets, and Nuqsaf will not silently pick one.

All hawl dates are stored in both Gregorian and Hijri; the reminder UI shows Hijri first.

7.3 Zakatable asset classes

Nuqsaf computes zakat on the following asset classes visible through Plaid:

• Cash and cash-equivalents (checking, savings, money market, brokerage cash) — full balance at 2.5%.
• Receivables (debts owed to the user that are expected to be repaid) — user-entered only; Plaid does not surface these.
• Business inventory held for resale — user-entered only.
• Stocks held for capital appreciation (trader intent) — full market value at 2.5%. This is the majoritarian position.
• Stocks held for long-term dividend income (investor intent) — 2.5% on the zakatable portion (cash, inventory, receivables component of the issuer's balance sheet per the AAOIFI formula), not on the full market value. This is the more nuanced position and requires the user to declare intent per holding.

Non-zakatable:

• Primary residence.
• Personal-use vehicles and household goods.
• Retirement accounts where funds are locked and the user has no present access (contested — Nuqsaf defaults to not zakatable on locked portions, shows the user a note, and lets them override).

7.4 Rate

2.5% (1⁄40) on qualifying wealth at hawl completion. This rate is ijma across all madhhabs.

7.5 Discharge and recipients

Zakat must be given to one of the eight categories of eligible recipients named in Surah At-Tawbah 9:60: the poor, the needy, zakat administrators, those whose hearts are to be reconciled, captives, those in debt, those striving in the path of Allah, and the traveller in need. Nuqsaf's zakat partner-charity list is curated against these categories; the user always selects the recipient.

Unlike purification, zakat does earn reward from Allah. The intention (niyyah) that this is zakat, not sadaqah or purification, should be held at the time of giving.

7.6 Zakat engine limitations

• Nuqsaf cannot see physical cash, gold, silver, jewellery, business inventory, or livestock — user must add these manually.
• Mixed-use gold (jewellery worn vs. investment) is contested across madhhabs; Nuqsaf asks the user to categorise.
• The hawl-drop rule is not automated; drops trigger manual review.
• Agricultural and livestock zakat use different rules (10%/5%/one-in-forty sheep etc.) — not in scope.
• Mining and treasure trove (rikaz) zakat (20%) — not in scope.

8. Values layer — merchant-level classification

8.1 What the values layer does

The values layer surfaces spending at merchants with material exposure to categories many Muslims wish to avoid: alcohol, pork and non-halal meat, gambling and gaming, tobacco and vaping, and adult entertainment. It is separate from the riba flow — values spending does not require purification under the riba rules. It is surfaced for the user's own values alignment and, if a household member chooses, for household accountability.

8.2 Scholarly positions — why this is a toggle, not a default

All four Sunni madhhabs agree on the prohibition of direct trade in, production of, handling of, or serving of alcohol and pork. They diverge on incidental exposure at mixed-use merchants — e.g., buying bread at a grocery store that also sells pork, or dinner at a restaurant that serves alcohol alongside halal food.

• Permissive view (often associated with the Maliki tradition and some contemporary Hanafi scholars): permitted if the transaction does not directly fund the haram and the user is not endorsing or normalising it.
• Restrictive view (often associated with Hanbali applications of sadd al-dhara'i, blocking the means to evil): avoid the merchant entirely, because patronising it enables its overall operation.
• Ghalib / maghlub principle (classical screening heuristic applied across all madhhabs): if the predominant revenue of the merchant is haram, the transaction is treated as haram-adjacent even if the specific item purchased was halal; if haram is the minority and clearly separable, more tolerance applies.

8.3 Nuqsaf's three strictness levels

Users choose one of three settings per category (alcohol, pork, gambling, tobacco, adult):

• Hard avoid. Any transaction at a merchant with any exposure to the category is flagged. Reflects the restrictive view.
• Warn. Transactions at merchants where the category is the predominant revenue are flagged; mixed-use merchants are shown as advisory. Reflects the ghalib heuristic.
• Informational. All exposed transactions are logged but nothing is surfaced as a conflict. For users who want the data without the judgment.

Defaults per category ship as: alcohol=Warn, pork=Warn, gambling=Hard-avoid, tobacco=Informational, adult=Hard-avoid. Defaults can be changed at any time; changes apply going forward and the historical ledger keeps the setting active at the time of each transaction.

8.4 Classification mechanics

Merchant classification uses a two-step pipeline parallel to the riba pipeline:

1. Filter-list match. Community-maintained lists (e.g., the Boycott and Halal-certified filter lists) are checked by merchant name or chain identifier. A match produces a direct classification.
2. AI classification fallback. Unmatched merchants are sent to the same classifier used for riba, with a different system prompt scoped to the values taxonomy. Outputs: no exposure, incidental, predominant, plus a category and a reasoning string.

The user reviews and overrides per-merchant. Overrides are persistent — the next transaction at that merchant uses the user's last decision. Household members see the same classifications; households set a joint strictness.

8.5 What the values layer will not do

• It does not purify. There is no scholarly basis for purifying values-conflicting spending with sadaqah; the correct response is repentance and future avoidance.
• It does not share data with anyone outside the user's household.
• It does not assign a moral score or rank users.

9. Inheritance (Mirāth)

9.1 What the Mirāth assistant does

When a Muslim dies, their estate must be distributed according to Islamic rules before most secular estate planning takes effect. The Nuqsaf Mirāth assistant takes a kinship tree and an asset list from the surviving family, applies classical rules, and produces a distribution PDF that can be handed to the family's lawyer and imam.

The PDF is not a legal document. It is a scholar-reviewed reference calculation. Actual estate execution requires a qualified lawyer in the relevant jurisdiction and, where the family wants the distribution to bind, a compliant will.

9.2 Sunni engine (default)

The default engine implements classical Sunni ‘ilm al-fara'id (the science of ordained shares) as derived from Qur'an 4:11, 4:12, 4:176, and the Sunnah, with the classical Hanafi ordering applied where the madhhabs differ on procedural questions (acceptance of al-aul and al-radd).

1. Funeral expenses deducted first.
2. Debts of the deceased paid next.
3. Bequests (wasiyyah) honoured up to one-third of the remainder, and only to non-heirs.
4. Fixed shares (fara'id) assigned to the 12 Quranic heirs (husband, wife, father, mother, paternal grandfather, maternal/paternal grandmother, daughter, son's daughter, full sister, paternal half-sister, maternal half-sibling, uterine sibling) in the fractions named in the Qur'an.
5. Residue distributed to the asaba (male agnate residuaries) in the classical order (son, son's son, father, paternal grandfather, brother, brother's son, paternal uncle, uncle's son).
6. Al-aul: if fixed shares sum to more than unity, all shares are proportionally reduced.
7. Al-radd: if fixed shares sum to less than unity and there are no asaba, the surplus is returned proportionally to the fixed-share heirs (excluding spouse under the Hanafi rule).
8. Dhawi al-arham (distant kindred): only if no Quranic heir and no asaba exist.

9.3 Ja'fari engine (explicit opt-in)

Twelver Shia users may select the Ja'fari engine. It differs structurally:

• No asaba. The concept of agnate residuaries does not apply.
• Three classes of heirs. Class 1 (parents and descendants) excludes Classes 2 and 3 entirely; Class 2 (grandparents, siblings and their descendants) excludes Class 3; Class 3 (uncles, aunts and their children) inherits only in the absence of the first two.
• Representation (per stirpes). A grandchild stands in place of a deceased parent and takes that parent's share.
• No al-aul. If fixed shares exceed unity, the reduction is borne only by specific heirs according to Ja'fari rules, not proportionally.
• Al-radd applies but the distribution differs from the Sunni outcome because of the different classification.

9.4 Scope of the engine

• Monogamous marriage is assumed by default. Polygamous cases are supported with explicit entry of each wife.
• Non-Muslim heirs are excluded per classical rules; Nuqsaf flags the exclusion so the family can consult a scholar on contemporary positions.
• Adopted children do not inherit as children under classical rules; they may be named in wasiyyah up to one-third.
• Simultaneous death (all die in the same event, order unknown) follows the classical rule that none inherits from the other.
• Jurisdictional overlay is not attempted. Many US states override Islamic inheritance rules under statutory defaults; the PDF states clearly that it is the Islamic distribution, not a legal one.

9.5 Scholar review

The Mirāth engine is reviewed by a named scholar before launch and the scholar is listed on the methodology page. Every distribution is stamped with the engine version and the scholar's name. Disputes are routed to the scholar before the family acts. This is a life-and-family-sensitive feature; Nuqsaf will not ship it without a named scholar on the record.

10. Ask Nuqsaf — refusal posture and citation discipline

10.1 What the AI will answer

Ask Nuqsaf is a scoped AI assistant. It will answer questions that fall into one of four buckets:

1. Reading the user's own data. “How much interest did I earn last year?” “What's my current zakat estimate?” “Did I hit nisab yet?” These are retrieval against the user's account.
2. Summarising a ruling from the library. “What does Nuqsaf say about credit card cashback?” “Is Bitcoin halal according to your rulings?” The AI quotes the ruling and cites it.
3. Applying a ruling to the user's situation. “My 401k is with Fidelity in a conventional S&P 500 fund — what does your investment ruling mean for me?” The AI cites the ruling and walks through the application.
4. Procedural questions. “How do I export my zakat report?” “How does auto-purification work?”

10.2 What the AI will refuse

The AI will refuse and offer Ask-a-Scholar (the paid, human-reviewed service) for:

• Questions requiring a fiqh ruling that is not in the Nuqsaf rulings library.
• Questions about contested scholarly disagreement that requires a judgement call (“which madhhab should I follow?”).
• Questions involving specific family, marriage, divorce, or personal-status fiqh.
• Questions that require knowing something about the user's intentions or spiritual state that is outside Nuqsaf's data.

10.3 Citation discipline

Every substantive answer must cite at least one of: (a) a ruling slug from the Nuqsaf rulings library, (b) a section of this methodology document, (c) a specific transaction or dataset in the user's own account. The system prompt enforces this; answers without a citation are rejected by the response validator before being shown to the user. If no citation is available, the AI refuses.

10.4 Never-invent rules

• The AI does not derive new rulings.
• The AI does not paraphrase a ruling in a way that changes its meaning.
• The AI does not offer a confident answer on a contested question — it names the contest and refuses to pick a side.
• The AI does not guess hadith numbers, Qur'anic verse numbers, or scholar attributions. If it is not in the ruling text it does not appear in the answer.
• The AI does not use emoji or fintech language. Tone is the same tone as this document.

10.5 Transcript audit

Every Ask Nuqsaf session is stored with the user's account. A rolling sample is reviewed weekly by the founder and, once a scholar reviewer is on payroll, by the scholar. If a refusal is wrong (“should have answered”) or an answer is wrong (“should have refused” or “cited wrong ruling”), the system prompt is updated, the affected user is notified, and the methodology gets a versioned change-log entry if the underlying rule moved.

11. Known limitations

Technical

• Only US-linked Plaid accounts are supported.
• Transaction and holdings categorisation depends on Plaid's data quality.
• 12-month lookback for transactions (some institutions provide less).
• Pending transactions may change after report generation.
• Investment screening caches quarterly; intra-quarter balance changes are not reflected.

Fiqh

• Zakat engine covers only financial assets Plaid surfaces; physical gold, silver, cash, inventory, and livestock are user-entered.
• Nisab defaults to silver; users following gold must switch in Settings.
• Hawl-drop (below nisab mid-year) is flagged for manual review, not automated.
• Values layer relies on merchant-level data; a transaction tagged with an incorrect merchant will be mis-classified until the user overrides.
• Mirāth engine implements classical rules; it does not reconcile with US state-specific intestacy statutes.
• Ask-a-Scholar escalation depends on scholar availability; SLA is 48 hours but not guaranteed.

AI

• The classification model can make errors — it is pattern-matching, not scholarship.
• The pre-filter uses keyword heuristics that may miss unusual interest labels.
• Ask Nuqsaf refusals may be over-cautious in edge cases; the user can always escalate to Ask-a-Scholar.
• All AI outputs are subject to user review and override.

12. How to discharge purification correctly

12.1 Manual discharge (the majority path)

1. Give the full amount as sadaqah to a needy recipient — the poor, the indebted, orphans.
2. Do not expect reward from Allah for this specific act. This is disposal, not voluntary charity.
3. Do not count it as zakat. Zakat and purification are separate obligations.
4. Do not claim it as a tax deduction. The purpose is to remove impure income, not optimise taxes.
5. Do not give it to financial dependents. The money should leave your household entirely.
6. Give sooner rather than later. The longer riba income sits in your accounts, the harder to separate.
7. You do not need to tell the recipient. The sin was in the acquisition, not the receipt.

For interest PAID (credit cards, loans): seek tawba, pay off debt as quickly as possible (highest-interest first), avoid new interest-bearing debt, consult a scholar if your situation makes avoidance difficult.

12.2 Auto-purification via partner charities

Nuqsaf Monthly subscribers may opt into auto-purification. Flagged interest is discharged automatically, on a monthly cycle, to one or more partner charities the user selects from a curated list (candidates include LaunchGood, Helping Hand, Islamic Relief USA, Zakat Foundation of America, ICNA Relief; final list pending charity-side agreements).

The fiqh conditions in §12.1 are preserved by design, not by accident:

• Sadaqah with no expected reward. Every auto-purification transfer is tagged server-side with intent=purification, and the user-facing receipt states this explicitly. The intention (niyyah) is the user's; the plumbing just carries it.
• Not zakat. Zakat and purification flow through different partner lists and different ledger entries. They cannot be combined even if the user wants them to be.
• No tax deduction. The annual receipt Nuqsaf emits for auto-purification is explicitly marked not tax-deductible, regardless of the recipient charity's own 501(c)(3) status. This is so the user does not inadvertently retain an economic benefit from riba income.
• Leaves the household entirely. Partner charities are vetted to have no relationship to the user's household. Nuqsaf does not permit auto-purification to a user-named recipient; only the curated list is allowed.
• Fees disclosed. Stripe Connect processing fees and Nuqsaf's platform fee (used to sustain the engine, capped at 3–5%) are disclosed to the user before opt-in and on every receipt. The user's purified amount is the full flagged amount, before fees; fees come from Nuqsaf's revenue line, not from the user's discharge.

A user who is uncertain about auto-purification should use manual discharge. The fiqh default is manual; auto is a convenience layer that the methodology goes out of its way to make compatible, not a preferred path.

13. Process for challenge and correction

• Disagree with a classification? Click Exclude in the review screen. Your override is final and is written to the audit log.
• Found an error in a report? Email asghar@nuqsaf.com with your report ID and the error. We investigate within 48 hours and regenerate at no charge.
• Disagree with the methodology? This document is public for scrutiny. Email the specific section, the error, and your reasoning or scholarly source. If substantive, we consult peer reviewers and update the methodology with a versioned change log.
• Found a systematic AI error? If a category of transactions or merchants is consistently misclassified, email us. We add the pattern to the pre-filter and re-validate. Your report is regenerated free.
• Ask Nuqsaf refused when it should have answered, or answered when it should have refused? Email the transcript ID. This is reviewed in the weekly AI audit (§10.5).
• Mirāth distribution looks wrong? The engine stamps its version and reviewer on every PDF. Email the PDF ID; the reviewer is in the loop by default.

Notes to peer reviewers

Thank you for taking the time to read this draft. The author is not a scholar and depends on your feedback. Specific questions where your review would be most valuable:

Sections 1–5 (carried forward from v0.2):

1. Are the Quranic citations accurate and complete? Is there a riba verse the author has missed?
2. Are the hadith citations accurate? Please add numbers from your preferred editions and flag any hadith you consider weak or disputed.
3. Is the distinction between riba al-nasi'ah and riba al-fadl stated correctly?
4. Is the scope (§1) appropriately bounded? Is there a product surface in scope that should not be, or out of scope that should be?
5. Is the madhhab-neutrality approach (§5.3) defensible, or should Nuqsaf commit to a specific madhhab?

Sections 6–10 (new in v0.3):

6. §6 Investment screening. AAOIFI Standard 21 thresholds (30% debt, 30% interest-bearing investments, 5% non-permissible income) — is the stricter AAOIFI figure the right default over the 33⅓% used by index providers? Is the dividend purification formula stated correctly?
7. §7 Zakat. Is silver the right default nisab? Is the hawl-drop rule handled correctly (flagged for review rather than auto-reset)? Is the stocks-held-for-appreciation vs stocks-held-for-dividends distinction appropriate?
8. §8 Values layer. Are the three strictness levels well-drawn? Are the default strictness settings per category (alcohol=Warn, pork=Warn, gambling=Hard-avoid, tobacco=Informational, adult=Hard-avoid) reasonable?
9. §9 Mirāth. Is the Sunni engine procedurally correct as described? Is the Ja'fari three-class structure correctly characterised? Are there edge cases (kalalah, gharrawayn, mushtarika) that deserve explicit treatment in this document?
10. §10 Ask Nuqsaf. Is the refusal posture too strict, too loose, or right? Is the “no citation → no answer” rule a sound discipline?

Cross-cutting:

11. Is the discharge guidance in §12 (including §12.2 auto-purification) consistent with the classical conditions?
12. Are there fiqh risks introduced by making these surfaces automatic (real-time purification, scheduled discharge) that manual flows would not have?
13. Is the language appropriate for a general Muslim audience without over-simplifying?

Please send feedback to asghar@nuqsaf.com.

Jazak Allahu khairan for your time and care.

End of v0.3 draft — all 13 sections complete.