docs: clarify uninstall run-order + statusLine ceiling

Follow-up to #228 (issue #226):

- README: state that scripts/uninstall.js must run *before* the host
  remove command, since the script is itself a plugin file and gets
  deleted by the removal (or run it from a separate clone).
- uninstall.js: add a ponytail: comment naming the statusLine match
  ceiling — substring match + whole-key delete removes a combined
  (e.g. caveman+ponytail) statusline wholesale; upgrade path noted.
- Add trailing newline to the file.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

README.md

@@ -210,6 +210,17 @@ VS Code with the Codex extension reads `AGENTS.md`, which this repo ships, so it
 
 Which files map to which agent: [Agent portability](docs/agent-portability.md).
 
+### Uninstall
+
+| Host | Command |
+|------|---------|
+| Claude Code | `/plugin remove ponytail` |
+| Codex | `codex plugin remove ponytail` |
+| Pi agent | `pi uninstall ponytail` |
+| Cursor / Windsurf / Cline / etc. | Delete the copied rule file |
+
+These remove the plugin's own files. They leave behind a small amount of state ponytail writes outside the plugin folder: the mode flag, `~/.config/ponytail/config.json`, and (if you accepted the setup nudge) a `statusLine` entry in `~/.claude/settings.json`. Run `node scripts/uninstall.js` to clean those up too. **Run it before the host remove command above** — the script is itself a plugin file, so removing the plugin first deletes it (or run it from a separate clone of this repo). It only removes the statusLine entry if it points at ponytail's own script, so a statusline you set up yourself is left untouched.
+
 ## Commands
 
 | Command | What it does |
@@ -232,7 +243,7 @@ node scripts/check-rule-copies.js
 npm test
 ```
 
-The OpenClaw skill package (`.openclaw/skills/`) is generated from `skills/`; rerun `node scripts/build-openclaw-skills.js` after changing a skill, the test suite fails if it is stale.
+The OpenClaw skill package (`.openclaw/skills/`) is generated from `skills/`; rerun `node scripts/build-openclaw-skills.js` after changing a skill, the test suite fails if it is stale. To publish the skills to ClawHub, run `clawhub login` once, then `node scripts/publish-openclaw-skills.js` (it publishes all six at the `package.json` version; pass `--dry-run` to preview).
 
 The correctness benchmark spawns Python for email and CSV checks; `python3` is tried before `python`. CSV checks need `pandas` installed locally.
 

scripts/publish-openclaw-skills.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// Publish the generated OpenClaw skills (.openclaw/skills/) to ClawHub.
+//
+// ClawHub does not sync from GitHub: each skill is pushed explicitly with the
+// clawhub CLI and carries its own version. This publishes every generated skill
+// in one pass, versioned from the repo's package.json so ClawHub tracks the repo
+// instead of drifting (the same drift that hit the plugin manifests in #260).
+//
+// Prereqs:
+//   - `clawhub login` once (registry auth persists)
+//   - skills must be current: run `node scripts/build-openclaw-skills.js` first
+//     if you changed a skill (CI fails if the committed copies are stale)
+//
+// Usage:
+//   node scripts/publish-openclaw-skills.js            # publish all as latest
+//   node scripts/publish-openclaw-skills.js --dry-run  # preview, upload nothing
+//   (any extra args are passed through to `clawhub skill publish`)
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const root = path.join(__dirname, '..');
+const skillsDir = path.join(root, '.openclaw', 'skills');
+
+const version = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).version;
+
+// Every generated skill dir with a SKILL.md is publishable. Reading the dir
+// (instead of a hardcoded list) covers whatever build-openclaw-skills emits,
+// with nothing to keep in sync.
+const slugs = fs.readdirSync(skillsDir, { withFileTypes: true })
+  .filter((e) => e.isDirectory() && fs.existsSync(path.join(skillsDir, e.name, 'SKILL.md')))
+  .map((e) => e.name)
+  .sort();
+
+if (slugs.length === 0) {
+  console.error(`No skills under ${path.relative(root, skillsDir)}; run build-openclaw-skills.js first.`);
+  process.exit(1);
+}
+
+// "ponytail-review" -> "Ponytail Review"
+const displayName = (slug) =>
+  slug.split('-').map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+
+// Minimal quoting that satisfies both POSIX sh and cmd.exe: only display names
+// (which contain a space) need wrapping; slugs, versions, paths, and flags don't.
+const quote = (a) => (/[^\w./-]/.test(a) ? `"${a}"` : a);
+
+const passthrough = process.argv.slice(2);
+const extra = passthrough.length ? ` (${passthrough.join(' ')})` : '';
+console.log(`Publishing ${slugs.length} skills to ClawHub at version ${version}${extra}:`);
+
+for (const slug of slugs) {
+  const args = [
+    'clawhub', 'skill', 'publish', `.openclaw/skills/${slug}`,
+    '--slug', slug,
+    '--name', displayName(slug),
+    '--version', version,
+    '--tags', 'latest',
+    ...passthrough,
+  ];
+  const cmdline = args.map(quote).join(' ');
+  console.log(`\n$ ${cmdline}`);
+  const res = spawnSync(cmdline, { stdio: 'inherit', cwd: root, shell: true });
+  if (res.status !== 0) {
+    console.error(
+      `\nPublish failed for "${slug}" (exit ${res.status}). ` +
+      `Check that the clawhub CLI is installed and you have run \`clawhub login\`, then re-run. ` +
+      `Skills already published in this run are unaffected.`,
+    );
+    process.exit(res.status || 1);
+  }
+}
+
+console.log(`\nDone. Published ${slugs.length} skills at ${version}.`);

scripts/uninstall.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// ponytail — removes state ponytail wrote outside the plugin's own files:
+// the mode flag, the config file, and the statusLine entry it added to
+// settings.json. Plugin files themselves are removed by each host's own
+// uninstall command (see README); this only cleans up what those commands
+// can't see.
+
+const fs = require('fs');
+const path = require('path');
+const { getConfigPath, getClaudeDir } = require('../hooks/ponytail-config');
+
+function removeIfExists(filePath, label) {
+  try {
+    fs.unlinkSync(filePath);
+    console.log(`Removed ${label}: ${filePath}`);
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+}
+
+removeIfExists(path.join(getClaudeDir(), '.ponytail-active'), 'mode flag');
+removeIfExists(getConfigPath(), 'config file');
+
+const settingsPath = path.join(getClaudeDir(), 'settings.json');
+try {
+  const raw = fs.readFileSync(settingsPath, 'utf8').replace(/^\uFEFF/, '');
+  const settings = JSON.parse(raw);
+  const cmd = settings.statusLine && settings.statusLine.command;
+  // ponytail: substring-match the script name, then drop the whole statusLine
+  // key. A combined statusline (e.g. caveman+ponytail) whose command contains
+  // "ponytail-statusline" gets removed wholesale. Parse out only ponytail's part
+  // if combined statuslines become common.
+  if (typeof cmd === 'string' && cmd.includes('ponytail-statusline')) {
+    delete settings.statusLine;
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf8');
+    console.log(`Removed ponytail statusLine entry from ${settingsPath}`);
+  }
+} catch (e) {
+  if (e.code !== 'ENOENT') throw e;
+}

tests/uninstall.test.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const root = path.join(__dirname, '..');
+
+function runUninstall(env) {
+  return spawnSync(process.execPath, [path.join(root, 'scripts', 'uninstall.js')], {
+    env: { ...process.env, ...env },
+    encoding: 'utf8',
+  });
+}
+
+delete process.env.CLAUDE_CONFIG_DIR;
+
+const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'ponytail-uninstall-'));
+process.on('exit', () => fs.rmSync(temp, { recursive: true, force: true }));
+
+const home = path.join(temp, 'home');
+const claudeDir = path.join(home, '.claude');
+fs.mkdirSync(claudeDir, { recursive: true });
+
+const flagPath = path.join(claudeDir, '.ponytail-active');
+fs.writeFileSync(flagPath, 'full');
+
+const configDir = path.join(temp, 'config-home', 'ponytail');
+fs.mkdirSync(configDir, { recursive: true });
+const configPath = path.join(configDir, 'config.json');
+fs.writeFileSync(configPath, JSON.stringify({ defaultMode: 'ultra' }));
+
+const settingsPath = path.join(claudeDir, 'settings.json');
+fs.writeFileSync(settingsPath, JSON.stringify({
+  statusLine: { type: 'command', command: 'bash /some/path/ponytail-statusline.sh' },
+}));
+
+const env = {
+  HOME: home,
+  USERPROFILE: home,
+  XDG_CONFIG_HOME: path.join(temp, 'config-home'),
+};
+
+let result = runUninstall(env);
+assert.equal(result.status, 0, result.stderr);
+assert.equal(fs.existsSync(flagPath), false, 'mode flag must be removed');
+assert.equal(fs.existsSync(configPath), false, 'config file must be removed');
+
+const settingsAfter = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+assert.equal(
+  settingsAfter.statusLine,
+  undefined,
+  'ponytail statusLine entry must be removed',
+);
+
+// A user's own, unrelated statusLine must survive untouched.
+fs.writeFileSync(settingsPath, JSON.stringify({
+  statusLine: { type: 'command', command: 'bash ~/my-custom-statusline.sh' },
+}));
+
+result = runUninstall(env);
+assert.equal(result.status, 0, result.stderr);
+const settingsAfter2 = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+assert.equal(
+  settingsAfter2.statusLine.command,
+  'bash ~/my-custom-statusline.sh',
+  "a user's own statusLine must not be touched",
+);
+
+// Running on an already-clean machine must not throw.
+result = runUninstall({ HOME: path.join(temp, 'home-empty'), USERPROFILE: path.join(temp, 'home-empty') });
+assert.equal(result.status, 0, result.stderr);
+
+console.log('uninstall script checks passed');