docs: Consolidate quickstart guide into one canonical Quickstart#1033
docs: Consolidate quickstart guide into one canonical Quickstart#1033sudhanshu456 wants to merge 1 commit into
Conversation
- Merge getting-started/quickstart-new.md content into getting-started/quickstart.md; drop the separate quickstart-new.md and top-level quickstart.md - Fix wording: /skills instead of /, /agent instead of /mode - Add the missing Reviewer agent mode - Update nav to point Quickstart at the consolidated page Ported from AltimateAI/help-docs PR AltimateAI#13.
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
|
Hey! Your PR title Please update it to start with one of:
Where See CONTRIBUTING.md for details. |
📝 WalkthroughWalkthroughThe documentation consolidates Getting Started navigation around a rewritten quickstart, updates setup and agent-mode guidance, adds project and connection workflow instructions, refreshes command references, and changes built-in skill discovery instructions. ChangesQuickstart documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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 |
sudhanshu456
changed the title
|
Thanks for updating your PR! It now meets our contributing guidelines. 👍 |
1 similar comment
|
Thanks for updating your PR! It now meets our contributing guidelines. 👍 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 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/docs/getting-started.md`:
- Line 3: Replace the duplicate setup-guide content in getting-started.md with a
concise landing page that directs readers to getting-started/quickstart.md as
the canonical guide, or remove the page after verifying and updating inbound
links. Do not retain conflicting installation, configuration, or mode
instructions.
In `@docs/docs/getting-started/quickstart.md`:
- Around line 99-103: Update the fenced blocks in the quickstart documentation,
including the command-output block near the dbt indexing example and the
directory-tree block around the referenced later section, to specify the text
language identifier. Preserve their existing contents and formatting.
- Around line 200-208: Clarify the execution interface in the quickstart section
containing the warehouse_test and schema_index examples. State whether users
should enter these as slash commands, submit them through the TUI prompt with
the documented prefix, or run them through another interface, and update the
examples to match that supported syntax consistently.
- Around line 27-32: Update the “Does your org restrict npm install scripts?”
note to remove the incorrect npm config command and Lavamoat-specific guidance,
or replace it with the officially supported allow-scripts approval workflow and
documentation. Keep the explanation that blocked postinstall scripts can prevent
the CLI from functioning.
🪄 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: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: ce870d5e-c137-4c23-b219-270476738b59
📒 Files selected for processing (7)
docs/docs/configure/skills.mddocs/docs/getting-started.mddocs/docs/getting-started/index.mddocs/docs/getting-started/quickstart-new.mddocs/docs/getting-started/quickstart.mddocs/docs/quickstart.mddocs/mkdocs.yml
💤 Files with no reviewable changes (2)
- docs/docs/quickstart.md
- docs/docs/getting-started/quickstart-new.md
| # Getting Started | ||
|
|
||
| > **New to altimate?** [Start with the 5-minute quickstart](quickstart.md) to go from install to your first analysis in minutes. | ||
| > **New to Altimate Code?** [Start with the quickstart](getting-started/quickstart.md) to go from install to your first analysis. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Make this page a landing page or remove it.
docs/docs/getting-started.md still contains a second full setup guide while docs/mkdocs.yml now makes docs/docs/getting-started/quickstart.md canonical. The two pages already diverge on configuration paths and mode commands, so direct links can expose stale instructions. Replace the duplicate body with a short redirect/landing page or remove it after checking inbound links.
🤖 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/docs/getting-started.md` at line 3, Replace the duplicate setup-guide
content in getting-started.md with a concise landing page that directs readers
to getting-started/quickstart.md as the canonical guide, or remove the page
after verifying and updating inbound links. Do not retain conflicting
installation, configuration, or mode instructions.
| ??? note "Does your org restrict npm install scripts?" | ||
| If your org blocks npm lifecycle scripts (for example with `--ignore-scripts` or a script-approval gate like `@lavamoat/allow-scripts`), that postinstall step won't run, and the CLI may not function correctly. To let it run those postinstall scripts, run this and reinstall: | ||
|
|
||
| ## Step 2: Configure Your LLM | ||
| ```bash title="Terminal" | ||
| npm config set allow-scripts=altimate-code --location=user | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
rg -n --glob '*.md' --glob 'package.json' 'allow-scripts|`@lavamoat/allow-scripts`|ignore-scripts' .Repository: AltimateAI/altimate-code
Length of output: 775
🌐 Web query:
@lavamoat/allow-scripts npm config allow-scripts documentation
💡 Result:
@lavamoat/allow-scripts is a security tool designed to restrict the execution of dependency lifecycle scripts to only those explicitly approved in an allowlist [1][2]. By default, it denies all lifecycle scripts and requires a configuration process to enable necessary ones [1][3]. Configuration and Usage The tool's configuration is stored in the lavamoat property within your project's package.json file, specifically under the allowScripts object [2][4]. The workflow for managing dependencies with this tool is as follows: 1. Setup: Run allow-scripts setup to initialize the project [1][3]. This command creates or updates a.npmrc or.yarnrc file to include ignore-scripts=true, effectively disabling automatic script execution [5][3]. 2. Populate Allowlist: Run allow-scripts auto to generate and update the allowlist in your package.json [2][5]. This command automatically identifies dependencies with lifecycle scripts and adds them to the configuration, setting their status to false (denied) by default [1][4]. 3. Run Allowed Scripts: After every package installation, run allow-scripts run to execute only the lifecycle scripts for packages that have been explicitly set to true in the allowlist [1][2]. Configuration Format The configuration in package.json uses a record format where keys represent the package (or a dependency path) and values represent the permission status [2][6]: { "lavamoat": { "allowScripts": { "package-name#version": true, "other-package#version": false } } } Key Notes: - Version Pinning: Versions are mandatory for allowed packages to enhance security against maintainer compromise [4]. - Disallowed Packages: You can remove the #version suffix from disallowed items if you want to deny a package regardless of its version [6][4]. - Flexibility: You can opt out of version-specific behavior by using the --skip-versions flag with the auto and run commands [6][4]. - Error Handling: The tool will fail if it detects dependencies with unconfigured lifecycle scripts, prompting you to run allow-scripts auto to address them [2][5]. Installation It is recommended to install @lavamoat/allow-scripts globally for the initial setup, and as a project-local development dependency (npm i -D @lavamoat/allow-scripts) to ensure all contributors use the same configuration [1][3]. Local usage can be integrated directly into your project's scripts in package.json [5][7].
Citations:
- 1: https://www.npmjs.com/package/@lavamoat/allow-scripts
- 2: https://lavamoat.github.io/guides/allow-scripts/
- 3: https://github.com/LavaMoat/LavaMoat/tree/main/packages/allow-scripts
- 4: https://registry.npmjs.org/%40lavamoat%2Fallow-scripts
- 5: https://github.com/LavaMoat/LavaMoat/blob/main/packages/allow-scripts/README.md
- 6: https://npmx.dev/package/@lavamoat/allow-scripts/v/5.0.2
- 7: https://registry.npmjs.org/@lavamoat/allow-scripts
Update the allow-scripts approval guidance.
@lavamoat/allow-scripts uses the lavamoat.allowScripts allowlist in package metadata and expects approved lifecycle scripts to be run via its workflow, not arbitrary npm config set allow-scripts=altimate-code --location=user. Replace this with the actual supported approval mechanism/CLI documentation or remove the Lavamoat-specific example.
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 30-30: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
🤖 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/docs/getting-started/quickstart.md` around lines 27 - 32, Update the
“Does your org restrict npm install scripts?” note to remove the incorrect npm
config command and Lavamoat-specific guidance, or replace it with the officially
supported allow-scripts approval workflow and documentation. Keep the
explanation that blocked postinstall scripts can prevent the CLI from
functioning.
| ``` | ||
| Found dbt project: jaffle_shop (dbt-snowflake) | ||
| Found profile: snowflake_prod → Added connection 'snowflake_prod' | ||
| Indexing schema... 142 tables, 1,847 columns indexed | ||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add language identifiers to the fenced blocks.
markdownlint MD040 flags the command output fence and the directory-tree fence. Use text for both.
Proposed fix
-```
+```text
Found dbt project: jaffle_shop (dbt-snowflake)
...
- ```
+ ```textAlso applies to: 259-275
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 99-99: 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/docs/getting-started/quickstart.md` around lines 99 - 103, Update the
fenced blocks in the quickstart documentation, including the command-output
block near the dbt indexing example and the directory-tree block around the
referenced later section, to specify the text language identifier. Preserve
their existing contents and formatting.
Source: Linters/SAST tools
| Verify the connection, then index the schema for autocomplete and analysis: | ||
|
|
||
| ``` | ||
| > warehouse_test snowflake | ||
| ✓ Connected successfully | ||
| ```text title="In the TUI" | ||
| warehouse_test snowflake | ||
| ``` | ||
|
|
||
| --- | ||
| ```text title="In the TUI" | ||
| schema_index snowflake | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
rg -n --glob '*.md' 'warehouse_test|schema_index|/discover|/connect' docsRepository: AltimateAI/altimate-code
Length of output: 6186
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== quickstart relevant sections =="
sed -n '180,215p' docs/docs/getting-started/quickstart.md
sed -n '200,210p' docs/docs/getting-started/quickstart.md
echo
echo "== tui docs =="
sed -n '1,80p' docs/docs/usage/tui.md
echo
echo "== configure commands/docs docs =="
sed -n '1,45p' docs/docs/configure/commands.md
sed -n '530,555p' docs/docs/configure/warehouses.md
echo
echo "== tool docs for schema_index and warehouse_test =="
sed -n '1,80p' docs/docs/data-engineering/tools/schema-tools.md
sed -n '90,130p' docs/docs/data-engineering/tools/warehouse-tools.mdRepository: AltimateAI/altimate-code
Length of output: 9451
Clarify where users should run these warehouse commands.
These are shown as direct TUI commands, but the TUI docs only define slash commands, while /discover and the warehouse docs present warehouse_test / schema_index as prefixed prompts/tools. Update this section so users know whether to run /discover, type these through the TUI prompt, or use an alternate interface.
🤖 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/docs/getting-started/quickstart.md` around lines 200 - 208, Clarify the
execution interface in the quickstart section containing the warehouse_test and
schema_index examples. State whether users should enter these as slash commands,
submit them through the TUI prompt with the documented prefix, or run them
through another interface, and update the examples to match that supported
syntax consistently.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
4 issues found across 7 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="docs/docs/getting-started.md">
<violation number="1" location="docs/docs/getting-started.md:3">
P2: This file still contains a full multi-step setup guide (agent modes table, mode-switching commands, etc.) that overlaps with the now-canonical `getting-started/quickstart.md`. Since the goal is consolidation, consider reducing this page to a short landing/redirect that links to the canonical quickstart, otherwise readers may land here via direct links and see instructions that drift out of sync over time.</violation>
</file>
<file name="docs/docs/getting-started/quickstart.md">
<violation number="1" location="docs/docs/getting-started/quickstart.md:31">
P2: The suggested command `npm config set allow-scripts=altimate-code --location=user` does not correspond to how `@lavamoat/allow-scripts` actually works. LavaMoat uses a `"lavamoat": { "allowScripts": { "package-name": true } }` allowlist in `package.json`, managed via `allow-scripts auto` and executed with `allow-scripts run`. This guidance will confuse users whose orgs use LavaMoat. Either document the correct LavaMoat workflow, or clarify that this npm config approach is for a different script-blocking mechanism (e.g., npm's own `ignore-scripts` setting).</violation>
<violation number="2" location="docs/docs/getting-started/quickstart.md:203">
P2: `warehouse_test` and `schema_index` are shown without the `/` prefix, unlike every other TUI command in this guide (`/connect`, `/discover`, `/skills`, `/agents`). This inconsistency will confuse readers about how to invoke them. If they are slash commands, add the `/` prefix; if they are prompts the user types as natural-language input, change the title or add a brief note clarifying that.</violation>
<violation number="3" location="docs/docs/getting-started/quickstart.md:218">
P2: The Reviewer agent mode is added to the quickstart and getting-started overview but is completely absent from the canonical agents reference at `docs/docs/configure/agents.md` and from the README. If Reviewer is a real built-in mode, add it to the agents reference with its full permission model so users have a single source of truth. If it's not yet a shipped mode, it shouldn't be documented in the quickstart until the reference docs are also updated.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
| @@ -1,6 +1,6 @@ | |||
| # Getting Started | |||
There was a problem hiding this comment.
P2: This file still contains a full multi-step setup guide (agent modes table, mode-switching commands, etc.) that overlaps with the now-canonical getting-started/quickstart.md. Since the goal is consolidation, consider reducing this page to a short landing/redirect that links to the canonical quickstart, otherwise readers may land here via direct links and see instructions that drift out of sync over time.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/docs/getting-started.md, line 3:
<comment>This file still contains a full multi-step setup guide (agent modes table, mode-switching commands, etc.) that overlaps with the now-canonical `getting-started/quickstart.md`. Since the goal is consolidation, consider reducing this page to a short landing/redirect that links to the canonical quickstart, otherwise readers may land here via direct links and see instructions that drift out of sync over time.</comment>
<file context>
@@ -1,6 +1,6 @@
# Getting Started
-> **New to altimate?** [Start with the 5-minute quickstart](quickstart.md) to go from install to your first analysis in minutes.
+> **New to Altimate Code?** [Start with the quickstart](getting-started/quickstart.md) to go from install to your first analysis.
## Why altimate?
</file context>
| ``` | ||
| | Builder | Read/write | Scaffolding and editing dbt models and SQL. Writes prompt for approval. | | ||
| | Analyst | Read-only | Safe exploration of production data. SQL writes denied entirely. | | ||
| | Reviewer | Read-only | Grading a SQL/dbt change and returning an approve, comment, or request-changes verdict. | |
There was a problem hiding this comment.
P2: The Reviewer agent mode is added to the quickstart and getting-started overview but is completely absent from the canonical agents reference at docs/docs/configure/agents.md and from the README. If Reviewer is a real built-in mode, add it to the agents reference with its full permission model so users have a single source of truth. If it's not yet a shipped mode, it shouldn't be documented in the quickstart until the reference docs are also updated.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/docs/getting-started/quickstart.md, line 218:
<comment>The Reviewer agent mode is added to the quickstart and getting-started overview but is completely absent from the canonical agents reference at `docs/docs/configure/agents.md` and from the README. If Reviewer is a real built-in mode, add it to the agents reference with its full permission model so users have a single source of truth. If it's not yet a shipped mode, it shouldn't be documented in the quickstart until the reference docs are also updated.</comment>
<file context>
@@ -283,171 +195,140 @@ Add a warehouse connection to `.altimate-code/connections.json`:
-```
+| Builder | Read/write | Scaffolding and editing dbt models and SQL. Writes prompt for approval. |
+| Analyst | Read-only | Safe exploration of production data. SQL writes denied entirely. |
+| Reviewer | Read-only | Grading a SQL/dbt change and returning an approve, comment, or request-changes verdict. |
+| Plan | Minimal | Sketching an approach before switching to Builder to execute it. |
</file context>
|
|
||
| ## Step 2: Configure Your LLM | ||
| ```bash title="Terminal" | ||
| npm config set allow-scripts=altimate-code --location=user |
There was a problem hiding this comment.
P2: The suggested command npm config set allow-scripts=altimate-code --location=user does not correspond to how @lavamoat/allow-scripts actually works. LavaMoat uses a "lavamoat": { "allowScripts": { "package-name": true } } allowlist in package.json, managed via allow-scripts auto and executed with allow-scripts run. This guidance will confuse users whose orgs use LavaMoat. Either document the correct LavaMoat workflow, or clarify that this npm config approach is for a different script-blocking mechanism (e.g., npm's own ignore-scripts setting).
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/docs/getting-started/quickstart.md, line 31:
<comment>The suggested command `npm config set allow-scripts=altimate-code --location=user` does not correspond to how `@lavamoat/allow-scripts` actually works. LavaMoat uses a `"lavamoat": { "allowScripts": { "package-name": true } }` allowlist in `package.json`, managed via `allow-scripts auto` and executed with `allow-scripts run`. This guidance will confuse users whose orgs use LavaMoat. Either document the correct LavaMoat workflow, or clarify that this npm config approach is for a different script-blocking mechanism (e.g., npm's own `ignore-scripts` setting).</comment>
<file context>
@@ -1,204 +1,114 @@
-## Step 2: Configure Your LLM
+ ```bash title="Terminal"
+ npm config set allow-scripts=altimate-code --location=user
+ ```
+
</file context>
| > warehouse_test snowflake | ||
| ✓ Connected successfully | ||
| ```text title="In the TUI" | ||
| warehouse_test snowflake |
There was a problem hiding this comment.
P2: warehouse_test and schema_index are shown without the / prefix, unlike every other TUI command in this guide (/connect, /discover, /skills, /agents). This inconsistency will confuse readers about how to invoke them. If they are slash commands, add the / prefix; if they are prompts the user types as natural-language input, change the title or add a brief note clarifying that.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/docs/getting-started/quickstart.md, line 203:
<comment>`warehouse_test` and `schema_index` are shown without the `/` prefix, unlike every other TUI command in this guide (`/connect`, `/discover`, `/skills`, `/agents`). This inconsistency will confuse readers about how to invoke them. If they are slash commands, add the `/` prefix; if they are prompts the user types as natural-language input, change the title or add a brief note clarifying that.</comment>
<file context>
@@ -283,171 +195,140 @@ Add a warehouse connection to `.altimate-code/connections.json`:
-> warehouse_test snowflake
-✓ Connected successfully
+```text title="In the TUI"
+warehouse_test snowflake
</file context>
</details>
🤖 Code Review — OpenCodeReview (Gemini) — No Issues FoundNo supported files changed. |
2 participants
Issue for this PR
Closes #
Type of change
What does this PR do?
Consolidates the docs' three overlapping "getting started" pages into one canonical Quickstart, and fixes a handful of stale command references along the way.
How did you verify your code works?
Running local mkdocs preview
Screenshots / recordings
Checklist
Summary by cubic
Consolidates the three overlapping Getting Started pages into a single, canonical Quickstart and updates command references and agent modes for accuracy. This reduces confusion and points all entry paths to the latest Quickstart.
getting-started/quickstart-new.mdintogetting-started/quickstart.md; removegetting-started/quickstart-new.mdanddocs/quickstart.md.mkdocs.yml) and the Getting Started index button to point to the consolidated Quickstart./skillsreplaces/,/agentreplaces/mode; update examples accordingly.Written for commit 7ae4275. Summary will update on new commits.
Summary by CodeRabbit
/skillsand/agent analyst.