Grayscale/nanobot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: make onboarding friendlier for beginners (#4177)

Browse Source 
* docs: make onboarding friendlier for beginners

* docs: build clearer documentation paths

Maintainer edit: turn the onboarding follow-up into a layered docs structure for first-time setup, provider selection, troubleshooting, CLI reference, and source-level architecture. This keeps quick start focused while giving advanced users precise reference paths.

* docs: render architecture flow with mermaid

Maintainer edit: replace the ASCII architecture sketch with a GitHub-rendered Mermaid flowchart so the core runtime path is easier to scan in the PR and README docs.

* docs: recommend model presets for model config

Maintainer edit: make named modelPresets the primary model configuration path and expand fallback preset examples so string fallbacks are clearly preset names, not raw model IDs.

* docs: document api base urls and langfuse setup

Maintainer edit: explain when users need apiBase/base URL in quick start and provider docs, and add Langfuse tracing setup with troubleshooting links.

* docs: use python module pip consistently

Maintainer edit: keep install commands tied to the active Python interpreter by using python -m pip in the Azure optional dependency notes too.

* docs: add non-technical getting started path

Maintainer edit: add a wizard-first guide for users without terminal or JSON background, including a text TUI menu example and links from the main docs entrypoints.

* docs: avoid hard-wrapped prose in user docs

Maintainer edit: unwrap ordinary prose across user-facing documentation while preserving markdown structure, code blocks, tables, lists, and prompt/template files.

* docs: keep desktop list continuations nested

Maintainer edit: preserve list nesting after unwrapping prose in the desktop WebUI sync guide.

* docs: add one-command installer

Maintainer edit: add auditable macOS/Linux and Windows install scripts that install nanobot-ai and start the onboarding wizard, then document the commands in the main onboarding entrypoints.

* docs: add installer dry run mode

Maintainer edit: add --dry-run to the one-command installer scripts so users can preview Python detection, install source, pip command, and wizard behavior without changing their environment.

* docs: clean installer error output

Maintainer edit: make PowerShell installer failures print a concise Error: message instead of Write-Error call-site details.

* docs: add provider setup cookbook

Maintainer edit: add pasteable provider recipes for common hosted, local, fallback, runtime switching, and Langfuse setups, then link the cookbook from onboarding and troubleshooting entrypoints.

* docs: address review feedback

* docs: clarify reader paths

* docs: explain terminal basics for beginners

* docs: clarify wizard navigation

* docs: avoid duplicate onboarding steps

* docs: add setup status check

* docs: explain status output

* docs: remove provider recommendation wording

* docs: explain status diagnostics

* docs: reduce hard-wrapped guidance

* docs: migrate config examples to presets

* docs: clarify python command fallbacks

* docs: improve installer failure recovery

* docs: expand install troubleshooting

* docs: cover installer download failures

* docs: put stable install paths first

* docs: add bundled webui quick path

* docs: clarify provider-neutral setup

* docs: clarify gateway setup for chat surfaces

* docs: improve docs navigation paths

* docs: add configuration quick jump

* docs: clarify provider secret variables

* chore: request PR review acknowledgement

Empty commit: please read the PR review comments and reply on the PR to confirm that you have received them.

This commit intentionally changes no files; it exists only to notify the remote Codex run so it can end its active goal.

* docs: add README start here guide

* docs: avoid provider recommendation wording

* docs: guide next steps after first reply

* docs: explain merging JSON snippets

* docs: add CLI command chooser

* docs: add configuration task map

* docs: add deployment readiness guide

* docs: simplify WebUI entry paths

* docs: add provider recipe chooser

* docs: fix provider factual references

Update OpenRouter and LongCat model examples, align Bedrock guidance, and make fallback snippets schema-valid.

Also correct group policy wording and image-generation provider lists to match the current code.

* fix: keep PowerShell installer from closing caller shell

* docs: mention self-guided configuration
This commit is contained in:
chengyongru
2026-06-10 00:36:22 +08:00
committed by GitHub
parent 56ce18167e
commit 4a58b83acc
31 changed files with 3491 additions and 454 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/development.md
+8 -19
View File
@@ -1,13 +1,10 @@
# Development
This page collects contributor-facing notes for extending nanobot. User-facing setup
and runtime options live in [`configuration.md`](./configuration.md).
This page collects contributor-facing notes for extending nanobot. User-facing setup and runtime options live in [`configuration.md`](./configuration.md).
## Adding an LLM Provider
nanobot uses the provider registry in `nanobot/providers/registry.py` as the
source of truth for LLM provider metadata. Most OpenAI-compatible providers need
only two changes.
nanobot uses the provider registry in `nanobot/providers/registry.py` as the source of truth for LLM provider metadata. Most OpenAI-compatible providers need only two changes.
1. Add a `ProviderSpec` entry to `PROVIDERS`:
@@ -29,8 +26,7 @@ class ProvidersConfig(BaseModel):
myprovider: ProviderConfig = Field(default_factory=ProviderConfig)
```
Environment variables, config matching, provider status, and WebUI credential
display derive from those two entries.
Environment variables, config matching, provider status, and WebUI credential display derive from those two entries.
Useful `ProviderSpec` options:
@@ -50,12 +46,10 @@ Useful `ProviderSpec` options:
Transcription is intentionally split into two layers:
- `nanobot/audio/transcription_registry.py` owns provider names, aliases, default
models, and adapter loading.
- `nanobot/audio/transcription_registry.py` owns provider names, aliases, default models, and adapter loading.
- `nanobot/providers/transcription.py` owns provider-specific HTTP behavior.
Credentials still live under `providers.<provider>` so chat channels, WebUI, and
desktop resolve API keys and API bases the same way.
Credentials still live under `providers.<provider>` so chat channels, WebUI, and desktop resolve API keys and API bases the same way.
1. Add provider credentials to `ProvidersConfig`.
@@ -67,8 +61,7 @@ class ProvidersConfig(BaseModel):
2. Add a `ProviderSpec` in `nanobot/providers/registry.py`.
For transcription-only providers, set `is_transcription_only=True` so they show up
in credential/settings surfaces but stay out of chat model selection.
For transcription-only providers, set `is_transcription_only=True` so they show up in credential/settings surfaces but stay out of chat model selection.
```python
ProviderSpec(
@@ -83,9 +76,7 @@ ProviderSpec(
3. Add an adapter class in `nanobot/providers/transcription.py`.
Adapters receive resolved credentials and settings. They return an empty string
for provider errors so channel voice messages fail quietly instead of crashing the
agent loop.
Adapters receive resolved credentials and settings. They return an empty string for provider errors so channel voice messages fail quietly instead of crashing the agent loop.
```python
class MySTTTranscriptionProvider:
@@ -127,6 +118,4 @@ At minimum, cover:
6. Update user-facing docs.
Add the provider to [`configuration.md`](./configuration.md) where users choose
`transcription.provider`, but keep implementation details in this development
guide.
Add the provider to [`configuration.md`](./configuration.md) where users choose `transcription.provider`, but keep implementation details in this development guide.