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

[MervinPraison]

Context

Upstream PR MervinPraison/PraisonAI#1491 — "fix(onboard): drop unused home_channel + trim confusing prompts (4 fewer questions)" — has been merged to main (head SHA f5230ef).

The PR simplifies the praisonai onboard wizard in response to real user feedback:

"I didn't understand TELEGRAM_HOME_CHANNEL"
"don't you think we are asking too many questions?"

The wizard has gone from 9 prompts → 4 prompts, a dead YAML key has been removed from generated bot.yaml files, and a real bug (typing n at the "Config file path" prompt created a literal file named n in cwd) has been fixed.

This issue tracks the documentation work required in MervinPraison/PraisonAIDocs to reflect these user-facing changes. A follow-up agent should pick up this issue and land the doc updates.

---

What changed in the SDK (ground truth)

Source file: praisonai/cli/features/onboard.py (in praisonai-package/src/praisonai/).

1. Prompts removed from the wizard

#	Prompt (removed)	Why it was removed
4	Home channel / user ID for proactive messages (TELEGRAM_HOME_CHANNEL) (all 4 platforms)	No code path in the gateway consumed it. DeliveryTarget.channel_id is set per-job by the scheduler; home_channel was dead config that confused non-developer users.
5	Agent name	95% of users pressed Enter. Default (assistant) is already applied in __init__. Power users edit bot.yaml directly.
6	Agent instructions	Same pattern — default "You are a helpful AI assistant." already applied.
7	Config file path	Now always writes to the canonical ~/.praisonai/bot.yaml. Fixes the bug where typing n (meaning "no") created a literal file named n in the current working directory. Overwrite-confirm still guards existing files.

2. Prompts that remain (the "4 real questions")

1. Platform(s) — Telegram / Discord / Slack / WhatsApp
2. Token — bot token (hidden input, validated)
3. Allowed user IDs — security allowlist (per-platform)
4. Install as background service? — launchd / systemd / Windows Task

3. Dead YAML emit removed from _generate_bot_yaml

The home_channel: ${{TELEGRAM_HOME_CHANNEL}} (and sibling) lines are no longer written into generated bot.yaml files.

4. PLATFORMS dict fields

The home_channel_env key was removed from every platform entry in the PLATFORMS dict:

• TELEGRAM_HOME_CHANNEL — no longer declared
• DISCORD_HOME_CHANNEL — no longer declared
• SLACK_HOME_CHANNEL — no longer declared
• WHATSAPP_HOME_CHANNEL — no longer declared

A regression test (test_onboard_security.py) now asserts the absence of home_channel_env so a future copy-paste can't silently re-introduce dead config.

5. _save_env_vars comment updated

Docstring now says None values remove keys "e.g. dropping an allowlist" (the previous reference to home-channel has been dropped).

6. UX polish on Step 5

The "Written to ~/.praisonai/bot.yaml" line now formats the path in cyan, and the overwrite prompt now reads:

{path} exists. Overwrite with fresh config?

(previously just Overwrite?) with a clearer skip message: Kept existing file (was: Skipped).

---

Documentation impact — grep results

A full grep of docs/ was performed for home_channel, HOME_CHANNEL, Config file path, Agent name, Agent instructions, and the TELEGRAM/DISCORD/SLACK/WHATSAPP env-var names.

Good news: No current docs page enumerates the removed prompts or mentions home_channel by name. So the blast radius is small — no broken code blocks to chase down.

What does need updating:

Primary: docs/features/onboard.mdx (update — not rewrite)

This is the canonical onboarding page. Today it describes the wizard in 3 abstract steps (platform → token → daemon) and does not show the real prompt list. With the new leaner flow, we can be explicit and honest about exactly what users will see. Recommended edits:

• Replace the Quick Start <Steps> block so it reflects the real 4-question flow: Platform, Token, Allowed user IDs, Install as background service. Show actual terminal output snippets, not abstract placeholders.
• Add a new ## What The Wizard Asks section (or extend "How It Works") with a table of the 4 prompts, what each one sets, and what the generated bot.yaml contains.
• Add an <Info> callout: "Agent name and instructions use sensible defaults (assistant / "You are a helpful AI assistant."). Edit ~/.praisonai/bot.yaml after onboarding to customise them — the full schema is in the generated file."
• Mention that the config file path is always ~/.praisonai/bot.yaml (no longer prompted for). Link to praisonai doctor for discovering the path.
• Under "Re-running Onboarding", update the existing-file behaviour: the new overwrite prompt now says {path} exists. Overwrite with fresh config? with Kept existing file on decline.
• Migration note (<Warning> or <Note> block): "Upgrading from an older install? Your existing bot.yaml may contain a home_channel: ${TELEGRAM_HOME_CHANNEL} line — this was never consumed by the gateway and is safe to delete. Re-running praisonai onboard and accepting the overwrite will generate a clean file."
• Drop any wording that implies the wizard is verbose / has many steps — lean into "4 real questions, ~60 seconds" since that's now the actual UX and aligns with the page's 60-second subtitle.

Secondary: docs/install/installer.mdx (light touch)

• In the "Post-Install Flow" section (around the "Step: Bot Onboarding" cell), add a one-liner that onboarding asks 4 questions. No need to enumerate them — link to the onboard page.
• No changes needed to the --no-onboard / PRAISONAI_NO_ONBOARD docs.

No change required

These pages were checked and do not reference the removed prompts or home_channel:

• docs/install/quickstart.mdx (only has the generic "Set up a messaging bot" prompt line, unchanged)
• docs/best-practices/bot-security.mdx (uses a conceptual allowlist: YAML; no home_channel mention)
• docs/features/messaging-bots.mdx, docs/features/gateway.mdx, docs/features/bot-gateway.mdx, docs/features/bot-routing.mdx — describe allowed_users / BotConfig, not the onboard wizard
• docs/tools/external/{telegram,discord,slack}.mdx — platform tool docs, unrelated to home_channel
• docs/concepts/bot-os.mdx, docs/concepts/bot-vs-gateway.mdx — architecture concepts, no prompt references
• docs/cli/bot.mdx — bot start command, unaffected

⚠️ Do not edit docs/concepts/ — per AGENTS.md §1.8 that folder is HUMAN ONLY. All updates for this issue belong in docs/features/onboard.mdx and docs/install/installer.mdx.

---

Suggested rewrite — primary page outline

Here's a concrete outline the follow-up agent can use for docs/features/onboard.mdx. Keep the existing hero Mermaid diagram and overall structure (it already follows AGENTS.md §2), and replace / augment the sections below:

Replace Quick Start <Steps> with the real 4-question flow

## Quick Start

<Steps>
<Step title="Run the wizard">
\`\`\`bash
praisonai onboard
\`\`\`
</Step>

<Step title="Answer 4 questions">
The wizard asks exactly 4 questions — everything else uses sensible defaults:

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 a background service?** — `Y` on desktop, auto-skipped on CI/headless.
</Step>

<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.
</Step>
</Steps>

Add a "What the wizard writes" section

## What The Wizard Writes

| 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) |

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.

Add the migration note

<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.
</Note>

---

Reference: the full PR diff (for the agent that picks this up)

• PR: fix(onboard): drop unused home_channel + trim confusing prompts (4 fewer questions) PraisonAI#1491
• Branch: fix/onboard-lean-prompts → main
• Head SHA: f5230ef062991b309c3ce794783055abcff97df4
• Files changed: src/praisonai/praisonai/cli/features/onboard.py (+41 / -63), src/praisonai/tests/unit/cli/test_onboard_security.py (+16 / -7)
• Total: 2 files changed, 57 insertions(+), 70 deletions(-)

The synced mirror at praisonaidocs/praisonai/cli/features/onboard.py (refreshed daily by update_repos.sh) will pick up the new code automatically — verify against that file before writing the docs (per AGENTS.md §1.2 SDK-first cycle).

---

Acceptance criteria

• docs/features/onboard.mdx shows the real 4-question flow and no longer implies there are extra prompts for agent name / instructions / config path.
• A migration note calls out the dropped home_channel YAML line so upgrading users aren't confused.
• docs/install/installer.mdx Post-Install Flow section mentions "4 questions" (one-liner + link).
• No file under docs/concepts/ is touched (per AGENTS.md §1.8).
• docs.json is untouched — this is a content edit, not a new page.
• All code blocks copy-paste run (verify tokens / commands).
• Mintlify components (<Steps>, <Note>, <AccordionGroup>, <CardGroup>) used per AGENTS.md §4.
• Draft PR opened against main for review.

[MervinPraison]

Claude finished @MervinPraison's task —— View job • claude/issue-212-20260421-1600 • [Create PR ➔](https://github.com/MervinPraison/PraisonAIDocs/compare/main...claude/issue-212-20260421-1600?quick_pull=1&title=Issue%20%23212%3A%20Changes%20from%20Claude&body=This%20PR%20addresses%20issue%20%23212%0A%0AGenerated%20with%20%5BClaude%20Code%5D(https%3A%2F%2Fclaude.ai%2Fcode)

---

Documentation Update Complete ✅

I've successfully updated the onboard wizard documentation to reflect the new leaner 4-question flow from upstream PR #1491.

Changes Made

docs/features/onboard.mdx:

• ✅ Replaced Quick Start with the real 4-question flow (platform, token, allowlist, daemon)
• ✅ Updated "What Gets Installed" to "What The Wizard Writes" with file contents table
• ✅ Added migration note about removed home_channel YAML lines
• ✅ Updated re-running behavior to mention fixed config path (~/.praisonai/bot.yaml)
• ✅ Changed phases table to show security setup instead of validation

docs/install/installer.mdx:

• ✅ Added "asks 4 questions" reference to bot onboarding step
• ✅ Added link to onboard guide in Post-Install Flow section

Key Updates

• Documentation now shows the actual wizard experience (4 questions instead of 9)
• Users upgrading from older versions get clear migration guidance
• Agent name and instructions now use documented defaults (assistant / "You are a helpful AI assistant.")
• Config file path is always ~/.praisonai/bot.yaml (no longer prompted)
• Follows all AGENTS.md guidelines for user-friendly, non-developer documentation

Pull Request Created

Pull Request #213 - Ready for review

All requirements from the issue have been implemented following the detailed specifications provided.