# Harvest 🌱

**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.md) 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.md).                                                    |
| `@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.md) — 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.md) — `@holons/mcp-ui` in depth
* [HolonsBot](/software/holonsbot.md) — the Telegram interface (`@holons/telegram-ui`)
* [HoloSphere](/software/holosphere.md) — the distributed substrate every package writes to
* [Glossary](/getting-started/glossary.md) — vocabulary for the protocol concepts the code implements


---

# Agent Instructions: 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/software/harvest-dashboard.md?ask=<question>
```

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.