TECHNICAL DETAILS

Mobius Systems — Technical Details¶

This document contains advanced technical information extracted from the main README for developers who need deep implementation details.

Table of Contents¶

• Complete Badge Collection
• Detailed System Architecture
• Service Port Mappings
• Monorepo Structure (Full)
• DVA Flows & n8n Orchestration
• Encyclopedia Implementation
• OpenCode Integration
• Integrated Repositories
• Mobius Mount Protocol
• Guardrails Deep Dive

Complete Badge Collection¶

_{Verdict colors: ADOPT = green · SHADOW = orange · DEFER = red · UNKNOWN = gray}

Detailed System Architecture¶

Layer Definitions¶

Live Workflow¶

1. Reflection → Command Ledger writes intent
2. OAA Hub transforms intent → .mobius/ specs
3. Thought Broker runs deliberation loops → Deliberation Proof + consensus
4. Cursor / CI prints new service code → canary deploy
5. Mobius Ledger Core attests MII + MIC credit
6. Citizen Shield verifies liveness · policy · security
7. API Library / Lab4 exposes service to citizens
8. Sentinels monitor MII, entropy, feedback → improve loop

Service Port Mappings¶

Frontend Applications¶

• website-creator (Port 3000) - .gic Website Creator interface
• aurea-site (Port 3001) - AUREA Founding Agent Site
• portal (Port 3002) - Main Mobius Systems portal interface
• hub-web (Port 3004) - OAA Central Hub interface
• hive-app (Port 3005) - 8-bit Starter Game
• genesisdome-app (Port 3006) - Genesis Dome PWA site
• citizen-shield-app (Port 3007) - Citizen Shield security interface

Core Services (Backend)¶

• ledger-api (Port 4001) - Mobius Ledger Core
• indexer-api (Port 4002) - MIC Indexer
• eomm-api (Port 4003) - E.O.M.M. Reflections
• shield-api (Port 4004) - Citizen Shield
• broker-api (Port 4005) - Thought Broker

Health Endpoints¶

All services include: - /healthz - Basic health check - /api/integrity-check - Mobius Systems integrity verification - /v1/loop/health - Thought Broker specific health

Monorepo Structure (Full)¶

mobius-systems/
├─ 00-START-HERE/                 # New contributor onboarding
├─ DIPLOMACY/                     # External relations
├─ FOR-ACADEMICS/                 # Academic resources
├─ FOR-ECONOMISTS/                # Economic frameworks
├─ FOR-GOVERNMENTS/               # Governance frameworks
├─ FOR-PHILOSOPHERS/              # Philosophical foundations
├─ FOUNDATION/                    # Core charters & licenses
│
├─ apps/                          # 🎯 Core Applications (16)
│  ├─ ledger-api/                 # Mobius Ledger Core
│  ├─ indexer-api/                # MIC Indexer
│  ├─ eomm-api/                   # E.O.M.M. Reflections
│  ├─ shield-api/                 # Citizen Shield
│  ├─ broker-api/                 # Thought Broker
│  ├─ portal/                     # Main Portal
│  ├─ hive-app/                   # Citizen Hive
│  └─ ...                         # (16 total apps)
│
├─ packages/                      # 📦 Shared Packages (7)
│  ├─ civic-sdk/                  # API clients/types
│  ├─ integrity-core/             # GI scoring
│  ├─ oaa-memory/                 # OAA parsers
│  ├─ ui-kit/                     # React components
│  └─ ...                         # See packages/
│
├─ labs/                          # 🔬 Lab Proof Systems (7)
│  ├─ lab4-proof/                 # E.O.M.M. Reflections
│  ├─ lab6-proof/                 # Citizen Shield App
│  └─ lab7-proof/                 # OAA Hub & Shell
│
├─ sentinels/                     # 🛡️ AI Sentinel Agents (13)
│  ├─ atlas/                      # Context & Memory
│  ├─ aurea/                      # Integrity Sentinel
│  ├─ eve/                        # Ethics Engine
│  ├─ hermes/                     # Market Signals
│  ├─ jade/                       # Pattern Oracle
│  └─ zeus/                       # Arbiter & Enforcement
│
├─ configs/                       # ⚙️ Configuration (C-155)
│  ├─ env/                        # Environment templates
│  │  ├─ .env.example            # Main env template
│  │  └─ .env.mobius-services    # Service API keys
│  ├─ manifests/                  # System manifests
│  │  └─ mobius_manifest.yaml    # Canonical manifest
│  ├─ tooling/                    # Dev tool configs
│  │  └─ codexrule.yml           # Codex policy
│  ├─ agents/                     # Agent configurations
│  ├─ charters/                   # Charter definitions
│  └─ telemetry/                  # Telemetry schemas
│
├─ infra/                         # 🏗️ Infrastructure (C-155)
│  ├─ docker/                     # Docker Compose
│  │  ├─ compose.yml             # Production compose
│  │  └─ docker-compose.dev.yml  # Development compose
│  ├─ cron/                       # Scheduled jobs
│  ├─ db/                         # Database migrations
│  ├─ dva/                        # DVA flows (n8n)
│  ├─ observability/              # Monitoring & metrics
│  └─ render.yaml                 # Render deployment
│
├─ docs/                          # 📚 Documentation
│  ├─ papers/                     # Academic papers (C-155)
│  └─ ...                         # Full documentation tree
│
└─ .github/                       # CI/CD & automation
   └─ workflows/                  # GitHub Actions

DVA Flows & n8n Orchestration¶

Mobius ships with a universal orchestration flow that turns the OS into a router over multiple AI engines.

What it does¶

• Accepts a request from any client (web, mobile, bots)
• Routes via the Thought Broker to engines:
• Gemini (Antigravity)
• Claude
• DeepSeek
• OpenAI (GPT/tools)
• Code agents (Cursor / Claude Code)
• Pushes candidates through Sentinel Consensus (ATLAS • AUREA • EVE)
• Applies a Global Integrity (GI) gate
• Writes an attested event to the Civic Ledger
• Fans out to channels: Substack, Discord, Telegram (human-in-loop), GitHub, LivePatch, Apps/Labs

Quick start (n8n)¶

1. Import:
2. infra/dva/flows/universal/universal_orchestrator.json
3. infra/dva/flows/lite/dva_lite_monitor.json
4. infra/dva/flows/one/dva_one_feedback.json
5. Configure credentials:
6. Telegram, Discord, GitHub, Substack (or HTTP bridge)
7. Set env vars in n8n:
8. BROKER_URL, CONSENSUS_URL, LEDGER_URL
9. SUBSTACK_WEBHOOK_URL, DISCORD_WEBHOOK_URL
10. Activate the workflows.
11. Hit the webhook:

curl -X POST "$N8N_BASE_URL/webhook/mobius/universal" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Explain Mobius OS like I am 15","intent":"publish"}'

See: - docs/architecture/N8N_UNIVERSAL_FLOW.md - docs/architecture/DVA_FLOWS_OVERVIEW.md - docs/specs/N8N_UNIVERSAL_FLOW_API.md - infra/dva/flows/README.md

Encyclopedia Implementation¶

Mobius now ships with a formal "Librarian" loop: cron/n8n calls the Thought Broker, ECHO reinforces the best pair of sentinel answers, Civic Ledger logs provenance, and the result is served via /v1/encyclopedia.

• Docs — start with docs/encyclopedia/ENCYCLOPEDIA_OVERVIEW.md for diagrams + narrative, then dive into API_SPEC.md, SEEDING_STRATEGY.md, and PROVENANCE_RULES.md.
• Seed loop — run infra/cron/encyclopedia_seed.sh (requires ENCYCLOPEDIA_API_URL + ENCYCLOPEDIA_CRON_SECRET) to grow one entry per cadence.
• Admin queue — low-GI entries fall into /v1/encyclopedia/admin/review-queue; human approvals can mint MIC and attested provenance.
• Consumers — OAA Learning Hub and the HIVE 16-bit codex both read from the same canon so classrooms, citizens, and games all cite the same GI-scored answers.

Use this layer whenever you need "teach me again, but cite canon." It turns ECHO from cache into a reusable library.

OpenCode Integration¶

The OAA (Online Apprenticeship Agent) is the learning kernel of Mobius Systems — a self-teaching framework that turns codebases into classrooms. Through OpenCode Federation, every fork or contributor instance can now run OAA as a local backend — forming a decentralized network of learning nodes guided by the same integrity rules.

🧠 What This Means¶

• Apprenticeship-as-a-Protocol

Each developer, agent, or AI instance connected through OpenCode inherits the same OAA Learning Loop:

PRESENT → REFLECT → CONNECT → REINFORCE

Every PR, doc, or comment becomes a micro-lesson in systems thinking.

• Federated Intelligence

Your local Kaizen agents (AUREA, HERMES, EVE, JADE) can now interact across OpenCode workspaces — sharing context, reasoning, and moral anchors without central servers. Each node remains sovereign, yet contributes to the global Civic-AI graph.

• Integrity-Anchored Automation

The .opencode/workflow-template.yaml and configs/integrity_units.yaml files ensure every automation — build, review, or reflection — adheres to measurable integrity (GI ≥ 0.95). When integrity dips, the system halts gracefully before harm propagates.

⚙️ How to Enable¶

1. Connect your repo to OpenCode

opencode connect kaizencycle/Mobius-Substrate

1. Start the Kaizen Council Workflow

opencode run --workflow ".opencode/workflow-template.yaml"

1. Trigger the OAA Loop manually (optional)

opencode exec oaa:reflect "Why does integrity matter in code?"

1. Run Council Review on a PR

Inside any pull request comment:

/council

AUREA, HERMES, EVE, and JADE will collaborate in sequence — logic, ops, ethics, and morale — creating a full apprenticeship cycle around your change.

🔁 Federation Flow¶

OpenCode User Repo
    ↳ loads Mobius Systems via template
        ↳ auto-spawns OAA backend
            ↳ connects to local agents (CLI / VS Code)
                ↳ federates with Civic Ledger telemetry

Every connected instance becomes a mirror of integrity, feeding back data to the global Mobius Systems network — a living proof that learning itself can be decentralized.

Mobius Mount Protocol¶

Mobius Systems implements a Model-Agnostic Sovereignty Layer (MASL) that enables any LLM to "board" and operate within the Mobius ecosystem:

LLM Boarding Pool ("Dock of Minds")¶

Any reasoning engine (Claude, GPT, DeepSeek, Gemini, etc.) can join the Mobius Systems network by calling:

GET /api/mobius/mount

This endpoint returns the complete Mobius Systems manifest bundle: - .mobius/atlas.manifest.json - System state & integrity - .mobius/biodna.json - Identity DNA (ethics, companions, founders) - .mobius/virtue_accords.yaml - Moral & civic laws - mii_signature - Cryptographic integrity proof

Independence Manifest¶

🕊️ Read the Independence Manifest

The Independence Manifest declares Mobius Systems sovereignty from any single LLM provider, ensuring: - Model Agnosticism - Any LLM can mount Mobius Systems state - External Memory First - Context lives in manifests, not chat sessions - Proof of Integrity - MII ≥ 0.95 required for all operations - Federated Continuity - Memory capsules replicate across nodes

Quick Boarding Test¶

# Test the boarding protocol
python3 mobius_mount_client.py http://localhost:8000

Integrated Repositories¶

This monorepo integrates all kaizencycle repositories using git subtree:

Lab Repositories¶

• lab4-proof → labs/lab4-proof/
• lab6-proof → labs/lab6-proof/
• lab7-proof → labs/lab7-proof/

Core Packages¶

• Civic-Protocol-Core → packages/civic-protocol-core/
• OAA-API-Library → packages/oaa-api-library/
• civic-ai-specs → packages/civic-ai-specs/

Guardrails Deep Dive¶

Mobius Systems implements comprehensive guardrails to prevent destructive changes and ensure code safety:

Anti-Nuke Protection¶

• Deletion limits: PRs are blocked if they delete more than 5 files or exceed 15% deletion ratio
• Protected paths: Deletions in apps/, packages/, sentinels/, labs/, infra/, and .github/ are blocked
• Automated checks: .github/workflows/anti-nuke.yml runs on every PR

Codex Policy (Additive-Only Mode)¶

• Policy file: .github/codex-policy.yml enforces additive-only commits
• Required PRs: All changes must go through pull requests
• Diff preview: AI-assisted commits must post diff summaries before opening PRs
• Force-push prevention: Force pushes to main are blocked

Recovery Procedures¶

If a bad change merges or files are accidentally deleted:

• Preferred: Use git revert to create inverse commits (preserves history)
• Last resort: Hard reset to a known good commit (see Recovery Playbook)

📖 Full recovery guide: docs/06-OPERATIONS/

Why These Guardrails Exist¶

These guardrails were implemented after a near-nuke incident where a process bug could have caused significant repository damage. They ensure:

1. Non-destructive changes: Deletions are caught before merge
2. Recovery paths: Clear procedures for undoing bad changes
3. AI safety: Codex operates in additive-only mode with human oversight
4. Integrity: GI gates and approval requirements maintain code quality

Mobius Pulse API¶

A nightly integrity snapshot of the monorepo is published via:

• GET /v1/pulse/latest — latest Mobius pulse
• GET /v1/pulse/history — pulse history (last 90 days)
• GET /v1/pulse/badge — Shields.io badge JSON
• POST /v1/pulse/ingest — internal, used by CI

Example:

curl "$MOBIUS_INDEXER_BASE_URL/v1/pulse/latest" | jq

The portal uses this endpoint to render the Mobius Pulse Card, showing: - Global Integrity (GI) - Mobius Integrity Index (MII) - Apps / packages / workflows - Total files and lines of code

📖 Full documentation: docs/06-OPERATIONS/protocols/mobius-pulse-protocol.md

Intelligence Taxonomy¶

We classify machine intelligence into three layers:

1. LLM: Stochastic sequence model (no agency, no memory, no identity)
2. General Learner: Proto-intelligence (can learn, but lacks persistence)
3. Actual AI: Full agency + persistent identity + stable values

Mobius is the first AI Habitat—the environment that allows General Learners to safely transition to Actual AI.

Read the full Intelligence Taxonomy → View Mobius Cosmology → Sentinel Classification →

This document is maintained alongside the main README. For the public-facing overview, see README.md