more

docs_sp/community/reporting-a-bug.md

@@ -8,25 +8,62 @@ Help us improve sunnypilot by reporting issues you encounter.
 
 ## Before Reporting
 
-1. Check if the issue has already been reported on [GitHub Issues](https://github.com/sunnypilot/sunnypilot/issues)
-2. Try the latest version — the bug may already be fixed
-3. Check the [Discord Community](https://discord.sunnypilot.ai) for known issues
+!!! warning "Remove Customizations First"
+    If you have any custom modifications (forks, patches, config tweaks), **remove them and reproduce the issue on an official sunnypilot branch** before reporting. This rules out your modifications as the cause and helps maintainers focus on real bugs.
+
+1. **Upgrade** to the latest version — the bug may already be fixed
+2. **Remove customizations** — reproduce on a stock official branch
+3. **Search** [GitHub Issues](https://github.com/sunnypilot/sunnypilot/issues) and the [Discord Community](https://discord.sunnypilot.ai) for known reports
+4. **Preserve the route** — upload raw logs via [Comma Connect](https://connect.comma.ai) and keep the route available
 
 ## What to Include
 
-- **Device info** — Hardware model, software version, branch
+### Required Information
+
+- **Dongle ID** — Your comma Dongle ID (found in **Settings** → **Device** or in Comma Connect)
+- **Route ID** — The route ID from Comma Connect for the drive where the issue occurred
+- **Device info** — Hardware model (C3, C3X, C4), software version, branch
 - **Vehicle info** — Make, model, year
-- **Steps to reproduce** — What you did leading up to the issue
-- **Expected behavior** — What should have happened
-- **Actual behavior** — What actually happened
-- **Logs** — If possible, include relevant log files
+
+### Bug Report Template
+
+Use the following structure when filing your report:
+
+!!! example "Bug Report Format"
+
+    **Title:** One-sentence summary of the issue
+
+    **Description:** 1-2 sentences providing additional context about the problem.
+
+    **Steps to Reproduce:**
+
+    1. Step one
+    2. Step two
+    3. Step three
+
+    **Expected behavior:** What should have happened
+
+    **Actual behavior:** What actually happened
+
+    **Related Links:** Route link, log files, screenshots, or references to related issues
+
+## Pre-Submission Checklist
+
+Before submitting, confirm the following:
+
+- [ ] I am running the latest version of sunnypilot
+- [ ] I have removed all custom modifications and reproduced the issue on an official branch
+- [ ] I have searched existing issues and community channels for duplicates
+- [ ] I have preserved the route and uploaded raw logs via Comma Connect
+- [ ] I have included my comma Dongle ID
+- [ ] I have included the Route ID for the affected drive
 
 ## How to Report
 
 1. Go to [GitHub Issues](https://github.com/sunnypilot/sunnypilot/issues/new)
 2. Use the bug report template
-3. Fill in all requested information
+3. Fill in all requested information using the format above
 4. Submit the issue
 
 !!! tip
-    The more detail you provide, the faster we can diagnose and fix the issue.
+    The more detail you provide, the faster we can diagnose and fix the issue. Incomplete reports without Dongle IDs or route information may be closed.

docs_sp/features/alpha-longitudinal.md

@@ -0,0 +1,39 @@
+---
+title: Alpha Longitudinal
+---
+
+# Alpha Longitudinal
+
+## What It Does
+
+Alpha Longitudinal provides experimental longitudinal (speed and acceleration) control for vehicles that are openpilot-compatible but do not have official sunnypilot longitudinal support. This enables throttle and brake control on cars that would otherwise be limited to lateral (steering) assistance only.
+
+For officially supported vehicles, sunnypilot provides refined longitudinal tuning tailored to each platform. Alpha Longitudinal extends this capability to additional vehicles using a more generalized approach, allowing drivers of these cars to experience full ACC-like functionality through sunnypilot.
+
+## How It Works
+
+Alpha Longitudinal uses the vehicle's existing communication interfaces to send throttle and brake commands, bypassing the need for the vehicle's stock cruise control system. The system:
+
+- Reads vehicle speed, pedal position, and other sensor data through the car's CAN bus
+- Calculates desired acceleration based on the driving model's output
+- Sends throttle and brake commands directly to the vehicle's powertrain controllers
+
+Because this operates outside the vehicle manufacturer's intended cruise control pathway, the tuning is less refined than on officially supported platforms.
+
+## Requirements
+
+!!! info "Requirements"
+    - Vehicle must be openpilot-compatible (listed on the [comma.ai vehicle compatibility list](https://comma.ai/vehicles))
+    - Vehicle does not have official sunnypilot longitudinal support
+    - Feature is experimental and under active development
+
+!!! warning "Alpha Quality Software"
+    This feature is **alpha quality**. Expect rough edges, less smooth acceleration and braking behavior, and less refined stop-and-go performance compared to officially supported vehicles. Longitudinal behavior may vary significantly between vehicle models and driving conditions.
+
+## How to Enable
+
+**Settings** → **sunnypilot** → **Cruise Control** → **Alpha Longitudinal**
+
+## Settings Reference
+
+See [Cruise Control Settings](../settings/cruise.md) for configuration details.

docs_sp/features/auto-lane-change.md

@@ -11,17 +11,21 @@ Automatically executes lane changes when you activate the turn signal. You can c
 ## How It Works
 
 1. Activate your turn signal in the desired direction
-2. Depending on your setting:
+2. The system verifies that clear lane markings are detected by the vision system in the target lane — a lane change will not execute without visible lane lines
+3. The driver monitoring system checks that the driver is attentive before proceeding
+4. Depending on your setting:
     - **Nudge:** Give a light steering nudge to confirm the lane change
     - **Nudgeless:** The lane change begins immediately
     - **Timed (0.5s–3s):** The lane change begins after the configured delay
-3. If BSM Delay is enabled and a vehicle is detected in your blind spot, the lane change waits until the path is clear
+5. If BSM Delay is enabled and a vehicle is detected in your blind spot, the lane change waits until the path is clear
 
 ## Requirements
 
 !!! info "Requirements"
     - Lateral control must be active (sunnypilot must be engaged)
     - Vehicle must be traveling above a minimum speed threshold
+    - Clear lane markings must be visible to the vision system
+    - Driver must be attentive (monitored by the driver monitoring system)
 
 ## How to Enable
 

docs_sp/features/dynamic-experimental-control.md

@@ -8,21 +8,31 @@ title: Dynamic Experimental Control
 
 DEC automatically switches between openpilot's standard and experimental driving modes based on real-time road conditions. Instead of manually toggling between modes, the system chooses the most appropriate mode for the current situation.
 
+To understand DEC, it helps to know the three driving modes in the system:
+
+| Mode | Description |
+|------|-------------|
+| **Chill Mode** (Standard) | The default openpilot driving mode. Follows the lead car and stays in lane at a steady speed. Best suited for highway and open-road driving where stops and complex maneuvers are rare. |
+| **Experimental Mode** | An enhanced mode that can handle stops at traffic lights and stop signs, navigate turns, and respond to more complex urban scenarios. Designed for city driving. |
+| **DEC** | Not a driving mode itself, but a dynamic switcher that automatically selects between Chill and Experimental modes in real time based on road conditions. |
+
 ## How It Works
 
-DEC monitors multiple driving signals and conditions:
+DEC monitors multiple driving signals and conditions to decide which mode is most appropriate at any given moment:
 
-- **Current speed** — Lower speeds suggest city driving
-- **Turn detection** — Upcoming turns may need experimental mode
-- **Stop signs and traffic lights** — Intersections benefit from experimental mode
-- **Road type** — Highway vs. urban driving
+- **Current speed** — Lower speeds suggest city driving, favoring Experimental Mode
+- **Turn detection** — Upcoming turns trigger a switch to Experimental Mode for better handling
+- **Stop signs and traffic lights** — Intersections benefit from Experimental Mode's ability to stop and respond to signals
+- **Road type** — Highway vs. urban driving informs the mode selection
 
 Based on these signals, DEC switches between:
 
-| Mode | Best For |
+| Mode | When DEC Activates It |
 |------|----------|
-| **Standard Mode** | Highway driving with steady speeds and clear lanes |
-| **Experimental Mode** | City driving with stops, turns, and complex intersections |
+| **Chill Mode** | Highway driving with steady speeds, clear lanes, and no upcoming stops or complex intersections |
+| **Experimental Mode** | City driving with stops, turns, traffic lights, and complex intersections where the vehicle needs to slow down or stop |
+
+The switching happens seamlessly — DEC continuously evaluates conditions and transitions between modes without requiring any driver input.
 
 ## Requirements
 

docs_sp/features/icbm.md

@@ -6,18 +6,25 @@ title: Intelligent Cruise Button Management
 
 ## What It Does
 
-ICBM allows sunnypilot to intercept and dynamically manage your vehicle's cruise control button presses. Instead of directly changing the set speed, button presses are routed through sunnypilot's logic, enabling features like Speed Limit Control and Smart Cruise Control on vehicles that don't natively support sunnypilot longitudinal control.
+ICBM allows sunnypilot to intercept and dynamically manage your vehicle's cruise control button presses. Instead of directly changing the set speed, button presses are routed through sunnypilot's logic, enabling features like Speed Limit Assist and Smart Cruise Control on vehicles that don't natively support sunnypilot longitudinal control.
 
 This is particularly useful for vehicles where sunnypilot cannot directly control the gas and brakes — ICBM gives you many of the same benefits by intelligently managing the cruise buttons.
 
+## When to Use
+
+ICBM is designed specifically for vehicles where sunnypilot cannot directly control the throttle and brakes (i.e., no native longitudinal control). On these vehicles, the stock cruise control system still handles all actual acceleration and deceleration. ICBM bridges the gap by intelligently managing cruise button commands so you can still benefit from sunnypilot's speed planning features.
+
 ## How It Works
 
 1. You press the cruise speed button on your steering wheel
 2. ICBM intercepts the button press
 3. sunnypilot applies its logic (speed limits, map curves, etc.) to determine the appropriate speed change
-4. The adjusted command is sent to the vehicle's cruise system
+4. ICBM simulates the corresponding cruise button presses over the CAN bus, sending the adjusted command to the vehicle's stock cruise control system
 
-This happens transparently — from your perspective, the buttons work normally but with smarter behavior.
+This happens transparently — from your perspective, the buttons work normally but with smarter behavior. Under the hood, ICBM is communicating with the vehicle's cruise control module by simulating physical button presses on the CAN bus, which is why it works even on vehicles without direct throttle/brake control.
+
+!!! tip "Safety"
+    ICBM preserves all of your vehicle's stock safety systems. Forward Collision Avoidance (FCA), Automatic Emergency Braking (AEB), and other factory safety features remain fully active and unaffected, since the vehicle's own cruise control system is still performing the actual speed control.
 
 ## Requirements
 
@@ -36,7 +43,7 @@ When ICBM is enabled, the following features become available even on vehicles w
 - **[Smart Cruise Control — Vision](scc-v.md)** — Vision-based adaptive speed adjustments
 - **[Smart Cruise Control — Map](scc-m.md)** — Map-aware speed adjustments
 - **[Custom ACC Increments](custom-acc-increments.md)** — Custom button press speed steps
-- **[Speed Limit Control](speed-limit.md)** — Automatic speed limit matching
+- **[Speed Limit Assist](speed-limit.md)** — Automatic speed limit matching
 
 ## Settings Reference
 

docs_sp/features/mads.md

@@ -12,13 +12,23 @@ This means you can have lane-keeping assistance while controlling the gas and br
 
 ## How It Works
 
-With MADS enabled:
+With MADS enabled, Automatic Lane Centering (ALC) and Adaptive Cruise Control (ACC) can be engaged and disengaged independently. This is the core difference from standard openpilot, where both are always linked together.
 
-- **Steering stays active** even when you cancel cruise control
-- You can engage steering assistance independently of cruise
+- **Steering stays active** even when you cancel cruise control — ALC continues to provide lane centering while you control speed manually
+- **Independent engagement** — you can activate ALC without ACC, or both together, giving you flexible control over which assists are active
 - You choose what happens to steering when cruise disengages (remain active, pause, or fully disengage)
 - You can configure whether the main cruise button also activates steering
 
+### Engagement States
+
+MADS introduces distinct states that reflect how the driver and system interact:
+
+| State | Description |
+|-------|-------------|
+| **Active** | Steering assistance is fully engaged and actively providing lane centering |
+| **Paused** | Steering assistance is temporarily paused (e.g., due to certain conditions) but can resume without re-engaging |
+| **Overriding** | The driver is actively steering, temporarily overriding the system's lateral input. Steering assistance resumes when the driver releases the wheel |
+
 ## Requirements
 
 !!! info "Requirements"
@@ -26,7 +36,7 @@ With MADS enabled:
 
 ## How to Enable
 
-**Settings** → **sunnypilot** → **Steering** → enable **M.A.D.S.**
+**Settings** → **sunnypilot** → **Steering** → enable **MADS**
 
 Then configure the sub-settings in **MADS Settings**.
 

docs_sp/features/nnlc.md

@@ -12,10 +12,17 @@ NNLC replaces the traditional PID or torque-based steering controller with a neu
 
 Instead of using fixed mathematical formulas (PID controller), NNLC uses a machine learning model to calculate steering commands. The neural network has been trained on real-world driving data and can handle a wider variety of driving scenarios with smoother output.
 
+!!! note "Evolution from NNFF"
+    NNLC evolved from **Neural Network FeedForward (NNFF)**, an earlier approach that used a neural network as a feedforward component alongside traditional controllers. NNLC builds on this foundation by giving the neural network full lateral control authority, resulting in improved steering smoothness and adaptability.
+
+!!! info "Vehicle-Specific Training Data"
+    The neural network models are trained on real driving data collected from specific vehicles. Because each vehicle has unique steering characteristics, a dedicated model must be trained for each supported make/model. **Not all vehicles have trained models available** — if no model exists for your vehicle, the NNLC toggle will not appear in settings.
+
 ## Requirements
 
 !!! info "Requirements"
     - Vehicle must not use angle-based steering (`steerControlType` must not be `angle`)
+    - A trained NNLC model must be available for your specific vehicle
     - Mutually exclusive with [Torque Control](torque-control.md) — only one can be active at a time
     - Device must be offroad to enable/disable
 
@@ -24,7 +31,7 @@ Instead of using fixed mathematical formulas (PID controller), NNLC uses a machi
 **Settings** → **sunnypilot** → **Steering** → **Neural Network Lateral Control**
 
 !!! tip
-    Not all vehicles have NNLC models available. If the toggle does not appear, your vehicle may use angle-based steering which is not compatible with NNLC.
+    Not all vehicles have NNLC models available. If the toggle does not appear, your vehicle may use angle-based steering which is not compatible with NNLC, or a trained model may not yet exist for your vehicle.
 
 ## NNLC vs. Torque Control
 

docs_sp/features/osm-maps.md

@@ -6,7 +6,7 @@ title: OSM Maps
 
 ## What It Does
 
-Integrates OpenStreetMap (OSM) data to provide speed limit information, road geometry, and other map attributes. This data powers features like Speed Limit Control and Smart Cruise Control — Map.
+Integrates OpenStreetMap (OSM) data to provide speed limit information, road geometry, and other map attributes. This data powers features like Speed Limit Assist and Smart Cruise Control — Map.
 
 ## How It Works
 
@@ -32,7 +32,7 @@ Integrates OpenStreetMap (OSM) data to provide speed limit information, road geo
 
 ## Features That Use OSM Data
 
-- **[Speed Limit Control](speed-limit.md)** — Reads speed limits from map data
+- **[Speed Limit Assist](speed-limit.md)** — Reads speed limits from map data
 - **[Smart Cruise Control — Map](scc-m.md)** — Uses road geometry for proactive speed adjustment
 
 ## Managing Map Data

docs_sp/features/speed-limit.md

@@ -1,18 +1,50 @@
 ---
-title: Speed Limit Control
+title: Speed Limit Assist
 ---
 
-# Speed Limit Control
+# Speed Limit Assist
 
 ## What It Does
 
-Speed Limit Control detects the current speed limit using map data and can automatically adjust your cruise speed to match. It offers four operating modes ranging from passive information display to active speed management.
+Speed Limit Assist detects the current speed limit using map data and can automatically adjust your cruise speed to match. It offers four operating modes ranging from passive information display to active speed management.
 
 ## How It Works
 
-1. sunnypilot reads speed limit data from downloaded OSM maps
+1. sunnypilot reads speed limit data from one or more configured sources (see below)
 2. Based on your chosen mode, it displays, warns, or actively adjusts your set speed
-3. An optional offset (fixed or percentage) lets you cruise slightly above or below the limit
+3. When a speed limit change is detected, the system either applies it automatically or prompts you to confirm, depending on the confirmation mode
+4. An optional offset (fixed or percentage) lets you cruise slightly above or below the limit
+
+## Speed Limit Sources
+
+Speed Limit Assist can pull speed limit data from multiple sources. You can configure which source takes priority via the **Speed Limit Policy** setting.
+
+| Source | Description |
+|--------|-------------|
+| **OSM Map Data** | Speed limits from downloaded OpenStreetMap data. Requires [OSM Maps](osm-maps.md) to be configured and downloaded. |
+| **Car's Stock Speed Limit Data** | Some vehicles provide speed limit information from their built-in sensors (e.g., Traffic Sign Recognition cameras). Availability depends on the vehicle. |
+| **Navigation Data** | Speed limits embedded in navigation route data, when a navigation destination is active. |
+| **Camera Vision** | Speed limit signs detected by the device's road-facing camera using the vision model. |
+
+!!! tip "Source Priority"
+    When multiple sources detect different speed limits, the **Speed Limit Policy** setting determines which source is used. Configure this under **Settings** → **sunnypilot** → **Cruise Control** → **Speed Limit Policy**.
+
+## Confirmation Modes
+
+When the detected speed limit changes, you can choose how the system responds:
+
+| Mode | Behavior |
+|------|----------|
+| **Auto** | The cruise set speed adjusts automatically when a new speed limit is detected — no driver input required |
+| **User Confirm** | The system displays the new speed limit and waits for the driver to confirm before adjusting the set speed |
+
+## Driver Notifications
+
+Speed Limit Assist provides visual indicators on the driving HUD:
+
+- The currently detected speed limit is shown on the display
+- When a speed limit change is detected, a notification appears showing the new limit
+- In Warning and Assist modes, alerts notify you when you are exceeding the posted limit
 
 ## Requirements
 
@@ -22,7 +54,7 @@ Speed Limit Control detects the current speed limit using map data and can autom
 
 ## How to Enable
 
-**Settings** → **sunnypilot** → **Cruise Control** → **Speed Limit Control**
+**Settings** → **sunnypilot** → **Cruise Control** → **Speed Limit Assist**
 
 ## Operating Modes
 

docs_sp/getting-started/what-is-sunnypilot.md

@@ -11,7 +11,7 @@ sunnypilot is an open-source driver assistance system that enhances your car's e
 - **Adaptive Cruise Control** — Automatically adjusts speed to maintain distance from the car ahead
 - **Lane Centering** — Keeps your car centered in the lane on highways and well-marked roads
 - **Modular Assistive Driving System (MADS)** — Decouple lateral and longitudinal controls for flexible driving
-- **Speed Limit Control** — Automatically adjust speed based on map and sign data
+- **Speed Limit Assist** — Automatically adjust speed based on map and sign data
 - **Neural Network Lateral Control** — AI-based steering for smoother lane keeping
 
 ## How It Works

docs_sp/how-to/preserve-local-changes.md

@@ -0,0 +1,46 @@
+---
+title: Preserve Local Changes
+---
+
+# Preserve Local File Changes on Your comma Device
+
+## Overview
+
+By default, the comma device automatically updates sunnypilot, which overwrites any local file modifications you have made. To keep your local changes across reboots, you must disable automatic updates **before** making modifications.
+
+!!! warning "Complete These Steps First"
+    Local modifications applied **before** completing the steps below will **not** be retained. The automatic update process will overwrite them on the next reboot. Complete all steps first, then make your changes.
+
+## Steps
+
+### 1. Enable Advanced Controls
+
+Navigate to **Settings** → **Developer** → **Show Advanced Controls** and toggle it **ON**.
+
+This reveals additional settings options that are hidden by default, including the update toggle.
+
+### 2. Disable Updates
+
+Navigate to **Settings** → **Software** → **Disable Updates** and toggle it **ON**.
+
+This prevents the device from automatically pulling and applying updates from the remote branch.
+
+### 3. Reboot the Device
+
+Navigate to **Settings** → **Device** → **Reboot** to restart the device.
+
+The reboot applies the settings change and ensures the update service is fully stopped.
+
+### 4. Verify
+
+After the device restarts:
+
+1. Confirm that your settings from steps 1 and 2 are still active
+2. Make your desired local file changes (via SSH or other methods)
+3. Reboot again to confirm your changes persist
+
+!!! info "Automatic Updates Are Paused"
+    With updates disabled, your device will **not** receive new sunnypilot releases automatically. You will need to re-enable updates manually when you want to update to a newer version. To re-enable, reverse step 2: **Settings** → **Software** → **Disable Updates** → **OFF**.
+
+!!! tip "When to Use This"
+    This is useful for testing custom parameter values, experimental configurations, or developer modifications that you want to persist across device reboots without being overwritten by the update system.

docs_sp/how-to/share-a-route.md

@@ -0,0 +1,58 @@
+---
+title: How to Share a Route
+---
+
+# How to Share a Route
+
+## Overview
+
+Sharing driving routes is essential for debugging issues, getting support, and helping developers improve sunnypilot. Routes are shared through [comma Connect](https://connect.comma.ai), comma's web-based route management tool.
+
+## Step 1: Prepare the Route
+
+Before sharing, ensure the route data is fully uploaded and preserved.
+
+### Upload Raw Logs
+
+1. Go to [connect.comma.ai](https://connect.comma.ai)
+2. Select the route you want to share
+3. Open the **Files** tab
+4. Upload the raw logs for the route
+
+!!! warning "Upload Before Sharing"
+    Raw logs must be **fully uploaded** before they can be reviewed by others. If the logs are not uploaded, reviewers will not have access to the detailed data needed for debugging.
+
+### Preserve the Route
+
+Routes are automatically deleted after a retention period. To prevent this:
+
+1. Select the route in comma Connect
+2. Click **More info**
+3. Toggle **Preserved** to **ON**
+
+This ensures the route remains available for as long as you need it.
+
+## Step 2: Choose Sharing Method
+
+### Option A: Public Route (Recommended)
+
+The simplest way to share a single route for support or debugging.
+
+1. Select the route in comma Connect
+2. Toggle **Public access** to **ON**
+3. Copy the **Route ID** from the route details
+4. Share the Route ID in the support channel or forum thread
+
+!!! info "Privacy"
+    Making a route public means **anyone with the Route ID can access it**. Route data includes GPS coordinates and video footage. For privacy, start and end your recorded drives at public places such as parking lots or gas stations. Avoid starting or ending at your home, workplace, or other private locations.
+
+### Option B: Device Sharing
+
+Grants another user access to **all routes** on your device. Use this when ongoing collaboration is needed.
+
+1. Rename your device with your vehicle's **Year/Make/Model** and your **username** (e.g., "2023 Hyundai Ioniq 6 - jasonwen")
+2. Go to device settings in comma Connect
+3. Share the device via the other user's email address
+
+!!! tip "When to Use Device Sharing"
+    Device sharing is best for long-term collaboration with a developer or when multiple routes need to be reviewed. For one-off support requests, prefer Option A (Public Route) to limit access to only the relevant route.

docs_sp/references/branch-definitions.md

@@ -4,24 +4,73 @@ title: Branch Definitions
 
 # Branch Definitions
 
-Understanding sunnypilot's branching strategy.
+Understanding sunnypilot's branching strategy and device compatibility.
 
-## Branch Types
+!!! tip "Calling All Testers"
+    Testers, even without software development experience, are encouraged to run **staging** or **dev** branches and report issues. Your feedback is invaluable for improving sunnypilot before each release.
 
-| Branch | Stability | Purpose |
-|--------|----------|---------|
-| Release | Stable | Production-ready releases |
-| Staging | Beta | Pre-release testing |
-| Dev | Alpha | Active development |
-| Main | Development | Latest code, may be unstable |
+---
 
-## Naming Convention
+## Release Branches
 
-Branches follow the pattern: `<type>-<version>` (e.g., `release-0.9.x`)
+### release-tizi (C3X)
+
+- **Stability:** :material-check-circle: Highly stable
+- **Target devices:** Comma 3X (TIZI)
+- **Description:** The recommended branch for most Comma 3X users. This branch contains thoroughly tested features and fixes that have passed through staging and dev. Use this for daily driving.
+
+### release-tici (C3)
+
+- **Stability:** Not yet available
+- **Target devices:** Comma Three (TICI)
+- **Description:** A dedicated release branch for Comma Three is not yet available. C3 users should use `staging-tici` in the meantime.
+
+---
+
+## Pre-Release Branches
+
+### staging (C4 / C3X)
+
+- **Stability:** :material-alert-circle: Generally stable
+- **Target devices:** Comma Four (MICI), Comma 3X (TIZI)
+- **Description:** Pre-release testing branch. Features here are being validated before promotion to a release branch. Suitable for users who want early access to upcoming features and are willing to report issues.
+
+### staging-tici (C3)
+
+- **Stability:** :material-alert-circle: Generally stable
+- **Target devices:** Comma Three (TICI)
+- **Description:** Pre-release testing branch for Comma Three. Provides the most stable experience currently available for C3 devices.
+
+---
+
+## Development Branches
+
+### dev (C4 / C3X)
+
+- **Stability:** :material-close-circle: Least stable
+- **Target devices:** Comma Four (MICI), Comma 3X (TIZI)
+- **Description:** Active development branch with the latest features and fixes. Intended for testers and developers who want to try the newest changes and provide feedback. Expect occasional issues.
+
+### master (C4 / C3X)
+
+- **Stability:** :material-close-circle: Unstable
+- **Target devices:** Comma Four (MICI), Comma 3X (TIZI)
+- **Description:** The primary development branch where pull requests are merged. Not recommended for daily driving. Use this branch if you are contributing code to sunnypilot.
+
+### master-dev (C4 / C3X)
+
+- **Stability:** :material-close-circle: Unstable
+- **Target devices:** Comma Four (MICI), Comma 3X (TIZI)
+- **Description:** CI branch used to build prebuilt artifacts for the `dev` branch. Not intended for direct installation.
+
+---
 
 ## Which Branch Should I Use?
 
-- **Daily driving** → Release branch
-- **Want new features early** → Staging branch
-- **Helping test** → Dev branch
-- **Contributing code** → Main branch
+| Use Case | Recommended Branch |
+|----------|--------------------|
+| Daily driving (C3X) | `release-tizi` |
+| Daily driving (C3) | `staging-tici` |
+| Early access to features (C4/C3X) | `staging` |
+| Testing and feedback (C4/C3X) | `dev` |
+| Contributing code | `master` |

docs_sp/references/recommended-branches.md

@@ -4,18 +4,43 @@ title: Recommended Branches
 
 # Recommended Branches
 
-Choose the right branch for your needs.
-
-## For Most Users
-
-Use the latest **stable** release branch. This provides the best balance of features and reliability.
-
-## For Testers
-
-Use the **staging** or **dev** branch to test upcoming features and provide feedback.
-
-## For Developers
-
-Use the **main** branch for the latest development code.
+!!! warning
+    Please only install the branches listed below. All other branches are experimental development branches and are not intended for general use.
 
 See [Branch Definitions](branch-definitions.md) for detailed descriptions of each branch type.
+
+---
+
+## Comma Four (C4 / MICI)
+
+| Branch | Install URL | Stability |
+|--------|------------|-----------|
+| staging | `staging.sunnypilot.ai` | Generally stable, pre-release testing |
+| dev | `dev.sunnypilot.ai` | Least stable, for testers and developers |
+
+---
+
+## Comma 3X (C3X / TIZI)
+
+| Branch | Install URL | Stability |
+|--------|------------|-----------|
+| release-tizi | `release.sunnypilot.ai` | Highly stable, recommended for most users |
+| staging | `staging.sunnypilot.ai` | Generally stable, pre-release testing |
+| dev | `dev.sunnypilot.ai` | Least stable, for testers and developers |
+
+---
+
+## Comma Three (C3 / TICI)
+
+| Branch | Install URL | Stability |
+|--------|------------|-----------|
+| staging-tici | `staging.sunnypilot.ai` | Pre-release testing for C3 |
+
+!!! note
+    A dedicated release branch for Comma Three (`release-tici`) is not yet available. Use `staging-tici` for the most stable C3 experience.
+
+---
+
+## Changelogs
+
+For detailed changelogs of each release, see the [sunnypilot GitHub Releases](https://github.com/sunnypilot/sunnypilot/releases) page.

docs_sp/safety/driver-responsibility.md

@@ -0,0 +1,56 @@
+---
+title: Driver Responsibility & Level 2 ADAS
+---
+
+# Driver Responsibility & Level 2 ADAS
+
+!!! danger "You Are Always Responsible"
+    sunnypilot is **NOT** a self-driving system. You are legally and morally responsible for the vehicle at all times. No feature in sunnypilot removes or reduces your obligation to drive safely.
+
+## What is Level 2 ADAS
+
+sunnypilot is classified as a **Level 2 Advanced Driver Assistance System (ADAS)** per the SAE J3016 standard for driving automation. The SAE levels define increasing degrees of automation:
+
+| SAE Level | Name | Driver Role |
+|-----------|------|-------------|
+| 0 | No Automation | Driver performs all tasks |
+| 1 | Driver Assistance | System controls steering OR speed, not both |
+| **2** | **Partial Automation** | **System controls steering AND speed; driver must supervise** |
+| 3 | Conditional Automation | System handles driving in limited scenarios; driver must be ready |
+| 4–5 | High/Full Automation | System handles all driving tasks in defined conditions |
+
+sunnypilot operates at **Level 2** only. It can control steering and speed simultaneously, but the human driver must remain fully engaged at all times.
+
+## What This Means
+
+At Level 2, the system provides assistance — not autonomy. Specifically:
+
+- The system **can** control steering, acceleration, and braking simultaneously
+- The system **cannot** handle unexpected situations, edge cases, or complex scenarios reliably
+- The **driver** is the fallback for every situation the system cannot handle
+- The **driver** bears full legal responsibility for the vehicle's operation
+
+## Driver Obligations
+
+As the operator of a Level 2 ADAS vehicle, you must:
+
+- **Keep your hands on the steering wheel** at all times
+- **Keep your eyes on the road** and maintain situational awareness
+- **Be ready to intervene immediately** — the system can disengage or behave unexpectedly without warning
+- **Follow all traffic laws** — the system does not replace your judgment or legal obligations
+- **Never rely on the system** as a substitute for attentive driving
+
+## NHTSA Guidance
+
+The National Highway Traffic Safety Administration (NHTSA) classifies Level 2 systems as requiring **full driver engagement**. NHTSA's position is clear:
+
+- Level 2 systems are **driver support features**, not automated driving systems
+- The driver must be able to perform the complete driving task at all times
+- Manufacturers and operators share responsibility for safe use of these systems
+
+For more information, see [NHTSA's guidance on automated vehicles](https://www.nhtsa.gov/technology-innovation/automated-vehicles-safety).
+
+## Related Pages
+
+- [Safety Information](safety.md) — General safety guidelines and system limitations
+- [Prohibited Modifications](prohibited-modifications.md) — Modifications and uses that are not allowed

docs_sp/safety/prohibited-modifications.md

@@ -6,17 +6,33 @@ title: Prohibited Modifications
 
 Certain modifications to sunnypilot are prohibited for safety reasons.
 
-!!! danger
-    Modifying safety-critical components can result in dangerous driving behavior, vehicle damage, or personal injury.
+!!! danger "Zero Tolerance Policy"
+    All official sunnypilot branches strictly adhere to [comma.ai's safety policy](https://github.com/commaai/openpilot/blob/master/docs/SAFETY.md). Any changes against this policy will result in your fork and your device being **banned from both comma.ai and sunnypilot channels**.
 
-## What Is Prohibited
+## Panda Safety Violations
+
+The following modifications to panda safety logic are strictly prohibited:
+
+- **Preventing longitudinal disengagement on brake** — The system must disengage longitudinal control when the brake pedal is pressed. Overriding this behavior is prohibited.
+- **Automatic re-engagement after braking** — Automatically re-engaging longitudinal control upon brake release without explicit driver input is prohibited.
+- **Operating with cruise main off** — The system must disengage when cruise control main is in the off state. Bypassing this check is prohibited.
+- **Removing steering torque limits** — Modifying or removing the safety-enforced steering torque limits is prohibited.
+- **Bypassing vehicle safety interlocks** — Disabling or circumventing any vehicle-level safety interlock is prohibited.
+
+## Driver Monitoring Violations
+
+- **Reducing or weakening driver monitoring parameters** — Any modification that lowers the sensitivity, delays the response, or otherwise weakens the driver monitoring system is prohibited. This includes increasing allowed distraction time, reducing alert thresholds, or disabling monitoring entirely.
+
+## General Prohibitions
 
 - Disabling or bypassing driver monitoring
-- Removing steering torque limits
 - Modifying braking safety thresholds
-- Bypassing vehicle safety interlocks
 - Any modification that reduces the driver's ability to take manual control
 
 ## Why These Restrictions Exist
 
 These restrictions protect you, your passengers, and other road users. Safety-critical systems have been carefully tuned and tested. Unauthorized modifications can have unpredictable and dangerous consequences.
+
+!!! info "References"
+    - [comma.ai Safety Policy](https://github.com/commaai/openpilot/blob/master/docs/SAFETY.md)
+    - [Official sunnypilot Branches](../references/recommended-branches.md)

docs_sp/settings/cruise.md

@@ -18,7 +18,7 @@ Settings for adaptive cruise control behavior, including intelligent button mana
 | **Type** | Toggle (On/Off) |
 | **Default** | Off |
 
-Allows sunnypilot to dynamically manage cruise speed by intercepting button presses on the steering wheel. When enabled, speed adjustments are handled intelligently to support features like Speed Limit Control.
+Allows sunnypilot to dynamically manage cruise speed by intercepting button presses on the steering wheel. When enabled, speed adjustments are handled intelligently to support features like Speed Limit Assist.
 
 !!! info "Requirements"
     - Vehicle must support ICBM (shown only when `intelligentCruiseButtonManagementAvailable` is true in car parameters)
@@ -120,9 +120,9 @@ Automatically switches between openpilot and experimental mode based on driving
 
 ---
 
-## Speed Limit Control
+## Speed Limit Assist
 
-Speed Limit Control settings are located in a sub-panel within Cruise Control. See the dedicated [Speed Limit Settings](speed-limit.md) page for full details.
+Speed Limit Assist settings are located in a sub-panel within Cruise Control. See the dedicated [Speed Limit Settings](speed-limit.md) page for full details.
 
 ---
 

docs_sp/settings/osm.md

@@ -75,5 +75,5 @@ The panel displays the following read-only information:
 ## Related Features
 
 - [OSM Maps](../features/osm-maps.md)
-- [Speed Limit Control](../features/speed-limit.md)
+- [Speed Limit Assist](../features/speed-limit.md)
 - [Smart Cruise Control — Map](../features/scc-m.md)

docs_sp/settings/speed-limit.md

@@ -6,7 +6,7 @@ title: Speed Limit Settings
 
 Configure how sunnypilot responds to detected speed limits from maps, signs, and navigation data.
 
-**Location:** Settings → sunnypilot → Cruise Control → Speed Limit Control
+**Location:** Settings → sunnypilot → Cruise Control → Speed Limit Assist
 
 ---
 
@@ -80,5 +80,5 @@ Speed Limit Policy is a sub-panel that controls the priority of speed limit data
 
 ## Related Features
 
-- [Speed Limit Control](../features/speed-limit.md)
+- [Speed Limit Assist](../features/speed-limit.md)
 - [OSM Maps](../features/osm-maps.md)

docs_sp/settings/steering.md

@@ -10,7 +10,7 @@ Configure lateral (steering) control behavior including MADS, lane changes, and
 
 ---
 
-## M.A.D.S. (Modular Assistive Driving System)
+## MADS (Modular Assistive Driving System)
 
 | Property | Value |
 |----------|-------|

docs_sp/settings/vehicle/tesla.md

@@ -46,8 +46,8 @@ See [MADS Settings](../mads.md) for details on these settings.
 
 ---
 
-## Speed Limit Control Restrictions
+## Speed Limit Assist Restrictions
 
-On **release branches**, the Speed Limit Assist mode is disabled for Tesla vehicles. Info and Warning modes remain available.
+On **release branches**, Speed Limit Assist mode is disabled for Tesla vehicles. Info and Warning modes remain available.
 
 See [Speed Limit Settings](../speed-limit.md) for details.

docs_sp/technical/hyundai-longitudinal-tuning.md

@@ -0,0 +1,93 @@
+---
+title: Hyundai Longitudinal Tuning
+---
+
+# Hyundai Longitudinal Tuning Implementation
+
+!!! info "Audience"
+    This is advanced technical documentation intended for developers and contributors. End users do not need to understand these details to use sunnypilot.
+
+## Overview
+
+sunnypilot implements custom longitudinal (speed/acceleration) control tuning for Hyundai, Kia, and Genesis (HKG) vehicles. The goal is to produce smooth, comfortable acceleration and deceleration behavior that matches or exceeds the quality of the vehicle's stock adaptive cruise control system.
+
+This tuning layer sits between the driving model's desired acceleration output and the actual commands sent to the vehicle, shaping the acceleration profile to meet comfort and safety constraints.
+
+## Design Goals
+
+The longitudinal tuning for HKG vehicles targets the following objectives:
+
+- **Comfort**: Minimize abrupt speed changes that cause passenger discomfort
+- **Smoothness**: Produce acceleration and deceleration curves that feel natural and predictable
+- **Safety**: Maintain appropriate following distances and stopping margins
+- **Consistency**: Deliver repeatable behavior across different driving conditions
+- **Parity with stock**: Match or exceed the refinement of the factory ACC system
+
+## Standards Reference
+
+The tuning implementation references **ISO 15622** (Intelligent Transport Systems — Adaptive Cruise Control Systems — Performance Requirements and Test Procedures). This standard defines:
+
+- Maximum and minimum acceleration/deceleration rates for ACC systems
+- Response time requirements for speed changes
+- Following distance behavior and time-gap requirements
+- Performance criteria for cut-in and cut-out scenarios
+
+## Key Concepts
+
+### Jerk Limiting
+
+**Jerk** is the rate of change of acceleration (m/s^3). High jerk values produce the "jerky" feeling passengers experience during abrupt speed changes.
+
+The tuning system limits jerk to keep acceleration transitions smooth:
+
+- Acceleration onset is ramped gradually rather than applied instantly
+- Deceleration transitions are similarly smoothed to avoid sudden braking sensations
+- Different jerk limits apply to different driving scenarios (e.g., following vs. stopping)
+
+### Parabolic Approach
+
+When decelerating to a stop or approaching a slower lead vehicle, the system uses **parabolic deceleration profiles** rather than constant-rate braking. This means:
+
+- Deceleration starts gently and increases progressively
+- As the vehicle nears the target speed or stop point, deceleration tapers off
+- The result is a smooth, gradual stop rather than an abrupt one
+- This mimics how experienced human drivers naturally brake
+
+### Speed-Dependent Tuning
+
+Longitudinal behavior is tuned differently across speed ranges:
+
+| Speed Range | Tuning Focus |
+|-------------|--------------|
+| Low speed (stop-and-go) | Smooth stop/start transitions, creep management |
+| City speeds | Responsive acceleration, comfortable following |
+| Highway speeds | Gentle speed adjustments, fuel-efficient cruising |
+
+Parameters such as acceleration limits, jerk bounds, and following distance gains are adjusted based on the current vehicle speed to optimize behavior for each regime.
+
+### Lead Vehicle Response
+
+The system adapts its behavior based on the lead vehicle's actions:
+
+- **Lead accelerating**: Gradual acceleration to maintain gap without aggressive throttle
+- **Lead decelerating**: Proportional braking response with jerk limiting
+- **Lead cut-in**: Timely but smooth deceleration to establish safe following distance
+- **Lead cut-out**: Controlled acceleration to resume set speed
+
+## Technical Parameters
+
+The tuning system uses several categories of parameters:
+
+- **Acceleration bounds**: Maximum and minimum acceleration values at different speeds
+- **Jerk limits**: Rate-of-change constraints for both positive and negative acceleration
+- **Time constants**: Filtering and smoothing time constants for acceleration commands
+- **Following distance gains**: Speed-dependent proportional and derivative gains for gap control
+- **Stopping parameters**: Deceleration profiles and creep behavior for stop-and-go
+
+!!! tip "Contributing"
+    If you are working on longitudinal tuning for HKG vehicles, test changes thoroughly across multiple driving scenarios — highway cruising, city stop-and-go, and lead vehicle cut-in/cut-out — before submitting a pull request.
+
+## Related Pages
+
+- [Cruise Control Settings](../settings/cruise.md) — User-facing cruise control configuration
+- [Hyundai Vehicle Settings](../settings/vehicle/hyundai.md) — Hyundai-specific settings reference

mkdocs-sp.yml

@@ -101,7 +101,8 @@ nav:
           - Smart Cruise Control - Map: features/scc-m.md
           - Custom ACC Increments: features/custom-acc-increments.md
           - Dynamic Experimental Control: features/dynamic-experimental-control.md
-          - Speed Limit Control: features/speed-limit.md
+          - Speed Limit Assist: features/speed-limit.md
+          - Alpha Longitudinal: features/alpha-longitudinal.md
       - Steering:
           - Modular Assistive Driving System: features/mads.md
           - Neural Network Lateral Control: features/nnlc.md
@@ -136,9 +137,15 @@ nav:
       - Workflow: community/workflow.md
       - Reporting a Bug: community/reporting-a-bug.md
       - Discord Community: https://discord.sunnypilot.ai
+  - How-To Guides:
+      - Share a Route: how-to/share-a-route.md
+      - Preserve Local File Changes: how-to/preserve-local-changes.md
   - Safety:
       - Safety Information: safety/safety.md
+      - Driver Responsibility & L2 ADAS: safety/driver-responsibility.md
       - Prohibited Modifications: safety/prohibited-modifications.md
+  - Technical Reference:
+      - Hyundai Longitudinal Tuning: technical/hyundai-longitudinal-tuning.md
   - References:
       - Recommended Branches: references/recommended-branches.md
       - Branch Definitions: references/branch-definitions.md