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

[yjouffrault]

Completes the Build with AI documentation: the hub is reworked against a prose audit, the two spoke pages that were placeholders are written, and the three task pages are reworked. Follows the agreed structure in Build with AI — plan and content (INFP-678), §8–§13.

Six pages, all new to stable. PR #10164 is replaced by this, not extended.

The branch did not build before this

npm run build failed on two broken anchors, so CI could not have passed:

Broken anchor on /objects/import-from-csv       -> ../overview/build-with-ai#install
Broken anchor on /schema/analyze-your-data      -> ../overview/build-with-ai#install

The hub never had an Install heading — the section was called "Get started". Both links now point at build-with-ai/setup.mdx, which is where installation actually lives after this change. onBrokenAnchors is throw in docusaurus.config.ts.

The branch has also been rebased onto current origin/stable; it was 893 commits behind, so CI would have run against a stale base.

Worth a reviewer's attention

Three MCP facts were wrong or overstated. Checked against opsmill/infrahub-mcp source rather than the messaging brief:

Claim before	What src/infrahub_mcp/config.py says
"A read-only deployment removes write tools entirely"	read_only hides the write tools and blocks GraphQL mutations — the old wording overstated one half and omitted the other
Session branch pattern presented as fixed	branch_pattern defaults to mcp/session-{date}-{hex} and is configurable
Auth modes listed with no default	auth_mode defaults to none, meaning shared credentials. Both new pages say so, because it is the state a reader who configures nothing ends up in

The skill count was stale. The plan recorded eleven skills; the repo has 13. Two appeared nowhere in the main docs: Diagnostics Analyzer and Skill Gap Reporter. All 13 are now covered on the hub.

Diagnostics Analyzer has no reference page to link to. /skills/skills-reference/analyzing-diagnostics returns 404, as do the plausible variants; every other skill named on the hub resolves. It is named and described without a link. The skills site needs that page — worth its own issue.

The skills site contradicts itself on the count, saying "11 skills" then listing 12 at /skills/installation-setup. Not fixable from this repo; flagging it.

All three task pages had a duplicate H1 repeating the frontmatter title, which renders the title twice.

The hub rewrite

Driven by an audit of all 67 of its prose sentences, kept locally at dev/specs/docs/build-with-ai-hub-audit.md:

• Opens on capability and situation. It previously opened on a work breakdown — the tasks an implementation contains — which a reader cannot decide anything from. The three reader situations in plan §2 had been written down and reached none of the drafts.
• Eleven sentences had a skill as their grammatical subject — "The Schema Manager applies…", "The Data Importer can take…". A skill is content the assistant loads; the assistant applies the conventions. Those verbs now belong to the reader or the assistant.
• Three section openers stated their value as an absence ("You do not need to…", "…does not require a separate change workflow"). The second also framed Infrahub's ordinary review workflow as a concession, which it is not.
• Bare "AI" in four places where the plan reserves three distinct terms for three jobs.
• The recommendation is now stated. Both "Get started" paragraphs were conditional, so the AI-first path was inferable and never asserted.
• Heading renamed from "How AI changes are merged" — those changes are made through the MCP server by an assistant, so "AI changes" named neither.
• The last Where to start row bundled three unrelated jobs under one Documentation cell; split in two.
• Added the ## In this section catalog every other hub ends with.

Preserved deliberately: the Skills-vs-MCP comparison table, the two concrete review examples, the one-off-analysis-to-check hand-off, and the neutral treatment of the manual path.

The two new pages

Set up your AI assistant — numbered steps, because setup is run-once and dependency-ordered. Opens with a four-row comparison of what to install, which asks a different question from the hub's two-tool table (what you install against what each tool is) so the two do not compete. Step 4 is a check whose answer distinguishes "skills present, MCP absent" from "both live". Ends with the LLM-and-no-tools path, which plan §1 asks to present as a legitimate choice.

Work with your assistant — direct-versus-planned with a size and complexity table, then what the skills verify against what only a person can judge, then one change walked from prompt to merged Proposed Change. It deliberately does not restate the hub's rule about branch and review: the hub states the rule, this page walks one instance of it.

The three task pages

They ship as new files here, so leaving them unreworked would have meant a hub that sets conventions landing beside three pages that break them.

• Build your schema → Build your schema with AI. Retitled because it sits beside "Create and load schema" in the sidebar. It opened with the raw skill ID as the sentence subject (infrahub-managing-schemas returns…); that and four more skill-as-actor verbs now belong to the assistant. Cut the "an assistant can invent an attribute" paragraph, which now lives once on the hub.
• Import data from CSV. Kept the source-fallback table, cut the paragraph below it that argued for it. Gave the skill's verbs to the assistant. Fixed a link label that did not match the real page title, "Load data using YAML file". Kept the partial-load warning, which is the one genuine operational gotcha in the set.
• Analyze your data. Opened for a reader who is not the engineer who built the model, with the MCP tool names moved below the questions they answer. Removed a contradiction: one line claimed the six analysis categories had no manual equivalent, while a later section routes compliance rules to checks.

Also settled

• Plan open item 3, Infrahub Skills against Infrahub skills, was unsettled and these pages establish the term. Capitalised, as the product name — the docs already ran 8 to 1 that way.
• The duplicate objects/load-from-yaml sidebar entry (plan §14 phase 3) surfaced as a rebase conflict and is resolved here rather than deferred.

Deliberately left out

• The prompts table on Work with your assistant (plan §10 item 2). There is no source for it. The skills' trigger conditions describe when a skill fires, which is not the same as a prompt worth pasting, and this is the one thing on these pages a reader would copy verbatim. Needs prompts that have been run, or a test pass against a live instance.
• The copy-paste setup prompt (plan open item 2) — blocked on the same thing, and the plan already says it "has to work end to end or it does more harm than the paragraph it replaces".
• Plan §14 phases 4–5 (the AI badge, the Quickstart AI step, notes across existing pages) and plan open item 1 (the operations reader's front door).

Checks

• npm run build in docs/ passes on the rebased base; it failed before this change
• markdownlint-cli2 on all six changed pages: 0 errors
• All six pages verified rendering locally — sidebar category clickable with both children listed, breadcrumbs correct, no duplicate titles, no console errors
• Every sentence on all six pages read for subject and verb, and for literal verb use. On the three new pages this found 13 subjects that could not perform their verbs in my own first draft, including three cases of a page as the subject — the same failure the audit had flagged in the original
• Vale was not run — it is not installed in this environment. Its rule files were applied by hand instead (swap, simple-easy, branded-terms-case-swap, eg-ie), which caught a Jinja2 transformation link label that should match the page's real title, Write a Jinja2 Transformation. A Vale pass in CI is still worth watching.
• No changelog fragment: docs-only change.

[cubic-dev-ai]

3 issues found across 8 files

Confidence score: 4/5

• In docs/docs/overview/build-with-ai/setup.mdx, the primary npx skills add path may install outside the expected project-local skills/infrahub-common/ location, leaving readers with a setup that does not work as documented; specify the CLI scope and show how to verify the install location.
• In docs/docs/objects/import-from-csv.mdx, the preflight guidance may imply that references to live-only objects can be resolved from local schemas, which could give users false confidence in validation; qualify the claim and state the limitation clearly.
• In the worked example in docs/docs/objects/import-from-csv.mdx, the fabricated timestamp and placeholder SHA-256 appear to be real provenance, making the output non-reproducible or unverifiable; label them as illustrative placeholders or provide genuine generated values.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/docs/overview/build-with-ai/setup.mdx">

<violation number="1" location="docs/docs/overview/build-with-ai/setup.mdx:41">
P2: When readers use the primary `npx skills add` command, the subsequent project-local `skills/infrahub-common/` requirement may not be satisfied because the page does not specify the CLI scope or verify where it installs. Document the command's project-local option explicitly, or add a verification step that confirms the shared skill directory exists before continuing.</violation>
</file>

<file name="docs/docs/objects/import-from-csv.mdx">

<violation number="1" location="docs/docs/objects/import-from-csv.mdx:27">
P2: Custom agent: **Flag AI Slop and Fabricated Changes**

When only local schemas are available, the preflight can verify emitted-file closure but cannot resolve references to live-only objects. Qualify this claim and state that unresolved live references still require server-side validation.</violation>

<violation number="2" location="docs/docs/objects/import-from-csv.mdx:45">
P3: The worked example presents a fabricated timestamp and placeholder SHA-256 as generated provenance, so readers cannot reproduce or verify the shown output. Use clearly marked illustrative placeholders (or provide the source file and reproducible values) and link the partial-load recovery step to the branch-discard documentation.</violation>
</file>

<sub>Shadow auto-approve: would not auto-approve because issues were found.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: When readers use the primary npx skills add command, the subsequent project-local skills/infrahub-common/ requirement may not be satisfied because the page does not specify the CLI scope or verify where it installs. Document the command's project-local option explicitly, or add a verification step that confirms the shared skill directory exists before continuing.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/docs/overview/build-with-ai/setup.mdx, line 41:

<comment>When readers use the primary `npx skills add` command, the subsequent project-local `skills/infrahub-common/` requirement may not be satisfied because the page does not specify the CLI scope or verify where it installs. Document the command's project-local option explicitly, or add a verification step that confirms the shared skill directory exists before continuing.</comment>

<file context>
@@ -0,0 +1,118 @@
+The installer copies the skills into your project, so run it from the repository where your Infrahub schema, object files, and Python components are kept.
+
+```bash
+npx skills add opsmill/infrahub-skills
+```
+
</file context>

[cubic-dev-ai]

P2: Custom agent: Flag AI Slop and Fabricated Changes

When only local schemas are available, the preflight can verify emitted-file closure but cannot resolve references to live-only objects. Qualify this claim and state that unresolved live references still require server-side validation.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/docs/objects/import-from-csv.mdx, line 27:

<comment>When only local schemas are available, the preflight can verify emitted-file closure but cannot resolve references to live-only objects. Qualify this claim and state that unresolved live references still require server-side validation.</comment>

<file context>
@@ -0,0 +1,80 @@
+
+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.
</file context>

[cubic-dev-ai]

P3: The worked example presents a fabricated timestamp and placeholder SHA-256 as generated provenance, so readers cannot reproduce or verify the shown output. Use clearly marked illustrative placeholders (or provide the source file and reproducible values) and link the partial-load recovery step to the branch-discard documentation.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/docs/objects/import-from-csv.mdx, line 45:

<comment>The worked example presents a fabricated timestamp and placeholder SHA-256 as generated provenance, so readers cannot reproduce or verify the shown output. Use clearly marked illustrative placeholders (or provide the source file and reproducible values) and link the partial-load recovery step to the branch-discard documentation.</comment>

<file context>
@@ -0,0 +1,80 @@
+
+```yaml title="objects/001-devices.yml"
+# Generated from inventory.csv
+# sha256: 3f2a9c1e...  generated: 2026-08-13T10:04:00Z
+---
+apiVersion: infrahub.app/v1
</file context>