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:

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

One link per line works too:

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:

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.