docs: complete the Build with AI documentation (hub, spokes, and task pages)

.vale/styles/spelling-exceptions.txt

@@ -31,6 +31,7 @@ Buildkite
 cAdvisor
 Ceph
 changelog
+chatbot
 conftest
 Conftest
 cron
@@ -66,6 +67,7 @@ datetime
 default_branch
 default_filter
 Delinea
+denormalized
 Dependabot
 dev
 Diataxis

docs/docs/objects/import-from-csv.mdx

@@ -0,0 +1,80 @@
+---
+title: Import data from CSV
+description: Prompt an AI coding assistant to translate a CSV or TSV export into Infrahub object YAML, then load it the same way as any other object file.
+---
+
+Prompt an AI coding assistant to translate a CSV or TSV export into Infrahub object YAML. Your assistant writes the file, creates a branch, validates and loads it, and hands the branch back for you to review.
+
+:::info Prerequisite
+
+Requires an AI coding assistant with the [Infrahub Skills](../overview/build-with-ai/setup.mdx) installed. Without the MCP server or `infrahubctl` configured, your assistant works from local schema files instead, which is less accurate about your live schema.
+
+:::
+
+## What it does
+
+Working from the [Data Importer](https://docs.infrahub.app/skills/skills-reference/importing-data) skill, your assistant takes a CSV or TSV export — one file, a folder, or one large denormalized sheet — and checks its columns against your schema before writing anything. It tries these sources in order and uses the first one available:
+
+| Source | Requires | What it sees |
+|---|---|---|
+| MCP server | The [MCP server](../overview/build-with-ai/setup.mdx) connected to your instance | Live, branch-specific state — including dropdown choices and HFIDs added on a feature branch |
+| `infrahubctl schema export` | `infrahubctl` configured against your instance | The live schema, not branch-specific unless you pass `--branch` |
+| `/api/schema` REST endpoint | Network access to the instance's API | The same live schema as the CLI export |
+| Local `schemas/*.yml` files | Nothing — works with no connection to any instance | Whatever is on disk, which can lag what's actually deployed |
+
+The rows are translated into the same object YAML format documented on [Load data using YAML file](./load-from-yaml).
+
+Your assistant then checks its own output against the object-file rules and confirms every relationship reference resolves, before it contacts a server. Only once that passes does it create a fresh branch, run `infrahubctl object validate` against it to catch schema-resolution errors, and then `infrahubctl object load` to put the objects on the branch. Your assistant hands that branch back to you and never merges it.
+
+Where a column maps to nothing in your schema, your assistant stops and asks rather than guessing.
+
+## Worked example
+
+### 1. Provide the file
+
+```text title="Example prompt"
+Import this inventory.csv into Infrahub.
+```
+
+### 2. Review the generated object YAML
+
+Your assistant maps each column to a schema attribute or relationship and writes one numbered object file per kind, each carrying a provenance comment:
+
+```yaml title="objects/001-devices.yml"
+# Generated from inventory.csv
+# sha256: 3f2a9c1e...  generated: 2026-08-13T10:04:00Z
+---
+apiVersion: infrahub.app/v1
+kind: Object
+spec:
+  kind: NetworkDevice
+  data:
+    - name: sw01-svc01
+      site: Stonehenge Visitor Centre
+```
+
+### 3. Your assistant creates the branch, validates, and loads
+
+```bash
+infrahubctl branch create csv-import-20260813-1004
+infrahubctl object validate objects/ --branch csv-import-20260813-1004
+infrahubctl object load objects/ --branch csv-import-20260813-1004
+```
+
+You do not run these yourself. Your assistant runs them in this order, and only after its own local check passes. `infrahubctl object validate` catches schema-resolution errors — a kind that does not exist, a reference that does not resolve — before anything loads. The branch is named `csv-import-YYYYMMDD-HHMM` by default.
+
+### 4. Review the diff and open a Proposed Change
+
+Review the loaded objects in the web interface, then open a Proposed Change to merge the branch into `main`. See [Proposed Changes](../proposed-changes/overview) for the review workflow.
+
+## What to watch for
+
+An unmapped column stops the import instead of guessing at a match. Resolve the mismatch — rename the column, or add the attribute to your schema — and run it again, rather than working around it. Check the branch name before merging; `csv-import-YYYYMMDD-HHMM` is the default, not a required format.
+
+Loading is not transactional across files. If one file in a large batch fails partway through, the branch already has the earlier files applied. Discard the branch and run it again with a fresh name rather than repairing the partial state by hand.
+
+## Related
+
+- [Load data using YAML file](./load-from-yaml) — The object YAML format and the `infrahubctl object load` command behind this workflow: same format, same load command, with only the writing automated
+- [Set up your AI assistant](../overview/build-with-ai/setup.mdx) — Install the Infrahub Skills and connect the MCP server
+- [Data Importer skill reference](https://docs.infrahub.app/skills/skills-reference/importing-data) — Full column-mapping and fallback-order behavior

docs/docs/overview/build-with-ai/index.mdx

@@ -0,0 +1,126 @@
+---
+title: Build with AI
+description: Describe the network you want to model and have your assistant build the Infrahub schema, automation, and queries that represent it.
+---
+
+You can describe the network you want to model in your own terms and have your assistant build the Infrahub resources that represent it — the schema that models your network, the automation that acts on your data as it changes, and the queries that answer questions about it.
+
+Use this path to prototype a use case before you have learned Infrahub's schema model, to ship schema, Generators, and checks faster on an implementation you already run, or to answer a question about your live infrastructure without going through an engineer.
+
+This is the recommended way to build an Infrahub implementation. You can also do each of these tasks by hand, and the sections below link the instructions for doing that.
+
+## What your assistant needs to know
+
+Building an Infrahub implementation means turning your network design into a data model, populating that model with your data, and building the checks, Generators, Transformations, and other automation that operate on it. With an AI-first approach you describe the requirements and the business logic, and your assistant writes those resources, applying Infrahub's schema rules, file formats, and development conventions as it goes.
+
+That takes two kinds of context — Infrahub's conventions, and the state of your own instance. Each comes from a different tool:
+
+- **[Infrahub Skills](https://docs.infrahub.app/skills)** contain Infrahub's data model, conventions, and workflow patterns. Your assistant loads them and applies that knowledge as you create schemas, objects, checks, Generators, Transformations, imports, menus, and other Infrahub resources.
+- **[The Infrahub MCP server](https://docs.infrahub.app/mcp)** connects your AI assistant to a running Infrahub instance, where it can discover your schema, query your data, make changes on isolated branches, and open Proposed Changes for review.
+
+You can use either on its own. Together, your assistant has both the Infrahub-specific knowledge for how to build and the instance-specific context for what you have already built. Working with an LLM and neither tool installed is also a legitimate setup — see [Set up your AI assistant](./setup.mdx) for what you keep and what you give up, alongside the installation steps for both tools.
+
+## Start with what you want to build
+
+The starting point is your network design, in the terms your team already uses for it.
+
+You might describe a fabric with spine and leaf devices, the relationships between them, the addressing you need to allocate, and the configurations you eventually want to generate. Your assistant reads the Infrahub Skills for the conventions that turn those requirements into Infrahub resources — schema structures, relationships, queries, Python or Jinja2 code, and [`.infrahub.yml`](../../git-integration/infrahub-yml.mdx) registrations.
+
+For a well-scoped task, describe what you want and let your assistant select the appropriate skill. For a larger implementation, [Spec-Driven Development](https://docs.infrahub.app/skills/spec-driven-development) works through the requirements and the implementation plan before any files are generated: you review the plan, adjust the design, and then have the assistant build the individual components. See [Work with your assistant](./working-with-ai.mdx) to choose between them by the size and complexity of the change.
+
+You can learn Infrahub while working with your own network model: inspect what the assistant produces, ask why it chose a particular relationship or attribute type, and refine the implementation as your requirements evolve.
+
+## What you can build
+
+### Model your network
+
+Describe the domain you need to represent — devices, locations, circuits, services, routing, or another part of your network — and your assistant can create or extend an Infrahub schema.
+
+Your assistant reads the [Schema Manager](https://docs.infrahub.app/skills/skills-reference/managing-schemas) skill for Infrahub's conventions on node and attribute names, attribute types, relationships, [generics](../../schema/generics-and-inheritance.mdx), human-friendly IDs, [display labels](../../schema/display_label.mdx), [Profiles](../../profiles/overview.mdx), and [Object Templates](../../object-templates/overview.mdx), and applies them to the schema it writes. You can then validate that schema before loading it into Infrahub. See [Build your schema](../../schema/build-your-schema.mdx).
+
+### Bring in existing data
+
+When your network data is already held in spreadsheets, exports, or another source of truth, your assistant can map it into your Infrahub model.
+
+Working from the [Data Importer](https://docs.infrahub.app/skills/skills-reference/importing-data) skill, your assistant takes CSV or TSV data, inspects your Infrahub schema, maps columns to the appropriate attributes and relationships, generates [object files](../../objects/load-from-yaml.mdx) in the correct load order, and validates and loads them on a dedicated branch. Where a source field has no destination in your schema, your assistant reports the gap for you to resolve instead of choosing one silently. See [Import data from CSV](../../objects/import-from-csv.mdx).
+
+When you are creating objects from a description rather than from a file, your assistant can produce the same object-file format using the [Object Manager](https://docs.infrahub.app/skills/skills-reference/managing-objects) skill, with references and load order handled for you.
+
+### Build automation from your data
+
+You can have your assistant build the automation that runs as your modeled data changes. For example, ask it to:
+
+- create BGP sessions from a topology design;
+- generate devices, interfaces, and IP addresses from a fabric definition;
+- render device configurations from Infrahub data;
+- build a validation check for a network design rule.
+
+Each component has a skill carrying its Infrahub-specific patterns. For a Generator, your assistant uses the [Generator Manager](https://docs.infrahub.app/skills/skills-reference/managing-generators) to write the GraphQL query, the Python Generator, and the registration needed to derive infrastructure objects from a design and keep them synchronized as that design evolves. Your assistant works the same way from the [Transform Manager](https://docs.infrahub.app/skills/skills-reference/managing-transforms) for Transformations and the [Check Manager](https://docs.infrahub.app/skills/skills-reference/managing-checks) for checks. For the same work done by hand, see [Build a generator](../../generators/build.mdx), [Write a Jinja2 Transformation](../../transformations/jinja2.mdx), and [Build a check](../../learn/tutorials/build-a-check.mdx).
+
+### Ask questions about your live network data
+
+With the MCP server connected, your AI assistant can answer questions about the data in a running instance:
+
+- Which services depend on this circuit?
+- Which devices are missing a platform?
+- Which objects depend on this prefix?
+- Where does realized state differ from the design?
+
+The MCP server exposes your schema and data through structured tools, so your assistant can discover the kinds and relationships that actually exist instead of relying on assumptions about your model. For cross-node analysis, dependency and change-impact questions, drift analysis, and data-quality audits, your assistant uses the [Data Analyzer](https://docs.infrahub.app/skills/skills-reference/analyzing-data) skill, which needs the MCP connection to reach live data. See [Analyze your data](../../schema/analyze-your-data.mdx).
+
+### Maintain and improve your implementation
+
+Once an implementation is running, you can use your assistant to audit it, shape its navigation, diagnose problems, and report what you find.
+
+With the [Repo Auditor](https://docs.infrahub.app/skills/skills-reference/auditing-repo), your assistant reviews schema files, object files, Python components, `.infrahub.yml` registrations, and project structure against Infrahub conventions, and reports what should be corrected and why. With the [Menu Manager](https://docs.infrahub.app/skills/skills-reference/managing-menus), it can build [navigation](../../menu/overview.mdx) around the way different people use your data.
+
+When a deployment is misbehaving, your assistant reads the [Diagnostics Collector](https://docs.infrahub.app/skills/skills-reference/collecting-diagnostics) and runs `infrahub-collect` to gather the support bundle OpsMill needs. With the Diagnostics Analyzer, it triages a bundle you have already collected — tracebacks across the service logs, the incidents they correlate into, and any match against known issues in `opsmill/infrahub`.
+
+To report a bug or request a feature, your assistant uses the [Issue Reporter](https://docs.infrahub.app/skills/skills-reference/reporting-issues) to work out which `opsmill/infrahub-*` repository it belongs in, search for existing duplicates, and draft the issue for your review — see [How do I get help with Infrahub?](../../faq/faq.mdx#how-do-i-get-help-with-infrahub). Where a skill's own guidance was missing or unclear enough to cost you repeated retries, it can use the [Skill Gap Reporter](https://docs.infrahub.app/skills/skills-reference/reporting-skill-gaps) to report that friction against the skill itself.
+
+### Where to start
+
+| You want to | Documentation | Skill reference |
+|---|---|---|
+| Model a domain, and plan the migration when you change it later | [Build your schema](../../schema/build-your-schema.mdx) | [Schema Manager](https://docs.infrahub.app/skills/skills-reference/managing-schemas) |
+| Get data you already have into Infrahub | [Import data from CSV](../../objects/import-from-csv.mdx), [Load data using YAML file](../../objects/load-from-yaml.mdx) | [Data Importer](https://docs.infrahub.app/skills/skills-reference/importing-data), [Object Manager](https://docs.infrahub.app/skills/skills-reference/managing-objects) |
+| Generate objects from a design, render configuration, enforce a rule on every change | [Build a generator](../../generators/build.mdx), [Write a Jinja2 Transformation](../../transformations/jinja2.mdx), [Build a check](../../learn/tutorials/build-a-check.mdx) | [Generator Manager](https://docs.infrahub.app/skills/skills-reference/managing-generators), [Transform Manager](https://docs.infrahub.app/skills/skills-reference/managing-transforms), [Check Manager](https://docs.infrahub.app/skills/skills-reference/managing-checks) |
+| Ask questions about live infrastructure | [Analyze your data](../../schema/analyze-your-data.mdx) | [Data Analyzer](https://docs.infrahub.app/skills/skills-reference/analyzing-data) |
+| Organize the web interface | [Menu customization](../../menu/overview.mdx) | [Menu Manager](https://docs.infrahub.app/skills/skills-reference/managing-menus) |
+| Check a repository against Infrahub conventions | [infrahub.yml configuration](../../git-integration/infrahub-yml.mdx) | [Repo Auditor](https://docs.infrahub.app/skills/skills-reference/auditing-repo) |
+| Get help with a deployment that is misbehaving, or file an issue | [Getting help](../../faq/faq.mdx#how-do-i-get-help-with-infrahub) | [Diagnostics Collector](https://docs.infrahub.app/skills/skills-reference/collecting-diagnostics), [Issue Reporter](https://docs.infrahub.app/skills/skills-reference/reporting-issues) |
+
+## How Infrahub Skills and MCP work together
+
+| | Infrahub Skills | Infrahub MCP server |
+|---|---|---|
+| **What your assistant can use** | Infrahub conventions, patterns, examples, and development workflows | Your live Infrahub schema and data, plus tools to query and change them |
+| **Where it works** | Your project and its files | A running Infrahub instance |
+| **Use it when** | You are building or modifying schemas, objects, checks, Generators, Transformations, imports, or other project resources | You need to inspect, analyze, or change data in the instance you are connected to |
+
+Use both when your assistant needs to apply Infrahub conventions while also understanding the schema and data that already exist in your environment.
+
+Most Infrahub Skills work without the MCP server. The Data Analyzer is the exception, because the data it analyzes is live. With MCP connected, your assistant also has instance context in other development workflows, where that context is useful.
+
+## How changes made through MCP are reviewed
+
+Changes made through the MCP server reach the default branch the way every other change does: on a branch, through a Proposed Change you review and merge.
+
+When the MCP server makes its first write, it creates a session [branch](../../branches/overview.mdx). Additional writes in the same session stay on that branch. Session branches are named `mcp/session-{date}-{hex}` by default, and the pattern is configurable. When the work is ready, your assistant can call `propose_changes` to open a [Proposed Change](../../proposed-changes/overview.mdx) against the default branch.
+
+You review the diff and any configured checks in Infrahub before merging. The MCP server has no tool that merges a branch, so changes made through it do not reach the default branch until a person merges them.
+
+How much access the server has is yours to set. In a read-only deployment, the write tools are not offered to your assistant and GraphQL mutations are rejected. For a multi-user deployment, you choose how identity is established at the MCP and Infrahub layers — the default is a shared set of credentials, so a deployment several people connect to is worth configuring deliberately. See [MCP authentication](https://docs.infrahub.app/mcp/references/authentication) for the options.
+
+## Review what your assistant produces
+
+Your assistant applies Infrahub conventions and runs the validation appropriate to a task. Whether the result represents the network you intended to model is yours to decide.
+
+A schema can pass `infrahubctl schema check` and still model the wrong relationship for your design. An imported object file can be structurally valid while containing a source mapping you do not want. Review the model, the generated automation, and the data changes with the same attention you would give code or infrastructure changes produced by another engineer.
+
+Where a requirement should apply consistently, use Infrahub's validation mechanisms. Your assistant can answer "Which devices violate this naming convention?" for the data you have now. Where that rule should hold for every future change, the [Check Manager](https://docs.infrahub.app/skills/skills-reference/managing-checks) turns it into a [check](../../checks/overview.mdx) that runs as part of your Proposed Change workflow.
+
+## In this section
+
+- [Set up your AI assistant](./setup.mdx) — Install the Infrahub Skills, connect the MCP server, and choose the combination that fits how you work
+- [Work with your assistant](./working-with-ai.mdx) — Decide when to describe a change directly and when to plan it first, and what to check in what your assistant produces