clawdie-ai/README.md

<p align="center">
  <h1 align="center">🦞 Clawdie</h1>
</p>

<p align="center">
  <strong>Personal AI Assistant on FreeBSD</strong>
</p>

<p align="center">
  A lean, secure AI assistant running on FreeBSD 15 with native jail isolation.
</p>

<p align="center">
  <a href="https://docs.clawdie.si">Documentation</a>&nbsp; • &nbsp;
  <a href="https://clawdie.si">Website</a>&nbsp; • &nbsp;
  <a href="https://codeberg.org/Clawdie/Clawdie-AI">Codeberg</a>
</p>

<p align="center">
  <a href="repo-tokens"><img src="repo-tokens/badge.svg" alt="38.4k tokens, 19% of context window" valign="middle"></a>
  &nbsp;
  <a href="https://docs.clawdie.si/docs/split-brain.html"><img src="https://img.shields.io/badge/built--in%20knowledge-preloaded-2ab7ca" alt="built-in knowledge preloaded" valign="middle"></a>
</p>

<p align="center">
  <!-- token-count -->38.4k tokens · 19% of context window<!-- /token-count -->
  &nbsp; • &nbsp;
  built-in knowledge · preloaded
</p>

---

## Overview

Clawdie is a FreeBSD-first personal AI assistant with a host-side Node.js orchestrator and jailed agent execution. The core repo stays small, Telegram is built in, and additional channels or integrations are added through skills instead of being hard-wired into core.

## V2 Track

The `main` branch stays focused on the current working system. The
`multitenant` branch is the internal V2 track where Clawdie is refactored into
a host platform that can run tenant assistants such as `atlas` or `bob`.

That branch is for architecture work, not a feature race. The goal is to make
ownership, recovery, degraded mode, and FreeBSD-native multitenancy explicit
before any wider public launch.

## Current Release

`v0.10.0` (04.apr.2026)
Domain Defaults Fix

See [Changelog](html/docs-clawdie-si/changelog.html) for full release notes.

**Key Features:**

- 🏠 **Native FreeBSD** - No Linux emulation, native jail isolation
- 🔒 **Jail Isolation** - Secure OS-level containers with ZFS snapshots
- ⚡ **Better Performance** - Single layer: FreeBSD → Jail → Node.js
- 💾 **ZFS Integration** - Snapshots, quotas, compression, RAIDZ1 support
- 🌐 **Multi-Language Docs** - English, German, French, Spanish (Crowdin-managed)
- 📚 **Zero-Downtime Deployments** - Symlink-based versioning with instant rollback
- 🔄 **Automated Sync** - Daily documentation compilation & deployment @ 05:00 UTC
- 🔧 **Cloud & Baremetal** - ISO variants for VPS (headless) and physical hardware (GUI)
- 🔐 **SSH Keys & Passwords** - Pre-configured or interactive setup options
- 🔧 **CNC Ready** - clawdie-cnc for CNC machine control (in development)

## Why Clawdie?

### Why Jails Instead of Docker?

| Aspect          | Docker on FreeBSD         | FreeBSD Jails          |
| --------------- | ------------------------- | ---------------------- |
| Performance     | Good (emulation overhead) | **Excellent (native)** |
| Layers          | FreeBSD → Linux → Docker  | **FreeBSD → Jail**     |
| Security        | Good                      | **Excellent**          |
| Networking      | Docker bridge             | **Native IP**          |
| Complexity      | High                      | **Low**                |
| ZFS Integration | Manual                    | **Native**             |

**Result:** Simpler, faster, more secure.

### Why Clawdie?

[NanoClaw](https://github.com/qwibitai/nanoclaw) by Gavriel is the upstream line
we still track, and NanoClaw itself follows the broader
[OpenClaw](https://github.com/openclaw/openclaw) direction opened by
[Peter Steinberger](https://github.com/steipete). Clawdie takes that line onto
FreeBSD for operators who want:

- Native performance without Linux emulation
- ZFS integration for snapshots and quotas
- Simpler architecture (fewer layers)
- CNC machine integration for manufacturing

## Architecture

```
Telegram + scheduled tasks + IPC
  ↓
PostgreSQL ops database (messages, groups, tasks, sessions)
  ↓
Host orchestrator (Node.js)
  ↓
FreeBSD worker jail(s)
  ↓
Agent response
```

**Single Node.js process.** Agents execute in isolated FreeBSD worker jails with filesystem isolation via nullfs mounts. Only mounted directories are accessible. Per-group message queue with concurrency control. PostgreSQL defaults to host runtime (`DB_RUNTIME=host`) with platform-owned `system_*` databases: built-in skills/reference knowledge, user/agent memory, and operational state. A dedicated db jail remains available when explicitly selected. Ops + memory are required; the built-in skills artifact is committed and can be refreshed with `just refresh-skills-artifact` when docs or skills change.

### Key Files

- `src/index.ts` — orchestrator: state, message loop, agent invocation
- `src/hostd/` — privileged host daemon (types, ops, daemon, client)
- `src/controlplane.ts` — self-healing: checks hostd, service jails, PF; repairs via hostd
- `src/watchdog.ts` — memory throttle, run mode, control plane timer
- `src/channels/telegram.ts` — built-in Telegram channel
- `src/group-queue.ts` — per-group queue with global concurrency limit
- `src/agent-runner.ts` — spawns jailed agent processes
- `src/mount-security.ts` — mount allowlist enforcement
- `src/task-scheduler.ts` — scheduled tasks
- `src/db.ts` — PostgreSQL ops (messages, groups, sessions, state, routing)
- `setup/*.ts` — modular setup entrypoints
- `setup/service.ts` — generates `run-*.sh` wrappers at install time (not tracked in git)
- `groups/*/AGENTS.md` — per-group memory

A `justfile` provides discoverable command shortcuts. Run `just` (or `just --list`) to see all recipes. Prefer `just` for interactive work; `npm run <name>` remains for CI and scripting. The full installer is intentionally exposed as `just install` / `npm run install:clawdie` instead of the npm lifecycle name `install`.

Common mappings:

```
just install              # npm run install:clawdie
just install-from-db      # npm run install:clawdie -- --from db
just setup-db             # npm run setup -- --step db
just setup-cms            # npm run setup -- --step cms
```

## What It Supports

- **Telegram-first core** - Built-in Telegram channel plus headless/background operation.
- **Isolated group context** - Each group has its own `AGENTS.md` memory, isolated filesystem, and runs in its own jail sandbox with only that filesystem mounted.
- **Main channel** - Your private channel (self-chat) for admin control; every group is completely isolated.
- **Scheduled tasks** - Recurring jobs that run the AI agent and can message you back.
- **Jail isolation** - Agents are sandboxed in FreeBSD jails with ZFS snapshots.
- **Layered Memory Fabric** - PostgreSQL stores three platform-owned planes by default: `system_skills` for reviewed skills/reference knowledge, `system_brain` for user/agent memory, and `system_ops` for messages, tasks, sessions, routing, and runtime state. See [`docs/public/architecture/layered-memory-fabric.md`](docs/public/architecture/layered-memory-fabric.md).
- **Built-in payments, optional extras** - Stripe ships in core and is ready when configured; other channels and integrations can still be layered through skills.

## Installation

### Prerequisites

- FreeBSD 15.x
- ZFS root installation
- Root access or sudo
- Internet access for `pkg` and `npm`
- `bash` and `git` available before first run
- **`just`** — command runner (`pkg install just` on FreeBSD; preinstalled on Clawdie ISO)
- **At least one agent CLI on `PATH`**: one of `pi`, `aider`, `claude`, `codex`, or `gemini`. The controlplane harness uses Aider+Pi as the primary driver. Onboarding fails fast if none are present (see [`doc/AGENT-CLI-VALIDATION.md`](doc/AGENT-CLI-VALIDATION.md) for the validated install paths). The Clawdie ISO ships claude/gemini/pi via the npm-globals bundle, aider via `py311-aider_chat` pkg, and codex via `pkg install codex`.

Recommended explicit host baseline before first run:

```sh
sudo pkg install -y bash git bastille node24 npm tmux btop python311 uv ripgrep fd-find rsync postgresql18-client py311-pillow dejavu py311-aider_chat edk2-bhyve just
```

The `edk2-bhyve` package provides UEFI firmware required for optional browser-vm support
(FEATURE_BHYVE_GUI=YES in .env).

On FreeBSD, use `fd-find`. It provides the `fd` command that `pi` expects and
avoids colliding with the unrelated `fd` file manager package.

The host baseline also includes `py311-pillow` and `dejavu` so tmux screenshot
capture works without a separate `uv pip install Pillow` step.

If the host still has both Python 3.11 and 3.12 installed, pin `uv` to 3.11
explicitly until the generic `python3` path is cleaned up:

```sh
uv venv --python 3.11
uv run --python 3.11 <command>
```

### Operator Glasspane

The local operator cockpit lives in [`scripts/glass.sh`](scripts/glass.sh).
On a root/platform install it uses the tmux session name `glasspane`. On a
tenant install it uses `<tenant>-glasspane`.

```sh
# create and attach
sh scripts/glass.sh

# create without attaching (safe smoke test)
GLASS_ATTACH=0 sh scripts/glass.sh

# remove the glasspane session
sh scripts/glass.sh kill
```

On FreeBSD, keep `fd-find` installed. It provides the `fd` command that `pi`
expects inside the glasspane session.

First use:

- Start it with `sh scripts/glass.sh`.
- Window `0` (`glass`) contains `pi` on the left and `aider` on the right.
- Window `1` contains `btop`.
- Switch windows with `Ctrl-b 0` and `Ctrl-b 1`.
- Move between panes with `Ctrl-b` then an arrow key.
- Detach without killing the session with `Ctrl-b d`.
- Reattach later with `tmux attach -t glasspane`.
- Stop the session with `sh scripts/glass.sh kill`.

### Quick Start

```bash
# 1. Install the recommended FreeBSD host baseline
sudo pkg install -y bash git bastille node24 npm tmux btop python311 uv ripgrep fd-find rsync postgresql18-client py311-pillow dejavu py311-aider_chat just

# 2. Clone the repository
git clone https://codeberg.org/Clawdie/Clawdie-AI.git /home/clawdie/clawdie-ai
cd /home/clawdie/clawdie-ai

# 3. Bootstrap repo dependencies and hooks
./setup.sh

# 4. Ensure at least one agent CLI is on PATH (onboarding gates on this).
#    Pick whichever you use; the ISO bundle installs all supported CLIs offline.
pi --version >/dev/null 2>&1 || npm install -g @earendil-works/pi-coding-agent
# Optional alternates:
#   npm install -g @anthropic-ai/claude-code   # claude
#   npm install -g @google/gemini-cli          # gemini
#   sudo pkg install -y codex                  # codex (FreeBSD pkg)

# 5. Run the canonical install orchestrator
just install

# 6. If a step fails, fix the cause and resume from that step
just install-from-db

# 7. Validate the result
just doctor
```

If the host still has the old `fd` file manager package installed, `pkg` will
replace it with `fd-find`. That replacement is the intended FreeBSD baseline.

`just install` is the supported full path. The lower-level `setup/index.ts` steps remain available for debugging and targeted recovery, but new installs should prefer the orchestrator so checkpoints and resume behavior stay consistent.

### PI Profiles

`pi-tui` uses a single `PI_TUI_PROFILE` selector for common runtime scenarios:

- `setup` — onboarding and exact setup actions
- `operator` — normal daily runtime
- `status` — read-only health/status summaries
- `payments` — Stripe-safe support flow
- `docs` — docs and release copy
- `cms` — Astro/Strapi publishing work
- `git` — local git mirror and upstream sync
- `memory` — Layered Memory Fabric and PostgreSQL memory work
- `local` — Ollama/offline fallback
- `cnc` — CNC machine operation and G-code work

Check the resolved profile state with:

```sh
just setup -- --step pi-config
```

`pi-config` validates the active provider through Pi auth in
`~/.pi/agent/auth.json`, provider env vars in `.env`, or `OLLAMA_HOST`
for local Ollama.

List all built-in profiles with:

```sh
just setup -- --step pi-config --list-profiles
```

The Layered Memory Fabric database path is mandatory. Setup generates or preserves the
PostgreSQL and Strapi secrets in `.env`, then keeps `SKILLS_DB_URL`,
`MEMORY_DB_URL`, and `OPS_DB_URL` aligned with `AGENT_NAME`, subnet, and
passwords. The `db` step applies three distinct schema tracks:

- built-in knowledge tables in the skills DB
- dynamic hybrid-memory tables in the user/agent memory DB
- operational state tables in the ops DB (messages, tasks, sessions, routing)

The `db` step also imports the shipped built-in knowledge artifact by default.
`skills-memory --import` remains available as a manual re-import path. Maintainers refresh the committed artifact with `just refresh-skills-artifact`; the wrapper detects docs/skills/identity changes and checks OpenRouter budget before regenerating embeddings.
At runtime, the host queries the local skills DB before each jail run and
prepends the top built-in references to the prompt when relevant.

The active mandatory pieces are:

- `POSTGRES_ADMIN_PASSWORD`
- `SKILLS_DB_PASSWORD`
- `MEMORY_DB_PASSWORD`
- `OPS_DB_PASSWORD`
- `CONTROLPLANE_SHARED_SECRET`

For PostgreSQL identifiers, the root install uses the shared platform namespace
`system`, independent of `ASSISTANT_NAME` or `AGENT_NAME`. Platform databases
use `system_skills`, `system_brain`, `system_ops`, `system_git`, and
`system_web`. Later additive tenants get their own `<tenant>_*` databases.

`STRAPI_DB_PASSWORD` and the `STRAPI_*` app secrets feed the default internal
Strapi bootstrap inside the `cms` jail. They are generated
automatically if missing and should stay private to the CMS layer.

`npm run preflight-check` writes a full host validation bundle into
`tmp/preflight/<stamp>/`, including `summary.json` and `summary.env` for
the on-host agent. It includes `telegram-auth` in the default sequence;
`groups` and `register` remain post-deployment follow-up work
and no longer block base install verification on a fresh host.

Clawdie provisions local code hosting by default through the dedicated `git`
jail. The default mode is:

- `CODE_HOSTING_MODE=git`
- `FEATURE_GIT=YES`
- `WARDEN_GIT_IP=<subnet>.2`

The `git` step creates the shared `git` jail by default (`GIT_JAIL_NAME` can
override it), installs the git jail baseline, creates `/srv/git`, and mirrors
the current repository into a bare repository.

### Default IP Layout

The repo registry/default examples use `10.0.1.x`; live installs can override
this through `.env` with another private `/24` such as `192.168.72.x`. For a
running system, live jail state and `.env` are authoritative; this table is the
provisioning/default slot map from `infra/jails.yaml`:

- `.1` gateway on `warden0`
- `.2` `git` / Git Service
- `.3` `cms` / Web Service
- `.4` Local AI Models (`ollama` or `llama.cpp`, if enabled)
- `.5` optional `db` / Data Service when `DB_RUNTIME=jail`
- `.6` `browser` / Browser Execution Template
- `.101+` workers
- `.211` DB admin worker
- `.212` Git admin worker
- `.213` coordinator worker
- `.150+` ephemeral browser task clones

This keeps foundational services low in the range while leaving room for
multiple workers and avoiding overlap with host-facing web services. The CMS
stack stays on the private jail network instead of assuming control of host
nginx, which is the main reason the low fixed service slots matter.

### Naming and Local DNS

Current `main` separates public and internal naming:

- `AGENT_DOMAIN` is the public-facing site/API domain
- `AGENT_INTERNAL_DOMAIN` is the internal jail/service zone written into `/etc/hosts`

Fresh installs should keep public and internal names separate:

- `AGENT_DOMAIN=` until you have a real public DNS name configured
- `AGENT_INTERNAL_DOMAIN=<agent>.home.arpa` for local jail/service names

Why this changed:

- `.local` is reserved for mDNS and is a bad default for private service naming
- `home.arpa` is the safer standards-based internal namespace
- keeping public and internal names separate avoids accidentally treating a
  non-public jail hostname as if it were externally routable

## FreeBSD Milestone

<p align="center">
  <img src="docs/internal/tmux-screenshot-sample.png" alt="tmux diagnostic screenshot captured by Clawdie" width="720">
  <br>
  <em>Example tmux screenshot generated by Clawdie and sent as a Telegram photo</em>
</p>

Current runtime centers on:

- host-side orchestration in `src/index.ts`
- service-owned shared infrastructure (`clawdie` service, `system_*` platform resources)
- Bastille worker jails from `src/jail-config.ts`
- `just install` as the canonical install orchestrator
- mandatory DB bootstrap with built-in knowledge import when the artifact is present

### Simple Install Flow

```text
./setup.sh
  -> bootstrap repo dependencies and hooks
just install
  -> read first-boot setup seed or run onboarding fallback
  -> configure environment, pi, PF, jails, services, hostd
  -> provision Data Service, Git Service, Web Service when enabled
  -> verify install and report warnings
```

`ASSISTANT_NAME` is display-only. The root install remains the shared platform:
service name `clawdie`, platform namespace `system`, and no root `TENANT_ID`.
`groups` and `register` remain explicit follow-up steps after auth/state are
present; they are not part of the minimal first-boot path.

### Stripe Flow

```text
onboarding
  -> configure Stripe now? (or skip)
  -> write STRIPE_SECRET_KEY into .env
host agent-runner
  -> reads STRIPE_SECRET_KEY from .env
  -> passes it to jailed runtime in stdin JSON secrets payload
jailed agent runner
  -> merges secret into SDK env only
  -> registers Stripe MCP tools
agent chat
  -> can use payment, customer, invoice, and subscription tools
```

### Web Serving

nginx runs inside the Web Service (cms jail). By default, `setup/pf.ts` configures Warden egress (NAT) only; public ingress (PF `rdr`) is intentionally opt-in so Clawdie does not take over host ports 80/443 unexpectedly. Strapi (when used) is internal-only by default.

Operational docs for this milestone:

- [Bastille on FreeBSD 15](docs/public/architecture/bastille.md)
- [Jail Networking Strategy](docs/public/architecture/jail-networking.md)
- [PostgreSQL Memory Plan](docs/internal/POSTGRES-MEMORY.md)
- [Monitoring Model](docs/public/operate/monitoring.md)
- [Manual Reset and pi-tui Rebootstrap](docs/internal/CLEAN-RESET-PI-TUI.md)

## Usage

Talk to your assistant with the trigger word (default: `@Clawdie`):

```
@Clawdie send an overview of the sales pipeline every weekday morning at 9am
@Clawdie review the git history for the past week each Friday and update the README
@Clawdie every Monday at 8am, compile news on AI developments and message me a briefing
```

Run `just doctor` to check system health (runtime, jails, networking, services, DNS resolver probes, TLS certificate expiry, ACME renewal cron, morning-report schedule, and Layered Memory Fabric DB/artifact status). Exit codes: 0 = ok or warnings, 1 = error.

### TLS Certificate Lifecycle

Public edge certificates are managed by acme.sh on the FreeBSD host and installed under `/usr/local/etc/nginx/ssl/<label>/`. The TLS setup step is safe by default:

```sh
# Non-mutating local validation: acme binary, cron, nginx -t, webroots, challenge routes, cert parsing
sudo npx tsx setup/index.ts --step tls --smoke-test

# Repair/install lifecycle without forcing issuance: install acme.sh, install cert hooks, write /etc/cron.d/clawdie-acme
sudo npx tsx setup/index.ts --step tls --apply

# Force-renew one cert only when deliberately validating or recovering before expiry
sudo npx tsx setup/index.ts --step tls --apply --cert clawdie --force-renew
```

`just doctor` reports `TLS_<LABEL>` days remaining and `ACME_RENEWAL_CRON` status. Do not force-renew repeatedly; Let’s Encrypt rate-limits duplicate certificates.

From the main channel (your self-chat), you can manage groups and tasks:

```
@Clawdie list all scheduled tasks across groups
@Clawdie pause the Monday briefing task
@Clawdie join the Family Chat group
```

## Telegram Commands

A short selection — for the full reference (status, structured reports,
runtime, sessions, admin actions, free-text routing) see
[Operator Commands](docs/public/operate/operator-commands.md).

| Command          | Description                                                                    | Auth     |
| ---------------- | ------------------------------------------------------------------------------ | -------- |
| `/status`        | System summary: jails, ZFS, PF, budget, model                                  | anyone   |
| `/report`        | Structured system + auth report                                                | admin    |
| `/disk`          | Structured ZFS pool + snapshot report                                          | admin    |
| `/tasks`         | Structured controlplane task report                                            | admin    |
| `/budgetreport`  | Structured budget + token analytics                                            | admin    |
| `/publishreport` | Structured tenant publish/content report                                       | admin    |
| `/testreport`    | Structured build + test status (from wrapper-written JSON)                     | admin    |
| `/policy`        | Default runtime, per-chat overrides, fallback cooldowns                        | anyone   |
| `/usage`         | Per-agent token budget breakdown                                               | anyone   |
| `/clearcooldown` | Clear a [provider fallback](docs/public/operate/provider-fallback.md) cooldown | ops chat |
| `/compact`       | Compact session (summarize old, keep recent turns)                             | admin    |
| `/new`           | Hard reset session, start fresh                                                | admin    |
| `/stop`          | Kill running agent mid-response                                                | admin    |
| `/tts`           | Toggle voice replies (on/off/status/default)                                   | admin    |
| `/activation`    | Set trigger mode (always/mention)                                              | admin    |
| `/whoami`        | Show your Telegram identity                                                    | anyone   |
| `/help`          | List available commands                                                        | anyone   |

The bot also routes **free-text ops phrasings** ("disk usage", "are the
tests passing", "task report", etc.) to the matching structured report
instead of the LLM path — see
[Structured Reports → Free-Text Routing](docs/public/operate/structured-reports.md#free-text-routing).

### Session Compaction

When a conversation grows past the byte limit (`AGENT_SESSION_MAX_BYTES`), old turns are automatically summarized via the LLM and stored in the memory database. The session file is rewritten with a compaction header + last N turns at full fidelity. Manual compaction is available via `/compact`.

### Cost Model

Budget enforcement has been removed (26.maj.2026). DeepSeek prefix caching at ~98%
hit rate makes per-chat token budgets unnecessary.

### Text-to-Speech

Clawdie uses Microsoft Edge TTS (free, no API key) to generate voice replies. Configured via `TTS_AUTO_MODE`:

- `always` — every reply gets a voice message
- `inbound` — reply with voice when user sends a voice note
- `tagged` — only when agent output contains `[[tts]]` marker
- `off` — no voice messages

Per-chat override via `/tts` command.

## Customizing

Clawdie doesn't use configuration files. To make changes, just tell the AI agent what you want:

- "Change the trigger word to @Assistant"
- "Remember in the future to make responses shorter and more direct"
- "Add a custom greeting when I say good morning"
- "Store conversation summaries weekly"

Or run `/customize` for guided changes.

The codebase is small enough that the AI agent can safely modify it.

## Philosophy

**Small enough to understand.** One process, a few source files, no microservices. If you want to understand the full Clawdie codebase, ask the AI agent to walk you through it.

**Secure by isolation.** Agents run in FreeBSD jails with filesystem isolation via nullfs mounts. They can only access explicitly mounted directories. Bash access is safe because commands run inside the jail, not on your host.

**Built for the individual user.** Clawdie isn't a monolithic framework; it's software that fits each user's exact needs. You make your own fork and have the AI agent modify it to match your requirements.

**Customization = code changes.** No configuration sprawl. Want different behavior? Modify the code. The codebase is small enough that it's safe to make changes.

**AI-native.**

- FreeBSD installs can start with `npm run wizard` for optional interactive locale, timezone, and assistant-first onboarding. `bsddialog` is used when present; plain TTY prompts are the fallback. The selector uses FreeBSD's locale inventory, so you can choose any installed locale (for example `en_US.UTF-8` or `zh_CN.UTF-8`) and it is applied the same way as the default.
- The rest of setup remains modular and scriptable through `just setup -- --step ...` (or `npm run setup -- --step ...`).
- No monitoring dashboard; the harness shows status and the AI fills in the details.
- No debugging tools; describe the problem and the AI fixes it.

**Skills over features.** Instead of adding features (e.g., support for Telegram) to the codebase, contributors submit skills like `/add-telegram` that transform your fork. You end up with clean code that does exactly what you need.

## Documentation System (Phase 3.0+)

**v0.9.0 includes a complete multi-language documentation deployment system:**

### Architecture

```
Markdown Source (git)    →    Crowdin (translate)    →    Daily Sync (05:00 UTC)
     ↓                              ↓                              ↓
docs/public/*.md (English)    →    docs/public/{de,fr,es}/* →    docs-v0.9.0_24.mar.2026/
                                                          ├─ en/
                                                          ├─ de/
                                                          ├─ fr/
                                                          └─ es/

Symlink Swap (atomic, zero-downtime)
     ↓
https://docs.clawdie.si/{en,de,fr,es}/
```

### Features

- **Markdown Source of Truth** — English docs in `docs/public/*.md`, auto-synced to Crowdin
- **Crowdin Integration** — Translators work on [crowdin.com/project/clawdie-ai](https://crowdin.com/project/clawdie-ai)
- **Automated Sync** — Daily cron @ 05:00 UTC compiles markdown → HTML for all languages
- **Zero-Downtime Deployment** — Symlink-based versioning with atomic swaps
- **30-Day Retention** — Old versions auto-cleaned, instant rollback available
- **No External Dependencies** — Pure shell compilation (no pandoc, no external tools)

### Quick Links

- **[docs-deployment skill](.agent/skills/docs-deployment/SKILL.md)** — Complete operations guide
- **[CROWDIN.md](CROWDIN.md)** — Translation workflow
- **[Integration Guide](.agent/skills/docs-deployment/INTEGRATION.md)** — How build (clawdie-shell) and deployment (clawdie-ai) work together

### Supported Languages

- 🇬🇧 English (source, always current)
- 🇩🇪 Deutsch (German)
- 🇫🇷 Français (French)
- 🇪🇸 Español (Spanish)

Want to add more languages? Update `scripts/docs-sync.cron.sh` and add to Crowdin.

---

## Clawdie Ecosystem

| Component                   | Description                                        | Status      |
| --------------------------- | -------------------------------------------------- | ----------- |
| **`{AGENT_NAME}-worker`**   | Default Bastille worker jail profile               | Current     |
| **skills-memory bootstrap** | Precomputed pgvector import for the skills DB      | Current     |
| **docs-deployment**         | Multi-language docs with Crowdin sync (Phase 3.0+) | Live        |
| **clawdie-cnc**             | CNC machine control                                | Development |
| **browser-vm**              | Browser automation profile in jail config          | Planned     |
| **docs.clawdie.si**         | Documentation site (4 languages)                   | Live        |

### CNC (clawdie-cnc)

Clawdie-cnc is the **control system for the CNC machine** — an open source machine designed to manufacture geodesic dome components. It translates dome designs from [OSA](https://osa.smilepowered.org) into G-code, manages the build sequence, and logs everything to persistent memory.

See `clawdie-cnc/README.md` for details.

## Contributing

**Don't add features. Add skills.**

If you want to add Slack support, don't create a PR that adds Slack alongside Telegram. Instead, contribute a skill file (`.agent/skills/add-slack/SKILL.md`) that teaches the AI agent how to transform a Clawdie installation to use Slack.

Users then run `/add-slack` on their fork and get clean code that does exactly what they need, not a bloated system trying to support every use case.

### Available Skills (35+)

**Channels:** add-telegram, add-discord, add-gmail, add-slack, add-voice-transcription, x-integration

**Jail & Infrastructure:** warden-bootstrap, warden-pf, warden-zfs, warden-health, bastille-network, browser-vm, freebsd-admin, sanoid

**Operations:**

- **nginx** — CMS jail vhost management
- **nginx-glasspane** — Nginx security features
- **docs-deployment** — Multi-language documentation sync (NEW v0.9.0)
- telegram-admin, tmux-screenshot, postgres-memory

**Frontend & CMS:** astro, strapi

**Agent:** coding-agent, add-telegram-swarm, add-parallel

**Utility:** setup, update, customize, debug

### Skills Structure

```
.agent/skills/add-telegram/
├── SKILL.md           # Skill documentation and instructions
├── manifest.yaml      # Skill metadata
├── add/               # Files to add
│   └── src/channels/telegram.ts
├── modify/            # Files to modify
│   └── src/config.ts
└── tests/             # Skill tests
    └── telegram.test.ts
```

## Requirements

- FreeBSD 15.x
- Node.js 24+
- Python 3.11+ (for voice transcription, screenshots, and other features)
- ZFS (required for Bastille jails)
- Optional: Telegram bot token, provider API key, PostgreSQL URLs for memory/skills DB

## Security

Agents run in FreeBSD jails with filesystem isolation, not behind application-level permission checks. They can only access explicitly mounted directories. The codebase is small enough that you can review it. See [docs/public/operate/security.md](docs/public/operate/security.md) for the full security model.

## Documentation

- **[docs.clawdie.si](https://docs.clawdie.si)** - Complete documentation (English, Deutsch, Français, Español)
- **[docs/public/architecture/host-operator-model.md](docs/public/architecture/host-operator-model.md)** - Host-first operator model and service-jail layout
- **[.agent/skills/docs-deployment/SKILL.md](.agent/skills/docs-deployment/SKILL.md)** - Documentation deployment system (Phase 3.0+)
- **[.agent/skills/docs-deployment/INTEGRATION.md](.agent/skills/docs-deployment/INTEGRATION.md)** - Cross-repo integration guide (clawdie-ai ↔ clawdie-shell)
- **[CROWDIN.md](CROWDIN.md)** - How to translate and contribute translations
- **[AGENTS.md](AGENTS.md)** - Agent development guidelines

## Community

Questions or ideas? Open an issue on [Codeberg](https://codeberg.org/Clawdie/Clawdie-AI) or reach out at [hello@clawdie.si](mailto:hello@clawdie.si).

## Acknowledgments

Clawdie is built on giants' shoulders. [Peter Steinberger](https://github.com/steipete)
created [OpenClaw](https://github.com/openclaw/openclaw), which set the broader
project line. [NanoClaw](https://github.com/qwibitai/nanoclaw) by
[Gavriel](https://github.com/openclaw) distilled that line into a minimal
personal-assistant upstream. Clawdie is the FreeBSD-first fork in that lineage.

We keep NanoClaw as an upstream reference where it helps, then carry the design
into native jails, ZFS, PF, and the wider
[OSA](https://osa.smilepowered.org) mission.

## License

BSD 3-Clause License

Copyright (c) 2026, Sam (Samo Blatnik)

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions, and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions, and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

See [LICENSE](LICENSE) for full text.

---

<p align="center">
  <strong>Clawdie</strong> · Personal AI Assistant on FreeBSD<br>
  <a href="https://clawdie.si">clawdie.si</a> · <a href="https://docs.clawdie.si">docs.clawdie.si</a><br>
  <em>Built on giants' shoulders · FreeBSD-first</em>
</p>