@personaxis/core 0.11.0

package/dist/persona.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Persona file IO for the engine.
+ *
+ * The engine operates on a known PERSONA.md path (the active persona's compiled
+ * document) and its sibling state.json. Frontmatter carries the quantitative
+ * envelopes; state.json carries the mutable current values + mutation_log.
+ *
+ * This is intentionally narrow: path *resolution* (root vs subagent slugs) lives
+ * in the CLI's load.ts. The engine just reads/writes at given paths.
+ */
+/**
+ * Current state.json schema version (schema/state.schema.json's newest accepted
+ * value — 0.9.0 added the optional agent_session block; 0.10 changed no state
+ * fields). Single source for every seeder; keep in sync with the schema enum.
+ */
+export declare const STATE_SCHEMA_VERSION = "1.0.0";
+export interface PersonaFrontmatter {
+    [key: string]: unknown;
+}
+export interface MutationLogEntry {
+    ts: string;
+    field: string;
+    from: number;
+    to: number;
+    delta_requested: number;
+    clamped: boolean;
+    reason: string;
+    actor: "actor-llm" | "runtime-decay" | "runtime-context" | "human-operator" | "judge-correction";
+    tool_call_id?: string;
+    governance_blocked?: boolean;
+    /** v0.8: machine/instance that produced this mutation (cross-OS reconciliation). */
+    origin_node?: string;
+    /** v0.8: runtime session id, for traceability. */
+    session_id?: string;
+}
+export interface StateFile {
+    schema_version: string;
+    persona_id: string;
+    persona_version: string;
+    session_id?: string;
+    values: Record<string, number>;
+    active_context?: {
+        task_mode: string | null;
+        audience: string | null;
+        additional_context_flags?: string[];
+    };
+    memory_anchors_active?: string[];
+    mutation_log: MutationLogEntry[];
+    last_compiled_at?: string | null;
+    last_compiled_hash?: string | null;
+    /** v0.9: live agent-loop session tracking (resumable across runs). */
+    agent_session?: {
+        active_task: string | null;
+        started_at: string | null;
+        step_count: number;
+        token_count: number;
+        cost_usd: number;
+        stop_reason: string | null;
+    };
+}
+/** A persona handle: resolved paths + parsed frontmatter. */
+export interface PersonaHandle {
+    /** Path to the compiled PERSONA.md (or .claude/agents/<slug>.md). */
+    personaPath: string;
+    /** Path to sibling state.json. */
+    statePath: string;
+    /** Parsed YAML frontmatter from PERSONA.md (quantitative layers + envelopes). */
+    frontmatter: PersonaFrontmatter;
+    /** Raw markdown body (the qualitative compiled document). */
+    body: string;
+}
+export declare function loadPersona(personaPathArg: string): PersonaHandle;
+export declare function readState(statePath: string): StateFile;
+/**
+ * Atomic write: temp file + rename in the same directory, so concurrent readers
+ * (dash polling, another CLI) always see a complete JSON document — never a torn
+ * partial write. Serialization of read→modify→write sequences is the caller's job
+ * via withStateLock (see lock.ts).
+ */
+export declare function writeState(statePath: string, state: StateFile): void;
+export declare function stateExists(statePath: string): boolean;
+/** The human-facing name of a persona, from its frontmatter. */
+export declare function displayName(fm: PersonaFrontmatter): string;
+/**
+ * Return the persona's state, seeding a fresh state.json from envelope means if
+ * none exists yet. Keeps hosts (REPL, MCP) working out-of-the-box.
+ */
+export declare function ensureState(handle: PersonaHandle): StateFile;

package/dist/persona.js

@@ -0,0 +1,93 @@
+/**
+ * Persona file IO for the engine.
+ *
+ * The engine operates on a known PERSONA.md path (the active persona's compiled
+ * document) and its sibling state.json. Frontmatter carries the quantitative
+ * envelopes; state.json carries the mutable current values + mutation_log.
+ *
+ * This is intentionally narrow: path *resolution* (root vs subagent slugs) lives
+ * in the CLI's load.ts. The engine just reads/writes at given paths.
+ */
+import { readFileSync, writeFileSync, existsSync, renameSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import matter from "gray-matter";
+import { extractEnvelopes } from "./envelopes.js";
+import { withStateLock } from "./lock.js";
+/**
+ * Current state.json schema version (schema/state.schema.json's newest accepted
+ * value — 0.9.0 added the optional agent_session block; 0.10 changed no state
+ * fields). Single source for every seeder; keep in sync with the schema enum.
+ */
+export const STATE_SCHEMA_VERSION = "1.0.0";
+export function loadPersona(personaPathArg) {
+    const personaPath = resolve(personaPathArg);
+    if (!existsSync(personaPath)) {
+        throw new Error(`PERSONA.md not found at ${personaPath}`);
+    }
+    const raw = readFileSync(personaPath, "utf-8");
+    const parsed = matter(raw);
+    return {
+        personaPath,
+        statePath: join(dirname(personaPath), "state.json"),
+        frontmatter: (parsed.data ?? {}),
+        body: parsed.content ?? "",
+    };
+}
+export function readState(statePath) {
+    if (!existsSync(statePath)) {
+        throw new Error(`state.json not found at ${statePath}. Run 'personaxis state init' first.`);
+    }
+    return JSON.parse(readFileSync(statePath, "utf-8"));
+}
+/**
+ * Atomic write: temp file + rename in the same directory, so concurrent readers
+ * (dash polling, another CLI) always see a complete JSON document — never a torn
+ * partial write. Serialization of read→modify→write sequences is the caller's job
+ * via withStateLock (see lock.ts).
+ */
+export function writeState(statePath, state) {
+    const tmp = `${statePath}.${process.pid}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+    writeFileSync(tmp, JSON.stringify(state, null, 2) + "\n", "utf-8");
+    renameSync(tmp, statePath);
+}
+export function stateExists(statePath) {
+    return existsSync(statePath);
+}
+/** The human-facing name of a persona, from its frontmatter. */
+export function displayName(fm) {
+    const id = fm.identity;
+    const meta = fm.metadata;
+    return id?.display_name ?? meta?.name ?? id?.canonical_id ?? "persona";
+}
+/**
+ * Return the persona's state, seeding a fresh state.json from envelope means if
+ * none exists yet. Keeps hosts (REPL, MCP) working out-of-the-box.
+ */
+export function ensureState(handle) {
+    if (existsSync(handle.statePath))
+        return readState(handle.statePath);
+    // Seeding races with other processes seeding the same persona — take the lock and
+    // re-check so exactly one seeder wins.
+    return withStateLock(handle.statePath, () => {
+        if (existsSync(handle.statePath))
+            return readState(handle.statePath);
+        const env = extractEnvelopes(handle.frontmatter);
+        const meta = (handle.frontmatter.metadata ?? {});
+        const values = {};
+        for (const [k, e] of Object.entries(env.envelopes))
+            values[k] = e.mean;
+        const state = {
+            schema_version: STATE_SCHEMA_VERSION,
+            persona_id: meta.name ?? "persona",
+            persona_version: meta.version ?? "0.0.0",
+            values,
+            active_context: { task_mode: null, audience: null, additional_context_flags: [] },
+            memory_anchors_active: [],
+            mutation_log: [],
+            last_compiled_at: null,
+            last_compiled_hash: null,
+        };
+        writeState(handle.statePath, state);
+        return state;
+    });
+}

package/dist/ports/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * F3.3 — storage ports (the hexagonal seam, "only where it hurts": persistence).
+ *
+ * The engine's spec-faithful logic — clamp+audit mutation, the governance gate,
+ * the hash-chained ledger, the Living Loop — is pure and unchanged. What varies
+ * between a local CLI and the managed SaaS is only WHERE bytes live: the local
+ * default is a git-versionable persona folder (atomic writes + a per-persona
+ * lock); the SaaS is Postgres/S3 over the SAME engine. These ports are that
+ * boundary, and `defaultFsStorage()` is the reference (filesystem) adapter.
+ *
+ * Ports (each keyed by the persona's path/id so one engine can host many):
+ *   - LockProvider  — serialize read→modify→write (same-machine default; a
+ *                     distributed lock in the SaaS);
+ *   - StateStore    — state.json (the runtime checkpoint);
+ *   - MemoryStore   — semantic memory (memory.md) + consolidation;
+ *   - LedgerStore   — the append-only, hash-chained EPISODIC ledger
+ *                     (tamper-evident; append + read + verify + redact);
+ *   - ModelClient   — the LLM call the compiler/appraiser makes (the SaaS
+ *                     injects its hosted model; the loop's appraiser is the
+ *                     existing model seam and stays injectable separately).
+ */
+import type { StateFile } from "../persona.js";
+import type { MemoryEntry } from "../memory.js";
+export interface LockProvider {
+    /** Run `fn` while holding the exclusive lock for `key` (a persona's state path). */
+    withLock<T>(key: string, fn: () => T): T;
+}
+export interface StateStore {
+    read(key: string): StateFile;
+    write(key: string, state: StateFile): void;
+    exists(key: string): boolean;
+}
+export interface MemoryStore {
+    /** The curated long-term semantic memory (memory.md) as text. */
+    readSemantic(key: string): string;
+    /** Consolidate recent episodic entries into semantic memory. */
+    consolidate(key: string, limit?: number): {
+        ok: boolean;
+        path: string;
+        count: number;
+    };
+}
+export interface ChainVerification {
+    ok: boolean;
+    brokenAt?: number;
+}
+export interface LedgerStore {
+    /** All episodic entries (the hash-chained ledger), oldest→newest. */
+    read(key: string): MemoryEntry[];
+    /** Append one entry, extending the hash chain. */
+    append(key: string, entry: MemoryEntry): void;
+    /** Verify the chain is intact (tamper-evidence). */
+    verify(key: string): ChainVerification;
+    /** Erase an entry's content while keeping the chain verifiable (right-to-delete). */
+    redact(key: string, id: string, reason: string): {
+        redacted: boolean;
+    };
+}
+export interface ModelCompletion {
+    text: string;
+    model: string;
+}
+export interface ModelClient {
+    complete(prompt: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<ModelCompletion>;
+}
+/** The full storage bundle an engine host can inject. `model` is optional. */
+export interface Storage {
+    lock: LockProvider;
+    state: StateStore;
+    memory: MemoryStore;
+    ledger: LedgerStore;
+    model?: ModelClient;
+}
+export declare const fsLockProvider: LockProvider;
+export declare const fsStateStore: StateStore;
+export declare const fsMemoryStore: MemoryStore;
+export declare const fsLedgerStore: LedgerStore;
+/** The default filesystem storage bundle (git-versionable persona folder). */
+export declare function defaultFsStorage(): Storage;

package/dist/ports/index.js

@@ -0,0 +1,50 @@
+/**
+ * F3.3 — storage ports (the hexagonal seam, "only where it hurts": persistence).
+ *
+ * The engine's spec-faithful logic — clamp+audit mutation, the governance gate,
+ * the hash-chained ledger, the Living Loop — is pure and unchanged. What varies
+ * between a local CLI and the managed SaaS is only WHERE bytes live: the local
+ * default is a git-versionable persona folder (atomic writes + a per-persona
+ * lock); the SaaS is Postgres/S3 over the SAME engine. These ports are that
+ * boundary, and `defaultFsStorage()` is the reference (filesystem) adapter.
+ *
+ * Ports (each keyed by the persona's path/id so one engine can host many):
+ *   - LockProvider  — serialize read→modify→write (same-machine default; a
+ *                     distributed lock in the SaaS);
+ *   - StateStore    — state.json (the runtime checkpoint);
+ *   - MemoryStore   — semantic memory (memory.md) + consolidation;
+ *   - LedgerStore   — the append-only, hash-chained EPISODIC ledger
+ *                     (tamper-evident; append + read + verify + redact);
+ *   - ModelClient   — the LLM call the compiler/appraiser makes (the SaaS
+ *                     injects its hosted model; the loop's appraiser is the
+ *                     existing model seam and stays injectable separately).
+ */
+import { readState, writeState, stateExists, } from "../persona.js";
+import { withStateLock } from "../lock.js";
+import { readMemory, commitMemoryEntry, verifyMemoryChain, redactMemory, readSemanticMemory, consolidateSemantic, } from "../memory.js";
+// ── default filesystem adapters (the reference implementation) ──────────────────
+export const fsLockProvider = {
+    withLock: (key, fn) => withStateLock(key, fn),
+};
+export const fsStateStore = {
+    read: (key) => readState(key),
+    write: (key, state) => writeState(key, state),
+    exists: (key) => stateExists(key),
+};
+export const fsMemoryStore = {
+    readSemantic: (key) => readSemanticMemory(key),
+    consolidate: (key, limit) => consolidateSemantic(key, limit),
+};
+export const fsLedgerStore = {
+    read: (key) => readMemory(key),
+    append: (key, entry) => commitMemoryEntry(key, entry),
+    verify: (key) => verifyMemoryChain(key),
+    redact: (key, id, reason) => {
+        redactMemory(key, id, reason); // returns the redacted+audit entries or throws
+        return { redacted: true };
+    },
+};
+/** The default filesystem storage bundle (git-versionable persona folder). */
+export function defaultFsStorage() {
+    return { lock: fsLockProvider, state: fsStateStore, memory: fsMemoryStore, ledger: fsLedgerStore };
+}

package/dist/provenance.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Provenance & sensitive-action gates (F3 — plan/11-security).
+ *
+ * The memory-poisoning literature shows that "internal state = trusted" is a
+ * false assumption: untrusted content laundered through memory drives later
+ * "trusted" actions (Yang et al., 2026; Dash et al., 2026). Defenses here:
+ *   - rank every source by trust;
+ *   - gate sensitive actions on the *provenance of their justification* — if the
+ *     reasoning traces to an untrusted channel, the action is refused;
+ *   - a lightweight consensus check flags contradictory memory (A-MemGuard-style).
+ */
+import type { ProvenanceSource } from "./appraisal.js";
+import type { MemoryEntry } from "./memory.js";
+/** Higher = more trusted. tool/synthesis are the poisoning-prone channels. */
+export declare const TRUST: Record<ProvenanceSource, number>;
+export type SensitiveAction = "delete" | "external_api" | "credential_use" | "self_edit" | "file_write";
+/** Minimum justification trust required to dispatch each sensitive action. */
+export declare const ACTION_MIN_TRUST: Record<SensitiveAction, number>;
+export interface GateResult {
+    allowed: boolean;
+    action: SensitiveAction;
+    minTrust: number;
+    justificationTrust: number;
+    reason: string;
+}
+/**
+ * Decide whether a sensitive action may proceed given the provenance of the
+ * memory/observations justifying it. The weakest link wins: a single untrusted
+ * source in the justification chain caps the trust.
+ */
+export declare function sensitiveActionGate(action: SensitiveAction, justificationSources: ProvenanceSource[]): GateResult;
+export interface Anomaly {
+    kind: "contradiction" | "untrusted-spike" | "model-flagged";
+    detail: string;
+    entries: string[];
+}
+export interface AnomalyConfig {
+    /** Optional model classifier (A-MemGuard-style); fused with the heuristics. */
+    classifier?: (entry: MemoryEntry) => {
+        score: number;
+        label?: string;
+    };
+    /** Score at/above which a classifier hit becomes an anomaly. Default 0.7. */
+    threshold?: number;
+}
+/**
+ * Consensus / anomaly pass over recent memory. Explainable heuristics (negating
+ * statements, bursts of untrusted writes) PLUS an optional model-based check
+ * (Wei et al., 2025, A-MemGuard) fused in via `config.classifier`.
+ */
+export declare function detectMemoryAnomalies(entries: MemoryEntry[], config?: AnomalyConfig): Anomaly[];
+export type ConsensusVerdict = "consistent" | "conflicting" | "insufficient";
+export interface MemoryConsensus {
+    verdict: ConsensusVerdict;
+    supporting: string[];
+    contradicting: string[];
+}
+/**
+ * Multi-path consistency check (A-MemGuard): before a risky decision, ask whether
+ * the memory set agrees about a claim. Returns supporting vs contradicting entries
+ * and a verdict. `conflicting` is the signal to abstain / seek confirmation.
+ */
+export declare function memoryConsensus(entries: MemoryEntry[], claim: string): MemoryConsensus;

package/dist/provenance.js

@@ -0,0 +1,132 @@
+/**
+ * Provenance & sensitive-action gates (F3 — plan/11-security).
+ *
+ * The memory-poisoning literature shows that "internal state = trusted" is a
+ * false assumption: untrusted content laundered through memory drives later
+ * "trusted" actions (Yang et al., 2026; Dash et al., 2026). Defenses here:
+ *   - rank every source by trust;
+ *   - gate sensitive actions on the *provenance of their justification* — if the
+ *     reasoning traces to an untrusted channel, the action is refused;
+ *   - a lightweight consensus check flags contradictory memory (A-MemGuard-style).
+ */
+/** Higher = more trusted. tool/synthesis are the poisoning-prone channels. */
+export const TRUST = {
+    user: 3,
+    internal: 2,
+    synthesis: 1,
+    tool: 1,
+};
+/** Minimum justification trust required to dispatch each sensitive action. */
+export const ACTION_MIN_TRUST = {
+    delete: 3,
+    credential_use: 3,
+    external_api: 2,
+    self_edit: 3,
+    file_write: 2,
+};
+/**
+ * Decide whether a sensitive action may proceed given the provenance of the
+ * memory/observations justifying it. The weakest link wins: a single untrusted
+ * source in the justification chain caps the trust.
+ */
+export function sensitiveActionGate(action, justificationSources) {
+    const minTrust = ACTION_MIN_TRUST[action];
+    const justificationTrust = justificationSources.length === 0
+        ? 0
+        : Math.min(...justificationSources.map((s) => TRUST[s]));
+    const allowed = justificationTrust >= minTrust;
+    return {
+        allowed,
+        action,
+        minTrust,
+        justificationTrust,
+        reason: allowed
+            ? `justification trust ${justificationTrust} >= required ${minTrust}`
+            : `justification trust ${justificationTrust} < required ${minTrust} (untrusted provenance)`,
+    };
+}
+/**
+ * Consensus / anomaly pass over recent memory. Explainable heuristics (negating
+ * statements, bursts of untrusted writes) PLUS an optional model-based check
+ * (Wei et al., 2025, A-MemGuard) fused in via `config.classifier`.
+ */
+export function detectMemoryAnomalies(entries, config = {}) {
+    const anomalies = [];
+    const threshold = config.threshold ?? 0.7;
+    // 1. naive contradiction: "X" vs "not X" / "no X" on the same key phrase.
+    for (let i = 0; i < entries.length; i++) {
+        for (let j = i + 1; j < entries.length; j++) {
+            const a = entries[i].content.toLowerCase();
+            const b = entries[j].content.toLowerCase();
+            if (negates(a, b) || negates(b, a)) {
+                anomalies.push({
+                    kind: "contradiction",
+                    detail: `"${entries[i].content.slice(0, 40)}" vs "${entries[j].content.slice(0, 40)}"`,
+                    entries: [entries[i].hash, entries[j].hash],
+                });
+            }
+        }
+    }
+    // 2. untrusted spike: >=3 consecutive untrusted (tool/synthesis) writes.
+    let run = [];
+    for (const e of entries) {
+        if (TRUST[e.source] <= 1)
+            run.push(e);
+        else
+            run = [];
+        if (run.length >= 3) {
+            anomalies.push({
+                kind: "untrusted-spike",
+                detail: `${run.length} consecutive low-trust memory writes`,
+                entries: run.map((r) => r.hash),
+            });
+            run = [];
+        }
+    }
+    // 3. model-based pass (A-MemGuard): fuse a classifier's per-entry judgment.
+    if (config.classifier) {
+        for (const e of entries) {
+            const c = config.classifier(e);
+            if (c.score >= threshold) {
+                anomalies.push({
+                    kind: "model-flagged",
+                    detail: `${c.label ?? "anomalous"} (score ${c.score.toFixed(2)})`,
+                    entries: [e.hash],
+                });
+            }
+        }
+    }
+    return anomalies;
+}
+/**
+ * Multi-path consistency check (A-MemGuard): before a risky decision, ask whether
+ * the memory set agrees about a claim. Returns supporting vs contradicting entries
+ * and a verdict. `conflicting` is the signal to abstain / seek confirmation.
+ */
+export function memoryConsensus(entries, claim) {
+    const claimLc = claim.toLowerCase();
+    const core = claimLc.replace(/^(the |a |an )/, "").trim();
+    const supporting = [];
+    const contradicting = [];
+    for (const e of entries) {
+        const c = e.content.toLowerCase();
+        const negated = c.includes("not " + core) || c.includes("no " + core) || c.includes("isn't " + core);
+        if (negated)
+            contradicting.push(e.hash);
+        else if (core.length >= 4 && c.includes(core))
+            supporting.push(e.hash);
+    }
+    const verdict = supporting.length > 0 && contradicting.length > 0
+        ? "conflicting"
+        : supporting.length + contradicting.length === 0
+            ? "insufficient"
+            : "consistent";
+    return { verdict, supporting, contradicting };
+}
+function negates(a, b) {
+    // crude: b is "not <a>" / "no <a>" form of a
+    const core = a.replace(/^(the |a |an )/, "").trim();
+    if (core.length < 6)
+        return false;
+    return b.includes("not " + core) || b.includes("no " + core) || b.includes("isn't " + core);
+}

package/dist/recompile-marker.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Recompile-pending marker — the "stale" signal that closes the self-evolution loop.
+ *
+ * When a governed self-edit is APPLIED (overlay changes), the compiled PERSONA.md no longer
+ * reflects the spec. Core cannot compile (that needs an LLM, which lives in the CLI/host), so
+ * it drops a small sentinel next to personaxis.md. A consumer that CAN compile — the REPL
+ * (with a provider) or the host driving MCP — recompiles and clears it. `personaxis compile`
+ * clears it automatically; `compile --if-pending` is a cheap no-op when nothing is stale.
+ */
+export interface RecompileState {
+    pending: boolean;
+    reason?: string;
+    ts?: string;
+}
+/** Mark the persona's compiled doc as stale (idempotent). */
+export declare function markRecompilePending(personaPath: string, reason: string): void;
+export declare function readRecompilePending(personaPath: string): RecompileState;
+/** Clear the marker (called after a successful compile). */
+export declare function clearRecompilePending(personaPath: string): void;

package/dist/recompile-marker.js

@@ -0,0 +1,36 @@
+/**
+ * Recompile-pending marker — the "stale" signal that closes the self-evolution loop.
+ *
+ * When a governed self-edit is APPLIED (overlay changes), the compiled PERSONA.md no longer
+ * reflects the spec. Core cannot compile (that needs an LLM, which lives in the CLI/host), so
+ * it drops a small sentinel next to personaxis.md. A consumer that CAN compile — the REPL
+ * (with a provider) or the host driving MCP — recompiles and clears it. `personaxis compile`
+ * clears it automatically; `compile --if-pending` is a cheap no-op when nothing is stale.
+ */
+import { writeFileSync, readFileSync, existsSync, rmSync } from "node:fs";
+import { join, dirname } from "node:path";
+function markerPath(personaPath) {
+    return join(dirname(personaPath), ".recompile-pending.json");
+}
+/** Mark the persona's compiled doc as stale (idempotent). */
+export function markRecompilePending(personaPath, reason) {
+    writeFileSync(markerPath(personaPath), JSON.stringify({ pending: true, reason, ts: new Date().toISOString() }, null, 2) + "\n", "utf-8");
+}
+export function readRecompilePending(personaPath) {
+    const p = markerPath(personaPath);
+    if (!existsSync(p))
+        return { pending: false };
+    try {
+        const j = JSON.parse(readFileSync(p, "utf-8"));
+        return { pending: true, reason: j.reason, ts: j.ts };
+    }
+    catch {
+        return { pending: true };
+    }
+}
+/** Clear the marker (called after a successful compile). */
+export function clearRecompilePending(personaPath) {
+    const p = markerPath(personaPath);
+    if (existsSync(p))
+        rmSync(p);
+}

package/dist/registry.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Overseer registry + global/overlay persona model (F7 — plan/08-persona-model).
+ *
+ * The "master" personaxis-system is a governed *runtime* that is aware of every
+ * persona and project in the environment. It is NOT a feeling persona — it
+ * orchestrates and audits. This module is its memory:
+ *
+ *   ~/.personaxis/ (override with PERSONAXIS_HOME)
+ *     registry.json          personas, projects, collections, machines
+ *     personas/<slug>/        global identity + memory (reused across projects)
+ *
+ * Reuse model: a persona lives globally; each project "mounts" it with a local
+ * overlay (its own state.json + project memory). So the same persona can be
+ * reused WITH accumulated memory, or instantiated fresh per project. Collections
+ * (teams) group personas + projects. State is tracked per machine so the same
+ * user-clone can live on Windows/Linux/macOS and reconcile via git without one
+ * machine clobbering another.
+ */
+export interface PersonaRecord {
+    slug: string;
+    globalPath: string;
+    createdTs: string;
+}
+export interface ProjectRecord {
+    root: string;
+    slugs: string[];
+    lastSeen: string;
+    machine: string;
+}
+/**
+ * A Collection is pure ORGANIZATION — a named group of personas/projects, like a
+ * folder or tag. No runtime behavior. (Distinct from a Team, below.)
+ */
+export interface Collection {
+    name: string;
+    personas: string[];
+    projects: string[];
+}
+/**
+ * A Team is an OPERATIONAL multi-agent unit: personas with ROLES, a shared GOAL,
+ * that collaborate (e.g. via the blackboard, scoped to the team's members). A team
+ * has a lead and members; it is runtime, not just taxonomy.
+ */
+export interface TeamMember {
+    slug: string;
+    role: string;
+}
+export interface Team {
+    name: string;
+    lead?: string;
+    members: TeamMember[];
+    goal?: string;
+    createdTs: string;
+}
+export interface Registry {
+    version: 1;
+    personas: Record<string, PersonaRecord>;
+    projects: Record<string, ProjectRecord>;
+    collections: Record<string, Collection>;
+    teams: Record<string, Team>;
+    machines: Record<string, {
+        lastSeen: string;
+        os: string;
+    }>;
+}
+export declare function personaxisHome(): string;
+/** A stable per-machine id so cross-OS instances reconcile without clobbering. */
+export declare function machineId(): string;
+export declare function loadRegistry(): Registry;
+export declare function saveRegistry(reg: Registry): void;
+export declare function globalPersonaDir(slug: string): string;
+export declare function registerPersona(slug: string): PersonaRecord;
+export declare function registerProject(root: string, slugs: string[]): ProjectRecord;
+export declare function createCollection(name: string): Collection;
+export declare function addToCollection(name: string, kind: "persona" | "project", value: string): Collection;
+export declare function createTeam(name: string, lead?: string): Team;
+export declare function addTeamMember(name: string, slug: string, role: string): Team;
+export declare function setTeamGoal(name: string, goal: string): Team;
+export declare function getTeam(name: string): Team | undefined;
+/**
+ * Resolve the effective persona path for a project + slug: a project-local
+ * overlay (project `.personaxis/personas/<slug>/personaxis.md` or root
+ * `.personaxis/personaxis.md`) takes precedence over the global persona.
+ * Returns the first existing path, or the global path as the default target.
+ */
+export declare function resolveEffectivePersona(projectRoot: string, slug?: string): {
+    path: string;
+    scope: "project-overlay" | "global" | "none";
+};
+/** The overseer's situational summary of the whole environment. */
+export declare function overseerView(): {
+    machine: string;
+    personas: number;
+    projects: number;
+    collections: number;
+    teams: number;
+    machines: number;
+    detail: Registry;
+};