# Usage: what Ontology does
Ontology converts a collection of documents and original attachments into one
queryable executable. Think of a dataset as an immutable snapshot with citations,
search indexes and an agent interface. The ontology CLI creates the snapshot;
ontology-docs is an example executable that explores its own embedded dataset.
## Concrete usage
Install latest tools with `cargo install ontology` and `cargo install ontology-docs`.
Run ontology-docs with no arguments for discovery, then `search usage`, `list`,
`read usage`, `images`, `skills list` or `mcp-config`. Follow returned next argv arrays.
Human usage adds --human. A bare search command teaches its arguments/examples.
Author a dataset with `ontology build ./documents --name handbook --output handbook`.
The resulting handbook executable can search/read/serve without Cargo, Python,
Node or network services. The authoring tool needs Cargo and the source normally
retained in its registry cache. `pack` creates an intermediate .ontology file;
`bundle` compiles such an intermediate. Use --encrypt for at-rest data protection.
Search is lexical BM25 plus optional vector ranking. Prefixes such as competit or
onto expand deterministically against known vocabulary; this is not a learned
semantic encoder. Empty results suggest actual vocabulary and document browsing.
Imported learned vectors require matching model/query coordinates.
## Competition and design
Read [competition](competition) to compare Kiwix, llamafile, Datasette and other
alternatives. See [format](format), [agents](agents) and [overview](overview) for
container details, skills, citations and integrations. There is no universal binary,
OCR engine, crawler or bundled diffusion model. Explicit images/assets remain bytes.
## Objects, relationships and nested packages
An object is a typed item: document, chunk, image, original binary asset, skill,
skill resource, embedding row, link, nested package or unresolved reference. The
catalog gives each a namespaced id, local_id, path, content URL and package_path.
Legacy read/image commands use local_id; object/content use the namespaced id.
A path is an API path, not a server filesystem path. Original document formats are
normalized to text; images and explicit generic assets retain their original bytes.
Run `objects`, `object document:usage`, `graph`, `links`, `assets`, `embeddings`
or `packages`. Inspect [the sample attachment](ontology-asset:sample-bytes) and
[the nested package](ontology-asset:nested-example). `open nested-example` returns
its scope; `list --package-path nested-example` explores that child. Parent and
child can both have a usage document without sharing identities or permissions.
Encrypted children require their own password; the root password is never inherited.
A references edge records anchor, local context and Unicode span. Its weight means
importance of target to source, not probability. The deterministic formula combines
context-to-target affinity (55%), source-to-target affinity (20%), anchor/title token
Jaccard (15%) and logarithmic mention prominence (10%). Default vectors make this a
lexical proxy. Imported learned chunk vectors enable semantic pooling in their
single model space. Missing usable evidence receives 0.5. Structural contains edges
are separately labelled. Explicit finite weights retain author/model/revision provenance.
Run `server --port 0` to open the dashboard and [HTTP API](http). It uses the same
read-only operations as CLI and MCP. No attached executable or skill resource runs.
