{
  "markdown": "# 🔱 Omni — The All-Seeing Eye\n\n![Omni Header](assets/omni_header.png)\n\n**The Federation Governance Tricorder** — A modular, extensible observation engine that scans, maps, and guards codebases at galactic scale.\n\n<!-- mcp-name: io.github.Pantheon-LadderWorks/omni-scanner -->\n\n> *\"Never trust documentation, trust reality.\"* — ACE\n\nOmni is a Python-powered **passive observation platform** that discovers the truth about your code. It doesn't modify files or break builds — it sees, maps, and reports. Think of it as a **tricorder for your codebase**: point it at any directory and it reveals structure, dependencies, health, drift, and compliance in seconds.\n\n---\n\n## ✨ At a Glance\n\n| Dimension                | Reading                                                               |\n| :----------------------- | :-------------------------------------------------------------------- |\n| 🔍 **Scanner Categories** | 12 (from static analysis to git archaeology)                          |\n| 📦 **Total Scanners**     | 55 instruments across all categories                                  |\n| ⚡ **CLI Commands**       | 14 verbs for every observation need                                   |\n| 🧠 **MCP Server**         | Exposes all scanners as AI-callable tools                             |\n| 🏛️ **Pillars**            | 4 orchestration subsystems (Cartography, Intel, Gatekeeper, Registry) |\n| 🔌 **Federation Mode**    | Optional deep integration with a governance backend                   |\n| 🦴 **Standalone Mode**    | Works anywhere — no backend required                                  |\n\n---\n\n## 🚀 Quick Start\n\n> **New Here?** Check out the **[Beginner's Guide: Zero to Hero](docs/BEGINNERS_GUIDE.md)** for a step-by-step setup tutorial.\n\n### Install\n```bash\n# Recommended: Install from PyPI\npip install omni-governance\n\n# Or install from source:\n# pip install -e .\n```\n\n### Your First Scan\n```bash\n# Scan the current directory with all static scanners\nomni scan .\n\n# Run a specific scanner\nomni scan . --scanner surfaces\n\n# See what Omni knows about itself\nomni introspect\n```\n\n### Explore the Ecosystem\n```bash\n# Map your entire project constellation\nomni map\n\n# Check governance compliance\nomni gate .\n\n# Generate a full report\nomni report . --format markdown\n```\n\n---\n\n## 🏗️ Architecture — The Trinity\n\nOmni follows the **Trinity Architecture** — three layers with strict separation of concerns:\n\n```\n                    ┌──────────────────────────┐\n                    │        CLI (cli.py)       │  ← User interface\n                    │     14 verbs, 1 brain     │\n                    └────────────┬─────────────┘\n                                 │\n              ┌──────────────────┼──────────────────┐\n              │                  │                  │\n    ┌─────────▼──────┐  ┌───────▼────────┐  ┌──────▼───────┐\n    │  🧠 CORE       │  │  🏛️ PILLARS    │  │  📚 LIB      │\n    │  Identity      │  │  Cartography   │  │  I/O, Render │\n    │  Registry      │  │  Intel         │  │  Reporting   │\n    │  Gate          │  │  Gatekeeper    │  │  Tree, TAP   │\n    │  Paths         │  │  Registry      │  │  Requirements│\n    └─────────┬──────┘  └───────┬────────┘  └──────────────┘\n              │                 │\n    ┌─────────▼─────────────────▼──────────────────────────┐\n    │              🔍 SCANNERS (55 Instruments)            │\n    │   12 categories • Dynamic plugin loading             │\n    │   Each scanner: scan(target: Path) → dict            │\n    └──────────────────────────────────────────────────────┘\n              │\n    ┌─────────▼──────┐\n    │  🔧 BUILDERS   │  ← The only layer that writes\n    │  Registry Gen  │\n    │  Report Gen    │\n    └────────────────┘\n```\n\n> **Read-Only Guarantee**: Scanners never modify source files. Only Builders write, and only to designated artifact directories.\n\nFor the full architectural deep-dive, see **[ARCHITECTURE.md](ARCHITECTURE.md)**.\n\n---\n\n## 🔍 Scanner Categories\n\nOmni's 55 scanners are organized into 12 categories. Each scanner implements the universal `scan(target: Path) → dict` contract and is auto-discovered via `SCANNER_MANIFEST.yaml` files.\n\n### Open Source Scanners (Included in Build)\n\n| Category                                          | Scanners | Purpose                                                                                     |\n| :------------------------------------------------ | :------: | :------------------------------------------------------------------------------------------ |\n| **📁 [static](omni/scanners/static/)**             |    9     | Filesystem analysis — contracts, deps, docs, events, hooks, imports, surfaces, tools, UUIDs |\n| **🏗️ [architecture](omni/scanners/architecture/)** |    4     | Structural enforcement — import boundaries, coupling detection, drift analysis, compliance  |\n| **🔎 [discovery](omni/scanners/discovery/)**       |    8     | Component cataloging — projects, CLI commands, cores, MCP servers, archives, census         |\n| **🌐 [polyglot](omni/scanners/polyglot/)**         |    4     | Language ecosystems — Python packages, Node.js, Rust crates, generic (Go/Java/.NET/Docker)  |\n| **📚 [library](omni/scanners/library/)**           |    6     | Document intelligence — cohesion analysis, content depth, knowledge graphs, rituals         |\n| **🔀 [git](omni/scanners/git/)**                   |    5     | Repository intelligence — status, velocity, commit history, PR telemetry, utilities         |\n| **🔍 [search](omni/scanners/search/)**             |    3     | Pattern matching — file search, text search, regex pattern search with context              |\n| **🗄️ [db](omni/scanners/db/)**                     |    1     | Generic configuration-driven database scanning                                              |\n\n### Federation-Exclusive Scanners (Not in Open Source Build)\n\n> These scanners require the **Federation Heart** backend and are part of the proprietary governance layer. They appear in `omni introspect` when the Heart is available but are not distributed with the open-source release.\n\n| Category       | Scanners | Purpose                                                                              |\n| :------------- | :------: | :----------------------------------------------------------------------------------- |\n| **🛡️ health**   |    6     | Runtime health — Federation, CMP, pillar, station, tunnel, and system status         |\n| **🗃️ database** |    5     | CMP entity scanning — agents, artifacts, conversations, entities, projects           |\n| **⚓ fleet**    |    1     | Fleet registry generation and validation                                             |\n| **🔥 phoenix**  |    3     | Git history resurrection — archive scanning, orphan detection, temporal gap analysis |\n\nEach category has its own README with detailed scanner documentation. See the [Scanner Architecture Guide](omni/scanners/README.md) for the complete reference.\n\n---\n\n## 🏛️ The Four Pillars\n\nPillars are orchestration subsystems that coordinate multiple scanners and produce higher-level intelligence:\n\n| Pillar            | Role                  | Key Capability                                            |\n| :---------------- | :-------------------- | :-------------------------------------------------------- |\n| **🗺️ Cartography** | Ecosystem Mapper      | Maps project constellations and dependency webs           |\n| **🕵️ Intel**       | Intelligence Gatherer | Aggregates multi-scanner data into actionable insights    |\n| **⚖️ Gatekeeper**  | Policy Enforcer       | Validates compliance, catches drift, flags violations     |\n| **📋 Registry**    | Registry Operator     | Parses, validates, and manages `PROJECT_REGISTRY_V1.yaml` |\n\nSee [Pillars Architecture](omni/pillars/README.md) for the deep dive.\n\n---\n\n## ⚡ CLI Command Reference\n\n| Command             | Purpose                                                   |\n| :------------------ | :-------------------------------------------------------- |\n| `omni scan`         | Run scanners against a target directory                   |\n| `omni inspect`      | Deep inspection of a single project                       |\n| `omni gate`         | Policy enforcement and compliance checks                  |\n| `omni map`          | Ecosystem cartography and dependency mapping              |\n| `omni tree`         | Directory tree visualization                              |\n| `omni audit`        | Provenance, dependency, and lock auditing                 |\n| `omni registry`     | Registry operations and event scanning                    |\n| `omni library`      | Grand Librarian document intelligence                     |\n| `omni canon`        | Canon validation and discovery                            |\n| `omni report`       | Generate structured reports                               |\n| `omni init`         | Scaffold new Federation-compliant projects                |\n| `omni introspect`   | Self-inspection — shows all scanners, drift, capabilities |\n| `omni interpret`    | Interpret and explain scan results                        |\n| `omni inspect-tree` | Combined tree + inspection                                |\n\n---\n\n## 🔌 Federation Mode vs. Standalone\n\nOmni operates in two modes, transparently:\n\n### Standalone Mode (Default)\nNo external dependencies. Configuration from `omni.yml` and environment variables. All open-source scanners work perfectly. Ideal for individual developers and open-source projects.\n\n### Federation Mode (Optional)\nWhen `federation_heart` is installed, Omni gains:\n- **CartographyPillar** — Canonical path resolution across the entire Federation\n- **Constitution** — Governance rule enforcement from a central authority\n- **CMP Integration** — Project identity resolution against the Canonical Master Project database\n- **Runtime Health** — Live status of Federation services, stations, and tunnels\n\nThe integration is handled by a **single shim** (`omni/config/settings.py`) that bridges to the Heart when available and falls back gracefully when it's not.\n\n---\n\n## 🧠 MCP Server\n\nOmni includes a Model Context Protocol (MCP) server that exposes all 55 scanners as AI-callable tools. Any MCP-compatible AI assistant can invoke Omni's scanners programmatically.\n\n### Quick Start (npx)\nThe absolute easiest way to use the MCP Server is via npx (requires Node.js):\n```bash\nnpx -y @modelcontextprotocol/inspector mcp-server-omni-governance\n```\n\n### Run from Source\n```bash\n# The MCP server auto-discovers all registered scanners\npython -m mcp_server.omni_mcp_server\n```\n\nSee [MCP Server Documentation](mcp_server/README.md) for setup and configuration.\n\n---\n\n## 📁 Project Structure\n\n```\nomni/\n├── README.md              ← You are here\n├── ARCHITECTURE.md        ← Full architectural deep-dive\n├── CONTRIBUTING.md        ← How to add scanners and contribute\n├── CHANGELOG.md           ← Version history\n├── ROADMAP.md             ← Future plans\n├── pyproject.toml         ← Package definition\n├── omni/\n│   ├── cli.py             ← CLI entry point (14 commands)\n│   ├── core/              ← Brain — identity, registry, gate, paths\n│   ├── config/            ← Configuration & Federation Heart bridge\n│   ├── scanners/          ← 55 scanners across 12 categories\n│   ├── pillars/           ← 4 orchestration subsystems\n│   ├── lib/               ← Shared utilities (I/O, rendering, reporting)\n│   ├── builders/          ← Registry and report generators\n│   ├── scaffold/          ← Project templates\n│   └── templates/         ← Jinja2 report templates\n├── mcp_server/            ← MCP server exposing scanners as AI tools\n├── scripts/               ← Operational scripts\n├── tests/                 ← Test suite (pytest)\n├── docs/                  ← Historical docs and plans\n└── contracts/             ← Crown Contracts (C-TOOLS-OMNI-*)\n```\n\n---\n\n## 🔧 Configuration\n\nOmni follows a strict configuration hierarchy (highest priority wins):\n\n1. **CLI flags** (e.g., `--scanner surfaces`)\n2. **Environment variables** (e.g., `OMNI_ROOT`)\n3. **`omni.yml`** (project-level configuration)\n4. **Built-in defaults** (sensible fallbacks)\n\nKey environment variables:\n| Variable              | Purpose                           |\n| :-------------------- | :-------------------------------- |\n| `OMNI_ROOT`           | Override root path for scanning   |\n| `OMNI_REPO_INVENTORY` | Path to repository inventory JSON |\n| `OMNI_WORKSPACES`     | Workspace root paths              |\n| `OMNI_DB_CONFIG_PATH` | Database configuration directory  |\n\nSee [Configuration Guide](omni/config/README.md) for full details.\n\n---\n\n## 🧪 Testing\n\n```bash\n# Run all tests\npytest tests/ -v\n\n# With coverage\npytest tests/ --cov=omni --cov-report=html\n```\n\nSee [Test Suite Documentation](tests/README.md) for fixtures, standards, and CI setup.\n\n---\n\n## 🤝 Contributing\n\nWe welcome new scanners, pillars, and improvements. The scanner plugin system makes it straightforward to add new observation capabilities:\n\n1. Create a scanner file with a `scan(target: Path) → dict` function\n2. Register it in the category's `SCANNER_MANIFEST.yaml`\n3. Add tests and documentation\n\nSee **[CONTRIBUTING.md](CONTRIBUTING.md)** for the full guide.\n\n---\n\n## 📜 Requirements\n\n- **Python**: 3.8+\n- **Dependencies**: `pyyaml`, `pydantic` (core); `federation_heart` (optional, for Federation mode)\n- **OS**: Windows, macOS, Linux\n\n---\n\n## 📋 License\n\nOpen source. See [LICENSE](LICENSE) for details.\n\n---\n\n<p align=\"center\">\n  <em>The All-Seeing Eye observes. The Code writes the Code.</em><br/>\n  <strong>Omni v0.7.0</strong> — Pantheon LadderWorks\n</p>\n",
  "bytes": 13593,
  "sha": "8ba2f1419af59a5d8e8ad3a5fbef8764c9a652487b38901d873deb33c8093515",
  "repo_slug": "pantheon-ladderworks/omni-scanner",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_pantheon_ladderworks_omni_scan_33c09f7d/readme"
}