[Alejandro Lopez (soyalejolopez)]

Category

• New resource (script, agent, guide, analytics, skill)
• Update to an existing resource
• Bug fix
• Docs, site, or tooling

What's in this pull request?

Adds deep links from the Agent 365 Enablement Checklist into the Customer Implementation Guide, and makes npm run check enforce that the two stay in sync.

Deep links

• The guide now opens index.html#advanced/<key> in its Detailed view, scrolls to the step, highlights it, and moves focus to it. <key> is a step code in lowercase (4.04a, 12b, pp3, 5-0) or a section number (04, pp). #simple, #advanced, and the Simple and Detailed buttons behave as before. No guide content changes.
• The change is a small repeatable patch (tools/catalog-build/guide-deeplinks.js, 73 added lines in the generated guide) rather than a hand edit, so it can be reapplied if the guide is regenerated.
• Each checklist task now links to its exact step through a new guideHref() function. Six Defender tasks named their guide step only in words, so they now name its code. One of them, "Review real-time protection rules", had been matching step 2.02; it now points at 2.06 (Set up real-time protection rules).

Keeping the two aligned (npm run check, so it runs on every PR)

• Every checklist reference must name an existing guide section or step and include a step code. A description alone cannot be linked or verified.
• The checklist's guideHref() must build the address the check expects for every reference, and the guide must offer that address.
• The guide must carry the deep-link script exactly as the patch writes it.
• Every cited guide step and section must match the fingerprint recorded in tools/catalog-build/agent365-sync-state.json (its text and links). Editing a cited step fails the check and names the checklist tasks that depend on it. After reviewing them, run npm run sync:agent365 and commit the state file. The pull request template has a matching checkbox.
• The guide's review date moves into the same state file, so bumping its README updated date for a non-content change no longer counts as a review. npm run sync:agent365 -- --guide-reviewed records one.

Weekly workflow: a second job opens every address the checklist links to in a real headless browser and checks that the guide finds each step (npm run test:guide-deeplinks).

Versions: guide 1.3.0 to 1.4.0, checklist 1.0.1 to 1.0.2. The checklist's CONTENT_VERSION and CONTENT_REVIEWED are unchanged because its content was not reviewed.

How it was tested

• npm run check passes: 78 references link to existing steps and sections, the deep-link script is current, and 74 cited steps match their fingerprints.
• Checked that the sync check fails for each drift case: editing a cited step's text, renumbering a step, changing a link inside a step, regenerating the guide without the patch, and hand-editing the patch.
• Opened every address the checklist links to, plus one step and section from each guide section (93 in all), in headless Edge: each reported found, and an unknown key reported missing.
• In a browser, switched from Simple to a deep link and between keys, confirmed the right panel opens and the step is highlighted, and confirmed the checklist's task links resolve to #advanced/2.01, 2.06, 2.02, and 2.07.

Related issues

Follows #567. Part of the revamp tracked in #482.

Checklist

• No private, customer-specific, or unlicensed content, and no secrets
• README front matter is valid: npm ci --prefix tools/catalog-build && npm run check --prefix tools/catalog-build (passes)
• version and updated were bumped (and published was preserved) (guide 1.4.0, checklist 1.0.2)
• Installation and usage steps were tested (see above)
• Files over 5 MB were avoided (the guide was already 2.3 MB; it grew by about 6 KB)
• If this changes the Agent 365 Customer Implementation Guide or Enablement Checklist: I reviewed the checklist tasks and guide steps that cite each other, then ran npm run sync:agent365 --prefix tools/catalog-build (the recorded fingerprints are the baseline; no cited step changed)

See CONTRIBUTING.md for details.