torbenandClaude Opus 5.5
fe1de63e0f
Files changed: - CHANGES.md - INSTALL.md - README.md - VERSION - docs/reference/commands/types-instructions-and-docs.md - docs/tutorials/README.md - docs/tutorials/first-source-to-first-answer.md - docs/tutorials/sample-source.md - instructions/dev/doc-pull-through.md - tools/CONTRACT.md - tools/chemenu/commands/docs_verify.py - tools/chemenu/install_doc.py - tools/chemenu/tests/test_install_doc.py Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
158 lines
6.7 KiB
Markdown
158 lines
6.7 KiB
Markdown
# 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](../../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.
|
|
|
|
<!-- wikitool:toc -->
|
|
## Contents
|
|
|
|
- [1. Put the sample source into `incoming/`](#1-put-the-sample-source-into-incoming)
|
|
- [2. Ask the agent to ingest it](#2-ask-the-agent-to-ingest-it)
|
|
- [3. Tell the agent what matters](#3-tell-the-agent-what-matters)
|
|
- [4. Answer the two capture questions](#4-answer-the-two-capture-questions)
|
|
- [5. Let the agent publish](#5-let-the-agent-publish)
|
|
- [6. Look at what it wrote](#6-look-at-what-it-wrote)
|
|
- [7. Ask a question](#7-ask-a-question)
|
|
- [8. Optional: browse it in Obsidian](#8-optional-browse-it-in-obsidian)
|
|
- [What next](#what-next)
|
|
<!-- /wikitool:toc -->
|
|
|
|
## 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:
|
|
|
|
```bash
|
|
cp docs/tutorials/sample-source.md incoming/home-lab-backups.md
|
|
```
|
|
|
|
On Windows in PowerShell 7:
|
|
|
|
```powershell
|
|
Copy-Item docs/tutorials/sample-source.md incoming/home-lab-backups.md
|
|
```
|
|
|
|
Open [the sample](sample-source.md) 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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`.
|
|
|
|
```text
|
|
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](../../raw/CONTRACT.md#capture-fields-fidelity-and-authority)
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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](https://obsidian.md). 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](../how-to/browse-with-obsidian.md) 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](../how-to/ingest-a-source.md) - your own files, folders and web pages
|
|
- [Query the wiki](../how-to/query-the-wiki.md) - and search it yourself
|
|
- [Maintain the wiki](../how-to/maintain-the-wiki.md) - the lint the agent suggests every ten
|
|
sources
|