# Plan: LOOKUP verb (topic/importance catalog)

Status: draft, pending Fritz review (opened 2026-05-30). SPEC §6.7 drafted 2026-05-30 (the spec part of Slice 5 is done; soul + guidelines updates and the code slices remain). Slice 1 implemented on branch `feat/lookup-verb` (PR #166). Tracks [issue #113](https://github.com/latebit-io/demarkus/issues/113) (filed as "SEARCH"; the verb is named `LOOKUP` — see Naming).

(Supersedes the earlier `/plans/search-verb.md`, which is archived. That doc's history holds the full-text TF-IDF design we descoped.)

## What it is

`LOOKUP` is the **card catalog** for a demarkus world. Given a subject, it returns which documents are about it and how important they are, so the agent can go FETCH the right one without fetching and parsing the whole index hub and guessing. It is a token-efficient **supplement to the index**, not a search engine.

This fits the project's core metaphor exactly. The architecture's first principle is "the agent as the librarian"; LOOKUP is the catalog the librarian consults — look up a subject, get pointed at the shelf, FETCH the book. It is deliberately dumb: match a subject against author-declared catalog fields, order by importance. No relevance modeling, no body reading.

## Naming

Named `LOOKUP`, not `SEARCH`, on purpose. "Search" sets a full-text, relevance-engine expectation this does not meet, and its worst failure (an obvious body match that wasn't tagged returns nothing) reads as broken. "Look up" carries the catalog contract honestly: a catalog only knows what was filed in it, so a miss on an uncatalogued subject is expected behavior, not a bug. LOOKUP also keeps the verb cadence of FETCH / LIST / VERSIONS / PUBLISH / ARCHIVE / APPEND.

**Settled consequence:** full-text / semantic matching never enters core. It lives permanently in an opt-in **sidecar** (separate binary that reads demarkus over LIST/FETCH and builds its own index). A LOOKUP that did full-text would read wrong, and adding a separate SEARCH verb later would break "the verb set is final." Choosing LOOKUP closes that door on purpose. This finalizes the core verb set at 7.

## Topics

The verb, its implementation, and the delivery trail, each in one fetch:

- [The LOOKUP verb design](/plans/lookup-verb/design.md): the verb, declared metadata, ranking by importance, catalog design, read-auth filtering
- [Implementation](/plans/lookup-verb/implementation.md): module touch points, phasing, the sidecar decision for full text, risks, implementation status
- [Delivery](/plans/lookup-verb/delivery.md): slice 6 publish-side metadata, the merge, and the shipped status