pi-rngit-work-document-skill

A Pi skill (also usable as a plain Node library) for creating and updating rngit work documents over the Reticulum mesh — without the interactive editor that the rngit work CLI requires.

It speaks the exact same /mgmt/work request/response protocol as the Python rngit work tooling (see RNS/Utilities/rngit/server.py). Built on reticulum-js.

What it does

Operation	Permission needed	Notes
list	read	active (default) / completed / proposed / all
view	read	document body + update history
create	write + interact	lands in active, signed by your identity
propose	propose	lands in proposed
edit	write + interact	only the original author
update	interact	adds a signed update (comment)
complete	write + interact	moves a doc to completed
activate	write + interact	reactivates a doc into active

Install as a Pi skill

pi install npm:pi-rngit-work-document-skill
# or from a local checkout:
pi install ./packages/pi-rngit-work-document-skill

Configuration

The client connects to a local rnsd by default and needs to know which rngit node/repository to talk to.

Target discovery

The target rns://<hash>/<group>/<repo> is resolved automatically, in order:

1. Auto-discovery from project files in the current directory:
   • a rns:// git remote in .git/config (set by git clone rns://...), then
   • a package.json field (rngit, rngit.url, reticulum.rngit, or an rns:// repository/repository.url), then
   • the first rns:// URL in AGENTS.md, README.md, or CONTRIBUTING.md.
2. The RNGIT_URL / RNGIT_TARGET env var, which overrides discovery.

Environment variables

Variable	Meaning	Default
RNGIT_TARGET_HASH + RNGIT_GROUP + RNGIT_REPO	alternative to RNGIT_URL	—
RNS_HOST / RNS_PORT	local rnsd TCP interface	127.0.0.1:42424
RNGIT_IDENTITY	path to the client identity key	~/.pi-rngit-work/identity.key
RNGIT_PATH_TIMEOUT_MS	time to learn the remote identity	30000
RNGIT_REQUEST_TIMEOUT_MS	per-request response timeout	300000

Bootstrapping permissions

Pi keeps its own identity (separate from the human's rngit client identity), so the node admin can grant different permissions to humans and machines. The identity key is generated on first use; print its hash (no network) and hand it to the admin:

node skills/rngit-work/scripts/work.js identity

The admin then grants that hash permissions on the rngit server, e.g. in ~/.rngit/config:

[access]
public = r:all, w:<pi-hash>, i:<pi-hash>

…or per repository in a <repo>.allowed file. Flags: r=read, w=write, i=interact, p=propose, adm=admin. create/edit/update need w+i; propose needs p; list/view need r.

CLI usage

work.js list [--scope active|completed|proposed|all]
work.js view <id> [--scope ...]
work.js create <title...> --file <path|-> [--propose]
work.js edit <id> --file <path|-> [--title <t>] [--scope ...]
work.js update <id> --file <path|-> [--scope ...]
work.js complete <id>
work.js activate <id>
work.js identity                        # print pi's identity hash (no network)

Content is read with --file <path>, or from stdin via --file -. Add --json for structured output. Flags --url, --host, --port, --identity override the environment for a single run.

echo "# Heading\nBody text" | node scripts/work.js create "My first doc" --file -
node scripts/work.js list --scope all

As a library

import { WorkClient, loadConfig } from "pi-rngit-work-document-skill";

const client = new WorkClient(loadConfig());
await client.connect();

const created = await client.create("Plan something", "# Plan\nLet's …");
console.log(`Created #${created.id}`);

await client.update(created.id, "Update: started on this.");
console.log(await client.view(created.id));

await client.close();

Protocol notes

• Destination aspect: git.repositories; request path: /mgmt/work.
• Requests are msgpack maps keyed by the integer 0 (IDX_REPOSITORY) plus string fields. A plain JS object would coerce key 0 to "0" and be rejected, so the client builds payloads as a Map.
• Responses are a status byte (0 = OK) followed by a msgpack payload.
• create/propose/edit include a 64-byte Ed25519 signature over the content.

License

EUPL-1.2