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

# Contribute Symbols

> Validate and submit a .kicad_sym to the open-source Trace symbol library via a GitHub PR.

Contributions add symbols to the open-source library
`buildwithtrace/trace-kicad-symbols-lib`. Validation runs locally (no backend); submission
is proxied to the backend, which opens the PR.

<Steps>
  <Step title="Validate the file — POST /api/contribute/validate">
    Multipart form with `file` (`.kicad_sym` or `.kicad_mod`, ≤ 10 MB). Parsed locally by
    `kicad_parser.ts` against KiCad Library Conventions (KLC). **No auth.**

    ```json theme={null}
    { "valid": true, "errors": [], "warnings": [],
      "symbolName": "LM358", "pinCount": 8 }
    ```
  </Step>

  <Step title="Submit — POST /api/contribute/submit">
    **Auth required.** Multipart form: `file`, `library`, `description`, `authorName`,
    `authorEmail`. Proxies to `POST /api/v3/components/submit`, which creates the PR
    (the backend holds the GitHub token).

    ```json theme={null}
    { "success": true, "submissionId": "…",
      "message": "Symbol submitted for review. You'll be notified when it's approved." }
    ```
  </Step>
</Steps>

## Validation rules

* File must be `.kicad_sym` (a `.kicad_mod` is also accepted and detected as a footprint).
* Max 10 MB.
* Must be a valid KLC S-expression with a named symbol, at least one pin, and required
  properties (Description, Keywords, Reference); missing datasheet is a warning.

## Backend submit payload

The proxy derives and forwards:

```json theme={null}
{ "type": "symbol", "name": "…", "library": "…", "description": "…",
  "file_content": "…", "file_format": "kicad_sym", "pin_count": 8, "pad_count": 0 }
```

| Status | Meaning                 |
| ------ | ----------------------- |
| `400`  | Missing required fields |
| `401`  | Not authenticated       |
| `422`  | Invalid symbol file     |

<Info>
  Track submission status from `/my-symbols`. PRs go through human KLC review before merge.
</Info>