Simplify contextual developer links

[next-devin]

Summary

• derive merchant-to-developer relationships directly from the capability map instead of duplicating capability_ids in page frontmatter
• replace the large capability card with one unobtrusive developer entry link per mapped capability
• remove the irrelevant legacy-identifiers relationship from Get Started and remove links to the retired human capability page
• keep capabilities.json and the six domain bundles as the agent-facing contract

Verification

• npm run build
• rendered Fulfillment Locations shows Developer documentation: Fulfillment
• rendered Get Started has no developer footer
• no runtime console errors related to the change

Coordination

Pairs with NextCommerceCo/developer-docs#52, which removes the public capability page and page-level capability IDs while preserving the JSON map and domain bundles.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	nextcommerce-docs	e810c17	Commit Preview URL Branch Preview URL	Sep 04 2026, 08:37 AM

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Overview

Severity	Count
CRITICAL	0
WARNING	0
SUGGESTION	0

Files Reviewed (2 files)

• scripts/check-capabilities.mjs - 0 issues (previous startsWith host-substring and missing try/catch resolved by origin+pathname check with parse error handling)
• scripts/sync-capabilities.mjs - 0 issues (previous silent .every(...) shape check resolved by per-capability labeled diagnostics)

Resolved since previous review

• scripts/check-capabilities.mjs:39-50 - developer_docs URL validation now uses parsed.origin and parsed.pathname with a try/catch around new URL(), replacing the host-substring check that accepted e.g. developers.nextcommerce.com.evil.example/docs/...
• scripts/sync-capabilities.mjs:30-48 - shape validation now collects per-capability messages with capabilities[index] (id) labels, so failures identify the offending entry and field

Assumptions and unverified items

• Read-only mode; could not run npm run check-capabilities against a malformed map to verify the error path end-to-end
• Files outside the incremental diff (components/developer-resources.tsx, source.config.ts, app/not-found.tsx) are not re-reviewed; their outstanding comments remain valid against current HEAD per the prior review

Previous Review Summaries (2 snapshots, latest commit e87455a)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit e87455a)

Status: 2 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	1

This incremental change addresses most of the previous review's findings: the developer-resources component now uses new URL().pathname for normalization, throws on a missing developer entry page for developer-audience capabilities, and validates the snapshot shape in sync-capabilities.mjs. check-capabilities.mjs now documents its checks accurately and adds a real capability_ids frontmatter rejection and a developer-audience / developer-docs consistency check. Two new issues remain on changed code.

Issue Details (click to expand)

WARNING

File	Line	Issue
scripts/check-capabilities.mjs	40	startsWith(\${DEVELOPER_SITE}/docs/`)is a host-substring check, accepts e.g.developers.nextcommerce.com.evil.example/docs/..., and skips the try/catchused foroperator_docs`

SUGGESTION

File	Line	Issue
scripts/sync-capabilities.mjs	37	.every(...) shape validation collapses to a single boolean; the failure path cannot tell which capability or field was wrong

Files Reviewed (3 files)

• components/developer-resources.tsx - 0 new issues (previous startsWith/empty-developer_docs/Capability interface concerns resolved; first-entry-only suggestion still tracked in existing comment 3932246804)
• scripts/check-capabilities.mjs - 1 new issue
• scripts/sync-capabilities.mjs - 1 new issue

Previously identified, now resolved in this increment

• components/developer-resources.tsx URL normalization now uses new URL().pathname, fixing the base/path seam
• components/developer-resources.tsx empty developer_docs now throws for developer-audience capabilities instead of silently dropping
• scripts/check-capabilities.mjs header now documents the checks it actually performs
• scripts/check-capabilities.mjs abs single-use variable inlined
• source.config.ts capability_ids reintroductions are now caught by check-capabilities.mjs:94 (existing comment)

Assumptions and unverified items

• Could not run npm run build or npm run check-capabilities; read-only mode
• The seam between MERCHANT_SITE and the constructed base in developer-resources.tsx:25 is theoretically fragile but new URL() normalizes it
• Existing comment 3932246819 (source.config.ts capability_ids stripping) and 3932246823 (not-found.tsx redirect) remain valid but their files are outside the incremental diff

Fix these issues in Kilo Cloud

Previous review (commit c7e9732)

Status: 8 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	5
SUGGESTION	3

The refactor is directionally sound — deriving relationships from one source instead of duplicating them in 39 files removes a real drift surface. The concern is that the old duplication was enforced at build time, and the new derivation is not enforced at all. Every failure mode introduced here is silent: the developer footer simply stops rendering, with no error in prebuild and no visible signal in the page.

Issue Details (click to expand)

WARNING

File	Line	Issue
components/developer-resources.tsx	19	Trailing-slash normalization does not cover the base/path seam; a trailing slash in the upstream sources.merchant_docs silently disables every developer link
components/developer-resources.tsx	22	Exact full-URL equality breaks on cosmetic upstream variations (scheme, host case, www., fragment, query) with no build-time failure
components/developer-resources.tsx	24	Empty developer_docs drops a capability silently; Capability interface asserts fields that sync-capabilities.mjs never validates, so a missing operator_docs would throw at build time
scripts/check-capabilities.mjs	8	Documented check #2 is not implemented — no code verifies page relationships, a net loss of build-time verification versus the removed checks
source.config.ts	12	Zod strips unknown keys, so reintroduced capability_ids frontmatter is silently discarded instead of rejected; the corresponding unknown capability id check was deleted in the same PR

SUGGESTION

File	Line	Issue
components/developer-resources.tsx	30	Only developer_docs[0] is surfaced; ordering is an implicit upstream contract and remaining entries are now unreachable in-page
scripts/check-capabilities.mjs	65	abs is single-use and a leftover blank line remains where the rewrite block was removed
app/not-found.tsx	6	Confirm the retired /docs/capabilities URL is redirected on the developer site, not just unlinked here

Files Reviewed (48 files)

• components/developer-resources.tsx - 4 issues
• scripts/check-capabilities.mjs - 2 issues
• source.config.ts - 1 issue
• app/not-found.tsx - 1 issue
• app/docs/[[...slug]]/page.tsx - no issues
• app/llms.txt/route.ts - no issues
• scripts/sync-capabilities.mjs - no issues (comment-only change; see the validation gap noted on developer-resources.tsx:24)
• lib/capabilities.snapshot.json - no issues (regenerated snapshot; disputes API operations moved from payments-gateways to disputes, and legacy-identifiers operator_docs emptied, both consistent with the stated intent)
• AGENTS.md - no issues
• 39 content/docs/**/*.mdx files - frontmatter-only capability_ids removals, no issues

Assumptions and unverified items

• npm run build, npm run check-capabilities, and rendered-output verification could not be run: this review is read-only and Node execution is blocked in the sandbox. The PR description's verification claims were taken at face value.
• Cross-repo coordination with Improve agent setup and evaluation surfaces developer-docs#52 (removal of the public capability page and page-level capability IDs) is outside this diff and was not verified.
• Every capability in the committed snapshot currently has a non-empty developer_docs, so the silent-drop path on developer-resources.tsx:24 is latent rather than active today.

Fix these issues in Kilo Cloud

---

_{Reviewed by minimax-m3 · Input: 28.9K · Output: 3.3K · Cached: 233.5K}

[next-devin]

Addressed the review guardrail findings in e87455a:

• normalize both the page and mapped URLs to URL paths, covering trailing slashes, query strings, fragments, host casing, and other cosmetic origin differences
• validate capability shape during snapshot sync and again during the merchant build
• fail the build when a mapped developer-facing capability has no developer entry page
• reject any reintroduced capability_ids frontmatter instead of silently stripping it
• clean up the stale single-use variable and blank line

Two choices remain intentional:

• the footer shows only developer_docs[0]; the developer map now documents that the best entry page comes first, while the complete list remains available in capabilities.json and the domain bundles
• /docs/capabilities is intentionally removed and asserted to return 404 in developer-docs#52; redirecting a human reader to raw JSON would recreate the same machine-taxonomy leak in a different form

npm run build and the rendered Fulfillment/Get Started checks pass after these changes.

[next-devin]

Resolved the two remaining validation findings in e810c17:

• developer documentation URLs are now parsed and checked by exact origin plus /docs/ pathname, so host-prefix spoofing and malformed URLs fail CI
• snapshot sync now reports the exact capability index/id and malformed field instead of collapsing shape validation to one boolean

npm run check-capabilities and node --check scripts/sync-capabilities.mjs pass.