@neuroverseos/governance 0.7.0 → 0.8.1

package/README.md

@@ -3,12 +3,103 @@
 [![npm version](https://img.shields.io/npm/v/@neuroverseos/governance)](https://www.npmjs.com/package/@neuroverseos/governance)
 [![license](https://img.shields.io/npm/l/@neuroverseos/governance)](LICENSE.md)
 
-**Control what AI can do — and how it behaves — across every app.**
+**Behavioral governance for AI systems.** Give meaning to behavior — meaning relative to the behavioral models that have been declared and governed.
 
-NeuroVerse is the governance layer for AI-powered devices. It gives users, developers, and organizations a single system to define permissions, behavioral personality, and role-based access — for smart glasses, phones, agents, or any AI-enabled product.
+Human intelligence and artificial intelligence are two different kinds of intelligence working together. All organizations, all systems, gather people around declared shared intent. NeuroverseOS tools help define those intentions into behaviors — and those behaviors become a constitution carried out at runtime.
 
-**Built for multi-agent systems:** when many agents are active, they all evaluate against the same deterministic governance model.  
-**Built for handoff:** governance is portable as world/plan artifacts, so teams can update policy quickly and hand it across agents, apps, and operators without rewriting core logic.
+NeuroverseOS is the universe where human and AI meet to work together, defined by the behaviors the organization has agreed upon. **Radiant** is the behavioral intelligence layer built on top: it reads what happened, compares it against what was declared, and tells you where the work aligns and where it drifts.
+
+Together they put you in a cocoon of behavior — not a cage, a cocoon. Something that holds your shape while you're becoming what you said you'd become.
+
+## Two products, one package
+
+| Layer | What it does | Who uses it |
+|---|---|---|
+| **NeuroverseOS** | Governance engine — worldmodel compiler, guard engine, lens system, plan enforcement | Developers building governed AI apps |
+| **Radiant** | Behavioral intelligence — reads activity, gives it meaning through the worldmodel, measures human-AI alignment | Teams and organizations (starting with Auki/ExoCortex) |
+
+Both ship in `@neuroverseos/governance`. Install once, use either or both.
+
+## Radiant — behavioral intelligence for collaboration
+
+Radiant gives meaning to behavior. It reads activity across every tool your team uses, classifies each event by who did it (human, AI, or both together), extracts behavioral signals, identifies patterns through AI interpretation governed by the worldmodel, and produces a structured read.
+
+### Five data sources, one pipeline
+
+| Source | What it reads | What it reveals |
+|---|---|---|
+| **GitHub** | Commits, PRs, reviews, comments | What was SHIPPED — architecture decisions, code quality, collaboration patterns |
+| **ExoCortex** | attention.md, goals.md, sprint.md | What was STATED — the gap between intent and action is drift |
+| **Discord** | Channel messages, threads, help requests | How the team COMMUNICATES — response times, newcomer welcome, unresolved debates |
+| **Slack** | Workspace messages, partner channels | How the team COORDINATES externally — client engagement, coalition alignment |
+| **Notion** | Page creation, updates, staleness | How the team DOCUMENTS — knowledge crystallization, doc gaps, decision records |
+
+All five produce `Event[]` → same pipeline → one read. One command, all sources:
+
+```bash
+npx @neuroverseos/governance radiant emergent aukilabs/ \
+  --lens auki-builder --worlds ./worlds/ --view team
+```
+
+### Three views for different scopes
+
+```bash
+--view community    # public repos + public channels. Anyone can reproduce.
+--view team         # + private repos + team channels. Team exocortex.
+--view full         # + cross-exocortex comparison. Leader's view.
+```
+
+### Org-level reads
+
+Point at an entire GitHub org, not just one repo:
+
+```bash
+radiant emergent aukilabs/               # entire org
+radiant emergent aukilabs/exocortex      # single repo
+```
+
+### Output structure
+
+```
+EMERGENT    — what patterns are visible in the team's work
+MEANING     — what it means against the worldmodel (plain English, no jargon)
+MOVE        — what to do about it (or "nothing's broken, keep shipping")
+ALIGNMENT   — L/C/N/R scores (human, AI, collaboration, composite)
+GOVERNANCE  — audit trail: which events triggered governance, on which side
+DEPTH       — what Radiant can see now vs what unlocks with more reads
+```
+
+### Three alignment scores nobody else measures
+
+- **L (Human work)** — is the human's activity aligned with the declared model? Not productivity — alignment.
+- **C (AI work)** — is the AI's output governed by the worldmodel? Right vocabulary? Invariants respected?
+- **N (Human–AI collaboration)** — when human and AI work together, is shared meaning preserved? This score only exists because the worldmodel provides a shared frame to measure against.
+
+### Memory + evolution
+
+Radiant writes each read to the ExoCortex as a dated Memory Palace file. Next run reads prior history, detects pattern persistence, and proposes worldmodel evolution — what to ADD (recurring candidate patterns) and what to REMOVE (invariants that haven't fired). A lean worldmodel with 5 sharp invariants is stronger than a bloated one with 20.
+
+### MCP server
+
+Configure Claude Code to call Radiant in conversation — no terminal needed:
+
+```json
+{
+  "mcpServers": {
+    "radiant": {
+      "command": "npx",
+      "args": ["@neuroverseos/governance", "radiant", "mcp",
+               "--worlds", "./worlds/", "--lens", "auki-builder"]
+    }
+  }
+}
+```
+
+Ask Claude: *"What's emerging in aukilabs/exocortex this week?"* — Claude calls `radiant_emergent` behind the scenes and responds conversationally.
+
+For the full Radiant documentation, see [`src/radiant/examples/auki/README.md`](src/radiant/examples/auki/README.md).
+
+## Governance engine — deterministic rules for AI
 
 ```
 What AI can do      →  Rules (permissions)