# HUA dot product family - AI Documentation
# Curated family guide. Package-owned ai.yaml files remain the per-package source of truth.

family:
  name: "HUA dot product family"
  purpose: "Choose the correct dot package or tool surface for style resolution, build-time extraction, capability discovery, editor diagnostics, and packaged VS Code diagnostics."
  source_of_truth:
    package: "@hua-labs/dot"
    resolver: "dot()"
    explain: "dotExplain()"
    ax_catalog: "getDotAxCatalog()"
    ai_doc: "dot.ai.yaml"
  status:
    capability_truth: "@hua-labs/dot owns resolver, target support, and AX catalog truth."
    projections: "AOT, MCP, LSP, and VS Code consume or package dot metadata; they do not define independent support matrices."

packages:
  - package: "@hua-labs/dot"
    role: "core-engine"
    ai_doc: "dot.ai.yaml"
    use_for:
      - "Resolve utility strings into web, native, or flutter target output."
      - "Inspect target caveats with dotExplain()."
      - "Read package-owned AX capability metadata with getDotAxCatalog()."
    do_not_use_for:
      - "Editor integration packaging."
      - "Build-time replacement of source calls."

  - package: "@hua-labs/dot-aot"
    role: "build-time-projection"
    ai_doc: "dot-aot.ai.yaml"
    use_for:
      - "Replace static dot() calls with precomputed style objects during a build."
      - "Preserve dot resolver output parity at build time."
    boundary: "Delegates capability truth to @hua-labs/dot and getDotAxCatalog(); does not own an AOT-specific AX catalog."

  - package: "@hua-labs/dot-mcp"
    role: "ai-tooling-server"
    ai_doc: "dot-mcp.ai.yaml"
    use_for:
      - "Let AI clients resolve, explain, complete, validate, or query dot capabilities through MCP."
      - "Use dot_capabilities for compact AX capability discovery before resolving user input."
    boundary: "Read-only MCP projection over @hua-labs/dot metadata and resolver behavior."

  - package: "@hua-labs/dot-lsp"
    role: "language-server"
    ai_doc: "dot-lsp.ai.yaml"
    use_for:
      - "Provide autocomplete, hover, and diagnostics in editor integrations."
      - "Annotate target caveats with AX family/category metadata from @hua-labs/dot."
    boundary: "Diagnostics come from dotExplain(); AX labels are context, not a second resolver."

  - package: "dot-vscode"
    role: "packaged-editor-extension"
    ai_doc: "dot-vscode.ai.yaml"
    use_for:
      - "Use the VS Code extension boundary and packaged LSP smoke expectations."
      - "Verify packaged diagnostics include the AX metadata path before VSIX work."
    boundary: "Packages @hua-labs/dot-lsp for VS Code; does not define dot support or publish a VSIX by itself."

decision_guide:
  - task: "Need runtime style output for app code."
    choose: "@hua-labs/dot"
    reason: "The core resolver owns target output and support truth."

  - task: "Need to understand whether a utility family is supported for web/native/flutter before resolving content."
    choose: "@hua-labs/dot getDotAxCatalog() or @hua-labs/dot-mcp dot_capabilities"
    reason: "Both use the package-owned AX catalog without inventing support metadata."

  - task: "Need to inspect caveats for a concrete utility string."
    choose: "@hua-labs/dot dotExplain() or @hua-labs/dot-mcp dot_explain"
    reason: "Concrete input caveats must come from resolver output, not package presence."

  - task: "Need zero-runtime extraction for literal dot() calls."
    choose: "@hua-labs/dot-aot"
    reason: "AOT is the build-time projection surface."

  - task: "Need editor diagnostics in arbitrary editors."
    choose: "@hua-labs/dot-lsp"
    reason: "The LSP owns editor protocol behavior and uses dotExplain() for target caveats."

  - task: "Need VS Code packaging or extension smoke coverage."
    choose: "dot-vscode"
    reason: "The VS Code package owns extension packaging and copied-server smoke coverage."

rules:
  - "Do not infer target support from the existence of AOT, LSP, MCP, or VS Code packages."
  - "Use @hua-labs/dot as the source of truth for resolver output and AX capability metadata."
  - "Use dot_capabilities for AI capability discovery and dotExplain()/dot_explain for concrete input caveats."
  - "Treat AOT, MCP, LSP, and VS Code as projections or tool surfaces unless a reviewed source gate says otherwise."
  - "Package publish, VSIX publish, changesets, and deploys are separate gates."

recent_ax_sequence:
  - mission: "M649"
    result: "Common package AX docs/generator contract normalizes package-owned catalogs for compact AI-doc summaries."
  - mission: "M650"
    result: "dot MCP exposes read-only dot_capabilities over getDotAxCatalog()."
  - mission: "M651"
    result: "dot LSP target caveats include AX family/category context from getDotAxCatalog()."
  - mission: "M652"
    result: "dot VS Code packaged smoke checks the bundled LSP AX diagnostic metadata path."
  - mission: "M653"
    result: "dot AOT docs state that AOT follows dot resolver and AX catalog truth."