docs: rewrite for ClawHub discoverability and user-facing clarity

- ClawHub skill README: replace packaging notes with product page
  (problem statement, quick start, commands table, compatibility)
- SKILL.md: rewrite description for search, add tags in metadata
- Root README: lead with install/usage, add ClawHub as primary path
- Plugin README: add value prop tagline, scannable commands table
- releasing.md: add copy-paste GitHub Release note template
- Rebuild dist with updated docs

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

Author: guanjiawei

README.md

@@ -1,76 +1,86 @@
-# aima-openclaw
+# AIMA Doctor for OpenClaw
 
-Standalone OpenClaw distribution repo for AIMA Doctor.
+**One-command diagnosis and repair when your OpenClaw agent is stuck.**
 
-This repository contains the OpenClaw-facing parts of AIMA Doctor only:
+AIMA Doctor is an OpenClaw plugin that gives you a deterministic rescue path — diagnose process health, fix config breakage, recover device registration, and run guided repairs driven by the AIMA platform.
 
-- `plugin-package/aima-doctor/`: native OpenClaw plugin source
-- `clawhub-skill/aima-doctor/`: ClawHub-publishable compatibility skill
-- `runtime/`: standalone helper runtime for manual/runtime-only installs
-- `scripts/build-release.sh`: reproducible release packager
-- `dist/<version>/`: generated release artifacts
+## Install
 
-The AIMA platform backend, `/doctor/*.zip` distribution endpoints, invite-code
-policy, and end-to-end platform tests remain in the main
-`Approaching-AI/aima-service-new` repository. This repo is the public
-OpenClaw-facing package source.
+**From ClawHub** (recommended):
 
-## Supported flow
+```bash
+clawhub install aima-doctor
+```
 
-`/aima` is a deterministic rescue entrypoint for OpenClaw when the normal agent path is degraded but the gateway is still alive and able to receive messages.
+**From a release zip**:
 
-Supported user commands:
+```bash
+openclaw plugins install ./aima-doctor-plugin.zip
+openclaw plugins enable aima-doctor
+```
 
-- `/aima <symptom>`
-- `/aima status`
-- `/aima cancel`
+## Usage
 
-## Build a release
+In any OpenClaw conversation:
 
-```bash
-bash scripts/build-release.sh
+```
+/aima my agent keeps failing to install the package
+/aima status
+/aima cancel
 ```
 
-That command generates:
-
-- `dist/1.2.1/aima-doctor-plugin.zip`
-- `dist/1.2.1/aima-doctor-runtime.zip`
-- `dist/1.2.1/aima-doctor-skill.zip`
-- `dist/1.2.1/PUBLISH.md`
-- `dist/1.2.1/SHA256SUMS.txt`
+When AIMA Doctor asks a follow-up question, reply with `/aima <your answer>`.
 
-## Versioning
+## What's in this repo
 
-This repo intentionally tracks two version surfaces:
+This repository contains the OpenClaw-facing distribution of AIMA Doctor:
 
-- Git tags such as `v0.1`: public repo milestones
-- Bundle version in `VERSION` such as `1.2.1`: the packaged AIMA Doctor bundle
-  version used by the plugin, runtime, and ClawHub skill
+| Directory | Purpose |
+|-----------|---------|
+| `plugin-package/aima-doctor/` | Native OpenClaw plugin source (primary artifact) |
+| `clawhub-skill/aima-doctor/` | ClawHub-publishable skill bundle |
+| `runtime/` | Standalone helper runtime for manual installs |
+| `scripts/build-release.sh` | Reproducible release packager |
+| `dist/<version>/` | Generated release artifacts |
 
-That means the GitHub release can be `v0.1` while the shipped OpenClaw package
-version is still `1.2.1`.
+The AIMA platform backend, distribution endpoints, and end-to-end platform tests live in the main [aima-service-new](https://github.com/Approaching-AI/aima-service-new) repository.
 
-## Install the native plugin
+## Build a release
 
 ```bash
-openclaw plugins install ./dist/1.2.1/aima-doctor-plugin.zip
-openclaw plugins enable aima-doctor
+bash scripts/build-release.sh
 ```
 
+Outputs under `dist/<version>/`:
+
+- `aima-doctor-plugin.zip` — primary install artifact
+- `aima-doctor-runtime.zip` — standalone helper runtime
+- `aima-doctor-skill.zip` — ClawHub compatibility skill
+- `SHA256SUMS.txt` — integrity checksums
+- `PUBLISH.md` — release notes
+
 ## Publish to ClawHub
 
 ```bash
 cd dist/1.2.1/clawhub-skill
 clawhub publish ./aima-doctor --slug aima-doctor --name "AIMA Doctor" --version 1.2.1
 ```
 
-For a full release checklist, see `docs/releasing.md`.
+For the full release checklist, see [docs/releasing.md](docs/releasing.md).
+
+## Versioning
+
+This repo tracks two version surfaces:
+
+- **Git tags** (e.g., `v0.1`): public repo milestones
+- **Bundle version** in `VERSION` (e.g., `1.2.1`): the packaged AIMA Doctor version used by the plugin, runtime, and ClawHub skill
 
-## Runtime defaults
+## Compatibility
 
-- Homepage: `https://aimaservice.ai/doctor`
-- Default platform API: `https://aimaservice.ai/platform/api/v1`
-- Native plugin target: OpenClaw `2026.3.22+`
+- **OS**: macOS, Linux, Windows
+- **OpenClaw**: 2026.3.22+
+- **Default platform API**: https://aimaservice.ai/platform/api/v1
+- **Homepage**: https://aimaservice.ai/doctor
 
 ## License
 

clawhub-skill/aima-doctor/README.md

@@ -1,24 +1,54 @@
-# AIMA Doctor Skill Pack
+# AIMA Doctor
 
-This folder is a ClawHub-publishable OpenClaw skill bundle for AIMA Doctor.
+**One-command diagnosis and repair for OpenClaw.**
 
-## What this contains
+When your OpenClaw agent is stuck, confused, or unable to complete a task, AIMA Doctor gives you a deterministic rescue path — no guessing, no manual debugging.
 
-- `SKILL.md`: the OpenClaw skill entrypoint
-- `README.md`: packaging notes
+## Quick Start
 
-The helper runtime is distributed separately from:
+Install from ClawHub:
 
-- `https://aimaservice.ai/doctor/runtime.zip`
+```bash
+clawhub install aima-doctor
+```
+
+Then in any OpenClaw conversation:
+
+```
+/aima my agent keeps failing to install the package
+```
 
-## Local install
+AIMA Doctor will diagnose the issue, walk you through any needed fixes, and report back with clear results.
 
-1. Copy this folder under `<workspace>/skills/` or `~/.openclaw/skills/`.
-2. Extract the helper runtime into `~/.openclaw/tools/aima-doctor/`.
-3. Start a new OpenClaw session or restart the gateway.
+## Commands
 
-## Publish to ClawHub
+| Command | What it does |
+|---------|-------------|
+| `/aima <symptom>` | Start a diagnosis with a description of the problem |
+| `/aima status` | Check the progress of a running diagnosis |
+| `/aima cancel` | Cancel the current diagnosis |
 
-```bash
-clawhub publish ./aima-doctor --slug aima-doctor --name "AIMA Doctor" --version 1.2.1
-```
+When AIMA Doctor asks a follow-up question, reply with `/aima <your answer>`.
+
+## What it can fix
+
+- OpenClaw process health (hung, crashed, or unresponsive agents)
+- Configuration breakage (corrupted settings, missing config files)
+- AIMA device registration and token recovery
+- Guided local repair driven by AIMA platform diagnostics
+
+## How it works
+
+AIMA Doctor ships a packaged helper runtime that runs locally on your machine. It connects to the AIMA platform API to fetch diagnostics, then executes deterministic repair steps. No remote shell commands, no opaque scripts — everything runs from a versioned, auditable helper.
+
+## Compatibility
+
+- **OS**: macOS, Linux, Windows
+- **OpenClaw**: 2026.3.22+
+- **Runtime**: downloaded automatically on first use from `https://aimaservice.ai/doctor`
+
+## Links
+
+- Homepage: https://aimaservice.ai/doctor
+- Source: https://github.com/Approaching-AI/aima-openclaw
+- License: Apache-2.0

clawhub-skill/aima-doctor/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: aima
-description: Deterministic fallback diagnosis and repair for OpenClaw when the normal agent path is degraded.
+description: Diagnose and repair OpenClaw when your agent is stuck, confused, or failing. One-command rescue for process health, config breakage, and device registration.
 user-invocable: true
 homepage: https://aimaservice.ai/doctor
-metadata: {"openclaw":{"homepage":"https://aimaservice.ai/doctor","skillKey":"aima","os":["darwin","linux","win32"],"install":[{"id":"aima-doctor-runtime","kind":"download","url":"https://aimaservice.ai/doctor/runtime.zip","archive":"zip","extract":true,"targetDir":"~/.openclaw/tools/aima-doctor"}]}}
+metadata: {"openclaw":{"homepage":"https://aimaservice.ai/doctor","skillKey":"aima","tags":["diagnosis","repair","troubleshooting","health","recovery"],"os":["darwin","linux","win32"],"install":[{"id":"aima-doctor-runtime","kind":"download","url":"https://aimaservice.ai/doctor/runtime.zip","archive":"zip","extract":true,"targetDir":"~/.openclaw/tools/aima-doctor"}]}}
 ---
 
 # AIMA Doctor
 
-Use this skill when OpenClaw needs diagnosis or repair and the normal agent flow is degraded, confused, or stuck.
+Use this skill when your OpenClaw agent is stuck, confused, or failing — it provides a deterministic rescue path to diagnose and repair the issue.
 
 ## Runtime contract
 

dist/1.2.1/SHA256SUMS.txt

@@ -1,3 +1,3 @@
-2536e2f2353a6f025b8553bf6b5d7eedcdb7d51a7e64efe99f77fff020dc7c4f  aima-doctor-plugin.zip
-c16a581b34f1f63c1f427f3cc42110a3b828d02951221437135f4a11d915d6f9  aima-doctor-runtime.zip
-8b5f63d1d1eee4467a5ca776bef4f284fa68d50f8056dfd1c42eac0b6c946ef3  aima-doctor-skill.zip
+72e86df73af8625f0d47b1a64ba95959e07ce78f9970a248e6e89cb93e12f66f  aima-doctor-plugin.zip
+067a47eee9210956a24fc760573db93b26d4fa6cc08c4f43bb23c39567a3a180  aima-doctor-runtime.zip
+a0b08ee3aedc93515945ae4e34df2713b8d519f08990eb7e9b26ec9ec9b65042  aima-doctor-skill.zip

dist/1.2.1/aima-doctor-plugin.zip

@@ -1,24 +1,54 @@
-# AIMA Doctor Skill Pack
+# AIMA Doctor
 
-This folder is a ClawHub-publishable OpenClaw skill bundle for AIMA Doctor.
+**One-command diagnosis and repair for OpenClaw.**
 
-## What this contains
+When your OpenClaw agent is stuck, confused, or unable to complete a task, AIMA Doctor gives you a deterministic rescue path — no guessing, no manual debugging.
 
-- `SKILL.md`: the OpenClaw skill entrypoint
-- `README.md`: packaging notes
+## Quick Start
 
-The helper runtime is distributed separately from:
+Install from ClawHub:
 
-- `https://aimaservice.ai/doctor/runtime.zip`
+```bash
+clawhub install aima-doctor
+```
+
+Then in any OpenClaw conversation:
+
+```
+/aima my agent keeps failing to install the package
+```
 
-## Local install
+AIMA Doctor will diagnose the issue, walk you through any needed fixes, and report back with clear results.
 
-1. Copy this folder under `<workspace>/skills/` or `~/.openclaw/skills/`.
-2. Extract the helper runtime into `~/.openclaw/tools/aima-doctor/`.
-3. Start a new OpenClaw session or restart the gateway.
+## Commands
 
-## Publish to ClawHub
+| Command | What it does |
+|---------|-------------|
+| `/aima <symptom>` | Start a diagnosis with a description of the problem |
+| `/aima status` | Check the progress of a running diagnosis |
+| `/aima cancel` | Cancel the current diagnosis |
 
-```bash
-clawhub publish ./aima-doctor --slug aima-doctor --name "AIMA Doctor" --version 1.2.1
-```
+When AIMA Doctor asks a follow-up question, reply with `/aima <your answer>`.
+
+## What it can fix
+
+- OpenClaw process health (hung, crashed, or unresponsive agents)
+- Configuration breakage (corrupted settings, missing config files)
+- AIMA device registration and token recovery
+- Guided local repair driven by AIMA platform diagnostics
+
+## How it works
+
+AIMA Doctor ships a packaged helper runtime that runs locally on your machine. It connects to the AIMA platform API to fetch diagnostics, then executes deterministic repair steps. No remote shell commands, no opaque scripts — everything runs from a versioned, auditable helper.
+
+## Compatibility
+
+- **OS**: macOS, Linux, Windows
+- **OpenClaw**: 2026.3.22+
+- **Runtime**: downloaded automatically on first use from `https://aimaservice.ai/doctor`
+
+## Links
+
+- Homepage: https://aimaservice.ai/doctor
+- Source: https://github.com/Approaching-AI/aima-openclaw
+- License: Apache-2.0

dist/1.2.1/aima-doctor-runtime.zip

@@ -1,14 +1,14 @@
 ---
 name: aima
-description: Deterministic fallback diagnosis and repair for OpenClaw when the normal agent path is degraded.
+description: Diagnose and repair OpenClaw when your agent is stuck, confused, or failing. One-command rescue for process health, config breakage, and device registration.
 user-invocable: true
 homepage: https://aimaservice.ai/doctor
-metadata: {"openclaw":{"homepage":"https://aimaservice.ai/doctor","skillKey":"aima","os":["darwin","linux","win32"],"install":[{"id":"aima-doctor-runtime","kind":"download","url":"https://aimaservice.ai/doctor/runtime.zip","archive":"zip","extract":true,"targetDir":"~/.openclaw/tools/aima-doctor"}]}}
+metadata: {"openclaw":{"homepage":"https://aimaservice.ai/doctor","skillKey":"aima","tags":["diagnosis","repair","troubleshooting","health","recovery"],"os":["darwin","linux","win32"],"install":[{"id":"aima-doctor-runtime","kind":"download","url":"https://aimaservice.ai/doctor/runtime.zip","archive":"zip","extract":true,"targetDir":"~/.openclaw/tools/aima-doctor"}]}}
 ---
 
 # AIMA Doctor
 
-Use this skill when OpenClaw needs diagnosis or repair and the normal agent flow is degraded, confused, or stuck.
+Use this skill when your OpenClaw agent is stuck, confused, or failing — it provides a deterministic rescue path to diagnose and repair the issue.
 
 ## Runtime contract
 

dist/1.2.1/aima-doctor-skill.zip

@@ -1,15 +1,6 @@
 # AIMA Doctor Plugin
 
-This archive is the primary OpenClaw `2026.3.22+` install artifact for AIMA Doctor.
-
-## What this contains
-
-- `openclaw.plugin.json`: native OpenClaw plugin manifest
-- `index.js`: gateway plugin entrypoint
-- `skills/aima-doctor/SKILL.md`: bundled reference skill
-- `runtime/run.sh`: packaged doctor helper for macOS/Linux
-- `runtime/run.ps1`: packaged doctor helper for Windows
-- `runtime/config.json`: default AIMA platform URL
+**One-command diagnosis and repair for OpenClaw.** This is the primary native plugin for OpenClaw 2026.3.22+.
 
 ## Install
 
@@ -18,17 +9,28 @@ openclaw plugins install ./aima-doctor-plugin.zip
 openclaw plugins enable aima-doctor
 ```
 
-Then use these IM commands:
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `/aima <symptom>` | Start a diagnosis with a description of the problem |
+| `/aima status` | Check progress of a running diagnosis |
+| `/aima cancel` | Cancel the current diagnosis |
+
+When the helper asks a follow-up question, reply with `/aima <your answer>`.
+
+Legacy `/askforhelp*` and `/doctor*` aliases remain available for compatibility.
 
-- `/aima [symptom]`
-- `/aima status`
-- `/aima cancel`
+## What's inside
 
-When the helper asks a question, answer with `/aima <your reply>`.
+- `openclaw.plugin.json` — native OpenClaw plugin manifest
+- `index.js` — gateway plugin entrypoint
+- `skills/aima-doctor/SKILL.md` — bundled reference skill
+- `runtime/run.sh` — helper for macOS/Linux
+- `runtime/run.ps1` — helper for Windows
+- `runtime/config.json` — default AIMA platform URL
 
 ## Notes
 
-- The plugin package owns execution.
-- The bundled skill is for discovery/documentation and does not replace the native `/aima` command family.
-- Legacy `/askforhelp*` and `/doctor*` aliases remain available for compatibility.
-- Homepage: `https://aimaservice.ai/doctor`
+- The plugin package owns execution; the bundled skill is for discovery/documentation only.
+- Homepage: https://aimaservice.ai/doctor