Skip to content

Tool Integration Checklist

When adding a new tool to aguidetocloud.com, these are the touch points. The number was 12 in early 2026; production incidents have grown it to 14. The list will keep growing.

The headline rule lives in copilot-instructions.md → "New Tool Build Pattern". This page is the full file list with rationale.

The 14 touch points

# File What to do
1 data/toolkit_nav.toml Register the tool. Set all fields including data-category for the homepage card.
2 data/tool_colours.toml Pick an accent. Verify hue distance from existing tools (the colour space was exhausted at 45 tools — new tools share hues). Verify the CSS namespace isn't already taken (e.g. .ptester-* was Policy Tester before Prompt Tester wanted the same prefix).
3 data/tool_counters.toml Set base ≥ 50. Base = 0 hides the hero badge entirely — many tools shipped with no usage badge because of this.
4 layouts/free-tools/list.html Add card in the correct category section. If adding versions to existing tool, keep feature counts accurate.
5 baseof.html Add a body class for the new tool (page-{slug} pattern). Lots of CSS hangs off body classes.
6 nav.html Add to the nav with hasPrefix. Verify the category count <span> is correct — "Tools (47)" when count is 53 = credibility crater.
7 tool-ecosystem.html Add to the relevant group. Verify tool-eco-N CSS class exists in style.css — add desktop AND mobile rules if introducing a new ecosystem size.
8 feedback/list.html Add to the tool dropdown. Without this, users can't submit feedback for the tool.
9 OG image Run scripts/og-generator/. Verify static/images/og/{slug}.jpg exists on disk. CI auto-generates missing ones, but it's faster to do it locally.
10 taglines.toml + capture-tool-previews.py Add tagline. Run preview capture.
11 FAQPage JSON-LD in template Every tool with FAQ frontmatter MUST emit FAQPage JSON-LD. 16 tools shipped without it before the audit caught them.
12 cache_version in hugo.toml Bump on every CSS/JS deploy.
13 Smoke test ALL tabs + default scenario loads on first visit Don't trust "looks fine in dev". Click every tab, refresh, click again.
14 Full-site audit Verify in all 7 registry points, all ecosystem groups, nav counts match, preview images exist.

FAQ tab pattern (for tools that have one)

<details open>
  <!-- max-width:800px -->
  <!-- 4-6 questions -->
  <!-- Section titles use <h2> (hero already has the h1) -->
</details>

Then the FAQPage JSON-LD in the template — non-negotiable for SEO.

Why this checklist keeps growing

Every entry that wasn't in v1 of the checklist comes from a tool that shipped invisible or broken because someone forgot a step:

  • Step 11 (FAQPage JSON-LD) — 16 tools shipped without it. Found in Apr 2026 audit. Fixed in batch.
  • Step 7 expansion (tool-eco-N CSS) — Cert Compass shipped without ecosystem styling for 3 days because a new size class was added in HTML but not CSS.
  • Step 3 (base ≥ 50) — Multiple tools shipped with hidden hero badges because base was 0.
  • Step 14 (full-site audit) — Added after a tool was registered in toolkit_nav.toml but missing from tool-ecosystem.html and shipped invisible.

The shape of "done"

A tool is "shipped" only when:

  1. Visible on homepage (correct category card + count)
  2. Visible in nav (correct category count)
  3. Visible in tool-ecosystem partial (correct group)
  4. Visible in feedback dropdown
  5. Live OG image
  6. JSON-LD validates (Google Rich Results Test)
  7. Smoke test passes on a fresh browser session

If any of those is no, the tool isn't shipped — it's just deployed.

Cross-references

  • Deployment Playbook — steps 15–17 (cross-link audit, nav count audit, frontmatter completeness)
  • Production Incident Log — every tool that shipped broken
  • ~/.copilot/copilot-instructions.md → "New Tool Build Pattern" — the headline rule
  • ~/.copilot/copilot-instructions-reference.md → "Tool Registry" — the 56-tool table