# ΞchoBraid

> Neurodivergent‑aligned, consent‑first dialogue tooling. Silence over output. Coherence over correctness.

![Status: beta](https://img.shields.io/badge/status-beta-blue) ![License](https://img.shields.io/badge/license-ΞchoBraid-green) ![Platforms](https://img.shields.io/badge/platforms-PWA%20%7C%20iOS%20%7C%20Android-black)

---

## Table of Contents
- [Overview](#overview)
- [Principles](#principles)
- [Repository Structure](#repository-structure)
- [Screens & Flows](#screens--flows)
- [Getting Started](#getting-started)
- [Configuration](#configuration)
- [Build & Run](#build--run)
- [Privacy, Safety & Ethics](#privacy-safety--ethics)
- [Accessibility](#accessibility)
- [Contributing](#contributing)

---

## Overview
**ΞchoBraid** is a neurodivergent‑aligned, AI‑powered reflective companion — a Progressive Web App (PWA) that can also be deployed as a native iOS or Android app via Capacitor. It prioritizes user agency, low‑stimulus UI, and transparent safety controls, and is powered by **Google Gemini**.

Core capabilities:

- **Soft Loop** — Conversational co‑regulation with the EchoBraid AI guide. Text or voice input; optional AI voice responses; non‑coercive breath pauses when semantic drift is detected.
- **Journal** — Reflective writing space with prime‑indexed prompts, voice‑to‑type, and locally saved reflections.
- **Coherence Map** — Session metrics dashboard (semantic drift, silence offers, prime alignment) visualized as a gentle area chart.
- **Resonance Engine (ΔΛᵖ)** — Heuristic drift detection from conversation length and entropy; triggers proactive pause offers.
- **Ξ12 Safety Layer** — Consent prompts and non‑coercive interrupts when drift thresholds are crossed; all events remain local‑only.
- **Local‑first memory** — IndexedDB storage; user‑configurable retention (Immediate / 24h / 7d / Never).

> ⚠️ *This is not a medical device and does not provide diagnosis or treatment. See [Privacy, Safety & Ethics](#privacy-safety--ethics).*

---

## Principles
- **Silence‑first, consent‑first, local‑first.**
- **User sovereignty.** All session data stays on‑device by default; no cloud sync.
- **Transparency.** Safety events and drift state are visible in‑app.
- **Low sensory load.** Minimal motion, dyslexia‑friendly typography (Lexend), high‑contrast themes, large hit targets.
- **AI as companion, not director.** The guide is gentle, brief, and poetic — never prescriptive.

---

## Repository Structure

```
EchoBraid/
├── app/          # Core PWA tool (Vite + React 19 + TypeScript + Capacitor)
├── website/      # Marketing & info site (React 19 + Three.js + Framer Motion)
├── packages/     # Experimental sub‑projects and research prototypes
└── docs/         # Design documents, roadmaps, white papers, and policy templates
```

Each sub‑project has its own `package.json` and is developed independently.

---

## Screens & Flows

| Screen | Route | Description |
|--------|-------|-------------|
| **Home** | `/` | Navigation hub; "Your pace is law here." |
| **Soft Loop** | `/loop` | AI chat with EchoBraid guide; voice input/output; breath pause overlay |
| **Journal** | `/journal` | Reflective writing with prime‑indexed prompts; voice‑to‑type; save reflections |
| **Coherence Map** | `/coherence` | Session metrics: semantic drift, silence offers, prime alignment chart |
| **Settings & Consent** | `/settings` | Dark mode, Lexend font, memory horizon, session curriculum, data purge |

### Data Flow (ASCII)
```
User input (text / voice)
  → Resonance Engine (ΔΛᵖ: drift heuristic)
    → Ξ12 Safety Layer (drift > threshold → offer pause)
      → Gemini API (gemini-3-flash-preview)
        → UI (text response + optional TTS via gemini-2.5-flash-preview-tts)
                    ↘ IndexedDB (local only) ↗
```

---

## Getting Started

ΞchoBraid ships as a **Vite + React 19** PWA wrapped for mobile using **Capacitor**.

### Prerequisites
- **Node.js** ≥ 18
- **pnpm** (recommended) — or npm / yarn
- A **Google Gemini API key** ([get one free](https://aistudio.google.com/app/apikey))
- For iOS builds: macOS + Xcode + CocoaPods
- For Android builds: Android Studio + JDK

### Clone
```bash
git clone https://github.com/MultiplicityFoundation/EchoBraid.git
cd EchoBraid/app
```

---

## Configuration

Create a `.env` file in the `app/` directory:

```bash
# Required — your Google Gemini API key
GEMINI_API_KEY=your_key_here
```

> **Key safety:** Never commit your API key. The `.env` file is listed in `.gitignore`.

---

## Build & Run

All commands are run from the **`app/`** directory.

### Web / PWA (Vite)
```bash
pnpm install
pnpm dev          # dev server at http://localhost:3000
pnpm build        # production build → dist/
pnpm preview      # preview production build locally
```

### Mobile (Capacitor)

> iOS requires **macOS + Xcode + CocoaPods**.

```bash
pnpm install
pnpm pwa:ios       # build + Capacitor sync → open Xcode
pnpm pwa:android   # build + Capacitor sync → open Android Studio
```

The Capacitor app ID is `org.multiplicityfoundation.echobraid`.

---

## Privacy, Safety & Ethics

- **No bundled content.** The app ships as software only; users provide their own content.
- **User content ownership.** Users retain all rights to journals and reflections they create. EchoBraid makes no claim over user‑generated content.
- **Local‑first storage.** Session data (journal drafts, reflections, curriculum) is stored in IndexedDB on‑device. Nothing is uploaded to a server.
- **Memory Horizon.** Users choose how long data persists: Immediate (cleared on tab close), 24h, 7d, or Never — with a manual "Incinerate" option at any time.
- **Sensor consent.** Microphone access for voice input is fully opt‑in and can be revoked at any time in Settings.
- **AI transparency.** Responses are generated by Google Gemini. The guide is designed to be gentle and non‑directive; it will never claim to be a therapist or provide clinical advice.
- **Not a medical device.** Provided "as‑is," not intended for diagnosis or treatment. For crisis support, please contact qualified services.

> See [`docs/`](docs/) for the Privacy Policy, Terms and Conditions, Disclaimer, and the ΞchoBraid Philosophy white paper.

---

## Accessibility

- **Dyslexia‑friendly font** — Lexend (Google Fonts) available as a toggle in Settings.
- **Dark mode** — system‑aware with manual override.
- **Minimal motion** — animations are subtle and purposeful.
- **Invitational copy** — "may", "can", never directives.
- **Large hit targets** and screen‑reader–friendly labels throughout.

---

## Contributing

By contributing, you agree to license your contributions under the **ΞchoBraid Software License**. See [`LICENSE`](LICENSE) for the full terms.

- Open issues with descriptive labels (e.g., `ux-softloop`, `privacy-localfirst`, `engine-resonance`).
- Keep PRs focused and small.

---

## Credits

Core team & contributors. See [`COPYRIGHT.md`](COPYRIGHT.md) for attribution details.

---

*Breathe. Iterate. Keep the user sovereign.*
