Capability map, domain bundles, page metadata, deterministic validation, first CI workflow - #50
Merged
Conversation
…bundles content/capabilities.yaml is the hand-authored index; generate-capability-map.mjs validates it against the stable Admin API spec (operations by tag or id, webhook events), the content tree (developer pages), and the skills table, then writes lib/generated/capabilities.json and the generated /docs/capabilities page. Served at /capabilities.json (schema at /capabilities.schema.json) and rendered into six plain-Markdown bundles at /llms/<bundle>.txt: capability records for one domain followed by the full text of the developer pages they cite, with MDX components converted to Markdown. llms.txt lists the map and the bundles before the full corpus. Frontmatter gains audience, capability_ids, status, last_verified. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…ng fragments, first CI workflow validate-links now regenerates the reference trees first (same sequence locally and in CI) and accepts fragments for every heading level, which clears the standing h4 false alarm in apps/guides/fulfillment-service.mdx:150. check-agent-surfaces gains assertions for the capability map, the readable page, the bundles (size budget 400 KB, no MDX residue, absolute links), and llms.txt ordering. .github/workflows/ci.yml: npm ci, build, check. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…ved from the map
Counting rule (frozen): git-tracked content/docs/**/*.{md,mdx}; generated trees
are ignored. 67 authored pages, 60 lacked a description. check-frontmatter.mjs
requires a description on every authored page, validates the new fields, and
keeps capability_ids consistent with the map (--write inserts them). Also fixes
two typos found in passing (nak push, Submitting).
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Every developer page the map cites (or that declares capability_ids) renders a panel linking the merchant guides for the same capability; the post-build check asserts the panel on every cited page. AGENTS.md and the 404 page point at the map and bundles. check-live-surfaces.mjs runs against the deployed sites weekly: sitemap, robots, llms.txt, map and bundle integrity, 404 recovery, the merchant search budget, and the deterministic half of the 10-question smoke set. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
next-devin
marked this pull request as ready for review
September 3, 2026 09:31
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
developer-docs | 0843dea | Commit Preview URL Branch Preview URL |
Sep 03 2026, 10:09 AM |
![kilo-code-bot[bot]](https://avatars.githubusercontent.com/in/2193792?s=60&v=4){kind=small}
Code Review SummaryStatus: No Issues Found | Recommendation: Merge The incremental diff since
Files Reviewed (1 file)
Previous Review Summaries (2 snapshots, latest commit d9434c7)Current summary above is authoritative. Previous snapshots are kept for context only. Previous review (commit d9434c7)Status: No Issues Found | Recommendation: Merge All 4 findings from the previous review at
Two additional fixes landed in
Files Reviewed (incremental: 6 files)
Previous review (commit 55f1096)Status: 4 Issues Found | Recommendation: Address before merge Overview
Issue Details (click to expand)WARNING
SUGGESTION
Files Reviewed (24 files)
MDX frontmatter-only changes across ~60 docs pages were spot-checked and are consistent with Reviewed by minimax-m3 · Input: 19.7K · Output: 1.1K · Cached: 148.6K |
…fail on unmatched operation tags, least-privilege workflows Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
… last_verified dates Same two fixes as the NextCommerceCo/docs#34 review, applied to this repo's copies. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
… the whole file Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
next-devin
added a commit
that referenced
this pull request
Sep 4, 2026
) * check-live-surfaces: bounded concurrency and timeouts as failed checks, not crashes The first production run opened ~190 connections at once for the map-link sweep and died on an unhandled connect timeout. Link checks now run 8 at a time with a 20 s timeout each; a network error is reported as status 0 on that check instead of aborting the run. Against production after #50 and docs#34 deployed: 132 passed, 0 failed. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * check-live-surfaces: side-effect-only forEachLimit; drop the unused results array Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * check-live-surfaces: a throwing item is a failed check, not a crashed sweep Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds the platform capability map and the surfaces derived from it, plus the validation this repo was missing. Step 6 of the docs agent-accessibility work that #48 started.
What to look at
content/capabilities.yamlis the only hand-authored input: 14 capabilities, 6 bundles. Everything else is generated from it, the stable spec, and the content tree byscripts/generate-capability-map.mjs, which fails the build on an unknown page, operation, event, skill, or bundle./capabilities.json(schema at/capabilities.schema.json),/docs/capabilities, and/llms/{platform,admin-api,payments,campaigns,storefront,apps-webhooks}.txt.docs.nextcommerce.comconsumes the ids in Consume the platform capability map: capability_ids, developer resources panel, checks docs#34.lib/plain-text.tsturns the processed MDX into plain Markdown for the bundles (callouts to blockquotes, tabs to bold labels, cards to lists, mermaid to fences).check-agent-surfacesfails if a component tag survives.components/capability-links.tsx), asserted post-build.validate-linksregenerates first and accepts every heading level as a fragment target; the standing false alarm atapps/guides/fulfillment-service.mdx:150is gone without editing the page..github/workflows/ci.ymlis the repo's first workflow:npm ci,npm run build,npm run check.description; all do now, pluscapability_idsderived from the map (check-frontmatter --write). Counting rule is in the script header.scripts/check-live-surfaces.mjs(weekly workflow) checks the deployed sites and the deterministic half of the 10-question smoke set.Measured locally
Budget 400 KB each; the full corpus stays at about 1.5 MB and llms.txt now lists it after the bundles.
Sequencing
Branched from
main; merges cleanly on top of #49 (trial-merged). Merge #49 first so the legacy-identifiers wording lands once.Not asking for a second source of product truth: links, operations, and events come from the spec and the pages, and the map loses whenever they disagree.
Decision needed from: none.
🤖 Generated with Claude Code