first commit

Author: flhoildy

.agents/skills/clawbox-chat-stream/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: clawbox-chat-stream
+description: Use when changing or debugging ClawBox chat sending, SSE streaming, reasoning blocks, tool-call blocks, session synchronization, or title generation across the React frontend and the Bun OpenClaw bridge.
+---
+
+# ClawBox Chat Stream
+
+Use this skill when the task involves ClawBox chat flow, assistant streaming, tool event rendering, session history hydration, or title generation.
+
+## Read first
+
+- `src/hooks/useChat.ts`
+- `src/services/ai.ts`
+- `src/store/chat.ts`
+- `src/components/chat/`
+- `internal/routes/chat.ts`
+- `internal/providers/openclaw-rpc.ts`
+- `src/services/api.ts`
+
+## Workflow
+
+1. Map the end-to-end path: UI event -> frontend store/hook -> SSE parser -> backend route -> OpenClaw RPC event.
+2. If request or response payloads change, update every consumer in the same task instead of leaving cross-layer drift.
+3. For tool-call regressions, verify both streamed events and history rehydration. ClawBox uses live events plus follow-up history reconciliation.
+4. For title or unread-count issues, inspect the `finally` path in `src/hooks/useChat.ts` and the corresponding Zustand store updates.
+
+## Verification
+
+- Run `npm run build:frontend`.
+- Run `npm run build:backend`.
+- If the local gateway is available, use `bun test/openclaw-stream.ts --prompt "..."` as a manual smoke test.
+
+## Guardrails
+
+- Never guess OpenClaw protocol fields or event names.
+- Preserve the SSE event types expected by `src/services/ai.ts`.
+- Keep message block ordering consistent with the `text`, `reasoning`, and `tool_call` model.

.agents/skills/clawbox-git-commit-push/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: clawbox-git-commit-push
+description: Use when the user asks to stage ClawBox changes, write a git commit, create a non-interactive commit, or push the current branch safely without mixing unrelated worktree changes.
+---
+
+# ClawBox Git Commit Push
+
+Use this skill when the task is to prepare a clean git commit and push it from the current ClawBox repository.
+
+## Read first
+
+- `git status --short --branch`
+- `git diff --stat`
+- `git diff --cached --stat`
+- Targeted `git diff -- <paths>` for files intended for the commit
+
+## Workflow
+
+1. Inspect repo state before staging anything.
+2. Confirm the requested commit scope from actual modified files, not assumptions.
+3. Stage only intended paths with `git add <paths>`.
+4. Create the commit with `git commit -m "..."`.
+5. Check upstream with `git rev-parse --abbrev-ref --symbolic-full-name @{u}`.
+6. Use `git push` when upstream exists, or `git push -u origin <branch>` when the target is obvious.
+7. Report the commit hash, branch, and push result.
+
+## Guardrails
+
+- Never use destructive commands such as `git reset --hard`, `git checkout --`, rebase, or force-push unless the user explicitly asks.
+- Never stage unrelated or generated files silently.
+- Never amend a commit unless explicitly requested.
+- Prefer non-interactive git commands only.
+- Stop and ask when branch target, commit scope, or staged changes are ambiguous.
+
+## Verification
+
+- Run `git status --short --branch` before and after the commit.
+- Run `git log --oneline -1` after the commit.
+- If pushed, verify the branch is no longer ahead with `git status --short --branch`.

.agents/skills/clawbox-release-packaging/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: clawbox-release-packaging
+description: Use when changing ClawBox Tauri packaging, sidecar bootstrapping, version synchronization, Bun backend compilation, or release-related scripts and configuration. This includes the UTC date-based version generator, Tauri and Cargo version sync, Windows installer signing helpers, and GitHub release workflow guards. Do not use for actually cutting and pushing a release tag; use the release publish skill for that.
+---
+
+# ClawBox Release Packaging
+
+Use this skill when the task involves ClawBox versioning, Tauri configuration, backend binary packaging, sidecar lifecycle, or release build scripts.
+
+## Read first
+
+- `package.json`
+- `docs/releasing.md`
+- `.github/release-notes-template.md`
+- `docs/releases/`
+- `scripts/collect-release-assets.mjs`
+- `scripts/release-version.mjs`
+- `scripts/sync-version.mjs`
+- `scripts/sign-win-installer.mjs`
+- `scripts/build-backend.mjs`
+- `.github/workflows/release.yml`
+- `src-tauri/tauri.conf.json`
+- `src-tauri/Cargo.toml`
+- `src-tauri/src/lib.rs`
+- `internal/onboard/` if the task also affects runtime bootstrap or environment setup
+
+## Workflow
+
+1. Identify which layer is changing: UTC version generation, version synchronization, Bun backend compile output, Tauri shell, release workflow guard, release-notes lookup, release-asset filtering, or installer/signing script.
+2. Preserve `package.json` as the single source of truth for the app version. Any version automation must keep `package-lock.json`, `src-tauri/tauri.conf.json`, and `src-tauri/Cargo.toml` aligned.
+3. Keep the UTC date-based version format semver-safe. The current release flow uses `YYYY.M.D-N`, with `git fetch --tags` plus local `vYYYY.M.D-N` tags determining the next sequence.
+4. Keep sidecar naming and resource lookup behavior aligned with `scripts/build-backend.mjs` and `src-tauri/src/lib.rs`.
+5. Keep Windows installer signing dynamic. `tauri:build-win:sign-installer` should resolve `ClawBox_<version>_x64-setup.exe` from `package.json`, not from a hard-coded filename.
+6. Keep release publication scoped to user-facing assets only. The workflow should publish final `.dmg`, `.exe`, and the combined `CHECKSUMS.txt`, not the entire Tauri bundle tree.
+7. Keep release notes lookup aligned with the documented flow. Hand-written notes live at `docs/releases/<tag>.md`, with GitHub-generated notes as the fallback when the file is absent.
+8. If the change touches release publication behavior rather than packaging/configuration, hand off to `clawbox-release-publish` instead of extending this skill.
+9. If the change touches Windows signing or platform-specific installers, note any credentials or OS environments you could not validate.
+
+## Verification
+
+- Run `node scripts/release-version.mjs --dry-run` or `npm run release:version -- --dry-run` when changing release-version logic.
+- Run `npm run sync-version`.
+- Run `npm run build:backend`.
+- If Rust is available, run `cargo check --manifest-path src-tauri/Cargo.toml`.
+- If the change touches the release workflow, confirm that the workflow still rejects a tag/version mismatch, still publishes only final user assets, and still prefers `docs/releases/<tag>.md` over auto-generated notes when that file exists.
+
+## Guardrails
+
+- Do not guess bundle resource paths or binary names.
+- Do not hand-edit version values when changing the automated version flow; keep `npm version ... --no-git-tag-version` as the writer for `package.json` and `package-lock.json`.
+- Do not reintroduce a hard-coded Windows installer filename into `package.json` scripts.
+- Do not blur the boundary between "release packaging/config" and "actual release execution"; use `clawbox-release-publish` when the task is to cut, commit, tag, or push a release.
+- Keep cross-platform branches explicit instead of merging them into a single simplified path.
+- Mention any skipped platform validation in the final response.

.agents/skills/clawbox-release-publish/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: clawbox-release-publish
+description: Use when the user asks to prepare, cut, validate, tag, or publish a ClawBox desktop release. Covers the UTC date-based version flow (`npm run release:version`), release validation commands, release commit/tag creation, and pushing the matching `v` tag for the current package version that triggers GitHub Releases. Do not use for changing packaging or versioning logic itself; use the packaging skill for that.
+---
+
+# ClawBox Release Publish
+
+Use this skill to run the current ClawBox release process end to end.
+
+## Read first
+
+- `docs/releasing.md`
+- `.github/release-notes-template.md`
+- `docs/releases/`
+- `package.json`
+- `scripts/release-version.mjs`
+- `scripts/sync-version.mjs`
+- `.github/workflows/release.yml`
+- `git status --short --branch`
+
+If the user also asks to create the commit or push the branch/tag, read `.agents/skills/clawbox-git-commit-push/SKILL.md`.
+
+## Workflow
+
+1. Inspect the worktree before starting. Stop if unrelated dirty changes would be mixed into the release.
+2. Fetch tags with `git fetch --tags` before generating a version. The UTC day sequence is based on local tags.
+3. Run `npm run release:version`. This updates `package.json`, `package-lock.json`, `src-tauri/tauri.conf.json`, and `src-tauri/Cargo.toml`.
+4. Read back the selected version with `node -p "require('./package.json').version"` and use that exact value for the release commit and tag.
+5. If the user wants curated release notes, copy `.github/release-notes-template.md` to `docs/releases/v<version>.md` and fill it in before the release commit. If that file is missing, GitHub falls back to auto-generated notes.
+6. Run the standard release validation set unless the user explicitly scopes it down:
+   - `npm run scan:repo`
+   - `npm run audit:licenses`
+   - `npm run audit:deps`
+   - `npm run build:frontend`
+   - `npm run build:backend`
+   - `cargo check --manifest-path src-tauri/Cargo.toml`
+7. If the user wants the release prepared but not published, stop after reporting the version, changed files, release notes status, and validation status.
+8. If the user wants the release published, create a focused commit for the release files, create tag `v<version>`, push the branch, then push the tag.
+
+## Expected commands
+
+Prepare the next release version:
+
+```bash
+git fetch --tags
+npm run release:version
+```
+
+Validate the release:
+
+```bash
+npm run scan:repo
+npm run audit:licenses
+npm run audit:deps
+npm run build:frontend
+npm run build:backend
+cargo check --manifest-path src-tauri/Cargo.toml
+```
+
+Publish after validation:
+
+```bash
+VERSION=$(node -p "require('./package.json').version")
+cp .github/release-notes-template.md "docs/releases/v${VERSION}.md"
+
+git add package.json package-lock.json src-tauri/tauri.conf.json src-tauri/Cargo.toml docs/releases/v${VERSION}.md
+git commit -m "release: v$VERSION"
+git tag "v$VERSION"
+git push origin HEAD
+git push origin "v$VERSION"
+```
+
+## Guardrails
+
+- Do not hand-edit the version fields when the goal is to cut a release. Use `npm run release:version`.
+- Do not create or push a tag that differs from `v<package.json version>`. The release workflow rejects mismatches.
+- Do not silently skip `git fetch --tags`; without it, the same UTC day can generate the wrong `-N`.
+- Do not stage unrelated files, generated artifacts, or user work that is outside the release scope.
+- Do not assume release notes are mandatory; if `docs/releases/<tag>.md` is absent, the workflow falls back to GitHub-generated notes.
+- Do not claim Windows signing was performed unless `WIN_SIGN_THUMBPRINT` or equivalent signing prerequisites were actually available.
+- If validation is incomplete, say exactly which commands were skipped or failed.
+
+## Verification
+
+- Confirm `package.json`, `package-lock.json`, `src-tauri/tauri.conf.json`, and `src-tauri/Cargo.toml` all reflect the same version after `npm run release:version`.
+- Run `npm run sync-version` after version generation only when you need to verify the sync chain; it should not create additional diffs.
+- After commit/tag creation, report the version, commit hash, branch, and pushed tag.

.agents/skills/clawbox-release-publish/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ClawBox Release"
+  short_description: "Run ClawBox UTC date-based release flow"
+  default_prompt: "Use $clawbox-release-publish to prepare or execute the next ClawBox release."

.agents/skills/clawbox-ui-i18n/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: clawbox-ui-i18n
+description: Use when changing ClawBox React components, dialogs, settings pages, sidebar flows, or any user-facing copy that must stay aligned with react-i18next and the project's bilingual locale files.
+---
+
+# ClawBox UI i18n
+
+Use this skill for ClawBox frontend UI work, copy changes, settings screens, onboarding screens, dialogs, and general React component changes.
+
+## Read first
+
+- The target component under `src/components/`
+- Any matching Zustand store under `src/store/`
+- `src/services/api.ts` if the component loads or mutates backend data
+- `src/locales/en/translation.json`
+- `src/locales/zh/translation.json`
+
+## Workflow
+
+1. Add or update translation keys before wiring UI text.
+2. Keep translation keys nested by feature instead of flattening unrelated labels into generic buckets.
+3. Prefer existing store actions and selectors over adding duplicate component-local copies of remote state.
+4. If a component opens dialogs or renders chat blocks, inspect the sibling components in the same feature folder before changing layout or behavior.
+
+## Verification
+
+- Update both locale files in the same diff.
+- Run `npm run build:frontend`.
+
+## Guardrails
+
+- Do not leave hard-coded user-facing strings in JSX.
+- Preserve existing Radix UI and Tailwind patterns unless the task explicitly redesigns the feature.
+- Keep frontend API usage centralized in service modules where possible.

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,46 @@
+---
+name: Bug report
+about: Report a reproducible ClawBox bug
+title: "[Bug] "
+labels: bug
+assignees: ""
+---
+
+## Summary
+
+Describe the bug clearly and briefly.
+
+## Environment
+
+- ClawBox version:
+- OpenClaw version:
+- OS / architecture:
+- Install mode: development / packaged app
+
+## Steps To Reproduce
+
+1.
+2.
+3.
+
+## Expected Behavior
+
+Describe what you expected to happen.
+
+## Actual Behavior
+
+Describe what actually happened.
+
+## Validation
+
+- [ ] `npm run build:frontend`
+- [ ] `npm run build:backend`
+- [ ] `npm run smoke:backend` if real OpenClaw was unavailable
+
+## Support Boundary
+
+- [ ] I believe this is a ClawBox client issue rather than a pure OpenClaw daemon/runtime issue
+
+## Logs / Screenshots
+
+Add relevant logs or screenshots after redacting tokens, personal paths, and private data.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security policy
+    url: https://github.com/CommonstackAI/clawbox/blob/main/SECURITY.md
+    about: Please read the private reporting guidance before sharing a vulnerability.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,27 @@
+---
+name: Feature request
+about: Suggest an improvement for ClawBox
+title: "[Feature] "
+labels: enhancement
+assignees: ""
+---
+
+## Problem
+
+What user problem or workflow gap should this solve?
+
+## Proposed Change
+
+Describe the behavior you want.
+
+## OpenClaw Compatibility
+
+Does this require new Gateway RPCs, config fields, or protocol changes?
+
+## Alternatives Considered
+
+List any alternatives you considered.
+
+## Additional Context
+
+Add links, screenshots, or related issues if helpful.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,26 @@
+## Summary
+
+- What changed?
+- Why was it needed?
+
+## Validation
+
+- [ ] `npm run build:frontend`
+- [ ] `npm run build:backend`
+- [ ] `cargo check --manifest-path src-tauri/Cargo.toml` when Tauri/package code changed
+- [ ] `npm run smoke:backend` when a real OpenClaw runtime was unavailable
+- [ ] `npm run scan:repo`
+- [ ] `npm run audit:deps`
+
+## Compatibility Notes
+
+- OpenClaw version impact:
+- Migration / rollout notes:
+
+## Screenshots / Logs
+
+Include screenshots or logs when the change affects UI or onboarding.
+
+## Ownership
+
+State whether the change is ClawBox-only or also requires coordinated OpenClaw updates.