# Introduction

an open-source protocol for modular, purpose-aligned coordination

Holons provide a new way of organizing coordination in complex systems. Instead of relying on centralized platforms, rigid hierarchies, or loose networks with unclear responsibilities, holons enable autonomous units to collaborate through shared protocols for value flow, commitments, and accountability. Each holon acts as both a whole and a part, able to self-govern internally while participating in larger patterns of collaboration.

This architecture is designed for environments where relationships matter more than transactions, where resources are diverse (not only money), and where groups must act together without giving up their independence. Holons create a common language for commitments, contributions, and exchanges, allowing any group to coordinate with any other—whether they are families, cooperatives, nonprofits, DAOs, bioregional hubs, or global alliances.

At the core is a simple idea: **make relationships economically meaningful**. Instead of abstracting complexity away, holons reveal how value actually moves—time, care, knowledge, tools, land, money, infrastructure, and social capital. By doing so, they enable more equitable collaboration, clearer agreements, and a shared understanding of who contributes what, to whom, and under which conditions.

Holons function through modular smart-contract templates that communities can easily deploy and compose. These templates include contribution agreements, funding buckets, flow splitters, threshold triggers, value equations, and federation structures. Combined, they form a lightweight but expressive operating system for decentralized coordination.

This approach does not replace existing tools—it complements them. Holons can work alongside traditional accounting, governance, or project management systems, providing a missing layer: **transparent, programmable economic relationships across organizational boundaries**.

By adopting holons, groups gain:

* **Clarity:** Explicit, trackable commitments and resource flows.
* **Autonomy:** Each group maintains self-governance while participating in wider networks.
* **Interoperability:** Holons can connect across sectors, regions, and technologies.
* **Resilience:** Distributed value flow reduces dependency on central intermediaries.
* **Fairness:** Contributions and responsibilities are recognized across the entire ecosystem.

Holons are a shift in how we collaborate. They enable a move from competitive silos to regenerative networks—where value circulates, relationships strengthen, and collective intelligence becomes visible.

This introduction serves as a doorway into the architecture, patterns, and use cases that follow. The pages ahead explore how holons can be applied to real-world coordination challenges: from funding regenerative projects, to running nonprofits, to enabling bioregional governance, mutual credit, disaster relief, and new forms of digital organizations.

Holons are a foundation for a future in which collaboration scales with trust, transparency, and shared purpose. Welcome.

## Where to start

These docs cover three layers: the **protocol** (what holons are and how they coordinate), the **software** (the working implementation), and the **applications** (concrete use cases).

```
                    Application Areas
              (Non-profits · Bioregions · DAOs ·
               Disaster Relief · Family · Hubs · …)
                            │
                            ▼
                ┌────────────────────────┐
                │     Holons protocol    │
                │   membrane · splitter  │
                │ value equation · DNA · │
                │   federation · zones   │
                └───────────┬────────────┘
                            │
                            ▼
                ┌────────────────────────┐
                │   Software (Harvest)   │
                │ web · telegram · CLI · │
                │  AI agent · MCP server │
                │     @holons/core       │
                │       HoloSphere       │
                └────────────────────────┘
```

A recommended reading order:

1. [**What is a Holon?**](/getting-started/what-is-a-holon) — the 5-minute conceptual frame.
2. [**Run Your First Holon**](/getting-started/run-your-first-holon) — practical levels from a chat group to an MCP-callable federated holon.
3. [**Funding Flow**](/getting-started/funding-flow) — the economic layer (splitters, thresholds, value equations, federation).
4. [**Glossary**](/getting-started/glossary) — the single source of truth for vocabulary.
5. [**Harvest**](/software/harvest-dashboard) and [**The Shared Core**](/software/core) — the software architecture.
6. [**Application Areas**](https://github.com/liminalvillage/holonsdocs/blob/main/application-areas/README.md) — concrete scenarios.

If you're returning after a while, see [Migration Notes](/reference/migration-notes) for what's moved. If you're stuck, the [FAQ](/reference/faq) probably has the answer.


# What is a Holon?

A five-minute introduction before diving into the rest of the docs

The word **holon** comes from Greek: *holos* (whole) + *on* (part). A holon is a thing that is **simultaneously a whole and a part of something larger**. Your body is a holon: it is a whole organism, and it is part of a family, a community, an ecosystem. A team is a holon: a whole working unit, and a part of an organization.

The Holons protocol takes this idea and makes it usable as a coordination tool. Every group—family, team, cooperative, neighborhood, region—can run as a holon: self-governing internally, and composable with other holons externally.

This page is the short version. For the full architecture see [Funding Flow](/getting-started/funding-flow); for definitions of every recurring term see the [Glossary](/getting-started/glossary).

## The four ideas that make a holon work

A working holon needs to answer four questions. Each has a primitive in the protocol.

### 1. What holds it together? — the **membrane**

A holon has a [membrane](/getting-started/glossary#membrane): a flexible boundary that defines who is in, what the holon is for, and what it values. Membranes are semi-permeable—people, resources, and information cross in and out under conditions the holon sets for itself. The membrane is what gives the holon an identity distinct from its surroundings.

### 2. What is valued inside? — the **value equation**

Each holon defines its own [value equation](/getting-started/glossary#value-equation): a formula that converts contributions (hours, outcomes, appreciations, relationship-building) into points, and points into shares of whatever the holon distributes. Two holons can run identical software and produce very different cultures, simply by tuning the weights.

A common starting equation:

```
Points = (Hours × Hour_Weight) +
         (Appreciations × Appreciation_Weight) +
         (Outcomes_Delivered × Outcome_Weight)

Share  = Points_Individual / Points_Total
```

### 3. How do resources move? — **splitters and thresholds**

When resources flow into a holon, they are routed by primitives:

* A [Splitter](/getting-started/glossary#splitter) divides incoming flow between destinations—often between internal contributors and external ecosystem partners, with a single dial controlling the balance.
* A [Threshold Bucket](/getting-started/glossary#threshold-bucket) accumulates resources until a minimum need is met, then sends overflow to a downstream holon or federation pool.

Together these primitives make it possible to say: "fund what we need first, then share the surplus with the people who help us thrive."

### 4. How does it connect to others? — **federation**

Holons [federate](/getting-started/glossary#federation) by declaring trust relationships with other holons. A federation can be as light as "we share appreciation data" or as committed as "we share a mutual-aid treasury." Once federated, value can flow across holon boundaries under the rules each holon defines for itself. This is how a coffee co-op, a regional fund, and a bioregional alliance can act as one network without giving up their autonomy.

## A concrete picture

Imagine a community garden running as a holon:

1. The garden is a Telegram group. Members add the [HolonsBot](/software/holonsbot) and declare a purpose ("steward this land, feed the neighborhood").
2. Members use `/appreciate` to recognize each other's work—weeding, watering, hosting workshops. Appreciations accumulate as a public record.
3. The garden runs a **value equation** that weights appreciations heavily, hours moderately, and outcomes (harvests, workshops delivered) the most.
4. A small grant arrives. A **splitter** sends 70% to active contributors (proportional to points) and 30% into an ecosystem pool shared with three nearby gardens.
5. The four gardens have **federated**: when any one of them has surplus, it overflows into the shared pool, which redistributes to whichever garden currently needs it most.

Nothing here required a central authority. The rules are explicit, the record is public, and every holon retained its autonomy.

## Where to go next

* **Want the architectural depth?** Read [Funding Flow](/getting-started/funding-flow) — the full whitepaper on contracts, distribution mechanisms, and federation.
* **Want a specific shape of holon?** See [Holon types (flavor)](/software/holons-types-flavor) for composable patterns: [Splitter](/software/holons-types-flavor/splitter-holon), [Managed](/software/holons-types-flavor/managed-holon), [Zoned](/software/holons-types-flavor/zoned-holon), [Appreciative](/software/holons-types-flavor/appreciative-holon).
* **Want to set one up?** Start with [Setting up your holonic organization](/daos/setting-up-your-holonic-organization).
* **Want a specific use case?** Browse the [Application Areas](https://github.com/liminalvillage/holonsdocs/blob/main/application-areas/README.md) — non-profits, bioregional regeneration, mutual aid, family management, and more.
* **Stuck on a term?** The [Glossary](/getting-started/glossary) is the single source of truth for vocabulary.


# Run Your First Holon

An end-to-end walkthrough from zero to a federated, scored, MCP-callable holon

This is the practical companion to [What is a Holon?](/getting-started/what-is-a-holon). It walks through the actual steps of getting a holon running—people coordinating in chat, contributions being recognized, work being scored, federation to other holons, and AI agents able to participate via MCP.

You can stop after any step. Each one produces a working holon at a different level of capability.

## Level 0 — A chat group

The simplest holon is a group of people coordinating in one channel. No tools required.

1. Create a Telegram (or any chat) group.
2. Write the holon's **purpose** in the channel description: one sentence about what the holon is for.
3. Invite the people who will participate.

That's it. You have a holon: it has a [membrane](/getting-started/glossary#membrane) (the group), [shared DNA](/getting-started/glossary#shared-dna) (the purpose), and members. Everything that follows just makes it more legible.

## Level 1 — Add HolonsBot

This step turns informal coordination into structured, attributable records.

1. Follow [Setting up your holonic organization](/daos/setting-up-your-holonic-organization) to deploy [HolonsBot](/software/holonsbot) (or its modern incarnation `@holons/telegram-ui`) into the group.
2. Add the bot as an administrator.
3. Try the basic verbs:

| Verb                      | Example                                         |
| ------------------------- | ----------------------------------------------- |
| Create a task             | `/task water the seedlings`                     |
| Recognize a contribution  | `/appreciate @laura for hosting tonight's call` |
| Make an offer             | `/offer yoga sessions on Tuesday mornings`      |
| Make a request            | `/request someone to drive the truck on Friday` |
| See where everyone stands | `/status`                                       |

The holon now has a [task log](/software/tasks), an [appreciation record](/software/scoring), and an open board of needs and offers. It is a [Managed Holon](/software/holons-types-flavor/managed-holon).

## Level 2 — Define what counts

The next step is to make the holon's **values** explicit. This is what shapes what gets recognized.

1. Add **chromosomes** describing your values, tools, and practices — through the bot or directly via the [DNA domain](/software/dna).
2. Build a **DNA sequence** from the chromosomes that most define this holon (max 20).
3. Tune the [**value equation weights**](/software/scoring) so contributions you care about (hours, appreciations, completed quests, specific currencies) carry the right relative weight.

A nature-stewardship holon might weight outcomes (`completed`) and appreciations heavily, with hours secondary. A research collective might weight hours and currencies (paid grants) higher. There is no universal right answer—the equation **is** the culture.

## Level 3 — Federate

A single holon is useful. A federation is regenerative.

1. Identify one or two sibling holons—other groups doing related work.
2. Use the bot's `/federate` command (or call the [federation domain](/software/federation) directly) to declare the trust relationship.
3. Once federated, you can [publish](/software/federation) quests, offers, requests, or appreciations across the boundary. Holons that share a [settings hex](/software/federation#settings-hex-integration) can also be discovered by anyone subscribing to that cell.

Federation is bilateral and revocable. Each side keeps its own DNA, value equation, and rules; only the items each chooses to publish cross the membrane.

## Level 4 — Open to AI agents

This is what makes the difference between a holon that AI watches and a holon AI **participates in**.

### Option A — In-process Claude loop

Use [`@holons/ai-ui`](/software/ai-ui) when you want intelligence **embedded in** the holon's own infrastructure (a bot handler, a cron job, a webhook):

```bash
export ANTHROPIC_API_KEY=sk-…
holons-ai "Summarize this week's open quests in the garden holon"
```

The agent runs as the holon, with the actor identity you've configured (`HOLONS_ACTOR_*` env vars).

### Option B — MCP server for external agents

Use [`@holons/mcp-ui`](/software/mcp-server) when you want **external** clients (Claude Desktop, IDE plugins, custom agents) to participate:

```bash
# stdio mode — typical for Claude Desktop
node packages/mcp-ui/dist/index.js

# SSE on HTTP — when the server must be reachable over the network
node packages/mcp-ui/dist/index.js --port 3200
```

Configure the MCP client with the appropriate `HOLONS_PEER`, `HOLONS_APP`, and `HOLONS_ACTOR_*` env vars. The agent now sees \~100 tools spanning every core domain.

A holon at this level has:

* Humans coordinating through chat.
* Programmatic records (tasks, expenses, appreciations) that drive scoring.
* A clear identity (DNA) and culture (value equation).
* Trust relationships with sibling holons (federation).
* AI agents able to read, write, and act as first-class members.

## A worked example: the community garden

Three people start a neighborhood garden:

1. **Level 0.** They create a Telegram group, write "we steward this land and grow food for the block" in the description, and invite five neighbors.
2. **Level 1.** They add HolonsBot. The first week they log 11 tasks (`/task plant herbs`, `/task fix the gate hinge`) and exchange 23 appreciations.
3. **Level 2.** They add chromosomes — `regenerative practice`, `mutual aid`, `gardening tools`, `consent-based decisions`. They tune their value equation: `completed: 3` (outcomes matter more than starting things), `appreciations: 2` (peer recognition is core), `hours: 1`. The bot's `/status` now reflects what they actually value.
4. **Level 3.** Three nearby gardens federate with them. A surplus harvest gets `/published` to the federation; a request for help with a workshop reaches all four gardens at once. A bioregional aggregator subscribed to the settings-hex picks up the workshop and lists it on a regional board.
5. **Level 4.** They configure the MCP server with the garden's identity and connect Claude. Now a member can ask Claude, in a sentence, to "schedule a watering rotation for the next two weeks based on the weather forecast and people's stated availability." Claude reads the holon's state, calls the appropriate MCP tools, and the rotation appears as a set of recurring quests—every member can see, accept, or reassign them.

## Where to go from here

* **Tune the system.** Read [Scoring](/software/scoring) and adjust your value equation; read [DNA](/software/dna) and refine your chromosomes.
* **Compose flavors.** Layer a [Splitter Holon](/software/holons-types-flavor/splitter-holon) on top to route incoming funds; declare [Zones](/software/holons-types-flavor/zoned-holon) for differentiated participation.
* **Connect deeper.** Read [Funding Flow](/getting-started/funding-flow) for the protocol-level mechanics of multi-currency, threshold-based distribution.
* **Glossary.** Anything unfamiliar lives in the [Glossary](/getting-started/glossary).


# Glossary

A single source of truth for the vocabulary used across these docs

This glossary defines every recurring term in the Holons documentation. Anchor links (`#term-name`) are stable and can be referenced from any other page.

If a term you encounter is missing here, treat it as a gap to be filled, not as an established concept.

## Names of the things, clarified

Before the glossary proper: four names that get used across the docs and are sometimes confused.

* **THEOS — The Holonic Earth Operating System** — the canonical, broader open-source proposal at [theos.io](https://theos.io). Describes a *holonic, peer-to-peer social coordination protocol* aligned with planetary boundaries. See [THEOS](/software/the-holonic-earth-operating-system).
* **Holons** — colloquial shorthand for the protocol THEOS describes, and for working implementations of it (the Liminal Village software ecosystem documented in these docs is one such implementation).
* **Holonic Funding** — the economic/financial layer of the implementation: splitters, threshold buckets, value equations, federation. The subject of the [Funding Flow](/getting-started/funding-flow) whitepaper.
* **HoloSphere** — a JavaScript library for spatial, holonic data using H3 geospatial indexing and GunDB. The substrate for geographic holons. See [HoloSphere](/software/holosphere).
* **HolonsBot** — the Telegram bot that operationalizes a Managed Holon. See [HolonsBot](/software/holonsbot).

## Glossary

### Appreciation

An explicit, attributable act of peer recognition inside a holon. In HolonsBot it is the `/appreciate @user [reason]` command. Appreciations accumulate as a public record and feed the [value equation](#value-equation). They are the defining input of an [Appreciative Holon](/software/holons-types-flavor/appreciative-holon).

### Commitment

A promise made by a holon or contributor, published to the [Commitment Registry](#commitment-registry) so it can be tracked and validated. Commitments are the link between intent and reputation.

### Commitment Registry

A core smart contract that records published commitments, supports validation workflows, updates reputations on completion, and links commitments to delivered outcomes. See [Funding Flow Whitepaper](/getting-started/funding-flow-whitepaper) §3.1.

### Coopetition

"Collaborative competition." A culture in which members are motivated to contribute toward shared goals in a supportive environment, rather than to extract individual reward. Made possible by transparent appreciation data.

### Epoch

A fixed time window over which contributions are tallied and resources are distributed. Each epoch end is when a [value equation](#value-equation) is evaluated and a [splitter](#splitter) fires.

### Federation

A declared trust relationship between holons that lets value, data, or messages flow between them under shared rules. Federation creates a **trust graph** with three roles:

* **Resource sharing** — federated holons can access shared pools (mutual-aid treasuries, project funds, regenerative commons).
* **Data sharing** — in HoloSphere, federation propagates data between spaces while keeping a single source of truth.
* **Cross-holon recognition** — appreciation from one holon can carry weight in another.

See [Funding Flow Whitepaper](/getting-started/funding-flow-whitepaper) §2.2 and [HoloSphere Federation](/software/holosphere/federation).

### Flow Splitter

See [Splitter](#splitter).

### Holarchy

The nested structure formed by holons within holons. A team is in a department is in an organization is in a network—each level a whole and a part. The Holons protocol is designed to operate at every level of a holarchy without changing form.

### Holon

A unit that is simultaneously a whole and a part of a larger system (from Greek *holos* "whole" + *on* "part"). In the Holons protocol, a holon has an identity ([membrane](#membrane)), a value system ([value equation](#value-equation)), resource flows ([splitters](#splitter) and [thresholds](#threshold-bucket)), and the ability to [federate](#federation) with other holons.

### HoloSphere

A JavaScript library that implements holons as hierarchical geographic cells using H3 geospatial indexing and GunDB distributed storage. Provides the spatial substrate when holons map onto territory. See [HoloSphere](/software/holosphere).

### HolonsBot

The Telegram bot that operationalizes most [Managed Holons](/software/holons-types-flavor/managed-holon). Provides task tracking, appreciation, role assignment, federation, and resource coordination through chat commands. See [HolonsBot commands](/software/holonsbot/holonsbot-commands).

### Lens

In HoloSphere, a category or aspect of data attached to a holon (e.g. `environment`, `social`, `articles`, `temperature`). Lenses let a single holon hold many independent data streams.

### Membrane

The semi-permeable boundary that defines a holon's identity, purpose, and values. Membranes regulate what enters and exits—people, resources, information—and evolve as the holon's needs change. In some sections of the docs "membrane" and "holon" are used interchangeably to emphasize different aspects (the boundary vs. the unit it encloses).

### Multi-Sig Pool

A collectively governed treasury where multiple signatures are required to move funds. Used for federated decision-making and transparent fund allocation.

### Notify (HoloSphere)

The list of target spaces a holon notifies when its data changes. The mirror of [federation](#federation): if A federates with B, then `A.federation` includes B and `B.notify` includes A.

### Overflow

The portion of resources that exceeds a [threshold bucket's](#threshold-bucket) capacity. Overflow is automatically redistributed—typically to federated holons or a downstream pool—rather than accumulated indefinitely.

### Pioneer Relationship

An early, foundational collaboration between holons that share DNA (common values and principles). Pioneer relationships grow into larger, more complex collaborations over time.

### Points

The unit of contribution in a [value equation](#value-equation). Points are calculated from raw contributions (hours, appreciations, outcomes) using the holon's chosen weights, then converted to shares of a distribution.

### Relational Zone

A bilateral economic relationship between two holons—"I share my space if you share your expertise." Relational zones live on the **external** side of a [Splitter](#splitter) dial. **Not to be confused** with the internal membership zones of a [Zoned Holon](/software/holons-types-flavor/zoned-holon).

### Shared DNA

The common values and principles members of a holon hold in common. Shared DNA is what makes a membrane coherent; it is what new members must align with to be inside the holon rather than outside.

### Splitter

A primitive that routes incoming resources to multiple destinations according to a configurable rule. The canonical Splitter has a **dual mechanism**—internal contributor rewards on one side, external ecosystem flows on the other—and a single **dial** (0–100%) controlling the balance. See [Splitter Holon](/software/holons-types-flavor/splitter-holon) and [Funding Flow Whitepaper](/getting-started/funding-flow-whitepaper) §3.2.

### Threshold Bucket

A primitive that accumulates resources until a minimum is met, then either distributes them or routes [overflow](#overflow) to a downstream destination. Threshold buckets implement the principle "fund what we need first, then share the surplus." See [Funding Flow Whitepaper](/getting-started/funding-flow-whitepaper) §2.2.

### THEOS

The Holonic Earth Operating System — see [the names section above](#names-of-the-things-clarified) and the [THEOS](/software/the-holonic-earth-operating-system) page. Pronunciation: *theh-os*.

### Value Equation

A formula, chosen by each holon, that converts raw contributions into [points](#points) and points into shares of a distribution. The value equation is how a holon makes its priorities **economically meaningful**—what it pays attention to is what its members will be recognized for. See [Funding Flow Whitepaper](/getting-started/funding-flow-whitepaper) §3.2.

### Weights

The coefficients in a [value equation](#value-equation) that determine how much each type of contribution counts. Adjusted by the holon collectively (in HolonsBot, via `/weights`). Two holons running identical software can produce very different cultures simply by tuning weights.

### Zone (Zoned Holon)

A concentric tier of membership inside a [Zoned Holon](/software/holons-types-flavor/zoned-holon), representing depth of commitment. Typical zones: Core Stewards, Active Contributors, Ambassadors, Supporters. Distinct from a [Relational Zone](#relational-zone).


# Funding Flow

How resources move through holons and federations

**Holonic Funding** is the economic layer of the Holons protocol: the set of smart-contract primitives that let any holon receive, route, and distribute resources without a central custodian. This page is a working summary of how those primitives fit together.

For the full whitepaper—tokenomics, simulation results, market analysis, roadmap, and investment thesis—see [Funding Flow Whitepaper](/getting-started/funding-flow-whitepaper).

## The problem it solves

Every existing financial system assumes hierarchical control and monetary abstraction. Communities working on regeneration, commons-based projects, and decentralized coordination keep running into the same pattern: **value creation happens across relationships, not hierarchies**, but the tools available force every relationship through cash.

A regenerative village has empty rooms and can offer housing, food, and community. A developer can build valuable coordination infrastructure. Each has what the other needs—but the monetary system makes the exchange impossible unless both first convert their offering into money.

Holonic Funding makes relationships economically meaningful by tracking resource flows directly: time, care, knowledge, tools, land, infrastructure, and money, all as first-class flows between holons.

## Core idea

Every holon has the same shape:

* An **identity** ([membrane](/getting-started/glossary#membrane)) that defines who is in and what the holon is for.
* A **value system** ([value equation](/getting-started/glossary#value-equation)) that converts contributions into points and points into shares.
* **Flows** in and out, routed by configurable primitives.
* **Federation relationships** with other holons.

What changes between holons is the configuration of these elements—not the architecture.

## The primitives

Holonic Funding provides a small set of composable contracts. Each holon picks and parameterizes the ones it needs.

### Holon contract

The root identity object. Holds:

* Identity and reputation registry.
* Multi-asset resource balance.
* Inflow and outflow configuration.
* Federation membership.
* Commitment registry pointer.

### Splitter

Routes incoming flow to multiple destinations. The canonical form is a **dual-mechanism splitter** with a single adjustable **dial** (0–100%) governing the split between internal and external flows:

* **Internal flows** — rewards for direct contribution inside the holon.
* **External flows** — rewards routed to ecosystem partners through declared relational priorities.

The dial position shifts with the holon's stage: early stages favor internal (build capacity), mature stages favor external (invest in the ecosystem).

See [Splitter Holon](/software/holons-types-flavor/splitter-holon) for the patterns.

### Threshold bucket

Accumulates resources until a minimum is met, then either distributes or routes **overflow** to a downstream destination. Encodes the principle "fund what we need first, then share the surplus." Threshold buckets are how a holon expresses its actual cost of operation as a structural fact rather than a perpetual ask.

### Value equation module

Calculates points from contributions. A common form:

```
Points = (Hours × Hour_Weight) +
         (Appreciations × Appreciation_Weight) +
         (Outcomes_Delivered × Outcome_Weight)

Share  = Points_Individual / Points_Total
```

Each holon sets its own weights. This is what lets two holons running identical software produce completely different cultures—what they pay attention to is what their members get recognized for.

### Federation contract

Coordinates multiple holons. Manages:

* Shared resource pools (mutual-aid treasuries, project funds, regenerative commons).
* The trust graph between member holons.
* Access propagation—how rights and liabilities flow along delegation chains.

See [HoloSphere Federation](/software/holosphere/federation) for the data-layer counterpart.

### Commitment registry

Records published commitments, supports validation workflows, updates reputation on completion, and links commitments to delivered outcomes. The commitment registry is what makes promises economically meaningful: a holon's standing in the network is built from commitments kept.

## Distribution mechanisms

A holon's outgoing flow is shaped by two complementary mechanisms, balanced by the splitter dial:

**Mechanism A — Internal flows.** Reward direct value creation inside the holon.

1. Contributors log activities (hours, outcomes, appreciations).
2. The value equation calculates contribution points.
3. Resources are allocated proportionally at the end of each [epoch](/getting-started/glossary#epoch).

**Mechanism B — External flows.** Reward relationship-building and ecosystem participation.

1. The holon declares relational priorities (which partners it values).
2. Incoming resources are weighted by relational signals.
3. Resources flow to ecosystem partners.
4. Reciprocal value recognition strengthens the network.

The same holon can run both mechanisms simultaneously, with the dial controlling the proportion.

## Federation patterns

Holons federate to access shared resource pools under value-aligned conditions:

* **Mutual aid treasuries** for member support.
* **Project collaboration funds** for shared initiatives.
* **Regenerative commons pools** for ecosystem health.
* **Risk-sharing instruments** for collective resilience.
* **Shared infrastructure budgets** for network needs.

Federation creates a trust graph. Holons that are more connected attract more flow, and relationship-building becomes economically rewarded over time. Crucially, federated holons retain full autonomy: each one defines its own rules, value equation, and dial position—federation just declares which other holons it trusts and on what terms.

## Resources are not only money

The system coordinates many kinds of resources—tools, spaces, services, tokens, land, time, commitments—each tracked, valued, and governed according to the holon's own rules. Money is one flow among many, not the universal medium that compresses every other relationship.

This is what makes "relational zones" (bilateral resource agreements between holons—"I share my space if you share your expertise") tractable as on-protocol contracts rather than informal arrangements.

## Where to read deeper

* **Full whitepaper** — [Funding Flow Whitepaper](/getting-started/funding-flow-whitepaper) (problem statement, simulation results, tokenomics, market analysis, roadmap, investment thesis).
* **The shapes a holon can take** — [Holon types (flavor)](/software/holons-types-flavor): Splitter, Managed, Zoned, Appreciative.
* **Practical setup** — [Setting up your holonic organization](/daos/setting-up-your-holonic-organization) and [Managing your organization](/daos/managing-your-organization).
* **The data substrate** — [HoloSphere](/software/holosphere) for geographic holons, [HolonsBot](/software/holonsbot) for community holons.
* **Vocabulary** — [Glossary](/getting-started/glossary) for every recurring term.


# Funding Flow Whitepaper

Economic Infrastructure for Networked Coordination

**A memorandum for Mission-Aligned Funders and Founders alike**

Version 1.0\
New Moon, Lunation '73, November 2024

***

### Abstract

Holonic Funding is a federated smart-contract infrastructure that enables autonomous resource coordination across decentralized networks. By making relationships economically meaningful and tracking multi-resource contributions transparently, the system allows communities to coordinate value flows without centralized control or monetary abstraction.

This whitepaper presents the vision, technical architecture, tokenomics, market opportunity, and implementation strategy for building the financial operating system for regenerative, networked economies.

**Core Innovation:** Where traditional systems abstract complexity through money, Holonic Funding reveals resource flows—enabling fair coordination while maintaining the autonomy of participating nodes (Holons).

***

### Table of Contents

1. The Problem: Coordination Failure in Networked Systems
2. The Solution: Holonic Resource Orchestration
3. Technical Architecture
4. Tokenomics & Value Representation
5. Real-World Validation
6. Market Opportunity
7. Business Model
8. Implementation Roadmap
9. Risks & Mitigation
10. Team & Governance
11. Investment Opportunity
12. Conclusion

***

### 1. The Problem: Coordination Failure in Networked Systems

#### 1.1 The Fundamental Mismatch

Communities working on regeneration, commons-based projects, and decentralized coordination face a critical infrastructure gap:

**Value creation happens across relationships, not hierarchies.**

Yet every existing financial system assumes hierarchical control and monetary abstraction. The result is systematic coordination failure:

* **Rigid funding structures** that require centralized decision-making
* **Administrative overhead** consuming resources meant for mission work
* **Centralized bottlenecks** slowing resource allocation to weeks or months
* **Lack of trust infrastructure** requiring repeated verification across organizational boundaries
* **Inability to share resources fluidly** (space, tools, expertise, time)
* **No mechanism to track contribution and impact** in distributed networks
* **Fragmentation** between groups that should be collaborating

#### 1.2 Why Current Alternatives Fail

**Traditional Finance**

* Enforces hierarchies and centralization
* Hides resource flows behind monetary abstraction
* Optimizes for extraction, not coordination
* Requires legal entities and compliance overhead

**DAOs & Web3**

* Attempted governance through endless voting → fatigue and plutocracy
* Introduced tokens for speculation rather than coordination
* No mechanism for multi-resource tracking (only tokens)
* Cannot represent relationships or commitments economically

**Platform Cooperatives**

* Excellent values, inadequate infrastructure
* Forced to use traditional finance tools
* Cannot coordinate across organizational boundaries
* No federated resource sharing

#### 1.3 The Money Trap

A deeper problem underlies all of these: **money has become the universal measure of value, making all other resources economically invisible.**

This creates vicious cycles:

* Empty rooms sit unused because owners need "market rate" cash, even when community members could use the space
* Skilled contributors can't participate because they need immediate liquidity, even when the community has abundant non-monetary resources
* Communities with space, food, land, and expertise can't coordinate effectively because the financial system forces monetization of everything
* The system optimizes for monetary extraction rather than actual value creation

**Example:** A regenerative village has empty rooms and can provide housing, food, and community. A developer can build valuable coordination infrastructure. But the developer says "I need $3000/month to survive" and the village says "I need $3000/month in cash to cover operations." Both have what the other needs, but the monetary system makes exchange impossible.

**This is precisely the problem Holonic Funding solves.**

***

### 2. The Solution: Holonic Resource Orchestration

#### 2.1 Core Concept

Holonic Funding is a composable, federated smart-contract infrastructure that enables any group—small or large—to define how resources move through their ecosystem.

Each **Holon** (individual, team, project, or asset) can:

1. Receive and distribute resources automatically through configurable primitives
2. Form federations (networks of trust) with other Holons
3. Create shared pools for mutual aid, projects, or ecosystem needs
4. Build trust through commitments and reputation
5. Coordinate multiple resource types, not just money

**Where Web3 created tokens, Holonic Funding creates flows.**

**Where DAOs attempted governance, Holonic Funding enables resource orchestration.**

**Where traditional finance enforces centralization, Holonic Funding unlocks peer-to-peer coordination at scale.**

#### 2.2 Key Capabilities

**Autonomous Resource Distribution**

Each Holon receives and distributes resources through modular smart-contract primitives:

**Flow Splitters**

* Configurable routing: "70% to direct contributors, 30% to ecosystem pool"
* Adjustable dial between internal rewards and external collaboration
* Based on value equations defined by each Holon

**Threshold Buckets**

* Resources accumulate until threshold met
* Overflow automatically redistributes to federated Holons
* Ensures needs are met before excess is shared

**Revenue-Share Modules**

* Proportional distribution based on contribution tracking
* Works with hours, outcomes, appreciations, relationship-building
* Each Holon defines its own value equation

**Relational Zones**

* Bilateral economic relationships between Holons
* "I'll share my space if you share your expertise"
* Makes relationships economically meaningful

**Multi-Sig Pools**

* Collective treasury management
* Federated decision-making
* Transparent fund allocation

**Access and Liability Propagation**

* Trust-based resource sharing through delegation chains
* Borrow assets through network trust
* Liability automatically traced to delegator

**Resources aren't just money.** The system coordinates tools, spaces, services, tokens, land, time, and commitments—each tracked, valued, and governed according to community-defined rules.

**Federation (Networks of Trust)**

Holons form federations to access shared resource pools under predefined, value-aligned conditions:

* **Mutual aid treasuries** for member support
* **Project collaboration funds** for shared initiatives
* **Regenerative commons pools** for ecosystem health
* **Risk-sharing instruments** for collective resilience
* **Shared infrastructure budgets** for network needs

Federation creates trust graphs where:

* Access propagates through relationships
* Liability traces through delegation
* Reputation builds through delivery
* Resources flow to where they're valued

**Commitment-Based Trust Building**

Holons publish **commitments** (future obligations) which:

* Strengthen trust within networks
* Make resource attraction predictable
* Create foundation for value-based credit
* Enable collaborative investment
* Build visible track records of delivery

**Example:** A developer commits to building a feature in 2 weeks. The network allocates resources (space, food, tools) based on this commitment. Upon delivery, reputation increases and future resource access improves.

#### 2.3 What Makes This Unique

**Minimal Governance, Maximum Flow**

Instead of endless voting on every decision, Holons autonomously configure their own resource logic. Collective coordination emerges through economic interdependence, not bureaucracy.

Governance happens at the constitutional layer (rules about rules) not the operational layer (deciding every transaction).

**Composable Financial Machines**

A modular library of smart-contract primitives allows ecosystems to build tailored funding architectures—from simple revenue-sharing to complex multi-stakeholder regenerative funds.

Like LEGO blocks, primitives combine in infinite ways to match community needs.

**Relational Economics**

Relationships become economically meaningful through relational zones and bilateral signaling—infrastructure no existing blockchain system provides.

"I value your storytelling" becomes "I direct 10% of my resource flow to support your work."

**Multi-Resource Coordination**

Money is just one resource type. Holons coordinate:

* Physical assets (tools, spaces, land)
* Services (expertise, labor, facilitation)
* Time and attention
* Commitments and obligations
* Access rights
* Tokens (both fungible and non-fungible)

Each resource type tracked, valued, and governed appropriately.

**Federated Access with Accountability**

Trust graphs enable resource propagation (borrowing through chains of trust) with liability automatically traced back through delegation paths.

"I trust Alice, Alice trusts Bob, therefore Bob can use my workshop" → if Bob damages equipment, liability traces back to Alice, preserving trust.

**Purpose-Driven Resource Permissioning**

Every resource carries clearly encoded conditions:

* "Use my land for workshops, not parties"
* "This tool available to aligned networks only"
* "Space accessible during these hours"
* "Expertise available for regenerative projects"

Smart contracts enforce conditions automatically.

**Voluntary Ecosystem Contribution**

Holons can dedicate a portion of inflows to shared pools—but choose where contributions flow, creating long-term ecosystem alignment without coercion.

Unlike taxation (mandatory, opaque), this is voluntary, transparent, and directed by contributors.

**Configurable Value Equations**

Each Holon defines its own "value equation" for internal distribution:

**Simple:** 1 hour worked = 1 point = proportional share

**Complex:** Hours + appreciations + outcomes + relationship-building

**Domain-Specific:**

* Code commits + documentation + community support (tech teams)
* Facilitation quality + space holding + conflict resolution (communities)
* Story amplification + partnership development + fundraising (ambassadors)

**This flexibility is critical:** Different communities value different contributions. Artist collectives weight creative output differently than tech teams. Holonic Funding doesn't impose values—it provides infrastructure for communities to encode their own.

**Role Composability**

Contributors can wear multiple hats (developer + ambassador + strategist) with contributions tracked across roles. The system handles complexity transparently rather than forcing artificial simplification.

A person isn't just "a developer" or "an ambassador"—they're a multi-faceted contributor whose varied work is visible and valued.

***

### 3. Technical Architecture

#### 3.1 System Components

**Core Smart Contracts**

**Holon Contract**

* Identity and reputation registry
* Resource balance tracking (multi-asset)
* Inflow/outflow configuration
* Federation membership
* Commitment registry

**Splitter Contract**

* Configurable distribution logic
* Dual-mechanism routing (internal + external)
* Adjustable allocation dial (0-100%)
* Overflow handling

**Threshold Flow Contract**

* Minimum and maximum thresholds
* Accumulation and overflow logic
* Multi-round distribution
* Convergence optimization

**Value Equation Module**

* Contribution type weighting
* Point calculation logic
* Time-decay functions (optional)
* Outcome validation hooks

**Federation Contract**

* Multi-Holon coordination
* Shared pool management
* Trust graph representation
* Access propagation rules

**Commitment Registry**

* Promise publication
* Validation workflows
* Reputation updates
* Outcome linking

#### 3.2 Distribution Mechanisms

**Mechanism A: Internal Flows (Direct Contribution Rewards)**

**Purpose:** Reward direct value creation within a Holon

**Process:**

1. Contributors log activities (hours, outcomes, appreciations)
2. Value equation calculates contribution points
3. Resources allocated proportionally at epoch end

**Example Value Equation:**

```
Points = (Hours × Hour_Weight) + 
         (Appreciations × Appreciation_Weight) + 
         (Outcomes_Delivered × Outcome_Weight)

Share = Points_Individual / Points_Total
```

**Configurability:** Each Holon sets its own weights based on what it values.

**Mechanism B: External Flows (Collaborative Network Rewards)**

**Purpose:** Reward relationship-building and ecosystem participation

**Process:**

1. Holons declare relational priorities (which partners they value)
2. Incoming resources weighted by relational signals
3. Resources distributed to ecosystem partners
4. Strengthens network bonds

**Relational Zones:**

* Bilateral relationships between Holons
* "I value X's storytelling → direct 10% of flow to X"
* Reciprocal value recognition builds trust

**Network Effects:**

* More connected Holons attract more resources
* Relationship-building becomes economically rewarded
* Network density increases over time

**Splitter Configuration**

**The Dial:** 0-100% determines split between Mechanism A and B

* **0%** → All resources to internal contributors (siloed)
* **50%** → Balanced internal/external flows
* **100%** → All resources to ecosystem (pure collaboration)

Communities adjust based on their stage:

* Early stage: High internal (build capacity)
* Growth stage: Balanced (build + connect)
* Mature stage: High external (ecosystem investment)

#### 3.3 Simulation Results

**Threshold-based flow funding has been modeled showing:**

* **95% minimum needs coverage** even with only 60% of required capital
* **Network convergence in 3-5 rounds** of distribution
* **Superior equality** (lower Gini coefficient) compared to simple allocation models
* **Scalability to 1000+ node networks** without performance degradation

**Key Finding:** Smart redistribution through overflow logic enables networks to sustain members even during resource scarcity.

#### 3.4 Integration Points

**Blockchain Layer**

* EVM-compatible chains (Ethereum, Polygon, Arbitrum, Base)
* Integration with Inverter Protocol for workflow orchestration
* Cross-chain compatibility through bridge protocols

**Identity Layer**

* Ad4m DID integration for decentralized identity
* Sybil resistance through proof of personhood (optional)
* Reputation tracking across contexts

**Frontend Interfaces**

* Web application for Holon management
* Mobile app for contribution tracking
* API for third-party integrations

**Data Layer**

* IPFS for decentralized storage
* The Graph for event indexing
* Local-first with p2p sync (Perspectives)

***

### 4. Tokenomics & Value Representation

#### 4.1 The Resource Visibility Challenge

Traditional financial systems abstract complexity through money—"this costs $40, that costs $50"—hiding whether something was produced locally by 3D printer or shipped globally using exploited labor.

**Holonic Funding deliberately goes "one step below" monetary abstraction** to make resource flows visible.

This creates tension: the power of money comes from its simplification, but that simplification creates the problems we're solving. We must make complexity navigable without overwhelming users.

#### 4.2 Token Model: Fixed Allocation with Contribution-Based Distribution

**Monthly Token Allocation:**

* Fixed pool released per epoch (e.g., 10,000 tokens/month)
* Algorithmic adjustment based on network activity
* Distribution governed by contribution ratios within each Holon

**How It Works:**

1. **Network Release:** 10,000 tokens issued to federated Holons
2. **Inter-Holon Allocation:** Governance allocates between Holons
   * Example: 50% to Development, 20% to Community, 20% to Partnerships, 10% to Operations
   * Based on value created and network needs
3. **Intra-Holon Distribution:** Within each Holon, tokens distributed based on contribution tracking
4. **Multi-Purpose Tokens:** Same tokens work for monetary resources, physical resources, access rights, discounts

**Why Fixed Allocation:**

* Avoids security token classification (not issuing equity)
* Enables value capture during periods of zero monetary inflow
* Creates scarcity and incentives for value creation
* Allows market to discover token value
* Simpler governance (adjust rate, not individual issuances)

#### 4.3 Commitment-Outcome Architecture

Alternative to pure "hours worked" tracking:

**Structure:**

* **Commitments** → Specific outcomes promised to the network
* **Execution** → Work performed toward outcomes
* **Validation** → Community verifies completion
* **Minting** → Tokens issued upon successful validation

**Advantages:**

* Ties compensation to results, not just effort
* Creates visible "trees of executed tasks" for external evaluation
* Natural bounty system emerges
* Clearer for partnership and funding evaluation
* Builds reputation based on delivery

**Validation Methods:**

* Peer review (community validates)
* Objective criteria (code merged, document published)
* Oracle data (third-party verification)
* Time-based (commitment + time threshold = auto-validate)

#### 4.4 The Stability Requirement

**User Need:** "If I do this work, I need to know I'll receive THIS value."

**Challenge:** Protocol tokens fluctuate with markets, creating unpredictability.

**Dual-Token Approach:**

**Compensation Layer (Stable)**

* Stablecoins (USDC, DAI) for predictable value
* Resource guarantees (housing, food, tools)
* Immediate value realization

**Coordination Layer (Protocol Tokens)**

* Governance rights
* Access to network resources
* Relationship representation
* Reputation tracking

**Speculation Layer (Optional)**

* Market-traded protocol tokens
* For those who want upside exposure
* Separated from compensation needs

**This separation enables:**

* Contributors get predictable value for work
* Network coordination through protocol tokens
* Market discovery of protocol value
* Risk separation (stable income vs. venture upside)

#### 4.5 Revenue Share vs. Profit Share

**Traditional Approach: Profit Share**

* Revenue minus costs = distributable profit
* Simple to calculate
* Hides resource flows
* Forces monetary accounting

**Problem:** Two shoes cost $40 vs $50—no visibility into whether one was produced locally by 3D printer or shipped globally using exploited labor. Economic choice based only on price.

**Holonic Approach: Revenue Share with Resource Visibility**

* Track actual inputs (time, space, materials, capital, relationships)
* Communities define what counts as contribution vs. cost
* Resource pooling shifts ratios naturally (land + time + money → shared outcome)
* More complex but more fair and transparent

**Example:**

* Liminal Village contributes space ($20K/year value)
* Developer contributes 1,000 hours ($100K/year value)
* Funder contributes $30K capital
* **Network Total:** $150K value pooled
* **Revenue share:** 13% to space, 67% to developer, 20% to capital
* **Profit share would hide these contributions behind "costs"**

**Why This Matters:**

* Makes non-monetary contributions economically visible
* Enables resource pooling (not just monetary investment)
* Creates fair distribution across contribution types
* Reveals true cost of value creation (environmental, social)

#### 4.6 Addressing the Bootstrap Period

**Reality:** Early phase has work happening but minimal monetary inflow.

**Token Solution:**

* Tokens issued based on contributions (work, resources, outcomes)
* Value uncertain but tracked transparently
* Acts as "sweat equity" with cryptographic verification
* Multiple realization points:
  * **Internal network:** Exchange for resources (space, tools, services)
  * **External markets:** If tokens trade on exchanges
  * **Fiat conversion:** When monetary resources flow in
  * **Resource access:** Direct redemption within federation

**Risk Disclosure:**

Early contributors are taking **venture risk**. This must be made explicit:

* Tokens may have zero value if project fails
* Recommend hybrid compensation (some stable resources + token upside)
* Clear scenarios: best case, worst case, expected case
* Regular evaluation cycles (monthly/quarterly) with exit options
* Transparent modeling of potential outcomes

**Why Honesty Matters:**

Building trust requires acknowledging reality. Early contributors aren't "employees getting paid"—they're co-creators taking entrepreneurial risk. Making this explicit:

* Attracts the right people (aligned with vision, comfortable with uncertainty)
* Prevents resentment (everyone knew the terms)
* Creates realistic expectations (not promises of guaranteed returns)
* Builds community solidarity (we're in this together)

#### 4.7 Governance Minimization

Distribution requires some governance, but we minimize it:

**Protocol-Level Decisions (Algorithmic):**

* Token release rate
* Contribution validation methods
* Overflow and threshold logic
* Access propagation rules

**Community-Level Decisions (Quarterly Review):**

* Inter-Holon allocation ratios
* Value equation parameters
* Partnership priorities
* Network membership

**Individual-Level Decisions (Autonomous):**

* Intra-Holon distribution
* Splitter dial position
* Relational priority signaling
* Commitment publication

**Goal:** Embed rules in protocol, not in recurring meetings. Governance as constitutional layer (rules about rules), not operational layer (deciding every transaction).

**Why This Works:**

* Reduces coordination overhead
* Enables autonomous operation
* Maintains flexibility where needed
* Prevents governance capture

#### 4.8 Implementation Pragmatism

**The Complexity Trade-off:**

We're making visible what current systems hide. This is both our strength (fairness, transparency) and our challenge (cognitive load).

**Phased Simplicity:**

**Phase 1: Simple Profit Share (Months 1-6)**

* Get communities coordinating financially *at all*
* Basic contribution tracking (hours, appreciations)
* Monthly distribution based on simple ratios
* Single token type
* Builds trust and proves concept

**Goal:** Demonstrate immediate value without overwhelming complexity.

**Phase 2: Resource Visibility (Months 6-12)**

* Add non-monetary resource tracking
* Enable resource pooling (space + time + capital)
* Revenue share with visible contributions
* Federation begins (2-3 Holons connecting)

**Goal:** Show how multi-resource coordination creates new possibilities.

**Phase 3: Full Holonic Coordination (Year 2+)**

* Commitment-outcome trees
* Complex value equations
* Multi-token systems
* Cross-network propagation
* Algorithmic governance

**Goal:** Deliver the full vision for sophisticated networks.

**Critical Principle:** Each phase must provide standalone value. Don't promise Phase 3 capabilities while delivering Phase 1. Build trust incrementally.

**Templates Over Configuration:**

Rather than exposing all complexity, provide:

**Co-op Template**

* Equal shares, simple profit split
* Democratic governance
* Member-owned resources

**Project Template**

* Outcome-based bounties
* Milestone payments
* Contributor reputation

**Community Template**

* Resource pooling
* Needs-based distribution
* Mutual aid focus

**DAO Template**

* Token-weighted governance
* Treasury management
* Proposal workflows

Users start with templates, customize as they understand the system.

***

### 5. Real-World Validation

#### 5.1 Liminal Village: Living Laboratory

The core principles have been tested at **Liminal Village**, a regenerative community in Portugal, where:

* Multi-resource coordination practiced (housing, food, expertise, time)
* Tensions between monetary and non-monetary value directly experienced
* Contribution tracking needs validated through actual community operation
* Limitations of existing tools (Notion, spreadsheets, verbal agreements) painfully clear

**Key Learnings:**

**1. The Ambassador Role Validation**

Communities need people building relationships and telling their story to attract resources—but traditional employment can't fund this until success is proven (catch-22).

**Example:** Developer working on Holonic Funding needs to build partnerships, tell the story, attract funders. This work creates immense value but generates no immediate revenue. Traditional employment would require revenue first.

**Holonic Solution:** Sweat equity tracking enables this critical role. Contributions recorded, value recognized within network, reputation built. When resources flow, early relationship-building is rewarded.

**2. Resource Mismatch in Practice**

Village has abundant space and resources but needs small amounts of cash for specific needs (utilities, supplies). Contributors need stability but the village can't pay traditional salaries.

**The Impasse:** "I need $3000/month" meets "I have space worth $1000/month but only $500 cash."

**Traditional Finance Response:** "Sorry, doesn't work."

**Holonic Response:** "You receive $500 + space + food + community ($1500 equivalent) + sweat equity tokens for future upside. Total package: $2000 current + future upside."

Not perfect, but enables coordination where traditional finance creates deadlock.

**3. Trust Before Scale**

Small networks (5-20 people) need working internal coordination before they'll invest in larger network participation.

**Implication:** Must prove value locally before promising federation benefits. Single-Holon utility must be compelling standalone. Network effects are progressive enhancement, not requirement.

**4. Sweat Equity Without Infrastructure Breeds Resentment**

Contributors working on "sweat equity" basis without actual tracking system experience:

* Uncertainty about whether/when contributions will be valued
* Feeling exploited when approaching personal financial limits
* Tension between believing in vision and needing to survive
* Lack of clarity about what success looks like

**Critical Insight:** Contribution tracking can't be a "future feature"—it must be Day 1 infrastructure. Even simple system (spreadsheet + smart contract) beats having nothing. Trust requires proof.

**5. Role Complexity Is Real**

Modern work is multi-faceted (ambassador + developer + strategist + storyteller + relationship-builder) but payment systems want single-role simplicity.

**Example:** Same person builds code, facilitates partnerships, tells the story, designs architecture. Which role are they? All of them. System must handle this without bureaucratic overhead.

**Solution:** Multi-role contribution tracking with clear value equations. System handles complexity transparently rather than forcing artificial simplification.

#### 5.2 Technical Development Status

**Theoretical Framework**

* "The Holonic Experience" articulates four interconnected layers: collective intelligence, storytelling, decision making, action
* Biological analogies validate approach (cellular networks, immune systems)
* Philosophical foundation connects to holarchies and systems thinking

**Smart Contract Architecture**

* Dual-mechanism splitter contracts (internal + external flows)
* Configurable value equations for contribution tracking
* Threshold-based flow distribution logic
* Integration design with Inverter Protocol

**Simulation Validation**

* Threshold-based flow funding modeled extensively
* 95% minimum needs coverage with 60% capital
* 3-5 round convergence
* Scalability to 1000+ nodes demonstrated

#### 5.3 Current Phase: Pre-Deployment

**Status:** Core smart contract modules in development. Integration architecture defined. Pilot partners identified.

**What's Ready:**

* Conceptual framework validated through lived experience
* Smart contract architecture designed
* Simulation results validate viability
* Partnership discussions underway
* Team experiencing the coordination challenges we're solving (unique validation)

**What's Needed:**

* Complete smart contract development and security auditing
* User interface for Holon management
* Pilot deployments with 3-5 design partners
* Documentation and onboarding materials
* Legal structure and compliance framework

#### 5.4 Traction Indicators

* Holonic coordination principles tested in federated community networks
* Interest expressed by multiple bioregional hubs and regenerative villages
* Technical framework documented and peer-reviewed within Web3 coordination circles
* Strong demand signal for non-speculative community coordination mechanisms
* First-mover advantage: no comparable system provides relational funding logic with modular flow control

**Critical Validation:** The team is experiencing the exact problems we're solving. If we can't coordinate our own resources fairly, the system isn't ready. Our internal struggle validates both the problem's reality and our unique qualification to solve it.

***

### 6. Market Opportunity

#### 6.1 Target Markets

Holonic Funding addresses needs at the intersection of multiple emerging sectors:

**Primary Markets**

**Regenerative Villages & Bioregional Networks**

* 1,000+ intentional communities globally
* Growing rapidly post-COVID
* Need coordination infrastructure
* Values-aligned with our approach

**Mission-Driven DAOs and Web3 Collectives**

* 10,000+ DAOs active
* \~$20B in treasuries
* Seeking alternatives to token-weighted governance
* Need contributor coordination tools

**Platform Cooperatives**

* 500+ platform co-ops globally
* $3T+ cooperative sector
* Need federated resource sharing
* Forced to use traditional finance tools

**Nonprofits with Multi-Stakeholder Structures**

* 1.5M+ nonprofits in US alone
* Increasingly collaborative models
* Grant funding requires partnership coordination
* Need transparency and impact tracking

**Community Land Trusts & Shared Resource Networks**

* Growing movement for commons-based property
* Complex multi-stakeholder governance needs
* Resource sharing across properties
* Need trust infrastructure

**Adjacent Markets**

* Alternative governance / DAO tooling ($300M+ annually)
* Digital commons infrastructure
* Regenerative finance (ReFi) ecosystem
* Impact networks & bioregional coordination
* Local exchange and mutual credit systems
* Open-source funding mechanisms

#### 6.2 Market Sizing

**Total Addressable Market (TAM):**

* Global cooperative sector: $3+ trillion in assets
* DAO treasuries under management: \~$20 billion
* Impact investing market: $1+ trillion
* Community foundations and mutual aid: $50+ billion annually
* Platform cooperative economy: Growing 20%+ annually

**Serviceable Addressable Market (SAM):**

* Organizations actively seeking alternative coordination tools
* Communities practicing regenerative economics
* Networks requiring federated resource sharing
* Estimated $50-100B in resources needing coordination infrastructure

**Serviceable Obtainable Market (SOM):**

* Year 1: 50-100 early adopter communities (10,000-20,000 users)
* Year 3: 500-1,000 organizations (100,000-200,000 users)
* Year 5: 5,000+ organizations (1M+ users)

#### 6.3 Market Dynamics

**Tailwinds:**

* DAO governance fatigue creating demand for autonomy-preserving coordination
* Climate action requiring bioregional resource coordination at scale
* Web3 maturation moving beyond speculation toward real coordination infrastructure
* Deglobalization increasing importance of local and regional economic networks
* Commons movement needing technical infrastructure for shared resource management
* Growing awareness that hierarchical organizations can't solve networked problems

**Why Now:**

* Web3 infrastructure mature enough to support complex coordination
* Communities experienced enough with DAOs to know what doesn't work
* COVID accelerated remote coordination needs and distributed work models
* Climate crisis creating urgency for regenerative coordination
* Sufficient examples of coordination failure to validate the problem

#### 6.4 Competitive Landscape

**No direct competitors provide relational funding logic with modular flow control.**

Adjacent tools address fragments:

**Treasury Management**

* Gnosis Safe, Parcel, Multis
* **What they do:** Multi-sig wallets for collective fund management
* **What they lack:** Autonomous flow logic, contribution tracking, multi-resource coordination

**Contribution Tracking**

* Coordinape, SourceCred, Praise
* **What they do:** Track contributions, calculate rewards
* **What they lack:** Automatic distribution, federation, resource sharing beyond tokens

**Workflow Orchestration**

* Inverter, Allo Protocol
* **What they do:** Fund distribution workflows, milestone-based payments
* **What they lack:** Holonic federation, relational economics, multi-resource tracking

**Community Platforms**

* Hylo, Loomio, Discord/Telegram
* **What they do:** Communication and governance discussion
* **What they lack:** Economic coordination, resource tracking, automatic distribution

**Traditional Platforms**

* Slack, Notion, Asana + Stripe/PayPal
* **What they do:** Work coordination + payment processing
* **What they lack:** Contribution tracking, federated coordination, non-monetary resources

#### 6.5 Our Competitive Advantage

**Holonic Funding is the only system integrating:**

1. Autonomous resource distribution
2. Federated trust networks
3. Multi-resource coordination (beyond tokens)
4. Relational economics
5. Configurable value equations
6. Commitment-based reputation
7. Composable primitives

**Into a single, interoperable infrastructure layer.**

**Additionally:**

* First-mover advantage in relational funding
* Validated by lived experience (not just theory)
* Solving coordination problems we directly face
* Strong technical foundation (simulations prove viability)
* Values-aligned with target markets
* Network effects create defensibility

**Barrier to Entry:**

* Complexity of building trust infrastructure
* Need for deep coordination expertise
* Requires lived experience with the problems
* Technical sophistication (smart contracts + UX)
* Community building (can't just build and ship)

***

### 7. Business Model

#### 7.1 Revenue Streams

**Primary: SaaS Subscription + Protocol Fees**

Tiered subscription model with optional protocol fee participation:

**Basic Tier (Free for Small Groups)**

* Single Holon coordination (up to 10 members)
* Simple contribution tracking
* Template-based setup
* Community support
* **Revenue:** $0 (freemium entry point)

**Professional Tier ($50-200/month)**

* Multi-Holon federation (up to 100 members)
* Custom value equations
* Advanced primitives
* Priority support
* Analytics dashboard
* **Revenue:** Average $100/month per org

**Enterprise Tier ($500-2,000/month)**

* Large network coordination (unlimited members)
* Dedicated integration support
* Custom module development
* SLA guarantees
* White-label options
* **Revenue:** Average $1,000/month per network

**Protocol Fee Option (0.5-1%)**

* Optional fee on monetary flows through the system
* Shared back with protocol token holders (regenerative model)
* Only applicable to fiat/crypto transactions, not resource exchanges
* Users opt-in by holding protocol tokens
* **Revenue:** Variable based on network transaction volume

**Secondary: Premium Modules & Services**

**Premium Modules** ($50-500/month each)

* Advanced analytics and forecasting
* Specialized primitives (industry-specific)
* Integration packages (existing tools)
* Custom reporting

**Professional Services** ($150-300/hour)

* Onboarding and training
* Custom architecture design
* Partnership structuring
* Technical consulting

**Future: Module Marketplace**

* User-created coordination primitives
* Revenue share: 70% creator, 30% platform
* Curation and quality assurance
* Open-source encouraged but monetization enabled
* **Revenue:** Percentage of third-party sales

#### 7.2 Revenue Projections

**Conservative Scenario (5 Years)**

| Year | Organizations | Users   | SaaS MRR | Protocol Fees | Annual Revenue |
| ---- | ------------- | ------- | -------- | ------------- | -------------- |
| 1    | 50            | 2,500   | $5K      | $2K           | $84K           |
| 2    | 200           | 10,000  | $25K     | $15K          | $480K          |
| 3    | 1,000         | 50,000  | $125K    | $75K          | $2.4M          |
| 4    | 3,000         | 150,000 | $400K    | $250K         | $7.8M          |
| 5    | 10,000        | 500,000 | $1.2M    | $800K         | $24M           |

**Assumptions:**

* Average $120/month per organization
* Protocol fees average 0.5% on $500K/month network volume by Year 5
* Conservative adoption rate (20% annual churn)
* Premium services and modules not included

**Optimistic Scenario:** 2-3x these numbers if network effects accelerate adoption.

#### 7.3 Why This Model Works

**Immediate Revenue**

* SaaS subscriptions from day one
* Not dependent on token speculation
* Predictable, recurring revenue

**Aligned Incentives**

* Protocol fees only matter when users succeed (move real resources)
* Higher tier subscriptions reflect higher value received
* Premium modules address specific needs (not forced upgrades)

**Network Effects**

* More Holons = more value to each Holon = higher tier subscriptions
* More users = more module demand = marketplace growth
* More coordination = more protocol fees = more token value

**Not Token-Dependent**

* Business viable even if protocol tokens don't achieve high market value
* Revenue from actual value delivery, not speculation
* Sustainable even in crypto bear markets

**Regenerative Model**

* Protocol fees shared with token holders
* Success feeds back to community
* Early contributors benefit from long-term value creation

#### 7.4 Unit Economics

**Customer Acquisition Cost (CAC):** $500-1,000

* Content marketing
* Community building
* Pilot programs
* Word of mouth (later)

**Lifetime Value (LTV):** $3,000-10,000

* Average 2-5 year retention
* Upsells to higher tiers
* Premium modules
* Protocol fees accumulation

**LTV:CAC Ratio:** 3:1 to 10:1 (strong economics)

**Payback Period:** 6-12 months

#### 7.5 Go-to-Market Strategy

**Phase 1: Anchor Deployments** (Months 1-12)

**Strategy:** Deploy with 3-5 regenerative communities as design partners

**Activities:**

* Deep engagement, co-creation approach
* Document learnings publicly
* Build case studies and testimonials
* Iterate rapidly on feedback
* Free or heavily discounted during pilot

**Goal:** Prove product-market fit, gather detailed feedback, create reference customers

**Phase 2: Ecosystem Expansion** (Year 2)

**Strategy:** Target Web3 communities, platform co-ops, progressive foundations

**Activities:**

* Content marketing (blog, podcasts, workshops)
* Conference presence (ReFi, DAO, cooperative summits)
* Partnership with adjacent platforms (Coordinape, Inverter)
* Community-led growth (champions program)

**Goal:** Reach 200 organizations, establish category presence

**Phase 3: Sector Penetration** (Year 3+)

**Strategy:** Scale to nonprofits, impact networks, civic infrastructure

**Activities:**

* Sales team for enterprise customers
* Integration marketplace launch
* Certification program for consultants
* Regional ambassadors for localization

**Goal:** Establish as standard coordination layer, path to profitability

***

### 8. Implementation Roadmap

#### 8.1 Phase 1: Foundation (Months 1-6) - $500K Funding

**Technical Development**

* ✅ Complete core smart contracts
  * Holon registry and identity
  * Splitter contracts (dual-mechanism)
  * Threshold flow logic
  * Value equation modules
* ✅ Security audit (Trail of Bits or similar)
* ✅ Testnet deployment (Polygon Mumbai or similar)
* ✅ Basic web interface for Holon management

**Pilot Programs**

* ✅ 3 design partner communities identified
* ✅ Weekly co-creation sessions
* ✅ Iteration cycles every 2 weeks
* ✅ Document learnings publicly

**Team**

* ✅ Hire: Lead smart contract developer
* ✅ Hire: Frontend developer
* ✅ Hire: Community coordinator
* ✅ Establish: Legal entity and compliance framework

**Milestones:**

* Smart contracts audited and deployed on testnet
* 3 pilot communities using the system
* $10K+ in resources coordinated through platform
* Validated product-market fit with qualitative evidence

#### 8.2 Phase 2: Growth (Months 6-18) - $750K Additional Funding

**Technical Development**

* ✅ Mainnet deployment
* ✅ Mobile app for contribution tracking
* ✅ Integration with Inverter Protocol
* ✅ Template library (co-op, project, community, DAO)
* ✅ Analytics dashboard
* ✅ Federation features (cross-Holon coordination)

**Market Expansion**

* ✅ 50 organizations onboarded
* ✅ 10,000 users coordinating resources
* ✅ $500K+ in resources flowing through system
* ✅ Case studies and documentation published

**Team Growth**

* ✅ Hire: Backend engineer
* ✅ Hire: UX/UI designer
* ✅ Hire: Content marketer
* ✅ Hire: Customer success lead
* ✅ Engage: Legal/compliance counsel

**Revenue**

* ✅ First paying customers (Professional tier)
* ✅ $5K+ MRR by Month 18
* ✅ Clear path to profitability defined

**Milestones:**

* 50 organizations actively using platform
* $500K+ coordinated resources
* $5K MRR from subscriptions
* Strong qualitative validation (testimonials, case studies)

#### 8.3 Phase 3: Scale (Months 18-36) - $1.5M Additional Funding

**Technical Development**

* ✅ Commitment-outcome system fully deployed
* ✅ Advanced analytics and forecasting
* ✅ Module marketplace launch
* ✅ API for third-party integrations
* ✅ Multi-chain support

**Market Penetration**

* ✅ 500 organizations
* ✅ 100,000 users
* ✅ $10M+ coordinated resources
* ✅ Geographic expansion (Europe, Asia, Latin America)

**Team Scaling**

* ✅ 15-20 person team
* ✅ Regional community managers
* ✅ Sales team for enterprise
* ✅ Developer relations

**Revenue**

* ✅ $125K+ MRR
* ✅ $1.5M+ ARR
* ✅ Path to profitability clear
* ✅ Series A positioning established

**Milestones:**

* Category leadership established
* Strong network effects visible
* Path to $10M ARR clear
* International presence

#### 8.4 Phase 4: Leadership (Year 3-5)

**Vision:**

* 10,000+ organizations
* 500,000+ users
* $1B+ coordinated resources annually
* Standard coordination layer for regenerative economies
* Self-sustaining ecosystem of module creators
* Profitable, sustainable business

***

### 9. Risks & Mitigation

#### 9.1 Adoption Challenge (Chicken-Egg Problem)

**Risk:** Networks need critical mass to provide value, but reaching critical mass requires initial adopters.

**Severity:** High

**Mitigation:**

* **Anchor deployments** with existing communities (regenerative villages, established co-ops) that have critical mass internally
* **Design for immediate value** even at small scale—single-Holon utility must be compelling standalone
* **Federation benefits kick in gradually** as networks grow, not as requirement for initial value
* **Free tier** reduces barrier to experimentation
* **Templates** provide quick-start value without configuration burden

**Status:** Pilot partners identified, freemium model designed

#### 9.2 The Bootstrapping Paradox

**Risk:** Building coordination infrastructure requires sustained effort, but contributors need resources to survive during development.

**Severity:** High (existential for team)

**Reality:** This is the exact problem Holonic Funding solves—but we face it ourselves in building the solution. The team experiences firsthand the tension between "we need money to live" and "we're building a system that transcends money dependency."

**Mitigation:**

* **Hybrid approach:** Use traditional funding (grants, investment) to bootstrap, while practicing Holonic principles internally
* **Sweat equity tracking from day one:** Even without full system deployment, track all contributions to honor early builders when resources flow
* **Transparent agreements:** Clear terms about how early contributors benefit as the system succeeds
* **Staged value capture:** Design multiple inflection points where contributors can realize value (not just waiting for "exit")
* **Community investment:** Engage regenerative finance community members who understand long-term systemic value

**This risk is also validation:** If we can't solve our own coordination challenges, the system isn't ready for others. The struggle makes us better builders.

**Status:** Internal contribution tracking implemented, clear agreements with team members

#### 9.3 Paradigm Resistance

**Risk:** The system requires users to think differently about value—not everyone will make this shift easily.

**Severity:** Medium

**The Challenge:** Most people are trained to think: "I have an empty room → I need cash → I must charge market rate." Holonic Funding asks them to think: "I have an empty room → This person creates value for the network → Network membership has value → Resource exchange makes sense."

**Mitigation:**

* **Start with values-aligned communities** (regenerative villages, co-ops) already questioning current systems
* **Demonstrate immediate tangible benefits** (resource access, reduced overhead, better coordination)
* **Make monetary benefits clear** when they exist (reduce costs, increase coordination efficiency, attract funding)
* **Progressive onboarding:** Start simple (Phase 1), add complexity as understanding deepens (Phases 2-3)
* **Champion/ambassador program** to model the shift for others
* **Success stories** showing concrete results, not just theory

**Key Insight:** This isn't a bug, it's a feature. The paradigm shift is precisely what enables systemic change—but it means early adoption will be among those already questioning current systems.

**Status:** Marketing focused on early adopter communities, pilot partners values-aligned

#### 9.4 Technical Complexity

**Risk:** System may be too abstract or complex for average users to configure effectively.

**Severity:** Medium

**Mitigation:**

* **Pre-built templates** for common use cases (co-op, village, DAO, project)
* **Guided setup workflows** with smart defaults
* **Professional services** for complex implementations
* **Progressive disclosure** of advanced features (simple first, complexity optional)
* **Community-created modules** means specialists can build for specific needs
* **Documentation and training** materials for different user types

**Status:** Template library designed, UX principles established, professional services model planned

#### 9.5 Regulatory Uncertainty

**Risk:** Resource coordination and flow automation may face regulatory scrutiny depending on jurisdiction and resource types.

**Severity:** Medium to High (varies by jurisdiction)

**Mitigation:**

* **Conservative legal structure** establishment from day one
* **Engage regulatory advisors** early (crypto, securities, money transmission)
* **Design for compliance** (KYC/AML where required, reporting capabilities)
* **Geographic phasing** based on regulatory clarity (start in favorable jurisdictions)
* **Resource separation** (different rules for money vs physical resources)
* **Clear disclosures** about legal status and limitations

**Specific Concerns:**

* **Security token classification:** Fixed allocation model avoids this, but need legal opinion
* **Money transmission:** May need licenses in some jurisdictions for monetary flows
* **Tax implications:** Resource exchange may have tax consequences users need to understand

**Status:** Legal entity formation in progress, regulatory counsel engaged, compliance framework being designed

#### 9.6 Web3 Skepticism

**Risk:** Association with Web3/crypto may deter mainstream community adoption.

**Severity:** Low to Medium

**Mitigation:**

* **Emphasize real coordination benefits** over blockchain features in marketing
* **Abstract technical complexity** from user experience (they don't need to know it's blockchain)
* **Target communities already aligned** with decentralization values
* **Demonstrate tangible outcomes** through pilot programs (show, don't tell)
* **Avoid crypto jargon** in user-facing materials
* **Focus on impact:** "coordinate resources fairly" not "decentralized autonomous organizations"

**Status:** Messaging strategy focused on outcomes, not technology

#### 9.7 Network Effects Timing

**Risk:** Value increases with network size, but building network takes time—users may leave before network effects materialize.

**Severity:** Medium

**Mitigation:**

* **Immediate single-Holon value** (doesn't require network to be useful)
* **Quick wins** in first 30 days of use
* **Regular value delivery** (monthly distributions, visible contributions, etc.)
* **Community building** around shared values (retention through culture, not just features)
* **Freemium model** reduces cost of waiting for network effects

**Status:** Product designed for immediate value, community strategy in development

#### 9.8 Smart Contract Risk

**Risk:** Bugs or vulnerabilities in smart contracts could result in loss of funds or system failure.

**Severity:** High (catastrophic if realized)

**Mitigation:**

* **Professional security audit** by reputable firm (Trail of Bits, OpenZeppelin, etc.)
* **Formal verification** of critical contract logic
* **Bug bounty program** for community security researchers
* **Gradual rollout** starting with small amounts at risk
* **Insurance** for smart contract coverage (Nexus Mutual, Unslashed, etc.)
* **Upgradeability** through proxy patterns (balanced with decentralization)
* **Emergency pause functionality** for critical situations

**Status:** Security audit budgeted and planned, best practices research completed

***

### 10. Team & Governance

#### 10.1 Current Team

**Roberto Valenti** - Founder & System Architect

* Developer of Holons System and Liminal Village founder
* 10+ years experience in systems thinking and coordination technology
* Deep expertise in holonic principles and distributed systems
* Living the problems we're solving (validation through experience)

**Simon Q** - Ambassador & Partnerships

* Building relationships with regenerative communities and funders
* Storytelling and strategic communication
* Partnership development and network weaving
* Experienced coordinator in regenerative spaces

\[Additional team members to be added based on your actual team]

#### 10.2 Roles to Fill (Seed Funding)

**Lead Smart Contract Developer**

* Complete core contracts and primitives
* Security best practices
* Gas optimization
* Solidity expert

**Frontend Developer**

* Web application for Holon management
* React/Next.js experience
* Web3 integration (wagmi, viem)
* UX sensibility

**Backend Engineer**

* API development
* Database design
* Integration management
* Scalability focus

**Community Coordinator**

* Pilot program management
* User onboarding and support
* Feedback synthesis
* Documentation

**UX/UI Designer**

* Make complexity navigable
* Template design
* User flows
* Visual identity

#### 10.3 Advisory Board (To Be Established)

**Technical Advisors**

* Smart contract security expert
* Distributed systems architect
* Tokenomics specialist

**Domain Advisors**

* Regenerative economics practitioner
* Platform cooperative leader
* DAO governance expert
* Impact measurement specialist

**Business Advisors**

* Web3 go-to-market strategist
* SaaS business model expert
* Legal/compliance counsel

#### 10.4 Governance Structure

**Current Stage: Founders Lead**

* Clear decision-making for speed
* Transparent communication of decisions
* Open feedback loops with community
* Benevolent dictatorship while building

**Post-Launch: Progressive Decentralization**

* Protocol governance through token holders
* Operational autonomy for team
* Community input on strategic decisions
* Clear separation: protocol layer (decentralized) vs. business layer (centralized)

**Long-term Vision: Protocol Commons**

* Core protocol governed by token holders
* Business operates as protocol participant
* Multiple organizations building on protocol
* Commons-based governance for shared infrastructure

***

### 11. Investment Opportunity

#### 11.1 Current Funding Need: $750K - $1.5M Seed Round

**Use of Funds:**

**Technical Development (45% - $340K-675K)**

* Smart contract development and optimization
* Security audits (2 firms for critical components)
* Frontend and backend development
* Integration with existing protocols
* Mobile app development

**Pilot Deployments (20% - $150K-300K)**

* 3-5 design partner engagements
* Integration assistance and customization
* Weekly co-creation sessions
* Iteration resources
* Success measurement and documentation

**Team (25% - $190K-375K)**

* 3-5 core team members (developers, designer, community coordinator)
* Competitive salaries for crypto/Web3 talent
* Benefits and contractor support
* Advisor compensation

**Operations & Legal (10% - $75K-150K)**

* Entity formation and legal structure
* Regulatory compliance (securities, money transmission)
* Accounting and financial systems
* Insurance (liability, smart contract)
* General operations

#### 11.2 Milestones This Funding Enables (12-18 Months)

**Technical:**

* ✅ Audited smart contract suite deployed on mainnet
* ✅ Production-ready web application
* ✅ Mobile app for contribution tracking
* ✅ Integration with key protocols (Inverter, etc.)
* ✅ Template library for common use cases

**Traction:**

* ✅ 50-100 active organizations using the platform
* ✅ 5,000-10,000 users coordinating resources
* ✅ $500K-1M in resources coordinated through system
* ✅ Clear product-market fit validation

**Business:**

* ✅ First paying customers (Professional tier)
* ✅ $5K-10K MRR from subscriptions
* ✅ Validated pricing and business model
* ✅ Clear path to profitability established
* ✅ Series A positioning (metrics, narrative, investors engaged)

**Community:**

* ✅ Case studies and testimonials published
* ✅ Active community of practitioners
* ✅ Developer ecosystem emerging
* ✅ Thought leadership established in space

#### 11.3 Path to Profitability

**Revenue Trajectory:**

* Month 6: First paying customers ($1K MRR)
* Month 12: Early traction ($5K MRR)
* Month 18: Growth validation ($10K MRR)
* Month 24: Scale beginning ($25K MRR)
* Month 36: Profitability threshold ($100K MRR)

**Unit Economics:**

* Customer acquisition improving as word-of-mouth grows
* Lifetime value increasing as federation network effects kick in
* Margins improving as platform scales
* Protocol fees becoming meaningful at scale

**Profitability Timeline:** 36-48 months with this funding level

#### 11.4 Series A Positioning (18-24 Months)

**Metrics for Series A:**

* 500-1,000 organizations
* 50,000-100,000 users
* $50K-100K MRR
* Strong retention (>90% annual)
* Clear network effects (federation growth)
* Category leadership established

**Series A Use:**

* Scale go-to-market (sales team, marketing)
* International expansion
* Advanced features (commitment-outcome, analytics)
* Module marketplace launch
* Team scale to 15-20 people

**Series A Size:** $3M-5M

#### 11.5 Investor Value Proposition

**For Impact Investors:**

* **Systemic leverage:** Infrastructure enables regenerative coordination at scale
* **Theory of change:** Make commons-based resource coordination practical
* **Measurable impact:** Resources coordinated, communities empowered, carbon reduced
* **Aligned values:** Not extractive, regenerative by design

**For Web3 Investors:**

* **First-mover advantage:** No comparable relational funding infrastructure
* **Network effects:** Value compounds as more Holons join
* **Platform economics:** SaaS + protocol fees + marketplace = multiple revenue streams
* **Defensibility:** Deep coordination expertise + community + technical complexity
* **Market timing:** DAO fatigue creates opening for better coordination tools

**For Strategic Investors:**

* **Platform leverage:** Build on our infrastructure (Inverter, Gnosis, etc.)
* **Ecosystem growth:** More coordination tools = more Web3 adoption
* **Mission alignment:** Share vision for regenerative, decentralized economies
* **Early positioning:** Ground floor of new coordination paradigm

**For Financial Investors:**

* **Large TAM:** $50B+ in resources needing coordination infrastructure
* **Strong unit economics:** 3:1+ LTV:CAC, 6-12 month payback
* **Clear path to profitability:** 36-48 months
* **Multiple exit paths:** Strategic acquisition, public markets (long-term), sustainability as profitable business
* **Reasonable valuation:** Seed stage with clear milestones

#### 11.6 Investment Terms

**Structure:** SAFE or Priced Round (flexible based on investor preference)

**Valuation:** $3M-5M pre-money (negotiable based on investor value-add)

**Use of Funds:** As detailed above (45% tech, 20% pilots, 25% team, 10% ops)

**Investor Rights:**

* Board observer seat (lead investor)
* Information rights
* Pro-rata rights for future rounds
* Standard protective provisions

**Token Allocation (if applicable):**

* Team: 25%
* Early contributors: 10%
* Investors: 20%
* Community/Ecosystem: 30%
* Foundation/Treasury: 15%

(Subject to tokenomics design and legal structure)

#### 11.7 What We're Looking For in Partners

**Essential:**

* **Mission alignment:** Understand and value regenerative, commons-based coordination
* **Patience:** This is infrastructure—network effects take time
* **Strategic value:** Connections to pilot communities, Web3 ecosystem, or regulatory expertise
* **Long-term thinking:** 5-10 year horizon, not 2-year flip

**Ideal:**

* Experience with Web3 infrastructure investments
* Connections to regenerative finance community
* Understanding of DAO/cooperative governance
* Hands-on support (not just capital)

**Deal-breakers:**

* Expectation of quick exit
* Push for extractive business model
* Misalignment with values (purely financial motivation)
* Unrealistic timeline pressure

#### 11.8 Current Status & Momentum

**Funding Status:**

* Seeking lead investor for $750K-1.5M seed round
* Interest from \[X regenerative funds] and \[Y Web3 investors]
* In conversation with \[Z strategic partners]

**Timeline:**

* Target close: \[Q1/Q2 2025]
* Start development immediately upon funding
* Pilot programs launch: \[3-6 months post-funding]
* Series A raise: \[18-24 months post-funding]

***

### 12. Conclusion

#### 12.1 The Opportunity

We stand at a unique moment in history:

* **Web3 infrastructure** is mature enough to support complex coordination
* **DAO experiments** have revealed what doesn't work, creating demand for alternatives
* **Climate crisis** makes regenerative coordination urgent
* **Deglobalization** increases importance of local economic networks
* **Coordination failure** is increasingly recognized as the bottleneck for collective action

**Holonic Funding provides the missing infrastructure layer for this transition.**

#### 12.2 What We're Building

Not a product. Not a tool. **An economic operating system for the next era of coordination.**

A system where:

* Communities coordinate resources fluidly across organizational boundaries
* Value creation is visible and fairly rewarded, even when non-monetary
* Trust builds through transparent contribution and delivery
* Autonomy is preserved while enabling powerful collective action
* Relationships become economically meaningful
* Resource flows follow value, not just financial circuits

#### 12.3 Why We Can Win

**1. Deep Understanding**

We're not theorizing about coordination problems—we're living them. The tension in our own team validates the problem while informing our solution. Our struggle is our competitive advantage.

**2. Technical Innovation**

No existing system provides relational funding logic with modular flow control. We've designed and simulated the architecture. We know it works.

**3. Values Alignment**

Our target markets share our vision. We're building for communities we're part of. This creates authentic relationships and natural network growth.

**4. First-Mover Advantage**

Category is emerging but undefined. We can establish the standard for holonic coordination infrastructure.

**5. Network Effects**

Each new Holon makes the network more valuable to all participants. Federation creates compounding returns.

**6. Practical Path**

We're not waiting for utopia. Phase 1 provides immediate value. Phase 2 adds sophistication. Phase 3 delivers the full vision. Each phase stands alone.

#### 12.4 What Success Looks Like

**3 Years:**

* 1,000 organizations coordinating resources through Holonic Funding
* $10M+ in resources flowing fairly and transparently
* Category leadership established
* Profitable, sustainable business
* Strong community of practitioners

**5 Years:**

* 10,000 organizations, 500,000 users
* $1B+ coordinated resources annually
* Standard infrastructure for regenerative economies
* Thriving ecosystem of module creators
* Measurable impact on carbon reduction, community resilience, economic equity

**10 Years:**

* Millions of people coordinating across thousands of networks
* Regenerative resource flows as default, not exception
* Commons-based property and shared resources normalized
* Demonstration that systemic alternatives to extractive capitalism work
* Foundation for post-capitalist coordination at scale

#### 12.5 The Vision

**To enable millions of people and thousands of ecosystems to coordinate resources, commitments, and regenerative projects across the planet—fluidly, transparently, and trustfully—through a federated web of Holons.**

This is infrastructure for:

* Bioregional regeneration
* Global commons coordination
* Post-capitalist economies
* Cooperative digital infrastructure
* Shared risk and shared value networks

**This is not incremental improvement. This is systemic transformation.**

The world is shifting from centralized organizations and extractive economics toward networks, local ecosystems, and regenerative coordination. This transition needs infrastructure. **Holonic Funding is that infrastructure.**

#### 12.6 The Ask

We're seeking mission-aligned funders who understand that coordination infrastructure is the leverage point for systemic change.

**We need:**

* $750K-1.5M in seed capital
* Strategic partners with network connections
* Patient capital for 3-5 year horizon
* Active engagement, not just passive investment

**We offer:**

* Ground-floor position in foundational infrastructure
* Influence on protocol design and governance
* Access to rapidly growing regenerative economy ecosystem
* Contribution to systemic transformation

**The future isn't predetermined. It's something we create together—when we have the infrastructure to coordinate our intelligence, our stories, our decisions, and our actions at the level complexity demands.**

**Join us in building that infrastructure.**

***

### Contact

**For detailed pitch deck, technical specifications, pilot program discussions, or investment conversations:**

\[Contact Information]

***

### Appendices

#### Appendix A: Technical Specifications

\[Link to detailed smart contract documentation]

#### Appendix B: Simulation Results

\[Link to threshold flow funding analysis]

#### Appendix C: Pilot Partner Profiles

\[Descriptions of design partner communities]

#### Appendix D: Financial Model

\[Link to detailed revenue projections and unit economics]

#### Appendix E: Competitive Analysis

\[Detailed comparison with adjacent tools]

#### Appendix F: Legal & Compliance Framework

\[Regulatory analysis and compliance approach]

#### Appendix G: Glossary

* **Holon:** An autonomous unit that is simultaneously a whole and a part of larger wholes
* **Federation:** Network of Holons with trust relationships and shared resource pools
* **Value Equation:** Formula defining how contributions translate to resource allocation
* **Commitment:** Published promise of future delivery
* **Relational Zone:** Bilateral economic relationship between two Holons
* **Threshold:** Resource level that triggers overflow or distribution
* **Epoch:** Time period for contribution accounting and distribution

***

**End of Whitepaper**

*Version 1.0 - November 2024*

*This whitepaper is a living document. For the latest version and updates, visit: \[website]*


# The Holonic Earth Operating System (THEOS)

A novel social coordination protocol beyond blockchains and scarcity economics

**THEOS — The Holonic Earth Operating System** — is an open-source proposal for a novel social coordination protocol that moves beyond blockchains and conventional scarcity economics to create a coherent behavioural system for humanity, aligned with planetary boundaries.

The canonical introduction and living specification live at [theos.io](https://theos.io) and [docs.theos.io](https://docs.theos.io). This page is a faithful summary of that proposal; it is *not* an extension of it. The Liminal Village software described elsewhere in these docs ([Harvest](/software/harvest-dashboard), [HolonsBot](/software/holonsbot), [HoloSphere](/software/holosphere), the [Core](/software/core) domains) is one concrete *implementation path* for the protocol, not the protocol itself.

## The opportunity

Under the prevailing economy, human civilisation has achieved the height of its industrial and technological success. Yet increasing inequality, environmental degradation, and the climate crisis are forcing the question of whether the paradigm is serving people and the planet.

THEOS observes that with the advent of the internet, and with the latest advances in AI, complexity science, and distributed-systems technology, we now have the opportunity to create **novel protocol-based social coordination systems**. Widespread transition to a new paradigm no longer requires conventional political transformation; it can proceed by people **opting in** to a digital social-economic network when they are ready.

> The need for elected human representatives and centralised institutions is replaced with **consent-based protocols** which define how we conduct our relationships with one another and our environment.

## The four objectives

THEOS outlines a **holonic, peer-to-peer social coordination protocol** whose core rules are designed to emergently fulfil four objectives:

1. **Facilitate prosocial coordination** — favouring co-creation and collaboration over competition.
2. **Fulfil psycho-physiological needs** — ensuring wellbeing for all humans.
3. **Regenerate the planetary resource ecology** — attaining widespread abundance.
4. **Remain viable across locations and through time** — respecting the local and global boundary conditions of place and planet.

These objectives are not bolted on top of an existing economic system. They are baked into the protocol's "DNA"—the set of core rules from which collective social and economic behaviour emerges.

THEOS adopts a **tabula rasa approach**: starting from a clean set of fundamental assumptions about our relationship with the world, rather than reinventing the prevailing macroeconomic system.

## Key concepts

### The food web

The foundational metaphor. Earth's ecosystems form a deeply interconnected web in which species of all kinds consume and nourish one another. The human "economy" is an extension of this food web—a system for social coordination around resources to fulfil human psycho-physiological needs.

Starting from this premise reframes economics as ecology rather than as a self-contained domain of monetary exchange.

### The resource ecology

When producers organise to satisfy requests, they combine resources and labour into **recipes**—relations between products and their constituent components, in specified physical units. Recipes chain together into a graph called the **resource ecology**: every node is a unique type of resource; every edge is a transformation from constituents to product.

The resource ecology can be likened to a **transparent, shared web of supply chains** in which every resource is geo-localised. By shifting from a concealed collection of abstract, linear supply chains to a transparent geo-localised resource graph, local providers can fill gaps and optimise long supply pathways. The resource ecology **harmonises the efficiencies of globalisation with the resilience of localisation**.

### Resource-based economy

Market-based pricing is replaced with **resource-based prices**. The value of any resource equals the sum of the values of its constituent resources, cascading through recipes until the extremities of the food web—where the value graph is rooted in the most fundamental physical units, **energy and human time**.

Because prices reflect true production costs—not profit, rent, or speculation—a **fair-trade economy** becomes the default. Since resource-based prices are measured in physical units rather than dollars, **economising on price directly implies economising on resources**. Cradle-to-cradle life-cycle costs are traceable from production through end-of-life, and the needs-based incentive removes any drive to produce surplus. **Sustainability and circularity become emergent consequences of the protocol.**

### Regeneration and the primacy of the commons

In private-property or open-access systems, individuals race to exploit their desired share of resources before they miss out, degrading the resource base in the process. This is what THEOS calls the **'tragedy of open-access'** (commonly mislabeled as the 'tragedy of the commons'). The commons is in fact an ecologically viable alternative for collectively managing and allocating resources.

THEOS asserts the **primacy of the commons**:

* Private-property ownership and exchange of exclusion rights gives way to **stewardship** and **allocation rights** for managing shared common-pool resources.
* People do not individually 'own' resources—they earn rights to allocate them from the commons for a time.
* Effective stewardship is rewarded with a **regeneration incentive**, targeted at regenerating the resource commons.

Every resource maintains a **reserve** with a corresponding **reserve ratio** (the percentage withheld from its available pool). The regeneration incentive is computed from this ratio and used to encourage replenishment via natural and augmented processes—starting from the fundamental resources and the carrying capacity of the planetary base. **Resources can only be extracted to fulfil needs if the resource base has been regenerated to a sufficient level.**

### Planetary boundaries

For any system to remain viable long-term, it requires negative feedback to stay within limits. THEOS encodes those limits at the protocol level.

As the economy nears a planetary boundary for a particular resource or waste stream, the protocol **modulates its reserve ratio**. The regeneration incentive grows as the resource becomes scarce, increasing its effective price—simultaneously incentivising regeneration and disincentivising use.

Targets and boundaries are not set by central authorities. They are collectively set through a **distributed consensus mechanism**—the protocol's distributed governance of the commons. The system then automatically realigns incentives for the entire network to navigate toward or away from those targets.

> Instead of post-mortem analysis after boundaries have already been crossed, crisis can be averted by **pre-emptive collective action** well before critical limits are reached.

### The transition

The proposed protocol provides a viable path to recover from the degraded state of human economic activities by guiding it back toward prosocial coordination, regenerating abundance, and fulfilling wellbeing—while restoring harmony between people and the planet.

Crucially, the transition is **opt-in, piecewise, and non-isolating**:

* Anyone who agrees with the proposed economic rules can opt in when ready.
* No isolation from existing society is required.
* Participants trust in **fair indirect reciprocity**—everyone else who participates is bound by the same rules and rewarded in the same way for their contributions.
* Communities everywhere can nucleate alone but **merge when they are ready**; contributions across communities are **fungible**.

By coming together around a protocol rather than negotiating institution-by-institution, a coordinated transition becomes possible with much greater breadth and speed.

## Distinguishing THEOS from this documentation

This `holonsdocs` site is operated by **Liminal Village** and documents a working family of software (Harvest monorepo, HolonsBot, HoloSphere, the [Core](/software/core) domains, MCP server, AI UI) being built **in alignment with THEOS principles**. The two are related but distinct:

* **THEOS** is the proposal — the protocol design, the objectives, the conceptual architecture. It lives at [theos.io](https://theos.io) and is a collective, open-source proposal that welcomes contribution to its refinement.
* **The Holons software ecosystem** documented here is one **implementation path** that operationalises THEOS principles in working code: holons (the units), value equations (the protocol-aligned scoring), federation (the cross-holon trust graph), commons-aware resource tracking via [REA Accounting](/software/rea-accounting), and so on.

If you want the canonical protocol description, go to theos.io. If you want a working stack that puts the principles into practice today, you are already in the right place.

## Contributing to THEOS

THEOS is a **collective open-source proposal**. The documentation at [docs.theos.io](https://docs.theos.io) is a living gitbook—contribution to its definition and refinement is encouraged and welcome. The transition it proposes will not manifest in real communities without people willing to commit resources to co-create and bring this new economic paradigm to life. All [forms of capital](http://www.appleseedpermaculture.com/8-forms-of-capital/)—not only financial—are welcome.

## Sources

* [theos.io](https://theos.io) — homepage and statement of objectives
* [docs.theos.io](https://docs.theos.io) — the living gitbook proposal
* [docs.theos.io/the-proposition](https://docs.theos.io/the-proposition) — the four objectives and tabula-rasa framing
* [docs.theos.io/the-food-web](https://docs.theos.io/the-food-web), [/resource-ecology](https://docs.theos.io/resource-ecology), [/resource-based-economy](https://docs.theos.io/resource-based-economy), [/regeneration](https://docs.theos.io/regeneration), [/planetary-boundaries](https://docs.theos.io/planetary-boundaries), [/the-transition](https://docs.theos.io/the-transition) — the core concept pages summarized above

## See also

* [What is a Holon?](/getting-started/what-is-a-holon) — how holons operationalize the protocol
* [Funding Flow](/getting-started/funding-flow) — the economic-layer mechanics used by the working implementation
* [Glossary](/getting-started/glossary) — vocabulary used across these docs


# The Shared Core

The shared domain layer that every Holons interface calls into

**`@holons/core`** is the heart of the Holons codebase. It owns every piece of domain logic—scoring, tasks, council, DNA, federation, expenses, calendar, users, library, checklists, REA, settings, categories, commands—and exposes them as independently-callable modules. Every interface in [Harvest](/software/harvest-dashboard) (web, Telegram, CLI, AI, MCP) calls these modules. They do not duplicate the logic; they consume it.

This page is the architectural overview. For domain detail, jump to the individual pages.

## What "shared core" means in practice

> One source of truth for Holons domain logic, several UIs sharing it.

A user creating a task in Telegram and a Claude agent calling the MCP `task_create` tool reach the **same function**: `createDefaultTask` in `packages/core/src/tasks/creation.ts`. The Quest they produce lives in the **same lens** in HoloSphere. Scoring sees the **same event** when the Quest completes. Federation propagates the **same data**.

This is why "compute user score" means the same thing in every UI: there is only one implementation of it.

## Domain catalog

Each domain lives at `packages/core/src/<domain>/`, exposes its public API via `index.ts`, and is reachable from any consumer with a subpath import.

| Domain         | What it owns                                                                                                               | Page                                       |
| -------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| **tasks**      | Unified Quest model — tasks, proposals, events, offers, requests                                                           | [Tasks](/software/tasks)                   |
| **council**    | Proposal lifecycle and consent-based voting                                                                                | [Council](/software/council)               |
| **scoring**    | Value-equation evaluation; per-user / per-action / full-holon scores                                                       | [Scoring](/software/scoring)               |
| **rea**        | Resource-Event-Agent event ledger and factory                                                                              | [REA Accounting](/software/rea-accounting) |
| **dna**        | Holon chromosomes (value / tool / practice) and DNA sequences                                                              | [DNA](/software/dna)                       |
| **library**    | Shared community library — borrow / lend / deposit                                                                         | [Library](/software/library)               |
| **federation** | Cross-holon publishing via HoloSphere + Nostr                                                                              | *(no page yet)*                            |
| **holosphere** | Identity-aware reads/writes against the substrate                                                                          | [HoloSphere](/software/holosphere)         |
| **expenses**   | Shared cost logging and splitting                                                                                          | *(no page yet)*                            |
| **calendar**   | Events, recurring events, scheduling                                                                                       | *(no page yet)*                            |
| **users**      | Multi-holon membership and appreciation tracking                                                                           | *(no page yet)*                            |
| **checklists** | Recurring and role-based task lists                                                                                        | *(no page yet)*                            |
| **shopping**   | Shared shopping lists                                                                                                      | *(no page yet)*                            |
| **settings**   | Per-holon configuration with hex-grid integration                                                                          | *(no page yet)*                            |
| **categories** | Taxonomies for items and contributions                                                                                     | *(no page yet)*                            |
| **commands**   | Shared command registry used by [Text UI](/software/text-ui), [AI UI](/software/ai-ui), [MCP Server](/software/mcp-server) | *(see UI pages)*                           |

The "no page yet" entries are real, working domains; they just don't yet have dedicated docs. The MCP server exposes tools for every one of them.

## Conventions

A small set of rules keeps the core stable as it grows.

### Subpath imports — no central barrel

```ts
import { calculateUserScore } from '@holons/core/scoring';
import { createDefaultTask }  from '@holons/core/tasks';
import { saveProposal }       from '@holons/core/council';
```

There is **no** `import { everything } from '@holons/core'` barrel that re-exports every domain. The subpath form is mandatory because:

* It makes domain dependencies explicit in import lines.
* Tree-shaking works without any bundler magic.
* New domains land without touching a central re-export file.
* Two domains can have a function of the same name without colliding.

Subpath exports are configured via a wildcard in `packages/core/package.json`:

```json
"exports": {
  ".": "./src/index.ts",
  "./*": {
    "types": "./src/*/index.ts",
    "import": "./dist/*/index.js",
    "default": "./src/*/index.ts"
  }
}
```

Creating `packages/core/src/<new-domain>/index.ts` instantly makes `@holons/core/<new-domain>` importable—no configuration change needed.

### TypeScript everywhere

Core is TypeScript. New UIs are TypeScript. The Telegram bot is in a mixed JS+TS state (bootstrap and several modules migrated; the rest still JS, allowed via `allowJs`). Types are exported alongside functions:

```ts
import type { Quest, QuestParticipant } from '@holons/core/tasks';
```

### UI-agnostic

Core never imports `svelte`, `telegraf`, or any framework. Only `import type` for shared interface shapes when truly necessary. The list of allowed runtime dependencies is intentionally tiny: `holosphere`, `ical.js`. That's it.

### Pure vs. impure split

Every domain has the same internal structure:

* **Pure helpers** — functions that take data and return data. No I/O, no side effects. Used by every UI for live rendering (live tallies, live scores, live previews).
* **Impure helpers** — functions that read from or write to HoloSphere. Called when the action is committed.

This split is what lets the web dashboard show "if you complete this task, you and Laura each get 2 points" without round-tripping to storage: the same pure function runs in the browser.

### One HoloSphere factory

There is exactly one place that instantiates HoloSphere: `@holons/core/holosphere`. Every UI calls into it for identity-aware writes (`writeWithIdentity`, `canWriteToHolon`). This keeps actor resolution, write permissions, and audit attribution consistent regardless of where a call originates.

### Tests live next to the code

Every domain ships a vitest spec at `packages/core/src/<domain>/<domain>.test.ts`. Tests are not in a separate `tests/` tree. This keeps each domain self-contained and makes it obvious which test exercises which file.

## How a new domain lands

1. Create `packages/core/src/<domain>/{index.ts, types.ts, …}`.
2. Export the public surface from `index.ts`.
3. Write a vitest spec: `<domain>/<domain>.test.ts`.
4. If the domain has its own MCP tool wrappers, add `packages/mcp-ui/src/tools/<domain>.ts` and append the domain name to the `DOMAINS` array in `packages/mcp-ui/src/tools/index.ts`.

That's it. No central registration, no manifest, no per-UI plumbing. Every UI that imports from the new path automatically gets the new capability.

## How a new UI lands

1. `mkdir packages/<my-ui>/src`.
2. Copy `packages/text-ui/{package.json,tsconfig.json}` as a starting point.
3. Depend on `@holons/core` via `"@holons/core": "workspace:*"`.
4. `pnpm install` from the repo root.
5. Implement the renderer / parser / input mode against `@holons/core/commands` so the new UI invokes the same actions as the others.

The shared command registry is the single integration point a new UI needs to touch. Every existing command becomes available to the new UI for free.

## What this architecture buys

* **Consistency.** Every interface produces the same data, scores it the same way, federates the same events.
* **Speed.** A new feature is one PR, not five.
* **Independence.** Each UI can iterate on its presentation without coordinating with the others.
* **Testability.** Domain logic is exercised by vitest specs that run in milliseconds, with no UI launched.
* **AI-readiness.** Because every operation is a `CoreCommand` with declared params, exposing it as an [MCP tool](/software/mcp-server) or [Claude tool](/software/ai-ui) is a one-line wrapper.

## See also

* [Harvest](/software/harvest-dashboard) — the monorepo that contains `@holons/core` and its UIs
* [MCP Server](/software/mcp-server) — the auto-registered tool surface over the core
* Domain pages: [Tasks](/software/tasks), [Council](/software/council), [Scoring](/software/scoring), [REA Accounting](/software/rea-accounting), [DNA](/software/dna), [Library](/software/library)


# HoloSphere

The distributed substrate that every Holons UI reads from and writes to

## HoloSphere

**HoloSphere** is the storage substrate of the Holons ecosystem. It is a JavaScript library that combines [H3 geospatial indexing](https://h3geo.org) for hierarchical addressing with [GunDB](https://gun.eco) for distributed, peer-to-peer storage. Every interface in [Harvest](/software/harvest-dashboard)—the web dashboard, the Telegram bot, the CLI, the AI agent, the [MCP server](/software/mcp-server)—writes to and reads from HoloSphere. That shared substrate is what makes the system **one source of truth** despite having many user-facing surfaces.

This page is the conceptual introduction. For the full API reference, see [HoloSphere API Reference](#api-reference) below.

### The shape of the substrate

HoloSphere is organized around three concepts:

* **Holons** — units identified by an H3 cell (or, in non-geographic use, by any string ID). A holon is a folder; everything else lives inside it.
* **Lenses** — named categories of data within a holon (`tasks`, `expenses`, `rea_events`, `dna_sequence`, `proposals`, …). Each lens is independent: writing to one doesn't touch the others.
* **Items** — individual records inside a lens, each keyed by its own `id`.

```
holon (H3 cell or string ID)
├── lens "tasks"
│   ├── item "task-abc123"
│   └── item "task-def456"
├── lens "expenses"
│   └── item "expense-789"
├── lens "rea_events"
│   └── …
└── lens "dna_sequence"
    └── …
```

Every domain in `@holons/core` is the authority over one or more lenses—[Tasks](/software/tasks) owns `tasks`, [Council](/software/council) owns `proposals`, [REA Accounting](/software/rea-accounting) owns `rea_events`, and so on. HoloSphere itself is **content-agnostic**: it doesn't know what's in a lens, only how to store it, propagate it, and validate it against a schema if one is set.

### Why H3

H3 is Uber's hierarchical hexagonal geospatial indexing system. It maps any `(lat, lng)` to a hex cell at any of 16 resolutions, and provides constant-time parent/child/neighbor lookups.

HoloSphere uses H3 because:

* **Hierarchy is free.** A neighborhood holon's parent is a city holon; its children are block-level holons. No bespoke region trees.
* **Aggregation is natural.** "Roll up all environmental readings for this region" maps directly to `cellToChildren()` followed by `getAll()` on each child.
* **Neighbors are addressable.** Adjacent holons can subscribe to each other's lenses without configuring relationships individually.
* **Stable IDs.** Two clients computing the H3 index for the same `(lat, lng, resolution)` always get the same cell, so they always end up writing to the same holon.

A holon doesn't have to be geographic. A community, a project, a dataset—anything can be a holon if you give it an ID. H3 is the **default** addressing scheme, not a requirement.

### Why GunDB

GunDB is a decentralized, real-time, peer-to-peer database. HoloSphere uses it because:

* **No central server.** Holons can run on relays, on phones, on Raspberry Pis—the data finds its way.
* **Real-time by default.** Every read can subscribe; updates propagate to all peers.
* **Conflict-free for the common case.** GunDB's CRDT model handles concurrent writes without bespoke conflict resolution.
* **Offline-tolerant.** A peer that goes offline picks up missed writes when it reconnects.

The trade-off is that GunDB is eventually consistent and not transactional. HoloSphere works with this rather than around it: domains are designed so that "out-of-order writes" produce sensible end states.

### Multi-scale operations

The combination of H3 + GunDB lets HoloSphere support operations across scales naturally:

* **Localized** — query one holon, get its own data.
* **Delocalized / aggregated** — query a parent, get a roll-up across children.
* **Hybrid** — subscribe to a holon and propagate computed summaries upward (e.g., "regenerative practices reported per bioregion").

This is what makes [federation](/software/holosphere/federation) practical: a network of holons can share data along the H3 hierarchy or along explicit federation edges, with one consistent API.

### Lenses, schemas, and validation

A lens can be left untyped or constrained to a JSON Schema:

```javascript
await sphere.setSchema('temperature', {
  type: 'object',
  properties: {
    id: { type: 'string' },
    temperature: { type: 'number' },
    timestamp: { type: 'number' },
  },
  required: ['id', 'temperature', 'timestamp'],
});
```

In **strict mode**, writes that violate the schema are rejected at the substrate layer. This is what lets domains evolve independently without stepping on each other—the `tasks` schema doesn't know or care what shape `expenses` is.

Lenses without a schema accept arbitrary JSON. This is the **default**, and is appropriate for most domain data, which is typed at the `@holons/core` layer instead.

### Identity-aware writes

In the Holons monorepo, raw HoloSphere puts and gets are wrapped by the **identity-aware layer** in `@holons/core/holosphere`:

* `writeWithIdentity(holonId, lens, item, actor)` — attaches the writing actor to the record, used for attribution in scoring and federation.
* `canWriteToHolon(holonId, actor)` — checks whether an actor has standing to write to a holon (e.g., is a member, is in the right zone).

The MCP server and AI UI both resolve their actor through this layer, so every write is attributable regardless of which interface emitted it.

### Federation

Federation is the system that lets two HoloSphere spaces share data while keeping a single source of truth. A space adds another to its **federation list**; the other space adds the first to its **notify list**. Reads on federated lenses resolve transparently across the relationship.

Federation supports **soul references** (lightweight pointers) by default, so propagating data between spaces doesn't duplicate storage—the original lives in one space, and the federated copy resolves to it on read.

For the full federation model, see [Federation](/software/holosphere/federation).

### Installation

```bash
npm install holosphere
```

```javascript
import HoloSphere from 'holosphere';

const sphere = new HoloSphere('my-app');
const holon = await sphere.getHolon(40.7128, -74.0060, 7); // NYC at resolution 7

await sphere.put(holon, 'observations', {
  id: 'obs-001',
  temperature: 22.5,
  timestamp: Date.now(),
});
```

In a Holons monorepo deployment, you don't usually instantiate HoloSphere yourself—`@holons/core/holosphere` provides a factory that every UI shares, configured by `HOLONS_PEER` and `HOLONS_APP` env vars (see [MCP Server](/software/mcp-server#holosphere-connection)).

### See also

* [Federation](/software/holosphere/federation) — cross-space data sharing
* [Harvest](/software/harvest-dashboard) — the monorepo whose interfaces all share one HoloSphere namespace
* [MCP Server](/software/mcp-server) — the MCP layer that exposes the substrate to external agents

***

## API Reference

The remainder of this page is the canonical API reference for the standalone HoloSphere library.

### Holonic Architecture

HoloSphere implements holonic architecture in two ways:

**1. Spatial Hierarchy**

```javascript
// Get holons at different scales for a location
const holon = await sphere.getHolon(lat, lng, 7);  // City level
const parent = h3.cellToParent(holon, 6);          // Region level
const children = h3.cellToChildren(holon, 8);       // Neighborhood level

// Get entire hierarchy
const scales = sphere.getHolonScalespace(holon);    // All containing holons
```

**2. Data Organization**

```javascript
// Store data in different aspects (lenses) of a holon
await sphere.put(holon, 'environment', {
    id: 'air-001',
    temperature: 22.5,
    humidity: 65
});

await sphere.put(holon, 'social', {
    id: 'event-001',
    type: 'gathering',
    participants: 50
});
```

### Use Cases

#### Localized structures

```javascript
async function monitorLocalAir(lat, lng) {
    const neighborhood = await sphere.getHolon(lat, lng, 9);

    await sphere.put(neighborhood, 'air-quality', {
        id: `reading-${Date.now()}`,
        pm25: 12.5,
        timestamp: Date.now()
    });

    const readings = await sphere.getAll(neighborhood, 'air-quality');
}
```

#### Delocalized structures

```javascript
async function coordinateResources(region) {
    const localities = h3.cellToChildren(region, h3.getResolution(region) + 1);

    const resources = await Promise.all(
        localities.map(async locality => {
            return sphere.getAll(locality, 'resources');
        })
    );

    await sphere.compute(region, 'resources', 'summarize');
}
```

#### Hybrid structures

```javascript
async function coordinateEmergency(incident) {
    const epicenter = await sphere.getHolon(incident.lat, incident.lng, 8);
    const region = h3.cellToParent(epicenter, 6);

    await sphere.put(epicenter, 'emergencies', {
        id: incident.id,
        type: incident.type,
        severity: incident.severity
    });

    const nearbyResources = await sphere.getAll(region, 'resources');

    sphere.subscribe(epicenter, 'emergencies', (data) => {
        updateResponsePlan(data);
    });
}
```

### Constructor

```javascript
new HoloSphere(
    appName,    // String: Namespace for your application
    strict,     // Boolean: Enable strict schema validation (default: false)
    openaikey   // String: Optional OpenAI API key for AI features
)
```

### Core methods

* `async getHolon(lat, lng, resolution)` — Get H3 index for coordinates
* `async put(holon, lens, data)` — Store data
* `async get(holon, lens, key)` — Retrieve specific data
* `async getAll(holon, lens)` — Retrieve all data
* `async delete(holon, lens, key)` — Delete specific data
* `async deleteAll(holon, lens)` — Delete all data
* `async setSchema(lens, schema)` — Set JSON schema for validation
* `async getSchema(lens)` — Get current schema
* `subscribe(holon, lens, callback)` — Listen for changes

### Data validation

```javascript
const sphere = new HoloSphere('validated-data', true);

const measurementSchema = {
    type: 'object',
    properties: {
        id: { type: 'string' },
        value: { type: 'number' },
        unit: { type: 'string' },
        accuracy: { type: 'number' },
        timestamp: { type: 'number' }
    },
    required: ['id', 'value', 'unit'],
    additionalProperties: false
};

await sphere.setSchema('measurements', measurementSchema);
```

In strict mode, writes that don't match the schema are rejected.

### Federation API

#### `federate(spaceId1, spaceId2, password1, password2, bidirectional)`

Creates a federation relationship between two spaces.

```javascript
await holosphere.federate('space1', 'space2', 'pass1', 'pass2');
```

This sets up:

* `space1.federation` includes `space2`
* `space2.notify` includes `space1`

#### `propagate(holon, lens, data, options)`

Propagates data to federated spaces.

```javascript
await holosphere.propagate('space1', 'items', data, {
  useReferences: true,         // default: uses soul references
  targetSpaces: ['space2']     // optional: specific targets
});
```

Or use auto-propagation on every write:

```javascript
await holosphere.put('space1', 'items', data, null, {
  autoPropagate: true,
});
```

#### Soul references

When using the default `useReferences: true`:

1. Only a lightweight reference is stored in the federated space.
2. The reference contains the original item's ID and soul path.
3. On access, the reference is resolved to the original data.
4. Changes to the original are immediately visible through references.

Single source of truth, no storage duplication.

#### Federation structure

```javascript
{
    id: string,
    name: string,
    federation: string[],  // Source spaces this holon federates with
    notify: string[],      // Target spaces to notify of changes
    timestamp: number
}
```

#### Message federation

```javascript
// Track a federated message across chats
await holosphere.federateMessage('chat1', 'msg1', 'chat2', 'msg2', 'quest');

// Look up all federated copies
const messages = await holosphere.getFederatedMessages('chat1', 'msg1');

// Update across all federated chats
await holosphere.updateFederatedMessages('chat1', 'msg1', async (chatId, messageId) => {
    await updateMessageInChat(chatId, messageId);
});
```

### Dependencies

* `h3-js` — Uber's H3 geospatial indexing
* `gun` — Decentralized database
* `ajv` — JSON Schema validation
* `openai` — AI capabilities (optional)

### License

GPL-3.0-or-later


# Federation

## HoloSphere Federation

HoloSphere's federation system allows different holons (spaces) to share and access data from each other. Federation creates a relationship between spaces that enables data propagation and cross-space access.

### Key Concepts

* **Federation Relationship**: A connection between two spaces that allows data to flow between them.
* **Soul References**: Lightweight references that point to data in its original location (single source of truth).
* **Notification Flow**: Data notifications flow from source spaces to target spaces that are in the notify list.
* **Source-Target Relationship**: Each federation sets up a source space (federation list) and a target space (notify list).

### Federation Data Flow

The HoloSphere federation system works with a clear source-target relationship:

1. **Federation List**: When space A federates with space B, space A adds B to its federation list.
2. **Notify List**: Space B adds space A to its notify list.
3. **Data Flow**: When space A changes, space B gets notified (but not vice versa unless bidirectional).

### Creating Federation

Create federation relationships between spaces:

```javascript
// Create federation between space1 and space2
await holoSphere.federate('space1', 'space2');

// This sets up:
// - space1.federation includes space2
// - space2.notify includes space1
```

The bidirectional parameter is largely unused in the current implementation since the federation system naturally sets up the correct notification flow. The default relationship allows space2 to be notified of changes in space1.

### Storing and Propagating Data

Data must be explicitly propagated to federated spaces:

```javascript
const data = {
  id: 'item1',
  title: 'Federation Example',
  value: 42
};

// Store data in space1
await holoSphere.put('space1', 'items', data);

// Propagate to federated spaces
await holoSphere.propagate('space1', 'items', data);
```

You can also enable automatic propagation in the `put()` method:

```javascript
// Store data and automatically propagate
await holoSphere.put('space1', 'items', data, null, {
  autoPropagate: true
});
```

### Accessing Federated Data

#### Direct Retrieval

You can access data directly from any space:

```javascript
// Retrieve data from space2 (will resolve reference if it's a reference)
const data = await holoSphere.get('space2', 'items', 'item1', null, {
  resolveReferences: true  // Default is true
});
```

#### Aggregate Federated Data

Use `getFederated()` to get data from multiple federated spaces:

```javascript
// Get combined data from the local space and all its federated spaces
const federatedData = await holoSphere.getFederated('space2', 'items', {
  resolveReferences: true,  // Default: true
  idField: 'id'             // Field to use as the unique identifier
});
```

### Soul References

HoloSphere uses a simplified reference system based on soul paths:

1. A reference contains only an `id` and a `soul` property
2. The soul path is in the format: `appname/holon/lens/key`
3. When resolving a reference, HoloSphere follows the soul path to retrieve the original data

By default, federation propagation uses references instead of duplicating data. This can be controlled:

```javascript
// Propagate with full data copy instead of references
await holoSphere.propagate('space1', 'items', data, {
  useReferences: false
});
```

### Removing Federation

```javascript
// Remove federation relationship
await holoSphere.unfederate('space1', 'space2');
```

### Complete Example

Here's a complete example showing the proper way to set up and use federation:

```javascript
import HoloSphere from './holosphere.js';

async function federationExample() {
  const holoSphere = new HoloSphere('example-app');
  
  try {
    const space1 = 'public-space1';
    const space2 = 'public-space2';
    
    // Step 1: Create federation relationship
    await holoSphere.federate(space1, space2);
    
    // Step 2: Verify federation is set up properly
    const fedInfo1 = await holoSphere.getFederation(space1);
    const fedInfo2 = await holoSphere.getFederation(space2);
    
    console.log(`Federation info for ${space1}:`, fedInfo1);
    // Should include: federation: ['space2']
    
    console.log(`Federation info for ${space2}:`, fedInfo2);
    // Should include: notify: ['space1']
    
    // Step 3: Store data in space1
    const item = { 
      id: 'item1', 
      title: 'Federation Test', 
      value: 42 
    };
    
    await holoSphere.put(space1, 'items', item);
    
    // Step 4: Propagate data to federated spaces
    await holoSphere.propagate(space1, 'items', item);
    
    // Allow time for propagation
    await new Promise(resolve => setTimeout(resolve, 1000));
    
    // Step 5: Access data from space2 (resolves reference)
    const itemFromSpace2 = await holoSphere.get(space2, 'items', 'item1');
    console.log('Item from space2:', itemFromSpace2);
    
    // Step 6: Update item in space1
    const updatedItem = {
      ...item,
      value: 100,
      updated: true
    };
    
    await holoSphere.put(space1, 'items', updatedItem);
    
    // Since we're using soul references, the update is immediately visible
    // through the reference without needing to propagate again
    
    // Verify update is visible through the reference
    const updatedItemFromSpace2 = await holoSphere.get(space2, 'items', 'item1');
    console.log('Updated item from space2:', updatedItemFromSpace2);
    
    // Step 7: Clean up
    await holoSphere.unfederate(space1, space2);
  } finally {
    // Always close the HoloSphere instance
    await holoSphere.close();
  }
}

federationExample().catch(console.error);
```

### Troubleshooting

#### Common Issues

1. **Federation Relationship**: Make sure to check both the federation list and notify list to understand data flow.
2. **Data Propagation**: If data isn't appearing in federated spaces, check:
   * The federation relationship was created correctly
   * The data was propagated explicitly or `autoPropagate` was set to `true`
   * The notify list includes the target space
3. **Reference Resolution**: If you're getting reference objects instead of the actual data:
   * Make sure `resolveReferences` is set to `true` (it's the default)
   * Check that the original data still exists at the referenced location
4. **Timing Issues**: Data propagation is asynchronous. Add small delays (500-1000ms) between operations to allow propagation to complete.

#### Best Practices

1. **Verify Federation Structure**: After creating a federation, check both spaces to ensure:
   * Source space has the target in its federation list
   * Target space has the source in its notify list
2. **Explicit Propagation**: Unless you're using `autoPropagate`, always call `propagate()` explicitly after storing data that should be shared.
3. **Choose the Right Propagation Method**:
   * Use `useReferences: true` (default) to keep a single source of truth
   * Use `useReferences: false` only when you need independent copies
4. **Cleanup**: Always close the HoloSphere instance when done to prevent resource leaks.


# Harvest 🌱

The Holons monorepo — one shared core, five interfaces

**Harvest** is the unified codebase of the Holons ecosystem. It is a [pnpm](https://pnpm.io) monorepo containing one shared core (`@holons/core`) and a family of interfaces that all call into it. Every action—create a task, vote on a proposal, log an expense, publish to federation—means the same thing in every interface, because every interface invokes the same core function.

What was once "the Harvest dashboard" is now `apps/web` inside this monorepo. The Telegram bot, CLI, AI agent loop, and [MCP server](/software/mcp-server) live alongside it as sibling packages.

## Architecture

```
         ┌────────────────────────────────────────────────────────┐
         │                    @holons/core                        │
         │  scoring · tasks · federation · holosphere · shopping  │
         │  settings · dna · users · expenses · calendar · library│
         │  checklists · council · categories · commands · REA    │
         └────────────────────────────────────────────────────────┘
            ▲          ▲          ▲          ▲           ▲
            │          │          │          │           │
       ┌────────┐ ┌─────────┐ ┌────────┐ ┌────────┐ ┌─────────┐
       │harvest-│ │telegram-│ │text-ui │ │ai-ui   │ │mcp-ui   │
       │  web   │ │   ui    │ │ (CLI)  │ │(Claude)│ │(MCP srv)│
       └────────┘ └─────────┘ └────────┘ └────────┘ └─────────┘
                              │
                       ▼
              HoloSphere (GunDB + Nostr federation)
```

## Packages

| Package               | Path                    | What it owns                                                                                                                                                                    |
| --------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@holons/core`        | `packages/core/`        | UI-agnostic domain logic. Scoring, tasks, federation, HoloSphere I/O, DNA, users, expenses, calendar, library, checklists, council, categories, commands, REA.                  |
| `harvest-web`         | `apps/web/`             | SvelteKit web app — Mapbox/H3 visualizations, schema-driven forms, federation UI. The "dashboard" most people mean when they say Harvest.                                       |
| `@holons/telegram-ui` | `packages/telegram-ui/` | Telegraf bot — scenes, inline keyboards, Puppeteer screenshots. The current incarnation of [HolonsBot](/software/holonsbot).                                                    |
| `@holons/text-ui`     | `packages/text-ui/`     | Framework-agnostic CLI / REPL. Calls `@holons/core/commands`.                                                                                                                   |
| `@holons/ai-ui`       | `packages/ai-ui/`       | In-process Claude tool-use loop. Exposes `@holons/core/commands` directly as Claude tools so an agent can drive a holon in natural language.                                    |
| `@holons/mcp-ui`      | `packages/mcp-ui/`      | [MCP server](/software/mcp-server) — every public `@holons/core` function as an independently-callable MCP tool. Used by Claude Desktop, IDE integrations, and external agents. |

## The shared core

Every domain in `@holons/core` is published under a subpath export, so any UI imports just what it needs:

```ts
import { calculateUserScore } from '@holons/core/scoring';
import { createTask }         from '@holons/core/tasks';
import { publishFederation }  from '@holons/core/federation';
```

There is no cross-domain barrel — each domain stands on its own under `packages/core/src/<domain>/index.ts`. This is what keeps the five UIs in sync without coupling them.

A non-exhaustive view of the domains:

* **scoring** — value-equation evaluation, per user / per action / breakdown
* **tasks** — unified quest model (tasks, proposals, events, offers, requests)
* **council** — proposal lifecycle and consent-based voting
* **dna** — holon DNA sequences and chromosomes
* **federation** — cross-holon publishing via HoloSphere + Nostr
* **holosphere** — identity-aware reads and writes against the substrate
* **expenses** — shared cost logging and splitting
* **calendar** — events, recurring events, scheduling
* **users** — multi-holon membership and appreciation tracking
* **library** — shared resource catalog with tagging and search
* **checklists** — recurring and role-based task lists
* **rea** — Resource-Event-Agent accounting model
* **settings**, **categories**, **commands** — supporting domains

Each domain has its own vitest suite under `packages/core/src/<domain>/<domain>.test.ts`.

## The web dashboard

`apps/web` (formerly the standalone Harvest repo) is the SvelteKit visualization surface:

### Holonic network visualization 🕸️

* Interactive network graph showing holons and their relationships
* Real-time updates of holon states and connections
* Zoom and pan controls for easy navigation
* Color-coded nodes representing different holon types and states

### Holon management 🎛️

* View detailed information about individual holons
* Monitor holon health and status
* Inspect holon properties and configurations
* Track holon relationships and dependencies

### Sidebar controls 📊

* Filter holons by type or status
* Search functionality to quickly find specific holons
* Collapsible sidebar for maximizing view space
* Real-time metrics and statistics

Mapbox and H3 power the geospatial views; schema-driven forms let any lens defined in core be edited from the UI.

## Getting started

The monorepo uses pnpm workspaces. Node ≥20 and pnpm ≥10 are required.

```bash
# Clone the monorepo (or the standalone harvest-web, if a partial checkout is preferred)
git clone https://github.com/liminalvillage/harvest.git
cd harvest

# Install all workspaces with a single lockfile
pnpm install

# Typecheck and build all packages
pnpm -r typecheck
pnpm -r build
```

To run a specific UI:

| Command                                          | What it starts                                 |
| ------------------------------------------------ | ---------------------------------------------- |
| `pnpm dev`                                       | The web dashboard (`apps/web`)                 |
| `pnpm dev:bot`                                   | The Telegram bot                               |
| `pnpm -F @holons/text-ui exec holons --help`     | The CLI                                        |
| `pnpm -F @holons/ai-ui exec holons-ai "…"`       | The Claude AI loop (needs `ANTHROPIC_API_KEY`) |
| `node packages/mcp-ui/dist/index.js`             | The MCP server (stdio)                         |
| `node packages/mcp-ui/dist/index.js --port 3200` | The MCP server (SSE on HTTP)                   |

## Memory management (web dashboard)

When working with large holonic networks, memory usage can be significant due to the amount of data being processed and visualized. If you encounter "JavaScript heap out of memory" errors:

```bash
# Set Node.js memory limit to 4GB
export NODE_OPTIONS="--max-old-space-size=4096"
pnpm dev
```

For long-running production deployments, set memory limits based on your server specifications and the size of the federated network you expect to visualize.

## Adding a new shared domain

1. Create `packages/core/src/<domain>/{index.ts, …}.ts` and export from `index.ts`. Subpath exports cover it automatically via `packages/core/package.json` wildcards.
2. Add a vitest spec at `packages/core/src/<domain>/<domain>.test.ts`.
3. If the domain needs a new dep, add it to `packages/core/package.json` dependencies.

The same domain becomes available to every UI without any per-UI plumbing—and, because `@holons/mcp-ui` auto-registers tools for known domains, also becomes callable as an MCP tool with no extra work beyond writing a thin wrapper.

## Adding a new UI

1. Create `packages/<my-ui>/src/` and copy `packages/text-ui/{package.json,tsconfig.json}` as a starting point.
2. Depend on `@holons/core` via `"@holons/core": "workspace:*"`.
3. Run `pnpm install` from the repo root.
4. Implement the renderer/parser/input-mode against `@holons/core/commands` so all UIs invoke the same actions.

## See also

* [MCP Server](/software/mcp-server) — `@holons/mcp-ui` in depth
* [HolonsBot](/software/holonsbot) — the Telegram interface (`@holons/telegram-ui`)
* [HoloSphere](/software/holosphere) — the distributed substrate every package writes to
* [Glossary](/getting-started/glossary) — vocabulary for the protocol concepts the code implements


# MCP Server

Model Context Protocol server exposing the entire holonic core as callable tools

> **Status: early — `@holons/mcp-ui` is at `0.1.0`.** The tool surface and identity model are working but may evolve. Pin versions in production deployments and expect the occasional breaking change until `1.0`.

The **`@holons/mcp-ui`** package is the canonical interface between AI agents and the Holons ecosystem. It implements the [Model Context Protocol](https://modelcontextprotocol.io) and exposes every public function in `@holons/core` as an independently-callable tool. With it, a Claude (or any MCP-compatible) agent can fully participate in a holon: create tasks, vote on proposals, log expenses, calculate scores, publish to federation, manage DNA, and more—without any custom integration.

This is what makes a Claude agent a **first-class holon member** rather than an external assistant.

## What it is

* **Name:** `holons-mcp-ui`
* **Location:** `harvest/packages/mcp-ui/` in the [Harvest](/software/harvest-dashboard) monorepo
* **Replaces:** the legacy HTTP API (port 3101) and the duplicate MCP wrappers under `telegram-ui/mcp`
* **Tool count:** \~100 tools across 14 [domain modules](#tool-domains)

## Transports

The server supports two transports out of the box:

**stdio (default).** Used by Claude Desktop, IDE integrations, and any MCP client that spawns a subprocess.

```bash
node packages/mcp-ui/dist/index.js
```

**SSE over HTTP.** Used when the server needs to be reachable over the network.

```bash
node packages/mcp-ui/dist/index.js --port 3200
```

When `--port` is set, the server exposes:

| Method | Path        | Purpose                                       |
| ------ | ----------- | --------------------------------------------- |
| `GET`  | `/sse`      | Open an SSE stream for an MCP session         |
| `POST` | `/messages` | Send a client message to the open SSE session |
| `GET`  | `/`         | Health check — returns `{ name, version }`    |

## Identity model

Every tool call resolves an **actor**—the user the call is acting on behalf of. This is what makes writes attributable to a specific person (or agent) inside HoloSphere.

```ts
interface Actor {
  id: string | number;
  first_name?: string;
  username?: string;
}
```

The actor is resolved from environment variables, with per-call overrides possible:

| Variable                | Purpose        | Default   |
| ----------------------- | -------------- | --------- |
| `HOLONS_ACTOR_ID`       | Acting user ID | `mcp-ui`  |
| `HOLONS_ACTOR_NAME`     | Display name   | `MCP-UI`  |
| `HOLONS_ACTOR_USERNAME` | @handle        | *(unset)* |

For an AI agent to participate as a known person, set these to that person's identity before launching the server.

## HoloSphere connection

The server connects to the [HoloSphere](/software/holosphere) substrate using two environment variables:

| Variable      | Purpose                  | Default                     |
| ------------- | ------------------------ | --------------------------- |
| `HOLONS_PEER` | Gun relay URL            | `https://gun.holons.io/gun` |
| `HOLONS_APP`  | HoloSphere app namespace | `Holons`                    |

Every read and write—across every tool—lands in this namespace, which is also where the web dashboard, Telegram bot, and CLI write. **All interfaces share one source of truth.**

## Tool domains

Each domain module exposes one tool per public function in the corresponding `@holons/core` domain. Tools are registered automatically at startup; missing domain files are skipped silently.

| Domain       | Tools | What it does                                                                 |
| ------------ | ----- | ---------------------------------------------------------------------------- |
| `tasks`      | 10    | Create, update, plan, complete quests; manage participants and appreciation  |
| `council`    | 13    | Full proposal lifecycle — create, save, vote, tally, block, check agreement  |
| `dna`        | 12    | Holon DNA sequences and chromosomes — get, save, add, remove, validate, seed |
| `settings`   | 11    | Per-holon and per-user configuration, with hex-grid integration              |
| `library`    | 11    | Shared resource catalog — CRUD, tagging, search                              |
| `users`      | 9     | User CRUD and appreciation tracking                                          |
| `scoring`    | 9     | Value-equation evaluation — per user, per action, breakdown, full-holon      |
| `holosphere` | 8     | Direct substrate access — put, get, getAll, delete, subscribe, history       |
| `checklists` | 7     | Recurring and role-based checklist operations                                |
| `expenses`   | 6     | Log shared costs, split expenses, calculate per-member shares                |
| `shopping`   | 6     | Shopping list items shared across a holon                                    |
| `calendar`   | 5     | Events, recurring events, scheduling                                         |
| `federation` | 3     | Cross-holon publishing, federated snapshots, hex-coded settings              |
| `commands`   | 2     | Meta — dispatch a named command, list available commands                     |

Each tool is a thin wrapper around a `@holons/core` function. The dependency surface for each tool is just two functions, injected at registration:

```ts
interface ToolDeps {
  getHoloSphere: () => Promise<any>;
  resolveActor: (override?: Partial<Actor>) => Actor;
}
```

This means a tool is stateless from the MCP server's perspective—every call resolves its actor and substrate fresh.

## How agents use it

The two common patterns:

**Claude Desktop / IDE integration.** Configure the MCP client to launch `node packages/mcp-ui/dist/index.js` over stdio with the desired `HOLONS_ACTOR_*` and `HOLONS_PEER` / `HOLONS_APP` env vars. Claude can now call any of the \~100 tools as part of normal conversation.

**Embedded agent (`@holons/ai-ui`).** The [AI UI package](/software/harvest-dashboard) inside Harvest wraps `@holons/core` functions directly as Claude tool-use loop calls. The MCP server is what makes the same capability available to **external** agents and clients.

## Relationship to the rest of the stack

```
@holons/core  ──┬──>  harvest-web (SvelteKit dashboard)
                ├──>  @holons/telegram-ui (Telegraf bot)
                ├──>  @holons/text-ui (CLI/REPL)
                ├──>  @holons/ai-ui (in-process Claude loop)
                └──>  @holons/mcp-ui  ──>  external MCP clients
                                                │
                                                ▼
                                       Claude Desktop, IDEs,
                                       custom agents, …
```

Every interface ultimately writes to [HoloSphere](/software/holosphere), so an action taken through the MCP server is identical—in attribution, scoring, and federation propagation—to one taken in the Telegram bot or the web app.

## See also

* [Harvest Dashboard](/software/harvest-dashboard) — the monorepo that contains `@holons/mcp-ui` alongside the other UI shells.
* [HolonsBot](/software/holonsbot) — the Telegram interface that shares the same core.
* [HoloSphere](/software/holosphere) — the distributed substrate every tool reads from and writes to.
* [Glossary](/getting-started/glossary) — vocabulary for holons, federation, value equation, and friends.


# Tasks

The unified Quest model — tasks, proposals, events, offers, and requests under one shape

The **Tasks** domain in `@holons/core/tasks` is the most-used part of the system. It implements the **Quest** model: a single shape that covers tasks, proposals, events, offers, and requests, with the same lifecycle—create, accept participants, complete, recognize—applied uniformly.

A user opening the [Telegram bot](/software/holonsbot) and typing `/task do the dishes` and a Claude agent calling the MCP `task_create` tool are doing exactly the same thing: producing a Quest in the holon's `tasks` lens.

## Why "Quest" and not "Task"

Early on the system distinguished tasks, proposals, events, offers, and requests as separate types. They had different shapes, different lifecycle hooks, different UIs. The cost was significant: every new feature had to be replicated four times, every UI had four separate views, every aggregator special-cased on type.

The Quest model unifies them. They are still **conceptually** distinct (a `type` field still records what kind of work this is), but the data shape, persistence path, and operation surface are identical. The benefit is concrete: implementing appreciation, completion tracking, federation, or REA-event emission once covers all five.

## The Quest shape

```ts
interface Quest {
  id?: string | number;
  title: string;
  description?: string;

  status: 'ongoing' | 'completed' | 'cancelled' | 'scheduled'
        | 'recurring' | 'repeating' | 'pending' | 'stopped' | string;
  type?: 'task' | 'quest' | 'event' | 'proposal' | 'recurring' | string;
  category?: string;

  // Schedule
  when?: string;     // ISO timestamp
  ends?: string;
  location?: string;

  // People
  participants: QuestParticipant[];
  appreciation?: any[];

  // Provenance
  created?: string;            // ISO from web
  date?: number;               // ms epoch from Telegram
  initiator?: QuestInitiator;

  // Ordering / dependencies (used by quest-tree / council pipelines)
  orderIndex?: number;
  dependsOn?: string[];

  _meta?: QuestMeta;
  _deleted?: boolean;

  // Open shape so existing call sites read/write extra fields safely
  [key: string]: any;
}
```

The shape is deliberately **open**: extra fields are preserved across writes. This is what let the unification happen without forcing every UI to give up data it cared about. The Telegram bot still writes `message_thread_id`, `stoppers`, `dependencies`, `frequency`, `timeTracking`; the web app still writes its richer schedule fields; both continue to work.

Schedule fields (`when`, `ends`, `location`) come from the web side. Telegram-side metadata sits alongside under the open index. A Quest written by either UI is fully readable by both.

## Special quest forms

Two structures wrap the Quest model for higher-order workflows:

### QuestTree (recursive backcasting)

A directed graph of nested quests, used by the **AI council backcasting** flow. Each node is a quest that is both a parent (of finer-grained sub-quests) and a child (of a coarser vision-level goal). The root captures the long-term vision; leaves are immediately-actionable steps.

```ts
interface QuestTree {
  vision: { statement, principles, targetDate?, successIndicators };
  nodes: Record<string, QuestTreeNode>;
  rootNodeIds: string[];
  maxGenerations: number;
  branchingFactor: number;
  headAdvisor: string;
  resourceFlows?: Array<{ fromNodeId, toNodeId, resourceType, description }>;
}
```

Each node carries holonic metadata—skills required, resources required, impact category (`ecological` / `social` / `economic` / `spiritual` / `technical`), success metrics, future state—so a generated tree captures not just the work but the reasoning behind it.

### RitualSession → design streams

A ritual session produces a `wish_statement`, `declared_values`, a panel of advisors (real / mythic / archetype), and a set of **design streams**. `createTasksFromDesignStreams()` turns each stream into a Quest, preserving the link back to the ritual that birthed it.

This is how the system bridges **practice** (ceremony, ritual) and **execution** (tasks): the practice produces an artifact; the artifact decomposes into the work.

## Operations

Grouped by file:

**Creation (`creation.ts`)**

| Function                                | Purpose                                  |
| --------------------------------------- | ---------------------------------------- |
| `createDefaultTask(input)`              | Construct a Quest with sensible defaults |
| `createTaskFromStep(step, ctx)`         | Make a Quest from a design-stream step   |
| `createTasksFromDesignStreams(session)` | Bulk-create from a `RitualSession`       |
| `createTasksFromQuestTree(tree)`        | Bulk-create from a `QuestTree`           |
| `createTaskRecord(input)`               | Lowest-level constructor — pure          |

Constants: `COUNCIL_INITIATOR`, `DEFAULT_TASK_CATEGORY`.

**Participants (`participants.ts`)** — all pure, all return a new Quest:

| Function                           | Purpose                  |
| ---------------------------------- | ------------------------ |
| `addParticipant(task, user)`       | Join                     |
| `removeParticipant(task, userId)`  | Leave                    |
| `toggleParticipant(task, user)`    | Convenience toggle       |
| `addAppreciation(task, user)`      | Recognize a contribution |
| `removeAppreciation(task, userId)` | Undo                     |
| `toggleAppreciation(task, user)`   | Convenience toggle       |

**Completion (`completion.ts`, `completion-plan.ts`, `completion-execute.ts`)**

| Function                            | Purpose                                                                                  |
| ----------------------------------- | ---------------------------------------------------------------------------------------- |
| `applyTaskCompletion(task)`         | Pure: mark a Quest completed                                                             |
| `planTaskCompletion(task, ctx)`     | Compute the side effects of completion (REA events, scoring deltas, dependency cascades) |
| `executeCompletionPlan(plan, deps)` | Run the planned side effects                                                             |

The plan/execute split lets a caller **preview** what completing a Quest will do—what events get emitted, who gets points, which dependent quests unblock—before actually applying it. The MCP server exposes both halves as separate tools so an agent can confirm before committing.

**Persistence (`persistence.ts`)**

| Function                                         | Purpose                |
| ------------------------------------------------ | ---------------------- |
| `saveTaskToHolon(holosphere, holonId, task)`     | Persist a single Quest |
| `saveTasksToHolon(holosphere, holonId, tasks[])` | Persist multiple       |

The HoloSphere interface required is minimal (`HoloSphereLike`)—just `put` and optionally `get`—so the persistence layer is testable with simple in-memory mocks.

## Lifecycle in one picture

```
   createDefaultTask / createTaskFromStep
              │
              ▼
       Quest in memory
              │
              ▼          ┌─────────────────────┐
   addParticipant ─────► │  Quest in memory    │ ◄───── addAppreciation
   toggleParticipant     │  (pure updates)     │        toggleAppreciation
                         └──────────┬──────────┘
                                    │
                                    ▼
                          saveTaskToHolon
                                    │
                                    ▼
                          Quest in HoloSphere
                                    │
                                    ▼
                          planTaskCompletion
                                    │
                                    ▼
                          executeCompletionPlan
                                    │
                                    ▼
                          REA events + score updates +
                          dependency cascade
```

Every step except the persistence and execute calls is pure—so live previews (the web dashboard showing "if you complete this, you and Laura each get 2 points") are cheap.

## MCP tool surface

The [MCP server](/software/mcp-server) exposes **10 tools** in the `tasks` domain — the full lifecycle (create, save, participants, appreciation, plan, complete) plus reads. An agent connected via MCP can drive any quest from creation to completion entirely through tool calls.

## See also

* [Council](/software/council) — proposals are a Quest type with extra voting machinery
* [Scoring](/software/scoring) — how completed quests and appreciations turn into points
* [REA Accounting](/software/rea-accounting) — the event ledger that records the side effects of completion
* [HolonsBot](/software/holonsbot) — the most-used Quest interface


# Council

Proposal lifecycle and consent-based voting for holonic governance

The **Council** domain in `@holons/core/council` handles the proposal lifecycle for holonic governance. It implements consent-based decision-making: proposals are created, members signal **agree** or **block**, the result is tallied against a quorum, and the proposal's status is derived from those votes.

Council is how a [Managed Holon](/software/holons-types-flavor/managed-holon) makes binding decisions—who joins, how resources are allocated, what the DNA should be, when to federate. It is the operational counterpart to the protocol's [Commitment Registry](/getting-started/glossary#commitment-registry).

## Concepts

A **Proposal** has:

* an identity and a title,
* a status drawn from `ProposalStatus` (open, agreed, blocked, withdrawn, expired, …),
* a vote ledger — one `VoteEntry` per voter, with a direction (`agree` / `block` / `abstain`) and timestamp,
* a quorum threshold (`DEFAULT_QUORUM` if not set).

A **VoteTally** is the rolling aggregate over the ledger: counts of agree, block, abstain, and the derived status given the current quorum.

The Council store lives in the `proposals` lens of a holon's HoloSphere namespace (`PROPOSAL_LENS`), which means every interface—web, Telegram bot, CLI, AI agent, MCP client—sees the same proposals.

## Operations

The public functions exported by `@holons/core/council`:

| Function                                           | Purpose                                                    |
| -------------------------------------------------- | ---------------------------------------------------------- |
| `createProposal(input)`                            | Construct a new proposal object (no persistence yet)       |
| `saveProposal(holonId, proposal)`                  | Persist a proposal to HoloSphere                           |
| `createAndSaveProposal(input)`                     | Convenience: build and persist in one call                 |
| `deleteProposal(holonId, id)`                      | Remove a proposal from the holon                           |
| `castVote(holonId, id, voter, direction)`          | Record an explicit `agree` / `block` / `abstain` vote      |
| `agree(...)` / `block(...)`                        | Convenience wrappers around `castVote`                     |
| `applyVote(proposal, vote)`                        | Pure: produce an updated proposal with the new vote merged |
| `tallyVotes(proposal)`                             | Pure: count current agree/block/abstain                    |
| `deriveStatus(proposal, quorum)`                   | Pure: compute status from the current tally                |
| `hasAgreed(proposal, voterId)` / `hasBlocked(...)` | Quick membership checks for a specific voter               |
| `subscribeToProposals(holonId, cb)`                | Live updates as proposals or votes change                  |

The split between **impure** persistence helpers and **pure** tally/derivation helpers is deliberate: the pure functions are reused by every UI to render live tallies without round-tripping through storage.

## Voting model

Consent-based, not majoritarian:

* A proposal can **pass** when it has reached its quorum of agreements and has zero unresolved blocks.
* A **single block** by a member with standing is enough to keep the proposal from passing. The expectation is that the block-holder participates in resolving the underlying concern, not that the proposal needs a majority to override them.
* Abstain is a recorded position—useful for quorum math and for showing "I've seen this and chosen not to weigh in."

Quorum thresholds are configurable per proposal; `DEFAULT_QUORUM` is used when none is specified.

## MCP tool surface

The [MCP server](/software/mcp-server) exposes **13 tools** in the `council` domain — full proposal lifecycle plus voting and tally introspection. Any MCP-connected agent can therefore create proposals, cast votes, and check tallies on behalf of its resolved actor.

## See also

* [HolonsBot](/software/holonsbot) — the Telegram interface to Council (proposal commands, inline keyboards for voting)
* [DNA](/software/dna) — proposals are often used to add or remove chromosomes
* [Glossary: commitment](/getting-started/glossary#commitment) — the protocol-level promise type that Council operationalizes


# Scoring

How value equations turn contributions into scores

The **Scoring** domain in `@holons/core/scoring` is the engine that turns a holon's [REA event stream](/software/rea-accounting) into per-user scores. It is the working implementation of the [value equation](/getting-started/glossary#value-equation) — the concept referenced across the rest of the docs.

Where REA decides *what counts as a recorded event* and [Council](/software/council) / [DNA](/software/dna) decide *what the holon stands for*, scoring decides *how much each event is worth*. Every UI in the [Harvest](/software/harvest-dashboard) monorepo calls the same scoring functions, so "what's my score?" produces the same answer in the web app, the Telegram bot, the CLI, and via the [MCP server](/software/mcp-server).

## The pipeline

```
        ┌────────────────────────────┐
        │   REA events (rea_events)   │
        └──────────────┬──────────────┘
                       │
                       ▼
        ┌────────────────────────────┐
        │   REAAggregator             │
        │   → UserAggregates          │
        │   → currencyBalances        │
        └──────────────┬──────────────┘
                       │
                       ▼
        ┌────────────────────────────┐
        │   calculateUserScore()      │
        │   with ScoreEquation        │
        └──────────────┬──────────────┘
                       │
                       ▼
                    score
```

Three steps, three pieces of state:

1. **REA events** — every action that should count produced an event (see [REA Accounting](/software/rea-accounting)).
2. **Aggregates** — the aggregator reduces the event stream to per-user counters (`UserAggregates`) and per-currency balances.
3. **Score** — a pure function multiplies aggregates by the equation's weights.

## The value equation

```ts
interface ScoreEquation {
  initiated: number;
  completed: number;
  sent: number;
  received: number;
  hours: number;          // legacy, see migration
  collaboration: number;
  wants: number;
  offers: number;
  currencies: Record<string, number>;  // per-currency weights
}
```

`DEFAULT_EQUATION` ships with sensible starting values:

| Field             | Default | Meaning                                             |
| ----------------- | ------- | --------------------------------------------------- |
| `initiated`       | 1       | Quests created                                      |
| `completed`       | 2       | Quests completed (deliberately worth 2× initiating) |
| `sent`            | 1       | Appreciations sent                                  |
| `received`        | 1       | Appreciations received                              |
| `collaboration`   | 1       | Time-logging events                                 |
| `wants`           | 1       | Wants declared                                      |
| `offers`          | 1       | Offers declared                                     |
| `currencies.hour` | 1       | Hours logged (canonical currency)                   |

That "completed 2× initiated" default isn't accidental — it encodes one of the holon's most basic principles: finishing things matters more than starting them.

Each holon can change every weight. The equation is loaded from the holon's settings lens, cached synchronously for instant UI access, and live-updated via `subscribeToEquationChanges()`.

## User aggregates

```ts
interface UserAggregates {
  initiated: number;    // quests initiated
  completed: number;    // quests completed
  sent: number;         // appreciations sent
  received: number;     // appreciations received
  hours: number;        // sum of hours logged
  collaboration: number;// time-logging events
  wants: number;        // wants declared
  offers: number;       // offers declared
}
```

These are produced by `REAAggregator` from the event stream, or by `toAggregates()` from legacy data shapes. `ZERO_USER_AGGREGATES` is a useful default while REA queries are in flight.

## The score formula

```
score = aggregates.initiated     × equation.initiated
      + aggregates.completed     × equation.completed
      + aggregates.sent          × equation.sent
      + aggregates.received      × equation.received
      + aggregates.collaboration × equation.collaboration
      + aggregates.wants         × equation.wants
      + aggregates.offers        × equation.offers
      + Σ currencyBalances[c]    × equation.currencies[c]
```

Plain weighted sum. No magic, no neural net, no decay (yet). Every weight is multiplied by its aggregate; everything is added. The result is a single number per user.

For per-currency balances (`currencyBalances: Record<string, number>`), the score adds one term per currency the user holds, weighted by `equation.currencies[currency]`.

## Operations

The public functions exported by `@holons/core/scoring`:

| Function                                               | Purpose                                                      |
| ------------------------------------------------------ | ------------------------------------------------------------ |
| `calculateUserScore(aggregates, equation?, balances?)` | Pure: total score for one user                               |
| `calculateScoreFromUserData(userData, equation?)`      | Convenience: aggregates + score in one call                  |
| `calculateAllUserScores(holonId, equation?)`           | Score every user in a holon                                  |
| `getScoreBreakdown(aggregates, equation?, balances?)`  | Per-field contribution (for "where do my points come from?") |
| `getActionScore(actionType, equation?)`                | What's one of these actions worth right now?                 |
| `calculatePercentageShare(userScore, allScores)`       | One user's slice of the total                                |
| `calculateTaskCompletionScores(...)`                   | Specialized: per-task completion delta                       |
| `loadEquation(holonId)`                                | Read the holon's equation from settings                      |
| `getCachedEquation(holonId)`                           | Synchronous read of the cached equation                      |
| `preloadEquation(holonId)`                             | Warm the cache                                               |
| `subscribeToEquationChanges(holonId, cb)`              | Live updates                                                 |
| `migrateEquation(raw)`                                 | Fold legacy / loose-shape data into canonical form           |

The split between **pure** scoring helpers (`calculateUserScore`, `getScoreBreakdown`, …) and **impure** loaders (`loadEquation`, `subscribeToEquationChanges`) means every UI can render a score live from cached state without round-tripping to the substrate.

## Migration: legacy `hours` → `currencies.hour`

Historically the equation had a top-level `hours` weight. Newer code reads `currencies.hour`. `migrateEquation()` folds the legacy shape into the new one on load, and also folds flat top-level currency keys (`equation.euro = 0`) — the shape telegram-ui historically wrote — into `currencies.euro`.

The migration is idempotent and safe to call on already-migrated data. The deprecated top-level `hours` field is preserved (set equal to `currencies.hour`) so unmigrated consumers keep computing the same score.

## Subscriptions and caching

`getCachedEquation(holonId)` returns the cached equation synchronously, useful in render-paths that can't await. The cache is populated by `preloadEquation()` and kept fresh by `subscribeToEquationChanges()`, which listens to the underlying settings lens.

This pattern is why a slider in the web dashboard can instantly re-render every user's score when a holon adjusts a weight — the cache updates, the pure score function re-runs, every UI hears about it.

## MCP tool surface

The [MCP server](/software/mcp-server) exposes **9 tools** in the `scoring` domain:

* per-user score (`calculate_user_score`)
* all-user scoring (`calculate_all_scores`)
* score breakdown (`get_score_breakdown`)
* per-action delta (`get_action_score`)
* equation load/migration (`load_equation`, `migrate_equation`)
* and the supporting variants

Agents connected via MCP can answer "what's my contribution?" and "what would happen if we changed the equation?" without writing any score-computation code of their own.

## See also

* [REA Accounting](/software/rea-accounting) — the event stream this domain consumes
* [Glossary: value equation](/getting-started/glossary#value-equation) — the protocol concept
* [Glossary: epoch](/getting-started/glossary#epoch) — the time windows over which scores are distributed
* [Funding Flow](/getting-started/funding-flow) — how scores feed splitter/threshold distributions


# REA Accounting

The Resource-Event-Agent event ledger that underpins scoring and contribution tracking

**REA** stands for **Resource–Event–Agent**, a well-known accounting model from the work of William E. McCarthy: every economic phenomenon is captured as an *event* that moves *resources* between *agents*. The `@holons/core/rea` domain is the Holons ecosystem's implementation of that model.

Every action that should "count"—a task being completed, an appreciation being given, an expense being logged, a library item being borrowed, an offer being made—produces an REA event. Those events are what the [scoring](/software/harvest-dashboard) system reads when computing contribution equity, and what federated holons exchange when sharing recognition across membrane boundaries.

REA is the **substrate** layer of the contribution stack. Most users never interact with it directly; they create tasks, give appreciations, log expenses—and the corresponding REA events are recorded as a side effect.

## Why REA

The alternative to REA is to keep separate, ad-hoc records for tasks, appreciations, expenses, and so on, and then re-aggregate them for scoring. That works briefly but breaks down as soon as a holon wants to:

* recognize a new kind of contribution without rewriting the scoring pipeline,
* federate recognition data across holons that track different things,
* audit "what happened in this holon last month" as a single ordered stream.

REA solves these by making the **event** the unit of record, with a loose enough shape that new event types don't require schema migrations.

## The event shape

```ts
interface REAEvent {
  id: string;
  timestamp: number;
  resource?: {
    type?: string;
    quantity?: number;
    unit?: string;
    resourceId?: string | number;
    [key: string]: any;
  };
  provider?: { id?: string | number; type?: string; name?: string; [key: string]: any };
  receiver?: { id?: string | number; type?: string; name?: string; [key: string]: any };
  context?: {
    holonId?: string;
    questId?: string | null;
    itemId?: string | number;
    expenseId?: string;
    note?: string | null;
    [key: string]: any;
  };
  eventType?: string;
  status?: string;
  [key: string]: any;
}
```

The shape is deliberately loose. The required fields are `id` and `timestamp`; everything else is optional. Each domain that emits events adds the fields it cares about under `resource`, `context`, etc. Forward compatibility comes for free.

## Storage

Events are persisted in the `rea_events` lens of the holon they belong to:

```
HoloSphere.put(holonId, 'rea_events', event)
```

Querying is an in-memory filter pass over the lens contents, supporting:

```ts
interface EventQueryFilters {
  resourceType?: string;
  eventType?: string;
  agentId?: string | number;
  fromDate?: number;
  toDate?: number;
  status?: string;
}
```

This keeps the storage layer simple and the query layer flexible—the same semantics as the original Telegram-bot implementation, now lifted into shared core.

## The Event Factory

`REAEventFactory` is a static class with one method per kind of action that should produce an event. Callers don't construct raw REA events; they call factory methods like:

* `questCreated(...)` / `questCompleted(...)`
* `appreciationGiven(...)`
* `expenseEvents(expense)` — produces both the paid-event and the per-participant share-events
* `timeLogged(...)`
* `itemBorrowed(item, borrower)` / `itemReturned(item, returner)`
* `offerMade(...)` / `wantMade(...)`
* `creditIssued(...)`

The factory ensures every event has:

* a unique ID (`generateId(holonId)` produces `${holonId}_${timestamp}_${rand}`),
* properly shaped `provider` / `receiver` agents (`createUserAgent`, `createHolonAgent`, `createExternalAgent`),
* the correct `eventType` discriminator for downstream aggregators to dispatch on.

Output matches the original JavaScript factory exactly, so existing stored events keep aggregating correctly after the TS migration.

## Where it plugs in

REA is the integration point between several otherwise-independent domains:

* [**Council**](/software/council) emits events when proposals reach agreement (recognition for participation).
* [**Library**](/software/library) emits `itemBorrowed` and `itemReturned` events, with optional deposit accounting.
* **Expenses** emits a `expense:paid` event plus one share-event per participant.
* **Tasks** emits quest lifecycle events.
* **Scoring** consumes all of them through the `REAEventStoreLike` interface to compute contribution points.

This is why a "value equation" in the protocol sense can be reconfigured purely by changing weights: the underlying event stream is the same regardless of what you choose to value.

## MCP tool surface

REA itself is not heavily exposed as MCP tools—the goal is for events to be a **byproduct** of domain operations, not something agents have to manage directly. When a Claude agent calls `task_complete` or `appreciation_give` via the [MCP server](/software/mcp-server), the corresponding REA events are emitted automatically.

The `holosphere` MCP domain provides escape-hatch reads against the `rea_events` lens for tooling that wants to inspect the event stream directly.

## See also

* [Harvest](/software/harvest-dashboard) — the monorepo that contains `@holons/core/rea`
* [Glossary: value equation](/getting-started/glossary#value-equation) — what the event stream ultimately feeds
* [Glossary: epoch](/getting-started/glossary#epoch) — the time windows over which the events are aggregated
* [Funding Flow](/getting-started/funding-flow) — the protocol-level distribution mechanisms REA enables


# DNA

How a holon's identity is composed from chromosomes

A holon's **DNA** is its identity, expressed as an ordered sequence of chromosomes. Each chromosome captures one element of what the holon is or does—a value it holds, a tool it uses, a practice it observes. The DNA sequence is what makes a holon recognizable as itself: distinct from the holons around it, even when they share members or resources.

The `@holons/core/dna` domain provides the canonical model—the same chromosomes, sequences, and validation rules used by every interface in the [Harvest](/software/harvest-dashboard) monorepo.

## Concepts

### Chromosome

A single element of identity:

```ts
interface Chromosome {
  id: string;
  holonId: string;
  name: string;
  type: 'value' | 'tool' | 'practice';
  description: string;
  createdAt: number;
  updatedAt: number;
  icon?: string;
  color?: string;
}
```

Three types, by design:

* **Value** — what the holon cares about (e.g. "regeneration", "transparency", "care").
* **Tool** — what it uses (e.g. "Telegram", "sociocracy", "permaculture").
* **Practice** — what it does regularly (e.g. "weekly check-in", "rotating stewardship", "consent-based decisions").

Each chromosome lives in the holon's **ChromosomeLibrary**—the set of available pieces. Not every chromosome in the library is part of the DNA; the DNA is a curated, ordered subset.

### DNA Sequence

```ts
interface DNASequence {
  holonId: string;
  chromosomeIds: string[]; // Ordered, unique, max 20
  createdAt: number;
  updatedAt: number;
  version: number;
}
```

Constraints enforced by validation:

* **Ordered.** Sequence order matters—earlier chromosomes are more defining.
* **Unique.** No chromosome appears twice in a sequence.
* **Bounded.** `MAX_CHROMOSOMES_PER_DNA` caps the sequence at 20.
* **Referentially valid.** Every ID in the sequence must point to a real chromosome in the library.
* **Versioned.** The sequence carries a version counter for optimistic concurrency.

## Seed data

`@holons/core/dna/seed-data` ships default chromosomes so a new holon doesn't start from a blank slate:

* `defaultValues` — common starting values
* `defaultTools` — typical tools
* `defaultPractices` — frequently useful practices
* `getAllDefaultChromosomes()` / `getDefaultChromosomesByType(type)` — accessors

A newly created holon usually has its library seeded with these (`seedChromosomeLibrary`) and then evolves over time.

## Operations

The public functions exported by `@holons/core/dna`:

| Function                                    | Purpose                                              |
| ------------------------------------------- | ---------------------------------------------------- |
| `getChromosomeLibrary(holonId)`             | Load the full library for a holon                    |
| `getChromosome(holonId, id)`                | Read a single chromosome                             |
| `addChromosome(holonId, chromosome)`        | Add a new chromosome to the library                  |
| `updateChromosome(holonId, id, patch)`      | Modify an existing chromosome                        |
| `removeChromosome(holonId, id)`             | Remove a chromosome (with sequence-reference checks) |
| `getDNASequence(holonId)`                   | Load the current DNA sequence                        |
| `saveDNASequence(holonId, sequence)`        | Persist a new sequence (validated first)             |
| `seedChromosomeLibrary(holonId)`            | Initialize a library with defaults                   |
| `subscribeToChromosomeLibrary(holonId, cb)` | Live updates                                         |
| `subscribeToDNASequence(holonId, cb)`       | Live updates                                         |

And the pure validation helpers:

| Function                                                                | Purpose                                              |
| ----------------------------------------------------------------------- | ---------------------------------------------------- |
| `validateChromosome(chromosome)`                                        | Field-level validation                               |
| `validateDNA(sequence, library)`                                        | Whole-sequence validation against a library          |
| `validateDNASequence(sequence)`                                         | Structural validation (ordering, uniqueness, bounds) |
| `findDuplicates(sequence)` / `findInvalidReferences(sequence, library)` | Diagnostics for `validateDNA`                        |
| `createDNAError(type, message)`                                         | Construct a typed `DNAValidationError`               |

`DNAValidationError` distinguishes between `duplicate`, `max_length`, `invalid_reference`, and `missing_required` failures, so UIs can surface specific feedback rather than a generic "invalid."

## Governance interplay

DNA changes are typically not made unilaterally. The common pattern:

1. A member opens a [Council](/software/council) proposal: "Add chromosome *consent-based decisions* to our practices."
2. Members vote.
3. On agreement, the chromosome is added (`addChromosome`) and the sequence updated (`saveDNASequence`).

This binds DNA to the holon's governance: identity drifts only when the holon consents to it.

## MCP tool surface

The [MCP server](/software/mcp-server) exposes **12 tools** in the `dna` domain — full chromosome and sequence management, validation, and library seeding. An AI agent connected via MCP can propose, validate, and (if its actor has standing) commit DNA changes directly.

## See also

* [Council](/software/council) — the proposal lifecycle that governs DNA changes
* [Glossary: shared DNA](/getting-started/glossary#shared-dna) — the protocol-level concept this domain operationalizes
* [Glossary: membrane](/getting-started/glossary#membrane) — the identity boundary that DNA fills


# Library

Shared community library — tools, books, equipment borrowed and lent across a holon

The **Library** domain in `@holons/core/library` is the shared lending catalog of a holon. It tracks the tools, books, equipment, and other items members make available to each other, who has borrowed what, when it is due back, and—through integration with [REA accounting](/software/rea-accounting)—the deposit and return events that recognize the practice of sharing.

Where a typical resource catalog is read-mostly, the Library is built around the verbs of borrowing and lending: items have state (`borrowed` / `available`), borrowers and timestamps, optional return-by dates, and an audit trail of ratings and issues.

## Item types

Standard categories are enumerated in `LIBRARY_TYPES`:

* `tool`
* `book`
* `equipment`
* `other`

Type detection (`detectItemType`) infers a sensible default from a description, so members can add items without picking a category explicitly. UIs use type to choose icons (`getItemIcon`) and display names (`getTypeDisplayName`).

## Item shape

```ts
interface LibraryItem {
  id: string;
  type: LibraryItemType;
  borrowed: boolean;
  createdBy?: number | string;        // owner (typically a user id)
  createdByUsername?: string;
  borrower: string | null;            // display name of current borrower
  borrowerId?: number | string | null;
  borrowerInitials?: string;
  borrowedAt?: Date | string;
  returnBy?: Date | string;
  returnedAt?: Date | string;
  category: string;
  description: string;
  value: number;                      // for deposit accounting
  created: Date | string;
  ratings?: Array<{ user?: string; rating: number; review?: string; date: Date | string }>;
  issues?: Array<{ reporter?: string; issue: string; date: Date | string; resolved: boolean }>;
}
```

The `value` field is what links Library to deposit accounting: when a member borrows an item, a deposit event is emitted with this amount; when they return it, the deposit is released.

## Operations

The public functions exported by `@holons/core/library`:

| Function                                         | Purpose                                                             |
| ------------------------------------------------ | ------------------------------------------------------------------- |
| `createLibraryItem(name, opts?)`                 | Build a new item (no persistence)                                   |
| `addItem(db, holonId, item)`                     | Persist a new item to HoloSphere                                    |
| `getItem(db, holonId, id)`                       | Read a single item                                                  |
| `listItems(db, holonId)`                         | Read all items in the holon's library                               |
| `filterItems(items, predicate)`                  | Pure: apply borrow-state / type / search filters                    |
| `setItemValue(db, holonId, id, value)`           | Update an item's deposit value                                      |
| `removeItem(db, holonId, id)`                    | Remove an item from the library                                     |
| `borrowItem(db, holonId, id, actor)`             | Mark item borrowed by an actor; returns a `BorrowItemResult`        |
| `returnItem(db, holonId, id)`                    | Mark item returned; returns a `ReturnItemResult`                    |
| `getLibraryStats(items)`                         | Pure: aggregate `LibraryStats` (total, borrowed, available, byType) |
| `computeBorrowerInitials(actor)`                 | Pure helper: 2-letter initials from a `BorrowActor`                 |
| `getItemDisplayTitle(item)`                      | Pure helper: human-friendly title                                   |
| `getItemIcon(item)` / `getTypeDisplayName(type)` | Pure presentation helpers                                           |

The split between **impure** persistence helpers (`addItem`, `borrowItem`, …) and **pure** presentation/aggregation helpers (`filterItems`, `getLibraryStats`, `computeBorrowerInitials`, …) means every UI uses the same code paths to render the same data—no per-UI re-implementations.

## Deposit accounting

When an item with a non-zero `value` is borrowed, the Library emits an REA event recording the deposit; when it is returned, a release event is emitted. These are produced via the [REA event factory](/software/rea-accounting):

```ts
recordBorrowAccounting(item, borrower, deps);
recordReturnAccounting(item, returner, deps);
```

`AccountingDeps` is a thin interface (`REAEventFactoryLike` + `REAEventStoreLike`) that lets the library module stay decoupled from REA—callers pass in the implementations they want, including no-op stubs for tests.

The resulting events feed the [scoring](/software/harvest-dashboard) system, so a holon that values the practice of lending can weight it in its value equation alongside other contribution types.

## Ratings and issues

Each item carries optional `ratings` (per-user rating + review) and `issues` (reporter, description, date, resolution status). These are stored on the item itself rather than as separate records, which keeps the data co-located with what it describes—simpler to query, simpler to display.

## MCP tool surface

The [MCP server](/software/mcp-server) exposes **11 tools** in the `library` domain — CRUD, borrowing, returning, search, tagging, stats. Agents connected via MCP can manage the catalog directly, including borrowing on behalf of their resolved actor.

## See also

* [REA accounting](/software/rea-accounting) — the event ledger that records deposits and returns
* [Harvest](/software/harvest-dashboard) — the monorepo this domain lives in
* [HolonsBot](/software/holonsbot) — the Telegram interface to library borrow/return flows


# Expenses

Shared cost logging, splitting, and per-user balance accounting

The **Expenses** domain in `@holons/core/expenses` tracks shared monetary expenses inside a holon: who paid, what for, in which currency, and how the cost should be split among participants. From those raw records it computes per-user balances and a credit matrix showing who owes what to whom.

Where [REA Accounting](/software/rea-accounting) is the event ledger for **all** value flows in a holon, Expenses is the specialized layer for **monetary** ones. Every expense action produces REA events that feed [Scoring](/software/scoring), but the Expenses domain owns its own data model because monetary balances need stronger guarantees (currency normalization, integer-safe arithmetic, multi-currency netting) than a generic event stream provides.

## Concepts

### Expense

```ts
interface Expense {
  id: AgentId;
  date: number;                // Unix epoch ms
  amount: number;
  currency: string;            // normalized: lowercase, singular, a–z only
  description: string;
  paidBy: AgentId;
  splitWith: AgentId[];
  picture?: string | null;     // optional Telegram file_id for a receipt
}

type AgentId = string | number;
```

A few notes on the shape:

* **IDs are loose.** Telegram stores numeric user IDs; the web app uses UUID strings. The domain accepts both and normalizes at the storage edge.
* **Currency is normalized.** "EUR", "euros", "Euro" all become `eur` via `normalizeCurrency()`. This is what makes multi-currency totals additive without per-call casing checks.
* **`splitWith` can be loose.** Older records may arrive as a non-array. `coerceSplitWith()` is the canonical normalizer.
* **Pictures are optional.** Receipts are stored as Telegram file IDs—external blob storage stays out of the domain.

### Balance

```ts
interface UserBalance {
  userId: AgentId;
  net: number;       // positive = is owed; negative = owes
}
```

A single number per user per currency. Positive means the holon owes them; negative means they owe the holon.

### Credit matrix

```ts
interface BalancesResult {
  creditMatrix: number[][];   // creditMatrix[i][j] = what i is owed by j
  userIds: AgentId[];
  balances: UserBalance[];
}
```

An NxN matrix where `[i][j]` is the net amount user `i` is owed by user `j`. Row sums give per-user net balances; column sums give "how much does each user owe in total."

This is what lets the bot answer "settle up with Laura" by reading one cell of the matrix rather than reconstructing the full debt graph each time.

## Operations

### Creation and editing

| Function                             | Purpose                                      |
| ------------------------------------ | -------------------------------------------- |
| `createExpense(input)`               | Build an Expense from a `CreateExpenseInput` |
| `addParticipant(expense, userId)`    | Add a user to `splitWith` (pure)             |
| `removeParticipant(expense, userId)` | Remove (pure)                                |
| `toggleParticipant(expense, userId)` | Convenience toggle (pure)                    |
| `splitAmongAll(expense, allUsers)`   | Spread the cost across every user in a holon |

Operations are pure—they return a new `Expense`. Persistence is done by the calling UI through [HoloSphere](/software/holosphere).

### Balance computation

| Function                                                 | Purpose                                        |
| -------------------------------------------------------- | ---------------------------------------------- |
| `computeBalances(expenses, users)`                       | Full `BalancesResult` — matrix + per-user nets |
| `computeCreditMatrix(expenses, userIds)`                 | Just the matrix                                |
| `computeUserCurrencyBalance(expenses, userId, currency)` | One user, one currency                         |
| `coerceSplitWith(value)`                                 | Defensive normalizer for legacy data           |
| `normalizeCurrency(currency)`                            | Canonical currency code                        |

Aliases for legacy call sites:

* `calculateBalance` = `computeUserCurrencyBalance`
* `calculateCreditMatrix` = `computeCreditMatrix`

All computation is pure. A web UI rendering "you owe Laura €12.50" runs the same function as the Telegram bot running `/balance`.

## How a split works

The conventional even-split:

```
Each participant owes: amount / splitWith.length
The payer is credited:  amount
The payer's net:        +amount - (amount / splitWith.length)  if they're in splitWith
                        +amount                                  if they're not
```

For multi-currency holons, the same logic runs independently per currency. There is no implicit exchange rate—balances stay in the currency they were incurred in, and users can clear them in whichever currency makes sense.

## Integration with REA

When an expense is created, the corresponding [REAEventFactory](/software/rea-accounting#the-event-factory) emits:

* one `expense:paid` event with the payer as provider,
* one share event per participant, with the participant as receiver of the cost obligation.

These events feed scoring via the standard aggregator pipeline. A holon that values "covering shared costs" can give weight to `expense:paid` events in its [value equation](/software/scoring), so contributing financially becomes a recognized form of participation alongside hours and appreciations.

## Storage layout

Expenses are persisted in the `expenses` lens of their holon. Each expense is keyed by its `id` (Telegram message ID or UUID); reads use the standard `getAll` pattern.

The Telegram bot's persistence shape is the authoritative one — both the web app and any future UI normalize to it on write. This is what lets the same holon's expenses be edited from any interface without per-UI translation.

## MCP tool surface

The [MCP server](/software/mcp-server) exposes **6 tools** in the `expenses` domain:

* expense CRUD (`expense_create`, `expense_get`, `expense_delete`)
* split helpers (`split_expense`)
* balance computation (per-user, full matrix)

An MCP-connected agent can log a shared meal, calculate who owes whom, or settle a balance entirely through tool calls.

## See also

* [REA Accounting](/software/rea-accounting) — the event ledger expenses emit into
* [Scoring](/software/scoring) — how monetary contributions become recognized points
* [Library](/software/library) — sibling resource-sharing domain (with deposit accounting)
* [MCP Server](/software/mcp-server) — the tool surface


# Federation (Core Domain)

How holons publish to each other — the federation publishing domain

The **`@holons/core/federation`** module is the implementation behind the [federation](/getting-started/glossary#federation) concept. It is the layer that takes an item from one holon and makes it visible in another—or to many others, or to a specific geographic cell—under the rules each side has set for itself.

This is distinct from [HoloSphere federation](/software/holosphere/federation), which is about **data sharing between spaces**. The core federation domain sits one level up: it decides *what gets published, to whom, and how* before HoloSphere is asked to propagate it.

## The mental model

Two questions answered by every federation publish:

1. **What's being published?** An item, wrapped in a **hologram**—a propagation-ready envelope with provenance metadata (`publishedAt`, source attribution, original `id`).
2. **Where is it going?** A **target**, expressed as one of three shapes:

| Target                         | When to use it                                                               |
| ------------------------------ | ---------------------------------------------------------------------------- |
| `{ kind: 'all' }`              | Broadcast to every federated partner — the default for general announcements |
| `{ kind: 'partner', holonId }` | Send to one specific partner holon                                           |
| `{ kind: 'hex', cell }`        | Drop into a geographic H3 cell (regional / bioregional flows)                |

Same operation, three reach patterns. A holon publishing a quest to its sibling co-op uses `partner`. A bioregional hub publishing observations to everyone in its region uses `hex`. A holon announcing a new offering uses `all`.

## The publish surface

```ts
function publishToFederation(
  ctx: PublishContext,
  target: PublishTarget,
  options?: PublishOptions
): Promise<PublishOutcome>
```

### `PublishContext`

What's being published:

```ts
interface PublishContext {
  holosphere: HoloSphere;
  holonId: string;     // home holon (the source)
  lens: string;        // which lens — tasks, expenses, …
  item: { id: string; [k: string]: any };
}
```

The `id` is **required**: the publisher needs a stable identifier so receivers can resolve the hologram back to its origin.

### `PublishOptions`

How to publish:

```ts
interface PublishOptions {
  /** Also write to settings.hex if one is configured. Default true. */
  includeSettingsHex?: boolean;

  /** Federation source identity (e.g. nostr pubkey). Defaults to `holonId`. */
  federationSourceId?: string;

  /** Called when a put is rejected by HoloSphere ACL. */
  onWriteDenied?: (info: {
    target: string;
    lens: string;
    message: string;
  }) => void;
}
```

`federationSourceId` is the escape hatch for holons that key federation off something other than the home holon ID—typically a Nostr public key. UIs resolve their identity layer and pass it in.

`onWriteDenied` is how the UI gets notified when a target rejects the publish for permission reasons. The publish doesn't abort on a single denial; it continues with the other destinations and records the denial in the outcome.

### `PublishOutcome`

What happened:

```ts
interface PublishOutcome {
  publishedTo: number;      // count of successful destinations
  destinations: string[];   // their IDs
  errors: string[];         // per-destination failures
  usedHolograms: boolean;
}
```

A publish never throws on a single bad destination; it accumulates errors and lets the caller decide how to surface them.

## Settings-hex integration

A holon can configure a **settings hex** — an H3 cell that acts as its public bulletin board. When `includeSettingsHex` is `true` (the default), every "publish to all" also drops the hologram into that cell.

This is what enables **geographically-keyed discovery**: a regional aggregator subscribed to the hex sees every published item from every member holon in its region without those holons needing to know about it individually.

`readSettingsHex(holosphere, holonId)` reads the configured cell for a given holon. If unset, the cell-write side of the publish is skipped silently.

## Snapshots

`getFederationSnapshot(holosphere, holonId, federationSourceId?)` is the read-only view of a holon's federation state:

```ts
interface FederationSnapshot {
  federated: string[];                     // partner IDs
  partnerNames: Record<string, string>;    // ID → display name
}
```

This is what powers UI lists ("who am I federated with?") and what `publishToFederation` itself consults when target is `{ kind: 'all' }`.

## The hologram pattern

Every publish wraps the source item in a **hologram** before propagating. The hologram includes:

* a copy of the item,
* the origin holon ID,
* the origin lens,
* a published-at timestamp,
* the federation source ID (often a Nostr pubkey).

Why wrap? Because the **same item** may be in the origin holon's lens **and** in a partner's lens **and** in a hex cell—and consumers downstream need to know which copy they're looking at, who published it, and whether updates should track back to a canonical source.

The caller is responsible for stamping the source item with `published` / `publishedAt` / `publishedTo` markers (this is intentional—UIs often want to update their own item rendering at the same moment). The hologram itself is computed inside `publishToFederation`.

## How permission denials surface

HoloSphere's federation uses ACLs at the destination: a partner can refuse writes to particular lenses. When the publisher hits a denial:

1. The error is detected by name (`AuthorizationError`) or message (`Write access denied`).
2. A short message is built (`Unable to publish to <prefix>… — no write permission for <lens>`).
3. The `onWriteDenied` callback fires (UIs use this to show a toast).
4. The denial goes into `PublishOutcome.errors` as a short string.
5. The publish continues to the remaining destinations.

This is what makes federation **safely best-effort**: a misconfigured partner doesn't block other partners from receiving the publish.

## MCP tool surface

The [MCP server](/software/mcp-server) exposes **3 tools** in the `federation` domain:

* `publish_to_federation` — the core publish, with full target/options support
* `get_federation_snapshot` — read partner list and names
* `read_settings_hex` — read the configured discovery cell

An MCP-connected agent can therefore make a holon publish, inspect its federation, and discover where its broadcasts land—all without UI involvement.

## See also

* [Glossary: federation](/getting-started/glossary#federation) — the protocol concept this implements
* [HoloSphere Federation](/software/holosphere/federation) — the substrate layer beneath this domain
* [Tasks](/software/tasks) — most publishes are Quests; the federation flow is the same shape
* [MCP Server](/software/mcp-server) — the tool surface


# Text UI

Framework-agnostic CLI and REPL for driving holons from the terminal

**`@holons/text-ui`** is the command-line interface to the Holons ecosystem. It is the simplest possible renderer for `@holons/core/commands`: a parser, a dispatcher, and a default text renderer. No framework, no UI library, no network calls beyond what the core commands themselves do.

It's the right tool when you want to:

* poke at a holon from a terminal without launching Telegram or a browser,
* script repetitive holon operations in shell or CI,
* prototype a new core command and exercise it before wiring up a richer UI,
* fall back to a working interface when more elaborate UIs aren't an option.

## What it is

* **Name:** `@holons/text-ui`
* **Location:** `harvest/packages/text-ui/`
* **Binary:** `holons`
* **Dependencies:** just `@holons/core` (no SDKs, no frameworks)

## Modes

```bash
# REPL — interactive shell
holons

# Single command
holons createTask --holonId=garden --title="water seedlings"

# Help
holons --help
holons createTask --help
```

The REPL prompt:

```
holons REPL — type "help" or a command, "exit" to quit
holons> createTask --holonId=garden --title="water seedlings"
✓ Task "water seedlings" created in garden
holons> exit
```

`help`, `exit`, and `quit` are recognized as REPL meta-commands. Everything else is parsed and dispatched through the same registry the AI UI uses.

## The argument grammar

A small, predictable grammar. The parser handles both `process.argv` token arrays and free-form REPL lines (with quote handling).

```
<command> [--key=value] [--key value] [--flag] [--no-flag] [positional...]
```

Rules:

* `--key=value` — explicit assignment.
* `--key value` — lookahead form; works if the next token isn't another flag.
* `--flag` — boolean true.
* `--no-flag` — boolean false.
* Bare tokens become **positional** arguments (collected separately from named params).
* Single and double quotes group whitespace into one token: `--title="water the seedlings"`.

Values are auto-coerced: `true`/`false` → booleans, numeric strings → numbers, everything else stays a string.

## How a command dispatches

```
argv / line
    │
    ▼
parseArgv / parseLine
    │
    ▼
ParsedCommand { command, params, positional }
    │
    ▼
registry.get(command)         ← @holons/core/commands
    │
    ▼
Missing required params? → render help, exit 1
    │
    ▼
command.execute(params)
    │
    ▼
renderer.render(result)
```

The dispatcher checks for `--help`, validates required params, calls `execute()`, and hands the result to a `Renderer`. Exit code is `0` on success (`result.ok === true`), `1` on failure.

## Renderers

`defaultRenderer` writes plain text to stdout. The `Renderer` interface is small:

```ts
interface Renderer {
  render(result: CommandResult): void;
  error(err: unknown): void;
}
```

This is intentionally pluggable. A future structured-output renderer (`--json`) or a colored renderer for richer terminals would slot in here without changing parsers or dispatchers.

## The shared command registry

The text-ui and [AI UI](/software/ai-ui) **share the same `CommandRegistry` shape**. Each command is a `CoreCommand`:

```ts
interface CoreCommand {
  name: string;
  description: string;
  params: { name; type: 'string' | 'number' | 'boolean'; description; required? }[];
  execute(params): Promise<{ ok; message?; data? }>;
}
```

A command authored once is automatically:

* a CLI subcommand (`holons <name> --param=value`),
* a Claude tool (auto-generated JSON Schema from `params`),
* a candidate MCP tool (via the `commands` domain of [`@holons/mcp-ui`](/software/mcp-server)),
* discoverable through the central `commands` domain of `@holons/core`.

This is the leverage of the shared-core architecture: writing a new command is one file, and four interfaces light up.

## Help system

Help is generated from the registry — there is no separate "help text" to maintain.

```
holons --help              → lists all commands with descriptions
holons createTask --help   → lists params, types, required flags
```

The width-aligned formatting in `cli.ts` makes the output readable without bringing in a help-text library.

## When to use it

* You're authoring a new command and want the fastest possible feedback loop.
* You're shell-scripting a holon operation (cron jobs, CI, deployment hooks).
* You're testing end-to-end without wanting to spin up the web app.
* You want a clean fallback that depends only on `@holons/core`.

For natural-language input, use the [AI UI](/software/ai-ui). For external clients (Claude Desktop, IDEs), use the [MCP server](/software/mcp-server). For day-to-day community use, use the [Telegram bot](/software/holonsbot) or the [web dashboard](/software/harvest-dashboard).

## See also

* [AI UI](/software/ai-ui) — natural-language sibling using the same command registry
* [MCP Server](/software/mcp-server) — out-of-process server using the same domain layer
* [Harvest](/software/harvest-dashboard) — the monorepo `@holons/text-ui` lives in


# AI UI

In-process Claude tool-use loop — make a holon callable in natural language

> **Status: early — `@holons/ai-ui` is at `0.1.0`.** The agent loop and tool conversion are stable; the command registry currently lives as a fallback in this package and will move to `@holons/core/commands` upstream. Expect the import path for shared commands to change.

**`@holons/ai-ui`** is an in-process natural-language interpreter for Holons. It runs a Claude tool-use loop against the `@holons/core` commands so a user can say "log two hours on the garden task" and the agent translates it into the right sequence of `@holons/core` calls. It is what makes a Claude model **embedded inside** the holon's own infrastructure, rather than orchestrating it from outside.

This is the sibling of the [MCP server](/software/mcp-server): both expose `@holons/core` to AI agents, but they sit at different layers.

|               | `@holons/ai-ui`                                           | `@holons/mcp-ui`                                            |
| ------------- | --------------------------------------------------------- | ----------------------------------------------------------- |
| Process model | **In-process** — embeds Claude SDK inside the running app | **Out-of-process** — MCP server reached by external clients |
| Entry point   | `holons-ai` CLI (or library import)                       | stdio / SSE over HTTP                                       |
| Caller        | A holon's own scripts, cron jobs, bot handlers            | Claude Desktop, IDE integrations, other MCP-aware tools     |
| Best for      | Embedding intelligence into the holon                     | Letting external agents participate in the holon            |

The two are not redundant—they support different deployment patterns. A holon can run both.

## What it is

* **Name:** `@holons/ai-ui`
* **Location:** `harvest/packages/ai-ui/`
* **Binary:** `holons-ai`
* **SDK:** `@anthropic-ai/sdk`
* **Default model:** `claude-sonnet-4-6` (override via `HOLONS_AI_MODEL`)

## Using the CLI

```bash
# Single-prompt mode
holons-ai "Create a task in the garden holon called 'water the seedlings'"

# Pipe from stdin
echo "What tasks are open in the kitchen holon?" | holons-ai

# Help
holons-ai --help
```

Environment:

| Variable            | Purpose                    | Required |
| ------------------- | -------------------------- | -------- |
| `ANTHROPIC_API_KEY` | Claude API auth            | Yes      |
| `HOLONS_AI_MODEL`   | Override the default model | No       |

The CLI prints the agent's final text answer to stdout; everything else goes to stderr.

## How the loop works

```
user prompt
    │
    ▼
┌────────────────────────────────────────────────┐
│ Claude (sonnet-4-6) — sees:                    │
│  - system prompt (cached)                      │
│  - tool definitions (cached)                   │
│  - growing message history                     │
└────────────────────────────────────────────────┘
    │
    ▼  tool_use blocks?
    ├─ no  → return final text
    └─ yes
         │
         ▼
   For each tool_use:
     registry.get(name).execute(input)
     → JSON-stringify result
     → push as tool_result block
         │
         ▼
   Next iteration (back to Claude)
```

The loop terminates when the model emits `stop_reason: 'end_turn'` or produces no further `tool_use` blocks. Defensive cap: `maxIterations` (default 10), to prevent runaway loops.

Per-call defaults:

* `maxTokens` = 4096
* `maxIterations` = 10

## Prompt caching

The system prompt and tool definitions don't change across turns within a session, so they're sent with a single `cache_control: { type: 'ephemeral' }` breakpoint on the system block. Anthropic's render order is **tools → system → messages**, so a breakpoint on the system block caches both tools and system together. This:

* keeps the implementation well under the 4-breakpoint cache cap,
* avoids unnecessary cache writes,
* makes multi-turn sessions cheap.

The same pattern is recommended for any tool-use loop calling Claude — see the `agent.ts` source for the exact wiring.

## Tool definitions

Tools are derived from a `CommandRegistry`. Each registered command has:

```ts
interface CoreCommand {
  name: string;
  description: string;
  params: CoreCommandParam[];
  execute(params): Promise<{ ok: boolean; message?: string; data?: unknown }>;
}
```

At load time, every command is converted to an Anthropic `Tool` with a JSON Schema generated from its params. Required-param enforcement, type coercion, and side effects all live inside the command's own `execute()` — so the same registry powers both the AI loop and the [text UI](/software/harvest-dashboard) CLI.

Currently the registry lives at `packages/ai-ui/src/commands.ts` as a **fallback** (identical to the text-ui copy), designed so that when `@holons/core/commands` is extracted upstream, the package can switch to the shared registry with a no-op rename.

## System prompt

The default system prompt is intentionally narrow:

> *You are the Holons assistant. You help users manage tasks, hours, and shopping lists across their holons by calling the available tools. Always call a tool when the user requests an action; never fabricate results. After tools complete, summarize what was done in one sentence.*

Two principles worth noting:

1. **Always call a tool when the user requests an action.** The agent is not asked to be clever about when to act—if the user wants an action, an action happens.
2. **Never fabricate results.** Tool calls are the source of truth; the model's job is to dispatch and summarize, not to invent.

Callers can override the system prompt by passing `system` to `runAgent()`.

## Programmatic use

`runAgent()` is the library entry point — usable wherever a holon wants to embed natural-language intelligence (a bot handler, a webhook, a scheduled job):

```ts
import { runAgent } from '@holons/ai-ui';

const result = await runAgent("Create a task: water the seedlings", {
  model: 'claude-sonnet-4-6',
  maxIterations: 5,
});

console.log(result.text);
console.log(`tools called in ${result.iterations} turns`);
console.log(`stopped because: ${result.stopReason}`);
```

The returned `AgentResult` includes the final text, the iteration count, the last stop reason, and the full message transcript—useful for debugging or for feeding back into another loop.

## Testing

`packages/ai-ui/src/tools.test.ts` covers the command→tool conversion and the registry fallback. The agent loop is testable by injecting a pre-built `Anthropic` client into `runAgent({ client })`—no network needed for unit tests.

## When to use it

Pick `@holons/ai-ui` when:

* A holon's own code (a bot, a cron job, a script) wants to interpret natural-language input.
* You're comfortable shipping the Anthropic SDK as part of your holon's runtime.
* The agent should run **on behalf of** the holon, not as a separate user identity.

Pick the [MCP server](/software/mcp-server) when:

* An external client (Claude Desktop, an IDE) should be able to drive the holon.
* Multiple AI agents may connect concurrently with different actor identities.
* The integration should follow the standard MCP protocol rather than a Holons-specific API.

## See also

* [MCP Server](/software/mcp-server) — the out-of-process complement
* [Harvest](/software/harvest-dashboard) — the monorepo `@holons/ai-ui` is part of
* [HolonsBot](/software/holonsbot) — a natural place to embed an in-process agent loop
* [Glossary](/getting-started/glossary) — vocabulary for the protocol concepts the agent acts on


# Holons types (flavor)

Composable patterns for shaping a holon's behavior

A holon is a unit that is both a whole and a part. The Holons protocol does not enforce one shape for that unit—instead, it offers a small set of **flavors** that can be applied independently or combined. Each flavor answers a different question about how a holon operates.

| Flavor                                                                 | The question it answers                                        |
| ---------------------------------------------------------------------- | -------------------------------------------------------------- |
| [Splitter Holon](/software/holons-types-flavor/splitter-holon)         | How are incoming resources routed to multiple destinations?    |
| [Managed Holon](/software/holons-types-flavor/managed-holon)           | How are work, roles, and communication coordinated day-to-day? |
| [Zoned Holon](/software/holons-types-flavor/zoned-holon)               | How is membership stratified by depth of participation?        |
| [Appreciative Holon](/software/holons-types-flavor/appreciative-holon) | How are contributions recognized and weighted?                 |

These are not mutually exclusive categories. A real holon is usually several flavors at once: a community might be **Managed** (coordinated through a bot), **Appreciative** (its value system runs on peer recognition), **Zoned** (membership has depth), and contain a **Splitter** at its boundary to route incoming funds. The flavors are composable lenses, not exclusive types.

## How to pick a flavor

Start from the problem the holon is actually facing:

* If resources are arriving and need to be **distributed** — start with a [Splitter Holon](/software/holons-types-flavor/splitter-holon).
* If a group is already coordinating in chat and needs **structure** — start with a [Managed Holon](/software/holons-types-flavor/managed-holon).
* If contributions come in many forms and members need **different depths of involvement** — start with a [Zoned Holon](/software/holons-types-flavor/zoned-holon).
* If the culture of **recognition** is what makes the holon work — start with an [Appreciative Holon](/software/holons-types-flavor/appreciative-holon).

Once one flavor is in place, layering another is incremental rather than a re-architecture. The same identity, membership, and resource registries serve all of them.

## Related concepts

* [Funding Flow](/getting-started/funding-flow) — the full whitepaper on the primitives (splitters, threshold buckets, value equations, federation) that flavors compose on top of.
* [HolonsBot](/software/holonsbot) — the operational layer that makes most Managed and Appreciative Holons run in practice.
* [HoloSphere](/software/holosphere) — the spatial / federation substrate that lets holons of any flavor find and connect to each other.


# Splitter Holon

A **Splitter Holon** is a holon whose primary function is to route incoming resources to multiple destinations according to a configurable distribution rule. It is the foundational primitive for translating an inflow of value—money, tokens, hours of attention, access rights—into outflows that respect the priorities of the participants.

Where a generic holon holds resources, a Splitter Holon **moves** them. Every other holon type can be composed with a Splitter when distribution logic is needed.

## How it works

A Splitter Holon is configured with a set of destinations (other holons, wallets, or pools) and an allocation rule. When resources arrive, the rule is applied automatically.

The simplest form is a percentage split:

> "70% to direct contributors, 30% to the ecosystem pool."

Splitters can also condition allocations on a \[\[value-equation]]—for example, distributing a pool to contributors in proportion to logged hours, appreciations, and delivered outcomes.

## The dial: internal vs. external

The most common Splitter pattern in Holonic Funding is the **dual-mechanism splitter**, which has a single adjustable dial (0–100%) governing the split between two channels:

* **Internal flows (Mechanism A)** — rewards for direct contribution inside the holon.
* **External flows (Mechanism B)** — rewards routed to ecosystem partners through declared relational priorities.

| Dial position | Behavior                                                 |
| ------------- | -------------------------------------------------------- |
| 0%            | All resources to internal contributors (siloed)          |
| 50%           | Balanced internal/external flows                         |
| 100%          | All resources to ecosystem partners (pure collaboration) |

Communities adjust the dial based on their stage:

* **Early stage** — high internal, to build capacity.
* **Growth stage** — balanced, to build and connect.
* **Mature stage** — high external, to invest in the ecosystem.

## When to use a Splitter Holon

Use a Splitter Holon when:

* A pool of incoming resources must be divided across multiple parties on a recurring basis.
* The split should be transparent and changeable by the participants rather than by a custodian.
* You need to route overflow (anything above a threshold) to a different destination — for example, into a federated mutual-aid pool.

## Composition

Splitter Holons compose naturally with other primitives:

* With a **threshold bucket**, the Splitter only fires once minimum needs are met, and overflow goes to a downstream holon.
* With a **federation contract**, the external side of the dial can fan out across an entire trust graph instead of a single partner.
* With a **value equation module**, the internal side can be weighted by contribution data rather than fixed percentages.

See [Funding Flow](/getting-started/funding-flow) for the full whitepaper treatment of splitter contracts and distribution mechanisms.


# Managed Holon

A **Managed Holon** is a holon whose internal operations—tasks, roles, communication, and day-to-day coordination—are facilitated through an active manager. In the current Holons stack that manager is typically the [HolonsBot](/software/holonsbot) running inside a Telegram group, but the same pattern applies to any holon where coordination is mediated by a shared tool rather than left to ad-hoc conversation.

Where a Splitter Holon governs **flow of resources**, a Managed Holon governs **flow of work and attention**.

## What "managed" means here

A Managed Holon has at least the following elements explicitly tracked, rather than living in chat history or human memory:

* **Purpose** — a stated reason for the holon to exist, visible to every member.
* **Roles** — defined functions (e.g. `cook`, `gardener`, `facilitator`) that members can hold.
* **Tasks** — open commitments, completed actions, and their history.
* **Recognition** — appreciations and contribution points that update reputation over time.
* **Membership** — a clear boundary of who is in the holon and at what level of participation.

The manager (HolonsBot or equivalent) is what keeps these elements coherent without requiring a human administrator to act as a bottleneck.

## How it works in practice

A typical Managed Holon on Telegram is set up by following [Setting up your holonic organization](/daos/setting-up-your-holonic-organization):

1. Create a group chat for the holon and add the bot as an administrator.
2. Declare the holon's purpose so every new member sees it.
3. Use commands such as `/task`, `/setroles`, `/assignroles`, `/appreciate`, and `/facilitate` to make ongoing coordination explicit.
4. Federate with sibling holons via `/federate` to participate in larger structures.

Members interact with the holon through everyday chat; the bot quietly captures the structure—who committed to what, who recognized whom, what the current role distribution looks like—and exposes it through commands like `/tasks`, `/status`, `/board`, and `/dashboard`.

See the full [HolonsBot commands](/software/holonsbot/holonsbot-commands) reference for the available verbs.

## When to use a Managed Holon

Choose this flavor when:

* The group is already coordinating through chat and wants structure without leaving the tool they use.
* Roles, tasks, and contributions need to be **legible** to everyone, not just to a coordinator.
* The holon will eventually need to compose with other flavors—for example, feeding a [Splitter Holon](/software/holons-types-flavor/splitter-holon) with contribution data, or layering an [Appreciative Holon](/software/holons-types-flavor/appreciative-holon) value system on top.

A Managed Holon is often the **starting point**: once a group's coordination is captured in a manager, it becomes practical to add splitter logic, zone membership, or appreciation-weighted value equations on top of the same data.


# Zoned Holon

A **Zoned Holon** is a holon whose membership is stratified into concentric zones, each representing a different depth of commitment, responsibility, and access. Instead of a binary "member / not a member," participation is graded: people move inward as they take on more responsibility, and outward as their involvement shifts.

This pattern mirrors how living communities actually work—there is rarely a single class of "member"—and it lets a holon recognize many forms of contribution without forcing everyone into the same role.

## How zones work

Each zone defines:

* A **depth of participation** (from anchoring operations to occasional support).
* The **rights** that come with that depth (governance voting, treasury access, ability to onboard others, etc.).
* The **expectations** placed on members at that level.
* The **value weight** their contributions carry in the holon's [value equation](/getting-started/funding-flow).

Movement between zones is not promotion in the traditional sense. It is a continuous adjustment: as someone takes on more, they move toward the core; as they step back, they move outward. The system is designed so that **the right people end up in the right roles** without rigid status hierarchies.

## Example zone structure

A common four-zone configuration:

* **Zone 1 — Core Stewards.** Anchor operational roles. Ensure stability and continuity. Hold the highest level of trust and treasury access.
* **Zone 2 — Active Contributors.** Regularly participate in governance, projects, and development. Carry most of the day-to-day work.
* **Zone 3 — Ambassadors.** Represent the holon outward—spread the work, attract new members, build relationships with adjacent holons.
* **Zone 4 — Supporters.** Provide financial or resource-based contributions without active participation. Still recognized as part of the holon.

Each participant moves between zones based on their involvement and the value they bring. The system dynamically adjusts, ensuring meaningful participation is incentivized at every depth.

## Zoned Holon vs. Relational Zones

These two concepts share a name but operate at different scales—worth keeping straight:

* A **Zoned Holon** describes the **internal** membership structure of a single holon (Zone 1 → Zone 4 as above).
* **Relational Zones**, in the [funding flow](/getting-started/funding-flow) primitives, describe **bilateral economic relationships between separate holons**—e.g., "I'll share my space if you share your expertise." They live on the external side of the [Splitter Holon](/software/holons-types-flavor/splitter-holon) dial.

A holon can be Zoned internally **and** participate in Relational Zones externally; the two compose cleanly.

## When to use a Zoned Holon

Choose this flavor when:

* Contributions arrive in very different forms (time, money, advocacy, advisory) and you want each to be visible and valued.
* The holon needs a clear path for deeper involvement without creating gate-kept hierarchies.
* Governance rights, treasury access, or value-equation weighting should scale with depth of participation rather than being uniform.

Zoned structure pairs well with an [Appreciative Holon](/software/holons-types-flavor/appreciative-holon) value system, since appreciations can both signal and trigger movement between zones.


# Appreciative Holon

An **Appreciative Holon** is a holon whose value system is anchored in peer recognition. Contributions are surfaced and weighted primarily through **appreciations**—explicit acts of recognition members give each other—rather than through hours logged, tickets closed, or top-down evaluation.

Where a Splitter Holon distributes resources and a Managed Holon coordinates work, an Appreciative Holon decides **what counts as valuable in the first place**. The appreciation record is what feeds the holon's [value equation](/getting-started/funding-flow), and through that, downstream things like splits, rewards, and reputation.

## The appreciation framework

Members express recognition through a simple verb. In the [HolonsBot](/software/holonsbot), this is:

```
/appreciate @user [reason]
```

Example:

```
/appreciate @laura for taking care of the garden
```

Each appreciation is a public, attributable signal. Over time, these signals accumulate into a transparent record of participation, visible to the whole holon via `/status`. The record fosters **coopetition**—collaborative competition where members are motivated to contribute toward shared goals in a supportive environment rather than to extract individual reward. This is one of the patterns that operationalises [THEOS](/software/the-holonic-earth-operating-system)'s first objective: "facilitate prosocial coordination, favouring co-creation and collaboration over competition."

See [HolonsBot commands](/software/holonsbot/holonsbot-commands) for the full appreciation, status, and weights interface.

## How appreciations become value

Appreciations are one input among several in a holon's value equation. A typical formulation:

```
Points = (Hours × Hour_Weight) +
         (Appreciations × Appreciation_Weight) +
         (Outcomes_Delivered × Outcome_Weight)

Share  = Points_Individual / Points_Total
```

What makes a holon **Appreciative** is the relative weight: appreciations are the dominant or defining signal. The `/weights` command lets the holon collectively decide how much each type of contribution counts.

This means two holons can run identical software and produce very different cultures—one rewarding hours, another rewarding peer recognition—simply by tuning the weights.

## Why anchor on appreciation

* **Captures invisible work.** Care, facilitation, emotional labor, mentorship, and relationship-building rarely show up in ticket trackers. They show up clearly in appreciations.
* **Aligns with the holon's stated values.** Each holon (or membrane) defines what it values; appreciations are how members vote on that, continuously, in everyday language.
* **Resists gaming.** Unlike self-reported hours, appreciations require another person to vouch for the contribution. This builds a relational rather than transactional record.
* **Composes with federation.** When holons federate, appreciation data can flow across membrane boundaries, letting recognition in one community translate into standing in another.

## When to use an Appreciative Holon

Choose this flavor when:

* Much of the holon's real value creation is hard to measure with conventional metrics.
* The community wants its **culture of recognition** to be the primary engine of reputation and reward, not a secondary nicety.
* You plan to compose with a [Splitter Holon](/software/holons-types-flavor/splitter-holon), [Zoned Holon](/software/holons-types-flavor/zoned-holon), or federation contract that consumes contribution points—appreciations become a high-quality input for all of them.

Appreciation is the simplest interface for making relationships economically meaningful, which is the core promise of the Holons protocol.


# HolonsBot

The Conversational Interface for Holonic Coordination

**HolonsBot** is the real-time, conversational interface that brings holonic coordination to life. It translates the complexity of value flows, commitments, and inter-holon relationships into an intuitive, human-centered experience. Instead of navigating dashboards or smart-contract primitives directly, users interact with their holonic ecosystem through a simple message: *“What needs attention right now?”*

HolonsBot acts as the **bridge between humans and the holonic network**, orchestrating clarity, accountability, and flow across any context — from distributed teams and bioregional hubs to global regenerative alliances.

***

### **Key Functions**

#### **1. Contextual Awareness**

HolonsBot maintains a live understanding of:

* the structure of the holonic network,
* open commitments and resource flows,
* the current state of tasks, requests, and thresholds,
* the relationships between individuals, roles, holons, and federations.

It becomes an intelligent companion that can answer:\
\&#xNAN;*“What is the current load on our kitchen steward holon?”*\
\&#xNAN;*“Which commitments require action before the new moon?”*

***

#### **2. Conversational Task & Commitment Management**

Users can create, update, split, merge, or complete tasks using natural language:

* “Create a 3-way split of the garden maintenance task for this week.”
* “Assign me to the water-system inspection.”
* “Show me tasks with expiring commitments.”

HolonsBot automatically writes/updates the corresponding commitments in the **Commitment Registry**, ensuring perfect traceability.

***

#### **3. Holonic Funding Orchestration**

HolonsBot interacts directly with the holonic financial layer:

* Deploying new Holons (resource hubs, pools, buckets)
* Configuring flow splitters and routing rules
* Visualizing token bonding curve dynamics
* Initiating flows between holons (“Send 50% of incoming flows from Event Holon to Kitchen Holon until the threshold is met.”)

This gives communities a real-time window into their economic nervous system.

***

#### **4. Governance & Decision Support**

Within federated networks, HolonsBot can:

* facilitate consent-based proposals,
* manage signaling rounds,
* route decisions to the correct holon or role,
* track delegation chains in liquid governance,
* surface risks, tensions, or capacity constraints.

The bot becomes a neutral facilitator that keeps governance lightweight and actionable.

***

#### **5. Personalized Guidance for Each User**

HolonsBot recognizes:

* each user’s roles,
* commitments,
* zones of contribution,
* energy levels and availability (if shared),
* and their connection to specific hubs or holons.

It can say:

* “You have reached your weekly limit of 5 ongoing tasks.”
* “Your steward role requires attention in the next 24 hours.”
* “Two of your delegated responsibilities have open thresholds.”

This helps maintain balance, reduce burnout, and increase autonomy.

***

#### **6. Multi-Modal Interaction**

HolonsBot supports interaction via:

* Telegram / WhatsApp (for communities)
* Web widget inside the Holons dashboard
* API endpoints for hubs or DAOs
* Voice interfaces for accessibility in fieldwork (gardens, forests, disaster relief)

This allows holonic coordination wherever people actually work and live.

***

### **Technical Overview**

HolonsBot sits at the intersection of three architectural layers:

#### **1. Conversational Understanding Layer**

A fine-tuned LLM interprets user intent and maps it to holonic primitives:

* Holons
* Pools & buckets
* Splitters
* Value equations
* Commitments
* Federations
* Mutations & thresholds

#### **2. Orchestration Layer**

A deterministic parser converts intent into:

* contract calls
* database queries
* updates to the Commitment Registry
* notifications
* validations (“this flow violates a threshold rule”)

#### **3. Execution Layer**

The bot triggers transactions or queries across:

* Holonic smart contracts
* Off-chain commitment stores
* Federated data (hub-to-hub)
* Optional TEE/zk modules for encrypted governance

This creates a seamless flow from **spoken need → interpretable action → auditable output**.

***

### Getting started with HolonsBot

To put HolonsBot to work in your community:

1. Follow [Setting up your holonic organization](/daos/setting-up-your-holonic-organization) to create the chat structure and add the bot.
2. Use [Managing your organization](/daos/managing-your-organization) for ongoing coordination patterns.
3. Reference the full [HolonsBot commands](/software/holonsbot/holonsbot-commands) list for the available verbs.

For the conceptual frame of what HolonsBot is doing under the hood, see [Managed Holon](/software/holons-types-flavor/managed-holon) and the [Glossary](/getting-started/glossary).


# HolonsBot commands

### Task Management

* `/task [description]` - Creates a new task
  * Example: `/task do the dishes`
* `/tasks` - Lists currently open tasks
* `/actions` - Lists the history of completed tasks

### Recognition & Value System

* `/appreciate [@user] [reason]` - Sends appreciation to the listed user
  * Example: `/appreciate @laura for taking care of the garden`
* `/status` - Shows rank of user according to the value points
* `/weights` - Changes the points assigned to each action

### Needs & Offers

* `/request [description]` - Something you would like to have
  * Example: `/request foot massage`
* `/offer [description]` - Something you would like to give
  * Example: `/offer yoga sessions`
* `/board` - Lists all users' requests and offers

### Community & Facilitation

* `/prompt` - Indicates the day of the current lunation, together with a suggested team activity
* `/facilitate [issue]` - Gives advice on community issues
  * Example: `/facilitate i don't feel recognized`
* `/bigtalk` - Get to know each other better by collectively answering the prompt

### Role Management

* `/assignroles` - Assigns roles to members of the community based on their actions
* `/setroles [roles]` - Defines roles within the community
  * Example: `/setroles cook, gardener`

### Shopping & Expenses

* `/buy [item]` - Adds an item to the shopping list
  * Example: `/buy milk`
* `/shopping` - Displays the shopping list as clickable items
* `/spent` - Submits an expense in the format /spent \[quantity] \[currency] \[reason]
  * Example: /spent 10 euros shopping
* `/balance` - Prints balance table /balance \[currency]

### Personal Values & Needs

* `/ivalue` - Allows to specify the list of values for the user
* `/values [@users]` - Visualizes the shared values of the specified users, or of all users
* `/ineed` - Allows to specify the list of needs for the user
* `/needs [@users]` - Visualizes the shared needs of the specified users, or of all users

### Holon Management

* `/restart` - Resets everything, all data will be lost.
* `/fork` - Unbinds federated chats
* `/federate` - Federates with another holon

### Content Management

* `/tag [tag]` - Saves content under the specified tag
* `/publish` - Saves the content in the holosphere
* `/cast` - Saves the content on every scale in the holosphere
* `/summarize` - Listens to the conversation and summarises it when `/done` is entered

### System & Interface

* `/settings` - Opens up the configuration interface
* `/dashboard` - A direct link to the web dashboard
* `/checklists` - Opens up the list of checklists
* `/agenda` - Opens up the agenda interface


# Setting up your holonic organization

Setting Up a Fractal Organization using Telegram

Establishing a fractal holonic organization using Telegram involves structuring conversations to unify different chats effectively. Here’s how you can accomplish this:

1. **Create Chats for Each Holon**: Initiate group chats dedicated to each holon, allowing members to communicate effectively within their specific roles. This setup ensures that discussions are targeted and relevant to the tasks and responsibilities of each group.
2. **Establish a Central Communication Hub**: Form a main chat group to act as the central communication hub. This hub will serve as the linking point for all holons, enabling holistic oversight and fostering interconnectedness.
3. **Integrate the Holons Bot**: Add the @HolonsBot within each chat group to facilitate seamless management and operation. The bot can help automate tasks, manage permissions, and maintain order within the groups, thereby increasing efficiency.
4. **Setup the channel:** Enable topics, make history visible, and give admin rights to the telegram bot.
5. **Organize and Share Chat Links**: Make sure that each holon’s chat link is shared within the central hub to promote easy access and navigation. This organization will help members move between holons and maintain a holistic view of the organization’s activities.
6. **Adopt a Consistent Naming Convention**: Apply a clear and consistent naming convention for each chat that reflects the function and level of the holon it represents. This approach prevents confusion and aids in quick identification of each group’s purpose.
7. **Regularly Update and Reassess Structure**: Periodically review and update the chat structure and organization as the organization grows or evolves. Make adjustments based on feedback and changing needs to ensure the structure remains efficient and effective.

By following these steps, you can leverage Telegram to create a well-organized and dynamic fractal holonic organization. This setup will enhance communication, streamline operations, and support sustainable growth across all levels of your organizational structure.


# Managing your organization

Once your organization is set up, it's key to manage and maintain its structure for effectiveness. Here's how you can do it with the Holons Bot:

1. **Define Purpose:** Make clear what the purpose of the (sub) holon is, so that everyone can be driven by it
2. **Assign Roles**: Clearly define and assign roles within each holon to ensure clarity in tasks and responsibilities.
3. **Communication**: Use the bot to facilitate communication across different holons and levels, preserving transparency.
4. **Adaptation**: Regularly assess and adapt the holarchy as the organization evolves, using insights and feedback obtained through the bot.
5. **Review and Feedback**: Implement periodic reviews of processes and solicit feedback to enhance collaboration and efficiency.
6. **Expand**: As your organization grows, utilize the bot to seamlessly add new members and holons, ensuring consistency in the scaling process.

Implementing these strategies will help maintain a robust and dynamic organizational structure, enabling sustainable growth and responsiveness.


# Agreements

Explicit, programmable commitments between holons and their members

In the Holons protocol, **agreements** are the explicit contracts that make a holon's coordination legible. They describe who has committed to what, with whom, under which conditions, and how the result will be tracked.

Where casual coordination relies on shared memory and trust, holonic agreements turn intentions into structured records that can be referenced, validated, and acted on by both humans and contracts. This is what makes it possible for autonomous holons to collaborate across organizational boundaries without giving up their independence.

## What an agreement looks like

A holonic agreement typically captures:

* **The parties.** Which holons or individuals are involved.
* **The purpose.** What the agreement is for, in the holon's own terms.
* **The contributions and flows.** What resources move, in which direction, under what rules.
* **The value system.** Which contributions are recognized, and how they are weighted in the [value equation](/getting-started/glossary#value-equation).
* **The governance.** How decisions are made and how conflicts are resolved.
* **The duration and review.** When the agreement starts, when it is revisited, and how it can change.

These same elements show up at every scale—from a two-person Memorandum of Understanding to a federation contract spanning many holons.

## Where agreements live

Agreements operate on two layers:

* **Human-readable text** — the kind of document people sign. The [Memorandum of Understanding](/agreements/memorandum-of-understanding) is a canonical example and a useful starting template.
* **Programmable contracts** — the on-chain or off-chain records that enforce flow, track commitments, and update reputation. These are managed by the [Commitment Registry](/getting-started/glossary#commitment-registry) and related primitives described in [Funding Flow](/getting-started/funding-flow).

A working holon usually has both: a written agreement that members can read and discuss, paired with the corresponding contract configuration that makes the agreement enforceable in practice.

## Where to go next

* [Memorandum of Understanding](/agreements/memorandum-of-understanding) — a template agreement for participants collaborating on THEOS.
* [Funding Flow](/getting-started/funding-flow) — the primitives (Commitment Registry, splitters, thresholds, federation contracts) that make agreements programmable.
* [Setting up your holonic organization](/daos/setting-up-your-holonic-organization) — how to start a holon whose agreements are operationalized through the [HolonsBot](/software/holonsbot).


# Memorandum of Understanding

Between:

Participants Collaborating on the Development of the Holonic Earth Operating System (THEOS)

Purpose:

This MoU establishes a framework for collaboration among individuals and groups working on THEOS. Participants will actively use THEOS to test its features, principles, and effectiveness (“dogfooding”) while refining its functionality. The overarching objective is to create a regenerative economic model that fosters collaboration and innovation, with a specific focus on ensuring sustainability and equitable distribution of resources.

1\. Core Agreements

1.1 Shared Vision

Participants commit to advancing the development of THEOS to create a system that aligns with principles of holonic organization, equity, transparency, and regeneration.

1.2 Collaborative Participation

Participants agree to work collaboratively within a holon (a defined group or membrane) and use the tools and processes of THEOS for decision-making, resource allocation, and governance.

2\. Structure of Collaboration

2.1 Resource Contributions

Each iteration begins with participants contributing resources (financial or otherwise) into the shared holon pool. Contributions are logged and tracked transparently using theos.

2.2 Allocation Process

Participants within the holon collectively decide how the pooled resources are allocated, using sociocratic principles or other consent-based decision-making methods embedded in theos.

2.3 Iterative Funding Goal

The objective for each iteration is to raise at least the same amount of value as in the previous round. Contributions exceeding this target enhance the collective fund.

2.4 Matching Fund

An external funder (or matched funding mechanism) agrees to match the holon’s raised amount from the previous iteration, doubling the available resources for that cycle.

3\. Governance and Decision-Making

3.1 Holon Autonomy

Each holon operates autonomously, defining its goals, values, and decision-making processes, while adhering to the overarching principles of THEOS.

3.2 Shared DNA

All participants agree to abide by a shared set of values, principles, and objectives that guide collaboration, including transparency, equity, and regeneration.

3.3 Conflict Resolution

Any disputes or conflicts arising within the holon will be resolved using THEOS-supported sociocratic practices or other agreed-upon conflict resolution mechanisms.

4\. Appreciation and Value Tracking

4.1 Transparent Contributions

All contributions and participations are transparently logged and visible within theos, ensuring accountability and trust.

4.2 Appreciation Framework

Participants use appreciation mechanisms to recognize valuable contributions, ensuring alignment with the holon’s defined goals and priorities.

4.3 Incentives

In addition to matched funding, contributors may receive reputational or tangible rewards based on their contributions, as determined by the holon.

5\. Responsibilities of Participants

5.1 Active Engagement

Participants commit to actively engaging in discussions, decision-making, and implementation of tasks related to theos development and use.

5.2 Feedback and Refinement

Participants agree to provide constructive feedback and insights to improve theos, ensuring its scalability, usability, and impact.

5.3 Ethical Conduct

All participants agree to adhere to ethical principles, fostering an inclusive, supportive, and innovative environment.

6\. Duration and Review

6.1 Pilot Period

The initial collaboration under this MoU will run for a specified period (e.g., 6 months) to test and refine theos.

6.2 Review and Adjustment

At the end of each cycle, participants will review outcomes, document lessons learned, and adjust the collaboration framework as needed.

7\. Signatories

By signing this MoU, participants affirm their commitment to collaboratively develop, test, and refine the Holonic Earth Operating System.

Signed on \[Date]:

• \[Participant Name and Role]

• \[Participant Name and Role]

• \[Fund Representative Name and Role, if applicable]


# Non-Profit Associations

Non-profit organizations and social impact associations increasingly operate across distributed teams, decentralized territories, and multi-stakeholder collaborations. Traditional project management and accounting tools struggle to track real contributions, coordinate resources transparently, and sustain trust across diverse participants.\
A holonic coordination layer offers a shared economic and organizational substrate that enhances accountability, autonomy, and collective intelligence.

***

### Why It Matters

Non-profits and social impact networks navigate complex environments:

* volunteers with unpredictable availability
* multiple funding streams and grant conditions
* distributed partner organizations
* in-kind contributions, donated labor, and non-monetary exchanges
* impact metrics that are hard to track or validate

Holonic coordination provides a **transparent, interoperable, and accountability-driven** structure that aligns people, projects, and resources without adding bureaucratic overhead.

***

### What It Enables

#### **1. Transparent, Multi-Resource Contribution Tracking**

Every contribution—hours worked, materials donated, expertise shared, equipment lent, spaces offered—can be registered as a resource flow.\
This allows associations to:

* demonstrate real value created beyond financial accounting
* report to funders with credible, granular metrics
* recognize volunteers and contributors in meaningful ways
* build trust through transparent collective ownership of outcomes

***

#### **2. Project-Based Budgets With Collective Governance**

Each project, initiative, working group, or event can hold its own budget and define how resources flow in and out.\
Key outcomes:

* micro-budgets aligned to mission goals
* multi-stakeholder permissioning
* simple participatory governance (e.g., stewards approve spending)
* economic clarity even in highly collaborative environments

***

#### **3. Fractal Organizational Structure**

Non-profits often grow into networks: chapters, local groups, thematic clusters, partner initiatives.\
The holonic structure mirrors this:

* each team/project is autonomous
* all can interoperate across a shared infrastructure
* contributions to local groups can be recognized at the global scale
* funding can flow to the right layer—local, regional, global—without confusion

***

#### **4. Grant Management With Automated Reporting**

Grants can be represented as programmable buckets.\
Funds are released only when conditions are met, such as:

* matching contributions
* specific deliverables
* verified impact metrics
* milestone completion\
  Reporting becomes **automatic**, since all flows and commitments are already recorded.

***

#### **5. In-Kind Economy & Mutual Support Systems**

Associations can create an internal value system where:

* volunteers accumulate credits for their contributions
* credits can be redeemed for courses, events, services, accommodation, tools, or food
* partner organizations can exchange labor, materials, and expertise
* value circulates locally, strengthening community resilience

This creates a **regenerative economic layer** without introducing speculative tokens or complexity.

***

#### **6. Coalition Building & Inter-Association Collaboration**

When multiple associations collaborate, coordination is typically messy.\
A holonic layer enables:

* interoperable budgets
* shared milestones
* transparent co-funding
* cross-organizational contribution recognition
* unified impact dashboards\
  Each partner retains autonomy while benefiting from shared infrastructure.

***

### Use Cases

* **Community centers** tracking volunteer labor, tools, and shared spaces
* **Environmental organizations** coordinating restoration, monitoring, and regenerative projects
* **Mutual aid networks** coordinating resources during emergencies
* **Cultural associations** running events with distributed teams
* **Educational programs** tracking teaching hours, materials, and scholarship flows
* **Faith- or values-based communities** stewarding donations, service hours, and programs
* **Bioregional clusters** weaving multiple hubs and local groups into a coherent ecosystem

***

### Benefits at a Glance

| Challenge                  | Holonic Advantage                                    |
| -------------------------- | ---------------------------------------------------- |
| Fragmented coordination    | Shared, programmable resource flows                  |
| Invisible volunteer work   | Transparent multi-resource contribution registry     |
| Opaque budgets & reporting | Automatic, real-time financial and impact dashboards |
| Governance bottlenecks     | Role-based, fractal, permissioned decision flows     |
| Donor trust issues         | Verifiable, auditable, open accountability           |
| Lack of interoperability   | Cross-project, cross-association collaboration layer |

***

### Outcome

Non-profits gain a **lightweight but powerful coordination engine** that elevates trust, transparency, and autonomy—supporting mission-aligned work while reducing administrative load.\
Social impact associations can finally operate like **living, adaptive organisms** capable of coordinating resources with clarity, integrity, and shared purpose.


# Enlightened Businesses

A Coordination Framework for Purpose-Driven Organisations

Enlightened businesses operate as living systems — balancing purpose, people, and planetary wellbeing. To function in this way, they require organisational architectures that honour autonomy, illuminate contributions, and enable trust-based collaboration.\
Holons provide this foundation: semi-autonomous units of value, purpose, and responsibility that can self-organise while remaining part of a larger whole.

### Why Enlightened Businesses Need Holonic Architecture

Traditional organisational structures struggle to support conscious, regenerative, or purpose-aligned enterprises because they:

* **Reduce value to money**, ignoring care work, creativity, stewardship, and relational capital.
* **Centralise authority**, limiting responsiveness and collective intelligence.
* **Hide contributions and commitments**, causing misalignment or burnout.
* **Lack a way to scale purpose**, especially across distributed teams or multi-hub networks.

Holons address these structural gaps by making relationships, commitments, and resource flows explicit, transparent, and coordinated through living agreements.

### What Holons Make Possible

#### 1. **Purpose-Aligned Value Flows**

Holons route resources—funds, time, materials, impact credits—directly toward specific missions or teams.\
Purpose stops being a slogan and becomes a *flow dynamic* embedded in the organisation’s DNA.

#### 2. **Multi-Resource Contribution Tracking**

Each Holon can track labour, creativity, material inputs, mentorship, care, or environmental regeneration.\
This allows enlightened businesses to:

* honour invisible work
* create fairer incentive structures
* reward contribution, not hierarchy
* recognise stewardship as value

#### 3. **Living Agreements & Commitments**

Holons encode commitments: roles, responsibilities, deliverables, thresholds, and shared expectations.\
This removes the need for heavy management while increasing clarity and coherence.

#### 4. **Fractal Governance**

Holons are naturally nestable: individuals → teams → projects → departments → the whole organisation.\
This structure supports:

* autonomy at every scale
* shared purpose without centralisation
* continuous adaptation
* clarity in complex relational work

#### 5. **Transparent Impact Accounting**

Every Holon can track its own impact—financial, ecological, social, organisational.\
Enlightened businesses gain the ability to:

* prove integrity
* show regenerative outcomes
* make decisions based on real flows

### Example Applications

#### ● Regenerative Enterprises

Holons represent farms, garden zones, production lines, or training programs—enabling them to exchange value, track labour, and direct resources regeneratively.

#### ● Conscious Consulting & Coaching Studios

Holons track client journeys, team contributions, and revenue splits with fairness and transparency.

#### ● Creative, Cultural & Healing Organisations

Art collectives, wellness centres, and educational hubs can record contributions, share ownership of projects, and honour emotional/relational labour.

#### ● Multi-Hub Ecosystems

Networks of hubs can organise as interconnected Holons, coordinating resources, trainings, events, and regenerative impact across regions.

### Benefits for Enlightened Businesses

* **Alignment becomes operational**
* **Purpose flows through the organisation**
* **Teams self-organise with clarity and autonomy**
* **Contributions are visible, valued, and rewarded**
* **Impact becomes measurable and trustworthy**
* **The business evolves as a conscious ecosystem**


# DAO Tooling

Coordinating a DAO with Holonic Infrastructure

Decentralized Autonomous Organizations struggle with one recurring challenge: **coordinating diverse contributions, resources, and decisions across fluid, ever-changing groups of people.** Traditional DAO tooling focuses on voting, treasury management, or token distribution, but rarely on the *underlying coordination patterns* that make collective action reliable, transparent, and scalable.

A holonic architecture provides DAOs with **fractal coordination primitives** that allow each working group, project pod, or task force to self-organize autonomously while remaining part of an interdependent whole. This creates a governance and funding system that is both **decentralized and coherent**, supporting everything from micro-tasks to multi-stakeholder programs.

***

### Why DAOs Need a Holonic Layer

Most DAOs operate in a tension between:

* **local autonomy** (circles, pods, guilds that want freedom)
* **network-level coherence** (the need for shared treasuries, metrics, and governance)
* **fair compensation** for diverse contributions
* **transparent flow of resources**
* **verifiable commitments** among members

Holonic coordination introduces building blocks that allow DAOs to structure themselves as **nested, interoperable units**, where each unit manages its own commitments, flows, and rules while contributing to the larger DAO.

***

### Core Capabilities for DAO Coordination

#### **1. Federated Contribution Tracking**

Each circle, squad, or project maintains its own contribution registry.\
Hours, skills, materials, or outcomes are logged at the local level yet automatically aggregated across the DAO.\
This enables **fair value representation** without forcing a single contribution standard on every group.

#### **2. Multi-Treasury Resource Routing**

Instead of one central treasury, a DAO can operate with **nested treasuries**:\
task → project → working group → DAO multisig.\
Resources automatically flow along predefined sharing agreements, providing clarity and traceability without bottlenecks.

#### **3. Dynamic Roles and Agreements**

Any group can define:

* its purpose
* its accountabilities
* its decision-making protocol
* its contribution policies

These agreements become **smart-contract-encoded**, making governance both flexible and enforceable.

#### **4. Fractal Governance**

Circles can independently organize proposals, votes, and decision processes that suit their culture while still aligning with the wider DAO through:

* delegation flows
* topic-specific sub-circles
* shared meta-governance templates

This blends **liquid democracy**, **holocracy**, and **DAO governance** into one ecosystem.

#### **5. Value Equations & Reward Distribution**

A DAO can define custom rules such as:

* retroactive reward pools
* peer-based evaluation
* outcome-based bonuses
* contribution-weighted token minting

Holonic value equations ensure that every unit uses the model that fits its work while remaining interoperable across the DAO.

#### **6. Inter-DAO Collaboration**

Multiple DAOs can collaborate using the same primitives:

* shared projects
* shared funding pools
* cross-DAO roles
* federated governance

Each DAO keeps its autonomy while coordinating fluidly with partners in a **network-of-networks** model.

***

### What This Enables

#### **A DAO that can finally scale.**

With holonic primitives, a DAO evolves from a single collective to a **living ecosystem** of pods, catalysts, stewards, and working groups.

#### **A treasury that flows like mycelium.**

Resources move through clear, transparent paths aligned with agreements and contributions.

#### **A governance model that adapts to complexity.**

Groups can experiment with their own structures without fragmenting the DAO.

#### **A culture of accountability and shared ownership.**

Every contribution is visible, valued, and embedded in the economic structure.

***

### Use Cases for DAO Tooling

* Multi-pod governance
* Task bounties and contribution markets
* On-chain commitments and delegation
* Multi-sig routing and multi-treasury management
* Cross-DAO collaborations
* Grants tracking and reporting
* Federated teams across ecosystems
* Real-time contribution visibility
* Automated value-flow accounting

***

### Summary

Holonic coordination offers DAOs a **unified foundation for autonomy, transparency, and interoperability**.\
Rather than forcing a one-size-fits-all governance mechanism, it offers **modular, interoperable primitives** that DAOs can compose into their own organizational DNA.

This allows decentralized communities to evolve from loose collectives into **coherent, fractal, regenerative networks** capable of coordinating real value at any scale.


# Bioregional Regeneration

A Distributed Coordination Layer for Land, People & Projects

Bioregional regeneration requires a new kind of economic and governance infrastructure—one capable of aligning diverse actors, tracking real contributions, and weaving distributed projects into a coherent whole. Traditional tools struggle to manage this complexity: data becomes siloed, funding flows are opaque, and initiatives remain isolated even when they share the same landscape.

This coordination layer introduces a federated, smart-contract-based approach designed for bioregions. It enables communities, land stewards, associations, cooperatives, and local administrations to cooperate as a network rather than isolated organizations. By making flows of resources, commitments, and impact transparent and interoperable, it becomes possible to regenerate an entire territory as a living system.

***

### Why a Bioregional Approach Needs New Infrastructure

Bioregional regeneration is inherently multi-stakeholder and multi-resource. A single project may involve:

* Landowners offering access and ecological assets
* Stewards and practitioners providing labor, skills, and knowledge
* Investors supplying capital with regenerative return expectations
* Municipalities contributing permissions, spaces, or public goods
* Citizens offering participation, care work, and local initiatives
* Networks and hubs coordinating learning, governance, and culture

Without shared infrastructure, these elements remain fragmented. The result is duplicated work, uneven participation, misaligned incentives, and funding bottlenecks.

This system provides a unifying orchestration layer that respects autonomy while enabling coordination at scale.

***

### Key Capabilities for Bioregional Regeneration

#### **1. Transparent, Multi-Resource Value Flows**

All forms of capital—financial, ecological, social, intellectual, and material—can be represented and tracked without reducing them to a single metric.\
This allows bioregional actors to coordinate based on real resources rather than abstract budgets.

#### **2. Federated Funding & Circular Economies**

Projects can receive funding from multiple sources—grants, DAOs, public funds, donors—while maintaining transparency over how funds flow through the ecosystem.\
Treasuries can be connected across hubs, enabling circular flows that strengthen the bioregion as a whole.

#### **3. Local Governance With Interoperability**

Each initiative retains local autonomy, yet remains interoperable with others in the bioregion.\
Different governance models (associations, cooperatives, collectives, municipalities, DAOs) can plug into a shared coordination mesh.

#### **4. Commitment & Accountability Layer**

Agreements—tasks, roles, responsibilities, resource exchanges—are formalized and visible to all participants.\
This reduces friction, builds trust, and ensures that regenerative commitments are honored.

#### **5. Cross-Hub Collaboration**

Multiple hubs—ecovillages, learning centers, farms, fablabs, community houses—can coordinate activities, share resources, and co-fund projects.\
A bioregion becomes a distributed regenerative campus.

***

### Example Use Cases in a Bioregional Context

#### **Community Stewardship Agreements**

Landowners can open access to parcels for restoration, gardening, cultural events, or forest management, with clear terms and transparent value exchanges.

#### **Distributed Education & Skill-Sharing Programs**

Training sessions, workshops, and long-term learning pathways can be co-organized across hubs, with resource flows and contributions captured automatically.

#### **Regenerative Enterprise Development**

Mutual-support clusters for local producers, craftspeople, and innovators can pool resources, share infrastructure, and create federated business models.

#### **Bioregional Investment Pools**

Impact investors can channel resources into multiple interconnected projects, enabling risk-mitigation, diversification, and regenerative returns.

#### **Coordinated Ecosystem Restoration**

Rewilding, agroforestry, watershed protection, soil rebuilding, and fire-prevention initiatives can share data, tools, and labor through a common coordination mesh.

***

### Why This Matters

Bioregional regeneration is not only ecological—it is cultural, economic, and relational.\
To restore a landscape, we must restore the fabric of collaboration across its human communities.

This system provides:

* **Clarity** on who does what, with what resources, and for whom
* **Fairness** through transparent, accountable value flows
* **Synergy** by connecting isolated efforts into a cohesive whole
* **Scalability** through a fractal architecture that grows from local to regional to global
* **Resilience** by distributing knowledge, resources, and governance

Bioregions thrive when cooperation becomes effortless and trust becomes embedded in the infrastructure itself.


# Disaster Relief Coordination System

In moments of crisis, communities need an infrastructure capable of moving resources, information, and responsibilities with clarity and trust. This system provides a modular coordination layer that allows responders, local hubs, agencies, and volunteers to self-organize around real-world needs without relying on centralized bottlenecks.

By treating every actor—individuals, field teams, shelters, supply depots, kitchens, medical units, logistics routes, and donor collectives—as autonomous nodes capable of declaring their needs and capacities, the system creates a living, adaptive map of the crisis. It turns complexity into actionable clarity, allowing humanitarian response to scale from neighborhood to city to region with minimal friction.

### Key Capabilities

#### **1. Real-Time Needs & Offers Registry**

Each node can publish:

* Immediate needs (e.g., generators, water, beds, personnel)
* Available capacities (e.g., volunteers, kitchens, vehicles, medical expertise)
* Time-bounded commitments and task durations\
  This creates a dynamic, trustable picture of what is happening on the ground.

#### **2. Transparent Resource Flows**

Resources—material, financial, or human—move through an auditable pathway:

* Supplies flowing from donors → local depots → response teams → affected families
* Volunteer hours flowing from individuals → field tasks → relief outcomes
* Funds flowing into emergency buckets → allocated missions → verified expenses

Nothing gets “lost”; every flow has provenance and clear ownership.

#### **3. Task-Based Coordination**

Any node can:

* Create tasks
* Request support
* Split or merge responsibilities\
  This enables emergent swarm coordination, where the system naturally routes support to where it is most needed.

#### **4. Multi-Scale Organization**

Local teams operate autonomously, but their actions aggregate into higher-level structures:

* Neighbourhood response cells
* Municipal hubs
* Regional response networks
* Cross-border collaborations

Each layer maintains its own integrity while contributing to the whole.

#### **5. Federated Funding for Rapid Response**

Emergency funds can be:

* Assigned to specific missions
* Split across multiple response teams
* Released based on verifiable completion
* Redirected automatically when priorities shift

Funding becomes adaptive, transparent, and aligned with actual needs on the ground.

#### **6. Proof of Contribution**

Every action—delivering supplies, cooking meals, clearing debris, hosting displaced families—is acknowledged.\
This creates:

* Trust between actors
* Accountability
* A verifiable history of who supported what
* Long-term credit for participation in collective resilience

#### **7. Interoperability with Existing Relief Agencies**

The system can be used as:

* A backbone for NGO coordination
* A mesh network between grassroots groups
* A transparent ledger for municipalities
* A funding and reporting layer for donors

It complements, rather than replaces, existing structures.

***

### Example: A Typical Disaster Response Flow

1. **Local assessment teams** declare needs (shelter, food, fuel, medics).
2. **Nearby hubs** respond with available resources and volunteers.
3. **Donors and partner organizations** allocate funds to priority missions.
4. **Task coordinators** create micro-tasks (logistics, transport, cooking, clearing roads).
5. **Contributors** complete tasks and receive proof-of-contribution.
6. **Regional nodes** aggregate data and redirect support where gaps remain.
7. **The entire network** adapts dynamically as conditions change.

The result is a **self-coordinating disaster relief ecosystem** able to respond quickly, transparently, and at scale.


# Game B

Game-B Native Coordination Infrastructure

Game B calls for a shift from extractive, competitive systems to long-term, regenerative coordination. To get there, groups need tools that make collaboration *easier than competition*, and collective intelligence *more rewarding than individual optimization*. This architecture provides the missing substrate: a way for decentralized groups to cooperate, govern resources, and distribute value without central control—while preserving autonomy and enabling scalable coherence.

### From Game A Scarcity to Game B Regeneration

Game A relies on artificial scarcity, competitive advantage, opaque ownership, and zero-sum dynamics. In contrast, Game B demands systems that support:

* Transparent value flows
* Collective sense-making
* Adaptive governance
* Local autonomy nested within global coherence
* Incentive structures aligned with long-term flourishing

The system provides these primitives through composable coordination modules that let any group instantiate agreements, track multi-resource contributions, and evolve governance as complexity grows.

### Fractal, Evolutionary Governance

Game B thrives on *fractal subsidiarity*: governance that starts local, adapts dynamically, and scales without centralization. This architecture enables:

* **Nested coordination units** that can govern shared resources while remaining independent
* **Dynamic delegation and liquid authority** that fits the context rather than fixed hierarchies
* **Transparent commitments** that replace soft expectations with clear mutual agreements
* **Interoperable protocols** so that different communities can evolve diverse governance forms but remain compatible

This makes it possible to build multi-scale networks—local nodes, thematic guilds, bioregional alliances—without losing coherence.

### Multi-Resource Value Recognition

Game B requires acknowledging value far beyond money: care work, ecological regeneration, governance effort, cultural contribution, knowledge creation. The system includes:

* **Multi-resource accounting** to track time, skills, materials, energy, land, and digital resources
* **Transparent contribution registries** to attribute value where it arises
* **Custom scoring and reputation modules** to surface trusted participation

This allows communities to cultivate healthy reciprocity without needing to convert everything into currency.

### Regenerative Economies by Design

Instead of optimizing for extraction, communities can use the architecture to build regenerative, purpose-aligned economies. They can:

* Deploy **value-aligned funding pools** that attract mission-aligned capital
* Use **threshold buckets and flow splitters** to route resources to where they are needed
* Implement **intentional economic boundaries**, ensuring resources circulate within shared missions
* Set up **incentive systems** that reward behaviors supporting the commons

Capital becomes a flow, not a weapon; reinvestment becomes the default behavior, not the exception.

### Collective Intelligence & Sense-Making

Game B coordination depends on high-fidelity information flows. The architecture enables:

* **Context-rich metadata** attached to resources and actions
* **Declarative intent registries** to make plans and dependencies visible
* **Federation protocols** to coordinate across teams and hubs
* **Objective metrics + narrative data**, enabling both measurable and qualitative tracking

This creates the shared situational awareness required for large-scale coherence.

### Building the Next Civilization Stack

Used as a Game B engine, the system allows communities to evolve:

* Regenerative villages and bioregions
* Mutual-aid networks
* Digital commons ecosystems
* Post-capitalist economic experiments
* Distributed educational & research guilds
* Long-term stewardship of land, culture, and infrastructure

The architecture does not impose a fixed ideology. Instead, it offers a **toolkit for building the social technologies Game B needs**—autonomy, transparency, cooperation, regeneration—while allowing groups to experiment with new forms of living, producing, owning, and deciding.


# Family Management System

## Coordinating a Family System

*A Holonic Approach to Daily Life, Shared Resources, and Collective Growth*

Families are living networks. They exchange time, attention, care, and resources every day, yet most of these flows remain invisible. A holonic approach brings clarity, fairness, and shared agency into family life by treating the household as an evolving ecosystem of commitments, needs, and contributions.

***

### 🌱 1. The Household as a Living Network

Each domain of family life—meals, chores, learning, finances, emotional wellbeing, garden, digital devices—can be represented as its own semi-autonomous node with a clear purpose.\
This transforms the household from a web of assumptions into a transparent, co-created coordination system.

***

### 💛 2. Making Contributions Visible

Daily tasks often go unnoticed: cooking, cleaning, logistics, emotional labour, school support, and maintenance work.\
Tracking contributions helps the family:

* Understand who is carrying which load
* Rebalance responsibilities before tensions grow
* Appreciate work that is normally taken for granted
* Support children in taking age-appropriate ownership

This builds a culture of recognition, responsibility, and shared pride.

***

### 🔧 3. Fair Stewardship of Shared Resources

Families share many resources—rooms, cars, budgets, tools, devices, and even free time.\
A holonic approach allows:

* Transparent agreements on access
* Smooth rotation of shared items
* Budgeting flows linked to specific domains (repairs, school fund, holidays)
* Predictable planning instead of hidden expectations

Resources become cooperative, not competitive.

***

### 🔄 4. Gentle Mutual Credit for Household Contributions

Instead of chore charts or reward/punishment systems, a light mutual-credit mechanism acknowledges contributions in a non-competitive way.\
Credits can be exchanged for:

* Screen time
* Hosting a friend
* Choosing a family activity
* Special privileges
* Or simply as feedback for responsibility

This teaches children self-management, collaboration, and contribution-based fairness.

***

### 🌒 5. Aligning the Family with Cyclical Rhythms

The family can adopt monthly or seasonal planning rhythms—such as a weekly review or lunar cycle—creating calm and coherence.\
Each cycle becomes a moment to:

* Reflect on what worked
* Identify unmet needs or tensions
* Redistribute tasks
* Plan meals, budgets, and activities
* Celebrate growth

This introduces stability and shared intention into family life.

***

### 🧩 6. Conflict Resolution Through Shared Clarity

Because domains and agreements are explicit, tensions become visible early.\
The family can:

* Log unmet needs
* Propose new agreements
* Evolve responsibilities over time
* Mediate conflicts based on clarity instead of emotion

The system becomes a neutral mirror supporting healthy communication.

***

### 🌟 7. A Culture of Shared Agency

Children raised in this kind of system learn:

* Responsibility and initiative
* Stewardship of shared spaces
* How to negotiate needs
* How to honour commitments

Adults gain relief, structure, and transparency.\
The household becomes a regenerative commons where every member participates in shaping daily life.


# Hubs Network

A  network of hubs becomes powerful when autonomous places can collaborate, share resources, and coordinate actions without relying on centralized control.\
Holons enable this by providing the **shared coordination logic** that allows hubs to interoperate while remaining sovereign.

This page outlines how a network of hubs can use Holons to grow, self-organize, and sustain itself.

***

### **1. Network-Level Funding and Resource Flows**

Holons make it possible for multiple hubs to receive, split, and redistribute resources according to transparent agreements.\
Hubs can join funding circles or create them, enabling:

* multi-hub grants
* pooled bioregional funds
* cross-hub sponsorships
* regenerative allocation rules
* automatic distribution based on thresholds, weights, or contributions

This creates **collective financing** while avoiding centralization.

***

### **2. Shared Agreements Across Autonomous Hubs**

Hubs can adopt shared patterns for:

* roles
* responsibilities
* contributions
* budgets
* governance rhythms

Holons allow hubs to **instantiate** these agreements locally while still being part of a larger federation.

This produces unity without uniformity.

***

### **3. Portability of Roles, Projects, and Contributors**

Roles and projects exist as portable Holons.\
This allows:

* contributors to move between hubs and keep their value history
* roles to be recognized across places
* projects to continue in different hubs without renegotiation
* cross-hub teams to form organically

The network gains **mobility, flexibility, and continuity**.

***

### **4. Mutual Visibility and Collective Intelligence**

Holons generate real-time visibility into:

* what hubs are working on
* which roles are active
* what tasks or projects need support
* where resources are flowing
* which areas require attention

This visibility supports decentralized decision-making and **collective sensemaking** across the network.

***

### **5. Inter-Hub Collaboration at Multiple Scales**

Because Holons operate fractally, hubs can collaborate at different levels:

* two hubs sharing a single project
* a cluster of hubs co-managing a funding pool
* an entire bioregion coordinating programs or education
* global federations of hubs contributing to shared missions

Holons make multi-scale coordination **natural and dynamic**.

***

### **6. A Common Language for Contributions**

Hubs contribute in diverse ways: land, skills, hosting, care, knowledge, tech, governance, or funding.\
Holons allow these contributions to be recognized and combined across the network.

This enables:

* fair reciprocity
* transparent contribution histories
* shared value flows
* smoother partnerships
* healthier long-term relationships

A hub’s contributions become **visible and meaningful** to the whole ecosystem.

***

### **7. A Living, Adaptive, Community-Governed Ecosystem**

When hubs use Holons, the network evolves into a **self-organizing, regenerative system**:

* hubs are sovereign
* agreements are clear
* funding flows intelligently
* collaboration is fluid
* accountability is built in
* collective capacity grows

Holons provide the coordination substrate that allows a distributed constellation of hubs to behave like a **living ecosystem** — dynamic, cooperative, and capable of scaling without losing integrity.


# Features

A scannable catalog of everything the Holons ecosystem can currently do

This page is the catalog of what's working today — grouped by what you can *do*, not by which package implements it. Each capability links to the page with the deep-dive.

The implementation lives in the [Harvest](/software/harvest-dashboard) monorepo: one shared [`@holons/core`](/software/core), five interfaces (web, Telegram, CLI, AI agent, MCP server), and the [HoloSphere](/software/holosphere) substrate beneath all of them.

***

## Coordination

How groups organize work, time, and attention.

* **Unified Quest model** — tasks, proposals, events, offers, and requests are one shape with one lifecycle, so everything composes cleanly. [→ Tasks](/software/tasks)
* **Quest creation** — from a plain title, from a design-stream step, from a recursive QuestTree, or from a ritual session.
* **Participants** — join, leave, toggle membership on any quest (pure, instant in every UI).
* **Quest completion with plan/execute split** — preview what completion will do (who scores, which dependents unblock, which REA events fire) before committing.
* **QuestTree (recursive backcasting)** — generate nested goal trees from a vision statement, with holonic metadata per node (skills required, impact category, success metrics).
* **Ritual sessions → design streams** — turn a wish-statement and an advisor panel into a set of quests, preserving the ritual provenance.
* **Calendar** — events, recurring events, scheduling.
* **Checklists** — recurring and role-based task lists.

## Recognition & contribution tracking

Where what gets done gets seen.

* **Appreciations** — `/appreciate @user [reason]` style peer recognition, public and attributable. [→ Appreciative Holon](/software/holons-types-flavor/appreciative-holon)
* **Value equation** — each holon defines weights for hours, appreciations, completed quests, currencies, and more. [→ Scoring](/software/scoring)
* **Per-user scoring** — total score, breakdown by field, percentage share of the holon.
* **Per-action scoring** — answer "what would I get for this?" before doing it.
* **All-user scoring** — full leaderboard / equity view in one call.
* **Live subscriptions** — score and equation changes propagate to every UI in real time.
* **Time-decay weights and currency contributions** — built in to the equation model.
* **REA event ledger** — every recognized action emits a typed event into an append-only stream that feeds scoring, federation, and audit. [→ REA Accounting](/software/rea-accounting)

## Governance

How holons decide.

* **Council proposals** — full lifecycle: create, save, vote, tally, derive status. [→ Council](/software/council)
* **Consent-based voting** — `agree`, `block`, `abstain`. A single block by a member with standing keeps a proposal from passing.
* **Quorum thresholds** — per-proposal, with a sensible default.
* **Pure tally helpers** — every UI renders the same live tally without round-tripping to storage.
* **DNA changes via Council** — adding chromosomes or evolving the DNA sequence happens through proposals, binding identity drift to consent.
* **Role management** — `/setroles`, `/assignroles`, role-based checklists.

## Resources

What flows through the holon.

* **Shared expenses with multi-currency** — log a cost, split it, see the credit matrix and per-user net balances. [→ Expenses](/software/expenses)
* **Currency normalization** — "EUR", "euros", "Euro" all become `eur`; multi-currency totals are additive.
* **Receipt attachments** — pictures (Telegram file IDs) per expense.
* **Community library** — tools, books, equipment, lent and borrowed with state tracking. [→ Library](/software/library)
* **Deposit accounting** — items with a `value` produce REA deposit events on borrow and release events on return.
* **Ratings and issues** — per-item ratings, reviews, and issue reports with resolution status.
* **Shopping lists** — shared lists of items the holon needs, addable via `/buy`.
* **Wants and offers** — `/request` what you need, `/offer` what you can give. `/board` to see everyone's.

## Identity & culture

What the holon stands for.

* **DNA chromosomes** — three types: `value`, `tool`, `practice`. Each has a name, description, and optional icon/color. [→ DNA](/software/dna)
* **DNA sequence** — an ordered, unique, length-bounded (≤20) selection from the chromosome library that defines the holon.
* **Seed defaults** — new holons start with a curated set of default values, tools, and practices.
* **Live DNA validation** — duplicates, length overruns, invalid references, missing-required all surface as typed errors.
* **Versioned sequences** — DNA has a version counter for optimistic concurrency.
* **Membership zones** — Core Stewards / Active Contributors / Ambassadors / Supporters, with movement based on involvement. [→ Zoned Holon](/software/holons-types-flavor/zoned-holon)
* **Personal values and needs** — `/ivalue`, `/values`, `/ineed`, `/needs` capture per-user signals visible across the holon.

## Federation

How holons connect to each other.

* **Three publish targets** — broadcast to all federated partners, send to one specific partner, drop into an H3 cell. [→ Federation](/software/federation)
* **Hologram envelope** — published items get provenance metadata (origin holon, lens, timestamp, source identity).
* **Settings hex** — a geographic discovery cell: anyone subscribed to the cell sees every published item from every member holon in the region.
* **Federation snapshots** — read-only view of partners and partner names.
* **Nostr-keyed source identity** — `federationSourceId` can be a Nostr pubkey, separating identity from holon ID.
* **Best-effort propagation** — one bad destination doesn't block the rest; denials surface via callback and `PublishOutcome.errors`.
* **`/federate` and `/fork`** — bot commands to bind and unbind federations from chat.

## Interfaces

Five ways to interact with the same data.

* [**Web dashboard**](/software/harvest-dashboard) **(`apps/web`)** — SvelteKit app with Mapbox + H3 geospatial views, schema-driven forms, federation UI, interactive holon network graph.
* [**Telegram bot**](/software/holonsbot) **(`@holons/telegram-ui`)** — Telegraf with scenes, inline keyboards, Puppeteer screenshots. The everyday surface for most communities. Full [commands reference](/software/holonsbot/holonsbot-commands).
* [**Command-line interface**](/software/text-ui) **(`@holons/text-ui`)** — `holons` binary with REPL and one-shot modes; argument grammar; auto-generated help.
* [**AI agent loop**](/software/ai-ui) **(`@holons/ai-ui`)** — `holons-ai` CLI that runs an in-process Claude tool-use loop against the shared command registry. Embeddable as a library via `runAgent()`.
* [**MCP Server**](/software/mcp-server) **(`@holons/mcp-ui`)** — \~100 tools across 14 domains, stdio or SSE-over-HTTP. Any MCP client (Claude Desktop, IDE plugins, custom agents) can drive a holon end-to-end.

All five share the same `@holons/core` functions, so an action initiated in any of them produces identical effects in every other.

## AI integration

What makes a Claude agent a first-class member.

* **MCP tool surface** — \~100 tools spanning tasks, council, scoring, DNA, library, expenses, calendar, users, federation, holosphere, checklists, shopping, settings, and commands. [→ MCP Server](/software/mcp-server)
* **Two transports** — stdio (Claude Desktop / IDE integration) or SSE on HTTP (network-reachable agents).
* **Identity resolution** — `HOLONS_ACTOR_*` env vars (or per-call overrides) attribute every write to a specific user.
* **HoloSphere connection per call** — actor + substrate are resolved fresh, so the server is stateless and safely concurrent.
* **In-process agent loop** — `@holons/ai-ui` embeds Claude inside the holon's own runtime; useful for cron jobs, webhook handlers, embedded intelligence.
* **Prompt caching** — system prompt + tool definitions cached with one ephemeral breakpoint so multi-turn sessions are cheap.
* **Auto-tool generation** — every `CoreCommand` becomes an Anthropic tool with a JSON Schema generated from its params; one file, four interfaces.

## Spatial substrate

The data layer beneath everything.

* **H3 geospatial holons** — every holon can be a hierarchical hex cell; parent/child/neighbor lookups are constant-time. [→ HoloSphere](/software/holosphere)
* **Multi-resolution holons** — neighborhood → city → region → continent, with natural aggregation via cell-to-children traversal.
* **GunDB distributed storage** — peer-to-peer, real-time, offline-tolerant, no central server required.
* **Lenses** — named categories of data per holon (`tasks`, `expenses`, `rea_events`, `dna_sequence`, …) that evolve independently.
* **JSON Schema validation per lens** — strict mode rejects malformed writes at the substrate level.
* **Real-time subscriptions** — `subscribe(holon, lens, callback)` for live change feeds.
* **Soul references** — federated data uses lightweight pointers; the original lives in one space, copies resolve to it on read (single source of truth, no storage duplication).
* **Auto-propagation** — opt-in flag on writes to propagate to every federated space automatically.
* **AI summarization** — optional OpenAI integration to compute lens summaries across scales.
* **Identity-aware writes** — `writeWithIdentity` attaches the actor; `canWriteToHolon` checks standing.
* **Message federation** — track and update messages across federated chats.

## Agreements

How commitments become legible.

* **Memorandum of Understanding template** — written agreement covering vision, contributions, allocation, governance, conflict resolution, appreciation, review. [→ MoU](/agreements/memorandum-of-understanding)
* **Commitment Registry** — published commitments, validation workflows, reputation updates on completion. [→ Funding Flow](/getting-started/funding-flow)
* **Two-layer agreements** — human-readable text + programmable contract configuration that operationalises it. [→ Agreements](/agreements/agreements)

## Holon flavors (composable patterns)

Not exclusive types — most holons are several at once. [→ Holon types (flavor)](/software/holons-types-flavor)

* **Splitter Holon** — routes incoming resources via configurable splits; the canonical dial controls internal vs external flow.
* **Managed Holon** — coordinated day-to-day through HolonsBot (or equivalent); the common starting point.
* **Zoned Holon** — concentric membership zones for differentiated participation depth.
* **Appreciative Holon** — value system anchored in peer recognition.

## Implementation status

Mostly stable; a few packages are early.

| Component                  | Version      | Notes                                                                                       |
| -------------------------- | ------------ | ------------------------------------------------------------------------------------------- |
| `@holons/core`             | 0.1.x        | Active; shape stable, domains evolving                                                      |
| `apps/web` (`harvest-web`) | 2.0          | Production-grade dashboard                                                                  |
| `@holons/telegram-ui`      | active       | Mixed TS+JS; the most-tested surface                                                        |
| `@holons/text-ui`          | 0.1.0        | CLI/REPL — works, small surface                                                             |
| `@holons/ai-ui`            | **0.1.0**    | Early; command registry currently a fallback, will move to `@holons/core/commands` upstream |
| `@holons/mcp-ui`           | **0.1.0**    | Early; tool surface and identity model working but evolving                                 |
| HoloSphere                 | 1.3.0-alpha4 | Pre-1.0 substrate                                                                           |

## See also

* [Run Your First Holon](/getting-started/run-your-first-holon) — practical walkthrough that exercises most of these features end-to-end
* [The Shared Core](/software/core) — the architecture that makes all of this composable
* [MCP Server](/software/mcp-server) — the canonical surface for external (especially AI) integrations
* [FAQ](/reference/faq) — common questions
* [Migration Notes](/reference/migration-notes) — where things moved from


# Migration Notes

What moved, what was renamed, where things live now

The Holons codebase has consolidated significantly. If you've been away for a while—or you've followed older docs—this page is the map from "where things used to be" to "where they are now."

## The big change: one monorepo, one core

Previously, the ecosystem was a set of independent repos with overlapping logic. Now everything lives in one monorepo with a single shared core:

```
Before                              After
────────────────────────────────    ─────────────────────────────────
liminalvillage/harvest         ──►  harvest/apps/web
                                    (SvelteKit dashboard, was the
                                     standalone Harvest repo)

liminalvillage/holonsbot       ──►  harvest/packages/telegram-ui
                                    (Telegraf bot, business logic
                                     extracted to @holons/core)

(scattered across both repos)  ──►  harvest/packages/core
                                    (@holons/core — shared domain
                                     logic, called by every UI)

(new)                          ──►  harvest/packages/text-ui
                                    (@holons/text-ui — CLI/REPL)

(new)                          ──►  harvest/packages/ai-ui
                                    (@holons/ai-ui — in-process
                                     Claude tool-use loop)

(new)                          ──►  harvest/packages/mcp-ui
                                    (@holons/mcp-ui — MCP server,
                                     replaces legacy HTTP API)
```

If you previously cloned `liminalvillage/harvest` for the dashboard or `liminalvillage/holonsbot` for the bot, the modern equivalent is one clone of the harvest monorepo with pnpm workspaces.

The legacy `holonsbot` repo still exists and still runs in production at some installations, but new development happens in the monorepo.

## What was renamed

| Old name                             | New name                       | Notes                                                    |
| ------------------------------------ | ------------------------------ | -------------------------------------------------------- |
| Harvest (the dashboard)              | `harvest-web` / `apps/web`     | The dashboard is now one app inside the Harvest monorepo |
| Harvest (the project)                | `harvest` (the monorepo)       | The name now refers to the whole codebase                |
| HolonsBot (the codebase)             | `@holons/telegram-ui`          | The Telegram surface is preserved; logic moved to core   |
| HolonsBot HTTP API (port 3101)       | `@holons/mcp-ui`               | The HTTP API is replaced by an MCP server                |
| `holonsbot/mcp/holons-mcp.js`        | `@holons/mcp-ui`               | The bot-side MCP wrapper is being deprecated             |
| `packages/telegram-ui/mcp/server.js` | *redirect to `@holons/mcp-ui`* | Kept as a backwards-compat shim                          |

## The MCP layer

If you've been pointing Claude Desktop at the older `holons-mcp` server, the modern equivalent is `@holons/mcp-ui`:

| Concern    | Old (`holons-mcp`)                 | New (`@holons/mcp-ui`)                          |
| ---------- | ---------------------------------- | ----------------------------------------------- |
| Path       | `holonsbot/mcp/holons-mcp.js`      | `harvest/packages/mcp-ui/dist/index.js`         |
| Style      | HTTP wrapper around the bot daemon | Direct exposure of `@holons/core` functions     |
| Tool count | \~20 higher-level operations       | \~100 fine-grained tools across 14 domains      |
| Transport  | stdio + SSE on port 3100           | stdio + SSE on configurable port (default 3200) |
| Identity   | Bot-attributed                     | Explicit actor via `HOLONS_ACTOR_*` env vars    |

Both run side-by-side today. The recommended path forward is the new server—see [MCP Server](/software/mcp-server) for the full reference.

## The value equation

The scoring equation used to have a top-level `hours` weight:

```ts
// old shape
{ initiated, completed, sent, received, hours, collaboration, wants, offers }
```

New code reads hours through `currencies.hour`:

```ts
// new shape
{ initiated, completed, sent, received, hours,
  collaboration, wants, offers, currencies: { hour: 1, … } }
```

`migrateEquation()` folds the legacy form into the new one on load—idempotent and safe to call repeatedly. The deprecated top-level `hours` field is preserved (set equal to `currencies.hour`) so unmigrated consumers keep computing the same score.

If you wrote a custom UI against the old shape, it still works. See [Scoring](/software/scoring#migration-legacy-hours--currencieshour) for the full migration rules.

## The Quest model

Five separate types collapsed into one. Where the code used to distinguish:

* tasks
* proposals
* events
* offers
* requests

…there is now one `Quest` interface with a `type` discriminator. The shape is open, so any extra fields the old types carried (`message_thread_id`, `stoppers`, schedule fields, `frequency`, `timeTracking`, etc.) are preserved on writes.

Concretely:

* Telegram-bot quest records continue to round-trip with all their original fields.
* Web-app quest records keep their richer schedule data.
* New code works against the unified shape; old code reading the legacy fields keeps working.

See [Tasks](/software/tasks) for the full Quest model.

## Federation source identity

Older code used `holonId` as the federation source. Newer code accepts an explicit `federationSourceId`—typically a Nostr public key—falling back to `holonId` when not provided.

If you've been calling `publishToFederation` directly, no change is required: omitting `federationSourceId` produces the old behavior. To take advantage of Nostr-keyed federation, pass the public key.

## Run commands

If your scripts hard-coded the old install/run patterns:

| Action             | Old (standalone harvest)                   | New (monorepo)                               |
| ------------------ | ------------------------------------------ | -------------------------------------------- |
| Install            | `yarn`                                     | `pnpm install`                               |
| Run the web app    | `yarn dev`                                 | `pnpm dev`                                   |
| Run the bot        | *separate repo, separate install*          | `pnpm dev:bot`                               |
| Run the CLI        | *did not exist*                            | `pnpm -F @holons/text-ui exec holons --help` |
| Run the AI loop    | *did not exist*                            | `pnpm -F @holons/ai-ui exec holons-ai "…"`   |
| Run the MCP server | *separate, via holonsbot*                  | `node packages/mcp-ui/dist/index.js`         |
| Memory tuning      | `NODE_OPTIONS="--max-old-space-size=4096"` | *same*                                       |

## See also

* [Harvest](/software/harvest-dashboard) — the monorepo overview
* [MCP Server](/software/mcp-server) — the canonical MCP entry point
* [The Shared Core](/software/core) — how `@holons/core` is organized


# FAQ

Common questions about Holons, answered in one place

Quick answers to questions that come up often. Each one links to the deeper page where appropriate.

## Concepts

### What is a holon?

A holon is something that is **both a whole and a part**. In the Holons protocol it is a self-governing unit (a family, team, co-op, neighborhood, region) that can also participate in larger structures. See [What is a Holon?](/getting-started/what-is-a-holon).

### What's the difference between Holons, THEOS, and Holonic Funding?

* **THEOS (The Holonic Earth Operating System)** — the broader open-source proposal at [theos.io](https://theos.io). Describes a holonic, peer-to-peer social coordination protocol aligned with planetary boundaries.
* **Holons** — colloquial shorthand for the protocol THEOS describes, and for working implementations of it (such as the Liminal Village software ecosystem documented in these docs).
* **Holonic Funding** — the economic/financial layer of the implementation (splitters, threshold buckets, value equations, federation).

See the [glossary's naming section](/getting-started/glossary#names-of-the-things-clarified) and [THEOS](/software/the-holonic-earth-operating-system).

### What's the difference between HoloSphere and HolonsBot?

* [HoloSphere](/software/holosphere) is the **substrate** — a JavaScript library for distributed, H3-indexed data.
* [HolonsBot](/software/holonsbot) is one of several **interfaces** people use to operate holons (Telegram). It writes to HoloSphere through `@holons/core`.

Other interfaces include the [web dashboard](/software/harvest-dashboard), the [CLI](/software/text-ui), the [AI agent](/software/ai-ui), and the [MCP server](/software/mcp-server).

### Does a holon have to be geographic?

No. H3 indexing is the **default** addressing scheme because most early use cases were place-based (gardens, hubs, bioregions), but a holon can be any string ID. A holon for a virtual community, a distributed project, or a dataset is just as valid.

### What's a "value equation"?

A formula chosen by each holon that turns contributions (hours, appreciations, completed quests, currency balances) into scores. Different weights produce different cultures—what a holon weights is what its members get recognized for. See [Scoring](/software/scoring).

## Setup

### Where do I start?

If you want the philosophy first: [Introduction](/) → [What is a Holon?](/getting-started/what-is-a-holon).

If you want to get running: [Run Your First Holon](/getting-started/run-your-first-holon).

If you're a developer: [The Shared Core](/software/core).

### What do I need to run a holon?

For a basic Managed Holon on Telegram: a Telegram group, [HolonsBot](/software/holonsbot), and 10 minutes. See [Setting up your holonic organization](/daos/setting-up-your-holonic-organization).

For a federated holon with the web dashboard, AI agent, and MCP server: the [Harvest monorepo](/software/harvest-dashboard), Node ≥20, pnpm ≥10, and a Gun relay (the default `https://gun.holons.io/gun` works out of the box).

### Do I need to host my own Gun peer?

No. The default `https://gun.holons.io/gun` works. Hosting your own peer makes sense once you have data sovereignty or latency requirements that the default doesn't meet.

### What's the difference between `@holons/ai-ui` and `@holons/mcp-ui`?

Both expose `@holons/core` to AI agents, but at different layers:

* **`@holons/ai-ui`** runs an **in-process** Claude tool-use loop. Best when the holon itself wants to interpret natural-language input.
* **`@holons/mcp-ui`** is an **out-of-process** MCP server. Best when external clients (Claude Desktop, IDE plugins, third-party agents) should drive the holon.

A holon can run both. See [AI UI](/software/ai-ui) and [MCP Server](/software/mcp-server).

## Architecture

### Why is there one core and many UIs?

So that "compute user score," "create a task," or "publish to federation" means the **exact same thing** regardless of how a user reached the system. Without a shared core, every UI re-implements the logic, the implementations drift, and the same user sees different results in different surfaces.

See [The Shared Core](/software/core).

### How do new domains get added?

Create `packages/core/src/<domain>/index.ts`, export the public surface, write a vitest spec. The subpath wildcard in `package.json` makes `@holons/core/<domain>` importable instantly. Then optionally add `packages/mcp-ui/src/tools/<domain>.ts` to expose it as MCP tools.

See [The Shared Core](/software/core#how-a-new-domain-lands).

### Why H3 indexing?

Hierarchical hexagons give the system constant-time parent/child/neighbor lookups, stable IDs across clients computing the same coordinate, and natural aggregation patterns. Aggregating "all readings for this region" is a child-cell traversal rather than a custom regional schema.

See [HoloSphere](/software/holosphere#why-h3).

### Why GunDB?

Decentralized, real-time, peer-to-peer, offline-tolerant. Trades transactional consistency for autonomy and resilience. The Holons domains are designed to work with eventual consistency rather than against it.

See [HoloSphere](/software/holosphere#why-gundb).

## Operations

### What does "federation" actually mean in practice?

Two holons declare a trust relationship. Once federated, items one holon publishes (quests, offers, appreciations, expenses) become visible to the other under the rules each holon set for itself. Neither side gives up its autonomy—each keeps its own DNA, value equation, and storage namespace.

See [Federation](/software/federation) for the implementation and the [glossary](/getting-started/glossary#federation) for the concept.

### Can a holon belong to many federations?

Yes. The federation graph is a normal graph, not a tree—every holon can declare as many trust relationships as it wants. Items get published to specific targets (`all`, `partner`, `hex`) so a holon can choose where each publish lands.

### How does a holon recognize contributions from a federated partner?

Through appreciation data flowing across the federation, weighted into the local value equation. The [Appreciative Holon](/software/holons-types-flavor/appreciative-holon) pattern is the canonical answer; the [Scoring](/software/scoring) domain handles the math.

### Can I run a holon without HolonsBot?

Yes. HolonsBot is one interface; the [web dashboard](/software/harvest-dashboard), [CLI](/software/text-ui), [AI UI](/software/ai-ui), and [MCP server](/software/mcp-server) all do the same things. A holon could run with only the MCP server and a Claude agent, with no chat surface at all.

## AI integration

### Can a Claude agent be a member of a holon?

Yes—via either `@holons/ai-ui` (in-process) or `@holons/mcp-ui` (out-of-process). The agent resolves to an actor identity (`HOLONS_ACTOR_*`), and every action it takes is attributed to that identity in HoloSphere. Scoring, federation, and audit all treat it like any other member.

### What tools can the MCP server call?

Roughly 100 tools across 14 domains: tasks, council, scoring, REA-via-HoloSphere reads, DNA, library, expenses, calendar, users, federation, holosphere, checklists, shopping, settings, and commands. See [MCP Server](/software/mcp-server#tool-domains).

### How do I keep an AI agent from acting on behalf of someone it shouldn't?

Identity-aware writes (`canWriteToHolon` in `@holons/core/holosphere`) check permissions at the substrate level. The MCP server's `resolveActor` picks up the identity from env vars; if those map to a member with restricted standing, the agent inherits those restrictions automatically.

## Troubleshooting

### "Write access denied" when publishing

The destination holon's ACL refused the write. The publish doesn't abort—it records the denial in the `PublishOutcome.errors` and continues with other destinations. To fix the denial itself, check the destination's federation settings.

See [Federation: how permission denials surface](/software/federation#how-permission-denials-surface).

### "JavaScript heap out of memory" in the web dashboard

Large federated networks can exhaust the default Node.js memory limit. Bump it:

```bash
export NODE_OPTIONS="--max-old-space-size=4096"
pnpm dev
```

See [Harvest: memory management](/software/harvest-dashboard#memory-management-web-dashboard).

### The MCP server starts but Claude can't see any tools

Check that `registerAllTools` succeeded—each tool module is imported lazily, and a missing module is skipped silently. Look in stderr for "holons-mcp-ui running on stdio" (or "listening on port N (SSE)") to confirm the server is up; if it is but tools are empty, the build likely didn't include `packages/mcp-ui/dist/tools/*.js`. Re-run `pnpm -F @holons/mcp-ui build`.

### Score changes aren't reflecting in the UI

The value equation is cached synchronously for instant access. If a weight changed but the UI is still showing the old score, the cache hasn't been refreshed—call `preloadEquation(holonId)` or subscribe via `subscribeToEquationChanges()`.

See [Scoring: subscriptions and caching](/software/scoring#subscriptions-and-caching).

## I have another question

Open an issue in the relevant repo, or ask in the channel where your holon coordinates. If you find a recurring question worth adding here, edit this page and add it.