Metadata-Version: 2.4
Name: zenon-nebula
Version: 0.6.16
Summary: Autonomous intelligence platform for the Zenon Network
Author: ZenonOrg
License: MIT
Project-URL: Homepage, https://github.com/ZenonOrg/nebula
Project-URL: Documentation, https://github.com/ZenonOrg/nebula/blob/main/README.md
Project-URL: Repository, https://github.com/ZenonOrg/nebula
Project-URL: Issues, https://github.com/ZenonOrg/nebula/issues
Keywords: zenon,blockchain,intelligence,monitoring
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: networkx>=3.0
Requires-Dist: websocket-client>=1.6.0
Requires-Dist: tomli>=2.0.0; python_version < "3.11"
Provides-Extra: full
Requires-Dist: Pillow>=10.0.0; extra == "full"
Requires-Dist: PyPDF2>=3.0.0; extra == "full"
Requires-Dist: pdf2image>=1.16.0; extra == "full"
Requires-Dist: pytesseract>=0.3.10; extra == "full"
Requires-Dist: python-docx>=0.8.11; extra == "full"
Requires-Dist: openpyxl>=3.1.0; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.0.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
Requires-Dist: hypothesis>=6.0; extra == "dev"
Requires-Dist: pip-tools>=7.0; extra == "dev"
Requires-Dist: mkdocs-material>=9.0; extra == "dev"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5; extra == "docs"
Requires-Dist: mkdocs-material>=9.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
Dynamic: license-file

# Zenon Nebula

<div align="center">

```
██████████████████▇▇▇▇▇▇▇▇▆▆▅▅▆▆▆▇▆▆▆▆▆▆▇▇▆▇▇▇▇▇▇▇▇▇▇▇▇████████
▇▇██████▇█▇███████▇▆▆▅▅▅▅▆▆▆▆▅▅▅▅▅▅▅▄▅▇▇▇▆▇▅▅▅▆▇▆▆▇▇▇▇█████████
█▇███ █▇▇▇▇▇▇▇▇▇▆▆▅▅▆▆▆▆▆▅▅▄▄▄▅▅▄▄▃▃▅▇▇▇▆▅▃▃▄▂▄▅▇▇▇▆▆▇▇▇▆▇▇▇███
█▇▇▇▇▇▇▇▆▆▆▆▆▆▆▅▅▆▇▇▇▇▇▆▆▅▄▃▄▄▅▄▅▃▂▅▆▅▃▄▅▇▇▆▅▄▓▄▅▆▅▅▄▆▇▇▇▇▇▇▇▇▇
█▇▇▇▇▇▇▇▇▄▆▆▄▆▆▆▅▆▆▆▆▆▅▄▃▃▄▅▄▂▁▃▒▁▂▂▃▄▅▅▇▇▇▇▆▅▅▄▅▅▆▆▆▆▇▇▇▇▇▇▇▇▇
█████▇▇▇▆▆▆▆▆▆▆▆▆▅▄▄▅▄▄▃▃▄▄▁▓▒▒▁▄▃▂▅▄▄▅▅▆▇▆▆▇▇▆▄▆▄▅▅▅▅▅▆▇▇▇▇▇▇▇
████▇▅███▅▆▅█▇▄▄█▇▆▇▇▇▇▃▇▇▇▆▇▇▓▃▁█▇▃▂▂▇▇▂▄▆▄▄▆▇▇▇▇▆▄███▄▇▇▇▇▇▇▇
██▇▇▇▃██▇█▂▄▇▇▂▃▇▇▂▁▓▁▁▁▇█▓▓▒█▆▃▁▆▇▃▄▄▇▆▂▓▆▅▃▆▆▆▆▆▁██▁█▇▅▇▇▇▇▇▇
▇▇▇▇▆▄▆▆▃▆█▇█▇▂▁▇▅▅▃▁▁▁▓▅▆▒▓▒▆▆▓▒▆▃▄▅▄▇▆▁▃▇▇▃▆▆▆▆▄▇▆▃▁▇██▆▇▇▇▇▇
█▇▇▇▆▅██▁▅▄▆▇▆▓▓▇▆▆▆▆▅▅▓▄▄▄▆▆▆▅▁▃▆▆▇▆▇▇▅▅▄▇▇███▇▃██▂▅▂▃▇▇▂▇▆▇▇▇
██▇▇▇▆▄▄▆▆▆▆▅▃▁▂▂▂▂▂▂▂▃▃▁▒▓▓▓▓▄▄▄▅▃▁▂▃▅▆▇▆▆▅▅▅▅▅▆▅▆▆▆▇▆▆▆▅▆▇▇▇▇
▇▇▇▇▇▇▇▇▇▇▇▇▅▓▃▃▂▁▃▂▂▃▂▂▄▃▁▒▓▂▂▃▃▄▃▃▃▅▆▇▇▆▆▆▆▆▆▆▆▆▇▆▇▇▇▇▇▇▇▇▇▇█
██▇▇▇█▇▇▇▇▆▅▂▅▅▄▂▂▂▃▂▓▂▄▅▅▄▁▒▓▓▁▂▂▄▄▄▆▆▆▅▆▆▆▆▆▆▆▆▄▇▇▇▇▇▇▇▇▇▇▇▇█
████████▇▇▆▅▇▇▆▆▇▆▆▆▅▄▄▆▆▆▅▄▄▃▄▁▂▁▁▓▓▃▁░▁▄▅▂▄▂▃▆▅▅▄▅▆▆▇▇▇▇▇▇███
███████▇▇▇▇▇▇▇▆▅▆▇▆▅▄▅▆▆▇▇▇▅▅▅▅▅▄▃▄▄▄▂▆▇▇▆▆▇▇▆▅▅▆▇▇▇▃▇▇▇▇▇▇████
█████████▇▇▇▇▇▇▇▇▇▆▆▆▆▆▇▇▇▇▇▇▇▇▆▆▆▇▆▆▆▇▇▇█████▇▇███████████████
```

_autonomous intelligence for the Network of Momentum_

</div>

<!--
  Badge strategy:
  - Static shields.io badge-endpoint badges work everywhere and are
    self-documenting via their alt text.
  - Dynamic badges (GitHub Actions status, PyPI version, last-commit)
    are re-enabled below once the GitHub repo is reachable
    unauthenticated — they 404 against restricted-visibility repos,
    so the static variants above are the portable fallback.
  - SLSA 3 badge becomes accurate only after the release workflow's
    `provenance` job runs on a tagged release.
-->
<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License: MIT"></a>
  <img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue" alt="Python 3.10–3.13">
  <img src="https://img.shields.io/badge/status-alpha-orange" alt="Status: alpha">
  <img src="https://img.shields.io/badge/version-v0.6.16-informational" alt="Version v0.6.16">
</p>

<p align="center">
  <a href="docs/SECURITY-THREAT-MODEL.md"><img src="https://img.shields.io/badge/threat%20model-documented-green" alt="Threat model"></a>
  <a href="docs/SIGNING.md"><img src="https://img.shields.io/badge/sigstore-signed-5865F2" alt="sigstore signed"></a>
  <a href="https://slsa.dev"><img src="https://img.shields.io/badge/SLSA-level%203-brightgreen" alt="SLSA 3"></a>
  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/changelog-Keep%20a%20Changelog-orange" alt="Keep a Changelog"></a>
  <a href="https://conventionalcommits.org"><img src="https://img.shields.io/badge/commits-Conventional-fe5196" alt="Conventional Commits"></a>
  <a href="MAINTAINING.md"><img src="https://img.shields.io/badge/maintainers-AI%2BHuman-9cf" alt="Maintainers: AI+Human"></a>
</p>

<!-- nebula:quality-badges:start -->
<!-- Regenerated by scripts/regen_docs.py. Do not edit by hand.
     These badges are the operator-visible quality dashboard:
     every number auto-updates from the actual codebase state on
     every ship. If a count drops, the ship is rejecting reality. -->
<p align="center">
  <img src="https://img.shields.io/badge/tests-2435_passing-brightgreen" alt="Tests: 2435 passing">
  <img src="https://img.shields.io/badge/fuzz-12_properties-brightgreen" alt="Fuzz: 12 property-based tests">
  <img src="https://img.shields.io/badge/scenarios-48_gated-brightgreen" alt="Scenarios: 48 CI-gated regression tests">
  <img src="https://img.shields.io/badge/coverage-55%25_core%20%7C%2047%25_all-brightgreen" alt="Coverage: 55% core / 47% all">
  <img src="https://img.shields.io/badge/architecture-0_violations-brightgreen" alt="Architecture: 0 audit violations">
  <img src="https://img.shields.io/badge/dep%20graph-0_cycles-brightgreen" alt="Dep graph: 0 cycles">
  <img src="https://img.shields.io/badge/lint-ruff_clean-brightgreen" alt="Lint: ruff clean">
  <img src="https://img.shields.io/badge/mutation-Phase_F-orange" alt="Mutation: Phase F">
</p>

<p align="center">
  <img src="https://img.shields.io/badge/OPSEC-scanned-brightgreen" alt="OPSEC: scanned every push">
  <img src="https://img.shields.io/badge/anti--doxxing-enforced-brightgreen" alt="Anti-doxxing: enforced by rule + test">
  <img src="https://img.shields.io/badge/bandit-SAST_gated-brightgreen" alt="Bandit SAST gated">
  <img src="https://img.shields.io/badge/pip--audit-clean-brightgreen" alt="pip-audit clean">
  <img src="https://img.shields.io/badge/rule--adherence-auditor_live-brightgreen" alt="Rule adherence auditor live">
  <img src="https://img.shields.io/badge/README%20truth-gate_live-brightgreen" alt="README truth gate live">
  <img src="https://img.shields.io/badge/integrity-manifest_signed-brightgreen" alt="Integrity manifest signed">
  <img src="https://img.shields.io/badge/domains-17_plugins-blue" alt="17 domain plugins">
  <img src="https://img.shields.io/badge/engines-93_registered-blue" alt="93 engines registered">
</p>
<!-- nebula:quality-badges:end -->

<!--
When the repo goes public, uncomment the dynamic badges below and
delete the static Version/Status ones above.

<p align="center">
  <a href="https://github.com/ZenonOrg/nebula/actions/workflows/test.yml"><img src="https://github.com/ZenonOrg/nebula/actions/workflows/test.yml/badge.svg" alt="Tests"></a>
  <a href="https://github.com/ZenonOrg/nebula/actions/workflows/codeql.yml"><img src="https://github.com/ZenonOrg/nebula/actions/workflows/codeql.yml/badge.svg" alt="CodeQL"></a>
  <a href="https://github.com/ZenonOrg/nebula/actions/workflows/scorecard.yml"><img src="https://github.com/ZenonOrg/nebula/actions/workflows/scorecard.yml/badge.svg" alt="OSSF Scorecard"></a>
  <a href="https://pypi.org/project/zenon-nebula/"><img src="https://img.shields.io/pypi/v/zenon-nebula.svg" alt="PyPI"></a>
  <a href="https://github.com/ZenonOrg/nebula/releases"><img src="https://img.shields.io/github/v/release/ZenonOrg/nebula.svg" alt="Release"></a>
  <a href="https://github.com/ZenonOrg/nebula/commits/main"><img src="https://img.shields.io/github/last-commit/ZenonOrg/nebula.svg" alt="Last commit"></a>
</p>
-->


<!-- nebula:stats:start -->
<!-- Regenerated by scripts/regen_docs.py. Do not edit by hand. -->

| Metric | Count |
|--------|-------|
| Python files | 474 |
| Lines of code | 136,709 |
| Core modules | 129 |
| Domains | 17 |
| Engines | 93 |
| Test files | 148 |
| Scripts | 23 |
| Schema tables | 88 |
| MCP tools | 8 |

<!-- nebula:stats:end -->

Nebula is an autonomous intelligence platform for the Network of Momentum. It monitors the entire Zenon ecosystem in real time - specs, code, governance, bridge health, liquidity, narratives, and security - cross-references every signal through Bayesian hypothesis evolution and collision detection, and produces mission-aligned battle plans. Nebula is critical Zenon infrastructure: the nervous system that keeps the community informed, the network hardened, and the roadmap honest.

## Mission

Nebula is not locked to any one spec author. Its mission is derived
from the Zenon protocol's trajectory itself — PTLC, Bitcoin SPV,
Portal, Atomic Swap, Commitments, Sentinel Validator, Governance,
HyperQube, and everything else in flight or on the horizon. When a
spec corpus is available the mission is re-derived from the specs on
disk; otherwise it falls back to a hardcoded 5-pillar framework.
Either way, every engine grades its own output against the same
target:

> **Become the most trustless Bitcoin-adjacent programmable settlement
> layer in crypto.** Enable non-custodial BTC ↔ ZNN movement through
> cryptographic proofs — point-locks, SPV header relays, atomic swaps,
> relayer-bonded bridges — instead of custodians or wrapped tokens.
> Preserve Zenon's sovereign consensus and dual-coin economics while
> extending programmability via embedded contracts and HyperQube
> extension chains. Never introduce admin keys, pause buttons, or
> post-activation upgrade paths. Every new contract is a composable
> building block for a more decentralized, more auditable,
> more Bitcoin-adjacent programmability layer — not a shortcut
> around its own security guarantees.

The six things Nebula grades every engine's output against:

1. **Trustlessness** — does this finding move the system closer to
   zero-custody BTC interop?
2. **Sovereignty** — does it preserve Zenon's own consensus and
   on-chain governance? (no sidechain shortcuts, no L2 custodial
   escape hatches)
3. **Composability** — does it add a building block other contracts
   can compose with, or is it a dead-end feature?
4. **Auditability** — is the change auditable without trusting an
   off-chain oracle, a relayer, or a pause key?
5. **Adoption** — is it something external operators (pillars,
   sentinels, wallets, explorers, SDK consumers) can actually use?
6. **Research edge** (v0.6.10) — does it surface a pattern from
   another protocol (Bitcoin, Lightning, Cosmos, EVM, etc.) that
   Zenon should adopt first, or a novel mechanism Zenon can ship
   ahead of the curve? The workspace is a cross-chain telescope;
   this pillar puts weight on using that leverage.

When the spec corpus is available, `core/mission/spec_derivation.py`
re-derives these pillars from what TminusZ is actually writing (so the
mission tracks the specs as they evolve, not whatever we decided to
hardcode). Without the spec repo, the six pillars above are the
fallback. See [ADR-0010](docs/decisions/0010-spec-derived-mission.md)
for the full design.

## Participants

- **Developers** - spec drift detection, cross-repo ABI consistency, upstream monitoring across the repos you have cloned locally, auto-generated PR descriptions and test vectors.
- **Pillar operators** - Accelerator-Z treasury runway, per-pillar uptime tracking, delegation-drop alerts, voting accountability scorecards.
- **Delegators and stakers** - yield comparison across pillars and sentinels, participation funnel tracking, whale accumulation signals, thesis tracker for supply contraction.
- **Security researchers** - adversarial contract reviews, CVE monitoring for dependency trees, bridge exploit patterns from 10+ real hacks, attack-cost modelling against consensus, governance, and the bridge.
- **Community** - ecosystem health trends, contributor radar, narrative resonance in Bitcoin-adjacent discussion, competitive positioning against other Bitcoin-adjacent L1s and L2s (Stacks, RSK, Botanix, Citrea, BOB — whatever the operator has cloned into their workspace).

## What Nebula actually does

Nebula is not one feature — it's a **platform** that accumulates
capabilities every release. The shipped surface, grouped by what
operators actually use it for:

### Continuous diagnosis of the Zenon ecosystem

- **17 domains × 84 engines run autonomously every cycle.** Spec drift,
  cross-repo ABI consistency, CVE exposure, bridge TVL, pillar uptime,
  narrative dominance, supply thesis, Bitcoin-adjacent competitive
  positioning — every angle a core dev, pillar operator, security
  researcher, or delegator cares about has an engine producing
  WHAT / SO WHAT / NOW WHAT findings on a 30-second cadence.
- **Cross-engine collision detection** (`core/collision_engine.py`) —
  when two distinct engines converge on the same evidence, the
  signal gets promoted to a `breakthrough_candidate`. Single-engine
  opinions never graduate.
- **Bayesian hypothesis evolution** (`core/hypothesis_engine.py` +
  `core/hypotheses/hardener.py`) — every finding contributes to a
  hypothesis with explicit confidence math, decay on staleness, and
  retirement of anything that produces no supporting evidence for
  50 cycles.
- **Mission-aligned priority scoring** (`core/mission/definition.py` +
  `core/director.py`) — every finding gets graded against the 5
  pillars. The War Room daily battle plan sorts work by mission
  alignment, not by chronological order.

### Anti-funnel trust architecture (v0.4.0)

Nebula is designed for a peer-to-peer collective where the same
finding from N independent operators should reinforce confidence
but the same finding from one engine running N times should not.

- **Content-hash dedup** — every finding normalized to a stable hash
  so two instances describing the same bug with different prose
  still count as one piece of evidence.
- **Peer corroboration** (`core/peer_corroboration.py`) — Bayesian
  merge of cross-instance findings, weighted by the publishing
  peer's trust tier.
- **Trust caps at every boundary** — unknown peers capped at 0.30
  confidence, user-declared providers capped at 0.30, LLM summary
  output capped at 0.40, branch commits capped at 0.60, merged main
  up to 1.0. The confidence ceiling is mechanical, not optimistic.

### Stale-content and pattern discovery (v0.6.6)

Two engines that surface **anomalous or unfinished content** in
scanned repos — the kind of thing that deserves a human re-read
but rarely gets one:

- **`curiosity_scanner`** — random-samples stale workspace repos
  and greps for keyword signals (`TODO`, `HACK`, `experimental`,
  `untested`) plus protocol-adjacent terms (`schnorr`, `taproot`,
  `plasma`, `sentinel`, `spork`). Emits findings with clickable
  GitHub permalinks straight to the line so the operator can
  verify in one click.
- **`pattern_discoverer`** — scans for uncommon content shapes:
  explicit marker comments (`<!-- Clue: ... -->`, `hint:` YAML
  frontmatter, `Open Questions` sections) and data-encoded blobs
  (hex / base64 strings that decode to meaningful ASCII). Both
  classes are low-noise — the false-positive rate is controlled by
  length + entropy filters — so every finding is worth a glance.
- **Regression-gated** —
  `tests/scenarios/test_pattern_scanner_coverage.py` exercises
  both engines against a test-fixture repo with known inputs every
  CI run and asserts each detection class still fires. If a future
  change breaks either path, CI blocks the merge before the
  regression ships.

### Cross-chain reference analysis

Drop any Bitcoin-family / EVM / Cosmos reference chain into your
workspace and watch these engines light up:

- **`btc_spec_tracker`** maps every BIP to its corresponding ZIP and
  flags BIPs with no Zenon counterpart.
- **`cross_chain_cve_monitor`** cross-references historical CVEs in
  the reference chain against semantically similar functions in
  go-zenon. The output is a targeted "review this file for the same
  class of bug" finding.
- **`reference_diff`** computes structural diffs (line count,
  cyclomatic complexity, decision points) between Zenon's
  consensus-critical primitives and the reference implementations.
  A 3× divergence is a smell worth reviewing.
- **`protocol_family_classifier`** tags every workspace repo into a
  family (UTXO chain, account chain, zk rollup, bridge, SDK
  consumer, tooling) and lets cross-domain queries compare peers.

### Pluggable providers (v0.6.6 registry, v0.6.9 user providers)

- **Provider registry** (`core/providers/registry.py`) — every
  external capability (HTTP APIs, MCP servers, LLMs) is a pluggable
  `APIProvider` behind a common ABC. 6 builtin wrappers (github,
  explorer, market_data, vuln_feed, zenon_data, wayback, llm_xai)
  ship with telemetry on every call — engines don't know what
  provider they're using, the registry routes.
- **Telemetry** (`core/api_telemetry.py`) — every provider call
  logs latency, status, schema hash, and response size to the
  `api_call_log` table. Value-per-API scoring falls out: when an
  API is misbehaving or expensive or producing zero findings, you
  can see it.
- **Evidence provenance** (`evidence.api_sources` column) — every
  finding records which providers it consulted. `nebula findings
  --by-provider` shows the coverage matrix. Drop a provider and
  Nebula can tell you exactly how many findings you'd lose.
- **User providers via TOML** (v0.6.9 Phase B) — drop a
  `~/.config/nebula/providers.toml` file declaring your own HTTP
  APIs or MCP servers and Nebula registers them at boot. No
  forking. Trust capped at 0.30. See *User Providers* below.

### Mechanically-enforced self-integrity

Nebula inspects its own codebase with the same rigor it inspects
Zenon's. Every release ships with the following gates, CI-enforced:

- **Self-audit engine** (v0.6.3) — `rule_adherence_auditor` walks
  every recent commit and flags drift from `.claude/rules/`. Caught
  the v0.6.1 `continue-on-error` hallucination retrospectively on
  its first real run. The engine audits its own commit on every
  ship.
- **README truth auditor** (v0.6.7) — `readme_truth_auditor` walks
  `docs/claims.yml` (963-line executable ledger of public claims),
  runs every claim's verifier, and classifies drift / broken /
  unverified / stale_forward_claim. `scripts/check_readme_truth.py`
  is a CI gate. Also detects stale forward-looking claims in
  past CHANGELOG entries (when the plan moves a feature to a later
  version, old release notes get flagged as lies).
- **Architecture gates** — `scripts/audit_architecture.py` + `scripts/generate_dep_graph.py --check`
  enforce the three invariants (core never imports domains, engines
  never import peer engines, no circular imports). v0.6.9 made the
  dep-graph gate actually block CI on violations instead of silently
  reporting them.
- **Rule freshness test** — `tests/test_rule_freshness.py` walks
  every rule file and asserts every referenced path exists. Moves
  the "stale rule" failure mode into CI.
- **Attack-vector smoke test** — `tests/test_attack_vector_smoke.py`
  statically scans for unsafe patterns (shell=True, eval, missing
  subprocess timeouts) and fails the build on violations.
- **Fuzz tests + coverage floors** (v0.6.4) — Hypothesis-based
  property fuzzing on load-bearing pure functions; coverage floors
  at 55% core / 47% core+domains enforced by CI.
- **Mutation + chaos + perf** (v0.6.13 / Phase F) — planned next;
  the 10-gap list is publicly tracked in `docs/tasks.yaml`.

### Spec-audit feedback loop to TminusZ (v0.3.0+)

- **`spec_audit` engine** walks `knowledge/developer-commons/docs/specs`,
  runs 6 structural + semantic checks per spec, and persists findings
  with reproducible commit pins.
- **`tminusz_contributor`** converts every finding into a
  paste-ready GitHub issue body (via the shared
  `core/spec_audit_contributions.py` formatter) with WHAT / SO WHAT /
  NOW WHAT sections and a clickable spec-file permalink. Maintainers
  can triage Nebula's findings in 30 seconds each.

### Durable, tiered release discipline (v0.6.8)

- **Four-tier branching model** (`.claude/rules/branching.md`):
  Tier 0 typos → direct to main, Tier 1 new code → PR + CI green
  + self-merge, Tier 2 schema / security / multi-file → add a
  1-hour soak, Tier 3 release tags → **only** via
  `scripts/release.py ship` which verifies CI green on main,
  runs the README truth gate, tags, pushes, and watches the
  release workflow until completion.
- **Branch protection on main** — 11 required status checks,
  linear history, squash-merge only, force-push disallowed,
  admin bypass reserved for Tier 0 emergencies.
- **SLSA-3 provenance + sigstore signing** on every tagged release.

### Distributed intelligence

- **Multi-instance peer sync** via `core/transport.py` —
  filesystem-based SharedDirTransport (no central server, no
  GitHub required), snapshot export / import, SpacetimeDB
  integration optional.
- **Pseudonymous peer identity** — `peer:hex16` handles or
  operator-set `ZENON_PEER_ADDRESS`. Anti-doxxing invariants
  enforced by rule + test (no `--author`, no stylistic similarity
  inference, no real-name resolution).
- **Content-hash corroboration across instances** — the more
  operators running Nebula, the more independent confirmations
  each hypothesis accumulates, the faster bias gets caught.

### Findings as a machine-actionable task queue

- **Finding lifecycle** — every finding carries `open` / `resolved` /
  `verified` status, `resolved_by`, `resolved_at`, and
  `related_findings` linking bug → fix. `auto_resolve_findings`
  runs every cycle and pairs bugs with newer verifications.
- **ActionSpec dataclass** (v0.6.6) — findings can opt in to a
  structured action spec (action_type, target_repo, target_file,
  target_line, success_criteria, effort_estimate, risk_estimate).
  Already landed as a forward-compat stub so every finding from
  v0.6.6+ is agent-ready for Phase I.
- **Phase I agent swarm** (planned v0.6.18+19) — `nebula_claim_finding`
  / `nebula_complete_finding` MCP tools let executor agents
  (Claude Code, custom, OpenAI-based) atomically pick findings off
  the priority queue, do the work, and report back. Completions
  become new evidence that runs through the same plausibility gate
  + corroboration + Bayesian update as any other finding. See the
  full plan in `docs/tasks.yaml` (task #68).

### MCP interoperability (both directions)

- **Server** — `scripts/mcp_server.py` exposes 8 tools
  (`nebula_status`, `nebula_spec_coverage`,
  `nebula_security_findings`, `nebula_battle_plan`,
  `nebula_upstream_signals`, `nebula_aspirations`,
  `nebula_collisions`, `nebula_query`) over stdio, protocol
  `2024-11-05`. Any MCP-compatible client (Claude Code, Cursor,
  custom) plugs in via `.mcp.json`.
- **Client** (v0.6.9 Phase B) — Nebula can now **consume** MCP
  servers declared in `~/.config/nebula/providers.toml`. Your
  private research MCP server becomes just another provider
  Nebula engines can call through.

### Always-safe degradation

- **No LLM key?** Nebula still runs — about 70% of engines produce
  findings on local compute alone at $0/month. Degraded engines
  emit "LLM unavailable" findings instead of crashing.
- **No workspace?** Nebula still runs — engines that scan sibling
  repos emit "workspace not installed" findings and the rest
  continue on API / on-chain data.
- **No network?** Nebula still runs — local engines (git scans,
  AST parsing, SQLite queries) work offline. Network engines emit
  graceful-degrade findings.
- **xAI hanging / timing out / rate-limited?** Every branch is
  test-pinned in `tests/test_llm_provider_failure_modes.py` with
  a failure-mode contract table in the v0.2.17 CHANGELOG entry.

## Architecture

```
           +------------------+
           |   Mission Core   |   core/mission/definition.py (6 pillars + aspirations)
           +---------+--------+
                     |
                     v
        +---------------------------+
        |  UnifiedDirector          |   scores every proposal against mission
        |  Breakthrough Engine      |   hunts convergence + anomalies
        |  Aspiration Engine        |   tracks long-lived goals
        |  War Room                 |   daily battle plan
        +-----------+---------------+
                    |
                    v
    +---------+---------+---------+---------+---------+
    | 17 Domains       | 84 Engines         | Evidence DB |
    +---------+---------+---------+---------+---------+
    |                               |
    v                               v
    Schema Registry                Transport
    (single source of truth)       (peer sync, snapshots, MCP)
```

Text-only diagram on purpose: every arrow downstream from the mission core should be traceable to a mission pillar. Nebula never acts on LLM opinion alone; findings flow through Bayesian hypothesis evolution and cross-engine collision detection before they earn confidence.

## Quick Start

```bash
git clone https://github.com/ZenonOrg/nebula && cd nebula
pip install -r requirements.txt
cp env.example.txt .env        # add at least one LLM API key (XAI_API_KEY recommended)
./nebula --cycles 5            # run five cycles, see what it found
./nebula status                # summary of findings, hypotheses, collisions
```

Zero external infrastructure required. Nebula reads a public Zenon RPC node by default (set `ZENON_PUBLIC_RPC` to point at your own). Most engines work with zero keys; adding `XAI_API_KEY` unlocks the strategic synthesis engines (~$0.0017/cycle, ~$0.17 per 100 cycles — measured from a real 400-cycle harden run, see Cost section below).

## CLI Commands

| Command | Description |
|---------|-------------|
| `./nebula` | Run continuously (24/7) |
| `./nebula --cycles N` | Run N cycles then stop |
| `./nebula --budget N` | Run with a USD budget cap |
| `./nebula --hours N` | Run for N hours |
| `./nebula --domains sec,qual` | Run only selected domains |
| `./nebula status` | Show evidence count, hypotheses, collisions, uptime |
| `./nebula findings` | Show recent findings with lifecycle status |
| `./nebula plan` | Show the latest War Room battle plan |
| `./nebula domains` | List every registered domain and its engines |
| `./nebula hypotheses` | Show Bayesian hypotheses with current confidence |
| `./nebula costs` | LLM cost breakdown by provider and model |
| `./nebula specs` | Spec coverage matrix across go-zenon, SDKs, CLI, wallet |
| `./nebula height` | Evidence-chain height (append-only) |
| `./nebula serve` | Start the MCP server (8 tools) |
| `./nebula rpc` | Start the JSON-RPC server (default: 127.0.0.1:8484) |
| `./nebula providers` | List shipped + user providers (kind, trust tier, status) |
| `./nebula providers test <name>` | Dry-run a provider to confirm it's reachable |
| `./nebula providers reload` | Re-read `~/.config/nebula/providers.toml` without restarting |
| `./nebula findings --by-provider` | Group findings by the provider that produced them |
| `./nebula snapshot export` | Export evidence snapshot for peer sharing |
| `./nebula snapshot import FILE` | Import a peer snapshot |
| `./nebula sync` | Pull the latest snapshot from configured peers |
| `./nebula workspace list` | Show the workspace manifest with per-entry clone status |
| `./nebula workspace bootstrap` | Clone every required Zenon repo into `$ZENON_WORKSPACE_ROOT` (idempotent) |
| `./nebula workspace update` | `git fetch` on every cloned manifest entry (never auto-merges) |
| `./nebula workspace pin` | Report current HEAD SHAs + branches of cloned entries |
| `./nebula ask "question"` | Freeform query against the knowledge graph |

## 17 Domains, 84 Engines

### Building and shipping

| Domain | Engines | Purpose |
|--------|---------|---------|
| development | spec_tracker, impl_coverage, upstream_monitor, dependency_chain, spec_drift, spec_audit, btc_spec_tracker | Spec tracking, implementation coverage, upstream change detection, spec quality audit |
| quality | spec_verifier, build_verifier, cross_repo_checker, test_coverage, reference_diff | ABI byte-level comparison, build verification, cross-repo consistency, reference-chain diff |
| security | adversarial_reviewer, vuln_scanner, static_analyzer, report_generator, attack_simulator, cve_monitor, exploit_scanner, cross_chain_cve_monitor, attack_vector_scanner | Attack surface analysis, CVE tracking, fund-safety reviews, Nebula self-audit |
| standards | bip_zip_tracker, deployment_pipeline, crypto_compliance | BIP/ZIP tracking, release pipeline, crypto primitive compliance |
| devops | devnet_manager, rpc_client, integration_tests, test_runner | Devnet orchestration, JSON-RPC smoke tests, integration runners |
| contribution | pr_readiness, pr_description_gen, tminusz_contributor, auto_contributor, workspace_recommender | PR checklist, description generation, test vector extraction, workspace recommendations |

### Understanding the network

| Domain | Engines | Purpose |
|--------|---------|---------|
| intelligence | upstream_watcher, signal_detector, signal_router, ecosystem_health, repo_relationship_mapper | Git firehose, commit classification, signal routing, cross-repo dependency mapping |
| governance | treasury_monitor, proposal_analyzer, voting_patterns, governance_intel, pillar_accountability | Accelerator-Z runway, proposal lifecycle, per-pillar voting |
| network_health | node_census, decentralization_scorer, bridge_health, pillar_monitor | Nakamoto / HHI / Gini, bridge TVL, pillar uptime |
| economics | supply_tracker, staking_analyzer, liquidity_monitor, funnel_tracker, whale_watcher, yield_calculator | Emission, staking, DEX depth, participation funnel, whale tracking, yield comparison |

### Strategy and narrative

| Domain | Engines | Purpose |
|--------|---------|---------|
| product_market_fit | landscape_scanner, technical_positioning, roadmap_predictor, adoption_tracker, fork_detector, ecosystem_gap | Competitive mapping against Bitcoin-adjacent programmability projects (Stacks, RSK, Botanix, Citrea, etc.) and any reference chain in the workspace |
| investigation | architecture_analyzer, vision_tracker, protocol_family_classifier, curiosity_scanner, source_quality_scorer, pattern_discoverer | Code archaeology, architectural patterns, content-based trust scoring, stale-content + pattern anomaly detection (direct marker comments + indirect data-encoded blobs) |
| marketing | narrative_analyzer, ecosystem_positioning, narrative_dominance, bitcoin_narrative_builder | Narrative resonance, BTC-adjacent story hunting |

### Self-awareness

| Domain | Engines | Purpose |
|--------|---------|---------|
| education | doc_quality, onboarding_tracker | Wiki completeness per contract, developer onboarding grading |
| community | contributor_tracker, health_scorer, talent_radar, sentiment_tracker | Contributor activity, talent scoring, sentiment |
| interoperability | bridge_compat, evm_readiness, consensus_monitor | Bridge versioning, HyperQube/Supernova, cross-chain consensus |
| self_maintenance | engine_health_monitor, config_drift_detector | Engine success-rate monitoring, config drift detection |

## Core Modules

Nebula separates orchestration from discovery. The core layer is deliberately small and deterministic so domain engines can rely on it without worrying about ordering or state leaks.

**Mission and priorities** - mission.py, director.py, war_room.py, strategy_evolver.py, aspiration_engine.py, breakthrough_engine.py, red_team.py, persona_panel.py

**Evidence and hypotheses** - persist_to_db.py, schema_registry.py, evidence_vault.py, feedback_bus.py, collision_engine.py, knowledge_graph.py, validation_spiral.py, synthesis_engine.py, cascade_detector.py, hypothesis_engine.py, hypothesis_hardener.py, peer_corroboration.py

**Orchestration** - domain_registry.py, engine_scheduler.py, parallel_runner.py, run_context.py, template_dag.py, adaptive_router.py

**LLM routing** - model_router.py, llm_provider.py, prompt_builder.py, cost_optimizer.py

**Discovery** - discovery_base.py, curiosity.py, workspace_discovery.py, corpus.py, experiment_manager.py, self_extension.py, self_improver.py

**Network and data** - zenon_data.py (HTTP JSON-RPC to the Zenon chain), node_rpc.py (WebSocket to local znnd), nebula_rpc.py (HTTP server for peer Nebulas), explorer_api.py, market_data.py, github_api.py, universal_rpc.py, vuln_feed.py

**Transport and peers** - transport.py, sync.py, mcp_bridge.py, commons.py, integrations/

**Safety** - trust.py, opsec.py, hallucination_guard.py, forensic_audit.py, resilience.py, plausibility_gate.py, novelty_checker.py, finding_verifier.py, anomaly_detector.py

**Utilities** - commons.py, workspace.py, git_cache.py, file_extractors.py, api_fingerprint.py, failure_classifier.py

## Data Sources

Nebula pulls from every public source that matters for Zenon, with no special access required:

- **Zenon RPC** - HTTP JSON-RPC (default `https://my.hc1node.com:35997`) or local znnd via WebSocket. Ledger, pillar, sentinel, accelerator, token, bridge, stake, plasma namespaces all covered.
- **Git repositories** - whichever Zenon ecosystem repos are present under `ZENON_WORKSPACE_ROOT`. Nebula scans them every cycle for commits, spec drift, and dependency changes. Repos that aren't cloned locally are skipped (engines that depend on them return empty and log a "workspace missing" note). See "Local vs remote tracking" below.
- **GitHub API** - PR status, issue activity, contributor graphs.
- **CoinGecko** - ZNN / QSR price, market cap, 24h volume, rolling returns.
- **DexScreener** - wZNN/ETH pair depth, liquidity, trader counts.
- **DefiLlama** - bridge and protocol TVL via the `zenon-finance` slug.
- **LunarCrush** - social sentiment metrics when `LUNARCRUSH_API_KEY` is set.
- **OSV.dev** - dependency CVE lookups for go.sum / pubspec.lock.
- **Fear & Greed (alternative.me)** - market sentiment context.
- **Stacker News, HN Algolia, r/Bitcoin** - Bitcoin-narrative scanner inputs.
- **MCP peers** - SETI and any MCP-compatible tool plugged in via `NEBULA_MCP_PEERS`.

Every API integration is documented in the audit report `core/api_templates/` and rechecked by the quality domain on a schedule.

## Schema Registry

Every engine owns its tables. `core/schema_registry.py` walks the core package plus every domain plugin and engine module at startup, collects declared `SCHEMA_SQL` fragments, and applies them in dependency order with `CREATE TABLE IF NOT EXISTS`. Adding a new engine automatically adds its tables; removing one never leaves dead schema.

This replaces the old three-places-to-declare-schema pattern that caused "no such column" errors whenever an engine evolved ahead of `persist_to_db.SCHEMA_SQL`.

## Mission Alignment

`core/mission/definition.py` declares five weighted pillars: technical excellence (0.28), ecosystem expansion (0.20), narrative dominance (0.20), security hardening (0.20), adoption growth (0.12). `mission_alignment()` grades any finding against every pillar deterministically using domain membership, keyword density, and explicit tags. The Director boosts aspirations that rank high on mission alignment. The Breakthrough Engine flags any finding whose overall alignment crosses 0.65 as a `breakthrough_candidate` even without convergence or anomaly support.

## Breakthrough Hunting

`core/breakthrough_engine.py` runs three detectors every 10 cycles:

1. **Cross-engine convergence** - two or more distinct engines reporting the same evidence type inside a 24-hour window promote the signal.
2. **Anomaly amplification** - a single finding more than three sigma above its engine's baseline confidence distribution gets promoted.
3. **Mission-critical surfacing** - a single finding with `mission_alignment.overall >= 0.65` gets promoted.

Breakthrough candidates are persisted with evidence type `breakthrough_candidate` so the War Room can inspect them first. The whole module is deterministic: zero LLM cost.

## Aspiration Engine

`core/aspiration_engine.py` collects aspirations from the mission core and from every domain plugin, grades them on alignment / support / feasibility, and retires the ones that produce no progress for 50 cycles. Aspirations are queryable via `nebula aspirations`. Engines signal progress by persisting evidence with type `aspiration_progress:<title>`.

## MCP Integration

Plug Nebula into Claude Code, Cursor, or any MCP-compatible tool:

```bash
claude mcp add nebula python3 scripts/mcp_server.py
```

Eight tools exposed: `nebula_status`, `nebula_spec_coverage`, `nebula_security_findings`, `nebula_battle_plan`, `nebula_upstream_signals`, `nebula_aspirations`, `nebula_collisions`, `nebula_query`.

Questions like "what does Nebula say about the bridge?" route to the security and network_health evidence. Questions like "what's the next spec to ship?" route through the Director.

## User Providers — bring your own HTTP APIs and MCP servers

**v0.6.9 Phase B.** Nebula's provider registry (v0.6.6) ships 6 builtin
wrappers (github, explorer, market_data, vuln_feed, zenon_data, wayback,
llm_xai). As of v0.6.9, you can **declare your own HTTP APIs and MCP
servers** in a user-space TOML config and Nebula registers them at boot
alongside the shipped providers. No forking. No engine edits.

Drop this at `~/.config/nebula/providers.toml` (or `$XDG_CONFIG_HOME/nebula/providers.toml`
or `$NEBULA_PROVIDERS_CONFIG` if you want to override the path):

```toml
# Declarative HTTP API — becomes a callable APIProvider
[[api]]
name = "my-private-blockscout"
description = "Internal block explorer for my chain"
base_url = "https://blockscout.internal.example.com/api/v2"
auth_env_var = "MY_BLOCKSCOUT_TOKEN"   # read at call time, never persisted
auth_header = "Authorization"           # default: Authorization
auth_prefix = "Bearer "                 # default: "Bearer "
rate_limit_rps = 2                      # default: 1
timeout_seconds = 15                    # default: 10
trust_tier = "user"                     # capped at DEFAULT_TRUST (0.30)

  [[api.endpoints]]
  method_name = "get_block"
  http_method = "GET"
  path = "/blocks/{block_number}"
  response_jsonpath = "$.data"          # optional projection

  [[api.endpoints]]
  method_name = "get_address"
  http_method = "GET"
  path = "/addresses/{address}"

# MCP server provider — Nebula spawns it as a subprocess
[[mcp]]
name = "my-research-mcp"
description = "My private research MCP server"
command = "python3"
args = ["/abs/path/to/research_server.py"]
trust_tier = "user"
timeout_seconds = 30

# Or: an MCP server reachable via HTTP transport
[[mcp]]
name = "shared-team-mcp"
url = "https://mcp.team.example.com:3000"
auth_env_var = "TEAM_MCP_TOKEN"
trust_tier = "user"
```

Then manage it via `./nebula providers`:

```bash
./nebula providers list             # shipped + user, with kind + status
./nebula providers test my-private-blockscout
./nebula providers reload           # re-read config without restarting
./nebula providers add <snippet>    # append to user config (validates first)
./nebula providers remove <name>    # remove from user config
```

**Safety rails, mechanically enforced:**

- User providers are tagged `kind="api-user"` or `kind="mcp-user"`
  in the registry. Any finding that cites a user provider in its
  `api_sources` is capped at `DEFAULT_TRUST = 0.30` via
  `core.trust.cap_confidence_by_provider`, regardless of the
  engine's claimed confidence. A buggy or malicious user provider
  cannot pollute the evidence store with high-confidence findings.
- Path-param substitution is string replacement with URL encoding,
  not `eval`. The URL is OPSEC-scrubbed via `core.opsec.sanitize_url`
  before fingerprinting or logging. Auth tokens are read from the
  environment at call time — never persisted and never logged.
- Invalid TOML entries are skipped with a warning at boot, never
  crash the runner.
- MCP subprocess lifecycle is managed by `MCPConsumerProvider.shutdown()`
  which the graceful-shutdown path calls for every registered
  provider.

See `docs/runbooks/user-providers.md` for the end-to-end walkthrough.

## Multi-Instance Sharing

Run multiple Nebula instances and share intelligence:

```bash
# Instance A: publish
./nebula snapshot export            # data/snapshot_<timestamp>.json

# Instance B: consume
./nebula snapshot import data/snapshot_<timestamp>.json
./nebula sync                       # pull from configured peers
```

Evidence records carry SHA-256 integrity hashes and participant attestation. `core/peer_corroboration.py` boosts confidence on findings that independent peers also produced; trust in unknown peers is capped at 0.30 until reputation is earned. Peer corroboration only ever raises confidence - never lowers it.

## Local vs remote tracking — what runs with what you have

Nebula has two kinds of engines: ones that read files on your disk, and
ones that call external APIs. The more repos you have cloned locally, the
more of Nebula's 84 engines actually produce output.

**Engines that REQUIRE a local clone** (silently no-op without it):

| Engine | Needs |
|---|---|
| `upstream_watcher` | `git -C <repo>` — any git repo in the workspace |
| `spec_tracker` · `spec_drift` · `impl_coverage` | `knowledge/developer-commons/docs/specs` + `core/go-zenon` |
| `btc_spec_tracker` | A Bitcoin-family repo with a `bips/` directory |
| `reference_diff` | A reference chain repo (Bitcoin, Ethereum, etc.) + Zenon repos |
| `repo_relationship_mapper` | Any workspace repos with manifests (go.mod, pubspec.yaml, package.json, Cargo.toml) |
| `contributor_tracker` · `architecture_analyzer` · `vision_tracker` | Source repos on disk |
| `protocol_family_classifier` | Any workspace repos (for classification signals) |
| `cross_chain_cve_monitor` | At least one reference chain repo in the workspace |

**Engines that work without any local clones** (API + on-chain only):

`repo_relationship_mapper`, `ecosystem_health`, `cve_monitor`, `vuln_scanner`,
`node_census`, `decentralization_scorer`, `staking_analyzer`,
`treasury_monitor`, `supply_tracker`, `bridge_health`, `market_data`,
`narrative_analyzer`, `sentiment_tracker`, `consensus_monitor`,
`proposal_analyzer`, `voting_patterns`, `yield_calculator`.

Practical rule: if you only have go-zenon and znn_sdk_dart cloned, about
half of Nebula's engines produce data. Clone more of the ecosystem (see
`knowledge/`, `core/`, and `infrastructure/` sub-trees in the Zenon
workspace layout) and coverage grows linearly.

**One-command bootstrap (v0.6.10).** On a fresh install you don't have
to hunt down each repo by hand. Nebula ships
`data/workspace-manifest.yaml` — a canonical catalog of the Zenon
ecosystem repos it expects — and exposes `./nebula workspace
bootstrap`, which clones every `required: true` entry into its
declared path under `$ZENON_WORKSPACE_ROOT`. The command is
idempotent (already-cloned entries are skipped), has a `--dry-run`
flag, and a `--use-fork` flag for contributors who want `origin`
pointed at the ZenonOrg fork they can push to. Full walkthrough:
`docs/runbooks/workspace-manifest.md`.

## Drop reference chains into your workspace to unlock cross-chain analysis

**This is one of Nebula's most powerful features and the easiest win once
you try it.** Zenon's specs, particularly PTLC, Portal, Bitcoin SPV, and
Sentinel Validator, consciously borrow from other protocols. Without a
reference implementation in the same workspace, Nebula can only reason
about Zenon in isolation. With one, a whole class of engines lights up.

### What happens when you add Bitcoin Core

```bash
# Assume your workspace already has go-zenon + SDKs.
cd ~/Repos/Zenon
git clone --depth 50 https://github.com/bitcoin/bitcoin core/bitcoin
```

On the next cycle, Nebula's `workspace_discovery` detects the new repo,
classifies it as `blockchain_node_btc` via the generic signatures in
`core/workspace_discovery.py::REPO_SIGNATURES`, and writes it to the
`workspace_repos` table. Four cross-chain engines then activate:

- **`domains/development/btc_spec_tracker`** — walks the `bips/`
  directory, maps each BIP to a corresponding ZIP in
  `knowledge/developer-commons/docs/zips/` (if present), and flags any
  BIP that has no ZIP counterpart. If BIP-324 is merged upstream but
  there's no ZIP-XX draft for equivalent Zenon work, Nebula surfaces
  the gap with a WHAT/SO WHAT/NOW WHAT finding.
- **`domains/security/cross_chain_cve_monitor`** — cross-references
  historical Bitcoin Core CVEs (CVE-2024-35202 merkle proof
  validation, CVE-2022-44797 btcd taproot signature malleability,
  etc.) against semantically similar function names in go-zenon.
  When `go-zenon/vm/embedded/bitcoin_spv/verify.go` contains a function
  shaped like Bitcoin's patched code path, you get a targeted "review
  this file for the same class of bug" finding.
- **`domains/quality/reference_diff`** — for consensus-critical
  primitives like merkle proof validation and secp256k1 signature
  verification, extracts the function body from both codebases, computes
  a structural diff (line count, cyclomatic complexity, decision
  points), and flags large divergences. A Zenon function that's 3x more
  complex than its Bitcoin reference is a smell worth reviewing.
- **`domains/investigation/protocol_family_classifier`** — classifies
  every workspace repo into a family (UTXO chain, account chain, zk
  rollup, bridge, SDK consumer, tooling) and lets cross-domain queries
  compare peers within a family.

### What happens when you add Ethereum (go-ethereum)

```bash
git clone --depth 50 https://github.com/ethereum/go-ethereum core/geth
```

`protocol_family_classifier` tags it as `blockchain_node_evm`. The same
four engines above re-run against EVM primitives. `reference_diff`
compares Zenon's EVM-adjacent code (the HyperQube extension chain work)
against go-ethereum's reference implementations. `cross_chain_cve_monitor`
pulls the known Geth CVE list as its corroboration baseline.

### What happens when you add Cosmos SDK

```bash
git clone --depth 50 https://github.com/cosmos/cosmos-sdk core/cosmos-sdk
```

Classified as `blockchain_node_cosmos`. Engines then compare Zenon's
governance contract against Cosmos `x/gov`, and (when Sentinel Validator
lands) compare Zenon's validator set management against Cosmos
`x/staking`. This was the Zenon governance spec's cited inspiration —
having the reference on disk lets Nebula actually check alignment.

### Why this is a killer feature

- **Cross-pollinate security fixes.** Bitcoin Core spends millions of
  dollars a year on adversarial review. Every CVE they find is public.
  Nebula can automatically ask "does Zenon have the same bug?" for
  every fix — something no human does continuously.
- **Find spec gaps before TminusZ does.** When Bitcoin adopts BIP-324,
  Nebula flags "no corresponding ZIP." The Zenon community sees the
  signal weeks before manual review would catch it.
- **Prove primitives are correct by triangulation.** `reference_diff`
  won't catch subtle logic bugs, but it will catch "Zenon's merkle proof
  verifier is 200 lines while Bitcoin's is 40" — a red flag that says
  either Bitcoin is missing a check or Zenon added something worth
  auditing. Either answer is valuable.
- **Zero extra LLM cost.** All four engines use stdlib parsing + regex.
  No API calls. Running them forever is free.

**The invitation:** if you run Nebula, spend the 30 seconds to
`git clone --depth 50 bitcoin/bitcoin` into your workspace. You will
start surfacing findings within one cycle that nobody else in the
Zenon ecosystem is looking at.

## The network effect: more instances = sharper signal

**Nebula gets smarter as more people run it.** This isn't marketing — it's a
consequence of how the evidence and hypothesis layers are designed.

Each operator runs their own Nebula instance against their own workspace
(different forks, different API keys, different schedules, different
subsets of the 17 domains). Every instance independently produces findings
and hypotheses. Those findings flow to a shared commons via
`./nebula snapshot export` or the Nexus transport, and every other instance
pulls them via `./nebula sync`.

What happens next is the key:

- **Independent confirmation boosts confidence.** If instance A's
  `vuln_scanner` flags a bug in go-zenon and instance B's
  `adversarial_reviewer` independently flags the same bug, the
  Bayesian hypothesis update in `core/peer_corroboration.py` combines
  those two signals into a higher-confidence hypothesis than either
  alone. Two independent engines from two independent operators is
  much stronger evidence than either one alone.
- **Coverage compounds.** Operator A might have go-zenon on their disk
  but not znn_sdk_dart; operator B has the opposite. A single operator
  can only ever scan what they have. The commons sees the union.
- **Stale signal ages out.** `core/hypotheses/hardener.py` retires
  hypotheses whose supporting evidence is older than the staleness
  window. When multiple instances refresh the same finding on different
  schedules, the commons always has recent evidence.
- **Bias detection gets cheaper.** `hypothesis_hardener.py` flags
  single-source bias ("all supporting evidence came from one engine").
  With more operators running, the probability of single-source bias
  drops toward zero — there are more engines across more instances
  producing evidence against the same hypothesis.
- **Trust model prevents poisoning.** A malicious peer publishing
  garbage can only ever move a finding's confidence by at most their
  trust score, which is capped at 0.30 for unknown peers. Corroboration
  only ever raises confidence — a bad peer can't lower a good peer's
  finding. Trust compounds over time with a proof-of-work-style
  reputation curve.
- **Aggregate metrics become reliable.** Cost tracking, engine health,
  budget pacing — single-instance stats are noisy; commons-wide stats
  are actionable.

The practical implication: if you're the only operator running Nebula, you
get a solid solo-researcher tool. If you're one of ten, the commons is
richer than any of you could produce alone. If you're one of a hundred,
Nebula becomes a real-time distributed intelligence surface for the entire
Zenon ecosystem — which is the design target.

**The easiest way to make Nebula smarter is to run it.** Every new
operator's findings become everyone's signal, subject to the trust model.
See `docs/operations/multi-instance.md` for the transport modes (local
snapshots, Nexus via SpacetimeDB, shared directory) and the OPSEC
guarantees on what leaves your instance.

## Operator flexibility — run Nebula your way

Not every operator wants the full 17-domain × 84-engine sweep over
every repo in their workspace every cycle. Nebula is designed to be
**steerable at every level** so you can point it at exactly the
questions you care about.

### What ships today

- **Narrow by domain** — `./nebula --domains sec,qual` runs only the
  security and quality domains. Everything else is skipped. Useful
  when you're pillar-only or contributor-only and don't need the
  marketing / narrative scanners eating cycles.
- **Narrow by budget / time** — `--budget 0.50` stops the loop at
  $0.50 of LLM spend; `--hours 2` runs for 2 hours; `--cycles N`
  runs exactly N cycles. All composable.
- **Narrow by transport** — `NEBULA_TRANSPORT=local` runs without
  peer sync; `NEBULA_TRANSPORT=shared NEBULA_SHARED_DIR=...`
  publishes/pulls via a shared filesystem.
- **Narrow by LLM** — `XAI_API_KEY=""` or unset drops you into
  the free local-compute-only mode (~70% of engines still produce
  findings).

### What's on the near-term roadmap

- **Narrow by repo** (shipped v0.6.10, task #79) — `./nebula --repos go-zenon,syrius`
  filters every workspace-scanning engine down to just the listed
  repos. The rest of the workspace is untouched. Useful when you're
  focused on one PR, one spec, one integration — you don't want the
  full firehose.
- **Ad-hoc operator focus** (shipped v0.6.10, task #80) —
  `./nebula --focus "PTLC implementation bugs"` injects your directive
  into the Director's prompt and the breakthrough engine's alignment
  scoring. Findings relevant to your focus get a boost in the daily
  battle plan on top of the standard Zenon mission alignment. Think
  of it as telling Nebula *"while you're doing your normal work,
  also pay attention to this"*.
- **Long-lived operator intent** (planned — task #71) —
  `~/.config/nebula/intent.md` is a versioned prose narrative of
  your current research focus. `nebula status` shows it. Survives
  across sessions. Peers (with your permission) can read it for
  context about what you're thinking.
- **Mission pillar overrides** (planned — Phase G2, v0.6.15) —
  `~/.config/nebula/mission.toml` lets you append your own pillars
  to the shipped 5 or (with explicit risk acknowledgment) replace
  them entirely. The collective war room still converges on
  Zenon-mission-aligned output, but your individual instance
  explores the questions *you* care about.
- **User domains, hooks, engine overrides** (planned — Phase G1,
  v0.6.14) — drop a domain plugin in `~/.config/nebula/domains/`,
  disable a shipped engine via `~/.config/nebula/overrides.toml`,
  subscribe to `post_finding` / `pre_cycle` events via a hook
  script. All without forking.

The philosophy: **diverge at the individual level, converge at the
collective level**. Every operator runs whatever subset of Nebula
makes sense for their role and their research, but every operator's
findings feed the same content-hash-dedup'd, peer-corroborated,
mission-aligned commons. A pillar operator, a core dev, a security
researcher, and a delegator can all run Nebula on the same day
with radically different configurations — and each of their
findings still strengthens the hypothesis evolution for everyone
else.

## Publishing model — public wheel, controlled repo

Nebula operates with a deliberate asymmetry between its two
distribution surfaces:

- **PyPI package** (`pypi.org/project/zenon-nebula`) is **public**.
  Anyone can `pip install zenon-nebula` and get the full source
  of every shipped version. The README you're reading is the same
  README embedded as the PyPI project description. This is the
  supported installation path for every operator, regardless of
  GitHub access.
- **GitHub repo** is currently in **controlled-visibility mode**
  (`private`). Issues, PRs, CI logs, branch state, and the draft
  state of in-flight work stay gated to org members until the
  mechanical gates from v0.6.7 → v0.6.13 prove themselves. The
  README at the repo root flows through the same truth-auditor +
  regen pipeline as the PyPI copy.

Why the split is intentional and not a leak: the code has been
open via PyPI since v0.5.5 (10 versions live on PyPI as of
v0.6.8). The private-repo setting gates the **development
process** (issues + PRs + CI + branches), not the **shipped
product** (the wheel). The split is interim — the natural
destination is a fully public repo once the test pyramid and the
mechanical release gates stabilize across the v0.6.9 → v0.6.13
ship window. See `docs/runbooks/publishing-model.md` for the full
reasoning, the three options considered, the wheel-contents
verification procedure, and the concrete trigger criteria for
flipping to the fully public state.

**TL;DR for new operators**: `pip install zenon-nebula` and you
have the same code everyone else is running. Auditing what's in
the wheel is a one-command affair documented in the runbook.

## Portability

Nebula works the same way whether you checked out the whole Zenon workspace or just cloned Nebula alone:

- `ZENON_WORKSPACE_ROOT` env var controls where Nebula looks for sibling repos.
- Engines that scan sibling repos degrade gracefully to "no data" when the repo isn't present.
- No hardcoded `/Users/...` or `/home/...` paths; everything resolves via `core/workspace.py` helpers.
- `NEBULA_SKIP_WAR_ROOM=1` lets headless runs skip the LLM step for CI scenarios.
- `requirements.txt` ships every optional dep bundled (image/PDF/OCR/docx/xlsx extractors, semantic code graph, numpy) so `pip install` gives you full power out of the box — no separate "full" install. Ultra-minimal environments can grep out unneeded lines; Nebula degrades gracefully when any optional dep is missing.

## Cost

Most of Nebula runs free. LLM calls are reserved for strategic reasoning.

| Component | Cost |
|-----------|------|
| Local engines (git scans, filesystem, API queries, RPC) | Free |
| Collision detection, feedback bus, evidence storage | Free |
| Knowledge graph, hypothesis evolution, breakthrough hunt | Free |
| Director synthesis, War Room battle plan | 1-2 LLM calls/cycle |
| Security adversarial review | 1 LLM call per contract |

Nebula uses **xAI Grok exclusively** — chosen for cost. Grok 4.20 is
the cheapest frontier model that can handle the strategic synthesis
work, and `grok-4-1-fast-non-reasoning` is even cheaper for the
classification and routing tasks. The model router picks the right
tier per task. The prompt cache and the v0.2.18 circuit breaker keep
the bill capped even under bursty load.

Real cost data from a 400-cycle harden run:

| Workload | LLM calls | Cost |
|---|---|---|
| 1 cycle (~33s) | 0–2 | **~$0.0017** |
| 100 cycles (~55 min) | ~38 | **~$0.17** |
| 1000 cycles (~9 hours) | ~375 | **~$1.65** |
| 24 hours continuous | ~3600 cycles | **~$5.90** |
| 30 days continuous | ~108k cycles | **~$180** |

Each cycle runs ~85 engine invocations (17 domains × ~5 engines).
**~99.6% are free local work** — git scans, file reads, AST parsing,
SQLite queries, RPC calls. Only ~0.4% reach the LLM:

- Director priority synthesis (1–2 per cycle, escalates to reasoning)
- War Room daily battle plan (1 per ~120 cycles, since it's daily)
- Adversarial security reviews (cached after first scan per contract)
- Hypothesis hardener challenges (a handful per cycle, classifier-shaped)

The `--budget N` CLI flag stops the autonomous loop when LLM spend hits
$N. Typical operators set `--budget 0.50` or `--budget 1.00` per run.
Audit your real spend at any time with `./nebula costs`.

If you set `XAI_API_KEY=""` Nebula still runs — about 70% of engines
produce findings on local compute alone, at **$0/month**.

Set `XAI_API_KEY` in `.env` (or via `./nebula config api-key`).
Get a key at <https://console.x.ai>.

## Stats

Live counts are in the auto-regenerated block at the top of this README.
Run `python3 scripts/regen_docs.py` after any structural change; a pre-commit
hook also invokes it in `--check` mode.

## Adding a Domain

Domains are auto-discovered at runtime. Drop a plugin in `domains/`, restart. Every engine should declare its own `SCHEMA_SQL` constant so the registry picks the table up automatically.

```python
from core.domain_registry import DomainPlugin, EngineDefinition

class MyDomain(DomainPlugin):
    @property
    def name(self) -> str:
        return "my_domain"

    def get_engines(self) -> list:
        return [EngineDefinition(
            name="my_engine",
            module_path="domains.my_domain.engines.my_engine",
            priority=5,
            status="built",
        )]
```

See `domains/` for seventeen complete examples.

## License

MIT - see [LICENSE](LICENSE).

---

Built with Python 3.10+, SQLite, and xAI Grok.

[Zenon Network](https://zenon.network) / [ZenonOrg](https://github.com/ZenonOrg) / [Developer Commons](https://github.com/TminusZ/zenon-developer-commons)
