SYSTEM INFO
MDX Components and Style Reference
1. Purpose
This page is the canonical MDX authoring reference for ZAYAZ documentation. It demonstrates supported presentation patterns and records how reusable MDX components are made available.
It is not a canonical engine specification, schema contract, table contract, signal contract or architecture example. Data and identifiers used for visual demonstrations must not be interpreted as implementation requirements unless the example explicitly says it is backed by a canonical registry.
This distinction is important because repository tooling scans MDX source for component references. A fake component call inside a code fence can still be interpreted by a validator, extractor or preflight script as a live dependency.
Reference-page rules
- Live example — rendered on this page and backed by a real repository resource or registry.
- Syntax-only example — shown as inline code or escaped text and must not be interpreted as a live dependency.
- Global component — available to MDX through
docusaurus/src/theme/MDXComponents.js; no per-page import is required. - Local component — must be imported by the MDX document before it is rendered.
- Never add a fake live
Snippet,ExampleLink, schema, table, signal or ruleset merely to demonstrate syntax.
2. Globally available MDX components
The following components are currently registered through docusaurus/src/theme/MDXComponents.js and therefore do not require an import in each MDX page:
| Component | Typical purpose |
|---|---|
JiraChapterProgress | Page/chapter Jira progress |
ExampleLink | Link an MDX page to a file exposed by the examples/associated-file system |
DocExamplesMenu | Associated examples menu |
AuditEvidenceLink | Link to governed audit evidence |
Acronym | Resolve/display canonical acronym metadata |
RepoLinkIcon | Repository link affordance |
JiraNeed | Render a governed Jira Need reference |
2.1. Jira chapter progress — live
Syntax: <JiraChapterProgress scope="page" />
The component is rendered at the top of this page.
2.2. Acronym — live
We route hazard intelligence through ZHIF, while product-footprint documentation may reference PEF-ME.
Syntax: <Acronym id="PEF-ME" />
2.3. ExampleLink — syntax only unless an associated file exists
ExampleLink is global. Use it only when the referenced example actually exists for the document according to the examples plugin's resolution rules.
Syntax: <ExampleLink file="example.json" label="Example payload" />
Do not add a made-up live ExampleLink to this page just to illustrate the component.
3. Locally imported components
These components are imported by a document when needed. Keep imports minimal: importing a guarded component without using it is a CI error.
| Component | Import |
|---|---|
NodeMeta | import NodeMeta from '@site/src/components/NodeMeta'; |
TableSignals | import TableSignals from '@site/src/components/TableSignals'; |
TableGraphExplorer | import TableGraphExplorer from '@site/src/components/TableGraphExplorer'; |
StatusBadge | import StatusBadge from '@site/src/components/StatusBadge'; |
AudienceBlock | import AudienceBlock from '@site/src/components/AudienceBlock'; |
Tabs | import Tabs from '@theme/Tabs'; |
TabItem | import TabItem from '@theme/TabItem'; |
PdfLink | import PdfLink from '@site/src/components/PdfLink'; |
Modules | import Modules from '@site/src/components/Modules'; |
SchemaSnippet | import SchemaSnippet from '@site/src/components/SchemaSnippet'; |
RulesetSnippet | import RulesetSnippet from '@site/src/components/RulesetSnippet'; |
Snippet | import Snippet from '@site/src/components/Snippet'; |
ZayazEChart | import { ZayazEChart } from '@site/src/components/ZayazEChart'; |
SchemaLink also exists in the repository but is a legacy pattern. Prefer SchemaSnippet for current documentation unless a specific page has a justified reason to use SchemaLink.
4. Snippet — live verified example
Snippet resolves files relative to the MDX document's source_file under code/associated-files/.
This page has a real associated file at:
code/associated-files/system-info/style-examples/tags-integration.json
Therefore this is a valid live example:
{
"method_id": "GHG.intensity",
"version": "1.0.0",
"acl_tags": ["EU_ONLY", "NO_PHI"]
}
Copyable syntax: <Snippet file="tags-integration.json" showLineNumbers />
Important preflight behavior
npm run preflight-snippets scans MDX source for Snippet calls and verifies that referenced files exist. Do not put a fake multi-line <Snippet ... /> example in a fenced code block: current source scanning can still treat it as live.
For syntax-only documentation, use inline code as above or HTML-escaped markup.
5. SchemaSnippet — live
Use SchemaSnippet to show governed schema content rather than copying schemas manually into an MDX page.
[SchemaSnippet] Loading schema "zar/integrity_check_report.v1.schema.json" on client...
Syntax: <SchemaSnippet file="zar/integrity_check_report.v1.schema.json" title="Integrity Check Report — JSON Schema (v1)" showLineNumbers />
6. RulesetSnippet — syntax/reference behavior
RulesetSnippet is stage/ruleset aware and should only be rendered when the page has a real ruleset target that the component can resolve. This general style page intentionally does not pretend to own a DEV/STAGING/PROD ruleset.
Import:
import RulesetSnippet from '@site/src/components/RulesetSnippet';
Typical syntax:
<RulesetSnippet file="prod/MEID_EXAMPLE/ruleset-name-1_0_0.yaml" title="Ruleset title" showLineNumbers />
Replace the example path with a real governed ruleset key before rendering it live.
7. PDF links — live
Advanced Topic – IPCC Glossary (PDF)
Syntax: <PdfLink file="V0_2_Glossary.pdf">Link label</PdfLink>
8. Module views — live
Render one module:
Input Hub (inpt)
Domain: input-hub
Category: data-acquisition
Canonical data acquisition and onboarding domain for structured ESG input, system capability mapping, and signal capture.
Tags: core-module, csrd, esrs, traceability, white-label
Render modules matching a controlled tag:
Input Hub (inpt)
Domain: input-hub
Category: data-acquisition
Canonical data acquisition and onboarding domain for structured ESG input, system capability mapping, and signal capture.
Tags: core-module, csrd, esrs, traceability, white-label
Computation Hub (comp)
Domain: computation-hub
Category: analytics-modeling
Canonical computation and modeling domain for ESG calculations, simulations, extrapolation, aggregation, normalization, and decision-grade metric synthesis. Provides governed, auditable compute services to other modules (e.g., Reporting, Risk, Net Zero, ZARA).
Tags: core-module, decision-grade, traceability, white-label, csrd, esrs
Reports & Insights Hub (repo)
Domain: reports-insights-hub
Category: disclosure-insight
Canonical reporting, disclosure packaging, and insight delivery domain for CSRD/ESRS and related frameworks. Builds stakeholder-ready outputs, integrates trust and assurance signals, and supports structured export formats (e.g., XBRL/iXBRL) with audit-grade traceability.
Tags: core-module, decision-grade, traceability, white-label, csrd, esrs, assurance
Shared Intelligence Stack (siss)
Domain: shared-intelligence
Category: platform-orchestration
Foundational orchestration and intelligence layer that provides cross-module services for governance, trust, coordination, identity, localization, validation, audit logging, and system-wide interoperability across the ZAYAZ platform.
Tags: core-module, foundational, governance-grade, eu-ai-act-aligned, white-label-prohibited
ZARA — ZAYAZ Autonomous Reporting Assistant (zara)
Domain: ai-orchestration
Category: autonomous-reporting
Prompt-driven orchestration module that transforms user intent (e.g., 'Prepare CSRD report for 2025') into governed, auditable workflows across signals, forms, validation, policy generation, task routing, and final disclosure packaging.
Tags: core-module, decision-grade, prompt-to-impact, governance-grade, white-label, csrd, esrs, assurance
ZAAM — ZAYAZ Autonomous Agent Manager (zaam)
Domain: ai-agents
Category: agent-execution-management
Governed autonomous agent management module responsible for executing, coordinating, supervising, and constraining AI agents acting on behalf of users, teams, or the platform. ZAAM ensures agent actions remain auditable, role-aware, policy-bound, and aligned with ZAYAZ governance and trust requirements.
Tags: core-module, ai-agents, decision-grade, governance-grade, white-label, eu-ai-act-aligned, audit-first
Risk Intelligence Framework (risk)
Domain: governance-risk
Category: risk-intelligence
Decision-grade ESG risk identification, quantification, scenario analysis, and escalation.
Tags: core-module, decision-grade, governance-grade, white-label, csrd, esrs
NETZERO — Net-Zero Modeling & Transition Intelligence (netz)
Domain: climate-netzero
Category: transition-modeling
Decision-grade climate transition intelligence module that models baseline emissions, target pathways, abatement levers, cost curves, and uncertainty to support net-zero planning, CSRD/ESRS reporting, and board-level decarbonization strategy with audit-grade traceability.
Tags: core-module, decision-grade, governance-grade, white-label, csrd, esrs-e1, transition-plan, assurance
Verification & Assurance Module (vera)
Domain: assurance-verification
Category: trust-assurance
Decision-grade verification and assurance domain that orchestrates verifier workflows, evidence handling, trust scoring, audit trails, and assurance packaging across CSRD/ESRS and other frameworks. Enables third-party sign-off, dispute handling, and assurance-ready disclosure outputs with replayable provenance.
Tags: core-module, decision-grade, governance-grade, white-label, assurance, audit-first, csrd, esrs, verifier-network
SEEL — Stakeholder Engagement & Materiality (seel)
Domain: materiality-stakeholders
Category: double-materiality
Decision-grade stakeholder engagement and materiality assessment module that orchestrates stakeholder input collection, impact/financial materiality scoring, prioritization logic, and audit-grade evidence trails for CSRD/ESRS double materiality. Produces traceable materiality outcomes that drive reporting scope, risk intelligence, and governance decisions across ZAYAZ.
Tags: core-module, decision-grade, governance-grade, white-label, csrd, esrs, double-materiality, audit-first
EcoWorld Academy (acad)
Domain: education-training
Category: capability-building
Capability-building and credentialing module that delivers ESG training, assessments, certifications, and learning evidence trails. Links competence, role readiness, and policy adherence to platform trust, workflow permissions, and verifier confidence across ZAYAZ.
Tags: core-module, education, credentialing, governance-grade, white-label, audit-first, capacity-building
Vendor Performance Management (vend)
Domain: supplier-governance
Category: supply-chain-risk-compliance
Supplier-facing governance and intelligence module for onboarding, assessing, monitoring, scoring, and improving vendors across ESG, forced labour, CSDDD, CSRD, EUDR, Green Claims, carbon, evidence, and remediation workflows. VPM turns supplier due diligence into a continuous, auditable, AI-assisted performance management system linked to ZAYAZ risk, reporting, verification, and trust infrastructure.
Tags: core-module, supplier-governance, vendor-performance, forced-labour, csddd, csrd, eudr, green-claims, risk-intelligence, audit-first, white-label, verifier-ready, supplier-facing
Constitutional Governance (cgov)
Domain: constitutional-governance
Category: constitutional-knowledge-configuration
Canonical constitutional-understanding and configuration module governing how ZAYAZ represents organizations, resolves applicable industry and contextual knowledge, applies inheritance and provenance, and generates versioned constitutional configurations for downstream platform execution. The module owns Constitutional Organization Profiles, Industry Knowledge Profiles, and Constitutional Configurations while delegating policy authority, runtime assurance, computation, reporting, and autonomous orchestration to their respective modules.
Tags: core-module, canonical, platform, governance, audit-first, decision-grade, traceability, replay, constitutional, white-label
Pergamum Pulse (puls)
Domain: pergamum-pulse
Category: governed-knowledge-intelligence
Canonical governed knowledge acquisition, source capture, document interpretation, evidence addressing, semantic extraction, retrieval projection, change intelligence and historical knowledge-lifecycle module for ZAYAZ. Pergamum Pulse converts external and internal source material into traceable, rights-aware, versioned and HECATE-validatable knowledge while preserving immutable source lineage, human authority, Module lineage and Component lineage.
Tags: core-module, canonical, platform, knowledge-governance, audit-first, decision-grade, traceability, replay, human-in-the-loop, white-label
CUEM — Commercial Usage & Entitlement Module (cuem)
Domain: commercial-usage-entitlement
Category: commercial-accounting
Proposed platform-wide commercial usage and entitlement architecture for governed metering, contractual entitlements and allowances, rating, commercial ledgers, attributable costs, invoice aggregation, white-label settlement, reconciliation, replay, and unit-economics analytics. OMR output names are architecture-level output families only; CUEM owns no canonical artifact domain until the required Artifact Constitution and artifact-registry governance is completed.
Tags: core-module, canonical, platform, foundational, governance-grade, audit-first, traceability, white-label
Syntax:
<Modules id="input-hub" /><Modules tag="core-module" />
9. NodeMeta — live
NodeMeta is useful for registry-driven metadata views. The ID supplied must resolve to a real canonical node.
Engine Metadata
No registry entry found for pef-me yet.
Syntax: <NodeMeta id="pef-me" />
10. TableSignals — live
TableSignals accepts the table prop. Do not use the historical tableName form.
compute_executionsDraft| Signal | Type | Example | Description |
|---|---|---|---|
caller_ip | TEXT | 192.168.14.52, 15.188.110.23 | Source IP for security / anomaly analysis. |
created_at | TEXT | 2025-02-01T10:14:33Z, 2025-02-01T10:14:34Z | Execution timestamp (UTC). |
dataset_hashes | TEXT | IPCC-EFDB:sha256-a123bc9f1d92f12398fabc77bb38d99f2c91afbd5311a37d,IEA_SSP:sha256-98231acd19fa0287fb29c8ff093a772cd44aa2bc1faff391, UN_FAO_WATER:sha256-71ab3cd19fa0aa77fb29c8ff093a772cd44aa2135d1ac191 | Array/map of dataset artifact hashes used (e.g., ['IPCC-EFDB:sha256-...','IEA_SSP:sha256-...']). |
error_code | TEXT | null, SCHEMA_VALIDATION_FAILED | Machine-readable error code if status='error' (e.g., SCHEMA_VALIDATION_FAILED). |
exec_id | string (pk) | 01J9Z9K4M2F7W7N4Q7ZJ9V9XGF, 01J9Z9KCN4AMJ5T2W6S5XYF4E9 | Globally unique execution ID (ULID). Primary key. |
inputs_hash | TEXT | sha256:3fa42eab87cbdd29d8fd0c9a8bd1cb6a543920d8e16c08c28a1c78c9231e4b92, sha256:a128ab769e12ba91bb221b0a8afbd5311a37d4a0e366620eefb4e32976cf81aa | Cryptographic hash (e.g., sha256:...) of normalized input payload. |
latency_ms | TEXT | 143, 212 | End-to-end compute latency in milliseconds. |
method_id | TEXT | MID-00001, MID-00042 | Method ID (e.g., MID-00001). FK part 1 → ref_compute_method_registry.method_id. |
options_hash | TEXT | sha256:92f8aa769e12b2a3bfb2f2c91afbd5311a37d4a0e366620eefb4e32976c029d2, sha256:81aeaa769e12f89dfbb2f2c91afbd5311a37d4a0e366620eefb4e32976acc2b0 | Cryptographic hash of normalized options payload. |
output_hash | TEXT | sha256:4cd920fa8912a4627bb9eab32c5fdd314ff2a119e80cc291eabe927caae123ef, sha256:f12920fa8912ff111bb9eab32c5fdd314ff2a119e80cc291eabe927caac44ab1 | Cryptographic hash of normalized output payload. Optional if execution failed pre-output. |
provenance_id | TEXT | prov-7f892b1a3cdd4e8f8fba2e, prov-c102aa39efdd4694948df2 | Correlation ID returned to caller; links UI/API to this audit row. |
region | TEXT | eu-north-1, eu-central-1 | Region tag where compute ran (e.g., eu-north-1). |
status | TEXT | ok, error | ok | error. Final outcome. |
storage_ref | TEXT | s3://zayaz-computations/exec/01J9Z9K4M2F7W7N4Q7ZJ9V9XGF/input_output.json, s3://zayaz-computations/exec/01J9Z9KCN4AMJ5T2W6S5XYF4E9/input_output.json | Pointer to sealed blob with full input/output snapshots if retained. |
tenant_id | TEXT | eco-197-123-456-789, eco-044-001-882-331 | Tenant/customer identifier (used for multi-tenant isolation and audit). |
version | TEXT | 1.1.2, 1.0.0 | Exact version used (e.g., 1.0.0). FK part 2 → ref_compute_method_registry.version. |
Syntax: <TableSignals table="dim_countries" />
The table identifier should be canonical and should resolve in the signal/table registry used by the component.
11. TableGraphExplorer — live
Loading table relationship graph…
Syntax: <TableGraphExplorer focusTable="fact_pef_run" depth={2} height={520} showLegend={true} />
Use real table identifiers; this component is intended to visualize known graph relationships rather than define new ones.
12. StatusBadge — live
Inline examples:
- Experimental Experimental
- Stable Stable
Syntax: <StatusBadge status="stable" />
Use only statuses supported by the current component / lifecycle vocabulary.
13. AudienceBlock — live
Syntax: <AudienceBlock audience={['internal','developer']}>…</AudienceBlock>
14. Tabs and TabItem — live
- Client
- Verifier
- Authority
Client-facing content.
Verifier-facing content.
Authority-facing content.
Required imports:
import Tabs from '@theme/Tabs';import TabItem from '@theme/TabItem';
Use Tabs for genuine alternative views; do not hide mandatory requirements inside a tab that a reader may never open.
15. Docusaurus admonitions
No local component import is required for standard Docusaurus admonition syntax.
Use note for neutral supporting information.
Use tip for recommended practice or efficiency guidance.
Use info for contextual information that deserves emphasis.
Use warning when incorrect use can create significant documentation or implementation problems.
Use danger for high-impact safety, integrity, governance or production risks.
16. ZAYAZ custom callouts
Warning callout
This is a visual example. A production warning should describe a real governed condition.
Success callout
Use success styling for a verified completed state, not an assumption.
Information callout
This is contextual information.
Chat / prompt callout
How can I reduce GHG emissions by 20% by 2030?
17. Standard Markdown / MDX patterns
Internal link
External link with explicit browser behavior
<a href="https://example.com" target="_blank" rel="noopener noreferrer">External reference</a>
Superscript
E-C-O<sup>™</sup> Number renders as E-C-O™ Number.
Details / disclosure
Open supporting detail
Supporting material can be hidden until required, but canonical requirements should not be buried unnecessarily.
18. TODO markers — syntax only
This reference page must not create live migration debt merely by demonstrating TODO syntax. The examples are therefore escaped.
| Marker | Meaning |
|---|---|
<!-- ZAYAZ-TODO: STRUCTURE --> | Structural review required |
<!-- ZAYAZ-TODO: ADD-CMID --> | Canonical metric ID unresolved |
<!-- ZAYAZ-TODO: ADD-FK --> | Foreign-key relationship unresolved |
<!-- ZAYAZ-TODO: LINK-SSSR --> | Signal-registry relationship unresolved |
<!-- ZAYAZ-TODO: DATA-SOURCE --> | Authoritative data source unresolved |
<!-- ZAYAZ-TODO: EVIDENCE --> | Evidence/audit path unresolved |
<!-- ZAYAZ-TODO: POLICY --> | Policy relationship unresolved |
<!-- ZAYAZ-TODO: HECATE --> | Implementation contract not yet Hecate-ready |
See doc-transfer.mdx for the governed migration semantics of these markers.
19. Components that should normally be demonstrated elsewhere
Some components exist but are context-heavy or require specialized data contracts. This page records their availability without manufacturing fake data to make them render.
ZayazEChart
Import: import { ZayazEChart } from '@site/src/components/ZayazEChart';
Use a real chart configuration and dataset from the chart/document family. Do not introduce a fake chart contract here merely to satisfy an import.
RulesetSnippet
Import: import RulesetSnippet from '@site/src/components/RulesetSnippet';
Use a real stage/ruleset key in a ruleset-owning document.
SchemaLink — legacy
Import: import SchemaLink from '@site/src/components/SchemaLink';
Prefer SchemaSnippet for new governed schema documentation unless the legacy link behavior is specifically required.
20. Validator behavior authors must remember
Import guard
scripts/check-mdx-component-imports.mjs guards several commonly injected imports. If a guarded component is imported but not referenced in the MDX source, CI fails. Therefore:
- import only components the page actually renders;
- do not add imports as a generic boilerplate header;
- this reference page lists additional imports as inline code rather than importing unused components.
Snippet preflight
scripts/preflight-snippets.cjs resolves a Snippet through:
source_file
↓
code/associated-files/<source_file without .mdx>/
↓
Snippet file
A live example must point to an actual file in that derived directory.
Global MDX components
Before adding an import for ExampleLink, Acronym, JiraChapterProgress, JiraNeed, AuditEvidenceLink, RepoLinkIcon or DocExamplesMenu, check docusaurus/src/theme/MDXComponents.js. These are currently global and ordinarily should not be imported per page.
21. Maintaining this reference
When adding a new reusable MDX feature:
- Confirm the implementation exists in the current repository.
- Determine whether it is global or requires a local import.
- Determine whether rendering it requires a real registry, schema, table, signal, associated file or ruleset.
- Prefer a live example backed by real safe reference data.
- If a real example would create false architecture or dependencies, use a syntax-only example instead.
- Add the import/reference pattern here.
- Run the normal PR validation machinery.
- If a validator flags this page, fix the example/reference design rather than weakening the validator merely to accommodate demonstration content.
This page should remain useful as a copy/reference catalog while also being safe to scan as canonical MDX.