LCORE-2933: User doc#2158
Conversation
|
Warning Review limit reached
Next review available in: 44 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: ⛔ Files ignored due to path filters (2)
📒 Files selected for processing (14)
WalkthroughAdds a new User docs navigation structure and comprehensive guides for deployment, A2A integration, configuration schemas, RAG/BYOK, Agent Skills, authentication, and user data collection. ChangesUser documentation
Estimated code review effort: 4 (Complex) | ~60 minutes Possibly related PRs
✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 21
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/README.md (1)
98-100: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winRemove or populate the empty
RAG and BYOKnavigation section.
docs/README.md#L98-L100: remove the empty heading or add the intended RAG/BYOK links.docs/index.md#L105-L107: apply the same navigation correction.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/README.md` around lines 98 - 100, Remove the empty “RAG and BYOK” navigation section, or populate it with the intended links, in docs/README.md lines 98-100 and apply the same correction in docs/index.md lines 105-107; keep the surrounding “Other features” navigation intact.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/user_doc/a2a_protocol.md`:
- Around line 384-386: Update the newly added fenced code blocks around the
uvicorn command and the sections identified near the other reported ranges so
each opening and closing fence has a surrounding blank line, resolving the MD031
Markdown lint violations while preserving the existing code examples.
In `@docs/user_doc/byok_guide.md`:
- Around line 342-348: Mark the unauthenticated FAISS example at
docs/user_doc/byok_guide.md:342-348, the multi-store example at
docs/user_doc/byok_guide.md:368-374, and the reference example at
docs/user_doc/rag_guide.md:344-349 as local-development-only with a prominent
warning, or enable authentication in each configuration; direct production users
to the authentication configuration.
- Around line 98-107: Fix the Markdown formatting in the documentation by adding
required blank lines before and after headings and fenced code blocks, including
the sections around “Required Tools,” “System Requirements,” and “Knowledge
Sources.” Remove the unnecessary blank line inside the affected blockquote while
preserving its content, and apply the same spacing corrections to all other
reported locations so Markdownlint passes.
- Around line 116-122: Update the deprecated RAG configuration examples so 0.7.0
guidance consistently uses rag.byok.stores, rag.retrieval.inline/tool, rag.okp,
and rag.retrieval.inline.reranker instead of the removed top-level layout. Apply
this across docs/user_doc/byok_guide.md ranges 116-122, 162-183, 184-197,
251-272, and 336-401, and docs/user_doc/rag_guide.md ranges 66-74, 78-125, and
331-366; narrow deprecation wording only where an example is intentionally
documenting migration from the old layout.
In `@docs/user_doc/config.html`:
- Line 3: Update the config document’s HTML metadata to provide a meaningful
title and document language: replace the empty lang/xml:lang values on the root
html element and the blank title with appropriate values, preferably at the
source or Pandoc build configuration so regeneration preserves them.
In `@docs/user_doc/deployment_guide.md`:
- Around line 190-194: Normalize every fenced code block in the deployment
guide, including the listed occurrences, by adding blank lines before and after
each fence and specifying an appropriate language identifier on every opening
fence. Preserve each block’s existing content and ensure the Markdown passes
MD031 and MD040.
- Around line 846-847: Update the `run.yaml` references in
`deployment_guide.md`, including the additional occurrence near the later
deployment instructions, to use the repository-root examples path
(`../../examples/run.yaml`) instead of `../examples/run.yaml`.
- Around line 1023-1026: Replace every plaintext credential example with a
secret-safe environment or secret-manager reference: update
docs/user_doc/deployment_guide.md lines 1023-1026 and 1085-1088 for both API
keys, line 1271-1273 for the MongoDB password, and docs/user_doc/a2a_protocol.md
lines 232-240 for the PostgreSQL password; preserve the surrounding
configuration while ensuring no literal credentials remain.
- Around line 1014-1035: Align authentication guidance across the deployment and
A2A documentation: update the separate-process and embedded container
configurations in docs/user_doc/deployment_guide.md (sections 1014-1035 and
1076-1097) to use secure authentication defaults or explicitly mark them as
development-only, then update docs/user_doc/a2a_protocol.md (section 177-186) so
its A2A endpoint authentication requirement matches that guidance.
- Around line 454-458: Remove the trailing stray backtick from the documented cp
command so the copy-pasteable shell command is valid, while preserving the
existing source and destination paths.
- Around line 706-751: Make the Python version requirements consistent in the
deployment guide: update the Prerequisites entry and the embedded pyproject.toml
requires-python constraint so Python 3.13 installations succeed, or remove
Python 3.13 from the prerequisites. Keep the documented supported versions
aligned across both locations.
In `@docs/user_doc/rag_guide.md`:
- Line 23: Update the Markdown in rag_guide.md to resolve all reported
Markdownlint violations: use the correct References anchor, add required blank
lines around headings and fenced code blocks at the indicated sections, and
specify the appropriate language on the fence near line 255.
- Around line 143-149: Add a shell variable-definition block immediately before
the Podman command, initializing CONTAINER_DEVICE, GPUS, and EXPORTED_PORT with
valid documented defaults or explicit required values. Ensure the existing
command references these initialized variables unchanged.
- Around line 306-323: Update the “Chunk volume” section to remove the
deprecated src/constants.py instructions and table. Document only the supported
lightspeed-stack.yaml fields—rag.byok.max_chunks, rag.okp.max_chunks,
rag.retrieval.inline.max_chunks, and rag.retrieval.tool.max_chunks—and retain
the migration-guide reference as appropriate.
- Line 223: Correct the grammar in the RAG tool sentence by changing “where not
working” to “were not working,” without altering the surrounding wording.
In `@docs/user_doc/skills_guide.md`:
- Around line 50-61: Add a language identifier such as text to the remaining
unlabeled fenced code blocks in the skills guide, including the blocks around
the documented directory tree and the sections near lines 84 and 218. Preserve
their contents and formatting while ensuring every fenced block has an explicit
language.
- Around line 212-228: Update the progressive-disclosure documentation to
replace both references to activate_skill with the runtime tool name load_skill,
including the tool list and flow diagram, while leaving the surrounding
skill-loading behavior unchanged.
- Line 78: Update the relative links in skills_guide.md, including the examples
link near the complete configuration reference and the design links around the
affected sections, to resolve from the repository root: use examples/ for
repository examples and docs/design/ for design documentation instead of paths
under docs/user_doc/.
In `@docs/user_doc/user_data_collection.md`:
- Around line 8-11: Update the “Lightspeed Core Stack” overview to make
transcript storage conditional on the data-collection enablement setting and
feedback JSON storage conditional on feedback_enabled. Preserve the existing
statements about local directories and unique filenames, and ensure the overview
matches the conditional behavior described later in the document and implemented
by the feedback handling.
- Around line 3-18: Fix Markdown spacing in user_data_collection.md by adding
blank lines after all headings and before and after fenced code blocks at the
markdownlint-reported locations, including the listed lines and ranges. Preserve
the existing documentation content and code block formatting while ensuring
consistent heading and fence separation throughout the document.
- Around line 188-193: Update the Security Considerations “Data Redaction”
bullet to state that redaction applies only to query text, while user_id, query
metadata, and llm_response may still be stored. Remove wording that implies all
sensitive information is excluded.
---
Outside diff comments:
In `@docs/README.md`:
- Around line 98-100: Remove the empty “RAG and BYOK” navigation section, or
populate it with the intended links, in docs/README.md lines 98-100 and apply
the same correction in docs/index.md lines 105-107; keep the surrounding “Other
features” navigation intact.
🪄 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: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: c41ce421-7928-4cfa-a32b-c99944b3274e
⛔ Files ignored due to path filters (2)
docs/user_doc/config.pngis excluded by!**/*.pngdocs/user_doc/config.svgis excluded by!**/*.svg
📒 Files selected for processing (14)
docs/README.mddocs/index.mddocs/user_doc/README.mddocs/user_doc/a2a_protocol.mddocs/user_doc/auth.mddocs/user_doc/byok_guide.mddocs/user_doc/config.htmldocs/user_doc/config.jsondocs/user_doc/config.mddocs/user_doc/config.pumldocs/user_doc/deployment_guide.mddocs/user_doc/rag_guide.mddocs/user_doc/skills_guide.mddocs/user_doc/user_data_collection.md
📜 Review details
⏰ Context from checks skipped due to timeout. (6)
- GitHub Check: unit_tests (3.12)
- GitHub Check: E2E: server mode / ci / group 2
- GitHub Check: E2E: library mode / ci / group 3
- GitHub Check: E2E: library mode / ci / group 1
- GitHub Check: E2E: server mode / ci / group 1
- GitHub Check: E2E Tests for Lightspeed Evaluation job
🧰 Additional context used
📓 Path-based instructions (2)
**/*
📄 CodeRabbit inference engine (Custom checks)
**/*: Flag meaningful O(n^2)+ algorithms on non-trivial inputs, including handlers and Kubernetes list operations.
Flag N+1 patterns that list items and then query once per item, including Kubernetes API and database access.
Flag expensive work inside loops, including API calls, JSON parsing, and regex compilation.
Flag unbounded growth in caches, watchers, or buffers when eviction or limits are missing.
Flag missing pagination or limits on list operations and API endpoints.
Flag secrets or tokens logged in plaintext or hardcoded in source.
Flag API endpoints missing authentication or authorization.
Flag injection vulnerabilities, including SQL injection, command injection, and path traversal.
Flag sensitive data leaked in API responses, WebSocket messages, or logs.
Flag Kubernetes Secrets and Red Hat secrets missing OwnerReferences.
Files:
docs/user_doc/auth.mddocs/user_doc/config.mddocs/user_doc/config.htmldocs/user_doc/config.pumldocs/README.mddocs/user_doc/user_data_collection.mddocs/user_doc/skills_guide.mddocs/user_doc/a2a_protocol.mddocs/user_doc/byok_guide.mddocs/user_doc/config.jsondocs/index.mddocs/user_doc/deployment_guide.mddocs/user_doc/rag_guide.md
**/*.{py,yaml,yml,json,toml}
📄 CodeRabbit inference engine (AGENTS.md)
Never commit secrets or keys; use environment variables for sensitive data.
Files:
docs/user_doc/config.json
🪛 Checkov (3.3.8)
docs/user_doc/config.json
[high] 1-1842: Ensure that the global security field has rules defined
(CKV_OPENAPI_4)
[medium] 73-80: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
🪛 HTMLHint (1.9.2)
docs/user_doc/config.html
[error] 1-1: Special characters must be escaped : [ < ].
(spec-char-escape)
[error] 1-1: Special characters must be escaped : [ > ].
(spec-char-escape)
[error] 1-1: Doctype must be declared before any non-comment content.
(doctype-first)
[warning] 3-3: The lang attribute of element must have a value.
(html-lang-require)
[error] 8-8: <title></title> must not be empty.
(title-require)
🪛 LanguageTool
docs/user_doc/user_data_collection.md
[grammar] ~16-~16: Ensure spelling is correct
Context: ...ranscripts and feedback). - It packages these data into archives and uploads them to ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
docs/user_doc/skills_guide.md
[style] ~32-~32: The phrase ‘do not have the ability to’ might be wordy. Consider using “can't”.
Context: ...nt time**. End users of LS app products do not have the ability to add skills, similar to how they cannot ...
(HAS_THE_ABILITY_TO)
docs/user_doc/byok_guide.md
[grammar] ~129-~129: Ensure spelling is correct
Context: ...asciidoctor-text/convert-it-all.py) for AsciiDoc. 3. Organize content: Structure you...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~282-~282: Ensure spelling is correct
Context: ... combining BYOK and OKP is available at > examples/lightspeed-stack-byok-okp-rag.yaml. --- ## Supported Vector Database Types ### 1. ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
docs/user_doc/deployment_guide.md
[grammar] ~63-~63: Use a hyphen to join words.
Context: ...(LLMs), access to RAG databases, call so called agents, process conversation hist...
(QB_NEW_EN_HYPHEN)
[style] ~162-~162: ‘last but not least’ might be wordy. Consider a shorter alternative.
Context: ...ally made changes and improvements. And last but not least, it is possible to trace, monitor and d...
(EN_WORDINESS_PREMIUM_LAST_BUT_NOT_LEAST)
[style] ~189-~189: This phrase is redundant. Consider using “outside”.
Context: ...Llama Stack 1. Create a new directory outside of the lightspeed-stack project directory ...
(OUTSIDE_OF)
[style] ~286-~286: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...ble Llama Stack a file named run.yaml needs to be created. Copy the example `examples...
(REP_NEED_TO_VB)
[grammar] ~624-~624: Ensure spelling is correct
Context: ...* image is needed and no other packages nor tools need to be installed. ### Retr...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[style] ~846-~846: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...ble Llama Stack a file named run.yaml needs to be created. Use the example configurati...
(REP_NEED_TO_VB)
[style] ~1041-~1041: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...k* from within a container. The service needs to be configured, so `lightspeed-stack.yam...
(REP_NEED_TO_VB)
[style] ~1048-~1048: Unless you want to emphasize “not”, use “cannot” which is more common.
Context: ...container and the standard port mapping can not be leveraged there. This configuration ...
(CAN_NOT_PREMIUM)
[style] ~1048-~1048: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...poses, but for real deployment, network needs to be reconfigured accordingly to maintain...
(REP_NEED_TO_VB)
🪛 markdownlint-cli2 (0.23.0)
docs/user_doc/user_data_collection.md
[warning] 3-3: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 8-8: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 13-13: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 18-18: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 44-44: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 50-50: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 61-61: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 77-77: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 80-80: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 122-122: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 131-131: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 136-136: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 147-147: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 160-160: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 168-168: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
docs/user_doc/skills_guide.md
[warning] 50-50: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 84-84: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 218-218: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/user_doc/a2a_protocol.md
[warning] 384-384: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 395-395: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 401-401: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 414-414: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 417-417: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 421-421: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 424-424: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
docs/user_doc/byok_guide.md
[warning] 98-98: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 103-103: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 107-107: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 145-145: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 166-166: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 174-174: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 289-289: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 305-305: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 406-406: Blank line inside blockquote
(MD028, no-blanks-blockquote)
docs/user_doc/deployment_guide.md
[warning] 190-190: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 192-192: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 194-194: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 239-239: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 241-241: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 243-243: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 243-243: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 258-258: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 260-260: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 262-262: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 264-264: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 264-264: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 296-296: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 298-298: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 300-300: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 302-302: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 304-304: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 304-304: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 439-439: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 441-441: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 443-443: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 445-445: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 467-467: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 528-528: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 541-541: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 552-552: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 554-554: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 556-556: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 558-558: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 560-560: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 721-721: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 724-724: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 726-726: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 758-758: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 799-799: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 801-801: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 803-803: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 818-818: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 820-820: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 822-822: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 824-824: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 824-824: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 853-853: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 855-855: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 857-857: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 859-859: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 861-861: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 996-996: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 998-998: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 1000-1000: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 1002-1002: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
docs/user_doc/rag_guide.md
[warning] 23-23: Link fragments should be valid
(MD051, link-fragments)
[warning] 100-100: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 255-255: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 255-255: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 375-375: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 380-380: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above
(MD022, blanks-around-headings)
🔇 Additional comments (15)
docs/user_doc/rag_guide.md (1)
28-43: LGTM!Also applies to: 44-63, 379-383
docs/user_doc/byok_guide.md (1)
55-57: 🎯 Functional CorrectnessKeep both tool names; they refer to different surfaces.
file_searchis the BYOK tool-RAG name, whileknowledge_searchis the separate RAG-as-a-tool identifier. The docs should not be forced onto one canonical name.> Likely an incorrect or invalid review comment.docs/user_doc/config.md (2)
158-158: 🎯 Functional Correctness | ⚡ Quick winRendering artifact:
<;instead of<in ByokRag.score_multiplier description.The table cell renders as "values <; 1 reduce them" due to a stray literal semicolon after the
<entity. The JSON (config.json) and HTML (config.html) versions of this same description render this correctly as a plain<. Since this file is auto-generated, the fix likely belongs in the Markdown-table generation step (double-escaping bug) rather than a hand-edit here, but flagging since it's user-facing.✏️ Proposed fix
-| score_multiplier | number | Multiplier applied to relevance scores from this vector store. Used to weight results when querying multiple knowledge sources. Values > 1 boost this store's results; values <; 1 reduce them. | +| score_multiplier | number | Multiplier applied to relevance scores from this vector store. Used to weight results when querying multiple knowledge sources. Values > 1 boost this store's results; values < 1 reduce them. |
1-157: LGTM!Also applies to: 159-861
docs/user_doc/config.json (1)
1-1842: LGTM!docs/user_doc/config.html (1)
1-2: LGTM!Also applies to: 4-172, 176-2262
docs/user_doc/config.puml (1)
1-384: LGTM!docs/user_doc/auth.md (1)
1-15: LGTM!docs/user_doc/user_data_collection.md (1)
121-156: 🎯 Functional CorrectnessNo auth header needed for the local test flow. The example setup uses
auth_enabled: falsewithauthentication: noop, so these curl commands are fine as-is.> Likely an incorrect or invalid review comment.docs/README.md (1)
10-19: LGTM!Also applies to: 43-59
docs/index.md (1)
18-18: LGTM!Also applies to: 50-66
docs/user_doc/deployment_guide.md (2)
1-159: LGTM!
622-689: LGTM!Also applies to: 1109-1251
docs/user_doc/a2a_protocol.md (2)
1-67: LGTM!
260-376: LGTM!Also applies to: 526-687, 689-793
There was a problem hiding this comment.
Caution
Inline review comments failed to post. This is likely due to GitHub's internal server error or limits when posting large numbers of comments. If you are seeing this consistently it is likely a permissions issue. Please check "Moderation" -> "Code review limits" under your organization settings.
Actionable comments posted: 21
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/README.md (1)
98-100: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winRemove or populate the empty
RAG and BYOKnavigation section.
docs/README.md#L98-L100: remove the empty heading or add the intended RAG/BYOK links.docs/index.md#L105-L107: apply the same navigation correction.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/README.md` around lines 98 - 100, Remove the empty “RAG and BYOK” navigation section, or populate it with the intended links, in docs/README.md lines 98-100 and apply the same correction in docs/index.md lines 105-107; keep the surrounding “Other features” navigation intact.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/user_doc/a2a_protocol.md`:
- Around line 384-386: Update the newly added fenced code blocks around the
uvicorn command and the sections identified near the other reported ranges so
each opening and closing fence has a surrounding blank line, resolving the MD031
Markdown lint violations while preserving the existing code examples.
In `@docs/user_doc/byok_guide.md`:
- Around line 342-348: Mark the unauthenticated FAISS example at
docs/user_doc/byok_guide.md:342-348, the multi-store example at
docs/user_doc/byok_guide.md:368-374, and the reference example at
docs/user_doc/rag_guide.md:344-349 as local-development-only with a prominent
warning, or enable authentication in each configuration; direct production users
to the authentication configuration.
- Around line 98-107: Fix the Markdown formatting in the documentation by adding
required blank lines before and after headings and fenced code blocks, including
the sections around “Required Tools,” “System Requirements,” and “Knowledge
Sources.” Remove the unnecessary blank line inside the affected blockquote while
preserving its content, and apply the same spacing corrections to all other
reported locations so Markdownlint passes.
- Around line 116-122: Update the deprecated RAG configuration examples so 0.7.0
guidance consistently uses rag.byok.stores, rag.retrieval.inline/tool, rag.okp,
and rag.retrieval.inline.reranker instead of the removed top-level layout. Apply
this across docs/user_doc/byok_guide.md ranges 116-122, 162-183, 184-197,
251-272, and 336-401, and docs/user_doc/rag_guide.md ranges 66-74, 78-125, and
331-366; narrow deprecation wording only where an example is intentionally
documenting migration from the old layout.
In `@docs/user_doc/config.html`:
- Line 3: Update the config document’s HTML metadata to provide a meaningful
title and document language: replace the empty lang/xml:lang values on the root
html element and the blank title with appropriate values, preferably at the
source or Pandoc build configuration so regeneration preserves them.
In `@docs/user_doc/deployment_guide.md`:
- Around line 190-194: Normalize every fenced code block in the deployment
guide, including the listed occurrences, by adding blank lines before and after
each fence and specifying an appropriate language identifier on every opening
fence. Preserve each block’s existing content and ensure the Markdown passes
MD031 and MD040.
- Around line 846-847: Update the `run.yaml` references in
`deployment_guide.md`, including the additional occurrence near the later
deployment instructions, to use the repository-root examples path
(`../../examples/run.yaml`) instead of `../examples/run.yaml`.
- Around line 1023-1026: Replace every plaintext credential example with a
secret-safe environment or secret-manager reference: update
docs/user_doc/deployment_guide.md lines 1023-1026 and 1085-1088 for both API
keys, line 1271-1273 for the MongoDB password, and docs/user_doc/a2a_protocol.md
lines 232-240 for the PostgreSQL password; preserve the surrounding
configuration while ensuring no literal credentials remain.
- Around line 1014-1035: Align authentication guidance across the deployment and
A2A documentation: update the separate-process and embedded container
configurations in docs/user_doc/deployment_guide.md (sections 1014-1035 and
1076-1097) to use secure authentication defaults or explicitly mark them as
development-only, then update docs/user_doc/a2a_protocol.md (section 177-186) so
its A2A endpoint authentication requirement matches that guidance.
- Around line 454-458: Remove the trailing stray backtick from the documented cp
command so the copy-pasteable shell command is valid, while preserving the
existing source and destination paths.
- Around line 706-751: Make the Python version requirements consistent in the
deployment guide: update the Prerequisites entry and the embedded pyproject.toml
requires-python constraint so Python 3.13 installations succeed, or remove
Python 3.13 from the prerequisites. Keep the documented supported versions
aligned across both locations.
In `@docs/user_doc/rag_guide.md`:
- Line 23: Update the Markdown in rag_guide.md to resolve all reported
Markdownlint violations: use the correct References anchor, add required blank
lines around headings and fenced code blocks at the indicated sections, and
specify the appropriate language on the fence near line 255.
- Around line 143-149: Add a shell variable-definition block immediately before
the Podman command, initializing CONTAINER_DEVICE, GPUS, and EXPORTED_PORT with
valid documented defaults or explicit required values. Ensure the existing
command references these initialized variables unchanged.
- Around line 306-323: Update the “Chunk volume” section to remove the
deprecated src/constants.py instructions and table. Document only the supported
lightspeed-stack.yaml fields—rag.byok.max_chunks, rag.okp.max_chunks,
rag.retrieval.inline.max_chunks, and rag.retrieval.tool.max_chunks—and retain
the migration-guide reference as appropriate.
- Line 223: Correct the grammar in the RAG tool sentence by changing “where not
working” to “were not working,” without altering the surrounding wording.
In `@docs/user_doc/skills_guide.md`:
- Around line 50-61: Add a language identifier such as text to the remaining
unlabeled fenced code blocks in the skills guide, including the blocks around
the documented directory tree and the sections near lines 84 and 218. Preserve
their contents and formatting while ensuring every fenced block has an explicit
language.
- Around line 212-228: Update the progressive-disclosure documentation to
replace both references to activate_skill with the runtime tool name load_skill,
including the tool list and flow diagram, while leaving the surrounding
skill-loading behavior unchanged.
- Line 78: Update the relative links in skills_guide.md, including the examples
link near the complete configuration reference and the design links around the
affected sections, to resolve from the repository root: use examples/ for
repository examples and docs/design/ for design documentation instead of paths
under docs/user_doc/.
In `@docs/user_doc/user_data_collection.md`:
- Around line 8-11: Update the “Lightspeed Core Stack” overview to make
transcript storage conditional on the data-collection enablement setting and
feedback JSON storage conditional on feedback_enabled. Preserve the existing
statements about local directories and unique filenames, and ensure the overview
matches the conditional behavior described later in the document and implemented
by the feedback handling.
- Around line 3-18: Fix Markdown spacing in user_data_collection.md by adding
blank lines after all headings and before and after fenced code blocks at the
markdownlint-reported locations, including the listed lines and ranges. Preserve
the existing documentation content and code block formatting while ensuring
consistent heading and fence separation throughout the document.
- Around line 188-193: Update the Security Considerations “Data Redaction”
bullet to state that redaction applies only to query text, while user_id, query
metadata, and llm_response may still be stored. Remove wording that implies all
sensitive information is excluded.
---
Outside diff comments:
In `@docs/README.md`:
- Around line 98-100: Remove the empty “RAG and BYOK” navigation section, or
populate it with the intended links, in docs/README.md lines 98-100 and apply
the same correction in docs/index.md lines 105-107; keep the surrounding “Other
features” navigation intact.
🪄 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: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: c41ce421-7928-4cfa-a32b-c99944b3274e
⛔ Files ignored due to path filters (2)
docs/user_doc/config.pngis excluded by!**/*.pngdocs/user_doc/config.svgis excluded by!**/*.svg
📒 Files selected for processing (14)
docs/README.mddocs/index.mddocs/user_doc/README.mddocs/user_doc/a2a_protocol.mddocs/user_doc/auth.mddocs/user_doc/byok_guide.mddocs/user_doc/config.htmldocs/user_doc/config.jsondocs/user_doc/config.mddocs/user_doc/config.pumldocs/user_doc/deployment_guide.mddocs/user_doc/rag_guide.mddocs/user_doc/skills_guide.mddocs/user_doc/user_data_collection.md
📜 Review details
🔇 Additional comments (15)
docs/user_doc/rag_guide.md (1)
28-43: LGTM!Also applies to: 44-63, 379-383
docs/user_doc/byok_guide.md (1)
55-57: 🎯 Functional CorrectnessKeep both tool names; they refer to different surfaces.
file_searchis the BYOK tool-RAG name, whileknowledge_searchis the separate RAG-as-a-tool identifier. The docs should not be forced onto one canonical name.> Likely an incorrect or invalid review comment.docs/user_doc/config.md (2)
158-158: 🎯 Functional Correctness | ⚡ Quick winRendering artifact:
<;instead of<in ByokRag.score_multiplier description.The table cell renders as "values <; 1 reduce them" due to a stray literal semicolon after the
<entity. The JSON (config.json) and HTML (config.html) versions of this same description render this correctly as a plain<. Since this file is auto-generated, the fix likely belongs in the Markdown-table generation step (double-escaping bug) rather than a hand-edit here, but flagging since it's user-facing.✏️ Proposed fix
-| score_multiplier | number | Multiplier applied to relevance scores from this vector store. Used to weight results when querying multiple knowledge sources. Values > 1 boost this store's results; values <; 1 reduce them. | +| score_multiplier | number | Multiplier applied to relevance scores from this vector store. Used to weight results when querying multiple knowledge sources. Values > 1 boost this store's results; values < 1 reduce them. |
1-157: LGTM!Also applies to: 159-861
docs/user_doc/config.json (1)
1-1842: LGTM!docs/user_doc/config.html (1)
1-2: LGTM!Also applies to: 4-172, 176-2262
docs/user_doc/config.puml (1)
1-384: LGTM!docs/user_doc/auth.md (1)
1-15: LGTM!docs/user_doc/user_data_collection.md (1)
121-156: 🎯 Functional CorrectnessNo auth header needed for the local test flow. The example setup uses
auth_enabled: falsewithauthentication: noop, so these curl commands are fine as-is.> Likely an incorrect or invalid review comment.docs/README.md (1)
10-19: LGTM!Also applies to: 43-59
docs/index.md (1)
18-18: LGTM!Also applies to: 50-66
docs/user_doc/deployment_guide.md (2)
1-159: LGTM!
622-689: LGTM!Also applies to: 1109-1251
docs/user_doc/a2a_protocol.md (2)
1-67: LGTM!
260-376: LGTM!Also applies to: 526-687, 689-793
🛑 Comments failed to post (21)
docs/user_doc/a2a_protocol.md (1)
384-386: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win
Resolve the reported Markdown lint violations.
markdownlint-cli2reports MD031 warnings for these fenced blocks lacking surrounding blank lines. Apply the same formatting fix to the remaining newly added fences in this document.Also applies to: 395-409, 414-425
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 384-384: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/user_doc/a2a_protocol.md` around lines 384 - 386, Update the newly added fenced code blocks around the uvicorn command and the sections identified near the other reported ranges so each opening and closing fence has a surrounding blank line, resolving the MD031 Markdown lint violations while preserving the existing code examples.Source: Linters/SAST tools
docs/user_doc/byok_guide.md (3)
98-107: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Fix the reported Markdown formatting violations.
Add the required blank lines around headings and fenced blocks, and remove the blank line inside the blockquote at Line 406 so the documentation passes Markdownlint.
Also applies to: 145-145, 166-174, 289-305, 406-406
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 98-98: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below(MD022, blanks-around-headings)
[warning] 103-103: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below(MD022, blanks-around-headings)
[warning] 107-107: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below(MD022, blanks-around-headings)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/user_doc/byok_guide.md` around lines 98 - 107, Fix the Markdown formatting in the documentation by adding required blank lines before and after headings and fenced code blocks, including the sections around “Required Tools,” “System Requirements,” and “Knowledge Sources.” Remove the unnecessary blank line inside the affected blockquote while preserving its content, and apply the same spacing corrections to all other reported locations so Markdownlint passes.Source: Linters/SAST tools
116-122: 🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift
Migrate the docs off the deprecated top-level RAG layout
The guide still presents
byok_rag, top-levelrag,okp, andrerankeras the primary 0.7.0 configuration across multiple examples. Update those snippets torag.byok.stores/rag.retrieval.*/rag.okp, or narrow the deprecation note so the examples no longer advertise the removed layout.📍 Affects 2 files
docs/user_doc/byok_guide.md#L116-L122(this comment)docs/user_doc/byok_guide.md#L162-L183docs/user_doc/byok_guide.md#L184-L197docs/user_doc/byok_guide.md#L251-L272docs/user_doc/byok_guide.md#L336-L401docs/user_doc/rag_guide.md#L66-L74docs/user_doc/rag_guide.md#L78-L125docs/user_doc/rag_guide.md#L331-L366🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/user_doc/byok_guide.md` around lines 116 - 122, Update the deprecated RAG configuration examples so 0.7.0 guidance consistently uses rag.byok.stores, rag.retrieval.inline/tool, rag.okp, and rag.retrieval.inline.reranker instead of the removed top-level layout. Apply this across docs/user_doc/byok_guide.md ranges 116-122, 162-183, 184-197, 251-272, and 336-401, and docs/user_doc/rag_guide.md ranges 66-74, 78-125, and 331-366; narrow deprecation wording only where an example is intentionally documenting migration from the old layout.
342-348: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Do not leave copy-paste examples unauthenticated without a prominent local-only warning.
All complete examples set
auth_enabled: false. If users expose the configured port or change the host, the documented service has no API authentication. Mark these snippets explicitly as development-only and point production users to the authentication configuration.
docs/user_doc/byok_guide.md#L342-L348: label the FAISS example as local-only or enable authentication.docs/user_doc/byok_guide.md#L368-L374: label the multi-store example as local-only or enable authentication.docs/user_doc/rag_guide.md#L344-L349: apply the same warning or secure the reference configuration.As per coding guidelines, API endpoints missing authentication or authorization must be flagged.
📍 Affects 2 files
docs/user_doc/byok_guide.md#L342-L348(this comment)docs/user_doc/byok_guide.md#L368-L374docs/user_doc/rag_guide.md#L344-L349🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/user_doc/byok_guide.md` around lines 342 - 348, Mark the unauthenticated FAISS example at docs/user_doc/byok_guide.md:342-348, the multi-store example at docs/user_doc/byok_guide.md:368-374, and the reference example at docs/user_doc/rag_guide.md:344-349 as local-development-only with a prominent warning, or enable authentication in each configuration; direct production users to the authentication configuration.Source: Coding guidelines
docs/user_doc/config.html (1)
3-3: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash # Locate the command that generates docs/user_doc/config.html to confirm where title/lang metadata should be injected. rg -n 'config\.html' Makefile rg -n 'pandoc' MakefileRepository: lightspeed-core/lightspeed-stack
Length of output: 170
🏁 Script executed:
#!/bin/bash set -euo pipefail printf '\n== files of interest ==\n' git ls-files | rg '(^|/)(Makefile|makefile|config\.md|config\.html|docs/user_doc/|pandoc|pyreverse|README)' printf '\n== search for generators ==\n' rg -n 'pandoc|config\.html|config\.md|user_doc|pyreverse|metadata title|metadata lang|xml:lang|<title>' .Repository: lightspeed-core/lightspeed-stack
Length of output: 50391
🏁 Script executed:
#!/bin/bash set -euo pipefail printf '\n== docs/user_doc/config.html size/head ==\n' wc -l docs/user_doc/config.html sed -n '1,30p' docs/user_doc/config.html printf '\n== nearby title/lang lines ==\n' rg -n '<title>|xml:lang=|<html ' docs/user_doc/config.htmlRepository: lightspeed-core/lightspeed-stack
Length of output: 1143
🏁 Script executed:
#!/bin/bash set -euo pipefail printf '\n== tree around docs ==\n' fd -t f -a . docs .github . | sed -n '1,200p'Repository: lightspeed-core/lightspeed-stack
Length of output: 12185
🏁 Script executed:
#!/bin/bash set -euo pipefail sed -n '232,250p' Makefile printf '\n== config-related rules ==\n' rg -n 'config\.md|config\.html|pandoc|metadata|user_doc' MakefileRepository: lightspeed-core/lightspeed-stack
Length of output: 1175
🏁 Script executed:
#!/bin/bash set -euo pipefail printf '\n== docs/user_doc/config.md head ==\n' sed -n '1,40p' docs/user_doc/config.md printf '\n== docs/user_doc/README.md head ==\n' sed -n '1,120p' docs/user_doc/README.md printf '\n== docs/README.md relevant lines ==\n' rg -n 'user_doc|config\.html|pandoc|generate|build' docs/README.md docs/user_doc/README.md docs/index.mdRepository: lightspeed-core/lightspeed-stack
Length of output: 3313
🏁 Script executed:
#!/bin/bash set -euo pipefail printf '\n== config.md headings/front matter ==\n' rg -n '^(---|title:|lang:|# )' docs/user_doc/config.mdRepository: lightspeed-core/lightspeed-stack
Length of output: 269
🏁 Script executed:
#!/bin/bash set -euo pipefail printf '\n== search for docs/user_doc build tooling ==\n' rg -n 'pandoc|config\.md|config\.html|user_doc' .github Makefile docsRepository: lightspeed-core/lightspeed-stack
Length of output: 2825
Set a real title and language on the config doc
docs/user_doc/config.html:3,8still has<html lang="" xml:lang="">and a blank<title>. Add title/lang metadata in the source doc or pandoc build so the page has usable tab text and document language.🧰 Tools
🪛 HTMLHint (1.9.2)
[warning] 3-3: The lang attribute of element must have a value.
(html-lang-require)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/user_doc/config.html` at line 3, Update the config document’s HTML metadata to provide a meaningful title and document language: replace the empty lang/xml:lang values on the root html element and the blank title with appropriate values, preferably at the source or Pandoc build configuration so regeneration preserves them.docs/user_doc/deployment_guide.md (6)
190-194: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win
Resolve the reported Markdown lint violations.
markdownlint-cli2reports repeated MD031 warnings for fences without surrounding blank lines and MD040 warnings for fences without language identifiers throughout this added guide. Normalize the fenced blocks before merging so documentation CI and rendering remain consistent.Also applies to: 239-243, 258-264, 296-304, 439-445, 467-467, 528-528, 541-541, 552-560, 721-726, 758-758, 799-803, 818-824, 853-861, 996-1002
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 190-190: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 192-192: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 194-194: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/user_doc/deployment_guide.md` around lines 190 - 194, Normalize every fenced code block in the deployment guide, including the listed occurrences, by adding blank lines before and after each fence and specifying an appropriate language identifier on every opening fence. Preserve each block’s existing content and ensure the Markdown passes MD031 and MD040.Source: Linters/SAST tools
454-458: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Remove the stray backtick from the copy command.
The documented command is not valid shell syntax and will fail when users copy it.
Proposed fix
-cp examples/lightspeed-stack-lls-external.yaml lightspeed-stack.yaml` +cp examples/lightspeed-stack-lls-external.yaml lightspeed-stack.yaml📝 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.Copy the `examples/lightspeed-stack-lls-external.yaml` file to your llama-stack project directory, naming it `lightspeed-stack.yaml`:🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/user_doc/deployment_guide.md` around lines 454 - 458, Remove the trailing stray backtick from the documented cp command so the copy-pasteable shell command is valid, while preserving the existing source and destination paths.
706-751: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash set -euo pipefail echo '--- target section ---' sed -n '690,770p' docs/user_doc/deployment_guide.md echo echo '--- python version references ---' rg -n --hidden --no-messages '3\.13|requires-python|llama-stack==0\.2\.22' docs . -g '!**/.git/**'Repository: lightspeed-core/lightspeed-stack
Length of output: 50391
🏁 Script executed:
#!/bin/bash set -euo pipefail echo '--- root pyproject version constraint ---' sed -n '1,40p' pyproject.toml echo echo '--- version specifier semantics ---' python3 - <<'PY' from packaging.specifiers import SpecifierSet for spec in ["==3.12.*", ">=3.12,<3.14"]: s = SpecifierSet(spec) print(spec, "3.12.10" in s, "3.13.0" in s) PYRepository: lightspeed-core/lightspeed-stack
Length of output: 1406
Make the Python version requirement consistent. The prerequisites allow Python 3.13, but the embedded
pyproject.tomlpinsrequires-python = "==3.12.*", so a 3.13 install will fail atuv sync. Either drop 3.13 here or widen the project constraint.🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 721-721: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 724-724: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 726-726: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/user_doc/deployment_guide.md` around lines 706 - 751, Make the Python version requirements consistent in the deployment guide: update the Prerequisites entry and the embedded pyproject.toml requires-python constraint so Python 3.13 installations succeed, or remove Python 3.13 from the prerequisites. Keep the documented supported versions aligned across both locations.
846-847: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Fix the relative links to
run.yaml.From
docs/user_doc/deployment_guide.md,../examples/run.yamlresolves todocs/examples/run.yaml, while the surrounding commands refer to the repository-rootexamples/run.yaml. Use the correct relative path, likely../../examples/run.yaml, if the file is at repository root.Also applies to: 1068-1070
🧰 Tools
🪛 LanguageTool
[style] ~846-~846: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...ble Llama Stack a file namedrun.yamlneeds to be created. Use the example configurati...(REP_NEED_TO_VB)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/user_doc/deployment_guide.md` around lines 846 - 847, Update the `run.yaml` references in `deployment_guide.md`, including the additional occurrence near the later deployment instructions, to use the repository-root examples path (`../../examples/run.yaml`) instead of `../examples/run.yaml`.
1014-1035: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Align authentication defaults and documentation across the deployment and A2A guides.
The deployment snippets disable authentication, while the A2A guide states that A2A endpoints require it. Use secure defaults or clearly label the unauthenticated snippets as development-only.
docs/user_doc/deployment_guide.md#L1014-L1035: secure or clearly scope the separate-process container configuration.docs/user_doc/deployment_guide.md#L1076-L1097: secure or clearly scope the embedded container configuration.docs/user_doc/a2a_protocol.md#L177-L186: make the authentication requirement consistent with those deployment instructions.As per coding guidelines: flag API endpoints missing authentication or authorization.
📍 Affects 2 files
docs/user_doc/deployment_guide.md#L1014-L1035(this comment)docs/user_doc/deployment_guide.md#L1076-L1097docs/user_doc/a2a_protocol.md#L177-L186🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/user_doc/deployment_guide.md` around lines 1014 - 1035, Align authentication guidance across the deployment and A2A documentation: update the separate-process and embedded container configurations in docs/user_doc/deployment_guide.md (sections 1014-1035 and 1076-1097) to use secure authentication defaults or explicitly mark them as development-only, then update docs/user_doc/a2a_protocol.md (section 177-186) so its A2A endpoint authentication requirement matches that guidance.Source: Coding guidelines
1023-1026: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Replace all plaintext credential examples with secret-safe configuration.
docs/user_doc/deployment_guide.md#L1023-L1026: replaceapi_key: xyzzywith an environment-backed value.docs/user_doc/deployment_guide.md#L1085-L1088: replace the embedded-mode API key similarly.docs/user_doc/deployment_guide.md#L1271-L1273: replace the plaintext MongoDB password with a Secret or environment reference.docs/user_doc/a2a_protocol.md#L232-L240: replace the PostgreSQL password with a secret-management example.As per coding guidelines: never commit secrets or keys; use environment variables for sensitive data.
📍 Affects 2 files
docs/user_doc/deployment_guide.md#L1023-L1026(this comment)docs/user_doc/deployment_guide.md#L1085-L1088docs/user_doc/deployment_guide.md#L1271-L1273docs/user_doc/a2a_protocol.md#L232-L240🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/user_doc/deployment_guide.md` around lines 1023 - 1026, Replace every plaintext credential example with a secret-safe environment or secret-manager reference: update docs/user_doc/deployment_guide.md lines 1023-1026 and 1085-1088 for both API keys, line 1271-1273 for the MongoDB password, and docs/user_doc/a2a_protocol.md lines 232-240 for the PostgreSQL password; preserve the surrounding configuration while ensuring no literal credentials remain.Source: Coding guidelines
docs/user_doc/rag_guide.md (4)
23-23: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Fix the reported Markdownlint violations.
Correct the invalid
#referencesfragment, add blank lines around fenced blocks/headings, and specify a language for the fence at Line 255.Also applies to: 100-102, 255-255, 375-376, 380-380
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 23-23: Link fragments should be valid
(MD051, link-fragments)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/user_doc/rag_guide.md` at line 23, Update the Markdown in rag_guide.md to resolve all reported Markdownlint violations: use the correct References anchor, add required blank lines around headings and fenced code blocks at the indicated sections, and specify the appropriate language on the fence near line 255.Source: Linters/SAST tools
143-149: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Define the required shell variables before this copy-paste command.
${CONTAINER_DEVICE},${GPUS}, and${EXPORTED_PORT}are referenced without setup instructions. If unset, Podman receives invalid device/GPU or port arguments. Add a variable-definition block with valid defaults or replace them with explicit, documented values.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/user_doc/rag_guide.md` around lines 143 - 149, Add a shell variable-definition block immediately before the Podman command, initializing CONTAINER_DEVICE, GPUS, and EXPORTED_PORT with valid documented defaults or explicit required values. Ensure the existing command references these initialized variables unchanged.
223-223: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Correct the grammar typo.
“where not working” should be “were not working.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/user_doc/rag_guide.md` at line 223, Correct the grammar in the RAG tool sentence by changing “where not working” to “were not working,” without altering the surrounding wording.Source: Linters/SAST tools
306-323: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Remove the contradictory chunk-limit instructions.
This section says the constants are deprecated and replaced by
lightspeed-stack.yamlfields, then immediately instructs users to editsrc/constants.py. Document only the supported configuration path for the target release.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/user_doc/rag_guide.md` around lines 306 - 323, Update the “Chunk volume” section to remove the deprecated src/constants.py instructions and table. Document only the supported lightspeed-stack.yaml fields—rag.byok.max_chunks, rag.okp.max_chunks, rag.retrieval.inline.max_chunks, and rag.retrieval.tool.max_chunks—and retain the migration-guide reference as appropriate.docs/user_doc/skills_guide.md (3)
50-61: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add language identifiers to the remaining fenced blocks.
The reported markdownlint warnings at Lines 50, 84, and 218 require a fence language such as
text.Also applies to: 84-90, 218-232
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 50-50: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/user_doc/skills_guide.md` around lines 50 - 61, Add a language identifier such as text to the remaining unlabeled fenced code blocks in the skills guide, including the blocks around the documented directory tree and the sections near lines 84 and 218. Preserve their contents and formatting while ensuring every fenced block has an explicit language.Source: Linters/SAST tools
78-78: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash set -euo pipefail printf 'Repo files of interest:\n' git ls-files 'docs/user_doc/skills_guide.md' 'docs/**/examples*' 'examples/**' 'docs/user_doc/design/**' 'docs/design/**' | sed 's#^`#-` #' printf '\nTarget existence checks:\n' for p in \ 'docs/examples/lightspeed-stack-skills.yaml' \ 'examples/lightspeed-stack-skills.yaml' \ 'docs/user_doc/design' \ 'docs/design' do if [ -e "$p" ]; then printf '%s: exists\n' "$p" else printf '%s: missing\n' "$p" fi done printf '\nRelevant lines from docs/user_doc/skills_guide.md:\n' sed -n '70,90p;200,260p' docs/user_doc/skills_guide.md | cat -nRepository: lightspeed-core/lightspeed-stack
Length of output: 6958
🏁 Script executed:
#!/bin/bash set -euo pipefail python3 - <<'PY' from pathlib import Path root = Path('.') checks = [ Path('docs/examples/lightspeed-stack-skills.yaml'), Path('examples/lightspeed-stack-skills.yaml'), Path('docs/user_doc/design'), Path('docs/design'), ] for p in checks: print(f"{p}: {'exists' if p.exists() else 'missing'}") PY printf '\nLink lines:\n' grep -nE '\.\./examples/|(^|[^.])design/' docs/user_doc/skills_guide.md || trueRepository: lightspeed-core/lightspeed-stack
Length of output: 866
Fix the relative doc links. In
docs/user_doc/skills_guide.md,../examples/...points todocs/examples/..., anddesign/...points todocs/user_doc/design/...; update these to the repo-levelexamples/anddocs/design/paths. Lines 78, 208, and 250-252 are affected.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/user_doc/skills_guide.md` at line 78, Update the relative links in skills_guide.md, including the examples link near the complete configuration reference and the design links around the affected sections, to resolve from the repository root: use examples/ for repository examples and docs/design/ for design documentation instead of paths under docs/user_doc/.
212-228: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Use the runtime tool name
load_skill.The guide calls the tool
activate_skillon Lines 215 and 225, buttests/e2e/features/skills.featureexercisesload_skill. Update both references so the documented progressive-disclosure flow matches the implementation.Suggested fix
-2. **`activate_skill`** — When a task matches a skill's description, the LLM calls this to load the full instructions from `SKILL.md`. +2. **`load_skill`** — When a task matches a skill's description, the LLM calls this to load the full instructions from `SKILL.md`. ... -LLM calls activate_skill → loads full SKILL.md instructions +LLM calls load_skill → loads full SKILL.md instructions📝 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.Skills use a progressive disclosure pattern with three LLM tools: 1. **`list_skills`** — The LLM calls this to discover available skills. Returns the name and description of each skill. 2. **`load_skill`** — When a task matches a skill's description, the LLM calls this to load the full instructions from `SKILL.md`. 3. **`load_skill_resource`** — If the skill instructions reference files in `references/`, the LLM calls this to load them on demand.🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 218-218: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/user_doc/skills_guide.md` around lines 212 - 228, Update the progressive-disclosure documentation to replace both references to activate_skill with the runtime tool name load_skill, including the tool list and flow diagram, while leaving the surrounding skill-loading behavior unchanged.docs/user_doc/user_data_collection.md (3)
3-18: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Fix the reported Markdown spacing violations.
Add blank lines after headings and around fenced code blocks at the markdownlint-reported locations, including Lines 3, 8, 13, 18, 44, 50, 61, 77, 80, 122, 131, 136, 147, and 160.
Also applies to: 42-50, 59-80, 122-160
🧰 Tools
🪛 LanguageTool
[grammar] ~16-~16: Ensure spelling is correct
Context: ...ranscripts and feedback). - It packages these data into archives and uploads them to ...(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🪛 markdownlint-cli2 (0.23.0)
[warning] 3-3: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below(MD022, blanks-around-headings)
[warning] 8-8: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below(MD022, blanks-around-headings)
[warning] 13-13: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below(MD022, blanks-around-headings)
[warning] 18-18: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below(MD022, blanks-around-headings)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/user_doc/user_data_collection.md` around lines 3 - 18, Fix Markdown spacing in user_data_collection.md by adding blank lines after all headings and before and after fenced code blocks at the markdownlint-reported locations, including the listed lines and ranges. Preserve the existing documentation content and code block formatting while ensuring consistent heading and fence separation throughout the document.Source: Linters/SAST tools
8-11: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Make storage claims conditional on configuration.
The overview says every interaction and feedback submission creates a file, but the later data-flow section correctly says this occurs only when collection is enabled.
src/app/endpoints/feedback.pyalso gates feedback handling onfeedback_enabled. Make the overview consistently state that storage depends on the corresponding enablement settings.Also applies to: 109-115
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 8-8: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below(MD022, blanks-around-headings)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/user_doc/user_data_collection.md` around lines 8 - 11, Update the “Lightspeed Core Stack” overview to make transcript storage conditional on the data-collection enablement setting and feedback JSON storage conditional on feedback_enabled. Preserve the existing statements about local directories and unique filenames, and ensure the overview matches the conditional behavior described later in the document and implemented by the feedback handling.
188-193: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash set -euo pipefail # Inspect the relevant section with line numbers. sed -n '170,210p' docs/user_doc/user_data_collection.md # Show nearby mentions of redaction and retained fields across the document. rg -n "redacted_query|user_id|LLM response|query metadata|redact|privacy" docs/user_doc/user_data_collection.mdRepository: lightspeed-core/lightspeed-stack
Length of output: 2058
🏁 Script executed:
#!/bin/bash set -euo pipefail # Inspect the example payload section that mentions user_id and redacted_query. sed -n '50,115p' docs/user_doc/user_data_collection.md # Search for any explicit mention of the full LLM response or retained metadata. rg -n "LLM response|response|metadata|user_id|redacted_query|query" docs/user_doc/user_data_collection.mdRepository: lightspeed-core/lightspeed-stack
Length of output: 3686
Clarify what
redacted_queryactually redacts — The transcript example still storesuser_id, query metadata, andllm_response, so the doc should say redaction applies to the query text only and avoid implying that sensitive data cannot be captured.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/user_doc/user_data_collection.md` around lines 188 - 193, Update the Security Considerations “Data Redaction” bullet to state that redaction applies only to query text, while user_id, query metadata, and llm_response may still be stored. Remove wording that implies all sensitive information is excluded.
|
@coderabbitai full review |
✅ Action performedFull review finished. Your plan includes PR reviews subject to rate limits. More reviews will be available in 47 minutes. |
1 participant
Description
LCORE-2933: User doc
Type of change
Tools used to create PR
Related Tickets & Documents
Summary by CodeRabbit