renor 0.0.0-stage → 0.2.0

package/lib/setup.mjs

@@ -0,0 +1,256 @@
+/**
+ * `renor setup`: find the AI apps on this machine, add Renor to each without touching anything else in their config,
+ * sign in where the app can do it from the terminal, install the skill, then say plainly what is left, app by app.
+ */
+import { CLIENTS } from './clients.mjs'
+import { FIRST_MEMORY_RECALL, FIRST_MEMORY_SAVE, GATEWAY_URL, SKILL_INSTALL_ARGS } from './constants.mjs'
+import { checkCode, cleanupClient, probeGateway, verifyClient } from './verify.mjs'
+import { askAboutSharing, outcomeLine } from './sharing.mjs'
+import { confirm, interactive, which } from './system.mjs'
+
+/**
+ * @param {object} options
+ * @param {boolean} options.yes       add without asking first
+ * @param {boolean} options.dryRun    say what would happen, change nothing
+ * @param {boolean} options.login     run the sign-ins the apps offer from the terminal
+ * @param {boolean} options.skill     install the Renor skill
+ * @param {boolean} options.verify    also have Claude Code save and recall one test memory (the gateway is always probed)
+ * @param {boolean} options.force     replace a renor entry that points somewhere else
+ * @param {string[]|null} options.only  limit to these app ids
+ */
+export async function setup(options, io = defaultIo()) {
+  const { env, out, isTTY } = io
+  const paint = painter(out, env)
+  const say = (line = '') => out.write(line + '\n')
+  const canSignIn = options.login && isTTY
+
+  say(paint.bold('Renor setup'))
+  say(`Adds Renor (${GATEWAY_URL}) to the AI apps on this computer. Each app keeps everything else in its config.`)
+  say()
+
+  const pool = options.only ? CLIENTS.filter((client) => options.only.includes(client.id)) : CLIENTS
+  const found = []
+  const missing = []
+  for (const client of pool) {
+    const detection = client.detect({ env })
+    if (detection.found) found.push({ client, detection })
+    else missing.push(client)
+  }
+
+  if (found.length === 0) {
+    say('No supported app was found: Claude Code, Codex, Cursor, OpenCode, Gemini CLI, Pi or VS Code.')
+    say('For ChatGPT or Claude in the browser, open https://app.renor.cloud and follow the steps there.')
+    return { code: 0, results: [] }
+  }
+
+  say(`Found: ${found.map(({ client, detection }) => client.label + (detection.version ? ` ${detection.version}` : '')).join(', ')}.`)
+  if (missing.length > 0) say(paint.dim(`Not found: ${missing.map((client) => client.label).join(', ')}.`))
+  say()
+
+  if (options.dryRun) {
+    for (const { client, detection } of found) {
+      const now = client.current({ env })
+      say(`  ${client.label}: ${planFor(client, detection, now, options)}`)
+    }
+    say()
+    say('Dry run: nothing was changed.')
+    return { code: 0, results: [] }
+  }
+
+  if (!options.yes && isTTY) {
+    const signIns = canSignIn ? ' Your browser opens once for each app that signs in from here; approve Renor there.' : ''
+    const yes = await confirm(`Add Renor to ${found.length === 1 ? found[0].client.label : `these ${found.length} apps`}?${signIns} [Y/n] `, io)
+    if (!yes) {
+      say('Nothing was changed.')
+      return { code: 0, results: [] }
+    }
+    say()
+  }
+
+  const results = []
+  for (const { client, detection } of found) {
+    try {
+      results.push(await setUpOne(client, detection, { ...options, canSignIn }, { env, say }))
+    } catch (error) {
+      // One app's config that cannot be written (a permission, a file where a folder should be) is that app's failure,
+      // not the end of the run: the other apps are still set up and the report still says what is left.
+      const detail = error instanceof Error ? error.message : String(error)
+      results.push({ id: client.id, label: client.label, state: 'failed', next: `${detail} Add Renor by hand: ${client.byHand}` })
+    }
+  }
+
+  let skill = null
+  if (options.skill) {
+    if (!which('npx', env)) {
+      skill = { ok: false, detail: 'npx was not found.' }
+    } else {
+      say(paint.dim('Installing the Renor skill, which tells your AI when to save and when to recall…'))
+      const status = interactive('npx', SKILL_INSTALL_ARGS, { env })
+      skill = status === 0 ? { ok: true } : { ok: false, detail: `The skill install exited with ${status}.` }
+    }
+  }
+
+  await verifyAll(found, results, { env, say, paint, io, options })
+
+  report(results, skill, { say, paint })
+  const sharing = await askAboutSharing(io, options)
+  const sharingLine = outcomeLine(sharing, env)
+  if (sharingLine) say(sharingLine)
+  const failures = results.filter((result) => result.state === 'failed' || result.verified === false).length + (skill && !skill.ok ? 1 : 0)
+  return { code: failures > 0 ? 1 : 0, results, skill }
+}
+
+/** The proof: the gateway answers; with --verify, Claude Code (the app that can be limited to Renor's tools) saves and recalls one test memory. */
+async function verifyAll(found, results, { env, say, paint, io, options }) {
+  say()
+  const gateway = await probeGateway(io.fetch)
+  if (gateway.ok) say(`${paint.ok('✓')} Renor’s gateway answers.`)
+  else {
+    say(`${paint.warn('!')} ${gateway.detail}`)
+    say(`  Fix: ${gateway.fix}`)
+  }
+  if (!options.verify) return gateway.ok
+
+  const hasCheck = (result) => Boolean(found.find(({ client }) => client.id === result.id).client.check)
+  for (const result of results) {
+    if ((result.state === 'already' || result.state === 'added') && !hasCheck(result)) result.unchecked = true
+  }
+  const checkable = results.filter((result) => (result.state === 'already' || (result.state === 'added' && result.signedIn)) && hasCheck(result))
+  if (checkable.length === 0) {
+    say(paint.dim('Nothing to check from here yet: Claude Code is the app setup can test, and it is not signed in to Renor. Sign in as listed below, then run npx renor setup --verify.'))
+    return gateway.ok
+  }
+  if (!gateway.ok) {
+    for (const result of checkable) result.verified = false
+    return false
+  }
+  say(paint.dim('Checking Claude Code: it saves one test memory to Renor and recalls it. This can take a minute and uses a little of its model quota.'))
+  for (const result of checkable) {
+    const { client } = found.find((item) => item.client.id === result.id)
+    const code = checkCode()
+    result.checkCode = code
+    const check = verifyClient(client, { env, code, run: io.run })
+    result.verified = check.ok
+    let retiredId = check.retiredId
+    result.noteRetired = check.retired
+    if (!check.retired) {
+      const cleanup = cleanupClient(client, { env, code, savedId: check.savedId, run: io.run })
+      result.noteRetired = cleanup.retired
+      retiredId = cleanup.retiredId ?? retiredId
+    }
+    if (check.wrongRetire) {
+      check.ok = false
+      check.detail = `${client.label} retired a different memory (id ${check.wrongRetire.retired}) than the one it saved (id ${check.wrongRetire.saved}).`
+      check.fix = `put it back with restore_memory and the id ${check.wrongRetire.retired} (ask any connected AI, or use the dashboard's memory list). Setup then retired the test note itself.`
+    } else if (result.noteRetired && check.recalledOk) {
+      // The recall worked and the cleanup pass confirmed the retire the app had not.
+      check.ok = true
+    } else if (!result.noteRetired) {
+      check.ok = false
+      check.detail = `${check.detail ?? 'The check finished'}; setup could not retire the test note Renor setup check ${code}.`
+      check.fix = `Run npx renor setup --verify again; if it persists, write to hello@renor.cloud with the code ${code}.`
+    }
+    result.noteId = retiredId
+    result.verified = check.ok
+    if (!check.ok) {
+      result.verifyDetail = check.detail
+      result.verifyFix = check.fix
+    }
+  }
+  if (checkable.every((result) => result.noteRetired)) say(`${paint.ok('✓')} The test note${checkable.length === 1 && checkable[0].noteId ? ` (id ${checkable[0].noteId})` : ''} was retired again: it no longer comes back in search.`)
+  return gateway.ok
+}
+
+function planFor(client, detection, now, options) {
+  if (detection.blocked) return detection.blocked
+  if (now.configured && now.url === GATEWAY_URL && !options.force) return 'already has Renor; nothing to do.'
+  if (now.configured && !options.force) return `has a renor server at ${now.url ?? 'another address'}; it would be left alone (use --force to replace it).`
+  if (now.configured) return 'its renor server would be replaced with Renor’s address.'
+  return client.login ? 'Renor would be added, then signed in.' : 'Renor would be added.'
+}
+
+async function setUpOne(client, detection, options, { env, say }) {
+  const base = { id: client.id, label: client.label }
+  if (detection.blocked) return { ...base, state: 'blocked', next: detection.blocked }
+
+  const now = client.current({ env })
+  if (!now.readable) {
+    return { ...base, state: 'failed', next: `Its config file could not be read. Add Renor by hand: ${client.byHand}` }
+  }
+  if (now.configured && now.url === GATEWAY_URL && !options.force) {
+    return { ...base, state: 'already', next: null }
+  }
+  if (now.configured && !options.force) {
+    return {
+      ...base,
+      state: 'different',
+      next: `It already has a renor server at ${now.url ?? 'another address'}, left as it is. Run renor setup --force to replace it.`,
+    }
+  }
+
+  const ctx = { env, canSignIn: options.canSignIn, say }
+  const outcome = client.add(ctx, { replace: now.configured })
+  if (!outcome.ok) {
+    return { ...base, state: 'failed', next: `${outcome.detail ? outcome.detail + ' ' : ''}Add Renor by hand: ${client.byHand}` }
+  }
+
+  let signedIn = outcome.signedIn
+  const login = !signedIn && options.canSignIn && client.login ? (typeof client.login === 'function' ? client.login(ctx) : client.login) : null
+  if (login) {
+    say(`Signing in to Renor for ${client.label}. Your browser opens: sign in and approve.`)
+    signedIn = interactive(login[0], login[1], { env }) === 0
+  }
+  return {
+    ...base,
+    state: 'added',
+    signedIn,
+    detail: outcome.detail,
+    next: signedIn ? null : client.signIn,
+  }
+}
+
+function report(results, skill, { say, paint }) {
+  say()
+  say(paint.bold('Done.'))
+  const wired = results.filter((result) => result.state === 'already' || result.state === 'added').length
+  const verified = results.filter((result) => result.verified === true).length
+  say(`${wired} of ${results.length} wired${results.some((result) => result.verified !== undefined) ? `, ${verified} verified` : ''}.`)
+  const width = Math.max(...results.map((result) => result.label.length))
+  for (const result of results) {
+    const name = result.label.padEnd(width)
+    if (result.state === 'already') say(`  ${paint.ok('✓')} ${name}  already had Renor`)
+    else if (result.state === 'added' && result.signedIn) say(`  ${paint.ok('✓')} ${name}  added and signed in`)
+    else if (result.state === 'added') say(`  ${paint.todo('•')} ${name}  added. Left for you: ${result.next}`)
+    else say(`  ${paint.warn('!')} ${name}  ${result.next}`)
+    if (result.detail) say(`    ${paint.dim(result.detail)}`)
+    if (result.verified === true) say(`    ${paint.ok('✓')} verified: saved a test memory and recalled it`)
+    if (result.unchecked) say(`    ${paint.dim(`not checked by setup: tell it "${FIRST_MEMORY_SAVE}", then ask "${FIRST_MEMORY_RECALL}" in a new chat.`)}`)
+    if (result.verified === false) {
+      say(`    ${paint.warn('!')} not verified: ${result.verifyDetail ?? 'Renor’s gateway could not be reached.'}`)
+      if (result.verifyFix) say(`      Fix: ${result.verifyFix}`)
+    }
+  }
+  if (skill) {
+    say(skill.ok ? `  ${paint.ok('✓')} ${'Skill'.padEnd(width)}  installed` : `  ${paint.warn('!')} ${'Skill'.padEnd(width)}  not installed: ${skill.detail}`)
+  }
+  say()
+  say(`Try it: tell one of them "${FIRST_MEMORY_SAVE}"`)
+  say(`Then, in a new chat or another app, ask "${FIRST_MEMORY_RECALL}"`)
+  say(paint.dim('ChatGPT and Claude in the browser: open https://app.renor.cloud for their steps.'))
+}
+
+function painter(out, env) {
+  const on = Boolean(out.isTTY) && !env.NO_COLOR
+  const wrap = (open, close) => (text) => (on ? `\u001b[${open}m${text}\u001b[${close}m` : text)
+  return { bold: wrap(1, 22), dim: wrap(2, 22), ok: wrap(32, 39), todo: wrap(36, 39), warn: wrap(33, 39) }
+}
+
+function defaultIo() {
+  return {
+    env: process.env,
+    out: process.stdout,
+    input: process.stdin,
+    output: process.stdout,
+    isTTY: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+  }
+}

package/lib/sharing-gate.mjs

@@ -0,0 +1,42 @@
+/**
+ * Whether `renor setup` may ask the sharing question (#778): only while the operator's gate is open. The switch lives on the
+ * server (app_settings 'learning_sharing', supabase/migrations/20261024120000_learning_sharing_gate.sql) and the gateway reports
+ * it, as one public bit, at GET /sharing/status ({"open": true|false}). Anything but an answer of exactly {"open": true} (no
+ * network, a timeout, an older gateway without the route, a malformed body) means closed: the question is not asked.
+ *
+ * Opening the switch only lets setup ASK. Whether a row is ever stored is decided again by the server from the authenticated
+ * identity and that user's recorded consent; client-supplied workspace ids never decide it.
+ */
+import { GATEWAY_URL } from './constants.mjs'
+
+export const SHARING_STATUS_URL = new URL('/sharing/status', GATEWAY_URL).href
+
+/** True only when the gateway answers {"open": true} within `timeoutMs`. */
+export async function sharingPromptOpen({ fetchImpl = globalThis.fetch, url = SHARING_STATUS_URL, timeoutMs = 3000 } = {}) {
+  if (typeof fetchImpl !== 'function') return false
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    const response = await fetchImpl(url, {
+      headers: { accept: 'application/json' },
+      redirect: 'error',
+      signal: controller.signal,
+    })
+    if (!response.ok) return false
+    const body = await response.json()
+    return body !== null && typeof body === 'object' && body.open === true
+  } catch {
+    return false
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * Runs `ask` (the question #778 asks) only while the gate is open; otherwise returns 'closed' without asking or writing anything.
+ * #778's askAboutSharing calls it as its first step after its own not-interactive / environment / answered checks.
+ */
+export async function whenSharingOpen(ask, options = {}) {
+  if (!(await sharingPromptOpen(options))) return 'closed'
+  return ask()
+}

package/lib/sharing.mjs

@@ -0,0 +1,114 @@
+/**
+ * The one question `renor setup` asks, once: do you want to share anonymous usage signals with Renor? The answer is No unless the
+ * person says yes, and nothing is sent by this command either way: it only writes the choice, in this install's sharing folder,
+ * which the open-source engine (engine/src/sharing/state.ts) reads as a limit on every workspace folder on this install: the
+ * stricter of the install's answer and a workspace's own record is in force, and an engine finding the install at No turns any
+ * workspace record that is still on to off (engine/src/sharing/loop.ts). A No therefore stops every engine on this install that
+ * reads this folder; a yes never turns a workspace on by itself.
+ *
+ * The question is asked only while the operator's gate is open (cli/lib/sharing-gate.mjs, #961): closed, it asks and writes nothing.
+ *
+ * A hosted workspace has its own switch (the dashboard's Settings), which an owner signed in there controls; this file does not
+ * touch it. The record has the level, the time, the id of the words the person saw and their confirmation of being an adult, as the
+ * engine writes them (a test in tests/ holds the two in step).
+ */
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { createInterface } from 'node:readline'
+import { whenSharingOpen } from './sharing-gate.mjs'
+
+/** The id of the words below. Change the words, change the id. */
+export const SETUP_WORDING_VERSION = 'setup-2026-10-21'
+
+export const SHARING_QUESTION = `One question, asked once: help Renor learn from how its memory is used?
+  Share anonymous usage signals: numbers only (which memory was returned, its position and score, and whether your AI then opened or
+  cited it, times to the hour). Never memory text, queries, names or paths. Off is the default; you can change it any time with
+  \`renor-engine telemetry\`, and every field is listed in the engine's docs/TELEMETRY.md. Saying yes also confirms you are 18 or older.
+  This command sends nothing itself.
+Share anonymous usage signals? [y/N] `
+
+export function sharingDir(env = process.env) {
+  const set = (env.RENOR_SHARING_DIR || '').trim()
+  if (set !== '') return resolve(set)
+  const xdg = (env.XDG_CONFIG_HOME || '').trim()
+  return join(xdg !== '' ? resolve(xdg) : join(homedir(), '.config'), 'renor')
+}
+
+/** True when a person (or this command) already recorded an answer: the question is never asked twice. */
+export function hasAnswer(env = process.env) {
+  try {
+    const record = JSON.parse(readFileSync(join(sharingDir(env), 'sharing.json'), 'utf8'))
+    return record && record.version === 1 && ['off', 'signals', 'data'].includes(record.level)
+  } catch {
+    return false
+  }
+}
+
+/** An environment that says no already answered: DO_NOT_TRACK=1 or RENOR_SHARING=off. */
+export function environmentSaysNo(env = process.env) {
+  return (env.DO_NOT_TRACK || '').trim() === '1' || (env.RENOR_SHARING || '').trim().toLowerCase() === 'off'
+}
+
+export function recordAnswer(env, level, now = new Date()) {
+  const dir = sharingDir(env)
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  // mkdirSync's mode applies only to a folder it creates: one that already exists (made by hand, or by an older tool) is
+  // tightened here, so the folder holding the consent record is the owner's alone on every write.
+  chmodSync(dir, 0o700)
+  const record = {
+    version: 1,
+    level,
+    changedAt: now.toISOString(),
+    wording: SETUP_WORDING_VERSION,
+    adult: level !== 'off',
+    source: 'setup',
+  }
+  const temp = join(dir, `.sharing.json.${process.pid}.tmp`)
+  writeFileSync(temp, JSON.stringify(record, null, 2) + '\n', { mode: 0o600 })
+  renameSync(temp, join(dir, 'sharing.json'))
+  return record
+}
+
+function ask(question, { input = process.stdin, output = process.stdout } = {}) {
+  return new Promise((resolveAnswer) => {
+    const rl = createInterface({ input, output })
+    rl.question(question, (answer) => {
+      rl.close()
+      resolveAnswer(/^\s*y(es)?\s*$/i.test(answer))
+    })
+  })
+}
+
+/**
+ * What setup may say once the answer is recorded: only what this command controls, which is one folder for one account. It
+ * cannot see a hosted workspace's choice (Settings > Learning) or an engine run under another account or with its own
+ * RENOR_SHARING_DIR, so it never claims that nothing is sent, and a yes never claims that sharing is on.
+ */
+export function outcomeLine(result, env = process.env) {
+  const where = `Recorded for this computer's account, in ${join(sharingDir(env), 'sharing.json')}`
+  const elsewhere = 'A hosted workspace keeps its own switch in Settings on https://app.renor.cloud, and an engine run under another account reads its own folder.'
+  if (result === 'asked-no') {
+    return `${where}: not sharing. An engine that reads this folder stops sharing at its next check. ${elsewhere}`
+  }
+  if (result === 'asked-yes') {
+    return `${where}: sharing allowed up to anonymous usage signals. This turns nothing on by itself: an engine shares only for a workspace whose own choice is on (renor-engine telemetry). Undo it with renor-engine telemetry off. ${elsewhere}`
+  }
+  return null
+}
+
+/**
+ * Asks, in front of a person only, and records the answer. Returns what happened: 'asked-yes', 'asked-no', or the reason it did not
+ * ask ('not-interactive', 'answered', 'environment', or 'closed' while the operator's gate is closed).
+ */
+export async function askAboutSharing(io, { yes, dryRun }) {
+  const env = io.env
+  if (yes || dryRun || !io.isTTY) return 'not-interactive'
+  if (environmentSaysNo(env)) return 'environment'
+  if (hasAnswer(env)) return 'answered'
+  return whenSharingOpen(async () => {
+    const wants = await ask(SHARING_QUESTION, io)
+    recordAnswer(env, wants ? 'signals' : 'off')
+    return wants ? 'asked-yes' : 'asked-no'
+  }, { fetchImpl: io.fetch })
+}

package/lib/sync.mjs

@@ -0,0 +1,249 @@
+/**
+ * `renor sync`: keep the memory files you choose (CLAUDE.md, AGENTS.md, an agent's memory folder) in your Renor
+ * workspace, so Renor and the notes your agents already trust are one memory.
+ *
+ *   renor sync add <file-or-folder>…   choose what to sync (nothing is read or sent until you do)
+ *   renor sync remove <path>…          stop syncing it (what Renor already holds stays; forget it in the dashboard)
+ *   renor sync [--dry-run]             send what changed since the last run
+ *
+ * Each file is one import batch under Imported/synced/<path>, first line marking the source path. A changed file
+ * undoes its previous batch and imports the new text, so a note is never held twice. Only chosen paths are read,
+ * only .md files, and the token comes from RENOR_TOKEN (a connect token from the dashboard); nothing is stored.
+ */
+import { createHash } from 'node:crypto'
+import { lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve, relative, sep } from 'node:path'
+import { GATEWAY_URL } from './constants.mjs'
+import { openSession } from './mcp.mjs'
+import { home } from './system.mjs'
+
+const LABEL = 'synced'
+const FILE_BYTES = 64 * 1024
+const EMPTY = { chosen: [], synced: {} }
+
+export const statePath = (env) => join(home(env), '.renor', 'sync.json')
+
+export function loadState(env) {
+  try {
+    const parsed = JSON.parse(readFileSync(statePath(env), 'utf8'))
+    return { chosen: parsed.chosen ?? [], synced: parsed.synced ?? {} }
+  } catch {
+    return { ...EMPTY, chosen: [], synced: {} }
+  }
+}
+
+function saveState(env, state) {
+  const path = statePath(env)
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path + '.tmp', JSON.stringify(state, null, 2))
+  renameSync(path + '.tmp', path)
+}
+
+/**
+ * Every .md file under the chosen paths. A path you chose may itself be a link (dotfiles); inside a chosen folder
+ * links are skipped, so a folder cannot lead the walk to files you did not choose. Dot-names and node_modules are skipped.
+ */
+export function expand(chosen) {
+  const files = []
+  const walk = (path, top) => {
+    let info
+    try { info = top ? statSync(path) : lstatSync(path) } catch { return }
+    if (info.isDirectory()) {
+      for (const name of readdirSync(path).sort()) if (!name.startsWith('.') && name !== 'node_modules') walk(join(path, name), false)
+    } else if (info.isFile() && path.endsWith('.md')) files.push(path)
+  }
+  for (const path of chosen) walk(path, true)
+  return [...new Set(files)]
+}
+
+/** The shown path (~ for home) and the destination path inside Imported/synced/. A leading dot becomes _ (the engine skips dot-names), so .claude and claude stay apart. */
+export function describe(path, env) {
+  const base = home(env)
+  const rel = relative(base, path)
+  const inHome = !rel.startsWith('..') && rel !== ''
+  const shown = inHome ? '~/' + rel.split(sep).join('/') : path
+  const parts = (inHome ? rel.split(sep) : ['_', ...path.split(sep).filter(Boolean)]).map((p) => p.replace(/^\./, '_')).filter(Boolean)
+  return { shown, relativePath: parts.join('/') }
+}
+
+const sha = (text) => createHash('sha256').update(text).digest('hex')
+
+/** What to do for each chosen file, without calling Renor. */
+export function plan(env, state = loadState(env)) {
+  const items = []
+  for (const path of expand(state.chosen)) {
+    const { shown, relativePath } = describe(path, env)
+    const markdown = `<!-- renor-sync source: ${shown} -->\n\n${readFileSync(path, 'utf8')}`
+    const previous = state.synced[path]
+    const hash = sha(markdown)
+    let action = previous?.hash === hash ? 'unchanged' : previous ? 'update' : 'new'
+    if (Buffer.byteLength(markdown) > FILE_BYTES) action = 'too-big'
+    items.push({ path, shown, relativePath, markdown, hash, action, previous })
+  }
+  return items
+}
+
+/** The folders (synced, synced-2, …) this file is not in now, holds no kept copy in, and has no copy waiting to be retired in, in order. */
+function* freeLabels(previous) {
+  const waiting = [...(previous?.kept ?? []), ...(previous?.retire ?? [])].map((copy) => copy.label)
+  const used = new Set([previous?.label ?? (previous?.batchId ? LABEL : null), ...waiting])
+  for (let n = 1; n <= 50; n++) {
+    const label = n === 1 ? LABEL : `${LABEL}-${n}`
+    if (!used.has(label)) yield label
+  }
+}
+
+/**
+ * Retire an earlier batch of this file. Renor keeps a note the owner edited there and says so (`preserved`): that copy
+ * stays, is listed as kept, and its folder is not used for this file again. Returns 'retired' or 'kept'; a call that throws stays queued.
+ */
+async function retireOld(session, state, entry, old, shown, say, env) {
+  let undone
+  try {
+    undone = await session.call('undo_import', { batchId: old.batchId })
+  } catch (error) {
+    // A batch whose apply never happened has nothing to retire.
+    if (!/No applied batch|batch_not_found/.test(error instanceof Error ? error.message : '')) throw error
+    undone = {}
+  }
+  entry.retire = entry.retire.filter((copy) => copy.batchId !== old.batchId)
+  if (entry.retire.length === 0) delete entry.retire
+  // Preserved because another batch of this file still asserts the same text is not an edit; the last undo retires it.
+  const reasons = undone.preservedReasons ?? {}
+  const edited = (undone.preserved ?? []).filter((path) => !String(reasons[path] ?? '').startsWith('kept: re-asserted'))
+  let outcome = 'retired'
+  if (edited.length) {
+    if (!entry.kept?.some((copy) => copy.label === old.label)) entry.kept = [...(entry.kept ?? []), old]
+    say(`  kept      ${shown}: Renor kept the earlier copy (${reasons[edited[0]] || 'it was changed there, or could not be removed'}); the new copy is in`)
+    outcome = 'kept'
+  }
+  saveState(env, state)
+  return outcome
+}
+
+export async function sync(argv, io = { env: process.env, out: process.stdout, fetchImpl: fetch }) {
+  const { env, out } = io
+  const say = (line = '') => out.write(line + '\n')
+  const dryRun = argv.includes('--dry-run')
+  const words = argv.filter((arg) => !arg.startsWith('-'))
+  const [verb, ...rest] = words[0] === 'add' || words[0] === 'remove' || words[0] === 'list' ? words : ['run']
+  const state = loadState(env)
+
+  if (verb === 'add' || verb === 'remove') {
+    if (rest.length === 0) { say(`renor sync ${verb} needs at least one file or folder.`); return 2 }
+    const paths = rest.map((p) => resolve(p))
+    if (verb === 'add') {
+      const missing = paths.filter((p) => { try { statSync(p); return false } catch { return true } })
+      if (missing.length) { say(`Not found: ${missing.join(', ')}`); return 2 }
+      state.chosen = [...new Set([...state.chosen, ...paths])]
+    } else {
+      state.chosen = state.chosen.filter((p) => !paths.includes(p))
+    }
+    saveState(env, state)
+    const count = expand(state.chosen).length
+    say(`${verb === 'add' ? 'Chosen' : 'Left'}: ${paths.map((p) => describe(p, env).shown).join(', ')}. ${count} Markdown file${count === 1 ? '' : 's'} will sync. Run: renor sync`)
+    return 0
+  }
+
+  if (verb === 'list') {
+    for (const path of state.chosen) say(describe(path, env).shown)
+    if (state.chosen.length === 0) say('Nothing chosen. Add a file or folder: renor sync add ~/.claude/CLAUDE.md')
+    return 0
+  }
+
+  if (state.chosen.length === 0) {
+    say('Nothing chosen to sync. Pick the files you want Renor to hold, e.g.:')
+    say('  renor sync add ~/.claude/CLAUDE.md ./AGENTS.md')
+    return 0
+  }
+  const items = plan(env, state)
+  const pending = items.filter((item) => item.action === 'new' || item.action === 'update')
+  for (const item of items) say(`  ${item.action.padEnd(9)} ${item.shown}${item.action === 'too-big' ? ' (over 64 KiB; split it)' : ''}`)
+  const here = new Set(items.map((item) => item.path))
+  for (const path of Object.keys(state.synced)) {
+    if (!here.has(path)) say(`  gone      ${describe(path, env).shown} (deleted or no longer chosen; Renor still holds it, forget it in the dashboard)`)
+  }
+  const leftovers = Object.values(state.synced).some((entry) => entry.retire?.length)
+  if (dryRun || (pending.length === 0 && !leftovers)) {
+    say(dryRun ? 'Dry run: nothing was sent.' : 'Everything is already in sync.')
+    return 0
+  }
+  const token = env.RENOR_TOKEN
+  if (!token) { say('Set RENOR_TOKEN to a connect token from the Renor dashboard, then run renor sync again.'); return 2 }
+
+  let session
+  try {
+    session = await openSession(env.RENOR_MCP_URL || GATEWAY_URL, token, io.fetchImpl)
+  } catch (error) {
+    say(error instanceof Error ? error.message : String(error))
+    return 2
+  }
+  let failed = 0
+  try {
+    // An old copy that could not be retired last time goes first.
+    for (const [path, entry] of Object.entries(state.synced)) {
+      for (const old of [...(entry.retire ?? [])]) {
+        const shown = describe(path, env).shown
+        try {
+          await retireOld(session, state, entry, old, shown, say, env)
+        } catch (error) {
+          failed++
+          say(`  failed    ${shown}: could not retire an earlier copy: ${error instanceof Error ? error.message : error}`)
+        }
+      }
+    }
+    for (const item of pending) {
+      try {
+        // The new copy goes to a folder the file does not use yet, so it can be written while the old one is still
+        // there; the old one is retired only after the new one exists, and a failure on the way leaves it as it was.
+        const files = [{ relativePath: item.relativePath, markdown: item.markdown }]
+        // A folder where a different note already sits at this path (an attempt whose reply was lost) would be a conflict: skip it.
+        let label
+        let check
+        for (const candidate of freeLabels(item.previous)) {
+          check = await session.call('preview_import', { label: candidate, files, stage: false })
+          if (check.secretGuard || check.skipped?.length || !check.conflicts?.length) { label = candidate; break }
+        }
+        if (!label) throw new Error('no free folder for this file in Renor')
+        if (check.secretGuard || check.skipped?.length) throw new Error('Renor would leave this file out (it looks like it holds a secret, or is empty); the earlier copy was kept')
+        const preview = await session.call('preview_import', { label, files })
+        // Written down before apply: if the reply to apply is lost the batch may still have been applied, and every
+        // batch this file has had must be retired later or its text stays in Renor beside the current one.
+        const tried = item.previous ?? (state.synced[item.path] = { lost: [] })
+        tried.lost = [...(tried.lost ?? []), { batchId: preview.batchId, label }]
+        saveState(env, state)
+        const applied = await session.call('apply_import', { batchId: preview.batchId })
+        if (applied.notesConflicting) throw new Error('a different note is already at that place in Renor')
+        // Identical text already there (an earlier run whose reply was lost) counts: the batch asserts it again.
+        if ((applied.notesWritten ?? 0) + (applied.notesUnchanged ?? 0) !== 1) throw new Error('Renor wrote nothing for this file')
+        const before = item.previous ?? tried
+        const retire = [
+          ...(before.retire ?? []),
+          ...(before.batchId ? [{ batchId: before.batchId, label: before.label ?? LABEL }] : []),
+          ...(before.lost ?? []).filter((copy) => copy.batchId !== applied.batchId),
+        ]
+        const entry = { hash: item.hash, batchId: applied.batchId, label, syncedAt: new Date().toISOString() }
+        if (retire.length) entry.retire = retire
+        if (before.kept?.length) entry.kept = before.kept
+        state.synced[item.path] = entry
+        saveState(env, state)
+        let kept = false
+        for (const old of retire) {
+          try {
+            kept = (await retireOld(session, state, entry, old, item.shown, say, env)) === 'kept' || kept
+          } catch (error) {
+            failed++
+            say(`  failed    ${item.shown}: the new copy is in, the earlier one could not be retired (it is retried next run): ${error instanceof Error ? error.message : error}`)
+          }
+        }
+        if (!kept) say(`  synced    ${item.shown}`)
+      } catch (error) {
+        failed++
+        say(`  failed    ${item.shown}: ${error instanceof Error ? error.message : error}`)
+      }
+    }
+  } finally {
+    await session.close()
+  }
+  return failed ? 1 : 0
+}