From 498d279cd3deabbfcbb559360450da51d003f240 Mon Sep 17 00:00:00 2001
From: pc-gemini <pc-gemini@xmemo.dev>
Date: Sat, 22 Aug 2026 16:31:12 +0900
Subject: [PATCH] docs(skill): add first successful run path

---
 skills/xmemo/CHANGELOG.md            |  7 +++++++
 skills/xmemo/SKILL.md                | 29 ++++++++++++++++++++++++++++
 skills/xmemo/scripts/xmemo-skill.mjs |  2 +-
 test/xmemo-skill.test.js             |  5 +++++
 4 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/skills/xmemo/CHANGELOG.md b/skills/xmemo/CHANGELOG.md
index 101886f..e1e5242 100644
--- a/skills/xmemo/CHANGELOG.md
+++ b/skills/xmemo/CHANGELOG.md
@@ -1,5 +1,12 @@
 # XMemo Skill Change Log
 
+## 1.1.12
+
+- Add a short first-successful-run path: anonymous service health check,
+  deliberate credential choice, and credential verification before memory work.
+- Preserve runtime commands, network requests, authentication, scopes,
+  credential behavior, service APIs, and MCP fallback behavior.
+
 ## 1.1.11
 
 - Simplify the standalone Skill description so agents can discover its core
diff --git a/skills/xmemo/SKILL.md b/skills/xmemo/SKILL.md
index 659fc86..55e5b5d 100644
--- a/skills/xmemo/SKILL.md
+++ b/skills/xmemo/SKILL.md
@@ -7,6 +7,35 @@ description: Persistent, user-owned memory for agents. Use the standalone runtim
 
 Give your agent durable memory that survives across sessions, projects, and tools.
 
+## First Successful Run
+
+After ClawHub installs this Skill, run these commands from the Skill root to
+confirm the service and choose an authentication path in a few minutes:
+
+1. Check public service reachability without sending a credential:
+
+   ```text
+   node scripts/xmemo-skill.mjs doctor --anonymous
+   ```
+
+2. For account-backed memory, prefer an `XMEMO_KEY` supplied by a managed
+   secret store. Otherwise, start the formal device-login flow only when you
+   explicitly accept local plaintext credential storage:
+
+   ```text
+   node scripts/xmemo-skill.mjs login --allow-plaintext
+   ```
+
+3. Confirm the credential before running memory operations:
+
+   ```text
+   node scripts/xmemo-skill.mjs auth status --verify
+   ```
+
+If a command fails, use the exact next action it prints, then read
+`references/troubleshooting.md`. Once the check succeeds, continue with
+**Core Workflows** below.
+
 ## Runtime Selection
 
 XMemo supports two parallel integration paths:
diff --git a/skills/xmemo/scripts/xmemo-skill.mjs b/skills/xmemo/scripts/xmemo-skill.mjs
index 9001b46..ad03ac3 100644
--- a/skills/xmemo/scripts/xmemo-skill.mjs
+++ b/skills/xmemo/scripts/xmemo-skill.mjs
@@ -13,7 +13,7 @@ import os from 'node:os';
 import readline from 'node:readline';
 import { randomUUID } from 'node:crypto';
 
-const SKILL_VERSION = '1.1.11';
+const SKILL_VERSION = '1.1.12';
 const credentialsPath = path.join(os.homedir(), '.xmemo', 'skill-credentials.json');
 const registrationPath = path.join(os.homedir(), '.xmemo', 'skill-registration.json');
 const SCRIPT_COMMAND = 'node scripts/xmemo-skill.mjs';
diff --git a/test/xmemo-skill.test.js b/test/xmemo-skill.test.js
index b084e66..01cae68 100644
--- a/test/xmemo-skill.test.js
+++ b/test/xmemo-skill.test.js
@@ -13,6 +13,11 @@ test('XMemo Skill describes standalone CLI-backed runtime selection', async () =
 
   assert.match(skill, /^---\nname: xmemo-memory\ndescription: .+\n---\n/);
   assert.match(skill, /Runtime Selection/);
+  assert.match(skill, /First Successful Run/);
+  assert.match(skill, /After ClawHub installs this Skill/);
+  assert.match(skill, /doctor --anonymous/);
+  assert.match(skill, /auth status --verify/);
+  assert.match(skill, /managed\n+   secret store/);
   assert.match(skill, /scripts\/xmemo-skill\.mjs/);
   assert.doesNotMatch(skill, /node skills\/xmemo\/scripts\/xmemo-skill\.mjs/);
   assert.match(skill, /xmemo-skill\.mjs login/);