clawdie/clawdie-ai
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

fix(docs): sync 0.12 alignment to docs/public/ canonical source

Browse source
This commit is contained in:
Sam & Claude 2026-06-26 08:37:08 +02:00
parent 3b0fe67400
commit c0181b5c46
8 changed files with 15 additions and 20 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
docs/public/architecture/controlplane.md
View file

@ -94,7 +94,7 @@ Skills are discoverable via tags and the `skills_search` extension tool. The con
| `db-vacuum` | DBA | "Run vacuum on system_brain" |
| `db-migrate` | DBA | "Apply pending migrations" |
| `git-merge` | Git Admin | "Merge PR #42 into main" |
| `git-release-tag` | Git Admin | "Tag version v0.11.0" |
| `git-release-tag` | Git Admin | "Tag version v0.12.0" |
The catalog evolves over time; for the authoritative current list run `/skills` in Telegram or `just skill-list` on the host.
@ -143,7 +143,7 @@ three provider/model values in `agent_activity.payload`:
| Field | Meaning |
| -------------- | --------------------------------------------------------- |
| `configured_*` | What `.env` says (`PI_TUI_PROVIDER` / `PI_TUI_MODEL`) |
| `configured_*` | What `provider.env` says (`DEEPSEEK_API_KEY`) |
| `effective_*` | What was actually passed to pi (after fallback swap) |
| `actual_*` | What pi reports having used (parsed from session JSONL) |
@ -157,9 +157,7 @@ fallback cooldown line when one is active.
## References
- `doc/CONTROLPLANE-ARCHITECTURE.md` — detailed service layout
- `doc/CONTROLPLANE-MESSAGE-CONTRACT.md` — API contracts (what agents query and post)
- `doc/CONTROLPLANE-AGENT-ROLES.md` — role definitions, skill mappings, budgets
- `SOUL.md`, `SYSADMIN_AGENT.md`, `DB_ADMIN_AGENT.md`, `GIT_ADMIN_AGENT.md` — agent identity files
- [Provider Fallback](../operate/provider-fallback/) — automatic provider switching when the primary hits a usage cap
- [Structured Reports](../operate/structured-reports/) — operator-facing report family + free-text routing
- [Colibri Architecture](https://code.smilepowered.org/clawdie/colibri) — the Rust control plane replacing this TypeScript implementation

2
docs/public/architecture/freebsd-jail-implementation.md
View file

@ -161,7 +161,7 @@ just setup-cms
just setup -- --step dns
just setup -- --step verify
just doctor # health check, including DNS, TLS/ACME, and scheduled reports
just pi-config # view / validate runtime config
colibri-mcp tools # view / validate runtime config
```
## Related docs

6
docs/public/install/first-boot.md
View file

@ -364,10 +364,8 @@ move chat to a direct provider:
- **Per chat:** `/model` in Telegram lets you swap provider/model
for a single chat.
- **System-wide:** edit `.env` and set `PI_TUI_PROVIDER` /
`PI_TUI_MODEL` to your preferred provider (zAI, Anthropic,
OpenAI, Gemini). The OpenRouter key can stay configured as a
fallback — see
- **System-wide:** set `DEEPSEEK_API_KEY` in `provider.env`.
The agent uses DeepSeek by default.
[Provider Fallback](../operate/provider-fallback/).
### Reformat the install media

9
docs/public/install/fresh-install-checklist.md
View file

@ -84,7 +84,7 @@ ls -la /home/atlas/clawdie-ai/.env
```
```sh
grep -E '^(AGENT_NAME|AGENT_GENDER|AGENT_DOMAIN|AGENT_INTERNAL_DOMAIN|AGENT_TMP_DIR|PI_TUI_PROVIDER|PI_TUI_MODEL|EMBED_BASE_URL|TELEGRAM_BOT_TOKEN)=' .env
grep -E '^(AGENT_NAME|AGENT_GENDER|AGENT_DOMAIN|AGENT_INTERNAL_DOMAIN|AGENT_TMP_DIR|DEEPSEEK_API_KEY|EMBED_BASE_URL|TELEGRAM_BOT_TOKEN)=' .env
```
Verify:
@ -96,8 +96,7 @@ Verify:
| `AGENT_DOMAIN` | Public domain (e.g. `clawdie.si`) or `{agent}.internal` for VMs |
| `AGENT_INTERNAL_DOMAIN` | `{agent}.home.arpa` (Tailscale / local DNS) |
| `AGENT_TMP_DIR` | Writable path, not `/tmp` |
| `PI_TUI_PROVIDER` | Recommended `openai-codex`; `zai`, `openrouter`, `anthropic`, etc. are also valid. |
| `PI_TUI_MODEL` | Valid model for the provider |
| `DEEPSEEK_API_KEY` | DeepSeek API key for the agent harness (zot) |
| `EMBED_BASE_URL` | URL ending in `/v1` |
| `TELEGRAM_BOT_TOKEN` | Non-empty if `FEATURE_TELEGRAM=true` |
@ -142,8 +141,8 @@ attention before you treat publishing as healthy.
## 5. LLM provider connectivity
```sh
# Quick inference test via pi
pi --provider "${PI_TUI_PROVIDER}" --model "${PI_TUI_MODEL}" -e "reply with OK"
# Quick inference test via the agent
colibri --help # verify colibri CLI is available
```
Expected: Model responds. If using ZAI (GLM), verify the API key:

4
docs/public/install/install.md
View file

@ -66,7 +66,7 @@ just install
│
[ 2] environment host pkg baseline, bridge, locale REQUIRED
│
[ 3] pi-config validate/write pi provider optional ─── warn on missing provider auth
[ 3] agent-config validate/write agent provider optional ─── warn on missing provider auth
│ └── pi missing → warn, continue
[ 4] pf write PF include (NAT egress) REQUIRED
│ └── 📸 snapshot: post-pf
@ -284,7 +284,7 @@ but can be disabled), or **optional** (skipped unless explicitly enabled).
| ---------------- | -------- | ------------------------------------------------------------------ |
| onboarding | required | — |
| environment | required | — |
| pi-config | optional | warn on missing provider auth or missing pi |
| agent-config | optional | warn on missing provider auth or missing agent binary |
| pf | required | — |
| jails | required | — |
| git | default | `DB_RUNTIME=host` or `install-from hosts` |

2
docs/public/operate/monitoring.md
View file

@ -119,7 +119,7 @@ Note: the built-in knowledge artifact is committed in `bootstrap/skills-memory/`
Session safety:
- Pi sessions (`groups/<group>/sessions/*.jsonl`) grow over time. When a session file gets too large, the model can hit a context window limit and fail to respond.
- Agent sessions (`groups/<group>/sessions/*.jsonl`) grow over time. When a session file gets too large, the model can hit a context window limit and fail to respond.
- Use `AGENT_SESSION_MAX_BYTES` to cap session size; the runtime will start a fresh session automatically when exceeded (silent by default).
- Additional prompt guardrails limit resource abuse:
- `AGENT_MAX_INBOUND_CHARS` — truncates inbound messages exceeding this length

2
docs/public/operate/provider-fallback.md
View file

@ -140,7 +140,7 @@ Every agent activity row now records three provider/model values:
| Field | Meaning |
| -------------------- | -------------------------------------------------------- |
| `configured_*` | What `.env` says (`PI_TUI_PROVIDER` / `PI_TUI_MODEL`) |
| `configured_*` | What `provider.env` says (`DEEPSEEK_API_KEY`) |
| `effective_*` | What was actually passed to pi (after fallback swap) |
| `actual_*` | What pi reports having used (parsed from session JSONL) |

2
docs/public/operate/structured-reports.md
View file

@ -159,7 +159,7 @@ The pure builder pattern was a deliberate choice over a one-shot
"render-to-HTML now" approach. Three reasons:
- **Testable** — unit tests exercise the analysis logic with synthetic
inputs, no Postgres or pi running.
inputs, no Postgres or agent running.
- **Reusable** — the same `buildDiskReport()` could feed a dashboard widget
or a daily email digest later. We are not committed to Telegram as the
only sink.