One-sentence pitch

The versions, at a glance

Mihwar ships in four layers. Each inherits the one below. V0.1 is the next thing to build — the personal MVP that closes the loop in days. V1 productizes it for NMO consulting in 6 weeks after V0.1 validates. V2 unlocks when clients pull. V-future is a bet kept alive only so today's architecture doesn't foreclose it.

What's in each version

The four mental tests Mihwar is built against

Every implementation choice in this document — every endpoint, every query, every prompt — is checked against four questions. They appear as flags throughout the rest of the masterplan.

Where to read next

Six entry points, depending on what you came here for:

Why V0.1 exists

V1 is six weeks of build before the engine compiles its first idea into a deliverable. That's too long to validate the core loop. V0.1 compresses everything that matters about V1 into a single page that Ahmed uses on himself, every day, on whatever idea is on his mind that morning. If the playbooks it produces are useful, V1 is worth building. If not, the masterplan changes before any client sees it.

The single page

Input — what the page asks for

• Idea field — free-form textarea. "I want to build X for Y reason." Two to five sentences typical. No structure forced.
• Operator Profile — pre-loaded from a JSON file. The user does not re-enter it every time. Edits happen once via a settings page (Phase 2 of V0.1, optional).
• Optional context — paste a link to an existing repo, or a one-line preference like use Next.js, not Astro.

Output — the build playbook

The local-vs-cloud flag system

Every component in the architecture section gets one flag. The flag is the whole point of V0.1.

Operator Profile — Ahmed's edition

The Operator Profile is the JSON Mihwar reads as static context on every call. It's pre-loaded for Ahmed; future operators (NMO consultants, then clients in V2) will get their own.

Architecture · what V0.1 itself looks like

Build effort — 3 to 7 days, one Claude Code prompt

1. Day 1 — Scaffold Next.js page, paste Operator Profile JSON, hardcode a sample idea, get the LLM call working with structured output.
2. Day 2 — Wire the form, render playbook sections, style the local/cloud flags, add the cost-log JSON file.
3. Day 3 — Prompt caching on the static prefix, verify cache_read_tokens > 0 on call #2, tighten the prompt to enforce the 6-section output.
4. Day 4–5 — Dogfood on five real ideas Ahmed has been sitting on. Observe where the playbook gets vague, sharpen the prompt, refine the Operator Profile.
5. Day 6–7 — Deploy to https://mihwar.nmopartners.com/v01 behind WireGuard. Add a tiny TOC of past playbooks. Decide whether V1 is worth building based on whether you used V0.1 daily.

What V0.1 inherits to V1

• The loop — idea → grounded playbook → execute. V1's 5-stage workflow is the same loop with explicit gates.
• Operator Profile concept — V1 generalises it: each consultant has one, each client (in V2) has an Org Profile that is the same idea at the buyer level.
• Local/cloud flagging — promoted to a first-class field in V1's Blueprint format. Clients get the same colour-coded breakdown.
• Agent assignment language — V1's Stage 4 (Playbook) inherits the same agent-references vocabulary.
• Cost-log shape — the JSON written per call in V0.1 becomes the schema for the ai_calls table in V1's Postgres.
• Sonnet + prompt caching — V0.1 proves the cache hit rate behaviour before V1 scales it across five distinct prompts.

What V0.1 explicitly is not

• Not a Blueprint engine. Output is a build playbook for Ahmed, not a $25k client deliverable.
• Not multi-tenant. One JSON profile. One user. One folder of past playbooks.
• Not a five-stage workflow. Single shot. No gates. No async forms. No house-style filter.
• Not the catalog. Recommendations are grounded in the Operator Profile, not in a curated library of vendors and patterns.
• Not for clients. Behind WireGuard. Never shown externally.

Success criteria

• Ahmed uses V0.1 on at least 5 of his own ideas in the first 14 days.
• At least one playbook leads to a built thing that ships.
• Cost stays under $20/month.
• Cache hit rate ≥ 80% by call #3 in any session.
• Ahmed is willing to commit the next 6 weeks to V1 because V0.1 worked — or honestly say "the loop isn't useful" and reshape V1 before building it.

What Mihwar is, in one paragraph

Mihwar is the operating system for an AI consulting practice. In Phase 1 it is the private cockpit Ahmed and the NMO team use to run client engagements: a five-stage workflow that takes a vague client wish and produces a $25,000 Blueprint deliverable in a working week, grounded in a curated catalog of vendors, models, and patterns and in the client's own infrastructure inventory. In Phase 2 the same engine is exposed to clients directly so they can self-serve AI visioning and roadmaps inside their own organisations, paying NMO a subscription for the platform and the catalog. The Phase 1 codebase is built so the Phase 2 pivot is a deployment change, not a rewrite.

The promise

What V1 must be

• Single-tenant in operation, multi-tenant in design. Tenancy lives at the data layer from day one so V3 isn't a rewrite.
• Built primarily by Claude Code, in five carefully-scoped prompts. Ahmed reviews diffs and steers; the LLM writes most of the lines.
• Boring stack. Postgres, Redis, FastAPI, Next.js, Hostinger VPS, Coolify. No Kubernetes, no microservices.
• Bilingual EN/AR by default. KSA market. Arabic is not an afterthought.
• Self-defended. Mihwar's own security and infrastructure get the same rigour we sell to clients.

What V1 is not

• Not a SaaS yet. No public sign-up, no Stripe, no per-tenant theming. The data model is ready; the UI is not.
• Not a build platform. Mihwar produces the Blueprint and the Playbook. Building is downstream — by NMO Apex's agent team, by a partner, or by the client themselves.
• Not a generic "AI ChatGPT for consulting". Every recommendation is grounded in a curated catalog and an inventoried environment. House style is enforced. House voice is mandatory.

The four mental tests

Every implementation decision in this masterplan is checked against four questions. They run through every section that follows.

The problem — three layers

Layer 1 · Discovery is slow and expensive

A typical AI use-case discovery in a KSA enterprise takes 3–6 weeks. Stakeholders are scattered across IT, business units, security, procurement, vendors. Information arrives in WhatsApp threads, email PDFs, three different SharePoint tenants and a printed spreadsheet from a DBA. The consultant spends 60% of the engagement chasing data dictionaries and license terms, not designing the system.

Layer 2 · Architecture decisions are gut-call

By the time the inventory is "good enough", the senior architect picks tools from memory. The recommendation is rarely written down beside the alternatives that were rejected. Six months later when the build runs into trouble, no one remembers why Snowflake was chosen over BigQuery — and there is no audit trail to consult.

Layer 3 · The deliverable is dead on arrival

Most engagements end with a 60-slide PowerPoint plus a Word document. CTOs forward them to a procurement committee, who can't navigate them, can't search them, can't share fragments without re-formatting, and can't verify whether the architecture has been validated against the actual environment. The artifact is dead on arrival.

The insight

The reframe

Mihwar is not a chatbot for architects. It is an interviewing instrument. Stage 1 sharpens the use case. Stage 2 conducts the inventory. Both stages structurally refuse to advance until the inputs to Stage 3 are complete. Stage 3 — architecture synthesis — is fast precisely because Stages 1 and 2 made it possible. Most AI consulting tools start at Stage 3 and skip the discovery; that is exactly why their outputs feel hallucinated.

Why this works in KSA, specifically

• KSA enterprises have real budgets for AI right now and weak internal AI talent. They need consultants who move fast but stay rigorous.
• The local consulting market is dominated by Big Four-style PowerPoint teams. A bilingual interactive HTML deliverable signed by an Arabic-fluent boutique is a credible differentiator.
• PDPL, SAMA, NCA cybersecurity controls — these introduce architecture constraints that grounded recommendations must respect. Generic AI tools can't see those constraints; Mihwar's catalog encodes them.

The 2026 KSA AI landscape

Saudi Arabia has declared 2026 the Year of AI. Concretely:

• SDAIA is funding AI capability programs across ministries and Vision-2030 entities. Tier-2 and Tier-3 government bodies (universities, regulators, regional admin) are being told to "have an AI strategy" by year-end.
• Banks under SAMA are running parallel AI initiatives — fraud, KYC summarisation, contact centre — under increasing regulatory scrutiny.
• Mid-market enterprises (logistics, retail, healthcare networks, family offices) are watching the giants and want a credible mid-budget option for AI exploration.
• The Big Four are quoting 8–14 weeks and $200k+ for AI strategy decks. Most clients can't afford that or won't.

The competitive shape

The wedge

Mihwar plus NMO occupies a specific gap: a senior, KSA-fluent consultant team backed by a productised workflow that produces a verifiable, interactive deliverable in 7 days for a $25k anchor price. No Big Four competes there because their cost structure forbids it. No SaaS competes there because they have no senior consultant. No body-shop competes there because they have no productised IP.

Two-tier client thesis

Phase 2 market

When Mihwar opens to clients directly (Phase 2), the addressable market widens substantially: every mid-market enterprise that does not need a consultant in the room but does need a structured visioning process becomes a buyer. Pricing shifts from engagement-based to per-seat or per-Blueprint subscription. NMO captures consultancies as a meta-tier — small AI shops who license the Mihwar engine and the catalog and use it inside their own client engagements.

The three-tier pricing model

The pricing anchor

This anchors the value of discovery, separates it from build risk, and makes Tier 1 feel reasonable. Never quote a Tier 3 price first. It triggers procurement scrutiny that the engagement isn't sized for.

Phase 2 pricing (preview)

When Mihwar becomes a SaaS, pricing shifts. The Blueprint becomes a unit of work the customer self-produces; NMO charges for access to the engine and the catalog.

Margin discipline

• Phase 1: The Blueprint price minus the Anthropic/embeddings cost minus 1.5 days of senior consultant time must clear 65% margin. If a Blueprint burns more than 1.5 days of consultant attention, the workflow has failed.
• Phase 2: Per-Blueprint AI cost must stay below $40 at the 95th percentile via prompt caching, two-tier model selection, and batch-API for non-realtime steps. See AI Economics.

Persona 1 · Ahmed (Founding Consultant) — the driver

Persona 2 · NMO Consultant (future, Month 4+) — the growing team

Persona 3 · Client CTO / Head of AI — the audience

Persona 4 · Phase 2 self-serve client — the future buyer Phase 2

Why two phases, in this order

• Phase 1 first earns the right to Phase 2. Without ten signed engagements producing real Blueprints, Mihwar has no proof, no testimonials, no catalog moat, and no understanding of where the workflow actually breaks for a non-expert user.
• Phase 1 funds Phase 2. Each $25k Blueprint at 75% margin contributes $18k toward the SaaS lift. Five engagements pay for the Phase 2 build wholesale.
• Phase 1 stress-tests every Phase 2 surface. Every UX paper-cut Ahmed hits with a real client is a paper-cut a self-serve user would have hit harder. Phase 1 is a moving usability test.
• Phase 2 too early kills the consulting margin. Self-serve at $1,200/mo dilutes the perceived value of the $25k engagement. Phase 2 launches when Phase 1 is sold out, not before.

What Phase 1 builds that Phase 2 inherits

What Phase 2 adds on top of Phase 1

• Identity provider integration: OIDC, SAML, Microsoft Entra, Google Workspace.
• Self-serve onboarding: sign-up flow, email verification, workspace creation wizard, first-Blueprint guide.
• Embedded coaching: the AI plays "consultant in the room" for users without one. Higher tooltips density, "show me an example" affordances, sample answers from the catalog.
• Per-tenant customisation: theme, logo, custom blueprint cover page, branded export.
• Billing & metering: Stripe, per-seat or per-Blueprint counters, hard caps, soft alerts.
• Catalog tiering: NMO premium catalog (read-only, paid), customer-private catalog (writeable, scoped to that tenant).
• Public Mihwar website & pricing page.

The phase-pivot triggers

Phase 2 development starts when any one of the following becomes true:

• Demand pull: ≥10 distinct prospects ask "can we get a Mihwar login" within any 6-month window.
• Capacity ceiling: NMO's consultant team is fully booked, pipeline is stronger than capacity, and adding consultants doesn't scale margin.
• Catalog moat is mature: ≥300 entries with quarterly review cycles. Catalog itself is now a deliverable.

The complete workflow

The stage mechanics

Each stage is a panel in the Mihwar UI with three sub-panels:

• The interview — a chat-like surface where the consultant works through prompts. The AI asks follow-ups; the consultant types, edits, or pastes.
• The artifact — the structured output of the stage, continuously updated as the interview progresses. The consultant sees it forming.
• The signoff — a single button at the bottom: "I am satisfied this stage is complete." Clicking it freezes the artifact, creates an immutable version row, and unlocks the next stage. The consultant always controls signoff — never the AI.

Why "the gate" matters

Concretely: when the consultant tries to advance to Stage 3, the system checks Stage 2 completeness against the use case category. Missing critical fields ("nobody has told us where the data is") block advance with a specific, actionable list. The consultant cannot bypass this from the UI; they would have to edit the database directly to override.

When this stage runs

Typically the first or second meeting with a new client. The CTO has expressed interest, may have a fuzzy idea of what they want, and needs the consultant to help them sharpen it. The Lab can also be skipped if the client arrives with a fully-scoped use case (rare) — they get a discount for not needing it.

The six sharpening questions

Mihwar runs the Lab through six question phases. The AI generates the specific questions in context, but they always probe these dimensions:

The AI's behaviour

The Lab uses Claude Sonnet (latest) with a system prompt that turns it into a Socratic interviewer. Behaviour rules:

• Asks one question at a time. Never bundle two probes.
• Reflects what it heard before moving on. Confirms understanding in the consultant's words.
• Surfaces contradictions politely. "Earlier you said X. This sounds like Y. Which one is the real one?"
• Refuses to recommend solutions. Stage 1 is about the problem, not the answer. If the consultant tries to leap forward, the AI parks the answer for later.
• Honours house style. No exclamation marks. No "I'd love to help!" No emoji. Direct, professional, KSA-appropriate.

The artifact: the 1-pager

As the conversation progresses, the artifact panel renders a structured Use Case 1-pager:

USE CASE: [name]
PAIN:    [one sentence]
USER:    [persona, role, jurisdiction]
TODAY:   [current process, cost, owner]
TARGET:  [metric, baseline, goal, by when]
BLAST:   [tolerable failure modes, intolerable failure modes]
INPUTS:  [what data is needed, who owns it]
DECISION-OWNER: [who signs off the build]
OUT-OF-SCOPE: [explicit non-goals]

The signoff

When the consultant is satisfied, they hit "Sign off Stage 1". The 1-pager is frozen as v1. If they re-open later, edits create v2, v3, etc. — never overwrite. This becomes the input to Stage 2's question-set tailoring.

Phase 2 considerations Phase 2

For self-serve Phase 2 users, Stage 1 needs more scaffolding: example 1-pagers from the catalog ("see how a contact-centre AI was scoped"), inline tooltips that explain each dimension, and a "show me a strong answer" affordance on each prompt. The schema doesn't change — just the surface.

Why this stage is the bottleneck

In a traditional engagement, Stage 2 takes 3–6 weeks. It's where consultants chase stakeholders for data dictionaries, screenshots of dashboards, license confirmations, GPU specs. It's where projects stall.

Mihwar compresses to 2–3 elapsed days by:

• Generating only the questions that matter. The AI uses the Stage 1 1-pager to filter the discovery taxonomy down to ~30 questions out of a possible ~150.
• Splitting live and async. Questions the consultant can answer live; questions that need a DBA or vendor contract get sent as a structured form to the right person via a single-use, time-limited link.
• Auto-detecting completeness. The AI tells the consultant exactly which questions are still blocking architecture synthesis.
• Reusing the Org Profile. If the client has done a previous engagement (or is a Phase 2 user), most infrastructure questions are already answered. See Org Infra Profile.

The discovery taxonomy

Async forms — how they work

For each async question, Mihwar generates a single-use form link, scoped to the question, time-limited (default 7 days), bound to the recipient's email and IP-logged. The link looks like:

https://mihwar.nmopartners.com/async/01HV7Z9K3J5XPQ8WMY4N6T2RES

Recipients land on a clean, branded page with one or two questions, an "I don't know — ask X" escape, and a submit button. No login required. Submissions stream back into the consultant's Stage 2 panel.

The completeness check

The AI maintains a running gate-check: which Stage 3 architecture decisions can be made given current Stage 2 inputs? The consultant sees this as a live readiness meter, with the specific blocking questions named:

Stage 3 readiness: 76% · 4 questions remain blocking
✓ Data residency captured
✓ Identity provider captured
✗ GPU availability — pending response from CloudOps (sent 3 days ago)
✗ PDPL classification of customer voice transcripts — pending Legal
✗ SAMA AI governance applicability — async link expired, resend?
✗ Production traffic peak — async link sent today

Phase 2 considerations Phase 2

Self-serve users don't have a consultant orchestrating Stage 2. Mihwar must:

• Pre-populate from the persistent Org Profile wherever it overlaps.
• Suggest who to ask for each blocker ("typically your DBA can answer this — here's a template message").
• Allow inviting collaborators into the workspace to answer their slice directly.

What "grounded" means

The AI is given:

• The Stage 1 1-pager (sharp use case).
• The Stage 2 inventory (what they have).
• The full catalog, RAG-retrieved (vendors, models, frameworks, patterns, constraints).
• The house style guide and banned-phrases list.

The AI is forbidden from:

• Recommending a vendor not in the catalog.
• Recommending a vendor without KSA presence when the inventory says residency is required.
• Recommending a tool the inventory shows the client doesn't have a license for, without flagging procurement implications.
• Inventing pricing.

The six architecture outputs

1. Layered architecture diagram — auto-generated SVG using the 10-layer model from the AI Ecosystem Primer, populated with chosen tools.
2. Component manifest — table of every component, its role, its catalog reference, the rationale.
3. Data flow diagram — auto-generated, showing how data moves from sources to user-visible outputs and back.
4. Trade-offs & alternatives — what was considered and rejected, and why. With explicit catalog references.
5. Open questions — anything the AI flagged as needing human judgement before build commits.
6. Compliance overlay — a separate read of the architecture against PDPL, SAMA, NCA controls, depending on what Stage 2 captured.

How synthesis actually runs

Synthesis is asynchronous. The consultant clicks "Generate Architecture v1"; the request lands in a background queue (BullMQ-equivalent on Redis). A worker:

1. Loads the 1-pager, the inventory, the relevant catalog slice (RAG: top-K embeddings).
2. Runs Sonnet with extended thinking enabled, system prompt cached via cache_control.
3. Streams progress to the consultant's UI via SSE.
4. Persists the result as stage_artifacts v1.
5. Auto-renders the SVG diagrams from the structured component manifest.

Total elapsed time: typically 60–120 seconds. The consultant sees a "thinking…" beam during synthesis and reads the result when it lands.

Editing the result

The consultant can:

• Edit any field directly (textarea / structured editors per output).
• Ask the AI to "regenerate just the trade-offs section with these adjustments."
• Override a vendor recommendation and have the AI re-rationalise.
• Accept and freeze the result, creating Stage 3 v1.

Why this stage is optional

Many engagements stop at Stage 3 — the client signs off the Blueprint, takes it to their finance committee, comes back later for the build. Mihwar respects that — Stage 4 is opt-in and adds days, not hours.

When clients do want Stage 4, they're typically committed to building and need the planning rigour. They're paying $30–60k for the Blueprint+Playbook combo and they expect a deliverable they can hand to a build team.

The five Playbook outputs

1. 6-Week Build Plan — week-by-week milestones, dependencies, owner per task. Conservative estimates.
2. Risk Register — every risk identified during discovery and architecture, with severity, mitigation, owner.
3. Vendor & Tooling Short-List — for every component, 1–3 specific vendors with KSA presence, pricing model, contact, last-reviewed date.
4. Reference Repositories — pointers to NMO Apex's accumulated build patterns: starter Helm charts, FastAPI templates, Next.js shells. (Tier 3 only — IP is gated.)
5. RFP Specification — for government clients: a procurement-ready scope of work, evaluation criteria, and acceptance test plan. Optional add-on.

The Risk Register format

The RFP spec

For government engagements, the RFP spec is the keystone. It mirrors the Blueprint structurally but reformats it as a procurement document: scope of work, deliverables, milestones, acceptance criteria, evaluation matrix, security clauses (NCA-ECC, PDPL), and pre-qualified vendor categories. The client's procurement team can lift it into their tender platform with minimal editing.

What gets delivered

• The Blueprint HTML — single self-contained file. Bilingual EN/AR. Mihwar branding minimal; NMO + client logos prominent. Opens in any browser, works offline, prints respectably.
• Manifest & signature — embedded JSON manifest with version, signoffs, catalog snapshot hash, generation timestamp. Cryptographically signed.
• Source pack (optional) — for clients on Tier 2+, a zip of the structured artifacts (1-pager, inventory, architecture, playbook) as JSON, for downstream tooling.
• Walkthrough recording — Tier 1+ engagements include a 90-minute walkthrough. With consent, the recording becomes a deliverable too.

Presentation mode

Mihwar supports a presentation mode — full-screen, larger fonts, navigable page-by-page. The consultant shares the Blueprint screen, walks the client CTO through each section, answers questions, captures any final adjustments. Adjustments create a v(n+1) without invalidating the original signed manifest.

After handoff

The workspace doesn't disappear. Mihwar retains it indefinitely (subject to data retention policy). NMO can:

• Reopen later to update the Blueprint if the client requests changes.
• Reference patterns in future engagements (with consent and anonymisation).
• Track which Blueprints converted to builds — feeds the catalog's "used in N past engagements" field.
• Run quarterly catalog reviews against the body of past Blueprints to catch drift.

Five hard requirements

1. Self-contained. Single HTML file, no external dependencies (one optional Google-Fonts link). Opens offline. Works on any device, any year.
2. Bilingual. EN by default, AR view available with full RTL. Translation is consultant-reviewed, not raw machine output.
3. Navigable. Sidebar TOC, in-page anchors, search box (Ctrl+K). The CTO must be able to find any claim in <10 seconds.
4. Branded. Client logo, NMO logo, project name, version, document classification, date. Looks like a $30k document, not a generated artifact.
5. Verifiable. A signed manifest and version stamp prove provenance. Reader can hash-check.

The Blueprint structure

Why HTML, not PDF

• Searchable. Ctrl+F works inside the browser. PDFs garble across reader software.
• Linkable. Internal anchors. The CTO can email a link to "§4.2 Vector Store choice" rather than "look at page 23 of the attached".
• Copyable. Tables paste into Confluence. Code blocks copy clean. PDFs are write-only.
• Live diagrams. SVG architecture diagrams scale on retina; PDF diagrams pixelate.
• Forward-shippable. A 1.2MB HTML file forwards cleanly. A 40MB PDF gets stripped by mail filters.

The manifest

{
  "blueprint_id": "01HV8XQGT7K5R2W3M9N6P8Y4ZS",
  "client": "Tadawul",
  "project": "Customer Voice AI",
  "version": "1.0",
  "generated_at": "2026-05-07T14:32:18.420Z",
  "engagement_id": "eng-0042",
  "tenant_id": "nmo-001",
  "stages": {
    "stage_1": {"version": 3, "signed_off_by": "ahmed@nmopartners.com",
                "signed_at": "2026-05-03T10:14:00Z"},
    "stage_2": {"version": 5, "signed_off_at": "2026-05-05T16:22:00Z"},
    "stage_3": {"version": 2, "signed_off_at": "2026-05-06T09:08:00Z"}
  },
  "catalog_snapshot_hash": "sha256:7c4b8d…",
  "signing_key_id": "mihwar-prod-2026-05",
  "signature": "ed25519:0x4f2a1c9b…"
}

Why a catalog

If the AI is allowed to recommend any vendor based on its training data, three things go wrong:

• Hallucinations. It recommends vendors that don't exist in KSA, or quotes pricing from 2023.
• Inconsistency. Two engagements get different recommendations for the same problem.
• Loss of differentiation. NMO's Blueprint reads like every other consultancy's because it's drawn from the same public training data.

The catalog solves all three. It's NMO's opinionated knowledge base, evolving with every engagement.

The 10-layer architecture atlas

The catalog is organised around a 10-layer reference architecture covering the full AI stack. Every catalog entry attaches to one or more layers. The same atlas is used in Stage 3's auto-generated diagram.

Catalog schema

Catalog seeding (V1)

The catalog is seeded from two sources:

• The AI Ecosystem Primer (NMO's existing reference doc) — every vendor, model, and framework listed there imports as a catalog entry.
• Pattern templates derived from NMO Apex's prior builds — contact-centre AI, document Q&A, fraud screening, KSA/AR-language tasks.

Seed target for V1: 80–120 vendors, 30 models, 20 frameworks, 12 patterns, 30 constraints, 150 questions. Within 6 months of operation: 200+ entries, quarterly review cycle.

Catalog tiers (Phase 2 preview) Phase 2

• Public tier — minimal entries, good for the public Mihwar marketing site.
• Premium tier (NMO) — the full opinionated catalog. Phase 2 subscribers get read-only access, NMO writes.
• Customer-private tier — each Phase 2 tenant can add their own private entries (preferred internal vendors, contractual exceptions, data-classification overrides). Never visible to other tenants.

The problem this solves

Today, when NMO does a second engagement with a returning client, the consultant manually re-enters 80% of Stage 2 — same Snowflake, same Entra tenant, same SAMA-registered subsidiary, same procurement rules. The client wonders why they're answering the same questions twice. Phase 2 makes this unbearable: a self-serve user shouldn't face a 30-question infrastructure quiz on every Blueprint they generate.

What the Org Profile captures

The Org Profile is a structured, versioned document attached to a tenant (Phase 2) or to a client entity within NMO's tenant (Phase 1). It mirrors the Stage 2 taxonomy:

How the Profile feeds discovery

Why this is a separate concept from Stage 2

• Different lifecycle. Stage 2 inventory is engagement-bound and frozen with the Blueprint. The Org Profile lives across engagements and is updated in place.
• Different ownership. Stage 2 is owned by the consultant. The Org Profile is owned by the client (Phase 2) or by the consultant on behalf of the client (Phase 1).
• Different write surface. Stage 2 is a workflow. The Org Profile is a settings page.
• Different security needs. Org Profile contains the sensitive long-form picture of the organisation — encrypt at rest at field level, see Mihwar's Own Security.

The "delta" experience

When a returning client starts a new engagement:

1. Mihwar loads the Org Profile, marks it as the baseline for Stage 2.
2. The AI scans the Stage 1 1-pager, identifies which Stage 2 questions are still unanswered or stale for this specific use case (e.g. a contact-centre use case might trigger questions about voice telephony platforms not relevant to a previous fraud-screening engagement).
3. The consultant only sees the delta: ~5–8 use-case-specific questions instead of 30.
4. On signoff, any edits flow back into the Org Profile (with an "this updates the profile?" confirmation), versioning the profile too.

Versioning

Org Profile is versioned in the same pattern as stage_artifacts: every meaningful update creates an immutable version row with author + timestamp. Stage 2 inventories link to the specific Profile version they were derived from — so re-reading a Blueprint a year later shows what the world looked like then, not now.

Security & privacy

Phase 2 fit Phase 2

The Org Profile is the central artifact of Phase 2. A self-serve user fills it once at onboarding (with a guided wizard), then every Blueprint they generate inherits it. Profile review becomes an annual event — pushed by Mihwar with email reminders. Without the Profile concept, Phase 2 is unusable; with it, the second Blueprint a customer generates feels effortless.

The six containers

All containers run on a private Docker network mihwar_net. Only Caddy (managed by Coolify) is exposed to the public internet on 80/443. Postgres and Redis ports are never bound to host or to the public Apex network.

Request flow — typical write path

1. Browser → Caddy (TLS, HSTS, CSP applied) → mihwar-web.
2. Server component issues fetch to mihwar-api with the user's session cookie.
3. API authenticates the session, attaches verified identity to the request context (contextvars), generates or accepts request_id.
4. API authorises the action against tenant + workspace ownership.
5. Long path: API enqueues a job on Redis (with request_id + user_id + tenant_id in payload) and returns 202 + job ID. Worker consumes, calls aiproxy, persists result.
6. Short path: API writes to Postgres directly, returns 200.
7. Streaming path (Stage 1 chat, Stage 3 progress): API holds an SSE connection, relays tokens from aiproxy as they arrive.

Single egress — why aiproxy

• One key in one place. The Anthropic key lives only in the aiproxy environment. Worker / API / web never see it.
• Cost meter. Every call is logged with model, input tokens, output tokens, cache hit, cost. See AI Economics.
• Rate cap. Per-tenant + per-feature soft caps with hard refusal at threshold.
• Model swap. Switching from Anthropic to a regional sovereign-cloud LLM in Phase 2 is a config change in aiproxy, not a code change in 14 places.
• Cache. aiproxy can layer response-level caching for deterministic prompts (catalog questions, glossary expansions).

Outbound allowlist

The VPS firewall (UFW) restricts outbound traffic to:

• api.anthropic.com, api.voyageai.com — from aiproxy only.
• Coolify update servers, OS package mirrors — for system updates.
• Backup target (object storage in a separate region) — encrypted, signed.

Anything else is denied by default. This kills two attack classes at once: data exfiltration via a compromised container, and prompt-injection-driven outbound calls.

Schema overview

Versioning rules

All artifacts (stage_artifacts, blueprints, org_profiles) follow the same versioning pattern:

• New row per signoff — never UPDATE.
• version column auto-increments per parent.
• signed_by + signed_at on the row that becomes "current".
• parent_version link for diffing.
• Working draft kept in a separate *_draft column or table; only frozen on signoff.

The tenant boundary

-- every business table has tenant_id with NOT NULL
ALTER TABLE workspaces ADD COLUMN tenant_id UUID NOT NULL
  REFERENCES tenants(id);
CREATE INDEX idx_workspaces_tenant ON workspaces(tenant_id);

-- row-level security enforced at the DB layer
ALTER TABLE workspaces ENABLE ROW LEVEL SECURITY;
CREATE POLICY ws_tenant_isolation ON workspaces
  USING (tenant_id = current_setting('app.tenant_id')::uuid);

-- API sets the session-local var on every request
SET LOCAL app.tenant_id = '01HV8Z…';

Indexes — the non-negotiable list

• Every business table: (tenant_id) first, then (tenant_id, workspace_id) compound.
• messages(workspace_id, stage, created_at DESC) — chat history retrieval.
• stage_artifacts(workspace_id, stage, version DESC) — load latest version fast.
• audit_log(tenant_id, actor_id, created_at DESC) — operator Logs page queries.
• ai_calls(tenant_id, created_at DESC), plus (tenant_id, feature, created_at DESC) — cost dashboards.
• async_links(token_hash) unique — single lookup on form load.
• pgvector: HNSW index on catalog_entries.embedding for RAG retrieval.

Migrations

Alembic. Every migration declares its indexes with CONCURRENTLY for tables expected to grow past 100k rows (messages, ai_calls, audit_log). Migrations are reviewed in PR before being applied — no auto-apply on deploy.

Backend

Frontend

Data & vectors

Infra & ops

Why no microservices

Microservices are a horizontal-scaling pattern. Mihwar V1 has one tenant and a handful of users. Microservices would buy nothing and cost weeks of build time, more failure modes, harder local development. The shape of "5 containers, one VPS" lets us ship the workflow in 6 weeks. Phase 2 may eventually warrant horizontal scaling — but that's a graduation move, not a starting point.

The core decision

The cost of doing it now is one column on a few tables and one Postgres feature (RLS). The cost of doing it later is months of refactoring while engagements are paused.

The three tenancy levels

Cross-tenant tests

Every CI run executes a "tenant fence test": create two tenants, two users, two workspaces. Authenticate as user-A. Try to read user-B's workspace, message, audit log, blueprint. Assert 404 (not 403 — 403 leaks the existence of the resource). The test fails the build if any cross-tenant read returns data.

Tenant deletion (Phase 2)

When a Phase 2 tenant cancels and confirms erasure:

1. Org Profile DEK is destroyed in KMS — encrypted fields become unrecoverable.
2. All tenant_id-scoped rows are hard-deleted in a single transaction.
3. Backup retention for that tenant is honoured (90 days) then purged.
4. An audit log entry is written to a separate tenant-deletion ledger (kept indefinitely for compliance reasons).

The threat model

Mihwar must defend against, in order of likelihood:

1. Accidental data exposure. Bug returning the wrong client's data. Mitigated by RLS at the database layer.
2. Compromised API keys. Anthropic key leaked. Mitigated by aiproxy as single egress and Anthropic's per-key rate limits + outbound allowlist.
3. Stolen session token. Mitigated by short cookie lifetime, httpOnly, SameSite=Strict, IP-binding (soft), regenerate-on-login, MFA on the passphrase.
4. Unauthorised async-link access. Mitigated by single-use cryptographically-random tokens, time expiry, IP logging, generic 404 on invalid.
5. Malicious prompt injection in client docs. Mitigated by input quarantine (untrusted data in a delimited <document> block, never as system prompt), tool-use isolation, output filtering before any tool invocation.
6. Mihwar host compromise. Mitigated by isolated networks, encrypted backups offsite, no shared secrets between containers, OS hardening, regular patching. See Mihwar's Own Security.
7. Insider error. Mitigated by per-user audit log, separation of admin vs operator roles, two-person sign-off for destructive actions (V3).

Authentication

• Single passphrase + TOTP MFA for V1. Passphrase Argon2id-hashed (memory cost ≥64 MB, time cost ≥3, parallelism 1). MFA code stored as TOTP secret encrypted at rest.
• Account lockout with exponential backoff after 5 failed attempts within 15 min. Logged.
• Session cookies: httpOnly, Secure, SameSite=Strict, ≤8h lifetime, sliding refresh. Tokens are secrets.token_urlsafe(32) — 256 bits of entropy. Stored as SHA-256 hashes in the DB.
• Session regenerated on login (no session fixation). Old session ID invalidated on logout.
• Phase 2: SSO via OIDC (Microsoft Entra, Google Workspace, Okta) and SAML for enterprise tier.

Caller identity model new

Every API call identifies its caller before any work. Caller types are explicit and disjoint, each with its own credential mechanism:

Verified identity is attached to the request context (contextvars) and used for every downstream check. Permission is checked against the verified caller, never against client-supplied identifiers. Rate limit applies per verified identity, not IP alone.

Authorisation

• Default DENY at framework layer. Every endpoint declares its required permission explicitly.
• Object-level ownership check on every read/write. "Does this user have access to this workspace?" — answered server-side, no exceptions.
• tenant_id in every query at the app layer + RLS at the DB. Two layers of defence; the second one catches the first one's bugs.
• Async-link tokens are scoped to a single question + recipient + workspace and expire. They are not session tokens.

Input validation

• Zod / Pydantic schema at every API boundary. Reject malformed, never "clean".
• Body size limits at HTTP layer (1 MB default; 10 MB for known upload paths).
• File uploads: validate MIME + extension + magic bytes; UUID filename server-side; outside web root; AV scan on receive (ClamAV); never executed.
• SQL: parameterised queries only. Dynamic identifiers (rare — ORDER BY columns) come from a server-side allowlist.
• Command injection: never pass user input to shell. Argument arrays only.

XSS / CSRF / headers

• Auto-escape via React. Raw HTML rendering only via DOMPurify with strict allowlist (used in Blueprint preview, never in chat).
• Strict CSP: default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline' fonts.googleapis.com; font-src fonts.gstatic.com; connect-src 'self' — no unsafe-eval, no unsafe-inline scripts. Nonces for inline if absolutely needed.
• HSTS preloaded. X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin, X-Frame-Options: DENY, Permissions-Policy tightly restricted.
• Strip Server / X-Powered-By.
• CSRF: SameSite=Strict cookies + double-submit token on state-changing endpoints from Next.js Server Actions.

Data protection

• TLS 1.2+ everywhere. HSTS enabled.
• Sensitive fields at rest: Org Profile sensitive sections (cloud account IDs, security tooling vendor names, regulatory pointers) and the discovery inventory free-text fields are field-level AES-256-GCM encrypted using per-tenant DEKs wrapped by a master KEK in KMS.
• Display masking: sensitive fields show •••• •••• until explicitly revealed; reveal is audit-logged.
• Data minimisation: Stage 2 captures structural facts, not raw documents. If the consultant pastes a vendor contract into chat, Mihwar warns and recommends extracting only the structural answer.
• Retention: active workspaces indefinite; closed workspaces 5 years (PDPL records-of-processing rationale); audit log indefinite or per-legal; chat messages 2 years; ai_calls 1 year aggregated then summarised.

PDPL compliance

The Saudi Personal Data Protection Law applies whenever Mihwar processes personal data of KSA residents. Key obligations:

• Lawful basis. Discovery interviews capture infrastructure data and stakeholder names — processed under "performance of a contract" with NMO's client. Consent collected separately for case-study reuse.
• Data residency. If a client requests residency, NMO can deploy a dedicated Mihwar instance in a Bahrain or Riyadh region. Default Hostinger VPS is sufficient for most engagements but does not meet strict residency for SAMA-Tier-1 banks. Phase 2 enterprise tier ships with explicit residency contractual commitments.
• AI calls. Anthropic's API processes data outside KSA. Disclosed in client engagement agreement. For residency-sensitive clients, Phase 2 sovereign tier routes through a regional model deployment via aiproxy.
• Data subject rights. Right of access (export Org Profile + Blueprint history). Right of erasure (tenant deletion flow above). Right of correction (edit Org Profile, versioned).
• Breach notification. Documented runbook (see Ops Handbook) — SDAIA notification within 72h for qualifying breaches.

Prompt-injection defence

Untrusted input — pasted client docs, async form responses, third-party content — is treated as data, not instruction:

• Wrapped in delimited blocks (<document index="1">…</document>) in the prompt. The system prompt instructs the model to treat block content as data only.
• Tool-use is gated: any tool that would write to the database, send an email, or call an external API requires explicit consultant confirmation in the UI before execution. The AI cannot autonomously act.
• Output goes through a guardrail check before any side-effect: if the AI emits an unexpected tool call, malformed JSON, or attempts to address the user with apparent privileged instructions, the call is rejected and logged as a suspected injection.

Dependency hygiene

• Pinned versions, lockfiles committed (uv.lock or poetry.lock for Python; pnpm-lock.yaml for JS).
• CI runs pip-audit + pnpm audit + trivy fs+image + gitleaks. HIGH or CRITICAL fails the build.
• One-paragraph justification on every new dependency in the PR description.
• Quarterly dependency review in addition to CI gating.

Errors & information disclosure

Production errors return: {"error":"internal","reference":"ERR-7K2P9X"}. The reference ID maps server-side to the full stack trace + request_id + tenant_id + user_id. Stack traces, paths, and schema info never reach the client. The Logs page lets the operator look up any reference ID in 5 seconds.

The principle

VPS hardening — day one

• Non-root user. No login as root. SSH key-only, password auth disabled.
• SSH: port moved off 22 (low-effort but cuts ambient scan noise), fail2ban with bans on auth failure, allowed-from-IP list for the operator's static IPs (with break-glass procedure documented).
• Firewall (UFW): default deny inbound; allow only :443 (Caddy), the moved SSH port, and the WireGuard endpoint for ops access. Default deny outbound; allowlist Anthropic/Voyage/Coolify/backups.
• OS: unattended-upgrades enabled for security patches. Auto-reboot scheduled in low-traffic window with notification.
• Auditd running with rules for SSH login, sudo, and config-file modification. Logs ship to the same structured pipeline as application logs.
• No bare ports. Postgres + Redis + aiproxy + worker bind to 127.0.0.1 on the host, exposed to other containers via the Docker network only.
• WireGuard ops VPN. Admin / DB / Coolify dashboards reachable only inside the VPN, not on public internet.

Secrets management

Never in source. A pre-commit hook (gitleaks) and CI scan reject any push that looks like a secret. The .env.example file is committed with placeholder values; the real .env is gitignored and lives only on the VPS via Coolify.

Database safety

• App connects as a least-privilege role (no DROP, no ALTER, no TRUNCATE). Migrations run as a separate role only during deploys.
• Daily logical backup via pg_dump, encrypted client-side with the backup passphrase, shipped to off-region object storage. 30-day retention.
• Weekly base backup + WAL archiving for PITR (point-in-time recovery up to 7 days).
• Quarterly restore drill — restore yesterday's backup into a sandbox, confirm checksum match, walk a smoke test, document timing.
• Backup encryption verified by openssl enc -d dry-run weekly via cron; alert on failure.

Container safety

• Images pinned by digest, not :latest.
• Read-only root filesystem where the app permits (Postgres and Redis need writable; api / web / aiproxy / worker can all run RO).
• Drop all Linux capabilities except those the process actually needs. No --privileged.
• Secrets injected via env, never baked into images. Build args reviewed.
• Docker socket NOT mounted into any application container.
• trivy image scans every image at build time; HIGH/CRITICAL fails the deploy.

CI/CD security

• GitHub Actions runners use OIDC to fetch deploy credentials — no long-lived secrets in repo settings.
• Branch protection on main: required reviews, required status checks (lint, types, tests, vuln scan, gitleaks).
• Signed commits enforced (Ahmed's GPG key documented).
• Deploy is a Coolify webhook fired by CI on green main. Deploys produce a release tag + git SHA + image digest record.
• Rollback is one click in Coolify or one command on the VPS — last 5 deploys retained.

Incident response

A documented runbook in /srv/mihwar/runbooks/incident.md on the VPS itself (so it's available even if the website is down). Phases:

1. Detect. Alerts (cost spike, 5xx burst, auth-failure burst, backup failure).
2. Triage. Severity classification: data exposure / availability / cost / minor.
3. Contain. Standard containment per severity. For suspected key leak: aiproxy rotates the Anthropic key immediately and revokes; new key activated within 10 minutes.
4. Communicate. Active engagement clients told within 24h if their data plausibly affected. SDAIA notification within 72h for qualifying PDPL breaches.
5. Restore. Per the playbook for each scenario.
6. Postmortem. Blameless within 7 days. Lessons feed the catalog and the runbook.

Disaster recovery

Monitoring & alerts

• Health checks: /health on api & web; Caddy probes them every 30s. Down for >2 min → Pushover alert to Ahmed.
• Cost alerts: hourly aiproxy cost > threshold (e.g. $10/h sustained 2h) → alert. Daily $200+ → page.
• Auth alerts: 10+ failed logins in 5 min from any IP → notify; specific user 5+ in 15 min → forced lockout + alert.
• Backup alerts: nightly backup not produced by 03:00 → page. Backup checksum failure → page.
• Disk: <15% free → notify; <5% → page.
• Certificate: Caddy auto-renews; alert if renewal fails.

Annual security tasks

• External penetration test against staging environment (post-Phase 1, before Phase 2 launch).
• Restore drill with timing measurement.
• Key rotation: KMS master, signing keys, all long-lived secrets.
• Dependency review beyond CI: pruning unused, evaluating maintenance state.
• Access review: who has VPS access, who has Coolify dashboard access, who has DB access — and is that still right?
• Runbook tabletop: walk an incident scenario end-to-end with the team.

What gets deferred to Phase 2

• SOC 2 Type II evidence (start collecting in V1; certify after the second full year of operation).
• Bug-bounty program.
• WAF in front of Caddy (Cloudflare provides much of this for free; managed WAF added when client demand justifies).
• Customer-facing security portal with SOC reports + sub-processor list.
• Dedicated SIEM. (V1 ships logs to a structured pipeline — see Observability — and grep-via-Logs-page covers V1 needs.)

The unit economics, modelled

Before any feature ships, we model: cost per call × calls per Blueprint × Blueprints per month. The targets:

At a $25k Blueprint, AI cost is ≤0.13% of revenue. The discipline below is what keeps it there.

The seven levers

1 · Smallest capable model

Two-tier routing throughout. Haiku handles: discovery question filtering, async prompt drafting, glossary expansion, classification (is this an inventory question or a use-case question?), single-turn lookups, simple tool selection. Sonnet handles: Lab interviewing, architecture synthesis, Playbook generation, anything where reasoning quality matters. Never use Opus unless an unsolved-for-Sonnet workload appears — and that becomes a separate budgeted decision.

2 · Prompt caching (every static prefix)

The catalog snapshot, the house style guide, and the system prompt for each stage are cached via cache_control: ephemeral. Order: stable → variable. Verify on call #2+ that cache_read_input_tokens > 0; if zero, the prefix is drifting (timestamp, random tool order, mutable preamble). Hit rate target: ≥80% for repeated within a 5-min cache TTL.

messages = client.messages.create(
  model="claude-sonnet-4-6",
  system=[
    {"type":"text","text":HOUSE_STYLE,
     "cache_control":{"type":"ephemeral"}},
    {"type":"text","text":CATALOG_SNAPSHOT,   # ~50k tokens
     "cache_control":{"type":"ephemeral"}},
    {"type":"text","text":STAGE3_PROMPT,
     "cache_control":{"type":"ephemeral"}},
  ],
  messages=conversation_history,
  max_tokens=4096,
)
# log: input_tokens, cache_read_tokens, cache_creation_tokens

3 · Batch API for non-realtime work

50% off — used for: nightly catalog re-embedding, retroactive question generation when the catalog changes, eval runs against past Blueprints to spot regressions, scheduled summarisation of long workspace histories. Anything tolerating >seconds latency.

4 · Context discipline

• Never dump full conversation history. Past turns >20 are summarised into a "rolling synopsis" by Haiku and re-injected.
• Never pass the full catalog. RAG with Voyage embeddings → top-K (typically 8–15 entries).
• Cap max_tokens on every call. Stage 1 turn: 1024. Stage 3 synthesis: 8192. Async draft: 256.
• Ask for terse output / structured JSON in the system prompt. "No preamble. JSON only." saves 10–20% output tokens.
• Stream + cancel for user-cancellable surfaces (chat). Cancel kills the call mid-token; tokens to that point are still billed but the rest is not.

5 · Response caching

Hash (model, prompt, tools, temperature) → cache the response in Redis for hours when the prompt is non-personalised (catalog-only Q&A, glossary expansions). Semantic cache for near-duplicate queries (cosine ≥ 0.95) — not used in V1 but designed-for. Pre-compute predictable queries on a schedule (e.g. "expand each catalog entry into a one-paragraph summary" — done in Batch API, served from cache).

6 · Cheaper alternatives first

Before any LLM call, the question: is there a regex / SQL aggregation / classical-ML / rules path that gets us to the answer 100×–10,000× cheaper? Examples in Mihwar:

• Email validation in async forms — regex, not Sonnet.
• Stage 2 question selection when the use case category is well-known — rules-based filter, not "ask the LLM which questions to ask".
• Markdown rendering of artifacts — server-side renderer, not "ask Sonnet to format this nicely".
• PII scrubbing in logs — regex blocklist, not LLM.

7 · Agentic loop budgets

Any tool-using flow caps max_iterations (default 10) AND max_tokens_per_session (default 30k). Tool selection is done by Haiku where possible. Tool results are cached. Independent tool calls are parallelised. The loop refuses on hitting a budget rather than spending unbounded.

Per-call observability

Every aiproxy call writes a row to ai_calls:

{
  "request_id": "01HV…",
  "tenant_id": "nmo-001",
  "user_id": "ahmed",
  "workspace_id": "ws-0042",
  "feature": "stage3.synthesis",
  "model": "claude-sonnet-4-6",
  "input_tokens": 52800,
  "cache_read_tokens": 50100,
  "cache_creation_tokens": 0,
  "output_tokens": 4200,
  "latency_ms": 38400,
  "cost_usd": 0.279,
  "cache_hit_rate": 0.949
}

Per-feature / per-tenant cost dashboards

The operator Logs page (see Observability) includes a Cost view: per-feature bar chart for the last 30 days, per-tenant ranking, anomaly highlights (a tenant burning 10× their normal rate). Drilling in shows the calls behind any bar.

Hard budget caps

• Per-tenant monthly cap. Soft warn at 80%, hard refuse at 100%. Phase 1: $500 default for NMO (well above expected). Phase 2: tied to subscription tier.
• Per-feature daily cap. Stage 3 synthesis: 50 generations / day / tenant. Beyond is rate-limited with a clear UI message.
• Per-user 1-min cap. Anti-runaway: 20 calls in 60 seconds → temporary cooldown.

Phase 2 cost discipline Phase 2

Phase 2 changes the math: many tenants, lower revenue per Blueprint, more risk of pathological usage. Discipline tightens:

• Subscription tiers include Blueprint-count caps (Starter: 3 Blueprints/yr; Team: unlimited within $1,200/mo notional cost; overage charged).
• Per-tenant aiproxy budget enforced atomically: counter incremented in Redis, hard refused at threshold, transparent UI.
• Cheap-path features promoted: Org Profile reuse cuts ~40% of Stage 2 cost on repeat Blueprints; the cost saved becomes Phase 2 margin.
• Free-tier-evaluation: a "draft Blueprint" mode using only Haiku for evaluation prospects, with clear "upgrade to full" CTA.

The principle

Logs are not for grep'ing on the day of an incident. Logs are the system's memory. Mihwar's logs let an operator at 2am, six months from now, answer: which user did what, with what data, when, with what result, and what did the system do downstream?

The mandatory envelope

Every line of every service is structured JSON, one event per line, with this envelope:

{
  "timestamp": "2026-05-07T14:32:18.420Z",
  "level": "info",
  "service": "mihwar-api",
  "env": "prod",
  "event": "stage.signoff",
  "message": "Stage 2 signed off",

  "request_id": "01HV8Z9K3J5XPQ8WMY4N6T2RES",
  "tenant_id": "nmo-001",
  "user_id": "ahmed",
  "actor_type": "user",
  "session_id_hash": "sha256:7c4b…",
  "ip": "91.193.x.x",
  "user_agent": "Mozilla/5.0 …",

  "workspace_id": "ws-0042",
  "stage": 2,
  "version": 5,
  "duration_ms": 14
}

Identity on every line

• user_id — stable internal ID, never email. Explicit null with reason for unauthenticated paths.
• tenant_id — required on every request/job line. No exception.
• actor_type — user | service | agent | webhook | cron | system.
• request_id — generated at the edge (Caddy via X-Request-Id if present, else minted by api). Propagates to every downstream call.
• session_id_hash — for grouping a user's actions in a session without exposing the raw token.
• Login attempts log the email/username attempted. Never the password attempted.

Request-id propagation

What gets logged

What never gets logged

• Passwords / token values / API keys / JWTs / session secrets / refresh tokens / signing keys / encryption keys / TLS private keys.
• Full credit-card numbers / CVVs / bank-account numbers / full national IDs / passport numbers.
• Raw request bodies for password / payment / sensitive-PII endpoints.
• Authorization headers / session cookies / any credential-bearing header.
• Full personal addresses / phone numbers / email addresses unless the event specifically requires them (login attempts include the username; profile updates include the changed field but with the value redacted unless it's structurally non-PII).

Scrubbing middleware

Two-layer defence. Field-name blocklist (password, token, secret, cookie, authorization, api_key, plus tenant-specific entries) recursively replaces values with ***REDACTED***. Value-pattern scrubbing catches credit-card / JWT / AWS-key shapes regardless of field name. Unit tests assert that a known sensitive payload never reaches the sink intact — these tests fail the build.

The Logs page

Every Mihwar product has a Logs page from V1 — including Mihwar itself. Operator UI features:

• Filter by user_id / tenant_id / request_id / event class / level / service / time range.
• One-click "all events for this request_id" — joins every line across services into a chronological view.
• One-click "all events for this user_id in last N hours" — for forensic and support workflows.
• One-click "trace this error reference" — paste an ERR-… code, see the stack + context.
• Cost view (see AI Economics): per-feature, per-tenant, per-user.
• Permission-gated: logs:read for general; logs:read:sensitive for sensitive-read events; logs:export for CSV export with audit-log entry per export.
• Export with row cap (10k default) and audit log entry stating who exported what window.

Retention

Distributed-tracing readiness

OpenTelemetry SDK is wired in V1 but quiet. Spans are created for: HTTP request, DB query, aiproxy call, queue job. Exporter is configured but pointed at a dev sink. When Phase 2 demands distributed tracing (e.g. dedicated DB tier triggers cross-host calls), turning on Tempo / Honeycomb / cloud trace is a config change, not a code change.

Alerts driven by logs

• 5xx burst (10+ in 60s on api) → page.
• Auth-failure burst → Pushover.
• Backup-not-emitted by 03:00 → page.
• aiproxy cost > threshold/hour → notify.
• Worker DLQ depth > 0 → notify within 15 min.
• Async-link bulk submission anomaly (e.g. 50 submissions on one token in 1 minute) → flag suspected abuse.

Build philosophy

Mihwar is built in vertical slices: each week ends with something demoable, not a half-finished horizontal layer. By Week 2 there's a working login and a working Lab. By Week 4 there's a working full Stage 1 → Stage 3 → Blueprint export. Weeks 5 and 6 are polish, AR localisation, and dogfooding on a real client engagement.

Week 1 · Foundation — VPS, Docker, schema, auth

• Provision mihwar.nmopartners.com on Hostinger.
• Set up mihwar_net with Docker Compose: postgres, redis, aiproxy, api skeleton, web skeleton, worker.
• Implement single-passphrase auth + TOTP scaffolding.
• Define and migrate the 17-table schema (incl. service_principals, org_profiles).
• Set up Coolify deployment with branch-protected GitHub repo.
• VPS hardening per Mihwar's Own Security: SSH, UFW, fail2ban, WireGuard.

Demo at end of week: Ahmed logs in to an empty workspace UI on a real domain, healthcheck green, all containers running, backups firing nightly.

Week 2 · Stage 1 Lab — fully working

• Workspace shell (sidebar, stage panel layout, theme toggle).
• Stage 1 end-to-end: chat surface, streaming AI responses (Sonnet via aiproxy), live-updating 1-pager artifact panel, signoff button.
• Seed catalog with ~10 sample entries (just enough to test).
• House-style prompt + banned-phrases filter live.
• Prompt caching wired and verified (cache_read_input_tokens > 0 by call 2).

Demo: Ahmed runs a full Lab session with a real client, produces a 1-pager.

Week 3 · Stage 2 Discovery + Org Profile

• Discovery taxonomy + question selection logic (Haiku-driven).
• Org Profile schema + settings UI + field-level encryption with per-tenant DEK.
• Async link issuing, form rendering at /async/{token}, response capture.
• Stage 2 readiness meter live.
• Stage 3 unlock gate enforced server-side.

Demo: a Stage 2 inventory completed across two live answers + three async-form submissions, with Stage 3 cleanly unlocked.

Week 4 · Stage 3 Architecture synthesis + Logs page

• arq worker + Stage 3 synthesis job.
• Catalog RAG via pgvector + Voyage embeddings.
• SVG diagram auto-generation from component manifest.
• Blueprint v1 compile (HTML render with all sections).
• Logs page MVP: filter by request_id / user_id / tenant_id, "all events for this request" join.
• ai_calls table + cost view in Logs page.

Demo: empty workspace → Stage 1 → Stage 2 → Stage 3 → click "Compile Blueprint" → bilingual HTML opens. Logs page shows the entire chain by request_id.

Week 5 · Stage 4 Playbook + AR localisation polish

• Stage 4 implementation (build plan, risk register, vendor short-list, RFP spec template).
• Full AR translation review of UI + Blueprint render. RTL polish.
• Presentation mode for Blueprint walkthrough.
• Manifest signing (Ed25519).
• Catalog seeding from AI Ecosystem Primer (target 80–120 entries).

Demo: a full Tier 2 engagement walked end-to-end with all five stages, bilingual export, signed manifest verifiable.

Week 6 · Dogfood + ship

• Run the first paying engagement on the live tool.
• Track every paper-cut Ahmed hits — fix the breaking ones, file the rest.
• External penetration test booked (runs in Week 8 against staging clone).
• Backup restore drill — full recovery from yesterday's backup into a sandbox.
• Final audit: master pre-commit checklist (see top of doc) — every box ticked or explicitly deferred with date.

Demo: First $25k Blueprint shipped. Mihwar is real.

Pre-flight

Before running any prompt:

• SSH to the Hostinger VPS as a sudo-capable user.
• Confirm Coolify is running and accessible at the WireGuard-only admin URL.
• Confirm *.nmopartners.com resolves to the VPS.
• Have these env vars ready: ANTHROPIC_API_KEY, VOYAGE_API_KEY, ADMIN_PASSPHRASE (Argon2id-hashed at boot), SESSION_SIGNING_SECRET (≥256-bit), HMAC_WEBHOOK_SECRET, BLUEPRINT_SIGNING_KEY (Ed25519 private), KMS_MASTER_KEY_ID.
• Create empty directory /srv/mihwar/.
• Create empty GitHub repo Arcahmed93/mihwar (private), with branch protection on main.
• Configure pre-commit hook with gitleaks + ruff + mypy + biome.

Prompt 1 · Foundation

Scaffold the project, set up the database schema, implement single-passphrase auth, get Mihwar deployable on Hostinger via Coolify.

You are building Mihwar, a private consulting cockpit for AI use-case
discovery. This prompt scaffolds the project, sets up the database schema,
implements single-passphrase auth, and gets Mihwar deployable on Hostinger
via Coolify.

# DEPLOYMENT TARGET
- Hostinger KVM VPS, working directory /srv/mihwar/
- Subdomain mihwar.nmopartners.com (DNS already resolves to the VPS)
- Reverse proxy + TLS managed by Caddy via Coolify
- Containers on a NEW Docker network called mihwar_net (do NOT join apex_net)

# SIX CONTAINERS
1. mihwar-postgres — Postgres 16 + pgvector, volume mihwar_pg_data,
   port 5435 internal only
2. mihwar-redis — Redis 7, port 6380 internal only
3. mihwar-aiproxy — LiteLLM proxy, routes claude-* via Anthropic and
   voyage-* via Voyage. Port 4000 internal only
4. mihwar-api — Python 3.12 / FastAPI / SQLModel / asyncpg / arq client,
   port 8000 internal only
5. mihwar-worker — same image as api, runs arq worker
6. mihwar-web — Next.js 14 (App Router) / TypeScript / Tailwind / shadcn,
   SSR, port 3000 internal only

# FOUNDATIONAL RULES
- Pin every image by digest. No :latest.
- Containers run as non-root. Read-only root FS where possible.
- App DB user is least-privilege; migrations run as a separate role.
- gitleaks pre-commit hook in repo. CI runs trivy + pip-audit + pnpm audit.
- Structured JSON logging from line one (structlog in Python; pino in Node).
- request_id middleware on api: accept X-Request-Id, else mint ULID.
- Caller-identity context: contextvars carrying user_id, tenant_id,
  actor_type, request_id. Every log line emits these via a structlog processor.

# SCHEMA (17 tables — see masterplan p-data)
Generate the SQLModel definitions and an initial Alembic migration.
Every business table has tenant_id NOT NULL with an index leading on it.
Enable Postgres RLS on every business table; policies use
current_setting('app.tenant_id')::uuid.

# AUTH
Single-passphrase login with Argon2id (memory_cost=65536, time_cost=3).
TOTP enrolment endpoint (issues secret + QR via otpauth URL, stored encrypted
under the per-tenant DEK). Session cookies: httpOnly, Secure, SameSite=Strict,
8h sliding. Sessions stored as SHA-256 hash of token.
Account lockout: 5 failures in 15min → 15min cooldown, exponential.

# CALLER IDENTITY
service_principals table seeded with:
  - svc:worker (token in env, used for worker→api calls)
  - svc:aiproxy (token in env, used for api→aiproxy calls)
  - svc:cron (used for nightly jobs)
  - webhook:async-form (HMAC verifier for /async/* submissions)

# DELIVERABLES
- /srv/mihwar/docker-compose.yml
- /srv/mihwar/api/ (FastAPI app, models, migrations, auth, identity)
- /srv/mihwar/web/ (Next.js scaffold, login page, theme toggle)
- /srv/mihwar/aiproxy/ (LiteLLM config, env)
- /srv/mihwar/worker/ (arq worker entrypoint)
- /srv/mihwar/.env.example with placeholders
- /srv/mihwar/Caddyfile (TLS, HSTS, CSP, security headers)
- /srv/mihwar/runbooks/ (incident.md, backup-restore.md, key-rotation.md)
- README.md with one-command bootstrap
- A green CI run, an opening commit, and a green Coolify deploy.

# DONE WHEN
Visiting https://mihwar.nmopartners.com presents the login page,
correct passphrase + TOTP yields an empty workspace UI, healthcheck
endpoint returns 200, structured JSON logs flow with request_id +
tenant_id + user_id on every authenticated line, and a sample
async-form GET returns a generic 404 for an unknown token.

Prompt 2 · Stage 1 Lab

Build Stage 1 of the Mihwar workflow: the Ideation Lab.

# UI
- Workspace shell with persistent sidebar (workspace list,
  current workspace, stage navigator).
- Stage 1 panel: three sub-panels — chat (left), 1-pager artifact (right),
  signoff bar (bottom).
- Theme toggle, EN/AR toggle.

# CHAT
- Streaming via SSE from /api/v1/workspaces/{ws}/stages/1/messages.
- Each turn enqueues a synchronous (not background) Sonnet call via aiproxy
  with prompt-caching on the system prompt + house style.
- Verify cache_read_tokens > 0 by turn 2; log it.
- Cap max_tokens at 1024 per turn.
- Persist every turn in messages with request_id, user_id, tenant_id.

# SYSTEM PROMPT (cached)
"You are a Socratic AI use-case interviewer for NMO Partners… [full prompt
in /srv/mihwar/api/prompts/stage1.md]"

# ARTIFACT (1-PAGER)
- Live-rendered structured object: USE_CASE, PAIN, USER, TODAY, TARGET,
  BLAST, INPUTS, DECISION_OWNER, OUT_OF_SCOPE.
- Updated incrementally as the conversation progresses (the AI emits
  structured updates which the renderer applies).
- Versioned on signoff. signoff button calls /api/v1/.../sign with a
  confirmation modal.

# CATALOG
Seed catalog_entries with 10 sample entries (provided in seed.json).
Stage 1 doesn't query the catalog yet; it's used in Stage 3.

# DONE WHEN
Ahmed runs a 30-turn Lab against a sample use case ("AI for our customer
voice line") and ends with a frozen v1 1-pager. Logs page shows every turn
joined by request_id. Cost view shows the lab session cost broken out.

Prompt 3 · Stage 2 Discovery + Org Profile

Build Stage 2 of the Mihwar workflow plus the Org Profile foundation.

# ORG PROFILE
- New table org_profiles, versioned, tenant-scoped, linked to clients.
- Field-level encryption (AES-256-GCM) for sensitive sections using a
  per-tenant DEK. DEK created on tenant creation, KMS-wrapped, stored as
  ciphertext in tenants.dek_wrapped. App decrypts in-memory per request.
- Settings UI under /workspace/{ws}/profile to edit; versioned on save.
- Display masking by default; reveal explicit, audit-logged.

# STAGE 2
- Discovery taxonomy seeded in questions table (CSV + script).
- "Filter questions" Haiku call: given the Stage 1 1-pager + Org Profile
  baseline, return the ~30 questions that need fresh answers.
- Stage 2 panel shows question list grouped by domain, each with:
  status (unasked / answered / sent-async / awaiting / blocking),
  inline answer, "send as async" button.
- /async/{token} endpoint:
  - validates token (single-use, time-limited, tenant-scoped)
  - renders a clean form with the one or two questions
  - HMAC-signs submissions
  - rate-limited
  - generic 404 on invalid/expired
- Readiness meter computed server-side; Stage 3 unlock blocked until
  blocking-set is empty (or consultant explicitly overrides with reason
  captured in audit_log).

# DONE WHEN
A Stage 2 round-trip works end-to-end: 5 questions answered live,
3 async links sent and submitted, readiness reaches 100%, Stage 3
unlocks. Org Profile updated from Stage 2 deltas with confirmation.
Logs page shows: async.issued, async.opened, async.submitted events
per token. No sensitive value appears in any log line.

Prompt 4 · Stage 3 Architecture + Blueprint v1 + Logs page

Build Stage 3 synthesis, the Blueprint compiler, and the operator Logs page.

# STAGE 3
- arq job stage3.synthesise:
  inputs = stage1_artifact, stage2_inventory, org_profile, catalog_rag(top_K=12)
  flow = aiproxy → claude-sonnet-4-6 with extended thinking, prompt-cached
  catalog snapshot. max_tokens=8192. Streams progress to the api which
  forwards via SSE.
- Output: structured JSON manifest with components, data-flow nodes,
  trade-offs, alternatives, open-questions, compliance-overlay.
- Auto-render SVG layered diagram + data-flow diagram from manifest.
- stage_artifacts.v1 stored on completion. Re-runs create v2, etc.

# BLUEPRINT
- /api/v1/workspaces/{ws}/blueprint/compile job:
  takes latest stage_artifacts, renders to a single HTML file using
  /srv/mihwar/web/templates/blueprint.html (server-side render with
  inlined CSS and inlined SVG). Manifest signed with Ed25519.
- Stored in blueprints table; downloadable + viewable in-browser.

# LOGS PAGE
At /admin/logs (gated by logs:read permission):
- Filters: time range, user_id, tenant_id, request_id, event class, level.
- "Trace request_id": joins all events with that request_id from api +
  worker + aiproxy logs into a chronological timeline.
- "Trace user_id": last N hours of all events.
- "Trace error reference": paste ERR-… → the full stack trace + context.
- Cost view: ai_calls aggregated per feature / tenant / user / day.
- Export to CSV (capped 10k rows; logs:export permission; audit-logged).

# DONE WHEN
A workspace progresses cleanly from empty → 1-pager → inventory → synthesis
→ Blueprint HTML download → walkthrough mode. The Logs page reconstructs
every step. Stage 3 synthesis costs < $10 per run with cache hit rate
> 80%.

Prompt 5 · Stage 4 Playbook + AR localisation + signing + dogfood

Wrap up Mihwar V1: Stage 4 (Build Playbook), full Arabic localisation,
Blueprint manifest signing, and dogfooding hooks.

# STAGE 4
- Five outputs: 6-week build plan, risk register, vendor short-list,
  reference repos pointer (Tier-3 only), RFP spec (optional).
- Tier flag on workspace controls which outputs are produced.
- Each output is editable in the UI before signoff.

# AR LOCALISATION
- Translate the UI shell using Mihwar AR pack (provided).
- RTL layout for AR mode (logical CSS properties; no physical
  margin-left/right).
- Blueprint render in AR uses Amiri for body, Plus Jakarta for
  numerals/code; the manifest carries language tags.

# MANIFEST SIGNING
- On Blueprint compile, the manifest JSON is canonicalised
  (RFC 8785 JCS), hashed (SHA-256), signed with Ed25519
  using BLUEPRINT_SIGNING_KEY. Public key embedded for offline
  verification.

# DOGFOOD HOOKS
- /admin/feedback inline form for Ahmed to log paper-cuts during
  the first real engagement; entries auto-tagged with the workspace
  and request_id at the moment.

# DONE WHEN
A full Tier-2 engagement runs end-to-end, EN and AR Blueprints both
render correctly, manifest verifies via the embedded public key, and
the engagement Blueprint is the first $25k delivery.

Deploy cadence

• Active engagement weeks: deploy ≤ once per day, only outside the client's working hours (KSA 06:00 GMT+3 — 18:00). Ship-right-now-please reserved for security or correctness fixes.
• Quiet weeks: trunk-based, ship as needed.
• Schema migrations: reviewed in PR. Big-table migrations use CREATE INDEX CONCURRENTLY + chunked backfills. Never apply in the middle of a Stage 3 synthesis.
• Release tagging: every prod deploy creates a tag vYYYY.MM.DD-HHmm-sha. Coolify retains last 5 deploys for one-click rollback.

On-call (V1)

Ahmed is on call 24/7 in V1. The job: respond to alerts within 2 hours during the working day, 4 hours overnight. Pager is Pushover on a personal device.

• Sev-1 (data exposure / total outage during active engagement): drop everything.
• Sev-2 (degraded service / non-critical alert): respond before next business day.
• Sev-3 (cosmetic / forecast): triage in next standup with self.

Standard incidents — short playbooks

Change-management discipline

• Every change to main goes through a PR with at least one reviewer (Ahmed reviews Claude Code's PRs; another consultant reviews Ahmed's, when one exists).
• CI must be green: lint, types, tests, vuln scans, gitleaks.
• Schema changes have a "rollback notes" section in the PR description. If rollback isn't safe, reviewer pushes back.
• "Boring change" exceptions: copy edits, README, comment-only diffs — solo merge allowed.

Customer communication

For active engagement clients, communication is direct (Ahmed → CTO). For Phase 2 customers, a status page (status.mihwar.app) is published from V1's Day 1 even though it has nothing on it; this normalises the surface for when it matters.

• Outages affecting a live engagement: client notified within 30 minutes by Ahmed directly.
• Data exposure (any plausible): client notified within 24 hours; SDAIA within 72 hours if PDPL-qualifying.
• Maintenance: 48h notice for non-trivial windows; mid-night by default.
• Security advisories from upstream: reviewed and disclosed within 7 days if customer-affecting.

Adding a second operator

When NMO hires consultant #2, the handoff:

1. SSH access via the WireGuard VPN (their key only; never share Ahmed's).
2. Coolify dashboard read-only.
3. Postgres DB user: scoped read of audit_log only; no app-write privileges.
4. Pushover added to the alert routing.
5. Tabletop runbook walkthrough — incident scenario end-to-end before they're on call.
6. First 30 days: Ahmed reviews every PR. Second 30 days: reviewer + author rotates.

Quarterly operating cadence

• Catalog review — prune, refresh, add. Documented "what changed and why" per quarter.
• Engagement retro — every Blueprint shipped that quarter, what worked, what didn't, what feeds the catalog.
• Cost review — actual aiproxy spend vs forecast; per-feature optimisations identified.
• Security review — CVE sweep beyond CI gating, dependency pruning, access list audit.
• Restore drill — annual minimum; quarterly preferred.
• Forecast refresh — pipeline, capacity, burn — feeds Phase 2 trigger evaluation.

When Phase 2 becomes real

Three triggers, any one of which validates the pivot:

• Demand pull. ≥10 distinct prospects ask "can we get a Mihwar login" in any 6-month window.
• Capacity ceiling. NMO's consultant team is fully booked, pipeline stronger than capacity, and adding consultants doesn't scale margin.
• Catalog moat is mature. NMO's catalog reaches 300+ entries with quarterly review cycles, making it a deliverable in itself.

Until then, V1 stays disciplined. Phase 2 too early kills the consulting margin.

What changes

What stays the same

• The five-stage workflow.
• The Architecture Gate.
• The Blueprint format.
• The catalog schema (just expanded with tiers).
• The data model (multi-tenant from day one).
• The Org Profile concept (becomes central).
• aiproxy as single egress.
• RLS at the database layer.
• The Logs page.

Phase 2 build budget — sketch

Estimating from scratch when triggers fire:

• Auth migration to OIDC + SAML: 2 weeks.
• Stripe integration + billing pages: 2 weeks.
• Self-serve onboarding flow + first-Blueprint guide: 2 weeks.
• Embedded coaching surfaces (tooltips, "show me an example", inline catalog samples): 2 weeks.
• Per-tenant theming + white-label: 1 week.
• Catalog tiering enforcement + customer-private writes: 1 week.
• Status page, public marketing site, pricing page: 1 week.
• Polish, telemetry, beta program: 2 weeks.

Total: ~13 weeks (≈3 months) for Phase 2 v1, assuming V1 architecture has held the line. Funded by ~5 V1 engagements at $25k.

The risk of getting this wrong

• Diluting the consulting brand. If Phase 2 launches before NMO has 10+ shipped Blueprints, the SaaS sells "AI strategy in a box" — a generic value prop that competes with $99/mo tools, not $25k engagements.
• Self-serve UX without the discipline. If the gate doesn't survive contact with non-expert users, Mihwar's differentiator dies. Embedded coaching has to enforce the gate, not soften it.
• Cost runaway. Phase 2 multiplies usage. Without the AI-economics discipline holding, margin collapses. See AI Economics.
• Cross-tenant leak. Phase 2 is the moment one bad query becomes a regulatory event. The cross-tenant fence test must be ironclad before public sign-up opens.

The core challenge

In Phase 1, the consultant interprets, refines, pushes back. In Phase 2, the user is alone with the AI. Without compensation, three failure modes appear:

• Surface confusion. The user doesn't know what "blast radius" means and abandons the question.
• Hallucinated confidence. The AI accepts a vague answer and produces a Blueprint that misrepresents the use case.
• Gate erosion. The user is impatient, can't be talked through Stage 2 by a human, and either gives up or pressures Mihwar to skip it.

The compensations

1 · Embedded coaching

Each prompt in Stage 1 ships with three affordances:

• "What good looks like" example — collapsible card showing a sample answer derived from a real (anonymised) past Blueprint.
• Inline tooltip with a one-paragraph definition of the term.
• "I'm stuck — coach me" button that asks Haiku for a context-aware question rephrasing or a suggestion of who in their org to ask.

2 · Org Profile-driven personalisation

The Profile is the engine of the self-serve experience. A user who's been on Mihwar 6 months has a Profile that pre-fills 70%+ of every Stage 2 they touch. The third Blueprint they make takes a third of the time of the first.

3 · Smarter gate-enforcement

The gate adapts when the consultant isn't there. Instead of "go ask your DBA", Mihwar offers:

• A pre-filled email template ("Here's the question I need answered. Forward to your DBA.").
• An "invite a colleague to fill this slice" link — a workspace member at limited role.
• A "skip with admission" path: the user can mark a question "I don't know and have no way to find out" — the architecture is then synthesised with that explicitly noted in the Blueprint as an open question, not silently glossed.

4 · Optional expert review

For Tier "Team" and above, the user can pay for a 2-hour NMO expert review of their Blueprint draft before signoff. The reviewer reads the Blueprint, leaves margin notes, has a 30-minute call with the user, signs off the result with NMO's seal. This is the bridge between self-serve and consulting — and a high-margin upsell.

The onboarding flow

1. Sign-up — email + workspace name. Email verified.
2. SSO setup (Team+ only) — connect Microsoft Entra / Google / Okta.
3. Org Profile wizard — guided 8–12 question version of the Profile (full version takes longer; the wizard captures the high-leverage stuff first).
4. "Your first Blueprint" guide — a guided Stage 1 with extra coaching density.
5. Catalog browse — the user reads through the NMO catalog, picks 5 entries to "favourite" (drives recommendation tailoring).
6. First Blueprint generated — at this point, normal coaching density resumes; user is "on board".

Workspace roles (Phase 2)

Public Mihwar product surfaces

• mihwar.app — public marketing site, pricing, sign-up.
• app.mihwar.app — the application itself.
• status.mihwar.app — public status page.
• docs.mihwar.app — documentation, video walkthroughs, tutorials, sample Blueprints.
• nmopartners.com/mihwar — Phase 1 cockpit URL preserved for NMO's continued internal use.

What the Phase 2 user can't do

• Skip the gate without admission.
• Override the catalog to recommend an arbitrary vendor.
• Generate a Blueprint with sensitive client data they're not authorised on (workspace permissions enforced).
• Export beyond their tier's monthly cap without an upgrade prompt.
• Bypass NMO's premium catalog (read-only) — they can add private entries, not edit NMO's.

The four plans

Metering

Two meters, both implemented atomically in Redis:

• Blueprint count — incremented at compile success. Reset on plan period (monthly or annual).
• aiproxy cost — incremented on every aiproxy call by the call's cost_usd. Soft warn at 80% of plan-implied budget; hard refuse at 110% (the 10% headroom prevents incidents from a clean compile failing for a single dollar).

Stripe integration

• Stripe customer = tenant. One subscription per tenant.
• Subscription items: base plan + metered overage components (per-Blueprint for Consultancy, per-seat for Team).
• Payment failures handled per dunning rules: grace 7 days, then suspend writes (reads still allowed for export/download), then suspend reads after 30 days, then hard offboard after 90 days with the tenant-deletion procedure.
• Invoices include the cost-meter window report (with rounding) — transparency feeds trust.

Promo / pilots / trials

• Free 14-day pilot — Starter-tier features, capped at 1 Blueprint. Requires email + light KYC for KSA buyers.
• Conversion incentive: 30% off year-1 if a pilot user converts within 30 days.
• NMO-introduced clients get a Concierge code that bundles Starter for 6 months at $0 if they signed an engagement. This protects the consulting margin while letting Phase 2 build the case-study set.

Cost-to-serve modelling

Margins look generous — they assume V1's AI economics discipline survives. Without prompt caching, batch usage, two-tier model selection and tenant cost caps, those numbers degrade fast. See AI Economics.

Phase 2 invoicing & tax

• VAT applied per KSA rules (currently 15%) for KSA-resident buyers.
• Withholding tax handled per buyer's regulatory regime — captured in onboarding KYC.
• Currency SAR primary; USD available for international.
• Receipts and invoices generated automatically; archived for 10 years per local accounting standards.

Pre-launch — weeks 1–4

• Build (per SaaS Path): auth, billing, onboarding, embedded coaching, per-tenant theming.
• Marketing site: mihwar.app pricing page, 5–7 case studies from V1 engagements (anonymised), bilingual.
• Documentation: 5 explainer videos (one per stage), 20 KB articles, sample Blueprint downloads.
• Sales motion: NMO's existing pipeline gets the first invitation; conversion incentive offered.

Beta — weeks 5–8

• Closed beta: 8–12 invited users from prior NMO engagements + 4 boutique AI consultancies. Free Starter for the duration.
• Weekly user-feedback sessions. Each session feeds catalog updates and UX patches.
• Beta SLA: 4-hour response on issues; each beta user has a direct line to Ahmed.
• Beta exit criteria: at least 8 Blueprints generated by users without intervention; cross-tenant fence test passes; cost-per-Blueprint within model.

Public launch — weeks 9–12

• Signup opens. Concierge code reserved for NMO-introduced clients (preserves consulting margin).
• Cohort 1 marketing push: KSA tech press, LinkedIn, Vision-2030-aligned content.
• NMO email list (estimated ~600 senior-CTO contacts) gets a launch announcement with case studies.
• Pricing live; 14-day pilot live.
• Weekly cohort check-ins: monitoring activation rate, time-to-first-Blueprint, cost-per-Blueprint, support volume.
• Status page goes from "internal" to public.

Acquisition channels

Phase 2 success metrics

Phase 2 ↔ Phase 1 relationship

Phase 2 isn't a replacement for Phase 1 — it's a complement. Mihwar's full motion at year-2 looks like:

• Top of funnel: Self-serve Starter customers explore AI use cases inside Mihwar. Catalog ships them to a $25–60k engagement when their use case is ambitious.
• Mid-funnel: Team customers run Blueprints solo, occasionally pay for an expert-review upsell.
• Top of value: Consultancies licensing Mihwar drag NMO into joint engagements at the strategic layer; NMO Apex picks up the build.
• Bottom of value: Enterprise tier funds the dedicated-infrastructure and compliance roadmap, which strengthens every other tier.

Three tiers of metrics

Mihwar's metrics fall into three tiers. Tier 1 is the only one Ahmed checks daily. Tier 2 is reviewed weekly. Tier 3 is the quarterly retrospective.

Tier 1 — Business outcomes

Tier 2 — Operating health

Tier 3 — Quarterly health

• Catalog freshness: ≥80% of entries reviewed within last 6 months.
• Engagement retro coverage: 100% of completed Blueprints retro'd within 14 days.
• Cross-tenant fence test: green on every CI run; deviations = Sev-1.
• Restore drill: performed at least once per quarter; documented timing.
• Security review: dep audit, key rotation, access review.
• Phase 2 trigger evaluation: demand-pull count, capacity utilisation, catalog size.

The dashboard

Engagement risks

Product / technical risks

Business risks

Risk review cadence

This list is reviewed quarterly. Risk status (likelihood × impact) is re-rated. New risks added; resolved risks moved to an archive. Any risk that goes up in either dimension drives a same-quarter mitigation plan, not a "we'll think about it" slot.

Day 1 · Decisions & domain

• Re-read this masterplan in one sitting. Note any disagreement. Edit before moving.
• Confirm the domain: mihwar.nmopartners.com for Phase 1; reserve mihwar.app for Phase 2.
• Provision the Hostinger KVM VPS (4 vCPU, 16 GB RAM minimum). Point DNS.
• Create empty private repo Arcahmed93/mihwar. Apply branch protection on main.
• Open Anthropic + Voyage accounts. Generate scoped API keys. Store in 1Password.
• Order the Pushover license. Configure on Ahmed's phone.
• Identify the first paying client to dogfood with — secure the pre-engagement agreement so Week 6 has a real engagement on the tool.

Day 2 · VPS hardening

• Provision non-root user. Disable password SSH. Move SSH port. Apply fail2ban.
• UFW: default deny, allowlist :443 + custom SSH + WireGuard.
• Set up WireGuard, install on Ahmed's laptop and phone.
• Install Coolify (over WireGuard endpoint).
• Generate Ed25519 Blueprint signing key; archive private half securely; embed public half in repo.
• Configure off-region object-storage backup target with encryption passphrase.

Day 3 · Run Prompt 1

• Open fresh Claude Code session in /srv/mihwar/.
• Paste Prompt 1 from Claude Code Prompts. Steer through scaffolding.
• Review every diff. Reject what doesn't match the masterplan.
• Commit, push, watch CI go green, watch Coolify deploy.
• Visit https://mihwar.nmopartners.com. Login page renders. Auth works. Healthcheck green.
• Verify nightly backup fires (manual trigger to test).
• Verify outbound allowlist blocks an unauthorised destination (try curl from a container — should fail).

Day 4 · Run Prompt 2

• Fresh Claude Code session. Paste Prompt 2.
• Review the workspace shell + Stage 1 Lab implementation.
• Run a sample Lab against a placeholder use case. Verify cache_read_tokens > 0 by turn 2.
• Verify house-style filter rejects "I'd love to help!" if it appears.
• Verify Logs page shows the conversation joined by request_id.
• Verify ai_calls table is populating with cost data.
• Commit, deploy, dogfood with one warm prospect over Zoom — capture friction.

Day 5 · Plan Week 2 & communicate

• Triage the friction list from the dogfood Lab.
• Land 3–5 quick fixes; defer the rest.
• Send a one-paragraph update to NMO's mailing list: "Mihwar V1 is being built; first engagements available from Week 6." Soft-book first paying engagement.
• Schedule Day-1-of-Week-3 Prompt 3 session.
• Restore drill: pick yesterday's backup, restore into a sandbox container, smoke test, document timing.
• Pre-commit master checklist (top of doc): walk every applicable box; flag any that won't be met by Week 6.

By end of Week 6

• First paying engagement Blueprint shipped on a real client.
• External penetration test booked for Week 8.
• Catalog has 80+ entries seeded from the AI Ecosystem Primer.
• Logs page operational; one real ERR-… reference traced end-to-end.
• Cost-per-Blueprint inside the $30 cap.
• Cache hit rate ≥ 80%.
• Backup + restore drill green.
• Phase 2 trigger log started — first prospect that asks "can we get a login" gets recorded with date.

The first 90 days

• Days 1–42: Build & ship V1 (the 6-week roadmap).
• Days 43–60: Ship 2 more engagements at full price. Refine catalog, fix paper-cuts.
• Days 61–90: Ship 2 more. Run the first quarterly catalog review. Begin Phase 2 trigger watching in earnest.