Agent entry surfaces: llms.txt, AGENTS.md, generated counts, 404, cross-refs

[next-devin]

Agent entry surfaces for the developer portal. A prospect's or developer's agent reaching developers.nextcommerce.com today gets a /llms.txt titled "# Docs" with 338 relative links, no public agent guide, a home page whose endpoint and webhook counts are hand-typed and wrong, and no route to the changelog.

What

• app/llms.txt: named title and scope line, absolute URLs throughout, links to the merchant docs and their index, the changelog, the raw Admin API and Campaigns specs, webhooks, skills, testing, and AGENTS.md. Includes a two-sentence legacy identifiers note so agents stop "correcting" 29next hostnames and headers. llms-full.txt is untouched.
• AGENTS.md (new, public): what the two sites are, where to start, evidence rules, versions, corrections. CLAUDE.md now points at it; the gstack routing it carried was internal and is gone from the public surface. The setup file from Agent setup prompt: /agent-setup/prompt.md — one line to onboard a developer's agent onto NEXT #45 stays separate and is referenced.
• scripts/generate-stats.mjs: home page counts are generated from public/api/admin/2024-04-01.yaml and the webhooks table. Hardcoded values were 175+ and 22; the sources say 203 and 24.
• app/not-found.tsx: 404 with recovery links to docs, Admin API, webhooks, merchant docs, changelog, /llms.txt.
• Home page: a Changelog link (the portal has no changelog; the record lives on docs.nextcommerce.com).
• content/docs/index.mdx: ntk pull / ntk push, matching the Theme Kit guide. The Intro Bootstrap starter line is unchanged pending Alex.
• Webhooks page: one sentence that renewals arrive as transaction.created with billing_cycle >= 1; there is no renewal-named event and readers were inferring this. External checkout guide: points at payment_gateway / payment_gateway_group, which only the bankcard page mentioned. Admin API overview: header spelling now matches the spec.
• scripts/check-agent-surfaces.mjs: post-build assertions for all of the above (npm run check-agent-surfaces). No workflow yet; the repo has no CI, and that is a separate change.

Verified

• npm run build, npm run check-agent-surfaces pass. validate-links reports one pre-existing error unrelated to this change: an h4 fragment in the fulfillment-service guide that the validator does not index.
• Baseline evidence: a clean agent run on 2026-09-03 needed two fetches of the old llms.txt to recover verbatim paths, and reported the 22-vs-24 contradiction.

Decision needed from — Alex on two lines left as-is: the Intro Bootstrap starter recommendation on the overview, and the public support/correction route that AGENTS.md currently marks "being confirmed".

Refs #45. Part of NextCommerceCo/nextcommerce-site#92. Sibling PR on docs covers the merchant site.

🤖 Generated with Claude Code

[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	developer-docs	6b49567	Commit Preview URL Branch Preview URL	Sep 03 2026, 05:44 AM

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

The previous SUGGESTION about description escaping is resolved: the description now flows through linkText, which neutralises [ and ] like the title does.

Files Reviewed (1 changed source file in this incremental diff)

• app/llms.txt/route.ts — 0 issues (previous SUGGESTION addressed)

Previous Review Summaries (2 snapshots, latest commit 1c70301)

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

Previous review (commit 1c70301)

Status: 1 Issue Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	0
SUGGESTION	1

Issue Details (click to expand)

SUGGESTION

File	Line	Issue
app/llms.txt/route.ts	91	Description is not escaped, only the title — if any frontmatter description contains [ or ], the resulting llms.txt line is malformed

Files Reviewed (4 changed files in this incremental diff)

• app/llms.txt/route.ts — 1 issue (SUGGESTION)
• app/not-found.tsx — 0 issues (previous WARNING on external <Link> is fixed)
• scripts/generate-stats.mjs — 0 issues (previous SUGGESTION addressed: webhook count now sourced from spec with table cross-check that fails the build on drift)
• scripts/check-agent-surfaces.mjs — 0 issues (previous SUGGESTION addressed: now asserts both <span>N REST Endpoints</span> and <span>N Webhook Events</span> on the home page)

Fix these issues in Kilo Cloud

Previous review (commit f818df1)

Status: 5 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	2
SUGGESTION	3

Issue Details (click to expand)

WARNING

File	Line	Issue
app/page.tsx	414	<Link> used for external URL (docs.nextcommerce.com/changelog) — should be plain <a>
app/not-found.tsx	18	<Link> used for external URLs on lines 18 and 19 — should be plain <a>

SUGGESTION

File	Line	Issue
app/llms.txt/route.ts	82	Title/description interpolated into Markdown without escaping; risk of malformed llms.txt
scripts/generate-stats.mjs	47	Webhook event regex is brittle; consider deriving count from tools/config.py or generated references
scripts/check-agent-surfaces.mjs	60	Asymmetric post-build check — only webhookEvents substring is asserted, not adminApiOperations

Files Reviewed (12 files)

• AGENTS.md — 0 issues
• CLAUDE.md — 0 issues
• app/llms.txt/route.ts — 1 issue (SUGGESTION)
• app/not-found.tsx — 1 issue (WARNING)
• app/page.tsx — 1 issue (WARNING)
• content/docs/admin-api/guides/external-checkout.mdx — 0 issues
• content/docs/admin-api/index.mdx — 0 issues (header spelling fix is correct)
• content/docs/index.mdx — 0 issues
• content/docs/webhooks/index.mdx — 0 issues (new sentence aligns with TransactionSubscription.billing_cycle schema)
• package.json — 0 issues
• scripts/check-agent-surfaces.mjs — 1 issue (SUGGESTION)
• scripts/generate-stats.mjs — 1 issue (SUGGESTION)

Fix these issues in Kilo Cloud

---

_{Reviewed by minimax-m3 · Input: 20.3K · Output: 1.2K · Cached: 185.5K}