docs: add node1 runbooks, consolidation artifacts, and maintenance scripts

2026-02-19 00:14:27 -08:00
parent c57e6ed96b
commit 544874d952
586 changed files with 14065 additions and 22 deletions
--- a/docs/contracts/clan-visibility-guard.openapi.yaml
+++ b/docs/contracts/clan-visibility-guard.openapi.yaml
@@ -0,0 +1,164 @@
+openapi: 3.1.0
+info:
+  title: CLAN Visibility Guard API
+  version: 1.0.0
+  description: Visibility policy checks and sensitivity classification for CLAN/ZHOS.
+servers:
+  - url: http://clan-visibility-guard:8112
+tags:
+  - name: health
+  - name: visibility
+paths:
+  /health:
+    get:
+      tags: [health]
+      summary: Service health check
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HealthResponse"
+  /visibility/check_downgrade:
+    post:
+      tags: [visibility]
+      summary: Check if requested visibility downgrade is allowed
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/VisibilityCheckRequest"
+      responses:
+        "200":
+          description: Downgrade check result
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/VisibilityCheckResponse"
+        "400":
+          description: Invalid visibility level
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /visibility/classify:
+    post:
+      tags: [visibility]
+      summary: Classify text sensitivity and recommend level
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ClassifyRequest"
+      responses:
+        "200":
+          description: Classification result
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ClassifyResponse"
+  /visibility/redact_for_level:
+    post:
+      tags: [visibility]
+      summary: Redact text for target visibility level
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RedactRequest"
+      responses:
+        "200":
+          description: Redaction result
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RedactResponse"
+        "400":
+          description: Invalid visibility level
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+
+components:
+  schemas:
+    VisibilityLevel:
+      type: string
+      enum: [public, interclan, incircle, soulsafe, sacred]
+    HealthResponse:
+      type: object
+      required: [status, service]
+      properties:
+        status:
+          type: string
+          example: ok
+        service:
+          type: string
+          example: clan-visibility-guard
+    ErrorResponse:
+      type: object
+      required: [detail]
+      properties:
+        detail:
+          oneOf:
+            - type: string
+            - type: object
+    VisibilityCheckRequest:
+      type: object
+      required: [current_level, requested_level]
+      properties:
+        current_level:
+          $ref: "#/components/schemas/VisibilityLevel"
+        requested_level:
+          $ref: "#/components/schemas/VisibilityLevel"
+    VisibilityCheckResponse:
+      type: object
+      required: [allowed, reason, current_level, requested_level]
+      properties:
+        allowed:
+          type: boolean
+        reason:
+          type: string
+          enum: [ok, downgrade_requires_consent]
+        current_level:
+          $ref: "#/components/schemas/VisibilityLevel"
+        requested_level:
+          $ref: "#/components/schemas/VisibilityLevel"
+    ClassifyRequest:
+      type: object
+      required: [text]
+      properties:
+        text:
+          type: string
+    ClassifyResponse:
+      type: object
+      required: [recommended_level, sensitivity_flags]
+      properties:
+        recommended_level:
+          $ref: "#/components/schemas/VisibilityLevel"
+        sensitivity_flags:
+          type: array
+          items:
+            type: string
+    RedactRequest:
+      type: object
+      required: [text, target_level]
+      properties:
+        text:
+          type: string
+        target_level:
+          $ref: "#/components/schemas/VisibilityLevel"
+    RedactResponse:
+      type: object
+      required: [target_level, redacted_text, changed]
+      properties:
+        target_level:
+          $ref: "#/components/schemas/VisibilityLevel"
+        redacted_text:
+          type: string
+        changed:
+          type: boolean