docs: add release and packaging guidance

Author: guanjiawei

README.md

@@ -10,6 +10,11 @@ This repository contains the OpenClaw-facing parts of AIMA Doctor only:
 - `scripts/build-release.sh`: reproducible release packager
 - `dist/<version>/`: generated release artifacts
 
+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.
+
 ## Supported flow
 
 `/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.
@@ -34,6 +39,17 @@ That command generates:
 - `dist/1.2.1/PUBLISH.md`
 - `dist/1.2.1/SHA256SUMS.txt`
 
+## Versioning
+
+This repo intentionally tracks two version surfaces:
+
+- 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
+
+That means the GitHub release can be `v0.1` while the shipped OpenClaw package
+version is still `1.2.1`.
+
 ## Install the native plugin
 
 ```bash
@@ -48,6 +64,8 @@ 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`.
+
 ## Runtime defaults
 
 - Homepage: `https://aimaservice.ai/doctor`

docs/releases/v0.1.md

@@ -0,0 +1,28 @@
+# aima-openclaw v0.1
+
+Initial public release of the standalone OpenClaw-facing AIMA Doctor package.
+
+## Included bundle version
+
+- AIMA Doctor bundle version: `1.2.1`
+
+## Included artifacts
+
+- `aima-doctor-plugin.zip`
+- `aima-doctor-runtime.zip`
+- `aima-doctor-skill.zip`
+- `SHA256SUMS.txt`
+- `PUBLISH.md`
+
+## Scope
+
+- Native OpenClaw gateway plugin for `/aima`
+- Standalone runtime helper for macOS, Linux, and Windows
+- ClawHub-publishable compatibility skill bundle
+- Public release packaging flow separated from the main AIMA platform repo
+
+## Notes
+
+- Git tag `v0.1` marks the public repo milestone.
+- Bundle version `1.2.1` is the packaged OpenClaw artifact version.
+- ClawHub publishing should use `dist/1.2.1/clawhub-skill/aima-doctor/`.

docs/releasing.md

@@ -0,0 +1,97 @@
+# Releasing `aima-openclaw`
+
+This repo ships OpenClaw-facing artifacts only. A normal public release should
+produce and publish three bundles:
+
+- `aima-doctor-plugin.zip`
+- `aima-doctor-runtime.zip`
+- `aima-doctor-skill.zip`
+
+## 1. Update the bundle version
+
+Edit `VERSION` when the packaged AIMA Doctor bundle changes.
+
+Current value:
+
+```text
+1.2.1
+```
+
+The `VERSION` file controls:
+
+- generated `dist/<version>/`
+- `PUBLISH.md`
+- ClawHub publish examples
+
+## 2. Build release artifacts
+
+```bash
+bash scripts/build-release.sh
+```
+
+Verify these outputs exist:
+
+- `dist/<version>/aima-doctor-plugin.zip`
+- `dist/<version>/aima-doctor-runtime.zip`
+- `dist/<version>/aima-doctor-skill.zip`
+- `dist/<version>/SHA256SUMS.txt`
+- `dist/<version>/PUBLISH.md`
+
+## 3. Commit and push
+
+```bash
+git add .
+git commit -m "release: prepare <version>"
+git push origin main
+```
+
+## 4. Create a Git tag
+
+Repo tags mark public milestones and do not have to match the bundle version.
+
+Example:
+
+```bash
+git tag v0.1
+git push origin v0.1
+```
+
+## 5. Create the GitHub Release
+
+Attach the generated bundles:
+
+```bash
+gh release create v0.1 \
+  dist/<version>/aima-doctor-plugin.zip \
+  dist/<version>/aima-doctor-runtime.zip \
+  dist/<version>/aima-doctor-skill.zip \
+  dist/<version>/SHA256SUMS.txt \
+  dist/<version>/PUBLISH.md
+```
+
+Recommended release note shape:
+
+- public milestone tag, for example `v0.1`
+- packaged bundle version, for example `1.2.1`
+- attached plugin/runtime/skill bundle list
+- note that ClawHub publish should use the unpacked `dist/<version>/clawhub-skill/aima-doctor/`
+
+## 6. Publish to ClawHub
+
+Use the rendered skill directory, not the zip file:
+
+```bash
+cd dist/<version>/clawhub-skill
+clawhub publish ./aima-doctor --slug aima-doctor --name "AIMA Doctor" --version <version>
+```
+
+## Repo boundary
+
+Keep these concerns out of this repo:
+
+- AIMA platform backend code
+- `/doctor/plugin.zip`, `/doctor/runtime.zip`, `/doctor/skill.zip` HTTP routes
+- invite-code seeding and platform config
+- platform integration tests
+
+Those stay in `Approaching-AI/aima-service-new`.