Publish documents to CALM Hub via calm workspace

[LeighFinegold]

Feature Proposal

Target Project:

cli (calm workspace), integrating with calm-hub (the new Document endpoint).

Description of Feature:

Extend the CALM Workspace flow so a user can publish a document to CALM Hub from their workspace and we can demo the published document end-to-end. This is the user-facing slice that ties the PoC together, and it realises the agreement in #2866 that documents are "version controlled and pushed to CALM Hub with the same mechanism as calm workspace".

User Stories:

• As an architect, I want calm workspace push to publish my document to CALM Hub so that I can demonstrate a document going from local workspace to a live Hub registry, versioned alongside its architecture.
• As a reviewer, I want to open the published document from CALM Hub after a push so that the demo proves the full loop.

Current Limitations:

• calm workspace can push CALM artefacts today, but has no step to publish a document to a documents endpoint and no notion of a document artefact. The current workspace/Hub command overlap and gaps are catalogued in CALM Workspace vs CALM Hub CLI Command Comparison #2539.

Proposed Implementation:

• Extend calm workspace push (or add a dedicated publish step) to send the workspace's document(s) to the new namespace-scoped documents endpoint (/api/calm/namespaces/{namespace}/documents/{document-type}), honouring CALM Hub auth.
• Because documents ride the existing workspace mechanism, workspace check (drift detection) and bump (coordinated versioning) apply automatically - the document is versioned alongside its architecture.
• Record the published document's Hub location/id back into the workspace manifest so list reflects publish state.
• Demo path (local, no-auth / standalone Hub):
  1. Initialise a workspace and add a sample architecture + a document.
  2. calm workspace push → validates + publishes the document.
  3. Retrieve it from CALM Hub (API or UI) to confirm the loop.
• Dependencies: the Document endpoint and validation issues must land first.

Alternatives Considered:

• A separate calm publish command decoupled from workspace - possible, but the PoC goal is to demo the workspace publishing a document, so integrate with workspace.
• Manual upload via the API - rejected; the value is an automated, versioned publish.

Testing Strategy:

• CLI unit tests for the push→publish path (mocked Hub client) and manifest update.
• A scripted end-to-end demo against a local CALM Hub asserting the document is retrievable after push.

Documentation Requirements:

• calm workspace documentation: the publish flow and the demo steps.

Implementation Checklist:

• Design reviewed and approved
• Implementation completed
• Tests written and passing
• Documentation updated
• Relevant workflows updated (if needed)
• Performance impact assessed

Additional Context:

• This is the demo-able outcome of the PoC value cycle: workspace → validate → publish → retrievable in CALM Hub.
• Command placement should be consistent with the workspace/Hub surface analysed in CALM Workspace vs CALM Hub CLI Command Comparison #2539; related CLI publishing commands are in feat(cli): add push/pull/list/create commands for publishing and managing CALM Hub content #2377, and workspace acceleration in Add workspace skills suite to accelerate common development workflows #2237.
• the document format is defined in Design Discussion: Introduce a Knowledge Decorator for Architecture Documentation #2866; the underlying decision is Design Discussion: Documents vs Decorators #2791.

[101Steeps]

Happy to work on this to continue the work on the POC under Issue #2981 #2982

[101Steeps]

Draft implementation ready for maintainer review

The workspace publishing implementation is available in draft PR #3015.

It adds support for sad and knowledge Markdown documents in calm workspace:

• workspace add reads YAML frontmatter and requires a namespace.
• workspace push creates the initial document and records its Hub identity in the workspace manifest.
• workspace check detects changed Markdown that has not been version-bumped.
• workspace bump updates the manifest version without rewriting Markdown.
• workspace push creates the next immutable Hub version.
• Persisted document identity and Hub Locations are validated before Hub calls.

Testing completed:

• Full Linux npm test: all 17 workspace test summaries passed, including shared 90 files / 1,084 tests and CLI 28 files / 682 tests.
• npm run build:cli passed.
• Focused narrative helper tests: 17 passed.
• Combined POC: First-class Documents in CALM Hub  #2981 POC smoke test: 7 test files / 28 tests passed.
• Manual standalone POC: publish 1.0.0 → retrieve → edit → drift detected → bump → publish/retrieve 1.1.0 → clean final check.

#3015 depends on #3002 for the Calm Hub document endpoints.