# Black Bean Docs — Getting started

## 1. Prerequisites

1. Activate **Black Bean Tables**
2. Run the Tables seeder so `docs` and `doc_categories` are registered
3. **Tables → Structure → Sync** for both tables (or enable sync-after-seeder)
4. Activate **Black Bean Docs**
5. Open **Docs → Getting started** and clear remaining checklist items
6. Flush permalinks if `/docs/` 404s

## 2. Create a doc manually

1. **Docs → All docs → Add doc** (or Edit doc screen)
2. Title + status (`publish` / `draft`)
3. Assign categories
4. Upload a `.md` file (or paste in preview, then upload)
5. Save → view on `/docs/{slug}/`

## 3. Sync from plugin folders (recommended)

Keep source of truth in each plugin’s repo:

```
wp-content/plugins/teddy/docs/*.md
wp-content/plugins/teddy/CHANGELOG.md
wp-content/plugins/blackbean-tables/docs/*.md
…
```

Then:

1. Open **Docs → Sync**
2. Review discovered files and section mapping
3. Choose a plugin (or All) → **Sync now**
4. Or CLI:

```bash
docker compose exec wpcli wp bb-docs sync
docker compose exec wpcli wp bb-docs sync --plugin=teddy --dry-run
```

Categories are created automatically:

```
Teddy
├── Guides
├── Features
├── Release notes
├── Reference
└── Internal
```

## 4. Mapping rules (summary)

| File pattern | Section |
|--------------|---------|
| `FEATURES.md`, root `README.md` | Features |
| `GETTING-STARTED`, `*-guide*`, `PRODUCT.md` | Guides |
| `CHANGELOG.md`, `*RELEASE*` | Release notes |
| `modules/**`, deep reference READMEs | Reference |
| `*-prompt*`, ADR, architecture | Internal (draft) |

Override with filters: `bb_docs_sync_resolve_section`, `bb_docs_sync_plugin_slugs`.

## 5. Front-end check

- `/docs/` lists published docs
- Category chips filter by taxonomy
- Sitemap: `/bb-docs-sitemap.xml`

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| Sync: “categories table missing” | Sync `doc_categories` in Tables → Structure |
| Sync creates 0 categories | Same as above; re-run sync after DDL |
| 404 on `/docs/` | Flush permalinks |
| Ugly markdown | Optional CommonMark: `composer install` in docs plugin |
| Doc not public | Status is `draft` (Internal section defaults to draft) |