known-platform-limitations.md

# Known Platform Limitations

These are ClawHub platform behaviors that cannot be changed by editing SKILL.md or using different publish flags. Know them to avoid misdiagnosing issues.

---

## Local Edit ≠ Published Skill

Editing a local `SKILL.md` file does NOT update the public ClawHub page automatically. `clawhub publish` must be run explicitly to propagate changes.

This is the #1 historical failure mode. Always run publish when the user says "update the web page".

---

## CLI Publish Output ≠ Verification

A successful `clawhub publish` command (with commit ID returned) means the publish was accepted server-side. It does not mean the public page is correct, up-to-date, or fully propagated.

**Always verify** with `clawhub inspect <slug>` and public page text check.

---

## Public Page May Be Blocked

ClawHub is hosted on Vercel. Vercel security checkpoints can block:
- CLI commands (rate limit exhaustion or bot protection)
- Browser access to public pages (security checkpoint, rate limit, login wall)

When blocked, verification reports must show `BLOCKED` or `BLOCKED_ACCEPTED`, not `PASS`.

---

## CDN / Cache Lag

After a successful publish, the CDN can take 2–5 minutes to propagate the new content to all edge nodes. `clawhub inspect` may show correct content immediately, but the public page may show stale content temporarily.

**Do not re-publish immediately** if inspect shows correct version but public page looks stale. Wait 2–3 minutes first.

---

## Browser Snapshot Can Lie

The browser accessibility tree (`browser_snapshot` output) shows element hierarchy but not actual visual rendering. Known discrepancies:

- Numbered list items: `1.` can be visually present or stripped depending on context inside sections.
- Bold markers: `**1.**` survives; bare `1.` may be stripped inside H2 sections.
- Section nesting: accessibility tree can show correct containment while visual render differs.

**Always use `innerText` / raw rendered text for verification when exact content matching is required.**

---

## Top Install Block Is Auto-Generated

The prominent install block at the top of every ClawHub skill page (`openclaw skills install <slug>`) is AUTO-GENERATED by ClawHub from the slug. It is NOT controlled by:
- The `--name` flag in publish command
- The `## Install` section in SKILL.md
- Any manifest or package.json field

**Workaround for `--global` in install block:** Use a different slug (e.g., `openclaw-waste-audit`) — but that creates a new skill. There is no flag to add `--global` to the auto-generated top block.

**Confirmed 2026-05-23:** Published v1.8.5 with `--name "OpenClaw Token Waste Audit"` and SKILL.md `## Install` section with `waste-audit --global`. Top block still showed `openclaw skills install waste-audit` (no `--global`).

---

## HTML Comments Are Not Stripped

ClawHub's page renderer does NOT strip HTML comments. `<!-- comment -->` blocks in SKILL.md appear as visible raw text to all visitors.

**Never use HTML comments to hide internal content** from public view — they will be publicly readable.

The skill runtime reads the full SKILL.md, so hidden content still affects behavior — but it WILL be publicly visible if placed inline.

For truly private content, keep it in a separate `references/<slug>-notes.md` support file — it won't appear on the public page but the skill can still read it.

---

## Rename Command Is Broken

**Confirmed 2026-05-22:** `clawhub skill rename <slug> <new-slug> --yes` is broken on CLI 0.9.0.

**Symptom:** Returns `✖ newSlug required (remaining: N/3000, reset in Ns)` every time, regardless of argument order.

**Root cause:** The `--yes` flag consumes a positional argument slot, causing parser to misread the second positional as missing. This is a parse failure, NOT a rate limit signal.

**Correct approach:** Separate-slab migration:
1. Publish the new slug as a separate skill.
2. Update the old slug's content to redirect to the new canonical URL.
3. Both slugs remain live; old slug functions as a transition page.

---

## Rename / Merge / Delete Are Management Operations, Not Publishing

The CLI commands `clawhub skill rename`, `clawhub skill merge`, and `clawhub delete` exist, but they are skill-management operations that affect:
- Public routing and listing
- Registry state
- Download counts and install aliases

They must NOT be used as part of the normal publish flow. Treat them as out-of-scope for `clawhub-auto-publish`.

---

## Version Must Increment

ClawHub requires a higher semver on each publish. Cannot re-publish the same version — it will be rejected.

For first publish: any valid semver works (e.g., `1.0.0`).
For updates: new version must be higher than currently published version.

---

## Slug Namespace Restrictions

- Cannot start with `openclaw-` (protected namespace).
- Cannot end with `-openclaw`.

**Workaround:** Use slug like `waste-audit` with display name `OpenClaw Token Waste Audit`. The display name can contain any text; only the slug has restrictions.