From 0de2e1a49ebced77b36ddee1d6b0946b0c2e2225 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Mon, 16 Feb 2026 18:03:50 -0500 Subject: [PATCH 1/3] refactor: make AGENTS.md source of truth, CLAUDE.md as symlink --- AGENTS.md | 110 +++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 111 +----------------------------------------------------- 2 files changed, 111 insertions(+), 110 deletions(-) create mode 100644 AGENTS.md mode change 100644 => 120000 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..c21e44dc --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,110 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) 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 +``` + +## 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 +``` + +## Development + +Mintlify docs are deployed automatically. To preview locally: + +```bash +npx mintlify@latest dev +``` + +## 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' diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index c21e44dc..00000000 --- a/CLAUDE.md +++ /dev/null @@ -1,110 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) 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 -``` - -## 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 -``` - -## Development - -Mintlify docs are deployed automatically. To preview locally: - -```bash -npx mintlify@latest dev -``` - -## 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' diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 00000000..47dc3e3d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file From ee5775375446ed3e737d672a2979180cb8fb346c Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Mon, 16 Feb 2026 18:12:45 -0500 Subject: [PATCH 2/3] fix: rename header to Agent Instructions --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index c21e44dc..85162075 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,4 @@ -# CLAUDE.md +# Agent Instructions This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. From 3e4becdbba75b79d203230a92b8c0c8aa7519a68 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Tue, 17 Feb 2026 14:01:16 -0500 Subject: [PATCH 3/3] fix: use inclusive agent naming in AGENTS.md --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 85162075..86350a79 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # Agent Instructions -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +This file provides guidance to coding agents like Claude Code (claude.ai/code) and OpenCode when working with code in this repository. ## Repository Overview