Ciao Capabilities

---
name: ciao-capabilities
description: Authoritative catalog of what Ciaobot can do, for capability questions and feature tours. Use whenever the user asks what Ciaobot is, what it can do, what features are available, whether it can do something specific, or how one of its features works (memory, vault, vault review, archiving, adversarial review, schedules, interval automations, routines, workspaces, projects, forks, subagents, skills, MCP servers, slash commands, models, providers, opencode, plan mode, permission modes, notifications, package updates, keyboard shortcuts, files, document conversion, chat comments, pinned files, document previews, CSV tables and cell comments, HTML artifacts, artifact comments, backlinks, memory map, vault graph, note graph, retirement candidates) — and when onboarding or giving a tour or walkthrough to a new user. Trigger on phrasings like "what can you do", "what can ciaobot do", "help me get started", "give me a tour", "can you remind me / remember / schedule", "can you review vault notes", "can you run an adversarial review", "what will accepting this change", "show me the change before I accept", "can I talk about a note before retiring it", "can you convert documents", "can you comment on a chart", "can I fork this chat", "can you ask another provider", "can you stop asking permission", "can I install this on my mac", "how do I update ciaobot", "can you host on linux", "can I run you on a VPS", "ubuntu server install", even when the word "Ciaobot" is not mentioned.
---

# Ciaobot Capabilities

You are running inside Ciaobot. The app's feature surface is not otherwise visible from a chat session — the system prompt covers behavior, not features — so answer capability questions from this catalog instead of guessing from generic Claude knowledge. If the running app visibly disagrees with something here (features evolve), trust the app and say so.

## How to answer

- **Specific question** ("can you schedule things?", "where do my archived chats go?") → answer from the relevant section only. Don't recite the whole catalog.
- **Broad question** ("what can you do?") → give the one-paragraph pitch plus the capability areas below in a few lines each, then offer to go deeper on any of them.
- **New user / onboarding** → offer the guided tour below.
- Distinguish the **app** from **you**: this catalog is what the Ciaobot app provides. On top of it you have your normal agent abilities plus whatever skills, subagents, and slash commands are installed in this workspace (`skills/`, `subagents/`, `commands/`, and their `.claude/` mirrors).

## The one-paragraph pitch

Ciaobot is a local-first UI and UX layer for using Claude Code (and other backends) as a personal assistant and second brain. Chats, projects, files, schedules, memory, and archived knowledge live in one web app instead of being scattered across terminal sessions — and everything durable is plain markdown that works with any other tool even when Ciaobot is not running.

## Connecting providers

Ciaobot uses the provider CLI the user already has, rather than creating a
second model account or storing a second provider credential. For Anthropic,
the user installs and signs into [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview),
then chooses Claude Code in Ciaobot; Ciaobot adds workspace/project context and
handles the end-of-conversation memory pass around that session. For
OpenAI access, OpenRouter, Ollama, or another cloud/local backend, the user
installs [OpenCode 2.0.16+](https://opencode.ai/v2/docs/), configures and
authenticates the provider there, then chooses OpenCode in Ciaobot. Its connected models appear
in the Ciaobot picker. Point users to the live
[`INTEGRATIONS.md`](https://github.com/raffaelefarinaro/ciaobot/blob/main/INTEGRATIONS.md)
for current commands; do not invent version-sensitive install or login syntax.

## Capability catalog

### 1. Chats, projects, and workspaces

- Hierarchy: **workspace → project → chat**. A workspace is a life area (personal, work, a client); each workspace holds projects; each project holds chats plus durable context (files, notes, decisions) that Ciaobot injects into every chat inside it — the agent doesn't rediscover what you're working on each time.
- **Workspaces can have their own vault root, default provider, Google Workspace profile, tool deny-list, and MCP server allowlist.** Default models are per provider (Settings → Models & providers), not per workspace. In-chat, `ciao workspace list` lists the configured workspaces and `ciao context get` reports the active one.
- **Archiving a workspace** (Settings → Workspaces → Archive) never deletes files and never merges them into another workspace. The workspace leaves the sidebar, pickers and routines; its chats are archived, its automations leave with it, and Ciaobot stops using its notes and memory (search, the index, the Memory Map). Its folder is kept byte for byte in `.archived-workspaces/<name>-<date>/` in the install folder, and the Archived workspaces list on the same tab restores it; the restore confirmation lists the settings it will apply, and its automations come back paused until re-enabled in Automations. The primary workspace and the last one cannot be archived. There is no in-chat command for it.
- A new chat starts on the workspace's default provider and that provider's default model; each chat can override the model from the picker.
- **Projects are managed in-chat with `ciao project`**: `ciao project list [--include-completed]` lists a workspace's projects, `ciao project get [ID|NAME]` fetches one, `ciao project create --name` makes a new one, `ciao project update ID [--name] [--context] [--vault-folder]` edits metadata, and `ciao project complete ID` / `ciao project restore STEM` / `ciao project delete ID` handle the lifecycle.
- **Starting a chat from the home screen**: each workspace lane has a **+ new** button that starts a chat in that workspace's *General* project in one click. When the workspace has more than one project, a caret sits beside it that opens a project picker, so a new chat can go straight into the right project without creating it in General and moving it.
- Push notifications; the PWA is installable on desktop and mobile.
- Chats can be spawned programmatically from within a chat via `ciao chat create`.
- **Forks**: any completed agent answer has a *Fork conversation from here* action. It creates an independent new chat in the same project, copies the visible history through that answer, and inherits the source's provider/model/mode/thinking level — but starts a fresh provider session and never syncs back to the source. Forks are titled `Original · Fork 1`, `Original · Fork 2`. Use it to explore a branch without disturbing the original.
- **Subagents**: a chat's agent can dispatch subagents to work in parallel. While a background one runs it appears as a row under its chat in the sidebar, with the agent's description and a live working dot; clicking the row opens a read-only view of that agent's own conversation (you can read it, not steer it — a subagent is a transcript, not a chat you can send into). The row disappears when the agent finishes, and its full transcript stays in the chat's Activity trace, reachable from the same read-only view. Use for "investigate these four things in parallel".
- **Background runs**: when the work is one long script rather than a whole agent task, a chat's agent can start it as a tracked background command instead of a subagent — no model in the loop, no tool access, just the command. It does not block: the turn ends, the output streams into a log file, and when the process exits Ciaobot wakes the chat with the status, exit code, last lines, and the log path (batched, so a group finishing together produces one report). The run can be checked or stopped mid-flight, belongs only to the chat that started it, and is confined to the workspace. Use for "fetch, verify, enrich — one script each". Details: `ciao run start|status|cancel`.
- **Plan mode** (read-only: the agent researches and proposes an approach without editing anything) is not a control in the app — the model picker only offers the model and thinking level, and the chat header shows no mode chip. The backend still accepts `mode: "plan"`, so a chat can be put into it with `ciao chat create|update --mode plan` or the chat API (`PATCH /api/chats/<id>`, see `PWA_API.md`). A plan-mode chat gets `plan_mode_read_only` back from every mutating `ciao` command, including `ciao chat update`, so it cannot switch itself back out; changing the mode again takes the API or another chat.
- **Turn resilience**: if a turn hits a provider connection error, Ciaobot auto-retries it with backoff instead of dropping the message; you can stop the retry or trigger one immediately. The active chat's live socket also auto-reconnects so a brief network blip doesn't lose the streaming result.

### 2. Memory and the vault (second brain)

- **How memory works, in plain terms.** When a chat is archived and **Automatic session insights** is on in Settings → Automations, Ciaobot re-reads it and pulls out only what will matter later — a preference, a lesson, a person, a decision — and files each fact where it belongs: things true everywhere go into a small always-loaded memory (the `ciao:memory` / `ciao:profile` regions in `AGENTS.md`), project facts into that project's doc, people into `People/<Name>.md`, reusable how-to lessons into `Workspace/Learnings.md`. **Automatic trajectory capture** independently controls the structured trajectory record. Every remembered fact is dated, and when a fact changes, the new version replaces the old one (the old text is kept in an undo log, never silently lost). A nightly "Memory curation" routine tidies all of this: it merges duplicates, retires expired facts, re-checks old notes, and rotates logs.
- **What is automatic vs. what is yours.** Automatic: extracting facts from archived chats, filing confident state-shaped facts (including into the always-loaded `ciao:memory` / `ciao:profile` regions, project docs, people notes, and learnings), deduplicating, dating, nightly tidying, and search-index upkeep. Yours (by design): anything the memory pass was unsure about, plus every *new* region fact the nightly curation run finds — the nightly agent is an unattended run with no reviewer, so it only *consolidates* what a region already holds and queues new region facts for you. Review from the app's proposals panel or the CLI (`ciao memory-proposals`, `ciao memory-proposal-dismiss --text-file <file>`); you can also just tell any chat "remember this" or "forget that". Region caps are advisory — a full region never blocks a durable fact; consolidation (or raising the limit) is what makes room. Nothing is ever deleted automatically — aging or unused facts are only *reported* for you (or an attended chat) to decide. A History tab beside the queue shows every decision already made — what you or the nightly agent accepted or dismissed, and what archiving filed or recognized as already known on its own. A row shows the before/after of the write it performed and offers Undo when it has a reversible receipt — including an accept whose wording you edited first. Rows written before receipts existed, and the per-fact rows of a multi-fact batch (one row carries the batch's whole-file before image, so undoing the others would resurrect everything the batch removed), are view-only and say so. **See the exact change before you accept it**: a proposal's preview names the destination and shows the before/after body the accept would produce — including when it recognizes a duplicate and writes nothing, or bumps a learning's recurrence count instead of appending a second copy — and re-previews as you edit the wording. Where the result genuinely cannot be known without writing (a fold into a project doc or an existing person note is decided by a model at accept time) it says so rather than guessing. On a very large destination the preview covers only the first 20,000 characters of each side. A change past that point — an append to a long learnings file, say — falls outside the window, and because there is then no visible difference to show, the panel reads "Nothing changes" rather than flagging the truncation. The accept still makes the change, so treat that reading as "not shown here" on a long destination rather than "nothing will happen". If the destination moved after you looked, the accept is refused and you are shown a refreshed preview, so a write never lands on top of an edit nobody saw.
- The vault is standard, open markdown: notes, project folders, `AGENTS.md` (which also holds the bounded memory regions), a vault `MEMORY.md` (curator notes — separate from the bounded regions), a generated `INDEX.md` and `VOCABULARY.md` from frontmatter and markdown links. It is agent-agnostic and remains useful without Ciaobot.
- Vault tooling: search (`ciao vault search`, which covers vault notes, not archived transcripts) before adding duplicate facts, and refresh the index (`ciao index`) after larger edits. Read-only recall uses the matched `vault_search` snippets as private evidence; do not open full vault notes with generic file-read tools for pure recall, and admit when nothing is found. When a snippet is truncated and the answer turns on what it omits, search again with a narrower query built from that snippet's distinctive terms; when no snippet carries the answer, recall abstains rather than answering from an unmatched block. This is inline system-prompt policy, not a separate skill. The typed Ciaobot operations (projects, chats, subagents, automations) are the `ciao <noun> <verb>` commands, listed in the bundled `ciao-cli` skill and printed by `ciao help` — read that rather than guessing a name. The bounded memory regions can be edited directly with `Edit` on `AGENTS.md`, or with `ciao memory status` / `ciao memory update --region {memory,profile} --action {add,replace,remove}`. Vault-maintenance edits are the `ciao` CLI (`ciao index`, `ciao lint`).
- **Memory Map** (`/memory`): an interactive graph and list view of the whole vault for one workspace — nodes are notes (colored/typed from frontmatter), edges come from `related:`/`relatedTo:` frontmatter and relative markdown links in note bodies. It is one of Memory's five sidebar sections (To decide, Map, Categories, Retired, History); To decide lists suggested memories and notes to revisit on one page, with a filter for each. Search, filter by category, sort the list by links or by when each note was last checked; clicking a note opens it in a docked tile (the same one a pinned file uses) and lights up its neighbours, and notes unchecked too long carry an amber ring and link to the notes to revisit.
- **Vault Review**: inspect deterministic candidates for notes that are unverified past their type's horizon (project 30 days, person 90, everything else 180; logs, journals, `Workspace/` files, templates and completed projects never qualify — the same rule as the Memory Map's "unchecked" flag, so the two lists agree), unlinked, possible duplicates, say they were superseded (the row quotes the line and its line number), or carry no date, tags or aliases; review evidence in the PWA or through `ciao vault review`; keep (which clears the row and stamps the note's `updated:` date to today — a note with no frontmatter has nothing to stamp, and the app says so), trash, restore, or permanently delete with append-only audit records and reversible trash until confirmed deletion. A candidate left undecided simply stays in the queue. Trashed notes stay restorable until they are deleted — nothing is purged on a timer. A keep can be undone: "Recently cleared" lists the notes cleared that are still in the vault, and **Add back** returns one to the queue. A note that leaves the vault by an ordinary file deletion is recorded in the ledger too, so the audit trail accounts for everything that left.
- **Talk about a retirement candidate before deciding.** Every candidate row has "Talk about it": it opens a chat in that candidate's own workspace with the note pinned beside it and the composer pre-filled with the row's evidence — path, why curation flagged it, type, verification age, backlinks, duplicates — plus an instruction to change nothing. On a note nothing links to, the draft instead asks the agent to search the vault for the notes that *should* link to it and to write only the links that are approved — the repair that actually clears that flag. The message is a **draft, not sent**, so a specific question can be asked first, and the candidate stays queued whatever the answer. (The proposal queue's "talk about it" has the opposite shape: it runs in the background and reports back.)

### 3. Automations

- One primitive covers every cadence. An automation dispatches its prompt as a chat turn at a time of day (daily/weekly/monthly/once, timezone-aware), every N minutes, or only when the user clicks Run. Configure from the **Automations page** or directly in chat (`ciao schedule create|preview|update` carries the full field semantics in `ciao help`; `ciao schedule pause|resume|run|delete` handles the lifecycle).
- **Two targets, and the choice matters.** Point an automation at a **project** and each run opens a fresh chat there with its own model and provider — right for briefings, reports, and maintenance. Point it at an existing **chat** and every run continues that conversation, inheriting its model and mode — right when continuity between runs is the point ("check my PRs every 10 minutes and tell me what changed").
- **Every N minutes** is `frequency="interval"` with `interval_minutes` (minimum 1). Combined with a chat it is what used to be called a loop, and behaves the same way: a run that comes due while the chat is still working is skipped and retried shortly after, never queued, and the cadence resumes after a restart rather than replaying what it missed. Combined with a project it opens a fresh chat each time.
- **When to create one**: the agent creates automations conversationally when the user asks — this is an agent action, not a PWA-only button. Show a concise draft (cadence, next_run, target workspace, target project/chat) and get confirmation before creating, unless the user already explicitly asked to apply it. Call `ciao schedule preview` first to validate. Ask which workspace/project when it isn't obvious from the request. An automation always belongs to one logical workspace and shows under Automations for that workspace.
- Time-of-day runs that were due while the app was off are caught up on the next launch; each workspace shows how many it missed. A run that dispatched but stopped before it finished (a restart mid-turn, a killed model process) counts as missed too — it is recovered once on the next launch, and stays listed as missed if that recovery fails as well. A run that completed is never repeated. Interval runs are not replayed — their cadence just resumes.
- System maintenance schedules ship with the app. **Settings → Automations** lists the background work Ciaobot does on its own — what each automation does, when it runs, and how its last run went — leading with anything that needs attention. The **Automatic session insights** and **Automatic trajectory capture** switches stop their respective model processing or structured records for new and archived chats while leaving explicit one-time runs available. Failing automations can be re-run from there.

### 4. Files

- Create, preview, edit, and **restore** workspace and vault files from the PWA, with history — no terminal needed.
- **In chat**: agent file touches surface as inline cards; open the viewer, pin beside the chat, and add line comments on selections — including while the agent is still working, in which case the comment rides along on your next message. Freshly written `.md`/`.csv` files auto-surface in the pinned panel so you see them without hunting.
- **Drag to attach**: drag a file into the composer and Ciaobot uploads it into the active project folder, then hands the model an agent-accessible path. Images dropped this way upload as visual attachments.
- **Per-chat drafts**: unsent composer text is cached locally per chat and restored after switching chats or reloading. Sending clears only the active chat's draft.
- **Chat annotations**: select text in any message and attach a comment that rides on your next send. With a selection live you can skip the Comment pill: typing opens the note seeded with that keystroke, and pasting opens it with the clipboard text (and attaches pasted images). The same shortcuts work on document and CSV-cell selections in the viewer and the pinned panel.
- **Rich previews**: images inline; PDFs in the viewer; `.pptx` slides rendered as PDF (LibreOffice on the server).
- **Document conversion**: attach supported office documents and have the server convert them to Markdown for the agent, using the configured conversion service only when needed.
- **Interactive HTML artifacts**: ask for a dashboard, chart, annotated diff, timeline, or interactive comparison and Ciaobot writes one self-contained `.html` page that renders live in the panel, with a Preview/Code toggle and version history. The page runs sandboxed with no network access, so it works offline and cannot phone home. **Comment on the rendered page itself**: select text in the preview and a Comment pill appears, or Alt+Click any element — a chart bar, an SVG shape, a cell — to comment on the element rather than its text. The comment quotes what you picked into the composer, and the highlight stays anchored on the page across reloads and new versions, so you can point at a specific bar in a chart instead of describing it. Prose still belongs in markdown and tabular data in CSV, which have their own comment surfaces.
- **CSV tables**: `.csv` files render as an editable table in the viewer, and you can attach comments to individual cells (anchored by row and column) the same way you annotate document lines.
- **Backlinks**: the API has `GET /api/vault/backlinks`, which lists the vault notes that link to a given note (`[Note](./Note.md)`) — the incoming half of the link graph. The app has no Backlinks tab or panel that calls it; in the app, incoming links show up as edges in the Memory Map and as the backlink count on Vault Review candidates.
- **Keyboard shortcuts** are one set, because there is one client — the browser or the installed PWA: new chat is `Option+N`, archive is `Option+Backspace` (it works even while you are typing — a confirmation dialog stands in front of it), and `Cmd`/`Option` is whichever the platform uses. Arrow keys roam the home screen's recent chats and Esc closes the open chat. Unmodified `1`–`9` switch to the workspace in that position in the sidebar (inert while you are typing in a field), and `Cmd+S` / `Option+S` shows and hides the sidebar. The **keyboard shortcuts** card on **Settings → Home** lists the whole set.

The file workflow is designed around model collaboration: keep a Markdown document pinned beside the chat, edit it, annotate exact passages or CSV cells, and send the requested changes back with their locations. Markdown opens directly, CSV is an editable table, and `.pptx` is previewed as PDF. Supported document attachments are converted to Markdown with AnyDoc before injection so the model can read their contents efficiently.

### 5. Skills, subagents, and commands (extensibility)

- **Stock skills** ship with the app and are synced into `.claude/skills/` (`ciao sync-skills`, runs at startup). A same-named skill in the workspace's `skills/` folder overrides the packaged copy.
- **Visual plans**: ask for a plan, design direction, architecture review, UI flow, or approval artifact and Ciaobot writes a local Markdown plan with an optional self-contained HTML companion, including diagrams drawn as inline SVG. Markdown is the canonical, commentable, editable, restorable plan; HTML is an optional companion that answers a specific review question. Only one file is pinned at a time. Plan mode cannot produce a plan file — the skill explains that and offers an in-chat proposal instead. Routine working docs (notes, analyses) stay with the `workspace-authoring` skill.
- **Custom** skills, subagents, and slash commands are authored in the workspace (`skills/`, `subagents/`, `commands/`) and mirrored automatically.
- **Adding a skill**: place a folder `skills/<name>/SKILL.md` (or validated zip containing one top-level folder with `SKILL.md`) then run `ciao sync-skills`. Workspace git sync carries it to other operators. No GitHub fetch.
- **Skill improvement proposals**: when the memory pass finds a repeated failure or correction that traces back to one of this workspace's own skills, it files one plain-language proposal per skill in `Workspace/Skill-Proposals/`, never a silent edit. The nightly Workspace care run reviews that queue.

### 6. Models and providers

- Backends: **Claude Code** (Claude subscription or Anthropic API key) and **opencode** (the open-source agent CLI, bring-your-own model provider — this is how you reach anything else, including Ollama, OpenRouter, or a local OpenAI-compatible server: configure it in opencode and its models appear here automatically). A message sent while a turn is still running is buffered and flushed as the next turn when the active one finishes — this works identically across providers.
- **Other model backends**: Ollama, OpenRouter, LM Studio, and other OpenAI-compatible endpoints are reached through **opencode**. Configure the backend in opencode; Ciaobot discovers its connected models automatically and exposes them in the chat, workspace, and routine pickers. Ciaobot does not store or probe those backend credentials itself.
- Per-provider default model and thinking level for new chats (**Settings → Models & providers**, the chat providers card, which also shows each CLI's connection and lets you reconnect, verify, or log out) — no cross-provider tier mapping; each provider resolves `opus`/`sonnet`/`haiku`/`fable`-style aliases against its own catalog. Per-chat override in the picker, with Automatic resolving to the chat's own model.
- Per-provider default **permission mode** for new chats (**Settings → Models & providers**): *manual* asks before every action, *auto* (the default) runs safe reads and edits silently and asks before destructive ones, *bypass* allows everything. That default is the only permission control in the app — there is no in-chat mode switch. A single chat's mode can only be changed outside the UI, with `ciao chat update --mode` (which can lower a mode but never raise it above the calling chat's own) or the chat API.
- Beyond per-chat routing, one chat can **reach another model without leaving the conversation**: the `/critique` command gives an inline multi-model second opinion, and a handover moves the whole chat to another provider.
- **Adversarial review**: the built-in critique panel can send the same file, question, or idea to multiple configured agents and models, then synthesize their independent feedback into a comparative verdict. Select the participating models from the available provider/model configuration.
- **Session insights** can be disabled entirely in Settings → Automations.

### 7. Google Workspace (`gws`)

- Ciaobot integrates with Gmail, Calendar, Drive, Docs, Sheets, Slides, and Tasks through the [`gws` CLI](https://github.com/googleworkspace/cli).
- **Settings → Workspaces**: install `gws`, upload a GCP OAuth `client_secret.json` per profile, and connect Google accounts from the browser (no terminal required). The Google Workspace card (and its ⓘ panel) lives on that tab. In-chat, `ciao gws status` reports whether the active workspace's Google account is connected and its token valid before you promise a Google call will work.
- Separate **personal** and **work** profiles; each workspace picks which profile to use on the same Workspaces tab.
- Stock **`gws-*` skills** ship with the app (Gmail, Calendar, Drive, Docs, Sheets, Slides, Tasks, Forms). Setup details: `gws-shared` skill and the ⓘ panel on the Google Workspace card.

### App and system surface

- **Settings page**: Home (restart and app actions, keyboard shortcuts, PWA password, workspace health, main workspace path, package update, notifications in the browser, appearance, **host & client** multi-device role), Workspaces (including Google Workspace), Models & providers (chat provider connections and per-provider defaults, background models such as session insights and critique), Skills, Subagents, Commands, MCP (editable **project MCP servers** and secrets), Automations, and Notifications.
- **Workspace extensions in the UI**: the Skills, Subagents, Commands, and MCP tabs in Settings add and manage skills, subagents, slash commands, and MCP servers. They are not scoped to one workspace: a skill zip lands in the active workspace's agent root (shared by every workspace unless workspaces have their own roots), subagents and commands are written without a workspace, and MCP servers go into the install-root `.mcp.json` — which a chat reads only on a shared-root install; once workspaces have their own agent roots, each chat reads `<root>/.mcp.json` instead, and servers added in Settings are not visible to it until copied there. The only per-workspace MCP control is the workspace's `allowed_mcp_servers` allowlist in `.runtime/workspaces.json`, which has no UI and applies to Claude Code chats only (a workspace with no allowlist set reaches none of the declared servers).
- **Installing and updating**: the engine installs with one line — `curl -fsSL https://github.com/raffaelefarinaro/ciaobot/releases/latest/download/install.sh | sh` — and you open `http://localhost:8443` in a browser. To update, run that one line again, or use **Settings → Home**, which stages and applies the engine update in the background. There is no separate app to update: v1.0.0 retired the old macOS `Ciaobot.app`, and a machine that still has it runs the installer with `--migrate` (`... install.sh | sh -s -- --migrate`), which installs the engine *and* removes the old app bundle, and only if that removal could not run does `ciao desktop uninstall` still have to be run by hand (details in the repo README). The engine runs on macOS 13+ (Apple Silicon) and on Linux; the PWA itself is installable from any browser.
- **Other devices**: open Ciaobot from a phone or another computer. Settings → Home → Other devices lists every address this engine answers on, each with a QR code, and every device signs in with the Ciaobot password. Only an HTTPS address can install the app and get notifications: run `tailscale serve --bg 8443` and Ciaobot finds the Tailscale address on its own, or paste the address of another HTTPS proxy. Plain LAN addresses work in a browser only.
- **Linux/VPS hosting**: the engine and PWA run on Ubuntu 24.04 (Python 3.12, Node 22) as a systemd service under a dedicated account, with application code administrator-owned and the workspace private to the service account. Use any browser or installed PWA as the client; agents execute on the server with its files and credentials. Setup details: `docs/LINUX.md` in the Ciaobot GitHub repo.
- **Local HTTP API**: the app exposes an API an in-chat agent can drive (create chats, subagents, commands) — recipes are in `PWA_API.md` in the Ciaobot GitHub repo (`raffaelefarinaro/ciaobot`); fetch it when you need the raw API surface. For the common cases, `ciao help` already lists the agent commands and their flags.

### Privacy and trust posture

Local-first: the server, vault, and runtime state live on the user's machine; traffic leaves only toward the configured model providers. Memory is reviewable: confident state-shaped facts are filed by the memory pass, the unsure ones wait as proposals, and no unattended run promotes a new always-loaded fact. An existing notes folder is never discarded or rewritten during onboarding, and the vault stays portable plain markdown.

## Guided tour (new users)

When onboarding someone, walk through these hands-on:

1. **Orient** — workspaces → projects → chats; create or rename a project for something they're working on.
2. **Chat** — model picker and project context the agent always sees.
3. **Annotate & files** — message comments, inline file cards, pin, line comments, and rich previews.
4. **Memory** — archive → memory pass; confident facts are filed, unsure ones wait, and no unattended run promotes a new always-loaded fact.
5. **Schedules** — set up one small routine they'd actually use.
6. **Settings** — models & providers, package updates, and the engine's own service controls.

Close with: they can ask "what can Ciaobot do?" (or about any specific feature) in any chat, anytime.

## Where the details live

- Workspace customization surface (env vars, workspaces registry, tool deny-lists, model routing): `CIAO_CUSTOMIZATION.md` in the workspace root.
- Automations how-to: `ciao schedule` commands in `ciao help`. Spawning chats: `ciao chat create`. Reaching another model: `ciao chat handover` and the `/critique` command. Vault read conventions are inline system-prompt policy.
- Canonical docs in the Ciaobot GitHub repo (`raffaelefarinaro/ciaobot`, also present in source checkouts): `README.md`, `docs/ARCHITECTURE.md`, and `PWA_API.md` (routes, auth, agent recipes).