feat: scan-workspace command for cross-project Context derivation

[prakashUXtech]

Summary

A c4-gen scan-workspace command that derives the cross-project System Context view from per-project models plus a small workspace manifest naming the cross-project relationships. Replaces the hand-authored stop-gap at docs/c4/workspace.md in the OCEAN paw-workspace.

Why

Today every C4 model in the OCEAN workspace is per-project. Agents working in pocketpaw can't see that paw-enterprise is a downstream consumer of its REST API; agents in paw-enterprise can't see that ripple widgets are the rendering layer. The workspace-level cross-project view is the missing piece that makes C4 useful for agent system-prompts.

The current workaround is a hand-authored docs/c4/workspace.md that goes stale the moment a new project enters the workspace or a relationship changes. Auto-derivation removes the maintenance tax.

Proposed shape

c4-gen scan-workspace <workspace-root> --output <path>

Inputs:

• Workspace root directory containing multiple project subdirectories
• A workspace manifest (e.g. c4-workspace.yaml) naming projects + their cross-project relationships, since static analysis can't always reliably detect relationships like "paw-enterprise frontend calls pocketpaw REST API"

Outputs:

• A workspace-level model.json at <workspace-root>/docs/c4/model.json (or wherever --output points)
• A Mermaid render at <workspace-root>/docs/c4/workspace.md

Manifest sketch

# c4-workspace.yaml
projects:
  - name: pocketpaw
    path: pocketpaw
    description: Python FastAPI runtime + ee/cloud module
  - name: paw-enterprise
    path: paw-enterprise
    description: Svelte 5 + TypeScript dashboard
  - name: soul-protocol
    path: soul-protocol
    description: Python library for persistent AI identity
relationships:
  - from: paw-enterprise
    to: pocketpaw
    description: REST API + WebSocket
  - from: pocketpaw
    to: soul-protocol
    description: library import (when soul_enabled=true)
external:
  - name: MongoDB
    type: database
    used_by: [pocketpaw]
    note: ee/cloud only

Reference

Integration plan in the OCEAN workspace: docs/roadmap/future-upgrades/c4-integration.md (qbtrix/paw-workspace). The hand-authored stop-gap is at docs/c4/workspace.md in the same repo and shows the kind of output this command should produce.

Acceptance

• c4-gen scan-workspace reads the manifest + per-project models, emits model.json + Mermaid
• Existing per-project commands keep working
• Smoke test against the OCEAN workspace produces output close to the hand-authored workspace.md