Skip to main content

​
Contributing to Equa Documentation

This guide covers how to contribute to the Equa platform documentation, whether you are an AI agent authoring specs in a Cursor session or a human developer writing guides.

​
Principles

​
Verified Facts Only

Every claim in this documentation must be verified against source code, test output, or other primary evidence. Do not guess, assume, or state something as fact without citing a source. Good:
The authentication module supports Google OAuth via the google-auth.ts handler. Source: equa-server/modules/auth/src/google-auth.ts, Line: 1
Bad:
The authentication module probably supports multiple OAuth providers.

​
Citation Format

Use one of these citation formats: Inline file reference: 
Source: equa-server/modules/auth/src/google-auth.ts, Line: 42
Code block with file path: 
```typescript
// File: equa-server/modules/auth/src/google-auth.ts, Lines: 10-25
export async function handleGoogleAuth(req: Request) {
  // ...
}
```
Multiple sources: 
Sources:
- equa-web/src/modules/auth/pages/login.tsx, Line: 15 (frontend form)
- equa-server/modules/auth/src/google-auth.ts, Line: 42 (backend handler)

​
No Stale Information

When documenting a feature, always verify the current state of the code before writing. If code has changed since a document was last updated, update the document or flag it for review.

​
Mintlify Formatting

​
Frontmatter

Every .md file must start with YAML frontmatter: 
---
title: "Page Title"
description: "One-line description of this page"
---
Use root-relative paths without file extensions: Good: [Authentication](/specs/001-authentication) Bad: [Authentication](./specs/001-authentication.md) Bad: [Authentication](specs/001-authentication)

​
Headings

  • Use # for the page title (one per page)
  • Use ## for major sections
  • Use ### for subsections
  • Avoid em dashes and apostrophes in headings (they break Mintlify anchor links)

​
Components

Mintlify supports special components. Use them where appropriate: 
<Note>Important information the reader should know.</Note>
<Warning>Something that could cause problems if ignored.</Warning>
<Tip>Helpful but optional information.</Tip>

<CardGroup cols={2}>
  <Card title="Card Title" href="/path">Description</Card>
</CardGroup>

<AccordionGroup>
  <Accordion title="Question?">Answer.</Accordion>
</AccordionGroup>

​
Spequa Process

Documentation for Equa features follows the Spequa spec-driven process:

​
1. Specify

Create a specification by examining the actual source code. Use the templates/feature-spec.md template. Every section must cite real file paths and line numbers.

​
2. Plan

Break the specification into an implementation plan with phases and dependencies.

​
3. Tasks

Create a task breakdown with individual, verifiable tasks.

​
4. Implement

Write the documentation, verifying each claim against the codebase as you go.

​
5. Review

All documentation goes through review before being marked COMPLETE:
  • Technical accuracy review (does it match the code?)
  • Completeness review (are all sections filled?)
  • Citation verification (do all file references resolve?)

​
For AI Agents

When authoring documentation in a Cursor or Claude session:
  1. Always read source code first. Use the Read tool to inspect the actual files before writing about them.
  2. Cite every claim. Include file paths and line numbers for every technical statement.
  3. Use templates. Start from the appropriate template in templates/.
  4. Update the dashboard. After completing a document, update its status in README.md from NOT STARTED to DRAFT (or REVIEW if fully verified).
  5. Do not fabricate. If you cannot verify something, write “UNVERIFIED — requires manual inspection” instead of guessing.
  6. Run locally. Verify your changes render correctly with npx mintlify dev before marking complete.

​
For Human Contributors

​
Local Development

# Start the Mintlify dev server
npx mintlify dev

# The site will be available at http://localhost:3000
# Changes to .md files are hot-reloaded

​
Adding a New Document

  1. Choose the appropriate template from templates/.
  2. Create the .md file in the correct directory.
  3. Add the page to the navigation section in docs.json.
  4. Update the status in README.md.
  5. Run npx mintlify dev to verify rendering.

​
Review Workflow

  1. Local: Author and verify locally with npx mintlify dev.
  2. Staging: Push to a branch for staging review.
  3. Production: Merge to main for deployment.

​
Status Tracking

When you complete or update a document, update its row in README.md:
StatusMeaning
NOT STARTEDNo content authored yet
DRAFTInitial content written, not yet verified
REVIEWContent verified, awaiting peer review
COMPLETEReviewed and approved

​
Questions?

Open an issue on GitHub or reach out to the documentation team.