docs: Comprehensive documentation restructure and improvements#599
Closed
fossler wants to merge 24 commits intosipeed:mainfrom
Closed
docs: Comprehensive documentation restructure and improvements#599fossler wants to merge 24 commits intosipeed:mainfrom
fossler wants to merge 24 commits intosipeed:mainfrom
Conversation
Add documentation for future Claude Code instances with build commands, architecture overview, and key development patterns. Generated with [Z.ai](https://z.ai/subscribe?ic=JGTYCX7ZO7) Co-Authored-By: Z.ai GLM-5
Expand the docs/ directory with 109 markdown files covering: Getting Started: - Installation guide (binary, source, Docker, Termux) - Quick start and configuration basics - First chat tutorial User Guide: - Complete CLI reference (9 command docs) - 11 channel setup guides (Telegram, Discord, Slack, etc.) - 9 LLM provider guides (OpenRouter, Zhipu, Anthropic, etc.) - 8 tool documentation files - Skills system documentation - Workspace customization guides - Advanced features (multi-agent, routing, security, etc.) Developer Guide: - Architecture and data flow - Building and testing - Contributing guidelines - Extension guides for tools, providers, channels, skills - API reference for all interfaces Deployment: - Docker and systemd guides - Termux for Android - SBC guides (Raspberry Pi, LicheeRV Nano, MaixCAM) - Production security checklist Operations: - Health endpoints and monitoring - Logging and device monitoring - Troubleshooting guide Tutorials: - Step-by-step guides for common use cases - Hardware control tutorial Community: - Project roadmap - Support channels - Contributing roles Includes SUMMARY.md for mdBook/GitBook navigation. Generated with [Z.ai](https://z.ai/subscribe?ic=JGTYCX7ZO7) Co-Authored-By: Z.ai GLM-5
Expand the docs/ directory with 109 markdown files covering: Getting Started: - Installation guide (binary, source, Docker, Termux) - Quick start and configuration basics - First chat tutorial User Guide: - Complete CLI reference (9 command docs) - 11 channel setup guides (Telegram, Discord, Slack, etc.) - 9 LLM provider guides (OpenRouter, Zhipu, Anthropic, etc.) - 8 tool documentation files - Skills system documentation - Workspace customization guides - Advanced features (multi-agent, routing, security, etc.) Developer Guide: - Architecture and data flow - Building and testing - Contributing guidelines - Extension guides for tools, providers, channels, skills - API reference for all interfaces Deployment: - Docker and systemd guides - Termux for Android - SBC guides (Raspberry Pi, LicheeRV Nano, MaixCAM) - Production security checklist Operations: - Health endpoints and monitoring - Logging and device monitoring - Troubleshooting guide Tutorials: - Step-by-step guides for common use cases - Hardware control tutorial Community: - Project roadmap - Support channels - Contributing roles Includes SUMMARY.md for mdBook/GitBook navigation. Generated with [Z.ai](https://z.ai/subscribe?ic=JGTYCX7ZO7) Co-Authored-By: Z.ai GLM-5
Add 📚 Full Documentation section with links to docs/ directory and expand 🤝 Contribute & Roadmap section with roadmap highlights, contribution tracks, and community links. Updated files: - README.md (English) - README.zh.md (Chinese) - README.pt-br.md (Portuguese-Brazil) - README.vi.md (Vietnamese) - README.ja.md (Japanese) Generated with [Z.ai](https://z.ai/subscribe?ic=JGTYCX7ZO7) Co-Authored-By: Z.ai GLM-5
Add a quick-reference table pointing to relevant documentation for specific development tasks (architecture, tools, providers, configuration, deployment, etc.) Generated with [Z.ai](https://z.ai/subscribe?ic=JGTYCX7ZO7) Co-Authored-By: Z.ai GLM-5
Resolved conflict by keeping deletion of docs/tools_configuration.md (content already integrated into new documentation structure). Generated with [Z.ai](https://z.ai/subscribe?ic=JGTYCX7ZO7) Co-Authored-By: Z.ai GLM-5
- Create docs/user-guide/ide-setup/ directory - Add IDE Setup overview (README.md) - Add comprehensive Antigravity setup guide (antigravity.md) - Update docs/README.md and docs/SUMMARY.md with new section - Remove old ANTIGRAVITY_AUTH.md and ANTIGRAVITY_USAGE.md (content incorporated into new structure) Generated with [Z.ai](https://z.ai/subscribe?ic=JGTYCX7ZO7) Co-Authored-By: Z.ai GLM-5
Add detailed technical documentation for the Antigravity provider: - OAuth 2.0 with PKCE authentication flow - API endpoints and request/response formats - Token management and refresh - Model management and usage tracking - Schema sanitization for Gemini compatibility - Thinking block handling for Claude models - Error handling patterns This restores the technical content from the deleted ANTIGRAVITY_AUTH.md in an appropriate developer guide location. Generated with [Z.ai](https://z.ai/subscribe?ic=JGTYCX7ZO7) Co-Authored-By: Z.ai GLM-5
Content already incorporated into: - docs/community/roadmap.md - docs/community/contributing-roles.md Generated with [Z.ai](https://z.ai/subscribe?ic=JGTYCX7ZO7) Co-Authored-By: Z.ai GLM-5
Replace docs/community/roadmap.md content with 1:1 copy of the authoritative ROADMAP.md from repository root. Generated with [Z.ai](https://z.ai/subscribe?ic=JGTYCX7ZO7) Co-Authored-By: Z.ai GLM-5
The roadmap is now maintained in docs/community/roadmap.md as part of the comprehensive documentation structure. Generated with [Z.ai](https://z.ai/subscribe?ic=JGTYCX7ZO7) Co-Authored-By: Z.ai GLM-5
Updated in: - README.md - README.zh.md - README.pt-br.md - README.vi.md - README.ja.md - CLAUDE.md Generated with [Z.ai](https://z.ai/subscribe?ic=JGTYCX7ZO7) Co-Authored-By: Z.ai GLM-5
Replace docs/picoclaw_community_roadmap_260216.md references with docs/community/roadmap.md in all README translations. Generated with [Z.ai](https://z.ai/subscribe?ic=JGTYCX7ZO7) Co-Authored-By: Z.ai GLM-5
Add links from vendor table "OAuth only" text to the Antigravity setup documentation in all README translations. Generated with [Z.ai](https://z.ai/subscribe?ic=JGTYCX7ZO7) Co-Authored-By: Z.ai GLM-5
- Rename docs/wecom-app-configuration.md to -cn.md (Chinese) - Create docs/wecom-app-configuration-en.md (English translation) Generated with [Z.ai](https://z.ai/subscribe?ic=JGTYCX7ZO7) Co-Authored-By: Z.ai GLM-5
- Move wecom-app-configuration-en.md → channels/wecom-app-en.md - Move wecom-app-configuration-cn.md → channels/wecom-app-cn.md - Create channels/wecom.md as overview page - Add WeCom to channels README table - Update docs/README.md and SUMMARY.md Generated with [Z.ai](https://z.ai/subscribe?ic=JGTYCX7ZO7) Co-Authored-By: Z.ai GLM-5
- Update README.fr.md with Full Documentation and Roadmap sections - Add Migration section to docs indexes (model-list-migration.md) - Add Design section to docs indexes (provider-refactoring.md) Generated with [Z.ai](https://z.ai/subscribe?ic=JGTYCX7ZO7) Co-Authored-By: Z.ai GLM-5
- Create docs/user-guide/README.md as overview page - Add Community link to all README translations: - README.md (English) - README.zh.md (Chinese) - README.pt-br.md (Portuguese) - README.vi.md (Vietnamese) - README.ja.md (Japanese) - README.fr.md (French) Generated with [Z.ai](https://z.ai/subscribe?ic=JGTYCX7ZO7) Co-Authored-By: Z.ai GLM-5
Contributor
There was a problem hiding this comment.
Pull request overview
This PR restructures and expands the project documentation into a clearer multi-section layout (Getting Started, User Guide, Developer Guide, Deployment, Operations, Tutorials, Community), consolidating older standalone docs into the new structure.
Changes:
- Added extensive new docs across tutorials, operations, deployment, and developer guides, plus updated navigation (
docs/SUMMARY.md,docs/README.md). - Consolidated / removed older docs (e.g., roadmap and Antigravity docs) into the new structure and updated README translations to point to the new locations.
- Added contributor-oriented repo guidance file (
CLAUDE.md) and expanded community/support documentation.
Reviewed changes
Copilot reviewed 60 out of 126 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/tutorials/scheduled-tasks.md | Adds a scheduled tasks tutorial (cron + heartbeat) under the new tutorials structure |
| docs/tutorials/basic-assistant.md | Adds a beginner tutorial for initial setup and first chat |
| docs/tutorials/README.md | Adds tutorials landing page and learning paths |
| docs/tools_configuration.md | Removes legacy tools configuration doc (content moved into new structure) |
| docs/picoclaw_community_roadmap_260216.md | Removes legacy community roadmap doc (moved into docs/community/roadmap.md) |
| docs/operations/troubleshooting.md | Adds a centralized troubleshooting guide in the new operations section |
| docs/operations/monitoring.md | Adds production monitoring guidance (metrics, alerts, dashboards) |
| docs/operations/logging.md | Adds log management guidance (formats, rotation, aggregation) |
| docs/operations/health-endpoints.md | Documents gateway health/readiness/liveness endpoints |
| docs/operations/device-monitoring.md | Adds USB/serial device monitoring documentation |
| docs/getting-started/quick-start.md | Adds quick start guide aligned to new docs structure |
| docs/getting-started/installation.md | Adds installation guide (binary/source/docker/termux) |
| docs/getting-started/first-chat.md | Adds first-chat guide (one-shot, interactive, sessions) |
| docs/getting-started/configuration-basics.md | Adds configuration basics overview and env var pattern |
| docs/getting-started/README.md | Adds “Getting Started” index page |
| docs/developer-guide/testing.md | Adds developer testing guide and patterns |
| docs/developer-guide/extending/creating-skills.md | Adds detailed guide for creating skills |
| docs/developer-guide/extending/README.md | Adds extending guide index |
| docs/developer-guide/data-flow.md | Documents message bus data flow with diagrams and examples |
| docs/developer-guide/contributing.md | Adds contribution guidelines (workflow, standards, templates) |
| docs/developer-guide/building.md | Adds build-from-source guide and troubleshooting |
| docs/developer-guide/architecture.md | Adds architecture overview and component documentation |
| docs/developer-guide/api/README.md | Adds API reference index for core extension points |
| docs/developer-guide/README.md | Adds developer guide landing page |
| docs/deployment/sbc/README.md | Adds SBC deployment overview and tuning guidance |
| docs/deployment/docker.md | Adds Docker deployment guide and compose examples |
| docs/deployment/README.md | Adds deployment guide index |
| docs/community/support.md | Adds “Getting Help” support guidance and templates |
| docs/community/contributing-roles.md | Adds contribution roles and volunteer opportunities |
| docs/community/README.md | Adds community landing page and links |
| docs/SUMMARY.md | Defines GitBook-compatible navigation for the new doc structure |
| docs/README.md | Adds overall docs portal page and section index |
| docs/ANTIGRAVITY_USAGE.md | Removes legacy Antigravity usage doc (content moved into new IDE setup section) |
| README.md | Updates main README to link to new docs and roadmap location |
| README.zh.md | Updates Chinese README links to new roadmap/docs structure |
| README.vi.md | Updates Vietnamese README links to new roadmap/docs structure |
| README.pt-br.md | Updates Portuguese (Brazil) README links to new roadmap/docs structure |
| README.ja.md | Updates Japanese README links to new roadmap/docs structure |
| README.fr.md | Updates French README links to new roadmap/docs structure |
| CLAUDE.md | Adds repository guidance for Claude Code usage and project conventions |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 60 out of 126 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Add Community link to Full Documentation section - Sync formatting across all translations Generated with [Z.ai](https://z.ai/subscribe?ic=JGTYCX7ZO7) Co-Authored-By: Z.ai GLM-5
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 60 out of 126 changed files in this pull request and generated 5 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Add VERSION variable for easy updates - Update download links to match release naming (picoclaw_OS_arch) - Add all supported platforms: Linux, macOS, Windows, FreeBSD - Add one-liner install script for Linux/macOS - Update all download examples to use tar.gz format Generated with [Z.ai](https://z.ai/subscribe?ic=JGTYCX7ZO7) Co-Authored-By: Z.ai GLM-5
- Add 'sudo mv picoclaw /usr/local/bin' after chmod - Change './picoclaw onboard' to 'picoclaw onboard' Generated with [Z.ai](https://z.ai/subscribe?ic=JGTYCX7ZO7) Co-Authored-By: Z.ai GLM-5
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 60 out of 126 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Fix duplicate roadmap link in README - Fix nested code blocks in issue templates (support.md, contributing.md) - Fix API key redaction regex to include hyphens/underscores - Fix incorrect /exit command to exit in basic-assistant tutorial - Update installation guide formatting Generated with [Z.ai](https://z.ai/subscribe?ic=JGTYCX7ZO7) Co-Authored-By: Z.ai GLM-5
xiaket
requested changes
Feb 22, 2026
Collaborator
xiaket
left a comment
xiaket
left a comment
There was a problem hiding this comment.
At this point in time, it is not in the interest of the community to maintain all of these extra docs. And frankly at the age of AI, these separate docs are of little value.
Collaborator
|
Also, please use the PR template instead of writing the description using an AI. Thank you. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR introduces a comprehensive documentation restructure with new sections, improved organization, and content consolidation.
Major Changes
New Documentation Structure
docs/getting-started/) - Installation, quick start, first chatdocs/user-guide/) - Complete feature documentation with READMEdocs/developer-guide/) - Architecture, extending, API referencedocs/deployment/) - Docker, systemd, SBC guidesdocs/configuration/) - Complete config referencedocs/operations/) - Monitoring, logging, troubleshootingdocs/tutorials/) - Step-by-step guidesdocs/community/) - Roadmap, contributing, supportdocs/migration/) - Configuration migration guidesdocs/design/) - Architecture design documentsIDE Setup Section
docs/user-guide/ide-setup/directoryChannel Documentation
README Updates (All Translations)
Content Consolidation
ROADMAP.mdfrom root (moved todocs/community/roadmap.md)docs/ANTIGRAVITY_AUTH.mdanddocs/ANTIGRAVITY_USAGE.md(integrated into new structure)docs/picoclaw_community_roadmap_260216.md(content integrated)docs/user-guide/README.mdas overview pageFiles Changed
docs/README.mdanddocs/SUMMARY.mdindexesTesting
Generated with Z.ai