docs: update project README with installation and usage instructions

[aamohmd]

Summary by CodeRabbit

• Documentation
  • Completely updated project documentation with comprehensive system overview, architecture explanations, setup and configuration instructions, and project guidelines.

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Free

Run ID: 3e5b6305-fe13-4747-94b5-661e57a74bdd

📥 Commits

Reviewing files that changed from the base of the PR and between d8cc936 and 5100eef.

📒 Files selected for processing (1)

• README.md

---

📝 Walkthrough

Walkthrough

This PR replaces the repository README with comprehensive end-to-end documentation for Mizan, an AI legal assistant for Morocco. The new README covers the project's voice-first Darija-native approach, multi-agent debate architecture, offline-first capabilities, and provides complete developer setup, technical specification, and contribution guidance.

Changes

Mizan Project Documentation

Layer / File(s)	Summary
Project overview and core innovations README.md	Introduces Mizan as a voice-first, Darija-native AI legal assistant emphasizing structured tool-use JSON outputs, multi-agent debate flow (primary → devil's advocate → synthesis), and user-adaptive literacy profiles. Frames the free/local technology stack and offline-capable client behavior.
System architecture and pipeline flow README.md	Documents the end-to-end backend pipeline with intent classification, hybrid retrieval (BM25 + Cohere embeddings + reranking), multi-agent debate calls, answer formatting, and TTS feedback loop. Introduces connectivity-tier handling and provides examples of fast/slow/offline behavior.
Three AI innovations with technical depth README.md	Provides detailed code examples for function-calling constraints, claim-scoring debate/synthesis workflow with grounded/hedged/not_in_context states and confidence/lawyer-recommendation thresholds, and literacy-based user profile model with register mapping.
Retrieval, speech, and system prompts README.md	Explains hybrid retrieval pipeline with embeddings, reranking, namespace filtering, and offline fuzzy matching. Details local Whisper transcription and edge-tts streaming with offline degradation. Specifies system prompt rules for primary, devil's advocate, and synthesis agents including confidence computation and claim-softening logic.
Knowledge base sources and ingestion README.md	Describes knowledge base sources, chunking strategy with metadata schema, staleness warnings, and ingestion script commands for building the knowledge base.
Project structure and setup instructions README.md	Lists expected project directory structure with module-by-module responsibilities. Provides installation prerequisites, environment variables, backend/mobile startup commands, and evaluation/test targets.
Limitations, demo pitch, and contribution planning README.md	Documents known system limitations with mitigations in a reference table. Includes hackathon pitch with three demo moments and target metrics. Provides detailed 20-hour task split by developer role, synchronization milestones, optional addons, and specific contributing priorities.

---

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

---

Poem

🐰 A README reborn, with Darija dreams,
Multi-agents debating in structured teams,
Whisper and TTS, offline and free—
Mizan's framework, complete for all to see! ✨

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}