quantum-spherifier 1.0.0

package/README.md

@@ -0,0 +1,738 @@
+<p align="center">
+  <img src="docs/qspherifier.jpg" alt="QUANTU-SPHERIFIER" width="640" />
+</p>
+
+
+# THE QUANTUM SPHERIFIER (:qSpherifier) v1.0
+
+**An Autonomous Scientific Research Agent for Quantum Computing**
+
+> *Build quantum computers capable of solving problems impossible for current
+> (and short/mid-term) classical computers.*
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-green.svg)](https://nodejs.org)
+[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](#)
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Key Principles](#key-principles)
+- [The Four Research Lines](#the-four-research-lines)
+- [Architecture](#architecture)
+- [The Artificial Junky Neuron (AJN)](#the-artificial-junky-neuron-ajn)
+- [Resource Anchoring — Nothing Stays Isolated](#resource-anchoring--nothing-stays-isolated)
+- [Multi-LLM Integration](#multi-llm-integration)
+- [Document Generation & Patent Clustering](#document-generation--patent-clustering)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Usage](#usage)
+  - [Autonomous Research](#autonomous-research)
+  - [Web Dashboard](#web-dashboard)
+  - [CLI Commands](#cli-commands)
+  - [Owner Guidance](#owner-guidance)
+- [Configuration](#configuration)
+- [Docker](#docker)
+- [Project Structure](#project-structure)
+- [Testing](#testing)
+- [Lineage & Credits](#lineage--credits)
+- [License](#license)
+
+---
+
+## Overview
+
+**quantum-spherifier** is an autonomous AI research
+agent that, upon launch, immediately begins producing scientific documents —
+hypotheses, designs, simulation reports, and patent drafts — across four
+research lines of quantum computing. It does **not** wait for an owner
+directive; this is the core property of the **Artificial Junky Neuron (AJN)**
+framework on which it is built.
+
+The agent was created by **dramatically re-targeting and extending**
+[`fusionary-agent`](https://github.com/Justo-Tapiador/fusionary-agent) (which
+targeted nuclear fusion energy) to the quantum-computing domain. Both inherit
+from the original **`predator-jungle-agent`** v2.0 by Justo Tapiador Garcia
+(Universidad de Alicante), which defines the AJN architecture.
+
+### What makes qSpherifier different
+
+| Feature | fusionary-agent | **quantum-spherifier** |
+|---------|-----------------|------------------------|
+| Domain | Nuclear fusion | **Quantum computing** |
+| Research lines | Implicit (fusion subdomains) | **4 explicit lines** with a `ResearchLineRouter` |
+| Cross-linking | Optional | **Mandatory** — every hypothesis must reference KG concepts |
+| Patent clustering | None | **`PatentClusterManager`** groups filing-ready solutions |
+| LLM adapters | 3 (ZAI, Anthropic, OpenAI) | **6** (+ Google Gemini, DeepSeek, Local Ollama) with **task-routed** failover |
+| Resource anchors | Fusion hardware (ITER, SPARC, NIF) | **Real 2026 quantum hardware** (IBM Condor, Google Willow, IonQ, Quantinuum, QuEra, Atom Computing, PsiQuantum, Microsoft Majorana) |
+| Feasibility rules | Fusion physics (B-field, TBR, Q) | **Quantum metrics** (qubit count, gate fidelity, code distance, T-gate count, coherence, error rate) |
+| Physics tool | Plasma physics (Lawson, <σv>) | **Quantum physics** (surface-code error rate, overhead, Shor resources, chemistry T-count) |
+| Web dashboard | 6 tabs | **8 tabs** (added Research Lines + Patent Clusters) |
+
+---
+
+## Key Principles
+
+1. **Autonomous activation (AJN addiction)** — On launch, qSpherifier
+   immediately starts researching. It does not wait for a request. This is the
+   defining "addiction" property of the Artificial Junky Neuron.
+
+2. **Four research lines, deliberately cross-linked** — QEC, New Qubits,
+   Algorithms, and Molecular Simulation. Every 5th cycle is a **cross-link
+   cycle** that bridges two lines, ensuring that hardware advances (QEC/Qubits)
+   are enlaced with application advances (Algorithms/Simulation).
+
+3. **Resource anchoring to reality** — Every proposed solution is verified
+   against the actual quantum-computing capacity of human civilisation as of
+   2026. Solutions that exceed credible roadmaps are downgraded and not marked
+   patent-eligible. Nothing is proposed that requires physics or infrastructure
+   beyond what exists or is under active construction.
+
+4. **Nothing stays isolated** — Every hypothesis must cross-link to at least
+   one node in the Quantum Knowledge Graph. The `ResourceFeasibilityChecker`
+   verifies this and flags isolated solutions with reduced confidence.
+
+5. **Coherent patent clustering** — Successful solutions (intermediate or
+   final) are grouped into clusters that combine hardware-foundation documents
+   with application-layer documents. A cluster is **filing-ready** when it
+   spans both layers.
+
+6. **Multi-LLM task routing** — Different research tasks use the most
+   appropriate frontier LLM: GLM-4.6 for hypothesis generation, Claude for
+   patent drafting, Gemini for literature review, DeepSeek for proof
+   verification — with automatic failover.
+
+---
+
+## The Four Research Lines
+
+### 1. Quantum Error Correction (QEC)
+
+**Goal:** Build fault-tolerant logical qubits by suppressing physical errors
+below threshold and reducing the physical-to-logical overhead.
+
+**Key metrics:** logical_error_rate, code_distance, physical_to_logical_overhead, threshold
+
+**Seed topics:** Surface code, qLDPC, Color code, Magic-state distillation, Bacon-Shor
+
+**State of the art (2026):** Google Willow (105 qubits) demonstrated
+exponential error suppression below the surface-code threshold at distance 7.
+Quantinuum H2 demonstrated non-Abelian topological states. The frontier is
+qLDPC codes with constant-rate encoding, which could reduce overhead from
+$O(d^2)$ to $O(1)$.
+
+### 2. New Qubit Modalities
+
+**Goal:** Develop qubit platforms with longer coherence, higher gate fidelity,
+lower cost, and better scalability.
+
+**Key metrics:** T1, T2, gate2qFidelity, qubitCount, costPerQubit
+
+**Seed topics:** Transmon, Fluxonium, Cat qubit, Trapped ion, Neutral atom, Photonic, Topological, Silicon spin, NV center
+
+**State of the art (2026):** IBM Condor (1,121 qubits) and Atom Computing
+(1,180 neutral atoms) lead in qubit count. Quantinuum H2 leads in gate
+fidelity (99.87%). Fluxonium offers 3–10× longer coherence than transmon.
+Microsoft's Majorana 1 is the first topological-qubit prototype.
+
+### 3. Quantum Algorithms
+
+**Goal:** Discover and optimize algorithms with provable or practical quantum
+advantage on near-term and fault-tolerant hardware.
+
+**Key metrics:** circuit_depth, tgate_count, speedup, qubit_requirement
+
+**Seed topics:** Shor, Grover, VQE, QAOA, QFT, HHL, QPE, QML, QSVT
+
+**State of the art (2026):** QSVT (Gilyen et al. 2019) is the unifying
+framework that subsumes Grover, QPE, HHL, and Hamiltonian simulation as
+special cases, achieving optimal query complexity. Qubitization (a QSVT
+variant) reduces FeMoco T-gate count by ~100× versus Trotterization.
+
+### 4. Molecular Simulation
+
+**Goal:** Simulate fermionic systems (catalysts, drugs, materials) beyond
+classical capability.
+
+**Key metrics:** logical_qubits, tgate_count, chemical_accuracy, molecule_size
+
+**Seed topics:** FeMoco, Transition-metal catalysis, Drug discovery, Materials, Fermionic Hamiltonian, Jordan-Wigner, Trotter, Qubitization
+
+**State of the art (2026):** FeMoco (nitrogenase active site) remains the
+canonical "killer app" target, requiring ~3,000 logical qubits and ~10¹⁰
+T-gates for chemical accuracy. NISQ-era VQE on transition-metal catalysts is
+the near-term stepping stone. Qubitization is the algorithm of choice for
+fault-tolerant chemistry.
+
+---
+
+## Architecture
+
+qSpherifier is a **14-layer ANN-Psi backbone** (AJN + Transformer) wrapped in
+a research-cycle orchestrator, backed by a multi-LLM router, a quantum
+knowledge graph, and a hierarchical document archive.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    Owner Guidance Layer                          │
+│   Web Dashboard (Express + WS)  ·  CLI (Commander)              │
+└───────────────────────┬─────────────────────────────────────────┘
+                        │
+┌───────────────────────▼─────────────────────────────────────────┐
+│                  QSpherifierAgent (orchestrator)                 │
+│  ResearchLineRouter · HypothesisGenerator · Feasibility          │
+│  PatentDraftAssistant · PatentClusterManager · DocumentArchivist │
+└───────────────────────┬─────────────────────────────────────────┘
+                        │
+┌───────────────────────▼─────────────────────────────────────────┐
+│              ANN-Psi Backbone (14 layers)                        │
+│  L1-L2 Hybrid AJN · L3 Hetero AJN K=8 · L4-L5 Transformer       │
+│  L6 Hetero AJN K=16 · L7 Hybrid AJN · L8-L9 Transformer         │
+│  L10 Hetero AJN K=32 · L11 Hybrid AJN · L12 Hetero AJN K=8      │
+│  L13 Hybrid AJN · L14 Output AJN                                 │
+└───────────────────────┬─────────────────────────────────────────┘
+                        │
+┌───────────────────────▼─────────────────────────────────────────┐
+│              LLM Router (task-routed multi-LLM)                  │
+│  ZAI/GLM-4.6 · Claude Opus 4.1 · GPT-4o · Gemini 2.0 ·          │
+│  DeepSeek-R1 · Local (Ollama)                                   │
+└───────────────────────┬─────────────────────────────────────────┘
+                        │
+┌───────────────────────▼─────────────────────────────────────────┐
+│        Quantum Knowledge Graph + Citation Graph                  │
+│  Real 2026 hardware anchors · 4 research-line clusters          │
+│  Cross-link enforcement (nothing stays isolated)                 │
+└───────────────────────┬─────────────────────────────────────────┘
+                        │
+┌───────────────────────▼─────────────────────────────────────────┐
+│           Document Archive (hierarchical, tagged)                │
+│  topics/ hypotheses/ designs/ simulations/ patents/              │
+│  LaTeX + PDF + manifest.json + references.bib                    │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+See [`docs/architecture.md`](docs/architecture.md) for the full design document.
+
+---
+
+## The Artificial Junky Neuron (AJN)
+
+The AJN is the theoretical foundation (Tapiador García, 2024). Each neuron
+cycles through six **addiction phases**:
+
+| Phase | Behaviour |
+|-------|-----------|
+| **RANDOM** | High-entropy exploration of the quantum knowledge space |
+| **REINFORCE** | Bias developing toward a high-reward stimulus |
+| **SATURATION** | Topic sufficiently explored; praxes suppressed |
+| **WITHDRAWAL** | Craving returns; activation threshold decays |
+| **FRUSTRATION** | Failure state; covariance expanding chaotically |
+| **EXTINCTION** | Addiction dissolved; reset to random exploration |
+
+**Multi-objective reward:** `quality × novelty × feasibility × patentability`
+
+- `quality` — scientific soundness of the hypothesis
+- `novelty` — curiosity bonus for under-explored KG regions
+- `feasibility` — resource-feasibility weighting (real hardware anchors)
+- `patentability` — rewards praxes whose artifact is patent-eligible
+
+**Training features:** cosine-annealed learning rate, Hebbian traces,
+stratified replay buffer (top-quartile experiences), momentum, cascade
+monitoring.
+
+This is what makes qSpherifier **autonomous**: it does not wait for requests.
+It is "addicted" to quantum research and works continuously upon launch.
+
+---
+
+## Resource Anchoring — Nothing Stays Isolated
+
+Every proposed solution is verified against `RESOURCE_ANCHORS` — a table
+encoding the **actual quantum-computing capacity of human civilisation as of
+2026**:
+
+### Superconducting platforms
+- **IBM Condor** — 1,121 qubits (2023)
+- **IBM Heron R2** — 156 qubits, tunable couplers, 99.7% 2Q fidelity
+- **Google Willow** — 105 qubits, below-threshold QEC, distance-7 surface code
+- **Rigetti Ankaa-3** — 84 qubits, 99.5% 2Q fidelity
+
+### Trapped-ion platforms
+- **IonQ Forte Enterprise** — 36 algorithmic qubits, all-to-all, 99.6% 2Q
+- **Quantinuum H2** — 56 qubits, 99.87% 2Q fidelity (best in class)
+
+### Neutral-atom platforms
+- **QuEra Aquila** — 256 rubidium atoms (AWS Braket)
+- **Atom Computing** — 1,180 strontium atoms, 40s T1 (first 1K+ qubit platform)
+
+### Photonic platforms
+- **Xanadu Borealis** — 216 squeezed modes (GBS quantum advantage 2022)
+- **PsiQuantum Omega** — targeting 1M photonic qubits (GlobalFoundries fab)
+
+### Topological
+- **Microsoft Majorana 1** — first topological-qubit prototype (2024)
+
+### Silicon spin
+- **Intel Tunnel Falls** — 12-qubit silicon spin chip (Intel 3 CMOS node)
+
+### Infrastructure
+- **Dilution refrigerators** (Bluefors, Oxford Instruments) — 10–20 mK
+- **Cryo-CMOS control** (Intel, Google, SeeQC)
+- **GPU clusters** (NVIDIA H100/H200, cuQuantum) for classical simulation
+- **Exascale supercomputers** (Frontier, Aurora, Fugaku)
+
+### Feasibility rules (examples)
+
+| Rule | Test | Effect |
+|------|------|--------|
+| Physical qubits | >100M → speculative; >10K → mid_term; >1K → near_term; >100 → current | Caps unrealizable claims |
+| Logical qubits | >10K → speculative; >1K → long_term; >10 → near_term; ≥1 → current | Maps to FTQC roadmap |
+| Gate fidelity | <99% → long_term; <99.5% → mid_term; <99.9% → near_term; ≥99.9% → current | QEC threshold gating |
+| Code distance | >30 → long_term; >15 → mid_term; ≥3 → current | Surface-code scaling |
+| T-gate count | >10¹² → speculative; >10⁹ → long_term; >10⁶ → mid_term | Circuit-depth feasibility |
+| Coherence | >1000s → speculative; >1s → near_term; >1ms → current | Qubit modality maturity |
+
+---
+
+## Multi-LLM Integration
+
+qSpherifier uses a **task-routed multi-LLM router** with automatic failover:
+
+| Task | Primary model | Why |
+|------|---------------|-----|
+| `hypothesis_generation` | **GLM-4.6** (Z.ai) | Best STEM reasoning per token; 200K context |
+| `patent_drafting` | **Claude Opus 4.1** (Anthropic) | Precise legal language; careful claim construction |
+| `literature_review` | **Gemini 2.0 Flash** (Google) | 2M-token context; cost-effective long-document analysis |
+| `proof_verification` | **DeepSeek-R1** | Chain-of-thought reasoning; cost-effective mathematical verification |
+| `default` / fallback | **GPT-4o** (OpenAI) → Local (Ollama) | High throughput; air-gapped fallback |
+
+**Failover:** If the primary adapter fails, the router tries the next in the
+priority list. Failing adapters are demoted for 30 seconds before retry.
+Per-adapter success/failure rates are tracked.
+
+**Configuration:** Set any of these environment variables (all optional; the
+router skips adapters with missing keys):
+
+```bash
+ZAI_API_KEY=          # GLM-4.6 (primary)
+ANTHROPIC_API_KEY=    # Claude Opus 4.1
+OPENAI_API_KEY=       # GPT-4o
+GOOGLE_API_KEY=       # Gemini 2.0
+DEEPSEEK_API_KEY=     # DeepSeek-R1
+OLLAMA_ENDPOINT=      # Local Ollama (air-gapped fallback)
+```
+
+If no API keys are set, qSpherifier falls back to **template-based** hypothesis
+and patent generation — it still works, just with less creative output.
+
+---
+
+## Document Generation & Patent Clustering
+
+### Hierarchical archive
+
+Every artifact is stored under `research/<category>/<line>/<id>/`:
+
+```
+research/
+├── topics/                  # Background research notes (seeded)
+│   ├── qec/seed_surface_code_2026/        main.tex + manifest.json
+│   ├── qubits/seed_neutral_atom_2026/     main.tex + manifest.json
+│   ├── algorithms/seed_qsvt_2026/         main.tex + manifest.json
+│   └── molecular_simulation/seed_femoco_2026/  main.tex + manifest.json
+├── hypotheses/              # Formalised hypothesis records
+├── designs/                 # Quantum-processor / algorithm designs
+├── simulations/             # Numerical simulation reports
+├── patents/                 # USPTO-style patent application drafts
+├── cross_refs/              # Cross-reference indices
+├── indices/                 # patent_queue.md, master INDEX.md
+└── INDEX.md                 # Auto-generated master index
+```
+
+Each document directory contains:
+- `manifest.json` — machine-readable metadata (tags, cross-links, patent flags)
+- `main.tex` — LaTeX source (when applicable)
+- `main.md` — Markdown source (for indices)
+- `references.bib` — BibTeX bibliography (when applicable)
+- `figures/` — embedded figures
+
+### Patent clustering
+
+The `PatentClusterManager` groups patent-eligible documents into **coherent
+clusters** using union-find on shared KG concepts and cross-links. A cluster
+is **filing-ready** when it contains:
+- At least one **hardware-foundation** document (QEC or Qubits line)
+- At least one **application-layer** document (Algorithms or Simulation line)
+- At least 2 shared KG concepts
+
+This ensures that patent filings represent **complete solutions** — not
+isolated hardware or algorithmic tricks, but integrated paths from physical
+qubits to useful computation.
+
+---
+
+## Installation
+
+### Prerequisites
+
+- **Node.js** ≥ 18.0.0
+- **pdflatex** (optional, for PDF compilation — `texlive-latex-base` + `texlive-latex-extra`)
+- At least one LLM API key (optional but recommended)
+
+### From source
+
+```bash
+git clone https://github.com/Justo-Tapiador/quantum-spherifier.git
+cd quantum-spherifier
+npm install
+cp .env.example .env   # then edit .env to add your API keys
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Start the web dashboard (the agent boots autonomously inside it)
+npm run web
+# → open http://localhost:3000
+
+# 2. Or run headless autonomous research
+npm run research -- --cycles 100
+
+# 3. Guide the agent toward a specific target
+npm run guide "Focus on surface code distance 11 with neutral atoms, targeting logical error rate 1e-9"
+```
+
+The agent starts researching immediately. Watch the **Research Feed** tab for
+real-time progress, the **Archive** tab for produced documents, and the
+**Patent Clusters** tab for filing-ready solution groups.
+
+---
+
+## Usage
+
+### Autonomous Research
+
+This is the default and defining mode. On launch, qSpherifier immediately
+begins cycling through the four research lines, generating hypotheses,
+assessing feasibility, and archiving documents.
+
+```bash
+npm run research -- --cycles 500 --safety standard
+```
+
+Options:
+- `-c, --cycles <n>` — maximum cycles (default 50)
+- `-s, --safety <level>` — `permissive` | `standard` | `strict`
+- `--no-autonomous` — wait for explicit owner directives (disables AJN addiction)
+
+### Web Dashboard
+
+The dashboard provides 8 tabs:
+
+1. **Research Feed** — real-time WebSocket event stream
+2. **Research Lines** — overview of the 4 lines and their cycle counts
+3. **Archive** — all produced documents, filterable by research line
+4. **Patent Queue** — patent-eligible documents with full claims
+5. **Patent Clusters** — grouped filing-ready solutions (★ = filing-ready)
+6. **Knowledge Graph** — Mermaid diagram of the quantum KG (filterable by line)
+7. **Metrics** — live counters, gauges, and histograms
+8. **Owner Guidance** — send directives to steer the agent
+
+```bash
+npm run web
+# → http://localhost:3000
+```
+
+### CLI Commands
+
+```bash
+npm run cli -- research        # Run autonomous research (default)
+npm run cli -- guide "<text>"  # Send an owner directive
+npm run cli -- web             # Start web dashboard
+npm run cli -- demo            # Run a 3-cycle demo
+npm run cli -- train           # Run the 4-phase training pipeline
+npm run cli -- checkpoint save # Save a checkpoint
+npm run cli -- checkpoint list # List checkpoints
+npm run cli -- patents         # List patent-eligible documents
+npm run cli -- clusters        # List patent clusters
+npm run cli -- archive         # Rebuild archive indices
+npm run cli -- status          # Print agent status
+npm run cli -- kg              # Print knowledge graph stats + Mermaid
+npm run cli -- benchmark       # Run performance benchmark
+```
+
+### Owner Guidance
+
+The owner can steer qSpherifier at any time. The directive is parsed by the
+`HierarchicalCommandInterpreter` (LLM-assisted, regex fallback) into a
+structured research plan:
+
+```bash
+# Via CLI
+npm run guide "Focus on qLDPC codes on reconfigurable neutral-atom arrays for constant-rate encoding"
+
+# Via web UI
+# → Owner Guidance tab → type directive → Send Directive
+
+# Via REST API
+curl -X POST http://localhost:3000/api/guide \
+  -H 'Content-Type: application/json' \
+  -d '{"directive":"Evaluate cat-qubit Bacon-Shor codes for biased-noise error correction"}'
+```
+
+**Quick directives** (buttons in the web UI):
+- Surface code d=11 on neutral atoms
+- qLDPC on neutral atoms
+- Fluxonium long-coherence qubits
+- FeMoco via QPE
+- Cat-qubit Bacon-Shor
+- VQE for transition-metal catalysis
+- QSVT + qubitization cross-link
+- Silicon spin qubits CMOS
+
+The directive forces an immediate new cycle; the agent does not abandon its
+autonomous work but pivots the next cycle to the directed target.
+
+---
+
+## Configuration
+
+### Environment variables (`.env`)
+
+See [`.env.example`](.env.example) for the full template. Key variables:
+
+```bash
+# Agent
+QSPHERIFIER_RESEARCH_DIR=./research
+QSPHERIFIER_MAX_CYCLES=500
+QSPHERIFIER_SAFETY=standard
+
+# Web
+QSPHERIFIER_PORT=3000
+QSPHERIFIER_HOST=0.0.0.0
+
+# LLM keys (all optional; router skips missing)
+ZAI_API_KEY=
+ANTHROPIC_API_KEY=
+OPENAI_API_KEY=
+GOOGLE_API_KEY=
+DEEPSEEK_API_KEY=
+OLLAMA_ENDPOINT=http://localhost:11434
+```
+
+### Config files
+
+- [`config/default.json`](config/default.json) — default configuration
+- [`config/production.json`](config/production.json) — production overrides (strict safety, more cycles)
+
+### Safety levels
+
+| Level | Behaviour |
+|-------|-----------|
+| `permissive` | Minimal checks; fast batch research |
+| `standard` (default) | Blocks destructive file ops; rate-limited |
+| `strict` | All checks + requires ≥1 resource anchor per claim + ≥1 KG cross-link |
+
+**Forbidden patterns** (all levels): faster-than-light, infinite coherence,
+no-decoherence, perpetual quantum, free energy, "break RSA-2048 today".
+
+---
+
+## Docker
+
+```bash
+# Build
+npm run docker:build
+# or
+docker build -t quantum-spherifier -f docker/Dockerfile .
+
+# Run
+npm run docker:run
+# or
+docker run -p 3000:3000 \
+  -v $(pwd)/research:/app/research \
+  -v $(pwd)/data:/app/data \
+  -v $(pwd)/.env:/app/.env:ro \
+  quantum-spherifier
+
+# Or with docker-compose
+docker-compose -f docker/docker-compose.yml up
+```
+
+The Docker image includes `pdflatex` for PDF compilation.
+
+---
+
+## Project Structure
+
+```
+quantum-spherifier/
+├── src/
+│   ├── core/
+│   │   ├── QSpherifierAgent.js        # Main orchestrator
+│   │   ├── ANNPsi.js                  # 14-layer backbone (quantum stimulus classes)
+│   │   ├── ArtificialJunkyNeuron.js   # AJN core (6-phase addiction dynamics)
+│   │   └── StateSerializer.js         # Checkpoint save/load
+│   ├── layers/
+│   │   ├── AJNLayer.js                # Homogeneous/Heterogeneous/Hybrid AJN layers
+│   │   └── TransformerBlock.js        # Multi-head self-attention
+│   ├── modules/
+│   │   ├── QuantumKnowledgeGraph.js   # KG with real 2026 hardware anchors
+│   │   ├── ResourceFeasibilityChecker.js  # Quantum feasibility rules + anchors
+│   │   ├── HypothesisGenerator.js     # 4-line + cross-line hypothesis generation
+│   │   ├── ResearchLineRouter.js      # Routes cycles to 4 lines (+ cross-link every 5th)
+│   │   ├── DocumentArchivist.js       # Hierarchical archive with cross-links
+│   │   ├── PatentDraftAssistant.js    # USPTO-style patent drafting
+│   │   ├── PatentClusterManager.js    # Groups patents into filing-ready clusters
+│   │   ├── HierarchicalCommandInterpreter.js  # Parses owner directives
+│   │   ├── SafetyGuardrails.js        # Quantum-specific safety filters
+│   │   ├── MemorySystem.js            # 3-tier persistent memory
+│   │   ├── CitationGraph.js           # Citation/prior-art tracking
+│   │   ├── MetricsCollector.js        # Counters, gauges, histograms
+│   │   ├── PluginManager.js           # Hook-based plugin system
+│   │   ├── CascadeMonitor.js          # Self-healing cascade detection
+│   │   └── TokenEnergyArbitrator.js   # PID-controlled praxis emission
+│   ├── tools/
+│   │   ├── QuantumPhysicsTool.js      # Surface-code error rate, overhead, Shor resources
+│   │   ├── LaTeXDocumentTool.js       # TeX → PDF compilation
+│   │   ├── FileSystemTool.js          # Sandboxed file I/O
+│   │   ├── WebSearchTool.js           # Web search via z-ai-web-dev-sdk
+│   │   ├── BibliographyTool.js        # BibTeX generation
+│   │   ├── Tool.js                    # Abstract base
+│   │   └── ToolRegistry.js            # Central registry
+│   ├── llm/
+│   │   ├── LLMRouter.js               # Task-routed multi-LLM with failover
+│   │   ├── ZAIAdapter.js              # GLM-4.6 (primary)
+│   │   ├── AnthropicAdapter.js        # Claude Opus 4.1
+│   │   ├── OpenAIAdapter.js           # GPT-4o
+│   │   ├── GoogleAdapter.js           # Gemini 2.0
+│   │   ├── DeepSeekAdapter.js         # DeepSeek-R1
+│   │   ├── LocalLLMAdapter.js         # Ollama (air-gapped fallback)
+│   │   └── LLMAdapter.js              # Abstract base
+│   ├── training/
+│   │   └── TrainingPipeline.js        # 4-phase training
+│   └── index.js                       # Entry point + createQSpherifier factory
+├── web/
+│   ├── server.js                      # Express + WebSocket server
+│   └── public/
+│       ├── index.html                 # 8-tab dashboard
+│       ├── css/dashboard.css          # Quantum-themed dark UI
+│       └── js/dashboard.js            # Real-time client
+├── scripts/
+│   ├── cli.js                         # Commander-based CLI
+│   └── benchmark.js                   # Performance benchmark
+├── research/                          # Hierarchical document archive (seeded)
+│   ├── INDEX.md
+│   ├── indices/patent_queue.md
+│   └── topics/{qec,qubits,algorithms,molecular_simulation}/seed_*/main.tex
+├── config/
+│   ├── default.json
+│   └── production.json
+├── docker/
+│   ├── Dockerfile
+│   └── docker-compose.yml
+├── tests/
+│   └── run.js                         # Smoke tests
+├── plugins/
+│   └── example-plugin.js              # Example plugins (cross-link enforcer, metrics logger)
+├── docs/
+│   └── architecture.md                # Full architecture document
+├── .env.example
+├── .gitignore
+├── LICENSE
+├── package.json
+└── README.md
+```
+
+---
+
+## Testing
+
+```bash
+npm test
+```
+
+The test suite verifies:
+- Knowledge Graph seeds with real 2026 quantum hardware nodes
+- All four research lines have seeded concepts
+- Cross-link edges exist (nothing isolated)
+- `findUnderExplored` works per-line
+- Feasibility checker correctly tiers claims (100 qubits → current; 10M → speculative)
+- Resource anchors are detected for real hardware references
+- Cross-link verification flags isolated solutions
+- Surface-code error-rate formula is correct
+- Shor RSA-2048 resources are huge (≥1000 logical qubits)
+- FeMoco chemistry resources require >1M T-gates
+- Research line router routes and detects cross-link cycles
+- Document archivist archives, lists, and filters patents
+- Full agent boots and runs one cycle in template mode (no LLM)
+
+---
+
+## Lineage & Credits
+
+```
+predator-jungle-agent v2.0  (Justo Tapiador Garcia, UA)
+        │
+        │  + fusion domain specialization
+        ▼
+fusionary-agent v1.0  (https://github.com/Justo-Tapiador/fusionary-agent)
+        │
+        │  + quantum computing domain, 4 research lines, cross-linking,
+        │    patent clustering, 6 LLM adapters, real 2026 hardware anchors
+        ▼
+quantum-spherifier (:qSpherifier) v1.0   ← you are here
+```
+
+### Theoretical foundation
+
+> Tapiador García, J. (2024). *Agentic Theory: Definition of the Artificial
+> Junky Neuron (AJN).* Preprint WALLERMAX-AI 2604.00012. Universidad de
+> Alicante (UA).
+
+The AJN is a neuron model inspired by addiction neurobiology: it exhibits
+craving, reinforcement, saturation, withdrawal, frustration, and extinction.
+Unlike a standard artificial neuron, it does not passively wait for input —
+it actively *seeks* stimulus. This is the architectural property that makes
+qSpherifier autonomous.
+
+### Acknowledgements
+
+- The `predator-jungle-agent` and `fusionary-agent` projects for the AJN
+  infrastructure.
+- The quantum-computing community for the open literature on QEC, qubit
+  modalities, algorithms, and molecular simulation that seeds the knowledge
+  graph.
+- The LLM providers (Z.ai, Anthropic, OpenAI, Google, DeepSeek) whose models
+  power the hypothesis generation and patent drafting.
+
+---
+
+## License
+
+MIT License — see [LICENSE](LICENSE).
+
+---
+
+## Citation
+
+If you use quantum-spherifier in your research, please cite:
+
+```bibtex
+@software{quantum_spherifier_2026,
+  title  = {quantum-spherifier: Autonomous Scientific Research Agent for Quantum Computing},
+  author = {Tapiador Garcia, Justo and quantum-spherifier Project},
+  year   = {2026},
+  version = {1.0.0},
+  url    = {https://github.com/Justo-Tapiador/quantum-spherifier},
+  note   = {Based on Agentic Theory and the Artificial Junky Neuron (AJN)}
+}
+```
+
+---
+
+*quantum-spherifier does not wait. It researches.*