> 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/migration-notes.md).

# Migration Notes

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.md) 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.md#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.md) 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.md) — the monorepo overview
* [MCP Server](/software/mcp-server.md) — the canonical MCP entry point
* [The Shared Core](/software/core.md) — how `@holons/core` is organized


---

# 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/migration-notes.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.