[freeqaz-openai]

Problem

Contributors need a shared way to draw readable diagrams and distinguish implemented connections from pending integration. Add repository-local Mermaid guidance for documentation and PR descriptions.

Change

• Add mermaid-diagrams with a compact flowchart template, named phases, short HTML labels, and semantic colors. Solid arrows represent implemented connections; dashed arrows represent pending integration.
• Link the skill from repository instructions and the developer skills guide, document its maintenance, and allow its directory through the existing skill ignore rules.
• Keep diagrams optional when prose is sufficient. Require claims to match source evidence and report syntax checks and visual inspection separately.

Before / after

PR #141 already uses HTML Mermaid styling. For this comparison, the before strips that presentation; the after follows the skill. Both preserve the same nodes, connections, deployment blocker, and pending integration; the after view also aligns the phase starts.

Before: default styling and long labels

flowchart TB
  subgraph Drafts["Save draft configuration"]
    API["Binding APIs: Agent drafts"] -->|save| State[("Namespace State: PostgreSQL Bindings unverified")]
    State -->|nonempty selection| Gate["Deploy blocked: Before revision, queue or Compute"]
  end

  subgraph Protected["Prepare credentials explicitly"]
    Source["Encrypted App key: Operator-selected immutable K8s Secret"] -->|supply| Prepare
    Storage["Local custody: Pinned key file Token directory"] -->|supply| Prepare
    Prepare["Explicit preparation: Check binding + Secret"] -->|prepare| Owners["Protected primitives: RSA signing material Crypto + token store"]
  end

  Prepare -->|check identity| State
  Owners -.->|not connected| Work["Pending integration: Production Work Verified checkout"]

Loading

After: the Mermaid skill

---
config:
  theme: base
  htmlLabels: true
  themeVariables:
    fontSize: 14px
    primaryTextColor: "#344054"
    lineColor: "#8B949E"
    edgeLabelBackground: "#FFFFFF"
    clusterBkg: "#FAFBFC"
    clusterBorder: "#D8DEE6"
  flowchart:
    curve: linear
    nodeSpacing: 28
    rankSpacing: 32
    padding: 14
    diagramPadding: 12
    subGraphTitleMargin:
      top: 10
      bottom: 14
---
flowchart TB
  subgraph Drafts["Draft configuration"]
    API["<b>Binding APIs</b><br/>Agent drafts"] --->|save| State[("<b>Namespace State</b><br/>PostgreSQL<br/>Bindings unverified")]
    State -->|nonempty selection| Gate["<b>Deploy blocked</b><br/>Before revision,<br/>queue or Compute"]
  end

  subgraph Protected["Credential preparation"]
    Source["<b>Encrypted App key</b><br/>Operator-selected<br/>immutable K8s Secret"] -->|supply| Prepare
    Storage["<b>Local custody</b><br/>Pinned key file<br/>Token directory"] -->|supply| Prepare
    Prepare["<b>Explicit preparation</b><br/>Check binding + Secret"] -->|prepare| Owners["<b>Protected primitives</b><br/>RSA signing material<br/>Crypto + token store"]
  end

  Prepare -->|check identity| State
  Owners -.->|not connected| Work["<b>Pending integration</b><br/>Production Work<br/>Verified checkout"]

  classDef draft fill:#EDF2F7,stroke:#879AB0,color:#25364A,stroke-width:1px
  classDef input fill:#F1EEF5,stroke:#A091AD,color:#3A3243,stroke-width:1px
  classDef protected fill:#EBF3F0,stroke:#7F9D93,color:#2B4038,stroke-width:1px
  classDef blocked fill:#F7F1E5,stroke:#B3A078,color:#514532,stroke-width:1px
  classDef pending fill:#F3F4F6,stroke:#98A2AE,color:#44505F,stroke-width:1px,stroke-dasharray:4 4
  class API,State draft
  class Source,Storage input
  class Prepare,Owners protected
  class Gate blocked
  class Work pending
  style Drafts fill:#FAFBFC,stroke:#D8DEE6,stroke-width:1px
  style Protected fill:#FAFBFC,stroke:#D8DEE6,stroke-width:1px
  linkStyle default stroke:#8B949E,stroke-width:1px

Loading

Muted colors and thin borders distinguish roles without overpowering the labels. Aligned phase starts, clear title margins, and compact spacing make the flow easier to scan; the dashed gray path still identifies pending integration.

Verification

• Skill structure, local links, documentation length (200 Markdown files), workspace boundary, and pinned Prettier checks passed.
• The revised template and after example parsed and rendered locally with Mermaid 11.17.2 at document width; visual inspection checked label contrast, phase-title clearance, padding, and edge routing.
• docs:check: 16 of 17 tests passed. The generated OpenAPI fixture failed because the local dependency graph could not resolve @openclaw-enterprise/utils. The documentation build, navigation, and link tests passed.
• Autoreview returned reviewer_unavailable after a timeout and produced no review report.

Risks

This changes contributor guidance and an illustrative template; application behavior and dependencies are unchanged. Local rendering can differ from GitHub's renderer. Diagram validation establishes presentation and syntax, not runtime behavior.