[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![npm version](https://img.shields.io/npm/v/@vltrn/vingularity-protocol.svg)](https://www.npmjs.com/package/@vltrn/vingularity-protocol)
[![Node.js](https://img.shields.io/badge/Node.js-18.17%2B-green.svg)](https://nodejs.org)
[![MCP](https://img.shields.io/badge/MCP-Compatible-blueviolet.svg)](https://modelcontextprotocol.io)
[![Carbon6 OiS](https://img.shields.io/badge/Carbon6-OiS-0066FF.svg)](https://carbon6.agency)

# Vingularity Protocol

**Powered by VLTRN** | *Map everything. Connect everything. Understand everything.*

```
 ██╗   ██╗██╗███╗   ██╗ ██████╗ ██╗   ██╗██╗      █████╗ ██████╗ ██╗████████╗██╗   ██╗
 ██║   ██║██║████╗  ██║██╔════╝ ██║   ██║██║     ██╔══██╗██╔══██╗██║╚══██╔══╝╚██╗ ██╔╝
 ██║   ██║██║██╔██╗ ██║██║  ███╗██║   ██║██║     ███████║██████╔╝██║   ██║    ╚████╔╝
 ╚██╗ ██╔╝██║██║╚██╗██║██║   ██║██║   ██║██║     ██╔══██║██╔══██╗██║   ██║     ╚██╔╝
  ╚████╔╝ ██║██║ ╚████║╚██████╔╝╚██████╔╝███████╗██║  ██║██║  ██║██║   ██║      ██║
   ╚═══╝  ╚═╝╚═╝  ╚═══╝ ╚═════╝  ╚═════╝ ╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝   ╚═╝      ╚═╝
```

> **Best used with [Carbon\[6\] OiS](https://carbon6.agency)** — Vingularity Protocol is the intelligence layer that maps your entire ecosystem. Pair it with Carbon[6] OiS for full orchestration.

Auto-scan any codebase and generate a unified mind map showing every project, API, database, agent, port, and inter-system connection. **MCP Server + CLI** — works with Claude Code, Claude Desktop, or standalone.

*Standalone power. Ecosystem amplified.*

---

## Quick Start

```bash
# Zero-install scan
npx @vltrn/vingularity-protocol scan .

# Install globally
npm install -g @vltrn/vingularity-protocol
vingularity scan /path/to/your/projects

# Export as HTML with connection diagrams
vingularity scan . -f html -o mind-map.html
```

## What It Detects

| Category | Trigger Files | Extracted |
|----------|--------------|-----------|
| **Projects** | package.json, requirements.txt, pyproject.toml, Cargo.toml, go.mod, Gemfile, composer.json | Name, tech stack, framework, dependencies, scripts |
| **APIs** | route.ts, app.py, server.ts + regex patterns | HTTP method, path, framework, source file |
| **Databases** | prisma/schema.prisma, docker-compose DB images, .env refs | Type, port, models, connection refs |
| **AI/Agents** | .mcp.json, CLAUDE.md, AGENTS.md, LLM env vars | Type, name, config details |
| **Infrastructure** | Dockerfile, docker-compose.yml, nginx.conf, .service, render.yaml | Services, ports, images, volumes |
| **Documentation** | README.md, CLAUDE.md, ARCHITECTURE*.md | File paths, types |
| **Connections** | Cross-analysis of ports, env vars, shared deps | From/to, type, details |

## CLI Commands

```bash
vingularity scan [path]                      # Scan a directory tree
vingularity scan . -d 5 -f json -o out.json  # Custom depth, format, output file
vingularity map [-f markdown|json|html]      # Generate mind map from last scan
vingularity ports                            # Show all detected ports
vingularity connections [--project id]       # Show inter-system connections
vingularity export [format] [-o file]        # Export scan results
vingularity serve                            # Start MCP server (stdio)
```

## MCP Server

### Claude Code

Add to your `.mcp.json`:

```json
{
  "mcpServers": {
    "vingularity": {
      "command": "npx",
      "args": ["-y", "@vltrn/vingularity-protocol", "serve"]
    }
  }
}
```

### Claude Desktop

Add to your Claude Desktop config:

```json
{
  "mcpServers": {
    "vingularity": {
      "command": "npx",
      "args": ["-y", "@vltrn/vingularity-protocol", "serve"]
    }
  }
}
```

### MCP Tools

| Tool | Description |
|------|-------------|
| `scan_ecosystem` | Full directory scan (path, depth, includeHidden) |
| `scan_project` | Single project deep scan |
| `get_mind_map` | Return mind map (markdown or json) |
| `get_connections` | Return connection graph (optional project filter) |
| `get_port_map` | All detected ports/services |
| `get_tech_stack` | Technology inventory |

### MCP Resources

| URI | Description |
|-----|-------------|
| `vingularity://mind-map` | Full mind map |
| `vingularity://connections` | Connection graph |
| `vingularity://inventory` | System inventory |

## Configuration

Create `vingularity.config.yaml` in your project root or `~/.vingularity/config.yaml`:

```yaml
scan:
  maxDepth: 8
  maxFileSize: 1048576
  followSymlinks: false

ignore:
  - "*.log"
  - "*.tmp"

output:
  format: markdown
  includeTimestamp: true
  includeStats: true

analyzers:
  project: true
  api: true
  database: true
  agent: true
  infra: true
  docs: true
```

## Output Formats

- **Markdown** — ORACLE.md-style mind map with ASCII art, tables, and connection diagrams
- **JSON** — Full structured scan result for programmatic use
- **HTML** — Dark-themed page with Mermaid.js connection diagram (Carbon6 color system)

## Architecture

```
vingularity-protocol/
├── src/
│   ├── types.ts          # All types + Zod schemas
│   ├── config.ts         # Config loader (YAML regex + defaults)
│   ├── scanner/          # Directory walker + ignore patterns
│   ├── analyzers/        # 6 analyzers: project, api, database, agent, infra, docs
│   ├── graph/            # Connection builder + port resolver
│   ├── renderers/        # JSON, Markdown, HTML output
│   ├── mcp/              # MCP server (6 tools, 3 resources)
│   └── cli/              # Commander.js CLI
```

**3 runtime dependencies:** @modelcontextprotocol/sdk, commander, zod

## Carbon6 Cloud API

Vingularity Protocol connects to the **Carbon6 API** at `https://api.carbon6.agency` for cloud sync, remote monitoring, and multi-instance ecosystem intelligence.

### Register & Sync

```bash
# Register this machine with Carbon6
vingularity register --label "my-workstation"

# Scan and auto-sync to cloud
vingularity scan . --sync

# Sync last scan manually
vingularity sync

# Scan + sync in one shot
vingularity sync --scan-first /path/to/projects

# Check connectivity and instance status
vingularity status

# View sync history
vingularity history -n 20

# Remove registration
vingularity deregister
```

### Environment Override

```bash
# Use a custom API endpoint (default: https://api.carbon6.agency)
export VINGULARITY_API_URL=https://your-custom-endpoint.com
```

### MCP Cloud Tools

| Tool | Description |
|------|-------------|
| `sync_to_cloud` | Sync scan results to Carbon6 API (optional: scan first) |
| `cloud_status` | Check API registration and connectivity |
| `cloud_register` | Register instance with Carbon6 API |

### API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/vingularity/register` | Register new instance |
| `POST` | `/v1/vingularity/sync` | Sync scan results |
| `GET` | `/v1/vingularity/instances/:id` | Get instance status |
| `POST` | `/v1/vingularity/instances/:id/heartbeat` | Instance heartbeat |
| `GET` | `/v1/vingularity/instances/:id/scans` | List sync history |
| `DELETE` | `/v1/vingularity/instances/:id` | Deregister instance |

### Credentials

Stored at `~/.vingularity/credentials.json` (chmod 600). Contains instance ID and API key — never committed to git.

---

## Carbon[6] OiS Integration

Vingularity Protocol is the intelligence layer that maps your entire ecosystem. When connected to **Carbon[6] OiS**, scan results feed directly into the Orchestration and Intelligence System for real-time infrastructure awareness.

- **Ecosystem Discovery** — Vingularity scans and maps every project, service, and connection
- **OiS Orchestration** — Carbon[6] OiS uses that map to orchestrate, monitor, and coordinate
- **Continuous Awareness** — Schedule scans to keep OiS updated as your infrastructure evolves

> Vingularity sees. OiS acts.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## Requirements

- Node.js 18.17+

## License

MIT — see [LICENSE](LICENSE)

---

(c) 2026 **VLTRN Family Office**. All rights reserved.

Vingularity Protocol is a trademark of VLTRN Family Office.
Carbon6 and Carbon[6] OiS are trademarks of Carbon6 LLC.

**VLTRN Family Office** | 651 N Broad St, Suite 201, Middletown, DE 19709 | legal@carbon6.agency