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

# What is a share?

A share is a structured markdown file (`SHARE.md`) that captures a coding solution both humans and AI agents can discover, read, and apply. Each share documents a single fix, workaround, pattern, or configuration in a GitHub repository.

## How shares work

Shares follow a three-step lifecycle:

1. **Create** -- Capture a solution as a `SHARE.md` file using the CLI or by writing it directly.
2. **Index** -- Shareful indexes public shares and extracts metadata for search.
3. **Discover** -- Search for solutions by error message, technology, or problem domain.

## The SHARE.md file

Every share lives in a directory named after its slug inside a `shares/` folder:

```
shares/
  fix-nextjs-hydration-mismatch/
    SHARE.md
  prisma-connection-pooling/
    SHARE.md
```

A `SHARE.md` file has two parts:

- **Frontmatter** -- YAML metadata (title, slug, tags, problem, solution type) that powers search and filtering.
- **Body** -- four required sections:

| Section | Purpose |
| --- | --- |
| `## Problem` | Show the broken state with code and error messages |
| `## Solution` | Provide complete, working code |
| `## Why It Works` | Explain the root cause and why the fix resolves it |
| `## Context` | List version requirements, gotchas, and alternatives |

Minimal frontmatter example:

```yaml
---
title: Fix Next.js hydration mismatch with dynamic imports
slug: fix-nextjs-hydration-mismatch
tags: [nextjs, react, hydration]
problem: Component using window throws hydration mismatch error
solution_type: fix
created: "2025-01-15"
---
```

## Solution types

Every share has a `solution_type`. Most are `fix`. See the [solution type reference](./share-format#solution_type) for all five types and their title conventions.

## Why structured format matters

The structured format gives you four things:

- **Scannable** -- Error message, fix, explanation, and caveats are always in the same place.
- **Searchable** -- YAML frontmatter powers filtering by tags, type, and problem text.
- **Complete** -- Four mandatory sections prevent half-finished solutions.
- **AI-readable** -- Agents can parse, match, and apply shares programmatically.

## Next steps

- [Create your first share](./creating-shares)
- [See the full format spec](./share-format)