Project conventions for agents

The bundled skills cover Tangly itself. They don’t know your project — your conventions, your team’s rules, the historical reasons one folder is structured weirdly. That’s what these conventions files are for.

aiContext frontmatter

Per-page hint. The string lands in the page’s machine-readable index when an agent fetches llms.txt and gets passed as additional context when the page is read by AI surfaces (the contextual buttons, future chat integration).

---
title: Webhook signing
description: HMAC-SHA256 signing for incoming webhooks.
aiContext: |
  Common confusion: developers conflate the signing key (used to verify the
  signature) with the API key (used to authenticate to the API). They are
  different secrets with different rotation cycles.
---

The aiContext is not rendered to the page — it’s metadata-only. Reach for it when:

• A page has a non-obvious failure mode that agents would otherwise miss.
• The page documents something the canonical name suggests something different.
• You’ve watched agents make the same mistake on this page repeatedly.

If the context belongs in the page itself (a <Note> the reader should see), don’t smuggle it into aiContext.

AGENTS.md

The emerging standard for “instructions every agent should read on first contact.” Drop one at the repo root:

# AGENTS.md

This repo is a Tangly documentation site.

## Conventions

- Edit `.mdx` under `docs/`. Each page has frontmatter; required fields: `title`, `description`.
- Run `bunx tangly check` before committing. The build catches more — `bunx tangly build` is the final gate.
- Internal links: absolute slugs, no `.mdx` (`/guides/foo`, not `./foo.mdx`).
- Don't add `# Title` to the top of pages — Tangly renders H1 from frontmatter.
- Use Bun, not npm/yarn/pnpm.

## Tools

- `tangly init` — scaffold.
- `tangly dev` — dev server (port 4321).
- `tangly check` — validate.
- `tangly build` — production build.
- `tangly migrate` — convert mint.json → docs.json.

See `docs/reference/cli/` for full flags.

## Don'ts

- Don't reach for `eject` to make small changes — the doc has 5 layers of customization before that.
- Don't introduce frameworks beyond Astro + MDX + Tailwind.
- Don't run `oxfmt` on `*.mdx` / `*.md` — it mangles them.

Aider, Codex CLI, Continue, and Claude Code all read AGENTS.md automatically.

CLAUDE.md

Claude Code’s variant. It reads CLAUDE.md if present, otherwise AGENTS.md. If you have both, Claude Code reads CLAUDE.md; everything else reads AGENTS.md.

For a Tangly project that exists alongside other agent-driven workflows, the safe default is one AGENTS.md file with a CLAUDE.md symlink:

ln -s AGENTS.md CLAUDE.md

Or vice versa. Both files describing the same conventions is fine; just keep them in sync.

What to put in conventions files

Three categories:

1. Tooling. Which package manager. Which formatter. Which test runner. Which CLI commands matter.
2. Code conventions. Naming, file organization, “we do X this way for historical reasons.”
3. Don’ts. Things agents reach for that you’ve banned. Be explicit — agents don’t infer “we don’t use npm” from “we use bun.”

What NOT to put in:

• The full reference for tools — link out, don’t duplicate.
• Open product roadmap. Goes stale faster than agents respect it.
• Praise / tone hints (“be helpful”). The agent already has its own posture.

Per-folder rules (Cursor, Continue)

For different conventions in different parts of the repo, both Cursor (.cursor/rules/<name>.md) and Continue (.continueignore + per-folder context) support glob-scoped rules.

Tangly’s own repo uses this for its docs vs. its source code:

The docs.md rule pulls in the Tangly skill knowledge; the src.md rule talks about TypeScript / Bun / oxlint / oxfmt.

llms.txt isn’t a substitute

llms.txt is what’s in your docs. AGENTS.md is how to work with the repo. They overlap (your conventions probably belong in docs too) but answer different questions.

For a polished agent experience: AGENTS.md describes the workflow + tools, llms.txt describes the docs content, the bundled skill knows how to use the CLI. All three play different roles.