Cursor & other editors

Tangly’s primary agent integration is the Claude Code skills. For editors that don’t use Claude Code natively, the next-best surface is JSON Schema autocomplete — every modern editor has it, and Tangly publishes a schema for docs.json.

JSON Schema autocomplete

Add $schema to the top of your docs.json:

{
  "$schema": "https://tangly.dev/schema/docs.json",
  "name": "My docs"
}

Any LSP-aware editor will:

• Autocomplete every top-level field (navigation, colors, analytics, etc.).
• Validate values inline (hex format on colors.primary, enum membership on theme).
• Show descriptions on hover, pulled from the Zod schema’s JSDoc comments.

This works in:

• Cursor — out of the box. The built-in JSON LSP picks up $schema.
• VS Code — out of the box.
• Zed — out of the box.
• JetBrains IDEs (IntelliJ, WebStorm, PyCharm) — out of the box.
• Neovim with jsonls — out of the box.
• Windsurf — out of the box (Windsurf is a fork of VS Code).

If you’d rather pin to a local copy of the schema (no network):

{
  "$schema": "./node_modules/tangly/schema/docs.json"
}

tangly migrate rewrites the URL to whichever form you ran the command from.

Cursor rules

Cursor supports .cursorrules (legacy) and .cursor/rules/ (current). Tangly doesn’t ship one by default — but adding one is straightforward:

.cursor/rules/
└── tangly.md

---
description: Conventions for the docs site in this repo
globs: ["docs/**/*.mdx", "docs/docs.json"]
---

This repo's docs site uses Tangly. When editing files under `docs/`:

- Frontmatter must include at minimum `title` and `description`.
- Internal links use absolute slugs (`/guides/foo`), no `.mdx` extension.
- Don't add a `# Title` line to the top of pages — Tangly renders the page H1 from frontmatter.
- Run `bunx tangly check` before committing.

See `docs/guides/authoring/pages.mdx` for the full conventions.

The rules file scopes its guidance to docs/ so it doesn’t pollute non-docs work.

Windsurf

Windsurf’s “rules” feature is the same shape as Cursor’s. Same file works.

Aider

Aider reads CONVENTIONS.md from the repo root by default. Same pattern:

# CONVENTIONS.md

The docs site under `docs/` uses Tangly.
- Frontmatter: `title`, `description`.
- ...

For project-wide instructions (not just docs), see Conventions → AGENTS.md.

Codex CLI

Codex respects AGENTS.md (and CLAUDE.md). Same conventions file works for both. See Conventions.

What if my editor doesn’t support JSON Schema?

A surprising number of small / niche editors do — helix, kakoune, micro via plugins. Worst case, the file is just JSON. You lose autocomplete; nothing else breaks.

llms.txt as a fallback

For editors with no AI integration at all, the llms.txt Tangly emits is the universal fallback. Any agent that can fetch a URL can read it.