Enhance per-user instance management and status tracking in DeployStack Satellite

- Updated hierarchical router documentation to clarify user-specific process routing and tool filtering.
- Revised process management documentation to reflect per-user subprocess management and independent lifecycle.
- Enhanced status tracking documentation to emphasize per-user instance status and filtering logic.
- Introduced new instance lifecycle management documentation detailing creation, deletion, and team membership changes.
- Improved team isolation documentation to highlight per-user access control and instance separation.
- Updated tool discovery documentation to clarify per-user status integration and request logging settings.

Author: Lasim

development/backend/mcp-configuration-architecture.mdx

@@ -82,88 +82,42 @@ The three-tier system addresses this by:
 
 ## Database Schema
 
+The three-tier configuration system uses three main tables:
+
 ### Tier 1: MCP Catalog (`mcpServers`)
 
-The catalog defines the configuration structure for each MCP server type:
-
-**Core Configuration Fields:**
-```sql
--- Template Level (with lock controls)
-template_args: text('template_args')         -- [{value, locked, description}]
-template_env: text('template_env')           -- Fixed environment variables
-template_headers: text('template_headers')   -- Fixed HTTP headers (for HTTP/SSE)
-template_url_query_params: text('template_url_query_params') -- Fixed URL query params (for HTTP/SSE)
-
--- Team Schema (with lock/visibility controls)
-team_args_schema: text('team_args_schema')   -- Schema with lock controls
-team_env_schema: text('team_env_schema')     -- [{name, type, required, default_team_locked, visible_to_users}]
-team_headers_schema: text('team_headers_schema') -- HTTP headers schema (for HTTP/SSE)
-team_url_query_params_schema: text('team_url_query_params_schema') -- URL query params schema (for HTTP/SSE)
-
--- User Schema
-user_args_schema: text('user_args_schema')   -- User-configurable argument schema
-user_env_schema: text('user_env_schema')     -- User-configurable environment schema
-user_headers_schema: text('user_headers_schema') -- User HTTP headers schema (for HTTP/SSE)
-user_url_query_params_schema: text('user_url_query_params_schema') -- User URL query params schema (for HTTP/SSE)
-```
+Defines configuration structure for each MCP server type including template-level config, team/user schemas, transport configuration, and registry tracking.
 
-**Transport Configuration:**
-```sql
-transport_type: text('transport_type')       -- 'stdio' | 'http' | 'sse'
-packages: text('packages')                   -- JSON: npm/pip/docker packages (stdio)
-remotes: text('remotes')                     -- JSON: HTTP/SSE endpoints
-```
+### Tier 2: Team Installation (`mcpServerInstallations`)
 
-**Official Registry Tracking Fields:**
-```sql
-official_name: text('official_name')         -- Reverse-DNS name from registry
-synced_from_official_registry: boolean       -- True if synced from registry
-official_registry_server_id: text            -- Registry's server identifier
-official_registry_version_id: text           -- Registry's version identifier
-official_registry_published_at: timestamp    -- Original publication date
-official_registry_updated_at: timestamp      -- Last update in registry
-```
+Manages shared team configurations including installation name, team args, environment variables, headers, and URL query params.
 
-**GitHub Enhancement Fields:**
-```sql
-repository_source: text                      -- 'github' | 'gitlab' | 'bitbucket'
-repository_id: text                          -- Platform-specific repo ID
-repository_subfolder: text                   -- Monorepo subfolder path
-github_account_id: text                      -- For avatar URLs
-github_readme_base64: text                   -- Cached README content
-github_stars: integer                        -- Star count for social proof
-```
+### Per-User Instances (`mcpServerInstances`)
 
-### Tier 2: Team Installation (`mcpServerInstallations`)
+While not strictly a "configuration tier", the instance table enables per-user isolation:
 
-Team installations manage shared configurations:
+**Key Characteristics**:
+- One instance per user per installation (UNIQUE constraint)
+- Independent status tracking per user
+- CASCADE deletes when installation removed
+- Enables parallel status states (User A online, User B offline)
 
-```sql
-installation_name: text('installation_name') -- Team-friendly name
-team_args: text('team_args')                 -- Team-level arguments (JSON array)
-team_env: text('team_env')                   -- Team environment variables (JSON object)
-team_headers: text('team_headers')           -- Team HTTP headers (JSON object, for HTTP/SSE)
-team_url_query_params: text('team_url_query_params') -- Team URL query params (JSON object, for HTTP/SSE)
-```
+For complete database schema, see [Database Schema](/development/backend/database/).
 
-### Tier 3: User Configuration (`mcpUserConfigurations`)
+For complete instance lifecycle, see [Instance Lifecycle](/development/satellite/instance-lifecycle).
 
-Individual user configurations:
+### Tier 3: User Configuration (`mcpUserConfigurations`)
 
-```sql
-installation_id: text('installation_id')     -- References team installation
-user_id: text('user_id')                     -- User who owns this config
+Stores individual user configurations including personal args, environment variables, headers, and URL query params.
 
-user_args: text('user_args')                 -- User arguments (JSON array)
-user_env: text('user_env')                   -- User environment variables (JSON object)
-user_headers: text('user_headers')           -- User HTTP headers (JSON object, for HTTP/SSE)
-user_url_query_params: text('user_url_query_params') -- User URL query params (JSON object, for HTTP/SSE)
-```
+**For complete database schema details, see [Database Schema](/development/backend/database/).**
 
 ## Configuration Flow
 
 ### Runtime Assembly
 
+**Per-User Instance Isolation**: Configurations are assembled **per user** at runtime. Each team member's instance receives their merged config (template + team + user).
+
 ### Configuration Schema Step
 
 Global administrators categorize configuration elements through the Configuration Schema Step:

development/backend/mcp-server-oauth.mdx

@@ -376,6 +376,13 @@ if (provider) {
       status_message: 'Authenticated successfully, waiting for satellite to connect'
     });
     ```
+
+**Per-User Instance Creation**: OAuth callback creates the user's instance with status='connecting'. For multi-user teams:
+- Installing user's instance created with their OAuth credentials
+- Other team members' instances created with status='awaiting_user_config' (they must authenticate separately)
+- Each user authenticates independently with their own OAuth account
+
+For instance lifecycle details, see [Instance Lifecycle](/development/satellite/instance-lifecycle).
   </Step>
 
   <Step title="Encrypt and Store Tokens">
@@ -825,6 +832,8 @@ CREATE TABLE mcpOauthTokens (
       })
       .where(eq(mcpServerInstallations.id, installation.id));
     ```
+
+**Per-User Instance Impact**: Token refresh failures only affect the specific user's instance. Other team members' instances remain unaffected even if one user's OAuth token expires.
   </Step>
 </Steps>
 

development/backend/satellite/commands.mdx

@@ -76,23 +76,28 @@ interface CommandPayload {
 
 ## Status Changes Triggered by Commands
 
-Commands trigger installation status changes through satellite event emission:
+Commands trigger **per-user instance** status changes through satellite event emission:
 
-| Command | Status Before | Status After | When |
-|---------|--------------|--------------|------|
-| `configure` (install) | N/A | `provisioning` → `command_received` → `connecting` | Installation creation flow |
+| Command | Instance Status Before | Instance Status After | When |
+|---------|----------------------|---------------------|------|
+| `configure` (install) | N/A | `provisioning` or `awaiting_user_config` | New installation - depends on required user config |
 | `configure` (update) | `online` | `restarting` → `online` | Configuration change applied |
-| `configure` (delete) | Any | Process terminated | Installation removal |
-| `health_check` (credential) | `online` | `requires_reauth` | OAuth token invalid |
+| `configure` (delete) | Any | Instance deleted (CASCADE) | Installation removal |
+| `health_check` (credential) | `online` | `requires_reauth` | OAuth token invalid for this user |
 | `restart` | `online` | `restarting` → `online` | Manual restart requested |
 
-**Status Lifecycle on Installation**:
-1. Backend creates installation → status=`provisioning`
-2. Backend sends `configure` command → status=`command_received`
-3. Satellite connects to server → status=`connecting`
-4. Satellite discovers tools → status=`discovering_tools`
-5. Satellite syncs tools to backend → status=`syncing_tools`
-6. Process complete → status=`online`
+**Per-User Status Tracking**: Each team member's instance has independent status. User A's config change only affects User A's instance status.
+
+**Status Lifecycle on Installation** (per user):
+1. Backend creates installation → creates instances for all team members
+2. If user has required config → status=`provisioning`
+3. If user missing required config → status=`awaiting_user_config` (not sent to satellite)
+4. User configures settings → status changes to `provisioning` → satellite spawns
+5. Satellite connects → status=`connecting`
+6. Satellite discovers tools → status=`discovering_tools`
+7. Process complete → status=`online`
+
+For complete instance lifecycle documentation, see [Instance Lifecycle](/development/satellite/instance-lifecycle).
 
 For complete status transition documentation, see [Backend Events - Status Values](/development/backend/satellite/events#mcp-server-status_changed).
 
@@ -118,6 +123,11 @@ All `configure` commands include an `event` field in the payload for tracking an
 3. Identifies added/removed/modified servers
 4. Takes appropriate action
 
+**Per-User Instance Impact**: Configure commands trigger per-user instance creation/updates:
+- Installation created → All team members get instances (status depends on required user config)
+- Installation updated → Only affects users with existing configs (others remain `awaiting_user_config`)
+- Installation deleted → CASCADE deletes all user instances
+
 **Purpose of Event Field**:
 - Database record keeping
 - Structured logging

development/backend/satellite/communication.mdx

@@ -25,9 +25,9 @@ The satellite communication system includes:
 
 **Team-Aware Configuration Distribution**:
 - Global satellites receive ALL team MCP server installations
-- Each team installation becomes a separate process with unique identifier
-- Process ID format: `{server_slug}-{team_slug}-{installation_id}`
-- Team-specific configurations (args, environment, headers) merged per installation
+- Each team installation becomes separate per-user processes with unique identifiers
+- Process ID format: `{server_slug}-{team_slug}-{user_slug}-{installation_id}`
+- User-specific configurations (args, environment, headers) merged per user instance
 
 **Configuration Merging Process**:
 1. Template-level configuration (from MCP server definition)
@@ -268,7 +268,9 @@ The backend provides REST and SSE endpoints for frontend access to installation
 ### Status & Monitoring Endpoints
 
 **GET `/api/teams/{teamId}/mcp/installations/{installationId}/status`**
-- Returns current installation status, status message, and last update timestamp
+- Returns authenticated user's instance status only (not installation-level)
+- Each user sees ONLY their own instance status, not other team members' statuses
+- Response: `{ status, status_message, status_updated_at, last_health_check_at }`
 - Used by frontend for real-time status badges and progress indicators
 
 **GET `/api/teams/{teamId}/mcp/installations/{installationId}/logs`**
@@ -445,36 +447,21 @@ The satellite system integrates with existing DeployStack schema through 5 speci
 - Alert generation and notification triggers
 - Historical health trend analysis
 
-### New Columns Added (Status & Health Tracking System)
-
-**mcpServerInstallations** table:
-- `status` (text) - Current installation status (11 possible values)
-- `status_message` (text, nullable) - Human-readable status context or error details
-- `status_updated_at` (timestamp) - Last status change timestamp
-- `last_health_check_at` (timestamp, nullable) - Last health check execution time
-- `last_credential_check_at` (timestamp, nullable) - Last credential validation time
-- `settings` (jsonb, nullable) - Generic settings object (e.g., `request_logging_enabled`)
-
-**mcpServers** table:
-- `health_status` (text, nullable) - Template-level aggregated health status
-- `last_health_check_at` (timestamp, nullable) - Last template health check time
-- `health_check_error` (text, nullable) - Last health check error message
-
-**mcpServerLogs** table:
-- Stores batched stderr logs from satellites
-- 100-line limit per installation (enforced by cleanup cron job)
-- Fields: `installation_id`, `team_id`, `log_level`, `message`, `timestamp`
-
-**mcpRequestLogs** table:
-- Stores batched tool execution logs
-- `tool_response` (jsonb, nullable) - MCP server response data
-- Privacy control: Only captured when `request_logging_enabled=true`
-- Fields: `installation_id`, `team_id`, `tool_name`, `request_params`, `tool_response`, `duration_ms`, `success`, `error_message`, `timestamp`
-
-**mcpToolMetadata** table:
-- Stores discovered tools with token counts
-- Used for hierarchical router token savings calculations
-- Fields: `installation_id`, `server_slug`, `tool_name`, `description`, `input_schema`, `token_count`, `discovered_at`
+### Database Integration
+
+**Per-User Instance Model**: Each team member gets their own instance with independent status tracking. Status exists ONLY at the instance level in `mcpServerInstances` table.
+
+**Key Tables**:
+- `mcpServerInstances` - Per-user instance status tracking
+- `satellites` - Satellite registry
+- `satelliteCommands` - Command queue
+- `satelliteProcesses` - Process tracking
+- `satelliteUsageLogs` - Usage analytics
+- `satelliteHeartbeats` - Health monitoring
+
+For complete database schema details, see [Database Schema](/development/backend/database/).
+
+For complete instance lifecycle documentation, see [Instance Lifecycle](/development/satellite/instance-lifecycle).
 
 ### Team Isolation in Data Model
 
@@ -602,15 +589,11 @@ server.get('/satellites/:satelliteId/commands', {
 
 ### Database Integration
 
-The satellite system extends the existing database schema with 5 specialized tables:
+The satellite system uses specialized tables for registry, commands, processes, usage logs, and heartbeats.
 
-**Schema Location**: `services/backend/src/db/schema.ts`
+**Per-User Instance Model**: `mcpServerInstances` table tracks status for each user's instance independently, with CASCADE delete when installation is removed.
 
-**Table Relationships**:
-- `satellites` table links to existing `teams` and `authUser` tables
-- `satelliteProcesses` table references `mcpServerInstallations` for team context
-- `satelliteCommands` table includes team context for command execution
-- All tables use existing foreign key relationships for data integrity
+For complete database schema and relationships, see [Database Schema](/development/backend/database/).
 
 ### Configuration Query Implementation