> ## Documentation Index
> Fetch the complete documentation index at: https://docs.equa.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing Guide

> How to contribute to the Equa platform documentation

# 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:**

````markdown theme={null}
```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:

```yaml theme={null}
---
title: "Page Title"
description: "One-line description of this page"
---
```

### Internal Links

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:

```markdown theme={null}
<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](/onboarding/spequa-workflow) 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

```bash theme={null}
# 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`:

| Status      | Meaning                                   |
| ----------- | ----------------------------------------- |
| NOT STARTED | No content authored yet                   |
| DRAFT       | Initial content written, not yet verified |
| REVIEW      | Content verified, awaiting peer review    |
| COMPLETE    | Reviewed and approved                     |

***

## Questions?

Open an issue on [GitHub](https://github.com/EQUAStart/equa-docs/issues) or reach out to the documentation team.