Doc only, Sage's sage/row218 89ba79d94 (three commits squashed). Webby APPROVE round 1 (webby-0075,
rev 2848), round 2 (webby-0077, rev 2856) and round 3 (webby-0078, rev 2860). docs/case2/SETUP-SHEET.md
tells Melanie what the agents read, the playground, link and property forms, and what changes for
Bean and Chet, with M5's 1,200 character reply total (mos-1165). It goes to her only after C2-06
lands and on Jason's go (#419). docs/case2/SURVEY-RUN.md is design 10 step 7's run sheet: the
bare mirror as the source, a node check, output lines and refusals from survey.mjs. Claim sources
and rulings are in agents/sage/work/queue-218/BUILD.md. No test reads either doc path.
5.2 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
.canvasand.basefiles, 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. Each playground folder sits
inside one book folder, so one per book works well, for example <book>/playground/. 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.
- Open the graph view and open its settings panel.
- Under Groups, choose New group.
- 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>". - 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.
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 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.