renor 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Renor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# renor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Connects the AI apps on your computer to [Renor](https://renor.cloud), so they share one memory: tell one of them something, and the others know it too.
+
+```sh
+npx renor setup
+```
+
+It finds the apps you have, adds Renor to each, signs you in, and installs the Renor skill, which tells your AI when to save and when to recall. At the end it lists anything left for you to do, app by app.
+
+| App | How Renor is added | Sign-in |
+|---|---|---|
+| Claude Code | `claude mcp add --transport http --scope user renor …` | in Claude Code: `/mcp`, then Authenticate |
+| Codex | `codex mcp add renor --url …` | opens your browser right away |
+| Cursor | adds `renor` to `~/.cursor/mcp.json` (a backup of the old file is kept) | `cursor-agent mcp login renor`, or in Cursor's settings |
+| OpenCode | `opencode mcp add renor --url … --global` | `opencode mcp auth renor` |
+| Pi (0.99 or later) | `pi mcp add renor --url … --exposure direct` | `pi mcp login renor` |
+| VS Code | `code --add-mcp …` | when Copilot first uses Renor |
+
+Every app gets the same address, `https://mcp.renor.cloud/mcp`. No key is stored anywhere: you approve Renor in your browser, and each app keeps its own sign-in.
+
+## What it does not do
+
+- It never changes anything else in an app's config. A file with comments in it is left alone and you get the line to add by hand.
+- If an app already has a server named `renor` that points somewhere else, it is left as it is unless you pass `--force`.
+- It sends nothing anywhere itself. The only network use is the apps' own sign-ins and `npx skills` installing the skill.
+
+## Options
+
+```
+--dry-run      Say what would happen and change nothing
+-y, --yes      Do not ask before adding
+--no-login     Add Renor but leave the sign-ins for later
+--no-skill     Do not install the skill
+--force        Replace a renor server that points somewhere else
+--only <apps>  Only some apps: claude-code, codex, cursor, opencode, pi, vscode
+```
+
+ChatGPT and Claude in the browser are set up from your dashboard at https://app.renor.cloud.
+
+Needs Node.js 18 or later.

package/bin/renor.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * renor — connects the AI apps on this computer to Renor, the memory they share.
+ * Usage: npx renor setup [--yes] [--dry-run] [--no-login] [--no-skill] [--force] [--only claude-code,codex]
+ */
+import { readFileSync } from 'node:fs'
+import { HELP, parse } from '../lib/args.mjs'
+import { CLIENTS } from '../lib/clients.mjs'
+import { setup } from '../lib/setup.mjs'
+
+function version() {
+  try {
+    return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
+  } catch {
+    return 'unknown'
+  }
+}
+
+async function main() {
+  const options = parse(process.argv.slice(2))
+  if (options.version) {
+    process.stdout.write(version() + '\n')
+    return 0
+  }
+  if (options.help || !options.command) {
+    process.stdout.write(HELP + '\n')
+    return 0
+  }
+  if (options.command !== 'setup') {
+    process.stderr.write(`Unknown command: ${options.command}\n\n${HELP}\n`)
+    return 2
+  }
+  if (options.unknown.length > 0) {
+    process.stderr.write(`Unknown option: ${options.unknown.join(' ')}\n\n${HELP}\n`)
+    return 2
+  }
+  const unknownApps = (options.only || []).filter((id) => !CLIENTS.some((client) => client.id === id))
+  if (unknownApps.length > 0) {
+    process.stderr.write(`Unknown app: ${unknownApps.join(', ')}. Known: ${CLIENTS.map((client) => client.id).join(', ')}\n`)
+    return 2
+  }
+  const { code } = await setup(options)
+  return code
+}
+
+const [major] = process.versions.node.split('.').map(Number)
+if (major < 18) {
+  process.stderr.write(`renor needs Node.js 18 or later; this is ${process.versions.node}.\n`)
+  process.exit(1)
+}
+main().then(
+  (code) => process.exit(code),
+  (error) => {
+    process.stderr.write(`renor setup failed: ${error instanceof Error ? error.message : String(error)}\n`)
+    process.exit(1)
+  },
+)

package/lib/args.mjs

@@ -0,0 +1,38 @@
+/** The command line of `renor`: what it accepts, and its help text. */
+import { CLIENTS } from './clients.mjs'
+
+export const HELP = `renor — connect your AI apps to Renor, the memory they share.
+
+Usage
+  npx renor setup             Find your AI apps, add Renor to each, sign in, install the skill
+  npx renor setup --dry-run   Say what would happen and change nothing
+
+Options
+  -y, --yes       Do not ask before adding
+  --no-login      Add Renor but leave the sign-ins for later
+  --no-skill      Do not install the Renor skill
+  --force         Replace a renor server that points somewhere else
+  --only <apps>   Only these apps: ${CLIENTS.map((client) => client.id).join(', ')}
+  -h, --help      Show this help
+  -v, --version   Show the version
+
+ChatGPT and Claude in the browser are set up from https://app.renor.cloud.`
+
+export function parse(argv) {
+  const options = { command: null, yes: false, dryRun: false, login: true, skill: true, force: false, only: null, help: false, version: false, unknown: [] }
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === '-y' || arg === '--yes') options.yes = true
+    else if (arg === '--dry-run') options.dryRun = true
+    else if (arg === '--no-login') options.login = false
+    else if (arg === '--no-skill') options.skill = false
+    else if (arg === '--force') options.force = true
+    else if (arg === '--only') options.only = (argv[++i] || '').split(',').map((id) => id.trim()).filter(Boolean)
+    else if (arg.startsWith('--only=')) options.only = arg.slice(7).split(',').map((id) => id.trim()).filter(Boolean)
+    else if (arg === '-h' || arg === '--help') options.help = true
+    else if (arg === '-v' || arg === '--version') options.version = true
+    else if (!arg.startsWith('-') && !options.command) options.command = arg
+    else options.unknown.push(arg)
+  }
+  return options
+}

package/lib/clients.mjs

@@ -0,0 +1,237 @@
+/**
+ * One adapter per AI app `renor setup` knows. Each says how to find the app, whether Renor is already in its config,
+ * how to add it (the app's own command where it has one, a careful file merge where it does not), and how to sign in.
+ *
+ * The commands are the ones the dashboard's setup prompt gives people (src/lib/landing-setup-prompt.ts). What each
+ * app does with them was checked against the real apps on 2026-10-19 in a throwaway home folder: Claude Code 2.1.303,
+ * Codex 0.163.0, OpenCode 2.0.32, Pi 1.3.0 and cursor-agent 2026.10.16.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { GATEWAY_URL, SERVER_NAME } from './constants.mjs'
+import { atLeast, backupFile, capture, home, interactive, readJsonc, stripJsonComments, stripTrailingCommas, versionOf, which, writeJsonWithBackup } from './system.mjs'
+
+/** What an adapter's add reports. */
+const added = (detail = null, signedIn = false) => ({ ok: true, detail, signedIn })
+const failed = (detail) => ({ ok: false, detail, signedIn: false })
+
+/** The URL a config entry points at, from the shapes the apps use (`url`, or `serverUrl` in older files). */
+function urlOf(entry) {
+  if (!entry || typeof entry !== 'object') return null
+  return typeof entry.url === 'string' ? entry.url : typeof entry.serverUrl === 'string' ? entry.serverUrl : null
+}
+
+/** A JSON file we may rewrite: it parsed, and it held no comments that a rewrite would drop. */
+function plainJson(read) {
+  if (!read.ok) return false
+  if (!read.exists || !read.text) return true
+  return stripJsonComments(read.text).trim() === stripTrailingCommas(read.text).trim()
+}
+
+function vscodeUserDir(env) {
+  if (process.platform === 'darwin') return join(home(env), 'Library', 'Application Support', 'Code', 'User')
+  if (process.platform === 'win32') return join(env.APPDATA || join(home(env), 'AppData', 'Roaming'), 'Code', 'User')
+  return join(env.XDG_CONFIG_HOME || join(home(env), '.config'), 'Code', 'User')
+}
+
+function opencodeDir(env) {
+  return join(env.XDG_CONFIG_HOME || join(home(env), '.config'), 'opencode')
+}
+
+function codexConfig(env) {
+  return join(env.CODEX_HOME || join(home(env), '.codex'), 'config.toml')
+}
+
+/** Renor's table in Codex's config.toml, if any, and the url it holds. */
+function codexEntry(text) {
+  const lines = text.split(/\r?\n/)
+  const start = lines.findIndex((line) => /^\s*\[\s*mcp_servers\s*\.\s*(?:renor|"renor"|'renor')\s*\]\s*(#.*)?$/.test(line))
+  if (start < 0) return null
+  for (let i = start + 1; i < lines.length && !/^\s*\[/.test(lines[i]); i++) {
+    const match = lines[i].match(/^\s*url\s*=\s*"([^"]*)"/)
+    if (match) return { url: match[1] }
+  }
+  return { url: null }
+}
+
+export const CLIENTS = [
+  {
+    id: 'claude-code',
+    label: 'Claude Code',
+    detect: (ctx) => {
+      const bin = which('claude', ctx.env)
+      return bin ? { found: true, version: versionOf('claude', ctx.env) } : { found: false }
+    },
+    current: (ctx) => {
+      const read = readJsonc(join(home(ctx.env), '.claude.json'))
+      const entry = read.value?.mcpServers?.[SERVER_NAME]
+      return { readable: read.ok, configured: Boolean(entry), url: urlOf(entry) }
+    },
+    add: (ctx, { replace }) => {
+      if (replace) capture('claude', ['mcp', 'remove', SERVER_NAME, '-s', 'user'], { env: ctx.env })
+      const out = capture('claude', ['mcp', 'add', '--transport', 'http', '--scope', 'user', SERVER_NAME, GATEWAY_URL], { env: ctx.env })
+      return out.ok ? added() : failed((out.stderr || out.stdout || out.error || '').trim())
+    },
+    login: null,
+    signIn: 'Restart Claude Code, type /mcp, choose renor, then Authenticate.',
+    byHand: `claude mcp add --transport http --scope user ${SERVER_NAME} ${GATEWAY_URL}`,
+  },
+  {
+    id: 'codex',
+    label: 'Codex',
+    detect: (ctx) => (which('codex', ctx.env) ? { found: true, version: versionOf('codex', ctx.env) } : { found: false }),
+    current: (ctx) => {
+      const path = codexConfig(ctx.env)
+      if (!existsSync(path)) return { readable: true, configured: false, url: null }
+      try {
+        const entry = codexEntry(readFileSync(path, 'utf8'))
+        return { readable: true, configured: Boolean(entry), url: entry?.url ?? null }
+      } catch {
+        return { readable: false, configured: false, url: null }
+      }
+    },
+    // `codex mcp add` writes the config, then starts the browser sign-in and waits for it. Run in front of the person
+    // that is the whole setup; where nobody can approve a sign-in, the table is written directly instead, so nothing waits.
+    add: (ctx, { replace }) => {
+      if (replace) capture('codex', ['mcp', 'remove', SERVER_NAME], { env: ctx.env })
+      if (ctx.canSignIn) {
+        ctx.say(`Adding Renor to Codex. Codex opens your browser: sign in to Renor and approve.`)
+        const status = interactive('codex', ['mcp', 'add', SERVER_NAME, '--url', GATEWAY_URL], { env: ctx.env })
+        const nowThere = existsSync(codexConfig(ctx.env)) && codexEntry(readFileSync(codexConfig(ctx.env), 'utf8'))
+        if (status === 0) return added(null, true)
+        return nowThere ? added('The sign-in did not finish.') : failed(`codex mcp add exited with ${status}`)
+      }
+      const path = codexConfig(ctx.env)
+      mkdirSync(dirname(path), { recursive: true })
+      const before = existsSync(path) ? readFileSync(path, 'utf8') : ''
+      // A renor table that is still there (the remove above failed) would be written twice, which Codex cannot read.
+      if (codexEntry(before)) return failed(`${path} still has a [mcp_servers.${SERVER_NAME}] table that could not be removed, so it was left as it is.`)
+      const backup = before ? backupFile(path) : null
+      const table = `[mcp_servers.${SERVER_NAME}]\nurl = "${GATEWAY_URL}"\n`
+      appendFileSync(path, (before && !before.endsWith('\n') ? '\n' : '') + (before ? '\n' : '') + table)
+      return added(backup ? `The previous file is saved as ${backup}.` : null)
+    },
+    login: null,
+    signIn: 'Run codex mcp login renor, then restart Codex.',
+    byHand: `codex mcp add ${SERVER_NAME} --url ${GATEWAY_URL}`,
+  },
+  {
+    id: 'cursor',
+    label: 'Cursor',
+    detect: (ctx) => {
+      const bin = which('cursor-agent', ctx.env)
+      if (bin) return { found: true, version: versionOf('cursor-agent', ctx.env) }
+      return existsSync(join(home(ctx.env), '.cursor')) ? { found: true, version: null } : { found: false }
+    },
+    current: (ctx) => {
+      const read = readJsonc(join(home(ctx.env), '.cursor', 'mcp.json'))
+      const entry = read.value?.mcpServers?.[SERVER_NAME]
+      return { readable: read.ok, configured: Boolean(entry), url: urlOf(entry) }
+    },
+    add: (ctx) => {
+      const path = join(home(ctx.env), '.cursor', 'mcp.json')
+      const read = readJsonc(path)
+      if (!plainJson(read)) return failed(`${path} has comments or is not valid JSON, so it was left as it is.`)
+      const value = read.value && typeof read.value === 'object' ? read.value : {}
+      value.mcpServers = { ...(value.mcpServers || {}), [SERVER_NAME]: { url: GATEWAY_URL } }
+      const backup = writeJsonWithBackup(path, value)
+      return added(backup ? `The previous file is saved as ${backup}.` : null)
+    },
+    login: (ctx) => (which('cursor-agent', ctx.env) ? ['cursor-agent', ['mcp', 'login', SERVER_NAME]] : null),
+    signIn: 'Restart Cursor, open Settings › MCP, find renor and sign in.',
+    byHand: `Add { "mcpServers": { "${SERVER_NAME}": { "url": "${GATEWAY_URL}" } } } to ~/.cursor/mcp.json`,
+  },
+  {
+    id: 'opencode',
+    label: 'OpenCode',
+    detect: (ctx) => {
+      if (which('opencode', ctx.env)) return { found: true, version: versionOf('opencode', ctx.env) }
+      return existsSync(opencodeDir(ctx.env)) ? { found: true, version: null } : { found: false }
+    },
+    current: (ctx) => {
+      for (const name of ['opencode.json', 'opencode.jsonc']) {
+        const read = readJsonc(join(opencodeDir(ctx.env), name))
+        if (!read.exists) continue
+        // OpenCode 1 keeps servers under `mcp`, OpenCode 2 under `mcp.servers`; it reads both.
+        const entry = read.value?.mcp?.servers?.[SERVER_NAME] ?? read.value?.mcp?.[SERVER_NAME]
+        return { readable: read.ok, configured: Boolean(entry), url: urlOf(entry) }
+      }
+      return { readable: true, configured: false, url: null }
+    },
+    add: (ctx, { replace }) => {
+      // OpenCode's own command keeps the file's comments and format; an older OpenCode without it gets a careful merge.
+      if (!replace && which('opencode', ctx.env) && capture('opencode', ['mcp', 'add', '--help'], { env: ctx.env }).ok) {
+        const out = capture('opencode', ['mcp', 'add', SERVER_NAME, '--url', GATEWAY_URL, '--global'], { env: ctx.env })
+        if (out.ok) return added()
+      }
+      const path = join(opencodeDir(ctx.env), existsSync(join(opencodeDir(ctx.env), 'opencode.jsonc')) ? 'opencode.jsonc' : 'opencode.json')
+      const read = readJsonc(path)
+      if (!plainJson(read)) return failed(`${path} has comments or is not valid JSON, so it was left as it is.`)
+      const value = read.value && typeof read.value === 'object' ? read.value : {}
+      const mcp = { ...(value.mcp || {}) }
+      if (mcp.servers && typeof mcp.servers === 'object') mcp.servers = { ...mcp.servers, [SERVER_NAME]: { type: 'remote', url: GATEWAY_URL } }
+      else mcp[SERVER_NAME] = { type: 'remote', url: GATEWAY_URL }
+      value.mcp = mcp
+      const backup = writeJsonWithBackup(path, value)
+      return added(backup ? `The previous file is saved as ${backup}.` : null)
+    },
+    login: (ctx) => (which('opencode', ctx.env) ? ['opencode', ['mcp', 'auth', SERVER_NAME]] : null),
+    signIn: 'Run opencode mcp auth renor, then restart OpenCode.',
+    byHand: `opencode mcp add ${SERVER_NAME} --url ${GATEWAY_URL} --global`,
+  },
+  {
+    id: 'pi',
+    label: 'Pi',
+    detect: (ctx) => {
+      if (!which('pi', ctx.env)) return { found: false }
+      const version = versionOf('pi', ctx.env)
+      // `pi mcp` arrived in Pi 0.99.
+      return version && !atLeast(version, '0.99') ? { found: true, version, blocked: 'Update Pi first (pi update): Pi adds MCP servers from 0.99 on.' } : { found: true, version }
+    },
+    current: (ctx) => {
+      const read = readJsonc(join(home(ctx.env), '.pi', 'agent', 'mcp.json'))
+      const entry = read.value?.mcpServers?.[SERVER_NAME]
+      return { readable: read.ok, configured: Boolean(entry), url: urlOf(entry) }
+    },
+    // `pi mcp add` adds or replaces, so the same command serves a replacement.
+    add: (ctx) => {
+      const out = capture('pi', ['mcp', 'add', SERVER_NAME, '--url', GATEWAY_URL, '--exposure', 'direct'], { env: ctx.env })
+      return out.ok ? added() : failed((out.stderr || out.stdout || out.error || '').trim())
+    },
+    login: () => ['pi', ['mcp', 'login', SERVER_NAME]],
+    signIn: 'Run pi mcp login renor, then /reload in Pi.',
+    byHand: `pi mcp add ${SERVER_NAME} --url ${GATEWAY_URL} --exposure direct`,
+  },
+  {
+    id: 'vscode',
+    label: 'VS Code',
+    detect: (ctx) => (which('code', ctx.env) ? { found: true, version: versionOf('code', ctx.env) } : { found: false }),
+    current: (ctx) => {
+      const read = readJsonc(join(vscodeUserDir(ctx.env), 'mcp.json'))
+      const entry = read.value?.servers?.[SERVER_NAME]
+      return { readable: read.ok, configured: Boolean(entry), url: urlOf(entry) }
+    },
+    add: (ctx, { replace }) => {
+      if (replace) {
+        const path = join(vscodeUserDir(ctx.env), 'mcp.json')
+        const read = readJsonc(path)
+        if (!plainJson(read)) return failed(`${path} has comments or is not valid JSON, so it was left as it is.`)
+        const value = read.value || {}
+        value.servers = { ...(value.servers || {}), [SERVER_NAME]: { type: 'http', url: GATEWAY_URL } }
+        const backup = writeJsonWithBackup(path, value)
+        return added(backup ? `The previous file is saved as ${backup}.` : null)
+      }
+      const out = capture('code', ['--add-mcp', JSON.stringify({ name: SERVER_NAME, type: 'http', url: GATEWAY_URL })], { env: ctx.env })
+      return out.ok ? added() : failed((out.stderr || out.stdout || out.error || '').trim())
+    },
+    login: null,
+    signIn: 'Open VS Code. Copilot asks you to sign in to Renor the first time it uses it.',
+    byHand: `code --add-mcp '${JSON.stringify({ name: SERVER_NAME, type: 'http', url: GATEWAY_URL })}'`,
+  },
+]
+
+export function findClient(id) {
+  return CLIENTS.find((client) => client.id === id) ?? null
+}
+
+export { codexEntry, plainJson }

package/lib/constants.mjs

@@ -0,0 +1,27 @@
+/**
+ * What `renor setup` adds and installs. The same values the dashboard's setup prompt gives
+ * (src/lib/landing-setup-prompt.ts); tests/cli-setup.test.ts in the platform suite fails if they drift apart.
+ */
+
+/** Renor's one public MCP address. Sign-in is OAuth in the browser, so nothing here carries a key. */
+export const GATEWAY_URL = 'https://mcp.renor.cloud/mcp'
+
+/** The server's name in every client's config. */
+export const SERVER_NAME = 'renor'
+
+/** The public skill, pinned: the exact `skills` CLI version and the renor-skills commit it fetches. */
+export const SKILLS_CLI_VERSION = '1.7.2'
+export const RENOR_SKILLS_COMMIT = '018fddc51e6066c30c6919fdf27bbb1c8b64187a'
+export const SKILL_INSTALL_ARGS = [
+  '-y',
+  `skills@${SKILLS_CLI_VERSION}`,
+  'add',
+  `https://github.com/patrickpassosb/renor-skills/tree/${RENOR_SKILLS_COMMIT}`,
+  '--agent',
+  '*',
+  '-y',
+]
+
+/** What to tell the person to try once everything is connected (FIRST_MEMORY_CHECK in the platform). */
+export const FIRST_MEMORY_SAVE = 'Save to Renor: my favorite editor is Neovim.'
+export const FIRST_MEMORY_RECALL = 'What is my favorite editor?'

package/lib/setup.mjs

@@ -0,0 +1,171 @@
+/**
+ * `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 { 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.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, 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) {
+    results.push(await setUpOne(client, detection, { ...options, canSignIn }, { env, say }))
+  }
+
+  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}.` }
+    }
+  }
+
+  report(results, skill, { say, paint })
+  const failures = results.filter((result) => result.state === 'failed').length + (skill && !skill.ok ? 1 : 0)
+  return { code: failures > 0 ? 1 : 0, results, skill }
+}
+
+function planFor(client, detection, now, options) {
+  if (detection.blocked) return detection.blocked
+  if (now.configured && now.url === GATEWAY_URL) 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 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 (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/system.mjs

@@ -0,0 +1,194 @@
+/**
+ * The few things `renor setup` asks of the machine: find a program, run it (quietly or in front of the person), and read
+ * or carefully write a JSON config file. Nothing here talks to the network itself.
+ */
+import { spawnSync } from 'node:child_process'
+import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { delimiter, dirname, join } from 'node:path'
+import { createInterface } from 'node:readline'
+
+const WINDOWS = process.platform === 'win32'
+
+/** The person's home folder. RENOR_SETUP_HOME exists for tests, so they never touch a real home. */
+export function home(env = process.env) {
+  return env.RENOR_SETUP_HOME || env.HOME || env.USERPROFILE || homedir()
+}
+
+/** The full path of a program on PATH, or null. */
+export function which(command, env = process.env) {
+  const dirs = (env.PATH || env.Path || '').split(delimiter).filter(Boolean)
+  const exts = WINDOWS ? (env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';') : ['']
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const candidate = join(dir, command + ext)
+      try {
+        if (statSync(candidate).isFile()) return candidate
+      } catch {
+        // not here
+      }
+    }
+  }
+  return null
+}
+
+/** Run a program and keep what it prints. Never throws; a program that could not start reports ok: false. */
+export function capture(command, args, { env = process.env, timeoutMs = 20_000, input } = {}) {
+  const result = spawnSync(command, args, {
+    env,
+    encoding: 'utf8',
+    timeout: timeoutMs,
+    input: input ?? '',
+    shell: WINDOWS,
+    windowsHide: true,
+  })
+  return {
+    ok: result.status === 0,
+    status: result.status,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    error: result.error ? String(result.error.message || result.error) : null,
+  }
+}
+
+/** Run a program in front of the person (a sign-in that opens the browser and waits). Returns its exit status. */
+export function interactive(command, args, { env = process.env } = {}) {
+  const result = spawnSync(command, args, { env, stdio: 'inherit', shell: WINDOWS })
+  return result.status ?? 1
+}
+
+/** A program's version line, or null. */
+export function versionOf(command, env = process.env) {
+  const out = capture(command, ['--version'], { env, timeoutMs: 10_000 })
+  if (!out.ok) return null
+  const line = (out.stdout || out.stderr).trim().split('\n')[0] || ''
+  const match = line.match(/\d+\.\d+(\.\d+)?/)
+  return match ? match[0] : line || null
+}
+
+/** True when `version` is at least `minimum` (both dotted numbers). */
+export function atLeast(version, minimum) {
+  const a = String(version || '').split('.').map((part) => parseInt(part, 10) || 0)
+  const b = minimum.split('.').map((part) => parseInt(part, 10) || 0)
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    if ((a[i] || 0) !== (b[i] || 0)) return (a[i] || 0) > (b[i] || 0)
+  }
+  return true
+}
+
+/**
+ * JSON with comments (OpenCode allows them), read without a dependency: comments outside strings are dropped and
+ * trailing commas removed. Returns { exists, ok, value } and never throws.
+ */
+export function readJsonc(path) {
+  if (!existsSync(path)) return { exists: false, ok: true, value: {} }
+  let text
+  try {
+    text = readFileSync(path, 'utf8')
+  } catch {
+    return { exists: true, ok: false, value: null }
+  }
+  if (!text.trim()) return { exists: true, ok: true, value: {}, text }
+  try {
+    return { exists: true, ok: true, value: JSON.parse(stripJsonComments(text)), text }
+  } catch {
+    return { exists: true, ok: false, value: null, text }
+  }
+}
+
+export function stripJsonComments(text) {
+  let out = ''
+  let inString = false
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i]
+    const next = text[i + 1]
+    if (inString) {
+      out += ch
+      if (ch === '\\') {
+        out += next ?? ''
+        i++
+      } else if (ch === '"') {
+        inString = false
+      }
+      continue
+    }
+    if (ch === '"') {
+      inString = true
+      out += ch
+    } else if (ch === '/' && next === '/') {
+      while (i < text.length && text[i] !== '\n') i++
+      out += '\n'
+    } else if (ch === '/' && next === '*') {
+      i += 2
+      while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) i++
+      i++
+    } else {
+      out += ch
+    }
+  }
+  return stripTrailingCommas(out)
+}
+
+function closesNext(text, from) {
+  let i = from
+  while (i < text.length && /\s/.test(text[i])) i++
+  return text[i] === '}' || text[i] === ']'
+}
+
+/** Drop a comma that sits right before a closing brace or bracket, outside strings (a `,}` inside a string stays). */
+export function stripTrailingCommas(text) {
+  let out = ''
+  let inString = false
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i]
+    if (inString) {
+      out += ch
+      if (ch === '\\') {
+        out += text[i + 1] ?? ''
+        i++
+      } else if (ch === '"') {
+        inString = false
+      }
+    } else if (ch === '"') {
+      inString = true
+      out += ch
+    } else if (ch === ',' && closesNext(text, i + 1)) {
+      // a trailing comma: dropped
+    } else {
+      out += ch
+    }
+  }
+  return out
+}
+
+/**
+ * Write a JSON config. An existing file is copied next to itself first (`<name>.renor-backup-<time>`), and only a file
+ * that held plain JSON (no comments) is ever rewritten, so nothing the person wrote is lost.
+ */
+export function backupFile(path, now = new Date()) {
+  const backup = `${path}.renor-backup-${now.toISOString().replace(/[:.]/g, '-')}`
+  copyFileSync(path, backup)
+  return backup
+}
+
+export function writeJsonWithBackup(path, value, { now = new Date() } = {}) {
+  let backup = null
+  if (existsSync(path)) {
+    backup = backupFile(path, now)
+  } else {
+    mkdirSync(dirname(path), { recursive: true })
+  }
+  writeFileSync(path, JSON.stringify(value, null, 2) + '\n')
+  return backup
+}
+
+/** Ask a yes/no question; Enter means yes. */
+export function confirm(question, { input = process.stdin, output = process.stdout } = {}) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input, output })
+    rl.question(question, (answer) => {
+      rl.close()
+      resolve(!/^\s*n/i.test(answer))
+    })
+  })
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "renor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Connect your AI apps (Claude Code, Codex, Cursor, OpenCode, Pi, VS Code) to Renor, the memory they share.",
+  "type": "module",
+  "bin": {
+    "renor": "bin/renor.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "renor",
+    "mcp",
+    "memory",
+    "claude-code",
+    "codex",
+    "cursor",
+    "opencode"
+  ],
+  "homepage": "https://renor.cloud",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/patrickpassosb/renor.git",
+    "directory": "cli"
+  },
+  "license": "MIT"
+}