Skip to main content

AI assistants

Claude Code, Cursor and Codex are good at Next.js. They are wrong about Tanqory apps by default, and confidently so — because almost everything specific to this platform fails silently, which is exactly the class of thing a model cannot infer from your code.

Left to guess, an assistant will tell you to open localhost:3000 to check your work, put a new page at src/app/embed/settings/, ask for a read_orders permission, and add security headers that make the frame go blank. Each is reasonable somewhere else. Each is wrong here, and none of them produces an error message.

You already have the fix​

tanqory app init puts AGENTS.md at the root of your project, plus a CLAUDE.md pointing at the same file. Assistants read these on their own — no setup, no extension, no network call.

order-notifier/
├── AGENTS.md      ← read by Cursor, Codex, and most others
└── CLAUDE.md      ← the name Claude Code looks for; one line, points at AGENTS.md

Two names because different tools look for different filenames. One source of content, so they cannot drift apart.

If your project predates the scaffold, copy AGENTS.md out of a fresh tanqory app init into your own repo.

What is in it​

Not a summary of these docs. Every line is something that can go wrong without producing an error, which is the only reason it needs saying twice:

  • The embedded page runs only in an iframe — Loading… in a browser tab is correct behaviour, and not something to debug
  • useTanqoryApp() returns an error you must render, or every failure looks identical to a slow load
  • New screens go under [storeId]; a plain embed/page.tsx 404s the moment a merchant opens the app
  • apiBase is always https://app.tanqory.com — never a host with a region in it
  • Webhooks verify against the raw body
  • Never send X-Frame-Options; never redirect to a login page
  • Permissions are domain.action from a closed catalogue of 246 — there is no read_orders form
  • Declaring a menu item does not create a route
  • A symptom table, so the assistant matches before it edits

Try it​

With the project open in your assistant:

Add a settings screen and show it in the Orders menu.

Right — it creates src/app/embed/[storeId]/settings/page.tsx, renders error before ready, adds an entry to navigation.items in tanqory.app.json, and tells you to look at it with tanqory app dev.

Wrong, and how you will know — it creates src/app/embed/settings/page.tsx, or suggests opening localhost:3000/embed/settings to check. If you see either, the assistant is not reading AGENTS.md: confirm the file is at the repository root and that the assistant's working directory is the project, not a parent folder.

Other things worth pointing an assistant at​

tanqory.app.jsonAdd the $schema line and the editor validates the manifest as you type — see Manual setup
PermissionsThe full catalogue. Paste the list rather than letting a model invent scope names
This documentationAssistants that can browse do better with a URL than with a guess

What Tanqory does not offer yet​

There is no Tanqory MCP server. If you find a reference to one, it describes intent rather than something you can connect to today.

AGENTS.md in your project is the supported path, and it needs no network.