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

# Documentation

> Teach agents what your schema doesn't say.

A read-only gateway decides what an agent *may* read. Documentation decides whether what
it reads means anything.

Column names don't tell an agent that `status = 3` means refunded, that `orders.total`
excludes tax, that rows are soft-deleted so every query needs `deleted_at IS NULL`, or that
`users` was superseded by `accounts` in a migration nobody finished. Without that, an agent
writes confident, wrong SQL — and the first bad number costs more trust than a dozen right
ones earn, because now there's no way to tell which earlier answers were also wrong.

## How documentation gets written

<Steps>
  <Step title="Profile">
    TeamDuo reads the schema and profiles the actual data: value distributions on
    low-cardinality columns, null rates, min and max on dates, distinct counts, orphan rates
    across declared foreign keys.

    This is where the value is. "`status`: integer, nullable" helps nobody. "`status` is one
    of `pending | paid | refunded | disputed`, and 94% of rows are `paid`" changes what an
    agent writes.
  </Step>

  <Step title="Generate">
    An agent drafts documentation per table from the schema and the profile.
  </Step>

  <Step title="Review">
    Drafts land as **drafts**. A human reads them and accepts the ones that are right.
    Nothing reaches a querying agent on the strength of having been generated.
  </Step>

  <Step title="Publish">
    Published documentation is served to every agent querying that database, through
    `describe_datasource` and `search_docs`.
  </Step>
</Steps>

## Agents can write documentation too

An agent that just worked something out the hard way is the best possible author — that
knowledge was learned in use rather than guessed from names. It's also the one kind of
documentation nothing can automatically check, which is why it lands as a draft.

| Tool                    | What it does                                              | Scope          |
| ----------------------- | --------------------------------------------------------- | -------------- |
| `document_finding`      | Record one thing learned about a table. Saved for review. | `docs:write`   |
| `write_documentation`   | Replace a table's `summary` or `examples` section.        | `docs:write`   |
| `publish_documentation` | Publish or withdraw a table's documentation.              | `docs:publish` |

A section rewritten with `write_documentation` is **pinned**: regenerating the
documentation leaves it alone. Correcting something by hand is not work you should have to
do twice.

<Warning>
  `publish_documentation` is not reversible in the sense that matters. Other agents will
  act on what you publish. Withdrawing it later doesn't retract the queries written in the
  meantime — publish only what you're confident is true of this database.
</Warning>

## Writing documentation that helps

Say what the schema cannot:

> `subscriptions.status` — one of `trialing`, `active`, `past_due`, `canceled`.
> `past_due` rows still count as active revenue until day 30.

Not what it already says:

> `subscriptions.status` — a string column on the subscriptions table.

The second is a restatement of `describe_datasource`. The first is the reason an agent
gets the number right.