docs(onboard): update wizard docs for leaner 4-question flow + drop home_channel (PR #1491)#213
docs(onboard): update wizard docs for leaner 4-question flow + drop home_channel (PR #1491)#213MervinPraison wants to merge 2 commits intomainfrom
Conversation
…ome_channel (PR #1491) - Replace Quick Start with real 4-question flow: platform, token, allowlist, daemon - Update phases table to reflect security setup instead of validation step - Change 'What Gets Installed' to 'What The Wizard Writes' with file contents - Add migration note about removed home_channel YAML lines - Update re-running behavior to mention fixed config path (~/.praisonai/bot.yaml) - Light touch installer.mdx updates to mention 4 questions with link to onboard guide - Reflects upstream PR #1491 changes that reduced 9 prompts to 4 prompts Fixes #212 Co-authored-by: Mervin Praison <MervinPraison@users.noreply.github.com>
📝 WalkthroughWalkthroughDocumentation updates refactoring the onboarding guide from multi-step instructions to a concise 4-question wizard format. File paths are updated from Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related issues
Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the onboarding documentation to reflect a simplified bot setup process, including a revised quick-start guide and updated configuration file details. Feedback identifies visual inconsistencies regarding missing step titles and points out factual inaccuracies where the documented question count and configuration path do not match the current CLI behavior.
| <Step title="Run the onboard wizard"> | ||
| Launch the interactive bot setup wizard: | ||
|
|
||
| <Step> |
There was a problem hiding this comment.
The title attribute has been removed from this <Step>, but it remains on the third step (line 53). For visual consistency in the Mintlify documentation, it is recommended to either include titles for all steps or remove them from all. Keeping titles usually provides better context for the user.
<Step title="Run the onboard wizard">
| 3. Slack | ||
| 4. WhatsApp | ||
| ``` | ||
| <Step> |
There was a problem hiding this comment.
This <Step> is missing a title attribute, which makes it inconsistent with the third step. Adding a descriptive title would improve the structure and readability of the Quick Start guide.
<Step title="Configure the bot">
| - Restart the daemon service with new settings | ||
| - Preserve existing chat histories and agent memory | ||
|
|
||
| The config file path is **always** `~/.praisonai/bot.yaml` (no longer prompted for). Use `praisonai doctor` to discover the path. When re-running, the overwrite prompt now says `{path} exists. Overwrite with fresh config?` with `Kept existing file` on decline. |
There was a problem hiding this comment.
This line mentions that the config file path is "no longer prompted for", but the code in praisonai/cli/features/onboard.py at line 482 still explicitly prompts the user for the Config file path. This discrepancy between the documentation and the actual CLI behavior should be resolved to avoid user confusion.
|
|
||
| 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Pull request overview
Updates the documentation to match the upstream praisonai onboard wizard changes (now a lean 4-question flow) and documents the removal/migration guidance for the deprecated home_channel config.
Changes:
- Rewrites the onboarding Quick Start to reflect the 4 prompts users actually see and updates related sections (phases, outputs, re-run behavior).
- Adds migration guidance explaining that
home_channellines in olderbot.yamlfiles are safe to delete. - Updates installer docs to mention the onboarding wizard now asks 4 questions and links to the onboard guide.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| docs/features/onboard.mdx | Aligns onboarding docs with the new 4-question wizard flow and adds migration/re-run notes. |
| docs/install/installer.mdx | Updates installer flow text to reference the 4-question onboarding and links to the onboard guide. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - Restart the daemon service with new settings | ||
| - Preserve existing chat histories and agent memory | ||
|
|
||
| The config file path is **always** `~/.praisonai/bot.yaml` (no longer prompted for). Use `praisonai doctor` to discover the path. When re-running, the overwrite prompt now says `{path} exists. Overwrite with fresh config?` with `Kept existing file` on decline. |
There was a problem hiding this comment.
The sentence "Use praisonai doctor to discover the path" looks inaccurate: current Doctor docs describe validating agents/workflow config, but don't mention showing the onboard bot.yaml location. Either link to the specific Doctor subcommand/flag that prints the path (if it exists) or drop the Doctor reference and just state the fixed path.
| The config file path is **always** `~/.praisonai/bot.yaml` (no longer prompted for). Use `praisonai doctor` to discover the path. When re-running, the overwrite prompt now says `{path} exists. Overwrite with fresh config?` with `Kept existing file` on decline. | |
| 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. |
| <Steps> | ||
| <Step title="Run the onboard wizard"> | ||
| Launch the interactive bot setup wizard: | ||
|
|
||
| <Step> | ||
| ```bash | ||
| praisonai onboard | ||
| ``` | ||
|
|
||
| The wizard prompts you to choose a platform and walks you through token setup. | ||
| </Step> | ||
|
|
||
| <Step title="Pick your platform"> | ||
| Select from the supported messaging platforms: | ||
|
|
||
| ``` | ||
| Choose a platform: | ||
| 1. Telegram | ||
| 2. Discord | ||
| 3. Slack | ||
| 4. WhatsApp | ||
| ``` | ||
| <Step> | ||
| The wizard asks exactly 4 questions — everything else uses sensible defaults: |
There was a problem hiding this comment.
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.
| @@ -97,23 +82,25 @@ The onboarding process follows these phases: | |||
| |-------|-------------| | |||
| | **Platform Selection** | Choose Telegram, Discord, Slack, or WhatsApp | | |||
| | **Token Entry** | Paste the bot token for your chosen platform | | |||
There was a problem hiding this comment.
The phases table no longer mentions token validation, but the Quick Start section says the token is validated against the platform API. Consider adding a dedicated "Validation" phase back, or update the "Token Entry" description to explicitly include validation so the table stays accurate.
| | **Token Entry** | Paste the bot token for your chosen platform | | |
| | **Token Entry** | Paste the bot token for your chosen platform and validate it against the platform API | |
|
|
||
| The wizard validates the token and installs the daemon service. | ||
| <Step title="You're done"> | ||
| The wizard writes `~/.praisonai/bot.yaml`, persists tokens to `~/.praisonai/.env` (chmod 600), and shows the ✅ Done panel with your dashboard URL. |
There was a problem hiding this comment.
This page now says onboarding persists tokens to ~/.praisonai/.env, but later in the same doc ("Keep tokens secure") it still claims tokens are stored in ~/.praisonai/config/. Please reconcile these so the doc has a single, correct source of truth about where secrets live.
| The wizard writes `~/.praisonai/bot.yaml`, persists tokens to `~/.praisonai/.env` (chmod 600), and shows the ✅ Done panel with your dashboard URL. | |
| 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. |
| 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. | ||
|
|
||
| <Note> | ||
| **Upgrading?** Older `bot.yaml` files may contain a `home_channel: ${TELEGRAM_HOME_CHANNEL}` line (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. |
There was a problem hiding this comment.
Migration note: the example home_channel: ${TELEGRAM_HOME_CHANNEL} is very specific; if older generated files used a different env-var interpolation format, users may not recognize it. Consider wording this as "remove the home_channel key" (and optionally mention the env var) rather than relying on an exact string match.
| **Upgrading?** Older `bot.yaml` files may contain a `home_channel: ${TELEGRAM_HOME_CHANNEL}` line (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. | |
| **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. |
|
@claude resolve conflicts This branch has conflicts that must be resolved docs/features/onboard.mdx |
|
Claude finished @MervinPraison's task —— View job Merge conflicts resolved! ✅I've successfully resolved all merge conflicts in
Changes Made:
The branch is now up to date and all conflicts are resolved. The PR should be ready for review again. |
- Resolve merge conflicts by choosing the new 4-question flow content - Add missing step titles for consistency in Quick Start section - Fix token storage location references to consistently use ~/.praisonai/.env - Update migration note wording to be more generic as suggested in reviews - Combine validation into Token Entry phase description for clarity Fixes #212 Co-authored-by: Mervin Praison <MervinPraison@users.noreply.github.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/features/onboard.mdx`:
- 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.
- Around line 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.
- Around line 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.
- Around line 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.
In `@docs/install/installer.mdx`:
- 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.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: d71be323-10dc-40ea-8d4d-5c8055aac4a8
📒 Files selected for processing (2)
docs/features/onboard.mdxdocs/install/installer.mdx
| <Step title="Answer 4 questions"> | ||
| The wizard asks exactly 4 questions — everything else uses sensible defaults: | ||
|
|
||
| ``` | ||
| 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. |
There was a problem hiding this comment.
🧩 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.pyRepository: 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.
| ## 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. |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
🧩 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.pyRepository: 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:
- Update the generator to omit
home_channelon regeneration (if truly deprecated), or - Soften the migration note to clarify that
home_channelwill 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.
| ## 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. |
There was a problem hiding this comment.
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.
| </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 |
There was a problem hiding this comment.
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.
Summary
Changes Made
Test Plan
Fixes #212
🤖 Generated with Claude Code
Summary by CodeRabbit