# How it works

> Documentation index: [llms.min.txt](https://caseyrfsmith.github.io/scull/llms.min.txt) · Document manifest: [documents.json](https://caseyrfsmith.github.io/scull/documents.json)

Scull separates documentation preparation from lookup.

**How it works**

Specs and prose become reviewed schemas; schemas support exact lookup or an optional search index.

[View How it works diagram](https://caseyrfsmith.github.io/scull/assets/diagrams/mermaid-a8fa9cb524bb9ea37204-light.svg)

```mermaid
flowchart TD
    A[Markdown] --> C[Extract candidates]
    B[Structured specs] --> C
    V[Vocabulary] --> C
    C --> D[Reconcile and review]
    D --> E[Schema YAML]
    E --> F[Exact lookup]
    E --> G[Build index]
    G --> H[Semantic search]
```

## Build

A vocabulary names concepts, fields, and aliases. Parsers read structured specs; a configured LLM
drafts facts and caveats from prose. Deterministic reconciliation combines them into `.schema.yaml`.

Review the facts, quoted evidence, and field attachments. A correct warning attached to the wrong
field is still a bad artifact. Commit the reviewed output.

## Query

| Command                     | Reads                       | Model needed?                    |
| --------------------------- | --------------------------- | -------------------------------- |
| `get`, `context`, `caveats` | Local schemas               | No, with default output          |
| `search`                    | Compatible index            | Hosted or local query embeddings |
| `get --format=human`        | Schema plus rendering model | Yes                              |

`context` returns requested fields with attached and concept-wide caveats. Search discovers fields
when their names are unknown. Scull returns reference material; a host agent generates the answer.

## Update

Source hashes track input changes. Schema hashes track compiled content. Rebuild and review when
sources change; rebuild the index when its inputs or embedding configuration change. Distribute
matching schemas and indexes together.

Deterministic lookup does not establish factual correctness or completeness. Keep original docs
available for context outside the compiled artifact.

See [build a schemaset](https://caseyrfsmith.github.io/scull/docs/procedure/adding-a-concept.md), [review](https://caseyrfsmith.github.io/scull/docs/procedure/procedure-review.md), and
[index format](https://caseyrfsmith.github.io/scull/docs/reference/kg-builder.md).