# RAG Documentation Server Agreements
This file stores agreed-upon conventions and prompt context for interacting with the AI assistant.
## Formatting Rules
- Add new agreements under relevant sections with dates
- Use `code fences` for technical terms
- Prefix temporary rules with [WIP]
## Core Agreements
- Repository hosts only one TypeScript package
- Conform code you write with the rules in .prettierrc
- Prefer arrow functions
## TypeScript Configuration
- Uses NodeNext module resolution (configured in tsconfig.json)
- All imports must use explicit file extensions:
- `.js` for JavaScript/TypeScript files
- `.json` for JSON files
- Other asset types as appropriate
- Type checking enabled for all files
## GitHub Integration Rules
### Local Operations (Use CLI)
- All Git operations (commits/branches/pushes):
- Must use raw git commands
- Format commit messages directly via CLI
- Never use `npm run commit` or GitHub MCP tools
### Platform Interactions (Use MCP)
- Limit GitHub MCP to:
- PR management/comments
- Issue tracking
- Repository metadata
- Secret management
### Security & Configuration
- Never store credentials in code/configs
- Derive repository info from:
- Local .git/config
- package.json metadata
## RagDocs Usage
- When installing packages, always add their documentation to ragdocs-mcp
- Before starting problem solving, first query ragdocs-mcp for relevant documentation
- Use RAG-based knowledge retrieval for technical decisions rather than assumptions
## Package Management Rules
- Never modify package.json directly - always use `npm install <package>` commands
- Prefer exact version specifications when adding dependencies
- Ensure package-lock.json is committed after dependency changes
## Testing Conventions
- Use Mocha and Chai for all unit tests
- Follow AAA pattern (Arrange-Act-Assert)
- Colocate tests with `*.test.ts` suffix next to source files
- Use `__tests__` directories for complex modules
- Maintain these coverage thresholds:
```text
Statements: 80%
Branches: 75%
Functions: 85%
Lines: 80%
```
## Documentation Structure
1. Main README.md serves as package consumer documentation:
- Must include package consumption instructions (installation, basic usage)
- Contains high-level overview and essential usage
- Links to detailed documentation files (e.g. TECHNICAL_DESIGN.md)
- Development/debug setup belongs in CONTRIBUTING.md
- Maintains these mandatory sections:
- Main Title
- Badges
- Introduction (1-3 sentence summary)
- Features
- Table of Contents
2. Documentation maintenance rules:
- New chapters require immediate Table of Contents updates
- Technical design specifics reside in TECHNICAL_DESIGN.md
- Contributor guidelines remain in CONTRIBUTING.md
- AI-specific instructions belong in .clinerules
- Human-facing documentation lives in MD files (README.md, CONTRIBUTING.md etc.)
- Additional documentation files must include ## "A TITLE" section with:
- One-sentence summary of the file's purpose
- Link to the related MD file for detailed guidelines