fix(skills): add router IDE rule files and stop silent 404 installs

[r-marques]

Follow-up to #267, addressing @eruizgar91's REQUEST_CHANGES review — it landed ~8 minutes after
that PR merged, so the fixes need their own PR.

Both findings verified independently against the repo before folding anything in.

HIGH — the install page promised something that worked for 2 of 8 tabs

#267 added: "Every install method below works for either — swap nevermined-payments for
nevermined-router in the paths." Confirmed false. Each rule directory contains exactly one file,
the payments one, and Copilot/Codex load a single file (.github/copilot-instructions.md,
AGENTS.md) with no skill-name segment to swap at all.

The failure was silent, which is the actually dangerous part. All six curl commands used -o
with no --fail. Reproduced before fixing:

$ curl -s -o probe.mdc .../.cursor/rules/nevermined-router.mdc   # did not exist
  exit=0   file contents: [404: Not Found]
$ curl -sf -o probe2.mdc  (same URL)
  exit=22  file created: no

Cursor then loads 404: Not Found as a valid rule for every .ts/.js/.py file, and the
assistant has zero Router knowledge with nothing anywhere saying so.

Rather than retract the sentence, this makes it true. Adds condensed router rules for Cursor,
Windsurf, Cline and Amazon Q, generated from one shared body so they cannot drift, and all inside
the 6,000-character Windsurf limit the page itself documents — 5,292–5,457 chars. (My first draft
was 6,057 and had to be trimmed; the limit is only mentioned in the Windsurf tab, easy to miss.)

For Copilot and Codex CLI the claim genuinely cannot be made true by swapping a path, so it is
scoped honestly and those users are pointed at the full skill. The "Supported Tools at a Glance"
table — which still listed payments-only paths and contradicted the new claim two screens later — now
shows a Router column.

--fail added to all six commands either way, per the review.

Root cause of the missing Cursor file — caught pre-commit

.gitignore had a blanket /.cursor, so .cursor/rules/nevermined-router.mdc would have been
silently left out of the commit and shipped as the exact 404 this PR fixes. It only surfaced
because the file was absent from git status. nevermined-payments.mdc survives the rule only
because it was tracked before the rule existed.

Narrowed to /.cursor/* + !/.cursor/rules/, so published rules track normally while local Cursor
state stays ignored. Verified both directions — the rule file is no longer ignored, and
.cursor/mcp.json / .cursor/foo/bar still are.

LOW — mode A example taught the wrong version→header mapping

paying.md paired a v1 request ("x402Version": 1) with a v2 response ("x402Version": 2,
PAYMENT-SIGNATURE) inside the same numbered step, while the table 14 lines later says v2 →
PAYMENT-SIGNATURE, v1 → X-PAYMENT. Now a coherent v1 round trip, plus an explicit line on what a
v2 target returns instead. As @eruizgar91 noted there is no runtime harm — the file already says to
read the header name off the response — but it is a comprehension defect in a file copied verbatim
into agent context, at the one step where the header name decides whether an already-minted,
already-reserved payment is accepted.

Also folded in

• @aaitor's feat(skills): add the nevermined-router agent skill #267 watch-item, now due. The first publish landed at 0.1.0 as intended, so the
  one-shot version: "0.1.0" seed is removed — leaving it would re-try 0.1.0 on every future
  publish, hit the "already published" no-op, and silently freeze the skill at its first version.
  Skill bumped to 0.1.1 to match what auto-increment will produce. The SKILL_VERSION plumbing
  stays for the next new slug.
• @eruizgar91's noted tension on the Exa paragraph. It dead-ended at "tell the user it needs an
  account". It now points at the out-of-band rail — /integrations/exa, a $7 x402 card-delegation
  purchase that provisions or tops up an Exa API key, agent-driven — while keeping the correct point
  that it cannot go through /router/route. I read that page to confirm the description before
  writing it.

Verification

• Every raw.githubusercontent URL on the install page resolves to a real, committable file — 10/10, checked including git check-ignore so an ignored file can't pass as present. That is the exact check that would have caught the original bug.
• mintlify broken-links → no broken links found.
• Workflow YAML parses; both matrix legs now on auto-increment; SKILL_VERSION threading intact in both steps.
• Rule files: 5,292–5,457 chars, all under the documented 6,000 limit.

Deliberately not done

.github/copilot-instructions.md and AGENTS.md are single-purpose payments files. Merging Router
content into them would change what every Copilot/Codex user in this repo sees, and it is a content
decision rather than a fix — so the page is honest about the gap instead. Happy to open an issue if
we want Router guidance there.

Refs nevermined-io/nvm-monorepo#2595

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Nevermined	🟢 Ready	View Preview	Aug 3, 2026, 1:47 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[eruizgar91]

Adds the four missing nevermined-router IDE rule files, un-ignores .cursor/rules/ so they actually ship, and makes the install commands fail loudly instead of writing 404: Not Found into a user's rules directory. The change is coherent and the risky parts hold up under checking.

Verdict: APPROVE — no finding survived verification at or above the confidence bar.

Effort level: quick — bugs lens plus repository-invariants lens, one verifier per finding. This level does not examine git log/git blame on the touched lines, so a regression that quietly re-opens something an earlier commit closed would not have been caught here. Conventions were read from the repo's CLAUDE.md and AGENTS.md (both found and applied; nothing was inferred blind).

Checked and clean

• .gitignore negation actually works. /.cursor/* + !/.cursor/rules/ re-includes the directory correctly — all four new rule files are tracked at the head commit, brand-new untracked files under .cursor/rules/ (including nested ones) show up in git status, and .cursor/mcp.json is still ignored. No other rule touches .amazonq, .clinerules or .windsurf.
• The four raw.githubusercontent.com/.../main/... URLs will resolve after merge. Every path exists and is tracked at the head commit.
• curl --fail behaves as the page implies. On a 404 it exits 22 and writes no file at all — no truncated or 404: Not Found artifact left behind.
• Dropping the workflow version pin is correct. The nevermined-router slug already published at 0.1.0 (run 30817857071, commit 943f53f, both matrix legs green), so auto-increment yields next-patch 0.1.1 — exactly the SKILL.md frontmatter bump in this PR. Consistent, not a 1.0.0 surprise.
• Cursor .mdc frontmatter matches the working precedent. Byte-identical glob list to nevermined-payments.mdc; Cline's paths: frontmatter likewise mirrors its sibling. Windsurf file is 5,240 chars, inside the 6,000 limit.
• paying.md v1/v2 change is a fix, not a regression. It replaces a v1-request/v2-response pairing with a coherent v1 round trip, keeps the v2 default documented in the following paragraph, and the file already says to read the header name off the response rather than hardcoding it.
• No staging_sandbox/staging_live leakage; Mintlify frontmatter complete; /products/router/overview and /integrations/exa both resolve in docs.json.

Raised and deliberately discarded

Four candidates were verified and all landed below the bar:

• Codex CLI's Router availability (conf. 75) — the new bullet says Copilot and Codex CLI have "nothing to swap", but the Codex tab's own .agents/skills/ install does take a skill name, and the rewritten table hedges to "No via AGENTS.md". Real inconsistency, but the table discloses it and the tab documents the path; a follow-up nicety, not a blocker.
• lastUpdated not moved off 2026-08-03 alongside the 0.1.1 bump (conf. 68) — the sibling skill does bump both together, but the same header line also carries the version number, so staleness is still detectable.
• The four new rule files stop at the Exa dead-end while this same commit teaches SKILL.md that it isn't one (conf. 62) — an omission in a deliberately condensed surface rather than a false assertion.
• CLAUDE.md's "v2 headers are the ONLY supported format" vs. the v1 example (conf. 10) — that rule governs the Payments SDK server surface, not the Router paying a merchant whose version is the merchant's choice.

Also out of scope by policy: pre-existing issues (CLAUDE.md's IDE-surface inventory is stale — it names a .cursorrules that doesn't exist and omits .windsurf/rules/, .clinerules/, .amazonq/rules/), and the disclosed, intentional decision not to propagate Router guidance into .github/copilot-instructions.md and root AGENTS.md.