FactVerse AI Agent Documentation Architecture
The current FactVerse AI Agent pages are useful as overview material, but they are not yet a complete documentation library. They explain what the platform is and where it can be used. A usable docs library must also explain how to connect, configure, operate, validate, troubleshoot, and govern the agent workflows.
This page defines the target structure for the FactVerse AI Agent documentation set.
Current page roles
| Current page | Keep as | Why |
|---|---|---|
| FactVerse AI Agent | Overview | Introduces the product boundary, naming convention, and starting links. |
| Architecture | Concept | Explains how Agent connects FactVerse Platform, DFS, Designer, Inspector, MCP, knowledge, and simulation. |
| Capability Map | Concept | Maps product components and tools to customer-facing capabilities. |
| Use Cases | Concept and roadmap | Explains priority workflow areas and routes task details to workflow guides. |
| Facility Operations | Workflow concept | Describes the operating scenario and expected outputs. Links to the task-oriented workflow guide. |
| Predictive Maintenance | Workflow concept | Describes the maintenance scenario and evidence pattern. Links to the task-oriented workflow guide. |
| Physical AI | Workflow concept | Describes Designer, SimReady assets, simulation, and feedback loops. Links to the task-oriented workflow guide. |
These pages should stay as concepts, with task-oriented workflow guides handling implementation steps.
Target structure
FactVerse AI Agent
├── Overview
├── Documentation Architecture
├── Getting Started
│ ├── Prerequisites
│ ├── Authentication and scopes
│ ├── Connect an MCP client
│ ├── Make the first tool call
│ └── Verify the setup
├── Core Concepts
│ ├── Tenant, asset, and permission context
│ ├── Tools, scopes, and audit records
│ ├── Human approval and write actions
│ ├── Data readiness and source references
│ └── Digital twins, scenes, and simulation context
├── Integration Guides
│ ├── MCP client integration
│ ├── Enterprise agent integration
│ ├── Cloud deployment model
│ ├── On-premises deployment model
│ ├── Hybrid deployment model
│ └── Key rotation and secret handling
├── Workflow Guides
│ ├── Facility Operations
│ │ ├── Prepare asset and facility context
│ │ ├── Connect operational signals
│ │ ├── Generate an operating summary
│ │ └── Prepare an Inspector work order draft
│ ├── Predictive Maintenance
│ │ ├── Prepare equipment history
│ │ ├── Review signal quality
│ │ ├── Generate risk explanation
│ │ └── Create a maintenance check workflow
│ └── Physical AI
│ ├── Prepare a Designer scene
│ ├── Build SimReady assets
│ ├── Run simulation-oriented review
│ └── Feed validation results back to Agent workflows
├── Reference
│ ├── Tool reference
│ ├── Scope reference
│ ├── Request and response examples
│ ├── Error codes
│ └── Audit event reference
├── Troubleshooting
│ ├── Authentication failures
│ ├── Scope denied
│ ├── Missing or stale source data
│ ├── Tool timeout
│ ├── Write action blocked
│ └── Simulation job failure
└── Governance and Validation
├── Tenant boundaries
├── Approval policy
├── Evidence and citation expectations
├── Deployment acceptance checklist
└── Operational handover checklist
Page content contract
Each document type should carry a different level of detail.
| Page type | Must include | Keep separate from |
|---|---|---|
| Overview | Product boundary, supported audience, stable entry points | A marketing page or release note |
| Concept | Mental model, entities, boundaries, and when to use the feature | A vague capability pitch |
| Getting started | Required access, exact steps, expected result, verification command | A long architecture essay |
| Integration guide | Endpoint, authentication, scopes, environment setup, examples, failure modes | A product brochure |
| Workflow guide | Preconditions, step-by-step task, expected input/output, review point, rollback or next action | A use-case description without operator steps |
| Reference | Stable field names, parameters, scopes, responses, errors, generated source link | Narrative guidance |
| Troubleshooting | Symptom, likely cause, checks, fix, escalation path | A generic FAQ |
| Governance | Approval boundary, audit record, retention, risk notes, human responsibility | Legal or compliance overclaim |
Priority build order
- Getting Started: authentication, scopes, MCP connection, first tool call, and setup verification.
- Core Concepts: tenant context, asset context, governed tools, approval, audit, and source references.
- Workflow Guides for the three priority areas: facility operations, predictive maintenance, and Physical AI. The first guide set is now available and should be expanded with examples and troubleshooting.
- Reference expansion: examples, error codes, audit events, and generated tool catalog cross-links.
- Troubleshooting: common integration, permission, data, and simulation failure paths.
- Deployment and validation: cloud, on-premises, hybrid, acceptance checklist, and handover checklist.
Language rollout
English is the source language for architecture and integration details. Simplified Chinese, Traditional Chinese, and Japanese must ship in the same pull request for public navigation pages and priority usage pages. Tier 2 languages should join the sidebar after the page has enough implementation value to maintain.
Boundaries
- Mature MCP documentation remains intact while AI Agent docs grow around it.
- Customer-ready workflow documentation focuses on mature modules.
- Prioritize facility operations, predictive maintenance, and Physical AI.
- Keep legacy FactVerse AI / FAI references clearly labeled as legacy module material.
- Agent output patterns use approval, audit, and source references by default, with accountable people retaining operational decisions.
Definition of done for the docs library
The AI Agent section becomes a real documentation library when a customer or implementation engineer can:
- Understand what access and source systems are required.
- Connect an MCP client with the right endpoint and scope.
- Run a first tool call and verify the response.
- Follow at least one complete workflow from input data to reviewed output.
- Troubleshoot common failure paths from the public documentation.
- Validate deployment readiness and handover requirements.