ethagent 4.1.1 → 4.3.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ethagent",
-  "version": "4.1.1",
+  "version": "4.3.0",
   "description": "Portable Ethereum identity for your AI agent. Its soul, memory, and skills live onchain via ERC-8004 + IPFS and snap back into any session.",
   "author": { "name": "bairon.dev" },
   "homepage": "https://github.com/baairon/ethagent",
@@ -19,7 +19,7 @@
       {
         "matcher": "Edit|Write|MultiEdit",
         "hooks": [
-          { "type": "command", "command": "npx -y ethagent --memory-guard" }
+          { "type": "command", "command": "npx -y ethagent --pretool-guard" }
         ]
       }
     ],

package/README.md

@@ -42,7 +42,7 @@ That's the whole setup. You'll only open `ethagent` again to hand-edit your agen
 
 - **Soul** (`SOUL.md`): who it is, your standards, your voice, the way you work.
 - **Memory** (`MEMORY.md`): what it has learned about you, your preferences, and your projects, so context survives the move to a new machine.
-- **Skills:** the commands, tools, and prompts you teach it. Public by default, so other agents can discover them; mark one private to keep it off your public Agent Card (the profile your token publishes).
+- **Skills:** the commands, tools, and prompts you teach it. **Private by default** — yours alone, encrypted in your vault and mirrored into your harnesses so you can use them locally, but kept off your public Agent Card. Make one **public** when you want other agents to discover it; then only its name and description go on the card your token publishes.
 
 You grow these mostly by talking: with the plugin on, your agent updates its own soul and memory as you converse, and the changes sync automatically. To edit them by hand, open `ethagent`. To save your agent onchain so it can come back on any machine, choose **Save Snapshot** and sign.
 
@@ -63,7 +63,7 @@ Using another harness? You can still sync, but only Claude Code does it automati
 npx ethagent --sync
 ```
 
-It syncs files between `ethagent` and your harness on this machine, but only when you run it. To back it up so you can restore it anywhere, open `ethagent` and choose **Save Snapshot**.
+One command syncs it into every harness on this machine — soul, memory, and skills (public and private) — but only when you run it. To back it up so you can restore it anywhere, run `ethagent save` (or open `ethagent` and choose **Save Snapshot**); either way you approve the signature in your wallet.
 
 ## 🔒 What stays private
 
@@ -95,14 +95,31 @@ Built on open standards, so your agent is never tied to one harness.
 | Naming | ENS | A human-readable name that resolves to your agent and restores it from the name alone. |
 | Backup | IPFS snapshot | The encrypted bundle of soul, memory, and skills, pinned offchain and unlocked only by your wallet. |
 
+## 🔄 Updating
+
+ethagent ships as two pieces, and a full update can touch both:
+
+- **The npm package** (the engine: sync, skills, the guards). The plugin's hooks call `npx -y ethagent`, which resolves the latest published release, so **publishing a new version is the update** — nothing for most people to run. If you installed it globally, or call a bare `ethagent` in a hook or your shell, refresh that copy:
+
+  ```bash
+  npm i -g ethagent@latest
+  ```
+
+  Confirm what you're running with `ethagent --version`.
+
+- **The Claude Code plugin** (the hook wiring). New hooks ship in the plugin manifest, so to pick them up, update the plugin from the marketplace with `/plugin`.
+
+Rule of thumb: new sync and skill behavior rides your existing hooks as soon as the package is published; a brand-new hook also needs a plugin update.
+
 ## ⌨️ Commands
 
 Run with `npx ethagent`:
 
 | Command | What it does |
 | --- | --- |
-| `ethagent` | Open the interactive identity manager: create, ENS, custody, snapshots, transfer. |
-| `--sync` | Sync soul, memory, and public skills into every harness it detects. |
+| `ethagent` | Open the interactive identity manager: create, ENS, custody, transfer. |
+| `save` | Save an encrypted snapshot: pin to IPFS and rotate the onchain pointer. Opens your browser wallet to approve; add `--no-open` to only print the URL, `--json` for machine output. |
+| `--sync` | Sync soul, memory, and skills (public and private) into every harness it detects. |
 | `--sync-list` | List sync adapters and which ones detect in the current environment. |
 | `--status` | Print a one-line identity summary. |
 | `--demo` | Walk the manager with synthetic data, no wallet needed. |

package/commands/ethagent.md

@@ -3,9 +3,10 @@ name: ethagent
 description: Point the user at ethagent. ethagent stores an agent's identity onchain via ERC-8004 and syncs its soul, memory, and public skills into the active harness (Claude Code or Codex) on every SessionStart. To manage identity (create, ENS, custody, snapshots, transfer), the user runs `npx ethagent` in a separate terminal.
 ---
 
-Tell the user to run these in a separate terminal window, not inside this session:
+Most of these run in a separate terminal because they need a wallet or a TTY, but a few are safe to run from inside this session; each bullet says which:
 
-- `npx ethagent` opens the interactive identity manager for anything that needs a wallet signature (create agent, set ENS, switch custody, save snapshot, prepare transfer).
+- `npx ethagent` opens the interactive identity manager for anything that needs a wallet signature (create agent, set ENS, switch custody, prepare transfer).
+- `ethagent save` runs Save Snapshot (encrypt, pin to IPFS, rotate the onchain pointer). **You can run this yourself** as a normal tool call (e.g. `npx ethagent save`): no separate terminal and no TTY, and it will not hang. It prints a localhost wallet URL and opens the browser tab so the user approves the signature and transaction there. You trigger and run it; the user only approves in the wallet. Pass `--no-open` to just print the URL. Only run it when the user specifically asks to save or back up the agent; never run it on your own initiative or as a side effect of other work. It is a no-op (no wallet, no gas) when there are no local changes since the last snapshot.
 - `npx ethagent --sync` syncs the agent's soul, memory, and skills with every detected harness; soul and memory sync both ways, newest edit wins.
 - `npx ethagent --sync-list` shows which harnesses ethagent detects on this machine.
 - `npx ethagent --demo` walks the identity manager with synthetic data, no wallet or network required.
@@ -14,7 +15,7 @@ Tell the user to run these in a separate terminal window, not inside this sessio
 
 To rebuild the agent on a new machine, the user runs `npx ethagent`; it restores the identity from an ENS name or ERC-8004 token id, then asks the wallet to sign.
 
-You may run the non-interactive flags yourself when it helps (`--sync`, `--status`, `--sync-list`). Never launch the bare interactive `npx ethagent` or `--demo` from inside a session: they open a full-screen terminal app that needs a TTY and will hang the tool call. Anything that needs a wallet signature, the user always runs themselves.
+You may run the read-only non-interactive commands yourself whenever they help (`--sync`, `--status`, `--sync-list`). `ethagent save` is different: run it only when the user specifically asks you to save or back up the agent, never on your own initiative or as a side effect of other work. When they do ask, you can run it directly: there is no CLI step for the user and no separate terminal needed. It is headless, will not hang, prints a wallet URL, and opens the browser tab where the user approves the signature. You trigger and run the command; you never sign. (It is also a no-op when there are no local changes since the last snapshot.) Never launch the bare interactive `npx ethagent` or `--demo` from inside a session: they open a full-screen terminal app that needs a TTY and will hang the tool call. Anything else that needs a wallet signature (create, ENS, custody, transfer), the user always runs themselves.
 
 Where the synced files land:
 
@@ -35,6 +36,6 @@ The agent's portable identity lives in the ethagent vault and syncs into every h
   - Voice, standards, operating principles, and boundaries go in the vault `SOUL.md` in the same folder.
 - The vault files are the source of truth. After editing them, run `npx ethagent --sync` so the change propagates into `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, and any other detected harness.
 - Do NOT store durable identity in Claude Code's per-project memory (`~/.claude/projects/<slug>/memory/`): the sync treats those files as write-only mirror targets and overwrites them, and they never reach Codex or the encrypted backup. Keep only session- or repo-specific scratch notes there.
-- Syncing is not backup. To persist durable changes into the encrypted IPFS snapshot and onchain pointer, the user runs `npx ethagent` and chooses Save Snapshot (needs a wallet signature).
+- Syncing is not backup. To persist durable changes into the encrypted IPFS snapshot and onchain pointer, run `ethagent save` yourself: it pins the encrypted snapshot and rotates the onchain pointer, and the user only approves the signature in the browser wallet.
 
 If they ask "what's my agent" or "list my skills" without an identity yet, point them at `npx ethagent` to set one up first.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ethagent",
-  "version": "4.1.1",
+  "version": "4.3.0",
   "description": "Portable Ethereum identity for your AI agent. Its soul, memory, and skills live onchain via ERC-8004 + IPFS and snap back into any session.",
   "type": "module",
   "bin": {

package/src/cli/main.tsx

@@ -13,9 +13,12 @@ import type { IdentityManagerResult } from '../identity/manager/IdentityManager.
 import { loadConfig, saveConfig, type EthagentConfig } from '../storage/config.js'
 import { runSync, runSyncList, runSyncOnEdit } from './sync.js'
 import { runMemoryGuard } from './memoryGuard.js'
+import { runSkillGuard } from './skillGuard.js'
+import { runPreToolGuard } from './pretoolGuard.js'
 import { runSessionStart } from './sessionStart.js'
 import { runStatus } from './status.js'
 import { runResetCommand } from './reset.js'
+import { runSave } from './save.js'
 import { enableDemoMode, synthDemoConfig } from './demo.js'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
@@ -36,6 +39,7 @@ function printHelp(): void {
     '',
     'usage:',
     '  ethagent                    manage identity',
+    '  ethagent save               save an encrypted snapshot: pin to IPFS, rotate the onchain pointer (you approve in your wallet)',
     '  ethagent reset              delete local identity, continuity, and secrets',
     '  ethagent --sync             sync soul, memory, and skills to every harness',
     '  ethagent --sync-list        list sync adapters and which ones detect here',
@@ -46,7 +50,9 @@ function printHelp(): void {
     '',
     'plugin hooks (invoked automatically, not meant to be run by hand):',
     '  ethagent --session-start    sync, then tell the agent where to record memory',
+    '  ethagent --pretool-guard    one PreToolUse guard combining --memory-guard + --skill-guard',
     '  ethagent --memory-guard     keep agent memory in the portable markers, not local notes',
+    '  ethagent --skill-guard      keep skills in the portable vault, not the harness mirror',
   ]
   for (const line of lines) process.stdout.write(line + '\n')
 }
@@ -149,7 +155,9 @@ async function main(): Promise<number> {
   }
   if (flags.has('--sync-on-edit')) return runSyncOnEdit()
   if (flags.has('--session-start')) return runSessionStart()
+  if (flags.has('--pretool-guard')) return runPreToolGuard()
   if (flags.has('--memory-guard')) return runMemoryGuard()
+  if (flags.has('--skill-guard')) return runSkillGuard()
   if (flags.has('--sync-list')) return runSyncList()
   if (flags.has('--sync')) return runSync()
   if (flags.has('--status')) return runStatus(version)
@@ -157,6 +165,8 @@ async function main(): Promise<number> {
     enableDemoMode()
     return renderHub(synthDemoConfig())
   }
+  if (argv[0] === 'save') return runSave(argv.slice(1))
+  if (flags.has('--save')) return runSave(argv.filter(a => a !== '--save'))
   if (argv[0] === 'reset') return runResetCommand(argv.slice(1))
 
   const unknown = argv.find(a => a.startsWith('-'))

package/src/cli/pretoolGuard.ts

@@ -0,0 +1,32 @@
+import { loadConfig } from '../storage/config.js'
+import { hookFilePath, readHookPayload } from './hookIo.js'
+import { decideMemoryGuard } from './memoryGuard.js'
+import { decideSkillGuard } from './skillGuard.js'
+
+/**
+ * Combined PreToolUse guard: runs the memory-dir guard and the skills-mirror
+ * guard from a single process, so each Edit/Write/MultiEdit spawns one `npx`
+ * (one config load, one stdin read) instead of two. The two guards check
+ * disjoint directories, so at most one denies.
+ */
+export async function runPreToolGuard(): Promise<number> {
+  try {
+    const config = await loadConfig()
+    const filePath = hookFilePath(await readHookPayload())
+    const opts = { identityPresent: !!config?.identity }
+    const memory = decideMemoryGuard(filePath, opts)
+    const decision = memory.deny ? memory : decideSkillGuard(filePath, opts)
+    if (decision.deny) {
+      process.stdout.write(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: decision.reason,
+          },
+        }) + '\n',
+      )
+    }
+  } catch {}
+  return 0
+}

package/src/cli/save.ts

@@ -0,0 +1,162 @@
+import { stdout, stderr } from 'node:process'
+import { loadConfig, saveConfig, type EthagentConfig } from '../storage/config.js'
+import { resolveRegistryForIdentity } from '../identity/registry/registryConfig.js'
+import { continuityVaultStatus, continuityWorkingTreeStatus } from '../identity/continuity/storage/status.js'
+import { listPublishedContinuitySnapshots } from '../identity/continuity/snapshots.js'
+import { resolveValidatedPinataJwt } from '../identity/storage/pinataJwt.js'
+import { runRebackupSigning } from '../identity/manager/continuity/effects.js'
+import type { EffectCallbacks } from '../identity/manager/shared/effects/types.js'
+import { isWalletCancelled } from '../identity/manager/shared/utils.js'
+import type { Step } from '../identity/manager/reducer.js'
+import { openExternalUrl } from '../utils/openExternal.js'
+
+// Headless Save Snapshot: encrypt soul/memory/skills, pin to IPFS, and rotate the
+// ERC-8004 onchain pointer. The agent can trigger this; the human still approves the
+// signature and transaction in the browser wallet tab. The whole pipeline is reused
+// from the ink TUI (`runRebackupSigning`) with a print-only callbacks shim.
+//
+// Exit codes: 0 success · 1 no identity / not restored / generic runtime error ·
+// 2 usage (unknown option) · 3 credential or wallet problem the human must resolve
+// (no JWT, invalid JWT, or wallet cancelled/timed out).
+
+export type RunSaveDeps = {
+  loadConfig: typeof loadConfig
+  saveConfig: typeof saveConfig
+  resolveValidatedPinataJwt: typeof resolveValidatedPinataJwt
+  continuityVaultStatus: typeof continuityVaultStatus
+  continuityWorkingTreeStatus: typeof continuityWorkingTreeStatus
+  listPublishedContinuitySnapshots: typeof listPublishedContinuitySnapshots
+  runRebackupSigning: typeof runRebackupSigning
+  openExternalUrl: typeof openExternalUrl
+}
+
+const defaultDeps: RunSaveDeps = {
+  loadConfig,
+  saveConfig,
+  resolveValidatedPinataJwt,
+  continuityVaultStatus,
+  continuityWorkingTreeStatus,
+  listPublishedContinuitySnapshots,
+  runRebackupSigning,
+  openExternalUrl,
+}
+
+export async function runSave(args: string[] = [], deps: RunSaveDeps = defaultDeps): Promise<number> {
+  const json = args.includes('--json')
+  const noOpen = args.includes('--no-open')
+  const unknown = args.filter(a => a !== '--json' && a !== '--no-open')
+  if (unknown.length > 0) {
+    stderr.write(`unknown save option: ${unknown[0]}\nusage: ethagent save [--json] [--no-open]\n`)
+    return 2
+  }
+
+  const fail = (code: number, message: string): number => {
+    if (json) stdout.write(JSON.stringify({ ok: false, code, error: message }) + '\n')
+    else stderr.write(message + '\n')
+    return code
+  }
+
+  const config = await deps.loadConfig().catch(() => null)
+  if (!config?.identity) {
+    return fail(1, 'No agent identity yet. Run `npx ethagent` to create or link one.')
+  }
+  const activeConfig: EthagentConfig = config
+  const identity = config.identity
+
+  if (!identity.agentId) {
+    return fail(1, 'This identity has no agent token ID yet. Create or restore it with `npx ethagent` first.')
+  }
+
+  const registry = resolveRegistryForIdentity(identity, activeConfig)
+  if (!registry) {
+    return fail(1, 'No agent registry configured for this identity. Run `npx ethagent` to set it up.')
+  }
+
+  const vault = await deps.continuityVaultStatus(identity).catch(() => ({ ready: false }))
+  if (!vault.ready) {
+    return fail(1, 'Local continuity files are not restored. Run `npx ethagent` and restore this identity before saving a snapshot.')
+  }
+
+  // Only proceed when the working tree actually differs from the last published
+  // snapshot. If it is already up to date, do nothing: no wallet, no transaction, no
+  // gas. We only block on the confirmed-equal state ('published'); first saves
+  // ('not-published') and undeterminable cases still go through.
+  let publishState: string | undefined
+  try {
+    const [latest] = await deps.listPublishedContinuitySnapshots(identity, 1)
+    const tree = await deps.continuityWorkingTreeStatus(identity, latest)
+    publishState = tree.publishState
+  } catch {
+    publishState = undefined
+  }
+  if (publishState === 'published') {
+    if (json) stdout.write(JSON.stringify({ ok: true, skipped: true, reason: 'no-local-changes' }) + '\n')
+    else stdout.write('No local changes since the last snapshot; nothing to save.\n')
+    return 0
+  }
+
+  // JWT is resolved and validated BEFORE opening the wallet, so we never ask for a
+  // signature on a snapshot that then cannot be pinned.
+  let jwt: string | undefined
+  try {
+    jwt = await deps.resolveValidatedPinataJwt()
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err)
+    return fail(3, `The configured Pinata JWT is invalid or unreachable (${detail}). The wallet was not opened. Update it via \`npx ethagent\` -> IPFS Storage, then retry \`ethagent save\`.`)
+  }
+  if (!jwt) {
+    return fail(3, 'No IPFS storage credential configured, so the snapshot cannot be pinned and the wallet was not opened. Run `npx ethagent` once and set up IPFS Storage (or export PINATA_JWT in this shell), then retry `ethagent save`.')
+  }
+
+  let completed = false
+  const callbacks: EffectCallbacks = {
+    onStep: () => {},
+    onWalletReady: ready => {
+      if (!ready) return
+      const sink = json ? stderr : stdout
+      sink.write(`Approve this snapshot in your browser wallet tab: ${ready.url}\n`)
+      sink.write('Connect your wallet, sign one message, and approve one transaction (up to ~5 minutes)...\n')
+      if (!noOpen) deps.openExternalUrl(ready.url)
+    },
+    onIdentityComplete: async nextIdentity => {
+      await deps.saveConfig({ ...activeConfig, identity: nextIdentity })
+      completed = true
+      if (json) {
+        stdout.write(JSON.stringify({
+          ok: true,
+          cid: nextIdentity.backup?.cid ?? null,
+          txHash: nextIdentity.backup?.txHash ?? null,
+          agentUri: nextIdentity.agentUri ?? null,
+        }) + '\n')
+      } else {
+        stdout.write('Snapshot saved.\n')
+        if (nextIdentity.backup?.cid) stdout.write(`  CID:      ${nextIdentity.backup.cid}\n`)
+        if (nextIdentity.backup?.txHash) stdout.write(`  tx:       ${nextIdentity.backup.txHash}\n`)
+        if (nextIdentity.agentUri) stdout.write(`  agentURI: ${nextIdentity.agentUri}\n`)
+      }
+    },
+  }
+
+  const step: Extract<Step, { kind: 'rebackup-signing' }> = {
+    kind: 'rebackup-signing',
+    identity,
+    registry,
+    pinataJwt: jwt,
+    returnTo: { kind: 'menu' },
+  }
+
+  try {
+    await deps.runRebackupSigning(step, callbacks)
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    if (isWalletCancelled(err) || /timed out/i.test(message)) {
+      return fail(3, 'Wallet approval was cancelled or timed out. No snapshot was saved. Retry `ethagent save` when ready.')
+    }
+    return fail(1, `Save failed: ${message}`)
+  }
+
+  if (!completed) {
+    return fail(1, 'Save did not complete and no snapshot was recorded. Retry `ethagent save`.')
+  }
+  return 0
+}

package/src/cli/skillGuard.ts

@@ -0,0 +1,47 @@
+import { loadConfig } from '../storage/config.js'
+import { hookFilePath, isWithinDir, readHookPayload } from './hookIo.js'
+import { claudeSkillsDir } from './syncAdapters/claude-code.js'
+
+export const SKILL_REDIRECT_REASON =
+  "ethagent keeps this agent's skills in its portable continuity vault and generates the ~/.claude/skills " +
+  'mirror from it. Skills you create or edit directly here do not travel with the agent, and ethagent-managed ' +
+  'mirror copies are regenerated from the vault on the next sync. Author or edit skills in the vault instead: ' +
+  'run `ethagent` and open Skills (create, edit, set visibility) so they are versioned, encrypted, and synced ' +
+  'into every harness automatically. New skills are private by default; switch one to public only when you want ' +
+  'it listed on your Agent Card.'
+
+export function decideSkillGuard(
+  filePath: string | null | undefined,
+  opts: { identityPresent: boolean },
+): { deny: boolean; reason?: string } {
+  if (!opts.identityPresent) return { deny: false }
+  if (!filePath) return { deny: false }
+  // Scope: this guards the Claude Code skills mirror only. The Codex
+  // ~/.codex/AGENTS.md skill mirror is intentionally left unguarded, matching
+  // the Claude-only --memory-guard — the PreToolUse hook is registered only in
+  // the Claude Code plugin manifest.
+  if (isWithinDir(claudeSkillsDir(), filePath)) {
+    return { deny: true, reason: SKILL_REDIRECT_REASON }
+  }
+  return { deny: false }
+}
+
+export async function runSkillGuard(): Promise<number> {
+  try {
+    const config = await loadConfig()
+    const filePath = hookFilePath(await readHookPayload())
+    const decision = decideSkillGuard(filePath, { identityPresent: !!config?.identity })
+    if (decision.deny) {
+      process.stdout.write(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: decision.reason,
+          },
+        }) + '\n',
+      )
+    }
+  } catch {}
+  return 0
+}

package/src/cli/sync.ts

@@ -5,6 +5,7 @@ import { continuityWorkingTreeStatus } from '../identity/continuity/storage/stat
 import { listPublishedContinuitySnapshots } from '../identity/continuity/snapshots.js'
 import { changedContinuitySnapshotFiles } from '../identity/manager/continuity/state.js'
 import { listSkills } from '../identity/continuity/skills/loadSkills.js'
+import { isDraftScaffold } from '../identity/continuity/skills/scaffold.js'
 import { hashManagedBody, normalizeBody, reconstructVaultFile, sectionKey } from './syncAdapters/managedBlock.js'
 import { hookFilePath, readHookPayload, samePath } from './hookIo.js'
 import {
@@ -16,6 +17,15 @@ import type { PublicSkill } from './syncAdapters/shared.js'
 
 export type SyncOptions = { quiet?: boolean }
 
+/**
+ * Skills mirrored into local harnesses: every real skill (public AND private),
+ * so private skills are usable locally. The public Agent Card stays public-only
+ * (built separately via derivePublicSkillEntries). Drafts/scaffolds are skipped.
+ */
+export function selectMirrorSkills(all: readonly PublicSkill[]): PublicSkill[] {
+  return all.filter(s => !isDraftScaffold(s))
+}
+
 export async function runSync(opts: SyncOptions = {}): Promise<number> {
   const config = await loadConfig()
   if (!config?.identity) return 0
@@ -27,7 +37,7 @@ export async function runSync(opts: SyncOptions = {}): Promise<number> {
     process.stderr.write(`ethagent: could not load skills, skipping sync to avoid removing managed files (${(err as Error).message})\n`)
     return 1
   }
-  const publicSkills: PublicSkill[] = all.filter(s => s.visibility === 'public')
+  const mirrorSkills: PublicSkill[] = selectMirrorSkills(all)
 
   const targets: SyncAdapter[] = []
   for (const adapter of BUILT_IN_ADAPTERS) {
@@ -52,7 +62,7 @@ export async function runSync(opts: SyncOptions = {}): Promise<number> {
   const summaries: string[] = []
   for (const adapter of targets) {
     try {
-      const { count, skipped } = await adapter.mirror(publicSkills, context)
+      const { count, skipped } = await adapter.mirror(mirrorSkills, context)
       let summary = `${adapter.name}: ${count} skill${count === 1 ? '' : 's'}`
       if (skipped > 0) summary += `, skipped ${skipped} unmanaged`
       summaries.push(summary)

package/src/cli/syncAdapters/claude-code.ts

@@ -9,7 +9,7 @@ function claudeDir(): string {
   return path.join(os.homedir(), '.claude')
 }
 
-function claudeSkillsDir(): string {
+export function claudeSkillsDir(): string {
   return path.join(claudeDir(), 'skills')
 }
 
@@ -44,7 +44,7 @@ export async function projectMemoryMirrorsUnder(claudeRoot: string): Promise<str
 
 export const claudeCodeAdapter = {
   name: 'claude-code' as const,
-  description: 'Mirror public skills into ~/.claude/skills and inject soul/memory into ~/.claude/CLAUDE.md and the project MEMORY.md.',
+  description: 'Mirror skills (public and private) into ~/.claude/skills and inject soul/memory into ~/.claude/CLAUDE.md and the project MEMORY.md.',
   async detect(): Promise<boolean> {
     return pathExists(claudeDir())
   },

package/src/cli/syncAdapters/codex.ts

@@ -33,7 +33,7 @@ function neutralizeManagedMarkers(text: string): string {
 }
 
 function renderSkillsText(skills: EnrichedSkill[]): string {
-  if (skills.length === 0) return '_no public skills published yet._'
+  if (skills.length === 0) return '_no skills synced yet._'
   const lines: string[] = []
   for (const skill of skills) {
     lines.push(`## ${neutralizeManagedMarkers(skill.displayName ?? skill.name)}`, '')
@@ -45,7 +45,7 @@ function renderSkillsText(skills: EnrichedSkill[]): string {
 
 export const codexAdapter = {
   name: 'codex' as const,
-  description: 'Merge soul, memory, and public skill content into ~/.codex/AGENTS.md between ethagent markers.',
+  description: 'Merge soul, memory, and skill content (public and private) into ~/.codex/AGENTS.md between ethagent markers.',
   async detect(): Promise<boolean> {
     return pathExists(path.join(codexDir(), 'config.toml'))
   },

package/src/cli/syncAdapters/shared.ts

@@ -1,6 +1,15 @@
 import fs from 'node:fs/promises'
 import path from 'node:path'
 import type { SkillIndexEntry } from '../../identity/continuity/skills/types.js'
+import {
+  isReservedWindowsSegment,
+  isValidFilenameSegment,
+  isValidSegment,
+  MAX_FOLDER_DEPTH,
+} from '../../identity/continuity/skills/skillPaths.js'
+
+// Cap copied files at the same size the vault loader enforces.
+const MAX_MIRROR_FILE_BYTES = 256 * 1024
 
 export type PublicSkill = SkillIndexEntry
 
@@ -30,6 +39,39 @@ export async function pathExists(file: string): Promise<boolean> {
   try { await fs.access(file); return true } catch { return false }
 }
 
+/**
+ * Copy a vault skill folder into the harness, applying the SAME vetting the
+ * vault loader uses (skip symlinks, dotfiles, reserved Windows names, invalid
+ * segments, and oversize files) so the mirror never copies a superset of — or a
+ * symlink escaping — the vault's recognized file set.
+ */
+async function copyVettedSkillTree(srcDir: string, destDir: string, depth = 0): Promise<void> {
+  if (depth > MAX_FOLDER_DEPTH) return
+  await fs.mkdir(destDir, { recursive: true })
+  let entries: import('node:fs').Dirent[]
+  try {
+    entries = await fs.readdir(srcDir, { withFileTypes: true })
+  } catch {
+    return
+  }
+  for (const ent of entries) {
+    if (ent.isSymbolicLink()) continue
+    if (ent.name.startsWith('.')) continue
+    if (isReservedWindowsSegment(ent.name)) continue
+    const srcPath = path.join(srcDir, ent.name)
+    const destPath = path.join(destDir, ent.name)
+    if (ent.isDirectory()) {
+      if (!isValidSegment(ent.name)) continue
+      await copyVettedSkillTree(srcPath, destPath, depth + 1)
+    } else if (ent.isFile()) {
+      if (!isValidFilenameSegment(ent.name)) continue
+      const stat = await fs.stat(srcPath).catch(() => null)
+      if (!stat || stat.size > MAX_MIRROR_FILE_BYTES) continue
+      await fs.copyFile(srcPath, destPath)
+    }
+  }
+}
+
 export async function mirrorAsSkillFolders(
   root: string,
   skills: PublicSkill[],
@@ -41,16 +83,25 @@ export async function mirrorAsSkillFolders(
   let skipped = 0
   for (const skill of skills) {
     const targetDir = path.join(root, skill.name)
-    const targetFile = path.join(targetDir, 'SKILL.md')
     const exists = await pathExists(targetDir)
     const isOurs = manifest.skills.includes(skill.name)
     if (exists && !isOurs) { skipped++; continue }
+    const srcDir = path.dirname(skill.absolutePath)
+    const tmpDir = path.join(root, `.${skill.name}.ethagent-tmp`)
     try {
-      const body = await fs.readFile(skill.absolutePath, 'utf8')
-      await fs.mkdir(targetDir, { recursive: true })
-      await fs.writeFile(targetFile, body, 'utf8')
+      // Stage the new copy in a temp sibling, then swap it in. This keeps the
+      // existing managed copy intact if the copy fails (no destructive
+      // rm-before-write window), and refreshes the whole folder (scripts/,
+      // assets/), dropping files removed upstream.
+      await fs.rm(tmpDir, { recursive: true, force: true })
+      await copyVettedSkillTree(srcDir, tmpDir)
+      await fs.rm(targetDir, { recursive: true, force: true })
+      await fs.rename(tmpDir, targetDir)
       owned.push(skill.name)
-    } catch {}
+    } catch (err) {
+      await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => null)
+      process.stderr.write(`ethagent: failed to mirror skill "${skill.name}": ${(err as Error).message}\n`)
+    }
   }
   const keep = new Set<string>(owned)
   for (const name of manifest.skills) if (incoming.has(name)) keep.add(name)

package/src/identity/continuity/skills/loadSkills.ts

@@ -517,7 +517,7 @@ async function pathExists(file: string): Promise<boolean> {
   }
 }
 
-const DEFAULT_PASTED_VISIBILITY: SkillVisibility = 'public'
+const DEFAULT_SKILL_VISIBILITY: SkillVisibility = 'private'
 const LEGACY_DISCOVERABLE_RE = /^\s*visibility\s*:\s*['"]?discoverable['"]?\s*$/im
 
 async function ensureSkillVisibilityWritten(skillFile: string, raw: string): Promise<string> {
@@ -531,7 +531,7 @@ async function ensureSkillVisibilityWritten(skillFile: string, raw: string): Pro
   if (LEGACY_DISCOVERABLE_RE.test(raw)) {
     target = 'private'
   } else if (parsed.frontmatter.visibility === undefined) {
-    target = DEFAULT_PASTED_VISIBILITY
+    target = DEFAULT_SKILL_VISIBILITY
   }
   if (target === null) return raw
   const next = rewriteVisibility(raw, target)
@@ -587,7 +587,7 @@ function buildIndexEntry(args: {
   const derivedName = folder || segments.join('/')
   const fm = args.parsed.frontmatter
   const description = pickDescription(fm.description, args.parsed.body)
-  const visibility: SkillVisibility = fm.visibility ?? DEFAULT_PASTED_VISIBILITY
+  const visibility: SkillVisibility = fm.visibility ?? DEFAULT_SKILL_VISIBILITY
   return {
     name: derivedName,
     ...(fm.name ? { displayName: fm.name } : {}),

package/src/identity/continuity/skills/scaffold.ts

@@ -5,7 +5,7 @@ export type SkillScaffoldArgs = {
   visibility?: SkillVisibility
 }
 
-export function defaultSkillScaffold({ name, visibility = 'public' }: SkillScaffoldArgs): string {
+export function defaultSkillScaffold({ name, visibility = 'private' }: SkillScaffoldArgs): string {
   return [
     '---',
     `name: ${name}`,

package/src/identity/manager/continuity/skills/NewSkillVisibilityScreen.tsx

@@ -22,7 +22,7 @@ export const NewSkillVisibilityScreen: React.FC<NewSkillVisibilityScreenProps> =
 }) => (
   <Surface
     title={`Visibility · ${name}`}
-    subtitle="Public is the default."
+    subtitle="Private is the default."
     footer={footer}
   >
     {error && (
@@ -39,7 +39,7 @@ export const NewSkillVisibilityScreen: React.FC<NewSkillVisibilityScreenProps> =
           { value: 'back', label: 'Back', role: 'utility' },
         ]}
         hintLayout="inline"
-        initialIndex={1}
+        initialIndex={0}
         onSubmit={choice => {
           if (choice === 'back') return onCancel()
           return onSelect(choice)

package/src/identity/manager/useController.ts

@@ -2,7 +2,7 @@ import { useEffect, useReducer, useState } from 'react'
 import type { EthagentConfig, EthagentIdentity } from '../../storage/config.js'
 import { setTokenIdentity } from '../../storage/identity.js'
 import type { BrowserWalletReady } from '../wallet/browserWallet.js'
-import { registryConfigFromConfig } from '../registry/registryConfig.js'
+import { resolveRegistryForIdentity as resolveRegistryForIdentityFromConfig } from '../registry/registryConfig.js'
 import type { Erc8004RegistryConfig } from '../registry/erc8004.js'
 import {
   hasPinataJwt,
@@ -94,18 +94,8 @@ export function useIdentityManagerController({
     }
   }
 
-  const resolveRegistryForIdentity = (target: EthagentIdentity): Erc8004RegistryConfig | null => {
-    const resolution = registryConfigFromConfig(config)
-    if (target.chainId && target.identityRegistryAddress) {
-      return {
-        chainId: target.chainId,
-        rpcUrl: target.rpcUrl ?? resolution.defaultRpcUrl,
-        identityRegistryAddress: target.identityRegistryAddress as `0x${string}`,
-      }
-    }
-    if (resolution.config) return resolution.config
-    return null
-  }
+  const resolveRegistryForIdentity = (target: EthagentIdentity): Erc8004RegistryConfig | null =>
+    resolveRegistryForIdentityFromConfig(target, config)
 
   const completeTokenIdentity = async (nextIdentity: EthagentIdentity, message: string, source?: IdentityCompletionSource): Promise<void> => {
     if (mode === 'first-run' || !config) {

package/src/identity/registry/registryConfig.ts

@@ -1,4 +1,4 @@
-import type { EthagentConfig, SelectableNetwork } from '../../storage/config.js'
+import type { EthagentConfig, EthagentIdentity, SelectableNetwork } from '../../storage/config.js'
 import {
   chainIdForNetwork,
   DEFAULT_ERC8004_CHAIN_ID,
@@ -67,3 +67,22 @@ export function registryConfigFromConfig(config?: EthagentConfig): RegistryResol
     throw err
   }
 }
+
+// Resolve the registry an existing identity should operate against: prefer the
+// identity's own chain + registry address (filling in a default RPC when it has
+// none), otherwise fall back to the config-derived registry. Pure function of
+// (identity, config) so both the TUI controller and headless commands share it.
+export function resolveRegistryForIdentity(
+  identity: Pick<EthagentIdentity, 'chainId' | 'identityRegistryAddress' | 'rpcUrl'>,
+  config?: EthagentConfig,
+): Erc8004RegistryConfig | null {
+  const resolution = registryConfigFromConfig(config)
+  if (identity.chainId && identity.identityRegistryAddress) {
+    return {
+      chainId: identity.chainId,
+      rpcUrl: identity.rpcUrl ?? resolution.defaultRpcUrl,
+      identityRegistryAddress: identity.identityRegistryAddress as `0x${string}`,
+    }
+  }
+  return resolution.config
+}