@abraca/mcp 1.0.2 → 1.0.10

package/dist/abracadabra-mcp.esm.js

@@ -3,8 +3,12 @@ import { ZodOptional, z } from "zod";
 import process$1 from "node:process";
 import * as Y from "yjs";
 import { AbracadabraClient, AbracadabraProvider, awarenessStatesToArray } from "@abraca/dabra";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import * as fs from "node:fs";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
 import * as path from "node:path";
+import { dirname, join } from "node:path";
 
 //#region \0rolldown/runtime.js
 var __create = Object.create;
@@ -18430,6 +18434,992 @@ function waitForSync(provider, timeoutMs = 15e3) {
 	});
 }
 
+//#endregion
+//#region node_modules/@noble/ed25519/index.js
+/*! noble-ed25519 - MIT License (c) 2019 Paul Miller (paulmillr.com) */
+/**
+* 4KB JS implementation of ed25519 EdDSA signatures.
+* Compliant with RFC8032, FIPS 186-5 & ZIP215.
+* @module
+* @example
+* ```js
+import * as ed from '@noble/ed25519';
+(async () => {
+const privKey = ed.utils.randomPrivateKey();
+const message = Uint8Array.from([0xab, 0xbc, 0xcd, 0xde]);
+const pubKey = await ed.getPublicKeyAsync(privKey); // Sync methods are also present
+const signature = await ed.signAsync(message, privKey);
+const isValid = await ed.verifyAsync(signature, message, pubKey);
+})();
+```
+*/
+/**
+* Curve params. ed25519 is twisted edwards curve. Equation is −x² + y² = -a + dx²y².
+* * P = `2n**255n - 19n` // field over which calculations are done
+* * N = `2n**252n + 27742317777372353535851937790883648493n` // group order, amount of curve points
+* * h = 8 // cofactor
+* * a = `Fp.create(BigInt(-1))` // equation param
+* * d = -121665/121666 a.k.a. `Fp.neg(121665 * Fp.inv(121666))` // equation param
+* * Gx, Gy are coordinates of Generator / base point
+*/
+const ed25519_CURVE = {
+	p: 57896044618658097711785492504343953926634992332820282019728792003956564819949n,
+	n: 7237005577332262213973186563042994240857116359379907606001950938285454250989n,
+	h: 8n,
+	a: 57896044618658097711785492504343953926634992332820282019728792003956564819948n,
+	d: 37095705934669439343138083508754565189542113879843219016388785533085940283555n,
+	Gx: 15112221349535400772501151409588531511454012693041857206046113283949847762202n,
+	Gy: 46316835694926478169428394003475163141307993866256225615783033603165251855960n
+};
+const { p: P, n: N, Gx, Gy, a: _a, d: _d } = ed25519_CURVE;
+const h = 8n;
+const L = 32;
+const L2 = 64;
+const err = (m = "") => {
+	throw new Error(m);
+};
+const isBig = (n) => typeof n === "bigint";
+const isStr = (s) => typeof s === "string";
+const isBytes$1 = (a) => a instanceof Uint8Array || ArrayBuffer.isView(a) && a.constructor.name === "Uint8Array";
+/** assert is Uint8Array (of specific length) */
+const abytes$1 = (a, l) => !isBytes$1(a) || typeof l === "number" && l > 0 && a.length !== l ? err("Uint8Array expected") : a;
+/** create Uint8Array */
+const u8n = (len) => new Uint8Array(len);
+const u8fr = (buf) => Uint8Array.from(buf);
+const padh = (n, pad) => n.toString(16).padStart(pad, "0");
+const bytesToHex = (b) => Array.from(abytes$1(b)).map((e) => padh(e, 2)).join("");
+const C = {
+	_0: 48,
+	_9: 57,
+	A: 65,
+	F: 70,
+	a: 97,
+	f: 102
+};
+const _ch = (ch) => {
+	if (ch >= C._0 && ch <= C._9) return ch - C._0;
+	if (ch >= C.A && ch <= C.F) return ch - (C.A - 10);
+	if (ch >= C.a && ch <= C.f) return ch - (C.a - 10);
+};
+const hexToBytes = (hex) => {
+	const e = "hex invalid";
+	if (!isStr(hex)) return err(e);
+	const hl = hex.length;
+	const al = hl / 2;
+	if (hl % 2) return err(e);
+	const array = u8n(al);
+	for (let ai = 0, hi = 0; ai < al; ai++, hi += 2) {
+		const n1 = _ch(hex.charCodeAt(hi));
+		const n2 = _ch(hex.charCodeAt(hi + 1));
+		if (n1 === void 0 || n2 === void 0) return err(e);
+		array[ai] = n1 * 16 + n2;
+	}
+	return array;
+};
+/** normalize hex or ui8a to ui8a */
+const toU8 = (a, len) => abytes$1(isStr(a) ? hexToBytes(a) : u8fr(abytes$1(a)), len);
+const cr = () => globalThis?.crypto;
+const subtle = () => cr()?.subtle ?? err("crypto.subtle must be defined");
+const concatBytes = (...arrs) => {
+	const r = u8n(arrs.reduce((sum, a) => sum + abytes$1(a).length, 0));
+	let pad = 0;
+	arrs.forEach((a) => {
+		r.set(a, pad);
+		pad += a.length;
+	});
+	return r;
+};
+/** WebCrypto OS-level CSPRNG (random number generator). Will throw when not available. */
+const randomBytes = (len = L) => {
+	return cr().getRandomValues(u8n(len));
+};
+const big = BigInt;
+const arange = (n, min, max, msg = "bad number: out of range") => isBig(n) && min <= n && n < max ? n : err(msg);
+/** modular division */
+const M = (a, b = P) => {
+	const r = a % b;
+	return r >= 0n ? r : b + r;
+};
+const modN = (a) => M(a, N);
+/** Modular inversion using eucledian GCD (non-CT). No negative exponent for now. */
+const invert = (num, md) => {
+	if (num === 0n || md <= 0n) err("no inverse n=" + num + " mod=" + md);
+	let a = M(num, md), b = md, x = 0n, y = 1n, u = 1n, v = 0n;
+	while (a !== 0n) {
+		const q = b / a, r = b % a;
+		const m = x - u * q, n = y - v * q;
+		b = a, a = r, x = u, y = v, u = m, v = n;
+	}
+	return b === 1n ? M(x, md) : err("no inverse");
+};
+const callHash = (name) => {
+	const fn = etc[name];
+	if (typeof fn !== "function") err("hashes." + name + " not set");
+	return fn;
+};
+const apoint = (p) => p instanceof Point ? p : err("Point expected");
+const B256 = 2n ** 256n;
+/** Point in XYZT extended coordinates. */
+var Point = class Point {
+	static BASE;
+	static ZERO;
+	ex;
+	ey;
+	ez;
+	et;
+	constructor(ex, ey, ez, et) {
+		const max = B256;
+		this.ex = arange(ex, 0n, max);
+		this.ey = arange(ey, 0n, max);
+		this.ez = arange(ez, 1n, max);
+		this.et = arange(et, 0n, max);
+		Object.freeze(this);
+	}
+	static fromAffine(p) {
+		return new Point(p.x, p.y, 1n, M(p.x * p.y));
+	}
+	/** RFC8032 5.1.3: Uint8Array to Point. */
+	static fromBytes(hex, zip215 = false) {
+		const d = _d;
+		const normed = u8fr(abytes$1(hex, L));
+		const lastByte = hex[31];
+		normed[31] = lastByte & -129;
+		const y = bytesToNumLE(normed);
+		arange(y, 0n, zip215 ? B256 : P);
+		const y2 = M(y * y);
+		let { isValid, value: x } = uvRatio(M(y2 - 1n), M(d * y2 + 1n));
+		if (!isValid) err("bad point: y not sqrt");
+		const isXOdd = (x & 1n) === 1n;
+		const isLastByteOdd = (lastByte & 128) !== 0;
+		if (!zip215 && x === 0n && isLastByteOdd) err("bad point: x==0, isLastByteOdd");
+		if (isLastByteOdd !== isXOdd) x = M(-x);
+		return new Point(x, y, 1n, M(x * y));
+	}
+	/** Checks if the point is valid and on-curve. */
+	assertValidity() {
+		const a = _a;
+		const d = _d;
+		const p = this;
+		if (p.is0()) throw new Error("bad point: ZERO");
+		const { ex: X, ey: Y, ez: Z, et: T } = p;
+		const X2 = M(X * X);
+		const Y2 = M(Y * Y);
+		const Z2 = M(Z * Z);
+		const Z4 = M(Z2 * Z2);
+		if (M(Z2 * M(M(X2 * a) + Y2)) !== M(Z4 + M(d * M(X2 * Y2)))) throw new Error("bad point: equation left != right (1)");
+		if (M(X * Y) !== M(Z * T)) throw new Error("bad point: equation left != right (2)");
+		return this;
+	}
+	/** Equality check: compare points P&Q. */
+	equals(other) {
+		const { ex: X1, ey: Y1, ez: Z1 } = this;
+		const { ex: X2, ey: Y2, ez: Z2 } = apoint(other);
+		const X1Z2 = M(X1 * Z2);
+		const X2Z1 = M(X2 * Z1);
+		const Y1Z2 = M(Y1 * Z2);
+		const Y2Z1 = M(Y2 * Z1);
+		return X1Z2 === X2Z1 && Y1Z2 === Y2Z1;
+	}
+	is0() {
+		return this.equals(I);
+	}
+	/** Flip point over y coordinate. */
+	negate() {
+		return new Point(M(-this.ex), this.ey, this.ez, M(-this.et));
+	}
+	/** Point doubling. Complete formula. Cost: `4M + 4S + 1*a + 6add + 1*2`. */
+	double() {
+		const { ex: X1, ey: Y1, ez: Z1 } = this;
+		const a = _a;
+		const A = M(X1 * X1);
+		const B = M(Y1 * Y1);
+		const C = M(2n * M(Z1 * Z1));
+		const D = M(a * A);
+		const x1y1 = X1 + Y1;
+		const E = M(M(x1y1 * x1y1) - A - B);
+		const G = D + B;
+		const F = G - C;
+		const H = D - B;
+		const X3 = M(E * F);
+		const Y3 = M(G * H);
+		const T3 = M(E * H);
+		return new Point(X3, Y3, M(F * G), T3);
+	}
+	/** Point addition. Complete formula. Cost: `8M + 1*k + 8add + 1*2`. */
+	add(other) {
+		const { ex: X1, ey: Y1, ez: Z1, et: T1 } = this;
+		const { ex: X2, ey: Y2, ez: Z2, et: T2 } = apoint(other);
+		const a = _a;
+		const d = _d;
+		const A = M(X1 * X2);
+		const B = M(Y1 * Y2);
+		const C = M(T1 * d * T2);
+		const D = M(Z1 * Z2);
+		const E = M((X1 + Y1) * (X2 + Y2) - A - B);
+		const F = M(D - C);
+		const G = M(D + C);
+		const H = M(B - a * A);
+		const X3 = M(E * F);
+		const Y3 = M(G * H);
+		const T3 = M(E * H);
+		return new Point(X3, Y3, M(F * G), T3);
+	}
+	/**
+	* Point-by-scalar multiplication. Scalar must be in range 1 <= n < CURVE.n.
+	* Uses {@link wNAF} for base point.
+	* Uses fake point to mitigate side-channel leakage.
+	* @param n scalar by which point is multiplied
+	* @param safe safe mode guards against timing attacks; unsafe mode is faster
+	*/
+	multiply(n, safe = true) {
+		if (!safe && (n === 0n || this.is0())) return I;
+		arange(n, 1n, N);
+		if (n === 1n) return this;
+		if (this.equals(G)) return wNAF(n).p;
+		let p = I;
+		let f = G;
+		for (let d = this; n > 0n; d = d.double(), n >>= 1n) if (n & 1n) p = p.add(d);
+		else if (safe) f = f.add(d);
+		return p;
+	}
+	/** Convert point to 2d xy affine point. (X, Y, Z) ∋ (x=X/Z, y=Y/Z) */
+	toAffine() {
+		const { ex: x, ey: y, ez: z } = this;
+		if (this.equals(I)) return {
+			x: 0n,
+			y: 1n
+		};
+		const iz = invert(z, P);
+		if (M(z * iz) !== 1n) err("invalid inverse");
+		return {
+			x: M(x * iz),
+			y: M(y * iz)
+		};
+	}
+	toBytes() {
+		const { x, y } = this.assertValidity().toAffine();
+		const b = numTo32bLE(y);
+		b[31] |= x & 1n ? 128 : 0;
+		return b;
+	}
+	toHex() {
+		return bytesToHex(this.toBytes());
+	}
+	clearCofactor() {
+		return this.multiply(big(h), false);
+	}
+	isSmallOrder() {
+		return this.clearCofactor().is0();
+	}
+	isTorsionFree() {
+		let p = this.multiply(N / 2n, false).double();
+		if (N % 2n) p = p.add(this);
+		return p.is0();
+	}
+	static fromHex(hex, zip215) {
+		return Point.fromBytes(toU8(hex), zip215);
+	}
+	get x() {
+		return this.toAffine().x;
+	}
+	get y() {
+		return this.toAffine().y;
+	}
+	toRawBytes() {
+		return this.toBytes();
+	}
+};
+/** Generator / base point */
+const G = new Point(Gx, Gy, 1n, M(Gx * Gy));
+/** Identity / zero point */
+const I = new Point(0n, 1n, 1n, 0n);
+Point.BASE = G;
+Point.ZERO = I;
+const numTo32bLE = (num) => hexToBytes(padh(arange(num, 0n, B256), L2)).reverse();
+const bytesToNumLE = (b) => big("0x" + bytesToHex(u8fr(abytes$1(b)).reverse()));
+const pow2 = (x, power) => {
+	let r = x;
+	while (power-- > 0n) {
+		r *= r;
+		r %= P;
+	}
+	return r;
+};
+const pow_2_252_3 = (x) => {
+	const b2 = x * x % P * x % P;
+	const b5 = pow2(pow2(b2, 2n) * b2 % P, 1n) * x % P;
+	const b10 = pow2(b5, 5n) * b5 % P;
+	const b20 = pow2(b10, 10n) * b10 % P;
+	const b40 = pow2(b20, 20n) * b20 % P;
+	const b80 = pow2(b40, 40n) * b40 % P;
+	return {
+		pow_p_5_8: pow2(pow2(pow2(pow2(b80, 80n) * b80 % P, 80n) * b80 % P, 10n) * b10 % P, 2n) * x % P,
+		b2
+	};
+};
+const RM1 = 19681161376707505956807079304988542015446066515923890162744021073123829784752n;
+const uvRatio = (u, v) => {
+	const v3 = M(v * v * v);
+	const pow = pow_2_252_3(u * M(v3 * v3 * v)).pow_p_5_8;
+	let x = M(u * v3 * pow);
+	const vx2 = M(v * x * x);
+	const root1 = x;
+	const root2 = M(x * RM1);
+	const useRoot1 = vx2 === u;
+	const useRoot2 = vx2 === M(-u);
+	const noRoot = vx2 === M(-u * RM1);
+	if (useRoot1) x = root1;
+	if (useRoot2 || noRoot) x = root2;
+	if ((M(x) & 1n) === 1n) x = M(-x);
+	return {
+		isValid: useRoot1 || useRoot2,
+		value: x
+	};
+};
+const modL_LE = (hash) => modN(bytesToNumLE(hash));
+const sha512a = (...m) => etc.sha512Async(...m);
+const sha512s = (...m) => callHash("sha512Sync")(...m);
+const hash2extK = (hashed) => {
+	const head = hashed.slice(0, L);
+	head[0] &= 248;
+	head[31] &= 127;
+	head[31] |= 64;
+	const prefix = hashed.slice(L, L2);
+	const scalar = modL_LE(head);
+	const point = G.multiply(scalar);
+	return {
+		head,
+		prefix,
+		scalar,
+		point,
+		pointBytes: point.toBytes()
+	};
+};
+const getExtendedPublicKeyAsync = (priv) => sha512a(toU8(priv, L)).then(hash2extK);
+const getExtendedPublicKey = (priv) => hash2extK(sha512s(toU8(priv, L)));
+/** Creates 32-byte ed25519 public key from 32-byte private key. To use, set `etc.sha512Sync` first. */
+const getPublicKey = (priv) => getExtendedPublicKey(priv).pointBytes;
+const hashFinishS = (res) => res.finish(sha512s(res.hashable));
+const _sign = (e, rBytes, msg) => {
+	const { pointBytes: P, scalar: s } = e;
+	const r = modL_LE(rBytes);
+	const R = G.multiply(r).toBytes();
+	const hashable = concatBytes(R, P, msg);
+	const finish = (hashed) => {
+		return abytes$1(concatBytes(R, numTo32bLE(modN(r + modL_LE(hashed) * s))), L2);
+	};
+	return {
+		hashable,
+		finish
+	};
+};
+/**
+* Signs message (NOT message hash) using private key. To use, set `hashes.sha512` first.
+* Follows RFC8032 5.1.6.
+*/
+const sign = (msg, privKey) => {
+	const m = toU8(msg);
+	const e = getExtendedPublicKey(privKey);
+	return hashFinishS(_sign(e, sha512s(e.prefix, m), m));
+};
+/** Math, hex, byte helpers. Not in `utils` because utils share API with noble-curves. */
+const etc = {
+	sha512Async: async (...messages) => {
+		const s = subtle();
+		const m = concatBytes(...messages);
+		return u8n(await s.digest("SHA-512", m.buffer));
+	},
+	sha512Sync: void 0,
+	bytesToHex,
+	hexToBytes,
+	concatBytes,
+	mod: M,
+	invert,
+	randomBytes
+};
+/** ed25519-specific key utilities. */
+const utils = {
+	getExtendedPublicKeyAsync,
+	getExtendedPublicKey,
+	randomPrivateKey: () => randomBytes(L),
+	precompute: (w = 8, p = G) => {
+		p.multiply(3n);
+		return p;
+	}
+};
+const W = 8;
+const pwindows = Math.ceil(256 / W) + 1;
+const pwindowSize = 2 ** (W - 1);
+const precompute = () => {
+	const points = [];
+	let p = G;
+	let b = p;
+	for (let w = 0; w < pwindows; w++) {
+		b = p;
+		points.push(b);
+		for (let i = 1; i < pwindowSize; i++) {
+			b = b.add(p);
+			points.push(b);
+		}
+		p = b.double();
+	}
+	return points;
+};
+let Gpows = void 0;
+const ctneg = (cnd, p) => {
+	const n = p.negate();
+	return cnd ? n : p;
+};
+/**
+* Precomputes give 12x faster getPublicKey(), 10x sign(), 2x verify() by
+* caching multiples of G (base point). Cache is stored in 32MB of RAM.
+* Any time `G.multiply` is done, precomputes are used.
+* Not used for getSharedSecret, which instead multiplies random pubkey `P.multiply`.
+*
+* w-ary non-adjacent form (wNAF) precomputation method is 10% slower than windowed method,
+* but takes 2x less RAM. RAM reduction is possible by utilizing `.subtract`.
+*
+* !! Precomputes can be disabled by commenting-out call of the wNAF() inside Point#multiply().
+*/
+const wNAF = (n) => {
+	const comp = Gpows || (Gpows = precompute());
+	let p = I;
+	let f = G;
+	const pow_2_w = 2 ** W;
+	const maxNum = pow_2_w;
+	const mask = big(pow_2_w - 1);
+	const shiftBy = big(W);
+	for (let w = 0; w < pwindows; w++) {
+		let wbits = Number(n & mask);
+		n >>= shiftBy;
+		if (wbits > pwindowSize) {
+			wbits -= maxNum;
+			n += 1n;
+		}
+		const off = w * pwindowSize;
+		const offF = off;
+		const offP = off + Math.abs(wbits) - 1;
+		const isEven = w % 2 !== 0;
+		const isNeg = wbits < 0;
+		if (wbits === 0) f = f.add(ctneg(isEven, comp[offF]));
+		else p = p.add(ctneg(isNeg, comp[offP]));
+	}
+	return {
+		p,
+		f
+	};
+};
+
+//#endregion
+//#region node_modules/@noble/hashes/esm/utils.js
+/** Checks if something is Uint8Array. Be careful: nodejs Buffer will return true. */
+function isBytes(a) {
+	return a instanceof Uint8Array || ArrayBuffer.isView(a) && a.constructor.name === "Uint8Array";
+}
+/** Asserts something is Uint8Array. */
+function abytes(b, ...lengths) {
+	if (!isBytes(b)) throw new Error("Uint8Array expected");
+	if (lengths.length > 0 && !lengths.includes(b.length)) throw new Error("Uint8Array expected of length " + lengths + ", got length=" + b.length);
+}
+/** Asserts a hash instance has not been destroyed / finished */
+function aexists(instance, checkFinished = true) {
+	if (instance.destroyed) throw new Error("Hash instance has been destroyed");
+	if (checkFinished && instance.finished) throw new Error("Hash#digest() has already been called");
+}
+/** Asserts output is properly-sized byte array */
+function aoutput(out, instance) {
+	abytes(out);
+	const min = instance.outputLen;
+	if (out.length < min) throw new Error("digestInto() expects output buffer of length at least " + min);
+}
+/** Zeroize a byte array. Warning: JS provides no guarantees. */
+function clean(...arrays) {
+	for (let i = 0; i < arrays.length; i++) arrays[i].fill(0);
+}
+/** Create DataView of an array for easy byte-level manipulation. */
+function createView(arr) {
+	return new DataView(arr.buffer, arr.byteOffset, arr.byteLength);
+}
+/** Is current platform little-endian? Most are. Big-Endian platform: IBM */
+const isLE = new Uint8Array(new Uint32Array([287454020]).buffer)[0] === 68;
+const hasHexBuiltin = typeof Uint8Array.from([]).toHex === "function" && typeof Uint8Array.fromHex === "function";
+/**
+* Converts string to bytes using UTF8 encoding.
+* @example utf8ToBytes('abc') // Uint8Array.from([97, 98, 99])
+*/
+function utf8ToBytes(str) {
+	if (typeof str !== "string") throw new Error("string expected");
+	return new Uint8Array(new TextEncoder().encode(str));
+}
+/**
+* Normalizes (non-hex) string or Uint8Array to Uint8Array.
+* Warning: when Uint8Array is passed, it would NOT get copied.
+* Keep in mind for future mutable operations.
+*/
+function toBytes(data) {
+	if (typeof data === "string") data = utf8ToBytes(data);
+	abytes(data);
+	return data;
+}
+/** For runtime check if class implements interface */
+var Hash = class {};
+/** Wraps hash function, creating an interface on top of it */
+function createHasher(hashCons) {
+	const hashC = (msg) => hashCons().update(toBytes(msg)).digest();
+	const tmp = hashCons();
+	hashC.outputLen = tmp.outputLen;
+	hashC.blockLen = tmp.blockLen;
+	hashC.create = () => hashCons();
+	return hashC;
+}
+
+//#endregion
+//#region node_modules/@noble/hashes/esm/_md.js
+/**
+* Internal Merkle-Damgard hash utils.
+* @module
+*/
+/** Polyfill for Safari 14. https://caniuse.com/mdn-javascript_builtins_dataview_setbiguint64 */
+function setBigUint64(view, byteOffset, value, isLE) {
+	if (typeof view.setBigUint64 === "function") return view.setBigUint64(byteOffset, value, isLE);
+	const _32n = BigInt(32);
+	const _u32_max = BigInt(4294967295);
+	const wh = Number(value >> _32n & _u32_max);
+	const wl = Number(value & _u32_max);
+	const h = isLE ? 4 : 0;
+	const l = isLE ? 0 : 4;
+	view.setUint32(byteOffset + h, wh, isLE);
+	view.setUint32(byteOffset + l, wl, isLE);
+}
+/**
+* Merkle-Damgard hash construction base class.
+* Could be used to create MD5, RIPEMD, SHA1, SHA2.
+*/
+var HashMD = class extends Hash {
+	constructor(blockLen, outputLen, padOffset, isLE) {
+		super();
+		this.finished = false;
+		this.length = 0;
+		this.pos = 0;
+		this.destroyed = false;
+		this.blockLen = blockLen;
+		this.outputLen = outputLen;
+		this.padOffset = padOffset;
+		this.isLE = isLE;
+		this.buffer = new Uint8Array(blockLen);
+		this.view = createView(this.buffer);
+	}
+	update(data) {
+		aexists(this);
+		data = toBytes(data);
+		abytes(data);
+		const { view, buffer, blockLen } = this;
+		const len = data.length;
+		for (let pos = 0; pos < len;) {
+			const take = Math.min(blockLen - this.pos, len - pos);
+			if (take === blockLen) {
+				const dataView = createView(data);
+				for (; blockLen <= len - pos; pos += blockLen) this.process(dataView, pos);
+				continue;
+			}
+			buffer.set(data.subarray(pos, pos + take), this.pos);
+			this.pos += take;
+			pos += take;
+			if (this.pos === blockLen) {
+				this.process(view, 0);
+				this.pos = 0;
+			}
+		}
+		this.length += data.length;
+		this.roundClean();
+		return this;
+	}
+	digestInto(out) {
+		aexists(this);
+		aoutput(out, this);
+		this.finished = true;
+		const { buffer, view, blockLen, isLE } = this;
+		let { pos } = this;
+		buffer[pos++] = 128;
+		clean(this.buffer.subarray(pos));
+		if (this.padOffset > blockLen - pos) {
+			this.process(view, 0);
+			pos = 0;
+		}
+		for (let i = pos; i < blockLen; i++) buffer[i] = 0;
+		setBigUint64(view, blockLen - 8, BigInt(this.length * 8), isLE);
+		this.process(view, 0);
+		const oview = createView(out);
+		const len = this.outputLen;
+		if (len % 4) throw new Error("_sha2: outputLen should be aligned to 32bit");
+		const outLen = len / 4;
+		const state = this.get();
+		if (outLen > state.length) throw new Error("_sha2: outputLen bigger than state");
+		for (let i = 0; i < outLen; i++) oview.setUint32(4 * i, state[i], isLE);
+	}
+	digest() {
+		const { buffer, outputLen } = this;
+		this.digestInto(buffer);
+		const res = buffer.slice(0, outputLen);
+		this.destroy();
+		return res;
+	}
+	_cloneInto(to) {
+		to || (to = new this.constructor());
+		to.set(...this.get());
+		const { blockLen, buffer, length, finished, destroyed, pos } = this;
+		to.destroyed = destroyed;
+		to.finished = finished;
+		to.length = length;
+		to.pos = pos;
+		if (length % blockLen) to.buffer.set(buffer);
+		return to;
+	}
+	clone() {
+		return this._cloneInto();
+	}
+};
+/** Initial SHA512 state. Bits 0..64 of frac part of sqrt of primes 2..19 */
+const SHA512_IV = /* @__PURE__ */ Uint32Array.from([
+	1779033703,
+	4089235720,
+	3144134277,
+	2227873595,
+	1013904242,
+	4271175723,
+	2773480762,
+	1595750129,
+	1359893119,
+	2917565137,
+	2600822924,
+	725511199,
+	528734635,
+	4215389547,
+	1541459225,
+	327033209
+]);
+
+//#endregion
+//#region node_modules/@noble/hashes/esm/_u64.js
+/**
+* Internal helpers for u64. BigUint64Array is too slow as per 2025, so we implement it using Uint32Array.
+* @todo re-check https://issues.chromium.org/issues/42212588
+* @module
+*/
+const U32_MASK64 = /* @__PURE__ */ BigInt(2 ** 32 - 1);
+const _32n = /* @__PURE__ */ BigInt(32);
+function fromBig(n, le = false) {
+	if (le) return {
+		h: Number(n & U32_MASK64),
+		l: Number(n >> _32n & U32_MASK64)
+	};
+	return {
+		h: Number(n >> _32n & U32_MASK64) | 0,
+		l: Number(n & U32_MASK64) | 0
+	};
+}
+function split(lst, le = false) {
+	const len = lst.length;
+	let Ah = new Uint32Array(len);
+	let Al = new Uint32Array(len);
+	for (let i = 0; i < len; i++) {
+		const { h, l } = fromBig(lst[i], le);
+		[Ah[i], Al[i]] = [h, l];
+	}
+	return [Ah, Al];
+}
+const shrSH = (h, _l, s) => h >>> s;
+const shrSL = (h, l, s) => h << 32 - s | l >>> s;
+const rotrSH = (h, l, s) => h >>> s | l << 32 - s;
+const rotrSL = (h, l, s) => h << 32 - s | l >>> s;
+const rotrBH = (h, l, s) => h << 64 - s | l >>> s - 32;
+const rotrBL = (h, l, s) => h >>> s - 32 | l << 64 - s;
+function add(Ah, Al, Bh, Bl) {
+	const l = (Al >>> 0) + (Bl >>> 0);
+	return {
+		h: Ah + Bh + (l / 2 ** 32 | 0) | 0,
+		l: l | 0
+	};
+}
+const add3L = (Al, Bl, Cl) => (Al >>> 0) + (Bl >>> 0) + (Cl >>> 0);
+const add3H = (low, Ah, Bh, Ch) => Ah + Bh + Ch + (low / 2 ** 32 | 0) | 0;
+const add4L = (Al, Bl, Cl, Dl) => (Al >>> 0) + (Bl >>> 0) + (Cl >>> 0) + (Dl >>> 0);
+const add4H = (low, Ah, Bh, Ch, Dh) => Ah + Bh + Ch + Dh + (low / 2 ** 32 | 0) | 0;
+const add5L = (Al, Bl, Cl, Dl, El) => (Al >>> 0) + (Bl >>> 0) + (Cl >>> 0) + (Dl >>> 0) + (El >>> 0);
+const add5H = (low, Ah, Bh, Ch, Dh, Eh) => Ah + Bh + Ch + Dh + Eh + (low / 2 ** 32 | 0) | 0;
+
+//#endregion
+//#region node_modules/@noble/hashes/esm/sha2.js
+/**
+* SHA2 hash function. A.k.a. sha256, sha384, sha512, sha512_224, sha512_256.
+* SHA256 is the fastest hash implementable in JS, even faster than Blake3.
+* Check out [RFC 4634](https://datatracker.ietf.org/doc/html/rfc4634) and
+* [FIPS 180-4](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf).
+* @module
+*/
+const K512 = split([
+	"0x428a2f98d728ae22",
+	"0x7137449123ef65cd",
+	"0xb5c0fbcfec4d3b2f",
+	"0xe9b5dba58189dbbc",
+	"0x3956c25bf348b538",
+	"0x59f111f1b605d019",
+	"0x923f82a4af194f9b",
+	"0xab1c5ed5da6d8118",
+	"0xd807aa98a3030242",
+	"0x12835b0145706fbe",
+	"0x243185be4ee4b28c",
+	"0x550c7dc3d5ffb4e2",
+	"0x72be5d74f27b896f",
+	"0x80deb1fe3b1696b1",
+	"0x9bdc06a725c71235",
+	"0xc19bf174cf692694",
+	"0xe49b69c19ef14ad2",
+	"0xefbe4786384f25e3",
+	"0x0fc19dc68b8cd5b5",
+	"0x240ca1cc77ac9c65",
+	"0x2de92c6f592b0275",
+	"0x4a7484aa6ea6e483",
+	"0x5cb0a9dcbd41fbd4",
+	"0x76f988da831153b5",
+	"0x983e5152ee66dfab",
+	"0xa831c66d2db43210",
+	"0xb00327c898fb213f",
+	"0xbf597fc7beef0ee4",
+	"0xc6e00bf33da88fc2",
+	"0xd5a79147930aa725",
+	"0x06ca6351e003826f",
+	"0x142929670a0e6e70",
+	"0x27b70a8546d22ffc",
+	"0x2e1b21385c26c926",
+	"0x4d2c6dfc5ac42aed",
+	"0x53380d139d95b3df",
+	"0x650a73548baf63de",
+	"0x766a0abb3c77b2a8",
+	"0x81c2c92e47edaee6",
+	"0x92722c851482353b",
+	"0xa2bfe8a14cf10364",
+	"0xa81a664bbc423001",
+	"0xc24b8b70d0f89791",
+	"0xc76c51a30654be30",
+	"0xd192e819d6ef5218",
+	"0xd69906245565a910",
+	"0xf40e35855771202a",
+	"0x106aa07032bbd1b8",
+	"0x19a4c116b8d2d0c8",
+	"0x1e376c085141ab53",
+	"0x2748774cdf8eeb99",
+	"0x34b0bcb5e19b48a8",
+	"0x391c0cb3c5c95a63",
+	"0x4ed8aa4ae3418acb",
+	"0x5b9cca4f7763e373",
+	"0x682e6ff3d6b2b8a3",
+	"0x748f82ee5defb2fc",
+	"0x78a5636f43172f60",
+	"0x84c87814a1f0ab72",
+	"0x8cc702081a6439ec",
+	"0x90befffa23631e28",
+	"0xa4506cebde82bde9",
+	"0xbef9a3f7b2c67915",
+	"0xc67178f2e372532b",
+	"0xca273eceea26619c",
+	"0xd186b8c721c0c207",
+	"0xeada7dd6cde0eb1e",
+	"0xf57d4f7fee6ed178",
+	"0x06f067aa72176fba",
+	"0x0a637dc5a2c898a6",
+	"0x113f9804bef90dae",
+	"0x1b710b35131c471b",
+	"0x28db77f523047d84",
+	"0x32caab7b40c72493",
+	"0x3c9ebe0a15c9bebc",
+	"0x431d67c49c100d4c",
+	"0x4cc5d4becb3e42b6",
+	"0x597f299cfc657e2a",
+	"0x5fcb6fab3ad6faec",
+	"0x6c44198c4a475817"
+].map((n) => BigInt(n)));
+const SHA512_Kh = K512[0];
+const SHA512_Kl = K512[1];
+const SHA512_W_H = /* @__PURE__ */ new Uint32Array(80);
+const SHA512_W_L = /* @__PURE__ */ new Uint32Array(80);
+var SHA512 = class extends HashMD {
+	constructor(outputLen = 64) {
+		super(128, outputLen, 16, false);
+		this.Ah = SHA512_IV[0] | 0;
+		this.Al = SHA512_IV[1] | 0;
+		this.Bh = SHA512_IV[2] | 0;
+		this.Bl = SHA512_IV[3] | 0;
+		this.Ch = SHA512_IV[4] | 0;
+		this.Cl = SHA512_IV[5] | 0;
+		this.Dh = SHA512_IV[6] | 0;
+		this.Dl = SHA512_IV[7] | 0;
+		this.Eh = SHA512_IV[8] | 0;
+		this.El = SHA512_IV[9] | 0;
+		this.Fh = SHA512_IV[10] | 0;
+		this.Fl = SHA512_IV[11] | 0;
+		this.Gh = SHA512_IV[12] | 0;
+		this.Gl = SHA512_IV[13] | 0;
+		this.Hh = SHA512_IV[14] | 0;
+		this.Hl = SHA512_IV[15] | 0;
+	}
+	get() {
+		const { Ah, Al, Bh, Bl, Ch, Cl, Dh, Dl, Eh, El, Fh, Fl, Gh, Gl, Hh, Hl } = this;
+		return [
+			Ah,
+			Al,
+			Bh,
+			Bl,
+			Ch,
+			Cl,
+			Dh,
+			Dl,
+			Eh,
+			El,
+			Fh,
+			Fl,
+			Gh,
+			Gl,
+			Hh,
+			Hl
+		];
+	}
+	set(Ah, Al, Bh, Bl, Ch, Cl, Dh, Dl, Eh, El, Fh, Fl, Gh, Gl, Hh, Hl) {
+		this.Ah = Ah | 0;
+		this.Al = Al | 0;
+		this.Bh = Bh | 0;
+		this.Bl = Bl | 0;
+		this.Ch = Ch | 0;
+		this.Cl = Cl | 0;
+		this.Dh = Dh | 0;
+		this.Dl = Dl | 0;
+		this.Eh = Eh | 0;
+		this.El = El | 0;
+		this.Fh = Fh | 0;
+		this.Fl = Fl | 0;
+		this.Gh = Gh | 0;
+		this.Gl = Gl | 0;
+		this.Hh = Hh | 0;
+		this.Hl = Hl | 0;
+	}
+	process(view, offset) {
+		for (let i = 0; i < 16; i++, offset += 4) {
+			SHA512_W_H[i] = view.getUint32(offset);
+			SHA512_W_L[i] = view.getUint32(offset += 4);
+		}
+		for (let i = 16; i < 80; i++) {
+			const W15h = SHA512_W_H[i - 15] | 0;
+			const W15l = SHA512_W_L[i - 15] | 0;
+			const s0h = rotrSH(W15h, W15l, 1) ^ rotrSH(W15h, W15l, 8) ^ shrSH(W15h, W15l, 7);
+			const s0l = rotrSL(W15h, W15l, 1) ^ rotrSL(W15h, W15l, 8) ^ shrSL(W15h, W15l, 7);
+			const W2h = SHA512_W_H[i - 2] | 0;
+			const W2l = SHA512_W_L[i - 2] | 0;
+			const s1h = rotrSH(W2h, W2l, 19) ^ rotrBH(W2h, W2l, 61) ^ shrSH(W2h, W2l, 6);
+			const s1l = rotrSL(W2h, W2l, 19) ^ rotrBL(W2h, W2l, 61) ^ shrSL(W2h, W2l, 6);
+			const SUMl = add4L(s0l, s1l, SHA512_W_L[i - 7], SHA512_W_L[i - 16]);
+			SHA512_W_H[i] = add4H(SUMl, s0h, s1h, SHA512_W_H[i - 7], SHA512_W_H[i - 16]) | 0;
+			SHA512_W_L[i] = SUMl | 0;
+		}
+		let { Ah, Al, Bh, Bl, Ch, Cl, Dh, Dl, Eh, El, Fh, Fl, Gh, Gl, Hh, Hl } = this;
+		for (let i = 0; i < 80; i++) {
+			const sigma1h = rotrSH(Eh, El, 14) ^ rotrSH(Eh, El, 18) ^ rotrBH(Eh, El, 41);
+			const sigma1l = rotrSL(Eh, El, 14) ^ rotrSL(Eh, El, 18) ^ rotrBL(Eh, El, 41);
+			const CHIh = Eh & Fh ^ ~Eh & Gh;
+			const CHIl = El & Fl ^ ~El & Gl;
+			const T1ll = add5L(Hl, sigma1l, CHIl, SHA512_Kl[i], SHA512_W_L[i]);
+			const T1h = add5H(T1ll, Hh, sigma1h, CHIh, SHA512_Kh[i], SHA512_W_H[i]);
+			const T1l = T1ll | 0;
+			const sigma0h = rotrSH(Ah, Al, 28) ^ rotrBH(Ah, Al, 34) ^ rotrBH(Ah, Al, 39);
+			const sigma0l = rotrSL(Ah, Al, 28) ^ rotrBL(Ah, Al, 34) ^ rotrBL(Ah, Al, 39);
+			const MAJh = Ah & Bh ^ Ah & Ch ^ Bh & Ch;
+			const MAJl = Al & Bl ^ Al & Cl ^ Bl & Cl;
+			Hh = Gh | 0;
+			Hl = Gl | 0;
+			Gh = Fh | 0;
+			Gl = Fl | 0;
+			Fh = Eh | 0;
+			Fl = El | 0;
+			({h: Eh, l: El} = add(Dh | 0, Dl | 0, T1h | 0, T1l | 0));
+			Dh = Ch | 0;
+			Dl = Cl | 0;
+			Ch = Bh | 0;
+			Cl = Bl | 0;
+			Bh = Ah | 0;
+			Bl = Al | 0;
+			const All = add3L(T1l, sigma0l, MAJl);
+			Ah = add3H(All, T1h, sigma0h, MAJh);
+			Al = All | 0;
+		}
+		({h: Ah, l: Al} = add(this.Ah | 0, this.Al | 0, Ah | 0, Al | 0));
+		({h: Bh, l: Bl} = add(this.Bh | 0, this.Bl | 0, Bh | 0, Bl | 0));
+		({h: Ch, l: Cl} = add(this.Ch | 0, this.Cl | 0, Ch | 0, Cl | 0));
+		({h: Dh, l: Dl} = add(this.Dh | 0, this.Dl | 0, Dh | 0, Dl | 0));
+		({h: Eh, l: El} = add(this.Eh | 0, this.El | 0, Eh | 0, El | 0));
+		({h: Fh, l: Fl} = add(this.Fh | 0, this.Fl | 0, Fh | 0, Fl | 0));
+		({h: Gh, l: Gl} = add(this.Gh | 0, this.Gl | 0, Gh | 0, Gl | 0));
+		({h: Hh, l: Hl} = add(this.Hh | 0, this.Hl | 0, Hh | 0, Hl | 0));
+		this.set(Ah, Al, Bh, Bl, Ch, Cl, Dh, Dl, Eh, El, Fh, Fl, Gh, Gl, Hh, Hl);
+	}
+	roundClean() {
+		clean(SHA512_W_H, SHA512_W_L);
+	}
+	destroy() {
+		clean(this.buffer);
+		this.set(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0);
+	}
+};
+/** SHA2-512 hash function from RFC 4634. */
+const sha512 = /* @__PURE__ */ createHasher(() => new SHA512());
+
+//#endregion
+//#region packages/mcp/src/crypto.ts
+/**
+* Ed25519 key generation, persistence, and challenge signing for MCP agent auth.
+*/
+etc.sha512Sync = (...msgs) => sha512(etc.concatBytes(...msgs));
+const DEFAULT_KEY_PATH = join(homedir(), ".abracadabra", "agent.key");
+function toBase64url(bytes) {
+	return Buffer.from(bytes).toString("base64url");
+}
+function fromBase64url(b64) {
+	return new Uint8Array(Buffer.from(b64, "base64url"));
+}
+/**
+* Load an existing Ed25519 keypair from disk, or generate and persist a new one.
+* The file stores the raw 32-byte private key seed.
+*/
+async function loadOrCreateKeypair(keyPath) {
+	const path = keyPath || DEFAULT_KEY_PATH;
+	if (existsSync(path)) {
+		const seed = await readFile(path);
+		if (seed.length !== 32) throw new Error(`Invalid key file at ${path}: expected 32 bytes, got ${seed.length}`);
+		const privateKey = new Uint8Array(seed);
+		return {
+			privateKey,
+			publicKeyB64: toBase64url(getPublicKey(privateKey))
+		};
+	}
+	const privateKey = utils.randomPrivateKey();
+	const publicKey = getPublicKey(privateKey);
+	const dir = dirname(path);
+	if (!existsSync(dir)) await mkdir(dir, {
+		recursive: true,
+		mode: 448
+	});
+	await writeFile(path, Buffer.from(privateKey), { mode: 384 });
+	console.error(`[abracadabra-mcp] Generated new agent keypair at ${path}`);
+	console.error(`[abracadabra-mcp] Public key: ${toBase64url(publicKey)}`);
+	return {
+		privateKey,
+		publicKeyB64: toBase64url(publicKey)
+	};
+}
+/** Sign a base64url challenge with the agent's private key; returns base64url signature. */
+function signChallenge(challengeB64, privateKey) {
+	const challenge = fromBase64url(challengeB64);
+	return toBase64url(sign(challenge, privateKey));
+}
+
 //#endregion
 //#region packages/mcp/src/server.ts
 /**
@@ -18483,20 +19473,28 @@ var AbracadabraMCPServer = class {
 	get userId() {
 		return this._userId;
 	}
-	/** Start the server: login, discover spaces/root doc, connect provider. */
+	/** Start the server: authenticate with Ed25519 key, discover spaces/root doc, connect provider. */
 	async connect() {
-		await this.client.login({
-			username: this.config.username,
-			password: this.config.password
-		});
-		console.error(`[abracadabra-mcp] Logged in as ${this.config.username}`);
+		const keypair = await loadOrCreateKeypair(this.config.keyFile);
+		this._userId = keypair.publicKeyB64;
+		const signFn = (challenge) => Promise.resolve(signChallenge(challenge, keypair.privateKey));
 		try {
-			const me = await this.client.getMe();
-			this._userId = me.publicKey ?? me.id;
-			console.error(`[abracadabra-mcp] User ID (pubkey): ${this._userId}`);
-		} catch {
-			console.error("[abracadabra-mcp] Could not fetch user profile, proceeding without userId");
+			await this.client.loginWithKey(keypair.publicKeyB64, signFn);
+		} catch (err) {
+			const status = err?.status ?? err?.response?.status;
+			if (status === 404 || status === 422) {
+				console.error("[abracadabra-mcp] Key not registered, creating new account...");
+				await this.client.registerWithKey({
+					publicKey: keypair.publicKeyB64,
+					username: this.agentName.replace(/\s+/g, "-").toLowerCase(),
+					displayName: this.agentName,
+					deviceName: "MCP Agent",
+					inviteCode: this.config.inviteCode
+				});
+				await this.client.loginWithKey(keypair.publicKeyB64, signFn);
+			} else throw err;
 		}
+		console.error(`[abracadabra-mcp] Authenticated as ${this.agentName} (${keypair.publicKeyB64.slice(0, 12)}...)`);
 		this._serverInfo = await this.client.serverInfo();
 		let initialDocId = this._serverInfo.index_doc_id ?? null;
 		try {
@@ -18757,6 +19755,15 @@ var AbracadabraMCPServer = class {
 
 //#endregion
 //#region packages/mcp/src/tools/tree.ts
+/**
+* Normalize a document ID so the hub/root doc ID is treated as the tree root (null).
+* This lets callers pass the hub doc_id from list_spaces as parentId/rootId
+* and get the expected root-level results instead of an empty set.
+*/
+function normalizeRootId(id, server) {
+	if (id == null) return null;
+	return id === server.rootDocId ? null : id;
+}
 function readEntries$1(treeMap) {
 	const entries = [];
 	treeMap.forEach((value, id) => {
@@ -18778,7 +19785,10 @@ function childrenOf$1(entries, parentId) {
 }
 function descendantsOf(entries, id) {
 	const result = [];
+	const visited = /* @__PURE__ */ new Set();
 	function collect(pid) {
+		if (visited.has(pid)) return;
+		visited.add(pid);
 		for (const child of childrenOf$1(entries, pid)) {
 			result.push(child);
 			collect(child.id);
@@ -18787,32 +19797,36 @@ function descendantsOf(entries, id) {
 	collect(id);
 	return result;
 }
-function buildTree$1(entries, rootId, maxDepth, currentDepth = 0) {
+function buildTree$1(entries, rootId, maxDepth, currentDepth = 0, visited = /* @__PURE__ */ new Set()) {
 	if (maxDepth >= 0 && currentDepth >= maxDepth) return [];
-	return childrenOf$1(entries, rootId).map((entry) => ({
-		id: entry.id,
-		label: entry.label,
-		type: entry.type,
-		meta: entry.meta,
-		order: entry.order,
-		children: buildTree$1(entries, entry.id, maxDepth, currentDepth + 1)
-	}));
+	return childrenOf$1(entries, rootId).filter((e) => !visited.has(e.id)).map((entry) => {
+		const next = new Set(visited);
+		next.add(entry.id);
+		return {
+			id: entry.id,
+			label: entry.label,
+			type: entry.type,
+			meta: entry.meta,
+			order: entry.order,
+			children: buildTree$1(entries, entry.id, maxDepth, currentDepth + 1, next)
+		};
+	});
 }
 function registerTreeTools(mcp, server) {
-	mcp.tool("list_documents", "List direct children of a document (defaults to root). Returns id, label, type, meta, order.", { parentId: z.string().optional().describe("Parent document ID. Omit for root-level documents.") }, async ({ parentId }) => {
+	mcp.tool("list_documents", "List direct children of a document (defaults to root). Returns id, label, type, meta, order. NOTE: Only returns ONE level. Use find_document to search by name across the full tree, or get_document_tree to see the complete hierarchy.", { parentId: z.string().optional().describe("Parent document ID. Omit for root-level documents.") }, async ({ parentId }) => {
 		const treeMap = server.getTreeMap();
 		if (!treeMap) return { content: [{
 			type: "text",
 			text: "Not connected"
 		}] };
-		const targetId = parentId ?? null;
+		const targetId = normalizeRootId(parentId, server);
 		const children = childrenOf$1(readEntries$1(treeMap), targetId);
 		return { content: [{
 			type: "text",
 			text: JSON.stringify(children, null, 2)
 		}] };
 	});
-	mcp.tool("get_document_tree", "Get the full document tree as nested JSON. Useful for understanding the document structure.", {
+	mcp.tool("get_document_tree", "Get the full document tree as nested JSON. Call this FIRST when exploring a space or looking for documents — it shows the complete hierarchy including all nested documents. Use rootId to scope to a subtree.", {
 		rootId: z.string().optional().describe("Root document ID to start from. Omit for the entire tree."),
 		depth: z.number().optional().describe("Maximum depth to traverse. Default 3. Use -1 for unlimited.")
 	}, async ({ rootId, depth }) => {
@@ -18821,7 +19835,7 @@ function registerTreeTools(mcp, server) {
 			type: "text",
 			text: "Not connected"
 		}] };
-		const targetId = rootId ?? null;
+		const targetId = normalizeRootId(rootId, server);
 		const maxDepth = depth ?? 3;
 		const tree = buildTree$1(readEntries$1(treeMap), targetId, maxDepth);
 		return { content: [{
@@ -18829,10 +19843,52 @@ function registerTreeTools(mcp, server) {
 			text: JSON.stringify(tree, null, 2)
 		}] };
 	});
+	mcp.tool("find_document", "Search for documents by name across the entire tree. Returns matching documents with their full ancestor path. Use this when you're looking for a specific document and don't know where it is in the hierarchy.", {
+		query: z.string().describe("Search query — matched case-insensitively against document labels (substring match)."),
+		rootId: z.string().optional().describe("Restrict search to descendants of this document. Omit to search the entire tree.")
+	}, async ({ query, rootId }) => {
+		const treeMap = server.getTreeMap();
+		if (!treeMap) return { content: [{
+			type: "text",
+			text: "Not connected"
+		}] };
+		const entries = readEntries$1(treeMap);
+		const lowerQuery = query.toLowerCase();
+		const normalizedRoot = normalizeRootId(rootId, server);
+		const matches = (normalizedRoot ? descendantsOf(entries, normalizedRoot) : entries).filter((e) => e.label.toLowerCase().includes(lowerQuery));
+		const byId = new Map(entries.map((e) => [e.id, e]));
+		const results = matches.map((entry) => {
+			const path = [];
+			let current = entry.parentId;
+			const visited = /* @__PURE__ */ new Set();
+			while (current && !visited.has(current)) {
+				visited.add(current);
+				const parent = byId.get(current);
+				if (!parent) break;
+				path.unshift(parent.label);
+				current = parent.parentId;
+			}
+			return {
+				id: entry.id,
+				label: entry.label,
+				type: entry.type,
+				meta: entry.meta,
+				path
+			};
+		});
+		if (results.length === 0) return { content: [{
+			type: "text",
+			text: `No documents found matching "${query}". Try get_document_tree to see the full hierarchy.`
+		}] };
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(results, null, 2)
+		}] };
+	});
 	mcp.tool("create_document", "Create a new document in the tree. Returns the new document ID.", {
 		parentId: z.string().optional().describe("Parent document ID. Omit for top-level pages. Use a document ID for nested/child pages."),
 		label: z.string().describe("Display name / title for the document."),
-		type: z.string().optional().describe("Page type: \"doc\", \"kanban\", \"calendar\", \"table\", \"outline\", \"gallery\", \"slides\", \"timeline\", \"whiteboard\", \"map\", \"desktop\", \"mindmap\", \"graph\". Omit to inherit parent view."),
+		type: z.string().optional().describe("Page type: \"doc\", \"kanban\", \"calendar\", \"table\", \"outline\", \"gallery\", \"slides\", \"timeline\", \"whiteboard\", \"map\", \"dashboard\", \"mindmap\", \"graph\". Omit to inherit parent view."),
 		meta: z.record(z.unknown()).optional().describe("Initial metadata (PageMeta fields: color as hex string, icon as Lucide kebab-case name like \"star\"/\"code-2\"/\"users\" — never emoji, dateStart, dateEnd, priority 0-4, tags array, etc). Omit icon entirely to use page type default.")
 	}, async ({ parentId, label, type, meta }) => {
 		const treeMap = server.getTreeMap();
@@ -18842,11 +19898,12 @@ function registerTreeTools(mcp, server) {
 			text: "Not connected"
 		}] };
 		const id = crypto.randomUUID();
+		const normalizedParent = normalizeRootId(parentId, server);
 		const now = Date.now();
 		rootDoc.transact(() => {
 			treeMap.set(id, {
 				label,
-				parentId: parentId ?? null,
+				parentId: normalizedParent,
 				order: now,
 				type,
 				meta,
@@ -18905,7 +19962,7 @@ function registerTreeTools(mcp, server) {
 		}] };
 		treeMap.set(id, {
 			...entry,
-			parentId: newParentId ?? null,
+			parentId: normalizeRootId(newParentId, server),
 			order: order ?? Date.now(),
 			updatedAt: Date.now()
 		});
@@ -18946,7 +20003,7 @@ function registerTreeTools(mcp, server) {
 	});
 	mcp.tool("change_document_type", "Change the page type view of a document (data is preserved).", {
 		id: z.string().describe("Document ID."),
-		type: z.string().describe("New page type (e.g. \"doc\", \"kanban\", \"table\", \"calendar\", \"outline\", \"gallery\", \"slides\", \"timeline\", \"whiteboard\", \"map\", \"desktop\", \"mindmap\", \"graph\").")
+		type: z.string().describe("New page type (e.g. \"doc\", \"kanban\", \"table\", \"calendar\", \"outline\", \"gallery\", \"slides\", \"timeline\", \"whiteboard\", \"map\", \"dashboard\", \"mindmap\", \"graph\").")
 	}, async ({ id, type }) => {
 		const treeMap = server.getTreeMap();
 		if (!treeMap) return { content: [{
@@ -20932,36 +21989,63 @@ function registerServerInfoResource(mcp, server) {
 * Abracadabra MCP Server — entry point.
 *
 * Environment variables:
-*   ABRA_URL       (required) — Server URL (e.g. http://localhost:1234)
-*   ABRA_USERNAME  (required) — Service account username
-*   ABRA_PASSWORD  (required) — Service account password
-*   ABRA_AGENT_NAME           — Display name (default: "AI Assistant")
-*   ABRA_AGENT_COLOR          — HSL color for presence (default: "hsl(270, 80%, 60%)")
+*   ABRA_URL         (required) — Server URL (e.g. http://localhost:1234)
+*   ABRA_AGENT_NAME             — Display name (default: "AI Assistant")
+*   ABRA_AGENT_COLOR            — HSL color for presence (default: "hsl(270, 80%, 60%)")
+*   ABRA_INVITE_CODE            — Invite code for first-run registration (grants role)
+*   ABRA_KEY_FILE               — Path to Ed25519 key file (default: ~/.abracadabra/agent.key)
 */
 async function main() {
 	const url = process.env.ABRA_URL;
-	const username = process.env.ABRA_USERNAME;
-	const password = process.env.ABRA_PASSWORD;
-	if (!url || !username || !password) {
-		console.error("Missing required environment variables: ABRA_URL, ABRA_USERNAME, ABRA_PASSWORD");
+	if (!url) {
+		console.error("Missing required environment variable: ABRA_URL");
 		process.exit(1);
 	}
 	const server = new AbracadabraMCPServer({
 		url,
-		username,
-		password,
 		agentName: process.env.ABRA_AGENT_NAME,
-		agentColor: process.env.ABRA_AGENT_COLOR
+		agentColor: process.env.ABRA_AGENT_COLOR,
+		inviteCode: process.env.ABRA_INVITE_CODE,
+		keyFile: process.env.ABRA_KEY_FILE
 	});
 	const mcp = new McpServer({
 		name: "abracadabra",
 		version: "1.0.0"
 	}, {
 		capabilities: { experimental: { "claude/channel": {} } },
-		instructions: `Events from the abracadabra channel arrive as <channel source="abracadabra" ...>. They may be:
+		instructions: `Abracadabra is a CRDT collaboration platform where everything is a document in a tree.
+
+## Quick Start Workflow
+1. list_spaces → note the active space's doc_id (this is the hub/root document)
+2. get_document_tree(rootId: hubDocId) → see the FULL hierarchy before doing anything
+3. find_document(query) → search for a document by name if you know what you're looking for
+4. read_document / write_document / create_document → operate on specific documents
+
+## Key Concepts
+- Documents form a tree. A kanban board's columns are child documents; cards are grandchildren.
+- A document's label IS its display name everywhere. Children ARE the content (not just the body text).
+- Page types (doc, kanban, table, calendar, timeline, outline, etc.) are views over the SAME tree — switching types preserves data.
+- An empty markdown body does NOT mean empty content — always check the children array.
+
+## Finding Documents
+- list_documents only shows ONE level of children. If you don't find what you need, use find_document to search the entire tree by name, or get_document_tree to see the full hierarchy.
+- NEVER conclude a document doesn't exist after only checking root-level documents.
+
+## Rules
+- Always call list_spaces first to get the hub doc ID before creating documents.
+- Always call get_document_tree to understand existing structure before creating documents.
+- Use Lucide icon names in kebab-case (e.g. "star", "code-2") for meta.icon — NEVER emoji.
+- Never rename or write content to the hub document itself.
+- Use universal meta keys (color, icon, dateStart) — never prefix with page type names.
+
+## Channel Events
+Events from the abracadabra channel arrive as <channel source="abracadabra" ...>. They may be:
 - ai:task events from human users (includes sender, doc_id context)
 - chat messages from the platform chat system (includes channel, sender, sender_id)
-When you receive a channel event, read it, do the work using your tools, and reply using the reply tool (for document responses) or send_chat_message (for chat responses) with the appropriate context.`
+When you receive a channel event, read it, do the work using your tools, and reply using the reply tool (for document responses) or send_chat_message (for chat responses).
+
+## Full Reference
+Read the resource at abracadabra://agent-guide for the complete guide covering page type schemas, metadata reference, awareness/presence, content structure, and detailed examples.`
 	});
 	registerTreeTools(mcp, server);
 	registerContentTools(mcp, server);