chemenu/docs/tutorials/first-source-to-first-answer.md

From your first source to your first answer

In this tutorial you put one document into a fresh instance, let the agent turn it into wiki pages, look at what it wrote, and then ask the wiki a question and follow the answer back to the document. It takes about a quarter of an hour. You need nothing but the instance and your harness: the document is a sample that ships with the instance.

You start from an instance that INSTALL.md has just set up, with the agent session restarted afterwards so that it has loaded its skills. Ask the agent Which skills do you have? if you are unsure - wiki-ingest and wiki-query should be among them.

Contents

• 1. Put the sample source into incoming/
• 2. Ask the agent to ingest it
• 3. Tell the agent what matters
• 4. Answer the two capture questions
• 5. Let the agent publish
• 6. Look at what it wrote
• 7. Ask a question
• 8. Optional: browse it in Obsidian
• What next

1. Put the sample source into incoming/

incoming/ is where everything you want in the wiki waits until it is ingested. Copy the sample there - copy, not move, so the tutorial page keeps its sample:

cp docs/tutorials/sample-source.md incoming/home-lab-backups.md

On Windows in PowerShell 7:

Copy-Item docs/tutorials/sample-source.md incoming/home-lab-backups.md

Open the sample and read it once. It is a page of notes about the backups of a small home file server called Atlas: which tool makes them (restic), where they go, and why there are two targets (the 3-2-1 backup rule). Knowing what it says will let you check the agent's work.

2. Ask the agent to ingest it

In the agent session, say:

Ingest

A bare Ingest takes the oldest entry waiting in incoming/ - here, the only one. The agent reads the whole file before it writes anything.

3. Tell the agent what matters

The agent comes back with the key takeaways of the document and a few questions: which points matter most, which things should get a page of their own, and whether the document carries something you have to do. Answer in your own words, for example:

Atlas, restic and the 3-2-1 rule are what matter. Nothing to do from this one.

The pages it writes next follow your answer, so this is the moment to steer. The agent may well notice that the notes leave something untested and offer to track it as a task; "nothing to do" declines that.

Often the same message already asks the two questions of the next step. Then answer them in the same reply.

4. Answer the two capture questions

Before the file leaves incoming/, the agent asks two things about the capture itself:

• fidelity - how faithful is this file to the original? The sample is the notes exactly as written, so the answer is verbatim.
• authority - what may the material claim about its subject? The notes describe how a setup works; they do not set a standard anyone else has to follow. The answer is reporting.

verbatim, reporting

The agent never guesses these two. Only you know them, and only now: once the file is in the wiki, nobody can tell any more where it came from. raw/CONTRACT.md lists every value, for the sources you add later.

5. Let the agent publish

The agent now moves the file into raw/, writes the pages, and publishes everything as one commit. For a source this small that goes straight through; the agent tells you what it committed. If your instance has no remote, the commit stays on your machine.

A larger source - ten or more new or changed pages and files, not counting the generated indexes and log - stops at the Mass-Update Gate instead: you see the list of files and a line ending in --confirm <token>, and nothing is committed until you tell the agent to go ahead.

6. Look at what it wrote

Ask the agent where the pages are, or look yourself. You will find:

• The file itself under raw/, in a folder for the current year and month. It is never edited again.
• A source page under kb/sources/, summarising the notes. Its frontmatter carries your two answers, fidelity: verbatim and authority: reporting, and raw_files: points at the file in raw/.
• Entity and concept pages for what you said matters - Atlas, restic, the 3-2-1 backup rule, in the language and naming your instance chose at setup. Each one links back to the source page, and each claim taken from the notes carries a footnote citing it.
• A new entry at the end of kb/log.md, recording the ingest.

The exact set of pages depends on your answer in step 3, and on the agent: two runs of this tutorial do not produce word-for-word the same wiki. What is always the same is that every page is tied back to the file in raw/.

7. Ask a question

Start a new agent session, so that the answer can only come from the wiki and not from what the agent remembers of the ingest, and ask:

How are the backups of Atlas protected against a fire in the house?

The answer names the storage box outside the house as the copy that survives, and the 3-2-1 rule as the reason it exists. It cites the pages it came from and the source behind them. Open one of the cited pages and follow its footnote: it leads to the source page, and that one to the file in raw/ - the notes you copied in step 1.

Now ask something the notes do not answer:

How long does a full restore of Atlas take?

The notes say only that one has never been tried. The agent tells you that the wiki has no source for this, rather than estimating one. That is the rule behind every answer: no claim without a source.

8. Optional: browse it in Obsidian

Open the instance's root folder as a vault in Obsidian. The graph view shows the pages you just made and the links between them. Read there as much as you like, but change pages through the agent: Browse the wiki in Obsidian explains why.

What next

You have taken one source all the way from a file to a cited answer. From here on, the how-to guides cover the everyday tasks:

• Ingest a source - your own files, folders and web pages
• Query the wiki - and search it yourself
• Maintain the wiki - the lint the agent suggests every ten sources