Extending Teamcentric Forge from Live Documents to Dashboards

Teamcentric Forge started with a deliberately simple idea: keep technical documentation in Markdown, allow selected blocks to retrieve or generate fresh information at build time, and use a CLI to turn that source into an up-to-date document.

That model is useful on its own, but it also creates a natural path toward something broader: the same Markdown source can drive a live or periodically refreshed dashboard without introducing a second definition format.

The important architectural decision is that the Markdown document remains the source of truth. The dashboard, generated Markdown, and exported PDF are all different views of the same underlying definition.

The Original Forge Model

At its simplest, Forge consists of a document library, an editor, and a CLI.

A document stored in the tenant library contains normal Markdown alongside executable or retrievable blocks. The CLI retrieves that source, executes the dynamic sections, and generates an updated Markdown document.

The resulting document can remain local, be posted back into the Forge library, or be exported further, for example to PDF.

flowchart LR
    A["Forge SaaS Library"] --> B["Markdown Source"]
    B --> C["Forge CLI"]
    C --> D["Execute dynamic blocks"]
    D --> E["Generated Markdown"]
    E --> F["Local file"]
    E --> G["Post back to Forge"]
    E --> H["Export to PDF"]

The strength of this model is that execution happens where the CLI runs.

That means a Forge document can obtain information that a hosted SaaS platform would not normally be able to reach, including local files, private databases, Docker, internal services, operating-system information, or commands that require elevated privileges.

Markdown Remains the Source of Truth

The extension into dashboards should not introduce a second configuration system.

Instead of maintaining one definition for documentation and another for monitoring, Forge can use the same Markdown document to define both.

Conceptually:

flowchart TD
    A["Forge Markdown"] --> B["Execution Layer"]

    B --> C["Generated Document"]
    B --> D["Dashboard State"]

    C --> E["Markdown"]
    C --> F["PDF"]

    D --> G["Hosted Dashboard"]

The document defines:

what information is required,
how that information should be retrieved,
how often a live value should be refreshed,
where execution should take place,
and how the result should be represented.

The dashboard is therefore not a separate application definition. It is a visual rendering of the same document.

From Document Blocks to Dashboard Widgets

An executable Forge block can be treated as both a document element and a dashboard widget.

For example, a document might contain blocks representing:

production API health,
server disk usage,
Docker container state,
Git branch or release information,
SSL certificate expiry,
database statistics,
deployment status,
open issues,
or custom script output.

When the document is generated normally, these blocks become Markdown.

When the document is viewed as a dashboard, the same blocks become visual widgets.

flowchart LR
    A["Widget definition in Markdown"] --> B["Execute"]
    B --> C["Structured result"]

    C --> D["Markdown renderer"]
    C --> E["Dashboard renderer"]

    D --> F["Table / text / status"]
    E --> G["Card / gauge / chart / status"]

This separation between execution and presentation is what makes the extension practical.

A disk-space block, for example, should ideally return structured information rather than preformatted text:

{
  "totalBytes": 250000000000,
  "usedBytes": 184000000000,
  "freeBytes": 66000000000,
  "usedPercent": 73.6
}

The Markdown renderer might turn that into a table.

The dashboard renderer might display a progress bar or gauge.

The underlying result remains the same.

Every Document Can Have a Dashboard

Once widgets produce structured state, every Forge document can automatically have an associated dashboard.

The default dashboard layout can follow the order of the Markdown document.

For example:

## Production

:::
type: http-health
title: API
refresh: 30s
:::

:::
type: disk-space
title: Disk
path: /
refresh: 5m
:::

:::
type: docker-status
title: Containers
refresh: 1m
:::

Forge could automatically derive a dashboard similar to:

┌──────────────────┐  ┌──────────────────┐
│ API              │  │ Disk             │
│ Healthy          │  │ 73.6% used       │
└──────────────────┘  └──────────────────┘

┌──────────────────┐
│ Containers       │
│ 6 / 6 running    │
└──────────────────┘

The user can then visually rearrange those widgets.

That rearrangement does not need to alter the underlying Markdown. It can be stored separately as presentation metadata.

flowchart TD
    A["Markdown source"] --> B["Widget definitions"]
    B --> C["Default dashboard layout"]

    C --> D["User rearranges widgets"]
    D --> E["Dashboard layout metadata"]

    A --> F["Still remains canonical source"]

This keeps the responsibilities clean:

Concern	Source
What should be executed	Markdown
What the widget means	Markdown
Refresh interval	Markdown
Privilege requirement	Markdown
Latest runtime value	Widget state
Dashboard position and size	Layout metadata

The CLI Becomes a Generator and a Watcher

The existing CLI can be extended rather than replaced.

Its first role remains document generation.

forge generate production.md

Its second role becomes continuous or scheduled execution.

forge agent production.md

In agent mode, the CLI periodically executes the widgets defined in the Markdown and sends only the resulting structured state back to the SaaS platform.

flowchart LR
    A["Forge Library"] --> B["Markdown source"]
    B --> C["Forge CLI / Agent"]

    C --> D["Run widgets locally"]
    D --> E["Structured widget state"]

    E --> F["Forge SaaS"]
    F --> G["Hosted dashboard"]

This is important because the hosted dashboard does not need direct access to the customer’s infrastructure.

The CLI executes where the data is actually available.

Why the Local Runner Matters

A hosted Forge service can directly query many external APIs, but it cannot automatically inspect a private server.

For example, a dashboard widget may want to display:

Production server disk usage

The Forge SaaS platform cannot normally run:

df -h /

on a user’s private Linux server.

The local Forge agent can.

flowchart LR
    A["Private Server"] --> B["Forge CLI / Agent"]
    B --> C["df / Docker / DB / local API"]
    C --> D["Structured result"]
    D --> E["Outbound HTTPS"]
    E --> F["Forge SaaS Dashboard"]

Only an outbound connection is required.

There is no need for Forge SaaS to open a connection into the private network.

That makes the model suitable for small companies and individual developers who want useful system visibility without deploying a larger monitoring stack.

Generate Once or Watch Continuously

The same Markdown source can therefore support two execution patterns.

Point-in-time generation

forge generate production.md

This executes the document once and produces a snapshot.

Continuous execution

forge agent production.md

This keeps selected widgets refreshed and sends their latest values to the hosted dashboard.

flowchart TD
    A["Forge Markdown"] --> B{"Execution mode"}

    B -->|"generate"| C["Run once"]
    C --> D["Generate Markdown"]
    D --> E["Optional PDF export"]

    B -->|"agent"| F["Run periodically"]
    F --> G["Publish widget state"]
    G --> H["Live hosted dashboard"]

The important part is that these are not two separate products.

They are two execution modes over the same source.

A Lightweight Publish Mode

A persistent agent does not even need to be the first implementation.

A simpler intermediate command could be:

forge publish production.md

That command would:

retrieve or read the Markdown,
execute the widgets locally,
send the resulting widget state to Forge SaaS,
update the dashboard,
exit.

The operating system can handle scheduling.

For example:

*/5 * * * * forge publish production.md

This would provide a dashboard refreshed every five minutes without requiring Forge to initially build a persistent daemon.

The progression can therefore be incremental:

flowchart LR
    A["forge generate"] --> B["forge publish"]
    B --> C["forge agent"]
    C --> D["Installed Forge runner service"]

Each stage adds capability without invalidating the previous one.

Elevated Execution Remains Local

One particularly useful property of the local execution model is that some widgets may inspect information requiring elevated privileges.

For example:

smartctl -H /dev/nvme0

or protected service information.

Forge should not silently escalate privileges.

Instead, the document can declare that a widget requires elevation:

type: shell
title: SMART Health
command: smartctl -H /dev/nvme0
elevation: required

The CLI can inspect the document before execution:

forge inspect production.md

and report which widgets require additional permissions.

Execution might then support options such as:

forge generate production.md --skip-elevated

or:

forge generate production.md --allow-elevation

The key security principle is:

The SaaS may request privileged execution, but only the local environment can approve it.

flowchart TD
    A["Markdown requests elevated action"] --> B["Forge CLI"]
    B --> C{"Approved locally?"}

    C -->|"Yes"| D["Execute with permitted elevation"]
    C -->|"No"| E["Skip or fail widget"]

    D --> F["Publish result"]
    E --> F

The user remains in control of the machine.

For persistent agents, it is preferable that the entire Forge process does not run as root. Individual approved actions can be elevated when necessary.

Turning the Dashboard Back into Documentation

The flow also works in reverse.

A user looking at the dashboard may want to capture its current state.

Forge can generate a Markdown snapshot using the latest published widget values.

flowchart LR
    A["Live Dashboard"] --> B["Generate Snapshot"]
    B --> C["Markdown document"]
    C --> D["Forge Library"]
    C --> E["PDF export"]

This creates a useful connection between operational visibility and documentation.

Examples might include:

release-readiness reports,
weekly engineering summaries,
deployment snapshots,
environment status reports,
incident records,
infrastructure inventories,
audit evidence.

The live view answers:

What does the system look like now?

The generated document answers:

What did the system look like at this point in time?

Static Context and Live Data Can Coexist

A Forge dashboard does not have to consist only of metrics.

Because the source is a document, static explanatory text and dynamic data can exist together.

For example:

## Redis

The Redis instance is intentionally undersized during beta.

:::
type: redis-memory
refresh: 1m
:::

The planned upgrade threshold is 85%.

The dashboard can display both the explanation and the current value.

That is useful because technical status rarely makes complete sense without context.

A conventional monitoring dashboard might tell someone that Redis memory is at 78%.

Forge can also explain why 78% is currently acceptable.

Not Another Prometheus or Grafana

This extension does not require Forge to become a full observability platform.

The aim is not to implement:

high-frequency metrics ingestion,
distributed tracing,
log aggregation,
long-term time-series storage,
metric query languages,
or complex alert-routing systems.

Forge can deliberately remain lightweight.

Its job is closer to:

retrieve → execute → structure → display → document

Where historical monitoring already exists, Forge can consume it.

A widget could retrieve information from Prometheus, CloudWatch, Grafana, or another source rather than replacing them.

This makes Forge useful both for developers who have no monitoring infrastructure and for teams that already do.

The Resulting Architecture

The resulting architecture extends the existing Forge model rather than replacing it.

flowchart TD
    A["Forge Tenant Library"] --> B["Markdown Source of Truth"]
    B --> C["Forge Editor"]
    B --> D["Forge CLI / Runner"]

    D --> E["Execute local widgets"]
    D --> F["Execute remote/API widgets"]

    E --> G["Structured widget results"]
    F --> G

    G --> H["Markdown renderer"]
    G --> I["Dashboard renderer"]

    H --> J["Generated Markdown"]
    J --> K["PDF export"]
    J --> L["Optional post back to library"]

    I --> M["Customisable hosted dashboard"]
    M --> N["Generate snapshot"]
    N --> J

The architecture retains the original strengths of Forge:

portable Markdown,
local execution,
reusable blocks,
document generation,
tenant-hosted source,
and optional publication back to the SaaS platform.

It adds:

structured widget output,
live or periodically refreshed state,
automatic dashboards,
visual dashboard layouts,
local runner execution,
dashboard snapshots,
and a path toward lightweight operational visibility.

The defining principle remains simple:

Define the technical state once in Markdown, execute it where the truth lives, display it live when useful, and generate a document whenever a durable snapshot is needed.