feat(doc): add schema doc generator and initial Docusaurus content

.github/workflows/docs-preview.yml

@@ -0,0 +1,46 @@
+name: Docs Preview
+on:
+  push:
+    branches: [doc_next]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "docs-preview"
+  cancel-in-progress: true
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          submodules: recursive
+
+      - name: Install Node dependencies
+        run: npm ci
+
+      - name: Build Docusaurus site
+        env:
+          DOCUSAURUS_URL: https://dhower-qc.github.io
+          DOCUSAURUS_BASE_URL: /riscv-unified-db/
+        run: npm run build --workspace=doc
+
+      - name: Setup Pages
+        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
+        with:
+          path: doc/build
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

.github/workflows/regress.yml

@@ -1003,6 +1003,21 @@ jobs:
       run: docker load --input ${{ runner.temp }}/docker_image.tar
     - name: Check schema versions against published URLs
       run: "./do gen:schemas && ./bin/ruby tools/scripts/check_schema_versions.rb"
+  regress-schema-docs:
+    runs-on: ubuntu-latest
+    needs: build-container
+    steps:
+    - name: Clone Github Repo Action
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+    - name: Download docker image
+      uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+      with:
+        name: docker_image
+        path: "${{ runner.temp }}"
+    - name: Load image
+      run: docker load --input ${{ runner.temp }}/docker_image.tar
+    - name: Generate schema documentation
+      run: "./bin/chore gen -f schema-docs"
   build-idl-doc:
     runs-on: ubuntu-latest
     needs: build-container
@@ -1101,6 +1116,7 @@ jobs:
     - build-instruction-appendix
     - build-profile
     - regress-schema-versions
+    - regress-schema-docs
     - build-idl-doc
     - regress-gem-version-bump
     - build-docs-site

bin/chore

@@ -108,6 +108,7 @@ gen_subcmd_usage() {
   echo "  vscode-idl:    Generate tools/vscode/idl/syntaxes/idl.tmLanguage.json"
   echo "  regress:       Generate .github/workflows/regress.yml"
   echo "  ruby-type-def: Generate Ruby type signatutres"
+  echo "  schema-docs:   Generate schema documentation from JSON Schema files"
   echo ""
 }
 
@@ -281,6 +282,30 @@ do_gen_vscode_idl() {
   fi
 }
 
+#
+# Generate schema documentation from JSON Schema files
+#
+do_gen_schema_docs() {
+  source_setup
+  echo "Generating schema documentation"
+  if [ $fail_on_change -eq 1 ]; then
+    # Calculate checksum before generation
+    local sha_before
+    sha_before=$(find "$UDB_ROOT"/doc/docs/schemas -type f -name "*.mdx" -exec sha256sum {} \; 2>/dev/null | sort | sha256sum)
+  fi
+  $RUBY -I tools/ruby-gems/schema_doc_gen/lib tools/ruby-gems/schema_doc_gen/bin/schema-docs-all \
+    --schema-dir "$UDB_ROOT/spec/schemas" \
+    --output-dir "$UDB_ROOT/doc/docs/schemas" \
+    --generate-index
+  if [ $fail_on_change -eq 1 ]; then
+    local sha_after
+    sha_after=$(find "$UDB_ROOT"/doc/docs/schemas -type f -name "*.mdx" -exec sha256sum {} \; 2>/dev/null | sort | sha256sum)
+    if [ "$sha_before" != "$sha_after" ]; then
+      exit 1
+    fi
+  fi
+}
+
 #
 # Generate all development artifacts
 #
@@ -289,6 +314,7 @@ do_gen_all() {
   do_gen_vscode_idl
   do_ruby_type_def all
   do_gen_xqci_golden
+  do_gen_schema_docs
 }
 
 #
@@ -568,6 +594,10 @@ case "$subcommand" in
         do_gen_regress
         exit 0
         ;;
+      schema-docs )
+        do_gen_schema_docs
+        exit 0
+        ;;
       ruby-type-def )
         gem=all
         while getopts ":hg:" opt; do # Go through the options

doc/docs/concepts/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Concepts",
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "description": "Core concepts for working with the RISC-V Unified Database."
+  }
+}

doc/docs/concepts/configurations/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Configurations",
+  "position": 1,
+  "link": {
+    "type": "generated-index",
+    "description": "Understanding configuration files in UDB."
+  }
+}

doc/docs/concepts/configurations/overview.md

@@ -0,0 +1,124 @@
+---
+sidebar_position: 1
+status: in-progress
+---
+
+# Configurations Overview
+
+:::warning[Status: In Progress]
+This documentation is partially complete. Some sections may be missing or outdated.
+:::
+
+A **configuration** is a YAML file that describes a RISC-V system or family of systems by specifying which extensions are implemented, what their parameter values are, and how implementation-defined behavior is resolved. Configurations control how UDB generates artifacts — from fully general tools to highly specialized ISS code — and also provide a **standard machine-readable format** for precisely describing RISC-V implementations (used, for example, in RISC-V certification applications).
+
+Configurations are also where **spec overlays** are enabled, allowing vendor-specific customizations to be applied on top of the standard specification data (see [The Data Pipeline](../data-pipeline/overview.md)).
+
+:::tip Schema Reference
+For the complete technical schema definition including all fields and validation rules, see the [Configuration Schema Reference](/docs/schemas/v0.1/config_schema).
+:::
+
+## Why Configurations Exist
+
+The RISC-V ISA is highly modular and leaves many details up to implementers:
+
+- **Extension selection**: Does this system support floating-point? Vector? Compressed instructions?
+- **MXLEN**: Is this a 32-bit or 64-bit M-mode machine (or does it support both)?
+- **Parameters**: How wide is the physical address space? Are misaligned accesses supported? What exceptions are reported in `mtval`?
+- **Optional features**: Is the `misa` CSR implemented? Can extensions be dynamically enabled/disabled?
+
+UDB's specification data describes **all possible behaviors** across the entire RISC-V design space. A configuration lets you specify **how much you know** about the target system — from nothing (the full design space) to everything (a specific implementation) — and UDB generates artifacts appropriate to that level of specificity.
+
+## The Three Types of Configurations
+
+UDB supports three levels of specificity, each serving different use cases:
+
+### 1. Fully Configured (`type: fully configured`)
+
+**Specifies every parameter and extension** — represents a single concrete implementation.
+
+Every implementation-defined choice is pinned to a value. This is what you use to model a real hardware design or generate an ISS for a specific chip.
+
+**Example**: `cfgs/mc100-32-full-example.yaml` — a complete MC100-32 processor configuration with all extensions, parameters, and CSR behaviors fully specified.
+
+**Use cases**:
+- Generating a configuration-specific ISS for a shipping product
+- Producing documentation for a specific chip
+- Validating that a design conforms to a RISC-V profile
+- Submitting a design for certification
+
+**Key property**: All IDL code can be fully evaluated and optimized; no unknowns remain. Generated artifacts are tailored to this exact configuration.
+
+### 2. Partially Configured (`type: partially configured`)
+
+**Specifies some parameters and extensions, leaving others unspecified** — represents a family of implementations that share common characteristics.
+
+**Example**: `cfgs/rv32.yaml` — specifies `MXLEN: 32` and requires the `I` and `Sm` extensions, but leaves all other parameters and optional extensions unspecified. This describes "any RV32 system."
+
+**Use cases**:
+- Generating documentation or test suites that apply to a range of implementations
+- Building tools for a product line or processor family
+- Exploring "what if" scenarios (e.g., "what instructions are available if we add the `V` extension?")
+- Defining a baseline for vendor-specific customization
+
+**Key property**: Some IDL expressions can be evaluated (those depending only on known parameters), but code paths that depend on unknown parameters remain conditional. Generated artifacts must handle the full range of possibilities for unspecified parameters.
+
+### 3. Unconfigured (`type: unconfigured`)
+
+**Specifies nothing** — represents the entire RISC-V design space with no constraints.
+
+The special configuration **`_`** (underscore) is the canonical unconfigured architecture.
+
+**Example**: `cfgs/_.yaml` — describes "any RVI-standard architecture" with no parameters set, not even `MXLEN`.
+
+**Use cases**:
+- Generating the full RISC-V specification manual (covering all possible behaviors)
+- Building general-purpose tooling that works across all RISC-V systems (assemblers, disassemblers, debuggers)
+- Studying the full scope of the ISA without implementation assumptions
+- Generating schemas and abstract models
+
+**Key property**: No IDL expressions can be evaluated at compile time; all parameter-dependent behavior must be preserved in generated artifacts. Generated code must be maximally generic.
+
+## Configuration File Structure
+
+All configuration files share a common YAML structure:
+
+```yaml
+$schema: config_schema.json#
+kind: architecture configuration
+type: fully configured | partially configured | unconfigured
+name: MyConfig
+description: A brief description of this configuration
+
+# Full configs only: exact extensions and versions
+implemented_extensions:  # Omit for partial/unconfigured
+  - [ExtName, "version"]
+
+# Partial configs only: minimum extension requirements
+mandatory_extensions:  # Omit for full/unconfigured
+  - name: "ExtName"
+    version: ">= min_version"
+
+# All configs: parameter values
+params:  # Omit for unconfigured
+  PARAM_NAME: value
+
+# Optional: spec overlay directory
+arch_overlay: path/to/overlay  # See Config File Format and Data Pipeline
+```
+
+:::note
+`arch_overlay` is the current name for the spec overlay feature. This will be renamed to `spec_overlay` in a future version for clarity.
+:::
+
+See [Config File Format](./config-file-format.md) for the complete reference.
+
+## What's Next
+
+More detailed documentation on configurations is coming soon, including:
+
+- Full Configurations — Detailed format and examples
+- Partial Configurations — Specifying requirements without full detail
+- Unconfigured — The `_` config and when to use it
+- Config File Format — Complete YAML reference
+- Validating Configs — Checking compliance and catching errors
+

doc/docs/idl/builtins.mdx

@@ -16,10 +16,10 @@ Two special variables give access to the current instruction's context. They are
 
 ```idl
 # $pc: use the current PC to compute a branch target
-jump(PC + $signed(imm));
+jump($pc + $signed(imm));
 
 # $encoding: pass the current instruction encoding to a memory access
-X[xd] = read_memory<32>(virtual_address, $encoding);
+X[xd] = read_memory(32, virtual_address, $encoding);
 
 # raise() uses $encoding as the tval for illegal instruction exceptions
 raise(ExceptionCode::IllegalInstruction, mode(), $encoding);

doc/docs/idl/common-misunderstandings.mdx

@@ -37,7 +37,7 @@ See [Naming Rules](./variables#naming-rules).
 `if (x)` is a compilation error. An `if` condition must have type `Boolean`. You must write an explicit comparison:
 
 ```idl
-XReg src1 = X[rs1];
+XReg src1 = X[xs1];
 
 if (src1 != 0) { ... }  # correct
 # if (src1) { ... }     # compilation error
@@ -135,7 +135,7 @@ A Verilog-style literal with an explicit width that is too narrow to hold the va
 
 ```idl
 Bits<4> x = 4'd-1;   # -1 in 4 bits = 0b1111 = 15 (unsigned) — OK
-Bits<3> y = 3'd-1;   # truncates to 3 bits: 0b111 = 7 — sign bit lost
+Bits<3> y = 4'd-1;   # truncates to 3 bits: 0b111 = 7 — sign bit lost
 ```
 
 When encoding negative values, ensure the width is sufficient to hold the sign bit. Or use the 2's complement positive equivalent:

doc/docs/idl/control-flow.mdx

@@ -13,7 +13,7 @@ An `if` statement condition must be a `Boolean` type.
 Unlike C, a non-zero integer does **not** count as `true`. Using an integer directly as a condition is a compilation error — you must write an explicit comparison:
 
 ```idl
-XReg src1 = X[rs1];
+XReg src1 = X[xs1];
 
 if (src1 != 0) { ... }  # correct: explicit comparison
 # if (src1) { ... }     # compilation error: src1 is not Boolean

doc/docs/idl/data-types.mdx

@@ -1,8 +1,13 @@
 ---
 sidebar_position: 2
 title: Data Types
+status: complete
 ---
 
+:::info[Status: Complete]
+This documentation is complete and ready to use.
+:::
+
 IDL has the following types:
 
 - **Primitive**