fix(docs): enforce trailing-newline and whitespace-safe formatting in Projects docs

docs/docs.json

@@ -42,7 +42,24 @@
             "group": "Projects",
             "icon": "folder-tree",
             "pages": [
-              "projects/projects"
+              "projects/introduction",
+              "projects/quickstart",
+              "projects/project-concepts",
+              "projects/creating-first-project",
+              {
+                "group": "Guides",
+                "pages": [
+                  "projects/guides/managing-project-members",
+                  "projects/guides/deployment-settings-and-autoscaling"
+                ]
+              },
+              {
+                "group": "Reference",
+                "pages": [
+                  "projects/reference/project-tabs-reference"
+                ]
+              },
+              "projects/troubleshooting"
             ]
           },
           {

docs/projects/creating-first-project.mdx

@@ -0,0 +1,85 @@
+---
+title: "Creating Your First Project"
+description: "Step-by-step guide to create a project and operationally prepare it"
+---
+
+This guide walks through a practical setup flow for your first Bud AI Foundry project.
+
+## Before You Start
+
+Make sure you have permission to create and manage projects in your workspace.
+
+## 1. Create the Project Record
+
+1. Open **Projects**.
+2. Click **+ Project**.
+3. Fill in:
+   - **Name**: `Fraud Detection Assistant`
+   - **Description**: `Project for fraud triage model APIs`
+   - **Tags**: `risk`, `production`, `llm`
+4. Click **Create**.
+
+## 2. Add Team Members
+
+1. Open the new project.
+2. Click **Share/Invite**.
+3. Add users and assign view/manage scopes.
+4. Confirm invited members appear in project access controls.
+
+## 3. Deploy a Model in the Project
+
+1. Go to the **Deployments** tab.
+2. Create a deployment and select:
+   - Model source (for example Hugging Face or cloud provider)
+   - Target cluster
+   - Deployment name
+3. Save and wait for deployment status to become healthy/ready.
+
+## 4. Configure Deployment Settings
+
+Open deployment **Settings** and configure:
+
+- **Rate limits** to protect capacity
+- **Retry/fallback** rules for resiliency
+- **Autoscaling** minimum/maximum replicas and trigger metrics
+
+## 5. Add Route Logic
+
+1. Open the **Routes** tab.
+2. Create a route and select strategy (for example simple shuffle or least busy).
+3. Attach one or more eligible deployments.
+4. Save and validate route status.
+
+## 6. Validate Analytics and Observability
+
+1. Open **Analytics** to inspect baseline latency/throughput.
+2. Open **Observability** to verify runtime event visibility.
+3. Confirm traffic and error patterns are visible before broad rollout.
+
+## 7. Apply Guardrails
+
+1. Open **Guardrails**.
+2. Attach required safety or compliance policies.
+3. Verify policies are active and aligned with project requirements.
+
+## Completion Checklist
+
+- [x] Project created with metadata
+- [x] Team members invited with scoped permissions
+- [x] At least one deployment running
+- [x] Route configured to active deployment
+- [x] Analytics and observability validated
+- [x] Guardrails applied
+
+## End-to-End Setup Flow
+
+```mermaid
+flowchart TD
+    A[Create Project] --> B[Add Members]
+    B --> C[Create Deployment]
+    C --> D[Configure Settings]
+    D --> E[Create Route]
+    E --> F[Validate Analytics & Observability]
+    F --> G[Enable Guardrails]
+```
+

docs/projects/guides/deployment-settings-and-autoscaling.mdx

@@ -0,0 +1,51 @@
+---
+title: "Deployment Settings and Autoscaling"
+description: "Configure reliability, rate limits, and SLO-aware scaling inside a project"
+---
+
+## Overview
+
+Project deployments support operational controls for reliability and cost efficiency.
+
+## Configure Rate Limiting
+
+In deployment **Settings**:
+
+1. Enable **Rate Limit**.
+2. Choose an algorithm (fixed, sliding, or token bucket based on availability).
+3. Set request thresholds and burst behavior.
+4. Save and verify limits in runtime behavior.
+
+## Configure Retry and Fallback
+
+1. Set retry limits for transient failures.
+2. Add fallback deployment targets when available.
+3. Save and test with controlled failure scenarios.
+
+## Enable Autoscaling
+
+1. Toggle **Autoscaling** on.
+2. Set minimum and maximum replicas.
+3. Select trigger metrics (for example queue depth or latency-aligned signals).
+4. Configure stabilization windows/policies to avoid rapid oscillation.
+5. Save and monitor scale events in analytics/observability.
+
+## Best Practices
+
+<Check>Start with conservative max replica values, then scale after observing load.</Check>
+<Check>Pair autoscaling thresholds with realistic SLO targets.</Check>
+<Check>Use fallback only when secondary deployments are validated.</Check>
+<Check>Review settings after model or traffic profile changes.</Check>
+
+## Deployment Controls Flow
+
+```mermaid
+flowchart LR
+    A[Deployment Settings] --> B[Rate Limiting]
+    A --> C[Retry & Fallback]
+    A --> D[Autoscaling]
+    D --> E[Min/Max Replicas]
+    D --> F[SLO Trigger Metrics]
+    D --> G[Stabilization Policies]
+```
+

docs/projects/guides/managing-project-members.mdx

@@ -0,0 +1,52 @@
+---
+title: "Managing Project Members"
+description: "Invite collaborators and manage project-level permissions"
+---
+
+## Overview
+
+Project member management lets you control who can view and operate project resources.
+
+## Invite Members
+
+1. Open the target project.
+2. Click **Share** or **Invite**.
+3. Add one or more users.
+4. Assign permission scope (view/manage).
+5. Save and confirm invite status.
+
+## Update Permissions
+
+1. Open project member management.
+2. Locate the user.
+3. Change role/scope as needed.
+4. Save and verify updated access.
+
+## Remove Members
+
+1. Open project member management.
+2. Select a user.
+3. Click **Remove**.
+4. Confirm the action.
+
+## Recommended Access Model
+
+- Grant **manage** only to platform owners and on-call operators.
+- Grant **view** to stakeholders who need visibility but not mutation rights.
+- Review membership regularly, especially after team changes.
+
+## Related Docs
+
+- [Project Concepts](/projects/project-concepts)
+- [Troubleshooting](/projects/troubleshooting)
+
+## Member Management Workflow
+
+```mermaid
+flowchart LR
+    A[Open Project] --> B[Invite Member]
+    B --> C[Assign Scope]
+    C --> D[Review Access]
+    D --> E[Update or Remove Member]
+```
+

docs/projects/introduction.mdx

@@ -0,0 +1,73 @@
+---
+title: "Introduction to Projects"
+description: "Organize deployments, teams, routes, and governance in a single workspace"
+---
+
+## Overview
+
+The **Projects** module is the operational home for delivery teams in Bud AI Foundry. A project groups the assets you build and run—models, deployments, agents, routes, analytics, and guardrails—so teams can work in one governed workspace instead of jumping between tools.
+
+Use projects to define ownership boundaries, manage access, and keep production operations auditable.
+
+## Why Projects Matter
+
+**Unified AI Delivery Workspace**
+Track everything for an application in one place: deployment lifecycle, prompt/agent assets, routing, and runtime analytics.
+
+**Collaboration with RBAC**
+Project-level permissions control who can view, manage, deploy, edit routes, and configure settings.
+
+**Built-in Governance**
+Guardrails, observability, and deletion safeguards help teams enforce policy and reduce production risk.
+
+**Cost and Performance Control**
+Project analytics and deployment settings support SLO-aware tuning, autoscaling, and reliability controls.
+
+## Project Lifecycle Flow
+
+```mermaid
+flowchart LR
+    A[Create Project] --> B[Invite Members]
+    B --> C[Deploy Models]
+    C --> D[Configure Routes]
+    D --> E[Monitor Analytics & Observability]
+    E --> F[Apply Guardrails]
+    F --> G[Iterate with SLO-aware Scaling]
+```
+
+## Core Areas Inside a Project
+
+| Area | What you can do |
+|------|------------------|
+| **Deployments** | Create endpoints, inspect status, tune scaling and limits |
+| **Agents** | Manage project-linked agents and prompts |
+| **Routes** | Define traffic strategy across one or more deployments |
+| **Analytics** | Track latency, throughput, and utilization trends |
+| **Clusters** | View target infrastructure and placement context |
+| **Observability** | Inspect inference activity and operational signals |
+| **Guardrails** | Apply and monitor safety/compliance controls |
+
+## Typical Project Workflow
+
+1. **Create a project** with clear name, description, and tags.
+2. **Invite collaborators** with view/manage permissions.
+3. **Deploy models** into project-scoped endpoints.
+4. **Configure routing** and reliability controls.
+5. **Monitor analytics** and tune scaling/performance.
+6. **Harden governance** with guardrails and access reviews.
+
+## Getting Started
+
+<CardGroup cols={3}>
+  <Card title="Quick Start" icon="play" href="/projects/quickstart">
+    Create and configure your first project in minutes
+  </Card>
+
+  <Card title="Project Concepts" icon="book" href="/projects/project-concepts">
+    Understand structure, permissions, and module tabs
+  </Card>
+
+  <Card title="Step-by-Step Tutorial" icon="graduation-cap" href="/projects/creating-first-project">
+    Full walkthrough from project setup to deployment readiness
+  </Card>
+</CardGroup>

docs/projects/project-concepts.mdx

@@ -0,0 +1,75 @@
+---
+title: "Project Concepts"
+description: "Understand project structure, permissions, and operational boundaries"
+---
+
+## Project as an Operational Boundary
+
+A project is the primary boundary for organizing AI assets and operations in Bud AI Foundry. Most day-to-day activities—deployment lifecycle, routing, analytics, and safety controls—are scoped to a project.
+
+## Core Concepts
+
+### 1. Project Metadata
+
+Each project has a name, icon, description, and tags. Metadata helps teams discover and classify workloads across environments.
+
+### 2. Permission Scope
+
+Project permissions determine who can:
+
+- View project assets
+- Manage project settings and members
+- Create/edit/delete deployments and routes (depending on role scope)
+
+### 3. Tab-Based Functional Areas
+
+Project detail pages are organized into focused tabs for operational clarity:
+
+- **Deployments**: endpoint lifecycle and runtime settings
+- **Agents**: prompt- and agent-centric assets
+- **Routes**: traffic distribution strategy
+- **Analytics**: performance and capacity trends
+- **Clusters**: infrastructure placement context
+- **Observability**: runtime traces, logs, and request signals
+- **Guardrails**: policy and safety controls
+
+### 4. Safe Lifecycle Management
+
+Project deletion is intentionally guarded. If active deployments are present, deletion can be blocked until dependencies are removed or paused.
+
+### 5. SLO-Aware Scaling
+
+Deployment settings can be tuned with SLO-aligned autoscaling signals (for example latency or queue-related metrics), allowing teams to balance performance and cost.
+
+## How Projects Relate to Other Modules
+
+| Module | Relationship to Projects |
+|--------|---------------------------|
+| **Models** | Models are selected and deployed into project-scoped endpoints |
+| **Deployments** | Deployments are managed and governed within projects |
+| **Routes** | Routing policies are configured from project context |
+| **Observability** | Monitoring is filtered by project for faster diagnostics |
+| **User Management** | Access is granted to project resources via RBAC |
+
+## Best Practices
+
+<Check>Use one project per product, tenant, or major workload boundary.</Check>
+<Check>Keep project tags consistent for reporting and governance.</Check>
+<Check>Grant manage permissions to a minimal set of operators.</Check>
+<Check>Review analytics and observability before scaling or route changes.</Check>
+<Check>Enable guardrails early in lifecycle, not only after incidents.</Check>
+
+## Concept Map
+
+```mermaid
+flowchart LR
+    A[Project Boundary] --> B[Permissions]
+    A --> C[Operational Tabs]
+    A --> D[Governance]
+    C --> C1[Deployments]
+    C --> C2[Routes]
+    C --> C3[Analytics]
+    D --> D1[Guardrails]
+    D --> D2[Deletion Safeguards]
+```
+

docs/projects/projects.mdx

@@ -344,4 +344,4 @@ Publishing sets token pricing (input/output, USD per selected token block) and m
 
 **Q11. How does autoscaling work for deployments?**
 
-Autoscaling is configured in the deployment Settings tab. Enable it to set min/max replicas, choose SLO-driven metrics (queue depth, TTFT, TPOT, end-to-end latency, embedding/classify latency), and optionally add schedule hints or predictive scaling. These controls let the deployment scale intelligently against performance and cost objectives.
+Autoscaling is configured in the deployment Settings tab. Enable it to set min/max replicas, choose SLO-driven metrics (queue depth, TTFT, TPOT, end-to-end latency, embedding/classify latency), and optionally add schedule hints or predictive scaling. These controls let the deployment scale intelligently against performance and cost objectives.