federation

name	federation
description	Set up or repair learning-loop federation: identity creation, token redemption, Tailscale, visibility rules, and the first sync test. Run when /init asked you to defer federation, when sync is broken, or when rotating identity. Safe to re-run.

Federation Setup

Federation lets you share vault notes with other learning-loop users via interchange.live. The setup is non-trivial because it spans cryptography (Ed25519 keypair), single-use redemption tokens, an overlay network (Tailscale via headscale), and a hub round-trip that must succeed before any config is written.

This skill is invoked from /init Phase 4 when the user opts in, but is safe to run standalone any time you have a token from robin.

Paths

Resolve PLUGIN_DATA, VAULT, and the plugin root per ${CLAUDE_PLUGIN_ROOT}/skills-shared/paths-preamble.md (read it and apply).

Process

Detect, then walk the steps in order. Do not write the federation config until the sync test in step F succeeds: failed runs leave nothing on disk so re-running starts fresh.

A: Detect

If PLUGIN_DATA/federation/config.json already exists, report identity and peer count, and ask: "Federation is already configured. Re-run setup anyway?" Default no. If the user says no, exit cleanly.

B: Token

Ask: "Do you have an invite token?"

If no:

You'll need an invitation to join the federation. Apply at:
  https://interchange.live/apply

Once your application is approved, you'll receive a redeem URL.
Re-run /learning-loop:federation when you have it.

Exit cleanly.

If yes: proceed to identity setup.

C: Identity

The identity is an Ed25519 seed managed by the ll-search binary's seed store. Backends in priority order: the OS keyring (macOS Keychain / Linux Secret Service / Windows Credential Manager), then an encrypted-at-rest file under PLUGIN_DATA/federation/ (machine-derived key, used where no keyring daemon runs). A plaintext PLUGIN_DATA/federation/.seed file is a pre-v1.18 legacy format: still readable as a migration source, never created by the binary. On a fresh install no .seed file will exist — that is normal, not an error.

Plugin-root migration check (before running identity): if a legacy plaintext seed exists at ${CLAUDE_PLUGIN_ROOT}/federation/.seed (very old installs; that location gets wiped on reinstall):

1. Copy it to PLUGIN_DATA/federation/.seed (mode 0o600) — the binary's plaintext-legacy reader looks there
2. Delete the old one from the marketplace directory
3. Verify the pubkey matches config.identity.pubkey if a previous federation config exists. If it does not match, warn and offer to update the hub.

Run ll-search identity --config-dir $PLUGIN_DATA to load or create the Ed25519 keypair. Output is JSON:

{ "pubkey_b64": "0JuQ...r5o=", "backend": "keyring", "created": false }

• pubkey_b64 is the raw 32-byte public key as base64, ready to send to /api/redeem as-is. It becomes pubkey in config.json (written in step G).
• backend is "keyring", "encrypted", or "plaintext-legacy" — where the seed was loaded from (or stored, on first run). There is no seed_path field.
• created is true only when no seed existed in any backend and a fresh one was generated (into the keyring, or the encrypted file as fallback — never plaintext). The command is idempotent: existing seeds are reused, so re-runs return the same pubkey.

If backend is "plaintext-legacy": offer to upgrade the seed into a secure backend:

ll-search migrate-seed --config-dir $PLUGIN_DATA

The migration is fail-closed: the plaintext file is deleted only after the new backend has been written and verified, and re-running against an already-migrated seed is a no-op. Never migrate between backends by hand-copying files — the only manual file copy in this skill is the plugin-root relocation above, which exists solely to put the legacy file where migrate-seed and the legacy reader can find it.

D: Redeem

Ask for the token. POST to https://interchange.live/api/redeem with a 30-second timeout so a hung connection cannot stall the whole flow:

const res = await fetch('https://interchange.live/api/redeem', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ token, peer_id, pubkey: pubkey_b64 }),
  signal: AbortSignal.timeout(30_000),
});

The peer_id is bound to the token server-side: the user does not choose it. The redeem response returns the peer_id along with the headscale auth key and hub endpoint. Store these in memory for the rest of the flow. Do NOT write config yet: wait for the sync test to succeed.

Handle server errors:

• 404: "invalid token, check the URL you were sent"
• 409: "this token was already redeemed. If a previous setup redeemed but failed at sync, contact robin for a fresh token; the burned one cannot be replayed."
• 410: "this token has expired, contact robin for a new one"
• 502: "provisioning service is unreachable, try again later"

On AbortError (timeout) or any network error: surface "interchange.live unreachable, retry later" and exit without writing config. The token has not been spent on a connection failure: the same token will work on the next run.

On HTTP failure: exit without writing config.

E: Network Connection

Check for Tailscale. If not installed, guide installation (brew for macOS, curl for Linux). Run:

tailscale up --auth-key <headscale_auth_key> --login-server https://hs.interchange.live

Verify with tailscale status. If it fails, the auth key may have expired (24-hour window): surface the error and exit without writing config. The redeem token has already been consumed, so retrying needs a fresh token from robin (the same 409 rule as step D applies).

E.5: Visibility Rules

Present defaults:

• 3-permanent/ -> public (full content shared)
• 1-fleeting/ -> listed (title + tags + summary)
• Everything else -> private

Ask: "Does that work for you?" Allow pattern customization if not.

E.7: Knowledge Graph Opt-in

Ask: "Would you like your public note titles to appear on the interchange.live knowledge graph? (This only shares titles of notes marked public or listed, no content.)"

If yes, set "graph": true in the generated config. If no, set "graph": false.

E.8: Provenance Consent

Ask: "Share anonymized pipeline stats? (Tier 1: action counts only)"

F: First Sync Test

The federation config is not yet on disk. Run the sync test against the in-memory identity and the hub endpoint from the redeem response, with a 15-second timeout so a stalled connection cannot hang setup:

const { spawn } = await import('node:child_process');
const child = spawn(LL_SEARCH, ['sync', dbPath, vaultPath, '--hub-endpoint', hubEndpoint, '--peer-id', peerId], {
  env: { ...process.env },
});
const timer = setTimeout(() => child.kill('SIGKILL'), 15_000);
// await close, clearTimeout(timer) on exit

(Or invoke the binary via the existing helper and pass the same 15s deadline.)

On success: report counts (notes exported, peers downloaded). Proceed to G.

On failure or timeout: do not write config. Surface the specific error and offer the user a choice:

1. Retry sync now: re-run F against the same in-memory identity (no token re-burn, no re-redeem). Useful for transient network blips.
2. Exit setup: leave federation unconfigured. The redeem token has been spent. To complete federation later the user must contact robin for a fresh token; a re-run of this skill will see no PLUGIN_DATA/federation/config.json and start from scratch, but the burned token will return 409 on redeem.

Be explicit about the trade: "The token is single-use and was consumed. If sync keeps failing, you can either retry now or get a new token from robin: there is no way to replay this one."

G: Write Config

Only reached if F succeeded. Write PLUGIN_DATA/federation/config.json with identity (using the peer_id returned from D), visibility, graph, share_provenance fields, and hub endpoint from the redeem response.

Immediately after the config write, stamp the seed with version metadata so SessionStart can surface a one-shot notice on a future plugin major upgrade. Read the current plugin version from ${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json and write PLUGIN_DATA/federation/.seed-meta.json:

const PLUGIN = process.env.CLAUDE_PLUGIN_ROOT;
const PLUGIN_DATA = process.env.CLAUDE_PLUGIN_DATA;
const pluginVersion = JSON.parse(
  readFileSync(join(PLUGIN, '.claude-plugin', 'plugin.json'), 'utf-8'),
).version;
const metaPath = join(PLUGIN_DATA, 'federation', '.seed-meta.json');
// Merge: the binary writes a `backend` field into this sidecar; preserve it.
const existing = existsSync(metaPath)
  ? JSON.parse(readFileSync(metaPath, 'utf-8'))
  : {};
const meta = {
  ...existing,
  created_at: new Date().toISOString(),
  plugin_version: pluginVersion,
  plugin_major: parseInt(pluginVersion.split('.')[0], 10),
};
writeFileSync(metaPath, JSON.stringify(meta, null, 2));

// Successful (re-)setup clears any prior version-mismatch notice
const noticePath = join(PLUGIN_DATA, 'federation', '.seed-notice-shown');
if (existsSync(noticePath)) unlinkSync(noticePath);

Why: the SessionStart hook compares meta.plugin_major against the running plugin's major version and emits a single stderr line when they differ, suggesting /learning-loop:federation to rotate. Resetting .seed-notice-shown on every successful re-setup guarantees a future major bump (e.g. v2.x -> v3.x after the user already cleared a v1.x -> v2.x notice) re-fires correctly. The notice is informational only: nothing auto-rotates.

Key behavioural detail: the federation config file is the canonical "federation is set up" marker, and it is only written once a sync round-trip has actually worked. Failed setup runs leave no config behind, so re-running this skill from a fresh shell always re-enters cleanly. The seed in the seed store (keyring / encrypted file / legacy plaintext) is reused across re-runs (it is the user's identity, not federation state), so a re-run produces the same pubkey: the user will need a fresh token if the previous one was already redeemed.

Summary

After F succeeds and G writes config, report:

Federation configured.

  Identity:   [pubkey_b64 first 12 chars]
  Hub:        [endpoint]
  Peers:      [N] downloaded
  Visibility: [public/listed/private folder counts]
  Graph:      [yes/no]

Rules

• Never write the federation config until the sync test passes. Failed runs must leave no state on disk.
• Tokens are single-use and consumed on redeem (step D). Network failures BEFORE redeem are recoverable; failures AFTER redeem require a fresh token.
• The seed is the user's identity. Never delete it from its store — keyring entry, encrypted file, or legacy PLUGIN_DATA/federation/.seed — without explicit user request.
• Tailscale auth keys expire in 24 hours. If step E fails for that reason, the token is already spent.