feat: INSTALL.md is the English installation tutorial; new tutorial docs/tutorials/first-source-to-first-answer.md with a shipped sample source; README.md links it as its first-ingestion step (#191)
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
This commit is contained in:
torbenandClaude Opus 5.5 committed
1 parent
f9056c04f7
commit
fe1de63e0f
13 files changed
+403
-190
No files matched your search
@@ -4,5 +4,10 @@ Learning-oriented pages: a guided first walk through an instance, start to finis
|
||||
who has not used one before. A tutorial shows one path that works; it does not list options or
|
||||
explain why.
|
||||
|
||||
Nothing is here yet. The installation tutorial is still [INSTALL.md](../../INSTALL.md) at the
|
||||
repository root, which stays there; a walk from the first source to the first answer is planned.
|
||||
Take them in this order:
|
||||
|
||||
1. [Install a Chemenu instance](../../INSTALL.md) - from an empty folder to a running instance.
|
||||
It stays at the repository root, where someone who has nothing else yet finds it first.
|
||||
2. [From your first source to your first answer](first-source-to-first-answer.md) - ingest a
|
||||
sample document, look at the pages it became, and ask the wiki a question about it.
|
||||
[sample-source.md](sample-source.md) is the document it uses.
|
||||
@@ -0,0 +1,157 @@
|
||||
# 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
|
||||
@@ -0,0 +1,48 @@
|
||||
# Home lab backups - how they work now
|
||||
|
||||
Notes written after reworking the backups in September 2026. This file is the sample source for
|
||||
the tutorial "From your first source to your first answer"; the machine and its setup are made
|
||||
up for it.
|
||||
|
||||
## The machine
|
||||
|
||||
**Atlas** is the small file server in the hall cupboard: a fanless mini PC with two 4 TB disks
|
||||
in a mirror, running Debian 13. It holds the family photo archive, scanned documents and the
|
||||
configuration of every other machine in the house. Everything else on the network is replaceable;
|
||||
what is on Atlas is not.
|
||||
|
||||
## The tool
|
||||
|
||||
Backups are made with **restic**, an open-source backup program. restic splits files into chunks,
|
||||
stores each chunk only once and encrypts everything before it leaves the machine, so the backup
|
||||
target never sees a file name or a byte of content in the clear. A restic *repository* is the
|
||||
storage location it writes to; a *snapshot* is one backup run.
|
||||
|
||||
restic was chosen over plain `rsync` for two reasons: deduplication keeps the daily runs small,
|
||||
and encryption makes it safe to put a copy on storage someone else operates.
|
||||
|
||||
## How it is set up
|
||||
|
||||
Atlas runs restic every night at 02:30 from a systemd timer. Each run writes one snapshot to two
|
||||
repositories:
|
||||
|
||||
- a USB disk that stays plugged into Atlas, for fast restores;
|
||||
- a rented storage box at a hosting provider, reached over SFTP, as the copy outside the house.
|
||||
|
||||
Snapshots are thinned out by `restic forget` after each run: the last 7 daily, 5 weekly and
|
||||
12 monthly snapshots are kept.
|
||||
|
||||
## Why two targets
|
||||
|
||||
The setup follows the **3-2-1 backup rule**: keep three copies of the data, on two different
|
||||
kinds of storage, with one copy off site. Here the three copies are the mirror on Atlas itself,
|
||||
the USB disk, and the storage box. A fire or a burglary takes the first two; the storage box is
|
||||
what is left.
|
||||
|
||||
The mirror alone does not count as a backup. It protects against a dead disk, but a deleted or
|
||||
encrypted file is deleted or encrypted on both disks at once.
|
||||
|
||||
## What is still open
|
||||
|
||||
The restore has been tried once, for a single folder, from the USB disk. It worked and took
|
||||
under a minute. A full restore from the storage box has not been tried.
|
||||
Reference in new issue
Block a user