> For the complete documentation index, see [llms.txt](https://docs.holons.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.holons.io/reference/faq.md). # FAQ 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.md). ### 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.md#names-of-the-things-clarified) and [THEOS](/software/the-holonic-earth-operating-system.md). ### What's the difference between HoloSphere and HolonsBot? * [HoloSphere](/software/holosphere.md) is the **substrate** — a JavaScript library for distributed, H3-indexed data. * [HolonsBot](/software/holonsbot.md) 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.md), the [CLI](/software/text-ui.md), the [AI agent](/software/ai-ui.md), and the [MCP server](/software/mcp-server.md). ### 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.md). ## Setup ### Where do I start? If you want the philosophy first: [Introduction](/getting-started/readme.md) → [What is a Holon?](/getting-started/what-is-a-holon.md). If you want to get running: [Run Your First Holon](/getting-started/run-your-first-holon.md). If you're a developer: [The Shared Core](/software/core.md). ### What do I need to run a holon? For a basic Managed Holon on Telegram: a Telegram group, [HolonsBot](/software/holonsbot.md), and 10 minutes. See [Setting up your holonic organization](/daos/setting-up-your-holonic-organization.md). For a federated holon with the web dashboard, AI agent, and MCP server: the [Harvest monorepo](/software/harvest-dashboard.md), 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.md) and [MCP Server](/software/mcp-server.md). ## 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.md). ### How do new domains get added? Create `packages/core/src//index.ts`, export the public surface, write a vitest spec. The subpath wildcard in `package.json` makes `@holons/core/` importable instantly. Then optionally add `packages/mcp-ui/src/tools/.ts` to expose it as MCP tools. See [The Shared Core](/software/core.md#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.md#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.md#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.md) for the implementation and the [glossary](/getting-started/glossary.md#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.md) pattern is the canonical answer; the [Scoring](/software/scoring.md) domain handles the math. ### Can I run a holon without HolonsBot? Yes. HolonsBot is one interface; the [web dashboard](/software/harvest-dashboard.md), [CLI](/software/text-ui.md), [AI UI](/software/ai-ui.md), and [MCP server](/software/mcp-server.md) 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.md#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.md#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.md#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.md#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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.holons.io/reference/faq.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.