ethagent 3.1.2 → 3.3.0

package/README.md

@@ -5,8 +5,8 @@ A privacy-first AI agent with a portable Ethereum identity.
 Switch providers or machines and the AI agent you customized stays behind. `ethagent` ties the agent to a wallet you own, so its soul, memory, and skills follow you across providers, machines, and models.
 
 - **Portable.** The ERC-8004 token is the agent's durable identity. Use the ENS name as a readable handle, or the token ID plus chain as the permanent reference, to restore the same agent anywhere.
-- **Private.** Soul and memory are encrypted before they are pinned to IPFS. The wallet signature used to unlock them stays local and never submits a transaction, spends funds, or grants token approval.
-- **Public.** The agent URI points to plain JSON for the Agent Card and public skills, so other agents can discover capabilities through ERC-8004 and IPFS.
+- **Private.** Soul, memory, and skills are encrypted before they are pinned to IPFS. The wallet signature used to unlock them stays local and never submits a transaction, spends funds, or grants token approval.
+- **Public.** The agent URI points to a public metadata payload on IPFS that includes the Agent Card, so other agents can discover the agent's capabilities through ERC-8004.
 
 <details>
 <summary><strong>Glossary</strong> (click to expand)</summary>
@@ -16,9 +16,9 @@ Switch providers or machines and the AI agent you customized stays behind. `etha
 | Owner Wallet | Holds and controls the ERC-8004 agent token. Signs custody changes and, in Simple custody, every URI rotation. |
 | Operator Wallet | Additional wallet authorized to rotate the onchain URI on behalf of the owner. Used in Advanced custody. Never receives token approval. |
 | Vault | Immutable per-agent custody contract used in Advanced custody. Holds at most one ERC-8004 token. |
-| Snapshot | Encrypted bundle of SOUL.md, MEMORY.md, and session state. Pinned to IPFS; decrypts only against the owner wallet's signature. |
-| Agent URI | IPFS URI stored in the ERC-8004 `tokenURI`. Resolves to the agent's published metadata. |
-| Agent Card | Public JSON describing the agent: name, description, capabilities, and skills. Other agents fetch it for discovery. |
+| Snapshot | Encrypted bundle of SOUL.md, MEMORY.md, the skills/ tree, and session state. Pinned to IPFS; decrypts only against the owner wallet's signature. |
+| Agent URI | IPFS URI stored in the ERC-8004 `tokenURI`. Resolves to a public metadata payload that references the Agent Card. |
+| Agent Card | Public JSON describing the agent: name, description, capabilities, and skills. Pinned on IPFS and linked from the agent URI; other agents fetch it for discovery. |
 
 </details>
 
@@ -48,12 +48,12 @@ Once running:
 
 The Identity Hub manages everything portable about the agent:
 
-- **Public Profile** edits name, description, icon, and the Agent Card.
+- **Public Profile** edits name, description, and icon: what other agents see in the Agent Card.
 - **ENS Name** links the agent to a subdomain under a parent name the owner wallet controls.
 - **Custody Mode** switches between Simple and Advanced by depositing the token into its Vault or unwrapping it back out.
-- **Prepare Transfer** stages a dual-wallet snapshot before sending the token externally.
+- **Prepare Transfer** stages a dual-wallet snapshot so the receiver can restore the agent after the token moves externally.
 - **Refetch Latest** pulls the most recent published snapshot back to local files.
-- **Load Agent** accepts either an ENS name or a bare token ID, and loads any agent owned by or linked to the connected wallet.
+- **Switch Agent** accepts either an ENS name or a bare token ID, and loads any agent owned by or linked to the connected wallet.
 
 The menu surfaces drift automatically. Token ownership, vault state, ENS record alignment, and pending URI rotations are checked against the live chain when the menu opens.
 
@@ -61,16 +61,15 @@ Every agent has a continuity directory at `~/.ethagent/continuity`.
 
 ## Continuity
 
-Each agent's continuity directory holds a small set of files. Private files are encrypted before they ever reach IPFS; public files are plain JSON so other agents can discover what the agent does.
+Each agent's continuity directory holds a small set of private files. They are encrypted before they ever reach IPFS.
 
 | File | Visibility | Purpose |
 | --- | --- | --- |
 | `SOUL.md` | Private | Soul, boundaries, standing instructions, and identity framing. |
 | `MEMORY.md` | Private | Durable preferences, project context, decisions, and operating notes. |
-| `skills/` | Mixed | Skill folders. Each skill is private, discoverable, or public; new skills default to discoverable. |
-| `skills.json` | Public | Machine-readable capabilities derived from public skills. |
+| `skills/` | Private | Skill folders. The SKILL.md body never leaves your machine. The visibility flag only controls whether the skill's name and description get listed in the Agent Card. New skills default to public. |
 
-`SOUL.md`, `MEMORY.md`, and each `SKILL.md` are plain Markdown you edit through the Identity Hub under Continuity. Skills carry extra metadata: the frontmatter at the top of each `SKILL.md` (name, description, when_to_use, visibility, tags) tells the agent when to load it. Visibility is `private` (local-only, never shared), `discoverable` (indexed in `skills.json` so other agents can find it), or `public` (indexed and surfaced on the Agent Card).
+`SOUL.md`, `MEMORY.md`, and each `SKILL.md` are plain Markdown you edit through the Identity Hub under Continuity. Skill frontmatter (name, description, when_to_use, visibility, tags) tells the agent when to load it. The body stays local; `visibility: public` lists the name and description in the Agent Card.
 
 - **Save Snapshot Now** encrypts the private files, pins them to IPFS, and rotates the onchain pointer to the new CID.
 - **Refetch Latest** reads the pointer back, signs the decrypt challenge with your wallet, and overwrites local files from the snapshot.
@@ -103,7 +102,7 @@ Save the token ID + network somewhere safe. ENS records can be cleared and rebui
 - Sender signs snapshot access, receiver signs restore access.
 - Sender publishes the snapshot pointer to the agent URI.
 - The actual transfer happens externally afterwards, in whichever wallet UI you prefer.
-- Once the token has moved, the receiver opens **Load Agent** with the receiving wallet and restores the same agent from the published snapshot.
+- Once the token has moved, the receiver opens **Switch Agent** with the receiving wallet and restores the same agent from the published snapshot.
 
 The token transfer flow prepares decrypt access and agent URI pointers only. It does not initiate the transfer and does not request approval over the token.
 
@@ -136,8 +135,8 @@ Vision support is available on:
 
 ## Privacy
 
-- **Public:** token ownership, the agent URI payload, public discovery files, and IPFS CIDs.
-- **Private:** plaintext `SOUL.md`, plaintext `MEMORY.md`, sessions, prompt history, API keys, local permissions, and the wallet signatures used for decryption.
+- **Public:** token ownership, the agent URI, the Agent Card it references, and IPFS CIDs.
+- **Private:** plaintext `SOUL.md`, plaintext `MEMORY.md`, the local skills/ tree, sessions, prompt history, API keys, local permissions, and the wallet signatures used for decryption.
 - Snapshots use a wallet signature as unlock material. The signature does not submit a transaction, spend funds, or grant token approval.
 - The transfer flow writes a snapshot pointer and stops; it never approves or moves the token.
 - `ethagent reset` deletes local ethagent data from the current machine while preserving installed local model assets. It does not burn or transfer tokens, remove public IPFS content, or mutate the onchain agent URI. Run **Save Snapshot Now** before resetting if local edits should become the recoverable state.
@@ -150,7 +149,7 @@ Vision support is available on:
 | Model | Cloud provider or local GGUF runner. |
 | Identity | ERC-8004 token owned by the wallet. |
 | Continuity | Private files encrypted before IPFS pinning. |
-| Discovery | Public `skills.json`, Agent Card, services, and the current agent URI payload. |
+| Discovery | The agent URI and the Agent Card it points to. |
 | Recovery | Refetch the current agent URI, decrypt the latest snapshot, and restore local files. |
 
 The ERC-8004 token is the durable handle. The machine, model, and local session all change around it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ethagent",
-  "version": "3.1.2",
+  "version": "3.3.0",
   "description": "A privacy-first AI agent with a portable Ethereum identity",
   "type": "module",
   "main": "bin/ethagent.js",

package/src/chat/ChatScreen.tsx

@@ -44,7 +44,9 @@ import {
   shouldConfirmContextUsage,
   type ContextUsage,
 } from '../runtime/compaction.js'
-import { saveConfig } from '../storage/config.js'
+import { fetchLlamaCppContextSize, onLlamaCppContextSizeChange, setCachedLlamaCppContextSize } from '../models/llamacpp.js'
+import { llamaCppServerHostFromBaseUrl } from '../models/llamacppPreflight.js'
+import { localProviderBaseUrlFor, saveConfig } from '../storage/config.js'
 import { getCwd as getRuntimeCwd, setCwd as setRuntimeCwd, syncCwdFromProcess } from '../runtime/cwd.js'
 import { executeToolWithPermissions } from '../runtime/toolExecution.js'
 import { nextSessionMode, sessionModeLabel, type PermissionMode, type SessionMode } from '../runtime/sessionMode.js'
@@ -309,7 +311,7 @@ export const ChatScreen: React.FC<ChatScreenProps> = ({ config: initialConfig, o
       {
         role: 'progress',
         id: progressRowId,
-        title: kind === 'plan' ? 'summarizing plan context' : 'compacting conversation',
+        title: kind === 'plan' ? 'summarizing plan context' : 'Compacting conversation',
         progress: 0,
         status: state.stage,
         suffix: 'esc to cancel',
@@ -449,6 +451,22 @@ export const ChatScreen: React.FC<ChatScreenProps> = ({ config: initialConfig, o
     [],
   )
 
+  useEffect(() => {
+    if (config.provider !== 'llamacpp') return
+    const host = llamaCppServerHostFromBaseUrl(localProviderBaseUrlFor('llamacpp', config.baseUrl))
+    void fetchLlamaCppContextSize(host)
+    const unsubscribe = onLlamaCppContextSizeChange(() => {
+      refreshVisibleStats(
+        sessionMessagesRef.current,
+        providerRef.current.supportsTools,
+        cwdRef.current,
+        configRef.current,
+        modeRef.current,
+      )
+    })
+    return unsubscribe
+  }, [config.provider, config.baseUrl, refreshVisibleStats])
+
   const warnIfContextPressure = useCallback(
     (usage: ContextUsage, configForUsage: EthagentConfig) => {
       if (!shouldConfirmContextUsage(usage, CONTEXT_CONFIRM_PERCENT)) return
@@ -880,6 +898,11 @@ export const ChatScreen: React.FC<ChatScreenProps> = ({ config: initialConfig, o
           pendingPlanRef.current = planCandidate
           setPendingPlan(planCandidate)
         },
+        onContextExceeded: ({ contextLimit }) => {
+          setCachedLlamaCppContextSize(contextLimit)
+          pushNote('Context full. Compacting transcript. Re-send your message once compaction finishes.', 'dim')
+          void runCompaction()
+        },
         pendingAssistantTextRef,
         pendingThinkingTextRef,
         streamFlushTimerRef,

package/src/chat/chatTurnOrchestrator.ts

@@ -56,6 +56,7 @@ export type TurnOrchestratorContext = {
   applySessionRule: (rule?: SessionPermissionRule, persistRule?: boolean) => Promise<void>
   preflightProvider?: () => Promise<{ ok: true } | { ok: false; message: string }>
   onPlanReady?: (plan: string) => void
+  onContextExceeded?: (info: { contextLimit: number }) => void
   pendingAssistantTextRef: MutableRef<string | null>
   pendingThinkingTextRef: MutableRef<string | null>
   streamFlushTimerRef: MutableRef<ReturnType<typeof setTimeout> | null>
@@ -89,6 +90,7 @@ export async function runStreamingTurn(
     applySessionRule,
     preflightProvider,
     onPlanReady,
+    onContextExceeded,
     pendingAssistantTextRef,
     pendingThinkingTextRef,
     streamFlushTimerRef,
@@ -311,6 +313,7 @@ export async function runStreamingTurn(
         nowIso,
         mode,
         onPlanReady,
+        onContextExceeded,
         turnId: activeCheckpoint.turnId,
         model: getConfig().model,
         onFinishedNormally: () => { finishedNormally = true },
@@ -356,6 +359,7 @@ type EventHandlerContext = {
   nowIso: () => string
   mode: SessionMode
   onPlanReady?: (plan: string) => void
+  onContextExceeded?: (info: { contextLimit: number }) => void
   turnId: string
   model: string
   onFinishedNormally: () => void
@@ -365,6 +369,13 @@ function isCancelledEvent(ev: TurnEvent): boolean {
   return ev.type === 'cancelled'
 }
 
+export function parseContextExceededLimit(message: string): number | null {
+  const match = /exceeds the available context size \((\d+)\s*tokens?\)/i.exec(message)
+  if (!match) return null
+  const limit = Number.parseInt(match[1]!, 10)
+  return Number.isFinite(limit) && limit > 0 ? limit : null
+}
+
 async function handleEvent(ev: TurnEvent, ctx: EventHandlerContext): Promise<void> {
   switch (ev.type) {
     case 'iteration_start': {
@@ -453,6 +464,12 @@ async function handleEvent(ev: TurnEvent, ctx: EventHandlerContext): Promise<voi
       return
     }
     case 'error': {
+      const contextLimit = parseContextExceededLimit(ev.message)
+      if (contextLimit !== null && ctx.onContextExceeded) {
+        ctx.discardStreamingRows()
+        ctx.onContextExceeded({ contextLimit })
+        return
+      }
       ctx.pushNote(ev.message, 'error')
       if (ev.discardAssistant) {
         ctx.discardStreamingRows()

package/src/identity/continuity/history.ts

@@ -6,7 +6,7 @@ import type { ContinuityFiles } from './envelope.js'
 import {
   continuityVaultRef,
   ensureContinuityVault,
-  writePublicSkillsFile,
+  writeAgentCardFile,
   writeContinuityFiles,
   type PrivateContinuityFile,
 } from './storage.js'
@@ -20,7 +20,7 @@ type PrivateContinuityHistorySnapshot = {
   existedBefore: boolean
   previousContent: string
   previousFiles?: ContinuityFiles
-  previousPublicSkills?: string
+  previousAgentCard?: string
   changeSummary: string
   identity: {
     address: string
@@ -42,7 +42,7 @@ type RecordPrivateContinuityHistoryInput = {
   existedBefore: boolean
   previousContent: string
   previousFiles?: ContinuityFiles
-  previousPublicSkills?: string
+  previousAgentCard?: string
   changeSummary: string
   createdAt?: string
   sessionId?: string
@@ -69,7 +69,7 @@ export async function recordPrivateContinuityHistorySnapshot(
     existedBefore: input.existedBefore,
     previousContent: input.previousContent,
     ...(input.previousFiles ? { previousFiles: input.previousFiles } : {}),
-    ...(input.previousPublicSkills !== undefined ? { previousPublicSkills: input.previousPublicSkills } : {}),
+    ...(input.previousAgentCard !== undefined ? { previousAgentCard: input.previousAgentCard } : {}),
     changeSummary: input.changeSummary,
     identity: {
       address: input.identity.address,
@@ -125,8 +125,8 @@ export async function restorePrivateContinuityHistorySnapshot(
 
   if (snapshot.previousFiles) {
     await writeContinuityFiles(identity, snapshot.previousFiles)
-    if (snapshot.previousPublicSkills !== undefined) {
-      await writePublicSkillsFile(identity, snapshot.previousPublicSkills)
+    if (snapshot.previousAgentCard !== undefined) {
+      await writeAgentCardFile(identity, snapshot.previousAgentCard)
     }
     return snapshot
   }
@@ -137,8 +137,8 @@ export async function restorePrivateContinuityHistorySnapshot(
   } else {
     await fs.rm(snapshot.filePath, { force: true })
   }
-  if (snapshot.previousPublicSkills !== undefined) {
-    await writePublicSkillsFile(identity, snapshot.previousPublicSkills)
+  if (snapshot.previousAgentCard !== undefined) {
+    await writeAgentCardFile(identity, snapshot.previousAgentCard)
   }
   return snapshot
 }

package/src/identity/continuity/publicSkills.ts

@@ -68,29 +68,7 @@ export function defaultPublicSkillsProfile(identity: EthagentIdentity): PublicSk
     version: '1.0.0',
     ...(agentWallet ? { agentWallet } : {}),
     ...(imageUrl ? { imageUrl } : {}),
-    skills: [
-      {
-        id: 'software-engineering',
-        name: 'Software engineering',
-        description: 'Read code, plan implementations, debug failures, refactor safely, and run focused tests.',
-        inputModes: ['text/markdown'],
-        outputModes: ['text/markdown'],
-      },
-      {
-        id: 'workspace-tools',
-        name: 'Workspace tools',
-        description: 'Use permissioned local file, shell, clipboard, and MCP tools for project work.',
-        inputModes: ['text/markdown'],
-        outputModes: ['text/markdown', 'application/json'],
-      },
-      {
-        id: 'ethereum-identity',
-        name: 'Ethereum identity',
-        description: 'Represent a portable ERC-8004 agent identity controlled by the owner wallet.',
-        inputModes: ['text/markdown'],
-        outputModes: ['text/markdown', 'application/json'],
-      },
-    ],
+    skills: [],
   }
 }
 
@@ -103,7 +81,7 @@ export function appendPublicSkillEntries(
   const appended: PublicSkill[] = []
   const usedIds = new Set(baselineIds)
   for (const entry of entries) {
-    if (entry.visibility !== 'public' && entry.visibility !== 'discoverable') continue
+    if (entry.visibility !== 'public') continue
     const id = uniqueSkillId(entry.name, usedIds)
     usedIds.add(id)
     appended.push({
@@ -129,61 +107,6 @@ function uniqueSkillId(base: string, used: Set<string>): string {
   return `${slug}-${i}`
 }
 
-export function renderPublicSkillsJson(profile: PublicSkillsProfile): string {
-  const inputModes = unique(profile.skills.flatMap(skill => skill.inputModes))
-  const outputModes = unique(profile.skills.flatMap(skill => skill.outputModes))
-  const summary = {
-    schema: 'ethagent.public-skills.v1',
-    producer: ETHAGENT_PRODUCER,
-    ...(profile.agentWallet ? { agent_wallet: profile.agentWallet } : {}),
-    visibility: 'public',
-    name: profile.name,
-    description: profile.description,
-    version: profile.version,
-    ...(profile.imageUrl ? { imageUrl: profile.imageUrl } : {}),
-    inputModes,
-    outputModes,
-    boundary: 'Public discovery only. This is not executable code, private memory, or a skill installation manifest.',
-    capabilities: {
-      softwareEngineering: true,
-      workspaceTools: 'permissioned',
-      mcp: true,
-      streaming: true,
-      ethereumIdentity: 'ERC-8004',
-      encryptedContinuity: true,
-    },
-    delegation: {
-      bestFor: [
-        'code reading',
-        'implementation planning',
-        'debugging',
-        'refactors',
-        'tests',
-        'workspace automation',
-      ],
-      requiresApprovalFor: [
-        'workspace edits',
-        'shell commands',
-        'private continuity changes',
-      ],
-    },
-    privacy: {
-      publicOnly: true,
-      includesPrivateMemory: false,
-      includesExecutableCode: false,
-      includesSecrets: false,
-    },
-    skills: profile.skills.map(skill => ({
-      id: skill.id,
-      name: skill.name,
-      description: skill.description,
-      inputModes: skill.inputModes,
-      outputModes: skill.outputModes,
-    })),
-  }
-  return `${JSON.stringify(summary, null, 2)}\n`
-}
-
 export function createAgentCard(profile: PublicSkillsProfile, url?: string): AgentCard {
   const inputModes = unique(profile.skills.flatMap(skill => skill.inputModes))
   const outputModes = unique(profile.skills.flatMap(skill => skill.outputModes))
@@ -192,7 +115,7 @@ export function createAgentCard(profile: PublicSkillsProfile, url?: string): Age
     description: profile.description,
     version: profile.version,
     ...(profile.agentWallet ? { agent_wallet: profile.agentWallet } : {}),
-    protocolVersion: '0.2.6',
+    protocolVersion: '0.3.0',
     ...(url ? { url } : {}),
     ...(profile.imageUrl ? { image: profile.imageUrl } : {}),
     defaultInputModes: inputModes.length ? inputModes : ['text/markdown'],

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

@@ -14,7 +14,8 @@ const SUPPORTED_KEYS = new Set([
   'visibility',
 ])
 
-const VISIBILITY_VALUES: SkillVisibility[] = ['private', 'public', 'discoverable']
+const VISIBILITY_VALUES: SkillVisibility[] = ['private', 'public']
+const LEGACY_VISIBILITY_TO_PRIVATE = new Set(['discoverable'])
 
 export type ParsedSkillFile = {
   frontmatter: SkillFrontmatter
@@ -104,6 +105,8 @@ function assignKey(out: SkillFrontmatter, key: keyof SkillFrontmatter, rawValue:
     const literal = parseScalar(stripped).toLowerCase()
     if ((VISIBILITY_VALUES as string[]).includes(literal)) {
       out.visibility = literal as SkillVisibility
+    } else if (LEGACY_VISIBILITY_TO_PRIVATE.has(literal)) {
+      out.visibility = 'private'
     }
     return
   }

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

@@ -215,8 +215,11 @@ export async function loadSkillsTree(identity: EthagentIdentity): Promise<Contin
       const rel = `${skillEnt.name}/${file.relativePath}`
       if (!isValidSkillFilePath(rel)) continue
       if (file.sizeBytes > MAX_SKILL_FILE_BYTES) continue
-      const content = await fs.readFile(file.absolutePath, 'utf8').catch(() => null)
-      if (content === null) continue
+      const rawContent = await fs.readFile(file.absolutePath, 'utf8').catch(() => null)
+      if (rawContent === null) continue
+      const content = file.relativePath === SKILL_FILE_NAME
+        ? await ensureSkillVisibilityWritten(file.absolutePath, rawContent)
+        : rawContent
       tree[rel] = content
       totalFiles++
     }
@@ -359,7 +362,12 @@ export async function migrateLegacySkillFiles(skillsRoot: string): Promise<void>
     return
   }
   for (const topEnt of topDirents) {
-    if (!topEnt.isDirectory() || topEnt.isSymbolicLink()) continue
+    if (topEnt.isSymbolicLink()) continue
+    if (topEnt.isFile() && /\.md$/i.test(topEnt.name)) {
+      await adoptBareSkillFile(skillsRoot, topEnt.name)
+      continue
+    }
+    if (!topEnt.isDirectory()) continue
     if (!isValidSegment(topEnt.name)) continue
     const topDir = path.join(skillsRoot, topEnt.name)
     let children: import('node:fs').Dirent[]
@@ -403,6 +411,39 @@ export async function migrateLegacySkillFiles(skillsRoot: string): Promise<void>
   }
 }
 
+async function adoptBareSkillFile(skillsRoot: string, fileName: string): Promise<void> {
+  const sourcePath = path.join(skillsRoot, fileName)
+  let baseName: string
+  if (/^SKILL\.md$/i.test(fileName)) {
+    let parsedName: string | undefined
+    try {
+      const raw = await fs.readFile(sourcePath, 'utf8')
+      const parsed = parseSkillFile(raw)
+      const fmName = parsed.frontmatter.name?.trim()
+      if (fmName && isValidSegment(fmName)) parsedName = fmName
+    } catch {
+    }
+    baseName = parsedName ?? 'imported-skill'
+  } else {
+    const slug = fileName.replace(/\.md$/i, '')
+    if (!isValidSegment(slug)) return
+    baseName = slug
+  }
+  let target: string
+  try {
+    target = await chooseFlatTarget(skillsRoot, baseName)
+  } catch {
+    return
+  }
+  const targetDir = path.join(skillsRoot, target)
+  const targetFile = path.join(targetDir, SKILL_FILE_NAME)
+  try {
+    await fs.mkdir(targetDir, { recursive: true, mode: 0o700 })
+    await fs.rename(sourcePath, targetFile)
+  } catch {
+  }
+}
+
 async function chooseFlatTarget(skillsRoot: string, base: string): Promise<string> {
   let candidate = base
   let suffix = 2
@@ -476,6 +517,32 @@ async function pathExists(file: string): Promise<boolean> {
   }
 }
 
+const DEFAULT_PASTED_VISIBILITY: SkillVisibility = 'public'
+const LEGACY_DISCOVERABLE_RE = /^\s*visibility\s*:\s*['"]?discoverable['"]?\s*$/im
+
+async function ensureSkillVisibilityWritten(skillFile: string, raw: string): Promise<string> {
+  let parsed: { frontmatter: import('./types.js').SkillFrontmatter; body: string }
+  try {
+    parsed = parseSkillFile(raw)
+  } catch {
+    return raw
+  }
+  let target: SkillVisibility | null = null
+  if (LEGACY_DISCOVERABLE_RE.test(raw)) {
+    target = 'private'
+  } else if (parsed.frontmatter.visibility === undefined) {
+    target = DEFAULT_PASTED_VISIBILITY
+  }
+  if (target === null) return raw
+  const next = rewriteVisibility(raw, target)
+  if (next === raw) return raw
+  try {
+    await atomicWriteText(skillFile, next, { mode: 0o600 })
+  } catch {
+  }
+  return next
+}
+
 async function collectSkillEntries(root: string): Promise<SkillIndexEntry[]> {
   const out: SkillIndexEntry[] = []
   let topDirents: import('node:fs').Dirent[]
@@ -493,7 +560,8 @@ async function collectSkillEntries(root: string): Promise<SkillIndexEntry[]> {
       const stat = await fs.stat(skillFile)
       if (!stat.isFile()) continue
       if (stat.size > MAX_SKILL_FILE_BYTES) continue
-      const raw = await fs.readFile(skillFile, 'utf8')
+      const rawInitial = await fs.readFile(skillFile, 'utf8')
+      const raw = await ensureSkillVisibilityWritten(skillFile, rawInitial)
       const parsed = parseSkillFile(raw)
       const relativePath = `${skillEnt.name}/${SKILL_FILE_NAME}`
       out.push(buildIndexEntry({
@@ -519,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 ?? 'discoverable'
+  const visibility: SkillVisibility = fm.visibility ?? DEFAULT_PASTED_VISIBILITY
   return {
     name: derivedName,
     ...(fm.name ? { displayName: fm.name } : {}),

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

@@ -2,8 +2,9 @@ import { atomicWriteText } from '../../../storage/atomicWrite.js'
 import type { EthagentIdentity } from '../../../storage/config.js'
 import {
   appendPublicSkillEntries,
+  createAgentCard,
   defaultPublicSkillsProfile,
-  renderPublicSkillsJson,
+  serializeAgentCard,
 } from '../publicSkills.js'
 import { ensureContinuityVault, ensureTrailingNewline, readOrDefault } from '../storage/files.js'
 import { listSkills } from './loadSkills.js'
@@ -11,22 +12,22 @@ import type { SkillIndexEntry } from './types.js'
 
 export async function derivePublicSkillEntries(identity: EthagentIdentity): Promise<SkillIndexEntry[]> {
   const entries = await listSkills(identity)
-  return entries.filter(entry => entry.visibility === 'public' || entry.visibility === 'discoverable')
+  return entries.filter(entry => entry.visibility === 'public')
 }
 
-export async function renderPublicSkillsJsonForIdentity(identity: EthagentIdentity): Promise<string> {
+export async function renderAgentCardJsonForIdentity(identity: EthagentIdentity): Promise<string> {
   const publicEntries = await derivePublicSkillEntries(identity)
   const profile = appendPublicSkillEntries(defaultPublicSkillsProfile(identity), publicEntries)
-  return renderPublicSkillsJson(profile)
+  return serializeAgentCard(createAgentCard(profile))
 }
 
-export async function syncPublicSkillsManifest(identity: EthagentIdentity): Promise<string> {
+export async function syncAgentCardManifest(identity: EthagentIdentity): Promise<string> {
   const ref = await ensureContinuityVault(identity)
-  const next = await renderPublicSkillsJsonForIdentity(identity)
-  const current = await readOrDefault(ref.publicSkillsPath, '')
+  const next = await renderAgentCardJsonForIdentity(identity)
+  const current = await readOrDefault(ref.agentCardPath, '')
   if (current === ensureTrailingNewline(next) || current === next) {
     return current
   }
-  await atomicWriteText(ref.publicSkillsPath, ensureTrailingNewline(next), { mode: 0o644 })
+  await atomicWriteText(ref.agentCardPath, ensureTrailingNewline(next), { mode: 0o644 })
   return next
 }

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

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

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

@@ -1,4 +1,4 @@
-export type SkillVisibility = 'private' | 'public' | 'discoverable'
+export type SkillVisibility = 'private' | 'public'
 
 export type SkillFrontmatter = {
   name?: string

package/src/identity/continuity/snapshots.ts

@@ -17,7 +17,6 @@ type PublishedContinuitySnapshot = {
   metadataCid?: string
   agentUri?: string
   txHash?: string
-  publicSkillsCid?: string
   agentCardCid?: string
   contentHashes?: ContinuitySnapshotContentHashes
   label: string
@@ -55,8 +54,7 @@ export async function recordPublishedContinuitySnapshot(
     ...(backup.metadataCid ? { metadataCid: backup.metadataCid } : {}),
     ...(backup.agentUri ? { agentUri: backup.agentUri } : {}),
     ...(backup.txHash ? { txHash: backup.txHash } : {}),
-    ...(input.identity.publicSkills?.cid ? { publicSkillsCid: input.identity.publicSkills.cid } : {}),
-    ...(input.identity.publicSkills?.agentCardCid ? { agentCardCid: input.identity.publicSkills.agentCardCid } : {}),
+    ...(input.identity.agentCard?.cid ? { agentCardCid: input.identity.agentCard.cid } : {}),
     ...(contentHashes ? { contentHashes } : {}),
     label: input.label ?? 'published encrypted snapshot',
     identity: {
@@ -129,7 +127,6 @@ function enrichPublishedSnapshot(
     ...(snapshot.metadataCid ? {} : current.metadataCid ? { metadataCid: current.metadataCid } : {}),
     ...(snapshot.agentUri ? {} : current.agentUri ? { agentUri: current.agentUri } : {}),
     ...(snapshot.txHash ? {} : current.txHash ? { txHash: current.txHash } : {}),
-    ...(snapshot.publicSkillsCid ? {} : current.publicSkillsCid ? { publicSkillsCid: current.publicSkillsCid } : {}),
     ...(snapshot.agentCardCid ? {} : current.agentCardCid ? { agentCardCid: current.agentCardCid } : {}),
     ...(snapshot.contentHashes ? {} : current.contentHashes ? { contentHashes: current.contentHashes } : {}),
   }
@@ -141,8 +138,7 @@ function refreshPublishedSnapshotSidecars(
 ): PublishedContinuitySnapshot {
   return {
     ...snapshot,
-    ...(identity.publicSkills?.cid ? { publicSkillsCid: identity.publicSkills.cid } : {}),
-    ...(identity.publicSkills?.agentCardCid ? { agentCardCid: identity.publicSkills.agentCardCid } : {}),
+    ...(identity.agentCard?.cid ? { agentCardCid: identity.agentCard.cid } : {}),
   }
 }
 
@@ -180,8 +176,7 @@ function currentPublishedSnapshot(identity: EthagentIdentity): PublishedContinui
     ...(backup.metadataCid ? { metadataCid: backup.metadataCid } : {}),
     ...(backup.agentUri ? { agentUri: backup.agentUri } : {}),
     ...(backup.txHash ? { txHash: backup.txHash } : {}),
-    ...(identity.publicSkills?.cid ? { publicSkillsCid: identity.publicSkills.cid } : {}),
-    ...(identity.publicSkills?.agentCardCid ? { agentCardCid: identity.publicSkills.agentCardCid } : {}),
+    ...(identity.agentCard?.cid ? { agentCardCid: identity.agentCard.cid } : {}),
     label: 'current published snapshot',
     identity: {
       address: identity.address,

package/src/identity/continuity/storage/defaults.ts

@@ -1,6 +1,6 @@
 import type { EthagentIdentity } from '../../../storage/config.js'
 import type { ContinuityAgentSnapshot, ContinuityFiles } from '../envelope.js'
-import { defaultPublicSkillsProfile, renderPublicSkillsJson } from '../publicSkills.js'
+import { createAgentCard, defaultPublicSkillsProfile, serializeAgentCard } from '../publicSkills.js'
 import { renderPrivateIdentityBlock } from './markdown.js'
 
 export function continuityAgentSnapshot(identity: EthagentIdentity): ContinuityAgentSnapshot {
@@ -87,6 +87,6 @@ export function defaultContinuityFiles(identity: EthagentIdentity, _now = new Da
   }
 }
 
-export function defaultPublicSkillsJson(identity: EthagentIdentity): string {
-  return renderPublicSkillsJson(defaultPublicSkillsProfile(identity))
+export function defaultAgentCardJson(identity: EthagentIdentity): string {
+  return serializeAgentCard(createAgentCard(defaultPublicSkillsProfile(identity)))
 }

package/src/identity/continuity/storage/paths.ts

@@ -8,7 +8,7 @@ export function continuityVaultRef(identity: Pick<EthagentIdentity, 'chainId' |
     dir,
     soulPath: path.join(dir, 'SOUL.md'),
     memoryPath: path.join(dir, 'MEMORY.md'),
-    publicSkillsPath: path.join(dir, 'skills.json'),
+    agentCardPath: path.join(dir, 'agent-card.json'),
     skillsDir: path.join(dir, 'skills'),
   }
 }