Transferring Text to MDX

0. IMPORTANT: Update the frontmatter of all engines!

Add the following to the frontmatter (example data):

engine_data:
  meid: MEID_ASRE01_v2
  engine_kind: micro_engine
  engine_type:  #VALI — Validation Engines, TRFM — Transformation Engines, AGGR — Aggregation Engines, SEM — Stochastic Extrapolation Module
  owner: computation-hub
  category: general
  sub_category: environmental/energy
  related_engines:
    - name: a
    - name: b
    - name: c
  tables: 
    - name: aaa
      role: input
      excel: 
        data_file_id: aaa # explicit form (same id)
        sheet: Sheet1
        range: A1:D40
    - name: bbb
      role: input
      excel: 
        data_file_id: bbb # explicit form (same id)
        sheet: Sheet1
        range: A1:C60
    - name: ccc
      role: input
      excel: 
        data_file_id: ccc # explicit form (same id)
        sheet: Sheet1
        range: A1:Q60
  zssr:
    routes:
      - zssr.mice.environmental.energy.assr
  telemetry:
    topic:
      - assr
      - lca
      - efdb
  api_endpoint:
    run: /api/aggr/run
    validate: /api/aggr/validate

Empty (for easier copying):

engine_data:
  meid: 
  engine_kind: 
  engine_type:  #VALI — Validation Engines, TRFM — Transformation Engines, AGGR — Aggregation Engines, SEM — Stochastic Extrapolation Module
  owner: 
  category: 
  sub_category: 
  related_engines:
    - name: 
    - name: 
    - name: 
  tables: 
    - name: 
      role: 
      excel: 
        data_file_id: 
        sheet: 
        range: 
    - name: 
      role: 
      excel: 
        data_file_id: 
        sheet: 
        range: 
    - name: 
      role: 
      excel: 
        data_file_id: 
        sheet: 
        range: 
  zssr:
    routes:
      - 
  telemetry:
    topic:
      - 
      - 
      - 
  api_endpoint:
    run: 
    validate: 

Examples of usage:

Engine Metadatareview

ID: AGGR
Code: MICE_AGGR
MEID: MEID_ASRE01_v2
Type: micro_engine
Engine Type: VALI
Name: Aggregation Engines
Version: 0.1

Engine Capabilities

API: run: /api/aggr/run · validate: /api/aggr/validate
ZSSR Routes: zssr.mice.environmental.energy.assr
Telemetry Topics: assr, lca, efdb
Related Engines: a, b, c

Operational Metadata

{
  "id": "AGGR",
  "engine_kind": "micro_engine",
  "engine_type": "VALI",
  "title": "Aggregation Engines",
  "name": "Aggregation Engines",
  "meid": "MEID_ASRE01_v2",
  "code": "MICE_AGGR",
  "owner": "computation-hub",
  "category": "general",
  "subCategory": "environmental/energy",
  "lifecycle": {
    "status": "review",
    "semver": "0.1"
  },
  "related_engines": [
    "a",
    "b",
    "c"
  ],
  "zssr_routes": [
    "zssr.mice.environmental.energy.assr"
  ],
  "telemetry_topics": [
    "assr",
    "lca",
    "efdb"
  ],
  "api": {
    "run": "/api/aggr/run",
    "validate": "/api/aggr/validate"
  },
  "slug": "/micro-engines/aggregation-engines",
  "source_file": "/computation-hub-calcs/micro-engines/aggregation-engines.mdx",
  "hub": "computation-hub-calcs",
  "module": "aggr",
  "api_endpoint": {
    "run": "/api/aggr/run",
    "validate": "/api/aggr/validate"
  }
}

Graph View

AGGR depends on:

See also the Engines Registry.

1. Do hybrid batch work

👉 Migrate content in batches of ~5–8 chapters, and immediately do a “linking & grounding pass” for that batch before moving on.

That gives you:

Speed (batching)
Accuracy (context still fresh)
Structural integrity (foreign keys, CMIDs, signals don’t drift)

Avoid both extremes:

❌ Linking everything immediately (too slow)
❌ Migrating everything first (you’ll forget intent)

Why This Matters in The System (not generic docs) The manual is not prose-heavy documentation. It’s a knowledge graph with:

CMIDs
SSSR signals
Tables
Engines
Policies
Evidence chains
Search + Ask ZARA as consumers

That means linking is not cosmetic—it defines semantics.

If linking is you deferred too long:

You’ll lose why a table existed
CMIDs will drift from intent
You’ll re-read chapters multiple times
You’ll “paper over” missing structure instead of fixing it cleanly

2. The Optimal Workflow (Proven on Complex Manuals)

Phase 1 — Content Migration (Fast, Clean)

For each chapter:

Move text over
Light cleanup only (headings, lists, clarity)
DO NOT over-link
Add placeholders, not links

Example placeholders:

This keeps momentum high.

Phase 2 — Immediate Grounding Pass (Critical)

After 5–8 chapters, stop and do a grounding pass: For each chapter:

Identify:
CMIDs referenced
Tables implied
Signals used
Engines involved
Add:
<TableSignals />
<AuditEvidenceLink />
Cross-links
Foreign-key references

Because:

You still remember why things were written
You can normalize patterns across chapters
You catch inconsistencies early

Phase 3 — Structural Normalization (Light, Fast)

After grounding the batch:

Align naming
Ensure consistent CMID usage
Check signal/table reuse
Update registries if needed

This is where the system starts to self-reinforce.

3. A Concrete Rule of Thumb

Use this heuristic:

If you can still explain the chapter to someone else without re-reading it, you can still link it correctly.

Once you can’t, linking quality drops sharply.

That usually happens after ~8 chapters.

4. Practical Guardrails (Very Important)

4.1. Never leave a chapter “structurally ambiguous”

Even if links aren’t added yet, leave markers:

You can later grep for these. (See ch 5.)

4.2. Treat tables as first-class citizens

If a chapter uses data:

Either link the table now
Or explicitly mark:

Silence is dangerous.

4.3. CMIDs: batch-resolve, don’t guess

When migrating:

Write the concept in text
Resolve to CMID during grounding pass

This avoids premature CMID fragmentation.

4.4. Why This Is the Right Pace?

We’ve already built:

Registries
Search
Evidence links
Live graphs
Asset linking
Audience gating

That means structure work compounds.

Doing it in disciplined batches lets:

Search improve incrementally
Ask ZARA get smarter as we go
Errors surface early, not at the end

5. Standardized Markers

To manage deferred structure work we use specific markers in the text. Think of those comments as first-class TODO markers and reliably surface them later.

HTML comments like:

Marker	Meaning
`<!-- ZAYAZ-TODO: STRUCTURE -->`	Needs structural review
`<!-- ZAYAZ-TODO: ADD-CMID -->`	Metric not yet canonical
`<!-- ZAYAZ-TODO: ADD-FK -->`	Foreign key / table relation missing
`<!-- ZAYAZ-TODO: LINK-SSSR -->`	Signal registry link missing
`<!-- ZAYAZ-TODO: DATA-SOURCE -->`	Underlying data not identified
`<!-- ZAYAZ-TODO: EVIDENCE -->`	Audit evidence path missing
`<!-- ZAYAZ-TODO: POLICY -->`	Connect/link to Policy.

are:

✅ Ignored by Docusaurus rendering
✅ Preserved in MDX
✅ Searchable via scripts / grep
✅ Non-destructive (won’t break builds)
✅ Version-controllable

Optinally add a message:

`<!-- ZAYAZ-TODO: ADD-FK | Link dim_countries.iso_cc_id -> fact_emissions.country_id -->`

5.1. How to Get a List Later (Multiple Options)

Option 1 — Simple grep (fastest) From repo root:

grep -R "<!-- STRUCTURE REVIEW REQUIRED -->" content/

Or all structural markers at once:

grep -R "<!-- ZAYAZ-TODO: " content/ | grep -E "STRUCTURE|ADD-CMID|ADD-FK|LINK-SSSR|DATA-SOURCE|EVIDENCE"

Example output:

content/computation-hub-calcs/rif/risk-calibration.mdx:<!-- ZAYAZ-TODO: ADD-CMID -->
content/policies/env/climate-change.mdx:<!-- ZAYAZ-TODO: ADD-FK -->

Clean extract:

grep -R "<!-- ZAYAZ-TODO:" content/

This is future-proof for:

Building a report
Turning them into GitHub issues
Showing a “documentation completeness dashboard”

6. Search, Ask ZARA and ToDo — How to Use

6.1. Search

Use the search field to find relevant ZAYAZ documentation using semantic search.

You can:

Search by concepts, not just exact words

e.g. carbon passport lifecycle

Filter by section context automatically (engine, module, appendix)
Search for work-in-progress items using TODO markers:
todo → all documents with open TODOs
todo:STRUCTURE → only structure-related TODOs
todo:STRUCTURE,ADD_FK → documents matching all listed tags

Search results return the most relevant sections, not entire documents.

6.2. Ask ZARA

Ask ZARA is an AI assistant grounded only in the indexed ZAYAZ documentation.

You can:

Ask technical or conceptual questions

“How does FIRM model transition risk?”

Ask about incomplete areas

“What is missing in the ESG signal registry?”

Ask about TODOs and gaps

>“What STRUCTURE TODOs exist in the AI Intelligence Layer?”

ZARA will:

Cite relevant document sections when possible
Explicitly say when information is missing or incomplete
Never invent undocumented behavior

User query	Result
todo	All docs with any TODO
todo:any	All docs with any TODO
todo:STRUCTURE	Only docs with `<!-- ZAYAZ-TODO: STRUCTURE -->`
todo:STRUCTURE,ADD_FK	Docs that contain both tags
todo + normal words	(Intentionally not allowed — keeps syntax strict)
Normal question	Falls back to semantic search

6.3. Best Practice

Use Search to explore and scan
Use Ask ZARA to synthesize, explain, or identify gaps
Use  markers in docs to surface future work automatically

6.4. Search Syntax (Operators)

Operator	Example	Meaning
todo	todo	Return any doc section that contains at least one marker
todo:TAG	todo:STRUCTURE	Only docs that have the TODO tag STRUCTURE
todo:TAG1,TAG2	todo:STRUCTURE,ADD_FK	Docs that contain all listed TODO tags
CMID lookup	CMID-ZARA-00001	Finds pages/sections where the CMID was indexed
Slug scope	filterSlugPrefix="/ai-intelligence-layer"	API filter to restrict search to a subtree (UI can expose this later)
Type scope	filterSourceType="mdx"	API filter to limit to MDX vs JSON vs Excel docs

GitHub Repo Request for Change (RFC)

0. IMPORTANT: Update the frontmatter of all engines!​

Engine Metadatareview

Engine Capabilities

1. Do hybrid batch work​

2. The Optimal Workflow (Proven on Complex Manuals)​

Phase 1 — Content Migration (Fast, Clean)​

Phase 2 — Immediate Grounding Pass (Critical)​

Phase 3 — Structural Normalization (Light, Fast)​

3. A Concrete Rule of Thumb​

4. Practical Guardrails (Very Important)​

4.1. Never leave a chapter “structurally ambiguous”​

4.2. Treat tables as first-class citizens​

4.3. CMIDs: batch-resolve, don’t guess​

4.4. Why This Is the Right Pace?​

5. Standardized Markers​

5.1. How to Get a List Later (Multiple Options)​

6. Search, Ask ZARA and ToDo — How to Use​

6.1. Search​

6.2. Ask ZARA​

6.3. Best Practice​

6.4. Search Syntax (Operators)​