Files
stack/docs/case2/SETUP-SHEET.md
T
jason.woltje c27207f6e6 row 268 (C2-01c, #1773, Vikunja 464): playgrounds at three levels; classify checks prefixes first
checkMapping takes kind absent, hybrid or draft. A draft has a name and one
or more prefixes and no books, and comes back with books []. A prefix inside
or holding another entry's book refuses library-playground-other-universe,
which replaces library-playground-outside-book. A prefix equal to a book or
holding its own refuses library-mapping-invalid, as does a draft source.
classify returns a playground file's entry and the book holding its prefix,
or null at universe level and in a draft.
2026-10-22 00:04:42 -05:00

5.6 KiB

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. It changes nothing on your machine and commits nothing to your repo.

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 can't write to your repo at all. That covers canon, the playground and everything else.

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 have one, every note in a book folder is canon.

What the playground means for the agents:

  • They search canon unless they ask for the playground on purpose.
  • An agent may quote a playground note in an idea or a question. It may not use one to back a fact, a finding or a correction. Mosaic refuses that reply before you see it.
  • Only the folder decides. A tag or a property can't make a note playground or canon.

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.

Two things you might not expect

Moving a note into a book folder makes it canon

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, it is canon. The agents may then cite it as fact. A note that isn't settled yet belongs in the playground. Any note in a book folder outside the playground is canon, rough drafts included.

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.

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 Hermes they answer in free text and may write story text when you ask. In Mosaic every reply is a short list of items. Each item is an idea, a question, a finding or a fact. Each one quotes a line from your repo or from a web page the agent read for you.

They don't write passages. If you ask for prose, you get a question or an idea instead.

A reply holds at most 10 items and at most 1,200 characters of item text in all. It has at most 5 ideas of up to 200 characters each. A question, finding or fact runs up to 300 characters. You or Jason can ask for lower limits. When an agent can't back an answer with a quote, you see "No cited answer" instead.

Each book world stays separate. One item can't mix quotes from two worlds.

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 and type folders, which books share a world, the name of each playground folder, and which helpers to start with and when.