stack/docs/case2/SETUP-SHEET.md

# Your books in Mosaic: a setup sheet

This sheet is for you, Melanie. You keep writing in Obsidian the way you do now. Mosaic reads your
books repo after obsidian-git pushes it to git.mosaicstack.dev. Mosaic does not write directly to your
Obsidian vault. Each Console save and each note an agent writes becomes a commit in your repo. Your
computer gets those changes when obsidian-git pulls them.

## What the agents read

The agents read your books repo as you last pushed it. A push reaches them in about a minute.

They read notes, the `.md` files, inside your book folders. They don't read:
- notes at the top of the repo, outside any book folder
- `.canvas` and `.base` files, even inside a book folder
- images and other attachments
- anything in your other repos under `~/src`

They never write story or canon files. They may create, edit or delete `.md` notes only inside folders
you mark as `supporting`. A folder not marked `supporting` stays read-only to agents, including the
playground. A folder may be both `playground` and `supporting`.

Which folders are book folders, and which hold characters, places, research, your tracker or chapter
summaries, is set in one place. It is the `projects` entry of your business file in Mosaic. Jason
edits it by hand, and the agents can't change it. He will ask you to confirm it before the agents start.

## Your playground

A folder named in the `playground` list of that entry is your playground. A playground folder can sit
at one of three levels:
- Book level: inside one book folder, for ideas about that book, for example `<book>/playground/`.
- Universe level: outside every book folder, for ideas about a universe that aren't tied to one book.
- A new universe: a draft universe entry with a name and its own playground folders and no books, for a
  world you are only starting. When it is real, Jason turns it into a plain universe with books and you
  move the notes in Obsidian.

You choose the names and tell Jason. Until you mark a folder as `playground` or `supporting`, notes in
book folders are treated as canon.

What the playground means for the agents:
- They search canon unless they ask for the playground on purpose.
- They may cite a playground note. The Console shows that it is playground, not canon.
- Only the folder decides. A tag or a property can't make a note playground or canon. A playground
  folder is writable only when it is also marked `supporting`.

### Colour the playground in your graph

This is a setting of your own vault. It changes nothing for the agents.

1. Open the graph view and open its settings panel.
2. Under Groups, choose New group.
3. In the query box, type the playground's path with `path:`. Your vault is `~/src`, so the path
   starts with your books repo folder: `path:"<books repo folder>/<book>/<playground folder>"`.
4. Pick a colour.

Add one group per playground folder.

## Supporting folders

A folder you mark as `supporting` is where agents may write `.md` notes. They cannot write anywhere
else. A folder you have not marked is story, and agents leave it alone. A folder can be both
`playground` and `supporting`; then agents can search it when asked and can write supporting notes
there.

Tell Jason which folders you want to mark. He adds them to the `supporting` list in the `projects`
entry of your business file. He edits that entry by hand, and you can ask him to add or change a folder
later.

## Making a crossover (hybrid) universe

A crossover is its own universe, called a hybrid. It reads the canon of the universes it draws on, its
sources, and has its own books. Agents only cross worlds inside one. Like the rest of the `projects`
entry, Jason adds it by hand and the agents can't change it. Tell him what you want, and he writes an
entry with these keys:
- `kind`: `"hybrid"`.
- `name`: the name you call it by.
- `sources`: two or more universes it reads.
- `books`: its own book folders. It may start with none.
- `playground` and `supporting`: its own folders, the same as for any universe.
- `constraints`: the rules below, if you want any.
- `notes`: text on how the worlds fit together, up to 4000 characters. The continuity agent reads the
  notes and cites them.

A hybrid never reads a source's playground.

There are two kinds of constraint:
- `exclude` hides part of a source. It takes two forms. A source and a type folder, for example
  `second/Characters`, hides that type folder in each of that source's books. A path, for example
  `Book One/Research`, hides that folder or note, which must sit in a book of one of the sources. Agents
  in the hybrid don't see what is hidden, can't cite it beside a hybrid note, and a hybrid note that links
  to it gets a link warning.
- `pin` holds one fact fixed: a source note (`entity`, a `.md` path), a property (`field`) and its value
  (`value`). If the note goes missing or the property changes, Mosaic warns. It also warns when a hybrid
  note of the same type and name sets that property to something else. Linking to the note doesn't count:
  a hybrid character who links `[[Mara]]` is someone else.

Mosaic refuses an entry whose `exclude` or `pin` points outside the sources' books, or into a source's
playground.

## Saves and agent notes

When you save a file in the Console, Mosaic makes a commit under the name and email you give Jason for
`editor` in your `projects` entry. If that file moved after you opened it, Mosaic refuses the save and
keeps your text so you can copy it or try again.

Each time an agent creates, edits or deletes a supporting note, Mosaic makes a commit under that
agent's own name and shows you a notice in the Console with a Revert button. Mosaic's own notices do
not need a citation. Obsidian sees the change on its next pull. Supporting notes may contain any text.
You can read and revert every one.

## Two things you might not expect

### Moving a note can change how agents use it

The folder decides, so a move changes what the agents may do with a note. Once you move a note out of
the playground into a book folder and push, agents may treat it as canon unless it is inside a folder
you marked `supporting`. A note that isn't settled yet belongs in the playground. Any folder you mark
`supporting` stays a supporting folder even when it is inside a book folder.

### A short link can point somewhere else for the agents

Obsidian looks up a short link like `[[Mara]]` across your whole vault, `~/src`. The agents see only
your books repo. Say a note called `Mara` exists in your books repo and also in another of your repos.
Obsidian and the agents can then open different notes for the same link, and the agents can't tell.
If the name exists only in the other repo, the link leads nowhere for the agents.

A link with the full path from the top of your vault reaches the same note in both:

```
[[<books repo folder>/<book>/<characters folder>/Mara]]
```

Obsidian can write new links this way. In Settings, open Files and links and set New link format to
Absolute path in vault.

## Lists of links in properties

The agents read the links in two properties, `appears_in` and `relationships`. Put quotes around each
link in the list:

```yaml
appears_in: ["[[A]]", "[[B]]"]
```

One link per line works too:

```yaml
appears_in:
  - "[[A]]"
  - "[[B]]"
```

Obsidian's property editor adds the quotes for you. If you type the list by hand, don't leave them out:

```yaml
appears_in: [[[A]], [[B]]]
```

The agents' reader can't read that form. It then ignores every property of that note and lists the
note as a problem in Mosaic's status. It still finds the note by its path, its name and its text. A
value written without `[[ ]]` counts as a plain name, not a link.

## What changes for Bean and Chet

They keep their names and personalities. How they answer changes.

In Mosaic they can answer in free text, not a short list of items. There is no word-count or item-count
limit. They may cite your files, and the Console shows where each citation points. Citations are
optional by default. You or Jason can change these settings:

| Setting | Default | What it does |
|---|---:|---|
| `requireCitation` | `false` | When true, each answer needs a citation. Mosaic's own notices do not. |
| `citationsPerReply` | `20` | Maximum citations in one answer. |

File citations in one answer must stay within one universe.

They can give free-text answers that cite your books. Their repository writes are limited to `.md`
notes in folders you marked `supporting`.

You talk to them in the Console. Hermes keeps running until you have moved over, and stopping it is
your choice.

Five more helpers can join them: ideas, research, proofreader, fact-checker and continuity. You
choose which ones to start with, and you can add one later.

## What Jason will ask you

He will ask you to confirm your book folders, which books share a world, your playground and supporting
folders, the name and email for `editor`, and which helpers to start with and when.