AI Subsystem Overview (zmodu.ai)

zmodu.ai provides six modular capabilities for building controlled, auditable AI features in Zig applications. All capabilities enforce strict execution boundaries: allowlists, permission codes, token budgets, audit logs, and tenant isolation.

1. Document Map

TaskDocumentContents
Scaffold an AI chat moduleAI.mdzmodu scaffold --with-aichat, AiProvider, SSE streaming, multi-turn history, and MemoryStore
Integrate AI into a business serviceAI_DEV_GUIDE.mdAiKeyManager → AiProvider → SkillRegistry → Agent / Workflow → HTTP / Cron / Outbox / MCP
Configure agent authority gatesAGENT_RUNTIME.mdFail-closed ai.Guard, AgentSpec, ProposalPipeline, and AgentWorker
Browse built-in skillsAI_SKILLS.mdRead (db.query, kpi.query), propose (approval.request, notification.send), execute (entity.*, command.execute), and admin skills
Orchestrate multi-step workflowsAI_ORCHESTRATION.mdLinear and DAG Workflow, human approval gates, Budget, WAL crash recovery, and outbox bridges
Wire LLM-backed business policiesLLM_POLICIES.mdllmApprove, llmRiskDecide, llmDiagnose, llmVerify, and AiKeyManager key rotation
Expose skills over MCPMCP.mdai.mcp.serveStdio bridging SkillRegistry to Claude / Codex / external MCP clients

2. Architecture Overview

Chat Product    ---> AI.md (`--with-aichat` scaffold)

Business App    ---> AI_DEV_GUIDE.md (AiKeyManager -> AiProvider -> SkillRegistry)
                       ├──> AI_SKILLS.md         (What tools the Agent can call)
                       ├──> AGENT_RUNTIME.md     (Guard & Proposal -> Risk -> Execute)
                       ├──> AI_ORCHESTRATION.md  (Multi-step linear/DAG workflows)
                       └──> LLM_POLICIES.md      (Approval, risk, and diagnosis policies)

External Client ---> MCP.md (Exposes SkillRegistry over stdio MCP)

If you are using an AI coding assistant to write zmodu application code, start with AGENTS.md.