init

docs/ai-agent-framework/architecture.md

@@ -0,0 +1,118 @@
+---
+sidebar_position: 2
+---
+
+# Agent Architecture & Design
+
+This page summarizes the intended design of Mycelium Agents, based on the public descriptions on the main site. The details may evolve as we approach the 2026 launch.
+
+## High‑Level View
+
+From the **Agent Design** and **Advantages** sections:
+
+- Each agent **runs entirely inside your environment**.  
+- Agents **communicate peer‑to‑peer** across trusted nodes.  
+- Agents **access data locally** without exposing it to external providers.  
+- Agents are **portable**, moving with your infrastructure rather than with a single cloud vendor.
+
+Conceptually:
+
+```mermaid
+graph TD
+    A[Your Devices & Nodes] --> B[Agent Runtime]
+    B --> C[Local Data & Tools]
+    B --> D[Mycelium Network]
+    D --> E[Other Agents & Nodes]
+```
+
+- The **runtime** executes agent logic.  
+- Agents load and store data through local backends (files, QSFS, databases).  
+- Communication uses **Mycelium Network** between environments.
+
+## Core Properties
+
+### Local Execution
+
+From the "Local Execution" highlight:
+
+> *“Agents run entirely inside your environment. Models, logic, and memory stay within your own trusted hardware, never behind third‑party APIs.”*
+
+Implications:
+
+- You choose where agents run: laptop, homelab, edge cluster, or VDC.  
+- No requirement to send prompts or data to centralized AI APIs.  
+- Compliance and sovereignty become much easier to reason about.
+
+### Mesh Connectivity
+
+From the "Mesh Connectivity" highlight:
+
+> *“They communicate peer‑to‑peer across trusted nodes. Agents form direct encrypted paths between environments, without relays or central servers.”*
+
+This leverages **Mycelium Network** to:
+
+- Give agents a global, encrypted address space.  
+- Enable cross‑site coordination (home ↔ office ↔ cloud ↔ edge).  
+- Avoid central bottlenecks and single points of failure.
+
+### Private Data Access
+
+From the "Private Data Access" highlight:
+
+> *“They use your data without sending it elsewhere. Your datasets, embeddings, and context never leave your boundaries.”*
+
+Design goals:
+
+- Agents can work directly against local file systems, QSFS, and internal services.  
+- Sensitive inputs and outputs remain in environments you choose.  
+- Remote calls (if any) are explicit and policy‑controlled.
+
+### Portability
+
+From the "Portability" highlight:
+
+> *“They move with you, not with a cloud provider. Agents follow your devices, networks, and workflows, remaining sovereign across every location.”*
+
+Over time the framework aims to allow:
+
+- Re‑deploying agents between different nodes and VDCs.  
+- Maintaining state while moving execution closer to data or users.  
+- Using heterogeneous infrastructure (homelab + hoster nodes + VDCs) as one fabric.
+
+## Example Deployment Topologies
+
+### Single‑Node Local Agent
+
+- Agent runtime on your workstation.  
+- Local data and tools only.  
+- Mycelium Network used for optional remote access.
+
+### Multi‑Node Mesh
+
+- Agents running on several nodes (e.g. laptop, homelab, hoster node).  
+- P2P coordination over Mycelium.  
+- Some agents specialized for data access, others for orchestration.
+
+### VDC‑Backed Agent Cluster
+
+- Runtime deployed into a **VDC** as a set of Kubernetes workloads.  
+- Agents expose services reachable only via Mycelium Network.  
+- QSFS and other Mycelium components used for storage.
+
+## Security & Trust (Preview)
+
+From the "Security Architecture" and related messaging:
+
+- **Provable sovereignty** – Assign workloads to trusted zones and verify state with cryptographic proofs.  
+- **Autonomous zero‑trust** – Identity, policy, and attestation enforced continuously.  
+- **Planetary‑scale resilience** – Mesh routing around failures, including regional outages.
+
+As the framework evolves, expect more detailed specifications around:
+
+- Identity & authentication between agents.  
+- Policy models for where and how agents may run.  
+- Auditability and observability of agent behavior.
+
+## Status
+
+The architecture described here is intentionally high‑level and forward‑looking. For timelines and how to prepare, see **[Overview](/ai-agent-framework/overview)** and **[Getting Ready for Agents](/ai-agent-framework/getting-ready)**.

docs/ai-agent-framework/getting-ready.md

@@ -0,0 +1,84 @@
+---
+sidebar_position: 4
+---
+
+# Getting Ready for Agents
+
+The Agent Framework is planned for **H1 2026**, but you can start preparing your infrastructure and workflows today.
+
+This page is based on the "Call To Action" content from the Mycelium Agents page.
+
+## 1. Establish the Networking Layer
+
+Agents will rely on **Mycelium Network** for secure, peer‑to‑peer connectivity.
+
+- Install and use **[Mycelium Network](/network)** on your key devices.  
+- Become comfortable with overlay addresses and testing connectivity.  
+- Decide which machines, clusters, and locations will be part of your "agent fabric".
+
+## 2. Set Up Compute & Clusters
+
+Use **Mycelium Cloud** and **Virtual Data Centers** as the compute substrate for future agents.
+
+- Deploy clusters via **[Mycelium Cloud Getting Started](/cloud/getting-started)**.  
+- Explore **[Kubernetes Basics](/cloud/kubernetes-basics)** and the **[Deployment Tutorials](/cloud/tutorial)**.  
+- Design where different workloads should live (personal VDC, shared VDC, edge nodes, etc.).
+
+If you plan to run larger AI workloads, consider capacity with GPUs or high‑memory nodes.
+
+## 3. Decide How You’ll Host Capacity
+
+If you want agents to run on hardware beyond your personal machines, look into becoming a **hoster**:
+
+- Read **[Hosters Overview](/hosters/overview)** to understand the role.  
+- Choose hardware via **[Buy or Build a Node](/hosters/buy-node)** and **[Advanced Node Options](/hosters/advanced-nodes)**.  
+- Set up your node using **[Set Up Your Node](/hosters/setup)**.  
+- Learn about **[Hosting Economics (SPORE)](/hosters/economics)**.
+
+This prepares a foundation where agents can later run on your own nodes or on community capacity.
+
+## 4. Map Your Data & Privacy Requirements
+
+Agents are meant to operate on **your** data, not someone else’s cloud silo.
+
+Begin planning:
+
+- Where your key datasets live today.  
+- Which data must stay in specific jurisdictions or networks.  
+- Which data could be processed on edge nodes, VDCs, or both.  
+- How quantum‑safe and replicated storage (e.g. QSFS) might fit into your architecture.
+
+## 5. Start with Today’s Components
+
+From the call‑to‑action message:
+
+> *“The Agent Framework launches in H1 2026, but the foundation is ready now. Use today’s components — models, storage, compute, and network — to deploy workloads, connect nodes, and prepare for the next generation of distributed AI.”*
+
+Practical steps you can take now:
+
+- Deploy AI workloads on Mycelium Cloud clusters.  
+- Use Mycelium Network to connect dev machines, clusters, and edge boxes.  
+- Experiment with multi‑node workflows and data flows across environments.  
+- Treat these as early prototypes that agents will later formalize and automate.
+
+## 6. Stay Informed
+
+As the Agent Framework evolves, watch for:
+
+- Updated documentation and architecture deep‑dives.  
+- Early SDKs, CLIs, or runtimes for prototyping.  
+- Example patterns combining agents, VDCs, and QSFS.
+
+Follow official channels (site, docs, community) for announcements.
+
+---
+
+## Summary
+
+You don’t need to wait for the Agent Framework launch to start building:
+
+- Use **network**, **cloud**, **VDC**, and **hosting** pieces today.  
+- Organize data and infrastructure so that agents can slot in later.  
+- Think in terms of **sovereign, distributed AI** rather than centralized APIs.
+
+When agents arrive, you’ll already have the networking, compute, and data foundations in place.

docs/ai-agent-framework/overview.md

@@ -0,0 +1,76 @@
+---
+sidebar_position: 1
+slug: /ai-agent-framework
+---
+
+# Mycelium Agent Framework (Preview)
+
+> **Status:** Coming in 2026 – early design subject to change.
+
+Mycelium Agents are **private, sovereign, and distributed AI systems** that run on infrastructure you control. Instead of sending your data and logic to a centralized AI cloud, agents live **inside your own environment** and connect over the **Mycelium Network**.
+
+This page gives a high‑level preview of the framework and how it fits into the rest of Mycelium.
+
+## What Are Mycelium Agents?
+
+From the marketing overview:
+
+> *“Private, Sovereign and Distributed AI You Control.”*
+
+Mycelium Agents are designed so that:
+
+- **Execution stays local** – Models, logic, and memory run on your own hardware.  
+- **Connectivity is peer‑to‑peer** – Agents communicate over Mycelium’s encrypted mesh.  
+- **Data remains private** – Your datasets, embeddings, and tools stay inside your trust boundary.  
+- **Agents are portable** – They can move with you across devices, clusters, and locations.
+
+## Design Principles
+
+The Agent Framework is being designed around a few core principles (see **Agent Design** and **Advantages** on the main site):
+
+- **Inside your environment** – Each agent operates entirely within your chosen infrastructure (laptop, homelab, edge node, cluster).  
+- **Mesh connectivity** – Agents talk to each other across trusted nodes using Mycelium Network, without central relays.  
+- **Local data access** – Agents read and write data locally (file systems, QSFS, databases) without shipping it to a third‑party.  
+- **Zero‑trust posture** – Identity, policy, and attestation are enforced continuously.  
+- **Portability** – Agents follow your workflows, not a particular cloud provider.
+
+## Relationship to the Rest of Mycelium
+
+The Agent Framework is built on top of existing Mycelium components:
+
+- **Mycelium Network** – Encrypted IPv6 overlay and addressing fabric between nodes.  
+- **Mycelium Cloud / VDC** – Kubernetes clusters and virtual data centers hosting compute.  
+- **QSFS / Storage** – Quantum‑safe, replicated storage for long‑term data and model artifacts.  
+- **Hosters** – Community‑run capacity providing the underlying infrastructure.
+
+Agents are planned to run:
+
+- On your own devices (laptops, workstations, homelabs).  
+- On edge or datacenter nodes provided by hosters.  
+- Inside VDCs as part of larger application stacks.
+
+## What You Can Expect
+
+While the full technical spec is still evolving, you can expect:
+
+- A **runtime** for defining and running agents on your nodes.  
+- A **connectivity layer** for secure P2P communication between agents.  
+- A **policy model** for where agents may run and which data they may access.  
+- **Composability** with existing tools – containers, Kubernetes, storage backends, and Mycelium networking.
+
+## Timeline and Scope
+
+- **Launch window:** Agent Framework targeted for **H1 2026**.  
+- **Preview phase:** Before launch, expect design updates, early prototypes, and integration examples.  
+- **Ecosystem:** The goal is to make agents first‑class citizens of the wider Mycelium / ThreeFold ecosystem.
+
+## How to Prepare
+
+Although the Agent Framework itself is not yet released, you can prepare today by using the underlying components:
+
+- **Networking:** Get familiar with **[Mycelium Network](/network)** and how overlay addressing works.  
+- **Compute:** Use **[Mycelium Cloud](/cloud)** and **[VDCs](/vdc)** to deploy clusters and workloads.  
+- **Capacity:** If you want to run agents on your own or community hardware, explore **[Hosters](/hosters)**.  
+- **Data:** Consider how sensitive data will be stored and accessed locally (e.g. QSFS).
+
+See **[Getting Ready for Agents](/ai-agent-framework/getting-ready)** for a more practical checklist.

docs/ai-agent-framework/use-cases.md

@@ -0,0 +1,87 @@
+---
+sidebar_position: 3
+---
+
+# Agent Use Cases
+
+This page adapts the **Agent Use Cases** section from the Mycelium site into documentation form.
+
+## What the Framework Enables
+
+> *“The framework gives you full control over where agents live, how they connect, and what data they use.”*
+
+Agents are intended to be:
+
+- **Location‑aware** – you decide which nodes or VDCs they inhabit.  
+- **Network‑aware** – connectivity and topology are visible and controllable.  
+- **Data‑aware** – data stays where it should, with explicit movement.
+
+## Example Use Cases
+
+### Run Agents on Your Own Hardware
+
+Deploy agents directly on:
+
+- Laptops and workstations.  
+- Homelabs and edge boxes.  
+- VDCs and clusters you control.
+
+You are not tied to any single cloud or vendor; agents execute where it makes the most sense for latency, privacy, or cost.
+
+### Connect Agents Over the Mycelium Network
+
+Use **Mycelium Network** as the secure fabric between agents.
+
+- Private overlay addressing across homes, offices, and datacenters.  
+- Encrypted paths between nodes in different countries or environments.  
+- One consistent address space spanning local and remote infrastructure.
+
+### Keep Data and Memory Private by Default
+
+Agents are designed to:
+
+- Use local datasets, tools, prompts, and embeddings.  
+- Avoid sending sensitive context to external AI APIs by default.  
+- Respect policies for which data may be shared and where.
+
+This is especially important for regulated sectors and internal systems.
+
+### Build Workflows Across Cloud + Edge
+
+Orchestrate multi‑node workflows that span:
+
+- Edge clusters near data sources.  
+- Central VDCs for heavier compute or aggregation.  
+- Personal devices for interaction and control.
+
+Examples:
+
+- Real‑time processing at the edge, with summarized results aggregated in a VDC.  
+- Agents coordinating tasks between office locations and remote workers.  
+- Data pipelines that never leave your chosen infrastructure.
+
+### Operate in Regulated Contexts
+
+Run agents where strict requirements apply:
+
+- Healthcare, finance, public sector, and other regulated domains.  
+- Environments with **data residency** constraints.  
+- Workloads requiring verified identity and controlled connectivity.
+
+The combination of **local execution**, **sovereign infrastructure**, and **encrypted mesh networking** is intended to make regulatory compliance more tractable.
+
+### Blend Local and Remote Intelligence
+
+Not all tasks need to run on the same node:
+
+- Lightweight agents might run locally for responsiveness and interactivity.  
+- Heavier workloads can be scheduled to trusted remote nodes (e.g. GPU clusters).  
+- Data movement is explicit and policy‑driven.
+
+This supports hybrid strategies where you balance privacy, performance, and cost.
+
+---
+
+## Looking Ahead
+
+These use cases are **illustrative** and may expand as the Agent Framework matures. For how to prepare your infrastructure today, see **[Getting Ready for Agents](/ai-agent-framework/getting-ready)**.