Timeline Support in Docify/VSCode Tooling

## Background

### Docify
Docify is a CLI command (`calm docify`) that generates documentation websites from CALM architecture files. It loads a CALM JSON file, parses it into typed models, transforms to canonical format, and renders HTML via Handlebars templates with embedded widgets - outputting static HTML/Markdown suitable for Docusaurus or standalone viewing.

### Widget Framework
`@finos/calm-widgets` provides reusable Handlebars-based visualization components (tables, sequence diagrams, block diagrams, etc.) that transform CALM canonical model data into HTML. Widgets are registered as Handlebars helpers and used in both CLI docify output and VSCode preview rendering.

### VSCode Extension
The VSCode plugin provides live, in-IDE interaction with CALM architectures - allowing developers to browse, visualize, and validate their architecture models without leaving their editor.

**TreeView (Navigation)**
- Sidebar showing architecture structure (nodes, relationships, flows)
- Click to navigate between components

**Preview Panel (Visualization)**
- Visual rendering of architecture using the same widget pipeline as docify
- What you see in the IDE matches what gets generated as documentation

**Key Principle**: TreeView handles navigation, Preview handles visualization via widgets. This ensures consistent rendering across VSCode and CLI docify output.

---

## Description of Feature

Add comprehensive timeline visualization and navigation support to CALM tooling, enabling users to:
- Visualize architecture evolution over time
- Navigate between architecture versions at different milestones
- Generate documentation showing the complete architecture roadmap

CALM 1.2 already defines `timeline.json` and `calm-timeline.json` schemas, and `calm-models` has corresponding TypeScript types. However, the tooling cannot currently visualize or navigate timeline documents.

## Not In Scope
Currently the below doesn't cover calm-hub-ui but we can adapt the issue according or raised an additional issue for that support.

---

## User Stories

### US1: Timeline Visualization

**As an** user,
**I want** to see a visual timeline of my architecture evolution,
**So that** I can understand and communicate how the system changes over time.

**Proposed Implementation:**
- New `timeline-widget` in `calm-widgets` renders a visual timeline with milestones
- Each milestone displays as a clickable link pointing to its `architecture-ref` URL
- Clicking a milestone navigates to the architecture (can be opened inline, in iframe, or new tab depending on context)
- Widget usable in templates via: `{{timeline timelineData}}`
- Works in both VSCode preview and CLI docify output (same widget, consistent rendering)

---

### US2: Milestone Navigation

**As a** user,
**I want** to click on a timeline milestone and see that version of the architecture,
**So that** I can quickly compare different points in the architecture's evolution.

**Proposed Implementation:**
- Timeline widget renders clickable milestone markers
- Clicking opens the referenced architecture file
- Uses existing `NavigationService` with URL mapping for resolution

---

### US3: TreeView Timeline Support

**As a** user,
**I want** to see timeline milestones in the sidebar when I open a timeline file,
**So that** I can navigate between architecture versions without manually opening files.

**Proposed Implementation:**
- Detect timeline files via `$schema` field
- TreeView displays milestones as expandable nodes:

```
📅 Architecture Timeline: {name}
├── 📍 {milestone-1-name} ({date})
│ └── 🔗 {architecture-file}
├── 📍 {milestone-2-name} ({date})
│ └── 🔗 {architecture-file}
└── 📍 {milestone-3-name} ({date})
└── 🔗 {architecture-file}
```

- Clicking milestone opens referenced architecture in the current editor/preview view
- Preview panel updates to show the selected architecture visualization

---

### US4: Milestone Comparison

**As a** user,
**I want** to compare two milestones side-by-side,
**So that** I can understand what changed between architecture versions.

**Proposed Implementation:**
- Select two milestones to compare
- Side-by-side diff view showing:
- Nodes added/removed/modified
- Relationships changed
- Visual diff of block diagrams
- Could leverage existing diff tooling or build custom comparison widget

---

## Current Limitations

| Component | Current State | Gap |
|-----------|---------------|-----|
| CALM 1.2 Spec | `timeline.json` schema exists | ✅ No gap |
| calm-models | `timeline-types.ts` exists | ✅ No gap |
| calm-widgets | 6 widgets, none for timelines | ❌ No `timeline-widget` |
| shared/docify | Single architecture only | ❌ No timeline template |
| CLI docify | `calm docify -a arch.json` | ❌ Cannot process timeline.json |
| VSCode TreeView | Shows nodes/relationships/flows | ❌ No timeline milestone display |
| VSCode Preview | Renders via widgets | ❌ No timeline visualization |

**Summary**: The schema and types exist, but visualization, navigation, and documentation generation are missing.

---

## Proposed Implementation Phases

### Phase 1: Timeline Widget (calm-widgets)
- New `timeline-widget` renders visual timeline with milestones
- Template uses Mermaid or HTML/CSS for visualization
- Usage: `{{timeline timelineData}}`

### Phase 2: Timeline Template Bundle (shared)
- New timeline template for docusaurus bundle
- Generates timeline overview page with embedded widget
- Links to architecture documentation for each milestone

### Phase 3: VSCode TreeView Enhancement (calm-plugins/vscode)
- Detect timeline files via `$schema` field
- Display milestones as navigable tree nodes
- Clicking milestone opens referenced architecture via existing NavigationService
- Preview panel shows timeline-widget visualization

### Phase 4: Multi-Architecture Docify (cli/shared)
- Enhanced docify to process timeline.json
- Generates documentation for all referenced architectures
- Output structure with timeline index and milestone subdirectories

### Phase 5: Diffing Architecture?

---

## Additional Context

### Timeline Schema Structure (CALM 1.2)

```json
{
"$schema": "https://calm.finos.org/release/1.2/meta/calm-timeline.json",
"name": "Architecture Evolution",
"description": "Evolution from insecure to secure architecture",
"milestones": [
{
"unique-id": "initial",
"name": "Initial State",
"date": "2024-Q1",
"description": "Starting architecture without security controls",
"architecture-ref": "https://example.com/arch-insecure.json"
},
{
"unique-id": "secured",
"name": "Fully Secured",
"date": "2024-Q3",
"description": "Architecture with all security controls implemented",
"architecture-ref": "https://example.com/arch-secure.json"
}
]
}
```