# Topics, the categories of a house

A topic is how an owner sorts what comes in: "Bridge renovation", "Money", "Travel". In a
house a topic is an individual under an aspect named `Thema` (German for topic). Its
description, in a slot named `Umschreibung` (German for paraphrase), is the whole material
by which anyone decides what belongs to it. A document belongs to a topic through an edge of
the form `About`, which carries one sentence of reasoning.

A fresh house has neither the aspect nor the form. Check with `overview` (aspects) and
`list_forms` (a form titled About). If they are missing, coin them once.

## Coin the vocabulary, with these exact words

Use the modeller door. An aspect is its description: the same words are the same aspect in
every house, and other words are a different aspect that merely shares the name. Guided
assignment (planned, see `the-list-of-open-work`) looks for exactly this aspect and this
form. So copy both definitions as they stand, including the German slot name.

Call `define_aspect` with this YAML:

```yaml
Name: Thema

Description: >
  A Thema is a lasting concern of the person this memory belongs to: one of the worlds he
  lives in, and one that a find can belong to.


  Conventions of this aspect:

  - The Umschreibung slot carries the whole judgement material: what belongs here and what
  does not, in the owner's own words. Sharpening it is a new fassung, never an overwrite —
  and it is the intended way to steer assignment, in place of any rule in code.

  - Names are labels, never keys. Topics may overlap, and a find belongs to as many as fit.

  - Topics are coined by the owner alone. No agent invents one: a find that fits none stays
  unassigned, and that is a signal about the topic list, not about the find.

  - Assignment is an About edge from the content to the topic, carrying one sentence of
  reasoning. It is asserted generously and without conjecture — too many is one retract,
  too few is invisible.

  - What stands here is content, not vocabulary: a Thema is an individual of this corpus,
  never a concept of the model. The concept DAG describes the system; a Thema describes a
  life.

Properties:
- Name: Umschreibung
  Kind: Versioned
  Description: >
    What belongs to this topic and what does not, in the owner's own words. This text is
    the whole material an assigning agent judges by; sharpening it is a new fassung, and
    it makes every stamped document fall due again.
```

Call `define_form` with the title `About` and this YAML:

```yaml
Description: >
  An About states that the content (From) belongs to a topic (To): the assignment of a find
  to one of the owner's lasting concerns. It carries the one sentence that explains the
  assignment. The edge is an ordinary assertion — retract takes it back, and taking it back
  is the intended correction when an assignment misses.

Properties:
- Code: Reason
  Type: Storable
  Description: >
    One sentence naming what in the content makes it belong to this topic. It is shown to
    the owner as the explanation of the assignment; a reason that only repeats the topic's
    name explains nothing.
```

Both calls are idempotent: the answer says `is_new: false` when the definition already
stands. Keep the concept ID of the aspect and the ID of the form from the answers.

## Add a topic

Topics are the owner's. Ask your human which topics there are and what belongs to each; do
not invent them from the documents. The author door is enough from here on.

```
create_individual {"aspect_id": "<Thema concept ID>", "name": "Money"}
set_property {"thing_id": "<topic ID>", "path": ["Umschreibung"],
              "value": "Budgets, quotes, prices and invoices of any kind: what something costs.",
              "context_id": "<Thema concept ID>", "versioned": true}
```

`create_individual` never searches: calling it twice makes two topics of the same name.
List the existing ones first with `list_collection` on the collection that `overview`
reports for the aspect. To sharpen a description, call `set_property` again with the new
text; the old one stays readable through `get_history`.

## Assign, read, correct

```
assert_formed_link {"form_id": "<About ID>", "from_id": "<document ID>", "to_id": "<topic ID>",
                    "values": {"Reason": "Quarterly budget note with the cost of the bearings."}}
get_links {"id": "<topic ID>", "direction": "in", "form_id": "<About ID>"}
get_links {"id": "<document ID>", "direction": "out", "form_id": "<About ID>"}
retract {"link_id": "<link ID from get_links>"}
```

The first call assigns, the second lists everything that belongs to a topic, the third the
topics of one document, the fourth takes an assignment back. Asserting the same assignment
again changes nothing. For assigning many documents with the prompt of the house, use
`recipe-assign-topics`.

## Go deeper

- [recipe-assign-topics](recipe-assign-topics.md)
- [forms-aspects-concepts](forms-aspects-concepts.md)
- [working-by-recipe](working-by-recipe.md)
- [a-memory-you-can-shape](a-memory-you-can-shape.md)