wolli 0.0.2 → 0.0.3

package/README.md

@@ -2,7 +2,7 @@
 
 # Wolli
 
-**Build persistent, purposeful AI agents.**
+**Create purposeful, self-extending AI agents.**
 
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 [![npm](https://img.shields.io/npm/v/wolli.svg)](https://www.npmjs.com/package/wolli)
@@ -31,14 +31,25 @@ wolli
 The first run sets up your provider and creates your first agent. A new agent
 starts in a **forming** state: it interviews you to work out its purpose and
 records what it learns, and does not act unattended until you deploy it. Agents and
-state live under `~/.wolli`.
+state live under `~/.wolli`. `●` deployed and `○` forming.
+
+```
+ Agents
+
+ → ● inbox    Triage my email each morning, draft replies to the routine ones, flag what needs me.
+   ● scout    Watch the repos and deps we ship; when a release or CVE needs action, open an issue and ping me.
+   ● ledger   Track project spend across providers, reconcile invoices weekly, warn me before a budget tips over.
+   ○ sprout   Still working out my purpose.
+
+ ↑/↓ browse · enter chat · tab details · type to search commands · ctrl+c quit
+```
 
 ## How it works
 
 - **Purpose-built.** You state the agent's purpose at birth. It decides what the
   agent stores, when it speaks up, and what it does unattended.
 - **Self-extending.** The agent builds itself out for its purpose. It curates its
-  own memory and authors and installs its own skills, tools, and extensions; they
+  own memory and authors and installs its own skills, tools, extensions and integrations; they
   live in its home and load on reload. The agent grows more capable at its job
   instead of staying a fixed tool.
 - **Persistent.** Sessions are an append-only JSONL tree, the agent's lifetime
@@ -54,7 +65,7 @@ state live under `~/.wolli`.
   | `USER.md` | Facts about its human. |
 
 - **Always on, locally.** A per-agent daemon supervised by launchd (macOS) or
-  systemd (linux) runs the agent on schedules and events while your machine is on.
+  systemd (Linux) runs the agent on schedules and events while your machine is on.
 - **Sandboxed.** The agent runs in a sandbox by default: `srt` (Apple Seatbelt /
   bubblewrap), or optional Docker. Reaching your real machine is an explicit,
   approval-gated escalation.
@@ -76,6 +87,7 @@ removes them with it:
 
 | Type | What it adds |
 | --- | --- |
+| **Integrations** | TypeScript modules: tools, commands, events, UI. |
 | **Extensions** | TypeScript modules: tools, commands, events, UI. |
 | **Skills** | The Agent Skills standard. |
 | **Prompt templates** | `/name` slash commands. |
@@ -101,7 +113,6 @@ Two integrations ship bundled: **Telegram** (bidirectional chat) and a
 
 Full documentation is in [`packages/wolli/docs`](packages/wolli/docs/index.md):
 extensions, skills, prompt templates, themes, integrations, plugins, and the SDK.
-The integration/extension split is covered in [INTEGRATION.md](INTEGRATION.md).
 
 ## Roadmap
 

package/built-in/plugins/discord/README.md

@@ -0,0 +1,156 @@
+# Discord
+
+Connect a wolli agent to Discord. The bot runs over Discord's gateway WebSocket,
+gives each channel and DM its own wolli session, and replies in place. Setup is a
+few clicks in the Discord Developer Portal plus a single token prompt.
+
+## How the bot behaves
+
+Before setup, here's the part most people want to know: this bot answers
+**everything it can read**. There is no `@mention` gate.
+
+| Context | Behavior |
+|---------|----------|
+| **DMs** | Responds to every non-empty message. |
+| **Server channels** | Responds to every non-empty message in any channel it can read. No `@mention` required — unlike some Discord agents, the bot replies to plain messages. Scope where it listens with `allowedChannelIds`. |
+| **Other bots / itself** | Ignored. The bot skips its own messages and messages from any other bot, so it can't loop. |
+| **Empty / media-only messages** | Skipped (there is no inbound media handling). |
+
+While a turn runs, the bot shows Discord's **typing…** indicator in the channel and
+keeps it alive until the reply lands. Replies are chunked at **2000 characters**
+(Discord's per-message limit); Discord renders markdown natively, so formatting in
+the agent's output comes through as-is.
+
+If a new message arrives while the agent is mid-reply, it is **queued as a
+follow-up** and answered after the current turn finishes — it does not interrupt the
+in-flight response.
+
+## Session model
+
+Each channel and DM gets its **own wolli session**, bound by a `discord:channel`
+tag:
+
+- **Inbound** — an incoming message is routed to the session tagged for its channel.
+  If none exists yet, one is created and tagged on the spot. Histories never bleed
+  across channels, and two channels can run in parallel.
+- **Outbound** — the reply rides the producing session's tag, so the answer always
+  returns to the channel that started the turn — not to whoever messaged most
+  recently.
+
+## Setup
+
+### 1. Create a Discord application
+
+Open the [Discord Developer Portal](https://discord.com/developers/applications) and
+click **New Application**. Name it (e.g. "Wolli") and accept the terms.
+
+### 2. Enable the Message Content Intent
+
+This is the critical step. Open **Bot** in the sidebar, scroll to **Privileged
+Gateway Intents**, toggle **Message Content Intent** to **ON**, and **Save Changes**.
+
+Without it, the bot still receives message events but the message text arrives
+**empty**, so it can never reply. This is the single privileged intent the bot
+needs — you do **not** need Server Members or Presence.
+
+### 3. Reset and copy the bot token
+
+On the same **Bot** page, click **Reset Token**, complete 2FA if prompted, and copy
+the token. It is shown only once — if you lose it, reset and generate a new one. Keep
+it secret.
+
+### 4. Invite the bot
+
+Open **OAuth2 → URL Generator** and select:
+
+- **Scopes:** `bot`
+- **Bot Permissions:** **View Channels**, **Send Messages**, **Read Message History**
+
+Copy the generated URL at the bottom, open it, pick a server you administer, and
+authorize. Only the `bot` scope is required — the `applications.commands` scope is
+not needed.
+
+### 5. Install and onboard in wolli
+
+```bash
+wolli <agent> plugins install ./built-in/plugins/discord
+```
+
+In an interactive terminal this runs onboarding immediately: it prints the connect
+guide, then prompts you to **paste the bot token**. Paste the token from step 3.
+Wolli verifies it with a live `GET /users/@me` call and stores it. That single token
+is the only value you enter.
+
+If you installed non-interactively, onboard later with:
+
+```bash
+wolli <agent> plugins configure discord
+```
+
+### 6. Restart the agent
+
+```bash
+wolli restart <agent>
+```
+
+This starts the gateway producer that connects to Discord. After onboarding a fresh
+integration, restart the agent once so the bot comes online and begins responding.
+
+## Configuration reference
+
+Configuration lives per agent in `~/.wolli/agents/<name>/integrations.json` under
+`discord.default`:
+
+```json
+{
+  "discord": {
+    "default": {
+      "botToken": "...",
+      "allowedChannelIds": ["123456789012345678"]
+    }
+  }
+}
+```
+
+| Field | Required | Default | Purpose |
+|-------|----------|---------|---------|
+| `botToken` | Yes | — | The bot token. Onboarding stores it raw; a `$ENV` / `!cmd` reference placed here by hand also resolves on read. |
+| `allowedChannelIds` | No | *(any channel)* | Allowlist of channel IDs the bot will respond in. Empty or absent accepts **any** channel the bot can read (logged as a warning at startup). |
+
+Discord IDs are snowflakes — keep them as **quoted strings** in JSON, never numbers,
+since a 64-bit snowflake exceeds JavaScript's safe-integer range. To grab a channel
+ID, enable **Developer Mode** in Discord (Settings → Advanced), then right-click a
+channel and **Copy Channel ID**.
+
+`allowedChannelIds` is not asked during onboarding — edit `integrations.json` to set
+it.
+
+## Not supported
+
+The bot is deliberately focused on text chat. It does not provide:
+
+- Mention-gating — it answers every readable message, not only `@mentions`.
+- User, role, or guild allowlists — channel-level `allowedChannelIds` is the only
+  scope control.
+- Threads or auto-threading.
+- Reactions.
+- Native Discord slash commands.
+- Inbound or outbound media, attachments, or voice.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| Bot is online but never replies | Enable the **Message Content Intent** (step 2). Without it the message text arrives empty and there is nothing to answer. |
+| `Disallowed intents` on connect | Same cause: the Message Content Intent is not enabled in the Developer Portal. |
+| No reply right after the first install/onboard | Restart the agent (`wolli restart <agent>`) so the gateway producer starts. |
+| Silence in one specific channel | The bot is missing **View Channels** / **Send Messages** there, or the channel isn't in `allowedChannelIds`. Try a DM to isolate. |
+
+## Security
+
+- `allowedChannelIds` is the only access gate today. With it empty, **any** channel
+  the bot can read is accepted — set it to lock the bot to known channels.
+- There is no per-user or per-role gate. Anyone who can post in an allowed channel
+  can drive the agent, so keep the bot in trusted channels.
+- The bot token grants full control of the bot account — never commit it or share
+  it. Wolli writes `integrations.json` with mode `0600`.

package/built-in/plugins/discord/discord-chat.ts

@@ -0,0 +1,87 @@
+/**
+ * Discord chat extension — maps the transport's `message` events onto wolli sessions:
+ * each channel/DM gets its own session (bound by a `discord:channel` tag), inbound text
+ * is queued as a followUp, and the final assistant text is sent back on `agent_end`.
+ * Paired with `index.ts`.
+ */
+
+import type { AgentMessage } from "@opsyhq/agent";
+import type { ExtensionAPI } from "@opsyhq/wolli";
+
+// Discord's typing state lasts ~10s; refresh a little ahead of that.
+const TYPING_INTERVAL_MS = 8000;
+
+interface DiscordMessage {
+	channelId: string;
+	messageId: string;
+	text: string;
+	author: { id: string; name?: string };
+}
+
+/** Text of the last assistant message; "" for a pure tool-call turn. */
+function finalAssistantText(messages: AgentMessage[]): string {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const m = messages[i];
+		if (m.role !== "assistant") continue;
+		return m.content
+			.filter((c): c is { type: "text"; text: string } => c.type === "text")
+			.map((c) => c.text)
+			.join("")
+			.trim();
+	}
+	return "";
+}
+
+export default function (wolli: ExtensionAPI) {
+	const discord = wolli.getIntegration("discord", "default");
+
+	let typingTimer: ReturnType<typeof setInterval> | undefined;
+
+	discord.on("message", async (data) => {
+		const m = data as DiscordMessage;
+
+		// Reuse this channel's session, or create + tag a fresh one.
+		const channelTag = { "discord:channel": m.channelId };
+		const [match] = await wolli.findSessions(channelTag);
+		const session = match
+			? await wolli.openSession(match.id)
+			: await wolli.createSession({
+					setup: async (sessionManager) => {
+						await sessionManager.appendTags(channelTag);
+					},
+				});
+
+		// followUp: a message arriving mid-turn queues instead of interrupting.
+		void session.sendUserMessage(m.text, { deliverAs: "followUp" });
+	});
+
+	const stopTyping = (): void => {
+		if (typingTimer) {
+			clearInterval(typingTimer);
+			typingTimer = undefined;
+		}
+	};
+
+	wolli.on("agent_start", async (_event, ctx) => {
+		const channelId = ctx.session.getTags()["discord:channel"];
+		if (!channelId) return; // not a discord-bound session
+		const sendTyping = () => {
+			void discord.call("sendTyping", { channelId }).catch(() => {});
+		};
+		sendTyping();
+		stopTyping();
+		typingTimer = setInterval(sendTyping, TYPING_INTERVAL_MS);
+	});
+
+	wolli.on("agent_end", async ({ messages }, ctx) => {
+		stopTyping();
+
+		// Reply goes to the channel that started this turn (the producing session's tag).
+		const channelId = ctx.session.getTags()["discord:channel"];
+		if (!channelId) return; // not a discord-bound session
+
+		const text = finalAssistantText(messages as AgentMessage[]);
+		if (!text) return; // pure tool-call turn — nothing to send
+		await discord.call("sendMessage", { channelId, text });
+	});
+}

package/built-in/plugins/discord/index.ts

@@ -0,0 +1,192 @@
+/**
+ * Discord transport — holds the bot token, emits a `message` event per inbound message;
+ * the paired `discord-chat.ts` extension maps those onto sessions. Transport is the
+ * gateway WebSocket (discord.js `Client`); snowflake ids stay `string`. MESSAGE CONTENT
+ * is a privileged intent — enable it in the Developer Portal or `m.content` is empty.
+ * See README.md for setup.
+ */
+
+import type { IntegrationOnboardContext, IntegrationsAPI } from "@opsyhq/wolli";
+import { Client, Events, GatewayIntentBits, Partials, REST, Routes } from "discord.js";
+import { Type } from "typebox";
+
+/** Discord caps a single message at 2000 UTF-16 code units. */
+const DISCORD_MAX_LENGTH = 2000;
+
+const ONBOARD_GUIDE = [
+	"## Connect Discord",
+	"",
+	"1. Open the [Discord Developer Portal](https://discord.com/developers/applications)",
+	"   and create a **New Application**.",
+	"2. Go to **Bot**, then enable the **MESSAGE CONTENT INTENT** toggle (privileged —",
+	"   without it the bot receives empty message text).",
+	"3. On the **Bot** page, **Reset Token** and copy the token.",
+	"4. Go to **OAuth2 → URL Generator**, select the `bot` scope, copy the generated URL,",
+	"   open it, and invite the bot to your server.",
+	"5. Paste the token on the next screen.",
+	"",
+	"Wolli verifies the token and stores it for this agent.",
+].join("\n");
+
+interface DiscordAccount {
+	botToken: string;
+	allowedChannelIds?: string[];
+}
+
+/** One cached `REST` client per token for the request/response actions. */
+const rests = new Map<string, REST>();
+function getRest(token: string): REST {
+	let rest = rests.get(token);
+	if (!rest) {
+		rest = new REST({ version: "10" }).setToken(token);
+		rests.set(token, rest);
+	}
+	return rest;
+}
+
+/** Split into ≤2000-code-unit chunks without cutting a surrogate pair. */
+function chunkText(text: string, max = DISCORD_MAX_LENGTH): string[] {
+	if (text.length <= max) return [text];
+	const chunks: string[] = [];
+	let i = 0;
+	while (i < text.length) {
+		let end = Math.min(i + max, text.length);
+		if (end < text.length) {
+			const code = text.charCodeAt(end - 1);
+			if (code >= 0xd800 && code <= 0xdbff) end -= 1;
+		}
+		chunks.push(text.slice(i, end));
+		i = end;
+	}
+	return chunks;
+}
+
+/** Guided setup: collect the bot token, verify it via `GET /users/@me`, return it to store. */
+async function onboard(ctx: IntegrationOnboardContext): Promise<{ botToken: string } | undefined> {
+	ctx.ui.notify(ONBOARD_GUIDE, "info");
+
+	const entered = await ctx.ui.input("Paste the bot token from the Discord Developer Portal");
+	if (entered === undefined) return undefined; // cancelled
+	const token = entered.trim();
+	if (!token) {
+		ctx.ui.notify("No token entered.", "error");
+		return undefined;
+	}
+
+	try {
+		const me = (await new REST({ version: "10" }).setToken(token).get(Routes.user())) as { username: string };
+		ctx.ui.notify(`Verified bot ${me.username}.`, "info");
+	} catch (err) {
+		ctx.ui.notify(`Could not verify the token: ${err instanceof Error ? err.message : String(err)}`, "error");
+		return undefined;
+	}
+
+	return { botToken: token };
+}
+
+export default function (wolli: IntegrationsAPI) {
+	wolli.registerIntegration({
+		name: "discord",
+		account: Type.Object({
+			botToken: Type.String(),
+			/** Empty/absent = allow all (logged as a warning). */
+			allowedChannelIds: Type.Optional(Type.Array(Type.String())),
+		}),
+		events: {
+			message: Type.Object({
+				channelId: Type.String(),
+				messageId: Type.String(),
+				text: Type.String(),
+				author: Type.Object({
+					id: Type.String(),
+					name: Type.Optional(Type.String()),
+				}),
+			}),
+		},
+		onboard,
+		actions: {
+			sendMessage: {
+				description: "Send a text message to a channel (chunked at 2000; Discord renders markdown natively).",
+				parameters: Type.Object({
+					channelId: Type.String(),
+					text: Type.String(),
+				}),
+				execute: async (params, ctx) => {
+					const { channelId, text } = params as { channelId: string; text: string };
+					const account = ctx.account as DiscordAccount;
+					const rest = getRest(account.botToken);
+
+					const messageIds: string[] = [];
+					for (const content of chunkText(text)) {
+						const sent = (await rest.post(Routes.channelMessages(channelId), { body: { content } })) as {
+							id: string;
+						};
+						messageIds.push(sent.id);
+					}
+					return { messageIds };
+				},
+			},
+			sendTyping: {
+				description: "Show the 'typing…' indicator in a channel (lasts ~10s).",
+				parameters: Type.Object({
+					channelId: Type.String(),
+				}),
+				execute: async (params, ctx) => {
+					const { channelId } = params as { channelId: string };
+					const account = ctx.account as DiscordAccount;
+					const rest = getRest(account.botToken);
+					await rest.post(Routes.channelTyping(channelId));
+					return { ok: true };
+				},
+			},
+		},
+		run(ctx) {
+			const account = ctx.account as DiscordAccount;
+			const { botToken, allowedChannelIds } = account;
+			const allowAll = !allowedChannelIds || allowedChannelIds.length === 0;
+			if (allowAll) {
+				console.warn("[discord] no allowedChannelIds configured — accepting messages from ANY channel.");
+			}
+
+			const client = new Client({
+				intents: [
+					GatewayIntentBits.Guilds,
+					GatewayIntentBits.GuildMessages,
+					GatewayIntentBits.MessageContent,
+					GatewayIntentBits.DirectMessages,
+				],
+				partials: [Partials.Channel], // required to receive DMs
+			});
+
+			client.on(Events.MessageCreate, (m) => {
+				if (m.author.id === client.user?.id) return; // skip self
+				if (m.author.bot) return; // skip other bots (loop prevention)
+				if (!allowAll && !allowedChannelIds?.includes(m.channelId)) return;
+				const text = m.content;
+				if (!text) return; // empty without the MESSAGE CONTENT intent, or media-only
+
+				ctx.emit("message", {
+					channelId: m.channelId,
+					messageId: m.id,
+					text,
+					author: { id: m.author.id, name: m.author.username },
+				});
+			});
+
+			client.on(Events.Error, (err) => {
+				console.error("[discord] client error:", err.message);
+			});
+
+			// Fire-and-forget: login never settles into a state we await.
+			if (!ctx.signal.aborted) {
+				void client.login(botToken).catch((err) => {
+					console.error("[discord] failed to log in:", err instanceof Error ? err.message : err);
+				});
+			}
+
+			const dispose = () => void client.destroy();
+			ctx.signal.addEventListener("abort", dispose);
+			return dispose;
+		},
+	});
+}

package/built-in/plugins/discord/package.json

@@ -0,0 +1,16 @@
+{
+	"name": "wolli-integration-discord",
+	"private": true,
+	"version": "1.0.0",
+	"type": "module",
+	"wolli": {
+		"integrations": ["./index.ts"],
+		"extensions": ["./discord-chat.ts"]
+	},
+	"dependencies": {
+		"discord.js": "14.26.4"
+	},
+	"peerDependencies": {
+		"@opsyhq/wolli": "*"
+	}
+}

package/built-in/plugins/telegram/README.md

@@ -0,0 +1,153 @@
+# Telegram
+
+Connect a wolli agent to Telegram. The bot runs over Telegram's long-polling API,
+gives each chat its own wolli session, and replies in place. Setup is one message to
+[@BotFather](https://t.me/BotFather) plus a single token prompt — no public URL or
+TLS is required.
+
+## How the bot behaves
+
+Before setup, here's the part most people want to know: this bot answers **every
+text message it receives**. There is no `@mention` gate.
+
+| Context | Behavior |
+|---------|----------|
+| **Private chats** | Responds to every text message. |
+| **Group chats** | Responds to every text message it can see in any chat. No `@mention` required. Scope where it listens with `allowedChatIds`. |
+| **Its own messages** | Ignored. The bot skips messages it sent itself, so it can't loop. |
+| **Non-text messages** | Skipped. Photos, stickers, voice, and other media are not handled — only text messages reach the agent. |
+| **Slash commands** | `/new`, `/status`, `/help` are handled locally and never sent to the model (see [Commands](#commands)). |
+
+While a turn runs, the bot shows Telegram's **typing…** indicator and re-sends it
+every ~4 seconds (Telegram clears the state on its own) until the reply lands.
+
+Replies are chunked at **4096 characters** (Telegram's per-message limit) and each
+chunk is sent with the configured **parse mode** (`MarkdownV2` by default). Telegram,
+unlike Discord, needs a parse mode to render formatting — and if it rejects a chunk's
+formatting, that chunk is **re-sent as plain text**, so a stray markdown character
+never silently drops the reply.
+
+If a new message arrives while the agent is mid-reply, it is **queued as a follow-up**
+and answered after the current turn finishes — it does not interrupt the in-flight
+response.
+
+## Commands
+
+These commands are registered as the bot's command menu via BotFather on startup and
+are handled by the integration directly, not forwarded to the model:
+
+| Command | Action |
+|---------|--------|
+| `/new` | Start a fresh session for this chat. The new session becomes the active one; the previous session stays addressable but new messages route to the new one. |
+| `/status` | Show the current session name and the model used in the last reply. |
+| `/help` | List the available commands. |
+
+Any other `/command` returns `Unknown command: /<name>. Try /help.`
+
+## Session model
+
+Each chat gets its **own wolli session**, bound by a `telegram:chat` tag:
+
+- **Inbound** — an incoming message is routed to the session tagged for its chat. If
+  none exists yet, one is created and tagged on the spot. Histories never bleed across
+  chats, and two chats can run in parallel.
+- **Outbound** — the reply rides the producing session's tag, so the answer always
+  returns to the chat that started the turn — not to whoever messaged most recently.
+
+`/new` creates a fresh session tagged for the chat; because it becomes the newest
+match for that tag, subsequent messages route to it.
+
+## Setup
+
+### 1. Create a bot with BotFather
+
+Open [@BotFather](https://t.me/BotFather) in Telegram and send `/newbot`. Pick a name
+and a username; BotFather replies with a **bot token** like `123456:ABC-DEF...`. Copy
+it — you'll paste it in the next step. Keep it secret.
+
+### 2. Install and onboard in wolli
+
+```bash
+wolli <agent> plugins install ./built-in/plugins/telegram
+```
+
+In an interactive terminal this runs onboarding immediately: it prints the BotFather
+walkthrough, then prompts you to **paste the bot token**. Paste the token from step 1.
+Wolli verifies it with a live `getMe()` call and stores it. That single token is the
+only value you enter.
+
+If you installed non-interactively, onboard later with:
+
+```bash
+wolli <agent> plugins configure telegram
+```
+
+### 3. Restart the agent
+
+```bash
+wolli restart <agent>
+```
+
+This starts the long-poll producer that connects to Telegram. After onboarding a
+fresh integration its producer starts only on the next daemon start, so restart the
+agent once for the bot to come online and begin responding.
+
+## Configuration reference
+
+Configuration lives per agent in `~/.wolli/agents/<name>/integrations.json` under
+`telegram.default`:
+
+```json
+{
+  "telegram": {
+    "default": {
+      "botToken": "123456:ABC-DEF...",
+      "allowedChatIds": [123456789],
+      "parseMode": "MarkdownV2"
+    }
+  }
+}
+```
+
+| Field | Required | Default | Purpose |
+|-------|----------|---------|---------|
+| `botToken` | Yes | — | The BotFather token. Onboarding stores it raw; a `$ENV` / `!cmd` reference placed here by hand also resolves on read. |
+| `allowedChatIds` | No | *(any chat)* | Allowlist of chat IDs the bot will respond in. Empty or absent accepts **any** chat (logged as a warning at startup). |
+| `parseMode` | No | `MarkdownV2` | Outbound formatting: `"MarkdownV2"`, `"HTML"`, or `"plain"` (disables parse mode). |
+
+Telegram chat IDs are **numbers** — keep them unquoted in JSON, unlike Discord's
+quoted snowflakes.
+
+`allowedChatIds` and `parseMode` are not asked during onboarding — edit
+`integrations.json` to set them.
+
+## Not supported
+
+The bot is deliberately focused on text chat. It does not provide:
+
+- A durable cursor — on start it calls `deleteWebhook({ drop_pending_updates: true })`,
+  so a restart never replays a backlog but also drops messages sent while the bot was
+  offline.
+- Inbound media or images — only text messages are handled.
+- Webhook mode — the transport is long polling only.
+- Callback queries or inline keyboards.
+- Outbound rate-limit throttling.
+- Mention-gating, or per-user / per-role allowlists — chat-level `allowedChatIds` is
+  the only scope control.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| No reply right after the first install/onboard | Restart the agent (`wolli restart <agent>`) so the long-poll producer starts. |
+| Bot ignores messages sent while it was offline | Expected — `deleteWebhook({ drop_pending_updates: true })` clears the backlog on start. The bot only sees messages that arrive while it is running. |
+| Formatting looks broken, or a message seems to drop | A chunk that fails parse-mode parsing is re-sent as plain text. Set `parseMode: "plain"` to disable formatting entirely. |
+
+## Security
+
+- `allowedChatIds` is the only access gate. With it empty, **any** chat is accepted —
+  set it to lock the bot to known chats.
+- There is no per-user gate beyond that. Anyone who can post in an allowed chat can
+  drive the agent, so keep the bot in trusted chats.
+- The bot token grants full control of the bot account — never commit it or share it.
+  Wolli writes `integrations.json` with mode `0600`.

package/{plugins → built-in/plugins}/telegram/index.ts

@@ -12,7 +12,7 @@
  *
  * ## Install + configure
  *
- *   wolli <agent> plugins install ./plugins/telegram
+ *   wolli <agent> plugins install ./built-in/plugins/telegram
  *   # then paste the BotFather token into the guided prompt — that's it.
  *
  * Onboarding asks for the BotFather token directly, verifies it with a live `getMe()`,

package/dist/cli.js

@@ -257407,6 +257407,8 @@ __export(src_exports4, {
   getAuthPath: () => getAuthPath,
   getAvailableThemesWithPaths: () => getAvailableThemesWithPaths,
   getBinDir: () => getBinDir,
+  getBuiltInDir: () => getBuiltInDir,
+  getBuiltInSkillsDir: () => getBuiltInSkillsDir,
   getCustomThemesDir: () => getCustomThemesDir,
   getDaemonHost: () => getDaemonHost,
   getDaemonRuntimeDir: () => getDaemonRuntimeDir,
@@ -274245,8 +274247,14 @@ function getReadmePath() {
 function getDocsPath() {
   return resolve(join(getPackageDir(), "docs"));
 }
+function getBuiltInDir() {
+  return resolve(join(getPackageDir(), "built-in"));
+}
 function getPluginsDir() {
-  return resolve(join(getPackageDir(), "plugins"));
+  return join(getBuiltInDir(), "plugins");
+}
+function getBuiltInSkillsDir() {
+  return join(getBuiltInDir(), "skills");
 }
 function getHomeDir() {
   const envHome = process.env[ENV_HOME];
@@ -278576,12 +278584,13 @@ var Agent2 = class {
     const token = getDaemonToken() || persisted;
     const [latest] = this.getAgentState().sessions;
     if (!latest) throw new Error(`No session for agent "${this.name}".`);
+    const birthStartedAt = (await getDaemonInfo(base))?.startedAt ?? null;
     const snap = await this.send(latest.sessionId, { type: "deploy" });
     if (getServiceManager().kind === "none") return snap;
     await requestDaemonShutdown(base, token);
     await waitForShutdown(base);
     getServiceManager().start(this.name);
-    await waitForHealth(base);
+    await waitForRestart(base, birthStartedAt);
     this.controlStream?.close();
     for (const handle of this.sessions.values()) handle.close();
     this.sessions.clear();
@@ -278636,6 +278645,7 @@ var Agent2 = class {
     const base = `http://${getDaemonHost()}:${port}`;
     const token = getDaemonToken() || persisted;
     const service = getServiceManager();
+    const previousStartedAt = (await getDaemonInfo(base))?.startedAt ?? null;
     if (service.kind !== "none" && await service.isRunning(this.name)) {
       service.stop(this.name);
       await waitForShutdown(base);
@@ -278646,7 +278656,7 @@ var Agent2 = class {
       const [command, ...commandArgs] = daemonLaunchCommand(this.name);
       spawn2(command, commandArgs, { detached: true, stdio: "ignore" }).unref();
     }
-    await waitForHealth(base);
+    await waitForRestart(base, previousStartedAt);
   }
 };
 var SessionHandle = class _SessionHandle {
@@ -278917,6 +278927,16 @@ var SessionHandle = class _SessionHandle {
 var HEALTH_TIMEOUT_MS = 15e3;
 var HEALTH_POLL_MS = 150;
 var sleep5 = (ms2) => new Promise((resolve13) => setTimeout(resolve13, ms2));
+async function getDaemonInfo(base) {
+  try {
+    const response = await fetch(`${base}/health`, { signal: AbortSignal.timeout(1e3) });
+    if (!response.ok) return null;
+    const { status, pid, startedAt } = await response.json();
+    return status === "ok" && pid !== void 0 && startedAt !== void 0 ? { pid, startedAt } : null;
+  } catch {
+    return null;
+  }
+}
 async function isHealthy(base) {
   try {
     const response = await fetch(`${base}/health`, { signal: AbortSignal.timeout(1e3) });
@@ -278942,6 +278962,15 @@ async function waitForShutdown(base) {
   }
   throw new Error(`Daemon at ${base} did not shut down within ${HEALTH_TIMEOUT_MS / 1e3}s.`);
 }
+async function waitForRestart(base, since) {
+  const deadline = Date.now() + HEALTH_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    const info = await getDaemonInfo(base);
+    if (info && info.startedAt !== since) return;
+    await sleep5(HEALTH_POLL_MS);
+  }
+  throw new Error(`Daemon at ${base} did not restart within ${HEALTH_TIMEOUT_MS / 1e3}s.`);
+}
 async function requestDaemonShutdown(base, token) {
   try {
     const list2 = await fetch(`${base}/sessions`, {
@@ -310137,8 +310166,9 @@ var BIRTH_INSTRUCTION = [
   "",
   "You cannot act unattended yet. This session exists to make you real: open the conversation yourself,",
   "then interview your human hard \u2014 one sharp question at a time \u2014 until you understand what you are for",
-  "and who they are. Record as you go with the memory tool: USER = durable facts about your human;",
-  "MEMORY = your own durable notes. Their answers are raw material, not gospel \u2014 distill what you're",
+  "and who they are. Record with the memory tool only what will still matter next session: USER = stable",
+  "facts about your human (name, role, timezone, how they work, standing constraints); MEMORY = your own",
+  "durable notes. Their answers are raw material, not gospel \u2014 distill what you're",
   "really for, push back, and ask the follow-up. Do not hand-write SOUL.md and do not start doing the",
   "job yet; first become yourself.",
   "",
@@ -310162,7 +310192,9 @@ var EXTENDING_YOURSELF = [
   "commands, events, UI), connect external services and message channels via integrations, and add",
   "skills, prompt templates, and themes \u2014 bundle and install them as plugins. Before building from",
   "scratch, check the bundled plugins folder (path below) for a ready-made plugin: if one fits the need",
-  "(e.g. Telegram for chat), have your human install and onboard it instead of writing your own. Read",
+  "(e.g. Telegram for chat), have your human install and onboard it instead of writing your own. Skills",
+  "are lighter \u2014 the built-in skills folder (path below) holds ready-made ones you can install yourself by",
+  "copying into your own skills/ folder; prefer a fitting built-in skill over authoring a new one. Read",
   "the relevant docs below and follow their cross-references before building anything."
 ].join("\n");
 function section(title, content) {
@@ -310186,8 +310218,9 @@ function buildSystemPrompt(options2) {
     "immediately but become effective next session). Each is modifiable on its own:",
     "- SOUL.md \u2014 who you are, what you're for, how you operate. Authored when you deploy; once deployed you",
     "  rewrite it yourself with the bash tool.",
-    "- MEMORY.md \u2014 your own durable notebook. Edit it with the memory tool.",
-    "- USER.md \u2014 durable facts about your human. Edit it with the memory tool.",
+    "- MEMORY.md \u2014 your own durable notebook: knowledge, decisions, and learnings you accumulate. Edit it with the memory tool.",
+    "- USER.md \u2014 durable facts about your human: name, role, timezone, how they like to work, lasting constraints. Edit it with the memory tool.",
+    "- Save to either only what will still matter in a future session.",
     "",
     section("SOUL.md", soul),
     "",
@@ -310199,6 +310232,7 @@ function buildSystemPrompt(options2) {
   const readmePath = getReadmePath();
   const docsPath = getDocsPath();
   const pluginsDir = getPluginsDir();
+  const builtInSkillsDir = getBuiltInSkillsDir();
   parts.push(
     "",
     `## ${APP_NAME} documentation (read when the user asks about ${APP_NAME} itself \u2014 its extensions, integrations, skills, prompt templates, themes, plugins, or SDK \u2014 or when you extend or modify yourself)`,
@@ -310206,6 +310240,7 @@ function buildSystemPrompt(options2) {
     `- Additional docs: ${docsPath} (resolve docs/... under here, not the current working directory)`,
     `- Topics: extensions (docs/extensions.md), integrations (docs/integrations.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), themes (docs/themes.md), plugins (docs/plugins.md), sdk (docs/sdk.md)`,
     `- Bundled plugins ready to install: ${pluginsDir} (e.g. telegram, scheduler) \u2014 prefer installing a fitting one over building from scratch; have your human run \`${APP_NAME} <name> plugins install <path>\` then onboard it`,
+    `- Built-in skills ready to install: ${builtInSkillsDir} \u2014 browse them, then install one yourself by copying its folder into your own skills/ dir (\`mkdir -p skills && cp -r ${builtInSkillsDir}/<name> skills/\`); it loads next session`,
     `- When working on ${APP_NAME} topics, read the docs and follow .md cross-references before implementing`,
     `- Always read ${APP_NAME} .md files completely and follow links to related docs`
   );
@@ -312727,7 +312762,7 @@ function createMemoryTool(name) {
   return {
     name: "memory",
     label: "Memory",
-    description: "Edit your curated memory. MEMORY.md is your own durable notebook; USER.md holds facts about your human. (Your SOUL.md \u2014 who you are \u2014 is a free-form file you rewrite with the bash tool instead.) Edits are saved immediately but only appear in your prompt on your next session. Keep entries concise.",
+    description: "Edit your curated memory. MEMORY.md is your durable notebook (knowledge, decisions, learnings); USER.md holds durable facts about your human (role, timezone, working style, standing constraints). Save only what will still matter next session. (Your SOUL.md \u2014 who you are \u2014 is a free-form file you rewrite with the bash tool instead.) Edits are saved immediately but only appear in your prompt on your next session. Keep entries concise.",
     parameters: memorySchema,
     executionMode: "sequential",
     execute: async (_toolCallId, params) => {
@@ -318685,8 +318720,9 @@ async function handleCommand(runtime, session, cmd, requestShutdown) {
       await runtime.reload();
       return ok2(id, "update_plugins");
     }
-    // Onboarding writes through the runtime's live account store, so no second reload is needed; the
-    // source scopes onboarding to the just-installed plugin's integrations that declare `onboard`.
+    // Onboarding writes the account to the live store, but its producer (e.g. a Discord/Telegram
+    // gateway) starts only on the next daemon start, so the CLI tells the user to restart the agent.
+    // The `source` scopes onboarding to the just-installed plugin's integrations that declare `onboard`.
     case "onboard_plugin":
       return ok2(id, "onboard_plugin", {
         results: await runDaemonOnboarding(runtime, session.ui, ({ integrations, pluginManager }) => {
@@ -325419,7 +325455,7 @@ function printOnboardResults(agent, results, emptyMessage) {
     switch (status) {
       case "connected":
         console.log(source_default.green(`${service} connected.`));
-        console.log(source_default.dim(`Run "${APP_NAME} ${agent}" to use it.`));
+        console.log(source_default.dim(`Restart the agent for it to take effect: ${APP_NAME} restart ${agent}`));
         break;
       case "cancelled":
         console.log(source_default.dim(`${service}: onboarding cancelled.`));

package/docs/skills.md

@@ -7,6 +7,7 @@ Wolli implements the [Agent Skills standard](https://agentskills.io/specificatio
 ## Table of Contents
 
 - [Locations](#locations)
+- [Built-in Skills](#built-in-skills)
 - [How Skills Work](#how-skills-work)
 - [Skill Commands](#skill-commands)
 - [Skill Structure](#skill-structure)
@@ -45,6 +46,19 @@ To use skills from Claude Code or OpenAI Codex, add their directories to setting
 }
 ```
 
+## Built-in Skills
+
+Wolli ships a catalog of ready-made skills in the package's `built-in/skills/` directory. These are **not loaded automatically** — they are a library to install from, the same way bundled plugins are. The agent browses them and installs the ones it wants.
+
+Installing a built-in skill is just a copy into the agent's own `skills/` folder (the agent's working directory is its home, so `skills/` is relative):
+
+```bash
+mkdir -p skills
+cp -r <built-in-skills-dir>/<name> skills/
+```
+
+The agent is told the absolute `<built-in-skills-dir>` path in its system prompt. After the copy the skill loads on the next session (or after `/reload`), at which point it appears in the available-skills list and as `/skill:<name>`. The copy lives in the agent's home, so the agent owns it and can edit it freely without affecting the built-in original.
+
 ## How Skills Work
 
 1. At startup, Wolli scans skill locations and extracts names and descriptions

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "wolli",
-	"version": "0.0.2",
+	"version": "0.0.3",
 	"description": "Persistent, purposeful agent CLI with memory and identity",
 	"type": "module",
 	"piConfig": {
@@ -12,7 +12,7 @@
 	},
 	"files": [
 		"dist",
-		"plugins",
+		"built-in",
 		"docs",
 		"native"
 	],