Skip to content

refactor: make AGENTS.md source of truth, CLAUDE.md as symlink #42

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
recoupableorg merged 3 commits into from
Feb 17, 2026
Merged

refactor: make AGENTS.md source of truth, CLAUDE.md as symlink #42

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0de2e1a
refactor: make AGENTS.md source of truth, CLAUDE.md as symlink
sidneyswift Feb 16, 2026
ee57753
fix: rename header to Agent Instructions
sidneyswift Feb 16, 2026
3e4becd
fix: use inclusive agent naming in AGENTS.md
sidneyswift Feb 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 110 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
# Agent Instructions

This file provides guidance to coding agents like Claude Code (claude.ai/code) and OpenCode when working with code in this repository.

## Repository Overview

This is the Recoup API documentation site built with [Mintlify](https://mintlify.com). It provides API reference documentation for the Recoup platform.

## Git Workflow

**Always commit and push changes after completing a task.** Follow these rules:

1. After making changes, always commit with a descriptive message
2. Push commits to the current feature branch
3. **NEVER push directly to `main`** - always use feature branches and PRs

### Starting a New Task

Branch from `main`:

```bash
git checkout main && git pull origin main && git checkout -b <branch-name>
```

## Project Structure

```
docs/
├── docs.json # Mintlify configuration (navigation, branding, theme)
├── index.mdx # Homepage
├── quickstart.mdx # Getting started guide
├── development.mdx # Development setup guide
├── api-reference/ # API endpoint documentation
│ ├── introduction.mdx
│ ├── openapi.json # OpenAPI spec for API endpoints
│ └── [category]/ # Grouped API endpoints (tasks, artists, chat, etc.)
├── essentials/ # Core documentation pages
├── ai-tools/ # AI tool integration guides
├── logo/ # Brand logos (light.svg, dark.svg)
├── favicon.svg # Site favicon
├── images/ # Documentation images
└── snippets/ # Reusable MDX snippets
```
Comment on lines +27 to +43

@coderabbitai coderabbitai Bot Feb 17, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add language specifier to fenced code block.

The directory tree structure should specify a language for the code fence to improve rendering and satisfy linting rules.

📝 Proposed fix 
-```
+```text
 docs/
 ├── docs.json           # Mintlify configuration (navigation, branding, theme)
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)

[warning] 27-27: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@AGENTS.md` around lines 27 - 43, The fenced code block containing the
directory tree in AGENTS.md is missing a language specifier; update the opening
fence (the triple backticks that start the directory tree) to include a language
like "text" (e.g., change ``` to ```text) so the tree renders correctly and
satisfies linting; locate the fenced block that begins with the directory
listing (lines showing "docs/" and the tree entries) and add the language
specifier to the opening fence.


## Development

Mintlify docs are deployed automatically. To preview locally:

```bash
npx mintlify@latest dev

@coderabbitai coderabbitai Bot Feb 17, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🌐 Web query:

Mintlify CLI dev command 2025 2026 documentation

💡 Result:

Mintlify has two “dev” commands in their docs, depending on which CLI/project format you’re using:

  • If your repo has docs.json (older/common Mintlify docs format): install the mint CLI and run:

    • npm i -g mint
    • mint dev (or npx mint dev)
      Local preview: http://localhost:3000 and you can change the port with --port (e.g., mint dev --port 3333). [1][2]

  • If your repo has mint.json (Starter Kit / newer flow): install the mintlify CLI and run:

    • npm i -g mintlify
    • mintlify dev
      Local preview: http://localhost:3000 and you can change the port with --port (e.g., mintlify dev --port 3333). [3]

Rule of thumb: check your repo root—docs.json ⇒ mint dev; mint.json ⇒ mintlify dev. [2][3]

Sources
[1] Mintlify “Install the CLI / Preview locally” (mint dev) https://www.mintlify.com/docs/installation
[2] Mintlify “CLI installation” (mint dev, npx mint dev, --port, updates) https://mintlify.com/docs/installation
[3] Mintlify Starter Kit “Development” (mintlify dev, mint.json) https://www.mintlify.app/development

Update Mintlify CLI command to match current documentation.

The command npx mintlify@latest dev does not align with official Mintlify CLI documentation. Use one of these commands instead:

  • For docs.json projects: npx mint dev
  • For mint.json projects: mintlify dev

Check your repo root to determine which project format is being used, then apply the corresponding command.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@AGENTS.md` at line 50, Replace the outdated CLI invocation "npx
mintlify@latest dev" in AGENTS.md with the correct Mintlify CLI command for this
repository: if the repo uses docs.json projects use "npx mint dev", otherwise
for mint.json projects use "mintlify dev"; inspect the repo root to determine
whether docs.json or mint.json is present and update the single line containing
"npx mintlify@latest dev" accordingly.

```

## Configuration

All site configuration is in `docs.json`:
- **name**: Site name displayed in navigation
- **colors**: Brand colors (primary, light, dark)
- **logo**: Light and dark mode logo paths
- **favicon**: Favicon path
- **navigation**: Tab and page structure
- **navbar**: Top navigation links and buttons
- **footer**: Social links

## Branding

Reference `Recoup-Chat` codebase for correct branding values:
- **Primary color**: `#345A5D` (from `tailwind.config.ts` primaryGreen)
- **Support email**: `agent@recoupable.com`
- **App URL**: `https://chat.recoupable.com`
- **Website**: `https://recoupable.com`
- **Social URLs**:
- X: `https://x.com/recoupai`
- GitHub: `https://github.com/recoupable-com`
- LinkedIn: `https://www.linkedin.com/company/recoupable`

## Writing Documentation

### MDX Files

Documentation pages use MDX (Markdown + JSX). Key conventions:
- Use frontmatter for page metadata (title, description)
- Use Mintlify components for callouts, code blocks, and interactive elements
- Keep content concise and scannable

### API Reference

API endpoints are documented in `api-reference/` with:
- OpenAPI spec in `openapi.json` for auto-generated endpoint docs
- MDX pages in `api-reference/[category]/` that reference the OpenAPI spec

**CRITICAL: API reference MDX pages should be frontmatter-only.** Do NOT add custom sections (Overview, Availability, etc.) — let Mintlify auto-generate everything from the OpenAPI spec. All descriptions, parameter docs, and response schemas belong in `openapi.json`.

```mdx
---
title: 'List Items'
openapi: 'GET /api/items'
---
```

This is the correct pattern. Nothing else should go in the file.

## Code Principles

From `Recoup-Chat/principles.md`:

- **DRY**: Don't duplicate content across pages - use snippets
- **Single Responsibility**: One concept per page
- **Clear Organization**: Group related pages in directories
- **Self-Documenting**: Use clear titles and descriptions
- **Comments**: Explain 'why', not 'what'
110 changes: 0 additions & 110 deletions CLAUDE.md
View file
Open in desktop

This file was deleted.

1 change: 1 addition & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
AGENTS.md