Skip to content

docs(onboard): update wizard docs for leaner 4-question flow + drop home_channel (PR #1491) #213

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
MervinPraison wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs(onboard): update wizard docs for leaner 4-question flow + drop home_channel (PR #1491) #213

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bda30cf
docs(onboard): update wizard docs for leaner 4-question flow + drop h…
MervinPraison Apr 21, 2026
d549e2b
docs(onboard): resolve merge conflicts and address review feedback
MervinPraison Apr 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 24 additions & 97 deletions docs/features/onboard.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,6 @@ graph LR

<Steps>
<Step title="Run the onboard wizard">
Launch the interactive bot setup wizard:

```bash
# Zero prompts once you have the token — wizard configures the bot
# and installs the background daemon automatically.
Expand All @@ -49,28 +47,17 @@ Once tokens are collected, the daemon is installed automatically by default. Run
</Note>
</Step>

<Step title="Pick your platform">
Select from the supported messaging platforms:
<Step title="Answer 4 questions">
The wizard asks exactly 4 questions — everything else uses sensible defaults:
Comment on lines 37 to +51
Copy link

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this repo, every block appears to use (e.g., docs/install/installer.mdx). Switching to bare here is inconsistent and may render without labels (or fail depending on the Mintlify component). Add explicit titles for these first two steps to match existing docs patterns.

Copilot uses AI. Check for mistakes.

```
Choose a platform:
1. Telegram
2. Discord
3. Slack
4. WhatsApp
```

Each platform has different token requirements and setup steps.
1. **Which platform(s)?** — Telegram, Discord, Slack, WhatsApp (multi-select)
2. **Paste your bot token** — hidden input, validated against the platform API
3. **Allowed user IDs** — comma-separated allowlist (security). Leave blank for open access (not recommended).
4. **Install as background service?** — `Y` on desktop, auto-skipped on CI/headless.
Comment on lines +50 to +56
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify onboarding prompt and daemon behavior in the SDK implementation.
rg -n -C3 'Prompt\.ask|extra_env|Confirm\.ask\("\\nInstall as background service|Skipping daemon install' praisonai/cli/features/onboard.py

Repository: MervinPraison/PraisonAIDocs

Length of output: 6247

Update onboarding documentation to reflect actual SDK prompt behavior.

The wizard does not ask "exactly 4 questions." For each selected platform, it prompts for that platform's token plus any extra environment variables (e.g., Slack requires SLACK_APP_TOKEN, WhatsApp requires WHATSAPP_PHONE_NUMBER_ID). The daemon install prompt defaults to Yes and is skipped only when required tokens are missing—not automatically skipped on CI/headless environments as currently stated.

Suggested wording adjustments 
-<Step title="Answer 4 questions">
-The wizard asks exactly 4 questions — everything else uses sensible defaults:
+<Step title="Answer the 4-step wizard">
+The wizard guides you through 4 setup steps — token and extra env prompts appear for each selected integration:

 1. **Which platform(s)?** — Telegram, Discord, Slack, WhatsApp (multi-select)
 2. **Paste your bot token** — hidden input, validated against the platform API
 3. **Allowed user IDs** — comma-separated allowlist (security). Leave blank for open access (not recommended).
-4. **Install as background service?** — `Y` on desktop, auto-skipped on CI/headless.
+4. **Install as background service?** — defaults to `Y`; skipped when required tokens are missing.
-| **Daemon Install** | Sets up the platform daemon (launchd/systemd/Windows Task) |
+| **Daemon Install** | Offers to set up the platform daemon (launchd/systemd/Windows Task) |

Also applies to: 90-92

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/features/onboard.mdx` around lines 50 - 56, Update the "Answer 4
questions" Step text to remove the claim that the wizard asks exactly four
questions and instead state that it asks a base set plus per-platform prompts:
for each selected platform the wizard will also request that platform's bot
token and any additional required environment variables (e.g., Slack ->
SLACK_APP_TOKEN, WhatsApp -> WHATSAPP_PHONE_NUMBER_ID). Also correct the
daemon/install line so it says the background service install defaults to Yes
and is only skipped when required tokens/credentials are missing (not
automatically on CI/headless). Modify the same wording used around the Step
title "Answer 4 questions" and the repeated text referenced in the doc so both
places reflect these behaviors.

</Step>

<Step title="Configure tokens and security">
The wizard now supports multiple platforms and reads environment variables first. For each platform:

- Enter bot tokens (password-hidden)
- Configure user allowlists for security
- Set home channels for proactive messages

Tokens are automatically validated and the daemon is installed silently.
<Step title="You're done">
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.
</Step>
</Steps>

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

---

## What Gets Installed
## What The Wizard Writes

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

| Component | Location | Purpose |
|-----------|----------|---------|
| **Platform daemon** | System service (launchd/systemd/Windows Task) | Keeps bot running in background |
| **Bot configuration** | `~/.praisonai/config/` | Stores tokens and settings |
| **Gateway auth token** | `~/.praisonai/.env` (env var `GATEWAY_AUTH_TOKEN`) | Authentication for web dashboard |
| **Dashboard URL** | Printed in Done panel | Local web interface |
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.
Comment on lines +98 to +105
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add the required configuration table and a real schema pointer.

The new file-output table is useful, but this page still needs a Configuration Options table with Option, Type, Default, and Description, and line 105 should link to the schema/reference instead of saying the generated file contains the full schema inline. As per coding guidelines, “Configuration documentation must include a table with columns: Option, Type, Default, Description for all SDK config options.”

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/features/onboard.mdx` around lines 98 - 105, Add a "Configuration
Options" table under the "What The Wizard Writes" section that lists each
SDK-configurable option for ~/.praisonai/bot.yaml with columns Option, Type,
Default, Description (populate rows for platform routing, token env-var refs,
allowlist, agent defaults and any other SDK options referenced in the doc); also
replace the sentence claiming the generated file contains the full schema inline
with a direct link text to the canonical schema/reference (pointing to the
authoritative schema location used by the project) so readers can view the full
schema rather than relying on the generated file.


<Note>
**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.
Comment on lines +107 to +108
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify whether the onboarding generator still emits home_channel.
rg -n -C4 'home_channel|home_channel_env' praisonai/cli/features/onboard.py

Repository: MervinPraison/PraisonAIDocs

Length of output: 3825

Documentation contradicts implementation: home_channel will be re-added, not cleaned up.

The note at lines 107–108 claims re-running praisonai onboard with overwrite will "regenerate a clean file" without home_channel, but praisonai/cli/features/onboard.py lines 199–201 conditionally append home_channel whenever a platform's home_channel_env is present (all four platforms define this). If the corresponding environment variables remain set, home_channel will be reintroduced.

Either:

  1. Update the generator to omit home_channel on regeneration (if truly deprecated), or
  2. Soften the migration note to clarify that home_channel will persist if environment variables remain set.
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/features/onboard.mdx` around lines 107 - 108, The docs note is
inaccurate: the generator in praisonai/cli/features/onboard.py conditionally
re-appends home_channel when platforms define a home_channel_env, so re-running
praisonai onboard will reintroduce home_channel if those environment vars remain
set; update the Note in docs/features/onboard.mdx to state that home_channel
will persist when the corresponding environment variables (home_channel_env) are
present (or instruct to unset them) rather than saying the file will be cleaned,
and reference the conditional append logic in praisonai/cli/features/onboard.py
that re-adds home_channel.

</Note>

---

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

<Note>
If the daemon is already installed, re-running `praisonai onboard` is a no-op for the daemon service. Only configuration files are updated.
</Note>

---

## Manage the Daemon

The onboard wizard installs platform-specific daemon services. Use these commands to restart after configuration changes:

<Tabs>
<Tab title="macOS">
```bash
# Restart the daemon service
launchctl kickstart -k gui/$(id -u)/ai.praison.bot

# Check daemon status
launchctl list | grep ai.praison
```

Service label: `ai.praison.bot` (launchd)
</Tab>

<Tab title="Linux">
```bash
# Restart the daemon service
systemctl --user restart praisonai-bot

# Check daemon status
systemctl --user status praisonai-bot
```

Service unit: `praisonai-bot` (systemd)
</Tab>

<Tab title="Windows">
```bash
# Restart the daemon service
schtasks /End /TN PraisonAIGateway && schtasks /Run /TN PraisonAIGateway

# Check daemon status
schtasks /Query /TN PraisonAIGateway
```

Service name: `PraisonAIGateway` (Task Scheduler)
</Tab>
</Tabs>

---

## Terminology

Understanding the commands and what they actually do:
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.
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add the praisonai doctor path-discovery pointer.

This covers the fixed ~/.praisonai/bot.yaml path, but the linked issue also asks users to use praisonai doctor for path discovery/verification. Add a short linked sentence to the existing doctor docs.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/features/onboard.mdx` at line 166, Add a short linked sentence after the
sentence that states the config path is always `~/.praisonai/bot.yaml` (the
phrase appears in docs/features/onboard.mdx) directing users to run `praisonai
doctor` for path discovery/verification; link the words "praisonai doctor" to
the existing doctor docs page and keep the sentence concise (e.g., "For path
discovery and verification, run prais onai doctor.") so readers can easily
verify the config location.


<Note>
**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`.
If the daemon is already installed, re-running `praisonai onboard` is a no-op for the daemon service. Only configuration files are updated.
</Note>

| Command | What it does |
|---------|--------------|
| `praisonai gateway start` | Runs the gateway **in the foreground**. Not a daemon. |
| `praisonai gateway install` | Installs the launchd/systemd/Task-Scheduler service that auto-runs `praisonai gateway start` in the background with `KeepAlive=true`. |
| `praisonai gateway status` | Reports whether the daemon is loaded + running. |
| `praisonai gateway uninstall` | Removes the daemon service. |
| `praisonai onboard` | Configures messaging bots and automatically runs `praisonai gateway install` |

The daemon service literally wraps `praisonai gateway start --config ~/.praisonai/bot.yaml` to run it persistently in the background.

---

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

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

<Accordion title="Test the dashboard connection">
Expand Down
4 changes: 2 additions & 2 deletions docs/install/installer.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ flowchart TD
Runs `praisonai setup` for LLM configuration
</Step>
<Step title="Bot Onboarding">
Optional `praisonai onboard` for messaging bots (Telegram/Discord/Slack/WhatsApp)
Optional `praisonai onboard` for messaging bots — asks 4 questions to configure Telegram/Discord/Slack/WhatsApp
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Mirror the corrected onboarding wording here too.

If the onboard guide changes from “asks 4 questions” to “4-step flow,” update both installer references so users are not surprised by per-platform token or extra env prompts.

Also applies to: 155-155

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/install/installer.mdx` at line 72, Update the installer wording so it
matches the corrected onboard guide: replace the phrase "asks 4 questions" with
"4‑step flow" in the line containing "Optional `praisonai onboard` for messaging
bots — asks 4 questions to configure Telegram/Discord/Slack/WhatsApp" (and the
other occurrence noted around the same file, currently "also applies to:
155-155") so both installer references use "4-step flow" and remain consistent
with the onboarding guide.

</Step>
<Step title="Final Summary">
Shows either onboard wizard's ✅ Done panel or installer's Next Steps
Expand Down Expand Up @@ -152,7 +152,7 @@ curl -fsSL https://praison.ai/install.sh | bash -s -- --help
After successful installation and verification, the installer runs an interactive onboarding sequence:

1. **Setup wizard** (`praisonai setup`) - Configure LLM API keys
2. **Bot onboarding** (`praisonai onboard`) - Set up messaging bots (default: Yes)
2. **Bot onboarding** (`praisonai onboard`) - Asks 4 questions to set up messaging bots (default: Yes). See the [onboard guide](/docs/features/onboard) for details.
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The claim that the wizard "Asks 4 questions" is inconsistent with the current implementation in praisonai/cli/features/onboard.py. If the code hasn't been updated yet to match this new flow, this documentation will be inaccurate for users.

3. **Final summary** - Either the onboard wizard's ✅ Done panel or installer's Next Steps

**Two possible end states:**
Expand Down