@hybridaione/hybridclaw 0.2.10 → 0.3.0

package/CHANGELOG.md

@@ -2,12 +2,61 @@
 
 ## [Unreleased]
 
+## [0.3.0](https://github.com/HybridAIOne/hybridclaw/tree/v0.3.0)
+
+### Added
+
+- **Configurable sandbox modes**: Gateway start/restart now accept `--sandbox=container|host`, runtime config adds `container.sandboxMode`, and gateway/TUI status surfaces show the active sandbox mode so operators can avoid Docker-in-Docker when HybridClaw itself already runs inside a container.
+
+### Changed
+
+- **Container runtime hardening**: Container execution now drops Linux capabilities, disables privilege escalation, enforces a PID limit, uses a sized `/tmp` tmpfs, and adds `container.memorySwap` / `container.network` tuning alongside GHCR-first image pulls before the optional Docker Hub mirror.
+- **Packaged host runtime**: Root builds now compile and ship `container/dist/` so host sandbox mode can launch the bundled agent runtime from installed npm packages.
+- **Instruction sync workflow**: `hybridclaw audit instructions` now compares runtime copies in `~/.hybridclaw/instructions/` to installed package sources and uses `--sync` to restore shipped defaults instead of maintaining a local approval-hash baseline.
+
+### Fixed
+
+- **Release container publishing resilience**: Release-tag container publishing now always publishes GHCR even when Docker Hub credentials are absent, instead of failing before any registry push occurs.
+- **Install-root asset resolution**: Runtime docs/templates/instructions now resolve from the actual install root, so onboarding, prompt guardrails, workspace bootstrap files, and the built-in site no longer depend on `process.cwd()`.
+
+## [0.2.12](https://github.com/HybridAIOne/hybridclaw/tree/v0.2.12)
+
+### Added
+
+- **Automatic container publishing**: Added release-tag GitHub Actions publishing to Docker Hub (`hybridaione/hybridclaw-agent`) plus GHCR mirror (`ghcr.io/<org>/hybridclaw-agent`) with versioned tags (`vX.Y.Z`) and stable `latest` updates.
+- **Container build context guardrails**: Added `container/.dockerignore` and included it in npm package files so local secrets/artifacts are excluded from image build context.
+
+### Changed
+
+- **Runtime data default location**: Runtime config and data now default to `~/.hybridclaw` (`config.json`, `data/hybridclaw.db`, audit/session artifacts) to match home-directory workspace best practices.
+- **Container bootstrap pull order**: Container readiness now pulls prebuilt images from Docker Hub first (`v<app-version>`, then `latest`) with GHCR fallback before local build.
+- **README scope cleanup**: Reduced README to user-facing install/runtime guidance and moved maintainer/developer internals to `CONTRIBUTING.md`.
+- **Container build script behavior**: `npm run build:container` now runs `docker build` directly without requiring host TypeScript tooling.
+
+### Fixed
+
+- **First-run migration completeness**: Startup now migrates legacy `./config.json` and `./data` into `~/.hybridclaw`, archives legacy files, and stores migration backups under `~/.hybridclaw/migration-backups/` on conflicts.
+- **Install-root write issues**: Container image fingerprint state now persists under `~/.hybridclaw/container-image-state` (with legacy state fallback) instead of package install directories.
+- **Duplicate Discord `/status` slash entries**: Slash command registration now keeps `status`/`approve` global-only and removes stale guild-scoped duplicates to avoid duplicate command entries in guild channels.
+
+## [0.2.11](https://github.com/HybridAIOne/hybridclaw/tree/v0.2.11)
+
 ### Added
 
+- **Model default controls across TUI/Discord**: Added `model default [name]` command support in gateway/TUI plus a Discord `/model` slash command (`info`, `default`) with configured model choices.
+- **Local proactive reminder delivery path**: Added queued proactive pull API (`GET /api/proactive/pull`) and TUI polling so scheduler/heartbeat reminders reliably surface in `tui` channels.
+- **Scheduler timestamp regression test**: Added coverage for legacy SQLite second-precision timestamps and interval due-time regression handling.
+
 ### Changed
 
+- **Cron tool reminder contract**: Cron `add` now accepts prompt aliases (`prompt`/`message`/`text`), supports relative one-shot scheduling via `at_seconds`, and documents prompt-as-instruction semantics for future model runs.
+- **Scheduler prompt framing**: Scheduled model turns now explicitly instruct execution of the provided instruction without follow-up questions.
+
 ### Fixed
 
+- **SQLite timestamp interpretation drift**: Scheduler now normalizes legacy `YYYY-MM-DD HH:MM:SS` task timestamps as UTC, preventing immediate re-fire bugs on interval tasks after timezone conversion.
+- **Silent reply normalization edge case**: API/stream silent-token replacement now emits `Message sent.` only for real `message` send actions and otherwise falls back to the latest successful tool result.
+
 ## [0.2.10](https://github.com/HybridAIOne/hybridclaw/tree/v0.2.10)
 
 ### Added

package/README.md

@@ -11,13 +11,14 @@ npm install -g @hybridaione/hybridclaw
 hybridclaw onboarding
 ```
 
-Latest release: [v0.2.10](https://github.com/HybridAIOne/hybridclaw/releases/tag/v0.2.10)
+Latest release: [v0.3.0](https://github.com/HybridAIOne/hybridclaw/releases/tag/v0.3.0)
 
-## Release highlights (v0.2.10)
+## Release highlights (v0.3.0)
 
-- Fixed HybridAI `400 invalid_function_parameters` failures by correcting `message.components` schema (`array` now defines `items`).
-- Improved HybridAI reliability by centralizing stream-fallback/retry error classification in the container runtime.
-- Added regression tests for message-tool schema validity and HybridAI retry/fallback behavior.
+- Gateway start/restart now support `--sandbox=container|host`, runtime config adds `container.sandboxMode`, and gateway/TUI status surfaces show the active mode.
+- Container execution is hardened with dropped capabilities, `no-new-privileges`, PID limits, configurable network/memory-swap controls, and better GHCR-first image handling.
+- Root builds now package `container/dist/` so host sandbox mode can launch the bundled agent runtime from installed npm packages.
+- Runtime docs/templates/instructions now resolve from the actual install root, and `hybridclaw audit instructions --sync` restores shipped instruction copies under `~/.hybridclaw/instructions/`.
 
 ## HybridAI Advantage
 
@@ -51,7 +52,7 @@ hybridclaw onboarding
 # 3) open /register in browser (optional) and confirm in terminal
 # 4) open /login?next=/admin_api_keys in browser and get an API key
 # 5) paste API key (or URL containing it) back into the CLI
-# 6) choose the default bot (saved to config.json) and save secrets to `.env`
+# 6) choose the default bot (saved to ~/.hybridclaw/config.json) and save secrets to `.env`
 
 # Start gateway backend (default)
 hybridclaw gateway
@@ -74,349 +75,31 @@ Runtime model:
 - If `DISCORD_TOKEN` is set, Discord runs inside gateway automatically.
 - `hybridclaw tui` is a thin client that connects to the gateway.
 - `hybridclaw gateway` and `hybridclaw tui` validate the container image at startup.
-- If the image is missing, it is built automatically.
-- Default rebuild policy is `if-stale`: when tracked container sources changed since last build, the image is rebuilt automatically.
-- Policy override (optional): env `HYBRIDCLAW_CONTAINER_REBUILD=if-stale|always|never`.
-
-HybridClaw best-in-class capabilities:
-
-- explicit trust-model acceptance during onboarding (recorded in `config.json`)
-- typed `config.json` runtime settings with defaults, validation, and hot reload
-- formal prompt hook orchestration (`bootstrap`, `memory`, `safety`, `proactivity`)
-- layered memory substrate: structured KV, semantic memory, typed knowledge graph entities/relations, canonical cross-channel sessions, and usage event persistence
-- lightweight DB evolution and concurrency hardening via `PRAGMA user_version` migrations, `journal_mode=WAL`, and `busy_timeout=5000`
-- Discord conversational UX: edit-in-place streaming responses, fence-safe chunking beyond Discord's 2000-char limit, phase-aware typing/reactions, adaptive debounce batching, per-user rate limits, health-driven self-presence, reply-chain-aware context, concise attachment-first screenshot replies, and humanized pacing (time-of-day slowdown, cooldown scaling, selective silence, read-without-reply, startup staggering)
-- token-efficient context assembly: per-message history truncation, hard history budgets with head/tail preservation, and head/tail truncation for oversized bootstrap files
-- runtime self-awareness in prompts: exact HybridClaw version/date, model, and runtime host metadata injected each turn for reliable "what version/model are you?" answers
-- proactive runtime layer with active-hours gating, push delegation (`single`/`parallel`/`chain`), depth-aware tool policy, and retry controls
-- trusted-coworker approval model for tool execution: Green (`just run`), Yellow (`narrate + 5s interrupt window`), Red (`explicit approval`) with `yes` (once), `yes for session`, `yes for agent`, and explicit deny (`no`, also `4`) plus pinned-red protections
-- structured audit trail: append-only hash-chained wire logs (`data/audit/<session>/wire.jsonl`) with tamper-evident immutability, normalized SQLite audit tables, and verification/search CLI commands
-- observability export: incremental `events:batch` forwarding with durable cursor tracking and bot-scoped ingest token lifecycle via `ingest-token:ensure`
-- model token telemetry in audit/observability events (`model.usage`) with API usage + deterministic fallback estimates
-- built-in usage aggregation (`usage summary|daily|monthly|model`) plus JSONL session exports (`export session [sessionId]`) for cost/debug visibility
-- gateway lifecycle controls: managed + unmanaged restart/stop flows with graceful shutdown fallback paths
-- instruction-integrity approval flow: core instruction docs (`AGENTS.md`, `SECURITY.md`, `TRUST_MODEL.md`) are hash-verified against a local approved baseline before TUI start
+- `container.sandboxMode` defaults to `container`, but if HybridClaw is already running inside a container and the setting is not explicitly pinned, the gateway auto-switches to `host` to avoid Docker-in-Docker.
+- Use `hybridclaw gateway start --sandbox=host` or `hybridclaw gateway restart --sandbox=host` to force host execution for a given launch.
+- On first run, HybridClaw automatically prepares that image (pulls a prebuilt image first, then falls back to local build if needed).
+- If container setup fails, run `npm run build:container` in the project root and retry.
 
 ## Configuration
 
-HybridClaw uses typed runtime config in `config.json` (auto-created on first run).
-
-- Start from `config.example.json` (reference)
-- Runtime watches `config.json` and hot-reloads most settings (model defaults, heartbeat, prompt hooks, limits, etc.)
-- `discord.guildMembersIntent` enables richer guild member context and better `@name` mention resolution in replies (requires enabling **Server Members Intent** in Discord Developer Portal)
-- `discord.presenceIntent` enables Discord presence events (requires enabling **Presence Intent** in Discord Developer Portal)
-- `discord.respondToAllMessages` is a global fallback for open-policy guild channels without explicit mode config (`false` mention-gated, `true` free-response)
-- `discord.commandMode` controls command access: `public` (any user can run slash/`!claw` commands) or `restricted` (only allowlisted users can run slash/`!claw` commands)
-- `discord.commandAllowedUserIds` is the allowlist used when `discord.commandMode` is `restricted`
-- `discord.commandUserId` is a legacy single-user allowlist alias; when set without `commandMode`, runtime treats command access as `restricted` for backward compatibility
-- `discord.commandsOnly` optional hard mode: if `true`, the bot ignores non-`!claw` messages and only accepts prefixed commands (still subject to `discord.commandMode`)
-- `discord.groupPolicy` controls guild channel scope: `open` (default, mention-first unless a channel is set to `free`), `allowlist`, or `disabled`
-- `discord.freeResponseChannels` is a Hermes-style channel ID list that gets free-response behavior while other channels remain mention-gated
-- `discord.textChunkLimit` controls Discord message chunk size (default `2000`)
-- `discord.maxLinesPerMessage` controls max lines per Discord chunk (default `17`)
-- `discord.humanDelay` controls natural delays between multi-part messages (`off|natural|custom`)
-- `discord.typingMode` controls typing indicator lifecycle (`instant|thinking|streaming|never`)
-- `discord.presence.*` enables dynamic self-presence health states (healthy/degraded/exhausted mapped to `online|idle|dnd`, plus maintenance `invisible` during shutdown)
-- `discord.lifecycleReactions.*` enables phase emoji transitions (`queued|thinking|toolUse|streaming|done|error`)
-- approval policy layer is configured via `.hybridclaw/policy.yaml` (`approval.pinned_red`, `workspace_fence`, pending/timeout controls, audit toggles)
-- `discord.ackReaction`, `discord.ackReactionScope`, and `discord.removeAckAfterReply` control acknowledgment reaction behavior
-- `discord.debounceMs` controls default inbound debounce; channel overrides can tune noisy channels
-- `discord.rateLimitPerUser` and `discord.rateLimitExemptRoles` enforce per-user sliding-window limits
-- `discord.suppressPatterns` blocks auto-reply triggers for suppression terms (case-insensitive)
-- `discord.maxConcurrentPerChannel` limits concurrent in-flight runs per channel
-- `discord.guilds.<guildId>.defaultMode` sets that guild's fallback mode in `open` policy (`mention` recommended)
-- `discord.guilds.<guildId>.channels.<channelId>.*` supports per-channel mode and behavior overrides (`mode`, `typingMode`, `debounceMs`, `ackReaction*`, `humanDelay`, `rateLimitPerUser`, `suppressPatterns`, `maxConcurrentPerChannel`)
-- `scheduler.jobs[]` defines config-backed proactive jobs with `schedule.kind` (`cron|every|at`), `action.kind` (`agent_turn|system_event`), and delivery targets (`channel|last-channel|webhook`)
-- `scheduler.jobs[].name` / `scheduler.jobs[].description` add optional human-readable labels for status/log output; runtime status persists `nextRunAt`
-- Config scheduler job metadata (last status, consecutive errors, one-shot completion) persists atomically in `data/scheduler-jobs-state.json`
-- Config scheduler jobs auto-disable after repeated failures (5 consecutive errors) and one-shot jobs retry on a bounded interval until successful
-- `memory.decayRate` and `memory.consolidationIntervalHours` control semantic-memory consolidation intensity/cadence
-- `sessionCompaction.tokenBudget` and `sessionCompaction.budgetRatio` tune compaction token budgeting behavior
-- Built-in Discord humanization behaviors include night/weekend pacing, post-exchange cooldown scaling (after 5+ exchanges, reset after 20 minutes idle), selective silence in active free-mode channels, short-ack read reactions, and reconnect staggered dequeue
-- Per-guild/per-channel mode takes precedence over `discord.respondToAllMessages`
-- Discord slash commands: `/status`, `/approve [view|yes|session|agent|no] [approval_id]`, `/channel-mode <off|mention|free>`, and `/channel-policy <open|allowlist|disabled>` (ephemeral replies)
-- `skills.extraDirs` adds additional enterprise/shared skill roots (lowest precedence tier)
-- `proactive.*` controls autonomous behavior (`activeHours`, `delegation`, `autoRetry`, `ralph`)
-- `proactive.ralph.maxIterations` enables Ralph loop (`0` off, `-1` unlimited, `>0` extra autonomous iterations before forcing completion)
-- TUI/Gateway command: `ralph on|off|set <n>|info` (`0` off, `-1` unlimited, `1-64` extra iterations)
-- `observability.*` controls push ingest into HybridAI (`events:batch` endpoint, batching, identity metadata)
-- Some settings require restart to fully apply (for example HTTP bind host/port)
-- Default bot is configured via `hybridai.defaultChatbotId` in `config.json`
-- `hybridai.maxTokens` sets the default completion budget per model call (default `4096`)
-
-Secrets remain in `.env`:
-
-- `HYBRIDAI_API_KEY` (required)
-- `DISCORD_TOKEN` (optional)
-- `WEB_API_TOKEN` and `GATEWAY_API_TOKEN` (optional API auth hardening)
-- observability ingest token is auto-managed via `POST /api/v1/agent-observability/ingest-token:ensure` and cached locally
-
-Trust-model acceptance is stored in `config.json` under `security.*` and is required before runtime starts.
-
-See [TRUST_MODEL.md](./TRUST_MODEL.md) for onboarding acceptance policy and [SECURITY.md](./SECURITY.md) for technical security guidelines.
-
-## Audit Trail
-
-HybridClaw records a forensic audit trail by default:
-
-- append-only per-session wire logs in `data/audit/<session>/wire.jsonl`
-- SHA-256 hash chaining (`_prevHash` -> `_hash`) for tamper-evident immutability
-- normalized query tables in SQLite (`audit_events`, `approvals`)
-- policy denials captured as approval/authorization events (for example blocked commands)
-
-Useful commands:
-
-- `hybridclaw audit recent 50`
-- `hybridclaw audit search "tool.call" 50`
-- `hybridclaw audit approvals 50 --denied`
-- `hybridclaw audit verify <sessionId>`
-- `hybridclaw audit instructions`
-- `hybridclaw audit instructions --approve`
-
-Instruction approval notes:
-
-- local baseline file: `data/audit/instruction-hashes.json`
-- `hybridclaw audit instructions` fails when instruction files differ from the approved baseline
-- `hybridclaw audit instructions --approve` updates the local approved baseline
-- `hybridclaw tui` performs this check before startup and prompts for approval when files changed
-- instruction approval actions are audit logged (`approval.request` / `approval.response`, action `instruction:approve`)
-
-## Observability Push
-
-HybridClaw can forward structured audit records to HybridAI's ingest API:
-
-- endpoint: `POST /api/v1/agent-observability/events:batch`
-- source: local `audit_events` table (ordered by `id`)
-- transport: bearer ingest token auto-fetched via `POST /api/v1/agent-observability/ingest-token:ensure` using `HYBRIDAI_API_KEY`
-- delivery: incremental batches with persisted cursor (`observability_offsets` table), max 1000 events and max 2,000,000-byte payload per request
-- token handling: token cache is stored locally in SQLite (`observability_ingest_tokens`) and automatically refreshed on ingest auth failures
-- token visibility: `model.usage` payloads include `promptTokens`, `completionTokens`, `totalTokens`, plus estimated and API-native counters for accuracy/coverage
-
-Config keys (in `config.json`):
-
-- `observability.enabled` (`true` by default)
-- `observability.baseUrl` (for example `https://hybridai.one`)
-- `observability.ingestPath` (`/api/v1/agent-observability/events:batch`)
-- `observability.botId` (defaults to `hybridai.defaultChatbotId` when empty)
-- `observability.agentId`, `observability.label`, `observability.environment`
-- `observability.flushIntervalMs`, `observability.batchMaxEvents`
-
-Runtime diagnostics:
-
-- local status endpoint `GET /api/status` includes an `observability` block (enabled/running/paused, cursor, last success/failure timestamps)
-
-## Agent workspace
-
-Each agent gets a persistent workspace with markdown files that shape its personality and memory:
-
-| File | Purpose |
-|------|---------|
-| `SOUL.md` | Personality, tone, identity |
-| `IDENTITY.md` | Name, avatar, emoji |
-| `USER.md` | Info about the human |
-| `MEMORY.md` | Persistent memory across sessions |
-| `AGENTS.md` | Workspace conventions and rules |
-| `TOOLS.md` | Environment-specific notes |
-| `HEARTBEAT.md` | Periodic tasks |
-| `BOOT.md` | Startup instructions |
-
-Templates in `templates/` are copied to new agent workspaces on first run.
-Historical turn logs are mirrored into `<workspace>/.session-transcripts/*.jsonl` for `session_search`.
-
-## Skills
-
-HybridClaw supports `SKILL.md`-based skills (`<skill-name>/SKILL.md`).
-
-### Where to put skills
-
-You can place skills in:
-
-- any directory listed in `config.skills.extraDirs[]` (enterprise/shared)
-- bundled package skills (`<hybridclaw install>/skills/<skill-name>/SKILL.md`)
-- `$CODEX_HOME/skills/<skill-name>/SKILL.md` or `~/.codex/skills/<skill-name>/SKILL.md`
-- `~/.claude/skills/<skill-name>/SKILL.md`
-- `~/.agents/skills/<skill-name>/SKILL.md`
-- `./.agents/skills/<skill-name>/SKILL.md` (project)
-- `./skills/<skill-name>/SKILL.md` (workspace)
-
-Load precedence is:
-
-- `extra < bundled < codex < claude < agents-personal < agents-project < workspace`
-- skills are merged by `name`; higher-precedence sources override lower-precedence ones
-
-Security scanning is trust-aware:
-
-- `bundled` sources are treated as `builtin` and not scanned
-- `workspace` sources (`./skills/`, `./.agents/skills/`) are scanned; `caution` is allowed, `dangerous` is blocked
-- `personal` sources (`~/.codex/skills/`, `~/.claude/skills/`, `~/.agents/skills/`) are scanned and blocked on `caution`/`dangerous`
-- scanner includes Hermes-derived regex checks, structural limits (50 files, 1MB total, 256KB/file, binary/symlink checks), invisible-unicode detection, and mtime+content-hash cache reuse
-
-### Required format
-
-Each skill must be a folder with a `SKILL.md` file and frontmatter:
-
-```markdown
----
-name: repo-orientation
-description: Quickly map an unfamiliar repository and identify where a requested feature should be implemented.
-user-invocable: true
-disable-model-invocation: false
-always: false
-requires:
-  bins: [docker, git]
-  env: [GITHUB_TOKEN]
-metadata:
-  hybridclaw:
-    tags: [devops, docker]
-    related_skills: [kubernetes]
----
-
-# Repo Orientation
-...instructions...
-```
-
-Supported frontmatter keys:
-
-- `name` (required)
-- `description` (required)
-- `user-invocable` (optional, default `true`)
-- `disable-model-invocation` (optional, default `false`)
-- `always` (optional, default `false`; embeds full skill body in the system prompt up to `maxAlwaysChars=10000`, then demotes to summary)
-- `requires.bins` / `requires.env` (optional; skill is excluded unless requirements are met)
-- `metadata.hybridclaw.tags` / `metadata.hybridclaw.related_skills` (optional metadata namespace)
+HybridClaw creates `~/.hybridclaw/config.json` on first run and hot-reloads most runtime settings.
 
-### Using skills
-
-Skills are listed to the model as metadata (`name`, `description`, `location`), and the model reads `SKILL.md` on demand with the `read` tool. Skills with `always: true` are embedded directly in the system prompt.
-
-Prompt embedding modes:
-
-- `Always`: `always: true` embeds full body in `<skill_always ...>` (budgeted by `maxAlwaysChars=10000`)
-- `Summary`: default mode, emits only XML metadata under `<available_skills>`
-- `Hidden`: `disable-model-invocation: true` excludes the skill from model prompt metadata (still invocable by slash command when `user-invocable: true`)
-
-Explicit invocation is supported via:
-
-- `/skill <name> [input]`
-- `/skill:<name> [input]`
-- `/<name> [input]` (when `user-invocable: true`; command names are sanitized to lowercase `a-z0-9-`, max 32 chars, with `-2`/`-3` dedup and built-in command-name blocking)
-
-Example skill in this repo:
-
-- `skills/repo-orientation/SKILL.md`
-- `skills/current-time/SKILL.md`
-- `skills/personality/SKILL.md`
-- `skills/skill-creator/SKILL.md`
-
-### Personality switching skill
-
-HybridClaw includes a command-only personality skill that updates the active persona contract in `SOUL.md`.
-
-- List current/available persona: `/personality` (or `/personality list`)
-- Activate persona: `/personality <name>`
-- Reset to default persona: `/personality reset`
-
-The skill writes/updates a managed block in `SOUL.md`:
-
-- `## Active personality`
-- `Name: ...`
-- `Definition: ...` (copied from the selected profile in `skills/personality/SKILL.md`)
-- `Rules: ...` (runtime style/behavior constraints)
-
-Notes:
-
-- The personality skill is intentionally command-only (`always: false`, `disable-model-invocation: true`) to avoid adding per-turn prompt overhead.
-- Profiles are defined in `skills/personality/SKILL.md` and currently include 25 switchable personas (expert, style, and role personas).
-
-## Agent tools
-
-The agent has access to these sandboxed tools inside the container:
-
-- `read` / `write` / `edit` / `delete` — file operations
-- `glob` / `grep` — file search
-- `bash` — shell command execution
-- `memory` — durable memory files (`MEMORY.md`, `USER.md`, `memory/YYYY-MM-DD.md`)
-- `session_search` — search/summarize historical sessions from transcript archives
-- `delegate` — push-based background subagent tasks (`single`, `parallel`, `chain`) with auto-announced completion (no polling)
-- `web_fetch` — plain HTTP fetch + extraction for static/read-only content (docs, articles, READMEs, JSON/text APIs, direct files)
-- `browser_*` (optional) — full browser automation for JS-rendered or interactive pages (`navigate`, `snapshot`, `click`, `type`, `upload`, `press`, `scroll`, `back`, `screenshot`, `pdf`, `close`)
-
-`delegate` mode examples:
-
-- single: `{ "prompt": "Audit auth middleware and list risks", "label": "auth-audit" }`
-- parallel: `{ "mode": "parallel", "label": "module-audit", "tasks": [{ "prompt": "Scan api/" }, { "prompt": "Scan ui/" }] }`
-- chain: `{ "mode": "chain", "label": "implement-flow", "chain": [{ "prompt": "Scout the payment module" }, { "prompt": "Plan changes from: {previous}" }, { "prompt": "Implement based on: {previous}" }] }`
-
-Browser tooling notes:
-
-- Routing default: prefer `web_fetch` first for read-only retrieval.
-- Use browser tools for SPAs/web apps/auth flows/interaction tasks, or when `web_fetch` returns escalation hints (`javascript_required`, `spa_shell_only`, `empty_extraction`, `boilerplate_only`, `bot_blocked`).
-- Cost profile: browser calls are typically ~10-100x slower/more expensive than `web_fetch`.
-- Browser read flow: after `browser_navigate`, use `browser_snapshot` with `mode="full"` to extract content, then `browser_scroll` + `browser_snapshot` for additional lazy-loaded sections.
-- `browser_pdf` is for export artifacts, not text extraction.
-
-- The shipped container image preinstalls `agent-browser` and Chromium (Playwright).
-- You can override the binary via `AGENT_BROWSER_BIN` if needed.
-- User-directed authenticated browser-flow testing is supported (including filling/submitting login forms on the requested site).
-- Browser auth/session state now persists per HybridClaw session by default via a dedicated profile directory under `/workspace/.hybridclaw-runtime/browser-profiles`.
-- Session cookies/localStorage are also auto-saved/restored via `agent-browser` session-state files.
-- Optional overrides: `BROWSER_PERSIST_PROFILE=false` (disable profile persistence), `BROWSER_PERSIST_SESSION_STATE=false` (disable state file persistence), `BROWSER_PROFILE_ROOT=/path` (custom profile root), `BROWSER_CDP_URL=ws://...` (force CDP attachment to an existing browser).
-- Structured audit logs redact sensitive browser/tool arguments (password/token/secret fields and typed form text).
-- Navigation to private/loopback hosts is blocked by default (set `BROWSER_ALLOW_PRIVATE_NETWORK=true` to override).
-- Screenshot/PDF outputs are constrained to `/workspace/.browser-artifacts`.
-
-HybridClaw also supports automatic session compaction with pre-compaction memory flush:
-
-- when a session gets long, old turns are summarized into `session_summary`
-- before compaction, the agent gets a `memory`-only flush turn to persist durable notes
-- each `(agent_id, user_id)` pair also maintains a canonical cross-channel session for continuity across channels
-- canonical context injection includes compacted summary + recent cross-channel messages (excluding the current live session)
-- compaction writes JSONL exports to `<workspace>/.session-exports/` for human-readable debugging
-
-System prompt assembly is handled by a formal hook pipeline:
-
-- `bootstrap` hook (workspace bootstrap + skills metadata)
-- `memory` hook (session summary)
-- `safety` hook (runtime guardrails / trust-model constraints)
-- `proactivity` hook (memory capture, session recall, delegation behavior)
-
-Hook toggles live in `config.json` under `promptHooks`.
-
-## Testing
-
-Run checks locally:
-
-```bash
-# Typecheck only (no emit)
-npm run typecheck
-
-# Strict TS lint gate (unused locals/params)
-npm run lint
-
-# Unit tests (default `npm test`)
-npm run test:unit
-
-# Scoped suites (ready for dedicated tests)
-npm run test:integration
-npm run test:e2e
-npm run test:live
-```
-
-Test layout and scopes:
-
-- tests live under `tests/` (not `src/`)
-- unit tests: `tests/**/*.test.ts` (excluding `*.integration|*.e2e|*.live`)
-- integration tests: `tests/**/*.integration.test.ts`
-- e2e tests: `tests/**/*.e2e.test.ts`
-- live tests: `tests/**/*.live.test.ts`
+- Start from `config.example.json` (reference).
+- Runtime data is stored in `~/.hybridclaw/` by default (`config.json`, `data/hybridclaw.db`, audit/session files).
+- On upgrade, legacy `./config.json` and `./data` are migrated to `~/.hybridclaw` automatically; backups are kept in `~/.hybridclaw/migration-backups/` when needed.
+- `container.*` controls execution isolation, including `sandboxMode`, `memory`, `memorySwap`, `cpus`, `network`, and additional mounts.
+- Keep secrets in `.env` (`HYBRIDAI_API_KEY` required, `DISCORD_TOKEN` optional).
+- Trust-model acceptance is stored in `~/.hybridclaw/config.json` under `security.*` and is required before runtime starts.
+- See [TRUST_MODEL.md](./TRUST_MODEL.md) for onboarding acceptance policy and [SECURITY.md](./SECURITY.md) for technical security guidelines.
+- For advanced configuration, audit/observability details, skills internals, agent tools, and developer docs, see [CONTRIBUTING.md](./CONTRIBUTING.md).
 
 ## Commands
 
 CLI runtime commands:
 
 - `hybridclaw --version` / `-v` — Print installed HybridClaw version
-- `hybridclaw gateway start [--foreground]` — Start gateway (backend by default; foreground with flag)
-- `hybridclaw gateway restart [--foreground]` — Restart managed gateway backend process
+- `hybridclaw gateway start [--foreground] [--sandbox=container|host]` — Start gateway (backend by default; foreground with flag)
+- `hybridclaw gateway restart [--foreground] [--sandbox=container|host]` — Restart managed gateway backend process
 - `hybridclaw gateway stop` — Stop managed gateway backend process
 - `hybridclaw gateway status` — Show lifecycle/API status
 - `hybridclaw gateway <command...>` — Send a command to a running gateway (for example `sessions`, `bot info`)
@@ -424,6 +107,7 @@ CLI runtime commands:
 - `hybridclaw onboarding` — Run HybridAI account/API key onboarding
 - `hybridclaw update [status|--check] [--yes]` — Check for updates and upgrade global npm installs (source checkouts get git-based update instructions)
 - `hybridclaw audit ...` — Verify and inspect structured audit trail (`recent`, `search`, `approvals`, `verify`, `instructions`)
+- `hybridclaw audit instructions [--sync]` — Compare runtime instruction copies under `~/.hybridclaw/instructions/` against installed sources and restore shipped defaults when needed
 
 In Discord, use `!claw help` to see all commands. Key ones:
 
@@ -441,18 +125,3 @@ In Discord, use `!claw help` to see all commands. Key ones:
 - `!claw schedule add "<cron>" <prompt>` — Add cron scheduled task
 - `!claw schedule add at "<ISO time>" <prompt>` — Add one-shot task
 - `!claw schedule add every <ms> <prompt>` — Add interval task
-
-## Project structure
-
-```
-src/gateway.ts                    Core runtime entrypoint (DB, scheduler, heartbeat, HTTP API)
-src/tui.ts                        Terminal adapter (thin client to gateway)
-src/channels/discord/runtime.ts   Discord runtime integration and message transport
-src/channels/discord/*.ts         Discord responsibility modules (inbound, delivery, mentions, attachments, tools, stream)
-src/gateway-service.ts            Core shared agent/session logic used by gateway API
-src/gateway-client.ts             HTTP client used by thin clients (e.g. TUI)
-tests/                            Vitest suites (unit/integration/e2e/live scopes)
-container/src/                    Agent code (tools, HybridAI client, IPC)
-templates/                        Workspace bootstrap files
-data/                             Runtime data (gitignored): SQLite DB, sessions, agent workspaces
-```

package/config.example.json

@@ -1,5 +1,5 @@
 {
-  "version": 5,
+  "version": 6,
   "security": {
     "trustModelAccepted": false,
     "trustModelAcceptedAt": "",
@@ -69,9 +69,12 @@
     "models": ["gpt-5-nano", "gpt-5-mini", "gpt-5"]
   },
   "container": {
+    "sandboxMode": "container",
     "image": "hybridclaw-agent",
     "memory": "512m",
+    "memorySwap": "",
     "cpus": "1",
+    "network": "bridge",
     "timeoutMs": 300000,
     "additionalMounts": "",
     "maxOutputBytes": 10485760,
@@ -92,7 +95,7 @@
     "webApiToken": "",
     "gatewayBaseUrl": "http://127.0.0.1:9090",
     "gatewayApiToken": "",
-    "dbPath": "data/hybridclaw.db",
+    "dbPath": "~/.hybridclaw/data/hybridclaw.db",
     "logLevel": "info"
   },
   "observability": {
@@ -158,6 +161,8 @@
         "description": "Runs standup summary every weekday at 9am.",
         "schedule": {
           "kind": "cron",
+          "at": null,
+          "everyMs": null,
           "expr": "0 9 * * 1-5",
           "tz": "America/New_York"
         },
@@ -168,7 +173,8 @@
         "delivery": {
           "kind": "channel",
           "channel": "discord",
-          "to": "123456789012345678"
+          "to": "123456789012345678",
+          "webhookUrl": ""
         },
         "enabled": false
       }

package/container/.dockerignore

@@ -0,0 +1,16 @@
+node_modules
+dist
+.env
+.env.*
+.npmrc
+npm-debug.log*
+yarn-error.log*
+*.pem
+*.key
+*.crt
+*.p12
+*.pfx
+*.kubeconfig
+*.sqlite
+*.db
+*.log