Ark

An archive for a community's written record.

Minutes, decisions and reports accumulate for decades, and they usually end up in something one person administers: a Drupal site, a shared drive, a wiki with a password nobody can find. Ark keeps that record on Holochain instead, so it lives in the group rather than on a server, and every member holds it.

Documents are immutable, as they are everywhere in Holochain, but they are not frozen: amending one publishes a new version and keeps the old, so the record shows what it says now and what it used to say. The folder tree is separate from the documents, held as links, which means reorganising the archive never touches a document. Anyone in the group can file, amend, and reorganise.

Search runs entirely in the browser over the whole corpus — ranked results with snippets, quoted phrases, prefix terms, exclusions, and the text of attachments alongside the documents themselves.

Ark is a Moss tool.

Which line is this?

This is the main branch: Holochain 0.7 (hdi 0.8, hdk 0.7, holonix main-0.7) and Moss 0.16 (@theweave/cli 0.16.x, @theweave/api 0.7.x). The main-0.6 branch is the parallel Holochain 0.6 / Moss 0.15 line. The two are kept in step; pick the branch that matches the conductor and Moss you are running.

Development model

main is the development line. Work lands here first and is back-ported to main-0.6 by cherry-pick — not the other way round. A change that applies only to the 0.6 line (the HDK pin matching the conductor Moss 0.15 bundles) is authored there and stays there.

Environment Setup

PREREQUISITE: set up the holochain development environment.

Enter the nix shell in the root folder of the repository:

nix develop
npm install

Run the rest of these commands from inside that nix shell, or they won't work.

Running it in Moss

Two agents, each in their own Moss window, sharing a group:

npm run start:moss

One agent, for when a second one is just in the way:

npm run start:moss-1

Three, for watching structure changes propagate:

npm run start:moss-3

Running it without Moss

npm start

This brings up a network of two conductors and their UIs.

Tests

The DNA tests run against a real conductor and take a few minutes:

npm test

The UI's own tests are much faster and need no conductor:

npm run verify         # unit tests and typecheck
npm run test:e2e -w ui # end-to-end, headless, no display required

The end-to-end suite drives the real UI against an in-memory conductor stub, so it covers the parts that only break in a browser — the file picker, the search overlay, attachment previews, the pane header — without needing Holochain running.

Building

npm run package

Produces workdir/ark.webhapp.

Importing an existing archive

Ark reads a directory of markdown files with YAML front matter. title, date, folder and attachments are understood; every other key is carried through and kept, because what counts as metadata is a decision for the community holding the archive, not for this tool.

Export is the same format in reverse — a zip of markdown and attachments laid out in folders mirroring the tree. What Ark writes out, Ark reads back in.

License

Copyright (C) 2026, Lightningrod Labs

This program is free software: you can redistribute it and/or modify it under the terms of the license provided in the LICENSE file (CAL-1.0). This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.