---
name: kodadocs-multi-site
description: "Manage documentation for multiple projects in a workspace with batch operations, shared config, and cross-linking."
---

# Multi-Site Manager

## Overview

This skill manages documentation across multiple projects within a workspace or monorepo. It discovers all KodaDocs-enabled projects, provides a unified status dashboard, supports batch operations (regenerate all, deploy all, audit all), enables cross-linking between documentation sites, and supports shared configuration inheritance so common settings are defined once and inherited by all projects.

Use this skill when:
- You maintain a monorepo with multiple applications or packages
- You manage several standalone projects and want a unified docs workflow
- You want to deploy all doc sites at once after a release
- You need cross-references between related documentation sites
- You want consistent branding and configuration across all doc sites

## Prerequisites

Before running this skill, ensure the following:

1. **Multiple KodaDocs projects:** At least two projects with `.kodadocs/run_manifest.json` manifests, or at least two project directories where KodaDocs can be initialized.
2. **Workspace root:** A parent directory containing the project directories.
3. **KodaDocs MCP tools available:** The `mcp__kodadocs__*` tools must be accessible.
4. **Git repository (optional):** For change detection across projects.

## Workflow

### Step 1: Discover Projects in Workspace

Scan the workspace to find all KodaDocs-enabled projects.

**Search for existing manifests:**
```bash
# Find all KodaDocs manifest files in the workspace
find <workspace-root> -name "run_manifest.json" -path "*/.kodadocs/*" -maxdepth 4 -not -path "*/node_modules/*" -not -path "*/.next/*" -not -path "*/dist/*"
```

**For each discovered manifest, load its state:**
```
Call mcp__kodadocs__load_manifest with:
  project_path: "<project-directory>"
```

**Extract project metadata from each manifest:**
- Project name
- Last generation timestamp
- Number of routes discovered
- Number of articles generated
- Deployment URL (if deployed)
- Deployment provider
- Brand color and logo
- Framework detected

**Search for uninitialized projects:**
Also scan for projects that could have docs but have not been set up yet:
```bash
# Look for common project indicators without a .kodadocs directory
find <workspace-root> -maxdepth 3 -name "package.json" -o -name "pyproject.toml" -o -name "Cargo.toml" -o -name "go.mod" | while read f; do
  dir=$(dirname "$f")
  if [ ! -d "$dir/.kodadocs" ]; then
    echo "UNINITIALIZED: $dir"
  fi
done
```

**Build the project registry:**

```
Project Registry:
  1. frontend (Next.js) - /workspace/frontend
     Status: Generated | Last run: 2026-03-01 | Routes: 14 | URL: https://frontend-docs.kodadocs.com
  2. api (Django) - /workspace/api
     Status: Generated | Last run: 2026-02-28 | Routes: 22 | URL: https://api-docs.kodadocs.com
  3. admin-panel (React) - /workspace/admin
     Status: Stale (5 days old) | Last run: 2026-02-25 | Routes: 8 | URL: not deployed
  4. mobile-app (React Native) - /workspace/mobile
     Status: NOT INITIALIZED | No .kodadocs directory
```

### Step 2: Display Unified Status Dashboard

Present the user with a consolidated view of all projects.

**Status table format:**

| # | Project | Framework | Routes | Articles | Last Generated | Deploy URL | Status |
|---|---------|-----------|--------|----------|----------------|-----------|--------|
| 1 | frontend | Next.js | 14 | 14 | 2026-03-01 | frontend-docs.kodadocs.com | Current |
| 2 | api | Django | 22 | 20 | 2026-02-28 | api-docs.kodadocs.com | Current |
| 3 | admin-panel | React | 8 | 8 | 2026-02-25 | -- | Stale |
| 4 | mobile-app | React Native | -- | -- | -- | -- | Not initialized |

**Status definitions:**
- **Current:** Generated within the last 3 days and no code changes since
- **Stale:** Generated more than 3 days ago, or code changes exist since last generation
- **Not initialized:** Project exists but has no `.kodadocs/` directory
- **Error:** Manifest exists but is corrupt or incomplete

**Staleness detection:**
For each project with a manifest, check if code has changed:
```bash
cd <project-path>
LAST_SHA=$(cat .kodadocs/run_manifest.json | python3 -c "import sys,json; print(json.load(sys.stdin).get('last_commit_sha',''))")
if [ -n "$LAST_SHA" ]; then
  CHANGES=$(git diff --name-only "$LAST_SHA"..HEAD -- . | wc -l)
  if [ "$CHANGES" -gt 0 ]; then
    echo "STALE: $CHANGES files changed"
  fi
fi
```

### Step 3: Shared Configuration Management

Define shared configuration that all projects inherit.

**Shared config file location:** `<workspace-root>/.kodadocs/shared-config.json`

**Shared config schema:**
```json
{
  "brand_color": "#3e8fb0",
  "logo_path": "/workspace/assets/logo.png",
  "deploy_provider": "kodadocs",
  "license_key_env": "KODADOCS_LICENSE_KEY",
  "style_guide_path": "/workspace/.kodadocs/style-guide.md",
  "shared_navigation": {
    "enabled": true,
    "links": [
      { "text": "Frontend Docs", "url": "https://frontend-docs.kodadocs.com" },
      { "text": "API Docs", "url": "https://api-docs.kodadocs.com" },
      { "text": "Admin Docs", "url": "https://admin-docs.kodadocs.com" }
    ]
  },
  "defaults": {
    "blur_pii": true,
    "theme_name": "professional",
    "show_product_summary": true
  }
}
```

**Config inheritance rules:**
1. Shared config provides defaults for all projects
2. Per-project manifest values override shared config
3. User-specified values at runtime override everything

**Create shared config if it does not exist:**
If no shared config is found, ask the user:
- "Would you like to create a shared configuration for all projects?"
- If yes, prompt for brand_color, logo_path, and deploy_provider
- If no, each project uses its own independent configuration

**Validate shared config:**
- Ensure `brand_color` is a valid hex color
- Ensure `logo_path` points to an existing file (or is null)
- Ensure `deploy_provider` is one of: kodadocs, cloudflare, vercel, netlify, github-pages
- Ensure all `shared_navigation` URLs are valid

### Step 4: Batch Operations

Support running operations across all projects (or a selected subset).

**Operation: Regenerate All**

For each project (in parallel if independent, sequential if sharing resources):

1. Load the project manifest
2. Run `mcp__kodadocs__discover_routes` for fresh route discovery
3. Run `mcp__kodadocs__analyze_codebase` for code context
4. If the application is running, run `mcp__kodadocs__capture_screenshots`
5. Generate articles using code analysis and screenshots
6. Run `mcp__kodadocs__assemble_vitepress` with merged config (shared + project)
7. Save updated manifest via `mcp__kodadocs__save_manifest`

**Execution order:**
```
For each project in the registry:
  If status is "Not initialized":
    Ask: "Initialize docs for <project>? (y/n)"
    If yes: run full pipeline
    If no: skip
  If status is "Stale" or "Current":
    Run incremental refresh or full regeneration based on change count
  If status is "Error":
    Warn: "Skipping <project> due to manifest error"
```

**Progress reporting:**
```
Batch regeneration progress:
  [1/4] frontend ............ DONE (14 routes, 14 articles)
  [2/4] api ................. DONE (22 routes, 20 articles)
  [3/4] admin-panel ......... RUNNING (capturing screenshots...)
  [4/4] mobile-app .......... SKIPPED (not initialized)
```

**Operation: Deploy All**

Deploy all generated doc sites:

```
For each project with status "Current" or just regenerated:
  Call mcp__kodadocs__deploy_site with:
    site_dir: "<project output dir>"
    project_name: "<project name>"
    provider: "<shared or project-specific provider>"
    license_key: "<from env or shared config>"
    site_slug: "<project-specific slug>"
```

**Deploy order considerations:**
- Deploy projects with no cross-links first
- Deploy projects with cross-links after their link targets are live
- If a deployment fails, continue with remaining projects and report the failure

**Operation: Audit All**

Run a documentation freshness audit across all projects (see kodadocs-docs-audit skill for per-project details):

```
For each project with an existing manifest:
  Run route discovery and compare against manifest
  Check screenshot freshness
  Flag issues
```

Produce a unified audit report covering all projects.

### Step 5: Cross-Linking Between Doc Sites

Enable navigation between related documentation sites.

**Cross-link configuration:**
Define relationships between projects in the shared config:

```json
{
  "shared_navigation": {
    "enabled": true,
    "position": "top",
    "label": "Documentation",
    "links": [
      { "text": "Frontend", "url": "https://frontend-docs.kodadocs.com", "project": "frontend" },
      { "text": "API", "url": "https://api-docs.kodadocs.com", "project": "api" },
      { "text": "Admin", "url": "https://admin-docs.kodadocs.com", "project": "admin-panel" }
    ]
  }
}
```

**Inject cross-links during assembly:**
When calling `mcp__kodadocs__assemble_vitepress` for each project, include the shared navigation links in the VitePress configuration. These appear as a top navigation bar linking to sibling doc sites.

**Contextual cross-references:**
When generating articles, detect references to other projects:
- An API endpoint mentioned in the frontend docs should link to the API docs
- A shared component used across projects should link to its primary documentation
- Authentication flows that span frontend and API should cross-reference

**Cross-reference detection:**
```
For each article being generated:
  Scan for mentions of other project names
  Scan for API endpoint paths that match another project's routes
  Scan for shared model/type names across projects
  For each match:
    Insert a cross-reference link: "See [API Authentication](/api-docs/authentication)"
```

### Step 6: Initialize New Projects

For projects in the workspace that do not have KodaDocs set up:

1. **Detect framework:**
   ```
   Call mcp__kodadocs__detect_framework with:
     project_path: "<project-directory>"
   ```

2. **Discover routes:**
   ```
   Call mcp__kodadocs__discover_routes with:
     project_path: "<project-directory>"
   ```

3. **Apply shared config:**
   Inherit brand_color, logo_path, deploy_provider, and other defaults from the shared config.

4. **Generate a project-specific slug:**
   Derive from the project directory name: `my-project` -> `my-project-docs`

5. **Run the full pipeline:**
   Capture screenshots, analyze codebase, generate articles, assemble site.

6. **Add to shared navigation:**
   Update the shared config to include the new project in the cross-link navigation.

7. **Save manifest:**
   Save the new project's manifest with shared config values merged in.

### Step 7: Save Workspace State

After any batch operation, update the workspace-level state.

**Save shared config:**
Write the updated shared config to `<workspace-root>/.kodadocs/shared-config.json`.

**Save per-project manifests:**
Each project's manifest is saved individually via `mcp__kodadocs__save_manifest`.

**Generate a workspace summary file:**
Save a summary at `<workspace-root>/.kodadocs/workspace-summary.json`:

```json
{
  "workspace_root": "/workspace",
  "last_batch_operation": "regenerate-all",
  "last_batch_timestamp": "2026-03-02T14:30:00Z",
  "projects": [
    {
      "name": "frontend",
      "path": "/workspace/frontend",
      "framework": "Next.js",
      "status": "current",
      "routes": 14,
      "articles": 14,
      "deploy_url": "https://frontend-docs.kodadocs.com",
      "last_generated": "2026-03-02T14:30:00Z"
    }
  ],
  "shared_config_path": "/workspace/.kodadocs/shared-config.json"
}
```

## Decision Trees

### Project Discovery Scope

```
Is this a monorepo (single git root with multiple packages)?
  YES -> Scan workspace root recursively (max depth 4)
         Respect workspace config (package.json workspaces, pnpm-workspace.yaml, etc.)
  NO  -> Is a workspace root specified by the user?
           YES -> Scan that directory
           NO  -> Scan the current working directory and its immediate children
```

### Batch vs. Single Project

```
Did the user specify a project name?
  YES -> Operate on that single project only
  NO  -> Did the user request a batch operation (e.g., "regenerate all", "deploy all")?
           YES -> Operate on all discovered projects
           NO  -> Show the status dashboard and ask what to do
```

### Shared Config Creation

```
Does <workspace-root>/.kodadocs/shared-config.json exist?
  YES -> Load and validate it
         Are all referenced projects still present?
           YES -> Use as-is
           NO  -> Warn about orphaned project references. Remove them.
  NO  -> Are there 2+ projects with manifests?
           YES -> Offer to create shared config from the first project's settings
           NO  -> Skip shared config. Use per-project settings.
```

### Cross-Link Availability

```
Is shared_navigation.enabled = true in shared config?
  YES -> Are all linked URLs accessible?
           YES -> Include cross-links in all project assemblies
           NO  -> Include cross-links but mark unreachable URLs with a note
                  Warn: "Cross-link to <url> is not reachable. Deploy that project first."
  NO  -> Skip cross-linking. Each site is standalone.
```

### Stale Project Handling

```
Is the project marked as "Stale"?
  YES -> How many files changed since last generation?
           1-10 -> Suggest incremental refresh
           11-50 -> Suggest full regeneration
           50+ -> Suggest full regeneration with warning about time cost
  NO  -> Is the project marked as "Current"?
           YES -> Skip unless user explicitly requests regeneration
           NO  -> Handle according to status (Error -> fix, Not initialized -> offer setup)
```

### Deployment Ordering

```
Do any projects have cross-links to other projects?
  YES -> Build a dependency graph of cross-references
         Deploy projects with no incoming cross-link dependencies first
         Deploy projects with dependencies after their targets are live
         If circular dependencies exist -> Deploy all simultaneously, links will resolve after all are live
  NO  -> Deploy in any order (alphabetical by project name)
```

## Output Format

The skill produces:

1. **Status dashboard** - A table showing all projects with their status, routes, and deploy URLs
2. **Shared config** (`<workspace-root>/.kodadocs/shared-config.json`) - Workspace-level configuration
3. **Workspace summary** (`<workspace-root>/.kodadocs/workspace-summary.json`) - Machine-readable project registry
4. **Per-project outputs** - Updated manifests, articles, and sites for each project operated on
5. **Console summary:**

```
Multi-site workspace status:
  Projects discovered: 4
  Initialized: 3 | Not initialized: 1
  Current: 1 | Stale: 2 | Error: 0

Batch regeneration results:
  [1/3] frontend ............ DONE (14 routes, 14 articles, deployed)
  [2/3] api ................. DONE (22 routes, 20 articles, deployed)
  [3/3] admin-panel ......... DONE (8 routes, 8 articles, deployed)
  Skipped: mobile-app (not initialized)

Cross-links configured: 3 sites linked via shared navigation
Shared config saved: /workspace/.kodadocs/shared-config.json
```

## Error Handling

### No projects found in workspace
If the workspace scan finds zero projects (no manifests, no package.json/pyproject.toml):
- Inform: "No projects found in <workspace-root>. Ensure this is the correct workspace directory."
- Suggest: "Run the full KodaDocs pipeline on individual projects first."

### Only one project found
If only a single project is discovered:
- Inform: "Only one project found. Multi-site management requires two or more projects."
- Offer: "Would you like to run single-project operations on <project-name> instead?"

### Shared config conflicts with project config
If a project's manifest has values that conflict with shared config:
- Project-level values take precedence (override shared)
- Log: "Project <name> overrides shared brand_color (#abc -> #def)"
- Do not modify project-level overrides without explicit user instruction

### Batch operation partial failure
If some projects succeed and others fail during a batch operation:
- Complete all projects that can succeed
- Report failures at the end with per-project error details
- Do not roll back successful operations
- Save updated manifests only for successful projects

### Cross-link target not deployed
If a cross-link points to a project that has not been deployed:
- Include the link but add a tooltip/note: "(not yet deployed)"
- Log the warning in the batch report
- Suggest deploying the target project

### Circular cross-references
If project A links to B and B links to A:
- This is valid and expected. Both links will work after both sites are deployed.
- Deploy both sites. The links will resolve once all deployments are complete.

### Workspace root permissions
If the workspace root `.kodadocs/` directory cannot be created:
- Fall back to per-project configuration only
- Warn: "Cannot create workspace config directory. Using per-project settings."

### Manifest version mismatch across projects
If projects have manifests from different KodaDocs versions:
- Normalize all manifests to the current schema during the batch operation
- Warn: "Project <name> has an older manifest format. It will be updated."

## Success Criteria

The run is successful when:
- [ ] All projects in the workspace were discovered (manifests and uninitialized)
- [ ] Status dashboard was displayed with accurate status for each project
- [ ] Shared config was loaded (or created if requested)
- [ ] Batch operations completed for all eligible projects
- [ ] Per-project manifests were updated after operations
- [ ] Cross-links were configured in all project assemblies (if enabled)
- [ ] Workspace summary was saved
- [ ] Console summary was printed with per-project results
- [ ] Failed projects were reported with actionable error messages
- [ ] Deployment order respected cross-link dependencies
