Docs consolidation #257
Docs consolidation #257
Conversation
- Updated the interactive setup wizard instructions to recommend using the convenience script `./wizard.sh` for easier configuration. - Added detailed instructions for uploading and processing existing audio files via the API, including example commands for single and multiple file uploads. - Introduced a new section on HAVPE relay configuration for ESP32 audio streaming, providing environment variable setup and command examples. - Clarified the distributed deployment setup, including GPU and backend separation instructions, and added benefits of using Tailscale for networking. - Removed outdated `getting-started.md` and `SETUP_SCRIPTS.md` files to streamline documentation and avoid redundancy.
- Replaced direct command instructions with convenience scripts (`./wizard.sh` and `./start.sh`) for easier setup and service management. - Added detailed usage of convenience scripts for checking service status, restarting, and stopping services. - Clarified the distinction between convenience scripts and direct command usage for improved user guidance.
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the 📝 WalkthroughWalkthroughThis PR consolidates and reorganizes documentation across the project to promote convenience wrapper scripts (wizard.sh, start.sh, restart.sh, stop.sh, status.sh) for common operations. Multiple documentation files were updated to reference these scripts, and several duplicate quickstart guides were removed in favor of centralized documentation. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In @CLAUDE.md:
- Around line 29-36: The markdown shows bare shell commands (`./wizard.sh` and
`uv run --with-requirements setup-requirements.txt python wizard.py`) which
trigger MD034; wrap these paths in inline code or place the whole snippet in a
fenced code block (e.g., mark with ```bash) so the commands are rendered as code
and not treated as bare URLs; update the section around the "Run the interactive
setup wizard..." header to use inline backticks for each command or convert the
two lines into a single fenced bash block to satisfy the linter.
- Around line 502-507: The second line of the "Benefits of Distributed Setup:"
bullet list contains a run-on where "no CORS configuration needed Encrypted
inter-service communication" is merged; split or punctuate these as two separate
bullets (keep "Automatic Tailscale IP support (100.x.x.x) - no CORS
configuration needed" as one bullet and "Encrypted inter-service communication"
as its own bullet) or insert proper punctuation/conjunction between them so the
verb agreement and sentence boundaries are correct.
In @config/README.md:
- Around line 108-109: The README contains an incorrect absolute path and
inconsistent path styles: replace `/Docs/memory-configuration-guide.md` with the
correct repository path `backends/advanced/Docs/memory-configuration-guide.md`
and change the absolute links `/quickstart.md` and `/CLAUDE.md` (as shown in the
diff) to relative paths (e.g., `../quickstart.md`, `../CLAUDE.md`) or otherwise
normalize all links in config/README.md to use consistent relative paths so they
correctly resolve from this subdirectory.
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (10)
CLAUDE.mdDocs/features.mdDocs/getting-started.mdDocs/init-system.mdDocs/ports-and-access.mdREADME.mdbackends/advanced/Docs/quickstart.mdbackends/advanced/SETUP_SCRIPTS.mdconfig/README.mdquickstart.md
💤 Files with no reviewable changes (3)
- Docs/getting-started.md
- backends/advanced/SETUP_SCRIPTS.md
- backends/advanced/Docs/quickstart.md
🧰 Additional context used
📓 Path-based instructions (1)
**/*.{py,sh,md}
📄 CodeRabbit inference engine (CLAUDE.md)
Use
uv run python3instead ofpython3for running Python commands, as uv is the package manager for all Python projects.
Files:
README.mdconfig/README.mdDocs/ports-and-access.mdDocs/features.mdCLAUDE.mdquickstart.mdDocs/init-system.md
🧠 Learnings (3)
📚 Learning: 2026-01-06T08:43:14.315Z
Learnt from: CR
Repo: SimpleOpenSoftware/chronicle PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-06T08:43:14.315Z
Learning: Applies to **/*.{py,sh,md} : Use `uv run python3` instead of `python3` for running Python commands, as uv is the package manager for all Python projects.
Applied to files:
config/README.mdDocs/ports-and-access.mdquickstart.mdDocs/init-system.md
📚 Learning: 2026-01-06T08:43:14.315Z
Learnt from: CR
Repo: SimpleOpenSoftware/chronicle PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-06T08:43:14.315Z
Learning: Check backends/advanced/Docs for up to date information on advanced backend configuration and architecture.
Applied to files:
config/README.md
📚 Learning: 2026-01-06T08:43:14.315Z
Learnt from: CR
Repo: SimpleOpenSoftware/chronicle PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-06T08:43:14.315Z
Learning: Applies to **/*.py : Use job-based tracking system for all audio processing (WebSocket and file uploads) with stage events (audio → transcription → memory) and completion status.
Applied to files:
CLAUDE.md
🪛 LanguageTool
CLAUDE.md
[style] ~506-~506: The double modal “needed Encrypted” is nonstandard (only accepted in certain dialects). Consider “to be Encrypted”.
Context: ...x.x.x) - no CORS configuration needed - Encrypted inter-service communication **Service ...
(NEEDS_FIXED)
🪛 markdownlint-cli2 (0.18.1)
CLAUDE.md
30-30: Bare URL used
(MD034, no-bare-urls)
31-31: Bare URL used
(MD034, no-bare-urls)
🔇 Additional comments (16)
Docs/features.md (1)
174-175: Wrapper script references look good.The changes consistently promote
./wizard.shand./start.shacross both beginner and production use sections. This simplifies the documentation while maintaining clear guidance.Also applies to: 218-219
config/README.md (1)
23-26: Clear presentation of wrapper script with direct command fallback.The setup instructions properly show both the wrapper script (recommended) and the underlying
uv runcommand, allowing users to understand what they're running while defaulting to simplicity.README.md (2)
37-92: Project structure documentation is clear and comprehensive.The ASCII diagram accurately represents the repository layout with good annotations for key components. The reference to
*.shwrapper scripts on line 60 aligns well with the documentation consolidation theme.
94-155: Quick Command Reference well-structured with good UX patterns.The presentation of convenience scripts as the primary interface with expandable details showing underlying
uv runcommands is an excellent UX pattern. Users see the simple path first while still having access to full transparency. The explanation about what scripts wrap is particularly helpful. All referenced convenience scripts and Python modules exist and are properly configured.Docs/init-system.md (4)
40-46: Clear introduction of convenience script pattern.The section effectively establishes the wrapper script approach while preserving access to direct commands for advanced users. This pattern is well-executed across the file.
142-158: Excellent organization of convenience scripts section.The scripts are presented with clear purpose statements, and the explanatory note at line 158 effectively sets user expectations about what the wrappers do.
160-188: Full command documentation is comprehensive and well-structured.The collapsible section properly exposes the underlying commands with helpful variations (--all flag, service selection, --build option), giving power users the flexibility they need while keeping the convenience scripts prominent.
190-193: Clear guidance on when to use different service management approaches.The distinction between
restart(for .env changes) andstop+start(for code rebuilds) is accurate and helpful. Using convenience scripts in the guidance is consistent with the file's theme.Docs/ports-and-access.md (3)
10-14: Well-simplified quick-start flow using convenience scripts only.For a user journey document, showing only the wrapper scripts is the right choice. This keeps the critical path clear without overwhelming new users with alternatives.
94-109: Consistent and clear presentation of convenience scripts.The section mirrors the equivalent in init-system.md with identical descriptions and placement logic. The explanatory note properly sets expectations.
111-134: Comprehensive full command reference with proper service selection examples.The collapsible section provides the detailed commands equivalent to the convenience scripts while correctly showing service selection variations only where appropriate (e.g., --build only in start, not restart).
quickstart.md (4)
148-157: Excellent convenience script introduction with comprehensive wrapper explanation.Line 157's note is particularly valuable in a quickstart context—it explains not just the scripts but also what they wrap, helping users understand the documentation structure and locate full commands if needed.
201-208: Consistent convenience script pattern in service startup.The "Option 1" / "Option 2" structure effectively emphasizes the recommended path while respecting power users who need the direct command.
295-305: Excellent integration of convenience scripts into troubleshooting guidance.The pattern of showing convenience scripts first with full commands available in a separate subsection is particularly effective for troubleshooting—users can try the quick fix immediately, then access full details if needed.
150-157: Exceptional consistency across all three documentation files.Comparing command formats, script names, and descriptions across init-system.md, ports-and-access.md, and quickstart.md shows excellent coordination. All three files consistently present:
- Identical convenience script names and descriptions
- Identical command formats and flags
- Same pattern: convenience scripts prominently, full commands in accessible reference sections
- Appropriate adaptation of detail level per document type (quickstart is simplified, init-system is comprehensive, ports-and-access is focused)
This consistency makes the documentation easier to maintain and trust.
Also applies to: 148-208, 295-305
CLAUDE.md (1)
385-431: Well-structured documentation for audio file upload API.The new "Add Existing Data" section clearly explains the file upload workflow with practical curl examples for both single and batch file processing. The JSON response example is informative and matches the data structure well.
| # Run the interactive setup wizard from project root (recommended) | ||
| ./wizard.sh | ||
|
|
||
| # Or use the quickstart guide for step-by-step instructions | ||
| # See quickstart.md for detailed walkthrough | ||
| # Or use direct command: | ||
| uv run --with-requirements setup-requirements.txt python wizard.py | ||
|
|
||
| # For step-by-step instructions, see quickstart.md | ||
| ``` |
There was a problem hiding this comment.
Format shell script paths consistently to avoid bare URL linting warnings.
Lines 30-31 trigger MD034 (no-bare-urls) because ./wizard.sh appears without markdown formatting. Consider using inline code formatting to fix this.
🔧 Proposed fix for markdown formatting
### Quick Start
-```bash
+```bash
-# Run the interactive setup wizard from project root (recommended)
-./wizard.sh
+# Run the interactive setup wizard from project root (recommended)
+./wizard.shOr use inline code formatting:
-# Run the interactive setup wizard from project root (recommended)
-./wizard.sh
+# Run the interactive setup wizard from project root (recommended)
+`./wizard.sh`📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| # Run the interactive setup wizard from project root (recommended) | |
| ./wizard.sh | |
| # Or use the quickstart guide for step-by-step instructions | |
| # See quickstart.md for detailed walkthrough | |
| # Or use direct command: | |
| uv run --with-requirements setup-requirements.txt python wizard.py | |
| # For step-by-step instructions, see quickstart.md | |
| ``` | |
| # Run the interactive setup wizard from project root (recommended) | |
| `./wizard.sh` | |
| # Or use direct command: | |
| uv run --with-requirements setup-requirements.txt python wizard.py | |
| # For step-by-step instructions, see quickstart.md |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
30-30: Bare URL used
(MD034, no-bare-urls)
31-31: Bare URL used
(MD034, no-bare-urls)
🤖 Prompt for AI Agents
In @CLAUDE.md around lines 29 - 36, The markdown shows bare shell commands
(`./wizard.sh` and `uv run --with-requirements setup-requirements.txt python
wizard.py`) which trigger MD034; wrap these paths in inline code or place the
whole snippet in a fenced code block (e.g., mark with ```bash) so the commands
are rendered as code and not treated as bare URLs; update the section around the
"Run the interactive setup wizard..." header to use inline backticks for each
command or convert the two lines into a single fenced bash block to satisfy the
linter.
| **Benefits of Distributed Setup:** | ||
| - GPU services on dedicated hardware | ||
| - Lightweight backend on VPS/Raspberry Pi | ||
| - Automatic Tailscale IP support (100.x.x.x) - no CORS configuration needed | ||
| - Encrypted inter-service communication | ||
|
|
There was a problem hiding this comment.
Fix grammar in benefits list.
Line 506 contains a grammar issue: "needed Encrypted" is nonstandard. The phrase should use proper verb agreement or restructuring.
✏️ Proposed fix for grammar
-**Benefits of Distributed Setup:**
-- GPU services on dedicated hardware
-- Lightweight backend on VPS/Raspberry Pi
-- Automatic Tailscale IP support (100.x.x.x) - no CORS configuration needed - Encrypted inter-service communication
-- Encrypted inter-service communication
+**Benefits of Distributed Setup:**
+- GPU services on dedicated hardware
+- Lightweight backend on VPS/Raspberry Pi
+- Automatic Tailscale IP support (100.x.x.x) - no CORS configuration needed
+- Encrypted inter-service communication🧰 Tools
🪛 LanguageTool
[style] ~506-~506: The double modal “needed Encrypted” is nonstandard (only accepted in certain dialects). Consider “to be Encrypted”.
Context: ...x.x.x) - no CORS configuration needed - Encrypted inter-service communication **Service ...
(NEEDS_FIXED)
🤖 Prompt for AI Agents
In @CLAUDE.md around lines 502 - 507, The second line of the "Benefits of
Distributed Setup:" bullet list contains a run-on where "no CORS configuration
needed Encrypted inter-service communication" is merged; split or punctuate
these as two separate bullets (keep "Automatic Tailscale IP support (100.x.x.x)
- no CORS configuration needed" as one bullet and "Encrypted inter-service
communication" as its own bullet) or insert proper punctuation/conjunction
between them so the verb agreement and sentence boundaries are correct.
| - `/quickstart.md` - Setup guide | ||
| - `/CLAUDE.md` - Project overview and technical reference |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check if files exist at repository root
echo "Checking for documentation files at repository root..."
fd -H '(quickstart\.md|CLAUDE\.md)$' --max-depth 1
# List all markdown files in repository root to see available docs
echo -e "\nAvailable markdown files in repository root:"
fd -H '\.md$' --max-depth 1 --type f
# Also check the full repository structure to understand context
echo -e "\nRepository structure (top-level):"
ls -laRepository: SimpleOpenSoftware/chronicle
Length of output: 2663
🏁 Script executed:
#!/bin/bash
# Read the config/README.md file to see the context around lines 108-109
cat -n config/README.md | head -120 | tail -25Repository: SimpleOpenSoftware/chronicle
Length of output: 1021
🏁 Script executed:
#!/bin/bash
# Verify if the Docs/memory-configuration-guide.md exists
echo "Checking for memory-configuration-guide.md..."
fd -H 'memory-configuration-guide\.md'
echo -e "\nFiles in Docs directory:"
ls -la Docs/Repository: SimpleOpenSoftware/chronicle
Length of output: 507
Fix broken documentation link and consider path consistency.
The path /Docs/memory-configuration-guide.md on line 107 is incorrect—the file is actually located at backends/advanced/Docs/memory-configuration-guide.md. Additionally, since config/README.md is in a subdirectory, consider using relative paths (e.g., ../quickstart.md, ../CLAUDE.md) for better portability, or update all paths to correctly reflect the repository structure.
🤖 Prompt for AI Agents
In @config/README.md around lines 108 - 109, The README contains an incorrect
absolute path and inconsistent path styles: replace
`/Docs/memory-configuration-guide.md` with the correct repository path
`backends/advanced/Docs/memory-configuration-guide.md` and change the absolute
links `/quickstart.md` and `/CLAUDE.md` (as shown in the diff) to relative paths
(e.g., `../quickstart.md`, `../CLAUDE.md`) or otherwise normalize all links in
config/README.md to use consistent relative paths so they correctly resolve from
this subdirectory.
- Changed the speaker diarization model from `pyannote/speaker-diarization-3.1` to `pyannote/speaker-diarization-community-1` across multiple files for consistency. - Updated README files to reflect the new model and its usage instructions, ensuring users have the correct links and information for setup. - Enhanced clarity in configuration settings related to speaker recognition.
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.