docs: add INSTALL.md and align README for main; rustfmt workspace

- INSTALL.md: install-from-source + CI-parity verification checklist
- README/CONTRIBUTING: main green policy, INSTALL link, repo layout
- CHANGELOG: INSTALL entry; dedupe Unreleased Added section
- rustfmt across touched crates

Signed-off-by: Gnani Rahul <89947795+gnanirahulnutakki@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: gnanirahulnutakki

CHANGELOG.md

@@ -8,6 +8,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ### Added
 
+- **[INSTALL.md](INSTALL.md)** at repository root: install-from-source steps and the full verification checklist aligned with CI (format, clippy, tests, schema gate, open-verification SHA256, optional Hugo).
+
 - **M0**: Workspace bootstrap, Apache 2.0 licensing, governance documents, planning encyclopedia under `plans/` (48 documents covering landscape, gaps, value proposition, implementation, evaluation, deployment blueprints, and per-runtime quickstarts).
 - **M1**: Canonical event schema aligned with OpenTelemetry `gen_ai.*` semconv in `mara-schema`. Adapter/Sink/Policy trait surfaces in `mara-core`. Seven Architecture Decision Records covering license, WASM policy host, WAL format, hot reload, async runtime, error model, and configuration format.
 - **M2**: Pipeline scheduler (adapters → policy chain → sinks fan-out) in `mara-core::pipeline`. TOML configuration loader with JSON-schema-style validation in `mara-core::config`. JSONL tail adapter with per-file offset checkpointing. File rotation sink and stdout sink. Built-in PII redaction policy (regex-based, covering email, US phone, SSN, AWS / GCP / GitHub / OpenAI / Anthropic / Slack tokens, JWT). Head sampling policy. CLI `mara run`, `mara validate`, `mara version`, `mara setup <preset>` (stub) wired against config files. End-to-end integration test: JSONL → PII redaction → file sink.
@@ -20,17 +22,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - **CI / M2-02**: `scripts/benchmarks/schema_completeness_gate.py` plus job `schema-completeness-gate` — at least three runtime fixtures must average ≥85% fill on seven required `gen_ai`/`resource` fields.
 - **M2 (milestone board)**: Agent fields on `MaraExtensions`, gateway correlation id (`x-mara-request-id` / `mara.request_id`), dual latency metrics (gateway vs engine), `CostConfidence` for honest cost, parallel sink fan-out, `/readyz` readiness, bounded `/metrics` rendering, fan-out and sink-send-error counters, optional `server.metrics_max_in_flight_connections`, `docs/semconv.lock` + CI drift script, quickstarts, Kubernetes probe fragment, Phoenix/Presidio/eval OTLP notes, single-upstream proxy doc, vector/GPU spike ADR, Grafana compare-by-pipeline panel, and `scripts/materialize_agent_run_summary.py`.
 - **Docs / CI**: Redacted Ollama+Mara live-run bundles in `docs/captured/open-verification/` (SHA256 manifest + `scripts/captured/verify_open_verification.sh`; CI job `open-verification-sha256`).
+- Per-pipeline **`audit_policy_drops`** (default `false`): when enabled, a minimal `System` audit event (no body; correlation + `mara.policy_audit.*` + policy decisions) is sent to sinks on every policy drop. See `docs/observability/mara-policy-drop-audit.md`.
 
 ### Changed
 
 - **Breaking (policy authors)**: `PolicyOutcome::Drop` now includes the dropped `Event`. Use `PolicyOutcome::drop(event, reason)` instead of `PolicyOutcome::drop(reason)`. `ChainOutcome::Drop` is now `{ reason, event }` instead of a bare `String`.
 - **`/readyz` readiness**: `Health::is_aggregate_ready` is true only for `healthy` or `degraded` (not `starting`, `stopping`, `stopped`, or `failed`). `Adapter::health` / `Sink::health` default to `Health::healthy()` so typical pipelines stay ready unless an implementation opts into finer-grained status. See `docs/observability/mara-readyz-semantics.md`.
 - **LLM proxy**: Response `x-mara-request-id` is always a header-safe value (ASCII fast path, stripped graphic ASCII fallback, or UUID) while events keep the logical correlation id from the client or minted UUID.
 
-### Added
-
-- Per-pipeline **`audit_policy_drops`** (default `false`): when enabled, a minimal `System` audit event (no body; correlation + `mara.policy_audit.*` + policy decisions) is sent to sinks on every policy drop. See `docs/observability/mara-policy-drop-audit.md`.
-
 ### Known gaps (pre-1.0)
 
 - **OTLP**: HTTP/protobuf receivers for `/v1/logs` and `/v1/traces` are implemented in `mara-adapter-otlp`; optional gRPC (`:4317` style) logs+traces is available when `grpc_listen` is set. OTLP **HTTP exporters** in sinks are implemented; advanced exporter features remain incremental.

CONTRIBUTING.md

@@ -12,6 +12,8 @@ cargo test --workspace
 bash scripts/captured/verify_open_verification.sh
 ```
 
+For the **full** checklist (format, clippy, schema gate, optional Hugo build), see [`INSTALL.md`](INSTALL.md).
+
 The Rust toolchain is pinned in `rust-toolchain.toml`. `rustup` will install it automatically.
 
 ## Workflow

INSTALL.md

@@ -0,0 +1,82 @@
+# Installing and verifying Mara
+
+This document is the **canonical checklist** for anyone building from `main` (or any release tag). It mirrors what CI runs so you can reproduce a green build locally.
+
+## Prerequisites
+
+| Tool | Notes |
+|------|--------|
+| **Rust** | Use [rustup](https://rustup.rs/). The repo pins a toolchain in [`rust-toolchain.toml`](rust-toolchain.toml); `rustup` installs it automatically. |
+| **Python 3** | For schema completeness and open-verification scripts (stdlib only). |
+| **Hugo** (optional) | [Hugo Extended](https://gohugo.io/installation/) ≥ **0.120** to build the marketing site under [`website/`](website/README.md). |
+
+## Install from source
+
+```bash
+git clone https://github.com/ArdurAI/mara.git
+cd mara
+cargo build --release -p mara-cli
+```
+
+The `mara` binary is at `target/release/mara`. Add it to your `PATH`, or run via `cargo run --release --bin mara -- …`.
+
+### Example configuration
+
+Copy [`examples/mara.toml`](examples/mara.toml) to `mara.toml`, adjust listen addresses and paths, then:
+
+```bash
+./target/release/mara validate --config mara.toml
+./target/release/mara run --config mara.toml
+```
+
+## Verification (same gates as CI)
+
+Run from the repository root, in order:
+
+```bash
+# 1. Formatting
+cargo fmt --all --check
+
+# 2. Linter (warnings denied)
+cargo clippy --workspace --all-targets -- -D warnings
+
+# 3. Unit + integration tests
+cargo test --workspace
+
+# 4. Schema completeness gate (fixture fill-rates)
+python3 scripts/benchmarks/schema_completeness_gate.py
+
+# 5. Open verification bundles (pinned SHA256)
+bash scripts/captured/verify_open_verification.sh
+```
+
+**Expected:** every command exits with status **0**. The schema script prints a table (≥85% fill on required fields for qualifying runtimes). The verification script confirms `docs/captured/open-verification/SHASUMS256`.
+
+### Optional: Hugo site
+
+```bash
+cd website
+hugo --gc --minify
+```
+
+Output is `website/public/`. For local preview: `hugo server -D`.
+
+### Optional: Ollama smoke (needs Ollama)
+
+Short cloud smoke (see script header for environment variables):
+
+```bash
+bash scripts/realworld/ollama_cloud_smoke.sh
+```
+
+## Where results are recorded
+
+| Artifact | Purpose |
+|----------|---------|
+| `cargo test` | Rust test output in your terminal; CI logs on GitHub Actions. |
+| [`docs/captured/open-verification/`](docs/captured/open-verification/README.md) | Redacted JSONL + manifest for reproducible checks. |
+| [`.github/workflows/ci.yml`](.github/workflows/ci.yml) | Automated runs on pushes and PRs. |
+
+## Contributing
+
+After the steps above pass, follow [CONTRIBUTING.md](CONTRIBUTING.md) (DCO sign-off, focused PRs).

README.md

@@ -6,7 +6,7 @@ Think Fluent Bit for AI workloads: a small, fast, edge-deployable binary that co
 
 ## Status
 
-Pre-1.0. Active development on the v1 milestone plan ([MOS plan](plans/mara_mos_plan_d0da16c1.plan.md)).
+Pre-1.0. **`main` is expected to stay green** with the checks in [INSTALL.md](INSTALL.md) (format, clippy, tests, schema gate, open-verification SHA256). Feature work may land on `dev` first; releases and default clone experience track **`main`**. Roadmap detail: [MOS plan](plans/mara_mos_plan_d0da16c1.plan.md).
 
 ## What Mara captures
 
@@ -18,7 +18,7 @@ Tier C (analytics REST best-effort): **Augment Code**.
 
 Proxy tier (HTTP request/response capture for runtimes without native telemetry): **Ollama** (local LLM runtime).
 
-**MVP target (in active development on `cursor/mara-mvp` branch):** Claude Code (Tier A) and Ollama (Proxy) end-to-end. The other five runtimes are scaffolded and activate in MVP+1. See [the MVP plan](plans/08-mvp/01-scope-and-decision-criteria.md).
+**First-class paths on `main` today:** OTLP HTTP/protobuf (+ optional gRPC when configured), LLM HTTP proxy in front of Ollama/OpenAI-compatible servers, JSONL tail, file/stdout sinks, policy chain (redact, privacy, sample, deny), self-metrics (`/metrics`, `/healthz`, `/readyz`). Tier B/C adapters (hooks HTTP ingest, analytics polling) are configurable from TOML; see [docs/compat-matrix.md](docs/compat-matrix.md) and [the MVP plan](plans/08-mvp/01-scope-and-decision-criteria.md) for depth per runtime.
 
 See the [compatibility matrix specification](plans/05-evaluation/02-compatibility-matrix-spec.md) for details.
 
@@ -80,6 +80,7 @@ OpenTelemetry Protocol (gRPC + HTTP), Grafana Loki, Splunk HEC, Elasticsearch /
 │   └── 07-quickstarts/             # per-runtime onboarding
 ├── docs/                           # engineering reference (ADRs, runbooks)
 ├── website/                        # Hugo static site (project homepage)
+├── INSTALL.md                      # install + verification checklist for main
 └── .github/                        # CI and governance config
 ```
 
@@ -93,13 +94,16 @@ cd website && hugo server -D
 
 See [`website/README.md`](website/README.md) for theme notes, production build, and CI. Set `baseURL` in `website/hugo.toml` before deploying.
 
-## Build
+## Install and verify
+
+See **[INSTALL.md](INSTALL.md)** for a full install-from-source walkthrough and the exact command list used to validate `main` (including schema completeness and open-verification bundles).
+
+Quick check:
 
 ```bash
-cargo check --workspace
-cargo test --workspace
-cargo clippy --workspace --all-targets -- -D warnings
 cargo fmt --all --check
+cargo clippy --workspace --all-targets -- -D warnings
+cargo test --workspace
 ```
 
 The Rust toolchain is pinned via `rust-toolchain.toml`. `rustup` installs the right version on first use.
@@ -117,7 +121,7 @@ cargo run --bin mara -- --help
 cargo run --bin mara -- version
 ```
 
-In M0 the CLI is a scaffolded skeleton; real behaviors arrive in M2+ per the [phased milestones](plans/04-implementation/07-phased-milestones.md).
+The CLI implements **`mara run`**, **`mara validate`**, **`mara version`**, and **`mara setup`** (presets); behavior is driven by `mara.toml`. See [phased milestones](plans/04-implementation/07-phased-milestones.md) for history and upcoming work.
 
 ## Contributing
 

crates/mara-adapter-analytics/src/lib.rs

@@ -15,8 +15,8 @@ use mara_core::error::{Error, Result};
 use mara_core::health::Health;
 use mara_core::traits::{Adapter, EventSender};
 use mara_schema::Event;
-use reqwest::header::{ETAG, IF_MODIFIED_SINCE, IF_NONE_MATCH, LAST_MODIFIED};
 use reqwest::Url;
+use reqwest::header::{ETAG, IF_MODIFIED_SINCE, IF_NONE_MATCH, LAST_MODIFIED};
 use tokio::fs;
 use tokio::sync::Notify;
 use tokio::time::sleep;
@@ -38,7 +38,12 @@ pub struct AnalyticsHttpAdapterConfig {
 impl AnalyticsHttpAdapterConfig {
     /// Construct from parsed URL and poll settings.
     #[must_use]
-    pub fn new(name: impl Into<String>, url: Url, poll_interval_secs: u64, checkpoint_path: PathBuf) -> Self {
+    pub fn new(
+        name: impl Into<String>,
+        url: Url,
+        poll_interval_secs: u64,
+        checkpoint_path: PathBuf,
+    ) -> Self {
         Self { name: name.into(), url, poll_interval_secs, checkpoint_path }
     }
 }
@@ -64,12 +69,9 @@ impl Adapter for AnalyticsHttpAdapter {
     }
 
     async fn start(&self, out: EventSender) -> Result<()> {
-        let client = reqwest::Client::builder()
-            .timeout(Duration::from_secs(120))
-            .build()
-            .map_err(|e| Error::Config {
-                message: format!("analytics http client: {e}"),
-                path: None,
+        let client =
+            reqwest::Client::builder().timeout(Duration::from_secs(120)).build().map_err(|e| {
+                Error::Config { message: format!("analytics http client: {e}"), path: None }
             })?;
         info!(adapter = %self.cfg.name, url = %self.cfg.url, "analytics poller starting");
         let stop = self.stop.clone();
@@ -108,9 +110,13 @@ impl Adapter for AnalyticsHttpAdapter {
                         backoff = (backoff * 2).min(Duration::from_secs(300));
                         continue;
                     }
-                    let etag = resp.headers().get(ETAG).and_then(|v| v.to_str().ok()).map(str::to_owned);
-                    let last_modified =
-                        resp.headers().get(LAST_MODIFIED).and_then(|v| v.to_str().ok()).map(str::to_owned);
+                    let etag =
+                        resp.headers().get(ETAG).and_then(|v| v.to_str().ok()).map(str::to_owned);
+                    let last_modified = resp
+                        .headers()
+                        .get(LAST_MODIFIED)
+                        .and_then(|v| v.to_str().ok())
+                        .map(str::to_owned);
                     let body = match resp.bytes().await {
                         Ok(b) => b,
                         Err(e) => {
@@ -131,7 +137,8 @@ impl Adapter for AnalyticsHttpAdapter {
                                 }
                             }
                             if let Err(e) =
-                                write_checkpoint(&self.cfg.checkpoint_path, etag, last_modified).await
+                                write_checkpoint(&self.cfg.checkpoint_path, etag, last_modified)
+                                    .await
                             {
                                 warn!(adapter = %self.cfg.name, "checkpoint write: {e}");
                             }
@@ -193,10 +200,9 @@ async fn write_checkpoint(
     last_modified: Option<String>,
 ) -> Result<()> {
     if let Some(parent) = path.parent() {
-        fs::create_dir_all(parent).await.map_err(|e| Error::Io {
-            path: Some(parent.display().to_string()),
-            source: e,
-        })?;
+        fs::create_dir_all(parent)
+            .await
+            .map_err(|e| Error::Io { path: Some(parent.display().to_string()), source: e })?;
     }
     let mut s = String::new();
     if let Some(e) = etag {
@@ -209,10 +215,9 @@ async fn write_checkpoint(
         s.push_str(&l);
         s.push('\n');
     }
-    fs::write(path, s).await.map_err(|e| Error::Io {
-        path: Some(path.display().to_string()),
-        source: e,
-    })
+    fs::write(path, s)
+        .await
+        .map_err(|e| Error::Io { path: Some(path.display().to_string()), source: e })
 }
 
 fn parse_events_body(body: &[u8]) -> std::result::Result<Vec<Event>, String> {

crates/mara-adapter-hooks/src/lib.rs

@@ -67,9 +67,9 @@ impl Adapter for HooksHttpAdapter {
     }
 
     async fn start(&self, out: EventSender) -> Result<()> {
-        let listener = TcpListener::bind(self.cfg.http_listen).await.map_err(|e| {
-            Error::Io { path: Some(self.cfg.http_listen.to_string()), source: e }
-        })?;
+        let listener = TcpListener::bind(self.cfg.http_listen)
+            .await
+            .map_err(|e| Error::Io { path: Some(self.cfg.http_listen.to_string()), source: e })?;
         info!(adapter = %self.cfg.name, addr = %self.cfg.http_listen, "hooks http listening");
         let stop = self.stop.clone();
         let max = self.cfg.max_body_bytes;
@@ -173,7 +173,8 @@ fn parse_events(bytes: &[u8]) -> std::result::Result<Vec<Event>, &'static str> {
     if let Some(arr) = v.get("events").and_then(Value::as_array) {
         let mut out = Vec::with_capacity(arr.len());
         for item in arr {
-            let ev: Event = serde_json::from_value(item.clone()).map_err(|_| "invalid event in events[]")?;
+            let ev: Event =
+                serde_json::from_value(item.clone()).map_err(|_| "invalid event in events[]")?;
             out.push(ev);
         }
         if out.is_empty() {

crates/mara-adapter-jsonl/src/lib.rs

@@ -152,10 +152,8 @@ async fn tail_one(
 
     #[cfg(all(feature = "notify", unix))]
     let fs_wake: Option<std::sync::Arc<Notify>> = if notify_hot_tail {
-        let parent = path
-            .parent()
-            .map(std::path::Path::to_path_buf)
-            .unwrap_or_else(|| PathBuf::from("."));
+        let parent =
+            path.parent().map(std::path::Path::to_path_buf).unwrap_or_else(|| PathBuf::from("."));
         let n = std::sync::Arc::new(Notify::new());
         spawn_fs_wake_thread(parent, n.clone());
         Some(n)