Design Discussion: Documents vs Decorators

## Feature Discussion

### Target Project:

CALM (cross-cutting: calm-hub, calm-hub-ui, CLI, calm-spec)

### Description of Feature:

CALM tooling and workflows produce artefacts that sit alongside architectures but aren't architectures themselves. Solution Architecture Documents (SADs), user guides, operational runbooks, compliance narratives, API documentation, and similar prose or mixed-format deliverables.

These are documents in their own right with independent lifecycles, often authored by different teams, and needing version control.

Today, the only mechanism to associate these with an architecture in CALM Hub is to make them decorators. But a user guide isn't a "cross-cutting overlay that augments an existing CALM element." It's a standalone artefact. Treating it as a decorator:

1. **Loses version history**: decorators aren't versioned in CALM Hub (no version endpoints, no version timeline)
2. **Dilutes the decorator concept**: "decorator" becomes a catch-all for "anything that isn't core JSON," making it harder to reason about what decorators are actually for
3. **Misrepresents the artefact**: a SAD or user guide is a first-class deliverable, not supplementary metadata

For example, `calm docify` can generate documentation from architectures. Even if it were implemented, there's no place to publish the output.

### User Stories:

- As an **architect**, I want to publish my Solution Architecture Document alongside my CALM architecture so that reviewers can see both the model and the narrative in one place.
- As a **platform team lead**, I want to version operational runbooks associated with my architecture so that I can track changes over time and roll back if needed.
- As a **compliance officer**, I want architecture-related compliance narratives to be versioned and traceable so that I can demonstrate audit history.
- As a **developer**, I want user guides linked to the architecture they describe so that I don't have to search Confluence/SharePoint for the right version.

### Current Limitations:

- CALM Hub stores and versions 8 document types (architectures, patterns, flows, standards, interfaces, controls, ADRs, timelines), all JSON
- Decorators are stored but not versioned: no version endpoints, no version history, no timeline
- No mechanism exists to store non-JSON content (Markdown, HTML, PDF)
- `calm docify` SAD mode is unimplemented
- No CLI command to publish generated documentation to CALM Hub

### Proposed Implementation:

This issue is primarily a design question: the implementation depends on the answer.

The core question: where should versioned, non-JSON artefacts that relate to CALM architectures live? Options include:

1. **A new document type in CALM Hub**: versioned, content-type-aware, associated with architectures but independently managed
2. **External systems with references**: documents live in Git/Confluence/SharePoint; CALM tracks references to them (e.g. via a URL field on architectures)
3. **A hybrid**: CALM Hub stores metadata and references; content lives elsewhere but is discoverable through CALM Hub
4. **Make decorators versioned**: add versioning support to decorators so they can serve as the store for these artefacts. This addresses the versioning gap but still raises the question of whether a user guide or SAD is conceptually a "decorator"

Each has trade-offs around traceability, tooling integration, and scope. My instinct is that these artefacts sit outside the decorator model, but that's exactly the question this issue is asking - keen to hear views.

### Additional Context:

This issue is part of a series exploring CALM's decorator and document model. Related issues that may provide useful context:

- finos/architecture-as-code#2792 CALM Hub decorator registry and views
- finos/architecture-as-code#2793 Decorator Association Scalability Concerns
- finos/architecture-as-code#2552 Decorator mechanism: close meta-schema and CLI gaps
- finos/calm-schema#20 Allow flows array to be a reference (contains the decorator definitional debate)
- finos/calm-schema#8 Add a Guide Section to the CALM Schema

Start with the linked issues #2792, #2793, #2552, calm-schema #20, and calm-schema #8, then review the current CALM Hub document and decorator behavior described here. Done means maintainers have selected and documented a model for storing, linking, and versioning non-JSON artefacts, including the impact on calm docify and the CLI.

Written by the indexing model from the issue text.