chore: update WASM artifact checksums and version-pinned URLs

.env.example

@@ -1,4 +1,5 @@
 # Database Configuration
+DATABASE_BACKEND=postgres  # Pin postgres for compose/local server mode; otherwise ~/.ironclaw/ironclaw.db can auto-select libsql
 DATABASE_URL=postgres://localhost/ironclaw
 DATABASE_POOL_SIZE=30  # multi-tenant default; reduce to 5-10 for single-user or low-resource deployments
 
@@ -195,6 +196,12 @@ HEARTBEAT_INTERVAL_SECS=1800
 HEARTBEAT_NOTIFY_CHANNEL=cli
 HEARTBEAT_NOTIFY_USER=default
 
+# Local IronClaw home directory mounted into Docker when using docker-compose.yml.
+# Set this to ~/.ironclaw to reuse an existing host home; leave unset to use repo-local state.
+# IRONCLAW_HOME_DIR=~/.ironclaw
+# Docker Compose stores recent local history in the external Docker volume `ironclaw-pgdata`.
+# Create it once with: docker volume create ironclaw-pgdata
+
 # Memory hygiene settings (automatic cleanup of stale workspace documents)
 # Runs on each heartbeat tick; discovers cleanup targets from .config metadata
 # MEMORY_HYGIENE_ENABLED=true

.gitattributes

@@ -1 +1,2 @@
-tests/test-pages/**/*.html linguist-generated=true
+tests/test-pages/**/*.html linguist-generated=true
+migrations/*.sql text eol=lf

.github/FORK_WORKFLOW.md

@@ -0,0 +1,187 @@
+# Fork Workflow & Container Management
+
+Quick reference for maintaining and updating the JZKK720 fork of IronClaw.
+
+## Current Status
+
+- **Local Version**: 0.28.0 (from `Cargo.toml`)
+- **Fork**: `github.com/JZKK720/ironclaw` (origin)
+- **Upstream**: `github.com/nearai/ironclaw` (upstream, fetch-only)
+- **Container Registry**: `ghcr.io/jzkk720/ironclaw` (no local builds)
+- **Database Volume**: `pgdata_v025` (PostgreSQL)
+
+## Common Tasks
+
+### 1. Check Fork Status
+
+```bash
+# Sync git metadata
+git fetch origin && git fetch upstream
+
+# See what's unique in fork vs upstream
+git log --oneline upstream/main..origin/main
+
+# See what's behind
+git log --oneline origin/main..upstream/main
+```
+
+### 2. Pull Latest Container Images (Default: `:latest`)
+
+Your `docker-compose.yml` uses `:latest` tag by default, which means `docker compose pull` automatically fetches the newest image whenever you run it:
+
+```bash
+# Get the latest from GHCR (no local build needed)
+docker compose pull
+
+# Restart with new images
+docker compose up -d
+
+# Verify the version
+docker exec ironclaw ironclaw --version
+```
+
+Version updates happen automatically — as versions change (0.28.0 → 0.29.0 → etc.), the next `pull` gets the new image without any tag changes needed.
+
+### 3. Pin to Specific Version (Optional)
+
+If you need a specific version instead of `:latest`:
+
+```bash
+# Pin to v0.28.0 (for example)
+export IRONCLAW_TAG=0.28.0
+docker compose pull
+docker compose up -d
+
+# Or edit docker-compose.yml directly and change:
+# image: ghcr.io/jzkk720/ironclaw:0.28.0
+```
+
+### 4. Merge Upstream Changes
+
+```bash
+# Fetch upstream to see latest
+git fetch upstream
+
+# Compare main branches
+git log --oneline upstream/main..origin/main  # commits in fork not in upstream
+git log --oneline origin/main..upstream/main  # commits in upstream not in fork
+
+# Cherry-pick specific commits from upstream
+git cherry-pick <commit-hash>
+
+# Or do a full merge (if appropriate)
+git merge upstream/main
+
+# Push to fork
+git push origin main
+```
+
+### 5. Release a New Version
+
+```bash
+# Update version in Cargo.toml
+sed -i 's/version = "0.28.0"/version = "0.29.0"/' Cargo.toml
+
+# Commit
+git add Cargo.toml
+git commit -m "chore(fork): bump to v0.29.0"
+
+# Push to origin/main
+git push origin main
+
+# CI will automatically:
+# - Build the image
+# - Tag as :0.29.0 (version tag)
+# - Tag as :latest
+# - Tag as :sha-<7chars> (commit hash)
+# - Publish to ghcr.io/jzkk720/ironclaw
+```
+
+### 6. Test Changes on Staging Branch
+
+```bash
+# Create/update feature on staging branch
+git checkout staging
+git add .
+git commit -m "test: new feature"
+git push origin staging
+
+# CI will automatically:
+# - Build every hour (cron job)
+# - Tag as :staging
+# - Publish to ghcr.io/jzkk720/ironclaw:staging
+
+# Pull and test locally
+docker pull ghcr.io/jzkk720/ironclaw:staging
+docker run -it ghcr.io/jzkk720/ironclaw:staging ironclaw --help
+
+# When ready, merge to main
+git checkout main
+git merge staging
+git push origin main
+```
+
+## Container Image Tags
+
+| Tag | When | Source | Usage |
+|-----|------|--------|-------|
+| `:latest` | Release only | `main` branch | Production, default pull |
+| `:staging` | Hourly | `staging` branch | Testing, nightly builds |
+| `:0.28.0` | Release only | Version in Cargo.toml | Pinned releases |
+| `:sha-abc1234` | Every build | Git commit hash | Specific commit debugging |
+
+## Local Environment
+
+Your local runtime preserves:
+
+- ✅ `.env` — Database credentials, LLM config, API keys
+- ✅ `pgdata_v025/` — PostgreSQL database volume (persists across restarts)
+- ✅ `extensions/ironclaw-home/` — Custom extensions and skills
+- ✅ `~/.ironclaw/` — Settings, workspace, persistent memory
+
+These are **never** deleted or reset when running `docker compose up/down` or pulling new images.
+
+## Troubleshooting
+
+### Container doesn't have latest code
+
+```bash
+# Check what's running
+docker inspect ironclaw | grep -i image
+
+# Force pull latest
+docker compose pull --no-parallel
+docker compose down && docker compose up -d
+```
+
+### Database issues after update
+
+```bash
+# Check PostgreSQL health
+docker exec ironclaw pg_isready
+
+# View logs
+docker compose logs postgres
+
+# If needed, the volume pgdata_v025 persists between runs
+# Only delete if you want to reset the database
+docker volume rm pgdata_v025
+```
+
+### Git divergence
+
+```bash
+# See exactly what's different
+git log --graph --oneline --decorate --all
+
+# Resync to a known good state
+git fetch origin
+git reset --hard origin/main  # Local changes will be lost!
+```
+
+## References
+
+- **Main docs**: See [AGENTS.md](../AGENTS.md) for detailed architecture
+- **Workflows**: `.github/workflows/docker.yml` — Container build & publish
+- **Release process**: `.github/workflows/release.yml` — Version bumping
+- **Compose file**: `docker-compose.yml` — Local runtime configuration

.github/copilot-instructions.md

@@ -0,0 +1,79 @@
+# IronClaw — Copilot Instructions
+
+IronClaw is a secure, self-expanding personal AI assistant written in Rust (tokio async, axum, wasmtime). See [AGENTS.md](../AGENTS.md) for the authoritative agent contract and [CLAUDE.md](../CLAUDE.md) for the full development guide.
+
+## Build & Test
+
+```bash
+cargo fmt
+cargo clippy --all --benches --tests --examples --all-features  # zero warnings required
+cargo test                                        # unit tests
+cargo test --features integration                 # + PostgreSQL tests
+RUST_LOG=ironclaw=debug cargo run                 # run with logging
+```
+
+**Windows — Smart App Control blocks freshly compiled binaries.** Use Docker as the authoritative build path:
+```powershell
+docker compose up -d --build ironclaw
+```
+
+## Docker Build Modes
+
+- For deploy-like validation, stay in pull mode: `docker compose pull` and then `docker compose up -d --no-build postgres ironclaw`.
+- `ironclaw-worker` is still a required runtime image for orchestrated job containers, but its compose service is build-only; do not start it with `docker compose up` unless you are explicitly testing that image build.
+- Engine v2 `/project/` sandboxing is a different container path driven by [crates/Dockerfile.sandbox](../crates/Dockerfile.sandbox) and [docs/plans/2026-04-10-engine-v2-sandbox.md](../docs/plans/2026-04-10-engine-v2-sandbox.md). Do not remove `Dockerfile.worker` or the `SANDBOX_IMAGE` path without first auditing [src/config/sandbox.rs](../src/config/sandbox.rs), [src/orchestrator/job_manager.rs](../src/orchestrator/job_manager.rs), [src/cli/mod.rs](../src/cli/mod.rs), and [src/bridge/sandbox/](../src/bridge/sandbox/).
+- For pull-based local rollouts, treat `.env`, `IRONCLAW_HOME_DIR`, and the external `ironclaw-pgdata` volume as operator-owned state. Back them up before `docker compose pull` or container recreation.
+
+## Non-Negotiable Invariants
+
+| Rule | Scope |
+|------|-------|
+| No `.unwrap()` / `.expect()` in production code | All `src/` |
+| Zero clippy warnings — fix before committing | All changes |
+| All mutations from handlers/CLI go through `ToolDispatcher::dispatch()` | Handlers, CLI, channels |
+| New DB features must support both PostgreSQL **and** libSQL | `src/db/`, `migrations/` |
+| Check `FEATURE_PARITY.md` when any tracked behavior changes | All PRs |
+| Regression test with every bug fix | All PRs |
+| Use `crate::` for cross-module imports, `super::` only intra-module | All `src/` |
+
+## Module Specs (read before touching a subsystem)
+
+| Subsystem | Spec |
+|-----------|------|
+| `src/agent/` | [src/agent/CLAUDE.md](../src/agent/CLAUDE.md) |
+| `src/channels/web/` | [src/channels/web/CLAUDE.md](../src/channels/web/CLAUDE.md) |
+| `src/db/` | [src/db/CLAUDE.md](../src/db/CLAUDE.md) |
+| `src/llm/` | [src/llm/CLAUDE.md](../src/llm/CLAUDE.md) |
+| `src/tools/` | [src/tools/README.md](../src/tools/README.md) |
+| `src/workspace/` | [src/workspace/README.md](../src/workspace/README.md) |
+| `crates/ironclaw_engine/` | [crates/ironclaw_engine/CLAUDE.md](../crates/ironclaw_engine/CLAUDE.md) |
+
+## Extracted Crates
+
+Safety logic lives in `crates/ironclaw_safety/`; skills in `crates/ironclaw_skills/`. Import directly — `src/safety/mod.rs` and `src/skills/mod.rs` are thin shims that no longer glob-re-export. Use `use ironclaw_safety::SafetyLayer` not `crate::safety::SafetyLayer`.
+
+## Subsystem Rules (auto-applied by file pattern)
+
+Detailed rules live in [.claude/rules/](../.claude/rules/) and are surfaced as VS Code instructions:
+
+- [database.instructions.md](instructions/database.instructions.md) → `src/db/**`, `migrations/**`
+- [testing.instructions.md](instructions/testing.instructions.md) → `src/**/*.rs`, `tests/**`
+- [tools-and-dispatch.instructions.md](instructions/tools-and-dispatch.instructions.md) → `src/tools/**`, `src/channels/**`, `src/cli/**`
+- [safety-and-sandbox.instructions.md](instructions/safety-and-sandbox.instructions.md) → `src/safety/**`, `src/sandbox/**`, `src/secrets/**`
+- [ci-cd.instructions.md](instructions/ci-cd.instructions.md) → `.github/workflows/**`, `Dockerfile*`, `docker-compose.yml`
+- [local-ops.instructions.md](instructions/local-ops.instructions.md) → `docker-compose.yml`, `.env`, `README.md`, `deploy/**`, `docs/drafts/install/**`, `docs/drafts/platforms/**`
+- [telegram-channel.instructions.md](instructions/telegram-channel.instructions.md) → `channels-src/telegram/**`
+
+## Useful Prompts
+
+| Prompt | Purpose |
+|--------|---------|
+| `/smoke-test-telegram` | Smoke-test the Telegram WASM channel end-to-end |
+| `/check-pr-ready` | Run the pre-commit discipline checklist before opening a PR |
+| `/sync-upstream` | Step-by-step guide to manually merge upstream/main into fork/main |
+| `/validate-ghcr-upgrade` | Audit whether upstream changes are safe to publish to fork GHCR and whether downstream update/install channels will actually pick them up |
+| `/validate-installer-release-channel` | Audit whether PowerShell, shell, MSI, cargo-dist releases, and embedded registry URLs actually resolve to the fork-owned release channel |
+| `/update-local-docker-runtime` | Backup-first guide to pull new GHCR images into the local Docker stack without losing `.env`, bind-mounted state, or the external Postgres volume |
+| `/add-wasm-channel` | Scaffold a new WASM channel from scratch |
+| `/diagnose-startup` | Diagnose and fix Docker Compose startup failures where ironclaw or postgres won't start without a manual reboot |
+| `/intake-upstream-version` | End-to-end guide to merge a specific upstream release version (e.g. 0.28.2) into fork/main and publish updated GHCR images |

.github/instructions/ci-cd.instructions.md

@@ -0,0 +1,61 @@
+---
+applyTo: ".github/workflows/**,docker-compose.yml,Dockerfile,Dockerfile.worker,Dockerfile.test"
+description: "CI/CD, Docker, and build rules for IronClaw. Apply when editing GitHub Actions workflows, docker-compose.yml, or Dockerfiles."
+---
+
+# CI/CD & Build Rules
+
+## Windows — Smart App Control
+
+**On Windows, Smart App Control blocks freshly compiled Rust binaries.** Docker is the only viable build and test path on Windows:
+
+```powershell
+docker compose up -d --build ironclaw   # build + run
+docker compose exec ironclaw cargo test  # run tests inside container
+```
+
+Never attempt `cargo run` or `cargo test` directly on Windows hosts in this repo.
+
+## GitHub Actions Workflows
+
+| Workflow | Trigger | Purpose |
+|----------|---------|---------|
+| `docker-publish.yml` | Push to `main` | Build + push `ironclaw` and `ironclaw-worker` to GHCR |
+| `sync-upstream.yml` | Weekly Mon 02:00 UTC + manual | Auto-merge `upstream/main` → `fork/main`; builds GHCR images inline |
+| `test.yml` | Push, PR | Cargo unit tests |
+| `staging-ci.yml` | Push to `staging` | Full integration test suite |
+| `claude-review.yml` | PR | Automated code review |
+
+## GHCR Image Names
+
+```
+ghcr.io/jzkk720/ironclaw:latest          # main runtime (target: runtime-staging)
+ghcr.io/jzkk720/ironclaw-worker:latest   # sandbox worker
+```
+
+The moving auto-update tag is `:latest`; workflows may also publish immutable `:sha-*` tags for traceability.
+
+## Dockerfile Build Targets
+
+| Target stage | Used for |
+|-------------|---------|
+| `runtime-staging` | Production image (used by `docker-publish.yml`) |
+| `runtime` | Base runtime without staging extras |
+| `builder` | Intermediate — do not use as final image |
+
+## sync-upstream Mechanics
+
+**GITHUB_TOKEN pushes do not re-trigger other workflows.** This is why `sync-upstream.yml` builds and pushes Docker images inline rather than relying on `docker-publish.yml` triggering after its push. If you add build steps to one workflow, check whether the other needs to be updated too.
+
+## Watchtower
+
+Watchtower is defined in `docker-compose.yml` and polls GHCR hourly. It only updates containers with label `com.centurylinklabs.watchtower.enable: "true"`. The `ironclaw` service has this label; `postgres` and others do not.
+
+**One-time host prerequisite** (already documented in docker-compose.yml):
+```bash
+docker login ghcr.io -u jzkk720 -p <PAT with read:packages>
+```
+
+## Concurrency
+
+Both `docker-publish.yml` and `sync-upstream.yml` use concurrency groups to prevent parallel builds of the same branch. `docker-publish.yml` cancels in-progress builds; `sync-upstream.yml` does not (to avoid skipping a sync).