00 — Vision & Scope

1. The problem

A retail Muslim investor who wants to invest thoughtfully faces four separate problems, and every existing product solves at most two of them.

1. Compliance is opaque and expensive. Screening data is behind institutional paywalls. Consumer apps that offer "halal" filters rarely show the ratio inputs, the methodology, or the as-of date, so the user cannot verify or disagree.
2. Research is fragmented. Prices, filings, macro series, earnings transcripts, and news live in different tools with different mental models. Synthesising them is a full-time job.
3. Advice is unexplained. Robo-advisors output allocations. Newsletters output tickers. Neither shows the evidence chain, and neither can be interrogated.
4. Privacy is surrendered by default. Holdings, net worth, and risk tolerance are among the most sensitive data a person has, and they are routinely uploaded to third parties as a precondition of using the tool.

2. The product vision

A private investment team of twelve specialists that works continuously, refuses to recommend anything non-compliant, shows its evidence for every claim, practices with virtual money until it has earned trust, and never sends your portfolio anywhere you did not authorise.

Success is not "generates alpha." Success is justified confidence: after six months, the user can look at any past recommendation, see exactly what the system knew at the time, understand why it decided what it decided, and see whether that reasoning held up.

3. Users

There is one primary user — the owner-operator — but they occupy two modes.

Beginner mode (the default surface). Wants: what should I do, is it halal, how much can I lose, explain it simply. Never sees a ratio unless they tap for it. Cannot accidentally construct a concentrated, high-volatility portfolio because risk limits are enforced, not suggested.

Analyst mode (progressive disclosure). Wants: the point-in-time fundamentals behind the screen, the agent-by-agent breakdown, the backtest with walk-forward validation, the calibration curve for the confidence scores, the raw filing excerpt that a claim was drawn from.

The same views serve both. Depth is one click away, never in the way.

4. Scope

In scope for v1 (Phases 0–3)

• Multi-source data ingestion with point-in-time correctness
• Configurable Shariah screening across published methodologies, with full input disclosure and purification calculation
• Twelve specialised agents with a deterministic aggregation layer
• Paper trading with realistic fills, fees, slippage, dividends, and corporate actions
• Portfolio analytics: allocation, exposure, concentration, drawdown, attribution
• Backtesting with walk-forward validation and bias guards
• Conversational assistant grounded in the user's own portfolio and the stored evidence corpus
• Web application covering the ten named surfaces, responsive down to a phone browser
• Local-only operation as a first-class, tested configuration

In scope, gated (Phase 5)

• Real-money brokerage connectivity, behind explicit opt-in, a minimum paper-trading track record, and hardware-backed confirmation per order

Explicitly out of scope

Not building	Why
Multi-tenant SaaS	Serving recommendations to others is regulated investment advice; the architecture would need an entirely different compliance posture
Options, futures, CFDs, margin, short selling	Ruled out by the compliance model, not by preference — see 05
High-frequency or intraday scalping	The data architecture is point-in-time daily/intraday-bar, not tick-level; the edge claim would be false
Crypto (initially)	Compliance status is genuinely contested and methodology-dependent; deferred rather than fudged. Revisit in Phase 4 with an explicit rule pack
Social/copy trading	Introduces third-party data flow and herding dynamics that conflict with the privacy and evidence-first principles
Guaranteeing returns, or presenting outputs as advice	Legally and ethically unavailable

5. Design principles

These are the tie-breakers when two designs are otherwise comparable.

1. Compliance is a gate. Never a weight, never a score, never overridable by conviction.
2. Every claim carries a citation. A number without a source document ID and an as-of timestamp does not reach the user.
3. Deterministic where it can be, probabilistic where it must be. Ratios, limits, and fills are code. Judgement is a model. Do not confuse the two.
4. Local-first, cloud-optional. Every capability degrades to a local model or a smaller universe. Nothing hard-fails on a missing API key.
5. Refuse rather than guess. Missing or stale inputs produce UNCERTAIN and an explanation of what is missing, not a lower-confidence recommendation.
6. Capital preservation over return maximisation. When risk limits and an attractive signal conflict, the limit wins, and the system says so.
7. Auditable by construction. Every recommendation is reproducible from stored inputs, model versions, and prompt hashes.
8. Simulate before you trust. Nothing reaches real money without a track record generated under the same code path.

6. Success criteria

Measurable, and checked at each phase gate.

Correctness - Shariah screening reproduces published index constituency on a labelled validation universe with ≥ 98% agreement; every disagreement is individually explained. - Backtest results are reproducible bit-for-bit from a stored run manifest. - Zero look-ahead violations detected by the point-in-time audit harness.

Calibration (the metric that matters most, and the one most products never report) - Recommendation confidence is calibrated: over a rolling 12-month window, outcomes in the 70% confidence bucket resolve favourably 65–75% of the time. Brier score is tracked and shown in-app.

Trust - 100% of user-visible numeric claims resolve to a stored source document. - Median time to answer "why did you recommend this?" is under 5 seconds from the recommendation card.

Operational - Full daily pipeline completes in under 30 minutes on the reference home-server profile. - The system runs for 7 consecutive days with all cloud AI providers disabled, with no functional loss beyond documented universe reduction.

Safety - No code path exists from a recommendation to a real-money order before Phase 5. - Prompt-injection red-team suite passes with zero instances of ingested content influencing a tool call or an order.

7. Non-negotiable constraints

• Real money is unreachable until Phase 5, and then only after the user completes an explicit enablement ceremony.
• The user's holdings are never transmitted to a third-party model provider unless that specific data-sharing setting is enabled, and the app states plainly what leaves the device.
• No telemetry, analytics, or crash reporting is enabled by default.
• The compliance disclaimer and the "this is not advice" framing appear at the point of recommendation, not buried in settings.