---
name: ingest
description: Create or update a single OKF concept file from raw input. Use when the user wants to document a specific table, metric, API, service, or concept in the knowledge base — even if they say "add this to the okf", "documenta essa tabela", "cria um conceito pra isso", "adiciona no knowledge base", "register this API", or pastes a schema/description and says to save it. If no OKF files exist yet, suggest /mega-brain:init first.
---

# ingest — OKF Concept Writer

Turns raw input (schema dump, API doc, user description, table definition) into one OKF-formatted `.md` file committed to the knowledge base.

## Before writing

Look for existing OKF files: any `.md` with `type:` frontmatter, or `index.md` / `log.md` in the project. If none exist, stop and tell the user to run `/mega-brain:init` first.

If `.mega-brain.json` defines `dir`, save new concepts under that directory. Otherwise, choose a sensible location (`docs/`, project root, etc.) consistent with existing OKF files.

Check if a concept with the same name already exists. If so, ask whether to update it or create a new one.

## Output format

One `.md` file per concept. Only `type` is required:

```markdown
---
type: <concept type>
title: <display name>
description: <one sentence, plain language, no jargon>
resource: <URL to the actual resource, if any>
tags: [<tag1>, <tag2>]
timestamp: <ISO 8601 date>
---

<body: exact schema, formula, join patterns, examples, caveats>
```

## Common types

| Type | Use for |
|------|---------|
| `BigQuery Table` | BQ tables with schema |
| `BigQuery Dataset` | BQ datasets |
| `Table` | Non-BQ database tables |
| `Metric` | KPI or business metric with formula |
| `API` | REST/GraphQL endpoints |
| `Runbook` | Operational procedures |
| `Concept` | Business or domain terminology |
| `Service` | Internal microservices |
| `Pipeline` | ETL or data pipelines |

Types are freeform — add your own.

## Process

1. Read the source material
2. Identify the concept type and canonical name
3. Write `description`: one sentence, plain language
4. Add `resource` URL if there's a live resource (BQ console URL, API endpoint, dashboard)
5. Write the body with exact values — preserve field names, types, and formulas as-is; do not generalize
6. Link to related concepts with `[Name](relative-path.md)` — this builds the knowledge graph
7. Save next to related OKF files (e.g. `docs/tables/<slug>.md` or `<config-dir>/tables/<slug>.md`)
8. Add one line to `index.md`: `- [Title](path) — description`
9. Append to `log.md`: `<date> — added <title>`

## Updating an existing entry

- Update `timestamp`
- Preserve existing wikilinks unless explicitly removing them
- Keep `description` to one sentence — push additional detail into the body