Skip to content

Commit 3e76fac

Browse files
MervinPraisonMervinPraison
authored
Merge pull request #213 from MervinPraison/claude/issue-212-20260421-1600
docs(onboard): update wizard docs for leaner 4-question flow + drop home_channel (PR #1491)
2 parents e8d5765 + d549e2b commit 3e76fac

2 files changed

Lines changed: 26 additions & 99 deletions

File tree

‎docs/features/onboard.mdx‎

Lines changed: 24 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -36,8 +36,6 @@ graph LR
3636

3737
<Steps>
3838
<Step title="Run the onboard wizard">
39-
Launch the interactive bot setup wizard:
40-
4139
```bash
4240
# Zero prompts once you have the token — wizard configures the bot
4341
# and installs the background daemon automatically.
@@ -49,28 +47,17 @@ Once tokens are collected, the daemon is installed automatically by default. Run
4947
</Note>
5048
</Step>
5149

52-
<Step title="Pick your platform">
53-
Select from the supported messaging platforms:
50+
<Step title="Answer 4 questions">
51+
The wizard asks exactly 4 questions — everything else uses sensible defaults:
5452

55-
```
56-
Choose a platform:
57-
1. Telegram
58-
2. Discord
59-
3. Slack
60-
4. WhatsApp
61-
```
62-
63-
Each platform has different token requirements and setup steps.
53+
1. **Which platform(s)?** — Telegram, Discord, Slack, WhatsApp (multi-select)
54+
2. **Paste your bot token** — hidden input, validated against the platform API
55+
3. **Allowed user IDs** — comma-separated allowlist (security). Leave blank for open access (not recommended).
56+
4. **Install as background service?** — `Y` on desktop, auto-skipped on CI/headless.
6457
</Step>
6558

66-
<Step title="Configure tokens and security">
67-
The wizard now supports multiple platforms and reads environment variables first. For each platform:
68-
69-
- Enter bot tokens (password-hidden)
70-
- Configure user allowlists for security
71-
- Set home channels for proactive messages
72-
73-
Tokens are automatically validated and the daemon is installed silently.
59+
<Step title="You're done">
60+
The wizard writes bot configuration to `~/.praisonai/bot.yaml`, stores tokens/secrets in `~/.praisonai/.env` only (chmod 600), and shows the ✅ Done panel with your dashboard URL.
7461
</Step>
7562
</Steps>
7663

@@ -100,24 +87,26 @@ The onboarding process follows these phases:
10087
| Phase | Description |
10188
|-------|-------------|
10289
| **Platform Selection** | Choose Telegram, Discord, Slack, or WhatsApp |
103-
| **Token Entry** | Paste the bot token for your chosen platform |
104-
| **Validation** | Wizard tests the token with the platform API |
105-
| **Auto-install Daemon** | Automatically sets up the platform daemon (launchd/systemd/Windows Task) |
90+
| **Token Entry** | Paste the bot token for your chosen platform and validate it against the platform API |
91+
| **Security Setup** | Set allowed user IDs (or leave blank for open access) |
92+
| **Daemon Install** | Sets up the platform daemon (launchd/systemd/Windows Task) |
10693
| **Configuration** | Writes config files to `~/.praisonai/` |
10794
| **Completion** | Shows the ✅ Done panel with all connection details |
10895

10996
---
11097

111-
## What Gets Installed
98+
## What The Wizard Writes
11299

113-
When onboarding completes successfully, the wizard installs:
100+
| File | Contents |
101+
|------|----------|
102+
| `~/.praisonai/bot.yaml` | Platform routing, token env-var references, allowlist, agent defaults |
103+
| `~/.praisonai/.env` | Bot token(s), `*_ALLOWED_USERS`, `GATEWAY_AUTH_TOKEN` (chmod 600) |
114104

115-
| Component | Location | Purpose |
116-
|-----------|----------|---------|
117-
| **Platform daemon** | System service (launchd/systemd/Windows Task) | Keeps bot running in background |
118-
| **Bot configuration** | `~/.praisonai/config/` | Stores tokens and settings |
119-
| **Gateway auth token** | `~/.praisonai/.env` (env var `GATEWAY_AUTH_TOKEN`) | Authentication for web dashboard |
120-
| **Dashboard URL** | Printed in Done panel | Local web interface |
105+
Agent name (`assistant`) and instructions (`"You are a helpful AI assistant."`) use sensible defaults — edit `~/.praisonai/bot.yaml` to customise. The file contains the full schema as inline documentation.
106+
107+
<Note>
108+
**Upgrading?** Older `bot.yaml` files may contain a `home_channel` key (for example, `home_channel: ${TELEGRAM_HOME_CHANNEL}` or the equivalent for Discord / Slack / WhatsApp). This was never read by the gateway and is safe to delete. Re-running `praisonai onboard` and accepting the overwrite regenerates a clean file.
109+
</Note>
121110

122111
---
123112

@@ -174,74 +163,12 @@ Re-running the wizard will:
174163
- Skip daemon installation if already installed and running (prints `✓ Daemon already installed and running`)
175164
- Preserve existing chat histories and agent memory
176165

177-
<Note>
178-
If the daemon is already installed, re-running `praisonai onboard` is a no-op for the daemon service. Only configuration files are updated.
179-
</Note>
180-
181-
---
182-
183-
## Manage the Daemon
184-
185-
The onboard wizard installs platform-specific daemon services. Use these commands to restart after configuration changes:
186-
187-
<Tabs>
188-
<Tab title="macOS">
189-
```bash
190-
# Restart the daemon service
191-
launchctl kickstart -k gui/$(id -u)/ai.praison.bot
192-
193-
# Check daemon status
194-
launchctl list | grep ai.praison
195-
```
196-
197-
Service label: `ai.praison.bot` (launchd)
198-
</Tab>
199-
200-
<Tab title="Linux">
201-
```bash
202-
# Restart the daemon service
203-
systemctl --user restart praisonai-bot
204-
205-
# Check daemon status
206-
systemctl --user status praisonai-bot
207-
```
208-
209-
Service unit: `praisonai-bot` (systemd)
210-
</Tab>
211-
212-
<Tab title="Windows">
213-
```bash
214-
# Restart the daemon service
215-
schtasks /End /TN PraisonAIGateway && schtasks /Run /TN PraisonAIGateway
216-
217-
# Check daemon status
218-
schtasks /Query /TN PraisonAIGateway
219-
```
220-
221-
Service name: `PraisonAIGateway` (Task Scheduler)
222-
</Tab>
223-
</Tabs>
224-
225-
---
226-
227-
## Terminology
228-
229-
Understanding the commands and what they actually do:
166+
The config file path is **always** `~/.praisonai/bot.yaml` (no longer prompted for). When re-running, the overwrite prompt now says `{path} exists. Overwrite with fresh config?` with `Kept existing file` on decline.
230167

231168
<Note>
232-
**Important distinction**: `praisonai gateway start` runs in the **foreground** (not a daemon). The daemon is installed by `praisonai gateway install` or automatically by `praisonai onboard`.
169+
If the daemon is already installed, re-running `praisonai onboard` is a no-op for the daemon service. Only configuration files are updated.
233170
</Note>
234171

235-
| Command | What it does |
236-
|---------|--------------|
237-
| `praisonai gateway start` | Runs the gateway **in the foreground**. Not a daemon. |
238-
| `praisonai gateway install` | Installs the launchd/systemd/Task-Scheduler service that auto-runs `praisonai gateway start` in the background with `KeepAlive=true`. |
239-
| `praisonai gateway status` | Reports whether the daemon is loaded + running. |
240-
| `praisonai gateway uninstall` | Removes the daemon service. |
241-
| `praisonai onboard` | Configures messaging bots and automatically runs `praisonai gateway install` |
242-
243-
The daemon service literally wraps `praisonai gateway start --config ~/.praisonai/bot.yaml` to run it persistently in the background.
244-
245172
---
246173

247174
## Relationship to Setup
@@ -344,7 +271,7 @@ Telegram has the simplest setup process and most permissive API limits. Use it f
344271
</Accordion>
345272

346273
<Accordion title="Keep tokens secure">
347-
Bot tokens are stored in `~/.praisonai/config/`. Ensure this directory has proper permissions (600) and exclude it from version control.
274+
Bot tokens are stored in `~/.praisonai/.env`. Ensure this file has proper permissions (600) and exclude it from version control.
348275
</Accordion>
349276

350277
<Accordion title="Test the dashboard connection">

‎docs/install/installer.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ flowchart TD
6969
Runs `praisonai setup` for LLM configuration
7070
</Step>
7171
<Step title="Bot Onboarding">
72-
Optional `praisonai onboard` for messaging bots (Telegram/Discord/Slack/WhatsApp)
72+
Optional `praisonai onboard` for messaging bots — asks 4 questions to configure Telegram/Discord/Slack/WhatsApp
7373
</Step>
7474
<Step title="Final Summary">
7575
Shows either onboard wizard's ✅ Done panel or installer's Next Steps
@@ -152,7 +152,7 @@ curl -fsSL https://praison.ai/install.sh | bash -s -- --help
152152
After successful installation and verification, the installer runs an interactive onboarding sequence:
153153

154154
1. **Setup wizard** (`praisonai setup`) - Configure LLM API keys
155-
2. **Bot onboarding** (`praisonai onboard`) - Set up messaging bots (default: Yes)
155+
2. **Bot onboarding** (`praisonai onboard`) - Asks 4 questions to set up messaging bots (default: Yes). See the [onboard guide](/docs/features/onboard) for details.
156156
3. **Final summary** - Either the onboard wizard's ✅ Done panel or installer's Next Steps
157157

158158
**Two possible end states:**

0 commit comments

Comments
 (0)