# AGENTS.md — Cash Raven SDK (C ABI: Windows/macOS/Linux/C#/Go/Python)

Drop this into your repository so an LLM coding agent integrates the Cash Raven
SDK correctly through its C ABI (`cr_sdk.h` + `cr_sdk.dll`/`.dylib`/`.so`).

## What this SDK does
Shares a small, capped slice of the user's bandwidth (with their consent) so the
app developer earns revenue. Rust core exposed as a C ABI.

## Non-negotiable rules
1. **Consent is mandatory and built in.** Render the SDK's consent copy
   (`cr_consent_text(CR_CONSENT_TITLE, …)`, `CR_CONSENT_INTRO`, `CR_CONSENT_SAFETY`,
   `CR_CONSENT_ACCEPT`, …) and only proceed after the user explicitly accepts.
   Do NOT substitute your own wording.
2. **`cr_client_opt_in` is the only way to start sharing.** Never auto-enable.
3. **Opt-out is required.** Add a visible control that calls `cr_client_opt_out`.
4. Call `cr_client_free` on shutdown.

## Canonical integration (C)
```c
#include "cr_sdk.h"
CrClient* cr = cr_client_new("cashraven.io", 9000, DEVELOPER_KEY, user_id);

char buf[512];
cr_consent_text(CR_CONSENT_TITLE, buf, sizeof buf);   // render this + INTRO/SAFETY/ACCEPT
// ...user accepts...

cr_client_opt_in(cr);
cr_client_start(cr);
// REQUIRED opt-out control: cr_client_opt_out(cr);

CrMetrics m; cr_client_metrics(cr, &m);               // optional: read-only stats for your UI
cr_client_free(cr);                                   // shutdown
```
For C#/Go/Python, bind these same functions (P/Invoke, cgo, ctypes).

## Device protection is automatic — nothing to call
Once sharing starts, the SDK protects the user's device on its own: it detects
the connection type (Wi-Fi / Ethernet / metered cellular) and samples CPU / RAM /
temperature itself, then enforces the per-network data caps and backs off on busy
or hot devices. You do **not** feed it network type or metrics, and there is no
knob to disable this. `cr_client_metrics` only *reads* stats for your own UI.

## Do NOT
- Do not skip/replace the consent screen, start before consent, or omit opt-out.
- Do not try to disable or override the device-protection caps.

## Avoiding antivirus false positives (Windows)
Any app that makes outbound connections — including one that embeds this SDK — can
trip Windows Defender's ML heuristic **`Trojan:Win32/Wacatac.B!ml`** when it is
**new and unsigned**. That is a reputation/behaviour false positive, not a real
signature. The SDK core is deliberately clean (no obfuscation, no packing) and adds
no malware signature; the fix is on the app **you** ship:
1. **Authenticode-sign your app** with an OV code-signing certificate (or **EV**
   for instant SmartScreen reputation). This is the single most effective step and
   you should sign released Windows apps regardless.
2. If an unsigned test build is flagged, report the false positive at
   <https://www.microsoft.com/en-us/wdsi/filesubmission> — it clears in hours-days.
3. Ship `cr_sdk.dll` as-is next to your signed app — do not repack or obfuscate it.

## Going live
Submit your build + install/usage notes in the dashboard; sharing scales up
after compliance approval (unapproved keys run in 5-device test mode).