# Model notes, sources and connections

## Purpose

This is a starting content model for a searchable thinking garden. It can be implemented as Markdown, a table or a database. The point is to preserve distinctions that will matter when someone returns to an item, without making every capture feel like a tax return.

## Record types

**Source:** External material, including a paper, report, article, book, podcast or site. A Source record identifies the material and can contain a reading note. It does not by itself certify that the material has been read or verified.

**Note or Pebble:** A self-contained thought, question, observation, hypothesis or distinction. It can be linked to a Source without claiming that the Source made the same point.

**Connection:** An explicit relation between records. At minimum, store both record IDs and, where useful, a short note explaining why they are linked.

**Review item:** An entry needing classification, provenance or factual correction. This can be a status on a record rather than a separate type.

## Minimum useful fields

For a note:

```yaml
technical_id: immutable internal identifier
display_id: optional stable human reference
kind: note
title: specific, recognisable title
text: self-contained account
status: draft | reviewed | public | archived
topics: []
labels: []
origin: conversation, observation or source context
source_ids: []
related_item_ids: []
created_at: timestamp
updated_at: timestamp
```

For a source:

```yaml
technical_id: immutable internal identifier
kind: source
title: source title
authors: []
publication: optional
published: optional date
url_or_reference: stable locator if available
source_type: paper | report | article | book | podcast | other
reading_status: saved | skimmed | read | checked
note: what is useful and what remains uncertain
topics: []
labels: []
linked_note_ids: []
created_at: timestamp
```

You can omit fields in a small collection. Do not fabricate a publication date, author or reading status to make a schema look complete.

## Stable identifiers

An internal identifier should not change when a title changes. A short numerical display ID can help a person say “revise #037” or “merge #037 and #052”. It is an administrative handle. It need not appear in every browse list.

Never reuse retired display IDs. For a merge, keep a redirect or a small register showing where the retired item went. Sources may use the same technical identifier system without needing visible sequential numbers.

## Topics and labels

**Topics** are a limited number of broad routes for browsing. They may overlap. Usually one to three are enough for an item. Apply a topic because the central question belongs there, not because a word in the title matches.

**Labels** are more specific retrieval terms: concepts, methods, settings or people. Preserve useful detail, but expect spelling variants and near-duplicates. Periodically review labels before promoting any of them to top-level navigation.

If no topic fits, mark the item for review and keep it searchable. Do not invent a new global topic from one awkward record.

## Connections and provenance

Useful link types include “prompted by”, “supports”, “complicates”, “extends”, “contrasts with” and “related question”. If the software stores only a generic link, a brief relation note can carry the distinction.

Provenance should answer: Where did this thought come from? What part is reported evidence, and what part is interpretation? A link to a study does not make the whole note a study finding. Preserve qualifiers that matter to later use.

## Search and browse

Search titles, full note text, topics, labels and Source metadata. On a homepage, show actual item titles quickly. Put full metadata on individual pages. A recent list helps the owner return to new work, but should not overwhelm the main browse paths.

Test search with the words a person would remember, not only with exact titles. Test a topic page with five varied items. If it collects everything or nothing, adjust the topic definition.

## Minimal Markdown examples

```markdown
# A short, specific note title

ID: N-037
Status: Draft
Topics: Human–AI collaboration
Labels: review, decision consequences
Origin: Discussion of S-012; the design implication is my inference
Related: S-012, N-019

The self-contained thought goes here. It says what was observed, why the
distinction matters and what remains uncertain.
```

```markdown
# Source title

ID: S-012
Author: [name if known]
URL: [stable link]
Reading status: Skimmed
Linked notes: N-037

What I checked, what it contributes and what it does not establish.
```

The field names are examples, not a required ontology. A small reliable record beats an elaborate empty one.