docs: sync SAT OpenAPI spec into api-docs and repair spec-lint CI

.github/workflows/deploy-docs.yml

@@ -5,6 +5,7 @@ on:
     branches: [main]
     paths:
       - 'asm/openapi.yaml'
+      - 'sat/openapi.yaml'
       - 'docs/**'
       - '.github/workflows/deploy-docs.yml'
   workflow_dispatch:
@@ -33,6 +34,7 @@ jobs:
           mkdir -p _site
           cp docs/index.html _site/index.html
           cp asm/openapi.yaml _site/asm-openapi.yaml
+          cp sat/openapi.yaml _site/sat-openapi.yaml
 
       - name: Setup Pages
         uses: actions/configure-pages@v5

.github/workflows/validate-openapi.yml

@@ -5,10 +5,14 @@ on:
     paths:
       - '*/openapi.yaml'
       - '*/openapi.json'
+      - '.spectral.yaml'
+      - '.github/workflows/validate-openapi.yml'
   pull_request:
     paths:
       - '*/openapi.yaml'
       - '*/openapi.json'
+      - '.spectral.yaml'
+      - '.github/workflows/validate-openapi.yml'
 
 jobs:
   spectral:
@@ -25,10 +29,15 @@ jobs:
       - name: Install Spectral
         run: npm install -g @stoplight/spectral-cli@6.16.0
 
+      # `spectral:oas` is the built-in ruleset, but it must be referenced via
+      # a ruleset file's `extends` (see .spectral.yaml) — passing it directly
+      # as `--ruleset spectral:oas` is not valid in spectral-cli 6.x and fails
+      # with "Could not read ruleset". Error-severity findings gate the build;
+      # warnings are advisory (matches the hailbytes-sat repo's lint policy).
       - name: Lint ASM OpenAPI spec
         if: ${{ hashFiles('asm/openapi.yaml') != '' }}
-        run: spectral lint asm/openapi.yaml --ruleset spectral:oas --fail-severity warn
+        run: spectral lint asm/openapi.yaml --ruleset .spectral.yaml --fail-severity error
 
       - name: Lint SAT OpenAPI spec
         if: ${{ hashFiles('sat/openapi.yaml') != '' }}
-        run: spectral lint sat/openapi.yaml --ruleset spectral:oas --fail-severity warn
+        run: spectral lint sat/openapi.yaml --ruleset .spectral.yaml --fail-severity error

.spectral.yaml

@@ -0,0 +1,13 @@
+# Spectral ruleset for the HailBytes API documentation specs.
+#
+# Extends the built-in OpenAPI ruleset. Note that `--ruleset spectral:oas`
+# is NOT a valid CLI reference in spectral-cli 6.x — the built-in ruleset
+# must be referenced from a ruleset file via `extends`, which is what this
+# file provides. The validate-openapi.yml workflow points at this file.
+#
+# Gating philosophy mirrors the hailbytes-sat repo: error-severity findings
+# block; warnings are advisory. This lets the specs stay faithful to the
+# real APIs — e.g. the SAT API genuinely uses trailing-slash paths
+# (`/campaigns/`), which trips the advisory `path-keys-no-trailing-slash`
+# rule but is correct.
+extends: ["spectral:oas"]

README.md

@@ -26,7 +26,7 @@ This repository contains the complete API reference, OpenAPI 3.1 specifications,
 | Path | Description |
 |------|-------------|
 | `asm/openapi.yaml` | OpenAPI 3.1 spec for the ASM REST API |
-| `sat/openapi.yaml` | OpenAPI 3.1 spec for the SAT REST API *(coming soon)* |
+| `sat/openapi.yaml` | OpenAPI 3.0 spec for the SAT REST API |
 | `mcp/` | MCP server definitions for ASM and SAT tool integrations *(coming soon)* |
 | `guides/` | Integration guides (SIEM, ticketing, MSSP multi-tenant) *(coming soon)* |
 | `sdk/` | SDK examples (Python, Go, TypeScript) *(coming soon)* |

asm/openapi.yaml

@@ -347,6 +347,7 @@ paths:
     get:
       operationId: listTags
       summary: List tags
+      description: Returns all organizational tags defined in the tenant.
       tags: [Tags]
       responses:
         '200':
@@ -365,6 +366,7 @@ paths:
     post:
       operationId: createTag
       summary: Create tag
+      description: Creates a new organizational tag that can be applied to assets.
       tags: [Tags]
       requestBody:
         required: true

docs/index.html

@@ -4,18 +4,73 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>HailBytes API Reference</title>
-    <meta name="description" content="Interactive REST API reference for HailBytes ASM (Attack Surface Management)." />
+    <meta name="description" content="Interactive REST API reference for HailBytes ASM (Attack Surface Management) and SAT (Security Awareness Training)." />
     <style>
-      body { margin: 0; padding: 0; }
+      body { margin: 0; padding: 0; font-family: Roboto, -apple-system, BlinkMacSystemFont, sans-serif; }
+      #nav {
+        display: flex;
+        align-items: center;
+        gap: 0.5rem;
+        padding: 0.6rem 1rem;
+        background: #1d2330;
+        border-bottom: 1px solid #11141c;
+        position: sticky;
+        top: 0;
+        z-index: 10;
+      }
+      #nav .brand { color: #fff; font-weight: 600; margin-right: 1rem; }
+      #nav button {
+        background: transparent;
+        color: #c2c9d6;
+        border: 1px solid transparent;
+        border-radius: 6px;
+        padding: 0.4rem 0.9rem;
+        font-size: 0.9rem;
+        cursor: pointer;
+      }
+      #nav button:hover { color: #fff; }
+      #nav button.active { background: #32507e; color: #fff; }
     </style>
   </head>
   <body>
-    <redoc spec-url="asm-openapi.yaml"
-           hide-download-button="false"
-           expand-responses="200,201"
-           required-props-first="true"
-           sort-props-alphabetically="false">
-    </redoc>
+    <div id="nav">
+      <span class="brand">HailBytes API Reference</span>
+      <button id="tab-asm" data-spec="asm-openapi.yaml">ASM &mdash; Attack Surface Management</button>
+      <button id="tab-sat" data-spec="sat-openapi.yaml">SAT &mdash; Security Awareness Training</button>
+    </div>
+    <div id="redoc-container"></div>
     <script src="https://cdn.jsdelivr.net/npm/redoc@2.5.3/bundles/redoc.standalone.js"></script>
+    <script>
+      var REDOC_OPTIONS = {
+        hideDownloadButton: false,
+        expandResponses: "200,201",
+        requiredPropsFirst: true,
+        sortPropsAlphabetically: false
+      };
+      var container = document.getElementById("redoc-container");
+
+      function loadSpec(specUrl) {
+        Redoc.init(specUrl, REDOC_OPTIONS, container);
+      }
+
+      function activate(btn) {
+        document.querySelectorAll("#nav button").forEach(function (b) {
+          b.classList.remove("active");
+        });
+        btn.classList.add("active");
+        loadSpec(btn.getAttribute("data-spec"));
+      }
+
+      document.querySelectorAll("#nav button").forEach(function (btn) {
+        btn.addEventListener("click", function () {
+          activate(btn);
+          history.replaceState(null, "", "#" + btn.id.replace("tab-", ""));
+        });
+      });
+
+      // Honour #asm / #sat deep links; default to ASM.
+      var initialId = location.hash === "#sat" ? "tab-sat" : "tab-asm";
+      activate(document.getElementById(initialId));
+    </script>
   </body>
 </html>